@falai/agent 3.4.5 → 4.0.0-alpha.1

package/src/persistence/PrismaStore.ts

@@ -0,0 +1,127 @@
+/**
+ * Prisma Store over a generated Prisma client.
+ *
+ * The model (default `agentSession`) needs five fields, renameable through
+ * `fieldMappings.sessions`:
+ *
+ * ```prisma
+ * model AgentSession {
+ *   id        String   @id
+ *   version   Int
+ *   blob      Json
+ *   createdAt DateTime @default(now())
+ *   updatedAt DateTime @updatedAt
+ * }
+ * ```
+ *
+ * A first save is `create`, and Prisma's unique violation (`P2002`) is the
+ * conflict; later saves are `updateMany` filtered on `{ id, version }`, and
+ * `count === 0` is the conflict. 3.x read, checked and wrote in three steps
+ * and tolerated a model without `version`; neither survives.
+ */
+
+import { isRecord } from "../utils/json.js";
+import { SessionConflictError } from "../types/errors.js";
+import type { Session, Store } from "../types/session.js";
+import { readBlob, toBlob } from "./sessionRow.js";
+
+/** The delegate a generated client exposes per model. */
+export interface PrismaSessionModel {
+  create(params: { data: Record<string, unknown> }): Promise<Record<string, unknown>>;
+  findUnique(params: { where: Record<string, unknown> }): Promise<Record<string, unknown> | null>;
+  updateMany(params: { where: Record<string, unknown>; data: Record<string, unknown> }): Promise<{ count: number }>;
+}
+
+/** Matches a generated Prisma client: model delegates by name, plus `$disconnect`. */
+export interface PrismaClient {
+  [model: string]: unknown;
+  $disconnect?: () => Promise<void>;
+}
+
+export type PrismaSessionField = "id" | "version" | "blob" | "createdAt" | "updatedAt";
+
+export interface PrismaStoreOptions {
+  prisma: PrismaClient;
+  /** Model name on the client. Default `agentSession`. */
+  tables?: { sessions?: string };
+  /** Field names when the model uses other names. */
+  fieldMappings?: { sessions?: Partial<Record<PrismaSessionField, string>> };
+}
+
+export class PrismaStore<D = unknown> implements Store<D> {
+  private readonly prisma: PrismaClient;
+  private readonly model: PrismaSessionModel;
+  private readonly field: Record<PrismaSessionField, string>;
+
+  constructor(options: PrismaStoreOptions) {
+    const name = options.tables?.sessions ?? "agentSession";
+    const model = options.prisma[name];
+    if (!isSessionModel(model)) {
+      throw new TypeError(
+        `[TypeError] PrismaStore cannot use model "${name}": the client has no such delegate with create, findUnique and updateMany. ` +
+          `Add the model to schema.prisma and run prisma generate, or pass tables.sessions with its name.`,
+      );
+    }
+    this.prisma = options.prisma;
+    this.model = model;
+    const custom = options.fieldMappings?.sessions ?? {};
+    this.field = {
+      id: custom.id ?? "id",
+      version: custom.version ?? "version",
+      blob: custom.blob ?? "blob",
+      createdAt: custom.createdAt ?? "createdAt",
+      updatedAt: custom.updatedAt ?? "updatedAt",
+    };
+  }
+
+  async disconnect(): Promise<void> {
+    await this.prisma.$disconnect?.();
+  }
+
+  async load(id: string): Promise<Session<D> | null> {
+    const row = await this.model.findUnique({ where: { [this.field.id]: id } });
+    return row ? readBlob<D>(row[this.field.blob], id) : null;
+  }
+
+  async save(session: Session<D>, expectedVersion: number): Promise<Session<D>> {
+    const next = expectedVersion + 1;
+    const blob = toBlob(session, next);
+    const now = new Date();
+    const { field } = this;
+    if (expectedVersion === 0) {
+      try {
+        await this.model.create({
+          data: { [field.id]: session.id, [field.version]: next, [field.blob]: blob, [field.createdAt]: now, [field.updatedAt]: now },
+        });
+      } catch (error) {
+        if (!isUniqueViolation(error)) throw error;
+        throw new SessionConflictError(session.id, 0, await this.storedVersion(session.id));
+      }
+      return blob;
+    }
+    const { count } = await this.model.updateMany({
+      where: { [field.id]: session.id, [field.version]: expectedVersion },
+      data: { [field.version]: next, [field.blob]: blob, [field.updatedAt]: now },
+    });
+    if (count === 0) throw new SessionConflictError(session.id, expectedVersion, await this.storedVersion(session.id));
+    return blob;
+  }
+
+  private async storedVersion(id: string): Promise<number | undefined> {
+    const row = await this.model.findUnique({ where: { [this.field.id]: id } });
+    const version = row?.[this.field.version];
+    return typeof version === "number" ? version : undefined;
+  }
+}
+
+function isSessionModel(value: unknown): value is PrismaSessionModel {
+  return (
+    isRecord(value) &&
+    typeof value.create === "function" &&
+    typeof value.findUnique === "function" &&
+    typeof value.updateMany === "function"
+  );
+}
+
+/** Prisma's `PrismaClientKnownRequestError` for a unique constraint hit. */
+const isUniqueViolation = (error: unknown): boolean => isRecord(error) && error.code === "P2002";

