@xalia/agent 0.6.8 → 0.6.10

package/src/agent/documentSummarizer.ts

@@ -0,0 +1,157 @@
+import { getOpenAIClient } from "../chat/server/openAIRouterLLM";
+import { getLogger } from "@xalia/xmcp/sdk";
+
+const logger = getLogger();
+
+const SUMMARY_MODEL = "google/gemini-2.5-flash";
+const SUMMARY_MAX_TOKENS = 500;
+const SUMMARY_TEMPERATURE = 0.3;
+const SUMMARY_TIMEOUT_MS = 30000;
+const MAX_CONTENT_LENGTH = 100000;
+
+/**
+ * System prompt for document summarization, optimized for recall.
+ */
+const SUMMARY_SYSTEM_PROMPT =
+  `You are a document summarizer optimizing for RECALL. Create a summary ` +
+  `(3-10 sentences) that captures:
+- Main topic and purpose of the document
+- Key entities (names, organizations, places, dates, numbers)
+- Important concepts, terms, and topics mentioned
+- Any conclusions, results, or key findings
+
+Include specific details that would help locate this document later.
+Use keywords and phrases from the original text.
+Do NOT include meta-commentary about the document format.
+Output ONLY the summary text.`;
+
+export interface IDocumentSummarizer {
+  summarize(content: string): Promise<string>;
+}
+
+export class LLMDocumentSummarizer implements IDocumentSummarizer {
+  private model: string;
+
+  constructor(model: string = SUMMARY_MODEL) {
+    this.model = model;
+  }
+
+  async summarize(content: string): Promise<string> {
+    if (!content || content.trim().length === 0) {
+      return "Empty document";
+    }
+
+    try {
+      const summary = await this.summarizeWithTimeout(content);
+      return this.sanitizeSummary(summary);
+    } catch (error) {
+      const errorMsg = error instanceof Error ? error.message : String(error);
+      logger.warn(
+        `[DocumentSummarizer] LLM summarization failed: ${errorMsg}, ` +
+          `using fallback`
+      );
+      return this.fallbackSummary(content);
+    }
+  }
+
+  private async summarizeWithTimeout(content: string): Promise<string> {
+    const timeoutPromise = new Promise<never>((_, reject) => {
+      setTimeout(() => {
+        reject(new Error("Summary generation timeout"));
+      }, SUMMARY_TIMEOUT_MS);
+    });
+
+    const summaryPromise = this.callLLM(content);
+
+    return Promise.race([summaryPromise, timeoutPromise]);
+  }
+
+  private async callLLM(content: string): Promise<string> {
+    const client = getOpenAIClient(this.model);
+
+    const truncatedContent =
+      content.length > MAX_CONTENT_LENGTH
+        ? content.slice(0, MAX_CONTENT_LENGTH) + "\n\n[Content truncated...]"
+        : content;
+
+    const response = await client.chat.completions.create({
+      model: this.model,
+      messages: [
+        {
+          role: "system",
+          content: SUMMARY_SYSTEM_PROMPT,
+        },
+        {
+          role: "user",
+          content: `Please summarize this document:\n\n${truncatedContent}`,
+        },
+      ],
+      max_tokens: SUMMARY_MAX_TOKENS,
+      temperature: SUMMARY_TEMPERATURE,
+    });
+
+    const summary = response.choices[0]?.message?.content?.trim();
+
+    if (!summary) {
+      throw new Error("Empty response from LLM");
+    }
+
+    return summary;
+  }
+
+  private sanitizeSummary(summary: string): string {
+    return summary.replace(/\s+/g, " ").trim();
+  }
+
+  private fallbackSummary(content: string): string {
+    const cleaned = content.trim();
+
+    if (cleaned.length === 0) {
+      return "Empty document";
+    }
+
+    const firstParagraph = cleaned.split(/\n\n/)[0];
+    const maxLength = 500;
+
+    if (firstParagraph.length <= maxLength) {
+      return firstParagraph;
+    }
+
+    return cleaned.slice(0, maxLength).trim() + "...";
+  }
+}
+
+class FallbackDocumentSummarizer implements IDocumentSummarizer {
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async summarize(content: string): Promise<string> {
+    const cleaned = content.trim();
+
+    if (cleaned.length === 0) {
+      return "Empty document";
+    }
+
+    const firstParagraph = cleaned.split(/\n\n/)[0];
+    const maxLength = 500;
+
+    if (firstParagraph.length <= maxLength) {
+      return firstParagraph;
+    }
+
+    return cleaned.slice(0, maxLength).trim() + "...";
+  }
+}
+
+export function createDocumentSummarizer(model?: string): IDocumentSummarizer {
+  if (process.env.DISABLE_LLM_SUMMARIES === "true") {
+    return new FallbackDocumentSummarizer();
+  }
+  return new LLMDocumentSummarizer(model);
+}
+
+/**
+ * Convenience function for one-off summarization.
+ */
+export async function summarizeDocument(content: string): Promise<string> {
+  const summarizer = createDocumentSummarizer();
+  return summarizer.summarize(content);
+}

