@aiwg/cli 2026.10.10 → 2026.10.12

package/dist/src/sessions/adapters/hermes.js

@@ -1,7 +1,10 @@
+import { lstat } from 'node:fs/promises';
+import { join } from 'node:path';
 import { z } from 'zod';
 import { number } from '../../schema/zod-validation.mjs';
 import { schemaRejectionDetail, schemaIssueDetail, SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
 import { streamBoundedJsonLines, } from '../readers.js';
+import { HERMES_SNAPSHOT_LOCATOR_CLASS, HERMES_STATE_DB_FILENAME, hermesSnapshotStagingDir, snapshotHermesStateDb, } from './hermes-state-db.js';
 export const HERMES_ADAPTER_VERSION = '1.0.0';
 export const HERMES_EXPORT_SCHEMA_VERSION = '1.0.0';
 export const HERMES_NATIVE_SCHEMA_VERSION = '23.0.0';
@@ -64,14 +67,42 @@ export class HermesSessionAdapter {
     provider = 'hermes';
     adapterVersion = HERMES_ADAPTER_VERSION;
     disposition = 'implemented';
-    supportedOperations = ['inspect', 'stream'];
+    supportedOperations = ['discover', 'inspect', 'stream'];
     acquisitionModes = ['jsonl', 'api', 'sqlite-snapshot'];
     constructor(limits, localApi) {
         this.limits = limits;
         this.localApi = localApi;
     }
-    async *discover(_scope) {
-        // Native exports and consistent snapshots require explicit selection.
+    /**
+     * Discover through a consistent `sqlite3.backup()` snapshot of the
+     * explicitly authorized `<root>/state.db`. The live database is never
+     * opened for writing and never streamed directly; matching sessions are
+     * projected to an owned staging snapshot the existing consistent-snapshot
+     * path already validates.
+     */
+    async *discover(scope) {
+        if (scope.allowedRoots.length === 0) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Hermes discovery requires an explicitly authorized Hermes home; pass --hermes-root.');
+        }
+        const staging = hermesSnapshotStagingDir(scope.workspaceId);
+        for (const root of [...scope.allowedRoots].sort()) {
+            if (!(await isStateDbFile(join(root, HERMES_STATE_DB_FILENAME))))
+                continue;
+            const snapshot = await snapshotHermesStateDb({
+                hermesRoot: root,
+                stagingDir: staging,
+                allowedRoots: scope.allowedRoots,
+                workspaceId: scope.workspaceId,
+                limits: this.limits,
+            });
+            if (!snapshot)
+                continue;
+            yield {
+                provider: 'hermes',
+                locator: snapshot.projectionPath,
+                locatorClass: HERMES_SNAPSHOT_LOCATOR_CLASS,
+            };
+        }
     }
     async inspect(source) {
         if (source.locatorClass === 'hermes-export-jsonl'
@@ -284,6 +315,14 @@ function normalizeMessage(sessionId, message, index, line, locatorClass, common)
     }));
     return records;
 }
