@aiwg/cli 2026.7.20 → 2026.7.23

package/dist/src/sessions/optional-backends.js

@@ -0,0 +1,238 @@
+import { sha256, SessionContractError } from './contracts.js';
+export class FortemiSessionRepositoryBackend {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    previewImport(batch) {
+        const workspaceIds = [...new Set(batch.sessions.map((session) => session.workspaceId))];
+        if (workspaceIds.length !== 1) {
+            throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'optional backend import must contain exactly one workspace scope');
+        }
+        return repositoryPreview({
+            operation: 'upsert',
+            workspaceId: workspaceIds[0],
+            sourceId: batch.source.sourceId,
+            eventIdentities: batch.events.map((event) => `${event.eventId}:${event.digest}`),
+            transfersApprovedText: true,
+        });
+    }
+    async applyImport(batch, checkpoint, authorization) {
+        this.assertCapabilities();
+        const preview = this.previewImport(batch);
+        assertRepositoryAuthorization(preview, authorization);
+        const result = await this.options.client.callTool('upsert_external_notes', {
+            source_namespace: `aiwg.sessions.${batch.source.provider}`,
+            source_id: batch.source.sourceId,
+            source_schema_version: batch.source.sourceSchemaVersion,
+            import_run_id: batch.run.importRunId,
+            workspace_id: preview.workspaceId,
+            items: batch.events.map((event) => ({
+                external_id: event.eventId,
+                content: event.searchableText,
+                content_digest: event.digest,
+                metadata: {
+                    session_id: event.sessionId,
+                    import_run_id: event.importRunId,
+                    locator_class: batch.source.locatorClass,
+                    role: event.role,
+                    sensitivity: event.sensitivity.classification,
+                },
+            })),
+        });
+        return {
+            operationId: batch.run.importRunId,
+            outcome: result?.outcome ?? 'committed',
+            sessionsInserted: result?.sessions_inserted ?? batch.sessions.length,
+            eventsInserted: result?.events_inserted ?? batch.events.length,
+            checkpoint,
+        };
+    }
+    previewTombstone(workspaceId, sessionId, eventIds) {
+        return repositoryPreview({
+            operation: 'tombstone',
+            workspaceId,
+            sessionId,
+            eventIdentities: eventIds,
+            transfersApprovedText: false,
+        });
+    }
+    async tombstone(workspaceId, sessionId, eventIds, authorization) {
+        this.assertCapabilities(true);
+        const preview = this.previewTombstone(workspaceId, sessionId, eventIds);
+        assertRepositoryAuthorization(preview, authorization);
+        const result = await this.options.client.callTool('purge_external_notes', {
+            workspace_id: workspaceId,
+            session_id: sessionId,
+            external_ids: [...eventIds],
+            mode: 'tombstone',
+        });
+        return {
+            operationId: preview.operationId,
+            outcome: 'committed',
+            affected: result?.affected ?? eventIds.length,
+        };
+    }
+    assertCapabilities(requireGraphPurge = false) {
+        if (!this.options.capabilities.sourceAddressedUpsert
+            || !this.options.capabilities.typedMetadataPredicates
+            || !this.options.capabilities.evidenceLocators
+            || (requireGraphPurge && !this.options.capabilities.graphPurge)) {
+            throw new SessionContractError('UNSUPPORTED_OPERATION', 'Fortemi session repository requires source upsert, typed predicates, evidence locators, and graph purge for deletion');
+        }
+    }
+}
+export class FortemiSessionBackend {
+    options;
+    id = 'fortemi';
+    requiresNetwork = true;
+    requiresModel = true;
+    constructor(options) {
+        this.options = options;
+    }
+    async rank(request) {
+        if (!this.options.capabilities.sourceAddressedUpsert
+            || !this.options.capabilities.typedMetadataPredicates
+            || !this.options.capabilities.evidenceLocators) {
+            throw new SessionContractError('UNSUPPORTED_OPERATION', 'Fortemi session integration requires source upsert, typed predicates, and evidence locators');
+        }
+        const result = await this.options.client.callTool('search', {
+            query: request.query,
+            mode: 'hybrid',
+            predicates: [{ path: 'workspace_id', op: 'eq', value: request.workspaceId }],
+            candidates: request.documents.map((document) => ({
+                external_id: document.eventId,
+                content: document.text,
+                citation: document.citation,
+            })),
+        });
+        return (result?.results ?? [])
+            .filter((entry) => typeof entry.external_id === 'string' && typeof entry.score === 'number')
+            .map((entry) => ({ eventId: entry.external_id, score: entry.score }));
+    }
+}
+export class SessionSearchService {
+    lexical;
+    constructor(lexical) {
+        this.lexical = lexical;
+    }
+    preview(options, backend) {
+        const documents = this.documents(options);
+        return createPreview(options, backend, documents);
+    }
+    async search(request) {
+        if ((request.mode ?? 'lexical') === 'lexical' || !request.backend) {
+            return this.lexical.search(request.options);
+        }
+        const documents = this.documents(request.options);
+        const preview = createPreview(request.options, request.backend, documents);
+        if (!request.authorization?.approved
+            || request.authorization.operationId !== preview.operationId) {
+            throw new SessionContractError(request.backend.requiresNetwork ? 'NETWORK_NOT_AUTHORIZED' : 'OPERATION_NOT_AUTHORIZED', 'optional semantic/backend search requires approval of the exact preview operation');
+        }
+        const ranked = await request.backend.rank({
+            query: request.options.query,
+            workspaceId: request.options.workspaceId,
+            documents: documents.map((document) => ({
+                eventId: document.eventId,
+                text: document.searchableText,
+                citation: document.citation,
+            })),
+        });
+        const authorized = new Map(documents.map((document) => [document.eventId, document]));
+        const semanticByEvent = new Map();
+        for (const candidate of ranked) {
+            if (!Number.isFinite(candidate.score) || !authorized.has(candidate.eventId))
+                continue;
+            semanticByEvent.set(candidate.eventId, Math.max(semanticByEvent.get(candidate.eventId) ?? Number.NEGATIVE_INFINITY, candidate.score));
+        }
+        const semantic = [...semanticByEvent.entries()]
+            .map(([eventId, score]) => ({ eventId, score }))
+            .sort((left, right) => right.score - left.score || left.eventId.localeCompare(right.eventId));
+        const lexical = this.lexical.search({
+            ...request.options,
+            limit: Math.min(500, Math.max(request.options.limit * 2, request.options.limit)),
+            cursor: undefined,
+        }).items;
+        const scores = new Map();
+        lexical.forEach((hit, index) => scores.set(hit.eventId, 1 / (60 + index + 1)));
+        semantic.forEach((hit, index) => {
+            scores.set(hit.eventId, (scores.get(hit.eventId) ?? 0) + 1 / (60 + index + 1));
+        });
+        const publicHits = new Map([
+            ...documents.map(({ searchableText: _text, ...hit }) => [hit.eventId, hit]),
+            ...lexical.map((hit) => [hit.eventId, hit]),
+        ]);
+        const items = [...scores.entries()]
+            .map(([eventId, score]) => ({ hit: publicHits.get(eventId), score }))
+            .filter((entry) => Boolean(entry.hit))
+            .sort((left, right) => right.score - left.score
+            || left.hit.eventId.localeCompare(right.hit.eventId))
+            .slice(0, request.options.limit)
+            .map(({ hit, score }) => ({ ...hit, score }));
+        return { items, nextCursor: null };
+    }
+    documents(options) {
+        const { query: _query, cursor: _cursor, ...scope } = options;
+        return this.lexical.authorizedSearchDocuments({
+            ...scope,
+            limit: Math.min(500, Math.max(100, options.limit * 20)),
+        });
+    }
+}
+function createPreview(options, backend, documents) {
+    const operationId = sha256(JSON.stringify({
+        backend: backend.id,
+        mode: 'hybrid',
+        workspaceId: options.workspaceId,
+        queryDigest: sha256(options.query),
+        scopeDigest: sha256(JSON.stringify({
+            providers: options.providers ?? [],
+            dateFrom: options.dateFrom ?? null,
+            dateTo: options.dateTo ?? null,
+            participant: options.participant ?? null,
+            model: options.model ?? null,
+            role: options.role ?? null,
+            tool: options.tool ?? null,
+            tag: options.tag ?? null,
+            entity: options.entity ?? null,
+            sensitivity: options.sensitivity ?? null,
+            extractionState: options.extractionState ?? null,
+            limit: options.limit,
+        })),
+        eventIds: documents.map((document) => document.eventId),
+        requiresNetwork: backend.requiresNetwork,
+        requiresModel: backend.requiresModel,
+    }));
+    return {
+        contractVersion: '1.0.0',
+        operationId,
+        backend: backend.id,
+        mode: 'hybrid',
+        workspaceId: options.workspaceId,
+        candidateCount: documents.length,
+        transfersApprovedText: true,
+        requiresNetwork: backend.requiresNetwork,
+        requiresModel: backend.requiresModel,
+    };
+}
+function repositoryPreview(input) {
+    return {
+        contractVersion: '1.0.0',
+        operationId: sha256(JSON.stringify(input)),
+        backend: 'fortemi',
+        operation: input.operation,
+        workspaceId: input.workspaceId,
+        sourceId: input.sourceId,
+        sessionId: input.sessionId,
+        eventCount: input.eventIdentities.length,
+        transfersApprovedText: input.transfersApprovedText,
+        requiresNetwork: true,
+    };
+}
+function assertRepositoryAuthorization(preview, authorization) {
+    if (!authorization?.approved || authorization.operationId !== preview.operationId) {
+        throw new SessionContractError('NETWORK_NOT_AUTHORIZED', 'optional repository operation requires approval of the exact preview operation');
+    }
+}
+//# sourceMappingURL=optional-backends.js.map

package/dist/src/sessions/origin.js

@@ -0,0 +1,117 @@
+export const ORIGIN_CLASSIFIER_VERSION = '1.0.0';
+export function classifySessionEventOrigin(provider, record) {
+    const envelope = classifyWholeEnvelope(record.text);
+    if (envelope)
+        return envelope;
+    const kind = record.kind.toLowerCase();
+    if (isProviderBootstrap(provider, kind)) {
+        return classified('provider-bootstrap', `${provider}:structured-bootstrap`);
+    }
+    if (isToolControl(kind, record.role)) {
+        return classified('tool-control', `${provider}:structured-control`);
+    }
+    if (record.role === 'assistant') {
+        return classified('assistant-generated', `${provider}:assistant-role`);
+    }
+    if (record.role === 'user' && kind === 'message' && record.text.trim().length > 0) {
+        return classified('user-authored', `${provider}:user-message`);
+    }
+    return classified('unknown', `${provider}:insufficient-authorship-evidence`);
+}
+export function isControlOrigin(origin) {
+    return origin === 'provider-bootstrap'
+        || origin === 'workspace-instruction'
+        || origin === 'tool-control';
+}
+export function deriveSessionIntent(events) {
+    const eligible = events
+        .filter((event) => event.origin === 'user-authored'
+        && event.kind === 'message'
+        && event.searchableText.trim().length > 0)
+        .sort((left, right) => left.sequence - right.sequence || left.eventId.localeCompare(right.eventId));
+    const selected = eligible[0];
+    if (selected) {
+        const summary = normalizeExcerpt(selected.searchableText, 240);
+        return {
+            status: 'selected',
+            eventId: selected.eventId,
+            sequence: selected.sequence,
+            title: normalizeExcerpt(summary.split('\n')[0], 80),
+            summary,
+        };
+    }
+    const uncertain = events.some((event) => event.origin === 'unknown' && event.searchableText.trim().length > 0);
+    return {
+        status: uncertain ? 'unknown' : 'absent',
+        eventId: null,
+        sequence: null,
+        title: null,
+        summary: null,
+    };
+}
+function classifyWholeEnvelope(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return null;
+    if (/^# AGENTS\.md instructions for [^\n]+\n+<INSTRUCTIONS>\n[\s\S]*\n<\/INSTRUCTIONS>$/.test(trimmed)) {
+        return classified('workspace-instruction', 'envelope:agents-instructions');
+    }
+    for (const tag of [
+        'recommended_plugins',
+        'codex_internal_context',
+        'environment_context',
+    ]) {
+        if (wholeTag(trimmed, tag)) {
+            return classified('provider-bootstrap', `envelope:${tag}`);
+        }
+    }
+    if (wholeTag(trimmed, 'local-command-caveat')) {
+        return classified('tool-control', 'envelope:local-command-caveat');
+    }
+    if (/^<[A-Za-z_][\w.-]*(?:\s[^>]*)?>[\s\S]*<\/[A-Za-z_][\w.-]*>$/.test(trimmed)) {
+        return classified('unknown', 'envelope:unrecognized');
+    }
+    return null;
+}
+function wholeTag(value, tag) {
+    const escaped = tag.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`^<${escaped}(?:\\s[^>]*)?>[\\s\\S]*<\\/${escaped}>$`).test(value);
+}
+function isProviderBootstrap(provider, kind) {
+    if (provider === 'codex') {
+        return kind === 'codex.session_meta'
+            || kind === 'codex.turn_context'
+            || kind === 'codex.thread-state';
+    }
+    if (provider === 'factory') {
+        return kind === 'factory.session_start' || kind === 'factory.settings';
+    }
+    if (provider === 'cursor')
+        return kind === 'system';
+    return false;
+}
+function isToolControl(kind, role) {
+    return role === 'tool'
+        || role === 'system'
+        || kind === 'lifecycle-hook'
+        || kind === 'tool-call'
+        || kind === 'tool-result'
+        || kind === 'summary'
+        || kind.includes('lifecycle')
+        || kind.startsWith('tool.')
+        || kind.startsWith('cursor.cloud.')
+        || kind === 'cursor.agent.turn_ended'
+        || kind === 'factory.session_end';
+}
+function classified(origin, rule) {
+    return {
+        origin,
+        rule,
+        classifierVersion: ORIGIN_CLASSIFIER_VERSION,
+    };
+}
+function normalizeExcerpt(value, max) {
+    const normalized = value.replace(/\s+/g, ' ').trim();
+    return normalized.length <= max ? normalized : `${normalized.slice(0, max - 1)}…`;
+}
+//# sourceMappingURL=origin.js.map

