@loomcycle/client 0.17.0 → 0.20.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

@@ -418,6 +418,41 @@ class LoomcycleClient {
     async agentDef(input, opts) {
         return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_agentdef", input, opts);
     }
+    /** Register (or refresh) a code-js agent idempotently from an INLINE JS body
+     *  — the typed "ship a code agent with no host filesystem" convenience
+     *  (RFC J), mirror of {@link LoomcycleClient.ensureMcpServer}.
+     *
+     *  Runs `agentDef({op:"create", overlay:{provider:"code-js", code_body, …}})`,
+     *  which is content-addressed-idempotent in loomcycle: a byte-identical
+     *  re-registration is a no-op (`changed:false`), not a new version. This is
+     *  what makes code agents work across container boundaries / pure-cloud —
+     *  the JS no longer has to exist at `agent_code/<name>/index.js` on the
+     *  sidecar's disk.
+     *
+     *  Requires `LOOMCYCLE_CODE_AGENTS_ENABLED=1` on the sidecar — the same
+     *  switch that registers the code-js provider. Without it the create is
+     *  refused (raises {@link SubstrateToolRefusedError}). Keep `${run.*}` /
+     *  `${LOOMCYCLE_*}` placeholders in the body LITERAL so the content stays
+     *  stable and dedup engages on re-register. */
+    async ensureCodeAgent(opts, callOpts) {
+        const overlay = { provider: "code-js", code_body: opts.code };
+        if (opts.allowedTools)
+            overlay.allowed_tools = opts.allowedTools;
+        if (opts.tier)
+            overlay.tier = opts.tier;
+        if (opts.model)
+            overlay.model = opts.model;
+        const input = { op: "create", name: opts.name, overlay };
+        if (opts.description)
+            input.description = opts.description;
+        const row = (await this.agentDef(input, callOpts));
+        return {
+            name: opts.name,
+            defId: row.def_id,
+            version: row.version,
+            changed: row.deduplicated !== true,
+        };
+    }
     /** Invoke the SkillDef substrate tool over HTTP. Mirror of
      *  {@link LoomcycleClient.agentDef} for skills (v0.8.22+). Same
      *  input grammar, same error class on refusal. See the
@@ -442,8 +477,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 +490,65 @@ 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 (a byte-identical
+     *  re-registration is a no-op, not a new version) AND auto-discovers the
+     *  upstream's tools at ingestion — so {@link EnsureMcpServerResult.changed}
+     *  is false on a stable-content re-register, and
+     *  {@link EnsureMcpServerResult.discoveredToolCount} is populated straight
+     *  from the `create` (no separate rediscover needed for the count). On a
+     *  deduplicated re-register the count is absent (the tool surface was
+     *  unchanged), so it reflects only the freshly-discovered case.
+     *
+     *  Pass {@link EnsureMcpServerOptions.rediscover} only to FORCE a refresh
+     *  when the upstream's tools changed but the registration content didn't.
+     *
+     *  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;
+        // create auto-discovers at ingestion → the count is on the create response.
+        let discoveredToolCount = created.discovered;
+        if (opts.rediscover) {
+            const red = (await this.mcpServerDef({ op: "rediscover", name: opts.name }, callOpts));
+            row = red;
+            if (red.deduplicated !== true)
+                changed = true;
+            if (red.discovered !== undefined)
+                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, EnsureCodeAgentOptions, EnsureCodeAgentResult, 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);
@@ -275,6 +275,25 @@ export declare class LoomcycleClient {
     agentDef(input: SubstrateToolInput, opts?: {
         signal?: AbortSignal;
     }): Promise<SubstrateToolResponse>;
+    /** Register (or refresh) a code-js agent idempotently from an INLINE JS body
+     *  — the typed "ship a code agent with no host filesystem" convenience
+     *  (RFC J), mirror of {@link LoomcycleClient.ensureMcpServer}.
+     *
+     *  Runs `agentDef({op:"create", overlay:{provider:"code-js", code_body, …}})`,
+     *  which is content-addressed-idempotent in loomcycle: a byte-identical
+     *  re-registration is a no-op (`changed:false`), not a new version. This is
+     *  what makes code agents work across container boundaries / pure-cloud —
+     *  the JS no longer has to exist at `agent_code/<name>/index.js` on the
+     *  sidecar's disk.
+     *
+     *  Requires `LOOMCYCLE_CODE_AGENTS_ENABLED=1` on the sidecar — the same
+     *  switch that registers the code-js provider. Without it the create is
+     *  refused (raises {@link SubstrateToolRefusedError}). Keep `${run.*}` /
+     *  `${LOOMCYCLE_*}` placeholders in the body LITERAL so the content stays
+     *  stable and dedup engages on re-register. */
+    ensureCodeAgent(opts: EnsureCodeAgentOptions, callOpts?: {
+        signal?: AbortSignal;
+    }): Promise<EnsureCodeAgentResult>;
     /** Invoke the SkillDef substrate tool over HTTP. Mirror of
      *  {@link LoomcycleClient.agentDef} for skills (v0.8.22+). Same
      *  input grammar, same error class on refusal. See the
@@ -299,8 +318,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 +331,35 @@ 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 (a byte-identical
+     *  re-registration is a no-op, not a new version) AND auto-discovers the
+     *  upstream's tools at ingestion — so {@link EnsureMcpServerResult.changed}
+     *  is false on a stable-content re-register, and
+     *  {@link EnsureMcpServerResult.discoveredToolCount} is populated straight
+     *  from the `create` (no separate rediscover needed for the count). On a
+     *  deduplicated re-register the count is absent (the tool surface was
+     *  unchanged), so it reflects only the freshly-discovered case.
+     *
+     *  Pass {@link EnsureMcpServerOptions.rediscover} only to FORCE a refresh
+     *  when the upstream's tools changed but the registration content didn't.
+     *
+     *  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

@@ -415,6 +415,41 @@ export class LoomcycleClient {
     async agentDef(input, opts) {
         return postJSON(this.ctx, "/v1/_agentdef", input, opts);
     }
+    /** Register (or refresh) a code-js agent idempotently from an INLINE JS body
+     *  — the typed "ship a code agent with no host filesystem" convenience
+     *  (RFC J), mirror of {@link LoomcycleClient.ensureMcpServer}.
+     *
+     *  Runs `agentDef({op:"create", overlay:{provider:"code-js", code_body, …}})`,
+     *  which is content-addressed-idempotent in loomcycle: a byte-identical
+     *  re-registration is a no-op (`changed:false`), not a new version. This is
+     *  what makes code agents work across container boundaries / pure-cloud —
+     *  the JS no longer has to exist at `agent_code/<name>/index.js` on the
+     *  sidecar's disk.
+     *
+     *  Requires `LOOMCYCLE_CODE_AGENTS_ENABLED=1` on the sidecar — the same
+     *  switch that registers the code-js provider. Without it the create is
+     *  refused (raises {@link SubstrateToolRefusedError}). Keep `${run.*}` /
+     *  `${LOOMCYCLE_*}` placeholders in the body LITERAL so the content stays
+     *  stable and dedup engages on re-register. */
+    async ensureCodeAgent(opts, callOpts) {
+        const overlay = { provider: "code-js", code_body: opts.code };
+        if (opts.allowedTools)
+            overlay.allowed_tools = opts.allowedTools;
+        if (opts.tier)
+            overlay.tier = opts.tier;
+        if (opts.model)
+            overlay.model = opts.model;
+        const input = { op: "create", name: opts.name, overlay };
+        if (opts.description)
+            input.description = opts.description;
+        const row = (await this.agentDef(input, callOpts));
+        return {
+            name: opts.name,
+            defId: row.def_id,
+            version: row.version,
+            changed: row.deduplicated !== true,
+        };
+    }
     /** Invoke the SkillDef substrate tool over HTTP. Mirror of
      *  {@link LoomcycleClient.agentDef} for skills (v0.8.22+). Same
      *  input grammar, same error class on refusal. See the
@@ -439,8 +474,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 +487,65 @@ 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 (a byte-identical
+     *  re-registration is a no-op, not a new version) AND auto-discovers the
+     *  upstream's tools at ingestion — so {@link EnsureMcpServerResult.changed}
+     *  is false on a stable-content re-register, and
+     *  {@link EnsureMcpServerResult.discoveredToolCount} is populated straight
+     *  from the `create` (no separate rediscover needed for the count). On a
+     *  deduplicated re-register the count is absent (the tool surface was
+     *  unchanged), so it reflects only the freshly-discovered case.
+     *
+     *  Pass {@link EnsureMcpServerOptions.rediscover} only to FORCE a refresh
+     *  when the upstream's tools changed but the registration content didn't.
+     *
+     *  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;
+        // create auto-discovers at ingestion → the count is on the create response.
+        let discoveredToolCount = created.discovered;
+        if (opts.rediscover) {
+            const red = (await this.mcpServerDef({ op: "rediscover", name: opts.name }, callOpts));
+            row = red;
+            if (red.deduplicated !== true)
+                changed = true;
+            if (red.discovered !== undefined)
+                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, AgentDefOverlay, EnsureCodeAgentOptions, EnsureCodeAgentResult, 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;
@@ -886,6 +886,10 @@ export interface AgentDefRowResponse {
     /** Only populated on `set` / `fork` responses (was the new row
      *  auto-promoted to active?). Absent on get/list. */
     promoted?: boolean;
+    /** True when create was a content-addressed no-op: the active def already
+     *  carried identical content, so no new version was minted. Absent on a
+     *  real mint. Drives {@link LoomcycleClient.ensureCodeAgent}'s `changed`. */
+    deduplicated?: boolean;
 }
 /** Response shape for `AgentDef verify`. Answers "is the supplied
  *  content_sha256 the active deployed version of this name?"
@@ -938,6 +942,113 @@ 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;
+    /** Number of tools discovered via the upstream's `tools/list`. Present on
+     *  `rediscover` responses and — since loomcycle auto-discovers at ingestion
+     *  — on a fresh `create`/`fork` that ran the handshake. Absent on a
+     *  deduplicated create (the active tool surface was unchanged) and when
+     *  `discover:false` was passed. */
+    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;
+    /** Force a `tools/list` refresh after registering. Default false.
+     *
+     *  You usually do NOT need this: registration auto-discovers the upstream's
+     *  tools at ingestion, so {@link EnsureMcpServerResult.discoveredToolCount}
+     *  is already populated from the `create`. Set this only to force a re-read
+     *  when the upstream's tool surface changed but the registration content
+     *  (url/headers) did not — a plain re-register would dedup and keep the
+     *  cached tools, whereas a rediscover re-runs the handshake. */
+    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;
+}
+/** Typed `overlay` for an {@link LoomcycleClient.agentDef} create/fork —
+ *  the mutable subset of an agent definition. All fields optional (a fork
+ *  overlays only what changes). The `[extra]` tail keeps it forward-compatible
+ *  with fields the in-process tool may accept that the adapter doesn't model
+ *  yet — the tool owns the authoritative schema; the adapter doesn't re-validate.
+ *
+ *  `code_body` is the inline code-js orchestrator source (RFC J): set it (with
+ *  `provider: "code-js"`) to ingest a code agent through the substrate with NO
+ *  host filesystem bind — the symmetry that makes code agents work in
+ *  containers / pure-cloud. Requires `LOOMCYCLE_CODE_AGENTS_ENABLED=1` on the
+ *  sidecar; create/fork refuses a non-empty `code_body` otherwise. */
+export interface AgentDefOverlay {
+    provider?: string;
+    model?: string;
+    /** Inline code-js source. Empty/absent ⇒ the provider falls back to
+     *  `agent_code/<name>/index.js`. Stored verbatim (whitespace is hash-
+     *  significant); participates in content_sha256. */
+    code_body?: string;
+    tier?: string;
+    effort?: string;
+    max_tokens?: number;
+    max_iterations?: number;
+    max_concurrent_children?: number;
+    system_prompt?: string;
+    allowed_tools?: string[];
+    skills?: string[];
+    memory_scopes?: string[];
+    memory_quota_bytes?: number;
+    memory_backend?: string;
+    retry_attempts?: number;
+    [extra: string]: unknown;
+}
+/** Options for {@link LoomcycleClient.ensureCodeAgent}. */
+export interface EnsureCodeAgentOptions {
+    /** Agent name (substrate; must not collide with a static cfg.Agents name —
+     *  use a fork for those). */
+    name: string;
+    /** The inline code-js orchestrator source (the `function run(input){…}` body).
+     *  Keep any `${run.*}` / `${LOOMCYCLE_*}` placeholders LITERAL so the content
+     *  is stable across restarts — that's what lets loomcycle dedup the
+     *  re-registration. */
+    code: string;
+    /** The agent's allowed_tools ceiling (must be a subset of the caller's). */
+    allowedTools?: string[];
+    /** Per-user tier policy name (mutually exclusive with `model` in practice). */
+    tier?: string;
+    /** Pin a concrete model id (overrides tier resolution). */
+    model?: string;
+    description?: string;
+}
+/** Result of {@link LoomcycleClient.ensureCodeAgent}. */
+export interface EnsureCodeAgentResult {
+    name: string;
+    defId: string;
+    version: number;
+    /** True when this call minted a new version; false when loomcycle deduped
+     *  it (identical body + config already active). */
+    changed: boolean;
 }
 /** 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.20.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). v0.19.0 — typed inline code-js agent ingestion (AgentDefOverlay.code_body + ensureCodeAgent — register a deterministic code agent through the substrate with no host filesystem bind; RFC J). v0.20.0 — ensureMcpServer surfaces discoveredToolCount straight from create (loomcycle now auto-discovers MCP tools at ingestion); rediscover is now an explicit force-refresh.",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {