@tyvm/knowhow 0.0.118 → 0.0.120

package/src/processors/CustomVariables.ts

@@ -220,21 +220,26 @@ export class CustomVariables {
 
   /**
    * Creates a message processor function that substitutes variables in messages
+   *
+   * CACHING NOTE: To preserve Anthropic prefix-cache stability, we only apply
+   * variable substitution to the *last* (most-recently-added) message in the
+   * modifiedMessages array.  Historical messages have already been processed on
+   * prior turns; mutating them would change their content mid-conversation and
+   * instantly bust the entire downstream cache window.
    */
   createProcessor(
     filterFn?: (msg: Message) => boolean
   ): MessageProcessorFunction {
     return async (originalMessages: Message[], modifiedMessages: Message[]) => {
-      // Process messages in place - substitute variables before tool calls are executed
-      for (let i = 0; i < modifiedMessages.length; i++) {
-        const message = modifiedMessages[i];
-
-        if (filterFn && !filterFn(message)) {
-          continue;
-        }
-
-        // Apply variable substitution
-        modifiedMessages[i] = this.processMessage(message);
+      // Only process the last message (the newly added one).
+      // Processing historical messages would mutate already-committed content
+      // and destroy Anthropic's prefix-cache match from that point onwards.
+      const lastIndex = modifiedMessages.length - 1;
+      if (lastIndex < 0) return;
+
+      const message = modifiedMessages[lastIndex];
+      if (!filterFn || filterFn(message)) {
+        modifiedMessages[lastIndex] = this.processMessage(message);
       }
     };
   }
@@ -357,6 +362,13 @@ export class CustomVariables {
    * This helps the LLM discover that it can avoid re-outputting long strings
    * (e.g. JWTs, file contents) by storing them once with setVariable or
    * storeToolCallToVariable and then referencing them via {{varName}}.
+   *
+   * CACHING NOTE: To protect Anthropic prefix-cache stability this processor
+   * keeps at most ONE hint message in the array.  Before injecting a new hint
+   * it removes the previous one (identified by a stable sentinel prefix) so
+   * the total message count — and therefore every cache breakpoint — stays
+   * constant.  The hint content is also kept deterministic (no per-call
+   * volatile numbers) so that re-injecting the same hint is a cache no-op.
    */
   createRepetitionHintProcessor(options: {
     minLength?: number;       // Minimum string length to consider (default: 50)
@@ -377,11 +389,26 @@ export class CustomVariables {
     // ~100 base + 30 per example = ~190 tokens for the hint message itself
     const hintMessageTokens = options.hintMessageTokens ?? (100 + maxExamples * 30);
 
-    // Throttle state: track message count at last hint emission
+    // Stable sentinel that uniquely identifies hint messages injected by this processor.
+    // Must be a fixed string so the cache sees identical bytes on re-injection.
+    const HINT_SENTINEL = "⚠️ [knowhow:repetition-hint]";
+
+    // Throttle state: track the index of the message that was current when we
+    // last evaluated (ignoring the hint message itself in the count).
     let lastHintAtMessageCount = -Infinity;
 
     return async (originalMessages: Message[], modifiedMessages: Message[]) => {
-      // Throttle: only emit hint if enough new messages have been added since last hint
+      // Remove any previously injected hint so we never accumulate duplicates
+      // and so the message array length stays predictable for cache breakpoints.
+      const existingHintIndex = modifiedMessages.findIndex(
+        (m) => typeof m.content === "string" && m.content.startsWith(HINT_SENTINEL)
+      );
+      if (existingHintIndex !== -1) {
+        modifiedMessages.splice(existingHintIndex, 1);
+      }
+
+      // Throttle: only re-evaluate if enough *real* messages have arrived since last hint.
+      // We exclude the hint message itself from the count (already removed above).
       const currentMessageCount = modifiedMessages.length;
       if (currentMessageCount - lastHintAtMessageCount < throttleMessages) {
         return;
@@ -480,22 +507,20 @@ export class CustomVariables {
         }
 
         // Build example variable suggestions
-        const examples = repeatedEntries.slice(0, maxExamples).map(({ str, count, toolNames }, i) => {
+        // Use stable previews (fixed 80-char slices) to keep hint content
+        // deterministic across calls — volatile token counts are omitted so
+        // re-injecting the same hint does not bust the Anthropic prefix cache.
+        const examples = repeatedEntries.slice(0, maxExamples).map(({ str, toolNames }, i) => {
           const preview = str.trim().slice(0, 80).replace(/\s+/g, " ");
           const ellipsis = str.length > 80 ? "…" : "";
           const varName = `var${i + 1}`;
-          const charsSaved = (count - 1) * str.length;
-          const tokensSaved = Math.round(charsSaved / 4);
-          return (
-            `  • \`${varName}\` (used ${count}x in ${[...toolNames].join(", ")}, ~${tokensSaved} tokens saveable): "${preview}${ellipsis}"`
-          );
+          return `  • \`${varName}\` (in ${[...toolNames].join(", ")}): "${preview}${ellipsis}"`;
         });
 
         modifiedMessages.push({
           role: "user",
           content:
-            `⚠️ Tool inputs have large repetitions detected in: ${repeatedTools.join(", ")} ` +
-            `(~${grossTokensSaved} tokens saveable, ~${netTokensSaved} net after this reminder). ` +
+            `${HINT_SENTINEL} Tool inputs have large repetitions detected in: ${repeatedTools.join(", ")}. ` +
             `Consider storing repeated values with \`setVariable\` or \`storeToolCallToVariable\`, ` +
             `then reference them via {{variableName}} in future tool calls.\n` +
             `Top repeated values to consider storing as variables:\n` +

package/src/processors/TokenCompressor.ts

@@ -32,6 +32,12 @@ export class TokenCompressor implements JsonCompressorStorage {
   private compressionThreshold: number = 4000;
   private characterLimit: number = this.compressionThreshold * 4;
 
+  // Minimum size (in characters) a standalone chunk should have. Leftover content
+  // smaller than this is merged into an adjacent chunk so we never emit tiny,
+  // low-value chunks that force the agent into extra round-trips to reassemble a
+  // file. Defaults to half of the per-chunk character limit.
+  private minChunkCharacters: number = Math.floor(this.characterLimit / 2);
+
   // Largest size retrievable without re-compressing
   public maxTokens: number = this.compressionThreshold * 2;
 
@@ -56,6 +62,7 @@ export class TokenCompressor implements JsonCompressorStorage {
   public setCompressionThreshold(threshold: number): void {
     this.compressionThreshold = threshold;
     this.characterLimit = threshold * 4; // Update character limit based on new threshold
+    this.minChunkCharacters = Math.floor(this.characterLimit / 2);
     this.jsonCompressor.updateSettings(threshold, this.maxTokens);
   }
 
@@ -88,7 +95,7 @@ export class TokenCompressor implements JsonCompressorStorage {
     const chunkKeys: string[] = [];
     let remaining = content;
 
-    // Split from the end, creating chunks that will be linked
+    // Split from the end, creating chunks that will be linked.
     while (remaining.length > this.characterLimit) {
       const chunkStart = remaining.length - this.characterLimit;
       const chunk = remaining.substring(chunkStart);
@@ -96,9 +103,19 @@ export class TokenCompressor implements JsonCompressorStorage {
       remaining = remaining.substring(0, chunkStart);
     }
 
-    // The remaining part becomes the first chunk
+    // The remaining part becomes the first chunk. To avoid producing a tiny,
+    // low-value leading chunk (which forces the agent into extra round-trips to
+    // reassemble a file), merge it into the next chunk when it falls below the
+    // minimum chunk size. Only split it out as its own chunk when it is large
+    // enough to stand on its own.
     if (remaining.length > 0) {
-      chunks.unshift(remaining);
+      if (chunks.length > 0 && remaining.length < this.minChunkCharacters) {
+        // Prepend the small leftover onto the first existing chunk so every
+        // emitted chunk carries a meaningful amount of content.
+        chunks[0] = remaining + chunks[0];
+      } else {
+        chunks.unshift(remaining);
+      }
     }
 
     // Store chunks and create chain of references
@@ -131,7 +148,7 @@ export class TokenCompressor implements JsonCompressorStorage {
       200
     )}...\n[Use ${
       this.toolName
-    } tool with key "${firstKey}" to retrieve content. Follow NEXT_CHUNK_KEY references for complete content]\n[TIP: try jqToolResponse,grepToolResponse,tailToolResponse to filter/search/map without repeated expandTokens calls]`;
+    } tool with key "${firstKey}" to retrieve the FULL content in one call (chunks are auto-stitched; pass fromLine/toLine for a ranged read)]\n[TIP: try jqToolResponse,grepToolResponse,tailToolResponse to filter/search/map with REAL line numbers without expanding at all]`;
   }
 
   /**
@@ -282,6 +299,38 @@ export class TokenCompressor implements JsonCompressorStorage {
     return this.storage[key] || null;
   }
 
+  /**
+   * Retrieves the fully reassembled content for a key, following any
+   * `NEXT_CHUNK_KEY` references and stripping the chunk-linking markers. This
+   * lets callers get the complete content in a single call instead of chasing a
+   * chain of nested keys.
+   */
+  retrieveFullString(key: string): string | null {
+    let currentKey: string | null = key;
+    let result = "";
+    let found = false;
+    const visited = new Set<string>();
+
+    while (currentKey && !visited.has(currentKey)) {
+      visited.add(currentKey);
+      const chunk = this.storage[currentKey];
+      if (chunk === undefined) {
+        break;
+      }
+      found = true;
+
+      const nextMatch = chunk.match(/\n\n\[NEXT_CHUNK_KEY:\s*([^\s\]]+)\]/);
+      const nextKey = nextMatch ? nextMatch[1] : null;
+
+      // Strip the trailing NEXT_CHUNK_KEY marker before stitching.
+      const cleaned = chunk.replace(/\n\n\[NEXT_CHUNK_KEY:\s*[^\s\]]+\]/, "");
+      result += cleaned;
+      currentKey = nextKey;
+    }
+
+    return found ? result : null;
+  }
+
   storeString(key: string, value: string): void {
     if (this.estimateTokens(value) > this.maxTokens) {
       // adjust max tokens so we can always retrieve this without re-compressing
@@ -307,15 +356,42 @@ export class TokenCompressor implements JsonCompressorStorage {
     if (toolsService) {
       toolsService.addTools([expandTokensDefinition]);
       toolsService.addFunctions({
-        [this.toolName]: (key: string) => {
-          const data = this.retrieveString(key);
+        [this.toolName]: (key: string, fromLine?: number, toLine?: number) => {
+          // Auto-stitch: follow any NEXT_CHUNK_KEY chain and return the full,
+          // reassembled content so the agent never has to chase nested keys.
+          const data = this.retrieveFullString(key);
 
-          if (!data) {
+          if (data === null) {
             return `Error: No data found for key "${key}". Available keys: ${this.getStorageKeys().join(
               ", "
             )}`;
           }
-          return data;
+
+          // Optional ranged read: return only the requested 1-based, inclusive
+          // line range, prefixed with real line numbers for easy mapping back.
+          const hasRange =
+            typeof fromLine === "number" || typeof toLine === "number";
+          if (!hasRange) {
+            return data;
+          }
+
+          const lines = data.split("\n");
+          const totalLines = lines.length;
+          const start = Math.max(1, typeof fromLine === "number" ? fromLine : 1);
+          const end = Math.min(
+            totalLines,
+            typeof toLine === "number" ? toLine : totalLines
+          );
+
+          if (start > end) {
+            return `Error: Invalid line range for key "${key}": fromLine (${start}) is greater than toLine (${end}). Content has ${totalLines} lines.`;
+          }
+
+          const numbered: string[] = [];
+          for (let i = start; i <= end; i++) {
+            numbered.push(`${i}: ${lines[i - 1]}`);
+          }
+          return numbered.join("\n");
         },
       });
     }
@@ -420,7 +496,7 @@ export const expandTokensDefinition: Tool = {
   function: {
     name: "expandTokens",
     description:
-      "Retrieve a chunk of compressed data that was stored during message processing. The returned content may contain a `NEXT_CHUNK_KEY` to retrieve subsequent chunks. NOTE: Can also use jqToolResponse, grepToolResponse, tailToolResponse to access/filter/search compressed content without needing to expand all tokens.",
+      "Retrieve compressed data that was stored during message processing. The full content is automatically reassembled (any chunk chain is followed for you, so you never need to chase NEXT_CHUNK_KEY references). Optionally pass fromLine/toLine (1-based, inclusive) to return just a range of lines, prefixed with real line numbers. NOTE: Can also use jqToolResponse, grepToolResponse, tailToolResponse to access/filter/search compressed content without needing to expand all tokens.",
     parameters: {
       type: "object",
       positional: true,
@@ -429,6 +505,16 @@ export const expandTokensDefinition: Tool = {
           type: "string",
           description: "The key of the compressed data to retrieve",
         },
+        fromLine: {
+          type: "number",
+          description:
+            "Optional 1-based start line (inclusive) for a ranged read of the reassembled content.",
+        },
+        toLine: {
+          type: "number",
+          description:
+            "Optional 1-based end line (inclusive). Defaults to the end of the content when omitted.",
+        },
       },
       required: ["key"],
     },

package/src/services/AgentSyncFs.ts

@@ -220,10 +220,15 @@ export class AgentSyncFs {
         );
         this.lastInputContent = input;
 
-        agent.addPendingUserMessage({
-          role: "user",
-          content: input,
-        });
+        // Detect slash commands in the input
+        if (input.trim().startsWith("/")) {
+          await this.handleInputCommand(agent, input.trim());
+        } else {
+          agent.addPendingUserMessage({
+            role: "user",
+            content: input,
+          });
+        }
 
         // Clear the input file after processing
         await this.writeInput("");
@@ -233,6 +238,23 @@ export class AgentSyncFs {
     }
   }
 
+  /**
+   * Handle slash commands sent via input.txt
+   */
+  private async handleInputCommand(agent: BaseAgent, input: string): Promise<void> {
+    const [command, ...rest] = input.split(" ");
+    const message = rest.join(" ").trim() || undefined;
+
+    if (command === "/poke") {
+      console.log(`🫵 Received /poke command for task ${this.taskId}`);
+      agent.interrupt(message);
+    } else {
+      // Unknown command — treat as a regular message
+      console.warn(`⚠️ Unknown command "${command}", treating as message`);
+      agent.addPendingUserMessage({ role: "user", content: input });
+    }
+  }
+
   /**
    * Wait for resume by monitoring status file
    */

package/src/services/AgentSyncKnowhowWeb.ts

@@ -151,10 +151,15 @@ export class AgentSyncKnowhowWeb {
       // Inject pending messages into the agent
       const messageIds: string[] = [];
       for (const msg of pendingMessages) {
-        agent.addPendingUserMessage({
-          role: msg.role as "user" | "assistant",
-          content: msg.message,
-        });
+        // Detect slash commands in messages
+        if (msg.message.trim().startsWith("/")) {
+          await this.handleMessageCommand(agent, msg.message.trim());
+        } else {
+          agent.addPendingUserMessage({
+            role: msg.role as "user" | "assistant",
+            content: msg.message,
+          });
+        }
         messageIds.push(msg.id);
       }
 
@@ -167,6 +172,23 @@ export class AgentSyncKnowhowWeb {
     }
   }
 
+  /**
+   * Handle slash commands sent as pending messages
+   */
+  private async handleMessageCommand(agent: BaseAgent, input: string): Promise<void> {
+    const [command, ...rest] = input.split(" ");
+    const message = rest.join(" ").trim() || undefined;
+
+    if (command === "/poke") {
+      console.log(`🫵 Received /poke command for task ${this.knowhowTaskId}`);
+      agent.interrupt(message);
+    } else {
+      // Unknown command — treat as a regular message
+      console.warn(`⚠️ Unknown command "${command}", treating as message`);
+      agent.addPendingUserMessage({ role: "user", content: input });
+    }
+  }
+
   /**
    * Wait for the agent to be resumed or killed via API
    * Polls the API every 2 seconds, with a 1 hour timeout

package/src/services/SyncedAgentWatcher.ts

@@ -13,6 +13,8 @@ export interface SyncedAgentWatcher {
   stopWatching(): void;
   /** The task ID being watched */
   taskId: string;
+  /** Interrupt the agent's current tool call or AI completion */
+  interrupt(message?: string): Promise<void>;
   /** The agent name being watched */
   agentName: string;
   /** Send a message to the remote agent */
@@ -55,6 +57,7 @@ export interface AttachableAgent {
   pause(): void | Promise<void>;
   unpause(): void | Promise<void>;
   kill(): void | Promise<void>;
+  interrupt(message?: string): void | Promise<void>;
   addPendingUserMessage(message: Message): void;
 }
 
@@ -97,6 +100,11 @@ export class WatcherBackedAgent implements AttachableAgent {
     this.agentEvents.emit(this.eventTypes.done, "Agent killed");
   }
 
+  async interrupt(message?: string): Promise<void> {
+    await this.watcher.interrupt(message);
+    console.log("🫵 Interrupt sent to remote agent.");
+  }
+
   addPendingUserMessage(message: Message): void {
     // Fire-and-forget — errors are logged but not surfaced
     const text = typeof message.content === "string" ? message.content : "";