@spotpatch/agent 1.2.3 → 1.3.0

package/README.md

@@ -11,6 +11,7 @@ Security boundaries:
 - no model-controlled arbitrary shell;
 - no browser-side API keys;
 - bounded paths, reads, writes, Diff sizes, turns, and tool calls;
+- rejected read paths stay unread and unmodified while the bounded Agent loop can recover through allowed discovery results;
 - no implicit stash, reset, commit, push, publish, or deployment;
 - review is the default apply mode.
 
@@ -22,7 +23,7 @@ Requires Node.js `>=20.19.0`.
 
 业务应用应通过 [`@spotpatch/vite`](https://www.npmjs.com/package/@spotpatch/vite) 等框架适配器启用该能力。本包公开发布是为了形成可安装、可版本化的依赖图，不是独立 UI 接入入口。
 
-安全边界包括：不向模型开放任意 Shell、不把 API Key 放入浏览器、限制路径/读写/Diff/轮次/工具调用，并且不隐式执行 stash、reset、commit、push、发包或部署。默认应用模式必须经过审阅。
+安全边界包括：不向模型开放任意 Shell、不把 API Key 放入浏览器、限制路径/读写/Diff/轮次/工具调用；只读路径被拒绝时保持零读取、零修改，并允许 Agent 在既有边界内改用合法发现结果继续执行；不隐式执行 stash、reset、commit、push、发包或部署。默认应用模式必须经过审阅。
 
 要求 Node.js `>=20.19.0`。
 

package/dist/index.cjs

@@ -1872,7 +1872,7 @@ var AGENT_TOOL_DEFINITIONS = Object.freeze([
   }),
   Object.freeze({
     name: AGENT_TOOL_NAMES.readFile,
-    description: "Read a bounded inclusive line range from one allowed UTF-8 text file.",
+    description: "Read a bounded inclusive line range from one allowed UTF-8 text file. Choose an exact path supplied by trusted SpotPatch context or returned by list_files or search_text. A retryable TOOL_PATH_DENIED result means no file was read or changed: do not retry that path; discover an allowed path instead.",
     parameters: Object.freeze({
       type: "object",
       properties: Object.freeze({
@@ -1926,6 +1926,11 @@ var AGENT_TOOL_DEFINITIONS = Object.freeze([
     })
   })
 ]);
+var AGENT_TOOL_DEFINITIONS_WITHOUT_CHECKS = Object.freeze(
+  AGENT_TOOL_DEFINITIONS.filter(
+    (definition) => definition.name !== AGENT_TOOL_NAMES.runCheck
+  )
+);
 
 // src/tools/tool-executor.ts
 var SEARCH_READ_CONCURRENCY = 8;
@@ -2018,6 +2023,14 @@ function retryableArgumentsRejection() {
     guidance: "No files changed. Retry once with a new tool call ID and only the declared fields and value types."
   });
 }
+function retryableReadRejection() {
+  return Object.freeze({
+    errorCode: import_shared15.ERROR_CODES.TOOL_PATH_DENIED,
+    retryable: true,
+    reason: "PATH_UNAVAILABLE",
+    guidance: "No file was read or changed. Do not retry the same path. Use list_files or search_text, then read only an allowed path returned by that tool. Protected, external, missing, symlinked, directory, binary, and non-UTF-8 paths are unavailable."
+  });
+}
 function createAgentToolExecutor(options) {
   const cacheByTurn = /* @__PURE__ */ new Map();
   const fileCatalog = createAgentFileCatalog(options.worktreeRoot);
@@ -2117,7 +2130,15 @@ function createAgentToolExecutor(options) {
       }
       case AGENT_TOOL_NAMES.readFile: {
         const input = parseArguments(readFileSchema, call.arguments);
-        const file = await readTextFile(input.path);
+        let file;
+        try {
+          file = await readTextFile(input.path);
+        } catch (error) {
+          if (error instanceof import_shared15.SpotPatchError && error.code === import_shared15.ERROR_CODES.TOOL_PATH_DENIED) {
+            return retryableReadRejection();
+          }
+          throw error;
+        }
         const lines = file.content.split(/\r?\n/u);
         const startLine = input.startLine ?? 1;
         const endLine = input.endLine ?? Math.min(lines.length, startLine + 199);
@@ -2845,6 +2866,7 @@ var import_shared19 = require("@spotpatch/shared");
 var MAX_PROJECT_CONVENTION_CHARACTERS = 3500;
 var MAX_VALIDATION_CHECK_CHARACTERS = 1200;
 var MINIMUM_SELECTION_CONTEXT_CHARACTERS = 1024;
+var VALIDATION_SYSTEM_INSTRUCTION = "- Run each relevant configured check after the final write so failures can be corrected. Do not rerun an unchanged check, and do not claim a check passed unless run_check returned a passed status.\n";
 var AGENT_SYSTEM_INSTRUCTIONS = `You are editing code only inside a disposable, isolated Git worktree.
 
 Follow these rules exactly:
@@ -2859,9 +2881,13 @@ Follow these rules exactly:
 - Every patch must begin with 'diff --git a/<path> b/<path>', include matching '--- a/<path>' and '+++ b/<path>' headers and valid '@@' hunks. Send only the raw diff: no Markdown fences, prose, shell commands, or '*** Begin Patch' markers.
 - If a write tool returns a retryable PATCH_REJECTED result, no file changed. Follow its guidance, re-read the current file, and retry once with a new tool call ID.
 - If any tool returns a retryable TOOL_ARGUMENTS_INVALID result, no file changed. Retry once with a new tool call ID using only the declared fields and value types.
+- If read_file returns a retryable TOOL_PATH_DENIED result, no file was read or changed. Do not retry that path. Use list_files or search_text and choose an allowed path returned by the tool; never probe protected, external, generated, credential, environment, or lock files.
 - Never modify credentials, environment files, lockfiles, generated output, Git metadata, or dependencies.
-- Run each relevant configured check after the final write so failures can be corrected. Do not rerun an unchanged check, and do not claim a check passed unless run_check returned a passed status.
+${VALIDATION_SYSTEM_INSTRUCTION.trimEnd()}
 - Finish with a concise factual summary after all needed tool calls. Do not include secrets or absolute paths.`;
+function resolveAgentSystemInstructions(trustedFast) {
+  return trustedFast ? AGENT_SYSTEM_INSTRUCTIONS.replace(VALIDATION_SYSTEM_INSTRUCTION, "") : AGENT_SYSTEM_INSTRUCTIONS;
+}
 function redactedJson(value) {
   return JSON.stringify(
     value,
@@ -3053,7 +3079,8 @@ function composeAgentUserPrompt(annotation, maximumCharacters, context = {}) {
     (target, index) => `Target ${String(index + 1)}:
 ${(0, import_shared19.redactSensitiveText)(target.instruction.trim())}`
   ).join("\n\n");
-  const requestBlock = `${requestPrefix}${request}`;
+  const trustedFastBlock = context.trustedFast ? "\n\nTrusted direct execution is enabled. Start from each target's supplied code.relativePath or source.relativePath. When an exact path is present, do not call list_files first. Read each affected file once unless a write is rejected, make the smallest exact replacement that satisfies the request, and finish immediately after the successful write. No project validation check is available in this mode." : "";
+  const requestBlock = `${requestPrefix}${request}${trustedFastBlock}`;
   const checksPrefix = "\n\nConfigured validation checks (IDs and labels only):\n<validation_checks>\n";
   const checksSuffix = "\n</validation_checks>";
   if (requestBlock.length + contextPrefix.length + suffix.length + MINIMUM_SELECTION_CONTEXT_CHARACTERS > maximumCharacters) {
@@ -3091,7 +3118,7 @@ function isRetryableToolFailure(result) {
     return false;
   }
   const candidate = output;
-  return candidate.retryable === true && (candidate.errorCode === import_shared20.ERROR_CODES.PATCH_REJECTED || candidate.errorCode === import_shared20.ERROR_CODES.TOOL_ARGUMENTS_INVALID);
+  return candidate.retryable === true && (candidate.errorCode === import_shared20.ERROR_CODES.PATCH_REJECTED || candidate.errorCode === import_shared20.ERROR_CODES.TOOL_ARGUMENTS_INVALID || candidate.errorCode === import_shared20.ERROR_CODES.TOOL_PATH_DENIED);
 }
 function throwIfCancelled(signal) {
   if (signal.aborted) {
@@ -3156,6 +3183,8 @@ async function executeToolCalls(calls, turn, executor, callbacks, signal) {
   return Object.freeze(results);
 }
 async function executeAgentChange(options) {
+  const trustedFast = options.execution.applyMode === "trusted-auto";
+  const activeChecks = trustedFast ? Object.freeze({}) : options.execution.checks;
   const controller = new AbortController();
   const unlink = linkSignal(options.signal, controller);
   let jobTimedOut = false;
@@ -3187,7 +3216,7 @@ async function executeAgentChange(options) {
       })
     );
     const executor = createAgentToolExecutor({
-      checks: options.execution.checks,
+      checks: activeChecks,
       limits: options.execution.limits,
       worktreeRoot: worktree.root,
       onCheck(result2) {
@@ -3203,16 +3232,17 @@ async function executeAgentChange(options) {
       provider: options.provider,
       model: options.model,
       credential: options.credential,
-      instructions: AGENT_SYSTEM_INSTRUCTIONS,
+      instructions: resolveAgentSystemInstructions(trustedFast),
       userPrompt: composeAgentUserPrompt(
         options.annotation,
         options.promptMaxCharacters ?? 16e3,
         Object.freeze({
-          checks: options.execution.checks,
-          projectConventions
+          checks: activeChecks,
+          projectConventions,
+          trustedFast
         })
       ),
-      tools: AGENT_TOOL_DEFINITIONS,
+      tools: trustedFast ? AGENT_TOOL_DEFINITIONS_WITHOUT_CHECKS : AGENT_TOOL_DEFINITIONS,
       limits: options.execution.limits,
       ...options.fetch === void 0 ? {} : { fetch: options.fetch }
     });
@@ -3249,7 +3279,7 @@ async function executeAgentChange(options) {
     options.callbacks?.onPhase?.(
       Object.freeze({
         phase: "validating",
-        message: "Validating proposed changes."
+        message: trustedFast ? "Preparing trusted change for direct apply." : "Validating proposed changes."
       })
     );
     const initialChangeSet = await collectAgentChangeSet(
@@ -3258,7 +3288,7 @@ async function executeAgentChange(options) {
       options.execution.limits,
       controller.signal
     );
-    const requiredChecks = initialChangeSet.diff.length === 0 ? [] : Object.values(options.execution.checks).filter((check) => check.required);
+    const requiredChecks = initialChangeSet.diff.length === 0 ? [] : Object.values(activeChecks).filter((check) => check.required);
     const finalChecks = [];
     let ranFinalCheck = false;
     for (const check of requiredChecks) {