@loomcycle/client 0.29.1 → 0.33.0

package/dist/cjs/client.js

@@ -28,6 +28,87 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LoomcycleClient = void 0;
 const fetch_helpers_js_1 = require("./fetch-helpers.js");
 const stream_js_1 = require("./stream.js");
+/** samplingToWire maps the camelCase SamplingOptions to the snake_case wire
+ *  object, omitting unset fields so they inherit the agent's value. */
+function samplingToWire(s) {
+    const w = {};
+    if (s.temperature !== undefined)
+        w.temperature = s.temperature;
+    if (s.topP !== undefined)
+        w.top_p = s.topP;
+    if (s.topK !== undefined)
+        w.top_k = s.topK;
+    if (s.frequencyPenalty !== undefined)
+        w.frequency_penalty = s.frequencyPenalty;
+    if (s.presencePenalty !== undefined)
+        w.presence_penalty = s.presencePenalty;
+    if (s.seed !== undefined)
+        w.seed = s.seed;
+    if (s.stop !== undefined)
+        w.stop = s.stop;
+    return w;
+}
+/** compactionToWire maps the camelCase CompactionOptions to the snake_case
+ *  wire object, omitting unset fields so they inherit the agent's value. */
+function compactionToWire(c) {
+    const w = {};
+    if (c.enabled !== undefined)
+        w.enabled = c.enabled;
+    if (c.targetPercentage !== undefined)
+        w.target_percentage = c.targetPercentage;
+    if (c.keepLastN !== undefined)
+        w.keep_last_n = c.keepLastN;
+    if (c.keepFirst !== undefined)
+        w.keep_first = c.keepFirst;
+    if (c.autocompactAtPct !== undefined)
+        w.autocompact_at_pct = c.autocompactAtPct;
+    if (c.model !== undefined)
+        w.model = c.model;
+    return w;
+}
+/** runBody builds the snake_case /v1/runs request body from RunOptions,
+ *  omitting unset fields (preserves the server's nil semantics — notably
+ *  `allowedHosts: null` is treated as "omit", not deny-all). Shared by
+ *  runStreaming and each spawn of spawnRunBatch. `signal`/`debug` are client
+ *  concerns and never sent. */
+function runBody(opts) {
+    const body = {
+        agent: opts.agent,
+        segments: opts.segments,
+    };
+    if (opts.allowedTools !== undefined)
+        body.allowed_tools = opts.allowedTools;
+    if (opts.allowedHosts !== undefined && opts.allowedHosts !== null) {
+        body.allowed_hosts = opts.allowedHosts;
+    }
+    if (opts.webSearchFilter !== undefined)
+        body.web_search_filter = opts.webSearchFilter;
+    if (opts.sessionId !== undefined)
+        body.session_id = opts.sessionId;
+    if (opts.tenantId !== undefined)
+        body.tenant_id = opts.tenantId;
+    if (opts.userId !== undefined)
+        body.user_id = opts.userId;
+    if (opts.agentId !== undefined)
+        body.agent_id = opts.agentId;
+    if (opts.userTier !== undefined)
+        body.user_tier = opts.userTier;
+    if (opts.userBearer !== undefined)
+        body.user_bearer = opts.userBearer;
+    if (opts.userCredentials !== undefined)
+        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;
+    if (opts.sampling !== undefined)
+        body.sampling = samplingToWire(opts.sampling);
+    if (opts.compaction !== undefined)
+        body.compaction = compactionToWire(opts.compaction);
+    return body;
+}
 class LoomcycleClient {
     ctx;
     constructor(opts = {}) {
@@ -60,44 +141,7 @@ class LoomcycleClient {
      * events around the real frames. Silent (default) when omitted.
      */
     async *runStreaming(opts) {
-        // Build the body conditionally so omitted fields stay off the wire.
-        // The pointer-vs-empty distinction on allowed_hosts is preserved by
-        // treating `null` as "omit" — same as the server's nil semantics —
-        // so callers threading a possibly-unset slice don't accidentally
-        // send `allowed_hosts: null` (which JSON-decodes to a deny-all on
-        // some implementations).
-        const body = {
-            agent: opts.agent,
-            segments: opts.segments,
-        };
-        if (opts.allowedTools !== undefined)
-            body.allowed_tools = opts.allowedTools;
-        if (opts.allowedHosts !== undefined && opts.allowedHosts !== null) {
-            body.allowed_hosts = opts.allowedHosts;
-        }
-        if (opts.webSearchFilter !== undefined)
-            body.web_search_filter = opts.webSearchFilter;
-        if (opts.sessionId !== undefined)
-            body.session_id = opts.sessionId;
-        if (opts.tenantId !== undefined)
-            body.tenant_id = opts.tenantId;
-        if (opts.userId !== undefined)
-            body.user_id = opts.userId;
-        if (opts.agentId !== undefined)
-            body.agent_id = opts.agentId;
-        if (opts.userTier !== undefined)
-            body.user_tier = opts.userTier;
-        if (opts.userBearer !== undefined)
-            body.user_bearer = opts.userBearer;
-        if (opts.userCredentials !== undefined)
-            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);
+        yield* this.streamSSE("/v1/runs", runBody(opts), opts.signal, opts.debug);
     }
     /**
      * Continue an existing session with a new run. The session's prior
@@ -141,8 +185,52 @@ class LoomcycleClient {
             body.metadata = opts.metadata;
         if (opts.runTimeoutSeconds !== undefined)
             body.run_timeout_seconds = opts.runTimeoutSeconds;
+        if (opts.sampling !== undefined)
+            body.sampling = samplingToWire(opts.sampling);
+        if (opts.compaction !== undefined)
+            body.compaction = compactionToWire(opts.compaction);
         yield* this.streamSSE(`/v1/sessions/${encodeURIComponent(opts.sessionId)}/messages`, body, opts.signal, opts.debug);
     }
+    /**
+     * Spawn N fresh runs concurrently in ONE call (RFC Y external fan-out) and
+     * resolve once they ALL settle, returning the combined index-aligned
+     * envelope. A per-child failure is captured in that child's result
+     * (`status` + `error`) and never rejects the batch. Prefer this over firing
+     * N parallel {@link LoomcycleClient.runStreaming} calls.
+     *
+     * Each spawn is a fresh run (its `sessionId` is ignored). Capped at 32 —
+     * an over-cap batch rejects with InvalidArgumentError. `mode: "detach"`
+     * (async handles) is reserved for a future release and rejected today.
+     *
+     * Blocking: resolves only when the slowest child finishes (or `timeoutMs`
+     * elapses). Mirrors POST /v1/runs:batch.
+     */
+    async spawnRunBatch(opts) {
+        const body = {
+            spawns: opts.spawns.map(runBody),
+        };
+        if (opts.mode !== undefined)
+            body.mode = opts.mode;
+        if (opts.timeoutMs !== undefined)
+            body.timeout_ms = opts.timeoutMs;
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/runs:batch", body, {
+            signal: opts.signal,
+        });
+    }
+    /**
+     * Compact a run's conversation: summarize the history to free context and
+     * continue from the summary. Targets the run by `runId`. A live run must be
+     * PARKED (awaiting input) — a mid-turn run rejects (RunBusyError / 409).
+     * Returns `{ compacted, before_tokens, after_tokens, applied }`, where
+     * `applied` is "live", "marker", or "noop". Mirrors
+     * POST /v1/runs/{run_id}/compact.
+     */
+    async compactRun(runId, opts) {
+        const body = {};
+        if (opts?.reason !== undefined)
+            body.reason = opts.reason;
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, `/v1/runs/${encodeURIComponent(runId)}/compact`, body, opts);
+    }
     // ---- Agent metadata ----
     /** Read one agent's status + usage stats. Raises AgentNotFoundError
      *  when the agent_id is unknown. */

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, EnsureCodeAgentOptions, EnsureCodeAgentResult, EnsureMcpServerOptions, EnsureMcpServerResult, HealthResponse, Hook, InterruptListResponse, InterruptStatus, AckChannelOptions, AwaitChannelsOptions, BroadcastChannelsOptions, ChannelAckResult, ChannelAwaitResult, ChannelBroadcastResult, ChannelDescriptor, ChannelPeekResult, ChannelPublishResult, ChannelPurgeResult, 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, AwaitChannelsOptions, BroadcastChannelsOptions, ChannelAckResult, ChannelAwaitResult, ChannelBroadcastResult, ChannelDescriptor, ChannelPeekResult, ChannelPublishResult, ChannelPurgeResult, 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, CompactRunResult, RunBatchOptions, RunBatchResult, RunOptions, RunStateStreamItem, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, StreamUserRunStatesOptions, SubstrateToolInput, SubstrateToolResponse, TranscriptResponse, WhoamiResponse } from "./types.js";
 export declare class LoomcycleClient {
     private ctx;
     constructor(opts?: ClientOptions);
@@ -67,6 +67,33 @@ export declare class LoomcycleClient {
      * `_meta` open/close events.
      */
     continueSession(opts: ContinueOptions): AsyncIterable<AgentEvent>;
+    /**
+     * Spawn N fresh runs concurrently in ONE call (RFC Y external fan-out) and
+     * resolve once they ALL settle, returning the combined index-aligned
+     * envelope. A per-child failure is captured in that child's result
+     * (`status` + `error`) and never rejects the batch. Prefer this over firing
+     * N parallel {@link LoomcycleClient.runStreaming} calls.
+     *
+     * Each spawn is a fresh run (its `sessionId` is ignored). Capped at 32 —
+     * an over-cap batch rejects with InvalidArgumentError. `mode: "detach"`
+     * (async handles) is reserved for a future release and rejected today.
+     *
+     * Blocking: resolves only when the slowest child finishes (or `timeoutMs`
+     * elapses). Mirrors POST /v1/runs:batch.
+     */
+    spawnRunBatch(opts: RunBatchOptions): Promise<RunBatchResult>;
+    /**
+     * Compact a run's conversation: summarize the history to free context and
+     * continue from the summary. Targets the run by `runId`. A live run must be
+     * PARKED (awaiting input) — a mid-turn run rejects (RunBusyError / 409).
+     * Returns `{ compacted, before_tokens, after_tokens, applied }`, where
+     * `applied` is "live", "marker", or "noop". Mirrors
+     * POST /v1/runs/{run_id}/compact.
+     */
+    compactRun(runId: string, opts?: {
+        reason?: string;
+        signal?: AbortSignal;
+    }): Promise<CompactRunResult>;
     /** Read one agent's status + usage stats. Raises AgentNotFoundError
      *  when the agent_id is unknown. */
     getAgent(agentId: string, opts?: {

package/dist/client.js

@@ -25,6 +25,87 @@
  */
 import { authHeaders, deleteRequest, jsonFetch, patchJSON, postJSON, putJSON, raiseFromResponse, } from "./fetch-helpers.js";
 import { parseSSE } from "./stream.js";
+/** samplingToWire maps the camelCase SamplingOptions to the snake_case wire
+ *  object, omitting unset fields so they inherit the agent's value. */
+function samplingToWire(s) {
+    const w = {};
+    if (s.temperature !== undefined)
+        w.temperature = s.temperature;
+    if (s.topP !== undefined)
+        w.top_p = s.topP;
+    if (s.topK !== undefined)
+        w.top_k = s.topK;
+    if (s.frequencyPenalty !== undefined)
+        w.frequency_penalty = s.frequencyPenalty;
+    if (s.presencePenalty !== undefined)
+        w.presence_penalty = s.presencePenalty;
+    if (s.seed !== undefined)
+        w.seed = s.seed;
+    if (s.stop !== undefined)
+        w.stop = s.stop;
+    return w;
+}
+/** compactionToWire maps the camelCase CompactionOptions to the snake_case
+ *  wire object, omitting unset fields so they inherit the agent's value. */
+function compactionToWire(c) {
+    const w = {};
+    if (c.enabled !== undefined)
+        w.enabled = c.enabled;
+    if (c.targetPercentage !== undefined)
+        w.target_percentage = c.targetPercentage;
+    if (c.keepLastN !== undefined)
+        w.keep_last_n = c.keepLastN;
+    if (c.keepFirst !== undefined)
+        w.keep_first = c.keepFirst;
+    if (c.autocompactAtPct !== undefined)
+        w.autocompact_at_pct = c.autocompactAtPct;
+    if (c.model !== undefined)
+        w.model = c.model;
+    return w;
+}
+/** runBody builds the snake_case /v1/runs request body from RunOptions,
+ *  omitting unset fields (preserves the server's nil semantics — notably
+ *  `allowedHosts: null` is treated as "omit", not deny-all). Shared by
+ *  runStreaming and each spawn of spawnRunBatch. `signal`/`debug` are client
+ *  concerns and never sent. */
+function runBody(opts) {
+    const body = {
+        agent: opts.agent,
+        segments: opts.segments,
+    };
+    if (opts.allowedTools !== undefined)
+        body.allowed_tools = opts.allowedTools;
+    if (opts.allowedHosts !== undefined && opts.allowedHosts !== null) {
+        body.allowed_hosts = opts.allowedHosts;
+    }
+    if (opts.webSearchFilter !== undefined)
+        body.web_search_filter = opts.webSearchFilter;
+    if (opts.sessionId !== undefined)
+        body.session_id = opts.sessionId;
+    if (opts.tenantId !== undefined)
+        body.tenant_id = opts.tenantId;
+    if (opts.userId !== undefined)
+        body.user_id = opts.userId;
+    if (opts.agentId !== undefined)
+        body.agent_id = opts.agentId;
+    if (opts.userTier !== undefined)
+        body.user_tier = opts.userTier;
+    if (opts.userBearer !== undefined)
+        body.user_bearer = opts.userBearer;
+    if (opts.userCredentials !== undefined)
+        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;
+    if (opts.sampling !== undefined)
+        body.sampling = samplingToWire(opts.sampling);
+    if (opts.compaction !== undefined)
+        body.compaction = compactionToWire(opts.compaction);
+    return body;
+}
 export class LoomcycleClient {
     ctx;
     constructor(opts = {}) {
@@ -57,44 +138,7 @@ export class LoomcycleClient {
      * events around the real frames. Silent (default) when omitted.
      */
     async *runStreaming(opts) {
-        // Build the body conditionally so omitted fields stay off the wire.
-        // The pointer-vs-empty distinction on allowed_hosts is preserved by
-        // treating `null` as "omit" — same as the server's nil semantics —
-        // so callers threading a possibly-unset slice don't accidentally
-        // send `allowed_hosts: null` (which JSON-decodes to a deny-all on
-        // some implementations).
-        const body = {
-            agent: opts.agent,
-            segments: opts.segments,
-        };
-        if (opts.allowedTools !== undefined)
-            body.allowed_tools = opts.allowedTools;
-        if (opts.allowedHosts !== undefined && opts.allowedHosts !== null) {
-            body.allowed_hosts = opts.allowedHosts;
-        }
-        if (opts.webSearchFilter !== undefined)
-            body.web_search_filter = opts.webSearchFilter;
-        if (opts.sessionId !== undefined)
-            body.session_id = opts.sessionId;
-        if (opts.tenantId !== undefined)
-            body.tenant_id = opts.tenantId;
-        if (opts.userId !== undefined)
-            body.user_id = opts.userId;
-        if (opts.agentId !== undefined)
-            body.agent_id = opts.agentId;
-        if (opts.userTier !== undefined)
-            body.user_tier = opts.userTier;
-        if (opts.userBearer !== undefined)
-            body.user_bearer = opts.userBearer;
-        if (opts.userCredentials !== undefined)
-            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);
+        yield* this.streamSSE("/v1/runs", runBody(opts), opts.signal, opts.debug);
     }
     /**
      * Continue an existing session with a new run. The session's prior
@@ -138,8 +182,52 @@ export class LoomcycleClient {
             body.metadata = opts.metadata;
         if (opts.runTimeoutSeconds !== undefined)
             body.run_timeout_seconds = opts.runTimeoutSeconds;
+        if (opts.sampling !== undefined)
+            body.sampling = samplingToWire(opts.sampling);
+        if (opts.compaction !== undefined)
+            body.compaction = compactionToWire(opts.compaction);
         yield* this.streamSSE(`/v1/sessions/${encodeURIComponent(opts.sessionId)}/messages`, body, opts.signal, opts.debug);
     }
+    /**
+     * Spawn N fresh runs concurrently in ONE call (RFC Y external fan-out) and
+     * resolve once they ALL settle, returning the combined index-aligned
+     * envelope. A per-child failure is captured in that child's result
+     * (`status` + `error`) and never rejects the batch. Prefer this over firing
+     * N parallel {@link LoomcycleClient.runStreaming} calls.
+     *
+     * Each spawn is a fresh run (its `sessionId` is ignored). Capped at 32 —
+     * an over-cap batch rejects with InvalidArgumentError. `mode: "detach"`
+     * (async handles) is reserved for a future release and rejected today.
+     *
+     * Blocking: resolves only when the slowest child finishes (or `timeoutMs`
+     * elapses). Mirrors POST /v1/runs:batch.
+     */
+    async spawnRunBatch(opts) {
+        const body = {
+            spawns: opts.spawns.map(runBody),
+        };
+        if (opts.mode !== undefined)
+            body.mode = opts.mode;
+        if (opts.timeoutMs !== undefined)
+            body.timeout_ms = opts.timeoutMs;
+        return postJSON(this.ctx, "/v1/runs:batch", body, {
+            signal: opts.signal,
+        });
+    }
+    /**
+     * Compact a run's conversation: summarize the history to free context and
+     * continue from the summary. Targets the run by `runId`. A live run must be
+     * PARKED (awaiting input) — a mid-turn run rejects (RunBusyError / 409).
+     * Returns `{ compacted, before_tokens, after_tokens, applied }`, where
+     * `applied` is "live", "marker", or "noop". Mirrors
+     * POST /v1/runs/{run_id}/compact.
+     */
+    async compactRun(runId, opts) {
+        const body = {};
+        if (opts?.reason !== undefined)
+            body.reason = opts.reason;
+        return postJSON(this.ctx, `/v1/runs/${encodeURIComponent(runId)}/compact`, body, opts);
+    }
     // ---- Agent metadata ----
     /** Read one agent's status + usage stats. Raises AgentNotFoundError
      *  when the agent_id is unknown. */

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, ChannelPurgeResult, ChannelScope, ChannelSubscribeResult, PeekChannelOptions, PublishChannelOptions, SubscribeChannelOptions, AwaitChannelsOptions, BroadcastChannelsOptions, ChannelAwaitEntry, ChannelAwaitMode, ChannelAwaitResult, ChannelBroadcastEntry, ChannelBroadcastResult, 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 type { AgentEvent, ClientOptions, ContinueOptions, EventType, HostWidening, ParentContext, PromptContent, PromptSegment, RetryInfo, RunOptions, SamplingOptions, CompactionOptions, ToolUse, Usage, Agent, AgentStatus, AgentUsage, CancelAgentResult, ListAgentsResponse, RunBatchOptions, RunBatchResult, SpawnRunResult, CompactRunResult, 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, ChannelPurgeResult, ChannelScope, ChannelSubscribeResult, PeekChannelOptions, PublishChannelOptions, SubscribeChannelOptions, AwaitChannelsOptions, BroadcastChannelsOptions, ChannelAwaitEntry, ChannelAwaitMode, ChannelAwaitResult, ChannelBroadcastEntry, ChannelBroadcastResult, 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

@@ -168,6 +168,15 @@ export interface RunOptions {
      *  its budget spans that wait, so the CPU-oriented default is often too low.
      *  Ignored by LLM agents. 0 / omitted = inherit. */
     runTimeoutSeconds?: number;
+    /** Per-run LLM sampling override (v0.28.0), merged PER FIELD over the
+     *  agent's own sampling (this wins; unset fields inherit). Omitted =
+     *  inherit entirely. */
+    sampling?: SamplingOptions;
+    /** Per-run context-compaction override (v0.32.0), merged PER FIELD over
+     *  the agent's own compaction block (this wins; unset fields inherit).
+     *  Omitted = inherit entirely. Trigger compaction mid-run with
+     *  {@link LoomcycleClient.compactRun}. */
+    compaction?: CompactionOptions;
     /** 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
@@ -178,6 +187,38 @@ export interface RunOptions {
     debug?: boolean;
     signal?: AbortSignal;
 }
+/** Per-run LLM sampling override (v0.28.0). Mirrors config.Sampling — every
+ *  field optional; an unset field inherits the agent's value. An explicit
+ *  `temperature: 0` is deterministic, NOT "unset". Each provider maps what it
+ *  supports (e.g. topK is Anthropic/Gemini/Ollama; frequencyPenalty/
+ *  presencePenalty/seed are OpenAI/DeepSeek/Ollama). */
+export interface SamplingOptions {
+    temperature?: number;
+    topP?: number;
+    topK?: number;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    seed?: number;
+    stop?: string[];
+}
+/** Per-run context-compaction override (v0.32.0). Mirrors config.Compaction —
+ *  every field optional; an unset field inherits the agent's value. */
+export interface CompactionOptions {
+    /** Turn AUTO-compaction on for this run (default off). */
+    enabled?: boolean;
+    /** Summary aims for ~N% of the compacted span's length (10..50; default 10). */
+    targetPercentage?: number;
+    /** Keep the last N messages verbatim (default 4; 0 = summarize all). */
+    keepLastN?: number;
+    /** Pin the first user message (the task) verbatim (default true). */
+    keepFirst?: boolean;
+    /** Auto-compact when used/window ≥ N% (50..95; default 80; only when
+     *  enabled + the provider reports a context window). */
+    autocompactAtPct?: number;
+    /** Run the summary call on a cheaper/faster model served by the SAME
+     *  provider. Omitted = the run's model. */
+    model?: string;
+}
 /** Opaque caller-tracking lineage (v0.12.x) attached to a run and
  *  propagated to all its sub-agents. The runtime stores and echoes
  *  these fields verbatim and never interprets them. All fields
@@ -234,6 +275,10 @@ export interface ContinueOptions {
     /** Optional ad-hoc per-run code-js wall-clock budget (seconds) for the
      *  continuation's new run — see {@link RunOptions.runTimeoutSeconds}. */
     runTimeoutSeconds?: number;
+    /** Per-continuation LLM sampling override — see {@link RunOptions.sampling}. */
+    sampling?: SamplingOptions;
+    /** Per-continuation context-compaction override — see {@link RunOptions.compaction}. */
+    compaction?: CompactionOptions;
     /** Opt-in observability: see {@link RunOptions.debug}. Same shape. */
     debug?: boolean;
     signal?: AbortSignal;
@@ -292,6 +337,51 @@ export interface CancelAgentResult {
      *  terminated; the call still succeeds (idempotent contract). */
     cancelledCount: number;
 }
+/** Options for {@link LoomcycleClient.spawnRunBatch} — the RFC Y external
+ *  fan-out. Each spawn is a fresh-run {@link RunOptions} (its `sessionId` is
+ *  ignored — batch children never continue a session; `signal`/`debug` are
+ *  per-call client concerns and not sent). Capped at 32; the server rejects an
+ *  over-cap batch. */
+export interface RunBatchOptions {
+    spawns: RunOptions[];
+    /** "join" (default) — block until all children settle, returning the
+     *  combined envelope. "detach" (async run handles) is reserved for a future
+     *  release and rejected by the server today. */
+    mode?: "join";
+    /** Optional join deadline (ms): a child still running when it elapses is
+     *  cancelled and reported with a cancelled status in-envelope. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}
+/** One child run's outcome in a batch. Mirrors the server's SpawnResult wire
+ *  shape; a per-child failure is reported via `status` + `error`, never as a
+ *  thrown error (the batch as a whole still resolves). */
+export interface SpawnRunResult {
+    agent_id: string;
+    run_id: string;
+    session_id: string;
+    status: AgentStatus;
+    stop_reason?: string;
+    final_text?: string;
+    usage?: AgentUsage;
+    error?: string;
+}
+/** Result of {@link LoomcycleClient.spawnRunBatch} — `results` is index-aligned
+ *  with the request's `spawns`. */
+export interface RunBatchResult {
+    results: SpawnRunResult[];
+    spawned: number;
+}
+/** Result of {@link LoomcycleClient.compactRun}. `applied` is "live" (pushed to
+ *  the running loop), "marker" (persisted for a terminal run's next
+ *  continuation), or "noop" (too short to compact). */
+export interface CompactRunResult {
+    run_id: string;
+    compacted: boolean;
+    before_tokens: number;
+    after_tokens: number;
+    applied: "live" | "marker" | "noop";
+}
 /** TranscriptEvent — one persisted store.Event from
  *  GET /v1/sessions/{id}/transcript. The server wraps each
  *  providers.Event in {seq, run_id, ts_ns, type, event:{...}}.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loomcycle/client",
-  "version": "0.29.1",
-  "description": "TypeScript client for the loomcycle sidecar (HTTP+SSE). 52 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. v0.22.0 — version-aligned lockstep release; no client-surface change (RFC N tenant isolation of the agent/skill/MCP/Schedule/Webhook definition plane + real op-schemas on the builtin MCP meta-tools are both server-side). v0.23.0 — version-aligned lockstep release; no client-surface change (RFCs O/P/R MCP-server hardening + thin client and the RFC Q DeepSeek tool-content fix are all server-side / MCP-transport-side). v0.24.0 — purgeChannel clears a channel's buffered messages without deleting its definition (allowed on yaml-declared channels too, unlike deleteChannel — F20); AgentDefOverlay gains channels / evaluation_scopes / interruption so a COMPLETE interactive/multi-agent agent round-trips over the substrate (F14). (Consolidates the interim 0.24/0.25 package bumps, which were never tag-published, back into lockstep with the loomcycle v0.24.0 tag.) v0.25.0 — adds the RFC S channel fan-in/fan-out client twins: awaitChannels() (wait for any/all/at_least N messages across channels, or a timeout — non-committing) + broadcastChannels() (publish one payload to N channels in one atomic-pre-flight call), the client-facing counterparts of the in-band Channel.await / Channel.broadcast tool ops (the rest of v0.25.0 — the manual-management Web UI console + Context op=time + max_fires self-retiring schedules — is server-side / in-band, no client-surface change). v0.29.1 — Usage gains optional `max_context_tokens` (the serving model's context-window ceiling, stamped by the loop from Provider.Capabilities() on each usage event) so a consumer can render a 'context used / max' gauge without a hard-coded per-model table; additive + optional, no behavior change. (Lockstep catch-up: the field landed in loomcycle v0.29.0 but the adapter publish skipped on a version mismatch; v0.29.1 realigns the package version with the release tag so it publishes.)",
+  "version": "0.33.0",
+  "description": "TypeScript client for the loomcycle sidecar (HTTP+SSE). 54 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. v0.22.0 — version-aligned lockstep release; no client-surface change (RFC N tenant isolation of the agent/skill/MCP/Schedule/Webhook definition plane + real op-schemas on the builtin MCP meta-tools are both server-side). v0.23.0 — version-aligned lockstep release; no client-surface change (RFCs O/P/R MCP-server hardening + thin client and the RFC Q DeepSeek tool-content fix are all server-side / MCP-transport-side). v0.24.0 — purgeChannel clears a channel's buffered messages without deleting its definition (allowed on yaml-declared channels too, unlike deleteChannel — F20); AgentDefOverlay gains channels / evaluation_scopes / interruption so a COMPLETE interactive/multi-agent agent round-trips over the substrate (F14). (Consolidates the interim 0.24/0.25 package bumps, which were never tag-published, back into lockstep with the loomcycle v0.24.0 tag.) v0.25.0 — adds the RFC S channel fan-in/fan-out client twins: awaitChannels() (wait for any/all/at_least N messages across channels, or a timeout — non-committing) + broadcastChannels() (publish one payload to N channels in one atomic-pre-flight call), the client-facing counterparts of the in-band Channel.await / Channel.broadcast tool ops (the rest of v0.25.0 — the manual-management Web UI console + Context op=time + max_fires self-retiring schedules — is server-side / in-band, no client-surface change). v0.29.1 — Usage gains optional `max_context_tokens` (the serving model's context-window ceiling, stamped by the loop from Provider.Capabilities() on each usage event) so a consumer can render a 'context used / max' gauge without a hard-coded per-model table; additive + optional, no behavior change. (Lockstep catch-up: the field landed in loomcycle v0.29.0 but the adapter publish skipped on a version mismatch; v0.29.1 realigns the package version with the release tag so it publishes.) v0.33.0 — gRPC + TS client parity for the RFC Y external fan-out and the compaction surface: spawnRunBatch() (POST /v1/runs:batch — spawn up to 32 fresh runs concurrently in one call, combined index-aligned envelope, per-child failures in-envelope) + compactRun(runId) (POST /v1/runs/{run_id}/compact — summarize a parked run's context); plus per-run sampling + compaction overrides now accepted on runStreaming / continueSession (an explicit temperature 0 is preserved as deterministic, not dropped as falsy). (The gRPC half adds the matching SpawnRunBatch / CompactRun RPCs + the sampling/compaction fields on RunRequest/ContinueRequest — server-side.)",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {