@tyvm/knowhow 0.0.137 → 0.0.140

package/tests/agents/tools/observe.test.ts

@@ -0,0 +1,179 @@
+import { observe, stopObserving } from "../../../src/agents/tools/observe";
+import { ObservationSource } from "../../../src/agents/base/base";
+
+/**
+ * observe is a self-referential tool: it reads the calling agent + ToolsService
+ * off _ctx, builds a tool-poll ObservationSource, and delegates to the calling
+ * agent's own observe()/stopObserving() methods (which own the per-agent
+ * observation registry). These tests use a fake caller that implements the same
+ * per-agent observe()/stopObserving() contract as BaseAgent.
+ */
+describe("observe / stopObserving", () => {
+  const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+  // Minimal faithful reimplementation of BaseAgent.observe/stopObserving so the
+  // delegation is exercised end-to-end without constructing a full BaseAgent.
+  function makeCaller() {
+    const messages: any[] = [];
+    const observations = new Map<string, any>();
+    let seq = 0;
+    const done = "done";
+    const caller: any = {
+      currentTaskId: "task-x",
+      name: "Tester",
+      status: "in_progress",
+      getEnabledToolNames: () => ["fakeTool"],
+      addPendingMessage: (m: any) => messages.push(m),
+      observe(source: ObservationSource, opts: any = {}) {
+        const {
+          onlyOnChange = true,
+          maxUpdates = 20,
+          maxDurationMs = 10 * 60 * 1000,
+        } = opts;
+        seq += 1;
+        const safeLabel = source.label.replace(/[^A-Za-z0-9]+/g, "_").slice(0, 24);
+        const id = `obs_${safeLabel}_${Date.now()}_${seq}`;
+        let last: string | undefined;
+        const emit = (datum: unknown) => {
+          if (caller.status === done) {
+            caller.stopObserving(id);
+            return;
+          }
+          const str =
+            typeof datum === "string" ? datum : JSON.stringify(datum);
+          if (onlyOnChange && str === last) return;
+          last = str;
+          const obs = observations.get(id);
+          if (!obs) return;
+          obs.updates += 1;
+          caller.addPendingMessage({
+            role: "user",
+            content: `[observe:${id}] ${source.label} (update ${obs.updates}/${maxUpdates}):\n${str}`,
+          });
+          if (obs.updates >= maxUpdates) caller.stopObserving(id, "max updates reached");
+        };
+        const teardownPromise = Promise.resolve(source.start(emit));
+        const expiry = maxDurationMs
+          ? setTimeout(() => caller.stopObserving(id, "max duration reached"), maxDurationMs)
+          : undefined;
+        expiry?.unref?.();
+        observations.set(id, { id, label: source.label, updates: 0, teardownPromise, expiry });
+        return id;
+      },
+      stopObserving(id?: string, reason = "stopped") {
+        const ids = id ? [id] : [...observations.keys()];
+        let stopped = 0;
+        for (const oid of ids) {
+          const obs = observations.get(oid);
+          if (!obs) continue;
+          if (obs.expiry) clearTimeout(obs.expiry);
+          Promise.resolve(obs.teardownPromise).then(
+            (fn: any) => typeof fn === "function" && fn()
+          );
+          observations.delete(oid);
+          stopped += 1;
+        }
+        return id
+          ? stopped
+            ? `Stopped observer ${id} (${reason}).`
+            : `No active observer found with id: ${id}.`
+          : `Stopped ${stopped} active observer(s) (${reason}).`;
+      },
+    };
+    return { caller, messages };
+  }
+
+  function makeCtx(toolResults: string[]) {
+    const { caller, messages } = makeCaller();
+    let call = 0;
+    const Tools = {
+      callTool: jest.fn(async () => {
+        const r = toolResults[Math.min(call, toolResults.length - 1)];
+        call++;
+        return r;
+      }),
+    };
+    return { _ctx: { caller, Tools }, messages, Tools, caller };
+  }
+
+  it("requires toolName", async () => {
+    const res = await observe({ toolName: "" });
+    expect(res).toMatch(/toolName is required/);
+  });
+
+  it("errors without a ToolsService on _ctx", async () => {
+    const res = await observe({ toolName: "fakeTool", _ctx: { caller: {} } });
+    expect(res).toMatch(/no ToolsService/);
+  });
+
+  it("errors without a caller on _ctx", async () => {
+    const res = await observe({
+      toolName: "fakeTool",
+      _ctx: { Tools: { callTool: jest.fn() } as any },
+    });
+    expect(res).toMatch(/no calling agent/);
+  });
+
+  it("polls the tool and delivers changed results to the caller", async () => {
+    const { _ctx, messages, Tools } = makeCtx(["a", "b", "b", "c"]);
+
+    const res = await observe({
+      toolName: "fakeTool",
+      intervalMs: 500, // clamped to min 500
+      maxUpdates: 4,
+      _ctx: _ctx as any,
+    });
+    expect(res).toMatch(/Started observing/);
+
+    // Wait for ~4 polls
+    await delay(2400);
+
+    // Tool should have been called several times
+    expect(Tools.callTool).toHaveBeenCalled();
+    // Delivered updates: only changed values (a, b, c) => 3 update messages.
+    const updateMsgs = messages.filter((m) =>
+      String(m.content).includes("[observe:")
+    );
+    expect(updateMsgs.length).toBeGreaterThanOrEqual(3);
+  });
+
+  it("can be stopped early via stopObserving with the returned id", async () => {
+    const { _ctx, messages } = makeCtx(["x", "y", "z"]);
+    const res = await observe({
+      toolName: "fakeTool",
+      intervalMs: 500,
+      maxUpdates: 20,
+      _ctx: _ctx as any,
+    });
+    const idMatch = res.match(/id: (obs_[^)]+)\)/);
+    expect(idMatch).toBeTruthy();
+    const id = idMatch![1];
+
+    await delay(600);
+    const stopRes = await stopObserving({ id, _ctx: _ctx as any });
+    expect(stopRes).toContain(`Stopped observer ${id}`);
+
+    const before = messages.length;
+    await delay(1000);
+    // No further updates after stopping.
+    expect(messages.length).toBe(before);
+  });
+
+  it("stopObserving with no id stops all observers on that agent", async () => {
+    const { _ctx } = makeCtx(["1"]);
+    await observe({ toolName: "fakeTool", intervalMs: 1000, _ctx: _ctx as any });
+    const res = await stopObserving({ _ctx: _ctx as any });
+    expect(res).toMatch(/Stopped \d+ active observer/);
+  });
+
+  it("stopObserving on an unknown id returns a helpful message", async () => {
+    const { _ctx } = makeCtx(["1"]);
+    const res = await stopObserving({ id: "obs_does_not_exist", _ctx: _ctx as any });
+    expect(res).toMatch(/No active observer found/);
+  });
+
+  it("errors without a caller on _ctx for stopObserving", async () => {
+    const res = await stopObserving({ id: "x" });
+    expect(res).toMatch(/no calling agent/);
+  });
+});

