@aiwg/cli 2026.7.20 → 2026.7.21

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

@@ -0,0 +1,345 @@
+import { opendir } from 'node:fs/promises';
+import { basename, extname, resolve } from 'node:path';
+import { z } from 'zod';
+import { SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
+import { readBoundedJsonLines, streamBoundedJsonLines, } from '../readers.js';
+export const FACTORY_ADAPTER_VERSION = '1.0.0';
+export const FACTORY_SOURCE_SCHEMA_VERSION = '1.0.0';
+const FactoryRecordSchema = z.object({
+    schemaVersion: z.string().optional(),
+    type: z.string().min(1),
+    subtype: z.string().optional(),
+    uuid: z.string().min(1).optional(),
+    id: z.string().min(1).optional(),
+    parentUuid: z.string().nullable().optional(),
+    sessionId: z.string().min(1).optional(),
+    session_id: z.string().min(1).optional(),
+    timestamp: z.union([z.string(), z.number()]).optional(),
+    createdAt: z.number().optional(),
+    updatedAt: z.number().optional(),
+    cwd: z.string().optional(),
+    version: z.string().optional(),
+    message: z.object({
+        id: z.string().optional(),
+        role: z.string().optional(),
+        content: z.union([z.string(), z.array(z.unknown())]).optional(),
+    }).passthrough().optional(),
+    content: z.union([z.string(), z.array(z.unknown())]).optional(),
+    sessionSettings: z.record(z.unknown()).optional(),
+    settings: z.record(z.unknown()).optional(),
+    status: z.string().optional(),
+}).passthrough();
+export class FactorySessionAdapter {
+    limits;
+    transports;
+    discoveryLimits;
+    provider = 'factory';
+    adapterVersion = FACTORY_ADAPTER_VERSION;
+    disposition = 'implemented';
+    supportedOperations = ['discover', 'inspect', 'stream'];
+    acquisitionModes = ['jsonl', 'api'];
+    constructor(limits, transports = [], discoveryLimits = { maxDepth: 8, maxFiles: 10_000 }) {
+        this.limits = limits;
+        this.transports = transports;
+        this.discoveryLimits = discoveryLimits;
+    }
+    async *discover(scope) {
+        if (scope.allowedRoots.length === 0) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'Factory discovery requires an explicitly authorized projects 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', 'Factory source discovery exceeded the authorized file limit');
+                }
+                yield { provider: 'factory', locator, locatorClass: 'factory-droid-jsonl' };
+            }
+        }
+    }
+    async inspect(source) {
+        const parsed = await this.readSource(source);
+        return {
+            sourceSchemaVersion: parsed.schemaVersion,
+            consistency: parsed.consistency,
+            operationalState: 'available',
+        };
+    }
+    async *stream(source, cursor) {
+        if (source.locatorClass === 'factory-droid-jsonl') {
+            const input = await streamBoundedJsonLines({
+                selectedPath: source.locator,
+                allowedRoots: source.authorizedScope.allowedRoots,
+            }, { consistency: 'provisional', limits: this.limits });
+            const start = parseCursor(cursor?.value);
+            let outputIndex = 0;
+            let establishedId;
+            let schemaVersion = null;
+            let sawRecord = false;
+            for await (const line of input) {
+                sawRecord = true;
+                const parsed = FactoryRecordSchema.safeParse(line.value);
+                if (!parsed.success) {
+                    throw new SessionContractError('MALFORMED_SOURCE', 'Factory session record is malformed');
+                }
+                const value = parsed.data;
+                const currentSchema = value.schemaVersion ?? FACTORY_SOURCE_SCHEMA_VERSION;
+                if (schemaVersion && schemaVersion !== currentSchema) {
+                    throw new SessionContractError('SCHEMA_DRIFT', 'mixed Factory source schemas');
+                }
+                schemaVersion = currentSchema;
+                assertSupportedSchemaMajor(schemaVersion);
+                const filenameId = basename(source.locator, extname(source.locator));
+                const currentId = value.sessionId ?? value.session_id ?? 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) {
+                    if (outputIndex++ >= start)
+                        yield record;
+                }
+            }
+            if (!sawRecord && !input.incompleteTail) {
+                throw new SessionContractError('MALFORMED_SOURCE', 'Factory session source is empty');
+            }
+            return;
+        }
+        const parsed = await this.readSource(source);
+        const start = parseCursor(cursor?.value);
+        for (const record of parsed.records.slice(start))
+            yield record;
+    }
+    async readSource(source) {
+        let input;
+        let incompleteTail = false;
+        if (source.locatorClass === 'factory-droid-jsonl') {
+            const result = await readBoundedJsonLines({
+                selectedPath: source.locator,
+                allowedRoots: source.authorizedScope.allowedRoots,
+            }, { consistency: 'provisional', limits: this.limits });
+            input = result.records;
+            incompleteTail = result.incompleteTail;
+        }
+        else {
+            input = await this.remoteRecords(source);
+        }
+        if (input.length === 0 && !incompleteTail) {
+            throw new SessionContractError('MALFORMED_SOURCE', 'Factory session source is empty');
+        }
+        const schemaVersion = declaredVersion(input);
+        assertSupportedSchemaMajor(schemaVersion);
+        const normalized = normalize(input, source);
+        return {
+            schemaVersion,
+            consistency: normalized.complete && !incompleteTail ? 'complete' : 'provisional',
+            records: normalized.records,
+        };
+    }
+    async remoteRecords(source) {
+        const kind = source.locatorClass === 'factory-sessions-api'
+            ? 'sessions-api'
+            : source.locatorClass === 'factory-exec-stream'
+                ? 'droid-exec'
+                : undefined;
+        if (!kind)
+            throw new SessionContractError('UNSUPPORTED_OPERATION', 'unsupported Factory source class');
+        const operation = kind === 'sessions-api' ? 'factory.sessions.read' : 'factory.exec.stream';
+        if (source.authorizedScope.networkOperation !== operation
+            || (source.authorizedScope.authorizedAccounts?.length ?? 0) === 0) {
+            throw new SessionContractError('OPERATION_NOT_AUTHORIZED', `Factory ${kind} requires explicit account and ${operation} authorization`);
+        }
+        const transport = this.transports.find((candidate) => candidate.kind === kind);
+        if (!transport) {
+            throw new SessionContractError('UNSUPPORTED_OPERATION', `Factory ${kind} capability was not negotiated`);
+        }
+        const values = await transport.snapshot(source);
+        if (values.length > (this.limits?.maxRecords ?? 1_000_000)) {
+            throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'Factory remote record limit exceeded');
+        }
+        return values.map((value, sequence) => ({
+            value, sequence, byteOffset: sequence, byteLength: Buffer.byteLength(JSON.stringify(value)),
+        }));
+    }
+}
+function normalize(input, source) {
+    const output = [];
+    const filenameId = basename(source.locator, extname(source.locator));
+    let complete = false;
+    let establishedId;
+    for (const line of input) {
+        const parsed = FactoryRecordSchema.safeParse(line.value);
+        if (!parsed.success) {
+            throw new SessionContractError('MALFORMED_SOURCE', 'Factory session record is malformed');
+        }
+        const value = parsed.data;
+        const nativeSessionId = value.sessionId ?? value.session_id ?? 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 blocks = contentBlocks(value);
+        if (blocks.length === 0)
+            blocks.push({
+                kind: value.type === 'settings' ? 'factory.settings' : `factory.${value.type}`,
+                text: '',
+                opaque: value.type !== 'settings',
+                nativeId: undefined,
+                unknownFields: {},
+            });
+        blocks.forEach((block, index) => output.push({
+            nativeSessionId,
+            nativeEventId: block.nativeId
+                ?? (value.uuid ?? value.id ?? value.message?.id
+                    ? `${value.uuid ?? value.id ?? value.message?.id}:${index}`
+                    : undefined),
+            sequence: line.sequence * 1_000 + index,
+            kind: block.kind,
+            role: value.message?.role,
+            occurredAt: timestamp(value.timestamp ?? value.updatedAt ?? value.createdAt),
+            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',
+                workspace: { cwdClass: value.cwd ? '<workspace>' : undefined },
+                settings: value.sessionSettings ?? value.settings,
+                opaque: block.opaque,
+                provenance: {
+                    acquisition: source.locatorClass,
+                    schema: value.schemaVersion ?? FACTORY_SOURCE_SCHEMA_VERSION,
+                    apiNegotiated: source.locatorClass === 'factory-sessions-api',
+                    execNegotiated: source.locatorClass === 'factory-exec-stream',
+                },
+                unknownFields: {
+                    ...unknownFields(value, RECORD_KEYS),
+                    ...block.unknownFields,
+                },
+            },
+        }));
+    }
+    return { records: output, complete };
+}
+function contentBlocks(value) {
+    const content = value.message?.content ?? value.content;
+    if (typeof content === 'string') {
+        return [{ kind: 'message', text: content, opaque: false, unknownFields: {} }];
+    }
+    if (!Array.isArray(content))
+        return [];
+    return content.map((item) => {
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            return { kind: 'factory.unknown-block', text: '', opaque: true, unknownFields: { value: item } };
+        }
+        const block = item;
+        const type = typeof block.type === 'string' ? block.type : 'unknown';
+        const nativeId = typeof block.id === 'string'
+            ? block.id
+            : typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined;
+        if (type === 'text') {
+            return { kind: 'message', text: stringValue(block.text), opaque: false, nativeId,
+                unknownFields: unknownFields(block, new Set(['type', 'id', 'text'])) };
+        }
+        if (type === 'reasoning' || type === 'thinking') {
+            return { kind: 'reasoning', text: stringValue(block.text ?? block.thinking),
+                opaque: false, nativeId, unknownFields: unknownFields(block, new Set(['type', 'id', 'text', 'thinking'])) };
+        }
+        if (type === 'tool_use') {
+            return { kind: 'tool-call', text: stringValue(block.name), opaque: false, nativeId,
+                unknownFields: unknownFields(block, new Set(['type', 'id', 'name', 'input'])) };
+        }
+        if (type === 'tool_result') {
+            return { kind: 'tool-result', text: extractText(block.content), opaque: false, nativeId,
+                unknownFields: unknownFields(block, new Set(['type', 'tool_use_id', 'content', 'is_error'])) };
+        }
+        if (type === 'image') {
+            return { kind: 'image', text: '', opaque: true, nativeId,
+                unknownFields: { mediaType: block.media_type ?? block.source } };
+        }
+        return { kind: `factory.${type}`, text: '', opaque: true, nativeId, unknownFields: { ...block } };
+    });
+}
+async function* discoverJsonl(root, maxDepth) {
+    const pending = [{ path: root, depth: 0 }];
+    while (pending.length) {
+        const current = pending.shift();
+        let directory;
+        try {
+            directory = await opendir(current.path);
+        }
+        catch {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'authorized Factory root is inaccessible');
+        }
+        const directories = [];
+        const files = [];
+        for await (const entry of directory) {
+            const path = resolve(current.path, entry.name);
+            if (entry.isSymbolicLink())
+                continue;
+            if (entry.isDirectory() && current.depth < maxDepth)
+                directories.push(path);
+            else if (entry.isFile() && entry.name.endsWith('.jsonl'))
+                files.push(path);
+        }
+        for (const file of files.sort())
+            yield file;
+        for (const path of directories.sort())
+            pending.push({ path, depth: current.depth + 1 });
+    }
+}
+function declaredVersion(records) {
+    const versions = new Set(records.flatMap((record) => {
+        const value = asObject(record.value);
+        return typeof value.schemaVersion === 'string' ? [value.schemaVersion] : [];
+    }));
+    if (versions.size > 1)
+        throw new SessionContractError('SCHEMA_DRIFT', 'mixed Factory schema versions');
+    return [...versions][0] ?? FACTORY_SOURCE_SCHEMA_VERSION;
+}
+function timestamp(value) {
+    if (value === undefined)
+        return undefined;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
+}
+function lifecycle(status) {
+    if (status === 'archived')
+        return 'archived';
+    if (status === 'deleted')
+        return 'deleted';
+    return 'complete';
+}
+function extractText(value) {
+    if (typeof value === 'string')
+        return value;
+    if (!Array.isArray(value))
+        return '';
+    return value.map((item) => stringValue(asObject(item).text)).filter(Boolean).join('\n');
+}
+function stringValue(value) {
+    return typeof value === 'string' ? value : '';
+}
+function asObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value : {};
+}
+function unknownFields(value, keys) {
+    return Object.fromEntries(Object.entries(value).filter(([key]) => !keys.has(key)).sort(([a], [b]) => a.localeCompare(b)));
+}
+function parseCursor(value) {
+    if (!value)
+        return 0;
+    if (!/^\d+$/.test(value))
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid Factory cursor');
+    return Number(value);
+}
+const RECORD_KEYS = new Set([
+    'schemaVersion', 'type', 'subtype', 'uuid', 'id', 'parentUuid', 'sessionId',
+    'session_id', 'timestamp', 'createdAt', 'updatedAt', 'cwd', 'version', 'message',
+    'content', 'sessionSettings', 'settings', 'status',
+]);
+//# sourceMappingURL=factory.js.map

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

