@north-light/cli 0.3.576 → 0.3.578

package/dist/api/contract.d.ts

@@ -1,5 +1,5 @@
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export declare const CONTRACT_LEVEL = "1.38";
+export declare const CONTRACT_LEVEL = "1.40";
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export declare const REQUIRED_CONTRACT_HEADER = "Crouter-Required-Contract";
 /** Response header listing the contract levels the server serves, comma-separated, one per major, e.g. `1.3`. */

package/dist/api/contract.js

@@ -1 +1 @@
-var c=Object.defineProperty;var e=(r,t)=>c(r,"name",{value:t,configurable:!0});const f="1.38",i="Crouter-Required-Contract",p="Crouter-Contract";function l(r){const t=/^(\d+)\.(\d+)$/.exec(r.trim());return t===null?null:{major:Number(t[1]),minor:Number(t[2])}}e(l,"parseContractLevel");function a(r){return r==null?[]:r.split(",").map(t=>l(t)).filter(t=>t!==null)}e(a,"parseServedContracts");function s(r,t){const n=l(r);return n===null?!1:(typeof t=="string"||t===null||t===void 0?a(t):t).some(u=>u.major===n.major&&u.minor>=n.minor)}e(s,"contractSatisfies");function C(r,t,n={}){if(r===void 0)return null;if(l(r)===null)return{status:400,code:"invalid_request",param:i,message:`${i} must be a contract level like 1.0.`};if(s(r,t))return null;const o=r.trim();return{status:426,code:"runtime_version_unsupported",message:t===null||a(t).length===0?`The runtime did not name its contract level; the caller requires contract ${o} or later. Roll the runtime forward.`:`The runtime serves contract ${t}; the caller requires contract ${o} or later within the same major. Roll the runtime forward, or pin an SDK whose crouterContract the runtime serves.`,details:{sdk_version:(n.legacyMinimum??"").trim(),runtime_version:n.runtimeVersion??null,required_contract:o,runtime_contract:t}}}e(C,"contractRefusal");export{p as CONTRACT_HEADER,f as CONTRACT_LEVEL,i as REQUIRED_CONTRACT_HEADER,C as contractRefusal,s as contractSatisfies,l as parseContractLevel,a as parseServedContracts};
+var c=Object.defineProperty;var e=(r,t)=>c(r,"name",{value:t,configurable:!0});const f="1.40",i="Crouter-Required-Contract",p="Crouter-Contract";function l(r){const t=/^(\d+)\.(\d+)$/.exec(r.trim());return t===null?null:{major:Number(t[1]),minor:Number(t[2])}}e(l,"parseContractLevel");function a(r){return r==null?[]:r.split(",").map(t=>l(t)).filter(t=>t!==null)}e(a,"parseServedContracts");function s(r,t){const n=l(r);return n===null?!1:(typeof t=="string"||t===null||t===void 0?a(t):t).some(u=>u.major===n.major&&u.minor>=n.minor)}e(s,"contractSatisfies");function C(r,t,n={}){if(r===void 0)return null;if(l(r)===null)return{status:400,code:"invalid_request",param:i,message:`${i} must be a contract level like 1.0.`};if(s(r,t))return null;const o=r.trim();return{status:426,code:"runtime_version_unsupported",message:t===null||a(t).length===0?`The runtime did not name its contract level; the caller requires contract ${o} or later. Roll the runtime forward.`:`The runtime serves contract ${t}; the caller requires contract ${o} or later within the same major. Roll the runtime forward, or pin an SDK whose crouterContract the runtime serves.`,details:{sdk_version:(n.legacyMinimum??"").trim(),runtime_version:n.runtimeVersion??null,required_contract:o,runtime_contract:t}}}e(C,"contractRefusal");export{p as CONTRACT_HEADER,f as CONTRACT_LEVEL,i as REQUIRED_CONTRACT_HEADER,C as contractRefusal,s as contractSatisfies,l as parseContractLevel,a as parseServedContracts};

package/dist/api/dto/run-events.d.ts

