@executioncontrolprotocol/runtime 0.3.0

package/dist/protocols/agent-transport.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Abstract interface for agent-to-agent communication transport.
+ *
+ * The default implementation uses the official A2A JavaScript SDK.
+ * The engine uses this to delegate work from the orchestrator to
+ * specialist executors.
+ *
+ * @category Protocols
+ */
+/**
+ * A reference to a remote agent that can receive delegated tasks.
+ *
+ * @category Protocols
+ */
+export interface AgentRef {
+    /** The executor name this agent corresponds to. */
+    name: string;
+    /** Connection endpoint (URL, address, or local identifier). */
+    endpoint: string;
+    /** Optional protocol version the agent speaks. */
+    protocolVersion?: string;
+}
+/**
+ * Capabilities reported by a remote agent.
+ *
+ * @category Protocols
+ */
+export interface AgentCapabilities {
+    /** Human-readable name the agent reports. */
+    name: string;
+    /** Skills or task types the agent can handle. */
+    skills: string[];
+    /** Whether the agent supports streaming responses. */
+    supportsStreaming: boolean;
+}
+/**
+ * A task delegated to a remote agent.
+ *
+ * @category Protocols
+ */
+export interface DelegatedTask {
+    /** Unique task ID assigned by the engine. */
+    id: string;
+    /** The executor name this task targets. */
+    executorName: string;
+    /** Free-form task description for the specialist. */
+    task: string;
+    /** Structured context data provided to the specialist. */
+    context: Record<string, unknown>;
+    /** Execution hints (priority, token budgets, etc.). */
+    hints?: Record<string, unknown>;
+}
+/**
+ * The result of a delegated task returned by a remote agent.
+ *
+ * @category Protocols
+ */
+export interface DelegationResult {
+    /** The task ID this result corresponds to. */
+    taskId: string;
+    /** The executor name that produced this result. */
+    executorName: string;
+    /** The structured output from the specialist. */
+    output: Record<string, unknown>;
+    /** Whether the task completed successfully. */
+    success: boolean;
+    /** Error message if the task failed. */
+    error?: string;
+}
+/**
+ * Interface for agent-to-agent communication.
+ *
+ * Used by the ECP engine to delegate tasks from the orchestrator
+ * to specialist executors and collect their results.
+ *
+ * @category Protocols
+ */
+export interface AgentTransport {
+    /** Human-readable name for this transport implementation. */
+    readonly name: string;
+    /**
+     * Query the capabilities of a remote agent.
+     *
+     * @param agent - Reference to the agent to query.
+     * @returns The capabilities the agent reports.
+     */
+    capabilities(agent: AgentRef): Promise<AgentCapabilities>;
+    /**
+     * Delegate a task to a remote agent and wait for its result.
+     *
+     * @param agent - Reference to the target agent.
+     * @param task - The task to delegate.
+     * @returns The result produced by the agent.
+     */
+    delegate(agent: AgentRef, task: DelegatedTask): Promise<DelegationResult>;
+    /**
+     * Release any resources held by this transport.
+     */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=agent-transport.d.ts.map

package/dist/protocols/agent-transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-transport.d.ts","sourceRoot":"","sources":["../../src/protocols/agent-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IAEb,+DAA+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IAEjB,kDAAkD;IAClD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IAEb,iDAAiD;IACjD,MAAM,EAAE,MAAM,EAAE,CAAC;IAEjB,sDAAsD;IACtD,iBAAiB,EAAE,OAAO,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IAEX,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IAErB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IAEb,0DAA0D;IAC1D,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjC,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;IAEf,mDAAmD;IACnD,YAAY,EAAE,MAAM,CAAC;IAErB,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhC,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IAEjB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAE1D;;;;;;OAMG;IACH,QAAQ,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IAE1E;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB"}

package/dist/protocols/agent-transport.js

@@ -0,0 +1,11 @@
+/**
+ * Abstract interface for agent-to-agent communication transport.
+ *
+ * The default implementation uses the official A2A JavaScript SDK.
+ * The engine uses this to delegate work from the orchestrator to
+ * specialist executors.
+ *
+ * @category Protocols
+ */
+export {};
+//# sourceMappingURL=agent-transport.js.map

package/dist/protocols/agent-transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-transport.js","sourceRoot":"","sources":["../../src/protocols/agent-transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/protocols/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./tool-invoker.js";
+export * from "./agent-transport.js";
+export * from "./mcp/index.js";
+export * from "./a2a/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/protocols/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/protocols/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC"}

package/dist/protocols/index.js

@@ -0,0 +1,5 @@
+export * from "./tool-invoker.js";
+export * from "./agent-transport.js";
+export * from "./mcp/index.js";
+export * from "./a2a/index.js";
+//# sourceMappingURL=index.js.map

package/dist/protocols/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/protocols/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,gBAAgB,CAAC"}

package/dist/protocols/mcp/index.d.ts

@@ -0,0 +1,2 @@
+export { MCPToolInvoker } from "./mcp-tool-invoker.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/protocols/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/protocols/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/protocols/mcp/index.js

@@ -0,0 +1,2 @@
+export { MCPToolInvoker } from "./mcp-tool-invoker.js";
+//# sourceMappingURL=index.js.map

package/dist/protocols/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/protocols/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/protocols/mcp/mcp-tool-invoker.d.ts

@@ -0,0 +1,30 @@
+/**
+ * MCP implementation of the {@link ToolInvoker} interface.
+ *
+ * Uses the official `@modelcontextprotocol/sdk` (v1.x) to connect to
+ * MCP servers, discover tools, and invoke them. Supports both stdio
+ * and SSE transports.
+ *
+ * @category Protocols
+ */
+import type { ToolInvoker, ToolServerConfig, DiscoveredTool, ToolResult } from "../tool-invoker.js";
+/**
+ * MCP-backed tool invoker.
+ *
+ * Manages connections to multiple MCP servers and routes tool
+ * calls to the correct one.
+ *
+ * @category Protocols
+ */
+export declare class MCPToolInvoker implements ToolInvoker {
+    readonly name = "mcp";
+    private servers;
+    connect(config: ToolServerConfig): Promise<void>;
+    listTools(serverName: string): Promise<DiscoveredTool[]>;
+    callTool(serverName: string, toolName: string, args: Record<string, unknown>): Promise<ToolResult>;
+    disconnect(serverName: string): Promise<void>;
+    disconnectAll(): Promise<void>;
+    private getServer;
+    private createTransport;
+}
+//# sourceMappingURL=mcp-tool-invoker.d.ts.map

package/dist/protocols/mcp/mcp-tool-invoker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tool-invoker.d.ts","sourceRoot":"","sources":["../../../src/protocols/mcp/mcp-tool-invoker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EACV,WAAW,EACX,gBAAgB,EAChB,cAAc,EACd,UAAU,EACX,MAAM,oBAAoB,CAAC;AAoC5B;;;;;;;GAOG;AACH,qBAAa,cAAe,YAAW,WAAW;IAChD,QAAQ,CAAC,IAAI,SAAS;IAEtB,OAAO,CAAC,OAAO,CAAsC;IAE/C,OAAO,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAehD,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAWxD,QAAQ,CACZ,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,UAAU,CAAC;IAwBhB,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY7C,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAKpC,OAAO,CAAC,SAAS;IAUjB,OAAO,CAAC,eAAe;CAwBxB"}

package/dist/protocols/mcp/mcp-tool-invoker.js

