@crouton-kit/crouter 0.3.8 → 0.3.12

package/dist/commands/job.js

@@ -1,344 +0,0 @@
-// `crtr job` subtree — universal monitoring registry for any ongoing task.
-//
-// Producers (agent spawns, future task systems) register jobs and write
-// results; this subtree is the read/cancel/submit surface shared across all
-// producers. Sub-branches: read {list, status, logs, result}, submit, _fail,
-// cancel.
-//
-// Terminal-write contract:
-//   Worker calls `crtr job submit` → jobs.writeResult(jobId, result, 'done').
-//   If claude exits without submitting, the wrapper shell calls `crtr job _fail`
-//   → jobs.writeResult(jobId, {}, 'failed') IF result.json does not yet exist.
-//   `job read result` watches result.json appearance as the sole completion signal.
-//
-// `job read logs` is the only JSONL leaf.
-import { defineBranch, defineLeaf } from '../core/command.js';
-import { emitLine } from '../core/io.js';
-import { InputError } from '../core/io.js';
-import { writeMarkdownResult, readResult as jobsReadResult, jobStatus, listJobs, readLog, cancelJob, } from '../core/jobs.js';
-import { scheduleKillCurrentPane } from '../core/spawn.js';
-import { paginate } from '../core/pagination.js';
-const WAIT_BUDGET_MS = 10 * 60 * 1000;
-const FOLLOW_POLL_MS = 1000;
-const DEFAULT_KILL_SECS = 2;
-// ---------------------------------------------------------------------------
-// read sub-branch
-// ---------------------------------------------------------------------------
-const readList = defineLeaf({
-    name: 'list',
-    help: {
-        name: 'job read list',
-        summary: 'paginated list of jobs, sorted by created_at ascending',
-        params: [
-            { kind: 'flag', name: 'limit', type: 'int', required: false, default: 20, constraint: 'Default 20, max 100.' },
-            { kind: 'flag', name: 'cursor', type: 'string', required: false, constraint: 'Opaque token from next_cursor. Omit on first call.' },
-        ],
-        output: [
-            { name: 'items', type: 'object[]', required: true, constraint: 'Each: {job_id, kind, state, created_at}. Sorted by created_at ascending.' },
-            { name: 'next_cursor', type: 'string | null', required: true, constraint: 'null means no more items.' },
-            { name: 'total', type: 'integer | null', required: true, constraint: 'Total count of all jobs.' },
-        ],
-        outputKind: 'object',
-        effects: ['None. Read-only.'],
-    },
-    run: async (input) => {
-        const limit = typeof input['limit'] === 'number' ? input['limit'] : 20;
-        const cursor = typeof input['cursor'] === 'string' ? input['cursor'] : undefined;
-        const all = listJobs();
-        const page = paginate(all, { limit, cursor }, {
-            defaultLimit: 20,
-            maxLimit: 100,
-            keyOf: (item) => item.created_at,
-            total: 'count',
-        });
-        return {
-            items: page.items,
-            next_cursor: page.next_cursor,
-            total: page.total,
-        };
-    },
-});
-const readStatus = defineLeaf({
-    name: 'status',
-    help: {
-        name: 'job read status',
-        summary: 'read the current status of a job',
-        params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id from a producer (e.g. `crtr agent new *`).' },
-        ],
-        output: [
-            { name: 'job_id', type: 'string', required: true, constraint: 'Echo of input.' },
-            { name: 'state', type: 'string', required: true, constraint: 'One of: live, done, failed, canceled.' },
-            { name: 'age_s', type: 'number', required: true, constraint: 'Seconds since job creation.' },
-            { name: 'last_event', type: 'object | null', required: true, constraint: 'Most recent log event {event, ts}, or null if no events yet.' },
-        ],
-        outputKind: 'object',
-        effects: ['None. Read-only.'],
-    },
-    run: async (input) => {
-        const jobId = input['job_id'];
-        const status = jobStatus(jobId);
-        return {
-            job_id: jobId,
-            state: status.state,
-            age_s: status.age_s,
-            last_event: status.last_event,
-        };
-    },
-});
-const readLogs = defineLeaf({
-    name: 'logs',
-    help: {
-        name: 'job read logs',
-        summary: 'read log events from a job; emits JSONL — one event object per line',
-        params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id from a producer (e.g. `crtr agent new *`).' },
-            { kind: 'flag', name: 'since', type: 'string', required: false, constraint: 'ISO 8601 timestamp. Only emit events at or after this time.' },
-            { kind: 'flag', name: 'until', type: 'string', required: false, constraint: 'ISO 8601 timestamp. Only emit events before this time.' },
-            { kind: 'flag', name: 'level', type: 'enum', choices: ['debug', 'info', 'warn', 'error'], required: false, default: 'info', constraint: 'Minimum severity. Default: info.' },
-            { kind: 'flag', name: 'follow', type: 'bool', required: false, constraint: 'When present, stream new events until the job reaches a terminal state, then stop.' },
-        ],
-        output: [
-            {
-                name: '<event line>',
-                type: 'object',
-                required: true,
-                constraint: 'Each JSONL line is: {ts:string, level:"debug"|"info"|"warn"|"error", event:string, message:string, data?:object}. Emitted one per line.',
-            },
-        ],
-        outputKind: 'jsonl',
-        effects: ['None. Read-only.'],
-    },
-    run: async (input) => {
-        const jobId = input['job_id'];
-        const since = typeof input['since'] === 'string' ? input['since'] : undefined;
-        const until = typeof input['until'] === 'string' ? input['until'] : undefined;
-        const level = (typeof input['level'] === 'string' ? input['level'] : 'info');
-        const follow = input['follow'] === true;
-        const minLevel = level;
-        // Emit all existing events.
-        const events = readLog(jobId, { sinceTs: since, untilTs: until, minLevel });
-        for (const ev of events) {
-            emitLine(ev);
-        }
-        if (!follow)
-            return;
-        // Follow: poll for new events until the job reaches a terminal state.
-        // Track the latest emitted timestamp to avoid re-emitting.
-        let lastTs = until !== undefined ? until : new Date(0).toISOString();
-        // Update lastTs from emitted events.
-        for (const ev of events) {
-            const e = ev;
-            if (typeof e['ts'] === 'string' && e['ts'] > lastTs) {
-                lastTs = e['ts'];
-            }
-        }
-        const terminalStates = new Set(['done', 'failed', 'canceled']);
-        await new Promise((resolve) => {
-            const poll = () => {
-                const status = jobStatus(jobId);
-                const newEvents = readLog(jobId, { sinceTs: lastTs !== new Date(0).toISOString() ? lastTs : undefined, minLevel });
-                for (const ev of newEvents) {
-                    const e = ev;
-                    if (typeof e['ts'] === 'string' && e['ts'] > lastTs) {
-                        emitLine(e);
-                        lastTs = e['ts'];
-                    }
-                }
-                if (terminalStates.has(status.state)) {
-                    resolve();
-                    return;
-                }
-                setTimeout(poll, FOLLOW_POLL_MS);
-            };
-            setTimeout(poll, FOLLOW_POLL_MS);
-        });
-    },
-});
-const readResult = defineLeaf({
-    name: 'result',
-    help: {
-        name: 'job read result',
-        summary: 'read the final result of a completed job',
-        params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id from a producer (e.g. `crtr agent new *`).' },
-            { kind: 'flag', name: 'wait', type: 'bool', required: false, constraint: 'When present, blocks until a result file appears (up to 10 min).' },
-        ],
-        output: [
-            { name: 'job_id', type: 'string', required: true, constraint: 'Echo of input.' },
-            { name: 'status', type: 'string', required: true, constraint: 'One of: done, failed, canceled, timeout.' },
-            { name: 'result_md', type: 'string', required: false, constraint: 'Markdown body submitted by an agent via `crtr job submit`. Present when the job used the agent submit path.' },
-            { name: 'result', type: 'object', required: false, constraint: 'Structured object submitted by a programmatic caller (human/sys). Present when the job used the programmatic submit path.' },
-            { name: 'reason', type: 'string', required: false, constraint: 'Failure reason from frontmatter when status is failed and the agent submit path was used.' },
-        ],
-        outputKind: 'object',
-        effects: ['None. Read-only.'],
-    },
-    run: async (input) => {
-        const jobId = input['job_id'];
-        const wait = input['wait'] === true;
-        const r = await jobsReadResult(jobId, { waitMs: wait ? WAIT_BUDGET_MS : 0 });
-        const out = { job_id: jobId, status: r.status };
-        if (r.result !== undefined) {
-            out['result'] = r.result;
-        }
-        if (r.result_md !== undefined) {
-            out['result_md'] = r.result_md;
-        }
-        if (r.reason !== undefined) {
-            out['reason'] = r.reason;
-        }
-        return out;
-    },
-});
-const readBranch = defineBranch({
-    name: 'read',
-    help: {
-        name: 'job read',
-        summary: 'read job status, logs, or results',
-        children: [
-            { name: 'list', desc: 'paginated job list', useWhen: 'enumerating jobs' },
-            { name: 'status', desc: 'current state and age', useWhen: 'checking if a job is still live' },
-            { name: 'logs', desc: 'stream JSONL log events', useWhen: 'monitoring progress or debugging a job' },
-            { name: 'result', desc: 'read final result', useWhen: 'collecting the output of a completed job' },
-        ],
-    },
-    children: [readList, readStatus, readLogs, readResult],
-});
-// ---------------------------------------------------------------------------
-// submit — called by the worker inside its pane (or by any producer that
-// writes a result programmatically)
-// ---------------------------------------------------------------------------
-const jobSubmit = defineLeaf({
-    name: 'submit',
-    help: {
-        name: 'job submit',
-        summary: 'deliver a markdown result back to a job record (called by workers, or any producer writing the terminal value)',
-        params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id injected as $CRTR_JOB_ID in the spawned pane.' },
-            { kind: 'stdin', name: 'body', required: false, constraint: 'Markdown body of the result, piped on stdin. Required when --status is done (the default). When --status failed, stdin is optional; --reason carries the explanation.' },
-            { kind: 'flag', name: 'status', type: 'enum', choices: ['done', 'failed'], required: false, default: 'done', constraint: 'Terminal status to record. Default: done.' },
-            { kind: 'flag', name: 'reason', type: 'string', required: false, constraint: 'Short failure reason. Required when --status failed; ignored otherwise.' },
-            { kind: 'flag', name: 'kill-pane', type: 'bool', required: false, constraint: `When present, schedule the current tmux pane to close ${DEFAULT_KILL_SECS}s after submission so the spawned worker does not linger. Reviewer agents should pass this; planner/implementer handoffs already self-kill on spawn.` },
-        ],
-        output: [
-            { name: 'submitted', type: 'boolean', required: true, constraint: 'Always true on success.' },
-            { name: 'pane_kill_scheduled', type: 'boolean', required: true, constraint: 'True when --kill-pane is set and a tmux pane kill was scheduled. False otherwise (--kill-pane not set, not in tmux, or TMUX_PANE unset).' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Writes <jobdir>/result.md atomically (YAML frontmatter + body), marking the job done or failed.',
-            'Updates meta.json status to match.',
-            `When --kill-pane is set, schedules \`tmux kill-pane\` on $TMUX_PANE after ${DEFAULT_KILL_SECS}s (detached; submit still returns cleanly).`,
-        ],
-    },
-    run: async (input) => {
-        const jobId = input['job_id'];
-        const status = (typeof input['status'] === 'string' ? input['status'] : 'done');
-        const body = typeof input['body'] === 'string' ? input['body'] : '';
-        const reason = typeof input['reason'] === 'string' ? input['reason'] : '';
-        const killPane = input['killPane'] === true;
-        if (status === 'done' && body.trim() === '') {
-            throw new InputError({
-                error: 'invalid_field',
-                message: '--status done requires a markdown body on stdin.',
-                field: 'body',
-                next: `Pipe the markdown result on stdin, e.g. \`crtr job submit ${jobId} <<'MD' ... MD\`. For failures, use \`--status failed --reason "<why>"\`.`,
-            });
-        }
-        if (status === 'failed' && reason.trim() === '') {
-            throw new InputError({
-                error: 'invalid_field',
-                message: '--status failed requires --reason "<text>".',
-                field: 'reason',
-                next: 'Pass --reason explaining why the task could not complete.',
-            });
-        }
-        writeMarkdownResult(jobId, body, status, status === 'failed' ? reason : undefined);
-        const paneKillScheduled = killPane ? scheduleKillCurrentPane(DEFAULT_KILL_SECS) : false;
-        return { submitted: true, pane_kill_scheduled: paneKillScheduled };
-    },
-});
-// ---------------------------------------------------------------------------
-// _fail — called by the wrapper shell if claude exits without submitting
-// ---------------------------------------------------------------------------
-const jobFail = defineLeaf({
-    name: '_fail',
-    help: {
-        name: 'job _fail',
-        summary: 'internal: mark a job failed if it has not already been submitted (called by wrapper shell)',
-        params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id. If a result file already exists, this is a no-op.' },
-        ],
-        output: [
-            { name: 'recorded', type: 'boolean', required: true, constraint: 'True if failure was recorded; false if a result file already existed (no-op).' },
-        ],
-        outputKind: 'object',
-        effects: [
-            'Writes result.md with status "failed" and a reason if no result file is present.',
-            'Updates meta.json status to failed.',
-        ],
-    },
-    run: async (input) => {
-        const jobId = input['job_id'];
-        try {
-            const existing = await jobsReadResult(jobId, { waitMs: 0 });
-            if (existing.status !== 'timeout') {
-                return { recorded: false };
-            }
-        }
-        catch {
-            // job dir not found — still try to write to surface the failure
-        }
-        try {
-            writeMarkdownResult(jobId, '', 'failed', 'worker exited without submitting');
-            return { recorded: true };
-        }
-        catch {
-            return { recorded: false };
-        }
-    },
-});
-// ---------------------------------------------------------------------------
-// cancel
-// ---------------------------------------------------------------------------
-const jobCancel = defineLeaf({
-    name: 'cancel',
-    help: {
-        name: 'job cancel',
-        summary: 'send a best-effort cancellation signal to a running job',
-        params: [
-            { kind: 'positional', name: 'job_id', type: 'string', required: true, constraint: 'Job id from a producer (e.g. `crtr agent new *`).' },
-        ],
-        output: [
-            { name: 'canceled', type: 'boolean', required: true, constraint: 'True if a signal was delivered or the job was already terminal; false if the job was not live.' },
-        ],
-        outputKind: 'object',
-        effects: ['Best-effort: delivers SIGTERM to the worker process and marks meta.json canceled.'],
-    },
-    run: async (input) => {
-        const jobId = input['job_id'];
-        const result = cancelJob(jobId);
-        return { canceled: result.canceled };
-    },
-});
-// ---------------------------------------------------------------------------
-// root branch
-// ---------------------------------------------------------------------------
-export function registerJob() {
-    return defineBranch({
-        name: 'job',
-        help: {
-            name: 'job',
-            summary: 'monitor and collect results from any ongoing task',
-            model: 'A job is a producer-agnostic record of an ongoing task: state, logs, terminal result. Producers (`crtr agent new *`, future task systems) create jobs; this subtree is the shared read/cancel/submit surface. States: live | done | failed | canceled.',
-            children: [
-                { name: 'read', desc: 'read status, logs, or results', useWhen: 'monitoring or collecting from a running or completed job' },
-                { name: 'submit', desc: 'deliver result from inside a worker pane or any producer', useWhen: 'a worker is ready to return its output' },
-                { name: '_fail', desc: 'internal: mark job failed on unsubmitted exit', useWhen: 'called by the wrapper shell, not manually' },
-                { name: 'cancel', desc: 'best-effort cancel a live job', useWhen: 'stopping a job that is no longer needed' },
-            ],
-        },
-        children: [readBranch, jobSubmit, jobFail, jobCancel],
-    });
-}

