@north-light/api 0.3.580 → 0.3.587

package/dist/core/runtime/interactive-deliver.d.ts

@@ -0,0 +1,22 @@
+import type { MessageOrigin } from './stamp/protocol.js';
+/** Which engine call the broker routed a live deliver to (its ack `detail`):
+ *  idle → `prompt`, turn in flight → `steer`. */
+export type LiveDeliverRoute = 'prompt' | 'steer';
+/** What a live abort actually interrupted (its ack `detail`): an in-flight
+ *  agent turn, a running `!` bash command, or nothing (`idle`). */
+export type LiveInterruptOutcome = 'turn' | 'bash' | 'idle';
+/** Deliver `text` to a LIVE node's engine on its serialized frame loop. The
+ *  broker routes it itself (idle → prompt, streaming → steer) and acks once
+ *  routed; resolves with the route taken. `cards` are rendered runtime-card
+ *  envelopes placed ahead of the body inside that same frame handling, and
+ *  `origin` is the authorship the broker stamps onto the persisted message —
+ *  it rides the same frame as the body it describes. */
+export declare function deliverLive(nodeId: string, text: string, opts?: {
+    cards?: readonly string[];
+    origin?: MessageOrigin;
+}): Promise<LiveDeliverRoute>;
+/** Abort whatever a LIVE node's engine is doing (turn or `!` bash). Resolves
+ *  once the broker has PROCESSED the abort — which, on the single frame loop,
+ *  also implies every earlier-accepted deliver was already routed (so a
+ *  just-delivered send cannot start its turn after this resolves un-aborted). */
+export declare function interruptLive(nodeId: string): Promise<LiveInterruptOutcome>;

package/dist/core/runtime/interactive-deliver.js

@@ -0,0 +1,51 @@
+// interactive-deliver.ts — one-shot server-client delivery + interrupt against
+// a LIVE node broker over its view.sock. The daemon's interactive REST
+// vocabulary (`POST /v1/nodes/{id}/messages` with `delivery:'interactive'`, and
+// `POST /v1/nodes/{id}/interrupt`) rides these instead of the durable inbox, so
+// a live conversation's send and stop share the broker's ONE serialized frame
+// loop — the same ordering a tmux viewer gets — closing the send/abort race the
+// two-channel inbox path had (send rode the watcher's ~1.8s inject; stop rode a
+// direct abort frame; no shared ordering).
+//
+// Both ride the shared one-shot writable round-trip (broker-request.ts):
+// connect → `hello` as controller → send the correlated frame → await its ack.
+// A connection failure BEFORE establishment surfaces as `BrokerUnreachableError`
+// so the caller can fall back to the durable path.
+import { oneShotControllerRequest } from './broker-request.js';
+/** Deliver `text` to a LIVE node's engine on its serialized frame loop. The
+ *  broker routes it itself (idle → prompt, streaming → steer) and acks once
+ *  routed; resolves with the route taken. `cards` are rendered runtime-card
+ *  envelopes placed ahead of the body inside that same frame handling, and
+ *  `origin` is the authorship the broker stamps onto the persisted message —
+ *  it rides the same frame as the body it describes. */
+export function deliverLive(nodeId, text, opts = {}) {
+    const cards = opts.cards ?? [];
+    return oneShotControllerRequest({
+        nodeId,
+        what: 'the interactive delivery',
+        ackFor: 'deliver',
+        correlated: true,
+        frame: (id) => ({
+            type: 'deliver',
+            id,
+            text,
+            ...(cards.length > 0 ? { cards: [...cards] } : {}),
+            ...(opts.origin !== undefined ? { origin: opts.origin } : {}),
+        }),
+        result: (detail) => (detail === 'steer' ? 'steer' : 'prompt'),
+    });
+}
+/** Abort whatever a LIVE node's engine is doing (turn or `!` bash). Resolves
+ *  once the broker has PROCESSED the abort — which, on the single frame loop,
+ *  also implies every earlier-accepted deliver was already routed (so a
+ *  just-delivered send cannot start its turn after this resolves un-aborted). */
+export function interruptLive(nodeId) {
+    return oneShotControllerRequest({
+        nodeId,
+        what: 'the interrupt',
+        ackFor: 'abort',
+        correlated: true,
+        frame: (id) => ({ type: 'abort', id }),
+        result: (detail) => (detail === 'turn' || detail === 'bash' ? detail : 'idle'),
+    });
+}

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

@@ -0,0 +1,15 @@
+import type { BrokerConfigSnapshot } from '../config.js';
+export interface PiInvocation {
+    /** The daemon-resolved config used by a broker without access to runtime records. */
+    configSnapshot?: BrokerConfigSnapshot;
+    /** argv after the `pi` binary. */
+    argv: string[];
+    /** env to merge into the process. */
+    env: Record<string, string>;
+    /** `LaunchSpec.worktree`, carried into `launch_json` for the sandbox start script (D102). */
+    worktree?: {
+        repository: string;
+        branch: string;
+        base: string;
+    };
+}

package/dist/core/runtime/invocation.js

@@ -0,0 +1,10 @@
+// The broker-launch recipe shape, alone in a dependency-free module.
+//
+// `launch.ts` builds a PiInvocation and therefore reaches canvas state; the
+// modules that only need to READ the recipe shape (spawn-env, host) must not.
+// A type-only import is erased at compile time, but the shipped broker
+// extensions are gated on their STATIC import graph — the gate cannot tell an
+// erased edge from a live one, so an extension that reaches spawn-env would
+// read as reaching canvas.db through launch.ts. Keeping the interface here
+// makes the graph say what the runtime already does.
+export {};

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

@@ -0,0 +1,37 @@
+import { type NodeMeta } from '../canvas/index.js';
+import { type WakeOrigin } from './bearings.js';
+/** The runtime-restart continuation exactly as delivered. `revive.ts` injects
+ *  it as the prompt of a strict resume that follows a cleanly aborted turn. */
+export declare const RUNTIME_RESTART_CONTINUATION: string;
+/** The original spawning prompt, retained in the node row. */
+export declare function goalPath(nodeId: string): Promise<string>;
+export declare function readGoal(nodeId: string): Promise<string | null>;
+export declare function writeGoal(nodeId: string, text: string): Promise<void>;
+/** A concurrent first user message must never overwrite the first goal. */
+export declare function captureGoalIfAbsent(nodeId: string, text: string): Promise<boolean>;
+export declare function writeYieldMessage(nodeId: string, text: string): Promise<void>;
+export declare function readYieldMessage(nodeId: string): Promise<string | null>;
+export declare function clearYieldMessage(nodeId: string): Promise<void>;
+/** List the node's context/ dir (filenames, sorted). Empty when absent. */
+export declare function listContextDir(nodeId: string): Promise<string[]>;
+/** A retained report proves this node has already done work. It must restart
+ * from current context, never by replaying its birth mandate. */
+export declare function hasRetainedReports(nodeId: string): Promise<boolean>;
+export interface ReviveBearings {
+    /** The one-shot yield note left by the prior self, pending boot confirmation. */
+    yieldMsg: string | null;
+    /** Coalesced wake mail, held by the execution until the turn settles. */
+    unreadDigest: string | null;
+    unreadMessageIds?: string[];
+    /** Persona-transition framing to surface when the node's role changed while
+     *  it was away. The drift remains pending until context-intro completes. */
+    driftGuidance: string | null;
+}
+/** Claim wake mail for this launch without acknowledging it before a turn. */
+export declare function drainBearings(meta: NodeMeta, executionId: string): Promise<ReviveBearings>;
+/** Assemble the auto-injected first message for a FRESH revive of `meta` from its
+ *  already-drained `bearings` (see drainBearings) plus pure on-disk reads of the
+ *  node's goal, roadmap, and context dir, framed so the revived node can rebuild
+ *  its bearings in one turn. PURE: no state mutation, so calling it twice yields
+ *  the same string and consumes nothing — drainBearings owns the one-shot reads. */
+export declare function buildReviveKickoff(meta: NodeMeta, bearings: ReviveBearings, wakeReason?: WakeOrigin): Promise<string>;

