@north-light/api 0.0.0 → 0.3.414

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

@@ -0,0 +1,259 @@
+export declare const errorCodes: {
+    readonly unauthorized: {
+        readonly type: "authentication_error";
+        readonly status: 401;
+        readonly retryable: false;
+    };
+    readonly grant_revoked: {
+        readonly type: "authentication_error";
+        readonly status: 401;
+        readonly retryable: false;
+    };
+    readonly grant_removed: {
+        readonly type: "authentication_error";
+        readonly status: 401;
+        readonly retryable: false;
+    };
+    readonly grant_suspended: {
+        readonly type: "authentication_error";
+        readonly status: 401;
+        readonly retryable: false;
+    };
+    readonly refresh_token_expired: {
+        readonly type: "authentication_error";
+        readonly status: 401;
+        readonly retryable: false;
+    };
+    readonly refresh_token_reused: {
+        readonly type: "authentication_error";
+        readonly status: 401;
+        readonly retryable: false;
+    };
+    readonly scope_missing: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly owner_only: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly other_app_run: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly payer_not_app: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly approval_pending: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly user_denied: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    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_setup_pending: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly question_pages_off: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly isolated_run: {
+        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 invalid_scope: {
+        readonly type: "invalid_request_error";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly invalid_request: {
+        readonly type: "invalid_request_error";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly range_not_satisfiable: {
+        readonly type: "invalid_request_error";
+        readonly status: 416;
+        readonly retryable: false;
+    };
+    readonly conflict: {
+        readonly type: "invalid_request_error";
+        readonly status: 409;
+        readonly retryable: false;
+    };
+    readonly not_found: {
+        readonly type: "invalid_request_error";
+        readonly status: 404;
+        readonly retryable: false;
+    };
+    readonly model_unavailable: {
+        readonly type: "invalid_request_error";
+        readonly status: 404;
+        readonly retryable: false;
+    };
+    readonly upstream_model_unavailable: {
+        readonly type: "server_error";
+        readonly status: 503;
+        readonly retryable: true;
+    };
+    readonly substitution_refused: {
+        readonly type: "invalid_request_error";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly idempotency_conflict: {
+        readonly type: "invalid_request_error";
+        readonly status: 409;
+        readonly retryable: false;
+    };
+    readonly run_settled: {
+        readonly type: "invalid_request_error";
+        readonly status: 409;
+        readonly retryable: false;
+    };
+    readonly cap_exhausted: {
+        readonly type: "rate_limit_error";
+        readonly status: 402;
+        readonly retryable: false;
+    };
+    readonly concurrency_limit: {
+        readonly type: "rate_limit_error";
+        readonly status: 429;
+        readonly retryable: true;
+    };
+    readonly all_routes_exhausted: {
+        readonly type: "rate_limit_error";
+        readonly status: 429;
+        readonly retryable: true;
+    };
+    readonly provider_rate_limited: {
+        readonly type: "rate_limit_error";
+        readonly status: 429;
+        readonly retryable: true;
+    };
+    readonly rate_limited: {
+        readonly type: "rate_limit_error";
+        readonly status: 429;
+        readonly retryable: true;
+    };
+    readonly runtime_unreachable: {
+        readonly type: "server_error";
+        readonly status: 503;
+        readonly retryable: true;
+    };
+    readonly isolated_unavailable: {
+        readonly type: "server_error";
+        readonly status: 503;
+        readonly retryable: true;
+    };
+    readonly runtime_starting: {
+        readonly type: "server_error";
+        readonly status: 503;
+        readonly retryable: true;
+    };
+    readonly runtime_provisioning: {
+        readonly type: "server_error";
+        readonly status: 503;
+        readonly retryable: true;
+    };
+    readonly provider_unavailable: {
+        readonly type: "server_error";
+        readonly status: 503;
+        readonly retryable: true;
+    };
+    readonly upstream_refused: {
+        readonly type: "server_error";
+        readonly status: 502;
+        readonly retryable: false;
+    };
+    readonly provider_bad_response: {
+        readonly type: "server_error";
+        readonly status: 502;
+        readonly retryable: false;
+    };
+    readonly service_unavailable: {
+        readonly type: "server_error";
+        readonly status: 503;
+        readonly retryable: true;
+    };
+    readonly not_implemented: {
+        readonly type: "server_error";
+        readonly status: 501;
+        readonly retryable: false;
+    };
+    readonly permission_error: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
+    readonly storage_unavailable: {
+        readonly type: "server_error";
+        readonly status: 503;
+        readonly retryable: true;
+    };
+    readonly server_error: {
+        readonly type: "server_error";
+        readonly status: 500;
+        readonly retryable: true;
+    };
+    readonly server_failure: {
+        readonly type: "server_error";
+        readonly status: 500;
+        readonly retryable: false;
+    };
+    readonly wake_timeout: {
+        readonly type: "server_error";
+        readonly status: 504;
+        readonly retryable: true;
+    };
+};
+export type ErrorCode = keyof typeof errorCodes;
+export type ErrorType = (typeof errorCodes)[ErrorCode]['type'];
+export type ErrorOrigin = 'directory' | 'router' | 'runtime' | 'provider' | 'app';
+/** Full app-facing HTTP error body; the HTTP status is in the status line. */
+export interface ErrorEnvelope {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+        type: ErrorType;
+        param?: string;
+        origin: ErrorOrigin;
+        retryable: boolean;
+        retry_after_s?: number;
+        reset_at?: string;
+        request_id: string;
+        run_id?: string;
+        question_id?: string;
+        user_action?: string;
+        scope?: string;
+    };
+}

package/dist/api/error-codes.js

@@ -0,0 +1,56 @@
+// Contract 2, "Error envelope". This is the fixed-tuple subset of the
+// app-facing code table; codes with a variable status or a transport-specific
+// shape (provider_error, usage, stream_*) do not have a fixed tuple.
+export const errorCodes = {
+    unauthorized: { type: 'authentication_error', status: 401, retryable: false },
+    // A refusal that names no reason (runtime validation step 5, or the directory's bare invalid_grant). Not deprecated.
+    grant_revoked: { type: 'authentication_error', status: 401, retryable: false },
+    // The directory's reasons for refusing a refresh token (D2-ERR-49..51), carried in its invalid_grant error_description.
+    grant_removed: { type: 'authentication_error', status: 401, retryable: false },
+    grant_suspended: { type: 'authentication_error', status: 401, retryable: false },
+    refresh_token_expired: { type: 'authentication_error', status: 401, retryable: false },
+    refresh_token_reused: { type: 'authentication_error', status: 401, retryable: false },
+    scope_missing: { type: 'permission_error', status: 403, retryable: false },
+    owner_only: { type: 'permission_error', status: 403, retryable: false },
+    other_app_run: { type: 'permission_error', status: 403, retryable: false },
+    payer_not_app: { type: 'permission_error', status: 403, retryable: false },
+    approval_pending: { type: 'permission_error', status: 403, retryable: false },
+    user_denied: { type: 'permission_error', status: 403, retryable: false },
+    provider_refused: { type: 'permission_error', status: 403, retryable: false },
+    provider_not_connected: { type: 'permission_error', status: 403, retryable: false },
+    // An app refusing its own operation because a provider in its `requires` is not `ready`; details `{ provider, state, message?, next }`, copied from `grant.get`'s `dependencies[provider]` entry (`next` = `<issuer>/connect/setup/<provider>?client_id=<grantee>`). The daemon never raises it (it only carries `dependencies`).
+    provider_setup_pending: { type: 'permission_error', status: 403, retryable: false },
+    question_pages_off: { type: 'permission_error', status: 403, retryable: false },
+    isolated_run: { type: 'permission_error', status: 403, retryable: false },
+    provider_version_retired: { type: 'permission_error', status: 403, retryable: false },
+    invalid_scope: { type: 'invalid_request_error', status: 400, retryable: false },
+    invalid_request: { type: 'invalid_request_error', status: 400, retryable: false },
+    range_not_satisfiable: { type: 'invalid_request_error', status: 416, retryable: false },
+    conflict: { type: 'invalid_request_error', status: 409, retryable: false },
+    not_found: { type: 'invalid_request_error', status: 404, retryable: false },
+    model_unavailable: { type: 'invalid_request_error', status: 404, retryable: false },
+    upstream_model_unavailable: { type: 'server_error', status: 503, retryable: true },
+    substitution_refused: { type: 'invalid_request_error', status: 400, retryable: false },
+    idempotency_conflict: { type: 'invalid_request_error', status: 409, retryable: false },
+    run_settled: { type: 'invalid_request_error', status: 409, retryable: false },
+    cap_exhausted: { type: 'rate_limit_error', status: 402, retryable: false },
+    concurrency_limit: { type: 'rate_limit_error', status: 429, retryable: true },
+    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 },
+    runtime_unreachable: { type: 'server_error', status: 503, retryable: true },
+    isolated_unavailable: { type: 'server_error', status: 503, retryable: true },
+    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 },
+    upstream_refused: { type: 'server_error', status: 502, retryable: false },
+    provider_bad_response: { type: 'server_error', status: 502, retryable: false },
+    service_unavailable: { type: 'server_error', status: 503, retryable: true },
+    not_implemented: { type: 'server_error', status: 501, retryable: false },
+    permission_error: { type: 'permission_error', status: 403, retryable: false },
+    storage_unavailable: { type: 'server_error', status: 503, retryable: true },
+    server_error: { type: 'server_error', status: 500, retryable: true },
+    server_failure: { type: 'server_error', status: 500, retryable: false },
+    // Hosted router sleep/wake stage, not emitted by the always-on v1 runtime.
+    wake_timeout: { type: 'server_error', status: 504, retryable: true },
+};

package/dist/api/errors.d.ts

@@ -0,0 +1,47 @@
+/** The uniform JSON body crtrd returns on any non-2xx response. */
+export interface ErrorBody {
+    error: {
+        code: string;
+        message: string;
+        details?: unknown;
+        type?: string;
+        param?: string;
+        origin?: string;
+        retryable?: boolean;
+        retry_after_s?: number;
+        reset_at?: string;
+        request_id?: string;
+        run_id?: string;
+        question_id?: string;
+        scope?: string;
+        user_action?: string;
+    };
+}
+/** Thrown by `CrtrClient` on a non-2xx response (or a synthesized transport
+ *  failure such as an unreachable daemon). Carries the HTTP status, the stable
+ *  machine `code` from the `ErrorBody`, and optional structured `details`. */
+export declare class APIError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details?: unknown;
+    readonly headers: Headers;
+    readonly type?: string;
+    readonly param?: string;
+    readonly origin?: string;
+    readonly retryable?: boolean;
+    readonly retryAfterS?: number;
+    readonly resetAt?: string;
+    readonly requestId?: string;
+    readonly runId?: string;
+    readonly questionId?: string;
+    readonly scope?: string;
+    readonly userAction?: string;
+    constructor(status: number, code: string, message: string, details?: unknown, headers?: HeadersInit, envelope?: Partial<ErrorBody['error']>);
+}
+/** @deprecated Use APIError. Kept as the in-repo compatibility alias. */
+export { APIError as ApiError };
+/** A local API transport failure has stable status/code identity, independent
+ * of message prose. */
+export declare function isDaemonTransportApiError(error: unknown): error is APIError;
+/** Type guard for an `ErrorBody`-shaped parsed payload. */
+export declare function isErrorBody(value: unknown): value is ErrorBody;

package/dist/api/errors.js

@@ -0,0 +1,66 @@
+// API error contract (spec §8). Uniform JSON error body on any non-2xx; the
+// client parses it and throws `ApiError`.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+/** Thrown by `CrtrClient` on a non-2xx response (or a synthesized transport
+ *  failure such as an unreachable daemon). Carries the HTTP status, the stable
+ *  machine `code` from the `ErrorBody`, and optional structured `details`. */
+export class APIError extends Error {
+    status;
+    code;
+    details;
+    headers;
+    type;
+    param;
+    origin;
+    retryable;
+    retryAfterS;
+    resetAt;
+    requestId;
+    runId;
+    questionId;
+    scope;
+    userAction;
+    constructor(status, code, message, details, headers, envelope) {
+        super(message);
+        this.name = 'APIError';
+        this.status = status;
+        this.code = code;
+        this.headers = new Headers(headers);
+        if (details !== undefined)
+            this.details = details;
+        this.type = envelope?.type;
+        this.param = envelope?.param;
+        this.origin = envelope?.origin;
+        this.retryable = envelope?.retryable;
+        this.retryAfterS = envelope?.retry_after_s;
+        this.resetAt = envelope?.reset_at;
+        this.requestId = envelope?.request_id ?? this.headers.get('Request-Id') ?? undefined;
+        this.runId = envelope?.run_id;
+        this.questionId = envelope?.question_id;
+        this.scope = envelope?.scope;
+        this.userAction = envelope?.user_action;
+    }
+}
+/** @deprecated Use APIError. Kept as the in-repo compatibility alias. */
+export { APIError as ApiError };
+/** A local API transport failure has stable status/code identity, independent
+ * of message prose. */
+export function isDaemonTransportApiError(error) {
+    if (!(error instanceof APIError))
+        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.status >= 500 && error.code === 'daemon_health_unavailable');
+}
+/** Type guard for an `ErrorBody`-shaped parsed payload. */
+export function isErrorBody(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const err = value.error;
+    if (typeof err !== 'object' || err === null)
+        return false;
+    const { code, message } = err;
+    return typeof code === 'string' && typeof message === 'string';
+}

package/dist/api/index.d.ts

@@ -0,0 +1,48 @@
+export { CrtrClient, waitForDaemonAvailability } from './client.js';
+export type { CrtrClientOptions, CrtrRequestOptions } from './client.js';
+export { APIError, ApiError, isErrorBody } from './errors.js';
+export type { ErrorBody } from './errors.js';
+export { errorCodes } from './error-codes.js';
+export type { ErrorCode, ErrorEnvelope, ErrorOrigin, ErrorType } from './error-codes.js';
+export { API_VERSION, routes } from './routes.js';
+export { RUNTIME_VERSION_HEADER, MINIMUM_RUNTIME_VERSION_HEADER, compareReleaseVersions, minimumRuntimeRefusal } from './runtime-version.js';
+export type { MinimumRuntimeRefusal } from './runtime-version.js';
+export { LONG_POLL_MAX_WAIT_SECONDS, LONG_POLL_ROUTES, longPollHoldSeconds, longPollRoute, requestedWait } from './long-poll.js';
+export type { LongPollName, LongPollRoute } from './long-poll.js';
+export * from '../shared/generated-context.js';
+export * from './dto/common.js';
+export * from './dto/health.js';
+export * from './dto/limits.js';
+export * from './dto/grants.js';
+export * from './dto/nodes.js';
+export * from './dto/node-outcomes.js';
+export * from './dto/node-events.js';
+export * from './dto/run-events.js';
+export * from './dto/broker-signals.js';
+export * from './dto/bash-jobs.js';
+export * from './dto/messages.js';
+export * from './dto/reports.js';
+export * from './dto/structured-requests.js';
+export * from './dto/lifecycle.js';
+export * from './dto/subscriptions.js';
+export * from './dto/focus.js';
+export * from './dto/crons.js';
+export * from './dto/config.js';
+export * from './dto/attach.js';
+export * from './dto/broker.js';
+export * from './dto/profiles.js';
+export * from './dto/modelauth.js';
+export * from './dto/model-config.js';
+export * from './dto/canvas.js';
+export * from './dto/worktree.js';
+export * from './dto/human.js';
+export * from './dto/files.js';
+export * from './dto/bash.js';
+export * from './dto/inbox.js';
+export * from './dto/human-requests.js';
+export * from './dto/reviews.js';
+export * from './dto/review-comments.js';
+export * from './dto/chat-inventory.js';
+export * from './dto/analytics.js';
+export * from './dto/custom-objects.js';
+export type { WatchRequest, WatchResultDTO, UnwatchQuery, UnwatchResultDTO } from './dto/objects.js';

