@livx.cc/agentx 0.99.47 → 0.99.49

package/dist/tools.shell.d.ts

@@ -1,4 +1,4 @@
-import { A as AgentTool } from './tools-BqL8Lk4J.js';
+import { k as JobRegistry, A as AgentTool } from './tools-HsbxgqjF.js';
 import '@livx.cc/wcli/core';
 
 /**
@@ -81,7 +81,7 @@ interface ShellJobConfig {
     spawn?: SpawnFn;
     env?: Record<string, string>;
     redactEnv?: boolean;
-    /** Tail buffer cap per job (bytes); older output is dropped. Default 256 KB. */
+    /** Tail buffer cap per job (bytes); older output is dropped. Default 256 KB. Ignored when `jobs` is shared. */
     maxBuffer?: number;
     /** Kill all jobs on process exit (the CLI sets this; tests leave it off to avoid global handlers). */
     killOnExit?: boolean;
@@ -92,8 +92,15 @@ interface ShellJobConfig {
      * that finishes has to reach the MODEL, or `background:true` is a write-only hole — the model starts
      * a job, forgets it, and never collects the result. The host wires this to `agent.inject(...)`, which
      * folds the notice in at the next step boundary (and re-opens the turn if the model was about to stop).
+     * A job REAPED as stuck is reported too (status `killed` + `reason`).
      */
     onExit?: JobExitHandler;
+    /** The generic job registry these jobs live in. Share the Agent's (`AgentOptions.jobs`) so one
+     *  JobStatus/JobOutput surface and one liveness reaper cover shell, MCP and delegated tools alike. */
+    jobs?: JobRegistry;
+    /** Cumulative CPU seconds of a process group — the "is a silent job still working?" probe used before an
+     *  ADOPTED job is reaped as idle. Default: `ps` (psGroupCpuSeconds); return undefined when unknown. */
+    cpuTime?: (pgid: number) => Promise<number | undefined>;
 }
 interface JobExitNotice {
     id: string;
@@ -101,24 +108,43 @@ interface JobExitNotice {
     status: JobStatus;
     exitCode?: number;
     tail: string;
+    reason?: string;
 }
 type JobExitHandler = (n: JobExitNotice) => void;
 /** The exact text a completion notice becomes. Shared so every host (CLI, presets, embedders) pushes the
  *  same thing back to the model instead of each inventing its own wording. */
 declare function formatJobExit(n: JobExitNotice): string;
+/** Parse `ps` TIME (`[[dd-]hh:]mm:ss[.cc]`) to seconds. */
+declare function parsePsTime(t: string): number | undefined;
+/** Summed CPU seconds of the job's live processes: its process group (`pgid` = the detached leader's pid) PLUS every
+ *  descendant of that pid — a child that moved to its own group (`timeout`, `setsid`, some build tools) still works for
+ *  the job and must count. One `ps` call, C locale (stable number format); macOS + Linux. Undefined when nothing is
+ *  left or ps is unavailable — the reaper then treats CPU as unknown and does NOT kill on it. */
+declare function psGroupCpuSeconds(pgid: number): Promise<number | undefined>;
+/** Pure part of `psGroupCpuSeconds`: parse `pid ppid pgid time` rows, sum the group ∪ descendants of `root`. */
+declare function sumTreeCpu(psOut: string, root: number): number | undefined;
 /**
- * Per-session registry of background `/bin/sh` jobs. Backs `Shell({background:true})` and the
- * `ShellOutput`/`ShellStatus`/`ShellKill` tools. Output accumulates into a tail-capped ring so a
- * chatty process can't OOM. Bounded + killable; the CLI wires `killOnExit` so children are reaped.
+ * Per-session registry of background `/bin/sh` jobs. Backs `Shell({background:true})`, foreground-deadline
+ * adoption, and the `ShellOutput`/`ShellStatus`/`ShellKill` tools. A thin OS layer over the generic
+ * `JobRegistry` (src/tools.jobs.ts): output ring, liveness, notices and the stuck-job reaper live there.
+ *
+ * Liveness policy: an EXPLICIT `background:true` job is never idle-reaped (a quiet dev server is healthy).
+ * An ADOPTED job (a foreground command that outran its timeout) is: after the `shell` idle window with no
+ * output AND no CPU progress across its process group, it is SIGTERMed (SIGKILL after the grace period)
+ * and reported as `killed: stuck: idle Ns`.
  */
 declare class ShellJobRegistry {
     private cfg;
-    private jobs;
-    private seq;
+    readonly jobs: JobRegistry;
+    private meta;
     constructor(cfg: ShellJobConfig);
     start(command: string): Promise<string>;
-    /** Fire `onExit` at most once per job, with the tail so the model can act without a second round-trip. */
-    private notified;
+    private track;
+    private attach;
+    /** SIGTERM the whole group (bg children are detached group leaders — /bin/sh alone would orphan a forked
+     *  server), then SIGKILL after the grace period if it is still there. Falls back to the pid for fakes. */
+    private signal;
+    /** Fire `onExit` at most once per job (the registry guarantees one terminal state), with the tail so the model can act without a second round-trip. */
     private notifyExit;
     /**
      * Wire (or rewire) the completion callback AFTER construction. A host that only gets its agent handle
@@ -135,6 +161,7 @@ declare class ShellJobRegistry {
         status: JobStatus;
         exitCode?: number;
         bytes: number;
+        reason?: string;
     } | null;
     list(): Array<{
         id: string;
@@ -147,9 +174,11 @@ declare class ShellJobRegistry {
      * worse, a launcher that spawned its own detached worker leaves that worker running with nothing
      * tracking it. Adopting hands the model a handle instead: the command keeps going, its completion
      * is reported like any other job, and `seed` carries the output produced before the handoff.
+     * Unlike an explicit background job it IS liveness-checked (idle window + CPU probe): nobody asked for
+     * a long-lived process here, so one that goes silent and CPU-idle is stuck, not serving.
      */
     adopt(command: string, proc: SpawnedProcess, seed?: string): string;
-    kill(id: string): boolean;
+    kill(id: string, reason?: string): boolean;
     killAll(): void;
 }
 /** Build an opt-in real-shell tool bound to `options.cwd`. */
@@ -161,4 +190,4 @@ declare function makeRealShellTool(options: RealShellOptions): AgentTool;
  *  job (its registry is dropped), so it must not be able to inspect or SIGTERM the parent's either. */
 declare function makeShellJobTools(registry: ShellJobRegistry): AgentTool[];
 
-export { type JobExitHandler, type JobExitNotice, type JobStatus, type RealShellOptions, type ShellJobConfig, ShellJobRegistry, type SpawnFn, type SpawnedProcess, formatJobExit, makeRealShellTool, makeShellJobTools };
+export { type JobExitHandler, type JobExitNotice, type JobStatus, type RealShellOptions, type ShellJobConfig, ShellJobRegistry, type SpawnFn, type SpawnedProcess, formatJobExit, makeRealShellTool, makeShellJobTools, parsePsTime, psGroupCpuSeconds, sumTreeCpu };