@falai/agent 3.4.5 → 4.0.0-alpha.10

package/src/types/tool.ts

@@ -1,290 +1,65 @@
-/* eslint @typescript-eslint/no-explicit-any: "off"*/
 /**
- * Tool system type definitions
- */
-
-import type { Event, StepRef, ValidationResult } from "./index.js";
-import type { Directive } from "./flow.js";
-
-/**
- * Context provided to tool handlers
- */
-export interface ToolContext<TContext = unknown, TData = unknown> {
-  /** The agent's context data */
-  context: TContext;
-  /** Complete agent-level data collected so far */
-  data: Partial<TData>;
-  /** Interaction history */
-  history: Event[];
-  /** Current step reference (if in a flow) */
-  step?: StepRef;
-  /** Additional metadata */
-  metadata?: Record<string, unknown>;
-
-  /** Update the agent's context (triggers lifecycle hooks if configured) */
-  updateContext: (updates: Partial<TContext>) => Promise<void>;
-  /** Update the agent's collected data (triggers lifecycle hooks if configured) */
-  updateData: (updates: Partial<TData>) => Promise<void>;
-  /** Get a specific field from collected data */
-  getField<K extends keyof TData>(key: K): TData[K] | undefined;
-  /** Set a specific field in collected data */
-  setField<K extends keyof TData>(key: K, value: TData[K]): Promise<void>;
-  /** Check if a field exists in collected data */
-  hasField<K extends keyof TData>(key: K): boolean;
-
-  /**
-   * Emit a directive into the per-turn bus. Identical effect to returning
-   * `{ directive }` from the tool handler, but usable mid-handler (e.g.,
-   * after an early-exit branch decides the rest of the turn is moot).
-   *
-   * Multiple `dispatch()` calls in one handler are allowed; they are merged
-   * by Algorithm 4 along with directives from other tools/hooks this turn.
-   */
-  dispatch(directive: Directive<TContext, TData>): void;
-}
-
-/**
- * Result returned by a tool
- */
-export interface ToolResult<
-  TResultData = unknown,
-  TContext = unknown,
-  TData = unknown
-> {
-  /** The result data */
-  data?: TResultData;
-  /** Optional context update to be merged with current context */
-  contextUpdate?: Partial<TContext>;
-  /** Optional agent-level data update to be merged with collected data */
-  dataUpdate?: Partial<TData>;
-  /** Success indicator */
-  success?: boolean;
-  /** Error message if operation failed */
-  error?: string;
-  /** Optional metadata about the execution */
-  meta?: Record<string, unknown>;
-  /** Emit a directive declaratively (alternative to ctx.dispatch). */
-  directive?: Directive<TContext, TData>;
-  /** Emit multiple directives at once (alternative to repeated dispatch calls). */
-  directives?: Directive<TContext, TData>[];
-}
-
-/**
- * Handler function for a tool
- */
-export type ToolHandler<
-  TContext = unknown,
-  TData = unknown,
-  TResult = unknown
-> = (
-  context: ToolContext<TContext, TData>,
-  args?: Record<string, unknown>
-) =>
-    | Promise<TResult | ToolResult<TResult, TContext, TData>>
-    | TResult
-    | ToolResult<TResult, TContext, TData>;
-
-/**
- * Tool definition - single unified type (v2).
+ * Tools: typed functions the AI may call while it speaks.
  *
- * In v1 there were two tool types: `Tool` (basic) and `EnhancedTool`
- * (with metadata). v2 merges these into a single `Tool` type with all
- * metadata fields optional. `EnhancedTool` is removed from the public surface.
+ * A tool returns `{ value?, data? }`: `value` is what the model reads back,
+ * `data` is written to the session's collected data. Nothing else; movement
+ * between steps belongs to the flow, not to tools.
  */
