@goondan/openharness-base 0.1.3 → 0.1.5

package/dist/index.d.ts

@@ -1,9 +1,12 @@
-import { Extension, ToolDefinition } from '@goondan/openharness-types';
+import { Extension, LlmChatOptions, Message, ToolDefinition } from '@goondan/openharness-types';
 
 /**
  * BasicSystemPrompt extension — prepends a system message to the conversation
  * at the start of every turn.
  *
+ * Uses a fixed message ID so the system prompt is only appended once;
+ * subsequent turns detect the existing message and skip the append.
+ *
  * Priority 10 (HIGH) ensures it runs before other turn middleware.
  */
 declare function BasicSystemPrompt(text: string): Extension;
@@ -18,13 +21,22 @@ declare function MessageWindow(config: {
 
 /**
  * CompactionSummarize extension — when message count exceeds `threshold`,
- * removes the oldest messages and prepends a summary system message.
+ * removes the oldest messages and replaces them with an LLM-generated summary.
+ *
+ * By default, uses the agent's own LLM (`ctx.llm`) to produce the summary.
+ * A custom `summarizer` callback can override this for advanced use cases
+ * (e.g. using a cheaper model, external API, or deterministic logic).
  *
- * For MVP the "summary" is just the concatenation of removed message text.
+ * @param config.threshold - Trigger compaction when messages exceed this count.
+ * @param config.summaryPrompt - Custom system prompt for the LLM summarizer.
+ * @param config.summarizer - Optional override: produce summary text from messages.
  */
 declare function CompactionSummarize(config: {
     threshold: number;
     summaryPrompt?: string;
+    /** LLM options for the summarization call (e.g. model override for cheaper summarization). */
+    llmOptions?: LlmChatOptions;
+    summarizer?: (messages: Message[]) => Promise<string>;
 }): Extension;
 
 /**

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/extensions/basic-system-prompt.ts
-import { randomUUID } from "crypto";
+var SYSTEM_MESSAGE_ID = "sys-basic-system-prompt";
 function BasicSystemPrompt(text) {
   return {
     name: "basic-system-prompt",
@@ -7,19 +7,24 @@ function BasicSystemPrompt(text) {
       api.pipeline.register(
         "turn",
         async (ctx, next) => {
-          ctx.conversation.emit({
-            type: "append",
-            message: {
-              id: `sys-${randomUUID()}`,
-              data: {
-                role: "system",
-                content: text
-              },
-              metadata: {
-                __createdBy: "basic-system-prompt"
+          const alreadyExists = ctx.conversation.messages.some(
+            (m) => m.id === SYSTEM_MESSAGE_ID
+          );
+          if (!alreadyExists) {
+            ctx.conversation.emit({
+              type: "append",
+              message: {
+                id: SYSTEM_MESSAGE_ID,
+                data: {
+                  role: "system",
+                  content: text
+                },
+                metadata: {
+                  __createdBy: "basic-system-prompt"
+                }
               }
-            }
-          });
+            });
+          }
           return next();
         },
         { priority: 10 }
@@ -47,7 +52,13 @@ function MessageWindow(config) {
 }
 
 // src/extensions/compaction-summarize.ts
-import { randomUUID as randomUUID2 } from "crypto";
+import { randomUUID } from "crypto";
+var DEFAULT_SUMMARY_PROMPT = "You are a conversation compactor. Summarize the following messages into a concise summary that preserves all important context, decisions, facts, and action items. Be thorough but brief. Output only the summary text, nothing else.";
+function messageToText(m) {
+  const role = m.data.role;
+  const content = typeof m.data.content === "string" ? m.data.content : JSON.stringify(m.data.content);
+  return `[${role}]: ${content}`;
+}
 function CompactionSummarize(config) {
   return {
     name: "compaction-summarize",
@@ -58,16 +69,36 @@ function CompactionSummarize(config) {
           const keepCount = Math.floor(config.threshold / 2);
           const removeCount = messages.length - keepCount;
           const toRemove = messages.slice(0, removeCount);
-          const summaryText = toRemove.map(
-            (m) => typeof m.data.content === "string" ? m.data.content : JSON.stringify(m.data.content)
-          ).join(" ");
-          for (const msg of toRemove) {
+          let summaryText;
+          if (config.summarizer) {
+            summaryText = await config.summarizer([...toRemove]);
+          } else {
+            const transcript = toRemove.map(messageToText).join("\n");
+            const prompt = config.summaryPrompt ?? DEFAULT_SUMMARY_PROMPT;
+            const llmResponse = await ctx.llm.chat(
+              [
+                { id: `compaction-sys-${randomUUID()}`, data: { role: "system", content: prompt }, metadata: {} },
+                { id: `compaction-usr-${randomUUID()}`, data: { role: "user", content: transcript }, metadata: {} }
+              ],
+              [],
+              // no tools needed for summarization
+              ctx.abortSignal,
+              config.llmOptions
+            );
+            summaryText = llmResponse.text ?? transcript;
+          }
+          const [firstToRemove, ...restToRemove] = toRemove;
+          ctx.conversation.emit({
+            type: "remove",
+            messageId: firstToRemove.id
+          });
+          for (const msg of restToRemove) {
             ctx.conversation.emit({ type: "remove", messageId: msg.id });
           }
           ctx.conversation.emit({
             type: "append",
             message: {
-              id: `summary-${randomUUID2()}`,
+              id: `summary-${randomUUID()}`,
               data: {
                 role: "system",
                 content: `[Summary of earlier conversation]: ${summaryText}`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goondan/openharness-base",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "exports": {
     ".": {
@@ -9,7 +9,7 @@
     }
   },
   "dependencies": {
-    "@goondan/openharness-types": "0.1.3"
+    "@goondan/openharness-types": "0.1.5"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",

package/src/__tests__/basic-system-prompt.test.ts

@@ -82,6 +82,7 @@ function makeTurnContext(conversation: ConversationState): TurnContext {
         receivedAt: new Date().toISOString(),
       },
     },
+    llm: { chat: vi.fn().mockResolvedValue({ text: "mock" }) },
   };
 }
 
@@ -147,9 +148,39 @@ describe("BasicSystemPrompt", () => {
     const emittedEvent = conversation.emitted[0];
     expect(emittedEvent.type).toBe("append");
     if (emittedEvent.type === "append") {
+      expect(emittedEvent.message.id).toBe("sys-basic-system-prompt");
       expect(emittedEvent.message.data.role).toBe("system");
       expect(emittedEvent.message.data.content).toBe("You are helpful.");
       expect(emittedEvent.message.metadata?.__createdBy).toBe("basic-system-prompt");
     }
   });
+
+  it("does not duplicate the system message on subsequent turns", async () => {
+    const conversation = makeMockConversationState();
+    const { api, registeredMiddleware } = makeMockApi(conversation);
+
+    const ext = BasicSystemPrompt("You are helpful.");
+    ext.register(api);
+
+    const middleware = registeredMiddleware[0].handler;
+    const next = vi.fn(async () => stubTurnResult);
+
+    // First turn — should append
+    const ctx1 = makeTurnContext(conversation);
+    await middleware(ctx1, next);
+    expect(conversation.emitted).toHaveLength(1);
+
+    // Second turn — system message already in conversation.messages, should skip
+    const ctx2 = makeTurnContext(conversation);
+    await middleware(ctx2, next);
+    expect(conversation.emitted).toHaveLength(1); // still 1, no new append
+
+    // Third turn — still no duplication
+    const ctx3 = makeTurnContext(conversation);
+    await middleware(ctx3, next);
+    expect(conversation.emitted).toHaveLength(1);
+
+    // next() should have been called every turn
+    expect(next).toHaveBeenCalledTimes(3);
+  });
 });

package/src/__tests__/compaction-summarize.test.ts

@@ -83,6 +83,12 @@ function makeMockApi(conversation: ConversationState): {
   return { api, registeredMiddleware };
 }
 
+function makeMockLlmClient() {
+  return {
+    chat: vi.fn().mockResolvedValue({ text: "LLM-generated summary of the conversation." }),
+  };
+}
+
 function makeStepContext(conversation: ConversationState): StepContext {
   return {
     turnId: "turn-1",
@@ -101,6 +107,7 @@ function makeStepContext(conversation: ConversationState): StepContext {
         receivedAt: new Date().toISOString(),
       },
     },
+    llm: makeMockLlmClient(),
   };
 }
 
@@ -223,12 +230,53 @@ describe("CompactionSummarize", () => {
 
     await middleware(ctx, next);
 
+    // Verify LLM was called for summarization
+    expect(ctx.llm.chat).toHaveBeenCalledOnce();
+
     const emitted = (conversation as ReturnType<typeof makeMockConversationState>).emitted;
     const appendEvent = emitted.find((e) => e.type === "append");
     if (appendEvent && appendEvent.type === "append") {
       const content = appendEvent.message.data.content as string;
-      // Should include text from the removed messages
-      expect(content).toContain("Message 0");
+      // Should include the LLM-generated summary
+      expect(content).toContain("LLM-generated summary of the conversation.");
     }
   });
+
+  it("uses custom summarizer when provided", async () => {
+    const messages = makeMessages(12);
+    const conversation = makeMockConversationState(messages);
+    const { api, registeredMiddleware } = makeMockApi(conversation);
+
+    const summarizer = vi.fn(async (msgs: Message[]) => {
+      return `Custom summary of ${msgs.length} messages`;
+    });
+
+    const ext = CompactionSummarize({ threshold: 10, summarizer });
+    ext.register(api);
+
+    const middleware = registeredMiddleware[0].handler;
+    const ctx = makeStepContext(conversation);
+    const next = vi.fn(async () => stubStepResult);
+
+    await middleware(ctx, next);
+
+    // summarizer should have been called with the 7 removed messages
+    expect(summarizer).toHaveBeenCalledOnce();
+    expect(summarizer).toHaveBeenCalledWith(
+      expect.arrayContaining([
+        expect.objectContaining({ id: "msg-0" }),
+        expect.objectContaining({ id: "msg-6" }),
+      ]),
+    );
+    expect(summarizer.mock.calls[0][0]).toHaveLength(7);
+
+    const emitted = (conversation as ReturnType<typeof makeMockConversationState>).emitted;
+    const appendEvent = emitted.find((e) => e.type === "append");
+    if (appendEvent && appendEvent.type === "append") {
+      const content = appendEvent.message.data.content as string;
+      expect(content).toContain("Custom summary of 7 messages");
+    }
+
+    expect(next).toHaveBeenCalledOnce();
+  });
 });

package/src/__tests__/message-window.test.ts

@@ -101,6 +101,7 @@ function makeStepContext(conversation: ConversationState): StepContext {
         receivedAt: new Date().toISOString(),
       },
     },
+    llm: { chat: vi.fn().mockResolvedValue({ text: "mock" }) },
   };
 }
 

package/src/__tests__/required-tools-guard.test.ts

@@ -86,6 +86,7 @@ function makeTurnContext(conversation: ConversationState): TurnContext {
         receivedAt: new Date().toISOString(),
       },
     },
+    llm: { chat: vi.fn().mockResolvedValue({ text: "mock" }) },
   };
 }
 

package/src/extensions/basic-system-prompt.ts

@@ -1,10 +1,14 @@
 import type { Extension, ExtensionApi } from "@goondan/openharness-types";
-import { randomUUID } from "node:crypto";
+
+const SYSTEM_MESSAGE_ID = "sys-basic-system-prompt";
 
 /**
  * BasicSystemPrompt extension — prepends a system message to the conversation
  * at the start of every turn.
  *
+ * Uses a fixed message ID so the system prompt is only appended once;
+ * subsequent turns detect the existing message and skip the append.
+ *
  * Priority 10 (HIGH) ensures it runs before other turn middleware.
  */
 export function BasicSystemPrompt(text: string): Extension {
@@ -15,19 +19,26 @@ export function BasicSystemPrompt(text: string): Extension {
       api.pipeline.register(
         "turn",
         async (ctx, next) => {
-          ctx.conversation.emit({
-            type: "append",
-            message: {
-              id: `sys-${randomUUID()}`,
-              data: {
-                role: "system",
-                content: text,
-              },
-              metadata: {
-                __createdBy: "basic-system-prompt",
+          const alreadyExists = ctx.conversation.messages.some(
+            (m) => m.id === SYSTEM_MESSAGE_ID,
+          );
+
+          if (!alreadyExists) {
+            ctx.conversation.emit({
+              type: "append",
+              message: {
+                id: SYSTEM_MESSAGE_ID,
+                data: {
+                  role: "system",
+                  content: text,
+                },
+                metadata: {
+                  __createdBy: "basic-system-prompt",
+                },
               },
-            },
-          });
+            });
+          }
+
           return next();
         },
         { priority: 10 },

package/src/extensions/compaction-summarize.ts

@@ -1,15 +1,41 @@
-import type { Extension, ExtensionApi } from "@goondan/openharness-types";
+import type { Extension, ExtensionApi, Message, LlmChatOptions } from "@goondan/openharness-types";
 import { randomUUID } from "node:crypto";
 
+const DEFAULT_SUMMARY_PROMPT =
+  "You are a conversation compactor. Summarize the following messages into a concise summary " +
+  "that preserves all important context, decisions, facts, and action items. " +
+  "Be thorough but brief. Output only the summary text, nothing else.";
+
+/**
+ * Extract plain-text representation of a Message for summarization.
+ */
+function messageToText(m: Message): string {
+  const role = m.data.role;
+  const content =
+    typeof m.data.content === "string"
+      ? m.data.content
+      : JSON.stringify(m.data.content);
+  return `[${role}]: ${content}`;
+}
+
 /**
  * CompactionSummarize extension — when message count exceeds `threshold`,
- * removes the oldest messages and prepends a summary system message.
+ * removes the oldest messages and replaces them with an LLM-generated summary.
+ *
+ * By default, uses the agent's own LLM (`ctx.llm`) to produce the summary.
+ * A custom `summarizer` callback can override this for advanced use cases
+ * (e.g. using a cheaper model, external API, or deterministic logic).
  *
- * For MVP the "summary" is just the concatenation of removed message text.
+ * @param config.threshold - Trigger compaction when messages exceed this count.
+ * @param config.summaryPrompt - Custom system prompt for the LLM summarizer.
+ * @param config.summarizer - Optional override: produce summary text from messages.
  */
 export function CompactionSummarize(config: {
   threshold: number;
   summaryPrompt?: string;
+  /** LLM options for the summarization call (e.g. model override for cheaper summarization). */
+  llmOptions?: LlmChatOptions;
+  summarizer?: (messages: Message[]) => Promise<string>;
 }): Extension {
   return {
     name: "compaction-summarize",
@@ -22,21 +48,41 @@ export function CompactionSummarize(config: {
           const removeCount = messages.length - keepCount;
           const toRemove = messages.slice(0, removeCount);
 
-          // Build a naive summary from removed messages
-          const summaryText = toRemove
-            .map((m) =>
-              typeof m.data.content === "string"
-                ? m.data.content
-                : JSON.stringify(m.data.content),
-            )
-            .join(" ");
-
-          // Remove old messages
-          for (const msg of toRemove) {
+          let summaryText: string;
+
+          if (config.summarizer) {
+            // User-provided summarizer takes precedence
+            summaryText = await config.summarizer([...toRemove]);
+          } else {
+            // Default: LLM-based summarization via ctx.llm
+            const transcript = toRemove.map(messageToText).join("\n");
+            const prompt = config.summaryPrompt ?? DEFAULT_SUMMARY_PROMPT;
+
+            const llmResponse = await ctx.llm.chat(
+              [
+                { id: `compaction-sys-${randomUUID()}`, data: { role: "system", content: prompt }, metadata: {} },
+                { id: `compaction-usr-${randomUUID()}`, data: { role: "user", content: transcript }, metadata: {} },
+              ],
+              [], // no tools needed for summarization
+              ctx.abortSignal,
+              config.llmOptions,
+            );
+
+            summaryText = llmResponse.text ?? transcript;
+          }
+
+          // Remove old messages, replace first with summary for stable ordering
+          const [firstToRemove, ...restToRemove] = toRemove;
+          // Replace the first message with the summary
+          ctx.conversation.emit({
+            type: "remove",
+            messageId: firstToRemove.id,
+          });
+          for (const msg of restToRemove) {
             ctx.conversation.emit({ type: "remove", messageId: msg.id });
           }
 
-          // Prepend summary
+          // Prepend summary as a system message
           ctx.conversation.emit({
             type: "append",
             message: {