@ai-matrx/api 0.1.7 → 0.1.9

package/dist/index.js

@@ -1,7 +1,7 @@
 export { monitorStream } from './chunk-YTEOFGFC.js';
 export { API_KEY_PREFIX, MATRX_HEADERS, credentialToHeaders, toCredentialsPort } from './chunk-7MZPBCFV.js';
-import { OrganizationContextError, BackendApiError, parseHttpError, MatrxApiError, applyOrganizationContextHeader, extractMatrxErrorCode, extractMatrxErrorMessage, readMatrxNdjsonStream, readMatrxSseStream, requireOrganizationContext, StreamTransportError } from './chunk-2FJPWNXG.js';
-export { BackendApiError, CONTRACT_SHA256, DEPLOYMENTS, DOMAINS, MatrxApiError, OrganizationContextError, StreamTransportError, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, createApi, createOrganizationOperation, describeBackendFailure, extractMatrxErrorCode, extractMatrxErrorMessage, getUserMessage, isGenericUserMessage, isStreamTransportLost, openJsonOrStream, openStream, parseCallApiError, parseHttpError, parseHttpErrorBody, parsePersistedBackendError, parseStreamError, requireOrganizationContext, unwrapUpstreamError } from './chunk-2FJPWNXG.js';
+import { OrganizationContextError, BackendApiError, parseHttpError, MatrxApiError, applyOrganizationContextHeader, extractMatrxErrorCode, extractMatrxErrorMessage, readMatrxNdjsonStream, readMatrxSseStream, requireOrganizationContext, StreamTransportError } from './chunk-PIVTHTVR.js';
+export { BackendApiError, CONTRACT_SHA256, DEPLOYMENTS, DOMAINS, MatrxApiError, OrganizationContextError, StreamTransportError, applyOrganizationContextHeader, assertOrganizationMatchesOperation, assertQueryOrganizationMatchesContext, createApi, createOrganizationOperation, describeBackendFailure, extractMatrxErrorCode, extractMatrxErrorMessage, getUserMessage, isGenericUserMessage, isStreamTransportLost, openJsonOrStream, openStream, parseCallApiError, parseHttpError, parseHttpErrorBody, parsePersistedBackendError, parseStreamError, requireOrganizationContext, unwrapUpstreamError } from './chunk-PIVTHTVR.js';
 import { resilientFetch, isNetError, extractErrorMessage } from './chunk-KIEAFMKB.js';
 export { AbortedError, ConnectTimeoutError, HeartbeatTimeoutError, HttpError, NetError, NetworkError, OfflineError, TotalTimeoutError, extractErrorMessage, isNetError, isTransportFailure, resilientFetch, toNetError, withRetry } from './chunk-KIEAFMKB.js';
 import { credentialToHeaders } from '@ai-matrx/auth/credentials';
@@ -1741,4 +1741,637 @@ function createProviderUsageReporter(options) {
   };
 }
 
