@theokit/sdk-tools 0.12.0 → 0.13.0

package/dist/index.d.cts

@@ -182,6 +182,34 @@ declare function commandDenialReason(command: string, policies: CommandPolicy[])
 /** `true` when no policy denies `command` (an empty policy array allows everything). */
 declare function isCommandAllowed(command: string, policies: CommandPolicy[]): boolean;
 
+/**
+ * Context-tolerant single-occurrence text matching (`seek_sequence` parity, ported
+ * from the AgentBuilder Codex clone, M10/M13). Where a naive `edit_file` matches
+ * `old_string` byte-for-byte (or with a single whitespace-normalized fallback),
+ * this matcher is safe AND forgiving:
+ *
+ *   Stage 1 — exact byte substring, with an **ambiguity guard**: if the target
+ *     appears more than once it throws instead of silently editing the first hit
+ *     (a too-short `old_string` editing the wrong location is the classic footgun).
+ *   Stage 2 — line-based match down a **strictness ladder** (exact → rstrip → trim
+ *     → unicode-normalize), stopping at the first rung that yields exactly ONE
+ *     match; a rung matching 2+ positions throws (ambiguous), never picks one.
+ *
+ * Pure. Preserves the file's CRLF/LF style on the replaced region. Throws typed
+ * {@link ContextMatchError} (`empty | ambiguous | not_found`) so the caller maps to
+ * its own `{ ok: false, error }` shape.
+ */
+type ContextMatchReason = "empty" | "ambiguous" | "not_found";
+declare class ContextMatchError extends Error {
+    readonly reason: ContextMatchReason;
+    constructor(reason: ContextMatchReason, message: string);
+}
+/**
+ * Return `content` with the single occurrence of `find` replaced by `replace`, using the two-stage
+ * context-tolerant matcher. Throws {@link ContextMatchError} on empty/ambiguous/not-found.
+ */
+declare function replaceUnique(content: string, find: string, replace: string): string;
+
 /**
  * SSRF guard for network tools (M3-1).
  *
@@ -975,4 +1003,4 @@ interface CreateWriteFileToolOptions {
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, ReadTracker, ReasoningTools, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, ReadTracker, ReasoningTools, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };

package/dist/index.d.ts

@@ -182,6 +182,34 @@ declare function commandDenialReason(command: string, policies: CommandPolicy[])
 /** `true` when no policy denies `command` (an empty policy array allows everything). */
 declare function isCommandAllowed(command: string, policies: CommandPolicy[]): boolean;
 
+/**
+ * Context-tolerant single-occurrence text matching (`seek_sequence` parity, ported
+ * from the AgentBuilder Codex clone, M10/M13). Where a naive `edit_file` matches
+ * `old_string` byte-for-byte (or with a single whitespace-normalized fallback),
+ * this matcher is safe AND forgiving:
+ *
+ *   Stage 1 — exact byte substring, with an **ambiguity guard**: if the target
+ *     appears more than once it throws instead of silently editing the first hit
+ *     (a too-short `old_string` editing the wrong location is the classic footgun).
+ *   Stage 2 — line-based match down a **strictness ladder** (exact → rstrip → trim
+ *     → unicode-normalize), stopping at the first rung that yields exactly ONE
+ *     match; a rung matching 2+ positions throws (ambiguous), never picks one.
+ *
+ * Pure. Preserves the file's CRLF/LF style on the replaced region. Throws typed
+ * {@link ContextMatchError} (`empty | ambiguous | not_found`) so the caller maps to
+ * its own `{ ok: false, error }` shape.
+ */
+type ContextMatchReason = "empty" | "ambiguous" | "not_found";
+declare class ContextMatchError extends Error {
+    readonly reason: ContextMatchReason;
+    constructor(reason: ContextMatchReason, message: string);
+}
+/**
+ * Return `content` with the single occurrence of `find` replaced by `replace`, using the two-stage
+ * context-tolerant matcher. Throws {@link ContextMatchError} on empty/ambiguous/not-found.
+ */
+declare function replaceUnique(content: string, find: string, replace: string): string;
+
 /**
  * SSRF guard for network tools (M3-1).
  *
@@ -975,4 +1003,4 @@ interface CreateWriteFileToolOptions {
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, ReadTracker, ReasoningTools, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateListDirToolOptions, type CreateReadFileToolOptions, type CreateRunVitestToolOptions, type CreateSearchTextToolOptions, type CreateShellToolOptions, type CreateWebFetchToolOptions, type CreateWebSearchToolOptions, type CreateWriteFileToolOptions, DEFAULT_TOOL_GUIDANCE, type EnvContextOptions, type PlanModeTool, type PlanModeToolOptions, type PlanModeToolWithStore, type PlanNode, type QuestionTool, type QuestionToolOptions, ReadTracker, ReasoningTools, RedirectBlockedError, type RepoMapOptions, type ResolveAndScreenOptions, type ScreenedFetchOptions, type SessionArtifactStore, type SessionArtifactStoreOptions, SsrfBlockedError, type TodoItem, type TodolistTool, type ToolGuidanceMap, type TruncationOptions, type TruncationResult, type VitestSummary, type WebSearchCallback, type WebSearchResult, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };

package/dist/index.js

@@ -263,6 +263,90 @@ function createSessionArtifactStore(options) {
   }
   return { write, read, has, list, path };
 }
+
+// src/internal/context-match.ts
+var ContextMatchError = class extends Error {
+  reason;
+  constructor(reason, message) {
+    super(message);
+    this.name = "ContextMatchError";
+    this.reason = reason;
+  }
+};
+function normalizeUnicode(s) {
+  return s.replace(/[‐-―−]/g, "-").replace(/[‘-‛]/g, "'").replace(/[“-‟]/g, '"').replace(/[ -   　]/g, " ");
+}
+var LINE_MATCH_LADDER = [
+  (s) => s,
+  // exact
+  (s) => s.replace(/\s+$/, ""),
+  // rstrip (ignore trailing whitespace)
+  (s) => s.trim(),
+  // trim (ignore leading + trailing)
+  (s) => normalizeUnicode(s).trim()
+  // unicode + trim (loosest)
+];
+function matchesAt(lines, pattern, i, norm) {
+  for (let p = 0; p < pattern.length; p++) {
+    const lineAt = lines[i + p];
+    const patAt = pattern[p];
+    if (lineAt === void 0 || patAt === void 0 || norm(lineAt) !== norm(patAt)) return false;
+  }
+  return true;
+}
+function findHits(lines, pattern, norm) {
+  const hits = [];
+  for (let i = 0; i + pattern.length <= lines.length; i++) {
+    if (matchesAt(lines, pattern, i, norm)) hits.push(i);
+  }
+  return hits;
+}
+function seekUniqueLineMatch(lines, pattern, find) {
+  if (pattern.length === 0 || pattern.length > lines.length) return null;
+  for (const norm of LINE_MATCH_LADDER) {
+    const hits = findHits(lines, pattern, norm);
+    if (hits.length === 1) return hits[0] ?? null;
+    if (hits.length > 1) {
+      throw new ContextMatchError(
+        "ambiguous",
+        `target text is ambiguous (multiple matches); include more context:
+${find}`
+      );
+    }
+  }
+  return null;
+}
+function replaceUnique(content, find, replace) {
+  if (find === "") {
+    throw new ContextMatchError(
+      "empty",
+      "empty find is not a valid target; provide the text to replace"
+    );
+  }
+  const first = content.indexOf(find);
+  if (first !== -1) {
+    if (content.indexOf(find, first + 1) !== -1) {
+      throw new ContextMatchError(
+        "ambiguous",
+        `target text is ambiguous (multiple matches); include more context:
+${find}`
+      );
+    }
+    return content.slice(0, first) + replace + content.slice(first + find.length);
+  }
+  const lines = content.split("\n");
+  const at = seekUniqueLineMatch(lines, find.split("\n"), find);
+  if (at === null) {
+    throw new ContextMatchError("not_found", `target text not found:
+${find}`);
+  }
+  const patternLen = find.split("\n").length;
+  const matchedCrlf = patternLen > 0 && lines.slice(at, at + patternLen).every((l) => l.endsWith("\r"));
+  const replaceLines = matchedCrlf ? replace.split("\n").map((l) => l.endsWith("\r") ? l : `${l}\r`) : replace.split("\n");
+  return [...lines.slice(0, at), ...replaceLines, ...lines.slice(at + patternLen)].join("\n");
+}
+
+// src/edit-file.ts
 function createEditFileTool(opts) {
   const { projectRoot } = opts;
   return Tool.create({
@@ -304,26 +388,36 @@ function createEditFileTool(opts) {
       const exactIdx = content.indexOf(old_string);
       if (exactIdx !== -1) {
         await copyFile(absolutePath, `${absolutePath}.bak`);
-        const result2 = content.slice(0, exactIdx) + new_string + content.slice(exactIdx + old_string.length);
-        await writeFile(absolutePath, result2, "utf-8");
+        const result = content.slice(0, exactIdx) + new_string + content.slice(exactIdx + old_string.length);
+        await writeFile(absolutePath, result, "utf-8");
         return JSON.stringify({ ok: true, replacements: 1 });
       }
       const normalizedContent = normalizeWhitespace(content);
       const normalizedOld = normalizeWhitespace(old_string);
       const normalizedIdx = normalizedContent.indexOf(normalizedOld);
-      if (normalizedIdx === -1) {
-        return JSON.stringify({ ok: false, error: "no_match", path });
+      if (normalizedIdx !== -1) {
+        const span = findOriginalSpan(
+          content,
+          normalizedContent,
+          normalizedIdx,
+          normalizedOld.length
+        );
+        await copyFile(absolutePath, `${absolutePath}.bak`);
+        const result = content.slice(0, span.start) + new_string + content.slice(span.end);
+        await writeFile(absolutePath, result, "utf-8");
+        return JSON.stringify({ ok: true, replacements: 1 });
+      }
+      try {
+        const result = replaceUnique(content, old_string, new_string);
+        await copyFile(absolutePath, `${absolutePath}.bak`);
+        await writeFile(absolutePath, result, "utf-8");
+        return JSON.stringify({ ok: true, replacements: 1 });
+      } catch (err) {
+        if (err instanceof ContextMatchError) {
+          return JSON.stringify({ ok: false, error: "no_match", path });
+        }
+        throw err;
       }
-      const span = findOriginalSpan(
-        content,
-        normalizedContent,
-        normalizedIdx,
-        normalizedOld.length
-      );
-      await copyFile(absolutePath, `${absolutePath}.bak`);
-      const result = content.slice(0, span.start) + new_string + content.slice(span.end);
-      await writeFile(absolutePath, result, "utf-8");
-      return JSON.stringify({ ok: true, replacements: 1 });
     }
   });
 }
@@ -2247,6 +2341,6 @@ async function isBinaryFile(absolutePath) {
   }
 }
 
-export { CatastrophicCommandError, DEFAULT_TOOL_GUIDANCE, ReadTracker, ReasoningTools, RedirectBlockedError, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, ContextMatchError, DEFAULT_TOOL_GUIDANCE, ReadTracker, ReasoningTools, RedirectBlockedError, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map