@cursor/july 0.1.82 → 0.1.84

package/dist/internal/session-engine.js

@@ -22,7 +22,8 @@ import { SLACK_CHANNEL_ID } from "../channels/slack/constants.js";
 import { materializeSlackNudgeCarrier } from "../channels/slack/nudge-carrier.js";
 import { SlackAskDedupeStore, SlackNudgeStore, } from "../channels/slack/nudge-store.js";
 import { resolveDedicatedSlackHostBinding } from "../channels/slack/slack-channel.js";
-import { cursorHostedFiles, isCursorHostedFilesAvailable, } from "../files-backends/cursor-hosted.js";
+import { AGENT_SERVE_USER_STORE_FILES_SOURCE_ID, agentStoreKeys, } from "../files.js";
+import { cursorHostedFiles, isCursorHostedFilesAvailable, isCursorUserStoreFilesAvailable, } from "../files-backends/cursor-hosted.js";
 import { DEFAULT_MODEL, DIRECT_TOOL_CALL_CHANNEL_ID, isHostOauthConnectionTransport, isSymbolicConnectionTransport, } from "../types.js";
 import { ABCollector } from "./ab-collector.js";
 import { foldABStream } from "./ab-fold.js";
@@ -53,6 +54,7 @@ import { sessionExternalLinks } from "./session-links.js";
 import { SessionStore } from "./session-store.js";
 import { syncSkillsToStore } from "./skills-sync.js";
 import { StorageCoordinator } from "./storage-coordinator.js";
+import { decideToolCall } from "./tool-policy.js";
 import { normalizeToolResult, toolCallErrorMessage } from "./tool-result.js";
 import { estimateTurnCostFromApi, roundCostUsd, } from "./turn-cost.js";
 import { TurnGovernor } from "./turn-governor.js";