package/dist/api/index.js

@@ -0,0 +1,45 @@
+// `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 { APIError, ApiError, isErrorBody } from './errors.js';
+export { errorCodes } from './error-codes.js';
+export { API_VERSION, routes } from './routes.js';
+export { RUNTIME_VERSION_HEADER, MINIMUM_RUNTIME_VERSION_HEADER, compareReleaseVersions, minimumRuntimeRefusal } from './runtime-version.js';
+export { LONG_POLL_MAX_WAIT_SECONDS, LONG_POLL_ROUTES, longPollHoldSeconds, longPollRoute, requestedWait } from './long-poll.js';
+export * from '../shared/generated-context.js';
+export * from './dto/common.js';
+export * from './dto/health.js';
+export * from './dto/limits.js';
+export * from './dto/grants.js';
+export * from './dto/nodes.js';
+export * from './dto/node-outcomes.js';
+export * from './dto/node-events.js';
+export * from './dto/run-events.js';
+export * from './dto/broker-signals.js';
+export * from './dto/bash-jobs.js';
+export * from './dto/messages.js';
+export * from './dto/reports.js';
+export * from './dto/structured-requests.js';
+export * from './dto/lifecycle.js';
+export * from './dto/subscriptions.js';
+export * from './dto/focus.js';
+export * from './dto/crons.js';
+export * from './dto/config.js';
+export * from './dto/attach.js';
+export * from './dto/broker.js';
+export * from './dto/profiles.js';
+export * from './dto/modelauth.js';
+export * from './dto/model-config.js';
+export * from './dto/canvas.js';
+export * from './dto/worktree.js';
+export * from './dto/human.js';
+export * from './dto/files.js';
+export * from './dto/bash.js';
+export * from './dto/inbox.js';
+export * from './dto/human-requests.js';
+export * from './dto/reviews.js';
+export * from './dto/review-comments.js';
+export * from './dto/chat-inventory.js';
+export * from './dto/analytics.js';
+export * from './dto/custom-objects.js';

package/dist/api/long-poll.d.ts

@@ -0,0 +1,59 @@
+/** The longest any long-poll holds a request, in seconds. */
+export declare const LONG_POLL_MAX_WAIT_SECONDS = 25;
+export interface LongPollRoute {
+    /** The daemon operation this route is (its operation-table name), or, for a route outside `/v1`, a stable label. */
+    readonly name: string;
+    readonly method: 'GET';
+    /** `:name`-style path pattern, matched segment by segment like the daemon's router. */
+    readonly path: string;
+    /** The smallest `?wait=` the route accepts: the caller asks for an integer from this through
+     *  {@link LONG_POLL_MAX_WAIT_SECONDS} seconds, absent meaning 0 (answer at once). Without it the route takes no
+     *  `wait` and always holds up to {@link LONG_POLL_MAX_WAIT_SECONDS}. */
+    readonly minWait?: 0 | 1;
+}
+export declare const LONG_POLL_ROUTES: readonly [{
+    readonly name: "run.get";
+    readonly method: "GET";
+    readonly path: "/v1/runs/:run_id";
+    readonly minWait: 1;
+}, {
+    readonly name: "grant.get";
+    readonly method: "GET";
+    readonly path: "/v1/grant";
+    readonly minWait: 1;
+}, {
+    readonly name: "model_auth.get";
+    readonly method: "GET";
+    readonly path: "/v1/model-auth/flows/:flow_id";
+    readonly minWait: 1;
+}, {
+    readonly name: "structured-request.get";
+    readonly method: "GET";
+    readonly path: "/v1/structured-requests/:request_id";
+    readonly minWait: 0;
+}, {
+    readonly name: "node-outcomes.get.119";
+    readonly method: "GET";
+    readonly path: "/v1/nodes/:id/outcome";
+    readonly minWait: 0;
+}, {
+    readonly name: "vendor-signin.wait";
+    readonly method: "GET";
+    readonly path: "/signin/vendor/:flow_id/wait";
+}];
+export type LongPollName = (typeof LONG_POLL_ROUTES)[number]['name'];
+/** The long-poll route a request path is, or `undefined`. `pathname` is the URL's path without its query. */
+export declare function longPollRoute(method: string, pathname: string): LongPollRoute | undefined;
+/**
+ * The seconds a long-poll request asks to be held, from its first `wait` value: 0 when it carries none or an empty
+ * one (it answers at once), the requested seconds when `wait` is a decimal integer (no sign, no leading zero) in the
+ * route's range, and `null` when the daemon refuses it with 400 `invalid_request`. A route without `minWait` ignores
+ * the query and always holds up to {@link LONG_POLL_MAX_WAIT_SECONDS}.
+ */
+export declare function requestedWait(route: LongPollRoute, query: URLSearchParams): number | null;
+/**
+ * How long the daemon may hold this request before it starts answering, in seconds — or `undefined` when it answers
+ * at once: not a long-poll route, no `wait` or `wait=0`, or a `wait` it refuses. A proxy adds its own answer deadline
+ * on top. `url` is the request target (`/v1/runs/r1?wait=25`) or a parsed URL.
+ */
+export declare function longPollHoldSeconds(method: string, url: string | URL): number | undefined;

package/dist/api/long-poll.js