@@ -0,0 +1,121 @@
+/**
+ * MCP implementation of the {@link ToolInvoker} interface.
+ *
+ * Uses the official `@modelcontextprotocol/sdk` (v1.x) to connect to
+ * MCP servers, discover tools, and invoke them. Supports both stdio
+ * and SSE transports.
+ *
+ * @category Protocols
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+/**
+ * Extract text content from an MCP content block array.
+ */
+function extractContent(content) {
+    const textParts = content
+        .filter((c) => c.type === "text" && c.text)
+        .map((c) => c.text);
+    if (textParts.length === 1) {
+        try {
+            return JSON.parse(textParts[0]);
+        }
+        catch {
+            return textParts[0];
+        }
+    }
+    if (textParts.length > 1) {
+        return textParts.join("\n");
+    }
+    return content;
+}
+/**
+ * MCP-backed tool invoker.
+ *
+ * Manages connections to multiple MCP servers and routes tool
+ * calls to the correct one.
+ *
+ * @category Protocols
+ */
+export class MCPToolInvoker {
+    name = "mcp";
+    servers = new Map();
+    async connect(config) {
+        if (this.servers.has(config.name)) {
+            await this.disconnect(config.name);
+        }
+        const transport = this.createTransport(config);
+        const client = new Client({ name: "ecp-runtime", version: "0.3.0" }, { capabilities: {} });
+        await client.connect(transport);
+        this.servers.set(config.name, { client, transport, config });
+    }
+    async listTools(serverName) {
+        const server = this.getServer(serverName);
+        const result = await server.client.listTools();
+        return result.tools.map((tool) => ({
+            name: tool.name,
+            description: tool.description ?? "",
+            inputSchema: tool.inputSchema,
+        }));
+    }
+    async callTool(serverName, toolName, args) {
+        const server = this.getServer(serverName);
+        const result = await server.client.callTool({
+            name: toolName,
+            arguments: args,
+        });
+        if ("toolResult" in result) {
+            return {
+                content: result.toolResult,
+                isError: false,
+            };
+        }
+        const content = extractContent(result.content);
+        return {
+            content,
+            isError: result.isError ?? false,
+        };
+    }
+    async disconnect(serverName) {
+        const server = this.servers.get(serverName);
+        if (!server)
+            return;
+        try {
+            await server.client.close();
+        }
+        catch {
+            // best-effort cleanup
+        }
+        this.servers.delete(serverName);
+    }
+    async disconnectAll() {
+        const names = [...this.servers.keys()];
+        await Promise.allSettled(names.map((name) => this.disconnect(name)));
+    }
+    getServer(serverName) {
+        const server = this.servers.get(serverName);
+        if (!server) {
+            throw new Error(`MCP server "${serverName}" is not connected. Call connect() first.`);
+        }
+        return server;
+    }
+    createTransport(config) {
+        const t = config.transport;
+        const type = t.type;
+        switch (type) {
+            case "stdio":
+                return new StdioClientTransport({
+                    command: t.command,
+                    args: t.args ?? [],
+                    env: t.env,
+                    cwd: t.cwd,
+                });
+            case "sse":
+                return new SSEClientTransport(new URL(t.url));
+            default:
+                throw new Error(`Unsupported MCP transport type "${type}". Supported: "stdio", "sse".`);
+        }
+    }
+}
+//# sourceMappingURL=mcp-tool-invoker.js.map

package/dist/protocols/mcp/mcp-tool-invoker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tool-invoker.js","sourceRoot":"","sources":["../../../src/protocols/mcp/mcp-tool-invoker.ts"],"names":[],"mappings":"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"}

package/dist/protocols/tool-invoker.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Abstract interface for tool invocation providers.
+ *
+ * The default implementation delegates to MCP servers using the official
+ * MCP TypeScript SDK. The engine never calls tools directly — it always
+ * goes through a {@link ToolInvoker}.
+ *
+ * @category Protocols
+ */
+/**
+ * Metadata about a tool discovered from a server.
+ *
+ * @category Protocols
+ */
+export interface DiscoveredTool {
+    /** The tool's unique name on its server (e.g. `"issues.search"`). */
+    name: string;
+    /** Human-readable description. */
+    description: string;
+    /** JSON Schema describing the tool's accepted parameters. */
+    inputSchema: Record<string, unknown>;
+}
+/**
+ * The result of invoking a tool.
+ *
+ * @category Protocols
+ */
+export interface ToolResult {
+    /** The structured or textual data returned by the tool. */
+    content: unknown;
+    /** Whether the tool call ended in an error. */
+    isError: boolean;
+}
+/**
+ * Options for connecting to a tool server.
+ *
+ * @category Protocols
+ */
+export interface ToolServerConfig {
+    /** Logical name used to reference this server in the Context (e.g. `"jira"`). */
+    name: string;
+    /**
+     * Transport-specific connection details.
+     * For MCP: `{ type: "stdio", command: "...", args: [...] }` or
+     *          `{ type: "sse", url: "..." }`.
+     */
+    transport: Record<string, unknown>;
+}
+/**
+ * Interface for discovering and invoking tools on external servers.
+ *
+ * @category Protocols
+ */
+export interface ToolInvoker {
+    /** Human-readable name for this invoker implementation. */
+    readonly name: string;
+    /**
+     * Connect to a tool server. Must be called before
+     * {@link listTools} or {@link callTool} for that server.
+     *
+     * @param config - Connection configuration for the server.
+     */
+    connect(config: ToolServerConfig): Promise<void>;
+    /**
+     * List all tools available on a connected server.
+     *
+     * @param serverName - The logical name of the server.
+     * @returns The tools the server exposes.
+     */
+    listTools(serverName: string): Promise<DiscoveredTool[]>;
+    /**
+     * Invoke a tool on a connected server.
+     *
+     * @param serverName - The logical name of the server.
+     * @param toolName - The tool to invoke.
+     * @param args - Arguments to pass to the tool.
+     * @returns The tool's result.
+     */
+    callTool(serverName: string, toolName: string, args: Record<string, unknown>): Promise<ToolResult>;
+    /**
+     * Disconnect from a server and release resources.
+     *
+     * @param serverName - The logical name of the server to disconnect.
+     */
+    disconnect(serverName: string): Promise<void>;
+    /**
+     * Disconnect from all servers and release all resources.
+     */
+    disconnectAll(): Promise<void>;
+}
+//# sourceMappingURL=tool-invoker.d.ts.map

