@loomcycle/client 0.9.0 → 0.9.2

package/README.md

@@ -6,10 +6,19 @@ TypeScript client for the [loomcycle](https://github.com/denn-gubsky/loomcycle)
 
 ## Status
 
-**v0.8.18** — full Python-adapter parity + hook management. 27 methods covering run streaming, agent metadata, transcript, pause/resume/state, snapshot lifecycle, memory admin, interruption resolve, hook registration, and health.
+**v0.11.0** — 31 methods covering run streaming, agent metadata, transcript, pause/resume/state, snapshot lifecycle, memory admin, interruption resolve, hook registration, **v0.8.22 substrate admin (agentDef + skillDef)**, **v0.9.x n8n Phase 0 (listChannels + streamUserRunStates)**, **v0.9.x content_sha256** (the bundle-vs-deployed comparison workflow for Docker-bundled operators), and health.
 
 > Migrating from raw `fetch` against `/v1/*`? See **[docs/MIGRATING-FROM-HTTP.md](./docs/MIGRATING-FROM-HTTP.md)** for a side-by-side walkthrough.
 
+### What's new since v0.8.18
+
+- **`agentDef` / `skillDef`** (v0.8.22) — runtime fork / promote / retire / get / list / `verify` on the substrate. Lets a containerised app push agent + skill definitions to a remote loomcycle at startup without restarting it.
+- **`listChannels`** (v0.9.x) — list operator-declared channels with aggregate stats (message_count, oldest/newest visible_at). The substrate companion to the existing Channel tool; useful for credential pickers + dashboards.
+- **`streamUserRunStates`** (v0.9.x) — SSE stream of run state transitions scoped to one `user_id`. Yields `{ kind: "open" | "event", payload }` items until the connection closes (30-min server cap). The primary substrate hook for orchestration UIs that need to react when an agent run completes / fails / cancels.
+- **Content signatures** (v0.9.x) — every `agent_defs` / `skill_defs` row now carries a deterministic `content_sha256`. Combined with the `verify` op and the `loomcycle hash agent|skill` CLI subcommand, this gives Docker-bundled operators a one-call answer to *"is what I have in my image identical to what's deployed?"* — see [Content signatures](#content-signatures-v09x) below for the end-to-end workflow.
+- **Transcript first-cycle types** (v0.9.1) — `UserInputPayload` + `SystemPromptPayload` typed interfaces for the two new transcript events that surface "what the agent actually received" (the resolved system prompt + the caller's segments) as the first frames of every run.
+- **n8n polish — `debug` toggle + `parentAgentId` filter** (v0.13.0) — opt-in synthetic `stream_open` / `stream_close` frames on `runStreaming` / `continueSession` / `streamUserRunStates` plus a client-side `parentAgentId` filter on `listUserAgents` + `streamUserRunStates`. Default behaviour is unchanged for existing callers; both knobs are off until set. See [Patterns](#patterns) for when to reach for them.
+
 ## Install
 
 ```bash
@@ -207,6 +216,165 @@ export async function POST(req: Request) {
 - `fail_mode: "open"` (default) is right for telemetry hooks where a down receiver shouldn't break tool dispatch. `"closed"` is right for security hooks where a down receiver should fail the tool call (don't let bypassed payloads through).
 - `allow_hosts` in `PreHookResult` is a **trust-sensitive surface** — it widens the agent's outbound network policy for one tool call. Server enforces an operator-yaml allowlist (`hooks.permit_host_widen.owners`); your owner has to be on that list for `allow_hosts` to take effect. See the SECURITY note in `internal/hooks/types.go` before using.
 
+### Substrate admin: AgentDef + SkillDef (v0.8.22)
+
+Two op-discriminated methods that mirror the in-process `AgentDef` / `SkillDef` built-in tools over HTTP. The same `op` values an agent's tool_use would invoke are reachable directly from your app code — useful for runtime fork / promote / retire / list, and for the `verify` op covered in [Content signatures](#content-signatures-v09x).
+
+| Method | Returns | Notes |
+|---|---|---|
+| `agentDef(input)` | `Promise<SubstrateToolResponse>` | Op-discriminated. Mirrors `POST /v1/_agentdef`. |
+| `skillDef(input)` | `Promise<SubstrateToolResponse>` | Op-discriminated. Mirrors `POST /v1/_skilldef`. |
+
+The response type is intentionally `unknown` because the shape varies per op (`create`/`fork` return a row envelope; `list` returns `{name, versions: [...]}`; `verify` returns `AgentDefVerifyResult` / `SkillDefVerifyResult`). Cast / narrow as needed:
+
+```ts
+import type { AgentDefRowResponse } from "@loomcycle/client";
+
+const forked = (await client.agentDef({
+  op: "fork",
+  name: "researcher",
+  overlay: { system_prompt: "be very thorough", max_iterations: 32 },
+  promote: true,
+})) as AgentDefRowResponse;
+
+console.log(`forked def_id=${forked.def_id} hash=${forked.content_sha256}`);
+```
+
+Operations on AgentDef: `create` / `fork` / `get` / `list` / `promote` / `retire` / **`verify`** (v0.9.x). SkillDef has the same set minus `retire`'s edge cases. See `internal/tools/builtin/agentdef.go` for the canonical input schema; each op enforces the agent's `agent_def_scopes` / `skill_def_scopes` capability gate from the operator yaml.
+
+Refusals throw `SubstrateToolRefusedError` (a scope deny / empty body / allowed-tools widening); transport failures throw the usual typed errors (`AuthError`, `UnavailableError`, etc.).
+
+### Channels + run-state stream (v0.9.x n8n Phase 0)
+
+Two substrate-side surfaces added in the n8n integration's Phase 0 wire-API work. Useful for any orchestrator (not just n8n) that needs to see channel state or subscribe to run-state transitions.
+
+| Method | Returns | Notes |
+|---|---|---|
+| `listChannels()` | `Promise<ListChannelsResponse>` | Operator-declared channels + aggregate stats (`message_count`, `oldest_visible_at`, `newest_visible_at`). Mirrors `GET /v1/_channels`. |
+| `streamUserRunStates(userId, opts?)` | `AsyncIterable<RunStateStreamItem>` | SSE stream of run state transitions for one user. Yields one `{ kind: "open", ... }` frame then one `{ kind: "event", payload: RunStateEvent }` per matching transition until close. |
+
+**Streaming run-state events** — for orchestration UIs that want to react when an agent run completes / fails / cancels:
+
+```ts
+import type { RunStateEvent } from "@loomcycle/client";
+
+const ac = new AbortController();
+const stream = client.streamUserRunStates(userId, {
+  statuses: ["completed", "failed", "cancelled"], // optional filter
+  agent: "researcher",                            // optional filter
+  signal: ac.signal,
+});
+
+for await (const item of stream) {
+  if (item.kind === "open") {
+    console.log(`stream open for user=${item.payload.user_id}`);
+    continue;
+  }
+  const evt: RunStateEvent = item.payload;
+  console.log(`${evt.agent}/${evt.run_id} -> ${evt.status} (stop_reason=${evt.stop_reason ?? "-"})`);
+  // ... persist to DB, push to UI websocket, fire webhook, etc.
+}
+```
+
+The stream stays open for up to 30 minutes (server-enforced); reconnect on close for long-running orchestrators. Filters apply server-side; an empty filter delivers all transitions.
+
+### Content signatures (v0.9.x)
+
+**The bundle-vs-deployed comparison feature.** Every persisted `agent_defs` and `skill_defs` row carries a deterministic SHA-256 of its content-bearing fields (`content_sha256`). Combined with the CLI helper `loomcycle hash agent|skill <path>`, this lets Docker-bundled operators answer *"is what I have in my image identical to what's deployed?"* with one cheap call instead of fetching the full Definition JSONB and diffing it field by field.
+
+**The workflow** — three steps, fully Dockerfile-friendly:
+
+1. **At image-build time** (in your Dockerfile or CI): run the CLI against each bundled MD to capture the expected hash.
+
+   ```dockerfile
+   # Dockerfile
+   COPY agents/    /bundle/agents/
+   COPY skills/    /bundle/skills/
+   RUN /usr/local/bin/loomcycle hash agent /bundle/agents/researcher.md > /bundle/agents/researcher.sha256
+   RUN /usr/local/bin/loomcycle hash skill /bundle/skills/summariser   > /bundle/skills/summariser.sha256
+   ```
+
+2. **At container startup**: ask the deployed loomcycle whether each agent is in sync. Use `agentDef({op:"verify"})` / `skillDef({op:"verify"})` and narrow the response to `AgentDefVerifyResult` / `SkillDefVerifyResult`:
+
+   ```ts
+   import { readFile } from "node:fs/promises";
+   import type { AgentDefVerifyResult } from "@loomcycle/client";
+
+   const localHash = (await readFile("/bundle/agents/researcher.sha256", "utf-8")).trim();
+   const verify = (await client.agentDef({
+     op: "verify",
+     name: "researcher",
+     content_sha256: localHash,
+   })) as AgentDefVerifyResult;
+
+   if (verify.matches) {
+     console.log("researcher in sync");
+   } else if (!verify.deployed) {
+     console.log("researcher not deployed yet; pushing first version");
+     await pushAgent("/bundle/agents/researcher.md"); // your set-agent helper
+   } else {
+     console.log(`researcher drifted; deployed=${verify.current_sha256} local=${localHash}; pushing update`);
+     await pushAgent("/bundle/agents/researcher.md");
+   }
+   ```
+
+3. **Pushing on mismatch** is `agentDef({op:"set"|"fork", overlay: {...}})` with the same content the YAML expresses, parsed from your bundle.
+
+| Method | Returns | Notes |
+|---|---|---|
+| `agentDef({op:"verify", name, content_sha256})` | `Promise<AgentDefVerifyResult>` | `{matches, current_sha256, current_def_id, version, name, deployed}`. |
+| `skillDef({op:"verify", name, content_sha256})` | `Promise<SkillDefVerifyResult>` | Same shape. |
+
+**Key invariants:**
+
+- `matches: true` only when both hashes are non-empty AND equal. An empty caller hash NEVER matches (no false-positive when the deployed row's hash is also empty due to a not-yet-completed backfill).
+- `deployed: false` ⇒ `matches: false`. Use this to distinguish "no active row" (first deploy) from "drift" (push update).
+- The CLI hash and the substrate's hash are guaranteed identical for matching content — both compute through the same Go function in `internal/agents.Sign`.
+- Agent hash covers `name + description + system_prompt + allowed_tools + skills + model + provider + tier + effort + max_tokens + max_iterations + providers + models + memory_scopes + memory_quota_bytes`. Explicitly excluded: `def_id`, `version`, `created_at`, `retired`, **plus** `channels` and `*_scopes` (operator-yaml-only ACL fields that don't round-trip through `set` / `fork`).
+- Skill hash covers `name + description + body + allowed_tools`. Skill bodies are normalised before hashing (CRLF → LF; trailing whitespace stripped) so editor drift doesn't cause spurious mismatches.
+
+See `help(topic="content-signatures")` from inside an agent run for the full operator narrative.
+
+### Transcript first-cycle types (v0.9.1)
+
+Every run's persisted transcript now records two events that describe **what the agent actually received** before any model output:
+
+- **`system_prompt`** — the resolved system prompt (AgentDef body + skill bodies, after overlay + merge), with provenance (`agent_def_id` + `skill_def_ids` map).
+- **`user_input`** — the caller's `segments` from the original `POST /v1/runs`.
+
+Surface them via `getTranscript(sessionId)` and narrow on `event.type`:
+
+```ts
+import type {
+  SystemPromptPayload,
+  TranscriptEvent,
+  UserInputPayload,
+} from "@loomcycle/client";
+
+const { events } = await client.getTranscript(sessionId);
+
+for (const ev of events as TranscriptEvent[]) {
+  if (ev.type === "system_prompt") {
+    const p = ev.payload as SystemPromptPayload;
+    console.log(`prompt (def_id=${p.agent_def_id ?? "-"}): ${p.system_prompt.slice(0, 80)}...`);
+    if (p.skill_def_ids) {
+      for (const [skill, defId] of Object.entries(p.skill_def_ids)) {
+        console.log(`  skill ${skill} resolved to def_id=${defId}`);
+      }
+    }
+  } else if (ev.type === "user_input") {
+    const segs = ev.payload as UserInputPayload[];
+    console.log(`caller sent ${segs.length} segment(s):`);
+    for (const seg of segs) {
+      const firstText = seg.content.find((c) => c.type.endsWith("text"))?.text ?? "";
+      console.log(`  [${seg.role}] ${firstText.slice(0, 80)}`);
+    }
+  }
+}
+```
+
+These events are part of the persisted transcript (not the live `runStreaming` event channel — they fire before the first model call, before the SSE stream consumer typically attaches). Existing transcript readers that don't know the new types see them as `event: unknown` with the typed body in `payload` and ignore them safely.
+
 ## Errors
 
 Non-2xx responses throw typed subclasses of `LoomcycleError`. The original HTTP status is on `e.status`; the truncated response body is on `e.bodyText` (≤1 KiB).
@@ -254,6 +422,80 @@ try {
 }
 ```
 
+## Patterns
+
+A short field guide for the common consumer shapes — when to use which method, what each one costs, and how the v0.9.x polish hooks (`debug`, `parentAgentId`) fit in.
+
+### Sync vs async run consumption
+
+`runStreaming` and `continueSession` are **sync**: the iterator stays alive for the FULL duration of the run. Use them when:
+
+- You have a single agent run and want to render its output progressively (UI streaming, CLI tail-like display).
+- The caller can hold a connection per active run without worker-thread starvation.
+
+For async fire-and-forget patterns (the n8n trigger node's model), use `streamUserRunStates` instead:
+
+```ts
+// Don't do this in an n8n worker — blocks the worker for the full run:
+for await (const ev of client.runStreaming({ agent: "long-task", segments })) { ... }
+
+// Do this instead — kick off the run, get back a tracking ID, and watch run-state transitions:
+const seedRun = await runOnce(...);  // your one-shot dispatch
+for await (const item of client.streamUserRunStates(userId, {
+  statuses: ["completed", "failed", "cancelled"],
+})) {
+  if (item.kind === "event" && item.payload.agent_id === seedRun.agentId) {
+    // fire downstream workflow, persist to DB, etc.
+    break;
+  }
+}
+```
+
+`streamUserRunStates` holds ONE connection per user regardless of how many concurrent runs that user has. Server-enforced 30-minute timeout; reconnect on close.
+
+### `debug: true` — synthetic open/close frames
+
+All three streaming methods (`runStreaming`, `continueSession`, `streamUserRunStates`) accept `debug?: boolean`. Default off; behaviour is exactly the pre-v0.9.x shape.
+
+When `debug: true`:
+- `runStreaming` / `continueSession` brackets the real events with `{ type: "_meta", meta_subtype: "stream_open" | "stream_close", meta_reason }` frames. The leading-underscore type signals "client-synthesized; never on the wire." The `meta_reason` is `"eof"` on clean close or an error class name (e.g. `"AuthError"`) when the inner iterator threw mid-stream.
+- `streamUserRunStates` yields an extra `{ kind: "close", payload: { reason } }` item on stream end (in addition to the existing `kind: "open" | "event"` frames).
+
+```ts
+for await (const ev of client.runStreaming({ agent: "qa", segments, debug: true })) {
+  if (ev.type === "_meta") {
+    console.log(`[stream ${ev.meta_subtype}] reason=${ev.meta_reason}`);
+    continue;
+  }
+  // ... handle real events
+}
+```
+
+Use case: n8n trigger nodes that surface "stream re-opened / closed" log entries to the operator without inferring from event timing. Non-n8n consumers don't need to know the toggle exists.
+
+### `parentAgentId` — client-side narrowing
+
+`listUserAgents(userId, { parentAgentId })` and `streamUserRunStates(userId, { parentAgentId })` apply a client-side filter on the run's `parent_agent_id`. The server still returns / streams the full set; the adapter trims before yielding.
+
+```ts
+// All sub-runs spawned by a specific parent (one-shot snapshot)
+const subRuns = await client.listUserAgents(userId, {
+  parentAgentId: "ag_parent_abc",
+  status: "running",
+});
+
+// Same shape, but as a live stream
+for await (const item of client.streamUserRunStates(userId, {
+  parentAgentId: "ag_parent_abc",
+  statuses: ["completed", "failed"],
+})) {
+  // Only events whose payload.parent_agent_id === "ag_parent_abc"
+  // (open and close frames always pass through).
+}
+```
+
+**Cost note:** because the filter is client-side, the server doesn't shed any load. If the result set is large enough that you care about server-side narrowing, raise an issue — server-side `?parent_agent_id=` is a planned addition.
+
 ## Why HTTP, not gRPC
 
 Loomcycle's HTTP+SSE surface is the canonical wire contract — every gRPC RPC has an HTTP equivalent (see `internal/api/http/server.go` for the route registrations). The Python adapter (gRPC) and this TS adapter (HTTP) cover the same surface; the choice between them is about ecosystem fit, not capability. HTTP+SSE works through every reverse proxy without special config; gRPC needs HTTP/2 + protoc round trips. For Node.js orchestrators that already have `fetch` in scope, HTTP is the simpler dependency.

package/dist/client.d.ts

@@ -23,7 +23,7 @@
  * via fetch-helpers.ts:raiseFromResponse — see README.md for the
  * full mapping table.
  */
-import type { Agent, AgentEvent, AgentStatus, CancelAgentResult, ClientOptions, ContinueOptions, CreateSnapshotOptions, HealthResponse, Hook, InterruptListResponse, InterruptStatus, ListUsersResponse, MemoryEntriesResponse, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopesResponse, PauseResult, RegisterHookOptions, RegisterHookResponse, ResolveInterruptOptions, ResumeResult, RunOptions, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, SubstrateToolInput, SubstrateToolResponse, TranscriptResponse } from "./types.js";
+import type { Agent, AgentEvent, AgentStatus, CancelAgentResult, ClientOptions, ContinueOptions, CreateSnapshotOptions, HealthResponse, Hook, InterruptListResponse, InterruptStatus, AckChannelOptions, ChannelAckResult, ChannelPeekResult, ChannelPublishResult, ChannelSubscribeResult, ListChannelsResponse, PeekChannelOptions, PublishChannelOptions, SubscribeChannelOptions, ListUsersResponse, MemoryEntriesResponse, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopesResponse, PauseResult, RegisterHookOptions, RegisterHookResponse, ResolveInterruptOptions, ResumeResult, RunOptions, RunStateStreamItem, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, StreamUserRunStatesOptions, SubstrateToolInput, SubstrateToolResponse, TranscriptResponse } from "./types.js";
 export declare class LoomcycleClient {
     private ctx;
     constructor(opts?: ClientOptions);
@@ -34,6 +34,19 @@ export declare class LoomcycleClient {
      * 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.
      */
     runStreaming(opts: RunOptions): AsyncIterable<AgentEvent>;
     /**
@@ -44,6 +57,14 @@ export declare class LoomcycleClient {
      * 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.
      */
     continueSession(opts: ContinueOptions): AsyncIterable<AgentEvent>;
     /** Read one agent's status + usage stats. Raises AgentNotFoundError
@@ -58,9 +79,16 @@ export declare class LoomcycleClient {
         reason?: string;
         signal?: AbortSignal;
     }): Promise<CancelAgentResult>;
-    /** List a user's recent agent runs, optionally filtered by status. */
+    /** 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." */
     listUserAgents(userId: string, opts?: {
         status?: AgentStatus;
+        parentAgentId?: string;
         signal?: AbortSignal;
     }): Promise<Agent[]>;
     /** Read the full event log for a session. Each entry has seq,
@@ -233,7 +261,101 @@ export declare class LoomcycleClient {
     skillDef(input: SubstrateToolInput, opts?: {
         signal?: AbortSignal;
     }): Promise<SubstrateToolResponse>;
+    /** 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. */
+    mcpServerDef(input: SubstrateToolInput, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SubstrateToolResponse>;
     /** Shared SSE POST → stream-of-AgentEvent path. Used by
-     *  runStreaming + continueSession. */
+     *  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). */
     private streamSSE;
+    /** 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. */
+    listChannels(opts?: {
+        signal?: AbortSignal;
+    }): Promise<ListChannelsResponse>;
+    /** 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. */
+    publishChannel(channel: string, opts: PublishChannelOptions): Promise<ChannelPublishResult>;
+    /** 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. */
+    subscribeChannel(channel: string, opts: SubscribeChannelOptions): Promise<ChannelSubscribeResult>;
+    /** 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. */
+    peekChannel(channel: string, opts: PeekChannelOptions): Promise<ChannelPeekResult>;
+    /** 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`). */
+    ackChannel(channel: string, opts: AckChannelOptions): Promise<ChannelAckResult>;
+    /** 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. */
+    streamUserRunStates(userId: string, opts?: StreamUserRunStatesOptions): AsyncIterable<RunStateStreamItem>;
 }

package/dist/client.js

@@ -42,6 +42,19 @@ export class LoomcycleClient {
      * 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.
@@ -73,7 +86,7 @@ export class LoomcycleClient {
             body.user_tier = opts.userTier;
         if (opts.userBearer !== undefined)
             body.user_bearer = opts.userBearer;
-        yield* this.streamSSE("/v1/runs", body, opts.signal);
+        yield* this.streamSSE("/v1/runs", body, opts.signal, opts.debug);
     }
     /**
      * Continue an existing session with a new run. The session's prior
@@ -83,6 +96,14 @@ export class LoomcycleClient {
      * 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 = {
@@ -101,7 +122,7 @@ export class LoomcycleClient {
             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);
+        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
@@ -116,11 +137,21 @@ export class LoomcycleClient {
         const resp = await 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. */
+    /** 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 jsonFetch(this.ctx, `/v1/users/${encodeURIComponent(userId)}/agents${q}`, opts);
-        return resp.agents ?? [];
+        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). */
@@ -360,10 +391,44 @@ export class LoomcycleClient {
     async skillDef(input, opts) {
         return 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 postJSON(this.ctx, "/v1/_mcpserverdef", input, opts);
+    }
     // ---- Internal helpers ----
     /** Shared SSE POST → stream-of-AgentEvent path. Used by
-     *  runStreaming + continueSession. */
-    async *streamSSE(path, body, signal) {
+     *  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
@@ -388,6 +453,278 @@ export class LoomcycleClient {
         if (!resp.body) {
             throw new Error("loomcycle: response has no body");
         }
-        yield* parseSSE(resp.body.getReader());
+        if (!debug) {
+            // Silent default — pre-v0.9.x shape.
+            yield* 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* 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 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 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 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 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 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 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 } };
+        }
+    }
+}
+/** 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}`;
 }

package/dist/errors.d.ts

@@ -133,6 +133,22 @@ export declare class HookNotFoundError extends NotFoundError {
         bodyText?: string;
     });
 }
+/** 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. */
+export declare class ChannelCursorRegressionError extends LoomcycleError {
+    constructor(message: string, opts?: {
+        status?: number;
+        bodyText?: string;
+    });
+}
 /** SubstrateToolRefusedError — raised by `client.agentDef()` /
  *  `client.skillDef()` when the in-process tool refused the call
  *  (scope deny, empty body, allowed-tools widening, etc.). HTTP

package/dist/errors.js

@@ -136,6 +136,22 @@ export class HookNotFoundError extends NotFoundError {
         this.name = "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. */
+export class ChannelCursorRegressionError extends LoomcycleError {
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "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

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, 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, 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. */
@@ -157,6 +157,10 @@ export async function raiseFromResponse(resp) {
                 throw new AlreadyPausingError(msg, opts);
             if (bodyLower.includes("not_paused") || bodyLower.includes("not paused"))
                 throw new 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 ChannelCursorRegressionError(msg, opts);
             if (bodyLower.includes("session"))
                 throw new SessionBusyError(msg, opts);
             if (bodyLower.includes("agent_id"))

package/dist/index.d.ts

@@ -64,5 +64,5 @@
  * See `adapters/ts/README.md` for usage examples.
  */
 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, } from "./types.js";
-export { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, HookNotFoundError, NotFoundError, InvalidArgumentError, LoomcycleError, NotPausedError, PauseNotConfiguredError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, UnavailableError, } from "./errors.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";

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, 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, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, UnavailableError, } from "./errors.js";

package/dist/types.d.ts

@@ -7,7 +7,7 @@
  * `client.ts` for the input shapes (RunOptions, CreateSnapshotOptions,
  * etc.) — those are translated to snake_case in the request body.
  */
-export type EventType = "started" | "text" | "tool_call" | "tool_result" | "usage" | "done" | "error" | "retry" | "host_widened" | "session" | "agent";
+export type EventType = "started" | "text" | "tool_call" | "tool_result" | "usage" | "done" | "error" | "retry" | "host_widened" | "session" | "agent" | "_meta";
 export interface ToolUse {
     id: string;
     name: string;
@@ -69,6 +69,8 @@ export interface AgentEvent {
     run_id?: string;
     session_id?: string;
     parent_agent_id?: string | null;
+    meta_subtype?: "stream_open" | "stream_close";
+    meta_reason?: string;
 }
 export type PromptContent = {
     type: "trusted-text";
@@ -128,6 +130,14 @@ export interface RunOptions {
      *  (static-bearer setups unaffected). Sub-agents inherit identically.
      *  Never persisted; never logged in full. */
     userBearer?: string;
+    /** Opt-in observability: when true, the iterator emits client-
+     *  synthesized `{ type: "_meta", meta_subtype: "stream_open" | "stream_close" }`
+     *  events around the real event stream. `meta_reason` carries the
+     *  trigger ("eof", "abort", or an error class name). Default is
+     *  false — existing consumers see no behaviour change. Useful for
+     *  n8n nodes that want to surface "stream re-opened" / "stream
+     *  closed" log entries without inferring from event timing. */
+    debug?: boolean;
     signal?: AbortSignal;
 }
 export interface ContinueOptions {
@@ -156,6 +166,8 @@ export interface ContinueOptions {
      *  so different continuations in the same session may carry
      *  different end-user tokens. */
     userBearer?: string;
+    /** Opt-in observability: see {@link RunOptions.debug}. Same shape. */
+    debug?: boolean;
     signal?: AbortSignal;
 }
 export interface ClientOptions {
@@ -208,13 +220,50 @@ export interface CancelAgentResult {
 }
 /** TranscriptEvent — one persisted store.Event from
  *  GET /v1/sessions/{id}/transcript. The server wraps each
- *  providers.Event in {seq, run_id, ts_ns, type, event:{...}}. */
+ *  providers.Event in {seq, run_id, ts_ns, type, event:{...}}.
+ *
+ *  `payload` is the v0.9.1 sidecar field carrying the typed body of
+ *  events that don't fit the providers.Event union (the first-cycle
+ *  `system_prompt` + `user_input` transcript events). Narrow on
+ *  `type` to pick the right payload interface — see
+ *  {@link SystemPromptPayload} and {@link UserInputPayload}. */
 export interface TranscriptEvent {
     seq: number;
     run_id: string;
     ts_ns: number;
     type: string;
     event: unknown;
+    /** v0.9.1+ sidecar for typed transcript events:
+     *    type === "system_prompt" → SystemPromptPayload
+     *    type === "user_input"    → UserInputPayload[]
+     *  Absent for events the server hands through via `event`. */
+    payload?: SystemPromptPayload | UserInputPayload[] | unknown;
+}
+/** UserInputPayload mirrors the JSON of one `loop.PromptSegment` —
+ *  what the caller supplied as `segments` on POST /v1/runs +
+ *  /v1/sessions/{id}/messages. The transcript event's `payload`
+ *  field carries the FULL array (`UserInputPayload[]`) because one
+ *  call may include multiple segments (system + user prepends, etc.). */
+export interface UserInputPayload {
+    role: string;
+    content: Array<{
+        type: string;
+        text?: string;
+        cacheable?: boolean;
+    }>;
+}
+/** SystemPromptPayload mirrors the v0.9.1 system_prompt transcript
+ *  event payload — the resolved system prompt + provenance metadata
+ *  so operators can see WHICH AgentDef + WHICH SkillDef rows fed in. */
+export interface SystemPromptPayload {
+    system_prompt: string;
+    /** Empty for yaml-only agents (no AgentDef row). Pinned for
+     *  sub-runs spawned via the Agent tool with a def_id. */
+    agent_def_id?: string;
+    /** skillName → active SkillDef def_id. Only present for skills
+     *  whose DB-active row supplied the body; static-fallback skills
+     *  are absent. */
+    skill_def_ids?: Record<string, string>;
 }
 export interface TranscriptResponse {
     session: {
@@ -502,3 +551,263 @@ export type SubstrateToolResponse = unknown;
 export interface PostHookResult {
     result?: HookToolResult;
 }
+/** Aggregate stats for one operator-declared channel. Returned by
+ *  {@link LoomcycleClient.listChannels}. */
+export interface ChannelDescriptor {
+    name: string;
+    scope?: string;
+    semantic?: string;
+    publisher?: string;
+    period?: string;
+    default_ttl?: number;
+    max_messages?: number;
+    message_count: number;
+    /** RFC3339 — empty when count == 0. */
+    oldest_visible_at?: string;
+    newest_visible_at?: string;
+}
+/** Response shape for {@link LoomcycleClient.listChannels}. */
+export interface ListChannelsResponse {
+    channels: ChannelDescriptor[];
+}
+/** Scope selector for the Channel CRUD methods. `"global"` addresses
+ *  the admin surface; `"user"` requires `userId` and addresses the
+ *  per-end-user URL family. */
+export type ChannelScope = "global" | "user";
+/** Options for {@link LoomcycleClient.publishChannel}. `payload` is
+ *  the raw JSON value (object, array, string, number) to publish.
+ *  `deliverAt` (RFC3339Nano) defers the publish so long-poll
+ *  subscribers wake at the visible_at time. */
+export interface PublishChannelOptions {
+    scope: ChannelScope;
+    /** Required when scope === "user". The per-user URL is
+     *  /v1/users/{userId}/channels/{channel}/publish. */
+    userId?: string;
+    payload: unknown;
+    /** RFC3339Nano deferred-publish time. Omit for "publish now". */
+    deliverAt?: string;
+    signal?: AbortSignal;
+}
+/** Response shape for {@link LoomcycleClient.publishChannel}. */
+export interface ChannelPublishResult {
+    msg_id: string;
+    channel: string;
+    /** RFC3339Nano. */
+    created_at: string;
+    /** RFC3339Nano. Omitted when the publish was immediate. */
+    visible_at?: string;
+}
+/** Options for {@link LoomcycleClient.subscribeChannel}. The call is a
+ *  single-round-trip long-poll, NOT an open SSE stream — returns
+ *  immediately if messages are present, otherwise waits up to
+ *  `waitMs` for a publish. Auto-commits the cursor on a non-empty
+ *  batch (at-most-once shape). For at-least-once, use
+ *  {@link LoomcycleClient.peekChannel} + explicit ack. */
+export interface SubscribeChannelOptions {
+    scope: ChannelScope;
+    userId?: string;
+    /** Cursor to read forward from. Empty/omitted = the committed
+     *  cursor. `"cur_0"` = replay from the oldest non-expired row. */
+    fromCursor?: string;
+    /** Defaults to 10; clamped at 100 by the server. */
+    maxMessages?: number;
+    /** Long-poll timeout in ms. 0 / omitted = poll once and return.
+     *  Capped at the operator's `ChannelsLongPollCapMS` (default 30s). */
+    waitMs?: number;
+    signal?: AbortSignal;
+}
+/** One delivered message — same wire shape as the in-band Channel
+ *  tool's subscribe response. */
+export interface ChannelMessageItem {
+    id: string;
+    value: unknown;
+    /** RFC3339Nano. */
+    published_at: string;
+}
+/** Response shape for {@link LoomcycleClient.subscribeChannel}. */
+export interface ChannelSubscribeResult {
+    channel: string;
+    messages: ChannelMessageItem[];
+    /** Cursor to pass on the next subscribe call to continue forward.
+     *  Empty when the batch is empty. */
+    next_cursor: string;
+}
+/** Options for {@link LoomcycleClient.peekChannel}. */
+export interface PeekChannelOptions {
+    scope: ChannelScope;
+    userId?: string;
+    fromCursor?: string;
+    maxMessages?: number;
+    signal?: AbortSignal;
+}
+/** Response shape for {@link LoomcycleClient.peekChannel}. */
+export interface ChannelPeekResult {
+    channel: string;
+    messages: ChannelMessageItem[];
+}
+/** Options for {@link LoomcycleClient.ackChannel}. */
+export interface AckChannelOptions {
+    scope: ChannelScope;
+    userId?: string;
+    cursor: string;
+    signal?: AbortSignal;
+}
+/** Response shape for {@link LoomcycleClient.ackChannel}. */
+export interface ChannelAckResult {
+    ok: boolean;
+}
+/** One run state transition emitted by
+ *  {@link LoomcycleClient.streamUserRunStates}. The TS field is RFC3339. */
+export interface RunStateEvent {
+    run_id: string;
+    agent_id: string;
+    agent: string;
+    user_id: string;
+    parent_agent_id?: string;
+    status: string;
+    stop_reason?: string;
+    error?: string;
+    ts: string;
+}
+/** Initial stream_open frame emitted before the first run_state. */
+export interface RunStateStreamOpen {
+    user_id: string;
+    filter_status: string[] | null;
+    filter_agent: string;
+    keepalive_interval: number;
+}
+/** Yielded by {@link LoomcycleClient.streamUserRunStates}.
+ *
+ *  The first item is always `{ kind: "open", payload: RunStateStreamOpen }`.
+ *  Subsequent items are `{ kind: "event", payload: RunStateEvent }`.
+ *
+ *  Consumers branch on `kind`; the `open` frame is useful for confirming
+ *  the connection before any real events flow. */
+export type RunStateStreamItem = {
+    kind: "open";
+    payload: RunStateStreamOpen;
+} | {
+    kind: "event";
+    payload: RunStateEvent;
+} | {
+    kind: "close";
+    payload: RunStateStreamClose;
+};
+/** Optional filter for {@link LoomcycleClient.streamUserRunStates}. */
+export interface StreamUserRunStatesOptions {
+    /** Subset of states to receive. Empty means all states. */
+    statuses?: string[];
+    /** Filter to one agent name. Empty means any. */
+    agent?: string;
+    /** v0.9.x — client-side filter on the run's parent_agent_id.
+     *  Useful for "show me only the sub-runs spawned by agent X."
+     *  The filter is applied AFTER the SSE frame is parsed, so this
+     *  shrinks what your callback sees but doesn't reduce server-side
+     *  load. Server-side filtering is a separate (future) request.
+     *  Pass the empty string to opt out (default). */
+    parentAgentId?: string;
+    /** v0.9.x — opt-in observability: when true, the iterator yields a
+     *  client-synthesized `{ kind: "close", payload: { reason } }` item
+     *  when the stream ends (EOF, abort, or error). `reason` carries
+     *  the cause ("eof" on clean close or an error class name like
+     *  "AbortError" / "AuthError"). The opening `kind: "open"` frame
+     *  that always appears first is server-emitted, not synthetic;
+     *  `debug` has no effect on it. Default false leaves behaviour
+     *  identical to v0.9.x earlier. */
+    debug?: boolean;
+    signal?: AbortSignal;
+}
+/** v0.9.x — close-event payload emitted only under
+ *  {@link StreamUserRunStatesOptions.debug}. Synthetic; never on the
+ *  wire. */
+export interface RunStateStreamClose {
+    reason: string;
+}
+/** Response shape for `AgentDef set/fork/get/list` rows. Mirrors what
+ *  the server-side rowResponseMap emits. The `content_sha256` field is
+ *  the deterministic SHA-256 of the agent's content-bearing fields,
+ *  prefixed `sha256:` (Docker image-digest convention). Empty on rows
+ *  that pre-date v0.9.x and haven't been backfilled yet. */
+export interface AgentDefRowResponse {
+    def_id: string;
+    name: string;
+    version: number;
+    parent_def_id?: string;
+    description?: string;
+    created_at: string;
+    created_by_agent_id?: string;
+    retired: boolean;
+    bootstrapped_from_static: boolean;
+    /** "sha256:" + 64 hex chars; empty for not-yet-backfilled rows. */
+    content_sha256?: string;
+    /** Only populated on `set` / `fork` responses (was the new row
+     *  auto-promoted to active?). Absent on get/list. */
+    promoted?: boolean;
+}
+/** Response shape for `AgentDef verify`. Answers "is the supplied
+ *  content_sha256 the active deployed version of this name?"
+ *
+ *  - `matches: true`  — caller's local hash matches the deployed
+ *                       active version; no push needed.
+ *  - `matches: false` — bundle is out of sync; the operator should
+ *                       push a new version via `agentDef({op: "set",
+ *                       overlay: ...})`.
+ *  - `deployed: false` — no active row exists for this name (no
+ *                       deployment yet). matches is always false. */
+export interface AgentDefVerifyResult {
+    matches: boolean;
+    /** Deployed active row's hash; empty when not deployed. */
+    current_sha256: string;
+    /** Deployed active row's def_id; empty when not deployed. */
+    current_def_id: string;
+    /** Deployed active row's version; 0 when not deployed. */
+    version: number;
+    name: string;
+    /** True if an active row exists for this name. */
+    deployed: boolean;
+}
+/** Response shape for `SkillDef verify`. Same semantics as
+ *  AgentDefVerifyResult; the per-skill content basis is just
+ *  smaller (name + description + body + allowed_tools). */
+export interface SkillDefVerifyResult {
+    matches: boolean;
+    current_sha256: string;
+    current_def_id: string;
+    version: number;
+    name: string;
+    deployed: boolean;
+}
+/** Response shape for `MCPServerDef set/fork/get/list` rows. Mirrors
+ *  what the server-side rowResponseMap emits. `discovered_tools` is the
+ *  cached tools/list snapshot — refreshed via the `rediscover` op; not
+ *  part of the content_sha256 basis. */
+export interface MCPServerDefRowResponse {
+    def_id: string;
+    name: string;
+    version: number;
+    parent_def_id?: string;
+    description?: string;
+    created_at: string;
+    created_by_agent_id?: string;
+    retired: boolean;
+    bootstrapped_from_static: boolean;
+    /** "sha256:" + 64 hex chars; empty for not-yet-backfilled rows. */
+    content_sha256?: string;
+    /** Only populated on `set` / `fork` responses (auto-promoted?). */
+    promoted?: boolean;
+}
+/** Response shape for `MCPServerDef verify`. Same semantics as
+ *  AgentDefVerifyResult / SkillDefVerifyResult — answers "is the
+ *  supplied content_sha256 the deployed active version of this name?" */
+export interface MCPServerDefVerifyResult {
+    matches: boolean;
+    /** Deployed active row's hash; empty when not deployed. */
+    current_sha256: string;
+    /** Deployed active row's def_id; empty when not deployed. */
+    current_def_id: string;
+    /** Deployed active row's version; 0 when not deployed. */
+    version: number;
+    name: string;
+    /** True if an active row exists for this name. */
+    deployed: boolean;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loomcycle/client",
-  "version": "0.9.0",
-  "description": "TypeScript client for the loomcycle sidecar (HTTP+SSE). 29 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, and v0.8.22 substrate admin (agentDef + skillDef).",
+  "version": "0.9.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).",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {