@aiwg/cli 2026.7.20 → 2026.7.23

package/dist/src/sessions/contracts.js

@@ -0,0 +1,337 @@
+import { createHash } from 'node:crypto';
+import { z } from 'zod';
+export const SESSION_CONTRACT_VERSION = '1.0.0';
+export const SESSION_PROVIDER_IDS = [
+    'claude', 'codex', 'copilot', 'cursor', 'factory', 'hermes',
+    'opencode', 'openclaw', 'openhuman', 'warp', 'devin-desktop', 'generic',
+];
+export const SessionProviderIdSchema = z.enum(SESSION_PROVIDER_IDS);
+export const SESSION_PROVIDER_ALIASES = Object.freeze({
+    windsurf: 'devin-desktop',
+});
+const CompatibleSessionProviderIdSchema = z.preprocess((value) => typeof value === 'string'
+    ? (SESSION_PROVIDER_ALIASES[value] ?? value)
+    : value, SessionProviderIdSchema);
+export const CapabilityDispositionSchema = z.enum([
+    'implemented', 'manual-only', 'degraded', 'unsupported',
+]);
+export const OperationalStateSchema = z.enum([
+    'available', 'unavailable', 'inaccessible', 'version-unknown',
+    'schema-unsupported', 'degraded',
+]);
+export const ConsistencyStateSchema = z.enum([
+    'provisional', 'consistent-snapshot', 'complete',
+]);
+export const SessionErrorCodeSchema = z.enum([
+    'UNKNOWN_PROVIDER', 'UNKNOWN_SCHEMA_MAJOR', 'SOURCE_NOT_AUTHORIZED',
+    'SOURCE_OUTSIDE_ALLOWED_ROOT', 'SOURCE_SYMLINK', 'SOURCE_NOT_REGULAR_FILE',
+    'RESOURCE_LIMIT_EXCEEDED', 'NETWORK_NOT_AUTHORIZED', 'SCHEMA_DRIFT',
+    'OPERATION_NOT_AUTHORIZED',
+    'IMPORT_CONFLICT', 'IMPORT_INTERRUPTED', 'MALFORMED_SOURCE',
+    'DUPLICATE_NATIVE_ID', 'AMBIGUOUS_TIMESTAMP', 'TRUNCATED_SOURCE',
+    'UNSUPPORTED_OPERATION',
+    'INVALID_SEARCH_QUERY', 'INVALID_ARGUMENT',
+]);
+const VersionSchema = z.string().regex(/^\d+\.\d+\.\d+(?:[-+].+)?$/);
+const DigestSchema = z.string().regex(/^sha256:[a-f0-9]{64}$/);
+const NativeExtensionsSchema = z.record(z.unknown()).superRefine((value, context) => {
+    for (const key of Object.keys(value)) {
+        if (!key.startsWith('native.')) {
+            context.addIssue({ code: z.ZodIssueCode.custom, message: `native extension must use native.<provider>: ${key}` });
+        }
+    }
+});
+export const SessionSourceSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    sourceId: z.string().min(1),
+    provider: CompatibleSessionProviderIdSchema,
+    providerProfile: z.string().min(1),
+    locatorClass: z.string().min(1),
+    redactedLocator: z.string().min(1),
+    adapterVersion: VersionSchema,
+    sourceSchemaVersion: VersionSchema,
+    disposition: CapabilityDispositionSchema,
+    operationalState: OperationalStateSchema,
+    consistency: ConsistencyStateSchema,
+    authorizedAt: z.string().datetime({ offset: true }),
+    extensions: NativeExtensionsSchema.default({}),
+});
+export const SessionEventSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    eventId: z.string().min(1),
+    sessionId: z.string().min(1),
+    sourceId: z.string().min(1),
+    importRunId: z.string().min(1),
+    nativeId: z.string().min(1).nullable(),
+    sequence: z.number().int().nonnegative(),
+    kind: z.string().min(1),
+    role: z.string().min(1).nullable(),
+    participant: z.string().min(1).nullable().default(null),
+    toolName: z.string().min(1).nullable().default(null),
+    toolCallId: z.string().min(1).nullable().default(null),
+    model: z.string().min(1).nullable().default(null),
+    entities: z.array(z.string().min(1)).default([]),
+    extractionState: z.string().min(1).nullable().default(null),
+    occurredAt: z.string().datetime({ offset: true }).nullable(),
+    activityBoundary: z.enum(['pause', 'resume', 'continuation', 'end']).nullable().default(null),
+    activityBoundaryBasis: z.string().min(1).nullable().default(null),
+    activityBoundaryConfidence: z.enum(['low', 'medium', 'high']).nullable().default(null),
+    origin: z.enum([
+        'user-authored', 'assistant-generated', 'provider-bootstrap',
+        'workspace-instruction', 'tool-control', 'unknown',
+    ]).default('unknown'),
+    originRule: z.string().min(1).default('legacy:unknown'),
+    originClassifierVersion: VersionSchema.default('1.0.0'),
+    searchableText: z.string(),
+    digest: DigestSchema,
+    rawReference: z.object({
+        locatorClass: z.string().min(1),
+        offset: z.number().int().nonnegative().optional(),
+        sequence: z.number().int().nonnegative().optional(),
+    }),
+    adapterVersion: VersionSchema,
+    consistency: ConsistencyStateSchema,
+    sensitivity: z.object({
+        classification: z.enum(['none', 'sensitive']),
+        classes: z.array(z.string().min(1)),
+    }),
+    opaque: z.boolean().default(false),
+    extensions: NativeExtensionsSchema.default({}),
+});
+export const SessionSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    sessionId: z.string().min(1),
+    sourceId: z.string().min(1),
+    provider: CompatibleSessionProviderIdSchema,
+    nativeSessionId: z.string().min(1),
+    workspaceId: z.string().min(1),
+    startedAt: z.string().datetime({ offset: true }).nullable(),
+    updatedAt: z.string().datetime({ offset: true }).nullable(),
+    consistency: ConsistencyStateSchema,
+    lifecycle: z.enum([
+        'active', 'inactive', 'paused', 'complete', 'interrupted', 'archived',
+        'unknown', 'tombstoned',
+    ]),
+    intent: z.object({
+        status: z.enum(['selected', 'absent', 'unknown']),
+        eventId: z.string().min(1).nullable(),
+        sequence: z.number().int().nonnegative().nullable(),
+        title: z.string().nullable(),
+        summary: z.string().nullable(),
+    }).default({
+        status: 'unknown',
+        eventId: null,
+        sequence: null,
+        title: null,
+        summary: null,
+    }),
+    sourceDigest: DigestSchema,
+    extensions: NativeExtensionsSchema.default({}),
+});
+export const ImportCheckpointSchema = z.object({
+    cursor: z.string(),
+    recordsRead: z.number().int().nonnegative(),
+    bytesRead: z.number().int().nonnegative(),
+    checkpointVersion: z.literal('2').optional(),
+    positionKind: z.enum(['record-index', 'byte-offset', 'provider-native']).optional(),
+    sourceGeneration: z.string().min(1).optional(),
+    locatorClass: z.string().min(1).optional(),
+    adapterVersion: VersionSchema.optional(),
+    sourceSchemaVersion: VersionSchema.optional(),
+    policyVersion: VersionSchema.optional(),
+    continuity: z.enum([
+        'new-generation',
+        'validated-append',
+        'unchanged-replay',
+        'unverified',
+    ]).optional(),
+    sourceSize: z.number().int().nonnegative().optional(),
+    sourceMtimeMs: z.number().nonnegative().optional(),
+    sourceFileIdentity: z.string().min(1).optional(),
+    prefixDigest: DigestSchema.optional(),
+});
+export const ImportRunSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    importRunId: z.string().min(1),
+    sourceId: z.string().min(1),
+    parserVersion: VersionSchema,
+    policyVersion: VersionSchema,
+    sourceSchemaVersion: VersionSchema,
+    consistency: ConsistencyStateSchema,
+    status: z.enum(['running', 'committed', 'rolled-back', 'failed']),
+    checkpoint: ImportCheckpointSchema,
+    startedAt: z.string().datetime({ offset: true }),
+    completedAt: z.string().datetime({ offset: true }).nullable(),
+    errorCode: SessionErrorCodeSchema.nullable(),
+});
+export const ProvenanceEdgeSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    edgeId: z.string().min(1),
+    relation: z.enum([
+        'acquired-from', 'normalized-from', 'derived-from', 'promoted-to',
+        'supersedes', 'invalidates',
+    ]),
+    fromId: z.string().min(1),
+    toId: z.string().min(1),
+    importRunId: z.string().min(1),
+    createdAt: z.string().datetime({ offset: true }),
+});
+export const IntelligenceCandidateTypeSchema = z.enum([
+    'decision', 'requirement', 'constraint', 'preference', 'task', 'discovery',
+    'fix', 'failed-approach', 'procedure', 'risk', 'contradiction', 'question',
+    'entity', 'relationship',
+]);
+export const CandidateSecurityWarningSchema = z.enum([
+    'instruction-like', 'structure-breaking', 'control-character', 'bidi-control',
+    'unicode-confusable', 'active-content', 'secret-bearing',
+]);
+export const CandidateSecuritySchema = z.object({
+    disposition: z.enum(['clear', 'suspicious']),
+    warnings: z.array(CandidateSecurityWarningSchema),
+    requiresAcknowledgement: z.boolean(),
+    acknowledged: z.boolean(),
+    policyVersion: VersionSchema,
+}).strict();
+export const IntelligenceCandidateSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    candidateId: z.string().min(1),
+    version: z.number().int().positive(),
+    type: IntelligenceCandidateTypeSchema,
+    assertion: z.string().min(1),
+    subject: z.string().min(1).nullable(),
+    predicate: z.string().min(1).nullable(),
+    object: z.string().min(1).nullable(),
+    evidence: z.array(z.object({
+        eventId: z.string().min(1),
+        start: z.number().int().nonnegative(),
+        end: z.number().int().positive(),
+        quoteDigest: DigestSchema,
+        quote: z.string().min(1).optional(),
+    }).strict()).min(1),
+    confidence: z.number().min(0).max(1),
+    temporalScope: z.string().min(1),
+    projectScope: z.string().min(1),
+    extractionMethod: z.string().min(1),
+    extractionVersion: VersionSchema,
+    extractionPolicyVersion: VersionSchema,
+    model: z.string().min(1).nullable(),
+    sensitivity: z.enum(['none', 'sensitive']),
+    security: CandidateSecuritySchema.default({
+        disposition: 'clear',
+        warnings: [],
+        requiresAcknowledgement: false,
+        acknowledged: false,
+        policyVersion: '1.0.0',
+    }),
+    reviewState: z.enum([
+        'pending', 'accepted', 'rejected', 'deferred', 'promoted', 'superseded',
+    ]),
+    conflictsWith: z.array(z.string().min(1)).default([]),
+    supersedes: z.array(z.string().min(1)).default([]),
+    createdAt: z.string().datetime({ offset: true }),
+}).strict().superRefine((candidate, context) => {
+    if (candidate.type === 'relationship'
+        && (!candidate.subject || !candidate.predicate || !candidate.object)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'relationship candidates require subject, predicate, and object',
+        });
+    }
+});
+export const CandidateReviewReceiptSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    receiptId: z.string().min(1),
+    candidateId: z.string().min(1),
+    candidateVersion: z.number().int().positive(),
+    fromState: z.enum([
+        'pending', 'accepted', 'rejected', 'deferred', 'promoted', 'superseded',
+    ]),
+    toState: z.enum([
+        'pending', 'accepted', 'rejected', 'deferred', 'promoted', 'superseded',
+    ]),
+    reviewer: z.string().min(1),
+    reason: z.string().min(1),
+    securityWarnings: z.array(CandidateSecurityWarningSchema).default([]),
+    securityAcknowledged: z.boolean().default(false),
+    occurredAt: z.string().datetime({ offset: true }),
+}).strict();
+export const PromotionReceiptSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    receiptId: z.string().min(1),
+    operationId: z.string().min(1),
+    candidateId: z.string().min(1),
+    candidateVersion: z.number().int().positive(),
+    consumer: z.string().min(1),
+    destinationRef: z.string().min(1),
+    reviewer: z.string().min(1),
+    approvedAt: z.string().datetime({ offset: true }),
+    evidenceEventIds: z.array(z.string().min(1)).min(1),
+    conflictsWith: z.array(z.string().min(1)),
+    supersedes: z.array(z.string().min(1)),
+    beforeHash: DigestSchema.nullable(),
+    afterHash: DigestSchema,
+    dryRun: z.boolean(),
+    duplicate: z.boolean(),
+}).strict();
+export const DeletionReceiptSchema = z.object({
+    contractVersion: z.literal(SESSION_CONTRACT_VERSION),
+    receiptId: z.string().min(1),
+    operationId: z.string().min(1),
+    scopeClass: z.string().min(1),
+    counts: z.record(z.number().int().nonnegative()),
+    survivingDependentIds: z.array(z.string().min(1)),
+    actorClass: z.string().min(1),
+    reasonCode: z.string().min(1),
+    orphanCounts: z.record(z.number().int().nonnegative()),
+    outcome: z.enum(['preview', 'committed', 'failed']),
+    occurredAt: z.string().datetime({ offset: true }),
+}).strict();
+export const PromotionDependencyDecisionSchema = z.object({
+    dependentId: z.string().min(1),
+    action: z.enum([
+        'revoke', 'supersede', 'retain', 'origin_unavailable', 'delete', 'abort',
+    ]),
+    basis: z.string().min(1),
+}).strict();
+export function assertSessionProviderId(value) {
+    const canonical = SESSION_PROVIDER_ALIASES[value] ?? value;
+    const parsed = SessionProviderIdSchema.safeParse(canonical);
+    if (!parsed.success)
+        throw new SessionContractError('UNKNOWN_PROVIDER', `unknown session provider: ${value}`);
+    return parsed.data;
+}
+export function assertSupportedSchemaMajor(version, supportedMajor = 1) {
+    const match = /^(\d+)\./.exec(version);
+    if (!match || Number(match[1]) !== supportedMajor) {
+        throw new SessionContractError('UNKNOWN_SCHEMA_MAJOR', `unsupported session schema major: ${version}`);
+    }
+}
+export function stableSessionId(provider, sourceId, nativeSessionId) {
+    const canonical = assertSessionProviderId(provider);
+    // Preserve the legacy identity seed through the published compatibility
+    // window so existing Windsurf catalogs do not duplicate normalized rows.
+    const identitySeed = canonical === 'devin-desktop' ? 'windsurf' : canonical;
+    return stableId('session', identitySeed, sourceId, nativeSessionId);
+}
+export function stableEventId(provider, sourceId, record, digest) {
+    const canonical = assertSessionProviderId(provider);
+    const identityScheme = 'event-v2-native-scope';
+    return record.nativeEventId
+        ? stableId('event', identityScheme, canonical, sourceId, record.nativeSessionId, record.nativeEventId, record.sequence)
+        : stableId('event', identityScheme, canonical, sourceId, record.nativeSessionId, record.sequence, record.kind, digest);
+}
+export function sha256(value) {
+    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+function stableId(prefix, ...parts) {
+    return `${prefix}_${createHash('sha256').update(parts.join('\0')).digest('hex')}`;
+}
+export class SessionContractError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'SessionContractError';
+    }
+}
+//# sourceMappingURL=contracts.js.map

