@north-light/cli 0.0.0 → 0.3.414

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

@@ -0,0 +1,16 @@
+import type { EventComponent } from './types.js';
+export interface BoundEventSource {
+    component: EventComponent;
+    path: string;
+    node_id?: string;
+    stream_id?: string;
+}
+export declare function bindDaemonEventSource(): void;
+export declare function bindBrokerEventSource(nodeId: string): void;
+export declare function eventSource(): BoundEventSource | undefined;
+/** Test-only: clear the process-global binding. A single test process can
+ * legitimately play several components in sequence (an in-process revive binds
+ * a broker source via host.ts's bind-if-unbound; a later daemon-tick test then
+ * inherits it and trips emit's cross-node guard). Production processes bind
+ * exactly once and never reset. */
+export declare function resetEventSourceForTests(): void;

package/dist/core/events/source.js

@@ -0,0 +1 @@
+var d=Object.defineProperty;var e=(o,n)=>d(o,"name",{value:n,configurable:!0});import{join as t}from"node:path";import{crtrHome as u,isSafeNodeId as p,jobDir as c}from"../canvas/paths.js";let r;function m(o,n){return o.component===n.component&&o.path===n.path&&o.node_id===n.node_id&&o.stream_id===n.stream_id}e(m,"equal");function i(o){if(r===void 0){r=o;return}if(!m(r,o))throw new Error("event source is already bound for this process")}e(i,"bind");function b(){i({component:"daemon",path:t(u(),"crtrd.log")})}e(b,"bindDaemonEventSource");function _(o){if(!p(o))throw new TypeError("node_id must be a non-empty path segment of at most 128 UTF-8 bytes");i({component:"broker",node_id:o,path:t(c(o),"log.jsonl")})}e(_,"bindBrokerEventSource");function h(){return r}e(h,"eventSource");function v(){r=void 0}e(v,"resetEventSourceForTests");export{_ as bindBrokerEventSource,b as bindDaemonEventSource,h as eventSource,v as resetEventSourceForTests};

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

@@ -0,0 +1,68 @@
+export type EventLevel = 'error' | 'warn' | 'info' | 'debug';
+export type EventComponent = 'daemon' | 'broker' | 'control-plane' | 'front' | 'sentinel';
+export type EventOutcome = 'succeeded' | 'failed' | 'skipped';
+export type RetryDisposition = 'auto' | 'manual' | 'fatal';
+export type OperationId = string & {
+    readonly __operationId: unique symbol;
+};
+export declare const errorClassCodes: readonly ["rate_limit", "overloaded", "connection", "auth", "protocol", "context_overflow", "wedged", "model_not_found", "unknown"];
+export type ErrorClassCode = (typeof errorClassCodes)[number];
+export interface ErrorClass {
+    class: ErrorClassCode;
+    status?: number;
+    provider?: string;
+    retry_disposition?: RetryDisposition;
+}
+export interface EventError {
+    type: string;
+    message: string;
+    stack?: string;
+    cause?: string;
+}
+export type EventField = null | boolean | number | string | readonly EventField[] | {
+    readonly [key: string]: EventField;
+};
+export interface EventEnvelope {
+    v: 1;
+    ts: string;
+    level: EventLevel;
+    event: string;
+    component: EventComponent;
+    operation_id: OperationId;
+    node_id?: string;
+    stream_id?: string;
+    duration_ms?: number;
+    outcome?: EventOutcome;
+    attempt?: number;
+    error_class?: ErrorClass;
+    error?: EventError;
+    fields?: Readonly<Record<string, EventField>>;
+    record_truncated?: true;
+    original_bytes?: number;
+    dropped_fields_count?: number;
+}
+export interface BuildEnvelopeInput {
+    ts?: string;
+    level: EventLevel;
+    event: string;
+    component: EventComponent;
+    operation_id?: string;
+    node_id?: string;
+    stream_id?: string;
+    duration_ms?: number;
+    outcome?: EventOutcome;
+    attempt?: number;
+    error_class?: ErrorClass;
+    error?: unknown;
+    fields?: Readonly<Record<string, unknown>>;
+}
+export interface ErrorClassHints {
+    status?: number;
+    provider?: string;
+    retry_disposition?: RetryDisposition;
+}
+export interface OperationIdContext {
+    current(): OperationId | undefined;
+    run<T>(operationId: string, callback: () => T): T;
+    fresh<T>(callback: (operationId: OperationId) => T): T;
+}

package/dist/core/events/types.js

@@ -0,0 +1 @@
+const o=["rate_limit","overloaded","connection","auth","protocol","context_overflow","wedged","model_not_found","unknown"];export{o as errorClassCodes};

package/dist/core/exclusive-lock.d.ts

@@ -0,0 +1,34 @@
+/** The pid currently holding this lock, read straight off the marker name (the
+ *  token opens with the owner's pid). Null when the lock is free, unowned, or
+ *  names a token we cannot parse. Lets a caller tell "my child is doing the
+ *  work" apart from "my child is queued behind someone else's work" without
+ *  any new bookkeeping. */
+export declare function exclusiveLockOwnerPid(path: string): number | null;
+/**
+ * Block until `path` is no longer held by a LIVE other process, or the wait
+ * runs out. Unlike `withExclusiveDirectoryLock*` this never CLAIMS the lock —
+ * it is for a reader that only needs the holder's transition to be over before
+ * it looks at the directory the holder is rewriting.
+ *
+ * Returns immediately when the lock is free, when its marker names this very
+ * process (a caller waiting on its own lock would otherwise deadlock), or when
+ * the named owner is gone — a dead holder's transition is already over, however
+ * it ended.
+ */
+export declare function awaitExclusiveLockRelease(path: string, timeoutMs: number): void;
+export interface ExclusiveLockOptions {
+    /** Grace before a lock that names no owner at all is cleared. */
+    staleMs?: number;
+    timeoutMs?: number;
+    /** The error thrown when the wait runs out, so callers keep their own remediation. */
+    timeoutError?: () => Error;
+}
+/**
+ * Run a short filesystem transition under a token-checked, crash-reclaimable
+ * directory lock. A holder that dies releases immediately — the next contender
+ * sees a dead pid in the marker name — while a live holder is never stolen from,
+ * however long its operation runs.
+ */
+export declare function withExclusiveDirectoryLock<T>(path: string, operation: () => T, options?: ExclusiveLockOptions): T;
+/** Run an awaited operation under the same token-checked directory lock. */
+export declare function withExclusiveDirectoryLockAsync<T>(path: string, operation: () => Promise<T>, options?: ExclusiveLockOptions): Promise<T>;

package/dist/core/exclusive-lock.js

