@north-light/api 0.3.453 → 0.3.455

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.3";
+export declare const CONTRACT_LEVEL = "1.4";
 /** 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

@@ -12,7 +12,7 @@
 //
 // PURITY (spec §3.1): Node built-ins + `src/api/*` only.
 /** The contract level this build serves and requires. Written by `scripts/contract.mjs release`; never edit by hand. */
-export const CONTRACT_LEVEL = '1.3';
+export const CONTRACT_LEVEL = '1.4';
 /** Request header naming the one contract level the caller needs, e.g. `1.3`. Optional: absent means no check. */
 export 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/error-codes.d.ts

@@ -134,6 +134,31 @@ export declare const errorCodes: {
         readonly status: 409;
         readonly retryable: false;
     };
+    readonly invalid_argument: {
+        readonly type: "invalid_request_error";
+        readonly status: 400;
+        readonly retryable: false;
+    };
+    readonly machine_required: {
+        readonly type: "invalid_request_error";
+        readonly status: 409;
+        readonly retryable: false;
+    };
+    readonly device_offline: {
+        readonly type: "server_error";
+        readonly status: 503;
+        readonly retryable: true;
+    };
+    readonly device_timeout: {
+        readonly type: "server_error";
+        readonly status: 504;
+        readonly retryable: true;
+    };
+    readonly device_disconnected: {
+        readonly type: "server_error";
+        readonly status: 503;
+        readonly retryable: false;
+    };
     readonly not_found: {
         readonly type: "invalid_request_error";
         readonly status: 404;

package/dist/api/error-codes.js

@@ -37,6 +37,16 @@ export const errorCodes = {
     // A peer machine runs a crtr release below the peer-protocol floor; details `{ peer_version, floor, receiver_version }`. Update it with `crtr sys update`.
     peer_version_too_old: { type: 'invalid_request_error', status: 426, retryable: false },
     conflict: { type: 'invalid_request_error', status: 409, retryable: false },
+    // `provider.call` input that cannot apply: `machine` on a provider that is not served by a machine.
+    invalid_argument: { type: 'invalid_request_error', status: 400, retryable: false },
+    // A device call names no machine and the account has several (or the named one is not a device); details `{ candidates: [{ machine_id, name, last_seen }] }`.
+    machine_required: { type: 'invalid_request_error', status: 409, retryable: false },
+    // The device machine is offline, unreachable, or its Desktop is signed out.
+    device_offline: { type: 'server_error', status: 503, retryable: true },
+    // The device did not answer within the call's deadline.
+    device_timeout: { type: 'server_error', status: 504, retryable: true },
+    // The device's relay connection dropped mid-call; the action may have run, so it is not retryable.
+    device_disconnected: { type: 'server_error', status: 503, retryable: false },
     not_found: { type: 'invalid_request_error', status: 404, retryable: false },
     model_unavailable: { type: 'invalid_request_error', status: 404, retryable: false },
     upstream_model_unavailable: { type: 'server_error', status: 503, retryable: true },

package/dist/core/command-plugins/bundle.d.ts

@@ -1,5 +1,6 @@
 import { type ValidatedCommandManifest } from '../../api/command-manifest/manifest.js';
 import type { KindConfig, MemoryExtensionDeclarations, PageComponentRegistration, PluginBundle, PluginManifest, Scope } from '../../types.js';
+import { type BundleTransport } from './endpoint.js';
 /** Who may call a capability provider's tool group (contract 3). */
 export type ProviderGroupWho = 'own' | 'user' | 'allowlist' | 'any';
 /** One tool group a capability provider declares in `bundle.json`. */
@@ -34,11 +35,7 @@ export interface ValidatedBundle {
     version?: number;
     /** The transport `bundle.json` declares, when it declares one (a bundle the
      *  directory emits for a capability provider always does). */
-    transport?: {
-        kind: 'http';
-        endpoint: string;
-        authEnv?: string;
-    };
+    transport?: BundleTransport;
     /** The capability-provider block: present only on a provider bundle. */
     provider?: ProviderBlock;
     /** Kind-registry contributions declared in `bundle.json` (optional). The
@@ -82,11 +79,7 @@ export declare function validatePluginBundle(archive: Uint8Array, options: {
     extensibleCoreBranches?: ReadonlySet<string>;
 }): Promise<PluginBundleValidation>;
 /** An archive install's invocation transport. */
-export type BundleInvocationTransport = {
-    kind: 'http';
-    endpoint: string;
-    authEnv?: string;
-};
+export type BundleInvocationTransport = BundleTransport;
 /** The hash recorded as a bundle package's `version`: the exact archive bytes
  *  unpacked at its root. Same bytes, same version — which is what lets a
  *  re-sent archive be recognized as the generation already installed. */

package/dist/core/command-plugins/bundle.js

@@ -8,7 +8,7 @@ import { general } from '../errors.js';
 import { atomicWriteJson, atomicWriteText, ensureDir, nowIso, pathExists, removePath, syncDirectory, syncTree } from '../fs-utils.js';
 import { invalidPageComponentsReasons, normalizePageComponents } from '../human/page-catalog.js';
 import { validateMemoryExtensionDeclarations } from '../plugin-extensions.js';
-import { validateHttpPluginTransport } from './endpoint.js';
+import { validateBundleTransport } from './endpoint.js';
 /** A capability provider id or tool group id: contract 1's `<id>` grammar. */
 const PROVIDER_ID = /^[A-Za-z0-9_-]{1,64}$/;
 const PROVIDER_KEYS = new Set(['id', 'major', 'groups']);
@@ -240,7 +240,7 @@ function providerBundleIssue(metadata, commands) {
     if (metadata.transport === undefined) {
         return bundleInvalid('a provider bundle must declare its transport', '(missing)', 'transport { kind: "http", endpoint } in bundle.json', 'Add the provider endpoint as bundle.json transport.', 'bundle.json.transport');
     }
-    if (metadata.transport.authEnv !== undefined) {
+    if (metadata.transport.kind === 'http' && metadata.transport.authEnv !== undefined) {
         return bundleInvalid('a provider bundle must not declare authEnv', metadata.transport.authEnv, 'no authEnv: the runtime presents its own outbound token', 'Remove transport.authEnv from bundle.json.', 'bundle.json.transport.authEnv');
     }
     const declared = new Set(provider.groups.map((g) => g.group));
@@ -315,10 +315,10 @@ function parseBundleMetadata(bytes) {
     }
     let transport;
     if (record['transport'] !== undefined) {
-        const t = validateHttpPluginTransport(record['transport']);
+        const t = validateBundleTransport(record['transport']);
         if (t.transport === undefined) {
             return {
-                issue: bundleInvalid('bundle.json transport is invalid', t.errors.join('; '), '{ kind: "http", endpoint, authEnv? }', 'Fix transport in bundle.json.', 'bundle.json.transport'),
+                issue: bundleInvalid('bundle.json transport is invalid', t.errors.join('; '), '{ kind: "http", endpoint, authEnv? } or { kind: "machine" }', 'Fix transport in bundle.json.', 'bundle.json.transport'),
             };
         }
         transport = t.transport;

package/dist/core/command-plugins/endpoint.d.ts

@@ -22,3 +22,15 @@ export declare function validateHttpPluginTransport(raw: unknown): {
     };
     errors: string[];
 };
+/** The transport a served provider bundle declares: HTTP (the provider's endpoint) or `{ kind: "machine" }` (calls go to a device machine). */
+export type BundleTransport = {
+    kind: 'http';
+    endpoint: string;
+    authEnv?: string;
+} | {
+    kind: 'machine';
+};
+export declare function validateBundleTransport(raw: unknown): {
+    transport?: BundleTransport;
+    errors: string[];
+};

package/dist/core/command-plugins/endpoint.js

@@ -49,3 +49,10 @@ export function validateHttpPluginTransport(raw) {
         errors.push(...validateEnvVarName(transport.authEnv).errors);
     return errors.length ? { errors } : { transport: { kind: 'http', endpoint: normalizeEndpoint(transport.endpoint), ...(transport.authEnv !== undefined ? { authEnv: transport.authEnv } : {}) }, errors };
 }
+export function validateBundleTransport(raw) {
+    if (typeof raw === 'object' && raw !== null && !Array.isArray(raw) && raw.kind === 'machine') {
+        const unknown = Object.keys(raw).filter((key) => key !== 'kind');
+        return unknown.length ? { errors: [`transport has unknown keys: ${unknown.join(', ')}`] } : { transport: { kind: 'machine' }, errors: [] };
+    }
+    return validateHttpPluginTransport(raw);
+}

package/dist/types.d.ts

@@ -23,6 +23,10 @@ export type PluginTransport = {
     kind: 'http';
     endpoint: string;
     authEnv?: string;
+}
+/** A provider whose calls go to one of the account's `kind = device` machines over the relay; there is no endpoint. */
+ | {
+    kind: 'machine';
 };
 /** Provenance for a crouter-materialized HTTP plugin directory archive. */
 export interface PluginBundle {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.453",
+  "version": "0.3.455",
   "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
   "type": "module",
   "main": "./dist/api/index.js",