package/src/persistence/RedisStore.ts

@@ -0,0 +1,90 @@
+/**
+ * Redis Store over an ioredis-shaped client.
+ *
+ * One hash per session at `${keyPrefix}session:${id}` with the fields
+ * `version`, `blob` (the v4 session as JSON text), `createdAt`, `updatedAt`.
+ * The compare-and-swap is one Lua script, so two writers on a shared client
+ * cannot interleave between the read and the write (3.x checked, then set;
+ * WATCH/MULTI would not do either, since WATCH is per connection).
+ */
+
+import { SessionConflictError } from "../types/errors.js";
+import type { Session, Store } from "../types/session.js";
+import { readBlob, toBlob } from "./sessionRow.js";
+
+/** Matches ioredis. node-redis users wrap `eval` to this positional form. */
+export interface RedisClient {
+  hgetall(key: string): Promise<Record<string, string>>;
+  eval(script: string, numKeys: number, ...args: (string | number)[]): Promise<unknown>;
+  quit(): Promise<string>;
+}
+
+export interface RedisStoreOptions {
+  redis: RedisClient;
+  /** Prefix of every key. Default `agent:`. */
+  keyPrefix?: string;
+  /** Seconds a session lives after its last save; `0` keeps it forever. Default 7 days. */
+  sessionTTL?: number;
+}
+
+/**
+ * KEYS[1] the session hash; ARGV: expected version, next version, blob, now, ttl.
+ * Returns nil on success, the stored version on a conflict, `missing` when
+ * the hash is gone.
+ */
+const CAS_SCRIPT = `
+local current = redis.call('HGET', KEYS[1], 'version')
+if ARGV[1] == '0' then
+  if current then return current end
+elseif current ~= ARGV[1] then
+  return current or 'missing'
+end
+redis.call('HSET', KEYS[1], 'version', ARGV[2], 'blob', ARGV[3], 'updatedAt', ARGV[4])
+redis.call('HSETNX', KEYS[1], 'createdAt', ARGV[4])
+if tonumber(ARGV[5]) > 0 then redis.call('EXPIRE', KEYS[1], ARGV[5]) end
+return nil
+`;
+
+export class RedisStore<D = unknown> implements Store<D> {
+  private readonly redis: RedisClient;
+  private readonly keyPrefix: string;
+  private readonly ttl: number;
+
+  constructor(options: RedisStoreOptions) {
+    this.redis = options.redis;
+    this.keyPrefix = options.keyPrefix ?? "agent:";
+    this.ttl = options.sessionTTL ?? 7 * 24 * 60 * 60;
+  }
+
+  async disconnect(): Promise<void> {
+    await this.redis.quit();
+  }
+
+  async load(id: string): Promise<Session<D> | null> {
+    const row = await this.redis.hgetall(this.key(id));
+    if (Object.keys(row).length === 0) return null;
+    return readBlob<D>(row.blob, id);
+  }
+
+  async save(session: Session<D>, expectedVersion: number): Promise<Session<D>> {
+    const next = expectedVersion + 1;
+    const blob = toBlob(session, next);
+    const result = await this.redis.eval(
+      CAS_SCRIPT,
+      1,
+      this.key(session.id),
+      String(expectedVersion),
+      String(next),
+      JSON.stringify(blob),
+      new Date().toISOString(),
+      String(this.ttl),
+    );
+    if (result === null || result === undefined) return blob;
+    const actual = typeof result === "string" && result !== "missing" ? Number(result) : undefined;
+    throw new SessionConflictError(session.id, expectedVersion, actual);
+  }
+
+  private key(id: string): string {
+    return `${this.keyPrefix}session:${id}`;
+  }
+}

