@loomcycle/client 1.121.0 → 1.123.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" | "queued" | "admitted" | "call_queued" | "call_admitted" | "_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" | "file_captured" | "transcription" | "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;
@@ -445,6 +445,60 @@ export interface AdmissionInfo {
     /** On `call_queued` / `call_admitted`: the call lane's model kind (`"chat"`). */
     kind?: string;
 }
+/** Payload on `event: file_captured`: a file a tool returned, as the runtime
+ *  kept it in the run's inbox volume. Never the bytes, never a URL's query. */
+export interface FileCapturedInfo {
+    /** The file's reference, `volume:inbox:<dir>/<name>`. */
+    ref: string;
+    media_type: string;
+    /** Length in bytes. */
+    size: number;
+    /** Hex SHA-256 of the bytes. */
+    sha256: string;
+    /** Which producer returned it: `mcp:<server>/<tool>`, `http`, `webfetch` or
+     *  `download:<host>`. */
+    origin: string;
+    /** The run whose tool call returned it (a sub-agent's capture is reported
+     *  on the tree's stream). */
+    run_id?: string;
+}
+/** Payload on `event: transcription`: one OCR or speech-to-text pass a File
+ *  tool call made over an inbox file. Never the transcribed text. */
+export interface TranscriptionInfo {
+    /** The source file, `volume:inbox:<dir>/<name>`. */
+    ref: string;
+    /** The Markdown the pass wrote, when it wrote one. */
+    out?: string;
+    /** `"ocr"` or `"stt"`. */
+    purpose: string;
+    /** The configured engine that ran: `"vision"`, `"openai-audio"`,
+     *  `"command"`, …. */
+    engine: string;
+    /** The concrete provider/model pair the engine called, when it called one. */
+    provider?: string;
+    model?: string;
+    /** Pages sent to an OCR engine. */
+    pages?: number;
+    /** Audio duration sent to a speech-to-text engine, in seconds. */
+    seconds?: number;
+    input_tokens?: number;
+    output_tokens?: number;
+    /** The priced cost in `currency`. Absent when the pair is unpriced, which is
+     *  not the same as free. */
+    cost?: number;
+    currency?: string;
+    /** `"ok"`, `"partial"` (a cap or an engine error stopped it after some
+     *  units; what was written stays) or `"failed"`. */
+    status: string;
+    /** An estimate: no engine was called and nothing was spent. */
+    dry_run?: boolean;
+    /** The run whose tool call made the pass. */
+    run_id?: string;
+    /** Why the pass failed or stopped early (set on `"failed"`, and on
+     *  `"partial"` when a cap or an engine error stopped it). Never a secret, a
+     *  URL's query or the file's content. */
+    error?: string;
+}
 export interface LimitInfo {
     /** Which axis tripped: "operator" | "tenant" | "user". */
     scope: string;
@@ -685,6 +739,12 @@ 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: file_captured` — a file a tool returned, kept in the
+     *  run's inbox. Nil on all other event types. */
+    file?: FileCapturedInfo;
+    /** Payload on `event: transcription` — one OCR or speech-to-text pass a
+     *  File tool call made. Nil on all other event types. */
+    transcription?: TranscriptionInfo;
     /** 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
@@ -1499,6 +1559,15 @@ export interface RunSpec {
          *  own `crypto_scopes` were narrowed to, and are narrowed to again on
          *  resume. Absent: the parent held none. */
         crypto_scopes?: string[];
+        /** The parent run's shell-credential narrowing at spawn (RFC EW): the
+         *  names the child's own `shell_credentials` were narrowed to, and are
+         *  narrowed to again on resume. Absent: the parent narrowed nothing. `[]`:
+         *  the parent allowed none. */
+        shell_credentials?: string[];
+        /** The parent run's Git network grant at spawn (RFC FB): the operations
+         *  the child's own `git_remote` was narrowed to, and is narrowed to again
+         *  on resume. Absent: the parent had none. */
+        git_remote?: Array<'fetch' | 'push'>;
         /** The override offer the child passes on to its own children: its
          *  parent's, unchanged, so a resume offers what the live child did. Only
          *  a child of the offering run's definition (`def_id`, else `agent_name`)
@@ -1801,6 +1870,22 @@ export interface ErasureResidue {
     sessions_examined: number;
     truncated: boolean;
 }
+/** One bearer token an erasure names: its def id and name, never the bearer. */
+export interface ErasureTokenRef {
+    def_id: string;
+    name: string;
+}
+/**
+ * What an erasure removes from the subject's authority — in a report or a dry
+ * run, what it would: the groups the subject leaves, the lists its bindings
+ * (and its tokens' bindings) named, and the member tokens revoked.
+ * Config-declared rows are not listed; the store cannot remove them.
+ */
+export interface ErasureAccess {
+    groups: string[];
+    lists: string[];
+    tokens: ErasureTokenRef[];
+}
 /** Result of {@link LoomcycleClient.erasureReport} (RFC BL P5). */
 export interface ErasureReport {
     tenant: string;
@@ -1808,6 +1893,7 @@ export interface ErasureReport {
     tier1_covered: ErasureTier;
     tier2_uncovered: ErasureTier;
     tier3_residue: ErasureResidue;
+    access: ErasureAccess;
     notes: string[];
     /** Planes that could not be READ. Non-empty means every count is a lower bound. */
     errors?: string[];
@@ -1821,6 +1907,8 @@ export interface ErasureResult {
     /** Plane -> why it was kept. Never empty. */
     retained: Record<string, string>;
     residue: ErasureResidue;
+    /** The groups, lists and member tokens removed (or, in a dry run, that would be). */
+    access: ErasureAccess;
     errors?: string[];
     notes: string[];
 }
@@ -2059,6 +2147,43 @@ export interface WhoamiResponse {
     is_admin: boolean;
     legacy: boolean;
     open_mode?: boolean;
+    /** The deployment's access-control rollout mode: `compat`, `shadow` or
+     *  `enforce`. Absent on a server that predates access-control lists. */
+    acl_mode?: AclMode;
+    /** The caller's groups, transitive. Absent when none were resolved. */
+    groups?: string[];
+    /** The version of the caller's compiled access-control set. Absent in open
+     *  mode and when the set could not be resolved. */
+    acl_version?: number;
+    /** What the caller may reach, as the server's own gates would answer it.
+     *  Absent on a server that predates the summary. */
+    effective?: WhoamiEffective;
+    /** How the caller signed in. Absent on a server that predates Web UI
+     *  sessions. */
+    auth?: WhoamiAuth;
+}
+/** GET /v1/_me's sign-in block. `mode` is always present; the rest only when
+ *  a Web UI session (not a bearer) authenticated the request. */
+export interface WhoamiAuth {
+    /** `open` (no credential configured), `token` or `strict`. */
+    mode: "open" | "token" | "strict";
+    /** The configured gate the session was created through. */
+    gate?: string;
+    /** The authentication methods the gate used, e.g. `["bearer"]`. */
+    amr?: string[];
+    /** When the session's login happened (RFC 3339). */
+    auth_time?: string;
+    /** When the session stops authenticating unless renewed by activity. */
+    session_expires_at?: string;
+}
+/** GET /v1/_me's capability summary. Bounded and non-secret: a fixed list of
+ *  Web UI pages, no per-instance data. */
+export interface WhoamiEffective {
+    /** Per Web UI page id (`run`, `runs`, `channels`, `access`, `users`, …),
+     *  whether a request to the route the page loads first would pass the
+     *  route's scope gate and its access-control question in the current mode.
+     *  Every page is true in open mode. */
+    surfaces: Record<string, boolean>;
 }
 export type RuntimeStateStatus = "running" | "pausing" | "paused";
 /** A timed override of an agent's no-trace mode: until `until`, runs of
@@ -2259,6 +2384,49 @@ export interface MemorySearchInput {
      *  while `"require"` is a real filter. A tight `"require"` window is how a
      *  scope that holds the answer comes back empty. */
     when?: MemoryWhen;
+    /** Aim the search at part of the scope's documents: return only the chunks of
+     *  documents named at or under ANY of these Path-tree paths, in the scope's own
+     *  tree (sent as `under_paths`). Narrows DOCUMENT chunks only — facts and notes
+     *  the same search returns pass untouched — and is applied before ranking.
+     *
+     *  The four document filters need a search that can return documents (no
+     *  `sources`, or `sources` including `"documents"`; otherwise 400
+     *  `invalid_filter`), are refused on `scope: "tenant"` (400 `invalid_filter`),
+     *  and need SQL Memory on the server (400 `filter_unavailable`). They resolve in
+     *  the caller's own tenant. The response then carries {@link
+     *  MemorySearchResponse.filter}. For chunk-level filters (type, status, tags, a
+     *  validity instant) use `document({ op: "search" })`. */
+    underPaths?: string[];
+    /** Never return the chunks of documents named at or under these paths (sent as
+     *  `exclude_under_paths`). Documents only, as {@link underPaths}. */
+    excludeUnderPaths?: string[];
+    /** Return only the chunks of these documents (sent as `document_ids`).
+     *  Documents only, as {@link underPaths}. */
+    documentIds?: string[];
+    /** Never return the chunks of these documents (sent as
+     *  `exclude_document_ids`). Documents only, as {@link underPaths}. */
+    excludeDocumentIds?: string[];
+}
+/** What a document filter on {@link LoomcycleClient.memorySearch} resolved to —
+ *  present on the response ONLY when a filter was sent. */
+export interface MemorySearchDocumentFilter {
+    /** The filter as applied: paths canonicalised, blanks and duplicates dropped.
+     *  Only the kinds that were sent appear. */
+    applied: {
+        under_paths?: string[];
+        exclude_under_paths?: string[];
+        document_ids?: string[];
+        exclude_document_ids?: string[];
+    };
+    /** Documents with at least one matching chunk. 0 means the paths/ids name no
+     *  document in this scope — not that nothing relevant was found. */
+    matched_documents: number;
+    /** Chunks the filter let through. */
+    matched_chunks: number;
+    /** True when the match was sent as "everything except" its complement. Always
+     *  false while access-control rules can deny the caller reading part of the
+     *  scope — the counts then cover only documents it may read. */
+    inverted: boolean;
 }
 /** The observed-time predicate on {@link MemorySearchInput}. Timestamps are
  *  RFC3339 instants — resolve phrases like "the first weekend of October"
@@ -2347,6 +2515,9 @@ export interface MemorySearchResponse {
      *  those call for very different responses. Counts describe the candidate pool
      *  the ranker saw, not a scope-wide census. */
     time_filter?: MemoryTimeFilter;
+    /** What the document filter resolved to — present only when one was sent
+     *  ({@link MemorySearchInput.underPaths} and its siblings). */
+    filter?: MemorySearchDocumentFilter;
 }
 export interface MemoryTimeFilter {
     mode: "prefer" | "require";
@@ -3032,8 +3203,50 @@ export type DocumentToolInput = {
     from_id?: string;
     to_id?: string;
     kind?: string;
-    /** query_chunks: restrict to documents at/under this Path-tree path. */
+    /** query_chunks / query_documents / documents_summary: restrict to documents
+     *  at/under this Path-tree path. search / related: return only chunks of
+     *  documents named at or under it — applied inside every retrieval leg before
+     *  its limit, so the best matches come from that part of the tree. */
     under_path?: string;
+    /** search / related: chunks of documents named at or under ANY of these paths
+     *  (with `under_path`, the union of both). */
+    under_paths?: string[];
+    /** search / related: never chunks of documents named at or under this path. */
+    exclude_under_path?: string;
+    /** search / related: never chunks of documents named at or under these paths. */
+    exclude_under_paths?: string[];
+    /** documents_summary: the documents to summarize. search / related: return
+     *  only chunks of these documents. */
+    document_ids?: string[];
+    /** search / related: never chunks of these documents (e.g. the document under
+     *  review, so its own text is not found as evidence for itself). */
+    exclude_document_ids?: string[];
+    /** search / related: chunk types, each including its ontology subtypes (with
+     *  `type`, the union of both). */
+    types?: string[];
+    /** search / related: exact chunk statuses; any matches (with `status`, the union). */
+    statuses?: string[];
+    /** graph_recall / list_facts: answer as of this instant (unix nanoseconds).
+     *  search / related / query_chunks: only chunks whose stated validity (the
+     *  chunk's own valid_at/invalid_at and, for a fact, its fact dates) contains
+     *  it; a chunk with no stated validity always matches. */
+    as_of?: number;
+    /** graph_recall: how much of each chunk's text the rows carry. Omitted: chunks
+     *  that are not facts carry the first 600 characters of their body (a fact's
+     *  title is its claim, so facts stay title-only). `0`: titles only — the
+     *  cheapest structural walk, the response shape from before bodies existed.
+     *  `N` (at most 4000): up to N characters on every row, facts included. A cut
+     *  body ends on a word and the row says `body_truncated: true`; `budget_chars`
+     *  counts body characters too. */
+    body_chars?: number;
+    /** When the content became true in the world (unix nanoseconds).
+     *  upsert_chunk: the fact's start. create_chunk / update_chunk: the chunk's
+     *  own start (an edition coming into force); update_chunk with `null` clears
+     *  it. Omit when unknown. */
+    valid_at?: number | null;
+    /** When the content stopped being true (unix nanoseconds, exclusive; after
+     *  valid_at). Same ops as {@link valid_at}; `null` clears on update_chunk. */
+    invalid_at?: number | null;
     /** query_chunks: raw read-only SELECT (escape hatch; validator-gated). */
     sql?: string;
     /** Row/response bound. On `documents_summary` it defaults to 500 (max 5000) and
@@ -3107,6 +3320,74 @@ export type DocumentToolInput = {
  *  `create_document` returns `{document_id, root_chunk_id, ...}`). */
 export type PathToolResponse = unknown;
 export type DocumentToolResponse = unknown;
+/** What a filtered `document({op:"search"|"related", …})` call resolved its
+ *  structural filter to — present on the response ONLY when a filter argument
+ *  was passed (a filter-free response has no `filter` key). */
+export type DocumentSearchFilter = {
+    /** The filter as applied: singular fields folded into the plural ones, paths
+     *  canonicalised. Only the kinds that were passed appear. */
+    applied: {
+        under_paths?: string[];
+        exclude_under_paths?: string[];
+        document_ids?: string[];
+        exclude_document_ids?: string[];
+        types?: string[];
+        statuses?: string[];
+        tag?: string;
+        tag_prefix?: string;
+        as_of?: number;
+    };
+    /** Documents with at least one matching chunk. */
+    matched_documents: number;
+    /** Chunks the search could return. 0 = the filter matched nothing (the
+     *  response then has no hits and the query was never embedded). */
+    matched_chunks: number;
+    /** Present when a type was widened to its ontology subtypes. */
+    type_expanded_to?: string[];
+    /** True when the match was sent to the search as "everything except" its
+     *  complement (the smaller list). Always false while access-control rules can
+     *  deny the caller reading part of the scope — the counts above then cover
+     *  only documents it may read. */
+    inverted: boolean;
+};
+/** One hit of `document({op:"search"})`. */
+export type DocumentSearchHit = {
+    chunk_id: string;
+    score: number;
+    rank_score: number;
+    title?: string;
+    type?: string;
+    document_id?: string;
+    /** The chunk's own validity period, present only when set. */
+    valid_at?: number;
+    invalid_at?: number;
+    matched_unit?: {
+        kind: string;
+        text: string;
+    };
+};
+/** Response of `document({op:"search"})` — narrow a {@link DocumentToolResponse}
+ *  to it. */
+export type DocumentSearchResult = {
+    chunks: DocumentSearchHit[];
+    filter?: DocumentSearchFilter;
+    reranked?: boolean;
+    rerank_reason?: string;
+};
+/** Response of `document({op:"related"})` — narrow a {@link DocumentToolResponse}
+ *  to it. */
+export type DocumentRelatedResult = {
+    related: Array<{
+        chunk_id: string;
+        score: number;
+        title?: string;
+        type?: string;
+        document_id?: string;
+        valid_at?: number;
+        invalid_at?: number;
+    }>;
+    filter?: DocumentSearchFilter;
+};
 /** Input for {@link LoomcycleClient.history} — the RFC BE History tool
  *  (POST /v1/_history). Browse/search/annotate PAST CHATS (a chat = a session).
  *  Op-discriminated; the owner is resolved server-side from the authenticated
@@ -3928,6 +4209,15 @@ export interface EnsureMcpServerOptions {
      *  loomcycle's idempotent create dedup the re-registration. */
     headers?: Record<string, string>;
     description?: string;
+    /** How the server's text results reach the model. `"passthrough"` (the
+     *  default) hands them over as they came. `"capture"` keeps a file the
+     *  server returns as base64 inside a text block — the whole block, or a
+     *  JSON string field such as Microsoft Graph's `contentBytes` — in the
+     *  run's inbox and hands the model a one-line reference instead. Opt in
+     *  only for a server that returns files that way: a long opaque token
+     *  could otherwise look like one. Part of the registration's content, so
+     *  changing it mints a new version. Sent as the overlay's `binary_results`. */
+    binaryResults?: "passthrough" | "capture";
     /** Force a `tools/list` refresh after registering. Default false.
      *
      *  You usually do NOT need this: registration auto-discovers the upstream's
@@ -4040,6 +4330,18 @@ export interface AgentCompaction {
      *  memory its definition must authorize. */
     memory_flush?: boolean;
 }
+/** An agent's OCR and speech-to-text settings. It can opt in to OCR and lower
+ *  the operator's per-run caps; it can never raise them or pick an engine. */
+export interface AgentTranscription {
+    /** OCR for scans and images. Default `never`: OCR is billed per page. */
+    ocr?: 'auto' | 'always' | 'never';
+    /** Speech-to-text. Default `on` when the operator configured an engine. */
+    stt?: 'on' | 'off';
+    /** At most the operator's `transcription.ocr.max_pages_per_run`. */
+    max_pages_per_run?: number;
+    /** At most the operator's `transcription.stt.max_minutes_per_run`. */
+    max_minutes_per_run?: number;
+}
 /** 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. */
@@ -4186,6 +4488,19 @@ export interface AgentDefOverlay {
      *  only. Held to the author's own grant; a sub-agent holds only what its
      *  parent run also holds. */
     crypto_scopes?: string[];
+    /** Which operator-listed credentials the agent's `Bash` and Bashbox host
+     *  commands receive (RFC EW): only these names of
+     *  `LOOMCYCLE_BASH_ALLOWED_CREDS` / `LOOMCYCLE_BASHBOX_FALLBACK_ALLOWED_CREDS`.
+     *  Unset = every credential the operator lists; `[]` = none; never adds one.
+     *  Held to the author's own narrowing; a sub-agent gets only the names its
+     *  parent run also allows. */
+    shell_credentials?: string[];
+    /** Which network operations the agent's `Git` tool may perform (RFC FB):
+     *  `['fetch']` (clone, fetch, pull, ls_remote) or `['fetch', 'push']`.
+     *  Unset or `[]` = none, local repositories only; `push` needs `fetch`.
+     *  Held to the author's own grant; a sub-agent may perform an operation
+     *  only when its parent run also may. */
+    git_remote?: Array<'fetch' | 'push'>;
     /** Channel tool ACL (default-deny until set). */
     channels?: AgentChannelACL;
     /** Interruption tool gate — `enabled: true` REQUIRED for the tool to work. */
@@ -4221,6 +4536,8 @@ export interface AgentDefOverlay {
     sampling?: AgentSampling;
     /** Context compaction in `append` mode, merged per field. */
     compaction?: AgentCompaction;
+    /** OCR and speech-to-text settings, merged per field. */
+    transcription?: AgentTranscription;
     /** How history is distilled, merged per field. */
     context?: AgentContext;
     /** Volumes the file and exec tools may resolve paths against. None declared
@@ -4881,6 +5198,10 @@ export interface LibraryEntry<T = unknown> {
     active_def_id?: string;
     latest_version?: number;
     last_updated?: string;
+    /** /v1/_library/agents only: the context window, in tokens, a run of
+     *  this agent starts with — the resolved provider's window, lowered by
+     *  the agent's own max_context_tokens. Omitted when unknown. */
+    context_window?: number;
     /** Static-side definition body. Omitted when in_static is false
      *  (dynamic-only entries have no static body — query the substrate
      *  via AgentDef/SkillDef/MCPServerDef tools to fetch the active
@@ -5732,16 +6053,20 @@ export interface DefNameSummary {
 export interface DefNamesResponse {
     names: DefNameSummary[];
 }
-/** One token name's summary from {@link LoomcycleClient.listOperatorTokenDefNames}.
- *  Carries no secret material. */
+/** One (tenant, token name) summary from {@link LoomcycleClient.listOperatorTokenDefNames}.
+ *  A per-user (`u-`) name repeats across tenants, so it can appear once per
+ *  tenant. 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. */
+    /** Every token minted under the name in this tenant, rotated and retired ones included. */
     token_count: number;
-    /** A non-retired token exists. */
+    /** A non-retired, unexpired token exists. */
     has_current: boolean;
+    /** The newest live token's def_id; absent when none is live. Rotate or
+     *  retire by it: a per-user name is refused as a target. */
+    current_def_id?: string;
     last_updated: string;
 }
 /** Response of {@link LoomcycleClient.listOperatorTokenDefNames}. */
@@ -5913,6 +6238,49 @@ export interface RoutingResponse {
     throughput_mode?: string;
     /** Absent when no search providers are configured. */
     search?: SearchRoutingProvider[];
+    /** The memory embedder. Absent when none is configured. */
+    embedder?: RoutingEmbedder;
+    /** The decision models. Absent when none are configured. */
+    decision?: RoutingDecision;
+}
+/** The memory embedder in {@link RoutingResponse}. `state` is what its calls
+ *  did since boot, not a probe: `untried` means nothing has been embedded yet.
+ *  No error text or address is reported. */
+export interface RoutingEmbedder {
+    state: "untried" | "ok" | "failing";
+    provider?: string;
+    model?: string;
+    /** The `models:` alias `memory.embedder` names, when it names one. */
+    alias?: string;
+    /** Absent until the embedder has learned it. */
+    dimension?: number;
+    calls: number;
+    failures: number;
+    last_failure_kind?: string;
+    last_ok_unix?: number;
+    last_failure_unix?: number;
+}
+/** The decision block in {@link RoutingResponse}. */
+export interface RoutingDecision {
+    /** The model a call that names none is asked. */
+    default: string;
+    models: RoutingDecisionModel[];
+}
+/** One decision model. The state fields are its provider's probe; all three are
+ *  absent when the provider was never probed, and `listed` is also absent while
+ *  the provider is unreachable. Under the operator-key gate a tenant sees only
+ *  the models it can key. */
+export interface RoutingDecisionModel {
+    /** What a caller names: a `models:` alias or a model name. */
+    name: string;
+    provider: string;
+    model: string;
+    default?: boolean;
+    /** Reachable and listed. */
+    available?: boolean;
+    reachable?: boolean;
+    /** The provider's model list carries the model (for Ollama: it is pulled). */
+    listed?: boolean;
 }
 /** Response of {@link LoomcycleClient.listProviderModels}: a live listing from
  *  the provider, not the cached probe matrix. */
@@ -6050,3 +6418,337 @@ export interface StreamChangesOptions {
     /** Abort to close the stream; the iterator then throws an `AbortError`. */
     signal?: AbortSignal;
 }
+/** The access-control rollout mode a deployment runs in. */
+export type AclMode = "compat" | "shadow" | "enforce";
+/** Marks an entry the config declares rather than the store holds. */
+export type AclSource = "config";
+export type AclEffect = "allow" | "deny";
+/** What a binding attaches a list to. `tenant` is everyone in the tenant. */
+export type AclSubjectKind = "user" | "group" | "token" | "tenant";
+/** The closed `when` set of a rule. Every present field narrows the rule; an
+ *  absent one does not. */
+export interface AclCondition {
+    /** The request arrived on one of these (see `AclCatalog.transports`). */
+    transport?: string[];
+    /** A wall-clock window: on one of `days` (`mon`…`sun`), inside
+     *  `between: [from, to)` (`HH:MM`), in `tz` (an IANA zone). */
+    time?: {
+        days?: string[];
+        between?: string[];
+        tz?: string;
+    };
+    interactive?: boolean;
+    tier?: string[];
+    user_tier?: string[];
+    source_cidr?: string[];
+    owner_is_self?: boolean;
+    /** Inside a run: the run's agent matches this glob. */
+    agent?: string;
+    /** The run's spawn depth is at most `max`. */
+    depth?: {
+        max: number;
+    };
+}
+/** One rule: `effect` on any of `actions` over any of `resources`
+ *  (`type:selector`, e.g. `agent:reviewer-*`), when `when` holds. */
+export interface AclRule {
+    effect: AclEffect;
+    actions: string[];
+    resources: string[];
+    when?: AclCondition;
+    description?: string;
+}
+/** A rule list as written: a built-in baseline, or a draft list for
+ *  {@link LoomcycleClient.authzSimulate}. */
+export interface AclList {
+    name: string;
+    description?: string;
+    rules: AclRule[];
+}
+/** One rule list: a stored one, or (`source: "config"`) one the config
+ *  declares, which has only a name, a description and its rules. */
+export interface AclDefRow {
+    tenant_id?: string;
+    name: string;
+    /** Bumped on every write. Absent on a config list. */
+    version?: number;
+    content_sha256?: string;
+    catalog_version?: number;
+    rules: AclRule[];
+    description?: string;
+    created_at?: string;
+    updated_at?: string;
+    created_by?: string;
+    /** Set once the list is retired; absent while it is live. */
+    retired_at?: string;
+    source?: AclSource;
+}
+/** `aclDef({op: "list"})`. `builtin` is the code-defined baselines, which no
+ *  call can change. */
+export interface AclDefListResponse {
+    acls: AclDefRow[];
+    builtin: AclList[];
+}
+/** `GET /v1/_acldef/names`: every live list name the tenant's bindings can
+ *  reach, stored and config, sorted. */
+export interface AclDefNamesResponse {
+    names: string[];
+}
+/** `aclDef({op: "validate"})` on rules the server accepts. Rules it refuses
+ *  are a 400 (`acl_invalid`) naming the fault. */
+export interface AclValidateResult {
+    valid: boolean;
+    /** How many rules were read. */
+    rules: number;
+    catalog_version: number;
+}
+/** One resource type of the catalog: its verbs, and for a scoped type the
+ *  scopes a selector may name (`separator` joins scope and name). */
+export interface AclCatalogType {
+    type: string;
+    verbs: string[];
+    scopes?: string[];
+    separator?: string;
+}
+/** `aclDef({op: "catalog"})`: what a rule may name. */
+export interface AclCatalog {
+    catalog_version: number;
+    types: AclCatalogType[];
+    transports: string[];
+}
+/** The ops of the AclDef family. `create`, `update` and `put` are the same
+ *  upsert. */
+export type AclDefOp = "create" | "update" | "put" | "get" | "list" | "retire" | "validate" | "catalog" | "names";
+/** The input of {@link LoomcycleClient.aclDef}. `name` is required by
+ *  create/update/put/get/retire, `rules` by create/update/put/validate,
+ *  `include_retired` is read by list. */
+export interface AclDefInput {
+    op: AclDefOp;
+    name?: string;
+    rules?: AclRule[];
+    description?: string;
+    include_retired?: boolean;
+}
+/** One group: a stored one, or (`source: "config"`) one the config declares,
+ *  which lists its direct `members` (subjects) and member `groups` inline and
+ *  has no timestamps. A stored group's members come from
+ *  {@link LoomcycleClient.getGroup}. */
+export interface GroupRow {
+    tenant_id?: string;
+    name: string;
+    description?: string;
+    /** Set on a group an identity provider owns: its members are managed there,
+     *  and a write here is refused (409 `group_external`). */
+    external_id?: string;
+    created_at?: string;
+    updated_at?: string;
+    created_by?: string;
+    source?: AclSource;
+    members?: string[];
+    groups?: string[];
+}
+export type GroupMemberKind = "user" | "group";
+/** One direct membership edge of a stored group. */
+export interface GroupMember {
+    tenant_id?: string;
+    group: string;
+    member_kind: GroupMemberKind;
+    member_id: string;
+    added_at: string;
+    added_by?: string;
+}
+export interface GroupListResponse {
+    groups: GroupRow[];
+}
+/** `GET /v1/_groups/{name}`: a stored group with its direct members. */
+export interface GroupDetail {
+    group: GroupRow;
+    members: GroupMember[] | null;
+    /** Every group a member of this one is also in, transitively, this one
+     *  included. */
+    contained_in: string[] | null;
+}
+/** `GET /v1/_groups/{name}/effective`: everyone the group holds, at any
+ *  nesting depth, config-declared members included. */
+export interface GroupEffective {
+    group: string;
+    /** User subjects, sorted. */
+    users: string[];
+    /** The nested groups walked, sorted (the group itself excluded). */
+    groups: string[];
+}
+/** The body of {@link LoomcycleClient.createGroup}: an upsert by name. */
+export interface CreateGroupBody {
+    name: string;
+    description?: string;
+    external_id?: string;
+}
+/** What a membership write reports. `removed` is set by a removal. */
+export interface GroupMemberChange {
+    group: string;
+    kind: GroupMemberKind;
+    id: string;
+    removed?: boolean;
+}
+/** One binding of a list to a subject: a stored one, or (`source: "config"`)
+ *  one the config declares, which has no `binding_id` and no timestamps. */
+export interface AclBinding {
+    binding_id?: string;
+    tenant_id?: string;
+    acl: string;
+    subject_kind: AclSubjectKind;
+    /** Absent for a tenant-wide binding. */
+    subject_id?: string;
+    /** Absent when the binding never expires. */
+    expires_at?: string;
+    created_at?: string;
+    created_by?: string;
+    /** Set once retired; absent while live. */
+    retired_at?: string;
+    source?: AclSource;
+}
+export interface AclBindingListResponse {
+    bindings: AclBinding[];
+}
+/** The body of {@link LoomcycleClient.createAclBinding}. The list must exist
+ *  and `expires_at` (RFC 3339) must be in the future, or the server refuses
+ *  with 400 `acl_binding_invalid`. */
+export interface CreateAclBindingBody {
+    acl: string;
+    subject_kind: AclSubjectKind;
+    subject_id?: string;
+    expires_at?: string;
+}
+/** One rule that decided: list, its version, the rule's index, its effect. */
+export interface AuthzReason {
+    acl: string;
+    version?: number;
+    rule: number;
+    effect: AclEffect;
+}
+/** An access-control decision (AuthZEN 1.0 shape). `decision` is true only
+ *  when a rule allowed; `outcome` `no_match` means no rule spoke, which in
+ *  `compat` and `shadow` mode the scope gate then decides. */
+export interface AuthzDecision {
+    decision: boolean;
+    outcome: "allow" | "deny" | "no_match";
+    reasons?: AuthzReason[];
+    /** The request crossed a tenant and no rule was read. */
+    tenant_floor?: boolean;
+    mode: AclMode;
+}
+/** The request context a rule's `when` is judged against. Omitted fields take
+ *  the call's own (`transport` is the transport the call arrived on). */
+export interface AuthzRequestContext {
+    transport?: string;
+    interactive?: boolean;
+    tier?: string;
+    user_tier?: string;
+    agent?: string;
+    depth?: number;
+}
+/** One question: may `subject` do `action` to `resource`? An omitted
+ *  `subject` (or one naming the caller) asks about the caller; naming another
+ *  subject of the tenant needs a tenant operator. An empty `resource.id` asks
+ *  about any instance of the type. */
+export interface AuthzEvaluationRequest {
+    subject?: {
+        type?: string;
+        id?: string;
+    };
+    action: {
+        name: string;
+    };
+    resource: {
+        type: string;
+        id: string;
+        owner?: string;
+    };
+    context?: AuthzRequestContext;
+}
+/** How {@link LoomcycleClient.authzEvaluations} runs its batch. */
+export type AuthzEvaluationsSemantic = "execute_all" | "deny_on_first_deny" | "permit_on_first_permit";
+/** A batch of questions for one subject. A top-level `action`, `resource` or
+ *  `context` is the default each entry that omits its own inherits. 1 to 256
+ *  entries. */
+export interface AuthzEvaluationsRequest {
+    subject?: {
+        type?: string;
+        id?: string;
+    };
+    action?: {
+        name: string;
+    };
+    resource?: {
+        type: string;
+        id: string;
+        owner?: string;
+    };
+    context?: AuthzRequestContext;
+    evaluations: Array<Partial<Omit<AuthzEvaluationRequest, "subject">>>;
+    options?: {
+        evaluations_semantic?: AuthzEvaluationsSemantic;
+    };
+}
+export interface AuthzEvaluationsResponse {
+    evaluations: AuthzDecision[];
+}
+/** One rule the engine read for an explanation, matching or not, and why. */
+export interface AuthzTrace {
+    acl: string;
+    version?: number;
+    rule: number;
+    effect: AclEffect;
+    matched: boolean;
+    why: string;
+}
+/** A binding as the engine applied it. */
+export interface AuthzAppliedBinding {
+    id?: string;
+    acl: string;
+    subject_kind: AclSubjectKind;
+    subject_id?: string;
+    expires_at?: string;
+}
+/** `POST /v1/_authz/explain`: the decision, every rule read for the resource's
+ *  type, the bound lists that do not exist, the bindings applied, and the
+ *  subject's groups. */
+export interface AuthzExplainResponse {
+    decision: AuthzDecision;
+    traces: AuthzTrace[] | null;
+    missing_acls: string[] | null;
+    applied_bindings: AuthzAppliedBinding[] | null;
+    groups: string[] | null;
+}
+/** A draft binding for {@link LoomcycleClient.authzSimulate}. */
+export interface AuthzDraftBinding {
+    acl: string;
+    subject_kind: AclSubjectKind;
+    subject_id?: string;
+    expires_at?: string;
+}
+/** Evaluate questions against a DRAFT: the subject's lists and bindings now,
+ *  with `acls` added or replaced by name and `bindings` added. Nothing is
+ *  written. 1 to 256 requests. */
+export interface AuthzSimulateRequest {
+    subject?: {
+        type?: string;
+        id?: string;
+    };
+    acls?: AclList[];
+    bindings?: AuthzDraftBinding[];
+    requests: AuthzEvaluationRequest[];
+}
+export interface AuthzSimulateResult {
+    /** The request, echoed. */
+    request: AuthzEvaluationRequest;
+    now: AuthzDecision;
+    with_draft: AuthzDecision;
+    /** The outcome differs between `now` and `with_draft`. */
+    changed: boolean;
+}
+export interface AuthzSimulateResponse {
+    results: AuthzSimulateResult[];
+    /** Lists the draft's bindings name that no layer has. */
+    missing_acls: string[] | null;
+}