+async function isStateDbFile(path) {
+    try {
+        return (await lstat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
 function ended(value) {
     return Boolean(value.ended_at || value.provider_deleted_at || value.archived || value.inactive);
 }

package/dist/src/sessions/adapters/warp.js

@@ -50,7 +50,7 @@ export class WarpSessionAdapter {
         if (blocks.length === 0) {
             throw new SessionContractError('MALFORMED_SOURCE', 'Warp Markdown export contains no recognized user or assistant conversation blocks', schemaIssueDetail('headings'));
         }
-        const stableSessionId = `manual:${createHash('sha256').update(value).digest('hex').slice(0, 32)}`;
+        const stableSessionId = source.nativeSessionId ?? `manual:${createHash('sha256').update(value).digest('hex').slice(0, 32)}`;
         const lifecycleEvidence = /<!--\s*warp-lifecycle:\s*complete\s*-->/i.test(value)
             ? 'completed-at-import' : 'unknown-at-import';
         const title = /^#\s+(.+)$/m.exec(value)?.[1]?.trim();

package/dist/src/sessions/batch-import.js

@@ -6,6 +6,7 @@ import { coveragePreflight, sessionRuntimeIdentity } from './coverage-preflight.
 import { SESSION_CONTRACT_VERSION, SessionContractError, schemaIssueDetail, SessionSourceSchema, sha256, stableSessionId, stableEventId, } from './contracts.js';
 import { BATCH_IMPORT_VERSION, coverageFromBatchRun, } from './batch-contracts.js';
 import { IncrementalSessionImporter, SessionImportFailure } from './importer.js';
+import { HOST_CATALOG_WORKSPACE_ID, isAccountScopedAdapter, publishHostRoutedBatch, } from './host-catalog.js';
 import { matchImportExclusion, resolveImportExclusions } from './import-exclusions.js';
 import { resolveImportLimits } from './import-limits.js';
 import { fingerprintSourceFile } from './readers.js';
@@ -45,6 +46,7 @@ export async function importDiscoveryManifest(options) {
     run.completedAt = null;
     options.repository.saveBatchImportRun(run);
     injectFault(options, run, 'run-saved');
+    const hostRoutedSourceIds = [];
     for (const manifestSource of options.manifest.sources) {
         const disposition = run.sources.find((candidate) => candidate.sourceId === manifestSource.sourceId);
         if (!disposition) {
@@ -76,23 +78,33 @@ export async function importDiscoveryManifest(options) {
         persistProgress(options.repository, run, now());
         try {
             await assertManifestSourceUnchanged(manifestSource);
+            const adapter = adapterFor(manifestSource.provider, limits);
+            // Account-scoped providers (Grok Bot) are imported once into the
+            // host catalog; the workspace catalog records a reference (#3232).
+            // Any adapter declaring account scope follows this route.
+            const hostRouted = options.hostRepository !== undefined
+                && options.hostCatalogPath !== undefined
+                && isAccountScopedAdapter(adapter);
+            const targetRepository = hostRouted ? options.hostRepository : options.repository;
+            const importWorkspaceId = hostRouted ? HOST_CATALOG_WORKSPACE_ID : options.manifest.workspaceId;
+            if (hostRouted)
+                hostRoutedSourceIds.push(manifestSource.sourceId);
             const selectedSource = {
                 provider: manifestSource.provider,
                 locator: manifestSource.locator,
                 locatorClass: manifestSource.locatorClass,
                 sourceId: manifestSource.sourceId,
                 authorizedScope: {
-                    workspaceId: options.manifest.workspaceId,
+                    workspaceId: importWorkspaceId,
                     allowedRoots: [manifestSource.authorizedRoot],
                 },
             };
-            const adapter = adapterFor(manifestSource.provider, limits);
             const source = await sessionSource(selectedSource, adapter);
-            const receipts = await new IncrementalSessionImporter(options.repository).import({
+            const receipts = await new IncrementalSessionImporter(targetRepository).import({
                 source,
                 selectedSource,
                 adapter,
-                workspaceId: options.manifest.workspaceId,
+                workspaceId: importWorkspaceId,
                 policyVersion: '1.0.0',
                 batchRunId: run.runId,
                 publish: false,
@@ -101,7 +113,7 @@ export async function importDiscoveryManifest(options) {
                 limits,
             });
             await assertManifestSourceUnchanged(manifestSource);
-            const totals = options.repository.sourceImportTotals(manifestSource.sourceId, run.runId);
+            const totals = targetRepository.sourceImportTotals(manifestSource.sourceId, run.runId);
             disposition.sessionsAccepted = totals.sessions;
             disposition.eventsAccepted = totals.events;
             disposition.status = receipts.length > 0
@@ -134,6 +146,18 @@ export async function importDiscoveryManifest(options) {
         .map((source) => source.sourceId);
     injectFault(options, run, 'before-publication');
     options.repository.commitStagedBatch(run.runId, publishable);
+    if (options.hostRepository && options.hostCatalogPath && hostRoutedSourceIds.length > 0) {
+        const acceptedHost = run.sources
+            .filter((source) => hostRoutedSourceIds.includes(source.sourceId) && isAccepted(source.status))
+            .map((source) => source.sourceId);
+        publishHostRoutedBatch({
+            hostRepository: options.hostRepository,
+            workspaceRepository: options.repository,
+            batchRunId: run.runId,
+            sourceIds: acceptedHost,
+            hostCatalogPath: options.hostCatalogPath,
+        });
+    }
     injectFault(options, run, 'after-publication');
     run.status = pending ? 'interrupted' : rejected || acquisitionIncomplete ? 'partial' : 'complete';
     run.updatedAt = now().toISOString();
@@ -303,6 +327,16 @@ function providerProfile(provider, locatorClass) {
         return 'muse-native-session-log-v1';
     if (provider === 'grokbot')
         return 'grokbot-native-transcript-replica-v1';
+    if (provider === 'grok-build') {
+        return locatorClass === 'grok-build-native-chat-history'
+            ? 'grok-build-native-chat-history-v1'
+            : 'documented-cli-markdown-export';
+    }
+    if (provider === 'hermes') {
+        return locatorClass === 'hermes-consistent-snapshot-jsonl'
+            ? 'native-state-db-backup-snapshot-v1'
+            : 'native-schema-23-export';
+    }
     return 'manual-interchange';
 }
 function importErrorCode(error) {
@@ -360,8 +394,12 @@ async function rebuildFromCatalog(options) {
     let staged;
     try {
         staged = new SessionRepository(join(stagingDirectory, 'staging.sqlite'));
+        // The staged rebuild transfers normalized rows (not host references) into
+        // the destination, so account-scoped sources rebuild locally here as
+        // before; the destination's own host routing applies on its next import.
         const receipt = await importDiscoveryManifest({ ...options, manifest, repository: staged,
-            carryForward: undefined, fault: undefined });
+            carryForward: undefined, fault: undefined,
+            hostRepository: undefined, hostCatalogPath: undefined });
         const identities = new Set();
         const destinationCodex = new Map(catalogSessions(options.repository, workspaceId)
             .filter(session => session.provider === 'codex').map(session => [session.nativeSessionId, session.sourceId]));

package/dist/src/sessions/contracts.js

@@ -76,7 +76,7 @@ export const SessionErrorCodeSchema = z.enum([
     'OPERATION_NOT_AUTHORIZED',
     'IMPORT_CONFLICT', 'IMPORT_INTERRUPTED', 'MALFORMED_SOURCE',
     'DUPLICATE_NATIVE_ID', 'AMBIGUOUS_TIMESTAMP', 'TRUNCATED_SOURCE',
-    'UNSUPPORTED_OPERATION',
+    'UNSUPPORTED_OPERATION', 'UNSUPPORTED_PROVIDER',
     'INVALID_SEARCH_QUERY', 'INVALID_ARGUMENT',
 ]);
 const VersionSchema = z.string().regex(/^\d+\.\d+\.\d+(?:[-+].+)?$/);
@@ -103,6 +103,19 @@ export const SessionSourceSchema = z.object({
     authorizedAt: dateTime({ offset: true }),
     extensions: NativeExtensionsSchema.prefault({}),
 });
+/**
+ * Content-addressed reference to a tool-output image whose bytes live in
+ * the catalog blob store instead of inline in the event (#3265). The
+ * persisted shape's schema is this zod contract (session events have no
+ * JSON-schema file; see `lint:schemas`).
+ */
+export const SessionImageRefSchema = z.object({
+    digest: DigestSchema,
+    mediaType: z.string().min(1),
+    byteLength: integer().nonnegative(),
+    locatorClass: z.string().min(1).optional(),
+    offset: integer().nonnegative().optional(),
+});
 export const SessionEventSchema = z.object({
     contractVersion: z.literal(SESSION_CONTRACT_VERSION),
     eventId: z.string().min(1),
@@ -130,6 +143,12 @@ export const SessionEventSchema = z.object({
     originRule: z.string().min(1).default('legacy:unknown'),
     originClassifierVersion: VersionSchema.default('1.0.0'),
     searchableText: z.string(),
+    /**
+     * Image references extracted from inline payloads at import. Optional so
+     * pre-#3265 catalog rows (inline bytes, field absent) still parse; readers
+     * must tolerate `undefined` as "no references".
+     */
+    imageRefs: z.array(SessionImageRefSchema).optional(),
     digest: DigestSchema,
     rawReference: z.object({
         locatorClass: z.string().min(1),

package/dist/src/sessions/coverage-preflight.js

@@ -139,7 +139,13 @@ export function reconcileCoveragePreflight(preflight, sources) {
             return entry;
         const selected = sources.filter((source) => source.provider === entry.provider);
         const imported = selected.length === entry.sourceCount && selected.length > 0
-            && selected.every((source) => source.status === 'excluded' || (accepted.has(source.status) && source.eventsAccepted > 0));
+            // duplicate/previously-committed sources were acquired by an earlier
+            // run, so zero new events still counts as imported. A host-routed
+            // second workspace import lands here: the host copy already exists
+            // and the workspace only records references (#3232). A freshly
+            // committed source with zero events stays incomplete.
+            && selected.every((source) => source.status === 'excluded' || (accepted.has(source.status)
+                && (source.eventsAccepted > 0 || source.status !== 'committed')));
         return {
             ...entry,
             disposition: !imported ? 'import-incomplete'

package/dist/src/sessions/discovery-capability.js

@@ -0,0 +1,38 @@
+const REQUIRED_FLAGS = {
+    claude: [],
+    codex: ['--codex-root'],
+    cursor: [],
+    factory: [],
+    pi: [],
+    omp: ['--omp-root'],
+    'deepseek-harness': ['--dsh-root'],
+    muse: ['--muse-root'],
+    grokbot: ['--grokbot-root'],
+    'grok-build': ['--grok-root'],
+    hermes: ['--hermes-root'],
+};
+const LIVE_DETECTION = {
+    'grok-build': 'supported',
+};
+/**
+ * `discoverable` requires a wired `discover` operation on the loaded adapter,
+ * not merely an implemented ingest path; otherwise the provider stays
+ * `manual-export` (or `unsupported` when it has no ingest path at all).
+ */
+export function providerDiscoveryCapability(provider, supportedOperations) {
+    if (supportedOperations.includes('discover')) {
+        return {
+            disposition: 'discoverable',
+            authorization: 'explicit-root',
+            requiredFlags: REQUIRED_FLAGS[provider] ?? [],
+            liveDetection: LIVE_DETECTION[provider] ?? 'unsupported',
+        };
+    }
+    return {
+        disposition: 'manual-export',
+        authorization: 'none',
+        requiredFlags: [],
+        liveDetection: 'unsupported',
+    };
+}
+//# sourceMappingURL=discovery-capability.js.map

package/dist/src/sessions/fortemi-export-mapping.js

@@ -75,7 +75,16 @@ export function sessionToAiwgFortemiRecord(session, catalogTags = []) {
         updated_at: updatedAt,
     };
 }
-export function sessionEventToAiwgFortemiRecord(session, event) {
+/**
+ * Map one catalog event. `images` carries the event's image references
+ * resolved against the blob store when the caller can provide them
+ * (export build passes `repository.resolveEventImages`); omitted means
+ * "not resolved", never "no images" -- the placeholder text in `text` is
+ * always present regardless (#3265). Bytes are never embedded here, only
+ * the reference plus its availability, so a consumer knows whether the
+ * digest is fetchable from the catalog or gone.
+ */
+export function sessionEventToAiwgFortemiRecord(session, event, images = []) {
     const locator = sessionEventRecordLocator(session, event);
     const parentLocator = sessionRecordLocator(session);
     const updatedAt = event.occurredAt ?? new Date(0).toISOString();
@@ -110,6 +119,16 @@ export function sessionEventToAiwgFortemiRecord(session, event) {
                 nativeId: event.nativeId,
                 sequence: event.sequence,
                 toolCallId: event.toolCallId,
+                ...(images.length > 0
+                    ? {
+                        images: images.map((image) => ({
+                            digest: image.digest,
+                            mediaType: image.mediaType,
+                            byteLength: image.byteLength,
+                            status: image.status,
+                        })),
+                    }
+                    : {}),
             },
         }];
     const tags = [
@@ -117,6 +136,10 @@ export function sessionEventToAiwgFortemiRecord(session, event) {
         ...(event.role ? [tag('role', event.role)] : []),
         ...(event.toolName ? [tag('tool', event.toolName)] : []),
         ...(event.entities ?? []).map((entity) => tag('entity', entity)),
+        ...images.map((image) => tag('image', image.digest)),
+        ...images
+            .filter((image) => image.status === 'unavailable')
+            .map((image) => tag('image-unavailable', image.digest)),
     ];
     return {
         schema_version: SESSION_EXPORT_RECORD_SCHEMA_VERSION,
@@ -275,13 +298,20 @@ function exportManifestRecord(repoRef, generatedAt) {
  * session catalog's workspace id, not a git repo -- the field is repurposed
  * honestly rather than left to imply something untrue).
  */
-export function buildSessionAiwgFortemiIndexExport(repoRef, sessions, eventsBySessionId, outputs = [], catalogTagsBySessionId = new Map()) {
+export function buildSessionAiwgFortemiIndexExport(repoRef, sessions, eventsBySessionId, outputs = [], catalogTagsBySessionId = new Map(), 
+/**
+ * Resolve image references per event when the caller's catalog is at
+ * hand (`(event) => repository.resolveEventImages(event)`). Absent means
+ * references stay unresolved in the records, never that images are
+ * missing -- availability is only asserted when actually resolved (#3265).
+ */
+imageResolution) {
     const generatedAt = new Date().toISOString();
     const items = [exportManifestRecord(repoRef, generatedAt)];
     for (const session of sessions) {
         items.push(sessionToAiwgFortemiRecord(session, catalogTagsBySessionId.get(session.sessionId) ?? []));
         for (const event of eventsBySessionId.get(session.sessionId) ?? []) {
-            items.push(sessionEventToAiwgFortemiRecord(session, event));
+            items.push(sessionEventToAiwgFortemiRecord(session, event, imageResolution?.(event) ?? []));
         }
         for (const output of outputs.filter((entry) => entry.sessionId === session.sessionId)) {
             items.push(sessionOutputToAiwgFortemiRecord(session, output));

package/dist/src/sessions/host-catalog.js

@@ -0,0 +1,157 @@
+// Host catalog for account-scoped session providers (#3232).
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { createSessionAdapterRegistry } from './adapter-registry.js';
+/** Workspace id used for account-scoped sessions stored in the host catalog. */
+export const HOST_CATALOG_WORKSPACE_ID = 'host';
+/** DDL for the workspace-catalog reference table (created by SessionRepository). */
+export const HOST_REFERENCE_TABLE_DDL = `
+  CREATE TABLE IF NOT EXISTS session_host_refs (
+    provider TEXT NOT NULL, native_session_id TEXT NOT NULL,
+    session_id TEXT NOT NULL, source_id TEXT NOT NULL,
+    host_catalog TEXT NOT NULL,
+    PRIMARY KEY(provider, native_session_id)
+  );
+  CREATE INDEX IF NOT EXISTS idx_session_host_refs_session
+  ON session_host_refs(session_id);
+`;
+const HOST_CATALOG_ENV = 'AIWG_SESSIONS_HOST_CATALOG';
+/** User-scope (host) catalog path; the env override exists so tests never touch HOME. */
+export function defaultHostCatalogPath(homeDir = homedir()) {
+    const override = process.env[HOST_CATALOG_ENV]?.trim();
+    if (override)
+        return override;
+    return join(homeDir, '.aiwg', 'sessions', 'host-catalog.sqlite');
+}
+/** Account-scoped adapters (Grok Bot today) route to the host catalog. */
+export function isAccountScopedAdapter(adapter) {
+    return adapter.scopeClass === 'account';
+}
+/**
+ * Whether a discovery manifest holds any account-scoped source. Callers use
+ * this to avoid creating or opening the host catalog when every source is
+ * workspace-scoped. Unknown providers resolve to workspace scope.
+ */
+export function manifestNeedsHostCatalog(sources) {
+    if (sources.length === 0)
+        return false;
+    const registry = createSessionAdapterRegistry();
+    return sources.some((source) => {
+        try {
+            return isAccountScopedAdapter(registry.get(source.provider));
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Aggregate identity: one account-scoped conversation counts once per provider. */
+export function hostReferenceKey(identity) {
+    return `${identity.provider}\0${identity.nativeSessionId}`;
+}
+/** Drop cross-catalog duplicates, keeping the first row for each provider+session. */
+export function dedupeSessionIdentities(rows) {
+    const seen = new Set();
+    return rows.filter((row) => {
+        const key = hostReferenceKey(row);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/** Count sessions across catalogs without doubling account-scoped replicas. */
+export function countUniqueSessionsAcross(lists) {
+    return dedupeSessionIdentities(lists.flat()).length;
+}
+/** Host sessions backing a workspace catalog's references (matched by provider+session). */
+export function resolveHostReferences(references, hostSessions) {
+    const byKey = new Map(hostSessions.map((session) => [
+        hostReferenceKey({ provider: session.provider, nativeSessionId: session.nativeSessionId }),
+        session,
+    ]));
+    const resolved = [];
+    for (const reference of references) {
+        const session = byKey.get(hostReferenceKey(reference));
+        if (session)
+            resolved.push(session);
+    }
+    return resolved;
+}
+/**
+ * Workspace listing view: local rows plus referenced host sessions, with
+ * legacy duplicated copies (same provider+session already stored locally)
+ * counted once. Local rows win ties so workspace provenance is preserved.
+ */
+export function mergeSessionLists(local, referenced) {
+    return dedupeSessionIdentities([...local, ...referenced]);
+}
+/** Sessions in a repository reduced to aggregate identities (legacy rows included). */
+export function collectSessionIdentities(repository, workspaceId) {
+    return repository.listSessionIdentities(workspaceId);
+}
+/**
+ * Count sessions across workspace and host catalogs without doubling
+ * account-scoped replicas: two workspaces referencing the same host
+ * session plus a legacy workspace holding a copied row count once.
+ */
+export function countUniqueSessionsAcrossCatalogs(views) {
+    return dedupeSessionIdentities(views.flatMap((view) => [...view.identities, ...view.references])).length;
+}
+/** Index visible identities by internal session id for merge lookups. */
+export function indexIdentitiesBySessionId(identities) {
+    return new Map(identities.map((identity) => [identity.sessionId, identity]));
+}
+/**
+ * Merge local rows (search hits, analytics facts) with host-catalog rows,
+ * counting each session once by provider + native session id. Every local
+ * row is kept; a host row is dropped when the same session already has
+ * local rows (a legacy copied row wins over its host reference, mirroring
+ * mergeSessionLists, #3232) and host rows repeating across catalogs are
+ * deduped by hostRowKey. An unreachable host catalog contributes no rows,
+ * so local results are never lost.
+ */
+export function mergeCrossCatalogRows(localRows, hostRows, localIdentityBySessionId, hostIdentityBySessionId, hostRowKey) {
+    const localKeys = new Set();
+    for (const row of localRows) {
+        const identity = localIdentityBySessionId.get(row.sessionId);
+        if (identity) {
+            localKeys.add(hostReferenceKey({ provider: row.provider, nativeSessionId: identity.nativeSessionId }));
+        }
+    }
+    const seenHost = new Set();
+    const keptHost = hostRows.filter((row) => {
+        const identity = hostIdentityBySessionId.get(row.sessionId);
+        if (identity
+            && localKeys.has(hostReferenceKey({ provider: row.provider, nativeSessionId: identity.nativeSessionId }))) {
+            return false;
+        }
+        const key = hostRowKey(row);
+        if (seenHost.has(key))
+            return false;
+        seenHost.add(key);
+        return true;
+    });
+    return [...localRows, ...keptHost];
+}
+/**
+ * Publish staged account-scoped imports in the host catalog and record
+ * workspace references instead of copies (#3232). Non-destructive: legacy
+ * workspace rows are left untouched and stay readable.
+ */
+export function publishHostRoutedBatch(input) {
+    const accepted = new Set(input.sourceIds);
+    input.hostRepository.commitStagedBatch(input.batchRunId, [...accepted]);
+    for (const identity of input.hostRepository.listSessionIdentities(HOST_CATALOG_WORKSPACE_ID)) {
+        if (!accepted.has(identity.sourceId))
+            continue;
+        input.workspaceRepository.recordHostSessionReference({
+            provider: identity.provider,
+            nativeSessionId: identity.nativeSessionId,
+            sessionId: identity.sessionId,
+            sourceId: identity.sourceId,
+            hostCatalog: input.hostCatalogPath,
+        });
+    }
+}
+//# sourceMappingURL=host-catalog.js.map

package/dist/src/sessions/image-blobs.js

@@ -0,0 +1,141 @@
+// Content-addressed tool-output image references for the session catalog (#3265).
+import { createHash } from 'node:crypto';
+const IMAGE_DIGEST_PREFIX = 'sha256:';
+export function sha256Bytes(value) {
+    return `${IMAGE_DIGEST_PREFIX}${createHash('sha256').update(value).digest('hex')}`;
+}
+export function isImageDigest(value) {
+    return typeof value === 'string' && /^sha256:[a-f0-9]{64}$/.test(value);
+}
+/** Human-readable byte size for image placeholders (`3.1 MB`, `68 B`). */
+export function formatImageBytes(byteLength) {
+    if (!Number.isFinite(byteLength) || byteLength < 0)
+        return '0 B';
+    if (byteLength < 1024)
+        return `${Math.trunc(byteLength)} B`;
+    const kb = byteLength / 1024;
+    if (kb < 1024)
+        return `${kb.toFixed(1)} KB`;
+    return `${(kb / 1024).toFixed(1)} MB`;
+}
+/** Placeholder kept in `searchableText` (and FTS) instead of the image bytes. */
+export function imagePlaceholder(ref) {
+    return `[image: ${ref.digest}, ${ref.mediaType}, ${formatImageBytes(ref.byteLength)}]`;
+}
+// The payload class excludes whitespace so a match stops at the first word
+// boundary instead of swallowing following prose; shape (and a minimum
+// length well below any real image) is validated again on decode.
+const DATA_URL_PATTERN = /data:(image\/[a-zA-Z0-9+.-]+)(;[a-zA-Z0-9!#$&^_.+-]+)*;base64,([A-Za-z0-9+/=]+)/g;
+const MIN_BASE64_PAYLOAD_CHARS = 32;
+function decodeBase64Payload(payload) {
+    const compact = payload.replace(/\s+/g, '');
+    // `Buffer.from(x, 'base64')` never throws -- it skips invalid characters --
+    // so validate the shape first: base64 alphabet only, padding at the end,
+    // and a length that can carry at least one byte.
+    if (compact.length < 4 || compact.length % 4 === 1)
+        return null;
+    if (!/^(?:[A-Za-z0-9+/]+={0,2})$/.test(compact))
+        return null;
+    const bytes = Buffer.from(compact, 'base64');
+    if (bytes.length === 0)
+        return null;
+    return new Uint8Array(bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength));
+}
+/**
+ * Replace inline base64 image data URLs in free text with content-hash
+ * placeholders. Only `image/*` media types are extracted; other data URLs
+ * (and remote `http(s)` image URLs, which are references already) pass
+ * through untouched.
+ */
+export function extractInlineImagesFromText(text, source = {}) {
+    const images = [];
+    if (!text.includes('data:image/'))
+        return { text, images };
+    DATA_URL_PATTERN.lastIndex = 0;
+    const result = text.replace(DATA_URL_PATTERN, (match, mediaType, _params, payload) => {
+        if (payload.length < MIN_BASE64_PAYLOAD_CHARS)
+            return match;
+        const bytes = decodeBase64Payload(payload);
+        if (!bytes)
+            return match;
+        const ref = {
+            digest: sha256Bytes(bytes),
+            mediaType: String(mediaType).toLowerCase(),
+            byteLength: bytes.length,
+            ...(source.locatorClass !== undefined ? { locatorClass: source.locatorClass } : {}),
+            ...(source.offset !== undefined ? { offset: source.offset } : {}),
+            bytes,
+        };
+        images.push(ref);
+        return imagePlaceholder(ref);
+    });
+    return { text: result, images };
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Extract inline images from a whole import batch. Returns replacement
+ * events (bytes swapped for references) plus the distinct blobs to persist.
+ * Idempotent: placeholder text from an earlier pass matches no pattern, so
+ * importer-extracted batches and direct writers converge on the same store
+ * state. Blobs travel beside the events because event JSON must only hold
+ * the content-hash reference, never the bytes.
+ */
+export function extractBatchEventImages(batch) {
+    const blobs = new Map();
+    for (const carried of batch.imageBlobs ?? []) {
+        if (isImageDigest(carried.digest) && !blobs.has(carried.digest))
+            blobs.set(carried.digest, carried);
+    }
+    const events = batch.events.map((event) => {
+        const extracted = extractEventImages({
+            searchableText: event.searchableText,
+            extensions: event.extensions,
+            rawReference: event.rawReference,
+        });
+        for (const image of extracted.images) {
+            if (!blobs.has(image.digest))
+                blobs.set(image.digest, image);
+        }
+        if (extracted.images.length === 0)
+            return event;
+        const refs = [...(event.imageRefs ?? [])];
+        for (const ref of extracted.imageRefs) {
+            if (!refs.some((prior) => prior.digest === ref.digest))
+                refs.push(ref);
+        }
+        return {
+            ...event,
+            searchableText: extracted.searchableText,
+            extensions: extracted.extensions,
+            imageRefs: refs,
+        };
+    });
+    return { events, imageBlobs: [...blobs.values()] };
+}
+/** Extract inline images from one event's text; extensions keep their existing redaction. */
+export function extractEventImages(input) {
+    const source = {
+        ...(input.rawReference?.locatorClass !== undefined ? { locatorClass: input.rawReference.locatorClass } : {}),
+        ...(input.rawReference?.offset !== undefined ? { offset: input.rawReference.offset } : {}),
+    };
+    // Only event text is lifted. Provider image blocks in `extensions` are
+    // left to native-extension sanitization, which redacts them to markers,
+    // so this change never retains image bytes the catalog used to drop.
+    const text = extractInlineImagesFromText(input.searchableText ?? '', source);
+    const images = text.images;
+    return {
+        searchableText: text.text,
+        extensions: isPlainObject(input.extensions) ? input.extensions : {},
+        imageRefs: images.map((image) => ({
+            digest: image.digest,
+            mediaType: image.mediaType,
+            byteLength: image.byteLength,
+            ...(image.locatorClass !== undefined ? { locatorClass: image.locatorClass } : {}),
+            ...(image.offset !== undefined ? { offset: image.offset } : {}),
+        })),
+        images,
+    };
+}
+//# sourceMappingURL=image-blobs.js.map