@@ -0,0 +1,67 @@
+// The daemon's long-polls: the routes that may hold a request open before
+// answering, and how long. This table is the one declaration of them — the
+// daemon parses every `?wait=` through it, and a proxy in front of the daemon
+// (the hosting router) reads it to give a held request its hold plus its normal
+// answer deadline instead of cutting it off.
+//
+// PURITY (spec §3.1): Node built-ins + `src/api/*` only.
+/** The longest any long-poll holds a request, in seconds. */
+export const LONG_POLL_MAX_WAIT_SECONDS = 25;
+export const LONG_POLL_ROUTES = [
+    { name: 'run.get', method: 'GET', path: '/v1/runs/:run_id', minWait: 1 },
+    { name: 'grant.get', method: 'GET', path: '/v1/grant', minWait: 1 },
+    { name: 'model_auth.get', method: 'GET', path: '/v1/model-auth/flows/:flow_id', minWait: 1 },
+    { name: 'structured-request.get', method: 'GET', path: '/v1/structured-requests/:request_id', minWait: 0 },
+    { name: 'node-outcomes.get.119', method: 'GET', path: '/v1/nodes/:id/outcome', minWait: 0 },
+    // The vendor sign-in page's wait: outside `/v1` and the operation table, always held.
+    { name: 'vendor-signin.wait', method: 'GET', path: '/signin/vendor/:flow_id/wait' },
+];
+function segments(path) {
+    return path.split('/').filter((segment) => segment.length > 0);
+}
+/** The long-poll route a request path is, or `undefined`. `pathname` is the URL's path without its query. */
+export function longPollRoute(method, pathname) {
+    if (method.toUpperCase() !== 'GET')
+        return undefined;
+    const actual = segments(pathname);
+    return LONG_POLL_ROUTES.find((route) => {
+        const pattern = segments(route.path);
+        return pattern.length === actual.length && pattern.every((segment, i) => segment.startsWith(':') || segment === actual[i]);
+    });
+}
+/**
+ * The seconds a long-poll request asks to be held, from its first `wait` value: 0 when it carries none or an empty
+ * one (it answers at once), the requested seconds when `wait` is a decimal integer (no sign, no leading zero) in the
+ * route's range, and `null` when the daemon refuses it with 400 `invalid_request`. A route without `minWait` ignores
+ * the query and always holds up to {@link LONG_POLL_MAX_WAIT_SECONDS}.
+ */
+export function requestedWait(route, query) {
+    if (route.minWait === undefined)
+        return LONG_POLL_MAX_WAIT_SECONDS;
+    const value = query.get('wait');
+    if (!value)
+        return 0;
+    if (!/^(0|[1-9]\d?)$/.test(value))
+        return null;
+    const seconds = Number(value);
+    return seconds >= route.minWait && seconds <= LONG_POLL_MAX_WAIT_SECONDS ? seconds : null;
+}
+/**
+ * How long the daemon may hold this request before it starts answering, in seconds — or `undefined` when it answers
+ * at once: not a long-poll route, no `wait` or `wait=0`, or a `wait` it refuses. A proxy adds its own answer deadline
+ * on top. `url` is the request target (`/v1/runs/r1?wait=25`) or a parsed URL.
+ */
+export function longPollHoldSeconds(method, url) {
+    let parsed;
+    try {
+        parsed = typeof url === 'string' ? new URL(url, 'http://daemon.localhost') : url;
+    }
+    catch {
+        return undefined;
+    }
+    const route = longPollRoute(method, parsed.pathname);
+    if (route === undefined)
+        return undefined;
+    const seconds = requestedWait(route, parsed.searchParams);
+    return seconds ? seconds : undefined;
+}

package/dist/api/node-transport.d.ts

@@ -0,0 +1,18 @@
+import { CrtrClient, type CrtrClientOptions } from './client.js';
+/** Resolve crtrd's default unix socket path the same way `apiSocketPath()` does,
+ *  via Node built-ins only (no `core/canvas/paths.ts` import). */
+export declare function defaultSocketPath(): string;
+/** A standard `fetch` bound to one unix socket, built on `node:http` with
+ *  `{ socketPath }`. The returned `Response`'s body is a live `ReadableStream`
+ *  fed as bytes arrive — never buffered before the caller sees headers —
+ *  which is what lets `CrtrClient` serve a streaming route (SSE) later without
+ *  a second transport. Connection failures are wrapped as `TypeError('fetch
+ *  failed', { cause })`, matching the shape native `fetch` throws, so
+ *  `CrtrClient`'s cold-socket/interrupted-request classification (`err.cause.code`)
+ *  reads identically off either transport. */
+export declare function socketFetch(socketPath: string): typeof fetch;
+/** Construct a client bound to the default local socket with autostart on.
+ *  Without `onColdSocket`, a cold socket fails with `daemon_unavailable`. */
+export declare function localClient(opts?: Omit<CrtrClientOptions, 'baseUrl' | 'fetch'> & {
+    socketPath?: string;
+}): CrtrClient;