@north-light/cli 0.0.0 → 0.3.414

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

@@ -0,0 +1,93 @@
+import { InputError } from '../io.js';
+import type { HostHandle } from './host.js';
+/** The daemon's live-broker thresholds. The hard cap is the ledger's admission
+ *  bound; `warning` is the saturation notice supervision fires below it. Lives
+ *  here — beside the ledger that enforces it — so the ledger, a refusal
+ *  message, and supervision's warning all read ONE definition. */
+export declare function brokerThresholdsForDaemon(): {
+    warning: number;
+    automaticReviveCap: number;
+};
+/** The typed refusal a caller that cannot wait gets when the ledger is full.
+ *  An InputError so its details round-trip through crtrd's error body and reach
+ *  a CLI caller as the real cap text instead of an opaque 5xx. */
+export declare function brokerCapReached(cap: number, live: number): InputError;
+/** Real child-exit status, exactly as Node reports it. Codes/signals are
+ *  diagnostics only — never policy inputs (design D-4). */
+export interface FleetExitStatus {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+    /** The kernel's OOM killer ended the run's cgroup (hosted runtimes only). */
+    oomKilled?: boolean;
+}
+export interface FleetEntry {
+    /** The broker's supervised pid (never null — a launch with no pid is not
+     *  registered). */
+    pid: number;
+    /** The ChildProcess-backed handle (host.ts) whose `exited` promise is the
+     *  liveness authority. */
+    handle: HostHandle;
+}
+export interface FleetRegistry {
+    /** This daemon's epoch id — minted at boot, stamped into every broker's argv
+     *  (`--epoch <id>`) so the next daemon's startup census can reap every
+     *  prior-epoch broker without adoption. */
+    epoch(): string;
+    /** Record a just-spawned broker. Sync; THROWS if an entry already exists —
+     *  a second launch for a live node is a programming error, never silently
+     *  tolerated. */
+    register(nodeId: string, handle: HostHandle): void;
+    /** The reviveNode double-launch guard: a fleet entry IS liveness. */
+    has(nodeId: string): boolean;
+    /** True while ANY launch claim exists for this node — a registered broker OR
+     *  an in-flight reservation. `has` alone reads false during the window
+     *  between `reserveSlot` and registration, so a caller asking "could this
+     *  node come back to life right now?" (the managed-worktree sweep, before it
+     *  destroys a checkout) must ask this instead. */
+    isClaimed(nodeId: string): boolean;
+    /** Live-fleet checks pass (yield-stall, wedge, fatal-fault). */
+    get(nodeId: string): FleetEntry | undefined;
+    /** The capacity count: registered brokers only, excluding reservations. */
+    size(): number;
+    /** Every slot the cap accounts for — registered brokers plus launch
+     *  reservations that have not registered yet. */
+    occupancy(): number;
+    /** Claim a slot for `nodeId`. True means the caller may launch; false means
+     *  the cap is reached and the caller must freeze or refuse. Idempotent — a
+     *  node that already holds a slot (reserved or registered) gets true without
+     *  consuming a second one. */
+    reserveSlot(nodeId: string): boolean;
+    /** Give back a slot claimed by `reserveSlot` and not consumed by a launch. */
+    releaseReservation(nodeId: string): void;
+    entries(): Iterable<[string, FleetEntry]>;
+    /** Mark this exact broker's pause interruption before directly sending it
+     * SIGTERM. An explicit pid is the identity-checked fallback when the daemon
+     * has not registered a handle yet. */
+    interruptForProfilePause(nodeId: string, pid?: number): void;
+    /** Whether the next dead-row policy pass must absorb this pause interruption
+     * before a later pass may recover the row normally. */
+    hasProfilePauseInterruption(nodeId: string): boolean;
+    /** Drop an entry without policy (terminal exits + close paths). */
+    forget(nodeId: string): void;
+    /** Wired by `headlessBrokerHost.launch` to the handle's `exited` promise.
+     *  Removes the entry (freeing the capacity slot), then enqueues its
+     *  observation on the daemon's serial work lane — it never runs inline on
+     *  the Node event callback (design D-3). */
+    onChildExit(nodeId: string, status: FleetExitStatus, executionId?: string): void;
+    /** Test seam — delivers a synthetic exit through the SAME path as
+     *  onChildExit, so fabricated-row tests drive policy without a process. */
+    deliverExit(nodeId: string, status: FleetExitStatus): void;
+    /** The node-lifecycle tick's enactment entry: classify a row known to have no
+     *  live engine and enact through the SAME policy table exit events use, so
+     *  tick recovery and exit recovery can never diverge. */
+    applyDeadRowPolicy(nodeId: string): Promise<void>;
+}
+/** Inject the daemon's fleet registry. Idempotent for the same instance;
+ *  throws on a conflicting rebind (one registry per process, ever). */
+export declare function bindFleet(registry: FleetRegistry): void;
+/** The bound registry. Throws when unbound: broker launches happen only inside
+ *  crtrd (or a test harness that explicitly bound an in-process fleet). */
+export declare function boundFleet(): FleetRegistry;
+/** Test-only: clear the process-global binding, mirroring
+ *  resetEventSourceForTests. Production processes bind exactly once. */
+export declare function resetFleetForTests(): void;

package/dist/core/runtime/fleet.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var o=(e,r)=>i(e,"name",{value:r,configurable:!0});import{readConfig as s}from"../config.js";import{InputError as a}from"../io.js";import{envMaxLiveBrokers as h,envWarnLiveBrokers as c}from"../../shared/env.js";function l(){const e=s("user").brokerThresholds,r=h()??e.automaticReviveCap,t=c()??e.warning;return{warning:Math.min(t,r),automaticReviveCap:r}}o(l,"brokerThresholdsForDaemon");function b(e,r){return new a({error:"broker_cap_reached",message:`no broker slot is free \u2014 ${r} live brokers at the cap of ${e}.`,next:"Finish or close a live node (`crtr canvas dashboard` shows them), or raise the cap with CRTR_MAX_LIVE_BROKERS, then retry."})}o(b,"brokerCapReached");let n;function v(e){if(n!==void 0&&n!==e)throw new Error("a fleet registry is already bound for this process");n=e}o(v,"bindFleet");function m(){if(n===void 0)throw new Error("no fleet registry is bound in this process \u2014 broker launches happen only inside crtrd (route launch verbs through the /v1 API)");return n}o(m,"boundFleet");function w(){n=void 0}o(w,"resetFleetForTests");export{v as bindFleet,m as boundFleet,b as brokerCapReached,l as brokerThresholdsForDaemon,w as resetFleetForTests};

package/dist/core/runtime/focus-viewer.d.ts

