@theokit/sdk-tools 0.15.1 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # 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
+
+- ef00db3: Add `createCurrentTimeTool` — a built-in `current_time` tool. Codex-faithful at the core (Codex's
+  `clock.curr_time` returns UTC as `YYYY-MM-DD HH:MM:SS UTC`); this keeps that as the default and adds an
+  optional IANA `timezone` (additive superset — omitted ⇒ UTC) plus an unambiguous `iso` instant. Returns
+  `{ ok, current_time, iso, timezone }` or `{ ok: false, error: 'invalid_timezone' }`. The clock is
+  injectable (`{ clock }`) so the tool is deterministic under test.
+
 ## 0.15.1
 
 ### Patch Changes

package/dist/index.cjs

@@ -267,6 +267,46 @@ function createSessionArtifactStore(options) {
   }
   return { write, read, has, list, path };
 }
+function formatInTimezone(now, tz) {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone: tz,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  }).formatToParts(now);
+  const p = {};
+  for (const { type, value } of parts) p[type] = value;
+  const hour = p.hour === "24" ? "00" : p.hour;
+  return `${p.year}-${p.month}-${p.day} ${hour}:${p.minute}:${p.second} ${tz}`;
+}
+function createCurrentTimeTool(opts = {}) {
+  const clock = opts.clock ?? (() => /* @__PURE__ */ new Date());
+  return sdk.Tool.create({
+    name: "current_time",
+    description: "Get the current date and time. Returns { current_time, iso, timezone } as a JSON string, where current_time is 'YYYY-MM-DD HH:MM:SS <timezone>' and iso is the ISO-8601 instant. Pass an optional IANA timezone (e.g. 'America/Sao_Paulo', 'Europe/Lisbon'); defaults to UTC. Never state the date or time from memory \u2014 always call this. Returns { ok: false, error: 'invalid_timezone' } for an unknown timezone.",
+    inputSchema: zod.z.object({
+      timezone: zod.z.string().optional().describe("IANA timezone, e.g. 'America/Sao_Paulo' or 'Europe/Lisbon'. Defaults to UTC.")
+    }),
+    handler: ({ timezone }) => {
+      const tz = timezone ?? "UTC";
+      const now = clock();
+      try {
+        return JSON.stringify({
+          ok: true,
+          current_time: formatInTimezone(now, tz),
+          iso: now.toISOString(),
+          timezone: tz
+        });
+      } catch {
+        return JSON.stringify({ ok: false, error: "invalid_timezone", timezone: tz });
+      }
+    }
+  });
+}
 
 // src/internal/context-match.ts
 var ContextMatchError = class extends Error {
@@ -2257,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) {
@@ -2572,6 +2633,7 @@ exports.catastrophicShellReason = catastrophicShellReason;
 exports.commandDenialReason = commandDenialReason;
 exports.createApplyPatchTool = createApplyPatchTool;
 exports.createBraveWebSearchAdapter = createBraveWebSearchAdapter;
+exports.createCurrentTimeTool = createCurrentTimeTool;
 exports.createEditFileTool = createEditFileTool;
 exports.createGenericHttpSearchAdapter = createGenericHttpSearchAdapter;
 exports.createGitDiffTool = createGitDiffTool;
@@ -2586,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;