zoe-agent 0.3.1

package/dist/adapters/sdk/index.js

@@ -0,0 +1,209 @@
+/**
+ * Zoe SDK — Public entry point
+ *
+ * Exports `generateText`, `streamText`, `createAgent`, and all public types,
+ * tool factories, provider helpers, and skill utilities.
+ */
+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 { runAgentLoop } from "../../core/agent-loop.js";
+import { generateId, now, toZoeError, } from "../../core/message-convert.js";
+import { homedir } from 'os';
+import * as path from 'path';
+// ── Re-exports ───────────────────────────────────────────────────────────
+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";
+// Re-export middleware pipeline
+export { compose, loggingMiddleware, rateLimitMiddleware, authMiddleware, } from "../../core/index.js";
+// Gateway (lazy — only loaded when used)
+export const gateway = {
+    async createGateway(config, settingsAdapter) {
+        const { createGateway } = await import('../../gateway/index.js');
+        const { GatewaySettingsAdapter: Adapter } = await import('../../gateway/settings-adapter.js');
+        const adapter = settingsAdapter ?? new Adapter(process.env.ZOE_GATEWAY_DIR ?? path.join(homedir(), '.zoe'));
+        if (!settingsAdapter)
+            await adapter.initialize();
+        return createGateway(config, adapter);
+    },
+};
+export { createPersistenceBackend, registerBackend, createSessionStore, createMemoryStore, } from "../../core/session-store.js";
+// ── generateText ─────────────────────────────────────────────────────────
+/**
+ * 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 async function generateText(prompt, options) {
+    const opts = options ?? {};
+    const maxSteps = opts.maxSteps ?? 10;
+    // Resolve provider
+    const { provider: llmProvider, model } = await getProvider(opts.provider, opts.model);
+    // Resolve tools
+    const toolDefs = opts.tools ? resolveTools(opts.tools) : getAllToolDefinitions();
+    // Hooks
+    const hooks = createHookExecutor(opts.hooks);
+    // Build message list
+    const messages = [];
+    messages.push({
+        id: generateId(),
+        role: "user",
+        content: prompt,
+        timestamp: now(),
+    });
+    // Run the agent loop
+    const result = await runAgentLoop({
+        provider: llmProvider,
+        model,
+        messages,
+        toolDefs,
+        systemPrompt: opts.systemPrompt,
+        maxSteps,
+        hooks,
+        signal: opts.signal,
+        config: opts.config,
+        metadata: opts.metadata,
+        middleware: opts.middleware,
+        approveTool: opts.approveTool,
+        permissionLevel: opts.permissionLevel,
+    });
+    // Get the final text
+    const lastAssistant = [...result.messages]
+        .reverse()
+        .find((m) => m.role === "assistant" && m.content);
+    const text = lastAssistant?.content ?? "";
+    const genResult = {
+        text,
+        steps: result.steps,
+        toolCalls: result.toolCalls,
+        usage: result.usage,
+        finishReason: result.finishReason,
+        messages: result.messages,
+    };
+    await hooks.onFinish(genResult);
+    return genResult;
+}
+// ── streamText ───────────────────────────────────────────────────────────
+/**
+ * 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 async function streamText(prompt, options) {
+    const opts = options ?? {};
+    const maxSteps = opts.maxSteps ?? 10;
+    // Resolve provider
+    const { provider: llmProvider, model } = await getProvider(opts.provider, opts.model);
+    // Resolve tools
+    const toolDefs = opts.tools ? resolveTools(opts.tools) : getAllToolDefinitions();
+    // Hooks — merge stream-level callbacks with any base hooks
+    const mergedHooks = { ...opts.hooks };
+    const hooks = createHookExecutor(mergedHooks);
+    // Build message list
+    const messages = [];
+    messages.push({
+        id: generateId(),
+        role: "user",
+        content: prompt,
+        timestamp: now(),
+    });
+    // Abort controller
+    const abortController = new AbortController();
+    // Stream manager handles queues, async iterables, and SSE
+    const stream = new StreamManager();
+    // Run loop in background
+    (async () => {
+        try {
+            const result = await runAgentLoop({
+                provider: llmProvider,
+                model,
+                messages,
+                toolDefs,
+                systemPrompt: opts.systemPrompt,
+                maxSteps,
+                hooks,
+                signal: abortController.signal,
+                config: opts.config,
+                metadata: opts.metadata,
+                middleware: opts.middleware,
+                approveTool: opts.approveTool,
+                permissionLevel: opts.permissionLevel,
+                onStep: (step) => {
+                    if (opts.onStep)
+                        opts.onStep(step);
+                    if (step.type === "text" && step.content) {
+                        if (opts.onText)
+                            opts.onText(step.content);
+                        stream.enqueueText(step.content);
+                    }
+                    if (step.type === "tool_call" && step.toolCall) {
+                        if (opts.onToolCall) {
+                            opts.onToolCall({ name: step.toolCall.name, args: step.toolCall.args, callId: step.toolCall.id });
+                        }
+                        if (opts.onToolResult) {
+                            opts.onToolResult({ callId: step.toolCall.id, output: step.toolCall.result, success: true });
+                        }
+                    }
+                    stream.enqueueStep(step);
+                },
+            });
+            // fullText: join all text deltas that were enqueued
+            const allText = result.steps
+                .filter((s) => s.type === "text")
+                .map((s) => s.content ?? "")
+                .join("");
+            stream.resolveText(allText);
+            stream.resolveUsage(result.usage);
+            stream.resolveFinish(result.finishReason);
+        }
+        catch (err) {
+            const zoeErr = toZoeError(err, "PROVIDER_ERROR");
+            if (opts.onError)
+                opts.onError(zoeErr);
+            stream.resolveText("");
+            stream.resolveUsage({ promptTokens: 0, completionTokens: 0, totalTokens: 0, cost: 0 });
+            stream.resolveFinish("error");
+        }
+        finally {
+            stream.complete();
+        }
+    })();
+    return {
+        textStream: stream.textStream,
+        steps: stream.stepsStream,
+        fullText: stream.fullText,
+        usage: stream.usage,
+        finishReason: stream.finishReason,
+        abort: () => abortController.abort(),
+        toResponse: () => stream.toResponse(),
+        toSSEStream: () => stream.toSSEStream(),
+    };
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Zoe SDK — Settings Facade
+ *
+ * Wraps SettingsManager for SDK consumers.
+ * Import via `import { settings } from 'zoe-agent'`.
+ */
+import { SettingsError, SettingValue, SettingEntry } from '../../core/settings-manager.js';
+export declare const settings: {
+    get(dotKey: string): SettingValue;
+    set(dotKey: string, value: string): Promise<void>;
+    apply(updates: Record<string, string>): Promise<void>;
+    list(): SettingEntry[];
+    listByCategory(): Record<string, SettingEntry[]>;
+    onChange(callback: (changedKeys: string[]) => void): () => void;
+    reset(dotKey: string): Promise<void>;
+    resetAll(): Promise<void>;
+};
+export { SettingsError };

