@loomcycle/client 0.12.7 → 0.13.0

package/dist/cjs/client.js

@@ -91,6 +91,8 @@ class LoomcycleClient {
             body.user_bearer = opts.userBearer;
         if (opts.userCredentials !== undefined)
             body.user_credentials = opts.userCredentials;
+        if (opts.parentContext !== undefined)
+            body.parent_context = opts.parentContext;
         yield* this.streamSSE("/v1/runs", body, opts.signal, opts.debug);
     }
     /**
@@ -129,6 +131,8 @@ class LoomcycleClient {
             body.user_bearer = opts.userBearer;
         if (opts.userCredentials !== undefined)
             body.user_credentials = opts.userCredentials;
+        if (opts.parentContext !== undefined)
+            body.parent_context = opts.parentContext;
         yield* this.streamSSE(`/v1/sessions/${encodeURIComponent(opts.sessionId)}/messages`, body, opts.signal, opts.debug);
     }
     // ---- Agent metadata ----
@@ -458,6 +462,36 @@ class LoomcycleClient {
     async scheduleDef(input, opts) {
         return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_scheduledef", input, opts);
     }
+    /** Invoke the v1.x RFC G A2AServerCardDef substrate tool over HTTP.
+     *  Author + fork + retire A2A server-card definitions at runtime.
+     *  Mirror of {@link LoomcycleClient.scheduleDef} for A2A server cards.
+     *
+     *  Operator-admin-only: this endpoint requires the bearer token.
+     *
+     *  Op-discriminated input: `{op: "create" | "fork" | "get" |
+     *  "list" | "retire", ...}`.
+     *
+     *  Raises {@link SubstrateToolRefusedError} on tool-level refusals;
+     *  {@link InvalidArgumentError} on 400 (malformed JSON);
+     *  {@link AuthError} on 401. */
+    async a2aServerCardDef(input, opts) {
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_a2aservercarddef", input, opts);
+    }
+    /** Invoke the v1.x RFC G A2AAgentDef substrate tool over HTTP.
+     *  Author + fork + retire A2A agent definitions at runtime.
+     *  Mirror of {@link LoomcycleClient.scheduleDef} for A2A agents.
+     *
+     *  Operator-admin-only: this endpoint requires the bearer token.
+     *
+     *  Op-discriminated input: `{op: "create" | "fork" | "get" |
+     *  "list" | "retire", ...}`.
+     *
+     *  Raises {@link SubstrateToolRefusedError} on tool-level refusals;
+     *  {@link InvalidArgumentError} on 400 (malformed JSON);
+     *  {@link AuthError} on 401. */
+    async a2aAgentDef(input, opts) {
+        return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_a2aagentdef", input, opts);
+    }
     // ---- v0.10.3 Library v2 enumeration (read-only, merged yaml+substrate) ----
     /** List every agent the runtime knows about — yaml-static + dynamic
      *  AgentDefs merged into one envelope per name. Each entry carries

package/dist/client.d.ts

@@ -321,6 +321,36 @@ export declare class LoomcycleClient {
     scheduleDef(input: SubstrateToolInput, opts?: {
         signal?: AbortSignal;
     }): Promise<SubstrateToolResponse>;
+    /** Invoke the v1.x RFC G A2AServerCardDef substrate tool over HTTP.
+     *  Author + fork + retire A2A server-card definitions at runtime.
+     *  Mirror of {@link LoomcycleClient.scheduleDef} for A2A server cards.
+     *
+     *  Operator-admin-only: this endpoint requires the bearer token.
+     *
+     *  Op-discriminated input: `{op: "create" | "fork" | "get" |
+     *  "list" | "retire", ...}`.
+     *
+     *  Raises {@link SubstrateToolRefusedError} on tool-level refusals;
+     *  {@link InvalidArgumentError} on 400 (malformed JSON);
+     *  {@link AuthError} on 401. */
+    a2aServerCardDef(input: SubstrateToolInput, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SubstrateToolResponse>;
+    /** Invoke the v1.x RFC G A2AAgentDef substrate tool over HTTP.
+     *  Author + fork + retire A2A agent definitions at runtime.
+     *  Mirror of {@link LoomcycleClient.scheduleDef} for A2A agents.
+     *
+     *  Operator-admin-only: this endpoint requires the bearer token.
+     *
+     *  Op-discriminated input: `{op: "create" | "fork" | "get" |
+     *  "list" | "retire", ...}`.
+     *
+     *  Raises {@link SubstrateToolRefusedError} on tool-level refusals;
+     *  {@link InvalidArgumentError} on 400 (malformed JSON);
+     *  {@link AuthError} on 401. */
+    a2aAgentDef(input: SubstrateToolInput, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SubstrateToolResponse>;
     /** List every agent the runtime knows about — yaml-static + dynamic
      *  AgentDefs merged into one envelope per name. Each entry carries
      *  `source: "static-only" | "dynamic-only" | "both"` so callers can

package/dist/client.js

@@ -88,6 +88,8 @@ export class LoomcycleClient {
             body.user_bearer = opts.userBearer;
         if (opts.userCredentials !== undefined)
             body.user_credentials = opts.userCredentials;
+        if (opts.parentContext !== undefined)
+            body.parent_context = opts.parentContext;
         yield* this.streamSSE("/v1/runs", body, opts.signal, opts.debug);
     }
     /**
@@ -126,6 +128,8 @@ export class LoomcycleClient {
             body.user_bearer = opts.userBearer;
         if (opts.userCredentials !== undefined)
             body.user_credentials = opts.userCredentials;
+        if (opts.parentContext !== undefined)
+            body.parent_context = opts.parentContext;
         yield* this.streamSSE(`/v1/sessions/${encodeURIComponent(opts.sessionId)}/messages`, body, opts.signal, opts.debug);
     }
     // ---- Agent metadata ----
@@ -455,6 +459,36 @@ export class LoomcycleClient {
     async scheduleDef(input, opts) {
         return postJSON(this.ctx, "/v1/_scheduledef", input, opts);
     }
+    /** Invoke the v1.x RFC G A2AServerCardDef substrate tool over HTTP.
+     *  Author + fork + retire A2A server-card definitions at runtime.
+     *  Mirror of {@link LoomcycleClient.scheduleDef} for A2A server cards.
+     *
+     *  Operator-admin-only: this endpoint requires the bearer token.
+     *
+     *  Op-discriminated input: `{op: "create" | "fork" | "get" |
+     *  "list" | "retire", ...}`.
+     *
+     *  Raises {@link SubstrateToolRefusedError} on tool-level refusals;
+     *  {@link InvalidArgumentError} on 400 (malformed JSON);
+     *  {@link AuthError} on 401. */
+    async a2aServerCardDef(input, opts) {
+        return postJSON(this.ctx, "/v1/_a2aservercarddef", input, opts);
+    }
+    /** Invoke the v1.x RFC G A2AAgentDef substrate tool over HTTP.
+     *  Author + fork + retire A2A agent definitions at runtime.
+     *  Mirror of {@link LoomcycleClient.scheduleDef} for A2A agents.
+     *
+     *  Operator-admin-only: this endpoint requires the bearer token.
+     *
+     *  Op-discriminated input: `{op: "create" | "fork" | "get" |
+     *  "list" | "retire", ...}`.
+     *
+     *  Raises {@link SubstrateToolRefusedError} on tool-level refusals;
+     *  {@link InvalidArgumentError} on 400 (malformed JSON);
+     *  {@link AuthError} on 401. */
+    async a2aAgentDef(input, opts) {
+        return postJSON(this.ctx, "/v1/_a2aagentdef", input, opts);
+    }
     // ---- v0.10.3 Library v2 enumeration (read-only, merged yaml+substrate) ----
     /** List every agent the runtime knows about — yaml-static + dynamic
      *  AgentDefs merged into one envelope per name. Each entry carries

package/dist/index.d.ts

@@ -78,5 +78,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, CreateChannelOptions, UpdateChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, AgentDefRowResponse, AgentDefVerifyResult, SkillDefVerifyResult, MCPServerDefRowResponse, MCPServerDefVerifyResult, LibraryAgentDefinition, LibraryEntry, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, LLMChatContent, LLMChatMessage, LLMChatOptions, LLMChatResponse, LLMChatStreamDelta, LLMChatStreamItem, LLMChatToolCall, LLMChatUsage, LLMTool, LLMEmbeddingItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, LLMEmbeddingsUsage, } from "./types.js";
+export type { AgentEvent, ClientOptions, ContinueOptions, EventType, HostWidening, ParentContext, PromptContent, PromptSegment, RetryInfo, RunOptions, ToolUse, Usage, Agent, AgentStatus, AgentUsage, CancelAgentResult, ListAgentsResponse, TranscriptEvent, TranscriptResponse, HealthResponse, ListUsersResponse, UserSummary, 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, CreateChannelOptions, UpdateChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, AgentDefRowResponse, AgentDefVerifyResult, SkillDefVerifyResult, MCPServerDefRowResponse, MCPServerDefVerifyResult, LibraryAgentDefinition, LibraryEntry, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, LLMChatContent, LLMChatMessage, LLMChatOptions, LLMChatResponse, LLMChatStreamDelta, LLMChatStreamItem, LLMChatToolCall, LLMChatUsage, LLMTool, LLMEmbeddingItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, LLMEmbeddingsUsage, } from "./types.js";
 export { 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

@@ -69,6 +69,7 @@ export interface AgentEvent {
     run_id?: string;
     session_id?: string;
     parent_agent_id?: string | null;
+    parent_context?: ParentContext;
     meta_subtype?: "stream_open" | "stream_close";
     meta_reason?: string;
 }
@@ -139,6 +140,14 @@ export interface RunOptions {
      *  field auto-promotes to `userCredentials.default` for back-compat
      *  with v0.8.x flows. Never persisted; never logged. */
     userCredentials?: Record<string, string>;
+    /** Opaque caller-tracking lineage (v0.12.x). Carried verbatim by the
+     *  runtime, inherited UNCHANGED by every sub-agent the Agent tool
+     *  spawns, persisted on each run row, and echoed back on the per-agent
+     *  report surfaces (agent status, run-state stream, the `event: agent`
+     *  frame) — so you can attribute a child sub-agent's usage to the
+     *  user-initiated request that spawned the whole tree. Not a secret.
+     *  Omitted = no tracking context. */
+    parentContext?: ParentContext;
     /** 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
@@ -149,6 +158,20 @@ export interface RunOptions {
     debug?: boolean;
     signal?: AbortSignal;
 }
+/** 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
+ *  optional; an all-empty object is treated as absent. */
+export interface ParentContext {
+    /** The consumer's identifier for the user-initiated run at the root of
+     *  the spawn tree — echoed on every descendant. */
+    root_agent_run_id?: string;
+    /** The consumer's logical-operation key for the root request. */
+    function_key?: string;
+    /** The consumer's tier marker captured at root-run time (distinct from
+     *  `userTier`, which is loomcycle's resolver policy). */
+    tier_at_run?: string;
+}
 export interface ContinueOptions {
     /** Required — the session to continue. */
     sessionId: string;
@@ -179,6 +202,10 @@ export interface ContinueOptions {
      *  {@link RunOptions.userCredentials} for the full shape — same
      *  semantics, supplied per-continuation rather than per-fresh-run. */
     userCredentials?: Record<string, string>;
+    /** Opaque caller-tracking lineage (v0.12.x). See
+     *  {@link RunOptions.parentContext} — same shape; a continuation may
+     *  (re)set the lineage for the new run it creates. */
+    parentContext?: ParentContext;
     /** Opt-in observability: see {@link RunOptions.debug}. Same shape. */
     debug?: boolean;
     signal?: AbortSignal;
@@ -222,6 +249,11 @@ export interface Agent {
     usage: AgentUsage;
     last_heartbeat_at: string | null;
     live: boolean;
+    /** Opaque caller-tracking lineage this run carries (inherited from its
+     *  root for sub-agents), v0.12.x. Echoed here alongside `usage` so you
+     *  can attribute a child sub-agent's cost to the user-initiated request
+     *  in a single fetch. Omitted when the run carried no context. */
+    parent_context?: ParentContext;
 }
 export interface ListAgentsResponse {
     agents: Agent[];
@@ -744,6 +776,10 @@ export interface RunStateEvent {
     stop_reason?: string;
     error?: string;
     ts: string;
+    /** Opaque caller-tracking lineage echoed on the transition (v0.12.x),
+     *  so a subscriber learns which root request a finishing sub-agent
+     *  belongs to. Omitted when the run carried no context. */
+    parent_context?: ParentContext;
 }
 /** Initial stream_open frame emitted before the first run_state. */
 export interface RunStateStreamOpen {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loomcycle/client",
-  "version": "0.12.7",
+  "version": "0.13.0",
   "description": "TypeScript client for the loomcycle sidecar (HTTP+SSE). 46 methods covering run streaming, agent metadata, pause/resume/state, 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).",
   "license": "Apache-2.0",
   "type": "module",