@north-light/cli 0.0.0 → 0.3.414

package/dist/core/runtime/boot-root.d.ts

@@ -0,0 +1,34 @@
+import { cliClient } from '../../commands/api-client.js';
+export interface BootRootOpts {
+    cwd: string;
+    kind?: string;
+    name?: string;
+    /** Optional starter prompt (bare `crtr` requires none). */
+    prompt?: string;
+    /** Whether the viewer plays the initial-whip animation for `prompt`. Defaults
+     * to "the prompt is non-empty"; the front door passes false for a prompt the
+     * runtime produced rather than the user typing it. */
+    initialWhip?: boolean;
+    /** Explicit `--profile <id-or-name>` on the front-door invocation, resolved
+     *  through `resolveProfileOperand` — so a near-miss name still starts the
+     *  session, under the closest profile. Omit to run the MRU/create-or-root-profile
+     *  startup selector for `cwd` (see `selectProfileForCwd`) — a root has no
+     *  spawner to inherit from, so this is the front door's only source of profile
+     *  identity. */
+    profile?: string | null;
+    /** Profile already selected by the front door before its credential gate. */
+    selectedProfileId?: string;
+    /** `crtr --pick-profile`: force the startup profile chooser to open even when
+     *  a per-cwd default is pinned, so the user can re-pin or unpin it. Without
+     *  this a pinned default auto-picks silently (that is what "default" means). */
+    pickProfile?: boolean;
+}
+/** The root-create request the front door sends to crtrd. */
+export declare function rootCreateRequest(opts: BootRootOpts, profileId: string): Parameters<ReturnType<typeof cliClient>['createNode']>[0];
+/** Boot the front-door root: create the resident root through crtrd (broker
+ *  launched + view socket ready server-side), register THIS terminal's pane as
+ *  its foreground viewer, then exec `crtr surface attach` inline so this terminal
+ *  becomes a writable viewer. Does not return — it process.exit()s
+ *  when the inline attach exits (detach leaves the resident broker running, to
+ *  be reconnected later). */
+export declare function bootRoot(opts: BootRootOpts): Promise<never>;

package/dist/core/runtime/boot-root.js

@@ -0,0 +1,5 @@
+var w=Object.defineProperty;var d=(e,o)=>w(e,"name",{value:o,configurable:!0});import{spawn as l}from"node:child_process";import{inTmux as u,currentTmux as _,viewerSplitEnv as T}from"./placement-tmux.js";import{selectProfileForCwd as x}from"../profiles/select.js";import{cliClient as p}from"../../commands/api-client.js";import{mark as c}from"../timing.js";import{printComeBackNote as C}from"./come-back-note.js";function h(e,o){const t=e.kind;return{...t!==void 0?{kind:t}:{},mode:"base",prompt:e.prompt,profile:o,cwd:e.cwd,...e.name!==void 0?{name:e.name}:t!==void 0?{name:t}:{},root:!0,prefer_warm:!0}}d(h,"rootCreateRequest");async function E(e){if(!u()){const n=process.stderr.isTTY?i=>`\x1B[1;33m${i}\x1B[0m`:i=>i;process.stderr.write(`
+${n("crtr must be started from inside a tmux session.")}
+${n("Start tmux first, e.g.  tmux new -s work  \u2014 then run crtr there.")}
+
+`),process.exit(1)}c("boot_root.start");const o=e.selectedProfileId??await x(e.cwd,e.profile,e.pickProfile??!1);c("boot_root.profile_resolved");const a=(await p().createNode(h(e,o))).node_id;c("boot_root.node_created",{node:a});const r=_();if(r!==null)try{await p().registerFocus({node_id:a,pane:r.pane,session:r.session,window:r.window})}catch{}const s={...process.env,...T(),CRTR_ATTACH_WAIT_MS:"30000",...e.initialWhip??(e.prompt!==void 0&&e.prompt!=="")?{CRTR_ATTACH_INITIAL_WHIP:"1"}:{}};r!==null&&(s.CRTR_ATTACH_BORROWED_PANE=r.pane),c("boot_root.viewer_spawn");const m=l("crtr",["surface","attach","to",a],{stdio:"inherit",env:s}),f=await new Promise(n=>{m.once("exit",i=>n(i??0)),m.once("error",()=>n(1))});await C(a,f),process.exit(f)}d(E,"bootRoot");export{E as bootRoot,h as rootCreateRequest};

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

@@ -0,0 +1,55 @@
+/** Machine-global host dir in this process owner’s HOME. Only the daemon reconciles it; agents do not install the branded host. Deliberately NOT under `CRTR_HOME` (tests override
+ *  that to an isolated temp): the branded binary is a per-machine artifact keyed
+ *  to the installed node, shared across every canvas home. */
+export declare function brandedHostDir(): string;
+export declare function brandedHostBin(): string;
+/** macOS keys FDA grants on the Mach-O cdhash. A real developer identity
+ *  keeps that hash stable across branded-host rebuilds; ad-hoc signing is the
+ *  portable default for machines without a local signing certificate. */
+export declare function codesignIdentitiesForBrandedHost(opts?: {
+    configured?: string | null;
+    discovered?: string | null;
+}): string[];
+export declare function signBrandedHostArtifacts(binPath: string, libnodePath: string | null, sign?: (path: string) => void): void;
+export declare function brandedHostWorks(binPath: string, timeoutMs?: number): boolean;
+/** Ensure the branded host binary exists and matches the live node; return its
+ *  absolute path. Idempotent and self-healing. Throws on a genuine build failure
+ *  (disk full / permissions); hostExecPath() turns that into a logged fallback to
+ *  a real node so a broken host never blocks launching. */
+export declare function ensureBrandedHost(opts?: {
+    execPath?: string;
+}): string;
+/** Find a working, ABI-compatible, non-branded `node` to rebuild from. Blocking:
+ *  for CLI / explicit reconcile only, never the daemon's event loop (use
+ *  findRealNodeAsync there). Returns null when none works. */
+export declare function findRealNode(): string | null;
+/** Non-blocking findRealNode for the daemon's event loop. */
+export declare function findRealNodeAsync(): Promise<string | null>;
+/** Forget remembered host health (tests). */
+export declare function resetBrandedHostHealthCache(): void;
+/** The node to exec for a short-lived helper child (forked worker, bash
+ *  supervisor, probe). Outside the branded host this is `process.execPath`
+ *  untouched. Inside it, a host that no longer starts (dyld cannot resolve a
+ *  moved Homebrew dependency) would abort every child, so a real node is used
+ *  instead. Never blocks: it returns the last known answer and refreshes it in
+ *  the background. A fork that still dies calls recheckChildNode() to learn the
+ *  truth at once. */
+export declare function childNodeExecPath(execPath?: string): string;
+/** Re-probe the host now (after a child died) and return the node to retry on;
+ *  equals `execPath` when the host is fine or no real node exists. */
+export declare function recheckChildNode(execPath?: string): Promise<string>;
+/** Like childNodeExecPath(), but first awaits a probe no older than `maxAgeMs`
+ *  (coalesced with any probe in flight). Use it right before a fork whose death
+ *  would lose work (a broker, a bash job, the inventory child) so a host broken
+ *  since the last probe is caught before the exec, not after. The probe is a
+ *  non-blocking `node -e ''`; outside the branded host this costs nothing. */
+export declare function freshChildNodeExecPath(execPath?: string, maxAgeMs?: number): Promise<string>;
+/** hostExecPath() for async launchers: inside the host it is verified fresh
+ *  rather than taken from the cache. */
+export declare function hostExecPathFresh(): Promise<string>;
+/** The path the engine (broker / daemon) should be launched from. On macOS in a
+ * compiled (production) build this is the validated branded host; otherwise —
+ * non-darwin (TCC is macOS-only), source/tsx (dev + the test suite: never copy
+ * 70 MB into the real ~/.crouter), or the explicit `CRTR_BRANDED_HOST=0`
+ * opt-out — it is the live node. */
+export declare function hostExecPath(): string;

package/dist/core/runtime/branded-host.js

