@ai-matrx/agents 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 — 2026-08-22
+
+- Published the canonical NDJSON stream reader and envelope normalizer.
+- Published the copy-on-write result projection that removes provider-private
+  reasoning and signature material from Creator-facing output.
+- Added strict tests, ESM declarations, packed-artifact validation, and an
+  isolated consumer import canary.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AI Matrix Engine
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @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
+application code.
+
+## Install
+
+```bash
+pnpm add @ai-matrx/agents
+```
+
+## Read an agent stream
+
+```ts
+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, supports cancellation, normalizes full and compact Matrx envelopes, and
+reports malformed or unknown input through explicit callbacks.
+
+## Present a settled result safely
+
+```ts
+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.
+
+## 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
+
+```bash
+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.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { MatrxNdjsonIssue, MatrxStreamEnvelope, ReadMatrxNdjsonOptions, normalizeMatrxStreamEnvelope, readMatrxNdjsonStream } from './stream/ndjson.js';
+export { projectAgentResultForDisplay } from './presentation/result.js';

package/dist/index.js

@@ -0,0 +1,168 @@
+// stream/ndjson.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeMatrxStreamEnvelope(value) {
+  if (!isRecord(value)) return null;
+  if (typeof value.event === "string") {
+    return { event: value.event, data: value.data };
+  }
+  if (value.e === "c" && typeof value.t === "string") {
+    return { event: "chunk", data: { text: value.t } };
+  }
+  if (value.e === "r" && typeof value.t === "string") {
+    return { event: "reasoning_chunk", data: { text: value.t } };
+  }
+  return null;
+}
+async function* readMatrxNdjsonStream(body, options = {}) {
+  const queue = [];
+  let wakeConsumer = null;
+  let readerFinished = false;
+  const enqueue = (item) => {
+    queue.push(item);
+    const wake = wakeConsumer;
+    wakeConsumer = null;
+    wake?.();
+  };
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  const parseLine = (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch (error) {
+      options.onMalformedLine?.({ line: trimmed, error });
+      return;
+    }
+    const envelope = normalizeMatrxStreamEnvelope(parsed);
+    if (envelope) {
+      enqueue({ kind: "event", value: envelope });
+    } else {
+      options.onUnknownEnvelope?.(parsed);
+    }
+  };
+  const onAbort = () => {
+    void reader.cancel(options.signal?.reason).catch(() => void 0);
+  };
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  const readerPromise = (async () => {
+    let buffer = "";
+    try {
+      while (!options.signal?.aborted) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) parseLine(line);
+      }
+      buffer += decoder.decode();
+      if (!options.signal?.aborted && buffer.trim()) parseLine(buffer);
+    } catch (error) {
+      const aborted = options.signal?.aborted || error instanceof Error && error.name === "AbortError";
+      if (!aborted) enqueue({ kind: "error", error });
+    } finally {
+      readerFinished = true;
+      reader.releaseLock();
+      enqueue({ kind: "done" });
+    }
+  })();
+  try {
+    while (true) {
+      if (queue.length === 0) {
+        await new Promise((resolve) => {
+          wakeConsumer = resolve;
+        });
+      }
+      const item = queue.shift();
+      if (!item || item.kind === "done") return;
+      if (item.kind === "error") throw item.error;
+      yield item.value;
+    }
+  } finally {
+    options.signal?.removeEventListener("abort", onAbort);
+    if (!readerFinished) {
+      await reader.cancel().catch(() => void 0);
+    }
+    await readerPromise;
+  }
+}
+
+// presentation/result.ts
+var PRIVATE_REASONING_TYPES = /* @__PURE__ */ new Set([
+  "thinking",
+  "redacted_thinking",
+  "reasoning"
+]);
+var PRIVATE_PROVIDER_KEYS = /* @__PURE__ */ new Set([
+  "thought_signature",
+  "thoughtSignature",
+  "google_thought_signature",
+  "anthropic_signature",
+  "encrypted_content",
+  "signature_encoding"
+]);
+var SIGNATURE_PROVIDERS = /* @__PURE__ */ new Set([
+  "anthropic",
+  "google",
+  "openai"
+]);
+var OPAQUE_SIGNATURE_MIN_LENGTH = 200;
+var OMIT = /* @__PURE__ */ Symbol("omit-provider-private-value");
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPrivateReasoningBlock(value) {
+  return typeof value.type === "string" && PRIVATE_REASONING_TYPES.has(value.type.toLowerCase());
+}
+function isPrivateProviderKey(key, value, parent) {
+  if (PRIVATE_PROVIDER_KEYS.has(key)) return true;
+  if (key !== "signature") return false;
+  const provider = typeof parent.provider === "string" ? parent.provider.toLowerCase() : "";
+  return "signature_encoding" in parent || SIGNATURE_PROVIDERS.has(provider) || typeof value === "string" && value.length >= OPAQUE_SIGNATURE_MIN_LENGTH;
+}
+function project(value) {
+  if (Array.isArray(value)) {
+    let changed2 = false;
+    const output2 = [];
+    for (const item of value) {
+      const projected = project(item);
+      if (projected === OMIT) {
+        changed2 = true;
+        continue;
+      }
+      if (projected !== item) changed2 = true;
+      output2.push(projected);
+    }
+    return changed2 ? output2 : value;
+  }
+  if (!isRecord2(value)) return value;
+  if (isPrivateReasoningBlock(value)) return OMIT;
+  let changed = false;
+  const output = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (isPrivateProviderKey(key, child, value)) {
+      changed = true;
+      continue;
+    }
+    const projected = project(child);
+    if (projected === OMIT) {
+      changed = true;
+      continue;
+    }
+    if (projected !== child) changed = true;
+    output[key] = projected;
+  }
+  return changed ? output : value;
+}
+function projectAgentResultForDisplay(value) {
+  const projected = project(value);
+  return projected === OMIT ? null : projected;
+}
+
+export { normalizeMatrxStreamEnvelope, projectAgentResultForDisplay, readMatrxNdjsonStream };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../stream/ndjson.ts","../presentation/result.ts"],"names":["isRecord","changed","output"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Canonical AI Matrx NDJSON wire kernel.\n *\n * This module is deliberately independent of React, Redux, Next.js, Supabase,\n * and generated application types. Every Matrx client uses it to turn the\n * backend's byte stream into the same normalized `{ event, data }` envelopes.\n * Host runtimes remain responsible for HTTP/auth errors and for deciding what\n * each event means in their state model.\n */\n\nexport interface MatrxStreamEnvelope<TData = unknown> {\n  event: string;\n  data: TData;\n}\n\nexport interface MatrxNdjsonIssue {\n  line: string;\n  error: unknown;\n}\n\nexport interface ReadMatrxNdjsonOptions {\n  signal?: AbortSignal;\n  /** Malformed JSON is non-fatal, but it must never disappear silently. */\n  onMalformedLine?: (issue: MatrxNdjsonIssue) => void;\n  /** Valid JSON with no recognized Matrx event envelope is also non-fatal. */\n  onUnknownEnvelope?: (value: unknown) => void;\n}\n\ntype QueueItem =\n  | { kind: \"event\"; value: MatrxStreamEnvelope }\n  | { kind: \"error\"; error: unknown }\n  | { kind: \"done\" };\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * Normalize both supported Matrx wire shapes:\n *\n * - full: `{ \"event\": \"chunk\", \"data\": { \"text\": \"...\" } }`\n * - compact chunk: `{ \"e\": \"c\", \"t\": \"...\" }`\n * - compact reasoning: `{ \"e\": \"r\", \"t\": \"...\" }`\n */\nexport function normalizeMatrxStreamEnvelope(\n  value: unknown,\n): MatrxStreamEnvelope | null {\n  if (!isRecord(value)) return null;\n\n  if (typeof value.event === \"string\") {\n    return { event: value.event, data: value.data };\n  }\n  if (value.e === \"c\" && typeof value.t === \"string\") {\n    return { event: \"chunk\", data: { text: value.t } };\n  }\n  if (value.e === \"r\" && typeof value.t === \"string\") {\n    return { event: \"reasoning_chunk\", data: { text: value.t } };\n  }\n  return null;\n}\n\n/**\n * Read and normalize a Matrx NDJSON response body without applying consumer\n * backpressure to the network reader. The background read-ahead is important:\n * large tool payloads must keep draining even while React or another host is\n * processing the previous event.\n */\nexport async function* readMatrxNdjsonStream(\n  body: ReadableStream<Uint8Array>,\n  options: ReadMatrxNdjsonOptions = {},\n): AsyncGenerator<MatrxStreamEnvelope, void, undefined> {\n  const queue: QueueItem[] = [];\n  let wakeConsumer: (() => void) | null = null;\n  let readerFinished = false;\n\n  const enqueue = (item: QueueItem): void => {\n    queue.push(item);\n    const wake = wakeConsumer;\n    wakeConsumer = null;\n    wake?.();\n  };\n\n  const reader = body.getReader();\n  const decoder = new TextDecoder();\n\n  const parseLine = (line: string): void => {\n    const trimmed = line.trim();\n    if (!trimmed) return;\n\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(trimmed) as unknown;\n    } catch (error) {\n      options.onMalformedLine?.({ line: trimmed, error });\n      return;\n    }\n\n    const envelope = normalizeMatrxStreamEnvelope(parsed);\n    if (envelope) {\n      enqueue({ kind: \"event\", value: envelope });\n    } else {\n      options.onUnknownEnvelope?.(parsed);\n    }\n  };\n\n  const onAbort = (): void => {\n    void reader.cancel(options.signal?.reason).catch(() => undefined);\n  };\n  options.signal?.addEventListener(\"abort\", onAbort, { once: true });\n\n  const readerPromise = (async (): Promise<void> => {\n    let buffer = \"\";\n    try {\n      while (!options.signal?.aborted) {\n        const { value, done } = await reader.read();\n        if (done) break;\n\n        buffer += decoder.decode(value, { stream: true });\n        const lines = buffer.split(\"\\n\");\n        buffer = lines.pop() ?? \"\";\n        for (const line of lines) parseLine(line);\n      }\n\n      buffer += decoder.decode();\n      if (!options.signal?.aborted && buffer.trim()) parseLine(buffer);\n    } catch (error) {\n      const aborted =\n        options.signal?.aborted ||\n        (error instanceof Error && error.name === \"AbortError\");\n      if (!aborted) enqueue({ kind: \"error\", error });\n    } finally {\n      readerFinished = true;\n      reader.releaseLock();\n      enqueue({ kind: \"done\" });\n    }\n  })();\n\n  try {\n    while (true) {\n      if (queue.length === 0) {\n        await new Promise<void>((resolve) => {\n          wakeConsumer = resolve;\n        });\n      }\n\n      const item = queue.shift();\n      if (!item || item.kind === \"done\") return;\n      if (item.kind === \"error\") throw item.error;\n      yield item.value;\n    }\n  } finally {\n    options.signal?.removeEventListener(\"abort\", onAbort);\n    if (!readerFinished) {\n      await reader.cancel().catch(() => undefined);\n    }\n    await readerPromise;\n  }\n}\n","/**\n * Creator-facing projection of an agent execution result.\n *\n * Provider reasoning blocks and their signatures are replay material, not\n * workflow data. The execution engine must retain them so a later turn can be\n * continued correctly, but no result renderer, JSON tab, clipboard export, or\n * Content IR classifier should receive them as displayable values.\n *\n * This is a pure copy-on-write projection: values without private material\n * keep their original reference, while affected branches are cloned. Never\n * feed the projected value back into execution or persistence.\n */\n\nconst PRIVATE_REASONING_TYPES: ReadonlySet<string> = new Set([\n  \"thinking\",\n  \"redacted_thinking\",\n  \"reasoning\",\n]);\n\nconst PRIVATE_PROVIDER_KEYS: ReadonlySet<string> = new Set([\n  \"thought_signature\",\n  \"thoughtSignature\",\n  \"google_thought_signature\",\n  \"anthropic_signature\",\n  \"encrypted_content\",\n  \"signature_encoding\",\n]);\n\nconst SIGNATURE_PROVIDERS: ReadonlySet<string> = new Set([\n  \"anthropic\",\n  \"google\",\n  \"openai\",\n]);\n\nconst OPAQUE_SIGNATURE_MIN_LENGTH = 200;\nconst OMIT = Symbol(\"omit-provider-private-value\");\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isPrivateReasoningBlock(value: Record<string, unknown>): boolean {\n  return (\n    typeof value.type === \"string\" &&\n    PRIVATE_REASONING_TYPES.has(value.type.toLowerCase())\n  );\n}\n\nfunction isPrivateProviderKey(\n  key: string,\n  value: unknown,\n  parent: Record<string, unknown>,\n): boolean {\n  if (PRIVATE_PROVIDER_KEYS.has(key)) return true;\n  if (key !== \"signature\") return false;\n\n  const provider =\n    typeof parent.provider === \"string\" ? parent.provider.toLowerCase() : \"\";\n  return (\n    \"signature_encoding\" in parent ||\n    SIGNATURE_PROVIDERS.has(provider) ||\n    (typeof value === \"string\" && value.length >= OPAQUE_SIGNATURE_MIN_LENGTH)\n  );\n}\n\nfunction project(value: unknown): unknown | typeof OMIT {\n  if (Array.isArray(value)) {\n    let changed = false;\n    const output: unknown[] = [];\n    for (const item of value) {\n      const projected = project(item);\n      if (projected === OMIT) {\n        changed = true;\n        continue;\n      }\n      if (projected !== item) changed = true;\n      output.push(projected);\n    }\n    return changed ? output : value;\n  }\n\n  if (!isRecord(value)) return value;\n  if (isPrivateReasoningBlock(value)) return OMIT;\n\n  let changed = false;\n  const output: Record<string, unknown> = {};\n  for (const [key, child] of Object.entries(value)) {\n    if (isPrivateProviderKey(key, child, value)) {\n      changed = true;\n      continue;\n    }\n    const projected = project(child);\n    if (projected === OMIT) {\n      changed = true;\n      continue;\n    }\n    if (projected !== child) changed = true;\n    output[key] = projected;\n  }\n  return changed ? output : value;\n}\n\n/**\n * Remove provider-private reasoning material from a value crossing a\n * Creator-facing presentation or export boundary.\n */\nexport function projectAgentResultForDisplay(value: unknown): unknown {\n  const projected = project(value);\n  return projected === OMIT ? null : projected;\n}\n"]}

