@cruxy/cli 0.7.0 → 0.9.0

package/dist/subagent/orchestrator.js

@@ -0,0 +1,241 @@
+import path from "node:path";
+import { runAgent } from "../agent/loop.js";
+import { CruxyError, ErrorCode, messageOf, subagentDepthExceeded, } from "../errors/index.js";
+import { Budget, resolveBudget } from "./budget.js";
+import { scopeRegistry } from "./registry-scope.js";
+import { makeSpawnSubagentTool } from "./spawn-tool.js";
+/** Longest task excerpt shown in render chrome — display, not record. */
+const LABEL_MAX = 60;
+/**
+ * Spawns subagents (C.14): the existing agent loop re-driven over isolated
+ * state. Each spawn builds a fresh history seeded with only the task, a
+ * scoped-down registry, a fresh approval gate, and a hard budget, runs
+ * `runAgent` to completion (or cap), and folds the outcome into a compact
+ * {@link SubagentResult}. The child transcript is dropped here — the parent
+ * never sees it.
+ *
+ * Spawns are sequential by construction: the loop awaits each tool call, so
+ * two spawn requests in one turn run one after the other in deterministic
+ * order. Parallel fan-out is C.33's job — `spawn` is a self-contained async
+ * unit with no cross-spawn state, so it slots in without reshaping this class.
+ */
+export class SubagentOrchestrator {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Run one subagent to completion. `parentDepth` is the spawner's depth (the
+     * main agent is 0); spawning past `subagent.maxDepth` throws
+     * `CRUXY_E_SUBAGENT_DEPTH_EXCEEDED` — the spawn tool is also structurally
+     * withheld at the cap, so this throw is the fail-loud backstop.
+     *
+     * Never rejects on a *child* failure — provider or tool crashes come back as
+     * `status: "failed"` for the parent to reason over. The two exceptions that
+     * do propagate: the depth cap (above) and `CRUXY_E_APPROVAL_REQUIRED`
+     * (non-interactive default-deny must reach the boundary, U.3 — a subagent is
+     * not a way to swallow it).
+     */
+    async spawn(spec, parentDepth) {
+        const { deps } = this;
+        const { maxDepth, defaultBudget } = deps.config.subagent;
+        if (parentDepth >= maxDepth) {
+            throw subagentDepthExceeded(parentDepth, maxDepth);
+        }
+        const childDepth = parentDepth + 1;
+        // Scoped-down registry (throws on a tool the parent lacks — the spawn tool
+        // surfaces that to the model), plus a depth-bound spawn tool only while
+        // nesting is still allowed.
+        const registry = scopeRegistry(deps.parentRegistry, spec.tools);
+        if (childDepth < maxDepth) {
+            registry.register(makeSpawnSubagentTool(this, childDepth));
+        }
+        const budget = new Budget(resolveBudget(defaultBudget, spec.budget));
+        // Fresh gate per child (own allowlist), recording what it approves so the
+        // result can name the artifacts without ever shipping the transcript.
+        const approve = deps.makeChildApproval();
+        const artifacts = new Set();
+        const ctx = {
+            cwd: deps.cwd,
+            config: deps.config,
+            logger: deps.logger,
+            requestApproval: async (action) => {
+                const decision = await approve(action);
+                if (decision.allow)
+                    recordArtifacts(action, artifacts, deps.cwd);
+                return decision;
+            },
+        };
+        const label = taskLabel(spec.task);
+        deps.renderer?.note(`⏵ subagent: ${label}`);
+        deps.renderer?.setPhase({ kind: "subagent", label });
+        // The isolation seam: a brand-new history seeded with ONLY the task. The
+        // parent's messages are never in scope here, and this array dies with the
+        // spawn — only the structured result below leaves this function.
+        const messages = [{ role: "user", content: spec.task }];
+        let run;
+        try {
+            run = await runAgent({
+                messages,
+                provider: deps.provider,
+                registry,
+                config: deps.config,
+                ctx,
+                renderer: deps.renderer
+                    ? new SubagentRenderer(deps.renderer, label)
+                    : undefined,
+                git: deps.git,
+                projectInstructions: deps.projectInstructions,
+                subagent: true,
+                budget,
+            });
+        }
+        catch (err) {
+            // Non-interactive default-deny is the boundary's to report, not ours.
+            if (CruxyError.is(err) && err.code === ErrorCode.ApprovalRequired) {
+                deps.renderer?.setPhase(null);
+                throw err;
+            }
+            deps.renderer?.note(`✗ subagent failed: ${label}`);
+            deps.renderer?.setPhase(null);
+            return {
+                status: "failed",
+                summary: "",
+                ...artifactsField(artifacts),
+                error: `${ErrorCode.SubagentFailed}: ${messageOf(err) ?? "unknown error"}`,
+                iterations: 0,
+                usage: { input_tokens: 0, output_tokens: 0 },
+            };
+        }
+        deps.renderer?.setPhase(null);
+        const result = this.toResult(run, artifacts, label);
+        deps.logger.debug(`subagent ${result.status}: ${result.iterations} turn(s), tokens in/out ` +
+            `${result.usage.input_tokens}/${result.usage.output_tokens} — ${label}`);
+        return result;
+    }
+    /** Map the child's AgentResult to the structured, transcript-free shape. */
+    toResult(run, artifacts, label) {
+        const summary = lastAssistantText(run.messages);
+        const base = {
+            summary,
+            ...artifactsField(artifacts),
+            iterations: run.iterations,
+            usage: run.usage,
+        };
+        if (run.stop === "completed") {
+            this.deps.renderer?.note(`✓ subagent done: ${label}`);
+            return { status: "done", ...base };
+        }
+        // Both cap paths are the same outcome for the parent: a truncated, partial
+        // result with the reason — informational, never fatal (the parent decides
+        // what to do with it).
+        const reason = run.stop === "budget"
+            ? (run.stopReason ?? "budget cap reached")
+            : `agent.maxIterations ceiling reached (${this.deps.config.agent.maxIterations})`;
+        this.deps.renderer?.note(`✗ subagent stopped (budget): ${label}`);
+        return {
+            status: "budget-exceeded",
+            ...base,
+            error: `${ErrorCode.SubagentBudget}: ${reason}`,
+        };
+    }
+}
+/** One-line task excerpt for chrome (live phase, trail notes). */
+function taskLabel(task) {
+    const flat = task.replace(/\s+/g, " ").trim();
+    return flat.length > LABEL_MAX ? flat.slice(0, LABEL_MAX - 1) + "…" : flat;
+}
+/** `artifacts` only when non-empty — absent beats `[]` in the parent's context. */
+function artifactsField(artifacts) {
+    return artifacts.size > 0 ? { artifacts: [...artifacts].sort() } : {};
+}
+/**
+ * Record the paths an *approved* mutating action targets, project-relative.
+ * Shell commands carry no per-file attribution (same limitation C.32 records);
+ * they contribute no artifact entries.
+ */
+function recordArtifacts(action, artifacts, cwd) {
+    if (action.path) {
+        artifacts.add(path.relative(cwd, action.path) || action.path);
+    }
+    if (action.preview?.type === "patch") {
+        for (const file of action.preview.files)
+            artifacts.add(file.path);
+    }
+}
+/** The child's final assistant text — the summary the parent receives. */
+function lastAssistantText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg.role !== "assistant")
+            continue;
+        if (typeof msg.content === "string") {
+            if (msg.content.trim())
+                return msg.content.trim();
+            continue;
+        }
+        const text = msg.content
+            .filter((block) => block.type === "text")
+            .map((block) => block.text)
+            .join("\n")
+            .trim();
+        if (text)
+            return text;
+    }
+    return "";
+}
+/**
+ * The child's view of the ONE render path (U.4): a decorator over the parent's
+ * renderer, not a second implementation. Child assistant text is dropped — it
+ * is not user transcript; it returns to the parent as the structured summary.
+ * Child activity folds into the live region and trail with a `subagent ·`
+ * prefix, and the child's thinking phase keeps the task label on screen.
+ * Approval plumbing (`awaiting-approval`, previews, `promptResolved`) passes
+ * through untouched — the U.3 prompt renders identically inside a subagent.
+ */
+class SubagentRenderer {
+    caps;
+    inner;
+    label;
+    constructor(inner, label) {
+        this.inner = inner;
+        this.label = label;
+        this.caps = inner.caps;
+    }
+    /** Turn framing belongs to the parent's turn — the child's is dropped. */
+    beginTurn() { }
+    endTurn() { }
+    /** Child assistant text is result data, not transcript — dropped. */
+    write() { }
+    endSegment() { }
+    note(text) {
+        this.inner.note(`subagent · ${text}`);
+    }
+    preview(preview) {
+        this.inner.preview(preview);
+    }
+    status(text) {
+        this.inner.status(text);
+    }
+    setPhase(phase) {
+        // Keep the task on the live line while the child thinks; everything else
+        // (tool phases via toolLifecycle, approval yields) passes through.
+        if (phase?.kind === "thinking") {
+            this.inner.setPhase({ kind: "subagent", label: this.label });
+            return;
+        }
+        if (phase === null)
+            return; // the orchestrator owns clearing
+        this.inner.setPhase(phase);
+    }
+    /** The plan executor owns the progress register (C.31) — never the child. */
+    progress() { }
+    toolLifecycle(event) {
+        this.inner.toolLifecycle({ ...event, label: `subagent · ${event.label}` });
+    }
+    promptResolved() {
+        this.inner.promptResolved();
+    }
+    /** The parent owns the renderer's lifetime. */
+    close() { }
+}

package/dist/subagent/registry-scope.d.ts

@@ -0,0 +1,28 @@
+import { ToolRegistry } from "../tools/index.js";
+/**
+ * Child tool-registry derivation (C.14). The one rule: a subagent's toolset is
+ * scoped DOWN from its parent's, never up. Enforcement is structural — the
+ * child registry is built exclusively from `parent.get(name)` lookups, so a
+ * tool the parent lacks is unobtainable, not merely denied.
+ */
+/** The spawn tool's registered name (excluded from every scoped child set —
+ * the orchestrator re-adds a depth-bound instance only while depth allows). */
+export declare const SPAWN_SUBAGENT_TOOL_NAME = "spawn_subagent";
+/**
+ * The default child toolset: read-only investigation plus skills. Mirrors the
+ * C.31 propose-phase set — no writes, no shell, no VCS unless the parent
+ * explicitly grants them at spawn (and holds them itself).
+ */
+export declare const DEFAULT_SUBAGENT_TOOLS: readonly string[];
+/**
+ * Build a child registry as a strict subset of `parent`.
+ *
+ * - No `requested` → the intersection of {@link DEFAULT_SUBAGENT_TOOLS} with
+ *   what the parent actually has (a scoped parent scopes its children further).
+ * - With `requested` → every name must exist in the parent; an unavailable
+ *   name **throws** (fail loud — the spawn tool surfaces it to the model as a
+ *   tool error so it can self-correct, exactly like invalid arguments).
+ * - `spawn_subagent` is always stripped: nesting is the orchestrator's
+ *   decision (depth-capped), never a scope grant.
+ */
+export declare function scopeRegistry(parent: ToolRegistry, requested?: readonly string[]): ToolRegistry;

package/dist/subagent/registry-scope.js

@@ -0,0 +1,63 @@
+import { ToolRegistry } from "../tools/index.js";
+/**
+ * Child tool-registry derivation (C.14). The one rule: a subagent's toolset is
+ * scoped DOWN from its parent's, never up. Enforcement is structural — the
+ * child registry is built exclusively from `parent.get(name)` lookups, so a
+ * tool the parent lacks is unobtainable, not merely denied.
+ */
+/** The spawn tool's registered name (excluded from every scoped child set —
+ * the orchestrator re-adds a depth-bound instance only while depth allows). */
+export const SPAWN_SUBAGENT_TOOL_NAME = "spawn_subagent";
+/**
+ * The default child toolset: read-only investigation plus skills. Mirrors the
+ * C.31 propose-phase set — no writes, no shell, no VCS unless the parent
+ * explicitly grants them at spawn (and holds them itself).
+ */
+export const DEFAULT_SUBAGENT_TOOLS = [
+    "list_files",
+    "read_file",
+    "glob",
+    "grep_files",
+    "git_status",
+    "search_codebase",
+    "list_skills",
+    "load_skill",
+];
+/**
+ * Build a child registry as a strict subset of `parent`.
+ *
+ * - No `requested` → the intersection of {@link DEFAULT_SUBAGENT_TOOLS} with
+ *   what the parent actually has (a scoped parent scopes its children further).
+ * - With `requested` → every name must exist in the parent; an unavailable
+ *   name **throws** (fail loud — the spawn tool surfaces it to the model as a
+ *   tool error so it can self-correct, exactly like invalid arguments).
+ * - `spawn_subagent` is always stripped: nesting is the orchestrator's
+ *   decision (depth-capped), never a scope grant.
+ */
+export function scopeRegistry(parent, requested) {
+    const child = new ToolRegistry();
+    if (requested === undefined) {
+        for (const name of DEFAULT_SUBAGENT_TOOLS) {
+            const tool = parent.get(name);
+            if (tool)
+                child.register(tool);
+        }
+        return child;
+    }
+    for (const name of new Set(requested)) {
+        if (name === SPAWN_SUBAGENT_TOOL_NAME)
+            continue;
+        const tool = parent.get(name);
+        if (!tool) {
+            const available = parent
+                .list()
+                .map((t) => t.name)
+                .filter((n) => n !== SPAWN_SUBAGENT_TOOL_NAME)
+                .join(", ");
+            throw new Error(`tool "${name}" is not available to grant a subagent (a subagent's tools ` +
+                `must be a subset of yours). Available: ${available}`);
+        }
+        child.register(tool);
+    }
+    return child;
+}

package/dist/subagent/spawn-tool.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+import type { Tool } from "../tools/index.js";
+import type { SubagentOrchestrator } from "./orchestrator.js";
+/**
+ * The `spawn_subagent` tool (C.14): the parent-facing seam for delegation. A
+ * normal tool on the same loop as everything else — no hidden control flow.
+ * Bound to the spawner's depth at construction, so the registry a tool lives
+ * on structurally encodes how much deeper nesting may go: at the configured
+ * cap the tool simply isn't registered.
+ */
+declare const parameters: z.ZodObject<{
+    task: z.ZodString;
+    tools: z.ZodOptional<z.ZodArray<z.ZodString, "atleastone">>;
+    maxIterations: z.ZodOptional<z.ZodNumber>;
+    maxTokens: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    task: string;
+    maxTokens?: number | undefined;
+    maxIterations?: number | undefined;
+    tools?: [string, ...string[]] | undefined;
+}, {
+    task: string;
+    maxTokens?: number | undefined;
+    maxIterations?: number | undefined;
+    tools?: [string, ...string[]] | undefined;
+}>;
+/** Build a `spawn_subagent` tool bound to `orchestrator` at `depth`. */
+export declare function makeSpawnSubagentTool(orchestrator: SubagentOrchestrator, depth: number): Tool<typeof parameters>;
+export {};

package/dist/subagent/spawn-tool.js

