@loomcycle/client 0.10.4 → 0.11.1

package/README.md

@@ -6,18 +6,23 @@ TypeScript client for the [loomcycle](https://github.com/denn-gubsky/loomcycle)
 
 ## Status
 
-**v0.11.0** — 31 methods covering run streaming, agent metadata, transcript, pause/resume/state, snapshot lifecycle, memory admin, interruption resolve, hook registration, **v0.8.22 substrate admin (agentDef + skillDef)**, **v0.9.x n8n Phase 0 (listChannels + streamUserRunStates)**, **v0.9.x content_sha256** (the bundle-vs-deployed comparison workflow for Docker-bundled operators), and health.
+**v0.11.1** — 41 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)**, and health.
 
 > Migrating from raw `fetch` against `/v1/*`? See **[docs/MIGRATING-FROM-HTTP.md](./docs/MIGRATING-FROM-HTTP.md)** for a side-by-side walkthrough.
 
 ### What's new since v0.8.18
 
-- **`agentDef` / `skillDef`** (v0.8.22) — runtime fork / promote / retire / get / list / `verify` on the substrate. Lets a containerised app push agent + skill definitions to a remote loomcycle at startup without restarting it.
-- **`listChannels`** (v0.9.x) — list operator-declared channels with aggregate stats (message_count, oldest/newest visible_at). The substrate companion to the existing Channel tool; useful for credential pickers + dashboards.
-- **`streamUserRunStates`** (v0.9.x) — SSE stream of run state transitions scoped to one `user_id`. Yields `{ kind: "open" | "event", payload }` items until the connection closes (30-min server cap). The primary substrate hook for orchestration UIs that need to react when an agent run completes / fails / cancels.
-- **Content signatures** (v0.9.x) — every `agent_defs` / `skill_defs` row now carries a deterministic `content_sha256`. Combined with the `verify` op and the `loomcycle hash agent|skill` CLI subcommand, this gives Docker-bundled operators a one-call answer to *"is what I have in my image identical to what's deployed?"* — see [Content signatures](#content-signatures-v09x) below for the end-to-end workflow.
-- **Transcript first-cycle types** (v0.9.1) — `UserInputPayload` + `SystemPromptPayload` typed interfaces for the two new transcript events that surface "what the agent actually received" (the resolved system prompt + the caller's segments) as the first frames of every run.
-- **n8n polish — `debug` toggle + `parentAgentId` filter** (v0.13.0) — opt-in synthetic `stream_open` / `stream_close` frames on `runStreaming` / `continueSession` / `streamUserRunStates` plus a client-side `parentAgentId` filter on `listUserAgents` + `streamUserRunStates`. Default behaviour is unchanged for existing callers; both knobs are off until set. See [Patterns](#patterns) for when to reach for them.
+- **`llmChat` / `llmStream`** (v0.11.0) — direct LLM call surface that bypasses the agent loop. Provider routing + auth + retry without the ~50-200 ms per-turn overhead of a full `runStreaming` spawn. Drives n8n's `LoomCycleChatModel` AI Agent sub-node + any LangChain `BaseChatModel` consumer.
+- **`listLibraryAgents` / `listLibrarySkills` / `listLibraryMcpServers`** (v0.10.3) — typed wrappers around the v0.9.3 Library v2 endpoints. Each returns a `LibraryListResponse<T>` with source-tagged entries (`"static-only"` / `"dynamic-only"` / `"both"`) merging yaml + substrate views.
+- **`mcpServerDef`** (v0.9.x) — runtime registration of HTTP / Streamable-HTTP MCP servers without yaml edits. Same op grammar (create / fork / promote / retire / rediscover) as `agentDef` / `skillDef`.
+- **`agentDef` / `skillDef`** (v0.8.22) — runtime fork / promote / retire / get / list / `verify` on the substrate.
+- **`listChannels`** (v0.9.x) — list operator-declared channels with aggregate stats (message_count, oldest/newest visible_at).
+- **`streamUserRunStates`** (v0.9.x) — SSE stream of run state transitions scoped to one `user_id`. Yields `{ kind: "open" | "event", payload }` items until the connection closes (30-min server cap).
+- **Channel CRUD** (v0.9.x) — `publishChannel` / `subscribeChannel` / `peekChannel` / `ackChannel` with both admin scope (`scope: "global"`) and per-user scope (`scope: "user"` + `userId`).
+- **Content signatures** (v0.9.x) — every `agent_defs` / `skill_defs` row carries a deterministic `content_sha256`. Combined with the `verify` op gives operators a one-call answer to *"is what I have identical to what's deployed?"*.
+- **Transcript first-cycle types** (v0.9.1) — `UserInputPayload` + `SystemPromptPayload` typed interfaces for the two transcript events that surface "what the agent actually received" as the first frames of every run.
+- **Dual ESM + CJS distribution** (v0.10.1) — n8n's community-node loader (CommonJS) now works alongside ESM consumers.
+- **First-run UX on the binary** (v0.11.1) — paired CLI commands `loomcycle init` (bootstrap config) + `loomcycle doctor` (health check) + auto-discovery of `~/.config/loomcycle/loomcycle.yaml`. No adapter changes; lockstep version bump only.
 
 ## Install
 

package/dist/cjs/client.js

@@ -463,6 +463,64 @@ class LoomcycleClient {
     async listLibraryMcpServers(opts) {
         return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, "/v1/_library/mcp-servers", opts);
     }
+    // ---- v0.11.0 LLM Gateway ----
+    /** Non-streaming LLM chat completion via the gateway endpoint.
+     *  Wraps `POST /v1/_llm/chat` with `stream: false`. The gateway
+     *  resolves a provider per the routing precedence
+     *  (explicit-pin > explicit-provider > explicit-model > resolver
+     *  default), invokes it directly (no agent loop), and returns the
+     *  aggregated response with usage counters + the chosen
+     *  provider/model echoed back.
+     *
+     *  Use this when you want loomcycle's routing benefits (one
+     *  credential, one quota, one observability surface across
+     *  providers) without paying for the agent runtime overhead.
+     *  Tool-calling works: pass `tools[]` and read `tool_use` content
+     *  blocks back; the per-provider schema translation is handled by
+     *  the substrate's existing driver layer.
+     *
+     *  Raises {@link AuthError} on 401; {@link UnavailableError} on 503
+     *  (resolver not configured, store unwired);
+     *  {@link InvalidArgumentError} on 400 (bad request shape). */
+    async llmChat(opts) {
+        const body = serializeLLMOptions(opts, false);
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_llm/chat", body, {
+            signal: opts.signal,
+        });
+    }
+    /** Streaming LLM chat completion. Wraps `POST /v1/_llm/chat` with
+     *  `stream: true`. Yields one {@link LLMChatStreamItem} per SSE
+     *  frame in Anthropic-style: provider_chosen first, then
+     *  content_block_start / content_block_delta / content_block_stop
+     *  pairs, then message_delta + done.
+     *
+     *  Iteration terminates when the gateway closes the stream. On a
+     *  terminal error the gateway emits an `error` frame; the iterator
+     *  yields it and the caller decides whether to throw.
+     *
+     *  Use this for live token streaming into LangChain BaseChatModel
+     *  `_stream` callbacks. */
+    async *llmStream(opts) {
+        const body = serializeLLMOptions(opts, true);
+        const resp = await this.ctx.fetchImpl(this.ctx.baseUrl + "/v1/_llm/chat", {
+            method: "POST",
+            headers: {
+                ...(0, fetch_helpers_js_1.authHeaders)(this.ctx),
+                "Content-Type": "application/json",
+                Accept: "text/event-stream",
+            },
+            body: JSON.stringify(body),
+            signal: opts.signal,
+        });
+        if (!resp.ok) {
+            await (0, fetch_helpers_js_1.raiseFromResponse)(resp);
+        }
+        if (!resp.body) {
+            throw new Error("llmStream: response has no body");
+        }
+        const reader = resp.body.getReader();
+        yield* parseLLMStreamFrames(reader);
+    }
     // ---- Internal helpers ----
     /** Shared SSE POST → stream-of-AgentEvent path. Used by
      *  runStreaming + continueSession.
@@ -773,3 +831,72 @@ function channelOpPath(channel, scope, userId, op) {
     }
     return `/v1/_channels/${enc}/${op}`;
 }
+// ---- v0.11.0 LLM Gateway helpers ----
+/** serializeLLMOptions strips the AbortSignal (transport concern) and
+ *  forces the stream flag to match the call mode. */
+function serializeLLMOptions(opts, stream) {
+    const { signal: _signal, ...rest } = opts;
+    return { ...rest, stream };
+}
+/** parseLLMStreamFrames drains an SSE stream from /v1/_llm/chat and
+ *  yields one LLMChatStreamItem per frame. Unlike parseSSE in
+ *  stream.ts, the gateway's frames discriminate purely by the SSE
+ *  event name — there's no `type` field on the data payload. */
+async function* parseLLMStreamFrames(reader) {
+    const decoder = new TextDecoder("utf-8");
+    let buf = "";
+    let event = "";
+    let data = "";
+    const flush = () => {
+        if (!event || !data) {
+            event = "";
+            data = "";
+            return null;
+        }
+        try {
+            const payload = JSON.parse(data);
+            const item = { kind: event, payload };
+            event = "";
+            data = "";
+            return item;
+        }
+        catch {
+            event = "";
+            data = "";
+            return null;
+        }
+    };
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        buf += decoder.decode(value, { stream: true });
+        let idx;
+        while ((idx = buf.indexOf("\n")) !== -1) {
+            const line = buf.slice(0, idx).replace(/\r$/, "");
+            buf = buf.slice(idx + 1);
+            if (line === "") {
+                const item = flush();
+                if (item)
+                    yield item;
+                continue;
+            }
+            if (line.startsWith("event:"))
+                event = line.slice("event:".length).trim();
+            else if (line.startsWith("data:"))
+                data = line.slice("data:".length).trim();
+            // Keepalive comment lines (`:keepalive`) are silently dropped.
+        }
+    }
+    // Drain a final un-newlined frame on connection close.
+    if (buf.length > 0) {
+        const line = buf.replace(/\r$/, "");
+        if (line.startsWith("event:"))
+            event = line.slice("event:".length).trim();
+        else if (line.startsWith("data:"))
+            data = line.slice("data:".length).trim();
+    }
+    const item = flush();
+    if (item)
+        yield item;
+}

package/dist/cjs/index.js

@@ -52,6 +52,10 @@
  *     listLibrarySkills(): Promise<LibraryListResponse<LibrarySkillDefinition>>
  *     listLibraryMcpServers(): Promise<LibraryListResponse<LibraryMcpServerDefinition>>
  *
+ *     // LLM Gateway (v0.11.0 — direct provider routing, no agent loop)
+ *     llmChat(opts: LLMChatOptions): Promise<LLMChatResponse>
+ *     llmStream(opts: LLMChatOptions): AsyncIterable<LLMChatStreamItem>
+ *
  *   Errors (typed subclasses of LoomcycleError; see README for the
  *   full HTTP-status → typed-error mapping table):
  *     LoomcycleError, AgentNotFoundError, SessionNotFoundError,

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, ChannelPeekResult, ChannelPublishResult, ChannelSubscribeResult, ListChannelsResponse, PeekChannelOptions, PublishChannelOptions, SubscribeChannelOptions, LibraryAgentDefinition, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, ListUsersResponse, MemoryEntriesResponse, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopesResponse, PauseResult, RegisterHookOptions, RegisterHookResponse, ResolveInterruptOptions, ResumeResult, RunOptions, RunStateStreamItem, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, StreamUserRunStatesOptions, SubstrateToolInput, SubstrateToolResponse, TranscriptResponse } from "./types.js";
+import type { Agent, AgentEvent, AgentStatus, CancelAgentResult, ClientOptions, ContinueOptions, CreateSnapshotOptions, HealthResponse, Hook, InterruptListResponse, InterruptStatus, AckChannelOptions, ChannelAckResult, ChannelPeekResult, ChannelPublishResult, ChannelSubscribeResult, ListChannelsResponse, PeekChannelOptions, PublishChannelOptions, SubscribeChannelOptions, LibraryAgentDefinition, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, ListUsersResponse, LLMChatOptions, LLMChatResponse, LLMChatStreamItem, MemoryEntriesResponse, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopesResponse, PauseResult, RegisterHookOptions, RegisterHookResponse, ResolveInterruptOptions, ResumeResult, RunOptions, RunStateStreamItem, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, StreamUserRunStatesOptions, SubstrateToolInput, SubstrateToolResponse, TranscriptResponse } from "./types.js";
 export declare class LoomcycleClient {
     private ctx;
     constructor(opts?: ClientOptions);
@@ -329,6 +329,38 @@ export declare class LoomcycleClient {
     listLibraryMcpServers(opts?: {
         signal?: AbortSignal;
     }): Promise<LibraryListResponse<LibraryMcpServerDefinition>>;
+    /** Non-streaming LLM chat completion via the gateway endpoint.
+     *  Wraps `POST /v1/_llm/chat` with `stream: false`. The gateway
+     *  resolves a provider per the routing precedence
+     *  (explicit-pin > explicit-provider > explicit-model > resolver
+     *  default), invokes it directly (no agent loop), and returns the
+     *  aggregated response with usage counters + the chosen
+     *  provider/model echoed back.
+     *
+     *  Use this when you want loomcycle's routing benefits (one
+     *  credential, one quota, one observability surface across
+     *  providers) without paying for the agent runtime overhead.
+     *  Tool-calling works: pass `tools[]` and read `tool_use` content
+     *  blocks back; the per-provider schema translation is handled by
+     *  the substrate's existing driver layer.
+     *
+     *  Raises {@link AuthError} on 401; {@link UnavailableError} on 503
+     *  (resolver not configured, store unwired);
+     *  {@link InvalidArgumentError} on 400 (bad request shape). */
+    llmChat(opts: LLMChatOptions): Promise<LLMChatResponse>;
+    /** Streaming LLM chat completion. Wraps `POST /v1/_llm/chat` with
+     *  `stream: true`. Yields one {@link LLMChatStreamItem} per SSE
+     *  frame in Anthropic-style: provider_chosen first, then
+     *  content_block_start / content_block_delta / content_block_stop
+     *  pairs, then message_delta + done.
+     *
+     *  Iteration terminates when the gateway closes the stream. On a
+     *  terminal error the gateway emits an `error` frame; the iterator
+     *  yields it and the caller decides whether to throw.
+     *
+     *  Use this for live token streaming into LangChain BaseChatModel
+     *  `_stream` callbacks. */
+    llmStream(opts: LLMChatOptions): AsyncIterable<LLMChatStreamItem>;
     /** Shared SSE POST → stream-of-AgentEvent path. Used by
      *  runStreaming + continueSession.
      *

package/dist/client.js

@@ -23,7 +23,7 @@
  * via fetch-helpers.ts:raiseFromResponse — see README.md for the
  * full mapping table.
  */
-import { deleteRequest, jsonFetch, postJSON, raiseFromResponse, } from "./fetch-helpers.js";
+import { authHeaders, deleteRequest, jsonFetch, postJSON, raiseFromResponse, } from "./fetch-helpers.js";
 import { parseSSE } from "./stream.js";
 export class LoomcycleClient {
     ctx;
@@ -460,6 +460,64 @@ export class LoomcycleClient {
     async listLibraryMcpServers(opts) {
         return jsonFetch(this.ctx, "/v1/_library/mcp-servers", opts);
     }
+    // ---- v0.11.0 LLM Gateway ----
+    /** Non-streaming LLM chat completion via the gateway endpoint.
+     *  Wraps `POST /v1/_llm/chat` with `stream: false`. The gateway
+     *  resolves a provider per the routing precedence
+     *  (explicit-pin > explicit-provider > explicit-model > resolver
+     *  default), invokes it directly (no agent loop), and returns the
+     *  aggregated response with usage counters + the chosen
+     *  provider/model echoed back.
+     *
+     *  Use this when you want loomcycle's routing benefits (one
+     *  credential, one quota, one observability surface across
+     *  providers) without paying for the agent runtime overhead.
+     *  Tool-calling works: pass `tools[]` and read `tool_use` content
+     *  blocks back; the per-provider schema translation is handled by
+     *  the substrate's existing driver layer.
+     *
+     *  Raises {@link AuthError} on 401; {@link UnavailableError} on 503
+     *  (resolver not configured, store unwired);
+     *  {@link InvalidArgumentError} on 400 (bad request shape). */
+    async llmChat(opts) {
+        const body = serializeLLMOptions(opts, false);
+        return postJSON(this.ctx, "/v1/_llm/chat", body, {
+            signal: opts.signal,
+        });
+    }
+    /** Streaming LLM chat completion. Wraps `POST /v1/_llm/chat` with
+     *  `stream: true`. Yields one {@link LLMChatStreamItem} per SSE
+     *  frame in Anthropic-style: provider_chosen first, then
+     *  content_block_start / content_block_delta / content_block_stop
+     *  pairs, then message_delta + done.
+     *
+     *  Iteration terminates when the gateway closes the stream. On a
+     *  terminal error the gateway emits an `error` frame; the iterator
+     *  yields it and the caller decides whether to throw.
+     *
+     *  Use this for live token streaming into LangChain BaseChatModel
+     *  `_stream` callbacks. */
+    async *llmStream(opts) {
+        const body = serializeLLMOptions(opts, true);
+        const resp = await this.ctx.fetchImpl(this.ctx.baseUrl + "/v1/_llm/chat", {
+            method: "POST",
+            headers: {
+                ...authHeaders(this.ctx),
+                "Content-Type": "application/json",
+                Accept: "text/event-stream",
+            },
+            body: JSON.stringify(body),
+            signal: opts.signal,
+        });
+        if (!resp.ok) {
+            await raiseFromResponse(resp);
+        }
+        if (!resp.body) {
+            throw new Error("llmStream: response has no body");
+        }
+        const reader = resp.body.getReader();
+        yield* parseLLMStreamFrames(reader);
+    }
     // ---- Internal helpers ----
     /** Shared SSE POST → stream-of-AgentEvent path. Used by
      *  runStreaming + continueSession.
@@ -769,3 +827,72 @@ function channelOpPath(channel, scope, userId, op) {
     }
     return `/v1/_channels/${enc}/${op}`;
 }
+// ---- v0.11.0 LLM Gateway helpers ----
+/** serializeLLMOptions strips the AbortSignal (transport concern) and
+ *  forces the stream flag to match the call mode. */
+function serializeLLMOptions(opts, stream) {
+    const { signal: _signal, ...rest } = opts;
+    return { ...rest, stream };
+}
+/** parseLLMStreamFrames drains an SSE stream from /v1/_llm/chat and
+ *  yields one LLMChatStreamItem per frame. Unlike parseSSE in
+ *  stream.ts, the gateway's frames discriminate purely by the SSE
+ *  event name — there's no `type` field on the data payload. */
+async function* parseLLMStreamFrames(reader) {
+    const decoder = new TextDecoder("utf-8");
+    let buf = "";
+    let event = "";
+    let data = "";
+    const flush = () => {
+        if (!event || !data) {
+            event = "";
+            data = "";
+            return null;
+        }
+        try {
+            const payload = JSON.parse(data);
+            const item = { kind: event, payload };
+            event = "";
+            data = "";
+            return item;
+        }
+        catch {
+            event = "";
+            data = "";
+            return null;
+        }
+    };
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        buf += decoder.decode(value, { stream: true });
+        let idx;
+        while ((idx = buf.indexOf("\n")) !== -1) {
+            const line = buf.slice(0, idx).replace(/\r$/, "");
+            buf = buf.slice(idx + 1);
+            if (line === "") {
+                const item = flush();
+                if (item)
+                    yield item;
+                continue;
+            }
+            if (line.startsWith("event:"))
+                event = line.slice("event:".length).trim();
+            else if (line.startsWith("data:"))
+                data = line.slice("data:".length).trim();
+            // Keepalive comment lines (`:keepalive`) are silently dropped.
+        }
+    }
+    // Drain a final un-newlined frame on connection close.
+    if (buf.length > 0) {
+        const line = buf.replace(/\r$/, "");
+        if (line.startsWith("event:"))
+            event = line.slice("event:".length).trim();
+        else if (line.startsWith("data:"))
+            data = line.slice("data:".length).trim();
+    }
+    const item = flush();
+    if (item)
+        yield item;
+}

package/dist/index.d.ts

@@ -51,6 +51,10 @@
  *     listLibrarySkills(): Promise<LibraryListResponse<LibrarySkillDefinition>>
  *     listLibraryMcpServers(): Promise<LibraryListResponse<LibraryMcpServerDefinition>>
  *
+ *     // LLM Gateway (v0.11.0 — direct provider routing, no agent loop)
+ *     llmChat(opts: LLMChatOptions): Promise<LLMChatResponse>
+ *     llmStream(opts: LLMChatOptions): AsyncIterable<LLMChatStreamItem>
+ *
  *   Errors (typed subclasses of LoomcycleError; see README for the
  *   full HTTP-status → typed-error mapping table):
  *     LoomcycleError, AgentNotFoundError, SessionNotFoundError,
@@ -69,5 +73,5 @@
  * See `adapters/ts/README.md` for usage examples.
  */
 export { LoomcycleClient } from "./client.js";
-export type { AgentEvent, ClientOptions, ContinueOptions, EventType, HostWidening, PromptContent, PromptSegment, RetryInfo, RunOptions, ToolUse, Usage, Agent, AgentStatus, AgentUsage, CancelAgentResult, ListAgentsResponse, TranscriptEvent, TranscriptResponse, HealthResponse, ListUsersResponse, UserSummary, PauseResult, ResumeResult, RuntimeStateResponse, RuntimeStateStatus, CreateSnapshotOptions, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotListResponse, SnapshotRestoreResponse, MemoryEntriesResponse, MemoryEntry, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopeIDSummary, MemoryScopeKind, MemoryScopesResponse, InterruptListResponse, InterruptRow, InterruptStatus, ResolveInterruptOptions, Hook, HookFailMode, HookPhase, HookToolCall, HookToolResult, ListHooksResponse, PostHookCall, PostHookResult, PreHookCall, PreHookResult, RegisterHookOptions, RegisterHookResponse, SubstrateToolInput, SubstrateToolResponse, SystemPromptPayload, UserInputPayload, ChannelDescriptor, ListChannelsResponse, RunStateEvent, RunStateStreamClose, RunStateStreamItem, RunStateStreamOpen, StreamUserRunStatesOptions, AckChannelOptions, ChannelAckResult, ChannelMessageItem, ChannelPeekResult, ChannelPublishResult, ChannelScope, ChannelSubscribeResult, PeekChannelOptions, PublishChannelOptions, SubscribeChannelOptions, AgentDefRowResponse, AgentDefVerifyResult, SkillDefVerifyResult, MCPServerDefRowResponse, MCPServerDefVerifyResult, LibraryAgentDefinition, LibraryEntry, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, } from "./types.js";
+export type { AgentEvent, ClientOptions, ContinueOptions, EventType, HostWidening, PromptContent, PromptSegment, RetryInfo, RunOptions, ToolUse, Usage, Agent, AgentStatus, AgentUsage, CancelAgentResult, ListAgentsResponse, TranscriptEvent, TranscriptResponse, HealthResponse, ListUsersResponse, UserSummary, PauseResult, ResumeResult, RuntimeStateResponse, RuntimeStateStatus, CreateSnapshotOptions, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotListResponse, SnapshotRestoreResponse, MemoryEntriesResponse, MemoryEntry, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopeIDSummary, MemoryScopeKind, MemoryScopesResponse, InterruptListResponse, InterruptRow, InterruptStatus, ResolveInterruptOptions, Hook, HookFailMode, HookPhase, HookToolCall, HookToolResult, ListHooksResponse, PostHookCall, PostHookResult, PreHookCall, PreHookResult, RegisterHookOptions, RegisterHookResponse, SubstrateToolInput, SubstrateToolResponse, SystemPromptPayload, UserInputPayload, ChannelDescriptor, ListChannelsResponse, RunStateEvent, RunStateStreamClose, RunStateStreamItem, RunStateStreamOpen, StreamUserRunStatesOptions, AckChannelOptions, ChannelAckResult, ChannelMessageItem, ChannelPeekResult, ChannelPublishResult, ChannelScope, ChannelSubscribeResult, PeekChannelOptions, PublishChannelOptions, SubscribeChannelOptions, AgentDefRowResponse, AgentDefVerifyResult, SkillDefVerifyResult, MCPServerDefRowResponse, MCPServerDefVerifyResult, LibraryAgentDefinition, LibraryEntry, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, LLMChatContent, LLMChatMessage, LLMChatOptions, LLMChatResponse, LLMChatStreamDelta, LLMChatStreamItem, LLMChatToolCall, LLMChatUsage, LLMTool, } 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

@@ -51,6 +51,10 @@
  *     listLibrarySkills(): Promise<LibraryListResponse<LibrarySkillDefinition>>
  *     listLibraryMcpServers(): Promise<LibraryListResponse<LibraryMcpServerDefinition>>
  *
+ *     // LLM Gateway (v0.11.0 — direct provider routing, no agent loop)
+ *     llmChat(opts: LLMChatOptions): Promise<LLMChatResponse>
+ *     llmStream(opts: LLMChatOptions): AsyncIterable<LLMChatStreamItem>
+ *
  *   Errors (typed subclasses of LoomcycleError; see README for the
  *   full HTTP-status → typed-error mapping table):
  *     LoomcycleError, AgentNotFoundError, SessionNotFoundError,

package/dist/types.d.ts

@@ -879,3 +879,151 @@ export interface LibraryEntry<T = unknown> {
 export interface LibraryListResponse<T = unknown> {
     entries: LibraryEntry<T>[];
 }
+/** One message in the gateway conversation. Mirrors LangChain's
+ *  BaseMessage shape so consumers map without re-shaping. */
+export interface LLMChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    /** Flat string content. For "assistant" turns with tool_calls,
+     *  the content may be empty. For "tool" turns, this is the tool
+     *  result text. */
+    content?: string;
+    /** Set on "assistant" turns that requested tool invocations. */
+    tool_calls?: LLMChatToolCall[];
+    /** Set on "tool" turns; correlates back to the assistant's
+     *  tool_calls[].id. */
+    tool_call_id?: string;
+}
+/** One assistant-requested tool invocation. */
+export interface LLMChatToolCall {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+/** Tool the model may call. The substrate translates this into the
+ *  driver-native shape (Anthropic input_schema vs OpenAI function.
+ *  parameters vs Gemini function_declarations) — caller passes the
+ *  flat JSON schema and trusts the gateway's per-driver translation. */
+export interface LLMTool {
+    name: string;
+    description?: string;
+    input_schema: Record<string, unknown>;
+}
+/** Request body for llmChat / llmStream.
+ *
+ *  Two RFC-mentioned fields are deliberately absent in v1:
+ *  - `stop_sequences`: providers.Request has no matching field today;
+ *    accepting it would silently drop it. Lands when the providers
+ *    package surface grows the equivalent.
+ *  - `user_bearer`: the gateway calls provider.Call() directly with
+ *    no MCP transport, so `${run.user_bearer}` substitution has
+ *    nowhere to apply. Lands when the gateway grows an MCP path. */
+export interface LLMChatOptions {
+    messages: LLMChatMessage[];
+    tools?: LLMTool[];
+    max_tokens?: number;
+    temperature?: number | null;
+    /** Routing hint. When set with `model`, the resolver short-circuits
+     *  to that explicit pin. When set alone, the resolver picks the
+     *  best model in that provider given tier/user_tier. */
+    provider?: string;
+    /** Routing hint. When set with `provider`, explicit pin. When set
+     *  alone, the resolver picks the provider hosting that model. */
+    model?: string;
+    /** Tier for resolver dispatch. Defaults to "default" when neither
+     *  pin nor tier supplied. */
+    tier?: string;
+    /** Per-user quota tracking. Empty bypasses the per-user cap. */
+    user_id?: string;
+    /** Per-user tier overlay; takes precedence over `tier` when set. */
+    user_tier?: string;
+    /** Optional AbortSignal for caller-driven cancellation. */
+    signal?: AbortSignal;
+}
+/** Non-streaming response shape. */
+export interface LLMChatResponse {
+    /** Per-response id (llm_<hex>); useful in audit logs. */
+    id: string;
+    /** Per-request id (req_<hex>); cross-references the audit log. */
+    request_id: string;
+    /** Which provider the resolver picked. */
+    provider: string;
+    /** Specific model id picked. */
+    model: string;
+    /** Content blocks; one per text or tool_use output. */
+    content: LLMChatContent[];
+    stop_reason: "end_turn" | "max_tokens" | "tool_use" | "stop_sequence";
+    usage: LLMChatUsage;
+}
+/** One output content block. */
+export type LLMChatContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+};
+/** Token-accounting payload. Cache fields are populated only on
+ *  providers that surface them (Anthropic today). */
+export interface LLMChatUsage {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+}
+/** One streaming-mode SSE frame. The `kind` field is the SSE event
+ *  name; the `payload` carries the per-frame shape. v1 mirrors
+ *  Anthropic's streaming event names. */
+export type LLMChatStreamItem = {
+    kind: "provider_chosen";
+    payload: {
+        provider: string;
+        model: string;
+        request_id: string;
+    };
+} | {
+    kind: "content_block_start";
+    payload: {
+        index: number;
+        block: LLMChatContent;
+    };
+} | {
+    kind: "content_block_delta";
+    payload: {
+        index: number;
+        delta: LLMChatStreamDelta;
+    };
+} | {
+    kind: "content_block_stop";
+    payload: {
+        index: number;
+    };
+} | {
+    kind: "message_delta";
+    payload: {
+        delta: {
+            stop_reason?: string;
+        };
+        usage: LLMChatUsage;
+    };
+} | {
+    kind: "done";
+    payload: {
+        id: string;
+        stop_reason: string;
+        usage: LLMChatUsage;
+    };
+} | {
+    kind: "error";
+    payload: {
+        type: string;
+        code: string;
+        message: string;
+    };
+};
+export interface LLMChatStreamDelta {
+    type: "text_delta" | "input_json_delta";
+    text?: string;
+    partial_json?: string;
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loomcycle/client",
-  "version": "0.10.4",
-  "description": "TypeScript client for the loomcycle sidecar (HTTP+SSE). 39 methods covering run streaming, agent metadata, pause/resume/state, snapshot lifecycle, memory admin (incl. v0.9.0 Vector Memory embed_stats + reembed), interruption resolve, hook management, v0.8.22 substrate admin (agentDef + skillDef), v0.9.x n8n Phase 0 (listChannels + streamUserRunStates — with debug-mode synthetic open/close meta-frames + client-side parentAgentId filter), v0.9.x Channel CRUD (publishChannel + subscribeChannel + peekChannel + ackChannel — admin scope=global + per-user scope=user surfaces), v0.9.x content_sha256 (AgentDefVerifyResult + SkillDefVerifyResult types for the bundle-vs-deployed comparison workflow), v0.9.1 transcript first-cycle (SystemPromptPayload + UserInputPayload), v0.9.x dynamic MCP server registration (mcpServerDef + MCPServerDefVerifyResult — register HTTP/Streamable-HTTP MCP servers at runtime without yaml edits), and v0.10.3 Library v2 enumeration (listLibraryAgents + listLibrarySkills + listLibraryMcpServers — typed wrappers around the v0.9.3 yaml+substrate merged endpoints for n8n + workflow-editor integrations). v0.10.1 — dual ESM + CommonJS distribution (additive — ESM consumers unchanged; CJS consumers like n8n's community-node loader now work).",
+  "version": "0.11.1",
+  "description": "TypeScript client for the loomcycle sidecar (HTTP+SSE). 41 methods covering run streaming, agent metadata, pause/resume/state, snapshot lifecycle, memory admin (incl. v0.9.0 Vector Memory embed_stats + reembed), interruption resolve, hook management, v0.8.22 substrate admin (agentDef + skillDef), v0.9.x n8n Phase 0 (listChannels + streamUserRunStates), v0.9.x Channel CRUD (publishChannel + subscribeChannel + peekChannel + ackChannel), 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": {