@north-light/cli 0.0.0 → 0.3.413

package/dist/core/providers/call.d.ts

@@ -0,0 +1,62 @@
+import type { ManifestHttpLeaf, ManifestBranch, ManifestRootEntry } from '../../api/plugin-manifest-schema.js';
+import type { ValidatedCommandManifest } from '../../api/command-manifest/manifest.js';
+import type { ProviderCaller, ProviderCallInput, ProviderRequest } from '../../daemon/api/handlers/providers.js';
+import { ProviderError } from './errors.js';
+/** A canonical command path is relative to the provider, never provider-prefixed. */
+export interface ProviderLeaf {
+    tool: string;
+    leaf: ManifestHttpLeaf;
+}
+export declare function providerLeaves(commands: ValidatedCommandManifest, provider: string): ProviderLeaf[];
+export type ProviderHelpLeaf = Pick<ManifestHttpLeaf, 'kind' | 'name' | 'description' | 'whenToUse' | 'tier' | 'summary' | 'params' | 'output' | 'effects' | 'group'>;
+export interface ProviderHelpBranch extends Pick<ManifestBranch<ManifestHttpLeaf>, 'kind' | 'name' | 'description' | 'whenToUse' | 'tier' | 'summary' | 'model'> {
+    rootEntry?: ManifestRootEntry;
+    children: Array<ProviderHelpBranch | ProviderHelpLeaf>;
+}
+export interface ProviderToolDescription {
+    provider: string;
+    status: 'available';
+    major: number;
+    display_name: string;
+    groups: Array<{
+        group: string;
+        leaves: Array<{
+            tool: string;
+            description: string;
+            summary: string;
+            params: ManifestHttpLeaf['params'];
+            output: ManifestHttpLeaf['output'];
+        }>;
+    }>;
+    /** Help-only, caller-filtered tree. Never contains REST mappings, endpoints, credentials, or executable paths. */
+    commands: ProviderHelpBranch[];
+}
+export interface UnavailableProviderToolDescription {
+    provider: string;
+    display_name: string;
+    status: 'installing' | 'install_failed';
+    error?: string;
+    groups: [];
+    commands: [];
+}
+/** R8's broker help filter consumes groups[].leaves[].tool. */
+export declare function providerTools(caller: ProviderCaller, id: string): Promise<ProviderToolDescription>;
+export interface ProviderCallResult {
+    status: number;
+    body: unknown;
+}
+/** A single response seam: R7 reads Crtr-Receipt and writes the audit row here. */
+export interface ProviderResponseContext {
+    provider: string;
+    tool: string;
+    request_id: string;
+    run_id: string | null;
+    sub: string;
+    grantee: string;
+    jti: string;
+    status: number;
+    headers: Record<string, string | string[] | undefined>;
+}
+export declare function onProviderResponse(context: ProviderResponseContext): string | undefined;
+export declare function mapProviderResponse(status: number, body: unknown, headers: Record<string, string | string[] | undefined>, approved?: boolean): ProviderError;
+export declare function callProvider(caller: ProviderCaller, input: ProviderCallInput, request: ProviderRequest): Promise<ProviderCallResult>;

package/dist/core/providers/call.js

@@ -0,0 +1 @@
+var K=Object.defineProperty;var c=(e,r)=>K(e,"name",{value:r,configurable:!0});import{validateDeclaredResult as Q}from"../../api/command-manifest/result.js";import{callerAllows as T,requireGroup as V}from"../../daemon/api/handlers/providers.js";import{terminalGrant as W}from"../grants/mirror.js";import{listInstalledPlugins as X}from"../resolver.js";import{ProviderError as u}from"./errors.js";import{ensureProviderBundle as Y,refreshProviderBundle as Z,resolveProviderBundle as S,unavailableProviderError as ee}from"./bundles.js";import{prepareFileCall as re,resignForRetry as U,resolveFileResult as oe}from"./files.js";import{consumeApproval as te,requireProviderApproval as ne}from"./approval.js";import{outboundToken as ie}from"./mint.js";import{discardFile as se}from"./token-cache.js";import{registerProviderCall as ae}from"./inflight.js";import{buildRequestPlan as de}from"../command-plugins/transport/http-plan.js";import{sendProviderRequest as pe,ProviderTransportError as ue}from"./request.js";import{acceptProviderReceipt as le}from"./receipts.js";import{writeProviderAudit as ce}from"./audit.js";function O(e,r){const n=[],o=c((i,a)=>{const d=[...a,i.name];if(i.kind==="branch"){for(const g of i.children)o(g,d);return}const l=d[0]===r?d.slice(1).join(" "):d.join(" ");n.push({tool:l,leaf:i})},"walk");for(const i of e.roots)o(i,[]);return n}c(O,"providerLeaves");function D(e,r,n){if(e.kind!=="branch")return null;const o=[];for(const h of e.children)if(h.kind==="branch"){const w=D(h,r,n);w&&o.push(w)}else if("group"in h&&h.group&&T(n,`${r}:${h.group}`)){const{kind:w,name:k,description:t,whenToUse:A,tier:m,summary:q,params:b,output:j,effects:$,group:f}=h;o.push({kind:w,name:k,description:t,whenToUse:A,...m===void 0?{}:{tier:m},summary:q,params:b,output:j,effects:$,group:f})}if(o.length===0)return null;const{kind:i,name:a,description:d,whenToUse:l,tier:g,summary:v,model:_,rootEntry:y}=e;return{kind:i,name:a,description:d,whenToUse:l,...g===void 0?{}:{tier:g},summary:v,..._===void 0?{}:{model:_},...y===void 0?{}:{rootEntry:y},children:o}}c(D,"providerHelpBranch");async function Ne(e,r){const n=await S(r),o=O(n.commands,r),i=X("user").find(a=>a.name===r)?.manifest.description??r;return{provider:r,status:"available",major:n.major,display_name:i,groups:n.provider.groups.filter(a=>T(e,`${r}:${a.group}`)).map(a=>({group:a.group,leaves:o.filter(({leaf:d})=>d.group===a.group).map(({tool:d,leaf:l})=>({tool:d,description:l.description,summary:l.summary,params:l.params,output:l.output}))})),commands:n.commands.roots.flatMap(a=>{const d=D(a,r,e);return d?[d]:[]})}}c(Ne,"providerTools");function fe(e){return le(e.headers["crtr-receipt"],e)}c(fe,"onProviderResponse");function me(e){if(e.class==="person"){const r=W()?.sub;if(!r)throw new u("grant_revoked","the terminal has no active grant");return{sub:r,grantee:r}}if(!e.sub||!e.grantee)throw new u("grant_revoked","the caller has no active grant");return{sub:e.sub,grantee:e.grantee}}c(me,"identity");function ve(e,r){return[`${e.id}:${r.group}`]}c(ve,"callScope");function ge(e,r){const n=O(e.commands,e.id).find(o=>o.tool===r);if(!n)throw new u("not_found",`tool "${r}" is not in provider "${e.id}"`,{param:"tool"});if(!n.leaf.group)throw new u("not_found",`tool "${r}" has no group`,{param:"tool"});return n.leaf}c(ge,"leafFor");function J(e){if(!e||typeof e!="object"||Array.isArray(e))return{};const r=e.error;return!r||typeof r!="object"||Array.isArray(r)?{}:r}c(J,"errorBody");function he(e){const r=Array.isArray(e)?e[0]:e;if(!r)return;const n=Number(r);if(Number.isFinite(n)&&n>=0)return n;const o=Date.parse(r);return Number.isFinite(o)?Math.max(0,Math.ceil((o-Date.now())/1e3)):void 0}c(he,"retryAfter");function H(e,r,n,o=!1){const i=J(r),a=typeof i.code=="string"?i.code:void 0,d=typeof i.message=="string"?i.message:`provider answered HTTP ${e}`,l=typeof i.field=="string"?i.field:void 0,v={origin:"provider",details:{code:a??null,message:d,...l?{field:l}:{},...typeof i.next=="string"?{next:i.next}:{},...i.received!==void 0?{received:i.received}:{},status:e},...l?{param:l}:{}};return e===429?new u("provider_rate_limited",d,{...v,retry_after_s:he(n["retry-after"])}):e===401||e>=500?new u("provider_unavailable",d,v):e===403&&a==="provider_refused"?new u("provider_refused",d,v):e===403&&a==="approval_required"?new u("provider_error",o?"provider asked for approval again":"provider approval question is invalid",{...v,status:e}):new u("provider_error",d,{...v,status:e})}c(H,"mapProviderResponse");function L(e,r){return JSON.stringify({major:e.major,endpoint:e.transport.endpoint,baseUrl:e.commands.baseUrl??null,rest:r.rest,params:r.params,output:r.output})}c(L,"approvalShape");async function Se(e,r,n){const o=new AbortController,i=c(()=>o.abort(n.signal.reason),"abort");n.signal.aborted?i():n.signal.addEventListener("abort",i,{once:!0});let a=n.requestId;const d=ae({request_id:a,run_id:e.run_id,node_id:e.node_id,controller:o});let l,g,v,_,y,h,w,k="allowed";try{try{await Y(r.provider)}catch{throw ee(r.provider)}let t=await S(r.provider,r.version),A=!1,m,q,b,j=!1,$=!1;for(;;){const f=ge(t,r.tool);v=`${t.id}:${f.group}`,V(e,t.id,f.group);let I=null;if(r.approval&&!j){const s=te(e,r,L(t,f));b=s.option,I=s.prepared,w=r.approval,a=s.requestId,j=!0}const x={params:f.params.filter(s=>"type"in s&&s.type==="file").map(s=>s.name),output:f.output.find(s=>s.type==="file")?.name??null},B=JSON.stringify(x);if(q!==void 0&&q!==B)throw new u("provider_bad_response","the refreshed manifest changed the tool file contract",{origin:"provider",details:{status:409,message:"manifest_stale changed the tool file contract"}});q=B,I&&(m=await U(e,x,r.arguments,I,{signal:o.signal})),m??=await re(e,x,r.arguments,{signal:o.signal});const{sub:C,grantee:N}=me(e),R=await ie({audience:t.transport.endpoint,sub:C,grantee:N,initiating_app:N,scope:ve(t,f)},{signal:o.signal});_=R.jti;const G={registration:{name:t.id,endpoint:t.transport.endpoint},...t.commands.baseUrl?{baseUrl:t.commands.baseUrl}:{},...t.commands.timeouts?{timeouts:t.commands.timeouts}:{},params:f.params,rest:f.rest,output:f.output,commandPath:[t.id,...r.tool.split(" ")]},z=de(G,m.arguments,void 0,{authorization:`Bearer ${R.access_token}`,requestId:a,fileMode:"pass-through",extraHeaders:{...e.run_id?{"Crtr-Run-Id":e.run_id}:{},...b?{"Crtr-Approval":b}:{},...m.headers}});g??=Date.now()+(t.commands.timeouts?.requestMs??3e4);let p;try{if(p=await pe(z,{connectMs:t.commands.timeouts?.connectMs,requestMs:t.commands.timeouts?.requestMs,deadlineAt:g,signal:o.signal}),o.signal.aborted)throw o.signal.reason??new Error("provider call aborted")}catch(s){throw o.signal.aborted?o.signal.reason??s:s instanceof ue?new u("provider_unavailable",s.message,{origin:"provider",details:{status:null,code:s.kind}}):s}if(y??=fe({provider:t.id,tool:r.tool,request_id:a,run_id:e.run_id,sub:C,grantee:N,jti:R.jti,status:p.status,headers:p.headers}),h=p.headers["crtr-responder"],p.status===401&&se(R.key),p.status>=200&&p.status<300){const s=p.body;if(!s||typeof s!="object"||Array.isArray(s))throw new u("provider_bad_response","provider result is not a JSON object",{origin:"provider",details:{status:p.status,message:"provider result is not a JSON object"}});let E;try{E=await oe(e,m,s,{signal:o.signal})}catch(P){throw P instanceof u&&P.code==="provider_error"?new u("provider_bad_response",P.message,{origin:"provider",details:{status:p.status,message:P.message}}):P}l=E.cleanup;const F=Q(f.output,E.result);if(F)throw new u("provider_bad_response",`provider result has an invalid output field "${F.field}"`,{origin:"provider",param:F.field,details:{status:p.status,...F}});if(o.signal.aborted)throw o.signal.reason??new Error("provider call aborted");return{status:200,body:E.result}}const M=J(p.body);if(p.status===403&&M.code==="approval_required"&&!b&&!$){$=!0;const s=await ne(e,r,a,M.question,o.signal,L(t,f),m);if(w=s.questionId,b=s.option,m=await U(e,x,r.arguments,m,{signal:o.signal}),g=void 0,o.signal.aborted)throw new u("user_denied","the approval wait was canceled");continue}if(p.status===403&&M.code==="approval_required"&&b)throw H(p.status,p.body,p.headers,!0);if(p.status!==401&&M.manifest_stale===!0&&!A){A=!0,await Z(t.id,{conditional:!1,...r.version===void 0?{}:{version:r.version}}),t=await S(t.id,r.version);continue}throw H(p.status,p.body,p.headers,!!b)}}catch(t){throw t instanceof u&&t.question_id&&(w=t.question_id),k=`refused:${t instanceof u?t.code:"server_error"}`,l?.(),t}finally{try{ce({request_id:a,caller:e,provider:r.provider,tool:r.tool,scope_checked:v,outcome:k,jti:_,receipt_id:y,responder:h,question_id:w})}finally{d()}n.signal.removeEventListener("abort",i)}}c(Se,"callProvider");export{Se as callProvider,H as mapProviderResponse,fe as onProviderResponse,O as providerLeaves,Ne as providerTools};

package/dist/core/providers/errors.d.ts

@@ -0,0 +1,97 @@
+import { RunError } from '../runs/operations.js';
+export type ErrorType = 'invalid_request_error' | 'authentication_error' | 'permission_error' | 'rate_limit_error' | 'server_error';
+export type ErrorOrigin = 'directory' | 'router' | 'runtime' | 'provider';
+export interface CodeRow {
+    type: ErrorType;
+    status: number;
+    retryable: boolean;
+    user_action?: string;
+}
+/** The provider rows of the daemon-operations code table. `provider_error`'s
+ *  status is the provider's own 4xx; 400 is its default (a provider `scope_missing`). */
+export declare const PROVIDER_CODES: {
+    readonly provider_error: {
+        readonly type: "invalid_request_error";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly provider_rate_limited: {
+        readonly type: "rate_limit_error";
+        readonly status: 429;
+        readonly retryable: true;
+    };
+    readonly provider_unavailable: {
+        readonly type: "server_error";
+        readonly status: 503;
+        readonly retryable: true;
+    };
+    readonly provider_refused: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly provider_not_connected: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly provider_version_retired: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly storage_unavailable: {
+        readonly type: "server_error";
+        readonly status: 503;
+        readonly retryable: true;
+    };
+    readonly approval_pending: {
+        readonly user_action: "answer_question";
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly user_denied: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+};
+export type ProviderCode = keyof typeof PROVIDER_CODES;
+/** The non-provider codes a provider call also returns (the rest of the table
+ *  rows it reaches). Anything absent falls back by status. */
+declare const OTHER_CODES: Record<string, CodeRow>;
+export declare function codeRow(code: string, status: number): CodeRow;
+export interface ProviderErrorOptions {
+    /** Overrides the table status (`provider_error` carries the provider's 4xx). */
+    status?: number;
+    param?: string;
+    details?: unknown;
+    scope?: string;
+    origin?: ErrorOrigin;
+    retry_after_s?: number;
+    question_id?: string;
+    run_id?: string;
+}
+export declare class ProviderError extends RunError {
+    readonly origin: ErrorOrigin;
+    readonly type: ErrorType;
+    readonly retry_after_s?: number;
+    readonly question_id?: string;
+    readonly user_action?: string;
+    readonly run_id?: string;
+    constructor(code: ProviderCode | keyof typeof OTHER_CODES, message: string, options?: ProviderErrorOptions);
+}
+/** `scope_missing` naming the `<provider>:<group>` string. */
+export declare function scopeMissing(scope: string): ProviderError;
+/** The contract-2 error envelope for any value a provider operation throws.
+ *  A value that is not a `RunError` is a 500 `server_error` (its cause is logged by the caller).
+ *  `directoryCaller`: the caller holds a directory token (app listener). */
+export declare function providerErrorBody(thrown: unknown, requestId: string, directoryCaller: boolean, runId?: string): {
+    status: number;
+    body: {
+        error: Record<string, unknown>;
+    };
+    headers: Record<string, string>;
+};
+export {};

package/dist/core/providers/errors.js

@@ -0,0 +1 @@
+var y=Object.defineProperty;var d=(e,i)=>y(e,"name",{value:i,configurable:!0});import{RunError as _}from"../runs/operations.js";import{errorCodes as n}from"../../api/error-codes.js";const m={provider_error:{type:"invalid_request_error",status:400,retryable:!1},provider_rate_limited:n.provider_rate_limited,provider_unavailable:n.provider_unavailable,provider_refused:n.provider_refused,provider_not_connected:n.provider_not_connected,provider_version_retired:n.provider_version_retired,storage_unavailable:n.storage_unavailable,approval_pending:{...n.approval_pending,user_action:"answer_question"},user_denied:n.user_denied},g={unauthorized:n.unauthorized,grant_revoked:n.grant_revoked,scope_missing:n.scope_missing,permission_error:n.permission_error,invalid_request:n.invalid_request,not_found:n.not_found,not_implemented:n.not_implemented,runtime_starting:n.runtime_starting,server_error:n.server_error,provider_bad_response:n.provider_bad_response};function a(e,i){return m[e]??g[e]??(Object.prototype.hasOwnProperty.call(n,e)?n[e]:void 0)??{type:i===401?"authentication_error":i===403?"permission_error":i===429?"rate_limit_error":i>=500?"server_error":"invalid_request_error",status:i,retryable:i>=500}}d(a,"codeRow");class u extends _{static{d(this,"ProviderError")}origin;type;retry_after_s;question_id;user_action;run_id;constructor(i,s,t={}){const r=a(i,t.status??500);super(t.status??r.status,i,s,t.param,t.details,t.scope,r.retryable),this.type=r.type,this.origin=t.origin??"runtime",t.retry_after_s!==void 0&&(this.retry_after_s=t.retry_after_s),t.question_id!==void 0&&(this.question_id=t.question_id),t.run_id!==void 0&&(this.run_id=t.run_id),r.user_action!==void 0&&(this.user_action=r.user_action)}}function x(e){return new u("scope_missing",`missing scope ${e}`,{scope:e})}d(x,"scopeMissing");function b(e){if(!(e instanceof Error))return null;const{status:i,code:s,details:t,retryable:r}=e;return typeof i!="number"||typeof s!="string"||i<400||i>599?null:new _(i,s,e.message,void 0,t,void 0,typeof r=="boolean"?r:a(s,i).retryable)}d(b,"shaped");function q(e){if(e.code==="unauthorized"||e.code==="grant_revoked")return"reconnect";if(e.code==="scope_missing"&&e.scope)return`grant_scope:${e.scope}`}d(q,"directoryAction");function O(e,i,s,t){const r=e instanceof _?e:b(e)??new u("server_error","provider request failed"),o=r instanceof u?r:null,l=a(r.code,r.status),c=o?.run_id??t,p=o?.user_action??(s?q(r):void 0),v={code:r.code,message:r.message,...r.details===void 0?{}:{details:r.details},type:o?.type??l.type,...r.param?{param:r.param}:{},origin:o?.origin??"runtime",retryable:r.retryable,...o?.retry_after_s===void 0?{}:{retry_after_s:o.retry_after_s},request_id:i,...c?{run_id:c}:{},...o?.question_id?{question_id:o.question_id}:{},...p?{user_action:p}:{},...r.scope?{scope:r.scope}:{}},f={"Request-Id":i};return o?.retry_after_s!==void 0&&(f["Retry-After"]=String(o.retry_after_s)),{status:r.status,body:{error:v},headers:f}}d(O,"providerErrorBody");export{m as PROVIDER_CODES,u as ProviderError,a as codeRow,O as providerErrorBody,x as scopeMissing};

package/dist/core/providers/files.d.ts

@@ -0,0 +1,89 @@
+import { type StorageClient } from '../storage/client.js';
+/** The fields of `ProviderCaller` (daemon/api/handlers/providers.ts) this module
+ *  reads; a `ProviderCaller` is passed as is. */
+export interface FileCallCaller {
+    class: 'person' | 'app' | 'broker';
+    grantee: string | null;
+    resolved: readonly string[] | null;
+    nodeScopes: readonly string[] | null;
+    run_id: string | null;
+    node_id: string | null;
+}
+/** What a leaf's manifest declares about files: its `file`-typed params and its
+ *  one top-level `file` output field (D3-FILE-5), if any. */
+export interface LeafFiles {
+    params: readonly string[];
+    output: string | null;
+}
+export interface FileOptions {
+    /** Test seam: the storage client (default: the configured one). */
+    storage?: () => StorageClient;
+    signal?: AbortSignal;
+}
+/** One file argument copied to storage's `outbound` area. */
+export interface FileArgumentCopy {
+    param: string;
+    /** The caller's absolute runtime path (never sent to the provider). */
+    path: string;
+    name: string;
+    object_id: string;
+    /** The signed GET URL the provider receives, valid 15 minutes. */
+    url: string;
+}
+/** The upload a file result is PUT to. */
+export interface ResultUpload {
+    field: string;
+    upload_id: string;
+    upload_link: string;
+    /** The app the upload is recorded under (`uploads.grantee`). */
+    grantee: string;
+}
+export interface PreparedFileCall {
+    /** The call's arguments with every file argument replaced by its URL. */
+    arguments: Record<string, unknown>;
+    copies: FileArgumentCopy[];
+    upload: ResultUpload | null;
+    /** `Crtr-Upload-Id` and `Crtr-Upload-Link` for a leaf with a file output;
+     *  empty otherwise (D3-WIRE-9). */
+    headers: Record<string, string>;
+}
+export interface ResolvedFileResult {
+    /** The result with the file field replaced by a runtime path (unchanged when
+     *  the provider omitted the field). */
+    result: unknown;
+    /** Where the file landed, or null when the field was absent. */
+    file: {
+        path: string;
+        upload_id: string;
+    } | null;
+    /** Remove what this resolve wrote (for a failure after it). Idempotent. */
+    cleanup: () => void;
+}
+/** The fetch of a file result is bounded like an attachment fetch. */
+export declare const FILE_RESULT_FETCH_BUDGET_MS = 110000;
+/** Step 2 of a `provider.call` for a leaf with files, before any token is
+ *  minted: D3-FILE-1..3 for each file argument, then D3-FILE-6 for the output.
+ *  Refusals: `invalid_request` (`param`), `scope_missing` (`scope`),
+ *  `not_found`, `storage_unavailable`. A leaf with no files never touches
+ *  storage. */
+export declare function prepareFileCall(caller: FileCallCaller, leaf: LeafFiles, args: Record<string, unknown>, options?: FileOptions): Promise<PreparedFileCall>;
+/** The approval retry (D3-FILE-10, R5): a new GET URL for each copy and a new
+ *  PUT link for the upload. A copy storage no longer has (404, over 24 hours)
+ *  is made again from the caller's original path under the same checks. An
+ *  upload gone (404) is replaced by a new upload; one already holding bytes
+ *  (409: the provider PUT before asking for approval) is kept with its link
+ *  unchanged, since a stored upload's link cannot be re-signed and the
+ *  provider answers with that upload's id (G20). `args` are the caller's
+ *  original arguments (paths, not URLs). */
+export declare function resignForRetry(caller: FileCallCaller, leaf: LeafFiles, args: Record<string, unknown>, prepared: PreparedFileCall, options?: FileOptions): Promise<PreparedFileCall>;
+/** D3-FILE-8/9 on a 2xx result: accept the file field only when it names this
+ *  call's upload and storage's stored size equals `size` (and the bytes hash to
+ *  `sha256`); fetch it into the calling node's `attachments/` folder (outside a
+ *  run, `/apps/<app>/files/`), named after the field and unique there; record
+ *  it against the run; replace the field with the absolute runtime path.
+ *  `provider_error` for a wrong field, upload, size, digest or nothing stored;
+ *  `storage_unavailable` when storage cannot be reached. On any refusal nothing
+ *  is left in the caller's folder. */
+export declare function resolveFileResult(caller: FileCallCaller, prepared: PreparedFileCall, result: unknown, options?: FileOptions & {
+    budgetMs?: number;
+}): Promise<ResolvedFileResult>;

package/dist/core/providers/files.js

@@ -0,0 +1 @@
+var te=Object.defineProperty;var d=(e,t)=>te(e,"name",{value:t,configurable:!0});import{prepared as oe}from"../sqlite-statements.js";import{createHash as ne}from"node:crypto";import{closeSync as D,constants as re,createWriteStream as ie}from"node:fs";import{basename as ae,extname as se,isAbsolute as de,join as F}from"node:path";import{Transform as ue}from"node:stream";import{pipeline as le}from"node:stream/promises";import{appSpace as I}from"../layout.js";import{RunError as T}from"../runs/operations.js";import{createFileBeneath as ce,existsBeneath as M,openBeneath as fe,removeTreeBeneath as N,setModeBeneath as pe,unlinkBeneath as he,withDirBeneath as we}from"../spaces/open-beneath.js";import{ensureAppSpace as me}from"../spaces/space.js";import{invalidStorageName as H,storageClient as B,StorageRefused as U,UPLOAD_MAX_BYTES as C}from"../storage/client.js";import{contentTypeFor as _e,openCallerFile as ge}from"../storage/download.js";import{withCanvasWrite as ye}from"../canvas/db.js";import{deleteUploadUse as be,getUpload as $e,insertUpload as Se,insertUploadUses as ve,setUploadSize as Ue,uploadUseAt as ze}from"../storage/tables.js";import{ProviderError as l}from"./errors.js";const Ee=11e4,Ae="app:terminal";function P(e){if(e.class==="person")return e.grantee??Ae;if(!e.grantee)throw new l("server_error","provider caller has no grantee");return e.grantee}d(P,"grantee");function Fe(e){return e.class==="person"?null:{app:P(e),resolved:e.resolved??[],launched:e.class==="broker"?e.nodeScopes:null}}d(Fe,"fileCaller");function y(e){return e instanceof l?e:e instanceof U?new l("storage_unavailable",`storage refused: ${e.message}`):e instanceof T&&e.code==="storage_unavailable"?new l("storage_unavailable",e.message):e}d(y,"storageFailure");const b=d(e=>new l("provider_error",e,{origin:"provider"}),"providerError");function Te(e,t,n){if(typeof n!="string"||!n||!de(n)||n.includes("\0"))throw new l("invalid_request",`${t} must be an absolute runtime path`,{param:t});let i;try{i=ge(Fe(e),n)}catch(r){throw r instanceof T?r.code==="scope_missing"?new l("scope_missing",r.message,{param:t,...r.scope?{scope:r.scope}:{}}):r.code==="not_found"||r.code==="invalid_request"?new l("not_found",`no such file: ${n}`,{param:t}):r:r}try{if(i.size>C)throw new l("invalid_request",`${t} exceeds 100 MiB`,{param:t});const r=ae(i.path),o=H(r);if(o)throw new l("invalid_request",`${t}: file name cannot be sent: ${o}`,{param:t});return{param:t,file:i,name:r,mediaType:_e(i.path)}}catch(r){throw D(i.fd),r}}d(Te,"checkFileArgument");async function Be(e,t){try{const n=await e.createOutbound({name:t.name,size:t.file.size,media_type:t.mediaType});await e.putFileBytes(n.upload_link,t.file.fd,t.file.size,t.mediaType);const i=await e.signOutbound(n.object_id);return{param:t.param,path:t.file.path,name:t.name,object_id:n.object_id,url:i.url}}catch(n){throw y(n)}}d(Be,"copyOutbound");async function k(e,t,n,i){const r=[];try{for(const a of t)n[a]===void 0||n[a]===null||r.push(Te(e,a,n[a]));if(!r.length)return[];let o;try{o=i()}catch(a){throw y(a)}const c=[];for(const a of r)c.push(await Be(o,a));return c}finally{for(const o of r)D(o.file.fd)}}d(k,"copyArguments");function q(e){const t=H(e);if(t)throw new l("server_error",`file output ${e} cannot name an upload: ${t}`)}d(q,"checkOutputField");async function W(e,t,n){q(t);const i=P(e),r="application/octet-stream";let o;try{o=await n().createResultUpload({name:t,media_type:r,max_size:C})}catch(c){throw y(c)}return Se({upload_id:o.upload_id,grantee:i,name:t,media_type:r,size:C,created_at:new Date().toISOString()}),{field:t,upload_id:o.upload_id,upload_link:o.upload_link,grantee:i}}d(W,"createResultUpload");function X(e){return e?{"Crtr-Upload-Id":e.upload_id,"Crtr-Upload-Link":e.upload_link}:{}}d(X,"uploadHeaders");function Y(e,t){const n={...e};for(const i of t)n[i.param]=i.url;return n}d(Y,"withUrls");async function Je(e,t,n,i={}){const r=i.storage??B;t.output&&q(t.output);const o=await k(e,t.params,n,r),c=t.output?await W(e,t.output,r):null;return{arguments:Y(n,o),copies:o,upload:c,headers:X(c)}}d(Je,"prepareFileCall");async function Ke(e,t,n,i,r={}){const o=r.storage??B,c=[];for(const s of i.copies)try{const p=await o().signOutbound(s.object_id);c.push({...s,url:p.url})}catch(p){if(!(p instanceof U))throw y(p);c.push(...await k(e,[s.param],n,o))}let a=i.upload;if(a)try{const s=await o().signUploadLink(a.upload_id);a={...a,upload_link:s.upload_link}}catch(s){if(!(s instanceof U))throw y(s);s.status===404&&(a=await W(e,t.output??a.field,o))}return{arguments:Y(n,c),copies:c,upload:a,headers:X(a)}}d(Ke,"resignForRetry");const Ce=/^[0-9a-f]{64}$/i;function Oe(e,t){if(t===1)return e;const n=se(e);return n&&n!==e?`${e.slice(0,-n.length)}-${t}${n}`:`${e}-${t}`}d(Oe,"candidate");async function Qe(e,t,n,i={}){const r={result:n,file:null,cleanup:d(()=>{},"cleanup")},o=t.upload;if(!o||!n||typeof n!="object"||Array.isArray(n))return r;const c=n,a=c[o.field];if(a==null)return r;if(typeof a!="object"||Array.isArray(a))throw b(`${o.field} must be {upload_id, size, sha256}`);const s=a;if(typeof s.upload_id!="string"||typeof s.size!="number"||!Number.isSafeInteger(s.size)||s.size<0||typeof s.sha256!="string"||!Ce.test(s.sha256))throw b(`${o.field} must be {upload_id, size, sha256}`);if(s.upload_id!==o.upload_id)throw b(`${o.field} names an upload other than Crtr-Upload-Id`);const p=s.size,G=s.sha256.toLowerCase(),z=AbortSignal.timeout(i.budgetMs??Ee),O=i.signal?AbortSignal.any([z,i.signal]):z;let h;try{h=await(i.storage??B)().fetchUpload(o.upload_id,O)}catch(m){throw m instanceof U?b(`${o.field} names an upload with nothing stored`):y(m)}if(h.size===null)throw h.body.destroy(),new l("storage_unavailable",`storage did not say how many bytes ${o.field} holds`);if(h.size!==p)throw h.body.destroy(),b(`${o.field} claims ${p} bytes; storage holds ${h.size}`);const E=o.grantee,$=e.node_id!==null,J=await me(E),f=$?I(E).nodes:I(E).files,A=$?F(f,e.node_id):f,S=$?F(A,"attachments"):f,K={uid:process.getuid?.()??0,gid:J.gid},R=$&&!M(f,A),Q=$&&!R&&!M(f,S);let w=null,v=null,x=!1;const L=d(()=>{if(!x){if(x=!0,v)try{be(v)}catch{}if(w)try{he(f,w)}catch{}try{R?N(f,A):Q&&N(f,S)}catch{}}},"cleanup");try{we(f,S,()=>{},!0);for(let u=1;;u++){const _=F(S,Oe(o.field,u));if(!ze(_))try{ce(f,_,Buffer.alloc(0),432),w=_;break}catch(g){if(g.code!=="EEXIST")throw g}}let m=0;const j=ne("sha256"),V=new ue({transform(u,_,g){m+=u.length,j.update(u),g(null,u)}}),Z=fe(f,w,re.O_WRONLY);try{await le(h.body,V,ie("",{fd:Z,autoClose:!0}),{signal:O})}catch(u){throw z.aborted?new l("storage_unavailable","the file result could not be fetched within 110 s"):u instanceof T?y(u):new l("storage_unavailable",`storage stopped sending ${o.field}: ${u instanceof Error?u.message:String(u)}`)}if(m!==p)throw new l("storage_unavailable",`storage sent ${m} of ${p} bytes of ${o.field}`);if(j.digest("hex")!==G)throw b(`${o.field}: the stored bytes do not match sha256`);pe(f,w,432,K);const ee=w;ye(u=>{const _=$e(o.upload_id,u);if(!_||_.delete_pending_since)throw new l("not_found",`${o.field}: the upload was deleted while it was fetched`);if(Ue(o.upload_id,p,u),!e.run_id)return;const g=oe(u,"SELECT deleting_at FROM nodes WHERE node_id = ?").get(e.run_id);if(!g||g.deleting_at)throw new l("not_found",`run ${e.run_id} was deleted while its file result was fetched`);v={upload_id:o.upload_id,run_id:e.run_id,path:ee},ve([v],u)})}catch(m){throw h.body.destroy(),L(),m}return{result:{...c,[o.field]:w},file:{path:w,upload_id:o.upload_id},cleanup:L}}d(Qe,"resolveFileResult");export{Ee as FILE_RESULT_FETCH_BUDGET_MS,Je as prepareFileCall,Ke as resignForRetry,Qe as resolveFileResult};

package/dist/core/providers/inflight.d.ts

@@ -0,0 +1,13 @@
+export interface InflightProviderCall {
+    request_id: string;
+    run_id: string | null;
+    node_id: string | null;
+    controller: AbortController;
+}
+/** Register a call for its entire lifetime (including backoff and file retrieval). */
+export declare function registerProviderCall(call: InflightProviderCall): () => void;
+/** R9's run operations can abort matching calls without closing unrelated sockets. */
+export declare function abortProviderCalls(target: {
+    run?: string;
+    nodes?: readonly string[];
+}): void;

package/dist/core/providers/inflight.js

@@ -0,0 +1 @@
+var d=Object.defineProperty;var n=(e,o)=>d(e,"name",{value:o,configurable:!0});const r=new Map;function s(e){return r.set(e.request_id,e),()=>{r.get(e.request_id)===e&&r.delete(e.request_id)}}n(s,"registerProviderCall");function t(e){for(const o of r.values())(e.run&&o.run_id===e.run||e.nodes&&o.node_id&&e.nodes.includes(o.node_id))&&o.controller.abort()}n(t,"abortProviderCalls");export{t as abortProviderCalls,s as registerProviderCall};

package/dist/core/providers/mint.d.ts

@@ -0,0 +1,27 @@
+import { type GrantSync } from '../grants/sync.js';
+import { type CachedToken, type OutboundTokenRequest } from './token-cache.js';
+export type { OutboundTokenRequest } from './token-cache.js';
+export { discardFile } from './token-cache.js';
+/** How long the token endpoint has to answer. */
+export declare const MINT_TIMEOUT_MS = 10000;
+export interface MintOptions {
+    /** The directory issuer; default the configured `runtime.issuer`. */
+    issuer?: string;
+    /** The caller's signal: an abort rethrows its reason, not a mapped error. */
+    signal?: AbortSignal;
+    /** Test seam for the token endpoint. */
+    fetch?: typeof fetch;
+    /** The grant sync a stale-grant refusal triggers; default the daemon's (`requestGrantSync`). */
+    syncGrants?: GrantSync;
+    /** Clock for the reuse window (epoch ms). */
+    now?: () => number;
+}
+/** A token ready to send, plus the cache key R4 passes to `discardFile` on a provider 401. */
+export interface OutboundToken extends CachedToken {
+    key: string;
+}
+/** Mint one outbound token (no cache). Throws a mapped `ProviderError`. */
+export declare function mintOutboundToken(request: OutboundTokenRequest, options?: MintOptions): Promise<CachedToken>;
+/** The outbound token for `request`: the cached one while `now < exp − 30 s`
+ *  (D3-TOK-9), else a fresh mint, cached. Throws a mapped `ProviderError`. */
+export declare function outboundToken(request: OutboundTokenRequest, options?: MintOptions): Promise<OutboundToken>;

package/dist/core/providers/mint.js

@@ -0,0 +1 @@
+var j=Object.defineProperty;var s=(r,e)=>j(r,"name",{value:e,configurable:!0});import{createHash as T}from"node:crypto";import{readConfig as E}from"../config.js";import{emitEvent as R}from"../events/emit.js";import{grantSyncStateFor as M}from"../grants/mirror.js";import{assertion as A,requestGrantSync as N,runtimeClient as O}from"../grants/sync.js";import{ProviderError as p}from"./errors.js";import{cacheKey as P,cachedToken as I,discardEpoch as F,storeToken as G}from"./token-cache.js";import{discardFile as oe}from"./token-cache.js";const L=1e4;function C(r){const e=r.issuer??E("user").runtime?.issuer;if(!e)throw new p("not_found","provider calls need a directory-connected runtime");return e.replace(/\/$/,"")}s(C,"issuerOf");function m(r,e,t){return new p(r,e,{origin:"directory",details:t})}s(m,"directoryError");function D(r,e,t){const n=typeof e.error=="string"?e.error:null,o=typeof e.error_description=="string"?e.error_description:void 0,i={directory_status:r,...n?{directory_error:n}:{},...o?{directory_description:o}:{}},c=o?`: ${o}`:"";switch(n){case"invalid_client":case"invalid_request":return{error:m("server_error",`the directory refused the outbound token request (${n})${c}`,i),grantRefusal:!1};case"invalid_target":return{error:m("not_found",`the directory knows no provider at ${t.audience}${c}`,i),grantRefusal:!1};case"invalid_grant":return{error:m("grant_revoked",`the directory has no active grant for ${t.grantee}${c}`,i),grantRefusal:!0};case"provider_not_connected":return{error:m("provider_not_connected",o??"The user has not connected this provider.",i),grantRefusal:!1};case"invalid_scope":{const u=typeof e.scope=="string"&&e.scope?e.scope:t.scope.length===1?t.scope[0]:void 0,a=u?`missing scope ${u}`:`the grant does not cover ${t.scope.join(" ")}`;return{error:new p("scope_missing",a,{origin:"directory",details:i,...u?{scope:u}:{}}),grantRefusal:!0}}default:return{error:m("server_error",`the directory token endpoint answered ${r}${n?` ${n}`:""}${c}`,i),grantRefusal:!1}}}s(D,"refusal");function J(r){try{return JSON.parse(Buffer.from(r.split(".")[1]??"","base64url").toString("utf8"))}catch{return{}}}s(J,"claims");function U(r){const e=r.grant_rev,t=r.grant_status;return typeof e!="number"||!Number.isInteger(e)||e<0||typeof t!="string"?null:{rev:e,status:t}}s(U,"refusedGrantState");function B(r,e){const t=s(n=>n.status==="active"?0:1,"phase");return r.rev>e.rev||r.rev===e.rev&&t(r)>t(e)}s(B,"newer");function H(r,e,t){if(!e)return;const n=M(r.grantee,r.sub)??{rev:0,status:"removed"};if(!B(e,n))return;const o=t.syncGrants??N;Promise.resolve().then(()=>o({fresh:!0})).catch(()=>{})}s(H,"syncIfNewer");async function K(r,e={}){const n=`${C(e)}/token`,o=O(),i=new URLSearchParams({grant_type:"client_credentials",client_id:o.client_id,client_assertion_type:"urn:ietf:params:oauth:client-assertion-type:jwt-bearer",client_assertion:A(o,n),audience:r.audience,sub:r.sub,grantee:r.grantee,scope:[...new Set(r.scope)].sort().join(" "),initiating_app:r.initiating_app}),c=AbortSignal.timeout(L),u=e.signal?AbortSignal.any([e.signal,c]):c;let a,_;try{a=await(e.fetch??fetch)(n,{method:"POST",body:i,signal:u,headers:{Accept:"application/json"}}),_=await a.text()}catch(f){throw e.signal?.aborted?e.signal.reason:new p("server_error",`the directory token endpoint could not be reached: ${f instanceof Error?f.message:String(f)}`,{origin:"directory"})}let d=null;try{d=_?JSON.parse(_):null}catch{d=null}const l=d&&typeof d=="object"&&!Array.isArray(d)?d:{};if(!a.ok){const{error:f,grantRefusal:x}=D(a.status,l,r);throw R({level:"info",event:"daemon.providers.mint_refused",fields:{audience:r.audience,grantee:r.grantee,code:f.code,directory_error:typeof l.error=="string"?l.error:null,status:a.status}}),x&&H(r,U(l),e),f}const g=l.access_token;if(typeof g!="string"||!g)throw new p("server_error","the directory token response has no access_token",{origin:"directory"});const h=J(g),$=Math.floor((e.now?.()??Date.now())/1e3),y=l.expires_in,v=typeof y=="number"&&Number.isFinite(y)&&y>0?$+Math.floor(y):null,w=typeof h.exp=="number"?h.exp:null,b=v!==null&&w!==null?Math.min(v,w):v??w;if(b===null)throw new p("server_error","the directory token response names no expiry",{origin:"directory"});const S=typeof h.jti=="string"&&h.jti?h.jti:T("sha256").update(g).digest("hex");return{access_token:g,jti:S,exp:b}}s(K,"mintOutboundToken");const k=new Map;async function re(r,e={}){const t=P(r),n=e.now??Date.now,o=I(t,n());if(o)return{...o,key:t};let i=k.get(t);if(!i){const u=F(t);i=K(r,{...e,signal:void 0}).then(a=>(G(t,a,u),a)).finally(()=>{k.delete(t)}),i.catch(()=>{}),k.set(t,i)}return{...e.signal?await z(i,e.signal):await i,key:t}}s(re,"outboundToken");function z(r,e){return e.aborted?Promise.reject(e.reason):new Promise((t,n)=>{const o=s(()=>n(e.reason),"onAbort");e.addEventListener("abort",o,{once:!0}),r.then(t,n).finally(()=>e.removeEventListener("abort",o))})}s(z,"abortable");export{L as MINT_TIMEOUT_MS,oe as discardFile,K as mintOutboundToken,re as outboundToken};

package/dist/core/providers/receipts.d.ts

@@ -0,0 +1,9 @@
+/** A provider's informational receipt must belong to the call that carried it. */
+export declare function acceptProviderReceipt(value: string | string[] | undefined, call: {
+    provider: string;
+    tool: string;
+    request_id: string;
+    sub: string;
+    grantee: string;
+    run_id: string | null;
+}): string | undefined;

package/dist/core/providers/receipts.js

@@ -0,0 +1,3 @@
+var a=Object.defineProperty;var _=(r,t)=>a(r,"name",{value:t,configurable:!0});import{prepared as s}from"../sqlite-statements.js";import{withCanvasWrite as g}from"../canvas/db.js";function E(r,t){const d=Array.isArray(r)?r[0]:r;if(!d||d.length>16384)return;let n;try{n=JSON.parse(d)}catch{return}if(!n||typeof n!="object"||Array.isArray(n))return;const e=n;if(!(typeof e.receipt_id!="string"||!e.receipt_id||e.receipt_id.length>256||e.provider!==`app:${t.provider}`||e.tool!==t.tool||e.request_id!==t.request_id||e.sub!==t.sub||e.grantee!==t.grantee||e.payer!==t.sub||(e.run_id??null)!==t.run_id||typeof e.unit!="string"||!e.unit||typeof e.units!="number"||!Number.isFinite(e.units)||e.units<0||typeof e.time!="string"||!Number.isFinite(Date.parse(e.time))||typeof e.usd_equivalent!="number"||!Number.isFinite(e.usd_equivalent)||e.usd_equivalent<0))return g(i=>{if(!s(i,`INSERT OR IGNORE INTO provider_receipts
+      (provider, receipt_id, grantee, run_id, usd_equivalent, received_at) VALUES (?, ?, ?, ?, ?, ?)`).run(t.provider,e.receipt_id,t.grantee,t.run_id,e.usd_equivalent,new Date().toISOString()).changes)return;const p=new Date().toISOString().slice(0,7);if(s(i,`INSERT INTO grantee_usage (grantee, month, usd_equivalent) VALUES (?, ?, ?)
+      ON CONFLICT(grantee, month) DO UPDATE SET usd_equivalent = usd_equivalent + excluded.usd_equivalent`).run(t.grantee,p,e.usd_equivalent),t.run_id){const o=s(i,"SELECT usage_json FROM nodes WHERE node_id = ? AND run_id = ?").get(t.run_id,t.run_id);if(o){const u=o.usage_json?JSON.parse(o.usage_json):{};u.cost_usd=(typeof u.cost_usd=="number"?u.cost_usd:0)+e.usd_equivalent,s(i,"UPDATE nodes SET usage_json = ? WHERE node_id = ?").run(JSON.stringify(u),t.run_id)}}}),e.receipt_id}_(E,"acceptProviderReceipt");export{E as acceptProviderReceipt};

package/dist/core/providers/request.d.ts

@@ -0,0 +1,27 @@
+import { type IncomingHttpHeaders } from 'node:http';
+/** The caller builds and authorizes the request once; connection retries reuse it verbatim. */
+export interface ProviderRequestPlan {
+    url: URL | string;
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+}
+export interface ProviderRequestOptions {
+    connectMs?: number;
+    requestMs?: number;
+    /** Absolute Date.now() deadline, shared by separate sends (e.g. manifest refresh). */
+    deadlineAt?: number;
+    signal?: AbortSignal;
+}
+export interface ProviderResponse {
+    status: number;
+    headers: IncomingHttpHeaders;
+    /** JSON-decoded without output validation; non-JSON response bytes are returned as text. */
+    body: unknown;
+}
+export declare class ProviderTransportError extends Error {
+    readonly kind: 'timeout' | 'connection' | 'aborted';
+    constructor(kind: 'timeout' | 'connection' | 'aborted', message: string, options?: ErrorOptions);
+}
+/** Transport only: no provider response mapping, manifest refresh, or token handling. */
+export declare function sendProviderRequest(plan: ProviderRequestPlan, options?: ProviderRequestOptions): Promise<ProviderResponse>;

package/dist/core/providers/request.js

@@ -0,0 +1 @@
+var y=Object.defineProperty;var o=(n,e)=>y(n,"name",{value:e,configurable:!0});import{request as N}from"node:http";import{request as q}from"node:https";class w extends Error{static{o(this,"ProviderTransportError")}kind;constructor(e,r,i){super(r,i),this.kind=e,this.name="ProviderTransportError"}}const C=1e4,x=3e4,D=250,L=2e3,A=new Set(["ECONNREFUSED","ECONNRESET"]);async function Y(n,e={}){const r=new URL(n.url);if(r.protocol!=="http:"&&r.protocol!=="https:")throw new TypeError(`Unsupported provider protocol: ${r.protocol}`);const i=e.requestMs??x,s=e.connectMs??C;if(!Number.isFinite(i)||i<=0||!Number.isFinite(s)||s<=0)throw new RangeError("Provider timeouts must be positive finite milliseconds");const a=e.deadlineAt??Date.now()+i;if(!Number.isFinite(a))throw new RangeError("Provider deadline must be finite");let c=D,u;for(;;){if(e.signal?.aborted)throw b();const f=a-Date.now();if(f<=0)throw u?new w("connection","Provider connection retry deadline exhausted",{cause:u}):P();try{return await F(r,n,Math.min(s,f),f,e.signal)}catch(l){if(!(l instanceof T))throw l;if(u=l,e.signal?.aborted)throw b();const m=Math.min(c,a-Date.now());if(m<=0)throw S(l);if(await g(m,e.signal),e.signal?.aborted)throw b();if(Date.now()>=a)throw S(l);c=Math.min(c*2,L)}}}o(Y,"sendProviderRequest");class T extends Error{static{o(this,"RetryableConnectionError")}}function S(n){return new w("connection","Provider connection retry deadline exhausted",{cause:n})}o(S,"exhausted");function P(){return new w("timeout","Provider request timed out")}o(P,"timeout");function b(){return new w("aborted","Provider request aborted")}o(b,"aborted");function g(n,e){return new Promise((r,i)=>{if(e?.aborted){i(b());return}const s=setTimeout(a,n);e?.addEventListener("abort",c,{once:!0});function a(){e?.removeEventListener("abort",c),r()}o(a,"done");function c(){clearTimeout(s),e?.removeEventListener("abort",c),i(b())}o(c,"onAbort")})}o(g,"pause");function F(n,e,r,i,s){return new Promise((a,c)=>{if(s?.aborted){c(b());return}let u=!1,f=!1,l=!1,m,R;const E=(n.protocol==="https:"?q:N)(n,{method:e.method,headers:e.headers,agent:!1},t=>{f=!0,clearTimeout(m);const h=[];t.on("data",p=>h.push(p)),t.on("end",()=>{const p=Buffer.concat(h).toString("utf8");let M=p;try{M=JSON.parse(p)}catch{}d(void 0,{status:t.statusCode??0,headers:t.headers,body:M})}),t.on("error",p=>d(new w("connection","Provider response interrupted",{cause:p}))),t.on("close",()=>{t.complete||d(new w("connection","Provider response closed before completion"))})});function _(){clearTimeout(m),clearTimeout(R),s?.removeEventListener("abort",v)}o(_,"cleanup");function d(t,h){u||(u=!0,_(),t?(E.destroy(),c(t)):a(h))}o(d,"finish");function v(){d(b())}if(o(v,"onAbort"),s?.addEventListener("abort",v,{once:!0}),s?.aborted){v();return}m=setTimeout(()=>d(P()),r),R=setTimeout(()=>d(P()),i),E.on("socket",t=>{const h=o(()=>{l=!0,clearTimeout(m)},"connectedNow");t.connecting?t.once(n.protocol==="https:"?"secureConnect":"connect",h):h()}),E.on("error",t=>{u||(!f&&A.has(t.code??"")?d(new T(t.message,{cause:t})):d(new w("connection",f?"Provider response interrupted":"Provider connection failed",{cause:t})))}),E.on("close",()=>{!f&&!u&&d(new T(l?"Provider socket closed before response":"Provider connection closed before response"))}),e.body!==void 0&&E.write(e.body),E.end()})}o(F,"sendOnce");export{w as ProviderTransportError,Y as sendProviderRequest};

package/dist/core/providers/token-cache.d.ts

@@ -0,0 +1,44 @@
+import type { GrantRecord } from '../grants/mirror.js';
+/** A token is reused only while `now < exp − REUSE_MARGIN_S`. */
+export declare const REUSE_MARGIN_S = 30;
+/** What a mint is for; also the cache key's parts. */
+export interface OutboundTokenRequest {
+    /** The provider's registered endpoint URL (the token's `aud`). */
+    audience: string;
+    sub: string;
+    grantee: string;
+    initiating_app: string;
+    /** `<provider>:<group>` strings; order does not matter. */
+    scope: readonly string[];
+}
+/** A minted token. `exp` is epoch seconds (the JWT's own claim). */
+export interface CachedToken {
+    access_token: string;
+    jti: string;
+    exp: number;
+}
+export declare function tokenCacheDir(): string;
+/** JSON of `[aud, sub, grantee, initiating_app, sorted scopes]`. */
+export declare function cacheKey(request: OutboundTokenRequest): string;
+/** The cached token for `key` while it is still reusable, else null (a stale or unreadable file is removed). */
+export declare function cachedToken(key: string, nowMs?: number): CachedToken | null;
+/** The discard epoch of the pair a key names; pass it back to `storeToken`. */
+export declare function discardEpoch(key: string): number;
+/** Store a freshly minted token, unless its pair was discarded since `epoch` was read. Returns whether it was stored. */
+export declare function storeToken(key: string, token: CachedToken, epoch?: number): boolean;
+/** Discard the one token for `key` (a provider answered 401, D3-TOK-18). */
+export declare function discardFile(key: string): void;
+/** Discard every cached token for (`sub`, `grantee`). Returns how many went. */
+export declare function discardFor(sub: string, grantee: string, nowMs?: number): number;
+/** The (`sub`, `grantee`) pairs whose grant a sync revoked, removed, dropped,
+ *  replaced, or whose resolved scope set it changed. */
+export declare function changedGrantPairs(before: readonly GrantRecord[], after: readonly GrantRecord[]): Array<{
+    sub: string;
+    grantee: string;
+}>;
+/** The grant-sync hook (D3-TOK-20, CRD-16): discard every cached token of each
+ *  changed grant's (`sub`, `grantee`), and prune expired files. */
+export declare function discardChangedGrantTokens(before: readonly GrantRecord[], after: readonly GrantRecord[], nowMs?: number): {
+    pairs: number;
+    tokens: number;
+};

package/dist/core/providers/token-cache.js

@@ -0,0 +1 @@
+var k=Object.defineProperty;var o=(t,e)=>k(t,"name",{value:e,configurable:!0});import{createHash as J}from"node:crypto";import{mkdirSync as N,readdirSync as O,readFileSync as b,rmSync as p}from"node:fs";import{join as l}from"node:path";import{crtrHome as _}from"../canvas/paths.js";import{atomicWriteJson as j}from"../fs-utils.js";const F=30;function f(){return l(_(),"secrets","outbound-tokens")}o(f,"tokenCacheDir");function C(t){return JSON.stringify([t.audience,t.sub,t.grantee,t.initiating_app,[...new Set(t.scope)].sort()])}o(C,"cacheKey");function g(t){return l(f(),`${J("sha256").update(t).digest("hex")}.json`)}o(g,"fileFor");function m(t){try{const e=JSON.parse(t);return Array.isArray(e)&&typeof e[1]=="string"&&typeof e[2]=="string"?d(e[1],e[2]):null}catch{return null}}o(m,"pairOf");function d(t,e){return JSON.stringify([t,e])}o(d,"pairKey");function y(t){try{const e=JSON.parse(b(t,"utf8"));return typeof e.key!="string"||typeof e.access_token!="string"||typeof e.jti!="string"||typeof e.exp!="number"?null:e}catch{return null}}o(y,"readFile");function v(t,e){return e<(t.exp-F)*1e3}o(v,"usable");function H(t,e=Date.now()){const r=g(t),n=y(r);return!n||n.key!==t||!v(n,e)?(p(r,{force:!0}),null):{access_token:n.access_token,jti:n.jti,exp:n.exp}}o(H,"cachedToken");const a=new Map;function h(t){const e=m(t);return e===null?0:a.get(e)??0}o(h,"discardEpoch");function K(t,e,r=h(t)){return h(t)!==r?!1:(N(f(),{recursive:!0,mode:448}),j(g(t),{key:t,...e},{mode:384}),!0)}o(K,"storeToken");function P(t){p(g(t),{force:!0})}o(P,"discardFile");function x(t,e){let r;try{r=O(f())}catch{return 0}let n=0;for(const s of r){if(!s.endsWith(".json"))continue;const i=l(f(),s),c=y(i),u=c?m(c.key):null;c&&u!==null&&t.has(u)?(p(i,{force:!0}),n++):(!c||e>=c.exp*1e3)&&p(i,{force:!0})}return n}o(x,"sweep");function R(t,e,r=Date.now()){const n=d(t,e);return a.set(n,(a.get(n)??0)+1),x(new Set([n]),r)}o(R,"discardFor");function S(t){const e=new Map;for(const r of t){const n=r.resolved_scopes.map(({scope:i,mode:c})=>`${c} ${i}`).sort(),s=d(r.sub,r.grantee);e.set(s,[...e.get(s)??[],JSON.stringify([r.id,r.status,n])])}return new Map([...e].map(([r,n])=>[r,JSON.stringify(n.sort())]))}o(S,"grantStates");function D(t,e){const r=S(t),n=S(e),s=[];for(const[i,c]of r){if(n.get(i)===c)continue;const[u,w]=JSON.parse(i);s.push({sub:u,grantee:w})}return s}o(D,"changedGrantPairs");function W(t,e,r=Date.now()){const n=D(t,e).map(({sub:s,grantee:i})=>d(s,i));for(const s of n)a.set(s,(a.get(s)??0)+1);return{pairs:n.length,tokens:x(new Set(n),r)}}o(W,"discardChangedGrantTokens");export{F as REUSE_MARGIN_S,C as cacheKey,H as cachedToken,D as changedGrantPairs,W as discardChangedGrantTokens,h as discardEpoch,P as discardFile,R as discardFor,K as storeToken,f as tokenCacheDir};

package/dist/core/rate-limit-scope.d.ts

@@ -0,0 +1,25 @@
+export type ModelCooldownFamily = 'opus' | 'sonnet';
+export type RateLimitScope = {
+    kind: 'account';
+} | {
+    kind: 'model';
+    family: ModelCooldownFamily;
+};
+export interface RateLimitObservation {
+    scope: RateLimitScope;
+    /** `anthropic-ratelimit-unified-representative-claim`, when present. */
+    claim?: string;
+    /** Epoch ms the representative claim resets, from `-unified-reset` on a rejected response. */
+    resetAt?: number;
+    /** The rate-limit headers of the response (no auth material), lower-cased names. */
+    headers: Record<string, string>;
+}
+type HeaderSource = Headers | Record<string, string> | undefined;
+/** The cooldown family a model id belongs to, or undefined when only account-wide cooldowns apply to it. */
+export declare function modelCooldownFamily(modelId: string | undefined): ModelCooldownFamily | undefined;
+/** Only the rate-limit headers of a response: safe to log and store on a fault. */
+export declare function rateLimitHeaders(headers: HeaderSource): Record<string, string>;
+/** Classify a 429's headers for the model that was requested. */
+export declare function classifyRateLimit(headers: HeaderSource, modelId: string | undefined, now?: number): RateLimitObservation;
+export declare function describeRateLimitScope(scope: RateLimitScope): string;
+export {};

package/dist/core/rate-limit-scope.js

@@ -0,0 +1 @@
+var d=Object.defineProperty;var i=(e,t)=>d(e,"name",{value:t,configurable:!0});const m={seven_day_opus:"opus",seven_day_sonnet:"sonnet"},l=48,p=256;function y(e){if(e){if(/opus/i.test(e))return"opus";if(/sonnet/i.test(e))return"sonnet"}}i(y,"modelCooldownFamily");function L(e){return e?typeof Headers<"u"&&e instanceof Headers?[...e.entries()]:Object.entries(e).filter(t=>typeof t[1]=="string"):[]}i(L,"entries");function _(e){return e.startsWith("anthropic-ratelimit-")||e.startsWith("x-ratelimit-")||e==="retry-after"||e==="retry-after-ms"}i(_,"isRateLimitHeader");function b(e){const t={};for(const[s,r]of L(e)){const n=s.toLowerCase();if(_(n)){if(Object.keys(t).length>=l)break;t[n]=r.slice(0,p)}}return t}i(b,"rateLimitHeaders");function k(e,t,s=Date.now()){const r=b(e),n=r["anthropic-ratelimit-unified-representative-claim"]?.trim()||void 0,u=r["anthropic-ratelimit-unified-status"]?.trim()==="rejected",o=Number(r["anthropic-ratelimit-unified-reset"]),a=u&&Number.isFinite(o)&&o>0&&o*1e3>s?o*1e3:void 0,c=n===void 0?void 0:m[n],f=y(t);return{scope:u&&c!==void 0&&c===f?{kind:"model",family:c}:{kind:"account"},...n!==void 0?{claim:n}:{},...a!==void 0?{resetAt:a}:{},headers:r}}i(k,"classifyRateLimit");function x(e){return e.kind==="account"?"account":`model:${e.family}`}i(x,"describeRateLimitScope");export{k as classifyRateLimit,x as describeRateLimitScope,y as modelCooldownFamily,b as rateLimitHeaders};

package/dist/core/remote-canvas-target.d.ts

@@ -0,0 +1,4 @@
+import type { Scope, RemoteCanvasTarget } from '../types.js';
+import type { RelayTarget } from './broker-client/index.js';
+export declare function getRemoteCanvasTarget(name: string, scope?: Scope): RemoteCanvasTarget | undefined;
+export declare function resolveRemoteCanvasTarget(name: string, scope?: Scope): RelayTarget;

package/dist/core/remote-canvas-target.js

@@ -0,0 +1 @@
+var g=Object.defineProperty;var o=(e,t)=>g(e,"name",{value:t,configurable:!0});import{usage as s}from"./errors.js";import{readConfig as d}from"./config.js";import{getRelayToken as c}from"./secrets.js";function m(e,t="user"){return d(t).remoteCanvas.targets[e]}o(m,"getRemoteCanvasTarget");function p(e,t="user"){const a=d(t),r=a.remoteCanvas.targets[e];if(r===void 0){const i=Object.keys(a.remoteCanvas.targets);throw s(`no remote canvas target named '${e}'`+(i.length>0?` \u2014 configured: ${i.join(", ")}`:" \u2014 none configured yet")+`. Add one with \`crtr canvas config add ${e} --preview <url> --relay-token -\`.`)}const n=c(r.relayTokenRef,t);if(n===void 0||n==="")throw s(`target '${e}' has no stored relay token \u2014 add it with \`crtr canvas config add ${e} --relay-token -\`.`);return{previewEndpoint:r.previewEndpoint,relayToken:n}}o(p,"resolveRemoteCanvasTarget");export{m as getRemoteCanvasTarget,p as resolveRemoteCanvasTarget};

package/dist/core/render.d.ts

@@ -0,0 +1,12 @@
+import type { LeafHelp } from './help.js';
+import type { ErrorPayload } from './io.js';
+/** Schema-driven fallback: turn a result object into agent-ready plain markdown.
+ *  Field order follows the leaf's declared output schema; any extra keys append
+ *  after. Scalars (and nested objects) list as `- name: value` bullets, prose
+ *  fields render as paragraphs, and arrays become a count lead-in plus a table
+ *  or bullets. No root tag — the result is read as a continuation of the prompt. */
+export declare function renderResult(result: Record<string, unknown>, help: LeafHelp): string;
+/** Render a structured failure as an instruction-shaped block: what broke, what
+ *  was received, and the recovery road sign — the same recovery info the JSON
+ *  payload carries, shaped for the model to act on. */
+export declare function renderError(p: ErrorPayload): string;

package/dist/core/render.js

@@ -0,0 +1,18 @@
+var h=Object.defineProperty;var u=(e,n)=>h(e,"name",{value:n,configurable:!0});const $=new Set(["follow_up","digest","message","next","result","content","body","guide","summary","note","reason","detail","details","hint","instruction","instructions","prompt","roadmap","report","answer","response","text"]);function m(e){return String(e).replace(/"/g,"'").replace(/\n/g," ")}u(m,"attrEsc");function l(e){return e==null?"":Array.isArray(e)?e.map(l).join(", "):typeof e=="object"?JSON.stringify(e):String(e)}u(l,"scalarStr");function y(e){const n=JSON.stringify(e,null,2);let o="```";for(;n.includes(o);)o+="`";return`${o}json
+${n}
+${o}`}u(y,"fencedJson");function g(e,n){return typeof n!="string"?!1:$.has(e)?!0:n.includes(`
+`)||n.length>80}u(g,"isProse");function j(e){return l(e).replace(/\|/g,"\\|").replace(/\n/g," ")}u(j,"cellEsc");function b(e,n){if(n.length===0)return`0 ${e}.`;const o=`${n.length} ${e}:`;if(n.every(s=>s!==null&&typeof s=="object"&&!Array.isArray(s))){const s=n,i=[];for(const p of s)for(const a of Object.keys(p))i.includes(a)||i.push(a);const d=`| ${i.join(" | ")} |`,t=`| ${i.map(()=>"---").join(" | ")} |`,r=s.map(p=>`| ${i.map(a=>j(p[a])).join(" | ")} |`).join(`
+`);return`${o}
+
+${d}
+${t}
+${r}`}const c=n.map(s=>`- ${l(s)}`).join(`
+`);return`${o}
+${c}`}u(b,"renderArray");function A(e,n){const o=n.output.map(t=>t.name);for(const t of Object.keys(e))o.includes(t)||o.push(t);const f=[],c=[],s=[];for(const t of o){const r=e[t];if(r!=null){if(Array.isArray(r)){s.push(b(t,r));continue}if(g(t,r)){c.push({name:t,text:r});continue}f.push(`- ${t}: ${l(r)}`)}}const i=[];f.length>0&&i.push(f.join(`
+`));const d=c.length>1;for(const{name:t,text:r}of c)i.push(d?`**${t}:** ${r}`:r);for(const t of s)i.push(t);return i.join(`
+
+`)}u(A,"renderResult");function O(e){const n=[e.message];return e.received!==void 0&&e.received!==null&&e.received!==""&&n.push(`received: ${l(e.received)}`),e.field!==void 0&&n.push(`field: ${e.field}`),e.http_status!==void 0&&n.push(`http status: ${e.http_status}`),"primaryCompleted"in e&&e.primaryCompleted===!0&&(n.push("primaryCompleted: true"),n.push(`Primary result (the command already completed):
+${y(e.result)}`)),n.push(`Next: ${e.next}`),`<error code="${m(e.error)}">
+${n.join(`
+`)}
+</error>`}u(O,"renderError");export{O as renderError,A as renderResult};

package/dist/core/resolver.d.ts

@@ -0,0 +1,14 @@
+import type { InstalledMarketplace, InstalledPlugin, Scope } from '../types.js';
+export { listInstalledPluginsInRoot } from './installed-plugins.js';
+export declare function listInstalledPlugins(scope: Scope): InstalledPlugin[];
+export declare function listAllPlugins(): InstalledPlugin[];
+export declare function findPluginByName(name: string, scope?: Scope): InstalledPlugin | null;
+export interface ParsedSkillQualifier {
+    scope?: Scope;
+    segments: string[];
+}
+export declare function parseSkillQualifier(raw: string): ParsedSkillQualifier;
+export declare function listInstalledMarketplaces(scope: Exclude<Scope, 'builtin'>): InstalledMarketplace[];
+export declare function listAllMarketplaces(): InstalledMarketplace[];
+export declare function findMarketplaceByName(name: string, scope?: Exclude<Scope, 'builtin'>): InstalledMarketplace | null;
+export declare function scopeRootsLabel(): string;

package/dist/core/resolver.js

@@ -0,0 +1 @@
+var g=Object.defineProperty;var o=(t,e)=>g(t,"name",{value:e,configurable:!0});import{join as h}from"node:path";import{readConfig as x}from"./config.js";import{listDirs as j,pathExists as I}from"./fs-utils.js";import{readMarketplaceManifest as k}from"./manifest.js";import{InputError as M}from"./io.js";import{marketplacesDir as R,projectScopeRoot as u,scopeRoot as P,userScopeRoot as a}from"./scope.js";import{listInstalledPluginsInRoot as w}from"./installed-plugins.js";import{listInstalledPluginsInRoot as S}from"./installed-plugins.js";function l(t){const e=P(t);return e?S(t,e):[]}o(l,"listInstalledPlugins");function L(){const t=[];return u()&&t.push("project"),t.push("user"),t.push("builtin"),t.flatMap(l)}o(L,"listAllPlugins");function N(t,e){if(e)return l(e).find(r=>r.name===t)??null;for(const r of["project","user","builtin"].filter(n=>n==="project"?u()!==null:!0)){const n=l(r).find(s=>s.name===t);if(n)return n}return null}o(N,"findPluginByName");const E=new Set(["user","project"]);function Q(t){if(t.includes(":")){const r=t.replace(/:/g,"/");throw new M({error:"invalid_qualifier",message:"mixed separators ':' and '/' no longer supported; use slashes throughout",received:t,field:"name",next:`Use ${r}.`})}const e=t.split("/");return E.has(e[0])?{scope:e[0],segments:e.slice(1)}:{segments:e}}o(Q,"parseSkillQualifier");function f(t){const e=R(t);if(!e||!I(e))return[];const r=x(t),n=[];for(const s of j(e)){const c=h(e,s),p=k(c);if(!p)continue;const i=r.marketplaces[s],m=i&&i.url!==void 0?i.url:"",d=i&&i.ref!==void 0?i.ref:"main";n.push({name:s,scope:t,root:c,manifest:p,url:m,ref:d})}return n}o(f,"listInstalledMarketplaces");function U(){const t=[];return u()&&t.push("project"),t.push("user"),t.flatMap(f)}o(U,"listAllMarketplaces");function _(t,e){if(e)return f(e).find(r=>r.name===t)??null;for(const r of["project","user"]){if(r==="project"&&!u())continue;const n=f(r).find(s=>s.name===t);if(n)return n}return null}o(_,"findMarketplaceByName");function q(){const t=u();return t?`project=${t}, user=${a()}`:`user=${a()}`}o(q,"scopeRootsLabel");export{_ as findMarketplaceByName,N as findPluginByName,U as listAllMarketplaces,L as listAllPlugins,f as listInstalledMarketplaces,l as listInstalledPlugins,w as listInstalledPluginsInRoot,Q as parseSkillQualifier,q as scopeRootsLabel};

package/dist/core/review/birth.d.ts

@@ -0,0 +1,7 @@
+import type { ReviewRecord } from './types.js';
+import { type StageReviewArgs } from './stage.js';
+/**
+ * Stage filesystem-only fork state, atomically select the canonical binding,
+ * then realize that committed winner. Staging is never visible by itself.
+ */
+export declare function createReview(args: StageReviewArgs): Promise<ReviewRecord>;

package/dist/core/review/birth.js

@@ -0,0 +1 @@
+var s=Object.defineProperty;var n=(o,e)=>s(o,"name",{value:e,configurable:!0});import{commitBindingRequest as w}from"../human/requests.js";import{getReview as _}from"./store.js";import{discardStaging as a,stageReview as c}from"./stage.js";import{realizeReview as d}from"./realize.js";async function f(o){const e=await c(o);if(e.existing!==void 0){await d(e.existing.request_id);const r=_(e.existing.request_id);if(r===null)throw new Error(`realized review disappeared: ${e.existing.request_id}`);return r}let i;try{i=w({request_id:e.row.review_id,idempotency_key:e.row.idempotency_key,requester_node_id:e.row.origin_node_id,companion_node_id:e.row.companion_node_id,request_dir:e.row.review_dir,file:e.row.file,specification:{origin_kind:e.row.origin_kind,origin_session_file:e.row.origin_session_file,origin_session_id:e.row.origin_session_id,origin_leaf_id:e.row.origin_leaf_id,model_spec:e.row.model_spec,branch_file:e.row.branch_file,baseline_sha256:e.row.baseline_sha256,baseline_bytes:e.row.baseline_bytes,captured_at:e.row.captured_at,output_path:e.row.output_path,document_id:e.row.document_id,document_name:e.row.document_name,document_base:e.row.document_base},anchor_base_sha256:e.row.anchor_base_sha256,anchor_base_bytes:e.row.anchor_base_bytes,created_at:e.row.created,subtitle:e.row.subtitle,...e.row.document_name===null?{}:{title:e.row.document_name},inbox_listed:e.row.origin_kind==="ticket"})}catch(r){throw a(e.row.review_id,e.row.branch_file),r}i.won||a(e.row.review_id,e.row.branch_file),await d(i.request_id);const t=_(i.request_id);if(t===null)throw new Error(`realized review disappeared: ${i.request_id}`);return t}n(f,"createReview");export{f as createReview};