@loomcycle/client 0.9.3 → 0.10.1

package/dist/cjs/errors.js

@@ -0,0 +1,246 @@
+"use strict";
+/**
+ * Typed exceptions raised by LoomcycleClient. Mirrors the Python
+ * adapter's `errors.py` taxonomy 1:1 — same names, same semantics,
+ * just adapted to HTTP status codes (no gRPC StatusCode equivalents).
+ *
+ * Every error stores the raw HTTP status (`status`) and the raw
+ * response body (`bodyText`, truncated to 1 KiB) for log correlation
+ * when the typed class doesn't carry enough.
+ *
+ * Dispatch from raw HTTP response to typed error lives in
+ * `fetch-helpers.ts:raiseFromResponse` — that's the one place to
+ * look when adding a new error type.
+ *
+ * PR 5a foundation: classes defined; dispatch wiring lands here +
+ * in fetch-helpers.ts. The current `runStreaming` (the only public
+ * method in v0.1.0-alpha) throws a plain Error today; PR 5a keeps
+ * that behavior. PR 5b switches `runStreaming` + every new method
+ * to raise typed errors via `raiseFromResponse`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubstrateToolRefusedError = exports.ChannelCursorRegressionError = exports.HookNotFoundError = exports.SnapshotVersionError = exports.SnapshotTooLargeError = exports.SnapshotNotFoundError = exports.NotPausedError = exports.AlreadyPausingError = exports.PauseNotConfiguredError = exports.InvalidArgumentError = exports.UnavailableError = exports.AuthError = exports.PerUserQuotaExhaustedError = exports.BackpressureError = exports.AgentIDInUseError = exports.SessionBusyError = exports.SessionNotFoundError = exports.AgentNotFoundError = exports.NotFoundError = exports.LoomcycleError = void 0;
+class LoomcycleError extends Error {
+    status;
+    bodyText;
+    constructor(message, opts) {
+        super(message);
+        this.name = "LoomcycleError";
+        this.status = opts?.status;
+        this.bodyText = opts?.bodyText;
+    }
+}
+exports.LoomcycleError = LoomcycleError;
+/** 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
+ *  (agent / session / snapshot / generic 404 like a missing memory
+ *  row or interrupt). */
+class NotFoundError extends LoomcycleError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "NotFoundError";
+    }
+}
+exports.NotFoundError = NotFoundError;
+class AgentNotFoundError extends NotFoundError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "AgentNotFoundError";
+    }
+}
+exports.AgentNotFoundError = AgentNotFoundError;
+class SessionNotFoundError extends NotFoundError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "SessionNotFoundError";
+    }
+}
+exports.SessionNotFoundError = SessionNotFoundError;
+class SessionBusyError extends LoomcycleError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "SessionBusyError";
+    }
+}
+exports.SessionBusyError = SessionBusyError;
+class AgentIDInUseError extends LoomcycleError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "AgentIDInUseError";
+    }
+}
+exports.AgentIDInUseError = AgentIDInUseError;
+class BackpressureError extends LoomcycleError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "BackpressureError";
+    }
+}
+exports.BackpressureError = 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;
+ *   }
+ */
+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;
+    }
+}
+exports.PerUserQuotaExhaustedError = PerUserQuotaExhaustedError;
+class AuthError extends LoomcycleError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "AuthError";
+    }
+}
+exports.AuthError = AuthError;
+class UnavailableError extends LoomcycleError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "UnavailableError";
+    }
+}
+exports.UnavailableError = UnavailableError;
+class InvalidArgumentError extends LoomcycleError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "InvalidArgumentError";
+    }
+}
+exports.InvalidArgumentError = InvalidArgumentError;
+// ---- v0.8.18 — Pause/Snapshot typed errors ----
+/** Subclasses UnavailableError for back-compat: code that broadly
+ *  catches UnavailableError keeps working when this more-specific
+ *  variant fires. */
+class PauseNotConfiguredError extends UnavailableError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "PauseNotConfiguredError";
+    }
+}
+exports.PauseNotConfiguredError = PauseNotConfiguredError;
+class AlreadyPausingError extends LoomcycleError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "AlreadyPausingError";
+    }
+}
+exports.AlreadyPausingError = AlreadyPausingError;
+class NotPausedError extends LoomcycleError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "NotPausedError";
+    }
+}
+exports.NotPausedError = NotPausedError;
+class SnapshotNotFoundError extends NotFoundError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "SnapshotNotFoundError";
+    }
+}
+exports.SnapshotNotFoundError = SnapshotNotFoundError;
+class SnapshotTooLargeError extends LoomcycleError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "SnapshotTooLargeError";
+    }
+}
+exports.SnapshotTooLargeError = SnapshotTooLargeError;
+class SnapshotVersionError extends LoomcycleError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "SnapshotVersionError";
+    }
+}
+exports.SnapshotVersionError = SnapshotVersionError;
+/** HookNotFoundError — raised by deleteHook when no hook has the
+ *  supplied id (HTTP 404 with "hook" in the body). Extends
+ *  NotFoundError so consumers catching the broader category get this
+ *  one too. */
+class HookNotFoundError extends NotFoundError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "HookNotFoundError";
+    }
+}
+exports.HookNotFoundError = HookNotFoundError;
+/** ChannelCursorRegressionError — raised by `client.ackChannel()`
+ *  when the caller-supplied cursor is older than the currently-
+ *  committed cursor for the (channel, scope, scope_id) tuple. HTTP
+ *  409 with `{code: "channel_cursor_regression", ...}` body.
+ *
+ *  Mirrors `store.ErrChannelCursorRegression` on the loomcycle
+ *  side. Distinct from `SessionBusyError` etc. (which also map to
+ *  409) so the n8n adapter can distinguish "this cursor is stale,
+ *  re-fetch and retry from the new committed position" from other
+ *  409 conditions. */
+class ChannelCursorRegressionError extends LoomcycleError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "ChannelCursorRegressionError";
+    }
+}
+exports.ChannelCursorRegressionError = ChannelCursorRegressionError;
+/** SubstrateToolRefusedError — raised by `client.agentDef()` /
+ *  `client.skillDef()` when the in-process tool refused the call
+ *  (scope deny, empty body, allowed-tools widening, etc.). HTTP
+ *  status 422 with `{code: "tool_refused", error, tool}` body.
+ *
+ *  Distinct from transport failures: the request reached the
+ *  server, the substrate tool ran, and the tool itself returned
+ *  IsError=true. Operators catching this error should surface the
+ *  reason in `message` to the calling agent / user rather than
+ *  retrying. */
+class SubstrateToolRefusedError extends LoomcycleError {
+    /** Which substrate tool refused — "AgentDef" or "SkillDef". */
+    tool;
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "SubstrateToolRefusedError";
+        this.tool = opts?.tool ?? "";
+    }
+}
+exports.SubstrateToolRefusedError = SubstrateToolRefusedError;

