cursor-opencode-provider 0.7.6 → 0.8.1

package/dist/model-config.d.ts

@@ -8,6 +8,15 @@ import { type ModelInfo, type ModelVariant } from "./models.js";
  * tagged redundantly.
  */
 export declare function thinkingSuffixBaseNames(models: ModelInfo[]): Set<string>;
+/**
+ * models.dev-style family for a Cursor model id: the id without its version
+ * segments and context/speed suffixes (`claude-haiku-4-5` → `claude-haiku`,
+ * `gemini-3.8-flash` → `gemini-flash`, `gpt-5.6-luna` → `gpt-luna`).
+ * Kimi keeps its major generation (`kimi-k2.7-code` → `kimi-k2`). OpenCode
+ * picks its small title model by family and falls back to the session model when
+ * no entry has one. Cursor Auto (`default`) is not a model family.
+ */
+export declare function cursorModelFamily(id: string): string | undefined;
 export declare function modelInfoToConfig(mi: ModelInfo, options?: {
     thinkingSuffix?: boolean;
     contextTier?: "base" | "long";

package/dist/model-config.js

@@ -91,7 +91,7 @@ function modelInfoVariants(mi, variants) {
         // variant entry indistinguishable from the model entry in pickers that
         // collapse them.
         if (key === baseName && !usedKeys.has(key)) {
-            key = `${baseName}${tagDims(v.parameterValues)}` || `${baseName} default`;
+            key = `${baseName}${tagDims(v.parameterValues) || " default"}`;
         }
         else if (usedKeys.has(key)) {
             key = `${sanitized}${tagDims(v.parameterValues)}`;
@@ -140,6 +140,27 @@ export function thinkingSuffixBaseNames(models) {
             ambiguous.add(base);
     return ambiguous;
 }
+/**
+ * models.dev-style family for a Cursor model id: the id without its version
+ * segments and context/speed suffixes (`claude-haiku-4-5` → `claude-haiku`,
+ * `gemini-3.8-flash` → `gemini-flash`, `gpt-5.6-luna` → `gpt-luna`).
+ * Kimi keeps its major generation (`kimi-k2.7-code` → `kimi-k2`). OpenCode
+ * picks its small title model by family and falls back to the session model when
+ * no entry has one. Cursor Auto (`default`) is not a model family.
+ */
+export function cursorModelFamily(id) {
+    if (id === "default")
+        return undefined;
+    const base = id.replace(/(?:-(?:1m|fast))+$/, "");
+    const kimi = /^kimi-(k\d+)(?:[.p]\d+)*(?:-code(?:-highspeed)?)?$/.exec(base);
+    if (kimi)
+        return `kimi-${kimi[1]}`;
+    const family = base
+        .split("-")
+        .filter((part) => !/^\d+(?:[.p]\d+)*$/.test(part))
+        .join("-");
+    return family || undefined;
+}
 export function modelInfoToConfig(mi, options = {}) {
     const contextTier = options.contextTier ?? "base";
     const variants = options.variants ?? variantsForTier(mi, contextTier);
@@ -182,6 +203,12 @@ export function modelInfoToConfig(mi, options = {}) {
             output,
         },
     };
+    // Optional cache metadata may supply a family; the live AvailableModels
+    // schema has no family field. Empty metadata must not block derivation.
+    const reported = typeof mi.family === "string" ? mi.family.trim() : "";
+    const family = reported || cursorModelFamily(mi.id);
+    if (family)
+        config.family = family;
     const variantConfig = modelInfoVariants(mi, variants);
     if (variantConfig)
         config.variants = variantConfig;

package/dist/opencode2/catalog.d.ts

@@ -36,6 +36,7 @@ export type CatalogModelInfo = {
     modelID: string;
     providerID: string;
     name: string;
+    family?: string;
     capabilities: {
         tools: boolean;
         input: string[];

package/dist/opencode2/catalog.js

@@ -69,6 +69,8 @@ export function modelConfigEntryToInfo(id, entry) {
         time: { released: 0 },
         cost: toOpenCode2Costs(entry.cost),
     };
+    if (typeof entry.family === "string" && entry.family.trim())
+        info.family = entry.family.trim();
     if (options)
         info.settings = { ...options };
     return info;

package/dist/opencode2/image-save-tool.d.ts

@@ -0,0 +1,8 @@
+import type { PluginContext, ToolDraft } from "./types.js";
+/**
+ * Register the handle-only image commit tool on the OpenCode 2.0 direct
+ * catalog. Catalog `permission: "edit"` hides it when the host agent denies
+ * edits. Per-call `ask` is used when the runtime context provides it;
+ * otherwise containment still gates the write (opaque `image_id` only).
+ */
+export declare function registerCursorImageSaveTool(draft: ToolDraft, ctx: PluginContext): void;

package/dist/opencode2/image-save-tool.js

@@ -0,0 +1,84 @@
+import { executeCursorImageSave } from "../image-save.js";
+import { cursorImageSaveTool } from "../image-save-tool.js";
+import { CURSOR_IMAGE_SAVE_TOOL } from "../protocol/generate-image.js";
+import { getSessionDirectory } from "../session-directory.js";
+import { hostHasTool, OPENCODE2_DIRECT_TOOL_OPTIONS } from "./todo-tools.js";
+const IMAGE_SAVE_INPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        image_id: {
+            type: "string",
+            description: "Id of the pending Cursor-generated image to save",
+        },
+    },
+    required: ["image_id"],
+};
+const IMAGE_SAVE_OUTPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        path: { type: "string" },
+        bytes: { type: "number" },
+        message: { type: "string" },
+    },
+    required: ["path", "bytes", "message"],
+};
+function toolAsk(context) {
+    if (!context || typeof context !== "object")
+        return undefined;
+    const ask = context.ask;
+    return typeof ask === "function"
+        ? ask
+        : undefined;
+}
+async function workspaceForSession(ctx, sessionID) {
+    const marked = getSessionDirectory(sessionID);
+    if (marked)
+        return marked;
+    try {
+        return (await ctx.session.get({ sessionID })).location.directory;
+    }
+    catch {
+        return ctx.location?.directory || process.cwd();
+    }
+}
+/**
+ * Register the handle-only image commit tool on the OpenCode 2.0 direct
+ * catalog. Catalog `permission: "edit"` hides it when the host agent denies
+ * edits. Per-call `ask` is used when the runtime context provides it;
+ * otherwise containment still gates the write (opaque `image_id` only).
+ */
+export function registerCursorImageSaveTool(draft, ctx) {
+    if (hostHasTool(draft, CURSOR_IMAGE_SAVE_TOOL))
+        return;
+    draft.add({
+        name: CURSOR_IMAGE_SAVE_TOOL,
+        description: cursorImageSaveTool.description,
+        input: IMAGE_SAVE_INPUT_SCHEMA,
+        output: IMAGE_SAVE_OUTPUT_SCHEMA,
+        options: { ...OPENCODE2_DIRECT_TOOL_OPTIONS, permission: "edit" },
+        execute: async (input, context) => {
+            const sessionID = context.sessionID;
+            if (typeof sessionID !== "string" || !sessionID) {
+                throw new Error("OpenCode 2.0 image-save context did not provide a sessionID");
+            }
+            const directory = await workspaceForSession(ctx, sessionID);
+            const result = await executeCursorImageSave({ image_id: input?.image_id }, {
+                worktree: directory,
+                directory,
+                // The public 2.0 ToolContext has no permission prompt; catalog
+                // `permission: "edit"` and containment gate the write instead.
+                ask: toolAsk(context) ?? null,
+            });
+            return {
+                output: {
+                    path: result.title,
+                    bytes: result.bytes,
+                    message: result.output,
+                },
+                content: result.output,
+            };
+        },
+    });
+}

package/dist/opencode2/integration.d.ts

@@ -1,4 +1,5 @@
-import type { CredentialValue, IntegrationDomain, IntegrationDraft } from "./types.js";
+import { type AccessTokenRequest } from "../auth-renewal.js";
+import type { CredentialOAuth, CredentialValue, IntegrationDomain, IntegrationDraft } from "./types.js";
 /**
  * Integration registration for the OpenCode 2.0 plugin — the replacement for the
  * classic plugin's `auth` hook (`methods` + `loader`).
@@ -9,15 +10,37 @@ import type { CredentialValue, IntegrationDomain, IntegrationDraft } from "./typ
 export declare const CURSOR_OAUTH_METHOD_ID = "oauth";
 /** Env vars that can supply a Cursor API key without running /connect. */
 export declare const CURSOR_ENV_NAMES: string[];
+/**
+ * Host-driven session renewal (`POST /oauth/token`, as Cursor's IDE does).
+ * OpenCode 2.0 calls this when the stored `expires` is within five minutes
+ * (`packages/core/src/integration.ts`, `connection.resolve`) and persists the
+ * result. A session this process already renewed in memory is handed over
+ * instead of renewed again. A transient failure returns the unchanged session
+ * with `expires` moved to the next allowed attempt, so the host keeps working
+ * and asks again later; only a session Cursor ended, or one that expired
+ * unrenewed, throws.
+ */
+export declare function refreshOAuth(credential: CredentialOAuth): Promise<CredentialOAuth>;
 /** Register the Cursor integration and its three connection methods. */
 export declare function applyCursorIntegration(draft: IntegrationDraft): void;
 /**
- * Turn a stored credential into a Cursor access token.
+ * Turn a stored credential into a Cursor access token. The two credential
+ * kinds are handled separately and never substitute for each other.
+ *
+ * - `oauth`: the session token, renewed in memory once it is due by Cursor's
+ *   IDE window (the host itself refreshes only in the last five minutes; it
+ *   then persists the renewal through `refreshOAuth`).
+ * - `key`: a raw `crsr_…` API key (from /connect or `CURSOR_API_KEY`),
+ *   exchanged for a short-lived JWT and re-exchanged near its expiry. Any
+ *   other value is an already-issued token and is used as-is.
  *
- * OAuth credentials already hold a JWT (the host refreshes them via `refresh`
- * above). A `key` credential is the raw `crsr_…` API key, which Cursor requires us
- * to exchange for a short-lived JWT — mirroring the classic plugin's behavior.
+ * Throws `CursorAuthError` when no usable token can be produced.
+ */
+export declare function accessTokenFromCredential(credential: CredentialValue | undefined, request?: AccessTokenRequest): Promise<string>;
+/**
+ * Current access token of the active Cursor connection, for a Run. Throws a
+ * `CursorAuthError` that says why when there is none.
  */
-export declare function accessTokenFromCredential(credential: CredentialValue | undefined): Promise<string | undefined>;
-/** Resolve the active Cursor connection into an access token, if any. */
+export declare function requireCursorAccessToken(integration: IntegrationDomain, request?: AccessTokenRequest): Promise<string>;
+/** Access token of the active Cursor connection, or undefined (model discovery). */
 export declare function resolveCursorAccessToken(integration: IntegrationDomain): Promise<string | undefined>;

package/dist/opencode2/integration.js

@@ -1,6 +1,9 @@
 import { CURSOR_WEBSITE_HOST } from "../shared.js";
 import { cursorApiBaseURL } from "../plugin-core.js";
-import { buildLoginUrl, decodeJwtExpiryMs, exchangeApiKey, generatePkceChallenge, generatePkceParams, isExpiringSoon, pollForTokens, refreshAccessToken, } from "../auth.js";
+import { buildLoginUrl, decodeJwtExpiryMs, generatePkceChallenge, generatePkceParams, isExchangeableApiKey, pollForTokens, } from "../auth.js";
+import { renewSessionIfDue, resolveApiKeyToken, } from "../auth-renewal.js";
+import { CursorAuthError, CursorProviderError } from "../errors.js";
+import { errorMessage } from "../debug.js";
 import { CURSOR_INTEGRATION_ID } from "./catalog.js";
 /**
  * Integration registration for the OpenCode 2.0 plugin — the replacement for the
@@ -15,6 +18,13 @@ export const CURSOR_ENV_NAMES = ["CURSOR_API_KEY"];
 function websiteURL() {
     return process.env.CURSOR_WEBSITE_URL ?? `https://${CURSOR_WEBSITE_HOST}`;
 }
+/** `expires` of a session credential: the JWT's own expiry, as OpenCode's built-in OAuth integrations store it. */
+function sessionExpires(token) {
+    return decodeJwtExpiryMs(token) ?? Date.now();
+}
+function sessionTokensOf(credential) {
+    return { accessToken: credential.access, refreshToken: credential.refresh || credential.access };
+}
 /** Browser (PKCE) login: open URL, then poll until Cursor hands back tokens. */
 async function authorizeOAuth() {
     const params = generatePkceParams();
@@ -30,23 +40,38 @@ async function authorizeOAuth() {
             methodID: CURSOR_OAUTH_METHOD_ID,
             access: result.accessToken,
             refresh: result.refreshToken,
-            expires: decodeJwtExpiryMs(result.accessToken) ?? Date.now(),
+            expires: sessionExpires(result.accessToken),
         })),
     };
 }
 /**
- * Renew an expiring Cursor JWT. The host calls this lazily when the stored
- * credential is close to expiry, so it must not assume it runs on every request.
+ * Host-driven session renewal (`POST /oauth/token`, as Cursor's IDE does).
+ * OpenCode 2.0 calls this when the stored `expires` is within five minutes
+ * (`packages/core/src/integration.ts`, `connection.resolve`) and persists the
+ * result. A session this process already renewed in memory is handed over
+ * instead of renewed again. A transient failure returns the unchanged session
+ * with `expires` moved to the next allowed attempt, so the host keeps working
+ * and asks again later; only a session Cursor ended, or one that expired
+ * unrenewed, throws.
  */