@@ -0,0 +1,2 @@
+var J=Object.defineProperty;var r=(e,n)=>J(e,"name",{value:n,configurable:!0});import{copyFileSync as G,mkdirSync as g,existsSync as w,readFileSync as K,writeFileSync as D,chmodSync as U,readdirSync as V,renameSync as d,realpathSync as y,unlinkSync as Y,rmSync as q,linkSync as R}from"node:fs";import{homedir as $}from"node:os";import{dirname as C,join as s}from"node:path";import{execFile as z,spawn as Q,spawnSync as v}from"node:child_process";import{CRTR_DIR_NAME as M}from"../../types.js";import{emitEvent as x}from"../events/emit.js";import{withExclusiveDirectoryLock as X}from"../exclusive-lock.js";const S="crouter";function p(){return s($(),M,"host")}r(p,"brandedHostDir");function I(){return s(p(),S)}r(I,"brandedHostBin");function H(){return s(p(),".source.json")}r(H,"markerPath");function Z(e){const n=C(e);for(const t of[n,s(n,"..","lib")]){if(!w(t))continue;const o=V(t).find(c=>c.startsWith("libnode.")&&c.endsWith(".dylib"));if(o!==void 0)return s(t,o)}return null}r(Z,"findLibnode");function O(e,n,t){const o=`${n}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;G(e,o),t!==void 0&&U(o,t),d(o,n)}r(O,"atomicCopy");function k(e=H()){try{return JSON.parse(K(e,"utf8"))}catch{return null}}r(k,"readMarker");const ee=3e4;function te(e){const n=s($(),M),t=s(n,"host.lock");return g(n,{recursive:!0}),X(t,e,{timeoutMs:ee,timeoutError:r(()=>new Error(`timed out waiting for branded host lock: ${t}`),"timeoutError")})}r(te,"withBrandedHostLock");function ne(e={}){const n=e.configured?.trim();return n?[n]:[e.discovered?.trim()||"-"]}r(ne,"codesignIdentitiesForBrandedHost");function re(){if(process.platform!=="darwin")return null;const e=v("security",["find-identity","-v","-p","codesigning"],{stdio:["pipe","pipe","pipe"]});if(e.status!==0)return null;const t=(e.stdout??"").toString().split(`
+`).map(o=>o.match(/\)\s+[A-Fa-f0-9]{40}\s+"([^"]+)"/)?.[1]??null).filter(o=>o!==null);return t.find(o=>o.startsWith("Apple Development:"))??t.find(o=>o.startsWith("Developer ID Application:"))??t[0]??null}r(re,"discoverCodesignIdentity");function oe(e,n){const t=v("codesign",["-s",n,"--deep","--force",e],{stdio:["pipe","pipe","pipe"]});return{ok:t.status===0,stderr:(t.stderr??"").toString().trim()}}r(oe,"runCodesign");function ie(e){if(process.platform!=="darwin")return;const n=ne({configured:process.env.CRTR_CODESIGN_IDENTITY,discovered:re()});let t="";for(const o of n){const c=oe(e,o);if(c.ok)return;t=c.stderr}throw t&&!t.includes("valid on disk")&&x({event:"host.codesign.failed",level:"debug",error:t}),new Error(`codesign failed for ${e}: ${t||"codesign did not exit successfully"}`)}r(ie,"signBrandedHost");function se(e,n,t=ie){n!==null&&t(n),t(e)}r(se,"signBrandedHostArtifacts");function h(e,n=5e3){try{return v(e,["-e",""],{stdio:"ignore",timeout:n}).status===0}catch{return!1}}r(h,"brandedHostWorks");function ce(e={}){return te(()=>{const n=p(),t=I();let o=y(e.execPath??process.execPath);if(w(t)&&y(t)===o){if(h(t))return t;const l=ae();if(l===null)throw new Error(`branded host cannot start and no working node was found to rebuild it from: ${t}`);o=l}const c=k(),u=Z(o),f=u!==null?u.split("/").pop():null,_=r(l=>w(t)&&l!==null&&l.version===2&&(l.libnode===null||w(s(n,l.libnode))),"tupleExists"),A=r(l=>_(l)&&l.source===o&&l.libnode===f,"tupleMatches");if(A(c)&&h(t))return t;g(n,{recursive:!0});const m=s(n,`.reconcile.${process.pid}.${Math.random().toString(36).slice(2)}`),T=s(m,"previous");g(m);let N=!1;const B=_(c)&&h(t);try{const l=s(m,S),b=f!==null?s(m,f):null;if(u!==null&&b!==null&&O(u,b),O(o,l,493),se(l,b),!h(l))throw new Error(`rebuilt branded host failed its startup check: ${l}`);if(B&&ue(T,t,c),N=!0,b!==null&&d(b,s(n,f)),d(l,t),le({version:2,source:o,libnode:f}),!A(k())||!h(t))throw new Error(`published branded host tuple failed validation: ${t}`);if(c?.libnode!=null&&c.libnode!==f)try{Y(s(n,c.libnode))}catch{}return t}catch(l){throw N&&B&&de(T,t,c),l}finally{q(m,{recursive:!0,force:!0})}})}r(ce,"ensureBrandedHost");function le(e){const n=H(),t=`${n}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;D(t,JSON.stringify(e)),d(t,n)}r(le,"atomicCopyMarker");function ue(e,n,t){g(e),R(n,s(e,S)),t.libnode!==null&&R(s(p(),t.libnode),s(e,t.libnode)),D(s(e,".source.json"),JSON.stringify(t))}r(ue,"backupHostTuple");function de(e,n,t){if(t.libnode!==null&&d(s(e,t.libnode),s(p(),t.libnode)),d(s(e,S),n),d(s(e,".source.json"),H()),!h(n))throw new Error(`failed to restore previous branded host tuple: ${n}`)}r(de,"restoreHostTuple");function a(e){try{const n=y(p());return C(y(e))===n}catch{return!1}}r(a,"isBrandedHostExec");function P(){const e=["/opt/homebrew/bin/node","/usr/local/bin/node"];a(process.execPath)||e.push(process.execPath);for(const c of(process.env.PATH??"").split(":"))c!==""&&e.push(s(c,"node"));const n=k();n!==null&&typeof n.source=="string"&&e.push(n.source);const t=new Set,o=[];for(const c of e){let u;try{u=y(c)}catch{continue}t.has(u)||a(u)||(t.add(u),o.push(u))}return o}r(P,"realNodeCandidates");const L=["-p","process.versions.modules"];function F(e){return e!==null&&e.trim()===process.versions.modules}r(F,"abiMatches");function ae(){for(const e of P())try{const n=v(e,L,{encoding:"utf8",timeout:5e3,stdio:["ignore","pipe","ignore"]});if(n.status===0&&F(n.stdout))return e}catch{}return null}r(ae,"findRealNode");function W(e,n,t){return new Promise(o=>{try{z(e,n,{encoding:"utf8",timeout:t},(c,u)=>o(c===null?u:null))}catch{o(null)}})}r(W,"execFileProbe");async function fe(){for(const e of P())if(F(await W(e,L,5e3)))return e;return null}r(fe,"findRealNodeAsync");const pe=15e3,he=6e4,i={checkedAt:0,fallback:null,probing:null,lastHealAt:0};function _e(){i.checkedAt=0,i.fallback=null,i.probing=null,i.lastHealAt=0}r(_e,"resetBrandedHostHealthCache");function me(e){if(import.meta.url.endsWith(".ts"))return;const n=Date.now();if(!(n-i.lastHealAt<he)){i.lastHealAt=n;try{const t=`import(${JSON.stringify(import.meta.url)}).then((m) => m.ensureBrandedHost())`,o=Q(e,["--input-type=module","-e",t],{detached:!0,stdio:"ignore"});o.on("error",()=>{}),o.unref()}catch{}}}r(me,"healBrandedHostInBackground");function E(e){return i.probing!==null||(i.probing=(async()=>{try{if(await W(e,["-e",""],5e3)!==null){i.fallback=null;return}const n=await fe();n!==i.fallback&&n!==null&&x({event:"host.fallback.node",level:"warn",fields:{host:e,node:n}}),i.fallback=n,n!==null&&me(n)}finally{i.checkedAt=Date.now(),i.probing=null}})()),i.probing}r(E,"refreshHostHealth");function be(e=process.execPath){return a(e)?(Date.now()-i.checkedAt>pe&&i.probing===null&&E(e),i.fallback??e):e}r(be,"childNodeExecPath");async function Ae(e=process.execPath){return a(e)?(await E(e),i.fallback??e):e}r(Ae,"recheckChildNode");async function ye(e=process.execPath,n=1e3){return a(e)?(i.probing===null&&Date.now()-i.checkedAt>=n?await E(e):i.probing!==null&&await i.probing,i.fallback??e):e}r(ye,"freshChildNodeExecPath");async function Te(){return process.env.CRTR_BRANDED_HOST==="0"||process.platform!=="darwin"||import.meta.url.endsWith(".ts")?j():a(process.execPath)?ye():j()}r(Te,"hostExecPathFresh");function j(){if(process.env.CRTR_BRANDED_HOST==="0"||process.platform!=="darwin"||import.meta.url.endsWith(".ts"))return process.execPath;if(a(process.execPath))return be();try{return ce()}catch(e){return x({event:"host.fallback.node",level:"warn",error:e,fields:{host:I(),node:process.execPath}}),process.execPath}}r(j,"hostExecPath");export{I as brandedHostBin,p as brandedHostDir,h as brandedHostWorks,be as childNodeExecPath,ne as codesignIdentitiesForBrandedHost,ce as ensureBrandedHost,ae as findRealNode,fe as findRealNodeAsync,ye as freshChildNodeExecPath,j as hostExecPath,Te as hostExecPathFresh,Ae as recheckChildNode,_e as resetBrandedHostHealthCache,se as signBrandedHostArtifacts};

package/dist/core/runtime/broker/cli-relay.d.ts

@@ -0,0 +1,5 @@
+/** The broker alone holds the bearer. CLI processes see only this socket path. */
+export declare function serveCliRelay(nodeId: string, token: string): Promise<{
+    path: string;
+    close(): void;
+}>;

package/dist/core/runtime/broker/cli-relay.js

@@ -0,0 +1 @@
+var m=Object.defineProperty;var d=(s,n)=>m(s,"name",{value:n,configurable:!0});import{createServer as h,request as f}from"node:http";import{chmodSync as y,existsSync as l,unlinkSync as p}from"node:fs";import{join as S}from"node:path";import{apiSocketPath as u,nodeRunDir as k}from"../../canvas/paths.js";async function H(s,n){const r=S(k(s),"cli.sock"),o=h((t,e)=>{const i={...t.headers,authorization:`Bearer ${n}`};delete i.connection;const c=f({socketPath:u(),path:t.url,method:t.method,headers:i},a=>{e.writeHead(a.statusCode??502,a.headers),a.pipe(e)});c.on("error",a=>{e.headersSent||e.writeHead(503,{"content-type":"application/json"}),e.end(JSON.stringify({error:{code:"daemon_unavailable",message:a.message}}))}),t.pipe(c),e.on("close",()=>c.destroy())});return l(r)&&p(r),await new Promise((t,e)=>{o.once("error",e),o.listen(r,()=>{o.off("error",e),t()})}),y(r,384),{path:r,close(){o.closeAllConnections(),o.close(),l(r)&&p(r)}}}d(H,"serveCliRelay");export{H as serveCliRelay};

package/dist/core/runtime/broker/client-registry.d.ts

@@ -0,0 +1,36 @@
+import type { Socket } from 'node:net';
+import { FrameDecoder, type BrokerSnapshot, type BrokerToClient, type ClientRole } from '../broker-protocol.js';
+export interface BrokerClient {
+    id: string;
+    role: ClientRole;
+    socket: Socket;
+    decoder: FrameDecoder;
+    helloed: boolean;
+    /** Fixed by the first hello; absent `attends` remains backward-compatible true. */
+    attends: boolean;
+    snapshotTail: number | undefined;
+    pendingBytes: number;
+    queuedFrames: number;
+}
+/** Owns connected viewers, their outbound backpressure, and durable attach presence. */
+export declare class BrokerClientRegistry {
+    private readonly nodeId;
+    private readonly attachPath;
+    private readonly clients;
+    private readonly displayStatuses;
+    private readonly displayWidgets;
+    private displayTitle;
+    constructor(nodeId: string);
+    create(socket: Socket): BrokerClient;
+    writableClients(): BrokerClient[];
+    persistAttachState(): void;
+    dropClient(client: BrokerClient, reason: string): void;
+    removeClient(client: BrokerClient): void;
+    sendFrame(client: BrokerClient, frame: BrokerToClient, bypassHwm?: boolean): void;
+    broadcast(frame: BrokerToClient): void;
+    broadcastUi(frame: BrokerToClient): void;
+    displaySnapshot(): BrokerSnapshot['display'];
+    forEachHelloed(fn: (client: BrokerClient) => void): void;
+    dispose(): void;
+    clearAttachState(): void;
+}

package/dist/core/runtime/broker/client-registry.js

@@ -0,0 +1 @@
+var l=Object.defineProperty;var o=(d,e)=>l(d,"name",{value:e,configurable:!0});import{existsSync as r,mkdirSync as c,unlinkSync as h,writeFileSync as u}from"node:fs";import{nodeRunJobDir as a}from"../../canvas/paths.js";import{emitEvent as p}from"../../events/emit.js";import{encodeFrame as y,FrameDecoder as f,BROKER_READ_CAPS as g}from"../broker-protocol.js";const m=1e3,S=32*1024*1024;class B{static{o(this,"BrokerClientRegistry")}nodeId;attachPath;clients=new Set;displayStatuses=new Map;displayWidgets=new Map;displayTitle;constructor(e){this.nodeId=e,this.attachPath=`${a(e)}/attach.json`}create(e){const t={id:"",role:"observer",socket:e,decoder:new f(g),helloed:!1,attends:!0,snapshotTail:void 0,pendingBytes:0,queuedFrames:0};return this.clients.add(t),t}writableClients(){const e=[];for(const t of this.clients)!t.helloed||t.role!=="controller"||t.socket.destroyed||t.socket.readableEnded||!t.socket.writable||e.push(t);return e}persistAttachState(){try{let e=0;for(const s of this.clients)s.helloed&&s.attends&&(e+=1);const t=a(this.nodeId);r(t)||c(t,{recursive:!0}),u(this.attachPath,JSON.stringify({viewers:e,updated:new Date().toISOString()},null,2),"utf8")}catch{}}dropClient(e,t){if(this.clients.has(e)){p({level:"info",event:"broker.runtime.diagnostic",fields:{message:`dropping viewer ${e.id||"(pre-hello)"} \u2014 ${t}`}}),this.removeClient(e);try{e.socket.destroy()}catch{}}}removeClient(e){this.clients.delete(e),this.persistAttachState()}sendFrame(e,t,s=!1){let n;try{n=y(t)}catch{return}const i=Buffer.byteLength(n);if(!s&&(e.queuedFrames+1>m||e.pendingBytes+i>S)){this.dropClient(e,`backpressure high-water mark exceeded (queued=${e.queuedFrames}, pending=${e.pendingBytes}B)`);return}e.queuedFrames+=1,e.pendingBytes+=i;try{e.socket.write(n,()=>{e.queuedFrames-=1,e.pendingBytes-=i})}catch{e.queuedFrames-=1,e.pendingBytes-=i}}broadcast(e){for(const t of this.clients)t.helloed&&this.sendFrame(t,e)}broadcastUi(e){e.type==="extension_ui_request"&&(e.method==="setStatus"?(this.displayStatuses.delete(e.statusKey),e.statusText!==void 0&&this.displayStatuses.set(e.statusKey,e.statusText)):e.method==="setWidget"?(this.displayWidgets.delete(e.widgetKey),e.widgetLines!==void 0&&this.displayWidgets.set(e.widgetKey,{lines:[...e.widgetLines],placement:e.widgetPlacement??"aboveEditor"})):e.method==="setTitle"&&(this.displayTitle=e.title)),this.broadcast(e)}displaySnapshot(){return{statuses:Object.fromEntries(this.displayStatuses),widgets:Object.fromEntries([...this.displayWidgets].map(([e,t])=>[e,{lines:[...t.lines],placement:t.placement}])),title:this.displayTitle}}forEachHelloed(e){for(const t of this.clients)t.helloed&&e(t)}dispose(){for(const e of this.clients)try{e.socket.destroy()}catch{}this.clients.clear()}clearAttachState(){try{r(this.attachPath)&&h(this.attachPath)}catch{}}}export{B as BrokerClientRegistry};

package/dist/core/runtime/broker/daemon-ops.d.ts