@@ -0,0 +1,94 @@
+import { z } from "zod";
+import { CruxyError, ErrorCode } from "../errors/index.js";
+import { SPAWN_SUBAGENT_TOOL_NAME } from "./registry-scope.js";
+/**
+ * The `spawn_subagent` tool (C.14): the parent-facing seam for delegation. A
+ * normal tool on the same loop as everything else — no hidden control flow.
+ * Bound to the spawner's depth at construction, so the registry a tool lives
+ * on structurally encodes how much deeper nesting may go: at the configured
+ * cap the tool simply isn't registered.
+ */
+const parameters = z.object({
+    task: z
+        .string()
+        .min(1)
+        .describe("The complete, self-contained subtask. The subagent starts with NO context " +
+        "beyond this text — include every path, constraint, and expected output."),
+    tools: z
+        .array(z.string().min(1))
+        .nonempty()
+        .optional()
+        .describe("Tool names to grant the subagent — must be a subset of your own tools. " +
+        "Omit for the default read-only set. Grant write/shell tools only when " +
+        "the subtask needs them; every side effect still requires user approval."),
+    maxIterations: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Cap on the subagent's model turns (clamped to the configured ceiling)."),
+    maxTokens: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Cap on the subagent's total tokens (clamped to the configured ceiling)."),
+});
+/** The compact wire shape fed back to the parent model. */
+function renderResult(result) {
+    return JSON.stringify({
+        status: result.status,
+        summary: result.summary,
+        ...(result.artifacts ? { artifacts: result.artifacts } : {}),
+        ...(result.error ? { error: result.error } : {}),
+        iterations: result.iterations,
+        tokens: {
+            input: result.usage.input_tokens,
+            output: result.usage.output_tokens,
+        },
+    });
+}
+/** Build a `spawn_subagent` tool bound to `orchestrator` at `depth`. */
+export function makeSpawnSubagentTool(orchestrator, depth) {
+    return {
+        name: SPAWN_SUBAGENT_TOOL_NAME,
+        description: "Delegate a bounded, self-contained subtask to a scoped subagent with its own " +
+            "fresh context, a restricted toolset, and a hard budget. It runs to completion " +
+            "and returns only a structured result (status, summary, artifacts) — its " +
+            "transcript is discarded. Use for independent subtasks whose details you don't " +
+            'need in your own context (e.g. "find where X is configured and report the paths").',
+        parameters,
+        async execute(input) {
+            const budget = {
+                ...(input.maxIterations !== undefined
+                    ? { maxIterations: input.maxIterations }
+                    : {}),
+                ...(input.maxTokens !== undefined
+                    ? { maxTokens: input.maxTokens }
+                    : {}),
+            };
+            let result;
+            try {
+                result = await orchestrator.spawn({ task: input.task, tools: input.tools, budget }, depth);
+            }
+            catch (err) {
+                // Non-interactive default-deny propagates to the boundary (U.3) —
+                // same behavior as every other gated tool.
+                if (CruxyError.is(err) && err.code === ErrorCode.ApprovalRequired) {
+                    throw err;
+                }
+                // Depth-exceed and scope violations are the model's to correct: feed
+                // the coded, actionable message back as a tool error.
+                const message = CruxyError.is(err)
+                    ? `${err.code}: ${err.title}${err.cause ? ` — ${err.cause}` : ""}`
+                    : err.message;
+                return { ok: false, error: message };
+            }
+            // A failed child is an is_error result (strong signal), still structured;
+            // budget-exceeded is informational — a partial result, not an error.
+            return result.status === "failed"
+                ? { ok: false, error: renderResult(result) }
+                : { ok: true, output: renderResult(result) };
+        },
+    };
+}

package/dist/subagent/types.d.ts

@@ -0,0 +1,55 @@
+import type { Usage } from "@cruxy/sdk";
+/**
+ * Types for subagent orchestration (C.14): the main agent delegates a bounded
+ * subtask to a child agent that runs the SAME loop with its own fresh history,
+ * a scoped-down tool registry, and a hard budget — then returns a structured
+ * result and discards its transcript. The parent reasons over the result only;
+ * context isolation is the whole point.
+ */
+/** Why a subagent run ended. Every path returns a result — never a hang. */
+export type SubagentStatus = "done" | "budget-exceeded" | "failed";
+/**
+ * Hard caps a subagent runs under. `maxIterations` and `maxTokens` are always
+ * finite — a subagent is bounded by construction; `timeoutMs` is an optional
+ * wall-clock backstop on top.
+ */
+export interface BudgetLimits {
+    /** Cap on the subagent's model turns. */
+    maxIterations: number;
+    /** Cap on the subagent's combined input+output tokens. */
+    maxTokens: number;
+    /** Optional wall-clock cap in milliseconds. */
+    timeoutMs?: number;
+}
+/** A spawn request: the bounded task plus optional scope/budget narrowing. */
+export interface SubagentSpec {
+    /** The complete, self-contained subtask the subagent should perform. */
+    task: string;
+    /**
+     * Tool names to grant, resolved against the *parent's* registry — a subagent
+     * can only ever scope DOWN. Omitted → the default read-only set.
+     */
+    tools?: readonly string[];
+    /**
+     * Budget overrides. Clamped to `subagent.defaultBudget` from config — a
+     * spawn can narrow its budget, never raise it past the configured ceilings.
+     */
+    budget?: Partial<BudgetLimits>;
+}
+/**
+ * What the parent gets back — compact structured data, never the transcript.
+ * `summary` is the subagent's final assistant message (partial when a budget
+ * tripped); `artifacts` are the project-relative paths the subagent was
+ * approved to mutate.
+ */
+export interface SubagentResult {
+    status: SubagentStatus;
+    summary: string;
+    artifacts?: string[];
+    /** Present on `budget-exceeded` / `failed`: the coded, actionable reason. */
+    error?: string;
+    /** Model turns the subagent consumed. */
+    iterations: number;
+    /** Token usage the subagent consumed (folded into the parent's accounting). */
+    usage: Usage;
+}

package/dist/subagent/types.js

@@ -0,0 +1 @@
+export {};

package/dist/tools/types.d.ts

@@ -76,6 +76,24 @@ export type ActionPreview =
     commitBody: string;
     prTitle: string;
     prBody: string;
+}
+/**
+ * The full blast radius of a checkpoint restore (C.32): every file rollback
+ * will recreate/revert/delete (as patch-style entries), plus the paths that
+ * changed since the checkpoint by something *other* than the tracked run —
+ * shown before the diff so the collapse cap can never hide them. Rollback
+ * covers working-tree files only; commits/pushes/PRs made during the run are
+ * out of scope (stated in the rendered note).
+ */
+ | {
+    type: "rollback";
+    checkpointId: string;
+    createdAt: string;
+    runSummary: string;
+    files: PatchFilePreview[];
+    externalPaths: string[];
+    /** The run executed shell commands, so per-file attribution is impossible. */
+    attributionUnknown: boolean;
 };
 /**
  * A side-effecting action a tool wants to take, passed to `ctx.approve`. The
@@ -83,12 +101,12 @@ export type ActionPreview =
  */
 export interface ApproveAction {
     /** The category of side effect being requested. */
-    kind: "write" | "edit" | "shell" | "patch" | "vcs";
+    kind: "write" | "edit" | "shell" | "patch" | "vcs" | "rollback";
     /** Absolute resolved path the action targets (write/edit). */
     path?: string;
     /** The command to run (shell). */
     command?: string;
-    /** Exact-change preview rendered above the prompt (write/edit/patch/vcs). */
+    /** Exact-change preview rendered above the prompt (write/edit/patch/vcs/rollback). */
     preview?: ActionPreview;
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {