@falai/agent 3.4.5 → 4.0.0-alpha.10

package/examples/06-flow-control.ts

@@ -1,103 +0,0 @@
-/**
- * Programmatic flow control via Agent.dispatch and Directive shapes.
- * Teaches: dispatch from outside a turn, complete with next, abort, reply.
- * Read after: docs/guides/flow-control.md
- */
-
-import { createAgent, GeminiProvider, type Directive, type History } from "@falai/agent";
-
-// ─── Schema ──────────────────────────────────────────────────────────────────
-
-interface AppData {
-    item: string;
-    confirmed: boolean;
-}
-
-// ─── Agent setup ─────────────────────────────────────────────────────────────
-
-const agent = createAgent<{}, AppData>({
-    name: "FlowControlDemo",
-    provider: new GeminiProvider({
-        apiKey: process.env.GEMINI_API_KEY!,
-        model: "gemini-3.5-flash-lite",
-    }),
-    schema: {
-        type: "object",
-        properties: {
-            item: { type: "string" },
-            confirmed: { type: "boolean" },
-        },
-    },
-    flows: [
-        {
-            title: "Select Item",
-            steps: [
-                {
-                    id: "ask_item",
-                    prompt: "What item would you like?",
-                    collect: ["item"],
-                },
-                {
-                    id: "confirm",
-                    prompt: "You chose {{data.item}}. Confirm?",
-                    collect: ["confirmed"],
-                    requires: ["item"],
-                    // When the user confirms, complete with a chained directive
-                    // that moves to the "Checkout" flow.
-                    hooks: {
-                        finalize: (_context, data) => {
-                            if (data?.confirmed) {
-                                const d: Directive<{}, AppData> = {
-                                    complete: { next: { goTo: "Checkout" }, reason: "User confirmed" },
-                                };
-                                return d;
-                            }
-                            // Not confirmed — abort with a reason
-                            return { abort: "User declined the item" };
-                        },
-                    },
-                },
-            ],
-        },
-        {
-            title: "Checkout",
-            steps: [
-                {
-                    id: "receipt",
-                    // reply renders a verbatim message without an LLM call
-                    reply: "Your order for {{data.item}} is confirmed. Thank you!",
-                },
-            ],
-        },
-    ],
-});
-
-// ─── External dispatch ───────────────────────────────────────────────────────
-// Agent.dispatch queues a directive on a session OUTSIDE a respond() turn.
-// The directive takes effect on the next respond() call.
-
-async function externalRedirect() {
-    const history: History = [{ role: "user", content: "hello" }];
-
-    // First turn — enters "Select Item" normally
-    const res = await agent.respond({ history });
-    const session = res.session!;
-
-    // An external system decides to force-redirect to Checkout
-    const updated = await agent.dispatch({ goTo: "Checkout" }, session);
-
-    // Next turn picks up the pending directive
-    const next = await agent.respond({
-        history: [
-            ...history,
-            { role: "assistant", content: res.message },
-            { role: "user", content: "actually, rush my order" },
-        ],
-        session: updated,
-    });
-
-    console.log(next.message);
-    // → "Your order for ... is confirmed. Thank you!"
-}
-
-externalRedirect().catch(console.error);

package/examples/08-persistence.ts

