@cheerlyai/agentlib-protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cheerly AI
+
+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,77 @@
+# @cheerlyai/agentlib-protocol
+
+Parsers for the conventions agentlib layers on top of the Vercel AI SDK
+stream. Zero dependencies, no DOM — usable from React, Vue, Svelte, a Node
+service rendering a transcript, or a test.
+
+```bash
+npm install @cheerlyai/agentlib-protocol
+```
+
+## Why it exists
+
+The stream is standard: text deltas, tool parts, reasoning, step markers. But
+two things an agent can produce travel *inside* the assistant's text rather
+than as protocol parts, because that is what makes them degrade gracefully — a
+client that knows nothing about them still shows a readable reply instead of a
+hole.
+
+A chatbox that doesn't handle them looks broken: **raw JSON** where a chart
+should be, a **dangling heading** where citations should be.
+
+## Charts
+
+Agents with charts enabled are instructed to write a ```chart fenced block of
+JSON on a fixed schema. Parse it inside your markdown renderer's code-block
+handler:
+
+```ts
+import { parseChartSpec, CHART_LANGUAGE } from "@cheerlyai/agentlib-protocol";
+
+const spec = parseChartSpec(fenceContents);
+// null => not a drawable chart. Render the code block instead: a
+// half-streamed or malformed one is still readable as JSON.
+```
+
+`ChartSpec` is `{ type, title?, unit?, x, series }`, where `type` is one of
+`bar`, `line`, `area`, `stacked_bar`. Validation is strict about the things
+that would make a chart lie — a series whose values don't line up with the
+axis is rejected outright — and caps at 8 series, past which hue stops
+identifying anything.
+
+## Sources
+
+Agents with a knowledge base are instructed to end a reply with a `Sources:`
+section. Split it off so it renders as citations rather than trailing prose:
+
+```ts
+import { splitReply } from "@cheerlyai/agentlib-protocol";
+
+const { body, sources } = splitReply(text);
+```
+
+`sources` is null when there is none — and also while a heading has arrived
+but its list has not, so a "Sources" label never flashes above an empty box
+mid-stream. Recognises `Sources:`, `**Sources**`, `## Sources` and friends,
+because a model asked for a section in prose writes it differently every few
+runs.
+
+## Parts
+
+```ts
+import { isToolPart, toolPartName, OUTPUT_TOOL_PART, RUN_INFO_PART } from "@cheerlyai/agentlib-protocol";
+```
+
+`isToolPart` covers both shapes the protocol uses (`tool-<name>` and
+`dynamic-tool`). `OUTPUT_TOOL_PART` is the part carrying the reply of an agent
+with output fields — it arrives as tool activity, so a renderer that files it
+under "tools" hides the answer. `RUN_INFO_PART` is agentlib's trailer: read it
+via `useChat`'s `onData` and skip it when rendering.
+
+Anything you don't recognise must fall through to nothing rendered.
+
+## Already handled for you
+
+[`@cheerlyai/agentlib-react`](../react) and the script widget do all of this. Reach for
+this package when you are building the UI yourself, or on a stack they don't
+cover.

package/dist/index.cjs

@@ -0,0 +1,85 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  CHART_LANGUAGE: () => CHART_LANGUAGE,
+  OUTPUT_TOOL_PART: () => OUTPUT_TOOL_PART,
+  RUN_INFO_PART: () => RUN_INFO_PART,
+  isToolPart: () => isToolPart,
+  parseChartSpec: () => parseChartSpec,
+  splitReply: () => splitReply,
+  toolPartName: () => toolPartName
+});
+module.exports = __toCommonJS(src_exports);
+var CHART_LANGUAGE = "chart";
+var CHART_TYPES = ["bar", "line", "area", "stacked_bar"];
+var MAX_SERIES = 8;
+function parseChartSpec(raw) {
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof value !== "object" || value === null) return null;
+  const spec = value;
+  if (typeof spec.type !== "string" || !CHART_TYPES.includes(spec.type)) return null;
+  if (!Array.isArray(spec.x) || spec.x.length === 0) return null;
+  if (!Array.isArray(spec.series) || spec.series.length === 0) return null;
+  const x = spec.x.map(String);
+  const series = [];
+  for (const entry of spec.series.slice(0, MAX_SERIES)) {
+    if (typeof entry !== "object" || entry === null) return null;
+    const s = entry;
+    if (!Array.isArray(s.values)) return null;
+    const values = s.values.map(
+      (v) => typeof v === "number" && Number.isFinite(v) ? v : NaN
+    );
+    if (values.length !== x.length || values.some(Number.isNaN)) return null;
+    series.push({ label: typeof s.label === "string" ? s.label : "", values });
+  }
+  if (series.length === 0) return null;
+  return {
+    type: spec.type,
+    title: typeof spec.title === "string" ? spec.title : void 0,
+    unit: typeof spec.unit === "string" ? spec.unit : void 0,
+    x,
+    series
+  };
+}
+var SOURCES_HEADING = /(?:^|\n)\s{0,3}(?:#{1,6}\s*)?(?:\*\*)?Sources\s*:?(?:\*\*)?\s*:?\s*(?:\n|$)/gi;
+function splitReply(text) {
+  const re = new RegExp(SOURCES_HEADING.source, SOURCES_HEADING.flags);
+  let last = null;
+  for (let m; m = re.exec(text); ) last = m;
+  if (!last) return { body: text, sources: null };
+  const sources = text.slice(last.index + last[0].length).trim();
+  if (!sources) return { body: text, sources: null };
+  return { body: text.slice(0, last.index).trimEnd(), sources };
+}
+function isToolPart(type) {
+  return type.startsWith("tool-") || type === "dynamic-tool";
+}
+function toolPartName(part) {
+  return part.type === "dynamic-tool" ? part.toolName ?? "tool" : part.type.slice("tool-".length);
+}
+var OUTPUT_TOOL_PART = "tool-answer";
+var RUN_INFO_PART = "data-run-info";

package/dist/index.d.cts

@@ -0,0 +1,86 @@
+/** The conventions agentlib layers on top of the Vercel AI SDK stream.
+ *
+ * The stream itself is standard: text deltas, tool parts, reasoning, step
+ * markers. But two things an agent can produce travel *inside* the assistant's
+ * text rather than as protocol parts, because that is what makes them
+ * degrade gracefully — a client that knows nothing about them still shows a
+ * readable reply instead of a hole:
+ *
+ * - **Charts** arrive as a ```chart fenced block of JSON on a fixed schema.
+ * - **Sources** arrive as a trailing `Sources:` section.
+ *
+ * Both are written by the model because its instructions ask it to, which
+ * means neither is guaranteed to be well-formed. Every function here is
+ * tolerant: it returns null (or leaves the text alone) rather than throwing,
+ * so a half-streamed block or a hallucinated field costs you a chart, never
+ * the reply around it.
+ *
+ * Zero dependencies and no DOM, so the same parsing runs in a React app, a
+ * Vue one, a Node service rendering a transcript, or a test.
+ */
+/** A chart an agent asked for, validated. */
+type ChartSpec = {
+    type: "bar" | "line" | "area" | "stacked_bar";
+    title?: string;
+    unit?: string;
+    x: string[];
+    series: {
+        label: string;
+        values: number[];
+    }[];
+};
+/** The language tag on the fenced block agents use for charts. */
+declare const CHART_LANGUAGE = "chart";
+/** Parse a ```chart block's contents.
+ *
+ * Returns null for anything that isn't a chart that can be drawn honestly — a
+ * half-streamed block, a hallucinated field, a series whose values do not line
+ * up with the axis. Render the block as code when this returns null: JSON is
+ * readable, a thrown exception is not.
+ */
+declare function parseChartSpec(raw: string): ChartSpec | null;
+/** An assistant reply split into its prose and its citations. */
+type SplitReply = {
+    /** The answer, with the sources section removed. */
+    body: string;
+    /** The markdown of the sources section, or null when there is none. */
+    sources: string | null;
+};
+/** Split a reply's trailing `Sources:` section off from its prose.
+ *
+ * Safe to call on every render, including mid-stream: while the heading has
+ * arrived but its list has not, the text is returned untouched, so a
+ * "Sources" label never flashes above an empty box.
+ *
+ * The *last* heading wins — an answer that discusses the word "sources"
+ * earlier should not have its body truncated at that mention.
+ */
+declare function splitReply(text: string): SplitReply;
+/** Whether a stream part is tool activity, under either of the protocol's two
+ * shapes: `tool-<name>` for a declared tool, `dynamic-tool` for one resolved
+ * at run time (an MCP server's, say). */
+declare function isToolPart(type: string): boolean;
+/** The tool's name, for a part `isToolPart` accepts. */
+declare function toolPartName(part: {
+    type: string;
+    toolName?: string;
+}): string;
+/** The part carrying the reply of an agent configured with `output_fields`.
+ *
+ * Such an agent answers by calling its output tool, so its reply arrives as
+ * tool activity rather than as text. A client that files it under "tools"
+ * renders a collapsed "Used answer" — the answer itself, hidden — and one
+ * that ignores tool parts shows an empty bubble. Treat this part as the
+ * reply. (The embed API refuses these agents outright for that reason; on
+ * `/v1/agents/{id}/chat` they are yours to render.)
+ */
+declare const OUTPUT_TOOL_PART = "tool-answer";
+/** agentlib's trailing data part: run config, usage, and the conversation id.
+ *
+ * It rides in `message.parts` like anything else, so a renderer with no
+ * default case will show it as an unknown blob. Read it via `useChat`'s
+ * `onData` and skip it when rendering.
+ */
+declare const RUN_INFO_PART = "data-run-info";
+
+export { CHART_LANGUAGE, type ChartSpec, OUTPUT_TOOL_PART, RUN_INFO_PART, type SplitReply, isToolPart, parseChartSpec, splitReply, toolPartName };

package/dist/index.d.ts

@@ -0,0 +1,86 @@
+/** The conventions agentlib layers on top of the Vercel AI SDK stream.
+ *
+ * The stream itself is standard: text deltas, tool parts, reasoning, step
+ * markers. But two things an agent can produce travel *inside* the assistant's
+ * text rather than as protocol parts, because that is what makes them
+ * degrade gracefully — a client that knows nothing about them still shows a
+ * readable reply instead of a hole:
+ *
+ * - **Charts** arrive as a ```chart fenced block of JSON on a fixed schema.
+ * - **Sources** arrive as a trailing `Sources:` section.
+ *
+ * Both are written by the model because its instructions ask it to, which
+ * means neither is guaranteed to be well-formed. Every function here is
+ * tolerant: it returns null (or leaves the text alone) rather than throwing,
+ * so a half-streamed block or a hallucinated field costs you a chart, never
+ * the reply around it.
+ *
+ * Zero dependencies and no DOM, so the same parsing runs in a React app, a
+ * Vue one, a Node service rendering a transcript, or a test.
+ */
+/** A chart an agent asked for, validated. */
+type ChartSpec = {
+    type: "bar" | "line" | "area" | "stacked_bar";
+    title?: string;
+    unit?: string;
+    x: string[];
+    series: {
+        label: string;
+        values: number[];
+    }[];
+};
+/** The language tag on the fenced block agents use for charts. */
+declare const CHART_LANGUAGE = "chart";
+/** Parse a ```chart block's contents.
+ *
+ * Returns null for anything that isn't a chart that can be drawn honestly — a
+ * half-streamed block, a hallucinated field, a series whose values do not line
+ * up with the axis. Render the block as code when this returns null: JSON is
+ * readable, a thrown exception is not.
+ */
+declare function parseChartSpec(raw: string): ChartSpec | null;
+/** An assistant reply split into its prose and its citations. */
+type SplitReply = {
+    /** The answer, with the sources section removed. */
+    body: string;
+    /** The markdown of the sources section, or null when there is none. */
+    sources: string | null;
+};
+/** Split a reply's trailing `Sources:` section off from its prose.
+ *
+ * Safe to call on every render, including mid-stream: while the heading has
+ * arrived but its list has not, the text is returned untouched, so a
+ * "Sources" label never flashes above an empty box.
+ *
+ * The *last* heading wins — an answer that discusses the word "sources"
+ * earlier should not have its body truncated at that mention.
+ */
+declare function splitReply(text: string): SplitReply;
+/** Whether a stream part is tool activity, under either of the protocol's two
+ * shapes: `tool-<name>` for a declared tool, `dynamic-tool` for one resolved
+ * at run time (an MCP server's, say). */
+declare function isToolPart(type: string): boolean;
+/** The tool's name, for a part `isToolPart` accepts. */
+declare function toolPartName(part: {
+    type: string;
+    toolName?: string;
+}): string;
+/** The part carrying the reply of an agent configured with `output_fields`.
+ *
+ * Such an agent answers by calling its output tool, so its reply arrives as
+ * tool activity rather than as text. A client that files it under "tools"
+ * renders a collapsed "Used answer" — the answer itself, hidden — and one
+ * that ignores tool parts shows an empty bubble. Treat this part as the
+ * reply. (The embed API refuses these agents outright for that reason; on
+ * `/v1/agents/{id}/chat` they are yours to render.)
+ */
+declare const OUTPUT_TOOL_PART = "tool-answer";
+/** agentlib's trailing data part: run config, usage, and the conversation id.
+ *
+ * It rides in `message.parts` like anything else, so a renderer with no
+ * default case will show it as an unknown blob. Read it via `useChat`'s
+ * `onData` and skip it when rendering.
+ */
+declare const RUN_INFO_PART = "data-run-info";
+
+export { CHART_LANGUAGE, type ChartSpec, OUTPUT_TOOL_PART, RUN_INFO_PART, type SplitReply, isToolPart, parseChartSpec, splitReply, toolPartName };

package/dist/index.js

@@ -0,0 +1,64 @@
+// src/index.ts
+var CHART_LANGUAGE = "chart";
+var CHART_TYPES = ["bar", "line", "area", "stacked_bar"];
+var MAX_SERIES = 8;
+function parseChartSpec(raw) {
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof value !== "object" || value === null) return null;
+  const spec = value;
+  if (typeof spec.type !== "string" || !CHART_TYPES.includes(spec.type)) return null;
+  if (!Array.isArray(spec.x) || spec.x.length === 0) return null;
+  if (!Array.isArray(spec.series) || spec.series.length === 0) return null;
+  const x = spec.x.map(String);
+  const series = [];
+  for (const entry of spec.series.slice(0, MAX_SERIES)) {
+    if (typeof entry !== "object" || entry === null) return null;
+    const s = entry;
+    if (!Array.isArray(s.values)) return null;
+    const values = s.values.map(
+      (v) => typeof v === "number" && Number.isFinite(v) ? v : NaN
+    );
+    if (values.length !== x.length || values.some(Number.isNaN)) return null;
+    series.push({ label: typeof s.label === "string" ? s.label : "", values });
+  }
+  if (series.length === 0) return null;
+  return {
+    type: spec.type,
+    title: typeof spec.title === "string" ? spec.title : void 0,
+    unit: typeof spec.unit === "string" ? spec.unit : void 0,
+    x,
+    series
+  };
+}
+var SOURCES_HEADING = /(?:^|\n)\s{0,3}(?:#{1,6}\s*)?(?:\*\*)?Sources\s*:?(?:\*\*)?\s*:?\s*(?:\n|$)/gi;
+function splitReply(text) {
+  const re = new RegExp(SOURCES_HEADING.source, SOURCES_HEADING.flags);
+  let last = null;
+  for (let m; m = re.exec(text); ) last = m;
+  if (!last) return { body: text, sources: null };
+  const sources = text.slice(last.index + last[0].length).trim();
+  if (!sources) return { body: text, sources: null };
+  return { body: text.slice(0, last.index).trimEnd(), sources };
+}
+function isToolPart(type) {
+  return type.startsWith("tool-") || type === "dynamic-tool";
+}
+function toolPartName(part) {
+  return part.type === "dynamic-tool" ? part.toolName ?? "tool" : part.type.slice("tool-".length);
+}
+var OUTPUT_TOOL_PART = "tool-answer";
+var RUN_INFO_PART = "data-run-info";
+export {
+  CHART_LANGUAGE,
+  OUTPUT_TOOL_PART,
+  RUN_INFO_PART,
+  isToolPart,
+  parseChartSpec,
+  splitReply,
+  toolPartName
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@cheerlyai/agentlib-protocol",
+  "version": "0.1.0",
+  "description": "Parsers for the conventions agentlib layers on the Vercel AI SDK stream — chart blocks and source sections. Framework-agnostic, zero dependencies.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "lint": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3"
+  }
+}