package/dist/presentation/result.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Creator-facing projection of an agent execution result.
+ *
+ * Provider reasoning blocks and their signatures are replay material, not
+ * workflow data. The execution engine must retain them so a later turn can be
+ * continued correctly, but no result renderer, JSON tab, clipboard export, or
+ * Content IR classifier should receive them as displayable values.
+ *
+ * This is a pure copy-on-write projection: values without private material
+ * keep their original reference, while affected branches are cloned. Never
+ * feed the projected value back into execution or persistence.
+ */
+/**
+ * Remove provider-private reasoning material from a value crossing a
+ * Creator-facing presentation or export boundary.
+ */
+declare function projectAgentResultForDisplay(value: unknown): unknown;
+
+export { projectAgentResultForDisplay };

package/dist/presentation/result.js

@@ -0,0 +1,75 @@
+// presentation/result.ts
+var PRIVATE_REASONING_TYPES = /* @__PURE__ */ new Set([
+  "thinking",
+  "redacted_thinking",
+  "reasoning"
+]);
+var PRIVATE_PROVIDER_KEYS = /* @__PURE__ */ new Set([
+  "thought_signature",
+  "thoughtSignature",
+  "google_thought_signature",
+  "anthropic_signature",
+  "encrypted_content",
+  "signature_encoding"
+]);
+var SIGNATURE_PROVIDERS = /* @__PURE__ */ new Set([
+  "anthropic",
+  "google",
+  "openai"
+]);
+var OPAQUE_SIGNATURE_MIN_LENGTH = 200;
+var OMIT = /* @__PURE__ */ Symbol("omit-provider-private-value");
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPrivateReasoningBlock(value) {
+  return typeof value.type === "string" && PRIVATE_REASONING_TYPES.has(value.type.toLowerCase());
+}
+function isPrivateProviderKey(key, value, parent) {
+  if (PRIVATE_PROVIDER_KEYS.has(key)) return true;
+  if (key !== "signature") return false;
+  const provider = typeof parent.provider === "string" ? parent.provider.toLowerCase() : "";
+  return "signature_encoding" in parent || SIGNATURE_PROVIDERS.has(provider) || typeof value === "string" && value.length >= OPAQUE_SIGNATURE_MIN_LENGTH;
+}
+function project(value) {
+  if (Array.isArray(value)) {
+    let changed2 = false;
+    const output2 = [];
+    for (const item of value) {
+      const projected = project(item);
+      if (projected === OMIT) {
+        changed2 = true;
+        continue;
+      }
+      if (projected !== item) changed2 = true;
+      output2.push(projected);
+    }
+    return changed2 ? output2 : value;
+  }
+  if (!isRecord(value)) return value;
+  if (isPrivateReasoningBlock(value)) return OMIT;
+  let changed = false;
+  const output = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (isPrivateProviderKey(key, child, value)) {
+      changed = true;
+      continue;
+    }
+    const projected = project(child);
+    if (projected === OMIT) {
+      changed = true;
+      continue;
+    }
+    if (projected !== child) changed = true;
+    output[key] = projected;
+  }
+  return changed ? output : value;
+}
+function projectAgentResultForDisplay(value) {
+  const projected = project(value);
+  return projected === OMIT ? null : projected;
+}
+
+export { projectAgentResultForDisplay };
+//# sourceMappingURL=result.js.map
+//# sourceMappingURL=result.js.map

