@kuralle-agents/core 0.14.0 → 0.16.0

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, {

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 { 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>;
@@ -21,3 +39,4 @@ export declare function mergeTurnExtraction(node: CollectNode, state: FlowState,
     result: unknown;
 }>): MergeTurnExtractionResult;
 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
@@ -156,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/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>;

package/dist/flow/runFlow.js

@@ -1,5 +1,6 @@
 import { popFlowPark, runCollectDigression } from './collectDigression.js';
 import { parseConfirmation } from './confirmParse.js';
+import { inferRequiredFields, resetCollect } from './extraction.js';
 import { hasPendingUserInput, setPendingUserInput } from '../runtime/channels/inputBuffer.js';
 import { userInputToText } from '../runtime/userInput.js';
 import { collectUntilComplete } from './collectUntilComplete.js';
@@ -11,7 +12,7 @@ import { evaluateReplyControl } from './controlEvaluator.js';
 import { runNodeVerify, VerifyBlockedError } from './verify.js';
 import { loadRecordedSteps } from '../runtime/durable/replay.js';
 import { persistTurnUsageFromTurn } from '../runtime/turnTokenUsage.js';
-import { isApprovalDenial, isControlFlowSignal } from '../runtime/controlFlowSignal.js';
+import { isApprovalDenial, isControlFlowSignal, isRecoverableToolError } from '../runtime/controlFlowSignal.js';
 import { emitInteractiveOnNodeEnter } from './emitInteractive.js';
 import { appendConversationAudit } from '../audit/record.js';
 import { appendSafeAssistantMessage, degradeFlowError, findEscalateNode, } from './degrade.js';
@@ -253,6 +254,27 @@ async function dispatchNode(node, run, driver, ctx, agent, flow) {
     }
     throw new Error(`Unknown node kind: ${node.kind}`);
 }
+/**
+ * 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 function clearFlowCollectCache(state, flow) {
+    for (const node of flow.nodes) {
+        if (node.kind !== 'collect')
+            continue;
+        delete state[`__collect_${node.id}`];
+        delete state[`__collectTurns_${node.id}`];
+        for (const field of inferRequiredFields(node.schema)) {
+            delete state[field];
+        }
+    }
+}
 export async function runFlow(flow, run, driver, ctx, agent) {
     const registry = buildNodeRegistry(flow);
     const startNode = resolveStartNode(flow);
@@ -262,6 +284,18 @@ export async function runFlow(flow, run, driver, ctx, agent) {
         throw new Error(`Unknown active node "${initialNodeId}" in flow "${flow.name}"`);
     }
     if (!run.activeNode) {
+        // Fresh entry, not a resume. A collect node caches its extraction under
+        // `__collect_<nodeId>` and that cache is SUPPOSED to survive turn boundaries — it is how
+        // fields accumulate across several user turns mid-flow. But it must not survive the flow
+        // itself: re-entering a completed flow found the previous run's cache already complete,
+        // finished instantly with those values, and the action node acted on them.
+        //
+        // Observed live: three maintenance reports for three different units produced three
+        // copies of the FIRST work order; the units actually reported were never touched.
+        //
+        // Cleared here rather than on completion so mid-flow accumulation is untouched — which
+        // is what `continuity.test.ts` and the G14 slot-correction test encode.
+        clearFlowCollectCache(run.state, flow);
         run.activeNode = node.id;
         run.activeFlow = flow.name;
         ctx.emit({ channel: 'internal', type: 'flow-enter', payload: { flow: flow.name } });
@@ -270,7 +304,15 @@ export async function runFlow(flow, run, driver, ctx, agent) {
     }
     const edgeCounts = new Map();
     const maxOscillations = flow.maxOscillations ?? 2;
+    // The node to re-collect from when an action throws a recoverable error (bad referent,
+    // missing precondition). Tracked as the most recent collect node visited in THIS flow
+    // invocation. If an action runs before any collect (no node can re-collect), a
+    // recoverable error degrades exactly as a fatal one would.
+    let lastCollectNode;
     for (;;) {
+        if (isCollectNode(node)) {
+            lastCollectNode = node;
+        }
         let transition;
         try {
             transition = await dispatchNode(node, run, driver, ctx, agent, flow);
@@ -282,6 +324,25 @@ export async function runFlow(flow, run, driver, ctx, agent) {
             if (isControlFlowSignal(error) || isApprovalDenial(error)) {
                 throw error;
             }
+            if (isRecoverableToolError(error) && lastCollectNode) {
+                // The action node called a tool imperatively, so there is no model tool-call to
+                // attach a result to. Carry the message to the model as a system note (the next
+                // extraction/reply turn reads it from history), clear the offending collect's cache
+                // so re-entry genuinely re-collects instead of re-completing with the bad value, and
+                // return to that node. With the cache cleared and the turn's input already consumed
+                // by the collect that fed this action, collectUntilComplete emits its `ask` and
+                // parks on awaitingUser — a real re-ask, not an end.
+                resetCollect(run.state, lastCollectNode.id);
+                const note = {
+                    role: 'system',
+                    content: `Action "${node.id}" could not complete: ${error.message}. Re-collect the affected input from the user before retrying.`,
+                };
+                run.messages = [...run.messages, note];
+                node = lastCollectNode;
+                run.activeNode = node.id;
+                await ctx.runStore.putRunState(run);
+                continue;
+            }
             const message = error instanceof Error ? error.message : String(error);
             ctx.emit({ channel: 'client', type: 'error', payload: { error: message } });
             return degradeFlowError(flow, registry, run, driver, ctx, (n, r, d, c) => dispatchNode(n, r, d, c, agent, flow));

package/dist/runtime/Runtime.d.ts

@@ -21,6 +21,19 @@ import type { WakeOptions } from '../scheduler/index.js';
 import type { HandoffInputFilter } from './handoffFilters.js';
 import type { AgentSpan, AgentTrace } from '../types/trace.js';
 import { type TraceSink, type TraceStore } from '../tracing/TraceStore.js';
+/**
+ * What the user is told when the run hands off to a human and the app has not configured an
+ * escalation handler to say something better. Silence is the wrong default: an escalation
+ * that emits no text is indistinguishable from the agent having crashed.
+ */
+export declare const HANDOFF_TO_HUMAN_MESSAGE = "I'm bringing a colleague into this \u2014 they'll pick it up from here.";
+/**
+ * What the user is told on any turn that arrives WHILE a run is already held for a human.
+ * The agent does not re-run for these turns — without a live `kuralle resume` the session
+ * would otherwise re-escalate every message regardless of topic. Distinct from
+ * `HANDOFF_TO_HUMAN_MESSAGE`, which is the one-time notice emitted on the escalating turn.
+ */
+export declare const HELD_FOR_HUMAN_MESSAGE = "A colleague is already handling this \u2014 I'll pick it back up as soon as they're done.";
 export interface TracingConfig {
     enabled?: boolean;
     store?: TraceStore;

package/dist/runtime/Runtime.js

@@ -35,6 +35,19 @@ import { MemoryTraceStore } from '../tracing/MemoryTraceStore.js';
 import { mutateSessionWithRetry } from '../session/utils.js';
 import { isTraceStore } from '../tracing/TraceStore.js';
 import { runHookSafely } from './runHookSafely.js';
+/**
+ * What the user is told when the run hands off to a human and the app has not configured an
+ * escalation handler to say something better. Silence is the wrong default: an escalation
+ * that emits no text is indistinguishable from the agent having crashed.
+ */
+export const HANDOFF_TO_HUMAN_MESSAGE = "I'm bringing a colleague into this — they'll pick it up from here.";
+/**
+ * What the user is told on any turn that arrives WHILE a run is already held for a human.
+ * The agent does not re-run for these turns — without a live `kuralle resume` the session
+ * would otherwise re-escalate every message regardless of topic. Distinct from
+ * `HANDOFF_TO_HUMAN_MESSAGE`, which is the one-time notice emitted on the escalating turn.
+ */
+export const HELD_FOR_HUMAN_MESSAGE = "A colleague is already handling this — I'll pick it back up as soon as they're done.";
 export class Runtime {
     config;
     agentsById;
@@ -86,7 +99,23 @@ export class Runtime {
         }
         const execute = async () => {
             let runCtx;
+            // Whether the user has been told anything at all this turn. A terminal handoff with
+            // no escalation handler configured used to emit zero text — seven consecutive turns
+            // were observed producing empty output while silently firing transfer_to_agent, which
+            // is indistinguishable from an outage.
+            let sawUserText = false;
+            // Handoff targets already announced this turn. `hostLoop` emits a handoff part when
+            // the transfer control tool fires, and the terminal branch below emits one too —
+            // but only SOME terminal handoffs come through hostLoop's control path (a validator
+            // escalate does not), so neither emitter can be deleted. Deduplicate instead: the
+            // double emit produced a spurious `human -> human` self-edge in the trace, because
+            // by the second emit the recorder's current agent was already the target.
+            const announcedHandoffs = new Set();
             const emit = (part) => {
+                if (part.type === 'text-delta' && part.payload.delta)
+                    sawUserText = true;
+                if (part.type === 'handoff')
+                    announcedHandoffs.add(part.payload.targetAgent);
                 recorder?.record(part);
                 if (part.type === 'done')
                     this.flushTraceSinks();
@@ -142,6 +171,13 @@ export class Runtime {
             // THIS turn's consumption (delta), not the running session total (see the
             // per-turn scope requirement in the observability guide).
             const usageBaseline = readCumulativeUsage(freshRunState.state);
+            // A run parked on a terminal-handoff escalation (status 'paused' with NO `waitingFor`)
+            // is held for a human until `resumeFromEscalation`. It must not re-run the agent —
+            // without this gate every later turn re-escalated, recycling the prior escalation's
+            // reason even for unrelated messages. `waitingFor` is the discriminator: suspend and
+            // approval waits also set status 'paused' but DO set `waitingFor` and resume by
+            // signal; gating those would hang every approval and every suspended tool.
+            const heldForHuman = freshRunState.status === 'paused' && !freshRunState.waitingFor;
             const model = opened.agent.model ?? this.defaultModel;
             if (!model) {
                 throw new Error('Runtime requires agent.model or config.defaultModel');
@@ -191,152 +227,213 @@ export class Runtime {
             let terminalOutcome;
             let overflowRetried = false;
             try {
-                turnLoop: for (;;) {
-                    try {
-                        loopResult = await hostLoop({
-                            agent: activeAgent,
-                            run: runCtx.runState,
-                            driver,
-                            ctx: runCtx,
-                            classify: this.config.hostClassify ??
-                                (this.config.hostSelect ? adaptHostSelect(this.config.hostSelect) : undefined),
-                        });
-                    }
-                    catch (error) {
-                        if (!overflowRetried && this.config.compaction && isContextOverflowError(error)) {
-                            overflowRetried = true;
-                            await this.recoverFromOverflow(runCtx, activeAgent, emit);
-                            continue turnLoop;
-                        }
-                        throw error;
-                    }
-                    if (loopResult.kind === 'handoff') {
-                        if (this.terminalHandoffTargets.has(loopResult.to)) {
-                            emit({
-                                channel: 'internal',
-                                type: 'handoff',
-                                payload: { targetAgent: loopResult.to, reason: loopResult.reason },
+                if (heldForHuman) {
+                    // Mirror the degraded-turn shape so TurnHandle consumers see a normal text +
+                    // `done` and do not hang: the hold message streams once, the turn is persisted,
+                    // and the existing `finally` emits `done` and runs closeRun. The agent never runs.
+                    const heldId = crypto.randomUUID();
+                    emit({ channel: 'client', type: 'text-start', payload: { id: heldId } });
+                    emit({ channel: 'client', type: 'text-delta', payload: { id: heldId, delta: HELD_FOR_HUMAN_MESSAGE } });
+                    emit({ channel: 'client', type: 'text-end', payload: { id: heldId } });
+                    runCtx.runState.messages = [
+                        ...runCtx.runState.messages,
+                        { role: 'assistant', content: HELD_FOR_HUMAN_MESSAGE },
+                    ];
+                    await runCtx.runStore.putRunState(runCtx.runState);
+                    // NOT a terminal outcome: the run stays `paused` (closeRun only flips to
+                    // `finished` when terminalOutcome is set). Setting it would both break the
+                    // hold — the next turn would no longer see `paused` — and trip a stale-version
+                    // outcome mark across multi-turn sessions.
+                    loopResult = { kind: 'ended', reason: 'held_for_human' };
+                }
+                else {
+                    turnLoop: for (;;) {
+                        try {
+                            loopResult = await hostLoop({
+                                agent: activeAgent,
+                                run: runCtx.runState,
+                                driver,
+                                ctx: runCtx,
+                                classify: this.config.hostClassify ??
+                                    (this.config.hostSelect ? adaptHostSelect(this.config.hostSelect) : undefined),
                             });
-                            runCtx.runState.status = 'paused';
-                            await runCtx.runStore.putRunState(runCtx.runState);
-                            await this.dispatchEscalation(runCtx, activeAgent, { reason: loopResult.reason ?? 'handoff_to_human', category: loopResult.category }, emit, { setLatch: false });
-                            break;
-                        }
-                        handoffCount += 1;
-                        if (handoffCount > this.maxHandoffs) {
-                            throw new Error(`maxHandoffs exceeded (${this.maxHandoffs})`);
-                        }
-                        // Cross-turn ping-pong safeguard (handoffCount resets each turn, so it
-                        // can't catch A↔B oscillation spread across turns). This is a bound
-                        // ABOVE maxHandoffs: within-run runaway is caught by the maxHandoffs
-                        // check above; oscillation only fires for same-pair accumulation in the
-                        // persisted handoffHistory beyond that, so it never pre-empts maxHandoffs.
-                        if (isHandoffOscillating(opened.session.handoffHistory, runCtx.runState.activeAgentId, loopResult.to, this.maxHandoffs + 1)) {
-                            throw new Error(`Handoff oscillation detected between "${runCtx.runState.activeAgentId}" and "${loopResult.to}"`);
                         }
-                        const target = this.agentsById.get(loopResult.to);
-                        if (!target) {
-                            throw new Error(`Handoff target agent not found: ${loopResult.to}`);
+                        catch (error) {
+                            if (!overflowRetried && this.config.compaction && isContextOverflowError(error)) {
+                                overflowRetried = true;
+                                await this.recoverFromOverflow(runCtx, activeAgent, emit);
+                                continue turnLoop;
+                            }
+                            throw error;
                         }
-                        opened.session.handoffHistory.push({
-                            from: runCtx.runState.activeAgentId,
-                            to: loopResult.to,
-                            reason: loopResult.reason ?? 'handoff',
-                            timestamp: new Date(),
-                        });
-                        const handoffTarget = loopResult.to;
-                        const routeFilter = activeAgent.routes?.find((r) => r.agent === handoffTarget)?.filter;
-                        const inputFilter = routeFilter ?? this.config.handoffInputFilter;
-                        if (inputFilter) {
-                            const filtered = await inputFilter({
-                                messages: runCtx.runState.messages,
-                                workingMemory: runCtx.session.workingMemory,
-                                sourceAgentId: runCtx.runState.activeAgentId,
-                                targetAgentId: handoffTarget,
-                                reason: loopResult.reason,
+                        if (loopResult.kind === 'handoff') {
+                            if (this.terminalHandoffTargets.has(loopResult.to)) {
+                                // This emit is load-bearing for TERMINAL targets specifically. A terminal
+                                // handoff breaks out of the loop here, before hostLoop's own emit and before
+                                // handoffHistory is appended — so this is the only handoff part a client ever
+                                // sees for an escalation. Removing it as "redundant" silently produced zero
+                                // handoff parts for every escalation; escalation.test.ts catches it.
+                                //
+                                // The self-edge seen live (handoff human->human, two spans on one turn) is a
+                                // real but SEPARATE defect on the non-terminal path — fix it there, not by
+                                // deleting this.
+                                if (!announcedHandoffs.has(loopResult.to)) {
+                                    emit({
+                                        channel: 'internal',
+                                        type: 'handoff',
+                                        payload: { targetAgent: loopResult.to, reason: loopResult.reason },
+                                    });
+                                }
+                                // Record the terminal handoff in handoffHistory. This branch used to `break`
+                                // before the non-terminal push below, so the array stayed empty and
+                                // isHandoffOscillating could never see repeated escalations. The oscillation
+                                // check only runs on the non-terminal branch and only counts consecutive
+                                // same-pair hops, so appending `agent -> human` here cannot trip a false
+                                // oscillation on a later legitimate handoff to a different target.
+                                opened.session.handoffHistory.push({
+                                    from: runCtx.runState.activeAgentId,
+                                    to: loopResult.to,
+                                    reason: loopResult.reason ?? 'handoff',
+                                    timestamp: new Date(),
+                                });
+                                runCtx.runState.status = 'paused';
+                                // Never hand off in silence. dispatchEscalation returns immediately when no
+                                // escalation handler is configured, so without this the turn ends with no
+                                // assistant text at all and the user cannot tell an escalation from a crash.
+                                if (!sawUserText) {
+                                    const handoffId = crypto.randomUUID();
+                                    emit({ channel: 'client', type: 'text-start', payload: { id: handoffId } });
+                                    emit({
+                                        channel: 'client',
+                                        type: 'text-delta',
+                                        payload: { id: handoffId, delta: HANDOFF_TO_HUMAN_MESSAGE },
+                                    });
+                                    emit({ channel: 'client', type: 'text-end', payload: { id: handoffId } });
+                                    runCtx.runState.messages = [
+                                        ...runCtx.runState.messages,
+                                        { role: 'assistant', content: HANDOFF_TO_HUMAN_MESSAGE },
+                                    ];
+                                }
+                                await runCtx.runStore.putRunState(runCtx.runState);
+                                await this.dispatchEscalation(runCtx, activeAgent, { reason: loopResult.reason ?? 'handoff_to_human', category: loopResult.category }, emit, { setLatch: false });
+                                break;
+                            }
+                            handoffCount += 1;
+                            if (handoffCount > this.maxHandoffs) {
+                                throw new Error(`maxHandoffs exceeded (${this.maxHandoffs})`);
+                            }
+                            // Cross-turn ping-pong safeguard (handoffCount resets each turn, so it
+                            // can't catch A↔B oscillation spread across turns). This is a bound
+                            // ABOVE maxHandoffs: within-run runaway is caught by the maxHandoffs
+                            // check above; oscillation only fires for same-pair accumulation in the
+                            // persisted handoffHistory beyond that, so it never pre-empts maxHandoffs.
+                            if (isHandoffOscillating(opened.session.handoffHistory, runCtx.runState.activeAgentId, loopResult.to, this.maxHandoffs + 1)) {
+                                throw new Error(`Handoff oscillation detected between "${runCtx.runState.activeAgentId}" and "${loopResult.to}"`);
+                            }
+                            const target = this.agentsById.get(loopResult.to);
+                            if (!target) {
+                                throw new Error(`Handoff target agent not found: ${loopResult.to}`);
+                            }
+                            opened.session.handoffHistory.push({
+                                from: runCtx.runState.activeAgentId,
+                                to: loopResult.to,
+                                reason: loopResult.reason ?? 'handoff',
+                                timestamp: new Date(),
+                            });
+                            const handoffTarget = loopResult.to;
+                            const routeFilter = activeAgent.routes?.find((r) => r.agent === handoffTarget)?.filter;
+                            const inputFilter = routeFilter ?? this.config.handoffInputFilter;
+                            if (inputFilter) {
+                                const filtered = await inputFilter({
+                                    messages: runCtx.runState.messages,
+                                    workingMemory: runCtx.session.workingMemory,
+                                    sourceAgentId: runCtx.runState.activeAgentId,
+                                    targetAgentId: handoffTarget,
+                                    reason: loopResult.reason,
+                                });
+                                runCtx.runState.messages = filtered.messages;
+                                runCtx.session.workingMemory = filtered.workingMemory;
+                            }
+                            runCtx.runState.activeAgentId = loopResult.to;
+                            activeAgent = target;
+                            const targetSurface = await buildAgentToolSurface(target, opened.session, {
+                                configTools: this.config.tools,
+                                knowledgeProvider,
+                                defaultWorkingMemoryStore: this.config.defaultWorkingMemoryStore,
                             });
-                            runCtx.runState.messages = filtered.messages;
-                            runCtx.session.workingMemory = filtered.workingMemory;
+                            runCtx.autoRetrieve = knowledgeProvider
+                                ? buildAutoRetrieveProvider(knowledgeProvider, target)
+                                : undefined;
+                            runCtx.globalTools = targetSurface.globalTools;
+                            runCtx.skillPrompt = targetSurface.skillPrompt;
+                            runCtx.workingMemoryPrompt = appendGoalsPrompt(targetSurface.workingMemoryPrompt, runCtx.session.workingMemory);
+                            runCtx.workingMemoryTools = targetSurface.workingMemoryTools;
+                            runCtx.fs = targetSurface.resolvedWorkspace?.fs;
+                            runCtx.memoryService = this.config.memoryService
+                                ? buildMemoryService(this.config.memoryService, target)
+                                : undefined;
+                            const targetPolicies = resolveAgentPolicies(target);
+                            const targetModel = target.model ?? this.defaultModel;
+                            if (!targetModel) {
+                                throw new Error('Runtime requires agent.model or config.defaultModel');
+                            }
+                            runCtx.baseInstructions =
+                                (this.config.silentHandoff ?? true)
+                                    ? applyHandoffContinuation(target.instructions)
+                                    : target.instructions;
+                            runCtx.model = targetModel;
+                            runCtx.controlModel = target.controlModel ?? targetModel;
+                            runCtx.outOfBandControl = resolveOutOfBandControl(target);
+                            runCtx.limits = targetPolicies.limits;
+                            runCtx.refinementPolicies = targetPolicies.refinementPolicies;
+                            runCtx.validationPolicies = targetPolicies.validationPolicies;
+                            runCtx.inputProcessors = targetPolicies.inputProcessors;
+                            runCtx.outputProcessors = targetPolicies.outputProcessors;
+                            runCtx.toolExecutor = new CoreToolExecutor({
+                                tools: targetSurface.executorTools,
+                                enforcer: targetPolicies.enforcer,
+                                agentId: target.id,
+                                onInterim: (message) => {
+                                    const id = crypto.randomUUID();
+                                    emit({ channel: 'client', type: 'text-start', payload: { id } });
+                                    emit({
+                                        channel: 'client',
+                                        type: 'text-delta',
+                                        payload: { id, delta: message },
+                                    });
+                                    emit({ channel: 'client', type: 'text-end', payload: { id } });
+                                },
+                                onChunk: (chunk, toolName, toolCallId) => {
+                                    emit({
+                                        channel: 'internal',
+                                        type: 'tool-result',
+                                        payload: { toolName, result: chunk, toolCallId, preliminary: true },
+                                    });
+                                },
+                            });
+                            await runCtx.runStore.putRunState(runCtx.runState);
+                            continue;
                         }
-                        runCtx.runState.activeAgentId = loopResult.to;
-                        activeAgent = target;
-                        const targetSurface = await buildAgentToolSurface(target, opened.session, {
-                            configTools: this.config.tools,
-                            knowledgeProvider,
-                            defaultWorkingMemoryStore: this.config.defaultWorkingMemoryStore,
-                        });
-                        runCtx.autoRetrieve = knowledgeProvider
-                            ? buildAutoRetrieveProvider(knowledgeProvider, target)
-                            : undefined;
-                        runCtx.globalTools = targetSurface.globalTools;
-                        runCtx.skillPrompt = targetSurface.skillPrompt;
-                        runCtx.workingMemoryPrompt = appendGoalsPrompt(targetSurface.workingMemoryPrompt, runCtx.session.workingMemory);
-                        runCtx.workingMemoryTools = targetSurface.workingMemoryTools;
-                        runCtx.fs = targetSurface.resolvedWorkspace?.fs;
-                        runCtx.memoryService = this.config.memoryService
-                            ? buildMemoryService(this.config.memoryService, target)
-                            : undefined;
-                        const targetPolicies = resolveAgentPolicies(target);
-                        const targetModel = target.model ?? this.defaultModel;
-                        if (!targetModel) {
-                            throw new Error('Runtime requires agent.model or config.defaultModel');
+                        if (loopResult.kind === 'ended') {
+                            terminalOutcome = 'resolved';
+                            break;
                         }
-                        runCtx.baseInstructions =
-                            (this.config.silentHandoff ?? true)
-                                ? applyHandoffContinuation(target.instructions)
-                                : target.instructions;
-                        runCtx.model = targetModel;
-                        runCtx.controlModel = target.controlModel ?? targetModel;
-                        runCtx.outOfBandControl = resolveOutOfBandControl(target);
-                        runCtx.limits = targetPolicies.limits;
-                        runCtx.refinementPolicies = targetPolicies.refinementPolicies;
-                        runCtx.validationPolicies = targetPolicies.validationPolicies;
-                        runCtx.inputProcessors = targetPolicies.inputProcessors;
-                        runCtx.outputProcessors = targetPolicies.outputProcessors;
-                        runCtx.toolExecutor = new CoreToolExecutor({
-                            tools: targetSurface.executorTools,
-                            enforcer: targetPolicies.enforcer,
-                            agentId: target.id,
-                            onInterim: (message) => {
-                                const id = crypto.randomUUID();
-                                emit({ channel: 'client', type: 'text-start', payload: { id } });
-                                emit({
-                                    channel: 'client',
-                                    type: 'text-delta',
-                                    payload: { id, delta: message },
-                                });
-                                emit({ channel: 'client', type: 'text-end', payload: { id } });
-                            },
-                            onChunk: (chunk, toolName, toolCallId) => {
-                                emit({
-                                    channel: 'internal',
-                                    type: 'tool-result',
-                                    payload: { toolName, result: chunk, toolCallId, preliminary: true },
-                                });
-                            },
-                        });
-                        await runCtx.runStore.putRunState(runCtx.runState);
-                        continue;
-                    }
-                    if (loopResult.kind === 'ended') {
-                        terminalOutcome = 'resolved';
-                        break;
-                    }
-                    if (loopResult.kind === 'paused') {
-                        if (runCtx.runState.waitingFor?.signalName === '__escalate') {
-                            // Flow escalate() parks on the durable signal — notify the human
-                            // side now; the latch keeps the post-resume terminal handoff from
-                            // notifying a second time.
-                            const meta = runCtx.runState.waitingFor.meta;
-                            await this.dispatchEscalation(runCtx, activeAgent, { reason: String(meta?.reason ?? 'flow_escalation') }, emit, { setLatch: true });
+                        if (loopResult.kind === 'paused') {
+                            if (runCtx.runState.waitingFor?.signalName === '__escalate') {
+                                // Flow escalate() parks on the durable signal — notify the human
+                                // side now; the latch keeps the post-resume terminal handoff from
+                                // notifying a second time.
+                                const meta = runCtx.runState.waitingFor.meta;
+                                await this.dispatchEscalation(runCtx, activeAgent, { reason: String(meta?.reason ?? 'flow_escalation') }, emit, { setLatch: true });
+                            }
+                            break;
                         }
                         break;
                     }
-                    break;
+                    // Post-turn maintenance: text already streamed, so the summarizer call
+                    // is off the user's latency path; the NEXT turn starts compact.
+                    await this.applyCompaction(runCtx, activeAgent, emit, false);
                 }
-                // Post-turn maintenance: text already streamed, so the summarizer call
-                // is off the user's latency path; the NEXT turn starts compact.
-                await this.applyCompaction(runCtx, activeAgent, emit, false);
             }
             catch (error) {
                 await runHookSafely('onError', () => this.hooks?.onError?.(runCtx, error));

package/dist/runtime/channels/executeModelTool.js

@@ -2,7 +2,7 @@ import { classifyControl } from '../../flow/classifyControl.js';
 import { toolDeniedResult, toolErrorResult } from '../../tools/controlResults.js';
 import { idempotencyKey, logicalRunId } from '../durable/idempotency.js';
 import { findStepByKey } from '../durable/replay.js';
-import { isApprovalDenial, isControlFlowSignal } from '../controlFlowSignal.js';
+import { isApprovalDenial, isControlFlowSignal, isRecoverableToolError } from '../controlFlowSignal.js';
 export async function executeModelToolCall(ctx, call, localTools, durableOpts) {
     try {
         const localTool = localTools?.[call.toolName];
@@ -36,6 +36,12 @@ export async function executeModelToolCall(ctx, call, localTools, durableOpts) {
             // the turn dies and the user never hears why. No client error part: nothing broke.
             return { result: toolDeniedResult(error.toolName, error.by), failed: true };
         }
+        if (isRecoverableToolError(error)) {
+            // The model can correct this (bad referent, missing precondition): return the message
+            // as a tool result so it can retry. Not a malfunction, so no client error part —
+            // same posture as an approval denial.
+            return { result: toolErrorResult(error), failed: true };
+        }
         const message = error instanceof Error ? error.message : String(error);
         ctx.emit({ channel: 'client', type: 'error', payload: { error: message } });
         return { result: toolErrorResult(error), failed: true };

package/dist/runtime/channels/streaming/speakGated.js

@@ -1,4 +1,5 @@
 import { randomUUID } from 'node:crypto';
+import { isControlFlowSignal } from '../../controlFlowSignal.js';
 import { SentenceAggregator } from './SentenceAggregator.js';
 function emitMessage(ctx, id, text) {
     ctx.emit({ channel: 'client', type: 'text-start', payload: { id } });
@@ -31,6 +32,12 @@ export async function speakGated(args) {
             }
         }
         catch (err) {
+            // A suspend unwinds through here on its way to the host loop. It is not a failure and
+            // must not reach the user as one — the same rule executeModelToolCall and runFlow
+            // already apply. This third path was missed, so an approval pause still surfaced as
+            // "error: Run suspended waiting for __approval" mid-conversation.
+            if (isControlFlowSignal(err))
+                throw err;
             const message = err instanceof Error ? err.message : String(err);
             ctx.emit({ channel: 'client', type: 'error', payload: { error: message } });
             throw err instanceof Error ? err : new Error(message);
@@ -101,6 +108,8 @@ export async function speakGated(args) {
         return { text: emitted };
     }
     catch (err) {
+        if (isControlFlowSignal(err))
+            throw err;
         const message = err instanceof Error ? err.message : String(err);
         ctx.emit({ channel: 'client', type: 'error', payload: { error: message } });
         if (started) {

package/dist/runtime/closeRun.js

@@ -29,6 +29,12 @@ export async function closeRun(options) {
         // otherwise lacks assistant turns and keeps pre-guardrail (unredacted)
         // user input written at openRun.
         latest.messages = [...runState.messages];
+        // Persist handoff history accumulated on the run's working session this turn
+        // (terminal + non-terminal handoffs alike). Without this the in-memory pushes
+        // were silently dropped: stores that clone on get/save (e.g. MemoryStore) hand
+        // back a fresh snapshot here, and the previous mutator never copied handoffHistory
+        // across — so isHandoffOscillating's cross-turn safeguard never saw prior turns.
+        latest.handoffHistory = session.handoffHistory;
         syncPendingUserInput(ctx.session, latest);
     });
 }

package/dist/runtime/controlFlowSignal.d.ts

@@ -1,4 +1,4 @@
-import { ToolApprovalDeniedError } from '../tools/effect/errors.js';
+import { RecoverableToolError, ToolApprovalDeniedError } from '../tools/effect/errors.js';
 /**
  * The run is not finished: stop the turn, keep the journal, resume when a signal arrives.
  * It unwinds the stack like an error but is not a failure, so it must never be reported to
@@ -22,3 +22,9 @@ export declare function isControlFlowSignal(error: unknown): boolean;
  *   call the tool and can catch it or branch on `ctx.approve()` instead.
  */
 export declare function isApprovalDenial(error: unknown): error is ToolApprovalDeniedError;
+/**
+ * A tool failed in a way the model can correct (bad referent, missing precondition). Not a
+ * control-flow signal and not a fatal fault: on the flow path it routes back to re-collecting
+ * the offending input rather than degrading the turn.
+ */
+export declare function isRecoverableToolError(error: unknown): error is RecoverableToolError;

package/dist/runtime/controlFlowSignal.js

@@ -1,5 +1,5 @@
 import { SuspendError } from './durable/RunStore.js';
-import { ToolApprovalDeniedError } from '../tools/effect/errors.js';
+import { RecoverableToolError, ToolApprovalDeniedError } from '../tools/effect/errors.js';
 /**
  * The run is not finished: stop the turn, keep the journal, resume when a signal arrives.
  * It unwinds the stack like an error but is not a failure, so it must never be reported to
@@ -27,3 +27,11 @@ export function isControlFlowSignal(error) {
 export function isApprovalDenial(error) {
     return error instanceof ToolApprovalDeniedError;
 }
+/**
+ * A tool failed in a way the model can correct (bad referent, missing precondition). Not a
+ * control-flow signal and not a fatal fault: on the flow path it routes back to re-collecting
+ * the offending input rather than degrading the turn.
+ */
+export function isRecoverableToolError(error) {
+    return error instanceof RecoverableToolError;
+}

package/dist/runtime/hostLoop.js

@@ -80,10 +80,19 @@ async function runActiveFlow(flow, run, driver, ctx, agent) {
         await ctx.runStore.putRunState(run);
         return { kind: 'turnComplete' };
     }
-    const completed = run.state.__completedFlows;
-    const completedFlows = Array.isArray(completed) ? completed : [];
-    if (!completedFlows.includes(flow.name)) {
-        run.state.__completedFlows = [...completedFlows, flow.name];
+    // A flow that ended because a node threw is NOT completed. Marking it so made the
+    // failure permanent for the turn: `select` and the host-control tools both exclude a
+    // completed flow from re-entry, so a failed intake could not be retried even though the
+    // error was recoverable (a mistyped unit id, a transient tool fault). Observed live —
+    // a session held __completedFlows: ["raise_work_order"] with an errored journal step
+    // and no work order to show for it.
+    const degraded = result.kind === 'ended' && result.reason === 'error_degraded';
+    if (!degraded) {
+        const completed = run.state.__completedFlows;
+        const completedFlows = Array.isArray(completed) ? completed : [];
+        if (!completedFlows.includes(flow.name)) {
+            run.state.__completedFlows = [...completedFlows, flow.name];
+        }
     }
     run.activeFlow = undefined;
     run.activeNode = undefined;

package/dist/tools/effect/errors.d.ts

@@ -4,6 +4,21 @@ export declare class ToolTimeoutError extends Error {
     readonly timeoutMs: number;
     constructor(toolName: string, timeoutMs: number);
 }
+/**
+ * Thrown by a tool's `execute` (or a guard wrapping it) when the call failed for a
+ * reason the model can correct: a referent that does not exist ("Unknown unit '12B'"),
+ * a value out of range, a missing precondition the user can supply. Distinct from a
+ * fatal fault (network down, schema broken) in that the model should see the message
+ * and retry — not be told "something went wrong on my side".
+ *
+ * On the model path it is returned to the model as a tool result (the model self-corrects).
+ * On the flow path it is the signal to re-collect the offending input instead of
+ * degrading the flow — see `runFlow`. Detected by type (`isRecoverableToolError`), never
+ * by string-matching the message.
+ */
+export declare class RecoverableToolError extends Error {
+    constructor(message: string);
+}
 /** Thrown when a human denies a tool call that requires approval. */
 export declare class ToolApprovalDeniedError extends Error {
     readonly toolName: string;

package/dist/tools/effect/errors.js

@@ -9,6 +9,24 @@ export class ToolTimeoutError extends Error {
         this.timeoutMs = timeoutMs;
     }
 }
+/**
+ * Thrown by a tool's `execute` (or a guard wrapping it) when the call failed for a
+ * reason the model can correct: a referent that does not exist ("Unknown unit '12B'"),
+ * a value out of range, a missing precondition the user can supply. Distinct from a
+ * fatal fault (network down, schema broken) in that the model should see the message
+ * and retry — not be told "something went wrong on my side".
+ *
+ * On the model path it is returned to the model as a tool result (the model self-corrects).
+ * On the flow path it is the signal to re-collect the offending input instead of
+ * degrading the flow — see `runFlow`. Detected by type (`isRecoverableToolError`), never
+ * by string-matching the message.
+ */
+export class RecoverableToolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RecoverableToolError';
+    }
+}
 /** Thrown when a human denies a tool call that requires approval. */
 export class ToolApprovalDeniedError extends Error {
     toolName;

package/dist/tools/fs/createFsTool.js

@@ -158,7 +158,8 @@ export function createFsTool(opts) {
             'grep for exact terms, names, codes, or keywords (returns matching lines only), ' +
             'cat/read for full file contents. Prefer grep over semantic knowledge search when ' +
             'the user mentions an exact term or identifier — it is faster, cheaper, and exact. ' +
-            'Ops: ls, cat, grep, find, read, write, edit.',
+            'Ops: ls, cat, grep, find, read, write, edit. grep is CASE-SENSITIVE by default — pass ' +
+            'flags:"i" when searching prose, or a heading like "Entry notice" will not match "entry notice".',
         timeoutMs,
         input: workspaceInput,
         execute: async (args) => {

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/core"
   },
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "A framework for structured conversational AI agents",
   "publishConfig": {
     "access": "public"
@@ -103,7 +103,7 @@
     "typescript": "^5.3.0",
     "vitest": "^3.2.4",
     "zod": "^4.0.0",
-    "@kuralle-agents/fs": "0.14.0"
+    "@kuralle-agents/fs": "0.14.2"
   },
   "dependencies": {
     "chrono-node": "^2.6.0"