@ai-matrx/api 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,2006 @@
+import { M as MatrxStreamEnvelope, b as MatrxNdjsonIssue, c as MatrxStreamEnvelopeObservation, d as MatrxSseFrame } from './index-wC2vtb70.cjs';
+export { A as Api, e as ApiRequestInfo, a as ApiStream, f as AuthTier, g as CONTRACT_SHA256, C as CallOptions, h as CreateApiOptions, D as DEPLOYMENTS, i as DOMAINS, j as DeploymentName, E as Environment, H as HttpMethod, J as JsonOrStream, N as NdjsonEvent, O as OperationArgs, k as OperationDescriptor, l as OrgRule, S as SseEvent, m as StreamKind, n as createApi, o as openJsonOrStream, p as openStream } from './index-wC2vtb70.cjs';
+import { CredentialsPort } from './credentials.cjs';
+export { API_KEY_PREFIX, CredentialsSetting, MATRX_HEADERS, MatrxCredential, MatrxCredentialKind, credentialToHeaders, toCredentialsPort } from './credentials.cjs';
+import { ResilientFetchOptions } from './net.cjs';
+export { AbortedError, ConnectTimeoutError, HeartbeatTimeoutError, HttpError, NetError, NetErrorCode, NetworkError, OfflineError, ResilientFetchResult, RetryOptions, StreamMonitorOptions, TotalTimeoutError, extractErrorMessage, isNetError, isTransportFailure, monitorStream, resilientFetch, toNetError, withRetry } from './net.cjs';
+
+/**
+ * `@ai-matrx/agents/matrx` — the Matrx transport port.
+ *
+ * The ONE seam between this package's wire semantics and a host's connection
+ * policy. This package owns WHAT is said to the AI Matrx server — paths,
+ * methods, JSON bodies, streaming Accept headers, the `Last-Event-ID` cursor
+ * header — and the host owns HOW the connection is made:
+ *
+ * - base-URL / backend-channel resolution (global, sandbox override, local
+ *   engine, EC2-dedicated — whatever ladder the host runs);
+ * - credentials (Supabase JWT `Authorization: Bearer`, guest
+ *   `X-Fingerprint-ID`, or the API-key lane) — NEVER implemented here;
+ * - the `X-Organization-Id` context header;
+ * - retry policy, network-level timeouts, and diagnostics capture.
+ *
+ * A host implements the port in a few lines:
+ *
+ * ```ts
+ * const transport: MatrxTransport = {
+ *   fetch: (path, init) =>
+ *     fetch(`${baseUrl}${path}`, {
+ *       ...init,
+ *       headers: { ...init.headers, ...authHeaders() },
+ *     }),
+ * };
+ * ```
+ *
+ * The port is deliberately structural and `fetch`-shaped so `@ai-matrx/data`'s
+ * `/api` transport can implement it without importing this package.
+ */
+/**
+ * The request this package hands the port. A strict subset of `RequestInit`,
+ * so a host can spread it straight into `fetch`.
+ */
+interface MatrxTransportRequest {
+    method: "GET" | "POST";
+    /**
+     * Wire-semantic headers the CALL requires (`Content-Type`, `Accept`,
+     * `Last-Event-ID`). The host merges its policy headers (auth, org) on top;
+     * it must not drop these.
+     */
+    headers: Record<string, string>;
+    /** Pre-serialized JSON body, present on POST calls that carry one. */
+    body?: string;
+    /** Caller cancellation. The host must wire it to the underlying fetch. */
+    signal?: AbortSignal;
+}
+/**
+ * The transport port. `path` is server-relative and always starts with `/`
+ * (`/ai/...`, `/runtime/...`); the host prepends its resolved base URL.
+ */
+interface MatrxTransport {
+    fetch(path: string, init: MatrxTransportRequest): Promise<Response>;
+}
+/**
+ * A non-2xx response from the Matrx API, with the server's structured error
+ * body preserved and its richest human-readable message extracted.
+ */
+declare class MatrxApiError extends Error {
+    readonly name = "MatrxApiError";
+    /** HTTP status of the failed response. */
+    readonly status: number;
+    /** Machine code from the server body (`code`, or `detail.code`), when present. */
+    readonly code: string | null;
+    /** The parsed server error body, verbatim (undefined when unparsable). */
+    readonly serverDetail: unknown;
+    /** The request path the failure came from (server-relative). */
+    readonly path: string;
+    constructor(args: {
+        status: number;
+        path: string;
+        serverDetail?: unknown;
+        message?: string;
+    });
+}
+/**
+ * Extract the richest human-readable message from a Matrx/FastAPI error body.
+ *
+ * aidream 4xx validation errors look like
+ * `{ error, user_message, details: [{ field, message, help }] }`; hand-raised
+ * HTTPExceptions carry `{ detail: { code, message } }`; FastAPI's defaults are
+ * `{ detail: string | [{ msg }] }`. Preference order: `user_message` →
+ * `message` → joined `details[].message` → `detail.message` →
+ * `detail` string → joined `detail[].msg`. Returns undefined for
+ * unrecognized bodies so callers fall back to the bare status line.
+ */
+declare function extractMatrxErrorMessage(serverDetail: unknown): string | undefined;
+/**
+ * Extract the machine error code from a Matrx error body: top-level `code`,
+ * else `detail.code` (the hand-raised HTTPException shape). Null when absent.
+ */
+declare function extractMatrxErrorCode(serverDetail: unknown): string | null;
+
+/**
+ * `@ai-matrx/agents/matrx` — the AI Matrx server's error model, as every
+ * client reads it: `BackendApiError` (the server's `APIError` body),
+ * `StreamTransportError` (the socket died mid-run; the run may still finish
+ * and is reattachable), parsing of HTTP / stream / persisted errors, and the
+ * ONE sentence a person sees (`getUserMessage`, `describeBackendFailure`).
+ *
+ * Moved from matrx-frontend `lib/api/errors.ts` (chat-package independence
+ * P9); the app re-exports it from here. Pure: no host, no window, no env.
+ */
+/**
+ * Standardized error shape returned by all backend endpoints.
+ * Matches the Python `APIError` Pydantic model.
+ */
+interface BackendApiErrorData {
+    /** Machine-readable error code (e.g. "auth_required", "validation_error") */
+    error: string;
+    /** Developer-facing detail for debugging */
+    message: string;
+    /** Safe to display directly in the UI */
+    user_message: string;
+    /** Extra info (validation errors, etc.) */
+    details: unknown | null;
+    /** Unique request ID for support/debugging */
+    request_id: string;
+}
+/** Common backend error codes */
+type BackendErrorCode = "auth_required" | "token_required" | "admin_required" | "validation_error" | "not_found" | "internal_error" | "agent_error"
+/** The stream socket died mid-run; the server run may still be completing
+ *  and is reattachable. See `StreamTransportError`. */
+ | "stream_transport_lost" | (string & {});
+/**
+ * Typed error thrown by all backend API operations.
+ * Contains structured fields matching the Python APIError model.
+ *
+ * Usage:
+ * ```typescript
+ * try {
+ *   await client.post(ENDPOINTS.ai.agentStart(agentId), body);
+ * } catch (err) {
+ *   if (err instanceof BackendApiError) {
+ *     // Show err.userMessage to the user
+ *     // Log err.requestId for debugging
+ *     // Check err.code for programmatic handling
+ *   }
+ * }
+ * ```
+ */
+declare class BackendApiError extends Error {
+    /** Machine-readable error code */
+    readonly code: BackendErrorCode;
+    /** Developer-facing detail */
+    readonly detail: string;
+    /** Safe to display directly in the UI */
+    readonly userMessage: string;
+    /** Extra info (validation errors, etc.) */
+    readonly details: unknown | null;
+    /** Unique request ID for support/debugging */
+    readonly requestId: string;
+    /** HTTP status code (if from an HTTP response) */
+    readonly status: number | null;
+    constructor(data: {
+        code: BackendErrorCode;
+        detail: string;
+        userMessage: string;
+        details?: unknown | null;
+        requestId?: string | undefined;
+        status?: number | null | undefined;
+    });
+    /** Convert to the wire format for logging */
+    toJSON(): BackendApiErrorData;
+}
+/**
+ * The socket carrying a live NDJSON stream broke mid-run.
+ *
+ * THE DISTINCTION THIS EXISTS TO MAKE: a backend that blows up mid-stream does
+ * NOT break the socket — it emits a typed `error` event and closes the body
+ * cleanly. So an exception escaping the body reader means the *transport* died,
+ * not the run. And aidream streams run `detach_on_disconnect=True`: the server
+ * keeps executing and persisting the turn after our connection goes away.
+ *
+ * The client therefore cannot decide locally whether the answer is lost — it
+ * must ASK THE SERVER. That is what `resumable` means here: "reattach by
+ * requestId / conversationId / durable run id and let server truth settle it",
+ * never "this succeeded". A server that genuinely died reports `failed` on
+ * reattach and the honest record replaces the optimistic copy.
+ *
+ * Consumers: `run-ai-stream.ts` (chat → `reconnectServerOperation`) and
+ * `adopt-foreign-stream.ts` (pipeline runs → the surface's own rejoin).
+ */
+declare class StreamTransportError extends BackendApiError {
+    /** Always true — reattach and let the server settle the outcome. */
+    readonly resumable: true;
+    constructor(data: {
+        detail: string;
+        details?: unknown | null;
+        requestId?: string;
+    });
+}
+/**
+ * True when a failure is a dropped transport rather than a failed run. Use this
+ * instead of `instanceof` at boundaries that re-wrap errors (thunk rejections,
+ * `callApi` result errors), where the class identity is lost but the code
+ * survives.
+ */
+declare function isStreamTransportLost(error: unknown): boolean;
+/**
+ * Parse a non-OK HTTP response into a BackendApiError.
+ *
+ * Handles the standardized backend shape and falls back gracefully
+ * when the response isn't JSON or uses a legacy format.
+ */
+declare function parseHttpError(response: Response): Promise<BackendApiError>;
+/**
+ * Parse an already-decoded JSON error body into a BackendApiError.
+ *
+ * Exported because XHR callers (upload/download progress paths) have the
+ * parsed body in hand and MUST NOT hand-roll a shallower read: a private
+ * copy in `python-client.ts` looked only at top-level `error`/`message`, so
+ * FastAPI's `{"detail": {...}}` envelope — what every matrx-files 500 uses —
+ * degraded to the useless `code: "internal", detail: "HTTP 500"`. That is
+ * exactly how an upload failure with a real server-side cause reached the
+ * user as `Upload failed (500)` and nothing else. One parser, every transport.
+ */
+declare function parseHttpErrorBody(body: Record<string, unknown> | null, status: number): BackendApiError;
+/**
+ * Adapt callApi's result-style error into the same canonical error used by
+ * direct fetch and streaming consumers.
+ *
+ * callApi intentionally returns errors instead of throwing them, but its
+ * `serverDetail` contains the complete FastAPI body. Sending only
+ * `error.message` to a feature discards that body and turns a precise
+ * configuration failure into "HTTP 422". This adapter keeps one parser and
+ * one human-facing explanation path across both client styles.
+ */
+declare function parseCallApiError(error: {
+    message: string;
+    status?: number;
+    serverDetail?: unknown;
+}): BackendApiError;
+/**
+ * Parse streaming error event data into a BackendApiError.
+ *
+ * Handles both new format (`user_message`) and legacy (`user_visible_message`).
+ */
+declare function parseStreamError(data: unknown): BackendApiError;
+/**
+ * Restore the canonical error shape from a durable backend run row.
+ *
+ * Provider ledgers often keep an aggregate summary plus a more specific first
+ * child failure. Prefer that child so a page refresh does not turn a precise
+ * streamed failure back into "1 request failed".
+ */
+declare function parsePersistedBackendError(data: unknown, requestId?: string): BackendApiError | null;
+/** True when a message tells the reader nothing about what actually broke. */
+declare function isGenericUserMessage(message: string | null | undefined): boolean;
+interface UpstreamErrorPayload {
+    message: string;
+    code: string | null;
+    userMessage: string | null;
+    requestId: string | null;
+    status: number | null;
+}
+/**
+ * Recover an upstream service's structured error that a downstream service
+ * stringified into its own message.
+ *
+ * Real example (scraper wrapping aidream):
+ *   `aidream could not resolve GSC credential 7223…: HTTP 409 {"error":"conflict",
+ *    "message":"Google connection 7223… has no vault credential — it needs
+ *    re-authentication","user_message":"Something went wrong…","request_id":"9002…"}`
+ *
+ * Without this, the only actionable sentence on the whole hop is invisible.
+ */
+declare function unwrapUpstreamError(message: string): UpstreamErrorPayload | null;
+interface BackendFailureExplanation {
+    /** Machine code from the deepest layer that classified the failure. */
+    code: string;
+    /** The most specific human-readable cause available — never a template. */
+    cause: string;
+    /** What to headline in the UI: the cause when the server was generic. */
+    headline: string;
+    /** True when every user-facing message the server sent was a template. */
+    headlineWasGeneric: boolean;
+    /** Message chain, outermost (closest service) first. */
+    chain: string[];
+    /** Deepest request id available, for cross-service log correlation. */
+    requestId: string;
+    status: number | null;
+}
+/**
+ * THE anti-secrecy primitive: turn any thrown backend/stream failure into the
+ * most specific explanation the payload can support — unwrapping every nested
+ * upstream error and refusing to let a templated `user_message` be the answer.
+ *
+ * Every surface that reports a backend failure to a human should headline
+ * `explanation.headline` and always keep `cause` + `requestId` reachable.
+ */
+declare function describeBackendFailure(error: unknown): BackendFailureExplanation;
+/**
+ * Extract a user-visible message from any error object.
+ * Utility for components that just need the display string.
+ */
+declare function getUserMessage(error: unknown): string;
+
+/**
+ * The AI API protocol-version policy — which version of the AI runtime a
+ * Matrx client talks to, and the v2 → v1 transport fallback (moved in from
+ * matrx-frontend `lib/api/ai-api-version.ts` + `call-api.ts::
+ * fetchWithV2Fallback` under C22; server truth
+ * `aidream/docs/runtime/V2_FRONTEND_MIGRATION.md`).
+ *
+ * Background: the Python backend exposes a `/v2` runtime-spine namespace that
+ * wraps the core AI request surfaces in a request-tracking envelope. Body,
+ * headers, and streaming response are BYTE-IDENTICAL to v1 — only the URL
+ * differs.
+ *
+ * ─── The one rule that keeps burning us ─────────────────────────────────────
+ * `/v2` is inserted at the FRONT of the in-app path, right before `/ai`:
+ *
+ *     /ai/agents/{id}  → /v2/ai/agents/{id}   ✅ correct
+ *     /ai/v2/agents/…                          ❌ WRONG (nested) — 404s
+ *
+ * `toV2Path` below is the ONLY place this transform is spelled out.
+ *
+ * ─── Scope: ONLY the covered surfaces have a v2 form ────────────────────────
+ * chat, manual, agents/{id}, conversations/{id} (+ singular aliases),
+ * prompts/{id}, mandates/{key}. EVERYTHING ELSE — cancel, warm, resume,
+ * fork-and-run, runtime operations, files … — has NO v2 route, and the server
+ * does NOT auto-downgrade (a `/v2` request to an uncovered surface is a plain
+ * 404). So the transform is a scoped allowlist, never a blanket prefix.
+ */
+
+type MatrxAiApiVersion = "v1" | "v2";
+/**
+ * The package-wide default AI API version — the production value every Matrx
+ * client runs unless its host deliberately overrides
+ * (`createMatrxTransport({ aiApiVersion })`).
+ */
+declare const MATRX_AI_API_VERSION_DEFAULT: MatrxAiApiVersion;
+/**
+ * The canonical v1 path TEMPLATES the v2 spine covers, `{param}` placeholders
+ * intact — for hosts that route through a template registry.
+ */
+declare const V2_COVERED_AI_PATH_TEMPLATES: readonly ["/ai/manual", "/ai/chat", "/ai/agents/{agent_id}", "/ai/agent/{agent_id}", "/ai/conversations/{conversation_id}", "/ai/conversation/{conversation_id}", "/ai/prompts/{prompt_id}", "/ai/mandates/{mandate_key}"];
+/**
+ * Insert `/v2` at the front of an in-app path. Idempotent, and prefix-aware:
+ * a legacy `/api/` compatibility prefix (stripped server-side) is preserved so
+ * `/api/ai/chat` → `/api/v2/ai/chat`.
+ */
+declare function toV2Path(path: string): string;
+/** Whether `path` (already interpolated) is one of the covered surfaces. */
+declare function isCoveredAiPath(path: string): boolean;
+/**
+ * Whether an in-app path (or a full URL whose path was built by `toV2Path`)
+ * targets the v2 namespace — the guard the downgrade fallback keys off.
+ */
+declare function isV2Path(pathOrUrl: string): boolean;
+/**
+ * The inverse of `toV2Path` — strip the `/v2` version segment so a transport
+ * failure of the v2 endpoint (network error, 404/405, 5xx BEFORE any stream
+ * content) can retry the identical request on the v1 route. Works on a bare
+ * path, an `/api`-prefixed path, or a full URL (the `/v2/ai/` shape is unique
+ * to the version namespace). Idempotent on non-v2 input.
+ */
+declare function toV1FallbackUrl(url: string): string;
+/**
+ * Apply the active AI API version to an ALREADY-INTERPOLATED in-app path.
+ *
+ * - Covered surface + v2  → `/v2` prefix inserted.
+ * - Anything else (or v1) → returned unchanged.
+ *
+ * Pass the in-app PATH only (no scheme/host); prepend the base URL afterward.
+ */
+declare function applyAiApiVersion(path: string, version: MatrxAiApiVersion): string;
+/** One v2 → v1 downgrade, surfaced to the host's diagnostics sink. */
+interface MatrxProtocolDowngrade {
+    /** The failed v2 URL. */
+    url: string;
+    /** Why the downgrade fired (thrown error text, or `HTTP <status>`). */
+    reason: string;
+    /** HTTP status when the trigger was a response (404/405/5xx). */
+    status?: number;
+}
+interface MatrxProtocolFallbackOptions extends ResilientFetchOptions {
+    /**
+     * Fired on every downgrade — a sustained stream of these means a v2 surface
+     * is unhealthy. The fallback also `console.warn`s unconditionally (parity
+     * with the original host pipeline) so the signal never disappears silently.
+     */
+    onDowngrade?: (downgrade: MatrxProtocolDowngrade) => void;
+}
+/**
+ * `resilientFetch` with the v2 → v1 transport fallback. Fires ONLY when a
+ * `/v2/ai/...` ENDPOINT itself fails — a network-layer throw (non-abort), a
+ * 404/405 (surface not on v2), or a 5xx — always BEFORE any stream content is
+ * consumed. Never on an application error (those fail identically on v1), and
+ * never on a caller abort (a user cancel must not be logged as a downgrade —
+ * that poisons the exact telemetry the rollout reads to judge v2 health).
+ */
+declare function fetchWithMatrxProtocolFallback(url: string, init: RequestInit, opts?: MatrxProtocolFallbackOptions): Promise<{
+    response: Response;
+}>;
+/**
+ * The exact-match `pathOverrides` map for `resolveEndpointPath` — keyed on the
+ * canonical templates, valued at their `/v2` siblings. Empty for v1. Every call
+ * that flows through the endpoint-override registry picks up v2 for the covered
+ * surfaces — and ONLY the covered surfaces. (Moved from matrx-frontend
+ * `lib/api/ai-api-version.ts`, chat-package independence P9.)
+ */
+declare function aiVersionPathOverrides(version: MatrxAiApiVersion): Record<string, string>;
+
+/**
+ * The PRODUCTION `MatrxTransport` — the full connection pipeline every Matrx
+ * host used to hand-roll, moved in under C22 (THE HARD PARTS LIVE IN THE
+ * PACKAGE). A host constructs it from identity alone:
+ *
+ * ```ts
+ * const transport = createMatrxTransport({
+ *   baseUrl: "https://server.app.matrxserver.com",
+ *   credentials,                       // CredentialsPort (@ai-matrx/data)
+ *   organizationId: () => activeOrgId, // omit for conversation-lane calls
+ * });
+ * ```
+ *
+ * Everything else is defaulted to the proven production values:
+ *
+ * - **timeouts** — connect 15s (for a non-streaming FastAPI handler this is
+ *   effectively time-to-response), total UNCAPPED (the port cannot tell a JSON
+ *   call from a long-lived NDJSON/SSE stream; the connect timeout is the JSON
+ *   guard), via `@ai-matrx/data/net`'s `resilientFetch`;
+ * - **protocol** — the AI API version transform (`applyAiApiVersion`, default
+ *   v2) + the loud v2 → v1 transport fallback (`./protocol`);
+ * - **credentials** — read fresh from the injected `CredentialsPort` on EVERY
+ *   call, so a token refresh mid-run is picked up; mapped to headers by the
+ *   ONE `credentialToHeaders`;
+ * - **org context** — the fail-closed `X-Organization-Id` binding
+ *   (`./org-context`): configured lanes REQUIRE an org and refuse before the
+ *   wire; unconfigured lanes (conversation-scoped calls, which carry org in
+ *   the body) send none;
+ * - **error classification** — every failure normalizes through
+ *   `normalizeMatrxError` into the ONE `MatrxCallError` envelope;
+ * - **diagnostics** — a typed sink the host wires to its capture/telemetry
+ *   (`onRequest`, `onError`, `onProtocolDowngrade`); wiring it is optional,
+ *   the transport works silently without it.
+ *
+ * Header merge order is part of the port contract: wire headers first
+ * (`Content-Type` / `Accept` / `Last-Event-ID` — the package's), then
+ * credentials, then resolver policy headers, then the org header. Policy
+ * headers never carry `Content-Type` — the wire owns it, and a policy
+ * `Content-Type` merged over a GET SSE call would corrupt the wire, so the
+ * factory strips it defensively.
+ */
+
+/**
+ * The ONE classified error shape for Matrx client calls — the envelope hosts
+ * branch on instead of string-matching exceptions. Structurally compatible
+ * with matrx-frontend's `ApiCallError` by design.
+ */
+interface MatrxCallError {
+    type: "auth_error" | "network_error" | "http_error" | "validation_error" | "abort_error" | "unknown";
+    message: string;
+    /** HTTP status code, if applicable. */
+    status?: number;
+    /** Raw error detail from the server (the parsed error body). */
+    serverDetail?: unknown;
+    /** Machine code preserved through normalization (server `code`, org-context code, …). */
+    code?: string;
+    /** Original exception identity for diagnostics. */
+    name?: string;
+    /** Original exception stack. */
+    stack?: string;
+    /** JSON-safe dump of the original thrown value. */
+    raw?: unknown;
+}
+/**
+ * Classify any failure thrown by a Matrx client call — `MatrxApiError`, a
+ * typed `BackendApiError` / `StreamTransportError`, a `NetError` from the
+ * resilience layer, an org-context refusal, an abort — into the
+ * `MatrxCallError` envelope. Never throws.
+ *
+ * Every message is laundered through `honestTransportMessage`: a bare status
+ * line ("HTTP 400") never reaches a person — the status rides `status`.
+ * A `BackendApiError` keeps its machine `code` (a dropped socket stays
+ * `stream_transport_lost`, so a surface reattaches instead of dead-ending)
+ * and its structured `details` ride `serverDetail` (the organization-hold
+ * body carries the caller's membership choices there).
+ */
+declare function normalizeMatrxError(err: unknown): MatrxCallError;
+/**
+ * A fully-resolved connection target for one call: where to send it and which
+ * policy headers ride ON TOP of the wire + credential headers.
+ */
+interface MatrxTransportTarget {
+    /** Fully-qualified base URL, no trailing slash. */
+    baseUrl: string;
+    /**
+     * Extra policy headers for this target (e.g. a resolver that carries its own
+     * credential headers). `Content-Type` is stripped — the wire owns it.
+     */
+    policyHeaders?: Record<string, string>;
+    /** Routing channel label surfaced to `onRequest` telemetry. */
+    channel?: string;
+}
+/** Context handed to every diagnostics callback. */
+interface MatrxRequestInfo {
+    /** The final URL (base + version-transformed path). */
+    url: string;
+    method: "GET" | "POST";
+    /** The server-relative path as the package requested it. */
+    path: string;
+    /** The resolved routing channel (default "default"). */
+    channel: string;
+    /** The transport's call-site label (default "matrxTransport"). */
+    source: string;
+}
+/**
+ * The typed diagnostics sink — the host wires these to its telemetry/capture
+ * systems; all optional, and the transport is fully functional without them.
+ */
+interface MatrxTransportDiagnostics {
+    /** Fired at the last pre-fetch moment of every call. */
+    onRequest?: (info: MatrxRequestInfo) => void;
+    /**
+     * Fired for every thrown network failure and every non-2xx response not
+     * listed in `expectedErrorStatuses`, with the classified envelope.
+     */
+    onError?: (error: MatrxCallError, info: MatrxRequestInfo) => void;
+    /** Fired on every v2 → v1 protocol downgrade. */
+    onProtocolDowngrade?: (downgrade: MatrxProtocolDowngrade) => void;
+}
+interface CreateMatrxTransportOptions {
+    /** Fixed base URL, no trailing slash. Exactly one of `baseUrl` / `resolveTarget`. */
+    baseUrl?: string;
+    /**
+     * Per-call target resolver — for hosts whose base URL / policy headers are
+     * dynamic (server toggles, sandbox overrides, conversation channels).
+     * Resolution runs fresh on EVERY call and receives that call's request, so a
+     * resolver reads the call's OWN `X-Organization-Id` (a run's organization,
+     * `withRunOrganization`) instead of substituting the session's. May return a
+     * Promise to HOLD the call (e.g. while the person picks an organization), or
+     * throw to refuse it loudly.
+     */
+    resolveTarget?: (request: MatrxTransportRequest) => MatrxTransportTarget | Promise<MatrxTransportTarget>;
+    /**
+     * The credential source (`@ai-matrx/data`), read fresh per call so token
+     * refreshes are picked up mid-run. Omit only when the resolver's
+     * `policyHeaders` already carry the credentials.
+     */
+    credentials?: CredentialsPort;
+    /**
+     * The org-context binding. When configured, every call REQUIRES a valid org
+     * (fail-closed `organization_context_required` before the wire) and carries
+     * `X-Organization-Id`. Omit for conversation-lane transports, which send the
+     * org in the body only.
+     */
+    organizationId?: string | (() => string | null | undefined);
+    /** AI API protocol version (value or per-call getter). Default `"v2"`. */
+    aiApiVersion?: MatrxAiApiVersion | (() => MatrxAiApiVersion);
+    /** Max ms request start → response headers. Default 15_000. */
+    connectTimeoutMs?: number;
+    /**
+     * Max ms for the whole handshake. Default `null` (uncapped) — the port
+     * cannot tell a JSON call from a long-lived stream, and capping would kill
+     * long streams; the connect timeout is the real JSON guard.
+     */
+    totalTimeoutMs?: number | null;
+    /**
+     * HTTP failures this transport's call class fully handles as expected
+     * domain outcomes (e.g. 404 on runtime-operation identify). They still
+     * reach the package client (which maps them to typed results) but are not
+     * reported through `onError`.
+     */
+    expectedErrorStatuses?: readonly number[];
+    /** Short call-site label surfaced on `MatrxRequestInfo` (default "matrxTransport"). */
+    source?: string;
+    diagnostics?: MatrxTransportDiagnostics;
+}
+/**
+ * Build the production `MatrxTransport`. See the module doc for the pipeline;
+ * every knob defaults to the proven production value.
+ */
+declare function createMatrxTransport(options: CreateMatrxTransportOptions): MatrxTransport;
+
+/**
+ * `@ai-matrx/agents/matrx` — THE request pipeline every typed Matrx server call
+ * rides (chat package independence P9b). One implementation for every client:
+ * matrx-frontend's `lib/api` `callApi` and the chat package's bare-host default
+ * both build on it, and supply only their host facts — where the server is,
+ * which credential and organization ride, and where diagnostics go.
+ *
+ * What lives here (pure, no host/window/env read):
+ *
+ * - `buildMatrxRequestUrl` — path params, the legacy `/api` strip, the query;
+ * - `buildMatrxRequestBody` — scope injection (`organization_id` /
+ *   `project_id` / `task_id`), the UI-only field strip, and the fail-closed
+ *   body-vs-context organization check;
+ * - `bareStatusSentence` / `isBareTransportCode` / `honestTransportMessage` —
+ *   a bare status code is never a sentence at a person;
+ * - `parseMatrxNdjsonResponse` — a response body as typed envelopes, a broken
+ *   body reader classified as a resumable `StreamTransportError`;
+ * - `executeMatrxCall` — the JSON or NDJSON execution over the v2 → v1
+ *   protocol fallback, with the stream callbacks and `consumeStream`;
+ * - `sendMatrxRequest` / `readMatrxJsonResponse` — the raw-`Response` lane
+ *   for a host's imperative client (multipart bodies, byte downloads,
+ *   response-aware callers): one deadline, a caller abort kept as itself, and
+ *   the ONE HTTP error parser;
+ * - `buildSafeRequestLog` / `redactUrlForRequestLog` /
+ *   `shouldReportMatrxCallError` — the log and capture policy.
+ *
+ * The error envelope (`MatrxCallError`) and its ONE classifier
+ * (`normalizeMatrxError`) live in `./client`.
+ */
+
+type MatrxHttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH";
+/**
+ * Every context dimension a call may carry. `organization_id`, `project_id`
+ * and `task_id` are injected into the body; `user_id` rides the credential and
+ * `conversation_id` the path or an explicit body field — never injected.
+ */
+interface MatrxCallScope {
+    user_id?: string;
+    organization_id?: string;
+    project_id?: string;
+    task_id?: string;
+    conversation_id?: string;
+}
+interface MatrxCallResult<T = unknown> {
+    /** Parsed JSON response body (non-streaming calls only). */
+    data?: T;
+    /** Server-assigned request id (response header). */
+    requestId?: string;
+    /** Server-assigned conversation id (response header). */
+    conversationId?: string;
+    /** Set when the call failed with an HTTP error response. */
+    error?: MatrxCallError;
+}
+type MatrxQueryScalar = string | number | boolean;
+/**
+ * Query values: a scalar is sent as itself, an array repeats the key (the
+ * FastAPI repeatable-parameter convention), `null` / `undefined` are omitted.
+ */
+type MatrxQueryParams = Record<string, MatrxQueryScalar | readonly MatrxQueryScalar[] | null | undefined>;
+/**
+ * The full URL for one call: `{param}` segments substituted (encoded), the
+ * legacy `/api` prefix stripped (server routes no longer live under it), and
+ * the query appended.
+ */
+declare function buildMatrxRequestUrl(baseUrl: string, pathTemplate: string, pathParams?: Record<string, string>, queryParams?: MatrxQueryParams): string;
+/**
+ * Client capability flags that must never reach the server — the server's
+ * request schemas reject them.
+ */
+declare const MATRX_UI_ONLY_BODY_FIELDS: ReadonlySet<string>;
+/**
+ * The final request body: UI-only fields stripped, scope fields injected.
+ *
+ * A caller's `organization_id: null` (or blank) means "I have none of my own",
+ * never "send this for a different organization" — it is dropped and the
+ * scope's organization injected. A real value that disagrees with the scope
+ * is refused (`organization_context_mismatch`). With no scope organization
+ * (the org-less guest lane, an org-free read) nothing is injected for it.
+ * Other scope fields keep caller-wins behaviour.
+ */
+declare function buildMatrxRequestBody(body: unknown, scope: MatrxCallScope): Record<string, unknown>;
+/** True when a candidate sentence is really just the status line wearing words. */
+declare function isBareTransportCode(text: string | null | undefined): boolean;
+/**
+ * A BARE STATUS CODE IS NEVER A SENTENCE. What a person reads when the server
+ * answered an error with no readable message. The status itself rides
+ * `error.status`, which is what code branches on — this is only the words.
+ */
+declare function bareStatusSentence(status: number): string;
+/** `raw` unless it is empty or only a status line; then the status sentence. */
+declare function honestTransportMessage(raw: string, status: number | undefined): string;
+/** Request metadata safe to log: secret headers redacted, the body as its shape only. */
+declare function buildSafeRequestLog(headers: Record<string, string>, body: unknown): {
+    headers: Record<string, string>;
+    body: Record<string, unknown>;
+};
+/** The URL with every query value redacted. */
+declare function redactUrlForRequestLog(url: string): string;
+/** False only for an HTTP status the call site declared an expected outcome. */
+declare function shouldReportMatrxCallError(status: number | null | undefined, expectedErrorStatuses: readonly number[] | undefined): boolean;
+interface MatrxStreamIds {
+    requestId: string | null;
+    conversationId: string | null;
+}
+interface MatrxStreamParse<E = MatrxStreamEnvelope> extends MatrxStreamIds {
+    events: AsyncGenerator<E, void, undefined>;
+}
+interface ParseMatrxNdjsonResponseHooks {
+    /** Every envelope, before the consumer sees it. */
+    onEvent?: (event: MatrxStreamEnvelope, ids: MatrxStreamIds) => void;
+    /** A broken body reader, already classified, before it is thrown. */
+    onTransportError?: (error: BackendApiError, ids: MatrxStreamIds) => void;
+    onMalformedLine?: (issue: MatrxNdjsonIssue) => void;
+    onUnknownEnvelope?: (value: unknown) => void;
+}
+/**
+ * A Matrx NDJSON response as typed envelopes. The ids come from headers, so
+ * they are available before any event. A body that breaks mid-run is a
+ * TRANSPORT loss (the run may still finish server-side and is reattachable) —
+ * thrown as `StreamTransportError`, never a failed run; an abort ends quietly.
+ */
+declare function parseMatrxNdjsonResponse(response: Response, signal?: AbortSignal, hooks?: ParseMatrxNdjsonResponseHooks): MatrxStreamParse;
+interface ExecuteMatrxCallRequest<E = MatrxStreamEnvelope> {
+    /** The final URL (`buildMatrxRequestUrl`). */
+    url: string;
+    method: string;
+    /** Every header the host binds (credential, organization, Content-Type). */
+    headers: Record<string, string>;
+    /** The assembled body (`buildMatrxRequestBody`); never sent on GET/HEAD. */
+    body: unknown;
+    /** NDJSON streaming call. */
+    stream?: boolean;
+    signal?: AbortSignal;
+    /** Time to response headers. Default 15_000. */
+    connectTimeoutMs?: number;
+    /** Whole-request cap for JSON calls. Default 30_000; `null` uncaps. Streams are uncapped. */
+    totalTimeoutMs?: number | null;
+    /** Fires when headers arrive, before any event. */
+    onStreamStart?: (requestId: string | null, conversationId: string | null) => void;
+    onStreamEvent?: (event: E) => void;
+    /**
+     * Take ownership of the body instead of the executor draining it (a body is
+     * consumed once). `onStreamEvent` is then not called; start / complete /
+     * error still fire.
+     */
+    consumeStream?: (response: Response, ids: MatrxStreamIds) => Promise<void>;
+    onStreamComplete?: (requestId: string | null, conversationId: string | null) => void;
+    /** Fires for an HTTP error response on a stream (thrown failures are the caller's). */
+    onStreamError?: (error: MatrxCallError) => void;
+}
+interface ExecuteMatrxCallHooks<E = MatrxStreamEnvelope> {
+    /** Every v2 → v1 protocol downgrade. */
+    onProtocolDowngrade?: (downgrade: MatrxProtocolDowngrade) => void;
+    /** The host's stream parser (default `parseMatrxNdjsonResponse`). */
+    parseStream?: (response: Response, signal?: AbortSignal) => MatrxStreamParse<E>;
+}
+/**
+ * Execute one call over the v2 → v1 protocol fallback. An HTTP error
+ * response resolves as `{ error }`; a thrown failure (network, timeout,
+ * abort, a broken stream) propagates — the caller normalizes it with
+ * `normalizeMatrxError` and decides what to capture.
+ */
+declare function executeMatrxCall<T = unknown, E = MatrxStreamEnvelope>(request: ExecuteMatrxCallRequest<E>, hooks?: ExecuteMatrxCallHooks<E>): Promise<MatrxCallResult<T>>;
+interface SendMatrxRequestOptions {
+    /** Caller cancellation; an abort propagates as the caller's own AbortError. */
+    signal?: AbortSignal;
+    /**
+     * Deadline (ms) from send to response headers. On expiry the call rejects
+     * with a `BackendApiError` coded `request_timeout` (status 504) — never a
+     * fake caller cancellation. Omit for no deadline.
+     */
+    timeoutMs?: number;
+}
+/**
+ * Send one request and resolve with the raw `Response`, whatever its status.
+ * The lane for an imperative host client whose bodies are not JSON (a
+ * `FormData` upload), whose answers are bytes, or which reads the response
+ * itself. A caller abort and a network failure propagate unchanged; only this
+ * call's own deadline is classified (`request_timeout`).
+ */
+declare function sendMatrxRequest(url: string, init?: RequestInit, options?: SendMatrxRequestOptions): Promise<Response>;
+/**
+ * A response's JSON body, or the ONE classified `BackendApiError`
+ * (`parseHttpError`) for a non-2xx answer. A 204 resolves `null`.
+ */
+declare function readMatrxJsonResponse<T>(response: Response): Promise<T>;
+
+/**
+ * The fail-closed organization-context kernel — ONE implementation for every
+ * Matrx client transport (moved in from matrx-frontend
+ * `lib/api/organization-context.ts` verbatim under C22; the host module is now
+ * a re-export of this one).
+ *
+ * Transports resolve their authoritative organization first, then use these
+ * functions to bind that exact value without guessing or defaulting. The
+ * server never manufactures an org (it 422s a blank one), so the client
+ * refuses before the wire: a missing or malformed org id throws
+ * `OrganizationContextError` instead of sending a request that cannot succeed.
+ */
+type OrganizationContextErrorCode = "organization_context_required" | "organization_context_invalid" | "organization_context_mismatch";
+declare class OrganizationContextError extends Error {
+    readonly code: OrganizationContextErrorCode;
+    constructor(code: OrganizationContextErrorCode, message: string);
+}
+declare const organizationOperationBrand: unique symbol;
+/** A validated organization operation; construct only through the factory. */
+type OrganizationOperation = Readonly<{
+    organization_id: string;
+    readonly [organizationOperationBrand]: true;
+}>;
+declare function createOrganizationOperation(organizationId: string): OrganizationOperation;
+declare function assertOrganizationMatchesOperation(operation: OrganizationOperation, organizationId: string): void;
+/**
+ * Normalize and validate the effective organization id for a request. The
+ * override (an explicit per-call value) beats the selected context value.
+ * Throws `organization_context_required` when neither is present and
+ * `organization_context_invalid` when the candidate is not a UUID.
+ */
+declare function requireOrganizationContext(selectedOrganizationId: string | null | undefined, overrideOrganizationId?: string): string;
+/**
+ * Bind `X-Organization-Id` onto a header bag. A pre-existing org header that
+ * disagrees with the context org is a `organization_context_mismatch` error —
+ * never silently overwritten in either direction.
+ */
+declare function applyOrganizationContextHeader(headers: Record<string, string>, organizationId: string): Record<string, string>;
+/**
+ * Assert that an `organization_id` query parameter (when present) matches the
+ * request context organization — the query string must never smuggle a
+ * different org past the header binding.
+ */
+declare function assertQueryOrganizationMatchesContext(queryParams: Record<string, string | number | boolean> | undefined, organizationId: string): void;
+
+/** `@ai-matrx/agents/matrx` — moved from matrx-frontend `lib/api/log-api-target.ts` (chat-package independence P9). */
+/**
+ * lib/api/log-api-target.ts
+ *
+ * ONE place that logs the *final, resolved* destination of every outbound
+ * backend call — at the last moment, after every layer of server-address
+ * resolution has run and the URL can no longer change before `fetch()`.
+ *
+ * Why this exists:
+ *   We have several independent resolution layers — `selectResolvedBaseUrl`
+ *   (apiConfigSlice), the EC2 / sandbox override channel in
+ *   `resolve-base-url.ts`, per-call `forceBaseUrl` / `baseUrlOverride`, and
+ *   the env-var fallback in `python-client.ts`. A bug in any one of them can
+ *   silently send traffic to the wrong host (or to the sandbox URL, which is
+ *   reserved for a single rare case). This logger makes the actual target of
+ *   EVERY call visible in the console so misrouting is impossible to miss.
+ *
+ * Call this immediately before the `fetch()` / `resilientFetch()` /
+ * `XMLHttpRequest.open()` that uses the URL — never earlier.
+ */
+interface ApiTargetLogContext {
+    /** Short label of the call site, e.g. "callApi", "python-client.postJson". */
+    source: string;
+    /** HTTP method when known. */
+    method?: string;
+    /**
+     * Resolution channel when the call site knows it — "global" / "override" /
+     * "ec2-dedicated" / "force" / "env-fallback". Surfaces sandbox routing.
+     */
+    channel?: string;
+    /** The active server environment key from apiConfigSlice, when available. */
+    activeServer?: string;
+    /** Anything else worth seeing (conversationId, requestId, etc.). */
+    [extra: string]: unknown;
+}
+/**
+ * Log the final resolved target URL for an outbound backend call.
+ *
+ * Normal calls log at `console.info` with a green tag. Calls whose host looks
+ * like a sandbox/override target log at `console.error` with a red tag so they
+ * are impossible to miss while hunting a misrouting bug.
+ */
+declare function logApiTarget(url: string, context: ApiTargetLogContext): void;
+
+/**
+ * `@ai-matrx/agents/matrx` — the single primitive that transforms a server
+ * endpoint PATH (never the base URL) before it is sent: an exact per-path
+ * override, else a global version prefix. Moved from matrx-frontend
+ * `lib/api/resolve-endpoint-path.ts` (chat-package independence P9).
+ */
+interface EndpointOverrideConfig {
+    /**
+     * Global leading version segment applied to every path that has no exact
+     * pathOverride. `null` / empty → no version transform. The value may be
+     * given with or without a leading slash ("v2" and "/v2" both work).
+     */
+    apiVersion?: string | null;
+    /**
+     * Exact-match canonical-path → replacement-path map. Keys are the path
+     * template exactly as written in `ENDPOINTS` / the generated schema
+     * (including any `{param}` segments). Wins over `apiVersion`.
+     */
+    pathOverrides?: Record<string, string>;
+}
+/**
+ * Resolve the final path for a canonical endpoint path, applying any active
+ * override layers. Pure — given the same inputs it always returns the same
+ * path. Callers prepend the resolved base URL themselves.
+ *
+ * @param canonicalPath The path exactly as declared in ENDPOINTS / the schema.
+ * @param config        The active override layers (read from Redux).
+ */
+declare function resolveEndpointPath(canonicalPath: string, config?: EndpointOverrideConfig | null): string;
+
+/**
+ * Stamp the admin desktop-target preference onto a request body — but ONLY
+ * when the body already declares a live `desktop-native` capability.
+ *
+ * The preference (Settings → Admin Server, `adminPreferences.
+ * desktopTargetInstanceId`, persisted local-only) may DIRECT delegation to a
+ * specific desktop; it must never DECLARE one. Fabricating the capability
+ * here used to override the presence gate in `desktop-native.provider.ts`,
+ * so a stale preference silently rode every AI turn: the server stamped
+ * `target_instance_id` onto delegated tool calls while the smart-input
+ * indicator truthfully showed no desktop bound, and browser-executed tools
+ * (war_room_*, ui-first) 404'd their own /tool_results (submission-binding
+ * check) and wedged the turn.
+ */
+declare function applyDesktopTargetToRequestBody(body: unknown, targetInstanceId: string | null | undefined): void;
+
+/**
+ * `@ai-matrx/agents/matrx` — moved from matrx-frontend `lib/api/run-wait.ts` (chat-package
+ * independence P9). The knob read is injected (`resolveRunWaitWith`); the host wraps it.
+ */
+/**
+ * How long a client waits for the server to START answering a run — per output
+ * kind, as an organization knob.
+ *
+ * 🚨 THE DEFECT (2026-09-22). Pressing Run in the agent builder on an image
+ * agent ("Product Photo Studio", Gemini 3.1 Flash Image) died on the client with
+ * "Connection timed out after 15000ms". The builder's manual path was the only
+ * agent stream path carrying a fixed 15-second `connectTimeoutMs`, and that
+ * timer does not measure a TCP connect: aidream's prepared-streaming routes
+ * (`create_prepared_streaming_response`) finish request PREPARATION — auth, the
+ * request lane, conversation create, resolving attached files — BEFORE the
+ * response headers go out. A busy server or a draining deploy pushed prep past
+ * 15 s, the client aborted, and aborting before the headers dropped the server
+ * run with it (conversation created, no messages).
+ *
+ * THE RULE. A generation is a job, not a request with a stopwatch:
+ *   - Once the stream is open there is NO wall-clock cap — the server heartbeat
+ *     (every 5 s) keeps the watchdog fed and the run ends on the stream's own
+ *     `end` event.
+ *   - The one cap that remains — "the server never started answering" — is an
+ *     organization knob per output kind (`agents.run_wait.<kind>_seconds`),
+ *     with generous agent-set defaults registered in the knob table, never a
+ *     constant here.
+ *   - When that cap is actually hit, the person is told the truth: which model,
+ *     how long we waited, and that the server may still be working — with a
+ *     door to the conversation, because the run can finish without us.
+ *
+ * If the knob snapshot cannot be read the wait falls back to the stream
+ * lifetime backstop (announced loudly), never to a number nobody chose.
+ */
+/** What a run produces. Anything but text is a job (seconds to minutes). */
+/** Every output kind a run can wait on — one `<kind>_seconds` knob each. */
+declare const RUN_OUTPUT_KINDS: readonly ["text", "image", "video", "audio"];
+type RunOutputKind = (typeof RUN_OUTPUT_KINDS)[number];
+declare const RUN_WAIT_KNOB_FEATURE = "agents.run_wait";
+/**
+ * Stream lifetime backstop — the same 24 hours the agent run path
+ * (`runAiStream`) has always used. It is the ceiling for a stream that keeps
+ * heartbeating forever, not a wait anyone tunes; the heartbeat watchdog is the
+ * real liveness check. Also the first-response wait when the knob cannot be
+ * read (setTimeout's own ceiling is ~24.8 days, so this stays safe).
+ */
+declare const RUN_STREAM_LIFETIME_BACKSTOP_MS: number;
+declare function isJobOutputKind(kind: RunOutputKind): boolean;
+/**
+ * The output kind from a model's declared output modalities (the parsed
+ * `capabilities.output` list). Video outranks image outranks audio: a model
+ * that can emit several is waited on as its slowest.
+ */
+declare function runOutputKindFromModalities(output: readonly string[] | null | undefined): RunOutputKind;
+declare function runWaitKnobKey(kind: RunOutputKind): string;
+interface RunWait {
+    /** Milliseconds the client waits for the stream to open. */
+    firstResponseMs: number;
+    /** Seconds as configured, or null when the knob could not be read. */
+    seconds: number | null;
+    kind: RunOutputKind;
+}
+/**
+ * Resolve the first-response wait for one run from the organization's knob.
+ * Never throws — a run is never refused because a setting could not load; the
+ * failure is announced and the wait becomes the lifetime backstop.
+ */
+/**
+ * Reads one settings-register knob for an organization (and person). The HOST
+ * supplies it — matrx-frontend: `ensureEffectiveKnob` (lib/scoped-config).
+ */
+type RunWaitKnobReader = (organizationId: string, userId: string | null, knob: {
+    feature: string;
+    key: string;
+}) => Promise<unknown>;
+declare function resolveRunWaitWith(readKnob: RunWaitKnobReader, organizationId: string | null | undefined, userId: string | null | undefined, kind: RunOutputKind): Promise<RunWait>;
+/** "Generating an image with Gemini 3.1 Flash Image" — the job's working line. */
+declare function runJobLabel(kind: RunOutputKind, modelLabel: string | null): string;
+/**
+ * The honest sentence for a first-response timeout. The server may still
+ * finish the run, so the sentence says so and the caller attaches a door to
+ * the conversation.
+ */
+declare function runWaitTimeoutMessage(kind: RunOutputKind, modelLabel: string | null, seconds: number | null): string;
+
+/**
+ * `@ai-matrx/agents/matrx` — the client warm-up primitive.
+ *
+ * Contract: common-docs `systems/architecture/warm-cache/CONTRACT.md`.
+ *
+ * A page that knows what the person is about to need says so the moment they
+ * land: `warmup.warm([{ key: "agent", id }], "route")`. Calls made inside a
+ * ~50ms window coalesce into ONE authenticated `POST /ai/warm`; the same item
+ * is not sent twice for the same scope within 60s; the request is
+ * fire-and-forget and NEVER throws, rejects, or blocks. Signed
+ * out → nothing is sent. Until the server endpoint exists the call answers 404
+ * and the primitive stays silent (one `console.debug`, once).
+ *
+ * Auth, base URL and `X-Organization-Id` are the injected `MatrxTransport`'s
+ * job, exactly as for every other call in this package.
+ */
+
+declare const WARM_PATH: "/ai/warm";
+/** Why the warm was requested (the server records it per accepted item). */
+type WarmReason = "session" | "route" | "org_change" | "agent_change" | "conversation_change";
+/** One thing to warm. `core` carries no id; the others name their record. */
+interface WarmItem {
+    key: "core" | "org" | "agent" | "conversation" | (string & {});
+    id?: string | undefined;
+}
+interface CreateWarmupOptions {
+    /** The host's transport — base URL and credentials ride on it. */
+    transport: MatrxTransport;
+    /**
+     * True only for a signed-in person. Read fresh on every use. While false (or
+     * while `scope` is empty) requested warms are QUEUED, not dropped, and go out
+     * when the host calls `notifyScopeChanged()` after the person and org are ready.
+     */
+    isSignedIn: () => boolean;
+    /**
+     * The dedupe scope, read fresh: the person plus the active org
+     * (`${userId}:${orgId}`). Null/empty = not ready yet. Items go out only under
+     * the scope they were requested in; a scope change drops the stale ones (the
+     * page re-issues for the new scope) so nothing is ever sent with the wrong org.
+     */
+    scope?: () => string | null | undefined;
+    /**
+     * The active org id, read at send time and put on the request as
+     * `X-Organization-Id` so the request names the org its scope names.
+     */
+    organizationId?: () => string | null | undefined;
+    /** Coalescing window. Default 50ms. */
+    coalesceMs?: number;
+    /** Per-scope per-item dedupe window after a 2xx. Default 60_000ms. */
+    dedupeMs?: number;
+    /** Clock, for tests. Default `Date.now`. */
+    now?: () => number;
+}
+interface Warmup {
+    /** Queue items for the next coalesced `POST /ai/warm`. Never throws. */
+    warm(items: readonly WarmItem[], reason: WarmReason): void;
+    /** The current scope, or "" while the person/org are not ready. */
+    currentScope(): string;
+    /** Host calls this when the person or org may have changed; flushes the queue. */
+    notifyScopeChanged(): void;
+    /** Subscribe to scope changes (for `useSyncExternalStore`). Returns unsubscribe. */
+    subscribe(listener: () => void): () => void;
+}
+declare function createWarmup(options: CreateWarmupOptions): Warmup;
+/**
+ * Add `<link rel="preconnect">` for the server origin, once per origin, so the
+ * TLS handshake is done before the first AI call. No-op outside a browser.
+ */
+declare function preconnectServer(baseUrl: string | null | undefined): void;
+/** Test seam: forget which origins were preconnected. */
+declare function resetPreconnectedForTests(): void;
+
+/**
+ * Internal request plumbing for `@ai-matrx/agents/matrx`. Not part of the
+ * public surface — `matrx/index.ts` deliberately does not re-export this
+ * module. Everything here is pure: no globals, no work at import time.
+ */
+
+/** Encode one path segment (an id) safely into a server-relative path. */
+declare function encodePathSegment(value: string): string;
+type QueryValue = string | number | boolean | readonly string[] | undefined;
+/**
+ * Build a query string. Array values repeat the key (`kind=a&kind=b` — the
+ * FastAPI repeatable-parameter convention); undefined values are omitted.
+ * Returns "" or a string starting with "?".
+ */
+declare function buildQuery(params: Record<string, QueryValue>): string;
+interface JsonRequestOptions {
+    method: "GET" | "POST";
+    body?: unknown;
+    signal?: AbortSignal;
+}
+/**
+ * Execute a JSON request through the transport. Throws `MatrxApiError` on a
+ * non-2xx response; resolves with the parsed JSON body otherwise.
+ */
+declare function requestJson<T>(transport: MatrxTransport, path: string, options: JsonRequestOptions): Promise<T>;
+/**
+ * Options for every streaming call, riding the NDJSON kernel's contract.
+ * Public via `./run`'s re-export.
+ */
+interface MatrxStreamCallOptions {
+    /** Abort the fetch and end the events iterator. */
+    signal?: AbortSignal;
+    /** Bounded background read-ahead (see `stream/ndjson`). */
+    maxReadAhead?: number;
+    /** Malformed NDJSON is non-fatal but must never disappear silently. */
+    onMalformedLine?: (issue: MatrxNdjsonIssue) => void;
+    /** Valid JSON with no recognized Matrx envelope. */
+    onUnknownEnvelope?: (value: unknown) => void;
+    /** Observe every valid envelope in its exact wire form. */
+    onValidEnvelope?: (observation: MatrxStreamEnvelopeObservation) => void;
+}
+/**
+ * A live agent run: the server-assigned ids (from response headers, available
+ * BEFORE any event) and the normalized event stream. Public via `./run`.
+ */
+interface MatrxRunHandle {
+    /** `X-Request-ID` — the ONLY id `POST /ai/cancel/{request_id}` accepts. */
+    requestId: string | null;
+    /** `X-Conversation-ID` — the server's conversation identity. */
+    conversationId: string | null;
+    /** Normalized `{event, data}` envelopes through the ONE wire kernel. */
+    events: AsyncGenerator<MatrxStreamEnvelope, void, undefined>;
+    /** The raw response, for hosts that need headers/status beyond the ids. */
+    response: Response;
+}
+/**
+ * Wrap a validated streaming Response into the run handle — the ONE place
+ * the id headers are read and the NDJSON kernel is attached (`./run` and
+ * `./operations`' rejoin share it).
+ */
+declare function toRunHandle(response: Response, options: MatrxStreamCallOptions): MatrxRunHandle;
+interface StreamRequestOptions {
+    method: "GET" | "POST";
+    body?: unknown;
+    /** Extra wire-semantic headers (`Accept`, `Last-Event-ID`). */
+    headers?: Record<string, string>;
+    signal?: AbortSignal;
+}
+/**
+ * Execute a streaming request. Throws `MatrxApiError` on a non-2xx response
+ * (reading the error body as JSON when possible) or when a 2xx response
+ * carries no body; resolves with the validated `Response` otherwise.
+ */
+declare function requestStream(transport: MatrxTransport, path: string, options: StreamRequestOptions): Promise<Response>;
+
+/**
+ * The conversation-start contract — client-minted `conversation_id`, `is_new`,
+ * `store` — typed exactly per the cross-repo System of Record
+ * (`common-docs/systems/agents/conversation-start-contract/FEATURE.md`;
+ * server truth `aidream/services/conversation_context/scope.py::
+ * ConversationStartRequest`).
+ *
+ * Every request that STARTS a conversation sends all three fields, no
+ * defaults:
+ *
+ * | `is_new` | `store` | Result                                                   |
+ * |----------|---------|----------------------------------------------------------|
+ * | true     | true    | Create the row with the caller's id — 409 if it exists   |
+ * | true     | false   | No row. The id is correlation only (ephemeral run)       |
+ * | false    | true    | Continue it — 404 if the caller doesn't own it           |
+ * | false    | false   | Ephemeral run on a known id; nothing read, nothing written |
+ *
+ * `store` is the ONLY ephemeral signal; `is_new` is the caller's assertion
+ * about the id, never a persistence switch. `prior_messages` (the client-owned
+ * transcript of an ephemeral multi-turn run) is only valid with
+ * `store: false` — the union below makes the invalid combination
+ * unrepresentable, mirroring the server's 422.
+ *
+ * Continue routes (`POST /ai/conversations/{id}`) take the id from the path
+ * and do not carry this triple.
+ */
+/** Recursive JSON value — the package's honest type for free-form wire bags. */
+type MatrxJsonValue = string | number | boolean | null | MatrxJsonValue[] | {
+    [key: string]: MatrxJsonValue;
+};
+/** A JSON object on the wire. */
+type MatrxJsonObject = {
+    [key: string]: MatrxJsonValue;
+};
+/**
+ * One LLM message on the request wire — `prior_messages` entries for
+ * stateless multi-turn runs. Mirrors aidream's `ChatMessageInput`
+ * (`aidream/schemas/messages.py`, `extra="allow"` — additional provider
+ * fields round-trip untouched).
+ */
+interface MatrxChatMessage {
+    role: string;
+    content?: string | MatrxJsonValue[] | null;
+    name?: string | null;
+    tool_call_id?: string | null;
+    tool_calls?: MatrxJsonObject[] | null;
+    [extra: string]: MatrxJsonValue | undefined;
+}
+/** `is_new: true, store: true` — create the row with the caller's id. */
+interface MatrxStoredConversationCreate {
+    conversation_id: string;
+    is_new: true;
+    store: true;
+}
+/** `is_new: false, store: true` — continue an owned stored conversation via a start route. */
+interface MatrxStoredConversationContinue {
+    conversation_id: string;
+    is_new: false;
+    store: true;
+}
+/**
+ * `store: false` — ephemeral: nothing read, nothing written; the id is the
+ * caller's correlation handle. This is the ONLY member that may carry
+ * `prior_messages` (the server 422s a client transcript on a stored run).
+ */
+interface MatrxEphemeralConversation {
+    conversation_id: string;
+    is_new: boolean;
+    store: false;
+    prior_messages?: MatrxChatMessage[];
+}
+/** The full conversation-start triple, one member per contract cell. */
+type MatrxConversationStart = MatrxStoredConversationCreate | MatrxStoredConversationContinue | MatrxEphemeralConversation;
+/** Mint a fresh client-side conversation id (the contract requires the CLIENT to mint it). */
+declare function mintMatrxConversationId(): string;
+/** Start a NEW stored conversation (`is_new: true, store: true`). */
+declare function newStoredConversationStart(conversationId?: string): MatrxStoredConversationCreate;
+/**
+ * Continue an EXISTING stored conversation through a start route
+ * (`is_new: false, store: true` — 404 when the caller doesn't own the id).
+ * Prefer `continueAgentConversation` (the dedicated continue route) for
+ * ordinary follow-up turns.
+ */
+declare function continueStoredConversationStart(conversationId: string): MatrxStoredConversationContinue;
+/**
+ * Start a NEW ephemeral run (`is_new: true, store: false`) — a freshly minted
+ * correlation id, nothing persisted.
+ */
+declare function newEphemeralConversationStart(conversationId?: string): MatrxEphemeralConversation;
+/**
+ * Continue an ephemeral multi-turn run (`is_new: false, store: false`): the
+ * CLIENT owns the transcript and replays it as `prior_messages` (ordered
+ * oldest-first) because the server wrote no rows to rebuild from. The server
+ * still owns the agent definition, model, tools, and system prompt.
+ */
+declare function continueEphemeralConversationStart(conversationId: string, priorMessages: MatrxChatMessage[]): MatrxEphemeralConversation;
+
+/**
+ * Runtime operations — the canonical reconnect & resume read surface of the
+ * execution spine, over the `MatrxTransport` port.
+ *
+ * Server truth (verified against aidream source,
+ * `aidream/api/routers/runtime_operations.py` + `aidream/services/runtime/
+ * reconnect.py`; mounted at bare `/runtime`):
+ * - `GET  /runtime/operations/{request_id}`            — identify by `X-Request-ID`
+ * - `GET  /runtime/operations/by-link/{kind}/{id}`     — identify by feature record
+ * - `GET  /runtime/executions/{id}/events`             — durable seq-cursored page
+ * - `GET  /runtime/executions/{id}/events/stream`      — SSE replay-then-follow,
+ *   `id:` = per-tree seq, reconnect with `Last-Event-ID`
+ * - `POST /runtime/operations/{request_id}/rejoin`     — replay + follow the
+ *   ORIGINAL NDJSON response while its detached task is alive (409 when live
+ *   delivery is unavailable — fall back to the durable lifecycle stream)
+ *
+ * The contract: identify → recover durable progress → follow live → re-query
+ * the final result from the feature's own record. Token text is deliberately
+ * never replayed on the lifecycle stream — that is what `/rejoin` is for.
+ *
+ * The SSE wire rides the package's own `stream/sse` kernel. This module owns
+ * ONE connection's semantics (frames → typed events, cursor advancement,
+ * terminal `end`); stall timers, retry budgets, and reconnect loops stay host
+ * policy — every yielded item carries the cursor the next attempt resumes from.
+ */
+
+/** `matrx_runtime.models.ExecutionStatus` — the only progress column. */
+type MatrxRuntimeExecutionStatus = "pending" | "running" | "paused" | "waiting_input" | "completed" | "failed" | "cancelled";
+declare const TERMINAL_MATRX_RUNTIME_STATUSES: ReadonlySet<MatrxRuntimeExecutionStatus>;
+/** One durable spine event on the wire (`OperationEvent`) — `seq` is the reconnect cursor. */
+interface MatrxRuntimeOperationEvent {
+    seq: number | null;
+    /** Lifecycle vocabulary: created | started | paused | resumed | waiting_input | completed | failed | cancelled | checkpoint_saved | note. */
+    kind: string;
+    execution_id: string;
+    root_execution_id: string | null;
+    detail: MatrxJsonObject | null;
+    created_at: string | null;
+}
+/** One root execution as a reconnecting client sees it (`OperationView`). */
+interface MatrxRuntimeOperationView {
+    execution_id: string;
+    /** Durable request identity — feeds `/rejoin` and no-prompt resume recovery. */
+    request_id: string | null;
+    /**
+     * The root run's request id — the rejoin handle when by-link returns the
+     * LINKED execution (with its own status) instead of the root. Absent on
+     * older servers; `request_id` then is the handle.
+     */
+    root_request_id?: string | null;
+    type: string;
+    status: MatrxRuntimeExecutionStatus;
+    is_terminal: boolean;
+    waiting_input: boolean;
+    /** Decimal on the wire — may arrive as number or string; display-only. */
+    cost: number | string;
+    meters: Record<string, number | string>;
+    link_kind: string | null;
+    link_id: string | null;
+    error: MatrxJsonObject | null;
+    created_at: string | null;
+    started_at: string | null;
+    ended_at: string | null;
+    last_event_seq: number;
+    events_path: string;
+    stream_path: string;
+}
+interface MatrxOperationStatusResponse {
+    request_id: string;
+    operation_count: number;
+    operations: MatrxRuntimeOperationView[];
+}
+interface MatrxOperationsByLinkResponse {
+    link_kind: string;
+    link_id: string;
+    operation_count: number;
+    operations: MatrxRuntimeOperationView[];
+}
+interface MatrxOperationEventsPage {
+    execution_id: string;
+    root_execution_id: string;
+    events: MatrxRuntimeOperationEvent[];
+    /** Feeds the next page or the SSE `Last-Event-ID` — polling and push share ONE cursor. */
+    next_after_seq: number;
+    has_more: boolean;
+    root_status: MatrxRuntimeExecutionStatus;
+    root_is_terminal: boolean;
+}
+/**
+ * Where is my operation? Resolves an `X-Request-ID` to its root execution(s).
+ * Returns null on 404 — missing and unowned share one shape by design
+ * (existence is never leaked).
+ */
+declare function getRuntimeOperationStatus(transport: MatrxTransport, requestId: string, options?: {
+    signal?: AbortSignal;
+    executionId?: string;
+}): Promise<MatrxOperationStatusResponse | null>;
+/**
+ * Operations for a feature record — e.g. `("conversation", conversationId)`,
+ * `("workflow", runId)`, `("agent_run", runId)`. Newest first; unowned trees
+ * omitted. Returns null on 404 (surface absent, or the caller owns nothing —
+ * one shape by design).
+ */
+declare function getRuntimeOperationsByLink(transport: MatrxTransport, linkKind: string, linkId: string, options?: {
+    limit?: number;
+    signal?: AbortSignal;
+}): Promise<MatrxOperationsByLinkResponse | null>;
+/**
+ * Durable progress page for the whole operation TREE:
+ * `GET /runtime/executions/{id}/events?after_seq=…`. Pass any node id — it
+ * resolves to the root.
+ */
+declare function listRuntimeOperationEvents(transport: MatrxTransport, executionId: string, options?: {
+    afterSeq?: number;
+    limit?: number;
+    /** Repeatable event-kind filter. */
+    kinds?: readonly string[];
+    signal?: AbortSignal;
+}): Promise<MatrxOperationEventsPage>;
+/**
+ * One item from the follow stream. Every item carries `cursor` — the highest
+ * event seq seen so far, which is exactly the `Last-Event-ID` a reconnect
+ * resumes from (host retry policy owns the reconnect loop).
+ */
+type MatrxOperationFollowEvent = {
+    /** A parsed durable spine event. */
+    type: "event";
+    event: MatrxRuntimeOperationEvent;
+    /** The frame's SSE `id:` as an integer, when it carried one. */
+    seq: number | null;
+    cursor: number;
+} | {
+    /**
+     * A frame that carried no deliverable event — a comment heartbeat, an
+     * unknown event name, or a malformed payload (also surfaced through
+     * `onMalformedFrame`). ANY parsed frame proves the wire is alive: hosts
+     * reset stall timers and retry budgets on it.
+     */
+    type: "liveness";
+    cursor: number;
+} | {
+    /** The server's terminal frame — the root settled; the stream is over. */
+    type: "end";
+    status: MatrxRuntimeExecutionStatus | null;
+    cursor: number;
+};
+interface FollowRuntimeOperationOptions {
+    /** Resume cursor — the operation view's `last_event_seq` (0 = from start). */
+    lastEventSeq?: number;
+    /** Abort the follow — the generator simply ends. */
+    signal?: AbortSignal;
+    /** A frame whose payload failed to parse — never silently dropped. */
+    onMalformedFrame?: (frame: MatrxSseFrame, error: unknown) => void;
+    /** Unterminated trailing SSE text at stream end (diagnostic, never an event). */
+    onIncomplete?: (text: string) => void;
+}
+/**
+ * Follow ONE SSE connection of an operation's lifecycle stream:
+ * `GET /runtime/executions/{id}/events/stream` with `Last-Event-ID` when
+ * resuming past 0. Replays from the cursor, then follows live; a
+ * WAITING_INPUT park keeps it open (a resume re-attaches to the same
+ * execution and its events continue here). Ends after yielding
+ * `{type: "end"}` when the root settles; a server close WITHOUT an end frame
+ * simply ends the generator — reconnect from the last yielded `cursor` (host
+ * retry policy).
+ */
+declare function followRuntimeOperationEvents(transport: MatrxTransport, executionId: string, options?: FollowRuntimeOperationOptions): AsyncGenerator<MatrxOperationFollowEvent, void, undefined>;
+interface FollowRuntimeOperationToEndOptions {
+    /** Resume cursor — the operation view's `last_event_seq` (0 = from start). */
+    lastEventSeq?: number;
+    /** Caller teardown — aborting resolves with `ended: false`. */
+    signal?: AbortSignal;
+    /**
+     * The server pings every ~15s, so a wire that is open but silent past this
+     * is dead (buffering proxy, idle-killed connection) — abort the attempt and
+     * retry rather than hanging forever. Default 45_000.
+     */
+    stallTimeoutMs?: number;
+    /**
+     * Consecutive failed attempts before giving up. A single-server deployment
+     * deliberately drains for 60s, then starts a new container — the default
+     * budget (60 × 2s) keeps following for ~three minutes so the runtime ledger
+     * can bridge that handoff. ANY parsed frame resets the budget. Default 60.
+     */
+    reconnectLimit?: number;
+    /** Delay between attempts. Default 2_000. */
+    reconnectDelayMs?: number;
+    /** Fired per durable spine event (lifecycle transitions + notes). */
+    onEvent: (event: MatrxRuntimeOperationEvent, seq: number | null) => void;
+    /** A failed attempt (never silently swallowed when provided). */
+    onAttemptError?: (error: unknown) => void;
+    /** A frame whose payload failed to parse (the ledger heals gaps on reconnect). */
+    onMalformedFrame?: (frame: MatrxSseFrame, error: unknown) => void;
+}
+interface FollowRuntimeOperationToEndResult {
+    /** True when the server sent the terminal `end` frame. */
+    ended: boolean;
+    /** The root status carried on the `end` frame (when `ended`). */
+    status: MatrxRuntimeExecutionStatus | null;
+}
+/**
+ * Follow an operation's lifecycle stream TO ITS END — the full production
+ * reconnect policy over `followRuntimeOperationEvents`: replay-then-follow
+ * with bounded reconnects, a stall watchdog, and durable `Last-Event-ID`
+ * cursor advancement across attempts.
+ *
+ * Resolves `{ended: true, status}` on the server's `end` frame (the operation
+ * settled); `{ended: false}` when the caller aborted or every reconnect
+ * attempt failed. A WAITING_INPUT park keeps the stream open by design — a
+ * resume re-attaches to the same execution and its events continue arriving
+ * on the same cursor. Any parsed frame — comment heartbeats included —
+ * proves the wire is alive and resets both the stall timer and the retry
+ * budget.
+ */
+declare function followRuntimeOperationToEnd(transport: MatrxTransport, executionId: string, options: FollowRuntimeOperationToEndOptions): Promise<FollowRuntimeOperationToEndResult>;
+/**
+ * Rejoin the ORIGINAL NDJSON response while its detached task is still alive:
+ * `POST /runtime/operations/{request_id}/rejoin`. Replays the response from
+ * frame one, then continues live — every frame is sequence-stamped
+ * (`stream_seq`), so a same-page reconnect can drop frames it already
+ * rendered. Throws `MatrxApiError` with status 409 when live delivery is
+ * unavailable — fall back to `followRuntimeOperationEvents` + a final record
+ * re-query. The `requestId` must be the server's `X-Request-ID`.
+ */
+declare function rejoinRuntimeOperation(transport: MatrxTransport, requestId: string, options?: MatrxStreamCallOptions): Promise<MatrxRunHandle>;
+
+/**
+ * Resume-or-rejoin — the ONE client behavior for "pick a run back up".
+ *
+ * Server truth (aidream `services/runtime/FEATURE.md` § "A live run is
+ * REJOINED, never resumed beside itself"; `reconnect.run_in_progress_error`):
+ * - Every resume / retry / continue door asked to resume a run that is STILL
+ *   LIVE answers `409` with, at the ROOT of the error body,
+ *   `{error, code: "run_in_progress", live_request_id, rejoin_path, message,
+ *   …extras}` (extras: `run_id` for workflow / SEO / comparison, `arm_index` /
+ *   `arm`, `analysis_id`). The client follows `rejoin_path` — never a URL it
+ *   builds — because a door outside the spine (SEO collections) answers
+ *   `live_request_id: null` with its own `/seo/collections/{run_id}/rejoin`.
+ * - Chat/conversation resume answers `code: "resume_conflict"` — even when the
+ *   body ALSO names `live_request_id` + `rejoin_path` — and it is ALWAYS host
+ *   retry, never a rejoin: the claim holder is usually the turn that is still
+ *   SUSPENDING, and rejoining it replays that turn from frame one (duplicate
+ *   text) while the person's continuation never runs. Only
+ *   `code: run_in_progress` rejoins.
+ * - The envelope RESERVES `request_id` for the refusing call's own id — the
+ *   live run is read from `live_request_id`, never `request_id` (reading it
+ *   rejoined a request that did not exist: 404, 2026-10-01).
+ * - A rejoin answers `409 live_stream_unavailable` when there is no journal to
+ *   replay (resumed workflow legs, comparison arms). Then: a body naming a
+ *   workflow `run_id` → follow `GET /runs/{run_id}/events/stream` (the workflow
+ *   SSE, which also carries the node_stream media frames); otherwise follow the
+ *   durable lifecycle (`followRuntimeOperationToEnd`).
+ *
+ * Resume and rejoin are work on an EXISTING run, so they carry THAT run's
+ * organization (`organizationId`), never whatever the session has selected.
+ */
+
+declare const MATRX_RUN_IN_PROGRESS = "run_in_progress";
+declare const MATRX_RESUME_CONFLICT = "resume_conflict";
+declare const MATRX_LIVE_STREAM_UNAVAILABLE = "live_stream_unavailable";
+/**
+ * Any error carrying an HTTP status and the parsed server body —
+ * `MatrxApiError`, matrx-frontend's `ApiCallError`, or a host's own shape.
+ */
+interface MatrxHttpErrorLike {
+    status?: unknown;
+    serverDetail?: unknown;
+}
+/**
+ * The machine code of a Matrx HTTP error: `code` (or the envelope's hoisted
+ * `error`) from `detail`, `details`, or the top level. Null when absent.
+ */
+declare function readMatrxErrorCode(error: unknown): string | null;
+/**
+ * The machine code a server message carries as a PREFIX
+ * (`"resume_conflict: another run is live"` → `resume_conflict`), for envelope
+ * variants that pass the message but map `error` to a generic status word.
+ * Only the known resume/turn-lock codes match; null for anything else.
+ */
+declare function readMatrxErrorCodeFromMessage(message: string | null | undefined): string | null;
+/**
+ * The conversation's own organization id, for scoping a resume/rejoin to the
+ * RUN's organization instead of the session's selection. Transport-agnostic:
+ * the host injects `read` (a supabase select, a REST call, …) returning the raw
+ * `organization_id` (or throwing). Null — with `onUnreadable(reason)` — when it
+ * is missing or unreadable, so the caller keeps the active organization and
+ * says so.
+ */
+declare function readConversationOrganizationId(conversationId: string, read: (conversationId: string) => Promise<unknown>, onUnreadable?: (reason: string | null) => void): Promise<string | null>;
+/** Where to rejoin a live run, read from a resume door's 409. */
+interface MatrxLiveRunRejoin {
+    /** The live request (`GET /runtime/operations/{id}`); null for doors outside the spine (SEO). */
+    liveRequestId: string | null;
+    /** Server-relative path to `POST` for the NDJSON replay-then-follow. Always from the body when present. */
+    rejoinPath: string;
+    /** `run_id` extra (workflow / SEO / comparison), when present. */
+    runId: string | null;
+    /** The refusal's code — always `run_in_progress` (chat's `resume_conflict` is retried, never rejoined). */
+    code: string;
+    /** The refusal body (root of the envelope), for door-specific extras (`arm_index`, `analysis_id`, …). */
+    body: Record<string, unknown>;
+}
+/**
+ * The rejoin target of a live-run refusal: `409` with `code: run_in_progress`.
+ * Null for every other error — a genuine failure is never mistaken for a live
+ * run, and chat's `resume_conflict` is never a rejoin even when its body names
+ * one (the host retries the resume so the continuation runs). Reads
+ * `rejoin_path` from the body first; derives the runtime rejoin from
+ * `live_request_id` only when the body names no path. Never reads
+ * `request_id`.
+ */
+declare function readLiveRunRejoin(error: unknown): MatrxLiveRunRejoin | null;
+/**
+ * The request id of a run that is STILL LIVE, read from a resume door's
+ * refusal (`live_request_id` — never the envelope's own `request_id`). Null
+ * for every other error, and for a live refusal outside the spine (SEO) —
+ * follow `readLiveRunRejoin(error).rejoinPath` instead.
+ */
+declare function readLiveRunRequestId(error: unknown): string | null;
+/**
+ * `409 resume_conflict` — another run holds the conversation's claim (usually
+ * the turn still suspending); retry the resume with the host's backoff so the
+ * continuation runs. Never a rejoin, even when the body names a live run.
+ */
+declare function isResumeConflict(error: unknown): boolean;
+/** `409 live_stream_unavailable` — the rejoin journal is gone; follow the durable lifecycle instead. */
+declare function isLiveStreamUnavailable(error: unknown): boolean;
+/**
+ * The server-relative rejoin path — for hosts whose stream pipeline takes a
+ * URL instead of a transport (prepend the resolved base URL).
+ */
+declare function runtimeOperationRejoinPath(requestId: string): string;
+/**
+ * The text to show for a stream `error` event: the server's `user_message`
+ * first (it is written for the person — e.g. "OpenAI refused this request:
+ * the platform's OpenAI account is out of credit."), then `message`. Accepts
+ * the `{event, data}` envelope or its `data` payload. Null when neither is
+ * present — the host supplies its own fallback; it must never REPLACE a
+ * message the server sent.
+ */
+declare function streamErrorText(eventOrPayload: unknown): string | null;
+/**
+ * Open any Matrx NDJSON stream by path (`POST`, optional JSON body) — for
+ * feature doors outside the agent lifecycle (`/podcast/resume/{run_id}`, …)
+ * so their streams ride the same transport and wire kernel as every run.
+ */
+declare function openMatrxStream(transport: MatrxTransport, path: string, options?: MatrxStreamCallOptions & {
+    body?: unknown;
+}): Promise<MatrxRunHandle>;
+/**
+ * Bind a run's organization onto every call as `X-Organization-Id`. The
+ * call's own org is the request's organization: `createMatrxTransport` hands
+ * it to the host's `resolveTarget(request)`, never lets a policy or session
+ * org replace it, and never refuses it for want of a session org (2026-10-07:
+ * Applet jobs were refused "Select an organization…" before any I/O, and with
+ * an active org set the run silently moved into it).
+ */
+declare function withRunOrganization(transport: MatrxTransport, organizationId: string): MatrxTransport;
+/**
+ * Follow a workflow run's SSE (`GET /runs/{run_id}/events/stream`) — the
+ * rejoin fallback for workflow legs with no stream journal. Delivers every
+ * parsed event (durable run events with their seq; ephemeral `node_stream`
+ * frames — including `kind: "media"` — with seq null). One connection, no
+ * reconnect policy: resolves `{ended: true}` on the server's `end` frame,
+ * `{ended: false}` when the wire closes or the caller aborts.
+ */
+declare function followWorkflowRunEvents(transport: MatrxTransport, runId: string, options: {
+    onEvent: (event: Record<string, unknown>, seq: number | null) => void;
+    lastEventId?: number | null;
+    signal?: AbortSignal;
+}): Promise<{
+    ended: boolean;
+}>;
+type ResumeOrRejoinOutcome = 
+/** The resume door ran the run; its stream was delivered to `onEnvelope`. */
+{
+    kind: "resumed";
+    requestId: string | null;
+}
+/** The run was live; its stream (from `rejoin_path`) was replayed + followed into `onEnvelope`. */
+ | {
+    kind: "rejoined";
+    rejoin: MatrxLiveRunRejoin;
+}
+/**
+ * The run was live but had no journal to replay; the durable lifecycle was
+ * followed instead. Re-query the feature's record for the result.
+ * `ended: false` = the follow gave up (or no operation was found).
+ */
+ | {
+    kind: "followed";
+    rejoin: MatrxLiveRunRejoin;
+    executionId: string | null;
+    ended: boolean;
+    status: MatrxRuntimeExecutionStatus | null;
+}
+/** No journal, and the run is a workflow: its run SSE was followed into `onWorkflowEvent`. */
+ | {
+    kind: "followed_workflow";
+    rejoin: MatrxLiveRunRejoin;
+    runId: string;
+    ended: boolean;
+}
+/** `409 resume_conflict` (named live run or not) — retry with the host's backoff policy. */
+ | {
+    kind: "resume_conflict";
+    error: MatrxApiError;
+};
+interface ResumeOrRejoinOptions extends Omit<MatrxStreamCallOptions, "signal"> {
+    /** Every NDJSON envelope — from the resume stream OR the rejoined stream. */
+    onEnvelope: (envelope: MatrxStreamEnvelope) => void;
+    /** THE RUN'S organization (from its durable record) — bound on every call. */
+    organizationId?: string | null;
+    signal?: AbortSignal;
+    /** Fired the moment a live run is detected, before the rejoin opens (reset replay-sensitive state). */
+    onRejoin?: (rejoin: MatrxLiveRunRejoin) => void;
+    /** Durable lifecycle events while following (the no-journal fallback). */
+    onOperationEvent?: (event: MatrxRuntimeOperationEvent) => void;
+    /** Workflow run SSE events (the no-journal fallback for a workflow `run_id`). */
+    onWorkflowEvent?: (event: Record<string, unknown>, seq: number | null) => void;
+    /** Tuning for the durable follow (stall / reconnect policy). */
+    follow?: Omit<FollowRuntimeOperationToEndOptions, "onEvent" | "signal" | "lastEventSeq">;
+}
+/**
+ * Resume a run — or, when the server says it is still live, REJOIN it.
+ *
+ * Calls `resumeCall` (the feature's resume door) and pipes its stream into
+ * `onEnvelope`. On a live-run refusal (`run_in_progress`) it follows the body's `rejoin_path`
+ * into the SAME handler under the same organization; when the rejoin has no
+ * journal (`live_stream_unavailable`) it follows the workflow run SSE (body
+ * names a workflow `run_id`) or the durable lifecycle. Never runs a live run a
+ * second time. Every `resume_conflict` comes back as an outcome; any other
+ * error is thrown.
+ */
+declare function resumeOrRejoin(transport: MatrxTransport, resumeCall: (transport: MatrxTransport, options: MatrxStreamCallOptions) => Promise<MatrxRunHandle>, options: ResumeOrRejoinOptions): Promise<ResumeOrRejoinOutcome>;
+/** What a `409 live_stream_unavailable` rejoin answer names: a workflow `run_id`, when it has one. */
+interface MatrxLiveStreamUnavailable {
+    runId: string | null;
+}
+/**
+ * Read a rejoin's `409 live_stream_unavailable` (the journal is gone). Null
+ * for every other error. For hosts that open the rejoin stream themselves —
+ * hand the result to `followUnavailableRejoin`.
+ */
+declare function readLiveStreamUnavailable(error: unknown): MatrxLiveStreamUnavailable | null;
+type MatrxFollowedOutcome = Extract<ResumeOrRejoinOutcome, {
+    kind: "followed" | "followed_workflow";
+}>;
+interface FollowUnavailableRejoinOptions {
+    /** THE RUN'S organization; omit when `transport` is already bound to it. */
+    organizationId?: string | null;
+    signal?: AbortSignal;
+    onOperationEvent?: (event: MatrxRuntimeOperationEvent) => void;
+    onWorkflowEvent?: (event: Record<string, unknown>, seq: number | null) => void;
+    follow?: Omit<FollowRuntimeOperationToEndOptions, "onEvent" | "signal" | "lastEventSeq">;
+}
+/**
+ * The no-journal fallback of a rejoin — the SAME branch `resumeOrRejoin`
+ * takes, exported for hosts whose rejoin stream rides their own wire (the
+ * extension's offscreen fetch, the desktop's request loop). A workflow
+ * `run_id` (from the unavailable body, else the refusal) on a runtime rejoin
+ * → follow the workflow run SSE; otherwise read the live operation and
+ * follow it to its end. Settle the result with `settleRunPickup`.
+ */
+declare function followUnavailableRejoin(transport: MatrxTransport, rejoin: MatrxLiveRunRejoin, unavailable: MatrxLiveStreamUnavailable, options?: FollowUnavailableRejoinOptions): Promise<MatrxFollowedOutcome>;
+/**
+ * The parts of a pick-up result `settleRunPickup` reads — every
+ * `ResumeOrRejoinOutcome` is one, and so is a host's own follow result.
+ */
+type MatrxRunPickup = {
+    kind: "resumed" | "rejoined";
+} | {
+    kind: "resume_conflict";
+} | {
+    kind: "followed";
+    executionId: string | null;
+    ended: boolean;
+    status: MatrxRuntimeExecutionStatus | null;
+} | {
+    kind: "followed_workflow";
+    ended: boolean;
+};
+type MatrxRunPickupSettlement = 
+/** The turn arrived on a stream the host already rendered — nothing to reload. */
+{
+    state: "streamed";
+}
+/** Bare `resume_conflict` — retry with the host's backoff. */
+ | {
+    state: "retry";
+}
+/**
+ * The run is over (or no live operation remains): the SAVED turn was
+ * reloaded — that is the answer to show, never an empty bubble and never a
+ * failure the run did not have. `status` null = unknown (workflow / none
+ * found); `reloaded: false` = the reload itself threw (`error`).
+ */
+ | {
+    state: "settled";
+    status: MatrxRuntimeExecutionStatus | null;
+    reloaded: boolean;
+    error?: unknown;
+}
+/** The follow gave up while the run may still be live; `onStillRunning` (default: reload what is saved) ran. */
+ | {
+    state: "still_running";
+    reloaded: boolean;
+    error?: unknown;
+};
+interface SettleRunPickupOptions {
+    /** Re-read the feature's saved record (the conversation's messages) into the screen. */
+    reloadSavedTurn: () => Promise<void> | void;
+    /**
+     * The follow gave up on a run that may still be live. Default: reload what
+     * is saved now. A host with its own patient recovery (the web app's
+     * dropped-stream poll) passes it here instead.
+     */
+    onStillRunning?: () => Promise<void> | void;
+}
+/**
+ * THE one mapping from a pick-up result to what the screen does, shared by
+ * every chat client so a live run that cannot replay ends the same way
+ * everywhere: streamed → done; bare conflict → retry; followed to its end
+ * (or nothing live left to follow) → reload the saved turn and report the
+ * run's real status; follow gave up → still running (never "failed").
+ */
+declare function settleRunPickup(pickup: MatrxRunPickup, options: SettleRunPickupOptions): Promise<MatrxRunPickupSettlement>;
+
+/**
+ * Follow or reconnect to a server job — THE client primitive for "a page
+ * refreshed (or a tab came back) while the server was still working".
+ *
+ * Server truth (aidream `services/runtime/reconnect.py`): every stream opens a
+ * durable run record keyed by its `X-Request-ID`, optionally linked to a
+ * feature record (`("conversation", id)`, `("processed_document", id)`, …), and
+ * its NDJSON response is journaled with `(stream_id, stream_seq)` stamps.
+ *
+ * One call does the whole recovery:
+ *
+ *   1. identify   — `GET /runtime/operations/{request_id}` or
+ *                   `GET /runtime/operations/by-link/{kind}/{id}`
+ *   2. rejoin     — `POST /runtime/operations/{request_id}/rejoin` replays the
+ *                   journal then follows live; frames already delivered on this
+ *                   page are dropped by `(stream_id, stream_seq)`
+ *   3. fallback   — 404/409 `live_stream_unavailable` (or any rejoin failure):
+ *                   follow the durable lifecycle stream to its end
+ *   4. settle     — re-read the run's status and call `reloadSavedResult()`;
+ *                   the feature's own record is the content truth
+ *
+ * The outcome ALWAYS carries a true status read from the server — never an
+ * "unknown": a run that settled says so, a run still live after every follow
+ * attempt says it is still running (`settled: false`), and no recorded run at
+ * all is `"none"`.
+ *
+ * Framework-light: transport port in, callbacks out. React binding:
+ * `useServerJob` in `@ai-matrx/agents/react`. Chat keeps its Redux pipeline and
+ * shares `pickServerJobOperation` / `createStreamReplayCursor` from here.
+ */
+
+/** The transport stamp of one NDJSON frame, when the server sent one. */
+interface MatrxStreamCursorStamp {
+    streamId: string | null;
+    streamSeq: number;
+}
+/**
+ * Read a frame's `(stream_id, stream_seq)` stamp. Null for unstamped frames
+ * (older servers, compact envelopes) — those are always delivered.
+ */
+declare function readStreamCursor(frame: unknown): MatrxStreamCursorStamp | null;
+/**
+ * Remembers the highest delivered `stream_seq` PER `stream_id`, so a replayed
+ * journal never renders a frame twice. A new `stream_id` is a new emitter
+ * segment (e.g. a resumed leg) whose sequence restarts at 1 — its frames are
+ * admitted. The mark is kept per segment, not just for the latest one: a page
+ * that live-followed segment A then B and then rejoins (the journal replays A
+ * then B) must drop BOTH replays. Keep one cursor per job for the life of the
+ * page: the first live stream and every later rejoin share it.
+ */
+interface StreamReplayCursor {
+    /** True when the frame is new and should be delivered; false = already seen. */
+    admit(frame: unknown): boolean;
+    /** The segment of the last ADMITTED stamped frame. */
+    readonly streamId: string | null;
+    /** The high-water mark of that segment. */
+    readonly lastSeq: number;
+    /** High-water marks of every segment seen, by `stream_id`. */
+    readonly marks: Readonly<Record<string, number>>;
+    /** Forget everything (a cold page replays from frame one). */
+    reset(): void;
+}
+interface StreamReplayCursorOptions {
+    /** Fired when an ADMITTED frame opens a new emitter segment (sequence restarts). */
+    onSegmentChange?: (streamId: string) => void;
+    /**
+     * Resume from marks a host persisted (e.g. Redux). `streamId`/`lastSeq` is the
+     * current segment; `marks` adds earlier segments' high-water marks.
+     */
+    seed?: {
+        streamId?: string | null;
+        lastSeq?: number;
+        marks?: Readonly<Record<string, number>>;
+    };
+}
+declare function createStreamReplayCursor(options?: StreamReplayCursorOptions): StreamReplayCursor;
+/**
+ * Where a followed job stands. The server's run statuses, plus:
+ * `connecting` — looking the run up (only ever an intermediate state);
+ * `none` — the server holds no run for this target (nothing to follow; the
+ * saved record is the whole truth).
+ */
+type ServerJobStatus = "connecting" | "none" | MatrxRuntimeExecutionStatus;
+/** A settled status the outcome can carry (never `connecting`). */
+type ServerJobFinalStatus = Exclude<ServerJobStatus, "connecting">;
+declare function isServerJobSettled(status: ServerJobStatus): boolean;
+/**
+ * The one operation to follow from an identify answer: the first live one,
+ * else the newest (the server sorts newest first). Null when there is none.
+ * Works on both by-link shapes: the original (one run per operation) and the
+ * newer one that returns the LINKED execution with its own status plus the
+ * `root_request_id` to rejoin by.
+ */
+declare function pickServerJobOperation<T extends {
+    is_terminal: boolean;
+}>(operations: readonly T[] | null | undefined): T | null;
+/**
+ * The request id to rejoin and re-read by: the root run's id when the server
+ * names one (`root_request_id`, newer by-link shape), else the operation's own.
+ */
+declare function serverJobRejoinHandle(operation: {
+    request_id: string | null;
+    root_request_id?: string | null;
+} | null | undefined): string | null;
+/** What to follow: the run's own `X-Request-ID`, or the feature record it is linked to. */
+type ServerJobTarget = {
+    requestId: string;
+} | {
+    linkKind: string;
+    linkId: string;
+};
+type ServerJobPath = "none" | "already_settled" | "rejoin" | "lifecycle";
+interface ServerJobOutcome {
+    /** The run's true status as last read from the server. */
+    status: ServerJobFinalStatus;
+    /** True when `status` is terminal or `none` — `reloadSavedResult` ran. */
+    settled: boolean;
+    /** The caller aborted; `status` is the last status read. */
+    aborted: boolean;
+    /** How the job was followed. */
+    path: ServerJobPath;
+    requestId: string | null;
+    executionId: string | null;
+    /** The run's error column when it failed. */
+    error: Record<string, unknown> | null;
+    /** NDJSON frames delivered to `onFrame` / dropped as already seen. */
+    framesDelivered: number;
+    framesSkipped: number;
+    /** `reloadSavedResult` completed without throwing. */
+    reloaded: boolean;
+    reloadError?: unknown;
+}
+interface FollowServerJobOptions {
+    target: ServerJobTarget;
+    /** Every NEW NDJSON frame of the rejoined response (replay + live). */
+    onFrame?: (envelope: MatrxStreamEnvelope) => void;
+    /** Every status transition, with the operation view when one is known. */
+    onStatus?: (status: ServerJobStatus, operation: MatrxRuntimeOperationView | null) => void;
+    /** Durable lifecycle events while following without a journal. */
+    onOperationEvent?: (event: MatrxRuntimeOperationEvent) => void;
+    /** The rejoin could not replay; the lifecycle follow takes over (diagnostic). */
+    onRejoinUnavailable?: (error: unknown) => void;
+    /**
+     * Re-read the feature's saved record into the screen. Called once the job
+     * settles (terminal or no run) — the saved record is the content truth.
+     */
+    reloadSavedResult: (outcome: {
+        status: ServerJobFinalStatus;
+        operation: MatrxRuntimeOperationView | null;
+    }) => Promise<void> | void;
+    /** Share one cursor across every reconnect of this job on this page. */
+    cursor?: StreamReplayCursor;
+    /**
+     * Host-owned rejoin: the host opens and renders the rejoin wire itself (chat
+     * feeds it through its Redux stream pipeline, which dedupes on the same
+     * cursor). Replaces the built-in frame loop. Throw when the wire is
+     * unavailable (the lifecycle follow takes over); return `"stand-down"` when
+     * the host has already taken over recovery and this attempt must stop.
+     */
+    rejoinConsumer?: (args: {
+        operation: MatrxRuntimeOperationView;
+        /** The id to rejoin by (`root_request_id` when the server names one). */
+        requestId: string;
+    }) => Promise<void | "stand-down">;
+    /**
+     * After a rejoin ended with the run still live: `"handoff"` returns now
+     * (the host re-enters), `"follow"` (default) follows the lifecycle to its end.
+     */
+    afterRejoin?: (operation: MatrxRuntimeOperationView) => "follow" | "handoff";
+    /** Wraps the identify read (e.g. an offline retry budget). */
+    retry?: <T>(attempt: () => Promise<T>) => Promise<T>;
+    /** THE RUN'S organization, when the transport is not already bound to it. */
+    organizationId?: string | null;
+    signal?: AbortSignal;
+    /** Lifecycle follow tuning (stall watchdog, reconnect budget). */
+    follow?: Omit<FollowRuntimeOperationToEndOptions, "onEvent" | "signal" | "lastEventSeq">;
+    /** Max operations read by link. Default 5. */
+    linkLimit?: number;
+    /**
+     * The host already holds (or shares) the FIRST by-link read for this target —
+     * answer the identify step from it instead of issuing a second identical GET.
+     * Used only for the initial identify of a `linkKind/linkId` target; later
+     * refreshes always read the server fresh.
+     */
+    identifyLink?: (linkKind: string, linkId: string, signal?: AbortSignal) => Promise<readonly MatrxRuntimeOperationView[] | null | undefined>;
+}
+/**
+ * Follow a server job to its end — or reconnect to it after a refresh. See the
+ * module doc for the four steps. Throws only when the FIRST identify read
+ * fails (the server is unreachable — nothing true can be said yet); every
+ * later failure degrades to the next step and ends in a status the server
+ * actually reported.
+ */
+declare function followServerJob(transport: MatrxTransport, options: FollowServerJobOptions): Promise<ServerJobOutcome>;
+
+/**
+ * Browser-held provider sessions report their failures through the server.
+ *
+ * Realtime voice (OpenAI / xAI) and Cartesia TTS run browser → provider
+ * directly on an ephemeral token from the token broker, so a provider refusal
+ * (e.g. the platform's account is out of credit) never touches the server —
+ * the operator would never hear of it, and the person would see raw provider
+ * text. Every client calls `reportProviderSessionFailure` from the session's
+ * error handler and shows the returned `user_message`.
+ *
+ * Server truth: `POST /broker/provider-failures`
+ * (`aidream/api/routers/token_broker.py`; body `ProviderSessionFailureReport`
+ * in `aidream/services/token_broker/models.py` — `extra="forbid"`, allow-listed
+ * providers, bounded text; identity and organization come from the session).
+ */
+
+/** The providers whose sessions a browser holds directly (server allow-list). */
+type MatrxClientSessionProvider = "openai" | "xai" | "cartesia";
+interface ProviderSessionFailure {
+    provider: MatrxClientSessionProvider;
+    model?: string | null;
+    /** HTTP status the provider answered, when the failure was an HTTP answer. */
+    status_code?: number | null;
+    /** The provider's own error type/code (`insufficient_quota`, …). */
+    error_type?: string | null;
+    /** The provider's text, verbatim — classified server-side, never shown. */
+    message: string;
+}
+/** `ProviderSessionFailureVerdict` — what to show, and whether reconnecting can help. */
+interface ProviderSessionFailureVerdict {
+    error_type: string;
+    retryable: boolean;
+    /** The sentence to show the person (never the provider's raw text). */
+    user_message: string;
+}
+/** The body the server accepts — bounded exactly as its model bounds it. */
+declare function providerSessionFailureBody(failure: ProviderSessionFailure): Record<string, string | number>;
+/**
+ * Report a browser-held provider session failure and get the sentence to
+ * show. Resolves null (and warns) when the report itself could not be made —
+ * the caller then shows its own fallback; it never throws from an error
+ * handler.
+ */
+declare function reportProviderSessionFailure(transport: MatrxTransport, failure: ProviderSessionFailure, options?: {
+    signal?: AbortSignal;
+}): Promise<ProviderSessionFailureVerdict | null>;
+
+export { type ApiTargetLogContext, BackendApiError, type BackendApiErrorData, type BackendErrorCode, type BackendFailureExplanation, type CreateMatrxTransportOptions, type CreateWarmupOptions, CredentialsPort, type EndpointOverrideConfig, type ExecuteMatrxCallHooks, type ExecuteMatrxCallRequest, type FollowRuntimeOperationOptions, type FollowRuntimeOperationToEndOptions, type FollowRuntimeOperationToEndResult, type FollowServerJobOptions, type FollowUnavailableRejoinOptions, type JsonRequestOptions, MATRX_AI_API_VERSION_DEFAULT, MATRX_LIVE_STREAM_UNAVAILABLE, MATRX_RESUME_CONFLICT, MATRX_RUN_IN_PROGRESS, MATRX_UI_ONLY_BODY_FIELDS, type MatrxAiApiVersion, MatrxApiError, type MatrxCallError, type MatrxCallResult, type MatrxCallScope, type MatrxChatMessage, type MatrxClientSessionProvider, type MatrxConversationStart, type MatrxEphemeralConversation, type MatrxFollowedOutcome, type MatrxHttpErrorLike, type MatrxHttpMethod, type MatrxJsonObject, type MatrxJsonValue, type MatrxLiveRunRejoin, type MatrxLiveStreamUnavailable, type MatrxOperationEventsPage, type MatrxOperationFollowEvent, type MatrxOperationStatusResponse, type MatrxOperationsByLinkResponse, type MatrxProtocolDowngrade, type MatrxProtocolFallbackOptions, type MatrxQueryParams, type MatrxRequestInfo, type MatrxRunHandle, type MatrxRunPickup, type MatrxRunPickupSettlement, type MatrxRuntimeExecutionStatus, type MatrxRuntimeOperationEvent, type MatrxRuntimeOperationView, type MatrxStoredConversationContinue, type MatrxStoredConversationCreate, type MatrxStreamCallOptions, type MatrxStreamCursorStamp, type MatrxStreamIds, type MatrxStreamParse, type MatrxTransport, type MatrxTransportDiagnostics, type MatrxTransportRequest, type MatrxTransportTarget, OrganizationContextError, type OrganizationContextErrorCode, type OrganizationOperation, type ParseMatrxNdjsonResponseHooks, type ProviderSessionFailure, type ProviderSessionFailureVerdict, type QueryValue, RUN_OUTPUT_KINDS, RUN_STREAM_LIFETIME_BACKSTOP_MS, RUN_WAIT_KNOB_FEATURE, ResilientFetchOptions, type ResumeOrRejoinOptions, type ResumeOrRejoinOutcome, type RunOutputKind, type RunWait, type RunWaitKnobReader, type SendMatrxRequestOptions, type ServerJobFinalStatus, type ServerJobOutcome, type ServerJobPath, type ServerJobStatus, type ServerJobTarget, type SettleRunPickupOptions, type StreamReplayCursor, type StreamReplayCursorOptions, type StreamRequestOptions, StreamTransportError, TERMINAL_MATRX_RUNTIME_STATUSES, type UpstreamErrorPayload, V2_COVERED_AI_PATH_TEMPLATES, WARM_PATH, type WarmItem, type WarmReason, type Warmup, aiVersionPathOverrides, applyAiApiVersion, applyDesktopTargetToRequestBody, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, bareStatusSentence, buildMatrxRequestBody, buildMatrxRequestUrl, buildQuery, buildSafeRequestLog, continueEphemeralConversationStart, continueStoredConversationStart, createMatrxTransport, createOrganizationOperation, createStreamReplayCursor, createWarmup, describeBackendFailure, encodePathSegment, executeMatrxCall, extractMatrxErrorCode, extractMatrxErrorMessage, fetchWithMatrxProtocolFallback, followRuntimeOperationEvents, followRuntimeOperationToEnd, followServerJob, followUnavailableRejoin, followWorkflowRunEvents, getRuntimeOperationStatus, getRuntimeOperationsByLink, getUserMessage, honestTransportMessage, isBareTransportCode, isCoveredAiPath, isGenericUserMessage, isJobOutputKind, isLiveStreamUnavailable, isResumeConflict, isServerJobSettled, isStreamTransportLost, isV2Path, listRuntimeOperationEvents, logApiTarget, mintMatrxConversationId, newEphemeralConversationStart, newStoredConversationStart, normalizeMatrxError, openMatrxStream, parseCallApiError, parseHttpError, parseHttpErrorBody, parseMatrxNdjsonResponse, parsePersistedBackendError, parseStreamError, pickServerJobOperation, preconnectServer, providerSessionFailureBody, readConversationOrganizationId, readLiveRunRejoin, readLiveRunRequestId, readLiveStreamUnavailable, readMatrxErrorCode, readMatrxErrorCodeFromMessage, readMatrxJsonResponse, readStreamCursor, redactUrlForRequestLog, rejoinRuntimeOperation, reportProviderSessionFailure, requestJson, requestStream, requireOrganizationContext, resetPreconnectedForTests, resolveEndpointPath, resolveRunWaitWith, resumeOrRejoin, runJobLabel, runOutputKindFromModalities, runWaitKnobKey, runWaitTimeoutMessage, runtimeOperationRejoinPath, sendMatrxRequest, serverJobRejoinHandle, settleRunPickup, shouldReportMatrxCallError, streamErrorText, toRunHandle, toV1FallbackUrl, toV2Path, unwrapUpstreamError, withRunOrganization };