package/src/persistence/SQLiteStore.ts

@@ -0,0 +1,103 @@
+/**
+ * SQLite Store over a better-sqlite3-shaped database (bun:sqlite fits too).
+ *
+ * One row per session: `id`, `version`, `blob` (the v4 session as JSON text),
+ * `created_at`, `updated_at`. The compare-and-swap is the statement itself:
+ * `INSERT OR IGNORE` for a first save, `UPDATE … WHERE version = ?` after,
+ * and `changes === 0` means someone else got there first.
+ *
+ * A 3.x `agent_sessions` table has different columns. Point `tables.sessions`
+ * at a fresh table; 3.x blobs move through `migrateSession` at the host's
+ * choke point, not through this table.
+ */
+
+import { SessionConflictError } from "../types/errors.js";
+import type { Session, Store } from "../types/session.js";
+import { asPromise, readBlob, toBlob } from "./sessionRow.js";
+
+/** Matches better-sqlite3 and bun:sqlite statements. */
+export interface SqliteStatement {
+  run(...params: unknown[]): { changes: number };
+  get(...params: unknown[]): unknown;
+}
+
+/** Matches better-sqlite3 and bun:sqlite databases. */
+export interface SqliteDatabase {
+  prepare(sql: string): SqliteStatement;
+  exec(sql: string): unknown;
+  close(): void;
+}
+
+export interface SQLiteStoreOptions {
+  db: SqliteDatabase;
+  /** Table name. Default `agent_sessions`. */
+  tables?: { sessions?: string };
+}
+
+export class SQLiteStore<D = unknown> implements Store<D> {
+  private readonly db: SqliteDatabase;
+  private readonly table: string;
+
+  constructor(options: SQLiteStoreOptions) {
+    this.db = options.db;
+    this.table = options.tables?.sessions ?? "agent_sessions";
+  }
+
+  /** Create the table when it is missing. */
+  initialize(): Promise<void> {
+    return asPromise(() => {
+      this.db.exec(
+        `CREATE TABLE IF NOT EXISTS ${this.table} (
+          id TEXT PRIMARY KEY,
+          version INTEGER NOT NULL,
+          blob TEXT NOT NULL,
+          created_at TEXT NOT NULL,
+          updated_at TEXT NOT NULL
+        )`,
+      );
+    });
+  }
+
+  disconnect(): Promise<void> {
+    return asPromise(() => this.db.close());
+  }
+
+  load(id: string): Promise<Session<D> | null> {
+    return asPromise(() => {
+      const row = this.db.prepare(`SELECT blob FROM ${this.table} WHERE id = ?`).get(id);
+      if (row === undefined || row === null) return null;
+      return readBlob<D>(column(row, "blob"), id);
+    });
+  }
+
+  save(session: Session<D>, expectedVersion: number): Promise<Session<D>> {
+    return asPromise(() => {
+      const next = expectedVersion + 1;
+      const blob = toBlob(session, next);
+      const json = JSON.stringify(blob);
+      const now = new Date().toISOString();
+      const result =
+        expectedVersion === 0
+          ? this.db
+              .prepare(
+                `INSERT OR IGNORE INTO ${this.table} (id, version, blob, created_at, updated_at) VALUES (?, ?, ?, ?, ?)`,
+              )
+              .run(session.id, next, json, now, now)
+          : this.db
+              .prepare(`UPDATE ${this.table} SET version = ?, blob = ?, updated_at = ? WHERE id = ? AND version = ?`)
+              .run(next, json, now, session.id, expectedVersion);
+      if (result.changes === 0) throw new SessionConflictError(session.id, expectedVersion, this.storedVersion(session.id));
+      return blob;
+    });
+  }
+
+  private storedVersion(id: string): number | undefined {
+    const row = this.db.prepare(`SELECT version FROM ${this.table} WHERE id = ?`).get(id);
+    const version = row === undefined || row === null ? undefined : column(row, "version");
+    return typeof version === "number" ? version : undefined;
+  }
+}
+
+function column(row: unknown, name: string): unknown {
+  return typeof row === "object" && row !== null && name in row ? (row as Record<string, unknown>)[name] : undefined;
+}

