Skip to content

prompt-async-gate-rfc.md

Latest commit

 

History

History
235 lines (180 loc) · 9.07 KB

prompt-async-gate-rfc.md

File metadata and controls

235 lines (180 loc) · 9.07 KB

ADR: prompt-async-gate - reservation-based duplicate-injection guard

Status

Accepted (introduced in v4.2.0)

Context

Issue #4012 reported duplicate streaming output after OMO injected an internal message into a live OpenCode session.

The user-visible failure was two assistant bubbles streaming the same continuation.

The root race was not one hook making one bad decision. Multiple internal routes could observe the same idle, completion, or error edge and each decide that the parent session needed a wake or recovery prompt.

The most important race window was:

  1. OpenCode emitted a session.idle event.
  2. OMO started an isSessionActive HTTP poll.
  3. OpenCode was still pacing the streaming animation for the previous answer.
  4. The poll observed an inactive or idle-looking session.
  5. OMO injected a continuation prompt.
  6. A second hook observed the same edge and injected again.
  7. The user saw two assistant bubbles.

The historical race site was visible in the built bundle at dist/index.js:69665-69680. That code checked session activity before sending an internal prompt, but the check and the prompt were not protected by a shared reservation.

OpenCode's prompt_async route contributed to the failure mode because it has fire-and-forget semantics. session.promptAsync can resolve before the prompt is durably accepted by the target session. A later session.error event can still arrive for the same attempt, so the caller can believe dispatch finished while a recovery hook still treats the session as eligible for retry.

OMO has 13+ internal hook callers that can inject prompts, including:

  • background task parent wakes
  • runtime fallback retries
  • model suggestion retries
  • team mailbox live delivery
  • session recovery continuations
  • todo continuation resumes
  • CLI run resumes
  • Claude Code hook injections
  • sync subagent prompts
  • background subagent prompts

Route-local guards cannot close this race. Each route can be correct in isolation and still collide with another route in the same process.

The root AGENTS.md now records the governing invariant in the section "Internal message injection is dangerous": production code may call session.prompt or session.promptAsync only inside src/shared/prompt-async-gate.ts. Every other route must use the shared gate.

Decision

Create src/shared/prompt-async-gate.ts as the single production owner of raw OpenCode prompt dispatch.

The gate exposes one public dispatcher that production callers must use:

export function dispatchInternalPrompt(
  options: InternalPromptDispatchArgs,
): Promise<InternalPromptDispatchResult>

The gate coordinates callers with a module-global reservation map:

const reservations = new Map<string, Reservation>()

The map is keyed by sessionID. A reservation records the source that claimed the session, an expiration time, and a Symbol(source) token. The token gives each reservation identity beyond its text source.

Every caller supplies a stable source string such as:

const source = `background-agent:${taskID}`

The shared flow is:

  1. Prune expired reservations.
  2. Reserve the session before waiting or dispatching.
  3. Wait for the idle settle period.
  4. Poll session activity unless the route has a proven opt-out.
  5. Dispatch through the selected OpenCode prompt API.
  6. Keep the reservation during the post-dispatch hold.
  7. Release after the hold or through an explicit recovery path.

The reservation is taken before the activity poll so that two hooks cannot both enter the poll-dispatch window.

The default post-dispatch hold is exported as:

export const DEFAULT_PROMPT_ASYNC_POST_DISPATCH_HOLD_MS = 2_000

postDispatchHoldMs defaults to 2_000 ms (2 s) as of v4.2.3 (previously 250 ms). The gate holds the reservation briefly after the dispatch attempt even when dispatch throws synchronously or returns a failed result. This closes the AGENTS.md hazard where promptAsync returns before durable acceptance and a late OpenCode error races with retry logic. The 8x bump reduces dispatch contention against session.error arrivals on slower providers.

The default dispatch timeout is 30 seconds:

export const DEFAULT_PROMPT_DISPATCH_TIMEOUT_MS = 30_000

dispatchTimeoutMs wraps the underlying session.promptAsync or session.prompt call with Promise.race. A hung OpenCode API call must fail closed instead of holding a reservation forever.

The public dispatcher delegates to one internal runner:

dispatchAfterSessionIdle<TInput>(args)

