@xalia/agent 0.5.8 → 0.6.1

package/src/agent/agentUtils.ts

@@ -1,5 +1,6 @@
 import { getLogger } from "@xalia/xmcp/sdk";
-import { Agent, AgentProfile, OnMessageCB, OnToolCallCB } from "./agent";
+import { Agent, AgentProfile } from "./agent";
+import { IAgentEventHandler } from "./iAgentEventHandler";
 import { IPlatform } from "./iplatform";
 import { SkillManager } from "./sudoMcpServerManager";
 import OpenAI from "openai";
@@ -10,148 +11,159 @@ import { DummyLLM } from "./dummyLLM";
 import { ILLM } from "./llm";
 import { strict as assert } from "assert";
 import { RepeatLLM } from "./repeatLLM";
-import { McpServerManager } from "./mcpServerManager";
+import { ContextManager, IContextManager } from "./context";
 
 const logger = getLogger();
 
 export const DEFAULT_LLM_URL = "http://localhost:5001/v1";
-export const DEFAULT_LLM_MODEL = "gpt-4o";
+// uses openrouter
+export const DEFAULT_LLM_MODEL =
+  process.env["DEFAULT_LLM_MODEL"] || "openai/gpt-4o";
 
 export const XALIA_APP_HEADER = {
   "HTTP-Referer": "xalia.ai",
   "X-Title": "Xalia",
 };
 