package/src/persistence/sessionRow.ts

@@ -0,0 +1,45 @@
+/**
+ * What every store writes and reads: the v4 session blob, and nothing else.
+ * One place so the seven stores cannot drift on what a row means.
+ * PostgreSQL hands JSONB back parsed, SQLite and Redis hand back text; both
+ * arrive here.
+ */
+
+import { assertSession, InvalidSessionError } from "../core/Migrate.js";
+import type { Session } from "../types/session.js";
+
+/** The blob to persist, stamped with the version it is saved as. Optional keys are written only when set. */
+export function toBlob<D>(session: Session<D>, version: number): Session<D> {
+  const blob: Session<D> = {
+    id: session.id,
+    v: 4,
+    version,
+    data: session.data,
+    runs: session.runs,
+    claims: session.claims,
+    inputs: session.inputs,
+    metadata: session.metadata,
+  };
+  if (session.lastUserAt !== undefined) blob.lastUserAt = session.lastUserAt;
+  if (session.lastAssistantAt !== undefined) blob.lastAssistantAt = session.lastAssistantAt;
+  if (session.history !== undefined) blob.history = session.history;
+  return blob;
+}
+
+/** A stored blob (parsed, or JSON text) back to a Session. Anything not v4-shaped throws. */
+export function readBlob<D>(raw: unknown, sessionId: string): Session<D> {
+  let blob: unknown = raw;
+  if (typeof raw === "string") {
+    try {
+      blob = JSON.parse(raw);
+    } catch {
+      throw new InvalidSessionError(sessionId, "blob is not valid JSON");
+    }
+  }
+  return assertSession<D>(blob, sessionId);
+}
+
+/** Runs synchronous store work as a promise, so a thrown error is a rejection like everywhere else. */
+export function asPromise<T>(work: () => T): Promise<T> {
+  return new Promise((resolve) => resolve(work()));
+}

package/src/providers/DeepSeekProvider.ts

@@ -43,7 +43,8 @@ export class DeepSeekProvider extends OpenAICompatibleProvider {
   public readonly name = "deepseek";
   public readonly capabilities: ProviderCapabilities = {
     supportsTools: true,
-    supportsNativeJsonSchema: true,
+    // JSON yes, a schema no — see `structuredOutput` below.
+    supportsNativeJsonSchema: false,
     supportsStreaming: true,
     supportsStreamingToolCalls: true,
     supportsPromptCaching: true,
@@ -60,8 +61,12 @@ export class DeepSeekProvider extends OpenAICompatibleProvider {
       apiKey: options.apiKey,
       baseUrl: options.baseURL ?? "https://api.deepseek.com",
       model: options.model,
-      // No Responses API here; chat completions enforces the schema natively.
-      structuredOutput: "json_schema",
+      // DeepSeek serves `response_format: { type: 'json_object' }` and nothing
+      // else: a `json_schema` format answers
+      // `400 "This response_format type is unavailable now"` on every call.
+      // So the endpoint guarantees JSON and the prompt carries the shape, which
+      // is the path the parser already tolerates.
+      structuredOutput: "json_object",
       ...(options.jsonWithTools ? { jsonWithTools: options.jsonWithTools } : {}),
       ...(options.backupModels ? { backupModels: options.backupModels } : {}),
       ...(options.fallbacks ? { fallbacks: options.fallbacks } : {}),

package/src/providers/GeminiProvider.ts

@@ -5,9 +5,10 @@
  * hits and the thinking levels are all in `@providerkit/core`, written against
  * the REST API rather than the SDK.
  *
- * v3 sends a response schema alongside tools when a caller asks for both. v2
- * dropped the schema in that case, from a 2024-era constraint that no longer
- * holds — a sibling codebase runs the combination in production today.
+ * On Gemini 3 a response schema and tools travel on the same call. On Gemini 2
+ * they cannot: the API answers `400 "Function calling with a response mime
+ * type: 'application/json' is unsupported"`, so the schema rides in the prompt
+ * instead. `@providerkit/core` reads the model id and picks; nothing to set.
  */
 
 import { createGeminiProvider, type FallbackOptions, type Provider } from "@providerkit/core";

package/src/providers/OpenAICompatibleProvider.ts

@@ -52,6 +52,10 @@ export interface OpenAICompatibleProviderInit
   /** Names the provider in errors, and picks core's effort dialect. */
   id: string;
   headers?: Record<string, string>;
+  /** App attribution for OpenRouter's rankings — sent as `HTTP-Referer`. */
+  siteUrl?: string;
+  /** App name for OpenRouter's rankings — sent as `X-Title`. */
+  siteName?: string;
   config?: RequestConfig;
   structuredOutput?: StructuredOutputMode;
   /** See {@link JsonWithTools}. Only affects calls that carry tools. */
@@ -101,6 +105,8 @@ function buildProvider(init: OpenAICompatibleProviderInit, mode: StructuredOutpu
     ...(init.jsonWithTools ? { jsonWithTools: init.jsonWithTools } : {}),
     ...(init.baseUrl ? { baseUrl: init.baseUrl } : {}),
     ...(init.headers ? { headers: init.headers } : {}),
+    ...(init.siteUrl ? { siteUrl: init.siteUrl } : {}),
+    ...(init.siteName ? { siteName: init.siteName } : {}),
     ...(init.config?.maxTokens ? { maxTokens: init.config.maxTokens } : {}),
     ...(init.config?.effort ? { effort: init.config.effort } : {}),
     ...(init.providerOrder ? { providerOrder: init.providerOrder } : {}),

package/src/providers/OpenRouterProvider.ts

@@ -71,10 +71,8 @@ export class OpenRouterProvider extends OpenAICompatibleProvider {
       // json_schema passthrough is what its models actually support.
       structuredOutput: "json_schema",
       ...(options.jsonWithTools ? { jsonWithTools: options.jsonWithTools } : {}),
-      headers: {
-        ...(options.siteUrl ? { "HTTP-Referer": options.siteUrl } : {}),
-        ...(options.siteName ? { "X-Title": options.siteName } : {}),
-      },
+      ...(options.siteUrl ? { siteUrl: options.siteUrl } : {}),
+      ...(options.siteName ? { siteName: options.siteName } : {}),
       ...(options.providerOrder ? { providerOrder: options.providerOrder } : {}),
       ...(options.backupModels ? { backupModels: options.backupModels } : {}),
       ...(options.fallbacks ? { fallbacks: options.fallbacks } : {}),

package/src/providers/ProviderAdapter.ts

@@ -22,6 +22,8 @@ import {
   ProviderError,
   classify,
   isBackupEligible,
+  isCompleteJson,
+  parseToolArgs,
   probeJsonWithTools,
   requireContent,
   streamWatch,
@@ -145,8 +147,13 @@ function shouldTryBackup(error: unknown): boolean {
 }
 
 /** History plus the composed prompt, as the seam's messages. */
-export function toMessages(history: HistoryItem[], prompt: string): ChatMessage[] {
+export function toMessages(history: HistoryItem[], prompt: string, system?: string): ChatMessage[] {
   const out: ChatMessage[] = [];
+  // First, and before any history: a cached prefix is only a prefix if nothing
+  // precedes it. Anthropic-shape hoists every system item into one top-level
+  // block, so a host that also puts system items in its history joins them to
+  // this one — fine while those are stable, and the host's to keep stable.
+  if (system?.trim()) out.push({ role: "system", content: system });
   for (const item of history) {
     switch (item.role) {
       case "system":
@@ -159,6 +166,11 @@ export function toMessages(history: HistoryItem[], prompt: string): ChatMessage[
         out.push({
           role: "assistant",
           content: item.content ?? "",
+          // Anthropic-shape drops these on purpose (its thinking blocks are
+          // signed); OpenAI-shape replays them, which is what DeepSeek and the
+          // GLM endpoints require on a turn that called a tool.
+          ...(item.reasoning ? { reasoning: item.reasoning } : {}),
+          ...(item.reasoningDetails?.length ? { reasoningDetails: item.reasoningDetails } : {}),
           ...(item.tool_calls?.length
             ? {
                 toolCalls: item.tool_calls.map((call) => ({
@@ -212,6 +224,8 @@ function toJsonOutput(input: GenerateMessageInput<unknown>): StreamOptions["json
 interface Accumulator {
   text: string;
   model: string;
+  reasoning: string;
+  reasoningDetails?: unknown[];
   finishReason?: string;
   promptTokens?: number;
   completionTokens?: number;
@@ -229,6 +243,8 @@ function fold(acc: Accumulator, chunk: ProviderChunk): string {
     acc.cachedInputTokens = chunk.usage.cachedInputTokens;
   }
   if (chunk.finishReason) acc.finishReason = chunk.finishReason;
+  if (chunk.reasoning) acc.reasoning += chunk.reasoning;
+  if (chunk.reasoningDetails?.length) acc.reasoningDetails = chunk.reasoningDetails;
   for (const call of chunk.toolCalls ?? []) {
     const entry = acc.calls.get(call.index) ?? { name: "", arguments: "" };
     if (call.name) entry.name = call.name;
@@ -246,11 +262,18 @@ function toolCallsOf(acc: Accumulator, label: string): ToolCallList {
   const out: ToolCallList = [];
   for (const [, entry] of [...acc.calls.entries()].sort(([a], [b]) => a - b)) {
     if (!entry.name) continue;
-    let args: Record<string, unknown> = {};
-    try {
-      if (entry.arguments) args = JSON.parse(entry.arguments) as Record<string, unknown>;
-    } catch (error) {
-      logger.warn(`[${label}] Failed to parse tool call arguments:`, error);
+    // Arguments arrive in fragments and the last one can be cut: a stream that
+    // ended early, a model at its `max_tokens`, a gateway that double-escaped.
+    // `JSON.parse` on that string throws, and the tool then ran with NOTHING —
+    // a lookup with no id, a send with no recipient, behind one warn line.
+    // `parseToolArgs` recovers what the model did send, closing an open string
+    // rather than dropping it — so a cut value arrives short instead of absent,
+    // and the tool's own `validateInput` decides whether that is enough.
+    const args = entry.arguments ? parseToolArgs(entry.arguments) : {};
+    if (entry.arguments && !isCompleteJson(entry.arguments)) {
+      logger.warn(
+        `[${label}] ${entry.name}: arguments were cut mid-stream; kept ${Object.keys(args).length} field(s).`,
+      );
     }
     out.push({ toolName: entry.name, arguments: args });
   }
@@ -333,10 +356,10 @@ export abstract class ProviderAdapter implements AiProvider {
   async *generateMessageStream<TContext = unknown, TStructured = AgentStructuredResponse>(
     input: GenerateMessageInput<TContext>,
   ): AsyncGenerator<GenerateMessageStreamChunk<TStructured>> {
-    const messages = toMessages(input.history, input.prompt);
+    const messages = toMessages(input.history, input.prompt, input.system);
     const tools = toTools(input.tools);
     const json = toJsonOutput(input);
-    const acc: Accumulator = { text: "", model: this.primaryModel, calls: new Map() };
+    const acc: Accumulator = { text: "", model: this.primaryModel, reasoning: "", calls: new Map() };
 
     const opts: StreamOptions = {
       ...this.defaults,
@@ -409,10 +432,15 @@ export abstract class ProviderAdapter implements AiProvider {
     const text = json && !structured && isJSONShaped(acc.text) ? "" : acc.text;
 
     if (toolCalls.length > 0) {
+      // The reasoning rides out with the tool calls it produced. A thinking
+      // provider rejects the next round when the assistant turn that called the
+      // tool comes back without it, so the caller has to be able to replay it.
       structured = {
         ...(structured ?? {}),
         message: (structured as AgentStructuredResponse | undefined)?.message || text,
         toolCalls,
+        ...(acc.reasoning ? { reasoning: acc.reasoning } : {}),
+        ...(acc.reasoningDetails ? { reasoningDetails: acc.reasoningDetails } : {}),
       } as TStructured;
     }