@falai/agent 1.2.7 → 2.0.0

package/src/core/createAgent.ts

@@ -0,0 +1,40 @@
+/**
+ * Level-1 factory for constructing an Agent from a single options object.
+ *
+ * `createAgent` is syntactic sugar over `new Agent(options)` and is the
+ * recommended entry point in docs and examples. Generic inference flows
+ * from `schema` through `flows[].steps[].collect` identically to `new Agent`.
+ *
+ * @example
+ * ```typescript
+ * const agent = createAgent({
+ *   name: 'BookingBot',
+ *   provider: new GeminiProvider({ apiKey }),
+ *   schema: { type: 'object', properties: { name: { type: 'string' }, email: { type: 'string' } } },
+ *   flows: [{ title: 'Onboarding', steps: [{ collect: ['name', 'email'] }] }],
+ * });
+ * ```
+ *
+ * **Validates: Requirements 14.1–14.7**
+ */
+
+import { Agent } from "./Agent";
+import type { AgentOptions } from "../types";
+
+/**
+ * Create an Agent from a single options object.
+ *
+ * This is the recommended entry point for constructing agents in v2.
+ * Accepts the same options as `new Agent(options)` — `schema`, `provider`,
+ * `instructions`, `flows`, and everything else `AgentOptions` carries.
+ *
+ * Generic inference flows from `schema` through `flows[].steps[].collect`.
+ * Invalid `collect` references throw `FlowConfigurationError` at construction time.
+ *
+ * Post-construction flow registration is still available via `agent.createFlow(...)`.
+ */
+export function createAgent<TContext = unknown, TData = unknown>(
+    options: AgentOptions<TContext, TData>
+): Agent<TContext, TData> {
+    return new Agent<TContext, TData>(options);
+}

package/src/core/flow-namespace.ts

@@ -0,0 +1,219 @@
+/**
+ * `flow` namespace — type guards, merge, and validation helpers for Directives.
+ *
+ * No builder constructors live here (no `flow.goTo(...)`, `flow.complete(...)` etc.).
+ * Directives are plain object literals; this namespace provides runtime utilities only.
+ */
+
+import type { Directive } from "../types/flow";
+import { FlowConfigurationError } from "./Step";
+
+// ─── Position field metadata ─────────────────────────────────────────────────
+
+/** Position fields in precedence order (highest first). */
+const POSITION_FIELDS = ["abort", "complete", "goTo", "goToStep", "reset"] as const;
+type PositionField = (typeof POSITION_FIELDS)[number];
+
+/** Precedence map: lower number = higher priority. */
+const POSITION_PRECEDENCE: Record<PositionField, number> = {
+    abort: 0,
+    complete: 1,
+    goTo: 2,
+    goToStep: 2,
+    reset: 3,
+};
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function getSetPositionFields(d: Directive): PositionField[] {
+    return POSITION_FIELDS.filter((f) => d[f] !== undefined && d[f] !== null);
+}
+
+/**
+ * Determines whether `candidate` beats `current` by precedence.
+ * Lower precedence number wins. On tie, candidate wins (last-emission-wins).
+ */
+function beatsCurrent(
+    candidate: PositionField,
+    current: PositionField | null
+): boolean {
+    if (current === null) return true;
+    return POSITION_PRECEDENCE[candidate] <= POSITION_PRECEDENCE[current];
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/**
+ * Type guard: is `x` a Directive (or any subtype like PreDirective)?
+ *
+ * A value is considered a Directive if it is a non-null object. The Directive
+ * interface has all-optional fields, so any plain object qualifies structurally.
+ * This guard filters out primitives, null, undefined, arrays, and functions.
+ */
+function isDirective(x: unknown): x is Directive {
+    return (
+        x !== null &&
+        x !== undefined &&
+        typeof x === "object" &&
+        !Array.isArray(x)
+    );
+}
+
+/**
+ * Merge two directives by Algorithm 4's rules:
+ * - Position fields: precedence (abort > complete > goTo/goToStep > reset);
+ *   ties broken by emission order (b wins over a — last wins).
+ * - reply: last-wins (b.reply overrides a.reply if set).
+ * - dataUpdate / contextUpdate: shallow-merge (b overrides a on key collision).
+ * - appendPrompt / injectTools (PreDirective fields): concatenate then dedupe.
+ * - halt: logical-OR.
+ */
+function merge<T extends Directive>(a: T, b: T): T {
+    const result = {} as Record<string, unknown>;
+
+    // ── Position field: winner-takes-all by precedence, b wins ties ──
+    const aPos = getSetPositionFields(a as Directive);
+    const bPos = getSetPositionFields(b as Directive);
+
+    // Pick the highest-priority position field across both directives.
+    // b's fields are evaluated after a's, so b wins on same precedence (last-wins).
+    let winnerField: PositionField | null = null;
+    let winnerSource: Directive | null = null;
+
+    for (const field of aPos) {
+        if (beatsCurrent(field, winnerField)) {
+            winnerField = field;
+            winnerSource = a as Directive;
+        }
+    }
+    for (const field of bPos) {
+        if (beatsCurrent(field, winnerField)) {
+            winnerField = field;
+            winnerSource = b as Directive;
+        }
+    }
+
+    if (winnerField !== null && winnerSource !== null) {
+        result[winnerField] = (winnerSource as Record<string, unknown>)[winnerField];
+    }
+
+    // ── reply: last-wins ──
+    if ((b as Directive).reply !== undefined) {
+        result.reply = (b as Directive).reply;
+    } else if ((a as Directive).reply !== undefined) {
+        result.reply = (a as Directive).reply;
+    }
+
+    // ── dataUpdate: shallow merge ──
+    const aData = (a as Record<string, unknown>).dataUpdate as
+        | Record<string, unknown>
+        | undefined;
+    const bData = (b as Record<string, unknown>).dataUpdate as
+        | Record<string, unknown>
+        | undefined;
+    if (aData || bData) {
+        result.dataUpdate = { ...aData, ...bData };
+    }
+
+    // ── contextUpdate: shallow merge ──
+    const aCtx = (a as Record<string, unknown>).contextUpdate as
+        | Record<string, unknown>
+        | undefined;
+    const bCtx = (b as Record<string, unknown>).contextUpdate as
+        | Record<string, unknown>
+        | undefined;
+    if (aCtx || bCtx) {
+        result.contextUpdate = { ...aCtx, ...bCtx };
+    }
+
+    // ── appendPrompt (PreDirective): concatenate ──
+    const aPrompt = (a as Record<string, unknown>).appendPrompt as
+        | string[]
+        | undefined;
+    const bPrompt = (b as Record<string, unknown>).appendPrompt as
+        | string[]
+        | undefined;
+    if (aPrompt || bPrompt) {
+        result.appendPrompt = [...(aPrompt ?? []), ...(bPrompt ?? [])];
+    }
+
+    // ── injectTools (PreDirective): concatenate then dedupe by id (last wins) ──
+    const aTools = (a as Record<string, unknown>).injectTools as
+        | Array<{ id: string;[k: string]: unknown }>
+        | undefined;
+    const bTools = (b as Record<string, unknown>).injectTools as
+        | Array<{ id: string;[k: string]: unknown }>
+        | undefined;
+    if (aTools || bTools) {
+        const combined = [...(aTools ?? []), ...(bTools ?? [])];
+        // Dedupe by id — last definition wins
+        const seen = new Map<string, (typeof combined)[number]>();
+        for (const tool of combined) {
+            seen.set(tool.id, tool);
+        }
+        result.injectTools = Array.from(seen.values());
+    }
+
+    // ── halt (PreDirective): logical OR ──
+    const aHalt = (a as Record<string, unknown>).halt as boolean | undefined;
+    const bHalt = (b as Record<string, unknown>).halt as boolean | undefined;
+    if (aHalt || bHalt) {
+        result.halt = true;
+    }
+
+    return result as T;
+}
+
+/**
+ * Runtime validator. Throws FlowConfigurationError for invalid combinations:
+ * - Multiple position fields set.
+ * - `goTo` set as empty object `{}` (no flow target).
+ * - `reply` co-existing with `abort` (abort ends the conversation; a reply is nonsensical).
+ */
+function validate(d: Directive): void {
+    // ── Multiple position fields ──
+    const setFields = getSetPositionFields(d);
+    if (setFields.length > 1) {
+        throw new FlowConfigurationError(
+            `[FlowConfigurationError] Invalid directive: multiple position fields set (${setFields.join(", ")}). ` +
+            `A directive may have at most one position field. Remove the extras.`
+        );
+    }
+
+    // ── Empty goTo object ──
+    if (d.goTo !== undefined && d.goTo !== null) {
+        if (typeof d.goTo === "object") {
+            const goToObj = d.goTo as { flow?: string; step?: string };
+            if (!goToObj.flow && !goToObj.step) {
+                throw new FlowConfigurationError(
+                    `[FlowConfigurationError] Invalid directive: goTo is set as an empty object. ` +
+                    `goTo requires a flow id or title. Provide { flow: "<id>" } or use the string shorthand.`
+                );
+            }
+        }
+    }
+
+    // ── reply co-existing with abort ──
+    if (d.reply !== undefined && d.abort !== undefined) {
+        throw new FlowConfigurationError(
+            `[FlowConfigurationError] Invalid directive: reply cannot co-exist with abort. ` +
+            `An aborted conversation cannot deliver a reply. Remove one of the fields.`
+        );
+    }
+}
+
+/**
+ * The `flow` namespace object. Exported as a single const for ergonomic usage:
+ *
+ * ```ts
+ * import { flow } from '@falai/agent';
+ * if (flow.isDirective(x)) { ... }
+ * const merged = flow.merge(a, b);
+ * flow.validate(d);
+ * ```
+ */
+export const flow = {
+    isDirective,
+    merge,
+    validate,
+} as const;

package/src/index.ts

@@ -1,30 +1,26 @@
 /**
  * @falai/agent - Standalone AI Agent framework
  *
- * A strongly-typed, modular agent framework with route DSL and AI provider strategy
+ * A strongly-typed, modular agent framework with flow DSL and AI provider strategy
  */
 
 // Core
 export { Agent } from "./core/Agent";
-export { Route } from "./core/Route";
-export { Step } from "./core/Step";
-export { ResponseModal } from "./core/ResponseModal";
-export type {
-  ResponseModalOptions,
-  RespondParams,
-  StreamOptions,
-  GenerateOptions
-} from "./core/ResponseModal";
+export { createAgent } from "./core/createAgent";
+export { Flow } from "./core/Flow";
+export { Step, FlowConfigurationError } from "./core/Step";
+export { flow } from "./core/flow-namespace";
+export { DirectiveChainTracker } from "./core/DirectiveChainTracker";
+export type { DirectiveChainEntry } from "./core/DirectiveChainTracker";
+
 export { adaptEvent, convertHistoryToEvents } from "./core/Events";
 export { PersistenceManager } from "./core/PersistenceManager";
 export { SessionManager } from "./core/SessionManager";
 export { ToolManager, ToolCreationError, ToolExecutionError } from "./core/ToolManager";
-export { BatchExecutor, needsInput, type NeedsInputStep, type DetermineBatchParams } from "./core/BatchExecutor";
-export { BatchPromptBuilder, type BuildBatchPromptParams, type BatchPromptResult } from "./core/BatchPromptBuilder";
-export { CompactionEngine } from "./core/CompactionEngine";
+export { NotImplementedError } from "./types/errors";
+
 export { StreamingToolExecutor } from "./core/StreamingToolExecutor";
-export { PromptSectionCache } from "./core/PromptSectionCache";
-export type { PromptSectionType, PromptCacheConfig, SectionCompute } from "./core/PromptSectionCache";
+
 
 // Providers
 export { GeminiProvider } from "./providers/GeminiProvider";
@@ -71,11 +67,8 @@ export type {
   OpenSearchAdapterOptions,
 } from "./adapters/OpenSearchAdapter";
 
-// Constants
-export { END_ROUTE, END_ROUTE_ID } from "./constants";
-
 // Utils
-export { generateRouteId, generateStepId, generateToolId } from "./utils/id";
+export { generateFlowId, generateStepId, generateToolId } from "./utils/id";
 export { formatKnowledgeBase } from "./utils/template";
 export {
   ConditionEvaluator,
@@ -101,30 +94,40 @@ export type {
   AgentCompactionConfig,
   AgentResponse,
   Term,
-  Guideline,
-  GuidelineMatch,
+  Instruction,
+  ScopedInstructions,
+  AppliedInstruction,
   ContextLifecycleHooks,
   ContextProvider,
+  HookContext,
+  ExitReason,
   Event,
   EmittedEvent,
   MessageEventData,
   ToolEventData,
   StatusEventData,
   Participant,
-  RouteRef,
+  FlowRef,
   StepRef,
-  RouteOptions,
+  FlowOptions,
   StepOptions,
-  RouteTransitionConfig,
-  RouteCompletionHandler,
+  FlowLifecycleHooks,
+  StepLifecycleHooks,
   SessionState,
-  PendingTransition,
+  SignalsState,
+  SignalTriggerState,
+  Signal,
+  SignalContext,
+  SignalDirective,
+  SignalPredicate,
+  SignalPredicateContext,
+  SignalFiring,
+  SignalSchema,
   ToolContext,
   ToolResult,
   ToolHandler,
   Tool,
 
-  EnhancedTool,
   ToolValidationResult,
   ToolPermissionResult,
   ToolCallRequest,
@@ -161,20 +164,23 @@ export type {
   PersistenceAdapter,
   Template,
   TemplateContext,
-  ConditionTemplate,
   ConditionEvaluationResult,
   UserHistoryItem,
   AssistantHistoryItem,
   ToolHistoryItem,
   SystemHistoryItem,
-  // Multi-step execution types
+  // Flow execution types
   StoppedReason,
-  BatchResult,
-  BatchExecutionResult,
-  BatchExecutionEvent,
-  BatchExecutionEventType,
-  BatchExecutionTiming,
-  BatchExecutionError,
+  PrepareResult,
+  Directive,
+  PreDirective,
+  BranchEntry,
+  BranchMap,
+  BranchPredicate,
+  BranchPredicateContext,
+  ConditionPredicate,
+  ConditionIf,
+  ConditionWhen,
 } from "./types";
 export { CompositionMode, EventKind, MessageRole } from "./types";
-export { createSession, createSessionId, enterRoute, enterStep, mergeCollected } from "./utils";
+export { createSession, createSessionId, enterFlow, enterStep, completeCurrentFlow, isFlowCompletedThisSession, mergeCollected } from "./utils";

package/src/providers/GeminiProvider.ts

@@ -231,24 +231,26 @@ export class GeminiProvider implements AiProvider {
 
   /**
    * Safely extract text from a Gemini response or chunk.
-   * The `.text` getter can throw when the response contains only function calls
-   * (observed in some SDK versions). This method falls back to manually
-   * extracting text parts from candidates.
+   * Bypasses the SDK's `.text` getter entirely to avoid warnings about
+   * non-text parts (e.g., "thoughtSignature") in the response.
+   * Manually concatenates only text parts from candidates.
    *
    * @private
    */
   private safeExtractText(responseOrChunk: { text?: string; candidates?: Array<{ content?: { parts?: Array<{ text?: string; functionCall?: unknown }> } }> }): string {
+    // Always extract text parts manually to avoid SDK warnings about
+    // non-text parts like "thoughtSignature" in the response.
+    const parts = responseOrChunk.candidates?.[0]?.content?.parts;
+    if (parts) {
+      return parts
+        .filter((p) => p.text != null)
+        .map((p) => p.text)
+        .join("");
+    }
+    // Fallback: try the .text getter if no candidates structure exists
     try {
       return responseOrChunk.text || "";
     } catch {
-      // .text getter threw — extract text parts manually
-      const parts = responseOrChunk.candidates?.[0]?.content?.parts;
-      if (parts) {
-        return parts
-          .filter((p) => p.text != null)
-          .map((p) => p.text)
-          .join("");
-      }
       return "";
     }
   }
@@ -534,17 +536,17 @@ export class GeminiProvider implements AiProvider {
         }
       }
 
+      // Safely extract text — avoids SDK warning about non-text parts
+      const message = this.safeExtractText(response);
+
       // Debug logging for response structure
-      if (!response.text && toolCalls.length === 0) {
+      if (!message && toolCalls.length === 0) {
         logger.debug(`[GeminiProvider] Debug - Response structure:`, {
           candidatesCount: response.candidates?.length || 0,
           firstCandidateParts: response.candidates?.[0]?.content?.parts?.length || 0,
         });
       }
 
-      // Safely extract text — .text getter can throw when response has only function calls
-      const message = this.safeExtractText(response);
-
       // Only throw error if we have no text AND no function calls
       if (!message && toolCalls.length === 0) {
         logger.error(`[GeminiProvider] Empty response - no text or function calls`);