package/dist/presentation/result.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../presentation/result.ts"],"names":["changed","output"],"mappings":"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","file":"result.js","sourcesContent":["/**\n * Creator-facing projection of an agent execution result.\n *\n * Provider reasoning blocks and their signatures are replay material, not\n * workflow data. The execution engine must retain them so a later turn can be\n * continued correctly, but no result renderer, JSON tab, clipboard export, or\n * Content IR classifier should receive them as displayable values.\n *\n * This is a pure copy-on-write projection: values without private material\n * keep their original reference, while affected branches are cloned. Never\n * feed the projected value back into execution or persistence.\n */\n\nconst PRIVATE_REASONING_TYPES: ReadonlySet<string> = new Set([\n  \"thinking\",\n  \"redacted_thinking\",\n  \"reasoning\",\n]);\n\nconst PRIVATE_PROVIDER_KEYS: ReadonlySet<string> = new Set([\n  \"thought_signature\",\n  \"thoughtSignature\",\n  \"google_thought_signature\",\n  \"anthropic_signature\",\n  \"encrypted_content\",\n  \"signature_encoding\",\n]);\n\nconst SIGNATURE_PROVIDERS: ReadonlySet<string> = new Set([\n  \"anthropic\",\n  \"google\",\n  \"openai\",\n]);\n\nconst OPAQUE_SIGNATURE_MIN_LENGTH = 200;\nconst OMIT = Symbol(\"omit-provider-private-value\");\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isPrivateReasoningBlock(value: Record<string, unknown>): boolean {\n  return (\n    typeof value.type === \"string\" &&\n    PRIVATE_REASONING_TYPES.has(value.type.toLowerCase())\n  );\n}\n\nfunction isPrivateProviderKey(\n  key: string,\n  value: unknown,\n  parent: Record<string, unknown>,\n): boolean {\n  if (PRIVATE_PROVIDER_KEYS.has(key)) return true;\n  if (key !== \"signature\") return false;\n\n  const provider =\n    typeof parent.provider === \"string\" ? parent.provider.toLowerCase() : \"\";\n  return (\n    \"signature_encoding\" in parent ||\n    SIGNATURE_PROVIDERS.has(provider) ||\n    (typeof value === \"string\" && value.length >= OPAQUE_SIGNATURE_MIN_LENGTH)\n  );\n}\n\nfunction project(value: unknown): unknown | typeof OMIT {\n  if (Array.isArray(value)) {\n    let changed = false;\n    const output: unknown[] = [];\n    for (const item of value) {\n      const projected = project(item);\n      if (projected === OMIT) {\n        changed = true;\n        continue;\n      }\n      if (projected !== item) changed = true;\n      output.push(projected);\n    }\n    return changed ? output : value;\n  }\n\n  if (!isRecord(value)) return value;\n  if (isPrivateReasoningBlock(value)) return OMIT;\n\n  let changed = false;\n  const output: Record<string, unknown> = {};\n  for (const [key, child] of Object.entries(value)) {\n    if (isPrivateProviderKey(key, child, value)) {\n      changed = true;\n      continue;\n    }\n    const projected = project(child);\n    if (projected === OMIT) {\n      changed = true;\n      continue;\n    }\n    if (projected !== child) changed = true;\n    output[key] = projected;\n  }\n  return changed ? output : value;\n}\n\n/**\n * Remove provider-private reasoning material from a value crossing a\n * Creator-facing presentation or export boundary.\n */\nexport function projectAgentResultForDisplay(value: unknown): unknown {\n  const projected = project(value);\n  return projected === OMIT ? null : projected;\n}\n"]}

