@north-light/cli 0.0.0 → 0.3.414

package/dist/core/runtime/node-read.d.ts

@@ -0,0 +1,51 @@
+import type { BrokerSnapshot } from './broker-protocol.js';
+/** The node's conversation exactly as it ran: the raw session `.jsonl` bytes
+ *  plus the assembled system prompt. Nothing here is interpreted — this is the
+ *  faithful record (every session-tree entry, every cycle, every branch, every
+ *  custom role), as opposed to `readNodeSnapshot`'s cycle-flattened
+ *  `AgentMessage[]` reconstruction. */
+export interface NodeSessionRead {
+    nodeId: string;
+    /** Absolute path of the session file the bytes came from. */
+    sessionFile: string;
+    /** Verbatim contents of the session `.jsonl`. */
+    sessionJsonl: string;
+    /** The assembled system prompt as last captured, or `null` if never written. */
+    systemPrompt: string | null;
+}
+/** Read a node's raw conversation record off disk — no broker, no attach, no
+ *  mapping. The system prompt is NOT part of the session file (pi assembles it
+ *  per boot), so it is read from the sidecar the broker captures on every
+ *  rebind (`<jobDir>/system-prompt.md`), falling back to the one `launch.ts`
+ *  writes at spawn (`<nodeDir>/system-prompt.md`). */
+export declare function readNodeSession(nodeId: string): NodeSessionRead;
+export interface NodeSnapshotRead {
+    nodeId: string;
+    snapshot: BrokerSnapshot;
+    commands: Array<{
+        name: string;
+        description: string;
+        source: 'builtin';
+    }>;
+}
+export interface NodeMessagesPageRead {
+    messages: unknown[];
+    /** Stable session-entry ids aligned 1:1 with `messages`. */
+    messageIds?: string[];
+    /** Presentation visibility aligned 1:1 with `messages`. */
+    messageVisibility: Array<'visible' | 'internal'>;
+    nextCursor: string | null;
+}
+export interface NodeMessagesPageOptions {
+    cursor?: string;
+    limit?: number;
+}
+/** Reconstruct a persisted session without launching its broker. Backs the
+ * machine-readable snapshot endpoint and the human transcript render. */
+export declare function readNodeSnapshot(nodeId: string): Promise<NodeSnapshotRead>;
+/** A backward-paged, chronological window over the same visible history as a
+ * snapshot. `nextCursor` walks toward older messages. */
+export declare function readNodeMessagesPage(nodeId: string, { cursor, limit }: NodeMessagesPageOptions): Promise<NodeMessagesPageRead>;
+/** Human-readable history only: text messages plus terse tool records, never
+ * private model reasoning. */
+export declare function transcriptMarkdown(nodeId: string): Promise<string>;

package/dist/core/runtime/node-read.js

@@ -0,0 +1,3 @@
+var C=Object.defineProperty;var a=(e,t)=>C(e,"name",{value:t,configurable:!0});import{existsSync as N,readFileSync as R}from"node:fs";import{isBeneathRefusal as F,readFileBeneath as $,readTextBeneathIfExists as j}from"../spaces/open-beneath.js";import{join as g}from"node:path";import{InputError as f}from"../io.js";import{conversationIdFromPath as h,conversationStore as y,ConversationNotFoundError as A}from"../conversation-store/index.js";import{fullName as k,getNode as p}from"../canvas/index.js";import{nodeRunDir as w,nodeRunJobDir as S,sessionPtrPath as L}from"../canvas/paths.js";import{hydratePersistedAdvertisedCommandMessages as x}from"./advertised-command-invocation.js";import{SessionManager as T}from"./broker-sdk.js";import{openModelRegistry as P}from"./model-registry.js";import{BUILTIN_SLASH_COMMANDS as B}from"./pi-vendored.js";import{cycleAwareMessages as E}from"./session-cycles.js";import{projectTranscript as J}from"./session-visibility.js";import{normalizeToolGroupSummaryRecord as O}from"../../shared/tool-groups.js";async function U(e){if(e!==null)try{return(await P()).find(e.provider,e.modelId)}catch{return}}a(U,"resolveRecordedModel");function b(e,t){const o=a(i=>{const n=i?h(i):null;if(n===null)return null;try{return y().header(n).path}catch(l){if(l instanceof A)return null;throw l}},"resolvePath"),s=o(t);if(s!==null)return s;const r=L(e);return N(r)?o(R(r,"utf8").trim()):null}a(b,"resolveSessionFile");function V(e){const t=p(e);if(t===null)throw new f({error:"not_found",message:`no node: ${e}`,field:"id",next:"List nodes with `crtr node inspect list`."});return b(e,t.pi_session_file)}a(V,"readableSessionFile");function W(e,t){return{sessionFile:t,sessionId:e,userMessages:0,assistantMessages:0,toolCalls:0,toolResults:0,totalMessages:0,tokens:{input:0,output:0,cacheRead:0,cacheWrite:0,total:0},cost:0}}a(W,"emptyStats");function D(e,t,o){const s=W(t,o);s.totalMessages=e.length;for(const r of e)if(r.role==="user")s.userMessages++;else if(r.role==="assistant"){s.assistantMessages++;const i=Array.isArray(r.content)?r.content:[];s.toolCalls+=i.filter(l=>l!==null&&typeof l=="object"&&l.type==="toolCall").length;const n=r.usage;n!==void 0&&(s.tokens.input+=n.input??0,s.tokens.output+=n.output??0,s.tokens.cacheRead+=n.cacheRead??0,s.tokens.cacheWrite+=n.cacheWrite??0,s.cost+=n.cost?.total??0)}else r.role==="toolResult"&&s.toolResults++;return s.tokens.total=s.tokens.input+s.tokens.output+s.tokens.cacheRead+s.tokens.cacheWrite,s}a(D,"statsFromMessages");function me(e){const t=p(e);if(t===null)throw new f({error:"not_found",message:`no node: ${e}`,field:"id",next:"List nodes with `crtr node inspect list`."});const o=b(e,t.pi_session_file);if(o===null)throw new f({error:"no_session",message:`node has no readable session file: ${e}`,field:"id",next:"Choose a node with captured conversation history."});return{nodeId:e,sessionFile:o,sessionJsonl:(()=>{const{header:s,entries:r}=y().read(h(o));return[s,...r].map(i=>`${JSON.stringify(i)}
+`).join("")})(),systemPrompt:v(e,g(S(e),"system-prompt.md"))??v(e,g(w(e),"system-prompt.md"))}}a(me,"readNodeSession");function v(e,t){try{return $(w(e),t).toString("utf8")}catch(o){if(F(o))throw o;return null}}a(v,"readRunFileIfPresent");function G(e){try{const t=j(w(e),g(S(e),"tool-summaries.json"));return O(t===null?null:JSON.parse(t))}catch{return{}}}a(G,"readToolGroupSummaries");async function M(e){const t=p(e);if(t===null)throw new f({error:"not_found",message:`no node: ${e}`,field:"id",next:"List nodes with `crtr node inspect list`."});const o=b(e,t.pi_session_file);if(o===null)throw new f({error:"no_session",message:`node has no readable session file: ${e}`,field:"id",next:"Choose a node with captured conversation history."});const{header:s,entries:r}=y().read(h(o)),i=T.inMemory(s.cwd,void 0,[s,...r]),n=i.buildSessionContext();x(n.messages);const l=E(i);l!==void 0&&x(l.map(({message:c})=>c));const u=l===void 0?void 0:J(l,{boundaryReviewId:t.review_binding?.review_id,sessionEntries:i.getEntries()}),m=u?.map(({message:c})=>c)??n.messages;return{sessionFile:o,messages:m,identified:u,model:n.model,thinkingLevel:n.thinkingLevel,sessionId:i.getSessionId(),sessionName:i.getSessionName()}}a(M,"reconstructTranscript");function d(){throw new f({error:"invalid_cursor",message:"cursor must be a base64url-encoded messages cursor.",field:"cursor",next:"Omit cursor to start from the newest messages."})}a(d,"invalidCursor");function z(e,t){/^[A-Za-z0-9_-]+$/u.test(e)||d();let o;try{const r=Buffer.from(e,"base64url").toString("utf8");Buffer.from(r,"utf8").toString("base64url")!==e&&d(),o=JSON.parse(r)}catch{d()}(typeof o!="object"||o===null||o.v!==1||!Number.isSafeInteger(o.before))&&d();const s=o.before;return(s<0||s>t)&&d(),s}a(z,"decodeMessagesCursor");function q(e){return Buffer.from(JSON.stringify({v:1,before:e}),"utf8").toString("base64url")}a(q,"encodeMessagesCursor");async function H(e){const t=await M(e),o={messages:t.messages,...t.identified===void 0?{}:{messageIds:t.identified.map(({id:s})=>s)},messageVisibility:t.identified?.map(({visibility:s})=>s)??t.messages.map(()=>"visible"),turnVisibility:"visible",stats:D(t.messages,t.sessionId,t.sessionFile),state:{model:await U(t.model),thinkingLevel:t.thinkingLevel,isStreaming:!1,isCompacting:!1,steeringMode:"one-at-a-time",followUpMode:"one-at-a-time",sessionFile:t.sessionFile,sessionId:t.sessionId,sessionName:t.sessionName,autoCompactionEnabled:!0,messageCount:t.messages.length,pendingMessageCount:0},display:{statuses:{},widgets:{},title:void 0},queued:{steering:[],followUp:[]},toolGroupSummaries:G(e)};return{nodeId:e,snapshot:o,commands:B.map(s=>({...s,source:"builtin"}))}}a(H,"readNodeSnapshot");async function de(e,{cursor:t,limit:o=200}){if(!Number.isSafeInteger(o)||o<1||o>500)throw new f({error:"invalid_limit",message:"limit must be an integer from 1 through 500.",field:"limit",next:"Use a limit from 1 through 500."});if(V(e)===null)return{messages:[],messageIds:[],messageVisibility:[],nextCursor:null};const{messages:s,identified:r}=await M(e),i=t===void 0?s.length:z(t,s.length);let n=Math.max(0,i-o);for(;n>0&&typeof s[n]=="object"&&s[n]!==null&&s[n].role==="toolResult";)n--;const l=r?.slice(n,i);return{messages:l?.map(({message:u})=>u)??s.slice(n,i),...l===void 0?{}:{messageIds:l.map(({id:u})=>u)},messageVisibility:l?.map(({visibility:u})=>u)??s.slice(n,i).map(()=>"visible"),nextCursor:n===0?null:q(n)}}a(de,"readNodeMessagesPage");function Y(e){return typeof e=="string"?e:Array.isArray(e)?e.filter(t=>typeof t=="object"&&t!==null).filter(t=>t.type==="text"&&typeof t.text=="string").map(t=>t.text).join(""):""}a(Y,"textFromContent");function Z(e){switch(e.role){case"user":return"You";case"assistant":return"Agent";case"toolResult":return"Tool result";default:return typeof e.role=="string"?e.role:"Message"}}a(Z,"roleLabel");function K(e){return Array.isArray(e.content)?e.content.filter(t=>typeof t=="object"&&t!==null&&t.type==="toolCall").map(t=>`Tool: ${typeof t.name=="string"?t.name:"call"}`):[]}a(K,"toolSummaries");async function pe(e){const t=p(e);if(t===null)throw new f({error:"not_found",message:`no node: ${e}`,field:"node-id",next:"List nodes with `crtr node inspect list`."});const{snapshot:o}=await H(e),r=[`# ${k(t)}`,"",`Saved transcript \xB7 ${t.status} \xB7 ${t.lifecycle}`,""];for(const i of o.messages){if(typeof i!="object"||i===null)continue;const n=i;if(n.role==="custom"&&n.display===!1)continue;const l=Y(n.content),u=typeof n.text=="string"?n.text:"",m=l.trim()?l:u.trim()?u:"",c=K(n);if(!(!m&&c.length===0)){r.push(`## ${Z(n)}`,""),m&&r.push(m,"");for(const _ of c)r.push(`- ${_}`);c.length&&r.push("")}}return r.length===5&&r.push("_No saved messages._",""),r.join(`
+`)}a(pe,"transcriptMarkdown");export{de as readNodeMessagesPage,me as readNodeSession,H as readNodeSnapshot,pe as transcriptMarkdown};

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

