@loomcycle/client 0.10.0 → 0.10.2

package/dist/cjs/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Wire-shape types for the loomcycle HTTP+SSE surface. Field names use
+ * snake_case to match the Go server's JSON output (no client-side
+ * conversion — what's on the wire is what you get).
+ *
+ * Public API method *parameters* use camelCase (JS norm); see
+ * `client.ts` for the input shapes (RunOptions, CreateSnapshotOptions,
+ * etc.) — those are translated to snake_case in the request body.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/errors.d.ts

@@ -66,6 +66,56 @@ export declare class BackpressureError extends LoomcycleError {
         bodyText?: string;
     });
 }
+/**
+ * PerUserQuotaExhaustedError signals that the caller has hit their
+ * per-user cap on in-flight (active+queued) runs. Distinct from
+ * BackpressureError because the appropriate retry strategy differs:
+ * backpressure is operator-wide load (exponential backoff with jitter),
+ * per-user quota is "you specifically need to wait" (fixed window —
+ * server hint: `Retry-After: 5` seconds).
+ *
+ * v0.10.1+. Maps from HTTP 429 + JSON body
+ * `{"code":"per_user_quota_exhausted","user_id":"...","cap":N}`.
+ *
+ * The `userId` and `cap` fields are populated from the JSON body when
+ * the response is parseable; null when the server didn't include them
+ * (very old loomcycle binaries or non-JSON 429 responses).
+ *
+ * Typical handling:
+ *
+ *   try { await client.runStreaming(...); }
+ *   catch (e) {
+ *     if (e instanceof PerUserQuotaExhaustedError) {
+ *       // Wait the server-suggested window, then retry.
+ *       await sleep(e.retryAfterMs ?? 5000);
+ *       return client.runStreaming(...);
+ *     }
+ *     if (e instanceof BackpressureError) {
+ *       // Operator-wide load — jittered backoff.
+ *       await sleep(jittered(2000, 30000));
+ *       return client.runStreaming(...);
+ *     }
+ *     throw e;
+ *   }
+ */
+export declare class PerUserQuotaExhaustedError extends LoomcycleError {
+    /** Server-side user identifier the cap applies to. Null when the
+     *  server didn't include it in the JSON body. */
+    readonly userId: string | null;
+    /** Per-user cap value as configured on the server (active+queued).
+     *  Null when the server didn't include it. */
+    readonly cap: number | null;
+    /** Server-suggested retry window in milliseconds, from the
+     *  Retry-After header. Null when absent. */
+    readonly retryAfterMs: number | null;
+    constructor(message: string, opts?: {
+        status?: number;
+        bodyText?: string;
+        userId?: string;
+        cap?: number;
+        retryAfterMs?: number;
+    });
+}
 export declare class AuthError extends LoomcycleError {
     constructor(message: string, opts?: {
         status?: number;

package/dist/errors.js

@@ -68,6 +68,56 @@ export class BackpressureError extends LoomcycleError {
         this.name = "BackpressureError";
     }
 }
+/**
+ * PerUserQuotaExhaustedError signals that the caller has hit their
+ * per-user cap on in-flight (active+queued) runs. Distinct from
+ * BackpressureError because the appropriate retry strategy differs:
+ * backpressure is operator-wide load (exponential backoff with jitter),
+ * per-user quota is "you specifically need to wait" (fixed window —
+ * server hint: `Retry-After: 5` seconds).
+ *
+ * v0.10.1+. Maps from HTTP 429 + JSON body
+ * `{"code":"per_user_quota_exhausted","user_id":"...","cap":N}`.
+ *
+ * The `userId` and `cap` fields are populated from the JSON body when
+ * the response is parseable; null when the server didn't include them
+ * (very old loomcycle binaries or non-JSON 429 responses).
+ *
+ * Typical handling:
+ *
+ *   try { await client.runStreaming(...); }
+ *   catch (e) {
+ *     if (e instanceof PerUserQuotaExhaustedError) {
+ *       // Wait the server-suggested window, then retry.
+ *       await sleep(e.retryAfterMs ?? 5000);
+ *       return client.runStreaming(...);
+ *     }
+ *     if (e instanceof BackpressureError) {
+ *       // Operator-wide load — jittered backoff.
+ *       await sleep(jittered(2000, 30000));
+ *       return client.runStreaming(...);
+ *     }
+ *     throw e;
+ *   }
+ */
+export class PerUserQuotaExhaustedError extends LoomcycleError {
+    /** Server-side user identifier the cap applies to. Null when the
+     *  server didn't include it in the JSON body. */
+    userId;
+    /** Per-user cap value as configured on the server (active+queued).
+     *  Null when the server didn't include it. */
+    cap;
+    /** Server-suggested retry window in milliseconds, from the
+     *  Retry-After header. Null when absent. */
+    retryAfterMs;
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "PerUserQuotaExhaustedError";
+        this.userId = opts?.userId ?? null;
+        this.cap = opts?.cap ?? null;
+        this.retryAfterMs = opts?.retryAfterMs ?? null;
+    }
+}
 export class AuthError extends LoomcycleError {
     constructor(message, opts) {
         super(message, opts);

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, HookNotFoundError, InvalidArgumentError, LoomcycleError, NotFoundError, NotPausedError, PauseNotConfiguredError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, UnavailableError, } from "./errors.js";
+import { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, ChannelCursorRegressionError, HookNotFoundError, InvalidArgumentError, LoomcycleError, NotFoundError, NotPausedError, PauseNotConfiguredError, PerUserQuotaExhaustedError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, 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. */
@@ -187,8 +187,35 @@ export async function raiseFromResponse(resp) {
             }
             throw new SnapshotVersionError(msg, opts);
         }
-        case 429:
+        case 429: {
+            // 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
+            // branch retry strategies on the typed error.
+            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,
+                        userId: parsed.user_id,
+                        cap: parsed.cap,
+                        retryAfterMs: Number.isFinite(retryAfterMs) ? retryAfterMs : undefined,
+                    });
+                }
+            }
+            catch (e) {
+                // Re-throw the typed error; fall through on JSON-parse fail.
+                if (e instanceof PerUserQuotaExhaustedError)
+                    throw e;
+            }
             throw new BackpressureError(msg, opts);
