vouchington-tooling 0.24.0 → 0.25.0

package/README.md

@@ -19,8 +19,13 @@ npm install @typescript/typescript6
 npm install vitest
 # optional, only for vouchington-tooling/agent-blackboard and agent-blackboard CLI commands
 npm install agent-blackboard@^0.6.0
+# optional, only for `vouchington mcp` (zod is a peer of the SDK)
+npm install @modelcontextprotocol/sdk zod
 ```
 
+[`vouchington mcp`](docs/mcp-server.md) serves the agent-blackboard journal tools to an agent over
+stdio, with Claude, Codex, and Cursor registration examples.
+
 ## CLI
 
 ```bash
@@ -70,6 +75,7 @@ vouchington agent-blackboard journal append --session-id <uuid> --agent codex --
 vouchington agent-blackboard journal entries --session-id <uuid>
 vouchington agent-blackboard snapshot partition --snapshot <snapshot.jsonl> --checksum <sha256> --counts <counts.json>
 vouchington agent-blackboard snapshot cleanup --snapshot <snapshot.jsonl> --partition-directory <partitions-dir> --receipt <receipt-json>
+vouchington mcp
 vouchington install-playwright-chromium-arm64
 vouchington ghcr-package-retention example%2Fapi
 vouchington harness-admission-lane 4
@@ -578,3 +584,40 @@ aggregate dropped counts below observed friction drops and retains larger caller
 double counting. Generated frontmatter carries validated `work_outcome` and `feedback_coverage`
 for consumers to preserve or reject conflicting explicit overrides; trusted mode stays external.
 Human top-five summaries do not authorize dropping additional durable findings.
+
+The `## CI Failures` and `## Sandbox & Permission Audit` sections come from one optional audit
+source; the two inputs are mutually exclusive and supplying both throws before any collector runs.
+`friction: {directory, journalLoader, ...}` keeps reading the session-friction log together with the
+journal and is unchanged. `journal: {journalLoader}` needs no friction directory or log: both
+sections are assessed from the session's journal entries alone, and the report carries
+`coverage.frictionStatus: 'journal-only'` (in place of `empty` or `events`) so the text states that
+no log was observed. `feedbackCoverage.status: 'complete'` accepts either source. It is rejected
+when neither is supplied (the error names the missing source), and a journal-only audit does not
+count as assessed when the loader reports `not-found` (there is no log to establish that the session
+was observed), throws, or is truncated by the scan bounds.
+
+```ts
+await composeRetrospective({ ...input, journal: { journalLoader } })
+```
+
+`journalLoader` is the session-friction `JournalLoader`; `JournalLoader`, `JournalLoadResult`,
+`JournalEntry`, and `JournalAuditOptions` are exported as types from
+`vouchington-tooling/agent-blackboard`. The `## CI Failures` block grammar and its three status
+lines (`failures observed`, `none observed`, `unavailable (<reason>)`) are the same for both sources.
+Journal-only sandbox and permission entries are journal Markdown entries that hold exactly one
+block, escaped and length-bounded like CI failures, and other entries are ignored:
+
+```markdown
+- `sandbox-escalation` — git push — network write blocked
+  - Outcome: requested | approved | denied | unknown
+  - Evidence: permission prompt shown
+  - Disposition: reran with approval
+- `sandbox-failure` — node test — EPERM writing outside the worktree
+  - Evidence: stderr showed EPERM
+  - Disposition: moved output under TMPDIR
+```
+
+`ambiguous-failure` takes the same shape as `sandbox-failure`. The section reports
+`Status: none observed` or `Status: events observed`, each followed by
+`(journal entries only; no friction log observed)`; a truncated scan reports
+`unavailable (journal scan incomplete)` with the entries read so far.

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