package/src/agent/dummyLLM.ts

@@ -81,39 +81,43 @@ export class DummyLLM implements ILLM {
     _tools?: ToolDescriptor[],
     onMessage?: (msg: string, msgEnd: boolean) => Promise<void>,
     onReasoning?: (reasoning: string) => Promise<void>
-  ): Promise<Completion> {
+  ): Promise<{ stop: (msg: string) => void; completion: Promise<Completion> }> {
     await new Promise((r) => setTimeout(r, 0));
-    assert(this.idx < this.responses.length);
 
     this.lastRequest = messages;
 
-    for (;;) {
-      const response = this.responses[this.idx++];
+    const completion: Promise<Completion> = (async () => {
+      for (;;) {
+        const idx = this.idx++;
+        const response = this.responses[idx % this.responses.length];
 
-      if (response.finish_reason === "error") {
-        throw new Error(response.message);
-      }
+        if (response.finish_reason === "error") {
+          throw new Error(response.message);
+        }
 
-      if (response.finish_reason === "reasoning") {
-        if (onReasoning) {
-          await onReasoning(response.message);
+        if (response.finish_reason === "reasoning") {
+          if (onReasoning) {
+            await onReasoning(response.message);
+          }
+          continue;
         }
-        continue;
-      }
 
-      if (onMessage) {
-        const message = response.message;
-        void onMessage(message.content || "", true);
+        if (onMessage) {
+          const message = response.message;
+          void onMessage(message.content || "", true);
+        }
+
+        return {
+          id: String(idx),
+          choices: [response],
+          created: Date.now(),
+          model: "dummyLlmModel",
+          object: "chat.completion",
+        };
       }
+    })();
 
-      return {
-        id: String(this.idx),
-        choices: [response],
-        created: Date.now(),
-        model: "dummyLlmModel",
-        object: "chat.completion",
-      };
-    }
+    return { stop: () => {}, completion };
   }
 
   public setModel(_model: string): void {

package/src/agent/imageGenLLM.ts

@@ -1,6 +1,5 @@
 import { OpenAI } from "openai";
 import { strict as assert } from "assert";
-import { writeFileSync } from "fs";
 
 import { getLogger } from "@xalia/xmcp/sdk";
 
@@ -54,11 +53,11 @@ export class ImageGenLLM implements ILLM {
     return this.openai.baseURL;
   }
 
-  public async getConversationResponse(
+  public getConversationResponse(
     messages: MessageParam[],
     tools?: ToolDescriptor[],
     onMessage?: (msg: string, end: boolean) => Promise<void>
-  ): Promise<Completion> {
+  ): Promise<{ stop: (msg: string) => void; completion: Promise<Completion> }> {
     assert(!tools || tools.length === 0, "tools not supported in ImageGenLLM");
 
     // Designed for image generation using openrouter, which tweaks the Create
@@ -71,35 +70,32 @@ export class ImageGenLLM implements ILLM {
 
     logger.info(`[ImageGenLLM] params; ${JSON.stringify(params)}`);
 
-    const completion = (await this.openai.chat.completions.create(
-      params as OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming
-    )) as Completion;
-
-    // const completion = {} as unknown as ChatCompletion;
-
-    const filePath: string = "./completion.json";
-    logger.info(`[ImageGenLLM] writing ${filePath}`);
-    writeFileSync(filePath, JSON.stringify(completion), "utf-8");
-    logger.info(`[ImageGenLLM] written`);
-
-    // logger.debug(
-    //   `[ImageGenLLM.getConversationResponse] completion:
-    //   ${JSON.stringify(completion)}`
-    // );
-
-    if (onMessage) {
-      const message = completion.choices[0].message;
-      if (message.content) {
-        await onMessage(message.content, true);
-      }
-      if (message.images) {
-        message.images.forEach((image, index) => {
-          const imageUrl = image.image_url.url; // Base64 data URL
-          const truncated = imageUrl.substring(0, 50);
-          logger.info(`[ImageGenLLM] ${String(index + 1)}: ${truncated}...`);
-        });
+    const completion = (async () => {
+      const completion = (await this.openai.chat.completions.create(
+        params as OpenAI.Chat.Completions.ChatCompletionCreateParamsNonStreaming
+      )) as Completion;
+
+      // logger.debug(
+      //   `[ImageGenLLM.getConversationResponse] completion:
+      //   ${JSON.stringify(completion)}`
+      // );
+
+      if (onMessage) {
+        const message = completion.choices[0].message;
+        if (message.content) {
+          await onMessage(message.content, true);
+        }
+        if (message.images) {
+          message.images.forEach((image, index) => {
+            const imageUrl = image.image_url.url; // Base64 data URL
+            const truncated = imageUrl.substring(0, 50);
+            logger.info(`[ImageGenLLM] ${String(index + 1)}: ${truncated}...`);
+          });
+        }
       }
-    }
-    return completion;
+      return completion;
+    })();
+
+    return Promise.resolve({ stop: () => {}, completion });
   }
 }

package/src/agent/imageGenerator.ts

@@ -1,10 +1,7 @@
 import { Agent, createUserMessage } from "./agent";
-import { createLLM } from "./agentUtils";
 import { ContextManager } from "./context";
 import { NULL_AGENT_EVENT_HANDLER } from "./nullAgentEventHandler";
-import { NULL_PLATFORM } from "./nullPlatform";
-import { NODE_PLATFORM } from "../tool/nodePlatform";
-import { DEFAULT_IMAGE_GEN_MODEL } from "./imageGenLLM";
+import { ILLM } from "./llm";
 
 const IMAGE_GEN_SYSTEM_PROMPT = "You are an image generator";
 
@@ -17,19 +14,7 @@ export class ImageGenerator {
     this.contextManager = contextManager;
   }
 
-  public static async init(
-    llmUrl: string,
-    llmApiKey: string,
-    model?: string
-  ): Promise<ImageGenerator> {
-    const development = !!process.env.DEVELOPMENT;
-    const llm = await createLLM(
-      llmUrl,
-      llmApiKey,
-      model || DEFAULT_IMAGE_GEN_MODEL,
-      false /* stream */,
-      development ? NODE_PLATFORM : NULL_PLATFORM // allow file loading
-    );
+  public static init(llm: ILLM): ImageGenerator {
     const contextManager = new ContextManager(IMAGE_GEN_SYSTEM_PROMPT, []);
     const agent = Agent.initializeWithLLM(
       NULL_AGENT_EVENT_HANDLER,
@@ -53,7 +38,7 @@ export class ImageGenerator {
     }
 
     // Clear the context
-    while (this.contextManager.popMessage());
+    this.contextManager.clear();
 
     return agentResponse.images[0].image_url.url;
   }

package/src/agent/llm.ts

@@ -2,7 +2,7 @@ import * as openai from "./openAI";
 import { OpenAI } from "openai";
 
 export const XALIA_APP_HEADER = {
-  "HTTP-Referer": "xalia.ai",
+  "HTTP-Referer": "https://xalia.ai",
   "X-Title": "Xalia",
 };
 
@@ -68,7 +68,7 @@ export interface ILLM {
     tools?: ToolDescriptor[],
     onMessage?: (msg: string, end: boolean) => Promise<void>,
     onReasoning?: (reasoning: string) => Promise<void>
-  ): Promise<Completion>;
+  ): Promise<{ stop: (msg: string) => void; completion: Promise<Completion> }>;
 
   setModel(model: string): void;
 }

package/src/agent/openAILLM.ts

@@ -73,23 +73,27 @@ export class OpenAILLM implements ILLM {
     return this.openai.baseURL;
   }
 
-  public async getConversationResponse(
+  public getConversationResponse(
     messages: MessageParam[],
     tools?: ToolDescriptor[],
     onMessage?: (msg: string, end: boolean) => Promise<void>
-  ): Promise<Completion> {
-    const completion = await this.openai.chat.completions.create({
-      model: this.model,
-      messages,
-      tools,
-    });
-    if (onMessage) {
-      const message = completion.choices[0].message;
-      if (message.content) {
-        await onMessage(message.content, true);
+  ): Promise<{ stop: (msg: string) => void; completion: Promise<Completion> }> {
+    const completion: Promise<Completion> = (async () => {
+      const completion = await this.openai.chat.completions.create({
+        model: this.model,
+        messages,
+        tools,
+      });
+      if (onMessage) {
+        const message = completion.choices[0].message;
+        if (message.content) {
+          await onMessage(message.content, true);
+        }
       }
-    }
 
-    return completionFromOpenAI(completion);
+      return completionFromOpenAI(completion);
+    })();
+
+    return Promise.resolve({ stop: () => {}, completion });
   }
 }

package/src/agent/openAILLMStreaming.ts

@@ -13,7 +13,6 @@ import {
   MessageParam,
   ToolDescriptor,
 } from "./llm";
-
 import {
   Reasoning,
   ChatCompletionChunkChoiceDeltaWithReasoning,
@@ -516,13 +515,31 @@ export class OpenAILLMStreaming implements ILLM {
     tools?: ToolDescriptor[],
     onMessage?: (msg: string, end: boolean) => Promise<void>,
     onReasoning?: (reasoning: string) => Promise<void>
-  ): Promise<Completion> {
+  ): Promise<{ stop: (msg: string) => void; completion: Promise<Completion> }> {
+    return OpenAILLMStreaming.makeRequest(
+      this.openai,
+      this.model,
+      messages,
+      tools,
+      onMessage,
+      onReasoning
+    );
+  }
+
+  public static async makeRequest(
+    openai: OpenAI,
+    model: string,
+    messages: MessageParam[],
+    tools?: ToolDescriptor[],
+    onMessage?: (msg: string, end: boolean) => Promise<void>,
+    onReasoning?: (reasoning: string) => Promise<void>
+  ): Promise<{ stop: (msg: string) => void; completion: Promise<Completion> }> {
     const reasoning: Reasoning = {
       effort: "medium",
       enabled: true,
     };
-    const chunks = await this.openai.chat.completions.create({
-      model: this.model,
+    const chunks = await openai.chat.completions.create({
+      model: model,
       messages,
       tools,
       stream: true,
@@ -537,56 +554,95 @@ export class OpenAILLMStreaming implements ILLM {
       throw new Error("not a stream");
     }
 
-    let aggregatedMessage: Completion | undefined;
+    let stopMsg: string | undefined = undefined;
 
-    for await (const chunk of chunks) {
-      logger.debug(`[stream] chunk: ${JSON.stringify(chunk)}`);
+    const stop = (msg: string) => {
+      stopMsg = msg;
+    };
 
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-      if (chunk.object !== "chat.completion.chunk") {
-        // logger.warn("[stream]: unexpected message");
-        continue;
-      }
+    const completion: Promise<Completion> = (async () => {
+      // Completion built up over successive calls to processChunk.
+      let aggregatedMessage: Completion | undefined;
 
-      if (!aggregatedMessage) {
-        logger.debug(`[stream] first}`);
-        const { initMessage } = initializeCompletion(chunk);
-        aggregatedMessage = initMessage;
-      } else {
-        updateCompletion(aggregatedMessage, chunk);
-      }
+      const processChunk = async (
+        chunk: OpenAI.Chat.Completions.ChatCompletionChunk
+      ) => {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (chunk.object !== "chat.completion.chunk") {
+          // logger.warn("[stream]: unexpected message");
+          return;
+        }
 
-      if (onMessage) {
-        // Inform the call of a message fragment if it contains any text.
-        // Note: chunks may have zero choices (e.g., usage-only chunks), so
-        // we safely access the first choice.
+        if (!aggregatedMessage) {
+          logger.debug(`[stream] first}`);
+          const { initMessage } = initializeCompletion(chunk);
+          aggregatedMessage = initMessage;
+        } else {
+          updateCompletion(aggregatedMessage, chunk);
+        }
 
-        const delta = chunk.choices[0]?.delta;
-        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-        if (delta?.content) {
-          await onMessage(delta.content, false);
+        if (onMessage) {
+          // Inform the call of a message fragment if it contains any text.
+          // Note: chunks may have zero choices (e.g., usage-only chunks), so
+          // we safely access the first choice.
+
+          const delta = chunk.choices[0]?.delta;
+          // eslint-disable-next-line
+          if (delta?.content) {
+            await onMessage(delta.content, false);
+          }
         }
-      }
 
-      if (onReasoning) {
-        const delta = chunk.choices[0]
-          ?.delta as ChatCompletionChunkChoiceDeltaWithReasoning;
-        const reasoning = choiceDeltaExtractReasoning(delta);
-        if (reasoning) {
-          await onReasoning(reasoning);
+        if (onReasoning) {
+          const delta = chunk.choices[0]
+            ?.delta as ChatCompletionChunkChoiceDeltaWithReasoning;
+          const reasoning = choiceDeltaExtractReasoning(delta);
+          if (reasoning) {
+            await onReasoning(reasoning);
+          }
         }
+      };
+
+      // Process each chunk, checking for a stop signal.
+      for await (const chunk of chunks) {
+        logger.debug(`[stream] chunk: ${JSON.stringify(chunk)}`);
+        await processChunk(chunk);
+
+        /* eslint-disable @typescript-eslint/no-unnecessary-condition */
+        if (stopMsg) {
+          const choice: OpenAI.Chat.Completions.ChatCompletionChunk.Choice = {
+            delta: { content: stopMsg },
+            finish_reason:
+              aggregatedMessage && aggregatedMessage.choices[0].finish_reason
+                ? null
+                : "stop",
+            index: 0,
+          };
+
+          await processChunk({
+            id: aggregatedMessage?.id || "user_stop_chunk",
+            created: aggregatedMessage?.created || Date.now(),
+            model: aggregatedMessage?.model || model,
+            object: "chat.completion.chunk",
+            choices: [choice],
+          });
+          break;
+        }
+        /* eslint-enable @typescript-eslint/no-unnecessary-condition */
       }
-    }
 
-    if (onMessage) {
-      await onMessage("", true);
-    }
+      if (onMessage) {
+        await onMessage("", true);
+      }
 
-    logger.debug(
-      `[stream] final message: ${JSON.stringify(aggregatedMessage)}`
-    );
+      logger.debug(
+        `[stream] final message: ${JSON.stringify(aggregatedMessage)}`
+      );
+
+      assert(aggregatedMessage);
+      return aggregatedMessage;
+    })();
 
-    assert(aggregatedMessage);
-    return aggregatedMessage;
+    return { stop, completion };
   }
 }

package/src/agent/repeatLLM.ts

@@ -2,8 +2,17 @@ import { Choice, Completion, ILLM, MessageParam, ToolDescriptor } from "./llm";
 import { strict as assert } from "assert";
 
 export class RepeatLLM implements ILLM {
+  private prefix: string;
   private idx: number = 0;
 
+  constructor(prefix?: string) {
+    if (prefix && prefix.length > 0) {
+      this.prefix = prefix;
+    } else {
+      this.prefix = "Message number";
+    }
+  }
+
   public getModel(): string {
     return "repeat";
   }
@@ -16,10 +25,10 @@ export class RepeatLLM implements ILLM {
     _messages: MessageParam[],
     _tools?: ToolDescriptor[],
     onMessage?: (msg: string, msgEnd: boolean) => Promise<void>
-  ): Promise<Completion> {
+  ): Promise<{ stop: () => void; completion: Promise<Completion> }> {
     await new Promise((r) => setTimeout(r, 1000));
 
-    const content = `Message number ${String(this.idx++)}`;
+    const content = `${this.prefix} ${String(this.idx++)}`;
     const response: Choice = {
       finish_reason: "stop",
       index: 0,
@@ -36,11 +45,14 @@ export class RepeatLLM implements ILLM {
     }
 
     return {
-      id: String(this.idx),
-      choices: [response],
-      created: Date.now(),
-      model: "dummyLlmModel",
-      object: "chat.completion",
+      stop: () => {},
+      completion: Promise.resolve({
+        id: String(this.idx),
+        choices: [response],
+        created: Date.now(),
+        model: "dummyLlmModel",
+        object: "chat.completion",
+      }),
     };
   }