@@ -0,0 +1,39 @@
+import type { CrtrClient } from '../../api/index.js';
+import type { NodeDetailDTO } from '../../api/dto/nodes.js';
+export declare function viewerEnv(): Record<string, string>;
+/** The live viewer pane for `nodeId` (the pane a surface-attach viewer tagged
+ *  `@crtr_node`), or undefined. Pure tag scan over live panes. */
+export declare function viewerPaneOf(nodeId: string): string | undefined;
+export interface FocusViewerOpts {
+    cwd: string;
+    name: string;
+    pane?: string;
+    newPane?: boolean;
+    inPlace?: boolean;
+}
+export interface FocusViewerResult {
+    focused: boolean;
+    session: string | null;
+    inPlace: boolean;
+    revived: boolean;
+}
+/** Bring a node's ONE viewer forefront beside (or navigated to) the caller.
+ *  The server (`ensureAttach`) owns the broker revive + the view.sock
+ *  accept-wait; the `@crtr_node` pane tag is the viewer registry. crtr is
+ *  tmux-only: no caller pane ⇒ not focused. */
+export declare function focusViewer(client: CrtrClient, nodeId: string, opts: FocusViewerOpts): Promise<FocusViewerResult>;
+export interface FocusNodeResult {
+    focused: boolean;
+    session: string | null;
+    revived: boolean;
+    inPlace: boolean;
+}
+/** The whole `surface node focus` decision for one fetched node, placed into
+ *  `pane`: refuse a human-ask, open FINISHED work as a read-only saved
+ *  transcript popup, otherwise bring its conversation viewer into view.
+ *  Throws `InputError` for a human-ask; daemon failures propagate as `ApiError`. */
+export declare function focusNode(client: CrtrClient, node: Pick<NodeDetailDTO, 'node_id' | 'kind' | 'status' | 'lifecycle' | 'final_report' | 'cwd' | 'name'>, opts: {
+    pane: string;
+    newPane?: boolean;
+    inPlace?: boolean;
+}): Promise<FocusNodeResult>;

package/dist/core/runtime/focus-viewer.js

@@ -0,0 +1 @@
+var y=Object.defineProperty;var o=(r,e)=>y(r,"name",{value:e,configurable:!0});import{envHomeOverride as A}from"../../shared/env.js";import{isFinishedWork as E,isLiveStatus as R}from"../canvas/node-order.js";import{InputError as k}from"../io.js";import{closePane as P,currentTmux as C,displayPopupAsync as O,getPaneOption as h,listLivePanes as g,paneExists as v,paneLocation as f,renameWindow as H,respawnPaneSync as W,selectLayout as $,selectPane as _,selectWindow as L,setPaneOption as S,shellQuote as N,splitWindow as q,switchClient as z,windowOfPane as K}from"./placement-tmux.js";function M(){const r=A();return r!==void 0?{CRTR_HOME:r}:{}}o(M,"viewerEnv");function d(){return{...M(),CRTR_ATTACH_WAKE_PARKED:"0"}}o(d,"focusViewerEnv");function w(r){const e=g();if(e!==null){for(const n of e)if(h(n,"@crtr_node")===r)return n}}o(w,"viewerPaneOf");function T(r,e,n,t,a){const s=q(r,{cwd:n,env:d(),command:`crtr surface attach to ${e}`});if(s===null)return{focused:!1,session:null,inPlace:!1,revived:a};const c=f(s);return c!==null&&$(c.window,"even-horizontal"),_(s),{focused:!0,session:c?.session??t,inPlace:!1,revived:a}}o(T,"openBesideCaller");async function V(r,e,n){const t=n.pane??process.env.TMUX_PANE??C()?.pane;if(t===void 0||t==="")return{focused:!1,session:null,inPlace:!1,revived:!1};const s=(await r.ensureAttach(e,{resume:!0,revive:!0,wakeParked:!1})).revived,c=f(t)?.session??null;if(n.inPlace===!0){const i=h(t,"@crtr_node"),u=w(e);u!==void 0&&u!==t&&v(u)&&P(u);try{S(t,"@crtr_node","")}catch{}const p=K(t),x=i!==void 0&&i!==""?{...d(),CRTR_ATTACH_ROSTER:i}:d(),m=W({pane:t,cwd:n.cwd,env:x,command:`crtr surface attach to ${e}`});return m&&p!==null&&H(p,n.name),{focused:m,session:c,inPlace:!0,revived:s}}if(n.newPane===!0){const i=w(e);return i!==void 0&&v(i)&&P(i),T(t,e,n.cwd,c,s)}const l=w(e);if(l!==void 0){const i=f(l);if(i!==null)return z(i.session),L(i.session,i.window),_(l),{focused:!0,session:i.session,inPlace:!0,revived:s}}return T(t,e,n.cwd,c,s)}o(V,"focusViewer");async function U(r,e,n){const t=e.node_id;if(e.kind==="human")throw new k({error:"not_focusable",message:`node ${t} is a human-ask (kind:human), not a conversation \u2014 it has no pi session to focus.`,next:`The pending question is queued for the user; see it with \`crtr human list\`, or retract it with \`crtr human cancel ${t}\`.`});return!R(e.status)&&E({lifecycle:e.lifecycle,finalized:e.final_report!=null})?{focused:await O(n.pane,e.cwd,`crtr node inspect transcript ${N(t)}`),session:null,revived:!1,inPlace:!1}:V(r,t,{cwd:e.cwd,name:e.name,pane:n.pane,...n.newPane===!0?{newPane:!0}:{},...n.inPlace===!0?{inPlace:!0}:{}})}o(U,"focusNode");export{U as focusNode,V as focusViewer,M as viewerEnv,w as viewerPaneOf};

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

@@ -0,0 +1,5 @@
+/** Env marker set on every pi the front door boots. Its presence means we are
+ *  already inside a front-door-booted root, so a nested front-door launch must
+ *  be refused — otherwise a removed/renamed subcommand that a child pi re-runs
+ *  (e.g. `crtr node -h`) fork-bombs pi until the machine must be rebooted. */
+export declare const FRONT_DOOR_ENV = "CRTR_FRONT_DOOR";

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

@@ -0,0 +1 @@
+const O="CRTR_FRONT_DOOR";export{O as FRONT_DOOR_ENV};

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

@@ -0,0 +1,2 @@
+/** Open pi's provider picker and LoginDialogComponent before a root broker starts. */
+export declare function runFrontDoorLogin(): Promise<boolean>;

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

@@ -0,0 +1 @@
+var h=Object.defineProperty;var r=(a,t)=>h(a,"name",{value:t,configurable:!0});import{CredentialSynchronizationError as u,LoginDialogComponent as l,OAuthSelectorComponent as d}from"@earendil-works/pi-coding-agent";import{execFile as p}from"node:child_process";import{join as f}from"node:path";import{setAuthCredential as g}from"../auth-file.js";import{secretsDir as w}from"../layout.js";import{dialogAuthInteraction as y}from"../auth-interaction.js";import{isManagedProvider as C}from"../subscription-state.js";import{daemonManagedLogin as b}from"../model-auth/daemon-login.js";import{cliClient as D}from"../../commands/api-client.js";import{runSetupSettingsProcess as I}from"../../commands/sys/setup-settings-runner.js";import{buildProviderCatalog as L}from"../../commands/sys/panels/provider-panel.js";function P(a){const t=process.platform==="darwin"?"open":process.platform==="win32"?"cmd":"xdg-open",e=process.platform==="win32"?["/c","start","",a]:[a];p(t,e,{timeout:5e3},()=>{})}r(P,"openBrowser");class A{static{r(this,"FrontDoorLogin")}tui;runtime;agentDir;finish;component;dialog;settled=!1;constructor(t,e,s,o,n){this.tui=t,this.runtime=e,this.agentDir=s,this.finish=n,this.component=new d("login",o,i=>this.startLogin(o.find(m=>m.id===i)),()=>this.complete(!1))}get focused(){return this.component.focused}set focused(t){this.component.focused=t}handleInput(t){this.component.handleInput?.(t)}invalidate(){this.tui.requestRender()}render(t){return this.component.render(t)}dispose(){this.settled||this.dialog?.handleInput("\x1B")}complete(t){this.settled||(this.settled=!0,this.finish(t))}startLogin(t){if(!t){this.complete(!1);return}const e=new l(this.tui,t.id,i=>this.complete(i),t.name);this.dialog=e,this.component=e,this.tui.setFocus(this),this.tui.requestRender();const s=y(e,{openBrowser:P,onChange:r(()=>this.tui.requestRender(),"onChange"),isActive:r(()=>!this.settled&&!e.signal.aborted,"isActive")}),o=r(()=>{e.signal.aborted||this.complete(!1)},"fail");if(t.authType==="api_key"){e.showPrompt(`Enter API key for ${t.name}:`,"sk-...").then(async i=>{if(!i.trim()||this.settled){this.complete(!1);return}await g(t.id,{type:"api_key",key:i.trim()},f(w(),"auth.json")),this.complete(!0)}).catch(o);return}const n=t.id;if(C(n)){b(D(),n,s).then(()=>{this.settled||e.signal.aborted||this.complete(!0)}).catch(o);return}if(!this.runtime.getProvider(n)?.auth.oauth){this.complete(!1);return}this.runtime.login(n,"oauth",s).then(()=>this.complete(!0)).catch(i=>{if(i instanceof u){this.complete(!0);return}o()})}}async function B(){return await I(({tui:t,agentDir:e,runtime:s,registry:o},n)=>new A(t,s,e,L(s,o).map(({providerId:i,name:m,authType:c})=>({id:i,name:m,authType:c})),n.submit))===!0}r(B,"runFrontDoorLogin");export{B as runFrontDoorLogin};

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

@@ -0,0 +1,26 @@
+/** Parse `[dir] [prompt]` positionals + the front-door flags out of the leftover
+ *  tokens after the bare `crtr`. */
+export declare function parseRootArgs(tokens: string[]): {
+    cwd: string;
+    prompt?: string;
+    name?: string;
+    kind?: string;
+    profile?: string;
+    pickProfile?: boolean;
+    /** `-c`/`--continue` (resume MRU) or `-r`/`--resume` (resume via picker). */
+    resume?: 'continue' | 'pick';
+    /** `-r <node-id>`: reopen exactly this node. */
+    resumeId?: string;
+};
+export { FRONT_DOOR_ENV } from './front-door-env.js';
+/** If this invocation is a front-door (root) launch, boot it and never return.
+ *  Returns false when it's a recognized subcommand / help / unknown token (let
+ *  the dispatcher handle it — for unknown tokens it errors cleanly).
+ *
+ *  Takes NO command tree: it decides from argv plus the static `SUBTREE_NAMES`
+ *  list, so bare `crtr` never pays for assembling the full tree (measured 520ms
+ *  of the front door's ~1.6s — every subtree's module graph plus external
+ *  plugin/HTTP-transport plugin discovery, none of which a root boot reads). The one
+ *  case that genuinely needs external command names — a bare word that is also
+ *  an existing directory — builds the tree lazily, below. */
+export declare function maybeBootRoot(argv: string[]): Promise<boolean>;

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

@@ -0,0 +1,11 @@
+var D=Object.defineProperty;var w=(o,s)=>D(o,"name",{value:s,configurable:!0});import{existsSync as _,statSync as x}from"node:fs";import{resolve as T}from"node:path";import{SUBTREE_NAMES as C}from"../../build-root.js";import{FRONT_DOOR_ENV as E}from"./front-door-env.js";import{frontDoorBootPrompt as L}from"./first-run-offer.js";import{looksLikeNodeIdToken as b}from"./node-id-token.js";import{markTourOffered as A,recordSetupCompleted as W,setupCompleted as $,tourOfferPending as B}from"./setup-marker.js";function I(o){try{return _(o)&&x(o).isDirectory()}catch{return!1}}w(I,"isDir");const M=new Set(["--name","--kind","--profile","--pick-profile","--continue","-c","--resume","-r"]);async function G(){let o=!1;const s=w(()=>{o=!0},"onSigint");process.once("SIGINT",s);try{const{runSetup:r}=await import("../../commands/sys/setup-wizard.js"),e=await r();if(o){const l=new Error("Interrupted");throw l.name="AbortError",l}await W(e)}finally{process.removeListener("SIGINT",s)}}w(G,"runFirstSetup");function V(o){let s=process.cwd(),r,e,l,c=!1,p,u;const i=[];for(let f=0;f<o.length;f++){const n=o[f];if(n==="--name")r=o[++f];else if(n==="--kind")e=o[++f];else if(n==="--profile")l=o[++f];else if(n==="--pick-profile")c=!0;else if(n==="--continue"||n==="-c")p="continue";else if(n==="--resume"||n==="-r"){p="pick";const m=o[f+1];m!==void 0&&b(m)&&!I(T(m))&&(u=m,f++)}else n.startsWith("--")||i.push(n)}i.length>0&&I(T(i[0]))&&(s=T(i.shift()));const g=i.length>0?i.join(" "):void 0;return{cwd:s,prompt:g,name:r,kind:e,profile:l,pickProfile:c,resume:p,resumeId:u}}w(V,"parseRootArgs");import{FRONT_DOOR_ENV as re}from"./front-door-env.js";async function Q(o){const s=o.slice(2),r=s[0];if(process.env[E]||r==="-h"||r==="--help"||r==="--version"||r==="-v"||r!==void 0&&C.includes(r))return!1;if(r!==void 0){const t=/\s/.test(r),a=!r.startsWith("-")&&I(T(r)),d=M.has(r);if(!t&&!a&&!d)return!1;if(a){const{buildRoot:F}=await import("../../build-root.js");if((await F()).subtrees.some(N=>N.name===r))return!1}}const e=V(s),l=w(async()=>{if(e.profile===void 0)return;const{resolveProfileOperand:t}=await import("../profiles/manifest.js");e.profile=t(e.profile).profileId},"resolveProfileFlag");e.resumeId===void 0&&await l();const c=process.stdin.isTTY&&process.stdout.isTTY;let p=!1;c&&!$()&&(await G(),p=!0);let u=null,i,g=process.cwd();if(e.resumeId!==void 0){const{resolveResumeTarget:t,noResumeTargetMessage:a}=await import("./resume-root.js"),d=await t(e.resumeId);"error"in d&&(process.stderr.write(`${d.error}
+`),process.exit(1)),"none"in d?(e.resumeId.includes("-")&&(process.stderr.write(`${a(e.resumeId)}
+`),process.exit(1)),e.prompt=e.prompt===void 0?e.resumeId:`${e.resumeId} ${e.prompt}`,e.resumeId=void 0,await l()):(u=d.node.profile_id,i=d.node.node_id,I(d.node.cwd)&&(g=d.node.cwd))}if(i===void 0){const{selectProfileForCwd:t,selectProfileForCwdReadOnly:a}=await import("../profiles/select.js");p&&e.profile===void 0&&process.stdout.write(`
+Choose a profile
+`),u=e.profile??(c?await t(e.cwd,void 0,e.pickProfile):a(e.cwd))}const{exitForMissingProviderCredential:f,hasConfiguredProviderCredential:n}=await import("./provider-credential-gate.js");if(!await n(u)){c||f();const{runFrontDoorLogin:t}=await import("./front-door-login.js");await t()||f()}const{inTmux:m}=await import("./placement-tmux.js");if(c&&!m()){const{TMUX_STARTED_ENV:t,handoffToTmux:a}=await import("./tmux-handoff.js");process.env[t]===void 0&&a(s,i!==void 0?null:u,g)}const[{bootRoot:R},{resumeRoot:k},{rendererWarning:P,missingPackageWarning:v,piAgentDir:y}]=await Promise.all([import("./boot-root.js"),import("./resume-root.js"),import("./package-health.js")]);try{const t=v(y());t!==null&&process.stderr.write(`
+${t}
+
+`);const a=P();a!==null&&process.stderr.write(`
+${a}
+
+`)}catch{}if(i!==void 0){const{resumeNodeById:t}=await import("./resume-root.js");await t(i)}if(e.resume!==void 0&&await k(e.cwd,e.resume==="pick")==="aborted")return!0;const h=c&&(p||await B()),{prompt:O,initialWhip:S}=L({offerTour:h,userPrompt:e.prompt});return h&&m()&&await A(),await R({...e,prompt:O,initialWhip:S,selectedProfileId:u??void 0}),!0}w(Q,"maybeBootRoot");export{re as FRONT_DOOR_ENV,Q as maybeBootRoot,V as parseRootArgs};

package/dist/core/runtime/headless-pi.d.ts

@@ -0,0 +1,37 @@
+import { type ConstrainedSamplingConfig } from '@earendil-works/pi-ai';
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import type { TSchema } from 'typebox';
+export interface HeadlessTool {
+    name: string;
+    label: string;
+    description: string;
+    parameters: TSchema;
+    constrainedSampling?: false | ConstrainedSamplingConfig;
+}
+export interface HeadlessRequest {
+    systemPrompt: string;
+    userPrompt: string;
+    modelSpec: string;
+    /** Logical `family/strength` intent. Omit for a concrete model request. */
+    modelIntent?: string;
+    timeoutMs: number;
+    tool?: HeadlessTool;
+    /** Exact context to seed into an isolated in-memory session. */
+    seedMessages?: readonly AgentMessage[];
+    /** Reuses a provider cache identity without binding or persisting a session. */
+    sessionId?: string;
+    /** Omit `noTools` to load Pi's builtin tool suite. */
+    toolPolicy?: 'builtin';
+}
+/** Run a one-shot call whose only output channel is one structured tool call. */
+export declare function headlessToolCall(request: HeadlessRequest & {
+    tool: HeadlessTool;
+}): Promise<unknown>;
+/** Run a one-shot call and return the final assistant text. */
+export declare function headlessText(request: HeadlessRequest): Promise<string>;
+/** Run a tool-capable, extension-free in-memory turn against seeded context. */
+export declare function headlessTurn(request: HeadlessRequest & {
+    seedMessages: readonly AgentMessage[];
+    sessionId: string;
+    toolPolicy: 'builtin';
+}): Promise<'completed' | 'failed'>;

package/dist/core/runtime/headless-pi.js

@@ -0,0 +1 @@
+var j=Object.defineProperty;var a=(e,t)=>j(e,"name",{value:t,configurable:!0});import{envNodeCwd as F,envProfileId as D}from"../../shared/env.js";import{join as h}from"node:path";import{InMemoryCredentialStore as E}from"@earendil-works/pi-ai";import{PoolCredentialStore as L}from"../pool-credential-store.js";import{secretsDir as N}from"../layout.js";import{expandModelCandidates as O,modelRequestFromConfig as _,selectInitialModelRoute as B}from"../model-routes.js";import{configureBrokerModelRuntime as H}from"./broker/model-adapter.js";import{currentNodeToken as z}from"./broker/node-token.js";function G(e){for(let t=e.length-1;t>=0;t--){const i=e[t];if(i?.role!=="assistant")continue;if(typeof i.content=="string")return i.content.trim();if(!Array.isArray(i.content))continue;const r=i.content.map(l=>{const o=l;return o.type==="text"&&typeof o.text=="string"?o.text:""}).join("").trim();if(r!=="")return r}return""}a(G,"lastAssistantText");async function p(e,t,i){let r,l=!1,o=!1,g;const y=a(n=>{r===void 0||l||(l=!0,n&&r.abort().catch(()=>{}),r.dispose())},"disposeSession"),v=new Promise(n=>{g=setTimeout(()=>{o=!0,y(!0),n(t)},e.timeoutMs)}),R=(async()=>{try{const n=await import("@earendil-works/pi-coding-agent"),c=z()!==void 0;if(o)return t;const m=F()??process.cwd(),u=D(),x=n.getAgentDir(),w=await n.ModelRuntime.create({credentials:c?new E:new L(h(N(),"auth.json")),modelsPath:h(x,"models.json")});if(c&&H(w),o)return t;const M=await n.createAgentSessionServices({cwd:m,agentDir:x,modelRuntime:w,settingsManager:n.SettingsManager.inMemory(),resourceLoaderOptions:{noExtensions:!0,noContextFiles:!0,noSkills:!0,noPromptTemplates:!0,noThemes:!0,systemPrompt:e.systemPrompt,...c?{}:{extensionFactories:[(await import("../../builtin-pi-packages/pi-crtr-extensions/extensions/provider-rotation.js")).createProviderRotationExtension({modelIntent:e.modelIntent,nodeCwd:m,profileId:u})]}}});if(o)return t;const f=_(e.modelSpec,e.modelIntent,!1);if(f===void 0)return t;const S=new n.ModelRegistry(M.modelRuntime),T=c?O(f,m,u).map(d=>S.find(d.providerId,d.modelId)).find(d=>d!==void 0):B(f,S,{cwd:m,profileId:u}).selected?.model;if(T===void 0)return t;let I;const s=e.tool,C=s===void 0?void 0:n.defineTool({name:s.name,label:s.label,description:s.description,parameters:s.parameters,...s.constrainedSampling===void 0?{}:{constrainedSampling:s.constrainedSampling},async execute(d,A){return I=A,{content:[{type:"text",text:"Recorded."}],details:{recorded:!0},terminate:!0}}}),P=n.SessionManager.inMemory(m,e.sessionId===void 0?void 0:{id:e.sessionId});for(const d of e.seedMessages??[])P.appendMessage(d);return{session:r}=await n.createAgentSessionFromServices({services:M,sessionManager:P,model:T,thinkingLevel:"off",...s===void 0?e.toolPolicy==="builtin"?{}:{noTools:"all"}:{tools:[s.name],customTools:[C]}}),o||(await r.bindExtensions({}),o)?t:(await r.prompt(e.userPrompt),o?t:i(r,I))}catch{return t}finally{y(!1)}})();try{return await Promise.race([R,v])}finally{clearTimeout(g)}}a(p,"runHeadless");function $(e){return p(e,null,(t,i)=>i)}a($,"headlessToolCall");function b(e){return p(e,"",t=>G(t.messages))}a(b,"headlessText");function k(e){return p(e,"failed",()=>"completed")}a(k,"headlessTurn");export{b as headlessText,$ as headlessToolCall,k as headlessTurn};

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

@@ -0,0 +1,59 @@
+import { type NodeRow } from '../canvas/index.js';
+import type { PiInvocation } from './invocation.js';
+/** View-side launch hints the broker host needs beyond the PiInvocation. The
+ *  broker uses `cwd` + `resuming`; `name` is carried for the node's display. */
+export interface LaunchPlacement {
+    cwd: string;
+    name: string;
+    resuming: boolean;
+}
+/** A handle to a node's running engine container. The broker host supervises via
+ *  the broker pid recorded as pi_pid; no tmux placement coords exist (the engine
+ *  is never in a pane). */
+export interface HostHandle {
+    /** Supervised pid (signal-0 target). Null means the host failed to spawn an
+     *  engine at all. Spawn/revive record this pid immediately; the broker
+     *  re-records the same pid during extension bind. */
+    pid: number | null;
+    /** Real child-exit signal from the launch handle. Resolves when the detached
+     *  broker exits, so readiness waits can fail fast without pid probes. */
+    exited: Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+}
+export interface TeardownOptions {
+    excludePid?: number;
+}
+/** The only completion signal a caller may use for post-teardown work. A false
+ * result means the original engine tree could not be confirmed dead, so no
+ * cleanup may claim it was safe to remove resources it owned. */
+export interface TeardownResult {
+    confirmed: boolean;
+    error?: Error;
+}
+export interface Host {
+    /** Bring a node's ENGINE into existence from its launch recipe; return a
+     *  supervisable handle. */
+    launch(nodeId: string, inv: PiInvocation, opts: LaunchPlacement): HostHandle | Promise<HostHandle>;
+    /** Is this node's engine alive? PURE / non-mutating. `string | NodeRow` so
+     *  both call sites — the revive guard (passes the id) and the daemon (passes a
+     *  row) — share one selector. For the broker this IS isPidAlive(pi_pid). */
+    isAlive(node: string | NodeRow): boolean;
+    /** Tear the engine down (close/cancel teardown). Resolves only after the
+     * fixed process snapshot is confirmed dead, or with a diagnostic failure. */
+    teardown(nodeId: string, opts?: TeardownOptions): Promise<TeardownResult>;
+    /** Deliver an OS signal to the engine container — present so the daemon never
+     *  reaches around the abstraction. */
+    signal(nodeId: string, sig: NodeJS.Signals): void;
+}
+/** Validate the broker launch recipe before we detach a child process. This is
+ *  the fast-fail seam for known module/path errors: a bad engine resolve or a
+ *  missing plain session path throws here, before spawn(). */
+export declare function preflightBrokerLaunch(nodeId: string, inv: PiInvocation, cwd: string): void;
+/** Queue broker teardown after the close response settles. Completion includes
+ * any post-teardown work, which lets the daemon drain it during shutdown. */
+export declare function requestBrokerTeardown(nodeId: string, opts?: TeardownOptions, after?: () => Promise<void>): Promise<TeardownResult>;
+/** Isolated brokers require the Linux launcher; direct host spawn cannot enforce their filesystem or network policy. */
+export declare function isolatedBrokerLauncherAvailable(): boolean;
+export declare const headlessBrokerHost: Host;

package/dist/core/runtime/host.js

