fix(plugin): add timeout protection to getClient() in before_prompt_build hook

[Meskjei]

Problem

The before_prompt_build hook calls await getClient() without timeout protection. If the OpenViking client hasn't finished initializing when the hook is triggered, the agent will hang indefinitely waiting for the client Promise to resolve.

This happens because:

1. Plugin loads and registers the before_prompt_build hook
2. User sends a message before start() function completes OpenViking server startup
3. Hook triggers and calls await getClient()
4. getClient() waits for clientPromise to resolve
5. But clientPromise only resolves after start() finishes starting the OpenViking service
6. Deadlock: hook blocks agent → agent can't complete → start() can't finish

Solution

Wrap getClient() call with withTimeout() (5 seconds):

• If client initializes in time, proceed normally with memory recall
• If timeout, log warning and skip recall gracefully
• Agent continues without blocking

Testing

Tested locally with OpenClaw + OpenViking plugin:

• Before fix: Agent hangs on first message if OpenViking service not ready
• After fix: Agent responds normally, recall skipped gracefully if timeout

Related Issues

• Similar to [Bug]: memory-openviking plugin before_agent_start auto-recall hangs indefinitely, causing total silent agent failure #673 (which fixed auto-recall timeout but not the initial getClient() call in hook)
• Addresses [Bug]: examples/openclaw-plugin/index.ts missing withTimeout protection (same as #673) #748 (directory refactor bug where timeout fix wasn't synchronized to new plugin location)

[qin-ctx]

cc @Mijamind719

[qin-ptr]

Review Summary

This is a well-crafted bugfix that addresses a real timing issue: when a user sends a message before the OpenViking service completes initialization, the before_prompt_build hook would hang indefinitely waiting for the client Promise to resolve.

The solution correctly adds timeout protection (5 seconds) to the getClient() call at the hook layer. If the client isn't ready, the hook gracefully skips recall and allows the agent to respond normally.

Key strengths:

• ✅ Problem accurately identified: hook-layer infinite wait, not a deadlock
• ✅ Fix placed at the right layer (hook as consumer, not blocking other call sites)
• ✅ Minimal, surgical change with proper error handling
• ✅ No compatibility concerns

Minor suggestion (non-blocking):

• The 5-second timeout is hardcoded. While sufficient for most environments, consider making it configurable (e.g., clientInitTimeoutMs) for users with slower startup times. Not critical — the current behavior (skip first recall, subsequent messages work fine) is acceptable.

Approving for merge.

🤖 I am a bot owned by @qin-ctx.

[qin-ptr]

[Suggestion] (non-blocking)

The 5-second timeout is hardcoded. While this is reasonable for most environments, consider making it configurable (e.g., add a clientInitTimeoutMs config option with a default of 5000ms).

This would help users with slower environments (low-performance machines, large model loading) where service startup may take longer.

That said, the current behavior is acceptable: if timeout occurs, only the first auto-recall is skipped; subsequent messages work fine once the service is ready. Not a blocking issue.