vouchington-tooling 0.23.0 → 0.24.0

package/dist/agent-blackboard/feedback-fields.mjs

@@ -0,0 +1,38 @@
+import { isWellFormedUnicode } from '../session-friction/text.mjs';
+export function validateFeedbackText(value, label, maximum) {
+    if (typeof value !== 'string' ||
+        !value.trim() ||
+        Buffer.byteLength(value) > maximum ||
+        !isWellFormedUnicode(value) ||
+        // oxlint-disable-next-line no-control-regex -- reject controls at the durable boundary
+        /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(value))
+        throw new Error(`${label} must be bounded non-empty Unicode text`);
+}
+export function normalizeRepositories(value, required = true) {
+    if (value === undefined && !required)
+        return [];
+    if (!Array.isArray(value) || value.length > 32 || (required && value.length === 0))
+        throw new Error('repositories must be a non-empty array of owner/name strings');
+    return [
+        ...new Set(value.map((candidate) => {
+            if (typeof candidate !== 'string' || candidate.length > 160)
+                throw new Error('repositories must be a non-empty array of owner/name strings');
+            const repository = candidate.trim().toLowerCase();
+            if (!/^[a-z0-9-]+\/[a-z0-9._-]+$/.test(repository))
+                throw new Error('invalid repository attribution');
+            return repository;
+        })),
+    ].sort();
+}
+export function validateFeedbackReferences(value, label) {
+    if (!Array.isArray(value) || value.length > 64)
+        throw new Error(`${label} must be a bounded reference array`);
+    for (const reference of value) {
+        if (typeof reference === 'number') {
+            if (!Number.isSafeInteger(reference) || reference <= 0)
+                throw new Error(`${label} numbers must be positive integers`);
+        }
+        else
+            validateFeedbackText(reference, label, 256);
+    }
+}

package/dist/agent-blackboard/feedback-identity.d.mts

@@ -0,0 +1,2 @@
+import type { FeedbackIdentity } from './feedback-types.mts';
+export declare function validateFeedbackIdentity(identity: unknown): asserts identity is FeedbackIdentity;

package/dist/agent-blackboard/feedback-identity.mjs

@@ -0,0 +1,29 @@
+import { isWellFormedUnicode } from '../session-friction/text.mjs';
+import { assertSessionId } from './session-id.mjs';
+import { isObject } from './snapshot-partition-guards.mjs';
+export function validateFeedbackIdentity(identity) {
+    if (!isObject(identity) || typeof identity.sessionId !== 'string')
+        throw new Error('explicit feedback identity is required');
+    assertSessionId(identity.sessionId);
+    if (identity.sessionId.length > 256)
+        throw new Error('session identity is too long');
+    if (identity.parentSessionId !== null) {
+        if (typeof identity.parentSessionId !== 'string')
+            throw new Error('explicit parent identity is required');
+        assertSessionId(identity.parentSessionId, 'parent session id');
+        if (identity.parentSessionId.length > 256)
+            throw new Error('parent session identity is too long');
+    }
+    if (identity.parentSessionId === identity.sessionId)
+        throw new Error('a session cannot parent itself');
+    for (const key of ['agent', 'version'])
+        if (typeof identity[key] !== 'string' ||
+            !identity[key].trim() ||
+            identity[key].length > 128 ||
+            !isWellFormedUnicode(identity[key]) ||
+            // oxlint-disable-next-line no-control-regex -- reject control characters at the durable boundary
+            /[\x00-\x1f\x7f]/.test(identity[key]))
+            throw new Error(`explicit ${key} is required`);
+    if (Object.keys(identity).some((key) => !['sessionId', 'parentSessionId', 'agent', 'version'].includes(key)))
+        throw new Error('unsupported identity field');
+}

package/dist/agent-blackboard/feedback-online-error.d.mts

@@ -0,0 +1,7 @@
+import type { FeedbackDiagnostic } from './feedback-types.mts';
+export declare class FeedbackDeliveryError extends Error {
+    readonly status = "blocked";
+    readonly diagnostic: FeedbackDiagnostic;
+    constructor(diagnostic: FeedbackDiagnostic);
+}
+export declare function feedbackDiagnostic(error: unknown): FeedbackDiagnostic;

package/dist/agent-blackboard/feedback-online-error.mjs

@@ -0,0 +1,23 @@
+import { isObject } from './snapshot-partition-guards.mjs';
+export class FeedbackDeliveryError extends Error {
+    status = 'blocked';
+    diagnostic;
+    constructor(diagnostic) {
+        super(`Blackboard feedback blocked: ${diagnostic}`);
+        this.name = 'FeedbackDeliveryError';
+        this.diagnostic = diagnostic;
+    }
+}
+export function feedbackDiagnostic(error) {
+    if (error instanceof FeedbackDeliveryError)
+        return error.diagnostic;
+    if (isObject(error) &&
+        (error.status === 401 ||
+            error.status === 403 ||
+            error.statusCode === 401 ||
+            error.statusCode === 403))
+        return 'authentication-rejected';
+    if (isObject(error) && (error.status === 409 || error.statusCode === 409))
+        return 'identity-conflict';
+    return 'blackboard-unavailable';
+}

package/dist/agent-blackboard/feedback-online.d.mts

@@ -0,0 +1,2 @@
+import type { FeedbackOnlineOptions, FeedbackReceipt } from './feedback-types.mts';
+export declare function deliverFeedbackOnline(input: FeedbackOnlineOptions, fresh?: boolean): Promise<FeedbackReceipt>;

package/dist/agent-blackboard/feedback-online.mjs

