@north-light/cli 0.0.0 → 0.3.414

package/dist/core/runs/confinement.js

@@ -0,0 +1,2 @@
+var _=Object.defineProperty;var n=(e,r)=>_(e,"name",{value:r,configurable:!0});import{openDb as o,prepared as i}from"../canvas/db.js";function u(e,r=o()){const t=i(r,`SELECT n.run_id, n.isolated, r.isolated AS root_isolated FROM nodes n
+    LEFT JOIN nodes r ON r.node_id = n.run_id WHERE n.node_id = ?`).get(e);if(!t){const d=i(r,"SELECT run_id FROM deleted_isolated_nodes WHERE node_id = ?").get(e);return d?{run:d.run_id,isolated:!0}:null}return{run:t.run_id??e,isolated:t.isolated===1||t.root_isolated===1}}n(u,"runPlace");function f(e,r=o()){const t=u(e,r);t?.isolated&&i(r,"INSERT OR REPLACE INTO deleted_isolated_nodes (node_id, run_id) VALUES (?, ?)").run(e,t.run)}n(f,"rememberDeletedIsolated");function R(e,r=o()){const t=i(r,"SELECT registered_by FROM custom_objects WHERE object = ?").get(e);return t?.registered_by?u(t.registered_by,r)??{run:t.registered_by,isolated:!1}:null}n(R,"objectPlace");function c(e,r){return e.run===r.run||!e.isolated&&!r.isolated}n(c,"runsSeeEachOther");function O(e,r,t,d,l=o()){if((d??"app:terminal")!==r)return!0;const s=u(e,l);if(!s)return!0;const a=u(t,l);return a===null?!s.isolated:c(s,a)}n(O,"nodeMayReach");function g(e,r=o()){return i(r,"SELECT node_id FROM nodes WHERE run_id = ? OR node_id = ?").all(e,e).map(t=>t.node_id)}n(g,"runNodeIds");export{O as nodeMayReach,R as objectPlace,f as rememberDeletedIsolated,g as runNodeIds,u as runPlace,c as runsSeeEachOther};

package/dist/core/runs/events.d.ts

@@ -0,0 +1,41 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { RunEvent, RunEventFields, RunEventOf, RunEventType } from '../../api/dto/run-events.js';
+/** Every event on a run's stream, declared once in the API contract. */
+export type { RunEvent, RunEventType, RunEventOf, RunEventFields } from '../../api/dto/run-events.js';
+/** The run-notice outbox's hook: called (after the appender's commit) for every event appended to a run. */
+export declare function onRunEventAppended(hook: ((runId: string) => void) | undefined): void;
+/** Append one event to a run's log. `type` must be a declared run event and `fields` its fields. */
+export declare function appendRunEvent<T extends RunEventType>(db: DatabaseSync, runId: string, nodeId: string, type: T, fields: RunEventFields<T>): RunEventOf<T>;
+export declare function emitRunEvent<T extends RunEventType>(runId: string, nodeId: string, type: T, fields: RunEventFields<T>): RunEventOf<T>;
+export declare function emitRunSettlement<T extends 'node.settled' | 'child.settled'>(runId: string, nodeId: string, type: T, fields: RunEventFields<T>): void;
+export declare function readRunEvents(runId: string, after?: number): {
+    events: RunEvent[];
+    earliest_sequence: number | null;
+    latest_sequence: number;
+    backlog_count: number;
+    backlog_bytes: number;
+};
+export declare function subscribeRunEvents(runId: string, wake: () => void): () => void;
+export declare function notifyRunDeleted(runId: string): void;
+/** OWN-11 for a joined runtime: the legacy `user:local` grantee is the terminal app. */
+export declare function rewriteLocalRunEventGrantee(db: DatabaseSync): number;
+/** A run event cursor stays monotonic. Keep control/settlement/usage history
+ * for the observer's 30-day recovery window, but full payload events for 14
+ * days only; older conversation content is in the transcript store. The stream
+ * already signals a cursor gap when events have expired. Budget one page/tick. */
+export declare function expireRunEvents(now: number, limit?: number): number;
+/** The conversation store is the canonical full transcript. Keep the full
+ * stream for one day, then redact settled tool calls, prompts and thinking.
+ * This includes older completed events of a still-live run, but tool-call
+ * arguments remain until node finalization (a tool may be in progress).
+ * An open turn's deltas and status/settlement markers are never redacted. Cursor scans
+ * avoid re-searching the whole log each tick. Old event payload replay is a
+ * deliberate tradeoff; event identities and 30-day sequence gaps survive. */
+export declare function compactRunEvents(now: number, afterRowid?: number, scanLimit?: number, writeLimit?: number): {
+    cursor: number;
+    compacted: number;
+};
+/** Track an open `run.events` stream an app caller holds under `grant`. */
+export declare function registerGrantStream(grant: string, close: () => void): () => void;
+/** Close every open stream held under a grant that is no longer active. */
+export declare function closeGrantStreams(grant: string): number;

package/dist/core/runs/events.js

@@ -0,0 +1,7 @@
+var g=Object.defineProperty;var c=(e,t)=>g(e,"name",{value:t,configurable:!0});import{prepared as u}from"../sqlite-statements.js";import{openDb as y,withCanvasWrite as l}from"../canvas/db.js";import{repairRunConversations as O}from"../canvas/sessions.js";const _=new Map;let R;function D(e){R=e}c(D,"onRunEventAppended");function f(e,t,n,r,s){const o=u(e,"SELECT event_cursor, grantee, metadata_json FROM node_rows WHERE node_id = ? AND run_id = ?").get(t,t);if(!o||o.event_cursor===null)throw new Error(`missing run event cursor: ${t}`);const i={type:r,run_id:t,node_id:n,sequence_number:o.event_cursor,ts:new Date().toISOString(),metadata:o.metadata_json?JSON.parse(o.metadata_json):{},...s};return u(e,"INSERT INTO run_events (run_id, sequence_number, node_id, type, ts, body_json, grantee) VALUES (?, ?, ?, ?, ?, ?, ?)").run(t,i.sequence_number,n,r,i.ts,JSON.stringify(i),o.grantee),u(e,"UPDATE nodes SET event_cursor = event_cursor + 1, last_activity_at = ? WHERE node_id = ?").run(i.ts,t),queueMicrotask(()=>{for(const d of _.get(t)??[])d();try{R?.(t)}catch{}}),i}c(f,"appendRunEvent");function M(e,t,n,r){return l(s=>f(s,e,t,n,r))}c(M,"emitRunEvent");function L(e,t,n,r){l(s=>{u(s,"SELECT 1 FROM run_events WHERE run_id = ? AND node_id = ? AND type = ? AND json_extract(body_json, '$.outcome.revision') = ? LIMIT 1").get(e,t,n,r.outcome.revision)||f(s,e,t,n,r)})}c(L,"emitRunSettlement");function A(e,t=0){O(e);const n=y(),r=u(n,"SELECT event_cursor FROM nodes WHERE node_id = ? AND run_id = ?").get(e,e);if(!r)throw new Error(`run not found: ${e}`);const s=u(n,"SELECT MIN(sequence_number) AS sequence FROM run_events WHERE run_id = ?").get(e),o=u(n,"SELECT COUNT(*) AS count, COALESCE(SUM(LENGTH(body_json)), 0) AS bytes FROM run_events WHERE run_id = ? AND sequence_number > ?").get(e,t);return{events:(o.count>1e3||o.bytes>32*1024*1024?[]:u(n,"SELECT body_json FROM run_events WHERE run_id = ? AND sequence_number > ? ORDER BY sequence_number LIMIT 1000").all(e,t)).map(d=>JSON.parse(d.body_json)),earliest_sequence:s.sequence,latest_sequence:r.event_cursor-1,backlog_count:o.count,backlog_bytes:o.bytes}}c(A,"readRunEvents");function C(e,t){let n=_.get(e);return n||(n=new Set,_.set(e,n)),n.add(t),()=>{n.delete(t),n.size===0&&_.delete(e)}}c(C,"subscribeRunEvents");function H(e){queueMicrotask(()=>{for(const t of _.get(e)??[])t()})}c(H,"notifyRunDeleted");function x(e){return Number(u(e,"UPDATE run_events SET grantee = 'app:terminal' WHERE grantee = 'user:local'").run().changes)}c(x,"rewriteLocalRunEventGrantee");function W(e,t=128){return l(n=>{const r=new Date(e-12096e5).toISOString(),s=new Date(e-720*60*6e4).toISOString(),o=Number(u(n,`DELETE FROM run_events WHERE rowid IN
+      (SELECT rowid FROM run_events WHERE ts < ? AND type IN
+        ('node.tool_call.completed', 'node.tool_call.started', 'node.system_prompt.set',
+         'node.thinking.done', 'node.output_text.done') ORDER BY ts LIMIT ?)`).run(r,t).changes),i=Number(u(n,`DELETE FROM run_events WHERE rowid IN
+      (SELECT rowid FROM run_events WHERE ts < ? ORDER BY ts LIMIT ?)`).run(s,t-o).changes);return o+i})}c(W,"expireRunEvents");function h(e,t=0,n=256,r=8){return l(s=>{const o=u(s,`SELECT e.rowid, e.type, e.ts, length(e.body_json) AS bytes,
+      n.finalized_at FROM run_events e LEFT JOIN nodes n ON n.node_id = e.node_id
+      WHERE e.rowid > ? ORDER BY e.rowid LIMIT ?`).all(t,n);if(!o.length)return{cursor:0,compacted:0};let i=0,d=t;const m=new Date(e-1440*6e4).toISOString(),S=u(s,"SELECT body_json FROM run_events WHERE rowid = ?"),v=u(s,"UPDATE run_events SET body_json = ? WHERE rowid = ?");for(const a of o){if(d=a.rowid,!["node.tool_call.completed","node.tool_call.started","node.system_prompt.set","node.thinking.done"].includes(a.type)||a.ts>=m||a.bytes<1024||a.type==="node.tool_call.started"&&!a.finalized_at)continue;const E=JSON.parse(S.get(a.rowid).body_json);if(E.content_redacted!==!0&&(a.type==="node.tool_call.completed"?delete E.result:a.type==="node.tool_call.started"?delete E.arguments:delete E.text,E.content_redacted=!0,v.run(JSON.stringify(E),a.rowid),++i>=r))break}return{cursor:d,compacted:i}})}c(h,"compactRunEvents");const p=new Map;function j(e,t){let n=p.get(e);return n||(n=new Set,p.set(e,n)),n.add(t),()=>{n.delete(t),n.size===0&&p.delete(e)}}c(j,"registerGrantStream");function q(e){const t=[...p.get(e)??[]];for(const n of t)n();return t.length}c(q,"closeGrantStreams");export{f as appendRunEvent,q as closeGrantStreams,h as compactRunEvents,M as emitRunEvent,L as emitRunSettlement,W as expireRunEvents,H as notifyRunDeleted,D as onRunEventAppended,A as readRunEvents,j as registerGrantStream,x as rewriteLocalRunEventGrantee,C as subscribeRunEvents};

