@loomcycle/client 1.112.0 → 1.113.0

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" | "subagent_hold" | "awaiting_children" | "children_note" | "steer" | "context_compaction" | "capability_inert" | "hook_decision" | "limit" | "override" | "context_recap" | "context_state" | "context_distill_declined" | "context_exhausted" | "thinking" | "team_decision" | "turn_cancelled" | "provider_fallback" | "fallback_suppressed" | "model_downgraded" | "cache_invalidated" | "reasoning_invalidated" | "channel_publish" | "channel_delivery" | "interruption_pending" | "spawn_child_started" | "spawn_child_result" | "spawn_child_read" | "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" | "awaiting_children" | "children_note" | "steer" | "context_compaction" | "capability_inert" | "hook_decision" | "limit" | "override" | "context_recap" | "context_state" | "context_distill_declined" | "context_exhausted" | "thinking" | "team_decision" | "turn_cancelled" | "provider_fallback" | "fallback_suppressed" | "model_downgraded" | "cache_invalidated" | "reasoning_invalidated" | "channel_publish" | "channel_delivery" | "interruption_pending" | "spawn_child_started" | "spawn_child_result" | "spawn_child_read" | "prompt_snapshot" | "queued" | "admitted" | "call_queued" | "call_admitted" | "_meta";
 export interface ToolUse {
     id: string;
     name: string;
@@ -223,6 +223,53 @@ export interface InertContextSetting {
      *  leaves the operator hunting for the live knob. */
     fix?: string;
 }
+/** Why a per-run override is refused, in {@link OverridableField.reason}:
+ *  - `token_locked` — the caller's token carries an overrides policy that
+ *                     leaves the field out
+ *  - `agent_locked` — the agent's definition says `allow_overrides: false`
+ *
+ *  When both apply the token is named, because a run setting the field is
+ *  refused for that reason first. */
+export type OverrideLockReason = "token_locked" | "agent_locked";
+/** One per-run override in {@link AgentOverridableResponse.fields}. */
+export interface OverridableField {
+    /** Whether a run of the agent, started by this caller, may set it. */
+    overridable: boolean;
+    /** Present when `overridable` is false. */
+    reason?: OverrideLockReason;
+    /** The run may only make it smaller than the definition allows
+     *  (`max_concurrent_children`, `interruption`). */
+    narrow_only?: boolean;
+    /** The largest value accepted (`max_concurrent_children`: the fan-out
+     *  ceiling, the definition's or the runtime default). */
+    max?: number;
+    /** The values accepted, when the run path checks against a closed set this
+     *  agent has: `effort`, the configured `tier`s, and the `provider` and
+     *  `model` sets the definition declares. Absent means no closed set here —
+     *  any value the deployment accepts (see `listModels()` / `getRouting()`),
+     *  not anything at all. Each describes the field set on its own. */
+    values?: string[];
+}
+/** The reply from `GET /v1/_agentdef/{name}/overridable` — for every per-run
+ *  override, whether a run of this agent started by THIS caller may set it.
+ *
+ *  Folds the definition's `allow_overrides` with the caller's token overrides
+ *  policy, through the same checks the run path refuses with. The answer is
+ *  the caller's: do not reuse it for another token. Keys of `fields` are wire
+ *  names (`max_tokens`, not `maxTokens`), one per run option a token's
+ *  overrides policy can name. */
+export interface AgentOverridableResponse {
+    agent: string;
+    /** The AgentDef version answered for; absent for a yaml or registered agent,
+     *  which have no versions. Always the active version: a run cannot pin one. */
+    def_id?: string;
+    /** The definition's `allow_overrides`; unset reads as true. */
+    allow_overrides: boolean;
+    /** True when the caller's token carries an overrides policy, so `fields`
+     *  reflects this caller and not only the agent. */
+    restricted_by_token: boolean;
+    fields: Record<string, OverridableField>;
+}
 /** The reply from `retuneRun` — the run's MERGED configuration, not an echo of
  *  the request.
  *
@@ -375,6 +422,28 @@ export interface CapabilityInertInfo {
     /** A line naming the tool, the gate, and what to set. */
     message?: string;
 }