@@ -123,6 +125,15 @@ export class SessionEngine {
         this.activeTurns = new Map();
         /** Context used by the cloud turn's HTTP MCP callbacks. */
         this.activeToolContexts = new Map();
+        /**
+         * Tool call ids the host answered instead of running, per session.
+         *
+         * The mapper emits the result event from the harness's view of a finished
+         * call, which cannot tell an answered call from a real one — so the decision
+         * point records the id here and the mapper stamps the event from it.
+         * Registered only while a turn can invoke a tool.
+         */
+        this.stubbedCallIds = new Map();
         /**
          * Delivered-nudge count per session at the last tool boundary. The carrier
          * drains out-of-process, so a growing count is how the engine learns a
@@ -529,24 +540,7 @@ export class SessionEngine {
             const now = new Date().toISOString();
             const channelState = this.initialChannelState(channelId, sendOptions.state);
             const purpose = sendOptions.purpose === "eval" ? "eval" : "live";
-            let record = {
-                sessionId: newSessionId(),
-                channelId,
-                mode: (_d = sendOptions.mode) !== null && _d !== void 0 ? _d : "chat",
-                purpose,
-                continuationKey: (_e = sendOptions.continuationToken) !== null && _e !== void 0 ? _e : newContinuationKey(),
-                auth,
-                title: sendOptions.title,
-                channelState,
-                workspaceOverride: sendOptions.workspaceDir,
-                pendingWorkspaceFiles: sendOptions.workspaceFiles,
-                pendingImages: sendOptions.images,
-                cloudOverride: sendOptions.cloud,
-                sdkAgentId: sendOptions.sdkAgentId,
-                turnCount: 0,
-                createdAt: now,
-                updatedAt: now,
-            };
+            let record = Object.assign(Object.assign({ sessionId: newSessionId(), channelId, mode: (_d = sendOptions.mode) !== null && _d !== void 0 ? _d : "chat", purpose }, (sendOptions.dryRun === true ? { dryRun: true } : {})), { continuationKey: (_e = sendOptions.continuationToken) !== null && _e !== void 0 ? _e : newContinuationKey(), auth, title: sendOptions.title, channelState, workspaceOverride: sendOptions.workspaceDir, pendingWorkspaceFiles: sendOptions.workspaceFiles, pendingImages: sendOptions.images, cloudOverride: sendOptions.cloud, sdkAgentId: sendOptions.sdkAgentId, turnCount: 0, createdAt: now, updatedAt: now });
             yield this.sessions.save(record);
             (_a = this.storage) === null || _a === void 0 ? void 0 : _a.sessionRecord(record);
             yield this.appendEvent(record.sessionId, {
@@ -1129,7 +1123,10 @@ export class SessionEngine {
                     this.logger(`[agent-sdk] failed to record event for ${sessionId}: ${describeError(error)}`);
                 }
             };
-            const mapper = new TurnEventMapper(emit);
+            // Read by closure, so the mapper still sees it while draining after the
+            // registry entry below is gone.
+            const stubbed = new Set();
+            const mapper = new TurnEventMapper(emit, (callId) => stubbed.has(callId));
             // Take a turn slot before any work happens. When every slot is busy the
             // turn waits FIFO — durable `turn.queued` marks the wait — and a
             // preempting follow-up (or interrupt) resolves the wait as cancelled
@@ -1213,11 +1210,13 @@ export class SessionEngine {
                         }
                     }), signal, pendingImages);
                     this.activeToolContexts.set(sessionId, { record, turnId, emit });
+                    this.stubbedCallIds.set(sessionId, stubbed);
                     try {
                         outcome = yield this.runner.runTurn(request);
                     }
                     finally {
                         this.activeToolContexts.delete(sessionId);
+                        this.stubbedCallIds.delete(sessionId);
                     }
                 }
                 catch (error) {
@@ -1294,7 +1293,8 @@ export class SessionEngine {
         });
     }
     /**
-     * Sync authored skills onto the deployment store at `skills/<name>/…`
+     * Sync authored skills onto the Agent Store at `skills/<name>/…` (hosted)
+     * or `agent-serve/<agent>/skills/<name>/…` (personal-key local+cloud)
      * before the first cloud prompt, so `--agent-store-skills-dir` and the
      * first-turn S3 scan can discover them. False when the sync fails: the
      * turn then runs without store skills rather than pointing discovery at
@@ -1315,13 +1315,19 @@ export class SessionEngine {
         if (this.cloudSkillsSync !== undefined) {
             return this.cloudSkillsSync;
         }
+        const target = this.cloudSkillsStore();
+        if (target === undefined) {
+            this.cloudSkillsSync = Promise.resolve(false);
+            return this.cloudSkillsSync;
+        }
         const skills = this.project.agent.skills;
         let sync = syncSkillsToStore({
-            sink: cursorHostedFiles(),
+            sink: target.sink,
             agentName: this.project.name,
             skills,
+            skillsPrefix: target.skillsPrefix,
         }).then(() => true, (error) => {
-            this.logger(`[skills] deployment store sync failed: ${error instanceof Error ? error.message : String(error)}`);
+            this.logger(`[skills] ${target.label} sync failed: ${error instanceof Error ? error.message : String(error)}`);
             return false;
         });
         if (skills.length > 0) {
@@ -1332,6 +1338,29 @@ export class SessionEngine {
         this.cloudSkillsSync = sync;
         return sync;
     }
+    /**
+     * Hosted deployments own the deployment store. Local `serve`/`run` with
+     * a personal API key writes into the USER store under `agent-serve/`.
+     */
+    cloudSkillsStore() {
+        if (isCursorHostedFilesAvailable()) {
+            return {
+                sink: cursorHostedFiles(),
+                skillsPrefix: agentStoreKeys.skillsPrefix(),
+                label: "deployment store",
+            };
+        }
+        if (isCursorUserStoreFilesAvailable()) {
+            return {
+                sink: cursorHostedFiles({
+                    storeSourceId: AGENT_SERVE_USER_STORE_FILES_SOURCE_ID,
+                }),
+                skillsPrefix: agentStoreKeys.userSkillsPrefix(this.project.name),
+                label: "user store",
+            };
+        }
+        return undefined;
+    }
     buildTurnRequest(record, agent, turnId, prompt, isFirstTurn, instructionsInvisibleToHarness, emit, onUpdate, signal, images) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c;
@@ -1391,10 +1420,11 @@ export class SessionEngine {
                             : SERVER_TOOLS_MCP_SERVER_NAME,
                     });
                     const hosted = isCursorHostedFilesAvailable();
