@north-light/cli 0.0.0 → 0.3.413

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

@@ -0,0 +1,194 @@
+import { type MergedLaunchConfig } from '../config.js';
+import type { PiInvocation } from './invocation.js';
+export { CANVAS_EXTENSIONS, CANVAS_STOPHOOK_PATH, CANVAS_INBOX_WATCHER_PATH, CANVAS_RECAP_PATH, CANVAS_GOAL_CAPTURE_PATH, CANVAS_PASSIVE_CONTEXT_PATH, CANVAS_CONTEXT_INTRO_PATH, CANVAS_TOOL_GUIDE_PATH, CANVAS_DOC_SUBSTRATE_PATH, CANVAS_STRUCTURED_OUTPUT_PATH, CANVAS_BASH_VALVE_PATH, } from './canvas-extensions.js';
+import type { NodeMeta, LaunchSpec, Mode, Lifecycle } from '../canvas/index.js';
+import type { ModelIntent, ModelProvider, ScopeConfig } from '../../types.js';
+export { OPENAI_PROVIDER_ENV, configuredLadderProviders, inferPortableModelSelection } from './model-selection.js';
+export type { PortableModelSelection } from './model-selection.js';
+/** True when `model` is a PORTABLE ladder token — a bare strength/alias
+ *  (`ultra`, `normal`, `opus`, …), a `<family>/<strength>` pair, or an
+ *  anthropic family alias — i.e. a logical preference rather than a concrete
+ *  provider/model id. Portable tokens are safe to PERSIST as defaults
+ *  (`persistDefaultKindModel`): they re-resolve against the declared routes or
+ *  ladder the running build ships, so they never freeze a stale concrete model
+ *  id to disk. */
+export declare function isPortableModelToken(model: string): boolean;
+export declare function logicalModelIntent(model: string, ladders?: ScopeConfig['modelLadders']): ModelIntent | undefined;
+/** The routing contract an explicit model choice asks for, decided from the RAW
+ *  token: a portable token (`anthropic/strong`, `strong`, `opus`) is an intent
+ *  that may rotate to another family at the same strength; any other token names
+ *  one model exactly (undefined). `node new --model`, `node config --model`, and
+ *  a viewer `/model` all apply this one rule. */
+export declare function explicitModelIntent(model: string, ladders?: ScopeConfig['modelLadders']): ModelIntent | undefined;
+export declare function normalizeModel(model: string, ladders?: ScopeConfig['modelLadders']): string;
+/** The interleaved model-ladder cycle Alt+M / Alt+Shift+M walks: for each strength tier
+ *  from strongest to weakest, each offered provider before descending — anthropic/ultra,
+ *  openai/ultra, anthropic/strong, openai/strong, anthropic/medium, … Returns the
+ *  concrete `provider/id:thinking` ladder cells in that order. `providers` narrows the
+ *  cycle to the signed-in columns (`configuredLadderProviders`); an empty subset falls
+ *  back to every provider so the cycle can never go rungless. */
+export declare function interleavedLadderCycle(providers?: readonly ModelProvider[]): string[];
+/** The next model in the interleaved ladder cycle, starting from `currentSpec`
+ *  (a `provider/id:thinking` spec — pass `formatModelSpec(session.model,
+ *  session.thinkingLevel)`). `direction` is +1 (forward) or -1 (backward).
+ *
+ *  Rungs are matched on bare id AND thinking level first, so ladder cells that
+ *  share a bare model id (e.g. anthropic ultra=…:high vs strong=…:medium) don't
+ *  collapse onto each other; a bare-id-only match is the fallback. An off-ladder
+ *  current model — including a rung on a provider `providers` excludes — starts
+ *  the cycle at its top (the strongest offered rung). */
+export declare function nextLadderModel(currentSpec: string, direction?: 1 | -1, providers?: readonly ModelProvider[]): string;
+/** Compose a node's full pi launch recipe from the kind registry. The system
+ *  prompt is now a minimal static scaffold (`LAUNCH_SYSTEM_PROMPT`) — runtime/
+ *  spine/lifecycle/kind prose is spliced per-turn from gated builtin memory docs,
+ *  not baked in here. Launch KNOBS (model/tools/extensions) still come from the
+ *  kind registry (`resolveKindConfig`), keyed on the FULL kind string (top-level
+ *  or sub-kind). Model precedence, strongest to weakest:
+ *   1. Caller-supplied `opts.model` (durable on `meta.model_override`, re-passed
+ *      on every polymorph).
+ *   2. The kind's registered model — mode-aware: orchestrator mode prefers
+ *      `orchestratorModel`, falling back to `model`; base mode always uses
+ *      `model`.
+ *   3. Unset → pi default.
+ *  Callers pass the authoritative lifecycle + hasManager (`parent !== null`) so
+ *  a polymorph/flip rebuilds the recipe faithfully; `lifecycle` is returned
+ *  as-given, never derived from persona frontmatter. The two canvas
+ *  extensions are always first; kind-declared extensions follow. */
+export interface LaunchBuildOptions {
+    lifecycle: Lifecycle;
+    hasManager: boolean;
+    extraEnv?: Record<string, string>;
+    model?: string;
+    /** A newly supplied `--model` override. Resolve it through the target
+     *  ladder and any quality floor once, then freeze the resulting concrete
+     *  provider/id[:thinking] spec into the launch recipe so every launch,
+     *  revive, and retry consults exactly that model — but ONLY when the raw
+     *  token names a concrete model. A PORTABLE ladder token (`medium`,
+     *  `anthropic/opus`) is a strength preference, not a model identity, so it
+     *  keeps its route intent and stays eligible for fallback; freezing it
+     *  would fail a node closed on a canvas whose only authenticated route is a
+     *  different provider. Existing recipes instead carry
+     *  `modelExact`/`modelIntent` below verbatim. */
+    modelOverride?: boolean;
+    /** The TARGET node's cwd — anchors the project-scope stack for kind/ladder
+     *  resolution. Defaults to this process's own cwd, which is correct only
+     *  when the caller IS resolving for itself; spawn/polymorph paths must
+     *  pass the node's own cwd (same rule as `readMergedLaunchConfig`). */
+    cwd?: string;
+    /** The TARGET node's profile id — REQUIRED for a profile's kind/ladder
+     *  overrides (e.g. a `/model` default persisted by
+     *  `persistDefaultKindModel`) to be honored. Defaults to the ambient
+     *  `CRTR_PROFILE_ID`, which is EMPTY for a front-door shell invocation —
+     *  exactly the path that creates the user's sessions — so callers that
+     *  know the node's profile must pass it explicitly (null = no profile). */
+    profileId?: string | null;
+    /** Preserved intent from an existing launch recipe when rebuilding it. */
+    modelIntent?: ModelIntent;
+    /** Exact-consult launch: pass the captured `provider/id:thinking` spec
+     *  verbatim as `launch.model`, skipping `floorReviewModel`/`normalizeModel`
+     *  entirely (avoids any tier-collision reinterpretation). `opts.model` MUST
+     *  be defined when this is true. Sets `launch.modelExact = true`, which the
+     *  broker's launch-time/turn-time resolution paths must bypass every
+     *  fallback for and fail closed on unavailability. */
+    modelExact?: boolean;
+}
+/** Build a launch recipe for callers that are not on crtrd's event loop. */
+export declare function buildLaunchSpec(kind: string, mode: Mode, opts: LaunchBuildOptions): {
+    launch: LaunchSpec;
+    lifecycle: 'terminal' | 'resident';
+};
+/**
+ * Resolve launch config in a bounded subprocess before building a recipe.
+ * crtrd is single-threaded: project/profile roots can live on a network
+ * filesystem, so even an ordinary synchronous config read must never run on
+ * its event loop.
+ */
+export declare function buildLaunchSpecAsync(kind: string, mode: Mode, opts: LaunchBuildOptions): Promise<{
+    launch: LaunchSpec;
+    lifecycle: 'terminal' | 'resident';
+}>;
+/** Describe how a launch-config subprocess ended, with the cause an operator
+ *  needs: the exit code or fatal signal, and the tail of its stderr (a dyld
+ *  failure, an uncaught exception). Exported for tests. */
+export declare function describeLaunchConfigExit(code: number | null, signal: NodeJS.Signals | null, stderr: string): string;
+export declare function readMergedLaunchConfigAsync(cwd: string, profileId: string | null, 
+/** Test seam: the interpreter and worker script to fork with. */
+seam?: {
+    execPath?: string;
+    workerPath?: string;
+}): Promise<MergedLaunchConfig>;
+export type { PiInvocation } from './invocation.js';
+/** Construct the pi invocation for a node.
+ *  - fresh start: pass `prompt` (the node's first user message), no resume.
+ *  - fork start: pass `forkFrom` (absolute .jsonl path or partial uuid) to `--fork`
+ *    — pi COPIES that conversation into a NEW session for this node, then `prompt`
+ *    is delivered as the next message. One-shot at birth: the node thereafter
+ *    captures its OWN pi_session_file and revives by `--session` like any other.
+ *  - revive idle/done: pass `resumeSessionPath` (absolute .jsonl path) to
+ *    `--session` (keeps conversation). `resumeSessionId` (a bare uuid) is
+ *    accepted here too, but revive.ts's `resumeArgs` never produces one —
+ *    `headlessBrokerHost`'s preflight (host.ts) fatally rejects a bare
+ *    `--session` id before ever spawning the broker, so a real revive only
+ *    ever resumes by path (or falls through to fresh when no path exists).
+ *  - refresh-yield: same `.jsonl` (`resumeSessionPath`) PLUS `newCycle` —
+ *    emits the valueless `--crtr-new-cycle` token alongside `--session`. The
+ *    broker resets the session-tree leaf and roots the new cycle as a fresh
+ *    sibling branch instead of starting a new file; the node re-reads its
+ *    roadmap exactly as a fresh launch would. */
+export declare function buildPiArgv(meta: NodeMeta, opts?: {
+    prompt?: string;
+    resumeSessionId?: string;
+    resumeSessionPath?: string;
+    forkFrom?: string;
+    newCycle?: boolean;
+}): PiInvocation;
+/** The pi-SDK launch config the headless broker drives an in-process engine
+ *  with — the structural inverse of `buildPiArgv`'s flag vocabulary. Each field
+ *  maps one of buildPiArgv's emitted flags back to its SDK option:
+ *  `-e`→`extensionPaths`, `-n`→`editorName`, `--fork`→`forkFrom`,
+ *  `--session`→`resumeSessionPath|resumeSessionId`, `--crtr-new-cycle`→
+ *  `newCycle`, `--model`→`model`, `--crtr-model-exact`→`modelExact`, `--tools`→`tools`,
+ *  `--append-system-prompt`→`appendSystemPromptPath`, the trailing
+ *  positional→`firstPrompt`. */
+export interface BrokerSdkConfig {
+    /** The node's pinned working dir (from `CRTR_NODE_CWD`, else `process.cwd()`). */
+    cwd: string;
+    /** Absolute `.js` extension paths (the canvas extensions). */
+    extensionPaths: string[];
+    /** Session label (`-n`). */
+    editorName?: string;
+    /** Spawn-time fork source (`--fork <path|id>`). */
+    forkFrom?: string;
+    /** Resume by absolute `.jsonl` path (preferred — `SessionManager.open`). */
+    resumeSessionPath?: string;
+    /** Resume by bare session uuid. Accepted by the generic builder, but no live
+     *  caller sets it — revive resumes by absolute path only, and the broker
+     *  preflight rejects a bare `--session`. */
+    resumeSessionId?: string;
+    /** A refresh-yield's marker: reset the session-tree leaf and root a fresh
+     *  cycle as a new branch of the SAME resumed `.jsonl`, instead of starting a
+     *  new session file (`--crtr-new-cycle`). Only meaningful alongside
+     *  `resumeSessionPath`; never set together with `forkFrom`. */
+    newCycle?: boolean;
+    /** Model spec, e.g. `anthropic/sonnet` (`--model`). */
+    model?: string;
+    /** Exact-consult launch (`--crtr-model-exact`): `model` must run verbatim —
+     *  every launch-time/turn-time fallback is bypassed and unavailability must
+     *  fail rather than substitute. */
+    modelExact?: boolean;
+    /** Tool allowlist (`--tools a,b,c` → `['a','b','c']`). */
+    tools?: string[];
+    /** `--append-system-prompt` arg — a file path in practice (pi's loader
+     *  resolves a path or literal text identically). */
+    appendSystemPromptPath?: string;
+    /** The fresh-start kickoff message (the trailing positional). */
+    firstPrompt?: string;
+}
+/** Translate a `PiInvocation` (the recipe `buildPiArgv` produced) into the SDK
+ *  config the broker hosts an engine with. This is the EXACT inverse of
+ *  `buildPiArgv` and must track its flag set 1:1 — co-located here so the two
+ *  never drift. Safe because `buildPiArgv` is the SOLE producer of these flags
+ *  (we own both ends). SIDE EFFECT: merges `inv.env` into `process.env` so the
+ *  in-process engine + the bound canvas extensions see the same env a forked pi
+ *  would (CRTR_NODE_ID, CRTR_SUBTREE, …). */
+export declare function piInvocationToSdkConfig(inv: PiInvocation): BrokerSdkConfig;

