@loomcycle/client 0.8.20 → 0.9.0

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, ListUsersResponse, MemoryEntriesResponse, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopesResponse, PauseResult, RegisterHookOptions, RegisterHookResponse, ResolveInterruptOptions, ResumeResult, RunOptions, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, TranscriptResponse } from "./types.js";
+import type { Agent, AgentEvent, AgentStatus, CancelAgentResult, ClientOptions, ContinueOptions, CreateSnapshotOptions, HealthResponse, Hook, InterruptListResponse, InterruptStatus, ListUsersResponse, MemoryEntriesResponse, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopesResponse, PauseResult, RegisterHookOptions, RegisterHookResponse, ResolveInterruptOptions, ResumeResult, RunOptions, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, SubstrateToolInput, SubstrateToolResponse, TranscriptResponse } from "./types.js";
 export declare class LoomcycleClient {
     private ctx;
     constructor(opts?: ClientOptions);
@@ -207,6 +207,32 @@ export declare class LoomcycleClient {
     deleteHook(id: string, opts?: {
         signal?: AbortSignal;
     }): Promise<void>;
+    /** Invoke the AgentDef substrate tool over HTTP. Mirrors the
+     *  MCP `agentdef` meta-tool and the in-band agent tool_use of
+     *  the same name — different transport, identical semantics.
+     *
+     *  The `input.op` field discriminates create / fork / get /
+     *  list / promote / retire. The remaining fields are op-specific;
+     *  see the in-process tool's documentation.
+     *
+     *  Raises {@link SubstrateToolRefusedError} when the tool itself
+     *  refuses the call (scope deny, empty body, allowed-tools
+     *  widening, etc.) — distinct from transport failures so callers
+     *  can branch on the typed error class.
+     *
+     *  Raises {@link InvalidArgumentError} on 400 (malformed JSON
+     *  body); {@link AuthError} on 401; {@link UnavailableError} on
+     *  503 (store / connector unwired). */
+    agentDef(input: SubstrateToolInput, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SubstrateToolResponse>;
+    /** Invoke the SkillDef substrate tool over HTTP. Mirror of
+     *  {@link LoomcycleClient.agentDef} for skills (v0.8.22+). Same
+     *  input grammar, same error class on refusal. See the
+     *  agentDef() doc for the full shape and error contract. */
+    skillDef(input: SubstrateToolInput, opts?: {
+        signal?: AbortSignal;
+    }): Promise<SubstrateToolResponse>;
     /** Shared SSE POST → stream-of-AgentEvent path. Used by
      *  runStreaming + continueSession. */
     private streamSSE;

package/dist/client.js

@@ -333,6 +333,33 @@ export class LoomcycleClient {
     async deleteHook(id, opts) {
         await deleteRequest(this.ctx, `/v1/hooks/${encodeURIComponent(id)}`, opts);
     }
+    // ---- v0.8.22 substrate admin (AgentDef + SkillDef) ----
+    /** Invoke the AgentDef substrate tool over HTTP. Mirrors the
+     *  MCP `agentdef` meta-tool and the in-band agent tool_use of
+     *  the same name — different transport, identical semantics.
+     *
+     *  The `input.op` field discriminates create / fork / get /
+     *  list / promote / retire. The remaining fields are op-specific;
+     *  see the in-process tool's documentation.
+     *
+     *  Raises {@link SubstrateToolRefusedError} when the tool itself
+     *  refuses the call (scope deny, empty body, allowed-tools
+     *  widening, etc.) — distinct from transport failures so callers
+     *  can branch on the typed error class.
+     *
+     *  Raises {@link InvalidArgumentError} on 400 (malformed JSON
+     *  body); {@link AuthError} on 401; {@link UnavailableError} on
+     *  503 (store / connector unwired). */
+    async agentDef(input, opts) {
+        return postJSON(this.ctx, "/v1/_agentdef", input, opts);
+    }
+    /** Invoke the SkillDef substrate tool over HTTP. Mirror of
+     *  {@link LoomcycleClient.agentDef} for skills (v0.8.22+). Same
+     *  input grammar, same error class on refusal. See the
+     *  agentDef() doc for the full shape and error contract. */
+    async skillDef(input, opts) {
+        return postJSON(this.ctx, "/v1/_skilldef", input, opts);
+    }
     // ---- Internal helpers ----
     /** Shared SSE POST → stream-of-AgentEvent path. Used by
      *  runStreaming + continueSession. */

package/dist/errors.d.ts

@@ -133,3 +133,22 @@ export declare class HookNotFoundError extends NotFoundError {
         bodyText?: string;
     });
 }
+/** SubstrateToolRefusedError — raised by `client.agentDef()` /
+ *  `client.skillDef()` when the in-process tool refused the call
+ *  (scope deny, empty body, allowed-tools widening, etc.). HTTP
+ *  status 422 with `{code: "tool_refused", error, tool}` body.
+ *
+ *  Distinct from transport failures: the request reached the
+ *  server, the substrate tool ran, and the tool itself returned
+ *  IsError=true. Operators catching this error should surface the
+ *  reason in `message` to the calling agent / user rather than
+ *  retrying. */
+export declare class SubstrateToolRefusedError extends LoomcycleError {
+    /** Which substrate tool refused — "AgentDef" or "SkillDef". */
+    readonly tool: string;
+    constructor(message: string, opts?: {
+        status?: number;
+        bodyText?: string;
+        tool?: string;
+    });
+}

package/dist/errors.js

@@ -136,3 +136,22 @@ export class HookNotFoundError extends NotFoundError {
         this.name = "HookNotFoundError";
     }
 }
+/** SubstrateToolRefusedError — raised by `client.agentDef()` /
+ *  `client.skillDef()` when the in-process tool refused the call
+ *  (scope deny, empty body, allowed-tools widening, etc.). HTTP
+ *  status 422 with `{code: "tool_refused", error, tool}` body.
+ *
+ *  Distinct from transport failures: the request reached the
+ *  server, the substrate tool ran, and the tool itself returned
+ *  IsError=true. Operators catching this error should surface the
+ *  reason in `message` to the calling agent / user rather than
+ *  retrying. */
+export class SubstrateToolRefusedError extends LoomcycleError {
+    /** Which substrate tool refused — "AgentDef" or "SkillDef". */
+    tool;
+    constructor(message, opts) {
+        super(message, opts);
+        this.name = "SubstrateToolRefusedError";
+        this.tool = opts?.tool ?? "";
+    }
+}

package/dist/fetch-helpers.js

@@ -9,7 +9,7 @@
  * Method-level code in client.ts stays focused on URL + body shape;
  * the boring fetch + error-translation machinery lives here.
  */
-import { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, HookNotFoundError, InvalidArgumentError, LoomcycleError, NotFoundError, NotPausedError, PauseNotConfiguredError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, UnavailableError, } from "./errors.js";
+import { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, HookNotFoundError, InvalidArgumentError, LoomcycleError, NotFoundError, NotPausedError, PauseNotConfiguredError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, UnavailableError, } from "./errors.js";
 /** authHeaders builds the standard request header set: JSON Accept
  *  + Bearer token when the client was constructed with one. The
  *  caller adds Content-Type when posting a body. */
@@ -164,8 +164,25 @@ export async function raiseFromResponse(resp) {
             throw new LoomcycleError(msg, opts);
         case 413:
             throw new SnapshotTooLargeError(msg, opts);
-        case 422:
+        case 422: {
+            // 422 is shared between snapshot version errors (existing)
+            // and v0.8.22 substrate tool refusals. Discriminate by body:
+            // the substrate path returns `{code: "tool_refused", tool,
+            // error}` JSON; the snapshot path returns a free-form text.
+            try {
+                const parsed = JSON.parse(bodyText);
+                if (parsed.code === "tool_refused") {
+                    throw new SubstrateToolRefusedError(parsed.error ?? msg, { status, bodyText, tool: parsed.tool });
+                }
+            }
+            catch (e) {
+                // Re-throw our typed error if we matched; fall through to
+                // SnapshotVersionError on any JSON-parse failure.
+                if (e instanceof SubstrateToolRefusedError)
+                    throw e;
+            }
             throw new SnapshotVersionError(msg, opts);
+        }
         case 429:
             throw new BackpressureError(msg, opts);
         case 503:

package/dist/index.d.ts

@@ -42,6 +42,10 @@
  *     listRunInterrupts(runId, opts?): Promise<InterruptListResponse>
  *     resolveInterrupt(runId, interruptId, opts): Promise<unknown>
  *
+ *     // Substrate admin (v0.8.22)
+ *     agentDef(input): Promise<SubstrateToolResponse>
+ *     skillDef(input): Promise<SubstrateToolResponse>
+ *
  *   Errors (typed subclasses of LoomcycleError; see README for the
  *   full HTTP-status → typed-error mapping table):
  *     LoomcycleError, AgentNotFoundError, SessionNotFoundError,
@@ -49,7 +53,8 @@
  *     AuthError, UnavailableError, InvalidArgumentError,
  *     PauseNotConfiguredError (subclass of UnavailableError),
  *     AlreadyPausingError, NotPausedError, SnapshotNotFoundError,
- *     SnapshotTooLargeError, SnapshotVersionError
+ *     SnapshotTooLargeError, SnapshotVersionError,
+ *     SubstrateToolRefusedError (v0.8.22)
  *
  * Transport: HTTP+SSE. Auth: Bearer token via the Authorization
  * header. Designed for Node ≥18 (engines pinned); Bun/Deno likely
@@ -59,5 +64,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, } from "./types.js";
-export { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, HookNotFoundError, NotFoundError, InvalidArgumentError, LoomcycleError, NotPausedError, PauseNotConfiguredError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, UnavailableError, } from "./errors.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, } from "./types.js";
+export { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, HookNotFoundError, NotFoundError, InvalidArgumentError, LoomcycleError, NotPausedError, PauseNotConfiguredError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, UnavailableError, } from "./errors.js";

package/dist/index.js

@@ -42,6 +42,10 @@
  *     listRunInterrupts(runId, opts?): Promise<InterruptListResponse>
  *     resolveInterrupt(runId, interruptId, opts): Promise<unknown>
  *
+ *     // Substrate admin (v0.8.22)
+ *     agentDef(input): Promise<SubstrateToolResponse>
+ *     skillDef(input): Promise<SubstrateToolResponse>
+ *
  *   Errors (typed subclasses of LoomcycleError; see README for the
  *   full HTTP-status → typed-error mapping table):
  *     LoomcycleError, AgentNotFoundError, SessionNotFoundError,
@@ -49,7 +53,8 @@
  *     AuthError, UnavailableError, InvalidArgumentError,
  *     PauseNotConfiguredError (subclass of UnavailableError),
  *     AlreadyPausingError, NotPausedError, SnapshotNotFoundError,
- *     SnapshotTooLargeError, SnapshotVersionError
+ *     SnapshotTooLargeError, SnapshotVersionError,
+ *     SubstrateToolRefusedError (v0.8.22)
  *
  * Transport: HTTP+SSE. Auth: Bearer token via the Authorization
  * header. Designed for Node ≥18 (engines pinned); Bun/Deno likely
@@ -59,4 +64,4 @@
  * See `adapters/ts/README.md` for usage examples.
  */
 export { LoomcycleClient } from "./client.js";
-export { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, HookNotFoundError, NotFoundError, InvalidArgumentError, LoomcycleError, NotPausedError, PauseNotConfiguredError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, UnavailableError, } from "./errors.js";
+export { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, HookNotFoundError, NotFoundError, InvalidArgumentError, LoomcycleError, NotPausedError, PauseNotConfiguredError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, UnavailableError, } from "./errors.js";

package/dist/types.d.ts

@@ -472,6 +472,31 @@ export interface PostHookCall {
     tool_call: HookToolCall;
     tool_result: HookToolResult;
 }
+/** Input shape for {@link LoomcycleClient.agentDef} and
+ *  {@link LoomcycleClient.skillDef}. Mirrors the in-process tool
+ *  input — `op` discriminates create / fork / get / list / promote
+ *  / retire and the remaining fields are op-specific.
+ *
+ *  Typed loosely because the in-process tool owns the full schema;
+ *  the adapter doesn't re-validate. Use the optional `extra` index
+ *  signature for forward-compat fields. */
+export type SubstrateToolInput = {
+    op: "create" | "fork" | "get" | "list" | "promote" | "retire";
+    name?: string;
+    def_id?: string;
+    parent_def_id?: string;
+    overlay?: Record<string, unknown>;
+    description?: string;
+    promote?: boolean;
+    retired?: boolean;
+    [extra: string]: unknown;
+};
+/** Response shape for {@link LoomcycleClient.agentDef} and
+ *  {@link LoomcycleClient.skillDef}. `unknown` because the shape
+ *  varies per op — create/fork return a row envelope, list returns
+ *  `{name, versions: [...]}`, promote/retire return summary shapes.
+ *  Callers narrow as needed. */
+export type SubstrateToolResponse = unknown;
 /** Response a Post webhook returns. When result is omitted the tool
  *  result passes through unchanged. */
 export interface PostHookResult {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loomcycle/client",
-  "version": "0.8.20",
-  "description": "TypeScript client for the loomcycle sidecar (HTTP+SSE). 27 methods covering run streaming, agent metadata, pause/resume/state, snapshot lifecycle, memory admin, interruption resolve, and hook management.",
+  "version": "0.9.0",
+  "description": "TypeScript client for the loomcycle sidecar (HTTP+SSE). 29 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, and v0.8.22 substrate admin (agentDef + skillDef).",
   "license": "Apache-2.0",
   "type": "module",
   "repository": {