@tyvm/knowhow 0.0.137 → 0.0.140

package/src/services/modules/index.ts

@@ -7,6 +7,37 @@ import { KnowhowModule, ModuleContext } from "./types";
 import { services } from "../";
 import { toUniqueArray } from "../../utils";
 
+/**
+ * Module resolution search paths.
+ *
+ * A module's resolution order depends on WHICH config declared it:
+ *
+ * - Modules declared in the GLOBAL config should resolve against the global
+ *   install's node_modules (~/.knowhow/node_modules) — i.e. what's installed
+ *   alongside the global config. We still fall back to cwd paths as a last
+ *   resort so a globally-declared module can still be found if it only exists
+ *   locally.
+ *
+ * - Modules declared in the LOCAL config should resolve against the local
+ *   project first (cwd/.knowhow/node_modules), then the global config's
+ *   node_modules (~/.knowhow/node_modules), then cwd/node_modules.
+ */
+function localResolvePaths(): string[] {
+  return [
+    path.join(process.cwd(), ".knowhow", "node_modules"),
+    path.join(os.homedir(), ".knowhow", "node_modules"),
+    path.join(process.cwd(), "node_modules"),
+  ];
+}
+
+function globalResolvePaths(): string[] {
+  return [
+    path.join(os.homedir(), ".knowhow", "node_modules"),
+    path.join(process.cwd(), ".knowhow", "node_modules"),
+    path.join(process.cwd(), "node_modules"),
+  ];
+}
+
 export class ModulesService {
   async getDefaultContext() {
     return { ...services() };
@@ -19,7 +50,8 @@ export class ModulesService {
 
   async loadModulesFrom(
     config: { modules: string[] } & any,
-    context?: Partial<ModuleContext>
+    context?: Partial<ModuleContext>,
+    resolvePaths: string[] = localResolvePaths()
   ) {
     // If no context provided, fall back to global singletons
     if (!context) {
@@ -38,54 +70,84 @@ export class ModulesService {
 
     const allModulePaths = config.modules;
 
-    // Search paths: local .knowhow/node_modules first (where `knowhow modules install`
-    // puts packages for this project), then global ~/.knowhow/node_modules, and finally
-    // cwd/node_modules as a last resort. Putting cwd/node_modules last avoids accidentally
-    // picking up workspace-symlinked dev versions of modules (e.g. when running knowhow
-    // from within the knowhow monorepo itself) instead of the properly-installed version.
-    const resolvePaths = [
-      path.join(process.cwd(), ".knowhow", "node_modules"),
-      path.join(os.homedir(), ".knowhow", "node_modules"),
-      path.join(process.cwd(), "node_modules"),
-    ];
+    // `resolvePaths` (passed in by the caller) determines the search-path order.
+    // Global-config modules resolve against ~/.knowhow/node_modules first; local-config
+    // modules resolve against cwd/.knowhow/node_modules first. See localResolvePaths()
+    // and globalResolvePaths() above.
 
     for (const modulePath of allModulePaths) {
-      // Resolve relative paths relative to process.cwd() so that paths like
-      // "../../packages/knowhow-module-load-webpage" in knowhow.json work
-      // regardless of where the compiled output lives.
-      let resolvedPath: string;
+      // Build an ordered list of candidate resolutions for this module.
+      // Relative paths resolve to a single candidate (relative to cwd), while
+      // npm package names get one candidate per search path so we can fall
+      // back to the global install if a locally-symlinked (e.g. workspace dev)
+      // build fails to load (wrong Node ABI, broken build, etc.).
+      const candidates: string[] = [];
       if (modulePath.startsWith(".")) {
-        resolvedPath = path.resolve(process.cwd(), modulePath);
+        candidates.push(path.resolve(process.cwd(), modulePath));
       } else {
-        // For npm package names, try resolving from cwd first so locally-installed
-        // modules are found even when knowhow is installed globally.
+        // For npm package names, resolve against each search path individually
+        // (in priority order) so each becomes its own fallback candidate.
+        for (const searchPath of resolvePaths) {
+          try {
+            const resolved = require.resolve(modulePath, {
+              paths: [searchPath],
+            });
+            if (!candidates.includes(resolved)) candidates.push(resolved);
+          } catch {
+            // this search path doesn't have the module — try the next one
+          }
+        }
+        // Finally, normal require resolution as a last resort.
         try {
-          resolvedPath = require.resolve(modulePath, { paths: resolvePaths });
+          const resolved = require.resolve(modulePath);
+          if (!candidates.includes(resolved)) candidates.push(resolved);
         } catch {
-          resolvedPath = modulePath; // fall back to normal require resolution
+          // ignore — will fall through to the bare name below
         }
+        if (candidates.length === 0) candidates.push(modulePath);
       }
 
+      // Try each candidate in order. Only if EVERY candidate fails to load do
+      // we surface an error — a failure on one candidate (e.g. a stale local
+      // workspace build) should silently fall back to the next (e.g. the
+      // global install).
       let importedModule: KnowhowModule;
-      try {
-        const rawModule = require(resolvedPath);
-        importedModule = (rawModule.default || rawModule) as KnowhowModule;
-        context.Events?.log(
-          "ModulesService",
-          `🔌 Loading module: ${modulePath} (resolved: ${resolvedPath})`
-        );
-        await importedModule.init({
-          config,
-          cwd: process.cwd(),
-          context: context as ModuleContext,
-        });
-        context.Events?.log(
-          "ModulesService",
-          `✅ Module initialized: ${modulePath} (tools: ${importedModule.tools.length}, agents: ${importedModule.agents.length}, plugins: ${importedModule.plugins.length}, clients: ${importedModule.clients.length})`
-        );
-      } catch (err: any) {
+      let loaded = false;
+      const errors: { candidate: string; error: Error }[] = [];
+      for (const resolvedPath of candidates) {
+        try {
+          const rawModule = require(resolvedPath);
+          importedModule = (rawModule.default || rawModule) as KnowhowModule;
+          context.Events?.log(
+            "ModulesService",
+            `🔌 Loading module: ${modulePath} (resolved: ${resolvedPath})`
+          );
+          await importedModule.init({
+            config,
+            cwd: process.cwd(),
+            context: context as ModuleContext,
+          });
+          context.Events?.log(
+            "ModulesService",
+            `✅ Module initialized: ${modulePath} (tools: ${importedModule.tools.length}, agents: ${importedModule.agents.length}, plugins: ${importedModule.plugins.length}, clients: ${importedModule.clients.length})`
+          );
+          loaded = true;
+          break;
+        } catch (err: any) {
+          errors.push({ candidate: resolvedPath, error: err });
+          // try the next candidate
+        }
+      }
+
+      if (!loaded) {
+        // All candidates failed — report the last (most fully-resolved) error.
+        const last = errors[errors.length - 1];
+        const detail = last
+          ? `${last.error.message}`
+          : "no resolvable module found";
         process.stderr.write(
-          `\n⚠️  Failed to load module "${modulePath}": ${err.message}\n` +
+          `\n⚠️  Failed to load module "${modulePath}": ${detail}\n` +
+          `   Tried: ${candidates.join(", ") || "(none)"}\n` +
           `   Run "knowhow modules setup --global" or "knowhow modules install ${modulePath} --global" to fix this.\n\n`
         );
         continue;
@@ -130,14 +192,33 @@ export class ModulesService {
     const config = await getConfig();
 
     const globalConfig = await getGlobalConfig();
-    const allModulePaths = [
-      ...(globalConfig.modules || []),
-      ...(config.modules || []),
-    ];
-
-    return this.loadModulesFrom(
-      { ...config, modules: toUniqueArray(allModulePaths) },
-      context
+
+    const globalModules = toUniqueArray(globalConfig.modules || []);
+    // Local modules already loaded globally shouldn't be loaded again (a module
+    // that adds a CLI command would throw "already have command"). De-dupe local
+    // against global.
+    const localModules = toUniqueArray(config.modules || []).filter(
+      (m) => !globalModules.includes(m)
     );
+
+    // Load global-config modules resolving against the global install's
+    // node_modules (~/.knowhow/node_modules) first.
+    if (globalModules.length > 0) {
+      await this.loadModulesFrom(
+        { ...config, modules: globalModules },
+        context,
+        globalResolvePaths()
+      );
+    }
+
+    // Load local-config modules resolving against the local project's
+    // node_modules (cwd/.knowhow/node_modules) first.
+    if (localModules.length > 0) {
+      await this.loadModulesFrom(
+        { ...config, modules: localModules },
+        context,
+        localResolvePaths()
+      );
+    }
   }
 }

package/src/types.ts

@@ -35,6 +35,11 @@ export type GenerationSource = {
   outputName?: string;
   /** Pass to runAgentTask: enable .knowhow/processes/agents/<taskId> directory */
   syncFs?: boolean;
+  /**
+   * Pass to runAgentTask: push the agent's work to a remote Knowhow task
+   * (identified by this source's taskId).
+   */
+  syncRemote?: boolean;
   /**
    * Deterministic task ID for this source (used with syncFs).
    * Defaults to "generate:<sanitized-output>" when syncFs is enabled.

package/tests/agents/interrupt.test.ts

@@ -4,8 +4,10 @@
  * These verify the fix for the "agent gets stuck after /poke" bug:
  *  1. A stale (slow) operation that finishes AFTER its window was interrupted
  *     must NOT clobber a newer interruptible window's resolver.
- *  2. An interrupt() arriving with no active window must be queued and fire on
- *     the next makeInterruptible window (not silently dropped).
+ *  2. An interrupt() arriving with no active window is a no-op — there is
+ *     nothing to interrupt, so it must NOT be queued (a queued interrupt would
+ *     pre-empt the next tool call and drop its result). Any message supplied
+ *     with the poke is still added as a pending user message.
  *  3. Normal (non-interrupted) resolution still works.
  *  4. Errors propagate when not interrupted, and are swallowed when interrupted.
  */
@@ -20,7 +22,6 @@
 class InterruptHarness {
   private _interruptResolve: (() => void) | null = null;
   private _interruptToken = 0;
-  private _pendingInterrupt = false;
   public pendingUserMessages: any[] = [];
 
   addPendingUserMessage(m: any) {
@@ -43,12 +44,6 @@ class InterruptHarness {
 
       this._interruptResolve = () => finish(() => resolve(interruptValue));
 
-      if (this._pendingInterrupt) {
-        this._pendingInterrupt = false;
-        finish(() => resolve(interruptValue));
-        return;
-      }
-
       promise
         .then((result) => {
           finish(() => resolve(result));
@@ -69,9 +64,8 @@ class InterruptHarness {
     }
     if (this._interruptResolve) {
       this._interruptResolve();
-    } else {
-      this._pendingInterrupt = true;
     }
+    // No active window -> nothing to interrupt. Do NOT queue it.
   }
 
   get hasActiveResolver() {
@@ -157,19 +151,18 @@ describe("BaseAgent interrupt / makeInterruptible", () => {
     await expect(w2).resolves.toBe("fresh-result");
   });
 
-  test("interrupt() with no active window is queued and fires next window", async () => {
+  test("interrupt() with no active window is a no-op (NOT queued)", async () => {
     const h = new InterruptHarness();
     // No active window yet.
     expect(h.hasActiveResolver).toBe(false);
-    h.interrupt(); // queued, not dropped
+    h.interrupt(); // nothing to interrupt -> no-op
 
-    // Next window should fire immediately with the interrupt value.
+    // The next window must NOT be pre-empted — it should run its real op and
+    // resolve with the real result, not the interrupt value.
     const op = deferred<string>();
     const w = h.makeInterruptible(op.promise, "INT");
-    await expect(w).resolves.toBe("INT");
-    // Underlying op finishing later must be harmless.
-    op.resolve("later");
-    await op.promise;
+    op.resolve("real-result");
+    await expect(w).resolves.toBe("real-result");
   });
 
   test("errors propagate when not interrupted", async () => {

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