@loomcycle/client 1.112.0 → 1.114.0

package/dist/errors.d.ts

@@ -31,6 +31,21 @@ export declare class LoomcycleError extends Error {
         bodyText?: string;
         code?: string;
     });
+    /** Whether the same call, sent again unchanged, can succeed once time has
+     *  passed: true for a refusal that clears on its own (backpressure, a rate
+     *  limit, a per-user run quota, a paused runtime, a decision-model call
+     *  that failed or timed out), false for everything else, including a hard
+     *  token budget, a cap the caller must make room under, a bad request and
+     *  a missing resource. A retry loop can test this instead of a list of
+     *  classes.
+     *
+     *  It is a getter rather than a constructor field so that a subclass states
+     *  its answer by overriding it, without a constructor option any caller
+     *  could set. False is the default because a wrong `true` turns a refusal
+     *  that never clears into a loop that never ends, while a wrong `false`
+     *  only surfaces an error the caller could have waited out. The client
+     *  itself never retries; bound your own retries even when this is true. */
+    get retryable(): boolean;
 }
 /** Base class for every HTTP 404 the client surfaces. Lets callers
  *  catch any not-found case with a single `instanceof NotFoundError`
@@ -72,16 +87,45 @@ export declare class AgentIDInUseError extends LoomcycleError {
         code?: string;
     });
 }
-/** 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. */
+/** An HTTP 429 that clears on its own: the server is busy (`backpressure`),
+ *  a provider's queue is full (`provider_concurrency_exhausted`), or the
+ *  caller is starting runs too fast (`rate_limited`, raised as the
+ *  RateLimitedError subclass). Back off and retry; `retryable` is true.
+ *
+ *  One code under this class is the exception: `configured_run_cap` (the user
+ *  holds as many configured runs as allowed; start or discard one first)
+ *  needs the caller to act, so its `retryable` is false. It stays a
+ *  BackpressureError, the class every other 429 lands in.
+ *
+ *  Two 429s are not this class: a per-user run quota
+ *  (PerUserQuotaExhaustedError, also retryable) and a hard token budget
+ *  (TokenLimitExceededError, not retryable). */
 export declare class BackpressureError extends LoomcycleError {
     constructor(message: string, opts?: {
         status?: number;
         bodyText?: string;
         code?: string;
     });
+    get retryable(): boolean;
+}
+/**
+ * RateLimitedError signals that the caller is starting runs faster than its
+ * per-caller run-start rate allows: HTTP 429 with body code `rate_limited`.
+ * The server says when the next start will be admitted in `Retry-After`,
+ * surfaced here as `retryAfterMs`; wait that long rather than backing off on
+ * a guess. Retryable, like every BackpressureError.
+ */
+export declare class RateLimitedError extends BackpressureError {
+    /** Server-suggested retry window in milliseconds, from the Retry-After
+     *  header. Null when the header is absent or not a whole number of
+     *  seconds. */
+    readonly retryAfterMs: number | null;
+    constructor(message: string, opts?: {
+        status?: number;
+        bodyText?: string;
+        code?: string;
+        retryAfterMs?: number;
+    });
 }
 /**
  * TokenLimitExceededError signals that the caller is at a hard token budget:
@@ -92,20 +136,18 @@ export declare class BackpressureError extends LoomcycleError {
  * 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
- *   }
+ * It is not a BackpressureError, and `retryable` is false. It used to
+ * extend BackpressureError so that an older `instanceof BackpressureError`
+ * check kept catching it, but such a check is almost always a retry loop, and
+ * that loop then retried a refusal that cannot clear for the rest of the
+ * month. The relation was dropped on purpose: a retry loop keyed on
+ * BackpressureError or on `retryable` now stops here, and code that wants to
+ * report the budget tests for this class.
  *
  * The fields come from the response body and are null when the server did
  * not send them.
  */
