@north-light/cli 0.0.0 → 0.3.413

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

@@ -0,0 +1,3 @@
+/** fd 3 is a one-shot pipe from the daemon, not a file or an environment value. */
+export declare function receiveNodeToken(): Promise<string>;
+export declare function currentNodeToken(): string | undefined;

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

@@ -0,0 +1 @@
+var c=Object.defineProperty;var n=(r,e)=>c(r,"name",{value:e,configurable:!0});import{createReadStream as u}from"node:fs";let o=null;async function i(){if(o!==null)throw new Error("node token was already received");const r=[];for await(const t of u("",{fd:3,autoClose:!0}))r.push(Buffer.from(t));const e=Buffer.concat(r).toString("utf8");if(!/^[A-Za-z0-9_-]{43}$/.test(e))throw new Error("broker received an invalid node token");return o=e,e}n(i,"receiveNodeToken");function d(){return o??void 0}n(d,"currentNodeToken");export{d as currentNodeToken,i as receiveNodeToken};

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

@@ -0,0 +1,27 @@
+import { type CreateAgentSessionResult } from '@earendil-works/pi-coding-agent';
+import { type DeterministicCommandExpansion } from '../command-expansion.js';
+import { SessionListCache } from '../session-list-cache.js';
+import { type GetSettingsData, type GetTreeData, type ListMemoryRefsData, type ListModelsData, type ListScopedModelsData, type ListSessionsData, type RefMeta } from '../broker-protocol.js';
+export type BrokerSession = CreateAgentSessionResult['session'];
+export type CommandDisclosure = {
+    name: string;
+    description: string;
+    source: string;
+    template?: string;
+    expansion?: DeterministicCommandExpansion;
+    /** Whether this command can complete its outcome from a non-terminal chat
+     *  surface. Opt-in and fail-closed; builtins are never chat-capable. */
+    gatewayCapable: boolean;
+    argumentHint?: string;
+};
+export declare const modelKey: (model: {
+    provider: string;
+    id: string;
+}) => string;
+export declare function buildCommandList(session: BrokerSession): CommandDisclosure[];
+export declare function buildListMemoryRefsData(id: string, refs: RefMeta[], engineLeadingCommandNames: string[]): ListMemoryRefsData;
+export declare function buildListModelsData(id: string, session: BrokerSession): ListModelsData;
+export declare function buildScopedModelsData(id: string, session: BrokerSession): ListScopedModelsData;
+export declare function buildGetTreeData(id: string, session: BrokerSession, boundaryReviewId: string | undefined): GetTreeData;
+export declare function buildSettingsData(id: string, session: BrokerSession): GetSettingsData;
+export declare function buildSessionsData(id: string, scope: 'cwd' | 'all', session: BrokerSession, cache: SessionListCache): Promise<ListSessionsData>;

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

@@ -0,0 +1 @@
+var p=Object.defineProperty;var o=(n,t)=>p(n,"name",{value:t,configurable:!0});import{ModelRegistry as h}from"@earendil-works/pi-coding-agent";import{boundaryRootedTree as f}from"../session-visibility.js";import{isUnknownModel as M}from"../model-selection.js";import{BUILTIN_SLASH_COMMANDS as b}from"../pi-vendored.js";import{isDeterministicCommandExpansion as y}from"../command-expansion.js";import{registrationChatSurface as k,templateChatSurface as T}from"../command-surface.js";function m(n){return new h(n.modelRuntime)}o(m,"registryOf");const u=o(n=>n===void 0||M(n)?null:{provider:n.provider,id:n.id},"toModelRef"),S=o(n=>`${n.provider}/${n.id}`,"modelKey");function D(n){const t=[];for(const e of b)t.push({name:e.name,description:e.description,source:"builtin",gatewayCapable:!1});try{for(const e of n.extensionRunner.getRegisteredCommands()){const l=e.expansion;t.push({name:e.invocationName,description:e.description??"",source:"command",...y(l)?{expansion:l}:{},...k(e)})}}catch{}try{for(const e of n.promptTemplates)t.push({name:e.name,description:e.description,source:"template",template:e.content,...T(e)})}catch{}return t}o(D,"buildCommandList");function A(n,t,e){return{type:"data",id:n,kind:"list_memory_refs",refs:t,engineLeadingCommandNames:e}}o(A,"buildListMemoryRefsData");function R(n,t){const e=m(t);let l=[];try{l=e.getAvailable().map(S)}catch{}return{type:"data",id:n,kind:"list_models",models:e.getAll(),current:u(t.model),availableIds:l,scopedModels:t.scopedModels.map(a=>({model:a.model,thinkingLevel:a.thinkingLevel})),enabledModelIds:t.settingsManager.getEnabledModels()??null}}o(R,"buildListModelsData");function P(n,t){return{type:"data",id:n,kind:"list_scoped_models",allModels:m(t).getAll(),enabledModelIds:t.settingsManager.getEnabledModels()??null}}o(P,"buildScopedModelsData");function F(n,t,e){const l=t.sessionManager,a=e!==void 0?f(l.getTree(),e):l.getTree(),r=new Set,s=o(d=>{for(const c of d)r.add(c.entry.id),s(c.children)},"collectEntryIds");s(a);const g=t.getUserMessagesForForking().filter(d=>r.has(d.entryId)).map(d=>({id:d.entryId,text:d.text,timestamp:l.getEntry(d.entryId)?.timestamp})),i=l.getLeafId();return{type:"data",id:n,kind:"get_tree",tree:a,currentLeafId:i!==null&&r.has(i)?i:null,forkPoints:g}}o(F,"buildGetTreeData");function _(n,t){const e=t.settingsManager;let l=[];try{l=t.resourceLoader.getThemes().themes.map(i=>i.name??"").filter(i=>i!=="")}catch{}const a=e.getDefaultProvider(),r=e.getDefaultModel();let s=[];try{s=t.modelRuntime.getAvailableSnapshot()}catch{}const g={autoCompact:t.autoCompactionEnabled,defaultModel:a&&r?`${a}/${r}`:"not set",availableDefaultModels:s,showImages:e.getShowImages(),imageWidthCells:e.getImageWidthCells(),autoResizeImages:e.getImageAutoResize(),blockImages:e.getBlockImages(),enableSkillCommands:e.getEnableSkillCommands(),steeringMode:t.steeringMode,followUpMode:t.followUpMode,transport:e.getTransport(),httpIdleTimeoutMs:e.getHttpIdleTimeoutMs(),thinkingLevel:t.thinkingLevel,availableThinkingLevels:t.getAvailableThinkingLevels(),modelThinkingLevels:e.getAllModelThinkingLevels(),currentTheme:e.getTheme()??"",terminalTheme:"dark",availableThemes:l,hideThinkingBlock:e.getHideThinkingBlock(),mermaidRenderingMode:e.getMermaidRenderingMode(),collapseChangelog:e.getCollapseChangelog(),enableInstallTelemetry:e.getEnableInstallTelemetry(),doubleEscapeAction:e.getDoubleEscapeAction(),treeFilterMode:e.getTreeFilterMode(),showHardwareCursor:e.getShowHardwareCursor(),editorPaddingX:e.getEditorPaddingX(),autocompleteMaxVisible:e.getAutocompleteMaxVisible(),quietStartup:e.getQuietStartup(),clearOnShrink:e.getClearOnShrink(),showTerminalProgress:e.getShowTerminalProgress(),tuiMode:e.getTuiMode(),fullscreenExitOutput:e.getFullscreenExitOutput(),fullscreenScrollbar:e.getFullscreenScrollbar(),fullscreenCopyOnSelect:e.getFullscreenCopyOnSelect(),fullscreenWheelScrollLines:e.getFullscreenWheelScrollLines(),warnings:e.getWarnings(),defaultProjectTrust:e.getDefaultProjectTrust(),showCacheMissNotices:e.getShowCacheMissNotices(),cacheWarmingMode:e.getCacheWarmingMode(),outputPad:e.getOutputPad(),autoRetry:t.autoRetryEnabled,model:u(t.model)};return{type:"data",id:n,kind:"get_settings",settings:g}}o(_,"buildSettingsData");function O(n,t,e,l){const a=e.sessionManager;return(t==="all"?l.listAll():l.listDir(a.getCwd())).then(r=>({type:"data",id:n,kind:"list_sessions",scope:t,sessions:r,currentSessionFile:e.sessionFile}))}o(O,"buildSessionsData");export{D as buildCommandList,F as buildGetTreeData,A as buildListMemoryRefsData,R as buildListModelsData,P as buildScopedModelsData,O as buildSessionsData,_ as buildSettingsData,S as modelKey};

package/dist/core/runtime/broker/rebind.d.ts

@@ -0,0 +1,78 @@
+import type { AgentSessionRuntime, AgentSessionServices, ExtensionUIContext } from '@earendil-works/pi-coding-agent';
+import type { BrokerSdkConfig } from '../launch.js';
+import type { BrokerClientRegistry, BrokerClient } from './client-registry.js';
+import type { FaultRetry } from './fault-retry.js';
+import type { EventProjection } from './event-projection.js';
+import type { BrokerSession } from './read-ops.js';
+import type { ToolGroupTracker } from './tool-groups.js';
+import type { OperationId } from '../../events/types.js';
+export interface SubscriptionGeneration {
+    id: number;
+    session: BrokerSession;
+    fallback: {
+        storedId?: OperationId;
+        blocked: boolean;
+    };
+    stagedProviderAgentEnd: {
+        messages?: unknown[];
+    } | null;
+    stagedWatchdogAbort: boolean;
+    stagedRefreshAbort: boolean;
+    stagedOverflowFailure: {
+        errorMessage: string;
+    } | null;
+    executingTools: Set<string>;
+}
+type RebindDriverDeps = {
+    nodeId: string;
+    cfg: BrokerSdkConfig;
+    session: BrokerSession;
+    services: AgentSessionServices;
+    runtime: AgentSessionRuntime | undefined;
+    uiContext: () => ExtensionUIContext;
+    registry: BrokerClientRegistry;
+    toolGroups: ToolGroupTracker;
+    faultRetry: () => FaultRetry;
+    projection: () => EventProjection;
+    setActiveSession: (session: {
+        dispose: () => void;
+    }) => void;
+    disposeAndExit: (reason: string, status?: number) => void;
+    onSessionRebind: () => void;
+    onReplacementIdle?: () => void;
+    reWelcomeAll: () => void;
+};
+/** Owns session subscription replacement, its serialization lane, and replacement admission policy. */
+export declare class RebindDriver {
+    private readonly deps;
+    private sessionValue;
+    private servicesValue;
+    private unsubscribe;
+    private installed;
+    private nextSubscriptionGeneration;
+    private rebindTail;
+    private latestRebindRequest;
+    private replacementTail;
+    private admittedReplacements;
+    private agentRunActiveValue;
+    private shutdownRequested;
+    constructor(deps: RebindDriverDeps);
+    session(): BrokerSession;
+    services(): AgentSessionServices;
+    installedGeneration(): SubscriptionGeneration | undefined;
+    isAgentRunActive(): boolean;
+    isReplacing(): boolean;
+    requestShutdown(): void;
+    setRebindSession(): void;
+    enqueueRebind(candidateSession: BrokerSession, candidateServices: AgentSessionServices): Promise<void>;
+    runReplacement(client: BrokerClient, op: string, run: (runtime: AgentSessionRuntime) => Promise<{
+        cancelled: boolean;
+        detail?: string;
+    }>): void;
+    private removeInstalledSubscription;
+    private captureSystemPrompt;
+    private executeSubscriptionCallback;
+    private publishAndScheduleProviderRecovery;
+    private ackTo;
+}
+export {};

package/dist/core/runtime/broker/rebind.js

@@ -0,0 +1 @@
+var k=Object.defineProperty;var l=(d,e)=>k(d,"name",{value:e,configurable:!0});import{mkdirSync as v,writeFileSync as _}from"node:fs";import{join as A}from"node:path";import{nodeRunJobDir as E}from"../../canvas/paths.js";import{emitEvent as u}from"../../events/emit.js";import{operationIdContext as c}from"../../events/operation-id.js";import{installPersonaTransitionGate as I}from"../broker-persona-guidance.js";import{installRetryCardElision as T}from"./retry-card-elision.js";import{abortSessionFromExtension as w}from"./extension-abort.js";import{brokerRecovery as S,mutateBrokerFault as x,mutateBrokerProviderRetry as P}from"./daemon-ops.js";const f=2,m=3e4,b=Symbol("replacement-deadline-exceeded"),V="(interrupted)",g=Symbol.for("crtr.trailing-thinking-guard");function C(d){for(let e=d.length-1;e>=0;e--){const t=d[e];if(t!==void 0){if(t.type==="text"){if(t.text.trim().length===0)continue;return t}if(t.type==="thinking"){const n=t.thinkingSignature,r=typeof n=="string"&&n.trim().length>0;if(t.redacted!==!0&&t.thinking.trim().length===0&&!r)continue;return t}return t}}}l(C,"lastSerializedBlock");function y(d){return d.map(e=>e.role!=="assistant"||e.stopReason==="error"||e.stopReason==="aborted"||C(e.content)?.type!=="thinking"?e:{...e,content:[...e.content,{type:"text",text:V}]})}l(y,"guardTrailingThinking");function N(d){const e=d.convertToLlm;if(e[g]===!0)return;const t=l(n=>{const r=e(n);return r instanceof Promise?r.then(y):y(r)},"wrapped");t[g]=!0,d.convertToLlm=t}l(N,"installTrailingThinkingGuard");class K{static{l(this,"RebindDriver")}deps;sessionValue;servicesValue;unsubscribe;installed;nextSubscriptionGeneration=0;rebindTail=Promise.resolve();latestRebindRequest=0;replacementTail=Promise.resolve();admittedReplacements=0;agentRunActiveValue=!1;shutdownRequested=!1;constructor(e){this.deps=e,this.sessionValue=e.session,this.servicesValue=e.services}session(){return this.sessionValue}services(){return this.servicesValue}installedGeneration(){return this.installed}isAgentRunActive(){return this.agentRunActiveValue}isReplacing(){return this.admittedReplacements>0}requestShutdown(){if(!this.agentRunActiveValue){this.deps.disposeAndExit("shutdown-hook");return}this.shutdownRequested=!0}setRebindSession(){this.deps.runtime?.setRebindSession(e=>this.enqueueRebind(e,this.deps.runtime.services))}enqueueRebind(e,t){const n=++this.latestRebindRequest,r=this.rebindTail.then(async()=>{if(n!==this.latestRebindRequest)return;if(this.installed!==void 0){typeof this.sessionValue.sessionFile=="string"&&this.sessionValue.sessionFile!==""&&await P(this.deps.nodeId,{op:"invalidate",session_id:this.sessionValue.sessionManager.getSessionId()});const s=(await S(this.deps.nodeId)).fault;s?.link==="pi\u2192provider"&&s.retry.disposition==="auto"&&s.retry.by==="daemon"&&await x(this.deps.nodeId,{op:"clear",link:"pi\u2192provider",preserve_episode:!0})}if(this.installed?.executingTools.clear(),this.removeInstalledSubscription(),this.deps.setActiveSession(e),this.deps.projection().reset(),this.deps.faultRetry().reset(),this.agentRunActiveValue=!1,this.deps.onSessionRebind(),this.deps.toolGroups.resetForSession(),await e.bindExtensions({uiContext:this.deps.uiContext(),mode:"rpc",abortHandler:l(()=>w(e,()=>{const s=this.installed;s?.session===e&&(s.stagedRefreshAbort=!0)}),"abortHandler"),shutdownHandler:l(()=>this.requestShutdown(),"shutdownHandler")}),n!==this.latestRebindRequest)return;this.removeInstalledSubscription(),this.sessionValue=e,this.servicesValue=t;const a=e.agent;if(a&&(I(this.deps.nodeId,{agent:a,sessionManager:e.sessionManager},()=>this.deps.faultRetry().notePersonaGateFailure()),T(a),a.steeringMode="all",a.followUpMode="all",N(a)),this.deps.cfg.editorName!==void 0&&this.deps.cfg.editorName!=="")try{e.setSessionName(this.deps.cfg.editorName)}catch{}const o={id:++this.nextSubscriptionGeneration,session:e,fallback:{blocked:!1},stagedProviderAgentEnd:null,stagedWatchdogAbort:!1,stagedRefreshAbort:!1,stagedOverflowFailure:null,executingTools:new Set};this.unsubscribe=this.sessionValue.subscribe(s=>{if(!this.deps.projection().isCurrent(o))return;if(c.current()!==void 0){this.executeSubscriptionCallback(o,s);return}const i=o.fallback;if(s.type==="turn_start"&&i.storedId!==void 0){i.storedId=void 0,i.blocked=!0,c.fresh(()=>{u({level:"warn",event:"broker.turn.fallback_overlap",fields:{generation:o.id,engine_event:s.type}}),this.executeSubscriptionCallback(o,s)});return}if(s.type==="turn_start"&&!i.blocked){c.fresh(R=>{i.storedId=R,this.executeSubscriptionCallback(o,s)});return}const p=i.storedId;if(p!==void 0&&!i.blocked){c.run(p,()=>{this.executeSubscriptionCallback(o,s),s.type==="agent_settled"&&i.storedId===p&&(i.storedId=void 0)});return}this.executeSubscriptionCallback(o,s)}),this.installed=o,this.deps.projection().rearmIfStreaming(o),this.captureSystemPrompt(e)});return this.rebindTail=r.catch(()=>{}),r}runReplacement(e,t,n){const r=this.deps.runtime;if(r===void 0){this.deps.registry.sendFrame(e,{type:"error",code:"engine_error",message:"session replacement unsupported at this engine pin"});return}if(this.admittedReplacements>=f){c.fresh(()=>u({level:"warn",event:"broker.session_replacement.rejected",outcome:"skipped",fields:{op:t,reason:"capacity",admitted:f,cap:f}})),this.ackTo(e,t,!1,`session replacement busy (${f} active or queued)`);return}this.admittedReplacements++;const a=this.replacementTail.then(async()=>{try{await c.fresh(async()=>{const o=process.hrtime.bigint();let s;try{const h=new Promise(p=>{s=setTimeout(()=>p(b),m)}),i=await Promise.race([n(r),h]);if(i===b){u({level:"error",event:"broker.session_replacement.timed_out",outcome:"failed",duration_ms:Number(process.hrtime.bigint()-o)/1e6,fields:{op:t,deadline_ms:m,mutation_outcome:"indeterminate"}}),this.ackTo(e,t,!1,"session replacement timed out; broker restarting because session state is indeterminate"),this.deps.disposeAndExit("session-replacement-timeout",1);return}i.cancelled||this.deps.reWelcomeAll(),this.ackTo(e,t,!i.cancelled,i.cancelled?i.detail??"cancelled by extension":void 0)}catch(h){u({level:"error",event:"broker.session_replacement.failed",outcome:"failed",error:h,fields:{op:t,mutation_outcome:"indeterminate"}}),this.ackTo(e,t,!1,"session replacement failed; broker restarting because session state is indeterminate"),this.deps.disposeAndExit("session-replacement-failed",1)}finally{clearTimeout(s)}})}finally{this.admittedReplacements--,this.admittedReplacements===0&&this.deps.onReplacementIdle?.()}});this.replacementTail=a.catch(()=>{})}removeInstalledSubscription(){this.unsubscribe?.(),this.unsubscribe=void 0,this.installed=void 0}captureSystemPrompt(e){try{const t=E(this.deps.nodeId);v(t,{recursive:!0}),_(A(t,"system-prompt.md"),e.systemPrompt,"utf8")}catch{}}executeSubscriptionCallback(e,t){try{t.type==="agent_start"&&(this.agentRunActiveValue=!0),t.type==="agent_end"&&(e.stagedProviderAgentEnd=t,e.stagedOverflowFailure=null),t.type==="compaction_end"&&t.reason==="overflow"&&t.willRetry===!1&&typeof t.errorMessage=="string"&&(e.stagedOverflowFailure={errorMessage:t.errorMessage}),t.type==="agent_settled"&&(this.agentRunActiveValue=!1,this.publishAndScheduleProviderRecovery(e)),this.deps.toolGroups.observeToolGroupEvent(t),this.deps.projection().relayEvent(t,e)}catch(n){u({level:"debug",event:"broker.runtime.diagnostic",fields:{message:`event relay threw: ${String(n)}`}})}}async publishAndScheduleProviderRecovery(e){try{if(await this.deps.faultRetry().publishSettledProviderFault(e),this.shutdownRequested){this.deps.disposeAndExit("shutdown-after-settle");return}await this.deps.faultRetry().schedule()}catch(t){this.deps.faultRetry().abandonTurnEnd(),u({level:"error",event:"broker.daemon.operation.failed",node_id:this.deps.nodeId,error:t,fields:{operation:"provider_fault_settlement"}}),this.shutdownRequested&&this.deps.disposeAndExit("shutdown-after-settle")}}ackTo(e,t,n=!0,r,a){this.deps.registry.sendFrame(e,{type:"ack",for:t,ok:n,...r!==void 0?{detail:r}:{},...a!==void 0?{id:a}:{}})}}export{K as RebindDriver};

