@goondan/openharness-base 0.0.1-alpha4 → 0.1.0

package/src/__tests__/tools.test.ts

@@ -0,0 +1,332 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { BashTool } from "../tools/bash.js";
+import { FileReadTool, FileWriteTool, FileListTool } from "../tools/file-system.js";
+import { HttpFetchTool } from "../tools/http-fetch.js";
+import { JsonQueryTool } from "../tools/json-query.js";
+import { TextTransformTool } from "../tools/text-transform.js";
+import { WaitTool } from "../tools/wait.js";
+import type { ToolContext } from "@goondan/openharness-types";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeFile, mkdir } from "node:fs/promises";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeCtx(abortSignal?: AbortSignal): ToolContext {
+  return {
+    conversationId: "conv-1",
+    agentName: "test-agent",
+    abortSignal: abortSignal ?? new AbortController().signal,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// All tools — consolidated schema validation
+// ---------------------------------------------------------------------------
+
+describe("All tools — schema structure", () => {
+  it("every tool has name, description, non-empty required params, and a handler function", () => {
+    const tools = [
+      { factory: BashTool, expectedName: "bash", expectedRequired: ["command"] },
+      { factory: FileReadTool, expectedName: "file_read", expectedRequired: ["path"] },
+      { factory: FileWriteTool, expectedName: "file_write", expectedRequired: ["path", "content"] },
+      { factory: FileListTool, expectedName: "file_list", expectedRequired: ["path"] },
+      { factory: HttpFetchTool, expectedName: "http_fetch", expectedRequired: ["url"] },
+      { factory: JsonQueryTool, expectedName: "json_query", expectedRequired: ["data", "path"] },
+      { factory: TextTransformTool, expectedName: "text_transform", expectedRequired: ["text", "operation"] },
+      { factory: WaitTool, expectedName: "wait", expectedRequired: ["ms"] },
+    ];
+
+    for (const { factory, expectedName, expectedRequired } of tools) {
+      const tool = factory();
+      expect(tool.name).toBe(expectedName);
+      expect(typeof tool.description).toBe("string");
+      expect(tool.description.length).toBeGreaterThan(0);
+      expect(typeof tool.handler).toBe("function");
+
+      const params = tool.parameters as { properties: Record<string, unknown>; required: string[] };
+      for (const req of expectedRequired) {
+        expect(params.properties).toHaveProperty(req);
+        expect(params.required).toContain(req);
+      }
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// BashTool
+// ---------------------------------------------------------------------------
+
+describe("BashTool", () => {
+  it("returns stdout as text result on success", async () => {
+    const tool = BashTool();
+    const result = await tool.handler({ command: "echo hello" }, makeCtx());
+    expect(result.type).toBe("text");
+    if (result.type === "text") {
+      expect(result.text.trim()).toBe("hello");
+    }
+  });
+
+  it("returns error result on command failure", async () => {
+    const tool = BashTool();
+    const result = await tool.handler({ command: "cat /nonexistent_file_xyz_abc_123" }, makeCtx());
+    expect(result.type).toBe("error");
+    if (result.type === "error") {
+      expect(typeof result.error).toBe("string");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// FileReadTool
+// ---------------------------------------------------------------------------
+
+describe("FileReadTool", () => {
+  let tmpFile: string;
+
+  beforeEach(async () => {
+    tmpFile = join(tmpdir(), `openharness-test-${Date.now()}.txt`);
+    await writeFile(tmpFile, "hello file", "utf8");
+  });
+
+  it("reads file content successfully", async () => {
+    const tool = FileReadTool();
+    const result = await tool.handler({ path: tmpFile }, makeCtx());
+    expect(result.type).toBe("text");
+    if (result.type === "text") {
+      expect(result.text).toBe("hello file");
+    }
+  });
+
+  it("returns error for non-existent file", async () => {
+    const tool = FileReadTool();
+    const result = await tool.handler({ path: "/nonexistent/path/file.txt" }, makeCtx());
+    expect(result.type).toBe("error");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// FileWriteTool
+// ---------------------------------------------------------------------------
+
+describe("FileWriteTool", () => {
+  it("writes file successfully and returns text result", async () => {
+    const tmpFile = join(tmpdir(), `openharness-write-${Date.now()}.txt`);
+    const tool = FileWriteTool();
+    const result = await tool.handler({ path: tmpFile, content: "written content" }, makeCtx());
+    expect(result.type).toBe("text");
+    if (result.type === "text") {
+      expect(result.text).toContain(tmpFile);
+    }
+  });
+
+  it("returns error when path is invalid", async () => {
+    const tool = FileWriteTool();
+    const result = await tool.handler({ path: "/nonexistent/deeply/nested/path.txt", content: "x" }, makeCtx());
+    expect(result.type).toBe("error");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// FileListTool
+// ---------------------------------------------------------------------------
+
+describe("FileListTool", () => {
+  let tmpDir: string;
+
+  beforeEach(async () => {
+    tmpDir = join(tmpdir(), `openharness-list-${Date.now()}`);
+    await mkdir(tmpDir, { recursive: true });
+    await writeFile(join(tmpDir, "a.txt"), "a");
+    await writeFile(join(tmpDir, "b.txt"), "b");
+  });
+
+  it("lists directory entries as json result", async () => {
+    const tool = FileListTool();
+    const result = await tool.handler({ path: tmpDir }, makeCtx());
+    expect(result.type).toBe("json");
+    if (result.type === "json") {
+      const entries = result.data as Array<{ name: string; type: string }>;
+      expect(Array.isArray(entries)).toBe(true);
+      const names = entries.map((e) => e.name);
+      expect(names).toContain("a.txt");
+      expect(names).toContain("b.txt");
+    }
+  });
+
+  it("returns error for non-existent directory", async () => {
+    const tool = FileListTool();
+    const result = await tool.handler({ path: "/nonexistent/dir/xyz" }, makeCtx());
+    expect(result.type).toBe("error");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// HttpFetchTool
+// ---------------------------------------------------------------------------
+
+describe("HttpFetchTool", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("returns json result with status, headers, body on success", async () => {
+    const mockResponse = {
+      status: 200,
+      headers: {
+        get: (name: string) => (name === "content-type" ? "application/json" : null),
+        forEach: (cb: (value: string, key: string) => void) => {
+          cb("application/json", "content-type");
+        },
+      },
+      json: async () => ({ ok: true }),
+    };
+    vi.stubGlobal("fetch", vi.fn().mockResolvedValue(mockResponse));
+
+    const tool = HttpFetchTool();
+    const result = await tool.handler({ url: "https://example.com/api" }, makeCtx());
+
+    expect(result.type).toBe("json");
+    if (result.type === "json") {
+      const data = result.data as { status: number; headers: Record<string, string>; body: unknown };
+      expect(data.status).toBe(200);
+      expect(data.body).toEqual({ ok: true });
+    }
+  });
+
+  it("returns error result when fetch throws", async () => {
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("Network error")));
+
+    const tool = HttpFetchTool();
+    const result = await tool.handler({ url: "https://example.com/fail" }, makeCtx());
+    expect(result.type).toBe("error");
+    if (result.type === "error") {
+      expect(result.error).toContain("Network error");
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// JsonQueryTool
+// ---------------------------------------------------------------------------
+
+describe("JsonQueryTool", () => {
+  it("queries nested object with dot notation", async () => {
+    const tool = JsonQueryTool();
+    const data = { user: { name: "Alice", age: 30 } };
+    const result = await tool.handler({ data, path: "$.user.name" }, makeCtx());
+    expect(result.type).toBe("json");
+    if (result.type === "json") {
+      expect(result.data).toBe("Alice");
+    }
+  });
+
+  it("queries array with bracket notation", async () => {
+    const tool = JsonQueryTool();
+    const data = { items: ["a", "b", "c"] };
+    const result = await tool.handler({ data, path: "$.items[1]" }, makeCtx());
+    expect(result.type).toBe("json");
+    if (result.type === "json") {
+      expect(result.data).toBe("b");
+    }
+  });
+
+  it("returns root data for $ path", async () => {
+    const tool = JsonQueryTool();
+    const data = { x: 1 };
+    const result = await tool.handler({ data, path: "$" }, makeCtx());
+    expect(result.type).toBe("json");
+    if (result.type === "json") {
+      expect(result.data).toEqual(data);
+    }
+  });
+
+  it("returns undefined for missing path", async () => {
+    const tool = JsonQueryTool();
+    const data = { a: 1 };
+    const result = await tool.handler({ data, path: "$.b.c" }, makeCtx());
+    expect(result.type).toBe("json");
+    if (result.type === "json") {
+      expect(result.data).toBeUndefined();
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// TextTransformTool
+// ---------------------------------------------------------------------------
+
+describe("TextTransformTool", () => {
+  it("uppercase operation", async () => {
+    const tool = TextTransformTool();
+    const result = await tool.handler({ text: "hello world", operation: "uppercase" }, makeCtx());
+    expect(result).toEqual({ type: "text", text: "HELLO WORLD" });
+  });
+
+  it("lowercase operation", async () => {
+    const tool = TextTransformTool();
+    const result = await tool.handler({ text: "HELLO WORLD", operation: "lowercase" }, makeCtx());
+    expect(result).toEqual({ type: "text", text: "hello world" });
+  });
+
+  it("trim operation", async () => {
+    const tool = TextTransformTool();
+    const result = await tool.handler({ text: "  spaces  ", operation: "trim" }, makeCtx());
+    expect(result).toEqual({ type: "text", text: "spaces" });
+  });
+
+  it("split operation returns json array", async () => {
+    const tool = TextTransformTool();
+    const result = await tool.handler(
+      { text: "a,b,c", operation: "split", options: { delimiter: "," } },
+      makeCtx(),
+    );
+    expect(result.type).toBe("json");
+    if (result.type === "json") {
+      expect(result.data).toEqual(["a", "b", "c"]);
+    }
+  });
+
+  it("replace operation", async () => {
+    const tool = TextTransformTool();
+    const result = await tool.handler(
+      { text: "foo bar foo", operation: "replace", options: { find: "foo", replacement: "baz" } },
+      makeCtx(),
+    );
+    expect(result).toEqual({ type: "text", text: "baz bar baz" });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// WaitTool
+// ---------------------------------------------------------------------------
+
+describe("WaitTool", () => {
+  it("waits and returns text result", async () => {
+    const tool = WaitTool();
+    const result = await tool.handler({ ms: 10 }, makeCtx());
+    expect(result.type).toBe("text");
+    if (result.type === "text") {
+      expect(result.text).toBe("Waited 10ms");
+    }
+  });
+
+  it("respects maxMs cap", async () => {
+    const tool = WaitTool({ maxMs: 20 });
+    const result = await tool.handler({ ms: 1000 }, makeCtx());
+    expect(result.type).toBe("text");
+    if (result.type === "text") {
+      expect(result.text).toBe("Waited 20ms");
+    }
+  });
+
+  it("rejects when aborted", async () => {
+    const tool = WaitTool();
+    const ac = new AbortController();
+    const promise = tool.handler({ ms: 5000 }, makeCtx(ac.signal));
+    ac.abort();
+    await expect(promise).rejects.toThrow();
+  });
+});

package/src/extensions/compaction-summarize.ts

@@ -0,0 +1,58 @@
+import type { Extension, ExtensionApi } from "@goondan/openharness-types";
+import { randomUUID } from "node:crypto";
+
+/**
+ * CompactionSummarize extension — when message count exceeds `threshold`,
+ * removes the oldest messages and prepends a summary system message.
+ *
+ * For MVP the "summary" is just the concatenation of removed message text.
+ */
+export function CompactionSummarize(config: {
+  threshold: number;
+  summaryPrompt?: string;
+}): Extension {
+  return {
+    name: "compaction-summarize",
+
+    register(api: ExtensionApi): void {
+      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);
+
+          // 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) {
+            ctx.conversation.emit({ type: "remove", messageId: msg.id });
+          }
+
+          // Prepend summary
+          ctx.conversation.emit({
+            type: "append",
+            message: {
+              id: `summary-${randomUUID()}`,
+              data: {
+                role: "system",
+                content: `[Summary of earlier conversation]: ${summaryText}`,
+              },
+              metadata: {
+                __createdBy: "compaction-summarize",
+              },
+            },
+          });
+        }
+        return next();
+      });
+    },
+  };
+}

package/src/extensions/context-message.ts

@@ -0,0 +1,37 @@
+import type { Extension, ExtensionApi } from "@goondan/openharness-types";
+import { randomUUID } from "node:crypto";
+
+/**
+ * ContextMessage extension — prepends a system message to the conversation
+ * at the start of every turn.
+ *
+ * Priority 10 (HIGH) ensures it runs before other turn middleware.
+ */
+export function ContextMessage(text: string): Extension {
+  return {
+    name: "context-message",
+
+    register(api: ExtensionApi): void {
+      api.pipeline.register(
+        "turn",
+        async (ctx, next) => {
+          ctx.conversation.emit({
+            type: "append",
+            message: {
+              id: `ctx-msg-${randomUUID()}`,
+              data: {
+                role: "system",
+                content: text,
+              },
+              metadata: {
+                __createdBy: "context-message",
+              },
+            },
+          });
+          return next();
+        },
+        { priority: 10 },
+      );
+    },
+  };
+}

package/src/extensions/logging.ts

@@ -0,0 +1,42 @@
+import type { Extension, ExtensionApi } from "@goondan/openharness-types";
+
+/**
+ * Logging extension — subscribes to core events and logs them.
+ */
+export function Logging(config?: { logger?: (msg: string) => void }): Extension {
+  const log = config?.logger ?? console.log;
+
+  return {
+    name: "logging",
+
+    register(api: ExtensionApi): void {
+      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)}`);
+      });
+    },
+  };
+}

package/src/extensions/message-window.ts

@@ -0,0 +1,23 @@
+import type { Extension, ExtensionApi } from "@goondan/openharness-types";
+
+/**
+ * MessageWindow extension — truncates conversation history to keep only
+ * the most recent `maxMessages` messages before each step.
+ */
+export function MessageWindow(config: { maxMessages: number }): Extension {
+  return {
+    name: "message-window",
+
+    register(api: ExtensionApi): void {
+      api.pipeline.register("step", async (ctx, next) => {
+        if (ctx.conversation.messages.length > config.maxMessages) {
+          ctx.conversation.emit({
+            type: "truncate",
+            keepLast: config.maxMessages,
+          });
+        }
+        return next();
+      });
+    },
+  };
+}

package/src/extensions/required-tools-guard.ts

@@ -0,0 +1,24 @@
+import type { Extension, ExtensionApi } from "@goondan/openharness-types";
+
+/**
+ * RequiredToolsGuard extension — blocks a turn if any required tools are
+ * not registered.
+ */
+export function RequiredToolsGuard(config: { tools: string[] }): Extension {
+  return {
+    name: "required-tools-guard",
+
+    register(api: ExtensionApi): void {
+      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();
+      });
+    },
+  };
+}

package/src/extensions/tool-search.ts

@@ -0,0 +1,38 @@
+import type { Extension, ExtensionApi, JsonValue } from "@goondan/openharness-types";
+
+/**
+ * ToolSearch extension — registers a meta-tool `search_tools` that searches
+ * registered tool names and descriptions by keyword.
+ */
+export function ToolSearch(): Extension {
+  return {
+    name: "tool-search",
+
+    register(api: ExtensionApi): void {
+      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"] as string).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 as unknown as JsonValue };
+        },
+      });
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export { ContextMessage } from "./extensions/context-message.js";
+export { MessageWindow } from "./extensions/message-window.js";
+export { CompactionSummarize } from "./extensions/compaction-summarize.js";
+export { Logging } from "./extensions/logging.js";
+export { ToolSearch } from "./extensions/tool-search.js";
+export { RequiredToolsGuard } from "./extensions/required-tools-guard.js";
+
+// Tools
+export { BashTool } from "./tools/bash.js";
+export type { BashToolConfig } from "./tools/bash.js";
+export { FileReadTool, FileWriteTool, FileListTool } from "./tools/file-system.js";
+export { HttpFetchTool } from "./tools/http-fetch.js";
+export { JsonQueryTool } from "./tools/json-query.js";
+export { TextTransformTool } from "./tools/text-transform.js";
+export { WaitTool } from "./tools/wait.js";
+export type { WaitToolConfig } from "./tools/wait.js";

package/src/tools/bash.ts

@@ -0,0 +1,38 @@
+import { exec } from "node:child_process";
+import type { ToolDefinition, JsonObject, ToolContext } from "@goondan/openharness-types";
+
+export interface BashToolConfig {
+  timeout?: number;
+  maxBuffer?: number;
+}
+
+export function BashTool(config: BashToolConfig = {}): ToolDefinition {
+  const { timeout = 30_000, 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: JsonObject, _ctx: ToolContext) {
+      const command = args["command"] as string;
+      const cwd = args["cwd"] as string | undefined;
+
+      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 });
+          }
+        });
+      });
+    },
+  };
+}