@tyvm/knowhow 0.0.159 → 0.0.161

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

@@ -1,183 +0,0 @@
-/**
- * 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

@@ -1,138 +0,0 @@
-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

@@ -1,179 +0,0 @@
-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/readFile.test.ts

@@ -1,88 +0,0 @@
-import * as fs from "fs";
-import * as os from "os";
-import * as path from "path";
-import { readFile } from "../../../src/agents/tools/readFile";
-
-/**
- * These tests cover the readFile tool improvements:
- *  - plain text output (no unified-diff / Index: wrapper)
- *  - optional 1-based inclusive line ranges with real source line numbers
- */
-describe("readFile tool", () => {
-  let tmpFile: string;
-  const fileLines = [
-    "import x from 'y';",
-    "",
-    "function add(a, b) {",
-    "  return a + b;",
-    "}",
-    "",
-    "export default add;",
-  ];
-
-  // Minimal ToolsService-like context so readFile can resolve getContext()
-  // without depending on the global singletons.
-  const fakeThis: any = {
-    getContext: () => ({ Events: undefined }),
-  };
-
-  beforeEach(() => {
-    tmpFile = path.join(
-      os.tmpdir(),
-      `readFile-test-${Date.now()}-${Math.random().toString(36).slice(2)}.ts`
-    );
-    fs.writeFileSync(tmpFile, fileLines.join("\n"), "utf8");
-  });
-
-  afterEach(() => {
-    if (fs.existsSync(tmpFile)) {
-      fs.unlinkSync(tmpFile);
-    }
-  });
-
-  it("returns plain text with no diff/patch wrapper", async () => {
-    const result = await readFile.call(fakeThis, tmpFile);
-
-    expect(result).toBe(fileLines.join("\n"));
-    // The old behavior wrapped reads in a unified diff; make sure that's gone.
-    expect(result).not.toContain("Index:");
-    expect(result).not.toContain("@@");
-    expect(result).not.toMatch(/^\+/m);
-  });
-
-  it("returns a line range with real source line numbers", async () => {
-    const result = await readFile.call(fakeThis, tmpFile, 3, 5);
-
-    expect(result).toBe(
-      ["3: function add(a, b) {", "4:   return a + b;", "5: }"].join("\n")
-    );
-  });
-
-  it("defaults toLine to the end of file when omitted", async () => {
-    const result = await readFile.call(fakeThis, tmpFile, 6);
-
-    expect(result).toBe(["6: ", "7: export default add;"].join("\n"));
-  });
-
-  it("clamps an out-of-range toLine to the last line", async () => {
-    const result = await readFile.call(fakeThis, tmpFile, 6, 9999);
-
-    expect(result).toBe(["6: ", "7: export default add;"].join("\n"));
-  });
-
-  it("throws when fromLine is greater than toLine", async () => {
-    await expect(readFile.call(fakeThis, tmpFile, 5, 2)).rejects.toThrow(
-      /Invalid line range/
-    );
-  });
-
-  it("throws a helpful error when the file does not exist", async () => {
-    const missing = path.join(
-      os.tmpdir(),
-      "definitely-not-here-xyz.unknownext"
-    );
-    await expect(readFile.call(fakeThis, missing)).rejects.toThrow(
-      /File not found/
-    );
-  });
-});