@north-light/sdk 0.3.576 → 0.3.578

package/README.md

@@ -116,7 +116,7 @@ console.log(outcome.kind);
 
 ## Follow the reply to a message
 
-On a run, `runs.reply(runId, sent)` follows the turn that answers one `runs.message` and ends when that turn completes. `turn.completed.error` reports a refused (`content_refused`) or failed (`model_error`) model call.
+On a run, `runs.reply(runId, sent)` follows the turn that answers one `runs.message` and ends when that turn completes. `turn.completed.error` reports a refused (`content_refused`), failed (`model_error`) or rate-limited (`rate_limited`, with `retry_at`) model call.
 
 ```ts
 const sent = await client.runs.message(runId, 'Hello');

package/dist/resources/run-reply.d.ts

@@ -61,7 +61,7 @@ export interface RunReplyCollectOptions {
 /**
  * The reply to one message: the root's turn that delivers it. Consume it once:
  * iterate it, or call `collect()` (text plus how it ended, with an optional
- * `onDelta` while it streams) or `text()`. It ends after `turn.completed` (or `run.settled`) and
+ * `onDelta` while it streams) or `text()`. If a later message joins the same turn, text after that message belongs to its reply; this reply still waits for the turn to complete. Messages delivered together share the reply. It ends after `turn.completed` (or `run.settled`) and
  * closes its event stream; aborting the `signal` rejects with `APIUserAbortError`.
  */
 export declare class RunReply implements AsyncIterable<RunReplyEvent> {

package/dist/resources/run-reply.js

@@ -2,7 +2,7 @@ import { APIError } from '../errors.js';
 /**
  * The reply to one message: the root's turn that delivers it. Consume it once:
  * iterate it, or call `collect()` (text plus how it ended, with an optional
- * `onDelta` while it streams) or `text()`. It ends after `turn.completed` (or `run.settled`) and
+ * `onDelta` while it streams) or `text()`. If a later message joins the same turn, text after that message belongs to its reply; this reply still waits for the turn to complete. Messages delivered together share the reply. It ends after `turn.completed` (or `run.settled`) and
  * closes its event stream; aborting the `signal` rejects with `APIUserAbortError`.
  */
 export class RunReply {
@@ -19,6 +19,8 @@ export class RunReply {
         this.consumed = true;
         let stream = this.open(this.sent.sequence_number);
         let inTurn = false;
+        let textEnded = false;
+        let startingIds = new Set();
         try {
             for (;;) {
                 for await (const event of stream) {
@@ -30,11 +32,15 @@ export class RunReply {
                     }
                     if (!inTurn) {
                         inTurn = event.type === 'node.turn.started' && event.input.message_ids.includes(this.sent.message_id);
+                        if (inTurn && event.type === 'node.turn.started')
+                            startingIds = new Set(event.input.message_ids);
                         continue;
                     }
-                    if (event.type === 'node.output_text.delta')
+                    if (event.type === 'node.turn.started' && event.input.message_ids.some((id) => !startingIds.has(id)))
+                        textEnded = true;
+                    if (!textEnded && event.type === 'node.output_text.delta')
                         yield { type: 'text.delta', delta: event.delta, sequence_number: event.sequence_number };
-                    else if (event.type === 'node.output_text.done')
+                    else if (!textEnded && event.type === 'node.output_text.done')
                         yield { type: 'message.done', text: event.text, stop_reason: event.stop_reason, sequence_number: event.sequence_number };
                     else if (event.type === 'node.turn.completed') {
                         yield {

package/dist/resources/runs.d.ts

@@ -155,8 +155,9 @@ export declare class Runs {
         limit?: number;
     }, options?: RequestOptions): AsyncGenerator<RunObject, void, undefined>;
     /** Send a message to a run. `start_turn: true` (the default) answers it in its
-     *  own turn: a running run receives it when its current turn ends, and a
-     *  message sent before the first turn has started queues behind that turn,
+     *  turn. A running run reads it at its next step unless `steer: false` opts out
+     *  and waits for the current turn to end. A message sent before the first turn
+     *  has started queues behind that turn,
      *  because a run's `runs.start` prompt is always its first turn's input.
      *  `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
@@ -166,10 +167,11 @@ export declare class Runs {
      *  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
+     *  different message, `start_turn`, or effective `steer` 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;
+        steer?: boolean;
         idempotencyKey?: string;
     }): Promise<SentRunMessage>;
     /** A keyed POST under one overall deadline. `budgetMs` / `deadlineAt` (fixed here, once) bound every attempt, every

package/dist/resources/runs.js

@@ -41,8 +41,9 @@ export class Runs {
         }
     }
     /** Send a message to a run. `start_turn: true` (the default) answers it in its
-     *  own turn: a running run receives it when its current turn ends, and a
-     *  message sent before the first turn has started queues behind that turn,
+     *  turn. A running run reads it at its next step unless `steer: false` opts out
+     *  and waits for the current turn to end. A message sent before the first turn
+     *  has started queues behind that turn,
      *  because a run's `runs.start` prompt is always its first turn's input.
      *  `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
@@ -52,11 +53,11 @@ export class Runs {
      *  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
+     *  different message, `start_turn`, or effective `steer` 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 { idempotencyKey = crypto.randomUUID(), maxRetries = 2, start_turn, ...rest } = options;
-        const body = { message, ...(start_turn === undefined ? {} : { start_turn }) };
+        const { idempotencyKey = crypto.randomUUID(), maxRetries = 2, start_turn, steer, ...rest } = options;
+        const body = { message, ...(start_turn === undefined ? {} : { start_turn }), ...(steer === undefined ? {} : { steer }) };
         // 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.
         return this.keyedSend(`${runPath(runId)}/messages`, body, idempotencyKey, maxRetries, rest);

package/dist/skill/northlight/SKILL.md

@@ -2,7 +2,7 @@
 name: northlight
 description: "Use when building, debugging or shipping an app that signs people in with Northlight, starts runs on their Northlight runtime, or calls Northlight providers (sms, search, integrations, context, device) with @north-light/sdk."
 metadata:
-  sdk-version: "0.3.576"
+  sdk-version: "0.3.578"
 ---
 
 # Building a Northlight app
@@ -27,7 +27,7 @@ Never text a person first: Comms refuses a send to anyone who has not texted you
 
 ## First: check this skill matches the SDK
 
-This skill is for SDK version `0.3.576`. If the project has `node_modules/@north-light/sdk/package.json`, compare its `version` with that number. If they differ, run `npx @north-light/sdk skill` in the project, then read the rewritten `.agents/skills/northlight/SKILL.md` (or `.claude/skills/northlight/SKILL.md`) instead of this copy. It needs no account. A project that has no SDK yet starts with `npx @north-light/sdk@latest init <dir>`.
+This skill is for SDK version `0.3.578`. If the project has `node_modules/@north-light/sdk/package.json`, compare its `version` with that number. If they differ, run `npx @north-light/sdk skill` in the project, then read the rewritten `.agents/skills/northlight/SKILL.md` (or `.claude/skills/northlight/SKILL.md`) instead of this copy. It needs no account. A project that has no SDK yet starts with `npx @north-light/sdk@latest init <dir>`.
 
 ## Where things run
 

package/dist/testing/cloud.js

@@ -966,9 +966,14 @@ export class FakeCloud {
             throw invalid('message is required', 'message');
         if (params['start_turn'] !== undefined && typeof params['start_turn'] !== 'boolean')
             throw invalid('start_turn must be a boolean', 'start_turn');
+        if (params['steer'] !== undefined && typeof params['steer'] !== 'boolean')
+            throw invalid('steer must be a boolean', 'steer');
         const startTurn = params['start_turn'] ?? true;
+        if (!startTurn && params['steer'] === true)
+            throw invalid('steer requires start_turn', 'steer');
+        const steer = startTurn && params['steer'] !== false;
         const key = this.idempotencyKey(rawKey);
-        const hash = sha256Hex(JSON.stringify(['run.message', run.id, text, startTurn]));
+        const hash = sha256Hex(JSON.stringify(['run.message', run.id, text, startTurn, ...(startTurn && !steer ? ['steer:false'] : [])]));
         if (key !== null) {
             const entry = user.idempotent(key);
             if (entry) {
@@ -986,7 +991,9 @@ export class FakeCloud {
         const response = { run_id: run.id, message_id: accepted.message_id, sequence_number: accepted.sequence_number };
         if (key !== null)
             user.idempotency.set(key, { hash, runId: run.id, status: 202, body: structuredClone(response), createdAt: this.clock.now() });
-        if (startTurn)
+        if (startTurn && steer && run.isTurnOpen())
+            run.steer([accepted]);
+        else if (startTurn)
             this.respond(run, 'message', [accepted]);
         return { status: 202, body: response };
     }

package/dist/testing/run.d.ts

@@ -134,9 +134,10 @@ export declare class FakeRun {
         messageIds?: string[];
     }): void;
     /** The same turn ending in error: `last_turn_error` set, status idle. */
