@goondan/openharness-base 0.1.8 → 0.1.9

package/dist/index.d.ts

@@ -0,0 +1,84 @@
+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;
+
+/**
+ * MessageWindow extension — truncates conversation history to keep only
+ * the most recent `maxMessages` messages before each step.
+ */
+declare function MessageWindow(config: {
+    maxMessages: number;
+}): Extension;
+
+/**
+ * CompactionSummarize extension — when message count exceeds `threshold`,
+ * 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).
+ *
+ * @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;
+
+/**
+ * Logging extension — subscribes to core events and logs them.
+ */
+declare function Logging(config?: {
+    logger?: (msg: string) => void;
+}): Extension;
+
+/**
+ * ToolSearch extension — registers a meta-tool `search_tools` that searches
+ * registered tool names and descriptions by keyword.
+ */
+declare function ToolSearch(): Extension;
+
+/**
+ * RequiredToolsGuard extension — blocks a turn if any required tools are
+ * not registered.
+ */
+declare function RequiredToolsGuard(config: {
+    tools: string[];
+}): Extension;
+
+interface BashToolConfig {
+    timeout?: number;
+    maxBuffer?: number;
+}
+declare function BashTool(config?: BashToolConfig): ToolDefinition;
+
+declare function FileReadTool(): ToolDefinition;
+declare function FileWriteTool(): ToolDefinition;
+declare function FileListTool(): ToolDefinition;
+
+declare function HttpFetchTool(): ToolDefinition;
+
+declare function JsonQueryTool(): ToolDefinition;
+
+declare function TextTransformTool(): ToolDefinition;
+
+interface WaitToolConfig {
+    maxMs?: number;
+}
+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 };

package/dist/index.js

