@north-light/cli 0.3.421 → 0.3.423

package/dist/api/contract.d.ts

@@ -0,0 +1,45 @@
+/** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
+export declare const CONTRACT_LEVEL = "1.0";
+/** 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`. */
+export declare const CONTRACT_HEADER = "Crouter-Contract";
+/** A parsed `MAJOR.MINOR` level. */
+export interface ContractLevel {
+    major: number;
+    minor: number;
+}
+/** Parses one `MAJOR.MINOR` level; `null` when it is anything else. */
+export declare function parseContractLevel(value: string): ContractLevel | null;
+/** Parses a `Crouter-Contract` response value into its well-formed levels, dropping anything malformed. */
+export declare function parseServedContracts(header: string | null | undefined): ContractLevel[];
+/** True when `required` (one `MAJOR.MINOR`) is satisfied by `served` (a `Crouter-Contract` value or its parsed levels):
+ *  some served level has the same major and a minor at or above the required one. A malformed `required` is never
+ *  satisfied. */
+export declare function contractSatisfies(required: string, served: string | null | undefined | readonly ContractLevel[]): boolean;
+/** The refusal a server answers instead of handling a request, or `null` when the request may be handled.
+ *  - `required` absent: handled.
+ *  - `required` not `MAJOR.MINOR`: 400 `invalid_request` (`param` is the header).
+ *  - `required` not satisfied by `served`: 426 `runtime_version_unsupported`, details
+ *    `{sdk_version, runtime_version, required_contract, runtime_contract}` (the SDK's `RuntimeVersionDetails`).
+ *    `sdk_version` is the legacy minimum-runtime header value the caller sent (empty when it sent none). */
+export type ContractRefusal = {
+    status: 400;
+    code: 'invalid_request';
+    message: string;
+    param: string;
+} | {
+    status: 426;
+    code: 'runtime_version_unsupported';
+    message: string;
+    details: {
+        sdk_version: string;
+        runtime_version: string | null;
+        required_contract: string;
+        runtime_contract: string | null;
+    };
+};
+export declare function contractRefusal(required: string | undefined, served: string | null, context?: {
+    legacyMinimum?: string | undefined;
+    runtimeVersion?: string | null | undefined;
+}): ContractRefusal | null;

package/dist/api/contract.js

@@ -0,0 +1 @@
+var c=Object.defineProperty;var e=(r,t)=>c(r,"name",{value:t,configurable:!0});const f="1.0",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/error-codes.d.ts

@@ -4,6 +4,11 @@ export declare const errorCodes: {
         readonly status: 401;
         readonly retryable: false;
     };
