@aigne/afs 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 1.0.0 (2025-10-07)
+
+
+### Features
+
+* **afs:** add basic AFS(AIGNE File System) support ([#505](https://github.com/AIGNE-io/aigne-framework/issues/505)) ([ac2a18a](https://github.com/AIGNE-io/aigne-framework/commit/ac2a18a82470a2f31c466f329386525eb1cdab6d))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @aigne/sqlite bumped to 0.4.3-beta

package/LICENSE.md

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/lib/cjs/afs.d.ts

@@ -0,0 +1,26 @@
+import { Emitter } from "strict-event-emitter";
+import { SharedAFSStorage, type SharedAFSStorageOptions } from "./storage/index.js";
+import type { AFSStorage } from "./storage/type.js";
+import type { AFSEntry, AFSListOptions, AFSModule, AFSRoot, AFSRootEvents, AFSSearchOptions, AFSWriteEntryPayload } from "./type.js";
+export interface AFSOptions {
+    storage?: SharedAFSStorage | SharedAFSStorageOptions;
+}
+export declare class AFS extends Emitter<AFSRootEvents> implements AFSRoot {
+    moduleId: string;
+    path: string;
+    constructor(options?: AFSOptions);
+    private _storage;
+    storage(module: AFSModule): AFSStorage;
+    private modules;
+    use(module: AFSModule): this;
+    list(path: string, options?: AFSListOptions): Promise<{
+        list: AFSEntry[];
+    }>;
+    private findModules;
+    private isSubpath;
+    read(path: string): Promise<AFSEntry | undefined>;
+    write(path: string, content: AFSWriteEntryPayload): Promise<AFSEntry>;
+    search(path: string, query: string, options?: AFSSearchOptions): Promise<{
+        list: AFSEntry[];
+    }>;
+}

package/lib/cjs/afs.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AFS = void 0;
+const strict_event_emitter_1 = require("strict-event-emitter");
+const ufo_1 = require("ufo");
+const index_js_1 = require("./history/index.js");
+const index_js_2 = require("./storage/index.js");
+const DEFAULT_MAX_DEPTH = 5;
+class AFS extends strict_event_emitter_1.Emitter {
+    moduleId = "AFSRoot";
+    path = "/";
+    constructor(options) {
+        super();
+        this._storage =
+            options?.storage instanceof index_js_2.SharedAFSStorage
+                ? options.storage
+                : new index_js_2.SharedAFSStorage(options?.storage);
+        this.use(new index_js_1.AFSHistory());
+    }
+    _storage;
+    storage(module) {
+        return this._storage.withModule(module);
+    }
+    modules = new Map();
+    use(module) {
+        this.modules.set(module.path, module);
+        module.onMount?.(this);
+        return this;
+    }
+    async list(path, options) {
+        const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
+        if (!(maxDepth >= 0))
+            throw new Error(`Invalid maxDepth: ${maxDepth}`);
+        const results = [];
+        const modules = this.findModules(path);
+        for (const { module, subpath, mountPath } of modules) {
+            if (!module.list)
+                continue;
+            try {
+                const newMaxDepth = maxDepth - mountPath.split("/").filter(Boolean).length;
+                if (newMaxDepth < 0)
+                    continue;
+                const { list } = await module.list(subpath, { ...options, maxDepth: newMaxDepth });
+                results.push(...list.map((entry) => ({
+                    ...entry,
+                    path: (0, ufo_1.joinURL)(mountPath, entry.path),
+                })));
+            }
+            catch (error) {
+                console.error(`Error listing from module at ${mountPath}`, error);
+            }
+        }
+        return { list: results };
+    }
+    findModules(fullPath) {
+        const modules = [];
+        for (const [mountPath, module] of this.modules) {
+            const match = this.isSubpath(fullPath, mountPath);
+            if (!match)
+                continue;
+            modules.push({ ...match, module, mountPath });
+        }
+        return modules.sort((a, b) => b.matchedDepth - a.matchedDepth);
+    }
+    isSubpath(fullPath, mountPath) {
+        const fullPathSegments = fullPath.split("/").filter(Boolean);
+        const mountPathSegments = mountPath.split("/").filter(Boolean);
+        const fp = fullPathSegments.join("/");
+        const mp = mountPathSegments.join("/");
+        if (fp.startsWith(mp)) {
+            return {
+                matchedDepth: mountPathSegments.length,
+                subpath: (0, ufo_1.joinURL)("/", ...fullPathSegments.slice(mountPathSegments.length)),
+            };
+        }
+        else if (mp.startsWith(fp)) {
+            return {
+                matchedDepth: fullPathSegments.length,
+                subpath: (0, ufo_1.joinURL)("/", ...mountPathSegments.slice(fullPathSegments.length)),
+            };
+        }
+    }
+    async read(path) {
+        const modules = this.findModules(path);
+        for (const { module, mountPath, subpath } of modules) {
+            const entry = await module.read?.(subpath);
+            if (entry) {
+                return {
+                    ...entry,
+                    path: (0, ufo_1.joinURL)(mountPath, entry.path),
+                };
+            }
+        }
+    }
+    async write(path, content) {
+        const module = this.findModules(path)[0];
+        if (!module?.module.write)
+            throw new Error(`No module found for path: ${path}`);
+        const entry = await module.module.write(module.subpath, content);
+        return {
+            ...entry,
+            path: (0, ufo_1.joinURL)(module.mountPath, entry.path),
+        };
+    }
+    async search(path, query, options) {
+        const results = [];
+        for (const { module, mountPath, subpath } of this.findModules(path)) {
+            if (mountPath.startsWith(path)) {
+                if (!module.search)
+                    continue;
+                try {
+                    const { list } = await module.search(subpath, query, options);
+                    results.push(...list.map((entry) => ({
+                        ...entry,
+                        path: (0, ufo_1.joinURL)(mountPath, entry.path),
+                    })));
+                }
+                catch (error) {
+                    console.error(`Error searching in module at ${mountPath}`, error);
+                }
+            }
+        }
+        return { list: results };
+    }
+}
+exports.AFS = AFS;

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

@@ -0,0 +1,14 @@
+import type { AFSEntry, AFSListOptions, AFSModule, AFSRoot, AFSWriteEntryPayload } from "../type.js";
+export declare class AFSHistory implements AFSModule {
+    static Path: string;
+    path: string;
+    moduleId: string;
+    private _afs?;
+    get afs(): AFSRoot;
+    onMount(afs: AFSRoot): void;
+    list(path: string, options?: AFSListOptions): Promise<{
+        list: AFSEntry[];
+    }>;
+    read(path: string): Promise<AFSEntry | undefined>;
+    write(path: string, content: AFSWriteEntryPayload): Promise<AFSEntry>;
+}

package/lib/cjs/history/index.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AFSHistory = void 0;
+const uuid_1 = require("@aigne/uuid");
+const ufo_1 = require("ufo");
+class AFSHistory {
+    static Path = "/history";
+    path = AFSHistory.Path;
+    moduleId = "AFSHistory";
+    _afs;
+    get afs() {
+        if (!this._afs)
+            throw new Error("AFSHistory module is not mounted");
+        return this._afs;
+    }
+    onMount(afs) {
+        this._afs = afs;
+        afs.on("agentSucceed", ({ input, output }) => {
+            this.afs
+                .storage(this)
+                .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);
+            });
+        });
+    }
+    async list(path, options) {
+        if (path !== "/")
+            return { list: [] };
+        return this.afs.storage(this).list(options);
+    }
+    async read(path) {
+        return this.afs.storage(this).read(path);
+    }
+    async write(path, content) {
+        return this.afs.storage(this).create({ ...content, path });
+    }
+}
+exports.AFSHistory = AFSHistory;

package/lib/cjs/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./afs.js";
+export * from "./history/index.js";
+export * from "./storage/index.js";
+export * from "./type.js";

package/lib/cjs/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./afs.js"), exports);
+__exportStar(require("./history/index.js"), exports);
+__exportStar(require("./storage/index.js"), exports);
+__exportStar(require("./type.js"), exports);

package/lib/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

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

@@ -0,0 +1,24 @@
+import { initDatabase } from "@aigne/sqlite";
+import type { AFSEntry, AFSModule } from "../type.js";
+import { entriesTable } from "./models/entries.js";
+import type { AFSStorage, AFSStorageCreatePayload, AFSStorageListOptions } from "./type.js";
+export interface SharedAFSStorageOptions {
+    url?: string;
+}
+export declare class SharedAFSStorage {
+    options?: SharedAFSStorageOptions | undefined;
+    constructor(options?: SharedAFSStorageOptions | undefined);
+    private _db;
+    get db(): Promise<import("drizzle-orm/libsql/driver-core.js").LibSQLDatabase<Record<string, never>> | import("drizzle-orm/sqlite-proxy/driver.js").SqliteRemoteDatabase<Record<string, never>>>;
+    withModule(module: AFSModule): AFSStorage;
+}
+export declare class AFSStorageWithModule implements AFSStorage {
+    private db;
+    private table;
+    constructor(db: ReturnType<typeof initDatabase>, table: Promise<ReturnType<typeof entriesTable>>);
+    list(options?: AFSStorageListOptions): Promise<{
+        list: AFSEntry[];
+    }>;
+    read(path: string): Promise<AFSEntry | undefined>;
+    create(entry: AFSStorageCreatePayload): Promise<AFSEntry>;
+}

package/lib/cjs/storage/index.js

@@ -0,0 +1,72 @@
+"use strict";
+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 entries_js_1 = require("./models/entries.js");
+const DEFAULT_AFS_STORAGE_LIST_LIMIT = 10;
+class SharedAFSStorage {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    _db;
+    get db() {
+        this._db ??= (0, sqlite_1.initDatabase)({ url: this.options?.url });
+        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)));
+    }
+}
+exports.SharedAFSStorage = SharedAFSStorage;
+class AFSStorageWithModule {
+    db;
+    table;
+    constructor(db, table) {
+        this.db = db;
+        this.table = table;
+    }
+    async list(options = {}) {
+        const { filter, limit = DEFAULT_AFS_STORAGE_LIST_LIMIT } = options;
+        const db = await this.db;
+        const table = await this.table;
+        const list = 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))
+            .orderBy(...(options.orderBy ?? []).map((item) => (item[1] === "asc" ? sqlite_1.asc : sqlite_1.desc)(sqlite_1.sql.identifier(item[0]))))
+            .limit(limit)
+            .execute();
+        return { list };
+    }
+    async read(path) {
+        const db = await this.db;
+        const table = await this.table;
+        return db
+            .select()
+            .from(table)
+            .where((0, sqlite_1.eq)(table.path, path))
+            .limit(1)
+            .execute()
+            .then((memory) => memory.at(0));
+    }
+    async create(entry) {
+        const db = await this.db;
+        const table = await this.table;
+        let result = await db
+            .update(table)
+            .set(entry)
+            .where((0, sqlite_1.eq)(table.path, entry.path))
+            .returning()
+            .execute();
+        if (!result.length) {
+            result = await db.insert(table).values(entry).returning().execute();
+        }
+        const [res] = result;
+        if (!res)
+            throw new Error("Failed to create AFS entry, no result");
+        return res;
+    }
+}
+exports.AFSStorageWithModule = AFSStorageWithModule;

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

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

package/lib/cjs/storage/migrate.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+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");
+async function migrate(db, module) {
+    const migrations = [_001_init_js_1.init];
+    const migrationsTable = "__drizzle_migrations";
+    const migrationTableCreate = (0, sqlite_1.sql) `
+    CREATE TABLE IF NOT EXISTS ${sqlite_1.sql.identifier(migrationsTable)} (
+      "id" SERIAL PRIMARY KEY,
+      "moduleId" TEXT NOT NULL,
+      "hash" TEXT NOT NULL
+    )
+  `;
+    await (await db).run(migrationTableCreate).execute();
+    const dbMigrations = await (await db)
+        .values((0, sqlite_1.sql) `SELECT "id", "moduleId", "hash" FROM ${sqlite_1.sql.identifier(migrationsTable)} WHERE "moduleId" = ${sqlite_1.sql.param(module.moduleId)} ORDER BY id DESC LIMIT 1`)
+        .execute();
+    const lastDbMigration = dbMigrations[0];
+    const queriesToRun = [];
+    for (const migration of migrations) {
+        if (!lastDbMigration || lastDbMigration[1] < 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.moduleId)}, ${sqlite_1.sql.param(migration.hash)})`);
+        }
+    }
+    for (const query of queriesToRun) {
+        await (await db).run(query).execute();
+    }
+}

package/lib/cjs/storage/migrations/001-init.d.ts

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

package/lib/cjs/storage/migrations/001-init.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.init = void 0;
+const sqlite_1 = require("@aigne/sqlite");
+const entries_js_1 = require("../models/entries.js");
+exports.init = {
+    hash: "001-init",
+    sql: (module) => [
+        (0, sqlite_1.sql) `\
+CREATE TABLE ${sqlite_1.sql.identifier((0, entries_js_1.entriesTableName)(module))} (
+  "id" TEXT NOT NULL PRIMARY KEY,
+  "createdAt" DATETIME NOT NULL,
+  "updatedAt" DATETIME NOT NULL,
+  "path" TEXT NOT NULL,
+  "userId" TEXT,
+  "sessionId" TEXT,
+  "summary" TEXT,
+  "metadata" JSON,
+  "linkTo" TEXT,
+  "content" JSON,
+  UNIQUE (path)
+)
+`,
+    ],
+};