@tyvm/knowhow 0.0.146 → 0.0.148

package/autodoc/cli-reference.md

@@ -86,7 +86,7 @@ knowhow chat
 ---
 
 ### `knowhow agent`
-**Purpose:** Run a one-shot agent task directly from the CLI (default agent: `Patcher`). Can also resume a previously started task.
+**Purpose:** Start a new one-shot agent task directly from the CLI (default agent: `Patcher`).
 
 **Usage:**
 ```bash
@@ -114,8 +114,6 @@ knowhow agent [options]
   Custom prompt template file with a `{text}` placeholder
 - `--input <text>`  
   Task input (fallback to stdin if not provided)
-- `--resume`  
-  Resume a previously started task using `--task-id` (local FS or remote)
 - `--renderer <name>`  
   Renderer to use: `basic`, `compact`, `fancy`, or a path/package  
   (default: from config or `basic`)
@@ -136,14 +134,45 @@ Use a custom prompt template file:
 knowhow agent --prompt-file .knowhow/prompts/BasicCodeDocumenter.mdx --input "src/index.ts"
 ```
 
-Resume a task:
+Choose provider + renderer:
 ```bash
-knowhow agent --resume --task-id 123 --message-id 456 --input "Continue where you left off"
+knowhow agent --provider openai --model gpt-4.1-mini --renderer fancy --input "Fix the failing tests"
 ```
 
-Choose provider + renderer:
+---
+
+### `knowhow agents resume` / `knowhow agents fork`
+**Purpose:** Continue an existing agent task, or branch its history into a new task without modifying the source.
+
+**Usage:**
 ```bash
-knowhow agent --provider openai --model gpt-4.1-mini --renderer fancy --input "Fix the failing tests"
+knowhow agents resume [taskId] [options]
+knowhow agents fork [sourceTaskId] [options]
+```
+
+Both commands accept a full or partial task ID. Use `-i <number>` instead to select the corresponding row from `knowhow agents list`.
+
+#### Options
+- `-i, --index <number>` — Select a task by row number from `knowhow agents list`
+- `--rollback <count>` — Discard the newest N agent interactions before continuing (default: `0`)
+- `--input <text>` — Message to send after restoring history
+- `--message-id <messageId>` — Knowhow message ID for remote task lookup
+- `--sync-fs` — Enable filesystem-based synchronization
+- `--provider <provider>` — Override the saved AI provider
+- `--model <model>` — Override the saved model
+- `--agent-name <name>` — Override the saved agent
+- `--reasoning-effort <effort>` — Override the saved reasoning effort
+- `--renderer <name>` — Renderer to use (default: from config or `basic`)
+- `--task-id <taskId>` — Explicit destination task ID (`fork` only)
+
+Resume the first listed task after removing its newest assistant interaction:
+```bash
+knowhow agents resume -i 1 --rollback 1
+```
+
+Fork the third listed task into an explicit destination task ID:
+```bash
+knowhow agents fork -i 3 --rollback 1 --task-id my-new-task
 ```
 
 ---

package/bin/knowhow.js

@@ -1,12 +1,14 @@
-#!/usr/bin/env node --no-node-snapshot
+#!/usr/bin/env node
 
 // knowhow CLI entry point.
 //
-// --no-node-snapshot is required for isolated-vm (used by executeScript).
-// It is declared in the shebang above so that Node starts with it directly —
-// no re-exec needed. This means the process stays as a direct child of the
-// terminal (e.g. Ghostty) and inherits its macOS TCC (Screen Recording /
-// Accessibility) permissions without needing to grant them to node itself.
+// --no-node-snapshot is NOT needed here. The script module (knowhow-module-script)
+// forks a child process with --no-node-snapshot only when executeScript is actually
+// called. This means:
+//   - The shebang works on Linux (GNU env) and macOS without any argument-splitting tricks.
+//   - Ghostty (or whichever terminal launched knowhow) remains the TCC subject for
+//     macOS Screen Recording / Accessibility permissions — computer-use features work
+//     without having to grant those permissions to the node binary itself.
 
 const path = require("node:path");
 const cliJs = path.join(__dirname, "../ts_build/src/cli.js");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tyvm/knowhow",
-  "version": "0.0.146",
+  "version": "0.0.148",
   "description": "ai cli with plugins and agents",
   "main": "ts_build/src/index.js",
   "bin": {

package/src/agents/base/base.ts

@@ -22,6 +22,7 @@ import { Models } from "../../ai";
 import { MessageProcessor } from "../../services/MessageProcessor";
 import { DEFAULT_CONTEXT_LIMIT } from "../../clients/contextLimits";
 import { Marked } from "../../utils";
+import { TraceAll } from "../../util/Trace";
 
 export { Message, Tool, ToolCall };
 export interface ModelPreference {
@@ -83,6 +84,7 @@ interface ActiveObservation {
   expiry?: NodeJS.Timeout;
 }
 
+@TraceAll()
 export abstract class BaseAgent implements IAgent {
   abstract name: string;
   abstract description: string;
@@ -471,6 +473,28 @@ export abstract class BaseAgent implements IAgent {
     return this.getEnabledTools().map((t) => t.function.name);
   }
 
+  /** Restore the exact request-visible tool list persisted for a prior run. */
+  restoreEnabledTools(names: string[]) {
+    const uniqueNames = [...new Set(names)];
+    const lazyTools = this.tools as ToolsService & {
+      enableTools?: (patterns: string[]) => unknown;
+      restoreEnabledTools?: (names: string[]) => void;
+    };
+
+    // LazyToolsService only exposes explicitly enabled tools. Materialize the
+    // saved concrete names before applying the agent-level exact-set filter.
+    if (lazyTools.restoreEnabledTools) {
+      lazyTools.restoreEnabledTools(uniqueNames);
+    } else {
+      lazyTools.enableTools?.(uniqueNames);
+    }
+    const savedNames = new Set(uniqueNames);
+    this.disabledTools = this.tools
+      .getTools()
+      .map((tool) => tool.function.name)
+      .filter((name) => !savedNames.has(name));
+  }
+
   disableTool(toolName: string) {
     this.disabledTools.push(toolName);
   }
@@ -1011,9 +1035,6 @@ export abstract class BaseAgent implements IAgent {
       this.updateCurrentThread(messages);
       const isMissingTool = this.isRequiredToolMissing();
 
-      const startIndex = 0;
-      const endIndex = messages.length;
-
       // Process messages before each AI call
       messages = await this.messageProcessor.processMessages(
         messages,
@@ -1259,14 +1280,14 @@ export abstract class BaseAgent implements IAgent {
             : `Compressing messages: ${contextTokens} tokens exceeds ${this.getCompressThreshold()}`
         );
         this._forceCompact = false;
-        messages = await this.compressMessages(messages, startIndex, endIndex);
+        messages = await this.compressMessages(messages);
         this.startNewThread(messages);
         // Reset the real-token tracker. compressMessages() ran a completion over
-        // the FULL (pre-compression) thread, so lastPromptTokens now reflects
-        // that large context — not the small compressed thread. Zeroing it makes
-        // getContextTokenCount() fall back to the whitespace estimate of the new
-        // (small) thread until the next real completion reports fresh usage,
-        // preventing an immediate false re-compaction on the following iteration.
+        // the older history, so lastPromptTokens reflects the compression input
+        // rather than the newly reconstructed thread. Zeroing it makes
+        // getContextTokenCount() estimate the new thread until the next regular
+        // completion reports fresh usage, preventing an immediate false
+        // re-compaction on the following iteration.
         this.lastPromptTokens = 0;
       }
 
@@ -1665,15 +1686,24 @@ export abstract class BaseAgent implements IAgent {
     return this.taskBreakdown;
   }
 
-  async compressMessages(
-    messages: Message[],
-    startIndex: number,
-    endIndex: number
-  ) {
+  async compressMessages(messages: Message[]) {
+    // Preserve the latest agent interaction exactly. Starting the resumed thread
+    // at the final assistant message keeps its tool calls, every tool response,
+    // and any subsequent user messages together as one protocol-valid unit.
+    let resumeIndex = messages.length - 1;
+    while (
+      resumeIndex >= 0 &&
+      messages[resumeIndex].role !== "assistant"
+    ) {
+      resumeIndex--;
+    }
+    const compressionEnd = resumeIndex === -1 ? messages.length : resumeIndex;
+    const toCompress = messages.slice(0, compressionEnd);
+    const resumeMessages = messages.slice(compressionEnd);
+
     this.log(
-      `Compressing messages from ${startIndex} to ${endIndex}, total messages: ${messages.length}`
+      `Compressing messages from 0 to ${compressionEnd}, resuming from ${resumeIndex}, total messages: ${messages.length}`
     );
-    const toCompress = messages.slice(startIndex, endIndex);
     const toCompressPrompt = `We are compressing our conversation to save memory.
     Please summarize the conversation so far, so that we may continue the original task with a smaller context
 
@@ -1685,14 +1715,12 @@ export abstract class BaseAgent implements IAgent {
 
     Our initial task breakdown: ${this.taskBreakdown}
 
-    This summary will become the agent's only memory of the past, all other messages will be dropped:
+    This summary will replace the older history. The latest agent interaction will remain verbatim:
 
       `;
 
-    const model = this.getModel();
-
     const compressMessagesPayload = [
-      ...messages,
+      ...toCompress,
       {
         role: "user",
         content: toCompressPrompt,
@@ -1720,12 +1748,12 @@ export abstract class BaseAgent implements IAgent {
         `,
       },
     ] as Message[];
-    const systemMesasges = toCompress.filter((m) => m.role === "system");
+    const systemMessages = toCompress.filter((m) => m.role === "system");
 
     const newMessages = [
-      ...systemMesasges,
+      ...systemMessages,
       ...startMessages,
-      ...messages.slice(endIndex),
+      ...resumeMessages,
     ];
 
     const oldLength = this.getMessagesLength(messages);

package/src/agents/historyRollback.ts

@@ -0,0 +1,36 @@
+import { Message } from "../clients/types";
+
+/**
+ * Remove the newest agent interactions from the final persisted thread.
+ *
+ * An interaction starts with an assistant message and includes every following
+ * tool result up to (but not including) the next assistant message. Cutting at
+ * the assistant boundary keeps tool_call/tool-result pairs valid and makes
+ * `rollback: 1` useful for recovering from a failed final tool-use turn.
+ */
+export function rollbackAgentInteractions(
+  threads: Message[][],
+  rollback: number = 0
+): Message[][] {
+  if (!Number.isInteger(rollback) || rollback < 0) {
+    throw new Error("rollback must be a non-negative integer");
+  }
+
+  const cloned = threads.map((thread) => thread.map((message) => ({ ...message })));
+  if (rollback === 0 || cloned.length === 0) return cloned;
+
+  const lastThread = cloned[cloned.length - 1];
+  const assistantIndexes = lastThread
+    .map((message, index) => (message.role === "assistant" ? index : -1))
+    .filter((index) => index >= 0);
+
+  if (rollback > assistantIndexes.length) {
+    throw new Error(
+      `Cannot rollback ${rollback} interaction(s); the latest thread only has ${assistantIndexes.length} assistant interaction(s).`
+    );
+  }
+
+  const cutIndex = assistantIndexes[assistantIndexes.length - rollback];
+  cloned[cloned.length - 1] = lastThread.slice(0, cutIndex);
+  return cloned;
+}