@theokit/sdk-tools 0.9.1 → 0.11.0

package/dist/index.d.cts

@@ -576,6 +576,29 @@ interface CreateReadFileToolOptions {
 }
 declare function createReadFileTool(opts: CreateReadFileToolOptions): CustomTool;
 
+/**
+ * SE37 — the public reasoning toolkit: `ReasoningTools.create()` returns a
+ * `think` + `analyze` scratchpad (no-side-effect tools that echo the model's
+ * structured reasoning back as an observation, so the ReAct loop feeds it
+ * forward). Mirrors Anthropic's "think" tool + Agno's `ReasoningTools`.
+ *
+ * Lives in `@theokit/sdk-tools` (not core) so the full toolkit stays out of the
+ * core bundle. The `reasoning: true` agent flag auto-attaches an equivalent
+ * lean `think` from core; add these explicitly (`tools: [...ReasoningTools.create()]`)
+ * when you want the model to reason with a scratchpad on any model.
+ *
+ * @public
+ */
+
+/** Reasoning scratchpad tools. `ReasoningTools.create()` → `[think, analyze]`. */
+declare class ReasoningTools {
+    private constructor();
+    /** Build the tools. Pass `{ analyze: false }` for `think` only. */
+    static create(opts?: {
+        analyze?: boolean;
+    }): CustomTool[];
+}
+
 /**
  * `run_vitest` — built-in tool for coding agents.
  *
@@ -685,6 +708,11 @@ declare function createShellTool(opts: CreateShellToolOptions): CustomTool;
  *   - remove(id)         → remove an item
  *   - list()             → show all items with status
  *   - clear_completed()  → remove all done items
+ *
+ * #119 — state is keyed by `ctx.threadId` (the run's session identity, injected by the
+ * SDK from `Agent.getOrCreate(sessionId, …)`). One tool object served to many sessions
+ * from a single process keeps each session's list isolated. When no `threadId` is present
+ * (single-session CLI usage) every call shares one default session — behavior unchanged.
  */
 interface TodoItem {
     id: string;
@@ -697,9 +725,15 @@ interface TodolistTool {
     name: string;
     description: string;
     inputSchema: unknown;
-    handler: (input: TodoInput) => string;
-    /** Expose items for testing. */
-    getItems: () => TodoItem[];
+    /**
+     * #119 — the optional 2nd `ctx` carries the run's `threadId`; state is scoped to it.
+     * Single-argument callers (CLI / tests) share one default session.
+     */
+    handler: (input: TodoInput, ctx?: {
+        threadId?: string;
+    }) => string;
+    /** Expose a session's items for testing (defaults to the no-threadId session). */
+    getItems: (threadId?: string) => TodoItem[];
 }
 type TodoInput = {
     action: "add";
@@ -930,4 +964,4 @@ interface CreateWriteFileToolOptions {
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, 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, 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, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, type CommandPolicy, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, 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, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };

package/dist/index.d.ts

@@ -576,6 +576,29 @@ interface CreateReadFileToolOptions {
 }
 declare function createReadFileTool(opts: CreateReadFileToolOptions): CustomTool;
 
+/**
+ * SE37 — the public reasoning toolkit: `ReasoningTools.create()` returns a
+ * `think` + `analyze` scratchpad (no-side-effect tools that echo the model's
+ * structured reasoning back as an observation, so the ReAct loop feeds it
+ * forward). Mirrors Anthropic's "think" tool + Agno's `ReasoningTools`.
+ *
+ * Lives in `@theokit/sdk-tools` (not core) so the full toolkit stays out of the
+ * core bundle. The `reasoning: true` agent flag auto-attaches an equivalent
+ * lean `think` from core; add these explicitly (`tools: [...ReasoningTools.create()]`)
+ * when you want the model to reason with a scratchpad on any model.
+ *
+ * @public
+ */
+
+/** Reasoning scratchpad tools. `ReasoningTools.create()` → `[think, analyze]`. */
+declare class ReasoningTools {
+    private constructor();
+    /** Build the tools. Pass `{ analyze: false }` for `think` only. */
+    static create(opts?: {
+        analyze?: boolean;
+    }): CustomTool[];
+}
+
 /**
  * `run_vitest` — built-in tool for coding agents.
  *
@@ -685,6 +708,11 @@ declare function createShellTool(opts: CreateShellToolOptions): CustomTool;
  *   - remove(id)         → remove an item
  *   - list()             → show all items with status
  *   - clear_completed()  → remove all done items
+ *
+ * #119 — state is keyed by `ctx.threadId` (the run's session identity, injected by the
+ * SDK from `Agent.getOrCreate(sessionId, …)`). One tool object served to many sessions
+ * from a single process keeps each session's list isolated. When no `threadId` is present
+ * (single-session CLI usage) every call shares one default session — behavior unchanged.
  */
 interface TodoItem {
     id: string;
@@ -697,9 +725,15 @@ interface TodolistTool {
     name: string;
     description: string;
     inputSchema: unknown;
-    handler: (input: TodoInput) => string;
-    /** Expose items for testing. */
-    getItems: () => TodoItem[];
+    /**
+     * #119 — the optional 2nd `ctx` carries the run's `threadId`; state is scoped to it.
+     * Single-argument callers (CLI / tests) share one default session.
+     */
+    handler: (input: TodoInput, ctx?: {
+        threadId?: string;
+    }) => string;
+    /** Expose a session's items for testing (defaults to the no-threadId session). */
+    getItems: (threadId?: string) => TodoItem[];
 }
 type TodoInput = {
     action: "add";
@@ -930,4 +964,4 @@ interface CreateWriteFileToolOptions {
 }
 declare function createWriteFileTool(opts: CreateWriteFileToolOptions): CustomTool;
 
-export { CatastrophicCommandError, type CommandPolicy, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, 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, 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, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, type CommandPolicy, type CreateApplyPatchToolOptions, type CreateBraveWebSearchAdapterOptions, type CreateEditFileToolOptions, type CreateGenericHttpSearchAdapterOptions, type CreateGitDiffToolOptions, type CreateGlobToolOptions, 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, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };

package/dist/index.js

@@ -1433,6 +1433,37 @@ function evaluateReadBeforeWrite(tracker, path, currentMtimeMs) {
   if (recorded !== currentMtimeMs) return "stale";
   return "ok";
 }
+var ReasoningTools = class {
+  constructor() {
+  }
+  /** Build the tools. Pass `{ analyze: false }` for `think` only. */
+  static create(opts) {
+    const think = Tool.create({
+      name: "think",
+      description: "Use this as a scratchpad to think step by step BEFORE answering or acting. Write out your reasoning for one step. Nothing else happens \u2014 it is only your private reasoning space. Call it as many times as you need before the final answer.",
+      inputSchema: z.object({
+        thought: z.string().min(1, "think: `thought` must be a non-empty string.")
+      }),
+      handler: ({ thought }) => thought
+    });
+    if (opts?.analyze === false) return [think];
+    const analyze = Tool.create({
+      name: "analyze",
+      description: "Analyze the result of a previous step or tool call. State what you looked at, your analysis, and whether to `continue` reasoning, `validate` (double-check) your work, or give the `final_answer`. Use this to catch your own mistakes before answering.",
+      inputSchema: z.object({
+        title: z.string().optional(),
+        result: z.string().min(1, "analyze: `result` must describe what you are analyzing."),
+        analysis: z.string().min(1, "analyze: `analysis` must contain your reasoning."),
+        next_action: z.enum(["continue", "validate", "final_answer"])
+      }),
+      handler: ({ title, result, analysis, next_action }) => `${title ? `# ${title}
+` : ""}Result: ${result}
+Analysis: ${analysis}
+Next: ${next_action}`
+    });
+    return [think, analyze];
+  }
+};
 var DEFAULT_TIMEOUT_MS2 = 12e4;
 var DEFAULT_MAX_STDOUT_BYTES2 = 10 * 1024 * 1024;
 function createRunVitestTool(opts) {
@@ -1770,7 +1801,7 @@ function requireId(input) {
   if (!("id" in input) || !input.id) return null;
   return input.id;
 }
-function createTodolistTool() {
+function makeSessionOps() {
   const items = [];
   let nextId = 1;
   function genId() {
@@ -1839,6 +1870,26 @@ ${done}/${items.length} done | ${inProg} in progress | ${pending} pending`);
     list: () => listResult({}),
     clear_completed: handleClearCompleted
   };
+  return {
+    handle: (input) => {
+      const action = actions[input.action];
+      if (!action) return fail({ error: "invalid_action" });
+      return action(input);
+    },
+    getItems: () => [...items]
+  };
+}
+function createTodolistTool() {
+  const sessions = /* @__PURE__ */ new Map();
+  function ops(threadId) {
+    const key = threadId ?? "__default__";
+    let session = sessions.get(key);
+    if (session === void 0) {
+      session = makeSessionOps();
+      sessions.set(key, session);
+    }
+    return session;
+  }
   return {
     name: "todolist",
     description: "Create and maintain a structured task list for the current session \u2014 tracks progress and keeps a multi-step plan visible across turns. Use it proactively when the work has 3+ steps or the user gave multiple tasks; skip it for a single trivial step. Keep exactly ONE item 'in_progress' at a time, and mark 'complete' only after the work is actually done. Actions: 'add' (create with title), 'in_progress' (mark started by id), 'complete' (mark done by id), 'remove' (delete by id), 'list' (show all), 'clear_completed' (remove done items). Returns { ok, items, items_summary } (items = structured array; items_summary = formatted text).",
@@ -1861,12 +1912,8 @@ ${done}/${items.length} done | ${inProg} in progress | ${pending} pending`);
       },
       required: ["action"]
     },
-    handler: (input) => {
-      const action = actions[input.action];
-      if (!action) return fail({ error: "invalid_action" });
-      return action(input);
-    },
-    getItems: () => [...items]
+    handler: (input, ctx) => ops(ctx?.threadId).handle(input),
+    getItems: (threadId) => ops(threadId).getItems()
   };
 }
 function truncateOutput(output, opts) {
@@ -2192,6 +2239,6 @@ async function isBinaryFile(absolutePath) {
   }
 }
 
-export { CatastrophicCommandError, DEFAULT_TOOL_GUIDANCE, ReadTracker, RedirectBlockedError, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };
+export { CatastrophicCommandError, DEFAULT_TOOL_GUIDANCE, ReadTracker, ReasoningTools, RedirectBlockedError, SsrfBlockedError, buildEnvContext, buildRepoMap, catastrophicShellReason, commandDenialReason, createApplyPatchTool, createBraveWebSearchAdapter, createEditFileTool, createGenericHttpSearchAdapter, createGitDiffTool, createGlobTool, createListDirTool, createPlanModeTool, createQuestionTool, createReadFileTool, createRunVitestTool, createSearchTextTool, createSessionArtifactStore, createShellTool, createTodolistTool, createWebFetchTool, createWebSearchTool, createWriteFileTool, denyCatastrophicCommands, formatCode, formatDiff, formatError, formatFileList, injectGuidance, isBlockedIp, isCommandAllowed, renderToolList, resolveAndScreen, screenedFetch, todoItemsToPlanNodes, truncateOutput, withDefaultGuidance, withDescription, withShellExitGuidance, withToolResultGuidance };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map