💻 Change Type

• ✨ feat
• 🐛 fix
• ♻️ refactor
• 💄 style
• 👷 build
• ⚡️ perf
• ✅ test
• 📝 docs
• 🔨 chore

🔗 Related Issue

🔀 Description of Change

In server (queue) mode, a parent agent parked on callSubAgent never resumed after all sub-agents finished — the run just stopped after the tool calls completed.

Root cause: the sub-agent completion bridge (createSubAgentBridgeHook) was a handler-function-only hook. Handler hooks live in process memory; in queue mode (AGENT_RUNTIME_MODE=queue) HookDispatcher.dispatch only delivers hooks with a webhook config (getSerializedHooks filters on h.webhook), so the bridge never fired. tryResumeParentFromAsyncTool was never called and the parent op stayed in waiting_for_async_tool forever. Local mode (in-process dispatch) was unaffected, which is why the integration test passed.

Fix — webhook transport plus two race hardenings:

1. QStash webhook bridge: the hook now carries a webhook config (delivery: 'qstash', explicit because deliverWebhook defaults to plain fetch which the endpoint's QStash signature auth would reject) targeting the new /api/agent/webhooks/subagent-callback endpoint. The endpoint resolves the userId from the child operation's metadata (same trust chain as /run), reloads the child's final state from the coordinator, and runs the bridge. Local mode keeps the in-process handler. Both paths converge on the new AgentRuntimeService.completeSubAgentBridge (backfill parent's placeholder tool message → barrier-check → CAS → schedule resume). Non-2xx responses let QStash redeliver, covering transient DB/Redis failures.
2. Park-time self-check: sub-agents are dispatched mid-step, so a fast child could complete before the parent's parked state was persisted — its resume attempt no-oped against the status guard with nothing left to retry. After the parked state and agent_operations row are persisted, the parent now re-runs the resume barrier once to recover any resume that raced the park.
3. One-shot verify watchdog: when a completion finds the parent not yet resumable (scheduleVerifyOnHold), a delayed verifyAsyncToolBarrier re-check is scheduled (15s). It re-runs barrier + CAS without claiming the step lock, is idempotent, and never re-arms itself, so retries stay bounded at one per completion event. This covers transient failures around the last completion (a child dying between backfill and resume, a DB hiccup during the barrier read, a lost callback delivery). Pure sibling concurrency needs no extra cover: each completion checks the barrier only after committing its own backfill, so the last committer always sees every earlier one.

The webhook payload is trimmed to operationId/reason/status via eventFields: the endpoint reloads the child's final state from the coordinator, so the default payload (which ships the child's entire final answer via lastAssistantContent, plus any tool-produced attachments the shared lifecycle event extractor inlines) is dead weight.

🧪 How to Test

• Tested locally

• Added/updated tests

• No tests needed

• src/server/routers/lambda/__tests__/integration/aiAgent/serverSubAgent.integration.test.ts — end-to-end park → sub-op → backfill → resume (local handler path) passes.

• AgentRuntimeService.test.ts — 7 new cases: verify scheduling on not-yet-parked / unsatisfied barrier / terminal states; completeSubAgentBridge backfill from finalState, coordinator fallback (webhook path), error note on failure, resume despite backfill failure.

• subAgentCallback.test.ts — new endpoint handler tests (validation, 401, happy path, defaults, 500-for-redelivery).

• Full src/server/services/agentRuntime suite: 234 tests pass; type-check and eslint clean on touched files.

Queue-mode scenario to verify in a deployed environment: ask an agent to call N sub-agents in parallel (e.g. 3 weather lookups) — the parent should resume and produce the summary after all children finish.

📝 Additional Information

• Reproduction characteristics: in queue mode the hang was deterministic (the bridge never fired), not a flaky race; the screenshot symptom is all sub-agent calls showing completed with the parent never producing its final answer.
• execAgent's hetero completionWebhook extraction (hooks.find(h => h.type === 'onComplete')?.webhook) is unaffected: thread hooks precede the bridge in the hook array and the first onComplete match still has no webhook.
• QStash redelivery of the callback is safe: the backfill is idempotent and the resume is CAS-guarded.

🤖 Generated with Claude Code