@@ -0,0 +1,65 @@
+import { type BrokerSignalCachedNode } from '../../../daemon/broker-signals/bus.js';
+import type { BrokerExtensionStateDTO, BrokerGeneratedNameRequest, BrokerGeneratedNameResultDTO, BrokerModelCommitRequest, BrokerModelCommitResultDTO, BrokerParkActivityResultDTO, BrokerParkCompleteRequest, BrokerPersonaAckRequest, BrokerPersonaAckResultDTO, BrokerSessionBoundRequest, BrokerSessionBoundResultDTO, BrokerSettleDirective, BrokerSettleRequest, BrokerTelemetryRequest } from '../../../api/dto/broker-ops.js';
+import type { AcknowledgeMailResultDTO, ClaimMailResultDTO, MailReceiptDTO } from '../../../api/dto/mail.js';
+import type { BrokerFaultInputDTO, BrokerFaultRequest, BrokerFaultResultDTO, BrokerProviderRetryRequest, BrokerProviderRetryResultDTO, BrokerTurnRequest, BrokerTurnResultDTO, RecoveryStateDTO } from '../../../api/dto/recovery.js';
+import type { RelaunchRootResultDTO } from '../../../api/dto/lifecycle.js';
+import type { PushReportRequest } from '../../../api/dto/reports.js';
+import type { BackgroundedJobDTO, BackgroundedJobRequest, DeliveryRequest, DeliveryResponse } from '../../../api/dto/delivery.js';
+import type { NodeLogAppendResultDTO, NodeMessageBodyDTO, NodePushedFinalResultDTO, NodeTelemetryRecordRequest } from '../../../api/dto/node-records.js';
+export declare function appendBrokerLog(nodeId: string, record: string): Promise<NodeLogAppendResultDTO>;
+export declare function putBrokerTelemetry(nodeId: string, telemetry: Omit<NodeTelemetryRecordRequest, 'expected_execution_id'>): Promise<void>;
+export declare function putBrokerRecap(nodeId: string, briefing: string): Promise<void>;
+/** The body of a direct message the daemon spilled into this node's records. */
+export declare function readBrokerPassiveMessage(nodeId: string, ref: string): Promise<NodeMessageBodyDTO>;
+export declare function clearBrokerPushedFinal(nodeId: string): Promise<NodePushedFinalResultDTO>;
+export declare function consumeBrokerPushedFinal(nodeId: string): Promise<NodePushedFinalResultDTO>;
+export declare function startBrokerBashJob(nodeId: string, request: {
+    job_id: string;
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}): Promise<{
+    pid: number;
+}>;
+/** Record a command the valve just backgrounded as this node's job object. */
+export declare function recordBackgroundedJob(nodeId: string, jobId: string, request: BackgroundedJobRequest): Promise<BackgroundedJobDTO>;
+export declare function stopBrokerBashJob(nodeId: string, jobId: string): Promise<void>;
+export declare function brokerExecutionId(): string;
+export declare function bindBrokerSession(nodeId: string, request: Omit<BrokerSessionBoundRequest, 'executionId'>): Promise<BrokerSessionBoundResultDTO>;
+type BrokerInput<T> = T extends unknown ? Omit<T, 'expected_execution_id'> : never;
+export declare function settleBroker(nodeId: string, request: BrokerInput<BrokerSettleRequest>): Promise<BrokerSettleDirective>;
+export declare function completeBrokerPark(nodeId: string, request: BrokerInput<BrokerParkCompleteRequest>): Promise<BrokerSettleDirective>;
+export declare function recordBrokerParkActivity(nodeId: string): Promise<BrokerParkActivityResultDTO>;
+export declare function recordBrokerTelemetry(nodeId: string, request: Omit<BrokerTelemetryRequest, 'expected_execution_id'>): Promise<void>;
+export declare function claimBrokerMail(nodeId: string, channel: 'wake' | 'passive' | 'deferred_run', reportBodies: Map<string, Promise<string>>): Promise<ClaimMailResultDTO>;
+export declare function acknowledgeBrokerMail(nodeId: string, deliveries: MailReceiptDTO[]): Promise<AcknowledgeMailResultDTO>;
+export declare function recordBrokerTurn(nodeId: string, request: Omit<BrokerTurnRequest, 'expected_execution_id'>): Promise<BrokerTurnResultDTO>;
+export declare function mutateBrokerProviderRetry(nodeId: string, request: Omit<BrokerProviderRetryRequest, 'expected_execution_id'>): Promise<BrokerProviderRetryResultDTO>;
+export declare function mutateBrokerFault(nodeId: string, request: Omit<BrokerFaultRequest, 'expected_execution_id'>): Promise<BrokerFaultResultDTO>;
+export declare function brokerRecovery(nodeId: string): Promise<RecoveryStateDTO>;
+/** Node-scoped fault writes are for non-broker clients such as attach transport.
+ * Broker-owned recovery mutations use the execution-fenced wrappers above. */
+export declare function recordNodeFault(nodeId: string, input: BrokerFaultInputDTO): Promise<BrokerFaultResultDTO>;
+export declare function clearNodeFault(nodeId: string, opts?: {
+    link?: BrokerFaultInputDTO['link'];
+    preserveEpisode?: boolean;
+}): Promise<boolean>;
+/** Fixed canvas projection for broker extension rendering. It deliberately
+ * exposes no generic node/database facade. */
+export declare function commitBrokerModel(nodeId: string, request: BrokerInput<BrokerModelCommitRequest>): Promise<BrokerModelCommitResultDTO>;
+export declare function brokerExtensionState(nodeId: string): Promise<BrokerExtensionStateDTO>;
+/** Only node-owned fields are cached. A disconnected or stopped stream cannot
+ * guarantee freshness, so events at those boundaries read the daemon instead. */
+export declare function cachedBrokerNode(nodeId: string): Promise<BrokerSignalCachedNode>;
+/** The node's one delivery route: every rule-driven document delivery the
+ *  broker applies, recorded by crtrd in the same request. */
+export declare function brokerDelivery(nodeId: string, request: BrokerInput<DeliveryRequest>): Promise<DeliveryResponse>;
+export declare function commitBrokerGeneratedName(nodeId: string, request: BrokerInput<BrokerGeneratedNameRequest>): Promise<BrokerGeneratedNameResultDTO>;
+export declare function commitBrokerPersonaAck(nodeId: string, request: BrokerInput<BrokerPersonaAckRequest>): Promise<BrokerPersonaAckResultDTO>;
+/** Reports still use the canonical daemon report handler; this broker adapter
+ * only preserves terminal structured output's idempotent finalization result. */
+export declare function publishBrokerReport(nodeId: string, request: PushReportRequest): Promise<void>;
+/** Root `/new` remains on the dedicated relaunch operation because it launches
+ * a replacement broker and tears down this broker. Callers must not await it
+ * from Pi's session-start dispatch. */
+export declare function relaunchBrokerRoot(nodeId: string): Promise<RelaunchRootResultDTO>;
+export {};

package/dist/core/runtime/broker/daemon-ops.js

