@nanobpm/agentic 0.1.0 → 0.4.0

package/dist/session/normalizer/deepseek.js

@@ -0,0 +1,68 @@
+import { asRecord, optNumber, optString, reqString } from "./record.js";
+const HARNESS = "deepseek";
+function toDrafts(record) {
+    const obj = asRecord(HARNESS, record);
+    switch (obj.kind) {
+        case "message": {
+            const text = optString(HARNESS, obj, "content") ?? optString(HARNESS, obj, "text");
+            if (text === undefined || text.length === 0)
+                return [];
+            const role = optString(HARNESS, obj, "role");
+            return [{ type: role === "user" ? "user" : role === "system" ? "system" : "assistant", text }];
+        }
+        case "reasoning": {
+            const text = optString(HARNESS, obj, "content") ?? optString(HARNESS, obj, "text");
+            const providerContinuation = optString(HARNESS, obj, "continuation");
+            return [
+                {
+                    type: "reasoning",
+                    ...(text !== undefined ? { text } : {}),
+                    ...(providerContinuation !== undefined ? { providerContinuation } : {}),
+                },
+            ];
+        }
+        case "tool": {
+            const callId = reqString(HARNESS, obj, "id");
+            return [
+                {
+                    type: "tool-call",
+                    id: `call:${callId}`,
+                    callId,
+                    name: reqString(HARNESS, obj, "name"),
+                    args: obj.arguments ?? obj.args,
+                },
+            ];
+        }
+        case "tool_result": {
+            const callId = reqString(HARNESS, obj, "id");
+            return [
+                {
+                    type: "tool-result",
+                    id: `result:${callId}`,
+                    callId,
+                    ok: obj.ok !== false,
+                    result: obj.output ?? obj.result,
+                },
+            ];
+        }
+        case "usage":
+            return [
+                {
+                    type: "usage",
+                    inputTokens: optNumber(HARNESS, obj, "input") ?? optNumber(HARNESS, obj, "inputTokens") ?? 0,
+                    outputTokens: optNumber(HARNESS, obj, "output") ?? optNumber(HARNESS, obj, "outputTokens") ?? 0,
+                    ...(typeof obj.model === "string" ? { model: obj.model } : {}),
+                },
+            ];
+        default:
+            return [];
+    }
+}
+export const deepseekNormalizer = {
+    harness: HARNESS,
+    capabilities: { streaming: true, resumeById: true },
+    toDrafts,
+    resume(sessionId) {
+        return { transport: "sdk", sessionId, call: "restore", args: [sessionId] };
+    },
+};

package/dist/session/normalizer/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `@nanobpm/agentic/session/normalizer` — ADR 0062 slice 3 public surface.
+ *
+ * The `stream-json`/native-transcript fallback ingestion backend: the per-harness
+ * {@link HarnessNormalizer} contract, the shared causal-chain linker
+ * ({@link normalizeSession}/{@link linkDrafts}), the capability probe
+ * ({@link capabilityProbe}), and the current-fleet registry that enumerates the
+ * harnesses this slice ships an adapter for. A caller (the ingestion boundary,
+ * slice 5's enrolment gate) looks a harness up by id and gets its normalizer;
+ * {@link probeFleet} folds the whole registry into `durable-resume`
+ * advertisements in one call.
+ *
+ * The registry is derived from the normalizer modules themselves (each is keyed
+ * by its own `harness` id), so there is no second hand-maintained list of harness
+ * names to drift against.
+ */
+export type { CapabilityAdvertisement, DistributiveOmit, DraftEvent, HarnessCapabilities, HarnessNormalizer, ResumeShim, } from "./types.ts";
+export { capabilityProbe, NormalizerDialectError } from "./types.ts";
+export type { LinkOptions } from "./link.ts";
+export { linkDrafts, normalizeSession } from "./link.ts";
+import { claudeNormalizer } from "./claude.ts";
+import { copilotNormalizer } from "./copilot.ts";
+import { deepseekNormalizer } from "./deepseek.ts";
+import { kimiNormalizer } from "./kimi.ts";
+import { piNormalizer } from "./pi.ts";
+import { qwenNormalizer } from "./qwen.ts";
+import { type CapabilityAdvertisement, type HarnessNormalizer } from "./types.ts";
+export { claudeNormalizer, copilotNormalizer, deepseekNormalizer, kimiNormalizer, piNormalizer, qwenNormalizer };
+/** Every fallback normalizer in the current fleet, in reference-dialect order. */
+export declare const FLEET_NORMALIZERS: readonly HarnessNormalizer[];
+/** Registry keyed by `harness` id, derived from {@link FLEET_NORMALIZERS}. */
+export declare const NORMALIZER_REGISTRY: ReadonlyMap<string, HarnessNormalizer>;
+/** Look a harness's normalizer up by id, or `undefined` when it is not in the fleet. */
+export declare function normalizerFor(harness: string): HarnessNormalizer | undefined;
+/** Probe every harness in the fleet for its derived `durable-resume` advertisement. */
+export declare function probeFleet(): readonly CapabilityAdvertisement[];

package/dist/session/normalizer/index.js

@@ -0,0 +1,29 @@
+export { capabilityProbe, NormalizerDialectError } from "./types.js";
+export { linkDrafts, normalizeSession } from "./link.js";
+import { claudeNormalizer } from "./claude.js";
+import { copilotNormalizer } from "./copilot.js";
+import { deepseekNormalizer } from "./deepseek.js";
+import { kimiNormalizer } from "./kimi.js";
+import { piNormalizer } from "./pi.js";
+import { qwenNormalizer } from "./qwen.js";
+import { capabilityProbe } from "./types.js";
+export { claudeNormalizer, copilotNormalizer, deepseekNormalizer, kimiNormalizer, piNormalizer, qwenNormalizer };
+/** Every fallback normalizer in the current fleet, in reference-dialect order. */
+export const FLEET_NORMALIZERS = [
+    copilotNormalizer,
+    claudeNormalizer,
+    qwenNormalizer,
+    kimiNormalizer,
+    piNormalizer,
+    deepseekNormalizer,
+];
+/** Registry keyed by `harness` id, derived from {@link FLEET_NORMALIZERS}. */
+export const NORMALIZER_REGISTRY = new Map(FLEET_NORMALIZERS.map((n) => [n.harness, n]));
+/** Look a harness's normalizer up by id, or `undefined` when it is not in the fleet. */
+export function normalizerFor(harness) {
+    return NORMALIZER_REGISTRY.get(harness);
+}
+/** Probe every harness in the fleet for its derived `durable-resume` advertisement. */
+export function probeFleet() {
+    return FLEET_NORMALIZERS.map(capabilityProbe);
+}

package/dist/session/normalizer/kimi.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Kimi normalizer — ADR 0062 slice 3.
+ *
+ * Driven with `kimi -p --output-format stream-json`. Kimi tags each frame with an
+ * `event` discriminator and folds a tool call and its result under one `tool`
+ * event distinguished by `phase`. Restore is `-S [id]` (`-c` continues the
+ * latest). Streaming + resume-by-id → `durable-resume`.
+ */
+import { type HarnessNormalizer } from "./types.ts";
+export declare const kimiNormalizer: HarnessNormalizer;

package/dist/session/normalizer/kimi.js

@@ -0,0 +1,80 @@
+/**
+ * Kimi normalizer — ADR 0062 slice 3.
+ *
+ * Driven with `kimi -p --output-format stream-json`. Kimi tags each frame with an
+ * `event` discriminator and folds a tool call and its result under one `tool`
+ * event distinguished by `phase`. Restore is `-S [id]` (`-c` continues the
+ * latest). Streaming + resume-by-id → `durable-resume`.
+ */
+import { NormalizerDialectError } from "./types.js";
+import { asRecord, optNumber, optString, reqString } from "./record.js";
+const HARNESS = "kimi";
+function toDrafts(record) {
+    const obj = asRecord(HARNESS, record);
+    switch (obj.event) {
+        case "text": {
+            const text = optString(HARNESS, obj, "text");
+            if (text === undefined || text.length === 0)
+                return [];
+            const role = optString(HARNESS, obj, "role");
+            return [{ type: role === "user" ? "user" : role === "system" ? "system" : "assistant", text }];
+        }
+        case "reasoning": {
+            const text = optString(HARNESS, obj, "text");
+            const providerContinuation = optString(HARNESS, obj, "continuation");
+            return [
+                {
+                    type: "reasoning",
+                    ...(text !== undefined ? { text } : {}),
+                    ...(providerContinuation !== undefined ? { providerContinuation } : {}),
+                },
+            ];
+        }
+        case "tool": {
+            const callId = reqString(HARNESS, obj, "id");
+            const phase = optString(HARNESS, obj, "phase");
+            if (phase === "result") {
+                return [
+                    {
+                        type: "tool-result",
+                        id: `result:${callId}`,
+                        callId,
+                        ok: obj.ok !== false,
+                        result: obj.output ?? obj.result,
+                    },
+                ];
+            }
+            if (phase === "call" || phase === undefined) {
+                return [
+                    {
+                        type: "tool-call",
+                        id: `call:${callId}`,
+                        callId,
+                        name: reqString(HARNESS, obj, "name"),
+                        args: obj.arguments ?? obj.args,
+                    },
+                ];
+            }
+            throw new NormalizerDialectError(HARNESS, `unknown tool phase ${JSON.stringify(phase)}`);
+        }
+        case "usage":
+            return [
+                {
+                    type: "usage",
+                    inputTokens: optNumber(HARNESS, obj, "prompt_tokens") ?? 0,
+                    outputTokens: optNumber(HARNESS, obj, "completion_tokens") ?? 0,
+                    ...(typeof obj.model === "string" ? { model: obj.model } : {}),
+                },
+            ];
+        default:
+            return [];
+    }
+}
+export const kimiNormalizer = {
+    harness: HARNESS,
+    capabilities: { streaming: true, resumeById: true },
+    toDrafts,
+    resume(sessionId) {
+        return { transport: "cli", sessionId, args: ["-S", sessionId] };
+    },
+};

package/dist/session/normalizer/link.d.ts

@@ -0,0 +1,36 @@
+import { type SessionEvent } from "../events.ts";
+import type { DraftEvent, HarnessNormalizer } from "./types.ts";
+export interface LinkOptions {
+    /**
+     * Id generator for drafts that do not carry a native id. Default is
+     * `crypto.randomUUID`, which is unique-safe across repeated
+     * `normalizeSession()` calls for one session (e.g. per chunk / per resume
+     * leg); inject a deterministic generator in tests when stable ids are needed.
+     * It is only consulted when a draft omits `id`.
+     */
+    newId?: () => string;
+    /**
+     * The `parentId` the first linked event points at — the causal predecessor
+     * this transcript continues from. `null` (default) starts a fresh chain; on a
+     * resume the caller passes the last restored event's id so the new events
+     * continue the same chain across the resume boundary.
+     */
+    parentId?: string | null;
+}
+/**
+ * Thread a flat list of {@link DraftEvent}s into a causal chain of canonical
+ * {@link SessionEvent}s: each event's `id` is its native id when it supplied one
+ * else a freshly generated id, and its `parentId` is the id of the event before
+ * it (or {@link LinkOptions.parentId} for the first). Offsets are *not* assigned
+ * here — the authoritative log owns those on `emit` (slice 1); this only records
+ * causality (`parentId`), which survives compaction.
+ */
+export declare function linkDrafts(drafts: readonly DraftEvent[], options?: LinkOptions): SessionEvent[];
+/**
+ * Normalize a whole native transcript through a harness normalizer: map every
+ * record to drafts, then {@link linkDrafts} the concatenation into one canonical
+ * causal chain. This is the fallback backend's public ingestion call — the
+ * mirror of the ACP backend's `session/update` stream, producing the same
+ * {@link SessionEvent}s a caller feeds to a slice-1 `SessionAdapter.emit`.
+ */
+export declare function normalizeSession(normalizer: HarnessNormalizer, records: Iterable<unknown>, options?: LinkOptions): SessionEvent[];

package/dist/session/normalizer/link.js

@@ -0,0 +1,56 @@
+/**
+ * The shared causal-chain linker + stream driver every dialect reuses — ADR 0062
+ * slice 3.
+ *
+ * A {@link HarnessNormalizer} produces {@link DraftEvent}s (semantics only); the
+ * *chaining* — assigning each event a stable `id` and stamping `parentId` as the
+ * id of its predecessor — is identical across every harness dialect, so it lives
+ * here exactly once (derivation over duplication, AGENTS.md). {@link normalizeSession}
+ * is the one entry point a caller uses: it maps a whole native transcript through
+ * a normalizer, links the drafts into a causal chain, and validates every result
+ * against the slice-1 boundary ({@link parseSessionEvent}) so a dialect can never
+ * emit a shape that is not a canonical {@link SessionEvent}.
+ */
+import { randomUUID } from "node:crypto";
+import { parseSessionEvent } from "../events.js";
+/**
+ * Thread a flat list of {@link DraftEvent}s into a causal chain of canonical
+ * {@link SessionEvent}s: each event's `id` is its native id when it supplied one
+ * else a freshly generated id, and its `parentId` is the id of the event before
+ * it (or {@link LinkOptions.parentId} for the first). Offsets are *not* assigned
+ * here — the authoritative log owns those on `emit` (slice 1); this only records
+ * causality (`parentId`), which survives compaction.
+ */
+export function linkDrafts(drafts, options = {}) {
+    const newId = options.newId ?? randomUUID;
+    let parentId = options.parentId ?? null;
+    const linked = [];
+    for (const draft of drafts) {
+        const { id: nativeId, ...rest } = draft;
+        const id = nativeId ?? newId();
+        // Re-validate the fully-formed event at the slice-1 boundary: `rest` carries
+        // the discriminant + payload, and we add the chain fields. parseSessionEvent
+        // *builds* the union member field-by-field (never an as-cast), so a dialect
+        // bug surfaces here as a loud SessionEventShapeError instead of a bad row.
+        const event = parseSessionEvent({ ...rest, id, parentId });
+        linked.push(event);
+        parentId = id;
+    }
+    return linked;
+}
+/**
+ * Normalize a whole native transcript through a harness normalizer: map every
+ * record to drafts, then {@link linkDrafts} the concatenation into one canonical
+ * causal chain. This is the fallback backend's public ingestion call — the
+ * mirror of the ACP backend's `session/update` stream, producing the same
+ * {@link SessionEvent}s a caller feeds to a slice-1 `SessionAdapter.emit`.
+ */
+export function normalizeSession(normalizer, records, options = {}) {
+    const drafts = [];
+    for (const record of records) {
+        for (const draft of normalizer.toDrafts(record)) {
+            drafts.push(draft);
+        }
+    }
+    return linkDrafts(drafts, options);
+}

package/dist/session/normalizer/pi.d.ts

@@ -0,0 +1,13 @@
+/**
+ * pi / little-coder normalizer — ADR 0062 slice 3.
+ *
+ * Driven with `pi -p --mode json` (or `--mode rpc`): a JSON-RPC 2.0 notification
+ * stream. Session content arrives as `method` notifications
+ * (`session/message`, `session/reasoning`, `session/toolCall`,
+ * `session/toolResult`, `session/usage`) with a `params` payload. Restore is
+ * `--session-id <id>` (create-if-missing — the same flag both resumes an
+ * existing session and starts one under a chosen id); `-r` is the short alias and
+ * `--fork` branches. Streaming + resume-by-id → `durable-resume`.
+ */
+import type { HarnessNormalizer } from "./types.ts";
+export declare const piNormalizer: HarnessNormalizer;

package/dist/session/normalizer/pi.js

@@ -0,0 +1,61 @@
+import { asRecord, isRecord, optNumber, optString, reqString } from "./record.js";
+const HARNESS = "pi";
+function params(obj) {
+    return isRecord(obj.params) ? obj.params : {};
+}
+function toDrafts(record) {
+    const obj = asRecord(HARNESS, record);
+    const method = obj.method;
+    if (typeof method !== "string")
+        return []; // a JSON-RPC result/ack, not a notification
+    const p = params(obj);
+    switch (method) {
+        case "session/message": {
+            const text = optString(HARNESS, p, "text");
+            if (text === undefined || text.length === 0)
+                return [];
+            const role = optString(HARNESS, p, "role");
+            return [{ type: role === "user" ? "user" : role === "system" ? "system" : "assistant", text }];
+        }
+        case "session/reasoning": {
+            const text = optString(HARNESS, p, "text");
+            const providerContinuation = optString(HARNESS, p, "continuation");
+            return [
+                {
+                    type: "reasoning",
+                    ...(text !== undefined ? { text } : {}),
+                    ...(providerContinuation !== undefined ? { providerContinuation } : {}),
+                },
+            ];
+        }
+        case "session/toolCall": {
+            const callId = reqString(HARNESS, p, "id");
+            return [{ type: "tool-call", id: `call:${callId}`, callId, name: reqString(HARNESS, p, "name"), args: p.args }];
+        }
+        case "session/toolResult": {
+            const callId = reqString(HARNESS, p, "id");
+            return [{ type: "tool-result", id: `result:${callId}`, callId, ok: p.ok !== false, result: p.result }];
+        }
+        case "session/usage":
+            return [
+                {
+                    type: "usage",
+                    inputTokens: optNumber(HARNESS, p, "inputTokens") ?? 0,
+                    outputTokens: optNumber(HARNESS, p, "outputTokens") ?? 0,
+                    ...(typeof p.model === "string" ? { model: p.model } : {}),
+                },
+            ];
+        default:
+            return [];
+    }
+}
+export const piNormalizer = {
+    harness: HARNESS,
+    capabilities: { streaming: true, resumeById: true },
+    toDrafts,
+    resume(sessionId) {
+        // create-if-missing: `--session-id <id>` resumes it when it exists and starts
+        // it under that id when it does not.
+        return { transport: "cli", sessionId, args: ["--session-id", sessionId] };
+    },
+};

package/dist/session/normalizer/qwen.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Qwen Code normalizer — ADR 0062 slice 3.
+ *
+ * Driven with `qwen -p -o stream-json`. Qwen Code descends from the Gemini CLI,
+ * so its streaming dialect speaks that lineage: `content` frames tagged with a
+ * `role`, `thought` frames for reasoning, and `tool_call_request` /
+ * `tool_call_response` pairs. Restore is `-r <id>` (`-c` continues the latest).
+ * Streaming + resume-by-id → `durable-resume`.
+ */
+import type { HarnessNormalizer } from "./types.ts";
+export declare const qwenNormalizer: HarnessNormalizer;

package/dist/session/normalizer/qwen.js

@@ -0,0 +1,65 @@
+import { asRecord, optNumber, optString, reqString } from "./record.js";
+const HARNESS = "qwen-code";
+function toDrafts(record) {
+    const obj = asRecord(HARNESS, record);
+    switch (obj.type) {
+        case "content": {
+            const role = optString(HARNESS, obj, "role");
+            const text = optString(HARNESS, obj, "text");
+            if (text === undefined || text.length === 0)
+                return [];
+            return [{ type: role === "user" ? "user" : role === "system" ? "system" : "assistant", text }];
+        }
+        case "thought": {
+            // Gemini-lineage reasoning: a bold `subject` + `description` body.
+            const subject = optString(HARNESS, obj, "subject");
+            const description = optString(HARNESS, obj, "description");
+            const text = [subject, description].filter((s) => s !== undefined && s.length > 0).join(": ");
+            const providerContinuation = optString(HARNESS, obj, "thoughtSignature");
+            return [
+                {
+                    type: "reasoning",
+                    ...(text.length > 0 ? { text } : {}),
+                    ...(providerContinuation !== undefined ? { providerContinuation } : {}),
+                },
+            ];
+        }
+        case "tool_call_request": {
+            const callId = reqString(HARNESS, obj, "callId");
+            return [
+                { type: "tool-call", id: `call:${callId}`, callId, name: reqString(HARNESS, obj, "name"), args: obj.args },
+            ];
+        }
+        case "tool_call_response": {
+            const callId = reqString(HARNESS, obj, "callId");
+            return [
+                {
+                    type: "tool-result",
+                    id: `result:${callId}`,
+                    callId,
+                    ok: obj.error == null,
+                    result: obj.responseParts ?? obj.error,
+                },
+            ];
+        }
+        case "usage_metadata":
+            return [
+                {
+                    type: "usage",
+                    inputTokens: optNumber(HARNESS, obj, "promptTokenCount") ?? 0,
+                    outputTokens: optNumber(HARNESS, obj, "candidatesTokenCount") ?? 0,
+                    ...(typeof obj.model === "string" ? { model: obj.model } : {}),
+                },
+            ];
+        default:
+            return [];
+    }
+}
+export const qwenNormalizer = {
+    harness: HARNESS,
+    capabilities: { streaming: true, resumeById: true },
+    toDrafts,
+    resume(sessionId) {
+        return { transport: "cli", sessionId, args: ["-r", sessionId] };
+    },
+};

package/dist/session/normalizer/record.d.ts

@@ -0,0 +1,21 @@
+/** True for a plain (non-array) object; the shape every native record must have. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Narrow to a record or throw a dialect error attributing the harness. */
+export declare function asRecord(harness: string, value: unknown): Record<string, unknown>;
+/** Read a required string field or throw a dialect error. */
+export declare function reqString(harness: string, obj: Record<string, unknown>, field: string): string;
+/** Read an optional string field (undefined when absent), throwing on a wrong type. */
+export declare function optString(harness: string, obj: Record<string, unknown>, field: string): string | undefined;
+/** Read an optional finite number field, coercing absent/null to `undefined`. */
+export declare function optNumber(harness: string, obj: Record<string, unknown>, field: string): number | undefined;
+/** Narrow to an array or throw a dialect error. */
+export declare function asArray(harness: string, value: unknown, what: string): readonly unknown[];
+/**
+ * Collapse a message-content value to plain text. Harnesses model an assistant
+ * message either as a bare string or as an array of typed content parts
+ * (`{ type: "text", text }`); we concatenate the text parts and ignore the rest
+ * (tool-use parts are lifted to their own events by the dialect). Returns
+ * `undefined` when there is no text to emit so the dialect can skip an empty
+ * message.
+ */
+export declare function contentText(value: unknown): string | undefined;

package/dist/session/normalizer/record.js

@@ -0,0 +1,87 @@
+/**
+ * Small untyped-record inspection helpers shared by the per-harness dialect maps
+ * (ADR 0062 slice 3). A native record is untyped input (a `JSON.parse`d
+ * `stream-json` line, an SDK event object), so every dialect narrows it the same
+ * way: is-it-an-object, read-a-string, read-an-optional-string. Centralising the
+ * narrowing keeps the dialects declarative and, crucially, keeps them free of
+ * `as`-casts (AGENTS.md) — they narrow through these guards instead.
+ */
+import { NormalizerDialectError } from "./types.js";
+/** True for a plain (non-array) object; the shape every native record must have. */
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Describe a value for a dialect error: distinguishes `null` and `array` from the bare `typeof`. */
+function describeType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+/** Narrow to a record or throw a dialect error attributing the harness. */
+export function asRecord(harness, value) {
+    if (!isRecord(value)) {
+        throw new NormalizerDialectError(harness, `record must be a plain object, got ${describeType(value)}`);
+    }
+    return value;
+}
+/** Read a required string field or throw a dialect error. */
+export function reqString(harness, obj, field) {
+    const v = obj[field];
+    if (typeof v !== "string") {
+        throw new NormalizerDialectError(harness, `field "${field}" must be a string, got ${describeType(v)}`);
+    }
+    return v;
+}
+/** Read an optional string field (undefined when absent), throwing on a wrong type. */
+export function optString(harness, obj, field) {
+    const v = obj[field];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== "string") {
+        throw new NormalizerDialectError(harness, `field "${field}" must be a string when present, got ${describeType(v)}`);
+    }
+    return v;
+}
+/** Read an optional finite number field, coercing absent/null to `undefined`. */
+export function optNumber(harness, obj, field) {
+    const v = obj[field];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== "number" || !Number.isFinite(v)) {
+        throw new NormalizerDialectError(harness, `field "${field}" must be a finite number when present, got ${describeType(v)}`);
+    }
+    return v;
+}
+/** Narrow to an array or throw a dialect error. */
+export function asArray(harness, value, what) {
+    if (!Array.isArray(value)) {
+        throw new NormalizerDialectError(harness, `${what} must be an array, got ${describeType(value)}`);
+    }
+    return value;
+}
+/**
+ * Collapse a message-content value to plain text. Harnesses model an assistant
+ * message either as a bare string or as an array of typed content parts
+ * (`{ type: "text", text }`); we concatenate the text parts and ignore the rest
+ * (tool-use parts are lifted to their own events by the dialect). Returns
+ * `undefined` when there is no text to emit so the dialect can skip an empty
+ * message.
+ */
+export function contentText(value) {
+    if (typeof value === "string")
+        return value.length > 0 ? value : undefined;
+    if (!Array.isArray(value))
+        return undefined;
+    let text = "";
+    for (const part of value) {
+        if (typeof part === "string") {
+            text += part;
+        }
+        else if (isRecord(part) && part.type === "text" && typeof part.text === "string") {
+            text += part.text;
+        }
+    }
+    return text.length > 0 ? text : undefined;
+}