package/tests/agents/tools/replyToParent.test.ts

@@ -0,0 +1,125 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { replyToParent } from "../../../src/agents/tools/replyToParent";
+
+/**
+ * These tests exercise the `_ctx`-based self-referential mechanism:
+ * replyToParent discovers who is calling (and which parent spawned them)
+ * purely from the per-call context object threaded in as the last positional
+ * argument by ToolsService.callTool.
+ */
+describe("replyToParent (_ctx self-referential tool)", () => {
+  let tmpCwd: string;
+  let originalCwd: string;
+  let agentsDir: string;
+
+  beforeEach(() => {
+    originalCwd = process.cwd();
+    tmpCwd = fs.mkdtempSync(path.join(os.tmpdir(), "reply-parent-"));
+    process.chdir(tmpCwd);
+    agentsDir = path.join(tmpCwd, ".knowhow", "processes", "agents");
+    fs.mkdirSync(agentsDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    fs.rmSync(tmpCwd, { recursive: true, force: true });
+  });
+
+  function makeTask(taskId: string, meta: Record<string, any> = {}) {
+    const dir = path.join(agentsDir, taskId);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, "input.txt"), "", "utf8");
+    fs.writeFileSync(
+      path.join(dir, "metadata.json"),
+      JSON.stringify({ taskId, ...meta }, null, 2),
+      "utf8"
+    );
+    return dir;
+  }
+
+  it("returns a helpful message when there is no parent", async () => {
+    makeTask("child-1"); // no parentTaskId
+    const result = await replyToParent("hi", { taskId: "child-1" });
+    expect(result).toMatch(/No parent task found/);
+  });
+
+  it("uses parentTaskId directly from _ctx when provided", async () => {
+    const parentDir = makeTask("parent-1");
+    makeTask("child-2", { parentTaskId: "parent-1" });
+
+    const result = await replyToParent("progress update", {
+      taskId: "child-2",
+      parentTaskId: "parent-1",
+    });
+
+    expect(result).toMatch(/Sent message to parent task parent-1/);
+    const parentInput = fs.readFileSync(
+      path.join(parentDir, "input.txt"),
+      "utf8"
+    );
+    expect(parentInput).toContain("progress update");
+    expect(parentInput).toContain("[from:child-2]");
+  });
+
+  it("falls back to reading parentTaskId from the caller's metadata.json", async () => {
+    const parentDir = makeTask("parent-2");
+    makeTask("child-3", { parentTaskId: "parent-2" });
+
+    // No parentTaskId in _ctx — must be discovered from child-3's metadata.
+    const result = await replyToParent("need help", { taskId: "child-3" });
+
+    expect(result).toMatch(/Sent message to parent task parent-2/);
+    const parentInput = fs.readFileSync(
+      path.join(parentDir, "input.txt"),
+      "utf8"
+    );
+    expect(parentInput).toContain("need help");
+  });
+
+  it("reads taskId/name off _ctx.caller when taskId not set directly", async () => {
+    const parentDir = makeTask("parent-3");
+    makeTask("child-4", { parentTaskId: "parent-3" });
+
+    const fakeAgent = { currentTaskId: "child-4", name: "Researcher" };
+    const result = await replyToParent("done researching", {
+      caller: fakeAgent,
+    });
+
+    expect(result).toMatch(/Sent message to parent task parent-3/);
+    const parentInput = fs.readFileSync(
+      path.join(parentDir, "input.txt"),
+      "utf8"
+    );
+    expect(parentInput).toContain("[agent:Researcher]");
+    expect(parentInput).toContain("done researching");
+  });
+
+  it("appends rather than clobbers existing parent input", async () => {
+    const parentDir = makeTask("parent-4");
+    fs.writeFileSync(
+      path.join(parentDir, "input.txt"),
+      "existing message\n",
+      "utf8"
+    );
+    makeTask("child-5", { parentTaskId: "parent-4" });
+
+    await replyToParent("second message", {
+      taskId: "child-5",
+      parentTaskId: "parent-4",
+    });
+
+    const parentInput = fs.readFileSync(
+      path.join(parentDir, "input.txt"),
+      "utf8"
+    );
+    expect(parentInput).toContain("existing message");
+    expect(parentInput).toContain("second message");
+  });
+
+  it("returns error for empty message", async () => {
+    const result = await replyToParent("   ", { taskId: "whatever" });
+    expect(result).toMatch(/No message provided/);
+  });
+});

