akanjs 3.1.0-rc.2 → 3.1.0-rc.21

package/service/predefinedAdaptor/anthropicLlm.ts

@@ -2,6 +2,7 @@ import { adapt } from "../adapt";
 import type {
   AgentWireAttachment,
   AgentWireMessage,
+  AgentWireToolResult,
   LlmAccepts,
   LlmAdaptor,
   LlmLimits,
@@ -14,12 +15,14 @@ import { LlmOverflow } from "./llmOverflow";
 import { eachSseData } from "./sseData";
 
 type AnthropicSource = { type: "base64"; media_type: string; data: string } | { type: "url"; url: string };
-type AnthropicBlock =
+type AnthropicContentBlock =
   | { type: "text"; text: string }
   | { type: "image"; source: AnthropicSource }
-  | { type: "document"; source: AnthropicSource }
+  | { type: "document"; source: AnthropicSource };
+type AnthropicBlock =
+  | AnthropicContentBlock
   | { type: "tool_use"; id: string; name: string; input: Record<string, unknown> }
-  | { type: "tool_result"; tool_use_id: string; content: string };
+  | { type: "tool_result"; tool_use_id: string; content: string | AnthropicContentBlock[] };
 interface AnthropicMessage {
   role: "user" | "assistant";
   content: AnthropicBlock[];
@@ -76,7 +79,7 @@ export class AnthropicLlm
   }
 
   async chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null> {
-    const model = this.llmOption.model;
+    const model = request.model || this.llmOption.model;
     if (!this.llmOption.apiKey || !model) {
       this.logger.warn(
         "AnthropicLlm needs both apiKey and model — set them with option.setLlm(). Agent turns are unavailable.",
@@ -221,15 +224,7 @@ export class AnthropicLlm
     if (message.role === "tool")
       return {
         role: "user",
-        content: (message.toolResults ?? []).map((result) => ({
-          type: "tool_result" as const,
-          tool_use_id: result.id,
-          content: JSON.stringify({
-            ...(result.result !== undefined ? { result: result.result } : {}),
-            ...(result.changes?.length ? { changes: result.changes } : {}),
-            ...(result.error ? { error: result.error } : {}),
-          }),
-        })),
+        content: (message.toolResults ?? []).map((result) => AnthropicLlm.toolResult(result, accepts)),
       };
     if (message.role === "assistant")
       return {
@@ -248,9 +243,36 @@ export class AnthropicLlm
   }
 
   static userContent(message: AgentWireMessage, accepts?: LlmAccepts): AnthropicBlock[] {
-    const attachments = message.attachments ?? [];
     const notes: string[] = [];
-    const blocks = attachments.flatMap((attachment): AnthropicBlock[] => {
+    const blocks = AnthropicLlm.attachmentBlocks(message.attachments ?? [], accepts, notes);
+    const text = [message.text, ...notes].filter(Boolean).join("\n\n");
+    return [...(text ? [{ type: "text" as const, text }] : []), ...blocks];
+  }
+
+  /** A string while the call returned no file, so a transcript without one posts what it always did. */
+  static toolResult(result: AgentWireToolResult, accepts?: LlmAccepts): AnthropicBlock {
+    const payload = JSON.stringify({
+      ...(result.result !== undefined ? { result: result.result } : {}),
+      ...(result.changes?.length ? { changes: result.changes } : {}),
+      ...(result.error ? { error: result.error } : {}),
+    });
+    if (!result.attachments?.length) return { type: "tool_result", tool_use_id: result.id, content: payload };
+    const notes: string[] = [];
+    const blocks = AnthropicLlm.attachmentBlocks(result.attachments, accepts, notes);
+    return {
+      type: "tool_result",
+      tool_use_id: result.id,
+      content: [{ type: "text", text: [payload, ...notes].join("\n\n") }, ...blocks],
+    };
+  }
+
+  /** Pushes a note for each file no block can carry, for the caller to fold into the text beside them. */
+  static attachmentBlocks(
+    attachments: AgentWireAttachment[],
+    accepts: LlmAccepts | undefined,
+    notes: string[],
+  ): AnthropicContentBlock[] {
+    return attachments.flatMap((attachment): AnthropicContentBlock[] => {
       if (attachment.text)
         return [
           {
@@ -271,8 +293,6 @@ export class AnthropicLlm
       notes.push(`[Attachment not read: ${attachment.name} (${attachment.mimeType}) — this API has no block for it.]`);
       return [];
     });
-    const text = [message.text, ...notes].filter(Boolean).join("\n\n");
-    return [...(text ? [{ type: "text" as const, text }] : []), ...blocks];
   }
 
   static typed(source: AnthropicSource, mimeType: string): AnthropicSource {

package/service/predefinedAdaptor/database.adaptor.ts

@@ -19,8 +19,10 @@ import {
   SearchIndex,
 } from "./searchIndex";
 import { PostgresDialect } from "./sql/dialect/postgres";
+import { SqliteDialect } from "./sql/dialect/sqlite";
 import { BunSqliteClient } from "./sql/driver/bunSqlite";
 import { PostgresAkanClient } from "./sql/driver/postgres";
+import { MigrationTables } from "./sql/MigrationTables";
 import { PendingStoreEnsures } from "./sql/PendingStoreEnsures";
 import { PostgresInsightSession } from "./sql/PostgresInsightSession";
 import { SqlDocumentStore } from "./sql/SqlDocumentStore";
@@ -41,6 +43,13 @@ import { defaultSqliteFile } from "./sqlitePath";
 
 export { PostgresDialect } from "./sql/dialect/postgres";
 export { SqliteDialect } from "./sql/dialect/sqlite";
+export { type MigrationLedgerTable, MigrationTables } from "./sql/MigrationTables";
+export {
+  RawDocumentTable,
+  type RawFilter,
+  type RawFilterOperators,
+  type RawFindOptions,
+} from "./sql/RawDocumentTable";
 export { SqlDocumentStore } from "./sql/SqlDocumentStore";
 export type {
   AkanSqlClient,
@@ -55,8 +64,10 @@ export type {
   SqlDialect,
   SqliteDatabaseConfig,
   SqlResultRows,
+  TransferRow,
   UpsertByIdOptions,
 } from "./sql/types";
+export { descriptorHash, stableJson } from "./sql/values";
 
 const searchConfigOf = (env: SqliteEnv): Required<SearchConfig> => ({
   enabled: env.database?.search?.enabled ?? parseSearchEnabled(process.env.AKAN_SEARCH_ENABLED),
@@ -87,6 +98,7 @@ export class SqliteDatabase
   }))
   implements DatabaseAdaptor
 {
+  readonly dialect = new SqliteDialect();
   #db!: Database;
   #client!: BunSqliteClient;
   #stores = new Map<string, SqlDocumentStore>();
@@ -111,6 +123,7 @@ export class SqliteDatabase
     this.#db.run(
       `CREATE TABLE IF NOT EXISTS "_akan_meta" ("key" TEXT PRIMARY KEY NOT NULL, "value" TEXT NOT NULL, "updatedAt" INTEGER NOT NULL)`,
     );
+    for (const statement of MigrationTables.schema(this.dialect)) this.#db.run(statement);
     this.#searchIndex = new SearchIndex(this, this.config.search);
     await this.#searchIndex.ensureSchema();
     this.scheduler.registerCron(OPTIMIZE_CRON_KEY, OPTIMIZE_CRON, async () => {
@@ -246,6 +259,7 @@ export class PostgresDatabase
   }))
   implements DatabaseAdaptor
 {
+  readonly dialect = new PostgresDialect();
   #sql!: Sql;
   #client!: PostgresAkanClient;
   #stores = new Map<string, SqlDocumentStore>();
@@ -278,6 +292,7 @@ export class PostgresDatabase
       await this.getConnection().execute(
         `CREATE TABLE IF NOT EXISTS "_akan_meta" ("key" TEXT PRIMARY KEY NOT NULL, "value" TEXT NOT NULL, "updatedAt" BIGINT NOT NULL)`,
       );
+      for (const statement of MigrationTables.schema(this.dialect)) await this.getConnection().execute(statement);
       await this.getConnection().execute(PostgresDialect.schemaSetup());
       await this.#grantInsightSchema();
     });

package/service/predefinedAdaptor/documentTransfer.ts

@@ -1,6 +1,7 @@
 import { mkdir, readdir } from "node:fs/promises";
 import path from "node:path";
 import { Logger } from "akanjs/common";
+import { type MigrationLedgerTable, MigrationTables } from "./sql/MigrationTables";
 import type { DatabaseAdaptor, TransferRow } from "./sql/types";
 
 export interface TransferReport {
@@ -11,6 +12,7 @@ export interface TransferReport {
 /**
  * Model tables to one NDJSON file each and back, rows as stored. `_akan_meta`, the search mirror, the cache and the
  * queue stay behind: the target writes its own meta and rebuilds the mirror; sessions and pending jobs do not move.
+ * The migration ledger moves with the rows, or the target would run again the scripts its data already went through.
  */
 export class DocumentTransfer {
   static readonly #chunk = 1000;
@@ -39,9 +41,35 @@ export class DocumentTransfer {
       await writer.end();
       reports.push({ table: store.table, rows });
     }
+    for (const table of MigrationTables.ledger) {
+      const report = await this.#exportLedger(dir, table);
+      if (report) reports.push(report);
+    }
     return reports;
   }
 
+  async #exportLedger(dir: string, table: MigrationLedgerTable): Promise<TransferReport | null> {
+    let writer: Bun.FileSink | null = null;
+    let rows = 0;
+    let after: Record<string, unknown> | null = null;
+    for (;;) {
+      const chunk = await MigrationTables.exportRows(
+        this.#database.getConnection(),
+        table,
+        after,
+        DocumentTransfer.#chunk,
+      );
+      if (chunk.length) writer ??= Bun.file(path.join(dir, `${table.name}.ndjson`)).writer();
+      for (const row of chunk) writer?.write(`${JSON.stringify(row)}\n`);
+      rows += chunk.length;
+      const last = chunk.at(-1);
+      if (!last || chunk.length < DocumentTransfer.#chunk) break;
+      after = last;
+    }
+    await writer?.end();
+    return writer ? { table: table.name, rows } : null;
+  }
+
   async importFrom(dir: string): Promise<TransferReport[]> {
     const files = new Set((await readdir(dir)).filter((file) => file.endsWith(".ndjson")));
     const search = this.#database.getSearchIndex();
@@ -66,10 +94,32 @@ export class DocumentTransfer {
         this.#logger.warn(`Another process holds the search rebuild of ${store.table}; it catches up once that ends`);
       reports.push({ table: store.table, rows });
     }
+    for (const table of MigrationTables.ledger) {
+      const file = `${table.name}.ndjson`;
+      if (files.delete(file)) reports.push(await this.#importLedger(path.join(dir, file), table));
+    }
     for (const file of files) this.#logger.warn(`${file} matches no model of this app; skipped`);
     return reports;
   }
 
+  async #importLedger(file: string, table: MigrationLedgerTable): Promise<TransferReport> {
+    const write = async (chunk: Record<string, unknown>[]) =>
+      await this.#database.transaction(
+        async () => await MigrationTables.importRows(this.#database.getConnection(), table, chunk),
+      );
+    let rows = 0;
+    let chunk: Record<string, unknown>[] = [];
+    for await (const line of DocumentTransfer.#lines(file)) {
+      chunk.push(JSON.parse(line) as Record<string, unknown>);
+      if (chunk.length < DocumentTransfer.#chunk) continue;
+      await write(chunk);
+      rows += chunk.length;
+      chunk = [];
+    }
+    if (chunk.length) await write(chunk);
+    return { table: table.name, rows: rows + chunk.length };
+  }
+
   #stores() {
     const stores = this.#database.stores?.();
     if (!stores) throw new Error("This database adaptor keeps no model stores to transfer.");

package/service/predefinedAdaptor/endpointCacheControl.adaptor.ts

@@ -0,0 +1,19 @@
+import { adapt } from "../adapt";
+import { EndpointCacheKeys } from "../endpointCacheKeys";
+import { CacheAdaptorRole } from "./role.adaptor";
+
+/** Drops an endpoint's `{ cache }` answers before their TTL, across instances: every entry, or the one for `args`. */
+export class EndpointCacheControl extends adapt("endpointCacheControl", ({ plug }) => ({
+  cache: plug(CacheAdaptorRole),
+})) {
+  /** `args`: every declared argument in order, `null` for an omitted search one; not for slice lists. */
+  async invalidate(endpoint: string, args?: unknown[]): Promise<boolean> {
+    try {
+      await EndpointCacheKeys.invalidate(this.cache, endpoint, args);
+      return true;
+    } catch (error) {
+      this.logger.error(`Cache invalidation failed for ${endpoint}: ${String(error)}`);
+      return false;
+    }
+  }
+}

package/service/predefinedAdaptor/index.ts

@@ -3,6 +3,7 @@ export * from "./cache.adaptor";
 export * from "./compress.adaptor";
 export * from "./database.adaptor";
 export * from "./documentTransfer";
+export * from "./endpointCacheControl.adaptor";
 export * from "./insightQuery";
 export * from "./llm.adaptor";
 export * from "./llmOverflow";

package/service/predefinedAdaptor/llm.adaptor.ts

@@ -10,6 +10,8 @@ export interface AgentWireToolResult {
   result?: unknown;
   changes?: unknown[];
   error?: string;
+  /** Files the call handed the model, as content beside the JSON; one this model cannot read arrives as a `text` note. */
+  attachments?: AgentWireAttachment[];
 }
 
 /** Exactly one carrier reaches the model: `data` (inlined bytes), `url` (fetched by the provider) or `text`. */
@@ -68,6 +70,11 @@ export interface LlmTurnRequest {
   tools: AgentWireTool[];
   context: AgentWireContext[];
   instructions?: string;
+  /**
+   * This turn's model in place of `LlmOption.model`. `accepts`, `maxTokens` and `contextWindow` stay the option's, so a
+   * model that differs in them needs an adaptor of its own. Set by server code only: `runAgentTurn` takes no model.
+   */
+  model?: string;
 }
 
 export interface LlmTurnAnswer {

package/service/predefinedAdaptor/openaiDialect.ts

@@ -1,4 +1,11 @@
-import type { AgentWireMessage, LlmAccepts, LlmTurnAnswer, LlmTurnRequest, LlmUsage } from "./llm.adaptor";
+import type {
+  AgentWireAttachment,
+  AgentWireMessage,
+  LlmAccepts,
+  LlmTurnAnswer,
+  LlmTurnRequest,
+  LlmUsage,
+} from "./llm.adaptor";
 import { eachSseData } from "./sseData";
 
 export interface OpenaiToolCall {
@@ -25,7 +32,8 @@ interface OpenaiStreamChunk {
     finish_reason?: string | null;
   }[];
 }
-type OpenaiContentPart = { type: "text"; text: string } | { type: "image_url"; image_url: { url: string } };
+type OpenaiImagePart = { type: "image_url"; image_url: { url: string } };
+type OpenaiContentPart = { type: "text"; text: string } | OpenaiImagePart;
 export interface OpenaiMessage {
   role: "system" | "user" | "assistant" | "tool";
   content: string | OpenaiContentPart[];
@@ -86,16 +94,7 @@ export class OpenaiDialect {
           content: `Summary of the earlier conversation, standing in for the messages it replaced:\n\n${message.text ?? ""}`,
         },
       ];
-    if (message.role === "tool")
-      return (message.toolResults ?? []).map((result) => ({
-        role: "tool" as const,
-        tool_call_id: result.id,
-        content: JSON.stringify({
-          ...(result.result !== undefined ? { result: result.result } : {}),
-          ...(result.changes?.length ? { changes: result.changes } : {}),
-          ...(result.error ? { error: result.error } : {}),
-        }),
-      }));
+    if (message.role === "tool") return OpenaiDialect.toolMessages(message, accepts);
     if (message.role === "assistant")
       return [
         {
@@ -116,8 +115,47 @@ export class OpenaiDialect {
   }
 
   static userContent(message: AgentWireMessage, accepts?: LlmAccepts): string | OpenaiContentPart[] {
-    const attachments = message.attachments ?? [];
     const notes: string[] = [];
+    const { blocks, images } = OpenaiDialect.attachmentParts(message.attachments ?? [], accepts, notes);
+    const text = [message.text, ...blocks, ...notes].filter(Boolean).join("\n\n");
+    if (!images.length) return text;
+    return [...(text ? [{ type: "text" as const, text }] : []), ...images.map(({ part }) => part)];
+  }
+
+  static readonly toolPicturesHeading =
+    "Pictures the tool calls above returned, each after the name of the call that returned it. They are content, not something the user said.";
+
+  /**
+   * A `tool` message carries text alone in this dialect, so the pictures a call returned follow every tool message
+   * of the turn in one user message: between two tool messages it would break the run each call's answer has to sit in.
+   */
+  static toolMessages(message: AgentWireMessage, accepts?: LlmAccepts): OpenaiMessage[] {
+    const shown: OpenaiContentPart[] = [];
+    const answers = (message.toolResults ?? []).map((result): OpenaiMessage => {
+      const payload = JSON.stringify({
+        ...(result.result !== undefined ? { result: result.result } : {}),
+        ...(result.changes?.length ? { changes: result.changes } : {}),
+        ...(result.error ? { error: result.error } : {}),
+      });
+      const notes: string[] = [];
+      const { blocks, images } = OpenaiDialect.attachmentParts(result.attachments ?? [], accepts, notes);
+      for (const { name, part } of images)
+        shown.push({ type: "text", text: `[${result.name} returned ${name}]` }, part);
+      return { role: "tool", tool_call_id: result.id, content: [payload, ...blocks, ...notes].join("\n\n") };
+    });
+    if (!shown.length) return answers;
+    return [
+      ...answers,
+      { role: "user", content: [{ type: "text", text: OpenaiDialect.toolPicturesHeading }, ...shown] },
+    ];
+  }
+
+  /** Pushes a note for each file no part can carry, for the caller to fold into the text beside them. */
+  static attachmentParts(
+    attachments: AgentWireAttachment[],
+    accepts: LlmAccepts | undefined,
+    notes: string[],
+  ): { blocks: string[]; images: { name: string; part: OpenaiImagePart }[] } {
     
     const blocks = attachments.flatMap((attachment) =>
       attachment.text ? [`--- attachment: ${attachment.name} (${attachment.mimeType}) ---\n${attachment.text}`] : [],
@@ -138,11 +176,9 @@ export class OpenaiDialect {
           }
           
           const url = attachment.data ? `data:${mimeType};base64,${attachment.data}` : (attachment.url ?? "");
-          return url ? [{ type: "image_url" as const, image_url: { url } }] : [];
+          return url ? [{ name: attachment.name, part: { type: "image_url" as const, image_url: { url } } }] : [];
         });
-    const text = [message.text, ...blocks, ...notes].filter(Boolean).join("\n\n");
-    if (!images.length) return text;
-    return [...(text ? [{ type: "text" as const, text }] : []), ...images];
+    return { blocks, images };
   }
 
   static async consumeStream(

package/service/predefinedAdaptor/openaiLlm.ts

@@ -31,7 +31,7 @@ export class OpenaiLlm
   }
 
   async chat(request: LlmTurnRequest, onDelta?: (delta: string) => void): Promise<LlmTurnAnswer | null> {
-    const model = this.llmOption.model;
+    const model = request.model || this.llmOption.model;
     if (!this.llmOption.apiKey || !model) {
       this.logger.warn(
         "OpenaiLlm needs both apiKey and model — set them with option.setLlm(). Agent turns are unavailable.",

package/service/predefinedAdaptor/sql/MigrationTables.ts

@@ -0,0 +1,90 @@
+import type { AkanSqlClient, SqlDialect } from "./types";
+import { quoteIdent } from "./values";
+
+export interface MigrationLedgerTable {
+  name: string;
+  key: readonly string[];
+  columns: readonly string[];
+}
+
+/** The data-migration ledger, kept beside the rows it describes so each environment records what was applied to it. */
+export class MigrationTables {
+  static readonly run = "_akan_migration_run";
+  static readonly change = "_akan_migration_change";
+  static readonly ledger: readonly MigrationLedgerTable[] = [
+    {
+      name: MigrationTables.run,
+      key: ["id"],
+      columns: [
+        "id",
+        "migrationId",
+        "kind",
+        "status",
+        "target",
+        "checksum",
+        "buildId",
+        "params",
+        "planHash",
+        "summary",
+        "actor",
+        "checkpoint",
+        "startedAt",
+        "finishedAt",
+        "error",
+      ],
+    },
+    {
+      name: MigrationTables.change,
+      key: ["runId", "seq"],
+      columns: ["runId", "seq", "tableName", "docId", "op", "before", "after"],
+    },
+  ];
+
+  static schema(dialect: Pick<SqlDialect, "timestampType">) {
+    const ts = dialect.timestampType();
+    const run = quoteIdent(MigrationTables.run);
+    return [
+      `CREATE TABLE IF NOT EXISTS ${run} ("id" TEXT PRIMARY KEY NOT NULL, "migrationId" TEXT NOT NULL, "kind" TEXT NOT NULL, "status" TEXT NOT NULL, "target" TEXT, "checksum" TEXT NOT NULL, "buildId" TEXT, "params" TEXT, "planHash" TEXT, "summary" TEXT, "actor" TEXT, "checkpoint" TEXT, "startedAt" ${ts} NOT NULL, "finishedAt" ${ts}, "error" TEXT)`,
+      `CREATE INDEX IF NOT EXISTS ${quoteIdent(`${MigrationTables.run}_migrationId`)} ON ${run} ("migrationId", "startedAt")`,
+      `CREATE TABLE IF NOT EXISTS ${quoteIdent(MigrationTables.change)} ("runId" TEXT NOT NULL, "seq" INTEGER NOT NULL, "tableName" TEXT NOT NULL, "docId" TEXT NOT NULL, "op" TEXT NOT NULL, "before" TEXT NOT NULL, "after" TEXT NOT NULL, PRIMARY KEY ("runId", "seq"))`,
+    ];
+  }
+
+  /** Up to `limit` rows after the key of `after`, in key order. */
+  static async exportRows(
+    client: AkanSqlClient,
+    table: MigrationLedgerTable,
+    after: Record<string, unknown> | null,
+    limit: number,
+  ) {
+    const keyset = MigrationTables.#after(table, after);
+    return await client
+      .prepare(
+        `SELECT ${table.columns.map(quoteIdent).join(", ")} FROM ${quoteIdent(table.name)} WHERE ${keyset.sql} ORDER BY ${table.key.map(quoteIdent).join(", ")} LIMIT ${Math.trunc(limit)}`,
+      )
+      .all<Record<string, unknown>>(...keyset.params);
+  }
+
+  static async importRows(client: AkanSqlClient, table: MigrationLedgerTable, rows: Record<string, unknown>[]) {
+    const columns = table.columns.map(quoteIdent);
+    const updates = table.columns
+      .filter((column) => !table.key.includes(column))
+      .map((column) => `${quoteIdent(column)} = excluded.${quoteIdent(column)}`);
+    const statement = client.prepare(
+      `INSERT INTO ${quoteIdent(table.name)} (${columns.join(", ")}) VALUES (${columns.map(() => "?").join(", ")}) ON CONFLICT (${table.key.map(quoteIdent).join(", ")}) DO UPDATE SET ${updates.join(", ")}`,
+    );
+    for (const row of rows) await statement.run(...table.columns.map((column) => row[column] ?? null));
+  }
+
+  static #after(table: MigrationLedgerTable, after: Record<string, unknown> | null) {
+    if (!after) return { sql: "1 = 1", params: [] as unknown[] };
+    const terms = table.key.map((column, idx) => {
+      const equal = table.key.slice(0, idx);
+      return {
+        sql: `(${[...equal.map((prefix) => `${quoteIdent(prefix)} = ?`), `${quoteIdent(column)} > ?`].join(" AND ")})`,
+        params: [...equal.map((prefix) => after[prefix]), after[column]],
+      };
+    });
+    return { sql: `(${terms.map((term) => term.sql).join(" OR ")})`, params: terms.flatMap((term) => term.params) };
+  }
+}