package/dist/commands/plan.d.ts

@@ -1,4 +0,0 @@
-export declare const PLAN_NEW_GUIDE = "## Planning workflow\n\nBuild and save an implementation plan: a map another agent can execute without\nre-discovering context. Work through these phases before saving.\n\n### Phase 1: Understand\n\nBuild a full picture of the request and the code. Search for reusable\nfunctions, patterns, and existing implementations before proposing new ones.\n\nLaunch up to 3 Explore subagents IN PARALLEL (single message, multiple tool\ncalls). Use 1 agent for isolated, small-scope tasks; use more when scope is\nuncertain or multiple subsystems are involved. Give each a distinct focus so\nthey don't duplicate work.\n\n### Phase 2: Design\n\nDesign the implementation from Phase 1 findings. Default to launching at least\n1 Plan agent to validate your understanding and surface alternatives. Skip only\nfor trivially small tasks (typo fixes, single-line renames). Use up to 3 agents\nfor large refactors or architectural changes.\n\nIn the Plan agent prompt: include file paths, code-path traces, requirements,\nand constraints from Phase 1. Request a detailed implementation plan.\n\n### Phase 3: Review findings\n\nRead the critical files identified by agents. Confirm the plan aligns with the\nuser's request. Use AskUserQuestion ONLY to clarify requirements or choose\nbetween approaches \u2014 never to ask \"is this okay?\" or \"should I proceed?\".\n\n### Phase 4: Compose the plan body\n\nQuality bar \u2014 every item below is cheap to satisfy and saves the implementer\nfrom re-deciding:\n\n- Every decision pinned. No \"if X then Y\" branches, no \"investigate whether\u2026\",\n  no deferred choices. If you don't know, find out or ask now.\n- No timelines, no fallbacks, no magic values, no \"for now\" shortcuts.\n- Where the plan creates a new interface, schema, or contract, write the actual\n  shape, not \"design a Foo type.\"\n\nRequired sections:\n\n  # Plan: <one-line title>\n\n  ## Context\n  <why this change is being made \u2014 the problem, what prompted it, intended outcome>\n\n  ## Recommended approach\n  <your chosen approach only. Concise enough to scan, detailed enough to execute.>\n\n  ## Files to modify / create\n  - `path/to/file.ts` \u2014 <what changes>\n\n  ## Existing utilities to reuse\n  - `functionName` from `path/to/file.ts:LL` \u2014 <why it fits>\n\n  ## Verification\n  <how to test end-to-end \u2014 run the code, run tests, etc.>\n\nFor plans touching 4+ files across distinct concerns, structure parallel tasks:\n\n  ## Tasks\n  - **Task 1**: <name>\n    - Files: `a.ts`, `b.ts` (disjoint from other tasks)\n    - Depends on: (none) | Task N\n    - Integration: <shared types/APIs with exact shape>\n    - Changes: <bullets>\n\nSkip the Tasks structure for small plans; it's noise when there's no\nparallelism to unlock.\n\n### Phase 5: Save\n\nRun `crtr agent plan new`:\n\n  echo '<plan markdown>' | crtr agent plan new <kebab-case-name> [--spec <spec-name>]\n\n- NAME: short kebab-case slug. Nested names become subdirectories\n  (e.g. `auth/jwt-refresh`).\n- Pipe the full plan markdown composed in Phase 4 on stdin.\n- `--spec` (optional): name of the spec this plan implements. Enables alignment\n  check by the reviewer.\n\nOutput: `{path, follow_up}`. The `follow_up` field names the exact next call\n\u2014 run it.\n\n### Phase 6: Oversize check\n\nIf `follow_up` contains an oversize advisory (plan exceeds 200 lines), split\ninto a short index plan plus nested part plans, each under the threshold.\nRe-save. The implementer executes parts one at a time; long monolithic plans\nare under-decomposed.\n\n### Phase 7: Done\n\nAfter the reviewer approves the plan, your turn ends. Do not summarize in chat.\nFor a human gate, optionally put the plan in front of a person with `crtr\nhuman review` (anchored comments) and gate the handoff with `crtr human\napprove`. This complements \u2014 it does not replace \u2014 `crtr agent new reviewer`.\nIf the user is ready to build, ask once whether to hand off; if yes, run:\n`crtr agent new implementer` with the plan path.";
-export declare const PLAN_SHOW_GUIDE = "";
-import type { BranchDef } from '../core/command.js';
-export declare function registerPlan(): BranchDef;

