@loomcycle/client 1.99.0 → 1.101.0

package/README.md

@@ -139,8 +139,10 @@ The low-level primitives (`runStreaming({interactive:true})` + `sendRunInput` +
 | Method | Returns | Notes |
 |---|---|---|
 | `getAgent(agentId)` | `Promise<Agent>` | One agent's status + usage. Raises `AgentNotFoundError` if unknown. |
+| `getRun(runId)` | `Promise<Agent>` | One run by its run id — `getAgent`'s shape. Use it when an agent id names several runs (every walk of a team is `team:<name>`). Raises `NotFoundError` if unknown. |
 | `cancelAgent(agentId, opts?)` | `Promise<{ cancelledCount: number }>` | Cascades to children via `parent_agent_id`. Idempotent. |
 | `listUserAgents(userId, opts?)` | `Promise<Agent[]>` | Optional filter by status (`running` / `completed` / `failed` / `cancelled`). |
+| `listWalkRuns(walkId, { limit?, cursor? })` | `Promise<WalkRunsPage>` | One page of a team walk's runs — its own run and every member, oldest first: `{ agents, next_cursor }`. Pass `next_cursor` back as `cursor`; `""` on the last page. `limit` defaults to 100, at most 1000. Raises `NotFoundError` for a walk you cannot read. |
 | `getTranscript(sessionId)` | `Promise<TranscriptResponse>` | Persisted event log; one row per event with seq/run_id/ts_ns/type/event. |
 | `health()` | `Promise<HealthResponse>` | Liveness probe. Hits `/healthz` (no `/v1` prefix). Unauthenticated. |
 | `getConfig(opts?)` | `Promise<ConfigResponse>` | v1.38.0 — instance configuration: build identity, the feature matrix, and the live provider/model/search cascade with `active`/`selected`. `view` names the disclosure level (`public` / `authenticated` / `admin`). Also readable with **no bearer** against a deployment running `LOOMCYCLE_PUBLIC_CONFIG=1`, which serves the narrower `public` view — the landing-page case. |

package/dist/cjs/client.js

@@ -146,11 +146,6 @@ function runBody(opts) {
         body.tool_hooks = opts.toolHooks;
     if (opts.sampling !== undefined)
         body.sampling = samplingToWire(opts.sampling);
-    // Same keys on the wire as in the option (mode / name / until).
-    if (opts.toolChoice !== undefined)
-        body.tool_choice = opts.toolChoice;
-    if (opts.outputFormat !== undefined)
-        body.output_format = opts.outputFormat;
     if (opts.compaction !== undefined)
         body.compaction = compactionToWire(opts.compaction);
     if (opts.context !== undefined)
@@ -206,6 +201,11 @@ function applyOverridesToWire(body, opts) {
         body.interruption = opts.interruption;
     if (opts.review !== undefined)
         body.review = opts.review;
+    // Same keys on the wire as in the option (mode / name / until).
+    if (opts.toolChoice !== undefined)
+        body.tool_choice = opts.toolChoice;
+    if (opts.outputFormat !== undefined)
+        body.output_format = opts.outputFormat;
 }
 class LoomcycleClient {
     ctx;
@@ -291,10 +291,6 @@ class LoomcycleClient {
             body.tool_hooks = opts.toolHooks;
         if (opts.sampling !== undefined)
             body.sampling = samplingToWire(opts.sampling);
-        if (opts.toolChoice !== undefined)
-            body.tool_choice = opts.toolChoice;
-        if (opts.outputFormat !== undefined)
-            body.output_format = opts.outputFormat;
         if (opts.compaction !== undefined)
             body.compaction = compactionToWire(opts.compaction);
         if (opts.context !== undefined)
@@ -655,6 +651,14 @@ class LoomcycleClient {
     async getAgent(agentId, opts) {
         return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, `/v1/agents/${encodeURIComponent(agentId)}`, opts);
     }
+    /** Read one run by its run id — the same {@link Agent} shape as
+     *  {@link getAgent}. An agent id can name many runs (every walk of a team
+     *  is filed under `team:<name>`, which getAgent cannot address) and
+     *  getAgent answers the latest; a run id names one. Raises NotFoundError
+     *  for an unknown run, or one the caller may not see. */
+    async getRun(runId, opts) {
+        return (0, fetch_helpers_js_1.jsonFetch)(this.ctx, `/v1/runs/${encodeURIComponent(runId)}`, opts);
+    }
     /** Cancel a live agent (cascades to children via parent_agent_id).
      *  Returns count of agents cancelled. Idempotent — already-terminated
      *  agents return 0. */
@@ -683,6 +687,21 @@ class LoomcycleClient {
         }
         return all;
     }
+    /** One page of a team walk's runs — the walk's own run (its run id IS the
+     *  walk id) and every member it spawned, oldest first. Pass the page's
+     *  `next_cursor` back as `cursor` for the next one; it is "" on the last.
+     *  `limit` defaults to 100, at most 1000. Mirrors
+     *  `GET /v1/runs?walk_id=`. Raises NotFoundError for an unknown walk, or
+     *  one the caller may not see. */
+    async listWalkRuns(walkId, opts) {
+        const params = new URLSearchParams({ walk_id: walkId });
+        if (opts?.limit !== undefined)
+            params.set("limit", String(opts.limit));
+        if (opts?.cursor)
+            params.set("cursor", opts.cursor);
+        const resp = await (0, fetch_helpers_js_1.jsonFetch)(this.ctx, `/v1/runs?${params.toString()}`, opts);
+        return { agents: resp.agents ?? [], next_cursor: resp.next_cursor ?? "" };
+    }
     /** Aggregated token-usage + cost report (RFC AV). Group by any of
      *  tenant/user/provider/model/source over an optional time window; group by
      *  `source` for the operator-vs-tenant split. Tenant-scoped server-side: a
@@ -1514,7 +1533,8 @@ class LoomcycleClient {
         return (0, fetch_helpers_js_1.postJSON)(this.ctx, "/v1/_teamdef", body, opts);
     }
     /** Read the debug breakpoints armed on a live team walk
-     *  (`GET /v1/runs/{run_id}/breakpoints`).
+     *  (`GET /v1/runs/{run_id}/breakpoints`), and the review deadline its
+     *  member holds get (`review_ttl_seconds`, 0 = none).
      *
      *  404 when no walk is in flight under that run on this replica — loudly,
      *  because an arming that appeared to succeed and then never paused anything
@@ -1531,15 +1551,33 @@ class LoomcycleClient {
      *  off switch. A malformed entry is refused whole and leaves the previous
      *  arming exactly as it was.
      *
-     *  Each entry is a starter state id — `"wave"` (or `"wave:before_dispatch"`)
-     *  pauses the state before it dispatches, and `"wave:review"` holds its member
-     *  runs for a verdict ({@link LoomcycleClient.reviewRun}). An arm takes effect
-     *  at the next point the walk reaches; disarming RELEASES whatever is still
-     *  pending rather than stranding it.
-     *
-     *  A pause is read and answered through the run's interrupts. */
+     *  `"wave"` (or `"wave:before_dispatch"`) pauses a starter state before it
+     *  dispatches, and `"<state>:review"` holds the member runs of a starter,
+     *  agent or parallel state for a verdict ({@link LoomcycleClient.reviewRun}).
+     *  An arm takes effect at the next point the walk reaches; disarming
+     *  RELEASES whatever is still pending rather than stranding it.
+     *
+     *  Each state is checked against the walk's own team, as it is when the run
+     *  starts: an entry naming a state the team does not have, a pause on a
+     *  state that is not a starter, or review on a consolidator or a state that
+     *  runs no member, is refused with 400 `invalid_breakpoint` and the previous
+     *  arming is kept — rather than armed and silently never hit.
+     *
+     *  A pause is read and answered through the run's interrupts.
+     *
+     *  `opts.reviewTtlSeconds` also replaces the walk's review deadline — a
+     *  member hold nobody rules on within it ends rejected; `0` is no deadline.
+     *  Omit it to leave the deadline as it is. It applies from each member's
+     *  NEXT hold: a hold already in progress keeps the `expires_at` it
+     *  announced. A negative or out-of-range value is refused with 400
+     *  `invalid_review_ttl`, and so is the set sent with it. Like the
+     *  breakpoints, it lives only as long as the walk; a member restored after
+     *  a restart keeps the deadline it started with. */
     async setRunBreakpoints(runId, breakpoints, opts) {
-        return (0, fetch_helpers_js_1.putJSON)(this.ctx, `/v1/runs/${encodeURIComponent(runId)}/breakpoints`, { breakpoints }, opts);
+        const body = { breakpoints };
+        if (opts?.reviewTtlSeconds !== undefined)
+            body.review_ttl_seconds = opts.reviewTtlSeconds;
+        return (0, fetch_helpers_js_1.putJSON)(this.ctx, `/v1/runs/${encodeURIComponent(runId)}/breakpoints`, body, { signal: opts?.signal });
     }
     /** Invoke the RFC AL Path VFS tool over HTTP (`POST /v1/_path`). A
      *  Unix-like filesystem over your Memory entries, Volume mounts, and

package/dist/cjs/index.js

@@ -13,8 +13,10 @@
  *
  *     // Agent metadata
  *     getAgent(agentId): Promise<Agent>
+ *     getRun(runId): Promise<Agent>
  *     cancelAgent(agentId, opts?): Promise<CancelAgentResult>
  *     listUserAgents(userId, opts?): Promise<Agent[]>
+ *     listWalkRuns(walkId, opts?): Promise<WalkRunsPage>
  *     getTranscript(sessionId): Promise<TranscriptResponse>
  *     health(): Promise<HealthResponse>
  *     listUsers(opts?): Promise<ListUsersResponse>   // tenant-scoped (RFC L)

package/dist/client.d.ts

@@ -25,7 +25,7 @@
  */
 import { InteractiveSession } from "./interactive.js";
 import { ClientToolHost, type ConnectClientToolsOptions } from "./client-tools.js";
-import type { CredentialListResponse, CredentialMeta, CredentialScope, DirectoryInspection, DirectoryTenant, DirectoryUser, ErasureReport, ErasureResult, Agent, AgentEvent, AgentStatus, CancelAgentResult, ClientOptions, ContinueOptions, RunOverrideOptions, EffectiveConfigResponse, RetuneRunResponse, RunConfigResponse, RunPromptResponse, CreateSnapshotOptions, EnsureCodeAgentOptions, EnsureCodeAgentResult, EnsureMcpServerOptions, EnsureMcpServerResult, HealthResponse, InterruptListResponse, InterruptStatus, AckChannelOptions, AwaitChannelsOptions, BroadcastChannelsOptions, ChannelAckResult, ChannelAwaitResult, ChannelBroadcastResult, ChannelDescriptor, ChannelPeekResult, ChannelPublishResult, ChannelPurgeResult, ChannelReleaseResult, ChannelSubscribeResult, CreateChannelOptions, ListChannelsResponse, PeekChannelOptions, PublishChannelOptions, ReleaseChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, SubscribeChannelOptions, UpdateChannelOptions, LibraryAgentDefinition, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, ListUsersResponse, UserRecord, CreateUserBody, UpdateUserBody, MintedUserToken, ListUserTokensResponse, RunnableAgentsResponse, LLMChatOptions, LLMChatResponse, LLMChatStreamItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, MCPServerDefVerifyResult, MemoryEmbedStatsResponse, MemoryEntriesResponse, MemoryEntryResponse, MemoryBackfillResponse, MemoryPurgeResponse, MemoryReembedResponse, MemoryScopeIDsResponse, MemoryScopesResponse, MemorySearchInput, MemorySearchResponse, PauseResult, PersistentVolumesResponse, EphemeralVolumesResponse, ResolveInterruptOptions, ResumeResult, ResolverMatrix, CompactRunResult, ReplaySessionResult, CancelTurnResult, ReviewRunResult, RunBatchOptions, RunBatchResult, RunOptions, ConfiguredRun, ConfiguredRunPatch, RunStateStreamItem, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, StreamUserRunStatesOptions, SubstrateToolInput, SubstrateToolResponse, CreatedTeam, ListTeamsResponse, PromotedTeam, RetiredTeam, TeamBreakpoints, TeamDefDetail, TeamRunDetached, TeamRunTarget, TeamVerification, TeamVersionList, TeamDiagram, TeamRunResult, PathToolInput, PathToolResponse, DocumentToolInput, DocumentToolResponse, HistoryToolInput, HistoryToolResponse, TranscriptResponse, WhoamiResponse, UsageDimension, UsageReportResponse, TokenLimit, TokenLimitsResponse, ConfigResponse, SetTokenLimitRequest } from "./types.js";
+import type { CredentialListResponse, CredentialMeta, CredentialScope, DirectoryInspection, DirectoryTenant, DirectoryUser, ErasureReport, ErasureResult, Agent, AgentEvent, AgentStatus, CancelAgentResult, ClientOptions, ContinueOptions, RunOverrideOptions, EffectiveConfigResponse, RetuneRunResponse, RunConfigResponse, RunPromptResponse, CreateSnapshotOptions, EnsureCodeAgentOptions, EnsureCodeAgentResult, EnsureMcpServerOptions, EnsureMcpServerResult, HealthResponse, InterruptListResponse, InterruptStatus, WalkRunsPage, AckChannelOptions, AwaitChannelsOptions, BroadcastChannelsOptions, ChannelAckResult, ChannelAwaitResult, ChannelBroadcastResult, ChannelDescriptor, ChannelPeekResult, ChannelPublishResult, ChannelPurgeResult, ChannelReleaseResult, ChannelSubscribeResult, CreateChannelOptions, ListChannelsResponse, PeekChannelOptions, PublishChannelOptions, ReleaseChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, SubscribeChannelOptions, UpdateChannelOptions, LibraryAgentDefinition, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, ListUsersResponse, UserRecord, CreateUserBody, UpdateUserBody, MintedUserToken, ListUserTokensResponse, RunnableAgentsResponse, LLMChatOptions, LLMChatResponse, LLMChatStreamItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, MCPServerDefVerifyResult, MemoryEmbedStatsResponse, MemoryEntriesResponse, MemoryEntryResponse, MemoryBackfillResponse, MemoryPurgeResponse, MemoryReembedResponse, MemoryScopeIDsResponse, MemoryScopesResponse, MemorySearchInput, MemorySearchResponse, PauseResult, PersistentVolumesResponse, EphemeralVolumesResponse, ResolveInterruptOptions, ResumeResult, ResolverMatrix, CompactRunResult, ReplaySessionResult, CancelTurnResult, ReviewRunResult, RunBatchOptions, RunBatchResult, RunOptions, ConfiguredRun, ConfiguredRunPatch, RunStateStreamItem, RuntimeStateResponse, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotRestoreResponse, StreamUserRunStatesOptions, SubstrateToolInput, SubstrateToolResponse, CreatedTeam, ListTeamsResponse, PromotedTeam, RetiredTeam, TeamBreakpoints, TeamDefDetail, TeamRunDetached, TeamRunTarget, TeamVerification, TeamVersionList, TeamDiagram, TeamRunResult, PathToolInput, PathToolResponse, DocumentToolInput, DocumentToolResponse, HistoryToolInput, HistoryToolResponse, TranscriptResponse, WhoamiResponse, UsageDimension, UsageReportResponse, TokenLimit, TokenLimitsResponse, ConfigResponse, SetTokenLimitRequest } from "./types.js";
 export declare class LoomcycleClient {
     private ctx;
     constructor(opts?: ClientOptions);
@@ -360,6 +360,14 @@ export declare class LoomcycleClient {
     getAgent(agentId: string, opts?: {
         signal?: AbortSignal;
     }): Promise<Agent>;
+    /** Read one run by its run id — the same {@link Agent} shape as
+     *  {@link getAgent}. An agent id can name many runs (every walk of a team
+     *  is filed under `team:<name>`, which getAgent cannot address) and
+     *  getAgent answers the latest; a run id names one. Raises NotFoundError
+     *  for an unknown run, or one the caller may not see. */
+    getRun(runId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Agent>;
     /** Cancel a live agent (cascades to children via parent_agent_id).
      *  Returns count of agents cancelled. Idempotent — already-terminated
      *  agents return 0. */
@@ -382,6 +390,17 @@ export declare class LoomcycleClient {
         tenant?: string;
         signal?: AbortSignal;
     }): Promise<Agent[]>;
+    /** One page of a team walk's runs — the walk's own run (its run id IS the
+     *  walk id) and every member it spawned, oldest first. Pass the page's
+     *  `next_cursor` back as `cursor` for the next one; it is "" on the last.
+     *  `limit` defaults to 100, at most 1000. Mirrors
+     *  `GET /v1/runs?walk_id=`. Raises NotFoundError for an unknown walk, or
+     *  one the caller may not see. */
+    listWalkRuns(walkId: string, opts?: {
+        limit?: number;
+        cursor?: string;
+        signal?: AbortSignal;
+    }): Promise<WalkRunsPage>;
     /** Aggregated token-usage + cost report (RFC AV). Group by any of
      *  tenant/user/provider/model/source over an optional time window; group by
      *  `source` for the operator-vs-tenant split. Tenant-scoped server-side: a
@@ -1026,7 +1045,8 @@ export declare class LoomcycleClient {
         signal?: AbortSignal;
     }): Promise<TeamRunResult>;
     /** Read the debug breakpoints armed on a live team walk
-     *  (`GET /v1/runs/{run_id}/breakpoints`).
+     *  (`GET /v1/runs/{run_id}/breakpoints`), and the review deadline its
+     *  member holds get (`review_ttl_seconds`, 0 = none).
      *
      *  404 when no walk is in flight under that run on this replica — loudly,
      *  because an arming that appeared to succeed and then never paused anything
@@ -1043,15 +1063,31 @@ export declare class LoomcycleClient {
      *  off switch. A malformed entry is refused whole and leaves the previous
      *  arming exactly as it was.
      *
-     *  Each entry is a starter state id — `"wave"` (or `"wave:before_dispatch"`)
-     *  pauses the state before it dispatches, and `"wave:review"` holds its member
-     *  runs for a verdict ({@link LoomcycleClient.reviewRun}). An arm takes effect
-     *  at the next point the walk reaches; disarming RELEASES whatever is still
-     *  pending rather than stranding it.
-     *
-     *  A pause is read and answered through the run's interrupts. */
+     *  `"wave"` (or `"wave:before_dispatch"`) pauses a starter state before it
+     *  dispatches, and `"<state>:review"` holds the member runs of a starter,
+     *  agent or parallel state for a verdict ({@link LoomcycleClient.reviewRun}).
+     *  An arm takes effect at the next point the walk reaches; disarming
+     *  RELEASES whatever is still pending rather than stranding it.
+     *
+     *  Each state is checked against the walk's own team, as it is when the run
+     *  starts: an entry naming a state the team does not have, a pause on a
+     *  state that is not a starter, or review on a consolidator or a state that
+     *  runs no member, is refused with 400 `invalid_breakpoint` and the previous
+     *  arming is kept — rather than armed and silently never hit.
+     *
+     *  A pause is read and answered through the run's interrupts.
+     *
+     *  `opts.reviewTtlSeconds` also replaces the walk's review deadline — a
+     *  member hold nobody rules on within it ends rejected; `0` is no deadline.
+     *  Omit it to leave the deadline as it is. It applies from each member's
+     *  NEXT hold: a hold already in progress keeps the `expires_at` it
+     *  announced. A negative or out-of-range value is refused with 400
+     *  `invalid_review_ttl`, and so is the set sent with it. Like the
+     *  breakpoints, it lives only as long as the walk; a member restored after
+     *  a restart keeps the deadline it started with. */
     setRunBreakpoints(runId: string, breakpoints: string[], opts?: {
         signal?: AbortSignal;
+        reviewTtlSeconds?: number;
     }): Promise<TeamBreakpoints>;
     /** Invoke the RFC AL Path VFS tool over HTTP (`POST /v1/_path`). A
      *  Unix-like filesystem over your Memory entries, Volume mounts, and

package/dist/client.js

@@ -143,11 +143,6 @@ function runBody(opts) {
         body.tool_hooks = opts.toolHooks;
     if (opts.sampling !== undefined)
         body.sampling = samplingToWire(opts.sampling);
-    // Same keys on the wire as in the option (mode / name / until).
-    if (opts.toolChoice !== undefined)
-        body.tool_choice = opts.toolChoice;
-    if (opts.outputFormat !== undefined)
-        body.output_format = opts.outputFormat;
     if (opts.compaction !== undefined)
         body.compaction = compactionToWire(opts.compaction);
     if (opts.context !== undefined)
@@ -203,6 +198,11 @@ function applyOverridesToWire(body, opts) {
         body.interruption = opts.interruption;
     if (opts.review !== undefined)
         body.review = opts.review;
+    // Same keys on the wire as in the option (mode / name / until).
+    if (opts.toolChoice !== undefined)
+        body.tool_choice = opts.toolChoice;
+    if (opts.outputFormat !== undefined)
+        body.output_format = opts.outputFormat;
 }
 export class LoomcycleClient {
     ctx;
@@ -288,10 +288,6 @@ export class LoomcycleClient {
             body.tool_hooks = opts.toolHooks;
         if (opts.sampling !== undefined)
             body.sampling = samplingToWire(opts.sampling);
-        if (opts.toolChoice !== undefined)
-            body.tool_choice = opts.toolChoice;
-        if (opts.outputFormat !== undefined)
-            body.output_format = opts.outputFormat;
         if (opts.compaction !== undefined)
             body.compaction = compactionToWire(opts.compaction);
         if (opts.context !== undefined)
@@ -652,6 +648,14 @@ export class LoomcycleClient {
     async getAgent(agentId, opts) {
         return jsonFetch(this.ctx, `/v1/agents/${encodeURIComponent(agentId)}`, opts);
     }
+    /** Read one run by its run id — the same {@link Agent} shape as
+     *  {@link getAgent}. An agent id can name many runs (every walk of a team
+     *  is filed under `team:<name>`, which getAgent cannot address) and
+     *  getAgent answers the latest; a run id names one. Raises NotFoundError
+     *  for an unknown run, or one the caller may not see. */
+    async getRun(runId, opts) {
+        return jsonFetch(this.ctx, `/v1/runs/${encodeURIComponent(runId)}`, opts);
+    }
     /** Cancel a live agent (cascades to children via parent_agent_id).
      *  Returns count of agents cancelled. Idempotent — already-terminated
      *  agents return 0. */
@@ -680,6 +684,21 @@ export class LoomcycleClient {
         }
         return all;
     }
+    /** One page of a team walk's runs — the walk's own run (its run id IS the
+     *  walk id) and every member it spawned, oldest first. Pass the page's
+     *  `next_cursor` back as `cursor` for the next one; it is "" on the last.
+     *  `limit` defaults to 100, at most 1000. Mirrors
+     *  `GET /v1/runs?walk_id=`. Raises NotFoundError for an unknown walk, or
+     *  one the caller may not see. */
+    async listWalkRuns(walkId, opts) {
+        const params = new URLSearchParams({ walk_id: walkId });
+        if (opts?.limit !== undefined)
+            params.set("limit", String(opts.limit));
+        if (opts?.cursor)
+            params.set("cursor", opts.cursor);
+        const resp = await jsonFetch(this.ctx, `/v1/runs?${params.toString()}`, opts);
+        return { agents: resp.agents ?? [], next_cursor: resp.next_cursor ?? "" };
+    }
     /** Aggregated token-usage + cost report (RFC AV). Group by any of
      *  tenant/user/provider/model/source over an optional time window; group by
      *  `source` for the operator-vs-tenant split. Tenant-scoped server-side: a
@@ -1511,7 +1530,8 @@ export class LoomcycleClient {
         return postJSON(this.ctx, "/v1/_teamdef", body, opts);
     }
     /** Read the debug breakpoints armed on a live team walk
-     *  (`GET /v1/runs/{run_id}/breakpoints`).
+     *  (`GET /v1/runs/{run_id}/breakpoints`), and the review deadline its
+     *  member holds get (`review_ttl_seconds`, 0 = none).
      *
      *  404 when no walk is in flight under that run on this replica — loudly,
      *  because an arming that appeared to succeed and then never paused anything
@@ -1528,15 +1548,33 @@ export class LoomcycleClient {
      *  off switch. A malformed entry is refused whole and leaves the previous
      *  arming exactly as it was.
      *
-     *  Each entry is a starter state id — `"wave"` (or `"wave:before_dispatch"`)
-     *  pauses the state before it dispatches, and `"wave:review"` holds its member
-     *  runs for a verdict ({@link LoomcycleClient.reviewRun}). An arm takes effect
-     *  at the next point the walk reaches; disarming RELEASES whatever is still
-     *  pending rather than stranding it.
-     *
-     *  A pause is read and answered through the run's interrupts. */
+     *  `"wave"` (or `"wave:before_dispatch"`) pauses a starter state before it
+     *  dispatches, and `"<state>:review"` holds the member runs of a starter,
+     *  agent or parallel state for a verdict ({@link LoomcycleClient.reviewRun}).
+     *  An arm takes effect at the next point the walk reaches; disarming
+     *  RELEASES whatever is still pending rather than stranding it.
+     *
+     *  Each state is checked against the walk's own team, as it is when the run
+     *  starts: an entry naming a state the team does not have, a pause on a
+     *  state that is not a starter, or review on a consolidator or a state that
+     *  runs no member, is refused with 400 `invalid_breakpoint` and the previous
+     *  arming is kept — rather than armed and silently never hit.
+     *
+     *  A pause is read and answered through the run's interrupts.
+     *
+     *  `opts.reviewTtlSeconds` also replaces the walk's review deadline — a
+     *  member hold nobody rules on within it ends rejected; `0` is no deadline.
+     *  Omit it to leave the deadline as it is. It applies from each member's
+     *  NEXT hold: a hold already in progress keeps the `expires_at` it
+     *  announced. A negative or out-of-range value is refused with 400
+     *  `invalid_review_ttl`, and so is the set sent with it. Like the
+     *  breakpoints, it lives only as long as the walk; a member restored after
+     *  a restart keeps the deadline it started with. */
     async setRunBreakpoints(runId, breakpoints, opts) {
-        return putJSON(this.ctx, `/v1/runs/${encodeURIComponent(runId)}/breakpoints`, { breakpoints }, opts);
+        const body = { breakpoints };
+        if (opts?.reviewTtlSeconds !== undefined)
+            body.review_ttl_seconds = opts.reviewTtlSeconds;
+        return putJSON(this.ctx, `/v1/runs/${encodeURIComponent(runId)}/breakpoints`, body, { signal: opts?.signal });
     }
     /** Invoke the RFC AL Path VFS tool over HTTP (`POST /v1/_path`). A
      *  Unix-like filesystem over your Memory entries, Volume mounts, and

package/dist/index.d.ts

@@ -12,8 +12,10 @@
  *
  *     // Agent metadata
  *     getAgent(agentId): Promise<Agent>
+ *     getRun(runId): Promise<Agent>
  *     cancelAgent(agentId, opts?): Promise<CancelAgentResult>
  *     listUserAgents(userId, opts?): Promise<Agent[]>
+ *     listWalkRuns(walkId, opts?): Promise<WalkRunsPage>
  *     getTranscript(sessionId): Promise<TranscriptResponse>
  *     health(): Promise<HealthResponse>
  *     listUsers(opts?): Promise<ListUsersResponse>   // tenant-scoped (RFC L)
@@ -128,5 +130,5 @@ export { InteractiveSession } from "./interactive.js";
 export type { InteractiveSessionOps } from "./interactive.js";
 export { ClientToolHost, clientToolsURL, CLIENT_TOOL_SUBPROTOCOL } from "./client-tools.js";
 export type { ClientToolSchema, ClientToolInvocation, ConnectClientToolsOptions, WebSocketLike, WebSocketCtor, } from "./client-tools.js";
-export type { AgentEvent, ClientOptions, ContinueOptions, EventType, HostWidening, ImageMediaType, ParentContext, PromptContent, PromptSegment, RetryInfo, RunOptions, SamplingOptions, CompactionOptions, ContextOptions, ToolUse, Usage, Agent, AgentStatus, AgentUsage, RunResult, RunSpec, ConfiguredRun, ConfiguredRunPatch, ToolChoiceOptions, OutputFormatOptions, CancelAgentResult, ListAgentsResponse, RunBatchOptions, RunBatchResult, SpawnRunResult, CompactRunResult, DirectoryBudget, DirectoryInspection, DirectoryTenant, DirectoryUser, ErasureReport, ErasureResidue, ErasureResult, ErasureTier, CancelTurnResult, ReviewRunResult, TranscriptEvent, TranscriptResponse, HealthResponse, ListUsersResponse, UserSummary, UserRecord, CreateUserBody, UpdateUserBody, MintedUserToken, UserTokenMeta, ListUserTokensResponse, RunnableAgent, RunnableAgentsResponse, WhoamiResponse, PauseResult, ResumeResult, RuntimeStateResponse, RuntimeStateStatus, ResolverMatrix, ResolverModelStatus, ResolverProviderAvailability, CreateSnapshotOptions, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotListResponse, SnapshotRestoreResponse, MemoryEntriesResponse, MemoryEntry, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopeIDSummary, MemoryScopeKind, MemoryScopesResponse, MemorySearchInput, MemorySource, MemoryWhen, MemoryTimeFilter, MemorySearchEntry, MemorySearchResponse, MemoryEmbedModelStats, MemoryEmbedStatsResponse, MemoryReembedConfigured, MemoryReembedResponse, MemoryBackfillResponse, MemoryPurgeResponse, InterruptListResponse, InterruptRow, InterruptStatus, ResolveInterruptOptions, ChannelHookCall, ChannelHookResult, HookFailMode, HookPhase, HookToolCall, HookToolResult, PostHookCall, PostHookResult, PreHookCall, PreHookResult, SubstrateToolInput, SubstrateToolResponse, TeamNameSummary, ListTeamsResponse, TeamDiagram, CreatedTeam, PromotedTeam, RetiredTeam, TeamDefDetail, TeamVerification, TeamVersion, TeamVersionList, TeamBreakpoints, TeamRunDetached, TeamRunResult, TeamRunTarget, PathToolInput, PathToolResponse, DocumentToolInput, DocumentToolResponse, HistoryToolInput, HistoryToolResponse, VolumeMode, PersistentVolumeEntry, PersistentVolumesResponse, EphemeralVolumeEntry, EphemeralVolumesResponse, SystemPromptPayload, UserInputPayload, ChannelDescriptor, ListChannelsResponse, RunStateEvent, RunStateStreamClose, RunStateStreamItem, RunStateStreamOpen, StreamUserRunStatesOptions, AckChannelOptions, ChannelAckResult, ChannelMessageItem, ChannelPeekResult, ChannelPublishResult, ChannelPurgeResult, ChannelReleaseResult, ChannelScope, ChannelSubscribeResult, PeekChannelOptions, PublishChannelOptions, SubscribeChannelOptions, AwaitChannelsOptions, BroadcastChannelsOptions, ChannelAwaitEntry, ChannelAwaitMode, ChannelAwaitResult, ChannelBroadcastEntry, ChannelBroadcastResult, CreateChannelOptions, ReleaseChannelOptions, UpdateChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, AgentDefRowResponse, AgentDefVerifyResult, SkillDefVerifyResult, EnsureMcpServerOptions, EnsureMcpServerResult, MCPServerDefRowResponse, MCPServerDefVerifyResult, AgentDefOverlay, HookEvent, InlineWebhook, HookEntry, EventHooks, ToolEntry, ToolHooksByTool, EnsureCodeAgentOptions, EnsureCodeAgentResult, LibraryAgentDefinition, LibraryEntry, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, LLMChatContent, LLMChatMessage, LLMChatOptions, LLMChatResponse, LLMChatStreamDelta, LLMChatStreamItem, LLMChatToolCall, LLMChatUsage, LLMTool, LLMEmbeddingItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, LLMEmbeddingsUsage, UsageDimension, UsageAggregate, UsageReportResponse, CapabilityInertInfo, LimitInfo, ErrorInfo, CallFormat, CallRef, HookDecisionInfo, EffectiveConfigResponse, EffectiveConfigSource, EffectiveValue, RetuneRunResponse, RunConfigRecord, RunConfigResponse, RunPromptResponse, RunPromptSnapshot, PromptBlock, TokenLimit, TokenLimitsResponse, ConfigResponse, ConfigProvider, ConfigModel, ConfigSearch, ConfigInstance, SetTokenLimitRequest, CredentialScope, CredentialMeta, CredentialListResponse, } from "./types.js";
+export type { AgentEvent, ClientOptions, ContinueOptions, EventType, HostWidening, ImageMediaType, ParentContext, PromptContent, PromptSegment, RetryInfo, RunOptions, SamplingOptions, CompactionOptions, ContextOptions, ToolUse, Usage, Agent, AgentStatus, AwaitedState, AgentUsage, RunResult, RunSpec, ConfiguredRun, ConfiguredRunPatch, ToolChoiceOptions, OutputFormatOptions, CancelAgentResult, ListAgentsResponse, WalkRunsPage, RunBatchOptions, RunBatchResult, SpawnRunResult, CompactRunResult, DirectoryBudget, DirectoryInspection, DirectoryTenant, DirectoryUser, ErasureReport, ErasureResidue, ErasureResult, ErasureTier, CancelTurnResult, ReviewRunResult, TranscriptEvent, TranscriptResponse, HealthResponse, ListUsersResponse, UserSummary, UserRecord, CreateUserBody, UpdateUserBody, MintedUserToken, UserTokenMeta, ListUserTokensResponse, RunnableAgent, RunnableAgentsResponse, WhoamiResponse, PauseResult, ResumeResult, RuntimeStateResponse, RuntimeStateStatus, ResolverMatrix, ResolverModelStatus, ResolverProviderAvailability, CreateSnapshotOptions, SnapshotCreateResponse, SnapshotDescriptor, SnapshotEnvelope, SnapshotListResponse, SnapshotRestoreResponse, MemoryEntriesResponse, MemoryEntry, MemoryEntryResponse, MemoryScopeIDsResponse, MemoryScopeIDSummary, MemoryScopeKind, MemoryScopesResponse, MemorySearchInput, MemorySource, MemoryWhen, MemoryTimeFilter, MemorySearchEntry, MemorySearchResponse, MemoryEmbedModelStats, MemoryEmbedStatsResponse, MemoryReembedConfigured, MemoryReembedResponse, MemoryBackfillResponse, MemoryPurgeResponse, InterruptListResponse, InterruptRow, InterruptStatus, ResolveInterruptOptions, ChannelHookCall, ChannelHookResult, HookFailMode, HookPhase, HookToolCall, HookToolResult, PostHookCall, PostHookResult, PreHookCall, PreHookResult, SubstrateToolInput, SubstrateToolResponse, TeamNameSummary, ListTeamsResponse, TeamDiagram, CreatedTeam, PromotedTeam, RetiredTeam, TeamDefDetail, TeamVerification, TeamVersion, TeamVersionList, TeamBreakpoints, TeamRunDetached, TeamRunResult, TeamRunTarget, PathToolInput, PathToolResponse, DocumentToolInput, DocumentToolResponse, HistoryToolInput, HistoryToolResponse, VolumeMode, PersistentVolumeEntry, PersistentVolumesResponse, EphemeralVolumeEntry, EphemeralVolumesResponse, SystemPromptPayload, UserInputPayload, ChannelDescriptor, ListChannelsResponse, RunStateEvent, RunStateStreamClose, RunStateStreamItem, RunStateStreamOpen, StreamUserRunStatesOptions, AckChannelOptions, ChannelAckResult, ChannelMessageItem, ChannelPeekResult, ChannelPublishResult, ChannelPurgeResult, ChannelReleaseResult, ChannelScope, ChannelSubscribeResult, PeekChannelOptions, PublishChannelOptions, SubscribeChannelOptions, AwaitChannelsOptions, BroadcastChannelsOptions, ChannelAwaitEntry, ChannelAwaitMode, ChannelAwaitResult, ChannelBroadcastEntry, ChannelBroadcastResult, CreateChannelOptions, ReleaseChannelOptions, UpdateChannelOptions, SetMemoryEntryOptions, SetMemoryEntryResponse, AgentDefRowResponse, AgentDefVerifyResult, SkillDefVerifyResult, EnsureMcpServerOptions, EnsureMcpServerResult, MCPServerDefRowResponse, MCPServerDefVerifyResult, AgentDefOverlay, HookEvent, InlineWebhook, HookEntry, EventHooks, ToolEntry, ToolHooksByTool, EnsureCodeAgentOptions, EnsureCodeAgentResult, LibraryAgentDefinition, LibraryEntry, LibraryListResponse, LibraryMcpServerDefinition, LibrarySkillDefinition, LLMChatContent, LLMChatMessage, LLMChatOptions, LLMChatResponse, LLMChatStreamDelta, LLMChatStreamItem, LLMChatToolCall, LLMChatUsage, LLMTool, LLMEmbeddingItem, LLMEmbeddingsOptions, LLMEmbeddingsResponse, LLMEmbeddingsUsage, UsageDimension, UsageAggregate, UsageReportResponse, CapabilityInertInfo, LimitInfo, ErrorInfo, CallFormat, CallRef, HookDecisionInfo, EffectiveConfigResponse, EffectiveConfigSource, EffectiveValue, RetuneRunResponse, RunConfigRecord, SubagentHoldInfo, RunConfigResponse, RunPromptResponse, RunPromptSnapshot, PromptBlock, TokenLimit, TokenLimitsResponse, ConfigResponse, ConfigProvider, ConfigModel, ConfigSearch, ConfigInstance, SetTokenLimitRequest, CredentialScope, CredentialMeta, CredentialListResponse, } from "./types.js";
 export { AgentIDInUseError, AgentNotFoundError, AlreadyPausingError, AuthError, BackpressureError, NotFoundError, InvalidArgumentError, ChannelCursorRegressionError, LoomcycleError, NotPausedError, PauseNotConfiguredError, PerUserQuotaExhaustedError, SessionBusyError, SessionNotFoundError, SnapshotNotFoundError, SnapshotTooLargeError, SnapshotVersionError, SubstrateToolRefusedError, UnavailableError, } from "./errors.js";

package/dist/index.js

@@ -12,8 +12,10 @@
  *
  *     // Agent metadata
  *     getAgent(agentId): Promise<Agent>
+ *     getRun(runId): Promise<Agent>
  *     cancelAgent(agentId, opts?): Promise<CancelAgentResult>
  *     listUserAgents(userId, opts?): Promise<Agent[]>
+ *     listWalkRuns(walkId, opts?): Promise<WalkRunsPage>
  *     getTranscript(sessionId): Promise<TranscriptResponse>
  *     health(): Promise<HealthResponse>
  *     listUsers(opts?): Promise<ListUsersResponse>   // tenant-scoped (RFC L)

package/dist/types.d.ts

@@ -7,7 +7,7 @@
  * `client.ts` for the input shapes (RunOptions, CreateSnapshotOptions,
  * etc.) — those are translated to snake_case in the request body.
  */
-export type EventType = "started" | "text" | "tool_call" | "tool_result" | "usage" | "done" | "error" | "retry" | "host_widened" | "session" | "agent" | "awaiting_input" | "awaiting_review" | "steer" | "context_compaction" | "capability_inert" | "hook_decision" | "limit" | "override" | "context_recap" | "context_state" | "context_distill_declined" | "context_exhausted" | "thinking" | "turn_cancelled" | "provider_fallback" | "fallback_suppressed" | "model_downgraded" | "cache_invalidated" | "reasoning_invalidated" | "channel_publish" | "channel_delivery" | "interruption_pending" | "spawn_child_started" | "spawn_child_result" | "prompt_snapshot" | "_meta";
+export type EventType = "started" | "text" | "tool_call" | "tool_result" | "usage" | "done" | "error" | "retry" | "host_widened" | "session" | "agent" | "awaiting_input" | "awaiting_review" | "subagent_hold" | "steer" | "context_compaction" | "capability_inert" | "hook_decision" | "limit" | "override" | "context_recap" | "context_state" | "context_distill_declined" | "context_exhausted" | "thinking" | "turn_cancelled" | "provider_fallback" | "fallback_suppressed" | "model_downgraded" | "cache_invalidated" | "reasoning_invalidated" | "channel_publish" | "channel_delivery" | "interruption_pending" | "spawn_child_started" | "spawn_child_result" | "prompt_snapshot" | "_meta";
 export interface ToolUse {
     id: string;
     name: string;
@@ -54,6 +54,17 @@ export interface HostWidening {
     hook_name: string;
     hosts_added: string[];
 }
+/** A sub-agent's review hold, as its parent's stream reports it. */
+export interface SubagentHoldInfo {
+    subagent: string;
+    subagent_run_id: string;
+    state: "held" | "released";
+    held_by?: string;
+    round?: number;
+    expires_at?: string;
+    /** How the child ended: completed | rejected | failed | cancelled ("released" only). */
+    status?: string;
+}
 /** LimitInfo accompanies an `event: limit` frame (RFC AW per-scope token
  *  budgets). Names which scope tripped, how hard (`soft` warns + the run
  *  continues; `hard` means the NEXT run is refused at admission), and where the
@@ -519,6 +530,11 @@ export interface AgentEvent {
         expires_at?: string;
         held_by?: string;
     };
+    /** Payload on `event: subagent_hold` — on a parent's stream, a sub-agent it
+     *  started through the Agent tool is held for a verdict (`state` "held";
+     *  rule on it with {@link LoomcycleClient.reviewRun} on `subagent_run_id`)
+     *  or has ended (`state` "released", with `status`). */
+    subagent_hold?: SubagentHoldInfo;
     /** Payload on `event: steer` (RFC AI) — the operator's drained turn. On a
      *  re-attach replay, `source` is `"replay"`. Nil on all other event types. */
     user_input?: {
@@ -665,17 +681,27 @@ export interface RunOverrideOptions {
      *  it outright (status `rejected`). Settable while the run is going; `false`
      *  on a run that is held releases it as approved. */
     review?: boolean;
-    /** Let this run's agent ASK a human a question, overriding what its
-     *  definition allows.
-     *
-     *  Overridable because an interruption touches no data and no host — it blocks
-     *  and waits for a person — so the exposure is liveness, bounded by the run's
-     *  timeout and the interruption's own. */
+    /** Narrow whether this run's agent may ASK a human a question. `enabled`
+     *  must be true to keep asking (false switches it off); `kinds` keeps only
+     *  those the definition also allows; `max_pending` takes the smaller. It
+     *  never grants the Interruption tool to an agent that does not hold it —
+     *  there it is reported as `capability_inert`. A retune reaches a parked run
+     *  at its next operator turn. */
     interruption?: {
         enabled?: boolean;
         kinds?: string[];
         max_pending?: number;
     };
+    /** Per-run tool choice: whether and which tool the model must call, and
+     *  for how many calls. REPLACES the agent's own whole. On a retune it
+     *  replaces the run's own and takes effect from the run's next turn, where
+     *  its `until` starts counting; mode `auto` removes the forcing. */
+    toolChoice?: ToolChoiceOptions;
+    /** Per-run answer schema: the final answer is held to it where the model
+     *  supports it, and returned parsed as `result.structured`. REPLACES the
+     *  agent's own whole. On a retune it replaces the run's own and takes
+     *  effect from the run's next turn; a retune cannot remove it. */
+    outputFormat?: OutputFormatOptions;
 }
 export interface RunOptions extends RunOverrideOptions {
     agent: string;
@@ -768,13 +794,6 @@ export interface RunOptions extends RunOverrideOptions {
      *  agent's own sampling (this wins; unset fields inherit). Omitted =
      *  inherit entirely. */
     sampling?: SamplingOptions;
-    /** Per-run tool choice (RFC DI): whether and which tool the model must
-     *  call, and for how many calls. REPLACES the agent's own whole. */
-    toolChoice?: ToolChoiceOptions;
-    /** Per-run answer schema (RFC DI): the final answer is held to it where
-     *  the model supports it, and returned parsed as `result.structured`.
-     *  REPLACES the agent's own whole. */
-    outputFormat?: OutputFormatOptions;
     /** 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
@@ -990,6 +1009,14 @@ export interface ParentContext {
      *  fields, which are omitted when empty), so an index of 0 is a real first
      *  position and not an absent one. */
     wave_index?: number;
+    /** Which state of the walk ran this run — set on EVERY run a team walk
+     *  spawns (agent, parallel, consolidator and starter members alike), where
+     *  the wave fields are a starter's alone. */
+    state?: string;
+    /** The walk's own ordinal of state visits (1, 2, …): the runs of one visit
+     *  share it, and a revisit of the same state gets a new one. Absent outside
+     *  a walk. */
+    state_visit?: number;
 }
 export interface ContinueOptions extends RunOverrideOptions {
     /** Required — the session to continue. */
@@ -1045,13 +1072,6 @@ export interface ContinueOptions extends RunOverrideOptions {
     toolHooks?: ToolHooksByTool;
     /** Per-continuation LLM sampling override — see {@link RunOptions.sampling}. */
     sampling?: SamplingOptions;
-    /** Per-run tool choice (RFC DI): whether and which tool the model must
-     *  call, and for how many calls. REPLACES the agent's own whole. */
-    toolChoice?: ToolChoiceOptions;
-    /** Per-run answer schema (RFC DI): the final answer is held to it where
-     *  the model supports it, and returned parsed as `result.structured`.
-     *  REPLACES the agent's own whole. */
-    outputFormat?: OutputFormatOptions;
     /** Per-continuation context-compaction override — see {@link RunOptions.compaction}. */
     compaction?: CompactionOptions;
     /** Per-continuation context-distillation override — see
@@ -1085,6 +1105,10 @@ export interface ClientOptions {
 /** `configured` is a run created but not yet started (RFC DI). */
 /** `rejected` is a run a reviewer turned down without feedback (RFC DJ). */
 export type AgentStatus = "configured" | "running" | "completed" | "failed" | "cancelled" | "rejected";
+/** What a running run is blocked on: an open Channel subscribe, an open
+ *  Interruption ask, a hold for an operator's review verdict, or an
+ *  interactive run parked for the operator's next turn (`input`). */
+export type AwaitedState = "channel" | "interrupted" | "review" | "input";
 export interface AgentUsage {
     input_tokens?: number;
     output_tokens?: number;
@@ -1099,6 +1123,11 @@ export interface Agent {
     session_id: string;
     agent: string;
     parent_agent_id: string | null;
+    /** The run that spawned this one (an Agent-tool spawn, a team-walk member,
+     *  a walk started by an agent). Absent for a top-level run. Unlike
+     *  parent_agent_id it names one run: an agent id is reused by every run of
+     *  that agent. */
+    parent_run_id?: string;
     user_id: string;
     status: AgentStatus;
     started_at: string;
@@ -1108,6 +1137,26 @@ export interface Agent {
     usage: AgentUsage;
     last_heartbeat_at: string | null;
     live: boolean;
+    /** A persistent interactive run — it parks at end_turn waiting for operator
+     *  input. Absent for ordinary runs. */
+    interactive?: boolean;
+    /** What a RUNNING run is currently blocked on; absent while it makes
+     *  progress and for every run that is not running. See {@link AwaitedState}. */
+    awaited_state?: AwaitedState;
+    /** The channel name (`awaited_state: "channel"`; a fan-in `Channel` await
+     *  lists its channels comma-separated, bounded), interruption kind
+     *  (`awaited_state: "interrupted"`) or the agent_stop hook holding a review
+     *  (`awaited_state: "review"`) the run waits on. */
+    awaited_on?: string;
+    /** The replica owning the run's live cancel handle. Absent in a
+     *  single-replica deployment. */
+    replica_id?: string;
+    /** This run is a LIVE resident interactive sub-agent (opened with Agent
+     *  op=open) on the replica that answered. HTTP listings only — the gRPC read
+     *  cannot reach the per-replica registry this comes from. */
+    resident?: boolean;
+    /** A resident sub-agent's current state; set only with `resident`. */
+    resident_state?: "running" | "awaiting_input" | "completed" | "failed";
     /** 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
@@ -1115,11 +1164,11 @@ export interface Agent {
     parent_context?: ParentContext;
     /** The run's answer (RFC DI) — what the row had no field for; `stop_reason`,
      *  `error` and `usage` are above. Present on {@link LoomcycleClient.getAgent}
-     *  only (listings omit it), and only once the run has finished with
+     *  and {@link LoomcycleClient.getRun} only (listings omit it), and only once the run has finished with
      *  something to report. */
     result?: RunResult;
     /** The run's own configuration (RFC DI): the overrides it ran with, merged
-     *  over its definition. {@link LoomcycleClient.getAgent} only, like
+     *  over its definition. {@link LoomcycleClient.getAgent} / getRun only, like
      *  `result`; absent when the run overrode nothing. */
     spec?: RunSpec;
     /** A CONFIGURED run's request as it will start (RFC DI) — what
@@ -1170,6 +1219,55 @@ export interface RunSpec {
         hooks?: EventHooks;
         tool_hooks?: ToolHooksByTool;
     };
+    /** Hooks a definition added to the run (a team state's), each with the
+     *  definition it came from: its owner (`team:<name>`), owning tenant and
+     *  whether an operator wrote it. Written by the server only — no run
+     *  request can set a source. */
+    sourced_hooks?: Array<{
+        source: {
+            owner: string;
+            tenant?: string;
+            operator_authored?: boolean;
+        };
+        hooks?: EventHooks;
+        tool_hooks?: ToolHooksByTool;
+    }>;
+    /** What the run's hooks resolved to when it started, so a resumed run
+     *  fires those and no others: a fingerprint of the agent's own hooks and
+     *  the HookDef version each reference found. Present only on a run that
+     *  carries hooks. */
+    pinned_hooks?: {
+        agent: string;
+        defs?: Record<string, string>;
+    };
+    /** What bounded a sub-run at its spawn beyond its own agent: its parent's
+     *  volumes (names and modes; roots are resolved again on resume, never
+     *  stored) and the fan-out width it inherited. Present only on a sub-run.
+     *  Written by the server only. */
+    spawn?: {
+        volumes: {
+            active: boolean;
+            bindings?: Array<{
+                name: string;
+                read_only: boolean;
+                default?: boolean;
+            }>;
+        };
+        fanout_cap?: number;
+    };
+    /** The agent version the run started on, which a resumed run continues on:
+     *  the AgentDef version its agent name resolved to (`def_id` absent for an
+     *  agent with no versions — the operator's yaml or a registered agent). For
+     *  a registered agent, `registered_sha256` is a digest of the registration
+     *  the run started on; a resume refuses one changed since. `static` marks a
+     *  run that started on the operator's static configuration, which a resume
+     *  reads again rather than a same-named agent registered or forked since.
+     *  Written by the server only. */
+    agent_version?: {
+        def_id?: string;
+        registered_sha256?: string;
+        static?: boolean;
+    };
 }
 /** A finished run's answer (RFC DI). */
 export interface RunResult {
@@ -1184,6 +1282,12 @@ export interface RunResult {
 export interface ListAgentsResponse {
     agents: Agent[];
 }
+/** One page of a team walk's runs ({@link LoomcycleClient.listWalkRuns}),
+ *  ordered by started_at then run id. `next_cursor` is "" on the last page. */
+export interface WalkRunsPage {
+    agents: Agent[];
+    next_cursor: string;
+}
 export interface CancelAgentResult {
     /** Number of agents marked cancelled (root + descendants reached
      *  via parent_agent_id cascade). 0 when the agent had already
@@ -1560,6 +1664,14 @@ export interface SnapshotCreateResponse {
     label?: string;
     schema_version: number;
     byte_size: number;
+    /** What the capture carried that you should act on, named by location,
+     *  never by value: every literal-looking credential in a captured
+     *  definition (headers, URLs, stdio env/command/args), and every paused
+     *  run parked on a pending interrupt. A literal travels in the snapshot as
+     *  written; replace it with a `$cred:` or `${LOOMCYCLE_*}` reference (in a
+     *  stdio server's env, command or args only `${LOOMCYCLE_*}` resolves).
+     *  Omitted when there are none. */
+    warnings?: string[];
 }
 /** Full envelope returned by GET /v1/_snapshots/{id}. json_content
  *  carries the canonical envelope as a parsed JSON object — pipe
@@ -1590,10 +1702,18 @@ export interface SnapshotRestoreResponse {
     channel_cursors_restored?: number;
     evaluations_restored?: number;
     paused_runs_restored?: number;
+    /** How many restored paused runs the server re-dispatched as live loops.
+     *  Can be below `paused_runs_restored`: a run whose agent no longer
+     *  resolves is flagged failed and named in `warnings` instead. */
+    paused_runs_resumed?: number;
     synthesized_sessions?: number;
     transcript_events_restored?: number;
     interaction_history_restored?: number;
     warnings?: string[];
+    /** Every restore counter keyed by name (`agent_defs`, `hook_defs`,
+     *  `mcp_server_defs_activated`, ...) — including the ones the typed fields
+     *  above never carried. A new snapshot section adds a key here. */
+    restored?: Record<string, number>;
 }
 export interface MemoryScopeKind {
     name: string;
@@ -1741,6 +1861,13 @@ export interface MemorySearchEntry {
     document?: string;
     /** The chunk's own heading. Same conditions as {@link document}. */
     title?: string;
+    /** Present when the chunk was found through one of its Document derived search
+     *  units — a description, claim or question generated for it — rather than its
+     *  own text. The chunk appears once however many of its units matched. */
+    matched_unit?: {
+        kind: "description" | "claim" | "question";
+        text: string;
+    };
 }
 export interface MemorySearchResponse {
     scope: string;
@@ -2097,14 +2224,19 @@ export interface TeamRunTarget {
      *
      *  `"<state>:review"` arms review instead — see {@link TeamRunTarget.review}. */
     breakpoints?: string[];
-    /** Starter state ids whose member runs are held for an operator's verdict
-     *  when they finish: approve with {@link LoomcycleClient.reviewRun}, reject
-     *  with feedback the member revises from, or reject. A rejected member
-     *  reaches the sink as status `"rejected"` and does not count toward the
-     *  wave's `wait`. Also armable live as the breakpoint `"<state>:review"`. */
+    /** Starter, agent or parallel state ids whose member runs are held for an
+     *  operator's verdict when they finish: approve with
+     *  {@link LoomcycleClient.reviewRun}, reject with feedback the member revises
+     *  from, or reject. A rejected starter member reaches the sink as status
+     *  `"rejected"` and does not count toward the wave's `wait`; a rejected agent
+     *  or parallel member counts as failed. A consolidator state is refused — its
+     *  answer is the walk's verdict on the work, and a parallel state's own
+     *  consolidator is never held. Also armable live as the breakpoint
+     *  `"<state>:review"`. */
     review?: string[];
     /** With `review`: end a member hold nobody rules on within this many
-     *  seconds as rejected. Omit for no deadline. */
+     *  seconds as rejected. Omit for no deadline. Changeable while the walk
+     *  runs — see {@link LoomcycleClient.setRunBreakpoints}. */
     reviewTtlSeconds?: number;
 }
 /** What {@link LoomcycleClient.runTeam} returns for `mode: "detach"` — the
@@ -2132,6 +2264,10 @@ export interface TeamBreakpoints {
      *  sorted, so what you read back is what the walk will actually do rather
      *  than an echo of the shorthand you sent. */
     armed: string[];
+    /** The review deadline, in seconds, a member hold beginning now gets —
+     *  0 = none. Starts as the run's {@link TeamRunTarget.reviewTtlSeconds};
+     *  changeable with {@link LoomcycleClient.setRunBreakpoints}. */
+    review_ttl_seconds: number;
 }
 /** Input for {@link LoomcycleClient.path} — the RFC AL Unix-like VFS tool
  *  (POST /v1/_path). Op-discriminated; the server resolves scope + tenant
@@ -2691,6 +2827,9 @@ export interface RunStateEvent {
     agent: string;
     user_id: string;
     parent_agent_id?: string;
+    /** The run that spawned this one; absent for a top-level run. Unlike
+     *  `parent_agent_id`, which every run of an agent reuses, it names one run. */
+    parent_run_id?: string;
     status: string;
     stop_reason?: string;
     error?: string;
@@ -2699,6 +2838,16 @@ export interface RunStateEvent {
      *  so a subscriber learns which root request a finishing sub-agent
      *  belongs to. Omitted when the run carried no context. */
     parent_context?: ParentContext;
+    /** What a `running` run has started waiting on. A wait is announced as its
+     *  own `running` event and its end as another `running` event without this
+     *  field, so a client folding the stream holds the run's current wait. */
+    awaited_state?: AwaitedState;
+    /** The channel (a fan-in `Channel` await: its channels, comma-separated),
+     *  the interruption kind, or the agent_stop hook holding a review. */
+    awaited_on?: string;
+    /** RFC3339: when a review hold ends as rejected if nobody rules on it.
+     *  Absent when the wait has no deadline. */
+    hold_expires_at?: string;
 }
 /** Initial stream_open frame emitted before the first run_state. */
 export interface RunStateStreamOpen {
@@ -3017,6 +3166,12 @@ export interface AgentDefOverlay {
      *  reports `reranked` (and `rerank_reason` when false); a failed or unavailable
      *  rerank keeps the search's own order. */
     memory_rerank?: MemoryRerank;
+    /** `false` makes this agent's searches ignore Document derived search units — the
+     *  short descriptions, claims and questions an operator may generate for a
+     *  document so a question can match them. Unset uses them wherever they exist
+     *  (only where an operator generated them). A chunk found through a unit carries
+     *  `matched_unit: {kind, text}`. */
+    memory_units?: boolean;
     memory_quota_bytes?: number;
     memory_backend?: string;
     retry_attempts?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loomcycle/client",
-  "version": "1.99.0",
+  "version": "1.101.0",
   "description": "TypeScript client for the loomcycle sidecar (HTTP+SSE). 71 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.) v0.34.0 — version-aligned lockstep release; no client-surface change (context-transform plugins / RFC Z Phase 1a are server-side config; the exp7 hardening pass is server-side; the R2 cross-provider thinking-model downgrade surfaces a new `model_downgraded` SSE event the generic stream passes through unchanged). v0.35.0 — RFC AH dynamic filesystem volumes: volumeDef() (POST /v1/_volumedef — op-discriminated create/get/list/delete/purge; a Volume is flat, so delete unmaps + purge RemoveAll's, no retire/promote/fork) + listVolumes() / listEphemeralVolumes() (GET /v1/_volumes[/ephemeral] — tenant-scoped; host paths redacted for non-operator callers). Tenant-confined; the runtime derives the path inside an operator-blessed dynamic_root, so callers pass name + mode, never a host path. v1.1.1 — RFC AI interactive agentic sessions: an `interactive: true` flag on runStreaming/continueSession (a run that parks at end_turn for steering) + sendRunInput(runId, text) (POST /v1/runs/{id}/input — steer a live run) + streamRunByID(runId, {fromSeq}) (GET /v1/runs/{id}/stream — re-attach by run_id; the operator's prior turns replay as `steer` events so a cold client reconstructs the whole conversation) + a high-level InteractiveSession driver (client.interactiveSession / attachInteractiveSession — events()/send()/cancel(), the adapter port of the Web UI run terminal). The AgentEvent union gains awaiting_input/steer/context_compaction frames. Version-aligned with the loomcycle v1.1.x line so the v1.1.1 tag publishes it (also carrying the previously-unpublished v0.35.0 volume surface). v1.4.0 — RFC AL Path VFS + RFC AK Document on the wire: path(input) (POST /v1/_path — a Unix-like filesystem over Memory/Volumes/Documents; resolve/ls/stat/mkdir/mv/rm) + document(input) (POST /v1/_document — chunked-graph documents; 13 ops, needs SQL Memory on the sidecar). Scope (agent/user/tenant) + tenant are resolved server-side from the authenticated principal, never the wire; an off-run scope:'user' op keys on the principal subject so it interoperates with that user's agent runs. New PathToolInput / DocumentToolInput types; responses are op-varying (unknown — narrow as needed). v1.7.0 — RFC AT image/vision input: the PromptContent union gains an `image` variant ({ type:'image'; media_type: ImageMediaType; data: base64-no-prefix }) accepted in a user segment by runStreaming / continueSession (segments pass through unchanged — no method change). The model must be vision-capable or the run errors before the call. New ImageMediaType type (image/png|jpeg|gif|webp). v1.12.1 — Path/Document browse-by-subject + the full Document op set (RFC AS/AK): path(input, opts) / document(input, opts) accept optional scopeId / tenant browse overrides sent as ?scope_id= / ?tenant= query params (server reads them from the URL, re-checks authorization; omit both to browse your own subject — byte-identical to the pre-RFC-AS request), and DocumentToolInput.op now covers all 16 backend ops (adds set_path, export_md, import_md) with the matching include_metadata / markdown fields. Additive — existing path() / document() callers are unchanged. v1.16.0 — RFC BC client-executed tools (local tool host): connectClientTools({tools,onInvoke}) opens a persistent WebSocket to /v1/client-tools, registers tools this client runs on the user's machine (browser DOM / files / shell), and answers the invoke frames loomcycle routes when an agent of your principal calls a client:<tool> — returning your reply as an ordinary tool result. Returns a ClientToolHost driver (.close() to stop; auto-reconnect); dependency-free (global WebSocket in browsers / Node 22+, or an injected WebSocketImpl like the ws package on older Node); the bearer rides the Sec-WebSocket-Protocol subprotocol (browsers can't set an Authorization header on a WebSocket). The runtime's first WebSocket surface. v1.45.0 — RFC BL P5 subject erasure: erasureReport(subject, {tenant}) (GET /v1/_erasure — what this deployment holds about one subject, in three tiers: deletable with existing primitives, subject-keyed but not deletable, and facts ABOUT the subject in scopes they do not own) + erasureExecute(subject, {dryRun, confirm, tenant}) (POST /v1/_erasure — removes tiers 1 and 2). DEFAULTS TO A DRY RUN: dryRun defaults true and a live run also requires confirm === subject. The tier-3 residue is traceable only through the subject's chats, which a live run deletes, so a report afterwards shows rows: 0 while those facts remain — the returned object is the only durable record of what was not reached; persist it. New ErasureReport / ErasureResult / ErasureTier / ErasureResidue types. v1.47.0 — RFC BV memory-view SDK: memorySearch() (POST /v1/_memory/search — off-run unified semantic search spanning k/v entries AND document-chunk bodies in one ranked list, each hit tagged kind memory|document with chunk_id on document hits) + memoryEmbedStats(scope) + reembedMemory(scope, scopeId, {dryRun,limit}) (the Vector Memory embed-admin reads the memory-view console needs; dry_run defaults true). Fact reads (list_facts + get_chunk's entity block) ride the existing document() passthrough. Additive — existing callers unchanged. v1.61.0 — RFC CJ per-run context-window override: runStreaming / continueSession accept an optional maxContextTokens (integer tokens) that wins over the agent's own max_context_tokens; omitted inherits it (which defers to the provider/driver default). Distinct from a model's output cap; primarily for local inference (Ollama num_ctx). Serialized as the snake_case max_context_tokens field on POST /v1/runs + the continuation body; additive, existing callers unchanged. v1.72.1 — the TeamDef version lifecycle: listTeamVersions(name) (op=list — every version of one team, newest first), promoteTeam(defId) (op=promote — point the active pointer, which is what a run BY NAME executes; forkTeam defaults to promote:false, so authoring and putting in force stay two steps), retireTeam(defId, retired) (op=retire — reversible and version-scoped, unlike deleteTeam) and verifyTeam(name, contentSha256) (op=verify — the drift check for a workflow kept in source control and pushed to several deployments; an absent team answers deployed:false rather than raising). The ops existed on the substrate and over HTTP; a client that could author a team could not put one in force.",
   "license": "Apache-2.0",
   "type": "module",