cursor-opencode-provider 0.8.0 → 0.8.3

package/dist/errors.js

@@ -1,3 +1,4 @@
+import { APICallError } from "@ai-sdk/provider";
 /** Structured provider failure with retry and transport diagnostics. */
 export class CursorProviderError extends Error {
     origin;
@@ -14,6 +15,16 @@ export class CursorProviderError extends Error {
     rstCode;
     code;
     retryAfterMs;
+    /** Cursor's classified verdict, or false once provider retries must stop. */
+    retryable;
+    /**
+     * The provider stopped, but the host may send the turn again: the failed
+     * attempt only showed text or reasoning, before any checkpoint. Cursor CLI
+     * resends the same action in this case.
+     */
+    hostRetryable;
+    /** What the failed attempt did that a replay inside the Run would repeat. */
+    replayBarrier;
     constructor(message, options) {
         super(message, options.cause === undefined ? undefined : { cause: options.cause });
         this.name = "CursorProviderError";
@@ -25,8 +36,82 @@ export class CursorProviderError extends Error {
         this.rstCode = options.rstCode;
         this.code = options.code;
         this.retryAfterMs = options.retryAfterMs;
+        this.retryable = options.retryable;
+        this.hostRetryable = options.hostRetryable;
     }
 }
+/** Connect error code → HTTP status, per https://connectrpc.com/docs/protocol/#error-codes. */
+const CONNECT_CODE_HTTP_STATUS = {
+    canceled: 499,
+    unknown: 500,
+    invalid_argument: 400,
+    deadline_exceeded: 504,
+    not_found: 404,
+    already_exists: 409,
+    permission_denied: 403,
+    resource_exhausted: 429,
+    failed_precondition: 400,
+    aborted: 409,
+    out_of_range: 400,
+    unimplemented: 501,
+    internal: 500,
+    unavailable: 503,
+    data_loss: 500,
+    unauthenticated: 401,
+};
+/** Status for a final failure whose Connect code maps to 5xx (internal, unknown, …). */
+const NON_RETRYABLE_SERVER_STATUS = 400;
+/**
+ * The error the host receives. Like Cursor CLI, a request Cursor declared not
+ * retryable (see `cursorCliRetryable`), a spent/unsafe provider retry, or an
+ * authentication failure ends the turn: it becomes an AI SDK `APICallError`
+ * with `isRetryable: false` and the
+ * conventional `x-should-retry: false` header, which OpenCode 2 checks first
+ * (it retries a failure with no status or recognized code). OpenCode 1.x
+ * ignores both and retries any status >= 500 or a message matching its retry
+ * patterns, so the status is the Connect code's HTTP status capped below 500
+ * (Cursor CLI decides from the verdict, never the code) and the message is
+ * sanitized. The original code stays on `cause`.
+ *
+ * A `hostRetryable` failure is the opposite: Cursor CLI would send the same
+ * action again, but output the host already shows stops the provider from
+ * doing so. It becomes an `APICallError` with `isRetryable: true`, which
+ * OpenCode 1.x retries as the same step, and `x-should-retry: true` without a
+ * status, which OpenCode 2 continues after the shown output.
+ */
+export function hostFacingError(error) {
+    if (!(error instanceof Error))
+        return new Error(String(error));
+    const auth = error instanceof CursorAuthError;
+    if (!auth && error instanceof CursorProviderError && error.hostRetryable) {
+        return new APICallError({
+            message: error.message,
+            url: "cursor://agent.v1.AgentService/Run",
+            requestBodyValues: {},
+            responseHeaders: {
+                "x-should-retry": "true",
+                ...(error.retryAfterMs === undefined ? {} : { "retry-after-ms": String(error.retryAfterMs) }),
+            },
+            isRetryable: true,
+            cause: error,
+        });
+    }
+    if (!auth && (!(error instanceof CursorProviderError) || error.retryable !== false))
+        return error;
+    const connectStatus = error.code !== undefined && Object.hasOwn(CONNECT_CODE_HTTP_STATUS, error.code)
+        ? CONNECT_CODE_HTTP_STATUS[error.code]
+        : CONNECT_CODE_HTTP_STATUS.unknown;
+    const status = auth ? (error.statusCode === 403 ? 403 : 401) : connectStatus;
+    return new APICallError({
+        message: sanitizeHostTerminalMessage(error.message),
+        url: "cursor://agent.v1.AgentService/Run",
+        requestBodyValues: {},
+        statusCode: status >= 500 ? NON_RETRYABLE_SERVER_STATUS : status,
+        responseHeaders: { "x-should-retry": "false" },
+        isRetryable: false,
+        cause: error,
+    });
+}
 export class CursorLocalCancellationError extends CursorProviderError {
     constructor(message = "Cursor request cancelled locally", cause) {
         super(message, {
@@ -92,22 +177,53 @@ export function isRejectedCredentialError(error) {
         isUnauthenticatedStatus(error.code));
 }
 /**
- * OpenCode's SessionRetry treats several substrings in provider error messages
- * as always-retryable — notably bare "unavailable" and "exhausted", plus a
- * broader regex set (resource_exhausted, service unavailable, …).
- *
- * When this provider has already spent its Run retry budget, or has decided a
- * replay would be unsafe, the host-facing message must not re-arm that loop.
- * Keep the real gRPC/HTTP code on structured fields (`code`, `grpcStatus`).
+ * OpenCode 1.x SessionRetry retries an error whose message matches these
+ * patterns even when it is marked non-retryable (`RETRYABLE_MESSAGE_PATTERNS`
+ * and the `exhausted` / `unavailable` / `too_many_requests` substrings in
+ * upstream `packages/opencode/src/session/retry.ts`, v1.19). The status
+ * patterns match anywhere, so "$1500" or "500k" also re-arm it.
+ */
+const HOST_RETRY_MESSAGE_PATTERNS = [
+    /429|500|502|503|504|524/gi,
+    /rate increased too quickly|rate limit|rate-limit|rate_limit|too many requests|too_many_requests/gi,
+    /overloaded|service unavailable|service_unavailable|service-unavailable|internal error|internal_error|internal server error|server error|server_error|server-error|provider returned error|provider_returned_error|provider-returned-error/gi,
+    /terminated|fetch failed|failed to fetch|network[-_\s]error|upstream connect|connection error|connection refused|connection lost|socket connection was closed|socket hang up|reset before headers|getaddrinfo|enotfound|eai_again|econnrefused|econnreset|etimedout/gi,
+    /^timeout$|\b(?:request|response|connection|network|stream|read) (?:timeout|timed out|time out)\b/gi,
+    /try your request again|retry your request|resource exhausted|resource_exhausted/gi,
+    /\btry again (?:later|in\b)|\b(?:currently|temporarily) at capacity\b/gi,
+    /exhausted|unavailable/gi,
+];
+/** Invisible U+2060 WORD JOINER: the text reads the same but no longer matches. */
+const WORD_JOINER = "\u2060";
+/**
+ * When this provider has already spent its Run retry budget, decided a replay
+ * would be unsafe, or Cursor declared the request not retryable, the
+ * host-facing message must not re-arm OpenCode's SessionRetry loop. Common
+ * trigger words get readable replacements; any remaining match (status-like
+ * digits, Cursor's own wording) is split with a word joiner. Keep the real
+ * gRPC/HTTP code on structured fields (`code`, `grpcStatus`).
  */
 export function sanitizeHostTerminalMessage(message) {
-    return message
+    let text = message
         .replace(/\bresource[_\s-]?exhausted\b/gi, "capacity_limit")
         .replace(/\bservice[_\s-]?unavailable\b/gi, "capacity_limit")
         .replace(/\bunavailable\b/gi, "capacity_limit")
         .replace(/\boverloaded\b/gi, "capacity_limit")
         .replace(/\bretry exhausted\b/gi, "retries finished")
         .replace(/\bexhausted\b/gi, "finished");
+    // A joiner can add a `\b` boundary, so repeat until nothing matches.
+    for (let pass = 0; pass < 4; pass++) {
+        let changed = false;
+        for (const pattern of HOST_RETRY_MESSAGE_PATTERNS) {
+            text = text.replace(pattern, (match) => {
+                changed = true;
+                return `${match[0]}${WORD_JOINER}${match.slice(1)}`;
+            });
+        }
+        if (!changed)
+            break;
+    }
+    return text;
 }
 export class CursorRetryExhaustedError extends CursorProviderError {
     attempts;
@@ -118,6 +234,7 @@ export class CursorRetryExhaustedError extends CursorProviderError {
             origin: last.origin,
             transient: false,
             replaySafe: false,
+            retryable: false,
             statusCode: last.statusCode,
             grpcStatus: last.grpcStatus,
             rstCode: last.rstCode,
@@ -227,12 +344,50 @@ export function toCursorProviderError(error, options = { replaySafe: false }) {
         cause: error,
     });
 }
+/**
+ * A transient failure after the attempt showed only text or reasoning, before
+ * any checkpoint of the turn. Cursor CLI sends the same action again; the host
+ * does that here (see `hostFacingError`), and the lost-request record carries
+ * the user's request once.
+ */
+export function hostRetryError(cause, beforeOutput = false) {
+    return new CursorProviderError(beforeOutput
+        ? `${cause.message}; the Run could not start and the turn can be sent again`
+        : `${cause.message} after visible output, before Cursor saved a checkpoint; the turn can be sent again`, {
+        origin: cause.origin,
+        transient: false,
+        replaySafe: false,
+        hostRetryable: true,
+        statusCode: cause.statusCode,
+        grpcStatus: cause.grpcStatus,
+        rstCode: cause.rstCode,
+        code: cause.code,
+        retryAfterMs: cause.retryAfterMs,
+        cause,
+    });
+}
+/**
+ * Cursor CLI stops automatic resumes after two resumed attempts that streamed
+ * but saved no checkpoint, so the turn does not repeat the same work forever.
+ */
+export function noProgressResumeError(cause, resumes) {
+    return new CursorProviderError(`Cursor Run stopped after ${resumes} resume attempts made no progress; ` +
+        "send a message to continue from the last saved state", {
+        origin: cause.origin,
+        transient: false,
+        replaySafe: false,
+        retryable: false,
+        code: cause.code,
+        cause,
+    });
+}
 export function retrySuppressedError(cause, reason, attempt, maxAttempts) {
     const subject = sanitizeHostTerminalMessage(cause.message.replace(/^Cursor Run stream /, "Cursor stream "));
     return new CursorProviderError(`${subject} ${reason}; automatic retry unsafe (attempt ${attempt}/${maxAttempts})`, {
         origin: cause.origin,
         transient: false,
         replaySafe: false,
+        retryable: false,
         statusCode: cause.statusCode,
         grpcStatus: cause.grpcStatus,
         rstCode: cause.rstCode,

package/dist/host-agent-mode.d.ts

@@ -4,19 +4,68 @@
  * The language model stays host-neutral: it records a canonical Cursor mode
  * (`plan`, `spec`, `agent`, ...). A host entrypoint may install this structural
  * callback when its public API can select the corresponding primary agent.
- * OpenCode 2.0 uses it to select its vendor-maintained `plan` / `build` agents;
- * OpenCode 1.x continues to use advertised `plan_enter` / `plan_exit` tools.
+ * OpenCode 2.0 uses it to select its vendor-maintained `plan` / `build` agents
+ * and continues the turn via `session.synthetic` (OpenCode 2 `switchAgent`
+ * only publishes the agent and would otherwise idle).
+ * On OpenCode 1.x hosts, advertised `plan_enter` / `plan_exit` tools stay
+ * authoritative; without `plan_enter`, the classic entrypoint selects the
+ * `plan` agent the 1.x way, with a synthetic user message for that agent.
  */
 export type HostAgentModeSwitchInput = {
     sessionID: string;
     targetModeID: string;
     /** Concrete Cursor Run that owns the switch. */
     cursorSessionID?: string;
+    /** Host primary agent the owning Run executed under, when the host reported it. */
+    hostAgent?: string;
 };
 export type HostAgentModeSwitchFn = (input: HostAgentModeSwitchInput) => void | Promise<void>;
-export declare function setHostAgentModeSwitch(fn: HostAgentModeSwitchFn | undefined): void;
-/** Queue only when this host installed a native primary-agent switch. */
+export type HostAgentModeSwitchOptions = {
+    /** The switch also starts the host turn that continues the conversation. */
+    resumesTurn?: boolean;
+    /** Queue-time filter: a request the switch would not apply stays provider-owned. */
+    accepts?: (input: HostAgentModeSwitchInput) => boolean;
+};
+/** Synthetic user text that carries an OpenCode 1.x primary-agent switch. */
+export declare function hostAgentSwitchPromptText(agent: "plan" | "build"): string;
+/**
+ * OpenCode 1.x shape of the switch: a 1.x session runs each turn under the
+ * agent of its latest user message, which is how the host's own plan_enter /
+ * plan_exit change agents.
+ *
+ * It accepts only a real transition of a session running one of the host's
+ * own primary agents: entering an existing `plan` agent from another primary
+ * agent, or leaving the observed `plan` agent. Subagent and hidden internal
+ * sessions (title, summary, compaction, task children) never get a user turn
+ * injected.
+ */
+export declare function createPromptHostAgentModeSwitch(prompt: (input: {
+    sessionID: string;
+    agent: "plan" | "build";
+    text: string;
+}) => Promise<unknown>, primaryAgents: () => ReadonlySet<string> | undefined): {
+    apply: HostAgentModeSwitchFn;
+    accepts: (input: HostAgentModeSwitchInput) => boolean;
+};
+/**
+ * Install this host's native switch; it is used until a newer one is
+ * installed. The returned disposer removes only this switch, so disposing an
+ * older setup never removes a newer setup's switch. `undefined` removes all.
+ */
+export declare function setHostAgentModeSwitch(fn: HostAgentModeSwitchFn | undefined, options?: HostAgentModeSwitchOptions): () => void;
+/**
+ * How this host applies a Cursor mode switch to its primary agents: `resumes`
+ * when the switch also starts the next host turn, `next-turn` when the user's
+ * next message runs under the new agent, undefined without a native switch.
+ */
+export declare function hostAgentModeSwitchKind(): "resumes" | "next-turn" | undefined;
+/** Queue only when this host installed a native primary-agent switch that accepts the request. */
 export declare function queueHostAgentModeSwitch(input: HostAgentModeSwitchInput): boolean;
+/**
+ * True while an approved switch into the host `plan` agent waits for its Run to
+ * end and will itself start the plan-agent turn that continues the work.
+ */
+export declare function isHostPlanEntryPending(sessionID: string | undefined): boolean;
 export declare function cancelHostAgentModeSwitch(sessionID: string | undefined): void;
 /**
  * Apply the switch only after its Cursor Run is terminal and owns no pending

package/dist/host-agent-mode.js

@@ -4,28 +4,111 @@
  * The language model stays host-neutral: it records a canonical Cursor mode
  * (`plan`, `spec`, `agent`, ...). A host entrypoint may install this structural
  * callback when its public API can select the corresponding primary agent.
- * OpenCode 2.0 uses it to select its vendor-maintained `plan` / `build` agents;
- * OpenCode 1.x continues to use advertised `plan_enter` / `plan_exit` tools.
+ * OpenCode 2.0 uses it to select its vendor-maintained `plan` / `build` agents
+ * and continues the turn via `session.synthetic` (OpenCode 2 `switchAgent`
+ * only publishes the agent and would otherwise idle).
+ * On OpenCode 1.x hosts, advertised `plan_enter` / `plan_exit` tools stay
+ * authoritative; without `plan_enter`, the classic entrypoint selects the
+ * `plan` agent the 1.x way, with a synthetic user message for that agent.
  */
 import { errorMessage, trace } from "./debug.js";
-let switchHostAgent;
+/**
+ * Live switches, newest last. A host may set the plugin up more than once in
+ * one process (one setup per location instance, re-setup on plugin reload) and
+ * dispose an older setup after a newer one installed its switch.
+ */
+const registrations = [];
+function activeSwitch() {
+    return registrations[registrations.length - 1];
+}
 const pending = new Map();
+const applying = new Map();
 const MAX_PENDING_HOST_AGENT_SWITCHES = 256;
-export function setHostAgentModeSwitch(fn) {
-    switchHostAgent = fn;
-    if (!fn)
+/** True for Cursor mode ids served by the host's `plan` primary agent. */
+function isPlanModeID(targetModeID) {
+    const mode = targetModeID.trim().toLowerCase();
+    return mode === "plan" || mode === "spec";
+}
+/** Synthetic user text that carries an OpenCode 1.x primary-agent switch. */
+export function hostAgentSwitchPromptText(agent) {
+    return agent === "plan"
+        ? "Plan mode is now active. Continue planning the request above under the plan-mode " +
+            "instructions, and do not implement anything until the plan is approved."
+        : "Plan mode has ended. Continue with the approved work.";
+}
+/**
+ * OpenCode 1.x shape of the switch: a 1.x session runs each turn under the
+ * agent of its latest user message, which is how the host's own plan_enter /
+ * plan_exit change agents.
+ *
+ * It accepts only a real transition of a session running one of the host's
+ * own primary agents: entering an existing `plan` agent from another primary
+ * agent, or leaving the observed `plan` agent. Subagent and hidden internal
+ * sessions (title, summary, compaction, task children) never get a user turn
+ * injected.
+ */
+export function createPromptHostAgentModeSwitch(prompt, primaryAgents) {
+    return {
+        accepts: ({ targetModeID, hostAgent }) => {
+            const agents = primaryAgents();
+            const current = hostAgent?.trim();
+            if (!agents || !current || !agents.has(current))
+                return false;
+            return isPlanModeID(targetModeID) ? current !== "plan" && agents.has("plan") : current === "plan";
+        },
+        apply: async ({ sessionID, targetModeID }) => {
+            const agent = isPlanModeID(targetModeID) ? "plan" : "build";
+            await prompt({ sessionID, agent, text: hostAgentSwitchPromptText(agent) });
+        },
+    };
+}
+/**
+ * Install this host's native switch; it is used until a newer one is
+ * installed. The returned disposer removes only this switch, so disposing an
+ * older setup never removes a newer setup's switch. `undefined` removes all.
+ */
+export function setHostAgentModeSwitch(fn, options = {}) {
+    if (!fn) {
+        registrations.length = 0;
         pending.clear();
+        return () => { };
+    }
+    const registration = { fn, options };
+    registrations.push(registration);
+    return () => {
+        const index = registrations.lastIndexOf(registration);
+        if (index >= 0)
+            registrations.splice(index, 1);
+        if (registrations.length === 0)
+            pending.clear();
+    };
 }
-/** Queue only when this host installed a native primary-agent switch. */
+/**
+ * How this host applies a Cursor mode switch to its primary agents: `resumes`
+ * when the switch also starts the next host turn, `next-turn` when the user's
+ * next message runs under the new agent, undefined without a native switch.
+ */
+export function hostAgentModeSwitchKind() {
+    const active = activeSwitch();
+    if (!active)
+        return undefined;
+    return active.options.resumesTurn === true ? "resumes" : "next-turn";
+}
+/** Queue only when this host installed a native primary-agent switch that accepts the request. */
 export function queueHostAgentModeSwitch(input) {
     const sessionID = input.sessionID.trim();
     const targetModeID = input.targetModeID.trim();
-    if (!switchHostAgent || !sessionID || !targetModeID)
+    const active = activeSwitch();
+    if (!active || !sessionID || !targetModeID)
         return false;
+    if (active.options.accepts && !active.options.accepts({ ...input, sessionID, targetModeID }))
+        return false;
+    const hostAgent = input.hostAgent?.trim();
     pending.set(sessionID, {
         sessionID,
         targetModeID,
         ...(input.cursorSessionID ? { cursorSessionID: input.cursorSessionID } : {}),
+        ...(hostAgent ? { hostAgent } : {}),
         attempts: 0,
     });
     while (pending.size > MAX_PENDING_HOST_AGENT_SWITCHES) {
@@ -38,6 +121,17 @@ export function queueHostAgentModeSwitch(input) {
         `cursorSessionID=${input.cursorSessionID ?? ""} target=${targetModeID}`);
     return true;
 }
+/**
+ * True while an approved switch into the host `plan` agent waits for its Run to
+ * end and will itself start the plan-agent turn that continues the work.
+ */
+export function isHostPlanEntryPending(sessionID) {
+    if (activeSwitch()?.options.resumesTurn !== true)
+        return false;
+    const key = sessionID?.trim();
+    const target = key ? pending.get(key)?.targetModeID : undefined;
+    return target !== undefined && isPlanModeID(target);
+}
 export function cancelHostAgentModeSwitch(sessionID) {
     const key = sessionID?.trim();
     if (key)
@@ -53,7 +147,8 @@ export async function flushHostAgentModeSwitch(sessionID, options = {}) {
     if (!key)
         return false;
     const state = pending.get(key);
-    if (!state || !switchHostAgent)
+    const apply = activeSwitch()?.fn;
+    if (!state || !apply || applying.has(key))
         return false;
     if (options.terminal !== true || options.pumpActive || (options.pendingExecs ?? 0) > 0) {
         return false;
@@ -70,9 +165,12 @@ export async function flushHostAgentModeSwitch(sessionID, options = {}) {
         return false;
     }
     state.attempts += 1;
+    applying.set(key, state);
     try {
-        await switchHostAgent(state);
-        pending.delete(key);
+        await apply(state);
+        // A request queued during the callback belongs to a later transition.
+        if (pending.get(key) === state)
+            pending.delete(key);
         trace(`host-agent-mode: switched sessionID=${key} target=${state.targetModeID}`);
         return true;
     }
@@ -80,13 +178,19 @@ export async function flushHostAgentModeSwitch(sessionID, options = {}) {
         // Keep the request pending so a later explicit provider turn can retry at
         // its own terminal boundary. The provider-owned mode reminder remains the
         // behavioral fallback until the native host switch succeeds.
-        delete state.cursorSessionID;
+        if (pending.get(key) === state)
+            delete state.cursorSessionID;
         trace(`host-agent-mode: FAILED sessionID=${key} target=${state.targetModeID} ` +
             `attempts=${state.attempts} err=${errorMessage(error)}`);
         return false;
     }
+    finally {
+        if (applying.get(key) === state)
+            applying.delete(key);
+    }
 }
 export function resetHostAgentModeSwitchForTests() {
-    switchHostAgent = undefined;
+    registrations.length = 0;
     pending.clear();
+    applying.clear();
 }

package/dist/host-interrupt.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `openCodeSessionId` undefined: every session (the host is shutting down).
+ * `at`: when the host stopped, on this process's clock.
+ */
+export type HostInterruptListener = (openCodeSessionId: string | undefined, reason: string, at: number) => void | Promise<void>;
+export declare function onHostInterrupt(listener: HostInterruptListener): () => void;
+/**
+ * The host stopped this session's execution (OpenCode 2 never aborts `doStream`
+ * for it). `reason: "shutdown"` keeps the turn for the next server start: its
+ * state is saved, nothing is cancelled. Resolves once every listener settled.
+ */
+export declare function notifyHostInterrupt(openCodeSessionId: string | undefined, reason: string, at?: number): Promise<void>;

package/dist/host-interrupt.js

@@ -0,0 +1,18 @@
+// OpenCode 2 can evaluate the plugin and the AI SDK model as separate copies
+// of this module (one per Location); the copy holding the Run must hear the
+// plugin's interrupt.
+const LISTENERS = Symbol.for("cursor-opencode-provider.host-interrupt-listeners");
+const globals = globalThis;
+const listeners = globals[LISTENERS] ??= new Set();
+export function onHostInterrupt(listener) {
+    listeners.add(listener);
+    return () => { listeners.delete(listener); };
+}
+/**
+ * The host stopped this session's execution (OpenCode 2 never aborts `doStream`
+ * for it). `reason: "shutdown"` keeps the turn for the next server start: its
+ * state is saved, nothing is cancelled. Resolves once every listener settled.
+ */
+export async function notifyHostInterrupt(openCodeSessionId, reason, at = Date.now()) {
+    await Promise.allSettled([...listeners].map(async (listener) => listener(openCodeSessionId, reason, at)));
+}

package/dist/host-plan-file.d.ts

@@ -0,0 +1,28 @@
+/**
+ * OpenCode's own plan file per session, resolved while the session runs under
+ * the `plan` agent. CreatePlan records the plan there so the `plan_exit` review
+ * reads exactly the file the user approves.
+ *
+ * Resolution is structural: session `slug` / `time.created` from the classic
+ * client, project VCS and worktree from the plugin input, and the location
+ * from OpenCode's `Session.plan` rule (or an injected host path bridge).
+ */
+export declare function hostPlanFileFor(sessionID: string | undefined): string | undefined;
+/** True once the session's plan file is known, including known to be absent. */
+export declare function isHostPlanFileResolved(sessionID: string | undefined): boolean;
+/**
+ * Record a session's plan file. `null` records that the host defines none, so
+ * it is not looked up again; `undefined` forgets it, so the next request retries.
+ */
+export declare function setHostPlanFile(sessionID: string, file: string | null | undefined): void;
+export declare function resetHostPlanFilesForTests(): void;
+/**
+ * Resolve and remember the host plan file for one session. A session without
+ * one is remembered as such; a failed lookup is not, so a later request retries.
+ */
+export declare function resolveHostPlanFile(input: {
+    sessionID: string;
+    getSession: (sessionID: string) => Promise<unknown>;
+    worktree: string | undefined;
+    vcs: boolean;
+}): Promise<string | undefined>;

package/dist/host-plan-file.js

@@ -0,0 +1,76 @@
+/**
+ * OpenCode's own plan file per session, resolved while the session runs under
+ * the `plan` agent. CreatePlan records the plan there so the `plan_exit` review
+ * reads exactly the file the user approves.
+ *
+ * Resolution is structural: session `slug` / `time.created` from the classic
+ * client, project VCS and worktree from the plugin input, and the location
+ * from OpenCode's `Session.plan` rule (or an injected host path bridge).
+ */
+import { hostPlanFilePath } from "./context/paths.js";
+import { errorMessage, trace } from "./debug.js";
+/** Session → its plan file, or `null` when the host defines none for it. */
+const hostPlanFiles = new Map();
+const MAX_HOST_PLAN_FILES = 256;
+export function hostPlanFileFor(sessionID) {
+    const key = sessionID?.trim();
+    return (key ? hostPlanFiles.get(key) : undefined) ?? undefined;
+}
+/** True once the session's plan file is known, including known to be absent. */
+export function isHostPlanFileResolved(sessionID) {
+    const key = sessionID?.trim();
+    return !!key && hostPlanFiles.has(key);
+}
+/**
+ * Record a session's plan file. `null` records that the host defines none, so
+ * it is not looked up again; `undefined` forgets it, so the next request retries.
+ */
+export function setHostPlanFile(sessionID, file) {
+    const key = sessionID.trim();
+    if (!key)
+        return;
+    hostPlanFiles.delete(key);
+    if (file === undefined || file === "")
+        return;
+    hostPlanFiles.set(key, file);
+    while (hostPlanFiles.size > MAX_HOST_PLAN_FILES) {
+        const oldest = hostPlanFiles.keys().next().value;
+        if (!oldest)
+            break;
+        hostPlanFiles.delete(oldest);
+    }
+}
+export function resetHostPlanFilesForTests() {
+    hostPlanFiles.clear();
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * Resolve and remember the host plan file for one session. A session without
+ * one is remembered as such; a failed lookup is not, so a later request retries.
+ */
+export async function resolveHostPlanFile(input) {
+    try {
+        const response = record(await input.getSession(input.sessionID));
+        const info = record(response?.data) ?? response;
+        const slug = typeof info?.slug === "string" ? info.slug : "";
+        const created = record(info?.time)?.created;
+        if (!slug || typeof created !== "number" || !input.worktree) {
+            setHostPlanFile(input.sessionID, null);
+            return undefined;
+        }
+        const file = hostPlanFilePath({ worktree: input.worktree, vcs: input.vcs, created, slug });
+        setHostPlanFile(input.sessionID, file ?? null);
+        if (file)
+            trace(`host-plan-file: sessionID=${input.sessionID} file=${file}`);
+        return file;
+    }
+    catch (error) {
+        trace(`host-plan-file: unresolved sessionID=${input.sessionID} err=${errorMessage(error)}`);
+        setHostPlanFile(input.sessionID, undefined);
+        return undefined;
+    }
+}