@oharness/engine 0.1.0

package/dist/tools/builtin/task.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { defineTool } from "../define.js";
+import { toolError, toolText } from "../types.js";
+/**
+ * Spawns a subagent with its own context window and tool set.
+ *
+ * The description is built at registration time so the model sees the agent
+ * types that actually exist in this configuration, rather than a generic
+ * placeholder it has to guess against.
+ */
+export function createTaskTool(host) {
+    const types = host.listSubagentTypes();
+    const roster = types.length === 0
+        ? "(no subagent types are configured)"
+        : types.map((t) => `- ${t.name}: ${t.description}`).join("\n");
+    return defineTool({
+        name: "task",
+        description: [
+            "Delegate a self-contained piece of work to a subagent with its own context window.",
+            "The subagent cannot ask follow-up questions, so put everything it needs in the prompt — file paths, constraints, and what to return.",
+            "You receive only its final message, so state explicitly what it should report back.",
+            "Use this for wide searches or independent tracks of work; do routine multi-step work yourself rather than paying the delegation overhead.",
+            "",
+            "Available agent types:",
+            roster,
+        ].join("\n"),
+        parameters: z.object({
+            agentType: z
+                .string()
+                .describe(`Which subagent to run. One of: ${types.map((t) => t.name).join(", ") || "none"}`),
+            description: z.string().describe("Short (3-5 word) description of the task"),
+            prompt: z.string().min(1).describe("The complete, self-contained task for the subagent"),
+            model: z
+                .string()
+                .optional()
+                .describe("Override the model for this subagent, e.g. 'haiku' for cheap fan-out"),
+        }),
+        renderTitle: (input) => `Task(${input.agentType}: ${input.description})`,
+        async execute(input, ctx) {
+            const known = ctx.host.listSubagentTypes().map((t) => t.name);
+            if (!known.includes(input.agentType)) {
+                return toolError(`unknown agent type "${input.agentType}". Available: ${known.join(", ") || "none"}`);
+            }
+            ctx.onProgress({
+                toolCallId: ctx.toolCallId,
+                toolName: "task",
+                message: `Running ${input.agentType} subagent: ${input.description}`,
+            });
+            try {
+                const result = await ctx.host.runSubagent({
+                    agentType: input.agentType,
+                    prompt: input.prompt,
+                    description: input.description,
+                    model: input.model,
+                    signal: ctx.signal,
+                });
+                return toolText(result.text || "(the subagent returned no text)", {
+                    turns: result.turns,
+                    usage: result.usage,
+                });
+            }
+            catch (err) {
+                return toolError(`subagent failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        },
+    });
+}
+//# sourceMappingURL=task.js.map

package/dist/tools/builtin/task.js.map

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

package/dist/tools/builtin/todo.d.ts

@@ -0,0 +1,20 @@
+import { z } from "zod";
+declare const TodoItemSchema: z.ZodObject<{
+    content: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        in_progress: "in_progress";
+        completed: "completed";
+    }>;
+    activeForm: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type TodoItem = z.infer<typeof TodoItemSchema>;
+/**
+ * A scratchpad the model owns. Its value is less the storage than the forcing
+ * function: writing the plan down keeps multi-step work from drifting, and
+ * gives the user something to watch.
+ */
+export declare const todoTool: import("../types.ts").Tool;
+export declare function getTodos(state: Map<string, unknown>): TodoItem[];
+export declare function renderTodos(todos: TodoItem[]): string;
+export {};

package/dist/tools/builtin/todo.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { defineTool } from "../define.js";
+import { toolText } from "../types.js";
+const TODO_KEY = "todo:list";
+const TodoItemSchema = z.object({
+    content: z.string().min(1).describe("What needs to be done, in imperative form"),
+    status: z.enum(["pending", "in_progress", "completed"]),
+    activeForm: z
+        .string()
+        .optional()
+        .describe("Present-continuous form shown while the item is in progress"),
+});
+/**
+ * A scratchpad the model owns. Its value is less the storage than the forcing
+ * function: writing the plan down keeps multi-step work from drifting, and
+ * gives the user something to watch.
+ */
+export const todoTool = defineTool({
+    name: "todo_write",
+    description: [
+        "Record or update the task list for multi-step work.",
+        "Send the complete list every time — it replaces the previous one.",
+        "Keep exactly one item `in_progress`, and mark items `completed` as soon as they are actually done.",
+        "Skip this for single-step or trivial requests.",
+    ].join(" "),
+    parameters: z.object({
+        todos: z.array(TodoItemSchema).describe("The full task list, in order"),
+    }),
+    renderTitle: (input) => `Todo(${input.todos.length} items)`,
+    // The same: a list held in session state, guarded by nobody.
+    sessionLocal: true,
+    async execute(input, ctx) {
+        const inProgress = input.todos.filter((t) => t.status === "in_progress");
+        if (inProgress.length > 1) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${inProgress.length} items are in_progress. Exactly one item may be in progress at a time.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        ctx.host.state.set(TODO_KEY, input.todos);
+        return toolText(renderTodos(input.todos), { todos: input.todos });
+    },
+});
+export function getTodos(state) {
+    const stored = state.get(TODO_KEY);
+    return Array.isArray(stored) ? stored : [];
+}
+export function renderTodos(todos) {
+    if (todos.length === 0)
+        return "Task list cleared.";
+    const done = todos.filter((t) => t.status === "completed").length;
+    const lines = todos.map((todo) => {
+        const mark = todo.status === "completed" ? "x" : todo.status === "in_progress" ? "~" : " ";
+        return `[${mark}] ${todo.content}`;
+    });
+    return `${lines.join("\n")}\n\n${done}/${todos.length} complete.`;
+}
+//# sourceMappingURL=todo.js.map

package/dist/tools/builtin/todo.js.map

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

package/dist/tools/define.d.ts

@@ -0,0 +1,19 @@
+import { z } from "zod";
+import type { Tool, ToolContext, ToolResult } from "./types.ts";
+export interface DefineToolOptions<S extends z.ZodType> {
+    name: string;
+    description: string;
+    parameters: S;
+    readOnly?: boolean;
+    concurrencySafe?: boolean;
+    sessionLocal?: boolean;
+    hidden?: boolean;
+    renderTitle?(input: z.infer<S>): string;
+    execute(input: z.infer<S>, ctx: ToolContext): Promise<ToolResult>;
+}
+/**
+ * Define a tool from a zod schema. The schema does double duty: it generates
+ * the JSON Schema the model sees, and it validates the model's input before
+ * `execute` runs — so tools never have to defend against malformed arguments.
+ */
+export declare function defineTool<S extends z.ZodType>(opts: DefineToolOptions<S>): Tool;

package/dist/tools/define.js

@@ -0,0 +1,39 @@
+import { z } from "zod";
+import { zodToJsonSchema } from "../util/schema.js";
+/**
+ * Define a tool from a zod schema. The schema does double duty: it generates
+ * the JSON Schema the model sees, and it validates the model's input before
+ * `execute` runs — so tools never have to defend against malformed arguments.
+ */
+export function defineTool(opts) {
+    const inputSchema = zodToJsonSchema(opts.parameters);
+    return {
+        name: opts.name,
+        description: opts.description,
+        inputSchema,
+        readOnly: opts.readOnly,
+        concurrencySafe: opts.concurrencySafe ?? opts.readOnly,
+        sessionLocal: opts.sessionLocal,
+        hidden: opts.hidden,
+        source: "builtin",
+        validate(raw) {
+            const parsed = opts.parameters.safeParse(raw ?? {});
+            if (parsed.success)
+                return { ok: true, value: parsed.data };
+            return { ok: false, error: formatZodError(parsed.error) };
+        },
+        renderTitle: opts.renderTitle
+            ? (input) => opts.renderTitle(input)
+            : undefined,
+        execute: (input, ctx) => opts.execute(input, ctx),
+    };
+}
+function formatZodError(error) {
+    return error.issues
+        .map((issue) => {
+        const path = issue.path.length ? issue.path.join(".") : "(root)";
+        return `${path}: ${issue.message}`;
+    })
+        .join("; ");
+}
+//# sourceMappingURL=define.js.map

package/dist/tools/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../../src/tools/define.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAepD;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAsB,IAA0B;IACxE,MAAM,WAAW,GAAG,eAAe,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IAErD,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW;QACX,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,eAAe,EAAE,IAAI,CAAC,eAAe,IAAI,IAAI,CAAC,QAAQ;QACtD,YAAY,EAAE,IAAI,CAAC,YAAY;QAC/B,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,MAAM,EAAE,SAAS;QACjB,QAAQ,CAAC,GAAG;YACV,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC;YACpD,IAAI,MAAM,CAAC,OAAO;gBAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;YAC5D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;QAC5D,CAAC;QACD,WAAW,EAAE,IAAI,CAAC,WAAW;YAC3B,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,WAAY,CAAC,KAAmB,CAAC;YACnD,CAAC,CAAC,SAAS;QACb,OAAO,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,KAAmB,EAAE,GAAG,CAAC;KAChE,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,KAAiB;IACvC,OAAO,KAAK,CAAC,MAAM;SAChB,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE;QACb,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;QACjE,OAAO,GAAG,IAAI,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC;IACrC,CAAC,CAAC;SACD,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}

package/dist/tools/index.d.ts

@@ -0,0 +1,7 @@
+export { defineTool } from "./define.ts";
+export type { DefineToolOptions } from "./define.ts";
+export { ToolRegistry, matchesFilter, matchPattern } from "./registry.ts";
+export type { ToolFilter } from "./registry.ts";
+export { toolText, toolError, toolImage, toolResultText } from "./types.ts";
+export type { SubagentRunOptions, SubagentRunResult, Tool, ToolContent, ToolContext, ToolHost, ToolProgress, ToolResult, } from "./types.ts";
+export * from "./builtin/index.ts";

package/dist/tools/index.js

@@ -0,0 +1,5 @@
+export { defineTool } from "./define.js";
+export { ToolRegistry, matchesFilter, matchPattern } from "./registry.js";
+export { toolText, toolError, toolImage, toolResultText } from "./types.js";
+export * from "./builtin/index.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE1E,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAW5E,cAAc,oBAAoB,CAAC"}

package/dist/tools/registry.d.ts

@@ -0,0 +1,39 @@
+import type { ToolSchema } from "../core/types.ts";
+import type { Tool } from "./types.ts";
+export interface ToolFilter {
+    /** Only these tool names are exposed (glob-ish `mcp__github__*` allowed). */
+    allow?: string[];
+    /** These are removed, applied after `allow`. */
+    deny?: string[];
+}
+/**
+ * The set of tools a given agent may call. Registries are cheap to clone, so
+ * subagents get a filtered view rather than a shared mutable one.
+ */
+export declare class ToolRegistry {
+    private readonly tools;
+    register(tool: Tool): this;
+    registerAll(tools: Iterable<Tool>): this;
+    unregister(name: string): boolean;
+    /** Drop every tool contributed by an MCP server (used on disconnect). */
+    unregisterServer(server: string): number;
+    get(name: string): Tool | undefined;
+    /**
+     * Like `get`, but throws when the tool is missing. For call sites that
+     * cannot meaningfully continue without it — the agent loop uses `get` and
+     * reports the miss to the model instead.
+     */
+    require(name: string): Tool;
+    has(name: string): boolean;
+    list(): Tool[];
+    /** Tools the model is told about: visible, and passing the filter. */
+    visible(filter?: ToolFilter): Tool[];
+    /** The provider-facing schema list. */
+    schemas(filter?: ToolFilter): ToolSchema[];
+    clone(): ToolRegistry;
+    /** A view containing only the tools that pass `filter`. */
+    filtered(filter: ToolFilter): ToolRegistry;
+}
+export declare function matchesFilter(name: string, filter: ToolFilter | undefined): boolean;
+/** `*` matches any run of characters; everything else is literal. */
+export declare function matchPattern(value: string, pattern: string): boolean;

package/dist/tools/registry.js

@@ -0,0 +1,101 @@
+import { ToolError } from "../core/errors.js";
+/**
+ * The set of tools a given agent may call. Registries are cheap to clone, so
+ * subagents get a filtered view rather than a shared mutable one.
+ */
+export class ToolRegistry {
+    tools = new Map();
+    register(tool) {
+        this.tools.set(tool.name, tool);
+        return this;
+    }
+    registerAll(tools) {
+        for (const tool of tools)
+            this.register(tool);
+        return this;
+    }
+    unregister(name) {
+        return this.tools.delete(name);
+    }
+    /** Drop every tool contributed by an MCP server (used on disconnect). */
+    unregisterServer(server) {
+        let removed = 0;
+        for (const [name, tool] of this.tools) {
+            if (tool.source === "mcp" && tool.server === server) {
+                this.tools.delete(name);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    get(name) {
+        return this.tools.get(name);
+    }
+    /**
+     * Like `get`, but throws when the tool is missing. For call sites that
+     * cannot meaningfully continue without it — the agent loop uses `get` and
+     * reports the miss to the model instead.
+     */
+    require(name) {
+        const tool = this.tools.get(name);
+        if (!tool) {
+            throw new ToolError(name, `no tool named "${name}". Registered: ${this.list().map((t) => t.name).join(", ")}`);
+        }
+        return tool;
+    }
+    has(name) {
+        return this.tools.has(name);
+    }
+    list() {
+        return [...this.tools.values()];
+    }
+    /** Tools the model is told about: visible, and passing the filter. */
+    visible(filter) {
+        return this.list().filter((tool) => !tool.hidden && matchesFilter(tool.name, filter));
+    }
+    /** The provider-facing schema list. */
+    schemas(filter) {
+        return this.visible(filter).map((tool) => ({
+            name: tool.name,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+        }));
+    }
+    clone() {
+        const copy = new ToolRegistry();
+        for (const tool of this.tools.values())
+            copy.register(tool);
+        return copy;
+    }
+    /** A view containing only the tools that pass `filter`. */
+    filtered(filter) {
+        const copy = new ToolRegistry();
+        for (const tool of this.tools.values()) {
+            if (matchesFilter(tool.name, filter))
+                copy.register(tool);
+        }
+        return copy;
+    }
+}
+export function matchesFilter(name, filter) {
+    if (!filter)
+        return true;
+    if (filter.allow?.length && !filter.allow.some((p) => matchPattern(name, p)))
+        return false;
+    if (filter.deny?.length && filter.deny.some((p) => matchPattern(name, p)))
+        return false;
+    return true;
+}
+/** `*` matches any run of characters; everything else is literal. */
+export function matchPattern(value, pattern) {
+    if (pattern === "*")
+        return true;
+    if (!pattern.includes("*"))
+        return value === pattern;
+    const escaped = pattern
+        .split("*")
+        .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+        .join(".*");
+    return new RegExp(`^${escaped}$`).test(value);
+}
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAU9C;;;GAGG;AACH,MAAM,OAAO,YAAY;IACN,KAAK,GAAG,IAAI,GAAG,EAAgB,CAAC;IAEjD,QAAQ,CAAC,IAAU;QACjB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,WAAW,CAAC,KAAqB;QAC/B,KAAK,MAAM,IAAI,IAAI,KAAK;YAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,UAAU,CAAC,IAAY;QACrB,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IACjC,CAAC;IAED,yEAAyE;IACzE,gBAAgB,CAAC,MAAc;QAC7B,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,KAAK,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,IAAI,IAAI,CAAC,MAAM,KAAK,KAAK,IAAI,IAAI,CAAC,MAAM,KAAK,MAAM,EAAE,CAAC;gBACpD,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBACxB,OAAO,EAAE,CAAC;YACZ,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED;;;;OAIG;IACH,OAAO,CAAC,IAAY;QAClB,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClC,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,SAAS,CACjB,IAAI,EACJ,kBAAkB,IAAI,kBAAkB,IAAI,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACpF,CAAC;QACJ,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAClC,CAAC;IAED,sEAAsE;IACtE,OAAO,CAAC,MAAmB;QACzB,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,MAAM,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IACxF,CAAC;IAED,uCAAuC;IACvC,OAAO,CAAC,MAAmB;QACzB,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;YACzC,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC,CAAC,CAAC;IACN,CAAC;IAED,KAAK;QACH,MAAM,IAAI,GAAG,IAAI,YAAY,EAAE,CAAC;QAChC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE;YAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC5D,OAAO,IAAI,CAAC;IACd,CAAC;IAED,2DAA2D;IAC3D,QAAQ,CAAC,MAAkB;QACzB,MAAM,IAAI,GAAG,IAAI,YAAY,EAAE,CAAC;QAChC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;YACvC,IAAI,aAAa,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC;gBAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC5D,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AAED,MAAM,UAAU,aAAa,CAAC,IAAY,EAAE,MAA8B;IACxE,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,MAAM,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IAC3F,IAAI,MAAM,CAAC,IAAI,EAAE,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAAE,OAAO,KAAK,CAAC;IACxF,OAAO,IAAI,CAAC;AACd,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,OAAe;IACzD,IAAI,OAAO,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IACjC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,KAAK,OAAO,CAAC;IACrD,MAAM,OAAO,GAAG,OAAO;SACpB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;SAC1D,IAAI,CAAC,IAAI,CAAC,CAAC;IACd,OAAO,IAAI,MAAM,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAChD,CAAC"}

package/dist/tools/types.d.ts

@@ -0,0 +1,112 @@
+import type { ImageBlock, JSONSchema, TextBlock } from "../core/types.ts";
+import type { Logger } from "../util/logger.ts";
+export type ToolContent = Array<TextBlock | ImageBlock>;
+export interface ToolResult {
+    content: ToolContent;
+    isError?: boolean;
+    /** Not sent to the model; available to hooks and the UI. */
+    metadata?: Record<string, unknown>;
+}
+/** Emitted while a tool runs, so a UI can show progress. */
+export interface ToolProgress {
+    toolCallId: string;
+    toolName: string;
+    message: string;
+    data?: unknown;
+}
+export interface ToolContext {
+    cwd: string;
+    sessionId: string;
+    /** Id of the agent invoking the tool — main loop or a subagent. */
+    agentId: string;
+    toolCallId: string;
+    signal: AbortSignal;
+    logger: Logger;
+    onProgress(progress: ToolProgress): void;
+    /**
+     * Capabilities the harness lends to tools. Kept as an interface so the tool
+     * layer never imports the agent (which imports tools).
+     */
+    host: ToolHost;
+}
+export interface SubagentRunOptions {
+    agentType: string;
+    prompt: string;
+    description?: string;
+    model?: string;
+    signal?: AbortSignal;
+}
+export interface SubagentRunResult {
+    text: string;
+    turns: number;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+export interface ToolHost {
+    /** Spawn a subagent and run it to completion. Backs the Task tool. */
+    runSubagent(opts: SubagentRunOptions): Promise<SubagentRunResult>;
+    listSubagentTypes(): Array<{
+        name: string;
+        description: string;
+    }>;
+    /** Shared, session-scoped scratch state (the todo list lives here). */
+    state: Map<string, unknown>;
+    /**
+     * Resolve a model-supplied path against the workspace policy, throwing when
+     * it falls outside the roots allowed for that kind of access.
+     *
+     * Optional because the policy belongs to the agent and a bare host may not
+     * have one; tools then fall back to confining paths to the working
+     * directory. Lent as a capability rather than exposed as data so the tool
+     * layer still never imports the agent.
+     */
+    resolvePath?(input: string, access: "read" | "write"): string;
+}
+export interface Tool {
+    name: string;
+    /** Sent to the model — the main lever on whether the tool gets used well. */
+    description: string;
+    inputSchema: JSONSchema;
+    /**
+     * Read-only tools can be batched in parallel and skip permission prompts.
+     * Anything that mutates state or reaches the network should leave this off.
+     */
+    readOnly?: boolean;
+    /** Safe to run concurrently with other tools in the same assistant turn. */
+    concurrencySafe?: boolean;
+    /**
+     * Mutates only this session's own scratch state — no file, no command, no
+     * network, nothing that outlives the process.
+     *
+     * Distinct from `readOnly`, which such a tool is not: it changes something,
+     * and plan mode should still stop it. What this says is narrower — that
+     * approving it protects nobody, so asking is a toll rather than a safeguard.
+     * The permission engine exists to guard effects outside this process; see
+     * the note at the top of packages/server/src/server.ts for what it is really
+     * standing between.
+     */
+    sessionLocal?: boolean;
+    /** Hidden from the model but still invocable internally. */
+    hidden?: boolean;
+    /** Where the tool came from, for `/tools` and permission rules. */
+    source?: "builtin" | "mcp" | "custom";
+    /** MCP server name when `source === "mcp"`. */
+    server?: string;
+    /** Parse/validate raw model input. Returning an error skips execution. */
+    validate?(raw: unknown): {
+        ok: true;
+        value: unknown;
+    } | {
+        ok: false;
+        error: string;
+    };
+    /** One-line rendering of a call, e.g. `Bash(npm test)`. */
+    renderTitle?(input: unknown): string;
+    execute(input: unknown, ctx: ToolContext): Promise<ToolResult>;
+}
+export declare function toolText(text: string, metadata?: Record<string, unknown>): ToolResult;
+export declare function toolError(message: string): ToolResult;
+export declare function toolImage(mimeType: string, data: string, caption?: string): ToolResult;
+export declare function toolResultText(result: ToolResult): string;

package/dist/tools/types.js

@@ -0,0 +1,22 @@
+// ---------------------------------------------------------------------------
+// Result helpers
+// ---------------------------------------------------------------------------
+export function toolText(text, metadata) {
+    return { content: [{ type: "text", text }], ...(metadata ? { metadata } : {}) };
+}
+export function toolError(message) {
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+export function toolImage(mimeType, data, caption) {
+    const content = [{ type: "image", mimeType, data }];
+    if (caption)
+        content.unshift({ type: "text", text: caption });
+    return { content };
+}
+export function toolResultText(result) {
+    return result.content
+        .filter((b) => b.type === "text")
+        .map((b) => b.text)
+        .join("\n");
+}
+//# sourceMappingURL=types.js.map

package/dist/tools/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/tools/types.ts"],"names":[],"mappings":"AA0GA,8EAA8E;AAC9E,iBAAiB;AACjB,8EAA8E;AAE9E,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,QAAkC;IACvE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AAClF,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,QAAgB,EAAE,IAAY,EAAE,OAAgB;IACxE,MAAM,OAAO,GAAgB,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;IACjE,IAAI,OAAO;QAAE,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAC9D,OAAO,EAAE,OAAO,EAAE,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,MAAkB;IAC/C,OAAO,MAAM,CAAC,OAAO;SAClB,MAAM,CAAC,CAAC,CAAC,EAAkB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;SAChD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;SAClB,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}

package/dist/util/id.d.ts

@@ -0,0 +1,9 @@
+export declare function uuid(): string;
+export declare function shortId(bytes?: number): string;
+/**
+ * Tool-call ids must satisfy the strictest provider we target: OpenAI accepts
+ * arbitrary strings but rejects long ones on some endpoints, Gemini ignores
+ * them entirely. `call_<hex>` is safe everywhere.
+ */
+export declare function toolCallId(): string;
+export declare function sessionId(): string;

package/dist/util/id.js

@@ -0,0 +1,19 @@
+import { randomUUID, randomBytes } from "node:crypto";
+export function uuid() {
+    return randomUUID();
+}
+export function shortId(bytes = 6) {
+    return randomBytes(bytes).toString("hex");
+}
+/**
+ * Tool-call ids must satisfy the strictest provider we target: OpenAI accepts
+ * arbitrary strings but rejects long ones on some endpoints, Gemini ignores
+ * them entirely. `call_<hex>` is safe everywhere.
+ */
+export function toolCallId() {
+    return `call_${shortId(12)}`;
+}
+export function sessionId() {
+    return `${new Date().toISOString().slice(0, 10).replaceAll("-", "")}_${shortId(5)}`;
+}
+//# sourceMappingURL=id.js.map

package/dist/util/id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id.js","sourceRoot":"","sources":["../../src/util/id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,UAAU,IAAI;IAClB,OAAO,UAAU,EAAE,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,KAAK,GAAG,CAAC;IAC/B,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC5C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU;IACxB,OAAO,QAAQ,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,OAAO,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;AACtF,CAAC"}

package/dist/util/json.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tolerant JSON helpers for streamed tool arguments.
+ *
+ * Providers emit tool inputs as a stream of JSON fragments. To render a
+ * live preview ("Bash(npm run bui…") we need to parse a prefix of a JSON
+ * document, so `parsePartialJson` closes any open strings/arrays/objects
+ * before handing the text to JSON.parse.
+ */
+export declare function parseJson<T = unknown>(raw: string): {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function parsePartialJson(raw: string): unknown;
+/**
+ * Decode accumulated tool-argument JSON. Models occasionally emit a truncated
+ * or slightly malformed object; falling back to the partial parser keeps the
+ * turn alive, and an empty object lets the tool's own validation produce a
+ * useful error message instead of crashing the loop.
+ */
+export declare function decodeToolInput(raw: string): unknown;
+/** Truncate deeply/hugely nested values before logging or previewing. */
+export declare function previewJson(value: unknown, maxLength?: number): string;