@loomcycle/client 0.10.0 → 0.10.1

package/dist/cjs/client.js

@@ -0,0 +1,734 @@
+"use strict";
+/**
+ * LoomcycleClient — the single public class exported by
+ * @loomcycle/client. Speaks HTTP+SSE to a running loomcycle sidecar.
+ *
+ * hooks-connector PR C: full Python-adapter parity + hook management.
+ * 27 methods total — 26 async (run streaming, continuation, agent
+ * metadata, transcript, health, users, pause/resume/state, snapshot
+ * lifecycle capture / list / get / restore / delete, memory admin,
+ * interruption listing + resolve, hook registration / list / delete)
+ * plus one synchronous helper (exportSnapshotURL builds a URL string
+ * without issuing a request).
+ *
+ * Construction:
+ *
+ *   const client = new LoomcycleClient({
+ *     baseUrl: "http://127.0.0.1:8787",  // or process.env.LOOMCYCLE_BASE_URL
+ *     authToken: "...",                  // or process.env.LOOMCYCLE_AUTH_TOKEN
+ *   });
+ *
+ * Streaming methods (`runStreaming`, `continueSession`) return
+ * AsyncIterable<AgentEvent>; non-streaming methods return
+ * Promise<T>. Non-2xx responses throw typed errors from errors.ts
+ * via fetch-helpers.ts:raiseFromResponse — see README.md for the
+ * full mapping table.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoomcycleClient = void 0;
+const fetch_helpers_js_1 = require("./fetch-helpers.js");
+const stream_js_1 = require("./stream.js");
+class LoomcycleClient {
+    ctx;
+    constructor(opts = {}) {
+        this.ctx = {
+            baseUrl: (opts.baseUrl ?? "http://127.0.0.1:8787").replace(/\/$/, ""),
+            authToken: opts.authToken,
+            fetchImpl: opts.fetch ?? fetch,
+        };
+    }
+    // ---- Run lifecycle ----
+    /**
+     * Run an agent and stream events. Returns AsyncIterable<AgentEvent>;
+     * the iterator completes when the server closes the SSE stream.
+     *
+     * Errors during the run surface as `{ type: "error", error }` events;
+     * only transport / HTTP-level failures throw — and those throw typed
+     * errors (e.g. AuthError for 401, BackpressureError for 429).
+     *
+     * **Blocking semantics.** This iterator is alive for the FULL
+     * duration of the run — typically seconds, occasionally minutes for
+     * long tool chains. Callers that need fire-and-forget completion
+     * notifications (n8n's worker model, dashboards that don't want to
+     * hold a connection per active run) should subscribe to
+     * {@link LoomcycleClient.streamUserRunStates} instead, which yields
+     * one terminal-state frame per completed run without holding the
+     * run's stream open.
+     *
+     * v0.9.x — pass `opts.debug = true` to emit synthetic
+     * `{ type: "_meta", meta_subtype: "stream_open" | "stream_close" }`
+     * events around the real frames. Silent (default) when omitted.
+     */
+    async *runStreaming(opts) {
+        // Build the body conditionally so omitted fields stay off the wire.
+        // The pointer-vs-empty distinction on allowed_hosts is preserved by
+        // treating `null` as "omit" — same as the server's nil semantics —
+        // so callers threading a possibly-unset slice don't accidentally
+        // send `allowed_hosts: null` (which JSON-decodes to a deny-all on
+        // some implementations).
+        const body = {
+            agent: opts.agent,
+            segments: opts.segments,
+        };
+        if (opts.allowedTools !== undefined)
+            body.allowed_tools = opts.allowedTools;
+        if (opts.allowedHosts !== undefined && opts.allowedHosts !== null) {
+            body.allowed_hosts = opts.allowedHosts;
+        }
+        if (opts.webSearchFilter !== undefined)
+            body.web_search_filter = opts.webSearchFilter;
+        if (opts.sessionId !== undefined)
+            body.session_id = opts.sessionId;
+        if (opts.tenantId !== undefined)
+            body.tenant_id = opts.tenantId;
+        if (opts.userId !== undefined)
+            body.user_id = opts.userId;
+        if (opts.agentId !== undefined)
+            body.agent_id = opts.agentId;
+        if (opts.userTier !== undefined)
+            body.user_tier = opts.userTier;
+        if (opts.userBearer !== undefined)
+            body.user_bearer = opts.userBearer;
+        yield* this.streamSSE("/v1/runs", body, opts.signal, opts.debug);
+    }
+    /**
+     * Continue an existing session with a new run. The session's prior
+     * transcript is replayed into the model's context server-side;
+     * this iterator yields only the NEW events from the continuation.
+     *
+     * Raises SessionNotFoundError when sessionId is unknown,
+     * SessionBusyError when another request is in flight on the same
+     * session.
+     *
+     * **Blocking semantics.** Same as {@link LoomcycleClient.runStreaming} —
+     * the iterator stays alive for the duration of the new run. For
+     * async fire-and-forget completion patterns, see
+     * {@link LoomcycleClient.streamUserRunStates}.
+     *
+     * v0.9.x — pass `opts.debug = true` for synthetic
+     * `_meta` open/close events.
+     */
+    async *continueSession(opts) {
+        const body = {
+            segments: opts.segments,
+        };
+        if (opts.allowedTools !== undefined)
+            body.allowed_tools = opts.allowedTools;
+        if (opts.allowedHosts !== undefined && opts.allowedHosts !== null) {
+            body.allowed_hosts = opts.allowedHosts;
+        }
+        if (opts.webSearchFilter !== undefined)
+            body.web_search_filter = opts.webSearchFilter;
+        if (opts.agentId !== undefined)
+            body.agent_id = opts.agentId;
+        if (opts.userTier !== undefined)
+            body.user_tier = opts.userTier;
+        if (opts.userBearer !== undefined)
+            body.user_bearer = opts.userBearer;
+        yield* this.streamSSE(`/v1/sessions/${encodeURIComponent(opts.sessionId)}/messages`, body, opts.signal, opts.debug);
+    }
+    // ---- Agent metadata ----
+    /** Read one agent's status + usage stats. Raises AgentNotFoundError
+     *  when the agent_id is unknown. */
+    async getAgent(agentId, opts) {
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, `/v1/agents/${encodeURIComponent(agentId)}`, opts);
+    }
+    /** Cancel a live agent (cascades to children via parent_agent_id).
+     *  Returns count of agents cancelled. Idempotent — already-terminated
+     *  agents return 0. */
+    async cancelAgent(agentId, opts) {
+        const resp = await (0, fetch_helpers_js_1.postJSON)(this.ctx, `/v1/agents/${encodeURIComponent(agentId)}/cancel`, { reason: opts?.reason ?? "" }, opts);
+        return { cancelledCount: resp.cancelled_count };
+    }
+    /** List a user's recent agent runs, optionally filtered by status.
+     *
+     *  v0.9.x — `parentAgentId` narrows the result CLIENT-SIDE to runs
+     *  whose `parent_agent_id` matches. The server still returns the
+     *  full set (server-side `?parent_agent_id=` filter is a future
+     *  request); the adapter trims before returning. Useful for the
+     *  n8n trigger pattern "show me all sub-runs spawned by parent X." */
+    async listUserAgents(userId, opts) {
+        const q = opts?.status ? `?status=${encodeURIComponent(opts.status)}` : "";
+        const resp = await (0, fetch_helpers_js_1.jsonFetch)(this.ctx, `/v1/users/${encodeURIComponent(userId)}/agents${q}`, opts);
+        const all = resp.agents ?? [];
+        if (opts?.parentAgentId !== undefined && opts.parentAgentId !== "") {
+            return all.filter((a) => a.parent_agent_id === opts.parentAgentId);
+        }
+        return all;
+    }
+    /** Read the full event log for a session. Each entry has seq,
+     *  run_id, ts_ns, type, event (the providers.Event payload). */
+    async getTranscript(sessionId, opts) {
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, `/v1/sessions/${encodeURIComponent(sessionId)}/transcript`, opts);
+    }
+    /** Liveness probe. Unauthenticated. Returns build info + uptime.
+     *  Hits /healthz, not /v1/. */
+    async health(opts) {
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, "/healthz", opts);
+    }
+    /** Admin: list known users with running-count summary. Drives the
+     *  Web UI's user picker; operators with bearer auth can call too. */
+    async listUsers(opts) {
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, "/v1/_users", opts);
+    }
+    // ---- v0.8.17/8.18 Pause / Resume / State ----
+    /** Quiesce the runtime. Idempotent tools cancel immediately;
+     *  non-idempotent + external tools get a grace window then
+     *  force-cancel. Raises AlreadyPausingError on 409,
+     *  PauseNotConfiguredError on 503. */
+    async pauseRuntime(opts) {
+        const body = opts?.timeoutMs && opts.timeoutMs > 0
+            ? { timeout_ms: opts.timeoutMs }
+            : undefined;
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_pause", body, opts);
+    }
+    /** Release the runtime quiesce. Raises NotPausedError on 409. */
+    async resumeRuntime(opts) {
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_resume", undefined, opts);
+    }
+    /** Current runtime state. Cheap query — atomic state + a
+     *  bounded snapshots count. */
+    async getRuntimeState(opts) {
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, "/v1/_state", opts);
+    }
+    // ---- Snapshot lifecycle ----
+    /** Capture running-state into a per-section-semver JSON envelope.
+     *  Raises SnapshotTooLargeError on 413 when the envelope exceeds
+     *  LOOMCYCLE_SNAPSHOT_MAX_BYTES (default 512 MiB). */
+    async createSnapshot(opts) {
+        const body = {};
+        if (opts?.label)
+            body.label = opts.label;
+        if (opts?.includeHistory)
+            body.include_history = true;
+        if (opts?.includeHistorySince)
+            body.include_history_since = opts.includeHistorySince;
+        if (opts?.maxBytes && opts.maxBytes > 0)
+            body.max_bytes = opts.maxBytes;
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_snapshots", body, opts);
+    }
+    /** List captured snapshots (most-recent first). Capped at 200
+     *  server-side; the limit param defaults to 200 too. */
+    async listSnapshots(opts) {
+        const params = new URLSearchParams();
+        if (opts?.limit && opts.limit > 0)
+            params.set("limit", String(opts.limit));
+        if (opts?.labelContains)
+            params.set("label_contains", opts.labelContains);
+        const qs = params.toString();
+        const path = qs ? `/v1/_snapshots?${qs}` : "/v1/_snapshots";
+        const resp = await (0, fetch_helpers_js_1.jsonFetch)(this.ctx, path, opts);
+        return resp.entries ?? [];
+    }
+    /** Fetch the full snapshot envelope including JSON content.
+     *  Distinct from exportSnapshot (which is operator-facing
+     *  "where did this land on the host" semantics with a download
+     *  URL). Raises SnapshotNotFoundError on 404. */
+    async getSnapshot(snapshotId, opts) {
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, `/v1/_snapshots/${encodeURIComponent(snapshotId)}`, opts);
+    }
+    /** Returns the URL of the snapshot's canonical envelope —
+     *  synchronous and side-effect-free; does NOT issue an HTTP
+     *  request. The endpoint is bearer-authed like every other
+     *  `/v1/_snapshots/*` route, so callers must attach the same
+     *  `Authorization: Bearer <token>` header when fetching this
+     *  URL (e.g. `curl -H "Authorization: Bearer $TOKEN" ...`).
+     *  There is no token query-param fallback. */
+    exportSnapshotURL(snapshotId) {
+        return `${this.ctx.baseUrl}/v1/_snapshots/${encodeURIComponent(snapshotId)}/export`;
+    }
+    /** Restore from a same-instance snapshot id OR an inline
+     *  envelope JSON. Idempotent: ON CONFLICT DO NOTHING per row;
+     *  the returned counters reflect rows actually written.
+     *  Raises SnapshotVersionError on 422 when a section's
+     *  declared version is newer than the reader supports. */
+    async restoreSnapshot(opts) {
+        if (!opts.snapshotId && opts.json === undefined) {
+            // Client-side validation — match Python adapter's
+            // InvalidArgumentError pattern but the typed-error layer
+            // lives in errors.ts; for a thrown plain error here the
+            // method's catchers just see the message.
+            throw new Error("restoreSnapshot: pass snapshotId or json (one is required)");
+        }
+        if (opts.snapshotId && opts.json !== undefined) {
+            throw new Error("restoreSnapshot: pass only one of snapshotId or json");
+        }
+        // When json is supplied the id path-segment is ignored
+        // server-side; we use a placeholder "inline" segment to keep
+        // the URL well-formed.
+        const id = opts.snapshotId ?? "inline";
+        const body = {};
+        if (opts.includeHistory)
+            body.include_history = true;
+        if (opts.json !== undefined)
+            body.json = opts.json;
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, `/v1/_snapshots/${encodeURIComponent(id)}/restore`, body, opts);
+    }
+    /** Delete a snapshot. Idempotent — succeeds whether or not the
+     *  row existed (server returns 204 in both cases). */
+    async deleteSnapshot(snapshotId, opts) {
+        await (0, fetch_helpers_js_1.deleteRequest)(this.ctx, `/v1/_snapshots/${encodeURIComponent(snapshotId)}`, opts);
+    }
+    // ---- Memory admin ----
+    /** List the kinds of memory scopes the server knows about
+     *  (agent, user — or whatever the operator yaml declares). */
+    async listMemoryScopes(opts) {
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, "/v1/_memory/scopes", opts);
+    }
+    /** List the scope_ids that have at least one memory row under
+     *  a given scope. */
+    async listMemoryScopeIDs(scope, opts) {
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, `/v1/_memory/scopes/${encodeURIComponent(scope)}`, opts);
+    }
+    /** List memory entries under a (scope, scope_id) tuple.
+     *  Optional prefix narrows by key prefix. */
+    async listMemoryEntries(scope, scopeID, opts) {
+        const params = new URLSearchParams();
+        if (opts?.prefix)
+            params.set("prefix", opts.prefix);
+        // Guard against `limit: 0` (falsy but valid-looking) and negatives —
+        // both would either send `limit=0` (server treats as default but the
+        // semantic is unclear) or `limit=-N` (server rejects). Only send the
+        // param when the caller passed a meaningful positive number.
+        if (opts?.limit && opts.limit > 0)
+            params.set("limit", String(opts.limit));
+        const qs = params.toString();
+        const path = `/v1/_memory/scopes/${encodeURIComponent(scope)}/${encodeURIComponent(scopeID)}/keys${qs ? "?" + qs : ""}`;
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, path, opts);
+    }
+    /** Read a single memory entry by (scope, scope_id, key). */
+    async getMemoryEntry(scope, scopeID, key, opts) {
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, `/v1/_memory/scopes/${encodeURIComponent(scope)}/${encodeURIComponent(scopeID)}/keys/${encodeURIComponent(key)}`, opts);
+    }
+    // ---- Interruption ----
+    /** List interrupts addressable to a user_id. Default filter is
+     *  status=pending. */
+    async listUserInterrupts(userId, opts) {
+        const status = opts?.status ?? "pending";
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, `/v1/users/${encodeURIComponent(userId)}/interrupts?status=${encodeURIComponent(status)}`, opts);
+    }
+    /** List interrupts emitted by a specific run. */
+    async listRunInterrupts(runId, opts) {
+        const status = opts?.status ?? "pending";
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, `/v1/runs/${encodeURIComponent(runId)}/interrupts?status=${encodeURIComponent(status)}`, opts);
+    }
+    /** Resolve a pending Interruption.ask from outside the agent
+     *  loop. Lets a TS-side dashboard or service act as the human
+     *  answerer when operator yaml configures the consumer-MCP
+     *  backend. */
+    async resolveInterrupt(runId, interruptId, opts) {
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, `/v1/runs/${encodeURIComponent(runId)}/interrupts/${encodeURIComponent(interruptId)}/resolve`, {
+            kind: opts.kind ?? "question",
+            answer: opts.answer,
+            resolved_by: opts.resolvedBy ?? "client",
+        }, opts);
+    }
+    // ---- Hook management (hooks-connector series, PR C) ----
+    /** Register a pre- or post-tool webhook. The callback_url must be
+     *  an http:// or https:// endpoint the CONSUMER runs — loomcycle
+     *  POSTs PreHookCall / PostHookCall payloads to it. This method
+     *  manages registration only; the receiver is the consumer's own
+     *  HTTP framework (Express, Next.js, etc.).
+     *
+     *  Re-registering the same (owner, name) replaces the prior entry
+     *  with a fresh id (idempotent app-restart contract).
+     *
+     *  Raises InvalidArgumentError on 400 (bad URL / phase / missing
+     *  required fields). */
+    async registerHook(opts) {
+        const body = {
+            owner: opts.owner,
+            name: opts.name,
+            phase: opts.phase,
+            callback_url: opts.callbackUrl,
+        };
+        if (opts.agents !== undefined)
+            body.agents = opts.agents;
+        if (opts.tools !== undefined)
+            body.tools = opts.tools;
+        if (opts.failMode !== undefined)
+            body.fail_mode = opts.failMode;
+        if (opts.timeoutMs !== undefined && opts.timeoutMs > 0) {
+            body.timeout_ms = opts.timeoutMs;
+        }
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/hooks", body, opts);
+    }
+    /** List every currently-registered hook. Returns the array
+     *  unwrapped (the wire envelope is `{hooks: [...]}` — we strip
+     *  the envelope to match listUserAgents). In-memory only — empty
+     *  after a loomcycle restart. */
+    async listHooks(opts) {
+        const resp = await (0, fetch_helpers_js_1.jsonFetch)(this.ctx, "/v1/hooks", opts);
+        return resp.hooks ?? [];
+    }
+    /** Delete a registered hook by id. Raises HookNotFoundError on
+     *  404. Returns void on success (the HTTP 200 body `{deleted: id}`
+     *  is dropped — callers already know the id they passed). */
+    async deleteHook(id, opts) {
+        await (0, fetch_helpers_js_1.deleteRequest)(this.ctx, `/v1/hooks/${encodeURIComponent(id)}`, opts);
+    }
+    // ---- v0.8.22 substrate admin (AgentDef + SkillDef) ----
+    /** Invoke the AgentDef substrate tool over HTTP. Mirrors the
+     *  MCP `agentdef` meta-tool and the in-band agent tool_use of
+     *  the same name — different transport, identical semantics.
+     *
+     *  The `input.op` field discriminates create / fork / get /
+     *  list / promote / retire. The remaining fields are op-specific;
+     *  see the in-process tool's documentation.
+     *
+     *  Raises {@link SubstrateToolRefusedError} when the tool itself
+     *  refuses the call (scope deny, empty body, allowed-tools
+     *  widening, etc.) — distinct from transport failures so callers
+     *  can branch on the typed error class.
+     *
+     *  Raises {@link InvalidArgumentError} on 400 (malformed JSON
+     *  body); {@link AuthError} on 401; {@link UnavailableError} on
+     *  503 (store / connector unwired). */
+    async agentDef(input, opts) {
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_agentdef", input, opts);
+    }
+    /** Invoke the SkillDef substrate tool over HTTP. Mirror of
+     *  {@link LoomcycleClient.agentDef} for skills (v0.8.22+). Same
+     *  input grammar, same error class on refusal. See the
+     *  agentDef() doc for the full shape and error contract. */
+    async skillDef(input, opts) {
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_skilldef", input, opts);
+    }
+    /** Invoke the v0.9.x MCPServerDef substrate tool over HTTP.
+     *  Dynamic MCP server registration — register an HTTP /
+     *  Streamable-HTTP MCP server at runtime so its tools become
+     *  callable from any agent's `allowed_tools` list without a yaml
+     *  edit + restart.
+     *
+     *  Operator-admin-only: this endpoint requires the bearer token.
+     *
+     *  Op-discriminated input: `{op: "create" | "fork" | "get" | "list"
+     *  | "promote" | "retire" | "rediscover" | "verify", ...}`. Returns
+     *  shape varies — narrow with {@link MCPServerDefRowResponse} for
+     *  create/fork/get/list rows, {@link MCPServerDefVerifyResult} for
+     *  verify responses.
+     *
+     *  Hard constraints (substrate refuses these):
+     *  - Transport must be `http` or `streamable-http` (stdio stays
+     *    yaml-only — dynamic registration doesn't allow process spawn).
+     *  - URL hostname must be in LOOMCYCLE_HTTP_HOST_ALLOWLIST (SSRF
+     *    defence at the registration boundary).
+     *  - Name colliding with a static cfg.MCPServers entry is refused
+     *    (yaml is ground truth; use a different name).
+     *
+     *  Raises {@link SubstrateToolRefusedError} on tool-level refusals
+     *  (transport/host/yaml-name); {@link InvalidArgumentError} on 400
+     *  (malformed JSON); {@link AuthError} on 401. */
+    async mcpServerDef(input, opts) {
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_mcpserverdef", input, opts);
+    }
+    // ---- Internal helpers ----
+    /** Shared SSE POST → stream-of-AgentEvent path. Used by
+     *  runStreaming + continueSession.
+     *
+     *  When `debug` is true, the iterator yields a synthetic
+     *  `{ type: "_meta", meta_subtype: "stream_open" }` before any real
+     *  events AND a `{ type: "_meta", meta_subtype: "stream_close",
+     *  meta_reason }` on EOF / abort / error. The default is silent
+     *  (matches pre-v0.9.x behaviour). */
+    async *streamSSE(path, body, signal, debug) {
+        const headers = {
+            "Content-Type": "application/json",
+            // Accept BOTH text/event-stream (the success path) AND
+            // application/json (the error path — non-2xx responses come
+            // back as JSON so raiseFromResponse can extract typed errors).
+            // Per the Streamable HTTP spec; strict reverse proxies in
+            // front of the sidecar 406 otherwise. Same rationale as the
+            // v0.8.x MCP HTTP-transport hardening note in CLAUDE.md.
+            Accept: "text/event-stream, application/json",
+        };
+        if (this.ctx.authToken)
+            headers.Authorization = `Bearer ${this.ctx.authToken}`;
+        const resp = await this.ctx.fetchImpl(this.ctx.baseUrl + path, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal,
+        });
+        if (!resp.ok) {
+            await (0, fetch_helpers_js_1.raiseFromResponse)(resp);
+        }
+        if (!resp.body) {
+            throw new Error("loomcycle: response has no body");
+        }
+        if (!debug) {
+            // Silent default — pre-v0.9.x shape.
+            yield* (0, stream_js_1.parseSSE)(resp.body.getReader());
+            return;
+        }
+        // Debug shape: synthetic open + close around the real stream.
+        // The open frame carries no meta_reason — the frame itself IS the
+        // signal. The close frame's meta_reason distinguishes normal EOF
+        // from caller-side abort or a typed-error throw mid-stream.
+        //
+        // Close is emitted on both paths via try/catch/throw: success path
+        // emits AFTER the try block; error path emits INSIDE the catch
+        // before re-throwing. NOT a try/finally — the duplication is
+        // intentional so the close-then-throw ordering is explicit and
+        // a refactor adding `finally` doesn't accidentally double-emit.
+        yield { type: "_meta", meta_subtype: "stream_open" };
+        let closeReason = "eof";
+        try {
+            yield* (0, stream_js_1.parseSSE)(resp.body.getReader());
+        }
+        catch (e) {
+            // Capture the error type for the close frame, then re-throw so
+            // typed-error handling at the consumer site still works.
+            closeReason =
+                e && typeof e === "object" && "name" in e
+                    ? String(e.name)
+                    : "error";
+            yield {
+                type: "_meta",
+                meta_subtype: "stream_close",
+                meta_reason: closeReason,
+            };
+            throw e;
+        }
+        yield {
+            type: "_meta",
+            meta_subtype: "stream_close",
+            meta_reason: closeReason,
+        };
+    }
+    // ---- v0.9.x n8n RFC Phase 0 ----
+    /** List every operator-declared channel with aggregate stats
+     *  (message_count, oldest_visible_at, newest_visible_at).
+     *  Channels with no published messages still appear with
+     *  message_count=0. Orphaned message rows for un-declared channels
+     *  also appear (forensic visibility). Mirrors GET /v1/_channels. */
+    async listChannels(opts) {
+        return await (0, fetch_helpers_js_1.jsonFetch)(this.ctx, "/v1/_channels", opts);
+    }
+    // ---- v0.9.x Channel CRUD ----
+    //
+    // Four bearer-authed ops mirroring the in-band Channel tool's
+    // publish/subscribe/peek/ack. Two URL families behind the
+    // `scope` field:
+    //   - scope: "global" → POST /v1/_channels/{name}/{op} (admin)
+    //   - scope: "user"   → POST /v1/users/{userId}/channels/{name}/{op}
+    //
+    // The same operator bearer token guards both surfaces; the per-user
+    // URL embeds the user_id in the path so a caller can't forge a
+    // different user_id by lying in the body.
+    //
+    // Subscribe is a SINGLE-ROUND-TRIP long-poll, not an open stream.
+    // For continuous delivery, call `subscribeChannel` in a loop (the
+    // n8n trigger node's pattern). Auto-commits the cursor on non-empty
+    // batches (at-most-once shape) — use `peekChannel` + explicit
+    // `ackChannel` for at-least-once semantics.
+    /** Publish a JSON payload to an operator-declared channel. Mirrors
+     *  the in-band Channel tool's publish op semantics — including
+     *  deferred delivery via `deliverAt` (RFC3339Nano).
+     *
+     *  Errors:
+     *  - {@link NotFoundError} (404) when the channel isn't in operator
+     *    yaml. The wire `code` is `channel_not_declared`.
+     *  - {@link InvalidArgumentError} (400) on invalid scope / payload.
+     *  - {@link AuthError} (401) on bearer mismatch. */
+    async publishChannel(channel, opts) {
+        const path = channelOpPath(channel, opts.scope, opts.userId, "publish");
+        const body = { payload: opts.payload };
+        if (opts.deliverAt)
+            body.deliver_at = opts.deliverAt;
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, path, body, {
+            signal: opts.signal,
+        });
+    }
+    /** Read the next batch of messages from a channel. Single-round-
+     *  trip long-poll: returns immediately if messages are present,
+     *  otherwise waits up to `waitMs` for a publish. AUTO-COMMITS the
+     *  cursor on a non-empty batch.
+     *
+     *  For at-least-once delivery (crash safety between "loomcycle
+     *  returned the batch" and "consumer finished processing"), use
+     *  {@link LoomcycleClient.peekChannel} + an explicit
+     *  {@link LoomcycleClient.ackChannel} after durable processing. */
+    async subscribeChannel(channel, opts) {
+        const path = channelOpPath(channel, opts.scope, opts.userId, "subscribe");
+        const body = {};
+        if (opts.fromCursor !== undefined)
+            body.from_cursor = opts.fromCursor;
+        if (opts.maxMessages !== undefined)
+            body.max_messages = opts.maxMessages;
+        if (opts.waitMs !== undefined)
+            body.wait_ms = opts.waitMs;
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, path, body, {
+            signal: opts.signal,
+        });
+    }
+    /** Non-destructive read — never advances the committed cursor.
+     *  Use for at-least-once consumption patterns: peek, process the
+     *  batch durably, then `ackChannel` to advance. Multiple consumers
+     *  can peek the same channel without disturbing each other. */
+    async peekChannel(channel, opts) {
+        let path = channelOpPath(channel, opts.scope, opts.userId, "peek");
+        const params = [];
+        if (opts.fromCursor)
+            params.push(`from_cursor=${encodeURIComponent(opts.fromCursor)}`);
+        if (opts.maxMessages)
+            params.push(`max_messages=${opts.maxMessages}`);
+        if (params.length > 0)
+            path += `?${params.join("&")}`;
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, path, { signal: opts.signal });
+    }
+    /** Advance the committed cursor for a (channel, scope, scope_id)
+     *  tuple. Cursor must be monotonically forward — older cursors
+     *  raise a {@link ConflictError} (HTTP 409, code
+     *  `channel_cursor_regression`). */
+    async ackChannel(channel, opts) {
+        const path = channelOpPath(channel, opts.scope, opts.userId, "ack");
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, path, { cursor: opts.cursor }, { signal: opts.signal });
+    }
+    /** Subscribe to run state transitions for one user_id via SSE.
+     *  Yields one `{ kind: "open", ... }` item first (confirms the
+     *  connection is live), then one `{ kind: "event", ... }` per
+     *  matching state transition until the stream closes.
+     *
+     *  The stream stays open for at most 30 minutes (server-enforced).
+     *  Callers running indefinitely should reconnect on close.
+     *
+     *  Errors during the stream throw — they do NOT surface as items.
+     *  Pass an AbortSignal to terminate cleanly from the consumer side.
+     *
+     *  v0.9.x options:
+     *  - `parentAgentId` — client-side filter: only `kind: "event"`
+     *    items whose payload's `parent_agent_id` matches are yielded.
+     *    The server still streams every matching event; the adapter
+     *    filters before yielding. Empty/omitted = no filter.
+     *  - `debug` — when true, an additional `{ kind: "close", payload:
+     *    { reason } }` item is yielded when the stream ends (EOF,
+     *    abort, or pre-yield error). Useful for n8n nodes that surface
+     *    "stream re-opened / closed" log entries without inferring
+     *    from timing. Default false. */
+    async *streamUserRunStates(userId, opts) {
+        const params = new URLSearchParams();
+        if (opts?.statuses && opts.statuses.length > 0) {
+            params.set("status", opts.statuses.join(","));
+        }
+        if (opts?.agent) {
+            params.set("agent", opts.agent);
+        }
+        const qs = params.toString();
+        const path = `/v1/users/${encodeURIComponent(userId)}/agents/stream` +
+            (qs ? `?${qs}` : "");
+        const headers = {
+            Accept: "text/event-stream",
+        };
+        if (this.ctx.authToken) {
+            headers.Authorization = `Bearer ${this.ctx.authToken}`;
+        }
+        const resp = await this.ctx.fetchImpl(this.ctx.baseUrl + path, {
+            method: "GET",
+            headers,
+            signal: opts?.signal,
+        });
+        if (!resp.ok) {
+            await (0, fetch_helpers_js_1.raiseFromResponse)(resp);
+        }
+        if (!resp.body) {
+            throw new Error("loomcycle: streamUserRunStates response has no body");
+        }
+        const parentFilter = opts?.parentAgentId ?? "";
+        const debug = opts?.debug === true;
+        let closeReason = "eof";
+        try {
+            for await (const item of parseRunStateSSE(resp.body.getReader())) {
+                // Client-side parent_agent_id filter. Pre-v1 the server has no
+                // ?parent_agent_id= query param; n8n-style consumers that need
+                // a narrow view get a smaller iterator at the cost of
+                // unchanged server load. See StreamUserRunStatesOptions for
+                // the trade-off note.
+                if (parentFilter !== "" &&
+                    item.kind === "event" &&
+                    item.payload.parent_agent_id !== parentFilter) {
+                    continue;
+                }
+                yield item;
+            }
+        }
+        catch (e) {
+            closeReason =
+                e && typeof e === "object" && "name" in e
+                    ? String(e.name)
+                    : "error";
+            if (debug) {
+                yield { kind: "close", payload: { reason: closeReason } };
+            }
+            throw e;
+        }
+        if (debug) {
+            yield { kind: "close", payload: { reason: closeReason } };
+        }
+    }
+}
+exports.LoomcycleClient = LoomcycleClient;
+/** Lightweight SSE parser tailored to the run-state stream. Each
+ *  frame's event name distinguishes the two kinds; data is JSON.
+ *  Comment lines (": keepalive") are ignored. */
+async function* parseRunStateSSE(reader) {
+    const decoder = new TextDecoder("utf-8");
+    let buf = "";
+    let event = "";
+    let data = "";
+    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 === "") {
+                if (event && data) {
+                    try {
+                        const parsed = JSON.parse(data);
+                        if (event === "stream_open") {
+                            yield {
+                                kind: "open",
+                                payload: parsed,
+                            };
+                        }
+                        else if (event === "run_state") {
+                            yield {
+                                kind: "event",
+                                payload: parsed,
+                            };
+                        }
+                    }
+                    catch {
+                        // Drop malformed frame silently — same posture as parseSSE.
+                    }
+                }
+                event = "";
+                data = "";
+                continue;
+            }
+            if (line.startsWith("event:"))
+                event = line.slice("event:".length).trim();
+            else if (line.startsWith("data:"))
+                data = line.slice("data:".length).trim();
+        }
+    }
+}
+// channelOpPath builds the v0.9.x Channel CRUD URL. Two families:
+//   - scope === "global" → /v1/_channels/{channel}/{op}
+//   - scope === "user"   → /v1/users/{userId}/channels/{channel}/{op}
+// Channel name is URL-encoded so names containing slashes
+// ("findings/alpha", "_system/foo") survive transport.
+function channelOpPath(channel, scope, userId, op) {
+    const enc = encodeURIComponent(channel);
+    if (scope === "user") {
+        if (!userId) {
+            throw new Error(`loomcycle: scope="user" requires opts.userId for the channel ${op} call`);
+        }
+        return `/v1/users/${encodeURIComponent(userId)}/channels/${enc}/${op}`;
+    }
+    return `/v1/_channels/${enc}/${op}`;
+}