@falai/agent 0.4.0 → 0.5.0

package/src/types/agent.ts

@@ -21,11 +21,6 @@ export enum CompositionMode {
   CANNED_STRICT = "strict_canned",
 }
 
-/**
- * Forward declare observation types
- */
-import type { ObservationOptions } from "./observation";
-
 /**
  * Context lifecycle hooks for managing state persistence
  */
@@ -44,6 +39,19 @@ export interface ContextLifecycleHooks<TContext = unknown> {
     newContext: TContext,
     previousContext: TContext
   ) => Promise<void> | void;
+
+  /**
+   * Called after extracted data is updated (from AI response or tool execution)
+   * Useful for validation, enrichment, or persistence of gathered data
+   * Return modified extracted data or the same data to keep it unchanged
+   *
+   * Note: This hook works with ANY route's extracted data (since an agent can have
+   * multiple routes with different extraction schemas). Use type guards or runtime
+   * checks if you need type-specific logic.
+   */
+
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  onExtractedUpdate?: (extracted: any, previousExtracted: any) => any;
 }
 
 /**
@@ -64,6 +72,8 @@ export interface AgentOptions<TContext = unknown> {
   description?: string;
   /** The agent's primary goal or objective */
   goal?: string;
+  /** Optional personality/tone instructions used in prompts */
+  personality?: string;
   /** Default context data available to the agent */
   context?: TContext;
   /** Context provider function for always-fresh context (alternative to static context) */
@@ -72,8 +82,6 @@ export interface AgentOptions<TContext = unknown> {
   hooks?: ContextLifecycleHooks<TContext>;
   /** AI provider strategy for generating responses */
   ai: AiProvider;
-  /** Maximum number of processing iterations per request */
-  maxEngineIterations?: number;
   /** Composition mode for response generation */
   compositionMode?: CompositionMode;
   /** Initial terms for domain glossary */
@@ -83,9 +91,7 @@ export interface AgentOptions<TContext = unknown> {
   /** Initial capabilities */
   capabilities?: Capability[];
   /** Initial routes (will be instantiated as Route objects) */
-  routes?: RouteOptions[];
-  /** Initial observations for disambiguation */
-  observations?: ObservationOptions[];
+  routes?: RouteOptions<unknown>[];
   /** Optional persistence configuration for auto-saving sessions and messages */
   persistence?: PersistenceConfig;
 }

package/src/types/ai.ts

@@ -45,8 +45,12 @@ export interface GenerateMessageInput<TContext = unknown> {
     maxOutputTokens?: number;
     /** Reasoning/thinking configuration */
     reasoning?: ReasoningConfig;
-    /** Enable structured JSON output mode */
-    jsonMode?: boolean;
+    /**
+     * Required: Structured JSON schema the provider must enforce for output
+     */
+    jsonSchema: { [key: string]: unknown };
+    /** Optional schema name (used by providers that require one) */
+    schemaName?: string;
   };
   /** Abort signal for cancellation */
   signal?: AbortSignal;

package/src/types/history.ts

@@ -54,6 +54,14 @@ export interface MessageEventData {
   flagged?: boolean;
   /** Tags/reasons if flagged */
   tags?: string[];
+  /** Session metadata attached to this message */
+  session?: {
+    routeId?: string;
+    routeTitle?: string;
+    stateId?: string;
+    stateDescription?: string;
+    extracted?: Record<string, unknown>;
+  };
 }
 
 /**

package/src/types/index.ts

@@ -44,17 +44,6 @@ export type {
   GenerateMessageOutput,
 } from "./ai";
 
-// Prompt types
-export type {
-  PromptSection,
-  ContextVariable,
-  ContextVariableValue,
-} from "./prompt";
-export { SectionStatus } from "./prompt";
-
-// Observation types
-export type { Observation, ObservationOptions } from "./observation";
-
 // Persistence types
 export type {
   SessionData,

package/src/types/route.ts

@@ -3,6 +3,7 @@
  */
 
 import type { ToolRef } from "./tool";
+import type { StructuredSchema } from "./schema";
 
 /**
  * Reference to a route
@@ -29,8 +30,9 @@ import type { Guideline } from "./agent";
 
 /**
  * Options for creating a route
+ * @template TExtracted - Type of data extracted throughout the route (inferred from gatherSchema)
  */
-export interface RouteOptions {
+export interface RouteOptions<TExtracted = unknown> {
   /** Custom ID for the route (optional - will generate deterministic ID from title if not provided) */
   id?: string;
   /** Title of the route */
@@ -47,12 +49,27 @@ export interface RouteOptions {
   rules?: string[];
   /** Absolute prohibitions the agent must never do in this route */
   prohibitions?: string[];
+  /** Optional: extractions the router may return (added to routing schema) */
+  routingExtrasSchema?: StructuredSchema;
+  /** Optional: structured response data for this route's message generation */
+  responseOutputSchema?: StructuredSchema;
+  /**
+   * NEW: Schema defining data to extract throughout this route
+   * This creates a type-safe contract for what data the route collects
+   */
+  gatherSchema?: StructuredSchema;
+  /**
+   * NEW: Initial data to pre-populate when entering this route
+   * Useful for restoring sessions or pre-filling known information
+   * States with skipIf conditions will be automatically bypassed if data is present
+   */
+  initialData?: Partial<TExtracted>;
 }
 
 /**
  * Specification for a state transition
  */
-export interface TransitionSpec<TContext = unknown> {
+export interface TransitionSpec<TContext = unknown, TExtracted = unknown> {
   /** Transition to a chat state with this description */
   chatState?: string;
   /** Transition to execute a tool */
@@ -60,16 +77,35 @@ export interface TransitionSpec<TContext = unknown> {
   toolState?: ToolRef<TContext, any[], any>;
   /** Transition to a specific state or end marker */
   state?: StateRef | symbol;
+  /**
+   * NEW: Fields to gather from the conversation in this state
+   * These should match keys in the route's gatherSchema
+   */
+  gather?: string[];
+  /**
+   * NEW: Function to determine if this state should be skipped
+   * If returns true, the state will be bypassed
+   * @param extracted - Currently extracted data
+   * @returns true if state should be skipped, false otherwise
+   */
+  skipIf?: (extracted: Partial<TExtracted>) => boolean;
+  /**
+   * NEW: Required data fields that must be present before entering this state
+   * If any required field is missing, state cannot be entered
+   * Uses string[] for developer-friendly usage (same as gather)
+   */
+  requiredData?: string[];
 }
 
 /**
  * Result of a transition operation
  * Combines state reference with the ability to chain transitions
  */
-export interface TransitionResult<TContext = unknown> extends StateRef {
+export interface TransitionResult<TContext = unknown, TExtracted = unknown>
+  extends StateRef {
   /** Allow chaining transitions */
   transitionTo: (
-    spec: TransitionSpec<TContext>,
+    spec: TransitionSpec<TContext, TExtracted>,
     condition?: string
-  ) => TransitionResult<TContext>;
+  ) => TransitionResult<TContext, TExtracted>;
 }

package/src/types/routing.ts

@@ -0,0 +1,18 @@
+import type { StructuredSchema } from "./schema";
+
+export interface RoutingDecision {
+  context: string;
+  routes: Record<string, number>;
+  responseDirectives?: string[];
+  extractions?: unknown;
+  contextUpdate?: Record<string, unknown>;
+}
+
+export interface RoutingDecisionWithRoute extends RoutingDecision {
+  selectedRouteId: string;
+  maxScore: number;
+}
+
+export interface RoutingSchemaOptions {
+  extrasSchema?: StructuredSchema;
+}

package/src/types/schema.ts

@@ -0,0 +1,23 @@
+/**
+ * StructuredSchema - minimal JSON Schema subset used across providers
+ */
+export interface StructuredSchema {
+  type?: string | string[];
+  description?: string;
+  enum?: Array<string | number | boolean | null>;
+  nullable?: boolean;
+  properties?: Record<string, StructuredSchema>;
+  required?: string[];
+  items?: StructuredSchema;
+  additionalProperties?: boolean | StructuredSchema;
+  // Allow provider-specific passthroughs without breaking types
+  [key: string]: unknown;
+}
+
+/**
+ * A small helper describing a named schema (for providers that require a name)
+ */
+export interface NamedSchema {
+  name?: string;
+  schema: StructuredSchema;
+}

package/src/types/session.ts

@@ -0,0 +1,207 @@
+/**
+ * Session state types for tracking conversation progress
+ */
+
+/**
+ * Session state tracks the current position in the conversation flow
+ * and data extracted during the route progression
+ */
+export interface SessionState<TExtracted = Record<string, unknown>> {
+  /** Current route the conversation is in */
+  currentRoute?: {
+    id: string;
+    title: string;
+    enteredAt: Date;
+  };
+
+  /** Current state within the route */
+  currentState?: {
+    id: string;
+    description?: string;
+    enteredAt: Date;
+  };
+
+  /** Data extracted during the current route */
+  extracted: Partial<TExtracted>;
+
+  /** History of routes visited in this session */
+  routeHistory: Array<{
+    routeId: string;
+    enteredAt: Date;
+    exitedAt?: Date;
+    completed: boolean;
+  }>;
+
+  /** Session metadata */
+  metadata?: {
+    sessionId?: string;
+    createdAt?: Date;
+    lastUpdatedAt?: Date;
+    [key: string]: unknown;
+  };
+}
+
+/**
+ * Helper to create a new session
+ */
+export function createSession<TExtracted = Record<string, unknown>>(
+  metadata?: SessionState<TExtracted>["metadata"]
+): SessionState<TExtracted> {
+  return {
+    extracted: {},
+    routeHistory: [],
+    metadata: {
+      ...metadata,
+      createdAt: new Date(),
+      lastUpdatedAt: new Date(),
+    },
+  };
+}
+
+/**
+ * Helper to update session with new route
+ */
+export function enterRoute<TExtracted = Record<string, unknown>>(
+  session: SessionState<TExtracted>,
+  routeId: string,
+  routeTitle: string
+): SessionState<TExtracted> {
+  // Exit current route if exists
+  const routeHistory = [...session.routeHistory];
+  if (session.currentRoute) {
+    const lastRouteIndex = routeHistory.findIndex(
+      (r) => r.routeId === session.currentRoute?.id && !r.exitedAt
+    );
+    if (lastRouteIndex >= 0) {
+      routeHistory[lastRouteIndex].exitedAt = new Date();
+    }
+  }
+
+  // Enter new route
+  const now = new Date();
+  return {
+    ...session,
+    currentRoute: {
+      id: routeId,
+      title: routeTitle,
+      enteredAt: now,
+    },
+    currentState: undefined,
+    extracted: {}, // Reset extracted data for new route
+    routeHistory: [
+      ...routeHistory,
+      {
+        routeId,
+        enteredAt: now,
+        completed: false,
+      },
+    ],
+    metadata: {
+      ...session.metadata,
+      lastUpdatedAt: now,
+    },
+  };
+}
+
+/**
+ * Helper to update session with new state
+ */
+export function enterState<TExtracted = Record<string, unknown>>(
+  session: SessionState<TExtracted>,
+  stateId: string,
+  stateDescription?: string
+): SessionState<TExtracted> {
+  return {
+    ...session,
+    currentState: {
+      id: stateId,
+      description: stateDescription,
+      enteredAt: new Date(),
+    },
+    metadata: {
+      ...session.metadata,
+      lastUpdatedAt: new Date(),
+    },
+  };
+}
+
+/**
+ * Helper to merge extracted data into session
+ */
+export function mergeExtracted<TExtracted = Record<string, unknown>>(
+  session: SessionState<TExtracted>,
+  extracted: Partial<TExtracted>
+): SessionState<TExtracted> {
+  return {
+    ...session,
+    extracted: {
+      ...session.extracted,
+      ...extracted,
+    },
+    metadata: {
+      ...session.metadata,
+      lastUpdatedAt: new Date(),
+    },
+  };
+}
+
+/**
+ * Helper to convert SessionState to persistence-friendly format
+ * Used when saving to database
+ */
+export function sessionStateToData<TExtracted = Record<string, unknown>>(
+  session: SessionState<TExtracted>
+): {
+  currentRoute?: string;
+  currentState?: string;
+  collectedData: Record<string, unknown>;
+} {
+  return {
+    currentRoute: session.currentRoute?.id,
+    currentState: session.currentState?.id,
+    collectedData: {
+      extracted: session.extracted,
+      routeHistory: session.routeHistory,
+      currentRouteTitle: session.currentRoute?.title,
+      currentStateDescription: session.currentState?.description,
+      metadata: session.metadata,
+    },
+  };
+}
+
+/**
+ * Helper to convert database SessionData back to SessionState
+ * Used when loading from database
+ */
+export function sessionDataToState<TExtracted = Record<string, unknown>>(data: {
+  currentRoute?: string;
+  currentState?: string;
+  collectedData?: Record<string, unknown>;
+}): Partial<SessionState<TExtracted>> {
+  const collectedData = data.collectedData || {};
+
+  return {
+    currentRoute: data.currentRoute
+      ? {
+          id: data.currentRoute,
+          title:
+            (collectedData.currentRouteTitle as string) || data.currentRoute,
+          enteredAt: new Date(),
+        }
+      : undefined,
+    currentState: data.currentState
+      ? {
+          id: data.currentState,
+          description:
+            (collectedData.currentStateDescription as string) || undefined,
+          enteredAt: new Date(),
+        }
+      : undefined,
+    extracted: (collectedData.extracted as Partial<TExtracted>) || {},
+    routeHistory:
+      (collectedData.routeHistory as SessionState<TExtracted>["routeHistory"]) ||
+      [],
+    metadata:
+      (collectedData.metadata as SessionState<TExtracted>["metadata"]) || {},
+  };
+}

package/src/types/tool.ts

@@ -7,7 +7,7 @@ import type { Event, StateRef } from "./index";
 /**
  * Context provided to tool handlers
  */
-export interface ToolContext<TContext = unknown> {
+export interface ToolContext<TContext = unknown, TExtracted = unknown> {
   /** The agent's context data */
   context: TContext;
   /** Update the agent's context (triggers lifecycle hooks if configured) */
@@ -16,6 +16,8 @@ export interface ToolContext<TContext = unknown> {
   state?: StateRef;
   /** Interaction history */
   history: Event[];
+  /** Data extracted so far in the current route */
+  extracted?: Partial<TExtracted>;
   /** Additional metadata */
   metadata?: Record<string, unknown>;
 }
@@ -23,11 +25,17 @@ export interface ToolContext<TContext = unknown> {
 /**
  * Result returned by a tool
  */
-export interface ToolResult<TData = unknown, TContext = unknown> {
+export interface ToolResult<
+  TData = unknown,
+  TContext = unknown,
+  TExtracted = unknown
+> {
   /** The result data */
   data: TData;
   /** Optional context update to be merged with current context */
   contextUpdate?: Partial<TContext>;
+  /** Optional extracted data update to be merged with session state */
+  extractedUpdate?: Partial<TExtracted>;
   /** Optional metadata about the execution */
   meta?: Record<string, unknown>;
 }
@@ -35,23 +43,37 @@ export interface ToolResult<TData = unknown, TContext = unknown> {
 /**
  * Handler function for a tool
  */
-export type ToolHandler<TContext, TArgs extends unknown[], TResult> = (
-  context: ToolContext<TContext>,
+export type ToolHandler<
+  TContext,
+  TArgs extends unknown[],
+  TResult,
+  TExtracted = unknown
+> = (
+  context: ToolContext<TContext, TExtracted>,
   ...args: TArgs
-) => Promise<ToolResult<TResult, TContext>> | ToolResult<TResult, TContext>;
+) =>
+  | Promise<ToolResult<TResult, TContext, TExtracted>>
+  | ToolResult<TResult, TContext, TExtracted>;
 
 /**
  * Reference to a defined tool
  */
-export interface ToolRef<TContext, TArgs extends unknown[], TResult> {
+export interface ToolRef<
+  TContext,
+  TArgs extends unknown[],
+  TResult,
+  TExtracted = unknown
+> {
   /** Tool identifier */
   id: string;
   /** Tool name */
   name: string;
   /** Tool handler function */
-  handler: ToolHandler<TContext, TArgs, TResult>;
+  handler: ToolHandler<TContext, TArgs, TResult, TExtracted>;
   /** Description of what the tool does */
   description?: string;
   /** Parameter schema or description */
   parameters?: unknown;
+  /** Domain this tool belongs to (set when added via agent.addDomain) */
+  domainName?: string;
 }

package/src/utils/id.ts

@@ -53,16 +53,6 @@ export function generateStateId(
   return `state_${routeId}_${suffix}`;
 }
 
-/**
- * Generate a deterministic observation ID
- * Format: observation_{sanitized_description}_{hash}
- */
-export function generateObservationId(description: string): string {
-  const sanitized = sanitize(description.substring(0, 50)); // Limit length
-  const hash = simpleHash(description);
-  return `observation_${sanitized}_${hash}`;
-}
-
 /**
  * Generate a deterministic tool ID
  * Format: tool_{sanitized_name}_{hash}

package/src/utils/schema.ts

@@ -0,0 +1,32 @@
+import type { StructuredSchema } from "../types/schema";
+
+/**
+ * Convert our StructuredSchema to the OpenAI/OpenRouter JSON schema format
+ * (they already accept standard JSON Schema for responses.parse)
+ */
+export function convertToOpenAIJsonSchema(schema: StructuredSchema): object {
+  // For now our schema aligns well with JSON Schema draft-like structure
+  // Return as-is; callers should ensure correctness
+  return schema as object;
+}
+
+/**
+ * Convert our StructuredSchema to Gemini responseSchema (Type mapping)
+ * The @google/genai expects a slightly different shape
+ */
+export function convertToGeminiSchema(schema: StructuredSchema): object {
+  // Basic passthrough. If needed, a deeper mapping can be added later.
+  // Gemini supports a similar structure (type, properties, items, enum, etc.)
+  return schema as object;
+}
+
+/**
+ * Convert our StructuredSchema into Anthropic system prompt constraints.
+ * Since Anthropic lacks native schema parsing, we embed a concise instruction.
+ */
+export function convertToAnthropicConstraint(schema: StructuredSchema): string {
+  // Keep it concise to avoid context bloat
+  return `You must respond with valid JSON that matches this schema: ${JSON.stringify(
+    schema
+  )}`;
+}

package/dist/cjs/core/ConditionEvaluator.d.ts

@@ -1,72 +0,0 @@
-/**
- * ConditionEvaluator - Handles AI-powered condition evaluation
- *
- * This class is responsible for:
- * - Evaluating guideline conditions
- * - Evaluating transition conditions
- * - Extracting tool arguments from context and history
- */
-import type { Event, AiProvider } from "../types/index";
-import type { Guideline } from "../types/agent";
-import type { ToolRef } from "../types/tool";
-/**
- * Result of guideline condition evaluation
- */
-export interface GuidelineEvaluationResult {
-    matches: boolean;
-    rationale?: string;
-}
-/**
- * Result of transition condition evaluation
- */
-export interface TransitionEvaluationResult {
-    shouldFollow: boolean;
-    rationale?: string;
-}
-/**
- * Result of tool argument extraction
- */
-export interface ArgumentExtractionResult {
-    arguments: unknown[];
-    rationale?: string;
-}
-/**
- * ConditionEvaluator - Evaluates conditions using AI
- */
-export declare class ConditionEvaluator<TContext = unknown> {
-    private readonly ai;
-    constructor(ai: AiProvider);
-    /**
-     * Evaluate a guideline condition against context and history
-     */
-    evaluateGuidelineCondition(guideline: Guideline, context: TContext, history: Event[]): Promise<GuidelineEvaluationResult>;
-    /**
-     * Evaluate a transition condition
-     */
-    evaluateTransitionCondition(condition: string, context: TContext, history: Event[]): Promise<TransitionEvaluationResult>;
-    /**
-     * Extract tool arguments from context and history
-     */
-    extractToolArguments(tool: ToolRef<TContext, unknown[], unknown>, context: TContext, history: Event[]): Promise<ArgumentExtractionResult>;
-    /**
-     * Simple argument extraction from context (fallback)
-     */
-    simpleArgumentExtraction(tool: ToolRef<TContext, unknown[], unknown>, context: TContext): unknown[];
-    /**
-     * Extract recent messages from history
-     */
-    private extractRecentMessages;
-    /**
-     * Parse guideline evaluation from text response (fallback)
-     */
-    private parseGuidelineResponse;
-    /**
-     * Parse transition evaluation from text response (fallback)
-     */
-    private parseTransitionResponse;
-    /**
-     * Parse argument extraction from text response (fallback)
-     */
-    private parseArgumentResponse;
-}
-//# sourceMappingURL=ConditionEvaluator.d.ts.map

package/dist/cjs/core/ConditionEvaluator.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ConditionEvaluator.d.ts","sourceRoot":"","sources":["../../../src/core/ConditionEvaluator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAoB,MAAM,gBAAgB,CAAC;AAE1E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,OAAO,EAAE,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA0BD;;GAEG;AACH,qBAAa,kBAAkB,CAAC,QAAQ,GAAG,OAAO;IACpC,OAAO,CAAC,QAAQ,CAAC,EAAE;gBAAF,EAAE,EAAE,UAAU;IAE3C;;OAEG;IACG,0BAA0B,CAC9B,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,KAAK,EAAE,GACf,OAAO,CAAC,yBAAyB,CAAC;IA0DrC;;OAEG;IACG,2BAA2B,CAC/B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,KAAK,EAAE,GACf,OAAO,CAAC,0BAA0B,CAAC;IAyDtC;;OAEG;IACG,oBAAoB,CACxB,IAAI,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAC3C,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,KAAK,EAAE,GACf,OAAO,CAAC,wBAAwB,CAAC;IAiEpC;;OAEG;IACH,wBAAwB,CACtB,IAAI,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,OAAO,CAAC,EAC3C,OAAO,EAAE,QAAQ,GAChB,OAAO,EAAE;IAgCZ;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAc7B;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAW9B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAc/B;;OAEG;IACH,OAAO,CAAC,qBAAqB;CAsB9B"}