@kuralle-agents/core 0.14.0 → 0.15.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 } from './extraction.js';
 import { hasPendingUserInput, setPendingUserInput } from '../runtime/channels/inputBuffer.js';
 import { userInputToText } from '../runtime/userInput.js';
 import { collectUntilComplete } from './collectUntilComplete.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 } });

package/dist/runtime/Runtime.d.ts

@@ -21,6 +21,12 @@ 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.";
 export interface TracingConfig {
     enabled?: boolean;
     store?: TraceStore;

package/dist/runtime/Runtime.js

@@ -35,6 +35,12 @@ 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.";
 export class Runtime {
     config;
     agentsById;
@@ -86,7 +92,14 @@ 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;
             const emit = (part) => {
+                if (part.type === 'text-delta' && part.payload.delta)
+                    sawUserText = true;
                 recorder?.record(part);
                 if (part.type === 'done')
                     this.flushTraceSinks();
@@ -212,12 +225,38 @@ export class Runtime {
                     }
                     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.
                             emit({
                                 channel: 'internal',
                                 type: 'handoff',
                                 payload: { targetAgent: loopResult.to, reason: loopResult.reason },
                             });
                             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;

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/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/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.15.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.1"
   },
   "dependencies": {
     "chrono-node": "^2.6.0"