zoe-agent 0.3.1

package/dist/adapters/cli/tui/types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * TUI feed types — the discriminated union of feed entries.
+ *
+ * `use-feed` holds an array of `FeedEntry`; each `kind` maps to a render
+ * component. Entries are immutable once complete (so Ink's `<Static>` can
+ * render history efficiently); only the currently-streaming entry mutates.
+ *
+ * The shapes derive from Core's `StepResult` (text / tool_call) plus the
+ * adapter-level concerns the readline REPL handles inline: user input,
+ * permission approval, and errors.
+ */
+export interface UserMessageEntry {
+    id: string;
+    kind: 'user';
+    content: string;
+}
+export interface AssistantMessageEntry {
+    id: string;
+    kind: 'assistant';
+    content: string;
+}
+export interface ToolCallEntry {
+    id: string;
+    kind: 'tool';
+    name: string;
+    args: Record<string, unknown>;
+    status: 'running' | 'ok' | 'fail';
+    output?: string;
+    durationMs?: number;
+    /** Tool-specific structured payload (e.g. write_file's FileWriteMetadata)
+     *  for richer rendering. Opaque here; parsed at the component boundary. */
+    metadata?: unknown;
+}
+export interface ErrorEntry {
+    id: string;
+    kind: 'error';
+    message: string;
+}
+export interface InfoEntry {
+    id: string;
+    kind: 'info';
+    content: string;
+}
+export interface LogoEntry {
+    id: string;
+    kind: 'logo';
+}
+export type FeedEntry = UserMessageEntry | AssistantMessageEntry | ToolCallEntry | ErrorEntry | InfoEntry | LogoEntry;
+type DistributiveOmit<T, K extends keyof any> = T extends unknown ? Omit<T, K> : never;
+/** A feed entry without its generated id — the input shape for `appendEntry`. */
+export type FeedEntryInput = DistributiveOmit<FeedEntry, 'id'>;
+export {};

package/dist/adapters/cli/tui/types.js

@@ -0,0 +1,12 @@
+/**
+ * TUI feed types — the discriminated union of feed entries.
+ *
+ * `use-feed` holds an array of `FeedEntry`; each `kind` maps to a render
+ * component. Entries are immutable once complete (so Ink's `<Static>` can
+ * render history efficiently); only the currently-streaming entry mutates.
+ *
+ * The shapes derive from Core's `StepResult` (text / tool_call) plus the
+ * adapter-level concerns the readline REPL handles inline: user input,
+ * permission approval, and errors.
+ */
+export {};

package/dist/adapters/sdk/agent.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Zoe SDK — createAgent()
+ *
+ * A persistent agent with session memory, provider switching, and abort support.
+ * Wraps the LLMProvider directly (not the CLI-oriented Agent class) so results
+ * are structured rather than printed to the console.
+ */
+import type { AgentCreateOptions, SdkAgent } from "../../core/types.js";
+/**
+ * Create a persistent agent with session memory, provider switching,
+ * and abort support.
+ *
+ * @example
+ * ```ts
+ * const agent = await createAgent({ model: "gpt-4o" });
+ * const result = await agent.chat("Hello!");
+ * console.log(result.text);
+ * ```
+ */
+export declare function createAgent(options?: AgentCreateOptions): Promise<SdkAgent>;

package/dist/adapters/sdk/agent.js

