@falai/agent 3.4.5 → 4.0.0-alpha.10

package/src/utils/template.ts

@@ -1,442 +1,87 @@
-import type { Template, TemplateContext } from "../types/index.js";
-import type { Event, MessageEventData } from "../types/history.js";
-import { MessageRole, EventKind } from "../types/history.js";
-
 /**
- * Renders a template, which can be a string or a function, using the provided context.
- * This function is asynchronous to support template functions that perform async operations.
- *
- * @param template - The template to render (string or function).
- * @param params - The context object to pass to the template function.
- * @returns A promise that resolves to the rendered string.
+ * `{{path}}` substitution for prompts, `say` texts and action parameters.
  *
- * @example
- * ```typescript
- * // With a string template
- * const result1 = await render("Hello {{name}}", { context: { name: "Alice" } });
- * // Result: "Hello Alice"
+ * The scope has three roots: `data` (collected fields), `context` (the host's
+ * per-turn context) and `input` (the run's trigger payload). A path that
+ * resolves to nothing keeps its placeholder, so a typo stays visible instead
+ * of vanishing into an empty string.
  *
- * // With a function template
- * const fnTemplate = ({ context }) => `Hello ${context.name}`;
- * const result2 = await render(fnTemplate, { context: { name: "Bob" } });
- * // Result: "Hello Bob"
- * ```
+ * A path the host answered with nothing is a different case: it knows the
+ * field and knows it is blank. Then the placeholder goes and `tidy` closes the
+ * gap it left, so "Ola {{context.lead.name}}, tudo bem?" sends "Ola, tudo bem?"
+ * and never "Ola , tudo bem?". Two things count as blank: an empty string, and
+ * a path that walks THROUGH a null — `context.lead` being `null` means there
+ * is no lead, so "the lead's name" is blank, not mistyped. A null at the end of
+ * a path is still unknown: a field that collected nothing keeps its braces.
  */
-export async function render<TContext = unknown, TData = unknown>(
-  template: Template<TContext, TData> | undefined,
-  params: TemplateContext<TContext, TData>
-): Promise<string> {
-  if (typeof template === "function") {
-    // Execute the function and await the result if it's a promise
-    const result = await Promise.resolve(template(params));
-    return result;
-  }
 
-  if (typeof template === "string") {
-    // Fallback to the old renderTemplate logic for string-based templates
-    return renderTemplate(template, params.context as Record<string, unknown>);
-  }
-
-  // Return empty string if template is undefined or not a supported type
-  return "";
+export interface TemplateScope {
+  data?: unknown;
+  context?: unknown;
+  input?: unknown;
 }
 
-/**
- * Renders an array of templates.
- *
- * @param templates - An array of templates to render.
- * @param params - The context object.
- * @returns A promise that resolves to an array of rendered strings.
- */
-export async function renderMany<TContext = unknown, TData = unknown>(
-  templates: Template<TContext, TData>[] | undefined,
-  params: TemplateContext<TContext, TData>
-): Promise<string[]> {
-  if (!templates) {
-    return [];
-  }
-  return Promise.all(templates.map((t) => render(t, params)));
-}
+const PLACEHOLDER = /\{\{\s*([^}\s]+)\s*\}\}/g;
 
-/**
- * Renders template variables in a string using the provided context.
- * Supports {{variable}} and {{object.property}} syntax for property access.
- *
- * @param template - The template string containing {{variable}} placeholders
- * @param context - The context object to pull values from
- * @returns The rendered string with variables replaced
- *
- * @example
- * ```typescript
- * const template = "Hello {{user.name}}, welcome to {{company.name}}!";
- * const context = {
- *   user: { name: "Alice", age: 30 },
- *   company: { name: "Acme Corp", location: "NYC" }
- * };
- * const result = renderTemplate(template, context);
- * // Result: "Hello Alice, welcome to Acme Corp!"
- *
- * // Array handling
- * const template2 = "Items: {{items}}";
- * const context2 = { items: ["apple", "banana", "cherry"] };
- * const result2 = renderTemplate(template2, context2);
- * // Result: "Items: apple, banana, cherry"
- * ```
- */
-export function renderTemplate(
-  template: string,
-  context: Record<string, unknown> | undefined
-): string {
-  if (!template || !context) {
-    return template;
-  }
+/** The path ran into a `null` on its way down: the container the host named is absent. */
+const ABSENT = Symbol("absent");
 
-  return template.replace(
-    /\{\{([^}]+)\}\}/g,
-    (match: string, path: string): string => {
-      const value = getValueByPath(context, path.trim());
-      if (value === undefined || value === null) {
-        return match; // Keep the original placeholder if value not found
-      }
-      return valueToString(value);
+export function render(template: string, scope: TemplateScope): string {
+  let emptied = false;
+  const out = template.replace(PLACEHOLDER, (match, path: string) => {
+    const value = lookup(scope, path.split("."));
+    if (value === ABSENT) {
+      emptied = true;
+      return "";
     }
-  );
+    if (value === undefined || value === null) return match;
+    const text = stringify(value);
+    if (text === "") emptied = true;
+    return text;
+  });
+  return emptied ? tidy(out) : out;
 }
 
 /**
- * Gets a value from an object using dot notation path.
- * Supports nested property access like "user.name" or "user.address.city".
+ * Close the hole an empty value leaves: a doubled space, a space before
+ * punctuation, a space at the end of a line.
  *
- * @param obj - The object to search in
- * @param path - The dot-separated path to the property
- * @returns The value at the path, or undefined if not found
+ * Deliberately narrow. It only runs on a string where something substituted to
+ * "", and it only collapses a run of spaces that follows a visible character,
+ * so indentation in a markdown list survives.
  */
-function getValueByPath(obj: Record<string, unknown>, path: string): unknown {
-  const keys = path.split(".");
-  let current: unknown = obj;
-
-  for (const key of keys) {
-    if (
-      current === null ||
-      current === undefined ||
-      typeof current !== "object"
-    ) {
-      return undefined;
-    }
-    current = (current as Record<string, unknown>)[key];
-  }
-
-  return current;
+function tidy(text: string): string {
+  return text
+    .replace(/(?<=\S)[ \t]{2,}/g, " ")
+    .replace(/ +([,.;:!?\u2026])/g, "$1")
+    .replace(/[ \t]+$/gm, "");
 }
 
-/**
- * Converts a value to its string representation for template rendering.
- * Handles different types appropriately.
- *
- * @param value - The value to convert to string
- * @returns String representation of the value
- */
-function valueToString(value: unknown): string {
-  if (value === null || value === undefined) {
-    return "";
-  }
-
-  if (typeof value === "string") {
-    return value;
-  }
-
-  if (typeof value === "number" || typeof value === "boolean") {
-    return String(value);
-  }
-
-  if (Array.isArray(value)) {
-    // For arrays, join with commas by default
-    // Users can override this by using JSON.stringify in their templates if needed
-    return value.map((item) => valueToString(item)).join(", ");
-  }
-
-  if (typeof value === "object") {
-    // For objects, convert to JSON string
-    // This provides a readable representation while being safe
-    try {
-      return JSON.stringify(value);
-    } catch {
-      return "[object Object]";
-    }
+/** `render` over every string inside a value, recursively. Non-strings pass through. */
+export function renderDeep<T>(value: T, scope: TemplateScope): T {
+  if (typeof value === "string") return render(value, scope) as T;
+  if (Array.isArray(value)) return value.map((item: unknown) => renderDeep(item, scope)) as T;
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value).map(([k, v]) => [k, renderDeep(v, scope)]),
+    ) as T;
   }
-
-  // Fallback for any other type
-  return JSON.stringify(value);
+  return value;
 }
 
-/**
- * Renders template variables in an object recursively.
- * Handles nested objects and arrays.
- *
- * @param obj - The object to render templates in
- * @param context - The context object to pull values from
- * @returns The object with all string templates rendered
- */
-export function renderTemplateObject(
-  obj: unknown,
-  context: Record<string, unknown> | undefined
-): unknown {
-  if (obj === null || obj === undefined) {
-    return obj;
-  }
-
-  if (typeof obj === "string") {
-    return renderTemplate(obj, context);
-  }
-
-  if (Array.isArray(obj)) {
-    return obj.map((item) => renderTemplateObject(item, context));
-  }
-
-  if (typeof obj === "object") {
-    const result: Record<string, unknown> = {};
-    for (const [key, value] of Object.entries(obj)) {
-      result[key] = renderTemplateObject(value, context);
-    }
-    return result;
-  }
-
-  return obj;
-}
-
-/**
- * Creates helper functions for working with history and context in templates.
- * These helpers make it easier to access message content and perform common operations.
- *
- * @param history - The event history array
- * @returns Object containing helper functions
- */
-export function createTemplateHelpers(history?: Event[]) {
-  const helpers = {
-    /**
-     * Get the last message from history, optionally filtered by role.
-     * @param role - Optional role to filter by (user, assistant, etc.)
-     * @returns The message content or undefined if not found
-     */
-    getLastMessage(role?: MessageRole): string | undefined {
-      if (!history || history.length === 0) return undefined;
-
-      // Search backwards through history for the most recent message
-      for (let i = history.length - 1; i >= 0; i--) {
-        const event = history[i];
-        if (event.kind === EventKind.MESSAGE) {
-          // If no role specified, return the first message found
-          if (!role || event.source === role) {
-            const messageData = event.data as MessageEventData;
-            return messageData.message;
-          }
-        }
-      }
-      return undefined;
-    },
-
-    /**
-     * Get the last user message from history.
-     * @returns The user message content or undefined if not found
-     */
-    getLastUserMessage(): string | undefined {
-      return helpers.getLastMessage(MessageRole.USER);
-    },
-
-    /**
-     * Get the last assistant message from history.
-     * @returns The assistant message content or undefined if not found
-     */
-    getLastAssistantMessage(): string | undefined {
-      return helpers.getLastMessage(MessageRole.ASSISTANT);
-    },
-
-    /**
-     * Get all messages from history, optionally filtered by role.
-     * @param role - Optional role to filter by
-     * @returns Array of message contents
-     */
-    getMessages(role?: MessageRole): string[] {
-      if (!history || history.length === 0) return [];
-
-      const messages: string[] = [];
-      for (const event of history) {
-        if (event.kind === EventKind.MESSAGE) {
-          if (!role || event.source === role) {
-            const messageData = event.data as MessageEventData;
-            messages.push(messageData.message);
-          }
-        }
-      }
-      return messages;
-    },
-
-    /**
-     * Check if the last message contains any of the given keywords.
-     * @param keywords - Keywords to search for
-     * @param caseSensitive - Whether to perform case-sensitive search (default: false)
-     * @returns True if any keyword is found
-     */
-    lastMessageContains(keywords: string | string[], caseSensitive: boolean = false): boolean {
-      const lastMessage = helpers.getLastMessage();
-      if (!lastMessage) return false;
-
-      const searchText = caseSensitive ? lastMessage : lastMessage.toLowerCase();
-      const keywordArray = Array.isArray(keywords) ? keywords : [keywords];
-      
-      return keywordArray.some(keyword => {
-        const searchKeyword = caseSensitive ? keyword : keyword.toLowerCase();
-        return searchText.includes(searchKeyword);
-      });
-    },
-  };
-
-  return helpers;
-}
-
-/**
- * Creates a complete TemplateContext with helpers included.
- * This is a convenience function for creating template contexts with all the helper methods.
- *
- * @param params - The base template context parameters
- * @returns Complete TemplateContext with helpers
- */
-export function createTemplateContext<TContext = unknown, TData = unknown>(
-  params: Omit<Partial<TemplateContext<TContext, TData>>, 'helpers'>
-): TemplateContext<TContext, TData> {
-  return {
-    ...params,
-    data: params.data || {},
-    helpers: createTemplateHelpers(params.history),
-  };
-}
-
-/**
- * Formats a JSON structure into readable markdown format.
- * Handles nested objects, arrays, and primitive values.
- *
- * @param data - The JSON data to format
- * @param title - Optional title for the knowledge base section
- * @param maxDepth - Maximum nesting depth (default: 3)
- * @returns Formatted markdown string
- *
- * @example
- * ```typescript
- * const knowledge = {
- *   company: {
- *     name: "Acme Corp",
- *     products: ["Widget A", "Widget B"],
- *     locations: {
- *       headquarters: "NYC",
- *       branches: ["LA", "Chicago"]
- *     }
- *   }
- * };
- *
- * const markdown = formatKnowledgeBase(knowledge, "Company Information");
- * // Output:
- * // ## Company Information
- * //
- * // ### company
- * // - **name**: Acme Corp
- * // - **products**:
- * //   - Widget A
- * //   - Widget B
- * // - **locations**:
- * //   - **headquarters**: NYC
- * //   - **branches**:
- * //     - LA
- * //     - Chicago
- * ```
- */
-export function formatKnowledgeBase(
-  data: Record<string, unknown>,
-  title?: string,
-  maxDepth: number = 3
-): string {
-  const lines: string[] = [];
-
-  if (title) {
-    lines.push(`## ${title}`);
-    lines.push("");
-  }
-
-  if (!data || typeof data !== "object") {
-    lines.push("*No knowledge base data available*");
-    return lines.join("\n");
+function lookup(root: unknown, keys: string[]): unknown {
+  let current = root;
+  for (const key of keys) {
+    if (current === null) return ABSENT;
+    if (typeof current !== "object") return undefined;
+    current = (current as Record<string, unknown>)[key];
   }
-
-  formatObject(data, lines, 0, maxDepth);
-
-  return lines.join("\n");
+  return current;
 }
 
-/**
- * Recursively formats an object into markdown format
- */
-function formatObject(
-  obj: Record<string, unknown>,
-  lines: string[],
-  depth: number,
-  maxDepth: number,
-  prefix: string = ""
-): void {
-  const entries = Object.entries(obj);
-
-  if (entries.length === 0) {
-    lines.push(`${prefix}*Empty*`);
-    return;
-  }
-
-  for (const [key, value] of entries) {
-    const currentPrefix = prefix ? `${prefix}  ` : "";
-
-    if (value === null || value === undefined) {
-      lines.push(`${currentPrefix}- **${key}**: *Not specified*`);
-    } else if (
-      typeof value === "string" ||
-      typeof value === "number" ||
-      typeof value === "boolean"
-    ) {
-      lines.push(`${currentPrefix}- **${key}**: ${value}`);
-    } else if (Array.isArray(value)) {
-      if (value.length === 0) {
-        lines.push(`${currentPrefix}- **${key}**: *Empty list*`);
-      } else {
-        lines.push(`${currentPrefix}- **${key}**:`);
-        for (const item of value) {
-          if (
-            typeof item === "string" ||
-            typeof item === "number" ||
-            typeof item === "boolean"
-          ) {
-            lines.push(`${currentPrefix}  - ${item}`);
-          } else if (
-            depth < maxDepth &&
-            typeof item === "object" &&
-            item !== null
-          ) {
-            lines.push(`${currentPrefix}  - ${JSON.stringify(item)}`);
-          } else {
-            lines.push(`${currentPrefix}  - ${JSON.stringify(item)}`);
-          }
-        }
-      }
-    } else if (typeof value === "object") {
-      if (depth < maxDepth) {
-        lines.push(`${currentPrefix}- **${key}**:`);
-        formatObject(
-          value as Record<string, unknown>,
-          lines,
-          depth + 1,
-          maxDepth,
-          currentPrefix
-        );
-      } else {
-        lines.push(`${currentPrefix}- **${key}**: ${JSON.stringify(value)}`);
-      }
-    } else {
-      lines.push(`${currentPrefix}- **${key}**: ${JSON.stringify(value)}`);
-    }
-  }
+function stringify(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return value.map(stringify).join(", ");
+  return JSON.stringify(value);
 }

package/src/utils/usage.ts

@@ -0,0 +1,37 @@
+/**
+ * Token counts, added up across a turn.
+ *
+ * Providers report per call; a text turn spends two, plus one per tool round,
+ * plus one if the history was compacted. The host bills the conversation, so
+ * the framework hands it one figure beside `llmCalls`.
+ */
+
+import type { TokenUsage } from "../types/ai.js";
+
+interface Counted {
+  promptTokens?: number;
+  completionTokens?: number;
+  cachedInputTokens?: number;
+}
+
+/** What a call's metadata says it cost, or nothing when the provider said nothing. */
+export function readUsage(metadata: Counted | undefined): TokenUsage | undefined {
+  if (!metadata) return undefined;
+  const { promptTokens, completionTokens, cachedInputTokens } = metadata;
+  if (promptTokens === undefined && completionTokens === undefined) return undefined;
+  return {
+    promptTokens: promptTokens ?? 0,
+    completionTokens: completionTokens ?? 0,
+    cachedInputTokens: cachedInputTokens ?? 0,
+  };
+}
+
+/** Adds two tallies. Nobody counting is not the same as counting zero. */
+export function addUsage(a: TokenUsage | undefined, b: TokenUsage | undefined): TokenUsage | undefined {
+  if (!a || !b) return a ?? b;
+  return {
+    promptTokens: a.promptTokens + b.promptTokens,
+    completionTokens: a.completionTokens + b.completionTokens,
+    cachedInputTokens: a.cachedInputTokens + b.cachedInputTokens,
+  };
+}

package/dist/adapters/MemoryAdapter.d.ts

@@ -1,47 +0,0 @@
-/**
- * Memory adapter for persistence
- * In-memory storage for testing and development (no database required)
- */
-import type { MessageData, MessageRepository, PersistenceAdapter, SessionData, SessionRepository } from "../types/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 declare class MemoryAdapter<TData = Record<string, unknown>> implements PersistenceAdapter<TData> {
-    readonly sessionRepository: SessionRepository<TData>;
-    readonly messageRepository: MessageRepository;
-    private sessions;
-    private messages;
-    constructor();
-    /**
-     * Clear all data (useful for testing)
-     */
-    clear(): void;
-    /**
-     * Get data snapshot (useful for debugging)
-     */
-    getSnapshot(): {
-        sessions: SessionData<TData>[];
-        messages: MessageData[];
-    };
-}
-//# sourceMappingURL=MemoryAdapter.d.ts.map

package/dist/adapters/MemoryAdapter.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"MemoryAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/MemoryAdapter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAEV,WAAW,EACX,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EACX,iBAAiB,EAIlB,MAAM,mBAAmB,CAAC;AAK3B;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,aAAa,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAE,YAAW,kBAAkB,CAAC,KAAK,CAAC;IAC9F,SAAgB,iBAAiB,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAC;IAC5D,SAAgB,iBAAiB,EAAE,iBAAiB,CAAC;IACrD,OAAO,CAAC,QAAQ,CAAkC;IAClD,OAAO,CAAC,QAAQ,CAA2B;;IAU3C;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,WAAW,IAAI;QACb,QAAQ,EAAE,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;QAC/B,QAAQ,EAAE,WAAW,EAAE,CAAC;KACzB;CAMF"}