@@ -0,0 +1,225 @@
+import { z } from 'zod';
+import { SessionContractError, assertSupportedSchemaMajor, } from '../contracts.js';
+import { streamBoundedJsonLines } from '../readers.js';
+export const GENERIC_INTERCHANGE_KIND = 'aiwg.session-interchange';
+export const GENERIC_ADAPTER_VERSION = '1.0.0';
+const Rfc3339Schema = z.string().refine((value) => /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(value)
+    && !Number.isNaN(Date.parse(value)), 'timestamp must be RFC 3339 with an explicit UTC offset');
+export const GenericInterchangeHeaderSchema = z.object({
+    type: z.literal(GENERIC_INTERCHANGE_KIND),
+    schemaVersion: z.string().regex(/^\d+\.\d+\.\d+$/),
+    product: z.string().min(1),
+    productVersion: z.string().min(1),
+    sourceId: z.string().min(1),
+    exportedAt: Rfc3339Schema,
+    consistency: z.enum(['provisional', 'consistent-snapshot', 'complete']),
+    lifecycle: z.enum(['active', 'complete', 'archived']),
+    workspace: z.object({
+        id: z.string().min(1),
+        name: z.string().min(1).optional(),
+        repository: z.string().min(1).optional(),
+        branch: z.string().min(1).optional(),
+    }).passthrough(),
+    provenance: z.object({
+        exporter: z.string().min(1),
+        exporterVersion: z.string().min(1),
+        sourceClass: z.string().min(1),
+    }).passthrough(),
+    extensions: z.record(z.unknown()).default({}),
+}).passthrough();
+export const GenericInterchangeEventSchema = z.object({
+    type: z.literal('event'),
+    sessionId: z.string().min(1),
+    eventId: z.string().min(1),
+    sequence: z.number().int().nonnegative(),
+    kind: z.string().min(1),
+    role: z.string().min(1).optional(),
+    participant: z.string().min(1).optional(),
+    toolName: z.string().min(1).optional(),
+    toolCallId: z.string().min(1).optional(),
+    model: z.string().min(1).optional(),
+    entities: z.array(z.string().min(1)).optional(),
+    extractionState: z.string().min(1).optional(),
+    occurredAt: Rfc3339Schema.optional(),
+    text: z.string(),
+    lifecycle: z.enum(['active', 'complete', 'archived']),
+    extensions: z.record(z.unknown()).default({}),
+}).passthrough();
+export class GenericSessionInterchangeAdapter {
+    limits;
+    provider = 'generic';
+    adapterVersion = GENERIC_ADAPTER_VERSION;
+    disposition = 'manual-only';
+    supportedOperations = ['inspect', 'stream'];
+    acquisitionModes = ['manual-export'];
+    constructor(limits) {
+        this.limits = limits;
+    }
+    async *discover(_scope) {
+        throw new SessionContractError('UNSUPPORTED_OPERATION', 'generic interchange does not support automatic discovery; select an exported file explicitly');
+    }
+    async inspect(source) {
+        const input = await this.openStream(source);
+        let header = null;
+        const eventIds = new Set();
+        const sessionSequences = new Set();
+        for await (const record of input) {
+            if (!header) {
+                header = this.validateHeader(record.value, source);
+                continue;
+            }
+            const event = parseEvent(record.value);
+            if (eventIds.has(event.eventId)) {
+                throw new SessionContractError('DUPLICATE_NATIVE_ID', 'generic interchange contains a duplicate event ID');
+            }
+            eventIds.add(event.eventId);
+            const sequenceKey = `${event.sessionId}\0${event.sequence}`;
+            if (sessionSequences.has(sequenceKey)) {
+                throw new SessionContractError('DUPLICATE_NATIVE_ID', 'generic interchange contains a duplicate session sequence');
+            }
+            sessionSequences.add(sequenceKey);
+        }
+        if (!header)
+            throw new SessionContractError('MALFORMED_SOURCE', 'generic interchange is empty');
+        if (input.incompleteTail) {
+            throw new SessionContractError('TRUNCATED_SOURCE', 'generic interchange contains a truncated record');
+        }
+        return {
+            sourceSchemaVersion: header.schemaVersion,
+            consistency: header.consistency,
+            operationalState: 'available',
+        };
+    }
+    async *stream(source, cursor) {
+        const byteCursor = parseByteCursor(cursor?.value);
+        let header = null;
+        if (byteCursor !== null) {
+            const headerStream = await this.openStream(source);
+            const iterator = headerStream[Symbol.asyncIterator]();
+            const first = await iterator.next();
+            await iterator.return?.();
+            if (first.done)
+                throw new SessionContractError('MALFORMED_SOURCE', 'generic interchange is empty');
+            header = this.validateHeader(first.value.value, source);
+        }
+        const input = await this.openStream(source, byteCursor ?? undefined);
+        const start = byteCursor === null ? parseEventCursor(cursor?.value) : 0;
+        let eventIndex = 0;
+        const eventIds = new Set();
+        const sessionSequences = new Set();
+        for await (const record of input) {
+            if (!header) {
+                header = this.validateHeader(record.value, source);
+                continue;
+            }
+            const event = parseEvent(record.value);
+            if (eventIds.has(event.eventId)) {
+                throw new SessionContractError('DUPLICATE_NATIVE_ID', 'generic interchange contains a duplicate event ID');
+            }
+            eventIds.add(event.eventId);
+            const sequenceKey = `${event.sessionId}\0${event.sequence}`;
+            if (sessionSequences.has(sequenceKey)) {
+                throw new SessionContractError('DUPLICATE_NATIVE_ID', 'generic interchange contains a duplicate session sequence');
+            }
+            sessionSequences.add(sequenceKey);
+            if (eventIndex++ < start)
+                continue;
+            const knownKeys = new Set([
+                'type', 'sessionId', 'eventId', 'sequence', 'kind', 'role',
+                'occurredAt', 'text', 'lifecycle', 'extensions', 'participant',
+                'toolName', 'toolCallId', 'model', 'entities', 'extractionState',
+            ]);
+            const unknownFields = Object.fromEntries(Object.entries(event).filter(([key]) => !knownKeys.has(key)));
+            yield {
+                nativeSessionId: event.sessionId,
+                nativeEventId: event.eventId,
+                sequence: event.sequence,
+                kind: event.kind,
+                role: event.role,
+                participant: event.participant,
+                toolName: event.toolName,
+                toolCallId: event.toolCallId,
+                model: event.model,
+                entities: event.entities,
+                extractionState: event.extractionState,
+                sourceCursor: `byte:${record.byteOffset + record.byteLength}`,
+                sourceBytes: record.byteLength,
+                occurredAt: event.occurredAt,
+                text: event.text,
+                rawReference: { locatorClass: 'generic-interchange', sequence: event.sequence },
+                extensions: {
+                    ...event.extensions,
+                    unknownFields,
+                    lifecycle: event.lifecycle,
+                    workspace: header.workspace,
+                    provenance: header.provenance,
+                    product: header.product,
+                    productVersion: header.productVersion,
+                },
+            };
+        }
+        if (!header) {
+            throw new SessionContractError('MALFORMED_SOURCE', 'generic interchange is empty');
+        }
+        if (input.incompleteTail) {
+            throw new SessionContractError('TRUNCATED_SOURCE', 'generic interchange contains a truncated record');
+        }
+    }
+    openStream(source, cursor) {
+        return streamBoundedJsonLines({
+            selectedPath: source.locator,
+            allowedRoots: source.authorizedScope.allowedRoots,
+        }, {
+            cursor: cursor === undefined ? undefined : String(cursor),
+            consistency: 'provisional',
+            limits: this.limits,
+        });
+    }
+    validateHeader(value, source) {
+        const header = parseHeader(value);
+        assertSupportedSchemaMajor(header.schemaVersion);
+        if (header.sourceId !== source.sourceId) {
+            throw new SessionContractError('SCHEMA_DRIFT', 'selected source identity does not match interchange header');
+        }
+        return header;
+    }
+}
+function parseByteCursor(value) {
+    if (!value?.startsWith('byte:'))
+        return null;
+    const position = value.slice(5);
+    if (!/^\d+$/.test(position)) {
+        throw new SessionContractError('SCHEMA_DRIFT', 'invalid generic byte cursor');
+    }
+    return Number(position);
+}
+function parseHeader(value) {
+    const result = GenericInterchangeHeaderSchema.safeParse(value);
+    if (result.success)
+        return result.data;
+    if (hasAmbiguousTimestamp(result.error)) {
+        throw new SessionContractError('AMBIGUOUS_TIMESTAMP', 'generic interchange header has an ambiguous timestamp');
+    }
+    throw new SessionContractError('MALFORMED_SOURCE', 'input is not a declared AIWG generic session interchange');
+}
+function parseEvent(value) {
+    const result = GenericInterchangeEventSchema.safeParse(value);
+    if (result.success)
+        return result.data;
+    if (hasAmbiguousTimestamp(result.error)) {
+        throw new SessionContractError('AMBIGUOUS_TIMESTAMP', 'generic interchange event has an ambiguous timestamp');
+    }
+    throw new SessionContractError('MALFORMED_SOURCE', 'generic interchange event is malformed');
+}
+function hasAmbiguousTimestamp(error) {
+    return error.issues.some((issue) => issue.code === z.ZodIssueCode.custom
+        && (issue.path.at(-1) === 'occurredAt' || issue.path.at(-1) === 'exportedAt'));
+}
+function parseEventCursor(value) {
+    if (value === undefined || value === '')
+        return 0;
+    if (!/^\d+$/.test(value))
+        throw new SessionContractError('SCHEMA_DRIFT', 'generic event cursor is invalid');
+    return Number(value);
+}
+//# sourceMappingURL=generic.js.map