@xalia/agent 0.6.9 → 0.6.11

package/src/agent/agentUtils.ts

@@ -1,285 +0,0 @@
-import { McpServerSettings, getLogger } from "@xalia/xmcp/sdk";
-import { Configuration as SudoMcpConfiguration } from "@xalia/xmcp/sdk";
-
-import { Agent, AgentProfile } from "./agent";
-import { IAgentEventHandler } from "./iAgentEventHandler";
-import { IPlatform } from "./iplatform";
-import { SkillManager } from "./sudoMcpServerManager";
-import { OpenAILLM } from "./openAILLM";
-import { OpenAILLMStreaming } from "./openAILLMStreaming";
-import { DummyLLM } from "./dummyLLM";
-import { ContentPartImage, ILLM, MessageParam } from "./llm";
-import { strict as assert } from "assert";
-import { RepeatLLM } from "./repeatLLM";
-import { ContextManager, IContextManager } from "./context";
-
-const logger = getLogger();
-
-export async function createAgentWithoutSkills(
-  llmUrl: string,
-  model: string,
-  eventHandler: IAgentEventHandler,
-  platform: IPlatform,
-  contextManager: IContextManager,
-  llmApiKey: string | undefined,
-  sudomcpConfig: SudoMcpConfiguration,
-  authorizedUrl: string | undefined,
-  stream: boolean = false
-): Promise<[Agent, SkillManager]> {
-  // Init SudoMcpServerManager
-  logger.debug("[createAgentWithSkills] creating SudoMcpServerManager.");
-  const sudoMcpServerManager = await SkillManager.initialize(
-    (url: string, authResultP: Promise<boolean>, displayName: string) => {
-      platform.openUrl(url, authResultP, displayName);
-    },
-    sudomcpConfig.backend_url,
-    sudomcpConfig.api_key,
-    authorizedUrl
-  );
-
-  // Create agent using the event handler
-  const agent = await createAgentFromSkillManager(
-    llmUrl,
-    model,
-    eventHandler,
-    platform,
-    contextManager,
-    llmApiKey,
-    sudoMcpServerManager,
-    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,
-  model: string,
-  eventHandler: IAgentEventHandler,
-  platform: IPlatform,
-  contextManager: IContextManager,
-  llmApiKey: string | undefined,
-  sudomcpConfig: SudoMcpConfiguration,
-  mcpSettings: McpServerSettings,
-  authorizedUrl: string | undefined,
-  stream: boolean = false
-): Promise<[Agent, SkillManager]> {
-  const [agent, sudoMcpServerManager] = await createAgentWithoutSkills(
-    llmUrl,
-    model,
-    eventHandler,
-    platform,
-    contextManager,
-    llmApiKey,
-    sudomcpConfig,
-    authorizedUrl,
-    stream
-  );
-
-  logger.debug(
-    `[createAgentWithSkills] skilles: ${JSON.stringify(mcpSettings)}`
-  );
-  await sudoMcpServerManager.restoreMcpSettings(mcpSettings);
-
-  return [agent, sudoMcpServerManager];
-}
-
-export async function createAgentFromSkillManager(
-  llmUrl: string,
-  model: string,
-  eventHandler: IAgentEventHandler,
-  platform: IPlatform,
-  contextManager: IContextManager,
-  llmApiKey: string | undefined,
-  skillManager: SkillManager | undefined,
-  stream: boolean = false
-): Promise<Agent> {
-  // Create agent
-  logger.debug("[createAgentFromSkillManager] creating agent ...");
-  const llm = await createLLM(llmUrl, llmApiKey, model, stream, platform);
-  const agent = Agent.initializeWithLLM(
-    eventHandler,
-    llm,
-    contextManager,
-    skillManager
-  );
-
-  logger.debug("[createAgentFromSkillManager] done");
-  return agent;
-}
-
-/**
- * Interpret the `model` string to create a specialized agent (dummy, repeat,
- * etc) or return undefined if a specialized agent has not been requested.
- */
-export async function createSpecializedLLM(
-  model: string,
-  platform: IPlatform
-): Promise<ILLM | undefined> {
-  let llm: ILLM | undefined;
-
-  if (model && model.startsWith("dummy:")) {
-    llm = await DummyLLM.initFromModelUrl(model, platform);
-  } else if (model === "repeat") {
-    llm = new RepeatLLM();
-  }
-  return llm;
-}
-
-export async function createLLM(
-  llmUrl: string | undefined,
-  llmApiKey: string | undefined,
-  model: string,
-  stream: boolean = false,
-  platform: IPlatform
-): Promise<ILLM> {
-  let llm = await createSpecializedLLM(model, platform);
-  if (llm) {
-    return llm;
-  }
-
-  // Regular Agent
-  if (!llmApiKey) {
-    throw new Error("Missing OpenAI API Key");
-  }
-
-  logger.debug(`Initializing Agent: ${llmUrl ?? "unknown"} - ${model}`);
-  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
- * messages are not used by the caller, the user does not need to approve tool
- * calls, etc).
- */
-export async function createNonInteractiveAgent(
-  url: string,
-  agentProfile: AgentProfile,
-  defaultModel: string,
-  conversation: MessageParam[] | undefined,
-  platform: IPlatform,
-  openaiApiKey: string | undefined,
-  sudomcpConfig: SudoMcpConfiguration,
-  approveToolsUpTo: number
-): Promise<Agent> {
-  let remainingToolCalls = approveToolsUpTo;
-  const eventHandler: IAgentEventHandler = {
-    onCompletion: () => {},
-    onImage: () => {},
-    onAgentMessage: async () => {},
-    onReasoning: 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.model || defaultModel,
-    eventHandler,
-    platform,
-    contextManager,
-    openaiApiKey,
-    sudomcpConfig,
-    agentProfile.mcp_settings,
-    undefined
-  );
-
-  return agent;
-}
-
-/**
- * Create an Agent (from the AgentProfile), pass it a single prompt and output
- * the response.
- */
-export async function runOneShot(
-  url: string,
-  agentProfile: AgentProfile,
-  defaultModel: string,
-  conversation: MessageParam[] | undefined,
-  platform: IPlatform,
-  prompt: string,
-  image: string | undefined,
-  llmApiKey: string | undefined,
-  sudomcpConfig: SudoMcpConfiguration,
-  approveToolsUpTo: number
-): Promise<{
-  response: string;
-  conversation: MessageParam[];
-  images: ContentPartImage[] | undefined;
-}> {
-  logger.debug("[runOneShot]: start");
-
-  // Create a non-interactive agent and pass any prompt/ image to it.  Return
-  // the first answer.
-
-  const agent = await createNonInteractiveAgent(
-    url,
-    agentProfile,
-    defaultModel,
-    conversation,
-    platform,
-    llmApiKey,
-    sudomcpConfig,
-    approveToolsUpTo
-  );
-
-  const agentResponse = await agent.userMessageEx(prompt, image);
-  await agent.shutdown();
-  logger.debug("[runOneShot]: shutdown done");
-
-  if (!agentResponse) {
-    throw new Error("No message returned from agent");
-  }
-
-  // Handle different content types
-  const response = agentResponse.message;
-  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: responseText,
-    conversation: agent.getConversation(),
-    images: agentResponse.images,
-  };
-}