@@ -0,0 +1,3 @@
+var _e=Object.defineProperty;var u=(e,n)=>_e(e,"name",{value:n,configurable:!0});import{spawn as be}from"node:child_process";import{mkdirSync as ce,existsSync as $,unlinkSync as ae,openSync as j,closeSync as T,writeSync as Se,chmodSync as ye,lstatSync as Pe}from"node:fs";import{ensureAppSpace as Re}from"../spaces/space.js";import{sandboxCacheEnv as xe}from"../spaces/cache-env.js";import{compileLaunch as Oe,launchStillGranted as Te}from"../spaces/mounts.js";import{grantsGeneration as le}from"../grants/mirror.js";import{LAUNCHER_SOCKET as U}from"../../launcher/spec.js";import{launcherRequest as F}from"../../launcher/client.js";import{piAgentDir as De}from"./package-health.js";import{existsBeneath as Ne,readFileBeneath as Ae,readTextBeneathIfExists as Ce,setModeBeneath as P,withDirBeneath as W,writeFileBeneath as z}from"../spaces/open-beneath.js";import{dirname as V,join as w,resolve as Le,isAbsolute as Be}from"node:path";import{fileURLToPath as ue}from"node:url";import{connectViewSocket as $e}from"./view-socket.js";import{appSpace as G}from"../layout.js";import{readConfig as je,readMergedLaunchConfig as Fe}from"../config.js";import{readRotationConfig as Ge}from"../subscription-state.js";import{getNode as b}from"../canvas/index.js";import{crtrHome as fe,nodeRunDir as X,nodeRunJobDir as Ke,jobDir as Me,viewSocketPath as He,nodeAgentDir as Je,contextDir as qe,nodeHome as Ue}from"../canvas/paths.js";import{encodeFrame as We}from"./broker-protocol.js";import{buildBrokerEnv as ze}from"./spawn-env.js";import{hostExecPathFresh as Ve}from"./branded-host.js";import{isPidAlive as Q,killProcessTreePids as de,isAnyPidAlive as Xe,captureTeardownSnapshot as Qe}from"../canvas/pid.js";import{assertMandatoryCanvasExtensions as Ye}from"./canvas-extensions.js";import{boundFleet as Ze,brokerCapReached as Ie,brokerThresholdsForDaemon as er}from"./fleet.js";import{emitEvent as g}from"../events/emit.js";import{bindBrokerEventSource as rr,eventSource as nr}from"../events/source.js";import{envBrokerEngine as tr}from"../../shared/env.js";import{conversationIdFromPath as or,conversationStore as ir,ConversationNotFoundError as me,storeAddress as sr}from"../conversation-store/index.js";import{takeNodeToken as cr}from"../canvas/node-tokens.js";function K(){const e=V(ue(import.meta.url));return w(e,"broker-cli.js")}u(K,"resolveBrokerEntry");const ar="@earendil-works/pi-coding-agent";function lr(e,n){const t=w(De(),"models.json"),r=w(n,"models.json"),o=Ce(V(t),t);if(o===null)return;const f=JSON.parse(o),c=u(i=>Array.isArray(i)?i.map(c):i===null||typeof i!="object"?i:Object.fromEntries(Object.entries(i).filter(([s])=>!/^(apiKey|authorization|headers|token|secret)$/i.test(s)).map(([s,E])=>[s,c(E)])),"scrub"),l=`${JSON.stringify(c(f),null,2)}
+`;if(t===r&&o!==l){if(JSON.stringify(f)!==JSON.stringify(c(f)))throw new Error("terminal models.json contains credentials; move them into daemon secrets");P(e,r,432);return}z(e,r,l,{atomic:!0,mode:432}),P(e,r,432)}u(lr,"writeBrokerModels");function pe(e){return e.env.CRTR_BROKER_ENGINE??tr()}u(pe,"resolveEngineSpec");function he(e){return e.includes("/")||e.endsWith(".jsonl")}u(he,"isPlainLaunchSessionPath");function ur(e,n){return Be(e)?e:Le(n,e)}u(ur,"resolvePlainLaunchPath");function fr(e,n,t,r){if(t==="--session"&&!he(r))throw new Error(`[broker] refusing to launch ${e}: launch recipe passes bare --session id '${r}' \u2014 the broker fatally rejects bare ids; pass the .jsonl path instead.`);if(!he(r))return;const o=ur(r,n),f=or(o);try{if(f===null)throw new me(o);ir().header(f)}catch(c){if(!(c instanceof me))throw c;const l=t==="--session"?"session file":"fork source";throw new Error(`[broker] refusing to launch ${e}: launch recipe references missing ${l} '${r}' (${o})`)}}u(fr,"preflightLaunchSessionArg");function dr(e,n,t){const r=X(e);ce(r,{recursive:!0}),process.platform==="linux"&&$(U)&&Pe(r).uid===process.getuid()&&ye(r,504);const o=w(r,"broker-launch.json"),f={user:je("user"),launch:Fe(t,n.env.CRTR_PROFILE_ID||null),rotation:Ge()};z(r,o,JSON.stringify({...n,configSnapshot:f}),{atomic:!0});const c=Ae(r,o).toString("utf8"),l=JSON.parse(c);if(!Array.isArray(l.argv))throw new Error(`[broker] refusing to launch ${e}: broker-launch.json is missing the argv array`);const i=pe(n);try{const d=import.meta.resolve(i);if(d.startsWith("file:")&&!$(ue(d)))throw new Error(`resolved to missing file ${d}`)}catch(d){throw new Error(`[broker] refusing to launch ${e}: cannot resolve broker engine '${i}' from ${K()} \u2014 ${d.message}`)}const s=l.argv,E=[];for(let d=0;d<s.length;d++){const S=s[d];if(S==="-e"){const D=s[++d];D!==void 0&&E.push(D);continue}if(S!=="--session"&&S!=="--fork")continue;const R=s[++d];R!==void 0&&fr(e,t,S,R)}try{Ye(E)}catch(d){throw new Error(`[broker] refusing to launch ${e}: ${d.message}`)}}u(dr,"preflightBrokerLaunch");const mr=2e3,pr=2e3,hr=150;async function M(e,n){const t=Date.now()+n;for(;Xe(e);){const r=t-Date.now();if(r<=0)return!1;await new Promise(o=>setTimeout(o,Math.min(hr,r)))}return!0}u(M,"waitForTreeExit");async function wr(e,n,t){return e.length===0?{confirmed:!0}:t&&await M(e,mr)?{confirmed:!0}:(de(e,"SIGTERM",n),await M(e,pr)?{confirmed:!0}:(de(e,"SIGKILL",n),await M(e,5e3)?{confirmed:!0}:{confirmed:!1,error:new Error(`broker process tree for ${e.join(", ")} remained alive after SIGKILL`)}))}u(wr,"terminateBrokerTree");function we(e,n){const t=b(e),r=t?.pi_pid,o=r!=null?Qe(r,t?.pi_pid_identity??null,n.excludePid):null;return o?.reused===!0&&g({level:"warn",event:"broker.teardown.pid_reuse_refused",node_id:e,fields:{recorded_pid:r,expected_identity:t?.pi_pid_identity??null}}),{tree:o?.tree??[],identities:o?.identities??null,nodeId:e,launcherPid:$(U)&&o?.tree.includes(r)?r:null}}u(we,"prepareBrokerTeardown");async function ge(e){if(e.launcherPid!==null){try{await F({operation:"stop",pid:e.launcherPid})}catch(n){return Q(e.launcherPid)?{confirmed:!1,error:n instanceof Error?n:new Error(String(n))}:{confirmed:!0}}return await M([e.launcherPid],5e3)?{confirmed:!0}:{confirmed:!1,error:new Error(`launcher pid ${e.launcherPid} remained alive`)}}return new Promise(n=>{let t=!1,r=!1;const o=u(i=>{r||(r=!0,n(i))},"settle"),f=u(()=>{try{ae(He(e.nodeId))}catch{}},"cleanupSocket"),c=u(i=>{wr(e.tree,e.identities,i).then(o,s=>o({confirmed:!1,error:s instanceof Error?s:new Error(String(s))}))},"finish"),l=$e(e.nodeId);l.once("error",()=>{t||(f(),c(!1))}),l.once("connect",()=>{t=!0;try{l.write(We({type:"shutdown"}))}catch{}l.end(),f(),c(!0)})})}u(ge,"runPreparedBrokerTeardown");const H=new Map;function zr(e,n={},t){const r=H.get(e);if(r!==void 0)return t!==void 0&&r.after.push(t),r.completion;let o;const f=new Promise(i=>{o=i}),c={completion:f,resolve:o,after:t===void 0?[]:[t]};H.set(e,c);let l;try{l=we(e,n)}catch(i){const s={confirmed:!1,error:i instanceof Error?i:new Error(String(i))};return H.delete(e),g({level:"error",event:"broker.teardown.unconfirmed",node_id:e,error:s.error}),c.resolve(s),f}return setImmediate(()=>{H.delete(e),ge(l).then(async i=>{if(i.confirmed)for(const s of c.after)try{await s()}catch(E){g({level:"error",event:"broker.teardown.after_failed",node_id:e,error:E})}else g({level:"error",event:"broker.teardown.unconfirmed",node_id:e,error:i.error});c.resolve(i)},i=>{const s={confirmed:!1,error:i instanceof Error?i:new Error(String(i))};g({level:"error",event:"broker.teardown.unconfirmed",node_id:e,error:s.error}),c.resolve(s)})}),f}u(zr,"requestBrokerTeardown");function Ee(){return process.platform==="linux"&&$(U)}u(Ee,"isolatedBrokerLauncherAvailable");const Vr={async launch(e,n,t){if(b(e)?.isolated===!0&&!Ee())throw new Error("isolated broker requires the Linux root launcher");dr(e,n,t.cwd);const r=Ze();if(!r.reserveSlot(e))throw Ie(er().automaticReviveCap,r.size());let o=null,f,c=!1;try{const l=Me(e);ce(l,{recursive:!0}),o=j(w(l,"broker.log"),"a");const i=pe(n),s={...ze(n),CRTR_BROKER_ENGINE:i,CRTR_STORE_ADDRESS:sr()};if(i!==ar){const a=n.env.NODE_OPTIONS??process.env.NODE_OPTIONS;a!==void 0&&(s.NODE_OPTIONS=a)}nr()===void 0&&rr(e);const E=b(e)?.run_id;if(E){const a=b(E);if(!a||a.deleting_at)throw new Error("run is deleting")}const d=n.env.CRTR_EXECUTION_ID;if(!d)throw new Error("broker launch has no execution id");const S=cr(d),R=Ee();if(b(e)?.isolated===!0&&!R)throw new Error("isolated broker requires the Linux root launcher");if(process.platform==="linux"&&process.env.CRTR_LAUNCHER_SOCKET&&!R)throw new Error("root launcher socket is unavailable; refusing an unsandboxed broker");if(R){const a=b(e);if(!a)throw new Error(`missing node ${e}`);const m=a.grantee??"app:terminal",A=await Re(m);Object.assign(s,xe(m));const p={uid:process.getuid(),gid:A.gid},k=X(e);for(const[h,y]of[[G(m).nodes,Je(e,m)],[G(m).nodes,qe(e,m)],[k,Ke(e)]])W(h,y,()=>{},!0),P(h,y,1528,p);P(k,w(k,"broker-launch.json"),416,p);const I=w(k,"system-prompt.md");Ne(k,I)&&P(k,I,432,p);const ee=a.isolated===!0,v=Ue(e,m,ee);ee&&(W(G(m).nodes,v,()=>{},!0),P(G(m).nodes,v,1528,p),s.HOME=v,s.PI_CODING_AGENT_DIR=w(v,".pi","agent"));const q=w(v,".pi","agent");W(v,q,()=>{},!0),lr(v,q);const re=w(q,"settings.json"),ke=w(V(K()),"../../builtin-pi-packages/pi-crtr-extensions");z(v,re,`${JSON.stringify({packages:[ke]})}
+`,{atomic:!0,mode:432}),P(v,re,432);const ne=w(X(e),`token-${d}`),C=j(ne,"wx+",384);ae(ne),Se(C,S);const te=[j(`/proc/self/fd/${C}`,"r"),j(`/proc/self/fd/${C}`,"r")];T(C);const oe={nodeId:e,app:m,sub:a.sub??"user:local",grantId:a.grant_id??null,scopes:a.scopes??null,isolated:a.isolated===!0,...a.isolated===!0?{cwd:a.cwd}:{},command:[process.execPath,K(),"--canvas-home",fe(),"--epoch",r.epoch(),e],env:Object.fromEntries(Object.entries({...s,...a.isolated===!0?{PWD:a.cwd}:{}}).filter(h=>h[1]!==void 0)),auditMissing:u(h=>g({level:"warn",event:"broker.mount.missing",node_id:e,fields:{source:h}}),"auditMissing")};try{let h;for(const O of te){const L=le(),_=Oe(oe),B=await F({operation:"launch",spec:_},[O]);if(!("pid"in B))throw new Error("launcher did not return a pid");if(le()===L||Te(oe,_)){h=B.pid;break}g({level:"info",event:"broker.launch.regranted",node_id:e,fields:{pid:B.pid}}),await F({operation:"stop",pid:B.pid,signal:"SIGKILL"}).catch(()=>{})}if(h===void 0)throw new Error("grant changed during every launch attempt");const y=h,ve=Date.now(),ie=new Promise(O=>{const L=setInterval(()=>{Q(y)||(clearInterval(L),F({operation:"exit.status",pid:y}).then(_=>"oomKilled"in _&&_.oomKilled,()=>!1).then(_=>{g({level:_?"warn":"info",event:"broker.exited",node_id:e,fields:{pid:y,uptime_ms:Date.now()-ve,oom_killed:_}}),O({code:null,signal:null,..._?{oomKilled:!0}:{}})}))},250);L.unref()});T(o),o=null;const se={pid:y,exited:ie};return r.register(e,se),c=!0,ie.then(O=>r.onChildExit(e,O,d)),se}finally{for(const h of te)T(h)}}const D=await Ve(),x=be(D,[K(),"--canvas-home",fe(),"--epoch",r.epoch(),e],{cwd:t.cwd,detached:!0,stdio:["ignore",o,o,"pipe"],env:s});f=x;const N=x.stdio[3];if(!N||!("end"in N))throw new Error("broker token pipe did not open");N.on("error",a=>g({event:"broker.token_pipe.failed",level:"error",node_id:e,error:a})),N.end(S),T(o),o=null;const Y=Date.now(),Z=new Promise(a=>{let m=!1;const A=u(p=>{m||(m=!0,a(p))},"finish");x.once("exit",(p,k)=>{g({level:p===0?"info":"warn",event:"broker.exited",node_id:e,fields:{code:p,signal:k,uptime_ms:Date.now()-Y}}),A({code:p,signal:k})}),x.once("error",p=>{g({level:"error",event:"broker.launch.failed",node_id:e,error:p,fields:{uptime_ms:Date.now()-Y}}),A({code:null,signal:null})})});x.unref();const J={pid:x.pid??null,exited:Z};return J.pid!==null&&(r.register(e,J),c=!0,Z.then(a=>r.onChildExit(e,a,d))),J}catch(l){if(!c&&f?.pid!=null)try{f.kill("SIGTERM")}catch{}throw l}finally{c||r.releaseReservation(e),o!==null&&T(o)}},isAlive(e){return Q((typeof e=="string"?b(e):e)?.pi_pid)},teardown(e,n={}){try{return ge(we(e,n))}catch(t){return Promise.resolve({confirmed:!1,error:t instanceof Error?t:new Error(String(t))})}},signal(e,n){const t=b(e)?.pi_pid;if(t!=null)try{process.kill(t,n)}catch{}}};export{Vr as headlessBrokerHost,Ee as isolatedBrokerLauncherAvailable,dr as preflightBrokerLaunch,zr as requestBrokerTeardown};

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 @@
+var u=Object.defineProperty;var e=(t,r)=>u(t,"name",{value:r,configurable:!0});import{oneShotControllerRequest as a}from"./broker-request.js";function l(t,r,i={}){const o=i.cards??[];return a({nodeId:t,what:"the interactive delivery",ackFor:"deliver",correlated:!0,frame:e(n=>({type:"deliver",id:n,text:r,...o.length>0?{cards:[...o]}:{},...i.origin!==void 0?{origin:i.origin}:{}}),"frame"),result:e(n=>n==="steer"?"steer":"prompt","result")})}e(l,"deliverLive");function s(t){return a({nodeId:t,what:"the interrupt",ackFor:"abort",correlated:!0,frame:e(r=>({type:"abort",id:r}),"frame"),result:e(r=>r==="turn"||r==="bash"?r:"idle","result")})}e(s,"interruptLive");export{l as deliverLive,s as interruptLive};

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

@@ -0,0 +1,9 @@
+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>;
+}

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

@@ -0,0 +1,49 @@
+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 goal file — the prompt/task a node was spawned with, persisted at birth
+ *  so a fresh revive can re-read its mandate. */
+export declare function goalPath(nodeId: string): string;
+export declare function readGoal(nodeId: string): string | null;
+/** Persist the spawning prompt as the node's goal. No-op for an empty prompt
+ *  (e.g. a bare root). Idempotent enough — call once at spawn/boot. */
+export declare function writeGoal(nodeId: string, text: string): void;
+/** Write the goal ONLY if the node has none yet. This is how a bare root (no
+ *  spawn prompt) acquires its mandate: the first real user message becomes the
+ *  goal. Returns true when it wrote one, false when a goal already existed or
+ *  the text was empty. Guarded so a later message never clobbers the mandate. */
+export declare function captureGoalIfAbsent(nodeId: string, text: string): boolean;
+/** The yield-message file — a short note `crtr node yield` records for the next
+ *  fresh/cycling revive ("on wake, do X"). It remains durable through failed
+ *  launch attempts and is cleared only when session_start confirms a boot. */
+export declare function yieldMessagePath(nodeId: string): string;
+export declare function writeYieldMessage(nodeId: string, text: string): void;
+/** Read the pending yield message without mutating its confirmation state. */
+export declare function readYieldMessage(nodeId: string): string | null;
+/** Idempotently commit delivery of the yield message after a confirmed boot. */
+export declare function clearYieldMessage(nodeId: string): void;
+/** List the node's context/ dir (filenames, sorted). Empty when absent. */
+export declare function listContextDir(nodeId: string): 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): 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): 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): string;

package/dist/core/runtime/kickoff.js