@@ -0,0 +1 @@
+var _=Object.defineProperty;var t=(e,r)=>_(e,"name",{value:r,configurable:!0});import{localClient as B}from"../../../api/node-transport.js";import{ApiError as s}from"../../../api/errors.js";import{envExecutionId as h}from"../../../shared/env.js";import{brokerSignalClient as y}from"./signal-stream.js";import{cachedBrokerNodeFields as l}from"../../../daemon/broker-signals/bus.js";import{reportRefNodeId as N}from"../../../shared/inbox-entry-body.js";function o(){return B({autostart:!1})}t(o,"daemonClient");function I(e,r){return o().appendNodeLog(e,{record:r,expected_execution_id:n()})}t(I,"appendBrokerLog");function T(e,r){return o().putNodeTelemetry(e,{...r,expected_execution_id:n()})}t(T,"putBrokerTelemetry");function C(e,r){return o().putNodeRecap(e,{briefing:r,expected_execution_id:n()})}t(C,"putBrokerRecap");function M(e,r){return o().readNodePassiveMessage(e,r)}t(M,"readBrokerPassiveMessage");function S(e){return o().nodePushedFinal(e,{action:"clear",expected_execution_id:n()})}t(S,"clearBrokerPushedFinal");function A(e){return o().nodePushedFinal(e,{action:"consume",expected_execution_id:n()})}t(A,"consumeBrokerPushedFinal");function D(e,r){return o().request("POST",`/v1/nodes/${encodeURIComponent(e)}/jobs/start`,{...r,expected_execution_id:n()})}t(D,"startBrokerBashJob");function J(e,r,i){return o().recordBackgroundedJob(e,r,i)}t(J,"recordBackgroundedJob");function U(e,r){return o().request("DELETE",`/v1/nodes/${encodeURIComponent(e)}/jobs/${encodeURIComponent(r)}?foreground=1`,{expected_execution_id:n()})}t(U,"stopBrokerBashJob");function n(){const e=h();if(e===void 0||e==="")throw new Error("broker launch is missing CRTR_EXECUTION_ID");return e}t(n,"brokerExecutionId");function L(e,r){return o().bindBrokerSession(e,{...r,executionId:n()})}t(L,"bindBrokerSession");function $(e,r){return o().settleBroker(e,{...r,expected_execution_id:n()})}t($,"settleBroker");function j(e,r){return o().completeBrokerPark(e,{...r,expected_execution_id:n()})}t(j,"completeBrokerPark");function G(e){return o().recordBrokerParkActivity(e,{expected_execution_id:n()})}t(G,"recordBrokerParkActivity");function O(e,r){return o().recordBrokerTelemetry(e,{...r,expected_execution_id:n()})}t(O,"recordBrokerTelemetry");async function q(e,r,i){const x=o(),f=n(),a=await x.claimNodeMail(e,{execution_id:f,channel:r});if(a.action==="hold")return a;const p=await Promise.all(a.deliveries.map(async u=>{const c=u.entry.ref;if(c===void 0||N(c)===void 0)return u;try{let d=i.get(c);d===void 0&&(d=x.readNodeInboxReport(e,c,f).then(({content:m})=>m),i.set(c,d));const k=await d;return{...u,entry:{...u.entry,data:{...u.entry.data,report_body:k}}}}catch(d){if(i.delete(c),d instanceof s&&d.status===404)return u;throw d}}));if(p.length>0){const u=new Set(p.map(({entry:c})=>c.ref).filter(c=>c!==void 0));for(const c of i.keys())u.has(c)||i.delete(c)}return{...a,deliveries:p}}t(q,"claimBrokerMail");function z(e,r){return o().acknowledgeNodeMail(e,{execution_id:n(),deliveries:r})}t(z,"acknowledgeBrokerMail");function X(e,r){return o().recordBrokerTurn(e,{...r,expected_execution_id:n()})}t(X,"recordBrokerTurn");function H(e,r){return o().mutateBrokerProviderRetry(e,{...r,expected_execution_id:n()})}t(H,"mutateBrokerProviderRetry");function K(e,r){return o().mutateBrokerFault(e,{...r,expected_execution_id:n()})}t(K,"mutateBrokerFault");function Q(e){return o().getBrokerRecovery(e,n())}t(Q,"brokerRecovery");function V(e,r){return o().recordNodeFault(e,r)}t(V,"recordNodeFault");function W(e,r={}){return o().clearNodeFault(e,{...r.link===void 0?{}:{link:r.link},...r.preserveEpisode===void 0?{}:{preserve_episode:r.preserveEpisode}}).then(i=>i.cleared)}t(W,"clearNodeFault");function Y(e,r){return o().commitBrokerModel(e,{...r,expected_execution_id:n()})}t(Y,"commitBrokerModel");function b(e){return o().brokerExtensionState(e)}t(b,"brokerExtensionState");async function Z(e){const r=y();return r.state==="connected"&&r.latestNode!==void 0?l(r.latestNode):l((await b(e)).node)}t(Z,"cachedBrokerNode");function ee(e,r){return o().nodeDelivery(e,{...r,expected_execution_id:n()})}t(ee,"brokerDelivery");function re(e,r){return o().commitBrokerGeneratedName(e,{...r,expected_execution_id:n()})}t(re,"commitBrokerGeneratedName");function te(e,r){return o().commitBrokerPersonaAck(e,{...r,expected_execution_id:n()})}t(te,"commitBrokerPersonaAck");async function oe(e,r){try{await o().pushReport(e,r)}catch(i){if(r.tier==="final"&&i instanceof s&&i.code==="already_finalized")return;throw i}}t(oe,"publishBrokerReport");function ne(e){return o().relaunchRoot(e)}t(ne,"relaunchBrokerRoot");export{z as acknowledgeBrokerMail,I as appendBrokerLog,L as bindBrokerSession,ee as brokerDelivery,n as brokerExecutionId,b as brokerExtensionState,Q as brokerRecovery,Z as cachedBrokerNode,q as claimBrokerMail,S as clearBrokerPushedFinal,W as clearNodeFault,re as commitBrokerGeneratedName,Y as commitBrokerModel,te as commitBrokerPersonaAck,j as completeBrokerPark,A as consumeBrokerPushedFinal,K as mutateBrokerFault,H as mutateBrokerProviderRetry,oe as publishBrokerReport,C as putBrokerRecap,T as putBrokerTelemetry,M as readBrokerPassiveMessage,J as recordBackgroundedJob,G as recordBrokerParkActivity,O as recordBrokerTelemetry,X as recordBrokerTurn,V as recordNodeFault,ne as relaunchBrokerRoot,$ as settleBroker,D as startBrokerBashJob,U as stopBrokerBashJob};

package/dist/core/runtime/broker/engine-drive.d.ts

@@ -0,0 +1,37 @@
+import type { MessageOrigin } from '../stamp/protocol.js';
+import type { ClientToBroker } from '../broker-protocol.js';
+import type { BrokerClient, BrokerClientRegistry } from './client-registry.js';
+import type { EventProjection } from './event-projection.js';
+import type { MemoryRefGuidance } from './frame-memory-refs.js';
+import type { FrameReplies } from './frame-replies.js';
+import type { BrokerSession } from './read-ops.js';
+import type { RebindDriver } from './rebind.js';
+import type { ToolGroupTracker } from './tool-groups.js';
+import type { PromptDispatchTracker } from './turn-ignition.js';
+import type { TurnAdmissionGate } from './turn-admission.js';
+/** The frames that drive the live engine. */
+type DeliveredInput = {
+    delivery?: {
+        origin?: MessageOrigin;
+    };
+};
+export type DriveFrame = (Extract<ClientToBroker, {
+    type: 'prompt' | 'follow_up';
+}> & DeliveredInput) | Extract<ClientToBroker, {
+    type: 'steer' | 'abort' | 'bash';
+}>;
+export type EngineDriver = (client: BrokerClient, frame: DriveFrame) => Promise<unknown> | undefined;
+export declare function createEngineDriver(deps: {
+    nodeId: string;
+    registry: BrokerClientRegistry;
+    replies: FrameReplies;
+    session: () => BrokerSession;
+    dispatches: PromptDispatchTracker;
+    memoryRefs: MemoryRefGuidance;
+    rebind: RebindDriver;
+    projection: EventProjection;
+    toolGroups: ToolGroupTracker;
+    turnAdmission: TurnAdmissionGate;
+    prependDeferred?: (session: BrokerSession) => Promise<string[]>;
+}): EngineDriver;
+export {};

package/dist/core/runtime/broker/engine-drive.js

@@ -0,0 +1 @@
+var j=Object.defineProperty;var s=(h,m)=>j(h,"name",{value:m,configurable:!0});import{emitEvent as I}from"../../events/emit.js";import{operationIdContext as w}from"../../events/operation-id.js";import{parkSummaryGraceMs as q}from"../../../shared/env.js";import{headlessTurn as J}from"../headless-pi.js";import{completeBrokerPark as N,recordBrokerParkActivity as z}from"./daemon-ops.js";import{promptWithAdvertisedCommandInvocation as y}from"../advertised-command-invocation.js";import{heldDeferredInboxPromptJoin as H}from"./held-deferred-inbox.js";import{announceMessageOrigin as K}from"../stamp/channel.js";import{chooseGuidanceDeliveryMode as L,promptWithNextTurnGuidance as Q,resolveEngineRoute as V,resolveSteerCall as X}from"./engine-routing.js";function dt(h){const{nodeId:m,registry:u,replies:A,session:r,dispatches:p,memoryRefs:k,rebind:F,projection:E,toolGroups:M,turnAdmission:S}=h,{ackTo:P,engineErrorTo:R}=A,_=s(e=>{let t;return{relay:s(n=>{t=n,u.sendFrame(e,{type:"error",code:"engine_error",message:String(n)})},"relay"),failure:s(()=>t,"failure")}},"errorRelay"),f=s((e,t)=>r().sendCustomMessage({customType:"crtr-memory-refs",content:e,display:!1},{deliverAs:t}).catch(n=>{I({level:"warn",event:"broker.memory_refs.guidance_send_failed",error:n})}),"sendGuidance");let l=!1;const B=s(async()=>{if(!l)return;if((await z(m)).activity!=="recorded")throw new Error("parking completion took priority before input admission")},"recordParkActivityBeforeInput"),T=s(e=>{l=!0;const t=r(),n=t.model,o=t.sessionManager;(n===void 0||typeof n.provider!="string"||typeof n.id!="string"?Promise.resolve("failed"):J({systemPrompt:t.systemPrompt,userPrompt:e,modelSpec:`${n.provider}/${n.id}`,timeoutMs:q(),seedMessages:o.buildSessionContext().messages,sessionId:o.getSessionId(),toolPolicy:"builtin"})).catch(()=>"failed").then(i=>N(m,{outcome:i})).then(i=>{i.action==="shutdown"&&F.requestShutdown()}).catch(i=>{I({level:"error",event:"broker.park.complete_failed",error:i})}).finally(()=>{l=!1})},"runParkTurn"),v=s((e,t,n)=>{const o=n.relay,a=s(d=>d.then(()=>n.failure()),"settle"),i=s(d=>{const c=V(t,r().isStreaming),W=c.call==="prompt"?c.options:void 0,g=k.guidanceFor(t.text),$=s(()=>{t.delivery?.origin!==void 0&&K(t.text,t.delivery.origin)},"announceDelivery"),x=s(async()=>{if(c.call==="prompt"&&!r().isStreaming)try{await H()?.(r())}catch{}const C=c.call==="prompt"&&!r().isStreaming?await h.prependDeferred?.(r())??[]:[];C.length&&r().sessionManager.appendCustomEntry("crtr-turn-input",{message_ids:C}),$(),await r().prompt(t.text,{...W,preflightResult:d})},"prompt");if(g===null)return c.call==="prompt"?a(p.track(w.fresh(()=>y(r(),t.text,x).catch(o)))):(d(),a(r().followUp(t.text,t.images).catch(o)));const b=L(t.type,c.call,r().isStreaming);return c.call==="prompt"?a(b==="nextTurn"?p.track(Q(r(),g,()=>w.fresh(()=>y(r(),t.text,x))).catch(o)):p.track(w.fresh(()=>y(r(),t.text,x).catch(o).then(()=>f(g,b))))):(d(),a(r().followUp(t.text,t.images).catch(o).then(()=>f(g,b))))},"drive");return s(()=>S.admit(d=>l?B().then(()=>i(d),c=>(o(c),n.failure())):i(d)),"dispatch")()},"drivePromptOrFollowUp"),G=s((e,t,n)=>(async()=>(r().isBashRunning?r().abortBash():(await p.waitUntilAbortable(),r().isStreaming&&await r().abort()),v(e,{type:"prompt",text:t.text,...t.images!==void 0?{images:t.images}:{}},_(e))))().catch(o=>(n.relay(o),n.failure())),"driveInterruptPrompt"),O=s((e,t)=>{const n=t.relay,o=s(a=>{if(X(e.text,r())==="prompt")return y(r(),e.text,()=>r().prompt(e.text,{images:e.images,streamingBehavior:"steer",preflightResult:a}));a();const i=k.guidanceFor(e.text);return i===null?r().steer(e.text,e.images).then(()=>{}):r().steer(e.text,e.images).then(()=>f(i,"steer"))},"drive");S.admit(a=>l?B().then(()=>o(a),i=>{n(i)}):o(a)).catch(n)},"driveSteer"),D=s((e,t,n)=>{if(r().isBashRunning){r().abortBash(),t.id!==void 0&&P(e,"abort",!0,"bash",t.id);return}if(t.id===void 0){r().abort().catch(n.relay);return}(async()=>{try{await p.waitUntilAbortable();const o=r().isStreaming?"turn":"idle";await r().abort(),P(e,"abort",!0,o,t.id)}catch(o){R(e,t.id)(o)}})()},"driveAbort"),U=s((e,t,n)=>{const o=t.command;if(o.trim()==="")return;if(r().isBashRunning){u.sendFrame(e,{type:"error",code:"bash_busy",message:"A bash command is already running"});return}const a=t.excludeFromContext===!0;E.flush(),M.finishOpenToolGroup(),u.broadcast({type:"bash_start",command:o,excludeFromContext:a}),r().executeBash(o,i=>u.broadcast({type:"bash_output",chunk:i}),{excludeFromContext:a}).then(i=>{u.broadcast({type:"bash_end",exitCode:i.exitCode,cancelled:i.cancelled,truncated:i.truncated,fullOutputPath:i.fullOutputPath})}).catch(n.relay)},"driveBash");return(e,t)=>{if((t.type==="prompt"||t.type==="follow_up")&&t.delivery?.origin?.type==="runtime"&&t.delivery.origin.kind==="park"){T(t.text);return}const n=_(e);switch(t.type){case"prompt":return t.interrupt===!0?G(e,t,n):v(e,t,n);case"follow_up":return v(e,t,n);case"steer":O(t,n);return;case"abort":D(e,t,n);return;case"bash":U(e,t,n);return}}}s(dt,"createEngineDriver");export{dt as createEngineDriver};

package/dist/core/runtime/broker/engine-routing.d.ts

@@ -0,0 +1,143 @@
+import type { PromptOptions } from '@earendil-works/pi-coding-agent';
+import type { ImageContent } from '@earendil-works/pi-ai';
+/**
+ * Route a writable client's `prompt`/`follow_up` frame against the LIVE session
+ * state. The client picks its frame type off a possibly-STALE `isStreaming`
+ * snapshot, so the broker is authoritative and the client's choice is a HINT:
+ *
+ *  - m-B (streaming-safe prompt): a `prompt` arriving mid-stream needs
+ *    PromptOptions.streamingBehavior ("Required if streaming"; prompt() throws
+ *    without it). "steer" mirrors pi interactive-mode's own
+ *    Enter-while-streaming submit (`prompt(text, { streamingBehavior: "steer" })`).
+ *  - m-C (idle-safe follow_up): pi's followUp() only enqueues into a RUNNING
+ *    agent loop — on an idle session nothing ever drains the queue and the text
+ *    is silently lost. An idle `follow_up` therefore runs as a prompt now.
+ *
+ * driveEngine calls this synchronously with `session.isStreaming`, so the
+ * routed state cannot go stale between the check and the engine call.
+ * C1: images ride as a field on PromptOptions (pi: `prompt(text, { images })`).
+ */
+export declare function resolveEngineRoute(frame: {
+    type: 'prompt' | 'follow_up';
+    images?: ImageContent[];
+}, isStreaming: boolean): {
+    call: 'prompt';
+    options: PromptOptions;
+} | {
+    call: 'followUp';
+};
+/**
+ * True iff `text` would be consumed by pi's OWN leading-name preflight before
+ * `session.prompt/steer/followUp` ever sees it as prose — an extension command
+ * (`session.extensionRunner.getCommand`), a `/skill:name` skill, or a `/name`
+ * prompt template (mirrors `_tryExecuteExtensionCommand` / `_expandSkillCommand`
+ * / `expandPromptTemplate` in the pinned SDK verbatim, including the exact
+ * name-parsing substrings). Inline memory-reference guidance must NEVER fire
+ * for these — the leading token routes to the engine's own command surface,
+ * not prose referencing a memory doc. Each lookup is independently wrapped so
+ * an engine missing one accessor (the fake, or a degraded session) degrades
+ * that check to "not a match" rather than aborting the whole classification —
+ * matching `buildCommandList`'s existing "no live extensionRunner" tolerance.
+ */
+export declare function isLeadingEngineCommand(text: string, session: {
+    extensionRunner?: {
+        getCommand(name: string): unknown;
+    };
+    resourceLoader?: {
+        getSkills(): {
+            skills: Array<{
+                name: string;
+            }>;
+        };
+    };
+    promptTemplates?: ReadonlyArray<{
+        name: string;
+    }>;
+}): boolean;
+/** A `steer` frame normally maps directly to pi's steer queue. Engine commands,
+ * skills, and templates must instead pass through prompt()'s leading-command
+ * preflight; with streamingBehavior:'steer', ordinary expanded text still lands
+ * in the same queue. */
+export declare function resolveSteerCall(text: string, session: Parameters<typeof isLeadingEngineCommand>[1]): 'prompt' | 'steer';
+/**
+ * Enumerate every leading-token STRING this session's engine would
+ * independently consume as a leading command/skill/template dispatch BEFORE
+ * inline memory-reference guidance ever applies — the read-op sibling of
+ * `isLeadingEngineCommand`'s point-lookup, gathered as a full enumeration for
+ * viewer-side suppression instead of a per-submission membership check. Same
+ * three sources, same shape of the leading match `isLeadingEngineCommand`
+ * checks (bare extension-command invocation names and prompt-template names,
+ * `skill:<name>` for skills), so `/${token}` round-trips through
+ * `isLeadingEngineCommand(text, session)` for every emitted token (locked by
+ * a test). Kept STRICTLY separate from `buildCommandList` (command
+ * completion) and the ref inventory (`RefMeta` rows) — this is neither.
+ */
+export declare function engineLeadingCommandTokens(session: {
+    extensionRunner?: {
+        getRegisteredCommands(): Array<{
+            invocationName: string;
+        }>;
+    };
+    resourceLoader?: {
+        getSkills(): {
+            skills: Array<{
+                name: string;
+            }>;
+        };
+    };
+    promptTemplates?: ReadonlyArray<{
+        name: string;
+    }>;
+}): string[];
+/**
+ * Choose how the hidden `crtr-memory-refs` guidance custom message rides
+ * alongside a human frame's own engine call (design Flow B). Pure over the
+ * frame's routing outcome — never reads live session state itself, so a
+ * caller can decide the delivery mode from the exact same `route`
+ * `resolveEngineRoute` already computed for the human call.
+ *
+ *  - `steer` frame              -> 'steer' (always; no route call exists).
+ *  - a TRUE mid-stream follow_up (`routeCall === 'followUp'`) -> 'followUp'.
+ *  - every other `prompt`/`follow_up` routed as `routeCall === 'prompt'`:
+ *    idle -> 'nextTurn' (the ONLY case guidance precedes the human call —
+ *    pi's `prompt()` reads+clears its pending-nextTurn queue synchronously
+ *    into the SAME turn as the new user message); streaming (m-B
+ *    steer-while-streaming) -> 'steer', never 'nextTurn' (that would attach
+ *    to a later, unrelated turn).
+ */
+export declare function chooseGuidanceDeliveryMode(frameType: 'prompt' | 'follow_up' | 'steer', routeCall: 'prompt' | 'followUp' | undefined, isStreaming: boolean): 'steer' | 'followUp' | 'nextTurn';
+/**
+ * Deliver a `nextTurn` guidance custom message ATOMICALLY around the idle-
+ * prompt call it's meant to ride alongside. Pi's `_pendingNextTurnMessages`
+ * queue (the only public seam for `deliverAs:'nextTurn'`) is drained ONLY deep
+ * inside `session.prompt()`, well after several await points — extension-
+ * command interception, the `input` extension transform, a streaming reroute,
+ * model/auth validation, pre-turn compaction — that can return or throw BEFORE
+ * the drain ever runs. `sendCustomMessage`'s nextTurn branch pushes
+ * synchronously and unconditionally, so any of those early exits strands the
+ * pushed guidance in the queue to attach itself to whichever LATER, unrelated
+ * prompt happens to reach the drain first.
+ *
+ * There is no public SDK seam to observe or cancel a pending nextTurn message
+ * (`_pendingNextTurnMessages` is TS-`private` only — a plain runtime field, not
+ * `#private`), so this reaches into that one field and removes EXACTLY the
+ * entry this call pushed, identified by object identity via a locally-
+ * generated marker riding the message's own `details` field (never surfaced to
+ * the model, and irrelevant if the message WAS consumed normally — `details`
+ * is just carried through like any other field once folded into a real turn).
+ * Runs UNCONDITIONALLY after the human call settles, success or failure/early-
+ * return alike — a "successful" `prompt()` promise can just as easily be an
+ * early return that skipped the drain (an intercepted extension command, an
+ * `input` transform, a streaming reroute) as a genuine consumed turn, so only
+ * checking `.catch` is not enough.
+ */
+export declare function promptWithNextTurnGuidance(session: {
+    sendCustomMessage(message: {
+        customType: string;
+        content: unknown;
+        display?: boolean;
+        details?: unknown;
+    }, options?: {
+        deliverAs?: 'steer' | 'followUp' | 'nextTurn';
+    }): Promise<void>;
+}, guidance: string, runPrompt: () => Promise<void>): Promise<void>;

package/dist/core/runtime/broker/engine-routing.js

@@ -0,0 +1 @@
+var a=Object.defineProperty;var i=(e,n)=>a(e,"name",{value:n,configurable:!0});import{randomUUID as c}from"node:crypto";import{emitEvent as l}from"../../events/emit.js";function g(e,n){if(e.type==="follow_up"&&n)return{call:"followUp"};const r={};return e.images!==void 0&&(r.images=e.images),n&&(r.streamingBehavior="steer"),{call:"prompt",options:r}}i(g,"resolveEngineRoute");function u(e,n){if(e.startsWith("/")){const r=e.indexOf(" "),t=r===-1?e.slice(1):e.slice(1,r);try{if(n.extensionRunner?.getCommand(t))return!0}catch{}}if(e.startsWith("/skill:")){const r=e.indexOf(" "),t=r===-1?e.slice(7):e.slice(7,r);try{if(n.resourceLoader?.getSkills().skills.some(o=>o.name===t))return!0}catch{}}if(e.startsWith("/")){const t=e.match(/^\/([^\s]+)(?:\s+([\s\S]*))?$/)?.[1];if(t!==void 0)try{if(n.promptTemplates?.some(o=>o.name===t))return!0}catch{}}return!1}i(u,"isLeadingEngineCommand");function h(e,n){return u(e,n)?"prompt":"steer"}i(h,"resolveSteerCall");function y(e){const n=[];try{for(const r of e.extensionRunner?.getRegisteredCommands()??[])n.push(r.invocationName)}catch{}try{for(const r of e.resourceLoader?.getSkills().skills??[])n.push(`skill:${r.name}`)}catch{}try{for(const r of e.promptTemplates??[])n.push(r.name)}catch{}return n}i(y,"engineLeadingCommandTokens");function k(e,n,r){return e==="steer"?"steer":n==="followUp"?"followUp":r?"steer":"nextTurn"}i(k,"chooseGuidanceDeliveryMode");async function x(e,n,r){const t=`crtr-memory-refs-pending:${c()}`;let o=!1;try{await e.sendCustomMessage({customType:"crtr-memory-refs",content:n,display:!1,details:t},{deliverAs:"nextTurn"}),o=!0}catch(s){l({level:"warn",event:"broker.memory_refs.guidance_send_failed",error:s})}try{await r()}finally{o&&m(e,t)}}i(x,"promptWithNextTurnGuidance");function m(e,n){const r=e._pendingNextTurnMessages;if(!Array.isArray(r))return;const t=r.findIndex(o=>o?.details===n);t!==-1&&r.splice(t,1)}i(m,"clearOwnPendingNextTurnGuidance");export{k as chooseGuidanceDeliveryMode,y as engineLeadingCommandTokens,u as isLeadingEngineCommand,x as promptWithNextTurnGuidance,g as resolveEngineRoute,h as resolveSteerCall};

package/dist/core/runtime/broker/event-projection.d.ts

@@ -0,0 +1,43 @@
+import type { BrokerToClient } from '../broker-protocol.js';
+import type { BrokerSession } from './read-ops.js';
+import type { BrokerClientRegistry } from './client-registry.js';
+import type { SubscriptionGeneration } from './rebind.js';
+import type { FaultRetry } from './fault-retry.js';
+type EventProjectionDeps = {
+    registry: BrokerClientRegistry;
+    faultRetry: FaultRetry;
+    installedGeneration: () => SubscriptionGeneration | undefined;
+    currentSession: () => BrokerSession;
+    notifyTurnAccepted: () => void;
+    emitStartupMilestone: (event: string, model: string | null) => void;
+    formatModelSpec: (model: BrokerSession['model'], thinkingLevel?: string) => string | null;
+};
+/** Projects one live engine event stream to broker viewers and owns its relay timers. */
+export declare class EventProjection {
+    private readonly deps;
+    private pendingUpdate;
+    private pendingUpdateTimer;
+    private workingActivity;
+    private readonly streamWatchdog;
+    private readonly toolExecutionWatchdog;
+    private readonly streamWatchdogMs;
+    private pendingBroadcast;
+    private broadcastGeneration;
+    constructor(deps: EventProjectionDeps);
+    currentWorkingActivity(): string;
+    isCurrent(generation: SubscriptionGeneration): boolean;
+    flush(): void;
+    reset(): void;
+    dispose(): void;
+    /** Arms the applicable watchdog floor after a streaming event or rebind. */
+    rearmIfStreaming(generation: SubscriptionGeneration): void;
+    knownStreamWait(deadlineMs: number): () => void;
+    relayEvent(event: BrokerToClient, generation: SubscriptionGeneration): void;
+    private abortStalledStream;
+    private clearPendingUpdate;
+    private flushPendingUpdate;
+    private invalidatePendingBroadcasts;
+    private broadcast;
+    private setPendingBroadcast;
+}
+export {};

