@sema-ai/core 1.275.1

package/dist/tools/todo.js

@@ -0,0 +1,126 @@
+import { Type } from "typebox";
+/**
+ * design/102 (K-8 CC full-body) — TodoWrite parity (CONTEXT leg). A private, in-task plan the model rewrites to
+ * track multi-step work. State lives in this factory's closure — FRESH per task (each `assembleFullBodyTools` call
+ * makes its own) and torn down with the task; nothing durable, no deps, no egress. `effect:"idempotent"` because
+ * re-sending the whole list is repeat-safe. Distinct from `present_plan` (that SUSPENDS for human review); this is
+ * the model's own scratch. Returns a RAW {@link ToolSpec} pushed via `spec.tools` (prepare-task defines it) — NOT
+ * mounted default-on, so it stays INERT for non-full-body runs. (A later slice may project the list to the wire.)
+ */
+export function createTodoWriteTool() {
+    let todos = [];
+    return {
+        name: "TodoWrite", // CC tool name (design/102 §3.6)
+        // design/115 prompt wave: CC TodoWriteTool/prompt.ts verbatim — opening + When-to-Use / When-NOT / Task-States
+        // sections (the ~6KB examples block is deliberately dropped to keep the prompt lean). No CC-only mechanism is
+        // referenced, so this is the highest-value straight copy. One sema delta appended: the complete-list-replaces
+        // semantics (CC leaves it implicit; this line prevents half-list updates). Where CC's short DESCRIPTION says
+        // "at least one in_progress" but its PROMPT says "exactly ONE", the PROMPT wins (matches sema behavior).
+        description: "Use this tool to create and manage a structured task list for your current coding session. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.\n" +
+            "It also helps the user understand the progress of the task and overall progress of their requests.\n" +
+            "\n" +
+            "## When to Use This Tool\n" +
+            "Use this tool proactively in these scenarios:\n" +
+            "\n" +
+            "1. Complex multi-step tasks - When a task requires 3 or more distinct steps or actions\n" +
+            "2. Non-trivial and complex tasks - Tasks that require careful planning or multiple operations\n" +
+            "3. User explicitly requests todo list - When the user directly asks you to use the todo list\n" +
+            "4. User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)\n" +
+            "5. After receiving new instructions - Immediately capture user requirements as todos\n" +
+            "6. When you start working on a task - Mark it as in_progress BEFORE beginning work. Ideally you should only have one todo as in_progress at a time\n" +
+            "7. After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation\n" +
+            "\n" +
+            "## When NOT to Use This Tool\n" +
+            "\n" +
+            "Skip using this tool when:\n" +
+            "1. There is only a single, straightforward task\n" +
+            "2. The task is trivial and tracking it provides no organizational benefit\n" +
+            "3. The task can be completed in less than 3 trivial steps\n" +
+            "4. The task is purely conversational or informational\n" +
+            "\n" +
+            "NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.\n" +
+            "\n" +
+            "## Task States and Management\n" +
+            "\n" +
+            "1. **Task States**: Use these states to track progress:\n" +
+            "   - pending: Task not yet started\n" +
+            "   - in_progress: Currently working on (limit to ONE task at a time)\n" +
+            "   - completed: Task finished successfully\n" +
+            "\n" +
+            "   **IMPORTANT**: Task descriptions must have two forms:\n" +
+            '   - content: The imperative form describing what needs to be done (e.g., "Run tests", "Build the project")\n' +
+            '   - activeForm: The present continuous form shown during execution (e.g., "Running tests", "Building the project")\n' +
+            "\n" +
+            "2. **Task Management**:\n" +
+            "   - Update task status in real-time as you work\n" +
+            "   - Mark tasks complete IMMEDIATELY after finishing (don't batch completions)\n" +
+            "   - Exactly ONE task must be in_progress at any time (not less, not more)\n" +
+            "   - Complete current tasks before starting new ones\n" +
+            "   - Remove tasks that are no longer relevant from the list entirely\n" +
+            "\n" +
+            "3. **Task Completion Requirements**:\n" +
+            "   - ONLY mark a task as completed when you have FULLY accomplished it\n" +
+            "   - If you encounter errors, blockers, or cannot finish, keep the task as in_progress\n" +
+            "   - When blocked, create a new task describing what needs to be resolved\n" +
+            "   - Never mark a task as completed if:\n" +
+            "     - Tests are failing\n" +
+            "     - Implementation is partial\n" +
+            "     - You encountered unresolved errors\n" +
+            "     - You couldn't find necessary files or dependencies\n" +
+            "\n" +
+            "4. **Task Breakdown**:\n" +
+            "   - Create specific, actionable items\n" +
+            "   - Break complex tasks into smaller, manageable steps\n" +
+            "   - Use clear, descriptive task names\n" +
+            "   - Always provide both forms:\n" +
+            '     - content: "Fix authentication bug"\n' +
+            '     - activeForm: "Fixing authentication bug"\n' +
+            "\n" +
+            "When in doubt, use this tool. Being proactive with task management demonstrates attentiveness and ensures you complete all requirements successfully.\n" +
+            "\n" +
+            "Pass the COMPLETE todo list each call — it replaces the prior list.",
+        parameters: Type.Object({
+            todos: Type.Array(Type.Object({
+                content: Type.String({ description: "The task, in imperative form (e.g. \"Run the tests\")." }),
+                status: Type.Union([Type.Literal("pending"), Type.Literal("in_progress"), Type.Literal("completed")]),
+                // CC 2.1.187 parity (batch-D): present-continuous form shown while the item is in_progress (e.g.
+                // "Running the tests"). Optional for back-compat — a CC-trained model supplies it; older callers omit it.
+                activeForm: Type.Optional(Type.String({ description: "Present-continuous form shown while in progress (e.g. \"Running the tests\")." })),
+            })),
+        }),
+        effect: "idempotent",
+        execute: (args) => {
+            // 18-tool toolUseResult 尾批: capture the PRE-update list before reassigning, for the CC-shaped details.
+            // `activeForm` is REQUIRED and min(1) in CC's TodoItem (sema-shell TodoListSchema) but OPTIONAL in our
+            // input schema — fall back to `content` (also min-1) so the shell's checklist card never fails safeParse on
+            // a model that omitted activeForm.
+            const shape = (t) => ({
+                content: t.content,
+                status: t.status,
+                activeForm: t.activeForm && t.activeForm.length > 0 ? t.activeForm : t.content,
+            });
+            const oldTodos = todos.map(shape);
+            const written = args.todos;
+            // checklist #60 (CC TodoWriteTool.ts:69-70 parity): an all-completed write CLEARS the STORED
+            // list (`allDone = todos.every(_ => _.status === 'completed'); newTodos = allDone ? [] : todos`)
+            // — the next write's oldTodos starts from [], and nothing downstream can regurgitate finished
+            // items. CC's `every` on an empty array is true, so writing [] stores [] (same fixed point).
+            // The DETAILS still report the WRITTEN list (CC :96-99 returns `newTodos: todos`, not the
+            // cleared store) — the turn-attachments projection applies its own allDone clear on top.
+            const allDone = written.every((t) => t.status === "completed");
+            todos = allDone ? [] : written;
+            const newTodos = written.map(shape);
+            const open = written.filter((t) => t.status !== "completed").length;
+            // design/116 W3: CC's confirmation text verbatim (CC TodoWriteTool.ts:105 `base`) — the momentum sentence
+            // ("continue to use the todo list … proceed with the current tasks") is training-distribution load-bearing.
+            // Sema delta kept: the trailing (N total, M open) count, cheap observability the CC text lacks.
+            return {
+                content: `Todos have been modified successfully. Ensure that you continue to use the todo list to track your progress. ` +
+                    `Please proceed with the current tasks if applicable (${written.length} total, ${open} open)`,
+                // CC TodoWriteOutput {oldTodos, newTodos}; `type` = sema wire discriminator (stripped by shell z.object).
+                details: { type: "todo", oldTodos, newTodos },
+            };
+        },
+    };
+}
+//# sourceMappingURL=todo.js.map

