@falai/agent 3.4.5 → 4.0.0-alpha.1

package/src/core/DirectiveChainTracker.ts

@@ -1,144 +0,0 @@
-/**
- * Per-turn directive chain depth tracker.
- *
- * When directives chain (e.g., tool emits goTo → flow.onEnter emits goTo →
- * flow.onComplete emits complete.next → …), the chain can theoretically loop
- * forever. This tracker counts each directive application within a single turn
- * and throws `FlowConfigurationError` when the configured cap is exceeded.
- *
- * Chain breakers (`abort` mid-chain) stop counting and apply the
- * chain-terminating directive immediately.
- *
- * Validates: Requirements 22.1, 22.2, 22.3
- */
-
-import { FlowConfigurationError } from "./Step.js";
-import { logger } from "../utils/index.js";
-import type { Directive } from "../types/flow.js";
-
-/**
- * Entry in the directive chain log — records what was emitted and by whom.
- */
-export interface DirectiveChainEntry {
-    /** Human-readable description of the directive (e.g., "goTo:Booking", "complete", "abort:timeout") */
-    description: string;
-    /** Identifier of the emitter (e.g., "tool:lookup_order", "hook:onEnter", "pending") */
-    emitter: string;
-}
-
-/**
- * Tracks directive chain depth within a single turn.
- * Create one instance per turn; discard at turn end.
- */
-export class DirectiveChainTracker {
-    private chain: DirectiveChainEntry[] = [];
-    private readonly maxDepth: number;
-
-    constructor(maxDirectiveChain: number) {
-        this.maxDepth = maxDirectiveChain;
-    }
-
-    /**
-     * Record a directive application in the chain.
-     * Throws `FlowConfigurationError` if the chain exceeds `maxDirectiveChain`.
-     *
-     * @param directive - The directive being applied
-     * @param emitter - Identifier of the emitter (for diagnostics)
-     * @returns `true` if the directive is a chain breaker (abort) — caller should
-     *          apply it and stop the chain without further counting.
-     */
-    record(directive: Directive, emitter: string): boolean {
-        const description = describeDirective(directive);
-
-        // Check if this is a chain breaker (abort)
-        if (directive.abort !== undefined) {
-            this.chain.push({ description, emitter });
-            logger.debug(
-                `[DirectiveChainTracker] Chain breaker (abort) at depth ${this.chain.length}: ${description} from ${emitter}`
-            );
-            return true; // Chain breaker — apply and stop
-        }
-
-        this.chain.push({ description, emitter });
-
-        if (this.chain.length > this.maxDepth) {
-            const chainDescription = this.chain
-                .map((entry, i) => `  ${i + 1}. ${entry.description} (from: ${entry.emitter})`)
-                .join("\n");
-
-            throw new FlowConfigurationError(
-                `[FlowConfigurationError] Directive chain cycle detected: ` +
-                `chain depth (${this.chain.length}) exceeded maxDirectiveChain (${this.maxDepth}). ` +
-                `Review flow hooks and tool handlers for circular redirections.\n` +
-                `Chain (in emission order):\n${chainDescription}`
-            );
-        }
-
-        logger.debug(
-            `[DirectiveChainTracker] Chain depth ${this.chain.length}/${this.maxDepth}: ${description} from ${emitter}`
-        );
-
-        return false; // Not a chain breaker — continue normally
-    }
-
-    /** Current chain depth. */
-    get depth(): number {
-        return this.chain.length;
-    }
-
-    /** The full chain log (read-only). */
-    get entries(): ReadonlyArray<DirectiveChainEntry> {
-        return this.chain;
-    }
-
-    /** Reset the tracker (e.g., for testing or if the turn is restarted). */
-    reset(): void {
-        this.chain = [];
-    }
-}
-
-/**
- * Produce a human-readable one-line description of a directive for diagnostics.
- */
-function describeDirective(directive: Directive): string {
-    if (directive.abort !== undefined) {
-        const reason = typeof directive.abort === "string"
-            ? directive.abort
-            : typeof directive.abort === "object"
-                ? directive.abort.reason
-                : "";
-        return `abort${reason ? `:${reason}` : ""}`;
-    }
-    if (directive.goTo !== undefined) {
-        const target = typeof directive.goTo === "string"
-            ? directive.goTo
-            : typeof directive.goTo === "object"
-                ? directive.goTo.flow ?? "(no flow)"
-                : "";
-        return `goTo:${target}`;
-    }
-    if (directive.goToStep !== undefined) {
-        const target = typeof directive.goToStep === "string"
-            ? directive.goToStep
-            : typeof directive.goToStep === "object"
-                ? directive.goToStep.step
-                : "";
-        return `goToStep:${target}`;
-    }
-    if (directive.complete !== undefined) {
-        if (directive.complete === true) return "complete";
-        if (typeof directive.complete === "object" && directive.complete.next) {
-            return "complete(chained)";
-        }
-        return "complete";
-    }
-    if (directive.reset !== undefined) {
-        return "reset";
-    }
-    // State-only or reply-only directive
-    const parts: string[] = [];
-    if (directive.reply) parts.push("reply");
-    if (directive.dataUpdate) parts.push("dataUpdate");
-    if (directive.contextUpdate) parts.push("contextUpdate");
-    return parts.length > 0 ? parts.join("+") : "(empty)";
-}

package/src/core/Events.ts

@@ -1,164 +0,0 @@
-/**
- * Event utilities and helpers
- */
-
-import type {
-  Event,
-  EmittedEvent,
-  MessageEventData,
-  ToolEventData,
-  HistoryMessage,
-  MessageData,
-  HistoryItem,
-  History,
-} from "../types/index.js";
-import { EventKind, MessageRole } from "../types/index.js";
-
-/**
- * Convert a simple JSON history message to an internal Event
- */
-export function convertHistoryMessage<TData = unknown>(
-  message: HistoryMessage<TData>
-): Event<MessageEventData> {
-  return {
-    kind: EventKind.MESSAGE,
-    source: message.role,
-    data: {
-      participant: {
-        display_name: message.name || getDefaultName(message.role),
-      },
-      message: message.content,
-      session: message.session,
-    },
-    timestamp: message.timestamp || new Date().toISOString(),
-    id: message.metadata?.id as string,
-  };
-}
-
-/**
- * Get default participant name for a role
- */
-function getDefaultName(role: MessageRole): string {
-  switch (role) {
-    case MessageRole.USER:
-      return "User";
-    case MessageRole.ASSISTANT:
-      return "Assistant";
-    case MessageRole.SYSTEM:
-      return "System";
-    default:
-      return "Unknown";
-  }
-}
-
-/**
- * Convert an array of history messages to Events
- */
-export function convertHistoryToEvents<TData = unknown>(
-  history: HistoryMessage<TData>[]
-): Event[] {
-  return history.map(convertHistoryMessage);
-}
-
-/**
- * Adapt an event for inclusion in prompts
- * Transforms event data into a serializable format
- */
-export function adaptEvent(e: Event | EmittedEvent): string {
-  let data: unknown = e.data;
-
-  if (e.kind === EventKind.MESSAGE) {
-    const messageData = e.data as MessageEventData;
-
-    if (messageData.flagged) {
-      data = {
-        participant: messageData.participant.display_name,
-        message: "<N/A>",
-        censored: true,
-        reasons: messageData.tags,
-      };
-    } else {
-      data = {
-        participant: messageData.participant.display_name,
-        message: messageData.message,
-      };
-    }
-  }
-
-  if (e.kind === EventKind.TOOL) {
-    const toolData = e.data as ToolEventData;
-
-    data = {
-      tool_calls: toolData.tool_calls.map((tc) => ({
-        tool_id: tc.tool_id,
-        arguments: tc.arguments,
-        result: tc.result.data,
-      })),
-    };
-  }
-
-  const sourceMap: Record<MessageRole, string> = {
-    [MessageRole.USER]: "user",
-    [MessageRole.ASSISTANT]: "assistant",
-    [MessageRole.AGENT]: "agent",
-    [MessageRole.SYSTEM]: "system",
-  };
-
-  return JSON.stringify({
-    event_kind: e.kind,
-    event_source: sourceMap[e.source],
-    data,
-  });
-}
-
-/**
- * Convert MessageData to HistoryItem
- */
-export function convertMessageDataToHistoryItem(
-  message: MessageData
-): HistoryItem {
-  switch (message.role) {
-    case MessageRole.USER:
-      return {
-        role: "user",
-        content: message.content,
-      };
-    case MessageRole.ASSISTANT:
-      return {
-        role: "assistant",
-        content: message.content,
-        tool_calls: message.toolCalls?.map((tc, index) => ({
-          id: `call_${index}`, // Generate an ID since MessageData doesn't have tool call IDs
-          name: tc.toolName,
-          arguments: tc.arguments,
-        })),
-      };
-    case MessageRole.AGENT:
-      // Agent role typically represents tool execution results
-      // Since we don't have tool_call_id in MessageData, we'll use a placeholder
-      return {
-        role: "tool",
-        tool_call_id: "unknown", // MessageData doesn't store tool call IDs
-        name: "unknown_tool",
-        content: message.content,
-      };
-    case MessageRole.SYSTEM:
-      return {
-        role: "system",
-        content: message.content,
-      };
-    default:
-      // Fallback for unknown roles
-      return {
-        role: "system",
-        content: message.content,
-      };
-  }
-}
-
-/**
- * Convert an array of MessageData to History (HistoryItem[])
- */
-export function convertMessagesToHistory(messages: MessageData[]): History {
-  return messages.map(convertMessageDataToHistoryItem);
-}