@@ -0,0 +1 @@
+var x=Object.defineProperty;var o=(e,r)=>x(e,"name",{value:r,configurable:!0});import{existsSync as d,mkdirSync as D,readdirSync as M,rmSync as a,rmdirSync as T,statSync as A,unlinkSync as v,writeFileSync as L}from"node:fs";import{randomUUID as p}from"node:crypto";const f="owner.",m=10,I=250,E=3e4,h=5e3;function w(e){return Math.min(e*2,I)}o(w,"nextPollMs");function k(e){Atomics.wait(new Int32Array(new SharedArrayBuffer(4)),0,0,e)}o(k,"pause");function N(e){return new Promise(r=>setTimeout(r,e))}o(N,"pauseAsync");function l(e,r){return`${e}/${f}${r}`}o(l,"markerPath");function y(e){try{return M(e).find(r=>r.startsWith(f))?.slice(f.length)??null}catch{return null}}o(y,"observedMarkerToken");function S(e){const r=Number(e.split(".",1)[0]);if(!Number.isSafeInteger(r)||r<=0)return!1;try{return process.kill(r,0),!0}catch(t){return t.code==="EPERM"}}o(S,"ownerIsAlive");function _(e){try{return M(e).length===0}catch{return!1}}o(_,"isEmptyDirectory");function g(e){try{return Date.now()-A(e).mtimeMs}catch{return 0}}o(g,"ageMs");function P(e,r){const t=y(e);if(t!==null){if(S(t))return;try{v(l(e,t))}catch(n){if(n.code==="ENOENT")return;throw n}}else{if(g(e)<=r)return;if(!_(e)){a(e,{recursive:!0,force:!0});return}}try{T(e)}catch(n){const i=n.code;if(i!=="ENOENT"&&i!=="ENOTEMPTY"&&i!=="EEXIST")throw n}}o(P,"reclaimIfOwnerGone");function R(e){const r=y(e);if(r===null)return null;const t=Number(r.split(".",1)[0]);return Number.isSafeInteger(t)&&t>0?t:null}o(R,"exclusiveLockOwnerPid");function U(e,r){const t=Date.now()+r;let n=m;for(;;){const i=y(e);if(i===null||Number(i.split(".",1)[0])===process.pid||!S(i))return;const u=t-Date.now();if(u<=0)return;k(Math.min(n,u)),n=w(n)}}o(U,"awaitExclusiveLockRelease");function s(e,r){const t=`${process.pid}.${p()}`;try{return D(e,{mode:448}),L(l(e,t),"",{flag:"wx",mode:384}),{path:e,token:t}}catch(n){if(n.code!=="EEXIST")throw n;return P(e,r),null}}o(s,"tryAcquire");function F(e,r,t={}){const n=t.staleMs??E,i=Date.now()+(t.timeoutMs??h);let u=m,c=s(e,n);for(;c===null;){if(Date.now()>=i)throw t.timeoutError?.()??new Error(`timed out waiting for the exclusive lock: ${e}`);k(Math.min(u,Math.max(0,i-Date.now()))),u=w(u),c=s(e,n)}try{return r()}finally{d(l(c.path,c.token))&&a(c.path,{recursive:!0,force:!0})}}o(F,"withExclusiveDirectoryLock");async function X(e,r,t={}){const n=t.staleMs??E,i=Date.now()+(t.timeoutMs??h);let u=m,c=s(e,n);for(;c===null;){if(Date.now()>=i)throw t.timeoutError?.()??new Error(`timed out waiting for the exclusive lock: ${e}`);await N(Math.min(u,Math.max(0,i-Date.now()))),u=w(u),c=s(e,n)}try{return await r()}finally{d(l(c.path,c.token))&&a(c.path,{recursive:!0,force:!0})}}o(X,"withExclusiveDirectoryLockAsync");export{U as awaitExclusiveLockRelease,R as exclusiveLockOwnerPid,F as withExclusiveDirectoryLock,X as withExclusiveDirectoryLockAsync};

package/dist/core/fault-classifier.d.ts

@@ -0,0 +1,34 @@
+import type { ErrorClass, OperationId } from './events/types.js';
+import { type ProviderFailureDetails } from './provider-failure.js';
+export type FaultLink = 'pi→provider' | 'viewer↔broker' | 'relay↔broker' | 'viewer↔crtrd' | 'broker↔crtrd' | 'daemon→node' | 'crtr→pi';
+export type FaultKind = 'rate-limit' | 'overloaded' | 'connection' | 'auth' | 'protocol' | 'context-overflow' | 'other' | 'wedged' | 'model-not-found';
+export type FaultRetryDisposition = 'auto' | 'manual' | 'fatal';
+export type FaultRetryOwner = 'sdk' | 'daemon' | 'client';
+export interface FaultRetry {
+    disposition: FaultRetryDisposition;
+    by?: FaultRetryOwner;
+    attempt?: number;
+    max?: number;
+    nextAt?: string;
+}
+export interface FaultProviderError extends ProviderFailureDetails {
+    provider: string;
+    model: string;
+}
+export interface Fault {
+    link: FaultLink;
+    op: string;
+    kind: FaultKind;
+    retry: FaultRetry;
+    message: string;
+    since: string;
+    operation_id: OperationId;
+    anchorEntryId?: string;
+    providerError?: FaultProviderError;
+}
+export interface FaultClassification {
+    kind: FaultKind;
+    disposition: FaultRetryDisposition;
+}
+export declare function errorClassFromFault(fault: Pick<Fault, 'kind' | 'retry'>): ErrorClass;
+export declare function classify(link: FaultLink, raw: unknown): FaultClassification;

package/dist/core/fault-classifier.js

@@ -0,0 +1 @@
+var l=Object.defineProperty;var i=(e,o)=>l(e,"name",{value:o,configurable:!0});import{hasManagedProviderCoolingDiagnostic as u}from"./runtime/managed-provider-cooling.js";import{recognizeProviderError as f}from"./provider-error-recognition.js";import{extractProviderFailureDetails as p}from"./provider-failure.js";import{isRecord as a}from"../shared/predicates.js";const m={"rate-limit":"rate_limit",overloaded:"overloaded",connection:"connection",auth:"auth",protocol:"protocol","context-overflow":"context_overflow",wedged:"wedged","model-not-found":"model_not_found",other:"unknown"};function b(e){return{class:m[e.kind],retry_disposition:e.retry.disposition}}i(b,"errorClassFromFault");function v(e){switch(e.kind){case"rate-limit":return"rate-limit";case"auth":return"auth";case"protocol":return"protocol";case"context-overflow":return"context-overflow";case"overloaded":case"overloaded-only":case"transient-http":return"overloaded";case"connection":case"connection-only":return"connection";case"socket":case"service-unavailable":case"other":return"other"}}i(v,"faultKindFromProviderSignal");function g(e,o){return o==="auth"||o==="protocol"||o==="context-overflow"?"fatal":e==="pi\u2192provider"?o==="connection"||o==="rate-limit"||o==="overloaded"?"auto":"fatal":"manual"}i(g,"classifyDisposition");function y(e){if(typeof e=="string")return e;if(!a(e))return"";const o=[e.message,e.errorMessage,e.reason,e.body,e.statusText];for(const t of o)if(typeof t=="string"&&t!=="")return t;const r=e.error;if(a(r)){const t=r.message;if(typeof t=="string"&&t!=="")return t;const s=r.reason;if(typeof s=="string"&&s!=="")return s}return""}i(y,"rawText");function M(e,o){if(e==="pi\u2192provider"&&u(o))return{kind:"rate-limit",disposition:"auto"};const r=a(o)?o:{},t=p(o),s=t?.causes??[],d=f({code:r.code??t?.code??s.find(n=>n.code!==void 0)?.code,errno:r.errno??t?.errno??s.find(n=>n.errno!==void 0)?.errno,status:r.status??t?.status,wsCloseCode:r.code,wsCloseReason:r.reason,message:[y(o),t?.body,...s.flatMap(n=>[n.message,n.body])].filter(n=>typeof n=="string"&&n!=="").join(" ")}),c=v(d);return{kind:c,disposition:g(e,c)}}i(M,"classify");export{M as classify,b as errorClassFromFault};

package/dist/core/feed/feed.d.ts

@@ -0,0 +1,63 @@
+import type { InboxDisposition } from './inbox.js';
+export type PushKind = 'update' | 'urgent' | 'final';
+export type PushDeliveryTier = 'deferred' | 'normal' | 'urgent';
+export interface PushOpts {
+    kind: PushKind;
+    /** Update-only subscriber delivery urgency; report kind remains `kind`. */
+    deliveryTier?: PushDeliveryTier;
+    body: string;
+    from?: string;
+    /** Attribution snapshotted by the human-ticket settlement paths; absent means an ordinary report. */
+    disposition?: InboxDisposition;
+    /** Final only. The outcome the canonical final records; absent means `result`/`finalized`. */
+    outcome?: FinalOutcome;
+    /** Update only: this report answers a one-off structured-output request (`report.result`). */
+    result?: {
+        requestMessageId: string | null;
+    };
+}
+/** A declined structured result: the node finishes, but its latch records a failure. */
+export interface FinalOutcome {
+    /** Present only when the canonical final is a declined structured result. */
+    kind?: 'failure';
+    reason?: 'declined';
+    detailJson?: string | null;
+    /** Present only for `push result`; settlement and the canonical final share one transaction. */
+    structured?: {
+        requestId: string;
+        value?: unknown;
+        declined?: {
+            reason: string;
+            code: string;
+            retryable: boolean;
+        };
+        skipEffects?: boolean;
+    };
+}
+export interface PushResult {
+    /** `<nodeId>/reports/<name>` — the report document's ref. */
+    report: string;
+    reportId: string;
+    deliveredTo: string[];
+}
+export declare class StructuredRequestFinalizationError extends Error {
+    readonly state: string;
+    constructor(state: string);
+}
+export declare class FinalizationError extends Error {
+    readonly code: 'already_finalized' | 'finalization_forbidden' | 'unknown_node';
+    readonly report?: string | undefined;
+    constructor(code: 'already_finalized' | 'finalization_forbidden' | 'unknown_node', report?: string | undefined);
+}
+export declare function push(nodeId: string, opts: PushOpts): Promise<PushResult>;
+export declare function pushUpdate(nodeId: string, body: string, opts?: {
+    from?: string;
+    deliveryTier?: PushDeliveryTier;
+}): Promise<PushResult>;
+export declare function pushUrgent(nodeId: string, body: string, opts?: {
+    from?: string;
+}): Promise<PushResult>;
+export declare function pushFinal(nodeId: string, body: string, opts?: {
+    from?: string;
+    disposition?: InboxDisposition;
+}): Promise<PushResult>;

package/dist/core/feed/feed.js

@@ -0,0 +1,4 @@
+var N=Object.defineProperty;var i=(e,t)=>N(e,"name",{value:t,configurable:!0});import{prepared as p}from"../sqlite-statements.js";import{cancelCronsOnWake as $,getNode as h}from"../canvas/index.js";import{runStructuredRequestEffects as R,settleStructuredRequestIn as k}from"../canvas/structured-requests.js";import{openDb as y,withCanvasWrite as U}from"../canvas/db.js";import{randomUUID as b}from"node:crypto";import{composeNodeOutcomeDocument as q}from"../runtime/outcome-document.js";import{closeNode as A}from"../runtime/close.js";import{put as F}from"../graph/bodies.js";import{writeDocument as L}from"../graph/documents.js";import{publish as C}from"../graph/events.js";import{nodeObject as v}from"../graph/objects.js";import{readerForNode as z}from"../graph/reader.js";import{endMessageSubscriptions as D}from"../graph/watches.js";import{operationIdContext as M}from"../events/operation-id.js";class W extends Error{static{i(this,"StructuredRequestFinalizationError")}state;constructor(t){super(t==="expired"?"structured_request_expired":"structured_request_settled"),this.state=t}}class g extends Error{static{i(this,"FinalizationError")}code;report;constructor(t,r){super(t),this.code=t,this.report=r}}function B(e){const t=i((r,n=2)=>String(r).padStart(n,"0"),"pad");return`${e.getUTCFullYear()}${t(e.getUTCMonth()+1)}${t(e.getUTCDate())}T${t(e.getUTCHours())}${t(e.getUTCMinutes())}${t(e.getUTCSeconds())}${t(e.getUTCMilliseconds(),3)}`}i(B,"compactTs");function O(e,t=80){const r=e.split(`
+`)[0]??"";return r.length>t?`${r.slice(0,t-1)}\u2026`:r}i(O,"firstLine");function H(e){return e.kind==="final"?{event:"report.final"}:e.result!==void 0?{event:"report.result"}:e.kind==="urgent"?{event:"report.update",level:7}:{event:"report.update",level:e.deliveryTier==="deferred"?3:e.deliveryTier==="urgent"?7:5}}i(H,"eventFor");function S(e,t,r){const n=r.from??t,o=`reports/${B(new Date)}-${b().slice(-8)}-${r.kind}`,u=v(e,t),a=v(e,n),{object:s}=L(e,z(e,n,()=>[]),{owner:u,kind:"report",name:o,preview:O(r.body)||r.kind,privacy:"public"},r.body),c=`${t}/${o}`,{event:_,level:m}=H(r);C(e,{event:_,object:u,actor:a,...m===void 0?{}:{level:m},attrs:{},pointer:s.id,messageBody:{kind:r.kind,label:O(r.body),bodyRef:c,...r.disposition===void 0?{}:{disposition:r.disposition}}});const l=p(e,`SELECT d.destination_id FROM deliveries d JOIN messages m ON m.message_id = d.message_id
+    JOIN objects receiver ON receiver.id = d.destination_id
+    WHERE m.body_ref = ? AND receiver.type = 'node' ORDER BY d.destination_id`).all(c).map(w=>w.destination_id);return r.kind==="final"?D(e,u,"final"):r.result?.requestMessageId&&D(e,u,{result:r.result.requestMessageId}),{name:o,ref:c,doc:s,createdAt:s.created_at,deliveredTo:l}}i(S,"writeReport");function j(e,t){const r=y();r.exec("BEGIN IMMEDIATE");try{const n=p(r,"SELECT status, final_report FROM nodes WHERE node_id = ?").get(e);if(n===void 0)throw new g("unknown_node");const o=t.outcome;let u;if(o?.structured!==void 0){const d=k(r,o.structured.requestId,o.structured.declined===void 0?{intended:"completed",result:o.structured.value}:{intended:"declined",declined:o.structured.declined});if(!d.changed||d.row===null||d.row.state!=="completed"&&d.row.state!=="declined")return r.exec("COMMIT"),{written:void 0,...d.row===null?{}:{structured:d.row},structuredRefused:!0};u=d.row}else{const d=r.prepare("SELECT request_id FROM structured_requests WHERE node_id = ? AND state = 'pending'").get(e);if(d!==void 0){const f=k(r,d.request_id,{intended:"failed",failureReason:"finalized"});if(!f.changed||f.row===null||f.row.state!=="failed")return r.exec("COMMIT"),{written:void 0,...f.row===null?{}:{structured:f.row},structuredRefused:!0};u=f.row}}if(n.final_report!==null)throw new g("already_finalized",`${e}/${n.final_report}`);if(n.status!=="active"&&n.status!=="idle"&&n.status!=="done")throw new g("finalization_forbidden");const a=S(r,e,t),s=h(e),c=s?.kind!=="human",_=(s?.outcome_revision??0)+1,m=t.outcome?.kind??"result",l=t.outcome?.reason??"finalized",w=t.outcome?.detailJson??null,E=a.createdAt;if(c){const d=s===null?null:q({node:{...s,status:"done",intent:"done",terminal_reason:l},outcome:{kind:m,reason:l,at:E,revision:_,detailJson:w},finalReport:a.name,...u?.state==="completed"?{structuredResult:u.result}:{}});p(r,"UPDATE nodes SET status = 'done', intent = 'done', terminal_reason = ?, final_report = ?, finalized_at = ?, outcome_kind = ?, outcome_reason = ?, outcome_at = ?, outcome_revision = outcome_revision + 1, outcome_detail_json = ? WHERE node_id = ? AND final_report IS NULL").run(l,a.name,E,m,l,E,w,e),d!==null&&C(r,{event:"outcome",object:v(r,e),actor:null,attrs:{revision:_},messageBody:d})}else p(r,"UPDATE nodes SET status = 'done', intent = 'done', terminal_reason = 'finalized', final_report = ?, finalized_at = ? WHERE node_id = ? AND final_report IS NULL").run(a.name,E,e);return r.exec("COMMIT"),{written:a,...u===void 0?{}:{structured:u}}}catch(n){throw r.exec("ROLLBACK"),n}}i(j,"commitCanonicalFinal");async function x(e,t){if(!e)throw new Error(`push: empty nodeId (kind=${t.kind}) \u2014 a report must belong to a node`);if(t.kind==="final"&&t.deliveryTier!==void 0)throw new Error("push final does not accept a delivery tier");if(t.kind!=="final"&&t.outcome!==void 0)throw new Error("push outcome is final-only");if(t.kind!=="update"&&t.result!==void 0)throw new Error("a one-off result is an update report");if(F(t.body),t.kind==="final"){const n=j(e,t);if(n.structuredRefused===!0)throw n.structured!==void 0&&R(n.structured),new W(n.structured?.state??"failed");n.structured!==void 0&&t.outcome?.structured?.skipEffects!==!0&&R(n.structured);const{written:o}=n;if($(e),h(e)?.run_id===e){const a=p(y(),"SELECT node_id FROM nodes WHERE run_id = ? AND node_id != ? ORDER BY created DESC").all(e,e);for(const s of a){const c=h(s.node_id);c&&c.status!=="done"&&c.status!=="canceled"&&c.status!=="dead"&&A(s.node_id,{preserveEmpty:!0})}}return{report:o.ref,reportId:o.doc.id,deliveredTo:o.deliveredTo}}const r=U(n=>S(n,e,t));return{report:r.ref,reportId:r.doc.id,deliveredTo:r.deliveredTo}}i(x,"pushWithContext");function T(e,t){return M.current()===void 0?M.fresh(()=>x(e,t)):x(e,t)}i(T,"push");async function oe(e,t,r){return T(e,{kind:"update",body:t,...r})}i(oe,"pushUpdate");async function de(e,t,r){return T(e,{kind:"urgent",body:t,...r})}i(de,"pushUrgent");async function ue(e,t,r){return T(e,{kind:"final",body:t,...r})}i(ue,"pushFinal");export{g as FinalizationError,W as StructuredRequestFinalizationError,T as push,ue as pushFinal,oe as pushUpdate,de as pushUrgent};

package/dist/core/feed/inbox-migrate.d.ts

@@ -0,0 +1,11 @@
+export interface InboxMigrationSummary {
+    nodes: number;
+    entries: number;
+    cursors: number;
+    failures: number;
+}
+/** Scan every node dir under the local canvas and migrate legacy inbox state.
+ *  Idempotent; a node that fails migration is reported and skipped so one bad
+ *  dir cannot block daemon boot (its broker stays crash-faulted, same as
+ *  before the migration existed). */
+export declare function migrateLegacyInboxIdentities(): InboxMigrationSummary;

package/dist/core/feed/inbox-migrate.js

@@ -0,0 +1,3 @@
+var h=Object.defineProperty;var d=(r,t)=>h(r,"name",{value:t,configurable:!0});import{existsSync as l,readFileSync as w,readdirSync as x,renameSync as I,rmSync as E,statSync as C,writeFileSync as O}from"node:fs";import{join as F}from"node:path";import{createHash as L}from"node:crypto";import{inboxPath as N,nodesRoot as R}from"../canvas/index.js";import{emitEvent as U}from"../events/emit.js";const S=/^(?!0{32}$)[0-9a-f]{32}$/,_=/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,j=/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z$/;function z(r,t,e,n){return L("sha256").update(`crouter:legacy-inbox:${r}\0${t}\0${e}\0${n}`).digest("hex").slice(0,32)}d(z,"legacyIdentity");function b(r,t,e,n,i){if(i===void 0)return z(r,t,e,n);if(typeof i=="string"){if(S.test(i))return i;if(_.test(i))return i.replaceAll("-","").toLowerCase()}}d(b,"normalize");function p(r,t){const e=`${r}.tmp`;O(e,t,"utf8"),I(e,r)}d(p,"atomicWrite");function A(r){const t=N(r),e=`${t}.cursor`;let n=0,i=[];if(l(t)){const f=w(t,"utf8");if(f!==""){const s=f.split(`
+`);s.at(-1)===""&&s.pop();const g=s.map((a,m)=>{const o=JSON.parse(a),u=b("entry",r,m,a,o.entry_id),y=b("operation",r,m,a,o.operation_id);if(u===void 0||y===void 0)throw new Error(`unmigratable inbox row ${m}: ${String(o.entry_id)}`);const $=u!==o.entry_id||y!==o.operation_id;return $&&(n+=1),o.entry_id=u,o.operation_id=y,{line:$?JSON.stringify(o):a,ts:o.ts,entry_id:u}});i=g,n>0&&p(t,g.map(a=>`${a.line}
+`).join(""))}}if(!l(e))return{entries:n,cursor:!1};const c=w(e,"utf8").trim();if(c===""||S.test(c))return{entries:n,cursor:!1};if(_.test(c))return p(e,c.replaceAll("-","").toLowerCase()),{entries:n,cursor:!0};if(j.test(c)){let f=-1;for(let s=0;s<i.length;s+=1)i[s].ts<=c&&(f=s);return f<0?E(e):p(e,i[f].entry_id),{entries:n,cursor:!0}}throw new Error(`unrecognized inbox cursor: ${c.slice(0,64)}`)}d(A,"migrateNode");function X(){const r={nodes:0,entries:0,cursors:0,failures:0},t=R();if(!l(t))return r;for(const e of x(t))try{if(!C(F(t,e)).isDirectory())continue;const{entries:n,cursor:i}=A(e);(n>0||i)&&(r.nodes+=1,r.entries+=n,i&&(r.cursors+=1))}catch(n){r.failures+=1,U({level:"warn",event:"inbox.migrate.node_failed",node_id:e,error:n})}return r}d(X,"migrateLegacyInboxIdentities");export{X as migrateLegacyInboxIdentities};

package/dist/core/feed/inbox.d.ts

@@ -0,0 +1,34 @@
+import type { OperationId } from '../events/types.js';
+import type { ClaimedNodeMail } from '../canvas/deliveries.js';
+export type InboxTier = 'critical' | 'urgent' | 'normal' | 'deferred';
+export type InboxKind = 'update' | 'urgent' | 'final' | 'message' | 'completed';
+export type InboxDisposition = 'human-answer' | 'human-canceled';
+export type InboxEntryId = string & {
+    readonly __inboxEntryId: unique symbol;
+};
+/** The rendering projection of one immutable SQL message and its delivery. */
+export interface InboxEntry {
+    entry_id: InboxEntryId;
+    operation_id: OperationId;
+    ts: string;
+    from: string | null;
+    from_name?: string;
+    tier: InboxTier;
+    kind: InboxKind;
+    ref?: string;
+    label: string;
+    data?: Record<string, unknown>;
+    disposition?: InboxDisposition;
+}
+/** Project the immutable message body and destination-specific urgency into the canonical inbox rendering shape. */
+export declare function nodeMailEntry(delivery: ClaimedNodeMail): InboxEntry;
+/** The newest head body of the report document a message points at, or null when the entry
+ *  is not a report or the document is gone. */
+export declare function reportDocumentBody(objectId: string): string | null;
+export interface InboxDelivery {
+    kind: 'human' | 'card';
+    text: string;
+    entries: readonly InboxEntry[];
+}
+/** Split delivered entries into verbatim human messages and sender-grouped inbox cards. */
+export declare function coalesce(entries: readonly InboxEntry[]): readonly InboxDelivery[];

package/dist/core/feed/inbox.js

@@ -0,0 +1 @@
+var c=Object.defineProperty;var r=(o,e)=>c(o,"name",{value:e,configurable:!0});import{prepared as u}from"../sqlite-statements.js";import{openDb as m}from"../canvas/db.js";import{heads as p}from"../graph/documents.js";import{getById as l}from"../graph/objects.js";import{bodyOf as h}from"../graph/bodies.js";import{validateOperationId as y}from"../events/operation-id.js";import{formatInboxCard as b}from"../../shared/generated-context.js";import{inlineBody as I,renderEntryBody as g,reportRefNodeId as E}from"../../shared/inbox-entry-body.js";const _=/^(?!0{32}$)[0-9a-f]{32}$/;function x(o){if(typeof o!="string"||!_.test(o))throw new TypeError("entry_id must be 32 lowercase non-zero hexadecimal characters");return o}r(x,"validateInboxEntryId");function J(o){const e=o.message;return{entry_id:x(e.messageId),operation_id:y(e.operationId),ts:e.createdAt,from:e.senderNodeId,...e.senderName===null?{}:{from_name:e.senderName},tier:o.urgency,kind:e.kind,...e.bodyRef===null?{}:{ref:e.bodyRef},label:e.label,...e.bodyJson===null?{}:{data:e.bodyJson},...e.disposition===null?{}:{disposition:e.disposition}}}r(J,"nodeMailEntry");function k(o){const e=m(),n=l(e,o);if(n===null||n.type!=="document"||n.deleted_at!==null)return null;const s=p(e,n)[0];if(s===void 0)return null;const d=u(e,"SELECT source_path FROM documents WHERE object = ?").get(n.rowid);return h(s.body_hash,d?.source_path??null)}r(k,"reportDocumentBody");function B(o){const e=o.data?.push?.object?.id,n=E(o.ref)!==void 0&&e!==void 0?k(e):null;return g(o,n)}r(B,"entryBody");function N(o){return{kind:o.kind,body:B(o),...o.ref===void 0?{}:{ref:o.ref},...o.disposition===void 0?{}:{disposition:o.disposition}}}r(N,"cardEntry");function $(o){if(o.length===0)return[];const e=new Map;for(const t of o){const i=t.from??"system";e.has(i)||e.set(i,[]),e.get(i).push(t)}const n=[],s=[];let d=-1;for(const[t,i]of e){if(t==="human"){for(const f of i){const a=I(f);n.push({kind:"human",text:a===""?f.label:a,entries:[f]})}continue}d<0&&(d=n.length,n.push({kind:"card",text:"",entries:[]})),s.push({id:t,entries:i.map(N)})}return d>=0&&(n[d]={kind:"card",text:b(s),entries:o.filter(t=>(t.from??"system")!=="human")}),n}r($,"coalesce");export{$ as coalesce,J as nodeMailEntry,k as reportDocumentBody};

package/dist/core/feed/messages.d.ts

@@ -0,0 +1,83 @@
+import type { DatabaseSync } from 'node:sqlite';
+import { openDb } from '../canvas/db.js';
+import type { OperationId } from '../events/types.js';
+import type { Level, ListenDelivery } from '../graph/types.js';
+import { type InboxDisposition, type InboxKind, type InboxTier } from './inbox.js';
+export type { InboxDisposition, InboxKind, InboxTier } from './inbox.js';
+export interface NodeMailInput {
+    kind: InboxKind;
+    label: string;
+    senderNodeId?: string | null;
+    senderName?: string | null;
+    bodyRef?: string | null;
+    bodyJson?: unknown;
+    disposition?: InboxDisposition | null;
+    urgency: InboxTier;
+    wake: 0 | 1;
+    operationId?: string;
+    /** Caller-chosen message id, so a request can know its id before the insert. */
+    messageId?: string;
+    /** Optional caller-owned obligation identity, used by cron settlement replay. */
+    idempotencyKey?: string;
+    /** Runs with the mail insert, before the transaction commits. */
+    withinEnqueue?: (db: DatabaseSync, messageId: string) => void;
+}
+export interface EnqueuedNodeMail {
+    messageId: string;
+    deliveryId: string;
+    urgency: InboxTier;
+    createdAt: string;
+}
+export declare function newId(): string;
+/** A terminal-lifecycle destination's normal or deferred mail is raised to urgent. */
+export declare function effectiveTier(nodeId: string, urgency: InboxTier): InboxTier;
+export declare function insertMessage(db: ReturnType<typeof openDb>, input: {
+    messageId?: string;
+    operationId: OperationId;
+    createdAt: string;
+    senderNodeId: string | null;
+    senderName: string | null;
+    kind: InboxKind;
+    label: string;
+    bodyRef: string | null;
+    bodyJson: unknown | undefined;
+    disposition: InboxDisposition | null;
+    event?: {
+        event: string;
+        objectId: string;
+        level: Level;
+        actorId: string | null;
+    };
+    causeMessageId?: string | null;
+    depth?: number;
+}): string;
+/** The message's creation time, operation id and body — an oversized inline body is clipped
+ *  into `destinationNodeId`'s messages dir and referenced; with no destination it stays inline. */
+export declare function finalizeNodeMail(input: Omit<NodeMailInput, 'wake'>, destinationNodeId: string | null): {
+    createdAt: string;
+    operationId: OperationId;
+    bodyRef: string | null;
+    bodyJson: unknown | undefined;
+};
+/** Insert one immutable message and one node-inbox obligation into the caller's write transaction. */
+export declare function enqueueNodeMail(destinationNodeId: string, input: NodeMailInput): EnqueuedNodeMail;
+/** Contract §1: a listening delivery maps 1:1 onto an inbox tier; only `next-turn` does not wake. */
+export declare function listenDeliveryTier(delivery: ListenDelivery): {
+    urgency: InboxTier;
+    wake: 0 | 1;
+};
+/** Queue one runtime notice to a node's inbox inside the caller's write transaction (no sender). */
+export declare function queueNodeNotice(db: DatabaseSync, nodeId: string, notice: {
+    body: string;
+    label?: string;
+    tier: InboxTier;
+    wake: 0 | 1;
+}): EnqueuedNodeMail;
+/** Retract an obligation without fabricating a terminal receipt. */
+export declare function cancelDelivery(deliveryId: string, now?: number): boolean;
+export declare function cancelPendingNodeMail(nodeId: string, select?: {
+    senderNodeId?: string | null;
+    kind?: InboxKind;
+}): string[];
+/** Enqueue the one notice only if the same live controller wait is still dead. */
+export declare function enqueueControllerDeathNotice(nodeId: string, controllerId: string): EnqueuedNodeMail | null;

package/dist/core/feed/messages.js

@@ -0,0 +1,8 @@
+var w=Object.defineProperty;var a=(r,e)=>w(r,"name",{value:e,configurable:!0});import{prepared as l}from"../sqlite-statements.js";import{existsSync as E,mkdirSync as N,renameSync as I,writeFileSync as v}from"node:fs";import{randomBytes as b,randomUUID as k}from"node:crypto";import{join as S}from"node:path";import{cancelCronsOnWake as m}from"../canvas/crons.js";import{withCanvasWrite as u}from"../canvas/db.js";import{getRow as h}from"../canvas/canvas.js";import{messagesDir as R}from"../canvas/paths.js";import{syncDirectory as A,syncFile as D}from"../fs-utils.js";import{settleDeadControllerWait as T,settleMatchingControllerWait as O}from"../canvas/waits.js";import{generateOperationId as x,operationIdContext as L,validateOperationId as J}from"../events/operation-id.js";import{clipBody as C}from"../../shared/inbox-entry-body.js";function y(){let r;do r=b(16).toString("hex");while(r==="00000000000000000000000000000000");return r}a(y,"newId");function M(r,e){const n=JSON.stringify(r);if(n===void 0)throw new TypeError(`${e} must be JSON-serializable`);return n}a(M,"stringify");function W(r,e){return e!=="normal"&&e!=="deferred"?e:h(r)?.lifecycle==="terminal"?"urgent":e}a(W,"effectiveTier");function q(r,e,n){const t=R(r);E(t)||N(t,{recursive:!0});const d=e.replace(/[^0-9]/g,""),o=S(t,`${d}-${k().slice(0,6)}.md`),i=`${o}.tmp`;return v(i,n,"utf8"),D(i),I(i,o),A(t),o}a(q,"writeMessageBody");function U(r){if(typeof r!="object"||r===null)return"";const e=r.body;return typeof e=="string"?e.trim():""}a(U,"inlineBody");function f(r,e){const n=e.messageId??y(),t=Number(l(r,"UPDATE message_sequence SET seq = seq + 1 WHERE id = 1 RETURNING seq").get().seq);return l(r,`INSERT INTO messages
+       (message_id, seq, operation_id, created_at, sender_node_id, sender_name, kind, label, body_ref, body_json, disposition,
+        event, object_id, level, actor_id, cause_message_id, depth)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(n,t,e.operationId,e.createdAt,e.senderNodeId,e.senderName,e.kind,e.label,e.bodyRef,e.bodyJson===void 0?null:M(e.bodyJson,"message body"),e.disposition,e.event?.event??null,e.event?.objectId??null,e.event?.level??null,e.event?.actorId??null,e.causeMessageId??null,e.depth??0),n}a(f,"insertMessage");function g(r,e,n,t,d,o,i){const s=y();return l(r,`INSERT INTO deliveries
+       (delivery_id, message_id, destination_id, urgency, wake, state, idempotency_key, created_at, updated_at)
+     VALUES (?, ?, ?, ?, ?, 'pending', ?, ?, ?)`).run(s,e,n,t,d,i??null,o,o),s}a(g,"insertNodeDelivery");function _(r,e){const n=new Date().toISOString(),t=r.operationId===void 0?L.current()??x():J(r.operationId);let d=r.bodyRef??null,o=r.bodyJson;if(d===null&&e!==null&&r.senderNodeId!=="human"){const i=U(o),s=C(i);s.clipped&&(d=q(e,n,i),o={...o,body:s.text})}return{createdAt:n,operationId:t,bodyRef:d,bodyJson:o}}a(_,"finalizeNodeMail");function j(r,e){const n=_(e,r);return u(t=>{const d=l(t,"SELECT run_id FROM nodes WHERE node_id = ?").get(r);if(d?.run_id&&l(t,"SELECT deleting_at FROM nodes WHERE node_id = ?").get(d.run_id)?.deleting_at)throw new Error("run is deleting");if(e.idempotencyKey!==void 0){const c=l(t,`SELECT d.delivery_id, d.message_id, d.urgency, m.created_at
+        FROM deliveries d JOIN messages m ON m.message_id = d.message_id WHERE d.idempotency_key = ?`).get(e.idempotencyKey);if(c!==void 0)return{messageId:c.message_id,deliveryId:c.delivery_id,urgency:c.urgency,createdAt:c.created_at}}const o=Date.now(),i=W(r,e.urgency),s=f(t,{messageId:e.messageId,operationId:n.operationId,createdAt:n.createdAt,senderNodeId:e.senderNodeId??null,senderName:e.senderName??null,kind:e.kind,label:e.label,bodyRef:n.bodyRef,bodyJson:n.bodyJson,disposition:e.disposition??null}),p=g(t,s,r,i,e.wake,o,e.idempotencyKey);return O(r,e.senderNodeId??null,o,t),e.withinEnqueue?.(t,s),e.wake===1&&i!=="deferred"&&m(r),{messageId:s,deliveryId:p,urgency:i,createdAt:n.createdAt}})}a(j,"enqueueNodeMail");function ee(r){switch(r){case"interrupt":return{urgency:"critical",wake:1};case"steer":return{urgency:"urgent",wake:1};case"after-turn":return{urgency:"normal",wake:1};case"next-turn":return{urgency:"deferred",wake:0}}}a(ee,"listenDeliveryTier");function re(r,e,n){const t={kind:"update",label:n.label??"notice",bodyJson:{body:n.body},urgency:n.tier,wake:n.wake},d=_(t,e),o=Date.now(),i=f(r,{operationId:d.operationId,createdAt:d.createdAt,senderNodeId:null,senderName:null,kind:t.kind,label:t.label,bodyRef:d.bodyRef,bodyJson:d.bodyJson,disposition:null}),s=g(r,i,e,n.tier,n.wake,o);return n.wake===1&&n.tier!=="deferred"&&m(e),{messageId:i,deliveryId:s,urgency:n.tier,createdAt:d.createdAt}}a(re,"queueNodeNotice");function ne(r,e=Date.now()){return u(n=>Number(l(n,"UPDATE deliveries SET canceled_at = ?, updated_at = ? WHERE delivery_id = ? AND canceled_at IS NULL").run(e,e,r).changes)===1)}a(ne,"cancelDelivery");function te(r,e={}){return u(n=>{const t=["d.destination_id = ?","d.canceled_at IS NULL","d.state IN ('pending', 'handed_off')"],d=[r];e.senderNodeId!==void 0&&(t.push("m.sender_node_id IS ?"),d.push(e.senderNodeId)),e.kind!==void 0&&(t.push("m.kind = ?"),d.push(e.kind));const o=n.prepare(`SELECT d.delivery_id FROM deliveries d JOIN messages m ON m.message_id = d.message_id WHERE ${t.join(" AND ")}`).all(...d);if(o.length===0)return[];const i=Date.now();return n.prepare(`UPDATE deliveries SET canceled_at = ?, updated_at = ? WHERE delivery_id IN (${o.map(()=>"?").join(",")})`).run(i,i,...o.map(s=>s.delivery_id)),o.map(s=>s.delivery_id)})}a(te,"cancelPendingNodeMail");function de(r,e){return u(n=>{const t=Date.now(),d=l(n,`SELECT target.status AS controller_status FROM waits w LEFT JOIN nodes target ON target.node_id = w.target_id
+        WHERE w.node_id = ? AND w.kind = 'controller' AND w.target_id = ? AND w.satisfied_at IS NULL`).get(r,e);if(d===void 0||d.controller_status==="active"||d.controller_status==="idle")return null;const o=j(r,{kind:"urgent",label:"declared controller is no longer live",bodyJson:{body:`Controller ${e} is no longer live; the declared message wait was cleared.`},urgency:"urgent",wake:1});if(!T(r,e,t,n))throw new Error(`controller wait changed while notifying ${r}`);return o})}a(de,"enqueueControllerDeathNotice");export{ne as cancelDelivery,te as cancelPendingNodeMail,W as effectiveTier,de as enqueueControllerDeathNotice,j as enqueueNodeMail,_ as finalizeNodeMail,f as insertMessage,ee as listenDeliveryTier,y as newId,re as queueNodeNotice};

package/dist/core/feed/reports.d.ts

@@ -0,0 +1,10 @@
+/** Whether `nodeId` owns any live report document — proof it already did work. */
+export declare function hasReportDocuments(nodeId: string): boolean;
+/** `<nodeId>/<name>` of `nodeId`'s newest live report document — the name
+ *  `crtr canvas read` takes — or null when it pushed none. */
+export declare function newestReportName(nodeId: string): string | null;
+/** Body of `nodeId`'s newest live report document, trimmed; '' when it pushed none. */
+export declare function newestReportBody(nodeId: string): string;
+/** Body of the report document a push's `<nodeId>/reports/<name>` ref names;
+ *  null when the ref is not that shape or the document is gone. */
+export declare function reportBodyByName(ref: string): string | null;

package/dist/core/feed/reports.js

@@ -0,0 +1,2 @@
+var l=Object.defineProperty;var r=(t,e)=>l(t,"name",{value:e,configurable:!0});import{prepared as u}from"../sqlite-statements.js";import{openDb as d}from"../canvas/db.js";import{get as a}from"../graph/bodies.js";import{heads as p}from"../graph/documents.js";import{getById as c}from"../graph/objects.js";function R(t){const e=d(),n=c(e,t);return n===null||n.type!=="node"?!1:u(e,"SELECT 1 FROM objects WHERE owner = ? AND type = 'document' AND kind = 'report' AND deleted_at IS NULL LIMIT 1").get(n.rowid)!==void 0}r(R,"hasReportDocuments");function f(t){const e=d(),n=c(e,t);if(!(n===null||n.type!=="node"))return u(e,`SELECT * FROM objects WHERE owner = ? AND type = 'document' AND kind = 'report' AND deleted_at IS NULL
+    ORDER BY created_at DESC, name DESC LIMIT 1`).get(n.rowid)}r(f,"newestReport");function L(t){const e=f(t);return e===void 0?null:`${t}/${e.name}`}r(L,"newestReportName");function b(t){const e=d(),n=f(t);if(n===void 0)return"";const o=p(e,n)[0];if(o===void 0)return"";try{return a(o.body_hash).trim()}catch{return""}}r(b,"newestReportBody");function w(t){const e=t.indexOf("/");if(e<=0||!t.startsWith("reports/",e+1))return null;const n=d(),o=c(n,t.slice(0,e));if(o===null||o.type!=="node")return null;const i=u(n,"SELECT * FROM objects WHERE owner = ? AND type = 'document' AND name = ? AND deleted_at IS NULL").get(o.rowid,t.slice(e+1)),s=i===void 0?void 0:p(n,i)[0];if(s===void 0)return null;try{return a(s.body_hash)}catch{return null}}r(w,"reportBodyByName");export{R as hasReportDocuments,b as newestReportBody,L as newestReportName,w as reportBodyByName};

package/dist/core/frontmatter.d.ts

@@ -0,0 +1,8 @@
+export interface ParsedFrontmatterGeneric {
+    /** Raw, uncoerced key/value record from the YAML block (null when absent). */
+    data: Record<string, unknown> | null;
+    body: string;
+    raw: string;
+}
+/** Parse a frontmatter block as a raw key/value record. */
+export declare function parseFrontmatterGeneric(source: string): ParsedFrontmatterGeneric;

package/dist/core/frontmatter.js

@@ -0,0 +1 @@
+var e=Object.defineProperty;var t=(r,n)=>e(r,"name",{value:n,configurable:!0});import{parse as c}from"yaml";const i=/^---\s*\r?\n([\s\S]*?)\r?\n---\s*\r?\n?/;function f(r){const n=r.match(i);if(!n)return{data:null,body:r,raw:""};const o=n[1],a=r.slice(n[0].length);return{data:l(o),body:a,raw:o}}t(f,"parseFrontmatterGeneric");function l(r){return s(c(r))}t(l,"parseYamlBlock");function s(r){return r!==null&&typeof r=="object"&&!Array.isArray(r)?r:{}}t(s,"normalizeToRecord");export{f as parseFrontmatterGeneric};

package/dist/core/fs-utils.d.ts

@@ -0,0 +1,44 @@
+/** `realpathSync`, tolerant of a path that doesn't exist or can't be resolved. */
+export declare function realpathOrSelf(p: string): string;
+/** Expand a leading `~` against `homeDir` (pi's own convention). Other forms
+ *  — absolute, relative, `~user` — pass through as pi leaves them. */
+export declare function expandTilde(p: string, homeDir?: string): string;
+/** Collapse the home prefix to `~` so a path reads short. The inverse of
+ *  `expandTilde`, and the ONE collapse every surface prints paths through. */
+export declare function tildify(p: string, homeDir?: string): string;
+export declare function ensureDir(dir: string): void;
+export declare function writeJson(path: string, data: unknown): void;
+export interface AtomicWriteOptions {
+    /** Force this mode regardless of any existing file's mode. Omitted: preserve the existing file's mode, or default a new file to `0o600`. */
+    mode?: number;
+    /** Require the parent to exist, rather than recreate a removed project root. */
+    createParent?: boolean;
+}
+export declare function atomicWriteJson(path: string, data: unknown, opts?: AtomicWriteOptions): void;
+/** Force a file's written bytes to stable storage. */
+export declare function syncFile(path: string): void;
+/** Force a directory's entry changes to stable storage. */
+export declare function syncDirectory(path: string): void;
+/** Replace one file's contents in a single rename, so a concurrent reader — the
+ *  tmux inbox watcher, or crtrd serving a ticket read — sees either the old
+ *  bytes or the new ones and never a truncated file mid-write. */
+export declare function atomicWriteText(path: string, content: string | Uint8Array, opts?: AtomicWriteOptions): void;
+export declare function readJson<T = unknown>(path: string): T;
+export declare function readJsonIfExists<T = unknown>(path: string): T | null;
+/** Missing or corrupt reads as absent, so a crash artifact never throws. */
+export declare function readJsonOrNull<T = unknown>(path: string): T | null;
+export declare function readTextIfExists(path: string): string | null;
+export declare function readText(path: string): string;
+export declare function writeText(path: string, content: string): void;
+export declare function isDir(path: string): boolean;
+export declare function isSymlink(path: string): boolean;
+export declare function pathExists(path: string): boolean;
+export declare function listDirs(path: string): string[];
+export declare function listEntries(path: string): string[];
+export declare function removePath(path: string): void;
+export declare function linkOrCopy(target: string, linkPath: string, opts?: {
+    noSymlink?: boolean;
+}): 'symlink' | 'copy';
+export declare function readSymlinkTarget(path: string): string | null;
+export declare function walkFiles(root: string, predicate?: (name: string) => boolean, skipDir?: (name: string) => boolean): string[];
+export declare function nowIso(): string;

package/dist/core/fs-utils.js

@@ -0,0 +1,3 @@
+var v=Object.defineProperty;var n=(r,t)=>v(r,"name",{value:t,configurable:!0});import{existsSync as c,lstatSync as D,mkdirSync as E,readdirSync as y,readFileSync as f,rmSync as S,statSync as d,symlinkSync as W,writeFileSync as a,cpSync as w,readlinkSync as g,renameSync as I,chmodSync as $,realpathSync as b,closeSync as J,fsyncSync as O,openSync as T}from"node:fs";import{dirname as s,join as h,relative as L,sep as j}from"node:path";import{homedir as k,platform as F}from"node:os";function N(r){try{return b(r)}catch{return r}}n(N,"realpathOrSelf");function Q(r,t=k()){return r==="~"?t:r.startsWith("~/")||F()==="win32"&&r.startsWith("~\\")?h(t,r.slice(2)):r}n(Q,"expandTilde");function R(r,t=k()){return r===t?"~":r.startsWith(t+j)?"~"+r.slice(t.length):r}n(R,"tildify");function l(r){E(r,{recursive:!0})}n(l,"ensureDir");function U(r,t){l(s(r)),a(r,JSON.stringify(t,null,2)+`
+`,"utf8")}n(U,"writeJson");function V(r,t,i){C(r,JSON.stringify(t,null,2)+`
+`,i)}n(V,"atomicWriteJson");function X(r){const t=T(r,"r");try{O(t)}finally{J(t)}}n(X,"syncFile");function Y(r){const t=T(r,"r");try{O(t)}finally{J(t)}}n(Y,"syncDirectory");function C(r,t,i){i?.createParent!==!1&&l(s(r));const e=`${r}.${process.pid}.${Date.now()}.${Math.random().toString(16).slice(2)}.tmp`,o=i?.mode??(c(r)?d(r).mode&511:384);try{a(e,t,{mode:o}),$(e,o),I(e,r)}finally{c(e)&&S(e,{force:!0})}}n(C,"atomicWriteText");function M(r){return JSON.parse(f(r,"utf8"))}n(M,"readJson");function Z(r){try{return M(r)}catch(t){if(t.code==="ENOENT")return null;throw t}}n(Z,"readJsonIfExists");function _(r){try{return JSON.parse(f(r,"utf8"))}catch{return null}}n(_,"readJsonOrNull");function P(r){return c(r)?f(r,"utf8"):null}n(P,"readTextIfExists");function rr(r){return f(r,"utf8")}n(rr,"readText");function tr(r,t){l(s(r)),a(r,t,"utf8")}n(tr,"writeText");function q(r){try{return d(r).isDirectory()}catch{return!1}}n(q,"isDir");function z(r){try{return D(r).isSymbolicLink()}catch{return!1}}n(z,"isSymlink");function nr(r){return c(r)}n(nr,"pathExists");function er(r){return c(r)?y(r,{withFileTypes:!0}).filter(t=>t.isDirectory()||t.isSymbolicLink()).map(t=>t.name):[]}n(er,"listDirs");function ir(r){return c(r)?y(r):[]}n(ir,"listEntries");function A(r){!c(r)&&!z(r)||S(r,{recursive:!0,force:!0})}n(A,"removePath");function or(r,t,i={}){l(s(t)),A(t);const e=F()==="win32";if(!i.noSymlink&&!e){const o=L(N(s(t)),N(r));try{return W(o,t,q(r)?"dir":"file"),"symlink"}catch{return w(r,t,{recursive:!0}),"copy"}}return w(r,t,{recursive:!0}),"copy"}n(or,"linkOrCopy");function cr(r){try{return g(r)}catch{return null}}n(cr,"readSymlinkTarget");function ur(r,t=()=>!0,i=()=>!1){const e=[];if(!c(r))return e;const o=[r];for(;o.length;){const x=o.pop();let p;try{p=y(x,{withFileTypes:!0})}catch{continue}for(const u of p){const m=h(x,u.name);u.isDirectory()?i(u.name)||o.push(m):u.isFile()&&t(u.name)&&e.push(m)}}return e}n(ur,"walkFiles");function sr(){return new Date().toISOString()}n(sr,"nowIso");export{V as atomicWriteJson,C as atomicWriteText,l as ensureDir,Q as expandTilde,q as isDir,z as isSymlink,or as linkOrCopy,er as listDirs,ir as listEntries,sr as nowIso,nr as pathExists,M as readJson,Z as readJsonIfExists,_ as readJsonOrNull,cr as readSymlinkTarget,rr as readText,P as readTextIfExists,N as realpathOrSelf,A as removePath,Y as syncDirectory,X as syncFile,R as tildify,ur as walkFiles,U as writeJson,tr as writeText};

package/dist/core/git.d.ts

@@ -0,0 +1,28 @@
+export interface GitResult {
+    status: number;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
+    /** The child did not exit with a numeric status (for example, spawn failure or timeout). */
+    executionFailed?: true;
+    processError?: string;
+}
+export interface GitSyncOptions {
+    timeoutMs?: number;
+}
+export declare function gitSync(args: string[], cwd?: string, input?: string, options?: GitSyncOptions): GitResult;
+export interface GitAsyncOptions {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}
+export declare function gitAsync(args: string[], cwd?: string, input?: string, options?: GitAsyncOptions): Promise<GitResult>;
+export declare function clone(url: string, dest: string, opts?: {
+    ref?: string;
+    depth?: number;
+}): GitResult;
+export declare function fetch(cwd: string, ref?: string): GitResult;
+export declare function lsRemote(url: string): GitResult;
+export declare function currentSha(cwd: string): string | null;
+export declare function remoteSha(cwd: string, ref: string): string | null;
+export declare function isGitRepo(cwd: string): boolean;
+export declare function deriveNameFromUrl(url: string): string;

package/dist/core/git.js

@@ -0,0 +1,2 @@
+var h=Object.defineProperty;var o=(t,e)=>h(t,"name",{value:e,configurable:!0});import{spawn as x,spawnSync as S}from"node:child_process";import{network as v}from"./errors.js";function g(t=process.env){return{...t,GIT_OPTIONAL_LOCKS:"0"}}o(g,"gitEnv");function d(t,e,r,i={}){const n=S("git",t,{cwd:e,encoding:"utf8",input:r,env:g(),timeout:i.timeoutMs}),u=typeof n.status=="number"?n.status:1,f=typeof n.status=="number",a=typeof n.stdout=="string"?n.stdout:"",m=typeof n.stderr=="string"?n.stderr:"",c=n.error===void 0?void 0:String(n.error),p=n.error?.code==="ETIMEDOUT";return{status:u,stdout:a,stderr:m,...f?{}:{executionFailed:!0},...c===void 0?{}:{processError:c},...p?{timedOut:!0}:{}}}o(d,"gitSync");async function w(t,e,r,i={}){return new Promise(n=>{const u=x("git",t,{cwd:e,env:g(i.env)});r===void 0?u.stdin.end():u.stdin.end(r);let f="",a="",m=!1,c=!1;const p=i.timeoutMs===void 0?void 0:setTimeout(()=>{m=!0,u.kill("SIGTERM")},i.timeoutMs),l=o(s=>{c||(c=!0,p!==void 0&&clearTimeout(p),n(s))},"settle");u.stdout.on("data",s=>f+=s.toString()),u.stderr.on("data",s=>a+=s.toString()),u.on("close",s=>{l({status:typeof s=="number"?s:1,stdout:f,stderr:a,...m?{timedOut:!0,executionFailed:!0}:{}})}),u.on("error",s=>l({status:1,stdout:"",stderr:String(s),executionFailed:!0,processError:String(s)}))})}o(w,"gitAsync");function M(t,e,r={}){const i=["clone"];r.depth&&i.push("--depth",String(r.depth)),r.ref&&i.push("--branch",r.ref),i.push(t,e);const n=d(i);if(n.status!==0)throw v(`git clone failed: ${t}
+${n.stderr.trim()}`);return n}o(M,"clone");function $(t,e){const r=["fetch","origin"];return e&&r.push(e),d(r,t)}o($,"fetch");function b(t){return d(["ls-remote",t])}o(b,"lsRemote");function F(t){const e=d(["rev-parse","HEAD"],t);return e.status!==0?null:e.stdout.trim()}o(F,"currentSha");function I(t,e){const r=d(["rev-parse",`origin/${e}`],t);return r.status!==0?null:r.stdout.trim()}o(I,"remoteSha");function k(t){const e=d(["rev-parse","--is-inside-work-tree"],t);return e.status===0&&e.stdout.trim()==="true"}o(k,"isGitRepo");function A(t){const r=t.replace(/\.git\/?$/,"").replace(/\/$/,"").split("/").pop();return r||t}o(A,"deriveNameFromUrl");export{M as clone,F as currentSha,A as deriveNameFromUrl,$ as fetch,w as gitAsync,d as gitSync,k as isGitRepo,b as lsRemote,I as remoteSha};

package/dist/core/grants/local.d.ts

@@ -0,0 +1,4 @@
+/** The unjoined runtime's one grant; nodes created before join reference it by id. */
+export declare const LOCAL_TERMINAL_GRANT_ID = "local:terminal";
+/** An unjoined local runtime has exactly one grant, owned by its terminal app. */
+export declare function installLocalTerminalGrant(): void;

package/dist/core/grants/local.js

@@ -0,0 +1 @@
+var l=Object.defineProperty;var r=(e,a)=>l(e,"name",{value:a,configurable:!0});import{replaceGrants as n}from"./mirror.js";const t=["crtr:llm","crtr:act","crtr:schedule","crtr:memory:rw:user","crtr:memory:manage:user","crtr:files:rw:user:."].map(e=>({scope:e,mode:"always"})),s="local:terminal";function p(){const e=new Date().toISOString();n([{id:s,runtime:"runtime:local",sub:"user:local",grantee:"app:terminal",rev:1,scopes:t,resolved_scopes:t,spend_cap:null,expires_at:null,status:"active",revoked_at:null,approved_at:e,payer:"user",dependencies:{},synced_at:e}],e,"local")}r(p,"installLocalTerminalGrant");export{s as LOCAL_TERMINAL_GRANT_ID,p as installLocalTerminalGrant};