@loomcycle/client 0.17.0 → 0.18.0

package/README.md

@@ -6,12 +6,13 @@ TypeScript client for the [loomcycle](https://github.com/denn-gubsky/loomcycle)
 
 ## Status
 
-**v0.17.0** — 49 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)**, **v0.17.0 OSS multi-tenant auth (operatorTokenDef + whoami + tenant-scoped listUsers / listUserAgents — RFC L)**, 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.

package/dist/cjs/client.js

@@ -442,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).
      *
@@ -453,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

package/dist/cjs/index.js

@@ -49,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, ResolverMatrix, RunOptions, RunStateStreamItem, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, StreamUserRunStatesOptions, SubstrateToolInput, SubstrateToolResponse, TranscriptResponse, WhoamiResponse } 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);
@@ -299,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).
      *
@@ -310,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

package/dist/client.js

@@ -439,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).
      *
@@ -450,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

package/dist/index.d.ts

@@ -48,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)
@@ -80,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, 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, 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

@@ -48,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

@@ -607,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;
@@ -938,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.17.0",
-  "description": "TypeScript client for the loomcycle sidecar (HTTP+SSE). 49 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, 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": {