@cruxy/cli 0.6.0 → 0.7.0

package/dist/plan/service.js

@@ -0,0 +1,118 @@
+import { planApprovalRequired, planInvalid, planRevisionLimit, } from "../errors/index.js";
+import { ToolRegistry } from "../tools/index.js";
+import { runAgent } from "../agent/loop.js";
+import { promptPlanDecision } from "./approve.js";
+import { executePlan } from "./execute.js";
+import { makeSubmitPlanTool } from "./submit-plan.js";
+/**
+ * Orchestrates a plan-mode turn (C.31): propose → approve/revise (capped) →
+ * execute, all on the ordinary agent loop. The propose phase runs with a
+ * read-only + `submit_plan` registry so the agent cannot act before approval;
+ * execution runs with the full registry, one step at a time, per-action U.3
+ * gating intact.
+ */
+/** Default cap on plan revisions before failing loud. */
+export const MAX_PLAN_REVISIONS = 3;
+/** Tools available during the propose phase (read-only) — plus `submit_plan`. */
+const PLAN_PHASE_TOOLS = new Set([
+    "list_files",
+    "read_file",
+    "glob",
+    "grep_files",
+    "git_status",
+    "search_codebase",
+    "list_skills",
+    "load_skill",
+]);
+/** Build the read-only + `submit_plan` registry for the propose phase. */
+function buildPlanPhaseRegistry(execRegistry, holder) {
+    const registry = new ToolRegistry();
+    for (const tool of execRegistry.list()) {
+        if (PLAN_PHASE_TOOLS.has(tool.name))
+            registry.register(tool);
+    }
+    registry.register(makeSubmitPlanTool(holder));
+    return registry;
+}
+export async function runPlanSession(args) {
+    // Fail loud before proposing — a plan is never auto-approved (U.3 discipline).
+    if (!args.interactive)
+        throw planApprovalRequired();
+    const maxRevisions = args.maxRevisions ?? MAX_PLAN_REVISIONS;
+    const usage = { input_tokens: 0, output_tokens: 0 };
+    let messages = args.messages;
+    let iterations = 0;
+    const accumulate = (r) => {
+        messages = r.messages;
+        usage.input_tokens += r.usage.input_tokens;
+        usage.output_tokens += r.usage.output_tokens;
+        iterations += r.iterations;
+    };
+    const finish = () => ({
+        messages,
+        iterations,
+        stop: "completed",
+        usage,
+    });
+    // ── propose / revise loop (capped) ─────────────────────────────────────────
+    let feedback = null;
+    for (let rev = 0; rev <= maxRevisions; rev++) {
+        if (feedback !== null) {
+            messages.push({
+                role: "user",
+                content: `Revise the plan based on this feedback, then call submit_plan again with the updated steps:\n\n${feedback}`,
+            });
+        }
+        const holder = { plan: null };
+        const planRegistry = buildPlanPhaseRegistry(args.execRegistry, holder);
+        accumulate(await runAgent({
+            messages,
+            provider: args.provider,
+            registry: planRegistry,
+            config: args.config,
+            ctx: args.ctx,
+            git: args.git,
+            projectInstructions: args.projectInstructions,
+            onText: args.onText,
+            planMode: true,
+        }));
+        if (!holder.plan) {
+            throw planInvalid("the model ended its turn without calling submit_plan");
+        }
+        const plan = holder.plan;
+        const decision = await promptPlanDecision(plan, args.io);
+        if (decision.kind === "abort") {
+            args.io.write("plan aborted — nothing was executed.\n");
+            return finish();
+        }
+        if (decision.kind !== "revise") {
+            if (decision.kind === "approve-grant") {
+                args.planPolicy.enableSafeStepGrants();
+            }
+            // Execute step-by-step, driving one agent turn per step against the full
+            // registry. Each step's actions still pass through the U.3 gate.
+            const runStep = async (step) => {
+                messages.push({
+                    role: "user",
+                    content: `The plan is approved. Do ONLY step ${step.id}: ${step.title}. ${step.rationale} ` +
+                        "Do not start any other step. When this step is complete, stop.",
+                });
+                accumulate(await runAgent({
+                    messages,
+                    provider: args.provider,
+                    registry: args.execRegistry,
+                    config: args.config,
+                    ctx: args.ctx,
+                    git: args.git,
+                    projectInstructions: args.projectInstructions,
+                    onText: args.onText,
+                }));
+            };
+            await executePlan(plan, { runStep, io: args.io });
+            return finish();
+        }
+        feedback = decision.feedback;
+    }
+    // Rejected past the cap without converging.
+    throw planRevisionLimit(maxRevisions);
+}

