@kuralle-agents/core 0.13.0 → 0.15.0

package/README.md

@@ -1,6 +1,6 @@
 # @kuralle-agents/core
 
-The runtime and primitives for building conversational AI agents — text and voice — with structured flows, routing, and durable tool execution.
+The runtime and primitives for building conversational AI agents with structured flows, routing, and durable tool execution.
 
 ## Install
 
@@ -54,8 +54,8 @@ const runtime = createRuntime({ agents: [agent], defaultAgentId: 'support' });
 
 const handle = runtime.run({ input: 'Hello', sessionId: 'demo' });
 for await (const part of handle.events) {           // events is a property, not a method
-  if (part.type === 'text-delta') process.stdout.write(part.delta);
-  if (part.type === 'done') console.log('\nSession:', part.sessionId);
+  if (part.type === 'text-delta') process.stdout.write(part.payload.delta);
+  if (part.type === 'done') console.log('\nSession:', part.payload.sessionId);
 }
 await handle;   // resolves to TurnResult once the stream is consumed
 ```
@@ -230,7 +230,7 @@ return handle.toUIMessageStreamResponse({ sessionId: 'demo' });
 
 Kuralle orchestration events (flow telemetry, safety blocks, interactive choices) arrive as typed `data-kuralle-*` parts. Import `KuralleUIMessage` and `KuralleDataParts` for compile-time-safe `message.parts` and `useChat({ onData })` handlers.
 
-For non-UI consumers (curl, custom transports), use `handle.toResponseStream('sse')` to emit raw `HarnessStreamPart` JSON-SSE. Or use `@kuralle-agents/hono-server` — `POST /api/chat/sse` defaults to native `UIMessageStream`; append `?format=raw` for the legacy wire.
+For non-UI consumers (curl, custom transports), use `handle.toResponseStream('sse')` to emit raw `StreamPart` JSON-SSE. Or use `@kuralle-agents/hono-server` — `POST /api/chat/sse` defaults to native `UIMessageStream`; append `?format=raw` for the legacy wire.
 
 ## Related
 

package/dist/ai-sdk/uiMessageStream.d.ts

@@ -1,7 +1,7 @@
 import { type UIMessage } from 'ai';
 import type { ConversationOutcome } from '../outcomes/types.js';
 import type { ChoiceOption } from '../types/selection.js';
-import type { HarnessStreamPart } from '../types/stream.js';
+import type { StreamPart } from '../types/stream.js';
 export type KuralleMetadata = {
     sessionId?: string;
 };
@@ -46,6 +46,6 @@ export type KuralleDataParts = {
     };
 };
 export type KuralleUIMessage = UIMessage<KuralleMetadata, KuralleDataParts>;
-export declare function harnessToUIMessageStream(source: AsyncIterable<HarnessStreamPart>, opts?: {
+export declare function harnessToUIMessageStream(source: AsyncIterable<StreamPart>, opts?: {
     sessionId?: string;
 }): ReadableStream;

package/dist/ai-sdk/uiMessageStream.js

@@ -2,64 +2,64 @@ import { createUIMessageStream, generateId, } from 'ai';
 function writeHarnessPart(part, writer) {
     switch (part.type) {
         case 'text-start':
-            writer.write({ type: 'text-start', id: part.id });
+            writer.write({ type: 'text-start', id: part.payload.id });
             break;
         case 'text-delta':
-            writer.write({ type: 'text-delta', id: part.id, delta: part.delta });
+            writer.write({ type: 'text-delta', id: part.payload.id, delta: part.payload.delta });
             break;
         case 'text-end':
-            writer.write({ type: 'text-end', id: part.id });
+            writer.write({ type: 'text-end', id: part.payload.id });
             break;
         case 'text-cancel':
-            writer.write({ type: 'text-end', id: part.id });
+            writer.write({ type: 'text-end', id: part.payload.id });
             break;
         case 'tool-call':
             writer.write({
                 type: 'tool-input-available',
-                toolCallId: part.toolCallId ?? generateId(),
-                toolName: part.toolName,
-                input: part.args,
+                toolCallId: part.payload.toolCallId ?? generateId(),
+                toolName: part.payload.toolName,
+                input: part.payload.args,
             });
             break;
         case 'tool-result':
             writer.write({
                 type: 'tool-output-available',
-                toolCallId: part.toolCallId ?? 'unknown',
-                output: part.result,
+                toolCallId: part.payload.toolCallId ?? 'unknown',
+                output: part.payload.result,
             });
             break;
         case 'node-enter':
             writer.write({
                 type: 'data-kuralle-node',
-                data: { event: 'enter', node: part.nodeName },
+                data: { event: 'enter', node: part.payload.nodeName },
                 transient: true,
             });
             break;
         case 'node-exit':
             writer.write({
                 type: 'data-kuralle-node',
-                data: { event: 'exit', node: part.nodeName },
+                data: { event: 'exit', node: part.payload.nodeName },
                 transient: true,
             });
             break;
         case 'flow-enter':
             writer.write({
                 type: 'data-kuralle-flow',
-                data: { event: 'enter', flow: part.flow },
+                data: { event: 'enter', flow: part.payload.flow },
                 transient: true,
             });
             break;
         case 'flow-end':
             writer.write({
                 type: 'data-kuralle-flow',
-                data: { event: 'end', flow: part.flow, reason: part.reason },
+                data: { event: 'end', flow: part.payload.flow, reason: part.payload.reason },
                 transient: true,
             });
             break;
         case 'flow-transition':
             writer.write({
                 type: 'data-kuralle-flow',
-                data: { event: 'transition', from: part.from, to: part.to },
+                data: { event: 'transition', from: part.payload.from, to: part.payload.to },
                 transient: true,
             });
             break;
@@ -67,14 +67,18 @@ function writeHarnessPart(part, writer) {
             writer.write({
                 type: 'data-kuralle-handoff',
                 id: generateId(),
-                data: { targetAgent: part.targetAgent, reason: part.reason },
+                data: { targetAgent: part.payload.targetAgent, reason: part.payload.reason },
             });
             break;
         case 'interactive':
             writer.write({
                 type: 'data-kuralle-interactive',
-                id: part.nodeId,
-                data: { nodeId: part.nodeId, prompt: part.prompt, options: part.options },
+                id: part.payload.nodeId,
+                data: {
+                    nodeId: part.payload.nodeId,
+                    prompt: part.payload.prompt,
+                    options: part.payload.options,
+                },
             });
             break;
         case 'safety-blocked':
@@ -83,9 +87,9 @@ function writeHarnessPart(part, writer) {
                 id: generateId(),
                 data: {
                     kind: 'safety-blocked',
-                    moderator: part.moderator,
-                    rationale: part.rationale,
-                    userFacingMessage: part.userFacingMessage,
+                    moderator: part.payload.moderator,
+                    rationale: part.payload.rationale,
+                    userFacingMessage: part.payload.userFacingMessage,
                 },
             });
             break;
@@ -95,8 +99,8 @@ function writeHarnessPart(part, writer) {
                 id: generateId(),
                 data: {
                     kind: 'pipeline-validation-block',
-                    rationale: part.rationale,
-                    userFacingMessage: part.userFacingMessage,
+                    rationale: part.payload.rationale,
+                    userFacingMessage: part.payload.userFacingMessage,
                 },
             });
             break;
@@ -104,35 +108,44 @@ function writeHarnessPart(part, writer) {
             writer.write({
                 type: 'data-kuralle-outcome',
                 id: generateId(),
-                data: { outcome: part.outcome },
+                data: { outcome: part.payload.outcome },
             });
             break;
         case 'interrupted':
             writer.write({
                 type: 'data-kuralle-control',
-                data: { event: 'interrupted', reason: part.reason },
+                data: { event: 'interrupted', reason: part.payload.reason },
                 transient: true,
             });
             break;
         case 'paused':
             writer.write({
                 type: 'data-kuralle-control',
-                data: { event: 'paused', waitingFor: part.waitingFor },
+                data: { event: 'paused', waitingFor: part.payload.waitingFor },
                 transient: true,
             });
             break;
         case 'custom':
             writer.write({
                 type: 'data-kuralle-custom',
-                data: { name: part.name, data: part.data },
+                data: { name: part.payload.name, data: part.payload.data },
                 transient: true,
             });
             break;
         case 'error':
-            throw new Error(part.error);
+            throw new Error(part.payload.error);
         case 'done':
         case 'turn-end':
             break;
+        default: {
+            // Client-channel exhaustiveness guard. Internal-channel parts are
+            // deliberately unmapped here — they never reach a UI client. But a new
+            // `client` variant added without a case above would be silently dropped
+            // on the ADR-0005 default output path, so pin the residual to internal:
+            // adding a client variant without a case fails this assignment.
+            const _internalOnly = part;
+            void _internalOnly;
+        }
     }
 }
 export function harnessToUIMessageStream(source, opts) {
@@ -146,8 +159,8 @@ export function harnessToUIMessageStream(source, opts) {
                 });
             }
             for await (const part of source) {
-                if (part.type === 'done' && part.sessionId) {
-                    doneSessionId = doneSessionId ?? part.sessionId;
+                if (part.type === 'done' && part.payload.sessionId) {
+                    doneSessionId = doneSessionId ?? part.payload.sessionId;
                 }
                 else {
                     writeHarnessPart(part, writer);

package/dist/capabilities/LivePromptAssembler.d.ts

@@ -7,7 +7,7 @@
  * CapabilityHost with Runtime context (working memory, long-term memory,
  * policy injections) and structures the output per audio-model best practices.
  *
- * Adapters (Gemini, OpenAI Realtime, LiveKit) can extend or replace
+ * Adapters can extend or replace
  * the default with backend-specific voice rules and guardrails.
  *
  * Prompt structure follows Google's Live API best practices and

package/dist/capabilities/LivePromptAssembler.js

@@ -7,7 +7,7 @@
  * CapabilityHost with Runtime context (working memory, long-term memory,
  * policy injections) and structures the output per audio-model best practices.
  *
- * Adapters (Gemini, OpenAI Realtime, LiveKit) can extend or replace
+ * Adapters can extend or replace
  * the default with backend-specific voice rules and guardrails.
  *
  * Prompt structure follows Google's Live API best practices and

package/dist/capabilities/index.d.ts

@@ -1,7 +1,7 @@
 import type { ZodTypeAny } from 'zod';
 /**
  * Backend-agnostic tool declaration. Produced by capabilities,
- * consumed by adapters (Gemini, AI SDK, LiveKit).
+ * consumed by adapters (AI SDK and others).
  */
 export interface ToolDeclaration<TInput = unknown, TOutput = unknown> {
     name: string;

package/dist/eval/EvalRunner.js

@@ -25,16 +25,16 @@ export class EvalRunner {
             const handle = runtime.run({ input: turn.input, sessionId });
             for await (const part of handle.events) {
                 if (part.type === 'text-delta') {
-                    response += part.delta;
+                    response += part.payload.delta;
                 }
                 if (part.type === 'tool-call') {
-                    toolsCalled.push(part.toolName);
+                    toolsCalled.push(part.payload.toolName);
                 }
                 if (part.type === 'flow-transition') {
-                    transitions.push({ from: part.from, to: part.to });
+                    transitions.push({ from: part.payload.from, to: part.payload.to });
                 }
                 if (part.type === 'done') {
-                    sessionId = part.sessionId;
+                    sessionId = part.payload.sessionId;
                 }
             }
             await handle;

package/dist/eval/simulation.js

@@ -66,10 +66,11 @@ export async function simulateConversation(options) {
         let reply = '';
         for await (const part of handle.events) {
             if (part.type === 'text-delta')
-                reply += part.delta;
+                reply += part.payload.delta;
             if (part.type === 'tool-call')
-                toolsCalled.push(part.toolName);
-            if (part.type === 'escalation' || (part.type === 'handoff' && part.targetAgent === 'human')) {
+                toolsCalled.push(part.payload.toolName);
+            if (part.type === 'escalation' ||
+                (part.type === 'handoff' && part.payload.targetAgent === 'human')) {
                 escalated = true;
             }
         }

package/dist/events/TurnHandle.d.ts

@@ -1,7 +1,7 @@
-import type { HarnessStreamPart, TurnHandle } from '../types/stream.js';
+import type { StreamPart, TurnHandle } from '../types/stream.js';
 export interface EventBus {
-    emit(part: HarnessStreamPart): void;
-    events(): AsyncIterable<HarnessStreamPart>;
+    emit(part: StreamPart): void;
+    events(): AsyncIterable<StreamPart>;
     close(): void;
 }
 export declare function createEventBus(): EventBus;

package/dist/flow/collectUntilComplete.js

@@ -3,7 +3,7 @@ import { persistTurnUsageFromTurn } from '../runtime/turnTokenUsage.js';
 import { hasPendingUserInput } from '../runtime/channels/inputBuffer.js';
 import { userInputToText } from '../runtime/userInput.js';
 import { resolveCollectExtractionNode } from './nodeBuilders.js';
-import { computeMissingFields, createExtractionSubmitTool, getCollectData, incrementCollectTurns, emitExtractionTelemetry, mergeTurnExtraction, projectCollectData, schemaSatisfied, } from './extraction.js';
+import { computeMissingFields, createExtractionSubmitTool, getCollectData, incrementCollectTurns, emitExtractionTelemetry, mergeTurnExtraction, projectCollectData, schemaSatisfied, invalidCollectFields, setCollectData, } from './extraction.js';
 import { normalizeTransition } from './normalizeTransition.js';
 function appendAssistantMessage(run, text) {
     if (!text.trim()) {
@@ -50,8 +50,31 @@ export async function collectUntilComplete(node, run, driver, ctx, options) {
         const turns = incrementCollectTurns(run.state, node.id);
         const maxTurns = node.maxTurns ?? 10;
         if (turns > maxTurns) {
-            const data = projectCollectData(node, run.state);
-            return normalizeTransition(await node.onComplete(data, run.state));
+            // Running out of turns is not the same as finishing. Calling onComplete here with
+            // required fields still missing hands the rest of the flow a half-filled record and
+            // lets an action node act on it — for an intake SOP that means creating a record
+            // against whatever happened to be in state. Complete only if the node is genuinely
+            // satisfied; otherwise this is a failure to collect, and a human should see it.
+            if (schemaSatisfied(node, run.state)) {
+                const data = projectCollectData(node, run.state);
+                return normalizeTransition(await node.onComplete(data, run.state));
+            }
+            const missing = computeMissingFields(node, getCollectData(run.state, node.id));
+            return normalizeTransition({
+                escalate: `Could not collect ${missing.join(', ')} for "${node.id}" after ${maxTurns} turns.`,
+            });
+        }
+        // Drop any collected value the schema rejects before working out what to ask for.
+        // Without this a value that is present-but-invalid is neither missing (so it is never
+        // re-asked) nor satisfying (so the node never completes) — the loop would spin to
+        // maxTurns. Purging turns an invalid value back into a missing one, which the existing
+        // ask/extract machinery already knows how to chase.
+        const collected = getCollectData(run.state, node.id);
+        const invalid = invalidCollectFields(node, collected);
+        if (invalid.length > 0) {
+            for (const field of invalid)
+                delete collected[field];
+            setCollectData(run.state, node.id, collected);
         }
         const missingBefore = computeMissingFields(node, getCollectData(run.state, node.id));
         const submitTool = createExtractionSubmitTool(node, missingBefore, {
@@ -121,10 +144,10 @@ export function emitCollectAsk(node, run, ctx) {
         return;
     }
     const id = crypto.randomUUID();
-    ctx.emit({ type: 'text-start', id });
-    ctx.emit({ type: 'text-delta', id, delta: text });
-    ctx.emit({ type: 'text-end', id });
-    ctx.emit({ type: 'turn-end' });
+    ctx.emit({ channel: 'client', type: 'text-start', payload: { id } });
+    ctx.emit({ channel: 'client', type: 'text-delta', payload: { id, delta: text } });
+    ctx.emit({ channel: 'client', type: 'text-end', payload: { id } });
+    ctx.emit({ channel: 'internal', type: 'turn-end', payload: {} });
     appendAssistantMessage(run, text);
 }
 function mergeExtractionFromTurn(node, run, turn, ctx) {

package/dist/flow/degrade.js

@@ -7,9 +7,9 @@ export function appendSafeAssistantMessage(run, ctx, text = SAFE_DEGRADED_MESSAG
     const message = { role: 'assistant', content: text };
     run.messages = [...run.messages, message];
     const id = crypto.randomUUID();
-    ctx.emit({ type: 'text-start', id });
-    ctx.emit({ type: 'text-delta', id, delta: text });
-    ctx.emit({ type: 'text-end', id });
+    ctx.emit({ channel: 'client', type: 'text-start', payload: { id } });
+    ctx.emit({ channel: 'client', type: 'text-delta', payload: { id, delta: text } });
+    ctx.emit({ channel: 'client', type: 'text-end', payload: { id } });
 }
 export async function degradeFlowError(flow, registry, run, driver, ctx, dispatchNode) {
     appendSafeAssistantMessage(run, ctx);
@@ -29,6 +29,10 @@ export async function degradeFlowError(flow, registry, run, driver, ctx, dispatc
             // Fall through to graceful end if the escalate node also fails.
         }
     }
-    ctx.emit({ type: 'flow-end', flow: flow.name, reason: 'error_degraded' });
+    ctx.emit({
+        channel: 'internal',
+        type: 'flow-end',
+        payload: { flow: flow.name, reason: 'error_degraded' },
+    });
     return { kind: 'ended', reason: 'error_degraded' };
 }

package/dist/flow/emitInteractive.d.ts

@@ -1,3 +1,3 @@
 import type { FlowNode, FlowState } from '../types/flow.js';
-import type { HarnessStreamPart } from '../types/stream.js';
-export declare function emitInteractiveOnNodeEnter(node: FlowNode, state: FlowState, emit: (part: HarnessStreamPart) => void): void;
+import type { StreamPart } from '../types/stream.js';
+export declare function emitInteractiveOnNodeEnter(node: FlowNode, state: FlowState, emit: (part: StreamPart) => void): void;

package/dist/flow/emitInteractive.js

@@ -35,9 +35,12 @@ export function emitInteractiveOnNodeEnter(node, state, emit) {
         return;
     }
     emit({
+        channel: 'internal',
         type: 'interactive',
-        nodeId: node.id,
-        options: node.choices,
-        prompt: interactivePrompt(node, state),
+        payload: {
+            nodeId: node.id,
+            options: node.choices,
+            prompt: interactivePrompt(node, state),
+        },
     });
 }

package/dist/flow/extraction.d.ts

@@ -1,10 +1,28 @@
+import type { StandardSchemaV1 } from '../types/standard-schema.js';
 import type { CollectNode, FlowState } from '../types/flow.js';
 import type { Tool } from '../types/effectTool.js';
-import type { HarnessStreamPart } from '../types/stream.js';
+import type { StreamPart } from '../types/stream.js';
 export declare function resetCollect(state: FlowState, nodeId: string): void;
 export declare function getCollectData(state: FlowState, nodeId: string): Record<string, unknown>;
+export declare function setCollectData(state: FlowState, nodeId: string, data: Record<string, unknown>): void;
 export declare function incrementCollectTurns(state: FlowState, nodeId: string): number;
 export declare function computeMissingFields(node: CollectNode, data: Record<string, unknown>): string[];
+/**
+ * Fields whose collected value is present but does NOT satisfy the node's schema.
+ *
+ * Completion used to be presence-only: any non-empty value passed, so a model that invented
+ * an enum member (`urgency: "high"` against `z.enum(['emergency','urgent','routine'])`) or
+ * supplied the wrong primitive completed the node and the flow acted on it. The schema was
+ * only ever used to derive key names, never to check a value.
+ *
+ * Only validates synchronously — StandardSchema permits an async validator, and the
+ * completion gate is sync. Zod is sync, which covers every schema in this repo; an async
+ * validator degrades to the old presence-only behaviour rather than blocking.
+ *
+ * NOTE this catches SHAPE, not REFERENT. `unitId: "12B"` is a perfectly valid string; that a
+ * unit by that id does not exist is a domain fact only a tool boundary can know.
+ */
+export declare function invalidCollectFields(node: CollectNode, data: Record<string, unknown>): string[];
 export declare function schemaSatisfied(node: CollectNode, state: FlowState): boolean;
 export declare function projectCollectData(node: CollectNode, state: FlowState): unknown;
 export declare function mergeExtractionData(current: Record<string, unknown>, incoming: Record<string, unknown>): Record<string, unknown>;
@@ -20,4 +38,5 @@ export declare function mergeTurnExtraction(node: CollectNode, state: FlowState,
     name: string;
     result: unknown;
 }>): MergeTurnExtractionResult;
-export declare function emitExtractionTelemetry(node: CollectNode, state: FlowState, incoming: Record<string, unknown>, emit: (part: HarnessStreamPart) => void): void;
+export declare function emitExtractionTelemetry(node: CollectNode, state: FlowState, incoming: Record<string, unknown>, emit: (part: StreamPart) => void): void;
+export declare function inferRequiredFields(schema: StandardSchemaV1): string[];

package/dist/flow/extraction.js

@@ -17,7 +17,7 @@ export function getCollectData(state, nodeId) {
     }
     return {};
 }
-function setCollectData(state, nodeId, data) {
+export function setCollectData(state, nodeId, data) {
     state[collectDataKey(nodeId)] = data;
 }
 function getCollectTurns(state, nodeId) {
@@ -33,9 +33,58 @@ export function computeMissingFields(node, data) {
     const required = node.required ?? inferRequiredFields(node.schema);
     return required.filter((field) => !fieldPopulated(data[field]));
 }
+/**
+ * Fields whose collected value is present but does NOT satisfy the node's schema.
+ *
+ * Completion used to be presence-only: any non-empty value passed, so a model that invented
+ * an enum member (`urgency: "high"` against `z.enum(['emergency','urgent','routine'])`) or
+ * supplied the wrong primitive completed the node and the flow acted on it. The schema was
+ * only ever used to derive key names, never to check a value.
+ *
+ * Only validates synchronously — StandardSchema permits an async validator, and the
+ * completion gate is sync. Zod is sync, which covers every schema in this repo; an async
+ * validator degrades to the old presence-only behaviour rather than blocking.
+ *
+ * NOTE this catches SHAPE, not REFERENT. `unitId: "12B"` is a perfectly valid string; that a
+ * unit by that id does not exist is a domain fact only a tool boundary can know.
+ */
+export function invalidCollectFields(node, data) {
+    const validate = node.schema['~standard']?.validate;
+    if (typeof validate !== 'function')
+        return [];
+    let result;
+    try {
+        result = validate(data);
+    }
+    catch {
+        return [];
+    }
+    if (result instanceof Promise)
+        return [];
+    const issues = result
+        ?.issues;
+    if (!issues?.length)
+        return [];
+    const fields = new Set();
+    for (const issue of issues) {
+        const first = issue.path?.[0];
+        const key = typeof first === 'string'
+            ? first
+            : typeof first?.key === 'string'
+                ? (first.key)
+                : undefined;
+        // Only report fields the node actually collected. An issue on a field that was never
+        // supplied is a missing-field problem, which computeMissingFields already owns.
+        if (key && key in data)
+            fields.add(key);
+    }
+    return [...fields];
+}
 export function schemaSatisfied(node, state) {
     const data = getCollectData(state, node.id);
-    return computeMissingFields(node, data).length === 0;
+    if (computeMissingFields(node, data).length > 0)
+        return false;
+    return invalidCollectFields(node, data).length === 0;
 }
 export function projectCollectData(node, state) {
     // Hand onComplete EVERY field the node collected (all schema keys present in
@@ -129,16 +178,22 @@ export function emitExtractionTelemetry(node, state, incoming, emit) {
         }
     }
     emit({
+        channel: 'internal',
         type: 'custom',
-        name: 'flow.extraction.submission',
-        data: { node: node.id, fieldsAccepted, fieldsRejected },
+        payload: {
+            name: 'flow.extraction.submission',
+            data: { node: node.id, fieldsAccepted, fieldsRejected },
+        },
     });
     const collected = getCollectData(state, node.id);
     const missing = computeMissingFields(node, collected);
     emit({
+        channel: 'internal',
         type: 'custom',
-        name: 'flow.extraction.update',
-        data: { nodeId: node.id, collected, missing },
+        payload: {
+            name: 'flow.extraction.update',
+            data: { nodeId: node.id, collected, missing },
+        },
     });
 }
 function fieldPopulated(value) {
@@ -150,7 +205,7 @@ function fieldPopulated(value) {
     }
     return true;
 }
-function inferRequiredFields(schema) {
+export function inferRequiredFields(schema) {
     const zodSchema = schema;
     if (typeof zodSchema?.shape === 'object') {
         return Object.keys(zodSchema.shape);

package/dist/flow/reduceTransition.d.ts

@@ -1,7 +1,7 @@
 import type { LanguageModel } from 'ai';
 import type { Flow, FlowNode } from '../types/flow.js';
 import type { RunState } from '../runtime/durable/types.js';
-import type { HarnessStreamPart } from '../types/stream.js';
+import type { StreamPart } from '../types/stream.js';
 export interface ReduceTransitionInput {
     fromNodeId: string;
     toNode: FlowNode;
@@ -9,7 +9,7 @@ export interface ReduceTransitionInput {
     flow: Flow;
     model: LanguageModel;
     data?: Record<string, unknown>;
-    emit: (part: HarnessStreamPart) => void;
+    emit: (part: StreamPart) => void;
     abortSignal?: AbortSignal;
 }
 export declare function reduceTransition(input: ReduceTransitionInput): Promise<void>;

package/dist/flow/reduceTransition.js

@@ -8,9 +8,13 @@ function resolveNodeContext(toNode, flow) {
 }
 export async function reduceTransition(input) {
     const { fromNodeId, toNode, run, flow, model, data, emit, abortSignal } = input;
-    emit({ type: 'node-exit', nodeName: fromNodeId });
-    emit({ type: 'flow-transition', from: fromNodeId, to: toNode.id });
-    emit({ type: 'node-enter', nodeName: toNode.id });
+    emit({ channel: 'internal', type: 'node-exit', payload: { nodeName: fromNodeId } });
+    emit({
+        channel: 'internal',
+        type: 'flow-transition',
+        payload: { from: fromNodeId, to: toNode.id },
+    });
+    emit({ channel: 'internal', type: 'node-enter', payload: { nodeName: toNode.id } });
     emitInteractiveOnNodeEnter(toNode, run.state, emit);
     await applyContextStrategy({
         strategy: resolveNodeContext(toNode, flow),

package/dist/flow/runFlow.d.ts

@@ -16,4 +16,15 @@ export type FlowResult = {
 export declare class FlowOscillationError extends Error {
     constructor(from: string, to: string);
 }
+/**
+ * Drop everything a previous run of `flow` collected. Namespaced cache keys AND the
+ * un-namespaced copies `reduceTransition` promotes onto `run.state` via Object.assign.
+ *
+ * Clearing only the cache was not enough. The promoted fields are a plain merge, and
+ * `projectCollectData` omits any field the new extraction did not supply — so an optional
+ * field answered on report #1 (say `accessNotes: "key under the mat"`) and left blank on
+ * report #2 survives the merge and is read by the next action node as if it belonged to
+ * report #2. A work order then ships another unit's access instructions.
+ */
+export declare function clearFlowCollectCache(state: Record<string, unknown>, flow: Flow): void;
 export declare function runFlow(flow: Flow, run: RunState, driver: ChannelDriver, ctx: RunContext, agent?: AgentConfig): Promise<FlowResult>;