@ai-matrx/agents 0.2.1 → 0.5.0

package/CHANGELOG.md

@@ -1,18 +1,77 @@
 # Changelog
 
+## 0.5.0 — 2026-08-29
+
+- Added `@ai-matrx/agents/matrx` — the Matrx API client: run an agent
+  end-to-end against the AI Matrx server over ONE injected, fetch-shaped
+  `MatrxTransport` port (base URL, credentials, org header, retry, and
+  diagnostics stay the host's job — this package never implements auth).
+  - The conversation-start contract as a discriminated union (client-minted
+    `conversation_id`, `is_new`, `store`; ephemeral `prior_messages` is only
+    representable with `store: false`) plus builders for all four cells.
+  - Run lifecycle: `startAgentRun` (`POST /ai/agents/{id}`),
+    `continueAgentConversation`, `resumeAgentConversation`, `cancelAgentRun`
+    (`X-Request-ID` only), and `runAgentToCompletion` — every stream parsed
+    through the package's own NDJSON kernel; `stream: true` is forced so a
+    caller flag can never flip the response off NDJSON. `X-Request-ID` /
+    `X-Conversation-ID` surface on the handle before any event.
+  - Reconnect surface: identify by request id or feature link, durable
+    seq-cursored event pages, `followRuntimeOperationEvents` (SSE
+    replay-then-follow with `Last-Event-ID`, riding `stream/sse`; comment
+    heartbeats and malformed frames surface as liveness, terminal `end`
+    carries the root status), and `rejoinRuntimeOperation` (replay the
+    original NDJSON response; 409 = fall back to the lifecycle stream).
+  - Delegated tools: `submitAgentToolResults` (idempotent; the
+    `continuation_needed` signal for `/resume`), per-conversation and
+    per-user pending-call discovery with optional instance claim.
+  - `MatrxApiError` preserves the server's structured error body and extracts
+    its richest message/code (`user_message` → `message` → joined details →
+    FastAPI `detail` shapes).
+  - Every route, header, and response shape verified against the aidream
+    server source (routers `agents`/`conversations`/`cancel`/
+    `runtime_operations`, matrx-connect's streaming response headers).
+
+## 0.4.0 — 2026-08-28
+
+- Added `@ai-matrx/agents/stream/sse` — the pure incremental `text/event-stream`
+  frame kernel (`createMatrxSseFramer`, `parseMatrxSseFrame`,
+  `readMatrxSseStream`). Extracted from the two identical hand-rolled parsers in
+  the Matrix rejoin paths; covers all three SSE line/frame terminators by
+  construction (the production CRLF incident), byte-split UTF-8, comment
+  heartbeats as liveness-bearing frames, integer `id:` surfaced as the
+  `Last-Event-ID` cursor, and unterminated tails reported as diagnostics rather
+  than delivered as events. Host policy (fetch, stall timers, retry budgets,
+  cursor advancement) deliberately stays host-side.
+
+## 0.3.0 — 2026-08-24
+
+- Added a transport-independent incremental NDJSON framer for fragmented text
+  and bytes, including split UTF-8 and unterminated trailing input.
+- Added exact valid-envelope observation, physical-line malformed diagnostics,
+  cancellation proof, bounded configurable read-ahead, and ordered partial
+  transport failure behavior.
+- Preserved top-level `stream_seq` through wire normalization so projector
+  replay suppression receives the server's transport sequence.
+- Aligned tool status semantics with execution: server `tool_started` remains
+  streaming; only `tool_delegated` suspends for client work.
+- Bounded workflow render-block assembly by open sets, frames, and UTF-8 bytes;
+  malformed or invalid completions now produce typed diagnostics instead of
+  disappearing silently.
+- Expanded TypeScript checking to include every projection source and test.
+
 ## 0.2.1 — 2026-08-24
 
 - Published the documented workflow projection entry point that workspace
   consumers already used but the immutable 0.2.0 registry artifact omitted.
+- Added the portable workflow `node_stream` projection inlet with strict
+  answer/reasoning separation, bounded render-block assembly, replay
+  suppression, and shadowed-text state.
 - Added every request and workflow projection test to the normal package test
   gate; the previous Vitest include list silently ran only stream and
   presentation tests.
 
 ## 0.2.0 — 2026-08-22
 
-- Added the portable workflow `node_stream` projection inlet with strict
-  answer/reasoning separation, bounded render-block assembly, replay
-  suppression, and shadowed-text state.
 - Added a framework-free request event projector for identity, status, answer/reasoning, phases, operations, tools, render blocks, Content IR metadata, completion, and errors.
 - Added golden lifecycle fixtures, replay suppression, and copy-on-write guarantees.
 - Added conditional ESM/CommonJS artifacts and loader canaries for mixed Vite, Next.js, and Jest consumers.

package/README.md

@@ -1,8 +1,8 @@
 # @ai-matrx/agents
 
-Portable client-side primitives for AI Matrx agent applications. Version 1 is
-intentionally narrow: it standardizes the stream wire boundary and the safe
-Creator-facing result boundary without importing React, Redux, Next.js, or any
+Portable client-side primitives for AI Matrx agent applications. The package
+standardizes the stream wire, pure request/workflow projection, and safe
+Creator-facing result boundaries without importing React, Redux, Next.js, or
 application code.
 
 ## Install
@@ -25,8 +25,30 @@ for await (const envelope of readMatrxNdjsonStream(response.body!, {
 ```
 
 The reader preserves split UTF-8, drains the network independently of consumer
-work, supports cancellation, normalizes full and compact Matrx envelopes, and
-reports malformed or unknown input through explicit callbacks.
+work up to the configurable `maxReadAhead` bound, supports cancellation,
+normalizes full and compact Matrx envelopes, and reports malformed or unknown
+input through explicit callbacks. `onValidEnvelope` observes the exact parsed
+wire value before normalization without consuming it. Full-envelope
+`stream_seq` is preserved for projector replay suppression.
+
+## Frame non-ReadableStream transports
+
+```ts
+import { createMatrxNdjsonFramer } from "@ai-matrx/agents/stream/ndjson";
+
+const framer = createMatrxNdjsonFramer({
+  onMalformedLine: reportProtocolDamage,
+  onValidEnvelope: persistRawEnvelope,
+});
+
+handleEvents(framer.pushBytes(extensionMessageBytes));
+handleEvents(framer.pushText(desktopBridgeFragment));
+handleEvents(framer.finish());
+```
+
+The same incremental framer works with browser-extension messages, desktop
+bridges, WebSockets, and tests. `finish()` flushes split UTF-8 and diagnoses an
+invalid unterminated final line with `atCompletion: true`.
 
 ## Present a settled result safely
 
@@ -55,7 +77,47 @@ node = projectWorkflowNodeEvent(node, nodeStreamFrame);
 This is the single workflow presentation inlet. It keeps answer and private
 reasoning separate, rejects replayed frames, assembles bounded server
 `render_block` snapshots, and prevents shadowed text from being interpreted as
-a second copy of the same content.
+a second copy of the same content. Configure `maxOpenFrameSets`,
+`maxFramesPerBlock`, and `maxBytesPerBlock` when creating the projection;
+rejected or malformed blocks are observable through `lastRenderBlockIssue`.
+
+## Run an agent end-to-end (`./matrx`)
+
+The `@ai-matrx/agents/matrx` subpath is the Matrx API client. You inject ONE
+fetch-shaped transport — base URL, credentials (user JWT, guest fingerprint,
+or API key), the org header, and retry policy are yours; the package owns the
+wire semantics (paths, bodies, streaming headers, the `Last-Event-ID` cursor):
+
+```ts
+import {
+  newEphemeralConversationStart,
+  runAgentToCompletion,
+  type MatrxTransport,
+} from "@ai-matrx/agents/matrx";
+
+const transport: MatrxTransport = {
+  fetch: (path, init) =>
+    fetch(`https://server.app.matrxserver.com${path}`, {
+      ...init,
+      headers: { ...init.headers, Authorization: `Bearer ${token}` },
+    }),
+};
+
+const run = await runAgentToCompletion(transport, agentId, {
+  ...newEphemeralConversationStart(),
+  organization_id: orgId,
+  user_input: "Summarize this quarter's numbers.",
+}, { onChunk: (text) => render(text) });
+```
+
+Lower-level pieces: `startAgentRun` / `continueAgentConversation` /
+`resumeAgentConversation` return a `MatrxRunHandle` (`X-Request-ID` and
+`X-Conversation-ID` before any event, plus the normalized envelope stream);
+`cancelAgentRun` stops a run by its server request id;
+`getRuntimeOperationStatus` / `listRuntimeOperationEvents` /
+`followRuntimeOperationEvents` / `rejoinRuntimeOperation` are the reconnect
+ladder; `submitAgentToolResults` + pending-call discovery drive delegated
+client tools (watch `continuation_needed` → `resumeAgentConversation`).
 
 ## Runtime support