package/dist/src/sessions/policy.js

@@ -0,0 +1,192 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+import { SessionContractError } from './contracts.js';
+export async function authorizeSourceFile(input) {
+    if (input.allowedRoots.length === 0) {
+        throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'an explicitly selected allowed root is required');
+    }
+    const selected = resolve(input.selectedPath);
+    const selectedStat = await safeLstat(selected);
+    if (selectedStat.isSymbolicLink() && !input.allowSymlink) {
+        throw new SessionContractError('SOURCE_SYMLINK', 'symbolic-link session sources are disabled');
+    }
+    const canonicalPath = await safeRealpath(selected);
+    const roots = await Promise.all(input.allowedRoots.map(async (root) => ({
+        input: root,
+        canonical: await safeRealpath(resolve(root), true),
+    })));
+    const matchingRoot = roots.find(({ canonical }) => {
+        const rel = relative(canonical, canonicalPath);
+        return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel));
+    });
+    if (!matchingRoot) {
+        throw new SessionContractError('SOURCE_OUTSIDE_ALLOWED_ROOT', 'source is outside the explicitly allowed roots');
+    }
+    const stat = await safeLstat(canonicalPath);
+    if (!stat.isFile()) {
+        throw new SessionContractError('SOURCE_NOT_REGULAR_FILE', 'session source must be a regular file');
+    }
+    if (input.maxBytes !== undefined && stat.size > input.maxBytes) {
+        throw new SessionContractError('RESOURCE_LIMIT_EXCEEDED', 'session source exceeds the authorized byte limit');
+    }
+    return {
+        canonicalPath,
+        rootClass: matchingRoot.input,
+        size: stat.size,
+        mtimeMs: stat.mtimeMs,
+        dev: stat.dev,
+        ino: stat.ino,
+    };
+}
+async function safeLstat(path) {
+    try {
+        return await lstat(path);
+    }
+    catch {
+        throw new SessionContractError('SOURCE_NOT_AUTHORIZED', 'selected session source is inaccessible');
+    }
+}
+async function safeRealpath(path, root = false) {
+    try {
+        return await realpath(path);
+    }
+    catch {
+        throw new SessionContractError('SOURCE_NOT_AUTHORIZED', root ? 'an authorized source root is inaccessible' : 'selected session source is inaccessible');
+    }
+}
+const SECRET_PATTERNS = [
+    ['private-key', /-----BEGIN (?:RSA |EC |OPENSSH )?PRIVATE KEY-----[\s\S]*?-----END (?:RSA |EC |OPENSSH )?PRIVATE KEY-----/g],
+    ['bearer-token', /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}\b/gi],
+    ['authorization', /\bAuthorization\s*:\s*[^\r\n]+/gi],
+    ['cookie', /\b(?:Cookie|Set-Cookie)\s*:\s*[^\r\n]+/gi],
+    ['credential', /\b(?:api[_-]?key|token|password|secret)\s*(?:[:=]|\s)\s*["']?[^\s"',;]{6,}/gi],
+    ['provider-token', /\b(?:sk-(?:proj-)?|gh[pousr]_|github_pat_|xox[baprs]-|AKIA)[A-Za-z0-9._~+/=-]{8,}\b/g],
+    ['connection-string', /\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis):\/\/[^\s]+/gi],
+    ['credential-url', /\bhttps?:\/\/[^/\s:@]+:[^/\s@]+@[^\s]+/gi],
+    ['environment-assignment', /\b[A-Z][A-Z0-9_]*(?:TOKEN|SECRET|PASSWORD|PASSWD|API_KEY)\s*=\s*(?:"[^"]+"|'[^']+'|[^\s]+)/g],
+    ['fixture-credential', /\bredaction-canary-[A-Za-z0-9_-]+\b/gi],
+    ['email', /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi],
+];
+const SENSITIVE_KEY = /(?:authorization|auth[_-]?header|cookie|credential|password|passwd|secret|token|api[_-]?key|private[_-]?key|connection[_-]?string)/i;
+const CONTENT_KEY = /(?:^|[_-])(?:text|content|prompt|command|arguments?|args|result|output|body|request|response|source|code|query)(?:$|[_-])/i;
+const PATH_KEY = /(?:^|[_-])(?:path|cwd|directory|filename|file)(?:$|[_-])/i;
+const SAFE_STRING_KEY = /(?:^|[_-])(?:id|kind|type|role|status|state|lifecycle|reason|name|product|provider|version|schema|model|format|class|mode|event|operation|tool|method|language|scope|consistency|disposition|phase|visibility|protocol|category|classification)(?:$|[_-])/i;
+const CONTROL_CHARACTERS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g;
+const DEFAULT_NATIVE_LIMITS = {
+    maxDepth: 8,
+    maxNodes: 2_048,
+    maxObjectKeys: 128,
+    maxArrayItems: 256,
+    maxStringBytes: 8 * 1024,
+};
+/**
+ * Classify and sanitize provider-native attributes before they cross the
+ * persistence boundary. Decisions contain counts only and are safe for audit.
+ */
+export function sanitizeNativeExtensions(input, overrides = {}) {
+    const limits = { ...DEFAULT_NATIVE_LIMITS, ...overrides };
+    const classes = new Set();
+    const decisions = {};
+    const active = new WeakSet();
+    let nodes = 0;
+    const marker = (classification) => {
+        classes.add(classification);
+        decisions[classification] = (decisions[classification] ?? 0) + 1;
+        return `[REDACTED:${classification}]`;
+    };
+    const visit = (value, key, depth) => {
+        const classifiedKey = key.replace(/([a-z0-9])([A-Z])/g, '$1-$2');
+        nodes += 1;
+        if (nodes > limits.maxNodes)
+            return marker('node-limit');
+        if (depth > limits.maxDepth)
+            return marker('depth-limit');
+        if (value === null || typeof value === 'boolean' || typeof value === 'number')
+            return value;
+        if (typeof value === 'bigint')
+            return String(value);
+        if (typeof value !== 'string' && typeof value !== 'object') {
+            return marker('unsupported-value');
+        }
+        if (typeof value === 'string') {
+            if (SENSITIVE_KEY.test(classifiedKey))
+                return marker('sensitive-field');
+            if (CONTENT_KEY.test(classifiedKey))
+                return marker('content');
+            if (PATH_KEY.test(classifiedKey))
+                return marker('path');
+            if (Buffer.byteLength(value) > limits.maxStringBytes)
+                return marker('string-limit');
+            const redacted = redactSessionText(value);
+            for (const classification of redacted.classes)
+                classes.add(classification);
+            if (redacted.classes.length) {
+                decisions['classified-value'] = (decisions['classified-value'] ?? 0) + 1;
+                return redacted.text.replace(CONTROL_CHARACTERS, ' ');
+            }
+            if (!SAFE_STRING_KEY.test(classifiedKey))
+                return marker('unclassified-field');
+            return value.replace(/\r?\n/g, ' ').replace(CONTROL_CHARACTERS, ' ');
+        }
+        if (active.has(value))
+            return marker('circular-reference');
+        active.add(value);
+        try {
+            if (Array.isArray(value)) {
+                const selected = value.slice(0, limits.maxArrayItems)
+                    .map((entry) => visit(entry, key, depth + 1));
+                if (value.length > limits.maxArrayItems)
+                    selected.push(marker('array-limit'));
+                return selected;
+            }
+            const output = {};
+            const entries = Object.entries(value);
+            for (const [childKey, childValue] of entries.slice(0, limits.maxObjectKeys)) {
+                output[childKey.replace(/\r?\n/g, ' ').replace(CONTROL_CHARACTERS, '')] =
+                    visit(childValue, childKey, depth + 1);
+            }
+            if (entries.length > limits.maxObjectKeys)
+                output.__truncated__ = marker('object-key-limit');
+            return output;
+        }
+        finally {
+            active.delete(value);
+        }
+    };
+    const visited = visit(input ?? {}, 'extensions', 0);
+    const value = visited && typeof visited === 'object' && !Array.isArray(visited)
+        ? visited
+        : { value: visited };
+    return {
+        value,
+        sensitivity: classes.size ? 'sensitive' : 'none',
+        classes: [...classes].sort(),
+        decisions,
+    };
+}
+export function redactSessionText(input) {
+    const classes = new Set();
+    let text = input;
+    for (const [classification, pattern] of SECRET_PATTERNS) {
+        text = text.replace(pattern, () => {
+            classes.add(classification);
+            return `[REDACTED:${classification}]`;
+        });
+    }
+    return { text, sensitivity: classes.size ? 'sensitive' : 'none', classes: [...classes].sort() };
+}
+export function contentFreeAuditEvent(event) {
+    return Object.freeze({ ...event, counts: { ...event.counts } });
+}
+export function requireNetworkConsent(operation, authorizedOperation) {
+    if (authorizedOperation !== operation) {
+        throw new SessionContractError('NETWORK_NOT_AUTHORIZED', `network operation requires explicit consent: ${operation}`);
+    }
+}
+/** Apply authorization before a search implementation computes rank or snippets. */
+export function prefilterAuthorizedSearchScope(records, scope) {
+    const providers = scope.providers ? new Set(scope.providers) : null;
+    return records.filter((record) => record.workspaceId === scope.workspaceId
+        && (providers === null || providers.has(record.provider)));
+}
+//# sourceMappingURL=policy.js.map

package/dist/src/sessions/ports.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ports.js.map