package/dist/stream/ndjson.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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;
+    data: TData;
+}
+interface MatrxNdjsonIssue {
+    line: string;
+    error: unknown;
+}
+interface ReadMatrxNdjsonOptions {
+    signal?: AbortSignal;
+    /** Malformed JSON is non-fatal, but it must never disappear silently. */
+    onMalformedLine?: (issue: MatrxNdjsonIssue) => void;
+    /** Valid JSON with no recognized Matrx event envelope is also non-fatal. */
+    onUnknownEnvelope?: (value: unknown) => void;
+}
+/**
+ * Normalize both supported Matrx wire shapes:
+ *
+ * - full: `{ "event": "chunk", "data": { "text": "..." } }`
+ * - compact chunk: `{ "e": "c", "t": "..." }`
+ * - compact reasoning: `{ "e": "r", "t": "..." }`
+ */
+declare function normalizeMatrxStreamEnvelope(value: unknown): MatrxStreamEnvelope | null;
+/**
+ * Read and normalize a Matrx NDJSON response body without applying consumer
+ * backpressure to the network reader. The background read-ahead is important:
+ * large tool payloads must keep draining even while React or another host is
+ * processing the previous event.
+ */
+declare function readMatrxNdjsonStream(body: ReadableStream<Uint8Array>, options?: ReadMatrxNdjsonOptions): AsyncGenerator<MatrxStreamEnvelope, void, undefined>;
+
+export { type MatrxNdjsonIssue, type MatrxStreamEnvelope, type ReadMatrxNdjsonOptions, normalizeMatrxStreamEnvelope, readMatrxNdjsonStream };

