From bf04b8a066119d0e733abe8ea2088d3d815795d6 Mon Sep 17 00:00:00 2001 From: Michael Ramos Date: Sat, 3 Oct 2026 07:19:28 -0700 Subject: [PATCH 1/4] feat(ai): Ask this session for OpenCode 2, over a host-neutral pull bridge Adds the "pull" transport for Ask this session: a host that runs the Plannotator server as a separate process (the OpenCode plugin's CLI child today, the Claude Code mod next) long-polls POST /api/ai/bridge/poll for questions and posts answer deltas, done, error, status and interrupt results to POST /api/ai/bridge/event. Token from the host's environment (scrubbed after reading), loopback Host only, no Origin, bounded 25s long-poll, re-send until acknowledged, gone after 30s of silence. Both runtimes serve it through createAIEndpoints; Bun takes the env config, Pi accepts the same config as an option. OpenCode 2: /plannotator-review, -annotate and -last answer as a real turn (session.prompt with our own message id, streamed from the event stream, session.wait + session.context fallback), with busy wait / interrupt and Stop mapped to session.interrupt on our own turn only. Plan review answers from context (session.generate, "Quick answer from this session") because submit_plan is a pending tool call; every bridge on that session reports blocked so nothing interrupts the review. OpenCode 1 is not covered (a second adapter over a different event model). No version bumps. --- AGENTS.md | 4 +- apps/hook/server/index.ts | 5 + apps/opencode-plugin/cli-bridge.ts | 88 ++- apps/opencode-plugin/embedded.ts | 4 + apps/opencode-plugin/native-commands.ts | 22 +- .../opencode-session-bridge.test.ts | 318 ++++++++++ .../opencode-session-bridge.ts | 541 ++++++++++++++++++ apps/opencode-plugin/package.json | 1 + apps/opencode-plugin/server.ts | 22 + .../session-bridge-cli.test.ts | 114 ++++ apps/opencode-plugin/v2-client.ts | 15 +- apps/pi-extension/server/ai-runtime.ts | 16 +- apps/pi-extension/vendor.sh | 2 +- bun.lock | 1 + packages/ai/endpoints.ts | 32 ++ packages/ai/index.ts | 22 + packages/ai/package.json | 2 + packages/ai/session-bridge-pull-client.ts | 267 +++++++++ packages/ai/session-bridge-pull.test.ts | 347 +++++++++++ packages/ai/session-bridge-pull.ts | 540 +++++++++++++++++ packages/ai/session-bridge.ts | 38 +- .../server/ai-runtime.sessionBridge.test.ts | 73 +++ packages/server/ai-runtime.ts | 42 +- packages/server/annotate.ts | 6 +- packages/server/index.ts | 6 +- packages/server/package.json | 1 + packages/server/review.ts | 6 +- 27 files changed, 2510 insertions(+), 25 deletions(-) create mode 100644 apps/opencode-plugin/opencode-session-bridge.test.ts create mode 100644 apps/opencode-plugin/opencode-session-bridge.ts create mode 100644 apps/opencode-plugin/session-bridge-cli.test.ts create mode 100644 packages/ai/session-bridge-pull-client.ts create mode 100644 packages/ai/session-bridge-pull.test.ts create mode 100644 packages/ai/session-bridge-pull.ts diff --git a/AGENTS.md b/AGENTS.md index 422542fc71..9764ba1afe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -604,7 +604,9 @@ Ask AI providers are detected independently from installed/authenticated local C Automatic resolution is session-only and never writes a preference. Explicit per-origin choices are persisted in cookies, so a user can override the automatic match for one agent without changing the default for another. -**"Ask this session" (session bridge).** A host can let Ask AI be answered by the agent session that opened Plannotator instead of a separate SDK agent. The host implements the small `SessionBridge` interface (`packages/ai/session-bridge.ts`, vendored to Pi: `host`, `status()` = `ready | busy | blocked | gone`, `modes { turn, transient }`, `ask(req, sink, signal)`, optional `interrupt()`) and passes it as `sessionBridge` to the server (`startReviewServer` / `startAnnotateServer` / plan `ServerOptions` on Bun; review and annotate on Pi), which registers `SessionBridgeProvider` LAST under id `session-bridge` (server default unchanged) behind the unchanged `/api/ai/*` endpoints. `/api/ai/capabilities` adds `label` ("Ask this session · Pi") and live `sessionBridge { host, status, modes }` for it, `models: []` (no model picker). The provider, not the host, enforces one question at a time across threads (`ask_in_flight`), sends no system prompt (the question carries the `SESSION_ASK_HEADER` line plus the surface), and never interrupts implicitly: a busy session answers `agent_busy`, and the client re-asks with `/api/ai/query` `busyPolicy: "wait"` ("Ask when it finishes", streams `status: waiting` until idle) or `"interrupt"` ("Interrupt and ask now", host `interrupt()` then ask). `session_gone` / `session_blocked` offer "Ask a separate AI instead", which moves THIS page (never the cookie: `applyConfigChange(..., { persist: false })`) to `resolveSessionBridgeFallback` and re-asks. Abort cancels only our question; the runtime `detach()`es the bridge before teardown so a decision/exit never stops a turn already running. Client default (`resolveAIProviderSelection`): an explicit saved pick wins (per-origin for origins with their own provider, else the global one), then a usable bridge (not gone; blocked only with a transient mode), then the old order — byte-identical without a bridge. Code review sends the diff's identity (`buildSessionReviewIdentity`), never the patch. **Pi** (`apps/pi-extension/pi-session-bridge.ts`): review, annotate and last only (plan review blocks inside `submit_plan`, so it keeps the SDK providers), off in remote mode; the question is a `pi.sendMessage({ customType: "plannotator-ask", display: true, details: { askId } }, { triggerTurn: true })` turn read back from `message_start` / `message_update` text deltas / `tool_execution_start` / `agent_end`; listeners register once at load because `pi.on` returns no unsubscribe before Pi 1.0. OpenCode and Claude Code have no bridge yet, so their Ask AI is unchanged. +**"Ask this session" (session bridge).** A host can let Ask AI be answered by the agent session that opened Plannotator instead of a separate SDK agent. The host implements the small `SessionBridge` interface (`packages/ai/session-bridge.ts`, vendored to Pi: `host`, `status()` = `ready | busy | blocked | gone`, `modes { turn, transient }`, `ask(req, sink, signal)`, optional `interrupt()`) and passes it as `sessionBridge` to the server (`startReviewServer` / `startAnnotateServer` / plan `ServerOptions` on Bun; review and annotate on Pi), which registers `SessionBridgeProvider` LAST under id `session-bridge` (server default unchanged) behind the unchanged `/api/ai/*` endpoints. `/api/ai/capabilities` adds `label` ("Ask this session · Pi") and live `sessionBridge { host, status, modes }` for it, `models: []` (no model picker). The provider, not the host, enforces one question at a time across threads (`ask_in_flight`), sends no system prompt (the question carries the `SESSION_ASK_HEADER` line plus the surface), and never interrupts implicitly: a busy session answers `agent_busy`, and the client re-asks with `/api/ai/query` `busyPolicy: "wait"` ("Ask when it finishes", streams `status: waiting` until idle) or `"interrupt"` ("Interrupt and ask now", host `interrupt()` then ask). `session_gone` / `session_blocked` offer "Ask a separate AI instead", which moves THIS page (never the cookie: `applyConfigChange(..., { persist: false })`) to `resolveSessionBridgeFallback` and re-asks. Abort cancels only our question; the runtime `detach()`es the bridge before teardown so a decision/exit never stops a turn already running. Client default (`resolveAIProviderSelection`): an explicit saved pick wins (per-origin for origins with their own provider, else the global one), then a usable bridge (not gone; blocked only with a transient mode), then the old order — byte-identical without a bridge. Code review sends the diff's identity (`buildSessionReviewIdentity`), never the patch. **Pi** (`apps/pi-extension/pi-session-bridge.ts`): review, annotate and last only (plan review blocks inside `submit_plan`, so it keeps the SDK providers), off in remote mode; the question is a `pi.sendMessage({ customType: "plannotator-ask", display: true, details: { askId } }, { triggerTurn: true })` turn read back from `message_start` / `message_update` text deltas / `tool_execution_start` / `agent_end`; listeners register once at load because `pi.on` returns no unsubscribe before Pi 1.0. **OpenCode 2** (`apps/opencode-plugin/opencode-session-bridge.ts`): review, annotate and last ask a real turn — `ctx.session.prompt({ id, text, delivery: "steer", metadata: { source: "plannotator-ask" } })` under a message id generated in OpenCode's own ascending `msg_` format, streamed back from `ctx.event.subscribe()` (`session.inbox.delivered` with our id starts the answer, then `session.text.delta` / `text.ended` / `tool.input.started`, ended by `session.execution.succeeded|failed|interrupted`), with `session.wait` + `session.context` as the fallback when the event stream is missing (upstream #44788). Delivery is "steer", not "queue", on purpose: every V2 command leaves its session-URL notice as a pending steer row, and a queued question would wake the session with that notice promoted alone as its own model turn (seen live on 2.0.22). Busy comes from the execution events cross-checked by a single outstanding `session.wait` probe; abort and "Interrupt and ask now" use `session.interrupt` (whole execution), only on a turn that is ours or on the reviewer's explicit choice. Plan review answers from context only ("Quick answer from this session · OpenCode", `modes { turn: false, transient: true }`): `submit_plan` is a pending tool call, so a real turn cannot run until the decision (a prompt sent then waits for the tool result, verified live), and `markPlanReviewPending` makes EVERY bridge on that session report `blocked` so nothing can interrupt the review. The quick answer is `session.generate` (no transcript write; verified live on 2.0.22 with OpenAI during a pending `submit_plan`, and `@opencode/ai`'s `normalizeToolHistory` fills the unfinished call with an error result for every provider); it still offers the model its tools, so the question carries `SESSION_ASK_TRANSIENT_NOTE` and an empty answer (a tool call) is reported as a failure. The embedded plan server takes the bridge in-process; review/annotate/last and the CLI plan fallback run the `plannotator` CLI as a child and use the pull bridge below. **OpenCode 1** has no bridge (a second adapter over V1's different message/event model, not a small lift). Claude Code has no bridge yet; its mod will use the pull bridge. + +**Pull bridge (host-neutral, `packages/ai/session-bridge-pull.ts` server half, vendored to Pi; `session-bridge-pull-client.ts` host half).** For a host that runs the Plannotator server as a SEPARATE process and must not open a listener of its own (the OpenCode plugin's CLI child today, the Claude Code mod next). The host generates a per-launch secret and starts the server with `PLANNOTATOR_SESSION_BRIDGE_TOKEN` (>= 32 chars), `PLANNOTATOR_SESSION_BRIDGE_HOST` (`opencode` / `claude-code` / `pi`) and optional `PLANNOTATOR_SESSION_BRIDGE_MODES` (`turn,transient`; default `turn`). The Bun `createAIRuntime` takes that config once per process (`takeEnvPullSessionBridgeConfig`), deletes the three variables so agent jobs and terminals never inherit the token, and registers the same `SessionBridgeProvider` over it; it is off in remote mode and under `--tailscale` (and an in-process bridge wins). Pi's `createPiAIRuntime` accepts the same config as its `pullSessionBridge` option (no env takeover: Pi itself always bridges in-process). The host learns the port (OpenCode: `PLANNOTATOR_READY_FILE`) and then talks to two endpoints on `http://127.0.0.1:`, both `POST` + JSON with `Authorization: Bearer `: `/api/ai/bridge/poll` `{ status?, modes?, waitMs? }` long-polls (clamped to 25s; answers early when there is work) and returns `{ commands, closing?, superseded? }`, commands being `{ type: "ask", askId, text, mode }`, `{ type: "cancel", askId }` and `{ type: "interrupt", interruptId }`; `/api/ai/bridge/event` takes one event or `{ events: [...] }` — `started`, `delta`, `tool`, `done`, `error` (per question, `code` one of `busy|blocked|gone|aborted|failed`), `status`, and `interrupted { interruptId, ok, message? }` — and answers `409 { code: "ask_not_active" }` for a question that is no longer running, which tells the host to stop it. Commands are re-sent every ~5s until acknowledged (any event for that question; `interrupted` for an interrupt), so hosts dedupe by id. Guards, in order: a loopback Host with the server's own port (the runtime's `authorizeSessionBridgeRequest`, `403 session_bridge_forbidden_host`), no `Origin` header (`403`, a browser is never the host), the bearer token (`401`); without a pull bridge both paths answer `404`, which an older-binary-aware host treats as "no bridge". Liveness: until the host's first request the bridge reports `ready` (a question waits for the first poll); no first request within 30s, or 30s with no open poll after that, is `gone`, and a running question then fails `session_gone`. The newest poll supersedes an open one. A reviewer's Stop drops a question the host never confirmed, else queues `cancel` and frees the slot when the host confirms (or after 15s); `detach()` (decision / shutdown) drops only unconfirmed questions, and `dispose()` answers the open poll `closing`. Both runtimes route the two paths through `createAIEndpoints` (`pullBridge` dep), and Bun lifts the idle timeout for the poll (`isLongLivedAIEndpointPath`). Tests: `packages/ai/session-bridge-pull.test.ts` (fake host over the real client: streaming, early question, busy wait / interrupt, abort before and after pickup, host disappears, never connects, transient, bad token / Origin / rebinding Host, supersede, dispose, detach), `packages/server/ai-runtime.sessionBridge.test.ts` (env takeover, scrub, remote-off), `apps/opencode-plugin/session-bridge-cli.test.ts` (plugin ↔ CLI child end to end). **Model lists come from the installed tools, not hand lists.** Claude's list is the SDK's `supportedModels()` against the installed `claude` (a throwaway process with no prompt, `settingSources: []` so no user hooks run, no MCP servers, 10s cap, ~0.5s measured); Codex's is the app-server `model/list`. Both run lazily behind the provider initializer (`?activate=` or the first session), never at startup; a success is kept for the process, a failure may be retried after 60s (`createBestEffortOnce`), and the capabilities answer marks each such provider's list `modelsSource: 'fallback' | 'discovered'` so the client forgets a fallback answer and retries on its next load. The same discovery captures the tool version once (`claude --version` run alongside it; codex from the app-server initialize `userAgent`, via `cliVersionFrom`), kept even when discovery fails, and the answer carries it as an optional `toolVersion`; every Claude/Codex model picker (Agents tab launchers, Guided Review, Ask AI bars, Settings) shows a muted `ModelSourceHint` line ("From your installed Codex 0.155.1", or the built-in-list variant on `fallback`) only when `toolVersion` is present, so a host that omits it gets no hint. Both runtimes share `createDeferredModelDiscovery`: an `?activate=` probe waits for discovery, and so does a session for every provider except Claude, whose sessions resolve the model against the current list while discovery finishes in the background, so the first Ask AI answer does not wait on it — except when that list is still the fallback and lacks the requested pick (e.g. `opus[1m]`), where the session waits for discovery rather than silently running a different model once. One shape, `CatalogModel` in `packages/core/model-catalog.ts` (id, label, efforts + default effort, fast mode, `resolvedId`), serves Ask AI AND the review / Code Tour / Guided Review launchers: `useModelCatalogs` (`packages/ui/hooks/`) fetches the same `/api/ai/capabilities?activate=` answer for the ONE engine a launcher is set to, and `useAgentSettings` resolves saved picks against it at read time (the cookie is never rewritten). ONE resolver, `resolveModelChoice`, is used by the launchers, Ask AI's client (`aiProvider.ts`) and the AI session endpoint: exact id → the alias whose `resolvedId` covers it → the same family's alias (`claude-opus-5` → `opus`) → the surface default (Claude `opus` for review, `sonnet` for tour/guide; Codex `''` = the model the Codex list marks default, except Guided Review, which prefers `gpt-6-luna` when offered: `PREFERRED_GUIDE_CODEX_MODEL`) → the catalog default; it never moves a pick onto a `[1m]` id unless the pick was one. Efforts clamp to the model's own levels, launches wait until the catalog settles, and a loading row shows meanwhile. The Claude catalog drops the SDK's `default` pointer row and adds a bare latest alias per family offered, and always offers `opus` / `sonnet` / `haiku` (some CLIs, e.g. Claude Code 2.1.141, name Opus only through the `default` row, whose description then supplies the version); alias labels carry the version parsed from the row's `resolvedModel` (`claudeModelVersion`: "Opus 5.5 (latest)"), since the SDK's `displayName` has none. Codex fast mode is dropped when resolution replaces a saved model with a different one; changing Fast or reasoning then re-keys the section to the model shown. Codex fast support is read from `serviceTiers` (a `priority`/`fast` tier) as well as the deprecated `additionalSpeedTiers`. The only static lists are the small `CLAUDE_FALLBACK_MODELS` / `CODEX_FALLBACK_MODELS`, used when discovery fails. diff --git a/apps/hook/server/index.ts b/apps/hook/server/index.ts index c009ccd9d6..813432682e 100644 --- a/apps/hook/server/index.ts +++ b/apps/hook/server/index.ts @@ -113,6 +113,7 @@ import { createWorktreePool, type WorktreePool, type PoolEntry } from "@plannota import { parsePRUrl, checkPRAuth, fetchPR, getCliName, getCliInstallUrl, getMRLabel, getMRNumberLabel, getDisplayRepo, getPlatformLabel, getPRNumber, getPRHeadFetchSpec, getPRCloneCommand } from "@plannotator/server/pr"; import { writeRemoteShareLink } from "@plannotator/server/share-url"; import { enableTailscaleServe } from "@plannotator/server/tailscale-serve"; +import { takeEnvPullSessionBridgeConfig } from "@plannotator/server/ai-runtime"; import { writeUrlQr } from "@plannotator/server/qr"; import { resolveAnnotateTarget } from "./annotate-resolution"; import { LIVE_APP_REMOTE_MESSAGE } from "@plannotator/shared/live-probe"; @@ -276,6 +277,10 @@ if (tailscaleFlag) { // suppresses a config-file urlHost, avoiding the misleading // "set PLANNOTATOR_REMOTE=1" local-session warning mid --tailscale run. process.env.PLANNOTATOR_URL_HOST = ""; + // "Ask this session" stays off in a tailnet-published session, as it is in + // remote mode: the session is reachable from other devices. Taking the + // host's bridge config here discards it (and scrubs the token from env). + takeEnvPullSessionBridgeConfig(); } /** diff --git a/apps/opencode-plugin/cli-bridge.ts b/apps/opencode-plugin/cli-bridge.ts index 69f10d173b..76644495fe 100644 --- a/apps/opencode-plugin/cli-bridge.ts +++ b/apps/opencode-plugin/cli-bridge.ts @@ -2,7 +2,14 @@ import { spawn } from "node:child_process"; import { existsSync, readFileSync, rmSync, statSync } from "node:fs"; import { tmpdir } from "node:os"; import path from "node:path"; -import { randomUUID } from "node:crypto"; +import { randomBytes, randomUUID } from "node:crypto"; +import type { SessionBridge } from "@plannotator/ai/session-bridge"; +import { + SESSION_BRIDGE_HOST_ENV, + SESSION_BRIDGE_MODES_ENV, + SESSION_BRIDGE_TOKEN_ENV, +} from "@plannotator/ai/session-bridge-pull"; +import { runPullSessionBridgeClient } from "@plannotator/ai/session-bridge-pull-client"; import { parseAnnotateArgs, type ParsedAnnotateArgs } from "@plannotator/shared/annotate-args"; import { parseReviewArgs, resolveReviewTarget } from "@plannotator/shared/review-args"; import { @@ -85,6 +92,12 @@ interface RunCliOptions { extraEnv?: Record; bridge?: OpenCodeBridgeContext; abortSignal?: AbortSignal; + /** + * "Ask this session": a bridge to the OpenCode session that ran the command. + * The CLI server reaches it through the pull protocol: it gets a fresh token + * in its environment, and once it is listening this process long-polls it. + */ + sessionBridge?: SessionBridge; } interface RunCliResult { @@ -328,15 +341,25 @@ export function createCliStderrForwarder(client: OpenCodeClient, toastedUrls: Se }; } -function logReadyFile(client: OpenCodeClient, readyFile: string, readyLabel: string, loggedUrls: Set, toastedUrls: Set): void { +function logReadyFile( + client: OpenCodeClient, + readyFile: string, + readyLabel: string, + loggedUrls: Set, + toastedUrls: Set, + onServer?: (metadata: { port: number; isRemote: boolean }) => void, +): void { if (!existsSync(readyFile)) return; const contents = readFileSync(readyFile, "utf-8"); for (const line of contents.split(/\r?\n/)) { if (!line.trim()) continue; try { - const metadata = JSON.parse(line) as { url?: string }; + const metadata = JSON.parse(line) as { url?: string; port?: unknown; isRemote?: unknown }; if (!metadata.url || loggedUrls.has(metadata.url)) continue; + if (typeof metadata.port === "number") { + onServer?.({ port: metadata.port, isRemote: metadata.isRemote === true }); + } loggedUrls.add(metadata.url); log(client, "info", `[Plannotator] Open ${readyLabel}: ${metadata.url}`); toastPlannotatorUrl(client, `Open ${readyLabel}: ${metadata.url}`, toastedUrls); @@ -381,6 +404,25 @@ async function runPlannotatorCli(options: RunCliOptions): Promise const loggedUrls = new Set(); const toastedUrls = new Set(); const cwd = options.cwd ?? process.cwd(); + const sessionBridge = options.sessionBridge; + const bridgeToken = sessionBridge ? randomBytes(32).toString("base64url") : undefined; + const bridgeClient = new AbortController(); + let bridgeClientStarted = false; + // The server is up: start answering its "Ask this session" questions. + const onServer = ({ port, isRemote }: { port: number; isRemote: boolean }) => { + // The server keeps the bridge off in remote mode; nothing to poll there. + if (!sessionBridge || !bridgeToken || bridgeClientStarted || isRemote) return; + bridgeClientStarted = true; + void runPullSessionBridgeClient({ + baseUrl: `http://127.0.0.1:${port}`, + token: bridgeToken, + bridge: sessionBridge, + signal: bridgeClient.signal, + log: (message) => log(options.client, "info", message), + }).catch((error) => { + log(options.client, "info", `[Plannotator] Session bridge stopped: ${error instanceof Error ? error.message : String(error)}`); + }); + }; const env = { ...process.env, ...options.extraEnv, @@ -389,6 +431,16 @@ async function runPlannotatorCli(options: RunCliOptions): Promise PLANNOTATOR_ORIGIN: "opencode", PLANNOTATOR_CWD: cwd, PLANNOTATOR_READY_FILE: readyFile, + ...(sessionBridge && bridgeToken + ? { + [SESSION_BRIDGE_TOKEN_ENV]: bridgeToken, + [SESSION_BRIDGE_HOST_ENV]: "opencode", + [SESSION_BRIDGE_MODES_ENV]: [ + sessionBridge.modes.turn ? "turn" : "", + sessionBridge.modes.transient ? "transient" : "", + ].filter(Boolean).join(","), + } + : {}), }; const bin = getPlannotatorBin(); @@ -437,7 +489,7 @@ async function runPlannotatorCli(options: RunCliOptions): Promise }); stderrForwarder = createCliStderrForwarder(options.client, toastedUrls); interval = setInterval( - () => logReadyFile(options.client, readyFile, options.readyLabel, loggedUrls, toastedUrls), + () => logReadyFile(options.client, readyFile, options.readyLabel, loggedUrls, toastedUrls, onServer), 250, ); @@ -491,6 +543,7 @@ async function runPlannotatorCli(options: RunCliOptions): Promise } }); } finally { + bridgeClient.abort(); if (interval !== undefined) clearInterval(interval); if (forceKillTimer !== undefined) clearTimeout(forceKillTimer); if (abortSignal && abortListener) abortSignal.removeEventListener("abort", abortListener); @@ -527,10 +580,13 @@ export async function runCliPlanReview(input: { timeoutSeconds: number | null; abortSignal?: AbortSignal; bridge?: OpenCodeBridgeContext; + /** "Ask this session" (quick answers while the plan waits). */ + sessionBridge?: SessionBridge; }): Promise { const result = await runPlannotatorCli({ client: input.client, args: ["opencode-plan"], + sessionBridge: input.sessionBridge, cwd: input.cwd, input: JSON.stringify({ plan: input.planContent, @@ -691,6 +747,9 @@ export function buildAnnotatePromptFromBridgeOutcome( }); } +/** A session bridge the command owns for the lifetime of its CLI run. */ +export type DisposableSessionBridge = SessionBridge & { dispose?: () => void }; + export async function handleCliCommand(input: { command: string; client: OpenCodeClient; @@ -698,8 +757,24 @@ export async function handleCliCommand(input: { rawArgs: string; cwd?: string; bridge?: OpenCodeBridgeContext; + /** + * "Ask this session": builds the bridge to the invoking session. Called only + * once the command is about to open a Plannotator UI; disposed when it ends. + */ + createSessionBridge?: () => DisposableSessionBridge | undefined; }): Promise { const cwd = input.cwd ?? process.cwd(); + let ownedBridge: DisposableSessionBridge | undefined; + const sessionBridge = (): SessionBridge | undefined => { + if (!ownedBridge) { + try { + ownedBridge = input.createSessionBridge?.(); + } catch { + ownedBridge = undefined; + } + } + return ownedBridge; + }; try { if (input.command === "plannotator-review") { @@ -738,6 +813,7 @@ export async function handleCliCommand(input: { }), readyLabel: "code review", bridge: input.bridge, + sessionBridge: sessionBridge(), }); if (result.exitCode !== 0) { log(input.client, "error", result.stderr.trim() || `Plannotator CLI exited with code ${result.exitCode}`); @@ -782,6 +858,7 @@ export async function handleCliCommand(input: { cwd, readyLabel: "annotation UI", bridge: input.bridge, + sessionBridge: sessionBridge(), }); if (result.exitCode !== 0) { log(input.client, "error", result.stderr.trim() || `Plannotator CLI exited with code ${result.exitCode}`); @@ -837,6 +914,7 @@ export async function handleCliCommand(input: { }), readyLabel: "annotation UI", bridge: input.bridge, + sessionBridge: sessionBridge(), }); if (result.exitCode !== 0) { log(input.client, "error", result.stderr.trim() || `Plannotator CLI exited with code ${result.exitCode}`); @@ -869,5 +947,7 @@ export async function handleCliCommand(input: { } catch (error) { log(input.client, "error", `[Plannotator] ${error instanceof Error ? error.message : String(error)}`); if (isOpenCodePromptDeliveryError(error)) throw error; + } finally { + ownedBridge?.dispose?.(); } } diff --git a/apps/opencode-plugin/embedded.ts b/apps/opencode-plugin/embedded.ts index 183e0c427d..0ce29c8420 100644 --- a/apps/opencode-plugin/embedded.ts +++ b/apps/opencode-plugin/embedded.ts @@ -8,6 +8,7 @@ import { getAnnotateMessageFeedbackPrompt, } from "@plannotator/shared/prompts"; import { deliverOpenCodePrompt } from "./prompt-delivery-error"; +import type { SessionBridge } from "@plannotator/ai/session-bridge"; export interface EmbeddedPlanReviewInput { client: any; @@ -19,6 +20,8 @@ export interface EmbeddedPlanReviewInput { timeoutSeconds: number | null; abortSignal?: AbortSignal; logReady: (url: string, isRemote: boolean, port: number) => void; + /** "Ask this session": in-process bridge to the session (quick answers while the plan waits). */ + sessionBridge?: SessionBridge; } export interface EmbeddedPlanReviewResult { @@ -83,6 +86,7 @@ export async function runEmbeddedPlanReview( pasteApiUrl: input.pasteApiUrl, htmlContent: input.htmlContent, opencodeClient: input.client, + sessionBridge: input.sessionBridge, onReady: async (url, isRemote, port) => { await handleServerReady(url, isRemote, port); input.logReady(url, isRemote, port); diff --git a/apps/opencode-plugin/native-commands.ts b/apps/opencode-plugin/native-commands.ts index 63697221f1..8b1c868cfc 100644 --- a/apps/opencode-plugin/native-commands.ts +++ b/apps/opencode-plugin/native-commands.ts @@ -17,7 +17,13 @@ * translation client, so the two hosts cannot drift. */ -import { handleCliCommand, type OpenCodeBridgeAgent, type OpenCodeBridgeContext } from "./cli-bridge"; +import { + handleCliCommand, + type DisposableSessionBridge, + type OpenCodeBridgeAgent, + type OpenCodeBridgeContext, +} from "./cli-bridge"; +import { createOpenCodeSessionBridge } from "./opencode-session-bridge"; import { createV2BridgeClient, readListPayload, @@ -66,6 +72,19 @@ export interface CliCommandRequest { rawArgs: string; cwd?: string; bridge?: OpenCodeBridgeContext; + createSessionBridge?: () => DisposableSessionBridge | undefined; +} + +/** + * "Ask this session" for a native command: a bridge to the invoking session, + * or undefined on a host whose plugin API cannot prompt the session. + */ +export function createNativeCommandSessionBridge( + ctx: V2ContextLike, + sessionID: string, +): DisposableSessionBridge | undefined { + if (!sessionID || typeof ctx.session?.prompt !== "function") return undefined; + return createOpenCodeSessionBridge({ ctx, sessionID }); } export interface NativeCommandDeps { @@ -118,6 +137,7 @@ export async function runNativeCommand( rawArgs, cwd: await resolveDirectory(deps.ctx, sessionID), bridge: await deps.getBridgeContext(), + createSessionBridge: () => createNativeCommandSessionBridge(deps.ctx, sessionID), }); } finally { // The client may be watching the host's event stream for its session-URL diff --git a/apps/opencode-plugin/opencode-session-bridge.test.ts b/apps/opencode-plugin/opencode-session-bridge.test.ts new file mode 100644 index 0000000000..f068beb1ae --- /dev/null +++ b/apps/opencode-plugin/opencode-session-bridge.test.ts @@ -0,0 +1,318 @@ +import { afterEach, describe, expect, test } from "bun:test"; +import { + createOpenCodeMessageId, + createOpenCodeSessionBridge, + markPlanReviewPending, + readAnswerAfter, + type OpenCodeSessionBridge, +} from "./opencode-session-bridge"; +import type { SessionBridgeErrorCode } from "@plannotator/ai/session-bridge"; + +const SESSION = "ses_test"; + +/** A hand-driven stand-in for the plugin's `ctx.session` + `ctx.event`. */ +function fakeHost(options: { events?: boolean; idle?: boolean } = {}) { + const listeners = new Set<(event: unknown) => void>(); + const prompts: any[] = []; + const generates: any[] = []; + let interrupts = 0; + let idle = options.idle ?? true; + const idleWaiters: Array<() => void> = []; + let context: unknown[] = []; + let generateResult: (value: unknown) => void = () => {}; + + const emit = (type: string, data: Record = {}) => { + for (const listener of listeners) listener({ type, data: { sessionID: SESSION, ...data } }); + }; + const setIdle = (value: boolean) => { + idle = value; + if (value) for (const waiter of idleWaiters.splice(0)) waiter(); + }; + + const ctx: any = { + session: { + prompt: async (input: any) => { + prompts.push(input); + return { id: input.id }; + }, + generate: (input: any) => { + generates.push(input); + return new Promise((resolve) => { + generateResult = resolve; + }); + }, + interrupt: async () => { + interrupts += 1; + return { interrupted: true }; + }, + wait: () => (idle ? Promise.resolve() : new Promise((resolve) => idleWaiters.push(resolve))), + context: async () => context, + }, + ...(options.events !== false && { + event: { + subscribe: ({ signal }: { signal: AbortSignal }) => ({ + async *[Symbol.asyncIterator]() { + const queue: unknown[] = []; + let wake: (() => void) | null = null; + const listener = (event: unknown) => { + queue.push(event); + wake?.(); + }; + listeners.add(listener); + try { + while (!signal.aborted) { + if (queue.length) { + yield queue.shift(); + continue; + } + await new Promise((resolve) => { + wake = resolve; + signal.addEventListener("abort", () => resolve(), { once: true }); + }); + wake = null; + } + } finally { + listeners.delete(listener); + } + }, + }), + }, + }), + }; + + return { + ctx, + emit, + setIdle, + prompts, + generates, + get interrupts() { + return interrupts; + }, + setContext(value: unknown[]) { + context = value; + }, + resolveGenerate(value: unknown) { + generateResult(value); + }, + }; +} + +function recordingSink() { + const deltas: string[] = []; + const tools: string[] = []; + let done: string | undefined; + let error: { code: SessionBridgeErrorCode; message?: string } | undefined; + return { + sink: { + delta: (text: string) => deltas.push(text), + tool: (name: string) => tools.push(name), + done: (answer: string) => { + done = answer; + }, + error: (code: SessionBridgeErrorCode, message?: string) => { + error = { code, message }; + }, + }, + deltas, + tools, + get done() { + return done; + }, + get error() { + return error; + }, + }; +} + +async function waitFor(predicate: () => boolean, timeoutMs = 2000): Promise { + const start = Date.now(); + while (!predicate()) { + if (Date.now() - start > timeoutMs) throw new Error("timed out waiting"); + await new Promise((resolve) => setTimeout(resolve, 2)); + } +} + +const bridges: OpenCodeSessionBridge[] = []; +const releases: Array<() => void> = []; +afterEach(() => { + for (const bridge of bridges.splice(0)) bridge.dispose(); + for (const release of releases.splice(0)) release(); +}); + +function bridgeFor(host: ReturnType, extra: Record = {}) { + const bridge = createOpenCodeSessionBridge({ ctx: host.ctx, sessionID: SESSION, idleProbeMs: 20, busyProbeMs: 10, fallbackPollMs: 10, ...extra }); + bridges.push(bridge); + return bridge; +} + +describe("OpenCode session bridge", () => { + test("asks as a steered prompt under our own id and streams the turn that answers it", async () => { + const host = fakeHost(); + const bridge = bridgeFor(host); + const sink = recordingSink(); + bridge.ask({ askId: "a1", text: "[Plannotator Ask AI] why?", mode: "turn" }, sink.sink, new AbortController().signal); + await waitFor(() => host.prompts.length === 1); + const prompt = host.prompts[0]; + // "steer", so the question co-promotes with the session-URL notice the + // command left pending instead of waking a separate turn for the notice. + expect(prompt.delivery).toBe("steer"); + expect(prompt.id).toMatch(/^msg_[0-9a-f]{12}[0-9A-Za-z]{14}$/); + expect(prompt.metadata).toEqual({ source: "plannotator-ask" }); + + // Output from before our question was delivered is not ours. + host.emit("session.text.delta", { assistantMessageID: "m0", ordinal: 0, delta: "unrelated" }); + host.emit("session.execution.started"); + host.emit("session.inbox.delivered", { inboxID: prompt.id }); + host.emit("session.text.started", { assistantMessageID: "m1", ordinal: 0 }); + host.emit("session.text.delta", { assistantMessageID: "m1", ordinal: 0, delta: "Because " }); + host.emit("session.text.delta", { assistantMessageID: "m1", ordinal: 0, delta: "of X." }); + host.emit("session.text.ended", { assistantMessageID: "m1", ordinal: 0, text: "Because of X." }); + host.emit("session.tool.input.started", { assistantMessageID: "m1", id: "t1", name: "read" }); + // A block delivered whole, with no deltas, is replayed from text.ended. + host.emit("session.text.started", { assistantMessageID: "m2", ordinal: 0 }); + host.emit("session.text.ended", { assistantMessageID: "m2", ordinal: 0, text: "Also Y." }); + host.emit("session.execution.succeeded"); + + await waitFor(() => sink.done !== undefined); + expect(sink.done).toBe("Because of X.\n\nAlso Y."); + expect(sink.deltas.join("")).toBe("Because of X.\n\nAlso Y."); + expect(sink.tools).toEqual(["read"]); + }); + + test("reports busy while the session runs, blocked while a plan review waits, gone once deleted", async () => { + const host = fakeHost(); + const bridge = bridgeFor(host); + await waitFor(() => bridge.status() === "ready"); + host.emit("session.execution.started"); + await waitFor(() => bridge.status() === "busy"); + host.emit("session.execution.succeeded"); + await waitFor(() => bridge.status() === "ready"); + + const release = markPlanReviewPending(SESSION); + releases.push(release); + expect(bridge.status()).toBe("blocked"); + release(); + expect(bridge.status()).toBe("ready"); + + host.emit("session.deleted"); + await waitFor(() => bridge.status() === "gone"); + }); + + test("a session already running when the bridge starts reads busy until it goes idle", async () => { + const host = fakeHost({ idle: false }); + const bridge = bridgeFor(host); + await waitFor(() => bridge.status() === "busy"); + host.setIdle(true); + await waitFor(() => bridge.status() === "ready"); + }); + + test("stopping our running turn interrupts it; the interrupted run reports aborted", async () => { + const host = fakeHost(); + const bridge = bridgeFor(host); + const sink = recordingSink(); + const controller = new AbortController(); + bridge.ask({ askId: "a1", text: "q", mode: "turn" }, sink.sink, controller.signal); + await waitFor(() => host.prompts.length === 1); + host.emit("session.inbox.delivered", { inboxID: host.prompts[0].id }); + host.emit("session.text.delta", { assistantMessageID: "m1", ordinal: 0, delta: "partial" }); + controller.abort(); + await waitFor(() => host.interrupts === 1); + host.emit("session.execution.interrupted", { reason: "user" }); + await waitFor(() => sink.error !== undefined); + expect(sink.error?.code).toBe("aborted"); + }); + + test("a question stopped before delivery never interrupts other work; it is stopped once delivered", async () => { + const host = fakeHost(); + const bridge = bridgeFor(host); + const sink = recordingSink(); + const controller = new AbortController(); + bridge.ask({ askId: "a1", text: "q", mode: "turn" }, sink.sink, controller.signal); + await waitFor(() => host.prompts.length === 1); + controller.abort(); + await new Promise((resolve) => setTimeout(resolve, 20)); + expect(host.interrupts).toBe(0); + host.emit("session.inbox.delivered", { inboxID: host.prompts[0].id }); + await waitFor(() => host.interrupts === 1); + }); + + test("refuses an interrupt while the session waits on a plan review", async () => { + const host = fakeHost(); + const bridge = bridgeFor(host); + releases.push(markPlanReviewPending(SESSION)); + await expect(Promise.resolve(bridge.interrupt?.())).rejects.toThrow(); + expect(host.interrupts).toBe(0); + }); + + test("a transient question answers from session.generate without touching the transcript", async () => { + const host = fakeHost(); + const bridge = bridgeFor(host, { modes: { turn: false, transient: true } }); + const sink = recordingSink(); + bridge.ask({ askId: "a1", text: "what is step 2?", mode: "transient" }, sink.sink, new AbortController().signal); + await waitFor(() => host.generates.length === 1); + expect(host.generates[0]).toEqual({ sessionID: SESSION, prompt: "what is step 2?" }); + host.resolveGenerate({ text: "Step 2 migrates the table." }); + await waitFor(() => sink.done !== undefined); + expect(sink.done).toBe("Step 2 migrates the table."); + expect(host.prompts.length).toBe(0); + }); + + test("an empty transient answer (the model reached for a tool) is a failure, and an aborted one is dropped", async () => { + const host = fakeHost(); + const bridge = bridgeFor(host, { modes: { turn: false, transient: true } }); + const empty = recordingSink(); + bridge.ask({ askId: "a1", text: "q", mode: "transient" }, empty.sink, new AbortController().signal); + await waitFor(() => host.generates.length === 1); + host.resolveGenerate({ text: "" }); + await waitFor(() => empty.error !== undefined); + expect(empty.error?.code).toBe("failed"); + + const dropped = recordingSink(); + const controller = new AbortController(); + bridge.ask({ askId: "a2", text: "q", mode: "transient" }, dropped.sink, controller.signal); + await waitFor(() => host.generates.length === 2); + controller.abort(); + host.resolveGenerate({ text: "late" }); + await new Promise((resolve) => setTimeout(resolve, 20)); + expect(dropped.done).toBeUndefined(); + expect(dropped.error).toBeUndefined(); + }); + + test("with no event stream, the answer is read from the session context once it is idle", async () => { + const host = fakeHost({ events: false }); + const bridge = bridgeFor(host); + const sink = recordingSink(); + bridge.ask({ askId: "a1", text: "q", mode: "turn" }, sink.sink, new AbortController().signal); + await waitFor(() => host.prompts.length === 1); + const id = host.prompts[0].id; + host.setContext([ + { id: "msg_old", type: "user", content: [{ type: "text", text: "earlier" }] }, + { id, type: "user", content: [{ type: "text", text: "q" }] }, + { id: "msg_a", type: "assistant", content: [{ type: "text", text: "The answer." }] }, + ]); + await waitFor(() => sink.done !== undefined); + expect(sink.done).toBe("The answer."); + }); +}); + +describe("OpenCode message ids", () => { + test("follow OpenCode's ascending id shape and sort by creation time", () => { + const a = createOpenCodeMessageId(1_791_000_000_000); + const b = createOpenCodeMessageId(1_791_000_000_000); + const c = createOpenCodeMessageId(1_791_000_000_001); + expect(a).toMatch(/^msg_[0-9a-f]{12}[0-9A-Za-z]{14}$/); + expect([c, b, a].sort()).toEqual([a, b, c]); + }); + + test("readAnswerAfter stops at the next user message", () => { + expect(readAnswerAfter([ + { id: "msg_q", type: "user" }, + { id: "msg_a", type: "assistant", content: [{ type: "text", text: "one" }, { type: "tool" }] }, + { id: "msg_b", type: "assistant", content: [{ type: "text", text: "two" }] }, + { id: "msg_u", type: "user" }, + { id: "msg_c", type: "assistant", content: [{ type: "text", text: "not ours" }] }, + ], "msg_q")).toBe("one\n\ntwo"); + expect(readAnswerAfter([], "msg_q")).toBeUndefined(); + }); +}); diff --git a/apps/opencode-plugin/opencode-session-bridge.ts b/apps/opencode-plugin/opencode-session-bridge.ts new file mode 100644 index 0000000000..51f161c1cc --- /dev/null +++ b/apps/opencode-plugin/opencode-session-bridge.ts @@ -0,0 +1,541 @@ +/** + * "Ask this session" for OpenCode 2: answers Plannotator's Ask AI from the + * OpenCode session that opened the review, annotation or plan review. + * + * Implements the host-neutral `SessionBridge` (packages/ai/session-bridge.ts) + * over the plugin's own `ctx.session` and `ctx.event` domains. Two kinds of + * question: + * + * - `turn`: a real prompt in the session (`session.prompt`, delivery "steer"), + * streamed back from the event stream and kept in the transcript. Used by + * /plannotator-review, -annotate and -last, whose CLI server runs as a + * separate process and reaches this object through the pull bridge. + * - `transient`: `session.generate`, one completion over the session's + * context with nothing written to the transcript. Used while the session is + * waiting on a plan review (`submit_plan` is a pending tool call, so a real + * turn cannot run until the reviewer decides): checked live against OpenCode + * 2.0.22, `generate` answers during a pending tool call, and @opencode/ai + * fills the missing tool result before the request goes out. It still + * offers the model its tools, and a tool call yields an empty answer, which + * is reported as a failure rather than shown as blank. + * + * OpenCode API notes (checked against anomalyco/opencode `v2` 40679546d4 and + * the installed @opencode/cli 2.0.22): + * - `session.prompt({ id })` admits an inbox row under our id; the event + * `session.inbox.delivered { inboxID }` says it entered the model context. + * Message ids are time-ordered (`msg_` + 12 hex time chars + 14 base62), so + * ours is generated the same way to sort where it belongs in the transcript. + * - `session.execution.started|succeeded|failed|interrupted` bracket a run; + * text arrives as `session.text.delta` (live only) and `session.text.ended` + * (full text, replayable), tool names on `session.tool.input.started`. + * - The plugin session domain has no "is this session busy" call. Busy is + * tracked from the execution events, cross-checked by `session.wait`, which + * resolves at once when the session is idle (and is the whole signal when + * the event stream is unavailable, upstream #44788). + * - `session.interrupt` stops the WHOLE execution. It is only called for a + * turn that is ours, or when the reviewer chose "Interrupt and ask now", and + * never while the session waits on a plan review (status `blocked`). + */ + +import type { + SessionBridge, + SessionBridgeSink, + SessionBridgeStatus, +} from "@plannotator/ai/session-bridge"; +import type { V2ContextLike } from "./v2-client"; + +export const PLANNOTATOR_ASK_SOURCE = "plannotator-ask"; + +/** How long a turn question may sit undelivered on an idle session before it is reported failed. */ +const DELIVERY_WATCHDOG_MS = 15_000; +/** Idle re-check cadence while no execution event says otherwise. */ +const IDLE_PROBE_MS = 1_000; +/** A `session.wait` still pending after this means the session is running. */ +const BUSY_PROBE_MS = 300; +/** Without an event stream: how many times an answer that is not in the context yet is re-checked. */ +const FALLBACK_ATTEMPTS = 40; + +/** + * Sessions currently waiting on a Plannotator plan review (`submit_plan` is a + * pending tool call). A real turn cannot run there and interrupting would kill + * the review, so every bridge reports `blocked` for them. + */ +const planReviewPending = new Map(); + +export function markPlanReviewPending(sessionID: string): () => void { + planReviewPending.set(sessionID, (planReviewPending.get(sessionID) ?? 0) + 1); + let released = false; + return () => { + if (released) return; + released = true; + const count = (planReviewPending.get(sessionID) ?? 1) - 1; + if (count <= 0) planReviewPending.delete(sessionID); + else planReviewPending.set(sessionID, count); + }; +} + +export function isPlanReviewPending(sessionID: string): boolean { + return planReviewPending.has(sessionID); +} + +const ID_CHARS = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"; +let lastIdTimestamp = 0; +let idCounter = 0; + +/** A message id in OpenCode's own ascending format (`Identifier.ascending`). */ +export function createOpenCodeMessageId(timestamp = Date.now()): string { + if (timestamp !== lastIdTimestamp) { + lastIdTimestamp = timestamp; + idCounter = 0; + } + idCounter++; + const value = BigInt(timestamp) * 0x1000n + BigInt(idCounter); + let time = ""; + for (let index = 0; index < 6; index++) { + time += Number((value >> BigInt(40 - 8 * index)) & 0xffn).toString(16).padStart(2, "0"); + } + const bytes = crypto.getRandomValues(new Uint8Array(14)); + let random = ""; + for (const byte of bytes) random += ID_CHARS[byte % 62]; + return `msg_${time}${random}`; +} + +export interface OpenCodeSessionBridgeOptions { + ctx: V2ContextLike; + sessionID: string; + /** Default: both. Plan review passes transient only. */ + modes?: { turn: boolean; transient: boolean }; + /** Test seams. */ + deliveryWatchdogMs?: number; + idleProbeMs?: number; + busyProbeMs?: number; + fallbackPollMs?: number; +} + +export interface OpenCodeSessionBridge extends SessionBridge { + /** Stop watching the session. A running turn is left alone. */ + dispose(): void; +} + +interface ActiveTurn { + messageID: string; + sink: SessionBridgeSink; + delivered: boolean; + cancelled: boolean; + finished: boolean; + answer: string; + /** Text blocks (assistantMessageID:ordinal) that streamed at least one delta. */ + streamed: Set; + needsSeparator: boolean; + watchdog: ReturnType | null; +} + +function isRecord(value: unknown): value is Record { + return !!value && typeof value === "object"; +} + +function errorText(error: unknown): string { + return error instanceof Error ? error.message : String(error); +} + +function isNotFound(error: unknown): boolean { + if (!isRecord(error)) return false; + const tag = Reflect.get(error, "_tag"); + if (typeof tag === "string" && /NotFound/i.test(tag)) return true; + return /not ?found/i.test(errorText(error)); +} + +/** The text of the assistant messages that follow `messageID` in a `session.context` result. */ +export function readAnswerAfter(context: unknown, messageID: string): string | undefined { + if (!Array.isArray(context)) return undefined; + const index = context.findIndex((message) => isRecord(message) && message.id === messageID); + if (index < 0) return undefined; + const texts: string[] = []; + for (const message of context.slice(index + 1)) { + if (!isRecord(message)) continue; + if (message.type === "user") break; + if (message.type !== "assistant" || !Array.isArray(message.content)) continue; + for (const part of message.content) { + if (isRecord(part) && part.type === "text" && typeof part.text === "string" && part.text) texts.push(part.text); + } + } + return texts.join("\n\n"); +} + +export function createOpenCodeSessionBridge(options: OpenCodeSessionBridgeOptions): OpenCodeSessionBridge { + const { ctx, sessionID } = options; + const modes = options.modes ?? { turn: true, transient: true }; + const deliveryWatchdogMs = options.deliveryWatchdogMs ?? DELIVERY_WATCHDOG_MS; + const idleProbeMs = options.idleProbeMs ?? IDLE_PROBE_MS; + const busyProbeMs = options.busyProbeMs ?? BUSY_PROBE_MS; + const fallbackPollMs = options.fallbackPollMs ?? 500; + const session = ctx.session; + + let gone = false; + let disposed = false; + /** Undefined until the first probe answers. */ + let running: boolean | undefined; + let lastStartedAt = 0; + let active: ActiveTurn | null = null; + const controller = new AbortController(); + let probeTimer: ReturnType | null = null; + let probing = false; + + const status = (): SessionBridgeStatus => { + if (gone || disposed) return "gone"; + if (isPlanReviewPending(sessionID)) return "blocked"; + return running ? "busy" : "ready"; + }; + + const markGone = () => { + if (gone) return; + gone = true; + const turn = active; + if (turn && !turn.finished) finishTurn(turn, () => turn.sink.error("gone")); + }; + + // Busy probe: `session.wait` resolves once the session is idle (at once if + // it already is). One outstanding call at a time; while it hangs the + // session is running, and it resolving IS the busy -> idle transition. + const probe = () => { + probeTimer = null; + if (disposed || gone || probing || typeof session?.wait !== "function") return; + probing = true; + const startedAt = Date.now(); + let settled = false; + const busyTimer = setTimeout(() => { + if (!settled) running = true; + }, busyProbeMs); + void session.wait({ sessionID }).then( + () => { + settled = true; + clearTimeout(busyTimer); + probing = false; + if (lastStartedAt <= startedAt) running = false; + scheduleProbe(idleProbeMs); + }, + (error) => { + settled = true; + clearTimeout(busyTimer); + probing = false; + if (isNotFound(error)) markGone(); + else scheduleProbe(idleProbeMs * 5); + }, + ); + }; + + const scheduleProbe = (ms: number) => { + if (disposed || gone || probeTimer) return; + probeTimer = setTimeout(probe, ms); + (probeTimer as { unref?: () => void }).unref?.(); + }; + + const clearWatchdog = (turn: ActiveTurn) => { + if (turn.watchdog) clearTimeout(turn.watchdog); + turn.watchdog = null; + }; + + const finishTurn = (turn: ActiveTurn, report: () => void) => { + if (turn.finished) return; + turn.finished = true; + clearWatchdog(turn); + if (active === turn) active = null; + report(); + }; + + const appendText = (turn: ActiveTurn, text: string) => { + if (!text) return; + let delta = text; + if (turn.needsSeparator) { + delta = `\n\n${delta}`; + turn.needsSeparator = false; + } + turn.answer += delta; + if (!turn.cancelled) turn.sink.delta(delta); + }; + + /** Read the answer from the session itself (event stream missing or silent). */ + const finalizeFromContext = async (turn: ActiveTurn): Promise => { + try { + const context = await session?.context?.({ sessionID }); + if (turn.finished) return; + const answer = readAnswerAfter(context, turn.messageID); + if (answer === undefined) { + finishTurn(turn, () => turn.sink.error("failed", "The question did not reach the session.")); + return; + } + if (!turn.answer && answer) appendText(turn, answer); + finishTurn(turn, () => (turn.cancelled ? turn.sink.error("aborted") : turn.sink.done(turn.answer || answer))); + } catch (error) { + if (turn.finished) return; + finishTurn(turn, () => turn.sink.error(isNotFound(error) ? "gone" : "failed", errorText(error))); + } + }; + + /** + * No event stream (#44788): wait until the session is idle and read the + * answer from its context. `wait` can resolve before our run even starts, + * so an answer that is not there yet is re-checked a bounded number of times. + */ + const settleWithoutEvents = async (turn: ActiveTurn): Promise => { + for (let attempt = 0; !turn.finished; attempt++) { + try { + await session?.wait?.({ sessionID }); + } catch { + // Read the context anyway. + } + if (turn.finished) return; + let context: unknown; + try { + context = await session?.context?.({ sessionID }); + } catch (error) { + finishTurn(turn, () => turn.sink.error(isNotFound(error) ? "gone" : "failed", errorText(error))); + return; + } + if (turn.finished) return; + const answer = readAnswerAfter(context, turn.messageID); + if (answer) { + appendText(turn, answer); + finishTurn(turn, () => (turn.cancelled ? turn.sink.error("aborted") : turn.sink.done(answer))); + return; + } + if (attempt >= FALLBACK_ATTEMPTS) { + finishTurn(turn, () => turn.sink.error("failed", "The session did not answer the question.")); + return; + } + await new Promise((resolve) => setTimeout(resolve, fallbackPollMs)); + } + }; + + const handleEvent = (event: unknown) => { + if (!isRecord(event) || typeof event.type !== "string") return; + const data = isRecord(event.data) ? event.data : undefined; + if (!data || data.sessionID !== sessionID) return; + const turn = active; + switch (event.type) { + case "session.deleted": + markGone(); + return; + case "session.execution.started": + lastStartedAt = Date.now(); + running = true; + return; + case "session.inbox.delivered": + if (turn && data.inboxID === turn.messageID) { + turn.delivered = true; + clearWatchdog(turn); + // Stopped before it reached the model: stop it now that it is ours. + if (turn.cancelled) void session?.interrupt?.({ sessionID }).catch(() => {}); + } + return; + case "session.text.started": + if (turn?.delivered && turn.answer) turn.needsSeparator = true; + return; + case "session.text.delta": + if (turn?.delivered && typeof data.delta === "string") { + turn.streamed.add(`${String(data.assistantMessageID)}:${String(data.ordinal)}`); + appendText(turn, data.delta); + } + return; + case "session.text.ended": + // Some providers deliver a block whole: replay it when nothing streamed. + if (turn?.delivered && typeof data.text === "string") { + const key = `${String(data.assistantMessageID)}:${String(data.ordinal)}`; + if (!turn.streamed.has(key)) appendText(turn, data.text); + } + return; + case "session.tool.input.started": + if (turn?.delivered && !turn.cancelled && typeof data.name === "string") turn.sink.tool?.(data.name); + return; + case "session.execution.succeeded": + case "session.execution.failed": + case "session.execution.interrupted": { + running = false; + if (!turn?.delivered) return; + if (turn.cancelled) { + finishTurn(turn, () => turn.sink.error("aborted")); + } else if (event.type === "session.execution.succeeded") { + finishTurn(turn, () => turn.sink.done(turn.answer)); + } else if (event.type === "session.execution.failed") { + const error = isRecord(data.error) && typeof data.error.message === "string" ? data.error.message : undefined; + finishTurn(turn, () => turn.sink.error("failed", error || "The session hit an error while answering.")); + } else { + finishTurn(turn, () => turn.sink.error("failed", "The turn was stopped in the session before it finished answering.")); + } + return; + } + } + }; + + let eventsAvailable = false; + const subscribe = ctx.event?.subscribe; + if (typeof subscribe === "function") { + eventsAvailable = true; + void (async () => { + try { + for await (const event of subscribe({ signal: controller.signal })) handleEvent(event); + } catch { + // Fall through: the stream is best effort (#44788). + } finally { + eventsAvailable = false; + } + })(); + } + probe(); + + const askTurn = (text: string, sink: SessionBridgeSink, signal: AbortSignal) => { + const prompt = session?.prompt; + if (typeof prompt !== "function") { + sink.error("failed", "This OpenCode host cannot receive a prompt from a plugin."); + return; + } + const turn: ActiveTurn = { + messageID: createOpenCodeMessageId(), + sink, + delivered: false, + cancelled: false, + finished: false, + answer: "", + streamed: new Set(), + needsSeparator: false, + watchdog: null, + }; + active = turn; + + signal.addEventListener( + "abort", + () => { + if (turn.finished || turn.cancelled) return; + turn.cancelled = true; + // Only ever interrupt a run that is answering OUR question. One not + // delivered yet is interrupted on delivery (see the event handler). + if (turn.delivered) { + void session?.interrupt?.({ sessionID }).catch(() => { + finishTurn(turn, () => turn.sink.error("aborted")); + }); + } + }, + { once: true }, + ); + + // A question that never shows up (event stream silent, or dropped by the + // host): once the session is idle, settle it from the session context. + const watchdog = () => { + turn.watchdog = null; + if (turn.finished) return; + if (running) { + turn.watchdog = setTimeout(watchdog, deliveryWatchdogMs); + return; + } + void finalizeFromContext(turn); + }; + turn.watchdog = setTimeout(watchdog, deliveryWatchdogMs); + + void Promise.resolve() + .then(() => + prompt({ + sessionID, + id: turn.messageID, + text, + // "steer": the provider only asks an idle session, where steer and + // queue differ in one thing that matters. Every OpenCode 2 command + // posts its session-URL notice as a pending STEER row (resume: + // false), and a queued question would wake the session with that + // notice promoted ALONE ahead of it, as its own model turn (the + // #1515 promotion rule; seen live on 2.0.22: the model went off to + // act on the notice while the question waited). Steering promotes + // the notice and the question as one batch, one turn. + delivery: "steer", + metadata: { source: PLANNOTATOR_ASK_SOURCE }, + }), + ) + .then( + () => { + // No event stream: wait for the run to finish, then read the answer. + if (!eventsAvailable) void settleWithoutEvents(turn); + }, + (error) => { + finishTurn(turn, () => sink.error(isNotFound(error) ? "gone" : "failed", errorText(error))); + if (isNotFound(error)) markGone(); + }, + ); + }; + + const askTransient = (text: string, sink: SessionBridgeSink, signal: AbortSignal) => { + const generate = session?.generate; + if (typeof generate !== "function") { + sink.error("blocked", "This OpenCode host cannot answer from the session's context."); + return; + } + // `generate` cannot be cancelled: an abort just drops the answer. + void Promise.resolve() + .then(() => generate({ sessionID, prompt: text })) + .then( + (result) => { + if (signal.aborted) return; + const answer = isRecord(result) && typeof result.text === "string" ? result.text.trim() : ""; + if (!answer) { + sink.error( + "failed", + "The session tried to use a tool instead of answering. Quick answers cannot run tools; ask again, or wait for the plan decision.", + ); + return; + } + sink.delta(answer); + sink.done(answer); + }, + (error) => { + if (signal.aborted) return; + if (isNotFound(error)) markGone(); + sink.error(isNotFound(error) ? "gone" : "failed", errorText(error)); + }, + ); + }; + + return { + host: "opencode", + modes, + status, + ask(req, sink, signal) { + if (gone || disposed) { + sink.error("gone"); + return; + } + if (req.mode === "transient") { + askTransient(req.text, sink, signal); + return; + } + if (active) { + sink.error("busy", "Another Plannotator question is still running in this session."); + return; + } + if (isPlanReviewPending(sessionID)) { + sink.error("blocked"); + return; + } + askTurn(req.text, sink, signal); + }, + async interrupt() { + // The provider never asks while blocked, but a plan review may have + // started since: interrupting now would kill it. + if (isPlanReviewPending(sessionID)) throw new Error("The session is waiting on a plan review."); + const interrupt = session?.interrupt; + if (typeof interrupt !== "function") throw new Error("This OpenCode host cannot interrupt a session from a plugin."); + await interrupt({ sessionID }); + // The execution events (or the next probe) report the session idle. + if (!eventsAvailable) { + running = false; + scheduleProbe(0); + } + }, + dispose() { + if (disposed) return; + disposed = true; + controller.abort(); + if (probeTimer) clearTimeout(probeTimer); + probeTimer = null; + const turn = active; + if (turn && !turn.delivered) finishTurn(turn, () => turn.sink.error("gone")); + }, + }; +} diff --git a/apps/opencode-plugin/package.json b/apps/opencode-plugin/package.json index 979170a555..38332f20f7 100644 --- a/apps/opencode-plugin/package.json +++ b/apps/opencode-plugin/package.json @@ -46,6 +46,7 @@ "devDependencies": { "@opencode-ai/plugin": "1.18.32", "@opencode/plugin": "2.0.14", + "@plannotator/ai": "workspace:*", "@plannotator/server": "workspace:*", "@plannotator/shared": "workspace:*" }, diff --git a/apps/opencode-plugin/server.ts b/apps/opencode-plugin/server.ts index 1bf594deb9..d8d155d58b 100644 --- a/apps/opencode-plugin/server.ts +++ b/apps/opencode-plugin/server.ts @@ -31,6 +31,8 @@ import { type V2ContextLike, } from "./v2-client"; import { executeSubmitPlan } from "./submit-plan-executor"; +import type { SessionBridge } from "@plannotator/ai/session-bridge"; +import { createOpenCodeSessionBridge, markPlanReviewPending } from "./opencode-session-bridge"; import type { PlanEdit } from "./plan-edits"; import { getPlanningPrompt } from "./planning-prompt"; @@ -63,6 +65,7 @@ type EmbeddedRuntimeModule = { timeoutSeconds: number | null; abortSignal?: AbortSignal; logReady: (url: string, isRemote: boolean, port: number) => void; + sessionBridge?: SessionBridge; }) => Promise; }; @@ -215,6 +218,18 @@ const serverPlugin = { getAgents, sessionID: toolContext.sessionID, }); + // While the plan waits, the session is inside this tool call: a real + // turn cannot run (and interrupting would kill the review), so every + // bridge on this session reports `blocked`, and the plan review's own + // bridge answers from context only ("Quick answer", session.generate). + const releasePlanPending = markPlanReviewPending(toolContext.sessionID); + const planBridge = typeof v2.session?.generate === "function" + ? createOpenCodeSessionBridge({ + ctx: v2, + sessionID: toolContext.sessionID, + modes: { turn: false, transient: true }, + }) + : undefined; try { const result = await executeSubmitPlan({ edits: getPlanEdits(input), @@ -233,6 +248,7 @@ const serverPlugin = { timeoutSeconds: getPlanTimeoutSeconds(), directory, bridge, + sessionBridge: planBridge, }), resolveTargetAgent: async ({ requestedAgent }) => await switchV2SessionAgent({ ctx: v2, @@ -249,6 +265,8 @@ const serverPlugin = { return { content: result }; } finally { + planBridge?.dispose(); + releasePlanPending(); // Same call as `runNativeCommand`: closes the session-URL notice // watch for a review that delivered no prompt of its own. client.dispose(); @@ -357,6 +375,8 @@ async function runPlanReview(input: { abortSignal?: AbortSignal; directory: string; bridge: OpenCodeBridgeContext; + /** "Ask this session" while the plan waits (transient answers only). */ + sessionBridge?: SessionBridge; }): Promise { if (input.runtime === "embedded" && !hasEmbeddedRuntime()) { throw new Error('runtime "embedded" requires a Bun-hosted OpenCode plugin runtime. Use runtime "auto" or "cli" with this OpenCode host.'); @@ -375,6 +395,7 @@ async function runPlanReview(input: { timeoutSeconds: input.timeoutSeconds, abortSignal: input.abortSignal, logReady: createPlanReadyNotifier(input.client), + sessionBridge: input.sessionBridge, }); } catch (error) { if (input.runtime === "embedded") throw error; @@ -389,6 +410,7 @@ async function runPlanReview(input: { timeoutSeconds: input.timeoutSeconds, abortSignal: input.abortSignal, bridge: input.bridge, + sessionBridge: input.sessionBridge, }); } diff --git a/apps/opencode-plugin/session-bridge-cli.test.ts b/apps/opencode-plugin/session-bridge-cli.test.ts new file mode 100644 index 0000000000..8fa8531128 --- /dev/null +++ b/apps/opencode-plugin/session-bridge-cli.test.ts @@ -0,0 +1,114 @@ +import { describe, expect, mock, test } from "bun:test"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import path from "node:path"; +import { handleCliCommand } from "./cli-bridge"; +import type { SessionBridge } from "@plannotator/ai/session-bridge"; + +const AI_INDEX = path.join(import.meta.dir, "..", "..", "packages", "ai", "index.ts"); + +describe("Ask this session through the CLI child (pull bridge)", () => { + // The CLI runs as a separate process, so the only way a question reaches the + // OpenCode session is: the plugin hands the child a token, learns its port + // from the ready file, and long-polls it. This stub CLI is a real pull-bridge + // server that asks one question and records the answer it gets back. + test.skipIf(process.platform === "win32")("the plugin answers the child's question from the invoking session", async () => { + const root = mkdtempSync(path.join(tmpdir(), "plannotator-opencode-bridge-")); + const binary = path.join(root, "cli.ts"); + const out = path.join(root, "out.json"); + const doc = path.join(root, "notes.md"); + writeFileSync(doc, "# Notes\n"); + writeFileSync(binary, `#!/usr/bin/env bun +import { appendFileSync, writeFileSync } from "node:fs"; +import { createPullSessionBridge, takePullSessionBridgeConfig, SessionBridgeProvider } from ${JSON.stringify(AI_INDEX)}; +const config = takePullSessionBridgeConfig(process.env); +if (!config) { + writeFileSync(${JSON.stringify(out)}, JSON.stringify({ config: null })); + console.log(JSON.stringify({ decision: "dismissed" })); + process.exit(0); +} +const pull = createPullSessionBridge(config); +const server = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: (req) => pull.handle(req) ?? new Response("nf", { status: 404 }) }); +appendFileSync(process.env.PLANNOTATOR_READY_FILE, JSON.stringify({ url: "http://localhost:" + server.port, isRemote: false, port: server.port }) + "\\n"); +const provider = new SessionBridgeProvider(pull.bridge); +const session = await provider.createSession({ context: { mode: "annotate", annotate: { content: "# Notes", filePath: "notes.md" } } }); +const messages = []; +for await (const message of session.query("What is this file?")) messages.push(message); +writeFileSync(${JSON.stringify(out)}, JSON.stringify({ config: { host: config.host, modes: config.modes, tokenLength: config.token.length }, tokenLeft: process.env.PLANNOTATOR_SESSION_BRIDGE_TOKEN ?? null, messages })); +pull.dispose(); +server.stop(true); +console.log(JSON.stringify({ decision: "dismissed" })); +`, { mode: 0o755 }); + + const asked: string[] = []; + const dispose = mock(() => {}); + const hostBridge: SessionBridge & { dispose: () => void } = { + host: "opencode", + modes: { turn: true, transient: true }, + status: () => "ready", + ask(req, sink) { + asked.push(req.text); + setTimeout(() => { + sink.delta("A notes "); + sink.delta("file."); + sink.done("A notes file."); + }, 5); + }, + dispose, + }; + const client = { + app: { log: mock((_entry: { message: string }) => {}) }, + session: { prompt: mock(async (_input: unknown) => ({})) }, + }; + const previous = process.env.PLANNOTATOR_BIN; + try { + process.env.PLANNOTATOR_BIN = binary; + await handleCliCommand({ + command: "plannotator-annotate", + client, + sessionId: "ses_1", + cwd: root, + rawArgs: doc, + createSessionBridge: () => hostBridge, + }); + const result = JSON.parse(readFileSync(out, "utf-8")); + expect(result.config).toEqual({ host: "opencode", modes: { turn: true, transient: true }, tokenLength: 43 }); + // The child scrubs the token so nothing it spawns inherits it. + expect(result.tokenLeft).toBeNull(); + expect(asked).toHaveLength(1); + expect(asked[0]).toContain("What is this file?"); + const text = result.messages.filter((m: any) => m.type === "text_delta").map((m: any) => m.delta).join(""); + expect(text).toBe("A notes file."); + expect(result.messages.at(-1)).toMatchObject({ type: "result", result: "A notes file." }); + expect(dispose).toHaveBeenCalledTimes(1); + } finally { + if (previous === undefined) delete process.env.PLANNOTATOR_BIN; + else process.env.PLANNOTATOR_BIN = previous; + rmSync(root, { recursive: true, force: true }); + } + }, 20_000); + + test.skipIf(process.platform === "win32")("without a bridge the child gets no token", async () => { + const root = mkdtempSync(path.join(tmpdir(), "plannotator-opencode-nobridge-")); + const binary = path.join(root, "cli.ts"); + const out = path.join(root, "out.json"); + const doc = path.join(root, "notes.md"); + writeFileSync(doc, "# Notes\n"); + writeFileSync(binary, `#!/usr/bin/env bun +import { writeFileSync } from "node:fs"; +writeFileSync(${JSON.stringify(out)}, JSON.stringify({ token: process.env.PLANNOTATOR_SESSION_BRIDGE_TOKEN ?? null })); +console.log(JSON.stringify({ decision: "dismissed" })); +`, { mode: 0o755 }); + const client = { app: { log: mock((_entry: { message: string }) => {}) }, session: { prompt: mock(async () => ({})) } }; + const previous = process.env.PLANNOTATOR_BIN; + try { + process.env.PLANNOTATOR_BIN = binary; + await handleCliCommand({ command: "plannotator-annotate", client, sessionId: "ses_1", cwd: root, rawArgs: doc }); + expect(JSON.parse(readFileSync(out, "utf-8"))).toEqual({ token: null }); + } finally { + if (previous === undefined) delete process.env.PLANNOTATOR_BIN; + else process.env.PLANNOTATOR_BIN = previous; + rmSync(root, { recursive: true, force: true }); + } + }, 20_000); +}); diff --git a/apps/opencode-plugin/v2-client.ts b/apps/opencode-plugin/v2-client.ts index 617f9ae70f..044faf4df2 100644 --- a/apps/opencode-plugin/v2-client.ts +++ b/apps/opencode-plugin/v2-client.ts @@ -12,7 +12,20 @@ import type { OpenCodeBridgeAgent } from "./cli-bridge"; /** The subset of the V2 session domain this plugin touches. */ export interface V2SessionDomain { get?: (input: { sessionID: string }) => Promise<{ location?: { directory?: string } }>; - prompt?: (input: { sessionID: string; text: string; delivery?: unknown }) => Promise; + prompt?: (input: { + sessionID: string; + text: string; + delivery?: unknown; + /** Our own inbox/message id (`msg_…`), so its delivery event can be matched. */ + id?: string; + metadata?: Record; + }) => Promise; + /** "Ask this session" only: answer from the session's context without a turn. */ + generate?: (input: { sessionID: string; prompt: string }) => Promise; + /** Stops the session's whole current execution. */ + interrupt?: (input: { sessionID: string; resume?: boolean }) => Promise; + /** Resolves once the session is idle (at once when it already is). */ + wait?: (input: { sessionID: string }) => Promise; switchAgent?: (input: { sessionID: string; agent: string }) => Promise; switchModel?: (input: { sessionID: string; diff --git a/apps/pi-extension/server/ai-runtime.ts b/apps/pi-extension/server/ai-runtime.ts index 010e979868..1a30aca493 100644 --- a/apps/pi-extension/server/ai-runtime.ts +++ b/apps/pi-extension/server/ai-runtime.ts @@ -5,6 +5,7 @@ import { Readable } from "node:stream"; import { isAIEndpointPath } from "../generated/ai/endpoints.ts"; import { resolveCommandFromWhichOutput } from "../generated/ai/providers/command-path.ts"; import type { SessionBridge } from "../generated/ai/session-bridge.ts"; +import type { PullSessionBridgeConfig } from "../generated/ai/session-bridge-pull.ts"; import { isLoopbackHostHeader } from "../generated/loopback-host.ts"; import { handleApiNotFound, json, toWebRequest } from "./helpers.ts"; @@ -24,6 +25,13 @@ export interface CreatePiAIRuntimeOptions { * (DNS-rebinding guard). Undefined (not bound yet) refuses bridge requests. */ getServerPort?: () => number | undefined; + /** + * "Ask this session" over HTTP (session-bridge-pull.ts) for a host that + * cannot call this process directly. Pi itself always passes an in-process + * `sessionBridge`; this exists so both runtimes serve the same protocol. + * Ignored when `sessionBridge` is given. Callers keep it off in remote mode. + */ + pullSessionBridge?: PullSessionBridgeConfig; } function whichCmd(cmd: string): string | null { @@ -128,7 +136,11 @@ export async function createPiAIRuntime(options: CreatePiAIRuntimeOptions = {}): } // Registered last so the server default is unchanged; the client prefers it. - const bridgeProvider = options.sessionBridge ? new ai.SessionBridgeProvider(options.sessionBridge) : null; + const pullBridge = !options.sessionBridge && options.pullSessionBridge + ? ai.createPullSessionBridge(options.pullSessionBridge) + : null; + const sessionBridge = options.sessionBridge ?? pullBridge?.bridge; + const bridgeProvider = sessionBridge ? new ai.SessionBridgeProvider(sessionBridge) : null; if (bridgeProvider) registry.register(bridgeProvider, ai.SESSION_BRIDGE_PROVIDER_NAME); return { @@ -142,6 +154,7 @@ export async function createPiAIRuntime(options: CreatePiAIRuntimeOptions = {}): beforeProviderSession: discovery.beforeProviderSession, authorizeSessionBridgeRequest: (req: Request) => isLoopbackHostHeader(req.headers.get("host"), options.getServerPort?.()), + ...(pullBridge ? { pullBridge } : {}), }), dispose: () => { // Detach first: tearing the sessions down must not stop a turn the @@ -149,6 +162,7 @@ export async function createPiAIRuntime(options: CreatePiAIRuntimeOptions = {}): bridgeProvider?.detach(); sessionManager.disposeAll(); registry.disposeAll(); + pullBridge?.dispose(); }, }; } catch { diff --git a/apps/pi-extension/vendor.sh b/apps/pi-extension/vendor.sh index 35aafce18d..dc34ce462d 100755 --- a/apps/pi-extension/vendor.sh +++ b/apps/pi-extension/vendor.sh @@ -124,7 +124,7 @@ for f in ai-context model-catalog; do | cat - "../../packages/core/$f.ts" > "generated/ai/$f.ts" done -for f in index types provider session-manager endpoints context base-session session-bridge; do +for f in index types provider session-manager endpoints context base-session session-bridge session-bridge-pull; do src="../../packages/ai/$f.ts" printf '// @generated — DO NOT EDIT. Source: packages/ai/%s.ts\n' "$f" | cat - "$src" \ | sed -e "s|from ['\"]@plannotator/core/ai-context['\"]|from './ai-context.ts'|g" \ diff --git a/bun.lock b/bun.lock index 33c7d64706..feea84a111 100644 --- a/bun.lock +++ b/bun.lock @@ -89,6 +89,7 @@ "devDependencies": { "@opencode-ai/plugin": "1.18.32", "@opencode/plugin": "2.0.14", + "@plannotator/ai": "workspace:*", "@plannotator/server": "workspace:*", "@plannotator/shared": "workspace:*", }, diff --git a/packages/ai/endpoints.ts b/packages/ai/endpoints.ts index 2641775850..89dd67d11b 100644 --- a/packages/ai/endpoints.ts +++ b/packages/ai/endpoints.ts @@ -11,6 +11,8 @@ * POST /api/ai/abort — Abort the current query * GET /api/ai/sessions — List active sessions * GET /api/ai/capabilities — Check if AI features are available + * POST /api/ai/bridge/poll — "Ask this session" pull bridge: host long-poll (session-bridge-pull.ts) + * POST /api/ai/bridge/event — "Ask this session" pull bridge: host progress events */ import { resolveModelChoice } from "@plannotator/core/model-catalog"; @@ -18,6 +20,7 @@ import type { AIContext, AIMessage, AIProvider, CreateSessionOptions } from "./t import type { ProviderRegistry } from "./provider.ts"; import type { SessionManager } from "./session-manager.ts"; import { SessionBridgeProvider, SessionBridgeSession } from "./session-bridge.ts"; +import { SESSION_BRIDGE_EVENT_PATH, SESSION_BRIDGE_POLL_PATH } from "./session-bridge-pull.ts"; /** Canonical paths handled by the shared AI endpoint runtime. */ export const AI_ENDPOINT_PATHS = [ @@ -27,8 +30,18 @@ export const AI_ENDPOINT_PATHS = [ "/api/ai/abort", "/api/ai/permission", "/api/ai/sessions", + "/api/ai/bridge/poll", + "/api/ai/bridge/event", ] as const; +/** + * Endpoints whose requests legitimately stay open (SSE answers, the bridge + * long-poll): servers with a per-request idle timeout lift it for these. + */ +export function isLongLivedAIEndpointPath(path: string): boolean { + return path === "/api/ai/query" || path === SESSION_BRIDGE_POLL_PATH; +} + /** A path handled by the shared AI endpoint runtime. */ export type AIEndpointPath = (typeof AI_ENDPOINT_PATHS)[number]; @@ -105,6 +118,13 @@ export interface AIEndpointDeps { * answers without a guard. Other providers never consult it. */ authorizeSessionBridgeRequest?: (req: Request) => boolean; + /** + * "Ask this session" pull bridge (session-bridge-pull.ts), present when a + * host that runs this server as a separate process handed it a bridge + * token. Its two endpoints answer 404 without it, and are also gated by + * `authorizeSessionBridgeRequest` (loopback Host) before the token check. + */ + pullBridge?: { handle(req: Request): Promise | null }; } /** Error code for a bridge request refused by `authorizeSessionBridgeRequest`. */ @@ -221,8 +241,17 @@ export function createAIEndpoints(deps: AIEndpointDeps) { beforeCapabilities, beforeProviderSession, authorizeSessionBridgeRequest, + pullBridge, } = deps; + const handlePullBridge = async (req: Request): Promise => { + if (!pullBridge) { + return Response.json({ error: "No session bridge on this server.", code: "session_bridge_unavailable" }, { status: 404 }); + } + if (!authorizeSessionBridgeRequest?.(req)) return sessionBridgeForbidden(); + return (await pullBridge.handle(req)) ?? Response.json({ error: "Not found" }, { status: 404 }); + }; + return { "/api/ai/capabilities": async (req: Request) => { await beforeCapabilities?.(); @@ -498,6 +527,9 @@ export function createAIEndpoints(deps: AIEndpointDeps) { })) ); }, + + [SESSION_BRIDGE_POLL_PATH]: handlePullBridge, + [SESSION_BRIDGE_EVENT_PATH]: handlePullBridge, } as const; } diff --git a/packages/ai/index.ts b/packages/ai/index.ts index ba58927234..43de727036 100644 --- a/packages/ai/index.ts +++ b/packages/ai/index.ts @@ -99,6 +99,7 @@ export { SESSION_BRIDGE_PROVIDER_NAME, SESSION_BRIDGE_ERROR, SESSION_ASK_HEADER, + SESSION_ASK_TRANSIENT_NOTE, formatSessionAskText, sessionBridgeLabel, } from "./session-bridge.ts"; @@ -113,6 +114,26 @@ export type { SessionBridgeStatus, } from "./session-bridge.ts"; +// "Ask this session" pull bridge (hosts that run the server as a separate process) +export { + createPullSessionBridge, + takePullSessionBridgeConfig, + parseSessionBridgeModes, + SESSION_BRIDGE_POLL_PATH, + SESSION_BRIDGE_EVENT_PATH, + SESSION_BRIDGE_TOKEN_ENV, + SESSION_BRIDGE_HOST_ENV, + SESSION_BRIDGE_MODES_ENV, + SESSION_BRIDGE_MAX_POLL_MS, +} from "./session-bridge-pull.ts"; +export type { + BridgeCommand, + BridgeHostEvent, + PullSessionBridge, + PullSessionBridgeConfig, + PullSessionBridgeOptions, +} from "./session-bridge-pull.ts"; + // Session manager export { SessionManager } from "./session-manager.ts"; export type { SessionEntry, SessionManagerOptions } from "./session-manager.ts"; @@ -123,6 +144,7 @@ export { createBestEffortOnce, createDeferredModelDiscovery, isAIEndpointPath, + isLongLivedAIEndpointPath, SESSION_BRIDGE_FORBIDDEN_HOST, } from "./endpoints.ts"; export type { diff --git a/packages/ai/package.json b/packages/ai/package.json index 2d82bd2424..6a07fd0db8 100644 --- a/packages/ai/package.json +++ b/packages/ai/package.json @@ -11,6 +11,8 @@ "./session-manager": "./session-manager.ts", "./endpoints": "./endpoints.ts", "./session-bridge": "./session-bridge.ts", + "./session-bridge-pull": "./session-bridge-pull.ts", + "./session-bridge-pull-client": "./session-bridge-pull-client.ts", "./providers/claude-agent-sdk": "./providers/claude-agent-sdk.ts", "./providers/codex-app-server": "./providers/codex-app-server.ts", "./providers/command-path": "./providers/command-path.ts", diff --git a/packages/ai/session-bridge-pull-client.ts b/packages/ai/session-bridge-pull-client.ts new file mode 100644 index 0000000000..548db4a4a3 --- /dev/null +++ b/packages/ai/session-bridge-pull-client.ts @@ -0,0 +1,267 @@ +/** + * "Ask this session" pull bridge, host half: drives an in-process + * `SessionBridge` against a Plannotator server running in ANOTHER process. + * + * The host (e.g. the OpenCode plugin) implements `SessionBridge` over its own + * session API exactly as an in-process host would, starts the server process + * with the bridge token in its environment (`SESSION_BRIDGE_TOKEN_ENV`), and + * once the server is listening calls `runPullSessionBridgeClient`. The client + * long-polls `/api/ai/bridge/poll`, runs the commands it receives through the + * bridge, and posts progress to `/api/ai/bridge/event`. Protocol: + * session-bridge-pull.ts. + * + * It stops when the signal aborts, when the server says it is closing, on an + * auth or not-found answer, or after the server stops answering at all. It + * never stops a question already running in the session when it stops: the + * reviewer's decision goes to that same session next. + */ + +import type { SessionBridge, SessionBridgeErrorCode, SessionBridgeStatus } from "./session-bridge.ts"; +import type { BridgeCommand, BridgeHostEvent } from "./session-bridge-pull.ts"; +import { SESSION_BRIDGE_EVENT_PATH, SESSION_BRIDGE_POLL_PATH } from "./session-bridge-pull.ts"; + +export interface PullSessionBridgeClientOptions { + /** Server origin, e.g. `http://127.0.0.1:4321`. Always a loopback URL. */ + baseUrl: string; + token: string; + bridge: SessionBridge; + signal: AbortSignal; + /** How long each poll may wait on the server. Default 25s. */ + pollWaitMs?: number; + /** How often status changes are pushed between polls. Default 500ms. */ + statusIntervalMs?: number; + /** Deltas are batched for this long before posting. Default 40ms. */ + deltaFlushMs?: number; + /** Consecutive failed polls before giving up. Default 6 (backoff 0.5s..4s). */ + maxFailures?: number; + fetch?: typeof fetch; + log?: (message: string) => void; +} + +interface HostAsk { + controller: AbortController; + finished: boolean; +} + +function sleep(ms: number, signal: AbortSignal): Promise { + return new Promise((resolve) => { + if (signal.aborted) return resolve(); + const timer = setTimeout(done, ms); + function done() { + clearTimeout(timer); + signal.removeEventListener("abort", done); + resolve(); + } + signal.addEventListener("abort", done, { once: true }); + }); +} + +function readStatus(bridge: SessionBridge): SessionBridgeStatus { + try { + return bridge.status(); + } catch { + return "gone"; + } +} + +export async function runPullSessionBridgeClient(options: PullSessionBridgeClientOptions): Promise { + const doFetch = options.fetch ?? fetch; + const base = options.baseUrl.replace(/\/+$/, ""); + const pollWaitMs = options.pollWaitMs ?? 25_000; + const maxFailures = options.maxFailures ?? 6; + const deltaFlushMs = options.deltaFlushMs ?? 40; + const { bridge, signal } = options; + const log = options.log ?? (() => {}); + const headers = { "content-type": "application/json", authorization: `Bearer ${options.token}` }; + + /** Questions this host has seen (commands are re-sent until acknowledged). */ + const asks = new Map(); + const interrupts = new Set(); + let stopped = false; + + // One ordered outbox: events reach the server in the order they happened. + let outbox: BridgeHostEvent[] = []; + let sending: Promise = Promise.resolve(); + let flushTimer: ReturnType | null = null; + + const post = async (events: BridgeHostEvent[]): Promise => { + if (events.length === 0) return; + try { + const res = await doFetch(`${base}${SESSION_BRIDGE_EVENT_PATH}`, { + method: "POST", + headers, + body: JSON.stringify(events.length === 1 ? events[0] : { events }), + }); + if (res.status === 409) { + // The server no longer runs a question we are answering (the reviewer + // stopped it before we confirmed it): stop ours. + for (const event of events) { + if ("askId" in event) stopAsk(event.askId); + } + } + await res.body?.cancel().catch(() => {}); + } catch (error) { + log(`[Plannotator] Session bridge event failed: ${error instanceof Error ? error.message : String(error)}`); + } + }; + + const flushOutbox = (): Promise => { + if (flushTimer) clearTimeout(flushTimer); + flushTimer = null; + const batch = outbox; + outbox = []; + sending = sending.then(() => post(batch)); + return sending; + }; + + const emit = (event: BridgeHostEvent, immediate = true) => { + // Coalesce consecutive deltas of the same question. + const last = outbox[outbox.length - 1]; + if (event.type === "delta" && last?.type === "delta" && last.askId === event.askId) { + last.text += event.text; + } else { + outbox.push(event.type === "delta" ? { ...event } : event); + } + if (immediate) void flushOutbox(); + else if (!flushTimer) flushTimer = setTimeout(() => void flushOutbox(), deltaFlushMs); + }; + + const stopAsk = (askId: string) => { + const ask = asks.get(askId); + if (ask && !ask.finished) ask.controller.abort(); + }; + + const runAsk = (command: Extract) => { + if (asks.has(command.askId)) return; + const controller = new AbortController(); + const ask: HostAsk = { controller, finished: false }; + asks.set(command.askId, ask); + emit({ type: "started", askId: command.askId }); + const finish = (event: BridgeHostEvent) => { + if (ask.finished) return; + ask.finished = true; + emit(event); + }; + try { + bridge.ask( + { askId: command.askId, text: command.text, mode: command.mode }, + { + delta: (text) => { + if (!ask.finished && text) emit({ type: "delta", askId: command.askId, text }, false); + }, + tool: (name) => { + if (!ask.finished && name) emit({ type: "tool", askId: command.askId, name }); + }, + done: (answer) => finish({ type: "done", askId: command.askId, answer }), + error: (code: SessionBridgeErrorCode, message?: string) => + finish({ type: "error", askId: command.askId, code, ...(message ? { message } : {}) }), + }, + controller.signal, + ); + } catch (error) { + finish({ type: "error", askId: command.askId, code: "failed", message: error instanceof Error ? error.message : String(error) }); + } + }; + + const runInterrupt = async (interruptId: string) => { + if (interrupts.has(interruptId)) return; + interrupts.add(interruptId); + if (!bridge.interrupt) { + emit({ type: "interrupted", interruptId, ok: false, message: "This session cannot be interrupted." }); + return; + } + try { + await bridge.interrupt(); + emit({ type: "interrupted", interruptId, ok: true }); + } catch (error) { + emit({ type: "interrupted", interruptId, ok: false, message: error instanceof Error ? error.message : String(error) }); + } + }; + + const handleCommand = (command: BridgeCommand) => { + switch (command.type) { + case "ask": + runAsk(command); + break; + case "cancel": { + const ask = asks.get(command.askId); + if (!ask) { + // Never started here: confirm so the server frees the slot. + emit({ type: "error", askId: command.askId, code: "aborted" }); + } else if (ask.finished) { + // Already answered: the server only needs to hear it again. + emit({ type: "error", askId: command.askId, code: "aborted" }); + } else { + ask.controller.abort(); + } + break; + } + case "interrupt": + void runInterrupt(command.interruptId); + break; + } + }; + + // Push status changes between polls so a busy -> ready transition is seen + // within a fraction of a second, not at the next poll. + let lastStatus = readStatus(bridge); + const statusTimer = setInterval(() => { + const status = readStatus(bridge); + if (status === lastStatus) return; + lastStatus = status; + emit({ type: "status", status }); + }, options.statusIntervalMs ?? 500); + (statusTimer as { unref?: () => void }).unref?.(); + + let failures = 0; + try { + while (!signal.aborted && !stopped) { + let res: Response; + try { + lastStatus = readStatus(bridge); + res = await doFetch(`${base}${SESSION_BRIDGE_POLL_PATH}`, { + method: "POST", + headers, + body: JSON.stringify({ status: lastStatus, modes: bridge.modes, waitMs: pollWaitMs }), + signal, + }); + } catch (error) { + if (signal.aborted) break; + failures += 1; + if (failures >= maxFailures) { + log(`[Plannotator] Session bridge stopped: the Plannotator server is not answering (${error instanceof Error ? error.message : String(error)}).`); + break; + } + await sleep(Math.min(4_000, 500 * 2 ** (failures - 1)), signal); + continue; + } + if (res.status === 401 || res.status === 403 || res.status === 404 || res.status === 405 || res.status === 503) { + // Wrong token, not loopback, an older binary with no bridge, or AI disabled. + await res.body?.cancel().catch(() => {}); + if (res.status !== 404 && res.status !== 503) log(`[Plannotator] Session bridge refused (HTTP ${res.status}).`); + break; + } + if (!res.ok) { + await res.body?.cancel().catch(() => {}); + failures += 1; + if (failures >= maxFailures) break; + await sleep(Math.min(4_000, 500 * 2 ** (failures - 1)), signal); + continue; + } + failures = 0; + let body: { commands?: BridgeCommand[]; closing?: boolean } = {}; + try { + body = (await res.json()) as typeof body; + } catch { + // Treat as an empty answer. + } + for (const command of Array.isArray(body.commands) ? body.commands : []) { + if (command && typeof command === "object" && typeof command.type === "string") handleCommand(command); + } + if (body.closing) stopped = true; + } + } finally { + clearInterval(statusTimer); + await flushOutbox().catch(() => {}); + } +} diff --git a/packages/ai/session-bridge-pull.test.ts b/packages/ai/session-bridge-pull.test.ts new file mode 100644 index 0000000000..ac18923084 --- /dev/null +++ b/packages/ai/session-bridge-pull.test.ts @@ -0,0 +1,347 @@ +import { afterEach, describe, expect, test } from "bun:test"; +import { createAIEndpoints } from "./endpoints.ts"; +import { ProviderRegistry } from "./provider.ts"; +import { SessionManager } from "./session-manager.ts"; +import { + SESSION_ASK_HEADER, + SESSION_ASK_TRANSIENT_NOTE, + SESSION_BRIDGE_ERROR, + SESSION_BRIDGE_PROVIDER_NAME, + SessionBridgeProvider, + type SessionBridge, + type SessionBridgeAskRequest, + type SessionBridgeSink, + type SessionBridgeStatus, +} from "./session-bridge.ts"; +import { + createPullSessionBridge, + takePullSessionBridgeConfig, + SESSION_BRIDGE_EVENT_PATH, + SESSION_BRIDGE_POLL_PATH, + type PullSessionBridgeOptions, +} from "./session-bridge-pull.ts"; +import { runPullSessionBridgeClient } from "./session-bridge-pull-client.ts"; +import type { AIContext, AIMessage } from "./types.ts"; + +const TOKEN = "t".repeat(43); +const HOST = "127.0.0.1:4321"; +const CONTEXT: AIContext = { mode: "annotate", annotate: { content: "# Doc", filePath: "/repo/notes.md" } }; + +interface HostAsk { + req: SessionBridgeAskRequest; + sink: SessionBridgeSink; + signal: AbortSignal; +} + +/** The host side: an in-process bridge the test drives by hand. */ +function fakeHost(initial: SessionBridgeStatus = "ready", modes = { turn: true, transient: false }) { + let status = initial; + const asks: HostAsk[] = []; + let interrupts = 0; + const bridge: SessionBridge = { + host: "opencode", + modes, + status: () => status, + ask(req, sink, signal) { + asks.push({ req, sink, signal }); + }, + interrupt() { + interrupts += 1; + status = "ready"; + }, + }; + return { + bridge, + asks, + get interrupts() { + return interrupts; + }, + setStatus(next: SessionBridgeStatus) { + status = next; + }, + }; +} + +async function waitFor(predicate: () => boolean, timeoutMs = 3000): Promise { + const start = Date.now(); + while (!predicate()) { + if (Date.now() - start > timeoutMs) throw new Error("timed out waiting"); + await new Promise((resolve) => setTimeout(resolve, 5)); + } +} + +function collect(iterable: AsyncIterable) { + const messages: AIMessage[] = []; + const done = (async () => { + for await (const message of iterable) messages.push(message); + })(); + return { messages, done }; +} + +const cleanups: Array<() => void> = []; +afterEach(() => { + for (const cleanup of cleanups.splice(0)) cleanup(); +}); + +/** + * A Plannotator server's AI runtime with a pull bridge, plus a host process + * simulated by the real pull client talking to it through `fetch`. + */ +function setup(options: Partial = {}, host = fakeHost()) { + const pull = createPullSessionBridge({ + token: TOKEN, + host: "opencode", + modes: host.bridge.modes, + connectTimeoutMs: 2_000, + goneAfterMs: 2_000, + resendAfterMs: 50, + ...options, + }); + const registry = new ProviderRegistry(); + const provider = new SessionBridgeProvider(pull.bridge, { pollIntervalMs: 5 }); + registry.register(provider, SESSION_BRIDGE_PROVIDER_NAME); + const endpoints = createAIEndpoints({ + registry, + sessionManager: new SessionManager(), + authorizeSessionBridgeRequest: (req) => req.headers.get("host") === HOST, + pullBridge: pull, + }); + const call = (path: string, init: RequestInit = {}, headers: Record = {}) => + (endpoints as Record Promise>)[path]( + new Request(`http://${HOST}${path}`, { ...init, headers: { host: HOST, ...(init.headers as Record), ...headers } }), + ); + const fetchShim = (async (url: string | URL | Request, init?: RequestInit) => + call(new URL(String(url)).pathname, init ?? {})) as typeof fetch; + const controller = new AbortController(); + const startHost = (overrides: { token?: string } = {}) => + runPullSessionBridgeClient({ + baseUrl: `http://${HOST}`, + token: overrides.token ?? TOKEN, + bridge: host.bridge, + signal: controller.signal, + pollWaitMs: 100, + statusIntervalMs: 10, + deltaFlushMs: 5, + maxFailures: 2, + fetch: fetchShim, + }); + cleanups.push(() => { + controller.abort(); + pull.dispose(); + }); + return { pull, provider, host, call, startHost, stopHost: () => controller.abort() }; +} + +describe("pull session bridge", () => { + test("a question reaches the host through the poll and the answer streams back", async () => { + const { provider, host, startHost } = setup(); + void startHost(); + const session = await provider.createSession({ context: CONTEXT }); + const run = collect(session.query("Why this change?")); + + await waitFor(() => host.asks.length === 1); + const ask = host.asks[0]; + expect(ask.req.mode).toBe("turn"); + expect(ask.req.text.startsWith(SESSION_ASK_HEADER)).toBe(true); + expect(ask.req.text).toContain("Why this change?"); + + ask.sink.delta("Because "); + ask.sink.tool?.("read"); + ask.sink.delta("of #12."); + ask.sink.done("Because of #12."); + await run.done; + + const text = run.messages.filter((m) => m.type === "text_delta").map((m) => (m as { delta: string }).delta).join(""); + expect(text).toBe("Because of #12."); + expect(run.messages.some((m) => m.type === "tool_use" && m.toolName === "read")).toBe(true); + expect(run.messages.at(-1)).toMatchObject({ type: "result", success: true, result: "Because of #12." }); + }); + + test("a question asked before the host connects waits for its first poll", async () => { + const { provider, host, startHost } = setup(); + const session = await provider.createSession({ context: CONTEXT }); + const run = collect(session.query("early")); + await new Promise((resolve) => setTimeout(resolve, 30)); + expect(host.asks.length).toBe(0); + void startHost(); + await waitFor(() => host.asks.length === 1); + host.asks[0].sink.done("ok"); + await run.done; + expect(run.messages.at(-1)).toMatchObject({ type: "result", result: "ok" }); + }); + + test("a busy host: no policy answers agent_busy, wait holds the question until the host is ready", async () => { + const host = fakeHost("busy"); + const { provider, startHost, pull } = setup({}, host); + void startHost(); + await waitFor(() => pull.bridge.status() === "busy"); + const session = await provider.createSession({ context: CONTEXT }); + + const refused = collect(session.query("q")); + await refused.done; + expect(refused.messages).toEqual([expect.objectContaining({ type: "error", code: SESSION_BRIDGE_ERROR.agentBusy })]); + + const waiting = collect(session.query("q", { busyPolicy: "wait" })); + await waitFor(() => waiting.messages.some((m) => m.type === "status")); + await new Promise((resolve) => setTimeout(resolve, 30)); + expect(host.asks.length).toBe(0); + host.setStatus("ready"); + await waitFor(() => host.asks.length === 1); + host.asks[0].sink.done("answered"); + await waiting.done; + expect(waiting.messages.map((m) => m.type)).toEqual(["status", "status", "result"]); + }); + + test("interrupt-and-ask runs the host's interrupt through the poll before the question", async () => { + const host = fakeHost("busy"); + const { provider, startHost, pull } = setup({}, host); + void startHost(); + await waitFor(() => pull.bridge.status() === "busy"); + const session = await provider.createSession({ context: CONTEXT }); + const run = collect(session.query("now", { busyPolicy: "interrupt" })); + await waitFor(() => host.asks.length === 1); + expect(host.interrupts).toBe(1); + host.asks[0].sink.done("done"); + await run.done; + expect(run.messages[0]).toEqual({ type: "status", status: "interrupting" }); + expect(run.messages.at(-1)).toMatchObject({ type: "result", result: "done" }); + }); + + test("stopping a running question cancels it on the host, and frees the slot when the host confirms", async () => { + const { provider, host, startHost, pull } = setup(); + void startHost(); + const session = await provider.createSession({ context: CONTEXT }); + const run = collect(session.query("long one")); + await waitFor(() => host.asks.length === 1); + host.asks[0].sink.delta("partial"); + await new Promise((resolve) => setTimeout(resolve, 20)); + + session.abort(); + await run.done; + await waitFor(() => host.asks[0].signal.aborted); + + // Still running on the host: a second question is refused until it ends. + const second = await provider.createSession({ context: CONTEXT }); + const refused = collect(second.query("next")); + await refused.done; + expect(refused.messages.at(-1)).toMatchObject({ type: "error", code: SESSION_BRIDGE_ERROR.agentBusy }); + + host.asks[0].sink.error("aborted"); + await new Promise((resolve) => setTimeout(resolve, 30)); + const third = collect(second.query("next")); + await waitFor(() => host.asks.length === 2); + host.asks[1].sink.done("ok"); + await third.done; + expect(third.messages.at(-1)).toMatchObject({ type: "result", result: "ok" }); + expect(pull.bridge.status()).toBe("ready"); + }); + + test("a question stopped before the host picked it up never reaches the host", async () => { + const { provider, host, startHost } = setup(); + const session = await provider.createSession({ context: CONTEXT }); + const run = collect(session.query("never")); + await new Promise((resolve) => setTimeout(resolve, 20)); + session.abort(); + await run.done; + void startHost(); + await new Promise((resolve) => setTimeout(resolve, 150)); + expect(host.asks.length).toBe(0); + }); + + test("a host that stops polling is gone: the running question fails with session_gone", async () => { + const { provider, host, startHost, stopHost, pull } = setup({ goneAfterMs: 150 }); + void startHost(); + const session = await provider.createSession({ context: CONTEXT }); + const run = collect(session.query("q")); + await waitFor(() => host.asks.length === 1); + stopHost(); + await run.done; + expect(run.messages.at(-1)).toMatchObject({ type: "error", code: SESSION_BRIDGE_ERROR.gone }); + expect(pull.bridge.status()).toBe("gone"); + }); + + test("a host that never connects is gone after the connect timeout", async () => { + const { pull } = setup({ connectTimeoutMs: 50 }); + expect(pull.bridge.status()).toBe("ready"); + await new Promise((resolve) => setTimeout(resolve, 80)); + expect(pull.bridge.status()).toBe("gone"); + }); + + test("a blocked host with a transient mode gets a quick-answer question", async () => { + const host = fakeHost("blocked", { turn: false, transient: true }); + const { provider, startHost, pull } = setup({}, host); + expect(provider.label).toBe("Quick answer from this session · OpenCode"); + void startHost(); + await waitFor(() => pull.bridge.status() === "blocked"); + const session = await provider.createSession({ context: CONTEXT }); + const run = collect(session.query("what is step 2?")); + await waitFor(() => host.asks.length === 1); + expect(host.asks[0].req.mode).toBe("transient"); + expect(host.asks[0].req.text).toContain(SESSION_ASK_TRANSIENT_NOTE); + host.asks[0].sink.done("Step 2 migrates the table."); + await run.done; + expect(run.messages.at(-1)).toMatchObject({ type: "result", result: "Step 2 migrates the table." }); + }); + + test("refuses a wrong token, a browser Origin, a non-loopback Host, and answers 404 with no bridge", async () => { + const { call } = setup(); + const poll = { method: "POST", body: JSON.stringify({ waitMs: 0 }) }; + const auth = { authorization: `Bearer ${TOKEN}` }; + expect((await call(SESSION_BRIDGE_POLL_PATH, poll, auth)).status).toBe(200); + expect((await call(SESSION_BRIDGE_POLL_PATH, poll, { authorization: `Bearer ${"x".repeat(43)}` })).status).toBe(401); + expect((await call(SESSION_BRIDGE_POLL_PATH, poll)).status).toBe(401); + expect((await call(SESSION_BRIDGE_EVENT_PATH, { method: "POST", body: "{}" }, { ...auth, origin: "http://localhost:4321" })).status).toBe(403); + // DNS rebinding: right token, wrong Host. + expect((await call(SESSION_BRIDGE_POLL_PATH, poll, { ...auth, host: "evil.example:4321" })).status).toBe(403); + + const bare = createAIEndpoints({ registry: new ProviderRegistry(), sessionManager: new SessionManager(), authorizeSessionBridgeRequest: () => true }); + const res = await bare[SESSION_BRIDGE_POLL_PATH](new Request(`http://${HOST}${SESSION_BRIDGE_POLL_PATH}`, { method: "POST", headers: auth, body: "{}" })); + expect(res.status).toBe(404); + }); + + test("a newer poll supersedes an open one, and dispose answers the open poll with closing", async () => { + const { call, pull } = setup(); + const auth = { authorization: `Bearer ${TOKEN}` }; + const first = call(SESSION_BRIDGE_POLL_PATH, { method: "POST", body: JSON.stringify({ waitMs: 5_000 }) }, auth); + await new Promise((resolve) => setTimeout(resolve, 10)); + const second = call(SESSION_BRIDGE_POLL_PATH, { method: "POST", body: JSON.stringify({ waitMs: 5_000 }) }, auth); + expect(await (await first).json()).toEqual({ commands: [], superseded: true }); + await new Promise((resolve) => setTimeout(resolve, 10)); + pull.dispose(); + expect(await (await second).json()).toEqual({ commands: [], closing: true }); + expect(pull.bridge.status()).toBe("gone"); + }); + + test("detach drops a question the host never picked up and leaves a running one alone", async () => { + const { provider, host, startHost, pull } = setup(); + const session = await provider.createSession({ context: CONTEXT }); + const run = collect(session.query("pending")); + await new Promise((resolve) => setTimeout(resolve, 20)); + provider.detach(); + void startHost(); + await new Promise((resolve) => setTimeout(resolve, 150)); + expect(host.asks.length).toBe(0); + session.abort(); + await run.done; + expect(pull.bridge.status()).not.toBe("gone"); + }); +}); + +describe("takePullSessionBridgeConfig", () => { + test("reads the host's config once and scrubs it from the environment", () => { + const env: Record = { + PLANNOTATOR_SESSION_BRIDGE_TOKEN: TOKEN, + PLANNOTATOR_SESSION_BRIDGE_HOST: "opencode", + PLANNOTATOR_SESSION_BRIDGE_MODES: "turn,transient", + OTHER: "kept", + }; + expect(takePullSessionBridgeConfig(env)).toEqual({ token: TOKEN, host: "opencode", modes: { turn: true, transient: true } }); + expect(env).toEqual({ OTHER: "kept" }); + expect(takePullSessionBridgeConfig(env)).toBeUndefined(); + }); + + test("refuses a short token or an unknown host", () => { + expect(takePullSessionBridgeConfig({ PLANNOTATOR_SESSION_BRIDGE_TOKEN: "short", PLANNOTATOR_SESSION_BRIDGE_HOST: "opencode" })).toBeUndefined(); + expect(takePullSessionBridgeConfig({ PLANNOTATOR_SESSION_BRIDGE_TOKEN: TOKEN, PLANNOTATOR_SESSION_BRIDGE_HOST: "someone" })).toBeUndefined(); + }); +}); diff --git a/packages/ai/session-bridge-pull.ts b/packages/ai/session-bridge-pull.ts new file mode 100644 index 0000000000..9389bd867c --- /dev/null +++ b/packages/ai/session-bridge-pull.ts @@ -0,0 +1,540 @@ +/** + * "Ask this session" over HTTP: the pull bridge. + * + * The in-process `SessionBridge` (session-bridge.ts) needs the host to live in + * the same process as the Plannotator server (Pi, OpenCode's embedded plan + * server). A host that runs the server as a SEPARATE process (the OpenCode + * plugin spawning the `plannotator` CLI, the Claude Code mod) cannot be called + * directly, and should not have to open a listener of its own. It pulls + * instead: it long-polls this server for work and posts the answer back. + * + * This file is the server half. It builds a `SessionBridge` that the ordinary + * `SessionBridgeProvider` wraps, plus the two HTTP handlers the host talks to. + * Host-neutral: nothing here knows which agent is on the other end. + * + * Protocol (both endpoints are POST + JSON): + * + * POST /api/ai/bridge/poll body { status?, modes?, waitMs? } + * Long-poll for commands. Answers as soon as there is something to do, or + * with an empty list after `waitMs` (clamped to 0..25s, default 25s). + * -> 200 { commands: BridgeCommand[], closing?: true, superseded?: true } + * Each poll is also the host's heartbeat and status report. + * + * POST /api/ai/bridge/event body BridgeHostEvent | { events: BridgeHostEvent[] } + * The host reports progress: `started`, `delta`, `tool`, `done`, `error` + * (per question), `status`, and `interrupted` (per interrupt command). + * -> 200 { ok: true }, or 409 { ok: false, code: "ask_not_active" } when a + * question event names a question that is no longer running. + * + * Commands: { type: "ask", askId, text, mode } | { type: "cancel", askId } + * | { type: "interrupt", interruptId }. + * A command is re-sent on a later poll until the host acknowledges it (any + * event for that question; `interrupted` for an interrupt), so the host must + * treat ids as idempotent. + * + * Auth: `Authorization: Bearer `, where the token is a per-launch secret + * the host generated and handed to the server process (env + * `PLANNOTATOR_SESSION_BRIDGE_TOKEN`). It is never sent to the browser. The + * runtime additionally requires a loopback Host header with the server's own + * port, and these handlers refuse any request carrying an `Origin` header: a + * browser page is never the host. + * + * Liveness: before the host's first request the bridge reports `ready` (a + * question waits for the host to pick it up); if the host never connects + * within `connectTimeoutMs`, or stops polling for `goneAfterMs`, the bridge is + * `gone` and a running question fails with `gone`. + * + * Runtime-agnostic (vendored to Pi): web `Request`/`Response` only, no + * parameter properties, so it loads under Node's strip-only TypeScript. + */ + +import type { + SessionBridge, + SessionBridgeAskMode, + SessionBridgeErrorCode, + SessionBridgeHost, + SessionBridgeSink, + SessionBridgeStatus, +} from "./session-bridge.ts"; + +export const SESSION_BRIDGE_POLL_PATH = "/api/ai/bridge/poll"; +export const SESSION_BRIDGE_EVENT_PATH = "/api/ai/bridge/event"; + +/** Env vars a host sets on the server process it launches. */ +export const SESSION_BRIDGE_TOKEN_ENV = "PLANNOTATOR_SESSION_BRIDGE_TOKEN"; +export const SESSION_BRIDGE_HOST_ENV = "PLANNOTATOR_SESSION_BRIDGE_HOST"; +/** Comma-separated subset of `turn,transient`. Default `turn`. */ +export const SESSION_BRIDGE_MODES_ENV = "PLANNOTATOR_SESSION_BRIDGE_MODES"; + +export const SESSION_BRIDGE_MAX_POLL_MS = 25_000; +const MAX_EVENT_BODY_BYTES = 1_000_000; + +export type BridgeCommand = + | { type: "ask"; askId: string; text: string; mode: SessionBridgeAskMode } + | { type: "cancel"; askId: string } + | { type: "interrupt"; interruptId: string }; + +export type BridgeHostEvent = + | { type: "status"; status: SessionBridgeStatus } + | { type: "started"; askId: string } + | { type: "delta"; askId: string; text: string } + | { type: "tool"; askId: string; name: string } + | { type: "done"; askId: string; answer: string } + | { type: "error"; askId: string; code: SessionBridgeErrorCode; message?: string } + | { type: "interrupted"; interruptId: string; ok: boolean; message?: string }; + +export interface PullSessionBridgeConfig { + token: string; + host: SessionBridgeHost; + modes: { turn: boolean; transient: boolean }; +} + +export interface PullSessionBridgeOptions extends PullSessionBridgeConfig { + /** Default 30s: how long the host may take to make its first request. */ + connectTimeoutMs?: number; + /** Default 30s: silence (no open poll, no request) after which the host is gone. */ + goneAfterMs?: number; + /** Default 5s: an unacknowledged command is sent again after this. */ + resendAfterMs?: number; + /** Default 15s: how long an interrupt may take before it is reported failed. */ + interruptTimeoutMs?: number; + /** Default 15s: after a cancel, how long to wait for the host to confirm before freeing the slot. */ + cancelGraceMs?: number; + now?: () => number; +} + +export interface PullSessionBridge { + readonly bridge: SessionBridge; + /** Handle a request to one of the two bridge paths. `null` for any other path. */ + handle(req: Request): Promise | null; + /** Server shutdown: answer open polls with `closing`, fail anything still waiting. */ + dispose(): void; +} + +const STATUSES: ReadonlySet = new Set(["ready", "busy", "blocked", "gone"]); +const ERROR_CODES: ReadonlySet = new Set(["busy", "blocked", "gone", "aborted", "failed"]); +const BRIDGE_HOSTS: ReadonlySet = new Set(["pi", "opencode", "claude-code"]); + +function isRecord(value: unknown): value is Record { + return !!value && typeof value === "object" && !Array.isArray(value); +} + +function json(body: unknown, status = 200): Response { + return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } }); +} + +/** Constant-time string comparison (both sides are short ASCII tokens). */ +function tokensEqual(a: string, b: string): boolean { + if (a.length !== b.length) return false; + let diff = 0; + for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i); + return diff === 0; +} + +/** Parse `turn,transient` style mode lists. Unknown entries are ignored; empty means turn only. */ +export function parseSessionBridgeModes(value: string | undefined | null): { turn: boolean; transient: boolean } { + const parts = (value ?? "").split(",").map((part) => part.trim().toLowerCase()).filter(Boolean); + const turn = parts.includes("turn"); + const transient = parts.includes("transient"); + if (!turn && !transient) return { turn: true, transient: false }; + return { turn, transient }; +} + +/** + * Read (and REMOVE) the pull-bridge config a host put in the environment, so + * the token is not inherited by anything this process spawns later (agent + * jobs, the agent terminal). Returns undefined when absent or malformed. + */ +export function takePullSessionBridgeConfig(env: Record): PullSessionBridgeConfig | undefined { + const token = env[SESSION_BRIDGE_TOKEN_ENV]?.trim(); + const host = env[SESSION_BRIDGE_HOST_ENV]?.trim(); + const modes = env[SESSION_BRIDGE_MODES_ENV]; + delete env[SESSION_BRIDGE_TOKEN_ENV]; + delete env[SESSION_BRIDGE_HOST_ENV]; + delete env[SESSION_BRIDGE_MODES_ENV]; + // 32+ characters: a host-generated random secret, never a guessable word. + if (!token || token.length < 32 || !host || !BRIDGE_HOSTS.has(host)) return undefined; + return { token, host: host as SessionBridgeHost, modes: parseSessionBridgeModes(modes) }; +} + +interface ActiveAsk { + askId: string; + text: string; + mode: SessionBridgeAskMode; + sink: SessionBridgeSink; + /** The host acknowledged the question (any event for it). */ + acked: boolean; + /** Last time the ask command was handed to a poll; 0 = never. */ + sentAt: number; + cancelled: boolean; + cancelAcked: boolean; + cancelSentAt: number; + cancelTimer: ReturnType | null; +} + +interface PendingInterrupt { + interruptId: string; + sentAt: number; + resolve: () => void; + reject: (error: Error) => void; + timer: ReturnType; +} + +interface OpenPoll { + resolve: (response: Response) => void; + timer: ReturnType; +} + +export function createPullSessionBridge(options: PullSessionBridgeOptions): PullSessionBridge { + const now = options.now ?? (() => Date.now()); + const connectTimeoutMs = options.connectTimeoutMs ?? 30_000; + const goneAfterMs = options.goneAfterMs ?? 30_000; + const resendAfterMs = options.resendAfterMs ?? 5_000; + const interruptTimeoutMs = options.interruptTimeoutMs ?? 15_000; + const cancelGraceMs = options.cancelGraceMs ?? 15_000; + const createdAt = now(); + const modes = { ...options.modes }; + + let hostStatus: SessionBridgeStatus = "ready"; + let connected = false; + let lastSeen = createdAt; + let openPoll: OpenPoll | null = null; + let active: ActiveAsk | null = null; + let pendingInterrupt: PendingInterrupt | null = null; + let interruptSeq = 0; + let disposed = false; + let livenessTimer: ReturnType | null = null; + + const isGone = (): boolean => { + if (disposed) return true; + if (openPoll) return false; + const silence = now() - lastSeen; + return connected ? silence > goneAfterMs : silence > connectTimeoutMs; + }; + + const status = (): SessionBridgeStatus => (isGone() ? "gone" : hostStatus); + + const stopLivenessTimer = () => { + if (livenessTimer) clearInterval(livenessTimer); + livenessTimer = null; + }; + + const finishActive = (ask: ActiveAsk) => { + if (ask.cancelTimer) clearTimeout(ask.cancelTimer); + ask.cancelTimer = null; + if (active === ask) active = null; + if (!active && !pendingInterrupt) stopLivenessTimer(); + }; + + const failForGone = () => { + const ask = active; + if (ask) { + finishActive(ask); + ask.sink.error("gone"); + } + const interrupt = pendingInterrupt; + if (interrupt) { + pendingInterrupt = null; + clearTimeout(interrupt.timer); + interrupt.reject(new Error("The session is no longer available.")); + } + stopLivenessTimer(); + }; + + // While something waits on the host, notice when it disappears. + const ensureLivenessTimer = () => { + if (livenessTimer || disposed) return; + livenessTimer = setInterval(() => { + if (isGone()) failForGone(); + }, 1_000); + (livenessTimer as { unref?: () => void }).unref?.(); + }; + + /** Commands due for (re)sending right now. Marks them sent. */ + const takeDueCommands = (): BridgeCommand[] => { + const commands: BridgeCommand[] = []; + const t = now(); + const due = (sentAt: number) => sentAt === 0 || t - sentAt >= resendAfterMs; + const ask = active; + if (ask) { + if (!ask.cancelled && !ask.acked && due(ask.sentAt)) { + ask.sentAt = t; + commands.push({ type: "ask", askId: ask.askId, text: ask.text, mode: ask.mode }); + } + if (ask.cancelled && ask.acked && !ask.cancelAcked && due(ask.cancelSentAt)) { + ask.cancelSentAt = t; + commands.push({ type: "cancel", askId: ask.askId }); + } + } + const interrupt = pendingInterrupt; + if (interrupt && due(interrupt.sentAt)) { + interrupt.sentAt = t; + commands.push({ type: "interrupt", interruptId: interrupt.interruptId }); + } + return commands; + }; + + /** Hand due commands to the open poll, if there is one. */ + const flush = () => { + const poll = openPoll; + if (!poll) return; + const commands = takeDueCommands(); + if (commands.length === 0) return; + openPoll = null; + clearTimeout(poll.timer); + lastSeen = now(); + poll.resolve(json({ commands })); + }; + + const bridge: SessionBridge = { + host: options.host, + modes, + status, + ask(req, sink, signal) { + if (disposed || isGone()) { + sink.error("gone"); + return; + } + if (active) { + sink.error("busy", "Another Plannotator question is still running in this session."); + return; + } + const ask: ActiveAsk = { + askId: req.askId, + text: req.text, + mode: req.mode, + sink, + acked: false, + sentAt: 0, + cancelled: false, + cancelAcked: false, + cancelSentAt: 0, + cancelTimer: null, + }; + active = ask; + ensureLivenessTimer(); + signal.addEventListener( + "abort", + () => { + if (active !== ask || ask.cancelled) return; + ask.cancelled = true; + if (!ask.acked) { + // The host never confirmed it: drop it. If the host does pick it up, + // its first event is answered 409 `ask_not_active`, which tells the + // host to stop that question. + finishActive(ask); + return; + } + // Our question is in the session: ask the host to stop it, and free + // the slot once it confirms (or after a grace period). + ask.cancelTimer = setTimeout(() => finishActive(ask), cancelGraceMs); + (ask.cancelTimer as { unref?: () => void }).unref?.(); + flush(); + }, + { once: true }, + ); + flush(); + }, + interrupt() { + if (disposed || isGone()) return Promise.reject(new Error("The session is no longer available.")); + if (pendingInterrupt) return Promise.reject(new Error("An interrupt is already in progress.")); + return new Promise((resolve, reject) => { + interruptSeq += 1; + const interrupt: PendingInterrupt = { + interruptId: `interrupt-${interruptSeq}`, + sentAt: 0, + resolve, + reject, + timer: setTimeout(() => { + if (pendingInterrupt !== interrupt) return; + pendingInterrupt = null; + reject(new Error("The session did not confirm the interrupt in time.")); + }, interruptTimeoutMs), + }; + (interrupt.timer as { unref?: () => void }).unref?.(); + pendingInterrupt = interrupt; + ensureLivenessTimer(); + flush(); + }); + }, + detach() { + // Decision / shutdown: a question the host never confirmed is dropped; + // one already running in the session is left alone. + const ask = active; + if (ask && !ask.acked) finishActive(ask); + }, + }; + + const authorize = (req: Request): Response | null => { + if (req.headers.get("origin")) { + return json({ error: "Browser requests are not accepted here.", code: "session_bridge_forbidden_origin" }, 403); + } + const header = req.headers.get("authorization") ?? ""; + const match = /^Bearer\s+(\S+)$/i.exec(header.trim()); + if (!match || !tokensEqual(match[1], options.token)) { + return json({ error: "Missing or wrong session bridge token.", code: "session_bridge_unauthorized" }, 401); + } + return null; + }; + + const readJson = async (req: Request): Promise => { + const text = await req.text(); + if (text.length > MAX_EVENT_BODY_BYTES) throw new Error("Request body too large."); + return text ? JSON.parse(text) : {}; + }; + + const noteContact = () => { + connected = true; + lastSeen = now(); + }; + + const applyStatus = (value: unknown) => { + if (typeof value === "string" && STATUSES.has(value)) hostStatus = value as SessionBridgeStatus; + }; + + const handlePoll = async (req: Request): Promise => { + let body: unknown; + try { + body = await readJson(req); + } catch { + return json({ error: "Invalid JSON body." }, 400); + } + noteContact(); + if (isRecord(body)) { + applyStatus(body.status); + if (isRecord(body.modes)) { + if (typeof body.modes.turn === "boolean") modes.turn = body.modes.turn; + if (typeof body.modes.transient === "boolean") modes.transient = body.modes.transient; + } + } + if (disposed) return json({ commands: [], closing: true }); + if (hostStatus === "gone") failForGone(); + + const requested = isRecord(body) && typeof body.waitMs === "number" && Number.isFinite(body.waitMs) ? body.waitMs : SESSION_BRIDGE_MAX_POLL_MS; + const waitMs = Math.max(0, Math.min(SESSION_BRIDGE_MAX_POLL_MS, requested)); + + // Whoever polls last is the bridge: an older open poll ends now. + const previous = openPoll; + if (previous) { + openPoll = null; + clearTimeout(previous.timer); + previous.resolve(json({ commands: [], superseded: true })); + } + + const commands = takeDueCommands(); + if (commands.length > 0 || waitMs === 0) return json({ commands }); + + return await new Promise((resolve) => { + const poll: OpenPoll = { + resolve, + timer: setTimeout(() => { + if (openPoll !== poll) return; + openPoll = null; + lastSeen = now(); + resolve(json({ commands: takeDueCommands() })); + }, waitMs), + }; + openPoll = poll; + // A host that drops the connection is not "open" any more. + req.signal?.addEventListener( + "abort", + () => { + if (openPoll !== poll) return; + openPoll = null; + clearTimeout(poll.timer); + lastSeen = now(); + resolve(json({ commands: [] })); + }, + { once: true }, + ); + }); + }; + + /** Apply one host event. Returns false when it names a question that is not running. */ + const applyEvent = (event: unknown): boolean => { + if (!isRecord(event) || typeof event.type !== "string") return true; + if (event.type === "status") { + applyStatus(event.status); + if (hostStatus === "gone") failForGone(); + return true; + } + if (event.type === "interrupted") { + const interrupt = pendingInterrupt; + if (!interrupt || event.interruptId !== interrupt.interruptId) return true; + pendingInterrupt = null; + clearTimeout(interrupt.timer); + if (event.ok === true) interrupt.resolve(); + else interrupt.reject(new Error(typeof event.message === "string" && event.message ? event.message : "The session could not be interrupted.")); + return true; + } + const askId = typeof event.askId === "string" ? event.askId : ""; + const ask = active; + if (!ask || ask.askId !== askId) return false; + ask.acked = true; + switch (event.type) { + case "started": + return true; + case "delta": + if (typeof event.text === "string" && event.text && !ask.cancelled) ask.sink.delta(event.text); + return true; + case "tool": + if (typeof event.name === "string" && event.name && !ask.cancelled) ask.sink.tool?.(event.name); + return true; + case "done": + finishActive(ask); + if (ask.cancelled) ask.sink.error("aborted"); + else ask.sink.done(typeof event.answer === "string" ? event.answer : ""); + return true; + case "error": { + finishActive(ask); + const code = typeof event.code === "string" && ERROR_CODES.has(event.code) ? (event.code as SessionBridgeErrorCode) : "failed"; + const message = typeof event.message === "string" && event.message ? event.message : undefined; + ask.sink.error(ask.cancelled ? "aborted" : code, message); + return true; + } + default: + return true; + } + }; + + const handleEvent = async (req: Request): Promise => { + let body: unknown; + try { + body = await readJson(req); + } catch { + return json({ error: "Invalid JSON body." }, 400); + } + noteContact(); + const events = isRecord(body) && Array.isArray(body.events) ? body.events : [body]; + let ok = true; + for (const event of events) { + if (!applyEvent(event)) ok = false; + } + // An acknowledgement may have made a cancel due. + flush(); + return ok ? json({ ok: true }) : json({ ok: false, code: "ask_not_active" }, 409); + }; + + return { + bridge, + handle(req) { + const path = new URL(req.url).pathname; + if (path !== SESSION_BRIDGE_POLL_PATH && path !== SESSION_BRIDGE_EVENT_PATH) return null; + if (req.method !== "POST") return Promise.resolve(json({ error: "Method not allowed." }, 405)); + const refused = authorize(req); + if (refused) return Promise.resolve(refused); + return path === SESSION_BRIDGE_POLL_PATH ? handlePoll(req) : handleEvent(req); + }, + dispose() { + if (disposed) return; + disposed = true; + const poll = openPoll; + openPoll = null; + if (poll) { + clearTimeout(poll.timer); + poll.resolve(json({ commands: [], closing: true })); + } + failForGone(); + }, + }; +} diff --git a/packages/ai/session-bridge.ts b/packages/ai/session-bridge.ts index 74a877f037..f6c134b00c 100644 --- a/packages/ai/session-bridge.ts +++ b/packages/ai/session-bridge.ts @@ -77,6 +77,12 @@ export interface SessionBridge { * refuses an interrupt request. */ interrupt?(): void | Promise; + /** + * The server is about to deliver the reviewer's decision (or shut down): + * drop any question that has not reached the session yet, and leave a turn + * that is already running alone. Optional; in-process hosts deliver at once. + */ + detach?(): void; } // --------------------------------------------------------------------------- @@ -100,8 +106,14 @@ const HOST_LABELS: Record = { "claude-code": "Claude Code", }; -export function sessionBridgeLabel(host: SessionBridgeHost): string { - return `Ask this session · ${HOST_LABELS[host] ?? host}`; +export function sessionBridgeLabel( + host: SessionBridgeHost, + modes: { turn: boolean; transient: boolean } = { turn: true, transient: false }, +): string { + const name = HOST_LABELS[host] ?? host; + // A transient-only bridge (e.g. OpenCode plan review) answers from context, + // with no tools and nothing written to the transcript: say so. + return !modes.turn && modes.transient ? `Quick answer from this session · ${name}` : `Ask this session · ${name}`; } // --------------------------------------------------------------------------- @@ -111,6 +123,14 @@ export function sessionBridgeLabel(host: SessionBridgeHost): string { export const SESSION_ASK_HEADER = "[Plannotator Ask AI] A question from the reviewer in Plannotator. Answer it briefly, here in the session. Do not edit files or start new work unless the question asks you to."; +/** + * Added to a transient (quick-answer) question. The host answers from the + * session's context in one completion: a tool call there yields no answer at + * all, and a tool call the session is waiting on may still look unfinished. + */ +export const SESSION_ASK_TRANSIENT_NOTE = + "Answer in plain text only. Tools are not available for this reply, so do not call any. If a tool call of yours looks unfinished, it is still waiting on this review."; + function describeSurface(context: AIContext): string | null { switch (context.mode) { case "code-review": @@ -132,9 +152,10 @@ function describeSurface(context: AIContext): string | null { * The message the session receives. There is no system prompt: the host's own * prompt is in effect, so the header carries the framing. */ -export function formatSessionAskText(context: AIContext, prompt: string): string { +export function formatSessionAskText(context: AIContext, prompt: string, mode: SessionBridgeAskMode = "turn"): string { const surface = describeSurface(context); - return [SESSION_ASK_HEADER, surface, "", prompt.trim()].filter((line) => line !== null).join("\n"); + const note = mode === "transient" ? SESSION_ASK_TRANSIENT_NOTE : null; + return [SESSION_ASK_HEADER, note, surface, "", prompt.trim()].filter((line) => line !== null).join("\n"); } // --------------------------------------------------------------------------- @@ -170,7 +191,7 @@ export class SessionBridgeProvider implements AIProvider { constructor(bridge: SessionBridge, options: SessionBridgeProviderOptions = {}) { this.bridge = bridge; this.capabilities = { fork: false, resume: false, streaming: true, tools: bridge.modes.turn }; - this.label = sessionBridgeLabel(bridge.host); + this.label = sessionBridgeLabel(bridge.host, bridge.modes); this.pollIntervalMs = options.pollIntervalMs ?? 250; } @@ -210,6 +231,11 @@ export class SessionBridgeProvider implements AIProvider { */ detach(): void { this.closing = true; + try { + this.bridge.detach?.(); + } catch { + // Best effort: the decision must go out regardless. + } } async createSession(options: CreateSessionOptions): Promise { @@ -447,7 +473,7 @@ export class SessionBridgeSession extends BaseSession { ); try { - bridge.ask({ askId: `${this.id}:${gen}`, text: formatSessionAskText(this.context, prompt), mode }, sink, hostAbort.signal); + bridge.ask({ askId: `${this.id}:${gen}`, text: formatSessionAskText(this.context, prompt, mode), mode }, sink, hostAbort.signal); } catch (err) { sink.error("failed", err instanceof Error ? err.message : String(err)); } diff --git a/packages/server/ai-runtime.sessionBridge.test.ts b/packages/server/ai-runtime.sessionBridge.test.ts index 587d506c99..0b16dcec95 100644 --- a/packages/server/ai-runtime.sessionBridge.test.ts +++ b/packages/server/ai-runtime.sessionBridge.test.ts @@ -109,4 +109,77 @@ describe("createAIRuntime (Bun) with a session bridge", () => { asksFromRebound: 1, }); }, 15_000); + + // A host that launched this server as a separate process (OpenCode plugin, + // Claude Code mod) hands it a bridge token through the environment. + async function runPullRunner(extraEnv: Record) { + const dir = mkdtempSync(join(tmpdir(), "plannotator-pull-runtime-")); + tempDirs.push(dir); + const runner = join(dir, "runner.ts"); + const runtimeUrl = pathToFileURL(join(import.meta.dir, "ai-runtime.ts")).href; + writeFileSync(runner, ` + import { createAIRuntime } from ${JSON.stringify(runtimeUrl)}; + const runtime = await createAIRuntime({ cwd: ${JSON.stringify(dir)}, getServerPort: () => 4321 }); + const caps = await (await runtime.endpoints["/api/ai/capabilities"](new Request("http://localhost/api/ai/capabilities"))).json(); + const poll = (headers) => runtime.endpoints["/api/ai/bridge/poll"](new Request("http://localhost/api/ai/bridge/poll", { + method: "POST", + headers, + body: JSON.stringify({ status: "busy", waitMs: 0 }), + })); + const token = ${JSON.stringify("k".repeat(43))}; + const statuses = { + ok: (await poll({ host: "127.0.0.1:4321", authorization: "Bearer " + token })).status, + rebinding: (await poll({ host: "evil.example:4321", authorization: "Bearer " + token })).status, + badToken: (await poll({ host: "127.0.0.1:4321", authorization: "Bearer " + "x".repeat(43) })).status, + }; + const after = await (await runtime.endpoints["/api/ai/capabilities"](new Request("http://localhost/api/ai/capabilities"))).json(); + runtime.dispose(); + const bridge = caps.providers.find((p) => p.id === "session-bridge"); + console.log(JSON.stringify({ + bridge: bridge ? { label: bridge.label, status: bridge.sessionBridge.status } : null, + statusAfterPoll: after.providers.find((p) => p.id === "session-bridge")?.sessionBridge.status ?? null, + statuses, + tokenLeftInEnv: process.env.PLANNOTATOR_SESSION_BRIDGE_TOKEN ?? null, + })); + `); + const proc = Bun.spawn([process.execPath, runner], { + cwd: import.meta.dir, + env: { + ...process.env, + PATH: `${dir}:/usr/bin:/bin`, + PLANNOTATOR_REMOTE: "0", + PLANNOTATOR_SESSION_BRIDGE_TOKEN: "k".repeat(43), + PLANNOTATOR_SESSION_BRIDGE_HOST: "opencode", + PLANNOTATOR_SESSION_BRIDGE_MODES: "turn,transient", + ...extraEnv, + }, + stdout: "pipe", + stderr: "pipe", + }); + const [stdout, stderr, exitCode] = await Promise.all([ + new Response(proc.stdout).text(), + new Response(proc.stderr).text(), + proc.exited, + ]); + expect(exitCode, stderr).toBe(0); + return JSON.parse(stdout.trim().split("\n").at(-1)!); + } + + test("takes a pull bridge from the host's environment, scrubs the token, and guards the endpoints", async () => { + if (process.platform === "win32") return; + expect(await runPullRunner({})).toEqual({ + bridge: { label: "Ask this session · OpenCode", status: "ready" }, + statusAfterPoll: "busy", + statuses: { ok: 200, rebinding: 403, badToken: 401 }, + tokenLeftInEnv: null, + }); + }, 15_000); + + test("stays off in remote mode, and still scrubs the token", async () => { + if (process.platform === "win32") return; + const result = await runPullRunner({ PLANNOTATOR_REMOTE: "1" }); + expect(result.bridge).toBeNull(); + expect(result.statuses.ok).toBe(404); + expect(result.tokenLeftInEnv).toBeNull(); + }, 15_000); }); diff --git a/packages/server/ai-runtime.ts b/packages/server/ai-runtime.ts index 38593c9aac..5f73faa6af 100644 --- a/packages/server/ai-runtime.ts +++ b/packages/server/ai-runtime.ts @@ -1,5 +1,7 @@ import { createAIEndpoints, + createPullSessionBridge, + takePullSessionBridgeConfig, createDeferredModelDiscovery, createProvider, ProviderRegistry, @@ -8,10 +10,12 @@ import { SessionManager, type AIEndpoints, type PiSDKConfig, + type PullSessionBridgeConfig, type SessionBridge, } from "@plannotator/ai"; import { resolveWindowsCommandShim } from "@plannotator/ai/providers/command-path"; import { isLoopbackHostHeader } from "@plannotator/shared/loopback-host"; +import { isRemoteSession } from "./remote"; export interface AIRuntime { endpoints: AIEndpoints; @@ -35,6 +39,31 @@ interface CreateAIRuntimeOptions { * (DNS-rebinding guard). Undefined (not bound yet) refuses bridge requests. */ getServerPort?: () => number | undefined; + /** + * "Ask this session" for a host that launched this server as a SEPARATE + * process (the OpenCode plugin, the Claude Code mod): the host long-polls + * `/api/ai/bridge/poll` with this token (session-bridge-pull.ts). Defaults to + * the config the host put in the environment (`PLANNOTATOR_SESSION_BRIDGE_*`), + * taken once per process and removed from `process.env`. Ignored when an + * in-process `sessionBridge` is given, and off in remote mode. + */ + pullSessionBridge?: PullSessionBridgeConfig | null; +} + +let envPullBridgeTaken = false; +let envPullBridge: PullSessionBridgeConfig | undefined; + +/** + * The pull-bridge config from the environment, read once per process. Taking + * it also deletes the variables, so agent jobs and terminals spawned later + * never inherit the token. + */ +export function takeEnvPullSessionBridgeConfig(): PullSessionBridgeConfig | undefined { + if (!envPullBridgeTaken) { + envPullBridgeTaken = true; + envPullBridge = takePullSessionBridgeConfig(process.env); + } + return envPullBridge; } export async function createAIRuntime(options: CreateAIRuntimeOptions = {}): Promise { @@ -119,7 +148,16 @@ export async function createAIRuntime(options: CreateAIRuntimeOptions = {}): Pro // OpenCode not available. } - const bridgeProvider = options.sessionBridge ? new SessionBridgeProvider(options.sessionBridge) : null; + // Off in remote mode, in-process or pulled: anyone who can reach the session + // URL could otherwise type into the agent session (same reasoning as the + // agent terminal). + const remote = isRemoteSession(); + const inProcessBridge = remote ? undefined : options.sessionBridge; + const envPull = options.pullSessionBridge === undefined ? takeEnvPullSessionBridgeConfig() : undefined; + const pullConfig = remote || inProcessBridge ? undefined : (options.pullSessionBridge ?? envPull); + const pullBridge = pullConfig ? createPullSessionBridge(pullConfig) : null; + const sessionBridge = inProcessBridge ?? pullBridge?.bridge; + const bridgeProvider = sessionBridge ? new SessionBridgeProvider(sessionBridge) : null; if (bridgeProvider) registry.register(bridgeProvider, SESSION_BRIDGE_PROVIDER_NAME); const endpoints = createAIEndpoints({ @@ -132,6 +170,7 @@ export async function createAIRuntime(options: CreateAIRuntimeOptions = {}): Pro beforeProviderSession: discovery.beforeProviderSession, authorizeSessionBridgeRequest: (req) => isLoopbackHostHeader(req.headers.get("host"), options.getServerPort?.()), + ...(pullBridge ? { pullBridge } : {}), }); return { @@ -142,6 +181,7 @@ export async function createAIRuntime(options: CreateAIRuntimeOptions = {}): Pro bridgeProvider?.detach(); sessionManager.disposeAll(); registry.disposeAll(); + pullBridge?.dispose(); }, }; } diff --git a/packages/server/annotate.ts b/packages/server/annotate.ts index 4d8d3a0e35..3615b6067f 100644 --- a/packages/server/annotate.ts +++ b/packages/server/annotate.ts @@ -53,8 +53,8 @@ import { dirname, resolve as resolvePath } from "path"; import { isWithinDirectory } from "@plannotator/shared/html-assets-node"; import { isWSL } from "./browser"; import { handleOpenInApps, handleOpenIn } from "./open-in"; -import { AI_QUERY_ENDPOINT, createAIRuntime } from "./ai-runtime"; -import { isAIEndpointPath, type AIEndpoints, type SessionBridge } from "@plannotator/ai"; +import { createAIRuntime } from "./ai-runtime"; +import { isAIEndpointPath, isLongLivedAIEndpointPath, type AIEndpoints, type SessionBridge } from "@plannotator/ai"; import { createHtmlAssetRegistry, framedDocumentNotFound } from "./html-assets"; import { createBunAgentTerminalBridge } from "./agent-terminal"; import { startLiveAppProxy, type LiveAppProxy } from "./live-proxy"; @@ -1155,7 +1155,7 @@ export async function startAnnotateServer( } const handler = aiRuntime.endpoints[url.pathname as keyof AIEndpoints]; if (handler) { - if (url.pathname === AI_QUERY_ENDPOINT) { + if (isLongLivedAIEndpointPath(url.pathname)) { server.timeout(req, 0); } return handler(req); diff --git a/packages/server/index.ts b/packages/server/index.ts index 2344309dcf..9a457e1e46 100644 --- a/packages/server/index.ts +++ b/packages/server/index.ts @@ -56,8 +56,8 @@ import { warmFileListCache } from "@plannotator/shared/resolve-file"; import { createEditorAnnotationHandler } from "./editor-annotations"; import { createExternalAnnotationHandler } from "./external-annotations"; import { isWSL } from "./browser"; -import { AI_QUERY_ENDPOINT, createAIRuntime } from "./ai-runtime"; -import { isAIEndpointPath, type AIEndpoints, type SessionBridge } from "@plannotator/ai"; +import { createAIRuntime } from "./ai-runtime"; +import { isAIEndpointPath, isLongLivedAIEndpointPath, type AIEndpoints, type SessionBridge } from "@plannotator/ai"; import { isArchiveDocumentMutation } from "@plannotator/shared/archive-mode"; import { readPlanFile } from "@plannotator/shared/doc-resolve"; @@ -508,7 +508,7 @@ export async function startPlannotatorServer( } const handler = aiRuntime.endpoints[url.pathname as keyof AIEndpoints]; if (handler) { - if (url.pathname === AI_QUERY_ENDPOINT) { + if (isLongLivedAIEndpointPath(url.pathname)) { server.timeout(req, 0); } return handler(req); diff --git a/packages/server/package.json b/packages/server/package.json index 669595d98b..e4996920fc 100644 --- a/packages/server/package.json +++ b/packages/server/package.json @@ -22,6 +22,7 @@ "./uninstall": "./uninstall.ts", "./share-url": "./share-url.ts", "./tailscale-serve": "./tailscale-serve.ts", + "./ai-runtime": "./ai-runtime.ts", "./qr": "./qr.ts", "./sessions": "./sessions.ts", "./auto-update": "./auto-update.ts", diff --git a/packages/server/review.ts b/packages/server/review.ts index ddf665f7bd..76fc80639b 100644 --- a/packages/server/review.ts +++ b/packages/server/review.ts @@ -150,8 +150,8 @@ import { fetchPRArtifactDocument, PRArtifactDocumentError, } from "@plannotator/shared/pr-artifact-document"; -import { AI_QUERY_ENDPOINT, createAIRuntime } from "./ai-runtime"; -import { isAIEndpointPath, type AIEndpoints, type SessionBridge } from "@plannotator/ai"; +import { createAIRuntime } from "./ai-runtime"; +import { isAIEndpointPath, isLongLivedAIEndpointPath, type AIEndpoints, type SessionBridge } from "@plannotator/ai"; import { isWSL } from "./browser"; import { handleOpenInApps, handleOpenIn } from "./open-in"; import type { LocalWorkspaceReview, WorkspaceDiffType } from "./review-workspace"; @@ -3999,7 +3999,7 @@ export async function startReviewServer( ); } } - if (url.pathname === AI_QUERY_ENDPOINT) { + if (isLongLivedAIEndpointPath(url.pathname)) { server.timeout(req, 0); } return handler(req); From ea7a78556ac2eb38d1ca5f9990167e5fdf83bc6b Mon Sep 17 00:00:00 2001 From: Michael Ramos Date: Sat, 3 Oct 2026 07:33:09 -0700 Subject: [PATCH 2/4] fix(ai): keep the pull bridge off under --tailscale, scrub its token at CLI start The --tailscale path called takeEnvPullSessionBridgeConfig to discard the host's config, but the take caches it, so createAIRuntime served it anyway and tailnet peers could type into the agent session. Add an explicit discard. Also take the config at the top of the CLI, before git/gh/sem, the auto-update wrapper, or an agent terminal (AI disabled, archive) can inherit the token. --- apps/hook/server/index.ts | 13 ++++++++++--- packages/server/ai-runtime.sessionBridge.test.ts | 15 +++++++++++++-- packages/server/ai-runtime.ts | 10 ++++++++++ 3 files changed, 33 insertions(+), 5 deletions(-) diff --git a/apps/hook/server/index.ts b/apps/hook/server/index.ts index 813432682e..d86668e10d 100644 --- a/apps/hook/server/index.ts +++ b/apps/hook/server/index.ts @@ -113,7 +113,7 @@ import { createWorktreePool, type WorktreePool, type PoolEntry } from "@plannota import { parsePRUrl, checkPRAuth, fetchPR, getCliName, getCliInstallUrl, getMRLabel, getMRNumberLabel, getDisplayRepo, getPlatformLabel, getPRNumber, getPRHeadFetchSpec, getPRCloneCommand } from "@plannotator/server/pr"; import { writeRemoteShareLink } from "@plannotator/server/share-url"; import { enableTailscaleServe } from "@plannotator/server/tailscale-serve"; -import { takeEnvPullSessionBridgeConfig } from "@plannotator/server/ai-runtime"; +import { discardEnvPullSessionBridgeConfig, takeEnvPullSessionBridgeConfig } from "@plannotator/server/ai-runtime"; import { writeUrlQr } from "@plannotator/server/qr"; import { resolveAnnotateTarget } from "./annotate-resolution"; import { LIVE_APP_REMOTE_MESSAGE } from "@plannotator/shared/live-probe"; @@ -220,6 +220,12 @@ import reviewHtml from "../dist/review.html" with { type: "text" }; const reviewHtmlContent = reviewHtml as unknown as string; // Check for subcommand +// "Ask this session" pull-bridge secret: take it out of process.env before +// ANYTHING spawns (git/gh/sem before the server starts, the auto-update +// wrapper, agent terminals when Ask AI is disabled, archive mode), so no child +// inherits it. The config stays cached for createAIRuntime. +takeEnvPullSessionBridgeConfig(); + const rawArgs = process.argv.slice(2); let parsedStrictAnnotateOptions; try { @@ -279,8 +285,9 @@ if (tailscaleFlag) { process.env.PLANNOTATOR_URL_HOST = ""; // "Ask this session" stays off in a tailnet-published session, as it is in // remote mode: the session is reachable from other devices. Taking the - // host's bridge config here discards it (and scrubs the token from env). - takeEnvPullSessionBridgeConfig(); + // host's bridge config here discards it for the whole process (a plain + // take would only cache it for createAIRuntime to serve anyway). + discardEnvPullSessionBridgeConfig(); } /** diff --git a/packages/server/ai-runtime.sessionBridge.test.ts b/packages/server/ai-runtime.sessionBridge.test.ts index 0b16dcec95..8ba3238cfc 100644 --- a/packages/server/ai-runtime.sessionBridge.test.ts +++ b/packages/server/ai-runtime.sessionBridge.test.ts @@ -112,13 +112,14 @@ describe("createAIRuntime (Bun) with a session bridge", () => { // A host that launched this server as a separate process (OpenCode plugin, // Claude Code mod) hands it a bridge token through the environment. - async function runPullRunner(extraEnv: Record) { + async function runPullRunner(extraEnv: Record, options: { discardFirst?: boolean } = {}) { const dir = mkdtempSync(join(tmpdir(), "plannotator-pull-runtime-")); tempDirs.push(dir); const runner = join(dir, "runner.ts"); const runtimeUrl = pathToFileURL(join(import.meta.dir, "ai-runtime.ts")).href; writeFileSync(runner, ` - import { createAIRuntime } from ${JSON.stringify(runtimeUrl)}; + import { createAIRuntime, discardEnvPullSessionBridgeConfig } from ${JSON.stringify(runtimeUrl)}; + ${options.discardFirst ? "discardEnvPullSessionBridgeConfig();" : ""} const runtime = await createAIRuntime({ cwd: ${JSON.stringify(dir)}, getServerPort: () => 4321 }); const caps = await (await runtime.endpoints["/api/ai/capabilities"](new Request("http://localhost/api/ai/capabilities"))).json(); const poll = (headers) => runtime.endpoints["/api/ai/bridge/poll"](new Request("http://localhost/api/ai/bridge/poll", { @@ -182,4 +183,14 @@ describe("createAIRuntime (Bun) with a session bridge", () => { expect(result.statuses.ok).toBe(404); expect(result.tokenLeftInEnv).toBeNull(); }, 15_000); + + // The CLI's --tailscale path: the session is reachable from the tailnet, so + // the host's config is thrown away for the process (not merely cached). + test("a discarded env config is never served later in the process", async () => { + if (process.platform === "win32") return; + const result = await runPullRunner({}, { discardFirst: true }); + expect(result.bridge).toBeNull(); + expect(result.statuses.ok).toBe(404); + expect(result.tokenLeftInEnv).toBeNull(); + }, 15_000); }); diff --git a/packages/server/ai-runtime.ts b/packages/server/ai-runtime.ts index 5f73faa6af..f51429201e 100644 --- a/packages/server/ai-runtime.ts +++ b/packages/server/ai-runtime.ts @@ -66,6 +66,16 @@ export function takeEnvPullSessionBridgeConfig(): PullSessionBridgeConfig | unde return envPullBridge; } +/** + * Take the pull-bridge config from the environment and throw it away, so no + * later `createAIRuntime` in this process serves it (a `--tailscale` session + * is reachable from other devices, like remote mode). Also scrubs the env. + */ +export function discardEnvPullSessionBridgeConfig(): void { + takeEnvPullSessionBridgeConfig(); + envPullBridge = undefined; +} + export async function createAIRuntime(options: CreateAIRuntimeOptions = {}): Promise { const cwd = options.cwd ?? process.cwd(); const registry = new ProviderRegistry(); From d87b450242dfff70a0f5071b373fb7d2868f3bbf Mon Sep 17 00:00:00 2001 From: Michael Ramos Date: Sat, 3 Oct 2026 07:33:09 -0700 Subject: [PATCH 3/4] fix(opencode): never steer a question into a run that started since the last status report The server asks only when the host last reported ready, but that report can be a status tick old. If the user started a run in between, a steered question would land inside it, and Stop would then interrupt the user's run. Refuse with busy; the reviewer gets the usual wait / interrupt choice. --- apps/opencode-plugin/opencode-session-bridge.test.ts | 12 ++++++++++++ apps/opencode-plugin/opencode-session-bridge.ts | 9 +++++++++ 2 files changed, 21 insertions(+) diff --git a/apps/opencode-plugin/opencode-session-bridge.test.ts b/apps/opencode-plugin/opencode-session-bridge.test.ts index f068beb1ae..e4e104728b 100644 --- a/apps/opencode-plugin/opencode-session-bridge.test.ts +++ b/apps/opencode-plugin/opencode-session-bridge.test.ts @@ -199,6 +199,18 @@ describe("OpenCode session bridge", () => { await waitFor(() => bridge.status() === "gone"); }); + test("a turn question never steers into a run the session started since its last status report", async () => { + const host = fakeHost(); + const bridge = bridgeFor(host); + await waitFor(() => bridge.status() === "ready"); + host.emit("session.execution.started"); + await waitFor(() => bridge.status() === "busy"); + const sink = recordingSink(); + bridge.ask({ askId: "a1", text: "q", mode: "turn" }, sink.sink, new AbortController().signal); + expect(sink.error?.code).toBe("busy"); + expect(host.prompts.length).toBe(0); + }); + test("a session already running when the bridge starts reads busy until it goes idle", async () => { const host = fakeHost({ idle: false }); const bridge = bridgeFor(host); diff --git a/apps/opencode-plugin/opencode-session-bridge.ts b/apps/opencode-plugin/opencode-session-bridge.ts index 51f161c1cc..c3108ccb80 100644 --- a/apps/opencode-plugin/opencode-session-bridge.ts +++ b/apps/opencode-plugin/opencode-session-bridge.ts @@ -513,6 +513,15 @@ export function createOpenCodeSessionBridge(options: OpenCodeSessionBridgeOption sink.error("blocked"); return; } + // "steer" lands INSIDE a running execution. The server only asks when + // the host last reported ready, but that report can be up to one status + // tick old: if the session started a run since (the user typed), our + // question must not be steered into it (and a later Stop would then + // interrupt the user's own run). Report busy; the reviewer can wait. + if (running) { + sink.error("busy"); + return; + } askTurn(req.text, sink, signal); }, async interrupt() { From a5a618ebc8d32ce07758bea7ba6ece7c988ec122 Mon Sep 17 00:00:00 2001 From: Michael Ramos Date: Sat, 3 Oct 2026 07:36:29 -0700 Subject: [PATCH 4/4] docs: pull-bridge token is taken at CLI start; --tailscale discards it --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 462d642377..51a68da4be 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -661,7 +661,7 @@ Automatic resolution is session-only and never writes a preference. Explicit per **"Ask this session" (session bridge).** A host can let Ask AI be answered by the agent session that opened Plannotator instead of a separate SDK agent. The host implements the small `SessionBridge` interface (`packages/ai/session-bridge.ts`, vendored to Pi: `host`, `status()` = `ready | busy | blocked | gone`, `modes { turn, transient }`, `ask(req, sink, signal)`, optional `interrupt()`) and passes it as `sessionBridge` to the server (`startReviewServer` / `startAnnotateServer` / plan `ServerOptions` on Bun; review, annotate and plan review on Pi), which registers `SessionBridgeProvider` LAST under id `session-bridge` (server default unchanged) behind the unchanged `/api/ai/*` endpoints. `/api/ai/capabilities` adds `label` ("Ask this session · Pi") and live `sessionBridge { host, status, modes }` for it, `models: []` (no model picker). The provider, not the host, enforces one question at a time across threads (`ask_in_flight`), sends no system prompt (the question carries the `SESSION_ASK_HEADER` line plus the surface), and never interrupts implicitly: a busy session answers `agent_busy`, and the client re-asks with `/api/ai/query` `busyPolicy: "wait"` ("Ask when it finishes", streams `status: waiting` until idle) or `"interrupt"` ("Interrupt and ask now", host `interrupt()` then ask). `session_gone` / `session_blocked` offer "Ask a separate AI instead", which moves THIS page (never the cookie: `applyConfigChange(..., { persist: false })`) to `resolveSessionBridgeFallback` and re-asks. Abort cancels only our question; the runtime `detach()`es the bridge before teardown so a decision/exit never stops a turn already running. Client default (`resolveAIProviderSelection`): an explicit saved pick wins (per-origin for origins with their own provider, else the global one), then a usable bridge (not gone; blocked only with a transient mode), then the old order — byte-identical without a bridge. Code review sends the diff's identity (`buildSessionReviewIdentity`), never the patch. **Pi** (`apps/pi-extension/pi-session-bridge.ts`): review, annotate, last and plan review (plan review no longer blocks the session, see "Pi plan review does not block" below), off in remote mode; the question is a `pi.sendMessage({ customType: "plannotator-ask", display: true, details: { askId } }, { triggerTurn: true })` turn read back from `message_start` / `message_update` text deltas / `tool_execution_start` / `agent_end`; listeners register once at load because `pi.on` returns no unsubscribe before Pi 1.0. **OpenCode 2** (`apps/opencode-plugin/opencode-session-bridge.ts`): review, annotate and last ask a real turn — `ctx.session.prompt({ id, text, delivery: "steer", metadata: { source: "plannotator-ask" } })` under a message id generated in OpenCode's own ascending `msg_` format, streamed back from `ctx.event.subscribe()` (`session.inbox.delivered` with our id starts the answer, then `session.text.delta` / `text.ended` / `tool.input.started`, ended by `session.execution.succeeded|failed|interrupted`), with `session.wait` + `session.context` as the fallback when the event stream is missing (upstream #44788). Delivery is "steer", not "queue", on purpose: every V2 command leaves its session-URL notice as a pending steer row, and a queued question would wake the session with that notice promoted alone as its own model turn (seen live on 2.0.22). Busy comes from the execution events cross-checked by a single outstanding `session.wait` probe; abort and "Interrupt and ask now" use `session.interrupt` (whole execution), only on a turn that is ours or on the reviewer's explicit choice. Plan review answers from context only ("Quick answer from this session · OpenCode", `modes { turn: false, transient: true }`): `submit_plan` is a pending tool call, so a real turn cannot run until the decision (a prompt sent then waits for the tool result, verified live), and `markPlanReviewPending` makes EVERY bridge on that session report `blocked` so nothing can interrupt the review. The quick answer is `session.generate` (no transcript write; verified live on 2.0.22 with OpenAI during a pending `submit_plan`, and `@opencode/ai`'s `normalizeToolHistory` fills the unfinished call with an error result for every provider); it still offers the model its tools, so the question carries `SESSION_ASK_TRANSIENT_NOTE` and an empty answer (a tool call) is reported as a failure. The embedded plan server takes the bridge in-process; review/annotate/last and the CLI plan fallback run the `plannotator` CLI as a child and use the pull bridge below. **OpenCode 1** has no bridge (a second adapter over V1's different message/event model, not a small lift). Claude Code has no bridge yet; its mod will use the pull bridge. -**Pull bridge (host-neutral, `packages/ai/session-bridge-pull.ts` server half, vendored to Pi; `session-bridge-pull-client.ts` host half).** For a host that runs the Plannotator server as a SEPARATE process and must not open a listener of its own (the OpenCode plugin's CLI child today, the Claude Code mod next). The host generates a per-launch secret and starts the server with `PLANNOTATOR_SESSION_BRIDGE_TOKEN` (>= 32 chars), `PLANNOTATOR_SESSION_BRIDGE_HOST` (`opencode` / `claude-code` / `pi`) and optional `PLANNOTATOR_SESSION_BRIDGE_MODES` (`turn,transient`; default `turn`). The Bun `createAIRuntime` takes that config once per process (`takeEnvPullSessionBridgeConfig`), deletes the three variables so agent jobs and terminals never inherit the token, and registers the same `SessionBridgeProvider` over it; it is off in remote mode and under `--tailscale` (and an in-process bridge wins). Pi's `createPiAIRuntime` accepts the same config as its `pullSessionBridge` option (no env takeover: Pi itself always bridges in-process). The host learns the port (OpenCode: `PLANNOTATOR_READY_FILE`) and then talks to two endpoints on `http://127.0.0.1:`, both `POST` + JSON with `Authorization: Bearer `: `/api/ai/bridge/poll` `{ status?, modes?, waitMs? }` long-polls (clamped to 25s; answers early when there is work) and returns `{ commands, closing?, superseded? }`, commands being `{ type: "ask", askId, text, mode }`, `{ type: "cancel", askId }` and `{ type: "interrupt", interruptId }`; `/api/ai/bridge/event` takes one event or `{ events: [...] }` — `started`, `delta`, `tool`, `done`, `error` (per question, `code` one of `busy|blocked|gone|aborted|failed`), `status`, and `interrupted { interruptId, ok, message? }` — and answers `409 { code: "ask_not_active" }` for a question that is no longer running, which tells the host to stop it. Commands are re-sent every ~5s until acknowledged (any event for that question; `interrupted` for an interrupt), so hosts dedupe by id. Guards, in order: a loopback Host with the server's own port (the runtime's `authorizeSessionBridgeRequest`, `403 session_bridge_forbidden_host`), no `Origin` header (`403`, a browser is never the host), the bearer token (`401`); without a pull bridge both paths answer `404`, which an older-binary-aware host treats as "no bridge". Liveness: until the host's first request the bridge reports `ready` (a question waits for the first poll); no first request within 30s, or 30s with no open poll after that, is `gone`, and a running question then fails `session_gone`. The newest poll supersedes an open one. A reviewer's Stop drops a question the host never confirmed, else queues `cancel` and frees the slot when the host confirms (or after 15s); `detach()` (decision / shutdown) drops only unconfirmed questions, and `dispose()` answers the open poll `closing`. Both runtimes route the two paths through `createAIEndpoints` (`pullBridge` dep), and Bun lifts the idle timeout for the poll (`isLongLivedAIEndpointPath`). Tests: `packages/ai/session-bridge-pull.test.ts` (fake host over the real client: streaming, early question, busy wait / interrupt, abort before and after pickup, host disappears, never connects, transient, bad token / Origin / rebinding Host, supersede, dispose, detach), `packages/server/ai-runtime.sessionBridge.test.ts` (env takeover, scrub, remote-off), `apps/opencode-plugin/session-bridge-cli.test.ts` (plugin ↔ CLI child end to end). +**Pull bridge (host-neutral, `packages/ai/session-bridge-pull.ts` server half, vendored to Pi; `session-bridge-pull-client.ts` host half).** For a host that runs the Plannotator server as a SEPARATE process and must not open a listener of its own (the OpenCode plugin's CLI child today, the Claude Code mod next). The host generates a per-launch secret and starts the server with `PLANNOTATOR_SESSION_BRIDGE_TOKEN` (>= 32 chars), `PLANNOTATOR_SESSION_BRIDGE_HOST` (`opencode` / `claude-code` / `pi`) and optional `PLANNOTATOR_SESSION_BRIDGE_MODES` (`turn,transient`; default `turn`). The Bun CLI takes that config at its very first line (`takeEnvPullSessionBridgeConfig`, cached once per process; `createAIRuntime` reads the cache) and deletes the three variables, so nothing it spawns (git/gh before the server starts, agent jobs, terminals, the auto-update wrapper) inherits the token; `--tailscale` discards it outright (`discardEnvPullSessionBridgeConfig`). The runtime registers the same `SessionBridgeProvider` over it; it is off in remote mode and under `--tailscale` (and an in-process bridge wins). Pi's `createPiAIRuntime` accepts the same config as its `pullSessionBridge` option (no env takeover: Pi itself always bridges in-process). The host learns the port (OpenCode: `PLANNOTATOR_READY_FILE`) and then talks to two endpoints on `http://127.0.0.1:`, both `POST` + JSON with `Authorization: Bearer `: `/api/ai/bridge/poll` `{ status?, modes?, waitMs? }` long-polls (clamped to 25s; answers early when there is work) and returns `{ commands, closing?, superseded? }`, commands being `{ type: "ask", askId, text, mode }`, `{ type: "cancel", askId }` and `{ type: "interrupt", interruptId }`; `/api/ai/bridge/event` takes one event or `{ events: [...] }` — `started`, `delta`, `tool`, `done`, `error` (per question, `code` one of `busy|blocked|gone|aborted|failed`), `status`, and `interrupted { interruptId, ok, message? }` — and answers `409 { code: "ask_not_active" }` for a question that is no longer running, which tells the host to stop it. Commands are re-sent every ~5s until acknowledged (any event for that question; `interrupted` for an interrupt), so hosts dedupe by id. Guards, in order: a loopback Host with the server's own port (the runtime's `authorizeSessionBridgeRequest`, `403 session_bridge_forbidden_host`), no `Origin` header (`403`, a browser is never the host), the bearer token (`401`); without a pull bridge both paths answer `404`, which an older-binary-aware host treats as "no bridge". Liveness: until the host's first request the bridge reports `ready` (a question waits for the first poll); no first request within 30s, or 30s with no open poll after that, is `gone`, and a running question then fails `session_gone`. The newest poll supersedes an open one. A reviewer's Stop drops a question the host never confirmed, else queues `cancel` and frees the slot when the host confirms (or after 15s); `detach()` (decision / shutdown) drops only unconfirmed questions, and `dispose()` answers the open poll `closing`. Both runtimes route the two paths through `createAIEndpoints` (`pullBridge` dep), and Bun lifts the idle timeout for the poll (`isLongLivedAIEndpointPath`). Tests: `packages/ai/session-bridge-pull.test.ts` (fake host over the real client: streaming, early question, busy wait / interrupt, abort before and after pickup, host disappears, never connects, transient, bad token / Origin / rebinding Host, supersede, dispose, detach), `packages/server/ai-runtime.sessionBridge.test.ts` (env takeover, scrub, remote-off), `apps/opencode-plugin/session-bridge-cli.test.ts` (plugin ↔ CLI child end to end). **Model lists come from the installed tools, not hand lists.** Claude's list is the SDK's `supportedModels()` against the installed `claude` (a throwaway process with no prompt, `settingSources: []` so no user hooks run, no MCP servers, 10s cap, ~0.5s measured); Codex's is the app-server `model/list`. Both run lazily behind the provider initializer (`?activate=` or the first session), never at startup; a success is kept for the process, a failure may be retried after 60s (`createBestEffortOnce`), and the capabilities answer marks each such provider's list `modelsSource: 'fallback' | 'discovered'` so the client forgets a fallback answer and retries on its next load. The same discovery captures the tool version once (`claude --version` run alongside it; codex from the app-server initialize `userAgent`, via `cliVersionFrom`), kept even when discovery fails, and the answer carries it as an optional `toolVersion`; every Claude/Codex model picker (Agents tab launchers, Guided Review, Ask AI bars, Settings) shows a muted `ModelSourceHint` line ("From your installed Codex 0.155.1", or the built-in-list variant on `fallback`) only when `toolVersion` is present, so a host that omits it gets no hint. Both runtimes share `createDeferredModelDiscovery`: an `?activate=` probe waits for discovery, and so does a session for every provider except Claude, whose sessions resolve the model against the current list while discovery finishes in the background, so the first Ask AI answer does not wait on it — except when that list is still the fallback and lacks the requested pick (e.g. `opus[1m]`), where the session waits for discovery rather than silently running a different model once. One shape, `CatalogModel` in `packages/core/model-catalog.ts` (id, label, efforts + default effort, fast mode, `resolvedId`), serves Ask AI AND the review / Code Tour / Guided Review launchers: `useModelCatalogs` (`packages/ui/hooks/`) fetches the same `/api/ai/capabilities?activate=` answer for the ONE engine a launcher is set to, and `useAgentSettings` resolves saved picks against it at read time (the cookie is never rewritten). ONE resolver, `resolveModelChoice`, is used by the launchers, Ask AI's client (`aiProvider.ts`) and the AI session endpoint: exact id → the alias whose `resolvedId` covers it → the same family's alias (`claude-opus-5` → `opus`) → the surface default (Claude `opus` for review, `sonnet` for tour/guide; Codex `''` = the model the Codex list marks default, except Guided Review, which prefers `gpt-6-luna` when offered: `PREFERRED_GUIDE_CODEX_MODEL`) → the catalog default; it never moves a pick onto a `[1m]` id unless the pick was one. Efforts clamp to the model's own levels, launches wait until the catalog settles, and a loading row shows meanwhile. The Claude catalog drops the SDK's `default` pointer row and adds a bare latest alias per family offered, and always offers `opus` / `sonnet` / `haiku` (some CLIs, e.g. Claude Code 2.1.141, name Opus only through the `default` row, whose description then supplies the version); alias labels carry the version parsed from the row's `resolvedModel` (`claudeModelVersion`: "Opus 5.5 (latest)"), since the SDK's `displayName` has none. Codex fast mode is dropped when resolution replaces a saved model with a different one; changing Fast or reasoning then re-keys the section to the model shown. Codex fast support is read from `serviceTiers` (a `priority`/`fast` tier) as well as the deprecated `additionalSpeedTiers`. The only static lists are the small `CLAUDE_FALLBACK_MODELS` / `CODEX_FALLBACK_MODELS`, used when discovery fails.