@falai/agent 3.4.5 → 4.0.0-alpha.2

package/src/utils/condition.ts

@@ -1,296 +0,0 @@
-import type { TemplateContext, ConditionEvaluationResult } from "../types/template.js";
-import { createTemplateContext } from "./template.js";
-import { logger } from './logger.js'
-
-/**
- * Condition template — kept as a private type for internal use by the evaluator.
- * Removed from the public surface in v2.
- */
-type ConditionTemplate<TContext = unknown, TData = unknown> =
-  | string
-  | ((params: TemplateContext<TContext, TData>) => boolean | Promise<boolean>)
-  | ConditionTemplate<TContext, TData>[];
-
-export interface WhenConditionGroups {
-  positive: string[];
-  negative: string[];
-}
-
-function emptyWhenConditionGroups(): WhenConditionGroups {
-  return { positive: [], negative: [] };
-}
-
-function pushWhenCondition(groups: WhenConditionGroups, value: string): void {
-  const condition = value.trim();
-  if (!condition) {
-    return;
-  }
-
-  if (condition.startsWith("!")) {
-    const negative = condition.slice(1).trim();
-    if (negative) {
-      groups.negative.push(negative);
-    }
-    return;
-  }
-
-  groups.positive.push(condition);
-}
-
-/**
- * Evaluate code (`if`) predicates with AND semantics and short-circuit.
- *
- * Shared by branch and signal evaluation — both define `if` as one predicate
- * or an array of predicates over their respective contexts. A predicate that
- * throws is logged at ERROR (with `label` and index) and treated as false,
- * so a failing predicate only inhibits its own entry.
- */
-export async function evaluateIfPredicates<TCtx>(
-  predicates:
-    | ((ctx: TCtx) => boolean | Promise<boolean>)
-    | Array<(ctx: TCtx) => boolean | Promise<boolean>>,
-  ctx: TCtx,
-  label: string,
-): Promise<boolean> {
-  const predicateArray = Array.isArray(predicates) ? predicates : [predicates];
-
-  for (let i = 0; i < predicateArray.length; i++) {
-    try {
-      const result = await predicateArray[i](ctx);
-      if (!result) {
-        return false;
-      }
-    } catch (error) {
-      logger.error(
-        `[${label}] Predicate at index ${i} threw: ${error instanceof Error ? error.message : String(error)}`,
-      );
-      return false;
-    }
-  }
-
-  return true;
-}
-
-/**
- * Split AI-evaluated `when` strings into positive alternatives and negative
- * exclusions. Positive entries are OR alternatives. `!`-prefixed entries are
- * stripped and treated as OR exclusions, where any match inhibits the condition.
- */
-export function splitWhenConditions(
-  when: string | string[] | undefined | null
-): WhenConditionGroups {
-  const groups = emptyWhenConditionGroups();
-  if (when == null) {
-    return groups;
-  }
-
-  const entries: unknown[] = Array.isArray(when) ? when : [when];
-  for (const entry of entries) {
-    if (typeof entry === "string") {
-      pushWhenCondition(groups, entry);
-    }
-  }
-
-  return groups;
-}
-
-function splitConditionTemplate<TContext = unknown, TData = unknown>(
-  condition: ConditionTemplate<TContext, TData> | undefined | null
-): WhenConditionGroups {
-  const groups = emptyWhenConditionGroups();
-  if (condition == null) {
-    return groups;
-  }
-
-  if (Array.isArray(condition)) {
-    for (const subCondition of condition) {
-      const subGroups = splitConditionTemplate(subCondition);
-      groups.positive.push(...subGroups.positive);
-      groups.negative.push(...subGroups.negative);
-    }
-    return groups;
-  }
-
-  if (typeof condition === "string") {
-    pushWhenCondition(groups, condition);
-  }
-
-  return groups;
-}
-
-/**
- * Utility class for evaluating ConditionTemplate instances.
- * Handles mixed string/function conditions and separates programmatic
- * evaluation from AI context collection.
- */
-export class ConditionEvaluator<TContext = unknown, TData = unknown> {
-  constructor(private templateContext: TemplateContext<TContext, TData>) { }
-
-  /**
-   * Evaluates a condition template and returns both programmatic results
-   * and AI context strings.
-   * 
-   * @param condition The condition to evaluate
-   * @param logic Logic to apply for arrays ('AND' for when conditions, 'OR' for skipIf)
-   * @returns Evaluation result with programmatic result and AI context
-   */
-  async evaluateCondition(
-    condition: ConditionTemplate<TContext, TData>,
-    logic: 'AND' | 'OR' = 'AND'
-  ): Promise<ConditionEvaluationResult> {
-    const result: ConditionEvaluationResult = {
-      programmaticResult: logic === 'AND' ? true : false,
-      aiContextStrings: [],
-      aiExclusionStrings: [],
-      hasProgrammaticConditions: false,
-      evaluationDetails: []
-    };
-
-    if (!condition) {
-      return result;
-    }
-
-    // Handle array conditions
-    if (Array.isArray(condition)) {
-      return this.evaluateArrayCondition(condition, logic);
-    }
-
-    // Handle string conditions (AI context only)
-    if (typeof condition === 'string') {
-      const groups = splitWhenConditions(condition);
-      result.aiContextStrings.push(...groups.positive);
-      result.aiExclusionStrings?.push(...groups.negative);
-      result.evaluationDetails?.push({
-        condition: condition,
-        type: 'string'
-      });
-      // For string conditions, programmatic result depends on logic:
-      // AND logic: true (doesn't affect result)
-      // OR logic: false (doesn't trigger skip)
-      result.programmaticResult = logic === 'AND' ? true : false;
-      return result;
-    }
-
-    // Handle function conditions (programmatic evaluation)
-    if (typeof condition === 'function') {
-      result.hasProgrammaticConditions = true;
-      try {
-        const functionResult = await condition(this.templateContext);
-        result.programmaticResult = Boolean(functionResult);
-        result.evaluationDetails?.push({
-          condition: condition.toString(),
-          result: result.programmaticResult,
-          type: 'function'
-        });
-      } catch (error) {
-        // Log error and default to false for safety
-        logger.warn('Condition function evaluation failed:', error);
-        result.programmaticResult = false;
-        result.evaluationDetails?.push({
-          condition: condition.toString(),
-          result: false,
-          type: 'function'
-        });
-      }
-      return result;
-    }
-
-    // Fallback for unexpected types
-    logger.warn('Unexpected condition type:', typeof condition);
-    return result;
-  }
-
-  /**
-   * Evaluates an array of conditions with the specified logic.
-   */
-  private async evaluateArrayCondition(
-    conditions: ConditionTemplate<TContext, TData>[],
-    logic: 'AND' | 'OR'
-  ): Promise<ConditionEvaluationResult> {
-    const result: ConditionEvaluationResult = {
-      programmaticResult: logic === 'AND' ? true : false,
-      aiContextStrings: [],
-      aiExclusionStrings: [],
-      hasProgrammaticConditions: false,
-      evaluationDetails: [{
-        condition: `Array[${conditions.length}]`,
-        type: 'array'
-      }]
-    };
-
-    const functionResults: boolean[] = [];
-
-    for (const condition of conditions) {
-      const conditionResult = await this.evaluateCondition(condition, logic);
-
-      // Collect AI context strings
-      result.aiContextStrings.push(...conditionResult.aiContextStrings);
-      result.aiExclusionStrings?.push(...(conditionResult.aiExclusionStrings ?? []));
-
-      // Track if we have programmatic conditions
-      if (conditionResult.hasProgrammaticConditions) {
-        result.hasProgrammaticConditions = true;
-        functionResults.push(conditionResult.programmaticResult);
-      }
-
-      // Merge evaluation details
-      if (conditionResult.evaluationDetails) {
-        result.evaluationDetails?.push(...conditionResult.evaluationDetails);
-      }
-    }
-
-    // Apply logic to function results only
-    if (functionResults.length > 0) {
-      if (logic === 'AND') {
-        result.programmaticResult = functionResults.every(r => r);
-      } else { // OR
-        result.programmaticResult = functionResults.some(r => r);
-      }
-    } else {
-      // No programmatic conditions, result depends on logic:
-      // AND: true (no functions to fail)
-      // OR: false (no functions to succeed)
-      result.programmaticResult = logic === 'AND' ? true : false;
-    }
-
-    return result;
-  }
-}
-
-/**
- * Utility function to create a ConditionEvaluator instance.
- * Ensures the template context has helpers included.
- */
-export function createConditionEvaluator<TContext = unknown, TData = unknown>(
-  templateContext: Omit<Partial<TemplateContext<TContext, TData>>, 'helpers'>
-): ConditionEvaluator<TContext, TData> {
-  const contextWithHelpers = createTemplateContext(templateContext);
-  return new ConditionEvaluator(contextWithHelpers);
-}
-
-/**
- * Utility function to extract AI context strings from a condition without evaluation.
- * Useful for collecting context strings for prompt generation.
- */
-export function extractAIContextStrings<TContext = unknown, TData = unknown>(
-  condition: ConditionTemplate<TContext, TData>
-): string[] {
-  return splitConditionTemplate(condition).positive;
-}
-
-/**
- * Utility function to check if a condition has any programmatic components.
- */
-export function hasProgrammaticConditions<TContext = unknown, TData = unknown>(
-  condition: ConditionTemplate<TContext, TData>
-): boolean {
-  if (!condition) {
-    return false;
-  }
-
-  if (Array.isArray(condition)) {
-    return condition.some(subCondition => hasProgrammaticConditions(subCondition));
-  }
-
-  return typeof condition === 'function';
-}

package/src/utils/event.ts

@@ -1,16 +0,0 @@
-import { type Event, EventKind } from "../types/index.js";
-/**
- * Helper to extract last message from history
- */
-export function getLastMessageFromHistory(history: Event[]): string {
-  for (let i = history.length - 1; i >= 0; i--) {
-    const event = history[i];
-    if (event.kind === EventKind.MESSAGE) {
-      if (!event.data || !("message" in event.data)) {
-        continue;
-      }
-      return event.data.message;
-    }
-  }
-  return "";
-}

package/src/utils/id.ts

@@ -1,91 +0,0 @@
-/**
- * ID generation utilities
- * Provides deterministic ID generation to ensure consistency across server restarts
- */
-
-/**
- * Generate a deterministic ID from a string by creating a simple hash
- * This ensures the same input always produces the same ID
- */
-function simpleHash(str: string): string {
-  let hash = 0;
-  for (let i = 0; i < str.length; i++) {
-    const char = str.charCodeAt(i);
-    hash = (hash << 5) - hash + char;
-    hash = hash & hash; // Convert to 32-bit integer
-  }
-  return Math.abs(hash).toString(36);
-}
-
-/**
- * Sanitize a string for use in an ID
- */
-function sanitize(str: string): string {
-  return str.toLowerCase().replace(/[^a-z0-9]+/g, "_");
-}
-
-/**
- * Generate a deterministic flow ID
- * Format: flow_{sanitized_title}_{hash}
- */
-export function generateFlowId(title: string): string {
-  const sanitized = sanitize(title);
-  const hash = simpleHash(title);
-  return `flow_${sanitized}_${hash}`;
-}
-
-/**
- * Generate a deterministic step ID
- * Format: step_{sanitized_description}_{hash} or step_{flowId}_{index}
- */
-export function generateStepId(
-  flowId: string,
-  description?: string,
-  index?: number
-): string {
-  if (description) {
-    const sanitized = sanitize(description);
-    const hash = simpleHash(`${flowId}_${description}`);
-    return `step_${sanitized}_${hash}`;
-  }
-  // Fallback for steps without descriptions
-  const suffix = index !== undefined ? index : simpleHash(flowId);
-  return `step_${flowId}_${suffix}`;
-}
-
-/**
- * Generate a deterministic tool ID
- * Format: tool_{sanitized_name}_{hash}
- */
-export function generateToolId(name: string): string {
-  const sanitized = sanitize(name);
-  const hash = simpleHash(name);
-  return `tool_${sanitized}_${hash}`;
-}
-
-/**
- * Generate a deterministic tool ID for inline tool handlers
- * Format: tool_inline_{stepId}_{hash}
- */
-export function generateInlineToolId(stepId: string): string {
-  const hash = simpleHash(`${stepId}_inline_tool`);
-  return `tool_inline_${stepId}_${hash}`;
-}
-
-/**
- * Generate a deterministic signal ID.
- * Format: signal_{sanitized}_{hash}
- *
- * Uses a combination of the signal's title/description/index to produce
- * a stable id that is deterministic within a session (same inputs → same id).
- */
-export function generateSignalId(
-  title?: string,
-  description?: string,
-  index?: number
-): string {
-  const seed = title || description || `signal_${index ?? 0}`;
-  const sanitized = sanitize(seed);
-  const hash = simpleHash(`signal_${seed}_${index ?? 0}`);
-  return `signal_${sanitized}_${hash}`;
-}

