@cruxy/cli 0.23.0 → 0.25.0

package/dist/jobs/approval-queue.js

@@ -0,0 +1,96 @@
+export class ApprovalQueue {
+    queue = [];
+    seq = 0;
+    /**
+     * A job submits a gated action and awaits the decision. Resolves when the
+     * foreground services it ({@link serviceAll}) or a caller {@link withdraw}s it;
+     * rejects if the finalize throws. The action does NOT execute here — the caller
+     * only proceeds after this resolves `{allow:true}`.
+     */
+    submit(sub) {
+        return new Promise((resolve, reject) => {
+            this.queue.push({
+                id: `pa-${++this.seq}`,
+                jobId: sub.jobId,
+                summary: sub.summary,
+                tier: sub.tier,
+                finalize: sub.finalize,
+                resolve,
+                reject,
+                settled: false,
+            });
+        });
+    }
+    /** Whether any request is waiting to be serviced. */
+    hasPending() {
+        return this.queue.length > 0;
+    }
+    /** Count of requests waiting. */
+    get size() {
+        return this.queue.length;
+    }
+    /** Read-only snapshot of every pending request, FIFO order. */
+    pending() {
+        return this.queue.map((e) => ({
+            id: e.id,
+            jobId: e.jobId,
+            summary: e.summary,
+            tier: e.tier,
+        }));
+    }
+    /** The pending request for one job (a job has at most one at a time), if any. */
+    pendingFor(jobId) {
+        return this.pending().find((p) => p.jobId === jobId);
+    }
+    /**
+     * Foreground drain: service every currently-pending request, FIFO, ONE AT A
+     * TIME — each `finalize` fully settles (including the human's keypress) before
+     * the next begins, so two background prompts never overlap and the shared mutex
+     * inside `finalize` also serializes them against any foreground action. Returns
+     * the number serviced. Requests that arrive AFTER draining starts wait for the
+     * next drain (bounded work per idle window). A finalize throw rejects that one
+     * producer and drains on — one job's checkpoint failure never wedges the queue.
+     */
+    async serviceAll() {
+        let serviced = 0;
+        for (;;) {
+            const entry = this.queue.shift();
+            if (!entry)
+                break;
+            if (entry.settled)
+                continue; // withdrawn between snapshot and here
+            try {
+                const decision = await entry.finalize();
+                this.settle(entry, () => entry.resolve(decision));
+            }
+            catch (err) {
+                this.settle(entry, () => entry.reject(err));
+            }
+            serviced++;
+        }
+        return serviced;
+    }
+    /**
+     * Withdraw a job's pending request WITHOUT prompting — used when the job is
+     * cancelled (or the session exits) while it is paused: settle the producer with
+     * `decision` (a deny) so its `submit` promise resolves and the job can finish
+     * tearing down instead of blocking forever. Returns true if one was withdrawn.
+     */
+    withdraw(jobId, decision) {
+        const entry = this.queue.find((e) => e.jobId === jobId && !e.settled);
+        if (!entry)
+            return false;
+        const i = this.queue.indexOf(entry);
+        if (i !== -1)
+            this.queue.splice(i, 1);
+        this.settle(entry, () => entry.resolve(decision));
+        return true;
+    }
+    /** Settle an entry exactly once (double-settle is a defensive no-op). */
+    settle(entry, run) {
+        if (entry.settled)
+            return;
+        entry.settled = true;
+        run();
+    }
+}

package/dist/jobs/dispatch-tool.d.ts

@@ -0,0 +1,34 @@
+import { z } from "zod";
+import type { Tool } from "../tools/index.js";
+import type { JobManager } from "./manager.js";
+/**
+ * The `run_in_background` tool (C.28): the agent-facing seam for dispatching a
+ * background job. Unlike `spawn_subagent`, it does NOT block — it returns a job
+ * id immediately and the job runs CONCURRENTLY with the rest of the turn and the
+ * session. The agent uses it for long-running, self-contained work it does not
+ * want to wait on inline; the human watches it with `/jobs` and `/logs`, and any
+ * side effect the job takes still requires a foreground approval.
+ */
+export declare const RUN_IN_BACKGROUND_TOOL_NAME = "run_in_background";
+declare const parameters: z.ZodObject<{
+    task: z.ZodString;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString, "atleastone">>;
+    root: z.ZodOptional<z.ZodString>;
+    maxIterations: z.ZodOptional<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    task: string;
+    root?: string | undefined;
+    maxTokens?: number | undefined;
+    maxIterations?: number | undefined;
+    tools?: [string, ...string[]] | undefined;
+}, {
+    task: string;
+    root?: string | undefined;
+    maxTokens?: number | undefined;
+    maxIterations?: number | undefined;
+    tools?: [string, ...string[]] | undefined;
+}>;
+/** Build the `run_in_background` tool bound to the session's job manager. */
+export declare function makeRunInBackgroundTool(manager: JobManager): Tool<typeof parameters>;
+export {};