package/dist/core/runtime/launch.js

@@ -0,0 +1,3 @@
+var b=Object.defineProperty;var s=(e,r)=>b(e,"name",{value:r,configurable:!0});import{envProfileId as _}from"../../shared/env.js";import{mkdirSync as H}from"node:fs";import{join as V}from"node:path";import{readMergedLaunchConfig as M}from"../config.js";import{fork as U}from"node:child_process";import{fileURLToPath as D}from"node:url";import{freshChildNodeExecPath as F,recheckChildNode as $}from"./branded-host.js";import{LAUNCH_SYSTEM_PROMPT as G}from"./launch-prompt.js";import{nodeEnv as K}from"./nodes.js";import{editorLabel as W}from"../canvas/index.js";import{CANVAS_EXTENSIONS as Ie,CANVAS_STOPHOOK_PATH as Oe,CANVAS_INBOX_WATCHER_PATH as ye,CANVAS_RECAP_PATH as ve,CANVAS_GOAL_CAPTURE_PATH as Le,CANVAS_PASSIVE_CONTEXT_PATH as Re,CANVAS_CONTEXT_INTRO_PATH as be,CANVAS_TOOL_GUIDE_PATH as He,CANVAS_DOC_SUBSTRATE_PATH as Ve,CANVAS_STRUCTURED_OUTPUT_PATH as Me,CANVAS_BASH_VALVE_PATH as Ue}from"./canvas-extensions.js";import{nodeRunDir as X}from"../canvas/paths.js";import{writeFileBeneath as B}from"../spaces/open-beneath.js";import{projectOutputSchema as j}from"./structured-output.js";import{CANVAS_EXTENSIONS as z,mergeCanvasExtensions as T,assertMandatoryCanvasExtensions as Y}from"./canvas-extensions.js";import{modelLadders as a,defaultProvider as E,STRENGTH_ALIASES as p,MODEL_PROVIDER_KEYS as S,MODEL_STRENGTHS as x,THINKING_SUFFIXES as Q,stripThinkingSuffix as m}from"./model-selection.js";import{OPENAI_PROVIDER_ENV as Fe,configuredLadderProviders as $e,inferPortableModelSelection as Ge}from"./model-selection.js";function P(e,r=a()){return r[e]}s(P,"ladderFor");const g={light:0,medium:1,strong:2,ultra:3};function J(e,r,n){const t=m(e);for(const o of[!0,!1]){const i=o?x:[...x].sort((c,u)=>g[c]-g[u]);for(const c of n)for(const u of i){const f=r[c][u];if(!(o?f!==e:m(f)!==t))return{provider:c,strength:u}}}return null}s(J,"findLadderCell");function C(e){const r=e.lastIndexOf("/"),n=r===-1?void 0:e.slice(0,r),t=r===-1?e:e.slice(r+1),o=p[t];return o!==void 0?o:n!==void 0&&n!=="anthropic"?null:t==="opus"?"strong":t==="sonnet"?"medium":t==="haiku"?"light":null}s(C,"modelTokenStrength");function k(e,r=a()){const n=C(e);return n!==null?n:J(A(e,r),r,S)?.strength??null}s(k,"resolvedModelStrength");function Z(e){return e==="review"||e.startsWith("review/")||e.includes("/reviewers/")}s(Z,"isReviewQualityKind");function q(e,r,n,t=a()){if(r===void 0)return n;if(!Z(e)||n===void 0)return r;const o=k(r,t),i=k(n,t);return o===null||i===null?r:g[o]<g[i]?n:r}s(q,"floorReviewModel");function N(e){if(e.includes("/")){const r=e.lastIndexOf("/"),n=e.slice(0,r),t=e.slice(r+1);return n!==""&&(p[t]!==void 0||n==="anthropic"&&(t==="opus"||t==="sonnet"||t==="haiku"))}return p[e]!==void 0||e==="opus"||e==="sonnet"||e==="haiku"}s(N,"isPortableModelToken");function w(e,r=a()){const n=C(e);if(n!==null)return e.includes("/")?{family:e.slice(0,e.lastIndexOf("/")),strength:n}:e==="opus"||e==="sonnet"||e==="haiku"?{family:"anthropic",strength:n}:{family:E(r),strength:n}}s(w,"logicalModelIntent");function _e(e,r=a()){return N(e)?w(e,r):void 0}s(_e,"explicitModelIntent");function A(e,r=a()){if(e.includes("/")){const t=e.indexOf("/"),o=e.slice(0,t),i=e.slice(t+1),c=p[i];if(c!==void 0&&(o==="anthropic"||o==="openai"))return P(o,r)[c];if(o==="anthropic"){if(i==="opus")return r.anthropic.strong;if(i==="sonnet")return r.anthropic.medium;if(i==="haiku")return r.anthropic.light}return e}const n=p[e];return n!==void 0?P(E(r),r)[n]:e==="opus"?r.anthropic.strong:e==="sonnet"?r.anthropic.medium:e==="haiku"?r.anthropic.light:e}s(A,"normalizeModel");function I(e){const r=e.lastIndexOf(":");if(r<=0)return;const n=e.slice(r+1);return Q.has(n)?n:void 0}s(I,"thinkingSuffixOf");function ee(e=S){const r=e.length>0?e:S,n=a(),t=[];for(const o of x)for(const i of r)t.push(n[i][o]);return t}s(ee,"interleavedLadderCycle");function Te(e,r=1,n){const t=ee(n),o=A(e),i=m(o),c=I(o);let u=t.findIndex(f=>m(f)===i&&I(f)===c);return u===-1&&(u=t.findIndex(f=>m(f)===i)),u===-1?t[0]:t[(u+r+t.length)%t.length]}s(Te,"nextLadderModel");function O(e,r,n,t){const o=t.kinds[e],i=t.modelLadders,c=r==="orchestrator"?o?.orchestratorModel??o?.model:o?.model,u=n.modelExact===!0?n.model:q(e,n.model,c,i),f=n.modelExact===!0||n.modelOverride===!0&&n.model!==void 0&&!N(n.model),l=n.modelExact===!0?u:u!==void 0?A(u,i):void 0,h=f?void 0:n.modelIntent??(u!==void 0?w(u,i):void 0);return{launch:{model:l,modelIntent:h,modelExact:f?!0:void 0,tools:o?.tools??[],extensions:T([...z,...o?.extensions??[]]),systemPrompt:G,env:{...n.extraEnv??{},...h?{CRTR_MODEL_INTENT:`${h.family}/${h.strength}`}:{}}},lifecycle:n.lifecycle}}s(O,"buildLaunchSpecFromMerged");function Ee(e,r,n){return O(e,r,n,M(n.cwd??process.cwd(),n.profileId!==void 0?n.profileId:_()||null))}s(Ee,"buildLaunchSpec");async function Pe(e,r,n){const t=n.cwd??process.cwd(),o=n.profileId!==void 0?n.profileId:_()||null,i=await re(t,o);return O(e,r,n,i)}s(Pe,"buildLaunchSpecAsync");const y=15e3;function ne(e,r,n){const t=r!==null?`was killed by ${r}`:`exited with code ${e}`,o=n.trim().split(`
+`).slice(-8).join(`
+`).slice(-1500);return`launch config subprocess ${t}${o!==""?`: ${o}`:" (no stderr output)"}`}s(ne,"describeLaunchConfigExit");class v extends Error{static{s(this,"LaunchConfigWorkerCrash")}}async function re(e,r,n={}){const t=n.execPath??await F(),o=n.workerPath??D(new URL("./launch-config-worker.js",import.meta.url));try{return await L(e,r,t,o)}catch(i){if(!(i instanceof v))throw i;const c=await $(t);if(c===t)throw i;return L(e,r,c,o)}}s(re,"readMergedLaunchConfigAsync");function L(e,r,n,t){return new Promise((o,i)=>{const c=U(t,[],{execPath:n,stdio:["ignore","ignore","pipe","ipc"],serialization:"advanced"});let u="";c.stderr?.setEncoding("utf8").on("data",d=>{u=(u+d).slice(-8192)}),c.send({cwd:e,profileId:r});let f=!1;const l=s(d=>{f||(f=!0,clearTimeout(h),c.connected&&c.disconnect(),c.killed||c.kill("SIGKILL"),d())},"finish"),h=setTimeout(()=>l(()=>i(new Error(`timed out after ${y}ms reading launch config for ${e}`))),y);c.once("message",d=>{d.error!==void 0?l(()=>i(new Error(d.error))):d.config!==void 0?l(()=>o(d.config)):l(()=>i(new Error("launch config subprocess returned no result")))}),c.once("error",d=>l(()=>i(d))),c.once("close",(d,R)=>{d!==0&&!f&&l(()=>i(new v(ne(d,R,u))))})})}s(L,"runLaunchConfigWorker");function te(e,r){try{const n=X(e);H(n,{recursive:!0});const t=V(n,"system-prompt.md");return B(n,t,r,{atomic:!0}),t}catch{return null}}s(te,"writeSystemPromptFile");function Ce(e,r={}){const n=e.launch,t=T(n?.extensions);Y(t);const o=[];for(const i of t)o.push("-e",i);if(o.push("-n",W(e)),r.forkFrom!==void 0&&r.forkFrom!=="")o.push("--fork",r.forkFrom);else{const i=r.resumeSessionPath??r.resumeSessionId;i!==void 0&&o.push("--session",i),r.newCycle===!0&&o.push("--crtr-new-cycle")}if(n?.model!==void 0&&o.push("--model",n.model),n?.modelExact===!0&&o.push("--crtr-model-exact"),n?.tools!==void 0&&n.tools.length>0&&o.push("--tools",n.tools.join(",")),n?.systemPrompt!==void 0&&n.systemPrompt!==""){const i=te(e.node_id,n.systemPrompt)??n.systemPrompt;o.push("--append-system-prompt",i)}return r.prompt!==void 0&&r.prompt!==""&&o.push(r.prompt),j(e.node_id),{argv:o,env:K(e)}}s(Ce,"buildPiArgv");function ke(e){for(const[t,o]of Object.entries(e.env))process.env[t]=o;const r={cwd:e.env.CRTR_NODE_CWD??process.cwd(),extensionPaths:[]},n=e.argv;for(let t=0;t<n.length;t++){const o=n[t];switch(o){case"-e":r.extensionPaths.push(n[++t]);break;case"-n":r.editorName=n[++t];break;case"--fork":r.forkFrom=n[++t];break;case"--session":{const i=n[++t];i.includes("/")||i.endsWith(".jsonl")?r.resumeSessionPath=i:r.resumeSessionId=i;break}case"--model":r.model=n[++t];break;case"--crtr-model-exact":r.modelExact=!0;break;case"--tools":r.tools=n[++t].split(",").filter(i=>i!=="");break;case"--append-system-prompt":r.appendSystemPromptPath=n[++t];break;case"--crtr-new-cycle":r.newCycle=!0;break;default:r.firstPrompt=o;break}}return r}s(ke,"piInvocationToSdkConfig");export{Ue as CANVAS_BASH_VALVE_PATH,be as CANVAS_CONTEXT_INTRO_PATH,Ve as CANVAS_DOC_SUBSTRATE_PATH,Ie as CANVAS_EXTENSIONS,Le as CANVAS_GOAL_CAPTURE_PATH,ye as CANVAS_INBOX_WATCHER_PATH,Re as CANVAS_PASSIVE_CONTEXT_PATH,ve as CANVAS_RECAP_PATH,Oe as CANVAS_STOPHOOK_PATH,Me as CANVAS_STRUCTURED_OUTPUT_PATH,He as CANVAS_TOOL_GUIDE_PATH,Fe as OPENAI_PROVIDER_ENV,Ee as buildLaunchSpec,Pe as buildLaunchSpecAsync,Ce as buildPiArgv,$e as configuredLadderProviders,ne as describeLaunchConfigExit,_e as explicitModelIntent,Ge as inferPortableModelSelection,ee as interleavedLadderCycle,N as isPortableModelToken,w as logicalModelIntent,Te as nextLadderModel,A as normalizeModel,ke as piInvocationToSdkConfig,re as readMergedLaunchConfigAsync};

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

@@ -0,0 +1,10 @@
+/** End the node's context session: its ledger holds nothing. */
+export declare function clearNodeLedger(nodeId: string): void;
+/** Seed a fork's ledger once with the transcript rows its source holds; no
+ *  source → empty. A fork already seeded (at spawn, or by an earlier birth
+ *  attempt) keeps its ledger, so a retry after the source is deleted loses nothing. */
+export declare function forkNodeLedger(forkId: string, sourceId: string | null): void;
+/** Queue one inbox entry for a node revived from done listing the watched
+ *  documents that got a newer revision (by someone else) since `since`.
+ *  Returns whether a notice was queued. */
+export declare function noticeChangedWhileDone(nodeId: string, since: string): boolean;

package/dist/core/runtime/ledger.js

@@ -0,0 +1,3 @@
+var y=Object.defineProperty;var i=(e,o)=>y(e,"name",{value:o,configurable:!0});import{withCanvasWrite as u}from"../canvas/db.js";import{changedWhileDone as $}from"../substrate/delivery/deliver.js";import{queueNodeNotice as L}from"../feed/messages.js";import{clearLedger as f,forkLedger as k,hasLedger as N}from"../graph/exposures.js";import{getById as m,getByRowid as j,nodeObject as c}from"../graph/objects.js";function q(e){u(o=>f(o,c(o,e).rowid))}i(q,"clearNodeLedger");function H(e,o){u(n=>{const r=c(n,e);if(N(n,r.rowid))return;const t=o===null?null:m(n,o);t===null||t.type!=="node"?f(n,r.rowid):k(n,t.rowid,r.rowid)})}i(H,"forkNodeLedger");function d(e){return e===null?"?":e.type==="node"?e.id:e.name}i(d,"ownerHandle");function O(e,o){return u(n=>{const r=$(n,c(n,e),o);if(r.length===0)return!1;const t=r.map(({doc:l,from:g,to:w,authors:a})=>{const h=l.owner===null?null:j(n,l.owner),s=a.length===0?"":`, by ${a.map(p=>d(m(n,p))).join(", ")}`;return`- ${d(h)}/${l.name} \u2014 revision ${g??"none"} \u2192 ${w}${s}`});return L(n,e,{body:`Documents you watch changed while you were done:
+${t.join(`
+`)}`,label:"documents changed while you were done",tier:"normal",wake:0}),!0})}i(O,"noticeChangedWhileDone");export{q as clearNodeLedger,H as forkNodeLedger,O as noticeChangedWhileDone};

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

