@north-light/api 0.3.558 → 0.3.560

package/dist/api/client.js

@@ -908,6 +908,8 @@ export class CrtrClient {
         const opts = this.resolveBudget(callOpts);
         const idempotent = method === 'GET' || method === 'HEAD' || method === 'DELETE';
         const maxRetries = opts.maxRetries ?? this.maxRetries;
+        // A hosted runtime being created or replaced answers reads with a refusal that never reached it; wait for it inside this allowance.
+        const replacementWaitEndsAt = Math.min(opts.deadlineAt ?? Infinity, Date.now() + HOSTED_REPLACEMENT_WAIT_MS);
         for (let attempt = 0;; attempt++) {
             let response;
             try {
@@ -942,6 +944,15 @@ export class CrtrClient {
                     throw toTransportApiError(err, opts.signal);
                 }
             }
+            if (isRead(method) && maxRetries > 0 && response.status === 503 && await isRefusedBeforeForwarding(response, opts.deadlineAt)) {
+                const delayMs = Math.max(250, (retryAfterHeaderS(response) ?? 0) * 1_000) + Math.random() * 250;
+                // Out of allowance: the refusal itself is the answer, so the caller sees its cause.
+                if (Date.now() + delayMs >= replacementWaitEndsAt)
+                    return response;
+                await drainResponseBody(response, opts.deadlineAt);
+                await sleepWithin(delayMs, { signal: opts.signal });
+                continue;
+            }
             if (idempotent && attempt < maxRetries && isRetryableStatus(response.status)) {
                 await drainResponseBody(response, opts.deadlineAt);
                 await sleepWithin(retryDelayMs(attempt + 1), opts, retryAfterHeaderS(response));
@@ -1266,6 +1277,29 @@ async function parse(res, deadlineAt) {
     }
     throw new ApiError(res.status, 'internal', `request failed with status ${res.status}`, undefined, res.headers);
 }
+/** How long a read waits for a hosted runtime that is being created or replaced. */
+const HOSTED_REPLACEMENT_WAIT_MS = 60_000;
+/** Only reads are replayed after a refusal; a write is never retried on this state. */
+function isRead(method) {
+    return method === 'GET' || method === 'HEAD';
+}
+/** True when the response is the hosting router's 503 for a runtime that provisioning is creating or replacing
+ *  (`details.forwarded === false`): the request reached no runtime, so replaying it cannot run anything twice.
+ *  Reads a clone, so the caller still gets the body of the response it is handed. */
+async function isRefusedBeforeForwarding(response, deadlineAt) {
+    try {
+        // A router refusal is a few hundred bytes; anything declared larger, or a body that stalls, is not one.
+        if (Number(response.headers.get('content-length') ?? 0) > 8_192)
+            return false;
+        const text = await readTextWithin(response.clone(), Math.min(deadlineAt ?? Infinity, Date.now() + 5_000));
+        const error = JSON.parse(text).error;
+        return error?.origin === 'router' && error.details?.forwarded === false
+            && (error.details.runtime_state === 'creating' || error.details.runtime_state === 'recovering');
+    }
+    catch {
+        return false;
+    }
+}
 /** `429`/`5xx` are the only statuses the §7 retry policy replays. */
 function isRetryableStatus(status) {
     return status === 429 || status >= 500;

package/dist/api/contract.d.ts

@@ -1,5 +1,5 @@
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export declare const CONTRACT_LEVEL = "1.33";
+export declare const CONTRACT_LEVEL = "1.34";
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export declare const REQUIRED_CONTRACT_HEADER = "Crouter-Required-Contract";
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/contract.js

@@ -12,7 +12,7 @@
 //
 // PURITY (spec §3.1): Node built-ins + `src/api/*` only.
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export const CONTRACT_LEVEL = '1.33';
+export const CONTRACT_LEVEL = '1.34';
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export const REQUIRED_CONTRACT_HEADER = 'Crouter-Required-Contract';
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

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

@@ -0,0 +1,10 @@
+import type { BashRunDTO } from './bash.js';
+/** `POST /v1/exec`: run the `crtr` binary with `argv` (no shell, no stdin) in the calling app's sandbox. */
+export interface ExecRunParams {
+    /** Arguments after `crtr`; at least one, under 32 KB as JSON text. */
+    argv: string[];
+    /** Seconds before the process is killed; default 60, at most 100. */
+    timeout_s?: number;
+}
+/** A non-zero exit or a timeout is still a 200 with this body. */
+export type ExecRunDTO = BashRunDTO;

package/dist/api/dto/exec.js

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

package/dist/api/error-codes.d.ts

@@ -134,6 +134,11 @@ export declare const errorCodes: {
         readonly status: 409;
         readonly retryable: false;
     };
+    readonly model_sign_in_required: {
+        readonly type: "invalid_request_error";
+        readonly status: 409;
+        readonly retryable: false;
+    };
     readonly invalid_argument: {
         readonly type: "invalid_request_error";
         readonly status: 400;
@@ -214,6 +219,11 @@ export declare const errorCodes: {
         readonly status: 429;
         readonly retryable: true;
     };
+    readonly busy: {
+        readonly type: "rate_limit_error";
+        readonly status: 429;
+        readonly retryable: true;
+    };
     readonly runtime_unreachable: {
         readonly type: "server_error";
         readonly status: 503;
@@ -224,6 +234,11 @@ export declare const errorCodes: {
         readonly status: 503;
         readonly retryable: true;
     };
+    readonly sandbox_unavailable: {
+        readonly type: "server_error";
+        readonly status: 503;
+        readonly retryable: false;
+    };
     readonly runtime_starting: {
         readonly type: "server_error";
         readonly status: 503;

package/dist/api/error-codes.js

@@ -37,6 +37,8 @@ export const errorCodes = {
     // A peer machine runs a crtr release below the peer-protocol floor; details `{ peer_version, floor, receiver_version }`. Update it with `crtr sys update`.
     peer_version_too_old: { type: 'invalid_request_error', status: 426, retryable: false },
     conflict: { type: 'invalid_request_error', status: 409, retryable: false },
+    // A node start by an exec (or a cron armed from one) whose model provider is not signed in; details `{ url }` = `<directory issuer>/account/ai-subscription`.
+    model_sign_in_required: { type: 'invalid_request_error', status: 409, retryable: false },
     // `provider.call` input that cannot apply: `machine` on a provider that is not served by a machine.
     invalid_argument: { type: 'invalid_request_error', status: 400, retryable: false },
     // A device call names no machine and the account has several (or the named one is not a device); details `{ candidates: [{ machine_id, name, last_seen }] }`.
@@ -58,8 +60,12 @@ export const errorCodes = {
     all_routes_exhausted: { type: 'rate_limit_error', status: 429, retryable: true },
     provider_rate_limited: { type: 'rate_limit_error', status: 429, retryable: true },
     rate_limited: { type: 'rate_limit_error', status: 429, retryable: true },
+    // `exec`: the app already has 4 live exec processes on this runtime.
+    busy: { type: 'rate_limit_error', status: 429, retryable: true },
     runtime_unreachable: { type: 'server_error', status: 503, retryable: true },
     isolated_unavailable: { type: 'server_error', status: 503, retryable: true },
+    // `exec` on a runtime without a root launcher: it cannot sandbox the app's process, so it refuses to run it.
+    sandbox_unavailable: { type: 'server_error', status: 503, retryable: false },
     runtime_starting: { type: 'server_error', status: 503, retryable: true },
     runtime_provisioning: { type: 'server_error', status: 503, retryable: true },
     provider_unavailable: { type: 'server_error', status: 503, retryable: true },

package/dist/api/index.d.ts

@@ -42,6 +42,7 @@ export * from './dto/worktree.js';
 export * from './dto/human.js';
 export * from './dto/files.js';
 export * from './dto/bash.js';
+export * from './dto/exec.js';
 export * from './dto/inbox.js';
 export * from './dto/human-requests.js';
 export * from './dto/reviews.js';

package/dist/api/index.js

@@ -39,6 +39,7 @@ export * from './dto/worktree.js';
 export * from './dto/human.js';
 export * from './dto/files.js';
 export * from './dto/bash.js';
+export * from './dto/exec.js';
 export * from './dto/inbox.js';
 export * from './dto/human-requests.js';
 export * from './dto/reviews.js';

package/dist/api/routes.d.ts

@@ -151,6 +151,7 @@ export declare const routes: {
     readonly fileWrite: () => string;
     readonly fileList: () => string;
     readonly bash: () => string;
+    readonly exec: () => string;
     readonly objects: () => string;
     readonly object: (ref: string) => string;
     readonly objectsSearch: () => string;

package/dist/api/routes.js

@@ -182,6 +182,7 @@ export const routes = {
     fileWrite: () => `${V}/files/write`,
     fileList: () => `${V}/files/list`,
     bash: () => `${V}/bash`,
+    exec: () => `${V}/exec`,
     // Canvas objects and documents. A ref (name or id) may contain `/`, so it is
     // always one percent-encoded path segment.
     objects: () => `${V}/objects`,

package/dist/core/io.js

@@ -310,6 +310,13 @@ export function apiErrorToCliError(err, next, options = {}) {
             next: 'Start it with `crtr sys daemon start`, then retry.',
         });
     }
+    // A node start through an app's exec without a signed-in AI subscription: the person signs in at the URL.
+    if (err.code === 'model_sign_in_required') {
+        const url = err.details?.url;
+        return new InputError({ error: err.code, message: err.message,
+            next: typeof url === 'string' ? `Ask the person to sign in at ${url}, then retry.` : 'Ask the person to sign in to an AI subscription on their Northlight account, then retry.',
+            ...(typeof url === 'string' ? { details: { url } } : {}) }, ExitCode.USAGE);
+    }
     // A responding daemon can relay an unavailable provider or storage service.
     // HTTP 503 alone does not mean that crtrd is down.
     const d = err.details;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.558",
+  "version": "0.3.560",
   "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",