@loomcycle/client 1.112.0 → 1.113.0

package/dist/cjs/errors.js

@@ -19,7 +19,7 @@
  * to raise typed errors via `raiseFromResponse`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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;
+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.InsufficientScopeError = exports.AuthError = exports.PerUserQuotaExhaustedError = exports.TokenLimitExceededError = exports.RateLimitedError = exports.BackpressureError = exports.AgentIDInUseError = exports.SessionBusyError = exports.SessionNotFoundError = exports.AgentNotFoundError = exports.NotFoundError = exports.LoomcycleError = void 0;
 class LoomcycleError extends Error {
     status;
     bodyText;
@@ -36,8 +36,43 @@ 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);
+    }
 }
 exports.LoomcycleError = LoomcycleError;
+/** 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
@@ -78,17 +113,48 @@ 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. */
+/** 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). */
 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);
+    }
 }
 exports.BackpressureError = BackpressureError;
+/**
+ * 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.
+ */
+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;
+    }
+}
+exports.RateLimitedError = RateLimitedError;
 /**
  * TokenLimitExceededError signals that the caller is at a hard token budget:
  * HTTP 429 with body code `token_limit_exceeded`, from run creation and from
@@ -98,20 +164,18 @@ exports.BackpressureError = BackpressureError;
  * 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.
  */
-class TokenLimitExceededError extends BackpressureError {
+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
@@ -183,6 +247,11 @@ 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;
+    }
 }
 exports.PerUserQuotaExhaustedError = PerUserQuotaExhaustedError;
 class AuthError extends LoomcycleError {
@@ -192,6 +261,37 @@ class AuthError extends LoomcycleError {
     }
 }
 exports.AuthError = 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. */
+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;
+    }
+}
+exports.InsufficientScopeError = InsufficientScopeError;
+/** 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.) */
 class UnavailableError extends LoomcycleError {
     constructor(message, opts) {
         super(message, opts);
@@ -215,6 +315,10 @@ 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;
+    }
 }
 exports.PauseNotConfiguredError = PauseNotConfiguredError;
 class AlreadyPausingError extends LoomcycleError {

package/dist/cjs/fetch-helpers.js

@@ -167,6 +167,9 @@ 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
@@ -226,6 +229,19 @@ async function raiseFromResponse(resp) {
             throw new errors_js_1.InvalidArgumentError(msg, opts);
         case 401:
             throw new errors_js_1.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 errors_js_1.InsufficientScopeError(msg, {
+                    ...opts,
+                    requiredScope: stringField(bodyObject(bodyText)?.required_scope) ?? hinted,
+                });
+            }
+            throw new errors_js_1.LoomcycleError(msg, opts);
+        }
         case 404:
             // Priority: most-specific keyword wins.
             // - "snapshot" → SnapshotNotFoundError
@@ -285,8 +301,8 @@ 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 errors_js_1.TokenLimitExceededError(msg, {
@@ -298,6 +314,9 @@ async function raiseFromResponse(resp) {
                     window: stringField(body.window),
                 });
             }
+            if (opts.code === "rate_limited") {
+                throw new errors_js_1.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
@@ -305,18 +324,13 @@ 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 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,
+                        retryAfterMs: retryAfterMs(resp),
                     });
                 }
             }
