@xalia/agent 0.6.9 → 0.6.11

package/src/agent/mcpServerManager.ts

@@ -1,541 +0,0 @@
-import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
-import {
-  SSEClientTransport,
-  SSEClientTransportOptions,
-} from "@modelcontextprotocol/sdk/client/sse.js";
-import {
-  StreamableHTTPClientTransport,
-  StreamableHTTPClientTransportOptions,
-} from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { Client as McpClient } from "@modelcontextprotocol/sdk/client/index.js";
-import { Tool, Resource } from "@modelcontextprotocol/sdk/types.js";
-
-import { McpServerSettings, getLogger } from "@xalia/xmcp/sdk";
-export type { McpServerSettings } from "@xalia/xmcp/sdk";
-
-import { TokenAuth } from "./tokenAuth";
-import { strict as assert } from "assert";
-import { ToolDescriptor } from "./llm";
-import { ToolCallResult } from "./agent";
-
-const logger = getLogger();
-
-export type McpServerToolCallMetaData = {
-  "xalia/mcpServerName": string;
-};
-
-const mcpServerToolCallMetaKeys: (keyof McpServerToolCallMetaData)[] = [
-  "xalia/mcpServerName",
-];
-
-export function isMcpServerToolCallMetaData(
-  meta: unknown
-): meta is McpServerToolCallMetaData {
-  return (
-    !!meta &&
-    typeof meta === "object" &&
-    mcpServerToolCallMetaKeys.every((k) => k in meta)
-  );
-}
-
-export type McpServerToolCallResult = ToolCallResult<McpServerToolCallMetaData>;
-
-export type VerifiedMcpToolCall = {
-  mcpServerName: string;
-  toolName: string;
-  args: unknown;
-};
-
-export type ResourceContent = {
-  _meta?: Record<string, unknown>;
-  uri: string;
-  mimeType?: string;
-  text?: string;
-  blob?: string;
-};
-
-/// Callback into an Mcp server
-export type McpCallback = { (args: string): Promise<McpServerToolCallResult> };
-
-/// Map of tool name to callback
-export type McpCallbacks = Map<string, McpCallback>;
-
-/// List of tool names that are enabled.  We keep it as a map in the runtime
-/// object, so that we can quickly add and remove arbitrary entries.  (The
-/// AgentProfile keeps this as a flat list).
-export type EnabledToolsMap = Map<string, boolean>;
-
-/**
- * The (read-only) McpServerInfo to expose to external classes.  Callers
- * should not modify this data directly.  Only through the McpServerManager
- * class.
- */
-export class McpServerInfo {
-  private readonly name: string;
-  private readonly tools: Tool[]; // TODO: May not need both tools and toolsMap
-  private readonly resources: Resource[];
-  private readonly toolsMap: { [toolName: string]: Tool };
-  protected enabledToolsMap: EnabledToolsMap;
-
-  constructor(name: string, tools: Tool[], resources: Resource[]) {
-    const toolsMap: { [toolName: string]: Tool } = {};
-
-    for (const mcpTool of tools) {
-      const toolName = mcpTool.name;
-      toolsMap[toolName] = mcpTool;
-    }
-
-    this.name = name;
-    this.tools = tools;
-    this.resources = resources;
-    this.toolsMap = toolsMap;
-    this.enabledToolsMap = new Map();
-  }
-
-  public getName(): string {
-    return this.name;
-  }
-
-  public getEnabledTools(): EnabledToolsMap {
-    return this.enabledToolsMap;
-  }
-
-  public getTools(): Tool[] {
-    return this.tools;
-  }
-
-  public getResources(): Resource[] {
-    return this.resources;
-  }
-
-  public getTool(toolName: string): Tool | undefined {
-    return this.toolsMap[toolName];
-  }
-}
-
-/**
- * Instance of McpServerInfo which supports setting tool state.  Intended for
- * IMcpServerManager implementations, not for client code.
- */
-export class McpServerInfoRW extends McpServerInfo {
-  public enableTool(toolName: string) {
-    this.enabledToolsMap.set(toolName, true);
-  }
-
-  public disableTool(toolName: string) {
-    this.enabledToolsMap.delete(toolName);
-  }
-}
-
-/**
- * The internal class holds server info and allows it to be updated. Managed
- * by McpServerManager.  Do not access these methods except via the
- * McpServerManager.
- */
-class McpServerInfoInternal extends McpServerInfoRW {
-  private readonly client: McpClient;
-  private readonly callbacks: McpCallbacks;
-
-  constructor(
-    name: string,
-    client: McpClient,
-    tools: Tool[],
-    resources: Resource[]
-  ) {
-    super(name, tools, resources);
-
-    logger.debug(`[McpServerInfoInternal] tools: ${JSON.stringify(tools)}`);
-
-    const callbacks: McpCallbacks = new Map();
-
-    for (const mcpTool of tools) {
-      const toolName = mcpTool.name;
-
-      // Create callback
-      const callback = async (
-        argStr: string
-      ): Promise<McpServerToolCallResult> => {
-        logger.debug(
-          `cb for ${toolName} invoked with args (${typeof argStr}): ` +
-            JSON.stringify(argStr)
-        );
-
-        const argsObj: unknown = JSON.parse(argStr);
-        const toolResult = await client.callTool({
-          name: toolName,
-          arguments: argsObj as Record<string, unknown>,
-        });
-        logger.debug(
-          `cb for ${toolName} returned: ${JSON.stringify(toolResult)}`
-        );
-
-        assert(typeof toolResult === "object");
-        const content = toolResult.content as { [a: number]: unknown };
-        assert(typeof content === "object");
-        assert(content);
-        const content0 = content[0] as { text: string };
-        assert(typeof content0 === "object");
-        const content0Text = content0.text;
-        assert(typeof content0Text === "string");
-
-        const meta: Record<string, string> = (toolResult._meta ||
-          {}) as McpServerToolCallMetaData;
-        meta["xalia/mcpServerName"] = this.getName();
-        assert(isMcpServerToolCallMetaData(meta));
-
-        return {
-          response: content0Text,
-          _meta: meta,
-          ...(toolResult.structuredContent
-            ? { structuredContent: toolResult.structuredContent }
-            : {}),
-        };
-      };
-
-      callbacks.set(toolName, callback);
-    }
-
-    this.client = client;
-    this.callbacks = callbacks;
-  }
-
-  public async shutdown(): Promise<void> {
-    await this.client.close();
-  }
-
-  public getCallback(toolName: string): McpCallback | undefined {
-    return this.callbacks.get(toolName);
-  }
-
-  public async readResource(uri: string): Promise<ResourceContent[]> {
-    const res = await this.client.readResource({
-      uri,
-    });
-
-    logger.info(`readResource: got: ${JSON.stringify(res)}`);
-    return res.contents;
-  }
-}
-
-/**
- * The client's interface to a manager which has mcp servers assigned to it,
- * and can then query them for their tools, enable/disbale spercific tools and
- * remove servers completely.
- *
- * This interface says nothing about communication with a specific agent.  It
- * only defines the client-facing interactions.
- */
-export interface IMcpServerManager {
-  hasMcpServer(mcpServerName: string): boolean;
-  getMcpServerNames(): string[];
-  getMcpServer(mcpServerName: string): McpServerInfo;
-
-  removeMcpServer(mcpServerName: string): Promise<void>;
-  enableAllTools(mcpServerName: string): void;
-  disableAllTools(mcpServerName: string): void;
-  enableTool(mcpServerName: string, toolName: string): void;
-  disableTool(mcpServerName: string, toolName: string): void;
-
-  shutdown(): Promise<void>;
-}
-
-/**
- * Manage a set of MCP servers, where the tools for each server have an
- * 'enabled' flag.  Tools are disabled by default.  The set of enabled tools
- * over all servers is exposed as a single list of OpenAI functions.
- */
-export class McpServerManager implements IMcpServerManager {
-  private mcpServers = new Map<string, McpServerInfoInternal>();
-  private enabledToolsDirty: boolean = true;
-  private enabledOpenAITools: ToolDescriptor[] = [];
-
-  public async shutdown() {
-    await Promise.all(
-      Array.from(this.mcpServers.entries()).map(([name, server]) => {
-        logger.debug(`shutting down: ${name}...`);
-        return server.shutdown();
-      })
-    );
-
-    this.mcpServers.clear();
-  }
-
-  public hasMcpServer(mcpServerName: string): boolean {
-    return this.mcpServers.has(mcpServerName);
-  }
-
-  public getMcpServerNames(): string[] {
-    return Array.from(this.mcpServers.keys());
-  }
-
-  public getMcpServer(mcpServerName: string): McpServerInfo {
-    return this.getMcpServerInternal(mcpServerName);
-  }
-
-  public async addMcpServerWithTransport(
-    mcpServerName: string,
-    transport: Transport,
-    tools?: Tool[]
-  ): Promise<void> {
-    const client = new McpClient({
-      name: "@xalia/agent",
-      version: "1.0.0",
-    });
-
-    try {
-      await client.connect(transport);
-    } catch (e) {
-      // Ensure the socket is closed so the process can exit if there is an
-      // error at connection time.
-      await client.close();
-      throw e;
-    }
-    await this.addMcpServerWithClient(client, mcpServerName, tools);
-  }
-
-  public async addMcpServerWithSSEUrl(
-    mcpServerName: string,
-    url: string,
-    apiKey?: string,
-    tools?: Tool[]
-  ): Promise<void> {
-    logger.debug(`Adding mcp server ${mcpServerName}: ${url}`);
-    const sseTransportOptions: SSEClientTransportOptions = {};
-    if (apiKey) {
-      sseTransportOptions.authProvider = new TokenAuth(apiKey);
-    }
-    const urlO = new URL(url);
-    const transport = new SSEClientTransport(urlO, sseTransportOptions);
-    return this.addMcpServerWithTransport(mcpServerName, transport, tools);
-  }
-
-  public async addMcpServerWithStreamableHTTPUrl(
-    mcpServerName: string,
-    url: string,
-    apiKey?: string
-  ): Promise<void> {
-    logger.debug(`Adding mcp (s-http) server ${mcpServerName}: ${url}`);
-    const transportOptions: StreamableHTTPClientTransportOptions = {};
-    if (apiKey) {
-      transportOptions.authProvider = new TokenAuth(apiKey);
-    }
-    const urlO = new URL(url);
-    const transport = new StreamableHTTPClientTransport(urlO, transportOptions);
-    return this.addMcpServerWithTransport(mcpServerName, transport);
-  }
-
-  /**
-   * Add MCP server from an already connected McpClient.
-   */
-  public async addMcpServerWithClient(
-    client: McpClient,
-    mcpServerName: string,
-    tools?: Tool[]
-  ): Promise<void> {
-    try {
-      // TODO: require the tools to be passed in.
-
-      const resourcesP = client.listResources().catch((err: unknown) => {
-        logger.warn(
-          `resources ${mcpServerName}: ${JSON.stringify(err)} ${String(err)}`
-        );
-        return { resources: [] };
-      });
-      if (!tools) {
-        const mcpTools = await client.listTools();
-        tools = mcpTools.tools;
-      }
-
-      const resources: Resource[] = (await resourcesP).resources;
-      this.mcpServers.set(
-        mcpServerName,
-        new McpServerInfoInternal(mcpServerName, client, tools, resources)
-      );
-    } catch (e) {
-      await client.close();
-      throw e;
-    }
-  }
-
-  public async removeMcpServer(mcpServerName: string): Promise<void> {
-    const server = this.getMcpServerInternal(mcpServerName);
-    this.mcpServers.delete(mcpServerName);
-    await server.shutdown();
-    this.enabledToolsDirty = true;
-  }
-
-  public enableAllTools(mcpServerName: string) {
-    logger.debug(`enableAllTools: ${mcpServerName}`);
-    const server = this.getMcpServerInternal(mcpServerName);
-    for (const tool of server.getTools()) {
-      logger.debug(`enable: ${tool.name}`);
-      server.enableTool(tool.name);
-    }
-    this.enabledToolsDirty = true;
-  }
-
-  public disableAllTools(mcpServerName: string) {
-    logger.debug(`disableAllTools: ${mcpServerName}`);
-    const server = this.getMcpServerInternal(mcpServerName);
-    for (const tool of server.getTools()) {
-      logger.debug(`disable: ${tool.name}`);
-      server.disableTool(tool.name);
-    }
-    this.enabledToolsDirty = true;
-  }
-
-  public enableTool(mcpServerName: string, toolName: string) {
-    logger.debug(`enableTool: ${mcpServerName} ${toolName}`);
-    const server = this.getMcpServerInternal(mcpServerName);
-    server.enableTool(toolName);
-    this.enabledToolsDirty = true;
-  }
-
-  public disableTool(mcpServerName: string, toolName: string) {
-    const server = this.getMcpServerInternal(mcpServerName);
-    server.disableTool(toolName);
-    this.enabledToolsDirty = true;
-  }
-
-  public getOpenAITools(): ToolDescriptor[] {
-    if (this.enabledToolsDirty) {
-      this.enabledOpenAITools = computeOpenAIToolList(this.mcpServers);
-      this.enabledToolsDirty = false;
-    }
-
-    return this.enabledOpenAITools;
-  }
-
-  public verifyToolCall(
-    qualifiedToolName: string,
-    args: unknown
-  ): VerifiedMcpToolCall {
-    const [mcpServerName, toolName] = splitQualifiedName(qualifiedToolName);
-    logger.debug(`invoke: qualified: ${qualifiedToolName}`);
-    logger.debug(
-      `invoke: mcpServerName: ${mcpServerName}, toolName: ${toolName}`
-    );
-    logger.debug(`invoke: args: ${JSON.stringify(args)}`);
-
-    const server = this.getMcpServerInternal(mcpServerName);
-    const cb = server.getCallback(toolName);
-    if (!cb) {
-      throw new Error(`Unknown tool ${qualifiedToolName}`);
-    }
-    return {
-      mcpServerName,
-      toolName,
-      args,
-    };
-  }
-
-  /**
-   * Note the `qualifiedToolName` is the full `{mcpServerName}/{toolName}` as
-   * in the openai spec.
-   */
-  public async invoke(toolCall: VerifiedMcpToolCall): Promise<ToolCallResult> {
-    const server = this.getMcpServerInternal(toolCall.mcpServerName);
-    const cb = server.getCallback(toolCall.toolName);
-    if (!cb) {
-      throw new Error(`Unknown tool ${toolCall.toolName}`);
-    }
-
-    return cb(JSON.stringify(toolCall.args));
-  }
-
-  public async getResource(
-    serverName: string,
-    uri: string
-  ): Promise<ResourceContent[]> {
-    const server = this.getMcpServerInternal(serverName);
-    return server.readResource(uri);
-  }
-
-  /**
-   * "Settings" refers to the set of added servers and enabled tools.
-   */
-  public getMcpServerSettings(): McpServerSettings {
-    const config: McpServerSettings = {};
-
-    // NOTE: on load, entries of the form:
-    //
-    //   <server>: []
-    //
-    // may be interpreted as "all tools for <server>".  If the client has left
-    // a server with no tools enabled, we mark it as disabled.
-
-    for (const [serverName, server] of this.mcpServers) {
-      const tools = Array.from(server.getEnabledTools().keys());
-      if (tools.length > 0) {
-        config[serverName] = tools;
-      }
-    }
-
-    return config;
-  }
-
-  private getMcpServerInternal(mcpServerName: string): McpServerInfoInternal {
-    const server = this.mcpServers.get(mcpServerName);
-    if (server) {
-      return server;
-    }
-    throw Error(`[getMcpServerInternal] unknown server ${mcpServerName}`);
-  }
-}
-
-export function computeQualifiedName(
-  mcpServerName: string,
-  toolName: string
-): string {
-  return `${mcpServerName}__${toolName}`;
-}
-
-export function splitQualifiedName(
-  qualifiedToolName: string
-): [string, string] {
-  const delimIdx = qualifiedToolName.indexOf("__");
-  if (delimIdx < 0) {
-    throw Error(`invalid qualified name: ${qualifiedToolName}`);
-  }
-
-  return [
-    qualifiedToolName.slice(0, delimIdx),
-    qualifiedToolName.slice(delimIdx + 2),
-  ];
-}
-
-export function computeOpenAIToolList(
-  mcpServers: Map<string, McpServerInfoInternal>
-): ToolDescriptor[] {
-  const openaiTools: ToolDescriptor[] = [];
-
-  for (const [mcpServerName, mcpServer] of mcpServers) {
-    const tools = mcpServer.getTools();
-    const enabled = mcpServer.getEnabledTools();
-
-    for (const mcpTool of tools) {
-      const toolName = mcpTool.name;
-      if (enabled.get(toolName)) {
-        const qualifiedName = computeQualifiedName(mcpServerName, toolName);
-        const openaiTool = mcpToolToOpenAITool(mcpTool, qualifiedName);
-        openaiTools.push(openaiTool);
-      }
-    }
-  }
-
-  return openaiTools;
-}
-
-export function mcpToolToOpenAITool(
-  tool: Tool,
-  qualifiedName?: string
-): ToolDescriptor {
-  return {
-    type: "function",
-    function: {
-      name: qualifiedName || tool.name,
-      description: tool.description,
-      parameters: tool.inputSchema,
-    },
-  };
-}