package/dist/adapters/sdk/settings.js

@@ -0,0 +1,57 @@
+/**
+ * Zoe SDK — Settings Facade
+ *
+ * Wraps SettingsManager for SDK consumers.
+ * Import via `import { settings } from 'zoe-agent'`.
+ */
+import { SettingsManager, SettingsError, } from '../../core/settings-manager.js';
+import { loadMergedConfig, loadJsonConfig, getConfigPaths, applyEnvOverrides, } from '../../core/config.js';
+// ── Singleton ─────────────────────────────────────────────────────────────
+let manager = null;
+function getManager() {
+    if (!manager) {
+        const config = applyEnvOverrides(loadMergedConfig());
+        const paths = getConfigPaths();
+        const projectResult = loadJsonConfig(paths.local);
+        const globalResult = loadJsonConfig(paths.global);
+        manager = new SettingsManager({
+            config,
+            projectConfigPath: paths.local,
+            globalConfigPath: paths.global,
+            projectConfig: projectResult.config,
+            globalConfig: globalResult.config,
+        });
+    }
+    return manager;
+}
+// ── Public API ────────────────────────────────────────────────────────────
+export const settings = {
+    get(dotKey) {
+        return getManager().get(dotKey);
+    },
+    async set(dotKey, value) {
+        return getManager().set(dotKey, value);
+    },
+    async apply(updates) {
+        const m = getManager();
+        for (const [key, value] of Object.entries(updates)) {
+            await m.set(key, value);
+        }
+    },
+    list() {
+        return getManager().list();
+    },
+    listByCategory() {
+        return getManager().listByCategory();
+    },
+    onChange(callback) {
+        return getManager().onChange(callback);
+    },
+    async reset(dotKey) {
+        return getManager().reset(dotKey);
+    },
+    async resetAll() {
+        return getManager().resetAll();
+    },
+};
+export { SettingsError };

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

@@ -0,0 +1,7 @@
+/**
+ * Zoe SDK — Tool utilities (re-export layer)
+ *
+ * All tool registry, resolution, and factory logic lives in core/tool-executor.
+ * This file re-exports for backward compatibility.
+ */
+export { CORE_TOOLS, COMM_TOOLS, ADVANCED_TOOLS, ALL_TOOLS, tool, resolveTools, getToolGroup, registerTool, executeTool, getAllToolDefinitions, } from "../../core/tool-executor.js";

package/dist/adapters/sdk/tools.js

@@ -0,0 +1,13 @@
+/**
+ * Zoe SDK — Tool utilities (re-export layer)
+ *
+ * All tool registry, resolution, and factory logic lives in core/tool-executor.
+ * This file re-exports for backward compatibility.
+ */
+export { 
+// Tool group constants
+CORE_TOOLS, COMM_TOOLS, ADVANCED_TOOLS, ALL_TOOLS, 
+// Factory and resolution
+tool, resolveTools, getToolGroup, 
+// Registry and execution
+registerTool, executeTool, getAllToolDefinitions, } from "../../core/tool-executor.js";

package/dist/adapters/server/auth.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Zoe Server — API Key Authentication
+ *
+ * Generates, validates, and manages API keys for server access.
+ * Keys are stored in ~/.zoe/server-keys.json with associated scopes.
+ */
+import type { IncomingMessage } from "http";
+export type KeyScope = "agent:run" | "agent:read" | "admin";
+export interface ApiKeyEntry {
+    key: string;
+    scopes: KeyScope[];
+    created: string;
+    label: string;
+}
+/**
+ * Generate a new API key with the format `sk_zoe_{random}`.
+ * Optionally persist it to the key store file.
+ */
+export declare function generateApiKey(scopes?: KeyScope[], options?: {
+    label?: string;
+    filePath?: string;
+}): ApiKeyEntry;
+/**
+ * Validate an API key string against the stored keys.
+ * Returns the matching entry if valid, or null if not found.
+ */
+export declare function validateApiKey(key: string, options?: {
+    filePath?: string;
+}): ApiKeyEntry | null;
+/**
+ * Extract and validate an API key from an incoming HTTP request.
+ *
+ * For REST requests: checks `X-Zoe-API-Key` header first,
+ * then `Authorization: Bearer sk_zoe_...`.
+ * For WebSocket upgrades: checks the `token` query parameter.
+ *
+ * Returns the ApiKeyEntry if valid, or null if authentication fails.
+ */
+export declare function authMiddleware(req: IncomingMessage): ApiKeyEntry | null;
+/**
+ * Load all API keys from the key store file.
+ * Returns an array of ApiKeyEntry objects.
+ */
+export declare function loadApiKeys(filePath?: string): ApiKeyEntry[];
+/**
+ * Delete an API key from the store.
+ * Returns true if the key was found and removed.
+ */
+export declare function revokeApiKey(key: string, filePath?: string): boolean;
+/**
+ * Check whether a given key entry has a specific scope.
+ */
+export declare function hasScope(entry: ApiKeyEntry, scope: KeyScope): boolean;

package/dist/adapters/server/auth.js