-export interface Tool<
-  TContext = unknown,
-  TData = unknown,
-  TResult = unknown
-> {
-  /** Tool identifier */
-  id: string;
-  /** Tool handler function */
-  handler: ToolHandler<TContext, TData, TResult>;
-  /** Description of what the tool does (for AI discovery) */
-  description?: string;
-  /** Parameter schema or description */
-  parameters?: unknown;
-
-  // ── Optional metadata (merged from EnhancedTool in v2) ──
-
-  /** Whether this tool is safe to run concurrently with other concurrent-safe tools */
-  isConcurrencySafe?(input?: Record<string, unknown>): boolean;
-  /** Whether this tool only reads data without side effects */
-  isReadOnly?(input?: Record<string, unknown>): boolean;
-  /** Whether this tool performs destructive/irreversible operations */
-  isDestructive?(input?: Record<string, unknown>): boolean;
 
-  /** How the tool responds to abort signals: 'cancel' = immediate abort, 'block' = allow completion */
-  interruptBehavior?(): 'cancel' | 'block';
-  /** Maximum characters for the tool result before truncation */
-  maxResultSizeChars?: number;
-
-  /** Validate input before execution */
-  validateInput?(
-    input: Record<string, unknown>,
-    context: ToolContext<TContext, TData>
-  ): Promise<ToolValidationResult> | ToolValidationResult;
+import type { History } from "./history.js";
+import type { StructuredSchema } from "./schema.js";
+import type { Run } from "./session.js";
 
-  /** Check permissions before execution — when denied, handler is NOT invoked */
-  checkPermissions?(
-    input: Record<string, unknown>,
-    context: ToolContext<TContext, TData>
-  ): Promise<ToolPermissionResult> | ToolPermissionResult;
-}
-
-
-
-/**
- * Tool execution result
- */
-export interface ToolExecutionResult {
-  success: boolean;
-  data?: unknown;
-  error?: string;
-  contextUpdate?: Record<string, unknown>;
-  dataUpdate?: Record<string, unknown>;
-  metadata?: Record<string, unknown>;
-  /** Directives collected during tool execution (from ctx.dispatch and/or result.directive). */
-  directives?: Directive[];
+export interface ToolResult<D = unknown> {
+  /** What the model sees as the tool's answer. */
+  value?: unknown;
+  /** Collected data to write. */
+  data?: Partial<D>;
 }
 
-/**
- * Tool scope enumeration
- */
-export enum ToolScope {
-  AGENT = 'agent',
-  FLOW = 'flow',
-  STEP = 'step',
-  REGISTERED = 'registered',
-  ALL = 'all'
+export interface ToolCtx<C = unknown, D = unknown> {
+  context: C;
+  data: Partial<D>;
+  history: History;
+  /** The run that is speaking, when one is. */
+  run?: Run;
+  now: Date;
 }
 
-
-
-/**
- * Result of input validation on a tool call
- */
 export interface ToolValidationResult {
   valid: boolean;
   error?: string;
-  /** Suggested corrected input */
+  /** Suggested corrected input. */
   correctedInput?: Record<string, unknown>;
 }
 
-/**
- * Result of a permission check on a tool call
- */
 export interface ToolPermissionResult {
   allowed: boolean;
   reason?: string;
-  /** If not allowed, can the user override? */
-  canOverride?: boolean;
-}
-
-/**
- * A single tool invocation request from the LLM
- */
-export interface ToolCallRequest {
-  /** Unique ID for this tool call instance */
-  id: string;
-  /** Tool name/ID to execute */
-  toolName: string;
-  /** Arguments passed to the tool */
-  arguments: Record<string, unknown>;
-}
-
-/**
- * Result or progress update from a tool execution
- */
-export interface ToolExecutionUpdate<TData = unknown> {
-  /** The tool call this update relates to */
-  toolCallId: string;
-  /** Result message (undefined for progress updates) */
-  result?: ToolExecutionResult;
-  /** Progress message for long-running tools */
-  progress?: string;
-  /** Updated context after tool execution */
-  contextUpdate?: Record<string, unknown>;
-  /** Updated data after tool execution */
-  dataUpdate?: Partial<TData>;
-}
-
-/**
- * Internal status of a tracked tool in the executor queue
- */
-export type ToolStatus = 'queued' | 'executing' | 'completed' | 'yielded';
-
-/**
- * Internal type tracking the state of a queued or executing tool
- */
-export interface TrackedTool<TContext = unknown, TData = unknown> {
-  id: string;
-  toolCall: ToolCallRequest;
-  tool: Tool<TContext, TData>;
-  status: ToolStatus;
-  isConcurrencySafe: boolean;
-  promise?: Promise<void>;
-  results: ToolExecutionResult[];
-  pendingProgress: string[];
-}
-
-
-
-// --- Existing tool configuration types ---
-
-/**
- * Configuration for data enrichment tools
- */
-export interface DataEnrichmentConfig<TContext, TData, TFields extends keyof TData> {
-  id: string;
-  name?: string;
-  description?: string;
-  fields: TFields[];
-  enricher: (
-    context: TContext,
-    data: Pick<TData, TFields>
-  ) => Promise<Partial<TData>> | Partial<TData>;
-}
-
-/**
- * Configuration for validation tools
- */
-export interface ValidationConfig<TContext, TData, TFields extends keyof TData> {
-  id: string;
-  name?: string;
-  description?: string;
-  fields: TFields[];
-  validator: (
-    context: TContext,
-    data: Pick<TData, TFields>
-  ) => Promise<ValidationResult> | ValidationResult;
-}
-
-/**
- * Configuration for API call tools
- */
-export interface ApiCallConfig<TContext, TData, TResult> {
-  id: string;
-  name?: string;
-  description?: string;
-  endpoint: string | ((context: TContext, data: Partial<TData>) => string);
-  method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
-  headers?: Record<string, string> | ((context: TContext) => Record<string, string>);
-  body?: (context: TContext, data: Partial<TData>, args?: Record<string, unknown>) => unknown;
-  transform?: (response: unknown) => TResult;
 }
 
-/**
- * Configuration for computation tools
- */
-export interface ComputationConfig<TContext, TData, TResult> {
+export interface Tool<C = unknown, D = unknown> {
   id: string;
-  name?: string;
   description?: string;
-  inputs: (keyof TData)[];
-  compute: (
-    context: TContext,
-    inputs: Partial<TData>,
-    args?: Record<string, unknown>
-  ) => Promise<TResult> | TResult;
+  parameters?: StructuredSchema;
+  handler(args: Record<string, unknown>, ctx: ToolCtx<C, D>): ToolResult<D> | Promise<ToolResult<D>>;
+
+  /** Safe to run alongside other concurrency-safe tools in one round. */
+  isConcurrencySafe?(input: Record<string, unknown>): boolean;
+  /** Reads only; no side effects. */
+  isReadOnly?(input: Record<string, unknown>): boolean;
+  /** Irreversible; never run speculatively. */
+  isDestructive?(input: Record<string, unknown>): boolean;
+  /** Characters of the result kept before truncation. */
+  maxResultSizeChars?: number;
+  /** Check the model's arguments before the handler runs. */
+  validateInput?(
+    input: Record<string, unknown>,
+    ctx: ToolCtx<C, D>,
+  ): ToolValidationResult | Promise<ToolValidationResult>;
+  /** When denied, the handler is not invoked and the model is told why. */
+  checkPermissions?(
+    input: Record<string, unknown>,
+    ctx: ToolCtx<C, D>,
+  ): ToolPermissionResult | Promise<ToolPermissionResult>;
 }

package/src/utils/clock.ts

@@ -0,0 +1,70 @@
+/**
+ * Time you can hold still: a fake clock for `AgentOptions.clock` and an
+ * in-memory scheduler that fires `schedule[]` entries on demand. Tests and
+ * the playground use both; production hosts bring their own queue.
+ */
+
+import type { Clock, ScheduleEntry } from "../types/agent.js";
+import type { Duration } from "../types/flow.js";
+import { parseDuration } from "./duration.js";
+
+export interface FakeClock extends Clock {
+  now(): Date;
+  /** Move forward by a duration (`'24h'`) or a number of milliseconds. */
+  advance(by: Duration | number): Date;
+  set(iso: string): Date;
+}
+
+/** A clock that only moves when told to. Pass it as `clock` to the agent. */
+export function fakeClock(iso: string): FakeClock {
+  let at = parseIso(iso);
+  const clock = (): Date => new Date(at);
+  return Object.assign(clock, {
+    now: clock,
+    advance(by: Duration | number): Date {
+      at += typeof by === "number" ? by : parseDuration(by);
+      return clock();
+    },
+    set(next: string): Date {
+      at = parseIso(next);
+      return clock();
+    },
+  });
+}
+
+function parseIso(iso: string): number {
+  const ms = Date.parse(iso);
+  if (Number.isNaN(ms)) throw new Error(`fakeClock: "${iso}" is not a date.`);
+  return ms;
+}
+
+/**
+ * Holds `schedule[]` entries and hands back the ones that are due. A new
+ * entry with the same key replaces the old one; `replaces` removes that key.
+ */
+export class MemoryScheduler {
+  private readonly entries = new Map<string, ScheduleEntry>();
+
+  add(entry: ScheduleEntry): void {
+    if (entry.replaces) this.entries.delete(entry.replaces);
+    this.entries.delete(entry.key);
+    this.entries.set(entry.key, { ...entry, at: new Date(entry.at) });
+  }
+
+  remove(key: string): void {
+    this.entries.delete(key);
+  }
+
+  get size(): number {
+    return this.entries.size;
+  }
+
+  /** Removes and returns every entry whose `at` is not after `now`, earliest first. */
+  due(now: Date): ScheduleEntry[] {
+    const fired = [...this.entries.values()]
+      .filter((e) => e.at.getTime() <= now.getTime())
+      .sort((a, b) => a.at.getTime() - b.at.getTime());
+    for (const e of fired) this.entries.delete(e.key);
+    return fired;
+  }
+}

package/src/utils/duration.ts

@@ -0,0 +1,33 @@
+/**
+ * `Duration` strings: `'30s'`, `'5m'`, `'24h'`, `'3d'` → milliseconds.
+ */
+
+import { FlowConfigurationError } from "../types/errors.js";
+import type { Duration } from "../types/flow.js";
+
+const PATTERN = /^(\d+(?:\.\d+)?)(s|m|h|d)$/;
+
+const UNIT_MS: Record<string, number> = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 };
+
+/** `'30s'`, `'5m'`, `'24h'`, `'3d'`: a number followed by one unit. */
+export function isDuration(value: string): value is Duration {
+  return PATTERN.test(value);
+}
+
+/** Throws `FlowConfigurationError` unless `value` is a well-formed duration. */
+export function assertDuration(value: string, where = "duration"): asserts value is Duration {
+  if (!isDuration(value)) {
+    throw new FlowConfigurationError(
+      `[FlowConfigurationError] ${where} "${value}" is not a duration: expected a number followed by s, m, h or d. ` +
+        `Write it like "30s", "5m", "24h" or "3d".`,
+    );
+  }
+}
+
+/** `'5m'` → 300000. Throws on a malformed string. */
+export function parseDuration(value: string): number {
+  assertDuration(value);
+  const match = PATTERN.exec(value);
+  if (!match) throw new FlowConfigurationError(`[FlowConfigurationError] duration "${value}" did not parse.`);
+  return Math.round(Number(match[1]) * UNIT_MS[match[2]]);
+}

package/src/utils/history.ts

@@ -276,9 +276,10 @@ export function assistantMessage(
     id: string;
     name: string;
     arguments: Record<string, unknown>;
-  }>
+  }>,
+  thought?: { reasoning?: string; reasoningDetails?: unknown[] }
 ): HistoryItem {
-  return { role: "assistant", content, tool_calls: toolCalls };
+  return { role: "assistant", content, tool_calls: toolCalls, ...thought };
 }
 
 /**

package/src/utils/index.ts

@@ -2,75 +2,17 @@
  * Utility functions and helpers
  */
 
-// ID generation
-export {
-  generateFlowId,
-  generateStepId,
-  generateToolId,
-  generateInlineToolId,
-  generateSignalId,
-} from "./id.js";
-
-// Session management
-export {
-  createSession,
-  createSessionId,
-  boundConversationHistory,
-  DEFAULT_MAX_HISTORY_MESSAGES,
-  createPersistedState,
-  restoreSession,
-  enterFlow,
-  enterStep,
-  completeCurrentFlow,
-  isFlowCompletedThisSession,
-  mergeCollected,
-  dropUndeclaredFields,
-  sessionStepToData,
-  sessionDataToStep,
-} from "./session.js";
-
-// Template rendering
-export {
-  render,
-  renderMany,
-  formatKnowledgeBase,
-  createTemplateContext,
-} from "./template.js";
-
-// Cloning utilities
 export { cloneDeep } from "./clone.js";
-
-// Event utilities
-export { getLastMessageFromHistory } from "./event.js";
-
-// History utilities
+export { assertUsableCompletion, effectiveMessageText } from "./completion.js";
 export {
+  assistantMessage,
+  eventsToHistory,
+  eventToHistoryItem,
   historyItemToEvent,
   historyToEvents,
-  eventToHistoryItem,
-  eventsToHistory,
-  userMessage,
-  assistantMessage,
-  toolMessage,
   systemMessage,
+  toolMessage,
+  userMessage,
 } from "./history.js";
-
-// Logging
-export { LoggerLevel, logger } from "./logger.js";
-
-// Completion helpers
-export { effectiveMessageText, assertUsableCompletion } from "./completion.js";
-
-// Condition utilities
-export {
-  ConditionEvaluator,
-  createConditionEvaluator,
-  extractAIContextStrings,
-  hasProgrammaticConditions,
-} from "./condition.js";
-
-// JSON utilities
-export { parseJSONResponse, tryParseJSONResponse, extractEmbeddedJSONObject } from "./json.js";
-
-// Serialization utilities
-export { serializeToolResult, isToolResultLike, extractResultDirectives } from "./serialize.js";
+export { extractEmbeddedJSONObject, isJSONShaped, parseJSONResponse, tryParseJSONResponse } from "./json.js";
+export { logger, LoggerLevel } from "./logger.js";

package/src/utils/json.ts

@@ -196,3 +196,8 @@ function findObjectEnd(text: string, start: number): number {
 
   return -1;
 }
+
+/** A plain object: not null, not an array. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/utils/outcomes.ts

@@ -0,0 +1,56 @@
+/**
+ * One English sentence per outcome code.
+ *
+ * The framework copies the sentence onto every line it writes, so a log reads
+ * on its own. `satisfies` makes the compiler reject a new code without a
+ * sentence, so the two cannot drift. To show a line in another language, map
+ * `outcome.code` yourself and ignore `outcome.message`.
+ */
+
+import type { StepOutcomeCode } from "../types/session.js";
+
+export const OUTCOME_MESSAGES = {
+  "no-session": "a wake arrived for a session that does not exist",
+  "duplicate-input": "this input was already applied",
+  "stale-wake": "no run is waiting on this wake",
+  "silence-broken": "someone wrote after this silence wake was set",
+
+  "already-claimed": "this flow already ran here",
+  cooldown: "the flow's cooldown has not passed",
+  "hop-limit": "the chain reached the hop limit",
+  "already-running": "a run of this flow is already live here",
+  "flow-gone": "the flow is no longer registered on the agent",
+
+  "step-loop": "the run moved through 50 steps in one turn",
+  "step-gone": "the step is no longer in the flow",
+  "customer-replied": "the customer wrote before the wake fired",
+  "premise-changed": "the flow's while condition no longer holds",
+  silenced: "the host cannot speak right now",
+
+  "already-known": "every field this step collects is known",
+  "another-reply": "another run already answered this turn",
+  "already-sent": "this message was already sent once",
+  branch: "a branch of this step fired",
+  "max-asks": "the field was asked the most times allowed",
+  "inline-delay": "a short wait rides on the next message",
+  "awaiting-trigger": "the trigger's delay has not passed",
+  "awaiting-event": "the run is waiting for an event",
+  "event-arrived": "the event was reported",
+  "no-event": "the event did not arrive in time",
+  replied: "the customer replied while the run waited",
+  "no-reply": "the customer did not reply while the run waited",
+
+  "action-skipped": "the action decided not to run",
+  "action-failed": "the action failed",
+  "action-deferred": "the action asked to run again later",
+
+  "unknown-field": "no field by that name is declared on the agent",
+  "bad-value": "the value did not fit the field's type",
+  "not-in-enum": "the value is not one of the field's options",
+
+  "provider-quota": "the provider's usage limit is spent",
+  "provider-context": "the conversation outgrew the model's context window",
+  "provider-auth": "the provider rejected the credentials",
+  "provider-invalid": "the provider rejected the request",
+  "provider-unavailable": "the model call failed or came back empty",
+} as const satisfies Record<StepOutcomeCode, string>;

package/src/utils/phrases.ts

@@ -0,0 +1,40 @@
+/**
+ * Splitting an AI-judged phrase list into what counts and what rules it out.
+ *
+ * A trigger's phrases are alternatives: one match is enough. That makes the
+ * list useless for saying "but not this" — and "but not this" is what keeps a
+ * classifier honest. A customer answering "pode sim" to an offer of a meeting
+ * is agreeing to the meeting, not asking for a human, and without a way to say
+ * so every cheerful yes reads as a handoff request.
+ *
+ * So a phrase that opens with `!` is an exclusion: it does not make the trigger
+ * fire, it stops it. Exclusions win over matches, and the model is told both
+ * lists separately.
+ */
+
+export interface Phrases {
+  /** Any one of these makes it true. */
+  counts: string[];
+  /** Any one of these makes it false, whatever matched. */
+  excludes: string[];
+}
+
+/**
+ * Split a phrase list on the leading `!`. Blank entries and a bare `"!"` are
+ * dropped: they would render as an empty bullet and mean nothing to the model.
+ */
+export function splitPhrases(phrases: readonly string[]): Phrases {
+  const counts: string[] = [];
+  const excludes: string[] = [];
+  for (const phrase of phrases) {
+    const trimmed = phrase.trim();
+    if (!trimmed) continue;
+    if (trimmed.startsWith("!")) {
+      const body = trimmed.slice(1).trim();
+      if (body) excludes.push(body);
+      continue;
+    }
+    counts.push(trimmed);
+  }
+  return { counts, excludes };
+}