@@ -0,0 +1,138 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type NodeMeta, type Mode, type Lifecycle, type LaunchSpec, type ManagedWorktree, type OutcomeDeliveryBinding, type ReviewBinding } from '../canvas/index.js';
+/** Explicitly set the resolved install id. crtrd calls this once at boot,
+ *  immediately after `resolveInstallId()` — see crtrd.ts — so a provisioning
+ *  mismatch fails the daemon loudly at STARTUP rather than lazily on first
+ *  spawn. Exported for the daemon only; every other caller gets it lazily via
+ *  `installId()` below. */
+export declare function setInstallId(id: string): void;
+/** Raw time-sortable + random id shape — used for non-node opaque ids such as
+ *  focus ids (`f-…`) that are NOT canvas node identities and keep their
+ *  historical 2-segment shape (unstamped by the canvas-install id). */
+export declare function newJobId(): string;
+/** Generate a NODE id: `<install>-<time36>-<rand4hex>` (3 segments) — the
+ *  canvas-install id stamped onto the historical job-id shape, so every
+ *  minted node id is a globally-unique NAME that also names the canvas that
+ *  minted it (see the unified-chat/addressing design's "ID scheme"). crtrd is
+ *  the sole node minter. */
+export declare function newNodeId(): string;
+/** Thrown when a caller-specified `--node-id` (or its API twin `node_id`)
+ *  already names a live node. Distinguishable from every other spawn failure
+ *  so a caller can treat it as "attach instead of create" per the unified
+ *  chat/addressing design's ensure semantics — never overwrite, never
+ *  double-spawn. Mapped to HTTP 409 in `src/daemon/api/map.ts`. */
+export declare class NodeIdConflictError extends Error {
+    readonly nodeId: string;
+    constructor(nodeId: string);
+}
+/** Best-effort preflight for a caller-supplied `--node-id`, run BEFORE any
+ *  worktree is allocated for it (`spawnChild` in spawn.ts) — so a malformed or
+ *  already-taken id fails before there is anything to leak/clean up. Format
+ *  validation here is authoritative (an id that fails it can never become
+ *  valid); the duplicate check is advisory only — a concurrent create can
+ *  still win the race between this check and the synchronous check-then-
+ *  create below, which remains the SOLE authoritative decider. */
+export declare function preflightNodeId(nodeId: string): void;
+/** The root of a node's spine: walk the `parent` column up to `parent == null`.
+ *  Cycle-guarded (parents must not cycle, but never loop forever). Lives in the
+ *  node layer (not placement) so the env-builder and placement both reach it
+ *  without an import cycle — `CRTR_SUBTREE` is emitted as `rootOfSpine(nodeId)`
+ *  at every launch site. */
+export declare function rootOfSpine(nodeId: string): string;
+export interface NodeContext {
+    nodeId: string | null;
+    kind: string | null;
+    mode: Mode | null;
+}
+/** Read the current node's identity from the environment. A spawned pi process
+ *  runs with CRTR_NODE_ID set; its own `crtr` invocations spawn children under
+ *  it by reading CRTR_NODE_ID as the parent. */
+export declare function currentNodeContext(): NodeContext;
+/** Whether a node's broker admits inbox mail only between agent runs: an
+ *  app-started run and its descendants, never a person's terminal node. */
+export declare function inboxBetweenTurns(meta: Pick<NodeMeta, 'run_id' | 'grantee'>): boolean;
+/** The env injected into a node's pi process. Self-gating extensions read
+ *  CRTR_KIND/CRTR_MODE to flip behavior on polymorph without a respawn; the
+ *  feed/inbox machinery reads CRTR_NODE_ID. */
+export declare function nodeEnv(meta: NodeMeta): Record<string, string>;
+export interface SpawnNodeOpts {
+    kind: string;
+    mode?: Mode;
+    lifecycle?: Lifecycle;
+    cwd: string;
+    name?: string;
+    /** Editor-label handle (2-4 word kebab-case) for the node's first prompt. */
+    description?: string;
+    /** Parent node id: the spine manager. Omit for a user-opened root. */
+    parent?: string | null;
+    /** Node that created this node. Unlike parent (manager) and spawnedBy
+     *  (audit provenance), it is the actor of `created`, so the parent is pushed
+     *  `created` only when someone else created the child.
+     *  Null/omitted means an external process. */
+    creator?: string | null;
+    /** Node acting when neither creator nor parent is (a node forking another). */
+    actor?: string | null;
+    /** Node whose watches the new node copies (`fork`, never in the tree). */
+    forkSourceNode?: string | null;
+    /** Who spawned me (the `spawned_by` provenance edge), when it differs from
+     *  `parent` — e.g. an independent root (parent=null) still records its
+     *  spawner. Defaults to `parent`. */
+    spawnedBy?: string | null;
+    /** Raw `--fork-from` operand retained for identity framing and audit. */
+    forkFrom?: string | null;
+    /** Resolved absolute source session file retained for pre-bind retries. */
+    forkSourceFile?: string | null;
+    /** Suppress the spawn-time parent→child ACTIVE subscription. Default true
+     *  (every existing caller keeps its edge). False gives ordinary canvas
+     *  placement with no wake path back to the parent. */
+    subscribe?: boolean;
+    /** Immutable review-companion provenance. Omit for every ordinary node. */
+    reviewBinding?: ReviewBinding | null;
+    /** New subscriptions this node opens default to passive when true. */
+    passiveDefault?: boolean;
+    /** Resolved pi launch recipe (from resolve(kind,mode)). */
+    launch?: LaunchSpec;
+    /** Caller-pinned model tier (ultra/strong/medium/light) that overrides the
+     *  persona default. Persisted to `meta.model_override` so polymorphs preserve
+     *  it. Omit to use the persona default. */
+    modelOverride?: string | null;
+    /** The profile-directory id (`<slug>-<id>`) this node runs under; null only
+     *  for historical root/no-profile nodes. Written to `meta.profile_id` and the
+     *  row, and mirrored into the pi process env as `CRTR_PROFILE_ID` by
+     *  `nodeEnv` — the runtime → resolver seam every downstream memory/gate
+     *  consumer reads. Callers resolve/validate the operand (via
+     *  `loadProfileManifest`) before it reaches here; this layer just persists the
+     *  already-resolved id. */
+    profile_id?: string | null;
+    /** Per-run scope allow-list. Omit to inherit the creating node's list. */
+    scopes?: string[];
+    /** Sticky isolation; an isolated ancestor cannot be overridden. */
+    isolated?: boolean;
+    /** Run identity set on an app root; managed children inherit it. */
+    run?: Pick<NodeMeta, 'grantee' | 'sub' | 'grant_id' | 'client_id' | 'metadata_json' | 'run_id' | 'event_cursor' | 'usage_json'>;
+    /** Additional rows committed atomically with the newborn node. */
+    withinCreate?: (db: DatabaseSync, row: NodeMeta) => void;
+    /** Managed worktree already created for this node, if any. */
+    managedWorktree?: ManagedWorktree;
+    /** Absolute wall-clock deadline persisted with the row at birth. */
+    deadlineAt?: string;
+    /** Delivery target persisted with the row before any broker can launch. */
+    outcomeDelivery?: OutcomeDeliveryBinding;
+    /** Runs after the create hook admitted the birth but before its row is written. */
+    beforeCreate?: () => void | Promise<void>;
+    /** Root id replaced by this birth (`/new` or recycle); null for all other births. */
+    replaces?: string | null;
+    /** Override the generated id — either an internally pre-allocated id
+     *  (worktree naming; always valid+fresh) or an external caller's explicit id
+     *  (`--node-id`), which is format-validated
+     *  and duplicate-rejected (`NodeIdConflictError`) here. */
+    nodeId?: string;
+}
+/** The node that owns the conversation a fork copies, or null when no node does. */
+export declare function forkSourceNode(sourceFile: string): NodeMeta | null;
+/** Create a node on the canvas and wire its spawn-time edges.
+ *
+ *  For a child (parent given): the parent auto-subscribes ACTIVE to the child
+ *  (so it's woken when the child finishes), and a spawned_by audit edge is
+ *  recorded. For a root (no parent): no edges, resident by default. */
+export declare function spawnNode(opts: SpawnNodeOpts): Promise<NodeMeta>;

package/dist/core/runtime/nodes.js

@@ -0,0 +1 @@
+var H=Object.defineProperty;var a=(e,r)=>H(e,"name",{value:r,configurable:!0});import{envHomeOverride as L,envRuntimeHomeOverride as W,INBOX_BETWEEN_TURNS_ENV as G,scopeAllowed as R}from"../../shared/env.js";import{validateScopes as J}from"../scopes.js";import{activeGrant as A,terminalGrant as C}from"../grants/mirror.js";import{appendRunEvent as K}from"../runs/events.js";import{readConfig as I}from"../config.js";import{InputError as N}from"../io.js";import{ApiError as g}from"../../api/errors.js";import{randomBytes as X}from"node:crypto";import{existsSync as $}from"node:fs";import{resolve as z,relative as Y,isAbsolute as B,join as V,sep as Q}from"node:path";import{appSpace as Z}from"../layout.js";import{createNode as ee,assertRunNotDeleting as ne,conversationOwner as re,getNode as c,getRow as te}from"../canvas/index.js";import{ensureAppSpace as ie}from"../spaces/space.js";import{LAUNCHER_SOCKET as F}from"../../launcher/spec.js";import{resolveInstallId as oe}from"../canvas/install-id.js";import{isAppRun as le}from"../canvas/app-run.js";import{canvasDbPath as ae,contextDir as se}from"../canvas/paths.js";import{conversationIdFromPath as de}from"../conversation-store/index.js";import{usage as M}from"../errors.js";import{assertProfileAvailableForBirth as ue}from"../profiles/deletion-reservation.js";import{loadExactProfileManifest as ce}from"../profiles/manifest.js";import{admitNodeCreate as fe}from"../command-hooks/lifecycle-create.js";import{getById as pe,nodeObject as E,ownerForGrantee as _e}from"../graph/objects.js";import{recordActedOn as me}from"../graph/edges.js";import{recordWatch as ge,copyWatchesForFork as we}from"../graph/watches.js";import{publish as he}from"../graph/events.js";let k;const P=new Map;function en(e){k=e}a(en,"setInstallId");function Re(){if(k!==void 0)return k;const e=ae(),r=P.get(e);if(r!==void 0)return r;const o=oe();return P.set(e,o),o}a(Re,"installId");function ve(){return`${Date.now().toString(36)}-${X(4).toString("hex")}`}a(ve,"newJobId");function Ee(){return`${Re()}-${ve()}`}a(Ee,"newNodeId");const S=128,ye=/^[a-z0-9-]+$/;class j extends Error{static{a(this,"NodeIdConflictError")}nodeId;constructor(r){super(`node already exists: ${r}`),this.nodeId=r,this.name="NodeIdConflictError"}}function T(e){if(e.length===0||e.length>S)throw M(`invalid --node-id '${e}': must be 1-${S} characters`,{next:`Pass an id-safe string (lowercase letters, digits, hyphens) of at most ${S} characters.`});if(!ye.test(e))throw M(`invalid --node-id '${e}': must contain only lowercase letters, digits, and hyphens (e.g. 'remote42', 'my-node-1')`,{next:"Use only lowercase letters, digits, and hyphens."})}a(T,"validateNodeIdFormat");function nn(e){if(T(e),c(e)!==null)throw new j(e)}a(nn,"preflightNodeId");function Ce(e){if(T(e),c(e)!==null)throw new j(e);return e}a(Ce,"validatedExplicitNodeId");function rn(e){let r=e;const o=new Set;for(;;){if(o.has(r))return r;o.add(r);const s=te(r);if(s===null||s.parent==null)return r;r=s.parent}}a(rn,"rootOfSpine");function tn(){const e=process.env;return{nodeId:e.CRTR_NODE_ID??null,kind:e.CRTR_KIND??null,mode:e.CRTR_MODE??null}}a(tn,"currentNodeContext");function Ie(e){return le(e)}a(Ie,"inboxBetweenTurns");function on(e){const r={CRTR_NODE_ID:e.node_id,CRTR_KIND:e.kind,CRTR_MODE:e.mode,CRTR_LIFECYCLE:e.lifecycle,CRTR_NODE_CWD:e.cwd,CRTR_CONTEXT_DIR:se(e.node_id,e.grantee),CRTR_CYCLES:(e.cycles??0).toString(),CRTR_PROFILE_ID:e.profile_id??"",PI_CLAUDE_OAUTH_REINJECT_SCOPE:"never"};e.parent&&(r.CRTR_PARENT_NODE_ID=e.parent),e.run_id&&(r.CRTR_RUN_ID=e.run_id),Ie(e)&&(r[G]="1"),e.scopes!==null&&e.scopes!==void 0&&(r.CRTR_SCOPES=e.scopes.join(",")),r.CRTR_GRANTEE=e.grantee??"app:terminal";const o=L();o!==void 0&&o!==""&&(r.CRTR_HOME=o);const s=W();s!==void 0&&s!==""&&(r.CRTR_RUNTIME_HOME=s);const f=process.env.CRTR_SUBTREE;return f!==void 0&&f!==""&&(r.CRTR_SUBTREE=f),{...r,...e.launch?.env??{}}}a(on,"nodeEnv");function Ne(e){const r=de(e),o=r===null?null:re(r);return o===null?null:c(o)}a(Ne,"forkSourceNode");async function ln(e){const r=e.nodeId!==void 0?(T(e.nodeId),e.nodeId):Ee(),o=e.parent??null,s=o===null,f=e.spawnedBy??o,_=e.creator??null,x=e.mode??"base",y=e.lifecycle??(s?"resident":"terminal"),w=e.run===void 0?C():null,n={node_id:r,name:e.name??e.kind,description:e.description,cycles:0,created:new Date().toISOString(),cwd:e.cwd,host_kind:"broker",profile_id:e.profile_id??null,kind:e.kind,mode:x,lifecycle:y,persona_ack:{kind:e.kind,mode:x,lifecycle:y},status:"active",parent:o,spawned_by:f,creator:_,fork_from:e.forkFrom,fork_source_file:e.forkSourceFile,review_binding:e.reviewBinding,model_override:e.modelOverride??null,scopes:e.scopes??null,isolated:e.isolated===!0,grantee:e.run?.grantee??"app:terminal",sub:e.run?.sub??w?.sub??null,grant_id:e.run?.grant_id??w?.id??null,client_id:e.run?.client_id??null,metadata_json:s?e.run?.metadata_json??null:null,run_id:s?r:e.run?.run_id??null,event_cursor:s?e.run?.event_cursor??1:null,usage_json:s?e.run?.usage_json??JSON.stringify({input_tokens:0,output_tokens:0,cache_read_tokens:0,cache_write_tokens:0,cost_usd:0}):null,passive_default:e.passiveDefault??!1,...e.managedWorktree!==void 0?{managed_worktree:e.managedWorktree}:{},intent:null,deadline_at:e.deadlineAt??null,pi_session_id:null,pi_session_file:null,launch:e.launch},v=e.scopes===void 0?void 0:J(e.scopes),h=o===null?null:c(o);if(o!==null&&h===null)throw new Error(`cannot spawn under unknown parent node: ${o}`);if(h?.run_id&&c(h.run_id)?.deleting_at)throw new Error("run is deleting");const u=_===null?null:c(_);if(_!==null&&u===null)throw new Error(`cannot spawn from unknown creator node: ${_}`);if(u?.run_id&&c(u.run_id)?.deleting_at)throw new Error("run is deleting");const D=e.forkSourceFile==null?null:Ne(e.forkSourceFile),O=e.replaces==null?null:c(e.replaces),m=h??D??O??u??(f===null?null:c(f)),b=[h,u,D,O,f===null?null:c(f)].some(t=>t?.isolated===!0||t?.run_id!=null&&c(t.run_id)?.isolated===!0);if(b&&e.isolated===!1)throw new g(403,"isolated_run","isolation cannot be turned off under an isolated run",{param:"isolated"});if(n.isolated=b||e.isolated===!0,m!==null){const t=u??m;if(u&&m.grantee&&u.grantee&&u.grantee!==m.grantee)throw new g(403,"other_app_run","cannot create under another app's node");const i=u&&u!==m?[m,u]:[m],d=[];for(const l of i){l.scopes!==null&&l.scopes!==void 0&&d.push(l.scopes);const p=l.grantee==="app:terminal"?C():l.grant_id?A(l.grant_id):null;p?d.push(p.resolved):l.grantee==="app:terminal"&&!I("user").runtime?.issuer||d.push([])}if(v!==void 0&&!v.every(l=>d.every(p=>R(p,l))))throw new N({error:"unknown_scope",message:"child scopes must be covered by the creating node, its source and their current grants",received:v,field:"scopes",next:"Request only scopes the creating node currently holds."});if(n.scopes=v??(i.every(l=>l.scopes==null)&&i.every(l=>l.grant_id===t.grant_id&&l.sub===t.sub)?null:i.length===1?m.scopes??null:[...new Set(d.flat().filter(l=>d.every(p=>R(p,l))))]),n.scopes?.includes("crtr:act")&&!R(n.scopes,"crtr:llm"))throw new N({error:"invalid_scope",message:"crtr:act requires crtr:llm",received:n.scopes,field:"scopes",next:"Include crtr:llm or omit crtr:act."});n.grantee=t.grantee==="user:local"?"app:terminal":t.grantee,n.sub=t.sub??(n.grantee==="app:terminal"?w?.sub:null)??null,n.grant_id=t.grant_id??(n.grantee==="app:terminal"?w?.id:null)??null,n.client_id=t.client_id,n.run_id=s?r:t.run_id??null}if(e.run===void 0&&n.grantee==="app:terminal"&&I("user").runtime?.issuer&&w===null)throw new g(403,"scope_missing","terminal grant is not active");if(n.isolated){if(process.platform!=="linux"||!$(F))throw new g(400,"isolated_unavailable","isolated nodes require the Linux root launcher");if(e.managedWorktree!==void 0)throw new g(400,"invalid_request","isolated nodes cannot use a worktree",{param:"worktree"});const t=V(Z(n.grantee??"app:terminal").nodes,r),i=Y(t,z(n.cwd));if(!B(n.cwd)||i===".."||i.startsWith(`..${Q}`)||B(i))throw new g(400,"invalid_request","isolated node cwd must be inside its own folder",{param:"cwd"})}if(n.profile_id){const t=ce(n.profile_id).manifest.grantee??"app:terminal";if(t!==n.grantee){const i=`crtr:memory:rw:${t}:profile:${n.profile_id}`,d=n.grantee==="app:terminal"?C():n.grant_id?A(n.grant_id):null;if(!(n.grantee==="app:terminal"&&!I("user").runtime?.issuer)&&(!d||d.grantee!==n.grantee||!R(d.resolved,i))||!R(n.scopes,i))throw new N({error:"scope_missing",message:`missing scope ${i}`,received:n.profile_id,field:"profile",next:"Select a profile covered by this run and its current grant."})}}if(ue(n.profile_id??null),!n.grantee)throw new Error("node creation requires an app");const U=await fe({kind:n.kind,mode:n.mode,cwd:n.cwd,profile:n.profile_id??null,root:s,parentId:o,requestingNodeId:_,lifecycle:y,replaces:e.replaces??null},n.grantee),q=a((t,i)=>{const d=E(t,i.node_id),l=_??o??e.actor??f??null,p=l!==null&&pe(t,l)?.type==="node"?E(t,l):_e(t,e.run===void 0?"user:local":i.grantee);me(t,p,d),o!==null&&e.subscribe!==!1&&ge(t,E(t,o),d,"spawn"),e.forkSourceNode&&we(t,E(t,e.forkSourceNode),d),he(t,{event:"created",object:d,actor:p,attrs:{name:i.name,kind:i.kind,creator:_??null}})},"recordBirth");try{e.nodeId!==void 0&&Ce(e.nodeId),await e.beforeCreate?.(),(process.platform!=="linux"||$(F))&&await ie(n.grantee??"app:terminal"),ee(n,{outcomeDelivery:e.outcomeDelivery,withinCreate:a((t,i)=>{i.run_id&&i.run_id!==i.node_id&&ne(t,i.run_id),s&&e.run===void 0&&K(t,r,r,"run.started",{scopes:i.scopes??null,payer:"user",usage:JSON.parse(i.usage_json)}),e.withinCreate?.(t,i),q(t,i)},"withinCreate")})}finally{U()}return n}a(ln,"spawnNode");export{j as NodeIdConflictError,tn as currentNodeContext,Ne as forkSourceNode,Ie as inboxBetweenTurns,ve as newJobId,Ee as newNodeId,on as nodeEnv,nn as preflightNodeId,rn as rootOfSpine,en as setInstallId,ln as spawnNode};

package/dist/core/runtime/outcome-document.d.ts

@@ -0,0 +1,59 @@
+import type { DeclinedResult, NodeMeta, NodeOutcomeDetailV1, NodeOutcomeKind, TerminalReason } from '../canvas/types.js';
+export interface NodeOutcomeDocumentV1 {
+    schema: 'crtr.node-outcome/v1';
+    outcomeId: string;
+    nodeId: string;
+    revision: number;
+    kind: NodeOutcomeKind;
+    reason: TerminalReason;
+    settledAt: string;
+    node: {
+        name: string;
+        description?: string;
+        kind: string;
+        mode: 'base' | 'orchestrator';
+        lifecycle: 'terminal' | 'resident';
+        status: 'active' | 'idle' | 'done' | 'dead' | 'canceled';
+        terminalReason: TerminalReason | null;
+        cwd: string;
+        createdAt: string;
+        parent: string | null;
+        spawnedBy: string | null;
+    };
+    result?: {
+        /** The final report document's ref (`<nodeId>/reports/<name>`), read with `crtr canvas read`. */
+        finalReport: {
+            name: string;
+        };
+        structuredResult?: unknown;
+        structuredResultOmitted?: true;
+        structuredResultPath?: string;
+    };
+    failure?: {
+        message: string | null;
+        faultKind: NodeOutcomeDetailV1['fault_kind'] | null;
+        errorClass: NodeOutcomeDetailV1['error_class'] | null;
+        respawnFailures: number | null;
+        deadline: {
+            deadlineAt: string;
+            elapsedMs: number;
+        } | null;
+        /** Set only for reason `declined`: the reason, requester-classified code, and retryable claim. */
+        declined: DeclinedResult | null;
+    };
+}
+/** Freeze an action-independent document at outcome time. */
+export declare function composeNodeOutcomeDocument(args: {
+    node: NodeMeta;
+    outcome: {
+        kind: NodeOutcomeKind;
+        reason: TerminalReason;
+        at: string;
+        revision: number;
+        detailJson: string | null;
+    };
+    /** Required for a result before the final-report pointer has committed. */
+    finalReport?: string | null;
+    /** Lets the outcome transaction supply a parsed result without a second read. */
+    structuredResult?: unknown;
+}): NodeOutcomeDocumentV1;

package/dist/core/runtime/outcome-document.js

@@ -0,0 +1 @@
+var a=Object.defineProperty;var s=(t,e)=>a(t,"name",{value:e,configurable:!0});import{contextDir as f}from"../canvas/node-agent-paths.js";import{readOutputResult as m}from"./structured-output.js";const p=256*1024;function y(t,e){try{return m(t,e)}catch{return}}s(y,"structuredResult");function _(t){if(t===null)return null;try{return JSON.parse(t)}catch{return null}}s(_,"parseDetail");function c(t){if(Buffer.byteLength(t,"utf8")<=1024)return t;const n="\u2026";let r=Buffer.byteLength(n,"utf8"),l="";for(const i of t){const d=Buffer.byteLength(i,"utf8");if(r+d>1024)break;r+=d,l+=i}return`${l}${n}`}s(c,"truncateDescription");function k(t){const{node:e,outcome:n}=t,r=_(n.detailJson),l=t.finalReport??e.final_report??"",i=c(e.name),d=e.description===void 0?void 0:c(e.description),o=n.kind==="result"?t.structuredResult===void 0?y(e.node_id,e.grantee):t.structuredResult:void 0,u={schema:"crtr.node-outcome/v1",outcomeId:`${e.node_id}:${n.revision}`,nodeId:e.node_id,revision:n.revision,kind:n.kind,reason:n.reason,settledAt:n.at,node:{name:i,...d===void 0?{}:{description:d},kind:e.kind,mode:e.mode,lifecycle:e.lifecycle,status:e.status,terminalReason:e.terminal_reason??null,cwd:e.cwd,createdAt:e.created,parent:e.parent??null,spawnedBy:e.spawned_by??null},...n.kind==="result"?{result:{finalReport:{name:`${e.node_id}/${l}`},...o===void 0?{}:{structuredResult:o}}}:{failure:{message:r?.message??null,faultKind:r?.fault_kind??null,errorClass:r?.error_class??null,respawnFailures:r?.respawn_failures??null,deadline:r?.deadline===void 0?null:{deadlineAt:r.deadline.deadline_at,elapsedMs:r.deadline.elapsed_ms},declined:r?.declined??null}}};return Buffer.byteLength(JSON.stringify(u),"utf8")>p&&u.result?.structuredResult!==void 0&&(delete u.result.structuredResult,u.result.structuredResultOmitted=!0,u.result.structuredResultPath=`${f(e.node_id,e.grantee)}/result.json`),u}s(k,"composeNodeOutcomeDocument");export{k as composeNodeOutcomeDocument};

package/dist/core/runtime/package-health.d.ts

@@ -0,0 +1,34 @@
+export interface MissingPackage {
+    /** The raw `packages[]` entry as stored in settings.json. */
+    source: string;
+    /** Absolute path it resolved to (which does not exist). */
+    resolved: string;
+}
+/** A non-fatal, action-oriented diagnostic for an unprovisioned managed
+ * renderer — the one remaining out-of-tree dependency. Deliberately calls
+ * `isRendererReady()`, NOT `ensureRenderer()`: this runs on the front-door boot
+ * path and at crtrd startup, where a `uv pip install` (up to 180s) must never
+ * happen. Readiness is a handful of fs stats, no subprocess. */
+export declare function rendererWarning(): string | null;
+/**
+ * The pi agent config dir (`~/.pi/agent`, or `$PI_CODING_AGENT_DIR`) — a local
+ * reimplementation of pi's `getAgentDir()`. Reimplemented (not imported) ON
+ * PURPOSE: `getAgentDir` lives in `@earendil-works/pi-coding-agent`, and
+ * importing that package pulls in the ENTIRE ~360ms pi engine module graph. The
+ * front door calls this on every bare-`crtr` boot BEFORE spawning the broker, so
+ * a static/dynamic pi import here adds ~316ms of serialized dead-time in the
+ * foreground before the broker (which loads pi itself) even starts. This mirrors
+ * pi's contract exactly: `$PI_CODING_AGENT_DIR` (tilde-expanded) else
+ * `~/.pi/agent`. Same precedent as `bearings.ts` (keep the pi engine out of the
+ * hot/foreground path). If pi ever rebrands its configDir/env, update here.
+ */
+export declare function piAgentDir(homeDir?: string): string;
+/**
+ * Return every local-path package in `<agentDir>/settings.json` whose resolved
+ * path is missing. Empty when settings is absent/unreadable or all paths exist.
+ * Mirrors pi's own resolution: `resolve(agentDir, expandTilde(source))`.
+ */
+export declare function findMissingPackagePaths(agentDir: string, homeDir?: string): MissingPackage[];
+/** A human-readable, actionable warning for a set of missing packages, or
+ *  `null` when nothing is missing. Names `crtr sys setup` as the fix. */
+export declare function missingPackageWarning(agentDir: string, homeDir?: string): string | null;

package/dist/core/runtime/package-health.js

@@ -0,0 +1,4 @@
+var u=Object.defineProperty;var t=(r,e)=>u(r,"name",{value:e,configurable:!0});import{existsSync as f,readFileSync as g}from"node:fs";import{homedir as a}from"node:os";import{appSpace as m}from"../layout.js";import{join as c,resolve as d}from"node:path";import{isRendererReady as h}from"../termrender/termrender.js";import{expandTilde as l}from"../fs-utils.js";function j(){return h()?null:"crtr: the pinned termrender renderer is not provisioned \u2014 pages, reviews, and inline diagrams render as plaintext.\n  Fix: run `crtr sys setup` (requires `uv`: curl -LsSf https://astral.sh/uv/install.sh | sh)."}t(j,"rendererWarning");function w(r=a()){const e=process.env.PI_CODING_AGENT_DIR;return e!==void 0&&e!==""?l(e,r):c(r===a()?m("terminal").home:r,".pi","agent")}t(w,"piAgentDir");function y(r){return r.startsWith("npm:")?!1:r.startsWith(".")||r.startsWith("/")||r.startsWith("~")}t(y,"isLocalPathSource");function v(r,e=a()){let n;try{n=g(c(r,"settings.json"),"utf8")}catch{return[]}let s;try{s=JSON.parse(n).packages}catch{return[]}if(!Array.isArray(s))return[];const i=[];for(const o of s){if(typeof o!="string"||!y(o))continue;const p=d(r,l(o,e));f(p)||i.push({source:o,resolved:p})}return i}t(v,"findMissingPackagePaths");function F(r,e=a()){const n=v(r,e);if(n.length===0)return null;const s=n.map(i=>`  \u2022 ${i.source}
+      \u2192 ${i.resolved} (missing)`);return`crtr: ${n.length} configured pi package path${n.length===1?"":"s"} no longer exist${n.length===1?"s":""} \u2014 pi silently skips these, so their slash commands (e.g. ~/.claude commands & marketplace plugins) will not load.
+`+s.join(`
+`)+"\n  Fix: re-run `crtr sys setup` (re-resolves package paths to this repo's current location)."}t(F,"missingPackageWarning");export{v as findMissingPackagePaths,F as missingPackageWarning,w as piAgentDir,j as rendererWarning};

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

@@ -0,0 +1,21 @@
+import { type Mode, type Lifecycle } from '../canvas/index.js';
+/** The three-axis persona transition key. */
+export interface Persona {
+    kind: string;
+    mode: Mode;
+    lifecycle: Lifecycle;
+}
+export interface PersonaDriftResult {
+    from: Persona;
+    to: Persona;
+    /** Fresh-context framing for `to`; its snapshots carry document context. */
+    guidance: string;
+}
+/** Build only the non-document framing for a fresh-context transition. */
+export declare function transitionGuidance(nodeId: string, from: Persona, to: Persona): string;
+/** Compare the live persona with the last acknowledged context delivery.
+ * `guidance` contains only fresh-context framing; current snapshots supply its
+ * documents. An absent or pre-kind acknowledgment cannot fabricate drift. */
+export declare function personaDrift(nodeId: string): PersonaDriftResult | null;
+/** Commit the persona state whose context delivery is complete. */
+export declare function commitPersonaAck(nodeId: string, to: Persona): void;

package/dist/core/runtime/persona.js

@@ -0,0 +1,2 @@
+var s=Object.defineProperty;var n=(o,e)=>s(o,"name",{value:e,configurable:!0});import{getNode as i,updateNode as d}from"../canvas/index.js";import{readRoadmap as c}from"./roadmap.js";import{orchestratorContextNote as u}from"./bearings.js";function l(o,e){const r=c(o)??"(no roadmap yet)",t=[`You are now a ${e.toUpperCase()} ORCHESTRATOR. Your scarce resource is your own context window.`,"Your job is to manage context and delegate \u2014 not to do the goal yourself."];return t.push("","Your roadmap is your document `roadmap`; it loads at every new session of yours. Author it now with `crtr doc edit roadmap`: state the goal and exit criteria, and set the preview to the goal\u2019s first line, using your orchestration protocol. Current contents:","",r,"",u(),"","What promotion changes is how long your documents matter: you now persist across refresh cycles, so the documents you own (`crtr doc write`) carry what this goal needs between your refreshes, and a lesson that should outlive this node gets another owner (`--owner user|repo|profile`).","","Then delegate each unit with `crtr node new --kind <kind>`. When your context fills, run `crtr node yield` to refresh against this roadmap."),t.join(`
+`)}n(l,"orchestrationGuidance");function m(){return"You are HANDS-ON again \u2014 base mode. Do the work yourself in THIS window and finish it here; stop delegating by default. You no longer drive a roadmap, so `crtr node yield` is not your exit. Spawn a child only for a cleanly separable unit, never as your first move."}n(m,"baseModeGuidance");function f(o,e,r){if(e.mode===r.mode)return"";if(r.mode==="base")return m();const t=i(o);return l(o,t?.kind??"general")}n(f,"transitionGuidance");function g(o){const e=i(o);if(e===null)return null;const r={kind:e.kind,mode:e.mode,lifecycle:e.lifecycle},t=e.persona_ack,a=t===void 0?r:{kind:t.kind??e.kind,mode:t.mode,lifecycle:t.lifecycle};return a.kind===r.kind&&a.mode===r.mode&&a.lifecycle===r.lifecycle?null:{from:a,to:r,guidance:f(o,a,r)}}n(g,"personaDrift");function k(o,e){d(o,{persona_ack:e})}n(k,"commitPersonaAck");export{k as commitPersonaAck,g as personaDrift,f as transitionGuidance};

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

@@ -0,0 +1,8 @@
+export declare function resolveBundledPiPackageDir(): string;
+/** Environment for a bundled pi subprocess. pi resolves theme assets relative
+ *  to its package root; pnpm/npm mixed layouts can make its own module URL point
+ *  through `.pnpm` at a package copy without those JSON assets, so explicitly
+ *  pin the real bundled package directory (the same contract attach uses). */
+export declare function bundledPiSubprocessEnv(): NodeJS.ProcessEnv;
+export declare function resolveBundledPiCliPath(): string;
+export declare function bundledPiCommandForShell(quote: (value: string) => string): string;

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

@@ -0,0 +1 @@
+var d=Object.defineProperty;var i=(r,n)=>d(r,"name",{value:n,configurable:!0});import{existsSync as c,readFileSync as s}from"node:fs";import{dirname as l,join as a,parse as u}from"node:path";import{fileURLToPath as f}from"node:url";function g(r,n){let e=l(r);const o=u(e).root;for(;;){const t=a(e,"package.json");if(c(t))try{if(JSON.parse(s(t,"utf8")).name===n)return e}catch{return null}if(e===o)return null;e=l(e)}}i(g,"findPackageRootFromEntry");function p(){const r="@earendil-works/pi-coding-agent";let n;try{n=f(import.meta.resolve(r))}catch(o){throw new Error(`crouter install is missing bundled ${r}; reinstall crouter. ${o.message}`)}const e=g(n,r);if(e===null)throw new Error(`could not locate bundled ${r} package root from ${n}`);return e}i(p,"resolveBundledPiPackageDir");function y(){return{...process.env,PI_PACKAGE_DIR:p()}}i(y,"bundledPiSubprocessEnv");function m(){const r=p(),n=a(r,"package.json"),e=JSON.parse(s(n,"utf8")),o=e.bin&&typeof e.bin=="object"?e.bin.pi:void 0;if(typeof o!="string"||o.trim()==="")throw new Error(`bundled @earendil-works/pi-coding-agent does not declare a pi binary in ${n}`);const t=a(r,o);if(!c(t))throw new Error(`bundled pi binary is missing at ${t}`);return t}i(m,"resolveBundledPiCliPath");function $(r){return`${r(process.execPath)} ${r(m())}`}i($,"bundledPiCommandForShell");export{$ as bundledPiCommandForShell,y as bundledPiSubprocessEnv,m as resolveBundledPiCliPath,p as resolveBundledPiPackageDir};

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

@@ -0,0 +1,28 @@
+/** pi's sessions root, VENDORED from pi `config.getSessionsDir()` (= `<agentDir>/
+ *  sessions`). pi's package `exports` map is `.`-only, so config.js can't be
+ *  deep-imported, and a ROOT import of `getAgentDir` would eager-load the entire
+ *  heavy pi SDK index on crtr's front-door hot path (the reason broker-sdk.ts
+ *  dynamic-imports the engine). Mirrors pi: `PI_CODING_AGENT_DIR` env, else
+ *  `~/.pi/agent` (APP_NAME defaults to 'pi'). Re-sync on a pi SDK bump that moves
+ *  the sessions dir — same vendoring rationale as the slash-command list below.
+ *  `PI_CODING_AGENT_DIR` goes through the same tilde expansion pi's
+ *  `getAgentDir()` applies, or `~/custom-pi` yields a broken relative path. */
+export declare function piSessionsRoot(): string;
+/**
+ * pi's builtin slash commands — vendored verbatim from pi `core/slash-commands.js`
+ * `BUILTIN_SLASH_COMMANDS` (review C1). **21 entries at 0.78.1** (review n1 — NOT 23).
+ *
+ * Builtins are NOT engine-interpreted (`session.prompt('/model')` ships `/model`
+ * to the LLM as literal text), so the broker's `get_commands` op MERGES this list
+ * with the engine's registered commands/templates/skills, and the viewer
+ * autocomplete parses these locally. Both the broker and the viewer
+ * import this single copy.
+ *
+ * Upstream interpolates `${APP_NAME}` into the `quit` description; `APP_NAME`
+ * defaults to "pi" (overridable via pi config), so the vendored copy hardcodes
+ * "Quit pi".
+ */
+export declare const BUILTIN_SLASH_COMMANDS: ReadonlyArray<{
+    name: string;
+    description: string;
+}>;

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

@@ -0,0 +1 @@
+var i=Object.defineProperty;var e=(s,n)=>i(s,"name",{value:n,configurable:!0});import{join as o}from"node:path";import{piAgentDir as t}from"./package-health.js";function c(){return o(t(),"sessions")}e(c,"piSessionsRoot");const m=[{name:"settings",description:"Open settings menu"},{name:"model",description:"Select model (opens selector UI)"},{name:"scoped-models",description:"Enable/disable models for Ctrl+P cycling"},{name:"export",description:"Export session (HTML default, or specify path: .html/.jsonl)"},{name:"import",description:"Import and resume a session from a JSONL file"},{name:"share",description:"Share session as a secret GitHub gist"},{name:"copy",description:"Copy last agent message to clipboard"},{name:"name",description:"Set session display name"},{name:"session",description:"Show session info and stats"},{name:"changelog",description:"Show changelog entries"},{name:"hotkeys",description:"Show all keyboard shortcuts"},{name:"fork",description:"Create a new fork from a previous user message"},{name:"clone",description:"Duplicate the current session at the current position"},{name:"tree",description:"Navigate session tree (switch branches)"},{name:"login",description:"Configure provider authentication"},{name:"logout",description:"Remove provider authentication"},{name:"new",description:"Start a new session"},{name:"compact",description:"Manually compact the session context"},{name:"resume",description:"Resume a different session"},{name:"reload",description:"Reload keybindings, extensions, skills, prompts, and themes"},{name:"quit",description:"Quit pi"}];export{m as BUILTIN_SLASH_COMMANDS,c as piSessionsRoot};

package/dist/core/runtime/placement-tmux.d.ts

@@ -0,0 +1,32 @@
+export { paneExists, paneLocation, paneOfNode, paneCurrentPath, paneSize, paneRunning, ensureSession, openNodeWindow, splitWindow, closePane, currentTmux, switchClient, selectWindow, selectLayout, selectPane, getPaneOption, setPaneOption, breakPane, inTmux, piCommand, shellQuote, renameWindow, displayPopup, displayPopupAsync, windowOfPane, respawnPaneSync, respawnPaneInBackground, respawnPaneInPlace, runShellInBackground, paneStartCommand, panePid, windowAlive, listLivePanes, VIEWER_STAMP_OPTION, stampViewerPaneAsync, liveViewerPanes, sendAttachControl, displayClientMessage, displayMessage, windowIndex, sessionExists, tmuxAvailable, tmuxInteractive, } from './tmux-driver.js';
+export { installTmuxBindings } from './tmux-bindings.js';
+export { BROKER_VIEW_SOCKET_WAIT_MS, waitForBrokerViewSocket } from './view-socket.js';
+/** Env for a `crtr surface attach` VIEWER pane (the focus split, the spawn viewer
+ *  window, AND recycle's re-attach respawn): propagate CRTR_HOME so the viewer
+ *  resolves the SAME canvas home — and thus the right view.sock — under a
+ *  non-default override; otherwise an empty env (the pane inherits the tmux
+ *  server env, like every other crtr chrome pane). One helper so the viewer-pane
+ *  sites can't drift. */
+export declare function viewerSplitEnv(): Record<string, string>;
+/** The opened viewer pane's tmux coordinates. */
+export interface ViewerPane {
+    pane: string;
+    session: string | null;
+    window: string | null;
+}
+/** Open a `crtr surface attach` VIEWER pane for `nodeId` — the PURE tmux half of
+ *  placement's openViewerWindow (no focus-row write). Wraps `ensureSession` +
+ *  `openNodeWindow`/`splitWindow`. The attach client connects to the node's
+ *  `view.sock` and renders/drives the live broker engine — it NEVER launches the
+ *  engine (the one-writer invariant; the caller ensures the broker is alive
+ *  first). Returns the opened pane's coordinates, or null if tmux refused.
+ *    - default → a fresh WINDOW in `session` (the --root spawn-viewer path).
+ *    - `besidePane` → a SPLIT beside that pane in its own session (the focus
+ *      open-beside-the-caller path); `session` is then only a fallback. */
+export declare function openViewerPane(nodeId: string, session: string, opts?: {
+    name?: string;
+    cwd?: string;
+    besidePane?: string;
+    waitForBroker?: boolean;
+    initialWhip?: boolean;
+}): ViewerPane | null;

package/dist/core/runtime/placement-tmux.js

@@ -0,0 +1 @@
+var u=Object.defineProperty;var s=(e,n)=>u(e,"name",{value:n,configurable:!0});import{envHomeOverride as w}from"../../shared/env.js";import{paneLocation as m,ensureSession as P,openNodeWindow as T,splitWindow as f,selectLayout as _}from"./tmux-driver.js";import{BROKER_VIEW_SOCKET_WAIT_MS as I}from"./view-socket.js";import{paneExists as v,paneLocation as y,paneOfNode as g,paneCurrentPath as h,paneSize as B,paneRunning as M,ensureSession as V,openNodeWindow as k,splitWindow as H,closePane as L,currentTmux as N,switchClient as b,selectWindow as K,selectLayout as z,selectPane as F,getPaneOption as Q,setPaneOption as $,breakPane as j,inTmux as q,piCommand as D,shellQuote as G,renameWindow as J,displayPopup as U,displayPopupAsync as X,windowOfPane as Y,respawnPaneSync as Z,respawnPaneInBackground as ee,respawnPaneInPlace as ne,runShellInBackground as ie,paneStartCommand as oe,panePid as te,windowAlive as ae,listLivePanes as re,VIEWER_STAMP_OPTION as se,stampViewerPaneAsync as le,liveViewerPanes as ce,sendAttachControl as pe,displayClientMessage as de,displayMessage as ue,windowIndex as we,sessionExists as me,tmuxAvailable as Pe,tmuxInteractive as Te}from"./tmux-driver.js";import{installTmuxBindings as _e}from"./tmux-bindings.js";import{BROKER_VIEW_SOCKET_WAIT_MS as Se,waitForBrokerViewSocket as Ae}from"./view-socket.js";function S(){const e=w();return e!==void 0?{CRTR_HOME:e}:{}}s(S,"viewerSplitEnv");function E(e,n,i={}){const l=`crtr surface attach to ${e}`,c={...S(),...i.waitForBroker===!0?{CRTR_ATTACH_WAIT_MS:String(I)}:{},...i.initialWhip===!0?{CRTR_ATTACH_INITIAL_WHIP:"1"}:{}},o=i.cwd??process.cwd();if(i.besidePane!==void 0){const a=f(i.besidePane,{cwd:o,env:c,command:l});if(a===null)return null;const p=m(a),d=p?.session??n,r=p?.window??null;return r!==null&&_(r,"even-horizontal"),{pane:a,session:d,window:r}}P(n,o);const t=T({session:n,name:i.name??e,cwd:o,env:c,command:l});return t===null?null:{pane:t.pane,session:n,window:t.window}}s(E,"openViewerPane");export{Se as BROKER_VIEW_SOCKET_WAIT_MS,se as VIEWER_STAMP_OPTION,j as breakPane,L as closePane,N as currentTmux,de as displayClientMessage,ue as displayMessage,U as displayPopup,X as displayPopupAsync,V as ensureSession,Q as getPaneOption,q as inTmux,_e as installTmuxBindings,re as listLivePanes,ce as liveViewerPanes,k as openNodeWindow,E as openViewerPane,h as paneCurrentPath,v as paneExists,y as paneLocation,g as paneOfNode,te as panePid,M as paneRunning,B as paneSize,oe as paneStartCommand,D as piCommand,J as renameWindow,ee as respawnPaneInBackground,ne as respawnPaneInPlace,Z as respawnPaneSync,ie as runShellInBackground,z as selectLayout,F as selectPane,K as selectWindow,pe as sendAttachControl,me as sessionExists,$ as setPaneOption,G as shellQuote,H as splitWindow,le as stampViewerPaneAsync,b as switchClient,Pe as tmuxAvailable,Te as tmuxInteractive,S as viewerSplitEnv,Ae as waitForBrokerViewSocket,ae as windowAlive,we as windowIndex,Y as windowOfPane};

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

@@ -0,0 +1,100 @@
+import { type FocusRow } from '../canvas/index.js';
+export type { FocusRow };
+export { splitWindow, breakPane, selectLayout, selectPane, focusWindow, selectWindow, switchClient, openNodeWindow, ensureSession, paneLocation, paneExists, paneRunning, paneCurrentPath, currentTmux, inTmux, paneOfNode, setPaneOption, getPaneOption, piCommand, shellQuote, respawnPaneSync, closePane, displayPopup, windowOfPane, renameWindow, paneOfWindow, windowAlive, listLivePanes, listLivePanesAsync, } from './tmux-driver.js';
+export type { RespawnPaneOpts } from './tmux-driver.js';
+export { installTmuxBindings } from './tmux-bindings.js';
+export type { TmuxInstalledPair, TmuxInstallDiagnostic, TmuxInstallResult } from './tmux-bindings.js';
+/** The viewer a node has on screen, or null. UNIQUE(node_id) ⇒ at most one. */
+export declare function focusOf(nodeId: string): FocusRow | null;
+/** Does this node have a live viewer on screen? */
+export declare function isFocused(nodeId: string): boolean;
+/** The viewer realized by a given pane (`%id`), or null. */
+export declare function focusByPane(pane: string): FocusRow | null;
+/** The set of node ids that currently have a live viewer. */
+export declare function focusedNodes(): Set<string>;
+/** Every live viewer row (GC'ing any whose pane has gone). */
+export declare function listFocuses(): FocusRow[];
+/** A reviver: ensure a node's broker ENGINE is alive (idempotent → reviveNode →
+ *  headlessBrokerHost.launch). Injected so placement.ts need not import revive.ts
+ *  (which imports placement.ts — a cycle). */
+export type Reviver = (nodeId: string) => {
+    launch?: {
+        exited: Promise<{
+            code: number | null;
+            signal: NodeJS.Signals | null;
+        }>;
+    };
+} | void;
+/** Result of a focus op. `inPlace` = navigated to an existing viewer (no new
+ *  pane); false = a fresh viewer pane was opened/moved. `revived` = this call
+ *  had to (re)launch the broker engine. */
+export interface FocusResult {
+    focused: boolean;
+    session: string | null;
+    inPlace: boolean;
+    revived: boolean;
+}
+/** Register a `crtr surface attach` VIEWER pane as the node's one viewer focus row.
+ *  UNIQUE(node_id) ⇒ one viewer per node: returns
+ *  the existing row (no insert) when the pane or the node is already registered.
+ *  `window` is accepted for the call contract (spawn passes it) but not stored —
+ *  the focuses table keys on pane + session only. The attach client self-tags the
+ *  pane `@crtr_node` on connect, so `nodeInPane` resolves it either way. */
+export declare function registerViewerFocus(nodeId: string, pane: string, session: string | null, window: string | null): FocusRow | null;
+/** Open a surface-attach viewer for `nodeId` and register its viewer focus row —
+ *  the shared opener used by `focus` (a split beside the caller) and by a --root
+ *  spawn (a fresh window in the caller's current session). Wraps `ensureSession`
+ *  + `openNodeWindow`/`splitWindow` + `registerViewerFocus`. The attach client
+ *  connects to the node's `view.sock` and renders/drives the live broker engine
+ *  — it NEVER launches the engine (the one-writer invariant; the caller ensures
+ *  the broker is alive first). Returns the registered viewer row, or null if tmux
+ *  refused.
+ *    - default → a fresh WINDOW in `session` (the --root spawn-viewer path).
+ *    - `besidePane` → a SPLIT beside that pane in its own session (the focus
+ *      open-beside-the-caller path); `session` is then only a fallback. */
+export declare function openViewerWindow(nodeId: string, session: string, opts?: {
+    name?: string;
+    cwd?: string;
+    besidePane?: string;
+    waitForBroker?: boolean;
+    initialWhip?: boolean;
+}): FocusRow | null;
+export declare function focus(nodeId: string, opts: {
+    pane?: string;
+    newPane?: boolean;
+    inPlace?: boolean;
+    revive: Reviver;
+}): Promise<FocusResult>;
+/** Tear a node off its viewer (close/reset/cancel teardown). The broker engine
+ *  is killed by its own host teardown over view.sock — this only closes the
+ *  on-screen viewer: kill its pane (the window collapses once its last pane goes)
+ *  and drop its registry row. Best-effort tmux; the DB write always lands. No-op
+ *  when the node has no viewer. */
+export declare function tearDownNode(nodeId: string, keepPane?: string): void;
+/** Detach a node from the foreground (the `node lifecycle demote --detach` / Alt+C → D
+ *  half). Every node is a headless broker — the only thing on screen is its
+ *  surface-attach viewer pane — so "detach" means STOP FOREGROUNDING it: close the
+ *  viewer pane (and drop its row) and leave the broker engine running untouched,
+ *  reconnectable by a later `focus`. `pane` is the authoritative pane the caller
+ *  acts on (the Alt+C menu's `#{pane_id}`); falls back to the node's registered
+ *  viewer pane. No-op (false) when there is no live viewer pane to close. */
+export declare function detachToBackground(nodeId: string, pane?: string): boolean;
+/** Reap `nodeId` IFF it is an empty shell (see {@link isEmptyNode}): tear down its
+ *  broker engine, close any viewer, and hard-delete its row (edges cascade) + dir.
+ *  The user closing or detaching from a node that never said anything wants it
+ *  GONE, not parked as a canceled husk — except an OPEN managed worktree keeps
+ *  its node identity so the worktree remains owned and can later be closed.
+ *  Returns true when it reaped. No-op (false) on a node that produced output,
+ *  is mid-first-turn, owns an open managed worktree, or no longer exists. */
+export declare function reapIfEmpty(nodeId: string, keepPane?: string, teardown?: boolean): boolean;
+/** Sweep the whole canvas for empty shells and reap them — the bulk cleanup
+ *  behind `crtr canvas prune --empty`, for the husks that accumulated before
+ *  close/detach learned to reap. Skips: the caller ($CRTR_NODE_ID), dead rows,
+ *  nodes mid-first-turn, and any node with a LIVE broker (pi_pid alive) — a
+ *  running engine is the daemon's domain and may have output not yet persisted,
+ *  so bulk GC never kills one (the per-action {@link reapIfEmpty} does, since
+ *  the user explicitly closed/detached that node). `dryRun` reports candidates
+ *  without deleting. Returns the reaped (or, under dryRun, reapable) node ids. */
+export declare function reapEmptyNodes(opts?: {
+    dryRun?: boolean;
+}): string[];

package/dist/core/runtime/placement.js

@@ -0,0 +1 @@
+var V=Object.defineProperty;var t=(e,n)=>V(e,"name",{value:n,configurable:!0});import{envNodeId as $}from"../../shared/env.js";import{getNode as m,fullName as H,deleteNode as R,listNodes as M,openFocusRow as z,closeFocusRow as a,getFocusByNode as T,getFocusByPane as x,getFocusById as D,listFocuses as J}from"../canvas/index.js";import{nodeHasAssistantMessage as Q}from"../canvas/render-source.js";import{headlessBrokerHost as k}from"./host.js";import{publishNotice as U}from"./close.js";import{paneExists as d,paneLocation as h,closePane as P,currentTmux as X,switchClient as j,selectWindow as q,selectLayout as G,selectPane as S,getPaneOption as K,setPaneOption as Y,respawnPaneSync as Z,windowOfPane as I,renameWindow as ee}from"./tmux-driver.js";import{openViewerPane as ne,viewerSplitEnv as W,waitForBrokerViewSocket as oe}from"./placement-tmux.js";import{newJobId as se}from"./nodes.js";import{isPidAlive as y}from"../canvas/pid.js";import{splitWindow as Oe,breakPane as Re,selectLayout as Te,selectPane as ke,focusWindow as Se,selectWindow as We,switchClient as be,openNodeWindow as Ae,ensureSession as Be,paneLocation as Ee,paneExists as Ce,paneRunning as Le,paneCurrentPath as Ve,currentTmux as $e,inTmux as He,paneOfNode as Me,setPaneOption as ze,getPaneOption as De,piCommand as Je,shellQuote as Qe,respawnPaneSync as Ue,closePane as Xe,displayPopup as je,windowOfPane as qe,renameWindow as Ge,paneOfWindow as Ke,windowAlive as Ye,listLivePanes as Ze,listLivePanesAsync as Ie}from"./tmux-driver.js";import{installTmuxBindings as nn}from"./tmux-bindings.js";function g(e){return e===null?null:e.pane!==null&&!d(e.pane)?(a(e.focus_id),null):e}t(g,"liveOrPrune");function p(e){return g(T(e))}t(p,"focusOf");function _e(e){return p(e)!==null}t(_e,"isFocused");function ie(e){return g(x(e))}t(ie,"focusByPane");function xe(){return new Set(te().map(e=>e.node_id))}t(xe,"focusedNodes");function te(){const e=[];for(const n of J())g(n)!==null&&e.push(n);return e}t(te,"listFocuses");function re(){return`f-${se()}`}t(re,"newFocusId");function b(e,n,o,s){const u=x(n);if(u!==null)return u;const r=T(e);if(r!==null)return r;const l=re();return z(l,n,o,e),D(l)}t(b,"registerViewerFocus");function A(e,n,o={}){const s=ne(e,n,o);return s===null?null:b(e,s.pane,s.session,s.window)}t(A,"openViewerWindow");function B(e){const n=h(e)?.window??null;n!==null&&G(n,"even-horizontal"),S(e)}t(B,"surfaceNewPane");async function he(e,n){const o=m(e);if(o===null)return{focused:!1,session:null,inPlace:!1,revived:!1};const s=n.pane??process.env.TMUX_PANE??X()?.pane;if(s===void 0||s==="")return{focused:!1,session:null,inPlace:!1,revived:!1};const u=y(o.pi_pid??null),r=n.revive(e),l=!u;if(!await oe(e,r?.launch?.exited))return{focused:!1,session:null,inPlace:!1,revived:l};const v=h(s)?.session??null,N=v??"";if(n.inPlace===!0){const i=p(e);i!==null&&(i.pane!==null&&i.pane!==s&&d(i.pane)&&P(i.pane),a(i.focus_id));const c=x(s);c!==null&&c.node_id!==e&&a(c.focus_id);try{Y(s,"@crtr_node","")}catch{}const _=I(s),F=c?.node_id,L=F===void 0?W():{...W(),CRTR_ATTACH_ROSTER:F},O=Z({pane:s,cwd:o.cwd,env:L,command:`crtr surface attach to ${e}`});return O&&(_!==null&&ee(_,H(o)),b(e,s,v,_)),{focused:O,session:v,inPlace:!0,revived:l}}if(n.newPane===!0){const i=p(e);i!==null&&(i.pane!==null&&d(i.pane)&&P(i.pane),a(i.focus_id));const c=A(e,N,{cwd:o.cwd,besidePane:s});return c===null?{focused:!1,session:null,inPlace:!1,revived:l}:(c.pane!==null&&B(c.pane),{focused:!0,session:c.session,inPlace:!1,revived:l})}const f=p(e);if(f!==null&&f.pane!==null)if(K(f.pane,"@crtr_node")===e){const i=h(f.pane);if(i!==null)return j(i.session),q(i.session,i.window),S(f.pane),{focused:!0,session:i.session,inPlace:!0,revived:l};a(f.focus_id)}else a(f.focus_id);const w=A(e,N,{cwd:o.cwd,besidePane:s});return w===null?{focused:!1,session:null,inPlace:!1,revived:l}:(w.pane!==null&&B(w.pane),{focused:!0,session:w.session,inPlace:!1,revived:l})}t(he,"focus");function E(e,n){const o=p(e);o!==null&&(o.pane!==null&&o.pane!==n&&d(o.pane)&&P(o.pane),a(o.focus_id))}t(E,"tearDownNode");function ye(e,n){const o=n??p(e)?.pane??null;if(o===null||!d(o))return!1;const s=ie(o);s!==null&&a(s.focus_id);const u=P(o);return le(e),u}t(ye,"detachToBackground");function C(e){const n=m(e);return n===null||n.streaming===!0&&y(n.pi_pid)?!1:!Q(n.pi_session_file)}t(C,"isEmptyNode");function le(e,n,o=!0){return m(e)?.managed_worktree?.state==="open"||!C(e)?!1:(o&&k.teardown(e),E(e,n),R(e).deleted)}t(le,"reapIfEmpty");function ge(e={}){const n=e.dryRun??!1,o=$()??"",s=[];for(const u of M()){const r=u.node_id,l=m(r);r===o||u.status==="dead"||y(u.pi_pid)||l?.managed_worktree?.state==="open"||!C(r)||!n&&(U(r,"notice.close",`Child closed \u2014 ${l?.name??r} (${r}) was closed from the canvas and is no longer running.`,{reason:"child-closed",child:r}),k.teardown(r),E(r),!R(r).deleted)||s.push(r)}return s}t(ge,"reapEmptyNodes");export{Re as breakPane,Xe as closePane,$e as currentTmux,ye as detachToBackground,je as displayPopup,Be as ensureSession,he as focus,ie as focusByPane,p as focusOf,Se as focusWindow,xe as focusedNodes,De as getPaneOption,He as inTmux,nn as installTmuxBindings,_e as isFocused,te as listFocuses,Ze as listLivePanes,Ie as listLivePanesAsync,Ae as openNodeWindow,A as openViewerWindow,Ve as paneCurrentPath,Ce as paneExists,Ee as paneLocation,Me as paneOfNode,Ke as paneOfWindow,Le as paneRunning,Je as piCommand,ge as reapEmptyNodes,le as reapIfEmpty,b as registerViewerFocus,Ge as renameWindow,Ue as respawnPaneSync,Te as selectLayout,ke as selectPane,We as selectWindow,ze as setPaneOption,Qe as shellQuote,Oe as splitWindow,be as switchClient,E as tearDownNode,Ye as windowAlive,qe as windowOfPane};

package/dist/core/runtime/progress-bar.d.ts

@@ -0,0 +1,13 @@
+/** A running progress bar line. `setFraction` fills it from a real count;
+ *  leaving it unset keeps the indeterminate slider. `stop` erases the line and
+ *  resolves once the painter has released the terminal, so the caller can
+ *  write its own outcome line without interleaving. */
+export interface ProgressBar {
+    setFraction(fraction: number): void;
+    stop(): Promise<void>;
+}
+/** Start an animated bar on `stream`, drawn by a child process so it keeps
+ *  moving while this process blocks inside the step it describes. */
+export declare function startProgressBar(label: string, stream?: NodeJS.WriteStream & {
+    fd: number;
+}): ProgressBar;

package/dist/core/runtime/progress-bar.js

@@ -0,0 +1,2 @@
+var p=Object.defineProperty;var n=(o,e)=>p(o,"name",{value:e,configurable:!0});import{spawn as f}from"node:child_process";import{dirname as m,join as d}from"node:path";import{assetRoot as u}from"../asset-root.js";const s={setFraction(){},stop:n(async()=>{},"stop")};function l(){return d(m(u()),"bin","progress-painter.mjs")}n(l,"painterPath");function b(o,e=process.stdout){if(!e.isTTY)return s;let t;try{t=f(process.execPath,[l(),o],{stdio:["pipe",e.fd,"ignore"]})}catch{return s}let i=!0;t.stdin?.on("error",()=>{i=!1});const a=new Promise(r=>{t.once("exit",()=>{i=!1,r()}),t.once("error",()=>{i=!1,r()})});return{setFraction(r){i&&t.stdin?.write(`${Math.min(1,Math.max(0,r))}
+`)},async stop(){i&&t.stdin?.end();const r=new Promise(c=>setTimeout(()=>{t.kill("SIGKILL"),c()},1e3).unref());await Promise.race([a,r]),e.write("\r\x1B[2K\x1B[?25h")}}}n(b,"startProgressBar");export{b as startProgressBar};