@xalia/agent 0.6.4 → 0.6.5

package/src/agent/iAgentEventHandler.ts

@@ -1,8 +1,8 @@
 import { OpenAI } from "openai";
 import {
-  ChatCompletionAssistantMessageParam,
-  ChatCompletionMessageToolCall,
-  ChatCompletionToolMessageParam,
+  AssistantMessageParam,
+  MessageToolCall,
+  ToolMessageParam,
 } from "./llm";
 
 /**
@@ -17,7 +17,7 @@ export interface IAgentEventHandler {
    * `onAgentMessage`.  This call is for client code which wishes to track the
    * LLM context.
    */
-  onCompletion(result: ChatCompletionAssistantMessageParam): void;
+  onCompletion(result: AssistantMessageParam): void;
 
   /**
    * Images do not appear as part of `ChatCompletionAssistantMessageParam`,
@@ -30,7 +30,7 @@ export interface IAgentEventHandler {
    * Called when a tool call execution completes (success, error, or denial).
    * These messages are insertes into the LLM context.
    */
-  onToolCallResult(result: ChatCompletionToolMessageParam): void;
+  onToolCallResult(result: ToolMessageParam): void;
 
   /**
    * Called when the agent produces a message chunk (streaming).  Calls here
@@ -55,10 +55,7 @@ export interface IAgentEventHandler {
    * @param internal - If true, this is an "internal" or "Agent" tool.
    * @returns Promise<boolean> - true if approved, false if denied
    */
-  onToolCall(
-    toolCall: ChatCompletionMessageToolCall,
-    agentTool: boolean
-  ): Promise<boolean>;
+  onToolCall(toolCall: MessageToolCall, agentTool: boolean): Promise<boolean>;
 
   // Future extensibility examples:
   // onError?(error: AgentError): void;

package/src/agent/imageGenLLM.ts

@@ -4,7 +4,13 @@ import { writeFileSync } from "fs";
 
 import { getLogger } from "@xalia/xmcp/sdk";
 
-import { ILLM, ChatCompletion, XALIA_APP_HEADER } from "./llm";
+import {
+  ILLM,
+  Completion,
+  XALIA_APP_HEADER,
+  ToolDescriptor,
+  MessageParam,
+} from "./llm";
 
 const logger = getLogger();
 
@@ -49,10 +55,10 @@ export class ImageGenLLM implements ILLM {
   }
 
   public async getConversationResponse(
-    messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[],
-    tools?: OpenAI.Chat.Completions.ChatCompletionTool[],
+    messages: MessageParam[],
+    tools?: ToolDescriptor[],
     onMessage?: (msg: string, end: boolean) => Promise<void>
-  ): Promise<ChatCompletion> {
+  ): Promise<Completion> {
     assert(!tools || tools.length === 0, "tools not supported in ImageGenLLM");
 
     // Designed for image generation using openrouter, which tweaks the Create
@@ -67,7 +73,7 @@ export class ImageGenLLM implements ILLM {
 
     const completion = (await this.openai.chat.completions.create(
       params as OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming
-    )) as ChatCompletion;
+    )) as Completion;
 
     // const completion = {} as unknown as ChatCompletion;
 

package/src/agent/llm.ts

@@ -1,3 +1,4 @@
+import * as openai from "./openAI";
 import { OpenAI } from "openai";
 
 export const XALIA_APP_HEADER = {
@@ -5,123 +6,57 @@ export const XALIA_APP_HEADER = {
   "X-Title": "Xalia",
 };
 
-// Extend the ChatCompletionMessage type with an `images` value, compatible
-// with google/gemini-2.5-flash-image-preview.
+export type ContentPartImage = openai.ChatCompletionContentPartImage;
 
-export type ChatCompletionMessage =
-  OpenAI.Chat.Completions.ChatCompletionMessage & {
-    images?: OpenAI.Chat.Completions.ChatCompletionContentPartImage[];
-  };
+// For now, internally we only support "function" tool call requests, not
+// "custom" (impacts AssistantMessageParam).
+export type MessageToolCall = OpenAI.ChatCompletionMessageFunctionToolCall;
 
-export type ChatCompletionChoice = Omit<
-  OpenAI.Chat.Completions.ChatCompletion.Choice,
-  "message"
-> & { message: ChatCompletionMessage };
-
-export type ChatCompletion = Omit<
-  OpenAI.Chat.Completions.ChatCompletion,
-  "choices"
-> & { choices: Array<ChatCompletionChoice> };
-
-// Shortcuts to other useful OpenAI types.
-
-export type ChatCompletionMessageToolCall =
-  OpenAI.ChatCompletionMessageToolCall;
-
-export type ChatCompletionAssistantMessageParam =
-  OpenAI.ChatCompletionAssistantMessageParam;
+// ChatCompletionAssistantMessageParam, but with only "function" tool calls.
+export interface AssistantMessageParam
+  extends openai.ChatCompletionAssistantMessageParam {
+  tool_calls?: Array<MessageToolCall>;
+}
 
-export type ChatCompletionUserMessageParam =
-  OpenAI.ChatCompletionUserMessageParam;
+export type UserMessageParam = openai.ChatCompletionUserMessageParam;
 
-export type ChatCompletionToolMessageParam =
-  OpenAI.ChatCompletionToolMessageParam & {
-    metadata?: Record<string, string>;
-  };
+// Tool call results `ToolMessageParam` are only "function" results for now
+export interface ToolMessageParam
+  extends OpenAI.ChatCompletionToolMessageParam {
+  _meta?: Record<string, string>;
+  structuredContent?: unknown;
+}
 
-export type ChatCompletionMessageParam =
+export type MessageParam =
   | OpenAI.Chat.Completions.ChatCompletionSystemMessageParam
-  | ChatCompletionAssistantMessageParam
-  | ChatCompletionUserMessageParam
-  | ChatCompletionToolMessageParam;
+  | AssistantMessageParam
+  | UserMessageParam
+  | ToolMessageParam;
 
 // The tool description type
 
-export type ChatCompletionTool = OpenAI.Chat.Completions.ChatCompletionTool;
-
-// CompletionCreate params
-
-// openrouter reasoning type
-
-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;
-};
+export type ToolDescriptor = OpenAI.Chat.Completions.ChatCompletionFunctionTool;
 
 /**
- * A (openrouter-specific) stream chunk possibly containing reasoning tokens.
+ *
  */
-export type ChatCompletionChunkChoiceDeltaWithReasoning =
-  OpenAI.Chat.Completions.ChatCompletionChunk.Choice.Delta & {
-    reasoning?: string;
-    reasoning_details?: ReasoningDetails[];
-  };
-
-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;
+export interface Message /* WithReasoning */
+  extends openai.ChatCompletionMessage {
+  reasoning?: string;
+  tool_calls?: Array<MessageToolCall>;
 }
 
-/**
- * A chat completion message with extra reasoning tokens.
- */
-export type ChatCompletionMessageWithReasoning =
-  OpenAI.Chat.Completions.ChatCompletionMessage & {
-    reasoning?: string;
-  };
+// export interface Message extends MessageWithReasoning {}
+
+// Extend ChatCompletionChoice to only hold function tool calls
+export interface Choice extends openai.ChatCompletionChoice {
+  message: Message;
+}
+
+// Extends ChatCompletion to only hold function tool calls.
+export interface Completion extends openai.ChatCompletion {
+  choices: Array<Choice>;
+}
 
 export interface ILLM {
   getModel(): string;
@@ -129,11 +64,11 @@ export interface ILLM {
   getUrl(): string;
 
   getConversationResponse(
-    messages: ChatCompletionMessageParam[],
-    tools?: ChatCompletionTool[],
+    messages: MessageParam[],
+    tools?: ToolDescriptor[],
     onMessage?: (msg: string, end: boolean) => Promise<void>,
     onReasoning?: (reasoning: string) => Promise<void>
-  ): Promise<ChatCompletion>;
+  ): Promise<Completion>;
 
   setModel(model: string): void;
 }

package/src/agent/mcpServerManager.ts

@@ -1,25 +1,61 @@
-import { ChatCompletionTool } from "openai/resources.mjs";
+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 { TokenAuth } from "./tokenAuth";
-import { Tool } from "@modelcontextprotocol/sdk/types.js";
-import { strict as assert } from "assert";
+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<string> };
+export type McpCallback = { (args: string): Promise<McpServerToolCallResult> };
 
 /// Map of tool name to callback
 export type McpCallbacks = Map<string, McpCallback>;
@@ -35,11 +71,13 @@ export type EnabledToolsMap = Map<string, boolean>;
  * 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(tools: Tool[]) {
+  constructor(name: string, tools: Tool[], resources: Resource[]) {
     const toolsMap: { [toolName: string]: Tool } = {};
 
     for (const mcpTool of tools) {
@@ -47,11 +85,17 @@ export class McpServerInfo {
       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;
   }
@@ -60,6 +104,10 @@ export class McpServerInfo {
     return this.tools;
   }
 
+  public getResources(): Resource[] {
+    return this.resources;
+  }
+
   public getTool(toolName: string): Tool | undefined {
     return this.toolsMap[toolName];
   }
@@ -88,8 +136,15 @@ class McpServerInfoInternal extends McpServerInfoRW {
   private readonly client: McpClient;
   private readonly callbacks: McpCallbacks;
 
-  constructor(client: McpClient, tools: Tool[]) {
-    super(tools);
+  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();
 
@@ -97,7 +152,9 @@ class McpServerInfoInternal extends McpServerInfoRW {
       const toolName = mcpTool.name;
 
       // Create callback
-      const callback = async (argStr: string): Promise<string> => {
+      const callback = async (
+        argStr: string
+      ): Promise<McpServerToolCallResult> => {
         logger.debug(
           `cb for ${toolName} invoked with args (${typeof argStr}): ` +
             JSON.stringify(argStr)
@@ -120,7 +177,19 @@ class McpServerInfoInternal extends McpServerInfoRW {
         assert(typeof content0 === "object");
         const content0Text = content0.text;
         assert(typeof content0Text === "string");
-        return content0Text;
+
+        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);
@@ -134,9 +203,18 @@ class McpServerInfoInternal extends McpServerInfoRW {
     await this.client.close();
   }
 
-  public getCallback(toolName: string) {
+  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;
+  }
 }
 
 /**
@@ -169,7 +247,7 @@ export interface IMcpServerManager {
 export class McpServerManager implements IMcpServerManager {
   private mcpServers = new Map<string, McpServerInfoInternal>();
   private enabledToolsDirty: boolean = true;
-  private enabledOpenAITools: ChatCompletionTool[] = [];
+  private enabledOpenAITools: ToolDescriptor[] = [];
 
   public async shutdown() {
     await Promise.all(
@@ -194,19 +272,11 @@ export class McpServerManager implements IMcpServerManager {
     return this.getMcpServerInternal(mcpServerName);
   }
 
-  public async addMcpServerWithSSEUrl(
+  public async addMcpServerWithTransport(
     mcpServerName: string,
-    url: string,
-    apiKey?: string,
+    transport: Transport,
     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);
     const client = new McpClient({
       name: "@xalia/agent",
       version: "1.0.0",
@@ -223,6 +293,37 @@ export class McpServerManager implements IMcpServerManager {
     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.
    */
@@ -232,16 +333,23 @@ export class McpServerManager implements IMcpServerManager {
     tools?: Tool[]
   ): Promise<void> {
     try {
-      // TODO; require the tools to be passed in.
+      // 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(client, tools)
+        new McpServerInfoInternal(mcpServerName, client, tools, resources)
       );
     } catch (e) {
       await client.close();
@@ -289,7 +397,7 @@ export class McpServerManager implements IMcpServerManager {
     this.enabledToolsDirty = true;
   }
 
-  public getOpenAITools(): ChatCompletionTool[] {
+  public getOpenAITools(): ToolDescriptor[] {
     if (this.enabledToolsDirty) {
       this.enabledOpenAITools = computeOpenAIToolList(this.mcpServers);
       this.enabledToolsDirty = false;
@@ -325,7 +433,7 @@ export class McpServerManager implements IMcpServerManager {
    * Note the `qualifiedToolName` is the full `{mcpServerName}/{toolName}` as
    * in the openai spec.
    */
-  public async invoke(toolCall: VerifiedMcpToolCall): Promise<string> {
+  public async invoke(toolCall: VerifiedMcpToolCall): Promise<ToolCallResult> {
     const server = this.getMcpServerInternal(toolCall.mcpServerName);
     const cb = server.getCallback(toolCall.toolName);
     if (!cb) {
@@ -335,6 +443,14 @@ export class McpServerManager implements IMcpServerManager {
     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.
    */
@@ -390,8 +506,8 @@ export function splitQualifiedName(
 
 export function computeOpenAIToolList(
   mcpServers: Map<string, McpServerInfoInternal>
-): ChatCompletionTool[] {
-  const openaiTools: ChatCompletionTool[] = [];
+): ToolDescriptor[] {
+  const openaiTools: ToolDescriptor[] = [];
 
   for (const [mcpServerName, mcpServer] of mcpServers) {
     const tools = mcpServer.getTools();
@@ -413,7 +529,7 @@ export function computeOpenAIToolList(
 export function mcpToolToOpenAITool(
   tool: Tool,
   qualifiedName?: string
-): ChatCompletionTool {
+): ToolDescriptor {
   return {
     type: "function",
     function: {