Skip to content

Determine whether OpenCode v1.x supports next-dispatch durable delivery #39

Closed

Description

@frap129

Part of #38

Question

Can the currently supported OpenCode v1.x plugin API observe successful Read, Write, Apply Patch, and LSP events and make newly matched durable rule content available before the immediately following provider dispatch in the same logical turn? Identify the exact hook and message APIs, mutability and persistence constraints, ordering and concurrency behavior, and any version-specific limitations. Contrast the result with the assumptions in feat: deliver rules at the earliest OpenCode v2 hook.

Activity

  1. self-assigned this
    on Aug 28, 2026
  2. frap129 commented on Aug 28, 2026

    @frap129
    OwnerAuthor

    OpenCode v1.x next-dispatch durable delivery

    Decision

    Yes, for successful built-in Read, Write, Apply Patch, and LSP calls, the supported OpenCode v1.x API can make newly matched durable content visible to the immediately following provider dispatch in the same logical turn. It requires a composition of existing v1 APIs rather than one purpose-built hook:

    1. Observe the successful call in tool.execute.after and update a per-session, concurrency-safe pending set.
    2. Before returning from that awaited hook, persist newly admitted durable content with client.session.prompt({ noReply: true, parts: [{ type: "text", synthetic: true, ... }] }).
    3. Use experimental.chat.messages.transform as the next-dispatch guard: merge any still-pending content into its mutable messages output, then let OpenCode build the provider request.

    This is viable throughout the repository's declared v1 range beginning at @opencode-ai/plugin 1.3.7. The exact current package/runtime combination was also checked: the repository declares peer compatibility from ^1.3.7 and development ranges from ^1.18.23; the local lock resolves plugin and SDK 1.18.23; and the installed OpenCode runtime reports 1.18.25. Relevant hook and prompt-loop source is unchanged between OpenCode 1.18.23 and 1.18.25.

    Evidence

    Successful tool input and output are visible

    The v1 plugin contract gives tool.execute.after the tool name, session ID, call ID, and original args, plus mutable title, output, and metadata fields. It gives experimental.chat.messages.transform the mutable message/part array (plugin 1.18.23 hook types). The same required hooks already exist at the repository's minimum supported plugin version (plugin 1.3.7 hook types).

    For registry-backed built-in tools, OpenCode awaits the tool implementation, constructs its model-visible result, and only then awaits tool.execute.after; a thrown/failed execution does not reach that after-hook (1.18.23 tool wrapper, 1.3.7 tool wrapper). Therefore:

    • Read matching can inspect the successful returned output text and path arguments.
    • Write matching can inspect the submitted content/path in args; the output confirms success.
    • Apply Patch matching can inspect successful args.patchText and the returned result.
    • LSP matching can inspect its operation/path arguments and successful returned output text.

    This observes the result exposed to the model, including any truncation already performed by the tool. It does not reconstruct omitted file content or treat a failed tool attempt as an observation.

    Ordering reaches the next dispatch

    OpenCode awaits each plugin's hook sequentially in plugin load order and passes the same mutable output through the chain (1.18.23 trigger implementation; the 1.3.7 implementation is equivalent at lines 285-298). Event subscriptions are not suitable for this guarantee because event callbacks are not awaited in the same way.

    After a tool step, the session loop starts its next iteration by reloading persisted messages. It then awaits experimental.chat.messages.transform, converts those mutated messages to model messages, and only afterward calls the processor/provider (1.18.23 loop, transform-to-dispatch sequence). Version 1.3.7 has the same ordering (transform-to-dispatch sequence). Because the tool wrapper awaits tool.execute.after, state mutation and awaited persistence complete before that tool result settles and before the continuation dispatch can be assembled.

    experimental.chat.messages.transform is dispatch-local: OpenCode uses the mutated in-memory array to build provider messages but does not write those mutations back to session storage. It is therefore the correct immediate-visibility guard, not durable storage.

    Durable synthetic persistence is available without another model turn

    The official v1 SDK/server API accepts noReply on session.prompt; official documentation describes it as injecting context without an AI response (SDK session API, server message endpoint). In version-matched source, prompt creation persists the user message and parts, while noReply: true returns before entering the model loop (1.18.23 prompt flow, 1.3.7 prompt flow). Text-part input explicitly supports synthetic: true and metadata (1.18.23 schema).

    Consequently, an awaited session.prompt call from tool.execute.after can persist a synthetic user text part without independently resuming the assistant. The running loop then reloads that message for its next dispatch. The plugin must mark and ignore its own synthetic message in chat.message, because synthetic admission itself invokes that hook before storage. A delivery ledger must only acknowledge the rule after persistence succeeds; on failure, the pending rule remains available for the transform/retry path.

    Concurrency requires plugin-side coordination

    OpenCode 1.18.23/1.18.25 uses AI SDK 6.0.168. That SDK intentionally starts tool executions without awaiting each one, tracks outstanding results, and closes the tool-result stream only after all have settled (AI SDK 6.0.168 execution scheduling, stream completion barrier). Thus multiple tool.execute.after callbacks for one provider response may overlap, but the next OpenCode dispatch waits for all tool-result executions to settle.

    The plugin must serialize admission/persistence per session and deduplicate by durable rule identity. There is no v1 "all tools in this provider response completed" plugin hook, so the safe design is to admit each newly matched identity atomically as successful calls finish. All admitted messages are present before the next dispatch, but distinct concurrent matches are not guaranteed to be persisted as one synthetic message. In-memory state that is only eventually flushed, an unawaited SDK call, or an event handler cannot provide the timing guarantee.

    Version and compatibility constraints

    • Repository contract: package.json declares @opencode-ai/plugin and @opencode-ai/sdk peers as ^1.3.7, and development ranges as ^1.18.23.
    • Minimum supported v1: 1.3.7 contains all three required APIs (tool.execute.after, experimental.chat.messages.transform, and prompt noReply) and the required ordering, so this finding does not inherently require raising the peer floor.
    • Current environment: the local dependency lock resolves plugin/SDK 1.18.23, while opencode --version reports 1.18.25. The relevant files have identical content in both tags; the official comparison contains no change to these seams.
    • experimental.chat.messages.transform remains explicitly experimental. Any OpenCode upgrade must re-verify its signature and ordering.
    • A later plugin in load order can mutate the same messages after this plugin. The guarantee assumes ordinary cooperative plugins, not a later hook deliberately removing the injected content.

    Contrast with feat: deliver rules at the earliest OpenCode v2 hook

    The future ticket assumes a v2 session-context hook and a v2 synthetic-session operation as first-class seams. Those APIs are not present in the v2 Promise plugin surface shipped with OpenCode 1.18.23/1.18.25: its PluginContext exposes agent, AI SDK, catalog, command, integration, plugin, reference, and skill domains, but no session-context domain (v2 Promise PluginContext).

    The v1 answer therefore does not validate those future v2 API names or semantics. It establishes that file-content matching need not wait for v2: v1 can meet the temporal and durability requirement by composing an after-hook, an awaited no-reply synthetic prompt, and the pre-dispatch message transform. The v2 ticket remains the place to replace that composition with a single authoritative context/persistence seam once OpenCode actually ships and versions those APIs.

    Specification consequence

    The file-content rule specification may require successful Read, Write, Apply Patch, and path-associated LSP observations to become durably available on the immediately following provider dispatch under OpenCode v1.x. It must also require per-session serialization, identity deduplication, retry-on-persistence-failure, self-synthetic-message suppression, and dispatch-local transform fallback. It must not require one persisted message per concurrent tool batch, because v1 exposes no batch-completion hook.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions