@theokit/sdk-tools 0.16.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 0.18.0
+
+### Minor Changes
+
+- `createReadFileTool` gains three ADDITIVE, opt-in Codex-grade capabilities (all default OFF, so existing
+  consumers are byte-identical): `lineNumbers` (render a `cat -n` `<n>\t<line>` view so the model can cite/
+  edit by line), `offset`/`limit` input params (page through a large file), and `allowAbsolute` (honor an
+  absolute path outside `projectRoot` — the Codex read-only "reads-anywhere" sandbox). Security: with
+  `allowAbsolute`, the secret guard now blocks `.env`/`.git`/`node_modules`/`.theo` at ANY path depth (not
+  just the project-relative first segment), closing an absolute-path exfiltration hole. Opt-in only.
+
+## 0.17.0
+
+### Minor Changes
+
+- c98c40a: Add `createUpdatePlanTool` — a Codex-faithful `update_plan` built-in. The model posts a DECLARATIVE plan
+  (an ordered list of steps, each `pending | in_progress | completed`) and refreshes it as work proceeds.
+  Surface-agnostic by design: returns STRUCTURED `{ ok, explanation, steps, warning? }` so each surface
+  renders the checklist itself (no hard-coded glyphs). Follows Codex's "exactly one step in_progress"
+  invariant as a non-fatal `warning` (never rejects), so the agent self-corrects on the next update.
+  Distinct from the imperative `createTodolistTool` (add/complete by id) and `createPlanModeTool` (mode
+  toggle) — this is the declarative full-plan post.
+
 ## 0.16.0
 
 ### Minor Changes

package/dist/index.cjs

@@ -1579,23 +1579,53 @@ function createQuestionTool(opts) {
 }
 var MAX_FILE_SIZE = 5 * 1024 * 1024;
 var BINARY_PROBE_BYTES = 8 * 1024;
