Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix: pre-landing review fixes (purge uses the engine's settings.storage)
garrytanb46b8cf1173b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex f9a3ccce0c..7eadf4e271 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -18,6 +18,7 @@ identifiers and attribution are available in the pre-removal Git revision- `src/core/ops/files.ts`: `file_register` accepts only the upload layout path (`<page_slug>/<filename>`, or `unsorted/<first 8 hash chars>-<filename>`), refuses `page_not_found` for a page that does not exist or that the caller's read policy hides (member access and privacy, the private-pages hatch included), and records nothing unless the stored object matches. Rows record their store's backend and prefix. Registering the same path again updates its row.- A store that does not answer is the new `store_unavailable` code, never a file reported missing and never a row recorded.+- On an engine opened from settings, `delete_page` purge deletes a page's files from `settings.storage` too, and reports them remaining when the engine has none. Rows an embedded engine's `file_upload` wrote before this release point at the process store, so `file_url` and `file_verify` look for them in `settings.storage`.- `openEngine` refuses `engine_settings_invalid` for a `storage` setting missing a value its backend needs (so no backend falls back to a default path or environment credentials), an unknown field, a backend other than local or s3, or a prefix that is not one segment; an s3 store must name its endpoint, so no AWS_* variable or ~/.aws file picks it; `embeddedSettings()` reads back `hasSecret` instead of the secret.- `src/core/storage/local.ts` and `s3.ts` stream an object's size and SHA-256 (`hashObject`); other backends hash one download.- `test/file-register.test.ts`: real PGLite engines and a real local store; the unreachable store is a closed local port.diff --git a/docs/ENGINES.md b/docs/ENGINES.mdindex 641b93071e..fbeaa41cc5 100644--- a/docs/ENGINES.md+++ b/docs/ENGINES.md@@ -780,7 +780,7 @@ working directory:- **Files.** Every file op uses `settings.storage` (local, or s3 with its endpoint), keys under a one-segment `prefix`;brains sharing a bucket each set their own.-Still process-wide: file_upload's storage, transcription, the AI call log and timeouts, `GBRAIN_*` tuning variables (pool lifetime,+Still process-wide: the `gbrain files` CLI's storage, transcription, the AI call log and timeouts, `GBRAIN_*` tuning variables (pool lifetime,connect and session timeouts, `GBRAIN_PREPARE`, `GBRAIN_DIRECT_POOL_SIZE`, `GBRAIN_DISABLE_DIRECT_POOL`,`GBRAIN_RLS_SCOPE_BINDING`, the PGLite close watchdog), `PG*` TLS and tuningvariables, the connection-events audit log, and operation-leveldiff --git a/llms-full.txt b/llms-full.txtindex 4cc86831fb..81726e81b7 100644--- a/llms-full.txt+++ b/llms-full.txt@@ -6227,7 +6227,7 @@ working directory:- **Files.** Every file op uses `settings.storage` (local, or s3 with its endpoint), keys under a one-segment `prefix`;brains sharing a bucket each set their own.-Still process-wide: file_upload's storage, transcription, the AI call log and timeouts, `GBRAIN_*` tuning variables (pool lifetime,+Still process-wide: the `gbrain files` CLI's storage, transcription, the AI call log and timeouts, `GBRAIN_*` tuning variables (pool lifetime,connect and session timeouts, `GBRAIN_PREPARE`, `GBRAIN_DIRECT_POOL_SIZE`, `GBRAIN_DISABLE_DIRECT_POOL`,`GBRAIN_RLS_SCOPE_BINDING`, the PGLite close watchdog), `PG*` TLS and tuningvariables, the connection-events audit log, and operation-leveldiff --git a/src/core/ops/files.ts b/src/core/ops/files.tsindex 3f39755500..936b429589 100644--- a/src/core/ops/files.ts+++ b/src/core/ops/files.ts@@ -227,9 +227,8 @@ async function embeddedStorage(ctx: OperationContext, op: string) {const settings = embeddedSettingsRecord(ctx.engine)?.storage;if (!settings) throw opError('storage_error', `This engine was opened with no settings.storage, so ${op} cannot check any stored object.`,'Open the engine with storage (local or s3, with its values) in its settings; the process storage config is never used for an engine opened from settings. Nothing was recorded.');- const { createStorage, prefixedStorage } = await import('../storage.ts');- const { prefix, ...config } = settings;- try { return prefixedStorage(await createStorage({ bucket: '', ...config }), prefix); } catch (error) { throw storeUnavailable(op, error); }+ const { settingsStorage } = await import('../storage.ts');+ try { return (await settingsStorage(ctx.engine))!; } catch (error) { throw storeUnavailable(op, error); }}async function embeddedFileStore(ctx: OperationContext, op: string) {diff --git a/src/core/persistence/page-purge.ts b/src/core/persistence/page-purge.tsindex 19355ee035..48811d3283 100644--- a/src/core/persistence/page-purge.ts+++ b/src/core/persistence/page-purge.ts@@ -36,6 +36,7 @@ import type { BrainEngine } from '../engine.ts';import type { OperationContext } from '../ops/contract.ts';import { opError, type OperationError } from '../ops/contract.ts';import { readFix } from '../ops/op-fix.ts';+import { isEmbeddedEngine } from '../embedded-engine.ts';import type { PageSnapshot } from '../page-state/types.ts';import type { WriteRequest } from './model.ts';import { enterClaimStep, type ClaimPhaseClock } from './claim-phase.ts';@@ -377,8 +378,10 @@ export async function finishPagePurge(ctx: Pick<OperationContext, 'engine' | 'coconst remaining: string[] = [];if (purge.blobs?.length) {try {- const { createStorage } = await import('../storage.ts');- const storage = await createStorage((ctx.config as { storage?: unknown } | undefined)?.storage as never);+ const { createStorage, settingsStorage } = await import('../storage.ts');+ const storage = isEmbeddedEngine(ctx.engine) ? await settingsStorage(ctx.engine)+ : await createStorage((ctx.config as { storage?: unknown } | undefined)?.storage as never);+ if (!storage) throw new Error('This engine was opened with no settings.storage.');for (const path of purge.blobs) { try { await storage.delete(path); } catch { remaining.push(path); } }} catch { remaining.push(...purge.blobs); }}diff --git a/src/core/storage.ts b/src/core/storage.tsindex 9dd8b28ed9..c1c55ed40f 100644--- a/src/core/storage.ts+++ b/src/core/storage.ts@@ -1,6 +1,7 @@import { closeSync, openSync, readSync } from 'fs';import type { FileHandle } from 'fs/promises';import { createHash } from 'crypto';+import { embeddedSettingsRecord } from './embedded-engine.ts';/*** StorageBackend — pluggable interface for binary file storage.@@ -78,6 +79,14 @@ export function hashStorageFile(filePath: string): string {}}+/** The store an engine opened from settings keeps its files in (settings.storage under its prefix); undefined for any other engine or with no settings.storage. */+export async function settingsStorage(engine: object): Promise<StorageBackend | undefined> {+ const settings = embeddedSettingsRecord(engine)?.storage;+ if (!settings) return undefined;+ const { prefix, ...config } = settings;+ return prefixedStorage(await createStorage({ bucket: '', ...config }), prefix);+}+/** `backend` with every object key under `<prefix>/`; list() returns keys without it. No prefix returns `backend` itself. */export function prefixedStorage(backend: StorageBackend, prefix: string | undefined): StorageBackend {if (!prefix) return backend;diff --git a/test/file-register.test.ts b/test/file-register.test.tsindex 9bff26b217..bff91199c4 100644--- a/test/file-register.test.ts+++ b/test/file-register.test.ts@@ -142,6 +142,31 @@ describe('file_register', () => {expect(await run('file_verify', ctx, { storage_path: 'notes/plan/upload.txt' })).toMatchObject({ present: true, hash_matches: true });});+ test('file_upload on an engine opened without settings.storage refuses and never writes the process store', async () => {+ const engine = await embedded({ storage: undefined });+ await addPage(engine, 'notes/plan');+ const source = join(root, 'refused.txt');+ writeFileSync(source, 'refused bytes');+ const ctx = ctxFor(engine, { config: { storage: { backend: 'local', bucket: 'test', localPath: join(root, 'process-store-2') } } } as never);+ expect((await failure(() => run('file_upload', ctx, { path: source, page_slug: 'notes/plan' })))?.code).toBe('storage_error');+ expect([existsSync(join(root, 'process-store-2')), await fileRows(engine)]).toEqual([false, 0]);+ });++ test('a purge on an engine opened from settings deletes its blobs from that store, never the process store', async () => {+ const engine = await embedded({ storage: { ...storage, prefix: 'brain-a' } });+ const processDir = join(root, 'process-store-3');+ store('brain-a/notes/plan/p.txt', Buffer.from('embedded'));+ mkdirSync(join(processDir, 'notes/plan'), { recursive: true });+ writeFileSync(join(processDir, 'notes/plan/p.txt'), 'another brain');+ const { finishPagePurge } = await import('../src/core/persistence/page-purge.ts');+ const purged = { status: 'purged', source_id: 'default', slug: 'notes/plan', request_id: randomUUID(), purge: { blobs: ['notes/plan/p.txt'], removed: {} } };+ const result = await finishPagePurge({ engine, config: { storage: { backend: 'local', bucket: 'test', localPath: processDir } } } as never, purged) as { purge: { blobs_remaining: string[] } };+ expect([result.purge.blobs_remaining, existsSync(join(storageRoot, 'brain-a/notes/plan/p.txt')), existsSync(join(processDir, 'notes/plan/p.txt'))]).toEqual([[], false, true]);+ const bare = await embedded({ storage: undefined });+ const kept = await finishPagePurge({ engine: bare, config: { storage: { backend: 'local', bucket: 'test', localPath: processDir } } } as never, { ...purged, request_id: randomUUID() }) as { purge: { blobs_remaining: string[] } };+ expect([kept.purge.blobs_remaining, existsSync(join(processDir, 'notes/plan/p.txt'))]).toEqual([['notes/plan/p.txt'], true]);+ });+test('a store that cannot be reached is store_unavailable and records nothing', async () => {const engine = await embedded({ storage: unreachable });const bytes = Buffer.from('x');@@ -150,6 +175,7 @@ describe('file_register', () => {expect(await fileRows(engine)).toBe(0);await engine.executeRaw(`INSERT INTO files (filename, storage_path, content_hash, size_bytes) VALUES ('a.txt', 'unsorted/a.txt', $1, 1)`, [sha(bytes)]);for (const params of [{}, { storage_path: 'unsorted/a.txt' }]) expect((await failure(() => run('file_verify', ctxFor(engine), params)))?.code).toBe('store_unavailable');+ expect((await failure(() => run('file_url', ctxFor(engine), { storage_path: 'unsorted/a.txt' })))?.code).toBe('store_unavailable');});});