@spotpatch/agent 1.2.0 → 1.2.2

package/README.md

@@ -1,10 +1,33 @@
-# @spotpatch/agent
+<h1><a href="https://github.com/huanglvjing/spotpatch"><img src="https://raw.githubusercontent.com/huanglvjing/spotpatch/main/docs/assets/spotpatch-npm-icon.png" alt="SpotPatch" width="48" height="48" align="absmiddle" /></a> <code>@spotpatch/agent</code></h1>
 
-The Node-only SpotPatch Agent engine for provider protocols, bounded tools,
-isolated Git worktrees, validation checks, review, Apply, and conflict-safe
-Revert.
+## English
 
-Applications should enable this capability through trusted provider profiles in
-[`@spotpatch/vite`](https://www.npmjs.com/package/@spotpatch/vite). This package
-does not expose model-controlled shell execution and must never receive browser
-environment API keys.
+The Node-only Agent engine used by SpotPatch framework adapters. It owns OpenAI-compatible provider sessions, capability probes, bounded file tools, isolated Git worktrees, validation checks, Diff review, Apply, and conflict-safe Revert.
+
+Applications should enable this capability through a framework adapter such as [`@spotpatch/vite`](https://www.npmjs.com/package/@spotpatch/vite). This package is public so the adapter dependency graph can be installed and versioned; it is not a standalone UI integration.
+
+Security boundaries:
+
+- no model-controlled arbitrary shell;
+- no browser-side API keys;
+- bounded paths, reads, writes, Diff sizes, turns, and tool calls;
+- no implicit stash, reset, commit, push, publish, or deployment;
+- review is the default apply mode.
+
+Requires Node.js `>=20.19.0`.
+
+## 简体中文
+
+这是 SpotPatch 框架适配器使用的 Node-only Agent 引擎，负责 OpenAI-compatible Provider 会话、能力探测、有界文件工具、隔离 Git worktree、项目检查、Diff 审阅、Apply 和冲突安全的 Revert。
+
+业务应用应通过 [`@spotpatch/vite`](https://www.npmjs.com/package/@spotpatch/vite) 等框架适配器启用该能力。本包公开发布是为了形成可安装、可版本化的依赖图，不是独立 UI 接入入口。
+
+安全边界包括：不向模型开放任意 Shell、不把 API Key 放入浏览器、限制路径/读写/Diff/轮次/工具调用，并且不隐式执行 stash、reset、commit、push、发包或部署。默认应用模式必须经过审阅。
+
+要求 Node.js `>=20.19.0`。
+
+## Links / 链接
+
+- [Repository / 仓库](https://github.com/huanglvjing/spotpatch)
+- [AI execution model / AI 执行模型](https://github.com/huanglvjing/spotpatch/blob/main/docs/%E6%8A%80%E6%9C%AF%E6%96%B9%E6%A1%88/16-AIAgent%E6%89%A7%E8%A1%8C%E4%B8%8E%E5%8F%98%E6%9B%B4%E5%AE%A1%E9%98%85.md)
+- [MIT License / 许可证](https://github.com/huanglvjing/spotpatch/blob/main/LICENSE)

package/dist/index.cjs

@@ -69,9 +69,27 @@ function parseJsonRecord(value) {
 }
 function parseToolArguments(value) {
   if (typeof value !== "string") {
-    throw new import_shared.SpotPatchError(import_shared.ERROR_CODES.PROVIDER_PROTOCOL_UNSUPPORTED);
+    throw new import_shared.SpotPatchError(import_shared.ERROR_CODES.TOOL_ARGUMENTS_INVALID);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new import_shared.SpotPatchError(import_shared.ERROR_CODES.TOOL_ARGUMENTS_INVALID);
+  }
+  if (!isRecord(parsed)) {
+    throw new import_shared.SpotPatchError(import_shared.ERROR_CODES.TOOL_ARGUMENTS_INVALID);
+  }
+  return parsed;
+}
+function assertUniqueToolCallIds(calls) {
+  const ids = /* @__PURE__ */ new Set();
+  for (const call of calls) {
+    if (ids.has(call.id)) {
+      throw new import_shared.SpotPatchError(import_shared.ERROR_CODES.TOOL_CALL_ID_CONFLICT);
+    }
+    ids.add(call.id);
   }
-  return parseJsonRecord(value);
 }
 function requireString(record, field) {
   const value = record[field];
@@ -81,6 +99,7 @@ function requireString(record, field) {
   return value;
 }
 function validateToolResults(pendingCalls, results) {
+  assertUniqueToolCallIds(pendingCalls);
   if (pendingCalls.length === 0) {
     if (results !== void 0 && results.length > 0) {
       throw new import_shared.SpotPatchError(import_shared.ERROR_CODES.INTERNAL_ERROR);
@@ -478,6 +497,7 @@ function parseChatEvents(events) {
   }
   const finalText = content.join("");
   const toolCalls = finalizeToolCalls(calls);
+  assertUniqueToolCallIds(toolCalls);
   if (toolCalls.length === 0 && finalText.trim().length === 0) {
     throw new import_shared5.SpotPatchError(import_shared5.ERROR_CODES.PROVIDER_PROTOCOL_UNSUPPORTED);
   }
@@ -574,7 +594,7 @@ function collectFunctionCall(item, calls) {
   });
   const existing = calls.get(id);
   if (existing !== void 0 && (existing.name !== call.name || JSON.stringify(existing.arguments) !== JSON.stringify(call.arguments))) {
-    throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.PROVIDER_PROTOCOL_UNSUPPORTED);
+    throw new import_shared6.SpotPatchError(import_shared6.ERROR_CODES.TOOL_CALL_ID_CONFLICT);
   }
   calls.set(id, call);
 }
@@ -874,7 +894,7 @@ function encodeUtf8Text(content, includeByteOrderMark) {
 }
 async function writeAgentTextFileIfContentMatches(root, relativePath, expectedContent, nextContent, maximumBytes) {
   if (nextContent.includes("\0")) {
-    throw new import_shared9.SpotPatchError(import_shared9.ERROR_CODES.TOOL_INPUT_INVALID);
+    throw new import_shared9.SpotPatchError(import_shared9.ERROR_CODES.TOOL_ARGUMENTS_INVALID);
   }
   const absolutePath = await resolveExistingAgentPath(root, relativePath);
   const [metadata, currentBytes] = await Promise.all([
@@ -1066,7 +1086,10 @@ function minimalProcessEnvironment() {
     "LANG",
     "LC_ALL"
   ];
-  const environment = { CI: "1", NO_COLOR: "1" };
+  const environment = {
+    CI: "1",
+    NO_COLOR: "1"
+  };
   for (const name of allowedNames) {
     const value = process.env[name];
     if (value !== void 0) {
@@ -1143,7 +1166,7 @@ async function runConfiguredCheck(options) {
 function requireConfiguredCheck(checkId, checks) {
   const check = checks[checkId];
   if (check === void 0) {
-    throw new import_shared10.SpotPatchError(import_shared10.ERROR_CODES.TOOL_INPUT_INVALID);
+    throw new import_shared10.SpotPatchError(import_shared10.ERROR_CODES.TOOL_ARGUMENTS_INVALID);
   }
   return check;
 }
@@ -1455,7 +1478,7 @@ var MAX_DISCOVERED_FILES = 2e4;
 var TEXT_SAMPLE_BYTES = 8192;
 function compileGlob(glob) {
   if (glob.length === 0 || glob.length > 256 || glob.includes("\0") || glob.includes("\\") || glob.startsWith("/") || ["[", "]", "{", "}", "(", ")", "!"].some((character) => glob.includes(character)) || glob.split("/").some((segment) => segment === "..")) {
-    throw new import_shared14.SpotPatchError(import_shared14.ERROR_CODES.TOOL_INPUT_INVALID);
+    throw new import_shared14.SpotPatchError(import_shared14.ERROR_CODES.TOOL_ARGUMENTS_INVALID);
   }
   let expression = "^";
   for (let index = 0; index < glob.length; index += 1) {
@@ -1694,7 +1717,7 @@ var runCheckSchema = import_zod.z.strictObject({
   checkId: import_zod.z.string().min(1).max(64).regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/u)
 });
 function invalidTool() {
-  throw new import_shared15.SpotPatchError(import_shared15.ERROR_CODES.TOOL_INPUT_INVALID);
+  throw new import_shared15.SpotPatchError(import_shared15.ERROR_CODES.TOOL_ARGUMENTS_INVALID);
 }
 function parseArguments(schema, value) {
   const parsed = schema.safeParse(value);
@@ -1751,8 +1774,16 @@ function retryableWriteRejection(reason, guidance) {
     guidance
   });
 }
+function retryableArgumentsRejection() {
+  return Object.freeze({
+    errorCode: import_shared15.ERROR_CODES.TOOL_ARGUMENTS_INVALID,
+    retryable: true,
+    reason: "ARGUMENTS_DO_NOT_MATCH_CONTRACT",
+    guidance: "No files changed. Retry once with a new tool call ID and only the declared fields and value types."
+  });
+}
 function createAgentToolExecutor(options) {
-  const cache = /* @__PURE__ */ new Map();
+  const cacheByTurn = /* @__PURE__ */ new Map();
   const touchedPaths = /* @__PURE__ */ new Set();
   const executeUncached = async (call, signal) => {
     switch (call.name) {
@@ -1968,20 +1999,32 @@ function createAgentToolExecutor(options) {
     }
   };
   return Object.freeze({
-    async execute(call, signal) {
+    async execute(call, scope, signal) {
+      if (!Number.isSafeInteger(scope.turn) || scope.turn < 1) {
+        throw new import_shared15.SpotPatchError(import_shared15.ERROR_CODES.INTERNAL_ERROR);
+      }
+      const turnCache = cacheByTurn.get(scope.turn) ?? /* @__PURE__ */ new Map();
+      cacheByTurn.set(scope.turn, turnCache);
       const signature = `${call.name}\0${JSON.stringify(call.arguments)}`;
-      const cached = cache.get(call.id);
+      const cached = turnCache.get(call.id);
       if (cached !== void 0) {
         if (cached.signature !== signature) {
-          return invalidTool();
+          throw new import_shared15.SpotPatchError(import_shared15.ERROR_CODES.TOOL_CALL_ID_CONFLICT);
         }
         return cached.result;
       }
-      const result = Object.freeze({
-        toolCallId: call.id,
-        output: await executeUncached(call, signal)
-      });
-      cache.set(call.id, Object.freeze({ signature, result }));
+      let output;
+      try {
+        output = await executeUncached(call, signal);
+      } catch (error) {
+        if (error instanceof import_shared15.SpotPatchError && error.code === import_shared15.ERROR_CODES.TOOL_ARGUMENTS_INVALID) {
+          output = retryableArgumentsRejection();
+        } else {
+          throw error;
+        }
+      }
+      const result = Object.freeze({ toolCallId: call.id, output });
+      turnCache.set(call.id, Object.freeze({ signature, result }));
       return result;
     },
     touchedPaths() {
@@ -2552,6 +2595,7 @@ Follow these rules exactly:
 - Use apply_patch only when creating or deleting a file, or when the change cannot be expressed as one exact replacement. apply_patch accepts only a raw canonical unified Git diff.
 - 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.
 - Never modify credentials, environment files, lockfiles, generated output, Git metadata, or dependencies.
 - Do not claim a check passed unless run_check returned a passed status.
 - Finish with a concise factual summary after all needed tool calls. Do not include secrets or absolute paths.`;
@@ -2568,6 +2612,12 @@ function sliceText(value, maximum) {
 function createBoundedTarget(target, maximumCharacters) {
   const detailBudget = Math.max(192, maximumCharacters - 420);
   const bounded = {
+    ...target.page === void 0 ? {} : {
+      page: Object.freeze({
+        ...target.page,
+        url: (0, import_shared19.sanitizeUrl)(target.page.url, "http://spotpatch.invalid")
+      })
+    },
     source: target.source,
     react: Object.freeze({
       supported: target.react.supported,
@@ -2711,7 +2761,7 @@ function isRetryableToolFailure(result) {
     return false;
   }
   const candidate = output;
-  return candidate.errorCode === import_shared20.ERROR_CODES.PATCH_REJECTED && candidate.retryable === true;
+  return candidate.retryable === true && (candidate.errorCode === import_shared20.ERROR_CODES.PATCH_REJECTED || candidate.errorCode === import_shared20.ERROR_CODES.TOOL_ARGUMENTS_INVALID);
 }
 function throwIfCancelled(signal) {
   if (signal.aborted) {
@@ -2787,8 +2837,10 @@ async function executeAgentChange(options) {
     let summary;
     let toolCallCount = 0;
     for (let turn = 0; turn < options.execution.limits.maxTurns; turn += 1) {
+      const turnNumber = turn + 1;
       throwIfCancelled(controller.signal);
       const response = await session.next(pendingResults, controller.signal);
+      assertUniqueToolCallIds(response.toolCalls);
       if (response.toolCalls.length === 0) {
         summary = response.finalText.trim().slice(0, options.execution.limits.maxToolOutputCharacters);
         break;
@@ -2801,16 +2853,22 @@ async function executeAgentChange(options) {
       for (const call of response.toolCalls) {
         options.callbacks?.onTool?.(
           Object.freeze({
+            turn: turnNumber,
             toolCallId: call.id,
             toolName: call.name,
             state: "started"
           })
         );
         try {
-          const result2 = await executor.execute(call, controller.signal);
+          const result2 = await executor.execute(
+            call,
+            Object.freeze({ turn: turnNumber }),
+            controller.signal
+          );
           results.push(result2);
           options.callbacks?.onTool?.(
             Object.freeze({
+              turn: turnNumber,
               toolCallId: call.id,
               toolName: call.name,
               state: isRetryableToolFailure(result2) ? "failed" : "succeeded"
@@ -2819,6 +2877,7 @@ async function executeAgentChange(options) {
         } catch (error) {
           options.callbacks?.onTool?.(
             Object.freeze({
+              turn: turnNumber,
               toolCallId: call.id,
               toolName: call.name,
               state: "failed"