@@ -0,0 +1,34 @@
+import type { NodeMeta, NodeOutcomeDetailV1, NodeStatus, ExitIntent, TerminalReason } from '../canvas/types.js';
+/** The lifecycle events — the only vocabulary for moving a node's status/intent.
+ *  Each maps (in the table below) to a target status and/or intent plus the set
+ *  of from-statuses it is legal from. */
+export type LifecycleEvent = 'finish' | 'park' | 'cancel' | 'crash' | 'yield' | 'release' | 'refresh-launch' | 'revive';
+export interface TerminalOutcomeInput {
+    /** Omit to derive: a lifecycle terminal transition is always a failure. */
+    detail?: NodeOutcomeDetailV1;
+}
+/** Enact a lifecycle event on a node: validate the from-status against the
+ *  table, then write status+intent in ONE atomic statement (so they can never
+ *  disagree). Returns the hydrated node view after the write.
+ *
+ *  Throws on an unknown node or an illegal move. The conditional update makes
+ *  legality authoritative at SQLite write time rather than at a stale read. */
+export declare function transition(nodeId: string, event: LifecycleEvent, opts?: {
+    reason?: TerminalReason;
+    outcome?: TerminalOutcomeInput;
+}): NodeMeta;
+/** Whether this row is a PARKED node — terminalized by the unattended clock
+ *  rather than by finishing its own work. The one read of the park marker:
+ *  `done` qualified by `intent='parked'`, both written in the same atomic
+ *  statement by the `park` event above. Revival clears it (`revive` writes
+ *  `intent: null`), so a reopened node is an ordinary node again. */
+export declare function isParked(node: {
+    status: NodeStatus;
+    intent?: ExitIntent;
+}): boolean;
+/** Whether the lifecycle table committed a deliberate idle release. `release`
+ * writes this intent with `status='idle'` atomically before its broker may exit,
+ * so an old busy marker cannot override the durable release decision. */
+export declare function hasIdleReleaseIntent(node: {
+    intent?: ExitIntent;
+} | null): boolean;

package/dist/core/runtime/lifecycle.js

@@ -0,0 +1,2 @@
+var x=Object.defineProperty;var u=(t,e)=>x(t,"name",{value:e,configurable:!0});import{getNode as S,cancelCronsOnWake as J,transitionStatusIntent as b}from"../canvas/index.js";import{composeNodeOutcomeDocument as A}from"./outcome-document.js";import{withCanvasWrite as E}from"../canvas/db.js";import{nodeObject as D}from"../graph/objects.js";import{endMessageSubscriptions as L}from"../graph/watches.js";import{runStructuredRequestEffects as P,settlePendingStructuredRequestForNodeIn as $}from"../canvas/structured-requests.js";const m="*",j={finish:"finished",park:"parked",cancel:"stranded",crash:"crashed","refresh-launch":null,revive:null},l=["active","idle"],q={finish:{status:"done",intent:"done",from:l},park:{status:"done",intent:"parked",from:l},cancel:{status:"canceled",intent:null,from:m},crash:{status:"dead",from:l},yield:{intent:"refresh",from:l},release:{status:"idle",intent:"idle-release",from:[...l,"done"]},"refresh-launch":{status:"active",intent:"refresh",from:m},revive:{status:"active",intent:null,from:m}};function I(t,e){const r=t.split(`
+`)[0]??"";let n=0,c="";for(const d of r){const i=Buffer.byteLength(d,"utf8");if(n+i>e)break;n+=i,c+=d}return c}u(I,"firstLineAtMost");function M(t){if(t===void 0)return null;const e=t.message===void 0?void 0:I(t.message,500),r={...t,...e===void 0?{}:{message:e}},n=JSON.stringify(r);return Buffer.byteLength(n,"utf8")<=4*1024?n:JSON.stringify({schema:"crtr.node-outcome-detail/v1",truncated:!0,...e===void 0?{}:{message:e}})}u(M,"detailJson");function T(t,e){let r,n;return e==="finished"||e==="declined"?(r="done",n="done"):e==="parked"?(r="done",n="parked"):e==="closed"||e==="retired"||e==="stranded"||e==="deadline_exceeded"?(r="canceled",n=null):(r="dead",n=null),{...t,status:r,intent:n,terminal_reason:e}}u(T,"nodeAtOutcome");function v(t,e,r){const n=q[e],c=Object.prototype.hasOwnProperty.call(n,"status"),d=Object.prototype.hasOwnProperty.call(n,"intent"),i=r?.reason??j[e],f={};c&&(f.status=n.status),d&&(f.intent=n.intent??null),i!==void 0&&(f.terminal_reason=i);const a=e==="finish"||e==="park"||e==="cancel"||e==="crash",s=a?S(t):null,p=a&&s?.kind!=="human",h=i,_=a?new Date().toISOString():null,w=M(r?.outcome?.detail),y=p&&s?.run_id!=null&&i!=="parked"&&s.outcome_at!==null&&(l.includes(s.status)||s.outcome_reason==="parked");let k;p&&s!==null&&(s.outcome_at===null||y)&&(k=JSON.stringify(A({node:T(s,h),outcome:{kind:"failure",reason:h,at:_,revision:(s.outcome_revision??0)+1,detailJson:w}})));const N=a?i==="deadline_exceeded"?{intended:"expired",failureReason:"node_deadline_exceeded",failureDetail:r?.outcome?.detail??null}:{intended:"failed",failureReason:i,failureDetail:r?.outcome?.detail??null}:null,g=E(o=>{const O=b(t,f,{fromStatuses:n.from===m?void 0:n.from,requireNoFinalReport:e==="cancel",...p?{outcome:{kind:"failure",reason:h,detailJson:w,at:_,...y?{supersede:!0}:{},...k===void 0?{}:{documentJson:k}}}:{}});a&&O>0&&L(o,D(o,t),"done");const R=O===1&&N!==null?$(o,t,N):null;return{changes:O,settlement:R}});if(g.changes===0){const o=S(t);if(o===null)throw new Error(`transition: unknown node ${t}`);if(e==="cancel"&&o.final_report!==null&&o.final_report!==void 0)return o;throw new Error(`illegal lifecycle transition: '${e}' from status='${o.status}' (node ${t})`)}return g.settlement?.changed&&P(g.settlement.row),(e==="finish"||e==="park"||e==="cancel")&&J(t),S(t)}u(v,"transition");function G(t){return t.status==="done"&&t.intent==="parked"}u(G,"isParked");function H(t){return t?.intent==="idle-release"}u(H,"hasIdleReleaseIntent");export{H as hasIdleReleaseIntent,G as isParked,v as transition};

package/dist/core/runtime/managed-provider-cooling.d.ts