@@ -0,0 +1,168 @@
+/**
+ * Zoe Server — API Key Authentication
+ *
+ * Generates, validates, and manages API keys for server access.
+ * Keys are stored in ~/.zoe/server-keys.json with associated scopes.
+ */
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+// ── Defaults ───────────────────────────────────────────────────────────
+const DEFAULT_KEY_PATH = path.join(os.homedir(), ".zoe", "server-keys.json");
+// ── In-memory cache ────────────────────────────────────────────────────
+let cachedKeys = null;
+let cacheMtimeMs = 0;
+// ── Key store I/O ──────────────────────────────────────────────────────
+function readStore(filePath) {
+    try {
+        const raw = fs.readFileSync(filePath, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return { keys: [] };
+    }
+}
+function writeStore(store, filePath) {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(filePath, JSON.stringify(store, null, 2), {
+        mode: 0o600,
+    });
+}
+// ── Cache helpers ──────────────────────────────────────────────────────
+function invalidateCache() {
+    cachedKeys = null;
+    cacheMtimeMs = 0;
+}
+function loadCache(filePath) {
+    try {
+        const stat = fs.statSync(filePath);
+        if (cachedKeys && stat.mtimeMs === cacheMtimeMs) {
+            return cachedKeys;
+        }
+    }
+    catch {
+        // File may not exist yet — rebuild cache
+    }
+    const store = readStore(filePath);
+    const map = new Map();
+    for (const entry of store.keys) {
+        map.set(entry.key, entry);
+    }
+    cachedKeys = map;
+    try {
+        cacheMtimeMs = fs.statSync(filePath).mtimeMs;
+    }
+    catch {
+        cacheMtimeMs = 0;
+    }
+    return map;
+}
+// ── Public API ─────────────────────────────────────────────────────────
+/**
+ * Generate a new API key with the format `sk_zoe_{random}`.
+ * Optionally persist it to the key store file.
+ */
+export function generateApiKey(scopes = ["agent:run"], options) {
+    const random = crypto.randomBytes(32).toString("hex");
+    const key = `sk_zoe_${random}`;
+    const entry = {
+        key,
+        scopes,
+        created: new Date().toISOString(),
+        label: options?.label ?? "generated",
+    };
+    // Persist to disk
+    const filePath = options?.filePath ?? DEFAULT_KEY_PATH;
+    const store = readStore(filePath);
+    store.keys.push(entry);
+    writeStore(store, filePath);
+    invalidateCache();
+    return entry;
+}
+/**
+ * Validate an API key string against the stored keys.
+ * Returns the matching entry if valid, or null if not found.
+ */
+export function validateApiKey(key, options) {
+    if (!key || !key.startsWith("sk_zoe_")) {
+        return null;
+    }
+    const filePath = options?.filePath ?? DEFAULT_KEY_PATH;
+    const cache = loadCache(filePath);
+    return cache.get(key) ?? null;
+}
+/**
+ * Extract and validate an API key from an incoming HTTP request.
+ *
+ * For REST requests: checks `X-Zoe-API-Key` header first,
+ * then `Authorization: Bearer sk_zoe_...`.
+ * For WebSocket upgrades: checks the `token` query parameter.
+ *
+ * Returns the ApiKeyEntry if valid, or null if authentication fails.
+ */
+export function authMiddleware(req) {
+    let key;
+    // 1. Check X-Zoe-API-Key header
+    key = req.headers["x-zoe-api-key"];
+    // 2. Check Authorization: Bearer sk_zoe_...
+    if (!key) {
+        const auth = req.headers.authorization;
+        if (auth?.startsWith("Bearer ")) {
+            const token = auth.slice(7).trim();
+            if (token.startsWith("sk_zoe_")) {
+                key = token;
+            }
+        }
+    }
+    // 3. Check query parameter (for WebSocket upgrades)
+    if (!key && req.url) {
+        try {
+            const url = new URL(req.url, `http://${req.headers.host ?? "localhost"}`);
+            const tokenParam = url.searchParams.get("token");
+            if (tokenParam?.startsWith("sk_zoe_")) {
+                key = tokenParam;
+            }
+        }
+        catch {
+            // Malformed URL — ignore
+        }
+    }
+    if (!key) {
+        return null;
+    }
+    return validateApiKey(key);
+}
+/**
+ * Load all API keys from the key store file.
+ * Returns an array of ApiKeyEntry objects.
+ */
+export function loadApiKeys(filePath) {
+    const resolved = filePath ?? DEFAULT_KEY_PATH;
+    const store = readStore(resolved);
+    return store.keys;
+}
+/**
+ * Delete an API key from the store.
+ * Returns true if the key was found and removed.
+ */
+export function revokeApiKey(key, filePath) {
+    const resolved = filePath ?? DEFAULT_KEY_PATH;
+    const store = readStore(resolved);
+    const index = store.keys.findIndex((e) => e.key === key);
+    if (index === -1)
+        return false;
+    store.keys.splice(index, 1);
+    writeStore(store, resolved);
+    invalidateCache();
+    return true;
+}
+/**
+ * Check whether a given key entry has a specific scope.
+ */
+export function hasScope(entry, scope) {
+    return entry.scopes.includes(scope);
+}

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

@@ -0,0 +1,40 @@
+/**
+ * Zoe Remote Server — Entry Point
+ *
+ * Creates an HTTP server with REST endpoints and WebSocket support
+ * for real-time streaming conversations with LLM providers.
+ *
+ * Default port: 7337
+ */
+import * as http from "http";
+import type { PermissionLevel } from "../../core/types.js";
+export interface ServerOptions {
+    /** Port to listen on (default: ZOE_PORT, PORT, or 7337) */
+    port?: number;
+    /** Host to bind to (default: "0.0.0.0") */
+    host?: string;
+    /** Enable CORS headers (default: true) */
+    cors?: boolean;
+    /** Session TTL in seconds (default: 86400 = 24 hours) */
+    sessionTTL?: number;
+    /** Default permission level for REST endpoints (default: "moderate") */
+    permissionLevel?: PermissionLevel;
+    /** Maximum permission level clients can request (caps WebSocket messages) */
+    maxPermissionLevel?: PermissionLevel;
+}
+/**
+ * Initialize the skill registry and cache the skill metadata list.
+ * Called once during server startup.
+ */
+export declare function initializeSkills(): Promise<void>;
+/**
+ * Create and return the Zoe HTTP server (not yet listening).
+ *
+ * This sets up REST endpoints, WebSocket upgrade handling,
+ * session management, and CORS support.
+ */
+export declare function createServer(options?: ServerOptions): Promise<http.Server>;
+/**
+ * Create and start listening. Returns the running server.
+ */
+export declare function startServer(options?: ServerOptions): Promise<http.Server>;