@@ -0,0 +1,28 @@
+var B=Object.defineProperty;var i=(t,e)=>B(t,"name",{value:e,configurable:!0});import{join as w}from"node:path";import{getNode as M,subscriptionsOf as R,subscribersOf as N}from"../canvas/index.js";import{contextDir as h,nodeAgentDir as l}from"../canvas/node-agent-paths.js";import{hasReportDocuments as A}from"../feed/reports.js";import{readdirBeneath as E,readTextBeneathIfExists as x,unlinkBeneath as T,writeFileBeneath as $}from"../spaces/open-beneath.js";import{activeBackgroundBashJobs as D,bashJobCommandLine as I,formatBashElapsed as G}from"../bash-jobs.js";import{readRoadmap as O}from"./roadmap.js";import{buildWakeBearings as _}from"./bearings.js";import{personaDrift as Y}from"./persona.js";import{coalesce as C,nodeMailEntry as L}from"../feed/inbox.js";import{claimKickoffMail as U}from"../canvas/deliveries.js";import{formatCard as k}from"../../shared/generated-context.js";const ut=k("restart-continuation",{},"continue");function y(t){return w(h(t),"initial-prompt.md")}i(y,"goalPath");function j(t){return x(l(t),y(t))}i(j,"readGoal");function J(t,e){const n=e.trim();n!==""&&$(l(t),y(t),n+`
+`)}i(J,"writeGoal");function dt(t,e){const n=j(t);if(n!==null&&n.trim()!=="")return!1;const r=e.trim();return r===""?!1:(J(t,r),!0)}i(dt,"captureGoalIfAbsent");function b(t){return w(h(t),"yield-message.md")}i(b,"yieldMessagePath");function ct(t,e){const n=e.trim();n!==""&&$(l(t),b(t),n+`
+`)}i(ct,"writeYieldMessage");function P(t){const e=x(l(t),b(t))?.trim()??"";return e!==""?e:null}i(P,"readYieldMessage");function lt(t){try{T(l(t),b(t))}catch{}}i(lt,"clearYieldMessage");function F(t){return S(t,h(t)).sort()}i(F,"listContextDir");function K(t){return A(t)}i(K,"hasRetainedReports");function S(t,e){try{return E(l(t),e).map(n=>n.name)}catch(n){if(n.code==="ENOENT")return[];throw n}}i(S,"agentDirNames");function ft(t,e){const n=t.node_id,r=P(n),o=t.run_id?[]:U(n,e),s=o.map(a=>a.message.messageId),f=o.map(L);let u=null;if(f.length>0){const a=i(d=>{const m=d.data?.cards;return Array.isArray(m)?m.filter(v=>typeof v=="string"):[]},"cardsFor"),p=[];for(const d of f)(a(d).length>0||p.length===0)&&p.push([]),p.at(-1).push(d);u=p.map(d=>[...a(d[0]),C(d).map(m=>m.text).join(`
+
+`)].join(`
+
+`)).join(`
+
+`)}const c=Y(n),g=c?.guidance===void 0||c.guidance===""?null:c.guidance;return{yieldMsg:r,unreadDigest:u,unreadMessageIds:s,driftGuidance:g}}i(ft,"drainBearings");function q(t,e){const n=R(t).filter(o=>o.active).map(o=>M(o.node_id)).filter(o=>o!==null&&(o.status==="active"||o.status==="idle")),r=[];if(n.length>0){const o=n.length,s=o===1?"it has":"they have",f=o===1?"Its":"Their";r.push(`Awaiting ${o} node${o===1?"":"s"} \u2014 ${s} not finished. ${f} reports will wake you.`);for(const u of n)r.push(`  - ${u.name} (${u.node_id}) \u2014 ${u.status}`);r.push("",e??"(no unread reports)")}else r.push("Awaiting 0 nodes."),r.push("",e??"(no unread reports)");return`<feed>
+${r.join(`
+`)}
+</feed>`}i(q,"feedBlock");function W(t,e){const n=(t??I(e)).trim()||"(no command)";return n.length>120?`${n.slice(0,117)}\u2026`:n}i(W,"jobLabel");function z(t){const e=D(h(t));if(e.length===0)return null;const n=Date.now(),r=e.length===1,o=[`${e.length} background bash job${r?"":"s"} you started ${r?"is":"are"} STILL RUNNING, detached from any turn and unaffected by your refresh. Each one sends you a message when it exits \u2014 that wake is automatic, so do not poll it and do not relaunch the same command.`];for(const s of e)o.push(`  - ${s.jobId} \u2014 ${W(s.purpose,s.command)} \xB7 running ${G(n-s.startedAtMs)} \xB7 log ${s.logPath}`);return o.push("","Read output so far: `tail -n 50 <log>` (or `crtr node bash list --tail 20`). Abandon one: `crtr node bash kill <job-id>`."),`<background-jobs>
+${o.join(`
+`)}
+</background-jobs>`}i(z,"backgroundJobsBlock");function ht(t,e,n){const r=t.node_id,o=["You have been revived fresh after a context refresh \u2014 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."];n!==void 0&&o.push(_(n));const s=O(r);if(!(s!==null&&s.trim()!=="")&&!K(r)){const a=j(r);a!==null&&a.trim()!==""&&o.push(`<goal file="${y(r)}">
+${a.trim()}
+</goal>`)}const u=F(r).filter(a=>a!=="yield-message.md");o.push(`<context-dir path="${h(r)}">
+${u.length>0?u.join(`
+`):"(empty)"}
+</context-dir>`);const c=z(r);c!==null&&o.push(c),o.push(q(r,e.unreadDigest)),o.push(e.yieldMsg!==null?`<yield-message>
+${e.yieldMsg.trim()}
+</yield-message>`:"<yield-message/>");const g=N(r).length>0;return o.push(g?"If there is work to do, perform it. Otherwise stop \u2014 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 \u2014 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."),e.driftGuidance!==null&&o.push(`<persona-transition>
+Your role was changed while you were away. ${e.driftGuidance}
+</persona-transition>`),k("revive",{},`
+${o.join(`
+
+`)}
+`)}i(ht,"buildReviveKickoff");export{ut as RUNTIME_RESTART_CONTINUATION,ht as buildReviveKickoff,dt as captureGoalIfAbsent,lt as clearYieldMessage,ft as drainBearings,y as goalPath,K as hasRetainedReports,F as listContextDir,j as readGoal,P as readYieldMessage,J as writeGoal,ct as writeYieldMessage,b as yieldMessagePath};

package/dist/core/runtime/launch-config-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/runtime/launch-config-worker.js

@@ -0,0 +1 @@
+import{readMergedLaunchConfig as o}from"../config.js";process.once("message",e=>{try{process.send?.({config:o(e.cwd,e.profileId)})}catch(r){process.send?.({error:r instanceof Error?r.message:String(r)})}});

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,4 @@
+const n=`You are a node in the crtr canvas \u2014 an agentic runtime.
+
+Guidelines:
+- Use the crtr canvas (its documents, nodes and other objects) according to injected context.`;export{n as LAUNCH_SYSTEM_PROMPT};

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

@@ -0,0 +1,34 @@
+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 = "developer";
+/** 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;
+/** 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): string;

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

@@ -0,0 +1 @@
+var u=Object.defineProperty;var i=(e,n)=>u(e,"name",{value:n,configurable:!0});import{appSpace as p}from"../layout.js";import{envProfileId as m}from"../../shared/env.js";import{resolve as s}from"node:path";import{getNode as w}from"../canvas/canvas.js";import{usage as v}from"../errors.js";import{assertProfileActive as h}from"../profiles/manifest.js";import{buildLaunchSpecAsync as _,readMergedLaunchConfigAsync as x}from"./launch.js";import{resolveProfileId as y}from"./spawn.js";function k(e,n){return e??n?.manifest.default_kind??"general"}i(k,"resolveCreateKind");const K="developer";function j(e){return e.manifest.default_kind??K}i(j,"resolveRunKind");const N=new Set(["human"]);function M(e){return!N.has(e)}i(M,"isLaunchKind");async function g(e,n=process.cwd(),r=m()||null){const t=Object.keys((await x(n,r)).kinds);if(!t.includes(e))throw v(`unknown kind: ${e}`,{received:e,next:`Valid kinds: ${t.sort().join(", ")}.`})}i(g,"assertLaunchKind");async function R(e,n={}){const r=e.parent??void 0,t=e.cwd??process.cwd(),o=await y(e.profile,r??null,t,{readOnlySelection:n.readOnlyProfileSelection}),a=h(o),d=k(e.kind,a);await n.validateKind?.(d);const c=L({...e,kind:d},r,o,t);n.validateKind===void 0&&await g(d,c,o);const l=e.mode??"base",f=(await _(d,l,{lifecycle:e.root_lifecycle??(e.root===!0?"resident":"terminal"),hasManager:e.root!==!0,...e.model!==void 0?{model:e.model,modelOverride:!0}:{},cwd:c,profileId:o})).launch;return{profileId:o,profile:a,kind:d,mode:l,cwd:c,launch:f}}i(R,"resolveLaunchTarget");function L(e,n,r,t){if(e.pin_cwd!==void 0&&e.pin_cwd!=="")return s(e.pin_cwd);if(n!=null){const o=w(n);if(o!==null)return o.cwd}return e.cwd!==void 0&&e.cwd!==""?s(e.cwd):process.platform==="linux"?p("terminal").files:t}i(L,"resolveNodeCwd");export{K as RUN_DEFAULT_KIND,g as assertLaunchKind,M as isLaunchKind,k as resolveCreateKind,R as resolveLaunchTarget,L as resolveNodeCwd,j as resolveRunKind};