@goondan/openharness-base 0.5.7 → 1.0.0-rc.1

package/dist/index.d.ts

@@ -1,27 +1,62 @@
-import { Extension, LlmChatOptions, Message, ToolDefinition } from '@goondan/openharness-types';
+import { AgentExtension, 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.
+ * Extension returned by {@link BasicSystemPrompt}. Carries the prompt text so
+ * consumers that used to read it off the durable system message (compaction,
+ * prewarm, slack.host) can recover it via {@link getSystemPromptText} now that
+ * the prompt lives only in the projected view.
+ */
+interface BasicSystemPromptExtension extends AgentExtension {
+    readonly systemPromptText: string;
+}
+/**
+ * Recover the system prompt text from a {@link BasicSystemPrompt} extension.
+ * Returns `undefined` for any other extension.
+ */
+declare function getSystemPromptText(extension: AgentExtension): string | undefined;
+/**
+ * BasicSystemPrompt extension — makes a system message lead the prompt on every
+ * step.
  *
- * Priority 10 (HIGH) ensures it runs before other turn middleware.
+ * As of 1.0 this is a *projection* via `useModelInput`: the system prompt is
+ * part of the throwaway model input, never the durable log. If this projection
+ * ran zero times the durable log would still be correct — which is exactly the
+ * test for "view, not mutation". A one-time turn middleware (registered with
+ * `{ before: "*" }`, so it lands at the outermost band before any step) removes
+ * the legacy persisted copy from conversations created by older versions.
  */
-declare function BasicSystemPrompt(text: string): Extension;
+declare function BasicSystemPrompt(text: string): BasicSystemPromptExtension;
 
 /**
- * MessageWindow extension — truncates conversation history to keep only
- * the most recent `maxMessages` messages before each step.
+ * MessageWindow extension — keeps the model input to roughly the most recent
+ * `maxMessages` non-system messages.
+ *
+ * As of 1.0 this is a *projection* via `useModelInput`, not a durable
+ * truncation. The old `truncate` event mutated the log and made history
+ * unrecoverable; windowing the view instead leaves the durable log intact (pair
+ * this with CompactionSummarize if the log itself needs bounding).
+ *
+ * Two boundary rules keep the windowed view valid:
+ *  - leading system messages are always retained (the view invariant requires
+ *    system messages to lead, and the system prompt must survive windowing);
+ *  - the start boundary is extended backward off any tool-result so a windowed
+ *    view never begins with an orphaned tool-result whose assistant tool-call
+ *    was dropped.
  */
 declare function MessageWindow(config: {
     maxMessages: number;
-}): Extension;
+}): AgentExtension;
 
 /**
  * CompactionSummarize extension — when message count exceeds `threshold`,
- * removes the oldest messages and replaces them with an LLM-generated summary.
+ * removes the oldest *non-system* messages and replaces them with an
+ * LLM-generated summary.
+ *
+ * This is a durable mutation, not a projection: removing history and recording a
+ * summary changes the log itself, and must survive replay. It runs as step
+ * middleware (`useStep`) so it assembles context before the model call. System
+ * messages are never folded into the summary — filtering them out keeps stale
+ * prompts/summaries out of the new 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
@@ -37,28 +72,38 @@ declare function CompactionSummarize(config: {
     /** LLM options for the summarization call (e.g. model override for cheaper summarization). */
     llmOptions?: LlmChatOptions;
     summarizer?: (messages: Message[]) => Promise<string>;
-}): Extension;
+}): AgentExtension;
 
 /**
  * Logging extension — subscribes to core events and logs them.
  */
 declare function Logging(config?: {
     logger?: (msg: string) => void;
-}): Extension;
+}): AgentExtension;
 
 /**
  * ToolSearch extension — registers a meta-tool `search_tools` that searches
  * registered tool names and descriptions by keyword.
  */
-declare function ToolSearch(): Extension;
+declare function ToolSearch(): AgentExtension;
 
