@north-light/api 0.3.459 → 0.3.460

package/dist/core/io.d.ts

@@ -59,6 +59,9 @@ interface ErrorPayloadBase {
     http_status?: number;
     /** Seconds the provider asked the caller to wait before retrying (a rate limit). */
     retry_after_s?: number;
+    /** The structured details the runtime attached to a refusal the caller must act on (a `machine_required`
+     *  answer's `candidates`). Rendered below the message and kept in `--json`. */
+    details?: Record<string, unknown>;
     next: string;
 }
 export type ErrorPayload = ErrorPayloadBase & ({
@@ -116,9 +119,16 @@ export declare function diag(message: string): void;
  *      under the daemon's coarse `provider_*` code and the provider's HTTP
  *      status. The provider's code, `next`, `field` and `Retry-After` reach the
  *      caller unchanged; the status→code map would flatten them to `conflict`.
- *   4. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
+ *   4. A refusal the runtime itself rendered for `provider.call` (`options.providerCall`):
+ *      its envelope code came from the runtime's own table (`machine_required`,
+ *      `device_offline`, …), not from the HTTP status, so it is kept together with
+ *      its `details`. The caller of `provider.call` is the only one who knows the
+ *      envelope is that endpoint's, which is why this is an option and not inferred.
+ *   5. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
  *      and a caller-supplied-or-default `next`. */
-export declare function apiErrorToCliError(err: ApiError, next?: string): CrtrError;
+export declare function apiErrorToCliError(err: ApiError, next?: string, options?: {
+    providerCall?: boolean;
+}): CrtrError;
 /** Terminal error handler. Command-level failures (bad input, not-found,
  *  ambiguous) surface as the JSON response on stdout so the caller parses one
  *  contract. A daemon `ApiError` is translated to that same clean contract

package/dist/core/io.js

@@ -190,6 +190,9 @@ export function diag(message) {
     process.stderr.write(message + '\n');
 }
 // errors
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
 function payloadOf(e) {
     if (e instanceof InputError)
         return e.payload;
@@ -210,6 +213,7 @@ function payloadOf(e) {
         field: d.field,
         ...(typeof d.http_status === 'number' ? { http_status: d.http_status } : {}),
         ...(typeof d.retry_after_s === 'number' ? { retry_after_s: d.retry_after_s } : {}),
+        ...(isRecord(d.details) ? { details: d.details } : {}),
     };
     return result === undefined
         ? { ...base, next }
@@ -280,9 +284,14 @@ const STATUS_TO_CLI_CODE = {
  *      under the daemon's coarse `provider_*` code and the provider's HTTP
  *      status. The provider's code, `next`, `field` and `Retry-After` reach the
  *      caller unchanged; the status→code map would flatten them to `conflict`.
- *   4. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
+ *   4. A refusal the runtime itself rendered for `provider.call` (`options.providerCall`):
+ *      its envelope code came from the runtime's own table (`machine_required`,
+ *      `device_offline`, …), not from the HTTP status, so it is kept together with
+ *      its `details`. The caller of `provider.call` is the only one who knows the
+ *      envelope is that endpoint's, which is why this is an option and not inferred.
+ *   5. Otherwise map status→code (`STATUS_TO_CLI_CODE`) with the server message
  *      and a caller-supplied-or-default `next`. */
-export function apiErrorToCliError(err, next) {
+export function apiErrorToCliError(err, next, options = {}) {
     // A handover is NOT a down daemon: the successor is already up (the client
     // waited for its /healthz), so telling anyone to start one is wrong — the
     // only thing left is to re-issue the call.
@@ -304,12 +313,15 @@ export function apiErrorToCliError(err, next) {
     // A responding daemon can relay an unavailable provider or storage service.
     // HTTP 503 alone does not mean that crtrd is down.
     const d = err.details;
-    const provider = providerSupplied(err, d);
-    if (err.status === 503) {
+    const provider = providerSupplied(err, d, options.providerCall === true);
+    // A `device_timeout` the runtime rendered for `provider.call` (504) is the same operational class as a 503.
+    if (err.status === 503 || (options.providerCall === true && err.status === 504 && provider.code !== undefined)) {
         const code = provider.code ?? err.code;
         const details = {
             next: provider.next ?? next ?? 'Retry the command; if it persists, inspect the unavailable service named in the error.',
         };
+        if (provider.details !== undefined)
+            details['details'] = provider.details;
         if (provider.code !== undefined) {
             if (provider.field !== undefined)
                 details['field'] = provider.field;
@@ -333,6 +345,7 @@ export function apiErrorToCliError(err, next) {
             ...(provider.field !== undefined ? { field: provider.field } : {}),
             ...(provider.received !== undefined ? { received: provider.received } : {}),
             ...(provider.retryAfterS !== undefined ? { retry_after_s: provider.retryAfterS } : {}),
+            ...(provider.details !== undefined ? { details: provider.details } : {}),
             message: violations.length > 0 ? `${err.message}: ${violations.join('; ')}` : err.message.trim() !== '' ? err.message : `request refused (HTTP ${err.status}, ${err.code}) with no message`,
             next: provider.next ??
                 next ??
@@ -357,13 +370,32 @@ export function apiErrorToCliError(err, next) {
  *  did not originate at a provider, so non-provider status→code mapping is
  *  untouched. A code that is not a snake_case identifier, or that came with no
  *  provider HTTP status, is ignored. */
-function providerSupplied(err, d) {
+function providerSupplied(err, d, providerCall) {
+    const snake = (code) => typeof code === 'string' && /^[a-z][a-z0-9_]*$/.test(code);
+    // `provider.call` renders every refusal as a runtime envelope (`origin` set) whose `code` the runtime chose from its own
+    // table, so the code stands and `details` is the runtime's structured answer (not a provider's body). A code-less
+    // transport failure the client synthesized has no envelope and stays on the status map.
+    if (providerCall && err.origin !== undefined && err.origin !== 'provider' && snake(err.code)) {
+        const out = { code: err.code };
+        if (err.status === 503 || err.status === 504) {
+            out.next = err.retryable === true
+                ? 'Retry the command; if it persists, the machine or service named in the error is unavailable.'
+                : 'Read the error before retrying: the action may already have run.';
+        }
+        if (isRecord(err.details))
+            out.details = err.details;
+        if (err.param !== undefined)
+            out.field = err.param;
+        if (typeof err.retryAfterS === 'number')
+            out.retryAfterS = err.retryAfterS;
+        return out;
+    }
     if (err.origin !== 'provider' || d === undefined || d === null || typeof d !== 'object')
         return {};
     const out = {};
     // `details.status` is the provider's own HTTP status; the runtime's transport
     // diagnostics (`{status: null, code: 'timeout'}`) are not a provider's code.
-    if (typeof d.status === 'number' && typeof d.code === 'string' && /^[a-z][a-z0-9_]*$/.test(d.code))
+    if (typeof d.status === 'number' && snake(d.code))
         out.code = d.code;
     if (typeof d.next === 'string' && d.next.trim() !== '')
         out.next = d.next;

package/dist/core/render.d.ts

@@ -5,7 +5,7 @@ import type { ErrorPayload } from './io.js';
  *  after. Scalars (and nested objects) list as `- name: value` bullets, prose
  *  fields render as paragraphs, and arrays become a count lead-in plus a table
  *  or bullets. No root tag — the result is read as a continuation of the prompt. */
-export declare function renderResult(result: Record<string, unknown>, help: LeafHelp): string;
+export declare function renderResult(result: Record<string, unknown>, help: Pick<LeafHelp, 'output'>): string;
 /** Render a structured failure as an instruction-shaped block: what broke, what
  *  was received, and the recovery road sign — the same recovery info the JSON
  *  payload carries, shaped for the model to act on. */

package/dist/core/render.js

@@ -131,6 +131,10 @@ export function renderError(p) {
         lines.push(`http status: ${p.http_status}`);
     if (p.retry_after_s !== undefined)
         lines.push(`retry after: ${p.retry_after_s}s`);
+    // The runtime's structured answer (`machine_required`'s candidates): the caller acts on these values, so they are
+    // listed in full, arrays as a table.
+    if (p.details !== undefined && Object.keys(p.details).length > 0)
+        lines.push(renderResult(p.details, { output: [] }));
     if ('primaryCompleted' in p && p.primaryCompleted === true) {
         lines.push('primaryCompleted: true');
         lines.push(`Primary result (the command already completed):\n${fencedJson(p.result)}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@north-light/api",
-  "version": "0.3.459",
+  "version": "0.3.460",
   "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",