package/src/utils/serialize.ts

@@ -1,86 +0,0 @@
-/**
- * Serialization utilities for tool results and other data
- */
-
-import type { Directive } from "../types/flow.js";
-import type { ToolResult } from "../types/tool.js";
-
-/**
- * Decide whether a tool handler's return value is a ToolResult-shaped object.
- * Only SEMANTIC markers identify one — bare `{data}` / `{error}` shapes are
- * indistinguishable from ordinary business payloads (e.g. upstream API
- * envelopes) and must be wrapped as raw results instead. Shared by the
- * sequential (ToolManager) and concurrent (StreamingToolExecutor) paths so the
- * definition of "is a ToolResult" can't drift between them.
- */
-export function isToolResultLike(result: unknown): result is ToolResult {
-  return (
-    result !== null &&
-    typeof result === "object" &&
-    (("success" in result &&
-      typeof (result as Record<string, unknown>).success === "boolean") ||
-      "directive" in result ||
-      "directives" in result ||
-      "dataUpdate" in result ||
-      "contextUpdate" in result)
-  );
-}
-
-/**
- * Collect a ToolResult's directives — `{directive}` (singular shorthand) and
- * `{directives}` both count. Singular merges FIRST so plural entries win reply
- * ties (last-wins merge), identical on both executor paths.
- */
-export function extractResultDirectives<TContext = unknown, TData = unknown>(
-  result: ToolResult<unknown, TContext, TData>
-): Directive<TContext, TData>[] {
-  const directives: Directive<TContext, TData>[] = [];
-  if (result.directive) directives.push(result.directive);
-  if (Array.isArray(result.directives)) directives.push(...result.directives);
-  return directives;
-}
-
-/**
- * Serialize a tool execution result into a string suitable for conversation history.
- *
- * Priority:
- *   1. Failed result → error message
- *   2. String data   → returned as-is
- *   3. Object data   → JSON.stringify (with circular-reference safety)
- *   4. Primitive data → String()
- *   5. No data       → "Tool executed successfully"
- */
-export function serializeToolResult(result: {
-  success: boolean;
-  data?: unknown;
-  error?: string;
-}): string {
-  if (!result.success) {
-    return `Tool execution failed: ${result.error || "Unknown error"}`;
-  }
-
-  if (result.data === undefined || result.data === null) {
-    return "Tool executed successfully";
-  }
-
-  if (typeof result.data === "string") {
-    return result.data;
-  }
-
-  // Primitives (number, boolean) are safe to stringify directly
-  if (typeof result.data !== "object") {
-    return JSON.stringify(result.data);
-  }
-
-  // Objects / arrays — guard against circular references
-  try {
-    return JSON.stringify(result.data);
-  } catch {
-    // Circular or otherwise un-serializable object: extract what we can
-    const keys = Object.keys(result.data as Record<string, unknown>);
-    if (keys.length > 0) {
-      return `Tool returned object with keys: ${keys.join(", ")}`;
-    }
-    return "Tool executed successfully (result could not be serialized)";
-  }
-}