zoe-agent 0.3.1

package/dist/core/stream-manager.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Zoe Core — StreamManager
+ *
+ * Shared streaming queue management for text deltas, step results,
+ * and SSE conversion. Eliminates duplication between SDK's streamText()
+ * and agent's chatStream().
+ *
+ * Pattern: push-based queues with resolver-based backpressure.
+ * Producers call enqueueText/enqueueStep; consumers iterate via
+ * textStream/stepsStream async iterables.
+ */
+import type { StepResult, Usage } from "./types.js";
+export declare class StreamManager {
+    private textQueue;
+    private stepQueue;
+    private eventQueue;
+    private textDone;
+    private stepsDone;
+    private eventsDone;
+    private textResolver;
+    private stepResolver;
+    private eventResolver;
+    private textResolve;
+    private usageResolve;
+    private finishResolve;
+    readonly fullText: Promise<string>;
+    readonly usage: Promise<Usage>;
+    readonly finishReason: Promise<string>;
+    constructor();
+    /** Enqueue a text delta and wake any waiting consumer. */
+    enqueueText(delta: string): void;
+    /** Enqueue a step result and wake any waiting consumer. */
+    enqueueStep(step: StepResult): void;
+    /** Resolve the fullText promise. */
+    resolveText(text: string): void;
+    /** Resolve the usage promise. */
+    resolveUsage(usage: Usage): void;
+    /** Resolve the finishReason promise. */
+    resolveFinish(reason: string): void;
+    /** Signal completion: set done flags and wake any waiting consumers. */
+    complete(): void;
+    /** Async iterable of text deltas. */
+    get textStream(): AsyncIterable<string>;
+    /** Async iterable of step results. */
+    get stepsStream(): AsyncIterable<StepResult>;
+    /**
+     * Returns a ReadableStream that pipes text deltas and tool events as SSE.
+     *
+     * Events emitted:
+     *  - `text`        — { delta: string }
+     *  - `tool_call`   — { callId, name, args }
+     *  - `tool_result` — { callId, output, success }
+     *  - `done`        — { usage: { totalTokens, cost }, finishReason }
+     */
+    toSSEStream(): ReadableStream;
+    /** Returns a Web API Response wrapping the SSE stream. */
+    toResponse(): Response;
+}

package/dist/core/stream-manager.js

