@try-works/dsh-memory 0.1.32 → 0.2.1

package/src/assets/lfs.js

@@ -0,0 +1,169 @@
+// Git LFS: the transport for asset objects.
+//
+// The command runner is injectable and shaped like GitRunner.run in src/git.js: `(argv, opts)`
+// where argv EXCLUDES the `git` executable. Production passes the host's subprocess-backed
+// runner; tests pass a fake, so no test ever runs git. Nothing here executes at import time.
+import { execFile } from 'node:child_process'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+
+/** The rule that makes every object travel through LFS rather than the normal git plumbing. */
+export const GITATTRIBUTES_LINE = 'assets/objects/** filter=lfs diff=lfs merge=lfs -text'
+
+/** The first line of every LFS pointer file (spec v1). */
+const LFS_POINTER_PREFIX = 'version https://git-lfs.github.com/spec/v1'
+
+/** The git LFS binary probe result is cached per store for the life of the process. */
+const availableCache = new Map()
+
+/** In-flight `git lfs install --local` per store; a second capture awaits the first. */
+const installPromises = new Map()
+
+export function gitattributesPath(root) { return join(root, '.gitattributes') }
+
+/**
+ * Default runner: node:child_process with the same result shape as GitRunner.run.
+ * Used only when no runner is injected (the plugin passes the host's subprocess runner).
+ */
+export function defaultCommandRunner(argv, opts = {}) {
+  return new Promise((resolve) => {
+    execFile('git', argv, {
+      cwd: opts.cwd,
+      timeout: opts.timeout ?? 15_000,
+      windowsHide: true,
+      maxBuffer: 4 * 1024 * 1024,
+    }, (error, stdout, stderr) => {
+      if (!error) {
+        resolve({ exitCode: 0, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') })
+        return
+      }
+      const code = typeof error.code === 'number' ? error.code : (error.code === 'ENOENT' ? 127 : 1)
+      resolve({
+        exitCode: code,
+        stdout: String(stdout ?? ''),
+        stderr: String(stderr ?? '') || String(error.message ?? error),
+      })
+    })
+  })
+}
+
+/**
+ * True when the content is a Git LFS POINTER rather than the bytes it stands for. A pointer begins
+ * with the spec version line; the version line alone is not enough if it is not followed by the
+ * line break the format requires, so a PDF whose first words happen to match is not misread.
+ */
+export function isLfsPointer(content) {
+  if (content === undefined || content === null) return false
+  const text = Buffer.isBuffer(content) ? content.subarray(0, 200).toString('utf8') : String(content).slice(0, 200)
+  if (!text.startsWith(LFS_POINTER_PREFIX)) return false
+  const next = text[LFS_POINTER_PREFIX.length]
+  return next === undefined || next === '\n' || next === '\r'
+}
+
+/**
+ * Add the object filter rule to `.gitattributes` if it is not already there. Idempotent: the
+ * existing bytes are never rewritten, only appended to.
+ * @returns {{changed: boolean, created: boolean, error: Error|null}}
+ */
+export function ensureGitattributes(root) {
+  const file = gitattributesPath(root)
+  let existing = ''
+  try { existing = existsSync(file) ? readFileSync(file, 'utf8') : '' } catch (error) {
+    return { changed: false, created: false, error }
+  }
+  if (existing.split('\n').some((line) => line.trim() === GITATTRIBUTES_LINE)) {
+    return { changed: false, created: false, error: null }
+  }
+  const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : ''
+  try {
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, existing + separator + GITATTRIBUTES_LINE + '\n', 'utf8')
+  } catch (error) {
+    return { changed: false, created: false, error }
+  }
+  return { changed: true, created: existing.length === 0, error: null }
+}
+
+/**
+ * Is `git lfs` available to this process? Probes `git lfs version` once per store and caches the
+ * success; a failure is NOT cached, so installing LFS later works without a restart.
+ */
+export async function lfsAvailable({ root, run = defaultCommandRunner, refresh = false } = {}) {
+  const cacheKey = String(root ?? '')
+  if (!refresh && availableCache.get(cacheKey) === true) return true
+  let result
+  try { result = await run(['lfs', 'version'], { cwd: root }) } catch { result = undefined }
+  const ok = result !== undefined && result !== null && (result.exitCode ?? result.code) === 0
+  if (ok) availableCache.set(cacheKey, true)
+  return ok
+}
+
+/**
+ * Run `git lfs install --local` once per store. Only meaningful inside a git work tree: outside
+ * one there is nothing to configure, so that is reported as a no-op rather than a failure.
+ * @returns {Promise<{ok: boolean, installed: boolean, reason?: string}>}
+ */
+export async function ensureLfsInstalled(root, { run = defaultCommandRunner } = {}) {
+  if (!root || !existsSync(join(root, '.git'))) {
+    return { ok: true, installed: false, reason: 'store is not a git repository yet' }
+  }
+  if (!installPromises.has(root)) {
+    installPromises.set(root, (async () => {
+      let result
+      try { result = await run(['lfs', 'install', '--local'], { cwd: root }) } catch (error) {
+        return { ok: false, installed: false, reason: String(error?.message ?? error) }
+      }
+      if (result === undefined || result === null || (result.exitCode ?? result.code) !== 0) {
+        const reason = String(result?.stderr || result?.stdout || 'git lfs install --local failed').trim()
+        return { ok: false, installed: false, reason }
+      }
+      return { ok: true, installed: true }
+    })())
+  }
+  return installPromises.get(root)
+}
+
+/**
+ * The capture-time gate: the filter rule is in place, the binary exists, and (inside a repo) LFS is
+ * enabled locally. Objects are written only after this passes, so a store can never silently fill
+ * with pointer files that look like bytes.
+ * @returns {Promise<{ok: boolean, installed: boolean, gitattributesChanged: boolean, code?: string, message?: string}>}
+ */
+export async function ensureLfs(root, options = {}) {
+  const run = options.run ?? defaultCommandRunner
+  const attributes = ensureGitattributes(root)
+  if (attributes.error) {
+    return {
+      ok: false,
+      installed: false,
+      gitattributesChanged: false,
+      code: 'write-failed',
+      message: 'could not write .gitattributes: ' + String(attributes.error?.message ?? attributes.error),
+    }
+  }
+  const available = await lfsAvailable({ root, run, refresh: options.refresh })
+  if (!available) {
+    return {
+      ok: false,
+      installed: false,
+      gitattributesChanged: attributes.changed,
+      code: 'lfs-unavailable',
+      message: 'git lfs is not available on this machine; install Git LFS before storing assets',
+    }
+  }
+  const installed = await ensureLfsInstalled(root, { run })
+  if (!installed.ok) {
+    return {
+      ok: false,
+      installed: false,
+      gitattributesChanged: attributes.changed,
+      code: 'lfs-unavailable',
+      message: 'git lfs is available but could not be enabled in this repository: ' + (installed.reason ?? 'unknown error'),
+    }
+  }
+  return {
+    ok: true,
+    installed: installed.installed,
+    gitattributesChanged: attributes.changed,
+  }
+}

package/src/assets/objects.js

@@ -0,0 +1,199 @@
+// Content-addressed object blobs + the inventory inside state/assets.json.
+//
+// One object per unique content, independent of name or scope: `assets/objects/<ab>/<sha256>.<ext>`.
+// `refs` counts the asset entries across all scopes that point at the object, so `forget` can delete
+// the blob at zero without walking the blob tree. Everything here is synchronous file work; the
+// only caller that may touch bytes is `get` (and the write itself).
+import { createHash } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { canonicalMime, extensionForMime } from './policy.js'
+import { isLfsPointer } from './lfs.js'
+
+const SHA256 = /^[a-f0-9]{64}$/
+
+/** sha256 of content, lowercase hex. Accepts a Buffer or string. */
+export function sha256(content) {
+  return createHash('sha256').update(content).digest('hex')
+}
+
+export function objectsRoot(root) { return join(root, 'assets', 'objects') }
+
+/**
+ * Root-relative object path: assets/objects/<sha256[0:2]>/<sha256>.<ext>.
+ * The extension is derived from the MIME, not the file name, so the same content always resolves to
+ * the same path regardless of what it was called when it was captured.
+ */
+export function objectRelPath(mime, hash) {
+  const digest = String(hash ?? '')
+  if (!SHA256.test(digest)) throw new Error('invalid sha256: ' + digest)
+  return 'assets/objects/' + digest.slice(0, 2) + '/' + digest + '.' + extensionForMime(mime)
+}
+
+export function objectPath(root, mime, hash) {
+  return join(root, ...objectRelPath(mime, hash).split('/'))
+}
+
+/** Every existing file for one digest, whatever its extension. Used for read and delete fallback. */
+export function objectCandidates(root, hash) {
+  const digest = String(hash ?? '')
+  if (!SHA256.test(digest)) return []
+  const dir = join(objectsRoot(root), digest.slice(0, 2))
+  let names = []
+  try { names = readdirSync(dir).filter((name) => name.startsWith(digest + '.')) } catch { return [] }
+  return names.map((name) => join(dir, name))
+}
+
+/**
+ * Read one object's bytes.
+ * @returns {{ok: true, bytes: Buffer, file: string} | {ok: false, code: string, message: string}}
+ * A missing file and an LFS pointer are both `missing-bytes`: a 130-byte pointer is not the PDF the
+ * caller asked for, and pretending otherwise is the failure this store exists to avoid.
+ */
+export function readObject(root, mime, hash) {
+  const primary = objectPath(root, mime, hash)
+  const candidates = existsSync(primary)
+    ? [primary, ...objectCandidates(root, hash).filter((file) => file !== primary)]
+    : objectCandidates(root, hash)
+  if (candidates.length === 0) {
+    return {
+      ok: false,
+      code: 'missing-bytes',
+      message: 'the bytes for asset ' + hash + ' are missing from assets/objects; run `git lfs pull` in the memory store',
+    }
+  }
+  let lastError
+  for (const file of candidates) {
+    let bytes
+    try { bytes = readFileSync(file) } catch (error) { lastError = error; continue }
+    if (isLfsPointer(bytes)) {
+      return {
+        ok: false,
+        code: 'missing-bytes',
+        message: 'asset ' + hash + ' is a Git LFS pointer, not the bytes; run `git lfs pull` in the memory store',
+      }
+    }
+    return { ok: true, bytes, file }
+  }
+  return {
+    ok: false,
+    code: 'read-failed',
+    message: 'could not read asset ' + hash + ': ' + String(lastError?.message ?? lastError),
+  }
+}
+
+/**
+ * Write one object, creating the sharded directory. An existing complete file is left alone; a
+ * pointer or a truncated file is replaced with the real bytes, so re-capturing heals a clone that
+ * was made without LFS.
+ * @returns {{ok: true, rel: string, file: string, written: boolean} | {ok: false, code: string, message: string}}
+ */
+export function writeObject(root, mime, hash, bytes) {
+  const rel = objectRelPath(mime, hash)
+  const file = join(root, ...rel.split('/'))
+  if (existsSync(file)) {
+    try {
+      const existing = readFileSync(file)
+      if (!isLfsPointer(existing) && existing.length === bytes.length) return { ok: true, rel, file, written: false }
+    } catch { /* rewrite below is the safer answer */ }
+  }
+  try {
+    mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(file, bytes)
+    return { ok: true, rel, file, written: true }
+  } catch (error) {
+    return { ok: false, code: 'write-failed', message: 'could not write asset object: ' + String(error?.message ?? error) }
+  }
+}
+
+/** Delete every file for a digest. @returns how many files were removed. */
+export function deleteObjectFiles(root, hash) {
+  let deleted = 0
+  for (const file of objectCandidates(root, hash)) {
+    try { rmSync(file, { force: true }); deleted += 1 } catch { /* a stuck file must not hide the refcount result */ }
+  }
+  return deleted
+}
+
+/** Bytes physically present for a digest (used when the inventory has drifted). */
+export function objectBytesOnDisk(root, hash) {
+  let total = 0
+  for (const file of objectCandidates(root, hash)) {
+    try { total += statSync(file).size } catch { /* unreadable file contributes nothing */ }
+  }
+  return total
+}
+
+// --- inventory ------------------------------------------------------------------------------
+// The inventory is one map inside state/assets.json. It is read and written through the policy
+// module's state helpers so a policy write and an inventory write share one merge path.
+
+import { readAssetState, writeAssetState } from './policy.js'
+
+function numberOr(value, fallback) {
+  const number = Number(value)
+  return Number.isFinite(number) && number >= 0 ? number : fallback
+}
+
+/** The object inventory: sha256 -> { bytes, mime, refs, created }. */
+export function readInventory(root) {
+  return readAssetState(root).objects
+}
+
+/** The inventory record for one digest, or undefined. */
+export function inventoryObject(root, hash) {
+  const record = readInventory(root)[hash]
+  return record === undefined ? undefined : record
+}
+
+/**
+ * Record one entry's reference to an object. Creates the inventory record on first use and
+ * increments `refs` on every later capture, including a dedupe inside the same scope.
+ * @returns {{added: boolean, refs: number, object: object}}
+ */
+export function upsertObjectRef(root, { sha256: hash, bytes, mime, created } = {}) {
+  const state = readAssetState(root)
+  const existing = state.objects[hash]
+  if (existing !== undefined && existing !== null && typeof existing === 'object') {
+    existing.refs = numberOr(existing.refs, 0) + 1
+    if (!numberOr(existing.bytes, 0) && numberOr(bytes, 0)) existing.bytes = numberOr(bytes, 0)
+    if (!existing.mime && mime) existing.mime = mime
+    writeAssetState(root, state)
+    return { added: false, refs: existing.refs, object: existing }
+  }
+  const record = {
+    bytes: numberOr(bytes, 0),
+    mime: String(mime ?? 'application/octet-stream'),
+    refs: 1,
+    created: created ?? new Date().toISOString(),
+  }
+  state.objects[hash] = record
+  writeAssetState(root, state)
+  return { added: true, refs: 1, object: record }
+}
+
+/**
+ * Drop one reference. At zero the record is removed from the inventory and its logical bytes are
+ * reported so the caller can delete the file and say what was freed.
+ * @returns {{found: boolean, refs: number, bytes: number, removed: boolean}}
+ */
+export function releaseObjectRef(root, hash) {
+  const state = readAssetState(root)
+  const existing = state.objects[hash]
+  if (existing === undefined || existing === null || typeof existing !== 'object') {
+    return { found: false, refs: 0, bytes: 0, removed: false }
+  }
+  const refs = Math.max(0, numberOr(existing.refs, 0) - 1)
+  if (refs === 0) {
+    const bytes = numberOr(existing.bytes, 0)
+    delete state.objects[hash]
+    writeAssetState(root, state)
+    return { found: true, refs: 0, bytes, removed: true }
+  }
+  existing.refs = refs
+  writeAssetState(root, state)
+  return { found: true, refs, bytes: 0, removed: false }
+}
+
+// Re-exported so callers that only need the canonical mime/path pair do not import two modules.
+export { canonicalMime }

package/src/assets/policy.js

@@ -0,0 +1,259 @@
+// Asset policy + classification (pure, except the state/assets.json read/write).
+//
+// `state/assets.json` holds two different things in one file: the per-scope policy (toggles and
+// quotas, which a user or agent narrows) and the object inventory (what the store holds). Reading
+// projects the policy; writing merges it back so a policy edit can never drop the inventory, and an
+// inventory update can never drop an unknown policy field.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { DEFAULT_CONFIG } from '../defaults.js'
+import { sanitizeKey } from '../workspace-key.js'
+
+/** The three asset classes, in the order they are reported. */
+export const ASSET_CLASSES = ['documents', 'media', 'data']
+
+/** Config field controlling each class. */
+export const CLASS_TOGGLE = { documents: 'assetsDocuments', media: 'assetsMedia', data: 'assetsData' }
+
+// One table: [mime, extension, class]. Everything else is derived from it, so the accepted set
+// cannot drift between the classifier, the object path and the refusal message.
+const TYPES = [
+  ['application/pdf', 'pdf', 'documents'],
+  ['application/vnd.openxmlformats-officedocument.wordprocessingml.document', 'docx', 'documents'],
+  ['application/vnd.openxmlformats-officedocument.presentationml.presentation', 'pptx', 'documents'],
+  ['text/plain', 'txt', 'documents'],
+  ['text/markdown', 'md', 'documents'],
+  ['text/csv', 'csv', 'data'],
+  ['text/tab-separated-values', 'tsv', 'data'],
+  ['application/json', 'json', 'data'],
+  ['application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', 'xlsx', 'data'],
+  ['image/png', 'png', 'media'],
+  ['image/jpeg', 'jpg', 'media'],
+  ['image/webp', 'webp', 'media'],
+  ['image/gif', 'gif', 'media'],
+]
+
+const MIME_CLASS = new Map(TYPES.map(([mime, , assetClass]) => [mime, assetClass]))
+const MIME_EXTENSION = new Map(TYPES.map(([mime, extension]) => [mime, extension]))
+const EXTENSION_MIME = new Map()
+for (const [mime, extension] of MIME_EXTENSION) EXTENSION_MIME.set(extension, mime)
+// Names people actually have on disk, mapped onto the canonical mime above.
+EXTENSION_MIME.set('jpeg', 'image/jpeg')
+EXTENSION_MIME.set('markdown', 'text/markdown')
+
+/** Lowercase mime without parameters. Undefined when absent. */
+export function normalizeMime(mime) {
+  const text = String(mime ?? '').trim().toLowerCase()
+  if (text === '') return undefined
+  return text.split(';')[0].trim() || undefined
+}
+
+/** Lowercase extension (no dot) from a file name, or undefined. */
+export function extensionOfName(name) {
+  const base = String(name ?? '').split(/[\\/]/).pop() ?? ''
+  const at = base.lastIndexOf('.')
+  if (at <= 0 || at >= base.length - 1) return undefined
+  const extension = base.slice(at + 1).toLowerCase()
+  return /^[a-z0-9]+$/.test(extension) ? extension : undefined
+}
+
+/** Canonical mime for a file name, when the extension is one we know. */
+export function mimeForName(name) {
+  const extension = extensionOfName(name)
+  return extension === undefined ? undefined : EXTENSION_MIME.get(extension)
+}
+
+/** Canonical extension used in an object path. Unknown mime -> 'bin'. */
+export function extensionForMime(mime) {
+  const type = normalizeMime(mime)
+  return (type === undefined ? undefined : MIME_EXTENSION.get(type)) ?? 'bin'
+}
+
+/**
+ * The class that claims a file, from its mime or its name. An explicit, recognized mime wins over
+ * the name; an explicit mime nothing accepts wins too - a `.pdf` that is really a zip is not a
+ * document we can store, and silently believing the extension would be the worse answer.
+ * @returns {'documents'|'media'|'data'|undefined}
+ */
+export function classify({ name, mime } = {}) {
+  const explicit = normalizeMime(mime)
+  if (explicit !== undefined && explicit !== 'application/octet-stream') return MIME_CLASS.get(explicit)
+  const byName = mimeForName(name)
+  return byName === undefined ? undefined : MIME_CLASS.get(byName)
+}
+
+/** The mime stored on the object: an explicit recognized one, else the name's, else octet-stream. */
+export function canonicalMime({ name, mime } = {}) {
+  const explicit = normalizeMime(mime)
+  if (explicit !== undefined && explicit !== 'application/octet-stream') return explicit
+  return mimeForName(name) ?? 'application/octet-stream'
+}
+
+// --- policy file ----------------------------------------------------------------------------
+
+export function policyPath(root) { return join(root, 'state', 'assets.json') }
+
+function plainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {}
+}
+
+function cfgBoolean(cfg, key, fallback) {
+  const value = cfg === undefined || cfg === null ? undefined : cfg[key]
+  return typeof value === 'boolean' ? value : fallback
+}
+
+function cfgNumber(cfg, key, fallback) {
+  const value = cfg === undefined || cfg === null ? undefined : cfg[key]
+  return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : fallback
+}
+
+/**
+ * The whole state file, normalized. Exported for the inventory: one reader, so policy and objects
+ * can never disagree about what the file says.
+ */
+export function readAssetState(root) {
+  let parsed
+  try { parsed = JSON.parse(readFileSync(policyPath(root), 'utf8')) } catch { parsed = undefined }
+  const base = plainObject(parsed)
+  return {
+    ...base,
+    version: Number.isInteger(base.version) ? base.version : 1,
+    global: plainObject(base.global),
+    workspaces: plainObject(base.workspaces),
+    objects: plainObject(base.objects),
+    quotaNotices: Array.isArray(base.quotaNotices) ? base.quotaNotices : [],
+  }
+}
+
+export function writeAssetState(root, state) {
+  mkdirSync(join(root, 'state'), { recursive: true })
+  writeFileSync(policyPath(root), JSON.stringify(state, null, 2) + '\n', 'utf8')
+}
+
+/** The policy projection: toggles and quotas only, never the inventory. */
+export function readPolicy(root) {
+  const state = readAssetState(root)
+  return { version: state.version, global: state.global, workspaces: state.workspaces }
+}
+
+/**
+ * Merge a policy into the state file, preserving the inventory and unknown fields. A field absent
+ * from `policy` is left as it was, so a caller can write only the section it changed.
+ */
+export function writePolicy(root, policy = {}) {
+  const state = readAssetState(root)
+  const next = { ...state }
+  if (policy.version !== undefined) next.version = policy.version
+  if (policy.global !== undefined) next.global = plainObject(policy.global)
+  if (policy.workspaces !== undefined) next.workspaces = plainObject(policy.workspaces)
+  writeAssetState(root, next)
+  return next
+}
+
+// --- toggle resolution ----------------------------------------------------------------------
+
+/**
+ * Effective toggles for one scope. Config is a hard upper bound; a missing policy field does not
+ * narrow anything. A class is on only when every level allows it, so a workspace can narrow itself
+ * but cannot re-enable a class the config or the global policy turned off.
+ * @returns {{enabled: boolean, documents: boolean, media: boolean, data: boolean}}
+ */
+export function resolveToggles(cfg, root, { scope, key } = {}) {
+  const enabled = cfgBoolean(cfg, 'assetsEnabled', DEFAULT_CONFIG.assetsEnabled)
+  const policy = readPolicy(root)
+  const workspaceKey = scope === 'workspace' ? sanitizeKey(key) : undefined
+  const workspacePolicy = workspaceKey === undefined ? {} : plainObject(policy.workspaces[workspaceKey])
+  const toggles = { enabled }
+  for (const assetClass of ASSET_CLASSES) {
+    const configOn = enabled && cfgBoolean(cfg, CLASS_TOGGLE[assetClass], DEFAULT_CONFIG[CLASS_TOGGLE[assetClass]])
+    const globalOn = policy.global[assetClass] !== false
+    const workspaceOn = scope === 'workspace' ? workspacePolicy[assetClass] !== false : true
+    toggles[assetClass] = configOn && globalOn && workspaceOn
+  }
+  return toggles
+}
+
+/**
+ * Why a class may not be captured in this scope, or undefined when it may. Names the level so the
+ * refusal is actionable: "config", "workspace" or "global".
+ * @returns {{level: string, message: string}|undefined}
+ */
+export function toggleRefusal(cfg, root, { scope, key, class: assetClass } = {}) {
+  if (!cfgBoolean(cfg, 'assetsEnabled', DEFAULT_CONFIG.assetsEnabled)) {
+    return { level: 'config', message: assetClass + ' capture is disabled because the asset store is off in config (assetsEnabled)' }
+  }
+  if (!cfgBoolean(cfg, CLASS_TOGGLE[assetClass], DEFAULT_CONFIG[CLASS_TOGGLE[assetClass]])) {
+    return { level: 'config', message: assetClass + ' capture is disabled in config (' + CLASS_TOGGLE[assetClass] + ')' }
+  }
+  // Resolution order is config -> workspace -> global, and the refusal names the first level that
+  // narrowed, because that is the setting the reader needs to change.
+  const policy = readPolicy(root)
+  const workspaceKey = scope === 'workspace' ? sanitizeKey(key) : undefined
+  if (workspaceKey !== undefined) {
+    const workspacePolicy = plainObject(policy.workspaces[workspaceKey])
+    if (workspacePolicy[assetClass] === false) {
+      return { level: 'workspace', message: assetClass + ' capture is disabled by workspace policy for "' + workspaceKey + '"' }
+    }
+  }
+  if (policy.global[assetClass] === false) {
+    return { level: 'global', message: assetClass + ' capture is disabled by the global asset policy' }
+  }
+  return undefined
+}
+
+/** Quota for one scope: the policy's stored override, else the configured value. */
+export function quotaBytesFor(cfg, policy, { scope, key } = {}) {
+  if (scope === 'global') {
+    const stored = Number(policy?.global?.quotaBytes)
+    if (Number.isFinite(stored) && stored >= 0) return stored
+    return cfgNumber(cfg, 'assetsGlobalQuotaBytes', DEFAULT_CONFIG.assetsGlobalQuotaBytes)
+  }
+  const workspaceKey = sanitizeKey(key)
+  const stored = Number(workspaceKey === undefined ? undefined : policy?.workspaces?.[workspaceKey]?.quotaBytes)
+  if (Number.isFinite(stored) && stored >= 0) return stored
+  return cfgNumber(cfg, 'assetsWorkspaceQuotaBytes', DEFAULT_CONFIG.assetsWorkspaceQuotaBytes)
+}
+
+// --- quota notices --------------------------------------------------------------------------
+// An AUTOMATIC capture that hits the quota is not an interactive moment, so it records a notice
+// instead of asking a question. One notice per scope+key: the newest figures win, because the
+// reader wants the current wall, not its history.
+
+function nonNegative(value) {
+  const number = Number(value)
+  return Number.isFinite(number) && number >= 0 ? number : 0
+}
+
+function normalizeNotice(notice = {}) {
+  const scope = notice.scope === 'global' ? 'global' : 'workspace'
+  return {
+    scope,
+    key: scope === 'global' ? null : (sanitizeKey(notice.key) ?? null),
+    at: String(notice.at ?? '') === '' ? new Date().toISOString() : String(notice.at),
+    usedBytes: nonNegative(notice.usedBytes),
+    quotaBytes: nonNegative(notice.quotaBytes),
+  }
+}
+
+/** Record the quota wall an automatic capture met; replaces the notice for that scope+key. */
+export function addQuotaNotice(root, notice = {}) {
+  const state = readAssetState(root)
+  const stored = normalizeNotice(notice)
+  const kept = state.quotaNotices.filter((item) => {
+    if (item === null || typeof item !== 'object') return false
+    const sameScope = (item.scope === 'global' ? 'global' : 'workspace') === stored.scope
+    const itemKey = item.scope === 'global' ? null : (sanitizeKey(item.key) ?? null)
+    return !(sameScope && itemKey === stored.key)
+  })
+  // Bounded: a notice collection is a status board, not a log.
+  writeAssetState(root, { ...state, quotaNotices: [...kept, stored].slice(-50) })
+  return stored
+}
+
+/** Every stored quota notice, newest first. */
+export function readQuotaNotices(root) {
+  return readAssetState(root).quotaNotices
+    .filter((notice) => notice !== null && typeof notice === 'object')
+    .map((notice) => normalizeNotice(notice))
+    .sort((a, b) => String(b.at).localeCompare(String(a.at)))
+}

