cursor-opencode-provider 0.2.8 → 0.3.0

package/dist/plugin-v2.d.ts

@@ -1,2 +1,9 @@
+/**
+ * OpenCode Effect / Promise v2 plugin.
+ *
+ * Wires the Cursor provider through `ctx.aisdk.sdk` / `ctx.aisdk.language`
+ * (the V2 extension points). Auth still lives in the classic Hooks plugin
+ * (`plugin.ts`) until OpenCode integrations fully replace provider OAuth.
+ */
 declare const _default: import("@opencode-ai/plugin/v2/promise").Plugin;
 export default _default;

package/dist/plugin-v2.js

@@ -1,6 +1,6 @@
 import { define } from "@opencode-ai/plugin/v2/promise";
 import { CURSOR_PROVIDER_ID } from "./shared.js";
-import { createCursorLanguageModel } from "./language-model.js";
+import { createSdk, isCursorPackage } from "./plugin-core.js";
 import { adoptCompatHostCacheDir } from "./context/paths.js";
 /**
  * OpenCode Effect / Promise v2 plugin.
@@ -9,20 +9,6 @@ import { adoptCompatHostCacheDir } from "./context/paths.js";
  * (the V2 extension points). Auth still lives in the classic Hooks plugin
  * (`plugin.ts`) until OpenCode integrations fully replace provider OAuth.
  */
