@ai-matrx/api 0.1.7 → 0.1.9

package/dist/index.d.ts

@@ -1,12 +1,13 @@
-import { M as MatrxStreamEnvelope, b as MatrxNdjsonIssue, c as MatrxStreamEnvelopeObservation, d as MatrxSseFrame } from './index-Xx6L_pWk.js';
-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-Xx6L_pWk.js';
+import { M as MatrxStreamEnvelope, b as MatrxNdjsonIssue, c as MatrxStreamEnvelopeObservation, d as MatrxSseFrame } from './index-C3ZlP3BI.js';
+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-C3ZlP3BI.js';
 import { CredentialsPort } from '@ai-matrx/auth/credentials';
 export { API_KEY_PREFIX, CredentialsPort, CredentialsSetting, MATRX_HEADERS, MatrxCredential, MatrxCredentialKind, credentialToHeaders, toCredentialsPort } from '@ai-matrx/auth/credentials';
 import { ResilientFetchOptions } from './net.js';
 export { AbortedError, ConnectTimeoutError, HeartbeatTimeoutError, HttpError, NetError, NetErrorCode, NetworkError, OfflineError, ResilientFetchResult, RetryOptions, StreamMonitorOptions, TotalTimeoutError, extractErrorMessage, isNetError, isTransportFailure, monitorStream, resilientFetch, toNetError, withRetry } from './net.js';
+import { g as MandateKey, b as DynamicMandateKey } from './keys.generated-CK_C5UXG.js';
 
 /**
- * `@ai-matrx/agents/matrx` — the Matrx transport port.
+ * `@ai-matrx/api` — 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,
@@ -99,7 +100,7 @@ declare function extractMatrxErrorMessage(serverDetail: unknown): string | undef
 declare function extractMatrxErrorCode(serverDetail: unknown): string | null;
 
 /**
- * `@ai-matrx/agents/matrx` — the AI Matrx server's error model, as every
+ * `@ai-matrx/api` — 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
@@ -428,7 +429,7 @@ declare function aiVersionPathOverrides(version: MatrxAiApiVersion): Record<stri
  * - **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`;
+ *   guard), via `@ai-matrx/api/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
@@ -583,7 +584,7 @@ interface CreateMatrxTransportOptions {
 declare function createMatrxTransport(options: CreateMatrxTransportOptions): MatrxTransport;
 
 /**
- * `@ai-matrx/agents/matrx` — THE request pipeline every typed Matrx server call
+ * `@ai-matrx/api` — 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,
@@ -814,7 +815,7 @@ declare function applyOrganizationContextHeader(headers: Record<string, string>,
  */
 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). */
+/** `@ai-matrx/api` — moved from matrx-frontend `lib/api/log-api-target.ts` (chat-package independence P9). */
 /**
  * lib/api/log-api-target.ts
  *
@@ -859,7 +860,7 @@ interface ApiTargetLogContext {
 declare function logApiTarget(url: string, context: ApiTargetLogContext): void;
 
 /**
- * `@ai-matrx/agents/matrx` — the single primitive that transforms a server
+ * `@ai-matrx/api` — 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).
@@ -905,7 +906,7 @@ declare function resolveEndpointPath(canonicalPath: string, config?: EndpointOve
 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
+ * `@ai-matrx/api` — moved from matrx-frontend `lib/api/run-wait.ts` (chat-package
  * independence P9). The knob read is injected (`resolveRunWaitWith`); the host wraps it.
  */
 /**
@@ -990,7 +991,7 @@ declare function runJobLabel(kind: RunOutputKind, modelLabel: string | null): st
 declare function runWaitTimeoutMessage(kind: RunOutputKind, modelLabel: string | null, seconds: number | null): string;
 
 /**
- * `@ai-matrx/agents/matrx` — the client warm-up primitive.
+ * `@ai-matrx/api` — the client warm-up primitive.
  *
  * Contract: common-docs `systems/architecture/warm-cache/CONTRACT.md`.
  *
@@ -1062,7 +1063,7 @@ declare function preconnectServer(baseUrl: string | null | undefined): void;
 declare function resetPreconnectedForTests(): void;
 
 /**
- * Internal request plumbing for `@ai-matrx/agents/matrx`. Not part of the
+ * Internal request plumbing for `@ai-matrx/api`. 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.
  */
@@ -2066,4 +2067,783 @@ interface ProviderUsageReporter {
 }
 declare function createProviderUsageReporter(options: ProviderUsageReporterOptions): ProviderUsageReporter;
 
-export { type ApiTargetLogContext, BackendApiError, type BackendApiErrorData, type BackendErrorCode, type BackendFailureExplanation, type CreateMatrxTransportOptions, type CreateWarmupOptions, 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 ProviderSessionUsage, type ProviderSessionUsageReceipt, type ProviderUsageReporter, type ProviderUsageReporterOptions, type ProviderUsageSendResult, 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, createProviderUsageReporter, createStreamReplayCursor, createWarmup, describeBackendFailure, encodePathSegment, executeMatrxCall, extractMatrxErrorCode, extractMatrxErrorMessage, fetchWithMatrxProtocolFallback, followRuntimeOperationEvents, followRuntimeOperationToEnd, followServerJob, followUnavailableRejoin, followWorkflowRunEvents, getRuntimeOperationStatus, getRuntimeOperationsByLink, getUserMessage, honestTransportMessage, isBareTransportCode, isCoveredAiPath, isEmptyProviderUsage, isGenericUserMessage, isJobOutputKind, isLiveStreamUnavailable, isResumeConflict, isServerJobSettled, isStreamTransportLost, isV2Path, listRuntimeOperationEvents, logApiTarget, mintMatrxConversationId, newEphemeralConversationStart, newStoredConversationStart, normalizeMatrxError, openMatrxStream, parseCallApiError, parseHttpError, parseHttpErrorBody, parseMatrxNdjsonResponse, parsePersistedBackendError, parseStreamError, pickServerJobOperation, preconnectServer, providerSessionFailureBody, providerSessionUsageBody, readConversationOrganizationId, readLiveRunRejoin, readLiveRunRequestId, readLiveStreamUnavailable, readMatrxErrorCode, readMatrxErrorCodeFromMessage, readMatrxJsonResponse, readStreamCursor, redactUrlForRequestLog, rejoinRuntimeOperation, reportProviderSessionFailure, reportProviderSessionUsage, requestJson, requestStream, requireOrganizationContext, resetPreconnectedForTests, resolveEndpointPath, resolveRunWaitWith, resumeOrRejoin, runJobLabel, runOutputKindFromModalities, runWaitKnobKey, runWaitTimeoutMessage, runtimeOperationRejoinPath, sendMatrxRequest, serverJobRejoinHandle, settleRunPickup, shouldReportMatrxCallError, streamErrorText, toRunHandle, toV1FallbackUrl, toV2Path, unwrapUpstreamError, withRunOrganization };
+/**
+ * Agent run lifecycle against the AI Matrx API — start, continue, resume,
+ * cancel — over the `MatrxTransport` port, with every streaming response
+ * parsed through the package's ONE NDJSON wire kernel (`stream/ndjson`).
+ *
+ * Server truth (verified against aidream source):
+ * - `POST /ai/agents/{agent_id}`                — start   (`aidream/api/routers/agents.py`)
+ * - `POST /ai/conversations/{conversation_id}`  — continue (`aidream/api/routers/conversations.py`)
+ * - `POST /ai/conversations/{conversation_id}/resume` — resume after
+ *   client-delegated tool suspension (same router)
+ * - `POST /ai/cancel/{request_id}?mode=interrupt` — cancel (`aidream/api/routers/cancel.py`)
+ *
+ * Response headers arrive before the body: `X-Conversation-ID` and
+ * `X-Request-ID` are surfaced on the run handle immediately. `X-Request-ID`
+ * is the ONLY id the server accepts for cancel — a client-local id means
+ * nothing to it.
+ *
+ * Host policy stays out: no retry, no store, no timeouts, no persistence
+ * (C10: no-persistence). Cancellation is the caller's `AbortSignal`; a client
+ * disconnect never stops server work (`detach_on_disconnect`).
+ */
+
+/**
+ * Stable identity of the durable entity whose saved context owns a run —
+ * the server reloads the row and uses ITS scope (`ContextAnchor`,
+ * `aidream/services/conversation_context/scope.py`).
+ */
+interface MatrxContextAnchor {
+    resource_type: string;
+    resource_id: string;
+}
+/**
+ * Scope and source fields shared by every scoped request
+ * (`ScopedRequest` / `AcceptsInjectedScope` server-side). All optional here;
+ * the start request narrows `organization_id` to required.
+ */
+interface MatrxRequestScope {
+    organization_id?: string;
+    project_id?: string | null;
+    task_id?: string | null;
+    /** Active context-scope ids from the client's global picker (membership-validated server-side). */
+    scope_ids?: string[] | null;
+    /** Active scope-TYPE ids — a type-level selection with no specific scope chosen. */
+    active_scope_type_ids?: string[] | null;
+    context_anchor?: MatrxContextAnchor | null;
+    /** Stable application slug that initiated the request. */
+    source_app?: string | null;
+    /** Stable feature slug within the source application. */
+    source_feature?: string | null;
+    /** "user" = a person directly triggered this; "auto" = client automation; omit for API callers. */
+    initiation?: "user" | "auto" | null;
+    /** Specific connected desktop instance allowed to claim delegated local tools. */
+    target_instance_id?: string | null;
+}
+/**
+ * Fields shared by start/continue turn requests (tool injection, client
+ * capability envelope, context object). The complex bags (`tools`, `client`,
+ * `user`, `config_overrides`) are typed as JSON objects — their authoritative
+ * schemas are the server's Pydantic models and the generated API types;
+ * this package stays payload-agnostic about them by design.
+ */
+interface MatrxTurnFields {
+    /** What the human typed (string), or structured input parts. Never smuggle machine content here. */
+    user_input?: string | MatrxJsonValue[] | null;
+    /** Per-run model/config overrides (LLMParams shape). */
+    config_overrides?: MatrxJsonObject | null;
+    debug?: boolean;
+    /** Additive tool specs merged into the agent's resolved tool set. */
+    tools?: MatrxJsonObject[];
+    /** When set, becomes the agent's ENTIRE tool set for the turn. */
+    tools_replace?: MatrxJsonObject[] | null;
+    /** Client capability envelope (`ClientContext`). */
+    client?: MatrxJsonObject | null;
+    /** Per-request user-level tool inclusion/exclusion overrides. */
+    user?: MatrxJsonObject | null;
+    /** Per-route context object, free-form by design. */
+    context?: MatrxJsonObject;
+    writable_variables?: string[];
+    allow_context_create?: boolean;
+    /** Request-snapshot capture override (tri-state; omit for the platform default). */
+    snapshot?: boolean | null;
+}
+/**
+ * `POST /ai/agents/{agent_id}` body (`AgentStartRequest` server-side).
+ * The conversation-start triple is required by construction; `organization_id`
+ * is required (the server 422s a blank one — it never manufactures an org).
+ * `stream` is not accepted here: this client is the streaming path and always
+ * sends `stream: true`.
+ */
+type MatrxAgentStartRequest = MatrxConversationStart & Omit<MatrxRequestScope, "organization_id"> & MatrxTurnFields & {
+    organization_id: string;
+    /** Variable name → value map filling the agent's declared variables. */
+    variables?: MatrxJsonObject | null;
+    /** Run the versions table row instead of the live agent row. */
+    is_version?: boolean;
+    max_iterations?: number;
+    max_retries_per_iteration?: number;
+};
+/**
+ * `POST /ai/mandates/{mandate_key}` uses the exact saved-agent start body.
+ * The server resolves the mandate's holder, binding, and configuration; a
+ * client must offer only the declared variables and human input here.
+ */
+type MatrxMandateStartRequest = MatrxAgentStartRequest;
+/** `POST /ai/conversations/{id}` body (`ConversationContinueRequest` server-side). */
+type MatrxConversationContinueRequest = MatrxRequestScope & MatrxTurnFields & {
+    /** Re-run the conversation's current persisted state (recovery after a failed turn); omit `user_input`. */
+    retry?: boolean;
+};
+/**
+ * `POST /ai/conversations/{id}/resume` body (`ResumeRequest` server-side) —
+ * the shipped durable continuation after client-delegated tool calls were
+ * answered via `POST /tool_results` while the original stream was gone.
+ * `user_request_id` is optional: when omitted the server resolves the turn
+ * from the conversation's newest answered client-delegated tool call.
+ * Re-send fresh `context` here — a resumed loop is otherwise context-blind.
+ */
+type MatrxConversationResumeRequest = MatrxRequestScope & {
+    user_request_id?: string | null;
+    config_overrides?: MatrxJsonObject | null;
+    debug?: boolean;
+    tools?: MatrxJsonObject[];
+    tools_replace?: MatrxJsonObject[] | null;
+    client?: MatrxJsonObject | null;
+    user?: MatrxJsonObject | null;
+    context?: MatrxJsonObject;
+    writable_variables?: string[];
+    allow_context_create?: boolean;
+};
+/** `POST /ai/cancel/{request_id}` response (`CancelResponse` server-side). */
+interface MatrxCancelResponse {
+    status: string;
+    request_id: string;
+    spine_executions_signalled: string[];
+}
+/** Start an agent run: `POST /ai/agents/{agent_id}` (NDJSON stream). */
+declare function startAgentRun(transport: MatrxTransport, agentId: string, request: MatrxAgentStartRequest, options?: MatrxStreamCallOptions): Promise<MatrxRunHandle>;
+/**
+ * Start a declared mandate: `POST /ai/mandates/{mandate_key}` (NDJSON
+ * stream). This is deliberately separate from `startAgentRun`: callers name
+ * the mandate and never resolve or echo its holder/configuration themselves.
+ */
+declare function startMandateRun(transport: MatrxTransport, mandateKey: string, request: MatrxMandateStartRequest, options?: MatrxStreamCallOptions): Promise<MatrxRunHandle>;
+/** Continue a stored conversation: `POST /ai/conversations/{id}` (NDJSON stream). */
+declare function continueAgentConversation(transport: MatrxTransport, conversationId: string, request: MatrxConversationContinueRequest, options?: MatrxStreamCallOptions): Promise<MatrxRunHandle>;
+/**
+ * Resume a suspended loop after delegated tool answers landed:
+ * `POST /ai/conversations/{id}/resume` (NDJSON stream). A 409
+ * (`resume_conflict`) means another resume holds the run claim — retrying is
+ * host policy.
+ */
+declare function resumeAgentConversation(transport: MatrxTransport, conversationId: string, request?: MatrxConversationResumeRequest, options?: MatrxStreamCallOptions): Promise<MatrxRunHandle>;
+/**
+ * Stop a running request at its next iteration boundary:
+ * `POST /ai/cancel/{request_id}`. Cooperative and best-effort — the in-flight
+ * provider call finishes by design, and everything already streamed persists.
+ * `mode: "interrupt"` = stop-and-fork: the tail after the last clean boundary
+ * persists hidden so the user's follow-up replies to what they actually saw.
+ * The id must be the server's `X-Request-ID`.
+ */
+declare function cancelAgentRun(transport: MatrxTransport, requestId: string, options?: {
+    mode?: "cancel" | "interrupt";
+    signal?: AbortSignal;
+}): Promise<MatrxCancelResponse>;
+/**
+ * A run that terminated unsuccessfully: the server emitted a fatal `error`
+ * event, or the `user_request` completion settled `failed`/`cancelled`.
+ */
+declare class MatrxRunError extends Error {
+    readonly name = "MatrxRunError";
+    /** The verbatim `error` event payload, when one fired. */
+    readonly errorPayload: Record<string, unknown> | null;
+    /** The `user_request` completion status (`"failed"` | `"cancelled"`), when that was the trigger. */
+    readonly completionStatus: string | null;
+    /** Text streamed before the failure — partial content never vanishes. */
+    readonly partialText: string;
+    constructor(args: {
+        message: string;
+        errorPayload?: Record<string, unknown> | null;
+        completionStatus?: string | null;
+        partialText?: string;
+    });
+}
+interface MatrxCompletedRun {
+    /** Accumulated `chunk` text (falls back to the completion's `result.output`). */
+    text: string;
+    requestId: string | null;
+    conversationId: string | null;
+    /** The `user_request` completion payload, verbatim, when one arrived. */
+    completion: Record<string, unknown> | null;
+}
+interface RunAgentToCompletionOptions extends MatrxStreamCallOptions {
+    /** Live progress: the full accumulated text after each chunk. */
+    onChunk?: (fullText: string) => void;
+    /** Every normalized envelope, before this helper interprets it. */
+    onEvent?: (envelope: MatrxStreamEnvelope) => void;
+}
+/**
+ * Run an agent end-to-end and resolve with its full text output — the
+ * package-level equivalent of the simplest existing host path
+ * (`useRunAgent`): accumulate `chunk` text, treat a fatal `error` event or a
+ * `failed`/`cancelled` `user_request` completion as a thrown `MatrxRunError`,
+ * and fall back to the completion's `result.output` when no text streamed.
+ *
+ * The caller still owns the conversation-start triple on `request` — a
+ * one-shot run typically uses `newEphemeralConversationStart()`.
+ */
+declare function runAgentToCompletion(transport: MatrxTransport, agentId: string, request: MatrxAgentStartRequest, options?: RunAgentToCompletionOptions): Promise<MatrxCompletedRun>;
+
+/**
+ * Delegated client tools — submit results and discover pending calls.
+ *
+ * Server truth (verified against aidream source,
+ * `aidream/api/routers/conversations.py` + `aidream/services/ai_execution/
+ * tool_results.py`):
+ * - `POST /ai/conversations/{id}/tool_results` — durable, idempotent submit.
+ *   A delegated tool call HARD-SUSPENDS the loop; when the last outstanding
+ *   delegated row for the user_request resolves, the response carries
+ *   `continuation_needed: true` and the owning `user_request_id` — the signal
+ *   to open `resumeAgentConversation`. `continuation_needed` is best-effort:
+ *   parallel submits can both see `true`; `/resume` takes an atomic run claim
+ *   and the loser gets a 409.
+ * - `GET /ai/conversations/{id}/pending_calls` — delegated calls awaiting the
+ *   user in one conversation (rows survive disconnects and reloads).
+ * - `GET /ai/user/pending_calls` — every pending call for this user; an
+ *   optional `instance_id` atomically claims them for a desktop instance.
+ *
+ * A 404 from the submit means EVERY call_id was unknown (duplicate/expired);
+ * partial success returns 200 with `not_found` populated. Batching, retries,
+ * and the resume handoff are host policy — this module is the wire.
+ */
+
+/** One client tool answer (`ClientToolResult` server-side). */
+interface MatrxClientToolResult {
+    call_id: string;
+    tool_name: string;
+    /** Tool output — inherently polymorphic; recursive JSON by design. */
+    output?: MatrxJsonValue | null;
+    is_error?: boolean;
+    error_message?: string | null;
+    /** Client-measured execution time in ms. */
+    duration_ms?: number | null;
+}
+/** `POST /tool_results` response (`ToolResultsResponse` server-side). */
+interface MatrxToolResultsResponse {
+    resolved: string[];
+    already_resolved: string[];
+    not_found: string[];
+    /** True when the original stream is gone and no delegated calls remain — open `/resume`. */
+    continuation_needed: boolean;
+    user_request_id: string | null;
+    conversation_id: string;
+}
+/** One delegated call awaiting an answer (`PendingCallSummary` server-side). */
+interface MatrxPendingCallSummary {
+    id: string;
+    call_id: string;
+    conversation_id: string;
+    user_request_id: string | null;
+    message_id: string | null;
+    tool_name: string;
+    /** Tool-call argument bag — schema is per-tool (its input_schema). */
+    arguments: MatrxJsonObject;
+    iteration: number;
+    created_at: string | null;
+    expires_at: string | null;
+    target_instance_id: string | null;
+    claimed_by_instance_id: string | null;
+    claim_expires_at: string | null;
+    execution_authorization: MatrxJsonObject | null;
+}
+/**
+ * Submit client tool results: `POST /ai/conversations/{id}/tool_results`.
+ * Idempotent — duplicate submits return 200 with the ids in
+ * `already_resolved`. Throws `MatrxApiError` (status 404) when every call_id
+ * was unknown or expired; the stream stays alive in that case.
+ */
+declare function submitAgentToolResults(transport: MatrxTransport, conversationId: string, results: MatrxClientToolResult[], options?: {
+    instanceId?: string;
+    signal?: AbortSignal;
+}): Promise<MatrxToolResultsResponse>;
+/**
+ * Discover delegated calls awaiting the user in one conversation:
+ * `GET /ai/conversations/{id}/pending_calls`. Safe to call on every
+ * conversation load; a non-empty list should be surfaced exactly as if the
+ * original stream had delivered the `tool_delegated` events live.
+ */
+declare function listConversationPendingToolCalls(transport: MatrxTransport, conversationId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<MatrxPendingCallSummary[]>;
+/**
+ * Discover every delegated call awaiting this user across all conversations:
+ * `GET /ai/user/pending_calls`. Passing `instanceId` atomically CLAIMS the
+ * calls for that desktop instance — only pass it from a client that will
+ * actually execute them.
+ */
+declare function listUserPendingToolCalls(transport: MatrxTransport, options?: {
+    instanceId?: string;
+    signal?: AbortSignal;
+}): Promise<MatrxPendingCallSummary[]>;
+
+/**
+ * `@ai-matrx/api` — every AI Matrx server endpoint path, by feature
+ * area (matching the server's router structure). Paths only, rooted at the
+ * host (`/ai/...`, `/health`); the HOST owns the base URL.
+ *
+ * Moved from matrx-frontend `lib/api/endpoints.ts` (chat-package independence
+ * P9); the app re-exports it. The production origin and the per-environment
+ * base URLs stay in the host (they are environment values).
+ */
+
+/**
+ * All backend API endpoint paths.
+ *
+ * Organized by feature area matching the backend router structure.
+ * Use these constants everywhere instead of hardcoded strings.
+ *
+ * Auth tiers:
+ * - Public: No auth required
+ * - Guest OK: Fingerprint or JWT token
+ * - Authenticated: Valid JWT token required
+ * - Admin: Valid JWT token + admin role
+ */
+declare const ENDPOINTS: {
+    /** AI endpoints — chat, agents, conversations */
+    readonly ai: {
+        /**
+         * POST — Manual-mode execution (Builder + ephemeral conversations).
+         * POST /ai/manual
+         *
+         * Accepts full message history in `messages` on every call. Used by:
+         *   • Builder — reads the LIVE agent definition (incl. unsaved edits) and
+         *     sends it as the system instruction + priming messages.
+         *   • Ephemeral conversations (turn 2+) — no DB row exists, so the client
+         *     is the source of truth for history; sends it with each turn.
+         *
+         * `conversation_id` is optional in the body (for labeling/storage only);
+         * pair with `is_new:false, store:false` for fully stateless runs.
+         *
+         * NOTE: this replaces the legacy `/ai/chat` endpoint. The canonical
+         * client-side vocabulary is `manual` (see ConversationInvocation.routing
+         * .apiEndpointMode). The legacy `chat` alias below stays for one
+         * migration cycle.
+         */
+        readonly manual: "/ai/manual";
+        /** @deprecated Use `ENDPOINTS.ai.manual`. Kept for one migration cycle. */
+        readonly chat: "/ai/manual";
+        /**
+         * POST — Start a new agent conversation (Guest OK)
+         * POST /ai/agents/{agentId}
+         * Never send conversation_id — the server generates it and returns it in the stream.
+         */
+        readonly agentStart: (agentId: string) => `/ai/agents/${string}`;
+        /**
+         * POST — THE MANDATE DOOR. Start a new conversation by MANDATE KEY, not by
+         * agent id (Guest OK).
+         * POST /ai/mandates/{mandateKey}
+         *
+         * Body is the SAME `AgentStartRequest` as `agentStart`. The server resolves
+         * the principal (bearer/fingerprint) → system default → org binding → user
+         * binding, applies the binding's `config_overrides`, provision consumption
+         * and variable mapping, and then runs the IDENTICAL downstream pipeline
+         * (`_run_mandated_agent` → `_run_agent`). A rebind therefore changes which
+         * agent answers with NO client deploy — which is the entire point.
+         *
+         * Never send mandate-derived `config_overrides` on this path: the server
+         * treats request config as the EXPLICIT layer that WINS over the binding,
+         * so echoing a client-resolved binding back would re-fork resolution.
+         *
+         * 404 `{code: "mandate_unfulfilled"}` when the mandate cannot be resolved —
+         * surfaced verbatim, never swallowed into a client-side re-resolve.
+         */
+        readonly mandateStart: (mandateKey: MandateKey | DynamicMandateKey) => "/ai/mandates/agent_apps.prompt_app_dev" | "/ai/mandates/agent_factory.build" | "/ai/mandates/agent_factory.contract" | "/ai/mandates/agent_factory.instructions" | "/ai/mandates/agent_factory.proof_review" | "/ai/mandates/agent_factory.structure_builder" | "/ai/mandates/agent_factory.system_plan" | "/ai/mandates/agent_factory.tool_choice" | "/ai/mandates/agent_studio.chat_brief" | "/ai/mandates/ai.translation_cell_draft" | "/ai/mandates/alchemy.prepare_content" | "/ai/mandates/ambient.page_guidance" | "/ai/mandates/ambient.spoken_summary" | "/ai/mandates/applets.build" | "/ai/mandates/applets.fix" | "/ai/mandates/audio.live_music" | "/ai/mandates/audio.speech" | "/ai/mandates/brand.voice_rewrite" | "/ai/mandates/chat.cx_default" | "/ai/mandates/chat.default_new_chat" | "/ai/mandates/chat.quick_audio_plan" | "/ai/mandates/chat.quick_fair_news" | "/ai/mandates/chat.quick_flashcards" | "/ai/mandates/chat.quick_image" | "/ai/mandates/chat.quick_org_chart" | "/ai/mandates/chat.quick_research" | "/ai/mandates/chat.quick_showcase" | "/ai/mandates/chat.quick_writing_partner" | "/ai/mandates/chat.response_mode_brainstorm" | "/ai/mandates/chat.response_mode_data" | "/ai/mandates/chat.response_mode_research" | "/ai/mandates/chat.response_mode_video" | "/ai/mandates/checks.cleanup_bakeoff.answer" | "/ai/mandates/checks.cleanup_bakeoff.judge" | "/ai/mandates/checks.finding_disposition" | "/ai/mandates/checks.finding_disposition_review" | "/ai/mandates/cms.content_writing" | "/ai/mandates/cms.publish_review" | "/ai/mandates/cms.seo_metadata" | "/ai/mandates/cms.site_editing" | "/ai/mandates/cms.theme_design" | "/ai/mandates/code_editor.code_edit" | "/ai/mandates/code_editor.dynamic_context_edit" | "/ai/mandates/code_editor.prompt_app_ui_edit" | "/ai/mandates/coding_session.conversation_responder" | "/ai/mandates/coding_session.managed_translation_reference" | "/ai/mandates/commerce_intake.assess_value" | "/ai/mandates/commerce_intake.extract_vision" | "/ai/mandates/commerce_intake.grading" | "/ai/mandates/commerce_intake.instant_analysis" | "/ai/mandates/commerce_intake.refute_no_value" | "/ai/mandates/commerce_intake.research_product" | "/ai/mandates/commerce_intake.segment_photos" | "/ai/mandates/commerce_intake.verify_enrichment" | "/ai/mandates/content_gate.section_relevance_decision" | "/ai/mandates/content_ir.component_artisan" | "/ai/mandates/content_ir.kind_architect" | "/ai/mandates/content_ir.kind_component_builder" | "/ai/mandates/content_ir.kind_creator" | "/ai/mandates/content_plan.branch_purpose" | "/ai/mandates/content_plan.brief_writer" | "/ai/mandates/content_plan.deepen_page" | "/ai/mandates/content_plan.entity_attacher" | "/ai/mandates/content_plan.entity_curator" | "/ai/mandates/content_plan.family_namer" | "/ai/mandates/content_plan.keyword_strategist" | "/ai/mandates/content_plan.merge_wave" | "/ai/mandates/content_plan.p3_family" | "/ai/mandates/content_plan.p4_write" | "/ai/mandates/content_plan.p5_review" | "/ai/mandates/content_plan.p6_build" | "/ai/mandates/content_plan.p6_build.about" | "/ai/mandates/content_plan.p6_build.blog" | "/ai/mandates/content_plan.p6_build.comparison" | "/ai/mandates/content_plan.p6_build.contact" | "/ai/mandates/content_plan.p6_build.faq" | "/ai/mandates/content_plan.p6_build.guide" | "/ai/mandates/content_plan.p6_build.home" | "/ai/mandates/content_plan.p6_build.index" | "/ai/mandates/content_plan.p6_build.location" | "/ai/mandates/content_plan.p6_build.pillar" | "/ai/mandates/content_plan.p6_build.pricing" | "/ai/mandates/content_plan.p6_build.service" | "/ai/mandates/content_plan.plan_reviewer" | "/ai/mandates/content_plan.research_wave.audience_journey" | "/ai/mandates/content_plan.research_wave.competitor_coverage" | "/ai/mandates/content_plan.research_wave.keyword_value" | "/ai/mandates/content_plan.route_picker" | "/ai/mandates/content_plan.shape_planner" | "/ai/mandates/conversation.action_auditor" | "/ai/mandates/conversation.decision_ledger" | "/ai/mandates/conversation.drift_auditor" | "/ai/mandates/conversation.label_agent_run" | "/ai/mandates/conversation.label_chat" | "/ai/mandates/conversation.outcome_summarizer" | "/ai/mandates/conversation.vision_extractor" | "/ai/mandates/conversation.vision_interviewer" | "/ai/mandates/crm.journalist_beat_analyst" | "/ai/mandates/crm.media_list_ranker" | "/ai/mandates/crm.outreach_draft_reviewer" | "/ai/mandates/crm.outreach_fact_check" | "/ai/mandates/crm.outreach_personalization_coach" | "/ai/mandates/crm.outreach_personalization_writer" | "/ai/mandates/crm.outreach_pitch_writer" | "/ai/mandates/crm.outreach_recipient_shortlister" | "/ai/mandates/crm.outreach_reply_drafter" | "/ai/mandates/crm.outreach_strategy" | "/ai/mandates/crm.party_kind_judge" | "/ai/mandates/crm.save_contact" | "/ai/mandates/data.formula_writing" | "/ai/mandates/data.page_guidance" | "/ai/mandates/data.row_action" | "/ai/mandates/data.table_chat" | "/ai/mandates/desktop.cloud_chat" | "/ai/mandates/dictionary.workspace_guide" | "/ai/mandates/distillation.timeline_distiller" | "/ai/mandates/distillation.timeline_unfolder" | "/ai/mandates/docproc.content_structure" | "/ai/mandates/education.admin_guidance" | "/ai/mandates/education.analytics_narrate" | "/ai/mandates/education.audio_study_guidance" | "/ai/mandates/education.card_image_generator" | "/ai/mandates/education.card_image_prompt_writer" | "/ai/mandates/education.card_image_qc_judge" | "/ai/mandates/education.card_image_web_source" | "/ai/mandates/education.classes_guidance" | "/ai/mandates/education.creator_guidance" | "/ai/mandates/education.data_guidance" | "/ai/mandates/education.exam_prep_guidance" | "/ai/mandates/education.family_guidance" | "/ai/mandates/education.fastfire_guidance" | "/ai/mandates/education.features_guidance" | "/ai/mandates/education.flashcards_guidance" | "/ai/mandates/education.game_guidance" | "/ai/mandates/education.grade_handwritten" | "/ai/mandates/education.grade_work_guidance" | "/ai/mandates/education.kit_title" | "/ai/mandates/education.learn_guidance" | "/ai/mandates/education.levels_guidance" | "/ai/mandates/education.library_guidance" | "/ai/mandates/education.media_guidance" | "/ai/mandates/education.memory_generate" | "/ai/mandates/education.memory_guidance" | "/ai/mandates/education.memory_hint" | "/ai/mandates/education.mind_maps_guidance" | "/ai/mandates/education.mindmap_generate" | "/ai/mandates/education.notes_generate" | "/ai/mandates/education.notes_guidance" | "/ai/mandates/education.offline_guidance" | "/ai/mandates/education.page_guidance" | "/ai/mandates/education.plan_generate" | "/ai/mandates/education.planner_guidance" | "/ai/mandates/education.practice_oral_guidance" | "/ai/mandates/education.practice_tests_guidance" | "/ai/mandates/education.progress_guidance" | "/ai/mandates/education.quiz_deepen_item" | "/ai/mandates/education.quiz_generate" | "/ai/mandates/education.quiz_generate_from_source" | "/ai/mandates/education.quizzes_guidance" | "/ai/mandates/education.spoken_practice_design" | "/ai/mandates/education.spoken_practice_design_language" | "/ai/mandates/education.spoken_practice_grade" | "/ai/mandates/education.spoken_practice_grade_pronunciation" | "/ai/mandates/education.spoken_practice_review" | "/ai/mandates/education.start_guidance" | "/ai/mandates/education.study_aids_guidance" | "/ai/mandates/education.study_pack_flashcards" | "/ai/mandates/education.study_pack_lessons" | "/ai/mandates/education.study_pack_notes" | "/ai/mandates/education.study_pack_quiz" | "/ai/mandates/education.study_pack_v2_flashcards" | "/ai/mandates/education.study_pack_v2_lessons" | "/ai/mandates/education.study_pack_v2_notes" | "/ai/mandates/education.study_pack_v2_quiz" | "/ai/mandates/education.subjects_guidance" | "/ai/mandates/education.summaries_guidance" | "/ai/mandates/education.summarize" | "/ai/mandates/education.tutor_guidance" | "/ai/mandates/education.tutor_message" | "/ai/mandates/education.voice_tutor" | "/ai/mandates/evaluators.comparative_judge" | "/ai/mandates/evaluators.rubric_judge" | "/ai/mandates/extend.browser_chat" | "/ai/mandates/extend.pattern_from_data" | "/ai/mandates/extend.structured_extractor" | "/ai/mandates/feedback.item_triage_decision" | "/ai/mandates/flashcards.enrich_card" | "/ai/mandates/flashcards.expand_card" | "/ai/mandates/flashcards.fix_giveaway_cards" | "/ai/mandates/flashcards.generate_cards" | "/ai/mandates/flashcards.generate_from_source" | "/ai/mandates/flashcards.grade_spoken" | "/ai/mandates/flashcards.grade_typed_answer" | "/ai/mandates/flashcards.help_live" | "/ai/mandates/flashcards.helper_tts" | "/ai/mandates/flashcards.make_quiz_items" | "/ai/mandates/flashcards.micro_coach" | "/ai/mandates/flashcards.review_batch" | "/ai/mandates/flashcards.spoken_front_tts" | "/ai/mandates/flashcards.verify_against_source" | "/ai/mandates/foundry.planner" | "/ai/mandates/google.channel_video_plan" | "/ai/mandates/google.desk_work" | "/ai/mandates/google.traffic_change_explanation" | "/ai/mandates/growth_loop.quality_analyze" | "/ai/mandates/growth_loop.quality_brief" | "/ai/mandates/growth_loop.quality_crawl" | "/ai/mandates/growth_loop.quality_fill" | "/ai/mandates/growth_loop.quality_measure" | "/ai/mandates/growth_loop.quality_plan" | "/ai/mandates/growth_loop.quality_publish" | "/ai/mandates/growth_loop.quality_realize" | "/ai/mandates/growth_loop.quality_research" | "/ai/mandates/growth_loop.quality_serve" | "/ai/mandates/growth_loop.quality_suggest" | "/ai/mandates/growth_loop.quality_writeback" | "/ai/mandates/growth_loop.supervisor" | "/ai/mandates/hindsight.crystallizer" | "/ai/mandates/hindsight.replay_judge" | "/ai/mandates/hindsight.reviewer" | "/ai/mandates/human_decisions.fallback_decider" | "/ai/mandates/image.generate" | "/ai/mandates/image_pipeline.concept" | "/ai/mandates/image_pipeline.prompt_write" | "/ai/mandates/image_pipeline.qc_judge" | "/ai/mandates/iteration.architect" | "/ai/mandates/iteration.diagnostic" | "/ai/mandates/iteration.root_cause" | "/ai/mandates/iteration.thinking_display" | "/ai/mandates/kg.cluster_namer" | "/ai/mandates/kg.ner_extractor" | "/ai/mandates/knowledge.document_verifier" | "/ai/mandates/knowledge.qa_generator" | "/ai/mandates/knowledge.section_summarizer" | "/ai/mandates/local.answer_question" | "/ai/mandates/local.chat_persona_brainstorm" | "/ai/mandates/local.chat_persona_code_review" | "/ai/mandates/local.chat_persona_explain_simply" | "/ai/mandates/local.chat_persona_helpful" | "/ai/mandates/local.chat_persona_spoken_replies" | "/ai/mandates/local.chat_persona_summarize" | "/ai/mandates/local.chat_persona_transcript_polish" | "/ai/mandates/local.cloud_chat" | "/ai/mandates/local.cloud_chat_reply" | "/ai/mandates/local.confidential_chat" | "/ai/mandates/local.explain_code" | "/ai/mandates/local.extract_action_items" | "/ai/mandates/local.improve_writing" | "/ai/mandates/local.polish_style_action_items" | "/ai/mandates/local.polish_style_bullets" | "/ai/mandates/local.polish_style_custom" | "/ai/mandates/local.polish_style_formal" | "/ai/mandates/local.polish_style_light_cleanup" | "/ai/mandates/local.polish_style_meeting_notes" | "/ai/mandates/local.polish_style_standard" | "/ai/mandates/local.polish_transcript" | "/ai/mandates/local.raw_completion" | "/ai/mandates/local.summarize_text" | "/ai/mandates/local.tool_calling_chat" | "/ai/mandates/make.describe_template" | "/ai/mandates/mandate_outcome.goal_clause_extraction" | "/ai/mandates/mandate_outcome.goal_fitness_decision" | "/ai/mandates/mandates.holder_draft" | "/ai/mandates/marketing.endowment_analysis" | "/ai/mandates/marketing.endowment_portfolio" | "/ai/mandates/marketing.image_prompt" | "/ai/mandates/marketing.page_image" | "/ai/mandates/marketing.page_image_all_in_one" | "/ai/mandates/marketing.video_metadata" | "/ai/mandates/masterwork.approach_selector" | "/ai/mandates/masterwork.audition_judge" | "/ai/mandates/masterwork.bad_draft" | "/ai/mandates/masterwork.bad_example_probe" | "/ai/mandates/masterwork.case_oracle" | "/ai/mandates/masterwork.checkup_auditor" | "/ai/mandates/masterwork.coherence_partner" | "/ai/mandates/masterwork.conductor" | "/ai/mandates/masterwork.corpus_cleaner" | "/ai/mandates/masterwork.corpus_synthesizer" | "/ai/mandates/masterwork.counterparty" | "/ai/mandates/masterwork.critique_distiller" | "/ai/mandates/masterwork.draft_triage" | "/ai/mandates/masterwork.drip_distiller" | "/ai/mandates/masterwork.drip_question" | "/ai/mandates/masterwork.elicitation_judge" | "/ai/mandates/masterwork.exception_hunter" | "/ai/mandates/masterwork.exemplar_distiller" | "/ai/mandates/masterwork.faithfulness_judge" | "/ai/mandates/masterwork.intake_designer" | "/ai/mandates/masterwork.markup_distiller" | "/ai/mandates/masterwork.meeting_scavenger" | "/ai/mandates/masterwork.monologue_distiller" | "/ai/mandates/masterwork.outcome_judge" | "/ai/mandates/masterwork.pairwise_judge" | "/ai/mandates/masterwork.prediction_boundary" | "/ai/mandates/masterwork.prediction_distiller" | "/ai/mandates/masterwork.relationship_auditor" | "/ai/mandates/masterwork.rule_improver" | "/ai/mandates/masterwork.rulebook_auditor" | "/ai/mandates/masterwork.scout" | "/ai/mandates/masterwork.sealed_case_oracle" | "/ai/mandates/masterwork.sort_case_writer" | "/ai/mandates/masterwork.sort_distiller" | "/ai/mandates/masterwork.source_distiller" | "/ai/mandates/masterwork.teach_back_distiller" | "/ai/mandates/masterwork.teach_back_explainer" | "/ai/mandates/masterwork.template.chief_edit" | "/ai/mandates/masterwork.template.chief_generate" | "/ai/mandates/masterwork.template.editor" | "/ai/mandates/masterwork.template.maker" | "/ai/mandates/masterwork.timeline_distiller" | "/ai/mandates/masterwork.timeline_segmenter" | "/ai/mandates/masterwork.transcript_distiller" | "/ai/mandates/masterwork.transcript_shortlister" | "/ai/mandates/masterwork.triad_distiller" | "/ai/mandates/masterwork.triad_generator" | "/ai/mandates/masterwork.understudy" | "/ai/mandates/masterwork.unfolding_judge" | "/ai/mandates/masterworks.bench.a2_loop" | "/ai/mandates/masterworks.bench.calibration_decoy" | "/ai/mandates/masterworks.bench.consensus" | "/ai/mandates/masterworks.bench.extract" | "/ai/mandates/masterworks.bench.judge" | "/ai/mandates/masterworks.bench.panel" | "/ai/mandates/masterworks.bench.raw_arm" | "/ai/mandates/masterworks.vanilla_arm.answer_from_facts" | "/ai/mandates/masterworks.vanilla_arm.best_work" | "/ai/mandates/masterworks.vanilla_arm.outcome_case" | "/ai/mandates/masterworks.vanilla_arm.professional_help" | "/ai/mandates/media.youtube_analyzer" | "/ai/mandates/media_catalog.item_vetting_decision" | "/ai/mandates/meet.agenda_draft" | "/ai/mandates/meet.caption_translation" | "/ai/mandates/meet.live_intelligence" | "/ai/mandates/meet.live_notes" | "/ai/mandates/meet.pre_meeting_brief" | "/ai/mandates/meet.transcription" | "/ai/mandates/meet.wrap_up" | "/ai/mandates/memory.observer" | "/ai/mandates/memory.reflector" | "/ai/mandates/mermaid.diagram_editing" | "/ai/mandates/messaging.action_item_extraction" | "/ai/mandates/messaging.conversation_catch_up" | "/ai/mandates/messaging.conversation_summary" | "/ai/mandates/messaging.reply_drafting" | "/ai/mandates/messenger.answer_anything" | "/ai/mandates/models.availability_probe" | "/ai/mandates/ner.deep_chunk_extractor" | "/ai/mandates/ner.document_orienter" | "/ai/mandates/ner.entity_canonicalizer" | "/ai/mandates/ner.finisher" | "/ai/mandates/ner.item_proposer" | "/ai/mandates/ner.magic_moment_detector" | "/ai/mandates/ner.scope_proposer" | "/ai/mandates/ner.scope_slot_filler" | "/ai/mandates/ner.suggestion_reviewer" | "/ai/mandates/ner.sweep_scope_discoverer" | "/ai/mandates/ner.sweep_scope_reference_finder" | "/ai/mandates/ner.sweep_value_miner" | "/ai/mandates/news.angles" | "/ai/mandates/news.coarse_relevance" | "/ai/mandates/news.monitor_setup_proposer" | "/ai/mandates/news.report" | "/ai/mandates/news.story_origin" | "/ai/mandates/news.triage" | "/ai/mandates/notes.organizer" | "/ai/mandates/notes.page_guidance" | "/ai/mandates/observability.tool_trace_pattern_detection" | "/ai/mandates/observability.tool_trace_triage" | "/ai/mandates/orchestras.role_describer" | "/ai/mandates/orchestration.tool_failure_standoff_decision" | "/ai/mandates/org_chart.seat_job_suggester" | "/ai/mandates/pdf.chunk_clean_ocr_text" | "/ai/mandates/pdf.chunk_flashcards_json" | "/ai/mandates/pdf.chunk_flashcards_typescript" | "/ai/mandates/pdf.content_cleaner" | "/ai/mandates/personal_staff.escalation" | "/ai/mandates/personal_staff.front_line" | "/ai/mandates/podcast.audience_adapter" | "/ai/mandates/podcast.audio_dialogue" | "/ai/mandates/podcast.audio_english" | "/ai/mandates/podcast.audio_persian" | "/ai/mandates/podcast.chapter_marker" | "/ai/mandates/podcast.content_extractor" | "/ai/mandates/podcast.deep_research" | "/ai/mandates/podcast.image_v1" | "/ai/mandates/podcast.image_v2" | "/ai/mandates/podcast.image_v3" | "/ai/mandates/podcast.image_v4" | "/ai/mandates/podcast.image_v5" | "/ai/mandates/podcast.image_v6_feature" | "/ai/mandates/podcast.image_v6_feature_prompt" | "/ai/mandates/podcast.live_rewrite" | "/ai/mandates/podcast.metadata" | "/ai/mandates/podcast.multihost_script" | "/ai/mandates/podcast.post_prep_expansion" | "/ai/mandates/podcast.post_prep_fact_checking" | "/ai/mandates/podcast.post_prep_summarization" | "/ai/mandates/podcast.post_prep_translation" | "/ai/mandates/podcast.race_frontier" | "/ai/mandates/podcast.relevance_gate" | "/ai/mandates/podcast.roundtable_script" | "/ai/mandates/podcast.script_educational" | "/ai/mandates/podcast.script_news" | "/ai/mandates/podcast.script_persian" | "/ai/mandates/podcast.solo_script" | "/ai/mandates/podcast.title_optimizer" | "/ai/mandates/podcast.video_v1" | "/ai/mandates/podcast.video_v2" | "/ai/mandates/podcast_client.blog_writer" | "/ai/mandates/podcast_client.show_notes" | "/ai/mandates/podcast_client.topic_ideas" | "/ai/mandates/podcast_client.web_content_extractor" | "/ai/mandates/podcast_client.youtube_research" | "/ai/mandates/product_capture.instant_analysis" | "/ai/mandates/projects.creation_guide" | "/ai/mandates/proof_runs.judge" | "/ai/mandates/purpose.writer" | "/ai/mandates/rag.chunk_contextualizer" | "/ai/mandates/rag.grounded_synthesis" | "/ai/mandates/rag.grounding_claim_extract" | "/ai/mandates/rag.grounding_judge" | "/ai/mandates/rag.hyde_generator" | "/ai/mandates/rag.image_caption" | "/ai/mandates/rag.pdf_page_cleaner" | "/ai/mandates/rag.query_expander" | "/ai/mandates/rag_kinds.grounded_synthesis" | "/ai/mandates/records.enrichment" | "/ai/mandates/research.auto_tagger" | "/ai/mandates/research.condenser_1" | "/ai/mandates/research.condenser_2" | "/ai/mandates/research.coverage_audit" | "/ai/mandates/research.cross_cutting_tags" | "/ai/mandates/research.document_assembly" | "/ai/mandates/research.keyword_synthesis" | "/ai/mandates/research.report" | "/ai/mandates/research.report_updater" | "/ai/mandates/research.source_authority" | "/ai/mandates/research.source_triage_decision" | "/ai/mandates/research.structured_page_summary" | "/ai/mandates/research.suggest_setup" | "/ai/mandates/research.tag_consolidation" | "/ai/mandates/research.topic_deep_research" | "/ai/mandates/research_client.output_blog" | "/ai/mandates/research_client.output_brand_card" | "/ai/mandates/research_client.output_brand_profile" | "/ai/mandates/research_client.output_competitive_landscape" | "/ai/mandates/research_client.output_gap_analysis" | "/ai/mandates/research_client.output_literature_review" | "/ai/mandates/research_client.output_reputation_business" | "/ai/mandates/research_client.output_reputation_personal" | "/ai/mandates/research_client.output_seo" | "/ai/mandates/research_client.output_slides" | "/ai/mandates/scraper.fact_check" | "/ai/mandates/scraper.keyword_analysis" | "/ai/mandates/scraper.page_fetch_verdict" | "/ai/mandates/seo.ai_visibility_blind_question_writer" | "/ai/mandates/seo.ai_visibility_buyer_jobs" | "/ai/mandates/seo.ai_visibility_decision_analyst" | "/ai/mandates/seo.ai_visibility_evidence_icp" | "/ai/mandates/seo.ai_visibility_panel_designer" | "/ai/mandates/seo.ai_visibility_panel_report" | "/ai/mandates/seo.ai_visibility_question_architect" | "/ai/mandates/seo.ai_visibility_question_qa" | "/ai/mandates/seo.ai_visibility_writing_audit" | "/ai/mandates/seo.backlink_analysis" | "/ai/mandates/seo.backlink_context_assessor" | "/ai/mandates/seo.backlink_work_planner" | "/ai/mandates/seo.business_model_verdict" | "/ai/mandates/seo.competitor_classifier" | "/ai/mandates/seo.competitor_opportunity_autopsy" | "/ai/mandates/seo.competitor_page_autopsy" | "/ai/mandates/seo.coverage_analyst" | "/ai/mandates/seo.digital_pr_reputation_adjudicator" | "/ai/mandates/seo.evidence_workbench" | "/ai/mandates/seo.finding_fixer" | "/ai/mandates/seo.guidelines_drafter" | "/ai/mandates/seo.ideal_customer_profile" | "/ai/mandates/seo.keyword_classifier" | "/ai/mandates/seo.keyword_expander" | "/ai/mandates/seo.keyword_researcher" | "/ai/mandates/seo.keyword_serp_intent_analyst" | "/ai/mandates/seo.landscape_brief" | "/ai/mandates/seo.map_author" | "/ai/mandates/seo.map_curation" | "/ai/mandates/seo.money_map" | "/ai/mandates/seo.offering_extraction" | "/ai/mandates/seo.offering_valuation" | "/ai/mandates/seo.page_analyzer" | "/ai/mandates/seo.page_intent_proposer" | "/ai/mandates/seo.page_keyword_mapper" | "/ai/mandates/seo.page_mapper" | "/ai/mandates/seo.press_calendar_planner" | "/ai/mandates/seo.press_clip_reviewer" | "/ai/mandates/seo.press_headlines" | "/ai/mandates/seo.press_moment_researcher" | "/ai/mandates/seo.press_newsworthiness_check" | "/ai/mandates/seo.press_source_request_responder" | "/ai/mandates/seo.press_story_analyst" | "/ai/mandates/seo.press_strategist" | "/ai/mandates/seo.reputation_crisis_holding" | "/ai/mandates/seo.session_rule_writer" | "/ai/mandates/seo.session_stamp_proposer" | "/ai/mandates/seo.site_intake" | "/ai/mandates/seo.site_link_authority_router" | "/ai/mandates/seo.site_strategist" | "/ai/mandates/seo.starter_pack_proposer" | "/ai/mandates/seo.strategy.site_brief.generate" | "/ai/mandates/seo.topic_assigner" | "/ai/mandates/seo.topic_curation" | "/ai/mandates/shapes.write_picker_description" | "/ai/mandates/sms.owner_beta" | "/ai/mandates/social.post_breakdown" | "/ai/mandates/spaces.ask_page" | "/ai/mandates/spaces.autofill" | "/ai/mandates/spaces.build" | "/ai/mandates/spaces.design_database" | "/ai/mandates/spaces.move_in" | "/ai/mandates/spaces.writing_assist" | "/ai/mandates/start_page.maintainer" | "/ai/mandates/surfaces_client.binding_mapper" | "/ai/mandates/table.ask" | "/ai/mandates/table.column_fill" | "/ai/mandates/tasks.triage" | "/ai/mandates/tool_viz.component_generator" | "/ai/mandates/tools.summarize_content" | "/ai/mandates/transcript_studio.document_edit" | "/ai/mandates/transcript_studio.scribe_live" | "/ai/mandates/transcripts.clean_with_context" | "/ai/mandates/transcripts.clean_with_context_variable" | "/ai/mandates/transcripts.clean_without_context" | "/ai/mandates/vision_interview.adversary" | "/ai/mandates/vision_interview.amplifier" | "/ai/mandates/vision_interview.answer_tracker" | "/ai/mandates/vision_interview.archaeologist" | "/ai/mandates/vision_interview.architect" | "/ai/mandates/vision_interview.cartographer" | "/ai/mandates/vision_interview.requirements_author" | "/ai/mandates/vision_interview.scribe" | "/ai/mandates/vision_interview.sounding_board" | "/ai/mandates/vision_interview.transcript_cleaner" | "/ai/mandates/vision_interview.vision_author" | "/ai/mandates/voice.communicator" | "/ai/mandates/voice.gemini_live" | "/ai/mandates/voice.intro" | "/ai/mandates/voice.owner_beta" | "/ai/mandates/war_room.master" | "/ai/mandates/war_room.room" | "/ai/mandates/war_room.thread" | "/ai/mandates/web.endpoint_family_judge" | "/ai/mandates/workflow.complex_research.keyword_synthesis" | "/ai/mandates/workflow.complex_research.page_summary" | "/ai/mandates/workflow.complex_research.report" | "/ai/mandates/workflow.conductor" | "/ai/mandates/workflow.deep_research.keyword_synthesis" | "/ai/mandates/workflow.extract_namer" | "/ai/mandates/workflow.plan_design" | "/ai/mandates/workflow.plan_input_kind_authoring" | "/ai/mandates/workflow.plan_node_type_recommender" | "/ai/mandates/workflow.plan_notes_writer" | "/ai/mandates/workflow.plan_output_kind_authoring" | "/ai/mandates/workflow.recovery_advisor" | "/ai/mandates/workflow.run_assist_suggester" | "/ai/mandates/workflow.step_intelligence" | "/ai/mandates/workflow.steward" | "/ai/mandates/workflow.steward.agent_run" | "/ai/mandates/workflow.steward.data" | "/ai/mandates/workflow.steward.decision" | "/ai/mandates/workflow.steward.user_input" | "/ai/mandates/workflow.wizard.agent_run" | `/ai/mandates/${DynamicMandateKey}`;
+        /**
+         * POST — Continue any existing conversation (Guest OK)
+         * POST /ai/conversations/{conversationId}
+         * Conversation ID in URL. Just send user_input in the body.
+         */
+        readonly conversationContinue: (conversationId: string) => `/ai/conversations/${string}`;
+        /**
+         * POST — Pre-warm a conversation's server cache. No body. No auth.
+         * POST /ai/conversations/{conversationId}/warm
+         * Fire when user navigates to a conversation page.
+         */
+        readonly conversationWarm: (conversationId: string) => `/ai/conversations/${string}/warm`;
+        /**
+         * POST — Pre-warm an agent's server cache. No auth. (public endpoint)
+         * POST /ai/agents/{agentId}/warm
+         * Optional body: `{ source: "prompt" | "builtin" | "prompt_version" | "builtin_version" }`
+         */
+        readonly agentWarm: (agentId: string) => `/ai/agents/${string}/warm`;
+        /**
+         * POST — Start a new prompt conversation (Guest OK)
+         * POST /ai/prompts/{promptId}
+         * Body: PromptStartRequest — user_input, variables, stream, debug, client_tools, etc.
+         * Never send conversation_id — the server generates it and returns it in the stream.
+         */
+        readonly promptStart: (promptId: string) => `/ai/prompts/${string}`;
+        /**
+         * POST — Pre-warm a prompt's server cache. No auth. (public endpoint)
+         * POST /ai/prompts/{promptId}/warm
+         * Optional body: `{ source: string | null }`
+         */
+        readonly promptWarm: (promptId: string) => `/ai/prompts/${string}/warm`;
+        /**
+         * POST — Start a new block-streaming agent session (Guest OK)
+         * POST /ai/agents-blocks/{agentId}
+         * Same as agentStart but emits 'content_block' NDJSON events instead of raw 'chunk' events.
+         */
+        readonly agentBlocksStart: (agentId: string) => `/ai/agents-blocks/${string}`;
+        /**
+         * POST — Pre-warm a block-streaming agent (Public)
+         * POST /ai/agents-blocks/{agentId}/warm
+         * Optional body: `{ source: "prompt" | "builtin" | "prompt_version" | "builtin_version" }`
+         */
+        readonly agentBlocksWarm: (agentId: string) => `/ai/agents-blocks/${string}/warm`;
+        /** POST — Cancel a running request by request_id (Authenticated) */
+        readonly cancel: (requestId: string) => `/ai/cancel/${string}`;
+    };
+    /** Block processing test endpoints — Guest OK */
+    readonly blockProcessing: {
+        /** POST — Process raw text/markdown → structured blocks (JSON response) */
+        readonly process: "/utilities/block-processing/process";
+        /** POST — Process raw text/markdown → block events (NDJSON stream, simulates live agent) */
+        readonly processStream: "/utilities/block-processing/process/stream";
+    };
+    /** CX-data endpoints — conversation/message data (Authenticated) */
+    readonly cx: {
+        /**
+         * GET — Snapshot of "what the model is currently seeing" for a conversation.
+         * GET /cx/conversations/{conversationId}/context-state
+         * Initial hydration for the Model Context tab; live updates come via
+         * CONTEXT_STATE / CONTEXT_TRIMMED stream events after each turn.
+         */
+        readonly contextState: (conversationId: string) => `/cx/conversations/${string}/context-state`;
+    };
+    /** CMS server work — authenticated. CMS row CRUD stays direct-to-Supabase. */
+    readonly cms: {
+        /** POST — Canonical matrx-content-guard validation before CMS writes. */
+        readonly validate: "/cms/validate";
+        /**
+         * POST — THE decision door for a queued content exception
+         * (`features/approvals/cms-door.ts`). The exception id is the idempotency
+         * key; the server finds its queue row and replays the ordinary human write
+         * path. Nothing else decides these — the CMS's own review route is gone.
+         */
+        readonly approveException: (exceptionId: string) => `/cms/exceptions/${string}/approve`;
+        readonly rejectException: (exceptionId: string) => `/cms/exceptions/${string}/reject`;
+        /**
+         * POST `{page_id}` — the publish writing check for a page's FINAL text (the
+         * same gate the server publish seam runs). `allowed=false` carries the
+         * must-fix list and the three settings that lift the block.
+         */
+        readonly publishCheck: "/cms/publish-check";
+    };
+    /** Tool testing endpoints — Authenticated */
+    readonly tools: {
+        /** GET — List available tools (?category=) */
+        readonly testList: "/tools/test/list";
+        /** GET — Get tool details by name */
+        readonly testDetail: (toolName: string) => `/tools/test/${string}`;
+        /** POST — Create/reuse test session */
+        readonly testSession: "/tools/test/session";
+        /** POST — Execute tool test with streaming */
+        readonly testExecute: "/tools/test/execute";
+        /**
+         * POST `{tool_name, arguments, spend_approval_id?}` — a SCREEN runs one
+         * screen-callable tool as the signed-in person (no agent, no conversation).
+         * `status`: `ok` (the tool's own envelope in `output`), `needs_approval`
+         * (`approval` carries the approve_spend ask and its form render; call again
+         * with `spend_approval_id`), or `error`. 403 for a tool not declared
+         * `screen_callable`.
+         */
+        readonly screenRun: "/tools/screen-run";
+    };
+    /** Scraper endpoints — Authenticated */
+    readonly scraper: {
+        /** POST — Quick scrape URLs */
+        readonly quickScrape: "/scraper/quick-scrape";
+        /** POST — Search keywords */
+        readonly search: "/scraper/search";
+        /** POST — Search and scrape combined */
+        readonly searchAndScrape: "/scraper/search-and-scrape";
+        /** POST — Search and scrape with limits */
+        readonly searchAndScrapeLimited: "/scraper/search-and-scrape-limited";
+    };
+    /** Utility endpoints — Guest OK */
+    readonly utilities: {
+        /** @deprecated Use ENDPOINTS.pdf.extractText instead */
+        readonly pdfExtractText: "/utilities/pdf/extract-text";
+    };
+    /**
+     * PDF extraction, manipulation, and document management — Authenticated.
+     * Most JSON endpoints accept a unified source via `MediaRef` (preferred for
+     * cloud files via `cld_id`), `file`, `url`, or `local_path`. See
+     * `features/pdf-extractor/types.ts` for the full type re-exports.
+     *
+     * NOTE: list/detail endpoints below are kept for backwards compatibility
+     * but the workspace now reads `processed_documents` directly from Supabase
+     * for the sidebar list and the on-click detail (the old `extracted_documents`
+     * facade view was retired 2026-06-11). Loading hundreds of full `content`
+     * rows from Python was making the window take 2+ minutes to open.
+     */
+    readonly pdf: {
+        /**
+         * POST — Compress PDF (multipart file upload). Query params:
+         *   - `level` (1..5): minimum quality tier. 1=lossless, 5=max compression.
+         *   - `max_size_mb` (optional float): absolute upper bound on output size;
+         *     when set, the server escalates `level` one tier at a time until the
+         *     output fits (or tier 5 is reached). Omit for "honour level exactly."
+         * Response headers include `X-Compression-Level-Used` and
+         * `X-Compression-Cap-Satisfied` so the caller can see what actually ran.
+         */
+        readonly compress: "/utilities/pdf/compress";
+        /** POST — Single-file text extraction (stateless multipart, NDJSON streaming).
+         * Emits `pdf_extract_started` / `pdf_page_extracted` / `pdf_extract_complete`
+         * data events; the complete event carries the old `{ filename, text_content }`
+         * body. Consume via `streamPdfExtractText` (features/pdf-extractor/service/streamPdf.ts). */
+        readonly extractText: "/utilities/pdf/extract-text";
+        /** POST — Batch extraction with NDJSON streaming (saves to DB + storage). */
+        readonly batchExtract: "/utilities/pdf/batch-extract";
+        /**
+         * POST — Phone-scanner assembly (NDJSON streaming): ordered photos
+         * (optional quad + rotation) + PDFs → ONE user-visible PDF, extracted
+         * + handed to the content pipeline. Terminal `data` event carries
+         * `{ file_id, doc_id, page_count }`.
+         */
+        readonly fromImages: "/utilities/pdf/from-images";
+        /** POST — Text extraction from a remote source (MediaRef / url; NDJSON streaming,
+         * same events as `extractText`). Consume via `streamPdfExtractTextRemote`. */
+        readonly extractTextRemote: "/utilities/pdf/extract-text-remote";
+        /** POST — Table extraction. Returns `PdfResult`. */
+        readonly extractTables: "/utilities/pdf/extract-tables";
+        /** POST — Extract pages into a new PDF. Returns PDF blob. */
+        readonly extractPages: "/utilities/pdf/extract-pages";
+        /** POST — Crop pages (with `crop_box`). Returns PDF blob. */
+        readonly cropPages: "/utilities/pdf/crop-pages";
+        /** POST — Rotate pages. Returns PDF blob. */
+        readonly rotatePages: "/utilities/pdf/rotate-pages";
+        /** POST — Delete pages. Returns PDF blob. */
+        readonly deletePages: "/utilities/pdf/delete-pages";
+        /** POST — Merge multiple PDFs. Returns PDF blob. */
+        readonly merge: "/utilities/pdf/merge";
+        /** POST — Split PDF into parts (`parts` or `max_pages_per_part`). Returns ZIP blob. */
+        readonly split: "/utilities/pdf/split";
+        /** POST — Process a PDF with AI agents (single-pass / chunk / reassembly). Streams JSONL. */
+        readonly processWithAi: "/utilities/pdf/process-with-ai";
+        /** POST — Full pipeline: extract → chunk → AI → reassembly. Streams JSONL with `PdfPipelineOptions`. */
+        readonly fullPipeline: "/utilities/pdf/full-pipeline";
+        /** POST — AI content cleaning on an already-extracted document (NDJSON streaming). */
+        readonly cleanContent: (docId: string) => `/utilities/pdf/clean-content/${string}`;
+        /** @deprecated — Read `processed_documents` directly from Supabase with metadata-only projection. */
+        readonly documents: "/utilities/pdf/documents";
+        /** @deprecated — Read `processed_documents` directly from Supabase. */
+        readonly document: (docId: string) => `/utilities/pdf/documents/${string}`;
+        /** POST — Render one page to an image blob (PNG/JPEG/WebP/TIFF). */
+        readonly renderPage: "/utilities/pdf/render-page";
+        /** POST — Render every page; returns a ZIP of per-page images. */
+        readonly renderAll: "/utilities/pdf/render-all";
+        /** POST — Cover thumbnail at `max_side` px. */
+        readonly renderThumbnail: "/utilities/pdf/render-thumbnail";
+        /** POST — Reorder pages by `new_order`. Returns PDF blob. */
+        readonly reorderPages: "/utilities/pdf/reorder-pages";
+        /** POST — Insert pages from `source_*` into target. Returns PDF blob. */
+        readonly insertPages: "/utilities/pdf/insert-pages";
+        /** POST — Duplicate pages inline (`count` copies). Returns PDF blob. */
+        readonly duplicatePages: "/utilities/pdf/duplicate-pages";
+        /** GET — Studio preset catalog. Returns `PdfStudioCatalog`. */
+        readonly studioPresets: "/utilities/pdf/studio/presets";
+        /** POST — Studio dispatcher; image blob or ZIP depending on preset. */
+        readonly studioRender: "/utilities/pdf/studio/render";
+        /** POST — Detect headers / footers / watermarks / recurring side notes. Returns `RepeatedRegionsReport`. */
+        readonly detectRepeatedRegions: "/utilities/pdf/detect-repeated-regions";
+        /** POST — Detect + strip repeated regions from per-page text. Returns `StripRepeatedRegionsResultSchema`. */
+        readonly stripRepeatedRegions: "/utilities/pdf/strip-repeated-regions";
+        /** POST — Classify every page (cover / TOC / body / exhibit / signature / billing / ...). Returns `LayoutClassificationReport`. */
+        readonly classifyPages: "/utilities/pdf/classify-pages";
+        /** POST — Multi-column → linear reading order. Returns `ReadingOrderReport`. */
+        readonly extractReadingOrder: "/utilities/pdf/extract-reading-order";
+        /** GET — Builtin redaction pattern catalog (SSN / email / phone / MRN / ...). */
+        readonly redactPatterns: "/utilities/pdf/redact/patterns";
+        /** POST — Redact one or more page-anchored rectangles. PDF blob or persisted JSON. */
+        readonly redactRegions: "/utilities/pdf/redact-regions";
+        /** POST — Redact every regex match (builtin id or raw pattern). PDF blob or persisted JSON. */
+        readonly redactPattern: "/utilities/pdf/redact-pattern";
+        /** POST — Detect repeated regions then redact selected/all. PDF blob or persisted JSON. */
+        readonly redactRepeatedRegions: "/utilities/pdf/redact-repeated-regions";
+        /** POST — Wipe /Info + XMP metadata + thumbnails. */
+        readonly stripMetadata: "/utilities/pdf/strip-metadata";
+        /** POST — Granular composite scrub (metadata / attachments / JS / flatten). */
+        readonly scrub: "/utilities/pdf/scrub";
+        /** POST — Bake annotations + widgets into page content. */
+        readonly flattenAnnotations: "/utilities/pdf/flatten-annotations";
+    };
+    /**
+     * Per-page AI extraction — fan out an agent across pages of a document and
+     * persist structured results anchored to source page numbers. See
+     * `features/page-extraction/FEATURE.md` for the data model.
+     */
+    readonly pageExtraction: {
+        /** POST — Run extraction across pages (NDJSON streaming, per-page events). */
+        readonly runStream: "/page-extraction/runs/stream";
+        /** POST — Retry one failed page-run (replaces its results). */
+        readonly retryPageRun: (pageRunId: string) => `/page-extraction/page-runs/${string}/retry`;
+        /** POST — Cancel an in-flight run. */
+        readonly cancelRun: (runId: string) => `/page-extraction/runs/${string}/cancel`;
+    };
+    /** Test/admin endpoints — Admin only */
+    readonly tests: {
+        /** GET/POST — Example endpoints */
+        readonly examples: "/tests/examples";
+        /** GET — Stream text test */
+        readonly streamText: "/tests/stream/text";
+    };
+    /** Media processing endpoints — Authenticated */
+    readonly media: {
+        /**
+         * POST — Upload podcast video → extract cover frame, render podcast
+         * variants, returns URLs + Asset envelope. Image-only uploads now go
+         * through {@link ENDPOINTS.assets.upload} with `preset="podcast"`.
+         */
+        readonly uploadPodcastVideo: "/media/podcast/upload-video";
+        /**
+         * POST — stream the spoken transcript of a captioned YouTube video as
+         * text. Body: `{ youtube_url }`. Reuses the "YouTube Video Transcription
+         * Analysis" agent server-side (quiet run, no chat clutter). Streams NDJSON:
+         * the transcript arrives as chunk text (`accumulatedText`); a captionless
+         * video yields a non-fatal warning + empty text so callers stay honest.
+         */
+        readonly youtubeTranscript: "/media/youtube/transcript";
+    };
+    /**
+     * Content-processing orchestrator — the interactive counterpart to the
+     * automatic post-upload hook. Triggers extract→clean→chunk→embed→NER for an
+     * already-uploaded `cld_files` row and streams typed progress (NDJSON). The
+     * terminal `data` event carries a `ContentProcessingResult`
+     * (`signature: "ContentProcessingResult"`) with `status` + `processed_document_id`.
+     * Today's content types: `"pdf"` (default) and `"office"` (docx/pptx/xlsx —
+     * pure-python extraction, no LibreOffice/OCR; already-clean markdown so the
+     * LLM clean stage is skipped). The extracted text itself is NOT in the
+     * stream — read `docproc.processed_documents.content` directly via
+     * `docprocDb(supabase)` (canonical direct-Supabase read) once the run
+     * completes.
+     */
+    readonly contentProcessing: {
+        readonly process: (cldFileId: string) => `/content-processing/${string}`;
+    };
+    /**
+     * Unified asset (image / media) upload + render-variants pipeline.
+     *
+     * One endpoint family handles every media upload in the platform. The
+     * server renders preset variants (cover, OG, thumbnail, avatar sizes,
+     * favicons, etc.) and returns the canonical {@link Asset} envelope —
+     * see `features/files/types.ts` for the wire shape.
+     *
+     * Preset → variant key map (high level):
+     *   - raw      → only `original`
+     *   - podcast  → cover_url (3000²), cover_sd_url (1400²) + social baseline
+     *   - social   → og_url, square_url, portrait_url, story_url, yt_thumbnail_url + baseline
+     *   - web      → hero_url, og_url, card_url, touch_icon_url, pwa_icon_url, thumbnail_url + baseline
+     *   - email    → header_url, square_url (no baseline)
+     *   - logo     → logo_lg_url, logo_md_url, logo_sm_url + baseline
+     *   - avatar   → avatar_xl/lg/md/sm/xs_url (no baseline)
+     *   - favicon  → favicon_android/apple_touch/32/16_url (no baseline)
+     *
+     * Authenticated. See `features/files/api/assets.ts` for the typed
+     * client wrapper.
+     */
+    readonly assets: {
+        /** POST — multipart upload + render preset variants. */
+        readonly upload: "/assets";
+        /** GET — read the canonical Asset envelope for an upload's master file. */
+        readonly detail: (fileId: string) => `/assets/${string}`;
+        /** PATCH — change sharing / metadata. */
+        readonly patch: (fileId: string) => `/assets/${string}`;
+        /** POST — render more variants (idempotent). */
+        readonly addVariants: (fileId: string) => `/assets/${string}/variants`;
+        /** GET — list every server-known preset. */
+        readonly presets: "/assets/presets";
+        /**
+         * GET — convert any cld_files row to an Asset envelope. The
+         * click-to-render primitive: hand any file_id, get back URLs +
+         * variants the FE can render directly.
+         */
+        readonly forFile: (fileId: string) => `/files/${string}/asset`;
+        /**
+         * POST — no-persist preview rendering (E.16, matrx-utils v1.1.0).
+         * Accepts a `MediaRef` source + variants[]. Returns either base64
+         * `data_url` (≤256 KB) or a 5-min `ephemeral_url`. Replaces the
+         * deleted Next.js Sharp route at app/api/images/studio/process.
+         */
+        readonly preview: "/assets/preview";
+        /**
+         * POST — multipart variant of {@link preview}. Render directly without
+         * a prior `cld_files` row. Useful for Image Studio drag-and-drop
+         * preview before commit-to-save.
+         */
+        readonly previewMultipart: "/assets/preview/multipart";
+        /**
+         * POST — no-persist PDF compression (E.17). Accepts a `MediaRef` source.
+         * Returns `data_url` (≤256 KB) or a 5-min `ephemeral_url`.
+         * Replaces the deleted Next.js route at app/api/pdf/compress.
+         */
+        readonly pdfCompress: "/assets/pdf-compress";
+        /** POST — multipart variant of {@link pdfCompress}. */
+        readonly pdfCompressMultipart: "/assets/pdf-compress/multipart";
+    };
+    /** Health endpoints — Public (aligned with types/python-generated OpenAPI) */
+    readonly health: {
+        /** GET — Basic health check */
+        readonly check: "/health";
+        /** GET — Detailed health with component status */
+        readonly detailed: "/health/detailed";
+        /** GET — Liveness (process up; no I/O) */
+        readonly live: "/health/live";
+        /** GET — Readiness (deps initialized; use for deploy probes) */
+        readonly ready: "/health/ready";
+    };
+    /** Research endpoints — Authenticated */
+    readonly research: {
+        /** POST — Initialize research config */
+        readonly init: "/research/init";
+        /** GET — List templates */
+        readonly templatesList: "/research/templates/list";
+        /** POST — Create template */
+        readonly templatesCreate: "/research/templates";
+        /** GET — Template detail */
+        readonly templateDetail: (templateId: string) => `/research/templates/${string}`;
+        /** GET — Extension scrape queue */
+        readonly extensionScrapeQueue: "/research/extension/scrape-queue";
+        /** GET — Research state / PATCH — Update config */
+        readonly state: (projectId: string) => `/research/${string}`;
+        /** POST — Suggest setup */
+        readonly suggest: (projectId: string) => `/research/${string}/suggest`;
+        /** POST — Run full pipeline (streaming) */
+        readonly run: (projectId: string) => `/research/${string}/run`;
+        /** POST — Trigger search (streaming) */
+        readonly search: (projectId: string) => `/research/${string}/search`;
+        /** POST — Trigger scrape (streaming) */
+        readonly scrape: (projectId: string) => `/research/${string}/scrape`;
+        /** POST — Analyze all sources (streaming) */
+        readonly analyzeAll: (projectId: string) => `/research/${string}/analyze-all`;
+        /** POST — Synthesize */
+        readonly synthesize: (projectId: string) => `/research/${string}/synthesize`;
+        /** GET — Keywords */
+        readonly keywords: (projectId: string) => `/research/${string}/keywords`;
+        /** GET — Sources */
+        readonly sources: (projectId: string) => `/research/${string}/sources`;
+        /** GET — Tags */
+        readonly tags: (projectId: string) => `/research/${string}/tags`;
+        /** GET/POST — Document */
+        readonly document: (projectId: string) => `/research/${string}/document`;
+        /** GET — Costs */
+        readonly costs: (projectId: string) => `/research/${string}/costs`;
+    };
+    /**
+     * ACTION REQUESTS — `platform.action_request`. An agent asks the person it
+     * works for for ONE thing; they answer on `/q/<token>` and the parked turn
+     * resumes.
+     *
+     * All three sit on aidream's PUBLIC router at the BARE prefix (no `/api`,
+     * no version), because the person tapping them has no account in the general
+     * case. They are POSTs deliberately — the token would otherwise sit in a URL,
+     * which means in the access log and in every proxy between here and it.
+     *
+     * Reached ONLY from `features/action-requests/service.ts` (server lane): the
+     * `Authorization` header is what separates a signed-in completion from a
+     * bearer one, so the decision to send it belongs where the session cookie is.
+     */
+    readonly actionRequests: {
+        /** POST — what the page draws. MUTATES NOTHING. */
+        readonly open: "/action-requests/open";
+        /** POST — the answer. */
+        readonly complete: "/action-requests/complete";
+        /** POST — "text me a new link". Rate-limited in the database. */
+        readonly remint: "/action-requests/remint";
+    };
+};
+
+export { type ApiTargetLogContext, BackendApiError, type BackendApiErrorData, type BackendErrorCode, type BackendFailureExplanation, type CreateMatrxTransportOptions, type CreateWarmupOptions, ENDPOINTS, 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 MatrxAgentStartRequest, type MatrxAiApiVersion, MatrxApiError, type MatrxCallError, type MatrxCallResult, type MatrxCallScope, type MatrxCancelResponse, type MatrxChatMessage, type MatrxClientSessionProvider, type MatrxClientToolResult, type MatrxCompletedRun, type MatrxContextAnchor, type MatrxConversationContinueRequest, type MatrxConversationResumeRequest, type MatrxConversationStart, type MatrxEphemeralConversation, type MatrxFollowedOutcome, type MatrxHttpErrorLike, type MatrxHttpMethod, type MatrxJsonObject, type MatrxJsonValue, type MatrxLiveRunRejoin, type MatrxLiveStreamUnavailable, type MatrxMandateStartRequest, type MatrxOperationEventsPage, type MatrxOperationFollowEvent, type MatrxOperationStatusResponse, type MatrxOperationsByLinkResponse, type MatrxPendingCallSummary, type MatrxProtocolDowngrade, type MatrxProtocolFallbackOptions, type MatrxQueryParams, type MatrxRequestInfo, type MatrxRequestScope, MatrxRunError, 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 MatrxToolResultsResponse, type MatrxTransport, type MatrxTransportDiagnostics, type MatrxTransportRequest, type MatrxTransportTarget, type MatrxTurnFields, OrganizationContextError, type OrganizationContextErrorCode, type OrganizationOperation, type ParseMatrxNdjsonResponseHooks, type ProviderSessionFailure, type ProviderSessionFailureVerdict, type ProviderSessionUsage, type ProviderSessionUsageReceipt, type ProviderUsageReporter, type ProviderUsageReporterOptions, type ProviderUsageSendResult, type QueryValue, RUN_OUTPUT_KINDS, RUN_STREAM_LIFETIME_BACKSTOP_MS, RUN_WAIT_KNOB_FEATURE, ResilientFetchOptions, type ResumeOrRejoinOptions, type ResumeOrRejoinOutcome, type RunAgentToCompletionOptions, 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, cancelAgentRun, continueAgentConversation, continueEphemeralConversationStart, continueStoredConversationStart, createMatrxTransport, createOrganizationOperation, createProviderUsageReporter, createStreamReplayCursor, createWarmup, describeBackendFailure, encodePathSegment, executeMatrxCall, extractMatrxErrorCode, extractMatrxErrorMessage, fetchWithMatrxProtocolFallback, followRuntimeOperationEvents, followRuntimeOperationToEnd, followServerJob, followUnavailableRejoin, followWorkflowRunEvents, getRuntimeOperationStatus, getRuntimeOperationsByLink, getUserMessage, honestTransportMessage, isBareTransportCode, isCoveredAiPath, isEmptyProviderUsage, isGenericUserMessage, isJobOutputKind, isLiveStreamUnavailable, isResumeConflict, isServerJobSettled, isStreamTransportLost, isV2Path, listConversationPendingToolCalls, listRuntimeOperationEvents, listUserPendingToolCalls, logApiTarget, mintMatrxConversationId, newEphemeralConversationStart, newStoredConversationStart, normalizeMatrxError, openMatrxStream, parseCallApiError, parseHttpError, parseHttpErrorBody, parseMatrxNdjsonResponse, parsePersistedBackendError, parseStreamError, pickServerJobOperation, preconnectServer, providerSessionFailureBody, providerSessionUsageBody, readConversationOrganizationId, readLiveRunRejoin, readLiveRunRequestId, readLiveStreamUnavailable, readMatrxErrorCode, readMatrxErrorCodeFromMessage, readMatrxJsonResponse, readStreamCursor, redactUrlForRequestLog, rejoinRuntimeOperation, reportProviderSessionFailure, reportProviderSessionUsage, requestJson, requestStream, requireOrganizationContext, resetPreconnectedForTests, resolveEndpointPath, resolveRunWaitWith, resumeAgentConversation, resumeOrRejoin, runAgentToCompletion, runJobLabel, runOutputKindFromModalities, runWaitKnobKey, runWaitTimeoutMessage, runtimeOperationRejoinPath, sendMatrxRequest, serverJobRejoinHandle, settleRunPickup, shouldReportMatrxCallError, startAgentRun, startMandateRun, streamErrorText, submitAgentToolResults, toRunHandle, toV1FallbackUrl, toV2Path, unwrapUpstreamError, withRunOrganization };