@falai/agent 3.4.5 → 4.0.0-alpha.10

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) {