@crouter/sdk 0.3.389 → 0.3.390

package/README.md

@@ -97,6 +97,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crouter/sdk",
-  "version": "0.3.389",
+  "version": "0.3.390",
   "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.390",
+    "@crouter/identity": "^0.3.390",
     "jose": "^6.2.1"
   },
   "peerDependencies": {