@agentback/files 0.3.0

package/LICENSE

@@ -0,0 +1,33 @@
+Copyright (c) Ninemind.ai 2026.
+Node module: AgentBack
+This project is licensed under the MIT License, full text below.
+
+--------
+
+MIT License
+
+Copyright (c) Ninemind.ai 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and
+associated documentation files (the "Software"), to deal in the Software without
+restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished
+to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
+AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# @agentback/files
+
+> Transport-agnostic file storage: a `FileStore` port + an in-memory adapter.
+
+The storage seam behind AgentBack's first-class file upload/download. REST
+handlers never touch a storage SDK — they declare a `fileField()` on a route's
+body schema (uploads stream straight to the bound `FileStore`) and `return
+fileDownload(...)` (downloads stream back out). Bind any `FileStore`
+implementation at `FILE_STORE`; the [`@agentback/files-s3`](../files-s3) adapter
+is the production one.
+
+## The port
+
+```ts
+import {FILE_STORE, type FileStore} from '@agentback/files';
+
+interface FileStore {
+  put(key, body: Readable | Buffer, opts?): Promise<StoredFile>;
+  get(key): Promise<RetrievedFile>;       // throws FileNotFoundError if absent
+  exists(key): Promise<boolean>;
+  delete(key): Promise<void>;
+  presignedPut?(key, opts?): Promise<string>;  // optional (direct-to-storage)
+  presignedGet?(key, opts?): Promise<string>;  // optional
+}
+```
+
+Keys are **opaque and server-generated** — callers pass a UUID, never a
+client-controlled path. `get` throws `FileNotFoundError` (HTTP-free; the REST
+layer maps it to 404).
+
+## Flow
+
+```mermaid
+flowchart LR
+  C[client] -- multipart/form-data --> R[RestServer route]
+  R -- "fileField() → multipart parser" --> S[(FileStore.put<br/>UUID key)]
+  R --> H[handler: persist metadata]
+  C2[client] -- GET /files/id --> H2[handler]
+  H2 -- ownership check --> G[(FileStore.get)]
+  G -- fileDownload → pipe(res) --> C2
+```
+
+## Adapters
+
+- **`InMemoryFileStore`** (here) — buffers in a `Map`; tests/dev only.
+- **`FsFileStore`** (here) — local filesystem; streams to/from `<baseDir>/<key>`
+  with a metadata sidecar. Single-node / self-hosted / dev-with-persistence.
+- **`S3FileStore`** (`@agentback/files-s3`) — streams to S3 via AWS SDK v3.
+
+## Testing
+
+`@agentback/files/testing` exports `runFileStoreConformance(label, makeStore)`
+— the port contract as a reusable suite. Every adapter runs it:
+
+```ts
+import {runFileStoreConformance} from '@agentback/files/testing';
+runFileStoreConformance('MyStore', () => new MyStore());
+```
+
+See [`examples/hello-uploads`](../../examples/hello-uploads) for the end-to-end
+recipe (upload, list, owner-scoped download) and `@agentback/rest`'s
+`fileField` / `fileResponse` for the REST integration.

package/dist/__tests__/unit/fs-file-store.unit.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fs-file-store.unit.d.ts.map

package/dist/__tests__/unit/fs-file-store.unit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-file-store.unit.d.ts","sourceRoot":"","sources":["../../../src/__tests__/unit/fs-file-store.unit.ts"],"names":[],"mappings":""}

package/dist/__tests__/unit/fs-file-store.unit.js

@@ -0,0 +1,38 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+import { afterAll, describe, expect, it } from 'vitest';
+import { existsSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { FsFileStore } from '../../index.js';
+import { runFileStoreConformance } from '../../testing/conformance.js';
+const root = mkdtempSync(join(tmpdir(), 'agentback-fs-'));
+afterAll(() => rmSync(root, { recursive: true, force: true }));
+// Runs unconditionally (no external service needed) — unlike the S3 adapter.
+runFileStoreConformance('FsFileStore', () => new FsFileStore({ baseDir: root }));
+describe('FsFileStore specifics', () => {
+    it('writes the bytes to disk under baseDir', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'agentback-fs-spec-'));
+        const store = new FsFileStore({ baseDir: dir });
+        await store.put('k1', Buffer.from('on disk'), { contentType: 'text/plain' });
+        expect(existsSync(join(dir, 'k1'))).toBe(true);
+        expect(readFileSync(join(dir, 'k1'), 'utf8')).toBe('on disk');
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it('delete removes both the data and its metadata sidecar', async () => {
+        const dir = mkdtempSync(join(tmpdir(), 'agentback-fs-spec-'));
+        const store = new FsFileStore({ baseDir: dir });
+        await store.put('k2', Buffer.from('x'), { filename: 'x.bin' });
+        expect(existsSync(join(dir, 'k2.meta.json'))).toBe(true);
+        await store.delete('k2');
+        expect(existsSync(join(dir, 'k2'))).toBe(false);
+        expect(existsSync(join(dir, 'k2.meta.json'))).toBe(false);
+        rmSync(dir, { recursive: true, force: true });
+    });
+    it('rejects a key that escapes the base directory', async () => {
+        const store = new FsFileStore({ baseDir: root });
+        await expect(store.put('../escape', Buffer.from('no'))).rejects.toThrow(/escapes the base directory/);
+    });
+});
+//# sourceMappingURL=fs-file-store.unit.js.map

package/dist/__tests__/unit/fs-file-store.unit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-file-store.unit.js","sourceRoot":"","sources":["../../../src/__tests__/unit/fs-file-store.unit.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/unit/in-memory-file-store.unit.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=in-memory-file-store.unit.d.ts.map

package/dist/__tests__/unit/in-memory-file-store.unit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-file-store.unit.d.ts","sourceRoot":"","sources":["../../../src/__tests__/unit/in-memory-file-store.unit.ts"],"names":[],"mappings":""}

package/dist/__tests__/unit/in-memory-file-store.unit.js

@@ -0,0 +1,65 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+import { Readable } from 'node:stream';
+import { describe, it, expect, beforeEach } from 'vitest';
+import { InMemoryFileStore, FileNotFoundError } from '../../index.js';
+import { runFileStoreConformance } from '../../testing/conformance.js';
+runFileStoreConformance('InMemoryFileStore', () => new InMemoryFileStore());
+/** Drain a RetrievedFile's stream back to a Buffer for assertions. */
+async function drain(stream) {
+    const chunks = [];
+    for await (const c of stream)
+        chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c));
+    return Buffer.concat(chunks);
+}
+describe('InMemoryFileStore', () => {
+    let store;
+    beforeEach(() => {
+        store = new InMemoryFileStore();
+    });
+    it('round-trips a Buffer with its metadata', async () => {
+        const put = await store.put('k1', Buffer.from('hello'), {
+            contentType: 'text/plain',
+            filename: 'greeting.txt',
+            metadata: { owner: 'u1' },
+        });
+        expect(put).toEqual({ key: 'k1', size: 5, contentType: 'text/plain' });
+        const got = await store.get('k1');
+        expect(got.size).toBe(5);
+        expect(got.contentType).toBe('text/plain');
+        expect(got.filename).toBe('greeting.txt');
+        expect(got.metadata).toEqual({ owner: 'u1' });
+        expect((await drain(got.stream)).toString()).toBe('hello');
+    });
+    it('accepts a Readable body and reports the streamed size', async () => {
+        const body = Readable.from([Buffer.from('ab'), Buffer.from('cde')]);
+        const put = await store.put('k2', body);
+        expect(put.size).toBe(5);
+        expect((await drain((await store.get('k2')).stream)).toString()).toBe('abcde');
+    });
+    it('get() throws FileNotFoundError for a missing key', async () => {
+        await expect(store.get('nope')).rejects.toBeInstanceOf(FileNotFoundError);
+        await expect(store.get('nope')).rejects.toMatchObject({
+            code: 'file_not_found',
+            key: 'nope',
+        });
+    });
+    it('exists() reflects presence; delete() removes', async () => {
+        expect(await store.exists('k3')).toBe(false);
+        await store.put('k3', Buffer.from('x'));
+        expect(await store.exists('k3')).toBe(true);
+        expect(store.count).toBe(1);
+        await store.delete('k3');
+        expect(await store.exists('k3')).toBe(false);
+        expect(store.count).toBe(0);
+        // delete of a missing key is a no-op (idempotent)
+        await expect(store.delete('k3')).resolves.toBeUndefined();
+    });
+    it('does not implement the optional presigned hooks', () => {
+        const fs = store;
+        expect(fs.presignedPut).toBeUndefined();
+        expect(fs.presignedGet).toBeUndefined();
+    });
+});
+//# sourceMappingURL=in-memory-file-store.unit.js.map

package/dist/__tests__/unit/in-memory-file-store.unit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-file-store.unit.js","sourceRoot":"","sources":["../../../src/__tests__/unit/in-memory-file-store.unit.ts"],"names":[],"mappings":"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"}

package/dist/fs/fs-file-store.d.ts

@@ -0,0 +1,31 @@
+import { Readable } from 'node:stream';
+import { type FileStore, type PutOptions, type RetrievedFile, type StoredFile } from '../ports.js';
+export interface FsFileStoreOptions {
+    /** Directory under which all objects live. Created on demand. */
+    baseDir: string;
+    /** Optional key prefix (a subdirectory) namespacing every object. */
+    keyPrefix?: string;
+}
+/**
+ * Local-filesystem {@link FileStore}. Streams object bytes to/from
+ * `<baseDir>/<key>` and keeps a small `<key>.meta.json` sidecar for
+ * contentType/filename/metadata. Good for single-node deploys, self-hosting,
+ * and dev-with-persistence — between {@link InMemoryFileStore} and an
+ * `S3FileStore`.
+ *
+ * Every key is resolved under `baseDir` and rejected if it escapes (defense in
+ * depth — REST keys are already server-generated UUIDs, never client paths).
+ */
+export declare class FsFileStore implements FileStore {
+    private readonly baseDir;
+    private readonly prefix;
+    constructor(opts: FsFileStoreOptions);
+    /** Absolute data path for a key, guaranteed to stay within `baseDir`. */
+    private pathFor;
+    put(key: string, body: Readable | Buffer, opts?: PutOptions): Promise<StoredFile>;
+    get(key: string): Promise<RetrievedFile>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    private readSidecar;
+}
+//# sourceMappingURL=fs-file-store.d.ts.map

package/dist/fs/fs-file-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-file-store.d.ts","sourceRoot":"","sources":["../../src/fs/fs-file-store.ts"],"names":[],"mappings":"AAOA,OAAO,EAAC,QAAQ,EAAC,MAAM,aAAa,CAAC;AAErC,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AASrB,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,qBAAa,WAAY,YAAW,SAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,IAAI,EAAE,kBAAkB;IAKpC,yEAAyE;IACzE,OAAO,CAAC,OAAO;IAQT,GAAG,CACP,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,QAAQ,GAAG,MAAM,EACvB,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,UAAU,CAAC;IAehB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAsBxC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IASrC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YAM1B,WAAW;CAO1B"}

package/dist/fs/fs-file-store.js

