@agentxjs/mono-driver 2.0.0

package/src/MonoDriver.ts

@@ -0,0 +1,444 @@
+/**
+ * MonoDriver - Unified Cross-Platform Driver
+ *
+ * Implements the Driver interface using Vercel AI SDK.
+ * Supports multiple LLM providers (Anthropic, OpenAI, Google).
+ *
+ * ```
+ *         UserMessage
+ *              │
+ *              ▼
+ *     ┌─────────────────┐
+ *     │   MonoDriver    │
+ *     │                 │
+ *     │   receive()     │──► AsyncIterable<DriverStreamEvent>
+ *     │       │         │
+ *     │       ▼         │
+ *     │  Vercel AI SDK  │
+ *     └─────────────────┘
+ *              │
+ *              ▼
+ *         LLM Provider
+ *     (Anthropic/OpenAI/...)
+ * ```
+ */
+
+import { streamText, stepCountIs } from "ai";
+import type { ToolSet } from "ai";
+import { createAnthropic } from "@ai-sdk/anthropic";
+import { createOpenAI } from "@ai-sdk/openai";
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+import { createXai } from "@ai-sdk/xai";
+import { createDeepSeek } from "@ai-sdk/deepseek";
+import { createMistral } from "@ai-sdk/mistral";
+import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+import { createMCPClient } from "@ai-sdk/mcp";
+import type { MCPClient } from "@ai-sdk/mcp";
+import { Experimental_StdioMCPTransport } from "@ai-sdk/mcp/mcp-stdio";
+import type { Driver, DriverState, DriverStreamEvent } from "@agentxjs/core/driver";
+import type { UserMessage } from "@agentxjs/core/agent";
+import type { Session } from "@agentxjs/core/session";
+import { createLogger } from "commonxjs/logger";
+import type { MonoDriverConfig, MonoProvider, OpenAICompatibleConfig } from "./types";
+import { toVercelMessages, toStopReason, createEvent, toVercelTools } from "./converters";
+
+const logger = createLogger("mono-driver/MonoDriver");
+
+/**
+ * MonoDriver - Driver implementation using Vercel AI SDK
+ */
+export class MonoDriver implements Driver {
+  readonly name = "MonoDriver";
+
+  private _sessionId: string | null = null;
+  private _state: DriverState = "idle";
+  private abortController: AbortController | null = null;
+
+  private readonly config: MonoDriverConfig;
+  private readonly session?: Session;
+  private readonly provider: MonoProvider;
+  private readonly maxSteps: number;
+  private readonly compatibleConfig?: OpenAICompatibleConfig;
+
+  /** MCP clients created during initialize() */
+  private mcpClients: MCPClient[] = [];
+  /** Tools discovered from MCP servers */
+  private mcpTools: ToolSet = {};
+
+  constructor(config: MonoDriverConfig) {
+    this.config = config;
+    this.session = config.session;
+    this.provider = config.options?.provider ?? "anthropic";
+    this.maxSteps = config.options?.maxSteps ?? 10;
+    this.compatibleConfig = config.options?.compatibleConfig;
+  }
+
+  // ============================================================================
+  // Driver Interface Properties
+  // ============================================================================
+
+  get sessionId(): string | null {
+    return this._sessionId;
+  }
+
+  get state(): DriverState {
+    return this._state;
+  }
+
+  // ============================================================================
+  // Lifecycle Methods
+  // ============================================================================
+
+  async initialize(): Promise<void> {
+    if (this._state !== "idle") {
+      throw new Error(`Cannot initialize: Driver is in "${this._state}" state`);
+    }
+
+    logger.info("Initializing MonoDriver", {
+      agentId: this.config.agentId,
+      provider: this.provider,
+    });
+
+    // Generate a session ID for tracking
+    this._sessionId = `mono_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+
+    // Notify session ID captured
+    this.config.onSessionIdCaptured?.(this._sessionId);
+
+    // Initialize MCP servers
+    if (this.config.mcpServers) {
+      for (const [name, serverConfig] of Object.entries(this.config.mcpServers)) {
+        let client: MCPClient;
+
+        if ("command" in serverConfig) {
+          // Stdio transport — local subprocess
+          const transport = new Experimental_StdioMCPTransport({
+            command: serverConfig.command,
+            args: serverConfig.args,
+            env: serverConfig.env,
+          });
+          client = await createMCPClient({ transport });
+        } else {
+          // HTTP Streamable transport — remote server
+          client = await createMCPClient({
+            transport: {
+              type: serverConfig.type,
+              url: serverConfig.url,
+              headers: serverConfig.headers,
+            },
+          });
+        }
+
+        this.mcpClients.push(client);
+        const tools = await client.tools();
+        Object.assign(this.mcpTools, tools);
+        logger.info("MCP server connected", {
+          name,
+          toolCount: Object.keys(tools).length,
+        });
+      }
+    }
+
+    logger.info("MonoDriver initialized", { sessionId: this._sessionId });
+  }
+
+  async dispose(): Promise<void> {
+    if (this._state === "disposed") {
+      return;
+    }
+
+    logger.info("Disposing MonoDriver", { agentId: this.config.agentId });
+
+    // Abort any ongoing request
+    this.abortController?.abort();
+    this.abortController = null;
+
+    // Close MCP clients
+    for (const client of this.mcpClients) {
+      await client.close();
+    }
+    this.mcpClients = [];
+    this.mcpTools = {};
+
+    this._state = "disposed";
+    logger.info("MonoDriver disposed");
+  }
+
+  // ============================================================================
+  // Core Methods
+  // ============================================================================
+
+  async *receive(message: UserMessage): AsyncIterable<DriverStreamEvent> {
+    if (this._state === "disposed") {
+      throw new Error("Cannot receive: Driver is disposed");
+    }
+
+    if (this._state === "active") {
+      throw new Error("Cannot receive: Driver is already processing a message");
+    }
+
+    this._state = "active";
+    this.abortController = new AbortController();
+
+    try {
+      // Get history from Session
+      const history = this.session ? await this.session.getMessages() : [];
+
+      // Convert to Vercel AI SDK format
+      const messages = toVercelMessages(history);
+
+      // Add current user message
+      messages.push({
+        role: "user",
+        content:
+          typeof message.content === "string"
+            ? message.content
+            : message.content.map((part) => {
+                if ("text" in part) return { type: "text" as const, text: part.text };
+                return { type: "text" as const, text: String(part) };
+              }),
+      });
+
+      logger.debug("Sending message to LLM", {
+        provider: this.provider,
+        messageCount: messages.length,
+        agentId: this.config.agentId,
+      });
+
+      // Call Vercel AI SDK (v6)
+      const result = streamText({
+        model: this.getModel(),
+        system: this.config.systemPrompt,
+        messages,
+        tools: this.mergeTools(),
+        stopWhen: stepCountIs(this.maxSteps),
+        abortSignal: this.abortController.signal,
+      });
+
+      // Track state for event conversion
+      let messageStartEmitted = false;
+      // Track tool calls in current step for correct message ordering.
+      // AI SDK emits: tool-call → tool-result → finish-step
+      // Engine needs: AssistantMessage(with tool-calls) BEFORE ToolResultMessage
+      // So we inject message_stop before the first tool-result in each step.
+      let hasToolCallsInStep = false;
+
+      // Process fullStream (AI SDK v6 event types)
+      for await (const part of result.fullStream) {
+        if (this.abortController?.signal.aborted) {
+          yield createEvent("interrupted", { reason: "user" });
+          break;
+        }
+
+        switch (part.type) {
+          case "start":
+          case "start-step":
+            if (!messageStartEmitted) {
+              const messageId = `msg_${Date.now()}`;
+              const model = this.config.model ?? this.getDefaultModel();
+              yield createEvent("message_start", { messageId, model });
+              messageStartEmitted = true;
+            }
+            hasToolCallsInStep = false;
+            break;
+
+          case "text-delta":
+            yield createEvent("text_delta", { text: part.text });
+            break;
+
+          case "tool-input-start":
+            yield createEvent("tool_use_start", {
+              toolCallId: part.id,
+              toolName: part.toolName,
+            });
+            break;
+
+          case "tool-input-delta":
+            yield createEvent("input_json_delta", {
+              partialJson: part.delta,
+            });
+            break;
+
+          case "tool-call":
+            hasToolCallsInStep = true;
+            yield createEvent("tool_use_stop", {
+              toolCallId: part.toolCallId,
+              toolName: part.toolName,
+              input: part.input as Record<string, unknown>,
+            });
+            break;
+
+          case "tool-result":
+            // Flush AssistantMessage before first tool-result in this step.
+            // Ensures correct ordering: Assistant(tool-calls) → ToolResult
+            if (hasToolCallsInStep) {
+              yield createEvent("message_stop", {
+                stopReason: toStopReason("tool-calls"),
+              });
+              hasToolCallsInStep = false;
+            }
+            yield createEvent("tool_result", {
+              toolCallId: part.toolCallId,
+              result: part.output,
+              isError: false,
+            });
+            break;
+
+          case "tool-error":
+            if (hasToolCallsInStep) {
+              yield createEvent("message_stop", {
+                stopReason: toStopReason("tool-calls"),
+              });
+              hasToolCallsInStep = false;
+            }
+            yield createEvent("tool_result", {
+              toolCallId: part.toolCallId,
+              result: part.error,
+              isError: true,
+            });
+            break;
+
+          case "finish-step":
+            // Emit usage data for this step
+            if (part.usage) {
+              yield createEvent("message_delta", {
+                usage: {
+                  inputTokens: part.usage.inputTokens ?? 0,
+                  outputTokens: part.usage.outputTokens ?? 0,
+                },
+              });
+            }
+            // Reset for next step so start-step emits a new message_start
+            messageStartEmitted = false;
+            break;
+
+          case "finish":
+            yield createEvent("message_stop", {
+              stopReason: toStopReason(part.finishReason),
+            });
+            break;
+
+          case "error":
+            yield createEvent("error", {
+              message: String(part.error),
+              errorCode: "stream_error",
+            });
+            break;
+        }
+      }
+    } catch (error) {
+      if (error instanceof Error && error.name === "AbortError") {
+        yield createEvent("interrupted", { reason: "user" });
+      } else {
+        yield createEvent("error", {
+          message: error instanceof Error ? error.message : String(error),
+          errorCode: "runtime_error",
+        });
+        throw error;
+      }
+    } finally {
+      this._state = "idle";
+      this.abortController = null;
+    }
+  }
+
+  interrupt(): void {
+    if (this._state !== "active") {
+      logger.debug("Interrupt called but no active operation");
+      return;
+    }
+
+    logger.debug("Interrupting MonoDriver");
+    this.abortController?.abort();
+  }
+
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+
+  /**
+   * Merge MCP tools and config tools into a single ToolSet.
+   * Config tools (bash etc.) take precedence over MCP tools with the same name.
+   */
+  private mergeTools(): ToolSet | undefined {
+    const configTools = this.config.tools?.length ? toVercelTools(this.config.tools) : {};
+    const merged = { ...this.mcpTools, ...configTools };
+    return Object.keys(merged).length > 0 ? merged : undefined;
+  }
+
+  private getModel() {
+    const modelId = this.config.model ?? this.getDefaultModel();
+    const { apiKey } = this.config;
+    const baseURL = this.getBaseURL();
+
+    switch (this.provider) {
+      case "anthropic":
+        return createAnthropic({ apiKey, baseURL })(modelId);
+      case "openai":
+        return createOpenAI({ apiKey, baseURL })(modelId);
+      case "google":
+        return createGoogleGenerativeAI({ apiKey, baseURL })(modelId);
+      case "xai":
+        return createXai({ apiKey, baseURL })(modelId);
+      case "deepseek":
+        return createDeepSeek({ apiKey, baseURL })(modelId);
+      case "mistral":
+        return createMistral({ apiKey, baseURL })(modelId);
+      case "openai-compatible": {
+        if (!this.compatibleConfig) {
+          throw new Error("openai-compatible provider requires compatibleConfig in options");
+        }
+        const provider = createOpenAICompatible({
+          name: this.compatibleConfig.name,
+          baseURL: this.compatibleConfig.baseURL,
+          apiKey: this.compatibleConfig.apiKey ?? apiKey,
+        });
+        return provider.chatModel(modelId);
+      }
+      default:
+        return createAnthropic({ apiKey, baseURL })(modelId);
+    }
+  }
+
+  /**
+   * Get the base URL for the provider SDK.
+   *
+   * Provider SDKs expect baseURL to include the version path (e.g. /v1).
+   * DriverConfig.baseUrl is the API root without version path.
+   * This method bridges the gap.
+   */
+  private getBaseURL(): string | undefined {
+    if (!this.config.baseUrl) return undefined;
+    const base = this.config.baseUrl.replace(/\/+$/, "");
+    if (base.endsWith("/v1")) return base;
+    return `${base}/v1`;
+  }
+
+  private getDefaultModel(): string {
+    switch (this.provider) {
+      case "anthropic":
+        return "claude-sonnet-4-20250514";
+      case "openai":
+        return "gpt-4o";
+      case "google":
+        return "gemini-2.0-flash";
+      case "xai":
+        return "grok-3";
+      case "deepseek":
+        return "deepseek-chat";
+      case "mistral":
+        return "mistral-large-latest";
+      case "openai-compatible":
+        return "default";
+      default:
+        return "claude-sonnet-4-20250514";
+    }
+  }
+}
+
+/**
+ * Create a MonoDriver instance
+ */
+export function createMonoDriver(config: MonoDriverConfig): Driver {
+  return new MonoDriver(config);
+}

package/src/converters.ts

@@ -0,0 +1,175 @@
+/**
+ * Message and Event Converters
+ *
+ * Converts between AgentX types and Vercel AI SDK v6 types
+ */
+
+import { tool, jsonSchema } from "ai";
+import type { ModelMessage, ToolSet } from "ai";
+import type { Message, ToolResultMessage } from "@agentxjs/core/agent";
+import type { DriverStreamEvent, StopReason, ToolDefinition } from "@agentxjs/core/driver";
+
+// ============================================================================
+// Message Converters (AgentX → Vercel AI SDK v6)
+// ============================================================================
+
+/**
+ * Convert AgentX Message to Vercel ModelMessage
+ */
+export function toVercelMessage(message: Message): ModelMessage | null {
+  switch (message.subtype) {
+    case "user":
+      return {
+        role: "user",
+        content:
+          typeof message.content === "string" ? message.content : extractText(message.content),
+      };
+
+    case "assistant": {
+      // Assistant message may contain text and tool calls in content
+      const content = "content" in message ? message.content : "";
+      if (typeof content === "string") {
+        return { role: "assistant", content };
+      }
+      // Extract tool calls from content parts
+      const toolCalls = content.filter(
+        (p): p is { type: "tool-call"; id: string; name: string; input: Record<string, unknown> } =>
+          p.type === "tool-call"
+      );
+      if (toolCalls.length > 0) {
+        // Vercel AI SDK format: assistant with tool-call content
+        return {
+          role: "assistant",
+          content: [
+            ...content
+              .filter((p) => p.type === "text")
+              .map((p) => ({ type: "text" as const, text: (p as { text: string }).text })),
+            ...toolCalls.map((tc) => ({
+              type: "tool-call" as const,
+              toolCallId: tc.id,
+              toolName: tc.name,
+              input: tc.input,
+            })),
+          ],
+        } as unknown as ModelMessage;
+      }
+      return { role: "assistant", content: extractText(content) };
+    }
+
+    case "tool-result": {
+      const msg = message as ToolResultMessage;
+      return {
+        role: "tool",
+        content: [
+          {
+            type: "tool-result" as const,
+            toolCallId: msg.toolCallId,
+            toolName: msg.toolResult.name,
+            output: msg.toolResult.output,
+          },
+        ],
+      } as unknown as ModelMessage;
+    }
+
+    default:
+      return null;
+  }
+}
+
+/**
+ * Convert array of AgentX Messages to Vercel ModelMessages
+ */
+export function toVercelMessages(messages: Message[]): ModelMessage[] {
+  const result: ModelMessage[] = [];
+  for (const message of messages) {
+    const converted = toVercelMessage(message);
+    if (converted) {
+      result.push(converted);
+    }
+  }
+  return result;
+}
+
+/**
+ * Extract text from any content shape
+ */
+function extractText(content: unknown): string {
+  if (typeof content === "string") return content;
+
+  if (Array.isArray(content)) {
+    return content
+      .filter(
+        (part) =>
+          part !== null &&
+          typeof part === "object" &&
+          "text" in part &&
+          typeof part.text === "string"
+      )
+      .map((part) => part.text)
+      .join("");
+  }
+
+  return String(content ?? "");
+}
+
+// ============================================================================
+// Event Converters (Vercel AI SDK → AgentX)
+// ============================================================================
+
+/**
+ * Map Vercel AI SDK v6 finish reason to AgentX StopReason
+ */
+export function toStopReason(finishReason: string | null | undefined): StopReason {
+  switch (finishReason) {
+    case "stop":
+      return "end_turn";
+    case "length":
+      return "max_tokens";
+    case "tool-calls":
+      return "tool_use";
+    case "content-filter":
+      return "content_filter";
+    case "error":
+      return "error";
+    default:
+      return "other";
+  }
+}
+
+/**
+ * Create a DriverStreamEvent with timestamp
+ */
+export function createEvent<T extends DriverStreamEvent["type"]>(
+  type: T,
+  data: Extract<DriverStreamEvent, { type: T }>["data"]
+): DriverStreamEvent {
+  return {
+    type,
+    timestamp: Date.now(),
+    data,
+  } as DriverStreamEvent;
+}
+
+// ============================================================================
+// Tool Converters (AgentX → Vercel AI SDK v6)
+// ============================================================================
+
+/**
+ * Convert AgentX ToolDefinitions to Vercel AI SDK tool format
+ *
+ * Uses jsonSchema() instead of Zod to avoid adding Zod dependency to core.
+ * Type casts are needed to bridge our ToolDefinition.parameters (simplified
+ * JSON Schema) to the AI SDK's strict JSONSchema7 type.
+ */
+export function toVercelTools(tools: ToolDefinition[]): ToolSet {
+  const result: ToolSet = {};
+  for (const t of tools) {
+    result[t.name] = tool({
+      description: t.description,
+
+      inputSchema: jsonSchema(t.parameters as any),
+      execute: async (input) => t.execute(input as Record<string, unknown>),
+    });
+  }
+  return result;
+}

package/src/index.ts

@@ -0,0 +1,53 @@
+/**
+ * @agentxjs/mono-driver
+ *
+ * Unified cross-platform Driver using Vercel AI SDK.
+ *
+ * Features:
+ * - Multi-provider: Anthropic, OpenAI, Google (and more)
+ * - Cross-platform: Node.js, Bun, Cloudflare Workers, Edge Runtime
+ * - Lightweight: Direct HTTP API calls, no subprocess
+ *
+ * @example
+ * ```typescript
+ * import { createMonoDriver } from "@agentxjs/mono-driver";
+ *
+ * const driver = createMonoDriver({
+ *   apiKey: process.env.ANTHROPIC_API_KEY!,
+ *   agentId: "my-agent",
+ *   systemPrompt: "You are helpful",
+ *   options: {
+ *     provider: "anthropic",
+ *     maxSteps: 10,
+ *   },
+ * });
+ *
+ * await driver.initialize();
+ *
+ * for await (const event of driver.receive({ content: "Hello" })) {
+ *   if (event.type === "text_delta") {
+ *     process.stdout.write(event.data.text);
+ *   }
+ * }
+ *
+ * await driver.dispose();
+ * ```
+ */
+
+// Main exports
+export { MonoDriver, createMonoDriver } from "./MonoDriver";
+
+// Types
+export type {
+  MonoDriverConfig,
+  MonoDriverOptions,
+  MonoProvider,
+  MonoBuiltinProvider,
+  OpenAICompatibleConfig,
+} from "./types";
+
+// Converters (for advanced usage)
+export { toVercelMessage, toVercelMessages, toStopReason, createEvent } from "./converters";
+
+// Re-export Vercel AI SDK utilities for advanced usage
+export { stepCountIs } from "ai";