@ai-matrx/agents 0.3.0 → 0.5.1

package/dist/matrx/index.d.cts

@@ -0,0 +1,691 @@
+import { MatrxStreamEnvelope, MatrxNdjsonIssue, MatrxStreamEnvelopeObservation } from '../stream/ndjson.cjs';
+import { MatrxSseFrame } from '../stream/sse.cjs';
+
+/**
+ * `@ai-matrx/agents/matrx` — the Matrx transport port.
+ *
+ * The ONE seam between this package's wire semantics and a host's connection
+ * policy. This package owns WHAT is said to the AI Matrx server — paths,
+ * methods, JSON bodies, streaming Accept headers, the `Last-Event-ID` cursor
+ * header — and the host owns HOW the connection is made:
+ *
+ * - base-URL / backend-channel resolution (global, sandbox override, local
+ *   engine, EC2-dedicated — whatever ladder the host runs);
+ * - credentials (Supabase JWT `Authorization: Bearer`, guest
+ *   `X-Fingerprint-ID`, or the API-key lane) — NEVER implemented here;
+ * - the `X-Organization-Id` context header;
+ * - retry policy, network-level timeouts, and diagnostics capture.
+ *
+ * A host implements the port in a few lines:
+ *
+ * ```ts
+ * const transport: MatrxTransport = {
+ *   fetch: (path, init) =>
+ *     fetch(`${baseUrl}${path}`, {
+ *       ...init,
+ *       headers: { ...init.headers, ...authHeaders() },
+ *     }),
+ * };
+ * ```
+ *
+ * The port is deliberately structural and `fetch`-shaped so `@ai-matrx/data`'s
+ * `/api` transport can implement it without importing this package.
+ */
+/**
+ * The request this package hands the port. A strict subset of `RequestInit`,
+ * so a host can spread it straight into `fetch`.
+ */
+interface MatrxTransportRequest {
+    method: "GET" | "POST";
+    /**
+     * Wire-semantic headers the CALL requires (`Content-Type`, `Accept`,
+     * `Last-Event-ID`). The host merges its policy headers (auth, org) on top;
+     * it must not drop these.
+     */
+    headers: Record<string, string>;
+    /** Pre-serialized JSON body, present on POST calls that carry one. */
+    body?: string;
+    /** Caller cancellation. The host must wire it to the underlying fetch. */
+    signal?: AbortSignal;
+}
+/**
+ * The transport port. `path` is server-relative and always starts with `/`
+ * (`/ai/...`, `/runtime/...`); the host prepends its resolved base URL.
+ */
+interface MatrxTransport {
+    fetch(path: string, init: MatrxTransportRequest): Promise<Response>;
+}
+/**
+ * A non-2xx response from the Matrx API, with the server's structured error
+ * body preserved and its richest human-readable message extracted.
+ */
+declare class MatrxApiError extends Error {
+    readonly name = "MatrxApiError";
+    /** HTTP status of the failed response. */
+    readonly status: number;
+    /** Machine code from the server body (`code`, or `detail.code`), when present. */
+    readonly code: string | null;
+    /** The parsed server error body, verbatim (undefined when unparsable). */
+    readonly serverDetail: unknown;
+    /** The request path the failure came from (server-relative). */
+    readonly path: string;
+    constructor(args: {
+        status: number;
+        path: string;
+        serverDetail?: unknown;
+        message?: string;
+    });
+}
+/**
+ * Extract the richest human-readable message from a Matrx/FastAPI error body.
+ *
+ * aidream 4xx validation errors look like
+ * `{ error, user_message, details: [{ field, message, help }] }`; hand-raised
+ * HTTPExceptions carry `{ detail: { code, message } }`; FastAPI's defaults are
+ * `{ detail: string | [{ msg }] }`. Preference order: `user_message` →
+ * `message` → joined `details[].message` → `detail.message` →
+ * `detail` string → joined `detail[].msg`. Returns undefined for
+ * unrecognized bodies so callers fall back to the bare status line.
+ */
+declare function extractMatrxErrorMessage(serverDetail: unknown): string | undefined;
+/**
+ * Extract the machine error code from a Matrx error body: top-level `code`,
+ * else `detail.code` (the hand-raised HTTPException shape). Null when absent.
+ */
+declare function extractMatrxErrorCode(serverDetail: unknown): string | null;
+
+/**
+ * The conversation-start contract — client-minted `conversation_id`, `is_new`,
+ * `store` — typed exactly per the cross-repo System of Record
+ * (`common-docs/systems/agents/conversation-start-contract/FEATURE.md`;
+ * server truth `aidream/services/conversation_context/scope.py::
+ * ConversationStartRequest`).
+ *
+ * Every request that STARTS a conversation sends all three fields, no
+ * defaults:
+ *
+ * | `is_new` | `store` | Result                                                   |
+ * |----------|---------|----------------------------------------------------------|
+ * | true     | true    | Create the row with the caller's id — 409 if it exists   |
+ * | true     | false   | No row. The id is correlation only (ephemeral run)       |
+ * | false    | true    | Continue it — 404 if the caller doesn't own it           |
+ * | false    | false   | Ephemeral run on a known id; nothing read, nothing written |
+ *
+ * `store` is the ONLY ephemeral signal; `is_new` is the caller's assertion
+ * about the id, never a persistence switch. `prior_messages` (the client-owned
+ * transcript of an ephemeral multi-turn run) is only valid with
+ * `store: false` — the union below makes the invalid combination
+ * unrepresentable, mirroring the server's 422.
+ *
+ * Continue routes (`POST /ai/conversations/{id}`) take the id from the path
+ * and do not carry this triple.
+ */
+/** Recursive JSON value — the package's honest type for free-form wire bags. */
+type MatrxJsonValue = string | number | boolean | null | MatrxJsonValue[] | {
+    [key: string]: MatrxJsonValue;
+};
+/** A JSON object on the wire. */
+type MatrxJsonObject = {
+    [key: string]: MatrxJsonValue;
+};
+/**
+ * One LLM message on the request wire — `prior_messages` entries for
+ * stateless multi-turn runs. Mirrors aidream's `ChatMessageInput`
+ * (`aidream/schemas/messages.py`, `extra="allow"` — additional provider
+ * fields round-trip untouched).
+ */
+interface MatrxChatMessage {
+    role: string;
+    content?: string | MatrxJsonValue[] | null;
+    name?: string | null;
+    tool_call_id?: string | null;
+    tool_calls?: MatrxJsonObject[] | null;
+    [extra: string]: MatrxJsonValue | undefined;
+}
+/** `is_new: true, store: true` — create the row with the caller's id. */
+interface MatrxStoredConversationCreate {
+    conversation_id: string;
+    is_new: true;
+    store: true;
+}
+/** `is_new: false, store: true` — continue an owned stored conversation via a start route. */
+interface MatrxStoredConversationContinue {
+    conversation_id: string;
+    is_new: false;
+    store: true;
+}
+/**
+ * `store: false` — ephemeral: nothing read, nothing written; the id is the
+ * caller's correlation handle. This is the ONLY member that may carry
+ * `prior_messages` (the server 422s a client transcript on a stored run).
+ */
+interface MatrxEphemeralConversation {
+    conversation_id: string;
+    is_new: boolean;
+    store: false;
+    prior_messages?: MatrxChatMessage[];
+}
+/** The full conversation-start triple, one member per contract cell. */
+type MatrxConversationStart = MatrxStoredConversationCreate | MatrxStoredConversationContinue | MatrxEphemeralConversation;
+/** Mint a fresh client-side conversation id (the contract requires the CLIENT to mint it). */
+declare function mintMatrxConversationId(): string;
+/** Start a NEW stored conversation (`is_new: true, store: true`). */
+declare function newStoredConversationStart(conversationId?: string): MatrxStoredConversationCreate;
+/**
+ * Continue an EXISTING stored conversation through a start route
+ * (`is_new: false, store: true` — 404 when the caller doesn't own the id).
+ * Prefer `continueAgentConversation` (the dedicated continue route) for
+ * ordinary follow-up turns.
+ */
+declare function continueStoredConversationStart(conversationId: string): MatrxStoredConversationContinue;
+/**
+ * Start a NEW ephemeral run (`is_new: true, store: false`) — a freshly minted
+ * correlation id, nothing persisted.
+ */
+declare function newEphemeralConversationStart(conversationId?: string): MatrxEphemeralConversation;
+/**
+ * Continue an ephemeral multi-turn run (`is_new: false, store: false`): the
+ * CLIENT owns the transcript and replays it as `prior_messages` (ordered
+ * oldest-first) because the server wrote no rows to rebuild from. The server
+ * still owns the agent definition, model, tools, and system prompt.
+ */
+declare function continueEphemeralConversationStart(conversationId: string, priorMessages: MatrxChatMessage[]): MatrxEphemeralConversation;
+
+/**
+ * Internal request plumbing for `@ai-matrx/agents/matrx`. Not part of the
+ * public surface — `matrx/index.ts` deliberately does not re-export this
+ * module. Everything here is pure: no globals, no work at import time.
+ */
+
+/**
+ * Options for every streaming call, riding the NDJSON kernel's contract.
+ * Public via `./run`'s re-export.
+ */
+interface MatrxStreamCallOptions {
+    /** Abort the fetch and end the events iterator. */
+    signal?: AbortSignal;
+    /** Bounded background read-ahead (see `stream/ndjson`). */
+    maxReadAhead?: number;
+    /** Malformed NDJSON is non-fatal but must never disappear silently. */
+    onMalformedLine?: (issue: MatrxNdjsonIssue) => void;
+    /** Valid JSON with no recognized Matrx envelope. */
+    onUnknownEnvelope?: (value: unknown) => void;
+    /** Observe every valid envelope in its exact wire form. */
+    onValidEnvelope?: (observation: MatrxStreamEnvelopeObservation) => void;
+}
+/**
+ * A live agent run: the server-assigned ids (from response headers, available
+ * BEFORE any event) and the normalized event stream. Public via `./run`.
+ */
+interface MatrxRunHandle {
+    /** `X-Request-ID` — the ONLY id `POST /ai/cancel/{request_id}` accepts. */
+    requestId: string | null;
+    /** `X-Conversation-ID` — the server's conversation identity. */
+    conversationId: string | null;
+    /** Normalized `{event, data}` envelopes through the ONE wire kernel. */
+    events: AsyncGenerator<MatrxStreamEnvelope, void, undefined>;
+    /** The raw response, for hosts that need headers/status beyond the ids. */
+    response: Response;
+}
+
+/**
+ * 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/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>;
+/** 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>;
+
+/**
+ * Runtime operations — the canonical reconnect & resume read surface of the
+ * execution spine, over the `MatrxTransport` port.
+ *
+ * Server truth (verified against aidream source,
+ * `aidream/api/routers/runtime_operations.py` + `aidream/services/runtime/
+ * reconnect.py`; mounted at bare `/runtime`):
+ * - `GET  /runtime/operations/{request_id}`            — identify by `X-Request-ID`
+ * - `GET  /runtime/operations/by-link/{kind}/{id}`     — identify by feature record
+ * - `GET  /runtime/executions/{id}/events`             — durable seq-cursored page
+ * - `GET  /runtime/executions/{id}/events/stream`      — SSE replay-then-follow,
+ *   `id:` = per-tree seq, reconnect with `Last-Event-ID`
+ * - `POST /runtime/operations/{request_id}/rejoin`     — replay + follow the
+ *   ORIGINAL NDJSON response while its detached task is alive (409 when live
+ *   delivery is unavailable — fall back to the durable lifecycle stream)
+ *
+ * The contract: identify → recover durable progress → follow live → re-query
+ * the final result from the feature's own record. Token text is deliberately
+ * never replayed on the lifecycle stream — that is what `/rejoin` is for.
+ *
+ * The SSE wire rides the package's own `stream/sse` kernel. This module owns
+ * ONE connection's semantics (frames → typed events, cursor advancement,
+ * terminal `end`); stall timers, retry budgets, and reconnect loops stay host
+ * policy — every yielded item carries the cursor the next attempt resumes from.
+ */
+
+/** `matrx_runtime.models.ExecutionStatus` — the only progress column. */
+type MatrxRuntimeExecutionStatus = "pending" | "running" | "paused" | "waiting_input" | "completed" | "failed" | "cancelled";
+declare const TERMINAL_MATRX_RUNTIME_STATUSES: ReadonlySet<MatrxRuntimeExecutionStatus>;
+/** One durable spine event on the wire (`OperationEvent`) — `seq` is the reconnect cursor. */
+interface MatrxRuntimeOperationEvent {
+    seq: number | null;
+    /** Lifecycle vocabulary: created | started | paused | resumed | waiting_input | completed | failed | cancelled | checkpoint_saved | note. */
+    kind: string;
+    execution_id: string;
+    root_execution_id: string | null;
+    detail: MatrxJsonObject | null;
+    created_at: string | null;
+}
+/** One root execution as a reconnecting client sees it (`OperationView`). */
+interface MatrxRuntimeOperationView {
+    execution_id: string;
+    /** Durable request identity — feeds `/rejoin` and no-prompt resume recovery. */
+    request_id: string | null;
+    type: string;
+    status: MatrxRuntimeExecutionStatus;
+    is_terminal: boolean;
+    waiting_input: boolean;
+    /** Decimal on the wire — may arrive as number or string; display-only. */
+    cost: number | string;
+    meters: Record<string, number | string>;
+    link_kind: string | null;
+    link_id: string | null;
+    error: MatrxJsonObject | null;
+    created_at: string | null;
+    started_at: string | null;
+    ended_at: string | null;
+    last_event_seq: number;
+    events_path: string;
+    stream_path: string;
+}
+interface MatrxOperationStatusResponse {
+    request_id: string;
+    operation_count: number;
+    operations: MatrxRuntimeOperationView[];
+}
+interface MatrxOperationsByLinkResponse {
+    link_kind: string;
+    link_id: string;
+    operation_count: number;
+    operations: MatrxRuntimeOperationView[];
+}
+interface MatrxOperationEventsPage {
+    execution_id: string;
+    root_execution_id: string;
+    events: MatrxRuntimeOperationEvent[];
+    /** Feeds the next page or the SSE `Last-Event-ID` — polling and push share ONE cursor. */
+    next_after_seq: number;
+    has_more: boolean;
+    root_status: MatrxRuntimeExecutionStatus;
+    root_is_terminal: boolean;
+}
+/**
+ * Where is my operation? Resolves an `X-Request-ID` to its root execution(s).
+ * Returns null on 404 — missing and unowned share one shape by design
+ * (existence is never leaked).
+ */
+declare function getRuntimeOperationStatus(transport: MatrxTransport, requestId: string, options?: {
+    signal?: AbortSignal;
+}): Promise<MatrxOperationStatusResponse | null>;
+/**
+ * Operations for a feature record — e.g. `("conversation", conversationId)`,
+ * `("workflow", runId)`, `("agent_run", runId)`. Newest first; unowned trees
+ * omitted. Returns null on 404 (surface absent, or the caller owns nothing —
+ * one shape by design).
+ */
+declare function getRuntimeOperationsByLink(transport: MatrxTransport, linkKind: string, linkId: string, options?: {
+    limit?: number;
+    signal?: AbortSignal;
+}): Promise<MatrxOperationsByLinkResponse | null>;
+/**
+ * Durable progress page for the whole operation TREE:
+ * `GET /runtime/executions/{id}/events?after_seq=…`. Pass any node id — it
+ * resolves to the root.
+ */
+declare function listRuntimeOperationEvents(transport: MatrxTransport, executionId: string, options?: {
+    afterSeq?: number;
+    limit?: number;
+    /** Repeatable event-kind filter. */
+    kinds?: readonly string[];
+    signal?: AbortSignal;
+}): Promise<MatrxOperationEventsPage>;
+/**
+ * One item from the follow stream. Every item carries `cursor` — the highest
+ * event seq seen so far, which is exactly the `Last-Event-ID` a reconnect
+ * resumes from (host retry policy owns the reconnect loop).
+ */
+type MatrxOperationFollowEvent = {
+    /** A parsed durable spine event. */
+    type: "event";
+    event: MatrxRuntimeOperationEvent;
+    /** The frame's SSE `id:` as an integer, when it carried one. */
+    seq: number | null;
+    cursor: number;
+} | {
+    /**
+     * A frame that carried no deliverable event — a comment heartbeat, an
+     * unknown event name, or a malformed payload (also surfaced through
+     * `onMalformedFrame`). ANY parsed frame proves the wire is alive: hosts
+     * reset stall timers and retry budgets on it.
+     */
+    type: "liveness";
+    cursor: number;
+} | {
+    /** The server's terminal frame — the root settled; the stream is over. */
+    type: "end";
+    status: MatrxRuntimeExecutionStatus | null;
+    cursor: number;
+};
+interface FollowRuntimeOperationOptions {
+    /** Resume cursor — the operation view's `last_event_seq` (0 = from start). */
+    lastEventSeq?: number;
+    /** Abort the follow — the generator simply ends. */
+    signal?: AbortSignal;
+    /** A frame whose payload failed to parse — never silently dropped. */
+    onMalformedFrame?: (frame: MatrxSseFrame, error: unknown) => void;
+    /** Unterminated trailing SSE text at stream end (diagnostic, never an event). */
+    onIncomplete?: (text: string) => void;
+}
+/**
+ * Follow ONE SSE connection of an operation's lifecycle stream:
+ * `GET /runtime/executions/{id}/events/stream` with `Last-Event-ID` when
+ * resuming past 0. Replays from the cursor, then follows live; a
+ * WAITING_INPUT park keeps it open (a resume re-attaches to the same
+ * execution and its events continue here). Ends after yielding
+ * `{type: "end"}` when the root settles; a server close WITHOUT an end frame
+ * simply ends the generator — reconnect from the last yielded `cursor` (host
+ * retry policy).
+ */
+declare function followRuntimeOperationEvents(transport: MatrxTransport, executionId: string, options?: FollowRuntimeOperationOptions): AsyncGenerator<MatrxOperationFollowEvent, void, undefined>;
+/**
+ * Rejoin the ORIGINAL NDJSON response while its detached task is still alive:
+ * `POST /runtime/operations/{request_id}/rejoin`. Replays the response from
+ * frame one, then continues live — every frame is sequence-stamped
+ * (`stream_seq`), so a same-page reconnect can drop frames it already
+ * rendered. Throws `MatrxApiError` with status 409 when live delivery is
+ * unavailable — fall back to `followRuntimeOperationEvents` + a final record
+ * re-query. The `requestId` must be the server's `X-Request-ID`.
+ */
+declare function rejoinRuntimeOperation(transport: MatrxTransport, requestId: string, options?: MatrxStreamCallOptions): Promise<MatrxRunHandle>;
+
+/**
+ * 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[]>;
+
+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 };