package/dist/stream/ndjson.js

@@ -0,0 +1,96 @@
+// stream/ndjson.ts
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeMatrxStreamEnvelope(value) {
+  if (!isRecord(value)) return null;
+  if (typeof value.event === "string") {
+    return { event: value.event, data: value.data };
+  }
+  if (value.e === "c" && typeof value.t === "string") {
+    return { event: "chunk", data: { text: value.t } };
+  }
+  if (value.e === "r" && typeof value.t === "string") {
+    return { event: "reasoning_chunk", data: { text: value.t } };
+  }
+  return null;
+}
+async function* readMatrxNdjsonStream(body, options = {}) {
+  const queue = [];
+  let wakeConsumer = null;
+  let readerFinished = false;
+  const enqueue = (item) => {
+    queue.push(item);
+    const wake = wakeConsumer;
+    wakeConsumer = null;
+    wake?.();
+  };
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  const parseLine = (line) => {
+    const trimmed = line.trim();
+    if (!trimmed) return;
+    let parsed;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch (error) {
+      options.onMalformedLine?.({ line: trimmed, error });
+      return;
+    }
+    const envelope = normalizeMatrxStreamEnvelope(parsed);
+    if (envelope) {
+      enqueue({ kind: "event", value: envelope });
+    } else {
+      options.onUnknownEnvelope?.(parsed);
+    }
+  };
+  const onAbort = () => {
+    void reader.cancel(options.signal?.reason).catch(() => void 0);
+  };
+  options.signal?.addEventListener("abort", onAbort, { once: true });
+  const readerPromise = (async () => {
+    let buffer = "";
+    try {
+      while (!options.signal?.aborted) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) parseLine(line);
+      }
+      buffer += decoder.decode();
+      if (!options.signal?.aborted && buffer.trim()) parseLine(buffer);
+    } catch (error) {
+      const aborted = options.signal?.aborted || error instanceof Error && error.name === "AbortError";
+      if (!aborted) enqueue({ kind: "error", error });
+    } finally {
+      readerFinished = true;
+      reader.releaseLock();
+      enqueue({ kind: "done" });
+    }
+  })();
+  try {
+    while (true) {
+      if (queue.length === 0) {
+        await new Promise((resolve) => {
+          wakeConsumer = resolve;
+        });
+      }
+      const item = queue.shift();
+      if (!item || item.kind === "done") return;
+      if (item.kind === "error") throw item.error;
+      yield item.value;
+    }
+  } finally {
+    options.signal?.removeEventListener("abort", onAbort);
+    if (!readerFinished) {
+      await reader.cancel().catch(() => void 0);
+    }
+    await readerPromise;
+  }
+}
+
+export { normalizeMatrxStreamEnvelope, readMatrxNdjsonStream };
+//# sourceMappingURL=ndjson.js.map
+//# sourceMappingURL=ndjson.js.map

