zoe-agent 0.3.1

package/dist/core/types.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Zoe SDK — Shared TypeScript types
+ *
+ * This file is the single source of truth for all SDK interfaces.
+ * Every SDK module imports from here.
+ */
+import type { ZoeError as ZoeErrorType } from "./errors.js";
+import type { Middleware } from "./middleware.js";
+export type ProviderType = "openai" | "anthropic" | "glm" | "openai-compatible";
+export interface MultiProviderConfig {
+    openai?: {
+        apiKey: string;
+        model?: string;
+    };
+    anthropic?: {
+        apiKey: string;
+        model?: string;
+    };
+    glm?: {
+        apiKey: string;
+        model?: string;
+    };
+    "openai-compatible"?: {
+        apiKey: string;
+        baseUrl: string;
+        model?: string;
+    };
+    default: ProviderType;
+}
+export type ToolRiskCategory = "safe" | "edit" | "communications" | "destructive";
+export type PermissionLevel = "strict" | "moderate" | "permissive";
+export interface Message {
+    id: string;
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    toolCalls?: ToolCall[];
+    toolCallId?: string;
+    timestamp: number;
+}
+export interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    result?: string;
+}
+export interface StepResult {
+    type: "text" | "tool_call" | "text_delta" | "tool_progress";
+    content?: string;
+    toolCall?: {
+        id: string;
+        name: string;
+        args: Record<string, unknown>;
+        result: string;
+        duration: number;
+    };
+    /** For tool_progress: identifies which in-flight tool call the chunk belongs to. */
+    toolCallId?: string;
+    /** For tool_progress: the tool name + args (so the UI can render the block). */
+    name?: string;
+    args?: Record<string, unknown>;
+    /** Tool-specific structured payload (e.g. write_file's FileWriteMetadata) for
+     *  adapters to render. Populated only on `tool_call` steps whose handler
+     *  returned a ToolResult with metadata. NEVER enters message history. */
+    metadata?: Record<string, unknown>;
+    timestamp: number;
+}
+export interface Usage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cost: number;
+}
+export interface CumulativeUsage {
+    totalPromptTokens: number;
+    totalCompletionTokens: number;
+    totalCost: number;
+    requestCount: number;
+}
+export interface UserToolDefinition {
+    name?: string;
+    description: string;
+    parameters: unknown;
+    execute: (args: unknown, context: ToolContext) => Promise<string | ToolResult>;
+}
+export interface ToolContext {
+    onUpdate?: (progress: {
+        percentage?: number;
+        message?: string;
+    }) => void;
+    signal?: AbortSignal;
+    config?: Record<string, unknown>;
+}
+export interface ToolResult {
+    output: string;
+    success: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface ApproveToolCall {
+    name: string;
+    args: Record<string, unknown>;
+}
+/**
+ * Adapter-provided callback invoked before every tool execution.
+ * Return `true` to approve, `false` to deny (the tool is skipped
+ * and "User denied tool execution" is returned as the tool output).
+ *
+ * Each adapter implements its own UX:
+ *  - CLI: inquirer prompt (with ESC interrupt suspended)
+ *  - SDK: user-supplied callback or auto-approve
+ *  - Server: WebSocket round-trip to client
+ */
+export type ApproveToolFn = (call: ApproveToolCall) => Promise<boolean>;
+export interface Hooks {
+    beforeToolCall?: (call: {
+        name: string;
+        args: Record<string, unknown>;
+    }) => void | Promise<void>;
+    afterToolCall?: (result: {
+        name: string;
+        output: string;
+        duration: number;
+    }) => void | Promise<void>;
+    onStep?: (step: StepResult) => void | Promise<void>;
+    onError?: (error: ZoeErrorType) => void | Promise<void>;
+    onFinish?: (result: GenerateTextResult) => void | Promise<void>;
+}
+export interface GenerateTextOptions {
+    model?: string;
+    provider?: ProviderType;
+    systemPrompt?: string;
+    tools?: string[] | UserToolDefinition[];
+    skills?: string[];
+    maxSteps?: number;
+    temperature?: number;
+    maxTokens?: number;
+    output?: unknown;
+    hooks?: Hooks;
+    signal?: AbortSignal;
+    config?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    middleware?: Middleware[];
+    approveTool?: ApproveToolFn;
+    permissionLevel?: PermissionLevel;
+}
+export interface GenerateTextResult {
+    text: string;
+    data?: unknown;
+    error?: {
+        message: string;
+        issues: unknown;
+    };
+    steps: StepResult[];
+    toolCalls: ToolCall[];
+    usage: Usage;
+    finishReason: "stop" | "length" | "max_steps" | "error";
+    messages: Message[];
+}
+export interface StreamTextOptions extends GenerateTextOptions {
+    onText?: (delta: string) => void;
+    onToolCall?: (tool: {
+        name: string;
+        args: Record<string, unknown>;
+        callId: string;
+    }) => void;
+    onToolResult?: (result: {
+        callId: string;
+        output: string;
+        success: boolean;
+    }) => void;
+    onStep?: (step: StepResult) => void;
+    onError?: (error: ZoeErrorType) => void;
+}
+export interface StreamTextResult {
+    textStream: AsyncIterable<string>;
+    steps: AsyncIterable<StepResult>;
+    fullText: Promise<string>;
+    usage: Promise<Usage>;
+    finishReason: Promise<string>;
+    abort: () => void;
+    toResponse: () => Response;
+    toSSEStream: () => ReadableStream;
+}
+export interface AgentCreateOptions {
+    model?: string;
+    provider?: ProviderType;
+    systemPrompt?: string;
+    tools?: string[] | UserToolDefinition[];
+    skills?: string[];
+    maxSteps?: number;
+    permissionLevel?: PermissionLevel;
+    persist?: string | PersistenceBackend | PersistenceConfig | SessionStore;
+    hooks?: Hooks;
+    config?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    middleware?: Middleware[];
+    approveTool?: ApproveToolFn;
+}
+export interface SdkAgent {
+    chat(message: string): Promise<AgentResponse>;
+    chatStream(message: string, options?: StreamTextOptions): Promise<StreamTextResult>;
+    switchProvider(provider: ProviderType, model?: string): Promise<void>;
+    setSystemPrompt(prompt: string): void;
+    setTools(tools: string[]): void;
+    abort(): void;
+    clear(): void;
+    getHistory(): Message[];
+    getUsage(): CumulativeUsage;
+}
+export interface AgentResponse {
+    text: string;
+    toolCalls: ToolCall[];
+    usage: Usage;
+}
+/**
+ * Composable persistence backend. Implementations handle raw storage
+ * (file system, Redis, SQLite, etc.). Server-specific metadata (TTL,
+ * apiKeyHash) flows through the `metadata` field on `SessionData`.
+ */
+export interface PersistenceBackend {
+    /** Brand discriminator to distinguish from SessionStore */
+    __persistenceBackend: true;
+    save(id: string, data: SessionData): Promise<void>;
+    load(id: string): Promise<SessionData | null>;
+    delete(id: string): Promise<void>;
+    list(): Promise<string[]>;
+}
+/**
+ * Configuration object for creating a persistence backend via the factory.
+ * `type` selects the backend; remaining keys are backend-specific options.
+ */
+export interface PersistenceConfig {
+    type: string;
+    [key: string]: unknown;
+}
+/**
+ * @deprecated Use `PersistenceBackend` instead. Kept for backward compatibility.
+ */
+export interface SessionStore {
+    save(sessionId: string, messages: Message[]): Promise<void>;
+    load(sessionId: string): Promise<Message[] | null>;
+    delete(sessionId: string): Promise<void>;
+    list(): Promise<string[]>;
+}
+export interface SessionData {
+    id: string;
+    messages: Message[];
+    createdAt: number;
+    updatedAt: number;
+    provider?: ProviderType;
+    model?: string;
+    /** Arbitrary metadata for backends or consumers (e.g., TTL, apiKeyHash). */
+    metadata?: Record<string, unknown>;
+}
+export interface SkillMetadata {
+    name: string;
+    description: string;
+    tags: string[];
+}
+export { ZoeError, ProviderError, ToolError, MaxStepsError, AbortedError } from "./errors.js";

package/dist/core/types.js

@@ -0,0 +1,11 @@
+/**
+ * Zoe SDK — Shared TypeScript types
+ *
+ * This file is the single source of truth for all SDK interfaces.
+ * Every SDK module imports from here.
+ */
+// ── Errors ────────────────────────────────────────────────────────────
+// Error classes live in ./errors.ts. We re-export them here so that
+// existing consumers that import { ZoeError } from "./types.js"
+// continue to compile without changes.
+export { ZoeError, ProviderError, ToolError, MaxStepsError, AbortedError } from "./errors.js";

package/dist/gateway/gateway.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Zoe Gateway — MCPGateway engine
+ *
+ * Core engine that manages MCP and REST targets, routes requests,
+ * and exposes injectable tools for the agent loop.
+ */
+import type { ToolModule } from '../tools/interface.js';
+import { GatewaySettingsAdapter } from './settings-adapter.js';
+import type { AuditRecord, GatewayConfig, GatewayHooks, Target } from './types.js';
+export declare class MCPGateway {
+    private targets;
+    private mcpClients;
+    private auditLogs;
+    private routes;
+    private adminTargets;
+    private injectableToolsCache;
+    private invalidateToolsCache;
+    private settings;
+    private config;
+    private hooks;
+    constructor(settings: GatewaySettingsAdapter, config: GatewayConfig, hooks?: GatewayHooks);
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    private audit;
+    getAuditLogs(targetFilter?: string, limit?: number): AuditRecord[];
+    getUsageSummary(): Record<string, {
+        calls: number;
+        errors: number;
+    }>;
+    registerTarget(name: string, target: Target, isAdmin?: boolean): Promise<void>;
+    unregisterTarget(name: string): Promise<boolean>;
+    toggleTarget(name: string, enabled: boolean): Promise<boolean>;
+    getTargets(): Record<string, Target>;
+    addRoute(pattern: string, target: string, priority: number): Promise<void>;
+    removeRoute(pattern: string, target: string): Promise<void>;
+    routeRequest(request: string): string;
+    private connectMcpClient;
+    callMcpTool(agent: string, targetName: string, toolName: string, args: Record<string, unknown>): Promise<any>;
+    callRest(agent: string, targetName: string, reqPath: string, method: string, query?: Record<string, string>, body?: unknown): Promise<any>;
+    readResource(agent: string, targetName: string, uri: string): Promise<any>;
+    getPrompt(agent: string, targetName: string, name: string, args?: Record<string, string>): Promise<any>;
+    getRoutes(): Array<{
+        pattern: string;
+        target: string;
+        priority: number;
+    }>;
+    listCredentialKeys(): string[];
+    setCredential(key: string, value: string): Promise<void>;
+    deleteCredential(key: string): Promise<void>;
+    getInjectableTools(): ToolModule[];
+    private buildInjectableTools;
+}