@mrciphersmith/keryx 0.2.109 → 0.2.110

package/dist/cli.js

@@ -28143,7 +28143,7 @@ async function runAgentTurnCore(io, deps, history, userLine, options = {}) {
         continue;
       }
       executedAny = true;
-      const result = concurrentSpawnResults?.get(call.id) ?? await executeCall(call, toolByName, io.requestApproval, io.permissionMode, io.onAutoApproved, hasInvocationCapacity, reserveInvocation, invocationBudget.maxCalls);
+      const result = concurrentSpawnResults?.get(call.id) ?? await executeCall(call, toolByName, io.requestApproval, io.permissionMode, io.onAutoApproved, hasInvocationCapacity, reserveInvocation, invocationBudget.maxCalls, signal);
       io.onToolResult?.(call.name, result);
       const modelOutput = redactSensitiveText(result.output);
       const untrusted = result.untrusted === true;
@@ -28417,7 +28417,7 @@ async function runConcurrentSpawnBatch(spawnCalls, toolByName, io, deps, hasInvo
     return results;
   }
 }
-async function executeCall(call, toolByName, requestApproval, permissionMode, onAutoApproved, hasInvocationCapacity, reserveInvocation, maxToolCalls) {
+async function executeCall(call, toolByName, requestApproval, permissionMode, onAutoApproved, hasInvocationCapacity, reserveInvocation, maxToolCalls, signal) {
   const tool = toolByName.get(call.name);
   if (tool === undefined) {
     return { output: `unknown tool: ${call.name}`, isError: true };
@@ -28489,7 +28489,7 @@ async function executeCall(call, toolByName, requestApproval, permissionMode, on
   if (!reserveInvocation()) {
     return toolCallBudgetResult(maxToolCalls ?? 0, maxToolCalls ?? 0);
   }
-  return tool.invoke(input);
+  return tool.invoke(input, { ...signal !== undefined ? { signal } : {} });
 }
 function validateDirectBudget(name, value, min) {
   if (value === undefined)
@@ -28519,7 +28519,11 @@ var init_agent = __esm(() => {
   init_slate_lifecycle();
   init_slate_terminal_state();
   DURABLE_READ_TOOL_NAMES = new Set(["workspace_create", "workspace_propose", "slate_write_seed"]);
-  REPEATABLE_TOOL_NAMES = new Set(["shell_job_output"]);
+  REPEATABLE_TOOL_NAMES = new Set([
+    "shell_job_output",
+    "shell_task_output",
+    "shell_task_wait"
+  ]);
   INSTRUCTION_METAPROJECT_TOOLS = [
     "search_code",
     "graph_affected",
@@ -48683,7 +48687,7 @@ import path47 from "path";
 // package.json
 var package_default = {
   name: "@mrciphersmith/keryx",
-  version: "0.2.109",
+  version: "0.2.110",
   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: {
@@ -80719,6 +80723,7 @@ function createJobRegistry(options) {
     const dropped = job.outputBuffer.length - TERMINATED_OUTPUT_TAIL_BYTES;
     job.outputBuffer = job.outputBuffer.slice(dropped);
     job.readCursor = Math.max(0, job.readCursor - dropped);
+    job.droppedBytes += dropped;
   }
   function appendOutput(job, chunk, stream) {
     job.outputBuffer += chunk;
@@ -80732,6 +80737,7 @@ function createJobRegistry(options) {
       const dropped = job.outputBuffer.length - MAX_BACKGROUND_OUTPUT_BYTES;
       job.outputBuffer = job.outputBuffer.slice(dropped);
       job.readCursor = Math.max(0, job.readCursor - dropped);
+      job.droppedBytes += dropped;
       requestKill(job, "output-cap");
     }
   }
@@ -80797,6 +80803,7 @@ function createJobRegistry(options) {
         outputBuffer: "",
         outputHead: "",
         readCursor: 0,
+        droppedBytes: 0,
         exited: false,
         killRequested: false,
         phaseEmitted: false,
@@ -80874,6 +80881,27 @@ function createJobRegistry(options) {
       }
       return { ok: true, output };
     },
+    readOutputSince(jobId, since) {
+      const job = jobs.get(jobId);
+      if (job === undefined) {
+        return { ok: false, error: `unknown job_id: ${jobId}` };
+      }
+      const requested = Number.isFinite(since) && since > 0 ? Math.trunc(since) : 0;
+      const missed = Math.max(0, job.droppedBytes - requested);
+      const index = Math.min(job.outputBuffer.length, Math.max(0, requested - job.droppedBytes));
+      return {
+        ok: true,
+        output: job.outputBuffer.slice(index),
+        nextCursor: job.droppedBytes + job.outputBuffer.length,
+        missed,
+        status: job.info.status
+      };
+    },
+    markObserved(jobId) {
+      const job = jobs.get(jobId);
+      if (job !== undefined)
+        job.info.observed = true;
+    },
     async waitForExit(jobId, ms) {
       const job = jobs.get(jobId);
       if (job === undefined)
@@ -80959,7 +80987,7 @@ function shellJobOutputTool(registry) {
   return {
     definition: {
       name: "shell_job_output",
-      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.",
+      description: "DEPRECATED \u2014 use shell_task_output, which takes an explicit cursor; this name is kept for one release. " + "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" } },
@@ -80973,7 +81001,7 @@ function shellJobOutputTool(registry) {
       if (jobId.length === 0) {
         return { output: "shell_job_output requires a non-empty 'job_id'", isError: true };
       }
-      const result = registry.readOutput(jobId);
+      const result = registry.readOutput(resolveTaskId(registry, jobId));
       if (!result.ok) {
         return { output: result.error, isError: true };
       }
@@ -80981,11 +81009,175 @@ function shellJobOutputTool(registry) {
     }
   };
 }
+function shellTaskOutputTool(registry, options) {
+  return {
+    definition: {
+      name: "shell_task_output",
+      description: "Read a shell task's output from an EXPLICIT cursor. Input: { task_id: string, since?: integer } \u2014 " + "omit `since` (or pass 0) for everything retained, then pass back the next_cursor from the previous " + "result to get only what is new. Two calls with the same `since` return the same bytes, so this is safe " + "to call again after a failure. The result states the task's status and its next_cursor, and says so " + "when older output was dropped before your cursor.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          task_id: { type: "string" },
+          since: { type: "integer" }
+        },
+        required: ["task_id"],
+        additionalProperties: false
+      },
+      risk: "read"
+    },
+    invoke: async (input) => {
+      const taskId = typeof input.task_id === "string" ? input.task_id : "";
+      if (taskId.length === 0) {
+        return { output: "shell_task_output requires a non-empty 'task_id'", isError: true };
+      }
+      const since = typeof input.since === "number" ? input.since : 0;
+      const result = registry.readOutputSince(taskId, since);
+      if (!result.ok) {
+        return { output: result.error, isError: true };
+      }
+      if (options.observer === "main" && result.status !== "running") {
+        registry.markObserved(taskId);
+      }
+      const missed = result.missed > 0 ? `
+[${result.missed} byte(s) older than your cursor were dropped and cannot be re-read]` : "";
+      const trailer = `
+[task ${taskId} status=${result.status} next_cursor=${result.nextCursor}]`;
+      return { output: `${result.output}${missed}${trailer}`, isError: false };
+    }
+  };
+}
+function demoteTask(registry, taskId) {
+  const resolved = taskId;
+  const info = registry.get(resolved);
+  if (info === undefined) {
+    return { ok: false, error: `unknown task_id: ${taskId}` };
+  }
+  if (info.status !== "running") {
+    return { ok: false, error: `task ${resolved} is not running (status: ${info.status})` };
+  }
+  if (info.phase === "background") {
+    return { ok: false, error: `task ${resolved} is already running in the background` };
+  }
+  return registry.promote(resolved);
+}
+var MAX_TASK_WAIT_MS = 300000;
+function clampTaskWaitMs(ms) {
+  if (!Number.isFinite(ms))
+    return MAX_TASK_WAIT_MS;
+  if (ms <= 0)
+    return 0;
+  return Math.min(MAX_TASK_WAIT_MS, Math.trunc(ms));
+}
+function describeWaitedTask(registry, taskId) {
+  const info = registry.get(taskId);
+  if (info === undefined)
+    return `${taskId}: unknown task_id (not tracked by this session)`;
+  const exit = info.exitCode !== undefined ? ` exit=${info.exitCode}` : "";
+  const reason = info.killReason !== undefined ? ` killReason=${info.killReason}` : "";
+  return `${taskId}: ${info.status}${exit}${reason}`;
+}
+function shellTaskWaitTool(registry) {
+  return {
+    definition: {
+      name: "shell_task_wait",
+      description: 'Wait for shell tasks to finish instead of polling. Input: { task_ids: string[], mode: "any" | "all", ' + "timeout_ms?: integer } \u2014 `any` returns as soon as one of them ends, `all` when every one has. The wait is " + "bounded (timeout_ms is clamped to at most 300000) and NEVER kills: if the bound is reached you get each " + "task's current status and the tasks keep running. Read their output with shell_task_output(task_id).",
+      inputSchema: {
+        type: "object",
+        properties: {
+          task_ids: { type: "array", items: { type: "string" } },
+          mode: { type: "string", enum: ["any", "all"] },
+          timeout_ms: { type: "integer" }
+        },
+        required: ["task_ids", "mode"],
+        additionalProperties: false
+      },
+      risk: "read"
+    },
+    invoke: async (input, ctx) => {
+      const rawIds = Array.isArray(input.task_ids) ? input.task_ids : [];
+      const taskIds = rawIds.filter((id) => typeof id === "string" && id.length > 0);
+      if (taskIds.length === 0) {
+        return { output: "shell_task_wait requires a non-empty 'task_ids'", isError: true };
+      }
+      const mode = input.mode === "any" ? "any" : "all";
+      const timeoutMs = clampTaskWaitMs(typeof input.timeout_ms === "number" ? input.timeout_ms : MAX_TASK_WAIT_MS);
+      const known = taskIds.filter((id) => registry.get(id) !== undefined);
+      const signal = ctx?.signal;
+      let onAbort;
+      const aborted = new Promise((resolve) => {
+        if (signal === undefined)
+          return;
+        if (signal.aborted) {
+          resolve("aborted");
+          return;
+        }
+        onAbort = () => resolve("aborted");
+        signal.addEventListener("abort", onAbort, { once: true });
+      });
+      try {
+        if (known.length > 0) {
+          const waits = known.map((id) => registry.waitForExit(id, timeoutMs).then(() => id));
+          const settled = mode === "any" ? await Promise.race([...waits, aborted]) : await Promise.race([Promise.all(waits).then(() => "all"), aborted]);
+          if (settled === "aborted") {
+            const lines = taskIds.map((id) => describeWaitedTask(registry, id));
+            return {
+              output: `interrupted: the wait was stopped and every task is STILL RUNNING \u2014 none was killed.
+` + lines.join(`
+`),
+              isError: false
+            };
+          }
+        }
+        const lines = taskIds.map((id) => describeWaitedTask(registry, id));
+        return { output: lines.join(`
+`), isError: false };
+      } finally {
+        if (onAbort !== undefined)
+          signal?.removeEventListener("abort", onAbort);
+      }
+    }
+  };
+}
+function resolveTaskId(registry, id) {
+  if (registry.get(id) !== undefined)
+    return id;
+  const swapped = id.startsWith("job-") ? `task-${id.slice("job-".length)}` : id.startsWith("task-") ? `job-${id.slice("task-".length)}` : undefined;
+  if (swapped !== undefined && registry.get(swapped) !== undefined)
+    return swapped;
+  return id;
+}
+function shellTaskKillTool(registry) {
+  return {
+    definition: {
+      name: "shell_task_kill",
+      description: "Stop a running shell task \u2014 its entire process group, including any descendant it backgrounded. Input: " + "{ task_id: string }. Killing a task that has already finished is refused with its status rather than " + "signalling anything, so calling this twice is safe. Only tasks from this session can be targeted.",
+      inputSchema: {
+        type: "object",
+        properties: { task_id: { type: "string" } },
+        required: ["task_id"],
+        additionalProperties: false
+      },
+      risk: "read"
+    },
+    invoke: async (input) => {
+      const raw = typeof input.task_id === "string" ? input.task_id : "";
+      if (raw.length === 0) {
+        return { output: "shell_task_kill requires a non-empty 'task_id'", isError: true };
+      }
+      const taskId = raw;
+      const result = await registry.kill(taskId);
+      if (!result.ok) {
+        return { output: result.error, isError: true };
+      }
+      return { output: `task ${taskId} killed`, isError: false };
+    }
+  };
+}
 function shellJobKillTool(registry) {
   return {
     definition: {
       name: "shell_job_kill",
-      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.",
+      description: "DEPRECATED \u2014 use shell_task_kill; this name is kept for one release. " + "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" } },
@@ -81332,7 +81524,7 @@ function shellExecTool(root, run = makeCommandRunner(root), jobRegistry, options
       },
       risk: "shell"
     },
-    invoke: async (input) => {
+    invoke: async (input, ctx) => {
       const command = typeof input.command === "string" ? input.command : "";
       if (command.length === 0) {
         return { output: "shell_exec requires a non-empty 'command'", isError: true };
@@ -81365,21 +81557,34 @@ function shellExecTool(root, run = makeCommandRunner(root), jobRegistry, options
         });
       }
       const yieldMs = options?.yieldMs ?? resolveShellYieldMs();
-      const outcome = await jobRegistry.waitForExit(taskId, yieldMs);
+      const signal = ctx?.signal;
+      let onAbort;
+      const outcome = await (signal === undefined || signal.aborted === false ? Promise.race([
+        jobRegistry.waitForExit(taskId, yieldMs),
+        new Promise((resolve) => {
+          if (signal === undefined)
+            return;
+          onAbort = () => resolve("aborted");
+          signal.addEventListener("abort", onAbort, { once: true });
+        })
+      ]) : Promise.resolve("aborted"));
+      if (onAbort !== undefined)
+        signal?.removeEventListener("abort", onAbort);
       let collected = started.output;
       const pending = jobRegistry.readOutput(taskId);
       if (pending.ok)
         collected += pending.output;
-      if (outcome === "timeout") {
+      if (outcome === "timeout" || outcome === "aborted") {
         const promoted = jobRegistry.promote(taskId);
         if (!promoted.ok) {
           return { output: promoted.error, isError: true };
         }
+        const notice = outcome === "aborted" ? `interrupted: the wait was stopped, so this is now a background task and it is STILL RUNNING \u2014 it was not killed; read new output with shell_job_output("${taskId}") and stop it with shell_job_kill("${taskId}")` : `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}")`;
         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}")`,
+          notice,
           ...promoted.overCap !== undefined ? { overCap: promoted.overCap } : {}
         });
       }
@@ -82239,7 +82444,13 @@ function buildInteractiveAgentTools(input) {
     webFetchTool(),
     webSearchTool(input.searchController),
     shellExecTool(input.cwd, undefined, jobRegistry),
-    ...jobRegistry !== undefined ? [shellJobOutputTool(jobRegistry), shellJobKillTool(jobRegistry)] : [],
+    ...jobRegistry !== undefined ? [
+      shellTaskOutputTool(jobRegistry, { observer: "main" }),
+      shellTaskWaitTool(jobRegistry),
+      shellTaskKillTool(jobRegistry),
+      shellJobOutputTool(jobRegistry),
+      shellJobKillTool(jobRegistry)
+    ] : [],
     applyPatchTool(input.cwd),
     workspaceOverviewTool(input.cwd),
     workspaceReadTool(input.cwd),
@@ -88278,6 +88489,8 @@ function classifyBusyDispatch(params) {
     return "copy";
   if (commandName === "/mode")
     return "mode";
+  if (commandName === "/demote")
+    return "demote";
   if (commandName === "/game")
     return "game";
   const isBusyReadonlyCommand = isSessionInfo || isFlows || isWorkspace || isReview || isMcp || isMcpConsumer;
@@ -90432,6 +90645,11 @@ var AGENT_SLASH_COMMANDS = [
     description: "Hand a task to an external agent CLI \u2014 /delegate <agent> <task>",
     modes: AGENT_ONLY
   },
+  {
+    name: "/demote",
+    description: "Move a running foreground task to the background \u2014 /demote <task_id>",
+    modes: AGENT_ONLY
+  },
   {
     name: "/exit",
     description: "Leave the shell (/quit works too)",
@@ -90462,6 +90680,18 @@ function parseDelegateCommand(args) {
   }
   return { ok: true, agentId, task };
 }
+var DEMOTE_USAGE = "/demote <task_id>  (the task_id shell_exec returned)";
+function parseDemoteCommand(args) {
+  const trimmed = args.trim();
+  if (trimmed.length === 0) {
+    return { ok: false, reason: `usage: ${DEMOTE_USAGE}` };
+  }
+  const parts = trimmed.split(/\s+/);
+  if (parts.length > 1) {
+    return { ok: false, reason: `\`/demote\` takes ONE task_id \u2014 usage: ${DEMOTE_USAGE}` };
+  }
+  return { ok: true, taskId: parts[0] ?? "" };
+}
 function isCommandInMode(command, mode) {
   return command.modes.includes(mode);
 }
@@ -95116,7 +95346,12 @@ function paintBackgroundJobSidebar(otui, renderer, parent, entries, options) {
 
 // src/tui/tui-shell.ts
 var SESSION_PREVIEW_MESSAGE_COUNT = 200;
-var SIDE_WORKER_DENIED_TOOL_NAMES = new Set(["shell_job_kill"]);
+var SIDE_WORKER_DENIED_TOOL_NAMES = new Set([
+  "shell_job_kill",
+  "shell_task_kill",
+  "shell_task_wait",
+  "shell_job_output"
+]);
 function parseGitHubRemote(remote) {
   const trimmed = remote.trim();
   if (trimmed.length === 0) {
@@ -97989,6 +98224,22 @@ Staying in the current session.
           isMcpConsumer: isMcpConsumerCommand(line)
         });
         switch (decision) {
+          case "demote": {
+            const parsed = parseDemoteCommand(line.trim().replace(/^\/\S+\s*/, ""));
+            if (!parsed.ok) {
+              io.onSystem?.(`${parsed.reason}
+`);
+            } else if (deps.jobRegistry === undefined) {
+              io.onSystem?.(`This session tracks no shell tasks, so there is nothing to demote.
+`);
+            } else {
+              const demoted = demoteTask(deps.jobRegistry, parsed.taskId);
+              io.onSystem?.(demoted.ok ? `Task ${parsed.taskId} keeps running, now in the background \u2014 it was NOT stopped.
+` : `${demoted.error}
+`);
+            }
+            return;
+          }
           case "exit": {
             foregroundOperation.cancel("shell exit");
             foregroundOperation.dispose();
@@ -98184,6 +98435,22 @@ Staying in the current session.
           })();
           return;
         }
+        if (command.name === "/demote") {
+          const parsed = parseDemoteCommand(line.trim().replace(/^\/\S+\s*/, ""));
+          if (!parsed.ok) {
+            io.onSystem?.(`${parsed.reason}
+`);
+          } else if (deps.jobRegistry === undefined) {
+            io.onSystem?.(`This session tracks no shell tasks, so there is nothing to demote.
+`);
+          } else {
+            const demoted = demoteTask(deps.jobRegistry, parsed.taskId);
+            io.onSystem?.(demoted.ok ? `Task ${parsed.taskId} keeps running, now in the background \u2014 it was NOT stopped.
+` : `${demoted.error}
+`);
+          }
+          return;
+        }
         if (command.name === "/clear" || command.name === "/new") {
           (async () => {
             await closeSlateSession(slateSession, mintTimestampAttemptId);
@@ -100223,6 +100490,25 @@ ${GUTTER}${turnSeparator()}
 `);
           } else {
             agentIo.onSystem?.(`Compacted \u2212${packed.result.removed} context msgs \xB7 archive ${live.summary.archiveMessageCount} \xB7 compact\xD7${live.summary.compactCount}
+`);
+          }
+        }
+      } else if (command === "/demote") {
+        const parsed = parseDemoteCommand(rest);
+        if (!parsed.ok) {
+          agentIo.onSystem?.(`${parsed.reason}
+`);
+        } else if (deps.jobRegistry === undefined) {
+          agentIo.onSystem?.(`This session tracks no shell tasks, so there is nothing to demote.
+`);
+        } else {
+          const demoted = demoteTask(deps.jobRegistry, parsed.taskId);
+          if (!demoted.ok) {
+            agentIo.onSystem?.(`${demoted.error}
+`);
+          } else {
+            const overCap = demoted.overCap !== undefined ? ` Background tasks are over the cap; also running: ${demoted.overCap}.` : "";
+            agentIo.onSystem?.(`Task ${parsed.taskId} keeps running, now in the background \u2014 it was NOT stopped.${overCap}
 `);
           }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.109",
+  "version": "0.2.110",
   "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": {