@@ -335,6 +349,23 @@ async function raiseFromResponse(resp) {
             throw new errors_js_1.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/cjs/index.js

@@ -15,7 +15,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>
@@ -36,6 +36,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>
@@ -58,6 +61,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>
@@ -73,7 +80,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
@@ -84,8 +111,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
@@ -99,6 +126,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>>
@@ -115,13 +150,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
@@ -131,11 +171,14 @@
  * See `adapters/ts/README.md` for usage examples.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-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;
+exports.UnavailableError = exports.TokenLimitExceededError = exports.SubstrateToolRefusedError = exports.SnapshotVersionError = exports.SnapshotTooLargeError = exports.SnapshotNotFoundError = exports.SessionNotFoundError = exports.SessionBusyError = exports.RequestTooLargeError = exports.RateLimitedError = exports.PromptTooLargeError = exports.PerUserQuotaExhaustedError = exports.PauseNotConfiguredError = exports.NotPausedError = exports.LoomcycleError = exports.ChannelCursorRegressionError = exports.InvalidArgumentError = exports.InsufficientScopeError = exports.NotFoundError = exports.BackpressureError = exports.AuthError = exports.AlreadyPausingError = exports.AgentNotFoundError = exports.AgentIDInUseError = exports.CLIENT_TOOL_SUBPROTOCOL = exports.clientToolsURL = exports.ClientToolHost = exports.verifyLoomcycleDelivery = exports.verifyLoomcycleSignature = 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");
 Object.defineProperty(exports, "InteractiveSession", { enumerable: true, get: function () { return interactive_js_1.InteractiveSession; } });
+var signature_js_1 = require("./signature.js");
+Object.defineProperty(exports, "verifyLoomcycleSignature", { enumerable: true, get: function () { return signature_js_1.verifyLoomcycleSignature; } });
+Object.defineProperty(exports, "verifyLoomcycleDelivery", { enumerable: true, get: function () { return signature_js_1.verifyLoomcycleDelivery; } });
 var client_tools_js_1 = require("./client-tools.js");
 Object.defineProperty(exports, "ClientToolHost", { enumerable: true, get: function () { return client_tools_js_1.ClientToolHost; } });
 Object.defineProperty(exports, "clientToolsURL", { enumerable: true, get: function () { return client_tools_js_1.clientToolsURL; } });
@@ -147,6 +190,7 @@ Object.defineProperty(exports, "AlreadyPausingError", { enumerable: true, get: f
 Object.defineProperty(exports, "AuthError", { enumerable: true, get: function () { return errors_js_1.AuthError; } });
 Object.defineProperty(exports, "BackpressureError", { enumerable: true, get: function () { return errors_js_1.BackpressureError; } });
 Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_js_1.NotFoundError; } });
+Object.defineProperty(exports, "InsufficientScopeError", { enumerable: true, get: function () { return errors_js_1.InsufficientScopeError; } });
 Object.defineProperty(exports, "InvalidArgumentError", { enumerable: true, get: function () { return errors_js_1.InvalidArgumentError; } });
 Object.defineProperty(exports, "ChannelCursorRegressionError", { enumerable: true, get: function () { return errors_js_1.ChannelCursorRegressionError; } });
 Object.defineProperty(exports, "LoomcycleError", { enumerable: true, get: function () { return errors_js_1.LoomcycleError; } });
@@ -154,6 +198,7 @@ Object.defineProperty(exports, "NotPausedError", { enumerable: true, get: functi
 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, "RateLimitedError", { enumerable: true, get: function () { return errors_js_1.RateLimitedError; } });
 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; } });

package/dist/cjs/interactive.js

@@ -49,7 +49,11 @@ class InteractiveSession {
             else if (ev.type === "session" && ev.session_id) {
                 this.sessionId = ev.session_id;
             }
-            this.awaitingInput = ev.type === "awaiting_input";
+            // A queued/admitted frame reports the run's admission, not activity in
+            // its conversation, so it leaves awaitingInput as it was.
+            if (ev.type !== "queued" && ev.type !== "admitted") {
+                this.awaitingInput = ev.type === "awaiting_input";
+            }
             yield ev;
         }
     }

package/dist/cjs/signature.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Verifying a signed loomcycle hook delivery.
+ *
+ * A HookDef whose webhook body names a `signing_secret` signs every call it
+ * makes. The call carries
+ *
+ *     X-Loomcycle-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256>
+ *
+ * where the MAC is keyed by the secret and computed over `<t>.<raw body>` —
+ * the exact bytes of the request body. Only the body is signed: the body's
+ * `delivery_id` (a retry keeps it) is what a receiver dedupes on, and its
+ * `hook_name` / `owner` say which hook sent it. `X-Loomcycle-Delivery` and
+ * `X-Loomcycle-Hook` are UNSIGNED copies of those two fields — a replayer can
+ * change them — so never dedupe or authorize on them.
+ * {@link verifyLoomcycleDelivery} verifies and returns the body's identity.
+ *
+ * Web Crypto only (`crypto.subtle`), so the same function runs in Node and in
+ * a browser or edge runtime. It is async because Web Crypto is.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyLoomcycleSignature = verifyLoomcycleSignature;
+exports.verifyLoomcycleDelivery = verifyLoomcycleDelivery;
+const DEFAULT_TOLERANCE_SEC = 300;
+const HEX_RE = /^(?:[0-9a-fA-F]{2})+$/;
+// What Go's strconv.ParseInt accepts, so a header loomcycle's own receiver
+// would accept is accepted here too.
+const UNIX_RE = /^[+-]?\d+$/;
+/**
+ * Reports whether `header` (the `X-Loomcycle-Signature` value) is a valid
+ * signature of `rawBody` under `secret`, made within the tolerance of now.
+ *
+ * `rawBody` must be the request body exactly as received — the string or the
+ * bytes, before any JSON parsing. A body parsed and re-serialized will not
+ * match: key order, spacing and escapes all change the bytes. A string is
+ * hashed as its UTF-8 encoding.
+ *
+ * Fails closed: a missing or repeated-garbage header, a `t` that is not an
+ * integer, a stale or future `t`, a `v1` that is not hex, or a wrong MAC all
+ * return `false`, with no reason given. The MAC is compared by Web Crypto's
+ * HMAC verify, which compares in constant time. Throws only when no Web Crypto
+ * implementation is available (a configuration problem, not a bad request).
+ */
+async function verifyLoomcycleSignature(rawBody, header, secret, opts = {}) {
+    const subtle = opts.subtle ?? globalThis.crypto?.subtle;
+    if (!subtle) {
+        throw new TypeError("verifyLoomcycleSignature: no Web Crypto implementation; pass opts.subtle (on Node 18: require('node:crypto').webcrypto.subtle)");
+    }
+    if (typeof header !== "string" || typeof secret !== "string" || secret === "") {
+        return false;
+    }
+    let ts = "";
+    let macHex = "";
+    for (const raw of header.split(",")) {
+        const part = raw.trim();
+        if (part.startsWith("t="))
+            ts = part.slice(2);
+        else if (part.startsWith("v1="))
+            macHex = part.slice(3);
+    }
+    if (!UNIX_RE.test(ts) || !HEX_RE.test(macHex)) {
+        return false;
+    }
+    const t = Number(ts);
+    if (!Number.isSafeInteger(t)) {
+        return false;
+    }
+    const tolerance = opts.toleranceSec ?? DEFAULT_TOLERANCE_SEC;
+    const nowSec = (opts.now ?? Date.now()) / 1000;
+    if (!(tolerance >= 0) || Math.abs(nowSec - t) > tolerance) {
+        return false;
+    }
+    const enc = new TextEncoder();
+    const body = typeof rawBody === "string" ? enc.encode(rawBody) : rawBody;
+    // The MAC covers t exactly as written in the header, then ".", then the body.
+    const prefix = enc.encode(ts + ".");
+    const signed = new Uint8Array(prefix.length + body.length);
+    signed.set(prefix, 0);
+    signed.set(body, prefix.length);
+    const mac = new Uint8Array(macHex.length / 2);
+    for (let i = 0; i < mac.length; i++) {
+        mac[i] = parseInt(macHex.slice(i * 2, i * 2 + 2), 16);
+    }
+    try {
+        const key = await subtle.importKey("raw", enc.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["verify"]);
+        return await subtle.verify("HMAC", key, mac, signed);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * {@link verifyLoomcycleSignature}, then parse the verified body and return
+ * the identity a receiver should act on: its `delivery_id`, `hook_name` and
+ * `owner`. Resolves `null` when the signature does not verify, or the body is
+ * not a JSON object carrying a non-empty string `delivery_id` and `hook_name`
+ * — a signed delivery always has both. Deduplicating on `deliveryId` stays the
+ * caller's job.
+ */
+async function verifyLoomcycleDelivery(rawBody, header, secret, opts = {}) {
+    if (!(await verifyLoomcycleSignature(rawBody, header, secret, opts))) {
+        return null;
+    }
+    let body;
+    try {
+        body = JSON.parse(typeof rawBody === "string" ? rawBody : new TextDecoder().decode(rawBody));
+    }
+    catch {
+        return null;
+    }
+    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+        return null;
+    }
+    const { delivery_id: deliveryId, hook_name: hookName, owner } = body;
+    if (typeof deliveryId !== "string" || deliveryId === "" || typeof hookName !== "string" || hookName === "") {
+        return null;
+    }
+    return { deliveryId, hookName, owner: typeof owner === "string" ? owner : "", body: body };
+}