@crouter/sdk 0.3.389 → 0.3.391

package/README.md

@@ -45,6 +45,23 @@ const client = new Crouter({
 });
 ```
 
+## Runtime version
+
+The SDK talks only to a runtime at or above its own version (`SDK_VERSION`), and has no compatibility mode for older ones: its types, such as `RunObject.activity`, describe what a runtime at its release sends. Every runtime answer carries a `Crouter-Runtime-Version` header. When that version is older than the SDK, or the header is missing (every runtime released before this rule shipped), the call throws `RuntimeVersionError` before the SDK reads the response: `code` is `runtime_version_unsupported`, `status` is 426, `retryable` is false, and `sdkVersion` and `runtimeVersion` name both versions. Upgrade the runtime first, then the SDK.
+
+Pin `@crouter/sdk` to an exact version. One release is one version set: `@crouter/sdk@X` depends on exactly `@crouter/api@X` and `@crouter/identity@X`, so the pin fixes all three.
+
+```ts
+import { RuntimeVersionError } from '@crouter/sdk';
+
+try {
+  await client.runs.get(runId);
+} catch (error) {
+  if (error instanceof RuntimeVersionError) console.error(`runtime ${error.runtimeVersion ?? '(unnamed)'} is older than SDK ${error.sdkVersion}`);
+  else throw error;
+}
+```
+
 ## Run and parse a result
 
 `parse()` creates a root run, waits for its outcome, and types `output_parsed` from a Zod or Standard Schema. Pass `scopes` to give a run a per-run allow-list; under a scoped token the list must stay inside the token's ceiling, and omitting it gives the run the ceiling.
@@ -97,6 +114,8 @@ const text = await client.runs.reply(runId, sent).text();
 
 To answer a first message in the run's first turn, pass it to `runs.start`: `message` is stored with the run and always joins the first turn as context ahead of `prompt`, and the result's `message` is what `runs.reply` takes. (A `runs.message(id, text, {start_turn: false})` sent after `runs.start` joins the first turn only if it is stored before the run claims that turn's messages.)
 
+`runs.message(id, text, {idempotencyKey})` sends an `Idempotency-Key` (a fresh `crypto.randomUUID()` per call, reused across the SDK's own retries). The daemon delivers a key once for 24 hours and returns the original result on replay; the same key with a different body fails with `409 idempotency_conflict`. Pass your own key, derived from your message id, to dedupe across process restarts.
+
 ```ts
 const run = await client.runs.start({prompt: instructions, message: 'Hello'});
 const {text, ended, error} = await client.runs.reply(run.run_id, run.message!).collect({onDelta: (delta) => send(delta)});

package/dist/client.js

@@ -1,4 +1,4 @@
-import { APIError, CrtrClient, routes, } from '@crouter/api';
+import { APIError, CrtrClient, RUNTIME_VERSION_HEADER, compareReleaseVersions, routes, } from '@crouter/api';
 import { APIConnectionError, APIUserAbortError, AuthenticationError, CrouterError, mapError } from './errors.js';
 import { Bash } from './resources/bash.js';
 import { Canvas } from './resources/canvas.js';
@@ -19,6 +19,7 @@ import { StructuredRequests } from './resources/structured-requests.js';
 import { Memory } from './resources/memory.js';
 import { Uploads } from './resources/uploads.js';
 import { resolveJsonSchema } from './schema.js';
+import { SDK_VERSION } from './version.js';
 const LOCAL_SOCKET_FETCH = Symbol.for('@crouter/api/local-socket-fetch');
 const DEFAULT_TIMEOUT_MS = 30_000;
 const POLL_WAIT_SECONDS = 25;
@@ -100,7 +101,7 @@ export class Crouter {
             ...options.headers,
             ...(token === undefined ? {} : { Authorization: `Bearer ${token}` }),
         };
