@inflexa-ai/harness 0.45.0 → 0.46.0

package/dist/contracts/chat-events.d.ts

@@ -1,7 +1,7 @@
 /**
  * Chat-stream events — the harness wire vocabulary.
  *
- * Distinct from the 15 `data-*` chat parts (`chat-parts.ts`): those are UI
+ * Distinct from the `data-*` chat parts (`chat-parts.ts`): those are UI
  * presentation payloads a tool emits; these are the agent-loop stream events
  * the host chat route frames as SSE. Together they are the sole
  * host↔frontend wire contract — there is no AI SDK UI Message Stream
@@ -17,18 +17,18 @@ import type { TokenUsageRollup } from "./usage.js";
  * call chain that reached it (e.g. `["conversation-agent"]`, or
  * `["conversation-agent", "literature-reviewer"]` for a sub-agent).
  */
-export interface EventSource {
+export type EventSource = {
     agentId: string;
     callPath: string[];
     /** The id of the tool call that runs this loop. For a data profile, the workflow id of its attempt. */
     invocationId?: string;
-}
+};
 /** A run of assistant text. Deltas accumulate into the turn's reply. */
-export interface TextDeltaEvent {
+export type TextDeltaEvent = {
     type: "text-delta";
     text: string;
     source: EventSource;
-}
+};
 /**
  * How a tool call ended.
  *
@@ -71,12 +71,12 @@ export type ToolCallDetail = string;
  * A sub-agent loop started a request to its model. Only a sub-agent gives this frame, thus a consumer that
  * keeps the root frames only (`isRootFrame`) never sees it. A host reads it as "the sub-agent thinks".
  */
-export interface IterationEvent {
+export type IterationEvent = {
     type: "iteration";
     source: EventSource;
-}
+};
 /** A tool call has been dispatched. */
-export interface ToolStartedEvent {
+export type ToolStartedEvent = {
     type: "tool-started";
     /** The Anthropic `tool_use` block id — pairs with `tool-finished`. */
     toolUseId: string;
@@ -85,9 +85,9 @@ export interface ToolStartedEvent {
     /** See {@link ToolCallDetail}. Absent — never empty — when none was produced. */
     detail?: ToolCallDetail;
     source: EventSource;
-}
+};
 /** A tool call has resolved. */
-export interface ToolFinishedEvent {
+export type ToolFinishedEvent = {
     type: "tool-finished";
     toolUseId: string;
     name: string;
@@ -110,7 +110,7 @@ export interface ToolFinishedEvent {
      */
     durationMs?: number;
     source: EventSource;
-}
+};
 /**
  * The agent loop produced its terminal reply — the turn is complete.
  *
@@ -119,34 +119,58 @@ export interface ToolFinishedEvent {
  * `ChatErrorEvent` and therefore no rollup at all — the usage-record ledger,
  * not this event, is the complete account of what a turn spent.
  */
-export interface FinishEvent {
+export type FinishEvent = {
     type: "finish";
     source: EventSource;
-    /** What this loop's own LLM calls used, the forced wrap-up included. */
+    /** What this loop's own LLM calls used. */
     usage?: TokenUsageRollup;
     /**
      * The whole turn's total — this loop's calls plus every descendant loop's
      * (sub-agent tools included). Present only on the turn's root loop.
      */
     turnUsage?: TokenUsageRollup;
-}
+};
 /** The turn failed. `reason` is a machine-readable code when one applies. */
-export interface ChatErrorEvent {
+export type ChatErrorEvent = {
     type: "error";
     /** Human-readable, scrubbed error message. */
     message: string;
     /**
-     * Machine-readable failure code. For a turn that a `suspend` error failed, it
-     * is the suspend reason of the host, carried unread (`suspensionOfFailure`).
+     * Machine-readable failure code. A turn workflow pauses on a `suspend` error, thus only a turn with no workflow
+     * carries the suspend reason of the host here, unread.
      */
     reason?: string;
     source: EventSource;
-}
+};
+/**
+ * The id that the stored display gives a message of the turn. The frames after it belong to that message, up to
+ * the next `message-start` of the same role. The user message carries its text, because the turn stores it only
+ * with its first round, and a reader of the stream before that round has no other source of it.
+ */
+export type MessageStartEvent = {
+    type: "message-start";
+    messageId: string;
+    role: "user";
+    text: string;
+    source: EventSource;
+} | {
+    type: "message-start";
+    messageId: string;
+    role: "assistant";
+    source: EventSource;
+};
 /** The discriminated union of all chat-stream events. */
-export type ChatEvent = TextDeltaEvent | IterationEvent | ToolStartedEvent | ToolFinishedEvent | FinishEvent | ChatErrorEvent;
-/** A `data-*` part as a frame, with the source of its emitter when the emitter stamped one. */
-export type ChatPartFrame = ChatPart & {
+export type ChatEvent = TextDeltaEvent | IterationEvent | ToolStartedEvent | ToolFinishedEvent | FinishEvent | ChatErrorEvent | MessageStartEvent;
+/**
+ * A `data-*` part as a frame, with the source of its emitter when the emitter stamped one. A part whose type the
+ * part registry does not know rides as the emitter sent it — a newer emitter can lead the registry — so the frame
+ * also admits that record shape. The `data-` prefix stays required, so the loop-event narrowings exclude it.
+ */
+export type ChatPartFrame = (ChatPart & {
     source?: EventSource;
-};
+}) | ({
+    type: `data-${string}`;
+    source?: EventSource;
+} & Record<string, unknown>);
 /** One frame of a chat stream or a run stream: a loop event or a `data-*` part. */
 export type ChatFrame = ChatEvent | ChatPartFrame;

package/dist/contracts/chat-events.js

@@ -1,7 +1,7 @@
 /**
  * Chat-stream events — the harness wire vocabulary.
  *
- * Distinct from the 15 `data-*` chat parts (`chat-parts.ts`): those are UI
+ * Distinct from the `data-*` chat parts (`chat-parts.ts`): those are UI
  * presentation payloads a tool emits; these are the agent-loop stream events
  * the host chat route frames as SSE. Together they are the sole
  * host↔frontend wire contract — there is no AI SDK UI Message Stream

package/dist/contracts/chat-frame.d.ts

@@ -1,14 +1,15 @@
 import type { ChatDataPart, EmitEvent } from "../loop/types.js";
 import type { ChatStreamEvent } from "../providers/types.js";
-import type { ChatErrorEvent, ChatFrame, ChatPartFrame } from "./chat-events.js";
+import type { ChatErrorEvent, ChatFrame, ChatPartFrame, EventSource } from "./chat-events.js";
+import type { KnownChatPart } from "./chat-parts.js";
 import type { ChatMessage, MessagePart } from "./message.js";
 export type TurnTerminal = null | "finish" | {
     error: ChatErrorEvent;
 };
-export interface ApplyFrameResult {
+export type ApplyFrameResult = {
     messages: ChatMessage[];
     terminal: TurnTerminal;
-}
+};
 export type ChatPartCheck = {
     readonly ok: true;
     readonly frame: ChatPartFrame;
@@ -24,7 +25,7 @@ export declare function flattenDataPart(part: Pick<ChatDataPart, "type" | "data"
     type: `data-${string}`;
 } & Record<string, unknown>;
 /**
- * The frame of one emitted event, or `null` for `done` and for an `iteration` of the root agent. A frame of a sub-agent
+ * The frame of one emitted event, or `null` for an `iteration` of the root agent. A frame of a sub-agent
  * keeps its source, thus a consumer can filter it. A `text-delta` has no source, thus its frame gets `fallbackSource`,
  * the source of the root agent. A part frame is not checked here: {@link checkChatPart} checks it where it arrives.
  */
@@ -34,7 +35,16 @@ export declare function toChatFrame(event: EmitEvent | ChatStreamEvent | ChatDat
  * does not know. A type that the registry does not know passes unchanged, because a newer emitter can send it. The
  * source is checked for each type, because {@link isRootFrame} reads its call path.
  */
-export declare function checkChatPart(frame: ChatPartFrame): ChatPartCheck;
+export declare function checkChatPart(value: unknown): ChatPartCheck;
+/**
+ * Whether the frame is a part whose type the registry knows. The guard narrows by the registry key alone
+ * and does not re-validate the payload. That is safe on the arrival path only: the payload of a known part
+ * was schema-checked by {@link checkChatPart} where the frame arrived, so a frame that passed the check
+ * and holds a known key carries the checked part with the source it arrived with.
+ */
+export declare function isKnownPartFrame(frame: ChatPartFrame): frame is KnownChatPart & {
+    source?: EventSource;
+};
 /** A frame of the root agent of a chat turn, whose call path is `[agent.id]`. A longer path is a sub-agent. */
 export declare function isRootFrame(frame: ChatFrame): boolean;
 /**

package/dist/contracts/chat-frame.js

@@ -1,13 +1,23 @@
 // The one translation path of a chat stream. Browser-safe: each import from outside `contracts/` is a type import.
-import { isReconciling, PART_REGISTRY } from "./part-registry.js";
+import { z } from "zod";
+import { isKnownPartType, isReconciling } from "./part-registry.js";
 import { EventSourceSchema } from "./schemas/chat-events.js";
 import { ChatPartSchema } from "./schemas/chat-parts.js";
+/** The module imports no value from outside `contracts/` (browser-safe), so the generic record schema lives here. */
+const UnknownRecordSchema = z.record(z.string(), z.unknown());
+const ChatPartFrameSchema = z.looseObject({ type: z.templateLiteral(["data-", z.string()]), source: EventSourceSchema.optional() });
+/**
+ * The frame that {@link ChatPartFrameSchema} checked, given back as it arrived. The parse rebuilds the
+ * record and strips each field of `source` that the source schema does not know, but the passthrough
+ * contract of a type the registry does not know is byte for byte, so the arm returns the original
+ * record and not the parse's copy of it.
+ */
+const UnchangedFrameSchema = z.custom((value) => ChatPartFrameSchema.safeParse(value).success);
 function toSource(source) {
-    return {
-        agentId: source.agentId,
-        callPath: [...source.callPath],
-        ...(source.invocationId === undefined ? {} : { invocationId: source.invocationId }),
-    };
+    const frame = { agentId: source.agentId, callPath: [...source.callPath] };
+    if (source.invocationId !== undefined)
+        frame.invocationId = source.invocationId;
+    return frame;
 }
 /**
  * The wire shape of a data part, `{ ...data, type }`, which is the flat shape of the part contracts. The chat stream
@@ -17,11 +27,14 @@ export function flattenDataPart(part) {
     // The payload is `unknown`, and the spread is not checked here. The chat stream checks each frame with `checkChatPart`.
     // On the run stream the producer builds the payload with the fields of its part contract, and the synthesis-sink test
     // parses the result with `RunSynthesisPartSchema`.
-    const data = (part.data ?? {});
-    return { ...data, type: part.type };
+    const data = UnknownRecordSchema.safeParse(part.data ?? {});
+    let payload = {};
+    if (data.success)
+        payload = data.data;
+    return { ...payload, type: part.type };
 }
 /**
- * The frame of one emitted event, or `null` for `done` and for an `iteration` of the root agent. A frame of a sub-agent
+ * The frame of one emitted event, or `null` for an `iteration` of the root agent. A frame of a sub-agent
  * keeps its source, thus a consumer can filter it. A `text-delta` has no source, thus its frame gets `fallbackSource`,
  * the source of the root agent. A part frame is not checked here: {@link checkChatPart} checks it where it arrives.
  */
@@ -31,14 +44,12 @@ export function toChatFrame(event, fallbackSource) {
             // The root loop gives none: a consumer of the root frames, for example the first-frame time of a
             // browser, must not read the start of a model request as output.
             return event.source.callPath.length > 1 ? { type: "iteration", source: toSource(event.source) } : null;
-        case "done":
-            return null;
         case "tool-started":
             return {
                 type: "tool-started",
                 toolUseId: event.toolUseId,
                 name: event.name,
-                ...(event.detail === undefined ? {} : { detail: event.detail }),
+                detail: event.detail,
                 source: toSource(event.source),
             };
         case "tool-finished":
@@ -47,16 +58,19 @@ export function toChatFrame(event, fallbackSource) {
                 toolUseId: event.toolUseId,
                 name: event.name,
                 outcome: event.outcome,
-                ...(event.detail === undefined ? {} : { detail: event.detail }),
-                ...(event.durationMs === undefined ? {} : { durationMs: event.durationMs }),
+                detail: event.detail,
+                durationMs: event.durationMs,
                 source: toSource(event.source),
             };
         case "text-delta":
             return { type: "text-delta", text: event.text, source: toSource(fallbackSource) };
+        case "message-start":
+            return event.role === "user"
+                ? { type: "message-start", messageId: event.messageId, role: "user", text: event.text, source: toSource(event.source) }
+                : { type: "message-start", messageId: event.messageId, role: "assistant", source: toSource(event.source) };
         default: {
-            // The cast names the frame that the type claims. `checkChatPart` is the check.
             const part = flattenDataPart(event);
-            return { ...part, ...(event.source === undefined ? {} : { source: toSource(event.source) }) };
+            return { ...part, source: event.source === undefined ? undefined : toSource(event.source) };
         }
     }
 }
@@ -65,20 +79,27 @@ export function toChatFrame(event, fallbackSource) {
  * does not know. A type that the registry does not know passes unchanged, because a newer emitter can send it. The
  * source is checked for each type, because {@link isRootFrame} reads its call path.
  */
-export function checkChatPart(frame) {
-    const { source, ...part } = frame;
-    if (source !== undefined) {
-        const checkedSource = EventSourceSchema.safeParse(source);
-        if (!checkedSource.success)
-            return { ok: false, error: checkedSource.error.message };
-    }
-    if (!Object.hasOwn(PART_REGISTRY, frame.type))
-        return { ok: true, frame };
+export function checkChatPart(value) {
+    const frame = ChatPartFrameSchema.safeParse(value);
+    if (!frame.success)
+        return { ok: false, error: frame.error.message };
+    const { source, ...part } = frame.data;
+    if (!isKnownPartType(frame.data.type))
+        return { ok: true, frame: UnchangedFrameSchema.parse(value) };
     const parsed = ChatPartSchema.safeParse(part);
     if (!parsed.success)
         return { ok: false, error: parsed.error.message };
     return { ok: true, frame: source === undefined ? parsed.data : { ...parsed.data, source } };
 }
+/**
+ * Whether the frame is a part whose type the registry knows. The guard narrows by the registry key alone
+ * and does not re-validate the payload. That is safe on the arrival path only: the payload of a known part
+ * was schema-checked by {@link checkChatPart} where the frame arrived, so a frame that passed the check
+ * and holds a known key carries the checked part with the source it arrived with.
+ */
+export function isKnownPartFrame(frame) {
+    return isKnownPartType(frame.type);
+}
 /** A frame of the root agent of a chat turn, whose call path is `[agent.id]`. A longer path is a sub-agent. */
 export function isRootFrame(frame) {
     return frame.source === undefined || frame.source.callPath.length <= 1;
@@ -90,7 +111,7 @@ export function isRootFrame(frame) {
 export function reconcileKey(part) {
     if (part.type === "tool-call")
         return `tool-call:${part.toolCallId}`;
-    if (part.type === "text" || !Object.hasOwn(PART_REGISTRY, part.type) || !isReconciling(part.type))
+    if (part.type === "text" || !isKnownPartType(part.type) || !isReconciling(part.type))
         return undefined;
     return "id" in part && typeof part.id === "string" ? `${part.type}:${part.id}` : undefined;
 }
@@ -117,6 +138,11 @@ export function applyChatFrame(messages, frame, assistantId) {
     if (frame.type === "error") {
         return { messages, terminal: { error: frame } };
     }
+    if (frame.type === "message-start") {
+        if (frame.role === "assistant" || messages.some((message) => message.id === frame.messageId))
+            return { messages, terminal: null };
+        return { messages: [...messages, { id: frame.messageId, role: "user", parts: [{ type: "text", text: frame.text }] }], terminal: null };
+    }
     if (frame.type === "iteration")
         return { messages, terminal: null };
     const partFrame = frame;
@@ -134,7 +160,7 @@ function applyPartFrame(parts, frame) {
                     type: "tool-call",
                     toolCallId: frame.toolUseId,
                     toolName: frame.name,
-                    ...(frame.detail === undefined ? {} : { detail: frame.detail }),
+                    detail: frame.detail,
                 },
             ];
         case "tool-finished": {
@@ -143,23 +169,24 @@ function applyPartFrame(parts, frame) {
                 toolCallId: frame.toolUseId,
                 toolName: frame.name,
                 outcome: frame.outcome,
-                ...(frame.detail === undefined ? {} : { detail: frame.detail }),
-                ...(frame.durationMs === undefined ? {} : { durationMs: frame.durationMs }),
             };
-            let started = false;
-            const next = parts.map((p) => {
-                if (p.type !== "tool-call" || p.toolCallId !== frame.toolUseId)
-                    return p;
-                started = true;
-                return { ...p, ...finished };
-            });
-            // The stored transcript keeps a call whose start never arrived, thus a live view keeps it too.
-            return started ? next : [...parts, finished];
+            if (frame.detail !== undefined)
+                finished.detail = frame.detail;
+            if (frame.durationMs !== undefined)
+                finished.durationMs = frame.durationMs;
+            const started = parts.some((p) => p.type === "tool-call" && p.toolCallId === frame.toolUseId);
+            if (!started) {
+                // The stored transcript keeps a call whose start never arrived, thus a live view keeps it too.
+                return [...parts, finished];
+            }
+            return parts.map((p) => (p.type !== "tool-call" || p.toolCallId !== frame.toolUseId ? p : { ...p, ...finished }));
         }
         default: {
+            // A chat event type that no case above takes is not a part frame, thus this annotation fails to compile.
+            const partFrame = frame;
             // The source routes the frame, and it is not a field of the part. A rest type does not distribute over the
-            // union of the part frames, thus the cast names the part that remains.
-            const { source: _source, ...part } = frame;
+            // union of the part frames, thus the rest names the part that remains.
+            const { source: _source, ...part } = partFrame;
             return upsertPart(parts, part);
         }
     }