@crouter/api 0.3.382 → 0.3.383

package/dist/api/__tests__/error-codes.test.js

@@ -14,6 +14,7 @@ test('SDK and API expose one fixed code table with contract 2 tuples', () => {
     for (const code of ['grant_revoked', 'grant_removed', 'grant_suspended', 'refresh_token_expired', 'refresh_token_reused']) {
         assert.deepEqual(errorCodes[code], { type: 'authentication_error', status: 401, retryable: false }, code);
     }
+    assert.deepEqual(errorCodes.provider_setup_pending, { type: 'permission_error', status: 403, retryable: false });
     assert.equal('provider_error' in errorCodes, false); // provider's 4xx status varies
     assert.equal('usage' in errorCodes, false); // legacy socket-only code
     assert.equal('stream_gap' in errorCodes, false); // stream protocol, not a fixed HTTP row

package/dist/api/client.d.ts

@@ -7,6 +7,7 @@ import type { NodeEventsQuery } from './dto/node-events.js';
 import type { BrokerSignalLineDTO } from './dto/broker-signals.js';
 import type { NodeLogAppendRequest, NodeLogAppendResultDTO, NodeTelemetryRecordRequest, NodeRecapRecordRequest, NodeMessageBodyDTO, NodePushedFinalRequest, NodePushedFinalResultDTO } from './dto/node-records.js';
 import type { InterruptResultDTO, MessageResultDTO, SendMessageRequest } from './dto/messages.js';
+import type { CreateStructuredRequest, CreateStructuredRequestResponse, StructuredRequestDTO } from './dto/structured-requests.js';
 import type { PushReportRequest, PushReportResultDTO, ReportDTO, ReportsQuery, SubmitResultDTO, SubmitResultRequest } from './dto/reports.js';
 import type { CloseRequest, CloseResultDTO, PromoteRequest, RelaunchRootResultDTO, ReviveRequest, ReviveResultDTO, WaitRequest, YieldRequest } from './dto/lifecycle.js';
 import type { SubscribeRequest, SubscriptionDTO } from './dto/subscriptions.js';
@@ -78,6 +79,10 @@ export interface CrtrRequestOptions {
     signal?: AbortSignal;
     timeout?: number;
     maxRetries?: number;
+    /** Limits the full call — every attempt, response body, and cold-socket or
+     * interrupted-response recovery — to one wall-clock budget, without changing
+     * the client's default inactivity timeout. */
+    budgetMs?: number;
 }
 export declare class CrtrClient {
     private readonly baseUrl;
@@ -128,6 +133,12 @@ export declare class CrtrClient {
     /** Parsed NDJSON hints, consumed eagerly and line by line. The caller must
      * cancel with `signal` when done; no wall-clock timeout applies to the stream. */
     getBrokerSignals(id: string, executionId: string, options?: Omit<CrtrRequestOptions, 'timeout'>): AsyncIterable<BrokerSignalLineDTO>;
+    createStructuredRequest(req: CreateStructuredRequest, options?: CrtrRequestOptions): Promise<CreateStructuredRequestResponse>;
+    getStructuredRequest(requestId: string, { wait, budgetMs }?: {
+        wait?: number;
+        budgetMs?: number;
+    }): Promise<StructuredRequestDTO>;
+    cancelStructuredRequest(requestId: string, options?: CrtrRequestOptions): Promise<StructuredRequestDTO>;
     /** Register or replace an armed target for terminal-outcome delivery. */
     registerOutcomeDelivery(id: string, req: RegisterOutcomeDeliveryRequest): Promise<OutcomeDeliveryDTO>;
     getOutcomeDelivery(id: string): Promise<OutcomeDeliveryDTO>;
@@ -417,6 +428,10 @@ export declare class CrtrClient {
      *  only — POST/PATCH are never replayed once a request has actually been
      *  sent). No JSON parse; every wrapper goes through here. */
     private send;
+    private resolveBudget;
+    private awaitWithinBudget;
+    /** One transport attempt, deliberately without retry, cold-socket, or interrupted-response recovery. */
+    private sendOnce;
     private nodePath;
     /** Validate a background job id before route construction. Job ids arrive
      *  from the daemon's file-backed roster and must remain one path segment. */

package/dist/api/client.js

@@ -37,6 +37,7 @@ export async function waitForDaemonAvailability({ windowMs, probe, initialError,
         await sleep(Math.min(pollIntervalMs, afterProbe));
     }
 }
+const budgetExhausted = () => Object.assign(new Error('request budget exhausted'), { code: 'ETIMEDOUT' });
 export class CrtrClient {
     baseUrl;
     fetch;
@@ -193,6 +194,24 @@ export class CrtrClient {
             await reader.cancel().catch(() => { });
         }
     }
+    // Structured requests
+    createStructuredRequest(req, options) {
+        // A synchronous admission is one held exchange. Replaying a POST after a
+        // reset can create work the caller has already stopped waiting for, and
+        // cold-socket recovery consumes its fixed end-to-end budget.
+        if (req.mode === 'sync')
+            return this.sendOnce('POST', '/v1/structured-requests', req, options);
+        return this.request('POST', '/v1/structured-requests', req, options);
+    }
+    getStructuredRequest(requestId, { wait = 0, budgetMs } = {}) {
+        if (!Number.isInteger(wait) || wait < 0 || wait > 25) {
+            throw new RangeError('wait must be an integer between 0 and 25');
+        }
+        return this.request('GET', withQuery(`/v1/structured-requests/${this.requestPath(requestId)}`, { wait }), undefined, { budgetMs });
+    }
+    cancelStructuredRequest(requestId, options) {
+        return this.request('POST', `/v1/structured-requests/${this.requestPath(requestId)}/cancel`, {}, options);
+    }
     /** Register or replace an armed target for terminal-outcome delivery. */
     registerOutcomeDelivery(id, req) {
         return this.request('PUT', routes.nodeOutcomeDelivery(this.nodePath(id)), req);
@@ -808,7 +827,8 @@ export class CrtrClient {
      *  the §7 retry policy (connection errors and 429/5xx on GET/HEAD/DELETE
      *  only — POST/PATCH are never replayed once a request has actually been
      *  sent). No JSON parse; every wrapper goes through here. */
-    async send(method, path, body, opts = {}) {
+    async send(method, path, body, callOpts = {}) {
+        const opts = this.resolveBudget(callOpts);
         const idempotent = method === 'GET' || method === 'HEAD' || method === 'DELETE';
         const maxRetries = opts.maxRetries ?? this.maxRetries;
         for (let attempt = 0;; attempt++) {
@@ -819,7 +839,7 @@ export class CrtrClient {
             catch (err) {
                 if (this.isColdSocketError(err)) {
                     try {
-                        await this.handleColdSocket(err);
+                        await this.handleColdSocket(err, opts.deadlineAt);
                         response = await this.transport(method, path, body, opts);
                     }
                     catch (recoveryError) {
@@ -846,6 +866,42 @@ export class CrtrClient {
         }
     }
     // internals
+    resolveBudget(opts) {
+        const { budgetMs, ...rest } = opts;
+        if (budgetMs === 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 };
+    }
+    async awaitWithinBudget(promise, deadlineAt) {
+        if (deadlineAt === undefined)
+            return promise;
+        const remainingMs = deadlineAt - Date.now();
+        if (remainingMs <= 0)
+            throw budgetExhausted();
+        let timer;
+        try {
+            return await Promise.race([
+                promise,
+                new Promise((_resolve, reject) => { timer = setTimeout(() => reject(budgetExhausted()), remainingMs); }),
+            ]);
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+        }
+    }
+    /** One transport attempt, deliberately without retry, cold-socket, or interrupted-response recovery. */
+    async sendOnce(method, path, body, callOpts = {}) {
+        const opts = this.resolveBudget(callOpts);
+        try {
+            return await parse(await this.transport(method, path, body, opts));
+        }
+        catch (error) {
+            throw toTransportApiError(error, opts.signal);
+        }
+    }
     nodePath(id) {
         if (!isSafeNodeId(id)) {
             throw new ApiError(400, 'invalid_node_id', `invalid node id: ${JSON.stringify(id)}`);
@@ -913,11 +969,17 @@ export class CrtrClient {
      *  stays an unread `ReadableStream` on the returned `Response`, so a caller
      *  that wants to stream (SSE, later) never waits on a buffered body. */
     transport(method, path, body, opts = {}) {
+        const remainingBudgetMs = opts.deadlineAt === undefined ? undefined : opts.deadlineAt - Date.now();
+        if (remainingBudgetMs !== undefined && remainingBudgetMs <= 0)
+            return Promise.reject(budgetExhausted());
         const payload = body === undefined ? undefined : JSON.stringify(body);
         const headers = { accept: 'application/json', ...this.headers, ...opts.headers };
         if (payload !== undefined)
             headers['content-type'] = 'application/json';
-        const timeoutMs = opts.timeout ?? this.timeoutMs;
+        const baseTimeoutMs = opts.timeout ?? this.timeoutMs;
+        const timeoutMs = remainingBudgetMs === undefined
+            ? baseTimeoutMs
+            : baseTimeoutMs > 0 ? Math.min(baseTimeoutMs, remainingBudgetMs) : remainingBudgetMs;
         const controller = new AbortController();
         const timer = timeoutMs > 0
             ? setTimeout(() => controller.abort(new DOMException('request timed out', 'TimeoutError')), timeoutMs)
@@ -993,7 +1055,7 @@ export class CrtrClient {
      * it never replays. */
     async rideOutInterruptedRequest(method, path, body, opts = {}) {
         try {
-            await this.awaitAvailability();
+            await this.awaitAvailability(undefined, opts.deadlineAt);
         }
         catch (error) {
             throw toTransportApiError(error, opts.signal);
@@ -1008,9 +1070,12 @@ export class CrtrClient {
             throw toTransportApiError(err, opts.signal);
         }
     }
-    async awaitAvailability(initialError) {
+    async awaitAvailability(initialError, deadlineAt) {
+        const remainingBudgetMs = deadlineAt === undefined ? undefined : deadlineAt - Date.now();
+        if (remainingBudgetMs !== undefined && remainingBudgetMs <= 0)
+            throw budgetExhausted();
         await waitForDaemonAvailability({
-            windowMs: this.coldStartPollWindowMs,
+            windowMs: Math.min(this.coldStartPollWindowMs, remainingBudgetMs ?? this.coldStartPollWindowMs),
             initialError,
             probe: async (timeoutMs) => {
                 const response = await this.transport('GET', routes.healthz(), undefined, { timeout: timeoutMs });
@@ -1034,14 +1099,14 @@ export class CrtrClient {
     /** Optionally start the daemon, then observe availability before retrying the
      * request. Waiting is independent from permission to spawn: externally
      * managed daemons still get the same bounded readiness window. */
-    async handleColdSocket(initialError) {
+    async handleColdSocket(initialError, deadlineAt) {
         const startedHere = this.autostart && this.onColdSocket !== undefined && !this.coldStartAttempted;
         if (startedHere) {
             this.coldStartAttempted = true;
-            await this.onColdSocket();
+            await this.awaitWithinBudget(this.onColdSocket(), deadlineAt);
         }
         try {
-            await this.awaitAvailability(initialError);
+            await this.awaitAvailability(initialError, deadlineAt);
         }
         catch (error) {
             if (startedHere) {

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

@@ -1,3 +1,5 @@
+/** A provider's setup state for the account (directory spec, "Provider setup state"). */
+export type SetupState = 'not_started' | 'pending' | 'ready' | 'failed';
 export interface GrantGetDTO {
     sub: string;
     grantee: string;
@@ -11,4 +13,6 @@ export interface GrantGetDTO {
     }[];
     spend_cap: number | null;
     payer: 'user';
+    /** `{ <provider id>: <setup state> }` as the directory's grant sync carried it; `{}` when the grantee has none. The daemon performs no `requires` check: an app polls this and refuses its own operation with `provider_setup_pending`. */
+    dependencies: Record<string, SetupState>;
 }

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

@@ -69,6 +69,9 @@ export interface CreateNodeRequest {
      *  validated and duplicate-rejected server-side (`NodeIdConflictError` →
      *  HTTP 409 `node_id_exists`). See `crtr node new --node-id`. */
     node_id?: string;
+    /** Opaque key generated once per create attempt. A repeated key returns the
+     *  node created by its first served request. */
+    request_key?: string;
     /** Serve this create from the warm pool when a pre-booted spare matches the
      *  request's frozen launch tuple (kind, mode, resolved cwd, profile, model,
      *  situational_context) — answering in milliseconds instead of waiting out a

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

@@ -40,20 +40,22 @@ export interface DeclinedResultDTO {
     code: string;
     retryable: boolean;
 }
-/** `POST /v1/nodes/{id}/result` body ({id} = the submitting node). Either the
- *  structured result to validate against the node's pending output schema —
- *  `value` must be present; any JSON value (including null) is legal input to
- *  validation — or a decline: `decline` is the reason sentence, `code` the
- *  requester-classified token, `retryable` the node's retry claim. A decline
- *  records a `failure` outcome with reason `declined` carrying all three and
- *  clears the request without validating anything. */
+/** `POST /v1/nodes/{id}/result` body ({id} = the submitting node). `request_id`
+ *  identifies the pending structured request. Either `value` is validated
+ *  against that request's schema — any JSON value (including null) is legal
+ *  input — or a decline carries the reason sentence, requester-classified
+ *  code, and retry claim. A decline records a `failure` outcome with reason
+ *  `declined` carrying all three and clears the request without validating
+ *  anything. */
 export type SubmitResultRequest = {
+    request_id: string;
+} & ({
     value: unknown;
 } | {
     decline: string;
     code: string;
     retryable: boolean;
-};
+});
 /** Result of a structured-result submission (`crtr push result`). Terminal
  *  mode reuses the final-push machinery, so `transitioned` and the managed-worktree
  *  closure fields carry the same meaning as on PushReportResultDTO. */

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

@@ -0,0 +1,64 @@
+import type { NodeOutcomeDetailV1 } from './node-outcomes.js';
+import type { CreateNodeRequest } from './nodes.js';
+import type { IsoTime, NodeIdDTO, TerminalReasonDTO } from './common.js';
+import type { DeclinedResultDTO } from './reports.js';
+/** Fixed end-to-end work allowance for synchronous structured requests. */
+export declare const SYNC_WORK_BUDGET_MS = 60000;
+/** Local transport time retained after a synchronous request's work deadline. */
+export declare const TRANSPORT_MARGIN_MS = 5000;
+export type StructuredRequestModeDTO = 'sync' | 'async';
+export type StructuredRequestSubmissionDTO = 'terminal' | 'oneoff';
+export type StructuredRequestStateDTO = 'pending' | 'completed' | 'declined' | 'expired' | 'canceled' | 'failed';
+/** A JSON Schema object. Schema interpretation and validation are daemon-owned. */
+export type JsonSchemaDTO = Record<string, unknown>;
+/** Reasons that can fail a structured request before or after its node starts. */
+export type StructuredFailureReasonDTO = TerminalReasonDTO | 'node_create_failed' | 'bind_failed' | 'prompt_delivery_failed' | 'node_deadline_exceeded';
+export interface StructuredRequestFailureDTO {
+    reason: StructuredFailureReasonDTO;
+    detail: NodeOutcomeDetailV1 | null;
+}
+/** Durable authoritative state for one structured request. */
+export interface StructuredRequestDTO {
+    request_id: string;
+    node_id: NodeIdDTO | null;
+    mode: StructuredRequestModeDTO;
+    submission: StructuredRequestSubmissionDTO;
+    state: StructuredRequestStateDTO;
+    created_at: IsoTime;
+    deadline_at: IsoTime | null;
+    settled_at: IsoTime | null;
+    result: unknown | null;
+    declined: DeclinedResultDTO | null;
+    failure: StructuredRequestFailureDTO | null;
+}
+export type CreateStructuredRequestTarget = {
+    kind: 'new';
+    create: CreateNodeRequest;
+} | {
+    kind: 'node';
+    node_id: NodeIdDTO;
+};
+/** `POST /v1/structured-requests` body. */
+export interface CreateStructuredRequest {
+    request_id: string;
+    mode: StructuredRequestModeDTO;
+    target: CreateStructuredRequestTarget;
+    output_schema: JsonSchemaDTO;
+    prompt: string;
+    /** An absolute deadline propagated unchanged by callers that already have one. */
+    deadline_at?: IsoTime;
+    /** Requested duration only when establishing a deadline. */
+    work_budget_ms?: number;
+}
+/** An honest admission response: no request record exists when admission runs out of budget. */
+export type CreateStructuredRequestResponse = {
+    admitted: true;
+    request: StructuredRequestDTO;
+} | {
+    admitted: false;
+    reason: 'work_budget_exhausted';
+};
+/** `GET /v1/structured-requests/{request_id}` query. */
+export interface ReadStructuredRequestQuery {
+    wait?: number;
+}

package/dist/api/dto/structured-requests.js

@@ -0,0 +1,5 @@
+// Structured-request API DTOs.
+/** Fixed end-to-end work allowance for synchronous structured requests. */
+export const SYNC_WORK_BUDGET_MS = 60_000;
+/** Local transport time retained after a synchronous request's work deadline. */
+export const TRANSPORT_MARGIN_MS = 5_000;

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

@@ -69,6 +69,11 @@ export declare const errorCodes: {
         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;

package/dist/api/error-codes.js

@@ -18,6 +18,8 @@ export const errorCodes = {
     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, next }`, `next` = `<issuer>/connect/setup/<provider>`. 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 },

package/dist/api/index.d.ts

@@ -17,6 +17,7 @@ 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';

package/dist/api/index.js

@@ -17,6 +17,7 @@ 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';

package/dist/shared/generated-context.d.ts

@@ -18,7 +18,7 @@ export declare const CONNECTION_FAULT_RECOVERY_BODY = "The network connection is
 export declare const PROVIDER_FAULT_RECOVERY_BODY = "Your previous turn stopped on a provider fault. Continue from where you left off and retry the work that failed.";
 export type ModelFallbackRecoveryReason = 'credential' | 'not-found';
 /** Format the stop guard's dynamic structured-output mandate. */
-export declare function formatStructuredOutputReprompt(schema: string): string;
+export declare function formatStructuredOutputReprompt(schema: string, requestId: string): string;
 /** Keep model-fallback guidance editable without making it a reader contract. */
 export declare function formatModelFallbackRecovery(previousModel: string, nextModel: string, reason: ModelFallbackRecoveryReason): string;
 export interface GeneratedContextMessageLike {

package/dist/shared/generated-context.js

@@ -29,11 +29,11 @@ const REVIEW_APPROVAL_OPEN = '<crtr-review-approval>';
 const REVIEW_APPROVAL_CLOSE = '</crtr-review-approval>';
 const MODEL_FALLBACK_RECOVERY_OPEN = '<model-fallback-recovery>';
 const MODEL_FALLBACK_RECOVERY_CLOSE = '</model-fallback-recovery>';
-const STRUCTURED_OUTPUT_REPROMPT_PREFIX = 'You must submit a result matching the required schema with `crtr push result` before you can stop, or decline it with `crtr push result --decline "<reason>" --code <token>` when the schema cannot be honestly satisfied. You cannot finish or go dormant any other way while this request is pending.\n\nRequired schema:\n\n```json\n';
 const STRUCTURED_OUTPUT_REPROMPT_SUFFIX = '\n```';
 /** Format the stop guard's dynamic structured-output mandate. */
-export function formatStructuredOutputReprompt(schema) {
-    return `${STRUCTURED_OUTPUT_REPROMPT_PREFIX}${schema}${STRUCTURED_OUTPUT_REPROMPT_SUFFIX}`;
+export function formatStructuredOutputReprompt(schema, requestId) {
+    const submit = `crtr push result --request ${requestId}`;
+    return `You must submit a result matching the required schema with \`${submit}\` before you can stop, or decline it with \`${submit} --decline "<reason>" --code <token>\` when the schema cannot be honestly satisfied. You cannot finish or go dormant any other way while this request is pending.\n\nRequired schema:\n\n\`\`\`json\n${schema}${STRUCTURED_OUTPUT_REPROMPT_SUFFIX}`;
 }
 /** Keep model-fallback guidance editable without making it a reader contract. */
 export function formatModelFallbackRecovery(previousModel, nextModel, reason) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouter/api",
-  "version": "0.3.382",
+  "version": "0.3.383",
   "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",