+        }
         case 503:
             if (bodyLower.includes("pause") && bodyLower.includes("not configured"))
                 throw new PauseNotConfiguredError(msg, opts);

package/dist/index.d.ts

@@ -65,4 +65,4 @@
  */
 export { LoomcycleClient } from "./client.js";
 export type { AgentEvent, ClientOptions, ContinueOptions, EventType, HostWidening, PromptContent, PromptSegment, RetryInfo, RunOptions, ToolUse, Usage, Agent, AgentStatus, AgentUsage, CancelAgentResult, ListAgentsResponse, TranscriptEvent, TranscriptResponse, HealthResponse, ListUsersResponse, UserSummary, PauseResult, ResumeResult, RuntimeStateResponse, RuntimeStateStatus, CreateSnapshotOptions, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotListResponse, SnapshotRestoreResponse, MemoryEntriesResponse, MemoryEntry, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopeIDSummary, MemoryScopeKind, MemoryScopesResponse, InterruptListResponse, InterruptRow, InterruptStatus, ResolveInterruptOptions, Hook, HookFailMode, HookPhase, HookToolCall, HookToolResult, ListHooksResponse, PostHookCall, PostHookResult, PreHookCall, PreHookResult, RegisterHookOptions, RegisterHookResponse, SubstrateToolInput, SubstrateToolResponse, SystemPromptPayload, UserInputPayload, ChannelDescriptor, ListChannelsResponse, RunStateEvent, RunStateStreamClose, RunStateStreamItem, RunStateStreamOpen, StreamUserRunStatesOptions, AckChannelOptions, ChannelAckResult, ChannelMessageItem, ChannelPeekResult, ChannelPublishResult, ChannelScope, ChannelSubscribeResult, PeekChannelOptions, PublishChannelOptions, SubscribeChannelOptions, AgentDefRowResponse, AgentDefVerifyResult, SkillDefVerifyResult, MCPServerDefRowResponse, MCPServerDefVerifyResult, } from "./types.js";