package/src/config.js

@@ -52,6 +52,18 @@ export const Config = z.object({
   summaryMaxBullets: z.number().default(DEFAULT_CONFIG.summaryMaxBullets),
   consolidateMaxPromptBytes: z.number().default(DEFAULT_CONFIG.consolidateMaxPromptBytes),
   consolidateMaxDigestBytes: z.number().default(DEFAULT_CONFIG.consolidateMaxDigestBytes),
+
+  // --- config-file only: asset store ---
+  // A hard upper bound, on top of the per-scope policy in state/assets.json. Off by default:
+  // storing files is an explicit choice, and a disabled class refuses rather than drops.
+  assetsEnabled: z.boolean().default(DEFAULT_CONFIG.assetsEnabled),
+  assetsDocuments: z.boolean().default(DEFAULT_CONFIG.assetsDocuments),
+  assetsMedia: z.boolean().default(DEFAULT_CONFIG.assetsMedia),
+  assetsData: z.boolean().default(DEFAULT_CONFIG.assetsData),
+  assetsMaxBytes: z.number().default(DEFAULT_CONFIG.assetsMaxBytes),
+  assetsWorkspaceQuotaBytes: z.number().default(DEFAULT_CONFIG.assetsWorkspaceQuotaBytes),
+  assetsGlobalQuotaBytes: z.number().default(DEFAULT_CONFIG.assetsGlobalQuotaBytes),
+  assetsDescribe: z.boolean().default(DEFAULT_CONFIG.assetsDescribe),
 })
 
 export default Config

package/src/defaults.js

@@ -48,6 +48,17 @@ export const DEFAULT_CONFIG = Object.freeze({
   rerankSearch: false,
   injectionMaxChars: 3_600,
   injectionRefreshMs: 900_000,
+  // Asset store (documents / media / data). The master switch is OFF: nothing is captured and
+  // every asset tool refuses until it is turned on. Once on, the three class toggles default to
+  // true so the common case is one switch; per-scope narrowing lives in state/assets.json.
+  assetsEnabled: false,
+  assetsDocuments: true,
+  assetsMedia: true,
+  assetsData: true,
+  assetsMaxBytes: 50 * 1024 * 1024,                 // 50 MB per file
+  assetsWorkspaceQuotaBytes: 1024 * 1024 * 1024,    // 1 GB per workspace
+  assetsGlobalQuotaBytes: 1024 * 1024 * 1024,       // 1 GB for the global scope
+  assetsDescribe: true,                             // one model call per captured asset
 })
 
 /**