@@ -32,10 +32,13 @@ export type RunActivityDTO = {
     };
 };
 /** Why a turn ended in error: `content_refused` when the vendor refused the
- *  model call on safety grounds, `model_error` for any other failed call. */
+ *  model call on safety grounds, `rate_limited` when every model route is
+ *  rate-limited for longer than a turn waits, `model_error` for any other failed call. */
 export interface TurnErrorDTO {
-    code: 'content_refused' | 'model_error';
+    code: 'content_refused' | 'model_error' | 'rate_limited';
     message: string;
+    /** ISO time the rate limit is expected to lift; present only when `code` is `rate_limited`. */
+    retry_at?: string;
 }
 /** The broker's stop reason for one assistant message, unchanged. */
 export type AssistantStopReasonDTO = 'stop' | 'toolUse' | 'length' | 'error' | 'aborted';
@@ -111,7 +114,10 @@ export interface NodeMessageAcceptedEvent extends RunEventBaseDTO {
 }
 export interface NodeTurnStartedEvent extends RunEventBaseDTO {
     type: 'node.turn.started';
-    /** `message_ids`: the accepted `run.message` messages this turn delivers (empty for the prompt, an answer, or a child's report). */
+    /**
+     * `message_ids`: the accepted `run.message` messages this turn delivers (empty for the prompt, an answer, or a child's report).
+     * A turn can emit more than one `node.turn.started`: each time a steered `run.message` joins the open turn at the agent's next step, another one arrives with that message's `message_ids` and its own `entry_id`. A single `node.turn.completed` ends the turn and carries every joined id.
+     */
     input: {
         text: string;
         message_ids: string[];
@@ -156,7 +162,7 @@ export interface NodeToolCallCompletedEvent extends RunEventBaseDTO, Redactable
 }
 export interface NodeTurnCompletedEvent extends RunEventBaseDTO {
     type: 'node.turn.completed';
-    /** The same as the turn's `node.turn.started` `input.message_ids`. */
+    /** Every `input.message_ids` of the turn's `node.turn.started` events, in order (more than one when messages joined the turn). */
     message_ids: string[];
     /** The run's `run.get` status when the turn ended. */
     run_status: Exclude<RunStatusDTO, 'settled'>;

package/dist/builtin-memory/crouter-sdk/release-notes.md

@@ -9,10 +9,22 @@ when-and-why-to-read: When you need Release notes, this knowledge should be read
 
 Changes to `@north-light/sdk` that can change what an existing app sees. Newest first.
 
+## 0.3.578
+
+`runs.message` now steers a running root turn by default: the agent reads it at its next step. Pass `{ steer: false }` to wait for the current turn to end and start a separate turn. `start_turn: false` remains deferred and cannot use `steer: true`. When a later message joins a turn, `runs.reply` stops yielding text for the earlier message at that boundary, but still waits for the turn's completion. An app on an older SDK gets steering as soon as the runtime upgrades, because it cannot send `steer: false`; its `runs.reply` then streams the answer to a joined later message as part of the earlier reply. Upgrade the SDK to get the `RunReply` boundary and the opt-out.
+
+## 0.3.577
+
+`POST /v1/nodes` with a pinned `cwd` that is not an existing directory on the runtime's host now answers `cwd_missing` instead of creating a node whose broker then fails to launch. A sandbox, isolated or worktree node is not checked. `POST /v1/nodes/{id}/messages` with `reopen` to a dormant node whose recorded cwd is gone now answers `cwd_missing` before the reopen is committed or any mail is queued, instead of accepting the message and reporting `wake_failed`.
+
 ## 0.3.576
 
 On a cloud role, `provider.tools` now reports a granted provider as `available` once its bundle is installed in the deployment's shared plugin directory. It no longer answers `500` when a person has no materialized bundle; a granted provider still being installed reports `installing` or `install_failed`. Providers without that person's grant remain hidden. The Mac's plugin settings and provider tools behavior are unchanged.
 
+## Next release
+
+A turn that ends because every model route is rate-limited for longer than a turn waits now reports `error.code: 'rate_limited'` with `error.retry_at` (ISO time the limit is expected to lift), on `turn.completed` and `runs.get().last_turn_error`. It was `model_error` with the time only inside `message`. The run stays `idle` and usable, as before. An app that matches `error.code` exhaustively should handle the new value; one that treats any other code as a model error needs no change.
+
 ## 0.3.572
 
 `POST /v1/runs` works on a cloud role (a runtime started with `--role api` or `--role reconcile`). It answered `500 server_failure` because the role has no root launcher and the run start tried to prepare an app OS user and folder. Behavior on a person's Mac and on a hosted guest with a launcher is unchanged.

package/dist/builtin-memory/crouter-sdk/streaming.md

@@ -70,6 +70,8 @@ Every event except `error` carries `node_id` and `sequence_number` in addition t
 | `node.settled` | `{ node_id, sequence_number, outcome }` — terminal; the daemon ends the response after it |
 | `error` | `{ error: { code: 'stream_gap' \| 'stream_dropped' \| 'stream_error', message, details?: { earliest_sequence?: number } } }` — `stream_gap` is recoverable; the other codes terminate the response |
 
+A turn can emit more than one `node.turn.started`. A `run.message` sent while the turn is running steers by default, so the agent reads it at its next step and the stream emits another `node.turn.started` whose `input.message_ids` holds the joined message; the turn ends with one `node.turn.completed` whose `message_ids` lists every message that joined it. A reply to one message therefore ends at the turn's completion, not at the next `node.turn.started`; the SDK's `RunReply` stops yielding text once a later message joins. Send `{ steer: false }` to start a separate turn after the current one ends.
+
 `summary` on a tool-call event states whether arguments are null, an array and its item count, an object and its field count, or a primitive type. It never includes argument values or tool output.
 
 **Deliberately not carried:** thinking deltas, the model's tool-call construction deltas, raw tool output, and the system prompt. Those belong to the owner's viewer, not to an application's run stream.

package/dist/builtin-memory/northlight-apps/concepts/runs.md

@@ -33,6 +33,8 @@ const run = await runtime.runs.wait(started.run_id); // status is 'idle' once th
 
 `runs.wait` returns on `waiting_on_user`, `idle` and `settled`, so check the status before you read a result.
 
+A turn that fails on a model error leaves the run `idle`, not `settled`, with `last_turn_error` set (`{code, message}`); the same error is on that turn's `turn.completed` event. The run stays usable, and a retry is a `runs.message`. When `code` is `rate_limited`, every model route is rate-limited and `retry_at` (an ISO time) says when the limit is expected to lift: send the retry after `retry_at`, or `runs.cancel` the run, rather than wait for its deadline. A message sent before `retry_at` fails the same way.
+
 ## Outcome and result
 
 A `settled` run has an `outcome`:

package/dist/builtin-memory/northlight-apps/guides/stream-a-run.md

@@ -44,7 +44,7 @@ A chat app sends a message and shows the answer to it. `runs.reply(runId, sent,
 const sent = await runtime.runs.message(runId, 'What did the report say?');
 for await (const event of runtime.runs.reply(runId, sent)) {
   if (event.type === 'text.delta') append(event.delta);
-  if (event.type === 'turn.completed' && event.error) showError(event.error); // {code: 'content_refused' | 'model_error', message}
+  if (event.type === 'turn.completed' && event.error) showError(event.error); // {code: 'content_refused' | 'model_error' | 'rate_limited', message, retry_at?}
 }
 // or collect it: text as it streams, then the whole text and how the turn ended
 const {text, ended, error, outcome} = await runtime.runs.reply(runId, sent).collect({onDelta: (delta) => append(delta)});

package/dist/builtin-memory/northlight-apps/guides/test-your-app.md

@@ -62,7 +62,7 @@ A responder gets `{run, kind: 'start' | 'message', messages}`. It is called afte
 | Method | Effect |
 |---|---|
 | `reply(text, {chunks = 2, messageIds?})` | One turn: `node.turn.started`, text deltas, `node.output_text.done`, `node.turn.completed`. Delivers `messageIds` (default: every pending message). The run goes `idle` (`waiting_on_user` with an open question). |
-| `failTurn({code: 'model_error' \| 'content_refused', message})` | The same turn ending `stop_reason: 'error'`; `runs.get` shows `last_turn_error`; `runs.reply(...).collect()` ends `error`. |
+| `failTurn({code: 'model_error' \| 'content_refused' \| 'rate_limited', message, retry_at?})` | The same turn ending `stop_reason: 'error'`; `runs.get` shows `last_turn_error`; `runs.reply(...).collect()` ends `error`. `retry_at` (ISO) is required with `rate_limited` and refused with any other code. |
 | `setActivity(activity, {at?})` | Fake-only: status `running` with this `activity` until the next event. The only way to reach `writing` or a streaming tool call. |
 | `settle(ending)` | `{result}`, `{declined: {reason, code, retryable}}`, `{failure: 'canceled' \| 'deadline_exceeded'}`, or `{runtimeError: reason}`. Emits `node.settled` with the outcome the runtime writes. |
 | `idle()` | Goes idle without a new turn (stopped without submitting). |