zidane 1.5.2 → 1.6.0

package/dist/agent-DVvuhEN-.d.ts

@@ -0,0 +1,671 @@
+import { Hookable } from 'hookable';
+import { b as ExecutionContext, c as ExecutionHandle, e as SkillsConfig, S as SkillConfig } from './types-CyRzBgm0.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+
+/**
+ * Shared types for the agent system.
+ */
+
+type ThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high';
+interface McpServerConfig {
+    /** Display name (used for tool namespacing) */
+    name: string;
+    /** Transport type */
+    transport: 'stdio' | 'sse' | 'streamable-http';
+    /** For stdio: command to run */
+    command?: string;
+    /** For stdio: command arguments */
+    args?: string[];
+    /** For stdio: environment variables */
+    env?: Record<string, string>;
+    /** For sse/streamable-http: server URL */
+    url?: string;
+    /** Optional headers for HTTP transports */
+    headers?: Record<string, string>;
+}
+type ToolExecutionMode = 'sequential' | 'parallel';
+interface AgentBehavior {
+    /** Tool execution mode (default: 'sequential') */
+    toolExecution?: ToolExecutionMode;
+    /** Max agent loop iterations (default: 50) */
+    maxTurns?: number;
+    /** Max tokens per LLM response (default: 16384) */
+    maxTokens?: number;
+    /** Thinking token budget — overrides the level-based default when set */
+    thinkingBudget?: number;
+    /** JSON Schema for structured output. When set, the agent's final turn produces JSON matching this schema. */
+    schema?: Record<string, unknown>;
+}
+interface ImageContent {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: string;
+        data: string;
+    };
+}
+type SessionContentBlock = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    mediaType: string;
+    data: string;
+} | {
+    type: 'tool_call';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+} | {
+    type: 'tool_result';
+    callId: string;
+    output: string;
+    isError?: boolean;
+} | {
+    type: 'thinking';
+    text: string;
+};
+interface SessionMessage {
+    role: 'user' | 'assistant';
+    content: SessionContentBlock[];
+}
+interface SessionTurn {
+    /** UUID — generated by the store if it provides generateTurnId, else crypto.randomUUID() */
+    id: string;
+    /** Run that produced this turn (e.g. 'run_1') */
+    runId?: string;
+    role: 'user' | 'assistant' | 'system';
+    content: SessionContentBlock[];
+    /** Token usage — only present on assistant turns */
+    usage?: TurnUsage;
+    /** Unix timestamp (Date.now()) when the turn was created */
+    createdAt: number;
+}
+interface AgentRunOptions {
+    model?: string;
+    prompt: string;
+    system?: string;
+    thinking?: ThinkingLevel;
+    images?: ImageContent[];
+    /** Abort signal — when triggered, the agent stops after the current turn */
+    signal?: AbortSignal;
+    /** Behavior overrides for this run (overrides agent and harness defaults) */
+    behavior?: AgentBehavior;
+    /** Tool overrides for this run. Pass {} for no tools. Omit to use harness tools. */
+    tools?: Record<string, ToolDef>;
+}
+interface TurnUsage {
+    input: number;
+    output: number;
+    /** Tokens written to cache (Anthropic) */
+    cacheCreation?: number;
+    /** Tokens read from cache (Anthropic) */
+    cacheRead?: number;
+    /** Thinking/reasoning tokens used */
+    thinking?: number;
+    /** Cost in USD as reported by the provider (OpenRouter) */
+    cost?: number;
+}
+interface AgentStats {
+    totalIn: number;
+    totalOut: number;
+    turns: number;
+    elapsed: number;
+    /** Per-turn usage breakdown */
+    turnUsage?: TurnUsage[];
+    /** Total cost in USD (sum of per-turn costs reported by provider) */
+    cost?: number;
+    /** Stats from child agents spawned during this run */
+    children?: ChildRunStats[];
+    /** Structured output from schema enforcement (only present when behavior.schema is set) */
+    output?: Record<string, unknown>;
+}
+interface ChildRunStats {
+    id: string;
+    task: string;
+    stats: AgentStats;
+}
+
+interface AnthropicParams {
+    apiKey?: string;
+    access?: string;
+    refresh?: string;
+    expires?: number;
+    defaultModel?: string;
+}
+declare function anthropic(anthropicParams?: AnthropicParams): Provider;
+
+interface CerebrasParams {
+    apiKey?: string;
+    defaultModel?: string;
+}
+declare function cerebras(params?: CerebrasParams): Provider;
+
+interface OpenRouterParams {
+    apiKey?: string;
+    defaultModel?: string;
+}
+declare function openrouter(params?: OpenRouterParams): Provider;
+
+interface ToolSpec {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+}
+interface ToolCall {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+interface ToolResult {
+    id: string;
+    content: string;
+}
+interface StreamCallbacks {
+    onText: (delta: string) => void;
+}
+interface TurnResult {
+    /** Full assistant turn as a SessionMessage */
+    assistantMessage: SessionMessage;
+    /** Text content blocks concatenated */
+    text: string;
+    /** Tool calls requested by the model */
+    toolCalls: ToolCall[];
+    /** Whether the model wants to stop */
+    done: boolean;
+    usage: TurnUsage;
+}
+interface StreamOptions {
+    model: string;
+    system: string;
+    tools: unknown[];
+    messages: SessionMessage[];
+    maxTokens: number;
+    /** Thinking/reasoning level (optional, default: off) */
+    thinking?: ThinkingLevel;
+    /** Exact thinking token budget — overrides the level-based default when set */
+    thinkingBudget?: number;
+    /** Force tool selection behavior */
+    toolChoice?: {
+        type: 'auto' | 'required' | 'tool';
+        name?: string;
+    };
+    /** Abort signal for cancellation */
+    signal?: AbortSignal;
+}
+interface Provider {
+    readonly name: string;
+    readonly meta: {
+        defaultModel: string;
+    } & Record<string, unknown>;
+    /** Format tool specs for this provider */
+    formatTools: (tools: ToolSpec[]) => unknown[];
+    /** Create a user message (text or with images) */
+    userMessage: (content: string, images?: ImageContent[]) => SessionMessage;
+    /** Create an assistant message (for priming) */
+    assistantMessage: (content: string) => SessionMessage;
+    /** Create a tool results message to send back */
+    toolResultsMessage: (results: ToolResult[]) => SessionMessage;
+    /** Stream a turn, calling onText for each text delta */
+    stream: (options: StreamOptions, callbacks: StreamCallbacks) => Promise<TurnResult>;
+}
+
+/** Core tools available in every basic harness (without spawn) */
+declare const basicTools: {
+    shell: ToolDef;
+    readFile: ToolDef;
+    writeFile: ToolDef;
+    listFiles: ToolDef;
+};
+declare const _default: HarnessConfig;
+
+/**
+ * Runtime context passed to every tool execution.
+ * Provides access to the agent's provider, abort signal, execution environment, and hooks.
+ */
+interface ToolContext {
+    /** The LLM provider for this agent run */
+    provider: Provider;
+    /** Abort signal — tools should check this for early termination */
+    signal: AbortSignal;
+    /** The execution context (shell, filesystem, etc.) */
+    execution: ExecutionContext;
+    /** The active execution handle for the current agent run */
+    handle: ExecutionHandle;
+    /** Agent hooks for emitting events (e.g. spawn:complete) */
+    hooks: Hookable<AgentHooks>;
+    /** The harness config for this agent (tools available to the agent) */
+    harness: HarnessConfig;
+}
+interface ToolDef {
+    spec: ToolSpec;
+    execute: (input: Record<string, unknown>, ctx: ToolContext) => Promise<string>;
+}
+type ToolMap = Map<string, ToolDef>;
+interface HarnessConfig {
+    /** Display name for this harness */
+    name: string;
+    /** Default system prompt injected when no system is provided at run time */
+    system?: string;
+    /** Tool definitions available to the agent */
+    tools: Record<string, ToolDef>;
+    /** MCP servers to connect and expose as tools */
+    mcpServers?: McpServerConfig[];
+    /** Skills configuration at the harness level */
+    skills?: SkillsConfig;
+    /** Default behavior for agents using this harness */
+    behavior?: AgentBehavior;
+}
+/**
+ * Define a harness with a name, optional system prompt, and tools.
+ */
+declare function defineHarness(config: HarnessConfig): HarnessConfig;
+type Harness = HarnessConfig;
+/**
+ * A harness with no tools — for pure chat mode.
+ * Pass `tools: {}` in agent.run() or use this harness directly.
+ */
+declare const noTools: HarnessConfig;
+
+/**
+ * MCP (Model Context Protocol) server support.
+ *
+ * Connects to one or more MCP servers, discovers their tools,
+ * and wraps them as zidane ToolDefs for use in agent loops.
+ */
+
+interface McpConnection {
+    tools: Record<string, ToolDef>;
+    close: () => Promise<void>;
+}
+/**
+ * Convert MCP tool result content blocks to a single string.
+ * Text blocks are extracted; non-text blocks are JSON-stringified.
+ */
+declare function resultToString(content: unknown[]): string;
+/**
+ * Connect to MCP servers and discover their tools.
+ *
+ * Each tool is namespaced as `mcp_{serverName}_{toolName}` to avoid
+ * collisions with harness tools or tools from other servers.
+ *
+ * @param configs - Array of MCP server configurations
+ * @param _clientFactory - Internal: override client construction for testing
+ * @param hooks - Optional agent hooks for firing mcp:connect, mcp:error, mcp:close events
+ */
+declare function connectMcpServers(configs: McpServerConfig[], _clientFactory?: () => Client, hooks?: Hookable<AgentHooks>): Promise<McpConnection>;
+
+/**
+ * In-memory session store.
+ * Useful for development and testing. Data is lost when the process exits.
+ */
+
+declare function createMemoryStore(): SessionStore;
+
+/**
+ * Canonical SessionMessage format with converters from/to Anthropic and OpenAI-compat formats.
+ */
+
+declare function fromAnthropic(msg: {
+    role: string;
+    content: unknown;
+}): SessionMessage;
+declare function fromOpenAI(msg: {
+    role: string;
+    content: unknown;
+}): SessionMessage;
+declare function toAnthropic(msg: SessionMessage): {
+    role: string;
+    content: unknown;
+};
+declare function toOpenAI(msg: SessionMessage): {
+    role: string;
+    content: unknown;
+};
+declare function autoDetectAndConvert(msg: {
+    role: string;
+    content: unknown;
+}): SessionMessage;
+
+/**
+ * Remote session store via HTTP API.
+ *
+ * Expects a REST API with:
+ *   GET    {url}/sessions/{id}                    -> SessionData | 404
+ *   PUT    {url}/sessions/{id}                    -> save SessionData
+ *   DELETE {url}/sessions/{id}                    -> delete
+ *   GET    {url}/sessions?agentId=&limit=         -> { ids: string[] }
+ *   POST   {url}/sessions/{id}/turns              -> append turns
+ *   GET    {url}/sessions/{id}/turns?from=&limit= -> SessionTurn[]
+ *   PUT    {url}/sessions/{id}/runs/{runId}        -> update run
+ *   PATCH  {url}/sessions/{id}                    -> { status }
+ */
+
+interface RemoteStoreOptions {
+    /** Base URL of the session API */
+    url: string;
+    /** Optional headers (e.g. for authentication) */
+    headers?: Record<string, string>;
+}
+declare function createRemoteStore(options: RemoteStoreOptions): SessionStore;
+
+/**
+ * SQLite session store using Bun's built-in bun:sqlite.
+ */
+
+interface SqliteStoreOptions {
+    /** Path to the SQLite database file */
+    path: string;
+}
+declare function createSqliteStore(options: SqliteStoreOptions): SessionStore;
+
+/**
+ * Session management for agents.
+ *
+ * A session tracks identity, turn history, and run metadata.
+ * Plug in any storage backend by implementing the SessionStore interface,
+ * or use one of the built-in stores: memory, sqlite, remote.
+ */
+
+interface SessionRun {
+    id: string;
+    startedAt: number;
+    endedAt?: number;
+    prompt: string;
+    status: 'running' | 'completed' | 'aborted' | 'error';
+    turns?: number;
+    tokensIn?: number;
+    tokensOut?: number;
+    error?: string;
+    /** Per-turn usage breakdown */
+    turnUsage?: TurnUsage[];
+    /** Total usage across all turns */
+    totalUsage?: TurnUsage;
+    /** Estimated cost in USD */
+    cost?: number;
+}
+interface SessionData {
+    id: string;
+    agentId?: string;
+    turns: SessionTurn[];
+    runs: SessionRun[];
+    status: 'idle' | 'running' | 'completed' | 'error';
+    metadata: Record<string, unknown>;
+    createdAt: number;
+    updatedAt: number;
+}
+interface SessionStore {
+    /** Optional: generate a session ID server-side (e.g. Supabase UUID). */
+    generateSessionId?: () => string | Promise<string>;
+    /** Optional: generate a turn ID server-side. */
+    generateTurnId?: () => string | Promise<string>;
+    /** Load a session by ID. Returns null if not found. */
+    load: (sessionId: string) => Promise<SessionData | null>;
+    /** Save a session (create or update, full document). */
+    save: (session: SessionData) => Promise<void>;
+    /** Delete a session. */
+    delete: (sessionId: string) => Promise<void>;
+    /** List session IDs, optionally filtered. */
+    list: (filter?: {
+        agentId?: string;
+        limit?: number;
+    }) => Promise<string[]>;
+    /** Append new turns to a session (incremental, avoids full re-save). */
+    appendTurns: (sessionId: string, turns: SessionTurn[]) => Promise<void>;
+    /** Return a slice of turns for a session. */
+    getTurns: (sessionId: string, from?: number, limit?: number) => Promise<SessionTurn[]>;
+    /** Persist an updated run record (called after completeRun / abortRun / errorRun). */
+    updateRun: (sessionId: string, run: SessionRun) => Promise<void>;
+    /** Update the top-level status of a session. */
+    updateStatus: (sessionId: string, status: SessionData['status']) => Promise<void>;
+}
+interface Session {
+    /** Session ID */
+    readonly id: string;
+    /** Agent ID (optional label) */
+    readonly agentId?: string;
+    /** Current turn history */
+    readonly turns: SessionTurn[];
+    /** Top-level session status */
+    readonly status: SessionData['status'];
+    /** All runs in this session */
+    readonly runs: SessionRun[];
+    /** Arbitrary metadata */
+    readonly metadata: Record<string, unknown>;
+    /** Start tracking a new run */
+    startRun: (runId: string, prompt: string) => void;
+    /** Mark a run as completed */
+    completeRun: (runId: string, stats: {
+        turns: number;
+        tokensIn: number;
+        tokensOut: number;
+        turnUsage?: TurnUsage[];
+        cost?: number;
+    }) => void;
+    /** Mark a run as aborted */
+    abortRun: (runId: string) => void;
+    /** Mark a run as errored */
+    errorRun: (runId: string, error: string) => void;
+    /** Append turns to in-memory history AND persist via store.appendTurns (if store present) */
+    appendTurns: (turns: SessionTurn[]) => Promise<void>;
+    /** Replace all turns in-memory (does not persist — use save() for that) */
+    setTurns: (turns: SessionTurn[]) => void;
+    /** Update the session status in memory AND via store.updateStatus (if store present) */
+    updateStatus: (status: SessionData['status']) => Promise<void>;
+    /** Persist an updated run record via store.updateRun (if store present) */
+    updateRun: (run: SessionRun) => Promise<void>;
+    /** Generate a turn ID using store.generateTurnId if available, else crypto.randomUUID() */
+    generateTurnId: () => string | Promise<string>;
+    /** Set metadata key */
+    setMeta: (key: string, value: unknown) => void;
+    /** Persist the full session document to the store */
+    save: () => Promise<void>;
+    /** Serialize to SessionData */
+    toJSON: () => SessionData;
+}
+interface CreateSessionOptions {
+    /** Session ID. If omitted and store provides generateSessionId, that is used. */
+    id?: string;
+    /** Agent ID label */
+    agentId?: string;
+    /** Initial metadata */
+    metadata?: Record<string, unknown>;
+    /** Storage backend (optional, enables save/load) */
+    store?: SessionStore;
+    _data?: SessionData;
+}
+/**
+ * Create a new session.
+ * Async so stores that generate IDs server-side (e.g. Supabase) can be supported.
+ */
+declare function createSession(options?: CreateSessionOptions): Promise<Session>;
+/**
+ * Load an existing session from a store.
+ */
+declare function loadSession(store: SessionStore, sessionId: string): Promise<Session | null>;
+
+/**
+ * Agent creation and state management.
+ */
+
+interface AgentHooks {
+    'system:before': (ctx: {
+        system: string;
+    }) => void;
+    'turn:before': (ctx: {
+        turn: number;
+        turnId: string;
+        options: StreamOptions;
+    }) => void;
+    'turn:after': (ctx: {
+        turn: number;
+        turnId: string;
+        usage: TurnUsage;
+        message: SessionTurn;
+    }) => void;
+    'stream:text': (ctx: {
+        delta: string;
+        text: string;
+        turnId: string;
+        blockIndex: number;
+    }) => void;
+    'stream:end': (ctx: {
+        text: string;
+        turnId: string;
+        blockIndex: number;
+    }) => void;
+    'tool:before': (ctx: {
+        name: string;
+        input: Record<string, unknown>;
+    }) => void;
+    'tool:after': (ctx: {
+        name: string;
+        input: Record<string, unknown>;
+        result: string;
+    }) => void;
+    'tool:error': (ctx: {
+        name: string;
+        input: Record<string, unknown>;
+        error: Error;
+    }) => void;
+    'tool:gate': (ctx: {
+        name: string;
+        input: Record<string, unknown>;
+        block: boolean;
+        reason: string;
+    }) => void;
+    'tool:transform': (ctx: {
+        name: string;
+        input: Record<string, unknown>;
+        result: string;
+        isError: boolean;
+    }) => void;
+    'context:transform': (ctx: {
+        messages: SessionMessage[];
+    }) => void;
+    'steer:inject': (ctx: {
+        message: string;
+    }) => void;
+    'spawn:complete': (ctx: ChildRunStats) => void;
+    'spawn:before': (ctx: {
+        id: string;
+        task: string;
+    }) => void;
+    'spawn:error': (ctx: {
+        id: string;
+        task: string;
+        error: Error;
+    }) => void;
+    'mcp:connect': (ctx: {
+        name: string;
+        transport: string;
+        tools: string[];
+    }) => void;
+    'mcp:error': (ctx: {
+        name: string;
+        error: Error;
+    }) => void;
+    'mcp:close': (ctx: {
+        name: string;
+    }) => void;
+    'mcp:tool:before': (ctx: {
+        server: string;
+        tool: string;
+        input: Record<string, unknown>;
+    }) => void;
+    'mcp:tool:after': (ctx: {
+        server: string;
+        tool: string;
+        input: Record<string, unknown>;
+        result: string;
+    }) => void;
+    'mcp:tool:error': (ctx: {
+        server: string;
+        tool: string;
+        input: Record<string, unknown>;
+        error: Error;
+    }) => void;
+    'skills:resolve': (ctx: {
+        skills: SkillConfig[];
+    }) => void;
+    'skills:catalog': (ctx: {
+        catalog: string;
+        skills: SkillConfig[];
+    }) => void;
+    'skills:activate': (ctx: {
+        skill: SkillConfig;
+    }) => void;
+    'usage': (ctx: {
+        turn: number;
+        turnId: string;
+        usage: TurnUsage;
+        totalIn: number;
+        totalOut: number;
+    }) => void;
+    'output': (ctx: {
+        output: Record<string, unknown>;
+        schema: Record<string, unknown>;
+    }) => void;
+    'agent:abort': (ctx: object) => void;
+    'agent:done': (ctx: AgentStats) => void;
+    'session:start': (ctx: {
+        sessionId: string;
+        runId: string;
+        prompt: string;
+    }) => void;
+    'session:end': (ctx: {
+        sessionId: string;
+        runId: string;
+        status: 'completed' | 'aborted' | 'error';
+        turnRange: [number, number];
+    }) => void;
+    'session:turns': (ctx: {
+        sessionId: string;
+        count: number;
+    }) => void;
+    'session:meta': (ctx: {
+        sessionId: string;
+        key: string;
+        value: unknown;
+    }) => void;
+    'session:save': (ctx: {
+        sessionId: string;
+    }) => void;
+}
+interface AgentOptions {
+    /** Harness (tools + system prompt). Defaults to a no-tools harness if omitted. */
+    harness?: HarnessConfig;
+    provider: Provider;
+    /** Agent-level behavior defaults (overridden by run-level behavior) */
+    behavior?: AgentBehavior;
+    /** Execution context: where tools run. Defaults to in-process. */
+    execution?: ExecutionContext;
+    /** MCP servers to connect and expose as tools */
+    mcpServers?: McpServerConfig[];
+    /** Session for identity, turn persistence, and run tracking */
+    session?: Session;
+    /** Skills configuration (merged with harness-level skills, agent takes precedence) */
+    skills?: SkillsConfig;
+    /** @internal */
+    _mcpConnector?: (configs: McpServerConfig[]) => Promise<McpConnection>;
+}
+interface Agent {
+    hooks: Hookable<AgentHooks>;
+    run: (options: AgentRunOptions) => Promise<AgentStats>;
+    abort: () => void;
+    steer: (message: string) => void;
+    followUp: (message: string) => void;
+    waitForIdle: () => Promise<void>;
+    reset: () => void;
+    /** Destroy the execution context and clean up resources */
+    destroy: () => Promise<void>;
+    readonly isRunning: boolean;
+    readonly turns: SessionTurn[];
+    readonly execution: ExecutionContext;
+    readonly handle: ExecutionHandle | null;
+    readonly session: Session | null;
+    meta: Record<string, unknown>;
+}
+declare function createAgent({ harness: harnessOption, provider, behavior: agentBehavior, execution, mcpServers, session, skills: agentSkills, _mcpConnector }: AgentOptions): Agent;
+
+export { cerebras as $, type Agent as A, type TurnResult as B, type CerebrasParams as C, type TurnUsage as D, autoDetectAndConvert as E, connectMcpServers as F, createAgent as G, type Harness as H, type ImageContent as I, createMemoryStore as J, createRemoteStore as K, createSession as L, type McpConnection as M, createSqliteStore as N, type OpenRouterParams as O, type Provider as P, defineHarness as Q, type RemoteStoreOptions as R, type Session as S, type ThinkingLevel as T, fromAnthropic as U, fromOpenAI as V, loadSession as W, noTools as X, toAnthropic as Y, toOpenAI as Z, anthropic as _, type AgentBehavior as a, openrouter as a0, _default as a1, basicTools as a2, resultToString as a3, type AgentHooks as b, type AgentOptions as c, type AgentRunOptions as d, type AgentStats as e, type AnthropicParams as f, type ChildRunStats as g, type CreateSessionOptions as h, type HarnessConfig as i, type McpServerConfig as j, type SessionContentBlock as k, type SessionData as l, type SessionMessage as m, type SessionRun as n, type SessionStore as o, type SessionTurn as p, type SqliteStoreOptions as q, type StreamCallbacks as r, type StreamOptions as s, type ToolCall as t, type ToolContext as u, type ToolDef as v, type ToolExecutionMode as w, type ToolMap as x, type ToolResult as y, type ToolSpec as z };