package/dist/core/runtime/broker/event-projection.js

@@ -0,0 +1 @@
+var g=Object.defineProperty;var a=(n,t)=>g(n,"name",{value:t,configurable:!0});import{readConfig as c}from"../../config.js";import{envStreamWatchdogMs as p}from"../../../shared/env.js";import{emitEvent as r}from"../../events/emit.js";import{releaseKnownStreamWait as m,StreamWatchdog as o}from"../stream-watchdog.js";import{withoutYieldAbort as u}from"../session-cycles.js";import{DEFAULT_WORKING_ACTIVITY as d,randomWorkingActivity as f}from"../../../shared/working-activity.js";import{hydrateLiveAdvertisedCommandMessage as S,prepareAdvertisedCommandPersistence as _}from"../advertised-command-invocation.js";const b=75,h=20*6e4;class x{static{a(this,"EventProjection")}deps;pendingUpdate=null;pendingUpdateTimer=null;workingActivity=d;streamWatchdog;toolExecutionWatchdog;streamWatchdogMs=p();pendingBroadcast=null;broadcastGeneration=0;constructor(t){this.deps=t,this.streamWatchdog=new o(e=>{this.abortStalledStream(e,this.streamWatchdogMs,"while streaming \u2014 aborting stalled provider stream")},this.streamWatchdogMs),this.toolExecutionWatchdog=new o(e=>{this.abortStalledStream(e,h,"while a tool is executing \u2014 aborting stalled tool execution")},h)}currentWorkingActivity(){return this.workingActivity}isCurrent(t){return this.deps.installedGeneration()===t}flush(){this.flushPendingUpdate()}reset(){this.clearPendingUpdate(),this.invalidatePendingBroadcasts(),this.streamWatchdog.reset(),this.toolExecutionWatchdog.reset()}dispose(){this.clearPendingUpdate(),this.invalidatePendingBroadcasts(),this.streamWatchdog.reset(),this.toolExecutionWatchdog.reset()}rearmIfStreaming(t){if(t.session.isStreaming){if(t.executingTools.size>0){this.streamWatchdog.clear(),this.toolExecutionWatchdog.poke(t.id);return}this.toolExecutionWatchdog.clear(),this.streamWatchdog.poke(t.id)}}knownStreamWait(t){if(!Number.isFinite(t)||t<=Date.now())return()=>{};const e=this.deps.installedGeneration();if(e===void 0)return()=>{};const i=e.session;return this.streamWatchdog.pause(),()=>{this.deps.installedGeneration()!==e||this.deps.currentSession()!==i||m(this.streamWatchdog,e.id,i.isStreaming,e.executingTools.size>0)}}relayEvent(t,e){this.deps.faultRetry.onEvent(t);const i=t.type;if(i==="message_start"?S(t.message):i==="message_end"&&_(this.deps.currentSession(),t.message),i==="message_start"&&t.message.role==="user"){try{this.workingActivity=f(c("user").working_gerunds)}catch{this.workingActivity=d}this.broadcast({type:"working_activity",activity:this.workingActivity})}if(i==="agent_start"&&(this.deps.notifyTurnAccepted(),this.deps.emitStartupMilestone("broker.startup.agent_start",this.deps.formatModelSpec(this.deps.currentSession().model,this.deps.currentSession().thinkingLevel))),i==="message_update"&&t.message.role==="assistant"&&this.deps.emitStartupMilestone("broker.startup.provider_first_delta",this.deps.formatModelSpec(this.deps.currentSession().model,this.deps.currentSession().thinkingLevel)),i==="message_end"&&t.message.role==="assistant"&&this.deps.emitStartupMilestone("broker.startup.assistant_message_end",this.deps.formatModelSpec(this.deps.currentSession().model,this.deps.currentSession().thinkingLevel)),(i==="agent_start"||i==="turn_start")&&this.deps.faultRetry.clearTimer(),i==="agent_end"?(e.executingTools.clear(),this.streamWatchdog.reset(),this.toolExecutionWatchdog.reset()):(i==="tool_execution_start"?e.executingTools.add(t.toolCallId??""):i==="tool_execution_end"&&e.executingTools.delete(t.toolCallId??""),this.rearmIfStreaming(e)),i==="message_update"){this.pendingUpdate=t,this.pendingUpdateTimer===null&&(this.pendingUpdateTimer=setTimeout(()=>this.flushPendingUpdate(),b),typeof this.pendingUpdateTimer.unref=="function"&&this.pendingUpdateTimer.unref());return}if(this.flushPendingUpdate(),i==="message_end"&&e.stagedRefreshAbort){this.broadcast({...t,message:u(t.message)});return}this.broadcast(t)}abortStalledStream(t,e,i){const s=this.deps.installedGeneration();s===void 0||t!==s.id||(r({level:"debug",event:"broker.runtime.diagnostic",fields:{message:`stream watchdog: no engine event for ${e}ms ${i}`}}),s.stagedWatchdogAbort=!0,s.session.abort().catch(l=>{r({level:"debug",event:"broker.runtime.diagnostic",fields:{message:`stream watchdog abort failed: ${String(l)}`}})}))}clearPendingUpdate(){this.pendingUpdateTimer!==null&&(clearTimeout(this.pendingUpdateTimer),this.pendingUpdateTimer=null),this.pendingUpdate=null}flushPendingUpdate(){if(this.pendingUpdateTimer!==null&&(clearTimeout(this.pendingUpdateTimer),this.pendingUpdateTimer=null),this.pendingUpdate!==null){const t=this.pendingUpdate;this.pendingUpdate=null,this.broadcast(t)}}invalidatePendingBroadcasts(){this.broadcastGeneration++,this.pendingBroadcast=null}broadcast(t){const e=this.pendingBroadcast;if(e===null){this.deps.registry.broadcast(t);return}const i=this.broadcastGeneration;this.setPendingBroadcast(e.then(()=>{this.broadcastGeneration===i&&this.deps.registry.broadcast(t)}))}setPendingBroadcast(t){this.pendingBroadcast=t,t.then(()=>{this.pendingBroadcast===t&&(this.pendingBroadcast=null)})}}export{x as EventProjection};

package/dist/core/runtime/broker/extension-abort.d.ts

@@ -0,0 +1,15 @@
+interface AbortableSession {
+    clearQueue(): unknown;
+    abort(): Promise<unknown>;
+}
+export declare function refuseTurn(abort: () => void): void;
+export declare function wasTurnRefused(): boolean;
+export declare function clearRefusedTurn(): void;
+/** Prevent extensions from settling a turn that broker teardown will certify. */
+export declare function beginRuntimeTeardown(): void;
+export declare function isRuntimeTeardownInProgress(): boolean;
+/** Mark one synchronous ExtensionContext.abort() call as a refresh boundary. */
+export declare function runRefreshAbort(abort: () => void): void;
+/** Bound into Pi's extension context by the broker for every session generation. */
+export declare function abortSessionFromExtension(session: AbortableSession, stageRefreshAbort?: () => void): void;
+export {};

package/dist/core/runtime/broker/extension-abort.js

@@ -0,0 +1 @@
+var s=Object.defineProperty;var r=(e,n)=>s(e,"name",{value:n,configurable:!0});let t=!1,o=!1;const u=globalThis;function i(e){o=!0,e()}r(i,"refuseTurn");function a(){return o}r(a,"wasTurnRefused");function c(){o=!1}r(c,"clearRefusedTurn");function l(){u.__crtrRuntimeTeardownInProgress=!0}r(l,"beginRuntimeTeardown");function T(){return u.__crtrRuntimeTeardownInProgress===!0}r(T,"isRuntimeTeardownInProgress");function d(e){t=!0;try{e()}finally{t=!1}}r(d,"runRefreshAbort");function p(e,n){t&&(e.clearQueue(),n?.()),e.abort()}r(p,"abortSessionFromExtension");export{p as abortSessionFromExtension,l as beginRuntimeTeardown,c as clearRefusedTurn,T as isRuntimeTeardownInProgress,i as refuseTurn,d as runRefreshAbort,a as wasTurnRefused};