@loomcycle/client 0.15.0 → 0.18.0

package/README.md

@@ -6,12 +6,15 @@ TypeScript client for the [loomcycle](https://github.com/denn-gubsky/loomcycle)
 
 ## Status
 
-**v0.11.4** — 42 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**, **v0.9.x dynamic MCP server registration (mcpServerDef)**, **v0.10.3 Library v2 enumeration (listLibraryAgents/Skills/McpServers)**, **v0.11.0 LLM Gateway (llmChat + llmStream)**, **v0.11.4 OpenAI Embeddings (embeddings)**, and health.
+**v0.18.0** — 51 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**, **v0.9.x dynamic MCP server registration (mcpServerDef)** + **v0.18.0 typed `mcpServerDefVerify` + `ensureMcpServer` (idempotent register-if-changed)**, **v0.10.3 Library v2 enumeration (listLibraryAgents/Skills/McpServers)**, **v0.11.0 LLM Gateway (llmChat + llmStream)**, **v0.11.4 OpenAI Embeddings (embeddings)**, **v0.17.0 OSS multi-tenant auth (operatorTokenDef + whoami + tenant-scoped listUsers / listUserAgents — RFC L)**, 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
 
+- **`ensureMcpServer` / `mcpServerDefVerify`** (v0.18.0) — typed ergonomics for the dynamic-MCP dedup flow. `ensureMcpServer({name, url, headers?, rediscover?})` registers a callback MCP server **idempotently**: it runs `create` (a no-op in loomcycle ≥ v0.18.0 when the active def already carries identical content) plus an optional `rediscover` (a no-op on unchanged tools), and returns `{defId, version, changed, discoveredToolCount?}` — so a consumer re-registering on every startup gets `changed: false` once its registration content is stable. Keep `${run.*}` / `${LOOMCYCLE_*}` header placeholders **literal** (don't bake a per-restart token) or the content varies each boot and dedup can't engage. `mcpServerDefVerify(name, sha)` is the typed `op: verify` wrapper (`matches: true` = no-op signal).
+- **`operatorTokenDef` / `whoami` + tenant-scoped reads** (v0.17.0, RFC L) — the OSS multi-tenant authorization surface. `operatorTokenDef` is the op-discriminated admin tool over the `OperatorTokenDef` substrate (create / rotate / retire per-principal bearer tokens); `whoami()` returns the authoritative `(tenant, subject, scopes, is_admin)` resolved from the calling bearer; `listUsers({ tenant })` / `listUserAgents(userId, { tenant })` accept a super-admin tenant-focus (ignored server-side for a tenant principal — its own tenant is forced).
+
 - **`llmChat` / `llmStream`** (v0.11.0) — direct LLM call surface that bypasses the agent loop. Provider routing + auth + retry without the ~50-200 ms per-turn overhead of a full `runStreaming` spawn. Drives n8n's `LoomCycleChatModel` AI Agent sub-node + any LangChain `BaseChatModel` consumer.
 - **`listLibraryAgents` / `listLibrarySkills` / `listLibraryMcpServers`** (v0.10.3) — typed wrappers around the v0.9.3 Library v2 endpoints. Each returns a `LibraryListResponse<T>` with source-tagged entries (`"static-only"` / `"dynamic-only"` / `"both"`) merging yaml + substrate views.
 - **`mcpServerDef`** (v0.9.x) — runtime registration of HTTP / Streamable-HTTP MCP servers without yaml edits. Same op grammar (create / fork / promote / retire / rediscover) as `agentDef` / `skillDef`.
@@ -122,6 +125,7 @@ All methods are async / return `Promise<T>` unless noted; streaming methods retu
 | `pauseRuntime(opts?: { timeoutMs? })` | `Promise<PauseResult>` | Quiesce the runtime. Raises `AlreadyPausingError` on 409, `PauseNotConfiguredError` on 503. |
 | `resumeRuntime()` | `Promise<ResumeResult>` | Release the quiesce. Raises `NotPausedError` on 409. |
 | `getRuntimeState()` | `Promise<RuntimeStateResponse>` | Current state + paused-runs count. |
+| `resolveProbe()` | `Promise<ResolverMatrix>` | Force an immediate provider re-probe; returns the refreshed availability matrix. Raises `UnavailableError` on 503 (no resolver / no probe loop). |
 
 ### Snapshot lifecycle (v0.8.17 / v0.8.18)
 

package/dist/cjs/client.js

@@ -156,7 +156,12 @@ class LoomcycleClient {
      *  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 params = new URLSearchParams();
+        if (opts?.status)
+            params.set("status", opts.status);
+        if (opts?.tenant)
+            params.set("tenant", opts.tenant);
+        const q = params.toString() ? `?${params.toString()}` : "";
         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 !== "") {
@@ -174,10 +179,20 @@ class LoomcycleClient {
     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. */
+    /** List known users with running-count summary. Drives the Web UI's
+     *  user picker. Tenant-scoped server-side since v0.17.0 (RFC L): a
+     *  tenant principal sees only its own tenant's users; an admin sees all,
+     *  or focuses one tenant via `tenant` (?tenant=). */
     async listUsers(opts) {
-        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, "/v1/_users", opts);
+        const q = opts?.tenant ? `?tenant=${encodeURIComponent(opts.tenant)}` : "";
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, `/v1/_users${q}`, opts);
+    }
+    /** Whoami — the authenticated principal (RFC L v0.17.0). Any
+     *  authenticated bearer; returns its authoritative tenant / subject /
+     *  scopes + `is_admin`. `open_mode: true` when the server runs without
+     *  the token substrate (single shared LOOMCYCLE_AUTH_TOKEN). */
+    async whoami(opts) {
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, "/v1/_me", opts);
     }
     // ---- v0.8.17/8.18 Pause / Resume / State ----
     /** Quiesce the runtime. Idempotent tools cancel immediately;
@@ -199,6 +214,14 @@ class LoomcycleClient {
     async getRuntimeState(opts) {
         return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, "/v1/_state", opts);
     }
+    /** Trigger an immediate re-probe of every configured provider and
+     *  return the refreshed availability matrix. Operator-only escape
+     *  hatch when a transient outage stalls every provider and the
+     *  runtime would otherwise 503 until the next periodic probe.
+     *  Mirrors POST /v1/_resolve/probe. */
+    async resolveProbe(opts) {
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_resolve/probe", undefined, opts);
+    }
     // ---- Snapshot lifecycle ----
     /** Capture running-state into a per-section-semver JSON envelope.
      *  Raises SnapshotTooLargeError on 413 when the envelope exceeds
@@ -419,8 +442,10 @@ class LoomcycleClient {
      *  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).
+     *  - URL hostname must be in LOOMCYCLE_HTTP_HOST_ALLOWLIST or (since
+     *    v0.17.x) LOOMCYCLE_HTTP_PRIVATE_HOST_ALLOWLIST — the latter is where
+     *    a self-hosted loopback callback like `http://localhost:3000/api/mcp`
+     *    belongs (SSRF defence at the registration boundary).
      *  - Name colliding with a static cfg.MCPServers entry is refused
      *    (yaml is ground truth; use a different name).
      *
@@ -430,6 +455,57 @@ class LoomcycleClient {
     async mcpServerDef(input, opts) {
         return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_mcpserverdef", input, opts);
     }
+    /** Typed `MCPServerDef verify` — "is `contentSha256` the active version's
+     *  hash for `name`?" `matches: true` is the no-op signal (the analog of
+     *  the agent/skill verify-before-create dedup). Thin typed wrapper over
+     *  {@link mcpServerDef}. */
+    async mcpServerDefVerify(name, contentSha256, opts) {
+        return (await this.mcpServerDef({ op: "verify", name, content_sha256: contentSha256 }, opts));
+    }
+    /** Register (or refresh) a dynamic MCP server idempotently — the typed
+     *  "register-if-changed" convenience for a consumer that re-registers its
+     *  own callback server on every startup.
+     *
+     *  Runs `create` (which is content-addressed-idempotent in loomcycle
+     *  ≥ v0.18.0 — a byte-identical re-registration is a no-op, not a new
+     *  version) and, when {@link EnsureMcpServerOptions.rediscover} is set, a
+     *  `tools/list` rediscover (also idempotent on unchanged tools). The
+     *  returned {@link EnsureMcpServerResult.changed} is false when loomcycle
+     *  deduped both — so a stable-content re-register on every boot is a clean
+     *  no-op. Keep `${run.*}` / `${LOOMCYCLE_*}` header placeholders LITERAL
+     *  (don't resolve a per-restart token) or the content varies each boot and
+     *  dedup can't engage. */
+    async ensureMcpServer(opts, callOpts) {
+        const overlay = {
+            transport: opts.transport ?? "http",
+            url: opts.url,
+        };
+        if (opts.headers)
+            overlay.headers = opts.headers;
+        const createInput = { op: "create", name: opts.name, overlay };
+        if (opts.description)
+            createInput.description = opts.description;
+        const created = (await this.mcpServerDef(createInput, callOpts));
+        let row = created;
+        let changed = created.deduplicated !== true;
+        let discoveredToolCount;
+        if (opts.rediscover) {
+            const red = (await this.mcpServerDef({ op: "rediscover", name: opts.name }, callOpts));
+            row = red;
+            if (red.deduplicated !== true)
+                changed = true;
+            discoveredToolCount = red.discovered;
+        }
+        const result = {
+            name: opts.name,
+            defId: row.def_id,
+            version: row.version,
+            changed,
+        };
+        if (discoveredToolCount !== undefined)
+            result.discoveredToolCount = discoveredToolCount;
+        return result;
+    }
     /** Invoke the v1.x RFC E ScheduleDef substrate tool over HTTP.
      *  Author + fork + retire scheduled-run definitions at runtime.
      *  Mirror of {@link LoomcycleClient.agentDef} for schedules — the
@@ -522,6 +598,13 @@ class LoomcycleClient {
     async memoryBackendDef(input, opts) {
         return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_memorybackenddef", input, opts);
     }
+    /** OperatorTokenDef substrate ops (create/rotate/retire/get/list) —
+     *  RFC L OSS multi-tenant authorization. Operator-admin only. The
+     *  token plaintext is returned ONCE in the create/rotate response.
+     *  Mirrors POST /v1/_operatortokendef. */
+    async operatorTokenDef(input, opts) {
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_operatortokendef", input, opts);
+    }
     // ---- v0.10.3 Library v2 enumeration (read-only, merged yaml+substrate) ----
     /** List every agent the runtime knows about — yaml-static + dynamic
      *  AgentDefs merged into one envelope per name. Each entry carries

package/dist/cjs/index.js

@@ -17,12 +17,14 @@
  *     listUserAgents(userId, opts?): Promise<Agent[]>
  *     getTranscript(sessionId): Promise<TranscriptResponse>
  *     health(): Promise<HealthResponse>
- *     listUsers(): Promise<ListUsersResponse>
+ *     listUsers(opts?): Promise<ListUsersResponse>   // tenant-scoped (RFC L)
+ *     whoami(): Promise<WhoamiResponse>               // RFC L principal (v0.17.0)
  *
  *     // Pause / Resume / State (v0.8.17/8.18)
  *     pauseRuntime(opts?): Promise<PauseResult>
  *     resumeRuntime(): Promise<ResumeResult>
  *     getRuntimeState(): Promise<RuntimeStateResponse>
+ *     resolveProbe(opts?): Promise<ResolverMatrix>
  *
  *     // Snapshot lifecycle (v0.8.17/8.18)
  *     createSnapshot(opts?): Promise<SnapshotCreateResponse>
@@ -47,6 +49,8 @@
  *     agentDef(input): Promise<SubstrateToolResponse>
  *     skillDef(input): Promise<SubstrateToolResponse>
  *     mcpServerDef(input): Promise<SubstrateToolResponse>
+ *     mcpServerDefVerify(name, sha): Promise<MCPServerDefVerifyResult>   // v0.18.0
+ *     ensureMcpServer(opts): Promise<EnsureMcpServerResult>              // v0.18.0 — idempotent register-if-changed
  *     scheduleDef(input): Promise<SubstrateToolResponse>
  *
  *     // Library v2 enumeration (v0.10.3 — yaml+substrate merged)

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, AckChannelOptions, ChannelAckResult, ChannelDescriptor, ChannelPeekResult, ChannelPublishResult, ChannelSubscribeResult, CreateChannelOptions, ListChannelsResponse, PeekChannelOptions, PublishChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, SubscribeChannelOptions, UpdateChannelOptions, LibraryAgentDefinition, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, ListUsersResponse, LLMChatOptions, LLMChatResponse, LLMChatStreamItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, MemoryEntriesResponse, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopesResponse, PauseResult, RegisterHookOptions, RegisterHookResponse, ResolveInterruptOptions, ResumeResult, RunOptions, RunStateStreamItem, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, StreamUserRunStatesOptions, SubstrateToolInput, SubstrateToolResponse, TranscriptResponse } from "./types.js";
+import type { Agent, AgentEvent, AgentStatus, CancelAgentResult, ClientOptions, ContinueOptions, CreateSnapshotOptions, EnsureMcpServerOptions, EnsureMcpServerResult, HealthResponse, Hook, InterruptListResponse, InterruptStatus, AckChannelOptions, ChannelAckResult, ChannelDescriptor, ChannelPeekResult, ChannelPublishResult, ChannelSubscribeResult, CreateChannelOptions, ListChannelsResponse, PeekChannelOptions, PublishChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, SubscribeChannelOptions, UpdateChannelOptions, LibraryAgentDefinition, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, ListUsersResponse, LLMChatOptions, LLMChatResponse, LLMChatStreamItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, MCPServerDefVerifyResult, MemoryEntriesResponse, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopesResponse, PauseResult, RegisterHookOptions, RegisterHookResponse, ResolveInterruptOptions, ResumeResult, ResolverMatrix, RunOptions, RunStateStreamItem, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, StreamUserRunStatesOptions, SubstrateToolInput, SubstrateToolResponse, TranscriptResponse, WhoamiResponse } from "./types.js";
 export declare class LoomcycleClient {
     private ctx;
     constructor(opts?: ClientOptions);
@@ -89,6 +89,9 @@ export declare class LoomcycleClient {
     listUserAgents(userId: string, opts?: {
         status?: AgentStatus;
         parentAgentId?: string;
+        /** Super-admin tenant-focus (?tenant=, RFC L v0.17.0). Ignored
+         *  server-side for a tenant principal — its own tenant is forced. */
+        tenant?: string;
         signal?: AbortSignal;
     }): Promise<Agent[]>;
     /** Read the full event log for a session. Each entry has seq,
@@ -101,11 +104,21 @@ export declare class LoomcycleClient {
     health(opts?: {
         signal?: AbortSignal;
     }): Promise<HealthResponse>;
-    /** Admin: list known users with running-count summary. Drives the
-     *  Web UI's user picker; operators with bearer auth can call too. */
+    /** List known users with running-count summary. Drives the Web UI's
+     *  user picker. Tenant-scoped server-side since v0.17.0 (RFC L): a
+     *  tenant principal sees only its own tenant's users; an admin sees all,
+     *  or focuses one tenant via `tenant` (?tenant=). */
     listUsers(opts?: {
+        tenant?: string;
         signal?: AbortSignal;
     }): Promise<ListUsersResponse>;
+    /** Whoami — the authenticated principal (RFC L v0.17.0). Any
+     *  authenticated bearer; returns its authoritative tenant / subject /
+     *  scopes + `is_admin`. `open_mode: true` when the server runs without
+     *  the token substrate (single shared LOOMCYCLE_AUTH_TOKEN). */
+    whoami(opts?: {
+        signal?: AbortSignal;
+    }): Promise<WhoamiResponse>;
     /** Quiesce the runtime. Idempotent tools cancel immediately;
      *  non-idempotent + external tools get a grace window then
      *  force-cancel. Raises AlreadyPausingError on 409,
@@ -123,6 +136,14 @@ export declare class LoomcycleClient {
     getRuntimeState(opts?: {
         signal?: AbortSignal;
     }): Promise<RuntimeStateResponse>;
+    /** Trigger an immediate re-probe of every configured provider and
+     *  return the refreshed availability matrix. Operator-only escape
+     *  hatch when a transient outage stalls every provider and the
+     *  runtime would otherwise 503 until the next periodic probe.
+     *  Mirrors POST /v1/_resolve/probe. */
+    resolveProbe(opts?: {
+        signal?: AbortSignal;
+    }): Promise<ResolverMatrix>;
     /** 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). */
@@ -278,8 +299,10 @@ export declare class LoomcycleClient {
      *  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).
+     *  - URL hostname must be in LOOMCYCLE_HTTP_HOST_ALLOWLIST or (since
+     *    v0.17.x) LOOMCYCLE_HTTP_PRIVATE_HOST_ALLOWLIST — the latter is where
+     *    a self-hosted loopback callback like `http://localhost:3000/api/mcp`
+     *    belongs (SSRF defence at the registration boundary).
      *  - Name colliding with a static cfg.MCPServers entry is refused
      *    (yaml is ground truth; use a different name).
      *
@@ -289,6 +312,29 @@ export declare class LoomcycleClient {
     mcpServerDef(input: SubstrateToolInput, opts?: {
         signal?: AbortSignal;
     }): Promise<SubstrateToolResponse>;
+    /** Typed `MCPServerDef verify` — "is `contentSha256` the active version's
+     *  hash for `name`?" `matches: true` is the no-op signal (the analog of
+     *  the agent/skill verify-before-create dedup). Thin typed wrapper over
+     *  {@link mcpServerDef}. */
+    mcpServerDefVerify(name: string, contentSha256: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<MCPServerDefVerifyResult>;
+    /** Register (or refresh) a dynamic MCP server idempotently — the typed
+     *  "register-if-changed" convenience for a consumer that re-registers its
+     *  own callback server on every startup.
+     *
+     *  Runs `create` (which is content-addressed-idempotent in loomcycle
+     *  ≥ v0.18.0 — a byte-identical re-registration is a no-op, not a new
+     *  version) and, when {@link EnsureMcpServerOptions.rediscover} is set, a
+     *  `tools/list` rediscover (also idempotent on unchanged tools). The
+     *  returned {@link EnsureMcpServerResult.changed} is false when loomcycle
+     *  deduped both — so a stable-content re-register on every boot is a clean
+     *  no-op. Keep `${run.*}` / `${LOOMCYCLE_*}` header placeholders LITERAL
+     *  (don't resolve a per-restart token) or the content varies each boot and
+     *  dedup can't engage. */
+    ensureMcpServer(opts: EnsureMcpServerOptions, callOpts?: {
+        signal?: AbortSignal;
+    }): Promise<EnsureMcpServerResult>;
     /** Invoke the v1.x RFC E ScheduleDef substrate tool over HTTP.
      *  Author + fork + retire scheduled-run definitions at runtime.
      *  Mirror of {@link LoomcycleClient.agentDef} for schedules — the
@@ -381,6 +427,13 @@ export declare class LoomcycleClient {
     memoryBackendDef(input: SubstrateToolInput, opts?: {
         signal?: AbortSignal;
     }): Promise<SubstrateToolResponse>;
+    /** OperatorTokenDef substrate ops (create/rotate/retire/get/list) —
+     *  RFC L OSS multi-tenant authorization. Operator-admin only. The
+     *  token plaintext is returned ONCE in the create/rotate response.
+     *  Mirrors POST /v1/_operatortokendef. */
+    operatorTokenDef(input: SubstrateToolInput, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SubstrateToolResponse>;
     /** List every agent the runtime knows about — yaml-static + dynamic
      *  AgentDefs merged into one envelope per name. Each entry carries
      *  `source: "static-only" | "dynamic-only" | "both"` so callers can

package/dist/client.js

@@ -153,7 +153,12 @@ export class LoomcycleClient {
      *  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 params = new URLSearchParams();
+        if (opts?.status)
+            params.set("status", opts.status);
+        if (opts?.tenant)
+            params.set("tenant", opts.tenant);
+        const q = params.toString() ? `?${params.toString()}` : "";
         const resp = await jsonFetch(this.ctx, `/v1/users/${encodeURIComponent(userId)}/agents${q}`, opts);
         const all = resp.agents ?? [];
         if (opts?.parentAgentId !== undefined && opts.parentAgentId !== "") {
@@ -171,10 +176,20 @@ export class LoomcycleClient {
     async health(opts) {
         return 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. */
+    /** List known users with running-count summary. Drives the Web UI's
+     *  user picker. Tenant-scoped server-side since v0.17.0 (RFC L): a
+     *  tenant principal sees only its own tenant's users; an admin sees all,
+     *  or focuses one tenant via `tenant` (?tenant=). */
     async listUsers(opts) {
-        return jsonFetch(this.ctx, "/v1/_users", opts);
+        const q = opts?.tenant ? `?tenant=${encodeURIComponent(opts.tenant)}` : "";
+        return jsonFetch(this.ctx, `/v1/_users${q}`, opts);
+    }
+    /** Whoami — the authenticated principal (RFC L v0.17.0). Any
+     *  authenticated bearer; returns its authoritative tenant / subject /
+     *  scopes + `is_admin`. `open_mode: true` when the server runs without
+     *  the token substrate (single shared LOOMCYCLE_AUTH_TOKEN). */
+    async whoami(opts) {
+        return jsonFetch(this.ctx, "/v1/_me", opts);
     }
     // ---- v0.8.17/8.18 Pause / Resume / State ----
     /** Quiesce the runtime. Idempotent tools cancel immediately;
@@ -196,6 +211,14 @@ export class LoomcycleClient {
     async getRuntimeState(opts) {
         return jsonFetch(this.ctx, "/v1/_state", opts);
     }
+    /** Trigger an immediate re-probe of every configured provider and
+     *  return the refreshed availability matrix. Operator-only escape
+     *  hatch when a transient outage stalls every provider and the
+     *  runtime would otherwise 503 until the next periodic probe.
+     *  Mirrors POST /v1/_resolve/probe. */
+    async resolveProbe(opts) {
+        return postJSON(this.ctx, "/v1/_resolve/probe", undefined, opts);
+    }
     // ---- Snapshot lifecycle ----
     /** Capture running-state into a per-section-semver JSON envelope.
      *  Raises SnapshotTooLargeError on 413 when the envelope exceeds
@@ -416,8 +439,10 @@ export class LoomcycleClient {
      *  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).
+     *  - URL hostname must be in LOOMCYCLE_HTTP_HOST_ALLOWLIST or (since
+     *    v0.17.x) LOOMCYCLE_HTTP_PRIVATE_HOST_ALLOWLIST — the latter is where
+     *    a self-hosted loopback callback like `http://localhost:3000/api/mcp`
+     *    belongs (SSRF defence at the registration boundary).
      *  - Name colliding with a static cfg.MCPServers entry is refused
      *    (yaml is ground truth; use a different name).
      *
@@ -427,6 +452,57 @@ export class LoomcycleClient {
     async mcpServerDef(input, opts) {
         return postJSON(this.ctx, "/v1/_mcpserverdef", input, opts);
     }
+    /** Typed `MCPServerDef verify` — "is `contentSha256` the active version's
+     *  hash for `name`?" `matches: true` is the no-op signal (the analog of
+     *  the agent/skill verify-before-create dedup). Thin typed wrapper over
+     *  {@link mcpServerDef}. */
+    async mcpServerDefVerify(name, contentSha256, opts) {
+        return (await this.mcpServerDef({ op: "verify", name, content_sha256: contentSha256 }, opts));
+    }
+    /** Register (or refresh) a dynamic MCP server idempotently — the typed
+     *  "register-if-changed" convenience for a consumer that re-registers its
+     *  own callback server on every startup.
+     *
+     *  Runs `create` (which is content-addressed-idempotent in loomcycle
+     *  ≥ v0.18.0 — a byte-identical re-registration is a no-op, not a new
+     *  version) and, when {@link EnsureMcpServerOptions.rediscover} is set, a
+     *  `tools/list` rediscover (also idempotent on unchanged tools). The
+     *  returned {@link EnsureMcpServerResult.changed} is false when loomcycle
+     *  deduped both — so a stable-content re-register on every boot is a clean
+     *  no-op. Keep `${run.*}` / `${LOOMCYCLE_*}` header placeholders LITERAL
+     *  (don't resolve a per-restart token) or the content varies each boot and
+     *  dedup can't engage. */
+    async ensureMcpServer(opts, callOpts) {
+        const overlay = {
+            transport: opts.transport ?? "http",
+            url: opts.url,
+        };
+        if (opts.headers)
+            overlay.headers = opts.headers;
+        const createInput = { op: "create", name: opts.name, overlay };
+        if (opts.description)
+            createInput.description = opts.description;
+        const created = (await this.mcpServerDef(createInput, callOpts));
+        let row = created;
+        let changed = created.deduplicated !== true;
+        let discoveredToolCount;
+        if (opts.rediscover) {
+            const red = (await this.mcpServerDef({ op: "rediscover", name: opts.name }, callOpts));
+            row = red;
+            if (red.deduplicated !== true)
+                changed = true;
+            discoveredToolCount = red.discovered;
+        }
+        const result = {
+            name: opts.name,
+            defId: row.def_id,
+            version: row.version,
+            changed,
+        };
+        if (discoveredToolCount !== undefined)
+            result.discoveredToolCount = discoveredToolCount;
+        return result;
+    }
     /** Invoke the v1.x RFC E ScheduleDef substrate tool over HTTP.
      *  Author + fork + retire scheduled-run definitions at runtime.
      *  Mirror of {@link LoomcycleClient.agentDef} for schedules — the
@@ -519,6 +595,13 @@ export class LoomcycleClient {
     async memoryBackendDef(input, opts) {
         return postJSON(this.ctx, "/v1/_memorybackenddef", input, opts);
     }
+    /** OperatorTokenDef substrate ops (create/rotate/retire/get/list) —
+     *  RFC L OSS multi-tenant authorization. Operator-admin only. The
+     *  token plaintext is returned ONCE in the create/rotate response.
+     *  Mirrors POST /v1/_operatortokendef. */
+    async operatorTokenDef(input, opts) {
+        return postJSON(this.ctx, "/v1/_operatortokendef", input, opts);
+    }
     // ---- v0.10.3 Library v2 enumeration (read-only, merged yaml+substrate) ----
     /** List every agent the runtime knows about — yaml-static + dynamic
      *  AgentDefs merged into one envelope per name. Each entry carries

package/dist/index.d.ts

@@ -16,12 +16,14 @@
  *     listUserAgents(userId, opts?): Promise<Agent[]>
  *     getTranscript(sessionId): Promise<TranscriptResponse>
  *     health(): Promise<HealthResponse>
- *     listUsers(): Promise<ListUsersResponse>
+ *     listUsers(opts?): Promise<ListUsersResponse>   // tenant-scoped (RFC L)
+ *     whoami(): Promise<WhoamiResponse>               // RFC L principal (v0.17.0)
  *
  *     // Pause / Resume / State (v0.8.17/8.18)
  *     pauseRuntime(opts?): Promise<PauseResult>
  *     resumeRuntime(): Promise<ResumeResult>
  *     getRuntimeState(): Promise<RuntimeStateResponse>
+ *     resolveProbe(opts?): Promise<ResolverMatrix>
  *
  *     // Snapshot lifecycle (v0.8.17/8.18)
  *     createSnapshot(opts?): Promise<SnapshotCreateResponse>
@@ -46,6 +48,8 @@
  *     agentDef(input): Promise<SubstrateToolResponse>
  *     skillDef(input): Promise<SubstrateToolResponse>
  *     mcpServerDef(input): Promise<SubstrateToolResponse>
+ *     mcpServerDefVerify(name, sha): Promise<MCPServerDefVerifyResult>   // v0.18.0
+ *     ensureMcpServer(opts): Promise<EnsureMcpServerResult>              // v0.18.0 — idempotent register-if-changed
  *     scheduleDef(input): Promise<SubstrateToolResponse>
  *
  *     // Library v2 enumeration (v0.10.3 — yaml+substrate merged)
@@ -78,5 +82,5 @@
  * See `adapters/ts/README.md` for usage examples.
  */
 export { LoomcycleClient } from "./client.js";
-export type { AgentEvent, ClientOptions, ContinueOptions, EventType, HostWidening, ParentContext, 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, CreateChannelOptions, UpdateChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, AgentDefRowResponse, AgentDefVerifyResult, SkillDefVerifyResult, MCPServerDefRowResponse, MCPServerDefVerifyResult, LibraryAgentDefinition, LibraryEntry, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, LLMChatContent, LLMChatMessage, LLMChatOptions, LLMChatResponse, LLMChatStreamDelta, LLMChatStreamItem, LLMChatToolCall, LLMChatUsage, LLMTool, LLMEmbeddingItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, LLMEmbeddingsUsage, } from "./types.js";
+export type { AgentEvent, ClientOptions, ContinueOptions, EventType, HostWidening, ParentContext, PromptContent, PromptSegment, RetryInfo, RunOptions, ToolUse, Usage, Agent, AgentStatus, AgentUsage, CancelAgentResult, ListAgentsResponse, TranscriptEvent, TranscriptResponse, HealthResponse, ListUsersResponse, UserSummary, WhoamiResponse, PauseResult, ResumeResult, RuntimeStateResponse, RuntimeStateStatus, ResolverMatrix, ResolverModelStatus, ResolverProviderAvailability, 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, CreateChannelOptions, UpdateChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, AgentDefRowResponse, AgentDefVerifyResult, SkillDefVerifyResult, EnsureMcpServerOptions, EnsureMcpServerResult, MCPServerDefRowResponse, MCPServerDefVerifyResult, LibraryAgentDefinition, LibraryEntry, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, LLMChatContent, LLMChatMessage, LLMChatOptions, LLMChatResponse, LLMChatStreamDelta, LLMChatStreamItem, LLMChatToolCall, LLMChatUsage, LLMTool, LLMEmbeddingItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, LLMEmbeddingsUsage, } from "./types.js";
 export { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, HookNotFoundError, NotFoundError, InvalidArgumentError, ChannelCursorRegressionError, LoomcycleError, NotPausedError, PauseNotConfiguredError, PerUserQuotaExhaustedError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, UnavailableError, } from "./errors.js";

package/dist/index.js

@@ -16,12 +16,14 @@
  *     listUserAgents(userId, opts?): Promise<Agent[]>
  *     getTranscript(sessionId): Promise<TranscriptResponse>
  *     health(): Promise<HealthResponse>
- *     listUsers(): Promise<ListUsersResponse>
+ *     listUsers(opts?): Promise<ListUsersResponse>   // tenant-scoped (RFC L)
+ *     whoami(): Promise<WhoamiResponse>               // RFC L principal (v0.17.0)
  *
  *     // Pause / Resume / State (v0.8.17/8.18)
  *     pauseRuntime(opts?): Promise<PauseResult>
  *     resumeRuntime(): Promise<ResumeResult>
  *     getRuntimeState(): Promise<RuntimeStateResponse>
+ *     resolveProbe(opts?): Promise<ResolverMatrix>
  *
  *     // Snapshot lifecycle (v0.8.17/8.18)
  *     createSnapshot(opts?): Promise<SnapshotCreateResponse>
@@ -46,6 +48,8 @@
  *     agentDef(input): Promise<SubstrateToolResponse>
  *     skillDef(input): Promise<SubstrateToolResponse>
  *     mcpServerDef(input): Promise<SubstrateToolResponse>
+ *     mcpServerDefVerify(name, sha): Promise<MCPServerDefVerifyResult>   // v0.18.0
+ *     ensureMcpServer(opts): Promise<EnsureMcpServerResult>              // v0.18.0 — idempotent register-if-changed
  *     scheduleDef(input): Promise<SubstrateToolResponse>
  *
  *     // Library v2 enumeration (v0.10.3 — yaml+substrate merged)

package/dist/types.d.ts

@@ -336,6 +336,18 @@ export interface UserSummary {
 export interface ListUsersResponse {
     users: UserSummary[];
 }
+/** GET /v1/_me — the authenticated principal resolved from the bearer.
+ *  `open_mode` is true when the server runs without the OperatorTokenDef
+ *  substrate (single shared LOOMCYCLE_AUTH_TOKEN); `legacy` is true for a
+ *  shared-token principal when the substrate IS enabled. */
+export interface WhoamiResponse {
+    tenant_id: string;
+    subject: string;
+    scopes: string[];
+    is_admin: boolean;
+    legacy: boolean;
+    open_mode?: boolean;
+}
 export type RuntimeStateStatus = "running" | "pausing" | "paused";
 export interface PauseResult {
     state: string;
@@ -353,6 +365,25 @@ export interface RuntimeStateResponse {
     state: RuntimeStateStatus;
     paused_runs_count: number;
 }
+export interface ResolverModelStatus {
+    listed: boolean;
+    stalled: boolean;
+}
+export interface ResolverProviderAvailability {
+    excluded: boolean;
+    reachable: boolean;
+    models: Record<string, ResolverModelStatus>;
+    /** RFC3339 timestamp of the last probe for this provider. */
+    last_check: string;
+    last_error?: string;
+}
+/** The resolver availability matrix, captured right after a forced
+ *  re-probe. Same shape as GET /v1/_resolver. */
+export interface ResolverMatrix {
+    /** RFC3339 timestamp when this matrix snapshot was assembled. */
+    generated_at: string;
+    providers: Record<string, ResolverProviderAvailability>;
+}
 export interface SnapshotDescriptor {
     id: string;
     created_at: string;
@@ -576,7 +607,7 @@ export interface PostHookCall {
  *  the adapter doesn't re-validate. Use the optional `extra` index
  *  signature for forward-compat fields. */
 export type SubstrateToolInput = {
-    op: "create" | "fork" | "get" | "list" | "promote" | "retire";
+    op: "create" | "fork" | "get" | "list" | "promote" | "retire" | "rediscover" | "verify";
     name?: string;
     def_id?: string;
     parent_def_id?: string;
@@ -907,6 +938,43 @@ export interface MCPServerDefRowResponse {
     content_sha256?: string;
     /** Only populated on `set` / `fork` responses (auto-promoted?). */
     promoted?: boolean;
+    /** True when create/rediscover was a content-addressed no-op
+     *  (loomcycle ≥ v0.18.0): the active def already carried identical
+     *  content (create) or identical discovered_tools (rediscover), so no
+     *  new version was minted. Absent (undefined) on a real mint. */
+    deduplicated?: boolean;
+    /** Only on `rediscover` responses — the number of tools discovered. */
+    discovered?: number;
+}
+/** Options for {@link LoomcycleClient.ensureMcpServer}. */
+export interface EnsureMcpServerOptions {
+    /** Substrate name (not a static cfg.MCPServers name). */
+    name: string;
+    /** Absolute MCP endpoint, e.g. `http://localhost:3000/api/mcp`. */
+    url: string;
+    /** Default `"http"`. */
+    transport?: "http" | "streamable-http";
+    /** Per-request headers, stored verbatim. Keep `${run.*}` / `${LOOMCYCLE_*}`
+     *  substitution placeholders LITERAL (don't resolve a token yourself) so
+     *  the registration content is stable across restarts — that's what lets
+     *  loomcycle's idempotent create dedup the re-registration. */
+    headers?: Record<string, string>;
+    description?: string;
+    /** Run a `tools/list` rediscover after registering. Default false. */
+    rediscover?: boolean;
+}
+/** Result of {@link LoomcycleClient.ensureMcpServer}. */
+export interface EnsureMcpServerResult {
+    name: string;
+    defId: string;
+    version: number;
+    /** True when this call minted a new version (create and/or rediscover);
+     *  false when loomcycle deduped it (active def already current). A
+     *  consumer re-registering on every boot expects `changed: false` once
+     *  the registration content is stable. */
+    changed: boolean;
+    /** Populated when `rediscover` ran: the number of tools discovered. */
+    discoveredToolCount?: number;
 }
 /** Response shape for `MCPServerDef verify`. Same semantics as
  *  AgentDefVerifyResult / SkillDefVerifyResult — answers "is the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loomcycle/client",
-  "version": "0.15.0",
-  "description": "TypeScript client for the loomcycle sidecar (HTTP+SSE). 46 methods covering run streaming, agent metadata, pause/resume/state, snapshot lifecycle, memory admin (incl. v0.9.0 Vector Memory embed_stats + reembed AND v0.11.5 setMemoryEntry + deleteMemoryEntry), interruption resolve, hook management, v0.8.22 substrate admin (agentDef + skillDef), v0.9.x n8n Phase 0 (listChannels + streamUserRunStates), v0.9.x Channel CRUD (publishChannel + subscribeChannel + peekChannel + ackChannel), v0.11.5 Channel admin CRUD (createChannel + updateChannel + deleteChannel — runtime substrate; yaml channels refuse mutation with HTTP 409), v0.9.x content_sha256 verify, v0.9.1 transcript first-cycle, v0.9.x dynamic MCP server registration (mcpServerDef + MCPServerDefVerifyResult), v0.10.3 Library v2 enumeration (listLibraryAgents + listLibrarySkills + listLibraryMcpServers), and v0.11.0 LLM Gateway (llmChat + llmStream — direct provider routing without agent overhead; primary target is n8n's LoomCycleChatModel AI Agent sub-node and any LangChain-compatible consumer). v0.10.1 — dual ESM + CommonJS distribution (additive — ESM consumers unchanged; CJS consumers like n8n's community-node loader now work).",
+  "version": "0.18.0",
+  "description": "TypeScript client for the loomcycle sidecar (HTTP+SSE). 51 methods covering run streaming, agent metadata, pause/resume/state, resolver re-probe (resolveProbe — issue #88 operator escape hatch), operator-token admin (operatorTokenDef — RFC L OSS multi-tenant auth) + whoami (RFC L authoritative principal, v0.17.0) + tenant-scoped listUsers / listUserAgents, dynamic MCP registration (mcpServerDef + v0.18.0 typed mcpServerDefVerify + ensureMcpServer idempotent register-if-changed), snapshot lifecycle, memory admin (incl. v0.9.0 Vector Memory embed_stats + reembed AND v0.11.5 setMemoryEntry + deleteMemoryEntry), interruption resolve, hook management, v0.8.22 substrate admin (agentDef + skillDef), v0.9.x n8n Phase 0 (listChannels + streamUserRunStates), v0.9.x Channel CRUD (publishChannel + subscribeChannel + peekChannel + ackChannel), v0.11.5 Channel admin CRUD (createChannel + updateChannel + deleteChannel — runtime substrate; yaml channels refuse mutation with HTTP 409), v0.9.x content_sha256 verify, v0.9.1 transcript first-cycle, v0.9.x dynamic MCP server registration (mcpServerDef + MCPServerDefVerifyResult), v0.10.3 Library v2 enumeration (listLibraryAgents + listLibrarySkills + listLibraryMcpServers), and v0.11.0 LLM Gateway (llmChat + llmStream — direct provider routing without agent overhead; primary target is n8n's LoomCycleChatModel AI Agent sub-node and any LangChain-compatible consumer). v0.10.1 — dual ESM + CommonJS distribution (additive — ESM consumers unchanged; CJS consumers like n8n's community-node loader now work).",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {