@falai/agent 2.6.1 → 2.7.0

package/src/core/ResponseModal.ts

@@ -7,6 +7,7 @@ import type {
     AgentOptions,
     AgentResponse,
     AgentResponseStreamChunk,
+    EndedFlow,
     History,
     SessionState,
     StepRef,
@@ -37,11 +38,14 @@ import { AutoChainExecutor, type AutoChainResult } from "./AutoChainExecutor";
 import { StepLifecycle } from "./StepLifecycle";
 import { SessionFinalizer } from "./SessionFinalizer";
 import { ToolLoopExecutor } from "./ToolLoopExecutor";
+import { flow } from "./flow-namespace";
 import { SignalCoordinator } from "./SignalCoordinator";
 import { ResponseGenerationError } from "./ResponseGenerationError";
-import { cloneDeep, mergeCollected, logger, historyToEvents, completeCurrentFlow, render } from "../utils";
+import { ProviderError, SessionConflictError } from "../types/errors";
+import { cloneDeep, mergeCollected, logger, historyToEvents, completeCurrentFlow, render, userMessage, assistantMessage } from "../utils";
 import { createTemplateContext } from "../utils/template";
 import { StreamingMessageDecoder } from "../utils/streamingMessage";
+import { tryParseJSONResponse } from "../utils/json";
 import type { ToolManager } from "./ToolManager";
 
 /**
@@ -95,6 +99,19 @@ export interface ResponseModalOptions {
  */
 export interface RespondParams<TContext = unknown, TData = unknown> extends Record<string, unknown> {
     history: History;
+    /**
+     * The user's message for this turn. When set, the engine appends it to the
+     * generation history AND to the returned session's history, then appends
+     * the assistant reply on top — callers who hold sessions no longer need to
+     * maintain history arrays by hand.
+     */
+    message?: string;
+    /**
+     * Restrict this turn's ROUTING candidates to these flow ids/titles.
+     * Directive targets (goTo etc.) still resolve against the full registry.
+     * Use for entry-pin funnels instead of cloning/filtering agents.
+     */
+    allowedFlows?: string[];
     step?: StepRef;
     session?: SessionState<TData>;
     contextOverride?: Partial<TContext>;
@@ -140,6 +157,10 @@ interface ResponseContext<TContext = unknown, TData = unknown> {
     signalHalted?: boolean;
     /** Reply from a halt directive. */
     signalHaltReply?: string;
+    /** Flows exited via pendingDirective redirects/resets during routing. */
+    endedFlows?: EndedFlow[];
+    /** The user turn supplied via params.message (drives history ownership). */
+    turnMessage?: string;
 }
 
 /**
@@ -261,6 +282,13 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             if (preTurnSession) {
                 this.agent.session.syncSession(preTurnSession);
             }
+            // Typed library errors carry their own semantics (ProviderError.code,
+            // SessionConflictError) — rethrow bare so consumers can branch on
+            // them instead of string-matching. Everything else wraps with the
+            // original attached as `cause`.
+            if (error instanceof ProviderError || error instanceof SessionConflictError) {
+                throw error;
+            }
             throw new ResponseGenerationError(
                 `[ResponseGenerationError] Response generation failed: ${error instanceof Error ? error.message : String(error)}. ` +
                 `Check provider configuration and network connectivity.`,
@@ -430,6 +458,58 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         return this.agent.tool;
     }
 
+    /**
+     * Repair-parse a JSON-shaped protocol fragment (truncated output,
+     * fence-wrapped JSON) into a structured payload. Raw protocol fragments
+     * must never surface as the user-visible reply: if the repair parse fails,
+     * fail the turn LOUDLY so the caller's rollback/retry path engages instead
+     * of leaking `{"message": "…` to an end user. Plain prose (not JSON-shaped
+     * at all) never reaches this helper — the call sites gate on the fragment
+     * shape and pass it through untouched.
+     */
+    private salvageStructuredOutput(
+        raw: string,
+        surface: "turn" | "stream"
+    ): AgentStructuredResponse {
+        const salvaged = tryParseJSONResponse(raw) as Partial<AgentStructuredResponse> | undefined;
+        if (salvaged && typeof salvaged.message === "string") {
+            logger.warn(`[ResponseModal] Salvaged malformed structured output from ${surface} via JSON repair parse.`);
+            return { ...salvaged, message: salvaged.message };
+        }
+        throw ResponseGenerationError.fromError(
+            new Error(
+                "Model returned a schema-mandated response that could not be parsed as JSON. " +
+                `The ${surface} was failed instead of delivering raw protocol output to the user.`
+            ),
+            'structured_output_malformed',
+            { responseSchemaName: 'response_output' }
+        );
+    }
+
+    /**
+     * Tool-emitted directives (ctx.dispatch / `{directive}` returns): state
+     * writes apply now; control flow queues for the next turn's
+     * pendingDirective applier (same deferred semantics as dispatch()).
+     */
+    private async applyToolEmittedDirectives(
+        session: SessionState<TData>,
+        d: Directive<TContext, TData>
+    ): Promise<SessionState<TData>> {
+        if (d.dataUpdate) {
+            session = mergeCollected(session, d.dataUpdate);
+        }
+        if (d.contextUpdate) {
+            await this.agent.updateContext(d.contextUpdate);
+        }
+        const control = { ...d };
+        delete control.dataUpdate;
+        delete control.contextUpdate;
+        if (Object.keys(control).length > 0) {
+            flow.queuePending(session, control);
+        }
+        return session;
+    }
+
     /**
      * Collect scoped instructions from agent, flow, and step into a ScopedInstructions value.
      * @private
@@ -455,21 +535,25 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
      */
     private async prepareUnifiedResponseContext(params: RespondParams<TContext, TData>): Promise<ResponseContext<TContext, TData>> {
         try {
-            const { history: simpleHistory, contextOverride, signal } = params;
+            const { history: simpleHistory, contextOverride, signal, message: turnMessage, allowedFlows } = params;
 
             // Validate input parameters
             if (!simpleHistory) {
                 throw new ResponseGenerationError(
                     '[ResponseGenerationError] Missing history: history is required for response generation. ' +
-                    'Pass a valid history array to the respond/stream method.',
+                    'Pass a valid history array (or pass `message` alongside an existing history base).',
                     { params, phase: 'validation' }
                 );
             }
 
+            // `message` is the user turn: appended to what the model sees this
+            // turn AND recorded on the returned session's history.
+            const history = turnMessage
+                ? [...simpleHistory, userMessage(turnMessage)]
+                : simpleHistory;
+
             // Convert HistoryItem[] to Event[] for internal processing
-            const historyEvents = historyToEvents(simpleHistory);
-            // Keep original HistoryItem[] format for external APIs
-            const history = simpleHistory;
+            const historyEvents = historyToEvents(history);
 
             // Use ResponsePipeline for context and session preparation; context
             // and session are passed explicitly — the pipeline holds no state
@@ -515,9 +599,23 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 }
             }
 
+            // Record the user turn on the session's own history so the returned
+            // session carries the full exchange (respond owns session.history
+            // when `message` is used).
+            if (turnMessage) {
+                session.history = [...(session.history ?? []), userMessage(turnMessage)];
+            }
+
             // PHASE 1: PREPARE - Execute prepare function if current step has one
             try {
-                await this.stepLifecycle.runPrepare(session, effectiveContext);
+                const prepareDirective = await this.stepLifecycle.runPrepare(session, effectiveContext);
+                // Queue the control-flow directive for THIS turn: routing
+                // (handleRoutingAndStepSelection) consumes session.pendingDirective
+                // before deciding flow/step, so a prepare-phase goTo/goToStep/
+                // reset steers the current turn.
+                if (prepareDirective) {
+                    flow.queuePending(session, prepareDirective);
+                }
             } catch (error) {
                 throw ResponseGenerationError.fromError(error, 'step_preparation', params, { session, effectiveContext });
             }
@@ -534,6 +632,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 signalPreDirective?: Directive<TContext, TData>;
                 signalHalted?: boolean;
                 signalHaltReply?: string;
+                endedFlows?: EndedFlow[];
             };
             try {
                 routingResult = await this.responsePipeline.routeAndSelectStep({
@@ -541,6 +640,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     history: historyEvents,
                     context: effectiveContext,
                     signal,
+                    allowedFlows,
                 });
             } catch (error) {
                 throw ResponseGenerationError.fromError(error, 'routing_and_step_selection', params, { session, effectiveContext });
@@ -550,6 +650,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 effectiveContext,
                 session: routingResult.session,
                 history,
+                turnMessage,
                 selectedFlow: routingResult.selectedFlow,
                 selectedStep: routingResult.selectedStep,
                 responseDirectives: routingResult.responseDirectives,
@@ -559,6 +660,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 signalPreDirective: routingResult.signalPreDirective,
                 signalHalted: routingResult.signalHalted,
                 signalHaltReply: routingResult.signalHaltReply,
+                endedFlows: routingResult.endedFlows,
             };
         } catch (error) {
             // Re-throw ResponseGenerationError as-is, wrap others
@@ -748,6 +850,8 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         let isFlowComplete = false;
         let appliedInstructions: AppliedInstruction[] | undefined;
         let runPostPhase = true;
+        let tokensUsed: number | undefined;
+        const endedFlows: EndedFlow[] = [...(responseContext.endedFlows ?? [])];
 
         switch (plan.outcome.kind) {
             case 'halt': {
@@ -765,6 +869,11 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 });
                 isFlowComplete = true;
                 stoppedReason = plan.outcome.stoppedReason;
+                endedFlows.push({
+                    flowId: plan.outcome.selectedFlow.id,
+                    title: plan.outcome.selectedFlow.title,
+                    reason: plan.outcome.stoppedReason,
+                });
                 break;
             }
             case 'flowStep': {
@@ -786,6 +895,7 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 toolCalls = result.toolCalls;
                 session = result.session;
                 appliedInstructions = result.appliedInstructions;
+                tokensUsed = result.tokensUsed;
                 if (plan.outcome.step) {
                     executedSteps = [{ id: plan.outcome.step.id, flowId: plan.outcome.selectedFlow.id }];
                 }
@@ -811,6 +921,14 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             session, context: effectiveContext, historyEvents, message, signalFirings, runPostPhase,
         });
 
+        // History ownership: with params.message the returned session carries
+        // the full exchange — the user turn was recorded pre-routing, the
+        // assistant tail lands here (post-phase, so overridden replies are the
+        // ones recorded). Empty tails are skipped.
+        if (responseContext.turnMessage && tail.message) {
+            tail.session.history = [...(tail.session.history ?? []), assistantMessage(tail.message)];
+        }
+
         return {
             message: tail.message,
             session: tail.session,
@@ -820,6 +938,8 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
             stoppedReason,
             appliedInstructions,
             triggeredSignals: tail.triggeredSignals,
+            ...(tokensUsed !== undefined ? { metadata: { tokensUsed } } : {}),
+            ...(endedFlows.length > 0 ? { endedFlows } : {}),
         };
     }
 
@@ -852,6 +972,8 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
         session: SessionState<TData>;
         appliedInstructions?: AppliedInstruction[];
         stoppedReason?: StoppedReason;
+        /** Provider-reported usage for the primary generation call. */
+        tokensUsed?: number;
     }> {
         const { selectedFlow, selectedStep, responseDirectives, history, context, historyEvents, signal, transientAppendage, mergedPreDirective } = params;
         let session = params.session;
@@ -940,17 +1062,25 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 parameters: responseSchema ? { jsonSchema: responseSchema, schemaName: "response_output" } : undefined,
             });
 
-            let message = result.structured?.message || result.message;
-            let toolCalls = result.structured?.toolCalls;
+            let structuredData = result.structured;
+            let message = structuredData?.message || result.message;
+            const tokensUsed = result.metadata?.tokensUsed;
+
+            // A schema was requested but the provider failed to parse the model's
+            // JSON (truncated output, fence-wrapped fragments). Raw protocol
+            // fragments must never surface as the user-visible reply: attempt one
+            // repair-parse, and if that fails fail the turn LOUDLY so the caller's
+            // rollback/retry path engages instead of leaking `{"message": "…` to
+            // an end user. Plain prose (not JSON-shaped at all) still passes
+            // through — it is not a protocol fragment.
+            if (!structuredData && responseSchema && message && /^\s*(```|{)/.test(message)) {
+                const salvaged = this.salvageStructuredOutput(message, "turn");
+                structuredData = salvaged;
+                message = salvaged.message;
+            }
 
-            // Debug: Log initial AI response
-            logger.debug(`[ResponseModal] Initial AI response:`, {
-                hasMessage: !!message,
-                messageLength: message?.length || 0,
-                hasToolCalls: !!toolCalls,
-                toolCallsCount: toolCalls?.length || 0,
-                toolNames: toolCalls?.map(tc => tc.toolName) || [],
-            });
+            const effectiveResult = structuredData ? { ...result, structured: structuredData } : result;
+            let toolCalls = structuredData?.toolCalls;
 
             // Execute tools with unified loop handling
             const toolResult = await this.toolLoopExecutor.runLoop({
@@ -971,14 +1101,21 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 message = toolResult.finalMessage;
             }
 
+            // Tool-emitted directives (ctx.dispatch / `{directive}` returns):
+            // state writes apply now; control flow queues for the next turn's
+            // pendingDirective applier (same deferred semantics as dispatch()).
+            if (toolResult.directives) {
+                session = await this.applyToolEmittedDirectives(session, toolResult.directives);
+            }
+
             // Collect data from response
             // Use follow-up structured data from tool loop when available, fall back to original result
             const dataSource = toolResult.structured
                 ? { structured: toolResult.structured }
-                : result;
+                : effectiveResult;
             session = await this.collectDataFromResponse({ result: dataSource, selectedFlow, nextStep, session });
 
-            return { message, toolCalls, session, appliedInstructions };
+            return { message, toolCalls, session, appliedInstructions, tokensUsed };
         } finally {
             // Drain the transient appendage at end of turn.
             // This ensures Directive.appendPrompt does not leak to subsequent
@@ -1070,6 +1207,14 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                 const accumulated = tail.message;
                 const delta = tail.replyOverridden ? accumulated : chunk.delta;
 
+                // History ownership (parity with the sync tail): with
+                // params.message the returned session carries the full
+                // exchange — the user turn was recorded pre-routing, the
+                // assistant tail lands here, BEFORE finalize persists it.
+                if (responseContext.turnMessage && tail.message) {
+                    tail.session.history = [...(tail.session.history ?? []), assistantMessage(tail.message)];
+                }
+
                 // Single streaming exit: finalize the post-phase session so
                 // post-signal mutations (e.g. pendingDirective) are persisted.
                 await this.sessionFinalizer.finalize(tail.session, effectiveContext);
@@ -1291,6 +1436,15 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     session = batchResult.session;
                     toolCalls = batchResult.toolCalls;
 
+                    // Tool-emitted directives (ctx.dispatch / `{directive}`):
+                    // state writes apply now; control flow queues for the next
+                    // turn's pendingDirective applier (same deferred semantics
+                    // as dispatch()). A verbatim tool reply already replaced the
+                    // closing message inside runStreamingBatch.
+                    if (batchResult.directives) {
+                        session = await this.applyToolEmittedDirectives(session, batchResult.directives);
+                    }
+
                     // Prefer the post-tool follow-up structured for collection and
                     // emission whenever present — independent of whether a closing
                     // message was forced — matching the non-streaming path's
@@ -1309,6 +1463,18 @@ export class ResponseModal<TContext = unknown, TData = unknown> {
                     }
                 }
 
+                // Streaming twin of the non-streaming salvage guard: a schema was
+                // requested but no structured payload arrived, and the accumulated
+                // text is JSON-shaped (a protocol fragment) — repair-parse it or
+                // fail the turn rather than leaking raw output to the user.
+                if (chunk.done && !finalStructured && responseSchema && finalAccumulated && /^\s*(```|{)/.test(finalAccumulated)) {
+                    const salvaged = this.salvageStructuredOutput(finalAccumulated, "stream");
+                    finalStructured = salvaged;
+                    finalDelta = salvaged.message.startsWith(finalAccumulated)
+                        ? salvaged.message.slice(finalAccumulated.length)
+                        : salvaged.message;
+                }
+
                 // Collect data on the final chunk for any flow step — flow
                 // required/optional fields are valid targets even without a step
                 // `collect` — preferring the post-tool follow-up structured so a