@@ -0,0 +1,356 @@
+/**
+ * Zoe SDK — createAgent()
+ *
+ * A persistent agent with session memory, provider switching, and abort support.
+ * Wraps the LLMProvider directly (not the CLI-oriented Agent class) so results
+ * are structured rather than printed to the console.
+ */
+import { getProvider } from "../../core/provider-resolver.js";
+import { createHookExecutor } from "../../core/hooks.js";
+import { StreamManager } from "../../core/stream-manager.js";
+import { resolveTools, getAllToolDefinitions } from "./tools.js";
+import { createPersistenceBackend, persistSession } from "../../core/session-store.js";
+import { runAgentLoop } from "../../core/agent-loop.js";
+import { generateId, now, toZoeError, } from "../../core/message-convert.js";
+// ── Session persistence helpers ──────────────────────────────────────────
+/**
+ * Adapt a legacy `SessionStore` (save/load takes messages) to the
+ * `PersistenceBackend` interface (save/load takes full SessionData).
+ * If the object already has the `PersistenceBackend` signature, it passes through.
+ */
+function wrapAsPersistenceBackend(store) {
+    if ("__persistenceBackend" in store && store.__persistenceBackend === true) {
+        return store;
+    }
+    const s = store;
+    return {
+        __persistenceBackend: true,
+        save: async (id, data) => {
+            await s.save(id, data.messages);
+        },
+        load: async (id) => {
+            const messages = await s.load(id);
+            if (!messages)
+                return null;
+            return { id, messages, createdAt: Date.now(), updatedAt: Date.now() };
+        },
+        delete: s.delete.bind(s),
+        list: s.list.bind(s),
+    };
+}
+// ── createAgent ──────────────────────────────────────────────────────────
+/**
+ * Create a persistent agent with session memory, provider switching,
+ * and abort support.
+ *
+ * @example
+ * ```ts
+ * const agent = await createAgent({ model: "gpt-4o" });
+ * const result = await agent.chat("Hello!");
+ * console.log(result.text);
+ * ```
+ */
+export async function createAgent(options) {
+    const opts = options ?? {};
+    // Resolve provider
+    let { provider: llmProvider, model } = await getProvider(opts.provider, opts.model);
+    // System prompt
+    let systemPrompt = opts.systemPrompt ?? "You are a helpful assistant.";
+    // Tools
+    let toolDefs = opts.tools ? resolveTools(opts.tools) : getAllToolDefinitions();
+    // Hooks
+    const hookExecutor = createHookExecutor(opts.hooks);
+    // State
+    const messages = [];
+    const sessionId = generateId();
+    let activeAbortController = new AbortController();
+    // Concurrency guard — only one chat/chatStream at a time
+    let lock = Promise.resolve();
+    let releaseLock = null;
+    function acquire() {
+        const prev = lock;
+        lock = new Promise((r) => { releaseLock = r; });
+        return prev;
+    }
+    function release() {
+        releaseLock?.();
+        releaseLock = null;
+    }
+    // Cumulative usage
+    const cumulativeUsage = {
+        totalPromptTokens: 0,
+        totalCompletionTokens: 0,
+        totalCost: 0,
+        requestCount: 0,
+    };
+    // Session store
+    let backend = null;
+    if (opts.persist) {
+        if (typeof opts.persist === "string") {
+            // Legacy: string path → file backend
+            backend = createPersistenceBackend({ type: "file", path: opts.persist });
+        }
+        else if ("type" in opts.persist && typeof opts.persist.type === "string") {
+            // PersistenceConfig object
+            backend = createPersistenceBackend(opts.persist);
+        }
+        else if ("save" in opts.persist && "load" in opts.persist) {
+            // Already a PersistenceBackend or legacy SessionStore — use directly
+            backend = wrapAsPersistenceBackend(opts.persist);
+        }
+        // Try loading existing session
+        if (backend) {
+            const existing = await backend.load(sessionId);
+            if (existing) {
+                messages.push(...existing.messages);
+            }
+        }
+    }
+    // Add initial system prompt if no messages exist
+    if (messages.length === 0 && systemPrompt) {
+        messages.push({
+            id: generateId(),
+            role: "system",
+            content: systemPrompt,
+            timestamp: now(),
+        });
+    }
+    // ── Helper: persist messages ────────────────────────────────────────────
+    async function persistMessages() {
+        if (backend) {
+            await persistSession(backend, sessionId, messages);
+        }
+    }
+    // ── chat() ──────────────────────────────────────────────────────────────
+    async function chat(userMessage) {
+        await acquire();
+        try {
+            // Reset abort controller for this call
+            activeAbortController = new AbortController();
+            // Add user message
+            messages.push({
+                id: generateId(),
+                role: "user",
+                content: userMessage,
+                timestamp: now(),
+            });
+            const maxSteps = opts.maxSteps ?? 10;
+            const result = await runAgentLoop({
+                provider: llmProvider,
+                model: model,
+                messages,
+                toolDefs,
+                systemPrompt: systemPrompt,
+                maxSteps,
+                hooks: hookExecutor,
+                signal: activeAbortController.signal,
+                config: opts.config,
+                metadata: opts.metadata,
+                middleware: opts.middleware,
+                approveTool: opts.approveTool,
+                permissionLevel: opts.permissionLevel,
+            });
+            // Update cumulative usage from result
+            cumulativeUsage.totalPromptTokens += result.usage.promptTokens;
+            cumulativeUsage.totalCompletionTokens += result.usage.completionTokens;
+            cumulativeUsage.totalCost += result.usage.cost;
+            cumulativeUsage.requestCount += 1;
+            // Persist
+            await persistMessages();
+            // Get the final text
+            const lastAssistant = [...messages]
+                .reverse()
+                .find((m) => m.role === "assistant" && m.content);
+            const text = lastAssistant?.content ?? "";
+            return {
+                text,
+                toolCalls: result.toolCalls,
+                usage: result.usage,
+            };
+        }
+        finally {
+            release();
+        }
+    }
+    // ── chatStream() ────────────────────────────────────────────────────────
+    async function chatStream(message, streamOptions) {
+        await acquire();
+        try {
+            const streamAbort = new AbortController();
+            activeAbortController = streamAbort;
+            const mergedHooks = {
+                ...opts.hooks,
+                ...streamOptions,
+            };
+            const streamHookExecutor = createHookExecutor(mergedHooks);
+            // Add user message
+            messages.push({
+                id: generateId(),
+                role: "user",
+                content: message,
+                timestamp: now(),
+            });
+            const maxSteps = streamOptions?.maxSteps ?? opts.maxSteps ?? 10;
+            // Stream manager handles queues, async iterables, and SSE
+            const stream = new StreamManager();
+            // Run the loop in the background — lock released in finally when done
+            (async () => {
+                try {
+                    const result = await runAgentLoop({
+                        provider: llmProvider,
+                        model: model,
+                        messages,
+                        toolDefs,
+                        systemPrompt: systemPrompt,
+                        maxSteps,
+                        hooks: streamHookExecutor,
+                        signal: streamAbort.signal,
+                        config: opts.config,
+                        metadata: opts.metadata,
+                        middleware: opts.middleware,
+                        approveTool: opts.approveTool,
+                        permissionLevel: opts.permissionLevel,
+                        stream: true,
+                        onStep: (step) => {
+                            if (streamOptions?.onStep)
+                                streamOptions.onStep(step);
+                            // Streaming emits text_delta; non-streaming emits one complete
+                            // 'text'. Both flow to consumers as text deltas via enqueueText.
+                            if ((step.type === "text" || step.type === "text_delta") && step.content) {
+                                if (streamOptions?.onText)
+                                    streamOptions.onText(step.content);
+                                stream.enqueueText(step.content);
+                            }
+                            if (step.type === "tool_call" && step.toolCall) {
+                                if (streamOptions?.onToolCall) {
+                                    streamOptions.onToolCall({
+                                        name: step.toolCall.name,
+                                        args: step.toolCall.args,
+                                        callId: step.toolCall.id,
+                                    });
+                                }
+                                if (streamOptions?.onToolResult) {
+                                    streamOptions.onToolResult({
+                                        callId: step.toolCall.id,
+                                        output: step.toolCall.result,
+                                        success: true,
+                                    });
+                                }
+                            }
+                            stream.enqueueStep(step);
+                        },
+                    });
+                    // Update cumulative usage from result
+                    cumulativeUsage.totalPromptTokens += result.usage.promptTokens;
+                    cumulativeUsage.totalCompletionTokens += result.usage.completionTokens;
+                    cumulativeUsage.totalCost += result.usage.cost;
+                    cumulativeUsage.requestCount += 1;
+                    // Derive final text from the message history (robust to streaming,
+                    // where steps contain text_delta, not a complete 'text' step).
+                    const lastAssistant = [...messages]
+                        .reverse()
+                        .find((m) => m.role === "assistant" && m.content);
+                    const finalText = lastAssistant?.content ?? "";
+                    stream.resolveText(finalText);
+                    stream.resolveUsage(result.usage);
+                    stream.resolveFinish(result.finishReason);
+                }
+                catch (err) {
+                    const zoeErr = toZoeError(err, "PROVIDER_ERROR");
+                    if (streamOptions?.onError)
+                        streamOptions.onError(zoeErr);
+                    stream.resolveText("");
+                    stream.resolveUsage({ promptTokens: 0, completionTokens: 0, totalTokens: 0, cost: 0 });
+                    stream.resolveFinish("error");
+                }
+                finally {
+                    stream.complete();
+                    await persistMessages();
+                    release();
+                }
+            })();
+            return {
+                textStream: stream.textStream,
+                steps: stream.stepsStream,
+                fullText: stream.fullText,
+                usage: stream.usage,
+                finishReason: stream.finishReason,
+                abort: () => streamAbort.abort(),
+                toResponse: () => stream.toResponse(),
+                toSSEStream: () => stream.toSSEStream(),
+            };
+        }
+        catch (_err) {
+            release();
+            throw _err;
+        }
+    }
+    // ── switchProvider() ────────────────────────────────────────────────────
+    async function switchProvider(providerType, newModel) {
+        const result = await getProvider(providerType, newModel);
+        llmProvider = result.provider;
+        model = result.model;
+    }
+    // ── setSystemPrompt() ───────────────────────────────────────────────────
+    function setSystemPrompt(prompt) {
+        systemPrompt = prompt;
+        // Replace existing system message or add new one
+        const sysIdx = messages.findIndex((m) => m.role === "system");
+        if (sysIdx >= 0) {
+            messages[sysIdx] = {
+                id: messages[sysIdx].id,
+                role: "system",
+                content: prompt,
+                timestamp: now(),
+            };
+        }
+        else {
+            messages.unshift({
+                id: generateId(),
+                role: "system",
+                content: prompt,
+                timestamp: now(),
+            });
+        }
+    }
+    // ── setTools() ──────────────────────────────────────────────────────────
+    function setTools(tools) {
+        toolDefs = resolveTools(tools);
+    }
+    // ── abort() ─────────────────────────────────────────────────────────────
+    function abort() {
+        activeAbortController.abort();
+    }
+    // ── clear() ─────────────────────────────────────────────────────────────
+    function clear() {
+        messages.length = 0;
+        if (systemPrompt) {
+            messages.push({
+                id: generateId(),
+                role: "system",
+                content: systemPrompt,
+                timestamp: now(),
+            });
+        }
+    }
+    // ── getHistory() ────────────────────────────────────────────────────────
+    function getHistory() {
+        return [...messages];
+    }
+    // ── getUsage() ──────────────────────────────────────────────────────────
+    function getUsage() {
+        return { ...cumulativeUsage };
+    }
+    // ── Return the SdkAgent interface ───────────────────────────────────────
+    return {
+        chat,
+        chatStream,
+        switchProvider,
+        setSystemPrompt,
+        setTools,
+        abort,
+        clear,
+        getHistory,
+        getUsage,
+    };
+}

