@aiwg/cli 2026.7.21 → 2026.7.23

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

@@ -1,4 +1,5 @@
-import { basename, extname } from 'node:path';
+import { opendir } from 'node:fs/promises';
+import { basename, dirname, extname, resolve, } from 'node:path';
 import { z } from 'zod';
 import { SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
 import { readBoundedJsonLines, readBoundedText, streamBoundedJsonLines, } from '../readers.js';
@@ -44,19 +45,52 @@ const CloudEventSchema = z.object({
 }).passthrough().refine((value) => value.agent?.id || value.run?.id, {
     message: 'cloud event requires an agent or run identity',
 });
+const AgentTranscriptEventSchema = z.object({
+    schemaVersion: z.string().optional(),
+    id: z.string().optional(),
+    event_id: z.string().optional(),
+    request_id: z.string().optional(),
+    timestamp: z.string().datetime({ offset: true }).optional(),
+    type: z.string().min(1).optional(),
+    status: z.string().min(1).optional(),
+    role: z.string().min(1).optional(),
+    message: z.object({
+        id: z.string().optional(),
+        role: z.string().optional(),
+        content: z.union([z.string(), z.array(z.unknown())]).optional(),
+    }).passthrough().optional(),
+}).passthrough().refine((value) => value.role || value.type, {
+    message: 'agent transcript event requires role or type',
+});
 export class CursorSessionAdapter {
     limits;
+    discoveryLimits;
     provider = 'cursor';
     adapterVersion = CURSOR_ADAPTER_VERSION;
     disposition = 'implemented';
-    supportedOperations = ['inspect', 'stream'];
+    supportedOperations = ['discover', 'inspect', 'stream'];
     acquisitionModes = ['api', 'jsonl', 'manual-export'];
-    constructor(limits) {
+    constructor(limits, discoveryLimits = { maxDepth: 8, maxFiles: 10_000 }) {
         this.limits = limits;
+        this.discoveryLimits = discoveryLimits;
     }
-    async *discover(_scope) {
-        // Every supported Cursor surface requires an explicitly selected export.
-        // The undocumented editor SQLite store is intentionally excluded.
+    async *discover(scope) {
+        if (scope.allowedRoots.length === 0) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Cursor discovery requires an explicitly authorized agent-transcripts root');
+        }
+        let emitted = 0;
+        for (const root of [...scope.allowedRoots].sort()) {
+            for await (const locator of discoverJsonl(resolve(root), this.discoveryLimits.maxDepth)) {
+                if (++emitted > this.discoveryLimits.maxFiles) {
+                    throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Cursor source discovery exceeded the authorized file limit');
+                }
+                yield {
+                    provider: 'cursor',
+                    locator,
+                    locatorClass: 'cursor-agent-transcript-jsonl',
+                };
+            }
+        }
     }
     async inspect(source) {
         const parsed = await this.readSource(source);
@@ -179,9 +213,43 @@ export class CursorSessionAdapter {
                 records: normalized.records,
             };
         }
+        if (source.locatorClass === 'cursor-agent-transcript-jsonl') {
+            const normalized = normalizeAgentTranscript(input.records, source.locator);
+            return {
+                schemaVersion,
+                consistency: normalized.complete && !input.incompleteTail ? 'complete' : 'provisional',
+                records: normalized.records,
+            };
+        }
         throw new SessionContractError('UNSUPPORTED_OPERATION', 'unsupported Cursor source class');
     }
 }
+async function* discoverJsonl(root, remainingDepth) {
+    if (remainingDepth < 0)
+        return;
+    let directory;
+    try {
+        directory = await opendir(root);
+    }
+    catch {
+        return;
+    }
+    const entries = [];
+    for await (const entry of directory)
+        entries.push(entry);
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+        const path = resolve(root, entry.name);
+        if (entry.isSymbolicLink())
+            continue;
+        if (entry.isDirectory()) {
+            yield* discoverJsonl(path, remainingDepth - 1);
+        }
+        else if (entry.isFile() && extname(entry.name) === '.jsonl') {
+            yield path;
+        }
+    }
+}
 function normalizeCli(input) {
     const records = [];
     let sessionId;
@@ -196,7 +264,10 @@ function normalizeCli(input) {
             throw new SessionContractError('DUPLICATE_NATIVE_ID', 'Cursor CLI stream changes session identity');
         }
         sessionId = event.session_id;
-        complete ||= event.type === 'result' && event.subtype === 'success' && event.is_error !== true;
+        const terminal = event.type === 'result'
+            && event.subtype === 'success'
+            && event.is_error !== true;
+        complete ||= terminal;
         const text = event.type === 'result'
             ? (event.result ?? '')
             : (event.message?.content ?? []).flatMap((part) => part.text ?? []).join('');
@@ -220,7 +291,7 @@ function normalizeCli(input) {
                 permissionMode: event.permissionMode,
                 productVersion: event.cliVersion ?? event.version ?? 'not-reported',
                 toolCall: event.tool_call,
-                lifecycle: complete ? 'complete' : 'active',
+                ...(terminal ? { lifecycle: 'complete' } : {}),
                 provenance: { acquisition: 'cursor-cli-stream-json', schema: declaredEventVersion(event) },
                 unknownFields: unknownFields(event, CLI_KEYS),
             },
@@ -250,6 +321,7 @@ function normalizeCloud(input) {
         agentId = nextAgentId;
         runId = nextRunId;
         const status = event.run?.status ?? event.agent?.status;
+        const lifecycle = cloudLifecycle(event.type, status);
         complete ||= isTerminal(status) || event.type === 'agent.deleted' || event.type === 'agent.archived';
         const sessionId = runId ? `${agentId ?? 'agent'}:${runId}` : agentId;
         records.push({
@@ -258,13 +330,28 @@ function normalizeCloud(input) {
             sequence: line.sequence,
             kind: `cursor.cloud.${event.type}`,
             role: 'system',
+            activityBoundary: event.type === 'agent.unarchived'
+                ? 'resume'
+                : event.type === 'agent.archived' || event.type === 'agent.deleted'
+                    ? 'end'
+                    : undefined,
+            activityBoundaryBasis: event.type === 'agent.unarchived'
+                || event.type === 'agent.archived'
+                || event.type === 'agent.deleted'
+                ? `cursor-cloud:${event.type}`
+                : undefined,
+            activityBoundaryConfidence: event.type === 'agent.unarchived'
+                || event.type === 'agent.archived'
+                || event.type === 'agent.deleted'
+                ? 'high'
+                : undefined,
             text: extractCloudText(event.data),
             rawReference: { locatorClass: 'cursor-cloud-events-jsonl', offset: line.byteOffset },
             extensions: {
                 agent: event.agent,
                 run: event.run,
                 status,
-                lifecycle: cloudLifecycle(event.type, status),
+                ...(lifecycle ? { lifecycle } : {}),
                 reconnect: {
                     eventId: event.event_id ?? event.id,
                     supported: true,
@@ -277,6 +364,49 @@ function normalizeCloud(input) {
     }
     return { records, complete };
 }
+function normalizeAgentTranscript(input, locator) {
+    const nativeSessionId = agentTranscriptSessionId(locator);
+    const records = [];
+    let complete = false;
+    for (const line of input) {
+        const parsed = AgentTranscriptEventSchema.safeParse(line.value);
+        if (!parsed.success) {
+            throw new SessionContractError('MALFORMED_SOURCE', 'Cursor agent transcript event is malformed');
+        }
+        const event = parsed.data;
+        const terminal = event.type === 'turn_ended' && event.status === 'success';
+        complete ||= terminal;
+        const messageRole = event.message?.role ?? event.role ?? 'system';
+        records.push({
+            nativeSessionId,
+            nativeEventId: event.event_id ?? event.id ?? event.request_id ?? `${messageRole}:${line.sequence}`,
+            sequence: line.sequence,
+            kind: event.type ? `cursor.agent.${event.type}` : 'message',
+            role: messageRole,
+            participant: messageRole,
+            occurredAt: event.timestamp,
+            activityBoundary: event.type === 'turn_ended' ? 'end' : undefined,
+            activityBoundaryBasis: event.type === 'turn_ended'
+                ? `cursor-agent:${event.status ?? 'unknown'}`
+                : undefined,
+            activityBoundaryConfidence: event.type === 'turn_ended' ? 'high' : undefined,
+            text: messageText(event.message?.content),
+            rawReference: { locatorClass: 'cursor-agent-transcript-jsonl', offset: line.byteOffset },
+            extensions: {
+                transcriptRole: event.role,
+                status: event.status,
+                ...(terminal ? { lifecycle: 'complete' } : {}),
+                provenance: {
+                    acquisition: 'cursor-agent-transcript-jsonl',
+                    schema: declaredEventVersion(event),
+                    nativeSessionIdDerivedFromPath: true,
+                },
+                unknownFields: unknownFields(event, AGENT_TRANSCRIPT_KEYS),
+            },
+        });
+    }
+    return { records, complete };
+}
 function normalizeMarkdown(value, locator) {
     const heading = /^#{1,3}\s+(User|Assistant|Cursor)\s*$/gim;
     const matches = [...value.matchAll(heading)];
@@ -312,6 +442,26 @@ function normalizeMarkdown(value, locator) {
         };
     });
 }
+function agentTranscriptSessionId(locator) {
+    const fileIdentity = basename(locator, extname(locator));
+    const directoryIdentity = basename(dirname(locator));
+    return directoryIdentity && directoryIdentity === fileIdentity
+        ? directoryIdentity : fileIdentity;
+}
+function messageText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (!Array.isArray(value))
+        return '';
+    return value.map((item) => {
+        const block = asObject(item);
+        if (typeof block.text === 'string')
+            return block.text;
+        if (typeof block.content === 'string')
+            return block.content;
+        return '';
+    }).filter(Boolean).join('\n');
+}
 function declaredVersion(records) {
     const versions = new Set(records.map((line) => {
         const value = asObject(line.value);
@@ -342,7 +492,9 @@ function cloudLifecycle(type, status) {
         return 'active';
     if (status === 'cancelled' || status === 'canceled')
         return 'cancelled';
-    return isTerminal(status) ? 'complete' : 'active';
+    if (status === 'active')
+        return 'active';
+    return isTerminal(status) ? 'complete' : undefined;
 }
 function isTerminal(status) {
     return ['completed', 'failed', 'cancelled', 'canceled'].includes(status ?? '');
@@ -369,4 +521,8 @@ const CLI_KEYS = new Set([
     'duration_ms', 'duration_api_ms',
 ]);
 const CLOUD_KEYS = new Set(['schemaVersion', 'id', 'event_id', 'type', 'agent', 'run', 'data']);
+const AGENT_TRANSCRIPT_KEYS = new Set([
+    'schemaVersion', 'id', 'event_id', 'request_id', 'timestamp', 'type', 'status',
+    'role', 'message',
+]);
 //# sourceMappingURL=cursor.js.map

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

@@ -18,7 +18,7 @@ const FactoryRecordSchema = z.object({
     createdAt: z.number().optional(),
     updatedAt: z.number().optional(),
     cwd: z.string().optional(),
-    version: z.string().optional(),
+    version: z.union([z.string(), z.number()]).optional(),
     message: z.object({
         id: z.string().optional(),
         role: z.string().optional(),
@@ -80,7 +80,7 @@ export class FactorySessionAdapter {
                 sawRecord = true;
                 const parsed = FactoryRecordSchema.safeParse(line.value);
                 if (!parsed.success) {
-                    throw new SessionContractError('MALFORMED_SOURCE', 'Factory session record is malformed');
+                    throw factoryMalformedRecord(source, line, parsed.error);
                 }
                 const value = parsed.data;
                 const currentSchema = value.schemaVersion ?? FACTORY_SOURCE_SCHEMA_VERSION;
@@ -90,12 +90,12 @@ export class FactorySessionAdapter {
                 schemaVersion = currentSchema;
                 assertSupportedSchemaMajor(schemaVersion);
                 const filenameId = basename(source.locator, extname(source.locator));
-                const currentId = value.sessionId ?? value.session_id ?? establishedId ?? filenameId;
+                const currentId = factoryNativeSessionId(value, establishedId, filenameId);
                 if (establishedId && establishedId !== currentId) {
                     throw new SessionContractError('DUPLICATE_NATIVE_ID', 'Factory source changes session identity');
                 }
                 establishedId = currentId;
-                for (const record of normalize([line], source).records) {
+                for (const record of normalize([line], source, establishedId).records) {
                     if (outputIndex++ >= start)
                         yield record;
                 }
@@ -162,24 +162,28 @@ export class FactorySessionAdapter {
         }));
     }
 }
-function normalize(input, source) {
+function normalize(input, source, initialSessionId) {
     const output = [];
     const filenameId = basename(source.locator, extname(source.locator));
     let complete = false;
-    let establishedId;
+    let establishedId = initialSessionId;
     for (const line of input) {
         const parsed = FactoryRecordSchema.safeParse(line.value);
         if (!parsed.success) {
-            throw new SessionContractError('MALFORMED_SOURCE', 'Factory session record is malformed');
+            throw factoryMalformedRecord(source, line, parsed.error);
         }
         const value = parsed.data;
-        const nativeSessionId = value.sessionId ?? value.session_id ?? establishedId ?? filenameId;
+        const nativeSessionId = factoryNativeSessionId(value, establishedId, filenameId);
         if (establishedId && nativeSessionId !== establishedId) {
             throw new SessionContractError('DUPLICATE_NATIVE_ID', 'Factory source changes session identity');
         }
         establishedId = nativeSessionId;
         complete ||= ['session_end', 'result'].includes(value.type)
             || ['completed', 'archived', 'deleted'].includes(value.status ?? '');
+        const explicitLifecycle = ['session_end', 'result'].includes(value.type)
+            || ['completed', 'archived', 'deleted'].includes(value.status ?? '')
+            ? lifecycle(value.status)
+            : undefined;
         const blocks = contentBlocks(value);
         if (blocks.length === 0)
             blocks.push({
@@ -199,13 +203,30 @@ function normalize(input, source) {
             kind: block.kind,
             role: value.message?.role,
             occurredAt: timestamp(value.timestamp ?? value.updatedAt ?? value.createdAt),
+            activityBoundary: value.type === 'session_end'
+                ? 'end'
+                : value.type === 'session_start' && value.subtype === 'resume'
+                    ? 'resume'
+                    : value.type === 'session_start' && value.subtype === 'continuation'
+                        ? 'continuation'
+                        : undefined,
+            activityBoundaryBasis: value.type === 'session_end'
+                || (value.type === 'session_start'
+                    && (value.subtype === 'resume' || value.subtype === 'continuation'))
+                ? `factory:${value.type}:${value.subtype ?? 'none'}`
+                : undefined,
+            activityBoundaryConfidence: value.type === 'session_end'
+                || (value.type === 'session_start'
+                    && (value.subtype === 'resume' || value.subtype === 'continuation'))
+                ? 'high'
+                : undefined,
             text: block.text,
             rawReference: { locatorClass: source.locatorClass, offset: line.byteOffset },
             extensions: {
                 subtype: value.subtype,
                 parentUuid: value.parentUuid,
                 productVersion: value.version ?? 'not-reported',
-                lifecycle: complete ? lifecycle(value.status) : 'active',
+                ...(explicitLifecycle ? { lifecycle: explicitLifecycle } : {}),
                 workspace: { cwdClass: value.cwd ? '<workspace>' : undefined },
                 settings: value.sessionSettings ?? value.settings,
                 opaque: block.opaque,
@@ -263,6 +284,15 @@ function contentBlocks(value) {
         return { kind: `factory.${type}`, text: '', opaque: true, nativeId, unknownFields: { ...block } };
     });
 }
+function factoryNativeSessionId(value, establishedId, filenameId) {
+    if (value.sessionId)
+        return value.sessionId;
+    if (value.session_id)
+        return value.session_id;
+    if (value.type === 'session_start' && value.id)
+        return value.id;
+    return establishedId ?? filenameId;
+}
 async function* discoverJsonl(root, maxDepth) {
     const pending = [{ path: root, depth: 0 }];
     while (pending.length) {
@@ -291,6 +321,17 @@ async function* discoverJsonl(root, maxDepth) {
             pending.push({ path, depth: current.depth + 1 });
     }
 }
+function factoryMalformedRecord(source, record, error) {
+    const value = asObject(record.value);
+    const rawType = typeof value.type === 'string' ? value.type : '';
+    const type = /^[a-zA-Z0-9_.:-]{1,64}$/.test(rawType) ? rawType : '<missing-or-invalid>';
+    const issue = error.issues[0];
+    const requirement = issue?.path.length
+        ? issue.path.map(String).join('.')
+        : 'record';
+    return new SessionContractError('MALFORMED_SOURCE', `Factory source ${basename(source.locator)} record ${record.sequence + 1} `
+        + `type ${type} failed requirement ${requirement} (${issue?.code ?? 'invalid_type'})`);
+}
 function declaredVersion(records) {
     const versions = new Set(records.flatMap((record) => {
         const value = asObject(record.value);

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

@@ -0,0 +1,121 @@
+export const BATCH_IMPORT_VERSION = '1.0.0';
+export const COVERAGE_VERSION = '1.0.0';
+export function coverageFromBatchRun(run, now = new Date(), staleAfterMs = 24 * 60 * 60 * 1_000) {
+    if (!run)
+        return unknownCoverage();
+    const coveredStatuses = new Set([
+        'committed', 'duplicate', 'previously-committed',
+    ]);
+    const accepted = run.sources.filter((source) => source.status === 'committed').length;
+    const rejected = run.sources.filter((source) => source.status === 'rejected').length;
+    const skipped = run.sources.filter((source) => source.status === 'skipped').length;
+    const duplicated = run.sources.filter((source) => source.status === 'duplicate').length;
+    const previouslyCommitted = run.sources.filter((source) => source.status === 'previously-committed').length;
+    const pending = run.sources.filter((source) => source.status === 'pending' || source.status === 'running').length;
+    const checked = providerNames(run, 'checked');
+    const unavailable = providerNames(run, 'unavailable');
+    const exportRequired = providerNames(run, 'export-required');
+    const notChecked = providerNames(run, 'not-checked');
+    const manifestAgeMs = Math.max(0, now.getTime() - Date.parse(run.manifestCreatedAt));
+    const isStale = manifestAgeMs > staleAfterMs;
+    const incomplete = rejected > 0 || pending > 0 || skipped > 0
+        || exportRequired.length > 0 || notChecked.length > 0;
+    const rejectionCounts = {};
+    for (const source of run.sources) {
+        if (source.status !== 'rejected')
+            continue;
+        const code = source.errorCode ?? 'UNKNOWN_REJECTION';
+        rejectionCounts[code] = (rejectionCounts[code] ?? 0) + 1;
+    }
+    const sourceTimestamps = run.providers.flatMap((provider) => [
+        provider.dateRange.earliest,
+        provider.dateRange.latest,
+    ]).filter((value) => value !== null).sort();
+    const importedTimestamps = run.sources
+        .filter((source) => coveredStatuses.has(source.status))
+        .map((source) => source.updatedAt)
+        .sort();
+    const remediation = [
+        ...(rejected > 0
+            ? ['Run `aiwg sessions import-discovered --resume --confirm` after correcting rejected sources.']
+            : []),
+        ...(exportRequired.length > 0
+            ? ['Export and explicitly authorize providers marked export-required, then run discovery again.']
+            : []),
+        ...(isStale ? ['Run `aiwg sessions discover` to refresh the stale manifest.'] : []),
+    ];
+    return {
+        schemaVersion: COVERAGE_VERSION,
+        status: isStale ? 'stale' : incomplete ? 'partial' : 'complete',
+        workspaceId: run.workspaceId,
+        manifestId: run.manifestId,
+        batchRunId: run.runId,
+        manifestCreatedAt: run.manifestCreatedAt,
+        manifestAgeMs,
+        providers: { checked, unavailable, exportRequired, notChecked },
+        sources: {
+            discovered: run.sources.length,
+            accepted,
+            rejected,
+            skipped,
+            duplicated,
+            previouslyCommitted,
+            pending,
+        },
+        sessionsAccepted: run.sources.reduce((sum, source) => sum + source.sessionsAccepted, 0),
+        eventsAccepted: run.sources.reduce((sum, source) => sum + source.eventsAccepted, 0),
+        coverageRatio: run.sources.length === 0
+            ? null
+            : (accepted + duplicated + previouslyCommitted) / run.sources.length,
+        rejectionCounts,
+        sourceDateRange: {
+            earliest: sourceTimestamps.at(0) ?? null,
+            latest: sourceTimestamps.at(-1) ?? null,
+        },
+        importedDateRange: {
+            earliest: importedTimestamps.at(0) ?? null,
+            latest: importedTimestamps.at(-1) ?? null,
+        },
+        remediation,
+    };
+}
+function providerNames(run, status) {
+    return run.providers
+        .filter((provider) => provider.status === status)
+        .map((provider) => provider.provider)
+        .sort();
+}
+function unknownCoverage() {
+    return {
+        schemaVersion: COVERAGE_VERSION,
+        status: 'unknown',
+        workspaceId: '',
+        manifestId: null,
+        batchRunId: null,
+        manifestCreatedAt: null,
+        manifestAgeMs: null,
+        providers: {
+            checked: [],
+            unavailable: [],
+            exportRequired: [],
+            notChecked: [],
+        },
+        sources: {
+            discovered: 0,
+            accepted: 0,
+            rejected: 0,
+            skipped: 0,
+            duplicated: 0,
+            previouslyCommitted: 0,
+            pending: 0,
+        },
+        sessionsAccepted: 0,
+        eventsAccepted: 0,
+        coverageRatio: null,
+        rejectionCounts: {},
+        sourceDateRange: { earliest: null, latest: null },
+        importedDateRange: { earliest: null, latest: null },
+        remediation: ['Run `aiwg sessions discover --workspace <path>` to establish coverage.'],
+    };
+}
+//# sourceMappingURL=batch-contracts.js.map