@cruxy/cli 0.23.0 → 0.25.0

package/dist/cli/commands/run.js

@@ -7,14 +7,14 @@ import { themeForColor } from "../../theme/index.js";
 import { summarizeRuns, renderSummary, } from "../../usage/index.js";
 import { CheckpointGate } from "../../checkpoint/index.js";
 import { SandboxService } from "../../sandbox/index.js";
-import { buildHooksService } from "../../hooks/index.js";
+import { buildHooksService, buildHooksRouter } from "../../hooks/index.js";
 import { runInteractive } from "../repl.js";
 import { buildAgentSession } from "../session-factory.js";
 import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
 import { resetLspServices } from "../../lsp/index.js";
-import { connectMcpTools, resetMcpServices } from "../../mcp/index.js";
+import { connectMcpTools, deferredSiblingServers, resetMcpServices, } from "../../mcp/index.js";
 import { defaultPromptIO } from "../../approval/index.js";
-import { buildWorkspace, singleRootWorkspace, } from "../../workspace/index.js";
+import { buildWorkspace, sessionWorkspace, } from "../../workspace/index.js";
 /**
  * Parse one repeatable `--root` value into a {@link RootSpec} and append it. Form
  * `name=path` (explicit name) or a bare `path` (basename-named by buildWorkspace).
@@ -59,7 +59,7 @@ export function runCommand() {
         // onboarding or the session starts, never a half-built session.
         const workspace = opts.root.length
             ? await buildWorkspace(opts.root, { cwd: invocationCwd })
-            : singleRootWorkspace(invocationCwd);
+            : sessionWorkspace(invocationCwd);
         const primaryRoot = workspace.primary().absPath;
         logger.info(t.muted(`model:   ${config.model.provider}/${config.model.model}`));
         logger.info(t.muted(`config:  ${sources.project ?? sources.global ?? "defaults"}`));
@@ -78,7 +78,7 @@ export function runCommand() {
                 ? "writes fan all roots (each checkpointed)"
                 : "writes scope to primary (checkpoints disabled)";
             logger.info(t.muted(`roots:   ${workspace.roots().length} (${names}); primary ${workspace.primary().name} — ` +
-                `reads fan all roots; ${writes}; hooks/MCP scope to primary this release`));
+                `reads fan all roots; ${writes}; hooks fan per trusted root; MCP loads from primary only this release`));
         }
         // First-run with no key (and a TTY) → guided onboarding instead of the
         // dead-end auth error. The first-win demo is offered only in the no-prompt
@@ -127,21 +127,46 @@ export function runCommand() {
             ? await SandboxService.create({
                 config,
                 cwd: primaryRoot,
+                // R5 (C.26): the command's root (primary — shell/test attribute to
+                // it this release) mounts read-write; every OTHER declared root
+                // mounts read-only. Cross-root write is only ever granted per-root
+                // via a named escalation, never blanket.
+                siblingRoots: workspace
+                    .roots()
+                    .filter((r) => !r.primary)
+                    .map((r) => r.absPath),
                 reporter: renderer,
             })
             : undefined;
         if (sandbox) {
             logger.info(t.muted(`sandbox: ${sandbox.runtimeName} (network ${config.sandbox.network})`));
         }
-        // Hooks + custom slash commands (C.19). Built once per run: loads the
-        // layered catalog and yields the lifecycle runner (threaded into the
-        // session) + the resolved custom slash commands (given to the REPL).
-        const hooksService = await buildHooksService({
-            cwd: primaryRoot,
-            config,
-            interactive: Boolean(process.stdin.isTTY),
-            logger,
-        });
+        // Hooks + custom slash commands (C.19). Single-root uses the unchanged
+        // service (byte-identical: one runner, lazy trust prompt). Multi-root
+        // (C.26 step 5) builds ONE runner per root behind a HookRouter — tool
+        // events fire the acting root's hooks, lifecycle events fan every trusted
+        // root. Untrusted roots are skipped and NAMED here (never a silent loss).
+        let hooksRunner;
+        let hookCommands;
+        if (workspace.isMultiRoot) {
+            const router = await buildHooksRouter({ workspace, config, logger });
+            hooksRunner = router.runner;
+            hookCommands = router.commands;
+            for (const u of router.untrustedHookRoots) {
+                logger.info(t.muted(`hooks:   root "${u.name}" has ${u.count} untrusted hook${u.count === 1 ? "" : "s"} — ` +
+                    `not firing (run \`cruxy hooks trust ${u.absPath}\`)`));
+            }
+        }
+        else {
+            const hooksService = await buildHooksService({
+                cwd: primaryRoot,
+                config,
+                interactive: Boolean(process.stdin.isTTY),
+                logger,
+            });
+            hooksRunner = hooksService.runner;
+            hookCommands = hooksService.commands;
+        }
         // MCP servers (C.27): connect + trust-gate BEFORE building the session so
         // the tool catalogue is complete when the model first runs. Off by
         // default (no servers connect). A non-interactive run with an untrusted
@@ -153,12 +178,29 @@ export function runCommand() {
             interactive: Boolean(process.stdin.isTTY),
             io: defaultPromptIO(shouldUseColor()),
         });
-        const session = buildAgentSession(config, apiKey, workspace, Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox, hooksService.runner, mcp.tools);
+        // MCP is primary-root only this release (JC-D). Name each sibling-root
+        // server individually — never one generic line, never a silent drop —
+        // so a user who declared `github` in a sibling knows exactly why its
+        // tools aren't present (and that root-qualified names are a follow-up).
+        if (workspace.isMultiRoot) {
+            for (const d of deferredSiblingServers(workspace)) {
+                logger.info(t.muted(`mcp:     server "${d.server}" declared in ${d.root} not loaded (primary-root MCP only this release)`));
+            }
+        }
+        const session = buildAgentSession(config, apiKey, workspace, Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox, hooksRunner, mcp.tools);
         if (interactive) {
             try {
-                await runInteractive(session, undefined, renderer, checkpoints, hooksService.commands);
+                await runInteractive(session, undefined, renderer, checkpoints, hookCommands);
             }
             finally {
+                // Background jobs (C.28): cancel every live job on session exit —
+                // kill-tree'ing each job's process group (no orphan) and reporting an
+                // honest "N job(s) cancelled". A paused job is cancelled too, but any
+                // checkpoint it took survives for review/rollback.
+                const cancelled = (await session.jobs?.cancelAll("session exit")) ?? 0;
+                if (cancelled > 0) {
+                    logger.print(t.muted(`${cancelled} background job${cancelled === 1 ? "" : "s"} cancelled on exit`));
+                }
                 // LSP (C.12) + MCP (C.27): gracefully shut down any external server
                 // processes spawned during the session (the shared process-exit
                 // kill-tree is the fail-safe for a hard kill).
@@ -182,6 +224,10 @@ export function runCommand() {
         }
         finally {
             renderer.close();
+            // Background jobs (C.28): a one-shot run has no between-turns servicing
+            // loop, so cancel every live job on exit (kill-tree, no orphan) rather
+            // than leave one paused forever. Checkpoints taken survive for rollback.
+            await session.jobs?.cancelAll("session exit");
             // LSP (C.12) + MCP (C.27): gracefully shut down any external server
             // processes spawned during the run (the shared process-exit kill-tree
             // is the fail-safe for a hard kill).

package/dist/cli/onboard.js

@@ -1,7 +1,7 @@
 import { resolveApiKey } from "../config/index.js";
 import { createDefaultDeps, defaultOnboardingIO, isFirstRun, runOnboarding, } from "../onboarding/index.js";
 import { createRenderer } from "../render/index.js";
-import { singleRootWorkspace } from "../workspace/index.js";
+import { sessionWorkspace } from "../workspace/index.js";
 import { buildAgentSession } from "./session-factory.js";
 /**
  * CLI-layer glue between the entry points and the onboarding module (U.6). Keeps
@@ -27,7 +27,7 @@ export async function runFirstWinTask(config, cwd, prompt) {
     const renderer = createRenderer();
     // The onboarding first-win is inherently single-root (it runs before any
     // `--root` is parsed), so it acts over a trivial workspace on its cwd.
-    const session = buildAgentSession(config, apiKey, singleRootWorkspace(cwd), true, false, renderer);
+    const session = buildAgentSession(config, apiKey, sessionWorkspace(cwd), true, false, renderer);
     try {
         await session.send(prompt, renderer);
     }

package/dist/cli/repl.d.ts

@@ -7,7 +7,7 @@ import { type StreamRenderer } from "../render/index.js";
  * The REPL's slash commands — the autocomplete candidate set (U.7). Keep in
  * sync with the dispatch below and the HELP text.
  */