-        const baseFetch = options.fetch ?? (baseURL === undefined && isNodeRuntime() ? localSocketFetch(options.socketPath ?? env['CRTR_SOCKET']) : fetch);
+        const baseFetch = requireCurrentRuntime(options.fetch ?? (baseURL === undefined && isNodeRuntime() ? localSocketFetch(options.socketPath ?? env['CRTR_SOCKET']) : undefined));
         this.eventFetch = options.tokenSource ? (input, init) => {
             const url = new URL(input instanceof Request ? input.url : String(input));
             if (url.pathname === '/v1/health')
@@ -125,7 +126,7 @@ export class Crouter {
                 this.socketPath = undefined;
                 this.client = new CrtrClient({
                     baseUrl: 'http://localhost',
-                    fetch: options.fetch,
+                    fetch: baseFetch,
                     headers,
                     timeoutMs: this.timeout,
                     maxRetries: options.maxRetries,
@@ -134,11 +135,10 @@ export class Crouter {
             else {
                 const socketPath = options.socketPath ?? env['CRTR_SOCKET'];
                 this.socketPath = socketPath;
-                const fetch = options.fetch ?? localSocketFetch(socketPath);
                 const autostart = options.autostart ?? true;
                 this.client = new CrtrClient({
                     baseUrl: 'http://localhost',
-                    fetch,
+                    fetch: baseFetch,
                     headers,
                     timeoutMs: this.timeout,
                     maxRetries: options.maxRetries,
@@ -467,6 +467,38 @@ function nodeEnvironment() {
 function isNodeRuntime() {
     return typeof process !== 'undefined' && process.versions?.node !== undefined;
 }
+/**
+ * Latest only (P2): the SDK accepts a runtime at or above its own release (`SDK_VERSION`) and nothing older, so its
+ * types never describe a field an older runtime does not send. Every runtime response names its release in
+ * `Crouter-Runtime-Version`; a successful answer from an older runtime, or one that names no release (every runtime
+ * before the header existed), is replaced by a 426 `runtime_version_unsupported` envelope before anything reads it,
+ * which the client raises as `RuntimeVersionError`. A refusal without the header passes through unchanged: it can come
+ * from a router or proxy in front of the runtime, and it carries no runtime data. `/healthz`, the unversioned
+ * substrate probe the cold-start wait polls, is exempt.
+ */
+function requireCurrentRuntime(inner) {
+    const checked = async (input, init) => {
+        const response = await (inner ?? globalThis.fetch)(input, init);
+        const url = new URL(input instanceof Request ? input.url : String(input), 'http://localhost');
+        if (url.pathname === '/healthz')
+            return response;
+        const runtimeVersion = response.headers.get(RUNTIME_VERSION_HEADER);
+        if (runtimeVersion === null ? !response.ok : compareReleaseVersions(runtimeVersion, SDK_VERSION) >= 0)
+            return response;
+        await response.body?.cancel();
+        const message = runtimeVersion === null
+            ? `The runtime did not name its version, so it predates the runtime version header; @crouter/sdk ${SDK_VERSION} requires a runtime at ${SDK_VERSION} or later. Upgrade the runtime, or pin @crouter/sdk to the runtime's release.`
+            : `The runtime is ${runtimeVersion}; @crouter/sdk ${SDK_VERSION} requires a runtime at ${SDK_VERSION} or later. Upgrade the runtime, or pin @crouter/sdk to ${runtimeVersion}.`;
+        return new Response(JSON.stringify({ error: {
+                code: 'runtime_version_unsupported', message, type: 'invalid_request_error', retryable: false,
+                details: { sdk_version: SDK_VERSION, runtime_version: runtimeVersion },
+            } }), { status: 426, headers: { 'content-type': 'application/json' } });
+    };
+    if (inner !== undefined && inner[LOCAL_SOCKET_FETCH] === true) {
+        checked[LOCAL_SOCKET_FETCH] = true;
+    }
+    return checked;
+}
 function localSocketFetch(socketPath) {
     const load = new Function('specifier', 'return import(specifier)');
     let fetchPromise;

package/dist/error-codes.d.ts

@@ -2,6 +2,6 @@ export { errorCodes } from '@crouter/api';
 export type { ErrorCode, ErrorEnvelope, ErrorOrigin, ErrorType } from '@crouter/api';
 export { mapError } from './errors.js';
 /** Codes the SDK raises itself rather than reading from a daemon or directory response. */
-export declare const sdkErrorCodes: readonly ["crouter_error", "id_token_invalid", "oauth_nonce_missing", "oauth_state_mismatch", "oauth_exchange_mismatch", "run_idle", "waiting_on_user", "request_aborted", "request_timeout", "connection_error", "transport_error", "daemon_unavailable", "daemon_request_interrupted", "daemon_health_unavailable", "invalid_response", "stream_error", "stream_ended"];
+export declare const sdkErrorCodes: readonly ["crouter_error", "id_token_invalid", "oauth_nonce_missing", "oauth_state_mismatch", "oauth_exchange_mismatch", "run_idle", "waiting_on_user", "request_aborted", "request_timeout", "connection_error", "transport_error", "daemon_unavailable", "daemon_request_interrupted", "daemon_health_unavailable", "runtime_version_unsupported", "invalid_response", "stream_error", "stream_ended"];
 /** A code the SDK raises itself. An `APIError`'s `code` is one of these or an `ErrorCode` from the contract. */
 export type SdkErrorCode = typeof sdkErrorCodes[number];

package/dist/error-codes.js

@@ -27,6 +27,8 @@ export const sdkErrorCodes = [
     'daemon_unavailable',
     'daemon_request_interrupted',
     'daemon_health_unavailable',
+    /** The runtime is older than this SDK, or sent no `Crouter-Runtime-Version` (`RuntimeVersionError`). */
+    'runtime_version_unsupported',
     /** A response the SDK could not read as the API's JSON or error envelope. */
     'invalid_response',
     /** An event stream failed, or ended before the reply or node it carried did. */

package/dist/errors.d.ts

@@ -6,6 +6,20 @@ export declare class CrouterError extends APIError {
     readonly code: SdkErrorCode;
     constructor(message: string, code?: SdkErrorCode);
 }
+/** The runtime is older than this SDK (or names no version at all), so the SDK's types do not describe what it
+ *  sends. Raised before the SDK reads the response; never retryable. Upgrade the runtime (or pin the SDK to the
+ *  runtime's release). `code` is `runtime_version_unsupported`, `status` 426. */
+export declare class RuntimeVersionError extends APIError {
+    /** The oldest runtime this SDK accepts: its own release version. */
+    get sdkVersion(): string;
+    /** The version the runtime named in `Crouter-Runtime-Version`, or `null` when it sent none (a runtime from before the header existed). */
+    get runtimeVersion(): string | null;
+}
+/** `RuntimeVersionError.details`. */
+export interface RuntimeVersionDetails {
+    sdk_version: string;
+    runtime_version: string | null;
+}
 /** The daemon rejected the request: HTTP 400. */
 export declare class BadRequestError extends APIError {
 }

package/dist/errors.js

@@ -7,6 +7,15 @@ export class CrouterError extends APIError {
         this.name = 'CrouterError';
     }
 }
+/** The runtime is older than this SDK (or names no version at all), so the SDK's types do not describe what it
+ *  sends. Raised before the SDK reads the response; never retryable. Upgrade the runtime (or pin the SDK to the
+ *  runtime's release). `code` is `runtime_version_unsupported`, `status` 426. */
+export class RuntimeVersionError extends APIError {
+    /** The oldest runtime this SDK accepts: its own release version. */
+    get sdkVersion() { return this.details.sdk_version; }
+    /** The version the runtime named in `Crouter-Runtime-Version`, or `null` when it sent none (a runtime from before the header existed). */
+    get runtimeVersion() { return this.details.runtime_version; }
+}
 /** The daemon rejected the request: HTTP 400. */
 export class BadRequestError extends APIError {
 }
@@ -45,29 +54,31 @@ export function mapError(error) {
     if (!(error instanceof APIError) || error.constructor !== APIError) {
         return error instanceof APIError ? error : new APIConnectionError(0, 'connection_error', error instanceof Error ? error.message : String(error));
     }
-    const Constructor = error.code === 'request_aborted'
-        ? APIUserAbortError
-        : error.status === 504 || error.code === 'request_timeout'
-            ? APIConnectionTimeoutError
-            : error.code === 'daemon_unavailable' || error.code === 'transport_error' || error.code === 'daemon_request_interrupted' || error.code === 'daemon_health_unavailable'
-                ? APIConnectionError
-                : error.status === 400
-                    ? BadRequestError
-                    : error.status === 401
-                        ? AuthenticationError
-                        : error.status === 403
-                            ? PermissionDeniedError
-                            : error.status === 404
-                                ? NotFoundError
-                                : error.status === 409
-                                    ? ConflictError
-                                    : error.status === 413 || error.status === 422
-                                        ? UnprocessableEntityError
-                                        : error.status === 402 || error.status === 429
-                                            ? RateLimitError
-                                            : error.status >= 500
-                                                ? InternalServerError
-                                                : APIError;
+    const Constructor = error.code === 'runtime_version_unsupported'
+        ? RuntimeVersionError
+        : error.code === 'request_aborted'
+            ? APIUserAbortError
+            : error.status === 504 || error.code === 'request_timeout'
+                ? APIConnectionTimeoutError
+                : error.code === 'daemon_unavailable' || error.code === 'transport_error' || error.code === 'daemon_request_interrupted' || error.code === 'daemon_health_unavailable'
+                    ? APIConnectionError
+                    : error.status === 400
+                        ? BadRequestError
+                        : error.status === 401
+                            ? AuthenticationError
+                            : error.status === 403
+                                ? PermissionDeniedError
+                                : error.status === 404
+                                    ? NotFoundError
+                                    : error.status === 409
+                                        ? ConflictError
+                                        : error.status === 413 || error.status === 422
+                                            ? UnprocessableEntityError
+                                            : error.status === 402 || error.status === 429
+                                                ? RateLimitError
+                                                : error.status >= 500
+                                                    ? InternalServerError
+                                                    : APIError;
     return new Constructor(error.status, error.code, error.message, error.details, error.headers, {
         type: error.type, param: error.param, origin: error.origin, retryable: error.retryable,
         retry_after_s: error.retryAfterS, reset_at: error.resetAt, request_id: error.requestId, run_id: error.runId,

package/dist/index.d.ts

@@ -26,7 +26,9 @@ export { cursorFromRequest, forwardRunEvents } from './resources/forward.js';
 export type { NodeStreamEvent, NodeStreamEventListener, NodeStreamEventType } from './resources/node-stream.js';
 export { describeToolDefault, followActivity } from './resources/activity.js';
 export type { ActivityStep, DescribeTool } from './resources/activity.js';
-export { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, ConflictError, CrouterError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, UnprocessableEntityError, mapError, } from './errors.js';
+export { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, ConflictError, CrouterError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, RuntimeVersionError, UnprocessableEntityError, mapError, } from './errors.js';
+export type { RuntimeVersionDetails } from './errors.js';
+export { SDK_VERSION } from './version.js';
 export { sdkErrorCodes } from './error-codes.js';
 export type { SdkErrorCode } from './error-codes.js';
 export type { AuthStatus, AuthStatusParams, CancelParams, EnsureProfileParams, JsonSchema, MessageParams, NodeCreateParams, NodeEventsOptions, NodeOutcomeOptions, OutputSchema, ParsedOutcome, RequestOptions, SchemaOutput, } from './types.js';

package/dist/index.js

@@ -9,5 +9,6 @@ export { generateKeyPair } from './oauth/keygen.js';
 export { parsePrivateJwk, privateKeyFromFile } from './oauth/keygen.js';
 export { cursorFromRequest, forwardRunEvents } from './resources/forward.js';
 export { describeToolDefault, followActivity } from './resources/activity.js';
-export { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, ConflictError, CrouterError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, UnprocessableEntityError, mapError, } from './errors.js';
+export { APIError, APIConnectionError, APIConnectionTimeoutError, APIUserAbortError, AuthenticationError, BadRequestError, ConflictError, CrouterError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, RuntimeVersionError, UnprocessableEntityError, mapError, } from './errors.js';
+export { SDK_VERSION } from './version.js';
 export { sdkErrorCodes } from './error-codes.js';

package/dist/resources/run-stream.js

@@ -1,4 +1,4 @@
-import { APIError, APIUserAbortError } from '../errors.js';
+import { APIError, APIUserAbortError, mapError } from '../errors.js';
 /** A resumable run event stream. Closing it does not stop the run. */
 export class RunStream {
     open;
@@ -202,5 +202,5 @@ export class RunStream {
 async function streamResponseError(response) {
     const payload = await response.json();
     const error = payload.error;
-    return new APIError(response.status, error?.code ?? 'invalid_response', error?.message ?? `HTTP ${response.status}`, error?.details, response.headers, error);
+    return mapError(new APIError(response.status, error?.code ?? 'invalid_response', error?.message ?? `HTTP ${response.status}`, error?.details, response.headers, error));
 }

package/dist/resources/runs.d.ts

@@ -138,9 +138,16 @@ export declare class Runs {
      *  `start_turn: false` stores it without starting a turn; it is delivered as
      *  context at the start of the next turn, ahead of that turn's input. For a
      *  new run that is the first turn only if it is stored before the run claims
-     *  its first turn's messages; to guarantee it, pass `message` to `runs.start`. */
+     *  its first turn's messages; to guarantee it, pass `message` to `runs.start`.
+     *
+     *  The send carries an `Idempotency-Key`: `idempotencyKey` when given, otherwise a UUID generated for this
+     *  call and reused on every retry of it. The daemon keeps the key for 24 hours; a repeat with the same key
+     *  and the same message returns the first send's result without delivering again, and the same key with a
+     *  different message or `start_turn` throws `ConflictError` `idempotency_conflict`. To make a send safe
+     *  across your own restarts, derive the key from your own record of the send (a batch or row id). */
     message(runId: string, message: string, options?: RequestOptions & {
         start_turn?: boolean;
+        idempotencyKey?: string;
     }): Promise<SentRunMessage>;
     interrupt(runId: string, options?: RequestOptions & {
         children?: 'stop' | 'continue';

package/dist/resources/runs.js

@@ -19,8 +19,7 @@ export class Runs {
                 return await this.request('POST', '/v1/runs', body, { ...rest, maxRetries: 0, headers: { ...rest.headers, 'Idempotency-Key': idempotencyKey } });
             }
             catch (error) {
-                if (attempt >= maxRetries || !(error instanceof APIError) ||
-                    !(error.retryable === true || error.code === 'transport_error' || error.code === 'daemon_request_interrupted' || error.code === 'connection_error' || error.code === 'request_timeout'))
+                if (attempt >= maxRetries || !(error instanceof APIError) || !retryableSend(error))
                     throw error;
                 await pause(error.retryAfterS ? error.retryAfterS * 1_000 : 500 * 2 ** attempt, rest.signal);
             }
@@ -53,15 +52,24 @@ export class Runs {
      *  `start_turn: false` stores it without starting a turn; it is delivered as
      *  context at the start of the next turn, ahead of that turn's input. For a
      *  new run that is the first turn only if it is stored before the run claims
-     *  its first turn's messages; to guarantee it, pass `message` to `runs.start`. */
+     *  its first turn's messages; to guarantee it, pass `message` to `runs.start`.
+     *
+     *  The send carries an `Idempotency-Key`: `idempotencyKey` when given, otherwise a UUID generated for this
+     *  call and reused on every retry of it. The daemon keeps the key for 24 hours; a repeat with the same key
+     *  and the same message returns the first send's result without delivering again, and the same key with a
+     *  different message or `start_turn` throws `ConflictError` `idempotency_conflict`. To make a send safe
+     *  across your own restarts, derive the key from your own record of the send (a batch or row id). */
     async message(runId, message, options = {}) {
-        const { maxRetries = 2, start_turn, ...rest } = options;
+        const { idempotencyKey = crypto.randomUUID(), maxRetries = 2, start_turn, ...rest } = options;
+        const body = { message, ...(start_turn === undefined ? {} : { start_turn }) };
+        // One key per logical send, reused on every retry: the daemon answers a repeat with the first send's
+        // result, so a retry after a lost response cannot deliver the message twice.
         for (let attempt = 0;; attempt++) {
             try {
-                return await this.request('POST', `${runPath(runId)}/messages`, { message, ...(start_turn === undefined ? {} : { start_turn }) }, { ...rest, maxRetries: 0 });
+                return await this.request('POST', `${runPath(runId)}/messages`, body, { ...rest, maxRetries: 0, headers: { ...rest.headers, 'Idempotency-Key': idempotencyKey } });
             }
             catch (error) {
-                if (attempt >= maxRetries || !(error instanceof APIError) || error.retryable !== true || error.status === 0)
+                if (attempt >= maxRetries || !(error instanceof APIError) || !retryableSend(error))
                     throw error;
                 await pause(error.retryAfterS ? error.retryAfterS * 1_000 : 500 * 2 ** attempt, rest.signal);
             }
@@ -162,6 +170,10 @@ export class Runs {
         }
     }
 }
+/** A keyed send is safe to repeat after a refusal the daemon marked retryable or a transport failure. */
+function retryableSend(error) {
+    return error.retryable === true || error.code === 'transport_error' || error.code === 'daemon_request_interrupted' || error.code === 'connection_error' || error.code === 'request_timeout';
+}
 function runPath(id) {
     if (!/^[A-Za-z0-9_-]+$/.test(id))
         throw new TypeError('Invalid run id');

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+/** This SDK's release version. It is also the oldest runtime the SDK accepts: one release is one version set. */
+export declare const SDK_VERSION = "0.3.391";

package/dist/version.js

@@ -0,0 +1,3 @@
+// Written by scripts/release-version.mjs on every release; do not edit by hand.
+/** This SDK's release version. It is also the oldest runtime the SDK accepts: one release is one version set. */
+export const SDK_VERSION = '0.3.391';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouter/sdk",
-  "version": "0.3.389",
+  "version": "0.3.391",
   "description": "Typed Node and browser client for running crouter agents through the crtrd /v1 API.",
   "type": "module",
   "main": "./dist/index.js",
@@ -31,8 +31,8 @@
     "build": "tsc -p tsconfig.json && chmod 755 dist/keygen-cli.js"
   },
   "dependencies": {
-    "@crouter/api": "^0.3.389",
-    "@crouter/identity": "^0.3.389",
+    "@crouter/api": "0.3.391",
+    "@crouter/identity": "0.3.391",
     "jose": "^6.2.1"
   },
   "peerDependencies": {