@@ -0,0 +1,212 @@
+/**
+ * Zoe Core — StreamManager
+ *
+ * Shared streaming queue management for text deltas, step results,
+ * and SSE conversion. Eliminates duplication between SDK's streamText()
+ * and agent's chatStream().
+ *
+ * Pattern: push-based queues with resolver-based backpressure.
+ * Producers call enqueueText/enqueueStep; consumers iterate via
+ * textStream/stepsStream async iterables.
+ */
+// ── SSE helper ────────────────────────────────────────────────────────────
+function sseLine(event, data) {
+    return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+// ── StreamManager ─────────────────────────────────────────────────────────
+export class StreamManager {
+    // Queues for individual consumers
+    textQueue = [];
+    stepQueue = [];
+    // Unified event queue preserving interleaved insertion order for SSE
+    eventQueue = [];
+    // Done flags
+    textDone = false;
+    stepsDone = false;
+    eventsDone = false;
+    // Resolvers for backpressure
+    textResolver = null;
+    stepResolver = null;
+    eventResolver = null;
+    // Result promises
+    textResolve;
+    usageResolve;
+    finishResolve;
+    fullText;
+    usage;
+    finishReason;
+    constructor() {
+        this.fullText = new Promise((r) => { this.textResolve = r; });
+        this.usage = new Promise((r) => { this.usageResolve = r; });
+        this.finishReason = new Promise((r) => { this.finishResolve = r; });
+    }
+    // ── Producer API ──────────────────────────────────────────────────────
+    /** Enqueue a text delta and wake any waiting consumer. */
+    enqueueText(delta) {
+        this.textQueue.push(delta);
+        this.eventQueue.push({ type: "text", delta });
+        if (this.textResolver) {
+            this.textResolver();
+            this.textResolver = null;
+        }
+        if (this.eventResolver) {
+            this.eventResolver();
+            this.eventResolver = null;
+        }
+    }
+    /** Enqueue a step result and wake any waiting consumer. */
+    enqueueStep(step) {
+        this.stepQueue.push(step);
+        this.eventQueue.push({ type: "step", step });
+        if (this.stepResolver) {
+            this.stepResolver();
+            this.stepResolver = null;
+        }
+        if (this.eventResolver) {
+            this.eventResolver();
+            this.eventResolver = null;
+        }
+    }
+    /** Resolve the fullText promise. */
+    resolveText(text) {
+        this.textResolve(text);
+    }
+    /** Resolve the usage promise. */
+    resolveUsage(usage) {
+        this.usageResolve(usage);
+    }
+    /** Resolve the finishReason promise. */
+    resolveFinish(reason) {
+        this.finishResolve(reason);
+    }
+    /** Signal completion: set done flags and wake any waiting consumers. */
+    complete() {
+        this.textDone = true;
+        this.stepsDone = true;
+        this.eventsDone = true;
+        if (this.textResolver) {
+            this.textResolver();
+            this.textResolver = null;
+        }
+        if (this.stepResolver) {
+            this.stepResolver();
+            this.stepResolver = null;
+        }
+        if (this.eventResolver) {
+            this.eventResolver();
+            this.eventResolver = null;
+        }
+    }
+    // ── Consumer API ──────────────────────────────────────────────────────
+    /** Async iterable of text deltas. */
+    get textStream() {
+        const self = this;
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    async next() {
+                        while (self.textQueue.length === 0 && !self.textDone) {
+                            await new Promise((r) => { self.textResolver = r; });
+                        }
+                        if (self.textQueue.length > 0) {
+                            return { value: self.textQueue.shift(), done: false };
+                        }
+                        return { value: undefined, done: true };
+                    },
+                };
+            },
+        };
+    }
+    /** Async iterable of step results. */
+    get stepsStream() {
+        const self = this;
+        return {
+            [Symbol.asyncIterator]() {
+                return {
+                    async next() {
+                        while (self.stepQueue.length === 0 && !self.stepsDone) {
+                            await new Promise((r) => { self.stepResolver = r; });
+                        }
+                        if (self.stepQueue.length > 0) {
+                            return { value: self.stepQueue.shift(), done: false };
+                        }
+                        return { value: undefined, done: true };
+                    },
+                };
+            },
+        };
+    }
+    /**
+     * Returns a ReadableStream that pipes text deltas and tool events as SSE.
+     *
+     * Events emitted:
+     *  - `text`        — { delta: string }
+     *  - `tool_call`   — { callId, name, args }
+     *  - `tool_result` — { callId, output, success }
+     *  - `done`        — { usage: { totalTokens, cost }, finishReason }
+     */
+    toSSEStream() {
+        const encoder = new TextEncoder();
+        const self = this;
+        return new ReadableStream({
+            async start(controller) {
+                try {
+                    // Drain unified event queue preserving interleaved order
+                    while (true) {
+                        while (self.eventQueue.length === 0 && !self.eventsDone) {
+                            await new Promise((r) => { self.eventResolver = r; });
+                        }
+                        if (self.eventQueue.length === 0)
+                            break;
+                        const event = self.eventQueue.shift();
+                        if (event.type === "text") {
+                            controller.enqueue(encoder.encode(sseLine("text", { delta: event.delta })));
+                        }
+                        else if (event.type === "step" && event.step.type === "tool_call" && event.step.toolCall) {
+                            controller.enqueue(encoder.encode(sseLine("tool_call", {
+                                callId: event.step.toolCall.id,
+                                name: event.step.toolCall.name,
+                                args: event.step.toolCall.args,
+                            })));
+                            controller.enqueue(encoder.encode(sseLine("tool_result", {
+                                callId: event.step.toolCall.id,
+                                output: event.step.toolCall.result,
+                                success: true,
+                            })));
+                        }
+                    }
+                    // Done event
+                    const [usage, finishReason] = await Promise.all([
+                        self.usage,
+                        self.finishReason,
+                    ]);
+                    controller.enqueue(encoder.encode(sseLine("done", {
+                        usage: {
+                            totalTokens: usage.totalTokens,
+                            cost: usage.cost,
+                        },
+                        finishReason,
+                    })));
+                }
+                catch (err) {
+                    if (err instanceof Error && err.name !== "AbortError") {
+                        console.warn("[StreamManager] SSE stream error:", err);
+                    }
+                }
+                finally {
+                    controller.close();
+                }
+            },
+        });
+    }
+    /** Returns a Web API Response wrapping the SSE stream. */
+    toResponse() {
+        return new Response(this.toSSEStream(), {
+            headers: {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+            },
+        });
+    }
+}

