@loomcycle/client 0.18.0 → 0.21.0

package/dist/cjs/client.js

@@ -93,6 +93,10 @@ class LoomcycleClient {
             body.user_credentials = opts.userCredentials;
         if (opts.parentContext !== undefined)
             body.parent_context = opts.parentContext;
+        if (opts.metadata !== undefined)
+            body.metadata = opts.metadata;
+        if (opts.runTimeoutSeconds !== undefined)
+            body.run_timeout_seconds = opts.runTimeoutSeconds;
         yield* this.streamSSE("/v1/runs", body, opts.signal, opts.debug);
     }
     /**
@@ -133,6 +137,10 @@ class LoomcycleClient {
             body.user_credentials = opts.userCredentials;
         if (opts.parentContext !== undefined)
             body.parent_context = opts.parentContext;
+        if (opts.metadata !== undefined)
+            body.metadata = opts.metadata;
+        if (opts.runTimeoutSeconds !== undefined)
+            body.run_timeout_seconds = opts.runTimeoutSeconds;
         yield* this.streamSSE(`/v1/sessions/${encodeURIComponent(opts.sessionId)}/messages`, body, opts.signal, opts.debug);
     }
     // ---- Agent metadata ----
@@ -418,6 +426,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
@@ -466,15 +509,21 @@ class LoomcycleClient {
      *  "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. */
+     *  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",
@@ -488,13 +537,15 @@ class LoomcycleClient {
         const created = (await this.mcpServerDef(createInput, callOpts));
         let row = created;
         let changed = created.deduplicated !== true;
-        let discoveredToolCount;
+        // 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;
-            discoveredToolCount = red.discovered;
+            if (red.discovered !== undefined)
+                discoveredToolCount = red.discovered;
         }
         const result = {
             name: opts.name,

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, 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";
+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
@@ -323,15 +342,21 @@ export declare class LoomcycleClient {
      *  "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. */
+     *  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>;

package/dist/client.js

@@ -90,6 +90,10 @@ export class LoomcycleClient {
             body.user_credentials = opts.userCredentials;
         if (opts.parentContext !== undefined)
             body.parent_context = opts.parentContext;
+        if (opts.metadata !== undefined)
+            body.metadata = opts.metadata;
+        if (opts.runTimeoutSeconds !== undefined)
+            body.run_timeout_seconds = opts.runTimeoutSeconds;
         yield* this.streamSSE("/v1/runs", body, opts.signal, opts.debug);
     }
     /**
@@ -130,6 +134,10 @@ export class LoomcycleClient {
             body.user_credentials = opts.userCredentials;
         if (opts.parentContext !== undefined)
             body.parent_context = opts.parentContext;
+        if (opts.metadata !== undefined)
+            body.metadata = opts.metadata;
+        if (opts.runTimeoutSeconds !== undefined)
+            body.run_timeout_seconds = opts.runTimeoutSeconds;
         yield* this.streamSSE(`/v1/sessions/${encodeURIComponent(opts.sessionId)}/messages`, body, opts.signal, opts.debug);
     }
     // ---- Agent metadata ----
@@ -415,6 +423,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
@@ -463,15 +506,21 @@ export class LoomcycleClient {
      *  "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. */
+     *  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",
@@ -485,13 +534,15 @@ export class LoomcycleClient {
         const created = (await this.mcpServerDef(createInput, callOpts));
         let row = created;
         let changed = created.deduplicated !== true;
-        let discoveredToolCount;
+        // 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;
-            discoveredToolCount = red.discovered;
+            if (red.discovered !== undefined)
+                discoveredToolCount = red.discovered;
         }
         const result = {
             name: opts.name,

package/dist/index.d.ts

@@ -82,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, 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 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/types.d.ts

@@ -148,6 +148,21 @@ export interface RunOptions {
      *  user-initiated request that spawned the whole tree. Not a secret.
      *  Omitted = no tracking context. */
     parentContext?: ParentContext;
+    /** Optional NON-SECRET structured metadata passed to the agent (repo
+     *  name, review policy, preferred skills, …) — symmetric with the
+     *  WebHook/Schedule trigger paths. As a first-party (bearer-authed)
+     *  caller this is TRUSTED: a code-js agent reads it as `input.metadata`;
+     *  an LLM agent receives it as a trusted prompt block. NOT for secrets —
+     *  use {@link RunOptions.userCredentials} for tokens. Per-call, not session
+     *  state: a continuation does not inherit it — re-send on continue(). */
+    metadata?: Record<string, unknown>;
+    /** Optional ad-hoc per-run wall-clock budget (seconds) for a CODE-JS agent,
+     *  overriding the agent's `run_timeout_seconds` and the sidecar's global
+     *  default (precedence: per-run > per-agent > global). Use it for a fan-out
+     *  orchestrator that blocks in Agent.parallel_spawn awaiting LLM children —
+     *  its budget spans that wait, so the CPU-oriented default is often too low.
+     *  Ignored by LLM agents. 0 / omitted = inherit. */
+    runTimeoutSeconds?: number;
     /** Opt-in observability: when true, the iterator emits client-
      *  synthesized `{ type: "_meta", meta_subtype: "stream_open" | "stream_close" }`
      *  events around the real event stream. `meta_reason` carries the
@@ -206,6 +221,14 @@ export interface ContinueOptions {
      *  {@link RunOptions.parentContext} — same shape; a continuation may
      *  (re)set the lineage for the new run it creates. */
     parentContext?: ParentContext;
+    /** Optional NON-SECRET structured metadata for the new run — see
+     *  {@link RunOptions.metadata}. Same shape + trust posture. NOT inherited
+     *  from the original run (metadata is a per-call input, not session state):
+     *  re-send it on the continuation to carry it forward. */
+    metadata?: Record<string, unknown>;
+    /** Optional ad-hoc per-run code-js wall-clock budget (seconds) for the
+     *  continuation's new run — see {@link RunOptions.runTimeoutSeconds}. */
+    runTimeoutSeconds?: number;
     /** Opt-in observability: see {@link RunOptions.debug}. Same shape. */
     debug?: boolean;
     signal?: AbortSignal;
@@ -886,6 +909,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?"
@@ -943,7 +970,11 @@ export interface MCPServerDefRowResponse {
      *  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. */
+    /** 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}. */
@@ -960,7 +991,14 @@ export interface EnsureMcpServerOptions {
      *  loomcycle's idempotent create dedup the re-registration. */
     headers?: Record<string, string>;
     description?: string;
-    /** Run a `tools/list` rediscover after registering. Default false. */
+    /** 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}. */
@@ -976,6 +1014,65 @@ export interface EnsureMcpServerResult {
     /** 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
  *  supplied content_sha256 the deployed active version of this name?" */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loomcycle/client",
-  "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).",
+  "version": "0.21.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. v0.21.0 — run/continue accept optional non-secret `metadata` (repo name, review policy, …) passed to the agent, symmetric with the WebHook/Schedule trigger paths.",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {