@tyvm/knowhow 0.0.131 → 0.0.134

package/package.json

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

package/src/agents/base/base.ts

@@ -75,6 +75,13 @@ export abstract class BaseAgent implements IAgent {
 
   // Interrupt support: resolves the currently awaited tool call or completion
   private _interruptResolve: (() => void) | null = null;
+  // A monotonically-increasing token identifying the active interruptible window.
+  // Used to ensure a stale (slow) operation completing in the background cannot
+  // clobber a newer interruptible window's resolver.
+  private _interruptToken = 0;
+  // Set when interrupt() is called with no active window, so the next
+  // makeInterruptible fires immediately instead of dropping the interrupt.
+  private _pendingInterrupt = false;
 
   protected threads = [] as Message[][];
 
@@ -217,6 +224,11 @@ export abstract class BaseAgent implements IAgent {
     this.startTimeMs = Date.now();
     this.currentTaskId = taskId || this.startTimeMs.toString();
 
+    // Reset interrupt state so a queued/stale interrupt from a prior task
+    // can't fire against the new task.
+    this._interruptResolve = null;
+    this._pendingInterrupt = false;
+
     // Emit event for plugin integration
     const id = taskId || this.startTimeMs.toString();
     this.events.emit(this.eventTypes.agentNewTask, {
@@ -740,32 +752,43 @@ export abstract class BaseAgent implements IAgent {
     interruptValue: T
   ): Promise<T> {
     return new Promise<T>((resolve, reject) => {
-      let interrupted = false;
-
-      this._interruptResolve = () => {
-        interrupted = true;
-        this._interruptResolve = null;
-        resolve(interruptValue);
+      // Each interruptible window gets a unique token. `settled` guards this
+      // specific window so it can only ever resolve/reject once, and the token
+      // ensures a stale (slow) background operation that finishes AFTER this
+      // window was interrupted cannot clobber a NEWER window's resolver.
+      const myToken = ++this._interruptToken;
+      let settled = false;
+
+      const finish = (fn: () => void) => {
+        if (settled) return;
+        settled = true;
+        // Only clear the shared resolver if it still belongs to this window.
+        if (this._interruptToken === myToken) {
+          this._interruptResolve = null;
+        }
+        fn();
       };
 
+      this._interruptResolve = () => finish(() => resolve(interruptValue));
+
+      // If an interrupt arrived while there was no active window, honor it now.
+      if (this._pendingInterrupt) {
+        this._pendingInterrupt = false;
+        finish(() => resolve(interruptValue));
+        return;
+      }
+
       promise
         .then((result) => {
-          if (this._interruptResolve) {
-            this._interruptResolve = null;
-            resolve(result);
-          }
+          // If this window was already interrupted/settled, drop the stale
+          // result — do NOT touch _interruptResolve (it may belong to a newer
+          // window now).
+          finish(() => 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);
-          }
+          // If the window was already interrupted, swallow the late error.
+          if (settled) return;
+          finish(() => reject(err));
         });
     });
   }
@@ -777,10 +800,29 @@ export abstract class BaseAgent implements IAgent {
    */
   interrupt(message = "User interrupted this action you were waiting on") {
     this.log(`Interrupting current operation: ${message}`);
+
+    // If the user supplied a real message with the poke (not the default
+    // interrupt reason), queue it as a pending user message so the agent
+    // actually sees what they said on its next step.
+    if (
+      message &&
+      message !== "User interrupted this action you were waiting on"
+    ) {
+      this.addPendingUserMessage({ role: "user", content: message });
+    }
+
     if (this._interruptResolve) {
       this._interruptResolve();
     } else {
-      this.log("No active interruptible operation to interrupt", "warn");
+      // No active interruptible window right now (we're between the AI
+      // completion and the tool call, or in message processing). Queue the
+      // interrupt so the next makeInterruptible window fires immediately
+      // instead of silently dropping it.
+      this._pendingInterrupt = true;
+      this.log(
+        "No active interruptible operation — queued interrupt for next step",
+        "warn"
+      );
     }
   }
 

package/src/cli.ts

@@ -1,6 +1,23 @@
 #!/usr/bin/env node --no-node-snapshot
 // Mark this process as running the Knowhow CLI (not just the SDK)
 process.env.KNOWHOW_CLI = "1";
+
+// Determine which warnings to show based on the command being run.
+// Commands that don't need AI models or a config file should not spam warnings.
+// Individual commands can override by setting KNOWHOW_WARN_NEEDS before parsing.
+// Format: comma-separated list of "models" | "config" (or empty string to suppress all).
+const _rawArgs = process.argv.slice(2);
+const _firstArg = _rawArgs.find((a) => !a.startsWith("-"));
+const COMMANDS_NEEDING_MODELS = new Set(["chat", "agent", "ask", "generate", "embed", "replay"]);
+const COMMANDS_NEEDING_CONFIG = new Set([
+  "chat", "agent", "ask", "generate", "embed", "upload", "download",
+  "worker", "workers", "replay", "behaviors", "skills",
+]);
+const _needsModels = _firstArg && COMMANDS_NEEDING_MODELS.has(_firstArg) ? "models" : "";
+const _needsConfig = _firstArg && COMMANDS_NEEDING_CONFIG.has(_firstArg) ? "config" : "";
+const _needs = [_needsModels, _needsConfig].filter(Boolean).join(",");
+process.env.KNOWHOW_WARN_NEEDS = process.env.KNOWHOW_WARN_NEEDS ?? _needs;
+
 import { Command } from "commander";
 import { version } from "../package.json";
 import { logger } from "./logger";
@@ -44,6 +61,7 @@ import { addBehaviorsCommand } from "./commands/behaviors";
 import { addSkillsCommand } from "./commands/skills";
 import { addAgentsCommand } from "./commands/agents";
 import { addHashCommand } from "./commands/hash";
+import { addSandboxCommand } from "./commands/sandbox";
 
 // Handle unhandled promise rejections gracefully — particularly from MCP SDK
 // which fires errors via event emitters that can bypass Promise.allSettled.
@@ -112,6 +130,7 @@ async function main() {
   addSkillsCommand(program);
   addAgentsCommand(program);
   addHashCommand(program);
+  addSandboxCommand(program);
 
   // Load global modules early (before parse) so they can register CLI subcommands.
   // We pass only the Program in context — no services are spun up at this stage.

package/src/clients/index.ts

@@ -311,7 +311,8 @@ export class AIClient {
       if (!client) {
         if (entry.provider === "knowhow") {
           if (process.env.KNOWHOW_CLI) {
-            console.warn(
+            const warnNeeds = (process.env.KNOWHOW_WARN_NEEDS ?? "").split(",");
+            if (warnNeeds.includes("models")) console.warn(
               `⚠️  Knowhow provider is not logged in. Run 'knowhow login' to enable Knowhow models.`
             );
           }

package/src/commands/hash.ts

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import * as crypto from "crypto";
 import * as fs from "fs";
+import { execSync } from "child_process";
 import { globSync } from "glob";
 import { getHashes, saveHashes } from "../hashes";
 
@@ -42,7 +43,16 @@ export function addHashCommand(program: Command): void {
     )
     .option(
       "--save",
-      "Save the current hash after a successful build step."
+      "Save the current hash. In standalone mode, records the hash immediately (no command run). " +
+        "In --run mode, records the hash only if the command succeeds. " +
+        "Without --save in --run mode, the hash is never recorded — useful when --run is a " +
+        "side-effect trigger rather than the step that produces the tracked artifacts."
+    )
+    .option(
+      "--run <command>",
+      "Self-contained mode: if inputs are unchanged, skip and exit 0. " +
+        "If changed (or first run), run this shell command and — only if it " +
+        "succeeds — save the new hash. Replaces the '(hash) || (build && hash --save)' pattern."
     )
     .option("--verbose", "Print what files were found and the computed hash")
     .action(
@@ -51,6 +61,7 @@ export function addHashCommand(program: Command): void {
         input: string;
         output?: string;
         save?: boolean;
+        run?: string;
         verbose?: boolean;
       }) => {
         const hashes = await getHashes();
@@ -90,13 +101,16 @@ export function addHashCommand(program: Command): void {
           process.exit(0);
         }
 
-        // Check mode: if any output file is missing, always report changed
+        // Determine whether inputs (or missing outputs) indicate a rebuild is needed.
+        let changed = false;
+
+        // If any output file is missing, always report changed
         for (const outPath of outputPaths) {
           if (!fs.existsSync(outPath)) {
             if (opts.verbose) {
               console.error(`[knowhow hash] output file missing: ${outPath} → changed`);
             }
-            process.exit(1);
+            changed = true;
           }
         }
 
@@ -108,7 +122,47 @@ export function addHashCommand(program: Command): void {
           );
         }
 
-        if (storedHash && storedHash === currentHash) {
+        if (!(storedHash && storedHash === currentHash)) {
+          changed = true;
+        }
+
+        // --run mode: self-contained. Skip when unchanged; otherwise run the
+        // command and only save the new hash if it succeeds.
+        if (opts.run) {
+          if (!changed) {
+            if (opts.verbose) {
+              console.error(`[knowhow hash] ✓ unchanged — skipping "${opts.run}"`);
+            }
+            process.exit(0);
+          }
+
+          if (opts.verbose) {
+            console.error(`[knowhow hash] ✗ changed — running "${opts.run}"`);
+          }
+          try {
+            execSync(opts.run, { stdio: "inherit", shell: "/bin/sh" });
+          } catch (err: any) {
+            // Command failed — do NOT save the hash so it retries next time.
+            process.exit(typeof err?.status === "number" ? err.status : 1);
+          }
+
+          // Command succeeded — only save the hash if --save was also passed.
+          // Without --save, the hash is NOT recorded so the command will re-run next time.
+          // Use --save when --run produces the artifacts that the hash tracks.
+          // Omit --save when --run is a side-effect trigger (e.g. snapshot regeneration).
+          if (opts.save) {
+            if (!hashes[opts.name]) hashes[opts.name] = {};
+            hashes[opts.name][opts.input] = currentHash;
+            await saveHashes(hashes);
+            if (opts.verbose) {
+              console.error(`[knowhow hash] saved hash ${currentHash} for "${opts.name}"`);
+            }
+          }
+          process.exit(0);
+        }
+
+        // Legacy check mode: exit 0 (unchanged) or 1 (changed).
+        if (!changed) {
           if (opts.verbose) {
             console.error(`[knowhow hash] ✓ unchanged — skipping`);
           }