package/tests/agents/tools/sendAgentMessage.test.ts

@@ -0,0 +1,99 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { sendAgentMessage } from "../../../src/agents/tools/sendAgentMessage";
+
+describe("sendAgentMessage", () => {
+  let tmpCwd: string;
+  let originalCwd: string;
+  let agentsDir: string;
+
+  beforeEach(() => {
+    originalCwd = process.cwd();
+    tmpCwd = fs.mkdtempSync(path.join(os.tmpdir(), "send-msg-"));
+    process.chdir(tmpCwd);
+    agentsDir = path.join(tmpCwd, ".knowhow", "processes", "agents");
+    fs.mkdirSync(agentsDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    fs.rmSync(tmpCwd, { recursive: true, force: true });
+  });
+
+  function makeTask(taskId: string): string {
+    const dir = path.join(agentsDir, taskId);
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+  }
+
+  it("requires taskId and message", async () => {
+    expect(await sendAgentMessage({ taskId: "", message: "hi" })).toMatch(
+      /taskId is required/
+    );
+    expect(await sendAgentMessage({ taskId: "x", message: "" })).toMatch(
+      /message is required/
+    );
+  });
+
+  it("errors when the target task dir doesn't exist", async () => {
+    const res = await sendAgentMessage({ taskId: "nope", message: "hi" });
+    expect(res).toMatch(/target task directory not found/);
+  });
+
+  it("appends an envelope with sender identity from _ctx", async () => {
+    makeTask("child-1");
+    const res = await sendAgentMessage({
+      taskId: "child-1",
+      message: "do the thing",
+      _ctx: { taskId: "parent-1", caller: { name: "Developer" } },
+    });
+    expect(res).toMatch(/Sent message to task child-1/);
+    const input = fs.readFileSync(
+      path.join(agentsDir, "child-1", "input.txt"),
+      "utf8"
+    );
+    expect(input).toContain("[from:parent-1/Developer] do the thing");
+  });
+
+  it("uses explicit from when provided", async () => {
+    makeTask("child-2");
+    await sendAgentMessage({
+      taskId: "child-2",
+      message: "msg",
+      from: "orchestrator",
+    });
+    const input = fs.readFileSync(
+      path.join(agentsDir, "child-2", "input.txt"),
+      "utf8"
+    );
+    expect(input).toContain("[from:orchestrator] msg");
+  });
+
+  it("delivers as /poke when poke:true (interrupts recipient)", async () => {
+    makeTask("child-3");
+    await sendAgentMessage({
+      taskId: "child-3",
+      message: "stop and reconsider",
+      from: "boss",
+      poke: true,
+    });
+    const input = fs.readFileSync(
+      path.join(agentsDir, "child-3", "input.txt"),
+      "utf8"
+    );
+    expect(input).toMatch(/^\/poke \[from:boss\] stop and reconsider/);
+  });
+
+  it("appends without clobbering existing pending messages", async () => {
+    const dir = makeTask("child-4");
+    fs.writeFileSync(path.join(dir, "input.txt"), "existing line\n", "utf8");
+    await sendAgentMessage({
+      taskId: "child-4",
+      message: "second",
+      from: "a",
+    });
+    const input = fs.readFileSync(path.join(dir, "input.txt"), "utf8");
+    expect(input).toBe("existing line\n[from:a] second\n");
+  });
+});

package/tests/agents/tools/waitForAgentCompleted.test.ts

@@ -0,0 +1,147 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { waitForAgentCompleted } from "../../../src/agents/tools/waitForAgentCompleted";
+
+describe("waitForAgentCompleted", () => {
+  let tmpCwd: string;
+  let originalCwd: string;
+  let agentsDir: string;
+
+  beforeEach(() => {
+    originalCwd = process.cwd();
+    tmpCwd = fs.mkdtempSync(path.join(os.tmpdir(), "wait-agent-"));
+    process.chdir(tmpCwd);
+    agentsDir = path.join(tmpCwd, ".knowhow", "processes", "agents");
+    fs.mkdirSync(agentsDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    process.chdir(originalCwd);
+    fs.rmSync(tmpCwd, { recursive: true, force: true });
+  });
+
+  function makeTask(taskId: string, meta: Record<string, any> = {}, status?: string) {
+    const dir = path.join(agentsDir, taskId);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(
+      path.join(dir, "metadata.json"),
+      JSON.stringify({ taskId, ...meta }, null, 2),
+      "utf8"
+    );
+    if (status !== undefined) {
+      fs.writeFileSync(path.join(dir, "status.txt"), status, "utf8");
+    }
+    return dir;
+  }
+
+  it("returns error when taskId missing", async () => {
+    const res = JSON.parse(await waitForAgentCompleted({ taskId: "" }));
+    expect(res.status).toBe("error");
+    expect(res.error).toMatch(/taskId is required/);
+  });
+
+  it("returns error when task directory does not exist", async () => {
+    const res = JSON.parse(await waitForAgentCompleted({ taskId: "nope" }));
+    expect(res.status).toBe("error");
+    expect(res.error).toMatch(/No agent task directory/);
+  });
+
+  it("returns immediately with structured result for a completed task", async () => {
+    makeTask("done-1", {
+      status: "completed",
+      totalCostUsd: 1.23,
+      result: "the final answer",
+      artifacts: ["a.txt"],
+    });
+
+    const res = JSON.parse(await waitForAgentCompleted({ taskId: "done-1" }));
+    expect(res.status).toBe("completed");
+    expect(res.costUsd).toBe(1.23);
+    expect(res.finalAnswer).toBe("the final answer");
+    expect(res.artifacts).toEqual(["a.txt"]);
+  });
+
+  it("falls back to last assistant message when no result field", async () => {
+    makeTask("done-2", {
+      status: "completed",
+      totalCostUsd: 0.5,
+      threads: [
+        [
+          { role: "user", content: "do it" },
+          { role: "assistant", content: "I did it" },
+        ],
+      ],
+    });
+
+    const res = JSON.parse(await waitForAgentCompleted({ taskId: "done-2" }));
+    expect(res.finalAnswer).toBe("I did it");
+  });
+
+  it("treats inProgress:false with no status as completed", async () => {
+    makeTask("done-3", { inProgress: false, totalCostUsd: 0.1, result: "ok" });
+    const res = JSON.parse(await waitForAgentCompleted({ taskId: "done-3" }));
+    expect(res.status).toBe("completed");
+  });
+
+  it("times out on a still-running task", async () => {
+    makeTask("running-1", { status: "running", totalCostUsd: 0.2 });
+    const res = JSON.parse(
+      await waitForAgentCompleted({
+        taskId: "running-1",
+        timeoutMs: 300,
+        pollIntervalMs: 100,
+      })
+    );
+    expect(res.timedOut).toBe(true);
+    expect(res.status).toBe("running");
+    expect(res.costUsd).toBe(0.2);
+  });
+
+  it("resolves when a running task transitions to completed mid-poll", async () => {
+    const dir = makeTask("running-2", { status: "running", totalCostUsd: 0 });
+
+    // Flip to completed shortly after we start waiting.
+    setTimeout(() => {
+      fs.writeFileSync(
+        path.join(dir, "metadata.json"),
+        JSON.stringify(
+          {
+            taskId: "running-2",
+            status: "completed",
+            totalCostUsd: 2.0,
+            result: "eventually done",
+          },
+          null,
+          2
+        ),
+        "utf8"
+      );
+    }, 150);
+
+    const res = JSON.parse(
+      await waitForAgentCompleted({
+        taskId: "running-2",
+        timeoutMs: 3000,
+        pollIntervalMs: 100,
+      })
+    );
+    expect(res.status).toBe("completed");
+    expect(res.finalAnswer).toBe("eventually done");
+    expect(res.costUsd).toBe(2.0);
+  });
+
+  it("fails a task whose pid is dead without a terminal status", async () => {
+    // Use a pid that is virtually guaranteed not to exist.
+    makeTask("crashed-1", { status: "running", totalCostUsd: 0.3, pid: 999999 });
+    const res = JSON.parse(
+      await waitForAgentCompleted({
+        taskId: "crashed-1",
+        timeoutMs: 5000,
+        pollIntervalMs: 100,
+      })
+    );
+    expect(res.status).toBe("failed");
+    expect(res.error).toMatch(/exited without writing a terminal status/);
+  });
+});