package/dist/stream/ndjson.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../stream/ndjson.ts"],"names":[],"mappings":"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","file":"ndjson.js","sourcesContent":["/**\n * Canonical AI Matrx NDJSON wire kernel.\n *\n * This module is deliberately independent of React, Redux, Next.js, Supabase,\n * and generated application types. Every Matrx client uses it to turn the\n * backend's byte stream into the same normalized `{ event, data }` envelopes.\n * Host runtimes remain responsible for HTTP/auth errors and for deciding what\n * each event means in their state model.\n */\n\nexport interface MatrxStreamEnvelope<TData = unknown> {\n  event: string;\n  data: TData;\n}\n\nexport interface MatrxNdjsonIssue {\n  line: string;\n  error: unknown;\n}\n\nexport interface ReadMatrxNdjsonOptions {\n  signal?: AbortSignal;\n  /** Malformed JSON is non-fatal, but it must never disappear silently. */\n  onMalformedLine?: (issue: MatrxNdjsonIssue) => void;\n  /** Valid JSON with no recognized Matrx event envelope is also non-fatal. */\n  onUnknownEnvelope?: (value: unknown) => void;\n}\n\ntype QueueItem =\n  | { kind: \"event\"; value: MatrxStreamEnvelope }\n  | { kind: \"error\"; error: unknown }\n  | { kind: \"done\" };\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * Normalize both supported Matrx wire shapes:\n *\n * - full: `{ \"event\": \"chunk\", \"data\": { \"text\": \"...\" } }`\n * - compact chunk: `{ \"e\": \"c\", \"t\": \"...\" }`\n * - compact reasoning: `{ \"e\": \"r\", \"t\": \"...\" }`\n */\nexport function normalizeMatrxStreamEnvelope(\n  value: unknown,\n): MatrxStreamEnvelope | null {\n  if (!isRecord(value)) return null;\n\n  if (typeof value.event === \"string\") {\n    return { event: value.event, data: value.data };\n  }\n  if (value.e === \"c\" && typeof value.t === \"string\") {\n    return { event: \"chunk\", data: { text: value.t } };\n  }\n  if (value.e === \"r\" && typeof value.t === \"string\") {\n    return { event: \"reasoning_chunk\", data: { text: value.t } };\n  }\n  return null;\n}\n\n/**\n * Read and normalize a Matrx NDJSON response body without applying consumer\n * backpressure to the network reader. The background read-ahead is important:\n * large tool payloads must keep draining even while React or another host is\n * processing the previous event.\n */\nexport async function* readMatrxNdjsonStream(\n  body: ReadableStream<Uint8Array>,\n  options: ReadMatrxNdjsonOptions = {},\n): AsyncGenerator<MatrxStreamEnvelope, void, undefined> {\n  const queue: QueueItem[] = [];\n  let wakeConsumer: (() => void) | null = null;\n  let readerFinished = false;\n\n  const enqueue = (item: QueueItem): void => {\n    queue.push(item);\n    const wake = wakeConsumer;\n    wakeConsumer = null;\n    wake?.();\n  };\n\n  const reader = body.getReader();\n  const decoder = new TextDecoder();\n\n  const parseLine = (line: string): void => {\n    const trimmed = line.trim();\n    if (!trimmed) return;\n\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(trimmed) as unknown;\n    } catch (error) {\n      options.onMalformedLine?.({ line: trimmed, error });\n      return;\n    }\n\n    const envelope = normalizeMatrxStreamEnvelope(parsed);\n    if (envelope) {\n      enqueue({ kind: \"event\", value: envelope });\n    } else {\n      options.onUnknownEnvelope?.(parsed);\n    }\n  };\n\n  const onAbort = (): void => {\n    void reader.cancel(options.signal?.reason).catch(() => undefined);\n  };\n  options.signal?.addEventListener(\"abort\", onAbort, { once: true });\n\n  const readerPromise = (async (): Promise<void> => {\n    let buffer = \"\";\n    try {\n      while (!options.signal?.aborted) {\n        const { value, done } = await reader.read();\n        if (done) break;\n\n        buffer += decoder.decode(value, { stream: true });\n        const lines = buffer.split(\"\\n\");\n        buffer = lines.pop() ?? \"\";\n        for (const line of lines) parseLine(line);\n      }\n\n      buffer += decoder.decode();\n      if (!options.signal?.aborted && buffer.trim()) parseLine(buffer);\n    } catch (error) {\n      const aborted =\n        options.signal?.aborted ||\n        (error instanceof Error && error.name === \"AbortError\");\n      if (!aborted) enqueue({ kind: \"error\", error });\n    } finally {\n      readerFinished = true;\n      reader.releaseLock();\n      enqueue({ kind: \"done\" });\n    }\n  })();\n\n  try {\n    while (true) {\n      if (queue.length === 0) {\n        await new Promise<void>((resolve) => {\n          wakeConsumer = resolve;\n        });\n      }\n\n      const item = queue.shift();\n      if (!item || item.kind === \"done\") return;\n      if (item.kind === \"error\") throw item.error;\n      yield item.value;\n    }\n  } finally {\n    options.signal?.removeEventListener(\"abort\", onAbort);\n    if (!readerFinished) {\n      await reader.cancel().catch(() => undefined);\n    }\n    await readerPromise;\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@ai-matrx/agents",
+  "version": "0.1.0",
+  "description": "Portable AI Matrx agent stream protocol and safe result-presentation primitives.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "agents",
+    "ndjson",
+    "streaming",
+    "ai-matrx"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AI-Matrix-Engine/aidream.git",
+    "directory": "apps/shared/matrx-agents"
+  },
+  "homepage": "https://github.com/AI-Matrix-Engine/aidream/tree/main/apps/shared/matrx-agents#readme",
+  "bugs": {
+    "url": "https://github.com/AI-Matrix-Engine/aidream/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./stream/ndjson": {
+      "types": "./dist/stream/ndjson.d.ts",
+      "import": "./dist/stream/ndjson.js"
+    },
+    "./presentation/result": {
+      "types": "./dist/presentation/result.d.ts",
+      "import": "./dist/presentation/result.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@types/node": "^24.10.1",
+    "publint": "^0.3.24",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.6"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "check:package": "pnpm build && publint && pnpm verify:tarball",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "verify:tarball": "node ./scripts/verify-tarball.mjs"
+  }
+}