package/dist/commands/plan.js

@@ -1,309 +0,0 @@
-// `crtr agent plan` subtree — plan new / show / list handlers.
-export const PLAN_NEW_GUIDE = `## Planning workflow
-
-Build and save an implementation plan: a map another agent can execute without
-re-discovering context. Work through these phases before saving.
-
-### Phase 1: Understand
-
-Build a full picture of the request and the code. Search for reusable
-functions, patterns, and existing implementations before proposing new ones.
-
-Launch up to 3 Explore subagents IN PARALLEL (single message, multiple tool
-calls). Use 1 agent for isolated, small-scope tasks; use more when scope is
-uncertain or multiple subsystems are involved. Give each a distinct focus so
-they don't duplicate work.
-
-### Phase 2: Design
-
-Design the implementation from Phase 1 findings. Default to launching at least
-1 Plan agent to validate your understanding and surface alternatives. Skip only
-for trivially small tasks (typo fixes, single-line renames). Use up to 3 agents
-for large refactors or architectural changes.
-
-In the Plan agent prompt: include file paths, code-path traces, requirements,
-and constraints from Phase 1. Request a detailed implementation plan.
-
-### Phase 3: Review findings
-
-Read the critical files identified by agents. Confirm the plan aligns with the
-user's request. Use AskUserQuestion ONLY to clarify requirements or choose
-between approaches — never to ask "is this okay?" or "should I proceed?".
-
-### Phase 4: Compose the plan body
-
-Quality bar — every item below is cheap to satisfy and saves the implementer
-from re-deciding:
-
-- Every decision pinned. No "if X then Y" branches, no "investigate whether…",
-  no deferred choices. If you don't know, find out or ask now.
-- No timelines, no fallbacks, no magic values, no "for now" shortcuts.
-- Where the plan creates a new interface, schema, or contract, write the actual
-  shape, not "design a Foo type."
-
-Required sections:
-
-  # Plan: <one-line title>
-
-  ## Context
-  <why this change is being made — the problem, what prompted it, intended outcome>
-
-  ## Recommended approach
-  <your chosen approach only. Concise enough to scan, detailed enough to execute.>
-
-  ## Files to modify / create
-  - \`path/to/file.ts\` — <what changes>
-
-  ## Existing utilities to reuse
-  - \`functionName\` from \`path/to/file.ts:LL\` — <why it fits>
-
-  ## Verification
-  <how to test end-to-end — run the code, run tests, etc.>
-
-For plans touching 4+ files across distinct concerns, structure parallel tasks:
-
-  ## Tasks
-  - **Task 1**: <name>
-    - Files: \`a.ts\`, \`b.ts\` (disjoint from other tasks)
-    - Depends on: (none) | Task N
-    - Integration: <shared types/APIs with exact shape>
-    - Changes: <bullets>
-
-Skip the Tasks structure for small plans; it's noise when there's no
-parallelism to unlock.
-
-### Phase 5: Save
-
-Run \`crtr agent plan new\`:
-
-  echo '<plan markdown>' | crtr agent plan new <kebab-case-name> [--spec <spec-name>]
-
-- NAME: short kebab-case slug. Nested names become subdirectories
-  (e.g. \`auth/jwt-refresh\`).
-- Pipe the full plan markdown composed in Phase 4 on stdin.
-- \`--spec\` (optional): name of the spec this plan implements. Enables alignment
-  check by the reviewer.
-
-Output: \`{path, follow_up}\`. The \`follow_up\` field names the exact next call
-— run it.
-
-### Phase 6: Oversize check
-
-If \`follow_up\` contains an oversize advisory (plan exceeds 200 lines), split
-into a short index plan plus nested part plans, each under the threshold.
-Re-save. The implementer executes parts one at a time; long monolithic plans
-are under-decomposed.
-
-### Phase 7: Done
-
-After the reviewer approves the plan, your turn ends. Do not summarize in chat.
-For a human gate, optionally put the plan in front of a person with \`crtr
-human review\` (anchored comments) and gate the handoff with \`crtr human
-approve\`. This complements — it does not replace — \`crtr agent new reviewer\`.
-If the user is ready to build, ask once whether to hand off; if yes, run:
-\`crtr agent new implementer\` with the plan path.`;
-export const PLAN_SHOW_GUIDE = '';
-import { defineBranch, defineLeaf } from '../core/command.js';
-import { saveArtifact, readArtifact, listArtifacts, OVERSIZE_WARN_LINES } from '../core/artifact.js';
-import { paginate } from '../core/pagination.js';
-export function registerPlan() {
-    const planNew = defineLeaf({
-        name: 'new',
-        help: {
-            name: 'agent plan new',
-            summary: 'draft a plan from intent and optional spec alignment',
-            guide: PLAN_NEW_GUIDE,
-            params: [
-                {
-                    kind: 'positional',
-                    name: 'name',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Kebab-case slug used as the artifact filename. No spaces; use hyphens.',
-                },
-                {
-                    kind: 'stdin',
-                    name: 'body',
-                    required: true,
-                    constraint: "Full planning prose. Treated as the planner's north star; not parsed further.",
-                },
-                {
-                    kind: 'flag',
-                    name: 'spec',
-                    type: 'string',
-                    required: false,
-                    constraint: 'Name of the spec this plan implements. Enables alignment check on write. Must reference an existing spec artifact.',
-                },
-            ],
-            output: [
-                {
-                    name: 'path',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Absolute path to the written plan artifact.',
-                },
-                {
-                    name: 'follow_up',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Recommended next call (reviewer spawn via `crtr agent new reviewer`).',
-                },
-            ],
-            outputKind: 'object',
-            effects: [
-                'Writes a plan artifact to the plans artifact directory.',
-                'If `--spec` is provided, records the spec alignment reference in the artifact frontmatter.',
-            ],
-        },
-        run: async (input) => {
-            const name = input['name'];
-            const body = input['body'];
-            const spec = input['spec'];
-            const meta = {};
-            if (spec !== undefined)
-                meta['spec'] = spec;
-            const { path, oversize, lineCount } = saveArtifact('plans', name, body, meta);
-            let follow_up = `Review it: crtr agent new reviewer ${path} --kind plan (returns {job_id}), then crtr job read result <job_id> --wait.`;
-            follow_up +=
-                ` Optional human gate (complements, does not replace the agent reviewer): crtr human review --file ${path} for anchored comments, then gate handoff with crtr human approve --title "Approve this plan?".`;
-            if (oversize) {
-                follow_up +=
-                    ` OVERSIZE ADVISORY: this plan is ${lineCount} lines (> ${OVERSIZE_WARN_LINES}). Split into a short index plan plus nested part plans before reviewing.`;
-            }
-            return { path, follow_up };
-        },
-    });
-    const planShow = defineLeaf({
-        name: 'show',
-        help: {
-            name: 'agent plan show',
-            summary: 'read a plan artifact by name',
-            params: [
-                {
-                    kind: 'positional',
-                    name: 'name',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Exact artifact name (no path extension). Use `plan list` to enumerate.',
-                },
-            ],
-            output: [
-                {
-                    name: 'name',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Artifact name as stored.',
-                },
-                {
-                    name: 'path',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Absolute path to the artifact file.',
-                },
-                {
-                    name: 'body',
-                    type: 'string',
-                    required: true,
-                    constraint: 'Full plan body text.',
-                },
-                {
-                    name: 'spec',
-                    type: 'string | null',
-                    required: true,
-                    constraint: 'Associated spec name, or null if none.',
-                },
-            ],
-            outputKind: 'object',
-            effects: ['None. Read-only.'],
-        },
-        run: async (input) => {
-            const name = input['name'];
-            const record = readArtifact('plans', name);
-            return { name: record.name, path: record.path, body: record.body, spec: record.spec };
-        },
-    });
-    const planList = defineLeaf({
-        name: 'list',
-        help: {
-            name: 'agent plan list',
-            summary: 'paginated list of plan artifacts, sorted ascending by name',
-            params: [
-                {
-                    kind: 'flag',
-                    name: 'scope',
-                    type: 'enum',
-                    choices: ['user', 'project', 'all'],
-                    required: false,
-                    constraint: 'Filter by scope. Omit to list all.',
-                },
-                {
-                    kind: 'flag',
-                    name: 'limit',
-                    type: 'int',
-                    required: false,
-                    default: 20,
-                    constraint: 'Default 20, max 100.',
-                },
-                {
-                    kind: 'flag',
-                    name: 'cursor',
-                    type: 'string',
-                    required: false,
-                    constraint: "Opaque token from a previous response's next_cursor. Omit on first call.",
-                },
-            ],
-            output: [
-                {
-                    name: 'items',
-                    type: 'object[]',
-                    required: true,
-                    constraint: 'Each: {name, path, updated_at}. Sorted ascending by name.',
-                },
-                {
-                    name: 'next_cursor',
-                    type: 'string | null',
-                    required: true,
-                    constraint: 'Pass on the next call to continue. null means no more items.',
-                },
-                {
-                    name: 'total',
-                    type: 'integer | null',
-                    required: true,
-                    constraint: 'Total plans matching the query. Exact when cheap; null on large/filtered sets — do not retry to force it.',
-                },
-            ],
-            outputKind: 'object',
-            effects: ['None. Read-only.'],
-        },
-        run: async (input) => {
-            const limit = input['limit'] ?? 20;
-            const cursor = input['cursor'];
-            const all = listArtifacts('plans');
-            const result = paginate(all, { limit, cursor }, {
-                defaultLimit: 20,
-                maxLimit: 100,
-                keyOf: (item) => item.name,
-                total: 'count',
-            });
-            return {
-                items: result.items,
-                next_cursor: result.next_cursor,
-                total: result.total,
-            };
-        },
-    });
-    return defineBranch({
-        name: 'plan',
-        help: {
-            name: 'agent plan',
-            summary: 'create and read plan artifacts',
-            model: 'Lifecycle: draft -> active -> handed-off.',
-            children: [
-                { name: 'new', desc: 'draft a plan from intent', useWhen: 'starting fresh work or decomposing a spec' },
-                { name: 'show', desc: 'read a plan by name', useWhen: 'reasoning about an existing plan' },
-                { name: 'list', desc: 'enumerate plans', useWhen: 'discovering what plans exist' },
-            ],
-        },
-        children: [planNew, planShow, planList],
-    });
-}