-    failTurn({ code, message, messageIds }: {
+    failTurn({ code, message, retry_at, messageIds }: {
         code: TurnErrorDTO['code'];
         message: string;
+        retry_at?: string;
         messageIds?: string[];
     }): void;
     /** Fake-only: status `running` with `activity` overridden until the next appended event. */
@@ -157,6 +158,9 @@ export declare class FakeRun {
     expireEvents(upTo: number): void;
     /** Record an accepted message; returns it. */
     accept(text: string, startTurn: boolean, idempotencyKey: string | null): FakeRunMessage;
+    /** Deliver accepted messages into the open root turn at the next scripted step. */
+    steer(messages: readonly FakeRunMessage[]): void;
+    isTurnOpen(): boolean;
     /** Clear a non-canceled ending so a start-turn message runs it again (`commitReopenResident`). */
     reopen(): void;
     /** The app answered a question. */

package/dist/testing/run.js

@@ -142,11 +142,14 @@ export class FakeRun {
         });
     }
     /** The same turn ending in error: `last_turn_error` set, status idle. */
-    failTurn({ code, message, messageIds }) {
+    failTurn({ code, message, retry_at, messageIds }) {
+        if ((code === 'rate_limited') !== (retry_at !== undefined))
+            throw new Error('failTurn: retry_at is required with code rate_limited and only allowed there');
+        const error = retry_at === undefined ? { code, message } : { code, message, retry_at };
         this.turn(messageIds, (ids) => {
             this.append('node.output_text.done', { text: '', stop_reason: 'error', entry_id: entryId() });
-            this.turnError = { code, message };
-            return { stop_reason: 'error', ids, error: { code, message } };
+            this.turnError = error;
+            return { stop_reason: 'error', ids, error };
         });
     }
     /** Fake-only: status `running` with `activity` overridden until the next appended event. */
@@ -249,6 +252,20 @@ export class FakeRun {
         this.wake();
         return message;
     }
+    /** Deliver accepted messages into the open root turn at the next scripted step. */
+    steer(messages) {
+        if (!this.turnOpen())
+            throw new Error('no open turn to steer');
+        const started = this.log.filter((event) => event.node_id === this.id && event.type === 'node.turn.started').at(-1);
+        const ids = [...started.input.message_ids];
+        for (const message of messages) {
+            if (!ids.includes(message.message_id))
+                ids.push(message.message_id);
+            this.append('node.turn.started', { input: { text: message.text, message_ids: [...ids] }, entry_id: entryId() });
+            message.delivered = true;
+        }
+    }
+    isTurnOpen() { return this.turnOpen(); }
     /** Clear a non-canceled ending so a start-turn message runs it again (`commitReopenResident`). */
     reopen() {
         this.outcomeValue = undefined;
@@ -414,8 +431,9 @@ export class FakeRun {
         this.answered = false;
         // The status the run reads once this turn is closed (`run_status` is written as the turn ends).
         const status = this.messages.some((m) => m.start_turn && !m.delivered) ? 'running' : this.pendingQuestionIds.length ? 'waiting_on_user' : 'idle';
+        const steered = this.log.filter((event) => event.node_id === this.id && event.type === 'node.turn.started').at(-1);
         this.append('node.turn.completed', {
-            message_ids: ending.ids, run_status: status, stop_reason: ending.stop_reason,
+            message_ids: [...new Set([...ending.ids, ...steered.input.message_ids])], run_status: status, stop_reason: ending.stop_reason,
             ...(ending.error ? { error: ending.error } : {}), entry_id: entryId(),
         });
     }

package/dist/version.d.ts

@@ -1,5 +1,5 @@
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export declare const SDK_VERSION = "0.3.576";
+export declare const SDK_VERSION = "0.3.578";
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the
  *  contract level existed (which only knows this header) refuses this SDK, while every later runtime accepts it. */
 export declare const LEGACY_FLOOR = "0.3.423";

package/dist/version.js

@@ -1,6 +1,6 @@
 // SDK_VERSION is written by scripts/release-version.mjs on every release; do not edit by hand.
 /** This SDK's release version. Informational only: compatibility is the contract level, not this number. */
-export const SDK_VERSION = '0.3.576';
+export const SDK_VERSION = '0.3.578';
 // LEGACY_FLOOR is written once by `scripts/contract.mjs release`, at the first release that carries the contract level
 // (the `0.0.0` placeholder is replaced there and never again); do not edit by hand.
 /** The release sent in `Crouter-Minimum-Runtime-Version` on every request. It is frozen, so a runtime from before the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@north-light/sdk",
-  "version": "0.3.576",
-  "crouterContract": "1.38",
+  "version": "0.3.578",
+  "crouterContract": "1.40",
   "description": "Typed Node and browser client for running crouter agents through the crtrd /v1 API.",
   "type": "module",
   "main": "./dist/index.js",
@@ -44,9 +44,9 @@
     "prepublishOnly": "node -e \"if (process.env.npm_config_tag !== 'next') { console.error('@north-light/sdk publishes only with --tag next; scripts/promote-sdk.mjs is the only mover of latest.'); process.exit(1); }\""
   },
   "dependencies": {
-    "@north-light/api": "0.3.576",
-    "@north-light/identity": "0.3.576",
-    "@north-light/plugin": "0.3.576",
+    "@north-light/api": "0.3.578",
+    "@north-light/identity": "0.3.578",
+    "@north-light/plugin": "0.3.578",
     "jose": "^6.2.1"
   },
   "peerDependencies": {