@@ -1,98 +0,0 @@
-/** @intent Session persistence with MemoryAdapter: implicit default, explicit wiring, and sessionId for cross-turn continuity.
- *  @teaches MemoryAdapter, PersistenceConfig, sessionId, session resumption
- *  @readAfter docs/guides/persistence.md */
-import { createAgent, GeminiProvider, MemoryAdapter } from "../src/index.js";
-
-if (!process.env.GEMINI_API_KEY) throw new Error("Set GEMINI_API_KEY");
-
-const provider = new GeminiProvider({
-    apiKey: process.env.GEMINI_API_KEY,
-    model: "gemini-3.5-flash-lite",
-});
-
-const schema = {
-    type: "object" as const,
-    properties: {
-        city: { type: "string" },
-        checkIn: { type: "string" },
-        checkOut: { type: "string" },
-    },
-};
-
-const flows = [{
-    title: "Book Hotel",
-    requiredFields: ["city", "checkIn", "checkOut"],
-    steps: [
-        { id: "ask_city", prompt: "Which city are you visiting?", collect: ["city"] },
-        { id: "ask_dates", prompt: "What are your check-in and check-out dates?", collect: ["checkIn", "checkOut"] },
-    ],
-}];
-
-// --- 1. Implicit MemoryAdapter (default when no persistence is specified) ---
-// When you omit `persistence`, the agent uses an internal MemoryAdapter automatically.
-// Great for prototyping — zero config, but data is lost when the process exits.
-
-const simpleAgent = createAgent({
-    name: "BookingBot",
-    provider,
-    schema,
-    flows,
-});
-
-const res1 = await simpleAgent.respond({
-    history: [{ role: "user", content: "I'd like to book a hotel in Tokyo" }],
-});
-console.log("[Implicit adapter]", res1.message);
-
-// --- 2. Explicit MemoryAdapter with userId ---
-// Wire a MemoryAdapter explicitly to inspect stored sessions during development.
-
-const adapter = new MemoryAdapter();
-
-const agent = createAgent({
-    name: "BookingBot",
-    provider,
-    schema,
-    flows,
-    persistence: {
-        adapter,
-        userId: "user_42",
-    },
-});
-
-// --- 3. sessionId for cross-turn continuity ---
-// Pass `sessionId` at construct time so the same conversation resumes across calls.
-// In production, swap MemoryAdapter for PrismaAdapter (or Redis, Postgres, etc.)
-// and the session survives process restarts.
-
-const persistentAgent = createAgent({
-    name: "BookingBot",
-    provider,
-    schema,
-    flows,
-    persistence: {
-        adapter,        // swap to: new PrismaAdapter({ prisma }) for production
-        userId: "user_42",
-    },
-    sessionId: "user_42:thread_001",
-});
-
-// Turn 1 — agent collects city
-const turn1 = await persistentAgent.respond({
-    history: [{ role: "user", content: "I want to stay in Paris" }],
-});
-console.log("[Turn 1]", turn1.message);
-
-// Turn 2 — same sessionId, conversation continues where it left off
-const turn2 = await persistentAgent.respond({
-    history: [
-        { role: "user", content: "I want to stay in Paris" },
-        { role: "assistant", content: turn1.message },
-        { role: "user", content: "March 10 to March 14" },
-    ],
-});
-console.log("[Turn 2]", turn2.message);
-
-// Inspect stored data (MemoryAdapter-only convenience method)
-const snapshot = adapter.getSnapshot();
-console.log("[Sessions]", snapshot.sessions.length);

package/examples/09-signals.ts