package/dist/adapters/sdk/http.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Zoe SDK — HTTP response helpers
+ *
+ * Converts StreamTextResult into HTTP-friendly SSE responses
+ * using the Web API Response and ReadableStream interfaces.
+ *
+ * Delegates to StreamManager for SSE generation.
+ */
+import type { StreamTextResult } from "../../core/types.js";
+export interface SSEOptions {
+    headers?: Record<string, string>;
+}
+/**
+ * Formats a single Server-Sent Events message.
+ *
+ * @param event  The SSE event name
+ * @param data   The payload (will be JSON-serialised)
+ * @returns      A string in SSE wire format: `event: ...\ndata: ...\n\n`
+ */
+export declare function createSSEMessage(event: string, data: unknown): string;
+/**
+ * Converts a StreamTextResult into a SSE-formatted ReadableStream.
+ *
+ * Delegates to the StreamManager's toSSEStream() for actual event generation.
+ * The result's toSSEStream() emits events in the correct order:
+ *  - `text`      — incremental text deltas
+ *  - `tool_call` — tool invocations
+ *  - `tool_result` — tool execution results
+ *  - `done`      — final usage and finish reason
+ */
+export declare function toSSEStream(result: StreamTextResult, _options?: SSEOptions): ReadableStream;
+/**
+ * Converts a StreamTextResult into a Web API `Response` with an SSE body.
+ *
+ * Delegates to the StreamManager's toResponse() which sets standard SSE headers:
+ *  - `Content-Type: text/event-stream`
+ *  - `Cache-Control: no-cache`
+ *  - `Connection: keep-alive`
+ *
+ * @param result   The streaming result to convert
+ * @param options  Optional extra headers to merge into the response
+ */
+export declare function toResponse(result: StreamTextResult, options?: SSEOptions): Response;

