@theseus-whale/dsh-continuity 0.0.0-stage → 4.12.2

package/models/Xenova/bge-small-zh-v1.5/tokenizer_config.json

@@ -0,0 +1,15 @@
+{
+  "clean_up_tokenization_spaces": true,
+  "cls_token": "[CLS]",
+  "do_basic_tokenize": true,
+  "do_lower_case": false,
+  "mask_token": "[MASK]",
+  "model_max_length": 512,
+  "never_split": null,
+  "pad_token": "[PAD]",
+  "sep_token": "[SEP]",
+  "strip_accents": null,
+  "tokenize_chinese_chars": true,
+  "tokenizer_class": "BertTokenizer",
+  "unk_token": "[UNK]"
+}

package/package.json

@@ -1,6 +1,141 @@
 {
   "name": "@theseus-whale/dsh-continuity",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.12.2",
+  "description": "Band-controlled compaction with session-scoped pointer indexes, persona-scoped A/B/C/K memory, verifiable pass receipts, and read-only retrieval for DeepSeek Harness",
+  "type": "module",
+  "license": "MIT",
+  "main": "./src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./engine": "./src/engine.mjs",
+    "./policy": "./src/policy.mjs",
+    "./provenance": "./src/provenance.mjs",
+    "./range": "./src/range.mjs",
+    "./session-log": "./src/session-log.mjs",
+    "./session-log-tool": "./src/session-log-tool.mjs",
+    "./threads": "./src/threads.mjs",
+    "./threads-tool": "./src/threads-tool.mjs",
+    "./threads-core": "./src/threads-core.mjs",
+    "./threads-store": "./src/threads-store.mjs",
+    "./threads-backend": "./src/threads-backend.mjs",
+    "./tags": "./src/tags.mjs",
+    "./tags-store": "./src/tags-store.mjs",
+    "./folds-store": "./src/folds-store.mjs",
+    "./deleted-store": "./src/deleted-store.mjs",
+    "./tag-reject": "./src/tag-reject.mjs",
+    "./tool-preview": "./src/tool-preview.mjs",
+    "./client": "./client.js",
+    "./locale/*.json": "./locale/*.json",
+    "./icon": "./icon.svg",
+    "./package.json": "./package.json",
+    "./facets/schema": "./src/facets/schema.mjs",
+    "./facets/extract": "./src/facets/extract.mjs",
+    "./facets/index": "./src/facets/index.mjs",
+    "./facets/scanner": "./src/facets/scanner.mjs",
+    "./facets/classifier": "./src/facets/classifier.mjs",
+    "./facets/hybrid": "./src/facets/hybrid.mjs",
+    "./facets/service": "./src/facets/service.mjs",
+    "./facets/store": "./src/facets/store.mjs",
+    "./memory/event-log": "./src/memory/event-log.mjs",
+    "./memory/bm25": "./src/memory/bm25.mjs",
+    "./memory/summary-tree": "./src/memory/summary-tree.mjs",
+    "./memory/vector-index": "./src/memory/vector-index.mjs",
+    "./memory/planner": "./src/memory/planner.mjs",
+    "./memory/tokenize": "./src/memory/tokenize.mjs",
+    "./memory/event-model": "./src/memory/event-model.mjs",
+    "./memory/term-extractor": "./src/memory/term-extractor.mjs",
+    "./memory/referent-ledger": "./src/memory/referent-ledger.mjs",
+    "./memory/event-summary-tree": "./src/memory/event-summary-tree.mjs",
+    "./memory/calibration": "./src/memory/calibration.mjs",
+    "./memory/pre-turn": "./src/memory/pre-turn.mjs",
+    "./memory/language-router": "./src/memory/language-router.mjs",
+    "./memory/extraction-core": "./src/memory/extraction-core.mjs",
+    "./memory/extraction-score": "./src/memory/extraction-score.mjs",
+    "./memory/referent-candidates": "./src/memory/referent-candidates.mjs",
+    "./memory/structured-adapters": "./src/memory/structured-adapters.mjs",
+    "./memory/extraction-adapter": "./src/memory/extraction-adapter.mjs",
+    "./memory/coref-slots": "./src/memory/coref-slots.mjs",
+    "./memory/relik-adapter": "./src/memory/relik-adapter.mjs",
+    "./memory/extraction-provider": "./src/memory/extraction-provider.mjs",
+    "./memory/extraction-composite": "./src/memory/extraction-composite.mjs",
+    "./memory/extraction-pre-step": "./src/memory/extraction-pre-step.mjs",
+    "./peer": "./src/peer.mjs",
+    "./peer-tool": "./src/peer-tool.mjs"
+  },
+  "files": [
+    "src",
+    "client.js",
+    "cordis.patch.yml",
+    "locale/*.json",
+    "icon.svg",
+    "README.md",
+    "RELEASE-NOTES.md",
+    "bin",
+    "models",
+    "templates/rules-safe.md",
+    "templates/cmap.md",
+    "templates/keywords.md",
+    "templates/rules.md",
+    "templates/habits.md",
+    "templates/concepts.md",
+    "templates/rebuild.md",
+    "docs/*.md",
+    "guides",
+    "PANEL.md",
+    "INSTALL.md"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-sidebar",
+        "@deepseek-ai/dsh-client-ui-layout",
+        "@deepseek-ai/dsh-client-locale"
+      ]
+    }
+  },
+  "scripts": {
+    "test": "node test/policy.test.mjs && node test/provenance.test.mjs && node test/range.test.mjs && node test/session-log.test.mjs && node test/tool-preview.test.mjs && node test/stats.test.mjs && node test/threads.test.mjs && node test/tags.test.mjs && node test/tag-reject.test.mjs && node test/tag-detect.test.mjs && node test/user-turn.test.mjs && node test/save-start.test.mjs && node test/backfill.test.mjs && node test/migrate.test.mjs && node test/dispatch-probe.test.mjs && node test/t0.test.mjs && node test/topic.test.mjs && node test/inject-policy.test.mjs && node test/tag-confirm.test.mjs && node test/recheck.test.mjs && node test/tag-maintenance.test.mjs && node test/facets.test.mjs && node test/recall-cue.test.mjs && node test/recall-tool.test.mjs && node test/pointer-only.test.mjs && node test/bc-pre-step.test.mjs && node test/bc-store.test.mjs && node test/bc-recall.test.mjs && node test/special-keywords.test.mjs && node test/peer-smoke.test.mjs && node test/bc-panel-state.test.mjs && node test/recall-source-filter.test.mjs && node test/cmap-file.test.mjs && node test/recall-width.test.mjs && node test/bc-index-updater.test.mjs && node test/session-guard.test.mjs && node test/recall-exact.test.mjs && node test/mechanical-note.test.mjs",
+    "check": "node --check src/index.mjs && node --check src/engine.mjs && node --check src/range.mjs && node --check src/state.mjs && node --check src/session-log.mjs && node --check src/session-log-tool.mjs && node --check src/threads.mjs && node --check src/threads-store.mjs && node --check src/threads-backend.mjs && node --check src/threads-core.mjs && node --check src/threads-tool.mjs && node --check src/tags.mjs && node --check src/tags-store.mjs && node --check src/folds-store.mjs && node --check src/deleted-store.mjs && node --check src/backfill.mjs && node --check src/save-start.mjs && node --check src/user-turn.mjs && node --check src/tag-reject.mjs && node --check src/tag-detect.mjs && node --check src/tool-preview.mjs && node --check client.js && node --check src/tag-maintenance.mjs && node --check src/facets/schema.mjs && node --check src/facets/extract.mjs && node --check src/facets/index.mjs && node --check src/facets/scanner.mjs && node --check bin/facet-mvp.mjs && node --check src/facets/classifier.mjs && node --check src/facets/hybrid.mjs && node --check bin/facet-validate.mjs && node --check bin/facet-scan.mjs && node --check bin/facet-train.mjs && node --check src/facets/worker.mjs && node --check src/facets/service.mjs && node --check src/facets/random.mjs && node --check bin/facet-random-validate.mjs && node --check src/facets/sensitivity.mjs && node --check bin/facet-curve.mjs && node --check src/facets/panel.mjs && node --check src/facets/panel-state.mjs && node --check bin/facet-panel.mjs && node --check src/facets/load.mjs && node --check bin/facet-load.mjs && node --check src/facets/fold-plan.mjs && node --check bin/facet-fold.mjs && node --check src/facets/online-knn.mjs && node --check bin/facet-online-validate.mjs && node --check src/facets/linear-probe.mjs && node --check src/facets/mlp-probe.mjs && node --check src/facets/mlp-worker.mjs && node --check src/facets/mlp-service.mjs && node --check bin/facet-mlp-scan.mjs && node --check src/memory/event-log.mjs && node --check src/memory/bm25.mjs && node --check src/memory/summary-tree.mjs && node --check src/memory/vector-index.mjs && node --check src/memory/planner.mjs && node --check src/memory/tokenize.mjs && node --check bin/memory-build.mjs && node --check bin/memory-build-summary.mjs && node --check bin/memory-build-vector.mjs && node --check bin/memory-query.mjs && node --check bin/memory-eval.mjs && node --check bin/memory-bench.mjs && node --check bin/memory-scale.mjs && node --check bin/memory-dry-run.mjs && node --check bin/memory-loop-test.mjs && node --check bin/memory-replay-hints.mjs && node --check bin/memory-load-gate-replay.mjs && node --check bin/memory-closed-loop.mjs && node --check bin/memory-scenario-test.mjs && node --check bin/memory-event-alias-test.mjs && node --check src/memory/event-model.mjs && node --check src/memory/term-extractor.mjs && node --check src/memory/referent-ledger.mjs && node --check src/memory/event-summary-tree.mjs && node --check src/memory/calibration.mjs && node --check bin/memory-calibration.mjs && node --check src/memory/pre-turn.mjs && node --check bin/memory-pre-turn-harness.mjs && node --check src/memory/language-router.mjs && node --check src/memory/extraction-core.mjs && node --check src/memory/extraction-score.mjs && node --check src/memory/referent-candidates.mjs && node --check src/memory/structured-adapters.mjs && node --check src/memory/extraction-adapter.mjs && node --check bin/memory-extraction-bench.mjs && node --check bin/memory-user-loop.mjs && node --check src/recall-tool.mjs && node --check src/memory/bc-recall.mjs && node --check src/memory/bc-label.mjs && node --check src/memory/bc-pre-step.mjs && node --check src/memory/bc-store.mjs && node --check src/memory/bc-index.mjs && node --check src/memory/bc-shift.mjs && node --check src/memory/bc-panel-state.mjs && node --check src/memory/recall-cue.mjs && node --check bin/plugin-integrity.mjs && node --check src/peer.mjs && node --check src/peer-tool.mjs && node --check src/memory/special-keywords.mjs && node --check bin/bc-add-keywords.mjs && node --check bin/bc-ingest-index.mjs && node --check src/memory/cmap-file.mjs && node --check src/memory/bc-index-updater.mjs && node --check bin/eval-label-rules.mjs && node --check bin/relabel-dry-run.mjs && node -e \"import('./src/memory/relabel-migrate.mjs')\" && node --check src/recall-exact-tool.mjs"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "*",
+    "@deepseek-ai/dsh-agent": "*",
+    "@deepseek-ai/dsh-compaction": "*",
+    "@deepseek-ai/dsh-compaction-basic": "*",
+    "@deepseek-ai/dsh-llm": "*",
+    "@deepseek-ai/dsh-session": "*",
+    "@deepseek-ai/dsh-token-meter": "*",
+    "@deepseek-ai/dsh-tools": "*"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-compaction-basic": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-token-meter": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "compaction",
+    "continuity",
+    "provenance",
+    "context"
+  ],
+  "dependencies": {
+    "@huggingface/transformers": "^4.3.2",
+    "sharp": "^0.35.5"
+  }
+}

package/src/asset-tool.mjs

@@ -0,0 +1,237 @@
+import { join } from 'node:path';
+import { assetMarker, readAssetIndex, writeAsset, writeChildAsset } from './assets.mjs';
+import { eventContentBlocks } from './tool-preview.mjs';
+
+export const name = 'dsh-continuity/asset-tool';
+
+const PARAMETERS = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    action: {
+      type: 'string',
+      enum: ['get', 'list'],
+      description: 'get = one parent-session asset; list = recent parent-session assets.',
+    },
+    seq: {
+      type: 'integer',
+      description: 'get: the original event seq.',
+    },
+    path: {
+      type: 'string',
+      description: 'get: a registered relative path, e.g. assets/parent/image-42-abcd1234.png.',
+    },
+    limit: {
+      type: 'integer',
+      description: 'list: maximum rows (default 20, max 100).',
+    },
+  },
+  required: ['action'],
+};
+
+const CHILD_PARAMETERS = {
+  type: 'object',
+  additionalProperties: false,
+  properties: {
+    action: {
+      type: 'string',
+      enum: ['get', 'list'],
+      description: 'get = one child-session/PTC artifact; list = recent child artifacts.',
+    },
+    childSessionId: {
+      type: 'string',
+      description: 'Child session id, as shown in an [asset-child ...] marker.',
+    },
+    runId: {
+      type: 'string',
+      description: 'Optional PTC run id.',
+    },
+    seq: {
+      type: 'integer',
+      description: 'get: the child event seq.',
+    },
+    path: {
+      type: 'string',
+      description: 'get: a registered relative path, e.g. assets/ptc/run/child/image-...png.',
+    },
+    limit: {
+      type: 'integer',
+      description: 'list: maximum rows (default 20, max 100).',
+    },
+  },
+  required: ['action'],
+};
+
+function defaultHome() {
+  return join(process.env.USERPROFILE ?? process.env.HOME ?? '', '.dsh', 'continuity');
+}
+
+function formatRow(row) {
+  return `${assetMarker(row)} sha256=${row.sha256 ?? '?'} name=${row.name ?? '?'}`;
+}
+
+function formatChildRow(row) {
+  return `${assetMarker(row, 'child')} sha256=${row.sha256 ?? '?'} name=${row.name ?? '?'}`;
+}
+
+export function createSessionAssetTool({ home = defaultHome(), sessionQuery = null } = {}) {
+  return {
+    name: 'session_asset',
+    description: 'Retrieve a folded non-text payload from the current session assets. '
+      + 'Use after session_log shows an [asset-parent ...] marker. '
+      + 'The payload is outside the context; this returns its registered path and metadata, not the bytes.',
+    parameters: PARAMETERS,
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: String(value ?? '') }],
+    },
+    timeoutMs: 20_000,
+    isConcurrencySafe: () => true,
+    async execute(args, exec) {
+      const input = args !== null && typeof args === 'object' ? args : {};
+      const action = input.action;
+      if (action !== 'get' && action !== 'list') {
+        throw new Error('session_asset: action must be "get" or "list".');
+      }
+      const sessionId = exec?.agent?.session?.id ?? exec?.agent?.id;
+      if (sessionId === undefined || sessionId === null) {
+        throw new Error('session_asset: no current session id.');
+      }
+      const rows = (await readAssetIndex({ home, sessionId: String(sessionId) }))
+        .filter((row) => row.owner === 'parent');
+      if (action === 'list') {
+        const limit = Math.min(100, Math.max(1, Number.isInteger(input.limit) ? input.limit : 20));
+        const shown = rows.slice(-limit).reverse();
+        return [
+          `session_asset list · session=${sessionId} · assets=${rows.length}`,
+          ...shown.map(formatRow),
+        ].join('\n');
+      }
+      if (input.seq === undefined && input.path === undefined) {
+        throw new Error('session_asset get: seq or path is required.');
+      }
+      const row = input.path !== undefined
+        ? rows.find((entry) => entry.path === input.path)
+        : rows.find((entry) => Number(entry.seq) === Number(input.seq));
+      if (row === undefined && input.path === undefined && input.seq !== undefined
+        && typeof sessionQuery?.readSession === 'function') {
+        try {
+          const snapshot = await sessionQuery.readSession(String(sessionId));
+          const event = (Array.isArray(snapshot?.events) ? snapshot.events : [])
+            .find((entry) => Number(entry?.seq) === Number(input.seq));
+          const recovered = [];
+          for (const block of eventContentBlocks(event) ?? []) {
+            if (block === null || typeof block !== 'object') continue;
+            if (!['image', 'file', 'audio', 'video'].includes(block.type)) continue;
+            const written = await writeAsset({
+              home,
+              sessionId: String(sessionId),
+              block,
+              seq: input.seq,
+            });
+            if (written.ok) recovered.push(written.row);
+          }
+          if (recovered.length > 0) {
+            return [
+              `session_asset get · session=${sessionId} · recovered from raw seq=${input.seq}`,
+              ...recovered.map(formatRow),
+              `absolute=${join(home, 'sessions', String(sessionId), recovered[0].path)}`,
+            ].join('\n');
+          }
+        } catch { /* fall through to missing */ }
+      }
+      if (row === undefined) {
+        return `session_asset get · session=${sessionId} · no registered asset for ${input.path ?? `seq=${input.seq}`}`;
+      }
+      return [
+        `session_asset get · session=${sessionId}`,
+        formatRow(row),
+        `absolute=${join(home, 'sessions', String(sessionId), row.path)}`,
+      ].join('\n');
+    },
+  };
+}
+
+export function createChildAssetTool({ home = defaultHome(), sessionQuery = null } = {}) {
+  return {
+    name: 'child_asset',
+    description: 'Retrieve a folded child/PTC artifact from the parent session assets. '
+      + 'Use after session_log shows an [asset-child ...] marker. '
+      + 'This returns the registered path and metadata, not the bytes.',
+    parameters: CHILD_PARAMETERS,
+    output: {
+      schema: { type: 'string' },
+      render: (_args, value) => [{ type: 'text', text: String(value ?? '') }],
+    },
+    timeoutMs: 20_000,
+    isConcurrencySafe: () => true,
+    async execute(args, exec) {
+      const input = args !== null && typeof args === 'object' ? args : {};
+      const action = input.action;
+      if (action !== 'get' && action !== 'list') {
+        throw new Error('child_asset: action must be "get" or "list".');
+      }
+      const parentSessionId = exec?.agent?.session?.id ?? exec?.agent?.id;
+      if (parentSessionId === undefined || parentSessionId === null) {
+        throw new Error('child_asset: no current parent session id.');
+      }
+      const rows = (await readAssetIndex({ home, sessionId: String(parentSessionId) }))
+        .filter((row) => row.owner === 'child')
+        .filter((row) => input.childSessionId === undefined || row.childSessionId === input.childSessionId)
+        .filter((row) => input.runId === undefined || row.runId === input.runId);
+      if (action === 'list') {
+        const limit = Math.min(100, Math.max(1, Number.isInteger(input.limit) ? input.limit : 20));
+        const shown = rows.slice(-limit).reverse();
+        return [
+          `child_asset list · session=${parentSessionId} · assets=${rows.length}`,
+          ...shown.map(formatChildRow),
+        ].join('\n');
+      }
+      if (input.seq === undefined && input.path === undefined) {
+        throw new Error('child_asset get: seq or path is required.');
+      }
+      const row = input.path !== undefined
+        ? rows.find((entry) => entry.path === input.path)
+        : rows.find((entry) => Number(entry.seq) === Number(input.seq));
+      if (row === undefined && input.path === undefined
+        && input.childSessionId !== undefined && input.seq !== undefined
+        && typeof sessionQuery?.readSession === 'function') {
+        try {
+          const snapshot = await sessionQuery.readSession(input.childSessionId);
+          const event = (Array.isArray(snapshot?.events) ? snapshot.events : [])
+            .find((entry) => Number(entry?.seq) === Number(input.seq));
+          const blocks = event?.data?.message?.content;
+          const recovered = [];
+          for (const block of Array.isArray(blocks) ? blocks : []) {
+            if (block === null || typeof block !== 'object') continue;
+            if (!['image', 'file', 'audio', 'video'].includes(block.type)) continue;
+            const written = await writeChildAsset({
+              home,
+              parentSessionId: String(parentSessionId),
+              childSessionId: input.childSessionId,
+              runId: input.runId ?? 'adhoc',
+              block,
+              seq: input.seq,
+            });
+            if (written.ok) recovered.push(written.row);
+          }
+          if (recovered.length > 0) {
+            return [
+              `child_asset get · session=${parentSessionId} · recovered from child=${input.childSessionId}`,
+              ...recovered.map(formatChildRow),
+              `absolute=${join(home, 'sessions', String(parentSessionId), recovered[0].path)}`,
+            ].join('\n');
+          }
+        } catch { /* fall through to the missing message */ }
+      }
+      if (row === undefined) {
+        return `child_asset get · session=${parentSessionId} · no registered child asset for ${input.path ?? `seq=${input.seq}`}`;
+      }
+      return [
+        `child_asset get · session=${parentSessionId}`,
+        formatChildRow(row),
+        `absolute=${join(home, 'sessions', String(parentSessionId), row.path)}`,
+      ].join('\n');
+    },
+  };
+}

package/src/assets.mjs

@@ -0,0 +1,244 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+const MIME_EXT = Object.freeze({
+  'image/png': '.png',
+  'image/jpeg': '.jpg',
+  'image/webp': '.webp',
+  'image/gif': '.gif',
+  'image/svg+xml': '.svg',
+  'audio/mpeg': '.mp3',
+  'audio/ogg': '.ogg',
+  'audio/wav': '.wav',
+  'video/mp4': '.mp4',
+  'video/webm': '.webm',
+  'application/pdf': '.pdf',
+  'application/json': '.json',
+  'text/plain': '.txt',
+});
+
+const EXT_MIME = Object.freeze(Object.fromEntries(
+  Object.entries(MIME_EXT).map(([mime, ext]) => [ext, mime]),
+));
+
+function mimeFromPath(value) {
+  const ext = path.extname(String(value ?? '')).toLowerCase();
+  return EXT_MIME[ext] ?? null;
+}
+
+function safeId(value, fallback) {
+  const text = String(value ?? '').replace(/[^a-zA-Z0-9._-]/g, '');
+  return text.length > 0 ? text.slice(0, 160) : fallback;
+}
+
+function safeName(value, fallback = 'asset.bin') {
+  const text = path.basename(String(value ?? '').replaceAll('\\', '/')).replace(/[^a-zA-Z0-9._ -]/g, '');
+  return text.length > 0 ? text.slice(0, 160) : fallback;
+}
+
+function decodeDataUrl(value) {
+  const text = String(value ?? '');
+  const marker = text.indexOf(',');
+  if (!text.startsWith('data:') || marker < 0) return null;
+  const header = text.slice(5, marker);
+  const payload = text.slice(marker + 1);
+  const isBase64 = /;base64(?:;|$)/i.test(header);
+  const mime = header.split(';')[0] || null;
+  return {
+    buffer: Buffer.from(payload, isBase64 ? 'base64' : 'utf8'),
+    mime,
+  };
+}
+
+function attachmentObjectPath(attachmentId) {
+  const match = /^sha256:([a-f0-9]{64})$/i.exec(String(attachmentId ?? ''));
+  if (match === null) return null;
+  const digest = match[1].toLowerCase();
+  return path.join(
+    process.env.USERPROFILE ?? process.env.HOME ?? '',
+    '.dsh',
+    'attachments',
+    'v1',
+    'objects',
+    digest.slice(0, 2),
+    digest,
+  );
+}
+
+/**
+ * Return a local payload for a non-text content block, without fetching URLs.
+ * @returns {{ buffer: Buffer, sourcePath: string|null, mime: string|null }|null}
+ */
+export function blockPayload(block) {
+  if (block === null || typeof block !== 'object') return null;
+  const mime = block.mimeType ?? block.mime ?? block.attachment?.mimeType
+    ?? block.attachment?.mediaType ?? block.attachment?.mime ?? block.source?.media_type ?? null;
+  const raw = block.source?.data ?? block.data ?? block.base64;
+  if (typeof raw === 'string' && raw.length > 0) {
+    const decoded = decodeDataUrl(raw);
+    if (decoded !== null) return { ...decoded, sourcePath: null, mime: mime ?? decoded.mime };
+    try {
+      const buffer = Buffer.from(raw, 'base64');
+      if (buffer.length > 0) return { buffer, sourcePath: null, mime };
+    } catch { /* fall through */ }
+  }
+  const sourcePath = block.attachment?.path ?? block.path ?? block.source?.path;
+  if (typeof sourcePath === 'string' && sourcePath.length > 0 && fs.existsSync(sourcePath)) {
+    return { buffer: fs.readFileSync(sourcePath), sourcePath, mime: mime ?? mimeFromPath(sourcePath) };
+  }
+  const stored = attachmentObjectPath(block.attachment?.attachmentId ?? block.attachmentId);
+  if (stored !== null && fs.existsSync(stored)) {
+    return { buffer: fs.readFileSync(stored), sourcePath: stored, mime: mime ?? mimeFromPath(stored) };
+  }
+  return null;
+}
+
+export function assetKind(block) {
+  return typeof block?.type === 'string' ? block.type : 'file';
+}
+
+export function blockMeta(block) {
+  const kind = assetKind(block);
+  const payload = blockPayload(block);
+  const name = safeName(
+    block?.attachment?.name ?? block?.name ?? block?.fileName ?? block?.source?.name,
+    `${kind}-asset`,
+  );
+  const size = block?.attachment?.size ?? block?.attachment?.bytes ?? block?.size ?? block?.bytes;
+  return {
+    kind,
+    name,
+    mime: payload?.mime ?? block?.mimeType ?? block?.mime
+      ?? mimeFromPath(block?.attachment?.path ?? block?.path ?? block?.source?.path ?? name),
+    bytes: Number.isFinite(size) ? size : (payload?.buffer.length ?? null),
+    sourcePath: payload?.sourcePath ?? null,
+  };
+}
+
+export function sessionAssetsDir(home, sessionId) {
+  return path.join(home, 'sessions', safeId(sessionId, 'unknown'), 'assets');
+}
+
+export function assetRelativePath({ kind, seq, sha256, mime, sourcePath, name, prefix = 'parent' }) {
+  const ext = MIME_EXT[mime] ?? (path.extname(sourcePath ?? name ?? '') || '.bin');
+  return path.posix.join(
+    prefix,
+    `${safeId(kind, 'asset')}-${safeId(seq, '0')}-${String(sha256).slice(0, 8)}${ext}`,
+  );
+}
+
+/**
+ * Write one block payload under the parent session assets and append one index
+ * row. The write is atomic; an existing hash-named file is reused.
+ */
+export async function writeAsset({
+  home,
+  sessionId,
+  block,
+  seq,
+  owner = 'parent',
+  childSessionId = null,
+  runId = null,
+  prefix = 'parent',
+}) {
+  const payload = blockPayload(block);
+  if (payload === null) {
+    return { ok: false, reason: 'no-payload', meta: blockMeta(block) };
+  }
+  const meta = blockMeta(block);
+  const sha256 = createHash('sha256').update(payload.buffer).digest('hex');
+  const relative = assetRelativePath({
+    kind: meta.kind,
+    seq,
+    sha256,
+    mime: meta.mime,
+    sourcePath: meta.sourcePath,
+    name: meta.name,
+    prefix,
+  });
+  const directory = sessionAssetsDir(home, sessionId);
+  const absolute = path.join(directory, relative);
+  await fsp.mkdir(path.dirname(absolute), { recursive: true });
+  if (!fs.existsSync(absolute)) {
+    const temporary = `${absolute}.${randomUUID()}.tmp`;
+    await fsp.writeFile(temporary, payload.buffer, { flag: 'wx' });
+    await fsp.rename(temporary, absolute);
+  }
+  const row = {
+    owner,
+    sessionId: String(sessionId),
+    childSessionId: childSessionId === null ? null : String(childSessionId),
+    runId: runId === null ? null : String(runId),
+    seq: Number(seq),
+    kind: meta.kind,
+    mime: meta.mime,
+    name: meta.name,
+    bytes: payload.buffer.length,
+    sha256,
+    path: path.posix.join('assets', relative),
+    at: new Date().toISOString(),
+  };
+  const indexPath = path.join(directory, 'index.jsonl');
+  const existingRows = await readAssetIndex({ home, sessionId });
+  const existing = existingRows.find((entry) => entry.seq === Number(seq)
+    && entry.sha256 === sha256
+    && entry.path === row.path);
+  if (existing !== undefined) {
+    return { ok: true, row: existing, relative, absolute };
+  }
+  await fsp.appendFile(indexPath, `${JSON.stringify(row)}\n`, 'utf8');
+  return { ok: true, row, relative, absolute };
+}
+
+/** Mirror a child/PTC payload under the parent session's ptc/ namespace. */
+export async function writeChildAsset({
+  home,
+  parentSessionId,
+  childSessionId,
+  runId,
+  block,
+  seq,
+}) {
+  const prefix = path.posix.join(
+    'ptc',
+    safeId(runId, 'run'),
+    safeId(childSessionId, 'child'),
+  );
+  return writeAsset({
+    home,
+    sessionId: parentSessionId,
+    block,
+    seq,
+    owner: 'child',
+    childSessionId,
+    runId,
+    prefix,
+  });
+}
+
+export async function readAssetIndex({ home, sessionId }) {
+  const file = path.join(sessionAssetsDir(home, sessionId), 'index.jsonl');
+  try {
+    const text = await fsp.readFile(file, 'utf8');
+    return text.split('\n').filter(Boolean).map((line) => JSON.parse(line));
+  } catch (error) {
+    if (error?.code === 'ENOENT') return [];
+    throw error;
+  }
+}
+
+export async function findAssetBySeq({ home, sessionId, seq }) {
+  const rows = await readAssetIndex({ home, sessionId });
+  return rows.filter((row) => Number(row.seq) === Number(seq));
+}
+
+export function assetMarker(row, source = 'parent') {
+  if (source === 'child') {
+    return `[asset-child session=${row.childSessionId ?? row.sessionId} run=${row.runId ?? '?'}`
+      + ` seq=${row.seq} mime=${row.mime ?? '?'} bytes=${row.bytes ?? '?'} path=${row.path}]`;
+  }
+  return `[asset-parent seq=${row.seq} mime=${row.mime ?? '?'}`
+    + ` bytes=${row.bytes ?? '?'} path=${row.path}]`;
+}