@@ -15,6 +15,7 @@ export type BlackboardClientModule = {
         patch(input: unknown): Promise<unknown>;
         list(input: unknown): Promise<unknown>;
         get(id: string): Promise<unknown>;
+        archive?(sessionId: string): Promise<unknown>;
     };
     Entries: new (connection: BlackboardConnection) => {
         append(input: unknown): Promise<{
@@ -23,6 +24,9 @@ export type BlackboardClientModule = {
         }>;
         get(input: unknown): AsyncIterable<unknown>;
     };
+    Snapshots?: new (connection: BlackboardConnection) => {
+        export(options?: unknown): Promise<unknown>;
+    };
 };
 type BlackboardClientLoader = () => Promise<BlackboardClientModule>;
 export type BlackboardClientDependencies = {
@@ -31,4 +35,5 @@ export type BlackboardClientDependencies = {
 };
 export declare function resolveBlackboardConnection(env?: NodeJS.ProcessEnv): BlackboardConnection;
 export declare function loadClient(dependencies?: BlackboardClientDependencies): Promise<BlackboardClientModule>;
+export declare function isMissingModuleError(error: unknown): boolean;
 export {};

package/dist/agent-blackboard/client.mjs

@@ -34,7 +34,7 @@ async function defaultClientLoader(resolveFrom) {
     const specifier = pathToFileURL(consumerRequire.resolve('agent-blackboard')).href;
     return (await import(__rewriteRelativeImportExtension(specifier)));
 }
-function isMissingModuleError(error) {
+export function isMissingModuleError(error) {
     return (error instanceof Error &&
         'code' in error &&
         (error.code === 'ERR_MODULE_NOT_FOUND' || error.code === 'MODULE_NOT_FOUND'));

package/dist/agent-blackboard/feedback-audit-source.d.mts

@@ -0,0 +1,13 @@
+import { type SessionFrictionReport, type SessionFrictionReportOptions } from '../session-friction/index.mts';
+import { type JournalAuditOptions, type JournalAuditReport } from './feedback-journal-audit.mts';
+export type AuditSourceInput = {
+    friction?: SessionFrictionReportOptions;
+    journal?: JournalAuditOptions;
+};
+export type AuditReport = SessionFrictionReport | JournalAuditReport;
+export declare function assertSingleAuditSource(input: AuditSourceInput): void;
+/** Builds the CI-failure and sandbox sections from the friction log or from journal entries alone. */
+export declare function buildAuditReport(sessionId: string, input: AuditSourceInput): Promise<AuditReport>;
+/** Only a real log status or an explicit journal-only scan counts as assessed. */
+export declare function auditAssessed({ coverage }: AuditReport): boolean;
+export declare function completeCoverageError(input: AuditSourceInput): Error;

package/dist/agent-blackboard/feedback-audit-source.mjs

@@ -0,0 +1,30 @@
+import { buildSessionFrictionReport, } from '../session-friction/index.mjs';
+import { buildJournalAuditReport, } from './feedback-journal-audit.mjs';
+const ASSESSED_SOURCE_ERROR = 'complete feedback coverage requires assessed available factual and finding sources';
+const NOT_ASSESSED_MARKDOWN = '## CI Failures\nStatus: unavailable (not assessed)\n\n## Sandbox & Permission Audit\nStatus: unavailable (not assessed)';
+export function assertSingleAuditSource(input) {
+    if (input.friction && input.journal)
+        throw new Error('composition accepts either a friction or a journal audit source, not both');
+}
+/** Builds the CI-failure and sandbox sections from the friction log or from journal entries alone. */
+export async function buildAuditReport(sessionId, input) {
+    if (input.friction)
+        return buildSessionFrictionReport(sessionId, input.friction);
+    if (input.journal)
+        return buildJournalAuditReport(sessionId, input.journal);
+    return {
+        coverage: { journalStatus: 'unavailable', frictionStatus: 'absent', truncated: false },
+        markdown: NOT_ASSESSED_MARKDOWN,
+    };
+}
+/** Only a real log status or an explicit journal-only scan counts as assessed. */
+export function auditAssessed({ coverage }) {
+    return (coverage.journalStatus === 'complete' &&
+        ['empty', 'events', 'journal-only'].includes(coverage.frictionStatus) &&
+        !coverage.truncated);
+}
+export function completeCoverageError(input) {
+    return new Error(input.friction || input.journal
+        ? ASSESSED_SOURCE_ERROR
+        : `${ASSESSED_SOURCE_ERROR} (no friction or journal source supplied for CI failures and sandbox audit)`);
+}

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

@@ -1,6 +1,7 @@
 import { type RetrospectiveFactsOptions } from '../retrospective-facts/index.mts';
 import { type ResolveOptions } from '../retrospective-transcript/index.mts';
-import { type SessionFrictionReportOptions } from '../session-friction/index.mts';
+import type { SessionFrictionReportOptions } from '../session-friction/index.mts';
+import type { JournalAuditOptions } from './feedback-journal-audit.mts';
 import type { FeedbackCoverage, FeedbackReference, WorkOutcome } from './feedback-types.mts';
 export type FeedbackAssessment = {
     status: 'findings' | 'none-observed' | 'not-assessed' | 'unavailable';
@@ -28,7 +29,10 @@ export type RetrospectiveCompositionInput = {
     narrative: string;
     facts: Omit<RetrospectiveFactsOptions, 'raw'> | Unassessed;
     transcript: ResolveOptions | Unassessed;
+    /** CI failures and sandbox audit from a friction log plus journal. Exclusive with `journal`. */
     friction?: SessionFrictionReportOptions;
+    /** CI failures and sandbox audit from journal entries alone (`frictionStatus: 'journal-only'`). */
+    journal?: JournalAuditOptions;
     tools: FeedbackAssessment;
     architecture: FeedbackAssessment;
     knownSensitiveValues?: string[];

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

@@ -1,6 +1,6 @@
 import { runRetrospectiveFactsReport, } from '../retrospective-facts/index.mjs';
 import { runRetrospectiveTranscriptReport, } from '../retrospective-transcript/index.mjs';
-import { buildSessionFrictionReport, } from '../session-friction/index.mjs';
+import { assertSingleAuditSource, auditAssessed, buildAuditReport, completeCoverageError, } from './feedback-audit-source.mjs';
 import { createFeedbackEnvelope, redactFeedbackText } from './feedback-codec.mjs';
 import { validateFeedbackText } from './feedback-fields.mjs';
 function assessment(title, value) {
@@ -32,6 +32,7 @@ function unavailable(marker, input) {
     return `${marker}\nStatus: ${input.status.replaceAll('-', ' ')} (${input.reason})`;
 }
 export async function composeRetrospective(input) {
+    assertSingleAuditSource(input);
     const unavailableFacts = 'status' in input.facts
         ? {
             markdown: unavailable('=== Retrospective Facts ===', input.facts),
@@ -44,34 +45,23 @@ export async function composeRetrospective(input) {
             coverage: input.transcript.status,
         }
         : undefined;
-    const [facts, transcript, friction] = await Promise.all([
+    const [facts, transcript, audit] = await Promise.all([
         'status' in input.facts
             ? Promise.resolve(unavailableFacts)
             : runRetrospectiveFactsReport({ ...input.facts, raw: false }),
         'status' in input.transcript
             ? Promise.resolve(unavailableTranscript)
             : runRetrospectiveTranscriptReport(input.transcript),
-        input.friction
-            ? buildSessionFrictionReport(input.sessionId, input.friction)
-            : Promise.resolve({
-                coverage: {
-                    journalStatus: 'unavailable',
-                    frictionStatus: 'absent',
-                    truncated: false,
-                },
-                markdown: '## CI Failures\nStatus: unavailable (not assessed)\n\n## Sandbox & Permission Audit\nStatus: unavailable (not assessed)',
-            }),
+        buildAuditReport(input.sessionId, input),
     ]);
     if (input.feedbackCoverage.status === 'complete' &&
         (facts.coverage !== 'complete' ||
             transcript.coverage !== 'complete' ||
             ['not-assessed', 'unavailable'].includes(input.tools.status) ||
             ['not-assessed', 'unavailable'].includes(input.architecture.status) ||
-            friction.coverage.journalStatus !== 'complete' ||
-            !['empty', 'events'].includes(friction.coverage.frictionStatus) ||
-            friction.coverage.truncated))
-        throw new Error('complete feedback coverage requires assessed available factual and finding sources');
-    if ((friction.coverage.droppedCount ?? 0) > input.feedbackCoverage.droppedCount)
+            !auditAssessed(audit)))
+        throw completeCoverageError(input);
+    if ((audit.coverage.droppedCount ?? 0) > input.feedbackCoverage.droppedCount)
         throw new Error('feedback coverage dropped count must include observed friction drops');
     const markdown = [
         '---',
@@ -88,7 +78,7 @@ export async function composeRetrospective(input) {
         `## Outcome\nWork outcome: ${input.workOutcome}\nFeedback coverage: ${input.feedbackCoverage.status}\nDropped records: ${input.feedbackCoverage.droppedCount}`,
         `## Verifiable Facts\n${facts.markdown.trim()}`,
         `## Transcript Facts\n${transcript.markdown.trim()}`,
-        friction.markdown,
+        audit.markdown,
         assessment('Tool Findings', input.tools),
         assessment('Architecture Findings', input.architecture),
     ].join('\n\n');

package/dist/agent-blackboard/feedback-journal-audit.d.mts

@@ -0,0 +1,20 @@
+import type { JournalLoader, SessionFrictionCoverage } from '../session-friction/types.mts';
+export type JournalAuditOptions = {
+    journalLoader: JournalLoader;
+};
+/** `journal-only` says both sections were assessed from journal entries, with no log observed. */
+export type JournalAuditReport = {
+    coverage: {
+        journalStatus: SessionFrictionCoverage['journalStatus'];
+        frictionStatus: 'journal-only';
+        truncated: false;
+        droppedCount?: never;
+    };
+    markdown: string;
+};
+/**
+ * Builds `## CI Failures` and `## Sandbox & Permission Audit` from the session's journal entries
+ * alone. Unlike `buildSessionFrictionReport`, a session with no journal is unavailable rather than
+ * empty: without a log, nothing else establishes that the session was observed.
+ */
+export declare function buildJournalAuditReport(sessionId: string, options: JournalAuditOptions): Promise<JournalAuditReport>;

package/dist/agent-blackboard/feedback-journal-audit.mjs

@@ -0,0 +1,29 @@
+import { buildCiFailuresSection, getConformingGroups, incompleteCiSection, } from '../session-friction/ci-failures.mjs';
+import { scanJournal } from '../session-friction/journal.mjs';
+import { validateSessionId } from '../session-friction/session-id.mjs';
+import { getConformingSandboxBlocks, journalSandboxSection, unavailableSandboxSection, } from './feedback-journal-sandbox.mjs';
+function report(journalStatus, markdown) {
+    return { coverage: { journalStatus, frictionStatus: 'journal-only', truncated: false }, markdown };
+}
+function unavailable(reason) {
+    return report('unavailable', `## CI Failures\nStatus: unavailable (${reason})\n\n${unavailableSandboxSection(reason)}`);
+}
+/**
+ * Builds `## CI Failures` and `## Sandbox & Permission Audit` from the session's journal entries
+ * alone. Unlike `buildSessionFrictionReport`, a session with no journal is unavailable rather than
+ * empty: without a log, nothing else establishes that the session was observed.
+ */
+export async function buildJournalAuditReport(sessionId, options) {
+    validateSessionId(sessionId);
+    const scanned = await scanJournal(sessionId, options.journalLoader);
+    if (scanned.status === 'unreachable')
+        return unavailable('blackboard unreachable');
+    if (scanned.status === 'not-found')
+        return unavailable('no journal for session');
+    const ci = getConformingGroups(scanned.entries);
+    const sandbox = getConformingSandboxBlocks(scanned.entries);
+    if (scanned.truncated)
+        return report('partial', `${incompleteCiSection(ci)}\n\n${unavailableSandboxSection('journal scan incomplete', sandbox)}`);
+    const journal = { status: 'ok', markdownBlocks: ci, truncated: false };
+    return report('complete', `${buildCiFailuresSection(sessionId, journal, 'journal-only')}\n\n${journalSandboxSection(sandbox)}`);
+}

package/dist/agent-blackboard/feedback-journal-sandbox.d.mts

@@ -0,0 +1,5 @@
+import type { JournalEntry } from '../session-friction/types.mts';
+/** Journal entries that hold exactly one sandbox or permission block, made paste-safe. */
+export declare function getConformingSandboxBlocks(entries: Iterable<JournalEntry>): string[];
+export declare function unavailableSandboxSection(reason: string, blocks?: string[]): string;
+export declare function journalSandboxSection(blocks: string[]): string;

package/dist/agent-blackboard/feedback-journal-sandbox.mjs

@@ -0,0 +1,40 @@
+import { conformingBlocks, matchAuditBlock } from '../session-friction/audit-block.mjs';
+const SANDBOX_SECTION_HEADER = '## Sandbox & Permission Audit';
+const SOURCE = 'journal entries only; no friction log observed';
+const EVIDENCE = /^ {2}- Evidence: .*[^\s]$/;
+const DISPOSITION = /^ {2}- Disposition: .*[^\s]$/;
+const ESCALATION = [
+    /^- `sandbox-escalation` — .+ — .*[^\s]$/,
+    /^ {2}- Outcome: (?:requested|approved|denied|unknown)$/,
+    EVIDENCE,
+    DISPOSITION,
+];
+const FAILURE = [
+    /^- `(?:sandbox-failure|ambiguous-failure)` — .+ — .*[^\s]$/,
+    EVIDENCE,
+    DISPOSITION,
+];
+const FIELD_PREFIXES = [
+    '- `sandbox-escalation` — ',
+    '- `sandbox-failure` — ',
+    '- `ambiguous-failure` — ',
+    '  - Outcome: ',
+    '  - Evidence: ',
+    '  - Disposition: ',
+];
+function matchBlock(markdown) {
+    return (matchAuditBlock(markdown, ESCALATION, FIELD_PREFIXES) ??
+        matchAuditBlock(markdown, FAILURE, FIELD_PREFIXES));
+}
+/** Journal entries that hold exactly one sandbox or permission block, made paste-safe. */
+export function getConformingSandboxBlocks(entries) {
+    return conformingBlocks(entries, matchBlock);
+}
+export function unavailableSandboxSection(reason, blocks = []) {
+    return [`${SANDBOX_SECTION_HEADER}\nStatus: unavailable (${reason})`, ...blocks].join('\n\n');
+}
+export function journalSandboxSection(blocks) {
+    if (blocks.length === 0)
+        return `${SANDBOX_SECTION_HEADER}\nStatus: none observed (${SOURCE})`;
+    return `${SANDBOX_SECTION_HEADER}\nStatus: events observed (${SOURCE})\n\n${blocks.join('\n\n')}`;
+}

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

@@ -1,17 +1,16 @@
-import type { FeedbackCoverage, FeedbackDeliveryOptions, FeedbackDeliveryResult, FeedbackIdentity, WorkOutcome } from './feedback-types.mts';
+import type { FeedbackDeliveryResult } from './feedback-types.mts';
+import { type JournalInput } from './journal.mts';
 import { type BlackboardClientDependencies } from './client.mts';
 export { cleanupSnapshotPartitions, partitionSnapshot } from './snapshot.mts';
 export { assertSessionId } from './session-id.mts';
+export { appendJournalMarkdown } from './journal.mts';
+export type { JournalInput } from './journal.mts';
+export { archiveBlackboardSession, ensureBlackboardSession, exportSnapshot, } from './session-tools.mts';
+export type { EnsureSessionOutcome, SnapshotExportOutcome } from './session-tools.mts';
 export type * from './snapshot-types.mts';
 export declare function probeBlackboard(env?: NodeJS.ProcessEnv, dependencies?: BlackboardClientDependencies): Promise<void>;
-export declare function appendJournal(input: Omit<FeedbackDeliveryOptions, 'identity' | 'envelope'> & FeedbackIdentity & {
-    repositories: string[];
+export declare function appendJournal(input: JournalInput & {
     markdownFile: string;
-    sourceEventId: string;
-    workOutcome: WorkOutcome;
-    feedbackCoverage: FeedbackCoverage;
-    timestamp?: 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;
@@ -23,3 +22,5 @@ export { writeFeedback, verifyFreshFeedback, flushFeedbackOutbox, FeedbackDelive
 export { feedbackOutboxStatus } from './feedback-outbox.mts';
 export { composeRetrospective } from './feedback-compose.mts';
 export type { RetrospectiveCompositionInput, FeedbackAssessment } from './feedback-compose.mts';
+export type { JournalAuditOptions } from './feedback-journal-audit.mts';
+export type { JournalEntry, JournalLoader, JournalLoadResult } from '../session-friction/types.mts';

package/dist/agent-blackboard/index.mjs

@@ -1,55 +1,28 @@
-import { createFeedbackEnvelope, normalizeRepositories } from './feedback-codec.mjs';
-import { writeFeedback } from './feedback-delivery.mjs';
+import { appendJournalMarkdown, checkJournalInput } from './journal.mjs';
 import { loadClient, resolveBlackboardConnection, } from './client.mjs';
 import { readFile } from 'node:fs/promises';
 import { assertSessionId } from './session-id.mjs';
 export { cleanupSnapshotPartitions, partitionSnapshot } from './snapshot.mjs';
 export { assertSessionId } from './session-id.mjs';
+export { appendJournalMarkdown } from './journal.mjs';
+export { archiveBlackboardSession, ensureBlackboardSession, exportSnapshot, } from './session-tools.mjs';
 export async function probeBlackboard(env, dependencies) {
     const { Sessions } = await loadClient(dependencies);
     await new Sessions(resolveBlackboardConnection(env)).list({ limit: 1 });
 }
 export async function appendJournal(input) {
-    assertSessionId(input.sessionId);
-    if (input.parentSessionId != null)
-        assertSessionId(input.parentSessionId, 'parent session id');
-    const repositories = normalizeRepositories(input.repositories);
-    const timestamp = input.timestamp === undefined ? new Date() : new Date(input.timestamp);
-    if (Number.isNaN(timestamp.valueOf()))
-        throw new Error('journal timestamp is not a valid date-time');
+    const { markdownFile, ...journal } = input;
+    checkJournalInput(journal);
     let markdown;
     try {
-        markdown = new TextDecoder('utf-8', { fatal: true }).decode(await readFile(input.markdownFile));
+        markdown = new TextDecoder('utf-8', { fatal: true }).decode(await readFile(markdownFile));
     }
     catch {
         throw new Error('note file is not valid UTF-8 or cannot be read');
     }
     if (!markdown)
         throw new Error('note file is empty');
-    return writeFeedback({
-        identity: {
-            sessionId: input.sessionId,
-            parentSessionId: input.parentSessionId,
-            agent: input.agent,
-            version: input.version,
-        },
-        envelope: createFeedbackEnvelope({
-            schemaVersion: 1,
-            type: 'journal',
-            sourceEventId: input.sourceEventId,
-            timestamp: timestamp.toISOString(),
-            repositories,
-            markdown,
-            workOutcome: input.workOutcome,
-            feedbackCoverage: input.feedbackCoverage,
-            ...(input.category === undefined ? {} : { category: input.category }),
-        }),
-        mode: input.mode,
-        ...(input.outboxDirectory === undefined ? {} : { outboxDirectory: input.outboxDirectory }),
-        ...(input.env === undefined ? {} : { env: input.env }),
-        ...(input.dependencies === undefined ? {} : { dependencies: input.dependencies }),
-        ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
-    });
+    return appendJournalMarkdown({ ...journal, markdown });
 }
 export async function readJournal(sessionId, env, dependencies) {
     assertSessionId(sessionId);

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

@@ -0,0 +1,21 @@
+import type { FeedbackCoverage, FeedbackDeliveryOptions, FeedbackDeliveryResult, FeedbackIdentity, WorkOutcome } from './feedback-types.mts';
+export type JournalInput = Omit<FeedbackDeliveryOptions, 'identity' | 'envelope'> & FeedbackIdentity & {
+    repositories: string[];
+    sourceEventId: string;
+    workOutcome: WorkOutcome;
+    feedbackCoverage: FeedbackCoverage;
+    timestamp?: string;
+    category?: string;
+};
+/** Validates the identity, repositories, and timestamp before any note text is read. */
+export declare function checkJournalInput(input: JournalInput): {
+    repositories: string[];
+    timestamp: Date;
+};
+/**
+ * Appends a journal entry whose markdown is already in memory. `appendJournal` reads a note file
+ * and delegates here; callers that hold the text (for example the MCP server) skip the file.
+ */
+export declare function appendJournalMarkdown(input: JournalInput & {
+    markdown: string;
+}): Promise<FeedbackDeliveryResult>;

package/dist/agent-blackboard/journal.mjs

@@ -0,0 +1,45 @@
+import { createFeedbackEnvelope, normalizeRepositories } from './feedback-codec.mjs';
+import { writeFeedback } from './feedback-delivery.mjs';
+import { assertSessionId } from './session-id.mjs';
+/** Validates the identity, repositories, and timestamp before any note text is read. */
+export function checkJournalInput(input) {
+    assertSessionId(input.sessionId);
+    if (input.parentSessionId != null)
+        assertSessionId(input.parentSessionId, 'parent session id');
+    const repositories = normalizeRepositories(input.repositories);
+    const timestamp = input.timestamp === undefined ? new Date() : new Date(input.timestamp);
+    if (Number.isNaN(timestamp.valueOf()))
+        throw new Error('journal timestamp is not a valid date-time');
+    return { repositories, timestamp };
+}
+/**
+ * Appends a journal entry whose markdown is already in memory. `appendJournal` reads a note file
+ * and delegates here; callers that hold the text (for example the MCP server) skip the file.
+ */
+export async function appendJournalMarkdown(input) {
+    const { repositories, timestamp } = checkJournalInput(input);
+    return writeFeedback({
+        identity: {
+            sessionId: input.sessionId,
+            parentSessionId: input.parentSessionId,
+            agent: input.agent,
+            version: input.version,
+        },
+        envelope: createFeedbackEnvelope({
+            schemaVersion: 1,
+            type: 'journal',
+            sourceEventId: input.sourceEventId,
+            timestamp: timestamp.toISOString(),
+            repositories,
+            markdown: input.markdown,
+            workOutcome: input.workOutcome,
+            feedbackCoverage: input.feedbackCoverage,
+            ...(input.category === undefined ? {} : { category: input.category }),
+        }),
+        mode: input.mode,
+        ...(input.outboxDirectory === undefined ? {} : { outboxDirectory: input.outboxDirectory }),
+        ...(input.env === undefined ? {} : { env: input.env }),
+        ...(input.dependencies === undefined ? {} : { dependencies: input.dependencies }),
+        ...(input.timeoutMs === undefined ? {} : { timeoutMs: input.timeoutMs }),
+    });
+}

package/dist/agent-blackboard/session-tools.d.mts

@@ -0,0 +1,36 @@
+import { type BlackboardClientDependencies } from './client.mts';
+import type { FeedbackIdentity } from './feedback-types.mts';
+import type { SnapshotChecksum, SnapshotCounts, SnapshotManifest, SnapshotSelection } from './snapshot-types.mts';
+type ClientOptions = {
+    env?: NodeJS.ProcessEnv;
+    dependencies?: BlackboardClientDependencies;
+};
+export type EnsureSessionOutcome = {
+    sessionId: string;
+    status: 'created' | 'exists';
+    archived: boolean;
+};
+export type SnapshotExportOutcome = {
+    path: string;
+    counts: SnapshotCounts;
+    checksum: SnapshotChecksum;
+    manifest: SnapshotManifest;
+    cleanupToken?: string;
+};
+/** Idempotently creates the session; an existing session must match the supplied identity. */
+export declare function ensureBlackboardSession(input: FeedbackIdentity & ClientOptions): Promise<EnsureSessionOutcome>;
+/** Marks a session distilled. Metadata becomes immutable; entries stay appendable. */
+export declare function archiveBlackboardSession(input: {
+    sessionId: string;
+} & ClientOptions): Promise<{
+    sessionId: string;
+    archived: true;
+}>;
+/**
+ * Exports a snapshot into a private file the client generates. Callers cannot choose the
+ * destination, so a long-lived process with credentials never writes to an agent-chosen path.
+ */
+export declare function exportSnapshot(input: {
+    selection?: SnapshotSelection;
+} & ClientOptions): Promise<SnapshotExportOutcome>;
+export {};

package/dist/agent-blackboard/session-tools.mjs

@@ -0,0 +1,41 @@
+import { loadClient, resolveBlackboardConnection, } from './client.mjs';
+import { validateFeedbackIdentity } from './feedback-identity.mjs';
+import { assertSessionId } from './session-id.mjs';
+import { isObject } from './snapshot-partition-guards.mjs';
+const UPGRADE_HINT = 'upgrade agent-blackboard in the consumer package';
+/** Idempotently creates the session; an existing session must match the supplied identity. */
+export async function ensureBlackboardSession(input) {
+    const { sessionId, parentSessionId, agent, version } = input;
+    validateFeedbackIdentity({ sessionId, parentSessionId, agent, version });
+    const { Sessions } = await loadClient(input.dependencies);
+    const { status, session } = await new Sessions(resolveBlackboardConnection(input.env)).ensure({
+        id: sessionId,
+        parentSessionId,
+        agent,
+        version,
+    });
+    return { sessionId, status, archived: session.archivedAt != null };
+}
+/** Marks a session distilled. Metadata becomes immutable; entries stay appendable. */
+export async function archiveBlackboardSession(input) {
+    assertSessionId(input.sessionId);
+    const { Sessions } = await loadClient(input.dependencies);
+    const sessions = new Sessions(resolveBlackboardConnection(input.env));
+    if (typeof sessions.archive !== 'function')
+        throw new Error(`the installed agent-blackboard client cannot archive sessions; ${UPGRADE_HINT}`);
+    await sessions.archive(input.sessionId);
+    return { sessionId: input.sessionId, archived: true };
+}
+/**
+ * Exports a snapshot into a private file the client generates. Callers cannot choose the
+ * destination, so a long-lived process with credentials never writes to an agent-chosen path.
+ */
+export async function exportSnapshot(input) {
+    const { Snapshots } = await loadClient(input.dependencies);
+    if (!Snapshots)
+        throw new Error(`the installed agent-blackboard client cannot export snapshots; ${UPGRADE_HINT}`);
+    const result = await new Snapshots(resolveBlackboardConnection(input.env)).export(input.selection === undefined ? {} : { selection: input.selection });
+    if (!isObject(result) || typeof result.path !== 'string')
+        throw new Error('agent-blackboard returned an unexpected snapshot export result');
+    return result;
+}

package/dist/cli/commands/mcp.d.mts

@@ -0,0 +1,5 @@
+/**
+ * `vouchington mcp`: serves the agent-blackboard journal tools over stdio. It resolves once the
+ * server is connected; the open stdin keeps the process alive until the client disconnects.
+ */
+export declare function runMcpCommand(args: string[]): Promise<number>;

package/dist/cli/commands/mcp.mjs

@@ -0,0 +1,18 @@
+import { runMcpServer } from '../../mcp-server/run.mjs';
+import { readInstalledVersion } from '../installed-version.mjs';
+/**
+ * `vouchington mcp`: serves the agent-blackboard journal tools over stdio. It resolves once the
+ * server is connected; the open stdin keeps the process alive until the client disconnects.
+ */
+export async function runMcpCommand(args) {
+    try {
+        if (args.length > 0)
+            throw new Error('usage: vouchington mcp (takes no arguments; it serves stdio)');
+        await runMcpServer({ cwd: process.cwd(), env: process.env, version: readInstalledVersion() });
+        return 0;
+    }
+    catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}

package/dist/cli/index.mjs

@@ -1,11 +1,10 @@
 #!/usr/bin/env node
-import { readFileSync, realpathSync } from 'node:fs';
+import { realpathSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { runAgentHarnessConfigCli } from '../agent-harness-config/cli.mjs';
 import { runPostReviewCli } from '../gha-post-review/cli.mjs';
 import { runStageReviewPayloadCli } from '../gha-review-payload/cli.mjs';
-import { readPackageVersion } from '../package-version.mjs';
 import { runSwiftSemanticEqualCli } from '../swift-semantic-equal/cli.mjs';
 import { runGhaArtifactsCleanup } from './commands/gha-artifacts-cleanup.mjs';
 import { runGhaRuntimeAudit } from './commands/gha-runtime-audit.mjs';
@@ -21,11 +20,13 @@ import { runRetrospectiveTranscriptCommand } from './commands/retrospective-tran
 import { runLinkSkill } from './commands/link-skill.mjs';
 import { runRetrospectiveFactsCommand } from './commands/retrospective-facts.mjs';
 import { runAgentBlackboardCommand } from './commands/agent-blackboard.mjs';
+import { runMcpCommand } from './commands/mcp.mjs';
 import { runWithHostLock } from './commands/with-host-lock.mjs';
 import { runRequireUpToDate } from './commands/require-up-to-date.mjs';
 import { runAstGrepExamplesCommand } from './commands/ast-grep-examples.mjs';
 import { runAstGrepPackCommand } from './commands/ast-grep-pack.mjs';
 import { runGhaWorkspacePolicy } from './commands/gha-workspace-policy.mjs';
+import { readInstalledVersion } from './installed-version.mjs';
 import { parseCli } from './parse.mjs';
 import { packageScriptPath } from './script-path.mjs';
 import { commandUsage, printUsage } from './usage.mjs';
@@ -129,6 +130,8 @@ export function runCli(argv = process.argv) {
             return runRetrospectiveFactsCommand(parsed.args);
         case 'agent-blackboard':
             return runAgentBlackboardCommand(parsed.args);
+        case 'mcp':
+            return runMcpCommand(parsed.args);
         case 'require-up-to-date':
             return runRequireUpToDate(parsed);
         case 'gitleaks-directory-scan':
@@ -145,9 +148,6 @@ export function runCli(argv = process.argv) {
             return runGhaWorkspacePolicy(parsed);
     }
 }
-function readInstalledVersion() {
-    return readPackageVersion(JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')));
-}
 export function isMainModule(metaUrl, argv1) {
     if (argv1 === undefined)
         return false;

package/dist/cli/installed-version.d.mts

@@ -0,0 +1 @@
+export declare function readInstalledVersion(): string;