@tyvm/knowhow 0.0.129 → 0.0.131

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyvm/knowhow",
-  "version": "0.0.129",
+  "version": "0.0.131",
   "description": "ai cli with plugins and agents",
   "main": "ts_build/src/index.js",
   "bin": {
@@ -35,7 +35,6 @@
   "license": "MIT",
   "devDependencies": {
     "@babel/preset-typescript": "^7.23.3",
-    "typescript": "^5.0.0",
     "@types/diff": "^5.2.1",
     "@types/express": "^4.17.13",
     "@types/jest": "^29.5.13",
@@ -47,10 +46,11 @@
     "ts-jest": "^29.1.1",
     "ts-node": "^10.7.0",
     "tslint": "^6.1.3",
-    "tslint-config-prettier": "^1.18.0"
+    "tslint-config-prettier": "^1.18.0",
+    "typescript": "^5.0.0"
   },
   "dependencies": {
-    "@anthropic-ai/sdk": "^0.39.0",
+    "@anthropic-ai/sdk": "^0.111.0",
     "@google/genai": "^0.14.1",
     "@inquirer/editor": "^4.2.18",
     "@modelcontextprotocol/sdk": "^1.13.3",

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) {
@@ -715,10 +742,10 @@ 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
@@ -751,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");
     }
@@ -848,6 +875,8 @@ export abstract class BaseAgent implements IAgent {
           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 }),
         },
         { interruptValue: interruptResponse }
       );
@@ -1230,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

package/src/agents/configurable/ConfigAgent.ts

@@ -1,7 +1,6 @@
 import { AgentContext, BaseAgent } from "../base/base";
 import { Message } from "../../clients/types";
 import { Assistant, Config } from "../../types";
-import { EventService, ToolsService } from "../../services";
 import { MessageProcessor } from "../../services/MessageProcessor";
 
 export class ConfigAgent extends BaseAgent {

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/skills.ts

@@ -0,0 +1,79 @@
+import { ToolsService } from "../../services/Tools";
+import { services } from "../../services";
+
+/**
+ * List all skills currently loaded in memory.
+ * Returns a formatted string of name: description lines.
+ */
+export async function listSkills(this: ToolsService): Promise<string> {
+  const toolService =
+    this instanceof ToolsService ? (this as ToolsService) : services().Tools;
+
+  const { Behaviors } = toolService.getContext();
+
+  const skills = Behaviors.listSkills();
+  if (skills.length === 0) {
+    return "No skills available. Run `knowhow behaviors download --skills-only` to fetch skills.";
+  }
+  return skills.map((s) => `- ${s.name}: ${s.description}`).join("\n");
+}
+
+/**
+ * Load full instructions for a named skill from memory.
+ */
+export async function loadSkill(
+  this: ToolsService,
+  name: string
+): Promise<string> {
+  const toolService =
+    this instanceof ToolsService ? (this as ToolsService) : services().Tools;
+
+  const { Behaviors } = toolService.getContext();
+
+  const skill = Behaviors.findSkill(name);
+  if (!skill) {
+    const names = Behaviors.listSkills()
+      .map((s) => s.name)
+      .join(", ");
+    return `Skill "${name}" not found. Available skills: ${names || "none"}`;
+  }
+  return `## Skill: ${skill.name}\n\n${skill.instructions}`;
+}
+
+/** Tool definitions for listSkills + loadSkill */
+export const skillsToolDefinitions = [
+  {
+    type: "function" as const,
+    function: {
+      name: "listSkills",
+      description:
+        "List all available skills by name and description. Call this to discover what skills are available before loading one.",
+      parameters: {
+        type: "object" as const,
+        positional: true,
+        properties: {} as Record<string, never>,
+        required: [] as string[],
+      },
+    },
+  },
+  {
+    type: "function" as const,
+    function: {
+      name: "loadSkill",
+      description:
+        "Load the full instructions for a named skill. Use this when you need to follow a specific skill's guidance.",
+      parameters: {
+        type: "object" as const,
+        positional: true,
+        properties: {
+          name: {
+            type: "string",
+            description:
+              "The skill name to load (must match exactly or approximately)",
+          },
+        },
+        required: ["name"] as string[],
+      },
+    },
+  },
+];

package/src/agents/tools/startAgentTask.ts

@@ -3,7 +3,7 @@ import * as fs from "fs";
 import * as path from "path";
 import { spawn } from "child_process";
 
-interface StartAgentTaskParams {
+export interface StartAgentTaskParams {
   messageId?: string;
   syncFs?: boolean;
   taskId?: string;
@@ -14,6 +14,8 @@ interface StartAgentTaskParams {
   agentName?: string;
   maxTimeLimit?: number;
   maxSpendLimit?: number;
+  /** When true, wait for the agent subprocess to exit before resolving (for generate pipelines). */
+  waitForCompletion?: boolean;
 }
 
 const PROCESSES_DIR = path.join(process.cwd(), ".knowhow", "processes");
@@ -63,6 +65,7 @@ export async function startAgentTask(params: StartAgentTaskParams): Promise<stri
     agentName,
     maxTimeLimit,
     maxSpendLimit,
+    waitForCompletion,
   } = params;
   if (!prompt) {
     throw new Error("prompt is required to create a chat task");
@@ -156,24 +159,25 @@ export async function startAgentTask(params: StartAgentTaskParams): Promise<stri
         `To check status, read: ${agentTaskDir}/status.txt\n`
       : "";
 
-    // Give the agent 5 seconds to finish before detaching
-    const detachTime = 5 * 1000;
-    const tid = setTimeout(() => {
-      try { child.unref(); } catch {}
-      done(
-        `Agent started (pid=${pid}), running in background.\n` +
-        `Logs: ${logPath}\n` +
-        syncFsNote
-      );
-    }, detachTime);
-
     child.once("exit", (code) => {
-      clearTimeout(tid);
       done(
         `Agent finished with exit code ${code}.\nLogs: ${logPath}\n` +
         syncFsNote
       );
     });
+
+    if (!waitForCompletion) {
+      // Give the agent 5 seconds to finish before detaching (fire-and-forget mode)
+      const detachTime = 5 * 1000;
+      setTimeout(() => {
+        try { child.unref(); } catch {}
+        done(
+          `Agent started (pid=${pid}), running in background.\n` +
+          `Logs: ${logPath}\n` +
+          syncFsNote
+        );
+      }, detachTime);
+    }
   });
 }
 

