@aigne/afs-history 1.2.0-beta.3 → 1.2.0-beta.5

package/CHANGELOG.md

@@ -6,6 +6,34 @@
   * dependencies
     * @aigne/afs bumped to 1.2.0
 
+## [1.2.0-beta.5](https://github.com/AIGNE-io/aigne-framework/compare/afs-history-v1.2.0-beta.4...afs-history-v1.2.0-beta.5) (2025-12-31)
+
+
+### Features
+
+* add session compact support for AIAgent ([#863](https://github.com/AIGNE-io/aigne-framework/issues/863)) ([9010918](https://github.com/AIGNE-io/aigne-framework/commit/9010918cd3f18b02b5c60ddc9ed5c34b568d0b28))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/afs bumped to 1.4.0-beta.5
+
+## [1.2.0-beta.4](https://github.com/AIGNE-io/aigne-framework/compare/afs-history-v1.2.0-beta.3...afs-history-v1.2.0-beta.4) (2025-12-26)
+
+
+### Features
+
+* **core:** add session history support ([#858](https://github.com/AIGNE-io/aigne-framework/issues/858)) ([28a070e](https://github.com/AIGNE-io/aigne-framework/commit/28a070ed33b821d1fd344b899706d817ca992b9f))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/afs bumped to 1.4.0-beta.4
+
 ## [1.2.0-beta.3](https://github.com/AIGNE-io/aigne-framework/compare/afs-history-v1.2.0-beta.2...afs-history-v1.2.0-beta.3) (2025-12-24)
 
 

package/lib/cjs/index.d.ts

@@ -1,4 +1,4 @@
-import type { AFSListOptions, AFSListResult, AFSModule, AFSReadResult, AFSRoot, AFSWriteEntryPayload, AFSWriteResult } from "@aigne/afs";
+import type { AFSListOptions, AFSListResult, AFSModule, AFSReadOptions, AFSReadResult, AFSRoot, AFSWriteEntryPayload, AFSWriteResult } from "@aigne/afs";
 import { SharedAFSStorage, type SharedAFSStorageOptions } from "./storage/index.js";
 export * from "./storage/index.js";
 export interface AFSHistoryOptions {
@@ -6,10 +6,15 @@ export interface AFSHistoryOptions {
 }
 export declare class AFSHistory implements AFSModule {
     constructor(options?: AFSHistoryOptions);
-    private storage;
     readonly name: string;
+    private storage;
+    private afs?;
+    private router;
+    private rootEntries;
     onMount(afs: AFSRoot): void;
     list(path: string, options?: AFSListOptions): Promise<AFSListResult>;
-    read(path: string): Promise<AFSReadResult>;
+    read(path: string, options?: AFSReadOptions): Promise<AFSReadResult>;
     write(path: string, content: AFSWriteEntryPayload): Promise<AFSWriteResult>;
+    private getCompactType;
+    private normalizePath;
 }

package/lib/cjs/index.js

@@ -16,6 +16,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AFSHistory = void 0;
 const uuid_1 = require("@aigne/uuid");
+const radix3_1 = require("radix3");
 const ufo_1 = require("ufo");
 const index_js_1 = require("./storage/index.js");
 __exportStar(require("./storage/index.js"), exports);
@@ -26,35 +27,206 @@ class AFSHistory {
                 ? options.storage.withModule(this)
                 : new index_js_1.SharedAFSStorage(options?.storage).withModule(this);
     }
-    storage;
     name = "history";
+    storage;
+    afs;
+    router = (0, radix3_1.createRouter)({
+        routes: {
+            "/new": { type: "root", id: "new-history" },
+            "/by-session": { type: "root", id: "by-session" },
+            "/by-session/:sessionId": { type: "list", id: "by-session" },
+            "/by-session/:sessionId/@metadata/compact": { type: "compact-list", id: "by-session" },
+            "/by-session/:sessionId/@metadata/compact/new": { type: "compact-new", id: "by-session" },
+            "/by-session/:sessionId/@metadata/compact/:compactId": {
+                type: "compact-detail",
+                id: "by-session",
+            },
+            "/by-session/:sessionId/:entryId": { type: "detail", id: "by-session" },
+            "/by-user": { type: "root", id: "by-user" },
+            "/by-user/:userId": { type: "list", id: "by-user" },
+            "/by-user/:userId/@metadata/compact": { type: "compact-list", id: "by-user" },
+            "/by-user/:userId/@metadata/compact/new": { type: "compact-new", id: "by-user" },
+            "/by-user/:userId/@metadata/compact/:compactId": { type: "compact-detail", id: "by-user" },
+            "/by-user/:userId/:entryId": { type: "detail", id: "by-user" },
+            "/by-agent": { type: "root", id: "by-agent" },
+            "/by-agent/:agentId": { type: "list", id: "by-agent" },
+            "/by-agent/:agentId/@metadata/compact": { type: "compact-list", id: "by-agent" },
+            "/by-agent/:agentId/@metadata/compact/new": { type: "compact-new", id: "by-agent" },
+            "/by-agent/:agentId/@metadata/compact/:compactId": { type: "compact-detail", id: "by-agent" },
+            "/by-agent/:agentId/:entryId": { type: "detail", id: "by-agent" },
+        },
+    });
+    rootEntries = [
+        {
+            id: "new-history",
+            path: "/new",
+            description: "Write to this path to create a new history entry, generating a UUID-based path.",
+        },
+        {
+            id: "by-session",
+            path: "/by-session",
+            description: "Retrieve history entries by session ID.",
+        },
+        {
+            id: "by-user",
+            path: "/by-user",
+            description: "Retrieve history entries by user ID.",
+        },
+        {
+            id: "by-agent",
+            path: "/by-agent",
+            description: "Retrieve history entries by agent ID.",
+        },
+    ];
     onMount(afs) {
-        afs.on("agentSucceed", ({ input, output }) => {
-            this.storage
-                .create({
-                path: (0, ufo_1.joinURL)("/", (0, uuid_1.v7)()),
-                content: { input, output },
-            })
-                .then((entry) => {
-                afs.emit("historyCreated", { entry });
-            })
-                .catch((error) => {
-                console.error("Failed to store history entry", error);
-            });
-        });
+        this.afs = afs;
     }
     async list(path, options) {
-        if (path !== "/")
+        if (path === "/")
+            return { data: this.rootEntries };
+        // Parse virtual path and extract filter conditions
+        const match = this.router.lookup(path);
+        // If path doesn't match any virtual path pattern, return empty
+        if (!match) {
             return { data: [] };
-        return await this.storage.list(options);
+        }
+        const rootEntry = this.rootEntries.find((entry) => entry.path === `/${match.id}`);
+        if (!rootEntry)
+            return { data: [] };
+        if (match.type === "root") {
+            return { data: [rootEntry] };
+        }
+        const matchId = match.id;
+        if (match.type === "list" &&
+            (matchId === "by-session" || matchId === "by-user" || matchId === "by-agent")) {
+            // Merge virtual path filter with explicit filter options
+            const mergedFilter = {
+                ...options?.filter,
+                ...match.params,
+            };
+            const result = await this.storage.list({
+                ...options,
+                filter: mergedFilter,
+            });
+            // Add virtual path prefix to each entry's path
+            return {
+                ...result,
+                data: result.data.map((entry) => ({
+                    ...entry,
+                    path: this.normalizePath(entry, matchId),
+                })),
+            };
+        }
+        if (match.type === "compact-list" &&
+            (matchId === "by-session" || matchId === "by-user" || matchId === "by-agent")) {
+            const compactType = this.getCompactType(matchId);
+            const mergedFilter = {
+                ...options?.filter,
+                ...match.params,
+            };
+            const result = await this.storage.listCompact(compactType, {
+                ...options,
+                filter: mergedFilter,
+            });
+            return { data: result.data };
+        }
+        return { data: [] };
     }
-    async read(path) {
-        const data = await this.storage.read(path);
-        return { data };
+    async read(path, options) {
+        // Parse virtual path and extract filter conditions
+        const match = this.router.lookup(path);
+        if (!match)
+            return {};
+        const rootEntry = this.rootEntries.find((entry) => entry.path === `/${match.id}`);
+        if (!rootEntry)
+            return {};
+        if (match.type === "root") {
+            return { data: rootEntry };
+        }
+        if (match.type === "detail" &&
+            (match.id === "by-session" || match.id === "by-user" || match.id === "by-agent")) {
+            const entryId = match.params?.entryId;
+            if (!entryId)
+                throw new Error("Entry ID is required in the path to read detail.");
+            const data = await this.storage.read(entryId, {
+                filter: match.params,
+            });
+            return {
+                data: data && {
+                    ...data,
+                    path: this.normalizePath(data, match.id),
+                },
+            };
+        }
+        if (match.type === "compact-detail" &&
+            (match.id === "by-session" || match.id === "by-user" || match.id === "by-agent")) {
+            const compactId = match.params?.compactId;
+            if (!compactId)
+                throw new Error("Compact ID is required in the path to read compact detail.");
+            const compactType = this.getCompactType(match.id);
+            const mergedFilter = {
+                ...options?.filter,
+                ...match.params,
+            };
+            const data = await this.storage.readCompact(compactType, compactId, {
+                filter: mergedFilter,
+            });
+            return { data };
+        }
+        return {};
     }
     async write(path, content) {
-        const data = await this.storage.create({ ...content, path });
-        return { data };
+        const id = (0, uuid_1.v7)();
+        const match = this.router.lookup(path);
+        if (match?.type === "compact-new") {
+            const compactType = this.getCompactType(match.id);
+            const entry = await this.storage.createCompact(compactType, {
+                ...match.params,
+                ...content,
+                id,
+                path: (0, ufo_1.joinURL)("/", compactType, id),
+            });
+            return { data: entry };
+        }
+        if (match?.id !== "new-history") {
+            throw new Error("Can only write to /new or @metadata/compact/new paths.");
+        }
+        if (!content.sessionId)
+            throw new Error("sessionId is required to create a history entry.");
+        const entry = await this.storage.create({
+            ...content,
+            id,
+            path: (0, ufo_1.joinURL)("/", id),
+        });
+        this.afs?.emit("historyCreated", { entry });
+        return {
+            data: {
+                ...entry,
+                path: this.normalizePath(entry, "by-session"),
+            },
+        };
+    }
+    getCompactType(id) {
+        const mapping = {
+            "by-session": "session",
+            "by-user": "user",
+            "by-agent": "agent",
+        };
+        const type = mapping[id];
+        if (!type)
+            throw new Error(`Invalid compact type for id: ${id}`);
+        return type;
+    }
+    normalizePath(entry, type) {
+        const [prefix, scopeId] = {
+            "by-session": ["by-session", entry.sessionId],
+            "by-user": ["by-user", entry.userId],
+            "by-agent": ["by-agent", entry.agentId],
+        }[type] || [];
+        if (!prefix || !scopeId) {
+            throw new Error(`Cannot reset path for entry without ${type} info.`);
+        }
+        return (0, ufo_1.joinURL)("/", prefix, scopeId, entry.id);
     }
 }
 exports.AFSHistory = AFSHistory;

package/lib/cjs/storage/index.d.ts

@@ -1,7 +1,6 @@
 import type { AFSEntry, AFSModule } from "@aigne/afs";
 import { initDatabase } from "@aigne/sqlite";
-import { entriesTable } from "./models/entries.js";
-import type { AFSStorage, AFSStorageCreatePayload, AFSStorageListOptions } from "./type.js";
+import type { AFSStorage, AFSStorageCreatePayload, AFSStorageListOptions, AFSStorageReadOptions, CompactType } from "./type.js";
 export * from "./type.js";
 export interface SharedAFSStorageOptions {
     url?: string;
@@ -15,11 +14,18 @@ export declare class SharedAFSStorage {
 }
 export declare class AFSStorageWithModule implements AFSStorage {
     private db;
-    private table;
-    constructor(db: ReturnType<typeof initDatabase>, table: Promise<ReturnType<typeof entriesTable>>);
+    private module;
+    constructor(db: ReturnType<typeof initDatabase>, module: AFSModule);
+    private _tables?;
+    private get tables();
     list(options?: AFSStorageListOptions): Promise<{
         data: AFSEntry[];
     }>;
-    read(path: string): Promise<AFSEntry | undefined>;
+    read(id: string, options?: AFSStorageReadOptions): Promise<AFSEntry | undefined>;
     create(entry: AFSStorageCreatePayload): Promise<AFSEntry>;
+    createCompact(type: CompactType, entry: AFSStorageCreatePayload): Promise<AFSEntry>;
+    listCompact(type: CompactType, options?: AFSStorageListOptions): Promise<{
+        data: AFSEntry[];
+    }>;
+    readCompact(type: CompactType, id: string, options?: AFSStorageReadOptions): Promise<AFSEntry | undefined>;
 }

package/lib/cjs/storage/index.js

@@ -17,6 +17,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AFSStorageWithModule = exports.SharedAFSStorage = void 0;
 const sqlite_1 = require("@aigne/sqlite");
 const migrate_js_1 = require("./migrate.js");
+const compact_js_1 = require("./models/compact.js");
 const entries_js_1 = require("./models/entries.js");
 __exportStar(require("./type.js"), exports);
 const DEFAULT_AFS_STORAGE_LIST_LIMIT = 10;
@@ -31,57 +32,105 @@ class SharedAFSStorage {
         return this._db;
     }
     withModule(module) {
-        return new AFSStorageWithModule(this.db, (0, migrate_js_1.migrate)(this.db, module).then(() => (0, entries_js_1.entriesTable)(module)));
+        return new AFSStorageWithModule(this.db, module);
     }
 }
 exports.SharedAFSStorage = SharedAFSStorage;
 class AFSStorageWithModule {
     db;
-    table;
-    constructor(db, table) {
+    module;
+    constructor(db, module) {
         this.db = db;
-        this.table = table;
+        this.module = module;
+    }
+    _tables;
+    get tables() {
+        if (!this._tables) {
+            this._tables = this.db.then((db) => (0, migrate_js_1.migrate)(db, this.module).then(() => ({
+                db,
+                entries: (0, entries_js_1.entriesTable)(this.module),
+                compact: (0, compact_js_1.compactTable)(this.module),
+            })));
+        }
+        return this._tables;
     }
     async list(options = {}) {
         const { filter, limit = DEFAULT_AFS_STORAGE_LIST_LIMIT } = options;
-        const db = await this.db;
-        const table = await this.table;
+        const { db, entries } = await this.tables;
         const data = await db
             .select()
-            .from(table)
-            .where((0, sqlite_1.and)(filter?.userId ? (0, sqlite_1.eq)(table.userId, filter.userId) : undefined, filter?.sessionId ? (0, sqlite_1.eq)(table.sessionId, filter.sessionId) : undefined))
+            .from(entries)
+            .where((0, sqlite_1.and)(filter?.agentId ? (0, sqlite_1.eq)(entries.agentId, filter.agentId) : undefined, filter?.userId ? (0, sqlite_1.eq)(entries.userId, filter.userId) : undefined, filter?.sessionId ? (0, sqlite_1.eq)(entries.sessionId, filter.sessionId) : undefined, filter?.before ? (0, sqlite_1.lt)(entries.createdAt, new Date(filter.before)) : undefined, filter?.after ? (0, sqlite_1.gt)(entries.createdAt, new Date(filter.after)) : undefined))
             .orderBy(...(options.orderBy ?? []).map((item) => (item[1] === "asc" ? sqlite_1.asc : sqlite_1.desc)(sqlite_1.sql.identifier(item[0]))))
             .limit(limit)
             .execute();
         return { data };
     }
-    async read(path) {
-        const db = await this.db;
-        const table = await this.table;
+    async read(id, options) {
+        const { db, entries } = await this.tables;
         return db
             .select()
-            .from(table)
-            .where((0, sqlite_1.eq)(table.path, path))
+            .from(entries)
+            .where((0, sqlite_1.and)((0, sqlite_1.eq)(entries.id, id), options?.filter?.agentId ? (0, sqlite_1.eq)(entries.agentId, options.filter.agentId) : undefined, options?.filter?.userId ? (0, sqlite_1.eq)(entries.userId, options.filter.userId) : undefined, options?.filter?.sessionId ? (0, sqlite_1.eq)(entries.sessionId, options.filter.sessionId) : undefined))
             .limit(1)
             .execute()
             .then((memory) => memory.at(0));
     }
     async create(entry) {
-        const db = await this.db;
-        const table = await this.table;
+        const { db, entries } = await this.tables;
         let result = await db
-            .update(table)
+            .update(entries)
             .set(entry)
-            .where((0, sqlite_1.eq)(table.path, entry.path))
+            .where((0, sqlite_1.eq)(entries.id, entry.id))
             .returning()
             .execute();
         if (!result.length) {
-            result = await db.insert(table).values(entry).returning().execute();
+            result = await db.insert(entries).values(entry).returning().execute();
         }
         const [res] = result;
         if (!res)
             throw new Error("Failed to create AFS entry, no result");
         return res;
     }
+    async createCompact(type, entry) {
+        const { db, compact } = await this.tables;
+        const result = await db
+            .insert(compact)
+            .values({
+            ...entry,
+            metadata: {
+                ...entry.metadata,
+                type,
+            },
+        })
+            .returning()
+            .execute();
+        const [res] = result;
+        if (!res)
+            throw new Error(`Failed to create ${type} compact entry, no result`);
+        return res;
+    }
+    async listCompact(type, options = {}) {
+        const { db, compact } = await this.tables;
+        const { filter, limit = DEFAULT_AFS_STORAGE_LIST_LIMIT } = options;
+        const data = await db
+            .select()
+            .from(compact)
+            .where((0, sqlite_1.and)((0, sqlite_1.eq)((0, sqlite_1.sql) `json_extract(${compact.metadata}, '$.type')`, type), filter?.agentId ? (0, sqlite_1.eq)(compact.agentId, filter.agentId) : undefined, filter?.userId ? (0, sqlite_1.eq)(compact.userId, filter.userId) : undefined, filter?.sessionId ? (0, sqlite_1.eq)(compact.sessionId, filter.sessionId) : undefined, filter?.before ? (0, sqlite_1.lt)(compact.createdAt, new Date(filter.before)) : undefined, filter?.after ? (0, sqlite_1.gt)(compact.createdAt, new Date(filter.after)) : undefined))
+            .orderBy(...(options.orderBy ?? []).map((item) => (item[1] === "asc" ? sqlite_1.asc : sqlite_1.desc)(sqlite_1.sql.identifier(item[0]))))
+            .limit(limit)
+            .execute();
+        return { data };
+    }
+    async readCompact(type, id, options) {
+        const { db, compact } = await this.tables;
+        return db
+            .select()
+            .from(compact)
+            .where((0, sqlite_1.and)((0, sqlite_1.eq)((0, sqlite_1.sql) `json_extract(${compact.metadata}, '$.type')`, type), (0, sqlite_1.eq)(compact.id, id), options?.filter?.agentId ? (0, sqlite_1.eq)(compact.agentId, options.filter.agentId) : undefined, options?.filter?.userId ? (0, sqlite_1.eq)(compact.userId, options.filter.userId) : undefined, options?.filter?.sessionId ? (0, sqlite_1.eq)(compact.sessionId, options.filter.sessionId) : undefined))
+            .limit(1)
+            .execute()
+            .then((rows) => rows.at(0));
+    }
 }
 exports.AFSStorageWithModule = AFSStorageWithModule;

package/lib/cjs/storage/migrate.d.ts

@@ -1,3 +1,3 @@
 import type { AFSModule } from "@aigne/afs";
 import { type initDatabase } from "@aigne/sqlite";
-export declare function migrate(db: ReturnType<typeof initDatabase>, module: AFSModule): Promise<void>;
+export declare function migrate(db: Awaited<ReturnType<typeof initDatabase>>, module: AFSModule): Promise<void>;

package/lib/cjs/storage/migrate.js

@@ -4,8 +4,10 @@ exports.migrate = migrate;
 const sqlite_1 = require("@aigne/sqlite");
 const uuid_1 = require("@aigne/uuid");
 const _001_init_js_1 = require("./migrations/001-init.js");
+const _002_add_agent_id_js_1 = require("./migrations/002-add-agent-id.js");
+const _003_add_compact_table_js_1 = require("./migrations/003-add-compact-table.js");
 async function migrate(db, module) {
-    const migrations = [_001_init_js_1.init];
+    const migrations = [_001_init_js_1.init, _002_add_agent_id_js_1.addAgentId, _003_add_compact_table_js_1.addCompactTable];
     const migrationsTable = "__drizzle_migrations";
     const migrationTableCreate = (0, sqlite_1.sql) `
     CREATE TABLE IF NOT EXISTS ${sqlite_1.sql.identifier(migrationsTable)} (
@@ -14,18 +16,18 @@ async function migrate(db, module) {
       "hash" TEXT NOT NULL
     )
   `;
-    await (await db).run(migrationTableCreate).execute();
-    const dbMigrations = await (await db)
+    await db.run(migrationTableCreate).execute();
+    const dbMigrations = await db
         .values((0, sqlite_1.sql) `SELECT "id", "moduleId", "hash" FROM ${sqlite_1.sql.identifier(migrationsTable)} WHERE "moduleId" = ${sqlite_1.sql.param(module.name)} ORDER BY id DESC LIMIT 1`)
         .execute();
     const lastDbMigration = dbMigrations[0];
     const queriesToRun = [];
     for (const migration of migrations) {
-        if (!lastDbMigration || lastDbMigration[1] < migration.hash) {
+        if (!lastDbMigration || lastDbMigration[2] < migration.hash) {
             queriesToRun.push(...migration.sql(module), (0, sqlite_1.sql) `INSERT INTO ${sqlite_1.sql.identifier(migrationsTable)} ("id", "moduleId", "hash") VALUES(${sqlite_1.sql.param((0, uuid_1.v7)())}, ${sqlite_1.sql.param(module.name)}, ${sqlite_1.sql.param(migration.hash)})`);
         }
     }
     for (const query of queriesToRun) {
-        await (await db).run(query).execute();
+        await db.run(query).execute();
     }
 }

package/lib/cjs/storage/migrations/002-add-agent-id.d.ts

@@ -0,0 +1,2 @@
+import type { AFSStorageMigrations } from "../type.js";
+export declare const addAgentId: AFSStorageMigrations;

package/lib/cjs/storage/migrations/002-add-agent-id.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addAgentId = void 0;
+const sqlite_1 = require("@aigne/sqlite");
+const entries_js_1 = require("../models/entries.js");
+exports.addAgentId = {
+    hash: "002-add-agent-id",
+    sql: (module) => [
+        (0, sqlite_1.sql) `\
+ALTER TABLE ${sqlite_1.sql.identifier((0, entries_js_1.entriesTableName)(module))} ADD COLUMN "agentId" TEXT;
+`,
+    ],
+};

package/lib/cjs/storage/migrations/003-add-compact-table.d.ts

@@ -0,0 +1,2 @@
+import type { AFSStorageMigrations } from "../type.js";
+export declare const addCompactTable: AFSStorageMigrations;

package/lib/cjs/storage/migrations/003-add-compact-table.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addCompactTable = void 0;
+const sqlite_1 = require("@aigne/sqlite");
+const compact_js_1 = require("../models/compact.js");
+exports.addCompactTable = {
+    hash: "003-add-compact-table",
+    sql: (module) => [
+        (0, sqlite_1.sql) `\
+CREATE TABLE IF NOT EXISTS ${sqlite_1.sql.identifier((0, compact_js_1.compactTableName)(module))} (
+  "id" TEXT NOT NULL PRIMARY KEY,
+  "createdAt" DATETIME NOT NULL,
+  "updatedAt" DATETIME NOT NULL,
+  "path" TEXT NOT NULL,
+  "sessionId" TEXT,
+  "userId" TEXT,
+  "agentId" TEXT,
+  "metadata" JSON,
+  "content" JSON
+)
+`,
+    ],
+};