@loomcycle/client 1.112.0 → 1.113.0

package/dist/index.js

@@ -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
@@ -131,5 +171,6 @@
  */
 export { LoomcycleClient } from "./client.js";
 export { InteractiveSession } from "./interactive.js";
+export { verifyLoomcycleSignature, verifyLoomcycleDelivery } from "./signature.js";
 export { ClientToolHost, clientToolsURL, CLIENT_TOOL_SUBPROTOCOL } from "./client-tools.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 { 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";

package/dist/interactive.js

@@ -46,7 +46,11 @@ export 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/signature.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 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.
+ */
+/** Options for {@link verifyLoomcycleSignature}. */
+export interface VerifySignatureOptions {
+    /** How far `t` may be from now, either way, in seconds. Default 300 — the
+     *  window loomcycle's own receiver uses. A larger window lets a captured
+     *  delivery be replayed for longer. */
+    toleranceSec?: number;
+    /** The current time in milliseconds since the epoch, as `Date.now()`
+     *  returns. For tests; defaults to `Date.now()`. */
+    now?: number;
+    /** The Web Crypto implementation to use. Defaults to
+     *  `globalThis.crypto.subtle`, which Node 19+ and every browser have; on
+     *  Node 18 pass `require("node:crypto").webcrypto.subtle`. */
+    subtle?: SubtleCrypto;
+}
+/**
+ * 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).
+ */
+export declare function verifyLoomcycleSignature(rawBody: string | Uint8Array, header: string, secret: string, opts?: VerifySignatureOptions): Promise<boolean>;
+/** A delivery {@link verifyLoomcycleDelivery} verified: what to dedupe on and
+ *  which hook sent it, read from the signed body, plus the parsed body. */
+export interface VerifiedDelivery<T = Record<string, unknown>> {
+    /** The body's `delivery_id`. Dedupe on this — keep each id at least as long
+     *  as the tolerance window — never on the `X-Loomcycle-Delivery` header,
+     *  which is an unsigned copy a replayer can change. */
+    deliveryId: string;
+    /** The body's `hook_name`: the HookDef that sent it. The `X-Loomcycle-Hook`
+     *  header is an unsigned copy. */
+    hookName: string;
+    /** The body's `owner` (`agent:<name>`, `team:<name>`, `channel:<name>`). */
+    owner: string;
+    /** The parsed body. */
+    body: T;
+}
+/**
+ * {@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.
+ */
+export declare function verifyLoomcycleDelivery<T = Record<string, unknown>>(rawBody: string | Uint8Array, header: string, secret: string, opts?: VerifySignatureOptions): Promise<VerifiedDelivery<T> | null>;

package/dist/signature.js

@@ -0,0 +1,115 @@
+/**
+ * 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.
+ */
+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).
+ */
+export 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.
+ */
+export 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 };
+}