@theokit/sdk-tools 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 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

@@ -2297,6 +2297,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 +2648,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;