@@ -0,0 +1,92 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+import { createReadStream, createWriteStream } from 'node:fs';
+import { access, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, resolve, sep } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { FileNotFoundError, } from '../ports.js';
+/**
+ * Local-filesystem {@link FileStore}. Streams object bytes to/from
+ * `<baseDir>/<key>` and keeps a small `<key>.meta.json` sidecar for
+ * contentType/filename/metadata. Good for single-node deploys, self-hosting,
+ * and dev-with-persistence — between {@link InMemoryFileStore} and an
+ * `S3FileStore`.
+ *
+ * Every key is resolved under `baseDir` and rejected if it escapes (defense in
+ * depth — REST keys are already server-generated UUIDs, never client paths).
+ */
+export class FsFileStore {
+    constructor(opts) {
+        this.baseDir = resolve(opts.baseDir);
+        this.prefix = opts.keyPrefix ?? '';
+    }
+    /** Absolute data path for a key, guaranteed to stay within `baseDir`. */
+    pathFor(key) {
+        const full = resolve(this.baseDir, this.prefix + key);
+        if (full !== this.baseDir && !full.startsWith(this.baseDir + sep)) {
+            throw new Error(`Refusing a key that escapes the base directory: ${key}`);
+        }
+        return full;
+    }
+    async put(key, body, opts = {}) {
+        const p = this.pathFor(key);
+        await mkdir(dirname(p), { recursive: true });
+        const source = Buffer.isBuffer(body) ? Readable.from(body) : body;
+        await pipeline(source, createWriteStream(p));
+        const sidecar = {
+            ...(opts.contentType ? { contentType: opts.contentType } : {}),
+            ...(opts.filename ? { filename: opts.filename } : {}),
+            ...(opts.metadata ? { metadata: opts.metadata } : {}),
+        };
+        await writeFile(`${p}.meta.json`, JSON.stringify(sidecar));
+        const { size } = await stat(p);
+        return { key, size, contentType: opts.contentType };
+    }
+    async get(key) {
+        const p = this.pathFor(key);
+        let size;
+        try {
+            ({ size } = await stat(p));
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                throw new FileNotFoundError(key);
+            }
+            throw err;
+        }
+        const sidecar = await this.readSidecar(p);
+        return {
+            key,
+            stream: createReadStream(p),
+            size,
+            contentType: sidecar.contentType,
+            filename: sidecar.filename,
+            metadata: sidecar.metadata,
+        };
+    }
+    async exists(key) {
+        try {
+            await access(this.pathFor(key));
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async delete(key) {
+        const p = this.pathFor(key);
+        await rm(p, { force: true });
+        await rm(`${p}.meta.json`, { force: true });
+    }
+    async readSidecar(p) {
+        try {
+            return JSON.parse(await readFile(`${p}.meta.json`, 'utf8'));
+        }
+        catch {
+            return {};
+        }
+    }
+}
+//# sourceMappingURL=fs-file-store.js.map

package/dist/fs/fs-file-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-file-store.js","sourceRoot":"","sources":["../../src/fs/fs-file-store.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,+CAA+C;AAC/C,gEAAgE;AAEhE,OAAO,EAAC,gBAAgB,EAAE,iBAAiB,EAAC,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAC,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAC,MAAM,kBAAkB,CAAC;AAC9E,OAAO,EAAC,OAAO,EAAE,OAAO,EAAE,GAAG,EAAC,MAAM,WAAW,CAAC;AAChD,OAAO,EAAC,QAAQ,EAAC,MAAM,aAAa,CAAC;AACrC,OAAO,EAAC,QAAQ,EAAC,MAAM,sBAAsB,CAAC;AAC9C,OAAO,EACL,iBAAiB,GAKlB,MAAM,aAAa,CAAC;AAgBrB;;;;;;;;;GASG;AACH,MAAM,OAAO,WAAW;IAItB,YAAY,IAAwB;QAClC,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACrC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,SAAS,IAAI,EAAE,CAAC;IACrC,CAAC;IAED,yEAAyE;IACjE,OAAO,CAAC,GAAW;QACzB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;QACtD,IAAI,IAAI,KAAK,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,GAAG,GAAG,CAAC,EAAE,CAAC;YAClE,MAAM,IAAI,KAAK,CAAC,mDAAmD,GAAG,EAAE,CAAC,CAAC;QAC5E,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,CAAC,GAAG,CACP,GAAW,EACX,IAAuB,EACvB,OAAmB,EAAE;QAErB,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAC,SAAS,EAAE,IAAI,EAAC,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAClE,MAAM,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAAC;QAC7C,MAAM,OAAO,GAAY;YACvB,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAC,WAAW,EAAE,IAAI,CAAC,WAAW,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC5D,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACnD,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAC,CAAC,CAAC,CAAC,EAAE,CAAC;SACpD,CAAC;QACF,MAAM,SAAS,CAAC,GAAG,CAAC,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC;QAC3D,MAAM,EAAC,IAAI,EAAC,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC;QAC7B,OAAO,EAAC,GAAG,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAC,CAAC;IACpD,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,CAAC,EAAC,IAAI,EAAC,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;QAC3B,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAK,GAA6B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACrD,MAAM,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC;YACnC,CAAC;YACD,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;QAC1C,OAAO;YACL,GAAG;YACH,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC;YAC3B,IAAI;YACJ,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,QAAQ,EAAE,OAAO,CAAC,QAAQ;SAC3B,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;YAChC,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,MAAM,EAAE,CAAC,CAAC,EAAE,EAAC,KAAK,EAAE,IAAI,EAAC,CAAC,CAAC;QAC3B,MAAM,EAAE,CAAC,GAAG,CAAC,YAAY,EAAE,EAAC,KAAK,EAAE,IAAI,EAAC,CAAC,CAAC;IAC5C,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,CAAS;QACjC,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,CAAY,CAAC;QACzE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;CACF"}

package/dist/in-memory/in-memory-file-store.d.ts

@@ -0,0 +1,18 @@
+import { Readable } from 'node:stream';
+import { type FileStore, type PutOptions, type RetrievedFile, type StoredFile } from '../ports.js';
+/**
+ * In-memory {@link FileStore} for tests and local dev. Each object is buffered
+ * whole in a `Map`, so it is NOT for production — no streaming-to-disk and no
+ * size cap (a large upload is held in memory). Use an `S3FileStore` (or similar
+ * streaming adapter) in production.
+ */
+export declare class InMemoryFileStore implements FileStore {
+    private readonly store;
+    put(key: string, body: Readable | Buffer, opts?: PutOptions): Promise<StoredFile>;
+    get(key: string): Promise<RetrievedFile>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    /** Test helper: number of stored objects. */
+    get count(): number;
+}
+//# sourceMappingURL=in-memory-file-store.d.ts.map

package/dist/in-memory/in-memory-file-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-file-store.d.ts","sourceRoot":"","sources":["../../src/in-memory/in-memory-file-store.ts"],"names":[],"mappings":"AAIA,OAAO,EAAC,QAAQ,EAAC,MAAM,aAAa,CAAC;AACrC,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AASrB;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,SAAS;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA4B;IAE5C,GAAG,CACP,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,QAAQ,GAAG,MAAM,EACvB,IAAI,GAAE,UAAe,GACpB,OAAO,CAAC,UAAU,CAAC;IAWhB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAaxC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxC,6CAA6C;IAC7C,IAAI,KAAK,IAAI,MAAM,CAElB;CACF"}

package/dist/in-memory/in-memory-file-store.js

@@ -0,0 +1,60 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+import { Readable } from 'node:stream';
+import { FileNotFoundError, } from '../ports.js';
+/**
+ * In-memory {@link FileStore} for tests and local dev. Each object is buffered
+ * whole in a `Map`, so it is NOT for production — no streaming-to-disk and no
+ * size cap (a large upload is held in memory). Use an `S3FileStore` (or similar
+ * streaming adapter) in production.
+ */
+export class InMemoryFileStore {
+    constructor() {
+        this.store = new Map();
+    }
+    async put(key, body, opts = {}) {
+        const buffer = await toBuffer(body);
+        this.store.set(key, {
+            buffer,
+            contentType: opts.contentType,
+            filename: opts.filename,
+            metadata: opts.metadata,
+        });
+        return { key, size: buffer.byteLength, contentType: opts.contentType };
+    }
+    async get(key) {
+        const e = this.store.get(key);
+        if (!e)
+            throw new FileNotFoundError(key);
+        return {
+            key,
+            stream: Readable.from(e.buffer),
+            size: e.buffer.byteLength,
+            contentType: e.contentType,
+            filename: e.filename,
+            metadata: e.metadata,
+        };
+    }
+    async exists(key) {
+        return this.store.has(key);
+    }
+    async delete(key) {
+        this.store.delete(key);
+    }
+    /** Test helper: number of stored objects. */
+    get count() {
+        return this.store.size;
+    }
+}
+/** Collect a Buffer or a Readable into a single Buffer. */
+async function toBuffer(body) {
+    if (Buffer.isBuffer(body))
+        return body;
+    const chunks = [];
+    for await (const chunk of body) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}
+//# sourceMappingURL=in-memory-file-store.js.map

package/dist/in-memory/in-memory-file-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-memory-file-store.js","sourceRoot":"","sources":["../../src/in-memory/in-memory-file-store.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,+CAA+C;AAC/C,gEAAgE;AAEhE,OAAO,EAAC,QAAQ,EAAC,MAAM,aAAa,CAAC;AACrC,OAAO,EACL,iBAAiB,GAKlB,MAAM,aAAa,CAAC;AASrB;;;;;GAKG;AACH,MAAM,OAAO,iBAAiB;IAA9B;QACmB,UAAK,GAAG,IAAI,GAAG,EAAiB,CAAC;IA0CpD,CAAC;IAxCC,KAAK,CAAC,GAAG,CACP,GAAW,EACX,IAAuB,EACvB,OAAmB,EAAE;QAErB,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE;YAClB,MAAM;YACN,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,QAAQ,EAAE,IAAI,CAAC,QAAQ;SACxB,CAAC,CAAC;QACH,OAAO,EAAC,GAAG,EAAE,IAAI,EAAE,MAAM,CAAC,UAAU,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAC,CAAC;IACvE,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,CAAC;YAAE,MAAM,IAAI,iBAAiB,CAAC,GAAG,CAAC,CAAC;QACzC,OAAO;YACL,GAAG;YACH,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC;YAC/B,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,UAAU;YACzB,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,QAAQ,EAAE,CAAC,CAAC,QAAQ;SACrB,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,CAAC;IAED,6CAA6C;IAC7C,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF;AAED,2DAA2D;AAC3D,KAAK,UAAU,QAAQ,CAAC,IAAuB;IAC7C,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IACvC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,IAAI,EAAE,CAAC;QAC/B,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,KAAmB,CAAC,CAAC,CAAC;IACjF,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './ports.js';
+export * from './keys.js';
+export { InMemoryFileStore } from './in-memory/in-memory-file-store.js';
+export { FsFileStore, type FsFileStoreOptions } from './fs/fs-file-store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAC,iBAAiB,EAAC,MAAM,qCAAqC,CAAC;AACtE,OAAO,EAAC,WAAW,EAAE,KAAK,kBAAkB,EAAC,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+export * from './ports.js';
+export * from './keys.js';
+export { InMemoryFileStore } from './in-memory/in-memory-file-store.js';
+export { FsFileStore } from './fs/fs-file-store.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,+CAA+C;AAC/C,gEAAgE;AAEhE,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAC,iBAAiB,EAAC,MAAM,qCAAqC,CAAC;AACtE,OAAO,EAAC,WAAW,EAA0B,MAAM,uBAAuB,CAAC"}

package/dist/keys.d.ts

@@ -0,0 +1,5 @@
+import { BindingKey } from '@agentback/core';
+import type { FileStore } from './ports.js';
+/** DI key for the active {@link FileStore}. Bind an adapter; inject to use. */
+export declare const FILE_STORE: BindingKey<FileStore>;
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAIA,OAAO,EAAC,UAAU,EAAC,MAAM,iBAAiB,CAAC;AAC3C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,YAAY,CAAC;AAE1C,+EAA+E;AAC/E,eAAO,MAAM,UAAU,uBAA8C,CAAC"}

package/dist/keys.js

@@ -0,0 +1,7 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+import { BindingKey } from '@agentback/core';
+/** DI key for the active {@link FileStore}. Bind an adapter; inject to use. */
+export const FILE_STORE = BindingKey.create('files.store');
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,+CAA+C;AAC/C,gEAAgE;AAEhE,OAAO,EAAC,UAAU,EAAC,MAAM,iBAAiB,CAAC;AAG3C,+EAA+E;AAC/E,MAAM,CAAC,MAAM,UAAU,GAAG,UAAU,CAAC,MAAM,CAAY,aAAa,CAAC,CAAC"}

package/dist/ports.d.ts

@@ -0,0 +1,64 @@
+import type { Readable } from 'node:stream';
+/** Options accepted when storing a file. */
+export interface PutOptions {
+    /** MIME type recorded alongside the bytes (echoed on `get`). */
+    contentType?: string;
+    /** Original filename, surfaced on download as `Content-Disposition`. */
+    filename?: string;
+    /** Arbitrary string metadata persisted with the object. */
+    metadata?: Record<string, string>;
+}
+/** Result of a successful {@link FileStore.put}. */
+export interface StoredFile {
+    key: string;
+    size: number;
+    contentType?: string;
+    /** Backend entity tag (e.g. S3 ETag), when the adapter provides one. */
+    etag?: string;
+}
+/** A retrieved file: a readable byte stream plus the metadata stored with it. */
+export interface RetrievedFile {
+    key: string;
+    stream: Readable;
+    size: number;
+    contentType?: string;
+    filename?: string;
+    metadata?: Record<string, string>;
+}
+/** Options for the optional presigned-URL hooks. */
+export interface PresignOptions {
+    /** URL lifetime in seconds. Adapter chooses a default when omitted. */
+    expiresInSec?: number;
+}
+/**
+ * Transport-agnostic file storage seam. Adapters (in-memory, S3, …) implement
+ * it; REST handlers stream uploads in via {@link put} and downloads out via
+ * {@link get}. Bind an implementation at {@link FILE_STORE} and inject it.
+ *
+ * Keys are opaque to the store — callers MUST generate them server-side (e.g. a
+ * UUID); never pass a client-controlled path, or an S3 adapter is open to
+ * key-traversal. `get` throws {@link FileNotFoundError} for a missing key.
+ *
+ * `presignedPut`/`presignedGet` are optional: a server-proxied adapter omits
+ * them; a direct-to-storage adapter implements them. They are declared here so
+ * a future presigned flow is an additive capability, not a breaking change.
+ */
+export interface FileStore {
+    put(key: string, body: Readable | Buffer, opts?: PutOptions): Promise<StoredFile>;
+    get(key: string): Promise<RetrievedFile>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    presignedPut?(key: string, opts?: PutOptions & PresignOptions): Promise<string>;
+    presignedGet?(key: string, opts?: PresignOptions): Promise<string>;
+}
+/**
+ * Thrown by {@link FileStore.get} when no object exists at the key. The REST
+ * layer maps this to a 404 (it stays here so the port carries no HTTP/openapi
+ * dependency).
+ */
+export declare class FileNotFoundError extends Error {
+    readonly key: string;
+    readonly code = "file_not_found";
+    constructor(key: string);
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/ports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.d.ts","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAC,QAAQ,EAAC,MAAM,aAAa,CAAC;AAE1C,4CAA4C;AAC5C,MAAM,WAAW,UAAU;IACzB,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,QAAQ,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACnC;AAED,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAS;IACxB,GAAG,CACD,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,QAAQ,GAAG,MAAM,EACvB,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,UAAU,CAAC,CAAC;IACvB,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACzC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,YAAY,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAChF,YAAY,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACpE;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;IAE9B,QAAQ,CAAC,GAAG,EAAE,MAAM;IADhC,QAAQ,CAAC,IAAI,oBAAoB;gBACZ,GAAG,EAAE,MAAM;CAIjC"}

package/dist/ports.js

@@ -0,0 +1,17 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+/**
+ * Thrown by {@link FileStore.get} when no object exists at the key. The REST
+ * layer maps this to a 404 (it stays here so the port carries no HTTP/openapi
+ * dependency).
+ */
+export class FileNotFoundError extends Error {
+    constructor(key) {
+        super(`No file stored at key '${key}'.`);
+        this.key = key;
+        this.code = 'file_not_found';
+        this.name = 'FileNotFoundError';
+    }
+}
+//# sourceMappingURL=ports.js.map

package/dist/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"AAAA,mDAAmD;AACnD,+CAA+C;AAC/C,gEAAgE;AAiEhE;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAE1C,YAAqB,GAAW;QAC9B,KAAK,CAAC,0BAA0B,GAAG,IAAI,CAAC,CAAC;QADtB,QAAG,GAAH,GAAG,CAAQ;QADvB,SAAI,GAAG,gBAAgB,CAAC;QAG/B,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF"}

package/dist/testing/conformance.d.ts

@@ -0,0 +1,9 @@
+import { type FileStore } from '../ports.js';
+/**
+ * The {@link FileStore} contract, as a reusable suite. Every adapter
+ * (in-memory, S3, …) runs it to prove it honors the port. `makeStore` returns
+ * a fresh (or shared) store; keys are unique per assertion so a real bucket is
+ * safe.
+ */
+export declare function runFileStoreConformance(label: string, makeStore: () => FileStore | Promise<FileStore>): void;
+//# sourceMappingURL=conformance.d.ts.map

package/dist/testing/conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.d.ts","sourceRoot":"","sources":["../../src/testing/conformance.ts"],"names":[],"mappings":"AAMA,OAAO,EAAoB,KAAK,SAAS,EAAC,MAAM,aAAa,CAAC;AAc9D;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,GAC9C,IAAI,CA0CN"}

package/dist/testing/conformance.js

@@ -0,0 +1,62 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+import { Readable } from 'node:stream';
+import { describe, it, expect } from 'vitest';
+import { FileNotFoundError } from '../ports.js';
+async function drain(stream) {
+    const chunks = [];
+    for await (const c of stream)
+        chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c));
+    return Buffer.concat(chunks);
+}
+let n = 0;
+/** A unique key per call so a shared backing bucket stays collision-free. */
+function uniqueKey(tag) {
+    return `agentback-conformance/${tag}-${process.pid}-${++n}`;
+}
+/**
+ * The {@link FileStore} contract, as a reusable suite. Every adapter
+ * (in-memory, S3, …) runs it to prove it honors the port. `makeStore` returns
+ * a fresh (or shared) store; keys are unique per assertion so a real bucket is
+ * safe.
+ */
+export function runFileStoreConformance(label, makeStore) {
+    describe(`FileStore conformance: ${label}`, () => {
+        it('put → get round-trips bytes, contentType, size', async () => {
+            const store = await makeStore();
+            const key = uniqueKey('roundtrip');
+            const put = await store.put(key, Buffer.from('payload'), {
+                contentType: 'application/octet-stream',
+                filename: 'p.bin',
+            });
+            expect(put.size).toBe(7);
+            const got = await store.get(key);
+            expect((await drain(got.stream)).toString()).toBe('payload');
+            expect(got.contentType).toBe('application/octet-stream');
+            expect(got.size).toBe(7);
+            await store.delete(key);
+        });
+        it('accepts a Readable body', async () => {
+            const store = await makeStore();
+            const key = uniqueKey('stream');
+            await store.put(key, Readable.from([Buffer.from('ab'), Buffer.from('c')]));
+            expect((await drain((await store.get(key)).stream)).toString()).toBe('abc');
+            await store.delete(key);
+        });
+        it('exists reflects presence; delete removes', async () => {
+            const store = await makeStore();
+            const key = uniqueKey('lifecycle');
+            expect(await store.exists(key)).toBe(false);
+            await store.put(key, Buffer.from('x'));
+            expect(await store.exists(key)).toBe(true);
+            await store.delete(key);
+            expect(await store.exists(key)).toBe(false);
+        });
+        it('get of a missing key throws FileNotFoundError', async () => {
+            const store = await makeStore();
+            await expect(store.get(uniqueKey('missing'))).rejects.toBeInstanceOf(FileNotFoundError);
+        });
+    });
+}
+//# sourceMappingURL=conformance.js.map