package/dist/src/sessions/discovery.js

@@ -0,0 +1,51 @@
+import { SessionContractError, assertSessionProviderId, } from './contracts.js';
+export class SessionSourceAdapterRegistry {
+    adapters = new Map();
+    register(adapter) {
+        const provider = assertSessionProviderId(adapter.provider);
+        if (this.adapters.has(provider))
+            throw new Error(`session adapter already registered: ${provider}`);
+        this.adapters.set(provider, adapter);
+    }
+    get(providerInput) {
+        const provider = assertSessionProviderId(providerInput);
+        const adapter = this.adapters.get(provider);
+        if (!adapter) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', `no session adapter is registered for ${provider}`);
+        }
+        return adapter;
+    }
+    assertOperation(providerInput, operation) {
+        const adapter = this.get(providerInput);
+        if (!adapter.supportedOperations.includes(operation)) {
+            throw new SessionContractError('UNSUPPORTED_OPERATION', `${operation} is unsupported for provider ${adapter.provider}`);
+        }
+        return adapter;
+    }
+    async *discover(providerInput, scope) {
+        const adapter = this.assertOperation(providerInput, 'discover');
+        if (scope.allowedRoots.length === 0 && (scope.authorizedAccounts?.length ?? 0) === 0) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'discovery requires at least one explicitly authorized root or account');
+        }
+        yield* adapter.discover({
+            ...scope,
+            allowedRoots: [...scope.allowedRoots],
+            authorizedAccounts: scope.authorizedAccounts ? [...scope.authorizedAccounts] : undefined,
+        });
+    }
+    report(providerInput, input) {
+        const adapter = this.get(providerInput);
+        return Object.freeze({
+            provider: adapter.provider,
+            classification: adapter.disposition,
+            supportedOperations: Object.freeze([...adapter.supportedOperations]),
+            acquisitionModes: Object.freeze([...adapter.acquisitionModes]),
+            ...input,
+        });
+    }
+}
+export function redactSourceLocator(locator) {
+    const leaf = locator.replaceAll('\\', '/').split('/').filter(Boolean).at(-1) ?? '<source>';
+    return `<session-source>/${leaf.replace(/[^A-Za-z0-9._-]/g, '_')}`;
+}
+//# sourceMappingURL=discovery.js.map

package/dist/src/sessions/fixtures.js

@@ -0,0 +1,12 @@
+export function defineSessionAdapterFixture(fixture) {
+    if (fixture.synthetic !== true)
+        throw new Error('session fixtures must be synthetic or separately redacted');
+    if (fixture.disposition === 'implemented' && fixture.records.length === 0) {
+        throw new Error('implemented adapters require at least one synthetic fixture record');
+    }
+    if (fixture.disposition !== 'implemented' && !fixture.unsupportedReason) {
+        throw new Error(`${fixture.disposition} fixtures require an explicit reason`);
+    }
+    return Object.freeze({ ...fixture, records: Object.freeze([...fixture.records]) });
+}
+//# sourceMappingURL=fixtures.js.map

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

@@ -0,0 +1,152 @@
+import { mkdir, readFile, rename, rm, stat, writeFile, } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { dirname } from 'node:path';
+const DEFAULTS = {
+    waitMs: 5_000,
+    pollMs: 50,
+    heartbeatMs: 1_000,
+    staleMs: 30_000,
+};
+export class ImportLeaseContentionError extends Error {
+    owner;
+    waitMs;
+    code = 'IMPORT_LOCKED';
+    constructor(owner, waitMs) {
+        const identity = owner
+            ? `run ${owner.runId} (pid ${owner.pid} on ${owner.host}, heartbeat ${owner.heartbeatAt})`
+            : 'an unreadable owner';
+        super(`session import lease is held by ${identity}; waited ${waitMs}ms. `
+            + 'Wait for that run to finish, or remove the lease only after confirming the owner is no longer active.');
+        this.owner = owner;
+        this.waitMs = waitMs;
+        this.name = 'ImportLeaseContentionError';
+    }
+}
+export function importLeasePath(databasePath) {
+    return `${databasePath}.import.lock`;
+}
+export async function acquireImportLease(databasePath, runId, options = {}) {
+    const waitMs = options.waitMs ?? DEFAULTS.waitMs;
+    const pollMs = options.pollMs ?? DEFAULTS.pollMs;
+    const heartbeatMs = options.heartbeatMs ?? DEFAULTS.heartbeatMs;
+    const staleMs = options.staleMs ?? DEFAULTS.staleMs;
+    const now = options.now ?? (() => new Date());
+    const processAlive = options.processAlive ?? defaultProcessAlive;
+    const lockPath = importLeasePath(databasePath);
+    const ownerPath = `${lockPath}/owner.json`;
+    const deadline = Date.now() + waitMs;
+    await mkdir(dirname(databasePath), { recursive: true, mode: 0o700 });
+    while (true) {
+        try {
+            await mkdir(lockPath, { mode: 0o700 });
+            const observed = now().toISOString();
+            const owner = {
+                contractVersion: '1.0.0',
+                runId,
+                pid: process.pid,
+                host: hostname(),
+                startedAt: observed,
+                heartbeatAt: observed,
+            };
+            await writeOwner(ownerPath, owner);
+            const timer = setInterval(() => {
+                owner.heartbeatAt = now().toISOString();
+                void writeOwner(ownerPath, owner).catch(() => undefined);
+            }, heartbeatMs);
+            timer.unref();
+            let released = false;
+            return {
+                owner,
+                lockPath,
+                async release() {
+                    if (released)
+                        return;
+                    released = true;
+                    clearInterval(timer);
+                    const current = await readOwner(ownerPath);
+                    if (current?.runId === owner.runId) {
+                        await rm(lockPath, { recursive: true, force: true });
+                    }
+                },
+            };
+        }
+        catch (error) {
+            if (!isNodeError(error) || error.code !== 'EEXIST')
+                throw error;
+            const existing = await readOwner(ownerPath);
+            if (await staleLease(lockPath, existing, staleMs, processAlive)) {
+                const confirmed = await readOwner(ownerPath);
+                if (sameLease(existing, confirmed)
+                    && await staleLease(lockPath, confirmed, staleMs, processAlive)) {
+                    await rm(lockPath, { recursive: true, force: true });
+                    continue;
+                }
+            }
+            if (Date.now() >= deadline) {
+                throw new ImportLeaseContentionError(existing, waitMs);
+            }
+            await delay(Math.min(pollMs, Math.max(1, deadline - Date.now())));
+        }
+    }
+}
+async function writeOwner(path, owner) {
+    const temporary = `${path}.tmp-${process.pid}`;
+    await writeFile(temporary, `${JSON.stringify(owner)}\n`, { mode: 0o600 });
+    await rename(temporary, path);
+}
+async function readOwner(path) {
+    try {
+        const value = JSON.parse(await readFile(path, 'utf8'));
+        if (value.contractVersion !== '1.0.0'
+            || typeof value.runId !== 'string'
+            || typeof value.pid !== 'number'
+            || typeof value.host !== 'string'
+            || typeof value.startedAt !== 'string'
+            || typeof value.heartbeatAt !== 'string')
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+async function staleLease(lockPath, owner, staleMs, processAlive) {
+    if (!owner || owner.host !== hostname())
+        return false;
+    if (processAlive(owner.pid))
+        return false;
+    const heartbeat = owner ? Date.parse(owner.heartbeatAt) : Number.NaN;
+    if (Number.isFinite(heartbeat))
+        return Date.now() - heartbeat > staleMs;
+    try {
+        return Date.now() - (await stat(lockPath)).mtimeMs > staleMs;
+    }
+    catch {
+        return false;
+    }
+}
+function sameLease(first, second) {
+    if (!first || !second)
+        return first === second;
+    return first.runId === second.runId
+        && first.pid === second.pid
+        && first.host === second.host
+        && first.startedAt === second.startedAt
+        && first.heartbeatAt === second.heartbeatAt;
+}
+function defaultProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return isNodeError(error) && error.code === 'EPERM';
+    }
+}
+function isNodeError(error) {
+    return error instanceof Error && 'code' in error;
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=import-lease.js.map