@mrciphersmith/keryx 0.2.107 → 0.2.108

package/dist/cli.js

@@ -48579,7 +48579,7 @@ import path47 from "path";
 // package.json
 var package_default = {
   name: "@mrciphersmith/keryx",
-  version: "0.2.107",
+  version: "0.2.108",
   description: "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   private: false,
   publishConfig: {
@@ -80462,6 +80462,36 @@ var MAX_BACKGROUND_OUTPUT_BYTES = 2 * 1024 * 1024;
 var DEFAULT_INITIAL_BUFFER_MS = 500;
 var MAX_TRACKED_JOBS = 50;
 var TERMINATED_OUTPUT_TAIL_BYTES = 4000;
+var TASK_OUTPUT_HEAD_BYTES = 24000;
+var ENV_SHELL_IDLE_MS = "KERYX_SHELL_IDLE_MS";
+var ENV_SHELL_TIMEOUT_MS_FALLBACK = "KERYX_SHELL_TIMEOUT_MS";
+var DEFAULT_SHELL_IDLE_MS = 120000;
+var MIN_TASK_IDLE_TIMEOUT_MS = 1000;
+var MAX_TASK_IDLE_TIMEOUT_MS = 1800000;
+function parseEnvMs(raw) {
+  if (raw === undefined || raw.trim().length === 0)
+    return;
+  const n = Number.parseInt(raw.trim(), 10);
+  if (!Number.isFinite(n) || n < 0)
+    return Number.NaN;
+  return n;
+}
+function resolveShellIdleMs(env = process.env) {
+  const idle = parseEnvMs(env[ENV_SHELL_IDLE_MS]);
+  if (idle !== undefined) {
+    return Number.isNaN(idle) ? DEFAULT_SHELL_IDLE_MS : idle;
+  }
+  const legacy = parseEnvMs(env[ENV_SHELL_TIMEOUT_MS_FALLBACK]);
+  if (legacy !== undefined) {
+    return Number.isNaN(legacy) ? DEFAULT_SHELL_IDLE_MS : legacy;
+  }
+  return DEFAULT_SHELL_IDLE_MS;
+}
+function clampTaskIdleTimeoutMs(ms) {
+  if (!Number.isFinite(ms))
+    return MIN_TASK_IDLE_TIMEOUT_MS;
+  return Math.min(MAX_TASK_IDLE_TIMEOUT_MS, Math.max(MIN_TASK_IDLE_TIMEOUT_MS, Math.trunc(ms)));
+}
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -80539,11 +80569,34 @@ function createJobRegistry(options) {
   const initialBufferMs = options?.initialBufferMs ?? DEFAULT_INITIAL_BUFFER_MS;
   const onEvent = options?.onEvent;
   const maxTrackedJobs = options?.maxTrackedJobs ?? MAX_TRACKED_JOBS;
+  const idleMs = options?.idleMs ?? resolveShellIdleMs();
   let nextId = 0;
   const jobs = new Map;
   function runningJobs() {
     return [...jobs.values()].filter((j) => j.info.status === "running");
   }
+  function backgroundRunningJobs() {
+    return runningJobs().filter((j) => j.info.phase === "background");
+  }
+  function clearIdleTimer(job) {
+    if (job.idleTimer === undefined)
+      return;
+    clearTimeout(job.idleTimer);
+    job.idleTimer = undefined;
+  }
+  function armIdleTimer(job) {
+    clearIdleTimer(job);
+    if (job.info.status !== "running")
+      return;
+    const timeout = job.info.idleTimeoutMs;
+    if (timeout <= 0)
+      return;
+    const timer = setTimeout(() => {
+      requestKill(job, "idle");
+    }, timeout);
+    timer.unref?.();
+    job.idleTimer = timer;
+  }
   function evictOldestTerminatedIfOverCap() {
     if (jobs.size <= maxTrackedJobs)
       return;
@@ -80564,20 +80617,32 @@ function createJobRegistry(options) {
   }
   function appendOutput(job, chunk, stream) {
     job.outputBuffer += chunk;
+    if (job.outputHead.length < TASK_OUTPUT_HEAD_BYTES) {
+      job.outputHead = (job.outputHead + chunk).slice(0, TASK_OUTPUT_HEAD_BYTES);
+      job.info.outputHead = job.outputHead;
+    }
+    armIdleTimer(job);
     onEvent?.({ type: "output", jobId: job.info.jobId, chunk, stream });
     if (job.outputBuffer.length > MAX_BACKGROUND_OUTPUT_BYTES) {
       const dropped = job.outputBuffer.length - MAX_BACKGROUND_OUTPUT_BYTES;
       job.outputBuffer = job.outputBuffer.slice(dropped);
       job.readCursor = Math.max(0, job.readCursor - dropped);
-      if (!job.killRequested) {
-        job.killRequested = true;
-        terminateJob(job, killGraceMs);
-      }
+      requestKill(job, "output-cap");
     }
   }
+  function requestKill(job, reason) {
+    if (job.info.status !== "running")
+      return Promise.resolve();
+    if (job.killRequested)
+      return job.exitedPromise;
+    job.killRequested = true;
+    job.pendingKillReason = reason;
+    return terminateJob(job, killGraceMs);
+  }
   async function terminateJob(job, graceMs) {
     if (job.info.status !== "running")
       return;
+    clearIdleTimer(job);
     job.killRequested = true;
     job.handle.kill("SIGTERM");
     const exited = await Promise.race([job.exitedPromise.then(() => true), sleep(graceMs).then(() => false)]);
@@ -80586,14 +80651,17 @@ function createJobRegistry(options) {
     }
   }
   return {
-    async start(command) {
-      const running = runningJobs();
-      if (running.length >= maxConcurrent) {
-        const names = running.map((j) => j.info.command).join(", ");
-        return {
-          ok: false,
-          error: `background job limit reached (${maxConcurrent} running: ${names}); wait for one to finish or kill it with shell_job_kill first`
-        };
+    async start(command, opts) {
+      const phase = opts?.phase ?? "background";
+      if (phase === "background") {
+        const running = backgroundRunningJobs();
+        if (running.length >= maxConcurrent) {
+          const names = running.map((j) => j.info.command).join(", ");
+          return {
+            ok: false,
+            error: `background task limit reached (${maxConcurrent} running: ${names}); wait for one to finish or kill it with shell_job_kill first`
+          };
+        }
       }
       let handle;
       try {
@@ -80604,7 +80672,7 @@ function createJobRegistry(options) {
           error: `command failed to start: ${cause instanceof Error ? cause.message : String(cause)}`
         };
       }
-      const jobId = `job-${++nextId}-${handle.pid}`;
+      const jobId = `task-${++nextId}-${handle.pid}`;
       let resolveExited;
       const exitedPromise = new Promise((resolve) => {
         resolveExited = resolve;
@@ -80615,26 +80683,46 @@ function createJobRegistry(options) {
           pid: handle.pid,
           command,
           status: "running",
+          phase,
+          idleTimeoutMs: opts?.idleTimeoutMs ?? idleMs,
           startedAt: nowIso3()
         },
         handle,
         outputBuffer: "",
+        outputHead: "",
         readCursor: 0,
         exited: false,
         killRequested: false,
+        phaseEmitted: false,
         resolveExited,
         exitedPromise
       };
+      if (opts?.description !== undefined)
+        job.info.description = opts.description;
       jobs.set(jobId, job);
       evictOldestTerminatedIfOverCap();
-      onEvent?.({ type: "start", jobId, pid: handle.pid, command, startedAt: job.info.startedAt });
+      onEvent?.({
+        type: "start",
+        jobId,
+        pid: handle.pid,
+        command,
+        startedAt: job.info.startedAt,
+        ...opts?.description !== undefined ? { description: opts.description } : {}
+      });
+      if (phase === "background") {
+        job.phaseEmitted = true;
+        onEvent?.({ type: "phase", jobId, phase: "background" });
+      }
       handle.onOutput((chunk, stream) => appendOutput(job, chunk, stream));
       handle.onExit((info) => {
         if (job.exited)
           return;
         job.exited = true;
-        if (job.info.status === "running") {
-          job.info.status = job.killRequested ? "killed" : "exited";
+        clearIdleTimer(job);
+        const terminal = job.killRequested ? "killed" : info.exitCode === 0 ? "completed" : "failed";
+        job.info.status = terminal;
+        if (job.killRequested) {
+          job.info.killReason = job.pendingKillReason ?? "model";
         }
         job.info.exitCode = info.exitCode;
         job.info.endedAt = nowIso3();
@@ -80642,13 +80730,15 @@ function createJobRegistry(options) {
         onEvent?.({
           type: "exit",
           jobId,
-          status: job.info.status,
+          status: terminal,
+          ...job.info.killReason !== undefined ? { killReason: job.info.killReason } : {},
           exitCode: info.exitCode,
           endedAt: job.info.endedAt
         });
         shrinkTerminatedOutput(job);
       });
-      if (initialBufferMs > 0) {
+      armIdleTimer(job);
+      if (phase === "background" && initialBufferMs > 0) {
         await sleep(initialBufferMs);
       }
       const output = job.outputBuffer.slice(job.readCursor);
@@ -80670,7 +80760,41 @@ function createJobRegistry(options) {
       job.readCursor = job.outputBuffer.length;
       return { ok: true, output };
     },
-    async kill(jobId) {
+    async waitForExit(jobId, ms) {
+      const job = jobs.get(jobId);
+      if (job === undefined)
+        return "unknown";
+      if (job.exited || job.info.status !== "running")
+        return "exited";
+      let timer;
+      const timedOut = await Promise.race([
+        job.exitedPromise.then(() => false),
+        new Promise((resolve) => {
+          timer = setTimeout(() => resolve(true), ms);
+          timer.unref?.();
+        })
+      ]);
+      if (timer !== undefined)
+        clearTimeout(timer);
+      return timedOut ? "timeout" : "exited";
+    },
+    promote(jobId) {
+      const job = jobs.get(jobId);
+      if (job === undefined) {
+        return { ok: false, error: `unknown job_id: ${jobId}` };
+      }
+      job.info.phase = "background";
+      if (!job.phaseEmitted) {
+        job.phaseEmitted = true;
+        onEvent?.({ type: "phase", jobId, phase: "background" });
+      }
+      const others = backgroundRunningJobs().filter((j) => j.info.jobId !== jobId);
+      if (job.info.status === "running" && others.length >= maxConcurrent) {
+        return { ok: true, overCap: others.map((j) => j.info.command).join(", ") };
+      }
+      return { ok: true };
+    },
+    async kill(jobId, reason = "model") {
       const job = jobs.get(jobId);
       if (job === undefined) {
         return { ok: false, error: `unknown job_id: ${jobId}` };
@@ -80678,11 +80802,11 @@ function createJobRegistry(options) {
       if (job.info.status !== "running") {
         return { ok: false, error: `job ${jobId} is not running (status: ${job.info.status})` };
       }
-      await terminateJob(job, killGraceMs);
+      await requestKill(job, reason);
       return { ok: true };
     },
     async sweepAll() {
-      await Promise.all(runningJobs().map((job) => terminateJob(job, killGraceMs)));
+      await Promise.all(runningJobs().map((job) => requestKill(job, "session-exit")));
     }
   };
 }
@@ -80690,7 +80814,7 @@ function shellJobOutputTool(registry) {
   return {
     definition: {
       name: "shell_job_output",
-      description: "Return output produced by a background job (started via shell_exec with background:true) SINCE the " + "previous call for that job_id \u2014 never the full transcript again. Input: { job_id: string }. Poll this " + "instead of re-running shell_exec to check on a long-running job.",
+      description: "Return output produced by a shell task SINCE the previous call for that id \u2014 never the full transcript " + "again. Input: { job_id: string } \u2014 pass the task_id shell_exec returned for a command that outlived its " + "yield (or a background:true job). Poll this instead of re-running shell_exec to check on a long command.",
       inputSchema: {
         type: "object",
         properties: { job_id: { type: "string" } },
@@ -80716,7 +80840,7 @@ function shellJobKillTool(registry) {
   return {
     definition: {
       name: "shell_job_kill",
-      description: "Kill a background job started via shell_exec with background:true (its entire process group, including " + "any descendant it backgrounded). Input: { job_id: string }. Only jobs in this session's own registry can " + "be targeted.",
+      description: "Stop a running shell task \u2014 its entire process group, including any descendant it backgrounded. Input: " + "{ job_id: string } \u2014 the task_id shell_exec returned for a command still running after its yield (or a " + "background:true job). Only tasks in this session's own registry can be targeted.",
       inputSchema: {
         type: "object",
         properties: { job_id: { type: "string" } },
@@ -80921,6 +81045,37 @@ function resolveShellTimeoutMs(env = process.env) {
   }
   return n;
 }
+var DEFAULT_SHELL_YIELD_MS = 1e4;
+var ENV_SHELL_YIELD_MS = "KERYX_SHELL_YIELD_MS";
+function resolveShellYieldMs(env = process.env) {
+  const raw = env[ENV_SHELL_YIELD_MS];
+  if (raw === undefined || raw.trim().length === 0) {
+    return DEFAULT_SHELL_YIELD_MS;
+  }
+  const n = Number.parseInt(raw.trim(), 10);
+  if (!Number.isFinite(n) || n < 0) {
+    return DEFAULT_SHELL_YIELD_MS;
+  }
+  return n;
+}
+function boundOutput2(text) {
+  return text.length > MAX_OUTPUT_BYTES3 ? `${text.slice(0, MAX_OUTPUT_BYTES3)}
+\u2026(truncated)` : text;
+}
+function taskHandleResult(args) {
+  return {
+    output: JSON.stringify({
+      task_id: args.taskId,
+      job_id: args.taskId,
+      pid: args.pid,
+      status: "running",
+      output: boundOutput2(args.output),
+      notice: args.notice,
+      ...args.overCap !== undefined ? { over_cap: args.overCap } : {}
+    }),
+    isError: false
+  };
+}
 function makeCommandRunner(root) {
   return async (command) => {
     let netClose = async () => {};
@@ -81014,14 +81169,19 @@ ${notice}` : notice,
     }
   };
 }
-function shellExecTool(root, run = makeCommandRunner(root), jobRegistry) {
+function shellExecTool(root, run = makeCommandRunner(root), jobRegistry, options) {
   return {
     definition: {
       name: "shell_exec",
-      description: "Run a shell command in the project root (e.g. `git status`, `bun test`). Requires the user's approval " + "before it runs. Input: { command: string, background?: boolean }. Combined stdout+stderr is CAPPED at " + "20,000 bytes from the start of output \u2014 do not use sed/grep/cat/awk here to locate code (they can " + "silently truncate before reaching what you need, and repeating the command returns the same truncated " + "head); use search_code or graph_symbol instead, which are built for that and stay within the cap. Set " + "background:true for a long-running command (a dev server, a watch build) \u2014 it returns immediately with " + "{job_id, pid} instead of blocking; poll shell_job_output(job_id) for new output and shell_job_kill" + "(job_id) to stop it.",
+      description: "Run a shell command in the project root (e.g. `git status`, `bun test`). Requires the user's approval " + "before it runs. Input: { command: string, background?: boolean, description?: string, " + "idle_timeout_ms?: integer }. EVERY command returns within a bounded wait \u2014 a short one returns its " + "output directly, and one still running when the wait elapses keeps running as a task: you get " + "{task_id, pid, status, output} instead of its final output, and read the rest with " + "shell_job_output(task_id) and stop it with shell_job_kill(task_id). So a slow command never freezes " + "the session and never needs to be guessed at in advance. background:true only SKIPS the wait (use it " + "for a dev server or a watch build you know you will not read inline); it changes nothing else. " + "description is a short label for the task list. idle_timeout_ms is for a command that is deliberately " + "SILENT for a long time (a sleep, a slow poll) \u2014 a task that produces no output for its idle timeout " + "is killed, so raise it rather than lose the command. Combined stdout+stderr is CAPPED at 20,000 bytes " + "from the start of output \u2014 do not use sed/grep/cat/awk here to locate code (they can silently " + "truncate before reaching what you need, and repeating the command returns the same truncated head); " + "use search_code or graph_symbol instead, which are built for that and stay within the cap.",
       inputSchema: {
         type: "object",
-        properties: { command: { type: "string" }, background: { type: "boolean" } },
+        properties: {
+          command: { type: "string" },
+          background: { type: "boolean" },
+          description: { type: "string" },
+          idle_timeout_ms: { type: "integer" }
+        },
         required: ["command"],
         additionalProperties: false
       },
@@ -81032,20 +81192,66 @@ function shellExecTool(root, run = makeCommandRunner(root), jobRegistry) {
       if (command.length === 0) {
         return { output: "shell_exec requires a non-empty 'command'", isError: true };
       }
-      if (input.background === true) {
-        if (jobRegistry === undefined) {
+      const background = input.background === true;
+      if (jobRegistry === undefined) {
+        if (background) {
           return { output: "shell_exec: background jobs are not available in this session", isError: true };
         }
-        const started = await jobRegistry.start(command);
-        if (!started.ok) {
-          return { output: started.error, isError: true };
+        return run(command);
+      }
+      const startOpts = { phase: background ? "background" : "foreground" };
+      if (typeof input.description === "string" && input.description.length > 0) {
+        startOpts.description = input.description;
+      }
+      if (typeof input.idle_timeout_ms === "number") {
+        startOpts.idleTimeoutMs = clampTaskIdleTimeoutMs(input.idle_timeout_ms);
+      }
+      const started = await jobRegistry.start(command, startOpts);
+      if (!started.ok) {
+        return { output: started.error, isError: true };
+      }
+      const taskId = started.jobId;
+      if (background) {
+        return taskHandleResult({
+          taskId,
+          pid: started.pid,
+          output: started.output,
+          notice: `running as a background task; read new output with shell_job_output("${taskId}") and stop it with shell_job_kill("${taskId}")`
+        });
+      }
+      const yieldMs = options?.yieldMs ?? resolveShellYieldMs();
+      const outcome = await jobRegistry.waitForExit(taskId, yieldMs);
+      let collected = started.output;
+      const pending = jobRegistry.readOutput(taskId);
+      if (pending.ok)
+        collected += pending.output;
+      if (outcome === "timeout") {
+        const promoted = jobRegistry.promote(taskId);
+        if (!promoted.ok) {
+          return { output: promoted.error, isError: true };
         }
-        return {
-          output: JSON.stringify({ job_id: started.jobId, pid: started.pid, output: started.output }),
-          isError: false
-        };
+        return taskHandleResult({
+          taskId,
+          pid: started.pid,
+          output: collected,
+          notice: `still running after ${yieldMs}ms, so it is now a background task; read new output with shell_job_output("${taskId}") and stop it with shell_job_kill("${taskId}")`,
+          ...promoted.overCap !== undefined ? { overCap: promoted.overCap } : {}
+        });
+      }
+      const info = jobRegistry.get(taskId);
+      if (outcome === "unknown" || info === undefined) {
+        const so_far = boundOutput2(collected.trim());
+        const lost = `shell_exec: task ${taskId} is no longer tracked, so its exit status is unknown`;
+        return { output: so_far.length > 0 ? `${so_far}
+${lost}` : lost, isError: true };
       }
-      return run(command);
+      const exitCode = info.exitCode ?? 0;
+      const bounded = boundOutput2((info.outputHead ?? collected).trim());
+      const body = bounded.length > 0 ? bounded : `(no output; exit ${exitCode})`;
+      const idleKilled = info.status === "killed" && info.killReason === "idle";
+      const output = idleKilled ? `${body}
+shell_exec: no output for ${info.idleTimeoutMs}ms, so the command was killed (raise it for this command with idle_timeout_ms, or change the default with ${ENV_SHELL_IDLE_MS})` : body;
+      return { output, isError: info.status !== "completed" };
     }
   };
 }
@@ -94455,9 +94661,14 @@ function openExternalInspector(otui, chrome, options) {
 var MAX_BACKGROUND_JOB_OUTPUT_CHARS = 20000;
 var STATUS_GLYPH4 = {
   running: "\u25D0",
-  exited: "\u25CF",
+  completed: "\u25CF",
+  failed: "\u25B2",
   killed: "\u2717"
 };
+function appendBounded(output, chunk) {
+  const combined = output + chunk;
+  return combined.length > MAX_BACKGROUND_JOB_OUTPUT_CHARS ? combined.slice(-MAX_BACKGROUND_JOB_OUTPUT_CHARS) : combined;
+}
 function clip7(s, max) {
   if (max <= 0) {
     return "";
@@ -94486,6 +94697,9 @@ function formatJobMeta(entry, now = Date.now()) {
     ["Ended", entry.endedAt ?? "\u2014"],
     ["Exit code", entry.exitCode !== undefined ? String(entry.exitCode) : "\u2014"]
   ];
+  if (entry.killReason !== undefined) {
+    rows.push(["Kill reason", entry.killReason]);
+  }
   const width = rows.reduce((max, [label]) => Math.max(max, label.length), 0);
   return rows.map(([label, value]) => `${label.padEnd(width)}  ${value}`).join(`
 `);
@@ -94496,36 +94710,64 @@ function formatJobOutput(entry) {
 
 class BackgroundJobStore {
   jobs = new Map;
+  pending = new Map;
   listeners = new Set;
   apply(event) {
-    if (event.type === "start") {
-      this.jobs.set(event.jobId, {
-        jobId: event.jobId,
-        command: event.command,
-        pid: event.pid,
-        status: "running",
-        startedAt: event.startedAt,
-        output: ""
-      });
-      this.emit({ id: event.jobId, kind: "start" });
-      return;
-    }
-    const current = this.jobs.get(event.jobId);
-    if (current === undefined) {
-      return;
-    }
-    if (event.type === "output") {
-      const combined = current.output + event.chunk;
-      current.output = combined.length > MAX_BACKGROUND_JOB_OUTPUT_CHARS ? combined.slice(-MAX_BACKGROUND_JOB_OUTPUT_CHARS) : combined;
-      this.emit({ id: event.jobId, kind: "output" });
-      return;
-    }
-    current.status = event.status;
-    current.endedAt = event.endedAt;
-    if (event.exitCode !== undefined) {
-      current.exitCode = event.exitCode;
+    switch (event.type) {
+      case "start":
+        this.pending.set(event.jobId, {
+          jobId: event.jobId,
+          command: event.command,
+          pid: event.pid,
+          status: "running",
+          startedAt: event.startedAt,
+          output: ""
+        });
+        return;
+      case "phase": {
+        const entry = this.pending.get(event.jobId);
+        if (entry === undefined) {
+          return;
+        }
+        this.pending.delete(event.jobId);
+        this.jobs.set(event.jobId, entry);
+        this.emit({ id: event.jobId, kind: "start" });
+        return;
+      }
+      case "output": {
+        const hidden = this.pending.get(event.jobId);
+        if (hidden !== undefined) {
+          hidden.output = appendBounded(hidden.output, event.chunk);
+          return;
+        }
+        const current = this.jobs.get(event.jobId);
+        if (current === undefined) {
+          return;
+        }
+        current.output = appendBounded(current.output, event.chunk);
+        this.emit({ id: event.jobId, kind: "output" });
+        return;
+      }
+      case "exit": {
+        if (this.pending.delete(event.jobId)) {
+          return;
+        }
+        const current = this.jobs.get(event.jobId);
+        if (current === undefined) {
+          return;
+        }
+        current.status = event.status;
+        current.endedAt = event.endedAt;
+        if (event.exitCode !== undefined) {
+          current.exitCode = event.exitCode;
+        }
+        if (event.killReason !== undefined) {
+          current.killReason = event.killReason;
+        }
+        this.emit({ id: event.jobId, kind: "exit" });
+        return;
+      }
     }
-    this.emit({ id: event.jobId, kind: "exit" });
   }
   get(jobId) {
     return this.jobs.get(jobId);
@@ -94540,6 +94782,7 @@ class BackgroundJobStore {
     };
   }
   removeAll() {
+    this.pending.clear();
     if (this.jobs.size === 0) {
       return;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.107",
+  "version": "0.2.108",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {