@ai-matrx/agents

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

pnpm add @ai-matrx/agents

Read an agent stream

import { readMatrxNdjsonStream } from "@ai-matrx/agents/stream/ndjson";

for await (const envelope of readMatrxNdjsonStream(response.body!, {
  onMalformedLine: reportProtocolDamage,
  onUnknownEnvelope: reportUnknownEnvelope,
})) {
  handleEvent(envelope);
}

The reader preserves split UTF-8, drains the network independently of consumer 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

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

import { projectAgentResultForDisplay } from "@ai-matrx/agents/presentation/result";

const displayValue = projectAgentResultForDisplay(persistedExecutionValue);

The projection removes provider-private reasoning blocks and signature material without mutating the execution value. It is only for display, JSON views, and exports. Never persist the projected result or use it to continue an agent run.

Project workflow live output

import {
  createWorkflowNodeProjection,
  projectWorkflowNodeEvent,
} from "@ai-matrx/agents/projection/workflow";

let node = createWorkflowNodeProjection({ runId, nodeId });
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. Configure maxOpenFrameSets, maxFramesPerBlock, and maxBytesPerBlock when creating the projection; rejected or malformed blocks are observable through lastRenderBlockIssue.

Runtime support

The package is framework-free ESM targeting modern browsers, browser-based desktop shells, extensions, Next.js client or server modules, and Node 20+. It has no runtime dependencies and performs no work at import time.

Development

pnpm typecheck
pnpm test
pnpm check:package

check:package builds JavaScript and declarations, validates the manifest, packs the release artifact, checks its public types, installs it into an empty project, and imports every entry point.

Never publish directly from this working directory. Release the verified tarball produced by pnpm pack; prepublishOnly blocks the unsafe path.