@tyvm/knowhow 0.0.128 → 0.0.130

package/src/agents/base/base.ts

@@ -1,6 +1,7 @@
 import { EventEmitter } from "events"; // kept for reference; agentEvents now uses EventService
 import {
   CompletionResponse,
+  CompletionOptions,
   GenericClient,
   Message,
   MessageContent,
@@ -26,6 +27,8 @@ export { Message, Tool, ToolCall };
 export interface ModelPreference {
   model: string;
   provider: keyof typeof Clients.clients;
+  reasoning_effort?: CompletionOptions["reasoning_effort"];
+  reasoning_summary?: boolean;
 }
 
 export interface AgentContext {
@@ -60,6 +63,8 @@ export abstract class BaseAgent implements IAgent {
   protected turnCount = 0;
   protected totalCostUsd = 0;
   protected currentThread = 0;
+  protected reasoningEffort: CompletionOptions["reasoning_effort"] | undefined = undefined;
+  protected summarizeReasoning: boolean | undefined = undefined;
   protected totalInputTokens = 0;
   protected totalOutputTokens = 0;
   protected totalCacheReadTokens = 0;
@@ -69,7 +74,7 @@ export abstract class BaseAgent implements IAgent {
   protected compressMinMessages = 30;
 
   // Interrupt support: resolves the currently awaited tool call or completion
-  private _interruptResolve: ((value: any) => void) | null = null;
+  private _interruptResolve: (() => void) | null = null;
 
   protected threads = [] as Message[][];
 
@@ -233,6 +238,12 @@ export abstract class BaseAgent implements IAgent {
   updatePreferences(value: ModelPreference) {
     this.setModel(value.model);
     this.setProvider(value.provider);
+    if (value.reasoning_effort !== undefined) {
+      this.reasoningEffort = value.reasoning_effort;
+    }
+    if (value.reasoning_summary !== undefined) {
+      this.summarizeReasoning = value.reasoning_summary;
+    }
   }
 
   nextModel() {
@@ -262,6 +273,22 @@ export abstract class BaseAgent implements IAgent {
     this.client = null; // Reset client to force re-fetch
   }
 
+  setReasoningEffort(effort: CompletionOptions["reasoning_effort"]) {
+    this.reasoningEffort = effort;
+  }
+
+  getReasoningEffort(): CompletionOptions["reasoning_effort"] {
+    return this.reasoningEffort;
+  }
+
+  setSummarizeReasoning(value: boolean) {
+    this.summarizeReasoning = value;
+  }
+
+  getSummarizeReasoning(): boolean | undefined {
+    return this.summarizeReasoning;
+  }
+
   getClient() {
     if (!this.client) {
       if (this.provider) {
@@ -305,14 +332,16 @@ export abstract class BaseAgent implements IAgent {
     // Short response (≤ 3 words) that matches a termination word/phrase exactly
     const wordCount = trimmed.split(/\s+/).filter(Boolean).length;
     if (wordCount <= 3) {
-      const terminationPattern = /^(done|complete|completed|finished|final\s*answer|task\s*complete|all\s*done|that'?s\s*(all|it)|ok(ay)?|yes)[.!]*$/i;
+      const terminationPattern =
+        /^(done|complete|completed|finished|final\s*answer|task\s*complete|all\s*done|that'?s\s*(all|it)|ok(ay)?|yes)[.!]*$/i;
       if (terminationPattern.test(trimmed)) return true;
     }
 
     // Check if the first 1-3 words indicate task completion (for longer responses)
     // e.g. "Task complete: ...", "All done.", "No further changes needed.", "Confirmed complete."
     const firstWords = trimmed.split(/\s+/).slice(0, 3).join(" ");
-    const firstWordPattern = /^(task\s*(complete|completed|done|finished)|all\s*done|no\s*(further|more|additional|changes|action)|confirmed?\s*(complete|done|finished|one\s*last)|nothing\s*(more|further|else)|standing\s*by|everything\s*is|still\s*confirmed|acknowledged|done\s*and|complete\s*(and|\.)|completed\s*successfully|no\s*additional|verified\s*and)/i;
+    const firstWordPattern =
+      /^(task\s*(complete|completed|done|finished)|all\s*done|no\s*(further|more|additional|changes|action)|confirmed?\s*(complete|done|finished|one\s*last)|nothing\s*(more|further|else)|standing\s*by|everything\s*is|still\s*confirmed|acknowledged|done\s*and|complete\s*(and|\.)|completed\s*successfully|no\s*additional|verified\s*and)/i;
     if (firstWordPattern.test(firstWords)) return true;
 
     // If easyFinalAnswer mode is on, also match response starting with "✅" or numbered confirmation lists
@@ -418,15 +447,17 @@ export abstract class BaseAgent implements IAgent {
     return this.totalCostUsd;
   }
 
-  adjustTokenUsage(usage: any) {
+  adjustTokenUsage(usage: any, messages?: Message[]) {
     if (!usage) return;
     // Support both OpenAI-style (prompt_tokens/completion_tokens) and Anthropic-style (input_tokens/output_tokens)
     const inputTokens = usage.input_tokens ?? usage.prompt_tokens ?? 0;
     const outputTokens = usage.output_tokens ?? usage.completion_tokens ?? 0;
 
     const cacheReadTokens =
-      usage.cache_read_input_tokens ?? usage.cache_read_tokens ??
-      usage.prompt_tokens_details?.cached_tokens ?? 0;
+      usage.cache_read_input_tokens ??
+      usage.cache_read_tokens ??
+      usage.prompt_tokens_details?.cached_tokens ??
+      0;
     const cacheWriteTokens =
       usage.cache_creation_input_tokens ?? usage.cache_write_tokens ?? 0;
 
@@ -436,6 +467,7 @@ export abstract class BaseAgent implements IAgent {
     this.totalCacheWriteTokens += cacheWriteTokens;
 
     this.agentEvents.emit(this.eventTypes.tokenUsage, {
+      timestamp: new Date().toISOString(),
       inputTokens,
       outputTokens,
       cacheReadTokens,
@@ -444,6 +476,7 @@ export abstract class BaseAgent implements IAgent {
       totalOutputTokens: this.totalOutputTokens,
       totalCacheReadTokens: this.totalCacheReadTokens,
       totalCacheWriteTokens: this.totalCacheWriteTokens,
+      messages,
     });
   }
 
@@ -456,6 +489,37 @@ export abstract class BaseAgent implements IAgent {
     };
   }
 
+  /**
+   * Centralized helper for making an AI completion call while ensuring
+   * cost (totalCostUsd) and token usage (input/output/cache) are always
+   * updated consistently, regardless of which part of the agent triggers
+   * the completion (main call loop, task breakdown, compression, etc).
+   *
+   * Optionally supports being interrupted via makeInterruptible by passing
+   * an `interruptValue` in options - if the operation is interrupted, the
+   * interrupt value is returned and used for cost/usage tracking (which,
+   * for a typical interrupt stub with no usage/cost, is effectively a
+   * no-op).
+   */
+  protected async createAgentCompletion(
+    params: Parameters<GenericClient["createChatCompletion"]>[0],
+    options: {
+      interruptValue?: CompletionResponse;
+    } = {}
+  ): Promise<CompletionResponse> {
+    const { interruptValue } = options;
+
+    const callPromise = this.getClient().createChatCompletion(params);
+    const response = interruptValue
+      ? await this.makeInterruptible(callPromise, interruptValue)
+      : await callPromise;
+
+    this.adjustTotalCostUsd(response?.usd_cost);
+    this.adjustTokenUsage(response?.usage, params.messages);
+
+    return response;
+  }
+
   startNewThread(messages: Message[]) {
     this.currentThread++;
     this.agentEvents.emit(this.eventTypes.newThread, messages);
@@ -488,7 +552,14 @@ export abstract class BaseAgent implements IAgent {
       toolCallId: toolCall.id,
       functionName: toolCall.function?.name,
       functionArgs: {},
-      toolMessages: [{ role: "tool", tool_call_id: toolCall.id, name: toolCall.function?.name, content: interruptMsg }],
+      toolMessages: [
+        {
+          role: "tool",
+          tool_call_id: toolCall.id,
+          name: toolCall.function?.name,
+          content: interruptMsg,
+        },
+      ],
     };
 
     const { functionResp, toolMessages } = await this.makeInterruptible(
@@ -671,29 +742,31 @@ export abstract class BaseAgent implements IAgent {
     return new Promise<T>((resolve, reject) => {
       let interrupted = false;
 
-      this._interruptResolve = (value: any) => {
+      this._interruptResolve = () => {
         interrupted = true;
         this._interruptResolve = null;
-        resolve(value);
+        resolve(interruptValue);
       };
 
-      promise.then((result) => {
-        if (this._interruptResolve) {
-          this._interruptResolve = null;
-          resolve(result);
-        }
-      }).catch((err) => {
-        if (this._interruptResolve) {
-          this._interruptResolve = null;
-        }
-        // Only swallow the error if interrupt() was explicitly called.
-        // Otherwise re-throw so callers see the real error.
-        if (interrupted) {
-          resolve(interruptValue);
-        } else {
-          reject(err);
-        }
-      });
+      promise
+        .then((result) => {
+          if (this._interruptResolve) {
+            this._interruptResolve = null;
+            resolve(result);
+          }
+        })
+        .catch((err) => {
+          if (this._interruptResolve) {
+            this._interruptResolve = null;
+          }
+          // Only swallow the error if interrupt() was explicitly called.
+          // Otherwise re-throw so callers see the real error.
+          if (interrupted) {
+            resolve(interruptValue);
+          } else {
+            reject(err);
+          }
+        });
     });
   }
 
@@ -705,7 +778,7 @@ export abstract class BaseAgent implements IAgent {
   interrupt(message = "User interrupted this action you were waiting on") {
     this.log(`Interrupting current operation: ${message}`);
     if (this._interruptResolve) {
-      this._interruptResolve(message);
+      this._interruptResolve();
     } else {
       this.log("No active interruptible operation to interrupt", "warn");
     }
@@ -782,20 +855,30 @@ export abstract class BaseAgent implements IAgent {
       );
 
       const interruptResponse: CompletionResponse = {
-        choices: [{ message: { role: "assistant", content: "User interrupted this AI completion. Please continue." } }],
+        choices: [
+          {
+            message: {
+              role: "assistant",
+              content: "User interrupted this AI completion. Please continue.",
+            },
+          },
+        ],
         model,
         usage: undefined,
         usd_cost: 0,
       };
-      const response = await this.makeInterruptible(
-        this.getClient().createChatCompletion({
+
+      const response = await this.createAgentCompletion(
+        {
           model,
           messages,
           tools: this.getEnabledTools(),
           tool_choice: "auto",
           long_ttl_cache: this.runTime() > 300_000,
-        }),
-        interruptResponse
+          ...(this.reasoningEffort !== undefined && { reasoning_effort: this.reasoningEffort }),
+          ...(this.summarizeReasoning !== undefined && { reasoning_summary: this.summarizeReasoning }),
+        },
+        { interruptValue: interruptResponse }
       );
 
       // If the agent was paused while the completion was in-flight, wait here
@@ -829,8 +912,6 @@ export abstract class BaseAgent implements IAgent {
         }
       }
 
-      this.adjustTotalCostUsd(response?.usd_cost);
-      this.adjustTokenUsage(response?.usage);
       this.log("agent response cost: " + response?.usd_cost);
 
       // Typically, there's only one choice in the array, but you could have many
@@ -847,7 +928,6 @@ export abstract class BaseAgent implements IAgent {
 
         this.logMessages([lastMessage]);
 
-        const toolCalls = lastMessage.tool_calls;
         if (lastMessage.tool_calls) {
           // About to call a tool, process the messages
           // We could add all the tool calls, and do this once
@@ -856,6 +936,11 @@ export abstract class BaseAgent implements IAgent {
             "pre_tools"
           );
 
+          // Re-derive toolCalls from the freshly processed messages, since
+          // pre_tools processors (e.g. MinimalToolsMessageProcessor) may have
+          // rewritten the tool_calls on a deep-copied message array.
+          const toolCalls = messages[messages.length - 1].tool_calls;
+
           this.updateCurrentThread(messages);
 
           const truncationWarning = this.detectTruncatedToolCalls(
@@ -942,7 +1027,9 @@ export abstract class BaseAgent implements IAgent {
         firstMessage.content &&
         this.isTerminationResponse(firstMessage.content)
       ) {
-        this.log(`Termination word detected: "${firstMessage.content.trim()}", treating as finalAnswer`);
+        this.log(
+          `Termination word detected: "${firstMessage.content.trim()}", treating as finalAnswer`
+        );
         this.status = this.eventTypes.done;
         this.agentEvents.emit(this.eventTypes.done, firstMessage.content);
         return firstMessage.content;
@@ -1001,7 +1088,9 @@ export abstract class BaseAgent implements IAgent {
         this.logStatus();
 
         const continuation = `<Workflow>
-        Task terminates after you call on of these tools: ${JSON.stringify(this.requiredToolNames)}.\n
+        Task terminates after you call on of these tools: ${JSON.stringify(
+          this.requiredToolNames
+        )}.\n
         User likely only sees output from the required tool call.
         <TaskStatus>${statusMessage}</TaskStatus>
         </Workflow>`;
@@ -1048,7 +1137,12 @@ export abstract class BaseAgent implements IAgent {
 
       this.log(`Agent failed: ${e}`, "error");
 
-      if (e != null && typeof e === "object" && "response" in e && "data" in (e as any).response) {
+      if (
+        e != null &&
+        typeof e === "object" &&
+        "response" in e &&
+        "data" in (e as any).response
+      ) {
         this.log(
           `Error response data: ${JSON.stringify(e.response.data, null, 2)}`,
           "error"
@@ -1165,7 +1259,13 @@ export abstract class BaseAgent implements IAgent {
     toolCalls: ToolCall[],
     response: CompletionResponse
   ): { role: string; content: string } | null {
-    const outputTokens: number = response?.usage?.completion_tokens || 0;
+    // Subtract thinking/reasoning tokens — they're billed as output tokens but
+    // don't produce visible argument content, so including them inflates the heuristic.
+    const rawOutputTokens: number = response?.usage?.completion_tokens || 0;
+    const thinkingTokens: number =
+      (response?.usage?.output_tokens_details?.thinking_tokens ?? 0) +
+      (response?.usage?.output_tokens_details?.reasoning_tokens ?? 0);
+    const outputTokens = Math.max(0, rawOutputTokens - thinkingTokens);
     const totalArgLength = toolCalls.reduce(
       (sum, tc) => sum + (tc.function?.arguments?.length || 0),
       0
@@ -1223,20 +1323,20 @@ export abstract class BaseAgent implements IAgent {
 
     const model = this.getModel();
 
-    const response = await this.getClient().createChatCompletion({
+    const taskBreakdownMessages = [
+      ...messages,
+      {
+        role: "user",
+        content: taskPrompt,
+      },
+    ] as Message[];
+
+    const response = await this.createAgentCompletion({
       model,
-      messages: [
-        ...messages,
-        {
-          role: "user",
-          content: taskPrompt,
-        },
-      ],
+      messages: taskBreakdownMessages,
       max_tokens: 2000,
     });
 
-    this.adjustTotalCostUsd(response.usd_cost);
-
     this.taskBreakdown = response.choices[0].message.content;
     this.log(`task breakdown cost: ${response.usd_cost}`);
     return this.taskBreakdown;
@@ -1268,19 +1368,19 @@ export abstract class BaseAgent implements IAgent {
 
     const model = this.getModel();
 
-    const response = await this.getClient().createChatCompletion({
+    const compressMessagesPayload = [
+      ...messages,
+      {
+        role: "user",
+        content: toCompressPrompt,
+      },
+    ] as Message[];
+
+    const response = await this.createAgentCompletion({
       model,
-      messages: [
-        ...messages,
-        {
-          role: "user",
-          content: toCompressPrompt,
-        },
-      ],
+      messages: compressMessagesPayload,
     });
 
-    this.adjustTotalCostUsd(response.usd_cost);
-
     const summaries = response.choices.map((c) => c.message.content);
     this.summaries.push(...summaries);
 

package/src/agents/tools/execCommand.ts

@@ -259,7 +259,7 @@ const execWithTimeout = async (
 // Public tool
 export async function execCommand(
   command: string,
-  timeout?: number,
+  timeout?: number | string,
   continueInBackground?: boolean,
   logFileName?: string
 ): Promise<string> {
@@ -272,17 +272,37 @@ export async function execCommand(
     this instanceof ToolsService ? this : services().Tools
   ) as ToolsService;
 
+  // Coerce timeout to a number. Agents (and some tool-call serializers) often
+  // pass numeric arguments as strings (e.g. "120000"). Node's exec()/setTimeout
+  // reject non-integer values with "The value of \"timeout\" is out of range.
+  // It must be an unsigned integer", so normalize here before any use.
+  let normalizedTimeout: number | undefined;
+  const rawTimeout = typeof timeout === "string" ? Number(timeout.trim()) : timeout;
+  if (typeof rawTimeout !== "number" || !Number.isFinite(rawTimeout)) {
+    normalizedTimeout = undefined;
+  } else if (rawTimeout === -1) {
+    // -1 is the sentinel for "wait indefinitely" — leave as-is.
+    normalizedTimeout = -1;
+  } else {
+    // Clamp to a non-negative integer so the underlying APIs never throw.
+    normalizedTimeout = Math.max(0, Math.floor(rawTimeout));
+  }
+
   // Detect suspiciously small timeout values — agents often pass seconds instead of ms.
   // Any value < 100 is almost certainly a mistake (100ms is still very fast for a shell cmd).
   // We auto-correct to seconds and include a warning in the output so the agent learns.
-  let correctedTimeout = timeout;
+  let correctedTimeout = normalizedTimeout;
   let timeoutWarning = "";
-  if (timeout !== undefined && timeout !== -1 && timeout < 100) {
-    correctedTimeout = timeout * 1000;
+  if (
+    normalizedTimeout !== undefined &&
+    normalizedTimeout !== -1 &&
+    normalizedTimeout < 100
+  ) {
+    correctedTimeout = normalizedTimeout * 1000;
     timeoutWarning =
-      `⚠️  Warning: timeout was ${timeout}ms which is extremely small and likely a mistake. ` +
+      `⚠️  Warning: timeout was ${normalizedTimeout}ms which is extremely small and likely a mistake. ` +
       `The timeout unit is milliseconds, not seconds. ` +
-      `Auto-corrected to ${correctedTimeout}ms (${timeout}s).\n\n`;
+      `Auto-corrected to ${correctedTimeout}ms (${normalizedTimeout}s).\n\n`;
   }
 
   const context = toolService.getContext();

package/src/agents/tools/index.ts

@@ -23,3 +23,4 @@ export * from "./stringReplace";
 export * from "./startAgentTask";
 export * from "./ycmd";
 export * from "./mcp";
+export * from "./skills";

package/src/agents/tools/list.ts

@@ -7,6 +7,7 @@ import * as language from "./language/definitions";
 import * as mcp from "./mcp/definitions";
 import { googleSearchDefinition } from "./googleSearch";
 import { startAgentTaskDefinition } from "./startAgentTask";
+import { skillsToolDefinitions } from "./skills";
 
 function getPluginNames(): string {
   try {
@@ -681,4 +682,5 @@ export const includedTools = [
   ...ycmd.definitions,
   ...language.definitions,
   ...mcp.definitions,
+  ...skillsToolDefinitions,
 ] as Tool[];

package/src/agents/tools/minimal/callTool.ts

@@ -0,0 +1,45 @@
+import { minimatch } from "minimatch";
+import { MinimalToolsService } from "../../../services/MinimalToolsService";
+import { ToolsService } from "../../../services/Tools";
+
+/**
+ * Calls any tool by name with the given args.
+ * This is the escape hatch that lets agents call tools outside the base tool set
+ * without changing the `tools:` array sent to the AI (preserving cache stability).
+ */
+export async function callTool(
+  this: ToolsService,
+  args: { name: string; args: Record<string, any> }
+): Promise<any> {
+  const service = this as unknown as MinimalToolsService;
+  const { name, args: toolArgs } = args;
+
+  const allTools = service.getAllTools ? service.getAllTools() : service.getTools();
+
+  // Fuzzy match: exact, endsWith, or glob
+  const matchedTool =
+    allTools.find((t) => t.function.name === name) ||
+    allTools.find((t) => t.function.name.endsWith(name)) ||
+    allTools.find((t) => minimatch(t.function.name, name, { nocase: true }));
+
+  if (!matchedTool) {
+    const available = allTools.map((t) => t.function.name).join(", ");
+    return `Error: Tool "${name}" not found. Use inspectTools() to browse available tools. Available: ${available}`;
+  }
+
+  const toolName = matchedTool.function.name;
+
+  // Build a synthetic ToolCall object and delegate to the base callTool
+  const syntheticToolCall = {
+    id: `call_minimal_${Date.now()}_${Math.random().toString(36).substr(2, 6)}`,
+    type: "function" as const,
+    function: {
+      name: toolName,
+      arguments: JSON.stringify(toolArgs),
+    },
+  };
+
+  // Use base ToolsService.callTool with the matched tool name allowed
+  const result = await service.callToolByName(syntheticToolCall, toolName);
+  return result;
+}

package/src/agents/tools/minimal/definitions.ts

@@ -0,0 +1,50 @@
+import { Tool } from "../../../clients/types";
+
+export const callToolDefinition: Tool = {
+  type: "function",
+  function: {
+    name: "callTool",
+    description:
+      "Call any available tool by name with the given arguments. Use listStoredToolResponses + inspectTools to discover available tools and their argument schemas before calling. This is the primary way to call tools that are not in the base tool set.",
+    parameters: {
+      type: "object",
+      positional: false,
+      properties: {
+        name: {
+          type: "string",
+          description: "The name of the tool to call.",
+        },
+        args: {
+          type: "object",
+          description:
+            "The arguments to pass to the tool. Should match the tool's parameter schema.",
+        },
+      },
+      required: ["name", "args"],
+    },
+  },
+};
+
+export const inspectToolsDefinition: Tool = {
+  type: "function",
+  function: {
+    name: "inspectTools",
+    description:
+      "Get the full schema/definition for tools matching the given glob patterns. Use this to discover what arguments a tool needs before calling it via callTool. Example patterns: ['read*'] finds tools starting with 'read', ['*File'] finds tools ending with 'File'.",
+    parameters: {
+      type: "object",
+      positional: true,
+      properties: {
+        patterns: {
+          type: "array",
+          items: { type: "string" },
+          description:
+            "Array of glob patterns to filter tool names. If omitted, returns all available tools.",
+        },
+      },
+      required: [],
+    },
+  },
+};
+
+export const minimalDefinitions = [callToolDefinition, inspectToolsDefinition];

package/src/agents/tools/minimal/index.ts

@@ -0,0 +1,3 @@
+export * from "./callTool";
+export * from "./inspectTools";
+export * from "./definitions";

package/src/agents/tools/minimal/inspectTools.ts

@@ -0,0 +1,27 @@
+import { minimatch } from "minimatch";
+import { MinimalToolsService } from "../../../services/MinimalToolsService";
+import { ToolsService } from "../../../services/Tools";
+
+/**
+ * Returns the full tool definitions (schema) for all tools matching the given patterns.
+ * Used by agents to discover argument shapes before calling via callTool.
+ */
+export function inspectTools(
+  this: ToolsService,
+  patterns?: string[]
+): object[] {
+  const service = this as unknown as MinimalToolsService;
+  const allTools = service.getAllTools ? service.getAllTools() : service.getTools();
+
+  if (!patterns || patterns.length === 0) {
+    return allTools.map((t) => t.function);
+  }
+
+  return allTools
+    .filter((t) =>
+      patterns.some((pattern) =>
+        minimatch(t.function.name, pattern, { nocase: true })
+      )
+    )
+    .map((t) => t.function);
+}