-async function refreshOAuth(credential) {
-    const tokens = await refreshAccessToken(credential.refresh, cursorApiBaseURL());
+export async function refreshOAuth(credential) {
+    const renewal = await renewSessionIfDue(sessionTokensOf(credential), { baseUrl: cursorApiBaseURL() });
+    const methodID = credential.methodID || CURSOR_OAUTH_METHOD_ID;
+    const metadata = credential.metadata === undefined ? {} : { metadata: credential.metadata };
+    if (renewal.renewed) {
+        return {
+            type: "oauth",
+            methodID,
+            access: renewal.accessToken,
+            refresh: renewal.accessToken,
+            expires: sessionExpires(renewal.accessToken),
+            ...metadata,
+        };
+    }
     return {
-        type: "oauth",
-        methodID: credential.methodID || CURSOR_OAUTH_METHOD_ID,
-        access: tokens.accessToken,
-        refresh: tokens.refreshToken,
-        expires: decodeJwtExpiryMs(tokens.accessToken) ?? Date.now(),
-        ...(credential.metadata === undefined ? {} : { metadata: credential.metadata }),
+        ...credential,
+        methodID,
+        expires: renewal.retryAt ?? sessionExpires(credential.access),
     };
 }
 /** Register the Cursor integration and its three connection methods. */
@@ -75,48 +100,52 @@ export function applyCursorIntegration(draft) {
     });
 }
 /**
- * Turn a stored credential into a Cursor access token.
+ * Turn a stored credential into a Cursor access token. The two credential
+ * kinds are handled separately and never substitute for each other.
  *
- * OAuth credentials already hold a JWT (the host refreshes them via `refresh`
- * above). A `key` credential is the raw `crsr_…` API key, which Cursor requires us
- * to exchange for a short-lived JWT — mirroring the classic plugin's behavior.
+ * - `oauth`: the session token, renewed in memory once it is due by Cursor's
+ *   IDE window (the host itself refreshes only in the last five minutes; it
+ *   then persists the renewal through `refreshOAuth`).
+ * - `key`: a raw `crsr_…` API key (from /connect or `CURSOR_API_KEY`),
+ *   exchanged for a short-lived JWT and re-exchanged near its expiry. Any
+ *   other value is an already-issued token and is used as-is.
+ *
+ * Throws `CursorAuthError` when no usable token can be produced.
  */