package/dist/jobs/dispatch-tool.js

@@ -0,0 +1,96 @@
+import { z } from "zod";
+import { CruxyError } from "../errors/index.js";
+/**
+ * The `run_in_background` tool (C.28): the agent-facing seam for dispatching a
+ * background job. Unlike `spawn_subagent`, it does NOT block — it returns a job
+ * id immediately and the job runs CONCURRENTLY with the rest of the turn and the
+ * session. The agent uses it for long-running, self-contained work it does not
+ * want to wait on inline; the human watches it with `/jobs` and `/logs`, and any
+ * side effect the job takes still requires a foreground approval.
+ */
+export const RUN_IN_BACKGROUND_TOOL_NAME = "run_in_background";
+const parameters = z.object({
+    task: z
+        .string()
+        .min(1)
+        .describe("The complete, self-contained task for the background job. It starts with " +
+        "NO context beyond this text — include every path, constraint, and expected " +
+        "output. The job runs concurrently; you get a job id back immediately."),
+    tools: z
+        .array(z.string().min(1))
+        .nonempty()
+        .optional()
+        .describe("Tool names to grant the job — a subset of your own. Omit for the default " +
+        "read-only set. Grant write/shell tools only when the job needs them; every " +
+        "side effect still pauses for a foreground human approval."),
+    root: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Workspace root name (from your Environment) to confine the job's writes to. " +
+        "Omit for a read-only job or a single-root workspace."),
+    maxIterations: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Cap on the job's model turns (clamped to the configured ceiling)."),
+    maxTokens: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Cap on the job's total tokens (clamped to the configured ceiling)."),
+});
+/** Build the `run_in_background` tool bound to the session's job manager. */
+export function makeRunInBackgroundTool(manager) {
+    return {
+        name: RUN_IN_BACKGROUND_TOOL_NAME,
+        description: "Dispatch a self-contained task to run as a BACKGROUND JOB, concurrently with " +
+            "the rest of this session. Returns a job id immediately (non-blocking) — the " +
+            "job runs on its own while you continue. Use it for long or independent work " +
+            "you don't need to wait on inline (e.g. \"run the full test suite and fix any " +
+            "failures\"). The job's output goes to a log (the user reads it with /logs); any " +
+            "file/shell action it takes pauses for the user's approval. For a subtask whose " +
+            "RESULT you need before continuing, use spawn_subagent (which blocks) instead.",
+        parameters,
+        async execute(input) {
+            const spec = {
+                task: input.task,
+                ...(input.tools ? { tools: input.tools } : {}),
+                ...(input.root !== undefined ? { root: input.root } : {}),
+                budget: {
+                    ...(input.maxIterations !== undefined
+                        ? { maxIterations: input.maxIterations }
+                        : {}),
+                    ...(input.maxTokens !== undefined
+                        ? { maxTokens: input.maxTokens }
+                        : {}),
+                },
+            };
+            let view;
+            try {
+                view = manager.dispatch(spec);
+            }
+            catch (err) {
+                // Disabled / job-limit / unknown-root are the model's to correct — feed
+                // the coded, actionable message back as a tool error, never a stack.
+                if (CruxyError.is(err)) {
+                    return {
+                        ok: false,
+                        error: `${err.code}: ${err.title}${err.cause ? ` — ${err.cause}` : ""}`,
+                    };
+                }
+                throw err;
+            }
+            return {
+                ok: true,
+                output: JSON.stringify({
+                    jobId: view.id,
+                    status: view.status,
+                    note: "dispatched — runs in the background; check with /jobs and /logs",
+                }),
+            };
+        },
+    };
+}

package/dist/jobs/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./log-buffer.js";
+export * from "./log-renderer.js";
+export * from "./approval-queue.js";
+export * from "./manager.js";
+export * from "./dispatch-tool.js";

package/dist/jobs/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./log-buffer.js";
+export * from "./log-renderer.js";
+export * from "./approval-queue.js";
+export * from "./manager.js";
+export * from "./dispatch-tool.js";