package/dist/testing/conformance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformance.js","sourceRoot":"","sources":["../../src/testing/conformance.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@agentback/files",
+  "version": "0.3.0",
+  "description": "Transport-agnostic file storage port (FileStore) with an in-memory adapter",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/conformance.d.ts",
+      "import": "./dist/testing/conformance.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "tslib": "^2.8.1",
+    "@agentback/core": "~0.3.0"
+  },
+  "devDependencies": {
+    "vitest": "~4.1.8"
+  },
+  "engines": {
+    "node": ">=22.13"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
+}

package/src/__tests__/unit/fs-file-store.unit.ts

@@ -0,0 +1,45 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+
+import {afterAll, describe, expect, it} from 'vitest';
+import {existsSync, mkdtempSync, readFileSync, rmSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {FsFileStore} from '../../index.js';
+import {runFileStoreConformance} from '../../testing/conformance.js';
+
+const root = mkdtempSync(join(tmpdir(), 'agentback-fs-'));
+afterAll(() => rmSync(root, {recursive: true, force: true}));
+
+// Runs unconditionally (no external service needed) — unlike the S3 adapter.
+runFileStoreConformance('FsFileStore', () => new FsFileStore({baseDir: root}));
+
+describe('FsFileStore specifics', () => {
+  it('writes the bytes to disk under baseDir', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'agentback-fs-spec-'));
+    const store = new FsFileStore({baseDir: dir});
+    await store.put('k1', Buffer.from('on disk'), {contentType: 'text/plain'});
+    expect(existsSync(join(dir, 'k1'))).toBe(true);
+    expect(readFileSync(join(dir, 'k1'), 'utf8')).toBe('on disk');
+    rmSync(dir, {recursive: true, force: true});
+  });
+
+  it('delete removes both the data and its metadata sidecar', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'agentback-fs-spec-'));
+    const store = new FsFileStore({baseDir: dir});
+    await store.put('k2', Buffer.from('x'), {filename: 'x.bin'});
+    expect(existsSync(join(dir, 'k2.meta.json'))).toBe(true);
+    await store.delete('k2');
+    expect(existsSync(join(dir, 'k2'))).toBe(false);
+    expect(existsSync(join(dir, 'k2.meta.json'))).toBe(false);
+    rmSync(dir, {recursive: true, force: true});
+  });
+
+  it('rejects a key that escapes the base directory', async () => {
+    const store = new FsFileStore({baseDir: root});
+    await expect(store.put('../escape', Buffer.from('no'))).rejects.toThrow(
+      /escapes the base directory/,
+    );
+  });
+});

