Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
fix: storage shelf refuses while archived; adopt names a shelf it finishes
garrytan0381285ed89d
diff --git a/changelog.d/capy-storage-manifest-adopt.md b/changelog.d/capy-storage-manifest-adopt.mdindex e574ae75b5..ffa65ccb0c 100644--- a/changelog.d/capy-storage-manifest-adopt.md+++ b/changelog.d/capy-storage-manifest-adopt.md@@ -1,6 +1,6 @@**A storage manifest: agents can register what they archived to object storage and find it again later.** A new `storage` source holds one validated card per archived item: what it is, where every copy lives (store, bucket, path, restic repository and snapshot, size, file count, hash and its kind, when it was verified), where it came from and which skill restores it. `gbrain storage-register` adds a card (from stdin or `--card`) and never overwrites one; `gbrain storage-update <id> --expected-revision <rev>` patches a card bound to the revision it read and records restores newest first; `gbrain storage-find "<words>"` ranks the exact id, then an exact alias, then the cards holding most of the words, and a miss lists the closest cards; `gbrain storage-get` and `gbrain storage-list` read. On a brain with a Git checkout, `gbrain storage init` hosts the shelf in its own repository first (preview, then `--expect <plan_hash>`; it needs managed persistence), so each card is a commit before it is indexed. A repo-less brain gets a database-only shelf on the first register.-Cards never carry credentials or commands. A card is refused when any field looks like a secret, an environment assignment, a credential variable, a URL with user info or a presigned URL, or when any key is named `command`, `cmd`, `script`, `exec`, `shell` or `instructions`; object keys are checked too, and the refusal never echoes the value. A first shelf creation that stopped part way is finished by the next register or `storage init`. A restore is `{ skill, args }` with flat scalar arguments. gbrain stamps `registered_by` and `origin` itself, and holds no store credentials.+Cards never carry credentials or commands. A card is refused when any field looks like a secret, an environment assignment, a credential variable, a URL with user info or a presigned URL, or when any key is named `command`, `cmd`, `script`, `exec`, `shell` or `instructions`; object keys are checked too, and the refusal never echoes the value. A first shelf creation that stopped part way is finished by the next register or `storage init`, and an archived shelf refuses until it is restored. A restore is `{ skill, args }` with flat scalar arguments. gbrain stamps `registered_by` and `origin` itself, and holds no store credentials.The shelf is written only through the storage verbs. `put_page`, `remember` and every other page writer are refused `storage_source_managed` there, a request parameter cannot open the door, register and update run only from the trusted local CLI, and a dream cycle or enrichment run scoped to the shelf skips it. The source is not federated, so a remote connection reads cards only when its grant names `storage`.diff --git a/docs/guides/storage-manifest.md b/docs/guides/storage-manifest.mdindex bef6b2286d..40603d7f04 100644--- a/docs/guides/storage-manifest.md+++ b/docs/guides/storage-manifest.md@@ -33,8 +33,10 @@ carry commands or credentials, and gbrain never contacts a store. After the restOn a repo-less brain, including a fresh keyless install whose content directory (created by `gbrain init`) holds noGit checkout, the database is the record: the first `storage-register` (or `gbrain storage init`) creates the`storage` source, database-only and not federated, and every verb works there. If that first creation stopped part-way (a crash, two first registers at once), the next register or `gbrain storage init` finishes it. A `storage` source-that already holds someone else's pages is never taken over: the verbs refuse `storage_manifest_missing`.+way (a crash, two first registers at once), the next register or `gbrain storage init` finishes it, so an empty+`storage` source with no directory of its own counts as the shelf. A `storage` source that holds pages, or (on a+repo-less brain) has its own directory, is never taken over: the verbs refuse `storage_manifest_missing`, as they do while the shelf is archived (until+`gbrain sources restore storage`).On a brain with a Git checkout, Git stays the parent. `gbrain storage init --dir <absolute path> --dry-run` previews ahosted Git repository for the shelf, and the printed `--expect <plan_hash>` command creates it after the user agreesdiff --git a/src/core/storage-manifest/adopt.ts b/src/core/storage-manifest/adopt.tsindex b9e3e853d9..0d3240d013 100644--- a/src/core/storage-manifest/adopt.ts+++ b/src/core/storage-manifest/adopt.ts@@ -179,7 +179,7 @@ async function assertInterimSource(ctx: OperationContext, opts: AdoptOptions): P/** Preview: what apply would do. Writes nothing; refuses storage_manifest_missing on a brain with a Git checkout until storage init has run. */export async function previewAdopt(ctx: OperationContext, opts: AdoptOptions): Promise<AdoptPlan> {await assertInterimSource(ctx, opts);- const { creates } = await shelfWritable(ctx.engine);+ const { creates, exists } = await shelfWritable(ctx.engine);const shelf = new Map((await readShelfCards(ctx.engine)).map((row) => [row.id, row.card]));const seen = new Set<string>();const entries: AdoptEntry[] = (await listInterim(ctx, opts, false)).map((row): AdoptEntry => {@@ -201,13 +201,14 @@ export async function previewAdopt(ctx: OperationContext, opts: AdoptOptions): Pslug: e.slug, card: e.card ? cardDigest(e.card) : null, refused: e.refused.map((f) => `${f.field}:${f.reason}`),problem: e.problem ? `${e.problem.code}:${e.problem.reason}` : null, conflict: e.state === 'conflict' })) }));const summary = [`${entries.length} interim record(s) under ${opts.prefix} in source ${opts.sourceId}: ${counts.register} to register, ${counts.retag} already on the shelf to tag, ${counts.adopted} already adopted, ${counts.conflict} conflict(s), ${counts.blocked} blocked.`];- if (creates && counts.register) summary.push(`The first card creates the storage shelf (source ${STORAGE_SOURCE_ID}, database-only: this brain has no Git checkout, so the database is the record).`);+ if (creates && counts.register) summary.push(exists ? `The first card finishes the storage shelf (source ${STORAGE_SOURCE_ID}) that an earlier creation left without its role.`+ : `The first card creates the storage shelf (source ${STORAGE_SOURCE_ID}, database-only: this brain has no Git checkout, so the database is the record).`);if (drop_fields.length) summary.push(`Fields a card refuses, left out only when each is named with --drop-field: ${drop_fields.join(', ')}. The original pages keep them until finalize.`);if (counts.conflict) summary.push('A conflict is a card already on the shelf that differs from the record: it is never overwritten, and its original is not tagged.');if (counts.blocked) summary.push('Blocked pages need their record fixed on the page first; apply refuses until then.');const apply = counts.blocked || !(counts.register + counts.retag) ? undefined: [...adoptArgv(opts), ...drop_fields.flatMap((f) => ['--drop-field', f]), '--apply', '--expect', plan_hash];- return { action: 'adopt', dry_run: true, source_id: opts.sourceId, prefix: opts.prefix, shelf: creates ? 'creates' : 'exists', entries, counts, drop_fields, plan_hash, summary, ...(apply ? { apply } : {}) };+ return { action: 'adopt', dry_run: true, source_id: opts.sourceId, prefix: opts.prefix, shelf: creates && !exists ? 'creates' : 'exists', entries, counts, drop_fields, plan_hash, summary, ...(apply ? { apply } : {}) };}function staleHash(opts: AdoptOptions, expected: string, finalize: boolean): OperationError {diff --git a/src/core/storage-manifest/source.ts b/src/core/storage-manifest/source.tsindex c138b18b9a..4328ed792e 100644--- a/src/core/storage-manifest/source.ts+++ b/src/core/storage-manifest/source.ts@@ -24,7 +24,7 @@ export function isStorageRole(config: unknown): boolean {}/** `ours`: an empty source a shelf creation started and did not finish marking (hosted by storage init, or database-only). */-export interface StorageSourceState { exists: boolean; repoBrain: boolean; role: boolean; hosted: boolean; ours: boolean }+export interface StorageSourceState { exists: boolean; archived: boolean; repoBrain: boolean; role: boolean; hosted: boolean; ours: boolean }/*** A repo brain is one with any active source that has a directory (or the legacy sync.repo_path of default); mixed@@ -41,7 +41,7 @@ export async function storageSourceState(engine: BrainEngine): Promise<StorageSo'SELECT s.config, s.archived, s.local_path, EXISTS (SELECT 1 FROM pages p WHERE p.source_id = s.id) AS pages FROM sources s WHERE s.id=$1', [STORAGE_SOURCE_ID]);const config = row ? parseSourceConfig(row.config) : {};const hosted = !!config.hosted_repo;- return { exists: !!row && !row.archived, repoBrain: await isRepoBrain(engine), role: config.role === STORAGE_ROLE, hosted,+ return { exists: !!row && !row.archived, archived: !!row?.archived, repoBrain: await isRepoBrain(engine), role: config.role === STORAGE_ROLE, hosted,ours: !!row && !row.pages && (hosted || !row.local_path) };}@@ -53,6 +53,11 @@ function notOurs() {`The storage shelf needs the source ID ${STORAGE_SOURCE_ID}. Ask the user what that source holds before anything else; gbrain sources list shows it. Its pages stay where they are.`);}+function archivedShelf() {+ return opError('storage_manifest_missing', `Source ${STORAGE_SOURCE_ID} is archived; nothing was written.`,+ `Ask the user whether to bring it back with gbrain sources restore ${STORAGE_SOURCE_ID} (gbrain sources archived shows when it would be purged).`);+}+function initFix() {return readFix('Previews creating the storage shelf on this brain; changes nothing.', { argv: ['gbrain', 'storage', 'init', '--dry-run'] });}@@ -73,6 +78,7 @@ async function markRole(engine: BrainEngine): Promise<void> {*/export async function shelfWritable(engine: BrainEngine): Promise<{ creates: boolean; exists: boolean }> {const state = await storageSourceState(engine);+ if (state.archived) throw archivedShelf();if (state.exists && state.role) return { creates: false, exists: true };if (unfinished(state)) return { creates: true, exists: true };if (state.exists) throw notOurs();@@ -89,7 +95,7 @@ export async function ensureStorageSource(engine: BrainEngine): Promise<void> {if (!exists) {try { await addSource(engine, { id: STORAGE_SOURCE_ID, name: 'Storage manifest', federated: false }); } catch (error) {const now = await storageSourceState(engine);- if (!now.role && !unfinished(now)) throw error;+ if (!now.exists || (!now.role && !unfinished(now))) throw error;}}await markRole(engine);@@ -100,6 +106,7 @@ export interface StorageInitResult { action: 'none' | 'create_database_source' |/** `gbrain storage init`: preview, then apply. Repo-less: a database-only source. Repo brain: hostRepo, then the role. */export async function initStorageSource(engine: BrainEngine, opts: { dir?: string; pushRemote?: string; dryRun: boolean; expect?: string }): Promise<StorageInitResult> {const state = await storageSourceState(engine);+ if (state.archived) throw archivedShelf();if (state.exists && state.role && (!state.repoBrain || state.hosted)) {return { action: 'none', dry_run: opts.dryRun, repo_brain: state.repoBrain, summary: [`The storage shelf (source ${STORAGE_SOURCE_ID}) already exists${state.hosted ? ' as a hosted Git repository' : ''}.`] };}diff --git a/test/storage-manifest.test.ts b/test/storage-manifest.test.tsindex 1aa5425c96..d37d344f58 100644--- a/test/storage-manifest.test.ts+++ b/test/storage-manifest.test.ts@@ -168,6 +168,15 @@ describe('storage shelf on a repo-less brain', () => {expect(await role()).toMatchObject({ role: 'storage_manifest', federated: 'false' });expect((await call('storage_get', { id: 'after-crash' })).card.title).toBe('Dataset after-crash');+ await engine.executeRaw("UPDATE sources SET archived = true WHERE id = 'storage'");+ const archivedConfig = (await engine.executeRaw<{ config: unknown }>("SELECT config FROM sources WHERE id='storage'"))[0]!.config;+ for (const attempt of [call('storage_register', { card: card('while-archived') }), initStorageSource(engine, { dryRun: false })]) {+ const r = await refusal(attempt);+ expect(r?.code).toBe('storage_manifest_missing');+ expect(r!.message).toContain('archived');+ }+ expect((await engine.executeRaw<{ config: unknown }>("SELECT config FROM sources WHERE id='storage'"))[0]!.config).toEqual(archivedConfig);+await resetPgliteState(engine);await addSource(engine, { id: 'storage', name: 'Someone else', federated: false });await call('put_page', { slug: 'notes', source_id: 'storage', content: '---\ntype: note\ntitle: Notes\n---\nKept.\n', request_id: randomUUID() });