@tyvm/knowhow 0.0.138 → 0.0.141

package/src/services/MinimalToolsService.ts

@@ -1,4 +1,4 @@
-import { ToolsService, ToolContext } from "./Tools";
+import { ToolsService, ToolContext, ToolCallContext } from "./Tools";
 import { Tool, ToolCall } from "../clients/types";
 import { callTool } from "../agents/tools/minimal/callTool";
 import { inspectTools } from "../agents/tools/minimal/inspectTools";
@@ -107,7 +107,11 @@ export class MinimalToolsService extends ToolsService {
    * Used both by direct calls (agent calls the tool by its real name) and by
    * the callTool meta-tool (agent calls callTool({ name, args })).
    */
-  private async dispatchToTool(toolCall: ToolCall, resolvedName: string) {
+  private async dispatchToTool(
+    toolCall: ToolCall,
+    resolvedName: string,
+    callContext?: ToolCallContext
+  ) {
     // Temporarily surface the target tool in the visible list so base
     // ToolsService.callTool can find its definition, then restore state.
     const alreadyVisible = super
@@ -123,7 +127,7 @@ export class MinimalToolsService extends ToolsService {
       }
     }
 
-    const result = await super.callTool(toolCall, [resolvedName]);
+    const result = await super.callTool(toolCall, [resolvedName], callContext);
 
     // Remove the temporarily-added tool to keep the visible set stable
     if (!alreadyVisible) {
@@ -136,7 +140,11 @@ export class MinimalToolsService extends ToolsService {
   /**
    * Delegates to the full catalog for resolution, then runs via callToolByName.
    */
-  async callTool(toolCall: ToolCall, enabledTools?: string[]): Promise<any> {
+  async callTool(
+    toolCall: ToolCall,
+    enabledTools?: string[],
+    callContext?: ToolCallContext
+  ): Promise<any> {
     const functionName = toolCall.function.name;
 
     // Base tools (callTool, inspectTools, finalAnswer) → standard dispatch
@@ -145,7 +153,7 @@ export class MinimalToolsService extends ToolsService {
       .some((t) => t.function.name === functionName);
 
     if (isBaseTool) {
-      return super.callTool(toolCall, this.getToolNames());
+      return super.callTool(toolCall, this.getToolNames(), callContext);
     }
 
     // Extended tools: called directly by name (not via the callTool meta-tool).
@@ -158,10 +166,10 @@ export class MinimalToolsService extends ToolsService {
     );
 
     if (existsInCatalog) {
-      return this.dispatchToTool(toolCall, functionName);
+      return this.dispatchToTool(toolCall, functionName, callContext);
     }
 
     // Not found anywhere - let the base class produce the standard error.
-    return super.callTool(toolCall, [functionName]);
+    return super.callTool(toolCall, [functionName], callContext);
   }
 }

package/src/services/SyncedAgentWatcher.ts

@@ -58,6 +58,8 @@ export interface AttachableAgent {
   unpause(): void | Promise<void>;
   kill(): void | Promise<void>;
   interrupt(message?: string): void | Promise<void>;
+  /** Force conversation compaction at the next loop iteration (local agents only). */
+  requestCompact?(): void;
   addPendingUserMessage(message: Message): void;
 }
 

package/src/services/SyncerService.ts

@@ -13,10 +13,16 @@ export interface SyncerOptions {
   messageId?: string;
   /** Force fs sync even if messageId is provided */
   syncFs?: boolean;
-  /** Use an existing Knowhow task ID instead of creating a new one */
-  existingKnowhowTaskId?: string;
+  /**
+   * Push the agent's work to a remote Knowhow task. When set (and there is no
+   * messageId), the `taskId` is treated as the remote task ID to attach to and
+   * push updates to, rather than creating a new remote task.
+   */
+  syncRemote?: boolean;
   /** Agent name to persist in metadata.json */
   agentName?: string;
+  /** The taskId of the parent agent that spawned this task, if any. */
+  parentTaskId?: string;
 }
 
 export interface AgentSyncer {
@@ -37,7 +43,8 @@ export interface AgentSyncer {
  *
  * Decision logic:
  *   - Always sets up AgentSyncFs (primary local syncer)
- *   - If messageId is present AND syncFs is not forced AND no existingKnowhowTaskId → also sets up AgentSyncKnowhowWeb
+ *   - If messageId is present AND syncFs is not forced → creates a new remote task via AgentSyncKnowhowWeb
+ *   - If syncRemote is set (and no messageId) → attaches to the remote task identified by taskId
  */
 export class SyncerService implements AgentSyncer {
   private fsSync: AgentSyncFs;
@@ -59,11 +66,23 @@ export class SyncerService implements AgentSyncer {
     this.active = true;
     this.useWebSync = false;
 
-    // Determine whether to use web sync
+    // Determine whether to CREATE a new remote (web) task: only when we have a
+    // messageId and aren't forcing fs-only. A messageId means "definitely
+    // remote" — create a fresh remote task from that message.
     const shouldUseWebSync =
       !!options.messageId &&
-      !options.syncFs &&
-      !options.existingKnowhowTaskId;
+      !options.syncFs;
+
+    // Determine whether to ATTACH to an already-existing remote task and push
+    // local work to it (no creation needed). This is the "--sync-remote" path:
+    // the caller wants to push work to the remote task identified by taskId.
+    // We only auto-attach when there is NO messageId (messageId always creates
+    // a fresh remote task above).
+    //
+    // This is orthogonal to fs sync: we can push to the remote task AND keep
+    // the local .knowhow/processes/agents/<id>/ files in sync at the same time.
+    const shouldAttachExisting =
+      !!options.syncRemote && !options.messageId && !!options.taskId;
 
     // Always create fs sync task first
     console.log(
@@ -73,6 +92,7 @@ export class SyncerService implements AgentSyncer {
       taskId: options.taskId,
       prompt: options.prompt,
       agentName: options.agentName,
+      parentTaskId: options.parentTaskId,
     });
 
     // Optionally create web sync task
@@ -89,6 +109,15 @@ export class SyncerService implements AgentSyncer {
       }
     }
 
+    // Attach live web sync to an existing remote task (push updates to it).
+    if (!shouldUseWebSync && shouldAttachExisting) {
+      this.useWebSync = true;
+      this.createdTaskId = options.taskId;
+      console.log(
+        `🌐 Attaching web sync to existing remote task: ${options.taskId}`
+      );
+    }
+
     return fsTaskId;
   }
 

package/src/services/Tools.ts

@@ -16,6 +16,28 @@ import { PluginService } from "../plugins/plugins";
 import { McpService } from "./Mcp";
 import { BehaviorsService } from "./BehaviorsService";
 
+/**
+ * Per-invocation context passed into a tool call as `_ctx`.
+ *
+ * This is threaded through `callTool` and delivered to the tool implementation
+ * as the LAST positional argument (for positional tools) or merged onto the
+ * args object under the `_ctx` key (for non-positional tools).
+ *
+ * It enables self-referential tools: the calling agent can pass itself in via
+ * `caller`, so tools can read `caller.getCurrentTaskId()`, call
+ * `caller.addPendingUserMessage(...)`, subscribe to its events, etc. — without
+ * relying on shared mutable state on the ToolsService (which would break under
+ * concurrent tool usage).
+ */
+export interface ToolCallContext {
+  /** The agent (or other entity) that initiated this tool call. */
+  caller?: any;
+  /** The task id of the calling agent, if known. */
+  taskId?: string;
+  /** Arbitrary additional per-call context. */
+  [key: string]: any;
+}
+
 export interface ToolContext {
   Agents?: AgentService;
   Events?: EventService;
@@ -174,7 +196,11 @@ export class ToolsService {
     this.addFunctions(functions);
   }
 
-  async callTool(toolCall: ToolCall, enabledTools = this.getToolNames()) {
+  async callTool(
+    toolCall: ToolCall,
+    enabledTools = this.getToolNames(),
+    callContext?: ToolCallContext
+  ) {
     const functionName = toolCall.function.name;
     let functionArgs: any;
 
@@ -219,10 +245,21 @@ export class ToolsService {
       const properties = toolDefinition?.function?.parameters?.properties || {};
       const isPositional =
         toolDefinition?.function?.parameters?.positional || false;
-      const fnArgs = isPositional
+
+      // Thread the per-call context (`_ctx`) into the invocation so tools can be
+      // self-referential (e.g. read the calling agent off `_ctx.caller`).
+      // - positional tools receive `_ctx` as the LAST positional argument
+      // - non-positional tools receive it merged onto the args object as `_ctx`
+      const ctx: ToolCallContext = { ...(callContext || {}), Tools: this };
+
+      const positionalArgs = isPositional
         ? Object.keys(properties).map((p) => functionArgs[p])
         : functionArgs;
 
+      const fnArgs = isPositional
+        ? [...positionalArgs, ctx]
+        : { ...functionArgs, _ctx: ctx };
+
       // Execute the function
       const rawResponse = isPositional
         ? functionToCall.call(this, ...fnArgs)
@@ -250,7 +287,10 @@ export class ToolsService {
       // Handle special case for parallel tool use
       if (functionName === "multi_tool_use.parallel") {
         // Extract tool_calls array from arguments
-        const toolCallsArg = Array.isArray(fnArgs) ? fnArgs : [fnArgs];
+        // Use the original (un-`_ctx`-augmented) args for extraction.
+        const toolCallsArg = Array.isArray(functionArgs)
+          ? functionArgs
+          : [functionArgs];
         const toolCalls = Array.isArray(toolCallsArg) ? toolCallsArg : [];
 
         const calls = toolCalls as {

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 () => {