@aiwg/cli 2026.7.20 → 2026.7.23

package/dist/src/sessions/importer.js

@@ -0,0 +1,464 @@
+import { SESSION_CONTRACT_VERSION, SessionEventSchema, SessionSchema, assertSupportedSchemaMajor, sha256, stableEventId, stableSessionId, SessionContractError, } from './contracts.js';
+import { redactSessionText, sanitizeNativeExtensions } from './policy.js';
+import { fingerprintSourcePrefix } from './readers.js';
+import { classifySessionEventOrigin, deriveSessionIntent, } from './origin.js';
+const DEFAULT_LIMITS = {
+    maxRecords: 1_000_000,
+    maxRecordBytes: 8 * 1024 * 1024,
+    maxTotalBytes: 1024 * 1024 * 1024,
+    batchSize: 1_000,
+};
+export class SessionImportFailure extends SessionContractError {
+    failureReceipt;
+    constructor(failureReceipt, cause) {
+        super(cause instanceof SessionContractError ? cause.code : 'IMPORT_INTERRUPTED', cause instanceof Error ? cause.message : 'session import failed');
+        this.failureReceipt = failureReceipt;
+        this.name = 'SessionImportFailure';
+    }
+}
+export class IncrementalSessionImporter {
+    repository;
+    constructor(repository) {
+        this.repository = repository;
+    }
+    async import(request) {
+        assertSupportedSchemaMajor(request.source.sourceSchemaVersion);
+        if (request.inactivityThresholdMs !== undefined
+            && (!Number.isFinite(request.inactivityThresholdMs) || request.inactivityThresholdMs < 0)) {
+            throw new SessionContractError('INVALID_ARGUMENT', 'session inactivity threshold must be a non-negative duration');
+        }
+        if (request.workspaceId !== request.selectedSource.authorizedScope.workspaceId) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'session import workspace is outside the authorized source scope');
+        }
+        const limits = { ...DEFAULT_LIMITS, ...request.limits };
+        const previous = request.batchRunId
+            ? this.repository.getBatchCheckpoint(request.source.sourceId, request.adapter.adapterVersion, request.batchRunId) ?? this.repository.getCheckpoint(request.source.sourceId, request.adapter.adapterVersion)
+            : this.repository.getCheckpoint(request.source.sourceId, request.adapter.adapterVersion);
+        const continuity = await sourceContinuity(request, previous);
+        const sourceObservedAt = continuity
+            ? new Date(continuity.mtimeMs).toISOString()
+            : undefined;
+        const sourceGeneration = continuity?.sourceGeneration ?? sourceGenerationDigest(request);
+        if (previous?.sourceGeneration && previous.sourceGeneration !== sourceGeneration) {
+            throw new SessionContractError('SCHEMA_DRIFT', 'session source generation changed; explicit restart or migration is required');
+        }
+        if (previous?.adapterVersion && previous.adapterVersion !== request.adapter.adapterVersion) {
+            throw new SessionContractError('SCHEMA_DRIFT', 'session checkpoint adapter version changed; checkpoint migration is required');
+        }
+        if (previous?.sourceSchemaVersion
+            && previous.sourceSchemaVersion !== request.source.sourceSchemaVersion) {
+            throw new SessionContractError('SCHEMA_DRIFT', 'session checkpoint source schema changed; checkpoint migration is required');
+        }
+        if (previous?.policyVersion && previous.policyVersion !== request.policyVersion) {
+            throw new SessionContractError('SCHEMA_DRIFT', 'session checkpoint policy version changed; checkpoint migration is required');
+        }
+        const checkpoint = {
+            cursor: previous?.cursor ?? '',
+            recordsRead: previous?.recordsRead ?? 0,
+            bytesRead: previous?.bytesRead ?? 0,
+            checkpointVersion: '2',
+            positionKind: previous?.positionKind ?? 'record-index',
+            sourceGeneration,
+            locatorClass: request.selectedSource.locatorClass,
+            adapterVersion: request.adapter.adapterVersion,
+            sourceSchemaVersion: request.source.sourceSchemaVersion,
+            policyVersion: request.policyVersion,
+            continuity: continuity
+                ? (!previous || previous.positionKind === 'byte-offset'
+                    ? continuity.outcome
+                    : 'unverified')
+                : (previous ? 'unverified' : 'new-generation'),
+            sourceSize: continuity?.size,
+            sourceMtimeMs: continuity?.mtimeMs,
+            sourceFileIdentity: continuity?.fileIdentity,
+            prefixDigest: continuity?.prefixDigest,
+        };
+        const receipts = [];
+        let batch = [];
+        let batchStart = checkpoint.recordsRead;
+        let durableCheckpoint = { ...checkpoint };
+        const importStarted = performance.now();
+        let peakHeap = process.memoryUsage().heapUsed;
+        let peakRss = process.memoryUsage().rss;
+        const flush = () => {
+            if (batch.length === 0)
+                return;
+            if (request.signal?.aborted) {
+                throw new SessionContractError('IMPORT_INTERRUPTED', 'session import was cancelled at a durable batch boundary');
+            }
+            const runId = sha256([
+                request.source.sourceId, request.adapter.adapterVersion,
+                batchStart, checkpoint.recordsRead,
+                ...batch.map((record) => sha256(JSON.stringify(record))),
+            ].join('\0'));
+            const normalized = normalizeBatch(request, batch, runId, sourceObservedAt);
+            const run = {
+                contractVersion: SESSION_CONTRACT_VERSION,
+                importRunId: runId,
+                sourceId: request.source.sourceId,
+                parserVersion: request.adapter.adapterVersion,
+                policyVersion: request.policyVersion,
+                sourceSchemaVersion: request.source.sourceSchemaVersion,
+                consistency: request.source.consistency,
+                status: 'running',
+                checkpoint: { ...checkpoint },
+                startedAt: new Date().toISOString(),
+                completedAt: null,
+                errorCode: null,
+            };
+            const flushStarted = performance.now();
+            const sanitizedSource = {
+                ...request.source,
+                extensions: sanitizeNativeExtensions(request.source.extensions).value,
+            };
+            const receipt = this.repository.applyImport({
+                source: sanitizedSource, run,
+                sessions: normalized.sessions, events: normalized.events,
+                batchRunId: request.batchRunId,
+            }, { ...checkpoint }, request.publish ?? request.source.consistency !== 'complete');
+            const memory = process.memoryUsage();
+            peakHeap = Math.max(peakHeap, memory.heapUsed);
+            peakRss = Math.max(peakRss, memory.rss);
+            receipt.metrics = {
+                records: batch.length,
+                normalizedEvents: normalized.events.length,
+                normalizedBytes: batch.reduce((total, record) => total + Buffer.byteLength(JSON.stringify(record)), 0),
+                durationMs: performance.now() - importStarted,
+                batchLatencyMs: performance.now() - flushStarted,
+                heapUsedBytes: peakHeap,
+                rssBytes: peakRss,
+                checkpointDurable: true,
+            };
+            receipts.push(receipt);
+            durableCheckpoint = { ...checkpoint };
+            batch = [];
+            batchStart = checkpoint.recordsRead;
+        };
+        try {
+            for await (const record of request.adapter.stream(request.selectedSource, previous ? { value: previous.cursor } : undefined)) {
+                if (request.signal?.aborted) {
+                    throw new SessionContractError('IMPORT_INTERRUPTED', 'session import was cancelled and can resume from its durable checkpoint');
+                }
+                const bytes = Buffer.byteLength(JSON.stringify(record));
+                if (bytes > limits.maxRecordBytes
+                    || checkpoint.bytesRead + bytes > limits.maxTotalBytes
+                    || checkpoint.recordsRead + 1 > limits.maxRecords) {
+                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'session import exceeded an authorized resource limit');
+                }
+                batch.push(record);
+                checkpoint.recordsRead += 1;
+                if (record.sourceCursor?.startsWith('byte:')) {
+                    checkpoint.positionKind = 'byte-offset';
+                    checkpoint.cursor = record.sourceCursor;
+                    checkpoint.bytesRead = Number(record.sourceCursor.slice(5));
+                }
+                else {
+                    checkpoint.bytesRead += bytes;
+                    checkpoint.cursor = String(checkpoint.recordsRead);
+                }
+                if (batch.length >= limits.batchSize)
+                    flush();
+            }
+            flush();
+        }
+        catch (error) {
+            const published = request.publish ?? request.source.consistency !== 'complete';
+            const committed = published ? receipts : [];
+            throw new SessionImportFailure({
+                contractVersion: '1.0.0',
+                outcome: 'terminal-failure',
+                sourceId: request.source.sourceId,
+                sourceGeneration,
+                consistency: request.source.consistency,
+                committedPrefix: {
+                    batches: committed.length,
+                    records: committed.reduce((total, receipt) => total + (receipt.metrics?.records ?? 0), 0),
+                    events: committed.reduce((total, receipt) => total + receipt.eventsInserted, 0),
+                },
+                resumableCheckpoint: !published
+                    ? {
+                        ...durableCheckpoint,
+                        cursor: '',
+                        recordsRead: 0,
+                        bytesRead: 0,
+                        continuity: 'new-generation',
+                    }
+                    : durableCheckpoint,
+                errorCode: error instanceof SessionContractError
+                    ? error.code : 'IMPORT_INTERRUPTED',
+            }, error);
+        }
+        if (request.publish !== false && request.source.consistency === 'complete') {
+            this.repository.commitStagedImports(request.source.sourceId, request.adapter.adapterVersion);
+            for (const receipt of receipts) {
+                if (receipt.outcome === 'staged')
+                    receipt.outcome = 'committed';
+            }
+        }
+        return receipts;
+    }
+}
+function normalizeBatch(request, records, importRunId, sourceObservedAt) {
+    const sessions = new Map();
+    const events = records.map((record) => {
+        const sessionId = stableSessionId(request.source.provider, request.source.sourceId, record.nativeSessionId);
+        const redacted = redactSessionText(record.text);
+        const native = sanitizeNativeExtensions(record.extensions ?? {});
+        const digest = sha256(JSON.stringify(record));
+        const origin = classifySessionEventOrigin(request.source.provider, record);
+        const lifecycle = sessionLifecycle(request, record, sourceObservedAt);
+        const lifecycleEvidence = sessionLifecycleEvidence(request, record, sourceObservedAt);
+        const extensions = {
+            [`native.${request.source.provider}`]: native.value,
+        };
+        const event = SessionEventSchema.parse({
+            contractVersion: SESSION_CONTRACT_VERSION,
+            eventId: stableEventId(request.source.provider, request.source.sourceId, record, digest),
+            sessionId, sourceId: request.source.sourceId, importRunId,
+            nativeId: record.nativeEventId ?? null, sequence: record.sequence,
+            kind: record.kind, role: record.role ?? null, occurredAt: record.occurredAt ?? null,
+            activityBoundary: record.activityBoundary ?? null,
+            activityBoundaryBasis: record.activityBoundaryBasis ?? null,
+            activityBoundaryConfidence: record.activityBoundaryConfidence ?? null,
+            origin: origin.origin,
+            originRule: origin.rule,
+            originClassifierVersion: origin.classifierVersion,
+            participant: record.participant ?? null,
+            toolName: record.toolName ?? null,
+            toolCallId: record.toolCallId ?? null,
+            model: record.model ?? null,
+            entities: record.entities ?? [],
+            extractionState: record.extractionState ?? null,
+            searchableText: redacted.text, digest, rawReference: record.rawReference,
+            adapterVersion: request.adapter.adapterVersion,
+            consistency: request.source.consistency,
+            sensitivity: {
+                classification: redacted.sensitivity === 'sensitive' || native.sensitivity === 'sensitive'
+                    ? 'sensitive' : 'none',
+                classes: [...new Set([...redacted.classes, ...native.classes])].sort(),
+            },
+            opaque: !KNOWN_EVENT_KINDS.has(record.kind),
+            extensions,
+        });
+        if (!sessions.has(sessionId)) {
+            sessions.set(sessionId, SessionSchema.parse({
+                contractVersion: SESSION_CONTRACT_VERSION,
+                sessionId, sourceId: request.source.sourceId, provider: request.source.provider,
+                nativeSessionId: record.nativeSessionId, workspaceId: request.workspaceId,
+                startedAt: record.occurredAt ?? null, updatedAt: record.occurredAt ?? null,
+                consistency: request.source.consistency,
+                lifecycle,
+                sourceDigest: sha256(`${sourceGenerationDigest(request)}\0${record.nativeSessionId}`),
+                extensions: {
+                    [`native.${request.source.provider}`]: {
+                        lifecycleEvidence,
+                    },
+                },
+            }));
+        }
+        else {
+            const session = sessions.get(sessionId);
+            session.startedAt = earlierTimestamp(session.startedAt, record.occurredAt ?? null);
+            session.updatedAt = laterTimestamp(session.updatedAt, record.occurredAt ?? null);
+            session.consistency = strongerConsistency(session.consistency, request.source.consistency);
+            const nativeKey = `native.${request.source.provider}`;
+            const nativeEnvelope = session.extensions[nativeKey];
+            const nativeRecord = nativeEnvelope && typeof nativeEnvelope === 'object' && !Array.isArray(nativeEnvelope)
+                ? nativeEnvelope
+                : {};
+            const selected = selectLifecycleTransition(session.lifecycle, nativeRecord.lifecycleEvidence, lifecycle, lifecycleEvidence);
+            session.lifecycle = selected.lifecycle;
+            session.extensions[nativeKey] = {
+                ...nativeRecord,
+                lifecycleEvidence: selected.evidence,
+            };
+        }
+        return event;
+    });
+    for (const session of sessions.values()) {
+        session.intent = deriveSessionIntent(events.filter((event) => event.sessionId === session.sessionId));
+    }
+    return { sessions: [...sessions.values()], events };
+}
+const KNOWN_EVENT_KINDS = new Set(['message', 'tool-call', 'tool-result', 'artifact', 'attachment', 'summary']);
+function earlierTimestamp(left, right) {
+    if (!left)
+        return right;
+    if (!right)
+        return left;
+    return Date.parse(left) <= Date.parse(right) ? left : right;
+}
+function laterTimestamp(left, right) {
+    if (!left)
+        return right;
+    if (!right)
+        return left;
+    return Date.parse(left) >= Date.parse(right) ? left : right;
+}
+function strongerConsistency(left, right) {
+    const rank = {
+        provisional: 0,
+        'consistent-snapshot': 1,
+        complete: 2,
+    };
+    return rank[left] >= rank[right] ? left : right;
+}
+function sessionLifecycle(request, record, sourceObservedAt) {
+    const explicit = nativeLifecycle(record.extensions);
+    if (explicit)
+        return explicit;
+    if (request.source.consistency === 'complete')
+        return 'complete';
+    const observedAt = record.occurredAt ?? sourceObservedAt;
+    if (observedAt && isStaleHistoricalTimestamp(observedAt, inactivityThresholdMs(request)))
+        return 'inactive';
+    return 'active';
+}
+function sessionLifecycleEvidence(request, record, sourceObservedAt) {
+    const observedAt = record.occurredAt ?? sourceObservedAt;
+    const explicit = nativeLifecycle(record.extensions);
+    if (explicit) {
+        return {
+            basis: 'provider-explicit-event',
+            state: explicit,
+            observedAt: observedAt ?? request.source.authorizedAt,
+            confidence: 'high',
+        };
+    }
+    if (request.source.consistency === 'complete') {
+        return {
+            basis: 'complete-source',
+            state: 'complete',
+            observedAt: observedAt ?? request.source.authorizedAt,
+            confidence: 'high',
+        };
+    }
+    const thresholdMs = inactivityThresholdMs(request);
+    if (observedAt && isStaleHistoricalTimestamp(observedAt, thresholdMs)) {
+        return {
+            basis: 'inactivity-threshold',
+            state: 'inactive',
+            observedAt,
+            confidence: 'medium',
+            thresholdMs,
+        };
+    }
+    return {
+        basis: 'open-provisional-source',
+        state: 'active',
+        observedAt: observedAt ?? request.source.authorizedAt,
+        confidence: 'provisional',
+    };
+}
+function nativeLifecycle(extensions) {
+    const raw = typeof extensions?.lifecycle === 'string' ? extensions.lifecycle : undefined;
+    if (!raw)
+        return null;
+    const normalized = {
+        active: 'active',
+        inactive: 'inactive',
+        paused: 'paused',
+        complete: 'complete',
+        completed: 'complete',
+        archived: 'archived',
+        deleted: 'tombstoned',
+        cancelled: 'interrupted',
+        canceled: 'interrupted',
+        failed: 'interrupted',
+        interrupted: 'interrupted',
+        unknown: 'unknown',
+        'unknown-at-import': 'unknown',
+        'completed-at-import': 'complete',
+    };
+    return normalized[raw] ?? null;
+}
+function selectLifecycleTransition(leftLifecycle, left, rightLifecycle, right) {
+    const leftEvidence = asLifecycleEvidence(left);
+    if (leftLifecycle === 'tombstoned') {
+        return { lifecycle: leftLifecycle, evidence: leftEvidence ?? right };
+    }
+    if (!leftEvidence)
+        return { lifecycle: rightLifecycle, evidence: right };
+    const rank = {
+        'open-provisional-source': 1,
+        'inactivity-threshold': 1,
+        'complete-source': 2,
+        'provider-explicit-event': 3,
+    };
+    const leftRank = rank[String(leftEvidence.basis)] ?? 0;
+    const rightRank = rank[String(right.basis)] ?? 0;
+    const rightIsNewer = evidenceTimestamp(right) > evidenceTimestamp(leftEvidence);
+    return rightRank > leftRank || (rightRank === leftRank && rightIsNewer)
+        ? { lifecycle: rightLifecycle, evidence: right }
+        : { lifecycle: leftLifecycle, evidence: leftEvidence };
+}
+function asLifecycleEvidence(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : null;
+}
+function evidenceTimestamp(value) {
+    const parsed = Date.parse(String(value.observedAt ?? ''));
+    return Number.isFinite(parsed) ? parsed : Number.NEGATIVE_INFINITY;
+}
+const DEFAULT_INACTIVITY_THRESHOLD_MS = 24 * 60 * 60 * 1000;
+function inactivityThresholdMs(request) {
+    return request.inactivityThresholdMs ?? DEFAULT_INACTIVITY_THRESHOLD_MS;
+}
+function isStaleHistoricalTimestamp(value, thresholdMs) {
+    const timestamp = Date.parse(value);
+    return Number.isFinite(timestamp)
+        && Date.now() - timestamp > thresholdMs;
+}
+function sourceGenerationDigest(request) {
+    return sha256([
+        request.source.sourceId,
+        request.source.provider,
+        request.selectedSource.locatorClass,
+        request.source.sourceSchemaVersion,
+        request.adapter.adapterVersion,
+    ].join('\0'));
+}
+async function sourceContinuity(request, previous) {
+    if (request.selectedSource.authorizedScope.allowedRoots.length === 0
+        || /^[a-z][a-z0-9+.-]*:\/\//i.test(request.selectedSource.locator)
+        || request.selectedSource.locator.startsWith('<')) {
+        return null;
+    }
+    const authorization = {
+        selectedPath: request.selectedSource.locator,
+        allowedRoots: request.selectedSource.authorizedScope.allowedRoots,
+    };
+    const metadata = await fingerprintSourcePrefix(authorization, 0);
+    if (previous?.sourceSize !== undefined) {
+        if (metadata.size < previous.sourceSize) {
+            throw new SessionContractError('SCHEMA_DRIFT', 'session source was truncated before its durable checkpoint');
+        }
+        if (previous.sourceFileIdentity
+            && previous.sourceFileIdentity !== metadata.fileIdentity) {
+            throw new SessionContractError('SCHEMA_DRIFT', 'session source file generation was replaced or rotated');
+        }
+        const priorPrefix = await fingerprintSourcePrefix(authorization, previous.sourceSize);
+        if (previous.prefixDigest && priorPrefix.digest !== previous.prefixDigest) {
+            throw new SessionContractError('SCHEMA_DRIFT', 'session source prefix was rewritten before its durable checkpoint');
+        }
+    }
+    const current = await fingerprintSourcePrefix(authorization, metadata.size);
+    const generation = previous?.sourceGeneration ?? sha256([
+        sourceGenerationDigest(request),
+        metadata.fileIdentity,
+    ].join('\0'));
+    return {
+        sourceGeneration: generation,
+        outcome: !previous
+            ? 'new-generation'
+            : metadata.size === previous.sourceSize
+                && current.digest === previous.prefixDigest
+                ? 'unchanged-replay' : 'validated-append',
+        size: metadata.size,
+        mtimeMs: metadata.mtimeMs,
+        fileIdentity: metadata.fileIdentity,
+        prefixDigest: current.digest,
+    };
+}
+//# sourceMappingURL=importer.js.map

package/dist/src/sessions/index.js

@@ -0,0 +1,31 @@
+export * from './contracts.js';
+export * from './fixtures.js';
+export * from './policy.js';
+export * from './discovery.js';
+export * from './readers.js';
+export * from './repository.js';
+export * from './ports.js';
+export * from './optional-backends.js';
+export * from './knowledge-shard.js';
+export * from './candidates.js';
+export * from './promotion.js';
+export * from './importer.js';
+export * from './import-lease.js';
+export * from './batch-contracts.js';
+export * from './batch-import.js';
+export * from './workspace-discovery.js';
+export * from './timeline.js';
+export * from './origin.js';
+export * from './adapters/generic.js';
+export * from './adapters/claude.js';
+export * from './adapters/codex.js';
+export * from './adapters/copilot.js';
+export * from './adapters/cursor.js';
+export * from './adapters/factory.js';
+export * from './adapters/hermes.js';
+export * from './adapters/opencode.js';
+export * from './adapters/openclaw.js';
+export * from './adapters/openhuman.js';
+export * from './adapters/warp.js';
+export * from './adapters/windsurf.js';
+//# sourceMappingURL=index.js.map

package/dist/src/sessions/knowledge-shard.js

@@ -0,0 +1,61 @@
+export function convertSessionEventsToKnowledgeShard(source, events) {
+    const losses = [];
+    const records = events.map((event) => {
+        if (Object.values(event.extensions).some(hasPortableValue)) {
+            losses.push({
+                code: 'NATIVE_EXTENSION_NOT_PORTABLE',
+                eventId: event.eventId,
+                field: 'extensions',
+                reason: 'Knowledge Shard v1 has no canonical provider-native extension field',
+            });
+        }
+        if (event.rawReference.offset !== undefined) {
+            losses.push({
+                code: 'RAW_OFFSET_NOT_PORTABLE',
+                eventId: event.eventId,
+                field: 'rawReference.offset',
+                reason: 'Knowledge Shard v1 preserves locator class but not byte offsets',
+            });
+        }
+        if (event.rawReference.sequence !== undefined) {
+            losses.push({
+                code: 'RAW_SEQUENCE_NOT_PORTABLE',
+                eventId: event.eventId,
+                field: 'rawReference.sequence',
+                reason: 'Knowledge Shard v1 preserves event identity but not provider sequence locators',
+            });
+        }
+        return {
+            id: event.eventId,
+            content: event.searchableText,
+            metadata: {
+                provider: source.provider,
+                sessionId: event.sessionId,
+                eventId: event.eventId,
+                importRunId: event.importRunId,
+                sourceId: event.sourceId,
+                locatorClass: source.locatorClass,
+                role: event.role,
+                occurredAt: event.occurredAt,
+                sensitivity: event.sensitivity.classification,
+            },
+        };
+    });
+    return {
+        contractVersion: '1.0.0',
+        target: 'knowledge-shard-v1',
+        records,
+        losses,
+        lossless: losses.length === 0,
+    };
+}
+function hasPortableValue(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (Array.isArray(value))
+        return value.length > 0;
+    if (typeof value === 'object')
+        return Object.keys(value).length > 0;
+    return true;
+}
+//# sourceMappingURL=knowledge-shard.js.map