@crouton-kit/crouter 0.3.8 → 0.3.12

package/dist/core/resolver.js

@@ -1,7 +1,7 @@
 import { join, relative, sep, dirname } from 'node:path';
 import { SCOPE_SKILL_PLUGIN, SKILL_ENTRY_FILE, SKILLS_DIR, skillConfigKey, } from '../types.js';
 import { readConfig } from './config.js';
-import { listDirs, pathExists, readText, walkFiles, } from './fs-utils.js';
+import { listDirs, pathExists, readText, readTextIfExists, walkFiles, } from './fs-utils.js';
 import { readMarketplaceManifest, readPluginManifest } from './manifest.js';
 import { parseFrontmatter } from './frontmatter.js';
 import { ambiguous, notFound, usage } from './errors.js';
@@ -240,12 +240,62 @@ export function resolveSkill(rawName, opts = {}) {
     const direct = findSkillMatches(skillName, pluginQualifier, effectiveScope, effectivePluginFilter);
     if (direct.length > 0)
         return pickMatch(direct, skillName, pluginQualifier);
+    // Leaf-name fallback: the caller supplied only the final path segment
+    // (e.g. "cli-design" for "ai/interface/cli-design"). A direct path lookup
+    // missed because the skill lives under a nested path. Match by last segment.
+    const byLeaf = findSkillsByLeaf(skillName, pluginQualifier, effectiveScope, effectivePluginFilter);
+    if (byLeaf.length === 1)
+        return byLeaf[0];
+    if (byLeaf.length > 1) {
+        throw ambiguous(formatLeafAmbiguousMessage(skillName, byLeaf), {
+            skill: skillName,
+            candidates: byLeaf.map((m) => ({
+                id: formatSkillId(m),
+                plugin: m.plugin,
+                scope: m.scope,
+                path: m.path,
+            })),
+            next: 'Multiple skills share this leaf name. Re-run with one of the full paths in candidates.',
+        });
+    }
     throw notFound(formatNotFoundMessage(rawName, skillName, pluginQualifier), {
         skill: skillName,
         plugin: pluginQualifier,
         scope: parsed.scope,
     });
 }
+/** Canonical, unambiguous identifier for a skill. Scope-root skills are
+ *  qualified by scope; plugin skills by plugin name. */
+function formatSkillId(s) {
+    return s.plugin === SCOPE_SKILL_PLUGIN ? `${s.scope}/${s.name}` : `${s.plugin}/${s.name}`;
+}
+/** Match skills whose final path segment equals `leaf`. Only meaningful when
+ *  `leaf` is a bare segment (no slash) — a slashed query can never equal a
+ *  single segment, so this returns empty and the caller falls through. */
+function findSkillsByLeaf(leaf, pluginQualifier, scope, pluginFilter) {
+    if (leaf.includes('/'))
+        return [];
+    let all;
+    try {
+        all = scope ? listAllSkills(scope) : listAllSkills();
+    }
+    catch {
+        return [];
+    }
+    return all.filter((s) => {
+        if ((s.name.split('/').pop() ?? s.name) !== leaf)
+            return false;
+        if (pluginQualifier && s.plugin !== pluginQualifier)
+            return false;
+        if (pluginFilter && s.plugin !== pluginFilter)
+            return false;
+        return true;
+    });
+}
+function formatLeafAmbiguousMessage(leaf, matches) {
+    const ids = matches.map(formatSkillId).join(', ');
+    return `ambiguous skill: ${leaf} matches multiple skills: ${ids}`;
+}
 function findSkillMatches(name, pluginQualifier, scope, pluginFilter) {
     const plugins = scope ? listInstalledPlugins(scope) : listAllPlugins();
     const enabledPlugins = plugins.filter((p) => p.enabled);
@@ -332,7 +382,7 @@ function formatNotFoundMessage(rawName, skillName, pluginQualifier) {
         lines.push(`       did you mean: ${formatted.join(', ')}`);
     }
     else {
-        lines.push('       run `crtr skill list` or `crtr skill search <query>` to discover skills');
+        lines.push('       run `crtr skill find list` or `crtr skill find search <query>` to discover skills');
     }
     return lines.join('\n');
 }
@@ -484,6 +534,114 @@ export function findMarketplaceByName(name, scope) {
     }
     return null;
 }
+export function resolveCategory(name, opts = {}) {
+    const parsed = parseSkillQualifier(name);
+    if (parsed.segments.length === 0)
+        return null;
+    const effectiveScope = opts.scope ?? parsed.scope;
+    let pluginQualifier;
+    let subpath;
+    if (opts.pluginFilter !== undefined) {
+        pluginQualifier = opts.pluginFilter;
+        const sub = parsed.segments.join('/');
+        subpath = sub || undefined;
+    }
+    else if (parsed.segments.length > 1) {
+        const maybePlugin = parsed.segments[0];
+        const pluginMatch = findPluginByName(maybePlugin, effectiveScope) ??
+            (effectiveScope === undefined ? null : findPluginByName(maybePlugin));
+        if (pluginMatch !== null) {
+            pluginQualifier = maybePlugin;
+            subpath = parsed.segments.slice(1).join('/');
+        }
+        else {
+            pluginQualifier = undefined;
+            subpath = parsed.segments.join('/');
+        }
+    }
+    else {
+        const maybePlugin = parsed.segments[0];
+        const pluginMatch = findPluginByName(maybePlugin, effectiveScope) ??
+            (effectiveScope === undefined ? null : findPluginByName(maybePlugin));
+        if (pluginMatch !== null) {
+            pluginQualifier = maybePlugin;
+            subpath = undefined;
+        }
+        else {
+            pluginQualifier = undefined;
+            subpath = maybePlugin;
+        }
+    }
+    let skills;
+    let dir;
+    let id;
+    let resolvedScope;
+    if (pluginQualifier !== undefined) {
+        const plugin = findPluginByName(pluginQualifier, effectiveScope) ??
+            (effectiveScope === undefined ? null : findPluginByName(pluginQualifier));
+        if (!plugin)
+            return null;
+        resolvedScope = plugin.scope;
+        const allPluginSkills = listSkillsInPlugin(plugin);
+        if (subpath === undefined) {
+            skills = allPluginSkills;
+            dir = join(plugin.root, SKILLS_DIR);
+            id = pluginQualifier;
+        }
+        else {
+            skills = allPluginSkills.filter((s) => s.name.startsWith(subpath + '/'));
+            dir = join(plugin.root, SKILLS_DIR, ...subpath.split('/'));
+            id = `${pluginQualifier}/${subpath}`;
+        }
+    }
+    else if (subpath !== undefined) {
+        const scope = effectiveScope ?? 'user';
+        resolvedScope = scope;
+        const skillsRoot = scopeSkillsDir(scope);
+        if (!skillsRoot)
+            return null;
+        const allScopeSkills = listScopeRootSkills(scope);
+        skills = allScopeSkills.filter((s) => s.name.startsWith(subpath + '/'));
+        dir = join(skillsRoot, ...subpath.split('/'));
+        id = `${scope}/${subpath}`;
+    }
+    else {
+        return null;
+    }
+    if (skills.length === 0)
+        return null;
+    const indexMd = join(dir, 'index.md');
+    const indexPath = pathExists(indexMd) ? indexMd : undefined;
+    return { id, plugin: pluginQualifier, scope: resolvedScope, dir, indexPath, skills };
+}
+export function buildCategoryIndex(cat) {
+    const lines = [];
+    lines.push(`# ${cat.id} — ${cat.skills.length} skills`);
+    lines.push('');
+    if (cat.indexPath !== undefined) {
+        const authored = readTextIfExists(cat.indexPath);
+        if (authored !== null) {
+            const { body } = parseFrontmatter(authored);
+            const trimmed = body.trim();
+            if (trimmed.length > 0) {
+                lines.push(trimmed);
+                lines.push('');
+            }
+        }
+    }
+    lines.push('## Skills');
+    const sorted = [...cat.skills].sort((a, b) => a.name.localeCompare(b.name));
+    for (const skill of sorted) {
+        const fullId = skill.plugin === SCOPE_SKILL_PLUGIN
+            ? `${skill.scope}/${skill.name}`
+            : `${skill.plugin}/${skill.name}`;
+        const desc = skill.frontmatter.description ?? '(no description)';
+        lines.push(`- \`${fullId}\` — ${desc}`);
+    }
+    lines.push('');
+    lines.push(`Read one with \`crtr skill read <full-id>\`. Narrow with \`crtr skill find list --plugin ${cat.plugin ?? cat.id}\`.`);
+    return lines.join('\n');
+}
 export function scopeRootsLabel() {
     const proj = projectScopeRoot();
     return proj ? `project=${proj}, user=${userScopeRoot()}` : `user=${userScopeRoot()}`;

package/dist/core/runtime/front-door.d.ts

@@ -0,0 +1,10 @@
+import type { RootDef } from './../command.js';
+/** Env marker set on every pi the front door boots. Its presence means we are
+ *  already inside a front-door-booted root, so a nested front-door launch must
+ *  be refused — otherwise a removed/renamed subcommand that a child pi re-runs
+ *  (e.g. `crtr node -h`) fork-bombs pi until the machine must be rebooted. */
+export declare const FRONT_DOOR_ENV = "CRTR_FRONT_DOOR";
+/** If this invocation is a front-door (root) launch, boot it and never return.
+ *  Returns false when it's a recognized subcommand / help / unknown token (let
+ *  the dispatcher handle it — for unknown tokens it errors cleanly). */
+export declare function maybeBootRoot(root: RootDef, argv: string[]): boolean;

package/dist/core/runtime/front-door.js

@@ -0,0 +1,97 @@
+// The front door — bare `crtr` boots a resident root node.
+//
+//   crtr                         → boot a root in this terminal (no prompt)
+//   crtr [dir]                   → root pinned to dir
+//   crtr [dir] ["prompt"]        → root with a starter prompt
+//   crtr --name NAME ...         → named root
+//   crtr <subcommand> ...        → falls through to the normal dispatcher
+//   crtr -h | --help             → root help (dispatcher)
+//
+// This is the only place that distinguishes "I want to live here" (root) from
+// the subcommand surface. It runs before the dispatcher; if it boots, pi takes
+// over the terminal and the process never returns.
+import { existsSync, statSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { bootRoot } from './spawn.js';
+function isDir(p) {
+    try {
+        return existsSync(p) && statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/** Parse `[dir] [prompt]` positionals + `--name`/`--kind` flags out of the
+ *  leftover tokens after the bare `crtr`. */
+function parseRootArgs(tokens) {
+    let cwd = process.cwd();
+    let name;
+    let kind;
+    const positionals = [];
+    for (let i = 0; i < tokens.length; i++) {
+        const t = tokens[i];
+        if (t === '--name') {
+            name = tokens[++i];
+        }
+        else if (t === '--kind') {
+            kind = tokens[++i];
+        }
+        else if (t.startsWith('--')) {
+            // ignore unknown flags for the front door
+        }
+        else {
+            positionals.push(t);
+        }
+    }
+    // First positional that is an existing dir → cwd; the rest → prompt.
+    if (positionals.length > 0 && isDir(resolvePath(positionals[0]))) {
+        cwd = resolvePath(positionals.shift());
+    }
+    const prompt = positionals.length > 0 ? positionals.join(' ') : undefined;
+    return { cwd, prompt, name, kind };
+}
+/** Env marker set on every pi the front door boots. Its presence means we are
+ *  already inside a front-door-booted root, so a nested front-door launch must
+ *  be refused — otherwise a removed/renamed subcommand that a child pi re-runs
+ *  (e.g. `crtr node -h`) fork-bombs pi until the machine must be rebooted. */
+export const FRONT_DOOR_ENV = 'CRTR_FRONT_DOOR';
+/** If this invocation is a front-door (root) launch, boot it and never return.
+ *  Returns false when it's a recognized subcommand / help / unknown token (let
+ *  the dispatcher handle it — for unknown tokens it errors cleanly). */
+export function maybeBootRoot(root, argv) {
+    const tokens = argv.slice(2);
+    const first = tokens[0];
+    // Recursion guard: never boot a root from inside a front-door-booted pi.
+    // This is the hard backstop against fork bombs — even a future footgun where
+    // a child re-invokes a removed subcommand cannot loop, because the second
+    // boot is refused and falls through to the dispatcher.
+    if (process.env[FRONT_DOOR_ENV])
+        return false;
+    // `crtr -h` / `crtr --help` / `crtr --version` → dispatcher (root help).
+    if (first === '-h' || first === '--help' || first === '--version' || first === '-v') {
+        return false;
+    }
+    // A recognized subcommand → dispatcher.
+    const subtreeNames = new Set(root.subtrees.map((s) => s.name));
+    if (first !== undefined && subtreeNames.has(first))
+        return false;
+    // The front door boots pi ONLY on an unambiguous "live here" signal:
+    //   • bare `crtr`                  (no tokens)
+    //   • `crtr <dir> [prompt]`        (first positional is an existing dir)
+    //   • `crtr "multi word prompt"`   (first token contains whitespace)
+    // Anything else — a bare word like `job`, or a leading flag — is treated as a
+    // mistyped/removed subcommand and handed to the dispatcher, which errors with
+    // "unknown subcommand: <token>". Booting pi for such tokens is what let the
+    // renamed `agent`/`job` subcommands fork-bomb the front door.
+    if (first !== undefined) {
+        const looksLikePrompt = /\s/.test(first);
+        const looksLikeDir = !first.startsWith('-') && isDir(resolvePath(first));
+        if (!looksLikePrompt && !looksLikeDir)
+            return false;
+    }
+    // Unambiguous front-door launch → boot a resident root inline (exec pi in
+    // this terminal). Does not return.
+    const args = parseRootArgs(tokens);
+    bootRoot({ ...args, placement: 'inline' });
+    return true;
+}

package/dist/core/runtime/kickoff.d.ts

@@ -0,0 +1,23 @@
+import { type NodeMeta } from '../canvas/index.js';
+/** The goal file — the prompt/task a node was spawned with, persisted at birth
+ *  so a fresh revive can re-read its mandate. */
+export declare function goalPath(nodeId: string): string;
+export declare function readGoal(nodeId: string): string | null;
+/** Persist the spawning prompt as the node's goal. No-op for an empty prompt
+ *  (e.g. a bare root). Idempotent enough — call once at spawn/boot. */
+export declare function writeGoal(nodeId: string, text: string): void;
+/** The yield-message file — a short note `crtr node yield` records for the next
+ *  revive ("on wake, do X"). Consumed (deleted) when the revive reads it. */
+export declare function yieldMessagePath(nodeId: string): string;
+export declare function writeYieldMessage(nodeId: string, text: string): void;
+/** Read AND delete the yield message — it is a one-shot handoff to the next
+ *  revive, so a later crash-revive never resurfaces a stale note. */
+export declare function consumeYieldMessage(nodeId: string): string | null;
+/** List the node's context/ dir (filenames, sorted). Empty when absent. */
+export declare function listContextDir(nodeId: string): string[];
+/** Build the auto-injected first message for a FRESH revive of `meta`. Reads
+ *  the node's goal, roadmap, context dir, feed, and one-shot yield message off
+ *  disk and frames them so the revived node can rebuild its bearings in one
+ *  turn. Side effects: consumes the yield message and advances the feed cursor
+ *  (both are "read" by surfacing them here). */
+export declare function buildReviveKickoff(meta: NodeMeta): string;

package/dist/core/runtime/kickoff.js

@@ -0,0 +1,134 @@
+// The revive kickoff — the message auto-injected as a node's first turn when it
+// comes back FRESH (a refresh-yield, or `canvas revive --fresh`). The node's
+// in-memory context is gone, so this message IS its bearings: everything is
+// read from disk and framed so the node can rebuild and continue without a
+// round-trip. Resuming a saved conversation needs none of this (the
+// conversation already holds the context).
+//
+// Layout (the framing a revived node sees):
+//   <goal file=…>…</goal>                  the mandate it was spawned with
+//   <roadmap file=…>…</roadmap>            its evolving plan
+//   <context-dir path=…>…</context-dir>    what artifacts exist on disk
+//   <feed>Awaiting N nodes … digest</feed> who it waits on + unread reports
+//   <yield-message>…</yield-message>       the note its prior self left on yield
+//
+// The goal + yield-message are companion files in the node's context dir; the
+// yield-message is one-shot (consumed on the next revive).
+import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync, readdirSync, } from 'node:fs';
+import { join } from 'node:path';
+import { contextDir, getNode, subscriptionsOf, } from '../canvas/index.js';
+import { readRoadmap, roadmapPath } from './roadmap.js';
+import { readInboxSince, readCursor, writeCursor, coalesce, } from '../feed/inbox.js';
+// ---------------------------------------------------------------------------
+// Companion context files: the goal (the spawning mandate) and the one-shot
+// yield message (a note from the prior self to the revived self).
+// ---------------------------------------------------------------------------
+/** The goal file — the prompt/task a node was spawned with, persisted at birth
+ *  so a fresh revive can re-read its mandate. */
+export function goalPath(nodeId) {
+    return join(contextDir(nodeId), 'initial-prompt.md');
+}
+export function readGoal(nodeId) {
+    const p = goalPath(nodeId);
+    return existsSync(p) ? readFileSync(p, 'utf8') : null;
+}
+/** Persist the spawning prompt as the node's goal. No-op for an empty prompt
+ *  (e.g. a bare root). Idempotent enough — call once at spawn/boot. */
+export function writeGoal(nodeId, text) {
+    const body = text.trim();
+    if (body === '')
+        return;
+    mkdirSync(contextDir(nodeId), { recursive: true });
+    writeFileSync(goalPath(nodeId), body + '\n', 'utf8');
+}
+/** The yield-message file — a short note `crtr node yield` records for the next
+ *  revive ("on wake, do X"). Consumed (deleted) when the revive reads it. */
+export function yieldMessagePath(nodeId) {
+    return join(contextDir(nodeId), 'yield-message.md');
+}
+export function writeYieldMessage(nodeId, text) {
+    const body = text.trim();
+    if (body === '')
+        return;
+    mkdirSync(contextDir(nodeId), { recursive: true });
+    writeFileSync(yieldMessagePath(nodeId), body + '\n', 'utf8');
+}
+/** Read AND delete the yield message — it is a one-shot handoff to the next
+ *  revive, so a later crash-revive never resurfaces a stale note. */
+export function consumeYieldMessage(nodeId) {
+    const p = yieldMessagePath(nodeId);
+    if (!existsSync(p))
+        return null;
+    const body = readFileSync(p, 'utf8');
+    try {
+        rmSync(p);
+    }
+    catch { /* best-effort */ }
+    return body.trim() !== '' ? body : null;
+}
+/** List the node's context/ dir (filenames, sorted). Empty when absent. */
+export function listContextDir(nodeId) {
+    const dir = contextDir(nodeId);
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir).sort();
+}
+// ---------------------------------------------------------------------------
+// Feed block — who the node is awaiting, plus a drained digest of unread
+// reports. Draining here advances the cursor: the revived node has now "read"
+// the feed, so a later `crtr feed read` shows only what arrives afterward.
+// ---------------------------------------------------------------------------
+function feedBlock(nodeId) {
+    // Awaiting = active subscriptions whose publisher is still live (active|idle).
+    const awaiting = subscriptionsOf(nodeId)
+        .filter((s) => s.active)
+        .map((s) => getNode(s.node_id))
+        .filter((m) => m !== null && (m.status === 'active' || m.status === 'idle'));
+    const lines = [];
+    lines.push(`Awaiting ${awaiting.length} node${awaiting.length === 1 ? '' : 's'}.`);
+    for (const m of awaiting)
+        lines.push(`  - ${m.name} (${m.node_id}) — ${m.status}`);
+    const cursor = readCursor(nodeId);
+    const entries = readInboxSince(nodeId, cursor);
+    if (entries.length > 0) {
+        writeCursor(nodeId, entries[entries.length - 1].ts);
+        lines.push('', coalesce(entries));
+    }
+    else {
+        lines.push('', '(no unread reports)');
+    }
+    return `<feed>\n${lines.join('\n')}\n</feed>`;
+}
+// ---------------------------------------------------------------------------
+// buildReviveKickoff — assemble the full fresh-revive first message.
+// ---------------------------------------------------------------------------
+/** Build the auto-injected first message for a FRESH revive of `meta`. Reads
+ *  the node's goal, roadmap, context dir, feed, and one-shot yield message off
+ *  disk and frames them so the revived node can rebuild its bearings in one
+ *  turn. Side effects: consumes the yield message and advances the feed cursor
+ *  (both are "read" by surfacing them here). */
+export function buildReviveKickoff(meta) {
+    const nodeId = meta.node_id;
+    // Consume the one-shot yield note first so it never shows in the dir listing.
+    const yieldMsg = consumeYieldMessage(nodeId);
+    const parts = [
+        'You have been revived fresh after a context refresh — your previous in-memory ' +
+            'context is gone, by design. Everything below was just read from disk; it is your ' +
+            'full bearings. Rebuild from it and continue toward your goal.',
+    ];
+    const goal = readGoal(nodeId);
+    if (goal !== null && goal.trim() !== '') {
+        parts.push(`<goal file="${goalPath(nodeId)}">\n${goal.trim()}\n</goal>`);
+    }
+    const roadmap = readRoadmap(nodeId);
+    parts.push(`<roadmap file="${roadmapPath(nodeId)}">\n${roadmap !== null && roadmap.trim() !== '' ? roadmap.trim() : '(no roadmap on disk yet)'}\n</roadmap>`);
+    const files = listContextDir(nodeId);
+    parts.push(`<context-dir path="${contextDir(nodeId)}">\n${files.length > 0 ? files.join('\n') : '(empty)'}\n</context-dir>`);
+    parts.push(feedBlock(nodeId));
+    parts.push(yieldMsg !== null
+        ? `<yield-message>\n${yieldMsg.trim()}\n</yield-message>`
+        : '<yield-message/>');
+    parts.push('If there is work to do, perform it. Otherwise stop — `crtr push final "<result>"` ' +
+        'if the goal is met, or end your turn to stay dormant awaiting your workers.');
+    return parts.join('\n\n');
+}

package/dist/core/runtime/launch.d.ts

@@ -0,0 +1,34 @@
+import type { NodeMeta, LaunchSpec, Mode } from '../canvas/index.js';
+export declare const CANVAS_STOPHOOK_PATH: string;
+export declare const CANVAS_INBOX_WATCHER_PATH: string;
+export declare const CANVAS_NAV_PATH: string;
+/** The canvas extensions every node loads, in order: stophook (routing +
+ *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
+ *  graph chrome). All self-gate on CRTR_NODE_ID. */
+export declare const CANVAS_EXTENSIONS: string[];
+/** Bare model aliases resolve to the anthropic provider under pi (avoids the
+ *  bedrock default). Anything with a `/` or an unknown name passes through. */
+export declare function normalizeModel(model: string): string;
+/** Compose a node's full pi launch recipe from its persona. The two canvas
+ *  extensions are always first; persona-declared extensions follow. */
+export declare function buildLaunchSpec(kind: string, mode: Mode, opts?: {
+    extraEnv?: Record<string, string>;
+}): {
+    launch: LaunchSpec;
+    lifecycle: 'terminal' | 'resident';
+    skills: string[];
+};
+export interface PiInvocation {
+    /** argv after the `pi` binary. */
+    argv: string[];
+    /** env to merge into the process. */
+    env: Record<string, string>;
+}
+/** Construct the pi invocation for a node.
+ *  - fresh start: pass `prompt` (the node's first user message), no resume.
+ *  - revive idle/done: pass `resumeSessionId` to `--resume` (keeps conversation).
+ *  - refresh-yield: fresh again (no resume) — the node re-reads its roadmap. */
+export declare function buildPiArgv(meta: NodeMeta, opts?: {
+    prompt?: string;
+    resumeSessionId?: string;
+}): PiInvocation;

package/dist/core/runtime/launch.js

@@ -0,0 +1,85 @@
+// The launch spec — how a node becomes (or comes back as) a running pi process.
+//
+// pi-only. No claude branch — we are a super-opinionated system. A node's
+// LaunchSpec (persisted in meta.json) is the canonical recipe the daemon
+// replays to revive it faithfully: `--resume` to wake a done/idle node (keeps
+// its conversation), or fresh (against the context dir) for a refresh-yield.
+// The spec is rewritten on every polymorph (base→orchestrator) so a node
+// always comes back as its *current* self.
+import { existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolve as resolvePersona } from '../personas/index.js';
+import { nodeEnv } from './nodes.js';
+// ---------------------------------------------------------------------------
+// The two canvas pi-extensions every node loads. They self-gate on the live
+// {kind,mode} env, so the worker→orchestrator polymorph flips hook behavior
+// with no respawn.
+// ---------------------------------------------------------------------------
+function resolveExtension(name) {
+    const here = dirname(fileURLToPath(import.meta.url)); // dist/core/runtime or src/core/runtime
+    const candidates = [
+        join(here, '..', '..', 'pi-extensions', `${name}.js`),
+        join(here, '..', '..', 'pi-extensions', `${name}.ts`),
+    ];
+    return candidates.find((p) => existsSync(p)) ?? candidates[0];
+}
+export const CANVAS_STOPHOOK_PATH = resolveExtension('canvas-stophook');
+export const CANVAS_INBOX_WATCHER_PATH = resolveExtension('canvas-inbox-watcher');
+export const CANVAS_NAV_PATH = resolveExtension('canvas-nav');
+/** The canvas extensions every node loads, in order: stophook (routing +
+ *  telemetry + session-id capture), inbox-watcher (wake), nav (in-editor
+ *  graph chrome). All self-gate on CRTR_NODE_ID. */
+export const CANVAS_EXTENSIONS = [
+    CANVAS_STOPHOOK_PATH,
+    CANVAS_INBOX_WATCHER_PATH,
+    CANVAS_NAV_PATH,
+];
+/** Bare model aliases resolve to the anthropic provider under pi (avoids the
+ *  bedrock default). Anything with a `/` or an unknown name passes through. */
+export function normalizeModel(model) {
+    const bare = new Set(['sonnet', 'opus', 'haiku']);
+    if (bare.has(model))
+        return `anthropic/${model}`;
+    return model;
+}
+// ---------------------------------------------------------------------------
+// Build the launch spec from {kind, mode}
+// ---------------------------------------------------------------------------
+/** Compose a node's full pi launch recipe from its persona. The two canvas
+ *  extensions are always first; persona-declared extensions follow. */
+export function buildLaunchSpec(kind, mode, opts = {}) {
+    const p = resolvePersona(kind, mode);
+    const launch = {
+        model: p.model !== undefined ? normalizeModel(p.model) : undefined,
+        tools: p.tools,
+        extensions: [...CANVAS_EXTENSIONS, ...p.extensions],
+        systemPrompt: p.systemPrompt,
+        env: { ...(opts.extraEnv ?? {}) },
+    };
+    return { launch, lifecycle: p.lifecycle, skills: p.skills };
+}
+/** Construct the pi invocation for a node.
+ *  - fresh start: pass `prompt` (the node's first user message), no resume.
+ *  - revive idle/done: pass `resumeSessionId` to `--resume` (keeps conversation).
+ *  - refresh-yield: fresh again (no resume) — the node re-reads its roadmap. */
+export function buildPiArgv(meta, opts = {}) {
+    const spec = meta.launch;
+    const argv = [];
+    for (const ext of spec?.extensions ?? CANVAS_EXTENSIONS) {
+        argv.push('-e', ext);
+    }
+    argv.push('-n', meta.name);
+    if (opts.resumeSessionId !== undefined)
+        argv.push('--resume', opts.resumeSessionId);
+    if (spec?.model !== undefined)
+        argv.push('--model', spec.model);
+    if (spec?.tools !== undefined && spec.tools.length > 0)
+        argv.push('--tools', spec.tools.join(','));
+    if (spec?.systemPrompt !== undefined && spec.systemPrompt !== '') {
+        argv.push('--append-system-prompt', spec.systemPrompt);
+    }
+    if (opts.prompt !== undefined && opts.prompt !== '')
+        argv.push(opts.prompt);
+    return { argv, env: nodeEnv(meta) };
+}

package/dist/core/runtime/nodes.d.ts

@@ -0,0 +1,38 @@
+import { type NodeMeta, type Mode, type Lifecycle, type LaunchSpec } from '../canvas/index.js';
+/** Generate a node id in the same shape as job ids (time-sortable + random). */
+export declare function newNodeId(): string;
+export interface NodeContext {
+    nodeId: string | null;
+    parentNodeId: string | null;
+    kind: string | null;
+    mode: Mode | null;
+}
+/** Read the current node's identity from the environment. A spawned pi process
+ *  runs with CRTR_NODE_ID set; its own `crtr` invocations spawn children under
+ *  it by reading CRTR_NODE_ID as the parent. */
+export declare function currentNodeContext(): NodeContext;
+/** The env injected into a node's pi process. Self-gating extensions read
+ *  CRTR_KIND/CRTR_MODE to flip behavior on polymorph without a respawn; the
+ *  feed/inbox machinery reads CRTR_NODE_ID. */
+export declare function nodeEnv(meta: NodeMeta): Record<string, string>;
+export interface SpawnNodeOpts {
+    kind: string;
+    mode?: Mode;
+    lifecycle?: Lifecycle;
+    cwd: string;
+    name?: string;
+    /** Parent node id. Omit for a user-opened root. */
+    parent?: string | null;
+    /** New subscriptions this node opens default to passive when true. */
+    passiveDefault?: boolean;
+    /** Resolved pi launch recipe (from resolve(kind,mode)). */
+    launch?: LaunchSpec;
+    /** Override the generated id (e.g. when a caller pre-allocates one). */
+    nodeId?: string;
+}
+/** Create a node on the canvas and wire its spawn-time edges.
+ *
+ *  For a child (parent given): the parent auto-subscribes ACTIVE to the child
+ *  (so it's woken when the child finishes), and a spawned_by audit edge is
+ *  recorded. For a root (no parent): no edges, resident by default. */
+export declare function spawnNode(opts: SpawnNodeOpts): NodeMeta;