package/dist/core/runtime/broker/retry-card-elision.d.ts

@@ -0,0 +1,7 @@
+import type { Agent, AgentMessage } from '@earendil-works/pi-agent-core';
+/** Remove fault-retry cards from a provider request. A card stays only when
+ *  removing it would leave two assistant turns adjacent — the one shape where
+ *  it is load-bearing rather than transcript bookkeeping. */
+export declare function elideRetryCards(messages: AgentMessage[]): AgentMessage[];
+/** Wrap the agent's context transform so every provider request omits retry cards. */
+export declare function installRetryCardElision(agent: Pick<Agent, 'transformContext'>): void;

package/dist/core/runtime/broker/retry-card-elision.js

@@ -0,0 +1 @@
+var i=Object.defineProperty;var e=(t,n)=>i(t,"name",{value:n,configurable:!0});import{CONNECTION_FAULT_RECOVERY_BODY as s,PROVIDER_FAULT_RECOVERY_BODY as l,RUN_CONNECTION_FAULT_RETRY_BODY as u,parseCard as a}from"../../../shared/generated-context.js";const f=new Set([s,u,l]);function c(t){if(t.role!=="user")return!1;const n=a(t);return n!==null&&n.kind==="recovery"&&n.facts.attempt!==void 0&&f.has(n.body)}e(c,"isRetryCard");function d(t){return t.role==="assistant"&&(t.stopReason==="error"||t.stopReason==="aborted")}e(d,"isDroppedAssistant");function R(t){let n=null;for(let r=0;r<t.length;r++){const o=t[r];if(c(o)&&!C(t,r)){n??=t.slice(0,r);continue}n?.push(o)}return n??t}e(R,"elideRetryCards");function C(t,n){for(let r=n-1;r>=0;r--){const o=t[r];if(!(o.role==="system"||d(o)))return o.role==="assistant"}return!1}e(C,"followsCompletedAssistant");function O(t){const n=t.transformContext;t.transformContext=async(r,o)=>R(n===void 0?r:await n(r,o))}e(O,"installRetryCardElision");export{R as elideRetryCards,O as installRetryCardElision};

package/dist/core/runtime/broker/run-deferred-mail.d.ts

@@ -0,0 +1,8 @@
+import type { BrokerSession } from './read-ops.js';
+/** Called after agent_settled, when Pi has persisted the turn's user entry. */
+export declare function settleRunDeferredMail(nodeId: string, session: BrokerSession): Promise<void>;
+/** Stage durable non-waking mail before the turn's own prompt. Do not retire its
+ * delivery until the user entry is persisted; on replay, the message ID in Pi's
+ * conversation avoids a second custom entry while a consumed marker avoids a
+ * second turn attribution. */
+export declare function prependRunDeferredMail(nodeId: string, session: BrokerSession): Promise<string[]>;

package/dist/core/runtime/broker/run-deferred-mail.js