+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 SENSITIVE_SEGMENTS.has(s) || /^\.env\./.test(s);
+  });
+}
+function forbiddenReadError(path$1, allowAbsolute) {
+  if (isForbiddenPath(path$1)) {
+    return JSON.stringify({ ok: false, error: "forbidden_path", path: path$1 });
+  }
+  if (allowAbsolute && path.isAbsolute(path$1) && isForbiddenAtAnyDepth(path$1)) {
+    return JSON.stringify({ ok: false, error: "forbidden_path", path: path$1 });
+  }
+  return null;
+}
+function renderView(content, opts) {
+  const paginated = opts.offset !== void 0 || opts.limit !== void 0;
+  if (!opts.lineNumbers && !paginated) return content;
+  const lines = content.split("\n");
+  const start = Math.max(1, opts.offset ?? 1);
+  const end = opts.limit !== void 0 ? Math.min(lines.length, start - 1 + opts.limit) : lines.length;
+  const slice = lines.slice(start - 1, end);
+  return opts.lineNumbers ? slice.map((l, i) => `${start + i}	${l}`).join("\n") : slice.join("\n");
+}
 function createReadFileTool(opts) {
-  const { projectRoot, readTracker, filesystem: filesystem$1 } = opts;
+  const { projectRoot, readTracker, filesystem: filesystem$1, lineNumbers, allowAbsolute } = opts;
+  const numbered = lineNumbers === true ? " Returns a cat -n numbered view (`<n>\\t<line>`)." : "";
+  const abs = allowAbsolute === true ? " Absolute paths outside the project are honored." : "";
   return sdk.Tool.create({
     name: "read_file",
-    description: "Read a project-relative text file as UTF-8. ALWAYS read a file before you edit it (edit_file) or overwrite it (write_file), so your old_string / new content matches the real bytes exactly. Returns the WHOLE file (there is no offset or line-range parameter); to locate a symbol inside a large file, use search_text instead of re-reading. Refuses paths that escape the project root, sensitive files (.env, .git/, node_modules/, .theo/, lock files), and binary files (null byte in the first 8 KB); caps at 5 MB. Returns { ok, content, size } or { ok: false, error }.",
+    description: "Read a text file as UTF-8. ALWAYS read a file before you edit it (edit_file) or overwrite it (write_file), so your old_string / new content matches the real bytes exactly." + numbered + abs + " By default returns the whole file; use the optional offset (1-based first line) + limit to page through a large file, or search_text to locate a symbol. Refuses sensitive files (.env, .git/, node_modules/, .theo/, lock files) and binary files (null byte in the first 8 KB); caps at 5 MB. Returns { ok, content, size } or { ok: false, error }.",
     inputSchema: zod.z.object({
-      path: zod.z.string().min(1).describe("Project-relative file path.")
+      path: zod.z.string().min(1).describe("File path (project-relative; absolute when allowed)."),
+      offset: zod.z.number().int().min(1).optional().describe("1-based first line to read (default 1)."),
+      limit: zod.z.number().int().min(1).optional().describe("Max number of lines to read (default: all).")
     }),
-    handler: async ({ path }, ctx) => {
-      if (isForbiddenPath(path)) {
-        return JSON.stringify({ ok: false, error: "forbidden_path", path });
-      }
+    handler: async ({ path, offset, limit }, ctx) => {
+      const forbidden = forbiddenReadError(path, allowAbsolute === true);
+      if (forbidden !== null) return forbidden;
+      const view = { lineNumbers, offset, limit };
       if (filesystem$1) {
         const backend = await filesystem.resolveFilesystem(filesystem$1, ctx ?? {});
-        return readViaBackend(backend, path, (mtimeMs) => readTracker?.record(path, mtimeMs));
+        return readViaBackend(backend, path, view, (mtimeMs) => readTracker?.record(path, mtimeMs));
       }
-      const boundary = resolveBoundary(path, projectRoot);
+      const boundary = resolveBoundary(path, projectRoot, allowAbsolute === true);
       if ("error" in boundary) return boundary.error;
       const opened = await openHandleSafe(boundary.absolutePath, path);
       if ("error" in opened) return opened.error;
@@ -1603,6 +1633,7 @@ function createReadFileTool(opts) {
         return await readContent(
           opened.handle,
           path,
+          view,
           (mtimeMs) => readTracker?.record(path, mtimeMs)
         );
       } finally {
@@ -1611,7 +1642,7 @@ function createReadFileTool(opts) {
     }
   });
 }
-async function readViaBackend(backend, path, onRead) {
+async function readViaBackend(backend, path, view, onRead) {
   try {
     const stat2 = await backend.stat(path);
     if (stat2.size > MAX_FILE_SIZE) {
@@ -1623,12 +1654,12 @@ async function readViaBackend(backend, path, onRead) {
         limit: MAX_FILE_SIZE
       });
     }
-    const content = await backend.readFile(path);
-    if (content.includes("\0")) {
+    const raw = await backend.readFile(path);
+    if (raw.includes("\0")) {
       return JSON.stringify({ ok: false, error: "binary_file", path, size: stat2.size });
     }
     onRead?.(stat2.mtimeMs);
-    return JSON.stringify({ ok: true, content, size: stat2.size });
+    return JSON.stringify({ ok: true, content: renderView(raw, view), size: stat2.size });
   } catch (err) {
     if (err instanceof filesystem.FileNotFoundError) {
       return JSON.stringify({ ok: false, error: "not_found", path });
@@ -1639,14 +1670,17 @@ async function readViaBackend(backend, path, onRead) {
     throw err;
   }
 }
-function resolveBoundary(path, projectRoot) {
+function resolveBoundary(path$1, projectRoot, allowAbsolute) {
+  if (allowAbsolute && path.isAbsolute(path$1)) {
+    return { absolutePath: path$1 };
+  }
   try {
-    const absolutePath = safePathJoin(projectRoot, path);
+    const absolutePath = safePathJoin(projectRoot, path$1);
     assertNoSymlinkEscape(absolutePath, projectRoot);
     return { absolutePath };
   } catch (err) {
     if (err instanceof PathTraversalError || err instanceof ForbiddenPathError) {
-      return { error: JSON.stringify({ ok: false, error: "path_traversal", path }) };
+      return { error: JSON.stringify({ ok: false, error: "path_traversal", path: path$1 }) };
     }
     throw err;
   }
@@ -1663,7 +1697,7 @@ async function openHandleSafe(absolutePath, path) {
     throw err;
   }
 }
-async function readContent(handle, path, onRead) {
+async function readContent(handle, path, view, onRead) {
   const stat2 = await handle.stat();
   if (stat2.size > MAX_FILE_SIZE) {
     return JSON.stringify({
@@ -1677,9 +1711,9 @@ async function readContent(handle, path, onRead) {
   if (await isBinaryProbe(handle, Number(stat2.size))) {
     return JSON.stringify({ ok: false, error: "binary_file", path, size: stat2.size });
   }
-  const content = await handle.readFile({ encoding: "utf-8" });
+  const raw = await handle.readFile({ encoding: "utf-8" });
   onRead?.(stat2.mtimeMs);
-  return JSON.stringify({ ok: true, content, size: stat2.size });
+  return JSON.stringify({ ok: true, content: renderView(raw, view), size: stat2.size });
 }
 async function isBinaryProbe(handle, size) {
   const probeLen = Math.min(BINARY_PROBE_BYTES, size);
@@ -2297,6 +2331,27 @@ function truncateOutput(output, opts) {
     overflowPath
   };
 }
+var STATUS = ["pending", "in_progress", "completed"];
+var planStepSchema = zod.z.object({
+  step: zod.z.string().min(1).max(100).describe("A short step, \u2264 ~7 words."),
+  status: zod.z.enum(STATUS)
+});
+function createUpdatePlanTool() {
+  return sdk.Tool.create({
+    name: "update_plan",
+    description: "Post or refresh a short plan so the user sees your progress on a multi-step task. Pass an ordered `plan` of steps, each with a status (pending | in_progress | completed); keep exactly one step in_progress at a time and mark steps completed as you finish. Returns { ok, steps, warning? } as a JSON string \u2014 the surface renders the checklist. A `warning` is returned (not an error) if the one-in_progress invariant is violated, so you can self-correct on the next update.",
+    inputSchema: zod.z.object({
+      explanation: zod.z.string().max(200).optional().describe("One line on what changed / why (optional)."),
+      plan: zod.z.array(planStepSchema).min(1).describe("The ordered steps.")
+    }),
+    handler: ({ explanation, plan }) => {
+      const inProgress = plan.filter((s) => s.status === "in_progress").length;
+      const allDone = plan.every((s) => s.status === "completed");
+      const warning = !allDone && inProgress !== 1 ? `keep exactly one step in_progress until all are completed \u2014 found ${inProgress}` : void 0;
+      return JSON.stringify({ ok: true, explanation: explanation ?? null, steps: plan, warning });
+    }
+  });
+}
 var DEFAULT_TIMEOUT_MS4 = 3e4;
 var MAX_BODY_BYTES = 1 * 1024 * 1024;
 function createWebFetchTool(opts) {
@@ -2627,6 +2682,7 @@ exports.createSearchTextTool = createSearchTextTool;
 exports.createSessionArtifactStore = createSessionArtifactStore;
 exports.createShellTool = createShellTool;
 exports.createTodolistTool = createTodolistTool;
+exports.createUpdatePlanTool = createUpdatePlanTool;
 exports.createWebFetchTool = createWebFetchTool;
 exports.createWebSearchTool = createWebSearchTool;
 exports.createWriteFileTool = createWriteFileTool;