@tyvm/knowhow 0.0.138 → 0.0.141

package/tests/agents/observe-base.test.ts

@@ -0,0 +1,183 @@
+/**
+ * Tests for BaseAgent.observe() / stopObserving() — the per-agent observation
+ * registry that the `observe` tool delegates to.
+ *
+ * Verifies:
+ *  1. A source's emit() is delivered to the agent as a pending message.
+ *  2. onlyOnChange dedupes repeated data.
+ *  3. maxUpdates auto-stops and runs the source teardown.
+ *  4. stopObserving(id) cancels one; stopObserving() cancels all.
+ *  5. Observations are scoped to the instance — one agent's stopObserving()
+ *     with no id does NOT affect another agent's observers.
+ *  6. Data emitted after the agent is "done" is not injected.
+ */
+
+import { BaseAgent, ObservationSource } from "../../src/agents/base/base";
+
+// Teardown runs on the microtask queue (Promise.resolve(teardownPromise).then),
+// so flush a couple of ticks before asserting torndown state.
+const flush = () => new Promise((r) => setTimeout(r, 0));
+
+// Minimal stubs so BaseAgent can be constructed.
+function makeStubs() {
+  const events: any = {
+    setListener: () => {},
+    emit: () => {},
+    on: () => {},
+  };
+  const tools: any = {
+    getContext: () => ({}),
+    callTool: async () => "",
+  };
+  return { events, tools };
+}
+
+class TestAgent extends BaseAgent {
+  name = "TestAgent";
+  description = "test";
+  constructor() {
+    const { events, tools } = makeStubs();
+    super({ Tools: tools, Events: events });
+    // Agent must not be "done" for observations to deliver.
+    (this as any).status = this.eventTypes.inProgress;
+  }
+  async getInitialMessages(): Promise<any[]> {
+    return [];
+  }
+  get delivered(): any[] {
+    return (this as any).pendingMessages;
+  }
+  setStatus(s: string) {
+    (this as any).status = s;
+  }
+}
+
+/** A source we can drive manually and that records teardown. */
+function manualSource(label: string) {
+  let emitFn: ((d: unknown) => void) | undefined;
+  const state = { torndown: false };
+  const source: ObservationSource = {
+    label,
+    start(emit) {
+      emitFn = emit;
+      return () => {
+        state.torndown = true;
+      };
+    },
+  };
+  return {
+    source,
+    push: (d: unknown) => emitFn && emitFn(d),
+    state,
+  };
+}
+
+describe("BaseAgent.observe / stopObserving", () => {
+  it("delivers emitted data as pending messages", () => {
+    const agent = new TestAgent();
+    const { source, push } = manualSource("thing");
+    const id = agent.observe(source);
+    expect(id).toMatch(/^obs_thing_/);
+
+    push("hello");
+    expect(agent.delivered.length).toBe(1);
+    expect(String(agent.delivered[0].content)).toContain("hello");
+    expect(String(agent.delivered[0].content)).toContain(`[observe:${id}]`);
+    agent.stopObserving();
+  });
+
+  it("dedupes identical consecutive data with onlyOnChange (default)", () => {
+    const agent = new TestAgent();
+    const { source, push } = manualSource("dup");
+    agent.observe(source);
+    push("a");
+    push("a");
+    push("b");
+    expect(agent.delivered.length).toBe(2);
+    agent.stopObserving();
+  });
+
+  it("delivers every emit when onlyOnChange is false", () => {
+    const agent = new TestAgent();
+    const { source, push } = manualSource("nochange");
+    // dedupe of pendingMessages by content still applies in addPendingMessage,
+    // so use distinct data to observe count.
+    agent.observe(source, { onlyOnChange: false });
+    push("x1");
+    push("x2");
+    push("x3");
+    expect(agent.delivered.length).toBe(3);
+    agent.stopObserving();
+  });
+
+  it("auto-stops after maxUpdates and runs teardown", async () => {
+    const agent = new TestAgent();
+    const { source, push, state } = manualSource("cap");
+    agent.observe(source, { maxUpdates: 2 });
+    push("1");
+    push("2"); // hits cap -> stop
+    push("3"); // ignored, observer gone
+    expect(agent.delivered.length).toBe(2);
+    await flush();
+    expect(state.torndown).toBe(true);
+    agent.stopObserving();
+  });
+
+  it("stopObserving(id) cancels one observer and tears it down", async () => {
+    const agent = new TestAgent();
+    const a = manualSource("a");
+    const b = manualSource("b");
+    const idA = agent.observe(a.source);
+    agent.observe(b.source);
+    const res = agent.stopObserving(idA);
+    expect(res).toContain(`Stopped observer ${idA}`);
+    await flush();
+    expect(a.state.torndown).toBe(true);
+    expect(b.state.torndown).toBe(false);
+    // b still delivers
+    b.push("still here");
+    expect(agent.delivered.some((m) => String(m.content).includes("still here"))).toBe(true);
+    agent.stopObserving();
+  });
+
+  it("stopObserving() with no id cancels all", async () => {
+    const agent = new TestAgent();
+    const a = manualSource("a");
+    const b = manualSource("b");
+    agent.observe(a.source);
+    agent.observe(b.source);
+    const res = agent.stopObserving();
+    expect(res).toMatch(/Stopped 2 active observer/);
+    await flush();
+    expect(a.state.torndown).toBe(true);
+    expect(b.state.torndown).toBe(true);
+  });
+
+  it("is scoped per-agent — one agent's stopObserving does not affect another", async () => {
+    const agentA = new TestAgent();
+    const agentB = new TestAgent();
+    const sa = manualSource("sa");
+    const sb = manualSource("sb");
+    agentA.observe(sa.source);
+    agentB.observe(sb.source);
+
+    agentA.stopObserving(); // should only affect A
+    await flush();
+    expect(sa.state.torndown).toBe(true);
+    expect(sb.state.torndown).toBe(false);
+
+    sb.push("b-data");
+    expect(agentB.delivered.some((m) => String(m.content).includes("b-data"))).toBe(true);
+    agentB.stopObserving();
+  });
+
+  it("does not inject data once the agent is done", () => {
+    const agent = new TestAgent();
+    const { source, push } = manualSource("late");
+    agent.observe(source);
+    agent.setStatus(agent.eventTypes.done);
+    push("too late");
+    expect(agent.delivered.length).toBe(0);
+    agent.stopObserving();
+  });
+});

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

@@ -0,0 +1,138 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import {
+  connectAgent,
+  stopConnections,
+} from "../../../src/agents/tools/connectAgent";
+
+describe("connectAgent / stopConnections", () => {
+  let tmpCwd: string;
+  let originalCwd: string;
+  let agentsDir: string;
+
+  const delay = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+  beforeEach(() => {
+    originalCwd = process.cwd();
+    tmpCwd = fs.mkdtempSync(path.join(os.tmpdir(), "connect-agent-"));
+    process.chdir(tmpCwd);
+    agentsDir = path.join(tmpCwd, ".knowhow", "processes", "agents");
+    fs.mkdirSync(agentsDir, { recursive: true });
+  });
+
+  afterEach(async () => {
+    await stopConnections({});
+    process.chdir(originalCwd);
+    fs.rmSync(tmpCwd, { recursive: true, force: true });
+  });
+
+  function makeTask(taskId: string, threads: any[] = []): string {
+    const dir = path.join(agentsDir, taskId);
+    fs.mkdirSync(dir, { recursive: true });
+    writeThreads(taskId, threads);
+    return dir;
+  }
+
+  function writeThreads(taskId: string, threads: any[], extra: any = {}) {
+    fs.writeFileSync(
+      path.join(agentsDir, taskId, "metadata.json"),
+      JSON.stringify({ taskId, threads, ...extra }, null, 2),
+      "utf8"
+    );
+  }
+
+  function readInput(taskId: string): string {
+    const p = path.join(agentsDir, taskId, "input.txt");
+    return fs.existsSync(p) ? fs.readFileSync(p, "utf8") : "";
+  }
+
+  it("rejects empty connections array", async () => {
+    const res = await connectAgent({ connections: [] });
+    expect(res).toMatch(/non-empty array/);
+  });
+
+  it("reports missing task dirs but still wires valid ones", async () => {
+    makeTask("a");
+    const res = await connectAgent({
+      connections: [
+        { listener: "a", speaker: "missing" },
+        { listener: "a", speaker: "a" }, // self connection skipped
+      ],
+    });
+    expect(res).toMatch(/speaker task dir not found: missing/);
+    expect(res).toMatch(/self-connection for a/);
+  });
+
+  it("relays only NEW assistant messages from speaker to listener", async () => {
+    // Speaker starts with one existing assistant message (should NOT be relayed)
+    makeTask("listener", []);
+    makeTask("speaker", [
+      { role: "assistant", content: "old message" },
+    ]);
+
+    await connectAgent({
+      connections: [{ listener: "listener", speaker: "speaker" }],
+      intervalMs: 1000,
+    });
+
+    // Now the speaker produces a new assistant message
+    writeThreads("speaker", [
+      { role: "assistant", content: "old message" },
+      { role: "assistant", content: "new insight" },
+    ]);
+
+    // Wait for a couple of poll cycles
+    await delay(1300);
+
+    const input = readInput("listener");
+    expect(input).toContain("[from:speaker] new insight");
+    expect(input).not.toContain("old message");
+  });
+
+  it("supports bidirectional in a single call (array of connections)", async () => {
+    makeTask("a", []);
+    makeTask("b", []);
+
+    await connectAgent({
+      connections: [
+        { listener: "a", speaker: "b" },
+        { listener: "b", speaker: "a" },
+      ],
+      intervalMs: 1000,
+    });
+
+    writeThreads("a", [{ role: "assistant", content: "from A" }]);
+    writeThreads("b", [{ role: "assistant", content: "from B" }]);
+
+    await delay(1300);
+
+    // A hears B, B hears A
+    expect(readInput("a")).toContain("[from:b] from B");
+    expect(readInput("b")).toContain("[from:a] from A");
+  });
+
+  it("stops a specific connection by id", async () => {
+    makeTask("l", []);
+    makeTask("s", []);
+    const res = await connectAgent({
+      connections: [{ listener: "l", speaker: "s" }],
+      intervalMs: 1000,
+    });
+    const idMatch = res.match(/conn_[A-Za-z0-9_]+/);
+    expect(idMatch).toBeTruthy();
+    const stopRes = await stopConnections({ id: idMatch![0] });
+    expect(stopRes).toMatch(/Stopped connection/);
+  });
+
+  it("stopConnections() with no id stops all", async () => {
+    makeTask("l2", []);
+    makeTask("s2", []);
+    await connectAgent({
+      connections: [{ listener: "l2", speaker: "s2" }],
+      intervalMs: 1000,
+    });
+    const res = await stopConnections({});
+    expect(res).toMatch(/Stopped 1 active connection/);
+  });
+});

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/);
+  });
+});