@theokit/sdk-tools 0.26.2 → 0.26.3

package/dist/index.d.cts

@@ -130,7 +130,7 @@ declare function createCurrentTimeTool(opts?: CreateCurrentTimeToolOptions): Cus
 
 interface CreateEditFileToolOptions {
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ today's literal (additive).
      *
      * It exists because, in Codex, the name is BORN in the tool definition and is the approval decision
      * key — three consumers (model, approval, telemetry) of a string decided in one place. Renaming
@@ -226,15 +226,15 @@ interface CreateGitStatusToolOptions {
     maxStdoutBytes?: number;
     /**
      * Injected execution backend (`@theokit/sdk/sandbox`) — when present, `git status` runs via
-     * `SandboxBackend.execute`; omitido ⇒ o `git` local (inalterado).
+     * `SandboxBackend.execute`; omitted ⇒ the local `git` (unchanged).
      *
      * Symmetry with `createGitDiffTool`, flagged by the M76 review: without it `git_diff` would run
      * confined and `git_status` not, in the same session — and the asymmetry would be invisible until someone
-     * perceber que uma das duas escapa do sandbox.
+     * notice that one of the two escapes the sandbox.
      */
     sandbox?: SandboxProvider;
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ `"git_status"` (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ `"git_status"` (additive).
      *
      * The name is a contract: the approval key, what the model sees and what telemetry records.
      */
@@ -490,7 +490,7 @@ declare function buildRepoMap(cwd: string, opts?: RepoMapOptions): string;
  * This is a heuristic GUARDRAIL, NOT a sandbox: it is bypassable by deep obfuscation
  * (base64/env-indirection) and is best-effort. POSIX `/bin/sh` only; Windows
  * PowerShell is out of scope. True isolation needs a container.
- * referencia: .claude/knowledge-base/references/theocode-shell-guard/server-lib/shell-guard.ts
+ * reference: .claude/knowledge-base/references/theocode-shell-guard/server-lib/shell-guard.ts
  */
 
 /** Thrown / reported when a command matches the catastrophic deny-list. */
@@ -616,7 +616,7 @@ declare function withShellExitGuidance(tool: CustomTool): CustomTool;
 
 interface CreateListDirToolOptions {
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ today's literal (additive).
      *
      * It exists because, in Codex, the name is BORN in the tool definition and is the approval decision key —
      * three consumers (model, approval, telemetry) of a string decided in one place. Renaming
@@ -627,8 +627,8 @@ interface CreateListDirToolOptions {
     /** M76 — description exposed to the model. Omitted => today's literal (additive). */
     description?: string;
     /**
-     * M76 — opt-in "lista-em-qualquer-lugar": honra um `path` ABSOLUTO fora de `projectRoot`
-     * (paridade com `createReadFileTool`/`createSearchTextTool`, sandbox read-only do Codex).
+     * M76 — opt-in "list anywhere": honours an ABSOLUTE `path` outside `projectRoot`
+     * (parity with `createReadFileTool`/`createSearchTextTool`, Codex's read-only sandbox).
      *
      * The ANY-segment secret guard still applies, and is not separable: `isForbiddenPath`
      * only blocks the sensitive item when it is the FIRST segment, so a `/home/u/proj/.env/sub`
@@ -720,9 +720,9 @@ interface QuestionToolOptions {
     /**
      * Callback that presents the question to the user and resolves with the answer.
      *
-     * M76 — passou a ser OPCIONAL: o asker preferencial vem do contexto da run
+     * M76 — became OPTIONAL: the preferred asker comes from the run context
      * (`ctx.context.askUser`), because a value pinned here is the "baked into each factory" that the
-     * `CustomTool.handler` aponta como o problema que `ctx.context` existe para resolver. Este campo
+     * `CustomTool.handler` names as the problem `ctx.context` exists to solve. This field
      * remains as a fallback, for callers building the tool with a fixed asker (backward-compatible).
      */
     askUser?: (question: string, threadId?: string) => Promise<string>;
@@ -735,11 +735,11 @@ interface QuestionToolOptions {
     /** Maximum time to wait for user response in ms. Default: 300_000 (5 min). */
     timeoutMs?: number;
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ `"question"` (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ `"question"` (additive).
      *
      * The consumer needed this: Codex calls the tool `request_user_input`, and without the option it
      * had to rebuild the whole object by hand — the two-cast adapter T3.3
-     * eliminou.
+     * removed.
      */
     name?: string;
     /** M76 — description exposed to the model. Omitted => today's literal (additive). */
@@ -945,7 +945,7 @@ declare function createRunVitestTool(opts: CreateRunVitestToolOptions): CustomTo
 
 interface CreateSearchTextToolOptions {
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ today's literal (additive).
      *
      * It exists because, in Codex, the name is BORN in the tool definition and is the approval decision
      * key — three consumers (model, approval, telemetry) of a string decided in one place. Renaming
@@ -985,7 +985,7 @@ declare function createSearchTextTool(opts: CreateSearchTextToolOptions): Custom
 
 interface CreateShellToolOptions {
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ today's literal (additive).
      *
      * It exists because, in Codex, the name is BORN in the tool definition and is the approval decision
      * key — three consumers (model, approval, telemetry) of a string decided in one place. Renaming

package/dist/index.d.ts

@@ -130,7 +130,7 @@ declare function createCurrentTimeTool(opts?: CreateCurrentTimeToolOptions): Cus
 
 interface CreateEditFileToolOptions {
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ today's literal (additive).
      *
      * It exists because, in Codex, the name is BORN in the tool definition and is the approval decision
      * key — three consumers (model, approval, telemetry) of a string decided in one place. Renaming
@@ -226,15 +226,15 @@ interface CreateGitStatusToolOptions {
     maxStdoutBytes?: number;
     /**
      * Injected execution backend (`@theokit/sdk/sandbox`) — when present, `git status` runs via
-     * `SandboxBackend.execute`; omitido ⇒ o `git` local (inalterado).
+     * `SandboxBackend.execute`; omitted ⇒ the local `git` (unchanged).
      *
      * Symmetry with `createGitDiffTool`, flagged by the M76 review: without it `git_diff` would run
      * confined and `git_status` not, in the same session — and the asymmetry would be invisible until someone
-     * perceber que uma das duas escapa do sandbox.
+     * notice that one of the two escapes the sandbox.
      */
     sandbox?: SandboxProvider;
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ `"git_status"` (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ `"git_status"` (additive).
      *
      * The name is a contract: the approval key, what the model sees and what telemetry records.
      */
@@ -490,7 +490,7 @@ declare function buildRepoMap(cwd: string, opts?: RepoMapOptions): string;
  * This is a heuristic GUARDRAIL, NOT a sandbox: it is bypassable by deep obfuscation
  * (base64/env-indirection) and is best-effort. POSIX `/bin/sh` only; Windows
  * PowerShell is out of scope. True isolation needs a container.
- * referencia: .claude/knowledge-base/references/theocode-shell-guard/server-lib/shell-guard.ts
+ * reference: .claude/knowledge-base/references/theocode-shell-guard/server-lib/shell-guard.ts
  */
 
 /** Thrown / reported when a command matches the catastrophic deny-list. */
@@ -616,7 +616,7 @@ declare function withShellExitGuidance(tool: CustomTool): CustomTool;
 
 interface CreateListDirToolOptions {
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ today's literal (additive).
      *
      * It exists because, in Codex, the name is BORN in the tool definition and is the approval decision key —
      * three consumers (model, approval, telemetry) of a string decided in one place. Renaming
@@ -627,8 +627,8 @@ interface CreateListDirToolOptions {
     /** M76 — description exposed to the model. Omitted => today's literal (additive). */
     description?: string;
     /**
-     * M76 — opt-in "lista-em-qualquer-lugar": honra um `path` ABSOLUTO fora de `projectRoot`
-     * (paridade com `createReadFileTool`/`createSearchTextTool`, sandbox read-only do Codex).
+     * M76 — opt-in "list anywhere": honours an ABSOLUTE `path` outside `projectRoot`
+     * (parity with `createReadFileTool`/`createSearchTextTool`, Codex's read-only sandbox).
      *
      * The ANY-segment secret guard still applies, and is not separable: `isForbiddenPath`
      * only blocks the sensitive item when it is the FIRST segment, so a `/home/u/proj/.env/sub`
@@ -720,9 +720,9 @@ interface QuestionToolOptions {
     /**
      * Callback that presents the question to the user and resolves with the answer.
      *
-     * M76 — passou a ser OPCIONAL: o asker preferencial vem do contexto da run
+     * M76 — became OPTIONAL: the preferred asker comes from the run context
      * (`ctx.context.askUser`), because a value pinned here is the "baked into each factory" that the
-     * `CustomTool.handler` aponta como o problema que `ctx.context` existe para resolver. Este campo
+     * `CustomTool.handler` names as the problem `ctx.context` exists to solve. This field
      * remains as a fallback, for callers building the tool with a fixed asker (backward-compatible).
      */
     askUser?: (question: string, threadId?: string) => Promise<string>;
@@ -735,11 +735,11 @@ interface QuestionToolOptions {
     /** Maximum time to wait for user response in ms. Default: 300_000 (5 min). */
     timeoutMs?: number;
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ `"question"` (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ `"question"` (additive).
      *
      * The consumer needed this: Codex calls the tool `request_user_input`, and without the option it
      * had to rebuild the whole object by hand — the two-cast adapter T3.3
-     * eliminou.
+     * removed.
      */
     name?: string;
     /** M76 — description exposed to the model. Omitted => today's literal (additive). */
@@ -945,7 +945,7 @@ declare function createRunVitestTool(opts: CreateRunVitestToolOptions): CustomTo
 
 interface CreateSearchTextToolOptions {
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ today's literal (additive).
      *
      * It exists because, in Codex, the name is BORN in the tool definition and is the approval decision
      * key — three consumers (model, approval, telemetry) of a string decided in one place. Renaming
@@ -985,7 +985,7 @@ declare function createSearchTextTool(opts: CreateSearchTextToolOptions): Custom
 
 interface CreateShellToolOptions {
     /**
-     * M76 — nome exposto ao modelo. Omitido ⇒ o literal de hoje (aditivo).
+     * M76 — the name exposed to the model. Omitted ⇒ today's literal (additive).
      *
      * It exists because, in Codex, the name is BORN in the tool definition and is the approval decision
      * key — three consumers (model, approval, telemetry) of a string decided in one place. Renaming

package/dist/index.js

@@ -791,12 +791,12 @@ function checkPathScope(path, projectRoot) {
     throw err;
   }
 }
-var SEGMENTOS_SENSIVEIS = /* @__PURE__ */ new Set([".env", ".git", "node_modules", ".theo"]);
-function ehProibidoEmQualquerProfundidade(path) {
+var SENSITIVE_SEGMENTS = /* @__PURE__ */ new Set([".env", ".git", "node_modules", ".theo"]);
+function isForbiddenAtAnyDepth(path) {
   const segs = path.replace(/\\/g, "/").split("/").filter(Boolean);
   return segs.some((s) => {
     if (s === ".env.example") return false;
-    return SEGMENTOS_SENSIVEIS.has(s) || /^\.env\./.test(s);
+    return SENSITIVE_SEGMENTS.has(s) || /^\.env\./.test(s);
   });
 }
 
@@ -1584,7 +1584,7 @@ function createListDirTool(opts) {
     }),
     handler: async ({ path }, ctx) => {
       const relative3 = path === "" || path === "." ? "." : path;
-      const verdict = decidirEscopo(relative3, path, opts.allowAbsolute === true);
+      const verdict = decideScope(relative3, path, opts.allowAbsolute === true);
       if (verdict.error !== void 0) return verdict.error;
       if (verdict.absoluteRoot !== void 0) {
         return listViaLocalFs(verdict.absoluteRoot, ".", path, max);
@@ -1597,14 +1597,14 @@ function createListDirTool(opts) {
     }
   });
 }
-function decidirEscopo(relative3, original, allowAbsolute) {
+function decideScope(relative3, original, allowAbsolute) {
   const refuse = (error) => ({
     error: JSON.stringify({ ok: false, error, path: original })
   });
   if (relative3 !== "." && isForbiddenPath(relative3)) return refuse("forbidden_path");
   if (!isAbsolute(relative3)) return {};
   if (!allowAbsolute) return refuse("path_traversal");
-  if (ehProibidoEmQualquerProfundidade(relative3)) return refuse("forbidden_path");
+  if (isForbiddenAtAnyDepth(relative3)) return refuse("forbidden_path");
   return { absoluteRoot: relative3 };
 }
 async function listViaLocalFs(projectRoot, relative3, originalPath, max) {
@@ -1767,10 +1767,10 @@ function createPlanModeTool(options) {
 }
 
 // src/question.ts
-function askerDoContexto(context) {
+function askerFromContext(context) {
   if (typeof context !== "object" || context === null) return void 0;
-  const candidato = context.askUser;
-  return typeof candidato === "function" ? candidato : void 0;
+  const candidate = context.askUser;
+  return typeof candidate === "function" ? candidate : void 0;
 }
 function createQuestionTool(opts) {
   const timeoutMs = opts.timeoutMs ?? 3e5;
@@ -1785,7 +1785,7 @@ function createQuestionTool(opts) {
       required: ["question"]
     },
     handler: async (input, ctx) => {
-      const askUser = askerDoContexto(ctx?.context) ?? opts.askUser;
+      const askUser = askerFromContext(ctx?.context) ?? opts.askUser;
       if (askUser === void 0) {
         return JSON.stringify({
           ok: false,
@@ -1822,7 +1822,7 @@ function forbiddenReadError(path, allowAbsolute) {
   if (isForbiddenPath(path)) {
     return JSON.stringify({ ok: false, error: "forbidden_path", path });
   }
-  if (allowAbsolute && isAbsolute(path) && ehProibidoEmQualquerProfundidade(path)) {
+  if (allowAbsolute && isAbsolute(path) && isForbiddenAtAnyDepth(path)) {
     return JSON.stringify({ ok: false, error: "forbidden_path", path });
   }
   return null;