@ai-matrx/agents 0.10.7 → 0.11.1

package/dist/operations-BT5kKMHl.d.cts

@@ -0,0 +1,203 @@
+/**
+ * `@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>;
+}
+
+/**
+ * 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;
+
+/**
+ * Canonical AI Matrx NDJSON wire kernel.
+ *
+ * This module is deliberately independent of React, Redux, Next.js, Supabase,
+ * and generated application types. Every Matrx client uses it to turn the
+ * backend's byte stream into the same normalized `{ event, data }` envelopes.
+ * Host runtimes remain responsible for HTTP/auth errors and for deciding what
+ * each event means in their state model.
+ */
+interface MatrxStreamEnvelope<TData = unknown> {
+    event: string;
+    /** Immutable emitter segment; transport sequence is scoped to this id. */
+    stream_id?: string;
+    data: TData;
+    /** Monotonic transport sequence from full envelopes, when supplied. */
+    stream_seq?: number;
+}
+interface MatrxNdjsonIssue {
+    line: string;
+    error: unknown;
+    /** One-based physical NDJSON line number. */
+    lineNumber: number;
+    /** True when an unterminated trailing fragment was parsed by `finish()`. */
+    atCompletion: boolean;
+}
+interface MatrxStreamEnvelopeObservation {
+    /** Exact parsed JSON value before compact/full normalization. */
+    raw: unknown;
+    envelope: MatrxStreamEnvelope;
+    line: string;
+    lineNumber: number;
+    atCompletion: boolean;
+}
+
+/**
+ * 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";
+/** 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;
+}
+
+export type { MatrxTransport as M, MatrxStreamEnvelope as a, MatrxRuntimeOperationEvent as b, MatrxRuntimeExecutionStatus as c, MatrxNdjsonIssue as d, MatrxStreamEnvelopeObservation as e, MatrxConversationStart as f, MatrxJsonValue as g, MatrxJsonObject as h };

package/dist/operations-BT5kKMHl.d.ts

@@ -0,0 +1,203 @@
+/**
+ * `@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>;
+}
+
+/**
+ * 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;
+
+/**
+ * Canonical AI Matrx NDJSON wire kernel.
+ *
+ * This module is deliberately independent of React, Redux, Next.js, Supabase,
+ * and generated application types. Every Matrx client uses it to turn the
+ * backend's byte stream into the same normalized `{ event, data }` envelopes.
+ * Host runtimes remain responsible for HTTP/auth errors and for deciding what
+ * each event means in their state model.
+ */
+interface MatrxStreamEnvelope<TData = unknown> {
+    event: string;
+    /** Immutable emitter segment; transport sequence is scoped to this id. */
+    stream_id?: string;
+    data: TData;
+    /** Monotonic transport sequence from full envelopes, when supplied. */
+    stream_seq?: number;
+}
+interface MatrxNdjsonIssue {
+    line: string;
+    error: unknown;
+    /** One-based physical NDJSON line number. */
+    lineNumber: number;
+    /** True when an unterminated trailing fragment was parsed by `finish()`. */
+    atCompletion: boolean;
+}
+interface MatrxStreamEnvelopeObservation {
+    /** Exact parsed JSON value before compact/full normalization. */
+    raw: unknown;
+    envelope: MatrxStreamEnvelope;
+    line: string;
+    lineNumber: number;
+    atCompletion: boolean;
+}
+
+/**
+ * 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";
+/** 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;
+}
+
+export type { MatrxTransport as M, MatrxStreamEnvelope as a, MatrxRuntimeOperationEvent as b, MatrxRuntimeExecutionStatus as c, MatrxNdjsonIssue as d, MatrxStreamEnvelopeObservation as e, MatrxConversationStart as f, MatrxJsonValue as g, MatrxJsonObject as h };