@loomcycle/client 1.106.0 → 1.107.0

package/README.md

@@ -323,6 +323,77 @@ const { entries } = await client.listVolumes();
 
 Refusals throw `SubstrateToolRefusedError` (collision with a static volume name, no `dynamic_root` configured, cross-tenant); transport failures throw the usual typed errors.
 
+### Decision models
+
+Ask a **decision model** typed questions about a piece of text and get each answer with its probabilities. A decision model does not write: it reads the `state` you give it and answers a choice, a yes/no or a score, so there is no reply to parse and a call costs a few output tokens. Use it to route, gate, rank or grade text you already have. No run is involved; the tokens are charged to the caller and count against its token budget.
+
+| Method | Returns | Notes |
+|---|---|---|
+| `decide(req: DecideRequest)` | `Promise<DecideResponse>` | `{model?, state, questions}` → `{model, provider, served_model, answers, usage}`. Mirrors `POST /v1/_decide`. |
+| `listDecisionModels()` | `Promise<DecisionModelsResponse>` | The models a call may name, each with its limits, and the default. Mirrors `GET /v1/_decide/models`. |
+
+`questions` is keyed by names you choose, and each answer comes back under its question's name. `criteria` is typed per question type:
+
+| `type` | `criteria` | Answer |
+|---|---|---|
+| `choice` | required — `Record<string, string \| null>`: each key is an option, its value describes it (`null` when the key explains itself) | `{type, choice, probabilities, confidence}` |
+| `noul` | optional — `{true?: string; false?: string}` | `{type, noul}` — the probability of YES, 0 to 1 |
+| `score` | required — `string[]`, level descriptions **lowest first** | `{type, score, legend, probabilities, confidence}` — `score` is the expected position, counted from 0 |
+
+```ts
+const res = await client.decide({
+  state: { ticket: "My invoice for March was charged twice and I want my money back." },
+  questions: {
+    route: {
+      type: "choice",
+      instructions: "Which team should handle this ticket?",
+      criteria: { billing: "invoices, refunds, charges", support: "bugs, outages", sales: null },
+    },
+    urgent: { type: "noul", instructions: "Does this ticket need a reply within the hour?" },
+    detail: {
+      type: "score",
+      instructions: "How complete is the problem report?",
+      criteria: ["no detail", "some detail", "everything needed"],
+    },
+  },
+});
+
+const route = res.answers.route;
+if (route?.type === "choice") console.log(route.choice, route.probabilities);
+const urgent = res.answers.urgent;
+if (urgent?.type === "noul" && urgent.noul > 0.5) escalate();
+```
+
+- **`noul: 0` is an answer** (a definite no), not a missing one — never test it for truthiness.
+- **The probabilities are not calibrated.** Compare options within one answer; do not treat a fixed threshold as a guarantee.
+- **An answer is the model's own JSON, passed through unchanged.** The answer types name the documented fields and stay open to others, so a field a later model adds is readable without an adapter release.
+- Omit `model` for the deployment's default; name one only from `listDecisionModels()`.
+
+A refusal throws with the decision's own code on `e.code` (see [Errors](#errors)):
+
+| Status | `e.code` | What to do |
+|---|---|---|
+| 400 | `invalid_input` / `bad_question` / `bad_options` / `too_many_questions` | Fix the request; the message names the fault. |
+| 400 | `model_not_allowed` | Omit `model`, or use a name from `listDecisionModels()`. |
+| 403 | `operator_key_restricted` | The caller may not use the operator's provider key and has none of its own. Do not retry. |
+| 413 | `prompt_too_large` | The request does not fit the model's context and is never shortened for you: shorten `state` or ask fewer questions. |
+| 429 | `token_limit_exceeded` | The caller is at a hard token budget. Retrying does not help until the budget is raised or the month rolls over. |
+| 502 | `model_not_found` / `call_failed` | The provider does not serve that model (the same call fails again) / the call did not complete (try once more). |
+| 503 | `decision_not_configured` | This deployment declares no decision models. Do not retry. |
+| 504 | `timeout` | Send the same call again; if it repeats, make it smaller. |
+
+```ts
+try {
+  await client.decide(req);
+} catch (e) {
+  if (e instanceof LoomcycleError && e.code === "prompt_too_large") {
+    // shorten state and retry
+  } else throw e;
+}
+```
+
+Two of these have a class of their own: a `prompt_too_large` throws `PromptTooLargeError` and a `token_limit_exceeded` throws `TokenLimitExceededError` (with the budget on `e.scope` / `e.used` / `e.limit`). For the rest, branch on `e.code`, not on the class: the class follows the HTTP status alone.
+
 ### Channels + run-state stream (v0.9.x n8n Phase 0)
 
 Two substrate-side surfaces added in the n8n integration's Phase 0 wire-API work. Useful for any orchestrator (not just n8n) that needs to see channel state or subscribe to run-state transitions.