package/dist/core/tool-executor.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Zoe Core — Tool executor
+ *
+ * Tool registry, resolution, factory, and execution logic.
+ * Transport-agnostic: no chalk, no HTTP, no CLI concerns.
+ */
+import { ToolModule, ToolDefinition, ToolExecExtra } from "../tools/interface.js";
+import { UserToolDefinition, ToolResult } from "./types.js";
+/**
+ * Return the tool definitions for all registered tools (built-in + custom).
+ */
+export declare function getAllToolDefinitions(): ToolDefinition[];
+/**
+ * Return all registered tool modules (built-in + custom).
+ */
+export declare function getAllToolModules(): ToolModule[];
+export declare const CORE_TOOLS: string[];
+export declare const COMM_TOOLS: string[];
+export declare const ADVANCED_TOOLS: string[];
+export declare const ALL_TOOLS: string[];
+/**
+ * Create a custom tool module from a Zod-like schema definition.
+ *
+ * Returns a `ToolModule` compatible with the built-in tool registry,
+ * so custom tools can be mixed freely with built-in ones.
+ *
+ * @example
+ * ```ts
+ * const myTool = tool({
+ *   description: "Greets a person",
+ *   parameters: z.object({ name: z.string() }),
+ *   execute: async ({ name }) => `Hello, ${name}!`,
+ * });
+ * ```
+ */
+export declare function tool(definition: UserToolDefinition): ToolModule;
+/**
+ * Register a tool module in the global tool registry.
+ *
+ * @param module  A `ToolModule` to add to the registry
+ */
+export declare function registerTool(module: ToolModule): void;
+/**
+ * Coerce a tool handler's `string | ToolResult` return into a `ToolResult`.
+ * Plain strings (the common case) become `{ output, success: true }` with no
+ * metadata. Structured ToolResults pass through with `metadata` preserved.
+ */
+export declare function normalizeToolResult(raw: string | ToolResult): ToolResult;
+/**
+ * Execute a tool by name with the given arguments and optional config.
+ *
+ * @param name    Tool function name (e.g. "execute_shell_command")
+ * @param args    Arguments object for the tool
+ * @param config  Optional runtime config passed to the tool handler
+ * @returns       ToolResult — `output` (what the LLM sees) + optional `metadata`
+ *                for adapters (e.g. write_file's FileWriteMetadata for the diff)
+ * @throws        Error if the tool name is not found in the registry
+ */
+export declare function executeTool(name: string, args: Record<string, unknown>, config?: Record<string, unknown>, extra?: ToolExecExtra): Promise<ToolResult>;
+/**
+ * Return the built-in tool definitions belonging to a named group.
+ *
+ * @param group  One of "core", "comm", "advanced", or "all"
+ * @returns      Array of OpenAI function definitions for the matching tools
+ * @throws       Error if the group name is not recognised
+ */
+export declare function getToolGroup(group: "core" | "comm" | "advanced" | "all"): ToolDefinition[];
+type ToolInput = string | UserToolDefinition;
+/**
+ * Resolve a mixed array of tool references into concrete OpenAI function
+ * definitions ready to send to the LLM.
+ *
+ * Accepted input shapes:
+ *  - `"all"`                     — expands to all built-in tools
+ *  - `"core"` / `"comm"` / `"advanced"` — expands to the named group
+ *  - A built-in tool name string — looked up from the internal registry
+ *  - A `UserToolDefinition` object   — converted via `tool()` factory
+ *
+ * @param tools  Array of tool references (defaults to all built-in tools)
+ * @returns      Deduplicated array of OpenAI function definitions
+ * @throws       Error if a string name is not found in the built-in registry
+ */
+export declare function resolveTools(tools?: ToolInput[]): ToolDefinition[];
+export {};

package/dist/core/tool-executor.js

