@cursor/july 0.1.82 → 0.1.84

package/src/tools.ts

@@ -59,6 +59,7 @@ import type {
   JsonSchemaObject,
   ToolContext,
   ToolDefinition,
+  ToolEffectDeclaration,
   ToolExecuteResult,
   ToolNeedsApproval,
 } from "./types.js";
@@ -70,6 +71,8 @@ export type {
   ToolConfig,
   ToolContext,
   ToolDefinition,
+  ToolEffect,
+  ToolEffectDeclaration,
   ToolExecuteResult,
   ToolExecution,
   ToolNeedsApproval,
@@ -91,6 +94,15 @@ type ServerToolConfig<TSchema> = {
    */
   outputSchema?: z.ZodTypeAny | JsonSchemaObject;
   needsApproval?: ToolNeedsApproval<ToolInput<TSchema>>;
+  /**
+   * Whether this tool changes anything outside the session. Undeclared means
+   * write, so a dry-run session answers it instead of running it.
+   */
+  effect?: ToolEffectDeclaration<ToolInput<TSchema>>;
+  /** What a `"write"` tool returns in a dry-run session. */
+  dryRunResult?:
+    | ToolExecuteResult
+    | ((input: ToolInput<TSchema>) => ToolExecuteResult);
   execute: (
     input: ToolInput<TSchema>,
     ctx: ToolContext
@@ -112,6 +124,13 @@ type AgentToolConfig<TSchema> = {
   execute?: never;
   /** Human-in-the-loop approvals are only supported for server tools. */
   needsApproval?: never;
+  /**
+   * Agent tools run inside the harness, not through the host's tool path, so
+   * a dry run cannot answer them. Classify the work as a server tool if it
+   * needs to be dry-runnable.
+   */
+  effect?: never;
+  dryRunResult?: never;
 };
 
 /**

package/src/types.ts

@@ -867,6 +867,35 @@ export type ToolNeedsApproval<TInput> =
   | boolean
   | ((input: TInput) => boolean | Promise<boolean>);
 
+/**
+ * Whether invoking a tool can change anything outside this session.
+ *
+ * `"read"` cannot, by construction — a query, a file read, a listing.
+ * `"write"` changes something a person or another agent will later see: an
+ * external system (a comment, a message, a ticket) or shared storage another
+ * session reads back.
+ *
+ * This is what {@link SendMessageOptions.dryRun} enforces. In a dry-run
+ * session a write is answered by the host and never executed, while reads run
+ * for real — so an agent can be run against real data to see what it *would*
+ * have done.
+ *
+ * A tool that declares nothing is treated as a write: a dry run promises
+ * "nothing outside this session changed", which it cannot promise about a tool
+ * it knows nothing about. An unannotated tool is therefore useless in a dry
+ * run.
+ */
+export type ToolEffect = "read" | "write";
+
+/**
+ * A tool's declared {@link ToolEffect} — fixed, or decided per call from
+ * validated input for tools that read or write depending on their arguments
+ * (an HTTP request keyed on method, a SQL tool keyed on statement).
+ */
+export type ToolEffectDeclaration<TInput> =
+  | ToolEffect
+  | ((input: TInput) => ToolEffect);
+
 export interface ToolConfig<TInput> {
   description: string;
   /**
@@ -895,6 +924,20 @@ export interface ToolConfig<TInput> {
    * `execution: "server"` tools on the local runtime.
    */
   needsApproval?: ToolNeedsApproval<TInput>;
+  /**
+   * Whether this tool changes anything outside the session. Undeclared means
+   * write, so a dry run stubs it — see {@link ToolEffect}.
+   */
+  effect?: ToolEffectDeclaration<TInput>;
+  /**
+   * What a write tool returns in a dry-run session instead of executing.
+   *
+   * Omit for a tool whose result the caller only acknowledges. Supply one when
+   * the result is read structurally — a caller that uses `result.revision`
+   * breaks on a bare string — so a dry run stays on the same path production
+   * takes. Ignored unless {@link effect} resolves to `"write"`.
+   */
+  dryRunResult?: ToolExecuteResult | ((input: TInput) => ToolExecuteResult);
   /**
    * In-process implementation. Required when {@link execution} is
    * `"server"` (the default); ignored for `"agent"` tools.
@@ -918,6 +961,10 @@ export interface ToolDefinition extends BrandedDefinition<"tool"> {
   readonly inputSchema?: z.ZodTypeAny | JsonSchemaObject;
   readonly outputSchema?: z.ZodTypeAny | JsonSchemaObject;
   readonly needsApproval?: ToolNeedsApproval<never>;
+  readonly effect?: ToolEffectDeclaration<never>;
+  readonly dryRunResult?:
+    | ToolExecuteResult
+    | ((input: never) => ToolExecuteResult);
   readonly execute?: (
     input: never,
     ctx: ToolContext
@@ -1349,6 +1396,13 @@ export type SessionEventPayload =
         toolName: string;
         output?: unknown;
         isError: boolean;
+        /**
+         * The tool never ran: a write answered by the host in a `dryRun`
+         * session. `actions.requested` still carries the arguments the model
+         * chose, so this is the marker that separates "what it would have
+         * done" from a real effect when reading a trajectory.
+         */
+        stubbed?: true;
         parentCallId?: string;
       };
     }
@@ -1451,6 +1505,8 @@ export interface SessionInfo {
   mode: SessionMode;
   /** Omit / `"live"` for production traffic; `"eval"` for eval harness sessions. */
   purpose?: SessionPurpose;
+  /** True when write-classified tool calls are answered by the host. */
+  dryRun?: boolean;
   auth: AuthContext | null;
   title?: string;
   /**
@@ -1483,6 +1539,8 @@ export interface SessionRecord {
    * Older records omit this (treated as `"live"`).
    */
   purpose?: SessionPurpose;
+  /** Frozen at create from {@link SendMessageOptions.dryRun}. */
+  dryRun?: boolean;
   /**
    * Denormalized sticky A/B arms (mirrors durable `ab.assigned` events) so
    * the agent loop / tools can read arms without re-folding the log. Source
@@ -1657,6 +1715,15 @@ export interface SendMessageOptions {
    * (`defineAB`) so regression runs do not mix into live metrics.
    */
   purpose?: SessionPurpose;
+  /**
+   * Answer every write-classified tool call from the host instead of running
+   * it, for this session's whole life (create only — a follow-up cannot clear
+   * it, so a session that starts as a rehearsal stays one).
+   *
+   * Reads execute, writes are answered and recorded, and the arguments the
+   * model chose stay on the session log as the record of the intended action.
+   */
+  dryRun?: boolean;
   /**
    * Absolute directory used as the local harness `cwd` for this session.
    * On create, sets the session workspace. On resume (continuation hit),
@@ -2506,6 +2573,12 @@ export interface DiscoveredTool {
    * predicate). Runtime evaluation still runs the predicate per call.
    */
   needsApproval: boolean;
+  /**
+   * The tool's declared {@link ToolEffect} when it declares one statically, or
+   * `"dynamic"` when it declares a predicate resolved per call. Absent when it
+   * declares nothing, which a dry run treats as a write.
+   */
+  effect?: ToolEffect | "dynamic";
   /**
    * Agent tools: script body materialized under
    * `.agent-serve/tools/<name>.sh`.
@@ -2769,6 +2842,11 @@ export interface RunnerTurnRequest {
   runtime: AgentRuntime;
   /** Cloud options when {@link runtime} is `"cloud"`. */
   cloud?: AgentCloudOptions;
+  /**
+   * defineAgent directory slug for personal-key cloud creates. Injected
+   * by the engine — not part of authored {@link AgentCloudOptions}.
+   */
+  agentServeAgent?: string;
   /** In-process tools, already bound to the session's tool context. */
   customTools: Record<string, SDKCustomTool>;
   /** MCP servers from `agent/mcp-connections/`. */