package/dist/plan/submit-plan.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import type { Tool } from "../tools/index.js";
+import type { PlanHolder } from "./types.js";
+declare const parameters: z.ZodObject<{
+    steps: z.ZodArray<z.ZodObject<{
+        title: z.ZodString;
+        rationale: z.ZodString;
+        kind: z.ZodEnum<["read", "mutate", "destructive"]>;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        kind: "read" | "mutate" | "destructive";
+        rationale: string;
+    }, {
+        title: string;
+        kind: "read" | "mutate" | "destructive";
+        rationale: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    steps: {
+        title: string;
+        kind: "read" | "mutate" | "destructive";
+        rationale: string;
+    }[];
+}, {
+    steps: {
+        title: string;
+        kind: "read" | "mutate" | "destructive";
+        rationale: string;
+    }[];
+}>;
+/** Build a `submit_plan` tool bound to `holder`, which captures the last plan. */
+export declare function makeSubmitPlanTool(holder: PlanHolder): Tool<typeof parameters>;
+export {};

package/dist/plan/submit-plan.js

@@ -0,0 +1,57 @@
+import { z } from "zod";
+/**
+ * The `submit_plan` tool (C.31): the agent's only way to propose a plan. It is a
+ * normal tool on the same loop seam as everything else — no hidden control flow.
+ * During the propose phase this is the *only* non-read-only tool registered, so
+ * the agent structurally cannot act before approval.
+ *
+ * Validation is fail-loud: a malformed or empty plan returns `{ok:false}` so the
+ * model sees the error and retries, exactly like any other tool.
+ */
+const stepSchema = z.object({
+    title: z.string().min(1).describe("One-line imperative title for the step."),
+    rationale: z
+        .string()
+        .min(1)
+        .describe("Why this step exists / what it accomplishes."),
+    kind: z
+        .enum(["read", "mutate", "destructive"])
+        .describe("Risk estimate: read (no side effects), mutate (reversible file writes), " +
+        "destructive (shell, deletes, PR-open). Advisory — the approval gate re-checks each action."),
+});
+const parameters = z.object({
+    steps: z
+        .array(stepSchema)
+        .min(1)
+        .describe("Ordered steps that fully accomplish the task."),
+});
+/** Build a `submit_plan` tool bound to `holder`, which captures the last plan. */
+export function makeSubmitPlanTool(holder) {
+    return {
+        name: "submit_plan",
+        description: "Propose an ordered, step-by-step plan for the user to approve before you act. " +
+            "Call this first (and only this) in plan mode; do not take any other action until the plan is approved.",
+        parameters,
+        async execute(input) {
+            // zod already guarantees ≥1 step with non-empty fields; this is the
+            // fail-loud belt-and-suspenders for an empty array slipping through.
+            if (input.steps.length === 0) {
+                return { ok: false, error: "a plan must have at least one step" };
+            }
+            const steps = input.steps.map((s, i) => ({
+                id: String(i + 1),
+                title: s.title.trim(),
+                rationale: s.rationale.trim(),
+                kind: s.kind,
+                status: "pending",
+            }));
+            const plan = { steps };
+            holder.plan = plan;
+            return {
+                ok: true,
+                output: `Plan received (${steps.length} step${steps.length === 1 ? "" : "s"}) and shown to the user for approval. ` +
+                    "Do not take any further action now — end your turn.",
+            };
+        },
+    };
+}

package/dist/plan/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Types for plan mode (C.31). A {@link Plan} is a first-class, typed artifact the
+ * agent produces via the `submit_plan` tool — never free text — so the user can
+ * review the shape of the work once, and execution can track per-step status.
+ */
+/**
+ * The agent's risk *estimate* for a step, used only to render intent and shape
+ * the approval copy. It is NOT authoritative: the real U.3 gate re-classifies
+ * every concrete action at execution time (a step the agent calls "mutate" whose
+ * action turns out destructive still confirms).
+ */
+export type PlanStepKind = "read" | "mutate" | "destructive";
+/** Live execution status of a step. */
+export type PlanStepStatus = "pending" | "running" | "done" | "failed";
+export interface PlanStep {
+    /** Stable 1-based id assigned on submit (e.g. "1"). */
+    readonly id: string;
+    /** One-line imperative title. */
+    readonly title: string;
+    /** Why this step exists / what it accomplishes. */
+    readonly rationale: string;
+    /** The agent's risk estimate (advisory; see {@link PlanStepKind}). */
+    readonly kind: PlanStepKind;
+    /** Mutated in place as execution progresses. */
+    status: PlanStepStatus;
+}
+export interface Plan {
+    readonly steps: PlanStep[];
+}
+/**
+ * The user's decision at the plan-approval prompt.
+ * - `approve` — execute; every action still hits the U.3 gate.
+ * - `approve-grant` — execute AND auto-allow the safe (read/mutate, grantable)
+ *   steps for this run; destructive/ungrantable actions still confirm.
+ * - `revise` — send `feedback` back to the agent for a revised plan.
+ * - `abort` — cancel; nothing executes (also the default-deny for EOF/Ctrl-C).
+ */
+export type PlanDecision = {
+    readonly kind: "approve";
+} | {
+    readonly kind: "approve-grant";
+} | {
+    readonly kind: "revise";
+    readonly feedback: string;
+} | {
+    readonly kind: "abort";
+};
+/** Outcome of executing an approved plan. */
+export interface PlanExecutionResult {
+    /** True if every step reached `done`. */
+    readonly completed: boolean;
+    /** True if a step failed and the user chose to abort the run. */
+    readonly halted: boolean;
+    /** The id of the step that failed, when halted. */
+    readonly failedStepId?: string;
+}
+/** A mutable holder the `submit_plan` tool writes the captured plan into. */
+export interface PlanHolder {
+    plan: Plan | null;
+}

package/dist/plan/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for plan mode (C.31). A {@link Plan} is a first-class, typed artifact the
+ * agent produces via the `submit_plan` tool — never free text — so the user can
+ * review the shape of the work once, and execution can track per-step status.
+ */
+export {};

package/package.json

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