package/src/__tests__/unit/in-memory-file-store.unit.ts

@@ -0,0 +1,74 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+
+import {Readable} from 'node:stream';
+import {describe, it, expect, beforeEach} from 'vitest';
+import {InMemoryFileStore, FileNotFoundError, type FileStore} from '../../index.js';
+import {runFileStoreConformance} from '../../testing/conformance.js';
+
+runFileStoreConformance('InMemoryFileStore', () => new InMemoryFileStore());
+
+/** Drain a RetrievedFile's stream back to a Buffer for assertions. */
+async function drain(stream: Readable): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const c of stream) chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c));
+  return Buffer.concat(chunks);
+}
+
+describe('InMemoryFileStore', () => {
+  let store: InMemoryFileStore;
+  beforeEach(() => {
+    store = new InMemoryFileStore();
+  });
+
+  it('round-trips a Buffer with its metadata', async () => {
+    const put = await store.put('k1', Buffer.from('hello'), {
+      contentType: 'text/plain',
+      filename: 'greeting.txt',
+      metadata: {owner: 'u1'},
+    });
+    expect(put).toEqual({key: 'k1', size: 5, contentType: 'text/plain'});
+
+    const got = await store.get('k1');
+    expect(got.size).toBe(5);
+    expect(got.contentType).toBe('text/plain');
+    expect(got.filename).toBe('greeting.txt');
+    expect(got.metadata).toEqual({owner: 'u1'});
+    expect((await drain(got.stream)).toString()).toBe('hello');
+  });
+
+  it('accepts a Readable body and reports the streamed size', async () => {
+    const body = Readable.from([Buffer.from('ab'), Buffer.from('cde')]);
+    const put = await store.put('k2', body);
+    expect(put.size).toBe(5);
+    expect((await drain((await store.get('k2')).stream)).toString()).toBe('abcde');
+  });
+
+  it('get() throws FileNotFoundError for a missing key', async () => {
+    await expect(store.get('nope')).rejects.toBeInstanceOf(FileNotFoundError);
+    await expect(store.get('nope')).rejects.toMatchObject({
+      code: 'file_not_found',
+      key: 'nope',
+    });
+  });
+
+  it('exists() reflects presence; delete() removes', async () => {
+    expect(await store.exists('k3')).toBe(false);
+    await store.put('k3', Buffer.from('x'));
+    expect(await store.exists('k3')).toBe(true);
+    expect(store.count).toBe(1);
+
+    await store.delete('k3');
+    expect(await store.exists('k3')).toBe(false);
+    expect(store.count).toBe(0);
+    // delete of a missing key is a no-op (idempotent)
+    await expect(store.delete('k3')).resolves.toBeUndefined();
+  });
+
+  it('does not implement the optional presigned hooks', () => {
+    const fs: FileStore = store;
+    expect(fs.presignedPut).toBeUndefined();
+    expect(fs.presignedGet).toBeUndefined();
+  });
+});

package/src/fs/fs-file-store.ts

@@ -0,0 +1,123 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+
+import {createReadStream, createWriteStream} from 'node:fs';
+import {access, mkdir, readFile, rm, stat, writeFile} from 'node:fs/promises';
+import {dirname, resolve, sep} from 'node:path';
+import {Readable} from 'node:stream';
+import {pipeline} from 'node:stream/promises';
+import {
+  FileNotFoundError,
+  type FileStore,
+  type PutOptions,
+  type RetrievedFile,
+  type StoredFile,
+} from '../ports.js';
+
+/** Per-object metadata persisted next to the bytes as `<key>.meta.json`. */
+interface Sidecar {
+  contentType?: string;
+  filename?: string;
+  metadata?: Record<string, string>;
+}
+
+export interface FsFileStoreOptions {
+  /** Directory under which all objects live. Created on demand. */
+  baseDir: string;
+  /** Optional key prefix (a subdirectory) namespacing every object. */
+  keyPrefix?: string;
+}
+
+/**
+ * Local-filesystem {@link FileStore}. Streams object bytes to/from
+ * `<baseDir>/<key>` and keeps a small `<key>.meta.json` sidecar for
+ * contentType/filename/metadata. Good for single-node deploys, self-hosting,
+ * and dev-with-persistence — between {@link InMemoryFileStore} and an
+ * `S3FileStore`.
+ *
+ * Every key is resolved under `baseDir` and rejected if it escapes (defense in
+ * depth — REST keys are already server-generated UUIDs, never client paths).
+ */
+export class FsFileStore implements FileStore {
+  private readonly baseDir: string;
+  private readonly prefix: string;
+
+  constructor(opts: FsFileStoreOptions) {
+    this.baseDir = resolve(opts.baseDir);
+    this.prefix = opts.keyPrefix ?? '';
+  }
+
+  /** Absolute data path for a key, guaranteed to stay within `baseDir`. */
+  private pathFor(key: string): string {
+    const full = resolve(this.baseDir, this.prefix + key);
+    if (full !== this.baseDir && !full.startsWith(this.baseDir + sep)) {
+      throw new Error(`Refusing a key that escapes the base directory: ${key}`);
+    }
+    return full;
+  }
+
+  async put(
+    key: string,
+    body: Readable | Buffer,
+    opts: PutOptions = {},
+  ): Promise<StoredFile> {
+    const p = this.pathFor(key);
+    await mkdir(dirname(p), {recursive: true});
+    const source = Buffer.isBuffer(body) ? Readable.from(body) : body;
+    await pipeline(source, createWriteStream(p));
+    const sidecar: Sidecar = {
+      ...(opts.contentType ? {contentType: opts.contentType} : {}),
+      ...(opts.filename ? {filename: opts.filename} : {}),
+      ...(opts.metadata ? {metadata: opts.metadata} : {}),
+    };
+    await writeFile(`${p}.meta.json`, JSON.stringify(sidecar));
+    const {size} = await stat(p);
+    return {key, size, contentType: opts.contentType};
+  }
+
+  async get(key: string): Promise<RetrievedFile> {
+    const p = this.pathFor(key);
+    let size: number;
+    try {
+      ({size} = await stat(p));
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === 'ENOENT') {
+        throw new FileNotFoundError(key);
+      }
+      throw err;
+    }
+    const sidecar = await this.readSidecar(p);
+    return {
+      key,
+      stream: createReadStream(p),
+      size,
+      contentType: sidecar.contentType,
+      filename: sidecar.filename,
+      metadata: sidecar.metadata,
+    };
+  }
+
+  async exists(key: string): Promise<boolean> {
+    try {
+      await access(this.pathFor(key));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    const p = this.pathFor(key);
+    await rm(p, {force: true});
+    await rm(`${p}.meta.json`, {force: true});
+  }
+
+  private async readSidecar(p: string): Promise<Sidecar> {
+    try {
+      return JSON.parse(await readFile(`${p}.meta.json`, 'utf8')) as Sidecar;
+    } catch {
+      return {};
+    }
+  }
+}

package/src/in-memory/in-memory-file-store.ts

@@ -0,0 +1,80 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+
+import {Readable} from 'node:stream';
+import {
+  FileNotFoundError,
+  type FileStore,
+  type PutOptions,
+  type RetrievedFile,
+  type StoredFile,
+} from '../ports.js';
+
+interface Entry {
+  buffer: Buffer;
+  contentType?: string;
+  filename?: string;
+  metadata?: Record<string, string>;
+}
+
+/**
+ * In-memory {@link FileStore} for tests and local dev. Each object is buffered
+ * whole in a `Map`, so it is NOT for production — no streaming-to-disk and no
+ * size cap (a large upload is held in memory). Use an `S3FileStore` (or similar
+ * streaming adapter) in production.
+ */
+export class InMemoryFileStore implements FileStore {
+  private readonly store = new Map<string, Entry>();
+
+  async put(
+    key: string,
+    body: Readable | Buffer,
+    opts: PutOptions = {},
+  ): Promise<StoredFile> {
+    const buffer = await toBuffer(body);
+    this.store.set(key, {
+      buffer,
+      contentType: opts.contentType,
+      filename: opts.filename,
+      metadata: opts.metadata,
+    });
+    return {key, size: buffer.byteLength, contentType: opts.contentType};
+  }
+
+  async get(key: string): Promise<RetrievedFile> {
+    const e = this.store.get(key);
+    if (!e) throw new FileNotFoundError(key);
+    return {
+      key,
+      stream: Readable.from(e.buffer),
+      size: e.buffer.byteLength,
+      contentType: e.contentType,
+      filename: e.filename,
+      metadata: e.metadata,
+    };
+  }
+
+  async exists(key: string): Promise<boolean> {
+    return this.store.has(key);
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+
+  /** Test helper: number of stored objects. */
+  get count(): number {
+    return this.store.size;
+  }
+}
+
+/** Collect a Buffer or a Readable into a single Buffer. */
+async function toBuffer(body: Readable | Buffer): Promise<Buffer> {
+  if (Buffer.isBuffer(body)) return body;
+  const chunks: Buffer[] = [];
+  for await (const chunk of body) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk as Uint8Array));
+  }
+  return Buffer.concat(chunks);
+}

package/src/index.ts

@@ -0,0 +1,8 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+
+export * from './ports.js';
+export * from './keys.js';
+export {InMemoryFileStore} from './in-memory/in-memory-file-store.js';
+export {FsFileStore, type FsFileStoreOptions} from './fs/fs-file-store.js';

package/src/keys.ts

@@ -0,0 +1,9 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+
+import {BindingKey} from '@agentback/core';
+import type {FileStore} from './ports.js';
+
+/** DI key for the active {@link FileStore}. Bind an adapter; inject to use. */
+export const FILE_STORE = BindingKey.create<FileStore>('files.store');

package/src/ports.ts

@@ -0,0 +1,79 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+
+import type {Readable} from 'node:stream';
+
+/** Options accepted when storing a file. */
+export interface PutOptions {
+  /** MIME type recorded alongside the bytes (echoed on `get`). */
+  contentType?: string;
+  /** Original filename, surfaced on download as `Content-Disposition`. */
+  filename?: string;
+  /** Arbitrary string metadata persisted with the object. */
+  metadata?: Record<string, string>;
+}
+
+/** Result of a successful {@link FileStore.put}. */
+export interface StoredFile {
+  key: string;
+  size: number;
+  contentType?: string;
+  /** Backend entity tag (e.g. S3 ETag), when the adapter provides one. */
+  etag?: string;
+}
+
+/** A retrieved file: a readable byte stream plus the metadata stored with it. */
+export interface RetrievedFile {
+  key: string;
+  stream: Readable;
+  size: number;
+  contentType?: string;
+  filename?: string;
+  metadata?: Record<string, string>;
+}
+
+/** Options for the optional presigned-URL hooks. */
+export interface PresignOptions {
+  /** URL lifetime in seconds. Adapter chooses a default when omitted. */
+  expiresInSec?: number;
+}
+
+/**
+ * Transport-agnostic file storage seam. Adapters (in-memory, S3, …) implement
+ * it; REST handlers stream uploads in via {@link put} and downloads out via
+ * {@link get}. Bind an implementation at {@link FILE_STORE} and inject it.
+ *
+ * Keys are opaque to the store — callers MUST generate them server-side (e.g. a
+ * UUID); never pass a client-controlled path, or an S3 adapter is open to
+ * key-traversal. `get` throws {@link FileNotFoundError} for a missing key.
+ *
+ * `presignedPut`/`presignedGet` are optional: a server-proxied adapter omits
+ * them; a direct-to-storage adapter implements them. They are declared here so
+ * a future presigned flow is an additive capability, not a breaking change.
+ */
+export interface FileStore {
+  put(
+    key: string,
+    body: Readable | Buffer,
+    opts?: PutOptions,
+  ): Promise<StoredFile>;
+  get(key: string): Promise<RetrievedFile>;
+  exists(key: string): Promise<boolean>;
+  delete(key: string): Promise<void>;
+  presignedPut?(key: string, opts?: PutOptions & PresignOptions): Promise<string>;
+  presignedGet?(key: string, opts?: PresignOptions): Promise<string>;
+}
+
+/**
+ * Thrown by {@link FileStore.get} when no object exists at the key. The REST
+ * layer maps this to a 404 (it stays here so the port carries no HTTP/openapi
+ * dependency).
+ */
+export class FileNotFoundError extends Error {
+  readonly code = 'file_not_found';
+  constructor(readonly key: string) {
+    super(`No file stored at key '${key}'.`);
+    this.name = 'FileNotFoundError';
+  }
+}

package/src/testing/conformance.ts

@@ -0,0 +1,72 @@
+// Copyright Ninemind.ai 2026. All Rights Reserved.
+// This file is licensed under the MIT License.
+// License text available at https://opensource.org/license/mit/
+
+import {Readable} from 'node:stream';
+import {describe, it, expect} from 'vitest';
+import {FileNotFoundError, type FileStore} from '../ports.js';
+
+async function drain(stream: Readable): Promise<Buffer> {
+  const chunks: Buffer[] = [];
+  for await (const c of stream) chunks.push(Buffer.isBuffer(c) ? c : Buffer.from(c));
+  return Buffer.concat(chunks);
+}
+
+let n = 0;
+/** A unique key per call so a shared backing bucket stays collision-free. */
+function uniqueKey(tag: string): string {
+  return `agentback-conformance/${tag}-${process.pid}-${++n}`;
+}
+
+/**
+ * The {@link FileStore} contract, as a reusable suite. Every adapter
+ * (in-memory, S3, …) runs it to prove it honors the port. `makeStore` returns
+ * a fresh (or shared) store; keys are unique per assertion so a real bucket is
+ * safe.
+ */
+export function runFileStoreConformance(
+  label: string,
+  makeStore: () => FileStore | Promise<FileStore>,
+): void {
+  describe(`FileStore conformance: ${label}`, () => {
+    it('put → get round-trips bytes, contentType, size', async () => {
+      const store = await makeStore();
+      const key = uniqueKey('roundtrip');
+      const put = await store.put(key, Buffer.from('payload'), {
+        contentType: 'application/octet-stream',
+        filename: 'p.bin',
+      });
+      expect(put.size).toBe(7);
+      const got = await store.get(key);
+      expect((await drain(got.stream)).toString()).toBe('payload');
+      expect(got.contentType).toBe('application/octet-stream');
+      expect(got.size).toBe(7);
+      await store.delete(key);
+    });
+
+    it('accepts a Readable body', async () => {
+      const store = await makeStore();
+      const key = uniqueKey('stream');
+      await store.put(key, Readable.from([Buffer.from('ab'), Buffer.from('c')]));
+      expect((await drain((await store.get(key)).stream)).toString()).toBe('abc');
+      await store.delete(key);
+    });
+
+    it('exists reflects presence; delete removes', async () => {
+      const store = await makeStore();
+      const key = uniqueKey('lifecycle');
+      expect(await store.exists(key)).toBe(false);
+      await store.put(key, Buffer.from('x'));
+      expect(await store.exists(key)).toBe(true);
+      await store.delete(key);
+      expect(await store.exists(key)).toBe(false);
+    });
+
+    it('get of a missing key throws FileNotFoundError', async () => {
+      const store = await makeStore();
+      await expect(store.get(uniqueKey('missing'))).rejects.toBeInstanceOf(
+        FileNotFoundError,
+      );
+    });
+  });
+}