package/dist/cjs/fetch-helpers.js

@@ -0,0 +1,253 @@
+"use strict";
+/**
+ * Shared HTTP plumbing for LoomcycleClient. Three responsibilities:
+ *
+ *   1. Build the Authorization header from the client's bearer token.
+ *   2. JSON encode/decode the request + response.
+ *   3. Map non-2xx responses to typed errors from errors.ts (single
+ *      source of truth — mirrors Python's _raise_from_grpc).
+ *
+ * Method-level code in client.ts stays focused on URL + body shape;
+ * the boring fetch + error-translation machinery lives here.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.authHeaders = authHeaders;
+exports.jsonFetch = jsonFetch;
+exports.postJSON = postJSON;
+exports.deleteRequest = deleteRequest;
+exports.raiseFromResponse = raiseFromResponse;
+const errors_js_1 = require("./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. */
+function authHeaders(ctx) {
+    const h = { Accept: "application/json" };
+    if (ctx.authToken)
+        h.Authorization = `Bearer ${ctx.authToken}`;
+    return h;
+}
+/** jsonFetch performs a GET and unwraps the JSON body. Non-2xx
+ *  status maps to a typed error via raiseFromResponse. */
+async function jsonFetch(ctx, path, opts) {
+    const resp = await ctx.fetchImpl(ctx.baseUrl + path, {
+        method: "GET",
+        headers: authHeaders(ctx),
+        signal: opts?.signal,
+    });
+    if (!resp.ok) {
+        await raiseFromResponse(resp);
+    }
+    return (await resp.json());
+}
+/** postJSON sends a JSON-encoded body and unwraps the response.
+ *  When `body` is undefined, no body is sent (Content-Type
+ *  omitted). */
+async function postJSON(ctx, path, body, opts) {
+    const headers = authHeaders(ctx);
+    let bodyStr;
+    if (body !== undefined) {
+        headers["Content-Type"] = "application/json";
+        bodyStr = JSON.stringify(body);
+    }
+    const resp = await ctx.fetchImpl(ctx.baseUrl + path, {
+        method: "POST",
+        headers,
+        body: bodyStr,
+        signal: opts?.signal,
+    });
+    if (!resp.ok) {
+        await raiseFromResponse(resp);
+    }
+    // Some endpoints return 204 No Content; tolerate that with a
+    // null cast — typed methods that know they return 204 use a
+    // void wrapper instead.
+    if (resp.status === 204)
+        return null;
+    return (await resp.json());
+}
+/** deleteRequest sends a DELETE and tolerates 204/200/404-with-
+ *  idempotent-semantics per the loomcycle wire contract. */
+async function deleteRequest(ctx, path, opts) {
+    const resp = await ctx.fetchImpl(ctx.baseUrl + path, {
+        method: "DELETE",
+        headers: authHeaders(ctx),
+        signal: opts?.signal,
+    });
+    if (!resp.ok) {
+        await raiseFromResponse(resp);
+    }
+}
+/**
+ * raiseFromResponse — the single point where HTTP status + body
+ * text get mapped to typed errors. Always throws; the function
+ * signature returns `never` only because TypeScript needs the
+ * return type for control-flow narrowing.
+ *
+ * Mapping table:
+ *
+ *   400         → InvalidArgumentError
+ *   401         → AuthError
+ *   404 + "snapshot"   → SnapshotNotFoundError ────────┐
+ *   404 + "session"    → SessionNotFoundError          │  All extend
+ *   404 + "hook"       → HookNotFoundError             │  NotFoundError —
+ *   404 + "agent"      → AgentNotFoundError            │  callers can
+ *   404 + (other)      → NotFoundError (base)          │  catch any 404
+ *                                                      │  with one
+ *                                                      │  instanceof.
+ *   409 + "already_pausing" / "already paused" → AlreadyPausingError
+ *   409 + "not_paused" / "not paused"          → NotPausedError
+ *   409 + "session"                            → SessionBusyError
+ *   409 + "agent_id"                           → AgentIDInUseError
+ *   409 + (other)                              → LoomcycleError (base)
+ *   413         → SnapshotTooLargeError
+ *   422         → SnapshotVersionError (snapshot-version-too-new/unknown)
+ *   429         → BackpressureError
+ *   503 + "pause manager not configured" → PauseNotConfiguredError
+ *                                          (subclass of UnavailableError)
+ *   503 + (other)                        → UnavailableError
+ *   500-599 (other) → LoomcycleError (base)
+ *   default     → LoomcycleError (base)
+ *
+ * Priority within a status group is most-specific-first; an unknown
+ * 409 falls through to base LoomcycleError so callers see a
+ * meaningful message + status. For 404, the catch-all is NotFoundError
+ * (base) so the v0.8.18-added memory + interrupt routes don't
+ * misclassify into AgentNotFoundError when the 404 body doesn't
+ * mention "agent".
+ */
+async function raiseFromResponse(resp) {
+    const status = resp.status;
+    // Read body with a cap; many error bodies are JSON {error, message}
+    // shape but raw text is fine for matching keywords.
+    let bodyText = "";
+    try {
+        bodyText = await resp.text();
+    }
+    catch {
+        // network-level body read failure — fall through with empty body
+    }
+    const bodyLower = bodyText.toLowerCase();
+    // HTTP/2 strips reason phrases — Node's undici fetch returns "" for
+    // resp.statusText on HTTP/2 responses. Fall back to a stock phrase
+    // for the common status codes so the error message reads cleanly
+    // ("401 Unauthorized" not "401 " with a trailing space).
+    const statusPhrase = resp.statusText || stockStatusPhrase(status);
+    const msg = bodyText.trim() ? bodyText.slice(0, 1024) : `${status} ${statusPhrase}`;
+    const opts = { status, bodyText: bodyText.slice(0, 1024) };
+    switch (status) {
+        case 400:
+            throw new errors_js_1.InvalidArgumentError(msg, opts);
+        case 401:
+            throw new errors_js_1.AuthError(msg, opts);
+        case 404:
+            // Priority: most-specific keyword wins.
+            // - "snapshot" → SnapshotNotFoundError
+            // - "session"  → SessionNotFoundError
+            // - "hook"     → HookNotFoundError (must precede "agent" — the
+            //                hooks 404 body is `no hook with id "..."`,
+            //                doesn't mention "agent")
+            // - "agent" or "agent_id" → AgentNotFoundError
+            // - otherwise → NotFoundError (base) — e.g. memory rows, interrupts,
+            //   or any future 404-returning endpoint that doesn't fit the
+            //   existing keyword set.
+            if (bodyLower.includes("snapshot"))
+                throw new errors_js_1.SnapshotNotFoundError(msg, opts);
+            if (bodyLower.includes("session"))
+                throw new errors_js_1.SessionNotFoundError(msg, opts);
+            if (bodyLower.includes("hook"))
+                throw new errors_js_1.HookNotFoundError(msg, opts);
+            if (bodyLower.includes("agent"))
+                throw new errors_js_1.AgentNotFoundError(msg, opts);
+            throw new errors_js_1.NotFoundError(msg, opts);
+        case 409:
+            if (bodyLower.includes("already_pausing") || bodyLower.includes("already paused"))
+                throw new errors_js_1.AlreadyPausingError(msg, opts);
+            if (bodyLower.includes("not_paused") || bodyLower.includes("not paused"))
+                throw new errors_js_1.NotPausedError(msg, opts);
+            // v0.9.x — Channel CRUD ack with a stale cursor. Distinct so
+            // the n8n adapter / consumer can branch on `instanceof`.
+            if (bodyLower.includes("channel_cursor_regression"))
+                throw new errors_js_1.ChannelCursorRegressionError(msg, opts);
+            if (bodyLower.includes("session"))
+                throw new errors_js_1.SessionBusyError(msg, opts);
+            if (bodyLower.includes("agent_id"))
+                throw new errors_js_1.AgentIDInUseError(msg, opts);
+            throw new errors_js_1.LoomcycleError(msg, opts);
+        case 413:
+            throw new errors_js_1.SnapshotTooLargeError(msg, opts);
+        case 422: {
+            // 422 is shared between snapshot version errors (existing)
+            // and v0.8.22 substrate tool refusals. Discriminate by body:
+            // the substrate path returns `{code: "tool_refused", tool,
+            // error}` JSON; the snapshot path returns a free-form text.
+            try {
+                const parsed = JSON.parse(bodyText);
+                if (parsed.code === "tool_refused") {
+                    throw new errors_js_1.SubstrateToolRefusedError(parsed.error ?? msg, { status, bodyText, tool: parsed.tool });
+                }
+            }
+            catch (e) {
+                // Re-throw our typed error if we matched; fall through to
+                // SnapshotVersionError on any JSON-parse failure.
+                if (e instanceof errors_js_1.SubstrateToolRefusedError)
+                    throw e;
+            }
+            throw new errors_js_1.SnapshotVersionError(msg, opts);
+        }
+        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 errors_js_1.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 errors_js_1.PerUserQuotaExhaustedError)
+                    throw e;
+            }
+            throw new errors_js_1.BackpressureError(msg, opts);
+        }
+        case 503:
+            if (bodyLower.includes("pause") && bodyLower.includes("not configured"))
+                throw new errors_js_1.PauseNotConfiguredError(msg, opts);
+            throw new errors_js_1.UnavailableError(msg, opts);
+        default:
+            throw new errors_js_1.LoomcycleError(msg, opts);
+    }
+}
+/** stockStatusPhrase returns a stock reason phrase for the common
+ *  HTTP statuses raiseFromResponse handles. Used as a fallback when
+ *  Response.statusText is empty (HTTP/2 strips reason phrases). */
+function stockStatusPhrase(status) {
+    switch (status) {
+        case 400: return "Bad Request";
+        case 401: return "Unauthorized";
+        case 403: return "Forbidden";
+        case 404: return "Not Found";
+        case 409: return "Conflict";
+        case 413: return "Payload Too Large";
+        case 422: return "Unprocessable Entity";
+        case 429: return "Too Many Requests";
+        case 500: return "Internal Server Error";
+        case 502: return "Bad Gateway";
+        case 503: return "Service Unavailable";
+        case 504: return "Gateway Timeout";
+        default: return "HTTP " + status;
+    }
+}

package/dist/cjs/index.js

@@ -0,0 +1,91 @@
+"use strict";
+/**
+ * @loomcycle/client — TypeScript client for the loomcycle sidecar.
+ *
+ * Public surface (v0.8.18 — Python-adapter parity):
+ *
+ *   class LoomcycleClient
+ *     constructor(opts: ClientOptions)
+ *
+ *     // Run lifecycle (SSE streams)
+ *     runStreaming(opts: RunOptions): AsyncIterable<AgentEvent>
+ *     continueSession(opts: ContinueOptions): AsyncIterable<AgentEvent>
+ *
+ *     // Agent metadata
+ *     getAgent(agentId): Promise<Agent>
+ *     cancelAgent(agentId, opts?): Promise<CancelAgentResult>
+ *     listUserAgents(userId, opts?): Promise<Agent[]>
+ *     getTranscript(sessionId): Promise<TranscriptResponse>
+ *     health(): Promise<HealthResponse>
+ *     listUsers(): Promise<ListUsersResponse>
+ *
+ *     // Pause / Resume / State (v0.8.17/8.18)
+ *     pauseRuntime(opts?): Promise<PauseResult>
+ *     resumeRuntime(): Promise<ResumeResult>
+ *     getRuntimeState(): Promise<RuntimeStateResponse>
+ *
+ *     // Snapshot lifecycle (v0.8.17/8.18)
+ *     createSnapshot(opts?): Promise<SnapshotCreateResponse>
+ *     listSnapshots(opts?): Promise<SnapshotDescriptor[]>
+ *     getSnapshot(id): Promise<SnapshotEnvelope>
+ *     exportSnapshotURL(id): string  (synchronous; returns a URL)
+ *     restoreSnapshot(opts): Promise<SnapshotRestoreResponse>
+ *     deleteSnapshot(id): Promise<void>
+ *
+ *     // Memory admin
+ *     listMemoryScopes(): Promise<MemoryScopesResponse>
+ *     listMemoryScopeIDs(scope): Promise<MemoryScopeIDsResponse>
+ *     listMemoryEntries(scope, scopeID, opts?): Promise<MemoryEntriesResponse>
+ *     getMemoryEntry(scope, scopeID, key): Promise<MemoryEntryResponse>
+ *
+ *     // Interruption (v0.8.16)
+ *     listUserInterrupts(userId, opts?): Promise<InterruptListResponse>
+ *     listRunInterrupts(runId, opts?): Promise<InterruptListResponse>
+ *     resolveInterrupt(runId, interruptId, opts): Promise<unknown>
+ *
+ *     // Substrate admin (v0.8.22)
+ *     agentDef(input): Promise<SubstrateToolResponse>
+ *     skillDef(input): Promise<SubstrateToolResponse>
+ *
+ *   Errors (typed subclasses of LoomcycleError; see README for the
+ *   full HTTP-status → typed-error mapping table):
+ *     LoomcycleError, AgentNotFoundError, SessionNotFoundError,
+ *     SessionBusyError, AgentIDInUseError, BackpressureError,
+ *     AuthError, UnavailableError, InvalidArgumentError,
+ *     PauseNotConfiguredError (subclass of UnavailableError),
+ *     AlreadyPausingError, NotPausedError, SnapshotNotFoundError,
+ *     SnapshotTooLargeError, SnapshotVersionError,
+ *     SubstrateToolRefusedError (v0.8.22)
+ *
+ * Transport: HTTP+SSE. Auth: Bearer token via the Authorization
+ * header. Designed for Node ≥18 (engines pinned); Bun/Deno likely
+ * work but untested. Browser support is not a target (use the
+ * Web UI for browser-side operator control).
+ *
+ * See `adapters/ts/README.md` for usage examples.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnavailableError = exports.SubstrateToolRefusedError = exports.SnapshotVersionError = exports.SnapshotTooLargeError = exports.SnapshotNotFoundError = exports.SessionNotFoundError = exports.SessionBusyError = exports.PerUserQuotaExhaustedError = exports.PauseNotConfiguredError = exports.NotPausedError = exports.LoomcycleError = exports.ChannelCursorRegressionError = exports.InvalidArgumentError = exports.NotFoundError = exports.HookNotFoundError = exports.BackpressureError = exports.AuthError = exports.AlreadyPausingError = exports.AgentNotFoundError = exports.AgentIDInUseError = 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 errors_js_1 = require("./errors.js");
+Object.defineProperty(exports, "AgentIDInUseError", { enumerable: true, get: function () { return errors_js_1.AgentIDInUseError; } });
+Object.defineProperty(exports, "AgentNotFoundError", { enumerable: true, get: function () { return errors_js_1.AgentNotFoundError; } });
+Object.defineProperty(exports, "AlreadyPausingError", { enumerable: true, get: function () { return errors_js_1.AlreadyPausingError; } });
+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, "HookNotFoundError", { enumerable: true, get: function () { return errors_js_1.HookNotFoundError; } });
+Object.defineProperty(exports, "NotFoundError", { enumerable: true, get: function () { return errors_js_1.NotFoundError; } });
+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; } });
+Object.defineProperty(exports, "NotPausedError", { enumerable: true, get: function () { return errors_js_1.NotPausedError; } });
+Object.defineProperty(exports, "PauseNotConfiguredError", { enumerable: true, get: function () { return errors_js_1.PauseNotConfiguredError; } });
+Object.defineProperty(exports, "PerUserQuotaExhaustedError", { enumerable: true, get: function () { return errors_js_1.PerUserQuotaExhaustedError; } });
+Object.defineProperty(exports, "SessionBusyError", { enumerable: true, get: function () { return errors_js_1.SessionBusyError; } });
+Object.defineProperty(exports, "SessionNotFoundError", { enumerable: true, get: function () { return errors_js_1.SessionNotFoundError; } });
+Object.defineProperty(exports, "SnapshotNotFoundError", { enumerable: true, get: function () { return errors_js_1.SnapshotNotFoundError; } });
+Object.defineProperty(exports, "SnapshotTooLargeError", { enumerable: true, get: function () { return errors_js_1.SnapshotTooLargeError; } });
+Object.defineProperty(exports, "SnapshotVersionError", { enumerable: true, get: function () { return errors_js_1.SnapshotVersionError; } });
+Object.defineProperty(exports, "SubstrateToolRefusedError", { enumerable: true, get: function () { return errors_js_1.SubstrateToolRefusedError; } });
+Object.defineProperty(exports, "UnavailableError", { enumerable: true, get: function () { return errors_js_1.UnavailableError; } });

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/stream.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseSSE = parseSSE;
+/**
+ * parseSSE turns a chunked byte stream into typed AgentEvents.
+ *
+ * SSE framing (subset): "event: <name>\ndata: <json>\n\n". We only emit a
+ * frame when both event + data have been seen since the last blank line.
+ *
+ * Used by `runStreaming` and `continueSession` — both POST endpoints
+ * return the same SSE wire shape and the parser doesn't differentiate.
+ *
+ * Side-channel frames: the v0.4 `event: agent` SSE frame (and any future
+ * sse.sendRaw user) emits a JSON payload that does NOT carry the `type`
+ * field — the SSE event name is the only discriminator. parseSSE backfills
+ * `type` from the event name in that case so consumers see a well-formed
+ * AgentEvent and switch on `ev.type` uniformly.
+ */
+async function* parseSSE(reader) {
+    const decoder = new TextDecoder("utf-8");
+    let buf = "";
+    let event = "";
+    let data = "";
+    const flush = () => {
+        if (!event && !data)
+            return null;
+        if (!data) {
+            event = "";
+            return null;
+        }
+        try {
+            const parsed = JSON.parse(data);
+            // Side-channel sendRaw frames omit `type` in the JSON payload — the
+            // SSE event name is the only discriminator. Backfill it so the
+            // consumer's switch on ev.type doesn't miss these.
+            if (!parsed.type && event) {
+                parsed.type = event;
+            }
+            event = "";
+            data = "";
+            return parsed;
+        }
+        catch {
+            event = "";
+            data = "";
+            return null;
+        }
+    };
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        buf += decoder.decode(value, { stream: true });
+        let idx;
+        while ((idx = buf.indexOf("\n")) !== -1) {
+            const line = buf.slice(0, idx).replace(/\r$/, "");
+            buf = buf.slice(idx + 1);
+            if (line === "") {
+                const ev = flush();
+                if (ev)
+                    yield ev;
+                continue;
+            }
+            if (line.startsWith("event:"))
+                event = line.slice("event:".length).trim();
+            else if (line.startsWith("data:"))
+                data = line.slice("data:".length).trim();
+        }
+    }
+    // Stream ended. Drain any unterminated final line still in `buf` — a
+    // connection drop can land here mid-frame, and without this step the
+    // last frame whose `\n` never arrived would be silently lost. Then
+    // flush any pending event + data.
+    if (buf.length > 0) {
+        const line = buf.replace(/\r$/, "");
+        if (line.startsWith("event:"))
+            event = line.slice("event:".length).trim();
+        else if (line.startsWith("data:"))
+            data = line.slice("data:".length).trim();
+    }
+    const ev = flush();
+    if (ev)
+        yield ev;
+}