@loomcycle/client 0.11.2 → 0.11.4

package/README.md

@@ -6,7 +6,7 @@ TypeScript client for the [loomcycle](https://github.com/denn-gubsky/loomcycle)
 
 ## Status
 
-**v0.11.2** — 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.
+**v0.11.4** — 42 methods covering run streaming, agent metadata, transcript, pause/resume/state, snapshot lifecycle, memory admin, interruption resolve, hook registration, **v0.8.22 substrate admin (agentDef + skillDef)**, **v0.9.x n8n Phase 0 (listChannels + streamUserRunStates)**, **v0.9.x content_sha256**, **v0.9.x dynamic MCP server registration (mcpServerDef)**, **v0.10.3 Library v2 enumeration (listLibraryAgents/Skills/McpServers)**, **v0.11.0 LLM Gateway (llmChat + llmStream)**, **v0.11.4 OpenAI Embeddings (embeddings)**, and health.
 
 > Migrating from raw `fetch` against `/v1/*`? See **[docs/MIGRATING-FROM-HTTP.md](./docs/MIGRATING-FROM-HTTP.md)** for a side-by-side walkthrough.
 
@@ -24,6 +24,8 @@ TypeScript client for the [loomcycle](https://github.com/denn-gubsky/loomcycle)
 - **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.
 - **Docker image + brew formula polish** (v0.11.2) — multi-arch image at `docker.io/denngubsky/loomcycle`; brew formula caveats refreshed to reference `loomcycle init` / `loomcycle doctor`; new `installation` Context.help topic. No adapter changes; lockstep version bump only.
+- **OpenAI Chat Completions compatibility shim** (v0.11.3) — new `POST /v1/chat/completions` endpoint serves OpenAI's exact wire shape; consumers using the OpenAI SDK can point at loomcycle by changing only base URL + auth token. `@loomcycle/client` consumers should still prefer `llmChat()` / `llmStream()` over the shim for richer typing (per-frame discriminated unions vs OpenAI's flat chunks). No adapter changes; lockstep version bump only.
+- **OpenAI Embeddings compatibility shim** (v0.11.4) — new `POST /v1/embeddings` endpoint serves OpenAI's Embeddings API shape. New `embeddings()` adapter method + four typed exports (`LLMEmbeddingsOptions`, `LLMEmbeddingsResponse`, `LLMEmbeddingItem`, `LLMEmbeddingsUsage`). Dispatches to the single configured `providers.Embedder` (the same instance Memory tool uses); RAG tools / vector DBs / LangChain `OpenAIEmbeddings` consumers point at loomcycle by changing only the base URL.
 
 ## Install
 

package/dist/cjs/client.js

@@ -521,6 +521,29 @@ class LoomcycleClient {
         const reader = resp.body.getReader();
         yield* parseLLMStreamFrames(reader);
     }
+    // ---- v0.11.4 OpenAI Embeddings compatibility shim ----
+    /** Compute embedding vectors via the OpenAI-compatible
+     *  `/v1/embeddings` endpoint. Dispatches to the single configured
+     *  `providers.Embedder` (the same instance Memory tool uses for
+     *  `embed:true` internally). No resolver path, no tier overlay,
+     *  no streaming — embeddings are synchronous.
+     *
+     *  Accepts `input` as a string OR string array. Tokenized inputs
+     *  (number arrays) are refused at the server boundary — send text.
+     *  `encoding_format: "base64"` packs each float32 little-endian
+     *  then base64-encodes (saves ~25% wire bytes on 1536-dim
+     *  vectors); "float" (default) emits each vector as a JSON array.
+     *
+     *  Raises {@link AuthError} on 401; {@link UnavailableError} on
+     *  503 (no embedder configured — set memory.embedder.* in
+     *  loomcycle.yaml); {@link InvalidArgumentError} on 400 (bad
+     *  request shape). */
+    async embeddings(opts) {
+        const { signal: _signal, ...body } = opts;
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/embeddings", body, {
+            signal: opts.signal,
+        });
+    }
     // ---- Internal helpers ----
     /** Shared SSE POST → stream-of-AgentEvent path. Used by
      *  runStreaming + continueSession.

package/dist/cjs/index.js

@@ -56,6 +56,9 @@
  *     llmChat(opts: LLMChatOptions): Promise<LLMChatResponse>
  *     llmStream(opts: LLMChatOptions): AsyncIterable<LLMChatStreamItem>
  *
+ *     // OpenAI Embeddings compatibility shim (v0.11.4)
+ *     embeddings(opts: LLMEmbeddingsOptions): Promise<LLMEmbeddingsResponse>
+ *
  *   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, 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";
+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, LLMEmbeddingsOptions, LLMEmbeddingsResponse, MemoryEntriesResponse, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopesResponse, PauseResult, RegisterHookOptions, RegisterHookResponse, ResolveInterruptOptions, ResumeResult, RunOptions, RunStateStreamItem, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, StreamUserRunStatesOptions, SubstrateToolInput, SubstrateToolResponse, TranscriptResponse } from "./types.js";
 export declare class LoomcycleClient {
     private ctx;
     constructor(opts?: ClientOptions);
@@ -361,6 +361,23 @@ export declare class LoomcycleClient {
      *  Use this for live token streaming into LangChain BaseChatModel
      *  `_stream` callbacks. */
     llmStream(opts: LLMChatOptions): AsyncIterable<LLMChatStreamItem>;
