@falai/agent 3.4.5 → 4.0.0-alpha.2

package/src/utils/schema.ts

@@ -0,0 +1,145 @@
+/**
+ * Fields: what is known, what is still pending, what the model may see, and
+ * how a raw extracted value becomes a typed one.
+ */
+
+import { FlowConfigurationError } from "../types/errors.js";
+import type { FieldDef, FieldDefs, ParamDef, ParamDefs, ScalarDef } from "../types/flow.js";
+import type { StructuredSchema } from "../types/schema.js";
+
+/** The default number of times a field is asked before it is skipped. */
+export const DEFAULT_MAX_ASKS = 3;
+
+/** A value counts as known unless it is `undefined`, `null` or `''`. */
+export function isKnown(value: unknown): boolean {
+  return value !== undefined && value !== null && value !== "";
+}
+
+/** The step's `collect` fields that are still unknown and not yet at `maxAsks`, in order. */
+export function pendingFields(
+  step: { collect?: readonly string[]; maxAsks?: number },
+  data: Record<string, unknown>,
+  asked: Record<string, number>,
+): string[] {
+  const maxAsks = step.maxAsks ?? DEFAULT_MAX_ASKS;
+  return (step.collect ?? []).filter((field) => !isKnown(data[field]) && (asked[field] ?? 0) < maxAsks);
+}
+
+/** How a field may be harvested when the definition does not say: booleans only when asked. */
+export function extractMode(def: FieldDef): "anywhere" | "asked" {
+  return def.extract ?? (def.type === "boolean" ? "asked" : "anywhere");
+}
+
+export type Coerced = { ok: true; value: string | number | boolean } | { ok: false; code: "bad-value" | "not-in-enum" };
+
+/**
+ * Turn a raw value from the model into the field's type. Strings are coerced
+ * to numbers and booleans; enum membership is enforced. The `detail` is the
+ * outcome line the host shows when a value is dropped.
+ */
+export function coerceField(def: ScalarDef, raw: unknown): Coerced {
+  const value = coerceScalar(def, raw);
+  if (value === undefined) return { ok: false, code: "bad-value" };
+  if (def.enum && !def.enum.includes(value as string | number)) {
+    return { ok: false, code: "not-in-enum" };
+  }
+  return { ok: true, value };
+}
+
+function coerceScalar(def: ScalarDef, raw: unknown): string | number | boolean | undefined {
+  switch (def.type) {
+    case "string":
+      if (typeof raw === "string") return raw;
+      if (typeof raw === "number" || typeof raw === "boolean") return String(raw);
+      return undefined;
+    case "number":
+    case "integer": {
+      const n = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw.trim().replace(",", ".")) : NaN;
+      if (!Number.isFinite(n)) return undefined;
+      return def.type === "integer" ? Math.trunc(n) : n;
+    }
+    case "boolean":
+      if (typeof raw === "boolean") return raw;
+      if (typeof raw === "string") {
+        const s = raw.trim().toLowerCase();
+        if (["true", "sim", "yes", "1"].includes(s)) return true;
+        if (["false", "não", "nao", "no", "0"].includes(s)) return false;
+      }
+      return undefined;
+  }
+}
+
+export interface WireOptions {
+  /** Every property is required and accepts `null`. The envelope style. */
+  nullable?: boolean;
+}
+
+/**
+ * The JSON schema a provider sees: an allow-list of JSON-schema keys, with
+ * `ask`, `extract` and `optional` stripped. Closed (`additionalProperties:
+ * false`); every property required unless a parameter says `optional`.
+ */
+export function toWireSchema(defs: FieldDefs | ParamDefs, options: WireOptions = {}): StructuredSchema {
+  const properties: Record<string, StructuredSchema> = {};
+  const required: string[] = [];
+  const entries: Array<[string, FieldDef | ParamDef]> = Object.entries(defs);
+  for (const [name, def] of entries) {
+    properties[name] = wireProperty(def, options.nullable ?? false);
+    if (options.nullable || !("optional" in def && def.optional)) required.push(name);
+  }
+  return { type: "object", properties, required, additionalProperties: false };
+}
+
+function wireProperty(def: FieldDef | ParamDef, nullable: boolean): StructuredSchema {
+  const out: StructuredSchema = def.type === "array"
+    ? { type: "array", items: wireProperty(def.items, false) }
+    : { type: def.type };
+  if (def.description) out.description = def.description;
+  if (def.type !== "array" && def.enum) out.enum = [...def.enum];
+  if (nullable) out.type = [def.type, "null"];
+  return out;
+}
+
+/**
+ * Merge field rows authored per flow into the agent's one field set. Two
+ * rows for one slug must agree on type and enum; the first non-empty `ask`
+ * and `description` win.
+ */
+export function buildSchema(groups: Array<{ id: string; fields: FieldDefs }>): FieldDefs {
+  const merged: FieldDefs = {};
+  const owner: Record<string, string> = {};
+  for (const group of groups) {
+    for (const [slug, def] of Object.entries(group.fields)) {
+      const seen = merged[slug];
+      if (!seen) {
+        merged[slug] = { ...def };
+        owner[slug] = group.id;
+        continue;
+      }
+      if (seen.type !== def.type) {
+        throw new FlowConfigurationError(
+          `[FlowConfigurationError] field "${slug}" has two types: "${seen.type}" in "${owner[slug]}", ` +
+            `"${def.type}" in "${group.id}". Give one slug one type.`,
+        );
+      }
+      if (seen.enum && def.enum && !sameList(seen.enum, def.enum)) {
+        throw new FlowConfigurationError(
+          `[FlowConfigurationError] field "${slug}" has two option lists: in "${owner[slug]}" and "${group.id}". ` +
+            `Give one slug one list.`,
+        );
+      }
+      merged[slug] = {
+        ...seen,
+        enum: seen.enum ?? def.enum,
+        ask: seen.ask ?? def.ask,
+        description: seen.description ?? def.description,
+        extract: seen.extract ?? def.extract,
+      };
+    }
+  }
+  return merged;
+}
+
+function sameList(a: readonly (string | number)[], b: readonly (string | number)[]): boolean {
+  return a.length === b.length && a.every((v, i) => v === b[i]);
+}

package/src/utils/streamingMessage.ts

@@ -13,8 +13,9 @@
  * (tracking object depth and string context, so a nested decoy `"message"` key
  * or a `"message"` substring inside another value is never mistaken for it),
  * and is tolerant of truncation at any byte — a dangling escape sequence is
- * held back rather than emitted half-decoded. Input that is not a JSON object
- * (e.g. a provider streaming plain text) is passed through verbatim.
+ * held back rather than emitted half-decoded. A markdown fence around the
+ * object is skipped, and input that is not a JSON object (e.g. a provider
+ * streaming plain text) is passed through verbatim.
  */
 
 const WHITESPACE = " \t\n\r";
@@ -140,6 +141,28 @@ function skipJsonValue(s: string, i: number): ValueSkip {
   return j < n ? { end: j, complete: true } : { end: n, complete: false };
 }
 
+/**
+ * Index just past a leading markdown fence, `i` when there is none, or -1 when
+ * the text starts with backticks whose opening line has not arrived yet.
+ *
+ * A schema the model was merely ASKED for — which is how one rides on any call
+ * that also carries tools — comes back fenced from some models:
+ * ```json\n{"message":"…"}\n```. The non-streaming parser strips that fence;
+ * without the same step here the whole envelope streams to the customer
+ * verbatim, which is the leak this module exists to prevent. While the opener
+ * is still arriving there is no telling a fence from prose, so the caller holds
+ * the text back rather than guess.
+ */
+function fenceEnd(s: string, i: number): number {
+  if (s[i] !== "`") return i;
+  let j = i;
+  while (j < s.length && s[j] === "`") j++;
+  if (j === s.length) return -1; // still arriving: "`", "``", "```"
+  if (j - i < 3) return i; // one or two backticks: inline code in prose
+  const newline = s.indexOf("\n", j);
+  return newline === -1 ? -1 : newline + 1;
+}
+
 /**
  * Extract the decoded value of the top-level `message` string field from a
  * (possibly partial) JSON object string, returning the text available so far.
@@ -154,8 +177,15 @@ export function extractMessageSoFar(accumulated: string): string {
   let i = 0;
   while (i < n && WHITESPACE.includes(s[i])) i++;
 
-  // Not a JSON object — a plain-text stream; emit verbatim.
-  if (i >= n || s[i] !== "{") return accumulated;
+  const afterFence = fenceEnd(s, i);
+  if (afterFence === -1) return ""; // backticks arriving: a fence may be opening
+  const fenced = afterFence !== i;
+  i = afterFence;
+  while (i < n && WHITESPACE.includes(s[i])) i++;
+
+  // Not a JSON object — a plain-text stream; emit verbatim. Behind a fence it
+  // is an envelope whatever it holds, so nothing is emitted.
+  if (i >= n || s[i] !== "{") return fenced ? "" : accumulated;
   i++; // skip '{'
 
   while (i < n) {

package/src/utils/template.ts

@@ -1,442 +1,51 @@
-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.
- *
- * @example
- * ```typescript
- * // With a string template
- * const result1 = await render("Hello {{name}}", { context: { name: "Alice" } });
- * // Result: "Hello Alice"
+ * `{{path}}` substitution for prompts, `say` texts and action parameters.
  *
- * // With a function template
- * const fnTemplate = ({ context }) => `Hello ${context.name}`;
- * const result2 = await render(fnTemplate, { context: { name: "Bob" } });
- * // Result: "Hello Bob"
- * ```
+ * 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.
  */
-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;
+
+export function render(template: string, scope: TemplateScope): string {
+  return template.replace(PLACEHOLDER, (match, path: string) => {
+    const value = lookup(scope, path.split("."));
+    return value === undefined || value === null ? match : stringify(value);
+  });
 }
 
-/**
- * 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;
+/** `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;
   }
-
-  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);
-    }
-  );
+  return value;
 }
 
-/**
- * Gets a value from an object using dot notation path.
- * Supports nested property access like "user.name" or "user.address.city".
- *
- * @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
- */
-function getValueByPath(obj: Record<string, unknown>, path: string): unknown {
-  const keys = path.split(".");
-  let current: unknown = obj;
-
+function lookup(root: unknown, keys: string[]): unknown {
+  let current = root;
   for (const key of keys) {
-    if (
-      current === null ||
-      current === undefined ||
-      typeof current !== "object"
-    ) {
-      return undefined;
-    }
+    if (current === null || typeof current !== "object") return undefined;
     current = (current as Record<string, unknown>)[key];
   }
-
   return current;
 }
 
-/**
- * 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]";
-    }
-  }
-
-  // Fallback for any other type
+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);
 }
-
-/**
- * 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");
-  }
-
-  formatObject(data, lines, 0, maxDepth);
-
-  return lines.join("\n");
-}
-
-/**
- * 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)}`);
-    }
-  }
-}