-function isCursorPackage(pkg, providerID) {
-    if (providerID === CURSOR_PROVIDER_ID)
-        return true;
-    return (pkg.includes("cursor-opencode-provider") ||
-        /cursor-opencode-provider[/\\]dist[/\\]index\.js/.test(pkg));
-}
-function createSdk(options) {
-    const providerId = options.name || CURSOR_PROVIDER_ID;
-    return {
-        languageModel(modelId) {
-            return createCursorLanguageModel(modelId, providerId, options);
-        },
-    };
-}
 export default define({
     id: "cursor.provider",
     setup: async (ctx) => {

package/dist/plugin.d.ts

@@ -1,17 +1,3 @@
 import type { Hooks, PluginInput } from "@opencode-ai/plugin";
-import { type ModelInfo } from "./models.js";
-/**
- * Display names shared by both a thinking and a non-thinking model. A thinking
- * model with such a name needs a "Thinking" tag to disambiguate it from its
- * non-thinking twin (Cursor's Claude/Fable/Sonnet families). Models whose names
- * are already unique — including Cursor's GPT family, where the reasoning tier
- * ("None"/"Low"/"High"…) is baked into the name — are excluded, so they aren't
- * tagged redundantly.
- */
-export declare function thinkingSuffixBaseNames(models: ModelInfo[]): Set<string>;
-export declare function modelInfoToConfig(mi: ModelInfo, options?: {
-    thinkingSuffix?: boolean;
-    contextTier?: "base" | "long";
-}): Record<string, any>;
-export declare function modelsToConfig(models: ModelInfo[]): Record<string, any>;
+export { modelInfoToConfig, modelsToConfig, thinkingSuffixBaseNames } from "./model-config.js";
 export declare function CursorPlugin(input: PluginInput): Promise<Hooks>;

package/dist/plugin.js

@@ -1,199 +1,19 @@
 import { CURSOR_COMPACTION_OPTION, CURSOR_PROVIDER_ID, CURSOR_WEBSITE_HOST, CURSOR_API_HOST } from "./shared.js";
+import { cursorApiBaseURL, cursorGetServerConfigTelemetryEnabled } from "./plugin-core.js";
 import { pollForTokens, exchangeApiKey, refreshAccessToken, isExpiringSoon, generatePkceParams, generatePkceChallenge, buildLoginUrl, decodeJwtExpiryMs } from "./auth.js";
-import { CURSOR_VARIANT_PARAMETERS_KEY, CURSOR_WIRE_MODEL_ID_KEY, readCache, discoverModels, isCacheFresh, parseCursorContextLimit } from "./models.js";
+import { readCache, discoverModels, isCacheFresh } from "./models.js";
+// Re-exported for API compatibility: tests and downstream code import these
+// from "./plugin.js". Canonical home is ./model-config.ts, which stays free of
+// host plugin imports so the OpenCode 2.0 entrypoint can share it.
+import { modelsToConfig } from "./model-config.js";
+export { modelInfoToConfig, modelsToConfig, thinkingSuffixBaseNames } from "./model-config.js";
 import { adoptCompatHostCacheDir, opencodeGlobalCacheDir } from "./context/paths.js";
 import { readStoredAuth } from "./context/auth-store.js";
 import { resolveAgentUrl } from "./agent-url.js";
 import { captureCursorShellResult, cursorShellEnvForCall, cursorShellOriginalCommand, prepareCursorShellArgs, releaseCursorShellEnv, sanitizeRegisteredCursorShellOutput, setCursorShellPath, } from "./shell-timeout.js";
 import { sessionActivity } from "./activity.js";
-import { openCodeWebSearchTool } from "./web-tools.js";
+import { openCodeWebSearchTool } from "./web-search-tool.js";
 const MODULE_URL = new URL("./index.js", import.meta.url).href;
-/**
- * Strip characters and markup that break rendering in the OpenCode TUI/GUI from
- * a model or variant display name:
- *   • HTML tags (e.g. `<span style="…">Medium</span>`) — the IDE colours variant
- *     suffixes with a CSS var that doesn't exist in OpenCode, so the raw markup
- *     would show as literal text. We drop the tags and keep the inner text
- *     ("Medium").
- *   • HTML/markup chars (`< > & " ' \``), parentheses.
- *   • Tabs/newlines collapse to single spaces.
- * Dots and unicode letters are preserved so names stay readable.
- * Fixes https://github.com/oakimov/cursor-opencode-provider/issues/2.
- */
-function safeLabel(value) {
-    return (value
-        .replace(/<[^>]+>/g, "")
-        .replace(/[()<>&"'`]/g, "")
-        .replace(/\s+/g, " ")
-        .trim() || "default");
-}
-function baseName(mi) {
-    return safeLabel(mi.displayName ?? mi.id);
-}
-function modelInfoVariants(mi, variants) {
-    if (variants.length === 0)
-        return undefined;
-    const entries = {};
-    const usedKeys = new Set();
-    const baseName = safeLabel(mi.displayName ?? mi.id);
-    // Each variant's key is `safeLabel(displayName)` (the IDE's own label, e.g.
-    // "Opus 4.8 1M High Fast Thinking") so the picker matches what the user
-    // sees in Cursor. Two variants can sanitize to the same name when the IDE
-    // wraps a differentiator in `<span>…</span>` (e.g. Composer's "Fast"
-    // suffix collapses to the bare model name after stripping). To guarantee
-    // every variant stays pickable:
-    //   1. If the sanitized displayName matches the model name itself, suffix
-    //      it with distinguishing params (or "default") so it never collides
-    //      with the model entry in the variant panel.
-    //   2. If two variants still collide, tag the later one with its params.
-    // Suffixes must stay free of `()` / markup chars — same constraint as
-    // safeLabel (issue #2); use spaced tokens, not parenthetical tags.
-    const tagDims = (p) => {
-        const labels = [];
-        for (const d of p) {
-            if (d.id === "fast" && d.value === "true")
-                labels.push("Fast");
-            else if (d.id === "thinking" && d.value === "true")
-                labels.push("Thinking");
-            else if (d.id === "context")
-                labels.push(d.value);
-        }
-        if (labels.length > 0)
-            return ` ${labels.join(" ")}`;
-        // No params at all — still disambiguate from the model name itself.
-        if (p.length === 0)
-            return "";
-        return " default";
-    };
-    for (const v of variants) {
-        const sanitized = safeLabel(v.displayName || v.key || "default");
-        let key = sanitized;
-        // Never let a variant key equal the model name — that would make the
-        // 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`;
-        }
-        else if (usedKeys.has(key)) {
-            key = `${sanitized}${tagDims(v.parameterValues)}`;
-        }
-        let n = 2;
-        while (usedKeys.has(key))
-            key = `${sanitized}${tagDims(v.parameterValues)} ${n++}`;
-        usedKeys.add(key);
-        entries[key] = {
-            [CURSOR_VARIANT_PARAMETERS_KEY]: v.parameterValues.map((p) => ({ ...p })),
-        };
-    }
-    return entries;
-}
-function isLongContextVariant(v) {
-    return v.parameterValues.some((p) => p.id === "context" && parseCursorContextLimit(p.value) === 1_000_000);
-}
-function variantsForTier(mi, tier) {
-    return mi.variants.filter((v) => isLongContextVariant(v) === (tier === "long"));
-}
-/**
- * Display names shared by both a thinking and a non-thinking model. A thinking
- * model with such a name needs a "Thinking" tag to disambiguate it from its
- * non-thinking twin (Cursor's Claude/Fable/Sonnet families). Models whose names
- * are already unique — including Cursor's GPT family, where the reasoning tier
- * ("None"/"Low"/"High"…) is baked into the name — are excluded, so they aren't
- * tagged redundantly.
- */
-export function thinkingSuffixBaseNames(models) {
-    const flags = new Map();
-    for (const m of models) {
-        const base = baseName(m);
-        const entry = flags.get(base) ?? { hasThinking: false, hasNonThinking: false };
-        if (m.supportsThinking)
-            entry.hasThinking = true;
-        else
-            entry.hasNonThinking = true;
-        flags.set(base, entry);
-    }
-    const ambiguous = new Set();
-    for (const [base, f] of flags)
-        if (f.hasThinking && f.hasNonThinking)
-            ambiguous.add(base);
-    return ambiguous;
-}
-export function modelInfoToConfig(mi, options = {}) {
-    const contextTier = options.contextTier ?? "base";
-    const variants = variantsForTier(mi, contextTier);
-    let name = baseName(mi);
-    if (options.thinkingSuffix)
-        name += " Thinking";
-    if (contextTier === "long")
-        name += " 1M";
-    // OpenCode's context limit is static per model entry, while Cursor's context
-    // tier is a variant parameter. Long-context choices are therefore emitted as
-    // separate OpenCode entries by modelsToConfig.
-    const context = contextTier === "long"
-        ? (mi.maxContextForMaxMode ?? 1_000_000)
-        : (mi.maxContext ?? 200_000);
-    // OpenCode's overflow/compaction/UI use limit.context; generation and
-    // thinking budgets use limit.output. models.dev 1M peers advertise
-    // 64k–128k output — a tiny cap makes long-context sessions feel broken
-    // even when the 1M input window is correct.
-    const output = contextTier === "long" ? 128_000 : 32_000;
-    const config = {
-        name,
-        reasoning: mi.supportsThinking ?? false,
-        tool_call: mi.supportsAgent ?? true,
-        temperature: false,
-        limit: {
-            context,
-            output,
-        },
-    };
-    const variantConfig = modelInfoVariants(mi, variants);
-    if (variantConfig)
-        config.variants = variantConfig;
-    if (contextTier === "long") {
-        const defaultVariant = variants.find((v) => v.isDefaultMax) ?? variants[0];
-        if (defaultVariant) {
-            config.options = {
-                [CURSOR_WIRE_MODEL_ID_KEY]: mi.id,
-                [CURSOR_VARIANT_PARAMETERS_KEY]: defaultVariant.parameterValues.map((p) => ({ ...p })),
-            };
-        }
-    }
-    return config;
-}
-export function modelsToConfig(models) {
-    const ambiguous = thinkingSuffixBaseNames(models);
-    const out = {};
-    const usedIds = new Set(models.map((m) => m.id));
-    for (const m of models) {
-        const thinkingSuffix = !!m.supportsThinking && ambiguous.has(baseName(m));
-        const baseVariants = variantsForTier(m, "base");
-        const longVariants = variantsForTier(m, "long");
-        if (baseVariants.length > 0 || longVariants.length === 0) {
-            out[m.id] = modelInfoToConfig(m, { thinkingSuffix, contextTier: "base" });
-        }
-        if (longVariants.length === 0)
-            continue;
-        if (baseVariants.length === 0) {
-            out[m.id] = modelInfoToConfig(m, { thinkingSuffix, contextTier: "long" });
-            continue;
-        }
-        let longId = `${m.id}-1m`;
-        let suffix = 2;
-        while (usedIds.has(longId))
-            longId = `${m.id}-1m-${suffix++}`;
-        usedIds.add(longId);
-        out[longId] = modelInfoToConfig(m, { thinkingSuffix, contextTier: "long" });
-    }
-    return out;
-}
-function cursorApiBaseURL() {
-    return process.env.CURSOR_API_BASE_URL ?? `https://${CURSOR_API_HOST}`;
-}
-function cursorGetServerConfigTelemetryEnabled() {
-    return (process.env.CURSOR_GET_SERVER_CONFIG_TELEMETRY === "1" ||
-        process.env.CURSOR_GET_SERVER_CONFIG_TELEMETRY === "true");
-}
 export async function CursorPlugin(input) {
     // Prefer strong OCP host identity when available; otherwise resolve from explicit host signals/install path.
     await adoptCompatHostCacheDir();
@@ -443,10 +263,10 @@ export async function CursorPlugin(input) {
                             type: "text",
                             key: "apiKey",
                             message: "Cursor API key",
-                            placeholder: "sk-...",
+                            placeholder: "crsr_...",
                             validate(value) {
-                                if (!value.startsWith("sk-"))
-                                    return "API key should start with sk-";
+                                if (!value.startsWith("crsr_"))
+                                    return "API key should start with crsr_";
                                 return undefined;
                             },
                         },

package/dist/protocol/messages.d.ts

@@ -3,6 +3,16 @@ export declare function createMessageTypes(): protobuf.Root;
 export declare function getMessageTypes(): protobuf.Root;
 export declare function encodeMessage(typeName: string, message: Record<string, unknown>): Uint8Array;
 export declare function decodeMessage<T = Record<string, unknown>>(typeName: string, data: Uint8Array): T;
+/**
+ * Diagnostic-only: walk AgentServerMessage.interaction_update(1).turn_ended(14)
+ * without going through our hand-written TurnEnded schema, so a `cache_write`/
+ * `reasoning_tokens` question can be checked against the raw wire instead of
+ * guessed. Confirmed field ids 1-5 (input/output/cache_read/cache_write/
+ * reasoning) decode correctly. Live captures routinely include `f4` explicitly
+ * as `0` while `f3` (cache_read) and `f5` (reasoning) are non-zero — Cursor's
+ * agent TurnEnded populates the field but does not report write counts here.
+ */
+export declare function debugWalkTurnEnded(payload: Uint8Array): string;
 /**
  * Decode a protobuf sub-message from a frame payload that wraps it in
  * a top-level field key + length varint.  Skips the outer wrapper and

package/dist/protocol/messages.js

@@ -366,10 +366,29 @@ export function createMessageTypes() {
         { id: 1, name: "path", type: "string" },
         { id: 2, name: "error", type: "string" },
     ]);
+    // Cursor's LocalReadExecutor validates the target before execution and, for a
+    // missing / non-regular path, returns one of these typed ReadResult cases
+    // instead of running the tool. Mirroring the exact field ids/shapes lets this
+    // provider reply the same way so the model sees a structured file-not-found
+    // observation and the host never surfaces a permission prompt.
+    addType(root, "ReadFileNotFound", [{ id: 1, name: "path", type: "string" }]);
+    addType(root, "ReadPermissionDenied", [{ id: 1, name: "path", type: "string" }]);
+    addType(root, "ReadInvalidFile", [
+        { id: 1, name: "path", type: "string" },
+        { id: 2, name: "reason", type: "string" },
+    ]);
     addType(root, "ReadResult", [
         { id: 1, name: "success", type: "ReadSuccess" },
         { id: 2, name: "error", type: "ReadError" },
-    ], [{ name: "result", fields: ["success", "error"] }]);
+        { id: 4, name: "file_not_found", type: "ReadFileNotFound" },
+        { id: 5, name: "permission_denied", type: "ReadPermissionDenied" },
+        { id: 6, name: "invalid_file", type: "ReadInvalidFile" },
+    ], [
+        {
+            name: "result",
+            fields: ["success", "error", "file_not_found", "permission_denied", "invalid_file"],
+        },
+    ]);
     addType(root, "GrepArgs", [
         { id: 1, name: "pattern", type: "string" },
         { id: 2, name: "path", type: "string" },
@@ -1190,6 +1209,62 @@ export function decodeMessage(typeName, data) {
     const decoded = type.decode(data);
     return type.toObject(decoded, { defaults: true, json: true, longs: Number });
 }
+/** Schema-free walk of one message's top-level wire fields (no nested descent). */
+function readRawFields(buf) {
+    const reader = protobuf.Reader.create(buf);
+    const fields = [];
+    while (reader.pos < reader.len) {
+        const tag = reader.uint32();
+        const field = tag >>> 3;
+        const wireType = tag & 7;
+        switch (wireType) {
+            case 0:
+                fields.push({ field, wireType, varint: reader.uint64().toString() });
+                break;
+            case 1:
+                fields.push({ field, wireType, fixed: reader.fixed64().toString() });
+                break;
+            case 2:
+                fields.push({ field, wireType, bytes: reader.bytes() });
+                break;
+            case 5:
+                fields.push({ field, wireType, fixed: reader.fixed32() });
+                break;
+            default:
+                // Groups (3/4) aren't used on this wire; bail rather than desync the reader.
+                return fields;
+        }
+    }
+    return fields;
+}
+/**
+ * Diagnostic-only: walk AgentServerMessage.interaction_update(1).turn_ended(14)
+ * without going through our hand-written TurnEnded schema, so a `cache_write`/
+ * `reasoning_tokens` question can be checked against the raw wire instead of
+ * guessed. Confirmed field ids 1-5 (input/output/cache_read/cache_write/
+ * reasoning) decode correctly. Live captures routinely include `f4` explicitly
+ * as `0` while `f3` (cache_read) and `f5` (reasoning) are non-zero — Cursor's
+ * agent TurnEnded populates the field but does not report write counts here.
+ */
+export function debugWalkTurnEnded(payload) {
+    try {
+        const top = readRawFields(payload);
+        const iuField = top.find((f) => f.field === 1 && f.wireType === 2);
+        if (!iuField?.bytes)
+            return "(no interaction_update field)";
+        const iu = readRawFields(iuField.bytes);
+        const teField = iu.find((f) => f.field === 14 && f.wireType === 2);
+        if (!teField?.bytes)
+            return "(no turn_ended field in interaction_update)";
+        const te = readRawFields(teField.bytes);
+        return te
+            .map((f) => `f${f.field}:wt${f.wireType}=${f.varint ?? f.fixed ?? (f.bytes ? `bytes[${f.bytes.length}]` : "?")}`)
+            .join(" ");
+    }
+    catch (e) {
+        return `(walk failed: ${e.message})`;
+    }
+}
 /**
  * Decode a protobuf sub-message from a frame payload that wraps it in
  * a top-level field key + length varint.  Skips the outer wrapper and

package/dist/protocol/tool-call-bridge.js

@@ -1,4 +1,4 @@
-import { mapCursorArgsToOpencode, mcpRealToolName } from "./tools.js";
+import { mapCursorArgsToOpencode, mapCursorSubagentTypeToOpenCode, mcpRealToolName } from "./tools.js";
 import { decodeStructEntriesToJson } from "./struct.js";
 const TODO_STATUS = {
     0: "pending",
@@ -334,7 +334,27 @@ function openCodeSubagentType(raw) {
     if (typeof custom?.name === "string" && custom.name.length > 0)
         return custom.name;
     if (subtype.explore != null)
-        return "explore";
+        return mapCursorSubagentTypeToOpenCode("explore");
+    if (subtype.cursor_guide != null)
+        return mapCursorSubagentTypeToOpenCode("cursor_guide");
+    if (subtype.bash != null)
+        return mapCursorSubagentTypeToOpenCode("bash");
+    if (subtype.shell != null)
+        return mapCursorSubagentTypeToOpenCode("shell");
+    if (subtype.debug != null)
+        return mapCursorSubagentTypeToOpenCode("debug");
+    if (subtype.computer_use != null)
+        return mapCursorSubagentTypeToOpenCode("computer_use");
+    if (subtype.browser_use != null)
+        return mapCursorSubagentTypeToOpenCode("browser_use");
+    if (subtype.media_review != null)
+        return mapCursorSubagentTypeToOpenCode("media_review");
+    if (subtype.watch_video != null)
+        return mapCursorSubagentTypeToOpenCode("watch_video");
+    if (subtype.vm_setup_helper != null)
+        return mapCursorSubagentTypeToOpenCode("vm_setup_helper");
+    if (subtype.unspecified != null)
+        return mapCursorSubagentTypeToOpenCode("unspecified");
     return undefined;
 }
 /** Advertised OpenCode tool ids from Cursor McpToolDefinition descriptors. */

package/dist/protocol/tools.d.ts

@@ -64,6 +64,29 @@ export declare function toolsToMcpDescriptors(tools: OpencodeToolDef[], provider
 export declare function buildLiveRequestContext(tools: OpencodeToolDef[], providerIdentifier?: string, knownMcpServers?: Iterable<string>): Record<string, unknown>;
 export declare function mapExecServerToToolName(execField: string): string | undefined;
 export declare function mapToolNameToExecField(toolName: string): string | undefined;
+export type HostSubagentDefinition = {
+    name: string;
+    description?: string;
+};
+export type HostSubagentCatalog = {
+    executor?: "task" | "actor";
+    agents: HostSubagentDefinition[];
+    /** True when the host tool supplied its complete, permission-filtered catalog. */
+    complete: boolean;
+};
+/** Extract the current host's permission-filtered Task/Actor recipient catalog. */
+export declare function extractHostSubagentCatalog(tools: OpencodeToolDef[]): HostSubagentCatalog;
+/** Resolve a Cursor subtype against the agents the host can spawn this turn. */
+export declare function resolveCursorSubagentType(subagentType: string, catalog?: HostSubagentCatalog): string | undefined;
+/**
+ * Cursor's native Task/subagent protocol uses Cursor-owned subtype names while
+ * OpenCode-family hosts execute named agents. Map known Cursor built-ins to
+ * the closest host agent and preserve unknown values so user-defined OpenCode
+ * agents can still be called by exact name.
+ */
+export declare function mapCursorSubagentTypeToOpenCode(subagentType: string): string;
+/** Resolve a native Cursor subagent request to this turn's executor and catalog. */
+export declare function remapNativeSubagentForCatalog(parsed: ParsedExecRequest, advertisedToolNames: Iterable<string>, catalog?: HostSubagentCatalog): void;
 export type ParsedExecRequest = {
     id: number;
     execId: string;
@@ -92,6 +115,32 @@ export declare function mapCursorArgsToOpencode(toolName: string, raw: Record<st
  * → github_create_pull_request). Builtins under the default server stay bare.
  */
 export declare function mcpRealToolName(mcpArgs: Record<string, unknown>, defaultServer?: string): string;
+/**
+ * Resolve a read target the way Cursor's LocalReadExecutor does before it
+ * stats the file: untildify, then resolve a relative path against the workspace
+ * root (`env.workspace_paths[0]`), else resolve as-is. Kept in lockstep with
+ * agent utils `resolvePath(path, workspaceRoot)`.
+ */
+export declare function resolveReadTargetPath(requested: string, workspaceRoot: string): string;
+/**
+ * A typed ReadResult oneof case for a read target that fails Cursor's
+ * pre-execution validation, or undefined when the path is a readable file the
+ * tool should actually read. Mirrors LocalReadExecutor exactly:
+ *  - missing path (ENOENT/ENOTDIR)     → file_not_found
+ *  - directory                         → invalid_file "Path is a directory, not a file"
+ *  - socket/fifo/etc (not a file)      → invalid_file "Path is neither a file nor a directory"
+ * EACCES/EPERM (exists but unreadable) and any other stat error return undefined
+ * so the call proceeds to OpenCode and a genuine permission decision is never
+ * masked. Never rejects a non-existent *write/edit* target — this is read-only.
+ */
+export declare function classifyMissingReadTarget(absolutePath: string): Record<string, unknown> | undefined;
+/**
+ * Encode a pre-execution read rejection as the exact frames Cursor's client
+ * emits: the ExecClientMessage carrying the typed ReadResult oneof case, then
+ * the ACM #5 stream_close for that id. `readResult` is the case object from
+ * classifyMissingReadTarget (e.g. `{ file_not_found: { path } }`).
+ */
+export declare function buildReadRejectionMessages(execId: number, readResult: Record<string, unknown>): Uint8Array[];
 export type ToolResultInput = {
     execId: number;
     /** ExecClientMessage result field (from ParsedExecRequest.resultField). */
@@ -109,6 +158,13 @@ export type ToolResultInput = {
     resultMetadata?: Record<string, unknown>;
     /** Structured shell completion captured by the OpenCode plugin hook. */
     shellOutcome?: CursorShellOutcome;
+    /**
+     * Workspace root for result shapes that must name a directory
+     * (grep_result workspace_results keys, ls_result directory_tree_root).
+     * Must not fall back to process.cwd() — the OpenCode 2.0 daemon's cwd is
+     * often $HOME and would re-advertise the wrong folder to the model.
+     */
+    workspaceRoot?: string;
 };
 /**
  * Build one or more ExecClientMessage frames for a tool result.
@@ -146,7 +202,7 @@ export declare function unwrapReadOutput(output: string): string;
  * OpenCode returns free-form text; we wrap it in the minimal success shape the
  * server accepts (verified against agent.v1 wire captures).
  */
-export declare function buildTypedExecResult(resultField: string, output: string, error?: string, toolName?: string, resultMetadata?: Record<string, unknown>, shellOutcome?: CursorShellOutcome): Record<string, unknown>;
+export declare function buildTypedExecResult(resultField: string, output: string, error?: string, toolName?: string, resultMetadata?: Record<string, unknown>, shellOutcome?: CursorShellOutcome, workspaceRoot?: string): Record<string, unknown>;
 export declare function buildToolCallPart(execMsg: ParsedExecRequest, sessionId: string): {
     toolCallId: string;
     toolName: string;