+    readonly machine_revoked: {
+        readonly type: "authentication_error";
+        readonly status: 401;
+        readonly retryable: false;
+    };
     readonly grant_revoked: {
         readonly type: "authentication_error";
         readonly status: 401;
@@ -79,6 +84,11 @@ export declare const errorCodes: {
         readonly status: 403;
         readonly retryable: false;
     };
+    readonly unsandboxed_machine: {
+        readonly type: "permission_error";
+        readonly status: 403;
+        readonly retryable: false;
+    };
     readonly isolated_run: {
         readonly type: "permission_error";
         readonly status: 403;

package/dist/api/error-codes.js

@@ -1 +1 @@
-const e={unauthorized:{type:"authentication_error",status:401,retryable:!1},grant_revoked:{type:"authentication_error",status:401,retryable:!1},grant_removed:{type:"authentication_error",status:401,retryable:!1},grant_suspended:{type:"authentication_error",status:401,retryable:!1},refresh_token_expired:{type:"authentication_error",status:401,retryable:!1},refresh_token_reused:{type:"authentication_error",status:401,retryable:!1},scope_missing:{type:"permission_error",status:403,retryable:!1},owner_only:{type:"permission_error",status:403,retryable:!1},other_app_run:{type:"permission_error",status:403,retryable:!1},payer_not_app:{type:"permission_error",status:403,retryable:!1},approval_pending:{type:"permission_error",status:403,retryable:!1},user_denied:{type:"permission_error",status:403,retryable:!1},provider_refused:{type:"permission_error",status:403,retryable:!1},provider_not_connected:{type:"permission_error",status:403,retryable:!1},provider_setup_pending:{type:"permission_error",status:403,retryable:!1},question_pages_off:{type:"permission_error",status:403,retryable:!1},isolated_run:{type:"permission_error",status:403,retryable:!1},provider_version_retired:{type:"permission_error",status:403,retryable:!1},invalid_scope:{type:"invalid_request_error",status:400,retryable:!1},invalid_request:{type:"invalid_request_error",status:400,retryable:!1},range_not_satisfiable:{type:"invalid_request_error",status:416,retryable:!1},conflict:{type:"invalid_request_error",status:409,retryable:!1},not_found:{type:"invalid_request_error",status:404,retryable:!1},model_unavailable:{type:"invalid_request_error",status:404,retryable:!1},upstream_model_unavailable:{type:"server_error",status:503,retryable:!0},substitution_refused:{type:"invalid_request_error",status:400,retryable:!1},idempotency_conflict:{type:"invalid_request_error",status:409,retryable:!1},run_settled:{type:"invalid_request_error",status:409,retryable:!1},cap_exhausted:{type:"rate_limit_error",status:402,retryable:!1},concurrency_limit:{type:"rate_limit_error",status:429,retryable:!0},all_routes_exhausted:{type:"rate_limit_error",status:429,retryable:!0},provider_rate_limited:{type:"rate_limit_error",status:429,retryable:!0},rate_limited:{type:"rate_limit_error",status:429,retryable:!0},runtime_unreachable:{type:"server_error",status:503,retryable:!0},isolated_unavailable:{type:"server_error",status:503,retryable:!0},runtime_starting:{type:"server_error",status:503,retryable:!0},runtime_provisioning:{type:"server_error",status:503,retryable:!0},provider_unavailable:{type:"server_error",status:503,retryable:!0},upstream_refused:{type:"server_error",status:502,retryable:!1},provider_bad_response:{type:"server_error",status:502,retryable:!1},service_unavailable:{type:"server_error",status:503,retryable:!0},not_implemented:{type:"server_error",status:501,retryable:!1},permission_error:{type:"permission_error",status:403,retryable:!1},storage_unavailable:{type:"server_error",status:503,retryable:!0},server_error:{type:"server_error",status:500,retryable:!0},server_failure:{type:"server_error",status:500,retryable:!1},wake_timeout:{type:"server_error",status:504,retryable:!0}};export{e as errorCodes};
+const e={unauthorized:{type:"authentication_error",status:401,retryable:!1},machine_revoked:{type:"authentication_error",status:401,retryable:!1},grant_revoked:{type:"authentication_error",status:401,retryable:!1},grant_removed:{type:"authentication_error",status:401,retryable:!1},grant_suspended:{type:"authentication_error",status:401,retryable:!1},refresh_token_expired:{type:"authentication_error",status:401,retryable:!1},refresh_token_reused:{type:"authentication_error",status:401,retryable:!1},scope_missing:{type:"permission_error",status:403,retryable:!1},owner_only:{type:"permission_error",status:403,retryable:!1},other_app_run:{type:"permission_error",status:403,retryable:!1},payer_not_app:{type:"permission_error",status:403,retryable:!1},approval_pending:{type:"permission_error",status:403,retryable:!1},user_denied:{type:"permission_error",status:403,retryable:!1},provider_refused:{type:"permission_error",status:403,retryable:!1},provider_not_connected:{type:"permission_error",status:403,retryable:!1},provider_setup_pending:{type:"permission_error",status:403,retryable:!1},question_pages_off:{type:"permission_error",status:403,retryable:!1},unsandboxed_machine:{type:"permission_error",status:403,retryable:!1},isolated_run:{type:"permission_error",status:403,retryable:!1},provider_version_retired:{type:"permission_error",status:403,retryable:!1},invalid_scope:{type:"invalid_request_error",status:400,retryable:!1},invalid_request:{type:"invalid_request_error",status:400,retryable:!1},range_not_satisfiable:{type:"invalid_request_error",status:416,retryable:!1},conflict:{type:"invalid_request_error",status:409,retryable:!1},not_found:{type:"invalid_request_error",status:404,retryable:!1},model_unavailable:{type:"invalid_request_error",status:404,retryable:!1},upstream_model_unavailable:{type:"server_error",status:503,retryable:!0},substitution_refused:{type:"invalid_request_error",status:400,retryable:!1},idempotency_conflict:{type:"invalid_request_error",status:409,retryable:!1},run_settled:{type:"invalid_request_error",status:409,retryable:!1},cap_exhausted:{type:"rate_limit_error",status:402,retryable:!1},concurrency_limit:{type:"rate_limit_error",status:429,retryable:!0},all_routes_exhausted:{type:"rate_limit_error",status:429,retryable:!0},provider_rate_limited:{type:"rate_limit_error",status:429,retryable:!0},rate_limited:{type:"rate_limit_error",status:429,retryable:!0},runtime_unreachable:{type:"server_error",status:503,retryable:!0},isolated_unavailable:{type:"server_error",status:503,retryable:!0},runtime_starting:{type:"server_error",status:503,retryable:!0},runtime_provisioning:{type:"server_error",status:503,retryable:!0},provider_unavailable:{type:"server_error",status:503,retryable:!0},upstream_refused:{type:"server_error",status:502,retryable:!1},provider_bad_response:{type:"server_error",status:502,retryable:!1},service_unavailable:{type:"server_error",status:503,retryable:!0},not_implemented:{type:"server_error",status:501,retryable:!1},permission_error:{type:"permission_error",status:403,retryable:!1},storage_unavailable:{type:"server_error",status:503,retryable:!0},server_error:{type:"server_error",status:500,retryable:!0},server_failure:{type:"server_error",status:500,retryable:!1},wake_timeout:{type:"server_error",status:504,retryable:!0}};export{e as errorCodes};

package/dist/api/index.d.ts

@@ -7,6 +7,8 @@ export type { ErrorCode, ErrorEnvelope, ErrorOrigin, ErrorType } from './error-c
 export { API_VERSION, routes } from './routes.js';
 export { RUNTIME_VERSION_HEADER, MINIMUM_RUNTIME_VERSION_HEADER, compareReleaseVersions, minimumRuntimeRefusal } from './runtime-version.js';
 export type { MinimumRuntimeRefusal } from './runtime-version.js';
+export { CONTRACT_HEADER, CONTRACT_LEVEL, REQUIRED_CONTRACT_HEADER, contractRefusal, contractSatisfies, parseContractLevel, parseServedContracts } from './contract.js';
+export type { ContractLevel, ContractRefusal } from './contract.js';
 export { LONG_POLL_MAX_WAIT_SECONDS, LONG_POLL_ROUTES, longPollHoldSeconds, longPollRoute, requestedWait } from './long-poll.js';
 export type { LongPollName, LongPollRoute } from './long-poll.js';
 export * from '../shared/generated-context.js';

package/dist/api/index.js

@@ -1 +1 @@
-import{CrtrClient as e,deadlineExceeded as t,MAX_TIMER_MS as m,sleepWithin as p,waitForDaemonAvailability as f}from"./client.js";import{APIError as E,ApiError as i,isErrorBody as l}from"./errors.js";import{errorCodes as R}from"./error-codes.js";import{API_VERSION as n,routes as s}from"./routes.js";import{RUNTIME_VERSION_HEADER as d,MINIMUM_RUNTIME_VERSION_HEADER as A,compareReleaseVersions as M,minimumRuntimeRefusal as N}from"./runtime-version.js";import{LONG_POLL_MAX_WAIT_SECONDS as S,LONG_POLL_ROUTES as u,longPollHoldSeconds as L,longPollRoute as P,requestedWait as T}from"./long-poll.js";export*from"../shared/generated-context.js";export*from"./dto/common.js";export*from"./dto/health.js";export*from"./dto/limits.js";export*from"./dto/grants.js";export*from"./dto/usage.js";export*from"./dto/nodes.js";export*from"./dto/node-outcomes.js";export*from"./dto/node-events.js";export*from"./dto/run-events.js";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";export*from"./dto/crons.js";export*from"./dto/config.js";export*from"./dto/attach.js";export*from"./dto/broker.js";export*from"./dto/profiles.js";export*from"./dto/modelauth.js";export*from"./dto/model-config.js";export*from"./dto/canvas.js";export*from"./dto/worktree.js";export*from"./dto/human.js";export*from"./dto/files.js";export*from"./dto/bash.js";export*from"./dto/inbox.js";export*from"./dto/human-requests.js";export*from"./dto/reviews.js";export*from"./dto/review-comments.js";export*from"./dto/chat-inventory.js";export*from"./dto/analytics.js";export*from"./dto/custom-objects.js";export{E as APIError,n as API_VERSION,i as ApiError,e as CrtrClient,S as LONG_POLL_MAX_WAIT_SECONDS,u as LONG_POLL_ROUTES,m as MAX_TIMER_MS,A as MINIMUM_RUNTIME_VERSION_HEADER,d as RUNTIME_VERSION_HEADER,M as compareReleaseVersions,t as deadlineExceeded,R as errorCodes,l as isErrorBody,L as longPollHoldSeconds,P as longPollRoute,N as minimumRuntimeRefusal,T as requestedWait,s as routes,p as sleepWithin,f as waitForDaemonAvailability};
+import{CrtrClient as e,deadlineExceeded as t,MAX_TIMER_MS as m,sleepWithin as p,waitForDaemonAvailability as f}from"./client.js";import{APIError as E,ApiError as R,isErrorBody as _}from"./errors.js";import{errorCodes as i}from"./error-codes.js";import{API_VERSION as s,routes as n}from"./routes.js";import{RUNTIME_VERSION_HEADER as C,MINIMUM_RUNTIME_VERSION_HEADER as I,compareReleaseVersions as N,minimumRuntimeRefusal as O}from"./runtime-version.js";import{CONTRACT_HEADER as d,CONTRACT_LEVEL as S,REQUIRED_CONTRACT_HEADER as c,contractRefusal as L,contractSatisfies as M,parseContractLevel as u,parseServedContracts as D}from"./contract.js";import{LONG_POLL_MAX_WAIT_SECONDS as H,LONG_POLL_ROUTES as U,longPollHoldSeconds as V,longPollRoute as v,requestedWait as W}from"./long-poll.js";export*from"../shared/generated-context.js";export*from"./dto/common.js";export*from"./dto/health.js";export*from"./dto/limits.js";export*from"./dto/grants.js";export*from"./dto/usage.js";export*from"./dto/nodes.js";export*from"./dto/node-outcomes.js";export*from"./dto/node-events.js";export*from"./dto/run-events.js";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";export*from"./dto/crons.js";export*from"./dto/config.js";export*from"./dto/attach.js";export*from"./dto/broker.js";export*from"./dto/profiles.js";export*from"./dto/modelauth.js";export*from"./dto/model-config.js";export*from"./dto/canvas.js";export*from"./dto/worktree.js";export*from"./dto/human.js";export*from"./dto/files.js";export*from"./dto/bash.js";export*from"./dto/inbox.js";export*from"./dto/human-requests.js";export*from"./dto/reviews.js";export*from"./dto/review-comments.js";export*from"./dto/chat-inventory.js";export*from"./dto/analytics.js";export*from"./dto/custom-objects.js";export{E as APIError,s as API_VERSION,R as ApiError,d as CONTRACT_HEADER,S as CONTRACT_LEVEL,e as CrtrClient,H as LONG_POLL_MAX_WAIT_SECONDS,U as LONG_POLL_ROUTES,m as MAX_TIMER_MS,I as MINIMUM_RUNTIME_VERSION_HEADER,c as REQUIRED_CONTRACT_HEADER,C as RUNTIME_VERSION_HEADER,N as compareReleaseVersions,L as contractRefusal,M as contractSatisfies,t as deadlineExceeded,i as errorCodes,_ as isErrorBody,V as longPollHoldSeconds,v as longPollRoute,O as minimumRuntimeRefusal,u as parseContractLevel,D as parseServedContracts,W as requestedWait,n as routes,p as sleepWithin,f as waitForDaemonAvailability};

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

@@ -26,7 +26,7 @@ Every class below extends `APIError`, which carries `status`, `code`, `message`,
 | Condition | Class |
 |---|---|
 | SDK configuration error | `CrouterError` with `status: 0`, `code: 'crouter_error'` |
-| The runtime is older than the SDK, or names no version. The hosting router or the runtime can refuse this *before* handling (the SDK sends `Crouter-Minimum-Runtime-Version`): nothing was accepted and no idempotency key was recorded. A hosted runtime is always refused first once the hosting router has this check. Only a runtime that is not behind such a router and is older than the check release handles the request first, and then the SDK raises after | `RuntimeVersionError` with `status: 426`, `code: 'runtime_version_unsupported'`; `sdkVersion` and `runtimeVersion` (or `null`) name both, and it is never retryable. See [[crouter-sdk/release-notes]] |
+| The runtime does not serve the contract level the SDK requires, or names none. The hosting router or the runtime refuses this *before* handling (the SDK sends `Crouter-Required-Contract` and a frozen `Crouter-Minimum-Runtime-Version`): nothing was accepted and no idempotency key was recorded. A runtime that predates the contract level handles the request first, and the SDK then raises after | `RuntimeVersionError` with `status: 426`, `code: 'runtime_version_unsupported'`; `requiredContract` and `runtimeContract` (or `null`) name both levels, `sdkVersion` and `runtimeVersion` stay for logging, and it is never retryable. A level is `MAJOR.MINOR`; the runtime satisfies it when it serves the same major and a minor at or above. See [[crouter-sdk/release-notes]] |
 | HTTP 400 | `BadRequestError` |
 | HTTP 401 | `AuthenticationError` |
 | HTTP 403 | `PermissionDeniedError` |

package/dist/builtin-memory/crouter-sdk/getting-started.md

@@ -27,6 +27,8 @@ npm i @north-light/sdk
 
 One dependency. It re-exports every data type you need, so you do not also install `@north-light/api`.
 
+`@latest` always works against production: a release reaches `latest` only once production serves its contract level. The `next` tag carries every release the moment it is published and may need a newer runtime than production runs (see [[crouter-sdk/errors]] for `RuntimeVersionError`). Pin an exact version in your app.
+
 ## 3. Node, on the owner's own daemon
 
 Pass nothing. The client resolves the same socket path the `crtr` CLI does, and starts the daemon if it is not already up.

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

@@ -9,6 +9,16 @@ 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.423
+
+### Compatibility is a contract level, not the package version (additive)
+
+The SDK no longer refuses a runtime because its release number is lower than the SDK's. It sends `Crouter-Required-Contract: <CONTRACT_LEVEL>` and refuses a runtime that does not serve that level (`MAJOR.MINOR`, same major, minor at or above). The level changes only when the `/v1` surface changes, so an ordinary release no longer makes production answer 426. `RuntimeVersionError` keeps `status` 426 and code `runtime_version_unsupported`, and gains `requiredContract` and `runtimeContract`; `sdkVersion` and `runtimeVersion` stay. Apps that catch the error need no change.
+
+- Every SDK release is published to the `next` dist-tag; `latest` moves only once production serves its level. `@latest` therefore always works against production.
+- The SDK now tolerates values it does not know: an unknown run event `type` is passed to your listener as-is, and an unknown run `status` ends `runs.wait` and the run watcher, reporting the raw status (`RunEnded.ended` can be `'unknown'`). Handle a status or event type you do not recognize rather than assuming the union is closed.
+- `FakeCloud` takes `contract` and `routedContract` options and refuses an incompatible call at ingress, before any interceptor runs.
+
 ## 0.3.419
 
 ### Testing mode: `app_in_testing` (additive)