@@ -0,0 +1 @@
+var w=Object.defineProperty;var c=(e,r)=>w(e,"name",{value:r,configurable:!0});import{acknowledgeBrokerMail as h,claimBrokerMail as _}from"./daemon-ops.js";const M=new Map,p=new Map;function u(e){const r=new Set;let n=[];for(const t of e.sessionManager.getBranch()){if(t.type==="custom"&&t.customType==="crtr-turn-input"){const a=t.data?.message_ids;Array.isArray(a)&&n.push(...a.filter(d=>typeof d=="string"))}if(t.type==="message"&&t.message.role==="user"){for(const a of n)r.add(a);n=[]}}return r}c(u,"consumedIds");async function g(e,r){if(r.length===0)return;const n=await h(e,r.map(({deliveryId:t,attempts:a})=>({delivery_id:t,attempts:a,disposition:"acknowledged"})));if(n.action!=="acknowledged"||n.results.some(t=>t.outcome!=="acknowledged"))throw new Error(`deferred run mail acknowledgement held for ${e}`)}c(g,"acknowledge");async function v(e,r){const n=p.get(e)??[],t=u(r),a=n.filter(o=>t.has(o.messageId));await g(e,a);const d=new Set(a.map(o=>`${o.deliveryId}:${o.attempts}`));p.set(e,(p.get(e)??[]).filter(o=>!d.has(`${o.deliveryId}:${o.attempts}`)))}c(v,"settleRunDeferredMail");async function S(e,r){const n=await _(e,"deferred_run",M);if(n.action==="hold")throw new Error(`deferred run mail claim held for ${e}`);const t=new Set(r.sessionManager.getBranch().flatMap(i=>i.type==="custom_message"&&i.customType==="app_message"?[String(i.details?.message_id??"")]:[])),a=u(r),d=[],o=[];for(const i of n.deliveries.sort((s,l)=>(s.entry.seq??0)-(l.entry.seq??0))){const{entry:s}=i,l={deliveryId:i.delivery_id,attempts:i.attempts,messageId:s.entry_id};if(a.has(s.entry_id)){await g(e,[l]);continue}if(!t.has(s.entry_id)){const m=s.from_name;if(!m?.startsWith("app:"))throw new Error(`deferred run message ${s.entry_id} has no app sender`);const f=s.data?.body;if(typeof f!="string")throw new Error(`deferred run message ${s.entry_id} has no body`);const y=m.replaceAll("&","&amp;").replaceAll('"',"&quot;").replaceAll("<","&lt;");await r.sendCustomMessage({customType:"app_message",content:`<app-message from="${y}">${f}</app-message>`,display:!0,details:{message_id:s.entry_id}},{triggerTurn:!1}),t.add(s.entry_id)}o.push(l),d.push(s.entry_id)}return p.set(e,o),d}c(S,"prependRunDeferredMail");export{S as prependRunDeferredMail,v as settleRunDeferredMail};

package/dist/core/runtime/broker/run-turn-end.d.ts

@@ -0,0 +1,38 @@
+import type { TurnError } from '../../llm/refusal.js';
+export declare const TURN_END_ENTRY = "crtr-turn-end";
+/** What a run node's `crtr-turn-end` entry records: the turn's last stop reason and its error, if any. */
+export type TurnEnd = {
+    stop_reason: string;
+    error?: TurnError;
+};
+type TurnEndWriter = {
+    appendCustomEntry(customType: string, data?: unknown): unknown;
+};
+/**
+ * When a run node's turn ends, as its run event stream sees it.
+ *
+ * A turn that settles on a provider failure the daemon will retry
+ * (connection, overloaded, rate limit, or a stalled stream) has not ended for
+ * the app: the recovery turn answers the same messages. Its `crtr-turn-end` is
+ * held back, and the recovery turn's own end closes the turn. The held-back end
+ * (with its error) is written only when no recovery will run: retries are
+ * exhausted or abandoned, or another prompt starts first.
+ */
+export declare class RunTurnEnds {
+    private held;
+    private recoveryStarting;
+    /** `agent_start`. A recovery turn takes over the held-back end; any other turn first closes it. */
+    started(): void;
+    /** `agent_settled`. `retryPending`: the daemon's fault retry may re-drive this turn. */
+    settled(writer: TurnEndWriter, end: TurnEnd, retryPending: boolean): void;
+    /** The daemon's fault retry is about to prompt its recovery turn. */
+    beginRecovery(): void;
+    /** The recovery prompt returned. If its turn never started (preflight failed or an input handler consumed it), no recovery runs. */
+    recoveryReturned(): void;
+    /** No recovery turn will run (retries exhausted or abandoned, the prompt failed, the session was replaced): end the turn now. */
+    abandon(): void;
+    /** Whether a turn end is held for a recovery turn. */
+    holding(): boolean;
+    private flush;
+}
+export {};

package/dist/core/runtime/broker/run-turn-end.js

@@ -0,0 +1 @@
+var h=Object.defineProperty;var n=(t,e)=>h(t,"name",{value:e,configurable:!0});const s="crtr-turn-end";class l{static{n(this,"RunTurnEnds")}held;recoveryStarting=!1;started(){if(this.recoveryStarting){this.recoveryStarting=!1,this.held=void 0;return}this.flush()}settled(e,r,i){this.flush(),i?this.held={writer:e,end:r}:e.appendCustomEntry(s,r)}beginRecovery(){this.recoveryStarting=!0}recoveryReturned(){this.recoveryStarting&&this.abandon()}abandon(){this.recoveryStarting=!1,this.flush()}holding(){return this.held!==void 0}flush(){const e=this.held;e!==void 0&&(this.held=void 0,e.writer.appendCustomEntry(s,e.end))}}export{l as RunTurnEnds,s as TURN_END_ENTRY};

package/dist/core/runtime/broker/run-turn-queue.d.ts

@@ -0,0 +1,48 @@
+import type { BrokerSession } from './read-ops.js';
+import type { TurnAdmissionGate } from './turn-admission.js';
+import type { BrokerIdleTurnStart } from './held-deferred-inbox.js';
+/**
+ * The broker's idle-turn lane for inbox-delivered prompts.
+ *
+ * A run node (`CRTR_INBOX_BETWEEN_TURNS=1`) admits each inbox prompt only
+ * between agent runs: a prompt that arrives while a turn is live, a session is
+ * being replaced, or the run's launch prompt has not yet run queues here and
+ * starts as its own turn once the engine settles.
+ *
+ * The launch-prompt hold is the ordering rule for a run's first turn: the
+ * prompt a run was started with is always its first turn's input. The broker
+ * arms the socket listener, re-arms provider recovery, and only then dispatches
+ * that prompt, while the inbox watcher is live from `session_start`. Without
+ * the hold, a `run.message` accepted in that window started its own turn ahead
+ * of the launch prompt (Doppel friction M10).
+ */
+export type RunTurnQueue = {
+    /** Start (or queue) one inbox-delivered idle turn. */
+    start: BrokerIdleTurnStart;
+    /** Start the next queued prompt if the engine is free. */
+    drain(): void;
+    /** Whether a run node must not start an inbox turn now. */
+    busy(): boolean;
+    /** The launch prompt will be dispatched; hold inbox turns behind it. */
+    holdForKickoff(): void;
+    /** The launch prompt ran (or will not run); release held inbox turns. */
+    releaseKickoff(): void;
+    /** Prompts queued behind a live turn or the launch prompt, oldest first. */
+    queued(): ReadonlyArray<{
+        text: string;
+        messageIds: string[];
+    }>;
+};
+export type RunTurnQueueDeps = {
+    runNode: boolean;
+    session: () => BrokerSession;
+    isReplacing: () => boolean;
+    isAgentRunActive: () => boolean;
+    /** Frame/kickoff prompt dispatches still igniting. Zero before the frame
+     *  dispatcher exists. */
+    pendingDispatches: () => number;
+    turnAdmission: TurnAdmissionGate;
+    prependDeferred: (session: BrokerSession) => Promise<string[]>;
+    onError: (error: unknown) => void;
+};
+export declare function createRunTurnQueue(deps: RunTurnQueueDeps): RunTurnQueue;

package/dist/core/runtime/broker/run-turn-queue.js

@@ -0,0 +1 @@
+var v=Object.defineProperty;var n=(t,e)=>v(t,"name",{value:e,configurable:!0});function A(t){const{runNode:e,session:a,turnAdmission:d}=t,u=[];let o=!1,r=!1;const p=n(()=>t.isReplacing()||t.isAgentRunActive()||a().isStreaming,"engineBusy"),l=n(()=>r||o||p(),"mustQueue"),c=n(()=>{if(l())return;const i=u.shift();i&&g(i.text,i.messageIds)},"drain"),g=n((i,f=[])=>{if(e&&l()){u.push({text:i,messageIds:f});return}e&&(o=!0),d.admit(async h=>{const s=a();if(e&&s.isStreaming)return u.unshift({text:i,messageIds:f}),h(),Promise.resolve();const m=e?await t.prependDeferred(s):[];return e&&f.length+m.length>0&&s.sessionManager.appendCustomEntry("crtr-turn-input",{message_ids:[...m,...f]}),s.prompt(i,{preflightResult:h,...!e&&s.isStreaming?{streamingBehavior:"steer"}:{}})}).catch(t.onError).finally(()=>{e&&(o=!1,c())})},"start");return{start:g,drain:c,busy:n(()=>r||o||t.pendingDispatches()>0||t.isAgentRunActive()||a().isStreaming,"busy"),holdForKickoff:n(()=>{e&&(r=!0)},"holdForKickoff"),releaseKickoff:n(()=>{r&&(r=!1,c())},"releaseKickoff"),queued:n(()=>u,"queued")}}n(A,"createRunTurnQueue");export{A as createRunTurnQueue};

package/dist/core/runtime/broker/signal-stream.d.ts

@@ -0,0 +1,30 @@
+import type { BrokerExtensionNodeDTO } from '../../../api/dto/broker-ops.js';
+export type BrokerSignalState = 'disconnected' | 'connected' | 'unsupported' | 'stopped';
+export type BrokerSignalEvent = 'mail' | 'resync' | 'node' | 'fault-retry';
+type Listener = () => void;
+export declare class BrokerSignalClient {
+    private stateValue;
+    private latestNodeValue;
+    private readonly listeners;
+    private controller;
+    private retryTimer;
+    private heartbeatTimer;
+    private retryMs;
+    private running;
+    private nodeId;
+    private executionId;
+    get state(): BrokerSignalState;
+    /** The last hello/node projection; not an authoritative delivery or settlement read. */
+    get latestNode(): BrokerExtensionNodeDTO | undefined;
+    subscribe(event: BrokerSignalEvent | 'state', listener: Listener): () => void;
+    start(nodeId: string, executionId: string): void;
+    stop(): void;
+    private emit;
+    private setState;
+    private clearTimers;
+    private armHeartbeat;
+    private connect;
+    private handleLine;
+}
+export declare function brokerSignalClient(): BrokerSignalClient;
+export {};

package/dist/core/runtime/broker/signal-stream.js

@@ -0,0 +1 @@
+var a=Object.defineProperty;var s=(i,t)=>a(i,"name",{value:t,configurable:!0});import{localClient as o}from"../../../api/node-transport.js";import{ApiError as n}from"../../../api/errors.js";const h=Symbol.for("@crouton-kit/crtr:broker-signal-client");class l{static{s(this,"BrokerSignalClient")}stateValue="disconnected";latestNodeValue;listeners=new Map;controller;retryTimer;heartbeatTimer;retryMs=250;running=!1;nodeId;executionId;get state(){return this.stateValue}get latestNode(){return this.latestNodeValue}subscribe(t,r){let e=this.listeners.get(t);return e||(e=new Set,this.listeners.set(t,e)),e.add(r),(t==="state"||t==="resync"&&this.stateValue==="connected"||t==="node"&&this.latestNodeValue!==void 0)&&r(),()=>{e.delete(r)}}start(t,r){if(this.running){if(this.nodeId===t&&this.executionId===r)return;this.stop()}this.nodeId=t,this.executionId=r,this.running=!0,this.retryMs=250,this.connect()}stop(){this.running=!1,this.controller?.abort(),this.controller=void 0,this.clearTimers(),this.setState("stopped")}emit(t){for(const r of this.listeners.get(t)??[])try{r()}catch{}}setState(t){this.stateValue!==t&&(this.stateValue=t,this.emit("state"))}clearTimers(){this.retryTimer&&clearTimeout(this.retryTimer),this.heartbeatTimer&&clearTimeout(this.heartbeatTimer),this.retryTimer=this.heartbeatTimer=void 0}armHeartbeat(t){this.heartbeatTimer&&clearTimeout(this.heartbeatTimer),this.heartbeatTimer=setTimeout(()=>t.abort(),35e3),this.heartbeatTimer.unref?.()}connect(){if(!this.running||!this.nodeId||!this.executionId)return;const t=new AbortController;this.controller=t,(async()=>{try{for await(const e of o({autostart:!1}).getBrokerSignals(this.nodeId,this.executionId,{signal:t.signal,maxRetries:0})){if(!this.running||this.controller!==t)return;this.armHeartbeat(t),this.handleLine(e)}}catch(e){if(!this.running||this.controller!==t)return;if(e instanceof n&&(e.status===404||e.status===405)){this.clearTimers(),this.controller=void 0,this.setState("unsupported");return}if(e instanceof n&&e.status===409){this.stop();return}}if(!this.running||this.controller!==t)return;this.controller=void 0,this.clearTimers(),this.setState("disconnected");const r=Math.round(this.retryMs*(.8+Math.random()*.4));this.retryMs=Math.min(this.retryMs*2,5e3),this.retryTimer=setTimeout(()=>{this.retryTimer=void 0,this.connect()},r),this.retryTimer.unref?.()})()}handleLine(t){switch(t.type){case"hello":if(t.execution_id!==this.executionId){this.stop();return}this.retryMs=250,this.latestNodeValue=t.node,this.setState("connected"),this.emit("node"),this.emit("resync");break;case"mail":this.emit("mail");break;case"node":this.latestNodeValue=t.node,this.emit("node");break;case"fault-retry":this.emit("fault-retry");break;case"ping":break}}}function m(){const i=globalThis;return i[h]??=new l}s(m,"brokerSignalClient");export{l as BrokerSignalClient,m as brokerSignalClient};

package/dist/core/runtime/broker/tool-groups.d.ts

@@ -0,0 +1,39 @@
+import { type ToolGroupSummary } from '../../../shared/tool-groups.js';
+import type { BrokerToClient } from '../broker-protocol.js';
+/** Owns transcript tool-group state and its durable summary sidecars. */
+export declare class ToolGroupTracker {
+    private readonly broadcast;
+    private readonly toolSummariesPath;
+    private readonly pendingToolSummaryPath;
+    private readonly toolGroupSummaries;
+    private readonly summaryAttempted;
+    private readonly generatingToolGroups;
+    private readonly toolGroupsByCallId;
+    private readonly summaryTasks;
+    private openToolGroup;
+    private lastToolGroupBoundaryProse;
+    private sawAssistantProse;
+    constructor(nodeId: string, broadcast: (frame: BrokerToClient) => void);
+    summaries(): Record<string, ToolGroupSummary>;
+    resetForSession(): void;
+    finishOpenToolGroup(settleInterruptedTools?: boolean): void;
+    observeToolGroupEvent(event: {
+        type?: string;
+        message?: unknown;
+        toolCallId?: unknown;
+        toolName?: unknown;
+        args?: unknown;
+        result?: unknown;
+        isError?: unknown;
+        success?: unknown;
+    }): void;
+    persistPendingSummary(): void;
+    hasSummaryTasks(): boolean;
+    waitForSummaryTasks(): Promise<PromiseSettledResult<void>[]>;
+    private ensureOpenToolGroup;
+    private visibleBoundary;
+    private clearPendingToolGroupSummary;
+    private generateToolGroupSummary;
+    private generateSettledToolGroup;
+    private resumePendingSummary;
+}

package/dist/core/runtime/broker/tool-groups.js

@@ -0,0 +1 @@
+var T=Object.defineProperty;var l=(a,e)=>T(a,"name",{value:e,configurable:!0});import{existsSync as G,unlinkSync as u}from"node:fs";import{join as d}from"node:path";import{nodeRunJobDir as y}from"../../canvas/paths.js";import{readConfig as S}from"../../config.js";import{emitEvent as m}from"../../events/emit.js";import{atomicWriteJson as h,readJsonIfExists as p}from"../../fs-utils.js";import{assistantVisibleText as k,isGroupBoundaryKind as P,isTrueUserMessage as _,normalizeToolGroupSummaryRecord as b}from"../../../shared/tool-groups.js";import{generatedContextText as f,parseCard as I}from"../../../shared/generated-context.js";import{headlessToolGroupSummary as w,serializeToolGroup as A}from"../tool-group-summary.js";const C=1e3,O=1e4;function g(a){if(a===null||typeof a!="object"||Array.isArray(a))return null;const e=a;return Object.keys(e).sort().join(",")!=="key,segment,version"||e.version!==1||typeof e.key!="string"||typeof e.segment!="string"||e.key.length===0||e.key.length>C||e.segment.length===0||e.segment.length>O?null:{version:1,key:e.key,segment:e.segment}}l(g,"normalizePendingToolGroupSummary");class J{static{l(this,"ToolGroupTracker")}broadcast;toolSummariesPath;pendingToolSummaryPath;toolGroupSummaries=new Map;summaryAttempted;generatingToolGroups=new Map;toolGroupsByCallId=new Map;summaryTasks=new Set;openToolGroup;lastToolGroupBoundaryProse="";sawAssistantProse=!1;constructor(e,o){this.broadcast=o,this.toolSummariesPath=d(y(e),"tool-summaries.json"),this.pendingToolSummaryPath=d(y(e),"pending-tool-summary.json");try{const t=p(this.toolSummariesPath);for(const[i,n]of Object.entries(b(t)))this.toolGroupSummaries.set(i,n)}catch{}this.summaryAttempted=new Set(this.toolGroupSummaries.keys()),this.resumePendingSummary()}summaries(){return Object.fromEntries(this.toolGroupSummaries)}resetForSession(){this.openToolGroup=void 0,this.toolGroupsByCallId.clear(),this.sawAssistantProse=!1}finishOpenToolGroup(e=!1){const o=this.openToolGroup;if(this.openToolGroup=void 0,o!==void 0){if(o.closed=!0,e){for(const t of o.pendingToolIds)this.toolGroupsByCallId.delete(t);o.pendingToolIds.clear()}o.summarizeWhenSettled=S("user").summarize_tool_calls,this.generateSettledToolGroup(o)}}observeToolGroupEvent(e){if(e.type==="compaction_end"||e.type==="auto_retry_end"&&e.success!==!0){this.finishOpenToolGroup();return}if(e.type==="message_end"){const s=e.message;if(s!==null&&typeof s=="object"){const r=s;r.role==="assistant"&&(r.stopReason==="aborted"||r.stopReason==="error")&&this.finishOpenToolGroup(!0)}return}if(e.type==="tool_execution_start"){const s=this.ensureOpenToolGroup(),r=typeof e.toolCallId=="string"?e.toolCallId:"";s.key===void 0&&r!==""&&(s.key=r),r!==""&&(s.pendingToolIds.add(r),this.toolGroupsByCallId.set(r,s)),s.toolCount+=1,s.pieces.push({type:"tool",name:typeof e.toolName=="string"?e.toolName:"tool",args:e.args});return}if(e.type==="tool_execution_end"){const s=typeof e.toolCallId=="string"?e.toolCallId:"",r=s===""?this.openToolGroup:this.toolGroupsByCallId.get(s);r!==void 0&&(r.pieces.push({type:"result",name:typeof e.toolName=="string"?e.toolName:"tool",result:e.result,isError:e.isError===!0}),s!==""&&(r.pendingToolIds.delete(s),this.toolGroupsByCallId.delete(s)),this.generateSettledToolGroup(r));return}if(e.type!=="message_start"&&e.type!=="message_update")return;const o=e.message;if(o===null||typeof o!="object")return;const t=o;if(t.role==="assistant"){e.type==="message_start"&&(this.sawAssistantProse=!1);const s=k(t);!this.sawAssistantProse&&s.trim()!==""&&(this.sawAssistantProse=!0,this.visibleBoundary(s));return}if(e.type!=="message_start")return;if(t.role==="compactionSummary"||t.role==="branchSummary"||t.role==="bashExecution"||t.role==="status"||t.role==="error"||t.customType==="crtr-cycle-divider"){this.finishOpenToolGroup();return}if(_(t)){this.visibleBoundary(f(t));return}if(t.display===!1)return;const i=f(t),n=I(t);if(n!==null&&P(n.kind)){this.visibleBoundary(i);return}const c=this.ensureOpenToolGroup();i!==""&&c.pieces.push({type:"text",text:i})}persistPendingSummary(){const e=[...this.generatingToolGroups.values()].at(-1);if(e!==void 0)try{h(this.pendingToolSummaryPath,e)}catch(o){m({level:"warn",event:"broker.runtime.diagnostic",fields:{message:`failed to persist pending tool summary: ${o instanceof Error?o.message:String(o)}`}})}}hasSummaryTasks(){return this.summaryTasks.size>0}waitForSummaryTasks(){return Promise.allSettled([...this.summaryTasks])}ensureOpenToolGroup(){return this.openToolGroup===void 0&&(this.openToolGroup={toolCount:0,pieces:[],boundaryProse:this.lastToolGroupBoundaryProse,pendingToolIds:new Set,closed:!1,summarizeWhenSettled:!1}),this.openToolGroup}visibleBoundary(e){this.finishOpenToolGroup(),this.lastToolGroupBoundaryProse=e}clearPendingToolGroupSummary(e){try{const o=g(p(this.pendingToolSummaryPath));o?.key===e.key&&o.segment===e.segment&&u(this.pendingToolSummaryPath)}catch{}}generateToolGroupSummary(e){const{key:o,segment:t}=e;if(this.summaryAttempted.has(o)||this.generatingToolGroups.has(o))return;this.summaryAttempted.add(o),this.generatingToolGroups.set(o,e);let i;i=w(t).then(n=>{if(n!==null){this.toolGroupSummaries.set(o,n);try{h(this.toolSummariesPath,Object.fromEntries(this.toolGroupSummaries))}catch{this.toolGroupSummaries.delete(o);return}this.clearPendingToolGroupSummary(e),this.broadcast({type:"tool_group_summary",key:o,summary:n})}}).catch(()=>{}).finally(()=>{this.generatingToolGroups.delete(o),this.summaryTasks.delete(i)}),this.summaryTasks.add(i)}generateSettledToolGroup(e){!e.closed||e.pendingToolIds.size>0||e.key===void 0||!e.summarizeWhenSettled||this.generateToolGroupSummary({version:1,key:e.key,segment:A(e.boundaryProse,e.pieces)})}resumePendingSummary(){try{const e=g(p(this.pendingToolSummaryPath));e===null?G(this.pendingToolSummaryPath)&&(u(this.pendingToolSummaryPath),m({level:"warn",event:"broker.startup.warning",fields:{stage:"pending_tool_summary",message:"removed an invalid pending tool summary"}})):this.toolGroupSummaries.has(e.key)?u(this.pendingToolSummaryPath):this.generateToolGroupSummary(e)}catch(e){m({level:"warn",event:"broker.startup.warning",fields:{stage:"pending_tool_summary",message:e instanceof Error?e.message:String(e)}})}}}export{J as ToolGroupTracker};

package/dist/core/runtime/broker/turn-admission.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Serializes entry into AgentSession.prompt() until its preflight has decided
+ * whether it will start (or join) a run. AgentSession.isStreaming stays false
+ * through asynchronous preflight, so checking it before entering prompt() lets
+ * two calls reach the SDK's active-run ownership race. Each waiter therefore
+ * re-reads live state only after the preceding prompt has reported preflight.
+ */
+export type TurnAdmissionGate = {
+    admit<T>(start: (release: () => void) => Promise<T>): Promise<T>;
+};
+export declare function createTurnAdmissionGate(): TurnAdmissionGate;

package/dist/core/runtime/broker/turn-admission.js

@@ -0,0 +1 @@
+var c=Object.defineProperty;var s=(e,o)=>c(e,"name",{value:o,configurable:!0});function d(){let e=Promise.resolve();return{admit(o){const i=e;let a;const l=new Promise(t=>{a=t});return e=i.then(()=>l),i.then(()=>{let t=!1;const r=s(()=>{t||(t=!0,a())},"release");try{const n=o(r);return n.then(r,r),n}catch(n){throw r(),n}})}}}s(d,"createTurnAdmissionGate");export{d as createTurnAdmissionGate};

package/dist/core/runtime/broker/turn-ignition.d.ts

@@ -0,0 +1,49 @@
+import type { BrokerSession } from './read-ops.js';
+import type { TurnAdmissionGate } from './turn-admission.js';
+/**
+ * Prompt dispatches whose promise has not yet settled. `session.prompt()` does
+ * async setup (input transforms, model/auth validation, compaction) BEFORE
+ * `_isAgentRunActive` flips, so for a short window after a routed deliver the
+ * engine reads idle and `session.abort()` is a silent no-op — an interrupt
+ * racing that window would miss the turn entirely (verified live). The counter
+ * lets a caller distinguish "genuinely idle" from "turn still igniting".
+ */
+export type PromptDispatchTracker = {
+    track(p: Promise<unknown>): Promise<unknown>;
+    pending(): number;
+    /** Wait (bounded) for a pending dispatch to reach an abortable turn — or for
+     *  every dispatch to settle without one (an early return). Returns
+     *  immediately when the engine is already streaming or nothing is pending. */
+    waitUntilAbortable(): Promise<void>;
+};
+export declare function createPromptDispatchTracker(session: () => BrokerSession): PromptDispatchTracker;
+/**
+ * The one-shot waiters a `deliver` frame parks until its prompt is ACCEPTED by
+ * the engine (the broker's `agent_start`). Every waiter fires once, on the
+ * first acceptance after it was added.
+ */
+export type TurnAcceptanceGate = {
+    waitFor(waiter: () => void): void;
+    cancel(waiter: () => void): void;
+    notifyAccepted(): void;
+};
+export declare function createTurnAcceptanceGate(): TurnAcceptanceGate;
+/**
+ * The launch prompt, held until the session actually has a model. A model-less
+ * tier-3 boot leaves it pending; `drivePending` is a no-op while the session
+ * has no model, and the engine-control handler calls it again once a viewer
+ * installs one (set_model, cycle_model, ladder).
+ */
+export type KickoffDriver = {
+    kickoff(prompt: string, messageIds?: string[]): void;
+    drivePending(): void;
+};
+export declare function createKickoffDriver(deps: {
+    session: () => BrokerSession;
+    dispatches: PromptDispatchTracker;
+    turnAdmission: TurnAdmissionGate;
+    prependDeferred?: (session: BrokerSession) => Promise<string[]>;
+    /** The launch prompt holds the admission gate and is about to enter
+     *  `prompt()`; anything admitted after this sees its turn. */
+    onAdmitted?: () => void;
+}): KickoffDriver;

package/dist/core/runtime/broker/turn-ignition.js

@@ -0,0 +1 @@
+var g=Object.defineProperty;var r=(t,e)=>g(t,"name",{value:e,configurable:!0});import{emitEvent as w}from"../../events/emit.js";import{operationIdContext as h}from"../../events/operation-id.js";import{isUnknownModel as v}from"../model-selection.js";const A=5e3,k=25;function S(t){let e=0;return{track(n){e++;const i=Promise.resolve(n);return i.finally(()=>{e--}),i},pending:r(()=>e,"pending"),async waitUntilAbortable(){if(t().isStreaming||e===0)return;const n=Date.now()+A;for(;Date.now()<n&&!t().isStreaming&&e>0;)await new Promise(i=>setTimeout(i,k))}}}r(S,"createPromptDispatchTracker");function T(){const t=new Set;return{waitFor:r(e=>{t.add(e)},"waitFor"),cancel:r(e=>{t.delete(e)},"cancel"),notifyAccepted(){const e=[...t];t.clear();for(const n of e)n()}}}r(T,"createTurnAcceptanceGate");function B(t){const{session:e,dispatches:n,turnAdmission:i}=t;let a,c=[],o=!1;const m=r(()=>e().model===void 0||v(e().model),"sessionHasNoModel"),p=r(()=>{a===void 0||o||m()||(o=!0,i.admit(async s=>{const d=a;if(d===void 0||m())return s(),o=!1,Promise.resolve();const u=c;let f;try{f=await t.prependDeferred?.(e())??[]}catch(l){throw s(),o=!1,l}return a=void 0,c=[],t.onAdmitted?.(),u.length+f.length>0&&e().sessionManager.appendCustomEntry("crtr-turn-input",{message_ids:[...f,...u]}),n.track(h.fresh(()=>e().prompt(d,{preflightResult:s,...e().isStreaming?{streamingBehavior:"steer"}:{}}).catch(l=>{w({level:"error",event:"broker.prompt.first_failed",error:l})}).finally(()=>{o=!1})))}))},"drivePending");return{kickoff(s,d=[]){a=s,c=d,p()},drivePending:p}}r(B,"createKickoffDriver");export{B as createKickoffDriver,S as createPromptDispatchTracker,T as createTurnAcceptanceGate};

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

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

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

@@ -0,0 +1,3 @@
+var c=Object.defineProperty;var n=(e,r)=>c(e,"name",{value:r,configurable:!0});import{isSafeNodeId as d}from"../canvas/paths.js";import{emitEvent as p,flushBrokerLog as u}from"../events/emit.js";import{mark as a,timingProc as f}from"../timing.js";const l=process.hrtime.bigint(),m=new Date().toISOString(),t=process.argv.length>2?process.argv.at(-1):void 0;(t===void 0||!d(t))&&(process.stderr.write(`[broker] usage: broker-cli [--canvas-home <path>] [--epoch <id>] <nodeId>
+`),process.exit(1)),f("broker"),a("broker.entry",{node:t});const{runBroker:h,disposeActiveSession:g}=await import("./broker.js");a("broker.module_loaded");function s(e){try{g()}catch{}u().finally(()=>process.exit(e))}n(s,"disposeAndExit");function i(e,r){let o;try{o=p({level:"error",event:"broker.runtime.fatal",error:r,fields:{origin:e}})}catch{o=!1}o||process.stderr.write(`[broker] fatal (${e}): ${r instanceof Error?r.stack??r.message:String(r)}
+`)}n(i,"reportFatal"),process.on("uncaughtException",e=>{i("uncaughtException",e),s(1)}),process.on("unhandledRejection",e=>{i("unhandledRejection",e),s(1)}),h(t,l,m).catch(e=>{i("run_failure",e),s(1)});

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

@@ -0,0 +1,3 @@
+import type { BrokerExtensionNodeDTO, BrokerExtensionStateDTO } from '../../api/dto/broker-ops.js';
+export declare function editorLabelForBrokerNode(node: BrokerExtensionNodeDTO): string;
+export declare function buildForkBearingsFromState(state: BrokerExtensionStateDTO, situational?: string): string;

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

@@ -0,0 +1,3 @@
+var u=Object.defineProperty;var i=(e,r)=>u(e,"name",{value:r,configurable:!0});import{fullName as h}from"../canvas/labels.js";import{profileNote as f,renderGraphMap as p,buildIdentityAssertion as m,forkContextNote as g,orchestratorContextNote as w,worktreeNote as k}from"./bearings-render.js";function S(e){const r=(e.icon??"").trim(),t=e.name!==e.kind?e.name.trim():"",n=t!==""?t:(e.description??"").trim()||e.name;return r===""?n:`${r} ${n}`}i(S,"editorLabelForBrokerNode");function y(e){return f(e.cwd,e.profile_id)}i(y,"profileNote");function b(e){const{ancestors:r,children:t,node:n}=e;return p(n.node_id,n.kind,n.mode,r,t)}i(b,"graphMap");function v(e){const{node:r,fork_source:t}=e,n=t===null?r.fork_from??"":`${r.fork_from} ("${h(t)}")`;return m(r.node_id,r.kind,r.mode,r.fork_from,n)}i(v,"identity");function _(e){return k(e.managed_worktree)}i(_,"worktreeNote");function x(e){const r=e.review_binding;if(r==null)return"";if(r.kind==="page_feedback"){const t=r.review_id,n=r.target_file;return`You exist for one page's feedback conversation \u2014 ticket \`${t}\`, page source \`${n}\`. Think with the person about this one page and answer in a few plain sentences from the context you already carry. Revise the page in place with \`crtr human send --replace ${t} --page ${n}\` \u2014 it swaps in on their screen immediately \u2014 and briefly say what changed; a silent swap leaves them guessing. After dealing with an open feedback item \u2014 by revising the page or answering it here \u2014 resolve it with \`crtr human feedback resolve <comment_id>\`; \`crtr human feedback list ${t}\` shows each item's id and status. Never author feedback or resolve an item before dealing with it \u2014 a sent comment is immutable, and resolution is your report that the work is done. Asked to act beyond this page, give your advice and point the person at submitting it: the submitted answer is what reaches the task's owner, while work done here is invisible to it and ends when the ticket settles. When a question needs real exploration, delegate it to a child node and keep talking while it runs. The inherited conversation belongs to the origin node, not you \u2014 its task stays with it; carry only the context needed for this page. The person's visible transcript begins at the boundary marker above; everything earlier is context they cannot see \u2014 never treat it as shared ground; when they ask about it, answer plainly in your own words rather than replaying it.`}return`You exist for one human review of \`${r.target_file}\`. The inherited conversation belongs to the origin node, not you \u2014 carry only the context needed for this review. The person's visible transcript begins at the boundary marker above; everything earlier is context they cannot see.`}i(x,"reviewNote");function F(e,r=""){const{node:t,fork_source:n}=e,l=n?.status==="active"||n?.status==="idle"?`Source node ${n.node_id} ("${h(n)}") is still live and still holds the mandate from the copied conversation; do not resume that work here.`:"The source node\u2019s earlier graph position, lifecycle, children, schedules, worktree, situational context, and context-directory path do not carry over. Shared conversation, project, and operating context remain reference material.",o=["<crtr-bearings>",v(e),"",l,"","## Your node now",`Lifecycle: ${t.lifecycle}.`],s=b(e);if(o.push(...s===""?["Canvas: independent root with no parent or inherited graph edges."]:["",s]),o.push(g(t.node_id,t.grantee,t.fork_from??"")),(n===null||n.cwd!==t.cwd)&&o.push(`Working directory: \`${t.cwd}\`.`),n===null||n.profile_id!==t.profile_id){const a=y(t);a!==""&&o.push(a)}const d=_(t);d!==""&&o.push("","## Your managed worktree",d),t.mode==="orchestrator"&&o.push("",w());const c=x(t);return c!==""&&o.push("",c),o.push("","The first real user message after these bearings is your mandate.","</crtr-bearings>"),[o.join(`
+`),r].filter(a=>a!=="").join(`
+`)}i(F,"buildForkBearingsFromState");export{F as buildForkBearingsFromState,S as editorLabelForBrokerNode};

package/dist/core/runtime/broker-inventory.d.ts

@@ -0,0 +1,4 @@
+import type { ChatInventoryDTO } from '../../api/dto/chat-inventory.js';
+/** Collect the chat inventories for one node. Always resolves — every failure
+ *  mode is expressed in the returned document, not thrown. */
+export declare function readChatInventory(nodeId: string): Promise<ChatInventoryDTO>;

package/dist/core/runtime/broker-inventory.js

@@ -0,0 +1 @@
+var _=Object.defineProperty;var n=(o,r)=>_(o,"name",{value:r,configurable:!0});import{randomUUID as y}from"node:crypto";import{getNode as p}from"../canvas/canvas.js";import{BrokerClient as h}from"../broker-client/index.js";import{gatewayCommandRowsFromDetail as k,gatewayMemoryRows as v}from"./chat-inventory-rows.js";import{isBrokerLive as w}from"./model-swap.js";const T=15e3,g=1,C=n(o=>({node_id:o,broker_live:!1,commands:[],memory_refs:[]}),"empty");function S(o){const r=p(o);return r===null||!w(r)?Promise.resolve(C(o)):new Promise(a=>{const e=new h(o),u=y();let f=!1,d=!1,i,s;const l=setTimeout(()=>m(),T);typeof l.unref=="function"&&l.unref();function m(){if(!f){f=!0,clearTimeout(l);try{e.close()}catch{}a({node_id:o,broker_live:d,commands:i??[],memory_refs:s??[]})}}n(m,"finish");function c(){i!==void 0&&s!==void 0&&m()}n(c,"settleWhenComplete"),e.on("error",()=>m()),e.on("close",()=>m()),e.on("connect",()=>{d=!0,e.send({type:"hello",role:"observer",client_id:u,snapshot_tail:g}),e.send({type:"get_commands"}),e.request({type:"list_memory_refs"}).then(t=>{s=t.kind==="list_memory_refs"?v(t.refs):[],c()},()=>{s=[],c()})}),e.on("frame",t=>{if(t.type==="ack"&&t.for==="get_commands"){i=t.ok?k(t.detail):[],c();return}t.type==="error"&&t.id===void 0&&(i??=[],c())}),e.connect()})}n(S,"readChatInventory");export{S as readChatInventory};

package/dist/core/runtime/broker-persona-guidance.d.ts

@@ -0,0 +1,27 @@
+import type { Agent } from '@earendil-works/pi-agent-core';
+import type { BrokerExtensionStateDTO } from '../../api/dto/broker-ops.js';
+export interface BrokerPersona {
+    kind: string;
+    mode: 'base' | 'orchestrator';
+    lifecycle: 'terminal' | 'resident';
+}
+export interface BrokerPersonaDrift {
+    from: BrokerPersona;
+    to: BrokerPersona;
+}
+export declare function personaDriftFromBrokerState(state: BrokerExtensionStateDTO): BrokerPersonaDrift | null;
+/** A new context's current snapshots make a rank delta unnecessary. */
+export declare function acknowledgePersonaBaseline(state: BrokerExtensionStateDTO): Promise<boolean>;
+/** Append pending transitions until the delivered persona matches current canvas state. */
+export declare function deliverPendingPersonaTransition(initialState: BrokerExtensionStateDTO, deliver: (content: string) => void | Promise<void>): Promise<boolean>;
+interface PersonaTransitionSession {
+    agent: Pick<Agent, 'state' | 'transformContext'>;
+    sessionManager: {
+        appendCustomMessageEntry: (customType: string, content: string, display: boolean, details?: {
+            nodeId: string;
+        }) => unknown;
+    };
+}
+/** Gate each provider request on durable delivery of the current persona delta. */
+export declare function installPersonaTransitionGate(nodeId: string, session: PersonaTransitionSession, noteFailure?: () => void): void;
+export {};

package/dist/core/runtime/broker-persona-guidance.js

@@ -0,0 +1,4 @@
+var g=Object.defineProperty;var a=(n,e)=>g(n,"name",{value:e,configurable:!0});import{emitEvent as b}from"../events/emit.js";import{brokerDelivery as v,brokerExtensionState as p,commitBrokerPersonaAck as m}from"./broker/daemon-ops.js";import{buildSubPersonaMenu as h}from"../substrate/delivery/sub-persona-menu.js";import{orchestratorContextNote as x}from"./bearings-render.js";import{formatCard as T}from"../../shared/generated-context.js";function C(n){return[`You are now a ${n.kind.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.","","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 the approach below.","",x(),"","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."].join(`
+`)}a(C,"orchestrationGuidance");function P(){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."}a(P,"baseModeGuidance");function S(n,e){if(n.kind===e.kind)return"";const r=h(n.kind),o=h(e.kind);return r===o?"":o===""?`The ${e.kind} kind has no specialist sub-personas available.`:o}a(S,"subPersonaGuidance");function D(n,e,r,o){const t=[];return e.mode!==r.mode&&t.push(r.mode==="orchestrator"?C(n.node):P()),t.push(S(e,r)),t.push(o),t.filter(i=>i!=="").join(`
+
+`)}a(D,"transitionGuidance");function u(n){const e=n.node,r={kind:e.kind,mode:e.mode,lifecycle:e.lifecycle},o=e.persona_ack,t=o===void 0?r:{kind:o.kind??e.kind,mode:o.mode,lifecycle:o.lifecycle};return t.kind===r.kind&&t.mode===r.mode&&t.lifecycle===r.lifecycle?null:{from:t,to:r}}a(u,"personaDriftFromBrokerState");async function B(n){const e=u(n);if(e===null)return!1;if(!(await m(n.node.node_id,e)).applied)throw new Error(`persona baseline acknowledgment was rejected for ${n.node.node_id}`);return!0}a(B,"acknowledgePersonaBaseline");async function Y(n,e){const r=n.node.node_id;let o=n,t=u(o);if(t===null)return!1;let i=t.from;for(;;){const s={kind:o.node.kind,mode:o.node.mode,lifecycle:o.node.lifecycle};if(i.kind!==s.kind||i.mode!==s.mode||i.lifecycle!==s.lifecycle){const d=await v(r,{activity:"persona"}),c=D(o,i,s,d.content);c!==""&&await e(T("persona-transition",{},c)),i=s}if(t=u(o),t===null||(await m(r,t)).applied)return!0;o=await p(r)}}a(Y,"deliverPendingPersonaTransition");function H(n,e,r=()=>{}){const{agent:o}=e,t=o.transformContext;o.transformContext=async(i,s)=>{const l=t===void 0?i:await t(i,s);try{const d=await p(n);return await Y(d,c=>{const f={nodeId:n},w={role:"custom",customType:"crtr-persona-transition",content:c,display:!0,details:f,timestamp:Date.now()};e.sessionManager.appendCustomMessageEntry("crtr-persona-transition",c,!0,f);const y=o.state.messages;for(const k of new Set([y,i,l]))k.push(w)}),l}catch(d){throw r(),b({event:"broker.daemon.operation.failed",level:"error",node_id:n,error:d,fields:{operation:"persona_transition"}}),d}}}a(H,"installPersonaTransitionGate");export{B as acknowledgePersonaBaseline,Y as deliverPendingPersonaTransition,H as installPersonaTransitionGate,u as personaDriftFromBrokerState};