dispatchInternalPrompt({ mode: "async", ... }) binds session.promptAsync. dispatchInternalPrompt({ mode: "sync", ... }) binds session.prompt. Sharing the runner keeps reservation, hold, timeout, logging, and active-session behavior identical for async and sync prompt routes.

The public gate result is a discriminated union. Callers must treat active and reserved as successful suppression, not automatic retry signals. A route that changed optimistic task or loop state before dispatch owns restoring that state when the gate returns failed, unavailable, or a skipped status that requires rollback.

The gate exposes releasePromptAsyncReservation for intentional recovery paths. Prefix release is deliberately tight:

export function releasePromptAsyncReservation(
  sessionID: string,
  options?: {
    reservedBy?: string
    reservedByPrefix?: string
  },
): boolean

releasePromptAsyncReservation(sessionID, {
  reservedByPrefix: "runtime-fallback:",
})

reservedByPrefix must end in :. This prevents broad releases such as runtime matching unrelated sources. Exact source release remains available for callers that know the full reservation source.

Raw prompt calls outside the gate are blocked by src/shared/prompt-async-route-audit.test.ts. The audit uses the TypeScript Compiler API rather than regex so it catches destructuring, bracket access, optional chaining, and aliased or cast access patterns.

Consequences

Positive

  • Duplicate internal prompt injection now has one reservation winner per session.
  • The post-dispatch hold closes the AGENTS.md "returns before durably accepted" hazard even when dispatch errors synchronously.
  • Dispatch timeout prevents a stuck OpenCode call from holding the gate forever.
  • 13+ internal hook callers share one result model and one safety primitive.
  • The AST-based audit from HIGH-5 catches more bypass shapes than the prior regex audit.
  • Route-specific tests can focus on route behavior while the shared gate tests reservation semantics.

Negative

  • Caller-side retry logic that releases and retries must call releasePromptAsyncReservation explicitly when the original prompt did not durably reach the server. src/shared/model-suggestion-retry.ts is the reference case.
  • 13+ wiring sites each need to be conscious of the gate result. Treating reserved as a failure can create noisy retries.
  • A valid retry can be delayed by the default 2_000 ms post-dispatch hold (raised from 250 ms in v4.2.3).
  • The reservation map is process-local. It protects OMO hooks in the current plugin process, not every possible OpenCode process.

Migration

Existing session.prompt and session.promptAsync callers must route through dispatchInternalPrompt with the matching dispatch mode.

Existing production callers were wired through the introduction PR #4034.

The AST-based audit fails CI if a raw prompt call is added without an allowlist entry. Any allowlist entry must explain why the raw access is not a dispatch route or why it is still gate-routed.

New internal message routes must include duplicate-injection regression tests for their trigger. Static policy alone is not enough.

Future work

  • Replace prefix-tightened release with full Symbol-token-based release ownership. This is the HIGH-7 deferred work.
  • Define same-source concurrent caller handling. Some routes may need collapse semantics by source rather than by session only.
  • Add dispatch metrics for observability, including reservation win, reserved skip, active skip, timeout, and failed dispatch counts.
  • Consider cross-process coordination if OpenCode exposes a durable session lock or idempotency key.

References

  • Issue #4012: duplicate streaming output and two assistant bubbles.
  • PR #4034: introduction of prompt-async-gate.
  • Commit b333a5280: fix(prompt-async-gate): add dispatch timeout, shared runner, harden prefix release.
  • Commit 8c4cc09de: test(prompt-async-route-audit): migrate to TypeScript AST walker.
  • Commit ff1b15d53: fix(model-suggestion-retry): release reservation before retry attempt.
  • Commit f93d7297c: test(prompt-async-gate): cover dispatch timeout and post-dispatch error hold.
  • PR #3866 -> PR #4053: schema-compatible synthetic tool results for post-compaction recovery, related to safe recovery dispatch.
  • Root AGENTS.md: section "Internal message injection is dangerous".
  • .omo/rules/test-discipline.md: forbids setTimeout(resolve, N) and await sleep(N) in tests unless time itself is the system under test.
  • Implementation: src/shared/prompt-async-gate.ts.
  • Audit: src/shared/prompt-async-route-audit.test.ts.