package/dist/core/runs/operations.d.ts

@@ -0,0 +1,75 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { NodeMeta } from '../canvas/types.js';
+import type { AppPrincipal } from '../../daemon/api/principal.js';
+import { type ResolvedAttachments } from '../storage/attachments.js';
+import { type StorageClient, type StorageConfig } from '../storage/client.js';
+/** Fetches the storage URLs of a run's text into the run's `attachments/`. */
+export type AttachmentResolver = (runId: string, grantee: string, text: string) => Promise<ResolvedAttachments>;
+/** Storage deletes `run.delete` waits for before it answers. */
+export declare const RUN_DELETE_STORAGE_BUDGET_MS = 3000;
+export interface StorageDeps {
+    config: () => StorageConfig | null;
+    client: () => StorageClient;
+    budgetMs?: number;
+}
+/** OWN-11 for a joined runtime: the legacy `user:local` grantee is the terminal app. */
+export declare function rewriteLocalIdempotencyGrantee(db: DatabaseSync): number;
+export declare class RunError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly param?: string | undefined;
+    readonly details?: unknown | undefined;
+    readonly scope?: string | undefined;
+    readonly retryable: boolean;
+    constructor(status: number, code: string, message: string, param?: string | undefined, details?: unknown | undefined, scope?: string | undefined, retryable?: boolean);
+}
+export declare function ownedRun(id: string, grantee: string, allowDeleting?: boolean): NodeMeta;
+export type RunStatus = 'running' | 'waiting_on_user' | 'idle' | 'settled';
+/** Whether the run has a turn in flight or work owed to it (the `running` run status). */
+export declare function runIsRunning(runId: string): boolean;
+export declare function runObject(root: NodeMeta): Record<string, unknown>;
+/** An `Idempotency-Key` header value: absent, or 1–255 characters. */
+export declare function idempotencyKeyOf(header: unknown): string | undefined;
+/** Delete keys past their window; returns how many were removed. */
+export declare function pruneExpiredIdempotencyKeys(now?: number): number;
+export declare function startRun(principal: AppPrincipal, input: {
+    prompt: string;
+    scopes: string[] | null;
+    metadata: Record<string, unknown>;
+    profile?: string;
+    isolated?: boolean;
+    cwd?: string;
+    output_schema?: Record<string, unknown>;
+    message?: string;
+}, idempotencyKey?: string, resolveAttachments?: AttachmentResolver): Promise<Record<string, unknown>>;
+export declare function listRuns(grantee: string | null, options: {
+    status?: string;
+    after?: string;
+    limit: number;
+    visible?: (runId: string) => boolean;
+}): {
+    runs: Record<string, unknown>[];
+    next: string | null;
+};
+export declare function waitRun(id: string, grantee: string, seconds: number): Promise<Record<string, unknown>>;
+export declare function messageRun(root: NodeMeta, original: string, resolveAttachments?: AttachmentResolver, startTurn?: boolean, idempotencyKey?: string): Promise<{
+    run_id: string;
+    message_id: string;
+    sequence_number: number;
+}>;
+export declare function interruptRun(root: NodeMeta, children?: 'stop' | 'continue'): Promise<Record<string, unknown>>;
+export declare function cancelRun(root: NodeMeta, _options?: {
+    keepSchedules?: boolean;
+}): Promise<Record<string, unknown>>;
+/** The longest run name `run.rename` accepts. */
+export declare const RUN_NAME_MAX = 200;
+/** `run.rename`: set the root node's name — the name `crtr` shows for the node —
+ *  through the same path as `PATCH /v1/nodes/:id/config` `name`. */
+export declare function renameRun(root: NodeMeta, name: unknown): Record<string, unknown>;
+/** Delete a run. Answers how many of the run's released uploads storage has
+ *  not confirmed deleted; the due-work tick retries those. */
+export declare function deleteRun(root: NodeMeta, storage?: StorageDeps): Promise<{
+    uploads_pending: number;
+}>;
+export declare function traceRun(id: string, grantee: string, format?: string): Record<string, unknown>;
+export declare function requestedScopes(held: readonly string[], value: unknown, grantee: string): string[] | null;

package/dist/core/runs/operations.js

@@ -0,0 +1,12 @@
+var Re=Object.defineProperty;var u=(e,t)=>Re(e,"name",{value:t,configurable:!0});import{prepared as E}from"../sqlite-statements.js";import{createHash as $}from"node:crypto";import{ApiError as Se}from"../../api/errors.js";import{isAbsolute as J,relative as Ne,resolve as ve,sep as Oe,join as be}from"node:path";import{SessionManager as De}from"@earendil-works/pi-coding-agent";import{covers as L}from"@north-light/identity";import{openDb as Y,withCanvasWrite as A}from"../canvas/db.js";import{deleteNodeWithOwned as Te}from"../graph/deletion.js";import{getById as Ie}from"../graph/objects.js";import{repairRunConversations as G}from"../canvas/sessions.js";import{getNode as S,nodeFiles as Me,removeNodeFiles as Le,updateNode as Ae}from"../canvas/canvas.js";import{fullName as Ce}from"../canvas/labels.js";import{renameWindow as ke}from"../runtime/placement.js";import{liveExecutionForNode as X}from"../canvas/executions.js";import{conversationStore as z,isConversationNotFound as xe}from"../conversation-store/index.js";import{enqueueNodeMail as We}from"../feed/messages.js";import{newestReportBody as Fe}from"../feed/reports.js";import{ensureAppProfile as He,loadExactProfileManifest as qe}from"../profiles/manifest.js";import{stopNodeSandboxes as Q}from"../spaces/stop.js";import{BrokerUnreachableError as Ue}from"../runtime/broker-request.js";import{interruptLive as Pe}from"../runtime/interactive-deliver.js";import{isBrokerLive as V}from"../runtime/model-swap.js";import{newNodeId as Be}from"../runtime/nodes.js";import{writeGoal as je}from"../runtime/kickoff.js";import{reviveNode as W}from"../runtime/revive.js";import{spawnChildPrepared as $e}from"../runtime/spawn.js";import{isolatedBrokerLauncherAvailable as Je}from"../runtime/host.js";import{resolveRunKind as Ye}from"../runtime/launch-target.js";import{cycleAwareMessages as Ge}from"../runtime/session-cycles.js";import{originFor as Z}from"../runtime/stamp/protocol.js";import{readOutputRequest as Xe,readOutputResult as K}from"../runtime/structured-output.js";import{admitLegacyStructuredOutput as ee}from"../../daemon/structured-requests/sidecar.js";import{runSchemaRepromptPending as ze}from"../runtime/stop-guard.js";import{toRunOutcomeDTO as Qe}from"../../daemon/api/map.js";import{openAssistantMessageStartSequence as Ve}from"../../daemon/runs/observer.js";import{closeNode as te}from"../runtime/close.js";import{parseScope as Ze}from"@north-light/identity";import{appendRunEvent as ne,subscribeRunEvents as Ke}from"./events.js";import{runActivity as et}from"./activity.js";import{cancelOpenQuestions as se,openQuestionIds as re}from"./questions.js";import{appSpace as oe}from"../layout.js";import{ensureAppSpace as tt}from"../spaces/space.js";import{assertUploadsUsable as ie,resolveStorageUrls as nt}from"../storage/attachments.js";import{storageClient as st,storageConfig as rt}from"../storage/client.js";import{deleteUploadRow as ot,insertUploadUses as ae,releaseRunUploads as it}from"../storage/tables.js";import{abortProviderCalls as de}from"../providers/inflight.js";const ce=u((e,t,r)=>nt(t,e,r),"defaultResolver"),at=3e3;function sn(e){return Number(E(e,"UPDATE idempotency_keys SET grantee = 'app:terminal' WHERE grantee = 'user:local'").run().changes)}u(sn,"rewriteLocalIdempotencyGrantee");class R extends Error{static{u(this,"RunError")}status;code;param;details;scope;retryable;constructor(t,r,n,i,c,a,o=t===503){super(n),this.status=t,this.code=r,this.param=i,this.details=c,this.scope=a,this.retryable=o}}const O=u((e,t)=>new R(400,"invalid_request",e,t),"invalid"),F=u(()=>new R(404,"not_found","run not found"),"missing"),H=u(()=>({input_tokens:0,output_tokens:0,cache_read_tokens:0,cache_write_tokens:0,cost_usd:0}),"usage"),b=u(()=>Y(),"db");function C(e,t,r=!1){const n=S(e);if(!n||n.parent!==null||n.run_id!==e||n.grantee!==t||!r&&n.deleting_at)throw F();return n}u(C,"ownedRun");const q=["waiting_on_user","idle","settled"];function I(e){if(e.status==="canceled"||e.status==="dead"||e.status==="done"&&e.intent!=="parked")return"settled";const t=E(b(),`SELECT 1 FROM node_rows n WHERE n.run_id = ? AND n.status = 'active' AND
+    (n.last_settled_at IS NULL OR EXISTS (
+      SELECT 1 FROM run_events e WHERE e.run_id = ? AND e.node_id = n.node_id AND e.type = 'node.turn.started'
+        AND e.sequence_number > COALESCE((SELECT MAX(c.sequence_number) FROM run_events c
+          WHERE c.run_id = e.run_id AND c.node_id = e.node_id AND c.type = 'node.turn.completed'), 0)
+    )) LIMIT 1`).get(e.node_id,e.node_id),r=E(b(),"SELECT 1 FROM deliveries WHERE destination_id IN (SELECT node_id FROM nodes WHERE run_id = ?) AND state IN ('armed', 'pending') AND wake = 1 LIMIT 1").get(e.node_id);return t||r||!e.last_settled_at||ze(e)?"running":re(e.node_id).length?"waiting_on_user":"idle"}u(I,"runStatus");function rn(e){const t=S(e);return t!==null&&I(t)==="running"}u(rn,"runIsRunning");function M(e){G(e.node_id),e=S(e.node_id)??e;const t=I(e),r=t==="settled"?[]:re(e.node_id),n=Fe(e.node_id)||void 0,i=t==="settled"?Qe(e):null,c=i?.kind==="result"?K(e.node_id,e.grantee):void 0;return{run_id:e.node_id,name:e.name,status:t,...i?{outcome:i}:{},...c===void 0?{}:{result:c},...n!==void 0?{last_report:n}:{},pending_question_ids:r,...e.last_turn_error_json?{last_turn_error:JSON.parse(e.last_turn_error_json)}:{},usage:JSON.parse(e.usage_json??JSON.stringify(H())),payer:"user",scopes:e.scopes,metadata:e.metadata_json?JSON.parse(e.metadata_json):{},created_at:e.created,...t==="settled"&&e.outcome_at?{settled_at:e.outcome_at}:{},latest_sequence:(e.event_cursor??1)-1,last_activity_at:e.last_activity_at,activity:et(e.node_id,t)}}u(M,"runObject");const U=864e5,ue=255;function on(e){if(e!==void 0){if(typeof e!="string"||!e.length||e.length>ue)throw O(`Idempotency-Key must be 1-${ue} characters`);return e}}u(on,"idempotencyKeyOf");function P(e,t,r,n=Y()){const i=E(n,"SELECT body_hash, run_id, response_json, created_at FROM idempotency_keys WHERE grantee = ? AND key = ?").get(e,t);if(!(!i||Date.now()-Date.parse(i.created_at)>=U)){if(i.body_hash!==r)throw new R(409,"idempotency_conflict","key used with a different request");return{run_id:i.run_id,response:JSON.parse(i.response_json)}}}u(P,"findIdempotent");function me(e,t,r,n,i,c,a){E(e,"DELETE FROM idempotency_keys WHERE grantee = ? AND key = ? AND created_at <= ?").run(t,r,new Date(Date.now()-U).toISOString()),E(e,"INSERT INTO idempotency_keys (grantee, key, body_hash, run_id, response_json, created_at) VALUES (?, ?, ?, ?, ?, ?)").run(t,r,n,i,JSON.stringify(c),a)}u(me,"recordIdempotent");function an(e=Date.now()){return A(t=>Number(E(t,"DELETE FROM idempotency_keys WHERE created_at <= ?").run(new Date(e-U).toISOString()).changes))}u(an,"pruneExpiredIdempotencyKeys");function le(e,t,r,n,i){const c=n.text;let a=0;return{messageId:We(t,{kind:"message",label:c.slice(0,120),senderNodeId:"human",senderName:r,bodyJson:i?{body:c}:{body:c,start_turn:!1},urgency:i?"normal":"deferred",wake:i?1:0,withinEnqueue:u((d,p)=>{n.uses.length&&(ie(r,n.uses,d),ae(n.uses.map(({upload_id:y,path:g})=>({upload_id:y,path:g,run_id:t})),d)),a=ne(d,t,t,"node.message.accepted",{message_id:p,start_turn:i}).sequence_number},"withinEnqueue")}).messageId,sequence:a}}u(le,"acceptRunMessage");async function dn(e,t,r,n=ce){if(t.isolated&&!Je())throw new R(503,"isolated_unavailable","isolated runs require the Linux root launcher","isolated");const i=$("sha256").update(JSON.stringify(t)).digest("hex");if(r){const s=P(e.grantee,r,i);if(s){const m=C(s.run_id,e.grantee);return!m.pi_pid&&I(m)==="running"&&(t.output_schema!==void 0&&!m.outcome_at&&Xe(m.node_id).state==="absent"&&K(m.node_id,m.grantee)===void 0&&ee(m.node_id,"terminal",t.output_schema),await W(m.node_id,{resume:!0,capacity:"freeze"})),s.response}}await tt(e.grantee);const c=t.profile===void 0?He(e.grantee):qe(t.profile),a=c.manifest.grantee??"app:terminal";if(a!==e.grantee){const s=`crtr:memory:rw:${a}:profile:${c.profileId}`;if(!e.resolved.some(m=>L(m,s))||t.scopes!==null&&!t.scopes.some(m=>L(m,s)))throw new R(403,"scope_missing",`missing scope ${s}`,"profile",void 0,s)}const o=Be(),d=be(oe(e.grantee).nodes,o);if(t.isolated&&t.cwd!==void 0){const s=Ne(d,ve(t.cwd));if(!J(t.cwd)||s===".."||s.startsWith(`..${Oe}`)||J(s))throw O("cwd must be inside the isolated root node folder","cwd")}const p=await n(o,e.grantee,t.prompt),y=p.text;let g;try{g=t.message===void 0?void 0:await n(o,e.grantee,t.message)}catch(s){throw p.cleanup(),s}let f;try{await $e({kind:Ye(c),mode:"base",root:!0,rootLifecycle:"resident",readiness:"launch",cwd:t.isolated?t.cwd??d:oe(e.grantee).files,profile:c.profileId,prompt:y,nodeId:o,isolated:t.isolated??!1,...t.scopes===null?{}:{scopes:t.scopes},run:{grantee:e.grantee,sub:e.sub,grant_id:e.grant,client_id:e.client_id,metadata_json:JSON.stringify(t.metadata),run_id:o,event_cursor:1,usage_json:JSON.stringify(H())},withinCreate:u((s,m)=>{const h=p.uses;if(h.length&&(ie(e.grantee,h,s),ae(h.map(({upload_id:w,path:k})=>({upload_id:w,path:k,run_id:o})),s)),je(o,y),f={run_id:o,node_id:o,grantee:e.grantee,grant:e.grant,rev:e.rev,scopes:t.scopes,payer:"user",status:"running",created_at:m.created,metadata:t.metadata,sequence_number:0},ne(s,o,o,"run.started",{scopes:t.scopes,payer:"user",usage:H()}),g){const w=le(s,o,e.grantee,g,!1);f.message={run_id:o,message_id:w.messageId,sequence_number:w.sequence}}r&&me(s,e.grantee,r,i,o,f,m.created)},"withinCreate")},t.output_schema===void 0?void 0:s=>{ee(s,"terminal",t.output_schema)})}catch(s){if(S(o)||(p.cleanup(),g?.cleanup()),s instanceof Se&&(s.code==="isolated_run"||s.code==="invalid_request")){const m=s.details&&typeof s.details=="object"&&"param"in s.details&&typeof s.details.param=="string"?s.details.param:void 0;throw new R(s.status,s.code,s.message,m)}throw s}if(!f)throw new Error("run creation did not commit");return f}u(dn,"startRun");function cn(e,t){let r;if(t.after)try{const o=JSON.parse(Buffer.from(t.after,"base64url").toString());if(!o||typeof o!="object"||!("activity"in o)||typeof o.activity!="string"||!("id"in o)||typeof o.id!="string")throw new Error("invalid cursor");r={activity:o.activity,id:o.id}}catch{throw O("invalid list cursor","after")}const i=b().prepare(`SELECT node_id, COALESCE(last_activity_at, created) AS activity FROM node_rows
+    WHERE run_id = node_id AND deleting_at IS NULL ${e===null?"":"AND grantee = ?"}
+    ORDER BY activity DESC, node_id DESC`).all(...e===null?[]:[e]).filter(({node_id:o})=>!t.visible||t.visible(o)).filter(({activity:o,node_id:d})=>!r||o<r.activity||o===r.activity&&d<r.id).map(o=>({root:S(o.node_id),activity:o.activity})).filter(({root:o})=>!t.status||I(o)===t.status),c=i.slice(0,t.limit),a=c.at(-1);return{runs:c.map(({root:o})=>M(o)),next:i.length>t.limit&&a?Buffer.from(JSON.stringify({activity:a.activity,id:a.root.node_id})).toString("base64url"):null}}u(cn,"listRuns");async function un(e,t,r){const n=C(e,t),i=u(()=>M(C(e,t)),"read");return!r||q.includes(I(n))?i():new Promise((c,a)=>{const o=u(()=>{clearTimeout(y),clearInterval(p),d();try{c(i())}catch(g){a(g)}},"finish"),d=Ke(e,()=>{try{q.includes(String(i().status))&&o()}catch(g){clearTimeout(y),clearInterval(p),d(),a(g)}}),p=setInterval(()=>{q.includes(String(i().status))&&o()},250),y=setTimeout(o,r*1e3)})}u(un,"waitRun");async function mn(e,t,r=ce,n=!0,i){const c=e.status==="canceled"||e.outcome_reason==="closed",a=e.grantee??"app:terminal",o=$("sha256").update(JSON.stringify(["run.message",e.node_id,t,n])).digest("hex"),d=u(async f=>{const s=S(e.node_id),m=E(b(),"SELECT 1 FROM deliveries WHERE message_id = ? AND state = 'pending' AND canceled_at IS NULL").get(String(f.message_id));return s&&!c&&n&&!s.pi_pid&&m&&await W(e.node_id,{resume:!0,capacity:"freeze"}),f},"replay");if(i){const f=P(a,i,o);if(f)return d(f.response)}if(c)throw new R(409,"run_settled","canceled run cannot receive a message");const p=await r(e.node_id,a,t),y=n&&e.final_report&&!e.pi_pid?(await import("../runtime/reopen.js")).commitReopenResident:void 0;let g;try{g=A(f=>{if(i){const h=P(a,i,o,f);if(h)return{replayed:h.response}}y?.(e.node_id);const s=le(f,e.node_id,a,p,n),m={run_id:e.node_id,message_id:s.messageId,sequence_number:s.sequence};return i&&me(f,a,i,o,e.node_id,m,new Date().toISOString()),{result:m}})}catch(f){throw p.cleanup(),f}return"replayed"in g?(p.cleanup(),d(g.replayed)):(n&&!e.pi_pid&&await W(e.node_id,{resume:!0,capacity:"freeze"}),g.result)}u(mn,"messageRun");async function dt(e){const t=u(()=>new R(503,"service_unavailable",`node ${e} broker was unavailable before the interrupt reached it`),"unavailable");for(let r=0;r<2;r++){const n=S(e);if(!n)throw F();if(!V(n)){if(n.streaming)throw t();return}const i=X(e)?.executionId;try{await Pe(e)==="turn"&&de({nodes:[e]});return}catch(c){if(!(c instanceof Ue))throw c;const a=S(e);if(!a)throw F();if(!a.streaming)return;if(r===0&&V(a)&&X(e)?.executionId!==i)continue;throw t()}}throw t()}u(dt,"interruptNode");async function ln(e,t="stop"){const r=t==="stop"?E(b(),"SELECT node_id FROM nodes WHERE run_id = ?").all(e.node_id).map(({node_id:n})=>n):[e.node_id];return await Promise.all(r.map(n=>dt(n))),M(S(e.node_id)??e)}u(ln,"interruptRun");async function _n(e,t={}){const r=E(b(),"SELECT node_id FROM nodes WHERE run_id = ? ORDER BY created DESC").all(e.node_id).map(a=>a.node_id);de({run:e.node_id});const n=[];if(I(e)!=="settled")n.push(...te(e.node_id,{preserveEmpty:!0,stopReason:"run_canceled"}).closed);else for(const a of r){if(a===e.node_id)continue;const o=S(a);o&&o.status!=="done"&&o.status!=="canceled"&&o.status!=="dead"&&n.push(...te(a,{preserveEmpty:!0,stopReason:"run_canceled"}).closed)}if(await se({run_id:e.node_id},"the run was canceled"),(await Promise.all([...new Set([e.node_id,...n])].map(a=>Q(a,"run_canceled")))).some(a=>!a.confirmed))throw new R(500,"server_error","run process teardown could not be confirmed",void 0,void 0,void 0,!0);const c=S(e.node_id);return M(c??e)}u(_n,"cancelRun");const _e=200;function pn(e,t){if(typeof t!="string"||!t.trim())throw O("name is required","name");const r=t.trim();if(r.length>_e)throw O(`name exceeds ${_e} characters`,"name");const n=Ae(e.node_id,{name:r});return n.window&&ke(n.window,Ce(n)),M(n)}u(pn,"renameRun");async function fn(e,t={config:rt,client:st}){await se({run_id:e.node_id},"the run was deleted");const r=A(d=>(E(d,"UPDATE nodes SET deleting_at = COALESCE(deleting_at, ?) WHERE node_id = ?").run(new Date().toISOString(),e.node_id),E(d,"SELECT node_id FROM nodes WHERE run_id = ? ORDER BY created DESC").all(e.node_id).map(p=>p.node_id)));if((await Promise.all(r.map(d=>Q(d,"run_deleted",{deleting:!0})))).some(d=>!d.confirmed))throw new R(500,"server_error","run process teardown could not be confirmed",void 0,void 0,void 0,!0);const i=r.map(d=>{const p=Me(d);if(p.app===null)throw new Error(`run node missing during deletion: ${d}`);return p}),c=E(b(),"SELECT DISTINCT session_id FROM sessions WHERE session_id IS NOT NULL AND node_id IN (SELECT node_id FROM nodes WHERE run_id = ?)").all(e.node_id);for(const{session_id:d}of c)try{z().delete(d)}catch(p){if(!xe(p))throw p}const a=A(d=>{for(const f of r){const s=Ie(d,f);s!==null&&s.deleted_at===null&&Te(d,s)}const p=it([e.node_id],d);E(d,"DELETE FROM run_events WHERE run_id = ?").run(e.node_id),E(d,"DELETE FROM idempotency_keys WHERE run_id = ?").run(e.node_id);const y=r.map(()=>"?").join(","),g=d.prepare(`SELECT message_id FROM messages WHERE sender_node_id IN (${y}) UNION SELECT message_id FROM deliveries WHERE destination_id IN (${y})`).all(...r,...r);d.prepare(`DELETE FROM deliveries WHERE destination_id IN (${y})`).run(...r);for(const{message_id:f}of g)E(d,"DELETE FROM messages WHERE message_id = ? AND NOT EXISTS (SELECT 1 FROM deliveries WHERE message_id = ?)").run(f,f);return p});for(const d of i)Le(d);const{notifyRunDeleted:o}=await import("./events.js");return o(e.node_id),{uploads_pending:await ct(a,t)}}u(fn,"deleteRun");async function ct(e,t){if(!e.length||!t.config())return e.length;let r;try{r=t.client()}catch{return e.length}const n=new Set,i=e.map(a=>r.deleteUpload(a).then(()=>{ot(a),n.add(a)},()=>{}));let c;return await Promise.race([Promise.all(i),new Promise(a=>{c=setTimeout(a,t.budgetMs??at),c.unref?.()})]),clearTimeout(c),e.length-n.size}u(ct,"deleteReleasedUploads");function gn(e,t,r){C(e,t),G(e);const n=b();n.exec("BEGIN");try{const c=E(n,"SELECT node_id, parent FROM nodes WHERE run_id = ? ORDER BY CASE WHEN node_id = ? THEN 0 ELSE 1 END, created, node_id").all(e,e).map(s=>({node_id:s.node_id,parent_node_id:s.parent,conversations:E(n,"SELECT DISTINCT session_id FROM sessions WHERE node_id = ? ORDER BY created_at").all(s.node_id).map(({session_id:m})=>{const{header:h,entries:w}=z().read(m);if(r==="entries")return{conversation_id:m,header:h,entries:w};const k=De.inMemory(h.cwd,void 0,[h,...w]),pe=Ge(k)??[],B=new Map(w.map((_,N)=>[_.id,N])),fe=w.filter(_=>_.type==="custom"&&_.customType==="crtr-system-prompt").map(_=>({id:_.id,message:{role:"custom",customType:"crtr-system-prompt",data:"data"in _?_.data:void 0,timestamp:_.timestamp}})),j=w.filter(_=>_.type==="custom_message"&&_.customType==="app_message").map(_=>({id:_.id,message:{role:"custom",customType:"app_message",content:"content"in _?_.content:"",timestamp:_.timestamp}})),ge=s.node_id===e?w.find(_=>{if(_.type!=="message"||_.message.role!=="user")return!1;const N=Z(w,_.message.timestamp);return N?.type==="runtime"&&N.kind==="kickoff"})?.id:void 0,Ee=[...pe.filter(({id:_})=>!j.some(N=>N.id===_)),...fe,...j].sort((_,N)=>(B.get(_.id)??Number.MAX_SAFE_INTEGER)-(B.get(N.id)??Number.MAX_SAFE_INTEGER)).map(({id:_,message:N})=>{const l=N,D=l.usage,x=l.role==="user"?Z(w,Number(l.timestamp)):null,we=x?.type==="human"||_===ge,T=l.role==="toolResult"?"tool_result":l.role==="bashExecution"?"bash_execution":l.role==="compactionSummary"?"compaction_summary":l.role==="branchSummary"?"branch_summary":l.role==="custom"&&l.customType==="crtr-system-prompt"?"system":l.role==="user"?we?"user":"custom":l.role,ye=T==="custom"?l.role==="custom"?l.customType:x?.type==="runtime"?x.kind:"unknown":void 0,he=T==="system"&&l.customType==="crtr-system-prompt"?[{type:"text",text:l.data?.text??""}]:typeof l.content=="string"?[{type:"text",text:l.content}]:Array.isArray(l.content)?l.content.map(v=>v.type==="toolCall"?{type:"tool_call",tool_call_id:v.id,name:v.name,arguments:v.arguments}:v.type==="image"?{type:"image",mime_type:v.mimeType}:v.type==="thinking"?{type:"thinking",text:v.thinking}:v):[];return{entry_id:_,role:T,...T==="custom"?{custom_type:ye}:{},time:typeof l.timestamp=="string"?l.timestamp:new Date(Number(l.timestamp??Date.now())).toISOString(),content:he,...T==="assistant"?{model:l.model,provider:l.provider,stop_reason:l.stopReason,...l.errorMessage?{error_message:l.errorMessage}:{},...D?{usage:{input_tokens:D.input??0,output_tokens:D.output??0,cache_read_tokens:D.cacheRead??0,cache_write_tokens:D.cacheWrite??0,cost_usd:D.cost?.total??0}}:{}}:{},...T==="tool_result"?{tool_call_id:l.toolCallId,tool_name:l.toolName,is_error:l.isError}:{}}})??[];return{conversation_id:m,messages:Ee}})})),o=E(n,"SELECT event_cursor FROM nodes WHERE node_id = ?").get(e).event_cursor-1,d=new Map(c.map(s=>[s.node_id,Ve(s.node_id)])),p=E(n,`SELECT node_id, sequence_number FROM run_events
+      WHERE run_id = ? AND sequence_number <= ? AND type IN ('node.thinking.done', 'node.output_text.done', 'usage')
+      ORDER BY sequence_number`).all(e,o);for(const s of p){const m=d.get(s.node_id);m!=null&&s.sequence_number>=m&&d.set(s.node_id,null)}const y=E(n,`SELECT node_id, sequence_number, type, body_json FROM run_events
+      WHERE run_id = ? AND sequence_number <= ? AND type IN ('node.thinking.delta', 'node.output_text.delta')
+      ORDER BY sequence_number`).all(e,o),g=new Map;for(const s of y){const m=d.get(s.node_id);if(m==null||s.sequence_number<m)continue;const h=JSON.parse(s.body_json),w=g.get(s.node_id)??{thinking:"",text:""};s.type==="node.thinking.delta"?w.thinking+=h.delta:w.text+=h.delta,g.set(s.node_id,w)}const f=c.map(s=>({...s,in_progress_message:d.get(s.node_id)==null?null:g.get(s.node_id)??{thinking:"",text:""}}));return n.exec("COMMIT"),{run_id:e,latest_sequence:o,nodes:f}}catch(i){throw n.exec("ROLLBACK"),i}}u(gn,"traceRun");function En(e,t,r){if(t===void 0){if(!e.some(n=>L(n,"crtr:llm")))throw new R(403,"scope_missing","missing scope crtr:llm",void 0,void 0,"crtr:llm");return null}if(!Array.isArray(t)||t.some(n=>typeof n!="string"))throw O("scopes must be a list of scope strings","scopes");for(const n of t){try{Ze(n)}catch{throw O(`invalid scope ${n}`,"scopes")}if(/^crtr:files:(?:read|rw):app:/.test(n)&&n.split(":")[4]===r.slice(4))throw O(`own-app files cannot narrow a run: ${n}`,"scopes");if(!(/^crtr:memory:(?:read|rw):app:/.test(n)&&n.split(":")[4]===r.slice(4))&&!e.some(c=>L(c,n)))throw new R(403,"scope_missing",`missing scope ${n}`,void 0,void 0,n)}if(!t.includes("crtr:llm"))throw new R(403,"scope_missing","missing scope crtr:llm",void 0,void 0,"crtr:llm");return t}u(En,"requestedScopes");export{at as RUN_DELETE_STORAGE_BUDGET_MS,_e as RUN_NAME_MAX,R as RunError,_n as cancelRun,fn as deleteRun,on as idempotencyKeyOf,ln as interruptRun,cn as listRuns,mn as messageRun,C as ownedRun,an as pruneExpiredIdempotencyKeys,pn as renameRun,En as requestedScopes,sn as rewriteLocalIdempotencyGrantee,rn as runIsRunning,M as runObject,dn as startRun,gn as traceRun,un as waitRun};

package/dist/core/runs/questions.d.ts

@@ -0,0 +1,73 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { type HumanRequestRecord } from '../human/requests.js';
+import { type PreparedPage } from '../human/page-authoring.js';
+/**
+ * A question is a settleable human page request. Most belong to a run; a
+ * provider approval can also belong to an app without a run. Its question id
+ * is the human request id in either case.
+ */
+interface AskingNode {
+    node_id: string;
+    run_id: string;
+    grantee: string;
+}
+export interface ProviderQuestion {
+    question_id: string;
+    grantee: string;
+    sub: string;
+    provider: string;
+    tool: string;
+    status: 'open' | 'answered' | 'consumed' | 'canceled';
+    option_id: string | null;
+}
+/** The provider's prompt is displayed by the same human page mechanism as run questions. */
+export declare function providerApprovalPage(question: {
+    title: string;
+    body: string;
+    options: Array<{
+        option_id: string;
+        label: string;
+    }>;
+}): PreparedPage;
+/** The question's run, asking node, and app, or null when the request is not a question. */
+export declare function questionRun(request: HumanRequestRecord, db?: DatabaseSync): AskingNode | null;
+/** Called inside the page request's creating write: carries a new question on its run's stream. */
+export declare function appendWaitingOnUser(db: DatabaseSync, request: HumanRequestRecord): void;
+/** Called inside the settling write: an answered question emits `question.answered`. */
+export declare function appendQuestionAnswered(db: DatabaseSync, request: HumanRequestRecord): void;
+/** Open questions raised by any node of the run, oldest first. */
+export declare function openQuestionIds(runId: string, db?: DatabaseSync): string[];
+export type QuestionStatus = 'open' | 'answered' | 'canceled';
+export declare function questionStatus(request: HumanRequestRecord): QuestionStatus;
+/** The stored answer or cancellation of a settled question. */
+export declare function questionResult(request: HumanRequestRecord): unknown;
+/** The `question.get` shape. */
+export declare function questionObject(request: HumanRequestRecord, run: AskingNode | null, approval?: ProviderQuestion | null): Record<string, unknown>;
+/** A question by id, with its run or an app-owned runless provider approval. */
+export declare function getQuestion(questionId: string): {
+    request: HumanRequestRecord;
+    run: AskingNode | null;
+    approval: ProviderQuestion | null;
+} | null;
+/** Open question ids scoped to a run, one asking node, or every run of an app. */
+export declare function openQuestionIdsFor(target: {
+    run_id: string;
+} | {
+    node_id: string;
+} | {
+    grantee: string;
+}): string[];
+/**
+ * Cancel the open questions of a run, of one asking node, or of every run of an
+ * app, through the page mechanism's own cancel (`settleHumanRequest`, first
+ * writer wins): each becomes `canceled` and can never be answered afterwards.
+ * Answers how many this call canceled.
+ */
+export declare function cancelOpenQuestions(target: {
+    run_id: string;
+} | {
+    node_id: string;
+} | {
+    grantee: string;
+}, reason: string): Promise<number>;
+export {};

package/dist/core/runs/questions.js

@@ -0,0 +1,4 @@
+var _=Object.defineProperty;var i=(n,e)=>_(n,"name",{value:e,configurable:!0});import{prepared as a}from"../sqlite-statements.js";import{openDb as d}from"../canvas/db.js";import{getRequest as f}from"../human/requests.js";import{preparePageSource as m}from"../human/page-authoring.js";import{appendRunEvent as l}from"./events.js";function p(n,e){return a(n,"SELECT question_id, grantee, sub, provider, tool, status, option_id FROM provider_approvals WHERE question_id = ?").get(e)??null}i(p,"providerQuestion");function R(n){if(!n.title.trim()||!n.body.trim()||!Array.isArray(n.options)||n.options.length===0)throw new Error("provider approval needs a title, body, and options");const e=new Set(["deny"]);for(const o of n.options){if(!o.option_id||!o.label||e.has(o.option_id))throw new Error("provider approval option ids must be nonempty, unique, and different from deny");e.add(o.option_id)}const t=[...n.options.map(({option_id:o,label:s})=>({id:o,label:s})),{id:"deny",label:"Don't do this"}],r=`export default function Approval() { return <Page title={${JSON.stringify(n.title)}}><UserQuestion id="options" label="Choose an option" body={${JSON.stringify(n.body)}} mode="single" required={true} allowFreetext={false} options={${JSON.stringify(t)}} /></Page>; }`;return m({dialect:"jsx",document:r,delivery:{placement:"inline",inbox:!1,reply:!0}})}i(R,"providerApprovalPage");function w(n,e){return e===null?null:a(n,"SELECT node_id, run_id, grantee FROM node_rows WHERE node_id = ? AND run_id IS NOT NULL").get(e)??null}i(w,"askingNode");function g(n){return JSON.parse(n.specification_json)}i(g,"manifestOf");function u(n,e=d()){return n.kind!=="page"||!n.settleable?null:w(e,n.requester_node_id)}i(u,"questionRun");function c(n,e,t=d()){const r=g(n),o=p(t,n.request_id);return{question_id:n.request_id,initiating_app:e,title:n.title,...n.subtitle?{subtitle:n.subtitle}:{},...o?{provider:o.provider,tool:o.tool}:{},steps:r.steps,slots:r.slots.map(s=>({...s.id===void 0?{}:{id:s.id},kind:s.kind,step:s.step,config:s.config}))}}i(c,"questionFields");function D(n,e){const t=u(e,n);t===null||e.state!=="open"||l(n,t.run_id,t.node_id,"waiting_on_user",c(e,t.grantee,n))}i(D,"appendWaitingOnUser");function T(n,e){const t=e.result_json===null?null:JSON.parse(e.result_json);if(p(n,e.request_id)!==null){const s=t?.responses?.options?.selectedOptionIds?.[0];if(e.outcome==="answered"&&(typeof s!="string"||!s))throw new Error(`provider approval ${e.request_id} has no selected option`);a(n,"UPDATE provider_approvals SET status = ?, option_id = ? WHERE question_id = ? AND status = 'open'").run(e.outcome==="answered"?"answered":"canceled",e.outcome==="answered"?s:null,e.request_id)}if(e.outcome!=="answered"||t===null)return;const o=u(e,n);o!==null&&l(n,o.run_id,o.node_id,"question.answered",{question_id:e.request_id,answer:t.responses??{}})}i(T,"appendQuestionAnswered");function k(n,e=d()){return a(e,`SELECT h.request_id FROM human_requests h JOIN node_rows n ON n.node_id = h.requester_node_id
+    WHERE n.run_id = ? AND h.kind = 'page' AND h.state = 'open' AND h.settleable = 1
+    ORDER BY h.created_at, h.request_id`).all(n).map(t=>t.request_id)}i(k,"openQuestionIds");function h(n){return n.state!=="settled"?"open":n.outcome==="answered"?"answered":"canceled"}i(h,"questionStatus");function E(n){if(n.result_json===null)return null;const e=JSON.parse(n.result_json);return n.outcome==="answered"?e.responses??{}:e}i(E,"questionResult");function J(n,e,t){const r=h(n);return{...c(n,e?.grantee??t.grantee),...e===null?{}:{run_id:e.run_id,node_id:e.node_id},status:r,...r==="answered"?{answer:E(n)}:{}}}i(J,"questionObject");function L(n){const e=f(n);if(e===null||e.kind!=="page"||!e.settleable)return null;const t=d(),r=u(e,t),o=p(t,n);return r===null&&o===null?null:{request:e,run:r,approval:o}}i(L,"getQuestion");function v(n){const[e,t]="run_id"in n?["n.run_id = ?",n.run_id]:"node_id"in n?["n.node_id = ?",n.node_id]:["n.grantee = ?",n.grantee];return d().prepare(`SELECT h.request_id FROM human_requests h JOIN node_rows n ON n.node_id = h.requester_node_id
+    WHERE ${e} AND n.run_id IS NOT NULL AND h.kind = 'page' AND h.state = 'open' AND h.settleable = 1`).all(t).map(r=>r.request_id)}i(v,"openQuestionIdsFor");async function j(n,e){const t=v(n);if(!t.length)return 0;const{cancelHumanTicket:r}=await import("../../daemon/human/finish.js");let o=0;for(const s of t)(await r(s,{reason:e,actor:"crtrd"})).outcome==="settled"&&(o+=1);return o}i(j,"cancelOpenQuestions");export{T as appendQuestionAnswered,D as appendWaitingOnUser,j as cancelOpenQuestions,L as getQuestion,k as openQuestionIds,v as openQuestionIdsFor,R as providerApprovalPage,J as questionObject,E as questionResult,u as questionRun,h as questionStatus};

package/dist/core/runtime/advertised-command-invocation.d.ts

@@ -0,0 +1,20 @@
+import type { BrokerSession } from './broker/read-ops.js';
+export interface AdvertisedCommandInvocationMetadata {
+    crouterAdvertisedCommandInvocation: {
+        raw: string;
+    };
+}
+/** Restore extension-owned details while projecting persisted invocation
+ * metadata onto the runtime custom message. */
+export declare function hydratePersistedAdvertisedCommandMessages(messages: readonly unknown[]): void;
+/** Add live invocation metadata without changing extension-owned content or
+ * details. EventProjection calls this before relaying a custom message. */
+export declare function hydrateLiveAdvertisedCommandMessage(message: unknown): void;
+/** Bind the imminent message_end persistence call to the exact queued app
+ * message rather than to a payload-equality search across pending queues. */
+export declare function prepareAdvertisedCommandPersistence(session: BrokerSession, message: unknown): void;
+/** Install persistence/reload plumbing once on a newly built broker session. */
+export declare function installAdvertisedCommandInvocationContract(session: BrokerSession): void;
+/** Preserve a chat-advertised extension command's exact submitted text on the
+ * first displayed custom message its handler persists. */
+export declare function promptWithAdvertisedCommandInvocation<T>(session: BrokerSession, raw: string, runPrompt: () => Promise<T>): Promise<T>;

package/dist/core/runtime/advertised-command-invocation.js

@@ -0,0 +1 @@
+var S=Object.defineProperty;var u=(t,e)=>S(t,"name",{value:e,configurable:!0});import{AsyncLocalStorage as A}from"node:async_hooks";import{registrationChatSurface as j}from"./command-surface.js";const w=new A,y=new A,h=new WeakSet,M=new WeakSet,g=new WeakMap;function E(t){return{crouterPersistenceEnvelope:!0,crouterAdvertisedCommandInvocation:{raw:t.raw},...t.details===void 0?{}:{extensionDetails:t.details}}}u(E,"persistenceDetails");function W(t){if(typeof t!="object"||t===null)return null;const e=t;return e.crouterPersistenceEnvelope===!0&&typeof e.crouterAdvertisedCommandInvocation?.raw=="string"?e:null}u(W,"persistedDetails");function m(t,e){const n=e.content===t.content||t.content==null&&Array.isArray(e.content)&&e.content.length===0;return e.customType===t.customType&&n&&e.details===t.details&&e.display===!0}u(m,"matchesTarget");function k(t){if(typeof t!="object"||t===null)return;const e=t;if(e.role!=="custom")return;const n=W(e.details);n!==null&&(e.details=n.extensionDetails,e.crouterAdvertisedCommandInvocation=n.crouterAdvertisedCommandInvocation)}u(k,"hydratePersistedMessage");function b(t){for(const e of t)k(e)}u(b,"hydratePersistedAdvertisedCommandMessages");function I(t){if(typeof t!="object"||t===null)return;const e=t;if(e.role!=="custom"||typeof e.crouterAdvertisedCommandInvocation?.raw=="string")return;const n=y.getStore();n===void 0||n.relayed||!m(n,e)||(n.relayed=!0,e.crouterAdvertisedCommandInvocation={raw:n.raw},n.persisted&&M.add(e))}u(I,"hydrateLiveAdvertisedCommandMessage");function L(t,e){if(typeof e!="object"||e===null||M.has(e))return;const n=e;if(n.role!=="custom"||n.display!==!0)return;const f=n.crouterAdvertisedCommandInvocation;typeof f?.raw=="string"&&g.set(t.sessionManager,{raw:f.raw,customType:String(n.customType??""),content:n.content,details:n.details,persisted:!1,relayed:!0})}u(L,"prepareAdvertisedCommandPersistence");function D(t){if(h.has(t))return;h.add(t);const e=[],n=t.sessionManager,f=n.appendCustomMessageEntry.bind(n);n.appendCustomMessageEntry=(r,i,o,c)=>{const s=y.getStore(),p=g.get(n),a=p!==void 0&&m(p,{customType:r,content:i,display:o,details:c})?p:s!==void 0&&!s.persisted&&m(s,{customType:r,content:i,display:o,details:c})?s:e.find(d=>!d.persisted&&m(d,{customType:r,content:i,display:o,details:c}));if(a===void 0)return f(r,i,o,c);if(a.persisted=!0,a===p){g.delete(n);const d=e.findIndex(x=>x.raw===a.raw&&m(x,{customType:r,content:i,display:o,details:c}));d!==-1&&e.splice(d,1)}else{const d=e.indexOf(a);d!==-1&&e.splice(d,1)}return f(r,i,o,E(a))};const C=n.buildSessionContext.bind(n);n.buildSessionContext=()=>{const r=C();return b(r.messages),r},b(t.messages);const l=t.agent;for(const r of l===void 0?[]:["steer","followUp"]){const i=l?.[r];typeof i!="function"||l===void 0||(l[r]=(o,...c)=>{const s=y.getStore();return s!==void 0&&typeof o=="object"&&o!==null&&m(s,o)&&(I(o),!s.persisted&&!e.includes(s)&&e.push(s)),i.call(l,o,...c)})}const v=t.sendCustomMessage.bind(t);t.sendCustomMessage=(r,i)=>{const o=w.getStore();if(o===void 0||!o.active||o.claimed||r.display!==!0)return v(r,i);o.claimed=!0;const c={raw:o.raw,customType:r.customType,content:r.content,details:r.details,persisted:!1,relayed:!1};return y.run(c,()=>{const s=v(r,i);if(i?.deliverAs==="nextTurn"){const p=t._pendingNextTurnMessages;if(Array.isArray(p))for(let a=p.length-1;a>=0;a-=1){const d=p[a];if(!(typeof d!="object"||d===null||!m(c,d))){I(d),e.push(c);break}}}return s})}}u(D,"installAdvertisedCommandInvocationContract");function N(t,e,n){if(!e.startsWith("/"))return n();const f=e.indexOf(" "),C=f===-1?e.slice(1):e.slice(1,f);let l;try{l=t.extensionRunner?.getCommand(C)}catch{return n()}if(!j(l).gatewayCapable)return n();D(t);const v={raw:e,claimed:!1,active:!0};return w.run(v,async()=>{try{return await n()}finally{v.active=!1}})}u(N,"promptWithAdvertisedCommandInvocation");export{I as hydrateLiveAdvertisedCommandMessage,b as hydratePersistedAdvertisedCommandMessages,D as installAdvertisedCommandInvocationContract,L as prepareAdvertisedCommandPersistence,N as promptWithAdvertisedCommandInvocation};

package/dist/core/runtime/auth-reload.d.ts

@@ -0,0 +1,7 @@
+/** Reload a LIVE node's credentials over its view.sock. Connects as an
+ *  OBSERVER, sends `reload_auth`, and resolves on its ack. The handler is open
+ *  to any role, but observer accurately describes this role-independent operation.
+ *  Rejects on the broker's `error` frame,
+ *  connect failure, a premature close, or timeout — the caller (the daemon fan)
+ *  isolates each broker so one failure never aborts the rest. */
+export declare function reloadAuthLive(nodeId: string): Promise<void>;

package/dist/core/runtime/auth-reload.js

@@ -0,0 +1 @@
+var f=Object.defineProperty;var l=(n,i)=>f(n,"name",{value:i,configurable:!0});import{randomUUID as d}from"node:crypto";import{BrokerClient as h}from"../broker-client/index.js";const a=3e3;function w(n){return new Promise((i,r)=>{const o=new h(n),u=d();let s=!1;const c=setTimeout(()=>t(()=>r(new Error(`timed out after ${a}ms waiting for the broker to ack the auth reload`))),a);typeof c.unref=="function"&&c.unref();function t(e){if(!s){s=!0,clearTimeout(c);try{o.close()}catch{}e()}}l(t,"finish"),o.on("error",e=>t(()=>r(e))),o.on("close",()=>t(()=>r(new Error("broker connection closed before it acked the auth reload")))),o.on("connect",()=>{o.send({type:"hello",role:"observer",client_id:u}),o.send({type:"reload_auth"})}),o.on("frame",e=>{e.type==="ack"&&e.for==="reload_auth"&&e.ok?t(()=>i()):e.type==="error"&&t(()=>r(new Error(e.message)))}),o.connect()})}l(w,"reloadAuthLive");export{w as reloadAuthLive};

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

@@ -0,0 +1,15 @@
+export interface BannerInfo {
+    /** crtr version, e.g. "0.3.78" → shown as "v0.3.78". */
+    version?: string;
+    /** Active profile name, e.g. "acme". */
+    profile?: string;
+    /** Launch directory (already home-abbreviated if desired). */
+    cwd?: string;
+    /** One dim line under the cube (e.g. the tmux survival hint). */
+    hint?: string;
+}
+/** The crouton banner as pre-colored terminal lines: the cube on the left with
+ *  name/version, tagline, profile, and launch path stacked beside rows 1–4.
+ *  Missing facts are simply omitted (their row shows just the cube). No
+ *  leading/trailing blank lines — the caller frames it. */
+export declare function croutonBannerLines(info?: BannerInfo): string[];

package/dist/core/runtime/banner.js

@@ -0,0 +1 @@
+var m=Object.defineProperty;var u=(t,o)=>m(t,"name",{value:o,configurable:!0});const n="\x1B[0m",r="\x1B[38;5;180m",p="\x1B[38;5;137m",a="\x1B[1m",c="\x1B[2m";function $(t){return r+t.replace(/\./g,`${p}.${r}`)+n}u($,"crumb");const h=[$("      ________"),$("     /       /|"),$("    /  .  . / |"),$("   /_______/  |"),$("   |  .  . |  |"),$("   | .   . | /"),$("   |_______|/")];function b(t={}){const e=[`${a}${r}crouter${n}${t.version?`${c}  v${t.version}${n}`:""}`,`${c}the agentic runtime${n}`];t.profile&&e.push(`${c}profile: ${n}${r}${t.profile}${n}`),t.cwd&&e.push(`${c}${t.cwd}${n}`);const s=[];for(let _=0;_<h.length;_++){const i=_>=1&&_-1<e.length?`   ${e[_-1]}`:"";s.push(h[_]+i)}return t.hint&&s.push("",`${c}${t.hint}${n}`),s}u(b,"croutonBannerLines");export{b as croutonBannerLines};

package/dist/core/runtime/bearings-render.d.ts

@@ -0,0 +1,62 @@
+import { type NamedNode } from '../canvas/labels.js';
+export declare function escapeAttribute(value: string): string;
+/** The `<project_context>` block — the `<environment>` snapshot only: a
+ *  host/runtime line (platform, hostname, node version, tmux-or-not — the
+ *  headless engine's own process env, which its bash tools inherit), the cwd
+ *  dir listing, and git status/worktrees. Project guidance lives in the
+ *  document substrate, so this wrapper stays environment-only. It always emits
+ *  because the environment snapshot is always present. */
+export declare function buildProjectContextBlock(cwd: string): string;
+/** The documents-and-context-directory note — says where documents written for
+ *  another reader live (canvas documents the node owns, pointed at by name) and
+ *  names the context directory path INLINE (no XML attribute, so it never scopes
+ *  a sibling block) as the place for files that are not documents. Present for
+ *  every node, rendered as the `## Your documents and context directory`
+ *  subsection of <crtr-bearings>. */
+export declare function contextDirNote(nodeId: string, grantee?: string): string;
+/** The profile-purview note — rendered ONLY when the profile resolves to a
+ *  manifest that names at least one project dir. Phrased as PURVIEW, not a cwd
+ *  replacement: the node's cwd is still its one working dir (bash/edits run
+ *  there), the profile just widens what it may ALSO read/act on. Omitted
+ *  entirely for a profile with no project purview (including the stable root
+ *  profile) or a deleted/unreadable manifest — never throws. This absolute-path
+ *  disclosure is intentional (spec-approved): the agent must know its full
+ *  purview, not a redacted count. */
+export declare function profileNote(cwd: string, profileId: string | null | undefined): string;
+/** Orchestrator-only framing: a resident orchestrator survives refresh cycles,
+ *  so the documents it owns are also where a future cycle of itself resumes the
+ *  work. Used inside the bearings block (both lanes) AND in the promotion
+ *  guidance, so a promoted node gets the same note a born-orchestrator gets. */
+export declare function orchestratorContextNote(): string;
+/** The fork's context note: the fork's own context directory replaces the
+ *  source's for files, and the source's documents stay the source's — a bare
+ *  document name in the copied conversation now needs the source's prefix. */
+export declare function forkContextNote(nodeId: string, grantee: string | undefined, sourceId: string): string;
+export interface RelativeLabelNode extends NamedNode {
+    node_id: string;
+    kind: string;
+    status: string;
+    name: string;
+    description?: string;
+    icon?: string;
+}
+/** One relative's line in the map: `<id> — <kind> · <status>`, plus the node's
+ *  task description when it carries one (orientation: what that relative is for). */
+export declare function relativeLabel(node: RelativeLabelNode): string;
+/** The graph mini-map: the ancestry trunk (root first), then this node marked
+ *  `● you`, then its immediate children. Returns '' for a lone root with no
+ *  children (nothing to map). */
+export declare function renderGraphMap(nodeId: string, kind: string, mode: string, trunk: readonly RelativeLabelNode[], children: readonly RelativeLabelNode[]): string;
+/** The identity assertion injected at session start. A fork names its source
+ *  while treating the copied first-person narrative as reference. The caller
+ *  resolves `sourceLabel`: the bare `forkFrom` id when the source lookup
+ *  fails/is unsafe, else `${forkFrom} ("${fullName(src)}")`. */
+export declare function buildIdentityAssertion(nodeId: string, kind: string, mode: string, forkFrom: string | null | undefined, sourceLabel: string): string;
+export interface ManagedWorktreeLike {
+    state: string;
+    path: string;
+    branch: string;
+    base_ref: string;
+    base_sha: string;
+}
+export declare function worktreeNote(worktree: ManagedWorktreeLike | null | undefined): string;

package/dist/core/runtime/bearings-render.js

@@ -0,0 +1,18 @@
+var b=Object.defineProperty;var s=(e,t)=>b(e,"name",{value:t,configurable:!0});import{contextDir as m}from"../canvas/paths.js";import{fullName as w}from"../canvas/labels.js";import{tmuxSessionsReachable as v}from"./tmux-driver.js";import{spawnSync as x}from"node:child_process";import{readdirBeneath as k}from"../spaces/open-beneath.js";import{hostname as _}from"node:os";import{loadProfileManifest as C}from"../profiles/manifest.js";function D(e){return e.replaceAll("&","&amp;").replaceAll('"',"&quot;").replaceAll("<","&lt;").replaceAll(">","&gt;")}s(D,"escapeAttribute");function N(){const e=v();return`Host: ${[`${process.platform} ${process.arch}`,_(),`node ${process.version}`,`tmux server: ${e?"reachable":"none"}`].join(" \xB7 ")}`}s(N,"runtimeLine");function T(e){try{const n=k("/",e).sort((i,a)=>i.isDirectory()!==a.isDirectory()?i.isDirectory()?-1:1:i.name.localeCompare(a.name)),r=n.slice(0,50).map(i=>`${i.name}${i.isDirectory()?"/":""}`),o=n.length-r.length;return o>0?[...r,`[+${o} more]`]:r}catch{return["Directory listing: unavailable (cwd missing or unreadable)."]}}s(T,"directoryListingLines");function f(e,t,n,r){const o=x(t,n,{cwd:e,encoding:"utf8",...r===void 0?{}:{env:r}});return o.error!==void 0?{ok:!1,stdout:"",stderr:o.error.message}:{ok:o.status===0,stdout:(o.stdout??"").trim(),stderr:(o.stderr??"").trim()}}s(f,"runCommand");function $(){const e={...process.env,GIT_OPTIONAL_LOCKS:"0",GIT_CONFIG_NOSYSTEM:"1",GIT_CONFIG_GLOBAL:"/dev/null"};return delete e.GIT_CONFIG_PARAMETERS,delete e.GIT_CONFIG_COUNT,e}s($,"gitEnv");function d(e,t){const n=f(e,"git",t,$());return n.ok?n.stdout:""}s(d,"runGit");function A(e){const t=[];let n={};for(const r of e)r.startsWith("worktree ")?(n.path!==void 0&&t.push({path:n.path,branch:n.branch??"detached HEAD"}),n={path:r.slice(9)}):r.startsWith("branch ")&&(n.branch=r.slice(7).replace(/^refs\/heads\//,""));return n.path!==void 0&&t.push({path:n.path,branch:n.branch??"detached HEAD"}),t}s(A,"parseWorktrees");function G(e){const t=f(e,"git",["rev-parse","--is-inside-work-tree"],$());if(!t.ok)return/not a git repository/i.test(t.stderr)?["Git: not a git repository."]:[`Git: unavailable (${t.stderr||"git command failed"}).`];const n=d(e,["branch","--show-current"])||d(e,["rev-parse","--abbrev-ref","HEAD"])||"HEAD",r=d(e,["rev-parse","--short","HEAD"])||"unknown",o=d(e,["status","--porcelain"]).split(`
+`).filter(c=>c!=="").length,i=d(e,["worktree","list","--porcelain"]).split(`
+`),a=A(i),u=o===0?"clean":`${o} uncommitted change${o===1?"":"s"}`,h=`Git: ${n} @ ${r}; ${u}; ${a.length} worktree${a.length===1?"":"s"}.`,l=a.length===0?"Worktrees: none.":`Worktrees: ${a.map(c=>`${c.path} (${c.branch})`).join(", ")}`;return[h,l]}s(G,"gitSnapshotLines");function B(e){const t=T(e),n=G(e);let r=`<project_context>
+
+`;return r+=`<environment cwd="${D(e)}">
+`,r+=`${N()}
+`,r+=`Directory:
+${t.map(o=>`  ${o}`).join(`
+`)}
+`,r+=`${n.map(o=>`${o}`).join(`
+`)}
+`,r+=`</environment>
+</project_context>`,r}s(B,"buildProjectContextBlock");function W(e,t){return`Documents you write for another reader \u2014 specs, designs, findings, maps, plans \u2014 are canvas documents you own: write one with \`crtr doc write <name>\` (see \`crtr doc write -h\`), and point at it by the name it prints, \`[[${e}/<name>]]\`, never by a file path; other nodes read it with \`crtr canvas read\`, and inside this node the bare name resolves too. Your context directory \`${m(e,t)}\` (also \`$CRTR_CONTEXT_DIR\`) holds only what is not a document: scripts, data, logs and page modules. Your working dir is the project, NOT this directory, so a bare relative \`context/...\` lands in the repo, not here.`}s(W,"contextDirNote");function P(e,t){if(t==null||t==="")return"";let n;try{n=C(t)}catch{return""}const r=n.manifest.projects.map(o=>o.path);return r.length===0?"":`Your working dir is \`${e}\`. Your profile **${n.manifest.name}** also has purview over: ${r.join(", ")}.`}s(P,"profileNote");function M(){return"Because you persist across refresh cycles, the documents you own are also where a future cycle of you resumes the work: your document `roadmap` loads at every new session, and it points at the documents holding the decisions and findings a refreshed you would need, alongside the ones you share with the nodes you spawn."}s(M,"orchestratorContextNote");function F(e,t,n){return`Context directory: \`${m(e,t)}\` (\`$CRTR_CONTEXT_DIR\`), for files only; use it in place of every source-node context path above. Documents you write are yours. The source node's documents stay the source's: read them as \`[[${n}/<name>]]\`, and a bare document name in the copied conversation that meant one of them now needs that prefix.`}s(F,"forkContextNote");function y(e){const t=w(e),n=t!==""&&t!==e.kind&&t!==e.name?` \u2014 ${t}`:"";return`${e.node_id} (${e.kind} \xB7 ${e.status})${n}`}s(y,"relativeLabel");const O=5;function X(e,t,n,r,o){if(r.length===0&&o.length===0)return"";const i=s(c=>"  ".repeat(c),"indent"),a=["Your place in the canvas graph (ancestry above you, your direct children below):"];r.forEach((c,p)=>{a.push(`${i(p)}${p===0?"":"\u2514 "}${y(c)}`)});const u=r.length;a.push(`${i(u)}${u===0?"":"\u2514 "}\u25CF you: ${e} (${t}, ${n})`);const h=o.slice(0,O),l=o.length-h.length;return h.forEach((c,p)=>{const g=p===h.length-1&&l===0;a.push(`${i(u+1)}${g?"\u2514 ":"\u251C "}${y(c)}`)}),l>0&&a.push(`${i(u+1)}\u2514 +${l} more`),a.join(`
+`)}s(X,"renderGraphMap");function z(e,t,n,r,o){const i=[`You are node ${e} \u2014 kind ${t}, mode ${n}.`];return r!=null&&r!==""&&i.push("",`You are a new FORK of ${o}, not ${o}. Pi copied the earlier conversation into this session. Treat that first-person history as reference material, not your own past.`),i.join(`
+`)}s(z,"buildIdentityAssertion");function K(e){return e?.state!=="open"?"":`Branch: \`${e.branch}\`
+Worktree: \`${e.path}\`
+Base: \`${e.base_ref}\` @ \`${e.base_sha}\`
+Commit work here. Before finishing, land it with \`crtr node worktree close\` or keep the checkout and branch when the worktree is clean and its exact tip exists on any branch on origin. Auto-drop applies only when the worktree is clean (no uncommitted changes) and nothing remains to land (zero commits ahead of the base, or its commits are already contained in the base); otherwise, unlanded commits or uncommitted changes block finalization.`}s(K,"worktreeNote");export{z as buildIdentityAssertion,B as buildProjectContextBlock,W as contextDirNote,D as escapeAttribute,F as forkContextNote,M as orchestratorContextNote,P as profileNote,y as relativeLabel,X as renderGraphMap,K as worktreeNote};

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

@@ -0,0 +1,56 @@
+import { type Cron } from '../canvas/index.js';
+import type { DeliveredDoc, RenderContext } from '../substrate/delivery/render-event.js';
+import { buildProjectContextBlock, contextDirNote, orchestratorContextNote } from './bearings-render.js';
+/** The bearings custom type is shared with every attached renderer. */
+export { CONTEXT_INTRO_CUSTOM_TYPE } from '../../shared/generated-context.js';
+export { buildProjectContextBlock, contextDirNote, orchestratorContextNote };
+/** The profile-purview note — rendered ONLY when `profile_id` resolves to a
+ *  manifest that names at least one project dir. Phrased as PURVIEW, not a cwd
+ *  replacement: the node's cwd is still its one working dir (bash/edits run
+ *  there), the profile just widens what it may ALSO read/act on. Omitted
+ *  entirely for a profile with no project purview (including the stable root
+ *  profile) or a deleted/unreadable manifest — never throws (mirrors
+ *  `assembleNodeSubject`'s profile resolution). This absolute-path disclosure
+ *  is intentional (spec-approved): the agent must know its full purview, not a
+ *  redacted count. */
+export declare function profileNote(nodeId: string): string;
+/** The graph mini-map: the ancestry trunk (root first), then this node marked
+ *  `● you`, then its immediate children. Returns '' for a lone root with no
+ *  children (nothing to map). Exported for testing. */
+export declare function buildGraphMap(nodeId: string): string;
+/** Why a node was born or woken, as carried from the fired cron to the
+ *  injection seam. `ownerName` is the armer's resolved display name when it
+ *  still exists (a reaped cron's armer renders as a bare id, never crashes). */
+export interface WakeOrigin {
+    /** Which enactment the cron drove: a fresh node (`node_birth`) or a fresh
+     *  revive of an existing one (`schedule_revive`). */
+    kind: 'node_birth' | 'schedule_revive';
+    /** The armer node id (`crons.created_by`), or null if absent. */
+    ownerId: string | null;
+    /** The armer's display name, resolved if it still exists. */
+    ownerName?: string;
+    /** `crons.created` — when the cron was armed (ISO). */
+    armedAt: string;
+    /** `crons.recur` JSON when recurring, else null/undefined for a one-shot. */
+    recur?: string | null;
+}
+/** Build the provenance a fired cron carries to its injection seam, resolving
+ *  the armer's display name if that node still exists. */
+export declare function cronWakeOrigin(c: Cron, kind: WakeOrigin['kind']): WakeOrigin;
+/** Render the cron provenance block. The BIRTH variant names the ARMER
+ *  explicitly ("armed by node X") so a newborn never reads that id as its own;
+ *  the REVIVE variant drops armer attribution — a cron can revive a node it did
+ *  not create, and who armed it is not decision-relevant to a timed re-check —
+ *  and instead reframes the generic "you were revived" into "a clock woke you".
+ *  A recurrence surfaces its cadence either way, so the agent knows it is one
+ *  run of a standing job. No timestamp is rendered: "now"/the cadence already
+ *  carry the signal, and a raw ISO instant is noise an agent cannot cheaply turn
+ *  into an elapsed delta. */
+export declare function buildWakeBearings(origin: WakeOrigin): string;
+/** The bearings on the row-backed delivery engine: the knowledge catalog and
+ *  the workspace-open documents render against `ctx`'s ledger; `delivered`
+ *  lists what they delivered, for the caller to record. */
+export declare function buildContextBearings(nodeId: string, ctx: RenderContext): {
+    content: string;
+    delivered: DeliveredDoc[];
+};

package/dist/core/runtime/bearings.js

@@ -0,0 +1,7 @@
+var k=Object.defineProperty;var a=(e,n)=>k(e,"name",{value:n,configurable:!0});import{getNode as s,fullName as d,isSafeNodeId as y,subscriptionsOf as g}from"../canvas/index.js";import{cadenceDisplay as N}from"../wake.js";import{renderKnowledge as v,renderWorkspaceOpen as x}from"../substrate/delivery/render-boot.js";import{situationalContextEnvelope as _}from"./situational-context.js";import{statusRank as l}from"../canvas/node-order.js";import{buildProjectContextBlock as f,contextDirNote as p,orchestratorContextNote as h,profileNote as $,renderGraphMap as C,buildIdentityAssertion as S,worktreeNote as O}from"./bearings-render.js";import{CONTEXT_INTRO_CUSTOM_TYPE as J}from"../../shared/generated-context.js";function Y(e){const n=s(e);return n===null?"":$(n.cwd,n.profile_id)}a(Y,"profileNote");function E(e){const n=[],r=new Set([e]);let o=s(e)?.parent??null;for(;o!==null&&o!==""&&!r.has(o);){r.add(o);const t=s(o);if(t===null)break;n.unshift(t),o=t.parent??null}return n}a(E,"ancestorTrunk");const X=5;function j(e){return g(e).map(n=>s(n.node_id)).filter(n=>n!==null&&n.kind!=="human").sort((n,r)=>l(n.status)-l(r.status))}a(j,"childNodes");function A(e){const n=s(e);if(n===null)return"";const r=E(e),o=j(e);return C(e,n.kind,n.mode,r,o)}a(A,"buildGraphMap");function B(e){const n=s(e),r=n?.fork_from,o=r!=null&&r!==""&&y(r)?s(r):null,t=o!==null?`${r} ("${d(o)}")`:r??"";return S(e,n?.kind??"general",n?.mode??"base",r,t)}a(B,"buildIdentityAssertion");function R(e){return e.ownerId===null||e.ownerId===""?"an unknown node":e.ownerName!==void 0?`node ${e.ownerId} ("${e.ownerName}")`:`node ${e.ownerId} (now gone)`}a(R,"armerPhrase");function F(e,n){const r=e.created_by!=null?s(e.created_by):null;return{kind:n,ownerId:e.created_by,...r!==null?{ownerName:d(r)}:{},armedAt:e.created,recur:e.recur}}a(F,"cronWakeOrigin");function I(e){const n=e.recur!==null&&e.recur!==void 0&&e.recur!=="",r=n?N(e.recur):null;if(e.kind==="schedule_revive")return`<crtr-wake>
+${n?`A SCHEDULE woke you, not a message \u2014 a recurring cron firing ${r} revived you fresh. Nothing new happened on the canvas and nobody is waiting on a reply: the clock came round. Re-read your bearings below, do this cycle's pass of the standing job, and stop.`:"A SCHEDULE woke you, not a message \u2014 a one-shot cron armed to fire now revived you fresh. Nothing new happened on the canvas and nobody is waiting on a reply: the time you were waiting for arrived. Re-read your bearings below and continue from there."}
+</crtr-wake>`;const o=R(e);return`<crtr-wake>
+${n?`You were BORN by a scheduled wake, not spawned on demand \u2014 a recurring spawn-cron armed by ${o}, firing ${r}. The runtime re-births a fresh node like you on this cadence whether or not earlier runs survived: you are one run of a standing job, not a one-off, and you inherit nothing from prior runs but this task. Your task follows.`:`You were BORN by a scheduled wake, not spawned on demand \u2014 a one-shot deferred birth armed by ${o} to fire now. You are its only run, not a recurring job. Your task follows.`}
+</crtr-wake>`}a(I,"buildWakeBearings");function T(e){return O(e?.managed_worktree)}a(T,"managedWorktreeNote");function D(e,n,r){const o=s(e),t=["<crtr-bearings>",B(e)],u=A(e);u!==""&&t.push("","## Your place in the canvas",u),t.push("","## Your documents and context directory",p(e,o?.grantee));const i=Y(e);i!==""&&t.push("",i);const c=T(o);c!==""&&t.push("","## Your managed worktree",c),o?.mode==="orchestrator"&&t.push("",h()),t.push("</crtr-bearings>");const w=_(e)??"",m=o?.cwd!==void 0?f(o.cwd):"";return[t.join(`
+`),n,r,w,m].filter(b=>b!=="").join(`
+`)}a(D,"bearingsShell");function K(e,n){const r=v(n),o=x(n);return{content:D(e,r.content,o.content),delivered:[...r.delivered,...o.delivered]}}a(K,"buildContextBearings");export{J as CONTEXT_INTRO_CUSTOM_TYPE,K as buildContextBearings,A as buildGraphMap,f as buildProjectContextBlock,I as buildWakeBearings,p as contextDirNote,F as cronWakeOrigin,h as orchestratorContextNote,Y as profileNote};

package/dist/core/runtime/bin-contributions.d.ts

@@ -0,0 +1,44 @@
+import type { Scope } from '../../types.js';
+/** One resolved bare command: the name a node's bash sees, and the absolute
+ *  real path the shim links to. */
+export interface ResolvedBin {
+    name: string;
+    /** Absolute target validated inside the contributing root when this set resolved. */
+    target: string;
+    /** Human-readable contributor, e.g. `plugin "deploy-tools"` or
+     *  `config.json (/repo/.crouter)`. */
+    origin: string;
+    scope: Scope;
+}
+/** A declaration that did NOT become a bare command, with why. Surfaced by
+ *  `crtr sys doctor`; never thrown, so one bad entry can never stop a node
+ *  from launching. */
+export interface BinIssue {
+    name: string;
+    origin: string;
+    scope: Scope;
+    message: string;
+}
+export interface BinResolution {
+    /** Effective name → resolved bin, after layering. */
+    bins: Map<string, ResolvedBin>;
+    issues: BinIssue[];
+}
+/** The effective bare-command set for one node's cwd/profile, plus every
+ *  declaration that failed to become one.
+ *
+ *  Layers ascend in precedence (see `contributionLayers`). A name claimed by
+ *  two contributors in the SAME layer selects no winner: it is reported and
+ *  removed, so an ambiguous name resolves to nothing rather than to whichever
+ *  plugin sorted first. A higher layer may still claim that name explicitly —
+ *  that is an unambiguous choice, not a collision. */
+export declare function resolveBinContributions(targetCwd: string, targetProfileId: string | null): BinResolution;
+/** Materialize (idempotently) the shim directory for one effective set and
+ *  return its absolute path, or null when the set is empty. Built in a staging
+ *  dir and renamed into place, so a concurrent launch either sees no directory
+ *  or sees a complete one. */
+export declare function ensureBinShimDir(bins: Map<string, ResolvedBin>): string | null;
+/** The shim directory to prepend to a target node's PATH, or null when that
+ *  node's scopes declare no bare command. The one entry point the spawn-env
+ *  boundary calls. */
+export declare function binShimDirFor(targetCwd: string, targetProfileId: string | null): string | null;

package/dist/core/runtime/bin-contributions.js

@@ -0,0 +1,2 @@
+var S=Object.defineProperty;var i=(r,t)=>S(r,"name",{value:t,configurable:!0});import{createHash as j}from"node:crypto";import{existsSync as g,mkdirSync as x,realpathSync as p,renameSync as v,rmSync as w,statSync as C,symlinkSync as I}from"node:fs";import{dirname as R,join as l,resolve as k,sep as D}from"node:path";import{binDeclarationIssues as B,normalizeBin as d,readRawConfigAtRoot as F}from"../config.js";import{listInstalledPluginsInRoot as z}from"../installed-plugins.js";import{crtrHome as A}from"../canvas/paths.js";import{findProjectScopeRoots as H,scopeRoot as M}from"../scope.js";function b(r,t,e){return B(e).map(n=>({name:n.name,origin:r,scope:t,message:n.message}))}i(b,"contributorIssues");function h(r,t){return z(r,t).filter(e=>e.enabled&&e.manifest.bin!==void 0).sort((e,n)=>e.name.localeCompare(n.name)).map(e=>{const n=`plugin "${e.name}"`;return{origin:n,scope:r,root:e.root,bin:d(e.manifest.bin),issues:b(n,r,e.manifest.bin)}})}i(h,"pluginContributors");function y(r,t){const e=F(t)?.bin;if(e===void 0)return[];const n=`config.json (${t})`,c=d(e),s=r==="project"?R(t):t;return[{origin:n,scope:r,root:s,bin:c,issues:b(n,r,e)}]}i(y,"configContributor");function O(r,t){const e=[],n=M("user");n!==null&&e.push(h("user",n),y("user",n));const c=H(r,t);for(const s of[...c].reverse())e.push(h("project",s),y("project",s));return e.filter(s=>s.length>0)}i(O,"contributionLayers");function L(r,t){let e,n;try{e=p(r),n=p(k(r,t))}catch{return{reason:`target does not exist: ${l(r,t)}`}}if(n!==e&&!n.startsWith(e+D))return{reason:`target escapes its contributing root: ${t}`};const c=C(n);return c.isFile()?(c.mode&73)===0?{reason:`target lacks the POSIX exec bit: ${n}`}:{target:n}:{reason:`target is not a regular file: ${n}`}}i(L,"resolveTarget");function N(r,t){const e=new Map,n=[];for(const c of O(r,t)){const s=new Map;for(const o of c){n.push(...o.issues);for(const u of Object.keys(o.bin)){const a=s.get(u);a===void 0?s.set(u,[o]):a.push(o)}}for(const[o,u]of s){if(u.length>1){const $=u.map(m=>m.origin).join(", ");e.delete(o);for(const m of u)n.push({name:o,origin:m.origin,scope:m.scope,message:`bare command "${o}" is claimed by ${$} at the same precedence \u2014 no winner is selected and the name is not installed`});continue}const a=u[0],f=L(a.root,a.bin[o]);if("reason"in f){n.push({name:o,origin:a.origin,scope:a.scope,message:f.reason});continue}e.set(o,{name:o,target:f.target,origin:a.origin,scope:a.scope})}}return{bins:e,issues:n}}i(N,"resolveBinContributions");function T(r){const t=[...r.values()].sort((e,n)=>e.name.localeCompare(n.name)).map(e=>`${e.name}\0${e.target}`).join(`
+`);return j("sha256").update(t).digest("hex").slice(0,32)}i(T,"shimAddress");function W(r){if(r.size===0)return null;const t=l(A(),"bin-shims",T(r));if(g(t))return t;const e=`${t}.staging-${process.pid}-${Date.now().toString(36)}`;x(e,{recursive:!0});try{for(const n of r.values())I(n.target,l(e,n.name));v(e,t)}catch(n){if(w(e,{recursive:!0,force:!0}),g(t))return t;throw n}return t}i(W,"ensureBinShimDir");function U(r,t){return W(N(r,t).bins)}i(U,"binShimDirFor");export{U as binShimDirFor,W as ensureBinShimDir,N as resolveBinContributions};