+    /** Compute embedding vectors via the OpenAI-compatible
+     *  `/v1/embeddings` endpoint. Dispatches to the single configured
+     *  `providers.Embedder` (the same instance Memory tool uses for
+     *  `embed:true` internally). No resolver path, no tier overlay,
+     *  no streaming — embeddings are synchronous.
+     *
+     *  Accepts `input` as a string OR string array. Tokenized inputs
+     *  (number arrays) are refused at the server boundary — send text.
+     *  `encoding_format: "base64"` packs each float32 little-endian
+     *  then base64-encodes (saves ~25% wire bytes on 1536-dim
+     *  vectors); "float" (default) emits each vector as a JSON array.
+     *
+     *  Raises {@link AuthError} on 401; {@link UnavailableError} on
+     *  503 (no embedder configured — set memory.embedder.* in
+     *  loomcycle.yaml); {@link InvalidArgumentError} on 400 (bad
+     *  request shape). */
+    embeddings(opts: LLMEmbeddingsOptions): Promise<LLMEmbeddingsResponse>;
     /** Shared SSE POST → stream-of-AgentEvent path. Used by
      *  runStreaming + continueSession.
      *

package/dist/client.js

@@ -518,6 +518,29 @@ export class LoomcycleClient {
         const reader = resp.body.getReader();
         yield* parseLLMStreamFrames(reader);
     }
+    // ---- v0.11.4 OpenAI Embeddings compatibility shim ----
+    /** Compute embedding vectors via the OpenAI-compatible
+     *  `/v1/embeddings` endpoint. Dispatches to the single configured
+     *  `providers.Embedder` (the same instance Memory tool uses for
+     *  `embed:true` internally). No resolver path, no tier overlay,
+     *  no streaming — embeddings are synchronous.
+     *
+     *  Accepts `input` as a string OR string array. Tokenized inputs
+     *  (number arrays) are refused at the server boundary — send text.
+     *  `encoding_format: "base64"` packs each float32 little-endian
+     *  then base64-encodes (saves ~25% wire bytes on 1536-dim
+     *  vectors); "float" (default) emits each vector as a JSON array.
+     *
+     *  Raises {@link AuthError} on 401; {@link UnavailableError} on
+     *  503 (no embedder configured — set memory.embedder.* in
+     *  loomcycle.yaml); {@link InvalidArgumentError} on 400 (bad
+     *  request shape). */
+    async embeddings(opts) {
+        const { signal: _signal, ...body } = opts;
+        return postJSON(this.ctx, "/v1/embeddings", body, {
+            signal: opts.signal,
+        });
+    }
     // ---- Internal helpers ----
     /** Shared SSE POST → stream-of-AgentEvent path. Used by
      *  runStreaming + continueSession.

package/dist/index.d.ts

@@ -55,6 +55,9 @@
  *     llmChat(opts: LLMChatOptions): Promise<LLMChatResponse>
  *     llmStream(opts: LLMChatOptions): AsyncIterable<LLMChatStreamItem>
  *
+ *     // OpenAI Embeddings compatibility shim (v0.11.4)
+ *     embeddings(opts: LLMEmbeddingsOptions): Promise<LLMEmbeddingsResponse>
+ *
  *   Errors (typed subclasses of LoomcycleError; see README for the
  *   full HTTP-status → typed-error mapping table):
  *     LoomcycleError, AgentNotFoundError, SessionNotFoundError,
@@ -73,5 +76,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, LLMChatContent, LLMChatMessage, LLMChatOptions, LLMChatResponse, LLMChatStreamDelta, LLMChatStreamItem, LLMChatToolCall, LLMChatUsage, LLMTool, } 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, 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

@@ -55,6 +55,9 @@
  *     llmChat(opts: LLMChatOptions): Promise<LLMChatResponse>
  *     llmStream(opts: LLMChatOptions): AsyncIterable<LLMChatStreamItem>
  *
+ *     // OpenAI Embeddings compatibility shim (v0.11.4)
+ *     embeddings(opts: LLMEmbeddingsOptions): Promise<LLMEmbeddingsResponse>
+ *
  *   Errors (typed subclasses of LoomcycleError; see README for the
  *   full HTTP-status → typed-error mapping table):
  *     LoomcycleError, AgentNotFoundError, SessionNotFoundError,

package/dist/types.d.ts

@@ -1027,3 +1027,49 @@ export interface LLMChatStreamDelta {
     text?: string;
     partial_json?: string;
 }
+/** Request body for `embeddings()`. */
+export interface LLMEmbeddingsOptions {
+    /** Consumer's requested model id (echoed in the response).
+     *  Loomcycle uses the single configured embedder regardless;
+     *  the field is informational for drop-in compatibility. */
+    model: string;
+    /** Text(s) to embed. v1 accepts string or string[]; tokenized
+     *  inputs (number arrays) are refused — send text. */
+    input: string | string[];
+    /** "float" (default) emits each vector as a JSON array of
+     *  numbers; "base64" packs each float32 little-endian then
+     *  base64-encodes (saves ~25% wire bytes on 1536-dim vectors). */
+    encoding_format?: "float" | "base64";
+    /** OpenAI's post-hoc dimension reduction parameter. Accepted-
+     *  but-ignored in v0.11.4 (the providers.Embedder interface
+     *  doesn't take a dimension parameter today). */
+    dimensions?: number;
+    /** OpenAI-standard opaque end-user identifier. Maps to
+     *  loomcycle's per-user quota tracking + audit log. */
+    user?: string;
+    /** Optional AbortSignal for caller-driven cancellation. */
+    signal?: AbortSignal;
+}
+/** Per-embedding entry in the response data array. */
+export interface LLMEmbeddingItem {
+    object: "embedding";
+    /** float[] when the request used encoding_format:"float"
+     *  (default); base64 string when encoding_format:"base64". */
+    embedding: number[] | string;
+    index: number;
+}
+/** Token-accounting payload. v0.11.4 leaves both fields at 0 — the
+ *  substrate's Embedder interface doesn't return per-call token
+ *  counts today. When that lands, the shim's translator populates
+ *  these automatically. */
+export interface LLMEmbeddingsUsage {
+    prompt_tokens: number;
+    total_tokens: number;
+}
+/** Response shape mirrors OpenAI's /v1/embeddings exactly. */
+export interface LLMEmbeddingsResponse {
+    object: "list";
+    data: LLMEmbeddingItem[];
+    model: string;
+    usage: LLMEmbeddingsUsage;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loomcycle/client",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "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",