-/**
- * Util function to create an Agent from some config information.
- */
-async function createAgent(
-  llmUrl: string | undefined,
-  model: string | undefined,
-  systemPrompt: string,
-  onMessage: OnMessageCB,
-  onToolCall: OnToolCallCB,
-  platform: IPlatform,
-  openaiApiKey: string | undefined,
-  stream: boolean = false,
-  mcpServerManager: McpServerManager
-): Promise<Agent> {
-  let llm: ILLM | undefined;
-
-  if (model && model.startsWith("dummy:")) {
-    // Dummy Agent
-    const llmUrl = model.slice(6);
-    if (llmUrl.length === 0) {
-      throw "malformed dummy:<script>";
-    }
-    const script = await platform.load(llmUrl);
-    logger.debug(` script: ${script}`);
-    const responses: OpenAI.ChatCompletion.Choice[] = JSON.parse(script);
-    logger.debug(`Initializing Dummy Agent: ${llmUrl}`);
-    llm = new DummyLLM(responses);
-  } else if (model === "repeat") {
-    llm = new RepeatLLM();
-  } else {
-    // Regular Agent
-    if (!openaiApiKey) {
-      throw "Missing OpenAI API Key";
-    }
-
-    logger.debug(`Initializing Agent: ${llmUrl} - ${model}`);
-    if (stream) {
-      llm = new OpenAILLMStreaming(openaiApiKey, llmUrl, model);
-    } else {
-      llm = new OpenAILLM(openaiApiKey, llmUrl, model);
-    }
-  }
-
-  assert(llm);
-  return Agent.initializeWithLLM(
-    onMessage,
-    onToolCall,
-    systemPrompt,
-    llm,
-    mcpServerManager
-  );
-}
-
-/**
- * Util function to create and initialize an Agent given an AgentProfile.
- */
-export async function createAgentWithSkills(
+export async function createAgentWithoutSkills(
   llmUrl: string,
   agentProfile: AgentProfile,
-  onMessage: OnMessageCB,
-  onToolCall: OnToolCallCB,
+  eventHandler: IAgentEventHandler,
   platform: IPlatform,
+  contextManager: IContextManager,
   llmApiKey: string | undefined,
   sudomcpConfig: SudoMcpConfiguration,
   authorizedUrl: string | undefined,
-  conversation: OpenAI.ChatCompletionMessageParam[] | undefined,
   stream: boolean = false
 ): Promise<[Agent, SkillManager]> {
   // Init SudoMcpServerManager
   logger.debug("[createAgentWithSkills] creating SudoMcpServerManager.");
   const sudoMcpServerManager = await SkillManager.initialize(
-    platform.openUrl,
+    (url: string, authResultP: Promise<boolean>, displayName: string) => {
+      platform.openUrl(url, authResultP, displayName);
+    },
     sudomcpConfig.backend_url,
     sudomcpConfig.api_key,
     authorizedUrl
   );
   logger.debug(
-    "[createAgentWithSkills] restore mcp settings:" +
+    "[createAgentWithoutSkills] restore mcp settings:" +
       JSON.stringify(agentProfile.mcp_settings)
   );
-  await sudoMcpServerManager.restoreMcpSettings(agentProfile.mcp_settings);
 
-  // Create agent using the McpServerManager just created
+  // Create agent using the event handler
   const agent = await createAgentFromSkillManager(
     llmUrl,
     agentProfile,
-    onMessage,
-    onToolCall,
+    eventHandler,
     platform,
+    contextManager,
     llmApiKey,
     sudoMcpServerManager,
-    conversation,
     stream
   );
 
   return [agent, sudoMcpServerManager];
 }
 
+/**
+ * Create and initialize an Agent given an AgentProfile using the
+ * IAgentEventHandler interface. This is the preferred way to create
+ * agents.
+ */
+export async function createAgentWithSkills(
+  llmUrl: string,
+  agentProfile: AgentProfile,
+  eventHandler: IAgentEventHandler,
+  platform: IPlatform,
+  contextManager: IContextManager,
+  llmApiKey: string | undefined,
+  sudomcpConfig: SudoMcpConfiguration,
+  authorizedUrl: string | undefined,
+  stream: boolean = false
+): Promise<[Agent, SkillManager]> {
+  const [agent, sudoMcpServerManager] = await createAgentWithoutSkills(
+    llmUrl,
+    agentProfile,
+    eventHandler,
+    platform,
+    contextManager,
+    llmApiKey,
+    sudomcpConfig,
+    authorizedUrl,
+    stream
+  );
+
+  logger.debug("[createAgentWithSkills] restoring skills");
+  await sudoMcpServerManager.restoreMcpSettings(agentProfile.mcp_settings);
+
+  return [agent, sudoMcpServerManager];
+}
+
 export async function createAgentFromSkillManager(
   llmUrl: string,
   agentProfile: AgentProfile,
-  onMessage: OnMessageCB,
-  onToolCall: OnToolCallCB,
+  eventHandler: IAgentEventHandler,
   platform: IPlatform,
+  contextManager: IContextManager,
   llmApiKey: string | undefined,
   skillManager: SkillManager,
-  conversation: OpenAI.ChatCompletionMessageParam[] | undefined,
   stream: boolean = false
 ): Promise<Agent> {
   // Create agent
   logger.debug("[createAgentFromSkillManager] creating agent ...");
-  const agent = await createAgent(
+  const llm = await createLLM(
     llmUrl,
-    agentProfile.model,
-    agentProfile.system_prompt,
-    onMessage,
-    onToolCall,
-    platform,
     llmApiKey,
+    agentProfile.model,
     stream,
+    platform
+  );
+  contextManager.setAgentPrompt(agentProfile.system_prompt);
+  const agent = Agent.initializeWithLLM(
+    eventHandler,
+    llm,
+    contextManager,
     skillManager
   );
-  if (conversation) {
-    agent.setConversation(conversation);
-  }
 
   logger.debug("[createAgentFromSkillManager] done");
   return agent;
 }
 
+export async function createLLM(
+  llmUrl: string | undefined,
+  llmApiKey: string | undefined,
+  model: string | undefined,
+  stream: boolean = false,
+  platform: IPlatform
+): Promise<ILLM> {
+  let llm: ILLM | undefined;
+
+  if (model && model.startsWith("dummy:")) {
+    llm = await DummyLLM.initFromModelUrl(model, platform);
+  } else if (model === "repeat") {
+    llm = new RepeatLLM();
+  } else {
+    // Regular Agent
+    if (!llmApiKey) {
+      throw new Error("Missing OpenAI API Key");
+    }
+
+    logger.debug(
+      `Initializing Agent: ${llmUrl ?? "unknown"} - ${model ?? "unknown"}`
+    );
+    if (stream) {
+      llm = new OpenAILLMStreaming(llmApiKey, llmUrl, model);
+    } else {
+      llm = new OpenAILLM(llmApiKey, llmUrl, model);
+    }
+  }
+
+  assert(llm);
+  return llm;
+}
+
 /**
  * An "non-interactive" agent is one which is not intended to be used
  * interactively (settings cannot be dyanmically adjusted, intermediate
@@ -168,25 +180,33 @@ export async function createNonInteractiveAgent(
   approveToolsUpTo: number
 ): Promise<Agent> {
   let remainingToolCalls = approveToolsUpTo;
-  const onMessage = async () => {};
-  const onToolCall = async () => {
-    if (remainingToolCalls !== 0) {
-      --remainingToolCalls;
-      return true;
-    }
-    return false;
+  const eventHandler: IAgentEventHandler = {
+    onCompletion: () => {},
+    onAgentMessage: async () => {},
+    // eslint-disable-next-line @typescript-eslint/require-await
+    onToolCall: async () => {
+      if (remainingToolCalls !== 0) {
+        --remainingToolCalls;
+        return true;
+      }
+      return false;
+    },
+    onToolCallResult: () => {},
   };
 
+  const contextManager = new ContextManager(
+    agentProfile.system_prompt,
+    conversation || []
+  );
   const [agent, _] = await createAgentWithSkills(
     url,
     agentProfile,
-    onMessage,
-    onToolCall,
+    eventHandler,
     platform,
+    contextManager,
     openaiApiKey,
     sudomcpConfig,
-    undefined,
-    conversation
+    undefined
   );
 
   return agent;
@@ -230,11 +250,32 @@ export async function runOneShot(
   logger.debug("[runOneShot]: shutdown done");
 
   if (!response) {
-    throw "No message returned from agent";
+    throw new Error("No message returned from agent");
+  }
+
+  // Handle different content types
+  let responseText = "";
+  if (typeof response.content === "string") {
+    responseText = response.content;
+  } else if (response.content === null || response.content === undefined) {
+    responseText = "";
+  } else if (Array.isArray(response.content)) {
+    // Handle array of content parts
+    responseText = response.content
+      .map((part) => {
+        if ("text" in part) {
+          return part.text;
+        }
+        return "";
+      })
+      .join("");
+  } else {
+    // Fallback for other types
+    responseText = String(response.content);
   }
 
   return {
-    response: "" + response.content,
+    response: responseText,
     conversation: agent.getConversation(),
   };
 }

package/src/agent/compressingContextManager.ts

@@ -0,0 +1,164 @@
+import { strict as assert } from "assert";
+import { getLogger } from "@xalia/xmcp/sdk";
+
+import {
+  Agent,
+  ChatCompletionUserMessageParam,
+  ChatCompletionMessageParam,
+} from "./agent";
+import { NULL_PLATFORM } from "./nullPlatform";
+import { createLLM } from "./agentUtils";
+import { ContextManager, ContextManagerWithCommit } from "./context";
+import { NULL_AGENT_EVENT_HANDLER } from "./nullAgentEventHandler";
+
+const logger = getLogger();
+
+/**
+ * System prompt used to generate a conversation summary.
+ */
+const COMPRESSION_SYSTEM_PROMPT =
+  // eslint-disable-next-line max-len
+  "You are a context summarizer, creating MINIMAL conversation digests which can be used to CONTINUE the conversation at a later date. TOKEN EFFICIENCY is a HIGH PRIORITY. Summaries will only be seen by LLMs and should USE ANY AND ALL ABBREVIATIONS to keep them as CONCISE as possible, while PRESERVING IMPORTANT DETAILS of the CONVERSATION.";
+
+/**
+ * Text prepended to a summary to create the checkpoint message
+ */
+const CHECKPOINT_MESSAGE_PREFIX =
+  // eslint-disable-next-line max-len
+  "We are continuing an earlier conversation. The remainder of this message is a summary of the conversation so far: ";
+
+export function createCheckpointMessage(
+  summary: string
+): ChatCompletionUserMessageParam {
+  return {
+    role: "user",
+    content: CHECKPOINT_MESSAGE_PREFIX + summary,
+  };
+}
+
+export async function createCompressionAgent(
+  compressionAgentUrl: string,
+  compressionAgentModel: string,
+  compressionAgentApiKey: string
+): Promise<Agent> {
+  const llm = await createLLM(
+    compressionAgentUrl,
+    compressionAgentApiKey,
+    compressionAgentModel,
+    false /* stream */,
+    NULL_PLATFORM
+  );
+
+  return Agent.initializeWithLLM(
+    NULL_AGENT_EVENT_HANDLER,
+    llm,
+    new ContextManager(COMPRESSION_SYSTEM_PROMPT, [])
+  );
+}
+
+export async function createSummary(
+  compressionAgentUrl: string,
+  compressionAgentModel: string,
+  compressionAgentApiKey: string,
+  conversation: ChatCompletionMessageParam[]
+): Promise<string> {
+  const agent = await createCompressionAgent(
+    compressionAgentUrl,
+    compressionAgentModel,
+    compressionAgentApiKey
+  );
+
+  const resp = await agent.userMessageEx(JSON.stringify(conversation));
+  if (!resp) {
+    throw new Error("compression agent returned null");
+  }
+
+  assert(resp.role === "assistant");
+  assert(
+    typeof resp.content === "string",
+    "expected string content from compression agent"
+  );
+
+  return resp.content;
+}
+
+/**
+ * Can perform compression on the committed part of the context. Caller (not
+ * the Agent) is responsible for committing the conversation and triggering
+ * compression.
+ */
+export class CompressingContextManager extends ContextManagerWithCommit {
+  compressionAgentUrl: string;
+  compressionAgentModel: string;
+  compressionAgentApiKey: string;
+  compressingMessages: number | undefined;
+
+  constructor(
+    systemPrompt: string,
+    messages: ChatCompletionMessageParam[],
+    compressionAgentUrl: string,
+    compressionAgentModel: string,
+    compressionAgentApiKey: string
+  ) {
+    super(systemPrompt, messages);
+    this.compressionAgentUrl = compressionAgentUrl;
+    this.compressionAgentModel = compressionAgentModel;
+    this.compressionAgentApiKey = compressionAgentApiKey;
+    this.compressingMessages = undefined;
+
+    // Sanity check the conversation form.
+    //
+    // Ordinarily, the committed context should end with an "assistant"
+    // message (i.e. user messages, an agent loop terminating in a final agent
+    // response).  However, if a conversation has been compressed, we may have
+    // only the summary, which is a "user" message.  In this case, this should
+    // be the only message.
+
+    const numMessages = this.numMessages();
+    const lastMessage = this.lastMessage();
+    if (lastMessage) {
+      const finalRole = lastMessage.role;
+      if (finalRole === "user") {
+        assert(numMessages === 1);
+      } else {
+        assert(finalRole === "assistant", `unexpected final role ${finalRole}`);
+      }
+    }
+  }
+
+  async compress(): Promise<string> {
+    // Only select messages for compression if they have been committed.
+    const numToCompress = this.getCommittedLength();
+    const messagesToCompress = this.leadingMessages(numToCompress);
+    assert(messagesToCompress.length === numToCompress);
+    this.compressingMessages = numToCompress;
+    assert(this.compressingMessages > 1, "<2 messages commited in the context");
+
+    logger.debug(
+      `[CompressingContextManager] start (${String(this.compressingMessages)})`
+    );
+
+    try {
+      const summary = await createSummary(
+        this.compressionAgentUrl,
+        this.compressionAgentModel,
+        this.compressionAgentApiKey,
+        messagesToCompress
+      );
+
+      logger.debug(`[CompressingContextManager] summary: ${summary}`);
+
+      // Replace the context `messages` and update `lastCommittedMessage`
+      // index.
+
+      const checkpointMessage = createCheckpointMessage(summary);
+      assert(typeof checkpointMessage.content === "string");
+      this.replaceLeadingMessages(numToCompress, checkpointMessage);
+
+      return summary;
+    } finally {
+      this.compressingMessages = undefined;
+      logger.debug(`[CompressingContextManager] compression done`);
+    }
+  }
+}