@@ -0,0 +1,137 @@
+import { feedbackDeadline } from './feedback-deadline.mjs';
+import { FeedbackDeliveryError, feedbackDiagnostic } from './feedback-online-error.mjs';
+import { canonicalFeedback } from './feedback-canonical.mjs';
+import { loadClient, resolveBlackboardConnection } from './client.mjs';
+import { normalizeRepositories, validateFeedbackEnvelope } from './feedback-codec.mjs';
+import { validateFeedbackIdentity } from './feedback-identity.mjs';
+import { isObject } from './snapshot-partition-guards.mjs';
+async function ensureSession(sessions, identity) {
+    try {
+        return await sessions.ensure({
+            id: identity.sessionId,
+            parentSessionId: identity.parentSessionId,
+            agent: identity.agent,
+            version: identity.version,
+        });
+    }
+    catch (error) {
+        let existing;
+        try {
+            existing = await sessions.get(identity.sessionId);
+        }
+        catch {
+            throw error;
+        }
+        if (isObject(existing) &&
+            existing.id === identity.sessionId &&
+            ['parentSessionId', 'agent', 'version'].some((field) => (existing[field] ?? null) !== identity[field]))
+            throw new FeedbackDeliveryError('identity-conflict');
+        throw error;
+    }
+}
+async function findEvent(entries, envelope, expectedCreatedAt) {
+    let count = 0;
+    let inspectedBytes = 0;
+    let found;
+    let matching = 0;
+    for await (const entry of entries) {
+        inspectedBytes += Buffer.byteLength(JSON.stringify(entry));
+        if (++count > 10_000 || inspectedBytes > 2_000_000)
+            throw new FeedbackDeliveryError('readback-unconfirmed');
+        if (!isObject(entry) ||
+            !isObject(entry.data) ||
+            entry.data.sourceEventId !== envelope.sourceEventId)
+            continue;
+        try {
+            validateFeedbackEnvelope(entry.data);
+        }
+        catch {
+            throw new FeedbackDeliveryError('event-conflict');
+        }
+        if (canonicalFeedback(entry.data) !== canonicalFeedback(envelope) ||
+            typeof entry.createdAt !== 'string')
+            throw new FeedbackDeliveryError('event-conflict');
+        if (++matching > 1 && expectedCreatedAt !== undefined)
+            throw new FeedbackDeliveryError('event-conflict');
+        if (expectedCreatedAt === undefined || entry.createdAt === expectedCreatedAt)
+            found = { createdAt: entry.createdAt };
+    }
+    return found;
+}
+export async function deliverFeedbackOnline(input, fresh = false) {
+    validateFeedbackIdentity(input.identity);
+    validateFeedbackEnvelope(input.envelope);
+    return feedbackDeadline(async () => {
+        try {
+            let connection;
+            try {
+                connection = resolveBlackboardConnection(input.env);
+                const url = new URL(connection.baseUrl);
+                if (url.username ||
+                    url.password ||
+                    (url.protocol !== 'https:' &&
+                        !(url.protocol === 'http:' && ['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname))))
+                    throw new Error('invalid connection URL');
+            }
+            catch {
+                throw new FeedbackDeliveryError('configuration-invalid');
+            }
+            let client;
+            try {
+                client = await loadClient(input.dependencies);
+            }
+            catch {
+                throw new FeedbackDeliveryError('client-unavailable');
+            }
+            const { Sessions, Entries } = client;
+            const sessions = new Sessions(connection);
+            const entries = new Entries(connection);
+            const ensured = await ensureSession(sessions, input.identity);
+            if (ensured.session.archivedAt != null)
+                throw new FeedbackDeliveryError('archived-session');
+            const existing = await findEvent(entries.get({ sessionId: input.identity.sessionId, format: 'jsonl' }), input.envelope);
+            if (existing && fresh)
+                throw new FeedbackDeliveryError('event-conflict');
+            const merged = [
+                ...new Set([
+                    ...normalizeRepositories(ensured.session.data.repositories, false),
+                    ...input.envelope.repositories,
+                ]),
+            ].sort();
+            if (JSON.stringify(ensured.session.data.repositories) !== JSON.stringify(merged))
+                await sessions.patch({
+                    sessionId: input.identity.sessionId,
+                    data: { repositories: merged },
+                });
+            if (existing)
+                return {
+                    sessionId: input.identity.sessionId,
+                    sourceEventId: input.envelope.sourceEventId,
+                    createdAt: existing.createdAt,
+                    verified: true,
+                };
+            const appended = await entries.append({
+                sessionId: input.identity.sessionId,
+                data: input.envelope,
+            });
+            if (fresh &&
+                (!isObject(appended) ||
+                    typeof appended.createdAt !== 'string' ||
+                    !isObject(appended.data) ||
+                    canonicalFeedback(appended.data) !== canonicalFeedback(input.envelope)))
+                throw new FeedbackDeliveryError('readback-unconfirmed');
+            const confirmed = await findEvent(entries.get({ sessionId: input.identity.sessionId, format: 'jsonl' }), input.envelope, fresh ? appended.createdAt : undefined);
+            if (!confirmed)
+                throw new FeedbackDeliveryError('readback-unconfirmed');
+            return {
+                sessionId: input.identity.sessionId,
+                sourceEventId: input.envelope.sourceEventId,
+                createdAt: confirmed.createdAt,
+                verified: true,
+            };
+        }
+        catch (error) {
+            throw new FeedbackDeliveryError(feedbackDiagnostic(error));
+        }
+    }, input.timeoutMs);
+}

package/dist/agent-blackboard/feedback-outbox.d.mts

@@ -0,0 +1,8 @@
+import type { FeedbackOutboxRecord, FeedbackOutboxStatus } from './feedback-types.mts';
+export declare function feedbackOutboxStatus(directory: string): FeedbackOutboxStatus;
+export declare function listFeedbackOutbox(directory: string): FeedbackOutboxRecord[];
+export declare function persistFeedbackOutbox(directory: string, record: FeedbackOutboxRecord): number;
+export declare function removeFeedbackOutbox(directory: string, record: FeedbackOutboxRecord): {
+    pendingCount: number;
+    cleanupDiagnostic?: 'outbox-cleanup-failed';
+};

package/dist/agent-blackboard/feedback-outbox.mjs

@@ -0,0 +1,157 @@
+import { canonicalFeedback } from './feedback-canonical.mjs';
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, constants, fsyncSync, fstatSync, openSync, readdirSync, renameSync, unlinkSync, } from 'node:fs';
+import { isAbsolute, join, resolve } from 'node:path';
+import { ensurePrivateDirectory } from '../session-friction/directory.mjs';
+import { withFileLock } from '../session-friction/lock.mjs';
+import { openLogFile, readLogContent, writeAll } from '../session-friction/log-file.mjs';
+import { validateFeedbackEnvelope } from './feedback-codec.mjs';
+import { validateFeedbackIdentity } from './feedback-identity.mjs';
+import { isObject } from './snapshot-partition-guards.mjs';
+const FEEDBACK_OUTBOX_MAX_RECORDS = 128;
+const FEEDBACK_OUTBOX_MAX_BYTES = 2_000_000;
+const RECORD_MAX_BYTES = 18_000;
+function outboxDirectory(directory, create) {
+    if (typeof directory !== 'string' || directory.length > 4096 || !isAbsolute(directory))
+        throw new Error('feedback outbox requires an absolute private directory');
+    const path = resolve(directory);
+    ensurePrivateDirectory(path, create);
+    return path;
+}
+function filename(record) {
+    return `${createHash('sha256')
+        .update(JSON.stringify([record.identity.sessionId, record.envelope.sourceEventId]))
+        .digest('hex')}.json`;
+}
+function readRecord(path) {
+    const descriptor = openLogFile(path, constants.O_RDONLY);
+    try {
+        const status = fstatSync(descriptor);
+        if ((status.mode & 0o777) !== 0o600 || status.uid !== process.geteuid?.())
+            throw new Error('feedback outbox record must be private and owned by caller');
+        const bytes = status.size;
+        if (bytes > RECORD_MAX_BYTES)
+            throw new Error('feedback outbox record is too large');
+        const value = JSON.parse(readLogContent(descriptor, RECORD_MAX_BYTES));
+        if (!isObject(value) ||
+            Object.keys(value).some((key) => !['identity', 'envelope'].includes(key)))
+            throw new Error('invalid feedback outbox record');
+        validateFeedbackIdentity(value.identity);
+        validateFeedbackEnvelope(value.envelope);
+        return { record: { identity: value.identity, envelope: value.envelope }, bytes };
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function records(directory) {
+    const paths = readdirSync(directory).filter((name) => name !== '.records.lock' && name !== '.records.lock.reap');
+    if (paths.length > FEEDBACK_OUTBOX_MAX_RECORDS)
+        throw new Error('feedback outbox capacity exceeded; unsent records retained');
+    const result = paths.sort().map((name) => {
+        if (!/^[a-f0-9]{64}\.json$/.test(name))
+            throw new Error('feedback outbox contains an unresolved persistence file');
+        const path = join(directory, name);
+        const loaded = readRecord(path);
+        if (filename(loaded.record) !== name)
+            throw new Error('feedback outbox record identity does not match its path');
+        return { ...loaded, path };
+    });
+    if (result.reduce((sum, item) => sum + item.bytes, 0) > FEEDBACK_OUTBOX_MAX_BYTES)
+        throw new Error('feedback outbox byte capacity exceeded; unsent records retained');
+    return result;
+}
+function syncDirectory(directory) {
+    const descriptor = openSync(directory, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        fsyncSync(descriptor);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+export function feedbackOutboxStatus(directory) {
+    const path = outboxDirectory(directory, false);
+    if (!ensurePrivateDirectory(path, false))
+        return { status: 'empty', pendingCount: 0 };
+    return withFileLock(join(path, '.records'), () => {
+        const pendingCount = records(path).length;
+        return { status: pendingCount ? 'pending' : 'empty', pendingCount };
+    });
+}
+export function listFeedbackOutbox(directory) {
+    const path = outboxDirectory(directory, true);
+    return withFileLock(join(path, '.records'), () => records(path).map((item) => item.record));
+}
+export function persistFeedbackOutbox(directory, record) {
+    validateFeedbackIdentity(record.identity);
+    validateFeedbackEnvelope(record.envelope);
+    const path = outboxDirectory(directory, true);
+    return withFileLock(join(path, '.records'), () => {
+        const current = records(path);
+        const name = filename(record);
+        const existing = current.find((item) => item.path === join(path, name));
+        const serialized = JSON.stringify(record);
+        if (existing) {
+            if (canonicalFeedback(existing.record) !== canonicalFeedback(record))
+                throw new Error('feedback source event conflicts with a retained unsent record');
+            return current.length;
+        }
+        const bytes = Buffer.byteLength(serialized);
+        if (bytes > RECORD_MAX_BYTES ||
+            current.length >= FEEDBACK_OUTBOX_MAX_RECORDS ||
+            current.reduce((sum, item) => sum + item.bytes, 0) + bytes > FEEDBACK_OUTBOX_MAX_BYTES)
+            throw new Error('feedback outbox is full; unsent records retained');
+        const temporary = join(path, `.persist-${randomUUID()}`);
+        const descriptor = openSync(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+        try {
+            writeAll(descriptor, serialized);
+            fsyncSync(descriptor);
+        }
+        catch (error) {
+            closeSync(descriptor);
+            try {
+                unlinkSync(temporary);
+            }
+            catch { }
+            throw error;
+        }
+        closeSync(descriptor);
+        try {
+            renameSync(temporary, join(path, name));
+            syncDirectory(path);
+        }
+        catch (error) {
+            try {
+                unlinkSync(temporary);
+            }
+            catch { }
+            throw error;
+        }
+        return current.length + 1;
+    });
+}
+export function removeFeedbackOutbox(directory, record) {
+    const path = outboxDirectory(directory, true);
+    return withFileLock(join(path, '.records'), () => {
+        const current = records(path);
+        const existing = current.find((item) => item.path === join(path, filename(record)));
+        if (!existing)
+            return { pendingCount: current.length };
+        if (canonicalFeedback(existing.record) !== canonicalFeedback(record))
+            throw new Error('feedback outbox changed during delivery');
+        try {
+            unlinkSync(existing.path);
+        }
+        catch {
+            return { pendingCount: current.length, cleanupDiagnostic: 'outbox-cleanup-failed' };
+        }
+        try {
+            syncDirectory(path);
+        }
+        catch {
+            return { pendingCount: current.length - 1, cleanupDiagnostic: 'outbox-cleanup-failed' };
+        }
+        return { pendingCount: current.length - 1 };
+    });
+}

package/dist/agent-blackboard/feedback-types.d.mts

@@ -0,0 +1,66 @@
+import type { BlackboardClientDependencies } from './client.mts';
+export type FeedbackMode = 'interactive' | 'autonomous';
+export type WorkOutcome = 'in-progress' | 'success' | 'failure' | 'cancelled' | 'timed-out' | 'no-change' | 'policy-refusal' | 'unknown';
+export type FeedbackCoverage = {
+    status: 'complete' | 'partial' | 'unavailable' | 'not-assessed' | 'not-started';
+    sources: string[];
+    droppedCount: number;
+};
+export type FeedbackReference = string | number;
+export type FeedbackEnvelope = {
+    schemaVersion: 1;
+    type: 'journal' | 'retrospective';
+    sourceEventId: string;
+    timestamp: string;
+    repositories: string[];
+    markdown: string;
+    workOutcome: WorkOutcome;
+    feedbackCoverage: FeedbackCoverage;
+    category?: string;
+    date?: string;
+    issues?: FeedbackReference[];
+    prs?: FeedbackReference[];
+};
+export type FeedbackIdentity = {
+    sessionId: string;
+    parentSessionId: string | null;
+    agent: string;
+    version: string;
+};
+export type FeedbackReceipt = {
+    sessionId: string;
+    sourceEventId: string;
+    createdAt: string;
+    verified: true;
+};
+export type FeedbackDiagnostic = 'blackboard-unavailable' | 'client-unavailable' | 'configuration-invalid' | 'authentication-rejected' | 'identity-conflict' | 'readback-unconfirmed' | 'event-conflict' | 'archived-session' | 'delivery-timeout';
+export type FeedbackDeliveryResult = {
+    status: 'delivered';
+    sourceEventId: string;
+    pendingCount: number;
+    receipt: FeedbackReceipt;
+    cleanupDiagnostic?: 'outbox-cleanup-failed';
+} | {
+    status: 'pending';
+    sourceEventId: string;
+    pendingCount: number;
+    diagnostic: FeedbackDiagnostic;
+};
+export type FeedbackDeliveryOptions = {
+    identity: FeedbackIdentity;
+    envelope: FeedbackEnvelope;
+    mode: FeedbackMode;
+    outboxDirectory?: string;
+    env?: NodeJS.ProcessEnv;
+    dependencies?: BlackboardClientDependencies;
+    timeoutMs?: number;
+};
+export type FeedbackOnlineOptions = Omit<FeedbackDeliveryOptions, 'mode' | 'outboxDirectory'>;
+export type FeedbackOutboxRecord = {
+    identity: FeedbackIdentity;
+    envelope: FeedbackEnvelope;
+};
+export type FeedbackOutboxStatus = {
+    status: 'empty' | 'pending';
+    pendingCount: number;
+};

package/dist/agent-blackboard/feedback-types.mjs

@@ -0,0 +1 @@
+export {};

package/dist/agent-blackboard/index.d.mts

@@ -1,48 +1,25 @@
+import type { FeedbackCoverage, FeedbackDeliveryOptions, FeedbackDeliveryResult, FeedbackIdentity, WorkOutcome } from './feedback-types.mts';
+import { type BlackboardClientDependencies } from './client.mts';
 export { cleanupSnapshotPartitions, partitionSnapshot } from './snapshot.mts';
 export { assertSessionId } from './session-id.mts';
 export type * from './snapshot-types.mts';
-export type BlackboardConnection = {
-    baseUrl: string;
-    token: string;
-    readRetry: Record<string, never>;
-};
-export type BlackboardClientModule = {
-    Sessions: new (connection: BlackboardConnection) => {
-        ensure(input: unknown): Promise<{
-            status: 'created' | 'exists';
-            session: {
-                data: Record<string, unknown>;
-                archivedAt?: string | null;
-            };
-        }>;
-        patch(input: unknown): Promise<unknown>;
-        list(input: unknown): Promise<unknown>;
-        get(id: string): Promise<unknown>;
-    };
-    Entries: new (connection: BlackboardConnection) => {
-        append(input: unknown): Promise<{
-            createdAt: string;
-        }>;
-        get(input: unknown): AsyncIterable<unknown>;
-    };
-};
-type BlackboardClientLoader = () => Promise<BlackboardClientModule>;
-export type BlackboardClientDependencies = {
-    loadClient?: BlackboardClientLoader;
-    resolveFrom?: string | URL;
-};
-export declare function resolveBlackboardConnection(env?: NodeJS.ProcessEnv): BlackboardConnection;
 export declare function probeBlackboard(env?: NodeJS.ProcessEnv, dependencies?: BlackboardClientDependencies): Promise<void>;
-export declare function appendJournal(input: {
-    sessionId: string;
-    agent: string;
-    version: string;
+export declare function appendJournal(input: Omit<FeedbackDeliveryOptions, 'identity' | 'envelope'> & FeedbackIdentity & {
     repositories: string[];
     markdownFile: string;
-    parentSessionId?: string | null;
+    sourceEventId: string;
+    workOutcome: WorkOutcome;
+    feedbackCoverage: FeedbackCoverage;
     timestamp?: string;
-    env?: NodeJS.ProcessEnv;
-    dependencies?: BlackboardClientDependencies;
-}): Promise<string>;
+    category?: string;
+}): Promise<FeedbackDeliveryResult>;
 export declare function readJournal(sessionId: string, env?: NodeJS.ProcessEnv, dependencies?: BlackboardClientDependencies): Promise<unknown[]>;
 export declare function formatJournalEntries(sessionId: string, entries: unknown[]): string;
+export { resolveBlackboardConnection } from './client.mts';
+export type { BlackboardConnection, BlackboardClientModule, BlackboardClientDependencies, } from './client.mts';
+export type * from './feedback-types.mts';
+export { createFeedbackEnvelope, validateFeedbackEnvelope } from './feedback-codec.mts';
+export { writeFeedback, verifyFreshFeedback, flushFeedbackOutbox, FeedbackDeliveryError, } from './feedback-delivery.mts';
+export { feedbackOutboxStatus } from './feedback-outbox.mts';
+export { composeRetrospective } from './feedback-compose.mts';
+export type { RetrospectiveCompositionInput, FeedbackAssessment } from './feedback-compose.mts';