@falai/agent 3.4.5 → 4.0.0-alpha.2

package/src/types/history.ts

@@ -16,8 +16,6 @@ export enum MessageRole {
   SYSTEM = "system",
 }
 
-import type { SessionState } from "./session.js";
-
 /**
  * Types of events in the interaction history
  */
@@ -59,6 +57,13 @@ export type AssistantHistoryItem = {
     name: string;
     arguments: Record<string, unknown>;
   }>;
+  /** What the model thought before it called those tools. A thinking provider
+   *  rejects the next round without it. Set by the framework on its own tool
+   *  rounds; a host building history by hand leaves it out. */
+  reasoning?: string;
+  /** The same thing in the normalized shape OpenRouter sends. Replayed
+   *  verbatim, under the name the gateway gave it. */
+  reasoningDetails?: unknown[];
 };
 export type ToolHistoryItem = {
   role: "tool";
@@ -86,24 +91,6 @@ export type HistoryItem =
  */
 export type History = HistoryItem[];
 
-/**
- * Simple JSON format for history messages (developer-friendly)
- */
-export interface HistoryMessage<TData = unknown> {
-  /** Role of the message sender */
-  role: MessageRole;
-  /** Message content */
-  content: string;
-  /** Optional participant name */
-  name?: string;
-  /** Optional timestamp (ISO string) */
-  timestamp?: string;
-  /** Optional session state */
-  session?: SessionState<TData>;
-  /** Optional additional metadata */
-  metadata?: Record<string, unknown>;
-}
-
 /**
  * Data for a message event
  */

package/src/types/index.ts

@@ -1,164 +1,112 @@
 /**
- * Central type definitions export
+ * Every public type, in one place.
  */
 
-// Agent types
 export type {
-  AgentOptions,
   AgentCompactionConfig,
-  Term,
-  Instruction,
-  ScopedInstructions,
-  AppliedInstruction,
-  AgentResponseStreamChunk,
-  AgentResponse,
-  EndedFlow,
-  ContextLifecycleHooks,
-  ContextProvider,
-  ValidationError,
-  ValidationResult,
-  HookContext,
-  ExitReason,
+  AgentOptions,
+  BusinessHours,
+  Clock,
+  EndReason,
+  Idle,
+  OutboundMessage,
+  ScheduleEntry,
+  Silenced,
+  TurnBase,
+  TurnInput,
+  TurnKind,
+  TurnResult,
+  TurnStreamChunk,
 } from "./agent.js";
 
-// History types
-export type {
-  Event,
-  EmittedEvent,
-  MessageEventData,
-  ToolEventData,
-  StatusEventData,
-  Participant,
-  ToolResult as EventToolResult,
-  ToolCall,
-  HistoryMessage,
-  Role,
-  HistoryItem,
-  History,
-  UserHistoryItem,
-  AssistantHistoryItem,
-  SystemHistoryItem,
-  ToolHistoryItem,
-} from "./history.js";
-export { EventKind, MessageRole } from "./history.js";
-
-// Flow types
 export type {
-  FlowOptions,
-  FlowRef,
-  StepRef,
-  StepOptions,
-  FlowLifecycleHooks,
-  StepLifecycleHooks,
-  Directive,
-  BranchEntry,
-  BranchMap,
-  BranchPredicate,
-  BranchPredicateContext,
-  ConditionPredicate,
-  ConditionIf,
-  ConditionWhen,
-  StoppedReason,
-  PrepareResult,
+  Action,
+  ActionCtx,
+  ActionMap,
+  ActionResult,
+  Branch,
+  Condition,
+  ConditionMap,
+  ConditionSpec,
+  DoStep,
+  Duration,
+  EventDef,
+  EventMap,
+  FieldDef,
+  FieldDefs,
+  Flow,
+  IfStep,
+  InferData,
+  InferParams,
+  Instruction,
+  Next,
+  ParamDef,
+  ParamDefs,
+  Pred,
+  PredCtx,
+  Repeat,
+  SayStep,
+  ScalarDef,
+  ScalarType,
+  Step,
+  StepBase,
+  TalkStep,
+  Template,
+  Trigger,
+  WaitEventStep,
+  WaitStep,
 } from "./flow.js";
 
-// Session types
-export type { SessionState } from "./session.js";
-
-// Signals types (canonical source)
-export type {
-  Signal,
-  SignalContext,
-  SignalDirective,
-  ResolvedSignalDirective,
-  SignalPredicate,
-  SignalPredicateContext,
-  SignalFiring,
-  SignalSchema,
-  SignalsState,
-  SignalTriggerState,
-} from "./signals.js";
-
-// Tool types
 export type {
-  Tool,
-  ToolContext,
-  ToolResult,
-  ToolHandler,
-  ToolExecutionResult,
-  ToolValidationResult,
-  ToolPermissionResult,
-  ToolCallRequest,
-  ToolExecutionUpdate,
-  TrackedTool,
-  ToolStatus,
-  DataEnrichmentConfig,
-  ValidationConfig,
-  ApiCallConfig,
-  ComputationConfig
-} from "./tool.js";
-export { ToolScope } from "./tool.js";
+  Run,
+  RunStatus,
+  Session,
+  StepOutcome,
+  StepOutcomeCode,
+  StepOutcomeKind,
+  StepOutcomeStatus,
+  Store,
+  TriggerKind,
+} from "./session.js";
 
-// Compaction types
-export type {
-  CompactionOptions,
-  CompactionResult,
-} from "./compaction.js";
-
-// Prompt cache types
-export type {
-  PromptSectionType,
-  PromptCacheConfig,
-  SectionCompute,
-} from "./prompt-cache.js";
+export type { Tool, ToolCtx, ToolPermissionResult, ToolResult, ToolValidationResult } from "./tool.js";
 
-// AI provider types
 export type {
+  AgentStructuredResponse,
   AiProvider,
   GenerateMessageInput,
   GenerateMessageOutput,
-  AgentStructuredResponse,
-  ReasoningConfig,
+  TokenUsage,
   GenerateMessageStreamChunk,
   ProviderCapabilities,
+  ReasoningConfig,
 } from "./ai.js";
 
-// Schema types
-export type { StructuredSchema } from "./schema.js";
-
-// Persistence types
-export type {
-  SessionData,
-  MessageData,
-  SessionStatus,
-  SessionRepository,
-  MessageRepository,
-  PersistenceAdapter,
-  PersistenceConfig,
-  CreateSessionOptions,
-  CreateSessionData,
-  SaveMessageOptions,
-  CollectedStateData,
-  SessionUpdateOptions,
-} from "./persistence.js";
-
-// Template types
 export type {
-  Template,
-  TemplateContext,
-  ConditionEvaluationResult
-} from "./template.js";
-
-// Error types
-export { NotImplementedError, SessionConflictError, ProviderError } from "./errors.js";
-export type { ErrorKind } from "./errors.js";
+  AssistantHistoryItem,
+  EmittedEvent,
+  Event,
+  History,
+  HistoryItem,
+  MessageEventData,
+  Participant,
+  Role,
+  StatusEventData,
+  SystemHistoryItem,
+  ToolCall,
+  ToolEventData,
+  ToolHistoryItem,
+  ToolResult as EventToolResult,
+  UserHistoryItem,
+} from "./history.js";
+export { EventKind, MessageRole } from "./history.js";
 
-// Internal — ConditionTemplate is NOT exported from the public surface in v2.
-// It remains internally for the condition evaluator utility.
+export type { StructuredSchema } from "./schema.js";
+export type { CompactionOptions, CompactionResult } from "./compaction.js";
 
 export {
-  ConditionEvaluator,
-  createConditionEvaluator,
-  extractAIContextStrings,
-  hasProgrammaticConditions
-} from "../utils/condition.js";
+  FlowConfigurationError,
+  ProviderError,
+  SessionConflictError,
+} from "./errors.js";
+export type { ErrorKind } from "./errors.js";

package/src/types/session.ts

@@ -1,86 +1,151 @@
 /**
- * Session step types for tracking conversation progress
+ * Runtime state: runs, step outcomes, the session blob and the Store seam.
+ *
+ * The session blob is the unit of consistency (invariant I1): the host loads
+ * it, calls `turn`, and saves it back with the version it loaded. A losing
+ * save throws `SessionConflictError` and the same input is replayed.
  */
 
 import type { History } from "./history.js";
-import type { Directive } from "./flow.js";
-import type { SignalsState } from "./signals.js";
 
-// Re-export for backward compatibility — canonical declarations live in ./signals.ts
-export type { SignalsState, SignalTriggerState } from "./signals.js";
+export type RunStatus = "running" | "asking" | "waiting" | "suspended";
 
-/**
- * Session state tracks the current position in the conversation flow
- * and data collected at the agent level across all flows
- */
-export interface SessionState<TData = unknown> {
-  /** Unique session identifier (useful for persistence) */
-  id: string;
-
-  /** Current flow the conversation is in */
-  currentFlow?: {
-    id: string;
-    title: string;
-    enteredAt?: Date;
-  };
+export type TriggerKind = "message" | "mention" | "silence" | "event" | "start" | "flow";
 
-  /** Current step within the flow */
-  currentStep?: {
-    id: string;
-    description?: string;
-    enteredAt?: Date;
+/** One live execution of a flow inside a session. */
+export interface Run {
+  /** `${flowId}#${triggerKey}`: deterministic, so a replay mints the same keys. */
+  id: string;
+  flowId: string;
+  anchor: string;
+  dedupeKey: string;
+  stepId: string | null;
+  status: RunStatus;
+  trigger: { kind: TriggerKind; key: string; payload?: unknown };
+  input?: unknown;
+  /** Flow-to-flow chaining depth; capped at 5. */
+  hop: number;
+  startedAt: string;
+  /** Set while `suspended`; the most recently suspended run resumes first. */
+  suspendedAt?: string;
+  waiting?: {
+    kind: "timer" | "event";
+    /** The wake key; only a `wake` equal to it is honoured. */
+    key?: string;
+    until?: string;
+    setAt: string;
+    event?: string;
   };
+  /** Times each field was asked; a field at `maxAsks` is skipped. */
+  asked: Record<string, number>;
+  /** Times each step was entered; part of every action and message key. */
+  visits: Record<string, number>;
+  outcomes: StepOutcome[];
+}
 
-  /**
-   * Agent-level data collected across all flows
-   * This is the single source of truth for all collected data
-   * Flows can access and contribute to this shared data structure
-   */
-  data: Partial<TData>;
+export type StepOutcomeKind = "prompt" | "collect" | "say" | "do" | "wait" | "if" | "idle";
 
-  /** History of flows visited in this session */
-  flowHistory?: Array<{
-    flowId: string;
-    enteredAt?: Date;
-    exitedAt?: Date;
-    completed: boolean;
-  }>;
+export type StepOutcomeStatus = "ok" | "skipped" | "failed" | "waiting" | "deferred";
 
-  /**
-   * Pending directive to apply at the start of the next turn.
-   * Replaces the v1 `pendingTransition` field. When set, the turn pipeline
-   * applies this directive and skips `FlowRouter.decideFlowAndStep`.
-   *
-   * Cleared after application unless `complete.next` chains another directive.
-   */
-  pendingDirective?: Directive<unknown, TData>;
+/** One line per step for the host's execution log. */
+/**
+ * Why a line says what it says. Switch on this, never on `message`: the code
+ * is stable across versions, the sentence is not.
+ *
+ * `OUTCOME_MESSAGES` maps each one to its English sentence; a product that
+ * speaks another language maps the code to its own words instead.
+ */
+export type StepOutcomeCode =
+  // The turn refused the input
+  | "no-session"
+  | "duplicate-input"
+  | "stale-wake"
+  | "silence-broken"
+  // A trigger matched but started nothing
+  | "already-claimed"
+  | "cooldown"
+  | "hop-limit"
+  | "already-running"
+  | "flow-gone"
+  // A run ended early
+  | "step-loop"
+  | "step-gone"
+  | "customer-replied"
+  | "premise-changed"
+  | "silenced"
+  // A step
+  | "already-known"
+  | "another-reply"
+  | "already-sent"
+  | "branch"
+  | "max-asks"
+  | "inline-delay"
+  | "awaiting-trigger"
+  | "awaiting-event"
+  | "event-arrived"
+  | "no-event"
+  | "replied"
+  | "no-reply"
+  // A host action
+  | "action-skipped"
+  | "action-failed"
+  | "action-deferred"
+  // A value the model gave
+  | "unknown-field"
+  | "bad-value"
+  | "not-in-enum"
+  // The model
+  | "provider-unavailable"
+  | "provider-quota"
+  | "provider-context"
+  | "provider-auth"
+  | "provider-invalid";
 
-  /**
-   * Reserved for v2.x Signals feature. v2.0 does not read or mutate this
-   * field at runtime — persistence adapters preserve it bit-identical through
-   * save → load roundtrips. See Decision D-Q6 in design.md.
-   */
-  signals?: SignalsState;
+export interface StepOutcome {
+  runId?: string;
+  flowId?: string;
+  stepId?: string;
+  key?: string;
+  kind: StepOutcomeKind;
+  status: StepOutcomeStatus;
+  /** Why. Absent when the line needs no reason, such as a step that simply ran. */
+  code?: StepOutcomeCode;
+  /** The English sentence for `code`, filled by the framework. For logs; translate by `code` instead of showing this to someone who does not read English. */
+  message?: string;
+  /** Text this one occurrence carries: your `silenced` reason, an action's own words, the field a line is about. The framework never writes a sentence here. */
+  detail?: string;
+  next?: string;
+  until?: string;
+  at: string;
+  llmCalls?: number;
+}
 
-  /**
-   * Conversation history managed by the session
-   * Contains the full conversation between user and assistant
-   */
+/** One conversation's state. Holds many runs; at most one is asking. */
+export interface Session<D = unknown> {
+  id: string;
+  v: 4;
+  /** Optimistic-concurrency version; the host bumps it on save. */
+  version: number;
+  data: Partial<D>;
+  /** Live runs only. */
+  runs: Run[];
+  /** Once/cooldown claims: one key per flow. Always-flows keep the last 50. */
+  claims: Record<string, { at: string }>;
+  /** The last 50 keyed input ids, for replay detection. */
+  inputs: string[];
+  lastUserAt?: string;
+  lastAssistantAt?: string;
+  /** Kept only when the host does not manage history itself (playground). */
   history?: History;
+  metadata: Record<string, unknown>;
+}
 
-  /** Session metadata */
-  metadata?: {
-    createdAt?: Date;
-    lastUpdatedAt?: Date;
-    [key: string]: unknown;
-  };
-
-  /**
-   * Optimistic-concurrency version, managed by the persistence layer.
-   * Incremented on every successful save; a save with a stale version
-   * throws SessionConflictError instead of silently overwriting state
-   * written by a concurrent turn. Undefined for sessions never persisted
-   * or persisted by a pre-2.4 version (no conflict check is performed then).
-   */
-  version?: number;
+/**
+ * Where sessions live. `save` with `expectedVersion: 0` inserts if absent;
+ * a stale version throws `SessionConflictError`. On success the stored
+ * version is `expectedVersion + 1`, and the saved session comes back with it.
+ */
+export interface Store<D = unknown> {
+  load(id: string): Promise<Session<D> | null>;
+  save(session: Session<D>, expectedVersion: number): Promise<Session<D>>;
 }