package/src/agent/compressingContextManager.ts

@@ -1,129 +0,0 @@
-import { strict as assert } from "assert";
-import { getLogger } from "@xalia/xmcp/sdk";
-
-import { Agent } from "./agent";
-import { UserMessageParam, MessageParam, ILLM } from "./llm";
-import { ContextManager } from "./context";
-import { NULL_AGENT_EVENT_HANDLER } from "./nullAgentEventHandler";
-import { ContextManagerWithWorkspace } from "./contextWithWorkspace";
-
-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): UserMessageParam {
-  return {
-    role: "user",
-    content: CHECKPOINT_MESSAGE_PREFIX + summary,
-  };
-}
-
-export function createCompressionAgent(llm: ILLM): Agent {
-  return Agent.initializeWithLLM(
-    NULL_AGENT_EVENT_HANDLER,
-    llm,
-    new ContextManager(COMPRESSION_SYSTEM_PROMPT, [])
-  );
-}
-
-export async function createSummary(
-  llm: ILLM,
-  conversation: MessageParam[]
-): Promise<string> {
-  const agent = createCompressionAgent(llm);
-  const agentResp = await agent.userMessageEx(JSON.stringify(conversation));
-  if (!agentResp) {
-    throw new Error("compression agent returned null");
-  }
-
-  const resp = agentResp.message;
-  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 ContextManagerWithWorkspace {
-  readonly getLLM: () => Promise<ILLM>;
-  compressingMessages: number | undefined;
-
-  constructor(
-    systemPrompt: string,
-    messages: MessageParam[],
-    getLLM: () => Promise<ILLM>
-  ) {
-    super(systemPrompt, messages);
-    this.getLLM = getLLM;
-    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> {
-    const numToCompress = super.numMessages();
-    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 llm = await this.getLLM();
-      const summary = await createSummary(llm, 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`);
-    }
-  }
-}

package/src/agent/context.ts

@@ -1,265 +0,0 @@
-import { strict as assert } from "assert";
-import { MessageParam, UserMessageParam } from "./llm";
-import { SystemPromptProvider } from "./promptProvider";
-
-/**
- * ContextWriter
- */
-export interface IContextTransaction {
-  /**
-   * Add messages to the context.  Return handle to the first message.
-   */
-  addMessages(messages: MessageParam[]): number;
-  /**
-   * Add a single message to the context.  Returns a handle which can be used to
-   * overwrite the message before it it committed.
-   */
-  addMessage(message: MessageParam): number;
-  /**
-   * Retrieve message by handle.  Returns a reference to the message itself,
-   * so changes made by the caller will be committed.
-   */
-  getMessage(handle: number): MessageParam;
-  /**
-   * Get all LLM messages including system message (for LLM calls).  Owned by
-   * the transaction.
-   */
-  getLLMContext(): MessageParam[];
-
-  /**
-   * Length of context, including messages in this tx
-   */
-  getLLMContextLength(): number;
-}
-
-/**
- * Implementations of IContextManager manage the context, exposing it as an
- * array of `ChatCompletionMessageParam[]`. The system prompt is managed
- * elsewhere, and set to this object by the caller.
- */
-export interface IContextManager {
-  /**
-   * Get all LLM messages including system message (for LLM calls).
-   */
-  getLLMContext(): MessageParam[];
-
-  /**
-   * Get the "fixed" part of the system prompt
-   */
-  getAgentPrompt(): string;
-
-  /**
-   * Set the "fixed" part of the system prompt
-   */
-  setAgentPrompt(prompt: string): void;
-
-  setPromptFragment(fragmentID: string, prompt: string): void;
-
-  removePromptFragment(fragmentID: string): void;
-
-  /**
-   * Start a transaction
-   */
-  startTx(userMessages: UserMessageParam[]): Promise<IContextTransaction>;
-
-  /**
-   * Commit
-   */
-  commit(writer: IContextTransaction): Promise<void>;
-}
-
-export class ContextTransaction implements IContextTransaction {
-  private messages: MessageParam[];
-  private origLength: number;
-
-  constructor(baseMessages: MessageParam[], userMessages: UserMessageParam[]) {
-    assert(baseMessages[0].role === "system");
-    assert(baseMessages[1]?.role !== "system");
-
-    this.messages = baseMessages;
-    this.origLength = this.messages.length;
-    this.messages.push(...userMessages);
-  }
-
-  // IContextTransaction.addMessages
-  addMessages(messages: MessageParam[]): number {
-    assert(messages.every((m) => m.role !== "user"));
-    const handle = this.messages.length;
-    for (const message of messages) {
-      this.messages.push(message);
-    }
-    return handle;
-  }
-
-  // IContextTransaction.addMessage
-  addMessage(message: MessageParam): number {
-    assert(message.role !== "user");
-    const handle = this.messages.length;
-    this.messages.push(message);
-    return handle;
-  }
-
-  // IContextTransaction.getMessage
-  getMessage(handle: number): MessageParam {
-    assert(handle < this.messages.length);
-    return this.messages[handle];
-  }
-
-  // IContextTransaction.getLLMContext
-  getLLMContext(): MessageParam[] {
-    return this.messages;
-  }
-
-  // IContextTransaction.getLLMContextLength
-  getLLMContextLength(): number {
-    return this.messages.length;
-  }
-
-  newMessages(): MessageParam[] {
-    return this.messages.slice(this.origLength);
-  }
-
-  protected getLLMContextOrigLength(): number {
-    return this.origLength;
-  }
-
-  protected lastMessage(): MessageParam | undefined {
-    if (this.messages.length > 1) {
-      return this.messages[this.messages.length - 1];
-    }
-    return undefined;
-  }
-
-  popMessage(): MessageParam | undefined {
-    if (this.messages.length > this.origLength) {
-      return this.messages.pop();
-    }
-    return undefined;
-  }
-}
-
-/**
- * Trivial implementation of IContextManage which just manages the context as
- * an array of `ChatCompletionMessageParam[]`
- */
-export class ContextManager implements IContextManager {
-  private messages: MessageParam[];
-  private systemPromptProvider: SystemPromptProvider;
-
-  constructor(systemPrompt: string, messages: MessageParam[]) {
-    assert(messages.length === 0 || messages[0].role !== "system");
-
-    // Insert system message at the beginning if not present
-    if (messages.length === 0 || messages[0].role !== "system") {
-      this.messages = [
-        {
-          role: "system",
-          content: "",
-        } as MessageParam,
-        ...messages,
-      ];
-    } else {
-      assert(false);
-      // this.messages = [...conversationMessages];
-      // this.messages[0] = {systemPrompt;
-    }
-
-    this.systemPromptProvider = new SystemPromptProvider(systemPrompt);
-  }
-
-  // IContextManager.getLLMContext
-  getLLMContext(): MessageParam[] {
-    return this.getLLMContextRaw().slice();
-  }
-
-  // IContextManager.getAgentPrompt
-  getAgentPrompt(): string {
-    return this.systemPromptProvider.getAgentPrompt();
-  }
-
-  // IContextManager.setAgentPrompt
-  setAgentPrompt(prompt: string): void {
-    this.systemPromptProvider.setAgentPrompt(prompt);
-  }
-
-  // IContextManager.setPromptFragment
-  setPromptFragment(fragmentID: string, prompt: string) {
-    this.systemPromptProvider.setFragment(fragmentID, prompt);
-  }
-
-  // IContextManager.removePromptFragment
-  removePromptFragment(fragmentID: string) {
-    this.systemPromptProvider.removeFragment(fragmentID);
-  }
-
-  // IContextManager.startTx
-  startTx(userMessages: UserMessageParam[]): Promise<ContextTransaction> {
-    return Promise.resolve(
-      new ContextTransaction(this.getLLMContext(), userMessages)
-    );
-  }
-
-  // IContextManager.commit
-  commit(writer: IContextTransaction): Promise<void> {
-    assert(writer instanceof ContextTransaction);
-    const newMessages = writer.newMessages();
-    this.messages.push(...newMessages);
-    return Promise.resolve();
-  }
-
-  clear(): void {
-    this.messages = [
-      {
-        role: "system",
-        content: "",
-      },
-    ];
-  }
-
-  protected lastMessage(): MessageParam | undefined {
-    if (this.messages.length > 1) {
-      return this.messages[this.messages.length - 1];
-    }
-    return undefined;
-  }
-
-  protected numMessages(): number {
-    return this.messages.length - 1;
-  }
-
-  protected leadingMessages(numMessages: number): MessageParam[] {
-    return this.messages.slice(1, numMessages + 1);
-  }
-
-  protected trailingMessagesFrom(idx: number): MessageParam[] {
-    return this.messages.slice(1 + idx);
-  }
-
-  protected replaceLeadingMessages(
-    numMessagesToReplace: number,
-    replacement: MessageParam
-  ): void {
-    assert(this.messages.length >= 1 + numMessagesToReplace);
-    const remainingMsgs = this.messages.slice(1 + numMessagesToReplace);
-    this.messages = [this.messages[0], replacement, ...remainingMsgs];
-  }
-
-  protected popMessage(): MessageParam | undefined {
-    if (this.messages.length > 1) {
-      return this.messages.pop();
-    }
-    return undefined;
-  }
-
-  protected pushMessage(...msgs: MessageParam[]) {
-    this.messages.push(...msgs);
-  }
-
-  /// Returns the actual array (so that child classes can avoid an unnecessary
-  /// copy)
-  protected getLLMContextRaw(): MessageParam[] {
-    assert(this.messages[0].role === "system");
-    this.messages[0].content = this.systemPromptProvider.getSystemPrompt();
-    return this.messages;
-  }
-}