@@ -0,0 +1,256 @@
+/**
+ * Zoe Core — Tool executor
+ *
+ * Tool registry, resolution, factory, and execution logic.
+ * Transport-agnostic: no chalk, no HTTP, no CLI concerns.
+ */
+import { builtInTools } from "../tools/index.js";
+// ── Internal registry ───────────────────────────────────────────────
+const registry = [...builtInTools];
+/**
+ * Return the tool definitions for all registered tools (built-in + custom).
+ */
+export function getAllToolDefinitions() {
+    return registry.map((t) => t.definition);
+}
+/**
+ * Return all registered tool modules (built-in + custom).
+ */
+export function getAllToolModules() {
+    return registry;
+}
+// ── Tool groups ──────────────────────────────────────────────────────
+export const CORE_TOOLS = [
+    "execute_shell_command",
+    "read_file",
+    "write_file",
+    "get_current_datetime",
+];
+export const COMM_TOOLS = [
+    "send_email",
+    "web_search",
+    "send_notification",
+];
+export const ADVANCED_TOOLS = [
+    "read_website",
+    "take_screenshot",
+    "generate_image",
+    "optimize_prompt",
+    "use_skill",
+];
+export const ALL_TOOLS = [...CORE_TOOLS, ...COMM_TOOLS, ...ADVANCED_TOOLS];
+// ── Helpers ──────────────────────────────────────────────────────────
+let customToolCounter = 0;
+/**
+ * Convert a parameter definition into JSON Schema.
+ *
+ * Accepts plain `{ type: "object", properties: {...}, required: [...] }` objects.
+ * Anything else is wrapped in a generic object schema.
+ */
+function parametersToJsonSchema(parameters) {
+    if (parameters == null || typeof parameters !== "object") {
+        return { type: "object", properties: {} };
+    }
+    const rec = parameters;
+    // Already a valid JSON Schema object — validate basic shape
+    if ("type" in rec && "properties" in rec
+        && typeof rec.type === "string"
+        && typeof rec.properties === "object" && rec.properties !== null) {
+        return rec;
+    }
+    // Unknown shape — wrap generically
+    return { type: "object", properties: {} };
+}
+/**
+ * Generate a unique tool name when the user doesn't supply one.
+ */
+function generateToolName() {
+    customToolCounter += 1;
+    return `custom_tool_${customToolCounter}`;
+}
+// ── tool() factory ───────────────────────────────────────────────────
+/**
+ * Create a custom tool module from a Zod-like schema definition.
+ *
+ * Returns a `ToolModule` compatible with the built-in tool registry,
+ * so custom tools can be mixed freely with built-in ones.
+ *
+ * @example
+ * ```ts
+ * const myTool = tool({
+ *   description: "Greets a person",
+ *   parameters: z.object({ name: z.string() }),
+ *   execute: async ({ name }) => `Hello, ${name}!`,
+ * });
+ * ```
+ */
+export function tool(definition) {
+    const functionName = definition.name ?? generateToolName();
+    const jsonSchema = parametersToJsonSchema(definition.parameters);
+    const openaiDefinition = {
+        type: "function",
+        function: {
+            name: functionName,
+            description: definition.description,
+            parameters: {
+                type: jsonSchema.type ?? "object",
+                properties: jsonSchema.properties ?? {},
+                required: jsonSchema.required ?? [],
+            },
+        },
+    };
+    const handler = async (args, config, extra) => {
+        const context = {
+            config: config ?? {},
+            onUpdate: extra?.onUpdate,
+            signal: extra?.signal,
+        };
+        // Passthrough — normalization (string | ToolResult → ToolResult) happens once
+        // at the executeTool boundary. Direct handler callers get back exactly what
+        // `execute` returned (a string in the common case → backward compatible).
+        return definition.execute(args, context);
+    };
+    return {
+        name: functionName,
+        definition: openaiDefinition,
+        handler,
+    };
+}
+// ── registerTool ──────────────────────────────────────────────────────
+/**
+ * Register a tool module in the global tool registry.
+ *
+ * @param module  A `ToolModule` to add to the registry
+ */
+export function registerTool(module) {
+    if (registry.some(t => t.definition.function.name === module.definition.function.name)) {
+        console.warn(`[tool-executor] Duplicate tool registration ignored: ${module.definition.function.name}`);
+        return;
+    }
+    registry.push(module);
+}
+// ── executeTool ───────────────────────────────────────────────────────
+/**
+ * Coerce a tool handler's `string | ToolResult` return into a `ToolResult`.
+ * Plain strings (the common case) become `{ output, success: true }` with no
+ * metadata. Structured ToolResults pass through with `metadata` preserved.
+ */
+export function normalizeToolResult(raw) {
+    if (typeof raw === "string")
+        return { output: raw, success: true };
+    if (raw && typeof raw === "object" && "output" in raw)
+        return raw;
+    return { output: String(raw), success: true };
+}
+/**
+ * Execute a tool by name with the given arguments and optional config.
+ *
+ * @param name    Tool function name (e.g. "execute_shell_command")
+ * @param args    Arguments object for the tool
+ * @param config  Optional runtime config passed to the tool handler
+ * @returns       ToolResult — `output` (what the LLM sees) + optional `metadata`
+ *                for adapters (e.g. write_file's FileWriteMetadata for the diff)
+ * @throws        Error if the tool name is not found in the registry
+ */
+export async function executeTool(name, args, config, extra) {
+    const found = registry.find((t) => t.definition.function.name === name);
+    if (!found) {
+        throw new Error(`Unknown tool "${name}". Available: ${registry
+            .map((t) => t.definition.function.name)
+            .join(", ")}`);
+    }
+    const raw = await found.handler(args, config, extra);
+    return normalizeToolResult(raw);
+}
+// ── getToolGroup ─────────────────────────────────────────────────────
+/**
+ * Return the built-in tool definitions belonging to a named group.
+ *
+ * @param group  One of "core", "comm", "advanced", or "all"
+ * @returns      Array of OpenAI function definitions for the matching tools
+ * @throws       Error if the group name is not recognised
+ */
+export function getToolGroup(group) {
+    let names;
+    switch (group) {
+        case "core":
+            names = CORE_TOOLS;
+            break;
+        case "comm":
+            names = COMM_TOOLS;
+            break;
+        case "advanced":
+            names = ADVANCED_TOOLS;
+            break;
+        case "all":
+            names = ALL_TOOLS;
+            break;
+        default:
+            throw new Error(`Unknown tool group "${group}". Valid groups: core, comm, advanced, all`);
+    }
+    const defs = [];
+    for (const name of names) {
+        const found = registry.find((t) => t.definition.function.name === name);
+        if (found) {
+            defs.push(found.definition);
+        }
+    }
+    return defs;
+}
+/**
+ * Resolve a mixed array of tool references into concrete OpenAI function
+ * definitions ready to send to the LLM.
+ *
+ * Accepted input shapes:
+ *  - `"all"`                     — expands to all built-in tools
+ *  - `"core"` / `"comm"` / `"advanced"` — expands to the named group
+ *  - A built-in tool name string — looked up from the internal registry
+ *  - A `UserToolDefinition` object   — converted via `tool()` factory
+ *
+ * @param tools  Array of tool references (defaults to all built-in tools)
+ * @returns      Deduplicated array of OpenAI function definitions
+ * @throws       Error if a string name is not found in the built-in registry
+ */
+export function resolveTools(tools) {
+    const inputs = tools ?? ["all"];
+    const seen = new Set();
+    const result = [];
+    for (const input of inputs) {
+        // String reference — group name or built-in tool name
+        if (typeof input === "string") {
+            // Group expansion
+            if (input === "all" || input === "core" || input === "comm" || input === "advanced") {
+                const groupDefs = getToolGroup(input);
+                for (const def of groupDefs) {
+                    const name = def.function.name;
+                    if (!seen.has(name)) {
+                        seen.add(name);
+                        result.push(def);
+                    }
+                }
+                continue;
+            }
+            // Individual built-in tool lookup
+            const found = registry.find((t) => t.definition.function.name === input);
+            if (!found) {
+                throw new Error(`Unknown tool "${input}". Available: ${registry
+                    .map((t) => t.definition.function.name)
+                    .join(", ")}`);
+            }
+            const name = found.definition.function.name;
+            if (!seen.has(name)) {
+                seen.add(name);
+                result.push(found.definition);
+            }
+            continue;
+        }
+        // ToolDefinition object — convert via factory
+        const module = tool(input);
+        const name = module.definition.function.name;
+        if (!seen.has(name)) {
+            seen.add(name);
+            result.push(module.definition);
+        }
+    }
+    return result;
+}