@@ -1,144 +0,0 @@
-/**
- * Signals — pre-phase escalation with halt + replyWith, post-phase entity capture with extract.
- * Teaches: Signal, SignalContext, SignalDirective, behavior: 'cooldown', extract schema.
- * Read next: docs/reference/signals.md
- */
-
-import {
-    createAgent,
-    GeminiProvider,
-    createSession,
-    type Signal,
-    type SignalContext,
-    type SignalDirective,
-    type SignalFiring,
-} from "@falai/agent";
-
-// ─── Types ───────────────────────────────────────────────────────────────────
-
-interface AppContext {
-    supportTier: "free" | "premium";
-}
-
-interface AppData {
-    topic: string;
-    sentiment: string;
-    contactName: string;
-    contactEmail: string;
-}
-
-// ─── Signal 1: Pre-phase escalation with cooldown ────────────────────────────
-// Detects angry messages BEFORE the LLM responds. Halts normal flow and
-// replies with an escalation notice. Cooldown prevents re-triggering for 60s.
-
-const escalationSignal: Signal<AppContext, AppData> = {
-    id: "escalation",
-    title: "Anger Escalation",
-    description: "Detects user frustration and halts to escalate.",
-    phase: "pre",
-
-    when: "The user is expressing strong frustration, anger, or threats to leave",
-
-    behavior: "cooldown",
-    cooldownMs: 60_000,
-
-    handler(ctx: SignalContext<AppContext, AppData>): SignalDirective<AppContext, AppData> {
-        // halt: stops the LLM call from running
-        // replyWith: sends a canned response instead
-        return {
-            halt: true,
-            replyWith: "I can see this is frustrating — let me connect you with a specialist right away.",
-            dataUpdate: { sentiment: "escalated" },
-            stopOtherSignals: true,
-        };
-    },
-};
-
-// ─── Signal 2: Post-phase entity capture with extract ────────────────────────
-// After the LLM responds, extracts contact info the user may have provided.
-// Uses `extract` schema so the classifier pulls structured data alongside
-// the match decision.
-
-interface ContactExtract {
-    name: string | null;
-    email: string | null;
-}
-
-const contactCaptureSignal: Signal<AppContext, AppData, ContactExtract> = {
-    id: "contact_capture",
-    title: "Contact Info Capture",
-    description: "Extracts name and email from the conversation when mentioned.",
-    phase: "post",
-
-    when: "The user has provided their name or email address in this message",
-
-    extract: {
-        type: "object",
-        properties: {
-            name: { type: ["string", "null"], description: "The user's full name, or null if not provided" },
-            email: { type: ["string", "null"], description: "The user's email address, or null if not provided" },
-        },
-        required: ["name", "email"],
-    } as const,
-
-    async handler(ctx: SignalContext<AppContext, AppData, ContactExtract>): Promise<void> {
-        const { extracted } = ctx;
-
-        // Only update fields that were actually extracted
-        if (extracted.name) {
-            await ctx.updateData({ contactName: extracted.name });
-        }
-        if (extracted.email) {
-            await ctx.updateData({ contactEmail: extracted.email });
-        }
-    },
-};
-
-// ─── Agent ───────────────────────────────────────────────────────────────────
-
-const agent = createAgent<AppContext, AppData>({
-    name: "SupportAgent",
-    provider: new GeminiProvider({
-        apiKey: process.env.GEMINI_API_KEY!,
-        model: "gemini-3.5-flash-lite",
-    }),
-    context: { supportTier: "free" },
-    schema: {
-        type: "object",
-        properties: {
-            topic: { type: "string" },
-            sentiment: { type: "string" },
-            contactName: { type: "string" },
-            contactEmail: { type: "string" },
-        },
-    },
-    signals: [escalationSignal, contactCaptureSignal],
-    flows: [
-        {
-            title: "Support",
-            when: "User needs help with a product issue",
-            steps: [
-                { id: "triage", prompt: "Identify the user's issue and ask clarifying questions.", collect: ["topic"] },
-                { id: "resolve", prompt: "Provide a solution based on the identified topic." },
-            ],
-        },
-    ],
-});
-
-// ─── Run ─────────────────────────────────────────────────────────────────────
-
-const session = createSession<AppData>("signals-demo");
-
-const response = await agent.respond({
-    history: [{ role: "user", content: "This is ridiculous! I've been waiting 3 days. My name is Alex and my email is alex@example.com." }],
-    session,
-});
-
-console.log(response.message);
-
-// Observability: log which signals fired this turn
-if (response.triggeredSignals?.length) {
-    for (const firing of response.triggeredSignals as SignalFiring[]) {
-        console.log(`[signal] ${firing.id} (${firing.phase}) — ${firing.reason ?? "no reason"}`);
-    }
-}

package/src/adapters/MemoryAdapter.ts

@@ -1,281 +0,0 @@
-/**
- * Memory adapter for persistence
- * In-memory storage for testing and development (no database required)
- */
-
-import type {
-  CollectedStateData,
-  MessageData,
-  MessageRepository,
-  PersistenceAdapter,
-  SessionData,
-  SessionRepository,
-  SessionStatus,
-  SessionUpdateOptions,
-  CreateSessionData,
-} from "../types/index.js";
-import { SessionConflictError } from "../types/errors.js";
-import { cloneDeep } from "../utils/clone.js";
-import { createSessionId } from "../utils/index.js";
-
-/**
- * Memory Adapter - Provider-style API for in-memory persistence
- *
- * Perfect for:
- * - Testing
- * - Development
- * - Prototyping
- * - No database setup required
- *
- * @example
- * ```typescript
- * import { Agent, MemoryAdapter } from '@falai/agent';
- *
- * const agent = new Agent({
- *   name: "My Agent",
- *   provider: provider,
- *   persistence: {
- *     adapter: new MemoryAdapter(),
- *     userId: "user_123",
- *   },
- * });
- * ```
- */
-export class MemoryAdapter<TData = Record<string, unknown>> implements PersistenceAdapter<TData> {
-  public readonly sessionRepository: SessionRepository<TData>;
-  public readonly messageRepository: MessageRepository;
-  private sessions: Map<string, SessionData<TData>>;
-  private messages: Map<string, MessageData>;
-
-  constructor() {
-    this.sessions = new Map();
-    this.messages = new Map();
-
-    this.sessionRepository = new MemorySessionRepository<TData>(this.sessions);
-    this.messageRepository = new MemoryMessageRepository(this.messages);
-  }
-
-  /**
-   * Clear all data (useful for testing)
-   */
-  clear(): void {
-    this.sessions.clear();
-    this.messages.clear();
-  }
-
-  /**
-   * Get data snapshot (useful for debugging)
-   */
-  getSnapshot(): {
-    sessions: SessionData<TData>[];
-    messages: MessageData[];
-  } {
-    return {
-      sessions: Array.from(this.sessions.values()),
-      messages: Array.from(this.messages.values()),
-    };
-  }
-}
-
-/**
- * Memory Session Repository
- */
-class MemorySessionRepository<TData = Record<string, unknown>>
-  implements SessionRepository<TData> {
-  constructor(private sessions: Map<string, SessionData<TData>>) { }
-
-  create(data: CreateSessionData<TData>): Promise<SessionData<TData>> {
-    const id =
-      data.id || createSessionId();
-    const now = new Date();
-
-    const session: SessionData<TData> = {
-      ...data,
-      id,
-      status: data.status || "active",
-      messageCount: data.messageCount || 0,
-      version: data.version ?? 1,
-      createdAt: now,
-      updatedAt: now,
-    };
-
-    this.sessions.set(id, cloneDeep(session));
-    return Promise.resolve(cloneDeep(session));
-  }
-
-  findById(id: string): Promise<SessionData<TData> | null> {
-    const session = this.sessions.get(id);
-    return Promise.resolve(session ? cloneDeep(session) : null);
-  }
-
-  async findActiveByUserId(userId: string): Promise<SessionData<TData> | null> {
-    const sessions = Array.from(this.sessions.values())
-      .filter((s) => s.userId === userId && s.status === "active")
-      .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
-
-    return Promise.resolve(sessions[0] || null);
-  }
-
-  async findByUserId(
-    userId: string,
-    limit = 100
-  ): Promise<SessionData<TData>[]> {
-    const sessions = Array.from(this.sessions.values())
-      .filter((s) => s.userId === userId)
-      .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
-      .slice(0, limit);
-    return Promise.resolve(sessions);
-  }
-
-  async update(
-    id: string,
-    data: Partial<Omit<SessionData<TData>, "id" | "createdAt">>,
-    options?: SessionUpdateOptions
-  ): Promise<SessionData<TData> | null> {
-    const existing = this.sessions.get(id);
-    if (!existing) return null;
-
-    // Compare-and-swap: rows without a stored version (pre-2.4) are accepted
-    if (
-      options?.expectedVersion !== undefined &&
-      existing.version !== undefined &&
-      existing.version !== options.expectedVersion
-    ) {
-      throw new SessionConflictError(id, options.expectedVersion, existing.version);
-    }
-
-    const updated: SessionData<TData> = {
-      ...existing,
-      ...data,
-      version: (existing.version ?? options?.expectedVersion ?? 0) + 1,
-      updatedAt: new Date(),
-    };
-
-    this.sessions.set(id, cloneDeep(updated));
-    return Promise.resolve(cloneDeep(updated));
-  }
-
-  // Derived updaters route through update() so every state write shares one
-  // semantic across adapters: version bump + updatedAt refresh (the SQL
-  // adapters delegate to their update() the same way).
-
-  async updateStatus(
-    id: string,
-    status: SessionStatus,
-    completedAt?: Date
-  ): Promise<SessionData<TData> | null> {
-    // An undefined completedAt must be omitted, not spread — update() writes
-    // whatever keys it receives, and SQL skips undefined columns.
-    return this.update(id, completedAt ? { status, completedAt } : { status });
-  }
-
-  async updateCollectedData(
-    id: string,
-    collectedData: CollectedStateData<TData>
-  ): Promise<SessionData<TData> | null> {
-    return this.update(id, { collectedData });
-  }
-
-  async updateFlowStep(
-    id: string,
-    flow?: string,
-    step?: string
-  ): Promise<SessionData<TData> | null> {
-    // Mirror SQL's conditional column assembly: only defined values are written.
-    return this.update(id, {
-      ...(flow !== undefined && { currentFlow: flow }),
-      ...(step !== undefined && { currentStep: step }),
-    });
-  }
-
-  async incrementMessageCount(id: string): Promise<SessionData<TData> | null> {
-    // Bookkeeping write, deliberately NOT routed through update(): count bumps
-    // run alongside saveSessionState's version CAS every turn, so they must not
-    // move `version` (matches the SQL adapters' dedicated statement).
-    const session = this.sessions.get(id);
-    if (!session) return Promise.resolve(null);
-    const updated: SessionData<TData> = {
-      ...session,
-      messageCount: (session.messageCount || 0) + 1,
-      lastMessageAt: new Date(),
-      updatedAt: new Date(),
-    };
-    this.sessions.set(id, cloneDeep(updated));
-    return Promise.resolve(cloneDeep(updated));
-  }
-
-  async delete(id: string): Promise<boolean> {
-    const result = this.sessions.delete(id);
-    return Promise.resolve(result);
-  }
-}
-
-/**
- * Memory Message Repository
- */
-class MemoryMessageRepository implements MessageRepository {
-  constructor(private messages: Map<string, MessageData>) { }
-
-  async create(
-    data: Omit<MessageData, "id" | "createdAt">
-  ): Promise<MessageData> {
-    const id = `msg_${Date.now()}_${Math.random().toString(36).slice(2)}`;
-    const message: MessageData = {
-      ...data,
-      id,
-      createdAt: new Date(),
-    };
-
-    // Clone on store and on return so callers can't mutate the stored row —
-    // same isolation the session repository provides.
-    this.messages.set(id, cloneDeep(message));
-    return Promise.resolve(cloneDeep(message));
-  }
-
-  async findById(id: string): Promise<MessageData | null> {
-    const message = this.messages.get(id) || null;
-    return Promise.resolve(message);
-  }
-
-  async findBySessionId(
-    sessionId: string,
-    limit = 1000
-  ): Promise<MessageData[]> {
-    const messages = Array.from(this.messages.values())
-      .filter((m) => m.sessionId === sessionId)
-      .sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime())
-      .slice(0, limit);
-    return Promise.resolve(messages);
-  }
-
-  async findByUserId(userId: string, limit = 100): Promise<MessageData[]> {
-    const messages = Array.from(this.messages.values())
-      .filter((m) => m.userId === userId)
-      .sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime())
-      .slice(0, limit);
-    return Promise.resolve(messages);
-  }
-
-  async delete(id: string): Promise<boolean> {
-    const result = this.messages.delete(id);
-    return Promise.resolve(result);
-  }
-
-  async deleteBySessionId(sessionId: string): Promise<number> {
-    const toDelete = Array.from(this.messages.values()).filter(
-      (m) => m.sessionId === sessionId
-    );
-
-    toDelete.forEach((m) => this.messages.delete(m.id));
-    return Promise.resolve(toDelete.length);
-  }
-
-  async deleteByUserId(userId: string): Promise<number> {
-    const toDelete = Array.from(this.messages.values()).filter(
-      (m) => m.userId === userId
-    );
-
-    toDelete.forEach((m) => this.messages.delete(m.id));
-    return Promise.resolve(toDelete.length);
-  }
-}