-export declare class TokenLimitExceededError extends BackpressureError {
+export declare class TokenLimitExceededError extends LoomcycleError {
     /** Whose budget was hit: "operator", "tenant" or "user". */
     readonly scope: string | null;
     /** The id of that scope: the tenant id or the user subject. Null for the
@@ -178,6 +220,9 @@ export declare class PerUserQuotaExhaustedError extends LoomcycleError {
         cap?: number;
         retryAfterMs?: number;
     });
+    /** The quota counts the caller's own in-flight runs, so it frees up as
+     *  they finish. */
+    get retryable(): boolean;
 }
 export declare class AuthError extends LoomcycleError {
     constructor(message: string, opts?: {
@@ -186,6 +231,37 @@ export declare class AuthError extends LoomcycleError {
         code?: string;
     });
 }
+/** An HTTP 403 because the bearer token lacks a scope the call needs: body code
+ *  `insufficient_scope`. The token is valid; it was minted without that
+ *  grant. Ask an operator for a token that carries `requiredScope`; sending
+ *  the same call again never succeeds, so `retryable` is false.
+ *
+ *  Any other 403 (`restricted_token`, `operator_key_restricted`, …) stays a
+ *  plain LoomcycleError: those refuse the caller for something a new scope
+ *  does not fix. */
+export declare class InsufficientScopeError extends LoomcycleError {
+    /** The scope the token lacks, e.g. `runs:create` or `substrate:tenant`.
+     *  Read from the body's `required_scope`, or, from a server that predates
+     *  that field, from the `WWW-Authenticate: Bearer scope="…"` header. Null
+     *  when neither names one (a browser does not see that header on a
+     *  cross-origin response unless the server exposes it). */
+    readonly requiredScope: string | null;
+    constructor(message: string, opts?: {
+        status?: number;
+        bodyText?: string;
+        code?: string;
+        requiredScope?: string;
+    });
+}
+/** Every HTTP 503. The status is shared between a condition that clears on
+ *  its own and features this deployment does not have
+ *  (`decision_not_configured`, `store_unavailable`, `vector_unsupported`, …),
+ *  which never will, and many 503 bodies carry no code at all. So
+ *  `retryable` is true only for `runtime_paused` (new runs are refused while
+ *  the operator has the runtime paused) and false otherwise. A code-less 503
+ *  from run creation can also be a model tier with no provider available
+ *  right now; retry that one on your own judgement, with a bound. (The
+ *  inherited `retryable` reads `runtime_paused` from TRANSIENT_CODES.) */
 export declare class UnavailableError extends LoomcycleError {
     constructor(message: string, opts?: {
         status?: number;
@@ -209,6 +285,8 @@ export declare class PauseNotConfiguredError extends UnavailableError {
         bodyText?: string;
         code?: string;
     });
+    /** The server has no pause manager; asking again does not give it one. */
+    get retryable(): boolean;
 }
 export declare class AlreadyPausingError extends LoomcycleError {
     constructor(message: string, opts?: {

package/dist/errors.js

@@ -33,7 +33,42 @@ export class LoomcycleError extends Error {
         this.bodyText = opts?.bodyText;
         this.code = opts?.code;
     }
+    /** Whether the same call, sent again unchanged, can succeed once time has
+     *  passed: true for a refusal that clears on its own (backpressure, a rate
+     *  limit, a per-user run quota, a paused runtime, a decision-model call
+     *  that failed or timed out), false for everything else, including a hard
+     *  token budget, a cap the caller must make room under, a bad request and
+     *  a missing resource. A retry loop can test this instead of a list of
+     *  classes.
+     *
+     *  It is a getter rather than a constructor field so that a subclass states
+     *  its answer by overriding it, without a constructor option any caller
+     *  could set. False is the default because a wrong `true` turns a refusal
+     *  that never clears into a loop that never ends, while a wrong `false`
+     *  only surfaces an error the caller could have waited out. The client
+     *  itself never retries; bound your own retries even when this is true. */
+    get retryable() {
+        return this.code !== undefined && TRANSIENT_CODES.has(this.code);
+    }
 }
+/** Codes that clear on their own although the class their status maps to
+ *  does not: a 503 is mostly a feature the deployment lacks, and a 502 / 504
+ *  is any upstream failure, so the class alone says false. The server
+ *  classifies each of these as transient:
+ *  - `runtime_paused` (503): new runs are refused until the operator resumes.
+ *  - `call_failed` (502): a decision-model call did not complete.
+ *  - `timeout` (504): a decision-model call did not answer in time. */
+const TRANSIENT_CODES = new Set([
+    "runtime_paused",
+    "call_failed",
+    "timeout",
+]);
+/** 429 codes that do NOT clear by waiting: the caller has to act first, so
+ *  a retry loop on them never ends. `configured_run_cap`: the user already
+ *  holds as many configured (not yet started) runs as the operator allows,
+ *  and only starting or discarding one makes room. (A hard token budget,
+ *  `token_limit_exceeded`, has a class of its own outside BackpressureError.) */
+const CALLER_ACTION_429_CODES = new Set(["configured_run_cap"]);
 /** Base class for every HTTP 404 the client surfaces. Lets callers
  *  catch any not-found case with a single `instanceof NotFoundError`
  *  check, regardless of which specific resource was missing
@@ -69,15 +104,45 @@ export class AgentIDInUseError extends LoomcycleError {
         this.name = "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. */
+/** An HTTP 429 that clears on its own: the server is busy (`backpressure`),
+ *  a provider's queue is full (`provider_concurrency_exhausted`), or the
+ *  caller is starting runs too fast (`rate_limited`, raised as the
+ *  RateLimitedError subclass). Back off and retry; `retryable` is true.
+ *
+ *  One code under this class is the exception: `configured_run_cap` (the user
+ *  holds as many configured runs as allowed; start or discard one first)
+ *  needs the caller to act, so its `retryable` is false. It stays a
+ *  BackpressureError, the class every other 429 lands in.
+ *
+ *  Two 429s are not this class: a per-user run quota
+ *  (PerUserQuotaExhaustedError, also retryable) and a hard token budget
+ *  (TokenLimitExceededError, not retryable). */
 export class BackpressureError extends LoomcycleError {
     constructor(message, opts) {
         super(message, opts);
         this.name = "BackpressureError";
     }
+    get retryable() {
+        return this.code === undefined || !CALLER_ACTION_429_CODES.has(this.code);
+    }
+}
+/**
+ * RateLimitedError signals that the caller is starting runs faster than its
+ * per-caller run-start rate allows: HTTP 429 with body code `rate_limited`.
+ * The server says when the next start will be admitted in `Retry-After`,
+ * surfaced here as `retryAfterMs`; wait that long rather than backing off on
+ * a guess. Retryable, like every BackpressureError.
+ */
+export class RateLimitedError extends BackpressureError {
+    /** Server-suggested retry window in milliseconds, from the Retry-After
+     *  header. Null when the header is absent or not a whole number of
+     *  seconds. */
+    retryAfterMs;
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "RateLimitedError";
+        this.retryAfterMs = opts?.retryAfterMs ?? null;
+    }
 }
 /**
  * TokenLimitExceededError signals that the caller is at a hard token budget:
@@ -88,20 +153,18 @@ export class BackpressureError extends LoomcycleError {
  * 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
- *   }
+ * It is not a BackpressureError, and `retryable` is false. It used to
+ * extend BackpressureError so that an older `instanceof BackpressureError`
+ * check kept catching it, but such a check is almost always a retry loop, and
+ * that loop then retried a refusal that cannot clear for the rest of the
+ * month. The relation was dropped on purpose: a retry loop keyed on
+ * BackpressureError or on `retryable` now stops here, and code that wants to
+ * report the budget tests for this class.
  *
  * The fields come from the response body and are null when the server did
  * not send them.
  */
-export class TokenLimitExceededError extends BackpressureError {
+export class TokenLimitExceededError extends LoomcycleError {
     /** Whose budget was hit: "operator", "tenant" or "user". */
     scope;
     /** The id of that scope: the tenant id or the user subject. Null for the
@@ -172,6 +235,11 @@ export class PerUserQuotaExhaustedError extends LoomcycleError {
         this.cap = opts?.cap ?? null;
         this.retryAfterMs = opts?.retryAfterMs ?? null;
     }
+    /** The quota counts the caller's own in-flight runs, so it frees up as
+     *  they finish. */
+    get retryable() {
+        return true;
+    }
 }
 export class AuthError extends LoomcycleError {
     constructor(message, opts) {
@@ -179,6 +247,36 @@ export class AuthError extends LoomcycleError {
         this.name = "AuthError";
     }
 }
+/** An HTTP 403 because the bearer token lacks a scope the call needs: body code
+ *  `insufficient_scope`. The token is valid; it was minted without that
+ *  grant. Ask an operator for a token that carries `requiredScope`; sending
+ *  the same call again never succeeds, so `retryable` is false.
+ *
+ *  Any other 403 (`restricted_token`, `operator_key_restricted`, …) stays a
+ *  plain LoomcycleError: those refuse the caller for something a new scope
+ *  does not fix. */
+export class InsufficientScopeError extends LoomcycleError {
+    /** The scope the token lacks, e.g. `runs:create` or `substrate:tenant`.
+     *  Read from the body's `required_scope`, or, from a server that predates
+     *  that field, from the `WWW-Authenticate: Bearer scope="…"` header. Null
+     *  when neither names one (a browser does not see that header on a
+     *  cross-origin response unless the server exposes it). */
+    requiredScope;
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "InsufficientScopeError";
+        this.requiredScope = opts?.requiredScope ?? null;
+    }
+}
+/** Every HTTP 503. The status is shared between a condition that clears on
+ *  its own and features this deployment does not have
+ *  (`decision_not_configured`, `store_unavailable`, `vector_unsupported`, …),
+ *  which never will, and many 503 bodies carry no code at all. So
+ *  `retryable` is true only for `runtime_paused` (new runs are refused while
+ *  the operator has the runtime paused) and false otherwise. A code-less 503
+ *  from run creation can also be a model tier with no provider available
+ *  right now; retry that one on your own judgement, with a bound. (The
+ *  inherited `retryable` reads `runtime_paused` from TRANSIENT_CODES.) */
 export class UnavailableError extends LoomcycleError {
     constructor(message, opts) {
         super(message, opts);
@@ -200,6 +298,10 @@ export class PauseNotConfiguredError extends UnavailableError {
         super(message, opts);
         this.name = "PauseNotConfiguredError";
     }
+    /** The server has no pause manager; asking again does not give it one. */
+    get retryable() {
+        return false;
+    }
 }
 export class AlreadyPausingError extends LoomcycleError {
     constructor(message, opts) {

package/dist/fetch-helpers.d.ts

@@ -77,6 +77,9 @@ export declare function deleteJSON<T>(ctx: _FetchContext, path: string, opts?: {
  *
  *   400         → InvalidArgumentError
  *   401         → AuthError
+ *   403 + code "insufficient_scope" (or an older server's
+ *         WWW-Authenticate scope hint) → InsufficientScopeError
+ *   403 (other) → LoomcycleError (base)
  *   404 + "snapshot"   → SnapshotNotFoundError ────────┐
  *   404 + "session"    → SessionNotFoundError          │  All extend
  *   404 + "agent"      → AgentNotFoundError            │  callers can

package/dist/fetch-helpers.js

@@ -9,7 +9,7 @@
  * Method-level code in client.ts stays focused on URL + body shape;
  * the boring fetch + error-translation machinery lives here.
  */
-import { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, ChannelCursorRegressionError, InvalidArgumentError, LoomcycleError, NotFoundError, NotPausedError, PauseNotConfiguredError, PerUserQuotaExhaustedError, PromptTooLargeError, RequestTooLargeError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, TokenLimitExceededError, UnavailableError, } from "./errors.js";
+import { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, ChannelCursorRegressionError, InsufficientScopeError, InvalidArgumentError, LoomcycleError, NotFoundError, NotPausedError, PauseNotConfiguredError, PerUserQuotaExhaustedError, PromptTooLargeError, RateLimitedError, RequestTooLargeError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, TokenLimitExceededError, UnavailableError, } from "./errors.js";
 /** authHeaders builds the standard request header set: JSON Accept
  *  + Bearer token when the client was constructed with one. The
  *  caller adds Content-Type when posting a body. */
@@ -157,6 +157,9 @@ export async function deleteJSON(ctx, path, opts) {
  *
  *   400         → InvalidArgumentError
  *   401         → AuthError
+ *   403 + code "insufficient_scope" (or an older server's
+ *         WWW-Authenticate scope hint) → InsufficientScopeError
+ *   403 (other) → LoomcycleError (base)
  *   404 + "snapshot"   → SnapshotNotFoundError ────────┐
  *   404 + "session"    → SessionNotFoundError          │  All extend
  *   404 + "agent"      → AgentNotFoundError            │  callers can
@@ -216,6 +219,19 @@ export async function raiseFromResponse(resp) {
             throw new InvalidArgumentError(msg, opts);
         case 401:
             throw new AuthError(msg, opts);
+        case 403: {
+            // A missing scope says so in its code. A server from before the JSON
+            // body sent "insufficient scope" as plain text; the scope hint in
+            // WWW-Authenticate, which no other 403 carries, still identifies it.
+            const hinted = scopeFromWWWAuthenticate(resp);
+            if (opts.code === "insufficient_scope" || (opts.code === undefined && hinted !== undefined)) {
+                throw new InsufficientScopeError(msg, {
+                    ...opts,
+                    requiredScope: stringField(bodyObject(bodyText)?.required_scope) ?? hinted,
+                });
+            }
+            throw new LoomcycleError(msg, opts);
+        }
         case 404:
             // Priority: most-specific keyword wins.
             // - "snapshot" → SnapshotNotFoundError
@@ -275,8 +291,8 @@ export async function raiseFromResponse(resp) {
         }
         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).
+            // it gets its own class, deliberately outside BackpressureError: a
+            // retry loop keyed on that class must not spin on it all month.
             if (opts.code === "token_limit_exceeded") {
                 const body = bodyObject(bodyText) ?? {};
                 throw new TokenLimitExceededError(msg, {
@@ -288,6 +304,9 @@ export async function raiseFromResponse(resp) {
                     window: stringField(body.window),
                 });
             }
+            if (opts.code === "rate_limited") {
+                throw new RateLimitedError(msg, { ...opts, retryAfterMs: retryAfterMs(resp) });
+            }
             // 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
@@ -295,18 +314,13 @@ export async function raiseFromResponse(resp) {
             try {
                 const parsed = JSON.parse(bodyText);
                 if (parsed.code === "per_user_quota_exhausted") {
-                    // Retry-After is `<seconds>` per RFC; convert to ms.
-                    const retryAfterRaw = resp.headers.get("retry-after");
-                    const retryAfterMs = retryAfterRaw
-                        ? Number.parseInt(retryAfterRaw, 10) * 1000
-                        : undefined;
                     throw new PerUserQuotaExhaustedError(parsed.error ?? msg, {
                         status,
                         bodyText,
                         code: parsed.code,
                         userId: parsed.user_id,
                         cap: parsed.cap,
-                        retryAfterMs: Number.isFinite(retryAfterMs) ? retryAfterMs : undefined,
+                        retryAfterMs: retryAfterMs(resp),
                     });
                 }
             }
@@ -325,6 +339,23 @@ export async function raiseFromResponse(resp) {
             throw new LoomcycleError(msg, opts);
     }
 }
+/** retryAfterMs reads a `Retry-After` header given in seconds, as the server
+ *  always sends it, and returns milliseconds; undefined when the header is
+ *  absent or not a number (an HTTP-date form is not parsed). */
+function retryAfterMs(resp) {
+    const raw = resp.headers.get("retry-after");
+    if (!raw)
+        return undefined;
+    const ms = Number.parseInt(raw, 10) * 1000;
+    return Number.isFinite(ms) ? ms : undefined;
+}
+/** scopeFromWWWAuthenticate reads the scope from the RFC 6750 hint the server
+ *  sends with a scope refusal (`Bearer scope="runs:create"`); undefined when
+ *  the header is absent or names no scope. */
+function scopeFromWWWAuthenticate(resp) {
+    const m = /\bscope="([^"]*)"/.exec(resp.headers.get("www-authenticate") ?? "");
+    return stringField(m?.[1]);
+}
 /** 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

package/dist/index.d.ts

@@ -14,7 +14,7 @@
  *     getAgent(agentId): Promise<Agent>
  *     getRun(runId): Promise<Agent>
  *     cancelAgent(agentId, opts?): Promise<CancelAgentResult>
- *     listUserAgents(userId, opts?): Promise<Agent[]>
+ *     listUserAgents(userId, opts?): Promise<AgentList>
  *     listWalkRuns(walkId, opts?): Promise<WalkRunsPage>
  *     deleteRunTree(runId, opts?): Promise<RunTreeDeletion>     // needs runs:delete
  *     deleteSession(sessionId, {cascade: "children"}): Promise<RunTreeDeletion>
@@ -35,6 +35,9 @@
  *     resumeRuntime(): Promise<ResumeResult>
  *     getRuntimeState(): Promise<RuntimeStateResponse>
  *     resolveProbe(opts?): Promise<ResolverMatrix>
+ *     listModels(): Promise<ModelAliasesResponse>                 // configured model aliases
+ *     getRouting(): Promise<RoutingResponse>                      // per user_tier × tier cascade
+ *     listProviderModels(providerId): Promise<ProviderModelsResponse>   // admin token only
  *
  *     // Snapshot lifecycle (v0.8.17/8.18)
  *     createSnapshot(opts?): Promise<SnapshotCreateResponse>
@@ -57,6 +60,10 @@
  *     backfillEmbeddings(scope, scopeId, opts?): Promise<MemoryBackfillResponse>   // embeds rows that have none
  *     purgeStaleEmbeddings(scope, scopeId, opts?): Promise<MemoryPurgeResponse>    // DELETES; dry_run defaults true
  *
+ *     // Memory / document change feeds (RFC CD Part C; SSE; substrate:tenant)
+ *     streamMemoryChanges(opts?): AsyncIterable<ChangeFeedFrame>     // feed | change | error (non-fatal); resume with opts.since = last seq
+ *     streamDocumentChanges(opts?): AsyncIterable<ChangeFeedFrame>
+ *
  *     // Interruption (v0.8.16; decline RFC BH)
  *     listUserInterrupts(userId, opts?): Promise<InterruptListResponse>
  *     listRunInterrupts(runId, opts?): Promise<InterruptListResponse>
@@ -72,7 +79,27 @@
  *     mcpServerDef(input): Promise<SubstrateToolResponse>
  *     mcpServerDefVerify(name, sha): Promise<MCPServerDefVerifyResult>   // v0.18.0
  *     ensureMcpServer(opts): Promise<EnsureMcpServerResult>              // v0.18.0 — idempotent register-if-changed
- *     scheduleDef(input): Promise<SubstrateToolResponse>
+ *     scheduleDef(input): Promise<SubstrateToolResponse>                // input: ScheduleDefInput | SubstrateToolInput
+ *     webhookDef(input): Promise<SubstrateToolResponse>                 // input: WebhookDefInput | SubstrateToolInput
+ *     hookDef(input): Promise<SubstrateToolResponse>                    // input: HookDefInput | SubstrateToolInput
+ *     ensureHookDef(name, overlay, opts?): Promise<EnsureHookDefResult>  // idempotent register-if-changed
+ *     createHookDef / forkHookDef(name, overlay, opts?)                  // overlay strictly typed, no loose fallback
+ *     createScheduleDef / forkScheduleDef(name, overlay, opts?)          // ditto (overlay open: types of known keys checked)
+ *     createWebhookDef / forkWebhookDef(name, overlay, opts?)            // ditto
+ *
+ *     // Def name enumeration (tenant-scoped; opts.tenant = admin focus)
+ *     listAgentDefNames / listSkillDefNames / listHookDefNames / listMcpServerDefNames /
+ *     listScheduleDefNames / listA2AServerCardDefNames / listA2AAgentDefNames /
+ *     listWebhookDefNames / listMemoryBackendDefNames / listDocumentSourceDefNames
+ *       (opts?): Promise<DefNamesResponse>
+ *     listOperatorTokenDefNames(opts?): Promise<OperatorTokenDefNamesResponse>   // admin token only
+ *
+ *     // Schedules admin
+ *     listAllSchedules(opts?): Promise<ScheduleListResponse>      // static yaml + ScheduleDefs, merged
+ *     getScheduleState(defId): Promise<ScheduleStateView>
+ *     runScheduleNow(defId): Promise<ScheduleRunNowResult>        // fires on the next tick
+ *     pauseSchedule(defId): Promise<SchedulePauseResult>          // indefinite
+ *     resumeSchedule(defId): Promise<SchedulePauseResult>
  *
  *     // Dynamic filesystem volumes (v0.35.0 — RFC AH; tenant-confined)
  *     volumeDef(input): Promise<SubstrateToolResponse>            // create/get/list/delete/purge
@@ -83,8 +110,8 @@
  *     listTeams(): Promise<ListTeamsResponse>
  *     renderTeamDiagram(name, opts?): Promise<TeamDiagram>
  *     getTeamDef(defId): Promise<TeamDefDetail>
- *     createTeam(name, overlay): Promise<CreatedTeam>
- *     forkTeam(name, overlay): Promise<CreatedTeam>
+ *     createTeam(name, overlay, opts?): Promise<CreatedTeam>       // opts: promote (default true) / description
+ *     forkTeam(name, overlay, opts?): Promise<CreatedTeam>         // opts: promote / parentDefId / description
  *     deleteTeam(name): Promise<{name, deleted}>
  *     runTeam({name|defId, input}): Promise<TeamRunResult>
  *     runTeam({..., mode:"detach"}): Promise<TeamRunDetached>     // the handle, now — the walk runs on
@@ -98,6 +125,14 @@
  *     // History — browse/search/annotate past chats (RFC BE; tenant-confined)
  *     history(input): Promise<HistoryToolResponse>                // list/get/search/rename/annotate/pin/archive/recap/resume
  *
+ *     // Evaluation — score runs and read the scores back, outside a run
+ *     evaluation(input): Promise<…>                               // submit/get/list_for_run/list_for_def/aggregate
+ *     submitEvaluation(runId, score, opts?): Promise<EvaluationSubmitResult>
+ *     getEvaluation(evalId): Promise<EvaluationRecord>
+ *     listEvaluationsForRun(runId, opts?): Promise<EvaluationListForRunResult>
+ *     listEvaluationsForDef(defId, opts?): Promise<EvaluationListForDefResult>
+ *     aggregateEvaluations(defId, opts?): Promise<EvaluationAggregate>
+ *
  *     // Library v2 enumeration (v0.10.3 — yaml+substrate merged)
  *     listLibraryAgents(): Promise<LibraryListResponse<LibraryAgentDefinition>>
  *     listLibrarySkills(): Promise<LibraryListResponse<LibrarySkillDefinition>>
@@ -114,13 +149,18 @@
  *   full HTTP-status → typed-error mapping table):
  *     LoomcycleError, AgentNotFoundError, SessionNotFoundError,
  *     SessionBusyError, AgentIDInUseError, BackpressureError,
- *     AuthError, UnavailableError, InvalidArgumentError,
+ *     RateLimitedError (subclass of BackpressureError),
+ *     PerUserQuotaExhaustedError, AuthError, InsufficientScopeError (a 403
+ *     naming the scope the token lacks), UnavailableError,
+ *     InvalidArgumentError,
  *     PauseNotConfiguredError (subclass of UnavailableError),
  *     AlreadyPausingError, NotPausedError, SnapshotNotFoundError,
  *     SnapshotTooLargeError, RequestTooLargeError + PromptTooLargeError
  *     (both subclasses of SnapshotTooLargeError), TokenLimitExceededError
- *     (subclass of BackpressureError), SnapshotVersionError,
- *     SubstrateToolRefusedError (v0.8.22)
+ *     (NOT a BackpressureError: a hard budget, not retryable),
+ *     SnapshotVersionError, SubstrateToolRefusedError (v0.8.22).
+ *     Every one carries `retryable` (true only for a refusal that clears
+ *     on its own).
  *
  * Transport: HTTP+SSE. Auth: Bearer token via the Authorization
  * header. Designed for Node ≥18 (engines pinned); Bun/Deno likely
@@ -132,7 +172,9 @@
 export { LoomcycleClient } from "./client.js";
 export { InteractiveSession } from "./interactive.js";
 export type { InteractiveSessionOps } from "./interactive.js";
+export { verifyLoomcycleSignature, verifyLoomcycleDelivery } from "./signature.js";
+export type { VerifySignatureOptions, VerifiedDelivery } from "./signature.js";
 export { ClientToolHost, clientToolsURL, CLIENT_TOOL_SUBPROTOCOL } from "./client-tools.js";
 export type { ClientToolSchema, ClientToolInvocation, ConnectClientToolsOptions, WebSocketLike, WebSocketCtor, } from "./client-tools.js";
-export type { AgentEvent, ClientOptions, ContinueOptions, EventType, HostWidening, ImageMediaType, ParentContext, PromptContent, PromptSegment, RetryInfo, RunOptions, SamplingOptions, CompactionOptions, ContextOptions, ToolUse, Usage, CallTiming, Agent, AgentStatus, AwaitedState, AgentUsage, RunResult, RunSpec, RunSpecTeam, ConfiguredRun, ConfiguredRunPatch, ToolChoiceOptions, OutputFormatOptions, CancelAgentResult, ListAgentsResponse, WalkRunsPage, RunBatchOptions, RunBatchResult, SpawnRunResult, CompactRunResult, RunTreeDeletion, RunTreeNotReached, DirectoryBudget, DirectoryInspection, DirectoryTenant, DirectoryUser, ErasureReport, ErasureResidue, ErasureResult, ErasureTier, CancelTurnResult, ReviewRunResult, TranscriptEvent, TranscriptResponse, HealthResponse, ListUsersResponse, UserSummary, UserRecord, CreateUserBody, UpdateUserBody, MintedUserToken, TokenRestrictions, UserTokenMeta, ListUserTokensResponse, RunnableAgent, RunnableAgentsResponse, WhoamiResponse, PauseResult, RetentionOverride, ResumeResult, RuntimeStateResponse, RuntimeStateStatus, ResolverMatrix, ResolverModelStatus, ResolverProviderAvailability, CreateSnapshotOptions, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotListResponse, SnapshotRestoreResponse, MemoryEntriesResponse, MemoryEntry, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopeIDSummary, MemoryScopeKind, MemoryScopesResponse, MemorySearchInput, MemorySource, MemoryWhen, MemoryTimeFilter, MemorySearchEntry, MemorySearchResponse, MemoryEmbedModelStats, MemoryEmbedStatsResponse, MemoryReembedConfigured, MemoryReembedResponse, MemoryBackfillResponse, MemoryPurgeResponse, InterruptListResponse, InterruptRow, InterruptStatus, ResolveInterruptOptions, ChannelHookCall, ChannelHookResult, HookFailMode, HookPhase, HookToolCall, HookToolResult, PostHookCall, PostHookResult, PreHookCall, PreHookResult, SubstrateToolInput, SubstrateToolResponse, TeamNameSummary, ListTeamsResponse, TeamDiagram, CreatedTeam, PromotedTeam, RetiredTeam, TeamDefDetail, TeamVerification, TeamDraft, TeamDraftVerification, TeamIssue, TeamIssueKind, TeamVersion, TeamVersionList, TeamBreakpoints, TeamRunDetached, TeamRunResult, TeamRunTarget, PathToolInput, PathToolResponse, DocumentToolInput, DocumentToolResponse, HistoryToolInput, HistoryToolResponse, VolumeMode, PersistentVolumeEntry, PersistentVolumesResponse, EphemeralVolumeEntry, EphemeralVolumesResponse, SystemPromptPayload, UserInputPayload, ChannelDescriptor, ListChannelsResponse, RunStateEvent, RunStateStreamClose, RunStateStreamItem, RunStateStreamOpen, StreamUserRunStatesOptions, AckChannelOptions, ChannelAckResult, ChannelMessageItem, ChannelPeekResult, ListTeamChannelsOptions, PeekTeamChannelOptions, ReleaseTeamChannelOptions, TeamChannelReleaseResult, TeamChannelDeclaredIn, TeamChannelDescriptor, TeamChannelPeekResult, TeamChannelsResult, ChannelPublishResult, ChannelPurgeResult, ChannelReleaseResult, ChannelScope, ChannelSubscribeResult, PeekChannelOptions, PublishChannelOptions, SubscribeChannelOptions, AwaitChannelsOptions, BroadcastChannelsOptions, ChannelAwaitEntry, ChannelAwaitMode, ChannelAwaitResult, ChannelBroadcastEntry, ChannelBroadcastResult, CreateChannelOptions, ReleaseChannelOptions, UpdateChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, AgentDefRowResponse, AgentDefVerifyResult, SkillDefVerifyResult, EnsureMcpServerOptions, EnsureMcpServerResult, MCPServerDefRowResponse, MCPServerDefVerifyResult, AgentDefOverlay, HookEvent, InlineWebhook, HookEntry, EventHooks, ToolEntry, ToolHooksByTool, EnsureCodeAgentOptions, EnsureCodeAgentResult, LibraryAgentDefinition, LibraryEntry, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, LLMChatContent, LLMChatMessage, LLMChatOptions, LLMChatResponse, LLMChatStreamDelta, LLMChatStreamItem, LLMChatToolCall, LLMChatUsage, LLMTool, LLMEmbeddingItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, LLMEmbeddingsUsage, UsageDimension, UsageAggregate, UsageReportResponse, CapabilityInertInfo, LimitInfo, ErrorInfo, CallFormat, CallRef, HookDecisionInfo, TeamDecisionInfo, EffectiveConfigResponse, EffectiveConfigSource, EffectiveValue, RetuneRunResponse, RunConfigRecord, SubagentHoldInfo, RunConfigResponse, RunPromptResponse, RunPromptSnapshot, PromptBlock, TokenLimit, TokenLimitsResponse, ConfigResponse, ConfigProvider, ConfigModel, ConfigSearch, ConfigInstance, SetTokenLimitRequest, CredentialScope, CredentialMeta, CredentialListResponse, DecideRequest, DecideResponse, DecisionQuestion, DecisionChoiceQuestion, DecisionNoulQuestion, DecisionScoreQuestion, DecisionAnswer, DecisionChoiceAnswer, DecisionNoulAnswer, DecisionScoreAnswer, DecisionModel, DecisionModelsResponse, } from "./types.js";
-export { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, NotFoundError, InvalidArgumentError, ChannelCursorRegressionError, LoomcycleError, NotPausedError, PauseNotConfiguredError, PerUserQuotaExhaustedError, PromptTooLargeError, RequestTooLargeError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, TokenLimitExceededError, UnavailableError, } from "./errors.js";
+export type { AgentEvent, ClientOptions, ContinueOptions, EventType, HostWidening, ImageMediaType, ParentContext, PromptContent, PromptSegment, RetryInfo, RunOptions, RunOverrideOptions, SamplingOptions, CompactionOptions, ContextOptions, ToolUse, Usage, CallTiming, Agent, AgentStatus, AwaitedState, AgentUsage, RunResult, RunSpec, RunSpecTeam, ConfiguredRun, ConfiguredRunPatch, ToolChoiceOptions, OutputFormatOptions, CancelAgentResult, ListAgentsResponse, ListUserAgentsOptions, AgentList, WalkRunsPage, RunBatchOptions, RunBatchResult, SpawnRunResult, CompactRunResult, RunTreeDeletion, RunTreeNotReached, DirectoryBudget, DirectoryInspection, DirectoryTenant, DirectoryUser, ErasureReport, ErasureResidue, ErasureResult, ErasureTier, CancelTurnResult, ReviewRunResult, ReplaySessionResult, TranscriptEvent, TranscriptResponse, HealthResponse, ListUsersResponse, UserSummary, UserRecord, CreateUserBody, UpdateUserBody, MintedUserToken, TokenRestrictions, UserTokenMeta, ListUserTokensResponse, RunnableAgent, RunnableAgentsResponse, WhoamiResponse, PauseResult, RetentionOverride, ResumeResult, RuntimeStateResponse, RuntimeStateStatus, ResolverMatrix, ResolverModelStatus, ResolverProviderAvailability, CreateSnapshotOptions, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotListResponse, SnapshotRestoreResponse, MemoryEntriesResponse, MemoryEntry, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopeIDSummary, MemoryScopeKind, MemoryScopesResponse, MemorySearchInput, MemorySource, MemoryWhen, MemoryTimeFilter, MemorySearchEntry, MemorySearchResponse, MemoryEmbedModelStats, MemoryEmbedStatsResponse, MemoryReembedConfigured, MemoryReembedResponse, MemoryBackfillResponse, MemoryPurgeResponse, InterruptListResponse, InterruptRow, InterruptStatus, ResolveInterruptOptions, ChannelHookCall, ChannelHookResult, HookFailMode, HookPhase, HookToolCall, HookToolResult, PostHookCall, PostHookResult, PreHookCall, PreHookResult, SubstrateToolInput, SubstrateToolResponse, TeamNameSummary, ListTeamsResponse, TeamDiagram, CreatedTeam, PromotedTeam, RetiredTeam, TeamDefDetail, TeamVerification, TeamDraft, TeamDraftVerification, TeamIssue, TeamIssueKind, TeamVersion, TeamVersionList, TeamBreakpoints, TeamRunDetached, TeamRunResult, TeamRunTarget, CreateTeamOptions, ForkTeamOptions, DefNameSummary, DefNamesResponse, OperatorTokenDefNameSummary, OperatorTokenDefNamesResponse, ScheduleListEntry, ScheduleListResponse, ScheduleActiveRun, ScheduleStateView, ScheduleRunNowResult, SchedulePauseResult, ModelAlias, ModelAliasesResponse, RoutingResponse, RoutingUserTier, RoutingTier, RoutingCandidate, RoutingThroughput, RoutingProvider, SearchRoutingProvider, ProviderModelsResponse, TeamRunStep, TeamDecisionHandler, TeamDecisionQuestion, TeamDecisionAnswer, PathToolInput, PathToolResponse, DocumentToolInput, DocumentToolResponse, HistoryToolInput, HistoryToolResponse, EvaluationEmitterRole, EvaluationSubmitInput, EvaluationGetInput, EvaluationListForRunInput, EvaluationListForDefInput, EvaluationAggregateInput, EvaluationInput, EvaluationSubmitResult, EvaluationRecord, EvaluationListForRunResult, EvaluationListForDefResult, EvaluationScoreStats, EvaluationAggregate, VolumeMode, PersistentVolumeEntry, PersistentVolumesResponse, EphemeralVolumeEntry, EphemeralVolumesResponse, SystemPromptPayload, UserInputPayload, ChannelDescriptor, ListChannelsResponse, RunStateEvent, RunStateStreamClose, RunStateStreamItem, RunStateStreamOpen, StreamUserRunStatesOptions, ChangeFeedError, ChangeFeedFrame, ChangeFeedStatus, EmbedderHealth, MemoryChange, MemoryChangeScope, MemoryChangeType, StreamChangesOptions, AckChannelOptions, ChannelAckResult, ChannelMessageItem, ChannelPeekResult, ListTeamChannelsOptions, PeekTeamChannelOptions, ReleaseTeamChannelOptions, TeamChannelReleaseResult, TeamChannelDeclaredIn, TeamChannelDescriptor, TeamChannelPeekResult, TeamChannelsResult, ChannelPublishResult, ChannelPurgeResult, ChannelReleaseResult, ChannelScope, ChannelSubscribeResult, PeekChannelOptions, PublishChannelOptions, SubscribeChannelOptions, AwaitChannelsOptions, BroadcastChannelsOptions, ChannelAwaitEntry, ChannelAwaitMode, ChannelAwaitResult, ChannelBroadcastEntry, ChannelBroadcastResult, CreateChannelOptions, ReleaseChannelOptions, UpdateChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, AgentDefRowResponse, AgentDefVerifyResult, SkillDefVerifyResult, EnsureMcpServerOptions, EnsureMcpServerResult, MCPServerDefRowResponse, MCPServerDefVerifyResult, AgentDefOverlay, AgentRouting, AgentChannelACL, AgentInterruptionACL, AgentDecision, MemoryRerank, AgentSampling, AgentCompaction, AgentContext, TierCandidate, CoreBlock, HookEvent, InlineWebhook, HookEntry, EventHooks, ToolEntry, ToolHooksByTool, EnsureCodeAgentOptions, EnsureCodeAgentResult, CreateDefOptions, ForkDefOptions, EnsureHookDefOptions, EnsureHookDefResult, HookDefBody, HookDefForkOverlay, HookDefInput, HookDefMatch, HookDefOverlay, HookDefRowResponse, HookDefVerifyResult, ScheduleDefInput, ScheduleDefOverlay, ScheduleDefRowResponse, ScheduledRunHook, ScheduledRunPromptContent, ScheduledRunPromptSegment, WebhookDefAuth, WebhookDefFilter, WebhookDefInput, WebhookDefOverlay, WebhookDefRateLimit, WebhookDefRowResponse, WebhookDefDeliveries, WebhookDefSyncResponse, LibraryAgentDefinition, LibraryEntry, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, LLMChatContent, LLMChatMessage, LLMChatOptions, LLMChatResponse, LLMChatStreamDelta, LLMChatStreamItem, LLMChatToolCall, LLMChatUsage, LLMTool, LLMEmbeddingItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, LLMEmbeddingsUsage, UsageDimension, UsageAggregate, UsageReportResponse, CapabilityInertInfo, LimitInfo, AdmissionInfo, ErrorInfo, CallFormat, CallRef, HookDecisionInfo, TeamDecisionInfo, OverrideInfo, FallbackInfo, InterruptionEventInfo, SpawnChildInfo, TurnCancelledInfo, ChannelEventInfo, ContextCompactionInfo, ContextRecapInfo, ContextStateInfo, ContextExhaustedInfo, ContextTierVerdict, ContextDistillDeclinedInfo, EffectiveConfigResponse, EffectiveConfigSource, EffectiveValue, InertContextSetting, AgentOverridableResponse, OverridableField, OverrideLockReason, RetuneRunResponse, RunConfigRecord, SubagentHoldInfo, RunConfigResponse, RunPromptResponse, RunPromptSnapshot, PromptBlock, TokenLimit, TokenLimitsResponse, ConfigResponse, ConfigProvider, ConfigModel, ConfigSearch, ConfigInstance, SetTokenLimitRequest, CredentialScope, CredentialMeta, CredentialListResponse, DecideRequest, DecideResponse, DecisionQuestion, DecisionChoiceQuestion, DecisionNoulQuestion, DecisionScoreQuestion, DecisionAnswer, DecisionChoiceAnswer, DecisionNoulAnswer, DecisionScoreAnswer, DecisionModel, DecisionModelsResponse, } from "./types.js";
+export { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, NotFoundError, InsufficientScopeError, InvalidArgumentError, ChannelCursorRegressionError, LoomcycleError, NotPausedError, PauseNotConfiguredError, PerUserQuotaExhaustedError, PromptTooLargeError, RateLimitedError, RequestTooLargeError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, TokenLimitExceededError, UnavailableError, } from "./errors.js";