@ai-matrx/agents 0.5.1 → 0.6.1

package/dist/matrx/index.d.ts

@@ -1,3 +1,5 @@
+import { CredentialsPort } from '@ai-matrx/data';
+import { ResilientFetchOptions } from '@ai-matrx/data/net';
 import { MatrxStreamEnvelope, MatrxNdjsonIssue, MatrxStreamEnvelopeObservation } from '../stream/ndjson.js';
 import { MatrxSseFrame } from '../stream/sse.js';
 
@@ -94,6 +96,300 @@ declare function extractMatrxErrorMessage(serverDetail: unknown): string | undef
  */
 declare function extractMatrxErrorCode(serverDetail: unknown): string | null;
 
+/**
+ * The AI API protocol-version policy — which version of the AI runtime a
+ * Matrx client talks to, and the v2 → v1 transport fallback (moved in from
+ * matrx-frontend `lib/api/ai-api-version.ts` + `call-api.ts::
+ * fetchWithV2Fallback` under C22; server truth
+ * `aidream/docs/runtime/V2_FRONTEND_MIGRATION.md`).
+ *
+ * Background: the Python backend exposes a `/v2` runtime-spine namespace that
+ * wraps the core AI request surfaces in a request-tracking envelope. Body,
+ * headers, and streaming response are BYTE-IDENTICAL to v1 — only the URL
+ * differs.
+ *
+ * ─── The one rule that keeps burning us ─────────────────────────────────────
+ * `/v2` is inserted at the FRONT of the in-app path, right before `/ai`:
+ *
+ *     /ai/agents/{id}  → /v2/ai/agents/{id}   ✅ correct
+ *     /ai/v2/agents/…                          ❌ WRONG (nested) — 404s
+ *
+ * `toV2Path` below is the ONLY place this transform is spelled out.
+ *
+ * ─── Scope: ONLY the covered surfaces have a v2 form ────────────────────────
+ * chat, manual, agents/{id}, conversations/{id} (+ singular aliases),
+ * prompts/{id}, mandates/{key}. EVERYTHING ELSE — cancel, warm, resume,
+ * fork-and-run, runtime operations, files … — has NO v2 route, and the server
+ * does NOT auto-downgrade (a `/v2` request to an uncovered surface is a plain
+ * 404). So the transform is a scoped allowlist, never a blanket prefix.
+ */
+
+type MatrxAiApiVersion = "v1" | "v2";
+/**
+ * The package-wide default AI API version — the production value every Matrx
+ * client runs unless its host deliberately overrides
+ * (`createMatrxTransport({ aiApiVersion })`).
+ */
+declare const MATRX_AI_API_VERSION_DEFAULT: MatrxAiApiVersion;
+/**
+ * The canonical v1 path TEMPLATES the v2 spine covers, `{param}` placeholders
+ * intact — for hosts that route through a template registry.
+ */
+declare const V2_COVERED_AI_PATH_TEMPLATES: readonly ["/ai/manual", "/ai/chat", "/ai/agents/{agent_id}", "/ai/agent/{agent_id}", "/ai/conversations/{conversation_id}", "/ai/conversation/{conversation_id}", "/ai/prompts/{prompt_id}", "/ai/mandates/{mandate_key}"];
+/**
+ * Insert `/v2` at the front of an in-app path. Idempotent, and prefix-aware:
+ * a legacy `/api/` compatibility prefix (stripped server-side) is preserved so
+ * `/api/ai/chat` → `/api/v2/ai/chat`.
+ */
+declare function toV2Path(path: string): string;
+/** Whether `path` (already interpolated) is one of the covered surfaces. */
+declare function isCoveredAiPath(path: string): boolean;
+/**
+ * Whether an in-app path (or a full URL whose path was built by `toV2Path`)
+ * targets the v2 namespace — the guard the downgrade fallback keys off.
+ */
+declare function isV2Path(pathOrUrl: string): boolean;
+/**
+ * The inverse of `toV2Path` — strip the `/v2` version segment so a transport
+ * failure of the v2 endpoint (network error, 404/405, 5xx BEFORE any stream
+ * content) can retry the identical request on the v1 route. Works on a bare
+ * path, an `/api`-prefixed path, or a full URL (the `/v2/ai/` shape is unique
+ * to the version namespace). Idempotent on non-v2 input.
+ */
+declare function toV1FallbackUrl(url: string): string;
+/**
+ * Apply the active AI API version to an ALREADY-INTERPOLATED in-app path.
+ *
+ * - Covered surface + v2  → `/v2` prefix inserted.
+ * - Anything else (or v1) → returned unchanged.
+ *
+ * Pass the in-app PATH only (no scheme/host); prepend the base URL afterward.
+ */
+declare function applyAiApiVersion(path: string, version: MatrxAiApiVersion): string;
+/** One v2 → v1 downgrade, surfaced to the host's diagnostics sink. */
+interface MatrxProtocolDowngrade {
+    /** The failed v2 URL. */
+    url: string;
+    /** Why the downgrade fired (thrown error text, or `HTTP <status>`). */
+    reason: string;
+    /** HTTP status when the trigger was a response (404/405/5xx). */
+    status?: number;
+}
+interface MatrxProtocolFallbackOptions extends ResilientFetchOptions {
+    /**
+     * Fired on every downgrade — a sustained stream of these means a v2 surface
+     * is unhealthy. The fallback also `console.warn`s unconditionally (parity
+     * with the original host pipeline) so the signal never disappears silently.
+     */
+    onDowngrade?: (downgrade: MatrxProtocolDowngrade) => void;
+}
+/**
+ * `resilientFetch` with the v2 → v1 transport fallback. Fires ONLY when a
+ * `/v2/ai/...` ENDPOINT itself fails — a network-layer throw (non-abort), a
+ * 404/405 (surface not on v2), or a 5xx — always BEFORE any stream content is
+ * consumed. Never on an application error (those fail identically on v1), and
+ * never on a caller abort (a user cancel must not be logged as a downgrade —
+ * that poisons the exact telemetry the rollout reads to judge v2 health).
+ */
+declare function fetchWithMatrxProtocolFallback(url: string, init: RequestInit, opts?: MatrxProtocolFallbackOptions): Promise<{
+    response: Response;
+}>;
+
+/**
+ * The PRODUCTION `MatrxTransport` — the full connection pipeline every Matrx
+ * host used to hand-roll, moved in under C22 (THE HARD PARTS LIVE IN THE
+ * PACKAGE). A host constructs it from identity alone:
+ *
+ * ```ts
+ * const transport = createMatrxTransport({
+ *   baseUrl: "https://server.app.matrxserver.com",
+ *   credentials,                       // CredentialsPort (@ai-matrx/data)
+ *   organizationId: () => activeOrgId, // omit for conversation-lane calls
+ * });
+ * ```
+ *
+ * Everything else is defaulted to the proven production values:
+ *
+ * - **timeouts** — connect 15s (for a non-streaming FastAPI handler this is
+ *   effectively time-to-response), total UNCAPPED (the port cannot tell a JSON
+ *   call from a long-lived NDJSON/SSE stream; the connect timeout is the JSON
+ *   guard), via `@ai-matrx/data/net`'s `resilientFetch`;
+ * - **protocol** — the AI API version transform (`applyAiApiVersion`, default
+ *   v2) + the loud v2 → v1 transport fallback (`./protocol`);
+ * - **credentials** — read fresh from the injected `CredentialsPort` on EVERY
+ *   call, so a token refresh mid-run is picked up; mapped to headers by the
+ *   ONE `credentialToHeaders`;
+ * - **org context** — the fail-closed `X-Organization-Id` binding
+ *   (`./org-context`): configured lanes REQUIRE an org and refuse before the
+ *   wire; unconfigured lanes (conversation-scoped calls, which carry org in
+ *   the body) send none;
+ * - **error classification** — every failure normalizes through
+ *   `normalizeMatrxError` into the ONE `MatrxCallError` envelope;
+ * - **diagnostics** — a typed sink the host wires to its capture/telemetry
+ *   (`onRequest`, `onError`, `onProtocolDowngrade`); wiring it is optional,
+ *   the transport works silently without it.
+ *
+ * Header merge order is part of the port contract: wire headers first
+ * (`Content-Type` / `Accept` / `Last-Event-ID` — the package's), then
+ * credentials, then resolver policy headers, then the org header. Policy
+ * headers never carry `Content-Type` — the wire owns it, and a policy
+ * `Content-Type` merged over a GET SSE call would corrupt the wire, so the
+ * factory strips it defensively.
+ */
+
+/**
+ * The ONE classified error shape for Matrx client calls — the envelope hosts
+ * branch on instead of string-matching exceptions. Structurally compatible
+ * with matrx-frontend's `ApiCallError` by design.
+ */
+interface MatrxCallError {
+    type: "auth_error" | "network_error" | "http_error" | "validation_error" | "abort_error" | "unknown";
+    message: string;
+    /** HTTP status code, if applicable. */
+    status?: number;
+    /** Raw error detail from the server (the parsed error body). */
+    serverDetail?: unknown;
+    /** Machine code preserved through normalization (server `code`, org-context code, …). */
+    code?: string;
+    /** Original exception identity for diagnostics. */
+    name?: string;
+    /** Original exception stack. */
+    stack?: string;
+}
+/**
+ * Classify any failure thrown by a package client call — `MatrxApiError`,
+ * a `NetError` from the resilience layer, an org-context refusal, an abort —
+ * into the `MatrxCallError` envelope. Never throws.
+ */
+declare function normalizeMatrxError(err: unknown): MatrxCallError;
+/**
+ * A fully-resolved connection target for one call: where to send it and which
+ * policy headers ride ON TOP of the wire + credential headers.
+ */
+interface MatrxTransportTarget {
+    /** Fully-qualified base URL, no trailing slash. */
+    baseUrl: string;
+    /**
+     * Extra policy headers for this target (e.g. a resolver that carries its own
+     * credential headers). `Content-Type` is stripped — the wire owns it.
+     */
+    policyHeaders?: Record<string, string>;
+    /** Routing channel label surfaced to `onRequest` telemetry. */
+    channel?: string;
+}
+/** Context handed to every diagnostics callback. */
+interface MatrxRequestInfo {
+    /** The final URL (base + version-transformed path). */
+    url: string;
+    method: "GET" | "POST";
+    /** The server-relative path as the package requested it. */
+    path: string;
+    /** The resolved routing channel (default "default"). */
+    channel: string;
+    /** The transport's call-site label (default "matrxTransport"). */
+    source: string;
+}
+/**
+ * The typed diagnostics sink — the host wires these to its telemetry/capture
+ * systems; all optional, and the transport is fully functional without them.
+ */
+interface MatrxTransportDiagnostics {
+    /** Fired at the last pre-fetch moment of every call. */
+    onRequest?: (info: MatrxRequestInfo) => void;
+    /**
+     * Fired for every thrown network failure and every non-2xx response not
+     * listed in `expectedErrorStatuses`, with the classified envelope.
+     */
+    onError?: (error: MatrxCallError, info: MatrxRequestInfo) => void;
+    /** Fired on every v2 → v1 protocol downgrade. */
+    onProtocolDowngrade?: (downgrade: MatrxProtocolDowngrade) => void;
+}
+interface CreateMatrxTransportOptions {
+    /** Fixed base URL, no trailing slash. Exactly one of `baseUrl` / `resolveTarget`. */
+    baseUrl?: string;
+    /**
+     * Per-call target resolver — for hosts whose base URL / policy headers are
+     * dynamic (server toggles, sandbox overrides, conversation channels).
+     * Resolution runs fresh on EVERY call. May throw to refuse a call loudly.
+     */
+    resolveTarget?: () => MatrxTransportTarget;
+    /**
+     * The credential source (`@ai-matrx/data`), read fresh per call so token
+     * refreshes are picked up mid-run. Omit only when the resolver's
+     * `policyHeaders` already carry the credentials.
+     */
+    credentials?: CredentialsPort;
+    /**
+     * The org-context binding. When configured, every call REQUIRES a valid org
+     * (fail-closed `organization_context_required` before the wire) and carries
+     * `X-Organization-Id`. Omit for conversation-lane transports, which send the
+     * org in the body only.
+     */
+    organizationId?: string | (() => string | null | undefined);
+    /** AI API protocol version (value or per-call getter). Default `"v2"`. */
+    aiApiVersion?: MatrxAiApiVersion | (() => MatrxAiApiVersion);
+    /** Max ms request start → response headers. Default 15_000. */
+    connectTimeoutMs?: number;
+    /**
+     * Max ms for the whole handshake. Default `null` (uncapped) — the port
+     * cannot tell a JSON call from a long-lived stream, and capping would kill
+     * long streams; the connect timeout is the real JSON guard.
+     */
+    totalTimeoutMs?: number | null;
+    /**
+     * HTTP failures this transport's call class fully handles as expected
+     * domain outcomes (e.g. 404 on runtime-operation identify). They still
+     * reach the package client (which maps them to typed results) but are not
+     * reported through `onError`.
+     */
+    expectedErrorStatuses?: readonly number[];
+    /** Short call-site label surfaced on `MatrxRequestInfo` (default "matrxTransport"). */
+    source?: string;
+    diagnostics?: MatrxTransportDiagnostics;
+}
+/**
+ * Build the production `MatrxTransport`. See the module doc for the pipeline;
+ * every knob defaults to the proven production value.
+ */
+declare function createMatrxTransport(options: CreateMatrxTransportOptions): MatrxTransport;
+
+/**
+ * The fail-closed organization-context kernel — ONE implementation for every
+ * Matrx client transport (moved in from matrx-frontend
+ * `lib/api/organization-context.ts` verbatim under C22; the host module is now
+ * a re-export of this one).
+ *
+ * Transports resolve their authoritative organization first, then use these
+ * functions to bind that exact value without guessing or defaulting. The
+ * server never manufactures an org (it 422s a blank one), so the client
+ * refuses before the wire: a missing or malformed org id throws
+ * `OrganizationContextError` instead of sending a request that cannot succeed.
+ */
+type OrganizationContextErrorCode = "organization_context_required" | "organization_context_invalid" | "organization_context_mismatch";
+declare class OrganizationContextError extends Error {
+    readonly code: OrganizationContextErrorCode;
+    constructor(code: OrganizationContextErrorCode, message: string);
+}
+/**
+ * Normalize and validate the effective organization id for a request. The
+ * override (an explicit per-call value) beats the selected context value.
+ * Throws `organization_context_required` when neither is present and
+ * `organization_context_invalid` when the candidate is not a UUID.
+ */
+declare function requireOrganizationContext(selectedOrganizationId: string | null | undefined, overrideOrganizationId?: string): string;
+/**
+ * Bind `X-Organization-Id` onto a header bag. A pre-existing org header that
+ * disagrees with the context org is a `organization_context_mismatch` error —
+ * never silently overwritten in either direction.
+ */
+declare function applyOrganizationContextHeader(headers: Record<string, string>, organizationId: string): Record<string, string>;
+/**
+ * Assert that an `organization_id` query parameter (when present) matches the
+ * request context organization — the query string must never smuggle a
+ * different org past the header binding.
+ */
+declare function assertQueryOrganizationMatchesContext(queryParams: Record<string, string | number | boolean> | undefined, organizationId: string): void;
+
 /**
  * The conversation-start contract — client-minted `conversation_id`, `is_new`,
  * `store` — typed exactly per the cross-repo System of Record
@@ -585,6 +881,54 @@ interface FollowRuntimeOperationOptions {
  * retry policy).
  */
 declare function followRuntimeOperationEvents(transport: MatrxTransport, executionId: string, options?: FollowRuntimeOperationOptions): AsyncGenerator<MatrxOperationFollowEvent, void, undefined>;
+interface FollowRuntimeOperationToEndOptions {
+    /** Resume cursor — the operation view's `last_event_seq` (0 = from start). */
+    lastEventSeq?: number;
+    /** Caller teardown — aborting resolves with `ended: false`. */
+    signal?: AbortSignal;
+    /**
+     * The server pings every ~15s, so a wire that is open but silent past this
+     * is dead (buffering proxy, idle-killed connection) — abort the attempt and
+     * retry rather than hanging forever. Default 45_000.
+     */
+    stallTimeoutMs?: number;
+    /**
+     * Consecutive failed attempts before giving up. A single-server deployment
+     * deliberately drains for 60s, then starts a new container — the default
+     * budget (60 × 2s) keeps following for ~three minutes so the runtime ledger
+     * can bridge that handoff. ANY parsed frame resets the budget. Default 60.
+     */
+    reconnectLimit?: number;
+    /** Delay between attempts. Default 2_000. */
+    reconnectDelayMs?: number;
+    /** Fired per durable spine event (lifecycle transitions + notes). */
+    onEvent: (event: MatrxRuntimeOperationEvent, seq: number | null) => void;
+    /** A failed attempt (never silently swallowed when provided). */
+    onAttemptError?: (error: unknown) => void;
+    /** A frame whose payload failed to parse (the ledger heals gaps on reconnect). */
+    onMalformedFrame?: (frame: MatrxSseFrame, error: unknown) => void;
+}
+interface FollowRuntimeOperationToEndResult {
+    /** True when the server sent the terminal `end` frame. */
+    ended: boolean;
+    /** The root status carried on the `end` frame (when `ended`). */
+    status: MatrxRuntimeExecutionStatus | null;
+}
+/**
+ * Follow an operation's lifecycle stream TO ITS END — the full production
+ * reconnect policy over `followRuntimeOperationEvents`: replay-then-follow
+ * with bounded reconnects, a stall watchdog, and durable `Last-Event-ID`
+ * cursor advancement across attempts.
+ *
+ * Resolves `{ended: true, status}` on the server's `end` frame (the operation
+ * settled); `{ended: false}` when the caller aborted or every reconnect
+ * attempt failed. A WAITING_INPUT park keeps the stream open by design — a
+ * resume re-attaches to the same execution and its events continue arriving
+ * on the same cursor. Any parsed frame — comment heartbeats included —
+ * proves the wire is alive and resets both the stall timer and the retry
+ * budget.
+ */
+declare function followRuntimeOperationToEnd(transport: MatrxTransport, executionId: string, options: FollowRuntimeOperationToEndOptions): Promise<FollowRuntimeOperationToEndResult>;
 /**
  * Rejoin the ORIGINAL NDJSON response while its detached task is still alive:
  * `POST /runtime/operations/{request_id}/rejoin`. Replays the response from
@@ -688,4 +1032,4 @@ declare function listUserPendingToolCalls(transport: MatrxTransport, options?: {
     signal?: AbortSignal;
 }): Promise<MatrxPendingCallSummary[]>;
 
-export { type FollowRuntimeOperationOptions, type MatrxAgentStartRequest, MatrxApiError, type MatrxCancelResponse, type MatrxChatMessage, type MatrxClientToolResult, type MatrxCompletedRun, type MatrxContextAnchor, type MatrxConversationContinueRequest, type MatrxConversationResumeRequest, type MatrxConversationStart, type MatrxEphemeralConversation, type MatrxJsonObject, type MatrxJsonValue, type MatrxOperationEventsPage, type MatrxOperationFollowEvent, type MatrxOperationStatusResponse, type MatrxOperationsByLinkResponse, type MatrxPendingCallSummary, type MatrxRequestScope, MatrxRunError, type MatrxRunHandle, type MatrxRuntimeExecutionStatus, type MatrxRuntimeOperationEvent, type MatrxRuntimeOperationView, type MatrxStoredConversationContinue, type MatrxStoredConversationCreate, type MatrxStreamCallOptions, type MatrxToolResultsResponse, type MatrxTransport, type MatrxTransportRequest, type MatrxTurnFields, type RunAgentToCompletionOptions, TERMINAL_MATRX_RUNTIME_STATUSES, cancelAgentRun, continueAgentConversation, continueEphemeralConversationStart, continueStoredConversationStart, extractMatrxErrorCode, extractMatrxErrorMessage, followRuntimeOperationEvents, getRuntimeOperationStatus, getRuntimeOperationsByLink, listConversationPendingToolCalls, listRuntimeOperationEvents, listUserPendingToolCalls, mintMatrxConversationId, newEphemeralConversationStart, newStoredConversationStart, rejoinRuntimeOperation, resumeAgentConversation, runAgentToCompletion, startAgentRun, submitAgentToolResults };
+export { type CreateMatrxTransportOptions, type FollowRuntimeOperationOptions, type FollowRuntimeOperationToEndOptions, type FollowRuntimeOperationToEndResult, MATRX_AI_API_VERSION_DEFAULT, type MatrxAgentStartRequest, type MatrxAiApiVersion, MatrxApiError, type MatrxCallError, type MatrxCancelResponse, type MatrxChatMessage, type MatrxClientToolResult, type MatrxCompletedRun, type MatrxContextAnchor, type MatrxConversationContinueRequest, type MatrxConversationResumeRequest, type MatrxConversationStart, type MatrxEphemeralConversation, type MatrxJsonObject, type MatrxJsonValue, type MatrxOperationEventsPage, type MatrxOperationFollowEvent, type MatrxOperationStatusResponse, type MatrxOperationsByLinkResponse, type MatrxPendingCallSummary, type MatrxProtocolDowngrade, type MatrxProtocolFallbackOptions, type MatrxRequestInfo, type MatrxRequestScope, MatrxRunError, type MatrxRunHandle, type MatrxRuntimeExecutionStatus, type MatrxRuntimeOperationEvent, type MatrxRuntimeOperationView, type MatrxStoredConversationContinue, type MatrxStoredConversationCreate, type MatrxStreamCallOptions, type MatrxToolResultsResponse, type MatrxTransport, type MatrxTransportDiagnostics, type MatrxTransportRequest, type MatrxTransportTarget, type MatrxTurnFields, OrganizationContextError, type OrganizationContextErrorCode, type RunAgentToCompletionOptions, TERMINAL_MATRX_RUNTIME_STATUSES, V2_COVERED_AI_PATH_TEMPLATES, applyAiApiVersion, applyOrganizationContextHeader, assertQueryOrganizationMatchesContext, cancelAgentRun, continueAgentConversation, continueEphemeralConversationStart, continueStoredConversationStart, createMatrxTransport, extractMatrxErrorCode, extractMatrxErrorMessage, fetchWithMatrxProtocolFallback, followRuntimeOperationEvents, followRuntimeOperationToEnd, getRuntimeOperationStatus, getRuntimeOperationsByLink, isCoveredAiPath, isV2Path, listConversationPendingToolCalls, listRuntimeOperationEvents, listUserPendingToolCalls, mintMatrxConversationId, newEphemeralConversationStart, newStoredConversationStart, normalizeMatrxError, rejoinRuntimeOperation, requireOrganizationContext, resumeAgentConversation, runAgentToCompletion, startAgentRun, submitAgentToolResults, toV1FallbackUrl, toV2Path };