@@ -0,0 +1,537 @@
+// src/extensions/basic-system-prompt.ts
+var SYSTEM_MESSAGE_ID = "sys-basic-system-prompt";
+function BasicSystemPrompt(text) {
+  return {
+    name: "basic-system-prompt",
+    register(api) {
+      api.pipeline.register(
+        "turn",
+        async (ctx, next) => {
+          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 }
+      );
+    }
+  };
+}
+
+// src/extensions/message-window.ts
+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();
+      });
+    }
+  };
+}
+
+// src/extensions/compaction-summarize.ts
+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",
+    register(api) {
+      api.pipeline.register("step", async (ctx, next) => {
+        const messages = ctx.conversation.messages;
+        if (messages.length > config.threshold) {
+          const keepCount = Math.floor(config.threshold / 2);
+          const removeCount = messages.length - keepCount;
+          const toRemove = messages.slice(0, removeCount);
+          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-${randomUUID()}`,
+              data: {
+                role: "system",
+                content: `[Summary of earlier conversation]: ${summaryText}`
+              },
+              metadata: {
+                __createdBy: "compaction-summarize"
+              }
+            }
+          });
+        }
+        return next();
+      });
+    }
+  };
+}
+
+// src/extensions/logging.ts
+function Logging(config) {
+  const log = config?.logger ?? console.log;
+  return {
+    name: "logging",
+    register(api) {
+      api.on("turn.start", (payload) => {
+        log(`[turn.start] ${JSON.stringify(payload)}`);
+      });
+      api.on("turn.done", (payload) => {
+        log(`[turn.done] ${JSON.stringify(payload)}`);
+      });
+      api.on("turn.error", (payload) => {
+        log(`[turn.error] ${JSON.stringify(payload)}`);
+      });
+      api.on("step.start", (payload) => {
+        log(`[step.start] ${JSON.stringify(payload)}`);
+      });
+      api.on("step.done", (payload) => {
+        log(`[step.done] ${JSON.stringify(payload)}`);
+      });
+      api.on("tool.start", (payload) => {
+        log(`[tool.start] ${JSON.stringify(payload)}`);
+      });
+      api.on("tool.done", (payload) => {
+        log(`[tool.done] ${JSON.stringify(payload)}`);
+      });
+    }
+  };
+}
+
+// src/extensions/tool-search.ts
+function ToolSearch() {
+  return {
+    name: "tool-search",
+    register(api) {
+      api.tools.register({
+        name: "search_tools",
+        description: "Search registered tools by keyword in name or description.",
+        parameters: {
+          type: "object",
+          properties: {
+            query: {
+              type: "string",
+              description: "Keyword to search for in tool names and descriptions."
+            }
+          },
+          required: ["query"]
+        },
+        handler: async (args) => {
+          const query = args["query"].toLowerCase();
+          const allTools = api.tools.list();
+          const matching = allTools.filter(
+            (t) => t.name.toLowerCase().includes(query) || t.description.toLowerCase().includes(query)
+          );
+          return { type: "json", data: matching };
+        }
+      });
+    }
+  };
+}
+
+// src/extensions/required-tools-guard.ts
+function RequiredToolsGuard(config) {
+  return {
+    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(", ")}`
+          );
+        }
+        return next();
+      });
+    }
+  };
+}
+
+// src/tools/bash.ts
+import { exec } from "child_process";
+function BashTool(config = {}) {
+  const { timeout = 3e4, maxBuffer = 1024 * 1024 } = config;
+  return {
+    name: "bash",
+    description: "Execute a shell command and return its output.",
+    parameters: {
+      type: "object",
+      properties: {
+        command: { type: "string", description: "The shell command to execute." },
+        cwd: { type: "string", description: "Optional working directory for the command." }
+      },
+      required: ["command"]
+    },
+    async handler(args, _ctx) {
+      const command = args["command"];
+      const cwd = args["cwd"];
+      return new Promise((resolve) => {
+        exec(command, { timeout, maxBuffer, cwd }, (error, stdout, stderr) => {
+          if (error) {
+            resolve({ type: "error", error: stderr || error.message });
+          } else {
+            resolve({ type: "text", text: stdout });
+          }
+        });
+      });
+    }
+  };
+}
+
+// src/tools/file-system.ts
+import { readFile, writeFile, readdir } from "fs/promises";
+function FileReadTool() {
+  return {
+    name: "file_read",
+    description: "Read the contents of a file.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Absolute or relative path to the file to read." },
+        encoding: {
+          type: "string",
+          enum: ["utf8", "base64"],
+          description: "File encoding. Defaults to utf8."
+        }
+      },
+      required: ["path"]
+    },
+    async handler(args, _ctx) {
+      const filePath = args["path"];
+      const encoding = args["encoding"] ?? "utf8";
+      try {
+        const content = await readFile(filePath, { encoding });
+        return { type: "text", text: content };
+      } catch (err) {
+        return { type: "error", error: err.message };
+      }
+    }
+  };
+}
+function FileWriteTool() {
+  return {
+    name: "file_write",
+    description: "Write content to a file, creating or overwriting it.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Absolute or relative path to the file to write." },
+        content: { type: "string", description: "The content to write to the file." }
+      },
+      required: ["path", "content"]
+    },
+    async handler(args, _ctx) {
+      const filePath = args["path"];
+      const content = args["content"];
+      try {
+        await writeFile(filePath, content, "utf8");
+        return { type: "text", text: `File written: ${filePath}` };
+      } catch (err) {
+        return { type: "error", error: err.message };
+      }
+    }
+  };
+}
+function FileListTool() {
+  return {
+    name: "file_list",
+    description: "List files and directories in a given directory.",
+    parameters: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Absolute or relative path to the directory to list." }
+      },
+      required: ["path"]
+    },
+    async handler(args, _ctx) {
+      const dirPath = args["path"];
+      try {
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        const result = entries.map((e) => ({
+          name: e.name,
+          type: e.isDirectory() ? "directory" : "file"
+        }));
+        return { type: "json", data: result };
+      } catch (err) {
+        return { type: "error", error: err.message };
+      }
+    }
+  };
+}
+
+// src/tools/http-fetch.ts
+function HttpFetchTool() {
+  return {
+    name: "http_fetch",
+    description: "Perform an HTTP request and return the response.",
+    parameters: {
+      type: "object",
+      properties: {
+        url: { type: "string", description: "The URL to fetch." },
+        method: {
+          type: "string",
+          enum: ["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"],
+          description: "HTTP method. Defaults to GET."
+        },
+        headers: {
+          type: "object",
+          additionalProperties: { type: "string" },
+          description: "Optional request headers."
+        },
+        body: { type: "string", description: "Optional request body." }
+      },
+      required: ["url"]
+    },
+    async handler(args, _ctx) {
+      const url = args["url"];
+      const method = args["method"] ?? "GET";
+      const headers = args["headers"] ?? {};
+      const body = args["body"];
+      try {
+        const response = await fetch(url, {
+          method,
+          headers,
+          body: body !== void 0 ? body : void 0
+        });
+        const responseHeaders = {};
+        response.headers.forEach((value, key) => {
+          responseHeaders[key] = value;
+        });
+        let responseBody;
+        const contentType = response.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json")) {
+          responseBody = await response.json();
+        } else {
+          responseBody = await response.text();
+        }
+        return {
+          type: "json",
+          data: {
+            status: response.status,
+            headers: responseHeaders,
+            body: responseBody
+          }
+        };
+      } catch (err) {
+        return { type: "error", error: err.message };
+      }
+    }
+  };
+}
+
+// src/tools/json-query.ts
+function jsonQuery(data, path) {
+  let normalized = path.trim();
+  if (normalized.startsWith("$.")) {
+    normalized = normalized.slice(2);
+  } else if (normalized === "$") {
+    return data;
+  } else if (normalized.startsWith("$")) {
+    normalized = normalized.slice(1);
+  }
+  if (normalized === "" || normalized === ".") {
+    return data;
+  }
+  const segments = [];
+  const normalized2 = normalized.replace(/\[(\d+)\]/g, ".$1").replace(/\[['"](.+?)['"]\]/g, ".$1");
+  for (const part of normalized2.split(".")) {
+    if (part === "") continue;
+    const num = Number(part);
+    segments.push(Number.isInteger(num) && String(num) === part ? num : part);
+  }
+  let current = data;
+  for (const segment of segments) {
+    if (current === null || current === void 0) return void 0;
+    if (typeof current === "object") {
+      current = current[segment];
+    } else {
+      return void 0;
+    }
+  }
+  return current;
+}
+function JsonQueryTool() {
+  return {
+    name: "json_query",
+    description: "Query JSON data using a simple JSONPath-like path expression.",
+    parameters: {
+      type: "object",
+      properties: {
+        data: { description: "The JSON data to query." },
+        path: {
+          type: "string",
+          description: "JSONPath-like path, e.g. $.key.nested[0].field"
+        }
+      },
+      required: ["data", "path"]
+    },
+    async handler(args, _ctx) {
+      const data = args["data"];
+      const path = args["path"];
+      try {
+        const result = jsonQuery(data, path);
+        return { type: "json", data: result };
+      } catch (err) {
+        return { type: "error", error: err.message };
+      }
+    }
+  };
+}
+
+// src/tools/text-transform.ts
+function TextTransformTool() {
+  return {
+    name: "text_transform",
+    description: "Apply a transformation operation to a text string.",
+    parameters: {
+      type: "object",
+      properties: {
+        text: { type: "string", description: "The input text to transform." },
+        operation: {
+          type: "string",
+          enum: ["uppercase", "lowercase", "trim", "split", "replace"],
+          description: "The transformation to apply."
+        },
+        options: {
+          type: "object",
+          properties: {
+            delimiter: { type: "string", description: "Delimiter for split operation." },
+            find: { type: "string", description: "String to find for replace operation." },
+            replacement: { type: "string", description: "Replacement string for replace operation." }
+          }
+        }
+      },
+      required: ["text", "operation"]
+    },
+    async handler(args, _ctx) {
+      const text = args["text"];
+      const operation = args["operation"];
+      const options = args["options"] ?? {};
+      try {
+        switch (operation) {
+          case "uppercase":
+            return { type: "text", text: text.toUpperCase() };
+          case "lowercase":
+            return { type: "text", text: text.toLowerCase() };
+          case "trim":
+            return { type: "text", text: text.trim() };
+          case "split": {
+            const delimiter = options["delimiter"] ?? " ";
+            return { type: "json", data: text.split(delimiter) };
+          }
+          case "replace": {
+            const find = options["find"] ?? "";
+            const replacement = options["replacement"] ?? "";
+            return { type: "text", text: text.split(find).join(replacement) };
+          }
+          default:
+            return { type: "error", error: `Unknown operation: ${operation}` };
+        }
+      } catch (err) {
+        return { type: "error", error: err.message };
+      }
+    }
+  };
+}
+
+// src/tools/wait.ts
+function WaitTool(config = {}) {
+  const { maxMs = 6e4 } = config;
+  return {
+    name: "wait",
+    description: "Wait for a specified number of milliseconds before continuing.",
+    parameters: {
+      type: "object",
+      properties: {
+        ms: {
+          type: "number",
+          description: "Number of milliseconds to wait.",
+          minimum: 0
+        }
+      },
+      required: ["ms"]
+    },
+    async handler(args, ctx) {
+      const requestedMs = args["ms"];
+      const ms = Math.min(requestedMs, maxMs);
+      await new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, ms);
+        if (ctx.abortSignal.aborted) {
+          clearTimeout(timer);
+          reject(new Error("Aborted"));
+          return;
+        }
+        ctx.abortSignal.addEventListener("abort", () => {
+          clearTimeout(timer);
+          reject(new Error("Aborted"));
+        });
+      });
+      return { type: "text", text: `Waited ${ms}ms` };
+    }
+  };
+}
+export {
+  BashTool,
+  BasicSystemPrompt,
+  CompactionSummarize,
+  FileListTool,
+  FileReadTool,
+  FileWriteTool,
+  HttpFetchTool,
+  JsonQueryTool,
+  Logging,
+  MessageWindow,
+  RequiredToolsGuard,
+  TextTransformTool,
+  ToolSearch,
+  WaitTool
+};

package/package.json

@@ -1,26 +1,31 @@
 {
   "name": "@goondan/openharness-base",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "type": "module",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "import": "./dist/index.js",
       "types": "./dist/index.d.ts"
     }
   },
+  "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.1.8"
+    "@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"
   }
-}
+}