-export declare const REPL_COMMANDS: readonly ["/help", "/clear", "/compact", "/reload", "/plan", "/exit", "/quit"];
+export declare const REPL_COMMANDS: readonly ["/help", "/clear", "/compact", "/reload", "/plan", "/jobs", "/logs", "/cancel", "/exit", "/quit"];
 /** The stdin/stdout pair the REPL reads from and prompts on. Injectable for tests. */
 export interface ReplIO {
     input: Readable;

package/dist/cli/repl.js

@@ -2,6 +2,7 @@ import readline from "node:readline";
 import { makeReplCompleter } from "../components/index.js";
 import { resolveSlash } from "../hooks/index.js";
 import { runGatedShell } from "../tools/shell/exec.js";
+import { addRootToWorkspace } from "../workspace/index.js";
 import { themeForColor } from "../theme/index.js";
 import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
 import { createRenderer } from "../render/index.js";
@@ -19,6 +20,9 @@ export const REPL_COMMANDS = [
     "/compact",
     "/reload",
     "/plan",
+    "/jobs",
+    "/logs",
+    "/cancel",
     "/exit",
     "/quit",
 ];
@@ -28,6 +32,9 @@ const HELP = `Commands:
   /compact       summarize older history to free up context now
   /reload        re-read project instructions (CRUXY.md)
   /plan          toggle plan mode (propose a plan before executing)
+  /jobs          list background jobs and their status
+  /logs <id>     show a background job's log
+  /cancel <id>   cancel a background job
   /exit, /quit   leave cruxy
   Ctrl+D         leave cruxy`;
 const defaultIO = () => ({
@@ -113,6 +120,123 @@ function printReplError(err) {
         color: shouldUseColor(process.stdout),
     }));
 }
+/**
+ * `/add-root <name> <path>` (C.26 step 5) — an explicit, human-only way to
+ * declare another workspace root. This is a REPL command, NOT a model tool: the
+ * model can only reach the tool registry, and nothing named `add_root` is
+ * registered there, so the allowlist argument is unchanged. It validates the
+ * addition (TTY-only; same existence/name/overlap refusal as `--root`) and, on
+ * success, tells the user to relaunch with `--root` to activate it — a
+ * mid-session hot-swap would leave the checkpoint gate + hook router (both wired
+ * from the session-start workspace) half-attributed, so activation is deferred
+ * to a clean relaunch. A newly declared root always starts untrusted.
+ */
+async function handleAddRoot(input, session) {
+    const parts = input
+        .slice("/add-root".length)
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+    if (parts.length !== 2) {
+        logger.print(theme.muted("usage: /add-root <name> <path>"));
+        return;
+    }
+    const [name, rootPath] = parts;
+    const ctx = session.toolContext;
+    const current = ctx.workspace;
+    try {
+        const next = await addRootToWorkspace(current, { name, path: rootPath }, { cwd: ctx.cwd, tty: Boolean(process.stdin.isTTY) });
+        const abs = next.rootByName(name).absPath;
+        logger.print(theme.muted(`validated root "${name}" (${abs}). relaunch with \`--root ${name}=${rootPath}\` to activate it — ` +
+            `it starts untrusted (its hooks and project memory stay inert until you run \`cruxy hooks/memory trust\`).`));
+    }
+    catch (err) {
+        printReplError(err);
+    }
+}
+/**
+ * Service any background-job approvals that piled up (C.28) — the auto-surface
+ * point. Called when the foreground is idle (between turns), so a paused job's
+ * gated action is decided through the SAME U.3 prompt as a foreground one, one at
+ * a time. No pending → a no-op (nothing printed). The job resumes on approval.
+ */
+async function drainJobApprovals(session) {
+    const jobs = session.jobs;
+    if (!jobs || !jobs.hasPendingApprovals())
+        return;
+    logger.print(theme.muted(`\n${theme.glyph.bullet} a background job needs your approval:`));
+    await jobs.serviceApprovals();
+}
+/** Render the background-job list (`/jobs`). */
+function handleJobsList(session) {
+    const jobs = session.jobs;
+    if (!jobs) {
+        logger.print(theme.muted("background jobs are disabled — enable with `cruxy config set jobs.enabled true`"));
+        return;
+    }
+    const list = jobs.list();
+    if (list.length === 0) {
+        logger.print(theme.muted("no background jobs this session"));
+        return;
+    }
+    for (const j of list) {
+        const status = j.status === "failed" ? theme.danger(j.status) : theme.accent(j.status);
+        const pending = j.pendingApproval
+            ? theme.muted(` — needs approval: ${j.pendingApproval}`)
+            : "";
+        const err = j.error ? theme.muted(` (${j.error})`) : "";
+        logger.print(`${theme.strong(j.id)}  ${status}  ${j.label}${pending}${err}`);
+    }
+}
+/** Print one job's log (`/logs <id>`). */
+function handleJobLogs(input, session) {
+    const jobs = session.jobs;
+    if (!jobs) {
+        logger.print(theme.muted("background jobs are disabled"));
+        return;
+    }
+    const id = input.slice("/logs".length).trim();
+    if (!id) {
+        logger.print(theme.muted("usage: /logs <id>"));
+        return;
+    }
+    try {
+        const log = jobs.logs(id);
+        if (log.dropped > 0) {
+            logger.print(theme.muted(`… ${log.dropped} earlier line(s) rolled off`));
+        }
+        for (const line of log.lines) {
+            const text = line.stream === "err" ? theme.danger(line.text) : line.text;
+            logger.print(text);
+        }
+        logger.print(theme.muted(`(${log.status})`));
+    }
+    catch (err) {
+        printReplError(err);
+    }
+}
+/** Cancel a job (`/cancel <id>`). */
+async function handleJobCancel(input, session) {
+    const jobs = session.jobs;
+    if (!jobs) {
+        logger.print(theme.muted("background jobs are disabled"));
+        return;
+    }
+    const id = input.slice("/cancel".length).trim();
+    if (!id) {
+        logger.print(theme.muted("usage: /cancel <id>"));
+        return;
+    }
+    try {
+        const cancelled = jobs.cancel(id);
+        logger.print(theme.muted(cancelled
+            ? `cancelling ${id} (its process tree is killed; any checkpoint survives for rollback)`
+            : `${id} is already finished`));
+    }
+    catch (err) {
+        printReplError(err);
+    }
+}
 /**
  * Drive an interactive multi-turn session: prompt, read a line, dispatch slash
  * commands or run a turn, repeat. Assistant text and tool-call progress stream
@@ -135,6 +259,11 @@ export async function runInteractive(session, io = defaultIO(), renderer = creat
 }
 async function replLoop(session, io, renderer, checkpoints, slashCommands = []) {
     for (;;) {
+        // Auto-surface (C.28): before prompting, service any background-job approvals
+        // that piled up while the last turn ran — one at a time, through the same U.3
+        // prompt. Done here (foreground idle, no readline interface live) so a job's
+        // prompt never contends with the line reader.
+        await drainJobApprovals(session);
         const line = await readLine(io, PROMPT);
         // EOF / Ctrl+D.
         if (line === null) {
@@ -182,6 +311,22 @@ async function replLoop(session, io, renderer, checkpoints, slashCommands = [])
             logger.print(HELP);
             continue;
         }
+        if (trimmed === "/jobs") {
+            handleJobsList(session);
+            continue;
+        }
+        if (trimmed === "/logs" || trimmed.startsWith("/logs ")) {
+            handleJobLogs(trimmed, session);
+            continue;
+        }
+        if (trimmed === "/cancel" || trimmed.startsWith("/cancel ")) {
+            await handleJobCancel(trimmed, session);
+            continue;
+        }
+        if (trimmed === "/add-root" || trimmed.startsWith("/add-root ")) {
+            await handleAddRoot(trimmed, session);
+            continue;
+        }
         // Custom slash commands (C.19) — consulted AFTER builtins, so a custom
         // command can never shadow /help, /exit, etc. A `prompt` command expands to
         // text fed to the agent (safe); a `shell` command runs through the SAME

package/dist/cli/session-factory.d.ts

@@ -1,21 +1,35 @@
 import type { CruxyConfig } from "../config/index.js";
-import type { ApprovalDecision } from "../approval/index.js";
+import { withCheckpointGate } from "../checkpoint/index.js";
 import type { CheckpointGate } from "../checkpoint/index.js";
+export { withCheckpointGate };
 import type { SandboxService } from "../sandbox/index.js";
 import type { StreamRenderer } from "../render/index.js";
-import { type ApproveAction, type Tool } from "../tools/index.js";
+import { ToolRegistry, type Tool } from "../tools/index.js";
 import { Session, type LifecycleHookRunner } from "../agent/index.js";
 import type { Workspace } from "../workspace/index.js";
 /**
- * Wrap the approval gate with the C.32 auto-checkpoint hook. Ordering is the
- * whole point: a tool mutates only *after* `requestApproval` resolves, so
- * snapshotting after an `allow` decision but before returning it means the
- * checkpoint always lands before the run's first mutation — and a denied
- * action never creates one. The same seam records which paths the run touched
- * (file actions) or that attribution is lost (shell), for rollback's
- * external-change detection.
+ * Register every CONDITIONALLY-enabled runtime tool onto `registry`, in the fixed
+ * order the model sees them: `remember` (memory), the four LSP tools, the two web
+ * tools, the trusted MCP tools, then `spawn_subagent`. Factored out of
+ * {@link buildAgentSession} for ONE reason beyond tidiness: it makes the *complete
+ * runtime* tool set enumerable by a test (JC-B). The default registry only covers
+ * the 14 always-on tools; the allowlist test that pins "no tool can add a workspace
+ * root" is only sound if it runs against the SAME set the session ships — so the
+ * session factory and that test both build the surface through this one seam. A new
+ * conditionally-registered tool added here fails the allowlist test until it is
+ * consciously listed and audited.
+ *
+ * Each family is opt-in and inert when its feature flag is off, exactly as before —
+ * this function is a pure move of the inline registration, same guards, same order.
+ * `spawnTool` is passed in (already depth-bound) because it needs the orchestrator;
+ * it registers only when nesting is allowed (`subagent.maxDepth > 0`).
  */
-export declare function withCheckpointGate(requestApproval: (action: ApproveAction) => Promise<ApprovalDecision>, gate: CheckpointGate | undefined, ws: Workspace): (action: ApproveAction) => Promise<ApprovalDecision>;
+export declare function registerRuntimeTools(registry: ToolRegistry, config: CruxyConfig, opts?: {
+    mcpTools?: Tool[];
+    spawnTool?: Tool;
+    spawnManyTool?: Tool;
+    jobTool?: Tool;
+}): void;
 /**
  * Build a ready-to-run agent {@link Session} from a resolved key — the wiring
  * shared by `cruxy run` and the onboarding first-win task (so they can't drift).