@try-works/dsh-memory 0.1.32 → 0.2.0

package/src/tools.js

@@ -1,18 +1,22 @@
-// Agent tools: memory_search / remember / workspaces / associate / sync / forget.
-import { realpathSync } from 'node:fs'
-import { isAbsolute, resolve } from 'node:path'
+// Agent tools: memory_search / remember / workspaces / associate / sync / forget, plus the
+// memory_asset_* surface of the asset store.
+import { existsSync, realpathSync, statSync } from 'node:fs'
+import { basename, isAbsolute, resolve } from 'node:path'
+import { BlockAssembler } from '@deepseek-ai/dsh-llm'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { search } from './search.js'
 import { remember } from './remember.js'
 import { summarizeState, writeStateSection } from './state.js'
 import { rerankHits } from './rerank.js'
-import { logRun } from './telemetry.js'
+import { logRun, record } from './telemetry.js'
 import { isSubagentSession } from './session.js'
 import { appendActivity, clearActivity, readWorking, workingSummary, writeWorkingSection } from './working.js'
 import { associate, listWorkspaces } from './workspace.js'
 import { forget, forgetUndo } from './forget.js'
 import { buildMap } from './map.js'
 import { backupTasks, defaultSchedulePath, describeTask, listTasks, planRestore, readScheduleStore, TASK_STATES, writeTask } from './tasks.js'
+import { parseModelRef } from './defaults.js'
+import { describeAsset, usedForFrom } from './assets/describe.js'
 
 function renderHits(hits) {
   if (!hits || hits.length === 0) return [{ type: 'text', text: '(no memory matches)' }]
@@ -104,6 +108,313 @@ export function registerTools(ctx, store, extras = {}) {
   const tasksRestore = extras.tasksRestore
   const schedulePathOf = extras.schedulePath
 
+  // ---------------------------------------------------------------------------------------------
+  // Asset store surface
+  //
+  // src/assets/index.js is loaded LAZILY, at the first asset call that needs it. Two reasons:
+  // the module is a different owner's work in flight (a top-level import would make the whole
+  // plugin unloadable if it were temporarily missing), and nothing should touch the store until
+  // an asset operation actually runs. `extras.assets` is the test/embedding seam - production
+  // passes nothing and the real module is imported.
+  // ---------------------------------------------------------------------------------------------
+  let assetsModulePromise
+  const assetsOverride = extras.assets
+  async function assetsApi() {
+    if (assetsOverride) return assetsOverride
+    assetsModulePromise = assetsModulePromise ?? import('./assets/index.js')
+    return assetsModulePromise
+  }
+
+  /** The resolved configuration. MemoryStore already holds it (src/store.js: this.config). */
+  function assetConfig() { return store.config ?? {} }
+
+  function formatBytes(bytes) {
+    const value = Number(bytes) || 0
+    if (value >= 1024 * 1024 * 1024) return (value / (1024 * 1024 * 1024)).toFixed(1) + ' GB'
+    if (value >= 1024 * 1024) return (value / (1024 * 1024)).toFixed(1) + ' MB'
+    if (value >= 1024) return (value / 1024).toFixed(1) + ' KB'
+    return value + ' bytes'
+  }
+
+  /**
+   * The git runner assets-core needs for its LFS gate. Services are resolved at USE - this runs
+   * inside putAsset, during a tool call, when the host is fully mounted - never at wire time.
+   */
+  async function assetGitRunner(argv, options = {}) {
+    const subprocess = ctx.get('subprocess')
+    if (!subprocess || typeof subprocess.spawn !== 'function' || typeof subprocess.resolveExecutable !== 'function') {
+      return { exitCode: 127, stdout: '', stderr: 'subprocess service unavailable' }
+    }
+    let executable
+    try { executable = await subprocess.resolveExecutable('git', undefined, undefined) } catch { executable = null }
+    if (!executable) return { exitCode: 127, stdout: '', stderr: 'git unavailable' }
+    try {
+      const handle = subprocess.spawn({
+        argv: [executable, ...argv],
+        cwd: options.cwd,
+        stdio: { stdin: 'ignore', stdout: { maxBytes: 4 * 1024 * 1024 }, stderr: { maxBytes: 16 * 1024 } },
+        graceMs: 2000,
+        env: { GIT_CONFIG_COUNT: '0', GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0', LC_ALL: 'C' },
+      })
+      const outcome = await handle.done
+      const stdout = handle.collected?.stdout?.readFrom?.(0)?.text ?? ''
+      const stderr = handle.collected?.stderr?.readFrom?.(0)?.text ?? ''
+      return { exitCode: outcome?.exitCode ?? null, stdout, stderr }
+    } catch (error) {
+      return { exitCode: 1, stdout: '', stderr: String(error) }
+    }
+  }
+
+  /**
+   * One async (prompt) => text for the description model, or undefined when nothing is routable.
+   * Resolved at use from the live services: the configured memory model first, then the session's
+   * route, then anything the registry can enumerate. The description is optional by design, so
+   * every failure here ends in describe.js's deterministic fallback rather than in a failed put.
+   */
+  async function assetDescribeLlm(agent) {
+    const llm = ctx.get('llm')
+    if (!llm || typeof llm.stream !== 'function') return undefined
+    const cfg = assetConfig()
+    const configured = parseModelRef(cfg.summaryModel)
+    const header = agent?.session?.requestHeader?.()?.config
+    const sessionRoute = header && header.provider && header.model ? { provider: header.provider, model: header.model } : undefined
+    let target = configured ?? sessionRoute
+    if (!target) {
+      try {
+        for (const provider of llm.listProviders?.() ?? []) {
+          try {
+            const models = await llm.listModels(provider.id)
+            if (models && models.length > 0) { target = { provider: provider.id, model: models[0].id }; break }
+          } catch { /* one unroutable provider must not hide the description */ }
+        }
+      } catch { /* fall through to the deterministic fallback */ }
+    }
+    if (!target) return undefined
+    return async (prompt) => {
+      record(store.root, 'model-call', { modelCalls: 1, purpose: 'asset-describe', detail: { provider: target.provider, model: target.model } })
+      const assembler = new BlockAssembler()
+      for await (const chunk of llm.stream({
+        provider: target.provider,
+        model: target.model,
+        messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
+        maxTokens: 700,
+        purpose: 'asset-describe',
+      })) assembler.push(chunk)
+      return assembler.blocks().filter((block) => block && block.type === 'text').map((block) => block.text || '').join('\n').trim()
+    }
+  }
+
+  /** The describe hook assets-core awaits inside putAsset: one model call, never file contents. */
+  async function assetDescribeHook(agent) {
+    // assetsDescribe: false is the "never spend a model call on documentation" switch. When it is
+    // off, no hook is passed and the store's own deterministic floor writes the sections.
+    if (assetConfig().assetsDescribe === false) return undefined
+    const llm = await assetDescribeLlm(agent)
+    return (context) => describeAsset(context, { llm })
+  }
+
+  /** The durable attachment reference -> the bytes or a host path putAsset can copy. */
+  async function attachmentSource(attachment) {
+    const attachments = ctx.get('attachments')
+    if (!attachments) {
+      throw new Error('memory_asset_put: reading an attachment needs the attachments service, which is unavailable here; pass path or base64 instead')
+    }
+    const ref = typeof attachment === 'string' ? { attachmentId: attachment } : (attachment ?? {})
+    const image = ref.kind === 'image' || (typeof ref.mediaType === 'string' && ref.mediaType.startsWith('image/'))
+    if (image) {
+      // A durable image reference often has no display name. The store classifies and names by the
+      // media type, so synthesize the extension rather than passing an unnameable blob through.
+      const name = ref.name ?? ('image.' + ({ 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp', 'image/gif': 'gif' }[ref.mediaType] ?? 'png'))
+      const hostPath = typeof attachments.imageHostPath === 'function' ? attachments.imageHostPath(ref) : undefined
+      if (hostPath && existsSync(hostPath)) return { path: hostPath, name, mime: ref.mediaType }
+      if (typeof attachments.readImage !== 'function') throw new Error('memory_asset_put: this attachment provider cannot read images; pass path or base64 instead')
+      const stored = await attachments.readImage(ref)
+      return { bytes: stored?.data, name, mime: ref.mediaType }
+    }
+    if (!ref.name) throw new Error('memory_asset_put: a file attachment needs its name to be resolved; pass the durable reference as it appears in the message')
+    const fileRef = { attachmentId: ref.attachmentId, name: ref.name, bytes: ref.bytes }
+    const hostPath = typeof attachments.fileHostPath === 'function' ? attachments.fileHostPath(fileRef) : undefined
+    if (hostPath && existsSync(hostPath)) return { path: hostPath, name: ref.name }
+    if (typeof attachments.readFileStream !== 'function') throw new Error('memory_asset_put: this attachment provider cannot read files; pass path or base64 instead')
+    const chunks = []
+    for await (const chunk of attachments.readFileStream(fileRef)) chunks.push(Buffer.from(chunk))
+    return { bytes: Buffer.concat(chunks), name: ref.name }
+  }
+
+  /**
+   * How many bytes a capture carries, for quota arithmetic. Only the two shapes putAsset accepts
+   * are measured; anything else counts as zero and the store's own check remains the authority.
+   */
+  function captureBytes(input) {
+    if (input.bytes && typeof input.bytes.byteLength === 'number') return input.bytes.byteLength
+    if (input.path) {
+      try { return statSync(input.path).size } catch { return 0 }
+    }
+    return 0
+  }
+
+  function scopeQuota(policy, scope, key) {
+    if (scope === 'workspace') {
+      const entry = policy.workspaces?.[key]
+      return entry && Number.isFinite(entry.quotaBytes) ? entry.quotaBytes : undefined
+    }
+    return policy.global && Number.isFinite(policy.global.quotaBytes) ? policy.global.quotaBytes : undefined
+  }
+
+  function setScopeQuota(policy, scope, key, quotaBytes) {
+    if (scope === 'workspace') {
+      policy.workspaces = policy.workspaces ?? {}
+      policy.workspaces[key] = { ...(policy.workspaces[key] ?? {}), quotaBytes }
+    } else {
+      policy.global = { ...(policy.global ?? {}), quotaBytes }
+    }
+    return policy
+  }
+
+  /** The one question a quota refusal may put to the user. Four options, exactly. */
+  function quotaQuestion(detail = {}) {
+    const scopeName = detail.scope === 'workspace'
+      ? 'workspace ' + String(detail.key ?? '')
+      : 'the global scope'
+    const largest = Array.isArray(detail.largest) ? detail.largest : []
+    const listed = largest.length
+      ? largest.map((row) => String(row.name ?? row.id) + ' (' + formatBytes(row.bytes) + ')').join(', ')
+      : '(no other assets in this scope)'
+    return {
+      id: 'asset-quota',
+      header: 'Memory asset quota',
+      question: 'Asset quota reached for ' + scopeName + ' (' + formatBytes(detail.usedBytes) + ' of ' + formatBytes(detail.quotaBytes) + ').',
+      detail: 'The largest assets are: ' + listed + '. '
+        + '"Forget an asset to make room" forgets the largest listed asset(s) until this capture fits. '
+        + '"Raise" doubles this scope\'s quota in state/assets.json. '
+        + 'Nothing is deleted unless you choose Forget.',
+      options: [
+        { label: 'Forgive this capture', description: 'Store this one asset without changing the quota.' },
+        { label: "Raise this workspace's quota", description: 'Double the quota for ' + scopeName + ' and retry.' },
+        { label: 'Forget an asset to make room', description: 'Forget the largest listed asset(s), then retry the capture.' },
+        { label: 'Cancel', description: 'Store nothing; nothing is deleted.' },
+      ],
+    }
+  }
+
+  /** Map a user-questions answer onto one of the four decisions. Unknown answers cancel. */
+  function quotaChoice(answer, question) {
+    const batch = Array.isArray(answer?.answers) ? answer.answers : []
+    const item = batch.find((entry) => entry && entry.id === question.id) ?? batch[0]
+    const selected = Array.isArray(item?.selected) ? item.selected : []
+    const text = [selected[0], item?.custom].filter(Boolean).join(' ').toLowerCase()
+    if (text.includes('forgive')) return 'forgive'
+    if (text.includes('raise')) return 'raise'
+    if (text.includes('forget')) return 'forget'
+    return 'cancel'
+  }
+
+  /**
+   * Put one asset, and if the scope quota refuses it, ASK THE USER (exactly once) and act.
+   *
+   * This is the only path that asks: an explicit memory_asset_put has a caller waiting for the
+   * answer. Automatic attachment capture stays silent and records a notice instead. Each answer
+   * has a distinct effect:
+   *   Forgive - retry once with allowOverQuota (the store's one-shot bypass); policy unchanged.
+   *   Raise   - double the scope quota in the policy, then retry normally.
+   *   Forget  - forget the largest listed asset(s) until the capture fits, then retry.
+   *   Cancel  - return the refusal untouched; nothing is stored and nothing is deleted.
+   * A missing or failing user-questions service degrades to the plain refusal.
+   */
+  async function putAssetWithQuotaDecision(assets, input, exec) {
+    const cfg = assetConfig()
+    const first = await assets.putAsset(store, cfg, input)
+    if (first?.ok || first?.code !== 'quota-exceeded') return first
+    const questions = ctx.get('userQuestions')
+    if (!questions || typeof questions.ask !== 'function') return first
+    const detail = first.detail ?? {}
+    const question = quotaQuestion(detail)
+    let answer
+    try {
+      answer = await questions.ask({
+        questions: [question],
+        ...(exec?.agent ? { agent: exec.agent } : {}),
+        ...(exec?.signal ? { signal: exec.signal } : {}),
+      })
+    } catch {
+      // Asking failed (headless, aborted, no answerer): the refusal is the honest result.
+      return first
+    }
+    const choice = quotaChoice(answer, question)
+    if (choice === 'forgive') {
+      return assets.putAsset(store, cfg, { ...input, allowOverQuota: true })
+    }
+    if (choice === 'raise') {
+      try {
+        const policy = assets.readPolicy(store.root)
+        const current = Number(detail.quotaBytes) || scopeQuota(policy, detail.scope, detail.key) || 0
+        const next = Math.max(current * 2, (Number(detail.usedBytes) || 0) + captureBytes(input))
+        if (Number.isSafeInteger(next) && next > 0) {
+          assets.writePolicy(store.root, setScopeQuota(policy, detail.scope, detail.key, next))
+        }
+      } catch { /* an unwritable policy degrades to the refusal the retry will produce */ }
+      return assets.putAsset(store, cfg, input)
+    }
+    if (choice === 'forget') {
+      const deficit = Math.max(0, (Number(detail.usedBytes) || 0) + captureBytes(input) - (Number(detail.quotaBytes) || 0))
+      let freed = 0
+      for (const candidate of Array.isArray(detail.largest) ? detail.largest : []) {
+        if (freed >= deficit) break
+        try {
+          const result = await assets.forgetAsset(store, cfg, { id: candidate.id })
+          if (result?.ok) freed += Number(result.bytesFreed) || 0
+        } catch { /* keep trying the next listed asset */ }
+      }
+      return assets.putAsset(store, cfg, input)
+    }
+    return first
+  }
+
+  /** Turn a putAsset result into the tool's lossless, honest JSON. */
+  function putResultValue(result, { scope, key }) {
+    if (result && result.ok === true) {
+      const id = String(result.entryId ?? '')
+      return {
+        ok: true,
+        id,
+        // Both names, because the store's contract calls it entryId and every memory_* tool calls
+        // the same thing id; an agent reading either should not have to guess.
+        entryId: id,
+        sha256: String(result.sha256 ?? ''),
+        bytes: Number(result.bytes) || 0,
+        deduped: Boolean(result.deduped),
+        ...(result.entryPath ? { file: String(result.entryPath) } : {}),
+        scope,
+        ...(key ? { key: String(key) } : {}),
+      }
+    }
+    const failure = result && typeof result === 'object' ? result : { code: 'write-failed', message: 'the asset store returned no result' }
+    const code = String(failure.code ?? 'write-failed')
+    return {
+      ok: false,
+      code,
+      message: String(failure.message ?? 'the capture was refused'),
+      ...(failure.detail && typeof failure.detail === 'object' ? { detail: failure.detail } : {}),
+      ...(code === 'lfs-unavailable' ? { hint: 'This store syncs asset bytes through Git LFS. Install `git lfs` on the host and retry; nothing was stored.' } : {}),
+      scope,
+      ...(key ? { key: String(key) } : {}),
+    }
+  }
+
+  /** Turn any other contract refusal into the tool's lossless, honest JSON. */
+  function refusalValue(result, { hint } = {}) {
+    const failure = result && typeof result === 'object' ? result : { code: 'read-failed', message: 'the asset store returned no result' }
+    const code = String(failure.code ?? 'read-failed')
+    return {
+      ok: false,
+      code,
+      message: String(failure.message ?? 'the asset operation was refused'),
+      ...(failure.detail && typeof failure.detail === 'object' ? { detail: failure.detail } : {}),
+      ...(hint ? { hint } : {}),
+    }
+  }
+
+
   ctx.tools.register(defineTool({
     name: 'memory_search',
     description: 'Search the dsh-memory store (global + workspace layers). Returns ranked facts with file:line citations.',
@@ -130,6 +441,17 @@ export function registerTools(ctx, store, extras = {}) {
                 snippet: { type: 'string', required: true },
                 id: { type: 'string' },
                 score: { type: 'number' },
+                asset: {
+                  type: 'object', additionalProperties: false,
+                  description: 'Present when the hit is an asset entry: the blob exists and can be fetched.',
+                  properties: {
+                    sha256: { type: 'string', required: true },
+                    mime: { type: 'string', required: true },
+                    name: { type: 'string', required: true },
+                    bytes: { type: 'integer', required: true },
+                    class: { type: 'string', required: true },
+                  },
+                },
               },
             },
           },
@@ -560,6 +882,10 @@ export function registerTools(ctx, store, extras = {}) {
           modelCalls: { type: 'integer' },
           eventCounts: { type: 'object', additionalProperties: true },
           savedBy: { type: 'object', additionalProperties: true },
+          assets: {
+            type: 'object', additionalProperties: true,
+            description: 'Asset bytes and any quota notice an automatic capture could not ask about.',
+          },
           queue: {
             type: 'object', additionalProperties: false,
             properties: {
@@ -589,18 +915,30 @@ export function registerTools(ctx, store, extras = {}) {
           parts.push('needs attention: ' + classes.join(', ') + (attention.length > 3 ? ', +' + (attention.length - 3) + ' more kinds' : ''))
         }
         if (value.conflicted) parts.push('THE LAST SYNC CONFLICTED (see state/CONFLICT.md)')
+        const assets = value.assets
+        if (assets) {
+          const counts = assets.perClass ?? {}
+          parts.push('assets ' + formatBytes(assets.totalBytes) + ' (' + Object.entries(counts).map(([cls, n]) => n + ' ' + cls).join(', ') + ')')
+          const notices = assets.quotaNotices ?? []
+          // A quota wall an automatic capture hit is surfaced here because no one was asked at the
+          // time. It is a notice, not an error: nothing was dropped, and nothing was deleted.
+          if (notices.length) {
+            parts.push('asset quota notices: ' + notices.map((notice) => (notice.scope === 'global' ? 'global' : 'workspace ' + notice.key) + ' (' + formatBytes(notice.usedBytes) + ' of ' + formatBytes(notice.quotaBytes) + ')').join(', '))
+          }
+        }
         parts.push('model calls ' + (value.modelCalls || 0))
         return [{ type: 'text', text: parts.join('; ') + '.' }]
       },
     },
     async execute() {
       if (!statusNow) throw new Error('memory_status is unavailable in this context')
-      const s = statusNow()
+      const s = await statusNow()
       return {
         root: s.root, pendingDigests: s.pendingDigests, conflicted: s.conflicted,
         ...(s.lastSync && typeof s.lastSync.ok === 'boolean' ? { lastSyncOk: s.lastSync.ok } : {}),
         modelCalls: s.metrics?.modelCalls ?? 0, eventCounts: s.metrics?.events ?? {}, savedBy: s.metrics?.savedBy ?? {},
         ...(s.queue ? { queue: s.queue } : {}),
+        ...(s.assets ? { assets: s.assets } : {}),
       }
     },
   }))
@@ -758,11 +1096,11 @@ export function registerTools(ctx, store, extras = {}) {
       if (!syncNow) return { synced: false }
       const status = await syncNow()
       return {
-        // `synced` means SYNCED, not 'it did something'. It used to include committed and
-        // initialized, so a push that FAILED still reported synced:true whenever the local commit
-        // had succeeded - the result read {"synced":true,"conflict":true}, claiming success and
-        // failure at once. A local commit is progress, not a sync, and saying otherwise is the same
-        // defect as every other one this layer has produced: a green answer over a silent failure.
+        // `synced` means SYNCED, not 'it did something'. It used to include committed and
+        // initialized, so a push that FAILED still reported synced:true whenever the local commit
+        // had succeeded - the result read {"synced":true,"conflict":true}, claiming success and
+        // failure at once. A local commit is progress, not a sync, and saying otherwise is the same
+        // defect as every other one this layer has produced: a green answer over a silent failure.
         synced: Boolean(status && status.synced),
         ...(status && status.conflict ? { conflict: true } : {}),
         ...(status && status.error ? { error: String(status.error) } : {}),
@@ -792,6 +1130,393 @@ export function registerTools(ctx, store, extras = {}) {
     },
   }))
 
+  ctx.tools.register(defineTool({
+    name: 'memory_asset_put',
+    description: 'Store a file in the memory asset store: documents (PDF/DOCX/PPTX/TXT/MD), media (PNG/JPEG/WebP/GIF) and data (CSV/TSV/JSON/XLSX), subject to the class toggles. The bytes are deduplicated by sha256 and the entry is documented from the capture context (never by reading the file). Returns the entry id and whether the content was already present. If the scope quota refuses the capture, ONE question is put to the user (forgive / raise / forget / cancel) and the answer is acted on.',
+    parameters: {
+      path: { type: 'string', description: 'Path to the file to store. One of path, base64, or attachment is required.' },
+      base64: { type: 'string', description: 'The file bytes, canonical base64. One of path, base64, or attachment is required.' },
+      attachment: { type: 'object', additionalProperties: true, description: 'A durable attachment reference from a session message: { attachmentId, name?, mediaType?, bytes?, kind? }. One of path, base64, or attachment is required.' },
+      name: { type: 'string', description: 'Display name. Defaults to the file name or a synthesized image name.' },
+      mime: { type: 'string', description: 'Media type. Inferred from the name when omitted; images use the attachment media type.' },
+      class: { type: 'string', description: 'documents, media, or data. Inferred from the name/mime when omitted.' },
+      scope: { type: 'string', description: 'global or workspace. Defaults to the session workspace when there is one, else global.' },
+      workspace: { type: 'string', description: 'Workspace key when scope is workspace.' },
+      userMessage: { type: 'string', description: 'What the user was asking at capture time. This is what the entry is documented from.' },
+      toolCall: { type: 'string', description: 'The action being taken when the file was captured.' },
+      task: { type: 'string', description: 'The task in hand at capture time.' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          id: { type: 'string' },
+          entryId: { type: 'string' },
+          sha256: { type: 'string' },
+          bytes: { type: 'integer' },
+          deduped: { type: 'boolean' },
+          file: { type: 'string' },
+          scope: { type: 'string' },
+          key: { type: 'string' },
+          code: { type: 'string' },
+          message: { type: 'string' },
+          detail: { type: 'object', additionalProperties: true },
+          hint: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: value.ok
+          ? 'Stored ' + (value.id || 'an asset') + ' (' + formatBytes(value.bytes) + ', sha256 ' + String(value.sha256 || '').slice(0, 12) + (value.deduped ? ', content already present' : '') + ')' + (value.file ? ' -> ' + value.file : '') + '.'
+          : 'Not stored (' + value.code + '): ' + value.message + (value.hint ? ' ' + value.hint : ''),
+      }],
+    },
+    async execute(args, exec) {
+      refuseSubagentWrite(exec, 'memory_asset_put')
+      const assets = await assetsApi()
+      const cfg = assetConfig()
+      const inferred = (workspaceOf && exec?.agent) ? await workspaceOf(exec.agent) : undefined
+      let scope = args.scope
+      let key = args.workspace
+      if (scope === undefined) {
+        if (inferred) { scope = 'workspace'; key = key ?? inferred } else scope = 'global'
+      } else if (scope === 'workspace' && !key) {
+        key = inferred
+      }
+      if (scope !== 'global' && scope !== 'workspace') throw new Error('memory_asset_put: scope must be "global" or "workspace"')
+      if (scope === 'workspace' && !key) throw new Error('memory_asset_put: scope workspace needs a workspace key, and none could be inferred for this session. Pass workspace, or use scope global.')
+
+      let source
+      if (args.path) {
+        const base = exec?.agent?.session?.header?.cwd
+        const abs = isAbsolute(args.path) ? args.path : (base ? resolve(base, args.path) : resolve(args.path))
+        if (!existsSync(abs)) throw new Error('memory_asset_put: no such file: ' + abs)
+        let stat
+        try { stat = statSync(abs) } catch { stat = undefined }
+        if (!stat || !stat.isFile()) throw new Error('memory_asset_put: not a regular file: ' + abs)
+        source = { path: abs, name: args.name ?? basename(abs) }
+      } else if (typeof args.base64 === 'string') {
+        const bytes = Buffer.from(args.base64, 'base64')
+        if (bytes.byteLength === 0) {
+          // Honest refusal rather than a throw: an empty payload is a contract failure the same
+          // shape as `missing-bytes`, and the caller can act on it.
+          return { ok: false, code: 'missing-bytes', message: 'base64 decoded to zero bytes; nothing to store', scope, ...(key ? { key: String(key) } : {}) }
+        }
+        source = { bytes, name: args.name ?? 'inline.bin' }
+      } else if (args.attachment) {
+        source = await attachmentSource(args.attachment)
+      } else {
+        throw new Error('memory_asset_put needs one of path, base64, or attachment (a durable attachment reference)')
+      }
+
+      const name = args.name ?? source.name ?? (source.path ? basename(source.path) : 'inline.bin')
+      const mime = args.mime ?? source.mime
+      const captureContext = {
+        ...(args.userMessage ? { userMessage: args.userMessage } : {}),
+        ...(args.toolCall ? { toolCall: args.toolCall } : {}),
+        ...(args.task ? { task: args.task } : {}),
+        name,
+        ...(mime ? { mime } : {}),
+        ...(args.class ? { class: args.class } : {}),
+      }
+      const input = {
+        ...(source.path ? { path: source.path } : { bytes: source.bytes }),
+        name,
+        ...(mime ? { mime } : {}),
+        ...(args.class ? { class: args.class } : {}),
+        scope,
+        ...(key ? { key } : {}),
+        context: captureContext,
+        usedFor: usedForFrom(captureContext),
+        describe: await assetDescribeHook(exec?.agent),
+        runner: (argv, options) => assetGitRunner(argv, options),
+      }
+      const result = await putAssetWithQuotaDecision(assets, input, exec)
+      return putResultValue(result, { scope, key })
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_asset_get',
+    description: 'Resolve one stored asset to its metadata, and optionally copy the bytes to a path the agent can open. The only asset tool that touches blob bytes, and it touches exactly one. Reports missing-bytes honestly (an LFS pointer or a pruned object is not data).',
+    parameters: {
+      id: { type: 'string', description: 'Asset entry id (e.g. global-ast-0007).' },
+      sha256: { type: 'string', description: 'Content hash of the asset bytes, when the id is unknown.' },
+      toPath: { type: 'string', description: 'Copy the bytes to this path (relative paths resolve against the session working directory). Omit to read metadata only.' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          metadata: { type: 'object', additionalProperties: true },
+          bytes: { type: 'integer' },
+          path: { type: 'string' },
+          code: { type: 'string' },
+          message: { type: 'string' },
+          detail: { type: 'object', additionalProperties: true },
+          hint: { type: 'string' },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: value.ok
+          ? 'Asset ' + String(value.metadata?.id ?? '') + ': ' + String(value.metadata?.name ?? '') + ' (' + String(value.metadata?.mime ?? '') + ', ' + formatBytes(value.metadata?.bytes) + ', sha256 ' + String(value.metadata?.sha256 ?? '').slice(0, 12) + ')' + (value.path ? ' -> ' + value.path : '') + '.'
+          : 'Could not read the asset (' + value.code + '): ' + value.message + (value.hint ? ' ' + value.hint : ''),
+      }],
+    },
+    async execute(args, exec) {
+      if (!args.id && !args.sha256) throw new Error('memory_asset_get needs id or sha256')
+      const assets = await assetsApi()
+      let toPath = args.toPath
+      if (toPath) {
+        const base = exec?.agent?.session?.header?.cwd
+        toPath = isAbsolute(toPath) ? toPath : (base ? resolve(base, toPath) : resolve(toPath))
+      }
+      const result = await assets.getAsset(store, assetConfig(), {
+        ...(args.id ? { id: args.id } : {}),
+        ...(args.sha256 ? { sha256: args.sha256 } : {}),
+        ...(toPath ? { toPath } : {}),
+      })
+      if (result && result.ok === true) {
+        // Without toPath the store hands back the object BYTES; a tool result must be lossless JSON,
+        // so what travels is the byte count (the metadata already carries the same number).
+        const byteCount = typeof result.bytes === 'number'
+          ? result.bytes
+          : (result.bytes && typeof result.bytes.byteLength === 'number' ? result.bytes.byteLength : undefined)
+        return {
+          ok: true,
+          metadata: result.metadata && typeof result.metadata === 'object' ? result.metadata : {},
+          ...(typeof byteCount === 'number' ? { bytes: byteCount } : {}),
+          ...(result.path ? { path: String(result.path) } : {}),
+        }
+      }
+      return refusalValue(result, {
+        hint: String(result && result.code) === 'missing-bytes'
+          ? 'The bytes are missing from the store (an LFS pointer file, or a pruned object). Run `git lfs pull` in the memory store, then retry; the entry and its metadata are intact.'
+          : undefined,
+      })
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_asset_list',
+    description: 'List stored asset entries by scope, workspace and class, newest first and bounded. Reads entries only - it never walks the blob store.',
+    parameters: {
+      scope: { type: 'string', description: 'global, workspace, or all (default all).' },
+      workspace: { type: 'string', description: 'Workspace key when scope is workspace.' },
+      class: { type: 'string', description: 'documents, media, or data.' },
+      limit: { type: 'integer', description: 'Maximum rows (default 50).' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          scope: { type: 'string' },
+          key: { type: 'string' },
+          assets: { type: 'array', items: { type: 'object', additionalProperties: true } },
+          code: { type: 'string' },
+          message: { type: 'string' },
+          detail: { type: 'object', additionalProperties: true },
+        },
+      },
+      render: (_args, value) => {
+        if (!value.ok) return [{ type: 'text', text: 'Could not list assets (' + value.code + '): ' + value.message }]
+        const rows = value.assets ?? []
+        if (rows.length === 0) return [{ type: 'text', text: '(no stored assets in ' + value.scope + (value.key ? ' ' + value.key : '') + ')' }]
+        return [{
+          type: 'text',
+          text: rows.map((row) => row.id + ' [' + row.class + '] ' + row.name + ' (' + formatBytes(row.bytes) + ', ' + String(row.sha256).slice(0, 12) + ')').join('\n'),
+        }]
+      },
+    },
+    async execute(args, exec) {
+      const assets = await assetsApi()
+      const inferred = (workspaceOf && exec?.agent) ? await workspaceOf(exec.agent) : undefined
+      const scope = args.scope ?? 'all'
+      if (scope !== 'global' && scope !== 'workspace' && scope !== 'all') throw new Error('memory_asset_list: scope must be "global", "workspace", or "all"')
+      const key = scope === 'workspace' ? (args.workspace ?? inferred) : args.workspace
+      if (scope === 'workspace' && !key) throw new Error('memory_asset_list: scope workspace needs a workspace key, and none could be inferred for this session')
+      const result = await assets.listAssets(store, {
+        scope,
+        ...(key ? { key } : {}),
+        ...(args.class ? { class: args.class } : {}),
+        limit: args.limit ?? 50,
+      })
+      if (result && result.ok === true) {
+        return {
+          ok: true,
+          scope,
+          ...(scope === 'workspace' ? { key } : {}),
+          assets: Array.isArray(result.assets) ? result.assets : [],
+        }
+      }
+      return refusalValue(result)
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_asset_forget',
+    description: 'Delete one asset entry. The content-addressed object is deleted only when its last reference is gone, so another scope that stores the same bytes keeps them.',
+    parameters: {
+      id: { type: 'string', required: true, description: 'Asset entry id (e.g. global-ast-0007).' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          entryId: { type: 'string' },
+          objectDeleted: { type: 'boolean' },
+          bytesFreed: { type: 'integer' },
+          code: { type: 'string' },
+          message: { type: 'string' },
+          detail: { type: 'object', additionalProperties: true },
+        },
+      },
+      render: (_args, value) => [{
+        type: 'text',
+        text: value.ok
+          ? 'Forgot ' + value.entryId + ' (' + formatBytes(value.bytesFreed) + ' freed' + (value.objectDeleted ? ', the object was deleted' : ', the object is still referenced elsewhere') + ').'
+          : 'Could not forget (' + value.code + '): ' + value.message,
+      }],
+    },
+    async execute(args, exec) {
+      refuseSubagentWrite(exec, 'memory_asset_forget')
+      const assets = await assetsApi()
+      const result = await assets.forgetAsset(store, assetConfig(), { id: args.id })
+      if (result && result.ok === true) {
+        return {
+          ok: true,
+          entryId: String(result.entryId ?? args.id),
+          objectDeleted: Boolean(result.objectDeleted),
+          bytesFreed: Number(result.bytesFreed) || 0,
+        }
+      }
+      return refusalValue(result)
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'memory_asset_policy',
+    description: 'Read or set the per-scope asset toggles (documents, media, data) and the scope quota. The profile config is a hard upper bound: a class switched off there cannot be turned back on here, and the refusal names the level. Turning a class off is narrowing, never deletion - stored assets stay readable and searchable.',
+    parameters: {
+      scope: { type: 'string', description: 'global or workspace. Defaults to the session workspace when there is one, else global.' },
+      workspace: { type: 'string', description: 'Workspace key when scope is workspace.' },
+      documents: { type: 'boolean', description: 'Allow documents capture in this scope.' },
+      media: { type: 'boolean', description: 'Allow media capture in this scope.' },
+      data: { type: 'boolean', description: 'Allow data capture in this scope.' },
+      quotaBytes: { type: 'integer', description: 'Byte quota for this scope (positive integer).' },
+    },
+    output: {
+      schema: {
+        type: 'object', additionalProperties: false,
+        properties: {
+          ok: { type: 'boolean', required: true },
+          scope: { type: 'string' },
+          key: { type: 'string' },
+          config: { type: 'object', additionalProperties: true },
+          policy: { type: 'object', additionalProperties: true },
+          effective: { type: 'object', additionalProperties: true },
+          changed: { type: 'object', additionalProperties: true },
+          level: { type: 'string' },
+          detail: { type: 'object', additionalProperties: true },
+          code: { type: 'string' },
+          message: { type: 'string' },
+        },
+      },
+      render: (_args, value) => {
+        if (!value.ok) return [{ type: 'text', text: 'Policy unchanged (' + value.code + '): ' + value.message }]
+        const e = value.effective ?? {}
+        return [{
+          type: 'text',
+          text: 'Asset policy for ' + value.scope + (value.key ? ' ' + value.key : '') + ': '
+            + 'documents ' + (e.documents ? 'on' : 'off') + ', media ' + (e.media ? 'on' : 'off') + ', data ' + (e.data ? 'on' : 'off')
+            + (value.changed ? ' (changed: ' + Object.entries(value.changed).map(([k, v]) => k + '=' + String(v)).join(', ') + ')' : ''),
+        }]
+      },
+    },
+    async execute(args, exec) {
+      // Reading the policy is a harmless READ, allowed from a subagent. Only a change is a WRITE.
+      const writes = args.documents !== undefined || args.media !== undefined || args.data !== undefined || args.quotaBytes !== undefined
+      if (writes) refuseSubagentWrite(exec, 'memory_asset_policy')
+      const assets = await assetsApi()
+      const cfg = assetConfig()
+      const inferred = (workspaceOf && exec?.agent) ? await workspaceOf(exec.agent) : undefined
+      let scope = args.scope
+      let key = args.workspace
+      if (scope === undefined) {
+        if (inferred) { scope = 'workspace'; key = key ?? inferred } else scope = 'global'
+      } else if (scope === 'workspace' && !key) {
+        key = inferred
+      }
+      if (scope !== 'global' && scope !== 'workspace') throw new Error('memory_asset_policy: scope must be "global" or "workspace"')
+      if (scope === 'workspace' && !key) throw new Error('memory_asset_policy: scope workspace needs a workspace key, and none could be inferred for this session')
+
+      const config = {
+        enabled: cfg.assetsEnabled === true,
+        documents: cfg.assetsDocuments !== false,
+        media: cfg.assetsMedia !== false,
+        data: cfg.assetsData !== false,
+      }
+      const policy = assets.readPolicy(store.root)
+      const target = scope === 'global'
+        ? { ...(policy.global ?? {}) }
+        : { ...(policy.workspaces?.[key] ?? {}) }
+      const changed = {}
+      const fieldNames = { documents: 'assetsDocuments', media: 'assetsMedia', data: 'assetsData' }
+      for (const cls of ['documents', 'media', 'data']) {
+        if (args[cls] === undefined) continue
+        if (args[cls] === true && !config.enabled) {
+          const message = 'config ' + cls + ': the profile config (assetsEnabled) is a hard upper bound, so a per-scope policy cannot turn asset capture on'
+          return {
+            ok: false, code: 'toggle-off', message, level: 'config',
+            detail: { scope, ...(key ? { key } : {}), class: cls, level: 'config', configField: 'assetsEnabled' },
+            scope, ...(key ? { key } : {}),
+          }
+        }
+        if (args[cls] === true && config[cls] === false) {
+          const field = fieldNames[cls]
+          const message = 'config ' + cls + ': the profile config (' + field + ') is a hard upper bound, so a per-scope policy cannot turn ' + cls + ' back on'
+          return {
+            ok: false, code: 'toggle-off', message, level: 'config',
+            detail: { scope, ...(key ? { key } : {}), class: cls, level: 'config', configField: field },
+            scope, ...(key ? { key } : {}),
+          }
+        }
+        target[cls] = Boolean(args[cls])
+        changed[cls] = Boolean(args[cls])
+      }
+      if (args.quotaBytes !== undefined) {
+        if (!Number.isSafeInteger(args.quotaBytes) || args.quotaBytes <= 0) {
+          throw new Error('memory_asset_policy: quotaBytes must be a positive integer')
+        }
+        target.quotaBytes = args.quotaBytes
+        changed.quotaBytes = args.quotaBytes
+      }
+      if (Object.keys(changed).length > 0) {
+        if (scope === 'global') policy.global = target
+        else {
+          policy.workspaces = policy.workspaces ?? {}
+          policy.workspaces[key] = target
+        }
+        assets.writePolicy(store.root, policy)
+      }
+      const effective = assets.resolveToggles(cfg, store.root, { scope, ...(key ? { key } : {}) })
+      return {
+        ok: true,
+        scope,
+        ...(scope === 'workspace' ? { key } : {}),
+        config,
+        policy: target,
+        effective,
+        ...(Object.keys(changed).length > 0 ? { changed } : {}),
+      }
+    },
+  }))
+
   ctx.tools.register(defineTool({
     name: 'memory_consolidate',
     description: 'Consolidate pending captured session digests into durable memory entries (LLM pass). Forces memory to update now instead of waiting for the automatic cadence.',