package/dist/adapters/sdk/http.js

@@ -0,0 +1,61 @@
+/**
+ * Zoe SDK — HTTP response helpers
+ *
+ * Converts StreamTextResult into HTTP-friendly SSE responses
+ * using the Web API Response and ReadableStream interfaces.
+ *
+ * Delegates to StreamManager for SSE generation.
+ */
+// ── SSE helpers ─────────────────────────────────────────────────────────
+/**
+ * Formats a single Server-Sent Events message.
+ *
+ * @param event  The SSE event name
+ * @param data   The payload (will be JSON-serialised)
+ * @returns      A string in SSE wire format: `event: ...\ndata: ...\n\n`
+ */
+export function createSSEMessage(event, data) {
+    return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+}
+// ── toSSEStream ─────────────────────────────────────────────────────────
+/**
+ * Converts a StreamTextResult into a SSE-formatted ReadableStream.
+ *
+ * Delegates to the StreamManager's toSSEStream() for actual event generation.
+ * The result's toSSEStream() emits events in the correct order:
+ *  - `text`      — incremental text deltas
+ *  - `tool_call` — tool invocations
+ *  - `tool_result` — tool execution results
+ *  - `done`      — final usage and finish reason
+ */
+export function toSSEStream(result, _options) {
+    return result.toSSEStream();
+}
+// ── toResponse ──────────────────────────────────────────────────────────
+/**
+ * Converts a StreamTextResult into a Web API `Response` with an SSE body.
+ *
+ * Delegates to the StreamManager's toResponse() which sets standard SSE headers:
+ *  - `Content-Type: text/event-stream`
+ *  - `Cache-Control: no-cache`
+ *  - `Connection: keep-alive`
+ *
+ * @param result   The streaming result to convert
+ * @param options  Optional extra headers to merge into the response
+ */
+export function toResponse(result, options) {
+    if (options?.headers) {
+        // If custom headers are requested, create a new Response wrapping
+        // the StreamManager's SSE stream with merged headers.
+        const body = result.toSSEStream();
+        return new Response(body, {
+            headers: {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+                ...options.headers,
+            },
+        });
+    }
+    return result.toResponse();
+}

