@wrongstack/tools 0.5.5 → 0.5.7

package/dist/builtin.js

@@ -1,5 +1,5 @@
 import { spawn } from 'child_process';
-import { buildChildEnv, stripAnsi, detectNewlineStyle, normalizeToLf, toStyle, atomicWrite, unifiedDiff, compileGlob, loadPlan, emptyPlan, clearPlan, savePlan, removePlanItem, setPlanItemStatus, addPlanItem, formatPlan } from '@wrongstack/core';
+import { buildChildEnv, stripAnsi, detectNewlineStyle, normalizeToLf, toStyle, atomicWrite, unifiedDiff, compileGlob, loadPlan, emptyPlan, clearPlan, savePlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, setPlanItemStatus, formatPlan } from '@wrongstack/core';
 import * as path from 'path';
 import { dirname } from 'path';
 import * as os from 'os';
@@ -232,6 +232,323 @@ function parseAuditOutput(json, exitCode) {
   }
 }
 
+// src/circuit-breaker.ts
+var DEFAULT_MAX_CONSECUTIVE_FAILURES = 5;
+var DEFAULT_SLOW_CALL_THRESHOLD_MS = 6e4;
+var DEFAULT_MAX_SLOW_CALLS = 3;
+var DEFAULT_WINDOW_MS = 6e4;
+var DEFAULT_MAX_CALLS_PER_WINDOW = 30;
+var DEFAULT_COOLDOWN_MS = 3e4;
+var CircuitBreaker = class {
+  maxConsecutiveFailures;
+  slowCallThresholdMs;
+  maxSlowCalls;
+  windowMs;
+  maxCallsPerWindow;
+  cooldownMs;
+  state = "closed";
+  consecutiveFailures = 0;
+  window = [];
+  lastFailureAt = null;
+  lastSlowAt = null;
+  /** Timestamp when the breaker was opened (for cooldown calculation). */
+  openedAt = null;
+  /** Timestamp when the last call ran (for half-open gate). */
+  lastCallAt = null;
+  constructor(config = {}) {
+    this.maxConsecutiveFailures = config.maxConsecutiveFailures ?? DEFAULT_MAX_CONSECUTIVE_FAILURES;
+    this.slowCallThresholdMs = config.slowCallThresholdMs ?? DEFAULT_SLOW_CALL_THRESHOLD_MS;
+    this.maxSlowCalls = config.maxSlowCalls ?? DEFAULT_MAX_SLOW_CALLS;
+    this.windowMs = config.windowMs ?? DEFAULT_WINDOW_MS;
+    this.maxCallsPerWindow = config.maxCallsPerWindow ?? DEFAULT_MAX_CALLS_PER_WINDOW;
+    this.cooldownMs = config.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+  }
+  /**
+   * Returns true if the circuit allows a new call to proceed.
+   * When false, callers should abort the tool call and return a
+   * circuit-breaker error instead of spawning a process.
+   */
+  get canProceed() {
+    this._checkStateTransition();
+    return this.state !== "open";
+  }
+  /**
+   * Snapshot of the current breaker state for observability (`/kill`).
+   */
+  snapshot() {
+    this._checkStateTransition();
+    const now = Date.now();
+    let cooldownRemaining = null;
+    if (this.openedAt !== null && this.state === "open") {
+      const elapsed = now - this.openedAt;
+      cooldownRemaining = Math.max(0, this.cooldownMs - elapsed);
+    }
+    return {
+      state: this.state,
+      consecutiveFailures: this.consecutiveFailures,
+      slowCallsInWindow: this.window.filter((c) => c.slow).length,
+      callsInWindow: this.window.length,
+      windowMs: this.windowMs,
+      cooldownRemainingMs: cooldownRemaining,
+      lastFailureAt: this.lastFailureAt,
+      lastSlowAt: this.lastSlowAt
+    };
+  }
+  /**
+   * Call this BEFORE spawning a bash/exec process.
+   * Returns true if the call is allowed; false if the breaker is open.
+   * When false, callers MUST NOT spawn a process.
+   */
+  beforeCall() {
+    this._checkStateTransition();
+    if (this.state === "open") return false;
+    return true;
+  }
+  /**
+   * Call this AFTER a bash/exec process finishes (success or failure).
+   * `durationMs` is the wall-clock time the process ran.
+   * `failed` is true when the process returned a non-zero exit code or
+   * threw an exception before spawning.
+   */
+  afterCall(durationMs, failed) {
+    const now = Date.now();
+    this.lastCallAt = now;
+    if (this.state === "half-open") {
+      if (failed) {
+        this._trip();
+        return;
+      }
+      this._reset();
+      return;
+    }
+    this._pruneWindow(now);
+    const slow = durationMs >= this.slowCallThresholdMs;
+    this.window.push({ at: now, failed, slow });
+    if (failed) {
+      this.consecutiveFailures++;
+      this.lastFailureAt = now;
+      if (this.consecutiveFailures >= this.maxConsecutiveFailures) {
+        this._trip();
+      }
+      return;
+    }
+    this.consecutiveFailures = 0;
+    if (slow) {
+      this.lastSlowAt = now;
+      const slowCount = this.window.filter((c) => c.slow).length;
+      if (slowCount >= this.maxSlowCalls) {
+        this._trip();
+      }
+    }
+    const callCount = this.window.length;
+    if (callCount >= this.maxCallsPerWindow) {
+      this._trip();
+    }
+  }
+  /** Force the breaker open. Used by /kill force and Ctrl+C. */
+  forceOpen() {
+    this._trip();
+  }
+  /** Force a reset to closed. Used by tests and /kill reset. */
+  forceReset() {
+    this._reset();
+  }
+  _trip() {
+    if (this.state === "open") return;
+    this.state = "open";
+    this.openedAt = Date.now();
+  }
+  _reset() {
+    this.state = "closed";
+    this.consecutiveFailures = 0;
+    this.window = [];
+    this.openedAt = null;
+  }
+  /** Transition from open → half-open when cooldown elapses. */
+  _checkStateTransition() {
+    if (this.state !== "open" || this.openedAt === null) return;
+    const elapsed = Date.now() - this.openedAt;
+    if (elapsed >= this.cooldownMs) {
+      this.state = "half-open";
+      this.openedAt = null;
+    }
+  }
+  _pruneWindow(now) {
+    const cutoff = now - this.windowMs;
+    this.window = this.window.filter((c) => c.at >= cutoff);
+  }
+};
+
+// src/process-registry.ts
+var DEFAULT_GRACE_MS = 2e3;
+var ProcessRegistryImpl = class {
+  processes = /* @__PURE__ */ new Map();
+  breaker;
+  constructor(breakerConfig) {
+    this.breaker = new CircuitBreaker(breakerConfig);
+  }
+  register(info) {
+    this.processes.set(info.pid, { ...info, killed: false });
+  }
+  /** Unregister a process by PID. Called on 'close' / 'exit' events. */
+  unregister(pid) {
+    this.processes.delete(pid);
+  }
+  /** Get a single process by PID. */
+  get(pid) {
+    return this.processes.get(pid);
+  }
+  /** Get all tracked processes. */
+  list() {
+    return Array.from(this.processes.values());
+  }
+  /** Get processes filtered by name (e.g. 'bash', 'exec'). */
+  byName(name) {
+    return this.list().filter((p) => p.name === name);
+  }
+  /** Get processes filtered by session. */
+  bySession(sessionId) {
+    return this.list().filter((p) => p.sessionId === sessionId);
+  }
+  /** Count of active (non-killed) processes. */
+  get activeCount() {
+    let n = 0;
+    for (const p of this.processes.values()) {
+      if (!p.killed) n++;
+    }
+    return n;
+  }
+  /**
+   * Combined stats for observability — used by /ps and the TUI status bar.
+   */
+  stats() {
+    return {
+      activeCount: this.activeCount,
+      totalCount: this.processes.size,
+      breaker: this.breaker.snapshot()
+    };
+  }
+  /**
+   * Returns true if the circuit allows a new bash/exec call to proceed.
+   * When false, callers MUST NOT spawn a process.
+   */
+  get canProceed() {
+    return this.breaker.canProceed;
+  }
+  /**
+   * Called before spawning a process. Returns true if allowed; false if
+   * the circuit breaker is open.
+   */
+  beforeCall() {
+    return this.breaker.beforeCall();
+  }
+  /**
+   * Called after a process finishes. `durationMs` is wall-clock time;
+   * `failed` is true for non-zero exit codes.
+   */
+  afterCall(durationMs, failed) {
+    this.breaker.afterCall(durationMs, failed);
+  }
+  /** Force-open the circuit breaker (Ctrl+C, /kill force). */
+  forceBreakerOpen() {
+    this.breaker.forceOpen();
+  }
+  /** Force-reset the circuit breaker to closed (/kill reset). */
+  forceBreakerReset() {
+    this.breaker.forceReset();
+  }
+  /** Kill a single process by PID.
+   *
+   *  On POSIX: sends SIGTERM to the *process group* (-pid) so that
+   *  runaway grandchild processes (`sleep 9999 & disown`) are also killed.
+   *  After `graceMs` a SIGKILL is sent if the process hasn't exited.
+   *
+   *  On Windows: `child.kill()` maps to TerminateProcess — process groups
+   *  are not meaningfully supported. A second `force=true` call sends
+   *  SIGKILL (which maps to TerminateProcess again — the distinction is
+   *  in the exit code, not the signal).
+   *
+   *  Returns true if the process was found and kill was attempted.
+   */
+  kill(pid, opts = {}) {
+    const p = this.processes.get(pid);
+    if (!p) return false;
+    if (p.killed) return true;
+    const { force = false, graceMs = DEFAULT_GRACE_MS } = opts;
+    const isWin = os.platform() === "win32";
+    if (isWin) {
+      try {
+        p.child.kill(force ? "SIGKILL" : "SIGTERM");
+      } catch {
+      }
+      p.killed = true;
+      return true;
+    }
+    try {
+      if (force) {
+        try {
+          process.kill(-pid, "SIGKILL");
+        } catch {
+          p.child.kill("SIGKILL");
+        }
+      } else {
+        try {
+          process.kill(-pid, "SIGTERM");
+        } catch {
+          p.child.kill("SIGTERM");
+        }
+        const timer = setTimeout(() => {
+          if (this.processes.has(pid) && !p.child.killed) {
+            try {
+              process.kill(-pid, "SIGKILL");
+            } catch {
+              try {
+                p.child.kill("SIGKILL");
+              } catch {
+              }
+            }
+          }
+        }, graceMs);
+        timer.unref?.();
+      }
+    } catch {
+    }
+    p.killed = true;
+    return true;
+  }
+  /**
+   * Kill all tracked processes.
+   * Returns the PIDs that were kill()ed.
+   */
+  killAll(opts = {}) {
+    const pids = Array.from(this.processes.keys());
+    const killed = [];
+    for (const pid of pids) {
+      if (this.kill(pid, opts)) killed.push(pid);
+    }
+    return killed;
+  }
+  /**
+   * Kill all processes for a specific session.
+   * Returns the PIDs that were kill()ed.
+   */
+  killSession(sessionId, opts = {}) {
+    const pids = this.bySession(sessionId).map((p) => p.pid);
+    const killed = [];
+    for (const pid of pids) {
+      if (this.kill(pid, opts)) killed.push(pid);
+    }
+    return killed;
+  }
+};
+var _registry;
+function getProcessRegistry() {
+  if (!_registry) {
+    _registry = new ProcessRegistryImpl();
+  }
+  return _registry;
+}
+
 // src/bash.ts
 var MAX_OUTPUT = 32768;
 var DEFAULT_TIMEOUT = 3e4;