package/dist/protocols/tool-invoker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-invoker.d.ts","sourceRoot":"","sources":["../../src/protocols/tool-invoker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IAEb,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IAEpB,6DAA6D;IAC7D,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAC;IAEjB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,IAAI,EAAE,MAAM,CAAC;IAEb;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,OAAO,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjD;;;;;OAKG;IACH,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAAC;IAEzD;;;;;;;OAOG;IACH,QAAQ,CACN,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,UAAU,CAAC,CAAC;IAEvB;;;;OAIG;IACH,UAAU,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE9C;;OAEG;IACH,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAChC"}

package/dist/protocols/tool-invoker.js

@@ -0,0 +1,11 @@
+/**
+ * Abstract interface for tool invocation providers.
+ *
+ * The default implementation delegates to MCP servers using the official
+ * MCP TypeScript SDK. The engine never calls tools directly — it always
+ * goes through a {@link ToolInvoker}.
+ *
+ * @category Protocols
+ */
+export {};
+//# sourceMappingURL=tool-invoker.js.map

package/dist/protocols/tool-invoker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-invoker.js","sourceRoot":"","sources":["../../src/protocols/tool-invoker.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/providers/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./model-provider.js";
+export * from "./openai/index.js";
+export * from "./ollama/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC"}

package/dist/providers/index.js

@@ -0,0 +1,4 @@
+export * from "./model-provider.js";
+export * from "./openai/index.js";
+export * from "./ollama/index.js";
+//# sourceMappingURL=index.js.map

package/dist/providers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/providers/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC"}

package/dist/providers/model-provider.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Abstract interface for LLM model providers.
+ *
+ * Implementations bridge the ECP engine to specific model APIs (OpenAI,
+ * Anthropic, Ollama, etc.) while keeping the engine itself provider-agnostic.
+ *
+ * @category Providers
+ */
+/**
+ * A single message in a conversation with a model.
+ *
+ * @category Providers
+ */
+export interface ChatMessage {
+    /** The role of the message author. */
+    role: "system" | "user" | "assistant" | "tool";
+    /** Text content of the message. */
+    content: string;
+    /** Optional tool-call ID this message responds to. */
+    toolCallId?: string;
+    /** Optional name for the author (e.g. tool name). */
+    name?: string;
+}
+/**
+ * A tool definition the model can choose to call during generation.
+ *
+ * @category Providers
+ */
+export interface ToolDefinition {
+    /** Unique tool name (e.g. `"jira:issues.search"`). */
+    name: string;
+    /** Human-readable description of what the tool does. */
+    description: string;
+    /**
+     * JSON Schema describing the tool's parameters.
+     * Passed to the model as the function's input schema.
+     */
+    parameters: Record<string, unknown>;
+}
+/**
+ * A tool call requested by the model.
+ *
+ * @category Providers
+ */
+export interface ToolCall {
+    /** Unique ID for this tool call (used to match results). */
+    id: string;
+    /** The tool name the model wants to invoke. */
+    name: string;
+    /** The arguments the model provided, as a parsed object. */
+    arguments: Record<string, unknown>;
+}
+/**
+ * The result of a model generation request.
+ *
+ * @category Providers
+ */
+export interface GenerateResult {
+    /** The text content of the model's response (may be empty if tool calls are present). */
+    content: string;
+    /** Tool calls the model wants to make (empty array if none). */
+    toolCalls: ToolCall[];
+    /** The reason the model stopped generating. */
+    finishReason: "stop" | "tool-calls" | "length" | "content-filter" | "error";
+    /** Token usage for this generation. */
+    usage: TokenUsage;
+}
+/**
+ * Token counts for a generation request.
+ *
+ * @category Providers
+ */
+export interface TokenUsage {
+    /** Tokens consumed by the prompt/input. */
+    promptTokens: number;
+    /** Tokens generated in the response. */
+    completionTokens: number;
+    /** Total tokens (prompt + completion). */
+    totalTokens: number;
+}
+/**
+ * Options for a generation request.
+ *
+ * @category Providers
+ */
+export interface GenerateOptions {
+    /** The conversation messages to send. */
+    messages: ChatMessage[];
+    /** Model identifier override (e.g. `"gpt-4o"`). Falls back to executor config. */
+    model?: string;
+    /** Tools the model may call during generation. */
+    tools?: ToolDefinition[];
+    /** Controls randomness. 0 = deterministic, 1 = creative. */
+    temperature?: number;
+    /** Maximum tokens to generate. */
+    maxTokens?: number;
+    /**
+     * If set, the model should output structured JSON conforming
+     * to this schema.
+     */
+    responseFormat?: {
+        type: "json-schema";
+        schema: Record<string, unknown>;
+    };
+    /** Abort signal for cancellation. */
+    signal?: AbortSignal;
+}
+/**
+ * Provider interface for LLM model access.
+ *
+ * Each implementation wraps a specific model API while exposing
+ * a uniform interface to the ECP engine.
+ *
+ * @category Providers
+ */
+export interface ModelProvider {
+    /** Human-readable provider name (e.g. `"openai"`, `"ollama"`). */
+    readonly name: string;
+    /**
+     * Send a generation request to the model.
+     *
+     * @param options - The messages, tools, and configuration for this request.
+     * @returns The model's response including content, tool calls, and usage.
+     */
+    generate(options: GenerateOptions): Promise<GenerateResult>;
+    /**
+     * Whether this provider's models support native tool/function calling.
+     * If `false`, the engine must use prompt-based tool invocation.
+     */
+    supportsToolCalling(): boolean;
+}
+//# sourceMappingURL=model-provider.d.ts.map

package/dist/providers/model-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-provider.d.ts","sourceRoot":"","sources":["../../src/providers/model-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAE/C,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAEhB,sDAAsD;IACtD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,qDAAqD;IACrD,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IAEb,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,4DAA4D;IAC5D,EAAE,EAAE,MAAM,CAAC;IAEX,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IAEb,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,yFAAyF;IACzF,OAAO,EAAE,MAAM,CAAC;IAEhB,gEAAgE;IAChE,SAAS,EAAE,QAAQ,EAAE,CAAC;IAEtB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,GAAG,YAAY,GAAG,QAAQ,GAAG,gBAAgB,GAAG,OAAO,CAAC;IAE5E,uCAAuC;IACvC,KAAK,EAAE,UAAU,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IAErB,wCAAwC;IACxC,gBAAgB,EAAE,MAAM,CAAC;IAEzB,0CAA0C;IAC1C,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,yCAAyC;IACzC,QAAQ,EAAE,WAAW,EAAE,CAAC;IAExB,kFAAkF;IAClF,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,kDAAkD;IAClD,KAAK,CAAC,EAAE,cAAc,EAAE,CAAC;IAEzB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,kCAAkC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,cAAc,CAAC,EAAE;QACf,IAAI,EAAE,aAAa,CAAC;QACpB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACjC,CAAC;IAEF,qCAAqC;IACrC,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAE5D;;;OAGG;IACH,mBAAmB,IAAI,OAAO,CAAC;CAChC"}

package/dist/providers/model-provider.js

@@ -0,0 +1,10 @@
+/**
+ * Abstract interface for LLM model providers.
+ *
+ * Implementations bridge the ECP engine to specific model APIs (OpenAI,
+ * Anthropic, Ollama, etc.) while keeping the engine itself provider-agnostic.
+ *
+ * @category Providers
+ */
+export {};
+//# sourceMappingURL=model-provider.js.map

package/dist/providers/model-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-provider.js","sourceRoot":"","sources":["../../src/providers/model-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/providers/ollama/index.d.ts

@@ -0,0 +1,3 @@
+export { OllamaProvider } from "./ollama-provider.js";
+export type { OllamaProviderConfig } from "./ollama-provider.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/ollama/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/providers/ollama/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/providers/ollama/index.js

@@ -0,0 +1,2 @@
+export { OllamaProvider } from "./ollama-provider.js";
+//# sourceMappingURL=index.js.map

package/dist/providers/ollama/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/providers/ollama/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC"}