package/dist/core/runtime/kickoff.js

@@ -0,0 +1,263 @@
+// The revive kickoff — the message auto-injected as a node's first turn when it
+// comes back FRESH (a refresh-yield, or `node lifecycle 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), all of it inside one
+// <runtime kind="revive" …> card envelope:
+//   <roadmap file=…>…</roadmap>            its evolving plan — the source of truth
+//   <context-dir path=…>…</context-dir>    the files it left on disk (documents are read with `crtr canvas`)
+//   <feed>Awaiting N nodes … digest</feed> live wait state + unread/catch-up feed
+//   <yield-message>…</yield-message>       the note its prior self left on yield
+//
+// The roadmap (NOT the original spawn prompt) carries the goal on a refresh: its
+// Goal and Exit criteria hold the task, Where things stand its present state. context/
+// initial-prompt.md is NEVER injected into a node's prompts — it lives on disk
+// purely as a log of the original mandate; by the time a node is running it is
+// usually stale, and the roadmap is the doc the node keeps current. The
+// yield-message is one-shot (cleared when session_start confirms the revive).
+import { join } from 'node:path';
+import { getNode, subscriptionsOf, subscribersOf, } from '../canvas/index.js';
+import { contextDir, nodeAgentDir } from '../canvas/node-agent-paths.js';
+import { hasReportDocuments } from '../feed/reports.js';
+import { readdirBeneath } from '../spaces/open-beneath.js';
+import { openDb } from '../canvas/db.js';
+import { bashJobCommandLine, bashJobPaths, formatBashElapsed } from '../bash-jobs.js';
+import { runningJobs } from '../graph/jobs.js';
+import { readRoadmap } from './roadmap.js';
+import { buildWakeBearings } from './bearings.js';
+import { personaDrift } from './persona.js';
+import { coalesce, nodeMailEntry } from '../feed/inbox.js';
+import { claimKickoffMail } from '../canvas/deliveries.js';
+import { formatCard } from '../../shared/generated-context.js';
+import { mapAsync } from '../async-array.js';
+/** The runtime-restart continuation exactly as delivered. `revive.ts` injects
+ *  it as the prompt of a strict resume that follows a cleanly aborted turn. */
+export const RUNTIME_RESTART_CONTINUATION = formatCard('restart-continuation', {}, 'continue');
+// 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 original spawning prompt, retained in the node row. */
+export async function goalPath(nodeId) {
+    return join(await contextDir(nodeId), 'initial-prompt.md');
+}
+export async function readGoal(nodeId) {
+    const row = await (await openDb()).prepare('SELECT initial_prompt FROM nodes WHERE node_id = ?').get(nodeId);
+    return row?.initial_prompt ?? null;
+}
+export async function writeGoal(nodeId, text) {
+    const body = text.trim();
+    if (body === '')
+        return;
+    await (await openDb()).prepare('UPDATE nodes SET initial_prompt = ? WHERE node_id = ?').run(body + '\n', nodeId);
+}
+/** A concurrent first user message must never overwrite the first goal. */
+export async function captureGoalIfAbsent(nodeId, text) {
+    const body = text.trim();
+    if (body === '')
+        return false;
+    const result = await (await openDb()).prepare("UPDATE nodes SET initial_prompt = ? WHERE node_id = ? AND (initial_prompt IS NULL OR trim(initial_prompt) = '')").run(body + '\n', nodeId);
+    return result.changes === 1;
+}
+export async function writeYieldMessage(nodeId, text) {
+    const body = text.trim();
+    if (body === '')
+        return;
+    await (await openDb()).prepare('UPDATE nodes SET yield_note = ? WHERE node_id = ?').run(body + '\n', nodeId);
+}
+export async function readYieldMessage(nodeId) {
+    const row = await (await openDb()).prepare('SELECT yield_note FROM nodes WHERE node_id = ?').get(nodeId);
+    return row?.yield_note?.trim() || null;
+}
+export async function clearYieldMessage(nodeId) {
+    await (await openDb()).prepare('UPDATE nodes SET yield_note = NULL WHERE node_id = ?').run(nodeId);
+}
+/** List the node's context/ dir (filenames, sorted). Empty when absent. */
+export async function listContextDir(nodeId) {
+    return (await agentDirNames(nodeId, await contextDir(nodeId))).sort();
+}
+/** A retained report proves this node has already done work. It must restart
+ * from current context, never by replaying its birth mandate. */
+export async function hasRetainedReports(nodeId) {
+    return await hasReportDocuments(nodeId);
+}
+/** Entry names of one folder in the node's agent folder; none when it is absent. */
+async function agentDirNames(nodeId, dir) {
+    try {
+        return readdirBeneath(await nodeAgentDir(nodeId), dir).map((entry) => entry.name);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+/** Claim wake mail for this launch without acknowledging it before a turn. */
+export async function drainBearings(meta, executionId) {
+    const nodeId = meta.node_id;
+    // The note stays on disk until session_start confirms this launch.
+    const yieldMsg = await readYieldMessage(nodeId);
+    // A run's mail must enter pi as separate user messages, not be folded into
+    // this runtime revive prompt. Its watcher claims the pending rows after boot.
+    const claimed = meta.run_id ? [] : await claimKickoffMail(nodeId, executionId);
+    const unreadMessageIds = claimed.map((delivery) => delivery.message.messageId);
+    const entries = claimed.map(nodeMailEntry);
+    let unreadDigest = null;
+    if (entries.length > 0) {
+        // The launch argv carries one message. Keep coalescing card-free runs, but
+        // start a new batch at each entry with cards. A batch's cards are therefore
+        // directly ahead of its coalesced text, so they cannot leap an earlier body.
+        const cardsFor = (entry) => {
+            const cards = entry.data?.['cards'];
+            return Array.isArray(cards) ? cards.filter((card) => typeof card === 'string') : [];
+        };
+        const segments = [];
+        for (const entry of entries) {
+            if (cardsFor(entry).length > 0 || segments.length === 0)
+                segments.push([]);
+            segments.at(-1).push(entry);
+        }
+        unreadDigest = (await mapAsync(segments, async (segment) => [
+            ...cardsFor(segment[0]),
+            (await coalesce(segment)).map((delivery) => delivery.text).join('\n\n'),
+        ].join('\n\n'))).join('\n\n');
+    }
+    const drift = await personaDrift(nodeId);
+    const driftGuidance = drift?.guidance === undefined || drift.guidance === ''
+        ? null
+        : drift.guidance;
+    return { yieldMsg, unreadDigest, unreadMessageIds, driftGuidance };
+}
+/** Render the <feed> block PURELY: the live "awaiting" roster (a read), the
+ *  already-drained unread digest (from drainBearings), and a progressive index
+ *  to on-disk report history. No delivery mutation. */
+async function feedBlock(nodeId, unreadDigest) {
+    // Awaiting = active subscriptions whose publisher has not finished (active|idle).
+    const awaiting = (await mapAsync((await subscriptionsOf(nodeId))
+        .filter((s) => s.active), async (s) => await getNode(s.node_id)))
+        .filter((m) => m !== null && (m.status === 'active' || m.status === 'idle'));
+    const lines = [];
+    if (awaiting.length > 0) {
+        const n = awaiting.length;
+        const subj = n === 1 ? 'it has' : 'they have';
+        const poss = n === 1 ? 'Its' : 'Their';
+        lines.push(`Awaiting ${n} node${n === 1 ? '' : 's'} — ${subj} not finished. ${poss} reports will wake you.`);
+        for (const m of awaiting)
+            lines.push(`  - ${m.name} (${m.node_id}) — ${m.status}`);
+        lines.push('', unreadDigest ?? '(no unread reports)');
+    }
+    else {
+        lines.push('Awaiting 0 nodes.');
+        lines.push('', unreadDigest ?? '(no unread reports)');
+    }
+    return `<feed>\n${lines.join('\n')}\n</feed>`;
+}
+/** One-line label for a job: its purpose when the caller gave one, else its real
+ *  command line, clipped so a long pipeline stays scannable. */
+function jobLabel(purpose, command) {
+    const raw = (purpose ?? bashJobCommandLine(command)).trim() || '(no command)';
+    return raw.length > 120 ? `${raw.slice(0, 117)}…` : raw;
+}
+/** Live file-backed background bash jobs this node owns. A fresh revive has no
+ *  memory of handing anything off, so without this block the node cannot tell a
+ *  command it started is still running: it can neither read the log nor decide
+ *  whether to wait, and may relaunch the same work. Returns null — and the
+ *  kickoff omits the block entirely — when nothing is live. */
+async function backgroundJobsBlock(nodeId) {
+    const dir = await contextDir(nodeId);
+    const jobs = await runningJobs(await openDb(), nodeId);
+    if (jobs.length === 0)
+        return null;
+    const now = Date.now();
+    const one = jobs.length === 1;
+    const lines = [
+        `${jobs.length} background bash job${one ? '' : 's'} you started ${one ? 'is' : 'are'} STILL RUNNING, detached from any turn and unaffected by your refresh. ` +
+            `Each one sends you a message when it exits — that wake is automatic, so do not poll it and do not relaunch the same command.`,
+    ];
+    for (const job of jobs) {
+        lines.push(`  - ${job.jobId} — ${jobLabel(job.purpose, job.command)} · running ${formatBashElapsed(now - job.startedAtMs)} · log ${bashJobPaths(dir, job.jobId).jobLog}`);
+    }
+    lines.push('', 'Read output so far: `tail -n 50 <log>` (or `crtr node bash list --tail 20`). Abandon one: `crtr node bash kill <job-id>`.');
+    return `<background-jobs>\n${lines.join('\n')}\n</background-jobs>`;
+}
+// buildReviveKickoff — assemble the full fresh-revive first message.
+/** Assemble the auto-injected first message for a FRESH revive of `meta` from its
+ *  already-drained `bearings` (see drainBearings) plus pure on-disk reads of the
+ *  node's goal, roadmap, and context dir, framed so the revived node can rebuild
+ *  its bearings in one turn. PURE: no state mutation, so calling it twice yields
+ *  the same string and consumes nothing — drainBearings owns the one-shot reads. */
+export async function buildReviveKickoff(meta, bearings, wakeReason) {
+    const nodeId = meta.node_id;
+    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.',
+    ];
+    // Wake provenance (Invariant B/D): when a scheduled bare self-alarm fired this
+    // revive, the <crtr-wake> block reframes the generic "you were revived" above
+    // into "a TIMER woke you" — placed before the roadmap/disk bearings, so "why you
+    // woke" precedes "what to rebuild from". Only the daemon's bare-wake branch
+    // passes wakeReason.
+    if (wakeReason !== undefined)
+        parts.push(buildWakeBearings(wakeReason));
+    // The roadmap is the node's `roadmap` document: boot delivery hands it to
+    // this new session, so the kickoff does not repeat it. The original spawn
+    // prompt (context/initial-prompt.md) is deliberately NOT injected when a
+    // roadmap exists — by now it is usually stale.
+    const roadmap = await readRoadmap(nodeId);
+    const hasRoadmapBody = roadmap !== null && roadmap.trim() !== '';
+    // With NO roadmap the kickoff above carries no mandate at all, and an
+    // amnesiac fresh boot just stops (and is auto-finalized by the stop-guard) —
+    // observed when the daemon relaunches a spawned-but-never-launched node
+    // (audit 2026-06-09, Bug 4: mq45b6ch-9ecc2f03), whose only mandate on disk IS
+    // the goal. Surface the goal then. When a roadmap exists it stays the sole
+    // source of truth (the goal is usually stale by comparison) — unchanged.
+    if (!hasRoadmapBody && !await hasRetainedReports(nodeId)) {
+        const goal = await readGoal(nodeId);
+        if (goal !== null && goal.trim() !== '') {
+            parts.push(`<goal file="${await goalPath(nodeId)}">\n${goal.trim()}\n</goal>`);
+        }
+    }
+    // The yield note remains in the node row until confirmed boot. The broker
+    // lists its local context directory itself; the control plane has no such disk.
+    // Hidden applet/situation-origin ambient context (see situational-context.ts)
+    // is deliberately NOT injected here — this kickoff is the VISIBLE revive prompt.
+    // canvas-context-intro's session_start handler re-fires on every fresh/cycling
+    // revive (a new pi process boot) and re-injects buildContextIntro(), whose
+    // bearings body already nests the stored situational card; that seam covers
+    // this path, so duplicating it here would both repeat the card and put hidden
+    // ambient context into a visible prompt.
+    // Live background bash jobs sit beside the context-dir listing: both describe
+    // this node's OWN in-flight state, and both precede <feed>, which is about the
+    // other nodes it awaits. Absent when nothing is running.
+    const jobsBlock = await backgroundJobsBlock(nodeId);
+    if (jobsBlock !== null)
+        parts.push(jobsBlock);
+    parts.push(await feedBlock(nodeId, bearings.unreadDigest));
+    parts.push(bearings.yieldMsg !== null
+        ? `<yield-message>\n${bearings.yieldMsg.trim()}\n</yield-message>`
+        : '<yield-message/>');
+    // A node that reports UP the spine (has subscribers awaiting its result)
+    // finishes with `push final`. A human-attended node (no subscribers — a root
+    // conversation working directly with the user) has no result to submit and
+    // must not be told to finish: it stays resident and keeps working with the
+    // user.
+    const reportsUp = (await subscribersOf(nodeId)).length > 0;
+    parts.push(reportsUp
+        ? "If there is work to do, perform it. Otherwise stop — pipe the result to `crtr push final` through a single-quoted heredoc " +
+            'if the goal is met, or end your turn without a message to stay dormant awaiting your workers.'
+        : 'If there is work to do, perform it. Otherwise end your turn without writing a message — ' +
+            'the user already has your last reply, and a status recap would only bury it. You are ' +
+            'working directly with the user, so stay available and continue when they write back.');
+    // Non-document framing for a persona change made while the node was away.
+    // The replacement context's current snapshots carry all eligible documents;
+    // context-intro acknowledges the transition after those snapshots persist.
+    if (bearings.driftGuidance !== null) {
+        parts.push(`<persona-transition>\nYour role was changed while you were away. ${bearings.driftGuidance}\n</persona-transition>`);
+    }
+    // The envelope keeps a fresh revive out of canvas-goal-capture's
+    // first-real-input path, which would otherwise overwrite a bare root's
+    // mandate and rename it.
+    return formatCard('revive', {}, `\n${parts.join('\n\n')}\n`);
+}

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

@@ -0,0 +1,8 @@
+/** The minimal static system prompt every node launches with — a thin launcher
+ *  frame keeping the `\n\nGuidelines:` anchor the `before_agent_start` substrate
+ *  hook (canvas-doc-substrate.ts) splices its `<memory kind="preference">` block
+ *  before. ALL runtime/spine/lifecycle/kind prompting now lives as gated builtin
+ *  memory docs (src/builtin-memory/), spliced in fresh every turn — this scaffold
+ *  must never duplicate that prose. Imported by launch.ts (its own systemPrompt)
+ *  and `sys context prompt-review` so the two can never drift. */
+export declare const LAUNCH_SYSTEM_PROMPT: string;

package/dist/core/runtime/launch-prompt.js

@@ -0,0 +1,13 @@
+// launch-prompt.ts — the minimal static system-prompt scaffold, isolated from
+// launch.ts so CLI consumers (`sys context prompt-review`) can import the exact string
+// boot uses WITHOUT pulling launch.ts's canvas-db reach (editorLabel et al.).
+// Pure: zero imports.
+/** The minimal static system prompt every node launches with — a thin launcher
+ *  frame keeping the `\n\nGuidelines:` anchor the `before_agent_start` substrate
+ *  hook (canvas-doc-substrate.ts) splices its `<memory kind="preference">` block
+ *  before. ALL runtime/spine/lifecycle/kind prompting now lives as gated builtin
+ *  memory docs (src/builtin-memory/), spliced in fresh every turn — this scaffold
+ *  must never duplicate that prose. Imported by launch.ts (its own systemPrompt)
+ *  and `sys context prompt-review` so the two can never drift. */
+export const LAUNCH_SYSTEM_PROMPT = 'You are a node in the crtr canvas — an agentic runtime.\n\nGuidelines:\n' +
+    '- Use the crtr canvas (its documents, nodes and other objects) according to injected context.';

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

@@ -0,0 +1,43 @@
+import type { CreateNodeRequest } from '../../api/dto/nodes.js';
+import type { Mode } from '../canvas/types.js';
+import { type ProfileEntry } from '../profiles/manifest.js';
+import { buildLaunchSpecAsync } from './launch.js';
+export interface ResolvedLaunchTarget {
+    profileId: string | null;
+    profile: ProfileEntry | null;
+    kind: string;
+    mode: Mode;
+    cwd: string;
+    launch: Awaited<ReturnType<typeof buildLaunchSpecAsync>>['launch'];
+}
+export declare function resolveCreateKind(kind: string | undefined, profile: ProfileEntry | null): string;
+/** The daemon's default kind for an app-started run (`run.start`) whose profile
+ *  stores no `default_kind` — every app's own default profile, which
+ *  `ensureAppProfile` creates without one. */
+export declare const RUN_DEFAULT_KIND = "general";
+/** The model a `run.start` root gets when the start names no `model` and its
+ *  profile stores no `default_kind`: the default provider's medium rung, which
+ *  may rotate to another family at the same strength. An app-paid grant maps it
+ *  to the app's medium inference rung. */
+export declare const RUN_DEFAULT_MODEL = "medium";
+/** The kind a `run.start` root gets: its profile's `default_kind`, else
+ *  {@link RUN_DEFAULT_KIND}. `profile.list` reports this same value. */
+export declare function resolveRunKind(profile: ProfileEntry): string;
+/** The model a `run.start` root gets: the start's `model`, else
+ *  {@link RUN_DEFAULT_MODEL} for a profile without a `default_kind`, else the
+ *  profile kind's own model (undefined). */
+export declare function resolveRunModel(profile: ProfileEntry, requested: string | undefined): string | undefined;
+/** Whether a node of this kind is ever launched as a persona (and so needs a launch recipe). */
+export declare function isLaunchKind(kind: string): boolean;
+/** Validate a kind against the same cwd/profile configuration used to build its launch.
+ *  Resolution is subprocess-isolated: crtrd is single-threaded and a config read can
+ *  block indefinitely on a network filesystem. */
+export declare function assertLaunchKind(kind: string, cwd?: string, profileId?: string | null): Promise<void>;
+/** Resolve the exact profile, kind, cwd, mode and launch recipe a create will use. */
+export declare function resolveLaunchTarget(req: CreateNodeRequest, options?: {
+    readOnlyProfileSelection?: boolean;
+    /** Preserve an existing caller's validation boundary before target resolution. */
+    validateKind?: (kind: string) => void | Promise<void>;
+}): Promise<ResolvedLaunchTarget>;
+/** The directory a new node is pinned to. */
+export declare function resolveNodeCwd(req: CreateNodeRequest, parent: string | undefined, _profileId: string | null, contextCwd: string): Promise<string>;

package/dist/core/runtime/launch-target.js

@@ -0,0 +1,83 @@
+import { appSpace } from '../layout.js';
+import { envProfileId } from '../../shared/env.js';
+import { resolve } from 'node:path';
+import { getNode } from '../canvas/canvas.js';
+import { usage } from '../errors.js';
+import { assertProfileActive } from '../profiles/manifest.js';
+import { buildLaunchSpecAsync, readMergedLaunchConfigAsync } from './launch.js';
+import { resolveProfileId } from './spawn.js';
+export function resolveCreateKind(kind, profile) {
+    return kind ?? profile?.manifest.default_kind ?? 'general';
+}
+/** The daemon's default kind for an app-started run (`run.start`) whose profile
+ *  stores no `default_kind` — every app's own default profile, which
+ *  `ensureAppProfile` creates without one. */
+export const RUN_DEFAULT_KIND = 'general';
+/** The model a `run.start` root gets when the start names no `model` and its
+ *  profile stores no `default_kind`: the default provider's medium rung, which
+ *  may rotate to another family at the same strength. An app-paid grant maps it
+ *  to the app's medium inference rung. */
+export const RUN_DEFAULT_MODEL = 'medium';
+/** The kind a `run.start` root gets: its profile's `default_kind`, else
+ *  {@link RUN_DEFAULT_KIND}. `profile.list` reports this same value. */
+export function resolveRunKind(profile) {
+    return profile.manifest.default_kind ?? RUN_DEFAULT_KIND;
+}
+/** The model a `run.start` root gets: the start's `model`, else
+ *  {@link RUN_DEFAULT_MODEL} for a profile without a `default_kind`, else the
+ *  profile kind's own model (undefined). */
+export function resolveRunModel(profile, requested) {
+    return requested ?? (profile.manifest.default_kind === undefined ? RUN_DEFAULT_MODEL : undefined);
+}
+/** Kinds that name a control-plane node, not a persona: a `human` ask/page node has no
+ *  broker, is never launched, and has no entry in any launch config's `kinds`. */
+const NON_LAUNCH_KINDS = new Set(['human']);
+/** Whether a node of this kind is ever launched as a persona (and so needs a launch recipe). */
+export function isLaunchKind(kind) {
+    return !NON_LAUNCH_KINDS.has(kind);
+}
+/** Validate a kind against the same cwd/profile configuration used to build its launch.
+ *  Resolution is subprocess-isolated: crtrd is single-threaded and a config read can
+ *  block indefinitely on a network filesystem. */
+export async function assertLaunchKind(kind, cwd = process.cwd(), profileId = envProfileId() || null) {
+    const kinds = Object.keys((await readMergedLaunchConfigAsync(cwd, profileId)).kinds);
+    if (!kinds.includes(kind)) {
+        throw usage(`unknown kind: ${kind}`, { received: kind, next: `Valid kinds: ${kinds.sort().join(', ')}.` });
+    }
+}
+/** Resolve the exact profile, kind, cwd, mode and launch recipe a create will use. */
+export async function resolveLaunchTarget(req, options = {}) {
+    const parent = req.parent ?? undefined;
+    const contextCwd = req.cwd ?? process.cwd();
+    const profileId = await resolveProfileId(req.profile, parent ?? null, contextCwd, {
+        readOnlySelection: options.readOnlyProfileSelection,
+    });
+    const profile = assertProfileActive(profileId);
+    const kind = resolveCreateKind(req.kind, profile);
+    await options.validateKind?.(kind);
+    const cwd = await resolveNodeCwd({ ...req, kind }, parent, profileId, contextCwd);
+    if (options.validateKind === undefined)
+        await assertLaunchKind(kind, cwd, profileId);
+    const mode = (req.mode ?? 'base');
+    const launch = (await buildLaunchSpecAsync(kind, mode, {
+        lifecycle: req.root_lifecycle ?? (req.root === true ? 'resident' : 'terminal'),
+        hasManager: req.root !== true,
+        ...(req.model !== undefined ? { model: req.model, modelOverride: true } : {}),
+        cwd,
+        profileId,
+    })).launch;
+    return { profileId, profile, kind, mode, cwd, launch };
+}
+/** The directory a new node is pinned to. */
+export async function resolveNodeCwd(req, parent, _profileId, contextCwd) {
+    if (req.pin_cwd !== undefined && req.pin_cwd !== '')
+        return resolve(req.pin_cwd);
+    if (parent != null) {
+        const spawner = await getNode(parent);
+        if (spawner !== null)
+            return spawner.cwd;
+    }
+    if (req.cwd !== undefined && req.cwd !== '')
+        return resolve(req.cwd);
+    return process.platform === 'linux' ? appSpace('terminal').files : contextCwd;
+}