@north-light/crouter 0.3.317 → 0.3.319

package/dist/commands/node/create.js

@@ -1,332 +1,3 @@
-// `crtr node new` — creation commands and persona-kind helpers.
-import { envNodeId } from '../../shared/env.js';
-import { defineLeaf } from '../../core/command.js';
-import { InputError } from '../../core/io.js';
-import { mark } from '../../core/timing.js';
-import { OUTPUT_SCHEMA_CONSTRAINTS, OUTPUT_SCHEMA_TRANSPORT, parseOutputSchemaValue } from '../../core/runtime/structured-output.js';
-import { MODEL_SPEC_FORMS, MODEL_SPEC_NEXT } from '../../core/runtime/model-selection.js';
-import { readMergedLaunchConfig } from '../../core/config.js';
-import { parseDurationMs } from '../../core/wake.js';
-import { profilesStateBlock } from '../../core/profiles/state-block.js';
-import { resolveProfileOperand } from '../../core/profiles/manifest.js';
-import { stateBlock } from '../../core/help.js';
-import { cliClient, getNodeOrNull, rethrowAsCliError } from '../api-client.js';
-import { inTmux } from '../../core/runtime/placement-tmux.js';
-import { openSpawnViewer } from '../surface/node/placement.js';
-import { resolve } from 'node:path';
-const YIELD_NUDGE_THRESHOLD = 100_000;
-const NODE_NEW_OUTPUT_SCHEMA_EFFECT = '--output-schema writes the accepted result to the node’s context/result.json and pushes it as the node’s final report; a node that cannot honestly satisfy the schema declines with `crtr push result --decline "<reason>" --code <token>`, which finishes it with a failure outcome (reason `declined`) whose `declined` field carries { reason, code, retryable } and no result. Name the code tokens you accept in the prompt; crouter carries the code verbatim and you validate it.';
-const STD_CHILD_FOLLOW_UP = "Do not wait, poll, or duplicate this child's assignment in your own context — there is no result to await, stopping will not strand you, and duplicated work wastes the delegated context. You're auto-subscribed, so its finish wakes you on its own. Two moves only: do other independent work right now, or stop and end your turn — the wake brings you back.";
-/** Decision road sign for a managed (non-root) child. Normally STD_CHILD_FOLLOW_UP,
- *  but when the SPAWNER is an orchestrator whose context has already grown past
- *  YIELD_NUDGE_THRESHOLD, steer it to yield now and let its fresh revive handle
- *  the child's result. */
-export async function childFollowUp(spawnerId) {
-    if (spawnerId === undefined || spawnerId === '')
-        return STD_CHILD_FOLLOW_UP;
-    const spawner = await getNodeOrNull(spawnerId);
-    if (spawner === null || spawner.mode !== 'orchestrator')
-        return STD_CHILD_FOLLOW_UP;
-    const ctxTokens = spawner.context_tokens ?? null;
-    if (ctxTokens === null || ctxTokens < YIELD_NUDGE_THRESHOLD)
-        return STD_CHILD_FOLLOW_UP;
-    const k = Math.round(ctxTokens / 1000);
-    return `Child spawned — you're auto-subscribed, so its finish wakes you on its own; never wait, poll, or duplicate the child's assignment in your own context. But you're an orchestrator already carrying ~${k}k of context: rather than hold this window open for the result, checkpoint context/roadmap.md and \`crtr node yield\` now. Yielding ends this turn, and the child's completion then revives you fresh against your roadmap — let that clean revive absorb the result instead of this bloated context.`;
-}
-/** Validate a `--kind` against the installed personas; throws a listing InputError. */
-export function assertKind(kind) {
-    const kinds = Object.keys(readMergedLaunchConfig().kinds).sort();
-    if (!kinds.includes(kind)) {
-        throw new InputError({ error: 'unknown_kind', message: `unknown kind: ${kind}`, field: 'kind', next: `Valid kinds: ${kinds.join(', ')}.` });
-    }
-}
-/** A live `<kinds count=N>` state element — one `<kind> — <whenToUse>` line per
- *  installed top-level persona kind (project > user > builtin), lazily built so
- *  it reflects the caller's cwd/project scope. Appended to `node new -h` and
- *  `node promote -h` so custom kinds appear in help. Soft-fails via the renderer.
- *
- *  Keep this block cheap and caller-agnostic: help should not depend on the
- *  running node's current persona env, which can lag after polymorph. Sub-kinds
- *  (e.g. `audit/security`) are OMITTED here — `KindConfig.availableTo`
- *  defaults to the sub-kind's own top-level ancestor, and this generic block has
- *  no single ancestor to check against, so only an explicit `availableTo: ['*']`
- *  sub-kind (universally available) earns a place in this list. A direct launch
- *  by full sub-kind string is always valid regardless (visibility-only
- *  filtering) — discover the roster for a specific kind via
- *  `crtr sys context prompt-review --list --kind <kind>`. */
-export function kindsStateBlock() {
-    const registry = readMergedLaunchConfig().kinds;
-    const kinds = Object.keys(registry)
-        .filter((k) => {
-        const slash = k.indexOf('/');
-        if (slash === -1)
-            return true;
-        const availableTo = registry[k]?.availableTo ?? [k.slice(0, slash)];
-        return availableTo.includes('*');
-    })
-        .sort();
-    const lines = kinds
-        .map((k) => {
-        const w = registry[k]?.whenToUse ?? '';
-        return w ? `${k} — ${w}` : k;
-    })
-        .join('\n');
-    return stateBlock('kinds', { count: kinds.length }, lines);
-}
-function nodeNewParams() {
-    return [
-        { kind: 'stdin', name: 'prompt', required: false, constraint: 'First user message.' },
-        { kind: 'flag', name: 'kind', type: 'string', required: false, constraint: "Persona kind. Defaults to the profile's default kind; `general` when the profile has none. The <kinds> list below names every top-level installable kind." },
-        { kind: 'flag', name: 'mode', type: 'enum', choices: ['base', 'orchestrator'], required: false, default: 'base', constraint: 'Persona mode. base for one hands-on unit; orchestrator when the unit itself needs decomposition across children. When you hold several parallel units of one kind, spawn ONE orchestrator child of that kind to own the fan-out rather than spawning the units yourself — unless you are already an orchestrator of that kind, whose job is exactly that fan-out.' },
-        { kind: 'flag', name: 'cwd', type: 'path', required: false, constraint: 'Pin the node to this directory. Defaults to the spawner\u2019s directory for a managed child, and to the directory this command runs in for a root.' },
-        { kind: 'flag', name: 'name', type: 'string', required: false, constraint: 'Display name.' },
-        { kind: 'flag', name: 'parent', type: 'string', required: false, constraint: 'Parent node id. Defaults to the calling node.' },
-        { kind: 'flag', name: 'node-id', type: 'string', required: false, constraint: 'Exact id for the new node; lowercase letters, digits, and hyphens only, at most 128 characters. Rejected if already present.' },
-        { kind: 'flag', name: 'root', type: 'bool', required: false, constraint: 'Spawn an independent root with no parent or subscription. Mutually exclusive with --worktree.' },
-        { kind: 'flag', name: 'resident', type: 'bool', required: false, constraint: 'Birth the node as resident: it parks and stays wakeable without being forced to submit a final. Pass it ONLY when the user will open this node’s viewer pane and work with it back and forth; a child that only other nodes message stays terminal. Applies to managed children and roots; roots default to resident.' },
-        { kind: 'flag', name: 'terminal', type: 'bool', required: false, constraint: 'Birth the node as terminal: it finalizes when its work is done and leaves nothing wakeable behind. Only meaningful with --root, whose default is resident; managed children are already terminal. Pass it for bounded programmatic work no one will open a viewer on. Mutually exclusive with --resident.' },
-        { kind: 'flag', name: 'worktree', type: 'string', required: false, constraint: 'Local base branch for a crouter-managed worktree for this child. Mutually exclusive with --root.' },
-        { kind: 'flag', name: 'fork-from', type: 'string', required: false, constraint: 'Fork the new node from an existing node id, absolute session path, or partial pi session uuid.' },
-        {
-            kind: 'flag',
-            name: 'model',
-            type: 'string',
-            required: false,
-            constraint: 'Durable model override. Omit unless the task or governing guidance requires a specific model.',
-            focusedHelp: {
-                whenToUse: 'Use only when the user, task, or governing agent guidance already requires a specific provider, model, capability tier, or family. Omit it for routine delegation: the selected persona kind and profile own normal model selection, and review personas may enforce a quality floor.',
-                value: `Accepted forms: ${MODEL_SPEC_FORMS}. Concrete provider/id requests must be registered. Portable provider/tier, bare-tier, and family-alias requests resolve through the configured model ladders.`,
-                effects: [
-                    'The resolved concrete override is stored on the node and in its launch recipe, so every launch and revive uses that exact provider/model.',
-                    'Portable tiers and aliases resolve through the configured ladders; a persona quality floor may raise a weaker request before its resolved model is stored.',
-                ],
-            },
-        },
-        {
-            kind: 'flag',
-            name: 'profile',
-            type: 'string',
-            required: false,
-            constraint: 'Profile override. Use only when the task needs different project purview, memory, or environment; otherwise omit for normal inheritance or selection.',
-            focusedHelp: {
-                whenToUse: 'Use only when the work must run under a different profile because it needs that profile’s project purview, memory store, stored environment, or defaults. Do not use it merely to change the working directory, persona kind, model, or graph ownership; those have separate parameters.',
-                value: 'Pass a profile id or name from the <profiles> list below; a close-enough name resolves to the nearest profile and the choice is reported on stderr. Omit it inside a node to inherit the caller’s profile; outside a node, omission runs normal cwd-based profile selection.',
-                effects: [
-                    'The selected profile id is stored on the node and supplies its profile-scoped config, memory, environment, and injected bearings.',
-                    'It does not change the parent or subscription; --cwd separately pins the working directory.',
-                ],
-                dynamicState: () => profilesStateBlock(),
-            },
-        },
-        { kind: 'flag', name: 'situational-context', type: 'string', required: false, constraint: 'Hidden ambient context appended to injected bearings, never visible chat.' },
-        // Hidden: an idle root is the rare shape, and the empty-prompt error names
-        // this flag at exactly the moment it is needed. Advertising it would tax
-        // every spawn with a capability almost no caller wants.
-        { kind: 'flag', name: 'no-kickoff', type: 'bool', required: false, hidden: true, constraint: 'With --root, start the broker and session idle without a first message or model turn. Mutually exclusive with a prompt and --mode orchestrator.' },
-        { kind: 'flag', name: 'deadline', type: 'string', required: false, constraint: 'Positive, representable wall-clock duration from spawn. Grammar: one or more positive integer-unit parts; units: s, m, h, d; adjacent parts are summed. Omit for no deadline.' },
-        { kind: 'flag', name: 'outcome-action', type: 'string', required: false, constraint: 'Declared human-action name that receives the node outcome. Grammar: 1–128 ASCII letters, digits, dots, underscores, or hyphens; starts with a letter or digit. Omit when no external delivery target is needed.' },
-        { kind: 'flag', name: 'outcome-payload', type: 'string', required: false, constraint: 'JSON value, serialized at most 64 KiB, frozen and echoed to --outcome-action. Requires --outcome-action.' },
-        {
-            kind: 'flag',
-            name: 'output-schema',
-            type: 'string',
-            required: false,
-            constraint: 'Replace prose completion with a schema-constrained final result. Use only when its consumer requires fixed fields.',
-            focusedHelp: {
-                whenToUse: 'Use only when the node’s consumer needs a machine-checkable final object with fixed fields. Omit it for ordinary delegation or when a prose report is enough; structured output replaces the completion protocol, and an over-constrained schema can force retries.',
-                value: `Pass the JSON Schema the result must satisfy. ${OUTPUT_SCHEMA_TRANSPORT} ${OUTPUT_SCHEMA_CONSTRAINTS}`,
-                effects: [
-                    'The node must answer with `crtr push result` and cannot finish until the result is accepted; a plain `crtr push final` is blocked while the request is pending.',
-                    NODE_NEW_OUTPUT_SCHEMA_EFFECT,
-                    'The managed parent wakes through its existing subscription when the final report arrives; an independent root has no subscriber to wake.',
-                    'An accepted result, or a decline, removes the request and terminates the node.',
-                ],
-            },
-        },
-    ];
-}
-/** A root's viewer opens from THIS process (openSpawnViewer), so the caller's
- *  own tmux presence decides whether placement fields and the viewer effect can
- *  ever apply. Outside tmux they are dead weight, so help omits them. `inTmux()`
- *  is a bare env read — safe on the import-time help path. */
-function nodeNewOutput() {
-    return [
-        { name: 'node_id', type: 'string', required: true, constraint: 'New node id.' },
-        { name: 'name', type: 'string', required: true, constraint: 'Display name.' },
-        { name: 'frozen_at', type: 'string', required: false, constraint: 'Present when a managed child exists but capacity deferred its broker start.' },
-        ...(inTmux()
-            ? [
-                { name: 'window', type: 'string', required: false, constraint: 'tmux window id when a viewer opens.' },
-                { name: 'session', type: 'string', required: false, constraint: 'tmux session when a viewer opens.' },
-            ]
-            : []),
-        { name: 'follow_up', type: 'string', required: true, constraint: 'Managed child: continue unrelated work or stop; its final report wakes you. Root: hand it off; no report wakes you.' },
-    ];
-}
-function nodeNewEffects() {
-    return [
-        'Creates nodes/<id>/ in the canvas home, indexes the node in canvas.db, and starts its detached broker engine.',
-        'A managed child creates an active parent subscription; its pushes wake the parent. --root creates an independent node with spawned_by provenance and no parent subscription.',
-        '--worktree creates a managed worktree at ~/.crouter/canvas/worktrees/<node-id>/ on a new crtr/<node-id> branch.',
-        NODE_NEW_OUTPUT_SCHEMA_EFFECT,
-        '--deadline persists a wall-clock deadline from spawn; expiry cancels the node and records a failure outcome with reason deadline_exceeded.',
-        '--outcome-action registers one resolved local human-action target. When the node settles, crouter retries delivery of its outcome document until the target accepts it or permanently rejects it; --outcome-payload is frozen and echoed in that document.',
-        ...(inTmux() ? ['--root opens a viewer for the new node in the current tmux session.'] : []),
-    ];
-}
-async function runNodeCreation(input) {
-    const prompt = input['prompt'] ?? '';
-    const noKickoff = input['noKickoff'] === true;
-    if (!noKickoff && prompt.trim() === '') {
-        throw new InputError({ error: 'empty_prompt', message: 'a prompt is required (stdin or positional)', next: 'Pipe a task on stdin or pass it as an argument, or pass --no-kickoff to spawn an idle node with none.' });
-    }
-    if (noKickoff && prompt.trim() !== '') {
-        throw new InputError({ error: 'no_kickoff_with_prompt', message: '--no-kickoff cannot be combined with a prompt', field: 'no-kickoff', next: 'Drop --no-kickoff, or drop the prompt.' });
-    }
-    const kind = input['kind'];
-    const mode = (input['mode'] ?? 'base');
-    const pinCwdRaw = input['cwd']?.trim();
-    const pinCwd = pinCwdRaw !== undefined && pinCwdRaw !== '' ? resolve(pinCwdRaw) : undefined;
-    const name = input['name'];
-    const parent = input['parent'];
-    const root = input['root'] === true;
-    const resident = input['resident'] === true;
-    const terminal = input['terminal'] === true;
-    if (resident && terminal) {
-        throw new InputError({ error: 'lifecycle_conflict', message: '--resident and --terminal cannot both be passed', field: 'terminal', next: 'Pass the one birth lifecycle you want, or neither to take the default (resident for --root, terminal for a managed child).' });
-    }
-    const worktreeBaseRaw = input['worktree'];
-    if (worktreeBaseRaw !== undefined && worktreeBaseRaw.trim() === '') {
-        throw new InputError({ error: 'worktree_base_required', message: '--worktree requires a base branch', field: 'worktree', next: 'Pass an existing local branch that landing can fast-forward.' });
-    }
-    const worktreeBase = worktreeBaseRaw?.trim();
-    const forkFrom = input['forkFrom'];
-    const modelSpec = input['model']?.trim();
-    if (modelSpec === '') {
-        throw new InputError({ error: 'empty_spec', message: 'a model spec is required', field: 'model', next: `Run \`crtr node new --model -h\` and read the focused contract. ${MODEL_SPEC_NEXT}` });
-    }
-    // Resolved here rather than server-side so the closest-match notice lands on
-    // the caller's terminal instead of the daemon log, and so the daemon receives
-    // a durable id rather than a name it would have to interpret again.
-    const profileOperand = input['profile'];
-    const profile = profileOperand === undefined ? undefined : resolveProfileOperand(profileOperand).profileId;
-    const situationalContextRaw = input['situationalContext']?.trim();
-    const situationalContext = situationalContextRaw !== undefined && situationalContextRaw !== '' ? situationalContextRaw : undefined;
-    const outputSchemaParsed = parseOutputSchemaValue(input['outputSchema']);
-    const outputSchema = outputSchemaParsed !== null ? JSON.stringify(outputSchemaParsed) : null;
-    const deadline = input['deadline'];
-    if (deadline !== undefined) {
-        const durationMs = parseDurationMs(deadline);
-        const deadlineAt = durationMs === null ? Number.NaN : new Date(Date.now() + durationMs).getTime();
-        if (durationMs === null || !Number.isFinite(durationMs) || durationMs <= 0 || !Number.isFinite(deadlineAt)) {
-            throw new InputError({ error: 'invalid_deadline', message: '--deadline must be a positive representable duration', field: 'deadline', next: 'Pass positive integer-unit parts using s, m, h, or d.' });
-        }
-    }
-    const outcomeAction = input['outcomeAction'];
-    const outcomePayloadRaw = input['outcomePayload'];
-    if (outcomePayloadRaw !== undefined && outcomeAction === undefined) {
-        throw new InputError({ error: 'outcome_payload_requires_action', message: '--outcome-payload requires --outcome-action', field: 'outcome-payload', next: 'Pass the declared delivery action with --outcome-action.' });
-    }
-    let outcomePayload;
-    if (outcomePayloadRaw !== undefined) {
-        try {
-            outcomePayload = JSON.parse(outcomePayloadRaw);
-        }
-        catch {
-            throw new InputError({ error: 'invalid_outcome_payload', message: '--outcome-payload must be valid JSON', field: 'outcome-payload', next: 'Pass one valid JSON value.' });
-        }
-    }
-    const nodeId = input['nodeId']?.trim();
-    if (root && worktreeBase !== undefined) {
-        throw new InputError({ error: 'worktree_root_conflict', message: '--worktree is mutually exclusive with --root', field: 'worktree', next: 'Drop either --root or --worktree.' });
-    }
-    if (noKickoff && !root) {
-        throw new InputError({ error: 'no_kickoff_requires_root', message: '--no-kickoff is only valid with --root', field: 'no-kickoff', next: 'Add --root, or drop --no-kickoff and provide a prompt.' });
-    }
-    if (noKickoff && mode === 'orchestrator') {
-        throw new InputError({ error: 'no_kickoff_orchestrator_unsupported', message: '--no-kickoff cannot be combined with --mode orchestrator', field: 'no-kickoff', next: 'Drop --no-kickoff and provide a prompt, or spawn in base mode.' });
-    }
-    const creator = envNodeId();
-    const parentId = parent ?? creator;
-    mark('node_new.create_start', { root });
-    const detail = await cliClient().createNode({
-        ...(kind !== undefined ? { kind } : {}),
-        mode,
-        // The caller's directory is the profile-SELECTION context; where the node
-        // actually lands is resolved server-side (pin > spawner's cwd > profile
-        // home). Only `--cwd` pins.
-        cwd: process.cwd(),
-        ...(pinCwd !== undefined && pinCwd !== '' ? { pin_cwd: pinCwd } : {}),
-        ...(name !== undefined ? { name } : {}),
-        prompt,
-        ...(root ? { root: true } : { parent: parentId ?? null }),
-        ...(creator !== undefined ? { creator } : {}),
-        ...(resident ? { root_lifecycle: 'resident' } : {}),
-        ...(terminal ? { root_lifecycle: 'terminal' } : {}),
-        ...(worktreeBase !== undefined ? { worktree: worktreeBase } : {}),
-        ...(forkFrom !== undefined ? { fork_from: forkFrom } : {}),
-        ...(modelSpec !== undefined ? { model: modelSpec } : {}),
-        ...(profile !== undefined ? { profile } : {}),
-        ...(situationalContext !== undefined ? { situational_context: situationalContext } : {}),
-        ...(noKickoff ? { no_kickoff: true } : {}),
-        ...(outputSchema !== null ? { output_schema: outputSchema } : {}),
-        ...(deadline !== undefined ? { deadline } : {}),
-        ...(outcomeAction !== undefined ? {
-            outcome_delivery: {
-                action: outcomeAction,
-                ...(outcomePayload === undefined ? {} : { payload: outcomePayload }),
-            },
-        } : {}),
-        ...(nodeId !== undefined && nodeId !== '' ? { node_id: nodeId } : {}),
-        // A bare `--root --no-kickoff` create is exactly what the warm pool holds
-        // ready; every other shape is rejected server-side and cold-spawns.
-        ...(root ? { prefer_warm: true } : {}),
-    }).catch(rethrowAsCliError);
-    mark('node_new.node_created', { node: detail.node_id });
-    let placement = {};
-    if (root)
-        placement = openSpawnViewer(detail.node_id, detail.cwd, detail.name);
-    if (root)
-        mark('node_new.viewer_window_opened');
-    const frozen = !root && detail.frozen_at !== null;
-    const result = {
-        node_id: detail.node_id,
-        name: detail.name,
-        ...(frozen ? { frozen_at: detail.frozen_at } : {}),
-        window: placement.window,
-        session: placement.session,
-        follow_up: root
-            ? (noKickoff
-                ? 'Independent root spawned idle. No kickoff turn ran; hand it off or attach and prompt it. No report wakes you.'
-                : 'Independent root spawned. You are not subscribed, so its finish does not wake you; hand it off and move on.')
-            : (frozen
-                ? 'Child row exists, but no broker started because capacity is full. It is frozen and will launch when a broker slot frees; its final report wakes you then.'
-                : await childFollowUp(parentId)),
-    };
-    return result;
-}
-export const nodeNew = defineLeaf({
-    name: 'new',
-    description: 'create and start a node immediately',
-    whenToUse: 'a unit of work is genuinely separable from what you are doing: a bounded subtask you would otherwise grind out inline, several independent units worth running in parallel (usually via one orchestrator child of the matching kind rather than a flat fan-out from you), a scouting pass over unfamiliar code, a change that wants its own git worktree, or an answer you need in a fixed shape rather than as prose',
-    tier: 'important',
-    help: {
-        name: 'node new',
-        summary: 'create a node immediately and start its detached broker',
-        guide: 'The prompt is the child\u2019s entire brief: it wakes with this prompt, its persona, and ambient bearings \u2014 none of your conversation carries over. State the outcome and constraints. Pass an implementation plan only when it is already settled or necessary to preserve an approved decision; otherwise, let the child investigate and choose how. Give the reason along with the request: the larger goal this serves and what the child\'s output enables, so the child resolves ambiguity toward your intent instead of guessing. Name by absolute path every artifact the task depends on (a spec, an explore report, an earlier child\'s findings); the child inherits only the files the prompt names. When the report must carry something specific—findings inline, or paths to artifacts it wrote—say so in the prompt.',
-        params: nodeNewParams(),
-        output: nodeNewOutput(),
-        dynamicState: () => kindsStateBlock(),
-        outputKind: 'object',
-        effects: nodeNewEffects(),
-    },
-    run: (input) => runNodeCreation(input),
-    render: (r) => {
-        const win = r['window'] ? ` in window ${r['window']}` : '';
-        const lines = [`Spawned "${r['name']}" (${r['node_id']})${win}.`];
-        if (r['session'])
-            lines.push(`- session: ${r['session']}`);
-        lines.push('', String(r['follow_up']));
-        return lines.join('\n');
-    },
-});
+var L=Object.defineProperty;var o=(e,t)=>L(e,"name",{value:t,configurable:!0});import{envNodeId as z}from"../../shared/env.js";import{defineLeaf as H}from"../../core/command.js";import{InputError as r}from"../../core/io.js";import{mark as x}from"../../core/timing.js";import{OUTPUT_SCHEMA_CONSTRAINTS as B,OUTPUT_SCHEMA_TRANSPORT as J,parseOutputSchemaValue as W}from"../../core/runtime/structured-output.js";import{MODEL_SPEC_FORMS as K,MODEL_SPEC_NEXT as Y}from"../../core/runtime/model-selection.js";import{readMergedLaunchConfig as M}from"../../core/config.js";import{parseDurationMs as G}from"../../core/wake.js";import{profilesStateBlock as V}from"../../core/profiles/state-block.js";import{resolveProfileOperand as X}from"../../core/profiles/manifest.js";import{stateBlock as Q}from"../../core/help.js";import{cliClient as Z,getNodeOrNull as ee,rethrowAsCliError as te}from"../api-client.js";import{inTmux as R}from"../../core/runtime/placement-tmux.js";import{openSpawnViewer as ne}from"../surface/node/placement.js";import{resolve as oe}from"node:path";const re=1e5,$='--output-schema writes the accepted result to the node\u2019s context/result.json and pushes it as the node\u2019s final report; a node that cannot honestly satisfy the schema declines with `crtr push result --decline "<reason>" --code <token>`, which finishes it with a failure outcome (reason `declined`) whose `declined` field carries { reason, code, retryable } and no result. Name the code tokens you accept in the prompt; crouter carries the code verbatim and you validate it.',q="Do not wait, poll, or duplicate this child's assignment in your own context \u2014 there is no result to await, stopping will not strand you, and duplicated work wastes the delegated context. You're auto-subscribed, so its finish wakes you on its own. Two moves only: do other independent work right now, or stop and end your turn \u2014 the wake brings you back.";async function ie(e){if(e===void 0||e==="")return q;const t=await ee(e);if(t===null||t.mode!=="orchestrator")return q;const n=t.context_tokens??null;return n===null||n<re?q:`Child spawned \u2014 you're auto-subscribed, so its finish wakes you on its own; never wait, poll, or duplicate the child's assignment in your own context. But you're an orchestrator already carrying ~${Math.round(n/1e3)}k of context: rather than hold this window open for the result, checkpoint context/roadmap.md and \`crtr node yield\` now. Yielding ends this turn, and the child's completion then revives you fresh against your roadmap \u2014 let that clean revive absorb the result instead of this bloated context.`}o(ie,"childFollowUp");function Se(e){const t=Object.keys(M().kinds).sort();if(!t.includes(e))throw new r({error:"unknown_kind",message:`unknown kind: ${e}`,field:"kind",next:`Valid kinds: ${t.join(", ")}.`})}o(Se,"assertKind");function ae(){const e=M().kinds,t=Object.keys(e).filter(i=>{const s=i.indexOf("/");return s===-1?!0:(e[i]?.availableTo??[i.slice(0,s)]).includes("*")}).sort(),n=t.map(i=>{const s=e[i]?.whenToUse??"";return s?`${i} \u2014 ${s}`:i}).join(`
+`);return Q("kinds",{count:t.length},n)}o(ae,"kindsStateBlock");function se(){return[{kind:"stdin",name:"prompt",required:!1,constraint:"First user message."},{kind:"flag",name:"kind",type:"string",required:!1,constraint:"Persona kind. Defaults to the profile's default kind; `general` when the profile has none. The <kinds> list below names every top-level installable kind."},{kind:"flag",name:"mode",type:"enum",choices:["base","orchestrator"],required:!1,default:"base",constraint:"Persona mode. base for one hands-on unit; orchestrator when the unit itself needs decomposition across children. When you hold several parallel units of one kind, spawn ONE orchestrator child of that kind to own the fan-out rather than spawning the units yourself \u2014 unless you are already an orchestrator of that kind, whose job is exactly that fan-out."},{kind:"flag",name:"cwd",type:"path",required:!1,constraint:"Pin the node to this directory. Defaults to the spawner\u2019s directory for a managed child, and to the directory this command runs in for a root."},{kind:"flag",name:"name",type:"string",required:!1,constraint:"Display name."},{kind:"flag",name:"parent",type:"string",required:!1,constraint:"Parent node id. Defaults to the calling node."},{kind:"flag",name:"node-id",type:"string",required:!1,constraint:"Exact id for the new node; lowercase letters, digits, and hyphens only, at most 128 characters. Rejected if already present."},{kind:"flag",name:"root",type:"bool",required:!1,constraint:"Spawn an independent root with no parent or subscription. Mutually exclusive with --worktree."},{kind:"flag",name:"resident",type:"bool",required:!1,constraint:"Birth the node as resident: it parks and stays wakeable without being forced to submit a final. Pass it ONLY when the user will open this node\u2019s viewer pane and work with it back and forth; a child that only other nodes message stays terminal. Applies to managed children and roots; roots default to resident."},{kind:"flag",name:"terminal",type:"bool",required:!1,constraint:"Birth the node as terminal: it finalizes when its work is done and leaves nothing wakeable behind. Only meaningful with --root, whose default is resident; managed children are already terminal. Pass it for bounded programmatic work no one will open a viewer on. Mutually exclusive with --resident."},{kind:"flag",name:"worktree",type:"string",required:!1,constraint:"Local base branch for a crouter-managed worktree for this child. Mutually exclusive with --root."},{kind:"flag",name:"fork-from",type:"string",required:!1,constraint:"Fork the new node from an existing node id, absolute session path, or partial pi session uuid."},{kind:"flag",name:"model",type:"string",required:!1,constraint:"Durable model override. Omit unless the task or governing guidance requires a specific model.",focusedHelp:{whenToUse:"Use only when the user, task, or governing agent guidance already requires a specific provider, model, capability tier, or family. Omit it for routine delegation: the selected persona kind and profile own normal model selection, and review personas may enforce a quality floor.",value:`Accepted forms: ${K}. Concrete provider/id requests must be registered. Portable provider/tier, bare-tier, and family-alias requests resolve through the configured model ladders.`,effects:["The resolved concrete override is stored on the node and in its launch recipe, so every launch and revive uses that exact provider/model.","Portable tiers and aliases resolve through the configured ladders; a persona quality floor may raise a weaker request before its resolved model is stored."]}},{kind:"flag",name:"profile",type:"string",required:!1,constraint:"Profile override. Use only when the task needs different project purview, memory, or environment; otherwise omit for normal inheritance or selection.",focusedHelp:{whenToUse:"Use only when the work must run under a different profile because it needs that profile\u2019s project purview, memory store, stored environment, or defaults. Do not use it merely to change the working directory, persona kind, model, or graph ownership; those have separate parameters.",value:"Pass a profile id or name from the <profiles> list below; a close-enough name resolves to the nearest profile and the choice is reported on stderr. Omit it inside a node to inherit the caller\u2019s profile; outside a node, omission runs normal cwd-based profile selection.",effects:["The selected profile id is stored on the node and supplies its profile-scoped config, memory, environment, and injected bearings.","It does not change the parent or subscription; --cwd separately pins the working directory."],dynamicState:o(()=>V(),"dynamicState")}},{kind:"flag",name:"situational-context",type:"string",required:!1,constraint:"Hidden ambient context appended to injected bearings, never visible chat."},{kind:"flag",name:"no-kickoff",type:"bool",required:!1,hidden:!0,constraint:"With --root, start the broker and session idle without a first message or model turn. Mutually exclusive with a prompt and --mode orchestrator."},{kind:"flag",name:"deadline",type:"string",required:!1,constraint:"Positive, representable wall-clock duration from spawn. Grammar: one or more positive integer-unit parts; units: s, m, h, d; adjacent parts are summed. Omit for no deadline."},{kind:"flag",name:"outcome-action",type:"string",required:!1,constraint:"Declared human-action name that receives the node outcome. Grammar: 1\u2013128 ASCII letters, digits, dots, underscores, or hyphens; starts with a letter or digit. Omit when no external delivery target is needed."},{kind:"flag",name:"outcome-payload",type:"string",required:!1,constraint:"JSON value, serialized at most 64 KiB, frozen and echoed to --outcome-action. Requires --outcome-action."},{kind:"flag",name:"output-schema",type:"string",required:!1,constraint:"Replace prose completion with a schema-constrained final result. Use only when its consumer requires fixed fields.",focusedHelp:{whenToUse:"Use only when the node\u2019s consumer needs a machine-checkable final object with fixed fields. Omit it for ordinary delegation or when a prose report is enough; structured output replaces the completion protocol, and an over-constrained schema can force retries.",value:`Pass the JSON Schema the result must satisfy. ${J} ${B}`,effects:["The node must answer with `crtr push result` and cannot finish until the result is accepted; a plain `crtr push final` is blocked while the request is pending.",$,"The managed parent wakes through its existing subscription when the final report arrives; an independent root has no subscriber to wake.","An accepted result, or a decline, removes the request and terminates the node."]}}]}o(se,"nodeNewParams");function de(){return[{name:"node_id",type:"string",required:!0,constraint:"New node id."},{name:"name",type:"string",required:!0,constraint:"Display name."},{name:"frozen_at",type:"string",required:!1,constraint:"Present when a managed child exists but capacity deferred its broker start."},...R()?[{name:"window",type:"string",required:!1,constraint:"tmux window id when a viewer opens."},{name:"session",type:"string",required:!1,constraint:"tmux session when a viewer opens."}]:[],{name:"follow_up",type:"string",required:!0,constraint:"Managed child: continue unrelated work or stop; its final report wakes you. Root: hand it off; no report wakes you."}]}o(de,"nodeNewOutput");function le(){return["Creates nodes/<id>/ in the canvas home, indexes the node in canvas.db, and starts its detached broker engine.","A managed child creates an active parent subscription; its pushes wake the parent. --root creates an independent node with spawned_by provenance and no parent subscription.","--worktree creates a managed worktree at ~/.crouter/canvas/worktrees/<node-id>/ on a new crtr/<node-id> branch.",$,"--deadline persists a wall-clock deadline from spawn; expiry cancels the node and records a failure outcome with reason deadline_exceeded.","--outcome-action registers one resolved local human-action target. When the node settles, crouter retries delivery of its outcome document until the target accepts it or permanently rejects it; --outcome-payload is frozen and echoed in that document.",...R()?["--root opens a viewer for the new node in the current tmux session."]:[]]}o(le,"nodeNewEffects");async function ce(e){const t=e.prompt??"",n=e.noKickoff===!0;if(!n&&t.trim()==="")throw new r({error:"empty_prompt",message:"a prompt is required (stdin or positional)",next:"Pipe a task on stdin or pass it as an argument, or pass --no-kickoff to spawn an idle node with none."});if(n&&t.trim()!=="")throw new r({error:"no_kickoff_with_prompt",message:"--no-kickoff cannot be combined with a prompt",field:"no-kickoff",next:"Drop --no-kickoff, or drop the prompt."});const i=e.kind,s=e.mode??"base",c=e.cwd?.trim(),h=c!==void 0&&c!==""?oe(c):void 0,O=e.name,I=e.parent,a=e.root===!0,N=e.resident===!0,P=e.terminal===!0;if(N&&P)throw new r({error:"lifecycle_conflict",message:"--resident and --terminal cannot both be passed",field:"terminal",next:"Pass the one birth lifecycle you want, or neither to take the default (resident for --root, terminal for a managed child)."});const f=e.worktree;if(f!==void 0&&f.trim()==="")throw new r({error:"worktree_base_required",message:"--worktree requires a base branch",field:"worktree",next:"Pass an existing local branch that landing can fast-forward."});const m=f?.trim(),S=e.forkFrom,p=e.model?.trim();if(p==="")throw new r({error:"empty_spec",message:"a model spec is required",field:"model",next:`Run \`crtr node new --model -h\` and read the focused contract. ${Y}`});const T=e.profile,D=T===void 0?void 0:X(T).profileId,w=e.situationalContext?.trim(),C=w!==void 0&&w!==""?w:void 0,E=W(e.outputSchema),U=E!==null?JSON.stringify(E):null,u=e.deadline;if(u!==void 0){const l=G(u),F=l===null?Number.NaN:new Date(Date.now()+l).getTime();if(l===null||!Number.isFinite(l)||l<=0||!Number.isFinite(F))throw new r({error:"invalid_deadline",message:"--deadline must be a positive representable duration",field:"deadline",next:"Pass positive integer-unit parts using s, m, h, or d."})}const k=e.outcomeAction,y=e.outcomePayload;if(y!==void 0&&k===void 0)throw new r({error:"outcome_payload_requires_action",message:"--outcome-payload requires --outcome-action",field:"outcome-payload",next:"Pass the declared delivery action with --outcome-action."});let g;if(y!==void 0)try{g=JSON.parse(y)}catch{throw new r({error:"invalid_outcome_payload",message:"--outcome-payload must be valid JSON",field:"outcome-payload",next:"Pass one valid JSON value."})}const b=e.nodeId?.trim();if(a&&m!==void 0)throw new r({error:"worktree_root_conflict",message:"--worktree is mutually exclusive with --root",field:"worktree",next:"Drop either --root or --worktree."});if(n&&!a)throw new r({error:"no_kickoff_requires_root",message:"--no-kickoff is only valid with --root",field:"no-kickoff",next:"Add --root, or drop --no-kickoff and provide a prompt."});if(n&&s==="orchestrator")throw new r({error:"no_kickoff_orchestrator_unsupported",message:"--no-kickoff cannot be combined with --mode orchestrator",field:"no-kickoff",next:"Drop --no-kickoff and provide a prompt, or spawn in base mode."});const v=z(),j=I??v;x("node_new.create_start",{root:a});const d=await Z().createNode({...i!==void 0?{kind:i}:{},mode:s,cwd:process.cwd(),...h!==void 0&&h!==""?{pin_cwd:h}:{},...O!==void 0?{name:O}:{},prompt:t,...a?{root:!0}:{parent:j??null},...v!==void 0?{creator:v}:{},...N?{root_lifecycle:"resident"}:{},...P?{root_lifecycle:"terminal"}:{},...m!==void 0?{worktree:m}:{},...S!==void 0?{fork_from:S}:{},...p!==void 0?{model:p}:{},...D!==void 0?{profile:D}:{},...C!==void 0?{situational_context:C}:{},...n?{no_kickoff:!0}:{},...U!==null?{output_schema:U}:{},...u!==void 0?{deadline:u}:{},...k!==void 0?{outcome_delivery:{action:k,...g===void 0?{}:{payload:g}}}:{},...b!==void 0&&b!==""?{node_id:b}:{},...a?{prefer_warm:!0}:{}}).catch(te);x("node_new.node_created",{node:d.node_id});let _={};a&&(_=ne(d.node_id,d.cwd,d.name)),a&&x("node_new.viewer_window_opened");const A=!a&&d.frozen_at!==null;return{node_id:d.node_id,name:d.name,...A?{frozen_at:d.frozen_at}:{},window:_.window,session:_.session,follow_up:a?n?"Independent root spawned idle. No kickoff turn ran; hand it off or attach and prompt it. No report wakes you.":"Independent root spawned. You are not subscribed, so its finish does not wake you; hand it off and move on.":A?"Child row exists, but no broker started because capacity is full. It is frozen and will launch when a broker slot frees; its final report wakes you then.":await ie(j)}}o(ce,"runNodeCreation");const Te=H({name:"new",description:"create and start a node immediately",whenToUse:"a unit of work is genuinely separable from what you are doing: a bounded subtask you would otherwise grind out inline, several independent units worth running in parallel (usually via one orchestrator child of the matching kind rather than a flat fan-out from you), a scouting pass over unfamiliar code, a change that wants its own git worktree, or an answer you need in a fixed shape rather than as prose",tier:"important",help:{name:"node new",summary:"create a node immediately and start its detached broker",guide:"The prompt is the child\u2019s entire brief: it wakes with this prompt, its persona, and ambient bearings \u2014 none of your conversation carries over. State the outcome and constraints. Pass an implementation plan only when it is already settled or necessary to preserve an approved decision; otherwise, let the child investigate and choose how. Give the reason along with the request: the larger goal this serves and what the child's output enables, so the child resolves ambiguity toward your intent instead of guessing. Name by absolute path every artifact the task depends on (a spec, an explore report, an earlier child's findings); the child inherits only the files the prompt names. When the report must carry something specific\u2014findings inline, or paths to artifacts it wrote\u2014say so in the prompt.",params:se(),output:de(),dynamicState:o(()=>ae(),"dynamicState"),outputKind:"object",effects:le()},run:o(e=>ce(e),"run"),render:o(e=>{const t=e.window?` in window ${e.window}`:"",n=[`Spawned "${e.name}" (${e.node_id})${t}.`];return e.session&&n.push(`- session: ${e.session}`),n.push("",String(e.follow_up)),n.join(`
+`)},"render")});export{Se as assertKind,ie as childFollowUp,ae as kindsStateBlock,Te as nodeNew};