-export async function accessTokenFromCredential(credential) {
-    if (!credential)
-        return undefined;
-    if (credential.type === "oauth") {
-        if (credential.access && !isExpiringSoon(credential.access))
-            return credential.access;
-        if (!credential.refresh)
-            return credential.access || undefined;
-        try {
-            return (await refreshOAuth(credential)).access;
-        }
-        catch {
-            // Fall back to the existing token; the call may still succeed.
-            return credential.access || undefined;
-        }
+export async function accessTokenFromCredential(credential, request = {}) {
+    const force = request.forceRefresh === true;
+    if (credential?.type === "oauth") {
+        return (await renewSessionIfDue(sessionTokensOf(credential), { baseUrl: cursorApiBaseURL(), force })).accessToken;
     }
-    if (credential.type === "key") {
-        // Already a JWT (e.g. exchanged by an earlier run) — use it directly.
-        if (!credential.key.startsWith("crsr_"))
+    if (credential?.type === "key") {
+        if (!isExchangeableApiKey(credential.key))
             return credential.key;
-        try {
-            return (await exchangeApiKey(credential.key, cursorApiBaseURL())).accessToken;
-        }
-        catch {
-            return undefined;
-        }
+        return (await resolveApiKeyToken(credential.key, { baseUrl: cursorApiBaseURL(), force })).accessToken;
     }
-    return undefined;
+    throw new CursorAuthError("No Cursor login found; connect Cursor first", { code: "no_credential" });
 }
-/** Resolve the active Cursor connection into an access token, if any. */
-export async function resolveCursorAccessToken(integration) {
+/**
+ * Current access token of the active Cursor connection, for a Run. Throws a
+ * `CursorAuthError` that says why when there is none.
+ */
+export async function requireCursorAccessToken(integration, request = {}) {
+    let credential;
     try {
         const connection = await integration.connection.active(CURSOR_INTEGRATION_ID);
-        if (!connection)
-            return undefined;
-        return await accessTokenFromCredential(await integration.connection.resolve(connection));
+        credential = connection ? await integration.connection.resolve(connection) : undefined;
+    }
+    catch (error) {
+        // The host's resolve runs our refreshOAuth; keep its classified error.
+        if (error instanceof CursorProviderError)
+            throw error;
+        throw new CursorAuthError(`Cursor login could not be loaded (${errorMessage(error)})`, { cause: error });
+    }
+    return accessTokenFromCredential(credential, request);
+}
+/** Access token of the active Cursor connection, or undefined (model discovery). */
+export async function resolveCursorAccessToken(integration) {
+    try {
+        return await requireCursorAccessToken(integration);
     }
     catch {
         return undefined;

package/dist/opencode2/types.d.ts

@@ -43,6 +43,7 @@ export type ModelInfo2 = {
     modelID: string;
     providerID: string;
     name: string;
+    family?: string;
     capabilities: {
         tools: boolean;
         input: readonly string[];
@@ -415,6 +416,19 @@ export type McpEditor = {
 export type McpDomain = {
     readonly transform: Transform<McpEditor>;
 };
+/** Only the fields this plugin reads from a registered skill. */
+export type SkillInfo = {
+    readonly id: string;
+    readonly path: string;
+};
+export type SkillDomain = {
+    readonly list: () => Promise<{
+        readonly location: {
+            readonly directory: string;
+        };
+        readonly data: readonly SkillInfo[];
+    }>;
+};
 export type PluginLocation = {
     readonly directory: string;
 };
@@ -429,6 +443,7 @@ export type PluginContext = {
     readonly shell?: ShellDomain;
     readonly websearch?: WebSearchDomain;
     readonly mcp?: McpDomain;
+    readonly skill?: SkillDomain;
 };
 export type Cleanup = () => Promise<void> | void;
 export type Plugin2 = {

package/dist/parallel-step.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Parallel tool-call step boundary for OpenCode's AI SDK step model.
+ *
+ * Cursor fires execs as they are generated; CLI demuxes them concurrently and
+ * has no step boundary. OpenCode needs one `finish: tool-calls` after every
+ * call of the generation. Cursor's `tool_requests_listed` (InteractionUpdate
+ * field 27) carries that count. See tasks/plans/parallel-tool-calls-cli-parity.md.
+ */
+/** Idle without a progress frame while holding → close the step (ms). */
+export declare const PARALLEL_STEP_IDLE_MS = 1500;
+export type ParallelStepState = {
+    /** From field 27; undefined until Cursor lists the count for this step. */
+    listedCount?: number;
+    /** Model tool_call_ids seen this step. */
+    callIds: Set<string>;
+    /** Ids with a final client disposition this step. */
+    resolved: Set<string>;
+    /** Host tool-call parts emitted this step. */
+    emitted: number;
+    /** Wall time of the last progress frame (for the liveness guard). */
+    lastProgressAt: number;
+};
+export declare function noteToolRequestsListedSeen(): void;
+export declare function hasSeenToolRequestsListed(): boolean;
+/** Test-only: reset the process capability gate. */
+export declare function resetToolRequestsListedSeenForTests(): void;
+export declare function createParallelStep(now?: number): ParallelStepState;
+export declare function noteParallelStepProgress(step: ParallelStepState, now?: number): void;
+export declare function noteListedCallCount(step: ParallelStepState, callCount: number, now?: number): void;
+/**
+ * Record a final disposition for `callId`. Returns true when newly resolved.
+ * Empty ids are ignored. Prior-step ids in `prior` are ignored.
+ */
+export declare function resolveParallelStepCall(step: ParallelStepState, callId: string | undefined, prior?: ReadonlySet<string>, now?: number): boolean;
+export declare function recordParallelStepEmission(step: ParallelStepState, now?: number): void;
+/** True when the listed count is known and every listed call is resolved. */
+export declare function parallelStepCountMet(step: ParallelStepState): boolean;
+/**
+ * Whether to keep pumping for more calls of this step instead of finishing.
+ *
+ * - Gate off and no count yet → do not hold (today's one-call finish).
+ * - Human-gated interaction with unknown count → do not hold (prompt must show).
+ * - Otherwise hold until the count is met (or the liveness guard fires).
+ */
+export declare function shouldHoldParallelStep(step: ParallelStepState, options?: {
+    fieldSeen?: boolean;
+    humanGatedWithoutCount?: boolean;
+}): boolean;
+/** True when the hold has made no progress for `idleMs`. */
+export declare function shouldGuardCloseParallelStep(step: ParallelStepState, now?: number, idleMs?: number): boolean;
+/**
+ * Frames that reset the liveness guard while holding. Heartbeat, KV, and
+ * checkpoint are not progress — they say nothing about further tool calls.
+ */
+export declare function isParallelStepProgressFrame(kinds: {
+    toolRequestsListed?: boolean;
+    partialToolCall?: boolean;
+    toolCallDelta?: boolean;
+    toolCallStarted?: boolean;
+    toolCallCompleted?: boolean;
+    exec?: boolean;
+    interactionQuery?: boolean;
+    textDelta?: boolean;
+    thinkingDelta?: boolean;
+}): boolean;

package/dist/parallel-step.js

@@ -0,0 +1,102 @@
+/**
+ * Parallel tool-call step boundary for OpenCode's AI SDK step model.
+ *
+ * Cursor fires execs as they are generated; CLI demuxes them concurrently and
+ * has no step boundary. OpenCode needs one `finish: tool-calls` after every
+ * call of the generation. Cursor's `tool_requests_listed` (InteractionUpdate
+ * field 27) carries that count. See tasks/plans/parallel-tool-calls-cli-parity.md.
+ */
+/** Idle without a progress frame while holding → close the step (ms). */
+export const PARALLEL_STEP_IDLE_MS = 1_500;
+/** Process-level: Cursor has sent field 27 on any Run in this process. */
+let toolRequestsListedSeen = false;
+export function noteToolRequestsListedSeen() {
+    toolRequestsListedSeen = true;
+}
+export function hasSeenToolRequestsListed() {
+    return toolRequestsListedSeen;
+}
+/** Test-only: reset the process capability gate. */
+export function resetToolRequestsListedSeenForTests() {
+    toolRequestsListedSeen = false;
+}
+export function createParallelStep(now = Date.now()) {
+    return {
+        callIds: new Set(),
+        resolved: new Set(),
+        emitted: 0,
+        lastProgressAt: now,
+    };
+}
+export function noteParallelStepProgress(step, now = Date.now()) {
+    step.lastProgressAt = now;
+}
+export function noteListedCallCount(step, callCount, now = Date.now()) {
+    noteToolRequestsListedSeen();
+    if (Number.isFinite(callCount) && callCount >= 0) {
+        step.listedCount = callCount;
+    }
+    noteParallelStepProgress(step, now);
+}
+/**
+ * Record a final disposition for `callId`. Returns true when newly resolved.
+ * Empty ids are ignored. Prior-step ids in `prior` are ignored.
+ */
+export function resolveParallelStepCall(step, callId, prior, now = Date.now()) {
+    if (!callId)
+        return false;
+    if (prior?.has(callId))
+        return false;
+    step.callIds.add(callId);
+    if (step.resolved.has(callId))
+        return false;
+    step.resolved.add(callId);
+    noteParallelStepProgress(step, now);
+    return true;
+}
+export function recordParallelStepEmission(step, now = Date.now()) {
+    step.emitted++;
+    noteParallelStepProgress(step, now);
+}
+/** True when the listed count is known and every listed call is resolved. */
+export function parallelStepCountMet(step) {
+    return step.listedCount !== undefined && step.resolved.size >= step.listedCount;
+}
+/**
+ * Whether to keep pumping for more calls of this step instead of finishing.
+ *
+ * - Gate off and no count yet → do not hold (today's one-call finish).
+ * - Human-gated interaction with unknown count → do not hold (prompt must show).
+ * - Otherwise hold until the count is met (or the liveness guard fires).
+ */
+export function shouldHoldParallelStep(step, options = {}) {
+    if (options.humanGatedWithoutCount && step.listedCount === undefined)
+        return false;
+    const fieldSeen = options.fieldSeen ?? hasSeenToolRequestsListed();
+    if (!fieldSeen && step.listedCount === undefined)
+        return false;
+    if (parallelStepCountMet(step))
+        return false;
+    return true;
+}
+/** True when the hold has made no progress for `idleMs`. */
+export function shouldGuardCloseParallelStep(step, now = Date.now(), idleMs = PARALLEL_STEP_IDLE_MS) {
+    if (parallelStepCountMet(step))
+        return false;
+    return now - step.lastProgressAt >= idleMs;
+}
+/**
+ * Frames that reset the liveness guard while holding. Heartbeat, KV, and
+ * checkpoint are not progress — they say nothing about further tool calls.
+ */
+export function isParallelStepProgressFrame(kinds) {
+    return !!(kinds.toolRequestsListed
+        || kinds.partialToolCall
+        || kinds.toolCallDelta
+        || kinds.toolCallStarted
+        || kinds.toolCallCompleted
+        || kinds.exec
+        || kinds.interactionQuery
+        || kinds.textDelta
+        || kinds.thinkingDelta);
+}