-export { MATRX_AI_API_VERSION_DEFAULT, MATRX_LIVE_STREAM_UNAVAILABLE, MATRX_RESUME_CONFLICT, MATRX_RUN_IN_PROGRESS, MATRX_UI_ONLY_BODY_FIELDS, RUN_OUTPUT_KINDS, RUN_STREAM_LIFETIME_BACKSTOP_MS, RUN_WAIT_KNOB_FEATURE, TERMINAL_MATRX_RUNTIME_STATUSES, V2_COVERED_AI_PATH_TEMPLATES, WARM_PATH, aiVersionPathOverrides, applyAiApiVersion, applyDesktopTargetToRequestBody, bareStatusSentence, buildMatrxRequestBody, buildMatrxRequestUrl, buildQuery, buildSafeRequestLog, continueEphemeralConversationStart, continueStoredConversationStart, createMatrxTransport, createProviderUsageReporter, createStreamReplayCursor, createWarmup, encodePathSegment, executeMatrxCall, fetchWithMatrxProtocolFallback, followRuntimeOperationEvents, followRuntimeOperationToEnd, followServerJob, followUnavailableRejoin, followWorkflowRunEvents, getRuntimeOperationStatus, getRuntimeOperationsByLink, honestTransportMessage, isBareTransportCode, isCoveredAiPath, isEmptyProviderUsage, isJobOutputKind, isLiveStreamUnavailable, isResumeConflict, isServerJobSettled, isV2Path, listRuntimeOperationEvents, logApiTarget, mintMatrxConversationId, newEphemeralConversationStart, newStoredConversationStart, normalizeMatrxError, openMatrxStream, parseMatrxNdjsonResponse, pickServerJobOperation, preconnectServer, providerSessionFailureBody, providerSessionUsageBody, readConversationOrganizationId, readLiveRunRejoin, readLiveRunRequestId, readLiveStreamUnavailable, readMatrxErrorCode, readMatrxErrorCodeFromMessage, readMatrxJsonResponse, readStreamCursor, redactUrlForRequestLog, rejoinRuntimeOperation, reportProviderSessionFailure, reportProviderSessionUsage, requestJson, requestStream, resetPreconnectedForTests, resolveEndpointPath, resolveRunWaitWith, resumeOrRejoin, runJobLabel, runOutputKindFromModalities, runWaitKnobKey, runWaitTimeoutMessage, runtimeOperationRejoinPath, sendMatrxRequest, serverJobRejoinHandle, settleRunPickup, shouldReportMatrxCallError, streamErrorText, toRunHandle, toV1FallbackUrl, toV2Path, withRunOrganization };
+// src/core/run.ts
+async function streamCall(transport, path, body, options) {
+  const response = await requestStream(transport, path, {
+    method: "POST",
+    // This client IS the streaming path — `stream: true` always, last so a
+    // caller-supplied value can never flip the response off NDJSON.
+    body: { ...body, stream: true },
+    ...options.signal ? { signal: options.signal } : {}
+  });
+  return toRunHandle(response, options);
+}
+function startAgentRun(transport, agentId, request, options = {}) {
+  return streamCall(
+    transport,
+    `/ai/agents/${encodePathSegment(agentId)}`,
+    request,
+    options
+  );
+}
+function startMandateRun(transport, mandateKey, request, options = {}) {
+  return streamCall(
+    transport,
+    `/ai/mandates/${encodePathSegment(mandateKey)}`,
+    request,
+    options
+  );
+}
+function continueAgentConversation(transport, conversationId, request, options = {}) {
+  return streamCall(
+    transport,
+    `/ai/conversations/${encodePathSegment(conversationId)}`,
+    request,
+    options
+  );
+}
+function resumeAgentConversation(transport, conversationId, request = {}, options = {}) {
+  return streamCall(
+    transport,
+    `/ai/conversations/${encodePathSegment(conversationId)}/resume`,
+    request,
+    options
+  );
+}
+function cancelAgentRun(transport, requestId, options = {}) {
+  const query = buildQuery(
+    options.mode === "interrupt" ? { mode: "interrupt" } : {}
+  );
+  return requestJson(
+    transport,
+    `/ai/cancel/${encodePathSegment(requestId)}${query}`,
+    {
+      method: "POST",
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+}
+var MatrxRunError = class extends Error {
+  name = "MatrxRunError";
+  /** The verbatim `error` event payload, when one fired. */
+  errorPayload;
+  /** The `user_request` completion status (`"failed"` | `"cancelled"`), when that was the trigger. */
+  completionStatus;
+  /** Text streamed before the failure — partial content never vanishes. */
+  partialText;
+  constructor(args) {
+    super(args.message);
+    this.errorPayload = args.errorPayload ?? null;
+    this.completionStatus = args.completionStatus ?? null;
+    this.partialText = args.partialText ?? "";
+  }
+};
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringField(value, key) {
+  if (!isRecord3(value)) return null;
+  const field = value[key];
+  return typeof field === "string" && field ? field : null;
+}
+async function runAgentToCompletion(transport, agentId, request, options = {}) {
+  const handle = await startAgentRun(transport, agentId, request, options);
+  let text = "";
+  let completion = null;
+  let failure = null;
+  for await (const envelope of handle.events) {
+    options.onEvent?.(envelope);
+    if (envelope.event === "chunk") {
+      const chunk = stringField(envelope.data, "text");
+      if (chunk !== null) {
+        text += chunk;
+        options.onChunk?.(text);
+      }
+      continue;
+    }
+    if (envelope.event === "error" && failure === null) {
+      const payload = isRecord3(envelope.data) ? envelope.data : null;
+      failure = new MatrxRunError({
+        message: streamErrorText(payload) ?? "The agent run failed",
+        errorPayload: payload,
+        partialText: text
+      });
+      continue;
+    }
+    if (envelope.event !== "completion" || !isRecord3(envelope.data)) continue;
+    if (envelope.data.operation !== "user_request") continue;
+    completion = envelope.data;
+    const status = envelope.data.status;
+    if ((status === "failed" || status === "cancelled") && failure === null) {
+      const result = isRecord3(envelope.data.result) ? envelope.data.result : null;
+      failure = new MatrxRunError({
+        message: stringField(result, "error") ?? stringField(result, "user_message") ?? `The agent run ${status}`,
+        completionStatus: status,
+        partialText: text
+      });
+    }
+  }
+  if (failure) throw failure;
+  if (!text && completion) {
+    const result = completion.result;
+    const output = stringField(result, "output");
+    if (output !== null) text = output;
+  }
+  return {
+    text,
+    requestId: handle.requestId,
+    conversationId: handle.conversationId,
+    completion
+  };
+}
+
+// src/core/tools.ts
+function submitAgentToolResults(transport, conversationId, results, options = {}) {
+  return requestJson(
+    transport,
+    `/ai/conversations/${encodePathSegment(conversationId)}/tool_results`,
+    {
+      method: "POST",
+      body: {
+        results,
+        ...options.instanceId !== void 0 ? { instance_id: options.instanceId } : {}
+      },
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+}
+function listConversationPendingToolCalls(transport, conversationId, options = {}) {
+  return requestJson(
+    transport,
+    `/ai/conversations/${encodePathSegment(conversationId)}/pending_calls`,
+    {
+      method: "GET",
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+}
+function listUserPendingToolCalls(transport, options = {}) {
+  const query = buildQuery(
+    options.instanceId !== void 0 ? { instance_id: options.instanceId } : {}
+  );
+  return requestJson(
+    transport,
+    `/ai/user/pending_calls${query}`,
+    {
+      method: "GET",
+      ...options.signal ? { signal: options.signal } : {}
+    }
+  );
+}
+
+// src/core/endpoints.ts
+var ENDPOINTS = {
+  /** AI endpoints — chat, agents, conversations */
+  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.
+     */
+    manual: "/ai/manual",
+    /** @deprecated Use `ENDPOINTS.ai.manual`. Kept for one migration cycle. */
+    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.
+     */
+    agentStart: (agentId) => `/ai/agents/${agentId}`,
+    /**
+     * 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.
+     */
+    mandateStart: (mandateKey) => `/ai/mandates/${mandateKey}`,
+    /**
+     * POST — Continue any existing conversation (Guest OK)
+     * POST /ai/conversations/{conversationId}
+     * Conversation ID in URL. Just send user_input in the body.
+     */
+    conversationContinue: (conversationId) => `/ai/conversations/${conversationId}`,
+    /**
+     * 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.
+     */
+    conversationWarm: (conversationId) => `/ai/conversations/${conversationId}/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" }`
+     */
+    agentWarm: (agentId) => `/ai/agents/${agentId}/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.
+     */
+    promptStart: (promptId) => `/ai/prompts/${promptId}`,
+    /**
+     * POST — Pre-warm a prompt's server cache. No auth. (public endpoint)
+     * POST /ai/prompts/{promptId}/warm
+     * Optional body: `{ source: string | null }`
+     */
+    promptWarm: (promptId) => `/ai/prompts/${promptId}/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.
+     */
+    agentBlocksStart: (agentId) => `/ai/agents-blocks/${agentId}`,
+    /**
+     * POST — Pre-warm a block-streaming agent (Public)
+     * POST /ai/agents-blocks/{agentId}/warm
+     * Optional body: `{ source: "prompt" | "builtin" | "prompt_version" | "builtin_version" }`
+     */
+    agentBlocksWarm: (agentId) => `/ai/agents-blocks/${agentId}/warm`,
+    /** POST — Cancel a running request by request_id (Authenticated) */
+    cancel: (requestId) => `/ai/cancel/${requestId}`
+  },
+  /** Block processing test endpoints — Guest OK */
+  blockProcessing: {
+    /** POST — Process raw text/markdown → structured blocks (JSON response) */
+    process: "/utilities/block-processing/process",
+    /** POST — Process raw text/markdown → block events (NDJSON stream, simulates live agent) */
+    processStream: "/utilities/block-processing/process/stream"
+  },
+  /** CX-data endpoints — conversation/message data (Authenticated) */
+  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.
+     */
+    contextState: (conversationId) => `/cx/conversations/${conversationId}/context-state`
+  },
+  /** CMS server work — authenticated. CMS row CRUD stays direct-to-Supabase. */
+  cms: {
+    /** POST — Canonical matrx-content-guard validation before CMS writes. */
+    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.
+     */
+    approveException: (exceptionId) => `/cms/exceptions/${encodeURIComponent(exceptionId)}/approve`,
+    rejectException: (exceptionId) => `/cms/exceptions/${encodeURIComponent(exceptionId)}/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.
+     */
+    publishCheck: "/cms/publish-check"
+  },
+  /** Tool testing endpoints — Authenticated */
+  tools: {
+    /** GET — List available tools (?category=) */
+    testList: "/tools/test/list",
+    /** GET — Get tool details by name */
+    testDetail: (toolName) => `/tools/test/${toolName}`,
+    /** POST — Create/reuse test session */
+    testSession: "/tools/test/session",
+    /** POST — Execute tool test with streaming */
+    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`.
+     */
+    screenRun: "/tools/screen-run"
+  },
+  /** Scraper endpoints — Authenticated */
+  scraper: {
+    /** POST — Quick scrape URLs */
+    quickScrape: "/scraper/quick-scrape",
+    /** POST — Search keywords */
+    search: "/scraper/search",
+    /** POST — Search and scrape combined */
+    searchAndScrape: "/scraper/search-and-scrape",
+    /** POST — Search and scrape with limits */
+    searchAndScrapeLimited: "/scraper/search-and-scrape-limited"
+  },
+  /** Utility endpoints — Guest OK */
+  utilities: {
+    /** @deprecated Use ENDPOINTS.pdf.extractText instead */
+    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.
+   */
+  pdf: {
+    // ── Lifecycle ─────────────────────────────────────────────────────────
+    /**
+     * 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.
+     */
+    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). */
+    extractText: "/utilities/pdf/extract-text",
+    /** POST — Batch extraction with NDJSON streaming (saves to DB + storage). */
+    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 }`.
+     */
+    fromImages: "/utilities/pdf/from-images",
+    // ── New `MediaRef`-based JSON endpoints (matrx-utils) ─────────────────
+    /** POST — Text extraction from a remote source (MediaRef / url; NDJSON streaming,
+     * same events as `extractText`). Consume via `streamPdfExtractTextRemote`. */
+    extractTextRemote: "/utilities/pdf/extract-text-remote",
+    /** POST — Table extraction. Returns `PdfResult`. */
+    extractTables: "/utilities/pdf/extract-tables",
+    /** POST — Extract pages into a new PDF. Returns PDF blob. */
+    extractPages: "/utilities/pdf/extract-pages",
+    /** POST — Crop pages (with `crop_box`). Returns PDF blob. */
+    cropPages: "/utilities/pdf/crop-pages",
+    /** POST — Rotate pages. Returns PDF blob. */
+    rotatePages: "/utilities/pdf/rotate-pages",
+    /** POST — Delete pages. Returns PDF blob. */
+    deletePages: "/utilities/pdf/delete-pages",
+    /** POST — Merge multiple PDFs. Returns PDF blob. */
+    merge: "/utilities/pdf/merge",
+    /** POST — Split PDF into parts (`parts` or `max_pages_per_part`). Returns ZIP blob. */
+    split: "/utilities/pdf/split",
+    // ── AI pipelines (streaming JSONL) ────────────────────────────────────
+    /** POST — Process a PDF with AI agents (single-pass / chunk / reassembly). Streams JSONL. */
+    processWithAi: "/utilities/pdf/process-with-ai",
+    /** POST — Full pipeline: extract → chunk → AI → reassembly. Streams JSONL with `PdfPipelineOptions`. */
+    fullPipeline: "/utilities/pdf/full-pipeline",
+    /** POST — AI content cleaning on an already-extracted document (NDJSON streaming). */
+    cleanContent: (docId) => `/utilities/pdf/clean-content/${docId}`,
+    // ── Document management (server-side; prefer direct Supabase reads) ──
+    /** @deprecated — Read `processed_documents` directly from Supabase with metadata-only projection. */
+    documents: "/utilities/pdf/documents",
+    /** @deprecated — Read `processed_documents` directly from Supabase. */
+    document: (docId) => `/utilities/pdf/documents/${docId}`,
+    // ── Phase 2 — render & advanced page ops ──────────────────────────────
+    /** POST — Render one page to an image blob (PNG/JPEG/WebP/TIFF). */
+    renderPage: "/utilities/pdf/render-page",
+    /** POST — Render every page; returns a ZIP of per-page images. */
+    renderAll: "/utilities/pdf/render-all",
+    /** POST — Cover thumbnail at `max_side` px. */
+    renderThumbnail: "/utilities/pdf/render-thumbnail",
+    /** POST — Reorder pages by `new_order`. Returns PDF blob. */
+    reorderPages: "/utilities/pdf/reorder-pages",
+    /** POST — Insert pages from `source_*` into target. Returns PDF blob. */
+    insertPages: "/utilities/pdf/insert-pages",
+    /** POST — Duplicate pages inline (`count` copies). Returns PDF blob. */
+    duplicatePages: "/utilities/pdf/duplicate-pages",
+    /** GET — Studio preset catalog. Returns `PdfStudioCatalog`. */
+    studioPresets: "/utilities/pdf/studio/presets",
+    /** POST — Studio dispatcher; image blob or ZIP depending on preset. */
+    studioRender: "/utilities/pdf/studio/render",
+    // ── Phase 3 — layout analysis ─────────────────────────────────────────
+    /** POST — Detect headers / footers / watermarks / recurring side notes. Returns `RepeatedRegionsReport`. */
+    detectRepeatedRegions: "/utilities/pdf/detect-repeated-regions",
+    /** POST — Detect + strip repeated regions from per-page text. Returns `StripRepeatedRegionsResultSchema`. */
+    stripRepeatedRegions: "/utilities/pdf/strip-repeated-regions",
+    /** POST — Classify every page (cover / TOC / body / exhibit / signature / billing / ...). Returns `LayoutClassificationReport`. */
+    classifyPages: "/utilities/pdf/classify-pages",
+    /** POST — Multi-column → linear reading order. Returns `ReadingOrderReport`. */
+    extractReadingOrder: "/utilities/pdf/extract-reading-order",
+    // ── Phase 4 — redaction & privacy ─────────────────────────────────────
+    /** GET — Builtin redaction pattern catalog (SSN / email / phone / MRN / ...). */
+    redactPatterns: "/utilities/pdf/redact/patterns",
+    /** POST — Redact one or more page-anchored rectangles. PDF blob or persisted JSON. */
+    redactRegions: "/utilities/pdf/redact-regions",
+    /** POST — Redact every regex match (builtin id or raw pattern). PDF blob or persisted JSON. */
+    redactPattern: "/utilities/pdf/redact-pattern",
+    /** POST — Detect repeated regions then redact selected/all. PDF blob or persisted JSON. */
+    redactRepeatedRegions: "/utilities/pdf/redact-repeated-regions",
+    /** POST — Wipe /Info + XMP metadata + thumbnails. */
+    stripMetadata: "/utilities/pdf/strip-metadata",
+    /** POST — Granular composite scrub (metadata / attachments / JS / flatten). */
+    scrub: "/utilities/pdf/scrub",
+    /** POST — Bake annotations + widgets into page content. */
+    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.
+   */
+  pageExtraction: {
+    /** POST — Run extraction across pages (NDJSON streaming, per-page events). */
+    runStream: "/page-extraction/runs/stream",
+    /** POST — Retry one failed page-run (replaces its results). */
+    retryPageRun: (pageRunId) => `/page-extraction/page-runs/${pageRunId}/retry`,
+    /** POST — Cancel an in-flight run. */
+    cancelRun: (runId) => `/page-extraction/runs/${runId}/cancel`
+  },
+  /** Test/admin endpoints — Admin only */
+  tests: {
+    /** GET/POST — Example endpoints */
+    examples: "/tests/examples",
+    /** GET — Stream text test */
+    streamText: "/tests/stream/text"
+  },
+  /** Media processing endpoints — Authenticated */
+  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"`.
+     */
+    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.
+     */
+    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.
+   */
+  contentProcessing: {
+    process: (cldFileId) => `/content-processing/${cldFileId}`
+  },
+  /**
+   * 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.
+   */
+  assets: {
+    /** POST — multipart upload + render preset variants. */
+    upload: "/assets",
+    /** GET — read the canonical Asset envelope for an upload's master file. */
+    detail: (fileId) => `/assets/${fileId}`,
+    /** PATCH — change sharing / metadata. */
+    patch: (fileId) => `/assets/${fileId}`,
+    /** POST — render more variants (idempotent). */
+    addVariants: (fileId) => `/assets/${fileId}/variants`,
+    /** GET — list every server-known preset. */
+    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.
+     */
+    forFile: (fileId) => `/files/${fileId}/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.
+     */
+    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.
+     */
+    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.
+     */
+    pdfCompress: "/assets/pdf-compress",
+    /** POST — multipart variant of {@link pdfCompress}. */
+    pdfCompressMultipart: "/assets/pdf-compress/multipart"
+  },
+  /** Health endpoints — Public (aligned with types/python-generated OpenAPI) */
+  health: {
+    /** GET — Basic health check */
+    check: "/health",
+    /** GET — Detailed health with component status */
+    detailed: "/health/detailed",
+    /** GET — Liveness (process up; no I/O) */
+    live: "/health/live",
+    /** GET — Readiness (deps initialized; use for deploy probes) */
+    ready: "/health/ready"
+  },
+  /** Research endpoints — Authenticated */
+  research: {
+    /** POST — Initialize research config */
+    init: "/research/init",
+    /** GET — List templates */
+    templatesList: "/research/templates/list",
+    /** POST — Create template */
+    templatesCreate: "/research/templates",
+    /** GET — Template detail */
+    templateDetail: (templateId) => `/research/templates/${templateId}`,
+    /** GET — Extension scrape queue */
+    extensionScrapeQueue: "/research/extension/scrape-queue",
+    /** GET — Research state / PATCH — Update config */
+    state: (projectId) => `/research/${projectId}`,
+    /** POST — Suggest setup */
+    suggest: (projectId) => `/research/${projectId}/suggest`,
+    /** POST — Run full pipeline (streaming) */
+    run: (projectId) => `/research/${projectId}/run`,
+    /** POST — Trigger search (streaming) */
+    search: (projectId) => `/research/${projectId}/search`,
+    /** POST — Trigger scrape (streaming) */
+    scrape: (projectId) => `/research/${projectId}/scrape`,
+    /** POST — Analyze all sources (streaming) */
+    analyzeAll: (projectId) => `/research/${projectId}/analyze-all`,
+    /** POST — Synthesize */
+    synthesize: (projectId) => `/research/${projectId}/synthesize`,
+    /** GET — Keywords */
+    keywords: (projectId) => `/research/${projectId}/keywords`,
+    /** GET — Sources */
+    sources: (projectId) => `/research/${projectId}/sources`,
+    /** GET — Tags */
+    tags: (projectId) => `/research/${projectId}/tags`,
+    /** GET/POST — Document */
+    document: (projectId) => `/research/${projectId}/document`,
+    /** GET — Costs */
+    costs: (projectId) => `/research/${projectId}/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.
+   */
+  actionRequests: {
+    /** POST — what the page draws. MUTATES NOTHING. */
+    open: "/action-requests/open",
+    /** POST — the answer. */
+    complete: "/action-requests/complete",
+    /** POST — "text me a new link". Rate-limited in the database. */
+    remint: "/action-requests/remint"
+  }
+};
+
+export { ENDPOINTS, MATRX_AI_API_VERSION_DEFAULT, MATRX_LIVE_STREAM_UNAVAILABLE, MATRX_RESUME_CONFLICT, MATRX_RUN_IN_PROGRESS, MATRX_UI_ONLY_BODY_FIELDS, MatrxRunError, RUN_OUTPUT_KINDS, RUN_STREAM_LIFETIME_BACKSTOP_MS, RUN_WAIT_KNOB_FEATURE, TERMINAL_MATRX_RUNTIME_STATUSES, V2_COVERED_AI_PATH_TEMPLATES, WARM_PATH, aiVersionPathOverrides, applyAiApiVersion, applyDesktopTargetToRequestBody, bareStatusSentence, buildMatrxRequestBody, buildMatrxRequestUrl, buildQuery, buildSafeRequestLog, cancelAgentRun, continueAgentConversation, continueEphemeralConversationStart, continueStoredConversationStart, createMatrxTransport, createProviderUsageReporter, createStreamReplayCursor, createWarmup, encodePathSegment, executeMatrxCall, fetchWithMatrxProtocolFallback, followRuntimeOperationEvents, followRuntimeOperationToEnd, followServerJob, followUnavailableRejoin, followWorkflowRunEvents, getRuntimeOperationStatus, getRuntimeOperationsByLink, honestTransportMessage, isBareTransportCode, isCoveredAiPath, isEmptyProviderUsage, isJobOutputKind, isLiveStreamUnavailable, isResumeConflict, isServerJobSettled, isV2Path, listConversationPendingToolCalls, listRuntimeOperationEvents, listUserPendingToolCalls, logApiTarget, mintMatrxConversationId, newEphemeralConversationStart, newStoredConversationStart, normalizeMatrxError, openMatrxStream, parseMatrxNdjsonResponse, pickServerJobOperation, preconnectServer, providerSessionFailureBody, providerSessionUsageBody, readConversationOrganizationId, readLiveRunRejoin, readLiveRunRequestId, readLiveStreamUnavailable, readMatrxErrorCode, readMatrxErrorCodeFromMessage, readMatrxJsonResponse, readStreamCursor, redactUrlForRequestLog, rejoinRuntimeOperation, reportProviderSessionFailure, reportProviderSessionUsage, requestJson, requestStream, resetPreconnectedForTests, resolveEndpointPath, resolveRunWaitWith, resumeAgentConversation, resumeOrRejoin, runAgentToCompletion, runJobLabel, runOutputKindFromModalities, runWaitKnobKey, runWaitTimeoutMessage, runtimeOperationRejoinPath, sendMatrxRequest, serverJobRejoinHandle, settleRunPickup, shouldReportMatrxCallError, startAgentRun, startMandateRun, streamErrorText, submitAgentToolResults, toRunHandle, toV1FallbackUrl, toV2Path, withRunOrganization };