+/**
+ * Registration name of {@link RequiredToolsGuard}. Exported as a marker so other
+ * middleware can order around it with `before`/`after` without hardcoding the
+ * string — e.g. `{ after: REQUIRED_TOOLS_GUARD }`.
+ */
+declare const REQUIRED_TOOLS_GUARD = "required-tools-guard";
 /**
  * RequiredToolsGuard extension — blocks a turn if any required tools are
  * not registered.
+ *
+ * Registered with `{ after: "*" }` so it sits at the innermost band — the last
+ * check before the model call, after all other context-assembling middleware
+ * has run.
  */
 declare function RequiredToolsGuard(config: {
     tools: string[];
-}): Extension;
+}): AgentExtension;
 
 interface BashToolConfig {
     timeout?: number;
@@ -81,4 +126,4 @@ interface WaitToolConfig {
 }
 declare function WaitTool(config?: WaitToolConfig): ToolDefinition;
 
-export { BashTool, type BashToolConfig, BasicSystemPrompt, CompactionSummarize, FileListTool, FileReadTool, FileWriteTool, HttpFetchTool, JsonQueryTool, Logging, MessageWindow, RequiredToolsGuard, TextTransformTool, ToolSearch, WaitTool, type WaitToolConfig };
+export { BashTool, type BashToolConfig, BasicSystemPrompt, type BasicSystemPromptExtension, CompactionSummarize, FileListTool, FileReadTool, FileWriteTool, HttpFetchTool, JsonQueryTool, Logging, MessageWindow, REQUIRED_TOOLS_GUARD, RequiredToolsGuard, TextTransformTool, ToolSearch, WaitTool, type WaitToolConfig, getSystemPromptText };

package/dist/index.js

@@ -1,59 +1,75 @@
 // src/extensions/basic-system-prompt.ts
-var SYSTEM_MESSAGE_ID = "sys-basic-system-prompt";
+import {
+  createMessage
+} from "@goondan/openharness-types";
+var LEGACY_SYSTEM_MESSAGE_ID = "sys-basic-system-prompt";
+var CREATED_BY = "basic-system-prompt";
+function getSystemPromptText(extension) {
+  return extension.systemPromptText;
+}
 function BasicSystemPrompt(text) {
   return {
     name: "basic-system-prompt",
+    systemPromptText: text,
     register(api) {
-      api.pipeline.register(
-        "turn",
+      api.useTurn(
         async (ctx, next) => {
-          const alreadyExists = ctx.conversation.messages.some(
-            (m) => m.id === SYSTEM_MESSAGE_ID
-          );
-          if (!alreadyExists) {
-            ctx.conversation.emit({
-              type: "appendSystem",
-              message: {
-                id: SYSTEM_MESSAGE_ID,
-                data: {
-                  role: "system",
-                  content: text
-                },
-                metadata: {
-                  __createdBy: "basic-system-prompt"
-                }
-              }
+          const hasLegacy = ctx.conversation.getMessages().some((m) => m.id === LEGACY_SYSTEM_MESSAGE_ID);
+          if (hasLegacy) {
+            ctx.conversation.append({
+              type: "remove",
+              messageId: LEGACY_SYSTEM_MESSAGE_ID
             });
           }
           return next();
         },
-        { priority: 10 }
+        { before: "*" }
       );
+      api.useModelInput((view) => {
+        const rest = view.filter((m) => m.id !== LEGACY_SYSTEM_MESSAGE_ID);
+        const system = createMessage({
+          id: LEGACY_SYSTEM_MESSAGE_ID,
+          data: { role: "system", content: text },
+          createdBy: CREATED_BY
+        });
+        return [system, ...rest];
+      });
     }
   };
 }
 
 // src/extensions/message-window.ts
+function isToolResult(message) {
+  if (message.data.role !== "tool") return false;
+  const content = message.data.content;
+  if (typeof content === "string") return false;
+  return content.some(
+    (part) => part != null && typeof part === "object" && part.type === "tool-result"
+  );
+}
 function MessageWindow(config) {
   return {
     name: "message-window",
     register(api) {
-      api.pipeline.register("step", async (ctx, next) => {
-        if (ctx.conversation.messages.length > config.maxMessages) {
-          ctx.conversation.emit({
-            type: "truncate",
-            keepLast: config.maxMessages
-          });
-        }
-        return next();
+      api.useModelInput((view) => {
+        const system = view.filter((m) => m.data.role === "system");
+        const body = view.filter((m) => m.data.role !== "system");
+        if (body.length <= config.maxMessages) return view;
+        let start = body.length - config.maxMessages;
+        while (start > 0 && isToolResult(body[start])) start--;
+        return [...system, ...body.slice(start)];
       });
     }
   };
 }
 
 // src/extensions/compaction-summarize.ts
+import {
+  createMessage as createMessage2
+} from "@goondan/openharness-types";
 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.";
+var CREATED_BY2 = "compaction-summarize";
 function messageToText(m) {
   const role = m.data.role;
   const content = typeof m.data.content === "string" ? m.data.content : JSON.stringify(m.data.content);
@@ -63,12 +79,14 @@ function CompactionSummarize(config) {
   return {
     name: "compaction-summarize",
     register(api) {
-      api.pipeline.register("step", async (ctx, next) => {
-        const messages = ctx.conversation.messages;
+      api.useStep(async (ctx, next) => {
+        const messages = ctx.conversation.getMessages();
         if (messages.length > config.threshold) {
           const keepCount = Math.floor(config.threshold / 2);
-          const removeCount = messages.length - keepCount;
-          const toRemove = messages.slice(0, removeCount);
+          const removable = messages.filter((m) => m.data.role !== "system");
+          if (removable.length <= keepCount) return next();
+          const removeCount = removable.length - keepCount;
+          const toRemove = removable.slice(0, removeCount);
           let summaryText;
           if (config.summarizer) {
             summaryText = await config.summarizer([...toRemove]);
@@ -77,8 +95,16 @@ function CompactionSummarize(config) {
             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: {} }
+                createMessage2({
+                  id: `compaction-sys-${randomUUID()}`,
+                  data: { role: "system", content: prompt },
+                  createdBy: CREATED_BY2
+                }),
+                createMessage2({
+                  id: `compaction-usr-${randomUUID()}`,
+                  data: { role: "user", content: transcript },
+                  createdBy: CREATED_BY2
+                })
               ],
               [],
               // no tools needed for summarization
@@ -87,26 +113,19 @@ function CompactionSummarize(config) {
             );
             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 });
+          for (const msg of toRemove) {
+            ctx.conversation.append({ type: "remove", messageId: msg.id });
           }
-          ctx.conversation.emit({
+          ctx.conversation.append({
             type: "appendSystem",
-            message: {
+            message: createMessage2({
               id: `summary-${randomUUID()}`,
               data: {
                 role: "system",
                 content: `[Summary of earlier conversation]: ${summaryText}`
               },
-              metadata: {
-                __createdBy: "compaction-summarize"
-              }
-            }
+              createdBy: CREATED_BY2
+            })
           });
         }
         return next();
@@ -178,20 +197,26 @@ function ToolSearch() {
 }
 
 // src/extensions/required-tools-guard.ts
+var REQUIRED_TOOLS_GUARD = "required-tools-guard";
 function RequiredToolsGuard(config) {
   return {
-    name: "required-tools-guard",
+    name: REQUIRED_TOOLS_GUARD,
     register(api) {
-      api.pipeline.register("turn", async (ctx, next) => {
-        const registered = api.tools.list().map((t) => t.name);
-        const missing = config.tools.filter((name) => !registered.includes(name));
-        if (missing.length > 0) {
-          throw new Error(
-            `RequiredToolsGuard: missing required tools: ${missing.join(", ")}`
+      api.useTurn(
+        async (ctx, next) => {
+          const registered = api.tools.list().map((t) => t.name);
+          const missing = config.tools.filter(
+            (name) => !registered.includes(name)
           );
-        }
-        return next();
-      });
+          if (missing.length > 0) {
+            throw new Error(
+              `RequiredToolsGuard: missing required tools: ${missing.join(", ")}`
+            );
+          }
+          return next();
+        },
+        { after: "*" }
+      );
     }
   };
 }
@@ -530,8 +555,10 @@ export {
   JsonQueryTool,
   Logging,
   MessageWindow,
+  REQUIRED_TOOLS_GUARD,
   RequiredToolsGuard,
   TextTransformTool,
   ToolSearch,
-  WaitTool
+  WaitTool,
+  getSystemPromptText
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goondan/openharness-base",
-  "version": "0.5.7",
+  "version": "1.0.0-rc.1",
   "type": "module",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -12,19 +12,20 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "prepack": "pnpm build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
   "dependencies": {
-    "@goondan/openharness-types": "^0.5.7"
+    "@goondan/openharness-types": "workspace:^"
   },
   "devDependencies": {
     "@types/node": "^25.5.0",
     "tsup": "^8.4.0",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
-  },
-  "scripts": {
-    "build": "tsup src/index.ts --format esm --dts",
-    "test": "vitest run",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist"
   }
-}
+}