@iqai/adk 0.5.0 → 0.5.2

package/dist/index.mjs

@@ -3389,6 +3389,11 @@ var EventActions = class {
    * Requested authentication configurations.
    */
   requestedAuthConfigs;
+  /**
+   * Event compaction information. When set, this event represents
+   * a compaction of events within the specified timestamp range.
+   */
+  compaction;
   /**
    * Constructor for EventActions
    */
@@ -3399,6 +3404,7 @@ var EventActions = class {
     this.transferToAgent = options.transferToAgent;
     this.escalate = options.escalate;
     this.requestedAuthConfigs = options.requestedAuthConfigs;
+    this.compaction = options.compaction;
   }
 };
 
@@ -3941,9 +3947,196 @@ init_logger();
 var events_exports = {};
 __export(events_exports, {
   Event: () => Event,
-  EventActions: () => EventActions
+  EventActions: () => EventActions,
+  LlmEventSummarizer: () => LlmEventSummarizer,
+  runCompactionForSlidingWindow: () => runCompactionForSlidingWindow
 });
 
+// src/events/llm-event-summarizer.ts
+var DEFAULT_SUMMARIZATION_PROMPT = `You are a helpful assistant tasked with summarizing a conversation history.
+Please provide a concise summary of the following events, capturing the key information and context.
+Focus on the main topics discussed, important decisions made, and any action items or results.
+
+Events to summarize:
+{events}
+
+Provide your summary in a clear, concise format.`;
+var LlmEventSummarizer = class {
+  model;
+  prompt;
+  /**
+   * Creates a new LLM event summarizer.
+   * @param model - The LLM model to use for summarization
+   * @param prompt - Optional custom prompt template. Use {events} as placeholder for event content.
+   */
+  constructor(model, prompt) {
+    this.model = model;
+    this.prompt = prompt || DEFAULT_SUMMARIZATION_PROMPT;
+  }
+  /**
+   * Summarizes events using the configured LLM.
+   */
+  async maybeSummarizeEvents(events) {
+    if (!events || events.length === 0) {
+      return void 0;
+    }
+    const eventsText = this.formatEventsForSummarization(events);
+    const promptWithEvents = this.prompt.replace("{events}", eventsText);
+    const llmRequest = new LlmRequest({
+      contents: [
+        {
+          role: "user",
+          parts: [{ text: promptWithEvents }]
+        }
+      ]
+    });
+    let summaryText = "";
+    for await (const response of this.model.generateContentAsync(llmRequest)) {
+      summaryText += response.content?.parts?.map((part) => part.text || "").join("");
+    }
+    summaryText = summaryText.trim();
+    if (!summaryText) {
+      return void 0;
+    }
+    const summaryContent = {
+      role: "model",
+      parts: [{ text: summaryText }]
+    };
+    const compactionEvent = new Event({
+      invocationId: Event.newId(),
+      author: "user",
+      actions: new EventActions({
+        compaction: {
+          startTimestamp: events[0].timestamp,
+          endTimestamp: events[events.length - 1].timestamp,
+          compactedContent: summaryContent
+        }
+      })
+    });
+    return compactionEvent;
+  }
+  /**
+   * Formats events into a readable text format for summarization.
+   */
+  formatEventsForSummarization(events) {
+    const lines = [];
+    for (const event of events) {
+      const timestamp = new Date(event.timestamp * 1e3).toISOString();
+      const author = event.author;
+      if (event.content?.parts) {
+        for (const part of event.content.parts) {
+          if (part.text) {
+            lines.push(`[${timestamp}] ${author}: ${part.text}`);
+          } else if (part.functionCall) {
+            lines.push(
+              `[${timestamp}] ${author}: Called tool '${part.functionCall.name}' with args ${JSON.stringify(part.functionCall.args)}`
+            );
+          } else if (part.functionResponse) {
+            lines.push(
+              `[${timestamp}] ${author}: Tool '${part.functionResponse.name}' returned: ${JSON.stringify(part.functionResponse.response)}`
+            );
+          }
+        }
+      }
+    }
+    return lines.join("\n");
+  }
+};
+
+// src/events/compaction.ts
+init_logger();
+var logger = new Logger({ name: "EventCompaction" });
+async function runCompactionForSlidingWindow(config, session, sessionService, summarizer) {
+  if (!session.events || session.events.length === 0) {
+    return;
+  }
+  const lastCompactedEndTimestamp = findLastCompactedEndTimestamp(
+    session.events
+  );
+  const latestTimestampByInvocation = buildLatestTimestampByInvocation(
+    session.events
+  );
+  const uniqueInvocationIds = Array.from(latestTimestampByInvocation.keys());
+  const newInvocationIds = uniqueInvocationIds.filter(
+    (invId) => (latestTimestampByInvocation.get(invId) || 0) > lastCompactedEndTimestamp
+  );
+  if (newInvocationIds.length < config.compactionInterval) {
+    logger.debug(
+      `Not enough new invocations for compaction. Need ${config.compactionInterval}, have ${newInvocationIds.length}`
+    );
+    return;
+  }
+  const endInvId = newInvocationIds[newInvocationIds.length - 1];
+  const firstNewInvId = newInvocationIds[0];
+  const firstNewInvIdx = uniqueInvocationIds.indexOf(firstNewInvId);
+  const startIdx = Math.max(0, firstNewInvIdx - config.overlapSize);
+  const startInvId = uniqueInvocationIds[startIdx];
+  logger.debug(
+    `Compacting invocations from ${startInvId} to ${endInvId} (${newInvocationIds.length} new invocations, overlap: ${config.overlapSize})`
+  );
+  const eventsToCompact = sliceEventsByInvocationRange(
+    session.events,
+    startInvId,
+    endInvId
+  );
+  if (eventsToCompact.length === 0) {
+    logger.debug("No events to compact after filtering");
+    return;
+  }
+  logger.debug(`Summarizing ${eventsToCompact.length} events`);
+  const compactionEvent = await summarizer.maybeSummarizeEvents(eventsToCompact);
+  if (compactionEvent) {
+    logger.debug(
+      `Compaction created covering timestamps ${compactionEvent.actions.compaction?.startTimestamp} to ${compactionEvent.actions.compaction?.endTimestamp}`
+    );
+    await sessionService.appendEvent(session, compactionEvent);
+  }
+}
+function findLastCompactedEndTimestamp(events) {
+  for (let i = events.length - 1; i >= 0; i--) {
+    const event = events[i];
+    if (event.actions?.compaction) {
+      return event.actions.compaction.endTimestamp;
+    }
+  }
+  return 0;
+}
+function buildLatestTimestampByInvocation(events) {
+  const latestByInvocation = /* @__PURE__ */ new Map();
+  for (const event of events) {
+    if (event.actions?.compaction) {
+      continue;
+    }
+    const invId = event.invocationId;
+    if (!invId) {
+      continue;
+    }
+    const current = latestByInvocation.get(invId) || 0;
+    if (event.timestamp > current) {
+      latestByInvocation.set(invId, event.timestamp);
+    }
+  }
+  return latestByInvocation;
+}
+function sliceEventsByInvocationRange(events, startInvId, endInvId) {
+  let firstIndex = -1;
+  let lastIndex = -1;
+  for (let i = 0; i < events.length; i++) {
+    const event = events[i];
+    if (event.invocationId === startInvId && firstIndex === -1) {
+      firstIndex = i;
+    }
+    if (event.invocationId === endInvId) {
+      lastIndex = i;
+    }
+  }
+  if (firstIndex === -1 || lastIndex === -1 || firstIndex > lastIndex) {
+    return [];
+  }
+  const slicedEvents = events.slice(firstIndex, lastIndex + 1);
+  return slicedEvents.filter((event) => !event.actions?.compaction);
+}
+
 // src/flows/llm-flows/base-llm-flow.ts
 init_logger();
 
@@ -7393,8 +7586,8 @@ var BasicLlmRequestProcessor = class extends BaseLlmRequestProcessor {
       } else {
         (() => {
           try {
-            const logger = new Logger({ name: "BasicLlmRequestProcessor" });
-            logger.debug(
+            const logger2 = new Logger({ name: "BasicLlmRequestProcessor" });
+            logger2.debug(
               `Skipping request-level output schema for agent ${agent.name} because tools/transfers are present. Schema will be validated during response processing.`
             );
           } catch (e) {
@@ -8296,7 +8489,8 @@ function getContents(currentBranch, events, agentName = "") {
       isOtherAgentReply(agentName, event) ? convertForeignEvent(event) : event
     );
   }
-  let resultEvents = rearrangeEventsForLatestFunctionResponse(filteredEvents);
+  const processedEvents = processCompactionEvents(filteredEvents);
+  let resultEvents = rearrangeEventsForLatestFunctionResponse(processedEvents);
   resultEvents = rearrangeEventsForAsyncFunctionResponsesInHistory(resultEvents);
   const contents = [];
   for (const event of resultEvents) {
@@ -8408,6 +8602,31 @@ function isAuthEvent(event) {
   }
   return false;
 }
+function processCompactionEvents(events) {
+  const result = [];
+  let lastCompactionStartTime = Number.POSITIVE_INFINITY;
+  for (let i = events.length - 1; i >= 0; i--) {
+    const event = events[i];
+    if (event.actions?.compaction) {
+      const compaction = event.actions.compaction;
+      const synthesizedEvent = new Event({
+        timestamp: compaction.endTimestamp,
+        author: "model",
+        content: compaction.compactedContent,
+        branch: event.branch,
+        invocationId: event.invocationId
+      });
+      result.unshift(synthesizedEvent);
+      lastCompactionStartTime = Math.min(
+        lastCompactionStartTime,
+        compaction.startTimestamp
+      );
+    } else if (event.timestamp < lastCompactionStartTime) {
+      result.unshift(event);
+    }
+  }
+  return result;
+}
 
 // src/flows/llm-flows/identity.ts
 var IdentityLlmRequestProcessor = class extends BaseLlmRequestProcessor {
@@ -8777,14 +8996,7 @@ var NlPlanningRequestProcessor = class extends BaseLlmRequestProcessor {
       llmRequest
     );
     if (planningInstruction) {
-      if (llmRequest.appendInstructions) {
-        llmRequest.appendInstructions([planningInstruction]);
-      } else {
-        const existingInstructions = llmRequest.instructions || "";
-        llmRequest.instructions = `${existingInstructions}
-
-${planningInstruction}`;
-      }
+      llmRequest.appendInstructions([planningInstruction]);
     }
     removeThoughtFromRequest(llmRequest);
     for await (const _ of []) {
@@ -9876,7 +10088,7 @@ init_logger();
 import { generateId } from "ai";
 
 // src/runners.ts
-import { SpanStatusCode, context as context3, trace as trace3 } from "@opentelemetry/api";
+import { context as context3, SpanStatusCode, trace as trace3 } from "@opentelemetry/api";
 
 // src/agents/run-config.ts
 var StreamingMode = /* @__PURE__ */ ((StreamingMode2) => {
@@ -10464,6 +10676,10 @@ var Runner = class {
    * The memory service for the runner.
    */
   memoryService;
+  /**
+   * Configuration for event compaction.
+   */
+  eventsCompactionConfig;
   logger = new Logger({ name: "Runner" });
   /**
    * Initializes the Runner.
@@ -10473,13 +10689,15 @@ var Runner = class {
     agent,
     artifactService,
     sessionService,
-    memoryService
+    memoryService,
+    eventsCompactionConfig
   }) {
     this.appName = appName;
     this.agent = agent;
     this.artifactService = artifactService;
     this.sessionService = sessionService;
     this.memoryService = memoryService;
+    this.eventsCompactionConfig = eventsCompactionConfig;
   }
   /**
    * Runs the agent synchronously.
@@ -10581,6 +10799,10 @@ var Runner = class {
         }
         yield event;
       }
+      await context3.with(
+        spanContext,
+        () => this._runCompaction(session, invocationContext)
+      );
     } catch (error) {
       this.logger.debug("Error running agent:", error);
       span.recordException(error);
@@ -10693,6 +10915,52 @@ var Runner = class {
       runConfig
     });
   }
+  /**
+   * Runs compaction if configured.
+   */
+  async _runCompaction(session, _invocationContext) {
+    if (!this.eventsCompactionConfig) {
+      return;
+    }
+    const summarizer = this._getOrCreateSummarizer();
+    if (!summarizer) {
+      this.logger.warn(
+        "Event compaction configured but no summarizer available"
+      );
+      return;
+    }
+    try {
+      await runCompactionForSlidingWindow(
+        this.eventsCompactionConfig,
+        session,
+        this.sessionService,
+        summarizer
+      );
+    } catch (error) {
+      this.logger.error("Error running compaction:", error);
+    }
+  }
+  /**
+   * Gets the configured summarizer or creates a default LLM-based one.
+   */
+  _getOrCreateSummarizer() {
+    if (this.eventsCompactionConfig?.summarizer) {
+      return this.eventsCompactionConfig.summarizer;
+    }
+    if (this.agent instanceof LlmAgent) {
+      try {
+        const model = this.agent.canonicalModel;
+        return new LlmEventSummarizer(model);
+      } catch (error) {
+        this.logger.warn(
+          "Could not get canonical model for default summarizer:",
+          error
+        );
+        return void 0;
+      }
+    }
+    return void 0;
+  }
 };
 var InMemoryRunner = class extends Runner {
   /**
@@ -10722,6 +10990,7 @@ var AgentBuilder = class _AgentBuilder {
   sessionOptions;
   memoryService;
   artifactService;
+  eventsCompactionConfig;
   agentType = "llm";
   existingSession;
   existingAgent;
@@ -10935,6 +11204,14 @@ var AgentBuilder = class _AgentBuilder {
     this.config.afterToolCallback = callback;
     return this;
   }
+  /**
+   * Convenience method to start building with an existing agent
+   * @param agent The agent instance to wrap
+   * @returns New AgentBuilder instance with agent set
+   */
+  static withAgent(agent) {
+    return new _AgentBuilder(agent.name || "default_agent").withAgent(agent);
+  }
   /**
    * Provide an already constructed agent instance. Further definition-mutating calls
    * (model/tools/instruction/etc.) will be ignored with a dev warning.
@@ -11116,6 +11393,26 @@ var AgentBuilder = class _AgentBuilder {
     this.runConfig = config instanceof RunConfig ? config : new RunConfig({ ...this.runConfig || {}, ...config });
     return this;
   }
+  /**
+   * Configure event compaction for automatic history management
+   * @param config Event compaction configuration
+   * @returns This builder instance for chaining
+   * @example
+   * ```typescript
+   * const { runner } = await AgentBuilder
+   *   .create("assistant")
+   *   .withModel("gemini-2.5-flash")
+   *   .withEventsCompaction({
+   *     compactionInterval: 10,  // Compact every 10 invocations
+   *     overlapSize: 2,          // Include 2 prior invocations
+   *   })
+   *   .build();
+   * ```
+   */
+  withEventsCompaction(config) {
+    this.eventsCompactionConfig = config;
+    return this;
+  }
   /**
    * Configure with an in-memory session with custom IDs
    * Note: In-memory sessions are created automatically by default, use this only if you need custom appName/userId
@@ -11152,7 +11449,8 @@ var AgentBuilder = class _AgentBuilder {
         agent,
         sessionService: this.sessionService,
         memoryService: this.memoryService,
-        artifactService: this.artifactService
+        artifactService: this.artifactService,
+        eventsCompactionConfig: this.eventsCompactionConfig
       };
       const baseRunner = new Runner(runnerConfig);
       runner = this.createEnhancedRunner(baseRunner, session);
@@ -13883,6 +14181,7 @@ export {
   LangGraphAgent,
   LlmAgent,
   LlmCallsLimitExceededError,
+  LlmEventSummarizer,
   LlmRequest,
   LlmResponse,
   LoadArtifactsTool,
@@ -13979,6 +14278,7 @@ export {
   registerProviders,
   removeClientFunctionCallId,
   requestProcessor,
+  runCompactionForSlidingWindow,
   shutdownTelemetry,
   telemetryService,
   traceLlmCall,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iqai/adk",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Agent Development Kit for TypeScript with multi-provider LLM support",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",