Give the dispatch hook a stable answer for who sent a message

[ymichael]

Human comments

What was wrong

A message.dispatch handler could not tell a message a user typed from one thread sending another, and the provenance it did get changed between attempts of the same dispatch. The context's only sender-ish field was startedOnBehalfOf, which answers why a THREAD was started and is null on every send, steer, drain and retry; the author was otherwise only reachable through queuedMessage, which exists only on a re-attempt. So the sender was invisible on a message's first attempt and visible on its second. In the other direction, origin, originPluginId and startedOnBehalfOf were read from the request, so a drained re-attempt saw null where the first attempt saw values — a policy keyed on them was right on an idle host and quietly wrong under load, which is when the queue exists. Fixes #3781.

What changed

• One author rule. resolveDispatchAuthor (apps/server/src/services/threads/thread-runtime-config.ts) is the single derivation of (initiator, senderThreadId): retry → system, sender thread → agent, startedOnBehalfOf → its initiator, else user. The value was already computed inline in thread-send (turn event + permission escalation) and thread-provisioning (thread start) and thrown away before the hook ran; both now call it, as do the thread-create telemetry gate and thread-edit-message, which each had their own copy. No behaviour change at those four sites — they agree with the rule on every input.
• Provenance on the queued row. New nullable columns on queued_thread_messages — origin, origin_plugin_id, requested_by_initiator, requested_by_thread_id — written in the same insert as the wait and read back by the drain (migration 0126_overconfident_vin_gonzales.sql). The requester is its own pair rather than a reuse of sender_thread_id: that column drives the [bb message from thread:…] prefix and would have rewritten the drained message's text. Half a pair throws rather than degrading to null.
• Plugin API (SDK 0.4.99 → 0.4.100). MessageDispatchHookContext gains initiator: ThreadTurnInitiator and senderThreadId: string | null; origin / originPluginId keep their types but are now stable across re-attempts. startedOnBehalfOf leaves the type — every bit it carried is now in those three fields, and its name answers a different question. Core still sets it on the emitted object for handlers built against an older SDK, via a named shim in dispatch-hooks.ts; docs/api_to_audit.md records that the shim must go before stabilization.
• Types moved. ThreadCreateOrigin and StartedOnBehalfOf move from @bb/server-contract to @bb/domain, because packages/db/src/schema.ts needs the enum values — the alternative was typing two enum columns as string.
• Docs and surfaces. backend-events.md (Plugin Guide reference), plugin-api-map/src/surfaces.ts bullets, and the makeMessageDispatchHookContext fixture updated. No wire change: HOST_DAEMON_PROTOCOL_VERSION is untouched, as nothing crosses the server/daemon boundary.

How you verified

Eight new tests in apps/server/test/threads/dispatch-hooks.test.ts: the four author paths (user, agent, retry, and the sender named on a re-attempt), the drained-send and drained-thread-start author-stability cases, drained origin stability plus a follow-up send that must stay origin-less, and the older-SDK startedOnBehalfOf shim. The two drain tests fail before this change — thread-start reports agent inline and user once drained, which the shipped drain test missed because it only covered the send path.

• pnpm exec turbo run typecheck lint --filter=@bb/db --filter=@bb/domain --filter=@get-bb/plugin-sdk --filter=@bb/server --filter=@bb/plugin-api-map --filter=@bb/server-contract — 11/11 pass
• pnpm exec turbo run test --filter=@bb/db --filter=@bb/domain --filter=@get-bb/plugin-sdk --filter=@bb/plugin-api-map --filter=@bb/server-contract — pass, including migrate.test.ts (57 tests) with the new rewind coverage for the four columns
• pnpm exec turbo run test --filter=@bb/server — 2920 pass. Two failures under the full parallel run, both green in isolation: test/services/machines/lifecycle-recovery.test.ts timed out at 5s under load (unrelated area), and dispatch-hooks.test.ts needed the fork source to announce a provider session after rebasing onto Keep resumed threads in their own provider sessions #3512, now seeded the way the passing fork tests do.
• node .github/workflows/check-plugin-sdk-version.mjs — passes with the 0.4.100 bump

Fixes #3781

AGENT GENERATED