@tyvm/knowhow 0.0.138 → 0.0.141

package/tests/services/Tools.test.ts

@@ -1,4 +1,4 @@
-import { ToolsService, ToolContext } from "../../src/services/Tools";
+import { ToolsService, ToolContext, ToolCallContext } from "../../src/services/Tools";
 import { Tool, ToolCall } from "../../src/clients/types";
 import { createPatternMatcher } from "../../src/services/types";
 import { AgentService } from "../../src/services/AgentService";
@@ -268,7 +268,11 @@ describe("ToolsService", () => {
 
       const result = await toolsService.callTool(mockToolCall);
 
-      expect(mockFunction).toHaveBeenCalledWith({ input: "test value" });
+      // Non-positional tools receive `_ctx` merged onto the args object.
+      expect(mockFunction).toHaveBeenCalledWith(
+        expect.objectContaining({ input: "test value" })
+      );
+      expect(mockFunction.mock.calls[0][0]._ctx).toBeDefined();
       expect(result.toolMessages).toHaveLength(1);
       expect(result.toolMessages[0]).toEqual({
         tool_call_id: "call_123",
@@ -312,7 +316,12 @@ describe("ToolsService", () => {
 
       await toolsService.callTool(positionalCall);
 
-      expect(mockFunction).toHaveBeenCalledWith("hello", 42);
+      // Positional tools receive `_ctx` as the LAST positional argument.
+      expect(mockFunction).toHaveBeenCalledWith(
+        "hello",
+        42,
+        expect.objectContaining({ Tools: expect.anything() })
+      );
     });
 
     it("should handle tool not enabled error", async () => {
@@ -433,7 +442,10 @@ describe("ToolsService", () => {
 
       await toolsService.callTool(toolCallWithStringArgs);
 
-      expect(mockFunction).toHaveBeenCalledWith({ input: "escaped\nstring" });
+      expect(mockFunction).toHaveBeenCalledWith(
+        expect.objectContaining({ input: "escaped\nstring" })
+      );
+      expect(mockFunction.mock.calls[0][0]._ctx).toBeDefined();
     });
   });
   describe("Tool Override System", () => {
@@ -492,8 +504,9 @@ describe("ToolsService", () => {
 
       const result = await toolsService.callTool(toolCall);
 
+      // Non-positional args now include `_ctx`; the override receives them in an array.
       expect(overrideFunction).toHaveBeenCalledWith(
-        [{ input: "test" }],
+        [expect.objectContaining({ input: "test" })],
         expect.any(Object)
       );
       expect(originalFunction).not.toHaveBeenCalled();
@@ -627,7 +640,9 @@ describe("ToolsService", () => {
       const result = await toolsService.callTool(toolCall);
 
       expect(wrapperFunction).toHaveBeenCalled();
-      expect(originalFunction).toHaveBeenCalledWith({ input: "test" });
+      expect(originalFunction).toHaveBeenCalledWith(
+        expect.objectContaining({ input: "test" })
+      );
       expect(result.functionResp).toBe("wrapped: original result");
     });
 
@@ -841,7 +856,8 @@ describe("ToolsService", () => {
 
       const result = await toolsService.callTool(noParamCall);
 
-      expect(mockFunction).toHaveBeenCalledWith({});
+      expect(mockFunction).toHaveBeenCalledWith(expect.any(Object));
+      expect(mockFunction.mock.calls[0][0]._ctx).toBeDefined();
       expect(result.functionResp).toBe("no param result");
     });
 
@@ -897,14 +913,16 @@ describe("ToolsService", () => {
 
       const result = await toolsService.callTool(complexCall);
 
-      expect(mockFunction).toHaveBeenCalledWith({
+      expect(mockFunction).toHaveBeenCalledWith(
+        expect.objectContaining({
         config: {
           settings: [
             { key: "timeout", value: 5000 },
             { key: "retries", value: 3 },
           ],
         },
-      });
+        })
+      );
       expect(result.functionResp).toBe("complex result");
     });
 
@@ -1570,4 +1588,149 @@ describe("ToolsService", () => {
       expect(foundTools.map(t => t.function.name)).toContain("tool2");
     });
   });
+
+  describe("_ctx per-call context threading", () => {
+    const positionalTool: Tool = {
+      type: "function",
+      function: {
+        name: "posCtxTool",
+        parameters: {
+          type: "object",
+          positional: true,
+          properties: {
+            arg1: { type: "string" },
+          },
+          required: ["arg1"],
+        },
+      },
+    };
+
+    const nonPositionalTool: Tool = {
+      type: "function",
+      function: {
+        name: "nonPosCtxTool",
+        parameters: {
+          type: "object",
+          properties: {
+            input: { type: "string" },
+          },
+          required: ["input"],
+        },
+      },
+    };
+
+    it("passes _ctx as the last positional argument for positional tools", async () => {
+      const fn = jest.fn().mockResolvedValue("ok");
+      toolsService.addTool(positionalTool);
+      toolsService.setFunction("posCtxTool", fn);
+
+      const caller = { name: "TestAgent" };
+      await toolsService.callTool(
+        {
+          id: "c1",
+          type: "function",
+          function: {
+            name: "posCtxTool",
+            arguments: JSON.stringify({ arg1: "hello" }),
+          },
+        },
+        undefined,
+        { caller, taskId: "task-123" }
+      );
+
+      const callArgs = fn.mock.calls[0];
+      expect(callArgs[0]).toBe("hello");
+      const ctx = callArgs[1] as ToolCallContext;
+      expect(ctx).toBeDefined();
+      expect(ctx.caller).toBe(caller);
+      expect(ctx.taskId).toBe("task-123");
+      expect(ctx.Tools).toBe(toolsService);
+    });
+
+    it("merges _ctx onto the args object for non-positional tools", async () => {
+      const fn = jest.fn().mockResolvedValue("ok");
+      toolsService.addTool(nonPositionalTool);
+      toolsService.setFunction("nonPosCtxTool", fn);
+
+      const caller = { name: "TestAgent" };
+      await toolsService.callTool(
+        {
+          id: "c2",
+          type: "function",
+          function: {
+            name: "nonPosCtxTool",
+            arguments: JSON.stringify({ input: "value" }),
+          },
+        },
+        undefined,
+        { caller, taskId: "task-456" }
+      );
+
+      const argObj = fn.mock.calls[0][0];
+      expect(argObj.input).toBe("value");
+      expect(argObj._ctx).toBeDefined();
+      expect(argObj._ctx.caller).toBe(caller);
+      expect(argObj._ctx.taskId).toBe("task-456");
+      expect(argObj._ctx.Tools).toBe(toolsService);
+    });
+
+    it("still provides a _ctx (with Tools) when no callContext is passed", async () => {
+      const fn = jest.fn().mockResolvedValue("ok");
+      toolsService.addTool(nonPositionalTool);
+      toolsService.setFunction("nonPosCtxTool", fn);
+
+      await toolsService.callTool({
+        id: "c3",
+        type: "function",
+        function: {
+          name: "nonPosCtxTool",
+          arguments: JSON.stringify({ input: "value" }),
+        },
+      });
+
+      const argObj = fn.mock.calls[0][0];
+      expect(argObj._ctx).toBeDefined();
+      expect(argObj._ctx.Tools).toBe(toolsService);
+      expect(argObj._ctx.caller).toBeUndefined();
+    });
+
+    it("does not leak _ctx into the multi_tool_use.parallel extraction", async () => {
+      // The parallel path should extract calls from the ORIGINAL args, not the
+      // _ctx-augmented ones.
+      const parallelTool: Tool = {
+        type: "function",
+        function: {
+          name: "multi_tool_use.parallel",
+          parameters: { type: "object", properties: {} },
+        },
+      };
+      const inner = jest
+        .fn()
+        .mockResolvedValue(["r1", "r2"]);
+      toolsService.addTool(parallelTool);
+      toolsService.setFunction("multi_tool_use.parallel", inner);
+
+      const result = await toolsService.callTool(
+        {
+          id: "c4",
+          type: "function",
+          function: {
+            name: "multi_tool_use.parallel",
+            arguments: JSON.stringify([
+              { recipient_name: "functions.a", parameters: {} },
+              { recipient_name: "functions.b", parameters: {} },
+            ]),
+          },
+        },
+        undefined,
+        { caller: {}, taskId: "t" }
+      );
+
+      // Two tool messages, one per parallel call — proves extraction used the
+      // original array shape rather than an _ctx-wrapped object.
+      expect(result.toolMessages).toHaveLength(2);
+      expect(result.toolMessages[0].name).toBe("a");
+      expect(result.toolMessages[1].name).toBe("b");
+    });
+  });
 });

package/tests/unit/modules/moduleLoading.test.ts

@@ -1,3 +1,5 @@
+import * as os from "os";
+import * as path from "path";
 import { Config } from "../../../src/types";
 
 // Mock config before any other imports that depend on it
@@ -233,4 +235,71 @@ describe("ModulesService.loadModulesFromConfig", () => {
     expect(context.Agents.registerAgent).toHaveBeenCalledTimes(2);
     spy.mockRestore();
   });
+
+  it("resolves global-config modules against ~/.knowhow/node_modules first, local against cwd/.knowhow/node_modules first", async () => {
+    mockGetGlobalConfig.mockResolvedValue({
+      modules: ["global-pkg"],
+    } as unknown as Config);
+    mockGetConfig.mockResolvedValue({
+      modules: ["local-pkg"],
+    } as unknown as Config);
+
+    const service = new ModulesService();
+    const context = makeContext();
+
+    const calls: { modules: string[]; resolvePaths: string[] }[] = [];
+    const spy = jest
+      .spyOn(service as any, "loadModulesFrom")
+      .mockImplementation(async (...args: any[]) => {
+        const [cfg, , resolvePaths] = args;
+        calls.push({ modules: cfg.modules, resolvePaths });
+      });
+
+    await service.loadModulesFromConfig(context);
+
+    const globalKnowhow = path.join(os.homedir(), ".knowhow", "node_modules");
+    const localKnowhow = path.join(process.cwd(), ".knowhow", "node_modules");
+
+    const globalCall = calls.find((c) => c.modules.includes("global-pkg"));
+    const localCall = calls.find((c) => c.modules.includes("local-pkg"));
+
+    expect(globalCall).toBeDefined();
+    expect(localCall).toBeDefined();
+    // Global-config module: global node_modules is first in the search order
+    expect(globalCall!.resolvePaths[0]).toBe(globalKnowhow);
+    // Local-config module: local project node_modules is first in the search order
+    expect(localCall!.resolvePaths[0]).toBe(localKnowhow);
+
+    spy.mockRestore();
+  });
+
+  it("does not load a local module again if it is already declared globally (avoids duplicate command registration)", async () => {
+    mockGetGlobalConfig.mockResolvedValue({
+      modules: ["shared-pkg"],
+    } as unknown as Config);
+    mockGetConfig.mockResolvedValue({
+      modules: ["shared-pkg", "local-only-pkg"],
+    } as unknown as Config);
+
+    const service = new ModulesService();
+    const context = makeContext();
+
+    const loadedModuleLists: string[][] = [];
+    const spy = jest
+      .spyOn(service as any, "loadModulesFrom")
+      .mockImplementation(async (...args: any[]) => {
+        const [cfg] = args;
+        loadedModuleLists.push(cfg.modules);
+      });
+
+    await service.loadModulesFromConfig(context);
+
+    const allLoaded = loadedModuleLists.flat();
+    // shared-pkg loaded exactly once (via the global pass)
+    expect(allLoaded.filter((m) => m === "shared-pkg")).toHaveLength(1);
+    // local-only-pkg still loaded
+    expect(allLoaded).toContain("local-only-pkg");
+
+    spy.mockRestore();
+  });
 });

package/ts_build/package.json

@@ -1,11 +1,14 @@
 {
     "name": "@tyvm/knowhow",
-    "version": "0.0.138",
+    "version": "0.0.141",
     "description": "ai cli with plugins and agents",
     "main": "ts_build/src/index.js",
     "bin": {
         "knowhow": "bin/knowhow.js"
     },
+    "engines": {
+        "node": ">=20"
+    },
     "scripts": {
         "test": "jest --testTimeout 300000",
         "test:debug": "node --inspect-brk ../../node_modules/jest/bin/jest.js --detectOpenHandles --forceExit --testTimeout 300000",
@@ -39,7 +42,7 @@
         "@types/express": "^4.17.13",
         "@types/jest": "^29.5.13",
         "@types/mocha": "^10.0.8",
-        "@types/node": "^20.6.3",
+        "@types/node": "^24.0.0",
         "@types/ws": "^8.18.1",
         "jest": "^29.1.1",
         "prettier": "2.6.2",

package/ts_build/src/agents/base/base.d.ts

@@ -21,6 +21,22 @@ export interface ToolCallEvent {
     toolCall: ToolCall;
     functionResp: any;
 }
+export interface ObservationSource {
+    label: string;
+    start(emit: (datum: unknown) => void): void | (() => void) | Promise<void | (() => void)>;
+}
+export interface ObserveOpts {
+    onlyOnChange?: boolean;
+    maxUpdates?: number;
+    maxDurationMs?: number;
+}
+interface ActiveObservation {
+    id: string;
+    label: string;
+    updates: number;
+    teardownPromise: Promise<void | (() => void)>;
+    expiry?: NodeJS.Timeout;
+}
 export declare abstract class BaseAgent implements IAgent {
     abstract name: string;
     abstract description: string;
@@ -46,14 +62,17 @@ export declare abstract class BaseAgent implements IAgent {
     protected totalOutputTokens: number;
     protected totalCacheReadTokens: number;
     protected totalCacheWriteTokens: number;
+    protected lastPromptTokens: number;
     protected compressThreshold: number;
     protected compressMinMessages: number;
+    protected _forceCompact: boolean;
     private _interruptResolve;
     private _interruptToken;
-    private _pendingInterrupt;
     protected threads: Message[][];
     protected pendingUserMessages: Message[];
     protected pendingMessages: Message[];
+    protected _observations: Map<string, ActiveObservation>;
+    private _observationSeq;
     protected taskBreakdown: string;
     protected summaries: string[];
     protected currentTaskId: string | null;
@@ -87,6 +106,7 @@ export declare abstract class BaseAgent implements IAgent {
     constructor(context: AgentContext);
     protected log(message: string, level?: "info" | "warn" | "error"): void;
     setCompressThreshold(threshold: number): void;
+    requestCompact(): void;
     getCompressThreshold(): number;
     setMaxTurns(maxTurns: number | null): void;
     setMaxSpend(maxSpend: number | null): void;
@@ -155,7 +175,10 @@ export declare abstract class BaseAgent implements IAgent {
     logStatus(): void;
     addPendingMessage(message: Message): void;
     addPendingUserMessage(message: Message): void;
+    observe(source: ObservationSource, opts?: ObserveOpts): string;
+    stopObserving(id?: string, reason?: string): string;
     getMessagesLength(messages: Message[]): number;
+    getContextTokenCount(messages: Message[]): number;
     detectTruncatedToolCalls(toolCalls: ToolCall[], response: CompletionResponse): {
         role: string;
         content: string;

package/ts_build/src/agents/base/base.js

@@ -30,14 +30,17 @@ class BaseAgent {
     totalOutputTokens = 0;
     totalCacheReadTokens = 0;
     totalCacheWriteTokens = 0;
+    lastPromptTokens = 0;
     compressThreshold = 30000;
     compressMinMessages = 30;
+    _forceCompact = false;
     _interruptResolve = null;
     _interruptToken = 0;
-    _pendingInterrupt = false;
     threads = [];
     pendingUserMessages = [];
     pendingMessages = [];
+    _observations = new Map();
+    _observationSeq = 0;
     taskBreakdown = "";
     summaries = [];
     currentTaskId = null;
@@ -105,6 +108,9 @@ class BaseAgent {
     setCompressThreshold(threshold) {
         this.compressThreshold = threshold;
     }
+    requestCompact() {
+        this._forceCompact = true;
+    }
     getCompressThreshold() {
         if (this.compressThreshold !== contextLimits_1.DEFAULT_CONTEXT_LIMIT) {
             return this.compressThreshold;
@@ -112,7 +118,7 @@ class BaseAgent {
         const result = this.clientService.getContextLimit(this.getProvider(), this.getModel());
         const contextLimit = result?.contextLimit ?? contextLimits_1.DEFAULT_CONTEXT_LIMIT;
         const threshold = result?.threshold ?? contextLimit;
-        return Math.floor(threshold * 0.85);
+        return Math.floor(threshold * 0.7);
     }
     setMaxTurns(maxTurns) {
         this.maxTurns = maxTurns;
@@ -133,12 +139,14 @@ class BaseAgent {
         this.totalOutputTokens = 0;
         this.totalCacheReadTokens = 0;
         this.totalCacheWriteTokens = 0;
+        this.lastPromptTokens = 0;
         this.status = this.eventTypes.inProgress;
         this.turnCount = 0;
         this.startTimeMs = Date.now();
         this.currentTaskId = taskId || this.startTimeMs.toString();
         this._interruptResolve = null;
-        this._pendingInterrupt = false;
+        this._forceCompact = false;
+        this.stopObserving(undefined, "new task started");
         const id = taskId || this.startTimeMs.toString();
         this.events.emit(this.eventTypes.agentNewTask, {
             taskId: id,
@@ -318,6 +326,10 @@ class BaseAgent {
             usage.prompt_tokens_details?.cached_tokens ??
             0;
         const cacheWriteTokens = usage.cache_creation_input_tokens ?? usage.cache_write_tokens ?? 0;
+        const promptTokens = inputTokens + cacheReadTokens + cacheWriteTokens;
+        if (promptTokens > 0) {
+            this.lastPromptTokens = promptTokens;
+        }
         this.totalInputTokens += inputTokens;
         this.totalOutputTokens += outputTokens;
         this.totalCacheReadTokens += cacheReadTokens;
@@ -385,7 +397,10 @@ class BaseAgent {
                 },
             ],
         };
-        const { functionResp, toolMessages } = await this.makeInterruptible(this.tools.callTool(toolCall, this.getEnabledToolNames()), interruptResult);
+        const { functionResp, toolMessages } = await this.makeInterruptible(this.tools.callTool(toolCall, this.getEnabledToolNames(), {
+            caller: this,
+            taskId: this.currentTaskId,
+        }), interruptResult);
         this.agentEvents.emit(this.eventTypes.toolUsed, {
             toolCall,
             functionResp,
@@ -521,11 +536,6 @@ class BaseAgent {
                 fn();
             };
             this._interruptResolve = () => finish(() => resolve(interruptValue));
-            if (this._pendingInterrupt) {
-                this._pendingInterrupt = false;
-                finish(() => resolve(interruptValue));
-                return;
-            }
             promise
                 .then((result) => {
                 finish(() => resolve(result));
@@ -547,8 +557,7 @@ class BaseAgent {
             this._interruptResolve();
         }
         else {
-            this._pendingInterrupt = true;
-            this.log("No active interruptible operation — queued interrupt for next step", "warn");
+            this.log("No active interruptible operation to interrupt", "warn");
         }
     }
     async call(userInput, _messages, retryCount = 0) {
@@ -608,8 +617,12 @@ class BaseAgent {
                 tools: this.getEnabledTools(),
                 tool_choice: "auto",
                 long_ttl_cache: this.runTime() > 300_000,
-                ...(this.reasoningEffort !== undefined && { reasoning_effort: this.reasoningEffort }),
-                ...(this.summarizeReasoning !== undefined && { reasoning_summary: this.summarizeReasoning }),
+                ...(this.reasoningEffort !== undefined && {
+                    reasoning_effort: this.reasoningEffort,
+                }),
+                ...(this.summarizeReasoning !== undefined && {
+                    reasoning_summary: this.summarizeReasoning,
+                }),
             }, { interruptValue: interruptResponse });
             if (this.status === this.eventTypes.pause) {
                 this.log("Agent was paused after completion, waiting before processing tool calls");
@@ -710,12 +723,18 @@ class BaseAgent {
                 this.agentEvents.emit(this.eventTypes.done, firstMessage.content);
                 return firstMessage.content;
             }
-            if (this.getMessagesLength(messages) > this.getCompressThreshold() &&
-                messages.length > this.compressMinMessages) {
+            const contextTokens = this.getContextTokenCount(messages);
+            const overThreshold = contextTokens > this.getCompressThreshold() &&
+                messages.length > this.compressMinMessages;
+            if (overThreshold || this._forceCompact) {
                 const taskBreakdown = await this.getTaskBreakdown(messages);
-                this.log(`Compressing messages: ${this.getMessagesLength(messages)} exceeds ${this.getCompressThreshold()}`);
+                this.log(this._forceCompact
+                    ? `Compacting messages (manual /compact request): ${contextTokens} tokens`
+                    : `Compressing messages: ${contextTokens} tokens exceeds ${this.getCompressThreshold()}`);
+                this._forceCompact = false;
                 messages = await this.compressMessages(messages, startIndex, endIndex);
                 this.startNewThread(messages);
+                this.lastPromptTokens = 0;
             }
             if (["assistant", "tool"].includes(messages[messages.length - 1].role)) {
                 const statusMessage = this.getStatusMessage();
@@ -836,9 +855,85 @@ class BaseAgent {
         }
         this.events.emit(this.eventTypes.userSay, message.content);
     }
+    observe(source, opts = {}) {
+        const { onlyOnChange = true, maxUpdates = 20, maxDurationMs = 10 * 60 * 1000, } = opts;
+        this._observationSeq += 1;
+        const safeLabel = source.label.replace(/[^A-Za-z0-9]+/g, "_").slice(0, 24);
+        const id = `obs_${safeLabel}_${Date.now()}_${this._observationSeq}`;
+        let last;
+        const emit = (datum) => {
+            if (this.status === this.eventTypes.done) {
+                this.stopObserving(id);
+                return;
+            }
+            const str = typeof datum === "string" ? datum : JSON.stringify(datum);
+            if (onlyOnChange && str === last)
+                return;
+            last = str;
+            const obs = this._observations.get(id);
+            if (!obs)
+                return;
+            obs.updates += 1;
+            this.addPendingMessage({
+                role: "user",
+                content: `[observe:${id}] ${source.label} (update ${obs.updates}/${maxUpdates}):\n${str}`,
+            });
+            if (obs.updates >= maxUpdates) {
+                this.stopObserving(id, "max updates reached");
+            }
+        };
+        const teardownPromise = Promise.resolve(source.start(emit)).catch((e) => {
+            this.log(`observe(${source.label}) start failed: ${e?.message ?? e}`, "warn");
+            return undefined;
+        });
+        const expiry = maxDurationMs
+            ? setTimeout(() => this.stopObserving(id, "max duration reached"), maxDurationMs)
+            : undefined;
+        if (expiry && typeof expiry.unref === "function") {
+            expiry.unref();
+        }
+        this._observations.set(id, {
+            id,
+            label: source.label,
+            updates: 0,
+            teardownPromise,
+            expiry,
+        });
+        return id;
+    }
+    stopObserving(id, reason = "stopped") {
+        const ids = id ? [id] : [...this._observations.keys()];
+        let stopped = 0;
+        for (const oid of ids) {
+            const obs = this._observations.get(oid);
+            if (!obs)
+                continue;
+            if (obs.expiry)
+                clearTimeout(obs.expiry);
+            Promise.resolve(obs.teardownPromise)
+                .then((fn) => {
+                if (typeof fn === "function")
+                    fn();
+            })
+                .catch(() => { });
+            this._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}).`;
+    }
     getMessagesLength(messages) {
         return JSON.stringify(messages).split(" ").length;
     }
+    getContextTokenCount(messages) {
+        if (this.lastPromptTokens > 0) {
+            return this.lastPromptTokens;
+        }
+        return this.getMessagesLength(messages);
+    }
     detectTruncatedToolCalls(toolCalls, response) {
         const rawOutputTokens = response?.usage?.completion_tokens || 0;
         const thinkingTokens = (response?.usage?.output_tokens_details?.thinking_tokens ?? 0) +