-                    // Synced whenever hosted, not just when skills exist: removing the
-                    // last skill has to delete its store copies too. Discovery is native
-                    // (`--agent-store-skills-dir`); this only has to land the bytes.
-                    if (hosted) {
+                    // Synced whenever a store is reachable, not just when skills exist:
+                    // removing the last skill has to delete its store copies too.
+                    // Discovery is native (`--agent-store-skills-dir`); this only has
+                    // to land the bytes.
+                    if (hosted || isCursorUserStoreFilesAvailable()) {
                         yield this.ensureCloudSkillsSynced();
                     }
                     const memorySection = hosted
@@ -1412,11 +1442,13 @@ export class SessionEngine {
                     turnPrompt = `${preamble}\n\n${turnPrompt}`;
                 }
             }
-            return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ sessionId: record.sessionId }, (record.sdkAgentId === undefined
+            return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ sessionId: record.sessionId }, (record.sdkAgentId === undefined
                 ? {}
                 : { sdkAgentId: record.sdkAgentId })), { workspaceDir: this.harnessCwd(record), sandbox: ((_c = this.project.agent.local) === null || _c === void 0 ? void 0 : _c.sandbox) === true }), (runtime === "local" && agent.allowedTools !== undefined
                 ? { tools: agent.allowedTools }
-                : {})), { runnerStateDir: join(this.stateRoot, "runner"), prompt: turnPrompt, isFirstTurn }), (images !== undefined && images.length > 0 ? { images } : {})), (agent.model === undefined ? {} : { model: agent.model })), { runtime }), (mergedCloud === undefined ? {} : { cloud: mergedCloud })), { customTools: runtime === "local"
+                : {})), { runnerStateDir: join(this.stateRoot, "runner"), prompt: turnPrompt, isFirstTurn }), (images !== undefined && images.length > 0 ? { images } : {})), (agent.model === undefined ? {} : { model: agent.model })), { runtime }), (mergedCloud === undefined ? {} : { cloud: mergedCloud })), (runtime === "cloud" && !isCursorHostedFilesAvailable()
+                ? { agentServeAgent: this.project.name }
+                : {})), { customTools: runtime === "local"
                     ? yield this.buildCustomTools(record, agent, turnId, emit)
                     : {}, mcpServers: this.buildMcpServers(runtime, record.sessionId, yield this.evaluateConnectionAuth(record)) }), (runtime === "local" && this.hasAttachedAuthedConnections()
                 ? { perSendMcpServers: true }
@@ -1718,6 +1750,7 @@ export class SessionEngine {
     executeServerTool(args) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a;
+            var _b;
             const execute = args.tool.definition.execute;
             if (args.tool.execution !== "server" || typeof execute !== "function") {
                 return toolErrorResult(`Tool "${args.tool.name}" is not a server tool.`);
@@ -1726,7 +1759,7 @@ export class SessionEngine {
             if (!validation.ok) {
                 return toolErrorResult(`Invalid input for tool "${args.tool.name}": ${validation.message}`);
             }
-            const toolCallId = (_a = args.toolCallId) !== null && _a !== void 0 ? _a : newToolCallId(args.tool.name);
+            const toolCallId = (_b = args.toolCallId) !== null && _b !== void 0 ? _b : newToolCallId(args.tool.name);
             const toolCtx = {
                 toolCallId,
                 session: this.sessionInfo(args.record),
@@ -1742,6 +1775,19 @@ export class SessionEngine {
                 emit: args.emit,
             };
             try {
+                // Before the approval gate: a dry run is unattended, so parking a write
+                // for a human would hang the turn rather than answer it.
+                const decision = decideToolCall({
+                    dryRun: args.record.dryRun === true,
+                    effect: args.tool.definition.effect,
+                    dryRunResult: args.tool.definition.dryRunResult,
+                    input: validation.value,
+                });
+                if (decision.kind === "answer") {
+                    (_a = this.stubbedCallIds.get(args.record.sessionId)) === null || _a === void 0 ? void 0 : _a.add(toolCallId);
+                    this.logger(`[session] tool ${args.tool.name} answered by host (${toolCallId})`);
+                    return normalizeToolResult(decision.result);
+                }
                 const needsGate = yield evaluateNeedsApproval(args.tool.definition.needsApproval, validation.value);
                 if (needsGate) {
                     const decision = yield this.parkForApproval({
@@ -1960,10 +2006,20 @@ export class SessionEngine {
                     data: { calls: [{ callId, toolName, args: validation.value }] },
                 });
             }
+            // A separate body from the model path, so it asks the same policy: a
+            // session-bound `POST /v1/tools/:name`, `call --session`, or
+            // `handle.callTool` performs a write just as readily.
+            const decision = decideToolCall({
+                dryRun: (record === null || record === void 0 ? void 0 : record.dryRun) === true,
+                effect: tool.definition.effect,
+                dryRunResult: tool.definition.dryRunResult,
+                input: validation.value,
+            });
             const started = Date.now();
             this.logger(`[session] tool ${toolName} start (direct ${callId})`);
             let result;
             let isError;
+            const stubbed = decision.kind === "answer";
             const live = record;
             const emit = live === undefined
                 ? undefined
@@ -1971,26 +2027,33 @@ export class SessionEngine {
                     void this.appendEvent(live.sessionId, Object.assign(Object.assign({}, payload), { turnId: callId })).catch(() => { });
                 };
             try {
-                result = normalizeToolResult(yield execute(validation.value, {
-                    toolCallId: callId,
-                    session,
-                    workspaceDir,
-                    stateRoot: this.stateRoot,
-                    host: this.hostForSession(record === null || record === void 0 ? void 0 : record.sessionId),
-                    // Scratch calls have no real session; their facade stays unbound.
-                    artifacts: record === undefined
-                        ? this.artifactsApi()
-                        : this.artifactsApi({
-                            sessionId: record.sessionId,
-                            turnId: callId,
-                        }),
-                    send: (channelId, message, sendOptions = {}) => this.send(channelId, message, Object.assign(Object.assign({}, sendOptions), { auth: sendOptions.auth !== undefined
-                            ? sendOptions.auth
-                            : session.auth })),
-                    getSession: (channelId, sessionId) => this.getChannelSession(channelId, sessionId),
-                    emit,
-                }));
-                isError = isErrorEnvelope(result);
+                if (decision.kind === "answer") {
+                    this.logger(`[session] tool ${toolName} answered by host (direct ${callId})`);
+                    result = normalizeToolResult(decision.result);
+                    isError = false;
+                }
+                else {
+                    result = normalizeToolResult(yield execute(validation.value, {
+                        toolCallId: callId,
+                        session,
+                        workspaceDir,
+                        stateRoot: this.stateRoot,
+                        host: this.hostForSession(record === null || record === void 0 ? void 0 : record.sessionId),
+                        // Scratch calls have no real session; their facade stays unbound.
+                        artifacts: record === undefined
+                            ? this.artifactsApi()
+                            : this.artifactsApi({
+                                sessionId: record.sessionId,
+                                turnId: callId,
+                            }),
+                        send: (channelId, message, sendOptions = {}) => this.send(channelId, message, Object.assign(Object.assign({}, sendOptions), { auth: sendOptions.auth !== undefined
+                                ? sendOptions.auth
+                                : session.auth })),
+                        getSession: (channelId, sessionId) => this.getChannelSession(channelId, sessionId),
+                        emit,
+                    }));
+                    isError = isErrorEnvelope(result);
+                }
             }
             catch (error) {
                 this.logger(`[session] tool ${toolName} failed (direct ${callId}): ${describeError(error)}`);
@@ -2017,7 +2080,8 @@ export class SessionEngine {
                 yield this.appendEvent(record.sessionId, {
                     type: "action.result",
                     turnId: callId,
-                    data: { callId, toolName, output: result, isError },
+                    data: Object.assign({ callId,
+                        toolName, output: result, isError }, (stubbed ? { stubbed: true } : {})),
                 });
             }
             const errorMessage = isError ? toolCallErrorMessage(result) : undefined;
@@ -2028,6 +2092,33 @@ export class SessionEngine {
                 durationMs }, (errorMessage === undefined ? {} : { errorMessage })), (record === undefined ? {} : { sessionId: record.sessionId }));
         });
     }
+    /**
+     * Whether a dry run answers a bridged MCP call, for the cloud host bridge —
+     * the one tool path that does not reach {@link executeServerTool}, because
+     * it forwards to `host.mcp` instead of invoking a tool body.
+     *
+     * A bridged tool carries no `defineTool`, so it declares no effect, and the
+     * policy reads an undeclared tool as a write. In a dry run that answers
+     * bridged reads too; resolving effects from a server's own listing is the
+     * next unit's work.
+     */
+    bridgedCallAnswer(args) {
+        var _a;
+        // Read off the in-flight turn's context rather than the session store:
+        // the bridge already refuses a call with no active turn, so the record is
+        // in memory. That keeps this free for the sessions that are not dry runs,
+        // which is every session today.
+        const record = (_a = this.activeToolContexts.get(args.sessionId)) === null || _a === void 0 ? void 0 : _a.record;
+        const decision = decideToolCall({
+            dryRun: (record === null || record === void 0 ? void 0 : record.dryRun) === true,
+            effect: undefined,
+        });
+        if (decision.kind === "run") {
+            return { answered: false };
+        }
+        this.logger(`[session] bridged tool ${args.toolName} answered by host (${args.sessionId})`);
+        return { answered: true, result: normalizeToolResult(decision.result) };
+    }
     // ==========================================================================
     // Events: append, dispatch to channel handlers + hooks
     // ==========================================================================
@@ -2575,7 +2666,7 @@ export class SessionEngine {
             this.coalesceDrains.has(sessionId));
     }
     sessionInfo(record) {
-        return Object.assign(Object.assign(Object.assign({ id: record.sessionId, channelId: record.channelId, mode: record.mode, purpose: record.purpose === "eval" ? "eval" : "live", auth: record.auth, continuationKey: record.continuationKey }, (record.abs === undefined ? {} : { abs: record.abs })), (record.title === undefined ? {} : { title: record.title })), (record.sdkAgentId === undefined
+        return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ id: record.sessionId, channelId: record.channelId, mode: record.mode, purpose: record.purpose === "eval" ? "eval" : "live" }, (record.dryRun === true ? { dryRun: true } : {})), { auth: record.auth, continuationKey: record.continuationKey }), (record.abs === undefined ? {} : { abs: record.abs })), (record.title === undefined ? {} : { title: record.title })), (record.sdkAgentId === undefined
             ? {}
             : { sdkAgentId: record.sdkAgentId }));
     }

package/dist/internal/skills-sync.d.ts

@@ -1,9 +1,9 @@
 /**
- * Sync authored skills into the deployment's Agent Store so cloud-runtime
- * turns discover them natively. The engine writes through the hosted sink
- * at store-root `skills/<name>/…`; the cloud VM is launched with
- * `--agent-store-skills-dir /cursor/stores/deployment/skills` and walks that
- * directory the same way it walks a user store.
+ * Sync authored skills onto an Agent Store so cloud-runtime turns discover
+ * them natively. Hosted deployments write store-root `skills/<name>/…` (the
+ * VM's `--agent-store-skills-dir /cursor/stores/deployment/skills`). Local
+ * `serve`/`run` with `runtime: "cloud"` writes
+ * `agent-serve/<agent>/skills/<name>/…` on the USER store.
  */
 import { type FileSink } from "../files.js";
 import type { DiscoveredSkill } from "../types.js";
@@ -21,5 +21,7 @@ export declare function syncSkillsToStore(args: {
     /** Sweeps leftover keys from the pre-native `agentkit/v1/{agent}/skills/` prefix. */
     agentName: string;
     skills: readonly DiscoveredSkill[];
+    /** Store-root directory that holds SKILL.md files. Defaults to `skills/`. */
+    skillsPrefix?: string;
 }): Promise<void>;
 //# sourceMappingURL=skills-sync.d.ts.map