package/dist/jobs/log-buffer.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A bounded ring buffer of a background job's log lines (C.28). A job runs
+ * non-interactively, so its progress isn't on screen — `cruxy logs <id>` reads
+ * it back here. Bounded so a chatty job cannot grow memory without limit: once
+ * `capacity` lines are held, the oldest roll off. When anything is dropped the
+ * buffer records how many, so a reader is never misled into thinking a truncated
+ * tail is the whole story (`cruxy logs` prints an honest "… N earlier lines").
+ */
+export interface LogLine {
+    /** Milliseconds since the job started (monotonic, injected — never wall clock
+     * inside the buffer, so it stays deterministic and testable). */
+    atMs: number;
+    /** `out` for normal progress, `err` for diagnostics/failures. */
+    stream: "out" | "err";
+    /** The line text (no trailing newline). */
+    text: string;
+}
+export declare class LogBuffer {
+    private readonly capacity;
+    private readonly lines;
+    private droppedCount;
+    constructor(capacity: number);
+    /** Append a line, rolling the oldest off (and counting it) when at capacity. */
+    append(line: LogLine): void;
+    /** The retained lines, oldest-first (a copy — callers never mutate the buffer). */
+    snapshot(): LogLine[];
+    /** How many lines rolled off the front (0 when nothing was dropped). */
+    get dropped(): number;
+    /** Lines currently retained. */
+    get size(): number;
+}

package/dist/jobs/log-buffer.js

@@ -0,0 +1,30 @@
+export class LogBuffer {
+    capacity;
+    lines = [];
+    droppedCount = 0;
+    constructor(capacity) {
+        // A non-positive capacity would drop everything; clamp to at least 1 so a
+        // misconfigured buffer still shows the most recent line.
+        this.capacity = Math.max(1, Math.floor(capacity));
+    }
+    /** Append a line, rolling the oldest off (and counting it) when at capacity. */
+    append(line) {
+        this.lines.push(line);
+        while (this.lines.length > this.capacity) {
+            this.lines.shift();
+            this.droppedCount++;
+        }
+    }
+    /** The retained lines, oldest-first (a copy — callers never mutate the buffer). */
+    snapshot() {
+        return [...this.lines];
+    }
+    /** How many lines rolled off the front (0 when nothing was dropped). */
+    get dropped() {
+        return this.droppedCount;
+    }
+    /** Lines currently retained. */
+    get size() {
+        return this.lines.length;
+    }
+}

package/dist/jobs/log-renderer.d.ts

@@ -0,0 +1,32 @@
+import { type Theme } from "../theme/index.js";
+import type { RenderCapabilities, StreamRenderer, ToolLifecycleEvent } from "../render/index.js";
+/**
+ * A {@link StreamRenderer} for a background job (C.28) that captures activity into
+ * the job's log buffer and writes NOTHING to any terminal — a job runs
+ * non-interactively, off screen, and its foreground session owns the terminal.
+ * `cruxy logs <id>` (a REPL `/logs`) reads back what was captured here.
+ *
+ * Assistant text is accumulated and flushed a line at a time on `endSegment`;
+ * committed chrome notes and tool-call completions are captured verbatim. The
+ * live-region methods (status, phase, progress, prompt-resolved) are dropped —
+ * transient decor has no meaning in an append-only log.
+ */
+export declare class JobLogRenderer implements StreamRenderer {
+    private readonly sink;
+    readonly caps: RenderCapabilities;
+    readonly theme: Theme;
+    private pending;
+    constructor(sink: (stream: "out" | "err", text: string) => void);
+    beginTurn(): void;
+    write(delta: string): void;
+    endSegment(): void;
+    note(text: string): void;
+    toolLifecycle(event: ToolLifecycleEvent): void;
+    endTurn(): void;
+    preview(): void;
+    status(): void;
+    setPhase(): void;
+    progress(): void;
+    promptResolved(): void;
+    close(): void;
+}

package/dist/jobs/log-renderer.js

@@ -0,0 +1,70 @@
+import { themeForColor } from "../theme/index.js";
+/** Non-terminal capabilities: a background job renders to NOTHING on screen. */
+const OFFSCREEN_CAPS = {
+    tty: false,
+    color: false,
+    cursor: false,
+    spinner: false,
+    reducedMotion: true,
+    screenReader: false,
+    unicode: true,
+    width: 80,
+};
+/**
+ * A {@link StreamRenderer} for a background job (C.28) that captures activity into
+ * the job's log buffer and writes NOTHING to any terminal — a job runs
+ * non-interactively, off screen, and its foreground session owns the terminal.
+ * `cruxy logs <id>` (a REPL `/logs`) reads back what was captured here.
+ *
+ * Assistant text is accumulated and flushed a line at a time on `endSegment`;
+ * committed chrome notes and tool-call completions are captured verbatim. The
+ * live-region methods (status, phase, progress, prompt-resolved) are dropped —
+ * transient decor has no meaning in an append-only log.
+ */
+export class JobLogRenderer {
+    sink;
+    caps = OFFSCREEN_CAPS;
+    theme = themeForColor(false);
+    pending = "";
+    constructor(sink) {
+        this.sink = sink;
+    }
+    beginTurn() {
+        this.pending = "";
+    }
+    write(delta) {
+        this.pending += delta;
+        // Flush any complete lines immediately; keep the trailing partial line.
+        const nl = this.pending.lastIndexOf("\n");
+        if (nl === -1)
+            return;
+        const complete = this.pending.slice(0, nl);
+        this.pending = this.pending.slice(nl + 1);
+        for (const line of complete.split("\n"))
+            this.sink("out", line);
+    }
+    endSegment() {
+        if (this.pending.trim())
+            this.sink("out", this.pending.trimEnd());
+        this.pending = "";
+    }
+    note(text) {
+        this.sink("out", text);
+    }
+    toolLifecycle(event) {
+        if (event.event !== "end")
+            return; // only the committed outcome is log-worthy
+        const mark = event.ok ? "ok" : "fail";
+        this.sink(event.ok ? "out" : "err", `[${mark}] ${event.label}`);
+    }
+    endTurn() {
+        this.endSegment();
+    }
+    // Transient decor / previews have no place in an append-only job log.
+    preview() { }
+    status() { }
+    setPhase() { }
+    progress() { }
+    promptResolved() { }
+    close() { }
+}

package/dist/jobs/manager.d.ts

@@ -0,0 +1,139 @@
+import type { Provider } from "@cruxy/sdk";
+import { runAgent } from "../agent/loop.js";
+import { type ApprovalMutex, type PromptIO } from "../approval/index.js";
+import type { CruxyConfig } from "../config/index.js";
+import type { Router } from "../routing/index.js";
+import type { SandboxService } from "../sandbox/index.js";
+import { Semaphore } from "../subagent/index.js";
+import type { ToolRegistry } from "../tools/index.js";
+import type { logger as Logger } from "../utils/logger.js";
+import { Workspace } from "../workspace/index.js";
+import { ApprovalQueue } from "./approval-queue.js";
+import type { JobLog, JobSpec, JobView } from "./types.js";
+/**
+ * Everything the manager needs from the surrounding session, injected by the
+ * session factory. The SHARED members are the crux of C.28's "one system, not
+ * two": `semaphore`, `approvalQueue`, and `approvalMutex` are the SAME instances
+ * the foreground loop and subagents use, so a job contends for the one execution
+ * cap and serializes its prompts/checkpoints on the one mutex — never a parallel
+ * universe with its own limits.
+ */
+export interface JobManagerDeps {
+    config: CruxyConfig;
+    provider: Provider;
+    router?: Router;
+    /** The parent's registry — the ceiling every job's tool scope derives from. */
+    parentRegistry: ToolRegistry;
+    cwd: string;
+    workspace: Workspace;
+    logger: typeof Logger;
+    git?: {
+        branch: string;
+        dirty: boolean;
+    } | null;
+    projectInstructions?: string | null;
+    sandbox?: SandboxService;
+    /** The ONE execution semaphore, shared with subagents (JC-D, the shared cap). */
+    semaphore: Semaphore;
+    /** The ONE foreground pending-approval queue jobs produce onto. */
+    approvalQueue: ApprovalQueue;
+    /** The ONE approval mutex — job prompts/checkpoints serialize on it. */
+    approvalMutex: ApprovalMutex;
+    /**
+     * Whether an interactive foreground exists to service the queue. FALSE (a
+     * one-shot / piped run) means a job's gated action fails loud with
+     * `CRUXY_E_APPROVAL_REQUIRED` — it never auto-approves and never hangs on a
+     * human who will never come.
+     */
+    foregroundInteractive: boolean;
+    /** The shared prompt I/O used when the foreground services a job's request. */
+    promptIO: PromptIO;
+    /** Test seam: the loop driver. Defaults to the real {@link runAgent}. */
+    runAgentFn?: typeof runAgent;
+    /** Test seam: deterministic job ids. Defaults to `job-<seq>-<rand>`. */
+    idFactory?: () => string;
+    /** Test seam: log-line clock (ms). Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * Session-scoped background jobs (C.28). The main agent dispatches a job with
+ * `run_in_background`; it runs the SAME agent loop as a subagent but CONCURRENTLY
+ * with the foreground session, off screen (its output goes to a log buffer). A
+ * gated action pauses the job, releases its execution slot, and enqueues an
+ * approval request the foreground human services between turns; on approval the
+ * job re-acquires a slot (with priority) and runs on — its pre- AND post-pause
+ * mutations coalescing under ONE checkpoint. Cancel and session exit kill-tree a
+ * job's process tree (via its cancellation signal), leaving no orphan.
+ *
+ * The manager is session-scoped and dies with the session (NOT a daemon): nothing
+ * here persists a live registry across processes. What survives on disk is a
+ * job's checkpoint set, so `cruxy rollback <id>` still works afterwards.
+ */
+export declare class JobManager {
+    private readonly deps;
+    private readonly jobs;
+    /** In-flight executions, awaited on {@link cancelAll} so teardown completes. */
+    private readonly running;
+    private readonly idFactory;
+    private readonly now;
+    private readonly runAgentFn;
+    private seq;
+    constructor(deps: JobManagerDeps);
+    /**
+     * Dispatch a background job (the `run_in_background` seam). Fails loud when the
+     * feature is disabled, when the live-job ceiling is reached, or when a named
+     * root is unknown — all BEFORE the job is registered, so a refused dispatch
+     * leaves no ghost. Returns a view immediately; the job runs asynchronously.
+     */
+    dispatch(spec: JobSpec): JobView;
+    /** Live view of every job this session, dispatch order. */
+    list(): JobView[];
+    /** One job's view, or undefined if the id is unknown. */
+    get(id: string): JobView | undefined;
+    /** One job's full log (for `/logs <id>`). Fails loud on an unknown id. */
+    logs(id: string): JobLog;
+    /**
+     * Cancel one job: abort its run (kill-tree'ing any in-flight process via the
+     * signal reaching `ctx.signal`) and, if it is paused, withdraw its queued
+     * approval so it stops waiting. A checkpoint it already took SURVIVES for
+     * review/rollback. Fails loud on an unknown id; a no-op on an already-terminal
+     * job (returns false).
+     */
+    cancel(id: string): boolean;
+    /**
+     * Cancel EVERY live job (session exit / teardown) and AWAIT their teardown, so
+     * nothing is left running or orphaned. Returns how many were cancelled — the
+     * caller prints the honest "N job(s) cancelled". Idempotent.
+     */
+    cancelAll(reason: string): Promise<number>;
+    /** Jobs that are not yet terminal (queued + running + paused). */
+    liveCount(): number;
+    /** Whether any job is paused awaiting a foreground approval (drive the drain). */
+    hasPendingApprovals(): boolean;
+    /** Service every pending job approval on the foreground (called between turns). */
+    serviceApprovals(): Promise<number>;
+    /** Abort a job's run and unblock it if paused (shared by cancel/cancelAll). */
+    private abort;
+    /** Drive one job to completion, mapping every outcome onto its status. */
+    private execute;
+    /** Build the {@link runAgent} args for a job: scoped registry, budget, ctx. */
+    private runArgs;
+    /**
+     * The job's approval gate — the producer side of the pending-approval queue.
+     * A read-tier action passes freely. A mutate/destructive action with NO
+     * interactive foreground fails loud (never auto-approve, never hang). Otherwise
+     * the job PAUSES: it releases its execution slot (JC-D), enqueues the request
+     * for the foreground human, and blocks. On resolution it re-acquires a slot
+     * with PRIORITY (so it is not starved by work dispatched while it waited) and
+     * returns the decision. The real prompt + this job's checkpoint snapshot happen
+     * inside `finalize` on the foreground, serialized on the shared mutex.
+     */
+    private makeJobApproval;
+    /** Resolve a job's scope from an optional root name (fail-loud on unknown). */
+    private jobScope;
+    private statusFor;
+    private errorFor;
+    private requireJob;
+    private log;
+    private view;
+}