package/dist/adapters/sdk/index.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Zoe SDK — Public entry point
+ *
+ * Exports `generateText`, `streamText`, `createAgent`, and all public types,
+ * tool factories, provider helpers, and skill utilities.
+ */
+import type { GenerateTextOptions, GenerateTextResult, StreamTextOptions, StreamTextResult } from "../../core/types.js";
+export { createAgent } from "./agent.js";
+export { tool, CORE_TOOLS, COMM_TOOLS, ADVANCED_TOOLS, ALL_TOOLS } from "./tools.js";
+export { settings, SettingsError } from "./settings.js";
+export { configureProviders, loadProviderConfig, provider } from "../../core/provider-resolver.js";
+export { createSkillProviderSwitcher } from "../../core/skill-invoker.js";
+export type { SSEOptions } from "./http.js";
+export { compose, type PipelineContext, type Middleware, loggingMiddleware, rateLimitMiddleware, authMiddleware, } from "../../core/index.js";
+import type { GatewayConfig } from "../../gateway/types.js";
+import type { GatewaySettingsAdapter } from "../../gateway/settings-adapter.js";
+export declare const gateway: {
+    createGateway(config: GatewayConfig, settingsAdapter?: GatewaySettingsAdapter): Promise<import("../../gateway/gateway.js").MCPGateway | null>;
+};
+export type { ProviderType, MultiProviderConfig, Message, ToolCall, StepResult, Usage, CumulativeUsage, UserToolDefinition, ToolContext, ToolResult, Hooks, GenerateTextOptions, GenerateTextResult, StreamTextOptions, StreamTextResult, AgentCreateOptions, SdkAgent, AgentResponse, SessionStore, SessionData, PersistenceBackend, PersistenceConfig, SkillMetadata, ZoeError, PermissionLevel, ToolRiskCategory, } from "../../core/types.js";
+export { createPersistenceBackend, registerBackend, createSessionStore, createMemoryStore, } from "../../core/session-store.js";
+export type { SkillProviderSwitcher, ProviderSwitcherConfig, } from "../../core/skill-invoker.js";
+/**
+ * Run a one-shot agent loop and return the structured result.
+ *
+ * Creates fresh state for each call (stateless). Handles tool calls
+ * automatically until the provider returns no more tool calls or
+ * `maxSteps` is reached.
+ *
+ * @example
+ * ```ts
+ * const result = await generateText("What is the weather in SF?", {
+ *   tools: ["web_search"],
+ *   maxSteps: 5,
+ * });
+ * console.log(result.text);
+ * ```
+ */
+export declare function generateText(prompt: string, options?: GenerateTextOptions): Promise<GenerateTextResult>;
+/**
+ * Run a one-shot agent loop with streaming callbacks.
+ *
+ * Returns AsyncIterables for text and steps, plus `toResponse()` and
+ * `toSSEStream()` for HTTP server integration.
+ *
+ * Note: The current provider.chat() API returns full responses (not deltas),
+ * so onText receives the complete text at once. Future versions will integrate
+ * with provider-level streaming.
+ *
+ * @example
+ * ```ts
+ * const stream = await streamText("Explain quantum computing", {
+ *   onText: (delta) => process.stdout.write(delta),
+ * });
+ * const finalText = await stream.fullText;
+ * ```
+ */
+export declare function streamText(prompt: string, options?: StreamTextOptions): Promise<StreamTextResult>;