@peakflo/agent-harness 0.0.0-stage → 0.2.2-rc.1

package/dist/runtime/projection.js

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * THE PROJECTION — adapter message parts in, transcript parts out.
+ *
+ * Ported from the single chokepoint in 20x `agent-manager.ts`
+ * (`persistTranscriptEvent`, :5269) through which every piece of live streaming
+ * output passes on its way to the durable log. Keeping it a chokepoint is the
+ * whole reason the 20x transcript is reliable, and it is reproduced here for the
+ * same reason: one function decides what a transcript part IS, so a new backend
+ * cannot invent a second answer.
+ *
+ * THREE FILTERS, IN ORDER, each of which exists because of a real defect:
+ *
+ * 1. NO ID, NO PART. The upsert is keyed on (sessionId, partId); a part with no
+ *    id has no identity, so a second delta for it would insert a duplicate
+ *    instead of updating the first.
+ *
+ * 2. THE EPHEMERAL THREE ARE DROPPED. 'step-start', 'step-finish' and
+ *    'system-status' are UI-only frame markers. Persisting them would put
+ *    thousands of meaningless rows in every transcript and stream each one to
+ *    every reader. Their actual information — duration, token counts — belongs
+ *    in `TurnMetadata`, which is what closes defect G7.
+ *
+ *    The check goes through the SHARED predicate `isEphemeralPartType`, which
+ *    trims and lowercases. A backend emitting ' Step-Start ' must not slip past
+ *    a case-sensitive comparison and corrupt the projection permanently.
+ *
+ * 3. AN EMPTY PART IS DROPPED. The opening frame of a text part that never
+ *    received a delta is a stream artefact, and storing it puts a blank bubble
+ *    in the UI for ever. A part with a payload and no content is KEPT — a tool
+ *    call with arguments and no textual body is perfectly ordinary.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.projectParts = projectParts;
+exports.toIngestPart = toIngestPart;
+const contract_1 = require("../contract");
+const VALID_ROLES = new Set(['user', 'assistant', 'system']);
+/**
+ * The structured carriers, merged into one payload object.
+ *
+ * 20x wrapped questions/todos/taskProgress in a single object and stored it as
+ * one JSONB column, and the mobile and desktop readers both unwrap it that way.
+ * Changing the shape here would silently break both, so it is preserved even
+ * though a flatter shape would be tidier.
+ *
+ * Returns null — not an empty object — when there is nothing to carry, because
+ * `{}` is truthy and would defeat the emptiness filter above.
+ */
+function buildPayload(part) {
+    const hasCarrier = part.questions !== undefined ||
+        part.todos !== undefined ||
+        part.taskProgress !== undefined ||
+        isRichTool(part.tool);
+    if (!hasCarrier) {
+        return null;
+    }
+    const payload = {};
+    if (part.questions !== undefined) {
+        payload.questions = asJson(part.questions);
+    }
+    if (part.todos !== undefined) {
+        payload.todos = asJson(part.todos);
+    }
+    if (part.taskProgress !== undefined) {
+        payload.taskProgress = asJson(part.taskProgress);
+    }
+    if (isRichTool(part.tool)) {
+        payload.tool = asJson(normaliseToolForTranscript(part.tool));
+    }
+    return Object.keys(payload).length > 0 ? payload : null;
+}
+/**
+ * The transcript wire contract renders tool detail as text. Backends are less
+ * strict: Pi emits structured JSON for MCP input, while OpenCode usually emits
+ * a pre-serialised string. Normalise at the runtime boundary so a new adapter
+ * cannot hand React an object where the shared renderer calls string methods.
+ */
+function normaliseToolForTranscript(tool) {
+    if (!tool || typeof tool !== 'object' || Array.isArray(tool))
+        return tool;
+    const copy = { ...tool };
+    for (const key of ['title', 'description', 'input', 'output', 'error']) {
+        const value = copy[key];
+        if (value !== undefined && value !== null && typeof value !== 'string') {
+            copy[key] = displayText(value);
+        }
+    }
+    return copy;
+}
+function displayText(value) {
+    try {
+        const encoded = JSON.stringify(value);
+        return encoded === undefined ? String(value) : encoded;
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * A tool that carries more than a name — status, input, output, an error.
+ *
+ * The bare name goes in the `tool` COLUMN so it can be indexed and filtered;
+ * the rest goes in the payload. Splitting them is what lets a reader show
+ * "Read(src/index.ts)" without parsing JSON for every row in the transcript.
+ */
+function isRichTool(tool) {
+    if (!tool || typeof tool !== 'object') {
+        return false;
+    }
+    const keys = Object.keys(tool);
+    return keys.some((k) => k !== 'name');
+}
+function toolName(tool) {
+    if (typeof tool === 'string') {
+        return tool;
+    }
+    if (tool && typeof tool === 'object') {
+        const name = tool.name;
+        return typeof name === 'string' ? name : null;
+    }
+    return null;
+}
+/**
+ * A role the projection is willing to store.
+ *
+ * Defaults to 'system' rather than throwing, matching 20x. An unknown role from
+ * a new backend must not be able to abort a turn — the transcript is the record
+ * of what happened, and refusing to record it because a field was odd is the
+ * worst possible failure mode.
+ */
+function normaliseRole(role) {
+    return typeof role === 'string' && VALID_ROLES.has(role)
+        ? role
+        : 'system';
+}
+/**
+ * Coerce to something that survives a JSON round trip.
+ *
+ * A tool result can contain anything a backend chose to put there, including a
+ * value that `JSON.stringify` throws on (a BigInt) or silently mangles (a
+ * circular reference). Losing one tool's metadata is acceptable; losing the
+ * turn because a payload would not serialise is not.
+ */
+function asJson(value) {
+    try {
+        return JSON.parse(JSON.stringify(value ?? null));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Project a batch of adapter parts into transcript parts.
+ *
+ * Returns only the parts worth storing. An empty result is an ordinary outcome
+ * — a poll that saw nothing but step markers — and is NOT an error.
+ */
+function projectParts(raw) {
+    const out = [];
+    for (const part of raw) {
+        if (!part || !part.id) {
+            continue;
+        }
+        const partType = part.partType ?? part.type ?? 'text';
+        if ((0, contract_1.isEphemeralPartType)(partType)) {
+            continue;
+        }
+        // `||`, NOT `??`. Nullish coalescing only falls back on null/undefined, so
+        // a backend emitting `{ content: '', text: 'hello' }` — which OpenCode does
+        // for a part whose text arrives on a later field — kept the empty string,
+        // and filter 3 below then dropped the part as "empty". The user's text
+        // vanished with no error anywhere. Both fields mean the same thing here, so
+        // an empty one must yield to a populated one.
+        const content = part.content || part.text || '';
+        const payload = buildPayload(part);
+        // The 20x rule, kept exactly: content OR any structured carrier earns the
+        // part its place. Only a part with neither is dropped.
+        if (content.length === 0 && payload === null) {
+            continue;
+        }
+        out.push({
+            partId: part.id,
+            role: normaliseRole(part.role),
+            content,
+            partType,
+            tool: toolName(part.tool),
+            payload,
+            createdAt: typeof part.receivedAt === 'number' ? part.receivedAt : undefined
+        });
+    }
+    return out;
+}
+/**
+ * Convert a stored part into the wire shape for `POST /ingest`.
+ *
+ * `seq` and `rev` are dropped: they are SERVER-ALLOCATED, and a runner that
+ * could send them could fabricate an ordering or replay an old rev over a newer
+ * one. The contract's `TranscriptPartInput` has no field for either, so this is
+ * enforced by the type rather than by a convention someone must remember.
+ */
+function toIngestPart(part) {
+    return {
+        partId: part.partId,
+        role: part.role,
+        content: part.content,
+        partType: part.partType,
+        tool: part.tool ?? undefined,
+        payload: part.payload ?? undefined,
+        createdAt: new Date(part.createdAt ?? Date.now()).toISOString()
+    };
+}