package/dist/tools/todo.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo.js","sourceRoot":"","sources":["../../src/tools/todo.ts"],"names":[],"mappings":"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"}

package/dist/tools/web.d.ts

@@ -0,0 +1,59 @@
+import type { AgentTool } from "../internal/harness.js";
+import type { ToolSpec } from "../core/types.js";
+export interface WebFetchConfig {
+    /** If set, ONLY these hostnames may be fetched (exact host match) — and the allowlist is enforced on
+     *  **every redirect hop**, not just the initial URL (a redirect to a non-allowlisted host is refused
+     *  before the request is made). Omitted ⇒ no host restriction (the deployment's tool-policy gate is then
+     *  the only control — wire one for a multi-tenant deployment). */
+    allowHosts?: string[];
+    /** Injectable fetch (tests / a proxy). Defaults to the global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Max response bytes to read (default 2 MB). */
+    maxBytes?: number;
+    /** Wall-clock budget for the whole fetch (connect + redirects + body read), in ms. Default 30 000.
+     *  Without a local timeout, an unreachable host in a no-egress environment hangs until the OS-level
+     *  TCP timeout (60-120 s+) — an agent that retries then burns wall-clock on nothing. On expiry the
+     *  tool returns a routable error string, so the model can move on. */
+    timeoutMs?: number;
+    /** Optional sub-model extraction: given the (markdown) content + the caller's prompt, return a focused
+     *  answer. Its output is still derived from untrusted content, so it too is returned fenced. */
+    summarize?: (content: string, prompt: string, signal?: AbortSignal) => Promise<string>;
+    /** User-Agent header sent with every hop (批② P2-3). Default {@link DEFAULT_WEBFETCH_USER_AGENT};
+     *  a deployment can brand it (CC sends `Claude-User (<cc ua>; +https://support.anthropic.com/)`). */
+    userAgent?: string;
+}
+export declare function htmlToText(html: string): string;
+export declare function webFetchToolSpec(config?: WebFetchConfig): ToolSpec;
+/** Defined (harness) form of web_fetch — back-compat for direct execution / tests. For `spec.tools`, use the raw
+ *  {@link webFetchToolSpec} (prepare-task defineTool-wraps spec.tools entries). */
+export declare function createWebFetchTool(config?: WebFetchConfig): AgentTool;
+/**
+ * design/102 (K-8 CC full-body) — WebSearch (BRAIN / model-service leg). The search BACKEND is deployment-injected
+ * (provider-native search / a search API / an MCP-backed service); core ships NONE — the same boundary as
+ * {@link WebFetchConfig.summarize} and the model gateway. Absent backend ⇒ the tool is not assembled
+ * ({@link assembleFullBodyTools} only pushes it when `search` is wired). Results are UNTRUSTED external data —
+ * {@link delimitUntrusted}-fenced like web_fetch. 🔴 `effect:"read"`, NO `egress` field: a search is
+ * idempotent/retryable; declaring `egress:true` would throw at prep (`config.egress_requires_write_effect`) AND
+ * break resume-safety (a read reconciles as safe-to-retry, a write/egress one does not).
+ */
+export interface WebSearchConfig {
+    /**
+     * Deployment-injected search backend. core ships none. The optional `opts` carries the model's per-call
+     * `allowed_domains`/`blocked_domains` HINTS so a backend that supports native domain filtering (e.g. a
+     * `site:` query) can apply them up front. A backend MAY ignore `opts` — core re-enforces the domain
+     * constraint on the returned results as a floor (see `createWebSearchTool`), so honoring it is an
+     * optimization, not a correctness requirement. Back-compat: existing 2-arg backends keep working.
+     */
+    search: (query: string, signal?: AbortSignal, opts?: {
+        allowedDomains?: string[];
+        blockedDomains?: string[];
+    }) => Promise<Array<{
+        title: string;
+        url: string;
+        snippet: string;
+    }>>;
+    /** Max results returned to the model (default 10). */
+    maxResults?: number;
+}
+export declare function createWebSearchTool(config: WebSearchConfig): ToolSpec;
+//# sourceMappingURL=web.d.ts.map

package/dist/tools/web.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"web.d.ts","sourceRoot":"","sources":["../../src/tools/web.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAsBjD,MAAM,WAAW,cAAc;IAC7B;;;sEAGkE;IAClE,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IACtB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;0EAGsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;oGACgG;IAChG,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACvF;yGACqG;IACrG,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAmGD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAkE/C;AA4ID,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,cAAmB,GAAG,QAAQ,CAkMtE;AAED;mFACmF;AACnF,wBAAgB,kBAAkB,CAAC,MAAM,GAAE,cAAmB,GAAG,SAAS,CAEzE;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,MAAM,EAAE,CACN,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,WAAW,EACpB,IAAI,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,KAC5D,OAAO,CAAC,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IACrE,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AA0BD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,eAAe,GAAG,QAAQ,CA4ErE"}