-export { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, HookNotFoundError, NotFoundError, InvalidArgumentError, ChannelCursorRegressionError, LoomcycleError, NotPausedError, PauseNotConfiguredError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, UnavailableError, } from "./errors.js";
+export { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, HookNotFoundError, NotFoundError, InvalidArgumentError, ChannelCursorRegressionError, LoomcycleError, NotPausedError, PauseNotConfiguredError, PerUserQuotaExhaustedError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, UnavailableError, } from "./errors.js";

package/dist/index.js

@@ -64,4 +64,4 @@
  * See `adapters/ts/README.md` for usage examples.
  */
 export { LoomcycleClient } from "./client.js";
-export { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, HookNotFoundError, NotFoundError, InvalidArgumentError, ChannelCursorRegressionError, LoomcycleError, NotPausedError, PauseNotConfiguredError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, UnavailableError, } from "./errors.js";
+export { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, HookNotFoundError, NotFoundError, InvalidArgumentError, ChannelCursorRegressionError, LoomcycleError, NotPausedError, PauseNotConfiguredError, PerUserQuotaExhaustedError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, UnavailableError, } from "./errors.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loomcycle/client",
-  "version": "0.10.0",
-  "description": "TypeScript client for the loomcycle sidecar (HTTP+SSE). 36 methods covering run streaming, agent metadata, pause/resume/state, snapshot lifecycle, memory admin (incl. v0.9.0 Vector Memory embed_stats + reembed), interruption resolve, hook management, v0.8.22 substrate admin (agentDef + skillDef), v0.9.x n8n Phase 0 (listChannels + streamUserRunStates — with debug-mode synthetic open/close meta-frames + client-side parentAgentId filter), v0.9.x Channel CRUD (publishChannel + subscribeChannel + peekChannel + ackChannel — admin scope=global + per-user scope=user surfaces), v0.9.x content_sha256 (AgentDefVerifyResult + SkillDefVerifyResult types for the bundle-vs-deployed comparison workflow), v0.9.1 transcript first-cycle (SystemPromptPayload + UserInputPayload), and v0.9.x dynamic MCP server registration (mcpServerDef + MCPServerDefVerifyResult — register HTTP/Streamable-HTTP MCP servers at runtime without yaml edits).",
+  "version": "0.10.2",
+  "description": "TypeScript client for the loomcycle sidecar (HTTP+SSE). 36 methods covering run streaming, agent metadata, pause/resume/state, snapshot lifecycle, memory admin (incl. v0.9.0 Vector Memory embed_stats + reembed), interruption resolve, hook management, v0.8.22 substrate admin (agentDef + skillDef), v0.9.x n8n Phase 0 (listChannels + streamUserRunStates — with debug-mode synthetic open/close meta-frames + client-side parentAgentId filter), v0.9.x Channel CRUD (publishChannel + subscribeChannel + peekChannel + ackChannel — admin scope=global + per-user scope=user surfaces), v0.9.x content_sha256 (AgentDefVerifyResult + SkillDefVerifyResult types for the bundle-vs-deployed comparison workflow), v0.9.1 transcript first-cycle (SystemPromptPayload + UserInputPayload), and v0.9.x dynamic MCP server registration (mcpServerDef + MCPServerDefVerifyResult — register HTTP/Streamable-HTTP MCP servers at runtime without yaml edits). v0.10.1 — dual ESM + CommonJS distribution (additive — ESM consumers unchanged; CJS consumers like n8n's community-node loader now work).",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {
@@ -13,12 +13,14 @@
   "bugs": {
     "url": "https://github.com/denn-gubsky/loomcycle/issues"
   },
-  "main": "./dist/index.js",
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/cjs/index.js"
     }
   },
   "files": [
@@ -26,7 +28,9 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({type:'commonjs'}, null, 2))\"",
+    "build:esm": "tsc",
+    "build:cjs": "tsc -p tsconfig.cjs.json && node -e \"require('fs').writeFileSync('dist/cjs/package.json', JSON.stringify({type:'commonjs'}, null, 2))\"",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest"