zidane 1.0.2 → 1.2.0

package/dist/agent-DvZm8U14.d.ts

@@ -0,0 +1,313 @@
+import { Hookable } from 'hookable';
+import Anthropic from '@anthropic-ai/sdk';
+import { M as McpServerConfig, d as TurnUsage, b as SessionMessage, C as ChildRunStats, a as AgentStats, A as AgentRunOptions, c as ToolExecutionMode } from './types-4CFQ-6Qu.js';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { Provider, StreamOptions } from './providers.js';
+import { Session } from './session.js';
+
+/**
+ * Execution context types.
+ *
+ * An execution context defines *where* and *how* an agent's tools run.
+ * The agent loop and tools interact through this interface without knowing
+ * whether they're running in-process, in a Docker container, or in a
+ * remote sandbox.
+ */
+interface ContextCapabilities {
+    /** Can execute shell commands */
+    shell: boolean;
+    /** Can read/write files in a workspace */
+    filesystem: boolean;
+    /** Can make outbound network requests */
+    network: boolean;
+    /** Has GPU access */
+    gpu: boolean;
+}
+/** Opaque handle to a running execution context instance */
+interface ExecutionHandle {
+    id: string;
+    type: ContextType;
+    /** Working directory within the context */
+    cwd: string;
+}
+interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+interface SpawnConfig {
+    /** Working directory (created if it doesn't exist) */
+    cwd?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Docker image (only for 'docker' context) */
+    image?: string;
+    /** Resource limits */
+    limits?: {
+        /** Memory limit in MB */
+        memory?: number;
+        /** CPU limit (e.g. '1.0' = 1 core) */
+        cpu?: string;
+        /** Timeout in seconds for the entire context lifetime */
+        timeout?: number;
+    };
+    /** Sandbox provider config (only for 'sandbox' context) */
+    sandbox?: {
+        provider: string;
+        apiKey?: string;
+        [key: string]: unknown;
+    };
+}
+type ContextType = 'process' | 'docker' | 'sandbox';
+interface ExecutionContext {
+    /** Context type identifier */
+    readonly type: ContextType;
+    /** What this context supports */
+    readonly capabilities: ContextCapabilities;
+    /** Spawn a new execution environment */
+    spawn: (config?: SpawnConfig) => Promise<ExecutionHandle>;
+    /** Execute a shell command in the context */
+    exec: (handle: ExecutionHandle, command: string, options?: {
+        cwd?: string;
+        env?: Record<string, string>;
+        timeout?: number;
+    }) => Promise<ExecResult>;
+    /** Read a file from the context's filesystem */
+    readFile: (handle: ExecutionHandle, path: string) => Promise<string>;
+    /** Write a file to the context's filesystem */
+    writeFile: (handle: ExecutionHandle, path: string, content: string) => Promise<void>;
+    /** List files in a directory */
+    listFiles: (handle: ExecutionHandle, path: string) => Promise<string[]>;
+    /** Destroy the execution environment and clean up resources */
+    destroy: (handle: ExecutionHandle) => Promise<void>;
+}
+
+/** 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: Anthropic.Tool;
+    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[];
+}
+/**
+ * Define a harness with a name, optional system prompt, and tools.
+ */
+declare function defineHarness(config: HarnessConfig): HarnessConfig;
+type Harness = 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>;
+
+/**
+ * Agent creation and state management.
+ */
+
+interface AgentHooks {
+    'system:before': (ctx: {
+        system: string;
+    }) => void;
+    'turn:before': (ctx: {
+        turn: number;
+        options: StreamOptions;
+    }) => void;
+    'turn:after': (ctx: {
+        turn: number;
+        usage: TurnUsage;
+    }) => void;
+    'stream:text': (ctx: {
+        delta: string;
+        text: string;
+    }) => void;
+    'stream:end': (ctx: {
+        text: string;
+    }) => 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;
+    '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';
+    }) => void;
+    'session:messages': (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: HarnessConfig;
+    provider: Provider;
+    /** Tool execution mode: 'sequential' (default) or 'parallel' */
+    toolExecution?: ToolExecutionMode;
+    /** Execution context: where tools run. Defaults to in-process. */
+    execution?: ExecutionContext;
+    /** MCP servers to connect and expose as tools */
+    mcpServers?: McpServerConfig[];
+    /** Session for identity, message persistence, and run tracking */
+    session?: Session;
+    /** @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 messages: SessionMessage[];
+    readonly execution: ExecutionContext;
+    readonly handle: ExecutionHandle | null;
+    readonly session: Session | null;
+    meta: Record<string, unknown>;
+}
+declare function createAgent({ harness, provider, toolExecution, execution, mcpServers, session, _mcpConnector }: AgentOptions): Agent;
+
+export { type Agent as A, type ContextCapabilities as C, type ExecutionContext as E, type Harness as H, type McpConnection as M, type SpawnConfig as S, type ToolContext as T, _default as _, type ExecResult as a, type AgentHooks as b, type AgentOptions as c, type ContextType as d, type ExecutionHandle as e, type HarnessConfig as f, type ToolDef as g, type ToolMap as h, connectMcpServers as i, createAgent as j, defineHarness as k, basicTools as l, resultToString as r };

package/dist/chunk-26LIQARN.js

@@ -0,0 +1,109 @@
+import {
+  __esm
+} from "./chunk-PNKVD2UK.js";
+
+// src/mcp/index.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+function resultToString(content) {
+  if (!content || !Array.isArray(content))
+    return "";
+  return content.map((block) => {
+    if (block?.type === "text")
+      return block.text;
+    return JSON.stringify(block);
+  }).join("\n");
+}
+function createTransport(config) {
+  switch (config.transport) {
+    case "stdio":
+      return new StdioClientTransport({
+        command: config.command,
+        args: config.args,
+        env: config.env
+      });
+    case "sse":
+      return new SSEClientTransport(new URL(config.url), {
+        requestInit: config.headers ? { headers: config.headers } : void 0
+      });
+    case "streamable-http":
+      return new StreamableHTTPClientTransport(new URL(config.url), {
+        requestInit: config.headers ? { headers: config.headers } : void 0
+      });
+    default:
+      throw new Error(`Unknown MCP transport: ${config.transport}`);
+  }
+}
+async function connectMcpServers(configs, _clientFactory, hooks) {
+  const connections = [];
+  const tools = {};
+  const errors = [];
+  for (const config of configs) {
+    try {
+      const client = _clientFactory ? _clientFactory() : new Client({ name: "zidane", version: "1.0.0" });
+      const transport = createTransport(config);
+      await client.connect(transport);
+      connections.push({ name: config.name, client });
+      const { tools: mcpTools } = await client.listTools();
+      const toolNames = [];
+      for (const tool of mcpTools) {
+        const namespacedName = `mcp_${config.name}_${tool.name}`;
+        toolNames.push(namespacedName);
+        tools[namespacedName] = {
+          spec: {
+            name: namespacedName,
+            description: tool.description || "",
+            input_schema: tool.inputSchema ?? { type: "object", properties: {} }
+          },
+          execute: async (input, _ctx) => {
+            await hooks?.callHook("mcp:tool:before", { server: config.name, tool: tool.name, input });
+            try {
+              const result = await client.callTool({ name: tool.name, arguments: input });
+              const output = resultToString(result.content);
+              await hooks?.callHook("mcp:tool:after", { server: config.name, tool: tool.name, input, result: output });
+              return output;
+            } catch (err) {
+              await hooks?.callHook("mcp:tool:error", { server: config.name, tool: tool.name, input, error: err });
+              throw err;
+            }
+          }
+        };
+      }
+      await hooks?.callHook("mcp:connect", {
+        name: config.name,
+        transport: config.transport,
+        tools: toolNames
+      });
+    } catch (err) {
+      errors.push({ name: config.name, error: err });
+      await hooks?.callHook("mcp:error", { name: config.name, error: err });
+    }
+  }
+  if (errors.length > 0 && connections.length === 0) {
+    const messages = errors.map((e) => `${e.name}: ${e.error.message}`).join(", ");
+    throw new Error(`All MCP servers failed to connect: ${messages}`);
+  }
+  return {
+    tools,
+    close: async () => {
+      await Promise.allSettled(
+        connections.map(async ({ name, client }) => {
+          await hooks?.callHook("mcp:close", { name });
+          await client.close();
+        })
+      );
+    }
+  };
+}
+var init_mcp = __esm({
+  "src/mcp/index.ts"() {
+  }
+});
+
+export {
+  resultToString,
+  connectMcpServers,
+  init_mcp
+};