+/** AdmissionInfo accompanies `event: queued` and `event: admitted` frames.
+ *  Mirrors providers.AdmissionInfo. */
+export interface AdmissionInfo {
+    /** On `queued`: why the run waits — `"user_cap"` (its user already has its
+     *  cap of runs active) or `"global_cap"` (every run slot is taken). On
+     *  `call_queued`: why the call waits — `"lane"` (every slot of its call lane
+     *  is taken) or `"models_in_flight"` (the provider has its cap of models in
+     *  flight and this call's model is not among them). */
+    reason?: "user_cap" | "global_cap" | "lane" | "models_in_flight";
+    /** On `queued`: the run's place when it was queued, 1 being the next to
+     *  start. For `user_cap` it counts only the same user's waiting runs. It
+     *  moves as other runs start and end; `getRun` reports the current place
+     *  (`Agent.queue_position`). */
+    position?: number;
+    /** On `admitted`: how long the run waited for its slot, in milliseconds. On
+     *  `call_admitted`: how long the call waited. */
+    wait_ms?: number;
+    /** On `call_queued` / `call_admitted`: the provider id as configured. */
+    provider?: string;
+    /** On `call_queued` / `call_admitted`: the call lane's model kind (`"chat"`). */
+    kind?: string;
+}
 export interface LimitInfo {
     /** Which axis tripped: "operator" | "tenant" | "user". */
     scope: string;
@@ -615,6 +684,11 @@ export interface AgentEvent {
     /** Payload on `event: limit` (RFC AW) — a per-scope token-budget crossing.
      *  Nil on all other event types. */
     limit?: LimitInfo;
+    /** Payload on `event: queued` (why the run waits, and its place) and
+     *  `event: admitted` (how long it waited), and on `event: call_queued` /
+     *  `event: call_admitted` (the same for one model call, with its provider
+     *  and lane kind). Nil on all other event types. */
+    admission?: AdmissionInfo;
     /** Set on `capability_inert` events: a tool the agent holds and cannot use. */
     capability_inert?: CapabilityInertInfo;
     /** Payload on `event: hook_decision`. */
@@ -859,6 +933,11 @@ export interface RunOptions extends RunOverrideOptions {
      *  is the time bound for a `mode: "detach"` batch child, where `timeoutMs`
      *  is refused. Any agent, model-driven or code-js. */
     maxWallSeconds?: number;
+    /** What the run does when it cannot start at once: `"wait"` (the default)
+     *  accepts it with status `queued` — the stream yields a `queued` event,
+     *  then `admitted` when it gets a slot — and `"reject"` refuses it at once
+     *  (`per_user_quota_exhausted` or `backpressure`). A fresh run only. */
+    admission?: "wait" | "reject";
     /** `"none"` makes this a no-trace run: what it says is delivered on this
      *  stream and stored nowhere — the server keeps a marker for each event
      *  (its type and size) and a class for an error, never the text. Omit (or
@@ -1217,7 +1296,8 @@ 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";
+/** `queued` is a run accepted but waiting for a run slot. */
+export type AgentStatus = "configured" | "queued" | "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, an
  *  interactive run parked for the operator's next turn (`input`), or a run
@@ -1267,6 +1347,14 @@ export interface Agent {
      *  (`awaited_state: "review"`) or the child run ids, comma-separated and
      *  bounded (`awaited_state: "children"`) the run waits on. */
     awaited_on?: string;
+    /** Where a `queued` run stands now: 1 is the next to start. For
+     *  `queue_reason: "user_cap"` it counts only the same user's waiting runs.
+     *  {@link LoomcycleClient.getAgent} / getRun only, from the replica that
+     *  holds the run's wait; absent on every other run. */
+    queue_position?: number;
+    /** Why a `queued` run waits: its user already has its cap of runs active
+     *  (`user_cap`), or every run slot is taken (`global_cap`). */
+    queue_reason?: "user_cap" | "global_cap";
     /** The replica owning the run's live cancel handle. Absent in a
      *  single-replica deployment. */
     replica_id?: string;
@@ -1328,6 +1416,10 @@ export interface RunSpec {
      *  `maxWallSeconds`: past it the run ends `cancelled` with
      *  `stop_reason: "wall_limit"`. Absent when the run has no such limit. */
     max_wall_seconds?: number;
+    /** The run started with its tree's ephemeral volumes read-only: its own
+     *  definition, or an ancestor's, says `ephemeral_volumes: "ro"`. A resume
+     *  restores it whatever the definition says by then. */
+    ephemeral_read_only?: boolean;
     review_ttl_seconds?: number;
     /** Which model serves the run: model / provider / tier / effort. */
     routing?: Record<string, unknown>;
@@ -1517,7 +1609,33 @@ export interface RunResult {
 }
 export interface ListAgentsResponse {
     agents: Agent[];
+    /** True when an `awaited_state` listing stopped before reading every
+     *  running run (it reads at most 1,000), so a matching run may be missing.
+     *  Absent otherwise. */
+    truncated?: boolean;
+}
+/** {@link LoomcycleClient.listUserAgents}'s filters. */
+export interface ListUserAgentsOptions {
+    /** One status or several (a run in any of them is listed). Omitted → only
+     *  running runs; `"all"` → every status. An unknown status is a 400. */
+    status?: AgentStatus | "all" | AgentStatus[];
+    /** List only running runs blocked on one of these waits. Implies running:
+     *  a `status` other than `"running"` with it is a 400. */
+    awaitedState?: AwaitedState | AwaitedState[];
+    /** Narrows the result CLIENT-SIDE to runs whose `parent_agent_id`
+     *  matches. */
+    parentAgentId?: string;
+    /** Super-admin tenant-focus (?tenant=, RFC L v0.17.0). Ignored
+     *  server-side for a tenant principal — its own tenant is forced. */
+    tenant?: string;
+    signal?: AbortSignal;
 }
+/** {@link LoomcycleClient.listUserAgents}'s answer: the runs, still an array,
+ *  carrying `truncated: true` when an `awaitedState` listing stopped before
+ *  reading every running run. */
+export type AgentList = Agent[] & {
+    truncated?: boolean;
+};
 /** 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 {
@@ -2308,6 +2426,9 @@ export interface PreHookCall {
     phase: "pre";
     owner: string;
     hook_name: string;
+    /** Present on a signed call only: this delivery's id, inside the signed body.
+     *  Dedupe on it, never on the unsigned X-Loomcycle-Delivery header copy. */
+    delivery_id?: string;
     agent: string;
     user_id?: string;
     agent_id?: string;
@@ -2334,6 +2455,9 @@ export interface PostHookCall {
     phase: "post";
     owner: string;
     hook_name: string;
+    /** Present on a signed call only: this delivery's id, inside the signed body.
+     *  Dedupe on it, never on the unsigned X-Loomcycle-Delivery header copy. */
+    delivery_id?: string;
     agent: string;
     user_id?: string;
     agent_id?: string;
@@ -2347,6 +2471,9 @@ export interface ChannelHookCall {
     /** `"channel:<name>"`. */
     owner: string;
     hook_name: string;
+    /** Present on a signed call only: this delivery's id, inside the signed body.
+     *  Dedupe on it, never on the unsigned X-Loomcycle-Delivery header copy. */
+    delivery_id?: string;
     channel: string;
     scope: string;
     scope_id?: string;
@@ -2378,7 +2505,7 @@ export interface ChannelHookResult {
  *  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" | "rediscover" | "verify" | "delete" | "purge";
+    op: "create" | "fork" | "get" | "list" | "promote" | "retire" | "rediscover" | "verify" | "delete" | "purge" | "set_mode";
     name?: string;
     def_id?: string;
     parent_def_id?: string;
@@ -2387,6 +2514,27 @@ export type SubstrateToolInput = {
     promote?: boolean;
     retired?: boolean;
     mode?: VolumeMode;
+    source?: {
+        git: {
+            /** https URL of the repository, on a host the operator allows. */
+            url: string;
+            /** The full 40-digit sha-1 of the commit. */
+            commit: string;
+            /** Where to find the commit when the server serves none by sha. */
+            ref?: string;
+            /** `$cred:<name>` or `$ghapp:<name>`; must be restricted to this URL. */
+            credential?: string;
+            /** May only lower the operator's limit. */
+            max_bytes?: number;
+            /** Also write a diff from this commit: "merge-base:default" or a sha. */
+            diff_base?: string;
+            /** Names for the diff's files, each a plain name under `_meta/`. */
+            outputs?: {
+                diff?: string;
+                numstat?: string;
+            };
+        };
+    };
     [extra: string]: unknown;
 };
 /** Response shape for {@link LoomcycleClient.agentDef} and
@@ -2648,12 +2796,20 @@ export interface TeamRunResult {
     capped_state?: string;
     max_iterations?: number;
     iteration_count?: number;
-    /** The per-state trace. Absent when `deduplicated` is set. */
-    steps: TeamRunStep[];
+    /** The per-state trace. Absent when `deduplicated` is set: the trace is
+     *  built by the request that walks and is not stored on the run, so a retry
+     *  answered from the key has none to return. */
+    steps?: TeamRunStep[];
     /** Set (true) when the request's `idempotencyKey` was already held: nothing
      *  was started, and this is the walk that holds it, as it is now — `status`
      *  may be "running", and there are no `steps`. */
     deduplicated?: boolean;
+    /** On a `deduplicated` answer for a walk that has ended: the stop reason
+     *  recorded on its run. Absent while it runs, and when none was recorded. */
+    stop_reason?: string;
+    /** On a `deduplicated` answer for a walk that has ended: why it failed, as
+     *  recorded on its run. Absent when it did not fail. */
+    error?: string;
     [extra: string]: unknown;
 }
 /** What team {@link LoomcycleClient.runTeam} walks, and how. */
@@ -2720,6 +2876,11 @@ export interface TeamRunTarget {
      *  it has no `steps`: read the walk's member runs for those. Refused with
      *  `boardChunkId`, which already resumes a stored position. */
     idempotencyKey?: string;
+    /** When a state hits its iteration cap, ask a human (an interruption)
+     *  whether to continue, `reroute:<state>` or abort, instead of ending with
+     *  the `iteration_cap` outcome. An ask nobody answers, that times out or is
+     *  declined aborts the walk. Default false. */
+    interruptOnCap?: boolean;
 }
 /** What {@link LoomcycleClient.runTeam} returns for `mode: "detach"` — the
  *  handle, immediately, with the walk still running behind it.
@@ -2973,6 +3134,114 @@ export type HistoryToolInput = {
  *  returns the chat metadata + transcript (or Markdown), `recap` a summary,
  *  `resume` a continuation handle. Callers narrow as needed. */
 export type HistoryToolResponse = unknown;
+/** Who recorded an evaluation, relative to the run it scores. The server
+ *  derives it from the caller and the target run; it is never sent. A call
+ *  outside a run (this client) records `external` or `unrelated`. */
+export type EvaluationEmitterRole = "self" | "sibling" | "parent" | "external" | "unrelated";
+/** `evaluation({op:"submit"})`: record a score against a run. Scores are
+ *  additive — submitting again records another evaluation. */
+export interface EvaluationSubmitInput {
+    op: "submit";
+    run_id: string;
+    /** Required. Convention [-1,1] or [0,1]; the operator chooses. */
+    score: number;
+    /** Named axes to numeric values, e.g. `{correctness: 0.8}`. */
+    dimensions?: Record<string, number>;
+    /** Free-form structured payload. */
+    judgement?: unknown;
+    /** Natural-language reasoning. */
+    rationale?: string;
+}
+/** `evaluation({op:"get"})`: one evaluation by id. */
+export interface EvaluationGetInput {
+    op: "get";
+    eval_id: string;
+}
+/** `evaluation({op:"list_for_run"})`: every evaluation of one run. */
+export interface EvaluationListForRunInput {
+    op: "list_for_run";
+    run_id: string;
+    /** Max rows (default 100). */
+    limit?: number;
+}
+/** `evaluation({op:"list_for_def"})`: every evaluation of runs of one
+ *  definition version, in the caller's tenant. */
+export interface EvaluationListForDefInput {
+    op: "list_for_def";
+    def_id: string;
+    /** Max rows (default 100). */
+    limit?: number;
+}
+/** `evaluation({op:"aggregate"})`: the scores of a definition rolled up. */
+export interface EvaluationAggregateInput {
+    op: "aggregate";
+    def_id: string;
+    /** Walk parent_def_id and include the ancestors' evaluations. */
+    include_lineage?: boolean;
+}
+/** Input for {@link LoomcycleClient.evaluation}, discriminated by `op`. */
+export type EvaluationInput = EvaluationSubmitInput | EvaluationGetInput | EvaluationListForRunInput | EvaluationListForDefInput | EvaluationAggregateInput;
+/** What `submit` returns: the stored row's identity and the derived role. */
+export interface EvaluationSubmitResult {
+    eval_id: string;
+    run_id: string;
+    /** The definition version the run was running, denormalised at submit
+     *  time; `""` for a run that resolved through static config only. */
+    def_id: string;
+    emitter_role: EvaluationEmitterRole;
+    score: number;
+    /** RFC 3339 UTC. */
+    created_at: string;
+}
+/** One stored evaluation, as `get` and the `list_for_*` ops return it. */
+export interface EvaluationRecord {
+    eval_id: string;
+    run_id: string;
+    def_id: string;
+    score: number;
+    /** `null` when the submit carried none. */
+    dimensions: Record<string, number> | null;
+    /** `null` when the submit carried none. */
+    judgement: unknown;
+    rationale: string;
+    emitter_role: EvaluationEmitterRole;
+    emitter_agent_id: string;
+    emitter_run_id: string;
+    /** RFC 3339 UTC. */
+    created_at: string;
+}
+/** What `list_for_run` returns. An unknown run, or one the caller may not
+ *  read, lists nothing rather than refusing. */
+export interface EvaluationListForRunResult {
+    run_id: string;
+    evaluations: EvaluationRecord[];
+}
+/** What `list_for_def` returns. An unknown definition, or one the caller may
+ *  not read, lists nothing rather than refusing. */
+export interface EvaluationListForDefResult {
+    def_id: string;
+    evaluations: EvaluationRecord[];
+}
+/** Summary statistics over a set of scores. */
+export interface EvaluationScoreStats {
+    mean: number;
+    median: number;
+    min: number;
+    max: number;
+    latest: number;
+    count: number;
+}
+/** What `aggregate` returns. `count: 0` for an unknown definition. */
+export interface EvaluationAggregate {
+    def_id: string;
+    count: number;
+    score: EvaluationScoreStats;
+    /** Keyed by dimension name; only dimensions some row supplied. */
+    dimensions?: Record<string, EvaluationScoreStats>;
+    /** Keyed by emitter role. */
+    by_emitter_role?: Record<string, EvaluationScoreStats>;
+    lineage_included: boolean;
+}
 /** Volume access mode — read-only or read-write (RFC AH). */
 export type VolumeMode = "ro" | "rw";
 /** One row of {@link LoomcycleClient.listVolumes} (`GET /v1/_volumes`). */
@@ -3467,7 +3736,7 @@ export interface StreamUserRunStatesOptions {
      *  `parent_context.walk_id`).
      *
      *  A team walk's own run_id IS its walk id, so a caller that started a team
-     *  with `detach: true` passes back exactly the handle it already holds —
+     *  with `mode: "detach"` passes back exactly the handle it already holds —
      *  there is no second identifier and nothing to map. That is what makes a
      *  live view of one running workflow's agents a filter rather than a
      *  feature.
@@ -3635,17 +3904,6 @@ export interface EnsureMcpServerResult {
     /** Populated when `rediscover` ran: the number of tools discovered. */
     discoveredToolCount?: number;
 }
-/** Typed `overlay` for an {@link LoomcycleClient.agentDef} create/fork —
- *  the mutable subset of an agent definition. All fields optional (a fork
- *  overlays only what changes). The `[extra]` tail keeps it forward-compatible
- *  with fields the in-process tool may accept that the adapter doesn't model
- *  yet — the tool owns the authoritative schema; the adapter doesn't re-validate.
- *
- *  `code_body` is the inline code-js orchestrator source (RFC J): set it (with
- *  `provider: "code-js"`) to ingest a code agent through the substrate with NO
- *  host filesystem bind — the symmetry that makes code agents work in
- *  containers / pure-cloud. Requires `LOOMCYCLE_CODE_AGENTS_ENABLED=1` on the
- *  sidecar; create/fork refuses a non-empty `code_body` otherwise. */
 /** Per-agent Channel tool ACL (mirrors the sidecar `channels:` agent yaml).
  *  The Channel tool default-denies until publish/subscribe patterns are granted. */
 export interface AgentChannelACL {
@@ -3706,6 +3964,82 @@ export interface AgentDecision {
     /** The models a Decision call may name. Empty = every model the server lists. */
     models?: string[];
 }
+/** The `sampling` block of an {@link AgentDefOverlay}: {@link SamplingOptions}
+ *  in its wire spelling. The overlay is sent verbatim, so its nested blocks are
+ *  snake_case — the camelCase run-option types are converted by the client and
+ *  would be ignored here. A fork merges it per field; an explicit
+ *  `temperature: 0` is deterministic, not unset. */
+export interface AgentSampling {
+    temperature?: number;
+    top_p?: number;
+    top_k?: number;
+    frequency_penalty?: number;
+    presence_penalty?: number;
+    seed?: number;
+    stop?: string[];
+}
+/** The `compaction` block of an {@link AgentDefOverlay}: {@link CompactionOptions}
+ *  in its wire spelling, plus `memory_flush`, which only an agent definition
+ *  may set. A fork merges it per field. */
+export interface AgentCompaction {
+    enabled?: boolean;
+    target_percentage?: number;
+    keep_last_n?: number;
+    keep_first?: boolean;
+    autocompact_at_pct?: number;
+    model?: string;
+    /** Bank the span a compaction discards for the memory consolidator.
+     *  Per-agent only: a run cannot set it, because it makes the agent persist
+     *  memory its definition must authorize. */
+    memory_flush?: boolean;
+}
+/** The `context` block of an {@link AgentDefOverlay}: {@link ContextOptions}
+ *  in its wire spelling — see there for what each field does. A fork merges it
+ *  per field, and the spawn tree inherits it. */
+export interface AgentContext {
+    mode?: ContextOptions["mode"];
+    keep_last_n?: number;
+    reasoning?: ContextOptions["reasoning"];
+    recap_max_chars?: number;
+    model?: string;
+    autorecap_at_pct?: number;
+    state_schema?: Record<string, unknown>;
+    on_invalid_patch?: ContextOptions["onInvalidPatch"];
+    max_patch_retries?: number;
+    recall?: boolean;
+    harvest_to_memory?: boolean;
+}
+/** One entry of a per-tier candidate list (`models` on an
+ *  {@link AgentDefOverlay}). */
+export interface TierCandidate {
+    provider: string;
+    model: string;
+}
+/** A core memory block an agent carries (`core_blocks`). Its value is the
+ *  Memory entry `core/<label>` in the block's scope, rendered into the system
+ *  prompt. */
+export interface CoreBlock {
+    /** One path segment: no `/`, no whitespace. */
+    label: string;
+    /** Where the value lives. An `agent` block never crosses a spawn boundary. */
+    scope?: "agent" | "user" | "tenant";
+    /** Caps an agent write to the block, in bytes of the JSON value. 0 = only the
+     *  scope's `memory_quota_bytes`. */
+    limit_bytes?: number;
+    /** Operator-authored: the agent's writes to it are refused. */
+    read_only?: boolean;
+}
+/** Typed `overlay` for an {@link LoomcycleClient.agentDef} create/fork —
+ *  the mutable subset of an agent definition. All fields optional (a fork
+ *  overlays only what changes). The `[extra]` tail keeps it forward-compatible
+ *  with fields the in-process tool may accept that the adapter doesn't model
+ *  yet — the tool owns the authoritative schema; the adapter doesn't re-validate.
+ *
+ *  `code_body` is the inline code-js orchestrator source (RFC J): set it (with
+ *  `provider: "code-js"`) to ingest a code agent through the substrate with NO
+ *  host filesystem bind — the symmetry that makes code agents work in
+ *  containers / pure-cloud. Requires `LOOMCYCLE_CODE_AGENTS_ENABLED=1` on the
+ *  sidecar; create/fork refuses a non-empty `code_body` otherwise. */
 export interface AgentDefOverlay {
     provider?: string;
     model?: string;
@@ -3774,6 +4108,10 @@ export interface AgentDefOverlay {
      *  refused with `override_not_allowed`. Unset or `true` leaves them to the
      *  caller. A fork that does not send it keeps its parent's. */
     allow_overrides?: boolean;
+    /** `"ro"` gives the agent every ephemeral volume of its run read-only,
+     *  whatever mode the volume was created with, and the same to every agent
+     *  it spawns. The only value; a fork cannot clear it. */
+    ephemeral_volumes?: "ro";
     /** `"none"` makes every run of the agent a no-trace run: its content is
      *  delivered to the caller and stored nowhere. A fork that does not send it
      *  keeps its parent's, and `"default"` on a no-trace parent is refused. */
@@ -3788,6 +4126,88 @@ export interface AgentDefOverlay {
     channels?: AgentChannelACL;
     /** Interruption tool gate — `enabled: true` REQUIRED for the tool to work. */
     interruption?: AgentInterruptionACL;
+    /** The agent's own description — what an agent file's frontmatter
+     *  carries — and part of its content hash. Not the request's top-level
+     *  `description`, which is the rationale for this create/fork. */
+    description?: string;
+    /** Tier-routing override: the providers this agent's tier resolution tries,
+     *  in order, replacing the server's priority list. No effect on a
+     *  provider+model pin. */
+    providers?: string[];
+    /** Per-tier candidate lists, keyed by tier name. A tier set here replaces
+     *  the server's definition of that tier for this agent. */
+    models?: Record<string, TierCandidate[]>;
+    /** The web-search providers the WebSearch tool tries, in order. Empty uses
+     *  the server's default order. */
+    search_providers?: string[];
+    /** The context window this agent uses, in tokens — distinct from
+     *  `max_tokens`, the output cap. Sizes the window on a local model; on a
+     *  hosted one it can only lower the effective window. */
+    max_context_tokens?: number;
+    /** Lift the `max_iterations` cap for an LLM agent (cancel is the stop). A
+     *  fork can set it but cannot clear it. */
+    unbounded_iterations?: boolean;
+    /** Wall-clock budget, in seconds, for a code-js agent; 0 = the server's
+     *  default. Ignored by LLM agents. */
+    run_timeout_seconds?: number;
+    /** The system prompt before skill bodies are baked in. Defaults to
+     *  `system_prompt`; set it only to rebuild a prompt from a different base. */
+    system_prompt_base?: string;
+    /** Per-agent LLM sampling, merged per field over the parent's. */
+    sampling?: AgentSampling;
+    /** Context compaction in `append` mode, merged per field. */
+    compaction?: AgentCompaction;
+    /** How history is distilled, merged per field. */
+    context?: AgentContext;
+    /** Volumes the file and exec tools may resolve paths against. None declared
+     *  means `default`; declaring any confines the agent to exactly those. */
+    volumes?: string[];
+    /** SQL Memory scopes: `agent` | `user` | `run`. Unset means `["user"]`;
+     *  `["-*"]` grants none. */
+    sql_scopes?: string[];
+    /** Per-scope SQL database byte cap; 0 = the server's default. */
+    sql_quota_bytes?: number;
+    /** Whose past chats the History tool may read: `self` | `user` | `tenant` |
+     *  `global` (honored only for an admin). Unset means `["user"]`; `["-*"]`
+     *  grants none. */
+    history_scope?: string[];
+    /** Core memory blocks rendered into the system prompt. */
+    core_blocks?: CoreBlock[];
+    /** A sub-agent also receives its parent run's user- and tenant-scope core
+     *  blocks. */
+    inherit_core_blocks?: boolean;
+    /** Cap on all memory-injected prompt content, in tokens (estimated); 0 = the
+     *  server's default. */
+    memory_inject_max_tokens?: number;
+    /** Opt into the memory-usage protocol note. */
+    memory_protocol?: boolean;
+    /** Soft size cap, in bytes, the memory protocol asks the agent to keep its
+     *  index document under; 0 = the server's default. */
+    memory_index_max_bytes?: number;
+    /** Grant the Memory tool's consolidation control ops. Default-deny. */
+    memory_consolidation?: boolean;
+    /** Provisioning of the user-root memory document: `lazy` (default),
+     *  `force` or `suppress`. */
+    memory_roots?: "lazy" | "force" | "suppress";
+    /** Append the runtime's capability and tool-guide text to the system prompt
+     *  — for small models that under-read tool schemas. */
+    inject_tool_guide?: boolean;
+    /** Mark the agent as maintenance plumbing: its chats are excluded from
+     *  memory consolidation and hidden from History by default. A fork can set
+     *  it and cannot clear it. */
+    internal?: boolean;
+    /** Which AgentDef names this agent may fork / promote / retire: `self`,
+     *  `descendants`, `named:<name>` or `any`. Default-deny. */
+    agent_def_scopes?: string[];
+    /** Same closed set as `agent_def_scopes`, for ScheduleDef. Default-deny. */
+    schedule_def_scopes?: string[];
+    /** Same closed set as `agent_def_scopes`, for A2AServerCardDef. Default-deny. */
+    a2a_server_card_def_scopes?: string[];
+    /** Same closed set as `agent_def_scopes`, for A2AAgentDef. Default-deny. */
+    a2a_agent_def_scopes?: string[];
+    /** Which volumes this agent may create / delete / purge: `named:<volume>`
+     *  or `any`. Default-deny. */
+    volume_def_scopes?: string[];
     [extra: string]: unknown;
 }
 /** Options for {@link LoomcycleClient.ensureCodeAgent}. */
@@ -3832,6 +4252,440 @@ export interface MCPServerDefVerifyResult {
     /** True if an active row exists for this name. */
     deployed: boolean;
 }
+/** A HookDef's body: a code-js script the server runs in-process, or a webhook
+ *  it calls. The server refuses a code-js body carrying a url or headers, and
+ *  an http body carrying code. */
+export type HookDefBody = {
+    kind: "code-js";
+    /** A script defining `function hook(ev)` that returns the decision. */
+    code: string;
+} | {
+    kind: "http";
+    /** http:// or https://. */
+    url: string;
+    /** Sent with each call. A value may name a credential as
+     *  `$cred:<name>`, resolved for the run when the hook is called — keep
+     *  secrets there, not in the URL or a literal value. */
+    headers?: Record<string, string>;
+    /** Signs every delivery: the credential, as `"$cred:<name>"` and nothing
+     *  else, whose value keys the `X-Loomcycle-Signature` HMAC. It must be
+     *  usable for this `url` (unrestricted, or its `allowed_urls` covering
+     *  it). A secret that cannot be resolved fails the call; it is never
+     *  sent unsigned. Verify with `verifyLoomcycleDelivery`. */
+    signing_secret?: string;
+};
+/** Narrows a tool-event hook (`pre` / `post` / `post_failure`) within what it
+ *  is attached to. The server refuses it on any other event. */
+export type HookDefMatch = {
+    /** Exact tool names or trailing-`*` globs; empty = every tool. */
+    tools?: string[];
+};
+/** A HookDef's definition — the `overlay` of a `hookDef` create.
+ *
+ *  CLOSED on purpose (no index signature): the server decodes the overlay
+ *  strictly and refuses any key it does not know, so an unknown key here is a
+ *  compile error rather than a runtime refusal. A type alias rather than an
+ *  interface so it stays assignable to the loose `SubstrateToolInput.overlay`. */
+export type HookDefOverlay = {
+    /** Shown to whoever the hook denies, holds or rewrites — including a tenant
+     *  that did not write it. The body is never shown. At most 4 KiB. */
+    description?: string;
+    /** What the hook answers. Wherever it is attached, it is attached under this
+     *  event; `channel_publish` is a channel's own. */
+    event: HookEvent;
+    match?: HookDefMatch;
+    body: HookDefBody;
+    /** `"open"` (default): a failing hook lets the call through. `"closed"`: it
+     *  stops it. */
+    fail_mode?: HookFailMode;
+    /** Webhook: the whole call (default 5 s, max 60 s). code-js: each run of the
+     *  script (default 50 ms, max 1 s). */
+    timeout_ms?: number;
+};
+/** The `overlay` of a `hookDef` fork: each top-level field given replaces the
+ *  parent's, and `null` clears one (it decodes to the field's zero value). */
+export type HookDefForkOverlay = {
+    [K in keyof HookDefOverlay]?: HookDefOverlay[K] | null;
+};
+/** Typed input for {@link LoomcycleClient.hookDef}, one shape per op. */
+export type HookDefInput = {
+    op: "create";
+    name: string;
+    overlay: HookDefOverlay;
+    /** Free-text rationale (distinct from `overlay.description`). */
+    description?: string;
+    /** Default true. */
+    promote?: boolean;
+} | {
+    op: "fork";
+    name: string;
+    /** Default: the active version of `name` in your tenant. */
+    parent_def_id?: string;
+    overlay?: HookDefForkOverlay;
+    description?: string;
+    /** Default false. */
+    promote?: boolean;
+}
+/** By `def_id`, or the active version of `name`. */
+ | {
+    op: "get";
+    name?: string;
+    def_id?: string;
+} | {
+    op: "list";
+    name: string;
+} | {
+    op: "promote";
+    def_id: string;
+} | {
+    op: "retire";
+    def_id: string;
+    retired: boolean;
+} | {
+    op: "verify";
+    name: string;
+    content_sha256?: string;
+} | {
+    op: "delete";
+    name: string;
+};
+/** One HookDef version, as create / fork / get return it (`list` returns
+ *  `{name, versions: HookDefRowResponse[]}`). */
+export interface HookDefRowResponse {
+    def_id: string;
+    name: string;
+    version: number;
+    parent_def_id?: string;
+    description?: string;
+    created_at: string;
+    created_by_agent_id?: string;
+    retired: boolean;
+    /** "sha256:" + 64 hex chars, over the name and the normalized definition. */
+    content_sha256: string;
+    tenant_id?: string;
+    /** The stored definition, normalized: `fail_mode` filled in, empty fields
+     *  left out. */
+    definition: HookDefOverlay;
+    /** On create / fork: whether the new version was made active. */
+    promoted?: boolean;
+}
+/** Response shape for `HookDef verify`; same semantics as
+ *  {@link MCPServerDefVerifyResult}. Asking without `content_sha256` is how to
+ *  learn whether `name` is deployed at all: `deployed: false`, never an error. */
+export interface HookDefVerifyResult {
+    matches: boolean;
+    current_sha256: string;
+    current_def_id: string;
+    version: number;
+    name: string;
+    deployed: boolean;
+}
+/** Options for the strictly-typed create methods
+ *  ({@link LoomcycleClient.createHookDef},
+ *  {@link LoomcycleClient.createScheduleDef},
+ *  {@link LoomcycleClient.createWebhookDef}). */
+export interface CreateDefOptions {
+    /** Free-text rationale stored on the version (not part of the definition). */
+    description?: string;
+    /** Make the new version active. Server default: true. */
+    promote?: boolean;
+    signal?: AbortSignal;
+}
+/** Options for the strictly-typed fork methods. */
+export interface ForkDefOptions extends CreateDefOptions {
+    /** The version to fork. Default: the active version of the name in your
+     *  tenant (ScheduleDef / WebhookDef fall back to the yaml template of that
+     *  name). Server default for `promote` on a fork: false for HookDef, true
+     *  for ScheduleDef and WebhookDef. */
+    parentDefId?: string;
+}
+/** Options for {@link LoomcycleClient.ensureHookDef}. */
+export interface EnsureHookDefOptions {
+    /** Free-text rationale stored on a NEW version. Not part of the definition,
+     *  so changing only this does not mint one. */
+    description?: string;
+    signal?: AbortSignal;
+}
+/** Result of {@link LoomcycleClient.ensureHookDef}. */
+export interface EnsureHookDefResult {
+    name: string;
+    defId: string;
+    version: number;
+    /** True when this call created a version; false when the active version
+     *  already carried the same definition. */
+    changed: boolean;
+}
+/** One `on_complete` entry of a ScheduleDef or WebhookDef: what the server
+ *  does after the triggered run finishes. Mirrors config.ScheduledRunHook. */
+export type ScheduledRunHook = {
+    kind: "channel.publish";
+    channel: string;
+    payload?: Record<string, unknown>;
+} | {
+    kind: "mcp.call";
+    server: string;
+    tool: string;
+    args?: Record<string, unknown>;
+} | {
+    kind: "memory.set";
+    scope: string;
+    key: string;
+    /** The value written. */
+    payload?: Record<string, unknown>;
+};
+/** One block of a scheduled run's prompt. Only text survives into the run, so
+ *  there is no image form here. */
+export interface ScheduledRunPromptContent {
+    /** Default `"trusted-text"`. `"untrusted-block"` wraps the text as external
+     *  input. */
+    type?: "trusted-text" | "untrusted-block";
+    text: string;
+}
+/** One segment of a scheduled run's prompt. */
+export interface ScheduledRunPromptSegment {
+    role: "system" | "user";
+    content: ScheduledRunPromptContent[];
+}
+/** The `overlay` of a `scheduleDef` create / fork. On fork, a field the
+ *  overlay leaves out keeps the parent's; the credential maps merge key by key.
+ *
+ *  The `[extra]` tail stays because the server decodes the overlay loosely and
+ *  ignores keys it does not know — including the fields it stamps itself
+ *  (`operator_key_restricted`, `isolated`, `capture_disabled`,
+ *  `operator_layer`), which an overlay can neither set nor clear. */
+export interface ScheduleDefOverlay {
+    /** `"run"` (default) invokes `agent`; `"channel"` publishes a tick to
+     *  `channel` and starts no run; `"team"` starts a detached walk of `team`. */
+    delivery?: "run" | "channel" | "team";
+    channel?: string;
+    agent?: string;
+    prompt?: ScheduledRunPromptSegment[];
+    /** A 5-field cron expression. Setting it clears `user_tier_schedules`. */
+    schedule?: string;
+    /** Cron per user tier, for a template a fork picks from with `user_tier`.
+     *  Setting it clears `schedule`. */
+    user_tier_schedules?: Record<string, string>;
+    required_credentials?: string[];
+    /** IANA zone the cron is read in, e.g. `"Europe/Berlin"`. Default UTC. */
+    timezone?: string;
+    enabled?: boolean;
+    /** 0–1000: run the newest N slots missed during an outage, in slot order.
+     *  0 (default) collapses them into one fire. */
+    catch_up_max?: number;
+    /** N > 0 retires the def after its Nth fire; 0 = unbounded (a fork sends 0
+     *  to lift a parent's cap). */
+    max_fires?: number;
+    user_id?: string;
+    /** What a slot does while the previous run is still going. Default
+     *  `"forbid"`; refused on `delivery: "channel"`. */
+    concurrency_policy?: "forbid" | "allow" | "replace";
+    user_tier?: string;
+    /** Credential key → value, handed to the fired run. */
+    user_credentials?: Record<string, string>;
+    /** Credential key → env-var NAME the scheduler reads it from (the variable
+     *  must be on LOOMCYCLE_SCHEDULER_ENV_ALLOWLIST). */
+    user_credentials_from_env?: Record<string, string>;
+    on_complete?: ScheduledRunHook[];
+    /** Non-secret metadata the agent receives as trusted. */
+    metadata?: Record<string, unknown>;
+    /** The tenant fired runs execute in. Your own unless you are an admin;
+     *  omit it to use yours. */
+    tenant_id?: string;
+    /** `delivery: "team"` only: the team, its variables as literals, and the
+     *  walk's optional input. */
+    team?: string;
+    vars?: Record<string, string>;
+    input?: string;
+    [extra: string]: unknown;
+}
+/** Typed input for {@link LoomcycleClient.scheduleDef}, one shape per op. */
+export type ScheduleDefInput = {
+    op: "create" | "fork";
+    name: string;
+    /** fork only. Default: the active version of `name`, or its yaml
+     *  template. */
+    parent_def_id?: string;
+    overlay?: ScheduleDefOverlay;
+    description?: string;
+    /** Default true on both create and fork. */
+    promote?: boolean;
+} | {
+    op: "get";
+    def_id: string;
+} | {
+    op: "list";
+    name: string;
+} | {
+    op: "retire";
+    def_id: string;
+    retired: boolean;
+}
+/** Fork `def_id` with `hook` appended to its `on_complete`. */
+ | {
+    op: "add_hook";
+    def_id: string;
+    hook: ScheduledRunHook;
+}
+/** Fork `def_id` without its `on_complete[hook_index]` (0-based). */
+ | {
+    op: "remove_hook";
+    def_id: string;
+    hook_index: number;
+};
+/** One ScheduleDef version, as create / fork return it. */
+export interface ScheduleDefRowResponse {
+    def_id: string;
+    name: string;
+    version: number;
+    parent_def_id?: string;
+    description?: string;
+    created_at: string;
+    created_by_agent_id?: string;
+    retired: boolean;
+    bootstrapped_from_static: boolean;
+    /** The stored definition, including the fields the server stamps. */
+    definition: ScheduleDefOverlay;
+    /** Whether the new version was made active. */
+    promoted?: boolean;
+    /** Credential keys a snapshot stripped that this write did not re-supply;
+     *  the def stays disabled until they are. */
+    disabled_until_credentials_supplied?: string[];
+    /** Why a key you did name did not count, one line per key. */
+    unusable_credentials?: string[];
+}
+/** How a WebhookDef authenticates an inbound request. */
+export interface WebhookDefAuth {
+    /** `"hmac"` (default) verifies a body signature; `"bearer"` a token;
+     *  `"none"` neither. */
+    kind?: "hmac" | "bearer" | "none";
+    /** hmac only; the only one implemented. */
+    algorithm?: "sha256";
+    /** The header carrying the signature. */
+    header?: string;
+    /** Env-var NAME holding the hmac secret — never the secret itself. */
+    signing_secret_env?: string;
+    /** The header naming each delivery, for dedup; without it a body hash is
+     *  the delivery's identity. */
+    delivery_id_header?: string;
+    /** Env-var NAME holding the bearer token — never the token itself. */
+    bearer_token_env?: string;
+    /** The verification secret as a stored credential, `"$cred:<name>"` — a
+     *  tenant credential of the definition's own tenant, resolved on each
+     *  delivery so a rotation needs no restart. Takes the place of
+     *  `signing_secret_env` / `bearer_token_env`: set one form, not both. A
+     *  literal is refused. */
+    secret?: string;
+    /** The previous secret during a rotation, also `"$cred:<name>"`: a delivery
+     *  verified by either is accepted. */
+    previous_secret?: string;
+}
+/** Inbound request rate bound for one webhook. */
+export interface WebhookDefRateLimit {
+    requests_per_minute?: number;
+    burst?: number;
+}
+/** Hold the inbound request open until the run finishes (or the timeout). */
+export interface WebhookDefSyncResponse {
+    enabled?: boolean;
+    timeout_ms?: number;
+}
+/** The `overlay` of a `webhookDef` create / fork. On fork, a field the overlay
+ *  leaves out keeps the parent's; naming exactly one of `agent` / `channel` /
+ *  `team` clears the other two.
+ *
+ *  The `[extra]` tail stays for now: the server decodes the overlay loosely
+ *  and ignores keys it does not know — including the fields it stamps itself
+ *  (`operator_key_restricted`, `isolated`, `capture_disabled`). */
+export interface WebhookDefOverlay {
+    /** An overlay can only turn a webhook on; to turn one off, restate it. */
+    enabled?: boolean;
+    /** `"spawn"` (default) starts a run of `agent`; `"channel"` publishes the
+     *  body to `channel`; `"team"` starts a detached walk of `team` with the body
+     *  as its input. */
+    delivery?: "spawn" | "channel" | "team";
+    agent?: string;
+    channel?: string;
+    auth?: WebhookDefAuth;
+    rate_limit?: WebhookDefRateLimit;
+    body_size_limit_bytes?: number;
+    /** Credential key → env-var NAME the receiver reads it from. */
+    user_credentials_from_env?: Record<string, string>;
+    /** Credential key → value, handed to the run. */
+    user_credentials?: Record<string, string>;
+    /** Pins the started run's user tier; a delivery never chooses it. Must be
+     *  one of the server's user tiers. */
+    user_tier?: string;
+    /** A forge preset — `"github"`, `"gitea"` or `"gitlab"` — supplying
+     *  defaults for the auth kind and headers, the event header, the ping and
+     *  the shapes of the events it knows. A field set here overrides it. */
+    provider?: string;
+    /** The request header naming a delivery's event. */
+    event_header?: string;
+    /** When set, the only events that start anything: another is answered 202
+     *  `ignored`, the provider's ping 200, and a listed event counts only when
+     *  the signed body has its shape. Unset: every delivery is handled. */
+    events?: string[];
+    /** The JSONPaths the body of a listed event must hold, for an event the
+     *  provider has no shape for, or in place of its. A fork merges key by key;
+     *  an empty list removes that event's shape. */
+    event_shapes?: Record<string, string[]>;
+    /** Non-secret metadata the agent receives as trusted. */
+    metadata?: Record<string, unknown>;
+    /** The tenant spawned runs execute in — taken from the def, never from the
+     *  payload. Your own unless you are an admin; omit it to use yours. */
+    tenant_id?: string;
+    /** Target → JSONPath into the request body (`$`, `.key` and `[N]` only).
+     *  Targets: `goal`, `user_id`, `user_credentials.<KEY>`,
+     *  `run_metadata.<key>`. */
+    payload_mapping?: Record<string, string>;
+    sync_response?: WebhookDefSyncResponse;
+    on_complete?: ScheduledRunHook[];
+    /** `delivery: "team"` only: the team, and each variable as a JSONPath into
+     *  the body (`$`, `.key` and `[N]` only). */
+    team?: string;
+    vars?: Record<string, string>;
+    [extra: string]: unknown;
+}
+/** One WebhookDef version, as create / fork return it. */
+export interface WebhookDefRowResponse {
+    def_id: string;
+    name: string;
+    version: number;
+    parent_def_id?: string;
+    description?: string;
+    created_at: string;
+    created_by_agent_id?: string;
+    retired: boolean;
+    bootstrapped_from_static: boolean;
+    /** The stored definition, including the fields the server stamps. */
+    definition: WebhookDefOverlay;
+    promoted?: boolean;
+    /** Same meaning as on {@link ScheduleDefRowResponse}. */
+    disabled_until_credentials_supplied?: string[];
+    unusable_credentials?: string[];
+}
+/** Typed input for {@link LoomcycleClient.webhookDef}, one shape per op. */
+export type WebhookDefInput = {
+    op: "create" | "fork";
+    name: string;
+    /** fork only. Default: the active version of `name`, or its yaml
+     *  template. */
+    parent_def_id?: string;
+    overlay?: WebhookDefOverlay;
+    description?: string;
+    /** Default true on both create and fork. */
+    promote?: boolean;
+} | {
+    op: "get";
+    def_id: string;
+} | {
+    op: "list";
+    name: string;
+} | {
+    op: "retire";
+    def_id: string;
+    retired: boolean;
+};
 /** Static-side agent definition body. Snake_case keys mirror
  *  internal/lookup.SubstrateAgentDef so substrate-side and static-side
  *  definitions share one renderer. Forward-compatible: unknown fields
@@ -4268,6 +5122,12 @@ export interface CredentialMeta {
     updated_at?: string;
     expires_at?: string;
     status?: string;
+    /** The https URLs the value may be sent to, in canonical form. Absent for
+     *  an unrestricted credential; `[]` for one that is sent nowhere. */
+    allowed_urls?: string[];
+    /** The user name sent with the value where a destination takes one (HTTP
+     *  basic auth for a git source). Absent when none is stored. */
+    username?: string;
 }
 /** CredentialListResponse is the {op:list} result: metadata for the given scope. */
 export interface CredentialListResponse {
@@ -4392,3 +5252,343 @@ export interface DecisionModelsResponse {
     default: string;
     models: DecisionModel[];
 }
+/** One name's version roll-up from a `list*DefNames` method. Shared by every
+ *  def family except OperatorTokenDef ({@link OperatorTokenDefNameSummary}). */
+export interface DefNameSummary {
+    name: string;
+    /** The owning tenant; absent for the shared "" tenant. */
+    tenant_id?: string;
+    version_count: number;
+    active_def_id?: string;
+    latest_version: number;
+    /** When the newest version was created (RFC 3339). */
+    last_updated: string;
+    /** Versions not retired. Reported by the AgentDef, SkillDef, HookDef and
+     *  MCPServerDef families only. */
+    live_version_count?: number;
+    /** The active version is retired. Same families as `live_version_count`. */
+    active_retired?: boolean;
+}
+/** Response of the `list*DefNames` methods. `names` is `[]`, never `null`,
+ *  when nothing is declared. */
+export interface DefNamesResponse {
+    names: DefNameSummary[];
+}
+/** One token name's summary from {@link LoomcycleClient.listOperatorTokenDefNames}.
+ *  Carries no secret material. */
+export interface OperatorTokenDefNameSummary {
+    name: string;
+    tenant_id: string;
+    subject: string;
+    /** Every token minted under the name, rotated and retired ones included. */
+    token_count: number;
+    /** A non-retired token exists. */
+    has_current: boolean;
+    last_updated: string;
+}
+/** Response of {@link LoomcycleClient.listOperatorTokenDefNames}. */
+export interface OperatorTokenDefNamesResponse {
+    names: OperatorTokenDefNameSummary[];
+}
+/** One schedule in {@link LoomcycleClient.listAllSchedules}: a static yaml
+ *  `scheduled_runs` entry, a ScheduleDef, or both under one name. */
+export interface ScheduleListEntry {
+    name: string;
+    source: "static-only" | "dynamic-only" | "both";
+    in_static: boolean;
+    in_substrate: boolean;
+    version_count?: number;
+    /** The def id the per-schedule methods take. Absent for a static-only
+     *  schedule, which has no ScheduleDef to address. */
+    active_def_id?: string;
+    latest_version?: number;
+    /** When the newest ScheduleDef version was created. Absent for a
+     *  static-only schedule. */
+    last_updated?: string;
+    /** The yaml definition, for a static entry. */
+    static_definition?: unknown;
+}
+/** Response of {@link LoomcycleClient.listAllSchedules}. */
+export interface ScheduleListResponse {
+    entries: ScheduleListEntry[];
+}
+/** A run a schedule started and has not finished. */
+export interface ScheduleActiveRun {
+    def_id: string;
+    run_id: string;
+    /** The slot the run was fired for. */
+    slot_at: string;
+    /** Fired for a missed slot rather than a live one. */
+    catch_up?: boolean;
+    started_at: string;
+    /** The replica that claimed the slot; absent outside cluster mode. */
+    claimed_by?: string;
+}
+/** A schedule's runtime state from {@link LoomcycleClient.getScheduleState}.
+ *  Credentials never appear here. An optional instant is absent when unset —
+ *  test for presence. (A server before the fix that dropped them sent
+ *  `last_run_at` and `paused_until` as "0001-01-01T00:00:00Z" instead.) */
+export interface ScheduleStateView {
+    def_id: string;
+    /** Absent until the schedule first fires. */
+    last_run_at?: string;
+    last_run_id?: string;
+    /** completed | failed | cancelled | rejected | running | skipped_overlap | skipped… */
+    last_status?: string;
+    last_error?: string;
+    next_run_at: string;
+    /** Present while paused. {@link LoomcycleClient.pauseSchedule} sets it about
+     *  100 years ahead: an indefinite pause. */
+    paused_until?: string;
+    /** Fires so far, the count `max_fires` is measured against. */
+    fire_count: number;
+    /** The last claim: which slot, which replica, when. */
+    slot_at?: string;
+    claimed_by?: string;
+    claimed_at?: string;
+    /** When the last tracked run finished. */
+    finished_at?: string;
+    /** Present while a `catch_up_max` backlog drains: its newest slot. */
+    catch_up_until?: string;
+    /** Slots the last outage dropped (older than `catch_up_max`). */
+    missed_slots?: number;
+    /** Every run the schedule started and has not finished — `[]`, never absent. */
+    active_runs: ScheduleActiveRun[];
+}
+/** Result of {@link LoomcycleClient.runScheduleNow}. The run starts on the
+ *  scheduler's next tick, not during the call. */
+export interface ScheduleRunNowResult {
+    def_id: string;
+    scheduled: "next-tick";
+}
+/** Result of {@link LoomcycleClient.pauseSchedule} / {@link LoomcycleClient.resumeSchedule}. */
+export interface SchedulePauseResult {
+    def_id: string;
+    paused: boolean;
+}
+/** One configured model alias (the top-level `models:` map). */
+export interface ModelAlias {
+    provider: string;
+    model: string;
+    /** chat | decision | embedder. Absent for an untagged alias, which is a chat
+     *  model. */
+    kind?: string;
+}
+/** Response of {@link LoomcycleClient.listModels}: alias name → target. */
+export interface ModelAliasesResponse {
+    aliases: Record<string, ModelAlias>;
+}
+/** A candidate's throughput estimate. `multiplier` is what a scaled timeout
+ *  would be multiplied by. */
+export interface RoutingThroughput {
+    slowdown?: number;
+    multiplier: number;
+    samples: number;
+    source: string;
+    decode_tps?: number;
+    prefill_tps?: number;
+    ttft_ms?: number;
+    cold_load_ms?: number;
+    /** Admin only. */
+    queue_ms_p50?: number;
+    max_multiplier?: number;
+}
+/** One candidate in a routing cascade. */
+export interface RoutingCandidate {
+    provider: string;
+    model: string;
+    /** First in the displayed cascade. */
+    primary: boolean;
+    available?: boolean;
+    /** The first available candidate: what a run resolves to now. */
+    selected?: boolean;
+    stalled?: boolean;
+    rate_limited?: boolean;
+    reachable?: boolean;
+    /** Absent when throughput estimation is off. */
+    throughput?: RoutingThroughput;
+}
+/** One tier's ordered cascade, top first. */
+export interface RoutingTier {
+    /** low | middle | high */
+    tier: string;
+    cascade: RoutingCandidate[];
+}
+/** One user tier's tiers. */
+export interface RoutingUserTier {
+    /** "" when no user tiers are configured. */
+    name: string;
+    tiers: RoutingTier[];
+}
+/** One provider in the active-providers header. */
+export interface RoutingProvider {
+    provider: string;
+    reachable: boolean;
+    excluded: boolean;
+    /** The raw probe error — admin only. */
+    last_error?: string;
+}
+/** One web-search provider in the search cascade. */
+export interface SearchRoutingProvider {
+    provider: string;
+    primary: boolean;
+    /** This caller has a usable key. */
+    keyable?: boolean;
+    /** Keyable and not in a failure cooldown. */
+    available?: boolean;
+    selected?: boolean;
+    reachable?: boolean;
+    /** Admin only. */
+    last_error?: string;
+}
+/** Response of {@link LoomcycleClient.getRouting}. */
+export interface RoutingResponse {
+    generated_at: string;
+    /** The caller gets the admin view: raw `last_error`, nothing filtered. */
+    admin: boolean;
+    providers?: RoutingProvider[];
+    user_tiers: RoutingUserTier[];
+    /** The operator-key gate is on and this tenant's view is filtered to the
+     *  providers it can key itself. */
+    operator_key_restricted?: boolean;
+    /** `timeout_scaling.mode` when throughput estimation is on. */
+    throughput_mode?: string;
+    /** Absent when no search providers are configured. */
+    search?: SearchRoutingProvider[];
+}
+/** Response of {@link LoomcycleClient.listProviderModels}: a live listing from
+ *  the provider, not the cached probe matrix. */
+export interface ProviderModelsResponse {
+    provider: string;
+    fetched_at: string;
+    duration_ms: number;
+    /** Provider-native model ids. `[]` when the provider answered with none. */
+    models: string[];
+}
+/** Options of {@link LoomcycleClient.createTeam}. */
+export interface CreateTeamOptions {
+    signal?: AbortSignal;
+    /** Make the new version the team's active one. The server default is true
+     *  for a create; pass `false` to author it without putting it in force
+     *  (then {@link LoomcycleClient.promoteTeam}). */
+    promote?: boolean;
+    /** Free-text rationale stored on the version. */
+    description?: string;
+}
+/** Options of {@link LoomcycleClient.forkTeam}. Note `promote` defaults the
+ *  other way from a create: false. */
+export interface ForkTeamOptions extends CreateTeamOptions {
+    /** Make the new version the team's active one. The server default is false:
+     *  a fork is authored first and put in force with
+     *  {@link LoomcycleClient.promoteTeam}. */
+    promote?: boolean;
+    /** Fork this version instead of the name's active one. */
+    parentDefId?: string;
+}
+/** The kind of change a {@link MemoryChange} names. `memory.*` arrive on
+ *  {@link LoomcycleClient.streamMemoryChanges}, `document.chunk.*` on
+ *  {@link LoomcycleClient.streamDocumentChanges}. Mirrors the runtime's
+ *  `store.MemoryChangeType`. */
+export type MemoryChangeType = "memory.set" | "memory.delete" | "memory.scope_deleted" | "document.chunk.updated" | "document.chunk.deleted";
+/** The memory scope a change landed in. `global` is listed because the
+ *  runtime's scope enum has it and the feed passes the written scope through
+ *  unchanged, not because Memory writes it today. */
+export type MemoryChangeScope = "agent" | "user" | "tenant" | "global";
+/** One change coordinate, exactly as the runtime's `store.MemoryChange`
+ *  serialises.
+ *
+ *  VALUE-FREE by design: it names WHAT changed, never the value — pull the
+ *  current value through the data API (`getMemoryEntry`, `document`). `key` is
+ *  set for `memory.set` / `memory.delete`; `chunk_id` for `document.chunk.*`;
+ *  neither for `memory.scope_deleted`, which covers the whole scope. */
+export interface MemoryChange {
+    /** Monotonic cursor. Persist the last one you processed and pass it back as
+     *  `since` to resume after a disconnect. */
+    seq: number;
+    /** The caller's own tenant — the feed is never cross-tenant. Omitted for
+     *  the shared "" tenant. */
+    tenant?: string;
+    type: MemoryChangeType;
+    scope: MemoryChangeScope;
+    scope_id: string;
+    key?: string;
+    chunk_id?: string;
+    /** RFC3339 time of the write. */
+    at: string;
+}
+/** What the runtime's embedder has actually been doing, since boot. Mirrors
+ *  `providers.EmbedderHealth`.
+ *
+ *  Carried on the change feed because an embedding failure on a content write
+ *  is NOT fatal — the body is stored and the embedding skipped — so an
+ *  embedder outage shows as a perfectly busy feed over rows that are no longer
+ *  searchable. `untried` is "configured, nothing embedded yet", not a warning;
+ *  `absent` is "no embedder configured". */
+export interface EmbedderHealth {
+    state: "absent" | "untried" | "ok" | "failing";
+    provider?: string;
+    model?: string;
+    calls: number;
+    /** Failed embeddings since boot — roughly how many rows need
+     *  `backfillEmbeddings` to become searchable. */
+    failures: number;
+    /** A classified failure kind, never the raw error text (which can carry an
+     *  address). */
+    last_failure_kind?: string;
+    /** Unix seconds; absent when never. */
+    last_ok_unix?: number;
+    last_failure_unix?: number;
+}
+/** The opening frame of a change feed (`event: feed`). */
+export interface ChangeFeedStatus {
+    /** Whether writes are being captured at all. `false` means the server runs
+     *  without `LOOMCYCLE_MEMORY_CHANGES_ENABLED`: the stream stays open and
+     *  idles, and NO change will ever arrive — check this before waiting. */
+    enabled: boolean;
+    /** The cursor the server accepted. `0` when `since` was absent OR
+     *  unparseable — the server does not reject a bad cursor. */
+    since: number;
+    /** Reported beside `enabled`, never folded into it: capturing and embedding
+     *  fail independently. Absent on a runtime older than the field. */
+    embedder?: EmbedderHealth;
+}
+/** A change-feed `event: error` frame: the server could not read its change
+ *  log. NON-FATAL — the stream stays open, the server keeps retrying with
+ *  backoff, and its cursor does not advance, so change frames resume after
+ *  recovery without a gap. Sent once per failure streak, not per retry. */
+export interface ChangeFeedError {
+    /** Machine-readable; `store_unavailable` today. Branch on this. */
+    code: string;
+    /** Human-readable description. */
+    error: string;
+}
+/** Yielded by {@link LoomcycleClient.streamMemoryChanges} and
+ *  {@link LoomcycleClient.streamDocumentChanges}.
+ *
+ *  Same `{ kind, payload }` shape as {@link RunStateStreamItem}: the first
+ *  item is `{ kind: "feed" }`, then one `{ kind: "change" }` per change, with
+ *  an occasional `{ kind: "error" }` (see {@link ChangeFeedError}) when the
+ *  server cannot read its change log — iteration continues past it. `kind`
+ *  rather than `type` so the wrapper's discriminator cannot be confused with
+ *  the change's own `payload.type`. */
+export type ChangeFeedFrame = {
+    kind: "feed";
+    payload: ChangeFeedStatus;
+} | {
+    kind: "change";
+    payload: MemoryChange;
+} | {
+    kind: "error";
+    payload: ChangeFeedError;
+};
+/** Options for {@link LoomcycleClient.streamMemoryChanges} /
+ *  {@link LoomcycleClient.streamDocumentChanges}. */
+export interface StreamChangesOptions {
+    /** Resume cursor: deliver only changes with `seq` greater than this. Omit
+     *  (or `0`) to start from the oldest change the server still retains. Must
+     *  be a non-negative integer — the client throws rather than send a value
+     *  the server would silently read as `0` and replay everything. */
+    since?: number;
+    /** Abort to close the stream; the iterator then throws an `AbortError`. */
+    signal?: AbortSignal;
+}