Port delivery engine to session.synthetic + context hook

[frap129]

Question

Port the delivery engine (src/delivery/) from v1's synthetic-part injection via the chat.message hook to v2's primitives:

• Durable delivery (session-durable rules): v1 appended a synthetic text part to the user message via chat.message; v2 uses ctx.session.synthetic({ sessionID, text, metadata?, delivery?: "steer"|"queue" }). Verify: does steer/queue delivery timing match v1's "append to current user message before dispatch" semantics? If not, choose the closest and document the divergence.
• Transient delivery (ephemeral rules: agent/model/branch/tools): v1 used experimental.chat.messages.transform (one transient message per matching turn); v2 equivalent is the ctx.session.hook("context", ...). It runs per model dispatch (incl. tool continuations and compaction) and is never persisted — verify our "one transient message per matching turn" logic works against a per-dispatch-not-per-turn hook (may inject on tool continuations too; decide accept/adjust).
• Awaited no-reply admission (durable rule first matched by live File observation): v1 session.prompt with noReply → v2 ctx.session.prompt(..., { resume: false }). Keep transient fallback + retry-when-persistence-fails semantics.
• Preserve the existing codec/history-port (src/delivery/codec.ts, history port) or replace them if v2's session.context() read makes them obsolete.

[frap129]

Resolution

All four v2 API questions verified against the real beta source (@opencode-ai/plugin@0.0.0-beta-18999 typings + @opencode-ai/protocol and @opencode-ai/schema beta tarballs) and https://opencode.ai/v2/docs/build/plugins + the v2 API reference.

1. Durable delivery: steer matches v1's append-before-dispatch semantics

• session.synthetic "Durably admit synthetic session input and schedule execution unless resume is false" — a synthetic message is a durable inbox item (persisted message of type: "synthetic"), and delivery: "steer" (the default) runs it at the next step boundary, before queued prompts. queue would wait behind queued user prompts, which v1 never did.
• Kept delivery: 'steer' for all durable deliveries (src/runtime/orchestrator.ts prompt-hook handler). Divergence from v1 accepted and documented: v1 appended a synthetic part to the user message itself; v2 emits a separate persisted synthetic user message before the model sees the turn. Either way the content is in-history, idempotent, and visible to the dispatch.

2. Transient delivery: per-dispatch context hook works; re-injection on tool continuations is suppressed by turn-dedup

• Docs confirm the context hook "runs again for subsequent calls such as tool-driven continuations, transient session generation, and compaction, but not for title requests" — i.e. per model dispatch, never persisted.
• TransientDispatcher (src/delivery/delivery-transient.ts) keys a transientTurn on the latest real (non-transient) user message id present in the dispatch, so rule/hook keys already injected this turn are not appended again on tool continuations. A new user prompt resets the turn. Accepted as-is: one transient message per matching turn, delivered on every dispatch of that turn.

3. Awaited admission: session.prompt(..., { resume: false }) is exactly v1's noReply

• API docs: "Durably admit one session input and schedule agent-loop execution unless resume is false." No assistant reply, no prompt-hook recursion (synthetic messages and admissions don't run prompt hooks). Idempotent by id (ConflictError on duplicate), so persistPendingRules retry-through-history semantics are preserved (src/runtime/client-adapter.ts → session.prompt({ id, text, metadata, resume: false })). Transient fallback (return 'pending', retried on next dispatch via retryPendingAdmissions) unchanged.

4. Codec/history port: kept and extended, not replaced

• session.context() returns the full SessionMessageInfo[] union including type: "synthetic" messages with message-level metadata (no parts). decodeRawHistory was extended to read ledger keys from message-level metadata, so session.context() fully replaces the v1 session.messages history read; codec (rule-delivery-codec.ts) stays the single source of part/message/ledger-key identity.

Defect found and fixed during verification

• Synthetic id schema violation. The session.synthetic payload validates id against Session.Message.ID = isStartsWith("msg_"). We passed the codec's internal prt_rules_... part id — real v2 would reject every durable synthetic publish (masked in tests by the mocked sink). Fixed: syntheticMessageId() derives a stable msg_<partId> id (idempotency preserved; admission ids already used msg_-prefixed message ids).

Also verified

• Revert/compaction event names (session.revert.staged|cleared|committed, session.compaction.started|ended) and data.sessionID payload shape match the beta schema.
• SessionContext.model is a Model.Ref ({ providerID, id }), not { modelID } — our context-hook capture reads model.modelID, which under the real hook would silently leave model-matched rules unmatched. Tracked as follow-up (see map).

Verification: aube run lint clean, aubx tsc --noEmit clean, 547/547 tests pass on the v2 branch.