@north-light/api 0.3.414 → 0.3.416

package/dist/api/__tests__/deadline.test.d.ts

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

package/dist/api/__tests__/deadline.test.js

@@ -0,0 +1,46 @@
+// CrtrClient: one absolute deadline per call (audit P2). It covers every attempt and every retry wait; a Retry-After
+// longer than the time left fails at once with `deadline_exceeded` instead of sleeping past the deadline.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { CrtrClient, sleepWithin } from '../client.js';
+import { ApiError } from '../errors.js';
+const busy = (retryAfter) => new Response(JSON.stringify({ error: { code: 'service_unavailable', message: 'busy' } }), {
+    status: 503, headers: { 'content-type': 'application/json', ...(retryAfter ? { 'retry-after': retryAfter } : {}) },
+});
+test('a GET whose Retry-After is longer than the time left fails at once, typed, without sleeping', async () => {
+    let attempts = 0;
+    const client = new CrtrClient({ baseUrl: 'http://daemon.test', fetch: async () => { attempts++; return busy('120'); }, maxRetries: 3 });
+    const started = Date.now();
+    await assert.rejects(client.request('GET', '/v1/x', undefined, { budgetMs: 5_000 }), (error) => {
+        assert.ok(error instanceof ApiError);
+        assert.equal(error.code, 'deadline_exceeded');
+        assert.equal(error.status, 504);
+        const details = error.details;
+        assert.equal(details.reason, 'retry_after');
+        assert.equal(details.retry_after_s, 120);
+        assert.ok(details.deadline_at >= started + 4_000);
+        return true;
+    });
+    assert.ok(Date.now() - started < 1_000);
+    assert.equal(attempts, 1);
+});
+test('a delayed response ends at the deadline with deadline_exceeded, even from a fetch that ignores its signal', async () => {
+    const client = new CrtrClient({ baseUrl: 'http://daemon.test', fetch: () => new Promise(() => { }), timeoutMs: 60_000 });
+    const started = Date.now();
+    await assert.rejects(client.request('GET', '/v1/x', undefined, { deadlineAt: Date.now() + 120 }), (error) => error instanceof ApiError && error.code === 'deadline_exceeded');
+    assert.ok(Date.now() - started < 1_000);
+});
+test('with no deadline a Retry-After is not waited on: the plain backoff applies', async () => {
+    let attempts = 0;
+    const client = new CrtrClient({ baseUrl: 'http://daemon.test', fetch: async () => { attempts++; return attempts === 1 ? busy('120') : Response.json({ ok: true }); }, maxRetries: 1 });
+    const started = Date.now();
+    assert.deepEqual(await client.request('GET', '/v1/x'), { ok: true });
+    assert.ok(Date.now() - started < 5_000);
+});
+test('sleepWithin refuses a wait that reaches the deadline and stops early on an abort', async () => {
+    await assert.rejects(sleepWithin(10, { deadlineAt: Date.now() + 50 }, 60), (error) => error instanceof ApiError && error.code === 'deadline_exceeded');
+    const controller = new AbortController();
+    const waiting = sleepWithin(5_000, { signal: controller.signal });
+    setTimeout(() => controller.abort(), 20);
+    await assert.rejects(waiting, (error) => error instanceof ApiError && error.code === 'request_aborted');
+});

package/dist/api/client.d.ts

@@ -1,3 +1,4 @@
+import { ApiError } from './errors.js';
 import type { AppLimitsChangeDTO, LimitsDTO, SetAppLimitsRequest } from './dto/limits.js';
 import type { DaemonAdmitDTO, DaemonRestartDTO, DueDTO, HealthDTO, MigrateStateDTO, MigrateStateRequest, StatusDTO } from './dto/health.js';
 import type { BashJobStatusDTO, BashJobStopResultDTO } from './dto/bash-jobs.js';
@@ -88,7 +89,18 @@ export interface CrtrRequestOptions {
      * interrupted-response recovery — to one wall-clock budget, without changing
      * the client's default inactivity timeout. */
     budgetMs?: number;
+    /** The same limit as an absolute instant (epoch milliseconds), for a caller that already holds one deadline
+     *  for a larger operation and passes it to every call inside it. With `budgetMs` too, the earlier wins. */
+    deadlineAt?: number;
 }
+/** Why a call stopped at its deadline: `elapsed` — the time ran out; `retry_after` — the server asked for a wait
+ *  longer than the time left, so the call stopped without sleeping. */
+export type DeadlineReason = 'elapsed' | 'retry_after';
+/** The one error a call raises when its deadline passes (or a wait would pass it): status 504, code `deadline_exceeded`,
+ *  `details: { deadline_at, reason, retry_after_s? }`. */
+/** The longest delay a timer accepts (2^31-1 ms, about 24.8 days); a longer deadline would fire at once. */
+export declare const MAX_TIMER_MS = 2147483647;
+export declare function deadlineExceeded(deadlineAt: number, reason?: DeadlineReason, retryAfterS?: number): ApiError;
 export declare class CrtrClient {
     private readonly baseUrl;
     private readonly fetch;
@@ -498,4 +510,12 @@ export declare class CrtrClient {
      * managed daemons still get the same bounded readiness window. */
     private handleColdSocket;
 }
+/** One retry wait inside a call's deadline. A server-requested wait (`retryAfterS`) is honored only against a deadline:
+ *  when it would not finish before the deadline the call fails now with `deadline_exceeded` (`reason: 'retry_after'`)
+ *  instead of sleeping past it; a call without a deadline keeps the plain backoff. The sleep ends early, with the same
+ *  error, if the caller aborts. */
+export declare function sleepWithin(backoffMs: number, opts: {
+    deadlineAt?: number;
+    signal?: AbortSignal;
+}, retryAfterS?: number, cause?: unknown): Promise<void>;
 export declare function safeColdStartDiagnostic(hook: (() => string | undefined) | undefined): string | undefined;

package/dist/api/client.js

@@ -37,7 +37,19 @@ export async function waitForDaemonAvailability({ windowMs, probe, initialError,
         await sleep(Math.min(pollIntervalMs, afterProbe));
     }
 }
-const budgetExhausted = () => Object.assign(new Error('request budget exhausted'), { code: 'ETIMEDOUT' });
+/** The one error a call raises when its deadline passes (or a wait would pass it): status 504, code `deadline_exceeded`,
+ *  `details: { deadline_at, reason, retry_after_s? }`. */
+/** The longest delay a timer accepts (2^31-1 ms, about 24.8 days); a longer deadline would fire at once. */
+export const MAX_TIMER_MS = 2_147_483_647;
+export function deadlineExceeded(deadlineAt, reason = 'elapsed', retryAfterS) {
+    const message = reason === 'retry_after'
+        ? `the server asked to retry after ${retryAfterS}s, which is later than the call's deadline (${new Date(deadlineAt).toISOString()}); not waiting`
+        : `the call's deadline (${new Date(deadlineAt).toISOString()}) passed`;
+    return new ApiError(504, 'deadline_exceeded', message, {
+        deadline_at: deadlineAt, reason, ...(retryAfterS === undefined ? {} : { retry_after_s: retryAfterS }),
+    });
+}
+const budgetExhausted = (deadlineAt) => deadlineExceeded(deadlineAt ?? Date.now());
 export class CrtrClient {
     baseUrl;
     fetch;
@@ -831,7 +843,10 @@ export class CrtrClient {
      *  autostart + retry + error-mapping semantics. */
     async request(method, path, body, opts) {
         try {
-            return await parse(await this.send(method, path, body, opts));
+            // The deadline is fixed once here so the headers, the retries and the reading of the body share it.
+            const resolved = opts === undefined ? undefined : this.resolveBudget(opts);
+            const response = await this.send(method, path, body, resolved);
+            return await parse(response, resolved?.deadlineAt);
         }
         catch (error) {
             throw toTransportApiError(error, opts?.signal);
@@ -866,6 +881,9 @@ export class CrtrClient {
                         response = await this.transport(method, path, body, opts);
                     }
                     catch (recoveryError) {
+                        // The caller's deadline, not the last probe failure, is why the call stopped when it has passed.
+                        if (opts.deadlineAt !== undefined && Date.now() >= opts.deadlineAt && !isAbortError(recoveryError, opts.signal))
+                            throw deadlineExceeded(opts.deadlineAt);
                         throw toTransportApiError(recoveryError, opts.signal);
                     }
                 }
@@ -873,7 +891,7 @@ export class CrtrClient {
                     return await this.rideOutInterruptedRequest(method, path, body, opts);
                 }
                 else if (idempotent && attempt < maxRetries && !isAbortError(err, opts.signal) && (!this.localSocketTransport || !this.isInterruptedSocketError(err))) {
-                    await sleepMs(retryDelayMs(attempt + 1));
+                    await sleepWithin(retryDelayMs(attempt + 1), opts);
                     continue;
                 }
                 else {
@@ -881,8 +899,8 @@ export class CrtrClient {
                 }
             }
             if (idempotent && attempt < maxRetries && isRetryableStatus(response.status)) {
-                await drainResponseBody(response);
-                await sleepMs(retryDelayMs(attempt + 1));
+                await drainResponseBody(response, opts.deadlineAt);
+                await sleepWithin(retryDelayMs(attempt + 1), opts, retryAfterHeaderS(response));
                 continue;
             }
             return response;
@@ -890,24 +908,26 @@ export class CrtrClient {
     }
     // internals
     resolveBudget(opts) {
-        const { budgetMs, ...rest } = opts;
-        if (budgetMs === undefined)
+        const { budgetMs, deadlineAt, ...rest } = opts;
+        if (budgetMs === undefined && deadlineAt === undefined)
             return rest;
-        if (!Number.isFinite(budgetMs) || budgetMs <= 0)
-            throw new RangeError('budgetMs must be a positive finite number');
-        return { ...rest, deadlineAt: Date.now() + budgetMs };
+        if (budgetMs !== undefined && (!Number.isFinite(budgetMs) || budgetMs <= 0 || budgetMs > MAX_TIMER_MS))
+            throw new RangeError(`budgetMs must be a positive finite number of at most ${MAX_TIMER_MS}`);
+        if (deadlineAt !== undefined && (!Number.isFinite(deadlineAt) || deadlineAt - Date.now() > MAX_TIMER_MS))
+            throw new RangeError(`deadlineAt must be a finite epoch-millisecond instant at most ${MAX_TIMER_MS} ms from now`);
+        return { ...rest, deadlineAt: Math.min(deadlineAt ?? Infinity, budgetMs === undefined ? Infinity : Date.now() + budgetMs) };
     }
     async awaitWithinBudget(promise, deadlineAt) {
         if (deadlineAt === undefined)
             return promise;
         const remainingMs = deadlineAt - Date.now();
         if (remainingMs <= 0)
-            throw budgetExhausted();
+            throw budgetExhausted(deadlineAt);
         let timer;
         try {
             return await Promise.race([
                 promise,
-                new Promise((_resolve, reject) => { timer = setTimeout(() => reject(budgetExhausted()), remainingMs); }),
+                new Promise((_resolve, reject) => { timer = setTimeout(() => reject(budgetExhausted(deadlineAt)), remainingMs); }),
             ]);
         }
         finally {
@@ -994,7 +1014,7 @@ export class CrtrClient {
     transport(method, path, body, opts = {}) {
         const remainingBudgetMs = opts.deadlineAt === undefined ? undefined : opts.deadlineAt - Date.now();
         if (remainingBudgetMs !== undefined && remainingBudgetMs <= 0)
-            return Promise.reject(budgetExhausted());
+            return Promise.reject(budgetExhausted(opts.deadlineAt));
         const payload = body === undefined ? undefined : JSON.stringify(body);
         const headers = { accept: 'application/json', ...this.headers, ...opts.headers };
         if (payload !== undefined)
@@ -1004,8 +1024,10 @@ export class CrtrClient {
             ? baseTimeoutMs
             : baseTimeoutMs > 0 ? Math.min(baseTimeoutMs, remainingBudgetMs) : remainingBudgetMs;
         const controller = new AbortController();
+        // The deadline, not the per-attempt timeout, ended this attempt when it was the nearer of the two.
+        const deadlineEnds = remainingBudgetMs !== undefined && (baseTimeoutMs <= 0 || remainingBudgetMs <= baseTimeoutMs);
         const timer = timeoutMs > 0
-            ? setTimeout(() => controller.abort(new DOMException('request timed out', 'TimeoutError')), timeoutMs)
+            ? setTimeout(() => controller.abort(deadlineEnds ? budgetExhausted(opts.deadlineAt) : new DOMException('request timed out', 'TimeoutError')), timeoutMs)
             : undefined;
         const externalSignal = opts.signal;
         const onExternalAbort = () => controller.abort(externalSignal?.reason);
@@ -1020,7 +1042,7 @@ export class CrtrClient {
                 clearTimeout(timer);
             externalSignal?.removeEventListener('abort', onExternalAbort);
         };
-        return this.fetch(new URL(path, this.baseUrl), { method, headers, body: payload, signal: controller.signal })
+        return abortable(this.fetch(new URL(path, this.baseUrl), { method, headers, body: payload, signal: controller.signal }), controller.signal)
             .then((response) => this.retainRequestLifetime(response, finish, () => controller.signal.aborted ? controller.signal.reason : undefined), (error) => {
             finish();
             throw error;
@@ -1096,7 +1118,7 @@ export class CrtrClient {
     async awaitAvailability(initialError, deadlineAt) {
         const remainingBudgetMs = deadlineAt === undefined ? undefined : deadlineAt - Date.now();
         if (remainingBudgetMs !== undefined && remainingBudgetMs <= 0)
-            throw budgetExhausted();
+            throw budgetExhausted(deadlineAt);
         let startupFailure;
         try {
             await waitForDaemonAvailability({
@@ -1173,9 +1195,9 @@ function withQuery(base, query) {
 /** Parse a response into `T` — the first (and here, only) read of its body —
  *  or throw `ApiError` on non-2xx. A 204/empty body yields `undefined`
  *  (callers that type `void`/optional handle it). */
-async function parse(res) {
+async function parse(res, deadlineAt) {
     const ok = res.status >= 200 && res.status < 300;
-    const trimmed = (await res.text()).trim();
+    const trimmed = (await readTextWithin(res, deadlineAt)).trim();
     let payload;
     if (trimmed !== '') {
         try {
@@ -1201,12 +1223,49 @@ function isRetryableStatus(status) {
 /** A response abandoned mid-retry must have its stream drained, or the
  *  underlying connection (and, over a unix socket, the daemon's handler) is
  *  held open by a reader that will never arrive. */
-async function drainResponseBody(res) {
+async function drainResponseBody(res, deadlineAt) {
+    const cancelled = (async () => {
+        try {
+            await res.body?.cancel();
+        }
+        catch {
+            // Best-effort — the response is being discarded either way.
+        }
+    })();
+    // A body whose cancel never settles must not hold the call past its deadline: stop waiting for it then.
+    if (deadlineAt === undefined)
+        return cancelled;
+    let timer;
     try {
-        await res.body?.cancel();
+        await Promise.race([cancelled, new Promise((resolve) => { timer = setTimeout(resolve, Math.max(0, deadlineAt - Date.now())); })]);
     }
-    catch {
-        // Best-effort — the response is being discarded either way.
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+/** The response body as text, or `deadline_exceeded` once `deadlineAt` passes first (the body is then cancelled
+ *  without waiting for it). A transport that sends headers and then stalls cannot hold the call past its deadline. */
+async function readTextWithin(res, deadlineAt) {
+    if (deadlineAt === undefined)
+        return res.text();
+    const remaining = deadlineAt - Date.now();
+    const reading = res.text();
+    reading.catch(() => { });
+    if (remaining <= 0) {
+        void res.body?.cancel().catch(() => { });
+        throw deadlineExceeded(deadlineAt);
+    }
+    let timer;
+    try {
+        return await Promise.race([
+            reading,
+            new Promise((_resolve, reject) => { timer = setTimeout(() => { void res.body?.cancel().catch(() => { }); reject(deadlineExceeded(deadlineAt)); }, remaining); }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
     }
 }
 /** Exponential backoff for the §7 retry policy: 250ms, 500ms, 1s, capped at 2s. */
@@ -1266,6 +1325,54 @@ function toTransportApiError(err, signal) {
     }
     return new ApiError(503, 'transport_error', message);
 }
+/** The `Retry-After` header as seconds (delta-seconds form only), else undefined. */
+function retryAfterHeaderS(response) {
+    const seconds = Number(response.headers.get('retry-after'));
+    return Number.isFinite(seconds) && seconds > 0 ? seconds : undefined;
+}
+/** One retry wait inside a call's deadline. A server-requested wait (`retryAfterS`) is honored only against a deadline:
+ *  when it would not finish before the deadline the call fails now with `deadline_exceeded` (`reason: 'retry_after'`)
+ *  instead of sleeping past it; a call without a deadline keeps the plain backoff. The sleep ends early, with the same
+ *  error, if the caller aborts. */
+export async function sleepWithin(backoffMs, opts, retryAfterS, cause) {
+    const { deadlineAt, signal } = opts;
+    if (signal?.aborted)
+        throw new ApiError(0, 'request_aborted', 'request aborted by caller signal');
+    const requestedMs = deadlineAt !== undefined && retryAfterS !== undefined ? retryAfterS * 1_000 : undefined;
+    const waitMs = Math.max(backoffMs, requestedMs ?? 0);
+    if (deadlineAt !== undefined && Date.now() + waitMs >= deadlineAt) {
+        const error = deadlineExceeded(deadlineAt, requestedMs !== undefined && requestedMs >= backoffMs ? 'retry_after' : 'elapsed', requestedMs === undefined ? undefined : retryAfterS);
+        if (cause !== undefined)
+            Object.defineProperty(error, 'cause', { value: cause, configurable: true, writable: true });
+        throw error;
+    }
+    if (signal === undefined)
+        return sleepMs(waitMs);
+    await new Promise((resolve, reject) => {
+        const onAbort = () => { clearTimeout(timer); signal.removeEventListener('abort', onAbort); reject(new ApiError(0, 'request_aborted', 'request aborted by caller signal')); };
+        const timer = setTimeout(() => { signal.removeEventListener('abort', onAbort); resolve(); }, waitMs);
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+/** `pending`, or its rejection with the signal's reason once the signal aborts first. A transport that ignores its
+ *  signal (a custom `fetch`) therefore still ends at the call's deadline; a response that arrives after the abort is
+ *  discarded and its body cancelled. */
+function abortable(pending, signal) {
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener('abort', onAbort, { once: true });
+        pending.then((response) => {
+            signal.removeEventListener('abort', onAbort);
+            if (signal.aborted)
+                void response.body?.cancel().catch(() => { });
+            else
+                resolve(response);
+        }, (error) => { signal.removeEventListener('abort', onAbort); reject(error); });
+    });
+}
 function sleepMs(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }

package/dist/api/dto/common.d.ts

@@ -20,7 +20,7 @@ export type ModeDTO = 'base' | 'orchestrator';
 /** Why a node last stopped (mirrors the runtime `ExitIntent` union). */
 export type ExitIntentDTO = 'done' | 'refresh' | 'idle-release' | 'parked' | null;
 /** Why a terminal node ended (mirrors the runtime `TerminalReason` union). */
-export type TerminalReasonDTO = 'finalized' | 'finished' | 'parked' | 'closed' | 'retired' | 'crashed' | 'stranded' | 'boot_failed' | 'crash_looped' | 'launch_failed' | 'context_overflow' | 'deadline_exceeded' | 'provider_fatal' | 'declined' | 'out_of_memory';
+export type TerminalReasonDTO = 'finalized' | 'finished' | 'parked' | 'closed' | 'retired' | 'crashed' | 'stranded' | 'boot_failed' | 'crash_looped' | 'launch_failed' | 'context_overflow' | 'deadline_exceeded' | 'provider_fatal' | 'declined' | 'out_of_memory' | 'cap_exhausted';
 /** Inbox urgency tier for a delivered message (mirrors feed/inbox `InboxTier`). */
 export type InboxTierDTO = 'critical' | 'urgent' | 'normal' | 'deferred';
 /** Whether a node id is a safe single filesystem path segment. Re-declared here

package/dist/api/dto/crons.d.ts

@@ -27,6 +27,12 @@ export interface CronDTO {
     created_by: NodeIdDTO | null;
     /** The bash command each fire runs. */
     command: string;
+    /** The grant the cron runs under (checked at every fire, call and birth); null only for the terminal on a runtime with no issuer. */
+    grant_id: string | null;
+    /** The scopes the cron is bounded to; null = the grant's whole current set (a person-armed terminal cron). */
+    scopes: string[] | null;
+    /** The run of the node that armed it, when a node did. */
+    origin_run_id: string | null;
     /** The shell and any spawned node stay isolated when armed from an isolated node. */
     isolated: boolean;
     /** Next occurrence (UTC). */
@@ -131,7 +137,7 @@ export interface ArmCronRequest {
     isolated?: boolean;
     /** Execution context, snapshotted at arm time — chosen by the client, else
      *  inherited from the creating node; never re-resolved at run time. Omitted
-     *  means the daemon's default: the creating node's folder for an isolated
+     *  means the daemon's default: the cron's own folder for an isolated
      *  cron, else the app's files directory. A runtime whose cron runs are
      *  sandboxed refuses (400 `cwd_not_mounted`) a chosen cwd the run's mounts do
      *  not reach, so a cron is never armed with a directory it cannot start in. */

package/dist/api/dto/human-requests.d.ts

@@ -41,7 +41,7 @@ export interface CreateHumanRequestDTO {
     delivery_state: HumanRequestDeliveryState;
 }
 export interface HumanRequestDeliveryFailureDTO {
-    kind: 'exit' | 'signal' | 'timeout' | 'spawn_error';
+    kind: 'exit' | 'signal' | 'timeout' | 'spawn_error' | 'grant_refused';
     exit_code?: number;
     signal?: string;
     message?: string;

package/dist/api/dto/run-events.d.ts

@@ -57,7 +57,7 @@ export type RunOutcomeDTO = (OutcomeBase & {
     details: DeclinedResultDTO | null;
 }) | (OutcomeBase & {
     kind: 'failure';
-    reason: 'canceled' | 'deadline_exceeded';
+    reason: 'canceled' | 'deadline_exceeded' | 'cap_exhausted';
     declined: null;
 }) | (OutcomeBase & {
     kind: 'failure';

package/dist/api/dto/usage.d.ts

@@ -0,0 +1,27 @@
+/** One served model's month-to-date usage (`usage.get` `by_model`). */
+export interface SpendUsageModelRowDTO {
+    served_model: string;
+    input_tokens: number;
+    output_tokens: number;
+    /** List-price cost; null when the served model has no list price (an app-registered endpoint, or an unpriced model). */
+    usd_equivalent: number | null;
+}
+/** `usage.get`: the caller's grantee's month-to-date spend (daemon operations, `usage.get`). */
+export interface SpendUsageDTO {
+    grantee: string;
+    /** UTC calendar month, `YYYY-MM`. */
+    month: string;
+    /** User-paid spend this month: every model completion and provider receipt. Receipts have no `by_model` row, so this can exceed the sum of `by_model`. */
+    usd_equivalent: number;
+    /** User-paid model completions, one row per served model. */
+    by_model: SpendUsageModelRowDTO[];
+    /** App-paid usage; never counts toward `spend_cap`. */
+    app_paid: {
+        usd_equivalent: number;
+        by_model: SpendUsageModelRowDTO[];
+    };
+    /** The monthly cap on user-paid spend; once `usd_equivalent` reaches it, user-paid model calls answer `cap_exhausted` until `reset_at`. Null when uncapped. */
+    spend_cap: number | null;
+    /** 00:00Z on the first day of the next UTC month, when the count starts over. */
+    reset_at: string;
+}

package/dist/api/dto/usage.js

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

package/dist/api/errors.js

@@ -51,7 +51,7 @@ export function isDaemonTransportApiError(error) {
         return false;
     return (error.status === 503 && (error.code === 'daemon_unavailable'
         || error.code === 'transport_error'
-        || error.code === 'daemon_request_interrupted')) || (error.status === 504 && error.code === 'request_timeout')
+        || error.code === 'daemon_request_interrupted')) || (error.status === 504 && (error.code === 'request_timeout' || error.code === 'deadline_exceeded'))
         || (error.status >= 500 && error.code === 'daemon_health_unavailable');
 }
 /** Type guard for an `ErrorBody`-shaped parsed payload. */

package/dist/api/index.d.ts

@@ -1,5 +1,5 @@
-export { CrtrClient, waitForDaemonAvailability } from './client.js';
-export type { CrtrClientOptions, CrtrRequestOptions } from './client.js';
+export { CrtrClient, deadlineExceeded, MAX_TIMER_MS, sleepWithin, waitForDaemonAvailability } from './client.js';
+export type { CrtrClientOptions, CrtrRequestOptions, DeadlineReason } from './client.js';
 export { APIError, ApiError, isErrorBody } from './errors.js';
 export type { ErrorBody } from './errors.js';
 export { errorCodes } from './error-codes.js';
@@ -14,6 +14,7 @@ export * from './dto/common.js';
 export * from './dto/health.js';
 export * from './dto/limits.js';
 export * from './dto/grants.js';
+export * from './dto/usage.js';
 export * from './dto/nodes.js';
 export * from './dto/node-outcomes.js';
 export * from './dto/node-events.js';

package/dist/api/index.js

@@ -1,7 +1,7 @@
 // `crouter/api` — the single source of truth for crtrd's API DTOs,
 // route constants, error contract, and the typed `CrtrClient`. Dependency-light
 // by design (spec §3.1): Node built-ins + `src/api/*` only.
-export { CrtrClient, waitForDaemonAvailability } from './client.js';
+export { CrtrClient, deadlineExceeded, MAX_TIMER_MS, sleepWithin, waitForDaemonAvailability } from './client.js';
 export { APIError, ApiError, isErrorBody } from './errors.js';
 export { errorCodes } from './error-codes.js';
 export { API_VERSION, routes } from './routes.js';
@@ -12,6 +12,7 @@ export * from './dto/common.js';
 export * from './dto/health.js';
 export * from './dto/limits.js';
 export * from './dto/grants.js';
+export * from './dto/usage.js';
 export * from './dto/nodes.js';
 export * from './dto/node-outcomes.js';
 export * from './dto/node-events.js';

package/dist/core/layout.d.ts

@@ -22,6 +22,8 @@ export declare function appSpace(app: string): {
     home: string;
     cache: string;
 };
+/** The folder an isolated cron runs in: `<app space>/crons/<cron_id>/`. It belongs to the cron, not to the node that armed it. */
+export declare function cronFolder(app: string, cronId: string): string;
 /** The HOME an app's processes run with. With no sandbox (a Mac) the terminal is
  *  the person at their own machine — its grant already holds all of the person's
  *  files and nothing at the OS level confines its bash — so it gets the person's

package/dist/core/layout.js

@@ -63,6 +63,12 @@ export function appSpace(app) {
     const root = join(appsRoot(), id);
     return { root, memory: join(root, 'memory'), conversations: join(root, 'conversations'), nodes: join(root, 'nodes'), files: join(root, 'files'), home: join(root, 'home'), cache: join(root, 'cache') };
 }
+/** The folder an isolated cron runs in: `<app space>/crons/<cron_id>/`. It belongs to the cron, not to the node that armed it. */
+export function cronFolder(app, cronId) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(cronId))
+        throw new Error(`invalid cron id: ${cronId}`);
+    return join(appSpace(app).root, 'crons', cronId);
+}
 /** The HOME an app's processes run with. With no sandbox (a Mac) the terminal is
  *  the person at their own machine — its grant already holds all of the person's
  *  files and nothing at the OS level confines its bash — so it gets the person's

package/dist/shared/env.d.ts

@@ -1,12 +1,13 @@
 /** The current node's id (`CRTR_NODE_ID`), or undefined outside a node. */
 export declare function envNodeId(): string | undefined;
 /** Find the single launch snapshot mounted by the launcher into this process's
- * Linux namespace. Cron bash has no CRTR_NODE_ID, but its creator's mounted
- * launch snapshot supplies config and granted-command projection without
- * claiming the cron is a node. Its broker relay may already have closed when
- * the cron fires; still classify the sandbox so CLI bootstrap never falls back
- * to host stores or person authority. Neither CRTR_NODE_ID, CRTR_ANCHOR, nor
+ * Linux namespace. Cron bash has no CRTR_NODE_ID: its own execution folder
+ * (`cron-<execution_id>`, holding `cron-launch.json` and the execution socket)
+ * supplies config and granted-command projection without claiming the cron is
+ * a node, and never falls back to host stores or person authority. Neither CRTR_NODE_ID, CRTR_ANCHOR, nor
  * the caller-editable CRTR_API_SOCKET selects the launch identity. */
+/** The launch snapshot a mounted run folder carries: a node's `broker-launch.json`, or a cron execution's `cron-launch.json`. */
+export declare function launchSnapshotFile(dir: string): string | undefined;
 export declare function sandboxCliNodeId(): string | undefined;
 /** A Linux app command uses its mounted launch snapshot, not host user stores. */
 export declare function isSandboxedNode(): boolean;

package/dist/shared/env.js

@@ -30,12 +30,20 @@ export function envNodeId() {
     return process.env['CRTR_NODE_ID'];
 }
 /** Find the single launch snapshot mounted by the launcher into this process's
- * Linux namespace. Cron bash has no CRTR_NODE_ID, but its creator's mounted
- * launch snapshot supplies config and granted-command projection without
- * claiming the cron is a node. Its broker relay may already have closed when
- * the cron fires; still classify the sandbox so CLI bootstrap never falls back
- * to host stores or person authority. Neither CRTR_NODE_ID, CRTR_ANCHOR, nor
+ * Linux namespace. Cron bash has no CRTR_NODE_ID: its own execution folder
+ * (`cron-<execution_id>`, holding `cron-launch.json` and the execution socket)
+ * supplies config and granted-command projection without claiming the cron is
+ * a node, and never falls back to host stores or person authority. Neither CRTR_NODE_ID, CRTR_ANCHOR, nor
  * the caller-editable CRTR_API_SOCKET selects the launch identity. */
+/** The launch snapshot a mounted run folder carries: a node's `broker-launch.json`, or a cron execution's `cron-launch.json`. */
+export function launchSnapshotFile(dir) {
+    for (const name of ['broker-launch.json', 'cron-launch.json']) {
+        const path = join(dir, name);
+        if (lstatSync(path, { throwIfNoEntry: false })?.isFile())
+            return path;
+    }
+    return undefined;
+}
 export function sandboxCliNodeId() {
     if (process.platform !== 'linux')
         return undefined;
@@ -45,7 +53,7 @@ export function sandboxCliNodeId() {
         const ids = readdirSync(root, { withFileTypes: true }).filter((entry) => entry.isDirectory() &&
             /^[a-zA-Z0-9][a-zA-Z0-9-]{0,127}$/.test(entry.name) &&
             mounted.has(join(root, entry.name)) &&
-            lstatSync(join(root, entry.name, 'broker-launch.json'), { throwIfNoEntry: false })?.isFile());
+            launchSnapshotFile(join(root, entry.name)) !== undefined);
         return ids.length === 1 ? ids[0].name : undefined;
     }
     catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.414",
+  "version": "0.3.416",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",