@@ -270,12 +587,27 @@ var bashTool = {
   },
   async *executeStream(input, ctx, opts) {
     if (!input?.command) throw new Error("bash: command is required");
+    const registry = getProcessRegistry();
+    if (!registry.beforeCall()) {
+      yield {
+        type: "final",
+        output: {
+          output: "",
+          exit_code: 1,
+          timed_out: false,
+          pid: null,
+          error: "bash: circuit breaker open \u2014 too many consecutive failures or slow calls. Use /kill to inspect or /kill reset to recover."
+        }
+      };
+      return;
+    }
     const timeoutMs = Math.max(1, Math.min(input.timeout_ms ?? DEFAULT_TIMEOUT, 6e5));
     const isWin = os.platform() === "win32";
     const shell = isWin ? process.env["COMSPEC"] ?? "cmd.exe" : process.env["SHELL"] ?? "/bin/bash";
     const args = isWin ? ["/c", input.command] : ["-c", input.command];
     const env = buildChildEnv(ctx.session?.id);
     const detached = isWin ? !!input.background : true;
+    const startedAt = Date.now();
     if (input.background) {
       let buf2 = "";
       let truncated = false;
@@ -286,7 +618,18 @@ var bashTool = {
         detached: true,
         signal: opts.signal
       });
-      const pid = child2.pid;
+      const pid2 = child2.pid;
+      if (typeof pid2 === "number") {
+        registry.register({
+          pid: pid2,
+          name: "bash",
+          command: input.command,
+          startedAt: Date.now(),
+          sessionId: ctx.session?.id,
+          child: child2
+        });
+        child2.on("close", () => registry.unregister(pid2));
+      }
       child2.stdout?.on("data", (chunk) => {
         if (!truncated) {
           const remain = MAX_OUTPUT - buf2.length;
@@ -306,15 +649,16 @@ var bashTool = {
         }
       });
       child2.on("close", () => {
+        registry.afterCall(Date.now() - startedAt, false);
       });
-      if (typeof pid === "number") child2.unref();
+      if (typeof pid2 === "number") child2.unref();
       yield {
         type: "final",
         output: {
           output: truncated ? buf2.slice(0, MAX_OUTPUT) + "\u2026[truncated]" : buf2,
           exit_code: null,
           timed_out: false,
-          pid
+          pid: pid2
         }
       };
       return;
@@ -326,6 +670,17 @@ var bashTool = {
       detached,
       signal: opts.signal
     });
+    const pid = child.pid;
+    if (typeof pid === "number") {
+      registry.register({
+        pid,
+        name: "bash",
+        command: input.command,
+        startedAt: Date.now(),
+        sessionId: ctx.session?.id,
+        child
+      });
+    }
     let buf = "";
     let pending = "";
     let timedOut = false;
@@ -408,10 +763,13 @@ var bashTool = {
     });
     child.on("error", (err) => {
       for (const t of timers) clearTimeout(t);
+      registry.afterCall(Date.now() - startedAt, true);
       push({ kind: "error", err });
     });
     child.on("close", (code) => {
       for (const t of timers) clearTimeout(t);
+      if (typeof pid === "number") registry.unregister(pid);
+      registry.afterCall(Date.now() - startedAt, code !== 0 && code !== null);
       push({ kind: "end", code });
     });
     try {
@@ -1029,6 +1387,18 @@ var execTool = {
     required: ["command"]
   },
   async execute(input, ctx, opts) {
+    const registry = getProcessRegistry();
+    if (!registry.canProceed) {
+      return {
+        command: input.command,
+        args: input.args ?? [],
+        stdout: "",
+        stderr: "Circuit breaker is open \u2014 too many consecutive failures. Use /kill reset to recover.",
+        exitCode: 1,
+        truncated: false,
+        allowed: false
+      };
+    }
     const cmd = input.command.trim();
     if (!cmd)
       return {
@@ -1088,15 +1458,23 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
     let stdout = "";
     let stderr = "";
     let killed = false;
+    const startedAt = Date.now();
     const child = spawn(cmd, args, {
       cwd,
       signal,
       env: buildChildEnv(sessionId),
       stdio: ["ignore", "pipe", "pipe"]
     });
+    const registry = getProcessRegistry();
+    const pid = child.pid;
+    if (typeof pid === "number") {
+      const fullCommand = `${cmd} ${args.join(" ")}`;
+      registry.register({ pid, name: "exec", command: fullCommand, startedAt: Date.now(), sessionId, child });
+    }
     const timer = setTimeout(() => {
       killed = true;
-      child.kill("SIGTERM");
+      if (typeof pid === "number") registry.kill(pid);
+      else child.kill("SIGTERM");
     }, timeout);
     child.stdout?.on("data", (chunk) => {
       if (stdout.length < MAX_OUTPUT2) stdout += chunk.toString();
@@ -1106,18 +1484,24 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
     });
     child.on("close", (code) => {
       clearTimeout(timer);
+      if (typeof pid === "number") registry.unregister(pid);
+      const durationMs = Date.now() - startedAt;
+      const exitCode = killed ? 124 : code ?? 1;
+      registry.afterCall(durationMs, exitCode !== 0);
       resolve5({
         command: cmd,
         args,
         stdout: stdout.slice(0, MAX_OUTPUT2),
         stderr: stderr.slice(0, MAX_OUTPUT2),
-        exitCode: killed ? 124 : code ?? 1,
+        exitCode,
         truncated: stdout.length >= MAX_OUTPUT2 || stderr.length >= MAX_OUTPUT2,
         allowed: true
       });
     });
     child.on("error", (err) => {
       clearTimeout(timer);
+      if (typeof pid === "number") registry.unregister(pid);
+      registry.afterCall(Date.now() - startedAt, true);
       resolve5({
         command: cmd,
         args,
@@ -2799,8 +3183,8 @@ function extractPatchedFiles(output) {
 var planTool = {
   name: "plan",
   category: "Session",
-  description: "Inspect or edit the strategic plan board for this session. Plans persist across resume (unlike todos). Use this to lay out the multi-step approach before diving in, then mark steps in_progress/done as the work proceeds.",
-  usageHint: "Set action to one of: show | add | start | done | remove | clear. Pass `title` for add. Pass `target` (item id, 1-based index, or title substring) for start/done/remove. Always returns the formatted plan plus open/total counts.",
+  description: "Inspect or edit the strategic plan board for this session. Plans persist across resume (unlike todos). Use this to lay out the multi-step approach before diving in, then mark steps in_progress/done as the work proceeds. Promote a plan item to todos to start working on it. Apply templates for common workflows.",
+  usageHint: 'Set action to one of: show | add | start | done | remove | promote | derive | template_use | clear. Pass `title` for add. Pass `target` (item id, 1-based index, or title substring) for start/done/remove/promote/derive. Pass `subtasks` for promote/derive to break the plan item into multiple todos. Pass `template` (e.g. "new-feature", "bug-fix", "refactor", "release") for template_use. Always returns the formatted plan plus open/total counts.',
   permission: "auto",
   mutating: false,
   timeoutMs: 2e3,
@@ -2809,13 +3193,22 @@ var planTool = {
     properties: {
       action: {
         type: "string",
-        enum: ["show", "add", "start", "done", "remove", "clear"]
+        enum: ["show", "add", "start", "done", "remove", "promote", "derive", "template_use", "clear"]
       },
       title: { type: "string", description: "Required when action = add." },
       details: { type: "string", description: "Optional extra context for add." },
       target: {
         type: "string",
-        description: "Plan item id, 1-based index, or title substring. Required for start/done/remove."
+        description: "Plan item id, 1-based index, or title substring. Required for start/done/remove/promote/derive."
+      },
+      subtasks: {
+        type: "array",
+        items: { type: "string" },
+        description: "Optional subtasks for promote/derive. If omitted, a single todo is created from the plan item title."
+      },
+      template: {
+        type: "string",
+        description: "Template name for template_use action. Available: new-feature, bug-fix, refactor, release, security-audit, onboarding."
       }
     },
     required: ["action"]
@@ -2874,6 +3267,35 @@ var planTool = {
         await savePlan(planPath, plan);
         break;
       }
+      case "promote":
+      case "derive": {
+        if (!input.target) {
+          return mkResult(plan, false, `${input.action} requires \`target\` (id|index|substring).`);
+        }
+        const derived = deriveTodosFromPlanItem(plan, input.target, input.subtasks);
+        if (!derived) {
+          return mkResult(plan, false, `No plan item matched "${input.target}".`);
+        }
+        plan = derived.plan;
+        await savePlan(planPath, plan);
+        ctx.state.replaceTodos(derived.todos);
+        return mkResult(plan, true, `${input.action} ok \u2014 ${derived.todos.length} todo(s) created.`, derived.todos);
+      }
+      case "template_use": {
+        const templateName = input.template?.trim();
+        if (!templateName) {
+          return mkResult(plan, false, "template_use requires `template` name.");
+        }
+        const template = getPlanTemplate(templateName);
+        if (!template) {
+          return mkResult(plan, false, `Unknown template "${templateName}".`);
+        }
+        for (const item of template.items) {
+          ({ plan } = addPlanItem(plan, item.title, item.details));
+        }
+        await savePlan(planPath, plan);
+        return mkResult(plan, true, `Applied template "${template.name}" \u2014 ${template.items.length} items added.`);
+      }
       case "clear":
         plan = clearPlan(plan);
         await savePlan(planPath, plan);
@@ -2884,14 +3306,15 @@ var planTool = {
     return mkResult(plan, true, `Plan ${input.action} ok.`);
   }
 };
-function mkResult(plan, ok, message) {
+function mkResult(plan, ok, message, todos) {
   const open = plan.items.filter((i) => i.status !== "done").length;
   return {
     ok,
     message,
     plan: formatPlan(plan),
     count: plan.items.length,
-    open
+    open,
+    todos
   };
 }
 var MAX_BYTES2 = 5 * 1024 * 1024;