package/src/agent/nullAgentEventHandler.ts

@@ -1,26 +0,0 @@
-import { IAgentEventHandler } from "./iAgentEventHandler";
-
-/**
- * Trivial IAgentEventHandler implementation which does not track any messages
- * and does not allow tool calls.
- */
-export const NULL_AGENT_EVENT_HANDLER: IAgentEventHandler = {
-  onCompletion: (): void => {},
-  onImage: (): void => {},
-  onToolCallResult: (): void => {},
-  onAgentMessage: (): Promise<void> => {
-    return new Promise<void>((r) => {
-      r();
-    });
-  },
-  onReasoning: (): Promise<void> => {
-    return new Promise<void>((r) => {
-      r();
-    });
-  },
-  onToolCall: (): Promise<boolean> => {
-    return new Promise((r) => {
-      r(false);
-    });
-  },
-};

package/src/agent/nullPlatform.ts

@@ -1,13 +0,0 @@
-import { IPlatform } from "../agent/iplatform";
-
-export const NULL_PLATFORM: IPlatform = {
-  openUrl: () => {
-    throw new Error("null_platform openUrl called");
-  },
-  load: (): Promise<string> => {
-    throw new Error("null_platform load called");
-  },
-  renderHTML: (): Promise<void> => {
-    throw new Error("null_platform renderHTML called");
-  },
-};