@@ -458,6 +529,8 @@ These events are part of the persisted transcript (not the live `runStreaming` e
 
 Non-2xx responses throw typed subclasses of `LoomcycleError`. The original HTTP status is on `e.status`; the truncated response body is on `e.bodyText` (≤1 KiB).
 
+When the error body is JSON with a string `code` (`token_limit_exceeded`, `per_user_quota_exhausted`, `model_not_allowed`, …), that code is on `e.code`, whichever class the status maps to. A status is shared between unrelated conditions — a 429 is backpressure, a per-user quota or a token budget — so branch on `e.code` when you need to tell them apart. It is `undefined` for a plain-text body.
+
 | HTTP status / body | Exception class |
 |---|---|
 | 400 | `InvalidArgumentError` |
@@ -472,13 +545,42 @@ Non-2xx responses throw typed subclasses of `LoomcycleError`. The original HTTP
 | 409 + "session" | `SessionBusyError` |
 | 409 + "agent_id" | `AgentIDInUseError` |
 | 409 (other) | `LoomcycleError` (base) |
-| 413 | `SnapshotTooLargeError` |
+| 413 + code `snapshot_too_large` | `SnapshotTooLargeError` ⎫ |
+| 413 + code `prompt_too_large` | `PromptTooLargeError` ⎬ all are `instanceof SnapshotTooLargeError` (back-compat) |
+| 413 (other) | `RequestTooLargeError` ⎭ |
 | 422 | `SnapshotVersionError` |
-| 429 | `BackpressureError` |
+| 429 + code `per_user_quota_exhausted` | `PerUserQuotaExhaustedError` |
+| 429 + code `token_limit_exceeded` | `TokenLimitExceededError` (subclass of `BackpressureError` — back-compat) |
+| 429 (other) | `BackpressureError` |
 | 503 + "pause manager not configured" | `PauseNotConfiguredError` (subclass of `UnavailableError` — back-compat) |
 | 503 (other) | `UnavailableError` |
 | 500 / other | `LoomcycleError` (base) |
 
+**429: a token budget is not backpressure.** A plain `BackpressureError` is transient: the server is busy, back off and retry. `TokenLimitExceededError` is not: the caller is at a hard token budget (run creation and `decide()` both refuse with it), and the same call is refused until the budget is raised or the calendar month rolls over. It extends `BackpressureError` only so that an existing `instanceof BackpressureError` keeps catching it, so test for it first. The client never retries on its own; this matters to your retry loop.
+
+```ts
+import { BackpressureError, TokenLimitExceededError } from "@loomcycle/client";
+
+try {
+  for await (const ev of client.runStreaming({ /* ... */ })) {}
+} catch (e) {
+  if (e instanceof TokenLimitExceededError) {
+    // Not retryable now. e.scope is "operator" | "tenant" | "user"; e.scopeId is
+    // the tenant or user (null for the operator-wide budget); e.used and e.limit
+    // are tokens; e.window is "month". Each is null if the server did not send it.
+    console.error(`token budget reached for ${e.scope}: ${e.used}/${e.limit} this ${e.window}`);
+  } else if (e instanceof BackpressureError) {
+    // Transient: back off and retry.
+  } else {
+    throw e;
+  }
+}
+```
+
+**413: three classes, one legacy base.** Every 413 used to throw `SnapshotTooLargeError`, whatever was too large. A 413 is now named for its cause: `PromptTooLargeError` for a `decide()` request that does not fit the model's context (shorten `state` or ask fewer questions), `RequestTooLargeError` for any other non-snapshot 413 (a request body over the server's limit, a memory value or quota, a channel payload — `e.code` says which), and `SnapshotTooLargeError` itself for a snapshot over its cap. `PromptTooLargeError` extends `RequestTooLargeError`, which extends `SnapshotTooLargeError`, so an existing `instanceof SnapshotTooLargeError` still matches every 413; that relation is for compatibility and says nothing about snapshots. To single out a snapshot that is too large, test `e.code === "snapshot_too_large"`.
+
+`e.name` (and the `meta_reason` of a `stream_close` frame) is the most specific class name, so it reads `TokenLimitExceededError`, `PromptTooLargeError` or `RequestTooLargeError` where it used to read `BackpressureError` or `SnapshotTooLargeError`. Match with `instanceof` or `e.code`, not on the name.
+
 Priority within `404`: most-specific keyword wins (`snapshot` → `session` → `hook` → `agent` → base). The dispatch is keyword-matched on the response body lowercase; a hook with id `hook_agent_scan` still routes to `HookNotFoundError`, not `AgentNotFoundError`.
 
 ```ts

package/dist/cjs/client.js

@@ -772,6 +772,36 @@ class LoomcycleClient {
             params.set("tenant", opts.tenant);
         return (0, fetch_helpers_js_1.deleteRequest)(this.ctx, `/v1/_limits?${params.toString()}`, opts);
     }
+    /** Ask a decision model typed questions (`choice` / `noul` / `score`) about
+     *  `state` and get each answer with its probabilities. A decision model does
+     *  not write: there is no reply to parse and the call costs a few output
+     *  tokens. No run is involved; the tokens are charged to the caller and count
+     *  against its token budget. Mirrors `POST /v1/_decide`.
+     *
+     *  A refusal throws with the decision's own code on `e.code` and the HTTP
+     *  status on `e.status`: 400 `invalid_input` / `bad_question` / `bad_options`
+     *  / `too_many_questions` / `model_not_allowed`, 403
+     *  `operator_key_restricted`, 413 `prompt_too_large`, 429
+     *  `token_limit_exceeded`, 502 `model_not_found` / `call_failed`, 503
+     *  `decision_not_configured`, 504 `timeout`. Branch on the code: apart from
+     *  `PromptTooLargeError` (413) and `TokenLimitExceededError` (429), the
+     *  error class follows the status alone, and a status is shared with
+     *  unrelated conditions. */
+    async decide(req, opts) {
+        const body = {
+            state: req.state,
+            questions: req.questions,
+        };
+        if (req.model !== undefined)
+            body.model = req.model;
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_decide", body, opts);
+    }
+    /** The decision models a {@link decide} call may name, with each one's
+     *  limits, and the default. Throws with `code: "decision_not_configured"`
+     *  (503) on a deployment that declares none. Mirrors `GET /v1/_decide/models`. */
+    async listDecisionModels(opts) {
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, "/v1/_decide/models", opts);
+    }
     /** Read the full event log for a session. Each entry has seq,
      *  run_id, ts_ns, type, event (the providers.Event payload). */
     async getTranscript(sessionId, opts) {

package/dist/cjs/errors.js

@@ -19,15 +19,22 @@
  * to raise typed errors via `raiseFromResponse`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SubstrateToolRefusedError = exports.ChannelCursorRegressionError = exports.SnapshotVersionError = exports.SnapshotTooLargeError = exports.SnapshotNotFoundError = exports.NotPausedError = exports.AlreadyPausingError = exports.PauseNotConfiguredError = exports.InvalidArgumentError = exports.UnavailableError = exports.AuthError = exports.PerUserQuotaExhaustedError = exports.BackpressureError = exports.AgentIDInUseError = exports.SessionBusyError = exports.SessionNotFoundError = exports.AgentNotFoundError = exports.NotFoundError = exports.LoomcycleError = void 0;
+exports.SubstrateToolRefusedError = exports.ChannelCursorRegressionError = exports.SnapshotVersionError = exports.PromptTooLargeError = exports.RequestTooLargeError = exports.SnapshotTooLargeError = exports.SnapshotNotFoundError = exports.NotPausedError = exports.AlreadyPausingError = exports.PauseNotConfiguredError = exports.InvalidArgumentError = exports.UnavailableError = exports.AuthError = exports.PerUserQuotaExhaustedError = exports.TokenLimitExceededError = exports.BackpressureError = exports.AgentIDInUseError = exports.SessionBusyError = exports.SessionNotFoundError = exports.AgentNotFoundError = exports.NotFoundError = exports.LoomcycleError = void 0;
 class LoomcycleError extends Error {
     status;
     bodyText;
+    /** The machine-readable `code` of a JSON error body (`model_not_allowed`,
+     *  `token_limit_exceeded`, `per_user_quota_exhausted`, …), on whichever
+     *  class the status maps to. Undefined when the body is not JSON or carries
+     *  no string `code`. Read from the whole body, so it survives where
+     *  `bodyText` is cut at 1 KiB. Branch on this, not on the message. */
+    code;
     constructor(message, opts) {
         super(message);
         this.name = "LoomcycleError";
         this.status = opts?.status;
         this.bodyText = opts?.bodyText;
+        this.code = opts?.code;
     }
 }
 exports.LoomcycleError = LoomcycleError;
@@ -71,6 +78,10 @@ class AgentIDInUseError extends LoomcycleError {
     }
 }
 exports.AgentIDInUseError = AgentIDInUseError;
+/** Every HTTP 429 that is not a per-user quota. A plain BackpressureError is
+ *  the transient case (the server is busy; back off and retry). It has one
+ *  subclass that is NOT transient, TokenLimitExceededError — check for that
+ *  first when deciding whether to retry. */
 class BackpressureError extends LoomcycleError {
     constructor(message, opts) {
         super(message, opts);
@@ -78,6 +89,51 @@ class BackpressureError extends LoomcycleError {
     }
 }
 exports.BackpressureError = BackpressureError;
+/**
+ * TokenLimitExceededError signals that the caller is at a hard token budget:
+ * HTTP 429 with body code `token_limit_exceeded`, from run creation and from
+ * `decide()`.
+ *
+ * Do not retry it the way you retry backpressure. The budget is a calendar
+ * month's tokens for an operator, tenant or user; the same call is refused
+ * until an operator raises the budget or the window rolls over.
+ *
+ * It extends BackpressureError only so that code written before this class
+ * existed, which caught this refusal with `instanceof BackpressureError`,
+ * keeps catching it. Test for this class BEFORE BackpressureError:
+ *
+ *   if (e instanceof TokenLimitExceededError) {
+ *     // not retryable now: report e.scope / e.used / e.limit
+ *   } else if (e instanceof BackpressureError) {
+ *     // transient: back off and retry
+ *   }
+ *
+ * The fields come from the response body and are null when the server did
+ * not send them.
+ */
+class TokenLimitExceededError extends BackpressureError {
+    /** Whose budget was hit: "operator", "tenant" or "user". */
+    scope;
+    /** The id of that scope: the tenant id or the user subject. Null for the
+     *  operator-wide budget, and where the server withholds it. */
+    scopeId;
+    /** Tokens the scope has used in the current window. */
+    used;
+    /** The hard ceiling that was reached, in tokens. */
+    limit;
+    /** The budget window, e.g. "month" (a calendar month, UTC). */
+    window;
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "TokenLimitExceededError";
+        this.scope = opts?.scope ?? null;
+        this.scopeId = opts?.scopeId ?? null;
+        this.used = opts?.used ?? null;
+        this.limit = opts?.limit ?? null;
+        this.window = opts?.window ?? null;
+    }
+}
+exports.TokenLimitExceededError = TokenLimitExceededError;
 /**
  * PerUserQuotaExhaustedError signals that the caller has hit their
  * per-user cap on in-flight (active+queued) runs. Distinct from
@@ -182,6 +238,14 @@ class SnapshotNotFoundError extends NotFoundError {
     }
 }
 exports.SnapshotNotFoundError = SnapshotNotFoundError;
+/** A snapshot envelope over the size cap (HTTP 413, body code
+ *  `snapshot_too_large`).
+ *
+ *  For compatibility it is ALSO the base class of every other 413: until
+ *  RequestTooLargeError and PromptTooLargeError existed, the client raised
+ *  this class for any 413, so `instanceof SnapshotTooLargeError` is true for
+ *  all of them and stays true. To single out a snapshot that is too large,
+ *  test `e.code === "snapshot_too_large"`. */
 class SnapshotTooLargeError extends LoomcycleError {
     constructor(message, opts) {
         super(message, opts);
@@ -189,6 +253,32 @@ class SnapshotTooLargeError extends LoomcycleError {
     }
 }
 exports.SnapshotTooLargeError = SnapshotTooLargeError;
+/** An HTTP 413 that is not about a snapshot: a request body over the server's
+ *  size limit (`request_too_large`, or a plain-text 413 with no code), a
+ *  memory value or quota (`memory_value_too_large`, `memory_quota_exceeded`),
+ *  a channel payload (`payload_too_large`). `e.code` says which.
+ *
+ *  It extends SnapshotTooLargeError only because that is the class these
+ *  responses were raised as before this one existed; the relation keeps an
+ *  existing `instanceof SnapshotTooLargeError` matching and says nothing about
+ *  snapshots. */
+class RequestTooLargeError extends SnapshotTooLargeError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "RequestTooLargeError";
+    }
+}
+exports.RequestTooLargeError = RequestTooLargeError;
+/** A `decide()` request that does not fit the decision model's context (HTTP
+ *  413, body code `prompt_too_large`). The server never shortens it for you:
+ *  shorten `state` or ask fewer questions, then send it again. */
+class PromptTooLargeError extends RequestTooLargeError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "PromptTooLargeError";
+    }
+}
+exports.PromptTooLargeError = PromptTooLargeError;
 class SnapshotVersionError extends LoomcycleError {
     constructor(message, opts) {
         super(message, opts);

package/dist/cjs/fetch-helpers.js

@@ -178,15 +178,23 @@ async function deleteJSON(ctx, path, opts) {
  *   409 + "session"                            → SessionBusyError
  *   409 + "agent_id"                           → AgentIDInUseError
  *   409 + (other)                              → LoomcycleError (base)
- *   413         → SnapshotTooLargeError
+ *   413 + code "snapshot_too_large" → SnapshotTooLargeError ──┐ all are
+ *   413 + code "prompt_too_large"   → PromptTooLargeError     │ instanceof
+ *   413 (other)                     → RequestTooLargeError ───┘ SnapshotTooLargeError
  *   422         → SnapshotVersionError (snapshot-version-too-new/unknown)
- *   429         → BackpressureError
+ *   429 + code "per_user_quota_exhausted" → PerUserQuotaExhaustedError
+ *   429 + code "token_limit_exceeded"     → TokenLimitExceededError
+ *                                           (subclass of BackpressureError)
+ *   429 (other)                           → BackpressureError
  *   503 + "pause manager not configured" → PauseNotConfiguredError
  *                                          (subclass of UnavailableError)
  *   503 + (other)                        → UnavailableError
  *   500-599 (other) → LoomcycleError (base)
  *   default     → LoomcycleError (base)
  *
+ * Whatever class the status maps to, a JSON body's string `code` is on the
+ * error as `code` (see bodyCode).
+ *
  * Priority within a status group is most-specific-first; an unknown
  * 409 falls through to base LoomcycleError so callers see a
  * meaningful message + status. For 404, the catch-all is NotFoundError
@@ -212,7 +220,7 @@ async function raiseFromResponse(resp) {
     // ("401 Unauthorized" not "401 " with a trailing space).
     const statusPhrase = resp.statusText || stockStatusPhrase(status);
     const msg = bodyText.trim() ? bodyText.slice(0, 1024) : `${status} ${statusPhrase}`;
-    const opts = { status, bodyText: bodyText.slice(0, 1024) };
+    const opts = { status, bodyText: bodyText.slice(0, 1024), code: bodyCode(bodyText) };
     switch (status) {
         case 400:
             throw new errors_js_1.InvalidArgumentError(msg, opts);
@@ -248,7 +256,14 @@ async function raiseFromResponse(resp) {
                 throw new errors_js_1.AgentIDInUseError(msg, opts);
             throw new errors_js_1.LoomcycleError(msg, opts);
         case 413:
-            throw new errors_js_1.SnapshotTooLargeError(msg, opts);
+            // Every 413 used to be a SnapshotTooLargeError, so the two classes
+            // below extend it: an existing `instanceof SnapshotTooLargeError`
+            // still matches all three.
+            if (opts.code === "snapshot_too_large")
+                throw new errors_js_1.SnapshotTooLargeError(msg, opts);
+            if (opts.code === "prompt_too_large")
+                throw new errors_js_1.PromptTooLargeError(msg, opts);
+            throw new errors_js_1.RequestTooLargeError(msg, opts);
         case 422: {
             // 422 is shared between snapshot version errors (existing)
             // and v0.8.22 substrate tool refusals. Discriminate by body:
@@ -257,7 +272,7 @@ async function raiseFromResponse(resp) {
             try {
                 const parsed = JSON.parse(bodyText);
                 if (parsed.code === "tool_refused") {
-                    throw new errors_js_1.SubstrateToolRefusedError(parsed.error ?? msg, { status, bodyText, tool: parsed.tool });
+                    throw new errors_js_1.SubstrateToolRefusedError(parsed.error ?? msg, { status, bodyText, code: parsed.code, tool: parsed.tool });
                 }
             }
             catch (e) {
@@ -269,6 +284,20 @@ async function raiseFromResponse(resp) {
             throw new errors_js_1.SnapshotVersionError(msg, opts);
         }
         case 429: {
+            // A hard token budget is not transient the way backpressure is, so
+            // it gets its own class (a BackpressureError subclass, for callers
+            // that already catch that).
+            if (opts.code === "token_limit_exceeded") {
+                const body = bodyObject(bodyText) ?? {};
+                throw new errors_js_1.TokenLimitExceededError(msg, {
+                    ...opts,
+                    scope: stringField(body.scope),
+                    scopeId: stringField(body.scope_id),
+                    used: numberField(body.used),
+                    limit: numberField(body.limit),
+                    window: stringField(body.window),
+                });
+            }
             // v0.10.1: distinguish per-user quota exhaustion from
             // operator-wide backpressure. The shapes share the 429 status
             // but the JSON body's `code` field discriminates. Consumers
@@ -284,6 +313,7 @@ async function raiseFromResponse(resp) {
                     throw new errors_js_1.PerUserQuotaExhaustedError(parsed.error ?? msg, {
                         status,
                         bodyText,
+                        code: parsed.code,
                         userId: parsed.user_id,
                         cap: parsed.cap,
                         retryAfterMs: Number.isFinite(retryAfterMs) ? retryAfterMs : undefined,
@@ -305,6 +335,36 @@ async function raiseFromResponse(resp) {
             throw new errors_js_1.LoomcycleError(msg, opts);
     }
 }
+/** bodyCode returns the string `code` of a JSON error body, or undefined when
+ *  the body is not a JSON object or has none. Statuses are shared between
+ *  unrelated conditions (a 400 is any bad request; a 429 is backpressure, a
+ *  user quota or a token budget), and the code is what tells them apart. */
+function bodyCode(bodyText) {
+    return stringField(bodyObject(bodyText)?.code);
+}
+/** bodyObject returns a JSON error body as an object, or undefined when the
+ *  body is not JSON or is a JSON array or scalar. */
+function bodyObject(bodyText) {
+    try {
+        const parsed = JSON.parse(bodyText);
+        if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+    }
+    catch {
+        // not JSON: a plain-text error body has no fields
+    }
+    return undefined;
+}
+/** stringField / numberField read one body field, dropping a value of the
+ *  wrong type: an error's typed fields must not carry whatever a proxy or an
+ *  older server put under that name. An empty string counts as absent. */
+function stringField(v) {
+    return typeof v === "string" && v !== "" ? v : undefined;
+}
+function numberField(v) {
+    return typeof v === "number" && Number.isFinite(v) ? v : undefined;
+}
 /** stockStatusPhrase returns a stock reason phrase for the common
  *  HTTP statuses raiseFromResponse handles. Used as a fallback when
  *  Response.statusText is empty (HTTP/2 strips reason phrases). */

package/dist/cjs/index.js

@@ -116,7 +116,9 @@
  *     AuthError, UnavailableError, InvalidArgumentError,
  *     PauseNotConfiguredError (subclass of UnavailableError),
  *     AlreadyPausingError, NotPausedError, SnapshotNotFoundError,
- *     SnapshotTooLargeError, SnapshotVersionError,
+ *     SnapshotTooLargeError, RequestTooLargeError + PromptTooLargeError
+ *     (both subclasses of SnapshotTooLargeError), TokenLimitExceededError
+ *     (subclass of BackpressureError), SnapshotVersionError,
  *     SubstrateToolRefusedError (v0.8.22)
  *
  * Transport: HTTP+SSE. Auth: Bearer token via the Authorization
@@ -127,7 +129,7 @@
  * See `adapters/ts/README.md` for usage examples.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.UnavailableError = exports.SubstrateToolRefusedError = exports.SnapshotVersionError = exports.SnapshotTooLargeError = exports.SnapshotNotFoundError = exports.SessionNotFoundError = exports.SessionBusyError = exports.PerUserQuotaExhaustedError = exports.PauseNotConfiguredError = exports.NotPausedError = exports.LoomcycleError = exports.ChannelCursorRegressionError = exports.InvalidArgumentError = exports.NotFoundError = exports.BackpressureError = exports.AuthError = exports.AlreadyPausingError = exports.AgentNotFoundError = exports.AgentIDInUseError = exports.CLIENT_TOOL_SUBPROTOCOL = exports.clientToolsURL = exports.ClientToolHost = exports.InteractiveSession = exports.LoomcycleClient = void 0;
+exports.UnavailableError = exports.TokenLimitExceededError = exports.SubstrateToolRefusedError = exports.SnapshotVersionError = exports.SnapshotTooLargeError = exports.SnapshotNotFoundError = exports.SessionNotFoundError = exports.SessionBusyError = exports.RequestTooLargeError = exports.PromptTooLargeError = exports.PerUserQuotaExhaustedError = exports.PauseNotConfiguredError = exports.NotPausedError = exports.LoomcycleError = exports.ChannelCursorRegressionError = exports.InvalidArgumentError = exports.NotFoundError = exports.BackpressureError = exports.AuthError = exports.AlreadyPausingError = exports.AgentNotFoundError = exports.AgentIDInUseError = exports.CLIENT_TOOL_SUBPROTOCOL = exports.clientToolsURL = exports.ClientToolHost = exports.InteractiveSession = exports.LoomcycleClient = void 0;
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "LoomcycleClient", { enumerable: true, get: function () { return client_js_1.LoomcycleClient; } });
 var interactive_js_1 = require("./interactive.js");
@@ -149,10 +151,13 @@ Object.defineProperty(exports, "LoomcycleError", { enumerable: true, get: functi
 Object.defineProperty(exports, "NotPausedError", { enumerable: true, get: function () { return errors_js_1.NotPausedError; } });
 Object.defineProperty(exports, "PauseNotConfiguredError", { enumerable: true, get: function () { return errors_js_1.PauseNotConfiguredError; } });
 Object.defineProperty(exports, "PerUserQuotaExhaustedError", { enumerable: true, get: function () { return errors_js_1.PerUserQuotaExhaustedError; } });
+Object.defineProperty(exports, "PromptTooLargeError", { enumerable: true, get: function () { return errors_js_1.PromptTooLargeError; } });
+Object.defineProperty(exports, "RequestTooLargeError", { enumerable: true, get: function () { return errors_js_1.RequestTooLargeError; } });
 Object.defineProperty(exports, "SessionBusyError", { enumerable: true, get: function () { return errors_js_1.SessionBusyError; } });
 Object.defineProperty(exports, "SessionNotFoundError", { enumerable: true, get: function () { return errors_js_1.SessionNotFoundError; } });
 Object.defineProperty(exports, "SnapshotNotFoundError", { enumerable: true, get: function () { return errors_js_1.SnapshotNotFoundError; } });
 Object.defineProperty(exports, "SnapshotTooLargeError", { enumerable: true, get: function () { return errors_js_1.SnapshotTooLargeError; } });
 Object.defineProperty(exports, "SnapshotVersionError", { enumerable: true, get: function () { return errors_js_1.SnapshotVersionError; } });
 Object.defineProperty(exports, "SubstrateToolRefusedError", { enumerable: true, get: function () { return errors_js_1.SubstrateToolRefusedError; } });
+Object.defineProperty(exports, "TokenLimitExceededError", { enumerable: true, get: function () { return errors_js_1.TokenLimitExceededError; } });
 Object.defineProperty(exports, "UnavailableError", { enumerable: true, get: function () { return errors_js_1.UnavailableError; } });

package/dist/client.d.ts

@@ -25,7 +25,7 @@
  */
 import { InteractiveSession } from "./interactive.js";
 import { ClientToolHost, type ConnectClientToolsOptions } from "./client-tools.js";
-import type { CredentialListResponse, CredentialMeta, CredentialScope, DirectoryInspection, DirectoryTenant, DirectoryUser, ErasureReport, ErasureResult, Agent, AgentEvent, AgentStatus, CancelAgentResult, ClientOptions, ContinueOptions, RunOverrideOptions, EffectiveConfigResponse, RetuneRunResponse, RunConfigResponse, RunPromptResponse, CreateSnapshotOptions, EnsureCodeAgentOptions, EnsureCodeAgentResult, EnsureMcpServerOptions, EnsureMcpServerResult, HealthResponse, InterruptListResponse, InterruptStatus, WalkRunsPage, AckChannelOptions, AwaitChannelsOptions, BroadcastChannelsOptions, ChannelAckResult, ChannelAwaitResult, ChannelBroadcastResult, ChannelDescriptor, ChannelPeekResult, ChannelPublishResult, ChannelPurgeResult, ChannelReleaseResult, ChannelSubscribeResult, CreateChannelOptions, ListChannelsResponse, PeekChannelOptions, PublishChannelOptions, ReleaseChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, SubscribeChannelOptions, UpdateChannelOptions, LibraryAgentDefinition, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, ListUsersResponse, UserRecord, CreateUserBody, UpdateUserBody, MintedUserToken, ListUserTokensResponse, RunnableAgentsResponse, LLMChatOptions, LLMChatResponse, LLMChatStreamItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, MCPServerDefVerifyResult, MemoryEmbedStatsResponse, MemoryEntriesResponse, MemoryEntryResponse, MemoryBackfillResponse, MemoryPurgeResponse, MemoryReembedResponse, MemoryScopeIDsResponse, MemoryScopesResponse, MemorySearchInput, MemorySearchResponse, PauseResult, PersistentVolumesResponse, EphemeralVolumesResponse, ResolveInterruptOptions, ResumeResult, ResolverMatrix, CompactRunResult, ReplaySessionResult, CancelTurnResult, ReviewRunResult, RunBatchOptions, RunBatchResult, RunOptions, ConfiguredRun, ConfiguredRunPatch, RunStateStreamItem, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, StreamUserRunStatesOptions, SubstrateToolInput, SubstrateToolResponse, CreatedTeam, ListTeamsResponse, PromotedTeam, RetiredTeam, TeamBreakpoints, TeamDefDetail, TeamRunDetached, TeamRunTarget, TeamVerification, TeamDraft, TeamDraftVerification, TeamVersionList, TeamDiagram, TeamRunResult, PathToolInput, PathToolResponse, DocumentToolInput, DocumentToolResponse, HistoryToolInput, HistoryToolResponse, TranscriptResponse, WhoamiResponse, UsageDimension, UsageReportResponse, TokenLimit, TokenLimitsResponse, ConfigResponse, SetTokenLimitRequest } from "./types.js";
+import type { CredentialListResponse, CredentialMeta, DecideRequest, DecideResponse, DecisionModelsResponse, CredentialScope, DirectoryInspection, DirectoryTenant, DirectoryUser, ErasureReport, ErasureResult, Agent, AgentEvent, AgentStatus, CancelAgentResult, ClientOptions, ContinueOptions, RunOverrideOptions, EffectiveConfigResponse, RetuneRunResponse, RunConfigResponse, RunPromptResponse, CreateSnapshotOptions, EnsureCodeAgentOptions, EnsureCodeAgentResult, EnsureMcpServerOptions, EnsureMcpServerResult, HealthResponse, InterruptListResponse, InterruptStatus, WalkRunsPage, AckChannelOptions, AwaitChannelsOptions, BroadcastChannelsOptions, ChannelAckResult, ChannelAwaitResult, ChannelBroadcastResult, ChannelDescriptor, ChannelPeekResult, ChannelPublishResult, ChannelPurgeResult, ChannelReleaseResult, ChannelSubscribeResult, CreateChannelOptions, ListChannelsResponse, PeekChannelOptions, PublishChannelOptions, ReleaseChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, SubscribeChannelOptions, UpdateChannelOptions, LibraryAgentDefinition, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, ListUsersResponse, UserRecord, CreateUserBody, UpdateUserBody, MintedUserToken, ListUserTokensResponse, RunnableAgentsResponse, LLMChatOptions, LLMChatResponse, LLMChatStreamItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, MCPServerDefVerifyResult, MemoryEmbedStatsResponse, MemoryEntriesResponse, MemoryEntryResponse, MemoryBackfillResponse, MemoryPurgeResponse, MemoryReembedResponse, MemoryScopeIDsResponse, MemoryScopesResponse, MemorySearchInput, MemorySearchResponse, PauseResult, PersistentVolumesResponse, EphemeralVolumesResponse, ResolveInterruptOptions, ResumeResult, ResolverMatrix, CompactRunResult, ReplaySessionResult, CancelTurnResult, ReviewRunResult, RunBatchOptions, RunBatchResult, RunOptions, ConfiguredRun, ConfiguredRunPatch, RunStateStreamItem, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, StreamUserRunStatesOptions, SubstrateToolInput, SubstrateToolResponse, CreatedTeam, ListTeamsResponse, PromotedTeam, RetiredTeam, TeamBreakpoints, TeamDefDetail, TeamRunDetached, TeamRunTarget, TeamVerification, TeamDraft, TeamDraftVerification, TeamVersionList, TeamDiagram, TeamRunResult, PathToolInput, PathToolResponse, DocumentToolInput, DocumentToolResponse, HistoryToolInput, HistoryToolResponse, TranscriptResponse, WhoamiResponse, UsageDimension, UsageReportResponse, TokenLimit, TokenLimitsResponse, ConfigResponse, SetTokenLimitRequest } from "./types.js";
 export declare class LoomcycleClient {
     private ctx;
     constructor(opts?: ClientOptions);
@@ -464,6 +464,30 @@ export declare class LoomcycleClient {
         tenant?: string;
         signal?: AbortSignal;
     }): Promise<void>;
+    /** Ask a decision model typed questions (`choice` / `noul` / `score`) about
+     *  `state` and get each answer with its probabilities. A decision model does
+     *  not write: there is no reply to parse and the call costs a few output
+     *  tokens. No run is involved; the tokens are charged to the caller and count
+     *  against its token budget. Mirrors `POST /v1/_decide`.
+     *
+     *  A refusal throws with the decision's own code on `e.code` and the HTTP
+     *  status on `e.status`: 400 `invalid_input` / `bad_question` / `bad_options`
+     *  / `too_many_questions` / `model_not_allowed`, 403
+     *  `operator_key_restricted`, 413 `prompt_too_large`, 429
+     *  `token_limit_exceeded`, 502 `model_not_found` / `call_failed`, 503
+     *  `decision_not_configured`, 504 `timeout`. Branch on the code: apart from
+     *  `PromptTooLargeError` (413) and `TokenLimitExceededError` (429), the
+     *  error class follows the status alone, and a status is shared with
+     *  unrelated conditions. */
+    decide(req: DecideRequest, opts?: {
+        signal?: AbortSignal;
+    }): Promise<DecideResponse>;
+    /** The decision models a {@link decide} call may name, with each one's
+     *  limits, and the default. Throws with `code: "decision_not_configured"`
+     *  (503) on a deployment that declares none. Mirrors `GET /v1/_decide/models`. */
+    listDecisionModels(opts?: {
+        signal?: AbortSignal;
+    }): Promise<DecisionModelsResponse>;
     /** Read the full event log for a session. Each entry has seq,
      *  run_id, ts_ns, type, event (the providers.Event payload). */
     getTranscript(sessionId: string, opts?: {

package/dist/client.js

@@ -769,6 +769,36 @@ export class LoomcycleClient {
             params.set("tenant", opts.tenant);
         return deleteRequest(this.ctx, `/v1/_limits?${params.toString()}`, opts);
     }
+    /** Ask a decision model typed questions (`choice` / `noul` / `score`) about
+     *  `state` and get each answer with its probabilities. A decision model does
+     *  not write: there is no reply to parse and the call costs a few output
+     *  tokens. No run is involved; the tokens are charged to the caller and count
+     *  against its token budget. Mirrors `POST /v1/_decide`.
+     *
+     *  A refusal throws with the decision's own code on `e.code` and the HTTP
+     *  status on `e.status`: 400 `invalid_input` / `bad_question` / `bad_options`
+     *  / `too_many_questions` / `model_not_allowed`, 403
+     *  `operator_key_restricted`, 413 `prompt_too_large`, 429
+     *  `token_limit_exceeded`, 502 `model_not_found` / `call_failed`, 503
+     *  `decision_not_configured`, 504 `timeout`. Branch on the code: apart from
+     *  `PromptTooLargeError` (413) and `TokenLimitExceededError` (429), the
+     *  error class follows the status alone, and a status is shared with
+     *  unrelated conditions. */
+    async decide(req, opts) {
+        const body = {
+            state: req.state,
+            questions: req.questions,
+        };
+        if (req.model !== undefined)
+            body.model = req.model;
+        return postJSON(this.ctx, "/v1/_decide", body, opts);
+    }
+    /** The decision models a {@link decide} call may name, with each one's
+     *  limits, and the default. Throws with `code: "decision_not_configured"`
+     *  (503) on a deployment that declares none. Mirrors `GET /v1/_decide/models`. */
+    async listDecisionModels(opts) {
+        return jsonFetch(this.ctx, "/v1/_decide/models", opts);
+    }
     /** Read the full event log for a session. Each entry has seq,
      *  run_id, ts_ns, type, event (the providers.Event payload). */
     async getTranscript(sessionId, opts) {