@ai-matrx/agents 0.10.7 → 0.11.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/CHANGELOG.md +20 -0
  2. package/dist/content-transfer/index.cjs +1424 -0
  3. package/dist/content-transfer/index.cjs.map +1 -0
  4. package/dist/content-transfer/index.d.cts +84 -0
  5. package/dist/content-transfer/index.d.ts +84 -0
  6. package/dist/content-transfer/index.js +1406 -0
  7. package/dist/content-transfer/index.js.map +1 -0
  8. package/dist/content-transfer/react/index.cjs +1566 -0
  9. package/dist/content-transfer/react/index.cjs.map +1 -0
  10. package/dist/content-transfer/react/index.d.cts +63 -0
  11. package/dist/content-transfer/react/index.d.ts +63 -0
  12. package/dist/content-transfer/react/index.js +1541 -0
  13. package/dist/content-transfer/react/index.js.map +1 -0
  14. package/dist/index.cjs +23 -0
  15. package/dist/index.cjs.map +1 -1
  16. package/dist/index.d.cts +2 -1
  17. package/dist/index.d.ts +2 -1
  18. package/dist/index.js +23 -0
  19. package/dist/index.js.map +1 -1
  20. package/dist/mandates/index.cjs +9 -2
  21. package/dist/mandates/index.cjs.map +1 -1
  22. package/dist/mandates/index.d.cts +12 -5
  23. package/dist/mandates/index.d.ts +12 -5
  24. package/dist/mandates/index.js +9 -2
  25. package/dist/mandates/index.js.map +1 -1
  26. package/dist/matrx/index.cjs +23 -0
  27. package/dist/matrx/index.cjs.map +1 -1
  28. package/dist/matrx/index.d.cts +13 -646
  29. package/dist/matrx/index.d.ts +13 -646
  30. package/dist/matrx/index.js +23 -0
  31. package/dist/matrx/index.js.map +1 -1
  32. package/dist/operations--f5ko9Su.d.cts +659 -0
  33. package/dist/operations-BT5kKMHl.d.cts +203 -0
  34. package/dist/operations-BT5kKMHl.d.ts +203 -0
  35. package/dist/operations-Dp4ut-ac.d.ts +659 -0
  36. package/dist/react/index.cjs.map +1 -1
  37. package/dist/react/index.d.cts +44 -244
  38. package/dist/react/index.d.ts +44 -244
  39. package/dist/react/index.js.map +1 -1
  40. package/mandates/snapshots/keys.0.11.0.json +475 -0
  41. package/mandates/snapshots/keys.0.11.1.json +477 -0
  42. package/package.json +25 -4
@@ -1,102 +1,4 @@
1
- type AgentProjectionStatus = "pending" | "streaming" | "awaiting-tools" | "complete" | "error" | "cancelled";
2
- interface AgentProjectionOperation {
3
- operationId: string;
4
- operation: string;
5
- parentOperationId: string | null;
6
- status: "active" | "success" | "failed" | "cancelled";
7
- metadata: Record<string, unknown> | null;
8
- result: Record<string, unknown> | null;
9
- }
10
- interface AgentProjectionTool {
11
- callId: string;
12
- toolName: string;
13
- status: "started" | "progress" | "step" | "preview" | "completed" | "error" | "delegated";
14
- message: string | null;
15
- data: Record<string, unknown> | null;
16
- }
17
- interface AgentProjectionRenderBlock {
18
- blockId: string;
19
- blockIndex: number;
20
- type: string;
21
- status: "streaming" | "complete" | "error";
22
- content: string | null;
23
- data: Record<string, unknown> | null;
24
- metadata: Record<string, unknown> | null;
25
- }
26
- interface AgentRequestProjection {
27
- requestId: string;
28
- conversationId: string | null;
29
- status: AgentProjectionStatus;
30
- answer: string;
31
- reasoning: string;
32
- reasoningActive: boolean;
33
- phase: string | null;
34
- phaseHistory: string[];
35
- operations: Record<string, AgentProjectionOperation>;
36
- tools: Record<string, AgentProjectionTool>;
37
- renderBlocks: Record<string, AgentProjectionRenderBlock>;
38
- renderBlockOrder: string[];
39
- completion: Record<string, unknown> | null;
40
- error: Record<string, unknown> | null;
41
- lastTransportSeq: number;
42
- transportStreamId: string | null;
43
- eventCount: number;
44
- }
45
-
46
- /**
47
- * `@ai-matrx/agents/matrx` — the Matrx transport port.
48
- *
49
- * The ONE seam between this package's wire semantics and a host's connection
50
- * policy. This package owns WHAT is said to the AI Matrx server — paths,
51
- * methods, JSON bodies, streaming Accept headers, the `Last-Event-ID` cursor
52
- * header — and the host owns HOW the connection is made:
53
- *
54
- * - base-URL / backend-channel resolution (global, sandbox override, local
55
- * engine, EC2-dedicated — whatever ladder the host runs);
56
- * - credentials (Supabase JWT `Authorization: Bearer`, guest
57
- * `X-Fingerprint-ID`, or the API-key lane) — NEVER implemented here;
58
- * - the `X-Organization-Id` context header;
59
- * - retry policy, network-level timeouts, and diagnostics capture.
60
- *
61
- * A host implements the port in a few lines:
62
- *
63
- * ```ts
64
- * const transport: MatrxTransport = {
65
- * fetch: (path, init) =>
66
- * fetch(`${baseUrl}${path}`, {
67
- * ...init,
68
- * headers: { ...init.headers, ...authHeaders() },
69
- * }),
70
- * };
71
- * ```
72
- *
73
- * The port is deliberately structural and `fetch`-shaped so `@ai-matrx/data`'s
74
- * `/api` transport can implement it without importing this package.
75
- */
76
- /**
77
- * The request this package hands the port. A strict subset of `RequestInit`,
78
- * so a host can spread it straight into `fetch`.
79
- */
80
- interface MatrxTransportRequest {
81
- method: "GET" | "POST";
82
- /**
83
- * Wire-semantic headers the CALL requires (`Content-Type`, `Accept`,
84
- * `Last-Event-ID`). The host merges its policy headers (auth, org) on top;
85
- * it must not drop these.
86
- */
87
- headers: Record<string, string>;
88
- /** Pre-serialized JSON body, present on POST calls that carry one. */
89
- body?: string;
90
- /** Caller cancellation. The host must wire it to the underlying fetch. */
91
- signal?: AbortSignal;
92
- }
93
- /**
94
- * The transport port. `path` is server-relative and always starts with `/`
95
- * (`/ai/...`, `/runtime/...`); the host prepends its resolved base URL.
96
- */
97
- interface MatrxTransport {
98
- fetch(path: string, init: MatrxTransportRequest): Promise<Response>;
99
- }
1
+ import { d as MatrxNdjsonIssue, e as MatrxStreamEnvelopeObservation, f as MatrxConversationStart, g as MatrxJsonValue, h as MatrxJsonObject, M as MatrxTransport, c as MatrxRuntimeExecutionStatus, b as MatrxRuntimeOperationEvent } from '../operations-BT5kKMHl.cjs';
100
2
 
101
3
  /**
102
4
  * The PRODUCTION `MatrxTransport` — the full connection pipeline every Matrx
@@ -160,114 +62,6 @@ interface MatrxCallError {
160
62
  stack?: string;
161
63
  }
162
64
 
163
- /**
164
- * The conversation-start contract — client-minted `conversation_id`, `is_new`,
165
- * `store` — typed exactly per the cross-repo System of Record
166
- * (`common-docs/systems/agents/conversation-start-contract/FEATURE.md`;
167
- * server truth `aidream/services/conversation_context/scope.py::
168
- * ConversationStartRequest`).
169
- *
170
- * Every request that STARTS a conversation sends all three fields, no
171
- * defaults:
172
- *
173
- * | `is_new` | `store` | Result |
174
- * |----------|---------|----------------------------------------------------------|
175
- * | true | true | Create the row with the caller's id — 409 if it exists |
176
- * | true | false | No row. The id is correlation only (ephemeral run) |
177
- * | false | true | Continue it — 404 if the caller doesn't own it |
178
- * | false | false | Ephemeral run on a known id; nothing read, nothing written |
179
- *
180
- * `store` is the ONLY ephemeral signal; `is_new` is the caller's assertion
181
- * about the id, never a persistence switch. `prior_messages` (the client-owned
182
- * transcript of an ephemeral multi-turn run) is only valid with
183
- * `store: false` — the union below makes the invalid combination
184
- * unrepresentable, mirroring the server's 422.
185
- *
186
- * Continue routes (`POST /ai/conversations/{id}`) take the id from the path
187
- * and do not carry this triple.
188
- */
189
- /** Recursive JSON value — the package's honest type for free-form wire bags. */
190
- type MatrxJsonValue = string | number | boolean | null | MatrxJsonValue[] | {
191
- [key: string]: MatrxJsonValue;
192
- };
193
- /** A JSON object on the wire. */
194
- type MatrxJsonObject = {
195
- [key: string]: MatrxJsonValue;
196
- };
197
- /**
198
- * One LLM message on the request wire — `prior_messages` entries for
199
- * stateless multi-turn runs. Mirrors aidream's `ChatMessageInput`
200
- * (`aidream/schemas/messages.py`, `extra="allow"` — additional provider
201
- * fields round-trip untouched).
202
- */
203
- interface MatrxChatMessage {
204
- role: string;
205
- content?: string | MatrxJsonValue[] | null;
206
- name?: string | null;
207
- tool_call_id?: string | null;
208
- tool_calls?: MatrxJsonObject[] | null;
209
- [extra: string]: MatrxJsonValue | undefined;
210
- }
211
- /** `is_new: true, store: true` — create the row with the caller's id. */
212
- interface MatrxStoredConversationCreate {
213
- conversation_id: string;
214
- is_new: true;
215
- store: true;
216
- }
217
- /** `is_new: false, store: true` — continue an owned stored conversation via a start route. */
218
- interface MatrxStoredConversationContinue {
219
- conversation_id: string;
220
- is_new: false;
221
- store: true;
222
- }
223
- /**
224
- * `store: false` — ephemeral: nothing read, nothing written; the id is the
225
- * caller's correlation handle. This is the ONLY member that may carry
226
- * `prior_messages` (the server 422s a client transcript on a stored run).
227
- */
228
- interface MatrxEphemeralConversation {
229
- conversation_id: string;
230
- is_new: boolean;
231
- store: false;
232
- prior_messages?: MatrxChatMessage[];
233
- }
234
- /** The full conversation-start triple, one member per contract cell. */
235
- type MatrxConversationStart = MatrxStoredConversationCreate | MatrxStoredConversationContinue | MatrxEphemeralConversation;
236
-
237
- /**
238
- * Canonical AI Matrx NDJSON wire kernel.
239
- *
240
- * This module is deliberately independent of React, Redux, Next.js, Supabase,
241
- * and generated application types. Every Matrx client uses it to turn the
242
- * backend's byte stream into the same normalized `{ event, data }` envelopes.
243
- * Host runtimes remain responsible for HTTP/auth errors and for deciding what
244
- * each event means in their state model.
245
- */
246
- interface MatrxStreamEnvelope<TData = unknown> {
247
- event: string;
248
- /** Immutable emitter segment; transport sequence is scoped to this id. */
249
- stream_id?: string;
250
- data: TData;
251
- /** Monotonic transport sequence from full envelopes, when supplied. */
252
- stream_seq?: number;
253
- }
254
- interface MatrxNdjsonIssue {
255
- line: string;
256
- error: unknown;
257
- /** One-based physical NDJSON line number. */
258
- lineNumber: number;
259
- /** True when an unterminated trailing fragment was parsed by `finish()`. */
260
- atCompletion: boolean;
261
- }
262
- interface MatrxStreamEnvelopeObservation {
263
- /** Exact parsed JSON value before compact/full normalization. */
264
- raw: unknown;
265
- envelope: MatrxStreamEnvelope;
266
- line: string;
267
- lineNumber: number;
268
- atCompletion: boolean;
269
- }
270
-
271
65
  /**
272
66
  * Internal request plumbing for `@ai-matrx/agents/matrx`. Not part of the
273
67
  * public surface — `matrx/index.ts` deliberately does not re-export this
@@ -401,43 +195,49 @@ interface MatrxCancelResponse {
401
195
  spine_executions_signalled: string[];
402
196
  }
403
197
 
404
- /**
405
- * Runtime operations — the canonical reconnect & resume read surface of the
406
- * execution spine, over the `MatrxTransport` port.
407
- *
408
- * Server truth (verified against aidream source,
409
- * `aidream/api/routers/runtime_operations.py` + `aidream/services/runtime/
410
- * reconnect.py`; mounted at bare `/runtime`):
411
- * - `GET /runtime/operations/{request_id}` — identify by `X-Request-ID`
412
- * - `GET /runtime/operations/by-link/{kind}/{id}` — identify by feature record
413
- * - `GET /runtime/executions/{id}/events` — durable seq-cursored page
414
- * - `GET /runtime/executions/{id}/events/stream` — SSE replay-then-follow,
415
- * `id:` = per-tree seq, reconnect with `Last-Event-ID`
416
- * - `POST /runtime/operations/{request_id}/rejoin` — replay + follow the
417
- * ORIGINAL NDJSON response while its detached task is alive (409 when live
418
- * delivery is unavailable — fall back to the durable lifecycle stream)
419
- *
420
- * The contract: identify → recover durable progress → follow live → re-query
421
- * the final result from the feature's own record. Token text is deliberately
422
- * never replayed on the lifecycle stream — that is what `/rejoin` is for.
423
- *
424
- * The SSE wire rides the package's own `stream/sse` kernel. This module owns
425
- * ONE connection's semantics (frames → typed events, cursor advancement,
426
- * terminal `end`); stall timers, retry budgets, and reconnect loops stay host
427
- * policy — every yielded item carries the cursor the next attempt resumes from.
428
- */
429
-
430
- /** `matrx_runtime.models.ExecutionStatus` — the only progress column. */
431
- type MatrxRuntimeExecutionStatus = "pending" | "running" | "paused" | "waiting_input" | "completed" | "failed" | "cancelled";
432
- /** One durable spine event on the wire (`OperationEvent`) — `seq` is the reconnect cursor. */
433
- interface MatrxRuntimeOperationEvent {
434
- seq: number | null;
435
- /** Lifecycle vocabulary: created | started | paused | resumed | waiting_input | completed | failed | cancelled | checkpoint_saved | note. */
436
- kind: string;
437
- execution_id: string;
438
- root_execution_id: string | null;
439
- detail: MatrxJsonObject | null;
440
- created_at: string | null;
198
+ type AgentProjectionStatus = "pending" | "streaming" | "awaiting-tools" | "complete" | "error" | "cancelled";
199
+ interface AgentProjectionOperation {
200
+ operationId: string;
201
+ operation: string;
202
+ parentOperationId: string | null;
203
+ status: "active" | "success" | "failed" | "cancelled";
204
+ metadata: Record<string, unknown> | null;
205
+ result: Record<string, unknown> | null;
206
+ }
207
+ interface AgentProjectionTool {
208
+ callId: string;
209
+ toolName: string;
210
+ status: "started" | "progress" | "step" | "preview" | "completed" | "error" | "delegated";
211
+ message: string | null;
212
+ data: Record<string, unknown> | null;
213
+ }
214
+ interface AgentProjectionRenderBlock {
215
+ blockId: string;
216
+ blockIndex: number;
217
+ type: string;
218
+ status: "streaming" | "complete" | "error";
219
+ content: string | null;
220
+ data: Record<string, unknown> | null;
221
+ metadata: Record<string, unknown> | null;
222
+ }
223
+ interface AgentRequestProjection {
224
+ requestId: string;
225
+ conversationId: string | null;
226
+ status: AgentProjectionStatus;
227
+ answer: string;
228
+ reasoning: string;
229
+ reasoningActive: boolean;
230
+ phase: string | null;
231
+ phaseHistory: string[];
232
+ operations: Record<string, AgentProjectionOperation>;
233
+ tools: Record<string, AgentProjectionTool>;
234
+ renderBlocks: Record<string, AgentProjectionRenderBlock>;
235
+ renderBlockOrder: string[];
236
+ completion: Record<string, unknown> | null;
237
+ error: Record<string, unknown> | null;
238
+ lastTransportSeq: number;
239
+ transportStreamId: string | null;
240
+ eventCount: number;
441
241
  }
442
242
 
443
243
  /**
@@ -1,102 +1,4 @@
1
- type AgentProjectionStatus = "pending" | "streaming" | "awaiting-tools" | "complete" | "error" | "cancelled";
2
- interface AgentProjectionOperation {
3
- operationId: string;
4
- operation: string;
5
- parentOperationId: string | null;
6
- status: "active" | "success" | "failed" | "cancelled";
7
- metadata: Record<string, unknown> | null;
8
- result: Record<string, unknown> | null;
9
- }
10
- interface AgentProjectionTool {
11
- callId: string;
12
- toolName: string;
13
- status: "started" | "progress" | "step" | "preview" | "completed" | "error" | "delegated";
14
- message: string | null;
15
- data: Record<string, unknown> | null;
16
- }
17
- interface AgentProjectionRenderBlock {
18
- blockId: string;
19
- blockIndex: number;
20
- type: string;
21
- status: "streaming" | "complete" | "error";
22
- content: string | null;
23
- data: Record<string, unknown> | null;
24
- metadata: Record<string, unknown> | null;
25
- }
26
- interface AgentRequestProjection {
27
- requestId: string;
28
- conversationId: string | null;
29
- status: AgentProjectionStatus;
30
- answer: string;
31
- reasoning: string;
32
- reasoningActive: boolean;
33
- phase: string | null;
34
- phaseHistory: string[];
35
- operations: Record<string, AgentProjectionOperation>;
36
- tools: Record<string, AgentProjectionTool>;
37
- renderBlocks: Record<string, AgentProjectionRenderBlock>;
38
- renderBlockOrder: string[];
39
- completion: Record<string, unknown> | null;
40
- error: Record<string, unknown> | null;
41
- lastTransportSeq: number;
42
- transportStreamId: string | null;
43
- eventCount: number;
44
- }
45
-
46
- /**
47
- * `@ai-matrx/agents/matrx` — the Matrx transport port.
48
- *
49
- * The ONE seam between this package's wire semantics and a host's connection
50
- * policy. This package owns WHAT is said to the AI Matrx server — paths,
51
- * methods, JSON bodies, streaming Accept headers, the `Last-Event-ID` cursor
52
- * header — and the host owns HOW the connection is made:
53
- *
54
- * - base-URL / backend-channel resolution (global, sandbox override, local
55
- * engine, EC2-dedicated — whatever ladder the host runs);
56
- * - credentials (Supabase JWT `Authorization: Bearer`, guest
57
- * `X-Fingerprint-ID`, or the API-key lane) — NEVER implemented here;
58
- * - the `X-Organization-Id` context header;
59
- * - retry policy, network-level timeouts, and diagnostics capture.
60
- *
61
- * A host implements the port in a few lines:
62
- *
63
- * ```ts
64
- * const transport: MatrxTransport = {
65
- * fetch: (path, init) =>
66
- * fetch(`${baseUrl}${path}`, {
67
- * ...init,
68
- * headers: { ...init.headers, ...authHeaders() },
69
- * }),
70
- * };
71
- * ```
72
- *
73
- * The port is deliberately structural and `fetch`-shaped so `@ai-matrx/data`'s
74
- * `/api` transport can implement it without importing this package.
75
- */
76
- /**
77
- * The request this package hands the port. A strict subset of `RequestInit`,
78
- * so a host can spread it straight into `fetch`.
79
- */
80
- interface MatrxTransportRequest {
81
- method: "GET" | "POST";
82
- /**
83
- * Wire-semantic headers the CALL requires (`Content-Type`, `Accept`,
84
- * `Last-Event-ID`). The host merges its policy headers (auth, org) on top;
85
- * it must not drop these.
86
- */
87
- headers: Record<string, string>;
88
- /** Pre-serialized JSON body, present on POST calls that carry one. */
89
- body?: string;
90
- /** Caller cancellation. The host must wire it to the underlying fetch. */
91
- signal?: AbortSignal;
92
- }
93
- /**
94
- * The transport port. `path` is server-relative and always starts with `/`
95
- * (`/ai/...`, `/runtime/...`); the host prepends its resolved base URL.
96
- */
97
- interface MatrxTransport {
98
- fetch(path: string, init: MatrxTransportRequest): Promise<Response>;
99
- }
1
+ import { d as MatrxNdjsonIssue, e as MatrxStreamEnvelopeObservation, f as MatrxConversationStart, g as MatrxJsonValue, h as MatrxJsonObject, M as MatrxTransport, c as MatrxRuntimeExecutionStatus, b as MatrxRuntimeOperationEvent } from '../operations-BT5kKMHl.js';
100
2
 
101
3
  /**
102
4
  * The PRODUCTION `MatrxTransport` — the full connection pipeline every Matrx
@@ -160,114 +62,6 @@ interface MatrxCallError {
160
62
  stack?: string;
161
63
  }
162
64
 
163
- /**
164
- * The conversation-start contract — client-minted `conversation_id`, `is_new`,
165
- * `store` — typed exactly per the cross-repo System of Record
166
- * (`common-docs/systems/agents/conversation-start-contract/FEATURE.md`;
167
- * server truth `aidream/services/conversation_context/scope.py::
168
- * ConversationStartRequest`).
169
- *
170
- * Every request that STARTS a conversation sends all three fields, no
171
- * defaults:
172
- *
173
- * | `is_new` | `store` | Result |
174
- * |----------|---------|----------------------------------------------------------|
175
- * | true | true | Create the row with the caller's id — 409 if it exists |
176
- * | true | false | No row. The id is correlation only (ephemeral run) |
177
- * | false | true | Continue it — 404 if the caller doesn't own it |
178
- * | false | false | Ephemeral run on a known id; nothing read, nothing written |
179
- *
180
- * `store` is the ONLY ephemeral signal; `is_new` is the caller's assertion
181
- * about the id, never a persistence switch. `prior_messages` (the client-owned
182
- * transcript of an ephemeral multi-turn run) is only valid with
183
- * `store: false` — the union below makes the invalid combination
184
- * unrepresentable, mirroring the server's 422.
185
- *
186
- * Continue routes (`POST /ai/conversations/{id}`) take the id from the path
187
- * and do not carry this triple.
188
- */
189
- /** Recursive JSON value — the package's honest type for free-form wire bags. */
190
- type MatrxJsonValue = string | number | boolean | null | MatrxJsonValue[] | {
191
- [key: string]: MatrxJsonValue;
192
- };
193
- /** A JSON object on the wire. */
194
- type MatrxJsonObject = {
195
- [key: string]: MatrxJsonValue;
196
- };
197
- /**
198
- * One LLM message on the request wire — `prior_messages` entries for
199
- * stateless multi-turn runs. Mirrors aidream's `ChatMessageInput`
200
- * (`aidream/schemas/messages.py`, `extra="allow"` — additional provider
201
- * fields round-trip untouched).
202
- */
203
- interface MatrxChatMessage {
204
- role: string;
205
- content?: string | MatrxJsonValue[] | null;
206
- name?: string | null;
207
- tool_call_id?: string | null;
208
- tool_calls?: MatrxJsonObject[] | null;
209
- [extra: string]: MatrxJsonValue | undefined;
210
- }
211
- /** `is_new: true, store: true` — create the row with the caller's id. */
212
- interface MatrxStoredConversationCreate {
213
- conversation_id: string;
214
- is_new: true;
215
- store: true;
216
- }
217
- /** `is_new: false, store: true` — continue an owned stored conversation via a start route. */
218
- interface MatrxStoredConversationContinue {
219
- conversation_id: string;
220
- is_new: false;
221
- store: true;
222
- }
223
- /**
224
- * `store: false` — ephemeral: nothing read, nothing written; the id is the
225
- * caller's correlation handle. This is the ONLY member that may carry
226
- * `prior_messages` (the server 422s a client transcript on a stored run).
227
- */
228
- interface MatrxEphemeralConversation {
229
- conversation_id: string;
230
- is_new: boolean;
231
- store: false;
232
- prior_messages?: MatrxChatMessage[];
233
- }
234
- /** The full conversation-start triple, one member per contract cell. */
235
- type MatrxConversationStart = MatrxStoredConversationCreate | MatrxStoredConversationContinue | MatrxEphemeralConversation;
236
-
237
- /**
238
- * Canonical AI Matrx NDJSON wire kernel.
239
- *
240
- * This module is deliberately independent of React, Redux, Next.js, Supabase,
241
- * and generated application types. Every Matrx client uses it to turn the
242
- * backend's byte stream into the same normalized `{ event, data }` envelopes.
243
- * Host runtimes remain responsible for HTTP/auth errors and for deciding what
244
- * each event means in their state model.
245
- */
246
- interface MatrxStreamEnvelope<TData = unknown> {
247
- event: string;
248
- /** Immutable emitter segment; transport sequence is scoped to this id. */
249
- stream_id?: string;
250
- data: TData;
251
- /** Monotonic transport sequence from full envelopes, when supplied. */
252
- stream_seq?: number;
253
- }
254
- interface MatrxNdjsonIssue {
255
- line: string;
256
- error: unknown;
257
- /** One-based physical NDJSON line number. */
258
- lineNumber: number;
259
- /** True when an unterminated trailing fragment was parsed by `finish()`. */
260
- atCompletion: boolean;
261
- }
262
- interface MatrxStreamEnvelopeObservation {
263
- /** Exact parsed JSON value before compact/full normalization. */
264
- raw: unknown;
265
- envelope: MatrxStreamEnvelope;
266
- line: string;
267
- lineNumber: number;
268
- atCompletion: boolean;
269
- }
270
-
271
65
  /**
272
66
  * Internal request plumbing for `@ai-matrx/agents/matrx`. Not part of the
273
67
  * public surface — `matrx/index.ts` deliberately does not re-export this
@@ -401,43 +195,49 @@ interface MatrxCancelResponse {
401
195
  spine_executions_signalled: string[];
402
196
  }
403
197
 
404
- /**
405
- * Runtime operations — the canonical reconnect & resume read surface of the
406
- * execution spine, over the `MatrxTransport` port.
407
- *
408
- * Server truth (verified against aidream source,
409
- * `aidream/api/routers/runtime_operations.py` + `aidream/services/runtime/
410
- * reconnect.py`; mounted at bare `/runtime`):
411
- * - `GET /runtime/operations/{request_id}` — identify by `X-Request-ID`
412
- * - `GET /runtime/operations/by-link/{kind}/{id}` — identify by feature record
413
- * - `GET /runtime/executions/{id}/events` — durable seq-cursored page
414
- * - `GET /runtime/executions/{id}/events/stream` — SSE replay-then-follow,
415
- * `id:` = per-tree seq, reconnect with `Last-Event-ID`
416
- * - `POST /runtime/operations/{request_id}/rejoin` — replay + follow the
417
- * ORIGINAL NDJSON response while its detached task is alive (409 when live
418
- * delivery is unavailable — fall back to the durable lifecycle stream)
419
- *
420
- * The contract: identify → recover durable progress → follow live → re-query
421
- * the final result from the feature's own record. Token text is deliberately
422
- * never replayed on the lifecycle stream — that is what `/rejoin` is for.
423
- *
424
- * The SSE wire rides the package's own `stream/sse` kernel. This module owns
425
- * ONE connection's semantics (frames → typed events, cursor advancement,
426
- * terminal `end`); stall timers, retry budgets, and reconnect loops stay host
427
- * policy — every yielded item carries the cursor the next attempt resumes from.
428
- */
429
-
430
- /** `matrx_runtime.models.ExecutionStatus` — the only progress column. */
431
- type MatrxRuntimeExecutionStatus = "pending" | "running" | "paused" | "waiting_input" | "completed" | "failed" | "cancelled";
432
- /** One durable spine event on the wire (`OperationEvent`) — `seq` is the reconnect cursor. */
433
- interface MatrxRuntimeOperationEvent {
434
- seq: number | null;
435
- /** Lifecycle vocabulary: created | started | paused | resumed | waiting_input | completed | failed | cancelled | checkpoint_saved | note. */
436
- kind: string;
437
- execution_id: string;
438
- root_execution_id: string | null;
439
- detail: MatrxJsonObject | null;
440
- created_at: string | null;
198
+ type AgentProjectionStatus = "pending" | "streaming" | "awaiting-tools" | "complete" | "error" | "cancelled";
199
+ interface AgentProjectionOperation {
200
+ operationId: string;
201
+ operation: string;
202
+ parentOperationId: string | null;
203
+ status: "active" | "success" | "failed" | "cancelled";
204
+ metadata: Record<string, unknown> | null;
205
+ result: Record<string, unknown> | null;
206
+ }
207
+ interface AgentProjectionTool {
208
+ callId: string;
209
+ toolName: string;
210
+ status: "started" | "progress" | "step" | "preview" | "completed" | "error" | "delegated";
211
+ message: string | null;
212
+ data: Record<string, unknown> | null;
213
+ }
214
+ interface AgentProjectionRenderBlock {
215
+ blockId: string;
216
+ blockIndex: number;
217
+ type: string;
218
+ status: "streaming" | "complete" | "error";
219
+ content: string | null;
220
+ data: Record<string, unknown> | null;
221
+ metadata: Record<string, unknown> | null;
222
+ }
223
+ interface AgentRequestProjection {
224
+ requestId: string;
225
+ conversationId: string | null;
226
+ status: AgentProjectionStatus;
227
+ answer: string;
228
+ reasoning: string;
229
+ reasoningActive: boolean;
230
+ phase: string | null;
231
+ phaseHistory: string[];
232
+ operations: Record<string, AgentProjectionOperation>;
233
+ tools: Record<string, AgentProjectionTool>;
234
+ renderBlocks: Record<string, AgentProjectionRenderBlock>;
235
+ renderBlockOrder: string[];
236
+ completion: Record<string, unknown> | null;
237
+ error: Record<string, unknown> | null;
238
+ lastTransportSeq: number;
239
+ transportStreamId: string | null;
240
+ eventCount: number;
441
241
  }
442
242
 
443
243
  /**