package/dist/internal/skills-sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills-sync.d.ts","sourceRoot":"","sources":["../../src/internal/skills-sync.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAqC,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE/E,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,aAAa,CAAC;AAQpE;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,IAAI,EAAE,QAAQ,CAAC;IACf,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;CACpC,GAAG,OAAO,CAAC,IAAI,CAAC,CAsBhB"}
+{"version":3,"file":"skills-sync.d.ts","sourceRoot":"","sources":["../../src/internal/skills-sync.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAAqC,KAAK,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE/E,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,aAAa,CAAC;AAQpE;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,IAAI,EAAE,QAAQ,CAAC;IACf,qFAAqF;IACrF,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;IACnC,6EAA6E;IAC7E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuBhB"}

package/dist/internal/skills-sync.js

@@ -1,9 +1,9 @@
 /**
- * Sync authored skills into the deployment's Agent Store so cloud-runtime
- * turns discover them natively. The engine writes through the hosted sink
- * at store-root `skills/<name>/…`; the cloud VM is launched with
- * `--agent-store-skills-dir /cursor/stores/deployment/skills` and walks that
- * directory the same way it walks a user store.
+ * Sync authored skills onto an Agent Store so cloud-runtime turns discover
+ * them natively. Hosted deployments write store-root `skills/<name>/…` (the
+ * VM's `--agent-store-skills-dir /cursor/stores/deployment/skills`). Local
+ * `serve`/`run` with `runtime: "cloud"` writes
+ * `agent-serve/<agent>/skills/<name>/…` on the USER store.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -34,9 +34,11 @@ function legacySkillsPrefix(agent) {
  */
 export function syncSkillsToStore(args) {
     return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const skillsPrefix = (_a = args.skillsPrefix) !== null && _a !== void 0 ? _a : agentStoreKeys.skillsPrefix();
         const desired = new Map();
         for (const skill of args.skills) {
-            const key = (relPath) => agentStoreKeys.skillFile(skill.name, relPath);
+            const key = (relPath) => agentStoreKeys.skillFile(skill.name, relPath, skillsPrefix);
             desired.set(key("SKILL.md"), Buffer.from(buildSkillMd(skill), "utf8"));
             for (const [relPath, source] of Object.entries(skill.files)) {
                 desired.set(key(storeRelPath(relPath)), yield sourceBytes(source));
@@ -44,7 +46,7 @@ export function syncSkillsToStore(args) {
         }
         yield Promise.all([...desired].map(([key, body]) => putLastWriterWins(args.sink, key, body)));
         const [existing, leftover] = yield Promise.all([
-            args.sink.list(agentStoreKeys.skillsPrefix()),
+            args.sink.list(skillsPrefix),
             args.sink.list(legacySkillsPrefix(args.agentName)),
         ]);
         yield Promise.all([...existing.filter((entry) => !desired.has(entry.key)), ...leftover].map((entry) => args.sink.delete(entry.key)));

package/dist/internal/tool-policy.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The one decision every tool call passes through.
+ *
+ * A tool body can be reached by more than one path — the model's own calls on
+ * a local turn, a cloud turn's calls over the MCP endpoint, a direct
+ * `callTool`, the host connection bridge. Each of those is a separate code
+ * path, and a guarantee that holds on some of them is not a guarantee. So the
+ * decision lives here, in one pure function, and every path asks it rather
+ * than re-implementing it.
+ */
+import type { ToolEffect, ToolEffectDeclaration, ToolExecuteResult } from "../types.js";
+/** What the host does with one tool call. */
+export type ToolDecision = 
+/** Run the tool body. */
+{
+    kind: "run";
+}
+/** Do not run it; return this to the model instead. */
+ | {
+    kind: "answer";
+    result: ToolExecuteResult;
+};
+/** What a policy decision needs to know about the call. */
+export interface ToolCallFacts {
+    /** The session answers writes instead of running them. */
+    dryRun: boolean;
+    /** The tool's declaration, if it made one. */
+    effect: ToolEffectDeclaration<never> | undefined;
+    /** What a stubbed write should answer with, if the tool supplied one. */
+    dryRunResult?: ToolExecuteResult | ((input: never) => ToolExecuteResult);
+    /**
+     * Validated input, as the tool body would receive it. Only read by a
+     * per-call `effect` predicate and by a `dryRunResult` function, so a caller
+     * with neither — a bridged MCP tool, which carries no declaration at all —
+     * can omit it.
+     */
+    input?: unknown;
+}
+/**
+ * The effect of one specific call.
+ *
+ * Undeclared resolves to `"write"`. A dry run promises that nothing outside
+ * the session changed, and it cannot promise that about a tool it knows
+ * nothing about — so the unknown case is the one that costs a stubbed read
+ * rather than the one that leaks a real write.
+ */
+export declare function resolveEffect(effect: ToolEffectDeclaration<never> | undefined, input: unknown): ToolEffect;
+/** Decide what to do with one tool call. Pure; no I/O, no session state. */
+export declare function decideToolCall(facts: ToolCallFacts): ToolDecision;
+//# sourceMappingURL=tool-policy.d.ts.map

package/dist/internal/tool-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-policy.d.ts","sourceRoot":"","sources":["../../src/internal/tool-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,UAAU,EACV,qBAAqB,EACrB,iBAAiB,EAClB,MAAM,aAAa,CAAC;AAErB,6CAA6C;AAC7C,MAAM,MAAM,YAAY;AACtB,yBAAyB;AACvB;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE;AACjB,uDAAuD;GACrD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,CAAC;AAElD,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,MAAM,EAAE,OAAO,CAAC;IAChB,8CAA8C;IAC9C,MAAM,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC;IACjD,yEAAyE;IACzE,YAAY,CAAC,EAAE,iBAAiB,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,KAAK,iBAAiB,CAAC,CAAC;IACzE;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAUD;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,qBAAqB,CAAC,KAAK,CAAC,GAAG,SAAS,EAChD,KAAK,EAAE,OAAO,GACb,UAAU,CAIZ;AAED,4EAA4E;AAC5E,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,YAAY,CAWjE"}

package/dist/internal/tool-policy.js

@@ -0,0 +1,51 @@
+/**
+ * The one decision every tool call passes through.
+ *
+ * A tool body can be reached by more than one path — the model's own calls on
+ * a local turn, a cloud turn's calls over the MCP endpoint, a direct
+ * `callTool`, the host connection bridge. Each of those is a separate code
+ * path, and a guarantee that holds on some of them is not a guarantee. So the
+ * decision lives here, in one pure function, and every path asks it rather
+ * than re-implementing it.
+ */
+/**
+ * What a stubbed write answers. Deliberately not self-describing: a model told
+ * mid-turn that its writes are not real starts hedging its conclusions, and
+ * the conclusion is the thing a dry run exists to read. Tell the agent once,
+ * in its opening prompt, not in a tool result.
+ */
+const ACKNOWLEDGED = "Operation acknowledged.";
+/**
+ * The effect of one specific call.
+ *
+ * Undeclared resolves to `"write"`. A dry run promises that nothing outside
+ * the session changed, and it cannot promise that about a tool it knows
+ * nothing about — so the unknown case is the one that costs a stubbed read
+ * rather than the one that leaks a real write.
+ */
+export function resolveEffect(effect, input) {
+    const declared = typeof effect === "function" ? effect(input) : effect;
+    return declared === "read" ? "read" : "write";
+}
+/** Decide what to do with one tool call. Pure; no I/O, no session state. */
+export function decideToolCall(facts) {
+    if (!facts.dryRun) {
+        return { kind: "run" };
+    }
+    if (resolveEffect(facts.effect, facts.input) === "read") {
+        return { kind: "run" };
+    }
+    return {
+        kind: "answer",
+        result: dryRunAnswer(facts.dryRunResult, facts.input),
+    };
+}
+function dryRunAnswer(dryRunResult, input) {
+    if (dryRunResult === undefined) {
+        return ACKNOWLEDGED;
+    }
+    if (typeof dryRunResult === "function") {
+        return dryRunResult(input);
+    }
+    return dryRunResult;
+}