package/src/ai.ts

@@ -1,6 +1,13 @@
 import * as fs from "fs";
 import { readFile } from "./utils";
 
+/** Options forwarded to startAgentTask when a generation source has an `agent` field */
+export type AgentOptions = {
+  syncFs?: boolean;
+  taskId?: string;
+  maxTimeLimit?: number;
+  maxSpendLimit?: number;
+};
 import OpenAI from "openai";
 import { Assistant } from "./types";
 import { convertToText } from "./conversion";
@@ -46,17 +53,24 @@ export function readPromptFile(promptFile: string, input: string) {
   return input;
 }
 
-export async function singlePrompt(userPrompt: string, model = "", agent = "") {
-  const { Agents } = services();
+export async function singlePrompt(
+  userPrompt: string,
+  model = "",
+  agent = "",
+  agentOptions?: AgentOptions
+) {
   if (agent) {
-    const agentConfig = await Agents.getAgent(agent);
-    if (!agentConfig) {
-      throw new Error(`Agent ${agent} not found`);
-    }
-    if (model) {
-      agentConfig.setModel(model);
-    }
-    return agentConfig.call(userPrompt);
+    // Route through the full AgentModule pipeline (renderer, sync-fs, limits).
+    // This ensures generate agent runs produce readable output and are observable
+    // via `knowhow agents list/tail/status`, matching `knowhow agent --input` behaviour.
+    const { startAgentTask } = await import("./agents/tools/startAgentTask");
+    return startAgentTask({
+      agentName: agent,
+      prompt: userPrompt,
+      model: model || undefined,
+      waitForCompletion: true,
+      ...(agentOptions ?? {}),
+    });
   }
 
   if (!model) {
@@ -100,6 +114,11 @@ function isContextLengthError(err: any): boolean {
  * Recursively summarize an array of texts using a split-and-summarize approach.
  * When the combined texts exceed the context window (either by estimate or actual API error),
  * split the array in half, summarize each half recursively, then combine.
+ *
+ * NOTE: when an `agent` is provided the recursive split path is skipped — agents
+ * can handle large inputs themselves (they can read files). Splitting would create
+ * multiple isolated agent runs each writing partial output. Instead the combined
+ * content is passed directly to the agent.
  */
 async function summarizeTextsRecursive(
   texts: string[],
@@ -107,7 +126,8 @@ async function summarizeTextsRecursive(
   model: string,
   agent: string,
   contextLimit: number,
-  depth = 0
+  depth = 0,
+  agentOptions?: AgentOptions
 ): Promise<string> {
   const indent = "  ".repeat(depth);
 
@@ -115,7 +135,7 @@ async function summarizeTextsRecursive(
   if (texts.length === 1) {
     const content = template.replaceAll("{text}", texts[0]);
     console.log(`${indent}summarizeTexts[depth=${depth}]: single text, ~${estimateTokens(content)} tokens`);
-    return singlePrompt(content, model, agent);
+    return singlePrompt(content, model, agent, agentOptions);
   }
 
   // Check if combined fits in context window by estimate
@@ -127,7 +147,7 @@ async function summarizeTextsRecursive(
     // Try single combined prompt — if context error, fall through to split
     console.log(`${indent}summarizeTexts[depth=${depth}]: ${texts.length} texts, ~${estimatedTokens} tokens, trying combined`);
     try {
-      return await singlePrompt(combinedContent, model, agent);
+      return await singlePrompt(combinedContent, model, agent, agentOptions);
     } catch (err: any) {
       if (!isContextLengthError(err)) throw err;
       console.log(`${indent}summarizeTexts[depth=${depth}]: API rejected (context too long), splitting in half`);
@@ -136,14 +156,22 @@ async function summarizeTextsRecursive(
     console.log(`${indent}summarizeTexts[depth=${depth}]: ${texts.length} texts, ~${estimatedTokens} tokens exceeds limit, splitting in half`);
   }
 
+  // When an agent is assigned, don't split — agents can handle large inputs and
+  // splitting would create multiple isolated agent runs that each write partial output.
+  // Instead, pass the combined content as-is even if it may exceed context limit.
+  if (agent) {
+    console.log(`${indent}summarizeTexts[depth=${depth}]: agent mode — skipping split, passing combined content to agent`);
+    return singlePrompt(combinedContent, model, agent, agentOptions);
+  }
+
   // Split texts in half and recurse
   const mid = Math.ceil(texts.length / 2);
   const left = texts.slice(0, mid);
   const right = texts.slice(mid);
 
   const [leftSummary, rightSummary] = await Promise.all([
-    summarizeTextsRecursive(left, template, model, agent, contextLimit, depth + 1),
-    summarizeTextsRecursive(right, template, model, agent, contextLimit, depth + 1),
+    summarizeTextsRecursive(left, template, model, agent, contextLimit, depth + 1, agentOptions),
+    summarizeTextsRecursive(right, template, model, agent, contextLimit, depth + 1, agentOptions),
   ]);
 
   // Combine the two halves with a final summary prompt
@@ -153,27 +181,28 @@ async function summarizeTextsRecursive(
   console.log(`${indent}summarizeTexts[depth=${depth}]: combining halves, ~${finalEstimate} tokens`);
 
   if (finalEstimate < contextLimit) {
-    return singlePrompt(finalContent, model, agent);
+    return singlePrompt(finalContent, model, agent, agentOptions);
   }
 
   // If even the combined summaries are too long, recurse one more level
-  return summarizeTextsRecursive([leftSummary, rightSummary], template, model, agent, contextLimit, depth + 1);
+  return summarizeTextsRecursive([leftSummary, rightSummary], template, model, agent, contextLimit, depth + 1, agentOptions);
 }
 
 export async function summarizeTexts(
   texts: string[],
   template: string,
   model = "",
-  agent = ""
+  agent = "",
+  agentOptions?: AgentOptions
 ) {
   const effectiveModel = model || Models.openai.GPT_54_Nano;
   const contextLimit = getModelContextLimit(effectiveModel);
 
   console.log(
-    `summarizeTexts: ${texts.length} text(s), context limit: ${contextLimit}, model: ${effectiveModel}`
+    `summarizeTexts: ${texts.length} text(s), context limit: ${contextLimit}, model: ${effectiveModel}${agent ? `, agent: ${agent}` : ""}`
   );
 
-  return summarizeTextsRecursive(texts, template, model, agent, contextLimit).catch((err) => {
+  return summarizeTextsRecursive(texts, template, model, agent, contextLimit, 0, agentOptions).catch((err) => {
     return `Texts of combined length ${texts.reduce((a, t) => a + t.length, 0)} could not be summarized due to error: ${err.message}`;
   });
 }
@@ -193,23 +222,25 @@ export async function summarizeFiles(
   files: string[],
   template: string,
   model = "",
-  agent = ""
+  agent = "",
+  agentOptions?: AgentOptions
 ) {
   const texts = [];
   for (const file of files) {
     const text = `file: ${file}\n` + (await convertToText(file));
     texts.push(text);
   }
-  return summarizeTexts(texts, template, model, agent);
+  return summarizeTexts(texts, template, model, agent, agentOptions);
 }
 
 export async function summarizeFile(
   file: string,
   template: string,
   model = "",
-  agent = ""
+  agent = "",
+  agentOptions?: AgentOptions
 ) {
-  return await summarizeFiles([file], template, model, agent);
+  return await summarizeFiles([file], template, model, agent, agentOptions);
 }
 
 /*

package/src/chat/CliChatService.ts

@@ -336,12 +336,18 @@ export class CliChatService implements ChatService {
     return fullPrompt;
   }
 
-  async startChatLoop(): Promise<void> {
+  async startChatLoop(initialCommand?: string): Promise<void> {
     // Display available commands like the original
     const availableCommands = this.getCommandsForActiveModes();
     const commandNames = availableCommands.map((cmd) => `/${cmd.name}`);
     console.log("Commands:", commandNames.join(", "));
 
+    // If an initial command was provided (e.g. from CLI), process it before
+    // entering the interactive loop so the user lands in the right state.
+    if (initialCommand) {
+      await this.processInput(initialCommand.trim());
+    }
+
     while (true) {
       // Recompute available commands each iteration so mode changes are reflected in autocomplete
       const currentCommandNames = this.getCommandsForActiveModes().map(