@@ -0,0 +1,24 @@
+import type { AssistantMessageDiagnostic } from '@earendil-works/pi-ai';
+/** Diagnostic `type` tag carrying the cooling deadline; also the wire contract the
+ *  stophook matches on. */
+export declare const MANAGED_PROVIDER_COOLING_DIAGNOSTIC = "crtr:managed-provider-cooling";
+/** Stable error code so a caller can recognize the typed error without message parsing. */
+export declare const MANAGED_PROVIDER_COOLING_CODE = "managed_provider_cooling";
+/** Every managed provider pool tried this turn is cooling; `rateLimitedUntil` is
+ *  the earliest future deadline (epoch ms) across those pools. */
+export declare class ManagedProviderCoolingError extends Error {
+    readonly code = "managed_provider_cooling";
+    readonly rateLimitedUntil: number;
+    constructor(message: string, rateLimitedUntil: number);
+    /** The diagnostic to attach to the terminal assistant error so the deadline
+     *  reaches the stophook without regex-parsing the message. Built inline (not via
+     *  pi-ai's `createAssistantMessageDiagnostic`) to keep this module's runtime
+     *  import graph pi-free — the shape matches `AssistantMessageDiagnostic`. */
+    toDiagnostic(): AssistantMessageDiagnostic;
+}
+/** Strictly read the managed-cooling deadline (epoch ms) off an assistant
+ *  message's diagnostics. Returns the finite, strictly-positive `rateLimitedUntil`
+ *  from the first cooling diagnostic, or undefined when the message carries none
+ *  (or a malformed one). */
+export declare function hasManagedProviderCoolingDiagnostic(message: unknown): boolean;
+export declare function extractCoolingDeadline(message: unknown): number | undefined;

package/dist/core/runtime/managed-provider-cooling.js

@@ -0,0 +1 @@
+var s=Object.defineProperty;var e=(i,t)=>s(i,"name",{value:t,configurable:!0});const a="crtr:managed-provider-cooling",d="managed_provider_cooling";class g extends Error{static{e(this,"ManagedProviderCoolingError")}code=d;rateLimitedUntil;constructor(t,r){super(t),this.name="ManagedProviderCoolingError",this.rateLimitedUntil=r}toDiagnostic(){return{type:a,timestamp:Date.now(),details:{rateLimitedUntil:this.rateLimitedUntil}}}}function l(i){const t=i?.diagnostics;return Array.isArray(t)&&t.some(r=>r?.type===a)}e(l,"hasManagedProviderCoolingDiagnostic");function u(i){const t=i?.diagnostics;if(Array.isArray(t))for(const r of t){if(r?.type!==a)continue;const n=r?.details?.rateLimitedUntil,o=typeof n=="number"?n:Number(n);if(Number.isFinite(o)&&o>0)return o}}e(u,"extractCoolingDeadline");export{d as MANAGED_PROVIDER_COOLING_CODE,a as MANAGED_PROVIDER_COOLING_DIAGNOSTIC,g as ManagedProviderCoolingError,u as extractCoolingDeadline,l as hasManagedProviderCoolingDiagnostic};

package/dist/core/runtime/model-registry.d.ts

@@ -0,0 +1,3 @@
+import { ModelRegistry } from '@earendil-works/pi-coding-agent';
+/** Open pi's credential-backed model registry for runtime model resolution. */
+export declare function openModelRegistry(): Promise<ModelRegistry>;

package/dist/core/runtime/model-registry.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var r=(o,e)=>i(o,"name",{value:e,configurable:!0});import{join as t}from"node:path";import{ModelRegistry as n,ModelRuntime as m}from"@earendil-works/pi-coding-agent";import{PoolCredentialStore as s}from"../pool-credential-store.js";import{piAgentDir as a}from"./package-health.js";import{secretsDir as l}from"../layout.js";async function j(){const o=a(),e=await m.create({credentials:new s(t(l(),"auth.json")),modelsPath:t(o,"models.json")});return new n(e)}r(j,"openModelRegistry");export{j as openModelRegistry};

package/dist/core/runtime/model-selection.d.ts

@@ -0,0 +1,54 @@
+import type { ModelProvider, ModelStrength, ScopeConfig } from '../../types.js';
+/** Model-ladder resolution goes through `readMergedLaunchConfig` — the SAME
+ *  project-stack > profile > user > builtin precedence `resolveKindConfig`
+ *  already uses for `kinds` — so a project/profile override of `modelLadders`
+ *  is honored identically to a kind override, instead of this file reading
+ *  only user config. */
+export declare function modelLadders(): ScopeConfig['modelLadders'];
+/** Env var naming the DEFAULT provider for an UNqualified bare strength only.
+ *  `CRTR_MODEL_PROVIDER=openai` (case-insensitive) makes a bare `strong` resolve
+ *  on the OpenAI ladder; anything else defaults to Anthropic. A configured
+ *  defaultProvider in config.json wins over this env. */
+export declare const OPENAI_PROVIDER_ENV = "CRTR_MODEL_PROVIDER";
+export declare function defaultProvider(ladders?: ScopeConfig['modelLadders']): ModelProvider;
+/** Strength synonyms accepted from personas/callers. */
+export declare const STRENGTH_ALIASES: Record<string, ModelStrength>;
+export declare const MODEL_PROVIDER_KEYS: ModelProvider[];
+export declare const MODEL_STRENGTHS: ModelStrength[];
+/** Canonical user-facing grammar for a durable model override. Help and
+ *  recovery paths compose from this one phrase so accepted forms cannot drift. */
+export declare const MODEL_SPEC_FORMS: string;
+export declare const MODEL_SPEC_NEXT: string;
+/** The ladder providers a picker/cycle should OFFER: a provider column is kept
+ *  only when at least one of its ladder cells names a runtime provider the
+ *  caller reports as signed in (`isConfigured` — e.g. pool occupancy or
+ *  `registry.getProviderAuthStatus(id).configured`). A user who never logged
+ *  into Codex sees no openai column in settings and no openai rungs on Alt+M.
+ *  When NO column qualifies (a fresh install before any login), every provider
+ *  is returned: the model surfaces must stay reachable so the user can still
+ *  inspect config and go sign in. Resolution (`normalizeModel` etc.) is
+ *  deliberately NOT gated — an explicit `openai/strong` request still resolves
+ *  and then fails/falls back through the normal auth-aware launch policy. */
+export declare function configuredLadderProviders(isConfigured: (runtimeProviderId: string) => boolean, ladders?: ScopeConfig['modelLadders']): ModelProvider[];
+export declare const THINKING_SUFFIXES: Set<string>;
+export declare function parseModelSpec<T extends string = string>(spec: string): {
+    modelSpec: string;
+    thinkingLevel?: T;
+};
+export declare function isUnknownModel(model: {
+    provider?: string;
+    id?: string;
+    api?: string;
+} | null | undefined): boolean;
+export declare function stripThinkingSuffix(spec: string): string;
+export interface PortableModelSelection {
+    provider: ModelProvider;
+    strength: ModelStrength;
+}
+/** Choose the provider×strength option an editor should highlight for an
+ * existing model value. Portable tokens follow the exact provider rules used
+ * by `normalizeModel`; concrete ladder refs map back to their configured cell,
+ * ignoring a thinking suffix only after an exact match. An off-ladder concrete
+ * ref retains a recognizable provider and starts at `ultra`; an unrecognized
+ * value starts at `ultra` on the effective default provider. */
+export declare function inferPortableModelSelection(model: string | undefined, ladders?: ScopeConfig['modelLadders']): PortableModelSelection;

package/dist/core/runtime/model-selection.js

@@ -0,0 +1 @@
+var m=Object.defineProperty;var i=(r,e)=>m(r,"name",{value:e,configurable:!0});import{readMergedLaunchConfig as x}from"../config.js";function p(){return x().modelLadders}i(p,"modelLadders");const v="CRTR_MODEL_PROVIDER";function d(r=p()){const e=r.defaultProvider;return e==="anthropic"||e==="openai"?e:(process.env[v]??"").toLowerCase()==="openai"?"openai":"anthropic"}i(d,"defaultProvider");const l={ultra:"ultra",strong:"strong",medium:"medium",light:"light",normal:"medium",weak:"light"},u=["anthropic","openai"],c=["ultra","strong","medium","light"],E=`an exact registered provider/id; provider/tier where provider is ${u.join("|")} and tier is ${c.join("|")}; a bare tier (${c.join("|")}); or a family alias (opus|sonnet|haiku)`,_=`Pass ${E}.`;function L(r,e=p()){const n=u.filter(s=>c.some(f=>{const a=e[s][f],t=a.indexOf("/");return t>0&&r(a.slice(0,t))}));return n.length>0?n:[...u]}i(L,"configuredLadderProviders");const h=new Set(["off","minimal","low","medium","high","xhigh","max"]);function P(r){const e=r.lastIndexOf(":");if(e<=0)return{modelSpec:r};const n=r.slice(e+1);return h.has(n)?{modelSpec:r.slice(0,e),thinkingLevel:n}:{modelSpec:r}}i(P,"parseModelSpec");function I(r){return r?.provider==="unknown"&&r.id==="unknown"&&r.api==="unknown"}i(I,"isUnknownModel");function g(r){const e=r.lastIndexOf(":");return e<=0?r:h.has(r.slice(e+1))?r.slice(0,e):r}i(g,"stripThinkingSuffix");function R(r,e=p()){const n=r?.trim()??"";if(n!==""){const s=n.indexOf("/");if(s>0){const t=n.slice(0,s),o=l[n.slice(s+1)];if((t==="anthropic"||t==="openai")&&o!==void 0)return{provider:t,strength:o}}else{const t=l[n];if(t!==void 0)return{provider:d(e),strength:t};if(n==="opus")return{provider:"anthropic",strength:"strong"};if(n==="sonnet")return{provider:"anthropic",strength:"medium"};if(n==="haiku")return{provider:"anthropic",strength:"light"}}for(const t of u)for(const o of c)if(e[t][o]===n)return{provider:t,strength:o};const f=g(n);for(const t of u)for(const o of c)if(g(e[t][o])===f)return{provider:t,strength:o};const a=s>0?n.slice(0,s):"";if(a==="anthropic")return{provider:"anthropic",strength:"ultra"};if(a==="openai"||a==="openai-codex")return{provider:"openai",strength:"ultra"}}return{provider:d(e),strength:"ultra"}}i(R,"inferPortableModelSelection");export{u as MODEL_PROVIDER_KEYS,E as MODEL_SPEC_FORMS,_ as MODEL_SPEC_NEXT,c as MODEL_STRENGTHS,v as OPENAI_PROVIDER_ENV,l as STRENGTH_ALIASES,h as THINKING_SUFFIXES,L as configuredLadderProviders,d as defaultProvider,R as inferPortableModelSelection,I as isUnknownModel,p as modelLadders,P as parseModelSpec,g as stripThinkingSuffix};

package/dist/core/runtime/model-swap.d.ts

@@ -0,0 +1,26 @@
+import { type NodeMeta } from '../canvas/index.js';
+import type { ModelIntent } from '../../types.js';
+/** True when the node's broker engine is reachable: its recorded pid is alive
+ *  AND its view.sock exists. Both are required — a dead pid with a stale socket,
+ *  or a live pid mid-boot before it binds the socket, is NOT a live broker. */
+export declare function isBrokerLive(node: Pick<NodeMeta, 'node_id' | 'pi_pid'>): boolean;
+/** Swap a LIVE node's model over its view.sock. Connects as a controller,
+ *  sends `set_model`, and resolves with the broker-resolved durable spec from its
+ *  `model_changed` frame. Rejects with the broker's message on an `error` frame (e.g.
+ *  `no model matching '<spec>' in the registry`), on connect failure, or timeout.
+ *  `intent` is the routing contract the CALLER derived from the RAW token
+ *  (`explicitModelIntent`); `spec` is already normalized, so its shape no longer
+ *  says whether the pick was portable. Undefined means an exact model. */
+export declare function setModelLive(nodeId: string, spec: string, intent: ModelIntent | undefined): Promise<string>;
+/** Write a model choice into a node's durable recipe: `model_override` (so
+ *  polymorphs preserve it via buildLaunchSpec) and `launch.model`. A
+ *  `userSelected` change also replaces the routing contract the next revive
+ *  replays: with an `intent`, `launch.modelIntent` + `CRTR_MODEL_INTENT` (the
+ *  route may rotate to another family at that strength); without one,
+ *  `launch.modelExact` (the model runs verbatim). `spec` must already be a
+ *  concrete `provider/id` (normalizeModel maps tiers/aliases; a bare substring
+ *  cannot resolve offline). */
+export declare function updateModelRecipe(meta: NodeMeta, spec: string, intent: ModelIntent | undefined, userSelected: boolean): NodeMeta;
+/** Persist a user's model choice into a DORMANT node's durable recipe — the same
+ *  write the broker commits on a live switch. */
+export declare function persistDormantModel(nodeId: string, spec: string, intent: ModelIntent | undefined): void;

package/dist/core/runtime/model-swap.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var n=(e,o)=>u(e,"name",{value:o,configurable:!0});import{existsSync as c}from"node:fs";import{getNode as s,updateNode as f}from"../canvas/index.js";import{viewSocketPath as p}from"../canvas/paths.js";import{isPidAlive as _}from"../canvas/pid.js";import{oneShotControllerRequest as a}from"./broker-request.js";function y(e){return _(e.pi_pid)&&c(p(e.node_id))}n(y,"isBrokerLive");function L(e,o,t){let d;return a({nodeId:e,what:"the model switch",ackFor:"set_model",frame:n(()=>({type:"set_model",model:o,...t!==void 0?{intent:t}:{}}),"frame"),observe:n(r=>{r.type==="model_changed"&&r.spec!==null&&(d=r.spec)},"observe"),result:n(()=>d??o,"result")})}n(L,"setModelLive");function v(e,o,t,d){const r=e.launch===void 0?void 0:d?(()=>{const{modelIntent:h,modelExact:E,env:m,...l}=e.launch,{CRTR_MODEL_INTENT:x,...i}=m;return t!==void 0?{...l,model:o,modelIntent:t,env:{...i,CRTR_MODEL_INTENT:`${t.family}/${t.strength}`}}:{...l,model:o,modelExact:!0,env:i}})():{...e.launch,model:o};return f(e.node_id,{model_override:o,...r!==void 0?{launch:r}:{}})}n(v,"updateModelRecipe");function S(e,o,t){const d=s(e);d!==null&&v(d,o,t,!0)}n(S,"persistDormantModel");export{y as isBrokerLive,S as persistDormantModel,L as setModelLive,v as updateModelRecipe};

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

@@ -0,0 +1,69 @@
+/** Coerce arbitrary text into a 3-8 word kebab-case name, or '' if nothing
+ *  usable survives. Lowercases, keeps [a-z0-9], collapses everything else to a
+ *  single hyphen, and clamps to the first 8 words. */
+export declare function sanitizeSessionName(raw: string): string;
+/** Coerce arbitrary text into a one-line prose title, or '' if nothing usable
+ *  survives. Takes the first non-empty line, collapses runs of whitespace, drops
+ *  wrapping quotes, clamps at a word boundary, and capitalizes the opening
+ *  letter. Punctuation INSIDE the line survives — carrying it is what `title`
+ *  is for. */
+export declare function sanitizeSessionTitle(raw: string): string;
+/** Local fallback: the opening of the prompt as a title (no pi call), with its
+ *  punctuation. Whitespace collapses first so a multi-line message contributes
+ *  its actual opening words rather than whatever its first line happened to be. */
+export declare function titleFromPrompt(prompt: string): string;
+/** Local fallback: derive a kebab handle straight from the prompt (no pi call),
+ *  from the same opening words the fallback title keeps. */
+export declare function slugFromPrompt(prompt: string): string;
+/** The namer's model: the `light` rung of the DEFAULT provider's ladder, with
+ *  any thinking suffix stripped because the one-shot session uses thinking off.
+ *  Reading the ladder rather than pinning a concrete model id keeps naming working for a
+ *  user who never configured Anthropic: an OpenAI default provider resolves to
+ *  its own light rung. `CRTR_NAME_MODEL` still overrides. */
+export declare function lightModel(overrideEnv?: string): string;
+/** A generated session label: the kebab-case handle, the prose title, and the
+ *  Nerd Font glyph the namer chose. `title` is '' when the model gave nothing
+ *  usable, leaving the caller to fall back to the prompt's own opening words;
+ *  `icon` is '' on the same terms, and every surface renders the name alone in
+ *  that case. */
+export interface SessionName {
+    name: string;
+    title: string;
+    icon: string;
+}
+/** Normalize a model-supplied icon to a single renderable glyph, or '' when
+ *  nothing usable came back.
+ *
+ *  The model is asked for a `U+XXXX` codepoint rather than the literal
+ *  character: Nerd Font glyphs sit in the private-use areas, which models
+ *  reproduce unreliably as literal text (they tend to substitute an emoji), but
+ *  name accurately as codepoints. A literal glyph is still accepted — including
+ *  an emoji, which renders fine even if it is not the house style — so a model
+ *  that ignores the format still contributes. Rejects a spelled-out
+ *  `nf-fa-bug`, a bare ASCII letter, and anything multi-glyph, all of which
+ *  would render as noise or tofu in a label. */
+export declare function sanitizeIcon(raw: string): string;
+/** Ask Pi headlessly for a structured {name, title, icon} for `body`, async.
+ *  Resolves to a sanitized SessionName, or `{name:'',title:'',icon:''}` on
+ *  timeout, a missing tool call, or a malformed emission so the caller can fall
+ *  back to the prompt's own words.
+ *
+ *  Nothing FORCES the tool call — constrained sampling shapes the arguments once
+ *  the model decides to call it — so a model that answers in prose instead gets
+ *  one more attempt before the caller falls back.
+ *
+ *  This module stays canvas-free so CLI leaves can reach it. The canvas-coupled
+ *  commit path lives in pi-extensions/broker-local.ts, which imports this pure
+ *  helper and writes through crtrd's guarded generated-name operation. */
+export declare function headlessName(body: string, sourceCap?: number): Promise<SessionName>;
+/** Generate a name from a bounded conversation source rather than a single
+ *  kickoff message. The caller owns selecting representative conversation text;
+ *  this cap keeps the one-shot prompt compact. */
+export declare function headlessNameFromConversation(conversation: string): Promise<SessionName>;
+/** A filesystem-safe slug for the `.todos/<slug>.md` fallback path: lowercase,
+ *  [a-z0-9] kept, everything else → single hyphen, clamped to 8 words. */
+export declare function titleSlug(title: string): string;
+/** Ask Pi headlessly for a one-line issue title for `note`. Resolves to the
+ *  generated title, or a local first-line fallback on timeout or empty output.
+ *  Async; never throws. */
+export declare function generateIssueTitle(note: string): Promise<string>;

package/dist/core/runtime/naming.js

@@ -0,0 +1,14 @@
+var U=Object.defineProperty;var s=(e,t)=>U(e,"name",{value:t,configurable:!0});import{headlessText as k,headlessToolCall as p}from"./headless-pi.js";import{defaultProvider as h,modelLadders as m,stripThinkingSuffix as g}from"./model-selection.js";const a=2e3,f=45e3,x=["fixing/diagnosis: U+F188 bug, U+F0F1 stethoscope, U+F06D fire, U+F071 warning","building/changing code: U+F0AD wrench, U+F067 plus, U+F121 code, U+F085 cogs, U+F021 refresh","testing/verifying: U+F0C3 flask, U+F00C check, U+F24E balance","writing/docs/research: U+F02D book, U+F15C document, U+F002 magnifier, U+F0EB lightbulb","data/infra: U+F1C0 database, U+F0C2 cloud, U+F120 terminal, U+F013 gear, U+F1B3 packages","ship/perf/scale: U+F135 rocket, U+F0E7 bolt, U+F080 chart, U+F201 trend line","security/access: U+F132 shield, U+F023 lock, U+F084 key","interface/design: U+F1FC paintbrush, U+F03E image, U+F108 display","communication/coordination: U+F1D8 paper plane, U+F0E6 comments, U+F0E8 sitemap, U+F0C1 link"].join(`
+`),T="You label agent sessions. A session is whatever a person opened it for: a coding task, a question, a piece of research, an idea they are turning over, or an ordinary conversation. You are labelling that session, never taking part in it \u2014 do not answer the message, do not do the work it asks for, do not comment on it. Every session gets a label, however short, casual, misspelled, or open-ended its opening message is.\n\nCall the `name_session` tool exactly once with:\n- `title`: how a person would refer to this session in a list of their conversations \u2014 2-8 words, sentence case, written naturally with its punctuation intact (e.g. `What's your favorite color?`, `Payroll export mapping bug`, `Ideas for the launch email`). No quotes, no markdown, no trailing period.\n- `name`: the same subject as a concise 3-8 word kebab-case handle \u2014 lowercase words joined by single hyphens (e.g. `favorite-color-question`, `refactor-auth-token-flow`). No punctuation, quotes, or prose.\n- `icon`: ONE Nerd Font glyph, written as its codepoint in `U+XXXX` form (e.g. `U+F188`). Emit a codepoint, not a name like `nf-fa-bug`, and not an emoji.\n\nChoosing the icon \u2014 work through it in this order:\n1. Name the concrete SUBJECT of the task: the thing being acted on. A font, a trash can, an account, a browser tab, a clock, an invoice, a map, a robot, a specific technology's logo. If a glyph depicts that thing, use it. This is almost always the better icon, because it is what distinguishes this session from every other one.\n2. Only when the task has no depictable subject, fall back to the ACTIVITY (fixing, documenting, testing) using the generic set below.\n\nANY Nerd Font codepoint is allowed and the set is enormous \u2014 the whole Font Awesome range, Devicons and Seti technology logos, Octicons, Codicons, Weather, and the thousands of Material Design nouns above U+F0001. Reach into it. The examples below are the generic tier, NOT a menu: if your pick came from them and the task had a real subject, you picked wrong. Never reuse a generic gear, wrench, or bug for a task that is actually about something.\n\nGeneric fallback set, by kind of work:\n"+x;function C(e,t=a){return`<source>
+${e.slice(0,t)}
+</source>
+
+Label the session this text is from: call \`name_session\` once with a title, a name, and an icon depicting it, then stop. Do not answer it.`}s(C,"nameUserPrompt");const c=72;function l(e){return((e??"").split(`
+`).map(o=>o.trim()).find(o=>o!=="")??"").toLowerCase().replace(/[^a-z0-9]+/g,"-").split("-").filter(o=>o!=="").slice(0,8).join("-")}s(l,"sanitizeSessionName");function w(e){const n=((e??"").split(`
+`).map(i=>i.trim()).find(i=>i!=="")??"").replace(/\s+/g," ").replace(/^["'`]+|["'`]+$/g,"").trim();if(n==="")return"";let o=n;if(n.length>c){const i=n.slice(0,c),r=i.lastIndexOf(" ");o=`${(r>c/2?i.slice(0,r):i).trimEnd()}\u2026`}return o.charAt(0).toUpperCase()+o.slice(1)}s(w,"sanitizeSessionTitle");function E(e){return w((e??"").replace(/\s+/g," "))}s(E,"titleFromPrompt");function O(e){return l(E(e))||"session"}s(O,"slugFromPrompt");function j(e){const t=e===void 0?void 0:process.env[e];if(t!==void 0&&t.trim()!=="")return t.trim();const n=m();return g(n[h(n)].light)}s(j,"lightModel");function b(){const e=process.env.CRTR_NAME_MODEL;if(e!==void 0&&e.trim()!=="")return{modelSpec:e.trim()};const t=m(),n=h(t);return{modelSpec:g(t[n].light),modelIntent:`${n}/light`}}s(b,"nameModelRequest");const N={type:"object",properties:{title:{type:"string",description:"A 2-8 word sentence-case title a person would recognize this session by in a list, with its punctuation intact, e.g. Payroll export mapping bug. No quotes, markdown, or trailing period."},name:{type:"string",description:"A 3-8 word kebab-case session name: lowercase words joined by single hyphens, e.g. refactor-auth-token-flow. No punctuation, quotes, or prose."},icon:{type:"string",description:"The Nerd Font glyph depicting this session, as a codepoint in U+XXXX form (e.g. U+F188)."}},required:["title","name","icon"],additionalProperties:!1};function v(e){const t=(e??"").trim();if(t==="")return"";const n=/^(?:u\+|0x|\\u\{?|&#x)?([0-9a-f]{4,6})\}?;?$/i.exec(t);if(n!==null){const i=Number.parseInt(n[1],16);if(i>=8192&&i<=1114111)try{return String.fromCodePoint(i)}catch{return""}return""}const o=[...t];return o.length>2?"":o[0].codePointAt(0)>=8192?t:""}s(v,"sanitizeIcon");async function P(e,t=a){const n={name:"",title:"",icon:""},o={systemPrompt:T,userPrompt:C(e,t),...b(),timeoutMs:f,tool:{name:"name_session",label:"Name session",description:"Record the title, name, and icon for this session. Call exactly once, then stop.",parameters:N,constrainedSampling:{type:"json_schema",strict:"prefer"}}},i=await p(o)??await p(o);if(i===null||typeof i!="object")return n;const r=i,u=w(typeof r.title=="string"?r.title:""),d=l(typeof r.name=="string"?r.name:"")||l(u),F=v(typeof r.icon=="string"?r.icon:"");return d!==""?{name:d,title:u,icon:F}:n}s(P,"headlessName");function L(e){return P(e,3e4)}s(L,"headlessNameFromConversation");const S='You write GitHub issue titles. Given a free-text note (a todo, idea, or bug report), reply with ONLY a concise issue title: sentence case, 4-10 words, no trailing period, no quotes, no prefix like "Bug:" or "Idea:", no markdown. Capture the gist as an actionable title. Output JUST the title, nothing else.';function M(e){return`<note>
+${e.slice(0,a)}
+</note>
+
+Write a concise GitHub issue title for the note above. Output JUST the title, nothing else.`}s(M,"titleUserPrompt");function y(e){const t=(e??"").split(`
+`).map(o=>o.trim()).find(o=>o!=="")??"",n=t.length>80?`${t.slice(0,77).trimEnd()}\u2026`:t;return n!==""?n:"untitled"}s(y,"firstLineTitle");function q(e){return(e??"").toLowerCase().replace(/[^a-z0-9]+/g,"-").split("-").filter(n=>n!=="").slice(0,8).join("-")||"untitled"}s(q,"titleSlug");async function X(e){const t=(e??"").trim();if(t==="")return"untitled";try{const o=(await k({systemPrompt:S,userPrompt:M(t),...b(),timeoutMs:f})).split(`
+`).map(i=>i.trim()).find(i=>i!=="")??"";return o!==""?o.replace(/^["']|["']$/g,"").replace(/\.$/,""):y(t)}catch{return y(t)}}s(X,"generateIssueTitle");export{X as generateIssueTitle,P as headlessName,L as headlessNameFromConversation,j as lightModel,v as sanitizeIcon,l as sanitizeSessionName,w as sanitizeSessionTitle,O as slugFromPrompt,E as titleFromPrompt,q as titleSlug};

package/dist/core/runtime/nerd-font.d.ts

@@ -0,0 +1,46 @@
+export interface NerdFontDetection {
+    /** A Nerd Font face is installed somewhere on this system. */
+    installed: boolean;
+    /** The family or filename that matched, for the doctor message. */
+    evidence: string | null;
+    /** How the match was found — fontconfig query, or a font-directory scan. */
+    source: 'fc-list' | 'font-dir' | null;
+}
+export declare function detectNerdFont(platform?: NodeJS.Platform, home?: string): NerdFontDetection;
+/** Download the upstream symbols-only patch into the user's font dir. Works on
+ *  every Linux regardless of package manager — Debian/Ubuntu and Fedora ship no
+ *  Nerd Font package, so there is nothing native to install there. Needs no
+ *  sudo: it writes to `~/.local/share/fonts`.
+ *
+ *  curl runs with its progress meter on (no `-s`) because this is the one
+ *  install step with a real download percentage: setup captures that stderr
+ *  and drives the step's progress bar from it (`parseCurlPercent`). */
+export declare const NERD_FONT_MANUAL_LINUX_COMMAND: string;
+/** Reads percent complete out of curl's default progress meter as its stderr
+ *  arrives. Rows are separated by `\r` and look like
+ *  `100  1234k  100  1234k    0     0   987k      0 --:--:-- …`; the leading
+ *  column is the percentage of the whole transfer, and the header rows
+ *  (`  % Total    % Received …`) start with `%` so they never match.
+ *
+ *  Stateful because curl's writes split rows anywhere: the tail of a chunk is
+ *  held back until its row is terminated. Reading a half-row instead lands on
+ *  a different column and reports a number that was never true — in practice
+ *  the completed download's own summary row parsed as 0%.
+ *
+ *  Returns the percentage of the last complete row in this chunk, or null when
+ *  the chunk completed no row. */
+export declare function createCurlPercentReader(): (chunk: string) => number | null;
+export interface NerdFontInstallCommand {
+    command: string | null;
+    hint: string;
+    autoInstall: boolean;
+}
+/** The install command for this platform/package manager. `packageManager`
+ *  matches setup's detection: only brew and pacman have a real Nerd Font
+ *  package, everything else on Linux gets the upstream download. A non-brew
+ *  package manager only ever exists on Linux, so it settles the platform on its
+ *  own and `platform` decides only the `manual` case. */
+export declare function nerdFontInstallCommand(packageManager: 'brew' | 'apt-get' | 'dnf' | 'pacman' | 'manual', platform?: NodeJS.Platform): NerdFontInstallCommand;
+/** Every install path ends the same way: the font is on disk but the terminal
+ *  emulator still has to be pointed at it, and crtr cannot do that. */
+export declare const NERD_FONT_SELECT_HINT = "then set your terminal profile's font to a Nerd Font (e.g. add \"Symbols Nerd Font Mono\" as the non-ASCII/fallback font) \u2014 installing it does not select it";

package/dist/core/runtime/nerd-font.js

@@ -0,0 +1,2 @@
+var d=Object.defineProperty;var e=(n,t)=>d(n,"name",{value:t,configurable:!0});import{spawnSync as u}from"node:child_process";import{readdirSync as m}from"node:fs";import{homedir as p}from"node:os";import{join as l}from"node:path";const c=/nerd[ _-]?font|symbolsnerdfont|symbols-only/i;function y(n,t){return n==="darwin"?[l(t,"Library","Fonts"),"/Library/Fonts","/System/Library/Fonts"]:[l(t,".local","share","fonts"),l(t,".fonts"),"/usr/local/share/fonts","/usr/share/fonts"]}e(y,"fontDirs");function a(n,t){if(t<0)return null;let o;try{o=m(n,{withFileTypes:!0})}catch{return null}for(const r of o){if(r.isDirectory()){const s=a(l(n,r.name),t-1);if(s!==null)return s;continue}if(/\.(ttf|otf|ttc)$/i.test(r.name)&&c.test(r.name))return r.name}return null}e(a,"scanForNerdFont");function b(){if(u("sh",["-lc","command -v fc-list >/dev/null 2>&1"],{stdio:"ignore"}).status!==0)return null;const t=u("fc-list",[":","family"],{encoding:"utf8",timeout:5e3});if(t.status!==0||typeof t.stdout!="string")return null;for(const o of t.stdout.split(`
+`))if(c.test(o))return o.split(",")[0].trim();return""}e(b,"queryFontconfig");function I(n=process.platform,t=p()){if(n!=="darwin"){const o=b();if(o!==null&&o!=="")return{installed:!0,evidence:o,source:"fc-list"}}for(const o of y(n,t)){const r=a(o,3);if(r!==null)return{installed:!0,evidence:r,source:"font-dir"}}return{installed:!1,evidence:null,source:null}}e(I,"detectNerdFont");const N="mkdir -p ~/.local/share/fonts && curl -fL -o /tmp/NerdFontsSymbolsOnly.zip https://github.com/ryanoasis/nerd-fonts/releases/latest/download/NerdFontsSymbolsOnly.zip && unzip -oq /tmp/NerdFontsSymbolsOnly.zip -d ~/.local/share/fonts && fc-cache -f";function L(){let n="";return t=>{n+=t;const o=n.split(/[\r\n]/);n=o.pop()??"";let r=null;for(const s of o){const i=/^\s*(\d{1,3})\s+\S+\s+\d{1,3}\s/.exec(s);if(i===null)continue;const f=Number(i[1]);f<=100&&(r=f)}return r}}e(L,"createCurlPercentReader");function T(n,t=process.platform){const o=t!=="darwin"||n==="apt-get"||n==="dnf"||n==="pacman";return n==="brew"?{command:"brew install --cask font-symbols-only-nerd-font",hint:"Homebrew cask",autoInstall:!0}:n==="pacman"?{command:"sudo pacman -S --noconfirm ttf-nerd-fonts-symbols",hint:"pacman install",autoInstall:!0}:o?{command:N,hint:"download symbols-only patch to ~/.local/share/fonts (needs curl + unzip)",autoInstall:!0}:{command:null,hint:"install Homebrew, or download a Nerd Font from https://nerdfonts.com and add it in Font Book",autoInstall:!1}}e(T,"nerdFontInstallCommand");const x=`then set your terminal profile's font to a Nerd Font (e.g. add "Symbols Nerd Font Mono" as the non-ASCII/fallback font) \u2014 installing it does not select it`;export{N as NERD_FONT_MANUAL_LINUX_COMMAND,x as NERD_FONT_SELECT_HINT,L as createCurlPercentReader,I as detectNerdFont,T as nerdFontInstallCommand};

package/dist/core/runtime/node-id-token.d.ts

@@ -0,0 +1,6 @@
+/** True when `token` could name a node: the full id (`<install>-<time>-<rand>`)
+ *  or a prefix of it — the pickers, Find node and the viewer show the first 8
+ *  characters, which has no hyphen. A shape check only; whether it IS a node is
+ *  decided against the node list. Four characters minimum so a short ordinary
+ *  word is not swallowed. */
+export declare function looksLikeNodeIdToken(token: string): boolean;

package/dist/core/runtime/node-id-token.js

@@ -0,0 +1 @@
+var o=Object.defineProperty;var t=(e,n)=>o(e,"name",{value:n,configurable:!0});function r(e){return e.length>=4&&e.length<=128&&/^[a-z0-9]+(-[a-z0-9]+)*$/.test(e)}t(r,"looksLikeNodeIdToken");export{r as looksLikeNodeIdToken};