@theokit/sdk-tools 0.15.1 → 0.17.0

package/dist/index.d.cts

@@ -75,6 +75,27 @@ interface SessionArtifactStore {
  */
 declare function createSessionArtifactStore(options: SessionArtifactStoreOptions): SessionArtifactStore;
 
+/**
+ * `current_time` — built-in tool for coding agents.
+ *
+ * Returns the current date-time. Codex-faithful at the core (its `clock`/`curr_time` tool returns UTC
+ * as `YYYY-MM-DD HH:MM:SS UTC`); this built-in keeps that default and adds an optional IANA `timezone`
+ * (additive superset — omitted ⇒ UTC, exactly Codex's behavior) plus an unambiguous `iso` instant.
+ *
+ * The clock is injectable so the tool is deterministic under test (testing.md §6: never read the real
+ * wall clock in a unit test).
+ *
+ * Result shape (always a JSON string):
+ *   - `{ ok: true, current_time: "YYYY-MM-DD HH:MM:SS <tz>", iso: string, timezone: string }`
+ *   - `{ ok: false, error: "invalid_timezone", timezone }`
+ */
+
+interface CreateCurrentTimeToolOptions {
+    /** Injectable clock — defaults to `() => new Date()`. Pass a fixed clock for deterministic tests. */
+    clock?: () => Date;
+}
+declare function createCurrentTimeTool(opts?: CreateCurrentTimeToolOptions): CustomTool;
+
 /**
  * `edit_file` — built-in tool for coding agents.
  *
@@ -889,6 +910,22 @@ interface TruncationResult {
 }
 declare function truncateOutput(output: string, opts?: TruncationOptions): TruncationResult;
 
+/**
+ * `update_plan` — built-in tool for coding agents.
+ *
+ * Codex-faithful: the model posts a DECLARATIVE plan — an ordered list of short steps, each
+ * `pending | in_progress | completed` — and refreshes it as work proceeds. Codex's invariant is
+ * "exactly one step in_progress until everything is done"; this tool WARNS (never rejects) when that
+ * doesn't hold, so the agent self-corrects on the next update rather than failing the turn.
+ *
+ * Surface-agnostic by design (M17 DX): the result is STRUCTURED (`{ ok, steps, warning? }`) — each
+ * surface (terminal TUI, desktop, web) renders the checklist however it likes, rather than the package
+ * hard-coding glyphs. Result shape (always a JSON string):
+ *   - `{ ok: true, explanation: string | null, steps: PlanStep[], warning?: string }`
+ */
+
+declare function createUpdatePlanTool(): CustomTool;
+
 /**
  * `web_fetch` — built-in tool for coding agents.
  *
@@ -1052,4 +1089,4 @@ interface CreateWriteFileToolOptions {
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, 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, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateCurrentTimeToolOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, 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, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };

package/dist/index.d.ts

@@ -75,6 +75,27 @@ interface SessionArtifactStore {
  */
 declare function createSessionArtifactStore(options: SessionArtifactStoreOptions): SessionArtifactStore;
 
+/**
+ * `current_time` — built-in tool for coding agents.
+ *
+ * Returns the current date-time. Codex-faithful at the core (its `clock`/`curr_time` tool returns UTC
+ * as `YYYY-MM-DD HH:MM:SS UTC`); this built-in keeps that default and adds an optional IANA `timezone`
+ * (additive superset — omitted ⇒ UTC, exactly Codex's behavior) plus an unambiguous `iso` instant.
+ *
+ * The clock is injectable so the tool is deterministic under test (testing.md §6: never read the real
+ * wall clock in a unit test).
+ *
+ * Result shape (always a JSON string):
+ *   - `{ ok: true, current_time: "YYYY-MM-DD HH:MM:SS <tz>", iso: string, timezone: string }`
+ *   - `{ ok: false, error: "invalid_timezone", timezone }`
+ */
+
+interface CreateCurrentTimeToolOptions {
+    /** Injectable clock — defaults to `() => new Date()`. Pass a fixed clock for deterministic tests. */
+    clock?: () => Date;
+}
+declare function createCurrentTimeTool(opts?: CreateCurrentTimeToolOptions): CustomTool;
+
 /**
  * `edit_file` — built-in tool for coding agents.
  *
@@ -889,6 +910,22 @@ interface TruncationResult {
 }
 declare function truncateOutput(output: string, opts?: TruncationOptions): TruncationResult;
 
+/**
+ * `update_plan` — built-in tool for coding agents.
+ *
+ * Codex-faithful: the model posts a DECLARATIVE plan — an ordered list of short steps, each
+ * `pending | in_progress | completed` — and refreshes it as work proceeds. Codex's invariant is
+ * "exactly one step in_progress until everything is done"; this tool WARNS (never rejects) when that
+ * doesn't hold, so the agent self-corrects on the next update rather than failing the turn.
+ *
+ * Surface-agnostic by design (M17 DX): the result is STRUCTURED (`{ ok, steps, warning? }`) — each
+ * surface (terminal TUI, desktop, web) renders the checklist however it likes, rather than the package
+ * hard-coding glyphs. Result shape (always a JSON string):
+ *   - `{ ok: true, explanation: string | null, steps: PlanStep[], warning?: string }`
+ */
+
+declare function createUpdatePlanTool(): CustomTool;
+
 /**
  * `web_fetch` — built-in tool for coding agents.
  *
@@ -1052,4 +1089,4 @@ interface CreateWriteFileToolOptions {
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, 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, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, type CommandPolicy, ContextMatchError, type ContextMatchReason, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateCurrentTimeToolOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, type CreateInteractiveShellToolOptions, 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, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withName, withShellExitGuidance, withToolResultGuidance };

package/dist/index.js

@@ -265,6 +265,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 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: z.object({
+      timezone: 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 {
@@ -2255,6 +2295,27 @@ function truncateOutput(output, opts) {
     overflowPath
   };
 }
+var STATUS = ["pending", "in_progress", "completed"];
+var planStepSchema = z.object({
+  step: z.string().min(1).max(100).describe("A short step, \u2264 ~7 words."),
+  status: z.enum(STATUS)
+});
+function createUpdatePlanTool() {
+  return 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: z.object({
+      explanation: z.string().max(200).optional().describe("One line on what changed / why (optional)."),
+      plan: 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) {
@@ -2557,6 +2618,6 @@ async function isBinaryFile(absolutePath) {
   }
 }
 
-export { CatastrophicCommandError, ContextMatchError, DEFAULT_TOOL_GUIDANCE, ReadTracker, ReasoningTools, RedirectBlockedError, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, replaceUnique, 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, createCurrentTimeTool, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createInteractiveShellTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createUpdatePlanTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, createWriteStdinTool, 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