@hsb3/carbon-agui-adapter 0.1.0

package/dist/validate.js

@@ -0,0 +1,99 @@
+// ---------------------------------------------------------------------------
+// Runtime type-safety at the two AG-UI/Carbon trust boundaries (issue gmb9).
+//
+//  - IN  seam: every event the runner yields, validated against the protocol's
+//    own schema (@ag-ui/core EventSchemas) before the adapter switches on it.
+//  - OUT seam: every CUSTOM-carried Carbon item, validated for a known
+//    response_type plus its required top-level fields before it is emitted.
+//
+// Both validators are shallow by design: gross malformation is what crosses a
+// trust boundary, and a shallow check catches it cheaply without duplicating
+// the whole Carbon schema here. Nested items (card.body, carousel.items, grid
+// cells) are NOT recursed — a possible follow-up if deep validation is wanted.
+// ---------------------------------------------------------------------------
+import { EventSchemas } from '@ag-ui/core';
+/**
+ * IN seam. Validate a raw runner event against the AG-UI protocol schema.
+ * On success the parsed value is a canonical event; the cast to the adapter's
+ * local `AgUiEvent` is justified because it was validated against the
+ * protocol's own union and the local type is a structural subset the switch
+ * handles. On failure, `error` is zod's error summary.
+ */
+export function validateAgUiEvent(raw) {
+    const result = EventSchemas.safeParse(raw);
+    if (result.success)
+        return { ok: true, event: result.data };
+    return { ok: false, error: result.error.message };
+}
+const isObject = (v) => v !== null && typeof v === 'object';
+const isString = (v) => typeof v === 'string';
+/**
+ * OUT seam. Validate a raw CUSTOM-carried Carbon item before the adapter emits
+ * it: it must be an object, carry a `response_type` string in `known` (the
+ * adapter passes its KNOWN_CARBON_TYPES allowlist so this file needs no coverage
+ * import), and satisfy the required top-level fields for that response_type.
+ */
+export function validateCarbonItem(raw, known) {
+    if (!isObject(raw))
+        return { ok: false, reason: 'item is not a non-null object' };
+    const rt = raw.response_type;
+    if (!isString(rt))
+        return { ok: false, reason: 'response_type is not a string' };
+    if (!known.has(rt))
+        return { ok: false, reason: `unknown response_type: ${rt}` };
+    let reason = null;
+    switch (rt) {
+        case 'text':
+        case 'conversational_search':
+            if (!isString(raw.text))
+                reason = `${rt}: text must be a string`;
+            break;
+        case 'option':
+            if (!Array.isArray(raw.options))
+                reason = 'option: options must be an array';
+            break;
+        case 'image':
+        case 'video':
+        case 'audio':
+        case 'iframe':
+            if (!isString(raw.source))
+                reason = `${rt}: source must be a string`;
+            break;
+        case 'carousel':
+            if (!Array.isArray(raw.items))
+                reason = 'carousel: items must be an array';
+            break;
+        case 'grid':
+            if (!Array.isArray(raw.columns) || !Array.isArray(raw.rows)) {
+                reason = 'grid: columns and rows must both be arrays';
+            }
+            break;
+        case 'button':
+            if (!isString(raw.button_type))
+                reason = 'button: button_type must be a string';
+            break;
+        case 'system':
+            if (!isString(raw.title))
+                reason = 'system: title must be a string';
+            break;
+        case 'preview_card':
+            if (!isString(raw.workspace_id))
+                reason = 'preview_card: workspace_id must be a string';
+            break;
+        case 'user_defined':
+            if (!isObject(raw.user_defined))
+                reason = 'user_defined: user_defined must be a non-null object';
+            break;
+        case 'card':
+            // No strictly-required field, but body/footer are arrays when present.
+            if (raw.body !== undefined && !Array.isArray(raw.body))
+                reason = 'card: body must be an array when present';
+            else if (raw.footer !== undefined && !Array.isArray(raw.footer))
+                reason = 'card: footer must be an array when present';
+            break;
+        // date, pause, inline_error: no required field beyond response_type.
+    }
+    if (reason)
+        return { ok: false, reason };
+    return { ok: true, item: raw };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@hsb3/carbon-agui-adapter",
+  "version": "0.1.0",
+  "description": "Adapter that drives IBM Carbon AI Chat from an AG-UI event stream",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "@hsb3:registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "bun run typecheck && bun run test",
+    "coverage": "bun scripts/coverage.ts",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@ag-ui/core": "0.0.58"
+  },
+  "devDependencies": {
+    "@carbon/ai-chat": "1.19.0",
+    "@types/node": "^26.2.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.2.6"
+  }
+}