package/src/agent/openAI.ts

@@ -1,123 +0,0 @@
-import { OpenAI } from "openai";
-
-/**
- *
- * Extension to the OpenAI messages to support custom elements added by other
- * providers.  These represent the data returned by from provider APIs, which
- * may not match our internal structures.
- *
- */
-
-export type ChatCompletionContentPartImage =
-  OpenAI.Chat.Completions.ChatCompletionContentPartImage;
-
-export type ChatCompletionMessageToolCall =
-  OpenAI.Chat.Completions.ChatCompletionMessageToolCall;
-
-// Extend the ChatCompletionMessage type with an `images` value, compatible
-// with google/gemini-2.5-flash-image-preview.
-export interface ChatCompletionMessage
-  extends OpenAI.Chat.Completions.ChatCompletionMessage {
-  images?: ChatCompletionContentPartImage[];
-}
-
-// Extend ChatCompletionChoice with messages containing images
-export interface ChatCompletionChoice
-  extends OpenAI.Chat.Completions.ChatCompletion.Choice {
-  message: ChatCompletionMessage;
-}
-
-// Extends ChatCompletion with Choices containing images
-export interface ChatCompletion extends OpenAI.Chat.Completions.ChatCompletion {
-  choices: Array<ChatCompletionChoice>;
-}
-
-// TODO: Do we need these?  They are input types, generally for convenience.
-// Instead, we could just make sure our internal types are compatible with the
-// OpenAI definition.
-
-// Expose for conveinence for now
-
-export type ChatCompletionAssistantMessageParam =
-  OpenAI.ChatCompletionAssistantMessageParam;
-
-export type ChatCompletionContentPart = OpenAI.ChatCompletionContentPart;
-
-export type ChatCompletionUserMessageParam =
-  OpenAI.ChatCompletionUserMessageParam;
-
-// export type ToolMessageParam = OpenAI.ChatCompletionToolMessageParam;
-
-// openrouter reasoning types
-
-export type ReasoningEffort = {
-  effort?: OpenAI.ReasoningEffort;
-  max_tokens?: never;
-};
-
-export type ReasoningMaxTokens = { effort?: never; max_tokens?: number };
-
-export type ReasoningExclude = { exclude?: boolean; enabled?: never };
-
-export type ReasoningEnabled = {
-  exclude?: never;
-  enabled?: boolean;
-};
-
-export type Reasoning = (ReasoningEffort | ReasoningMaxTokens) &
-  (ReasoningExclude | ReasoningEnabled);
-
-export type ReasoningDetails = {
-  type: "reasoning.text" | "<unknown>";
-  text?: string;
-  signature?: string;
-  format?: string;
-  index?: number;
-};
-
-/**
- * A (openrouter-specific) stream chunk possibly containing reasoning tokens.
- */
-export type ChatCompletionChunkChoiceDeltaWithReasoning =
-  OpenAI.Chat.Completions.ChatCompletionChunk.Choice.Delta & {
-    reasoning?: string;
-    reasoning_details?: ReasoningDetails[];
-  };
-
-// /**
-//  * A chat completion message with extra reasoning tokens.
-//  */
-// export interface ChatCompletionMessageWithReasoning
-//   extends OpenAI.Chat.Completions.ChatCompletionMessage {
-//   reasoning?: string;
-// }
-
-// Util function to extract reasoning tokens
-
-export function choiceDeltaExtractReasoning(
-  delta: ChatCompletionChunkChoiceDeltaWithReasoning
-): string | undefined {
-  if (delta.reasoning) {
-    return delta.reasoning;
-  }
-
-  if (delta.reasoning_details) {
-    let reasoning = "";
-    for (const details of delta.reasoning_details) {
-      if (details.type !== "reasoning.text") {
-        throw new Error(`unexpected details.type: ${details.type}`);
-      }
-      if (details.text) {
-        if (typeof details.text !== "string") {
-          throw new Error(
-            `unexpected typeof details.text: ${typeof details.text}`
-          );
-        }
-        reasoning += details.text;
-      }
-    }
-    return reasoning;
-  }
-
-  return undefined;
-}