vouchington-tooling 3.0.2 → 3.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/agent-blackboard/feedback-delivery.d.mts +11 -4
- package/dist/agent-blackboard/feedback-delivery.mjs +22 -5
- package/dist/agent-blackboard/feedback-failure-parse.d.mts +3 -0
- package/dist/agent-blackboard/feedback-failure-parse.mjs +39 -0
- package/dist/agent-blackboard/feedback-failure.d.mts +32 -0
- package/dist/agent-blackboard/feedback-failure.mjs +48 -0
- package/dist/agent-blackboard/feedback-online-error.d.mts +5 -1
- package/dist/agent-blackboard/feedback-online-error.mjs +8 -1
- package/dist/agent-blackboard/feedback-online.mjs +3 -2
- package/dist/agent-blackboard/feedback-outbox-failure.d.mts +16 -0
- package/dist/agent-blackboard/feedback-outbox-failure.mjs +41 -0
- package/dist/agent-blackboard/feedback-outbox-read.d.mts +11 -0
- package/dist/agent-blackboard/feedback-outbox-read.mjs +33 -0
- package/dist/agent-blackboard/feedback-outbox-rejected.d.mts +14 -5
- package/dist/agent-blackboard/feedback-outbox-rejected.mjs +45 -19
- package/dist/agent-blackboard/feedback-outbox-write.d.mts +2 -0
- package/dist/agent-blackboard/feedback-outbox-write.mjs +26 -0
- package/dist/agent-blackboard/feedback-outbox.d.mts +2 -7
- package/dist/agent-blackboard/feedback-outbox.mjs +7 -52
- package/dist/agent-blackboard/feedback-types.d.mts +1 -1
- package/dist/agent-blackboard/index.d.mts +2 -0
- package/dist/agent-blackboard/index.mjs +2 -0
- package/dist/mcp-server/dispatch.mjs +3 -1
- package/dist/mcp-server/handlers-outbox.d.mts +1 -0
- package/dist/mcp-server/handlers-outbox.mjs +31 -2
- package/dist/mcp-server/tools-outbox.d.mts +2 -0
- package/dist/mcp-server/tools-outbox.mjs +31 -0
- package/dist/mcp-server/tools.mjs +2 -8
- package/docs/mcp-server.md +28 -15
- package/package.json +1 -1
- package/scripts/__pycache__/run_bounded_process.cpython-314.pyc +0 -0
- package/skills/blackboard/SKILL.md +10 -1
- package/skills/manifest.json +9 -9
- package/skills/retrospective-distill/SKILL.md +3 -1
|
@@ -1,10 +1,18 @@
|
|
|
1
1
|
import type { BlackboardClientDependencies } from './client.mts';
|
|
2
|
+
import { type FeedbackCause } from './feedback-failure.mts';
|
|
3
|
+
import { type FeedbackFailureReport } from './feedback-outbox-failure.mts';
|
|
2
4
|
import type { FeedbackDeliveryOptions, FeedbackDeliveryResult, FeedbackDiagnostic, FeedbackOnlineOptions } from './feedback-types.mts';
|
|
3
5
|
export { FeedbackDeliveryError } from './feedback-online-error.mts';
|
|
4
6
|
export declare function writeFeedback(input: FeedbackDeliveryOptions): Promise<FeedbackDeliveryResult>;
|
|
5
7
|
export declare function verifyFreshFeedback(input: FeedbackOnlineOptions): Promise<Extract<FeedbackDeliveryResult, {
|
|
6
8
|
status: 'delivered';
|
|
7
9
|
}>>;
|
|
10
|
+
type FeedbackRejected = {
|
|
11
|
+
sourceEventId: string;
|
|
12
|
+
diagnostic: FeedbackDiagnostic;
|
|
13
|
+
} & FeedbackCause & {
|
|
14
|
+
attempts?: number;
|
|
15
|
+
};
|
|
8
16
|
export declare function flushFeedbackOutbox(input: {
|
|
9
17
|
directory: string;
|
|
10
18
|
env?: NodeJS.ProcessEnv;
|
|
@@ -14,9 +22,8 @@ export declare function flushFeedbackOutbox(input: {
|
|
|
14
22
|
pendingCount: number;
|
|
15
23
|
deliveredCount: number;
|
|
16
24
|
diagnostic?: FeedbackDiagnostic;
|
|
17
|
-
rejected?:
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
}>;
|
|
25
|
+
rejected?: FeedbackRejected[];
|
|
26
|
+
/** Records still pending that failed this flush, with their non-secret cause and attempt count. */
|
|
27
|
+
failures?: FeedbackFailureReport[];
|
|
21
28
|
cleanupDiagnostic?: 'outbox-cleanup-failed';
|
|
22
29
|
}>;
|
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
import { createFeedbackEnvelope, validateFeedbackEnvelope } from "./feedback-codec.mjs";
|
|
2
2
|
import { validateFeedbackIdentity } from "./feedback-identity.mjs";
|
|
3
3
|
import { deliverFeedbackOnline } from "./feedback-online.mjs";
|
|
4
|
-
import { feedbackDiagnostic } from "./feedback-online-error.mjs";
|
|
4
|
+
import { feedbackDiagnostic, feedbackFailure } from "./feedback-online-error.mjs";
|
|
5
|
+
import { isTransientCause } from "./feedback-failure.mjs";
|
|
6
|
+
import { recordFeedbackFailure } from "./feedback-outbox-failure.mjs";
|
|
5
7
|
import { feedbackOutboxStatus, listFeedbackOutbox, persistFeedbackOutbox, removeFeedbackOutbox, } from "./feedback-outbox.mjs";
|
|
6
8
|
import { rejectFeedbackOutbox } from "./feedback-outbox-rejected.mjs";
|
|
7
9
|
export { FeedbackDeliveryError } from "./feedback-online-error.mjs";
|
|
@@ -33,7 +35,10 @@ export async function writeFeedback(input) {
|
|
|
33
35
|
catch (error) {
|
|
34
36
|
const diagnostic = feedbackDiagnostic(error);
|
|
35
37
|
if (PERMANENT.includes(diagnostic)) {
|
|
36
|
-
rejectFeedbackOutbox(input.outboxDirectory, record
|
|
38
|
+
rejectFeedbackOutbox(input.outboxDirectory, record, {
|
|
39
|
+
diagnostic,
|
|
40
|
+
...feedbackFailure(error),
|
|
41
|
+
});
|
|
37
42
|
throw error;
|
|
38
43
|
}
|
|
39
44
|
return {
|
|
@@ -55,6 +60,7 @@ export async function flushFeedbackOutbox(input) {
|
|
|
55
60
|
let diagnostic;
|
|
56
61
|
let cleanupDiagnostic;
|
|
57
62
|
const rejected = [];
|
|
63
|
+
const failures = [];
|
|
58
64
|
for (const record of listFeedbackOutbox(input.directory)) {
|
|
59
65
|
try {
|
|
60
66
|
await deliverFeedbackOnline({
|
|
@@ -68,13 +74,23 @@ export async function flushFeedbackOutbox(input) {
|
|
|
68
74
|
}
|
|
69
75
|
catch (error) {
|
|
70
76
|
const current = feedbackDiagnostic(error);
|
|
77
|
+
const cause = feedbackFailure(error);
|
|
78
|
+
const sourceEventId = record.envelope.sourceEventId;
|
|
71
79
|
if (PERMANENT.includes(current)) {
|
|
72
|
-
rejectFeedbackOutbox(input.directory, record);
|
|
73
|
-
rejected.push({ sourceEventId
|
|
80
|
+
rejectFeedbackOutbox(input.directory, record, { diagnostic: current, ...cause });
|
|
81
|
+
rejected.push({ sourceEventId, diagnostic: current, ...cause });
|
|
82
|
+
continue;
|
|
83
|
+
}
|
|
84
|
+
const { failure, quarantined } = recordFeedbackFailure(input.directory, record, cause);
|
|
85
|
+
if (quarantined) {
|
|
86
|
+
rejected.push({ sourceEventId, diagnostic: 'delivery-quarantined', ...failure });
|
|
74
87
|
continue;
|
|
75
88
|
}
|
|
89
|
+
failures.push({ sourceEventId, ...failure });
|
|
76
90
|
diagnostic = current;
|
|
77
|
-
|
|
91
|
+
// A record-specific failure must not starve the records behind it; an outage ends the flush.
|
|
92
|
+
if (isTransientCause(cause.cause))
|
|
93
|
+
break;
|
|
78
94
|
}
|
|
79
95
|
}
|
|
80
96
|
return {
|
|
@@ -83,6 +99,7 @@ export async function flushFeedbackOutbox(input) {
|
|
|
83
99
|
...(cleanupDiagnostic === undefined ? {} : { cleanupDiagnostic }),
|
|
84
100
|
...(diagnostic === undefined ? {} : { diagnostic }),
|
|
85
101
|
...(rejected.length === 0 ? {} : { rejected }),
|
|
102
|
+
...(failures.length === 0 ? {} : { failures }),
|
|
86
103
|
};
|
|
87
104
|
}
|
|
88
105
|
function prepareEnvelope(input) {
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { isObject } from "./snapshot-partition-guards.mjs";
|
|
2
|
+
import { CAUSE, CODE, MAX_ATTEMPTS, } from "./feedback-failure.mjs";
|
|
3
|
+
// Parsers for the failure and rejection metadata persisted in outbox records.
|
|
4
|
+
function integer(value, min, max) {
|
|
5
|
+
return typeof value === 'number' && Number.isInteger(value) && value >= min && value <= max
|
|
6
|
+
? value
|
|
7
|
+
: undefined;
|
|
8
|
+
}
|
|
9
|
+
function parseCause(value) {
|
|
10
|
+
const { cause, httpStatus, code } = value;
|
|
11
|
+
const status = httpStatus === undefined ? undefined : integer(httpStatus, 100, 599);
|
|
12
|
+
if ((cause !== undefined && !(typeof cause === 'string' && CAUSE.test(cause))) ||
|
|
13
|
+
(code !== undefined && !(typeof code === 'string' && CODE.test(code))) ||
|
|
14
|
+
(httpStatus !== undefined && status === undefined))
|
|
15
|
+
throw new Error('invalid feedback outbox failure');
|
|
16
|
+
return {
|
|
17
|
+
...(typeof cause === 'string' ? { cause } : {}),
|
|
18
|
+
...(status === undefined ? {} : { httpStatus: status }),
|
|
19
|
+
...(typeof code === 'string' ? { code } : {}),
|
|
20
|
+
};
|
|
21
|
+
}
|
|
22
|
+
export function parseFailure(value) {
|
|
23
|
+
const attempts = isObject(value) ? integer(value.attempts, 1, MAX_ATTEMPTS) : undefined;
|
|
24
|
+
if (!isObject(value) || attempts === undefined || typeof value.cause !== 'string')
|
|
25
|
+
throw new Error('invalid feedback outbox failure');
|
|
26
|
+
return { ...parseCause(value), attempts };
|
|
27
|
+
}
|
|
28
|
+
export function parseRejection(value) {
|
|
29
|
+
if (!isObject(value) || typeof value.diagnostic !== 'string' || !CAUSE.test(value.diagnostic))
|
|
30
|
+
throw new Error('invalid feedback outbox rejection');
|
|
31
|
+
const attempts = value.attempts === undefined ? undefined : integer(value.attempts, 1, MAX_ATTEMPTS);
|
|
32
|
+
if (value.attempts !== undefined && attempts === undefined)
|
|
33
|
+
throw new Error('invalid feedback outbox rejection');
|
|
34
|
+
return {
|
|
35
|
+
...parseCause(value),
|
|
36
|
+
diagnostic: value.diagnostic,
|
|
37
|
+
...(attempts === undefined ? {} : { attempts }),
|
|
38
|
+
};
|
|
39
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Why one delivery attempt failed, in a closed vocabulary with no messages, URLs, headers, or bodies
|
|
3
|
+
* so it can never echo a secret: `network`, `timeout`, `http-5xx`, `http-4xx`, `http-401`,
|
|
4
|
+
* `http-403`, `http-408`, `http-429`, `missing-env:<NAME>`, `invalid-url`, `client-unavailable`,
|
|
5
|
+
* `error:<ClassName>`, or the diagnostic itself for conflicts and archived sessions.
|
|
6
|
+
*/
|
|
7
|
+
export type FeedbackCause = {
|
|
8
|
+
cause: string;
|
|
9
|
+
httpStatus?: number;
|
|
10
|
+
code?: string;
|
|
11
|
+
};
|
|
12
|
+
/** A pending record's persisted failure; `attempts` counts consecutive flushes with this cause. */
|
|
13
|
+
export type FeedbackFailure = FeedbackCause & {
|
|
14
|
+
attempts: number;
|
|
15
|
+
};
|
|
16
|
+
/** What a `.rejected` record keeps about why it was refused. */
|
|
17
|
+
export type FeedbackRejection = Partial<FeedbackCause> & {
|
|
18
|
+
diagnostic: string;
|
|
19
|
+
attempts?: number;
|
|
20
|
+
};
|
|
21
|
+
export declare const QUARANTINE_ATTEMPTS = 5;
|
|
22
|
+
/** The highest persisted attempt count; later attempts saturate here. */
|
|
23
|
+
export declare const MAX_ATTEMPTS = 1000;
|
|
24
|
+
export declare const CAUSE: RegExp;
|
|
25
|
+
export declare const CODE: RegExp;
|
|
26
|
+
/** Transient or environmental causes never quarantine; only a record-specific cause can. */
|
|
27
|
+
export declare function isTransientCause(cause: string): boolean;
|
|
28
|
+
/** A missing connection variable is named; any other configuration fault is an invalid URL. */
|
|
29
|
+
export declare function configurationCause(env?: NodeJS.ProcessEnv): FeedbackCause;
|
|
30
|
+
export declare function statusCause(status: number): FeedbackCause;
|
|
31
|
+
/** Classifies a raw delivery error. Only the status, the error name, and a system code are read. */
|
|
32
|
+
export declare function causeOfError(error: unknown): FeedbackCause;
|
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
import { isObject } from "./snapshot-partition-guards.mjs";
|
|
2
|
+
export const QUARANTINE_ATTEMPTS = 5;
|
|
3
|
+
/** The highest persisted attempt count; later attempts saturate here. */
|
|
4
|
+
export const MAX_ATTEMPTS = 1000;
|
|
5
|
+
export const CAUSE = /^[A-Za-z0-9_:.-]{1,80}$/;
|
|
6
|
+
export const CODE = /^[A-Z][A-Z0-9_]{1,40}$/;
|
|
7
|
+
// Healing without touching the record: outages, throttling, credentials, and the environment.
|
|
8
|
+
const HEALS = /^(network|timeout|http-5xx|http-(401|403|408|429)|missing-env:.*|invalid-url)$/;
|
|
9
|
+
const HEALS_TOO = /^(client-unavailable|readback-unconfirmed|delivery-timeout)$/;
|
|
10
|
+
/** Transient or environmental causes never quarantine; only a record-specific cause can. */
|
|
11
|
+
export function isTransientCause(cause) {
|
|
12
|
+
return HEALS.test(cause) || HEALS_TOO.test(cause);
|
|
13
|
+
}
|
|
14
|
+
/** A missing connection variable is named; any other configuration fault is an invalid URL. */
|
|
15
|
+
export function configurationCause(env = process.env) {
|
|
16
|
+
const name = ['AGENT_BLACKBOARD_URL', 'AGENT_BLACKBOARD_TOKEN'].find((key) => !env[key]);
|
|
17
|
+
return { cause: name === undefined ? 'invalid-url' : `missing-env:${name}` };
|
|
18
|
+
}
|
|
19
|
+
export function statusCause(status) {
|
|
20
|
+
if (status >= 500)
|
|
21
|
+
return { cause: 'http-5xx', httpStatus: status };
|
|
22
|
+
const exact = [401, 403, 408, 429].includes(status);
|
|
23
|
+
return {
|
|
24
|
+
cause: exact ? `http-${status}` : status >= 400 ? 'http-4xx' : 'http-other',
|
|
25
|
+
httpStatus: status,
|
|
26
|
+
};
|
|
27
|
+
}
|
|
28
|
+
/** Classifies a raw delivery error. Only the status, the error name, and a system code are read. */
|
|
29
|
+
export function causeOfError(error) {
|
|
30
|
+
if (!isObject(error))
|
|
31
|
+
return { cause: 'error:unknown' };
|
|
32
|
+
const status = error.status ?? error.statusCode;
|
|
33
|
+
if (typeof status === 'number' && Number.isInteger(status) && status >= 100 && status <= 599)
|
|
34
|
+
return statusCause(status);
|
|
35
|
+
const nested = isObject(error.cause) ? error.cause : undefined;
|
|
36
|
+
const raw = error.code ?? nested?.code;
|
|
37
|
+
const code = typeof raw === 'string' && CODE.test(raw) ? raw : undefined;
|
|
38
|
+
const { name, message } = error;
|
|
39
|
+
if (code !== undefined)
|
|
40
|
+
return { cause: 'network', code };
|
|
41
|
+
if (name === 'TypeError' && message === 'fetch failed')
|
|
42
|
+
return { cause: 'network' };
|
|
43
|
+
return {
|
|
44
|
+
cause: typeof name === 'string' && /^[A-Za-z0-9]{1,40}$/.test(name)
|
|
45
|
+
? `error:${name}`
|
|
46
|
+
: 'error:unknown',
|
|
47
|
+
};
|
|
48
|
+
}
|
|
@@ -1,7 +1,11 @@
|
|
|
1
|
+
import { type FeedbackCause } from './feedback-failure.mts';
|
|
1
2
|
import type { FeedbackDiagnostic } from './feedback-types.mts';
|
|
2
3
|
export declare class FeedbackDeliveryError extends Error {
|
|
3
4
|
readonly status = "blocked";
|
|
4
5
|
readonly diagnostic: FeedbackDiagnostic;
|
|
5
|
-
|
|
6
|
+
/** The non-secret cause; it defaults to the diagnostic itself. */
|
|
7
|
+
readonly failure: FeedbackCause;
|
|
8
|
+
constructor(diagnostic: FeedbackDiagnostic, detail?: string, failure?: FeedbackCause);
|
|
6
9
|
}
|
|
7
10
|
export declare function feedbackDiagnostic(error: unknown): FeedbackDiagnostic;
|
|
11
|
+
export declare function feedbackFailure(error: unknown): FeedbackCause;
|
|
@@ -1,11 +1,15 @@
|
|
|
1
1
|
import { isObject } from "./snapshot-partition-guards.mjs";
|
|
2
|
+
import { causeOfError } from "./feedback-failure.mjs";
|
|
2
3
|
export class FeedbackDeliveryError extends Error {
|
|
3
4
|
status = 'blocked';
|
|
4
5
|
diagnostic;
|
|
5
|
-
|
|
6
|
+
/** The non-secret cause; it defaults to the diagnostic itself. */
|
|
7
|
+
failure;
|
|
8
|
+
constructor(diagnostic, detail, failure) {
|
|
6
9
|
super(`Blackboard feedback blocked: ${diagnostic}${detail === undefined ? '' : `: ${detail}`}`);
|
|
7
10
|
this.name = 'FeedbackDeliveryError';
|
|
8
11
|
this.diagnostic = diagnostic;
|
|
12
|
+
this.failure = failure ?? { cause: diagnostic };
|
|
9
13
|
}
|
|
10
14
|
}
|
|
11
15
|
export function feedbackDiagnostic(error) {
|
|
@@ -21,3 +25,6 @@ export function feedbackDiagnostic(error) {
|
|
|
21
25
|
return 'identity-conflict';
|
|
22
26
|
return 'blackboard-unavailable';
|
|
23
27
|
}
|
|
28
|
+
export function feedbackFailure(error) {
|
|
29
|
+
return error instanceof FeedbackDeliveryError ? error.failure : causeOfError(error);
|
|
30
|
+
}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { feedbackDeadline } from "./feedback-deadline.mjs";
|
|
2
2
|
import { FeedbackDeliveryError, feedbackDiagnostic } from "./feedback-online-error.mjs";
|
|
3
|
+
import { causeOfError, configurationCause } from "./feedback-failure.mjs";
|
|
3
4
|
import { canonicalFeedback, canonicalFeedbackEvent } from "./feedback-canonical.mjs";
|
|
4
5
|
import { loadClient, resolveBlackboardConnection } from "./client.mjs";
|
|
5
6
|
import { normalizeRepositories, validateFeedbackEnvelope } from "./feedback-codec.mjs";
|
|
@@ -93,7 +94,7 @@ export async function deliverFeedbackOnline(input, fresh = false) {
|
|
|
93
94
|
throw new Error('invalid connection URL');
|
|
94
95
|
}
|
|
95
96
|
catch {
|
|
96
|
-
throw new FeedbackDeliveryError('configuration-invalid');
|
|
97
|
+
throw new FeedbackDeliveryError('configuration-invalid', undefined, configurationCause(input.env));
|
|
97
98
|
}
|
|
98
99
|
let client;
|
|
99
100
|
try {
|
|
@@ -157,7 +158,7 @@ export async function deliverFeedbackOnline(input, fresh = false) {
|
|
|
157
158
|
catch (error) {
|
|
158
159
|
throw error instanceof FeedbackDeliveryError
|
|
159
160
|
? error
|
|
160
|
-
: new FeedbackDeliveryError(feedbackDiagnostic(error));
|
|
161
|
+
: new FeedbackDeliveryError(feedbackDiagnostic(error), undefined, causeOfError(error));
|
|
161
162
|
}
|
|
162
163
|
}, input.timeoutMs);
|
|
163
164
|
}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
import { type FeedbackCause, type FeedbackFailure } from './feedback-failure.mts';
|
|
2
|
+
import type { FeedbackOutboxRecord } from './feedback-types.mts';
|
|
3
|
+
export type FeedbackFailureReport = FeedbackFailure & {
|
|
4
|
+
sourceEventId: string;
|
|
5
|
+
};
|
|
6
|
+
/**
|
|
7
|
+
* Persists one failed flush attempt with the record. The attempt count continues only while the
|
|
8
|
+
* cause repeats. A record-specific (non-transient) cause on {@link QUARANTINE_ATTEMPTS} consecutive
|
|
9
|
+
* attempts moves the record to the rejected area with that cause as its diagnostic.
|
|
10
|
+
*/
|
|
11
|
+
export declare function recordFeedbackFailure(directory: string, record: FeedbackOutboxRecord, cause: FeedbackCause): {
|
|
12
|
+
failure: FeedbackFailure;
|
|
13
|
+
quarantined: boolean;
|
|
14
|
+
};
|
|
15
|
+
/** Every pending record's last failed flush, without creating the outbox directory. */
|
|
16
|
+
export declare function readFeedbackFailures(directory: string): FeedbackFailureReport[];
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
import { join } from 'node:path';
|
|
2
|
+
import { withFileLock } from "../private-files/lock.mjs";
|
|
3
|
+
import { canonicalFeedback } from "./feedback-canonical.mjs";
|
|
4
|
+
import { ensureOutboxDirectory } from "./feedback-outbox-directory.mjs";
|
|
5
|
+
import { MAX_ATTEMPTS, QUARANTINE_ATTEMPTS, isTransientCause, } from "./feedback-failure.mjs";
|
|
6
|
+
import { moveToRejected } from "./feedback-outbox-rejected.mjs";
|
|
7
|
+
import { writeOutboxFile } from "./feedback-outbox-write.mjs";
|
|
8
|
+
import { filename, outboxDirectory, records, syncDirectory } from "./feedback-outbox.mjs";
|
|
9
|
+
/**
|
|
10
|
+
* Persists one failed flush attempt with the record. The attempt count continues only while the
|
|
11
|
+
* cause repeats. A record-specific (non-transient) cause on {@link QUARANTINE_ATTEMPTS} consecutive
|
|
12
|
+
* attempts moves the record to the rejected area with that cause as its diagnostic.
|
|
13
|
+
*/
|
|
14
|
+
export function recordFeedbackFailure(directory, record, cause) {
|
|
15
|
+
const path = outboxDirectory(directory, true);
|
|
16
|
+
return withFileLock(join(path, '.records'), () => {
|
|
17
|
+
const existing = records(path).find((item) => item.path === join(path, filename(record)));
|
|
18
|
+
const attempts = existing?.failure?.cause === cause.cause
|
|
19
|
+
? Math.min(existing.failure.attempts + 1, MAX_ATTEMPTS)
|
|
20
|
+
: 1;
|
|
21
|
+
const failure = { ...cause, attempts };
|
|
22
|
+
if (!existing)
|
|
23
|
+
return { failure, quarantined: false };
|
|
24
|
+
if (canonicalFeedback(existing.record) !== canonicalFeedback(record))
|
|
25
|
+
throw new Error('feedback outbox changed during delivery');
|
|
26
|
+
if (!isTransientCause(cause.cause) && attempts >= QUARANTINE_ATTEMPTS) {
|
|
27
|
+
moveToRejected(path, record, { ...failure, diagnostic: 'delivery-quarantined' });
|
|
28
|
+
return { failure, quarantined: true };
|
|
29
|
+
}
|
|
30
|
+
writeOutboxFile(path, filename(record), { ...record, failure });
|
|
31
|
+
syncDirectory(path);
|
|
32
|
+
return { failure, quarantined: false };
|
|
33
|
+
});
|
|
34
|
+
}
|
|
35
|
+
/** Every pending record's last failed flush, without creating the outbox directory. */
|
|
36
|
+
export function readFeedbackFailures(directory) {
|
|
37
|
+
const path = outboxDirectory(directory, false);
|
|
38
|
+
if (!ensureOutboxDirectory(path, false))
|
|
39
|
+
return [];
|
|
40
|
+
return withFileLock(join(path, '.records'), () => records(path).flatMap(({ record, failure }) => failure ? [{ sourceEventId: record.envelope.sourceEventId, ...failure }] : []));
|
|
41
|
+
}
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
import type { FeedbackFailure, FeedbackRejection } from './feedback-failure.mts';
|
|
2
|
+
import type { FeedbackOutboxRecord } from './feedback-types.mts';
|
|
3
|
+
export declare const RECORD_MAX_BYTES = 18000;
|
|
4
|
+
export type LoadedRecord = {
|
|
5
|
+
record: FeedbackOutboxRecord;
|
|
6
|
+
/** The record payload size, excluding failure and rejection notes, as admission measures it. */
|
|
7
|
+
bytes: number;
|
|
8
|
+
failure?: FeedbackFailure;
|
|
9
|
+
rejection?: FeedbackRejection;
|
|
10
|
+
};
|
|
11
|
+
export declare function readRecord(path: string): LoadedRecord;
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { closeSync, constants, fstatSync } from 'node:fs';
|
|
2
|
+
import { openLogFile, readLogContent } from "../private-files/log-file.mjs";
|
|
3
|
+
import { validateFeedbackEnvelope } from "./feedback-codec.mjs";
|
|
4
|
+
import { parseFailure, parseRejection } from "./feedback-failure-parse.mjs";
|
|
5
|
+
import { validateFeedbackIdentity } from "./feedback-identity.mjs";
|
|
6
|
+
import { isObject } from "./snapshot-partition-guards.mjs";
|
|
7
|
+
export const RECORD_MAX_BYTES = 18_000;
|
|
8
|
+
// A stored failure or rejection note rides along with a record at its size limit.
|
|
9
|
+
const NOTE_MAX_BYTES = 1_000;
|
|
10
|
+
const RECORD_KEYS = ['identity', 'envelope', 'failure', 'rejection'];
|
|
11
|
+
export function readRecord(path) {
|
|
12
|
+
const descriptor = openLogFile(path, constants.O_RDONLY);
|
|
13
|
+
try {
|
|
14
|
+
const limit = RECORD_MAX_BYTES + NOTE_MAX_BYTES;
|
|
15
|
+
if (fstatSync(descriptor).size > limit)
|
|
16
|
+
throw new Error('feedback outbox record is too large');
|
|
17
|
+
const value = JSON.parse(readLogContent(descriptor, limit));
|
|
18
|
+
if (!isObject(value) || Object.keys(value).some((key) => !RECORD_KEYS.includes(key)))
|
|
19
|
+
throw new Error('invalid feedback outbox record');
|
|
20
|
+
validateFeedbackIdentity(value.identity);
|
|
21
|
+
validateFeedbackEnvelope(value.envelope);
|
|
22
|
+
const record = { identity: value.identity, envelope: value.envelope };
|
|
23
|
+
return {
|
|
24
|
+
record,
|
|
25
|
+
bytes: Buffer.byteLength(JSON.stringify(record)),
|
|
26
|
+
...(value.failure === undefined ? {} : { failure: parseFailure(value.failure) }),
|
|
27
|
+
...(value.rejection === undefined ? {} : { rejection: parseRejection(value.rejection) }),
|
|
28
|
+
};
|
|
29
|
+
}
|
|
30
|
+
finally {
|
|
31
|
+
closeSync(descriptor);
|
|
32
|
+
}
|
|
33
|
+
}
|
|
@@ -1,9 +1,18 @@
|
|
|
1
|
+
import type { FeedbackRejection } from './feedback-failure.mts';
|
|
1
2
|
import type { FeedbackOutboxRecord } from './feedback-types.mts';
|
|
2
3
|
/**
|
|
3
|
-
* Moves a permanently rejected record out of the pending set into the rejected area of the outbox
|
|
4
|
-
* The content is kept, never deleted, so a corrected
|
|
5
|
-
* rejected note stays inspectable. A record that is
|
|
4
|
+
* Moves a permanently rejected record out of the pending set into the rejected area of the outbox,
|
|
5
|
+
* with the rejection diagnostic stored beside it. The content is kept, never deleted, so a corrected
|
|
6
|
+
* retry of the same event is accepted while the rejected note stays inspectable. A record that is
|
|
7
|
+
* no longer pending is left alone. The caller must hold the outbox lock.
|
|
6
8
|
*/
|
|
7
|
-
export declare function
|
|
8
|
-
|
|
9
|
+
export declare function moveToRejected(path: string, record: FeedbackOutboxRecord, rejection: FeedbackRejection): boolean;
|
|
10
|
+
export declare function rejectFeedbackOutbox(directory: string, record: FeedbackOutboxRecord, rejection: FeedbackRejection): void;
|
|
11
|
+
/** Reads the rejected records and their stored diagnostics without creating the outbox directory. */
|
|
12
|
+
export declare function readRejectedDetails(directory: string): Array<{
|
|
13
|
+
record: FeedbackOutboxRecord;
|
|
14
|
+
rejection?: FeedbackRejection;
|
|
15
|
+
}>;
|
|
9
16
|
export declare function readRejectedFeedbackOutbox(directory: string): FeedbackOutboxRecord[];
|
|
17
|
+
/** Deletes rejected records last written at least `olderThanDays` days ago; 0 deletes them all. */
|
|
18
|
+
export declare function pruneRejectedFeedbackOutbox(directory: string, olderThanDays: number): number;
|
|
@@ -1,34 +1,60 @@
|
|
|
1
|
-
import { readdirSync,
|
|
1
|
+
import { readdirSync, statSync, unlinkSync } from 'node:fs';
|
|
2
2
|
import { join } from 'node:path';
|
|
3
3
|
import { withFileLock } from "../private-files/lock.mjs";
|
|
4
4
|
import { canonicalFeedback } from "./feedback-canonical.mjs";
|
|
5
5
|
import { ensureOutboxDirectory } from "./feedback-outbox-directory.mjs";
|
|
6
|
-
import {
|
|
6
|
+
import { readRecord } from "./feedback-outbox-read.mjs";
|
|
7
|
+
import { writeOutboxFile } from "./feedback-outbox-write.mjs";
|
|
8
|
+
import { filename, outboxDirectory, records, syncDirectory } from "./feedback-outbox.mjs";
|
|
9
|
+
const REJECTED = /^[a-f0-9]{64}\.rejected$/;
|
|
7
10
|
const rejectedName = (record) => filename(record).replace(/\.json$/, '.rejected');
|
|
8
11
|
/**
|
|
9
|
-
* Moves a permanently rejected record out of the pending set into the rejected area of the outbox
|
|
10
|
-
* The content is kept, never deleted, so a corrected
|
|
11
|
-
* rejected note stays inspectable. A record that is
|
|
12
|
+
* Moves a permanently rejected record out of the pending set into the rejected area of the outbox,
|
|
13
|
+
* with the rejection diagnostic stored beside it. The content is kept, never deleted, so a corrected
|
|
14
|
+
* retry of the same event is accepted while the rejected note stays inspectable. A record that is
|
|
15
|
+
* no longer pending is left alone. The caller must hold the outbox lock.
|
|
12
16
|
*/
|
|
13
|
-
export function
|
|
17
|
+
export function moveToRejected(path, record, rejection) {
|
|
18
|
+
const existing = records(path).find((item) => item.path === join(path, filename(record)));
|
|
19
|
+
if (!existing)
|
|
20
|
+
return false;
|
|
21
|
+
if (canonicalFeedback(existing.record) !== canonicalFeedback(record))
|
|
22
|
+
throw new Error('feedback outbox changed during delivery');
|
|
23
|
+
writeOutboxFile(path, rejectedName(record), { ...existing.record, rejection });
|
|
24
|
+
unlinkSync(existing.path);
|
|
25
|
+
syncDirectory(path);
|
|
26
|
+
return true;
|
|
27
|
+
}
|
|
28
|
+
export function rejectFeedbackOutbox(directory, record, rejection) {
|
|
14
29
|
const path = outboxDirectory(directory, true);
|
|
15
|
-
withFileLock(join(path, '.records'), () =>
|
|
16
|
-
const existing = records(path).find((item) => item.path === join(path, filename(record)));
|
|
17
|
-
if (!existing)
|
|
18
|
-
return;
|
|
19
|
-
if (canonicalFeedback(existing.record) !== canonicalFeedback(record))
|
|
20
|
-
throw new Error('feedback outbox changed during delivery');
|
|
21
|
-
renameSync(existing.path, join(path, rejectedName(record)));
|
|
22
|
-
syncDirectory(path);
|
|
23
|
-
});
|
|
30
|
+
withFileLock(join(path, '.records'), () => void moveToRejected(path, record, rejection));
|
|
24
31
|
}
|
|
25
|
-
/** Reads the rejected records without creating the outbox directory. */
|
|
26
|
-
export function
|
|
32
|
+
/** Reads the rejected records and their stored diagnostics without creating the outbox directory. */
|
|
33
|
+
export function readRejectedDetails(directory) {
|
|
27
34
|
const path = outboxDirectory(directory, false);
|
|
28
35
|
if (!ensureOutboxDirectory(path, false))
|
|
29
36
|
return [];
|
|
30
37
|
return withFileLock(join(path, '.records'), () => readdirSync(path)
|
|
31
|
-
.filter((name) =>
|
|
38
|
+
.filter((name) => REJECTED.test(name))
|
|
32
39
|
.sort()
|
|
33
|
-
.map((name) => readRecord(join(path, name))
|
|
40
|
+
.map((name) => readRecord(join(path, name)))
|
|
41
|
+
.map(({ record, rejection }) => ({ record, ...(rejection ? { rejection } : {}) })));
|
|
42
|
+
}
|
|
43
|
+
export function readRejectedFeedbackOutbox(directory) {
|
|
44
|
+
return readRejectedDetails(directory).map((item) => item.record);
|
|
45
|
+
}
|
|
46
|
+
/** Deletes rejected records last written at least `olderThanDays` days ago; 0 deletes them all. */
|
|
47
|
+
export function pruneRejectedFeedbackOutbox(directory, olderThanDays) {
|
|
48
|
+
const path = outboxDirectory(directory, false);
|
|
49
|
+
if (!ensureOutboxDirectory(path, false))
|
|
50
|
+
return 0;
|
|
51
|
+
const cutoff = Date.now() - olderThanDays * 86_400_000;
|
|
52
|
+
return withFileLock(join(path, '.records'), () => {
|
|
53
|
+
const old = readdirSync(path).filter((name) => REJECTED.test(name) && statSync(join(path, name)).mtimeMs <= cutoff);
|
|
54
|
+
for (const name of old)
|
|
55
|
+
unlinkSync(join(path, name));
|
|
56
|
+
if (old.length > 0)
|
|
57
|
+
syncDirectory(path);
|
|
58
|
+
return old.length;
|
|
59
|
+
});
|
|
34
60
|
}
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import { closeSync, constants, fsyncSync, openSync, renameSync, unlinkSync } from 'node:fs';
|
|
2
|
+
import { randomUUID } from 'node:crypto';
|
|
3
|
+
import { join } from 'node:path';
|
|
4
|
+
import { writeAll } from "../private-files/log-file.mjs";
|
|
5
|
+
/** Writes one outbox file durably: a private temporary file, fsync, then an atomic rename. */
|
|
6
|
+
export function writeOutboxFile(directory, name, value) {
|
|
7
|
+
const temporary = join(directory, `.persist-${randomUUID()}`);
|
|
8
|
+
const descriptor = openSync(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
|
|
9
|
+
try {
|
|
10
|
+
writeAll(descriptor, JSON.stringify(value));
|
|
11
|
+
fsyncSync(descriptor);
|
|
12
|
+
closeSync(descriptor);
|
|
13
|
+
renameSync(temporary, join(directory, name));
|
|
14
|
+
}
|
|
15
|
+
catch (error) {
|
|
16
|
+
try {
|
|
17
|
+
closeSync(descriptor);
|
|
18
|
+
}
|
|
19
|
+
catch { }
|
|
20
|
+
try {
|
|
21
|
+
unlinkSync(temporary);
|
|
22
|
+
}
|
|
23
|
+
catch { }
|
|
24
|
+
throw error;
|
|
25
|
+
}
|
|
26
|
+
}
|
|
@@ -1,13 +1,8 @@
|
|
|
1
|
+
import { type LoadedRecord } from './feedback-outbox-read.mts';
|
|
1
2
|
import type { FeedbackOutboxRecord, FeedbackOutboxStatus } from './feedback-types.mts';
|
|
2
3
|
export declare function outboxDirectory(directory: string, create: boolean): string;
|
|
3
4
|
export declare function filename(record: FeedbackOutboxRecord): string;
|
|
4
|
-
export declare function
|
|
5
|
-
record: FeedbackOutboxRecord;
|
|
6
|
-
bytes: number;
|
|
7
|
-
};
|
|
8
|
-
export declare function records(directory: string): Array<{
|
|
9
|
-
record: FeedbackOutboxRecord;
|
|
10
|
-
bytes: number;
|
|
5
|
+
export declare function records(directory: string): Array<LoadedRecord & {
|
|
11
6
|
path: string;
|
|
12
7
|
}>;
|
|
13
8
|
export declare function syncDirectory(directory: string): void;
|
|
@@ -1,16 +1,15 @@
|
|
|
1
1
|
import { canonicalFeedback, canonicalFeedbackEvent } from "./feedback-canonical.mjs";
|
|
2
|
-
import { createHash
|
|
3
|
-
import { closeSync, constants, fsyncSync,
|
|
2
|
+
import { createHash } from 'node:crypto';
|
|
3
|
+
import { closeSync, constants, fsyncSync, openSync, readdirSync, unlinkSync } from 'node:fs';
|
|
4
4
|
import { isAbsolute, join, resolve } from 'node:path';
|
|
5
5
|
import { ensureOutboxDirectory } from "./feedback-outbox-directory.mjs";
|
|
6
6
|
import { withFileLock } from "../private-files/lock.mjs";
|
|
7
|
-
import {
|
|
7
|
+
import { writeOutboxFile } from "./feedback-outbox-write.mjs";
|
|
8
8
|
import { validateFeedbackEnvelope } from "./feedback-codec.mjs";
|
|
9
|
+
import { RECORD_MAX_BYTES, readRecord } from "./feedback-outbox-read.mjs";
|
|
9
10
|
import { validateFeedbackIdentity } from "./feedback-identity.mjs";
|
|
10
|
-
import { isObject } from "./snapshot-partition-guards.mjs";
|
|
11
11
|
const FEEDBACK_OUTBOX_MAX_RECORDS = 128;
|
|
12
12
|
const FEEDBACK_OUTBOX_MAX_BYTES = 2_000_000;
|
|
13
|
-
const RECORD_MAX_BYTES = 18_000;
|
|
14
13
|
export function outboxDirectory(directory, create) {
|
|
15
14
|
if (typeof directory !== 'string' || directory.length > 4096 || !isAbsolute(directory))
|
|
16
15
|
throw new Error('feedback outbox requires an absolute directory');
|
|
@@ -23,25 +22,6 @@ export function filename(record) {
|
|
|
23
22
|
.update(JSON.stringify([record.identity.sessionId, record.envelope.sourceEventId]))
|
|
24
23
|
.digest('hex')}.json`;
|
|
25
24
|
}
|
|
26
|
-
export function readRecord(path) {
|
|
27
|
-
const descriptor = openLogFile(path, constants.O_RDONLY);
|
|
28
|
-
try {
|
|
29
|
-
const status = fstatSync(descriptor);
|
|
30
|
-
const bytes = status.size;
|
|
31
|
-
if (bytes > RECORD_MAX_BYTES)
|
|
32
|
-
throw new Error('feedback outbox record is too large');
|
|
33
|
-
const value = JSON.parse(readLogContent(descriptor, RECORD_MAX_BYTES));
|
|
34
|
-
if (!isObject(value) ||
|
|
35
|
-
Object.keys(value).some((key) => !['identity', 'envelope'].includes(key)))
|
|
36
|
-
throw new Error('invalid feedback outbox record');
|
|
37
|
-
validateFeedbackIdentity(value.identity);
|
|
38
|
-
validateFeedbackEnvelope(value.envelope);
|
|
39
|
-
return { record: { identity: value.identity, envelope: value.envelope }, bytes };
|
|
40
|
-
}
|
|
41
|
-
finally {
|
|
42
|
-
closeSync(descriptor);
|
|
43
|
-
}
|
|
44
|
-
}
|
|
45
25
|
export function records(directory) {
|
|
46
26
|
const paths = readdirSync(directory).filter((name) => !name.endsWith('.rejected') && !name.startsWith('.records.lock'));
|
|
47
27
|
if (paths.length > FEEDBACK_OUTBOX_MAX_RECORDS)
|
|
@@ -102,7 +82,6 @@ export function persistFeedbackOutbox(directory, record) {
|
|
|
102
82
|
const current = records(path);
|
|
103
83
|
const name = filename(record);
|
|
104
84
|
const existing = current.find((item) => item.path === join(path, name));
|
|
105
|
-
const serialized = JSON.stringify(record);
|
|
106
85
|
if (existing) {
|
|
107
86
|
// A version-only difference is the same event: delivery accepts it into the stored session.
|
|
108
87
|
const { version: _retained, ...retainedIdentity } = existing.record.identity;
|
|
@@ -112,37 +91,13 @@ export function persistFeedbackOutbox(directory, record) {
|
|
|
112
91
|
throw new Error('feedback source event conflicts with a retained unsent record');
|
|
113
92
|
return existing.record;
|
|
114
93
|
}
|
|
115
|
-
const bytes = Buffer.byteLength(
|
|
94
|
+
const bytes = Buffer.byteLength(JSON.stringify(record));
|
|
116
95
|
if (bytes > RECORD_MAX_BYTES ||
|
|
117
96
|
current.length >= FEEDBACK_OUTBOX_MAX_RECORDS ||
|
|
118
97
|
current.reduce((sum, item) => sum + item.bytes, 0) + bytes > FEEDBACK_OUTBOX_MAX_BYTES)
|
|
119
98
|
throw new Error('feedback outbox is full; unsent records retained');
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
try {
|
|
123
|
-
writeAll(descriptor, serialized);
|
|
124
|
-
fsyncSync(descriptor);
|
|
125
|
-
}
|
|
126
|
-
catch (error) {
|
|
127
|
-
closeSync(descriptor);
|
|
128
|
-
try {
|
|
129
|
-
unlinkSync(temporary);
|
|
130
|
-
}
|
|
131
|
-
catch { }
|
|
132
|
-
throw error;
|
|
133
|
-
}
|
|
134
|
-
closeSync(descriptor);
|
|
135
|
-
try {
|
|
136
|
-
renameSync(temporary, join(path, name));
|
|
137
|
-
syncDirectory(path);
|
|
138
|
-
}
|
|
139
|
-
catch (error) {
|
|
140
|
-
try {
|
|
141
|
-
unlinkSync(temporary);
|
|
142
|
-
}
|
|
143
|
-
catch { }
|
|
144
|
-
throw error;
|
|
145
|
-
}
|
|
99
|
+
writeOutboxFile(path, name, record);
|
|
100
|
+
syncDirectory(path);
|
|
146
101
|
return record;
|
|
147
102
|
});
|
|
148
103
|
}
|
|
@@ -37,7 +37,7 @@ export type FeedbackReceipt = {
|
|
|
37
37
|
/** Set when the session already stored a different `version`; the entry was delivered into it. */
|
|
38
38
|
storedVersion?: string;
|
|
39
39
|
};
|
|
40
|
-
export type FeedbackDiagnostic = 'blackboard-unavailable' | 'client-unavailable' | 'configuration-invalid' | 'authentication-rejected' | 'identity-conflict' | 'readback-unconfirmed' | 'event-conflict' | 'archived-session' | 'delivery-timeout';
|
|
40
|
+
export type FeedbackDiagnostic = 'blackboard-unavailable' | 'client-unavailable' | 'configuration-invalid' | 'authentication-rejected' | 'identity-conflict' | 'readback-unconfirmed' | 'event-conflict' | 'archived-session' | 'delivery-timeout' | 'delivery-quarantined';
|
|
41
41
|
export type FeedbackDeliveryResult = {
|
|
42
42
|
status: 'delivered';
|
|
43
43
|
sourceEventId: string;
|
|
@@ -21,6 +21,8 @@ export type * from './feedback-types.mts';
|
|
|
21
21
|
export { createFeedbackEnvelope, validateFeedbackEnvelope } from './feedback-codec.mts';
|
|
22
22
|
export { writeFeedback, verifyFreshFeedback, flushFeedbackOutbox, FeedbackDeliveryError, } from './feedback-delivery.mts';
|
|
23
23
|
export { feedbackOutboxStatus, readFeedbackOutbox } from './feedback-outbox.mts';
|
|
24
|
+
export { readFeedbackFailures } from './feedback-outbox-failure.mts';
|
|
25
|
+
export { pruneRejectedFeedbackOutbox, readRejectedDetails } from './feedback-outbox-rejected.mts';
|
|
24
26
|
export { composeRetrospective } from './feedback-compose.mts';
|
|
25
27
|
export type { RetrospectiveCompositionInput, FeedbackAssessment } from './feedback-compose.mts';
|
|
26
28
|
export type { JournalAuditOptions } from './feedback-journal-audit.mts';
|
|
@@ -40,5 +40,7 @@ export { BlackboardNotInstalledError, resolveBlackboardConnection } from "./clie
|
|
|
40
40
|
export { createFeedbackEnvelope, validateFeedbackEnvelope } from "./feedback-codec.mjs";
|
|
41
41
|
export { writeFeedback, verifyFreshFeedback, flushFeedbackOutbox, FeedbackDeliveryError, } from "./feedback-delivery.mjs";
|
|
42
42
|
export { feedbackOutboxStatus, readFeedbackOutbox } from "./feedback-outbox.mjs";
|
|
43
|
+
export { readFeedbackFailures } from "./feedback-outbox-failure.mjs";
|
|
44
|
+
export { pruneRejectedFeedbackOutbox, readRejectedDetails } from "./feedback-outbox-rejected.mjs";
|
|
43
45
|
export { composeRetrospective } from "./feedback-compose.mjs";
|
|
44
46
|
export { feedbackOutboxCounts } from "./feedback-outbox-counts.mjs";
|
|
@@ -4,7 +4,7 @@ import { readSessionId } from "./context.mjs";
|
|
|
4
4
|
import { journalAppend, journalEntries } from "./handlers-journal.mjs";
|
|
5
5
|
import { retrospectiveSave } from "./handlers-retrospective.mjs";
|
|
6
6
|
import { retrospectiveCheck } from "./retrospective-check.mjs";
|
|
7
|
-
import { outboxFlush, outboxStatus } from "./handlers-outbox.mjs";
|
|
7
|
+
import { outboxFlush, outboxPruneRejected, outboxStatus } from "./handlers-outbox.mjs";
|
|
8
8
|
import { snapshotArchive } from "./handlers-snapshot-archive.mjs";
|
|
9
9
|
import { snapshotCleanup } from "./handlers-snapshot-cleanup.mjs";
|
|
10
10
|
import { snapshotPartition } from "./handlers-snapshot-partition.mjs";
|
|
@@ -21,6 +21,7 @@ const HANDLERS = {
|
|
|
21
21
|
journal_entries: journalEntries,
|
|
22
22
|
outbox_status: outboxStatus,
|
|
23
23
|
outbox_flush: outboxFlush,
|
|
24
|
+
outbox_prune_rejected: outboxPruneRejected,
|
|
24
25
|
session_ensure: sessionEnsure,
|
|
25
26
|
retrospective_check: retrospectiveCheck,
|
|
26
27
|
retrospective_save: retrospectiveSave,
|
|
@@ -43,6 +44,7 @@ const DIAGNOSTIC_HINTS = {
|
|
|
43
44
|
'client-unavailable': 'agent-blackboard is not installed next to vouchington-tooling; if the install directory was removed, reinstall it first when it lives at a fixed path, then reconnect the server (`/mcp` in Claude Code, or restart Codex)',
|
|
44
45
|
'readback-unconfirmed': 'the write could not be confirmed; retry the same call (same sourceEventId and content)',
|
|
45
46
|
'delivery-timeout': 'delivery timed out; retry the same call (same sourceEventId and content)',
|
|
47
|
+
'delivery-quarantined': 'delivery failed repeatedly and the record was moved to the rejected area',
|
|
46
48
|
};
|
|
47
49
|
function describeError(error) {
|
|
48
50
|
if (error instanceof FeedbackDeliveryError)
|
|
@@ -9,4 +9,5 @@ export declare function outboxCounts(worktree: string, sessionId: string): {
|
|
|
9
9
|
worktreePendingCount: number;
|
|
10
10
|
};
|
|
11
11
|
export declare const outboxStatus: ToolHandler;
|
|
12
|
+
export declare const outboxPruneRejected: ToolHandler;
|
|
12
13
|
export declare const outboxFlush: ToolHandler;
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { flushFeedbackOutbox, feedbackOutboxCounts } from "../agent-blackboard/index.mjs";
|
|
1
|
+
import { flushFeedbackOutbox, feedbackOutboxCounts, pruneRejectedFeedbackOutbox, readFeedbackFailures, readRejectedDetails, } from "../agent-blackboard/index.mjs";
|
|
2
2
|
import { outboxDirectory } from "./context.mjs";
|
|
3
3
|
/**
|
|
4
4
|
* The outbox belongs to the worktree, not to one session, so two counts are reported. `pendingCount`
|
|
@@ -15,9 +15,38 @@ function statusCounts(worktree, sessionId) {
|
|
|
15
15
|
function sessionStatus(pendingCount) {
|
|
16
16
|
return pendingCount === 0 ? 'empty' : 'pending';
|
|
17
17
|
}
|
|
18
|
+
/** Why each pending record last failed and why each kept record was rejected: causes only. */
|
|
19
|
+
function causes(worktree) {
|
|
20
|
+
const directory = outboxDirectory(worktree);
|
|
21
|
+
const failures = readFeedbackFailures(directory);
|
|
22
|
+
const rejected = readRejectedDetails(directory).map(({ record, rejection }) => ({
|
|
23
|
+
sourceEventId: record.envelope.sourceEventId,
|
|
24
|
+
...rejection,
|
|
25
|
+
}));
|
|
26
|
+
return {
|
|
27
|
+
...(failures.length === 0 ? {} : { failures }),
|
|
28
|
+
...(rejected.length === 0 ? {} : { rejected }),
|
|
29
|
+
};
|
|
30
|
+
}
|
|
18
31
|
export const outboxStatus = async (_args, context) => {
|
|
19
32
|
const counts = statusCounts(context.worktree, context.sessionId);
|
|
20
|
-
return {
|
|
33
|
+
return {
|
|
34
|
+
sessionId: context.sessionId,
|
|
35
|
+
status: sessionStatus(counts.pendingCount),
|
|
36
|
+
...counts,
|
|
37
|
+
...causes(context.worktree),
|
|
38
|
+
};
|
|
39
|
+
};
|
|
40
|
+
export const outboxPruneRejected = async (args, context) => {
|
|
41
|
+
const days = args.olderThanDays ?? 7;
|
|
42
|
+
if (typeof days !== 'number' || !Number.isInteger(days) || days < 0)
|
|
43
|
+
throw new Error('olderThanDays must be a non-negative integer');
|
|
44
|
+
const prunedCount = pruneRejectedFeedbackOutbox(outboxDirectory(context.worktree), days);
|
|
45
|
+
return {
|
|
46
|
+
sessionId: context.sessionId,
|
|
47
|
+
prunedCount,
|
|
48
|
+
...statusCounts(context.worktree, context.sessionId),
|
|
49
|
+
};
|
|
21
50
|
};
|
|
22
51
|
export const outboxFlush = async (_args, context) => {
|
|
23
52
|
// Flushing creates the outbox directory, so an empty or absent outbox is reported as is.
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { IDEMPOTENT_ADDITIVE, MUTATING, READ_ONLY, tool, } from "./tools-schema.mjs";
|
|
2
|
+
export const OUTBOX_TOOLS = [
|
|
3
|
+
tool('outbox_status', 'Reports unsent journal records in the worktree outbox. pendingCount and status (empty or ' +
|
|
4
|
+
'pending) cover the caller sessionId only; worktreePendingCount covers every session. ' +
|
|
5
|
+
'rejectedCount (and worktreeRejectedCount) counts permanently rejected records kept aside. ' +
|
|
6
|
+
'failures lists each pending record that failed its last flush as sourceEventId, cause, ' +
|
|
7
|
+
'optional httpStatus and code, and attempts; rejected lists each kept rejection with its ' +
|
|
8
|
+
'stored diagnostic and cause. Causes are non-secret (network, timeout, http-5xx, ' +
|
|
9
|
+
'http-4xx, missing-env:NAME, and similar), never a message, URL, or response body.', READ_ONLY),
|
|
10
|
+
tool('outbox_flush', 'Delivers every retained record in the worktree outbox, whichever session wrote it, and ' +
|
|
11
|
+
'returns deliveredCount for the whole flush. pendingCount and status cover the remaining ' +
|
|
12
|
+
'records of the caller sessionId; worktreePendingCount covers every session. ' +
|
|
13
|
+
'A record with a permanent rejection moves to the rejected area and is listed in rejected ' +
|
|
14
|
+
'as sourceEventId, diagnostic, and cause. A record that fails delivery on a non-transient, ' +
|
|
15
|
+
'record-specific cause (a 4xx other than 401, 403, 408, or 429, or an unexpected error) on 5 ' +
|
|
16
|
+
'consecutive flushes is quarantined into the rejected area with diagnostic ' +
|
|
17
|
+
'delivery-quarantined, so it no longer counts as pending. Network errors, timeouts, 5xx, ' +
|
|
18
|
+
'credential and environment faults stay pending. failures lists each record that failed ' +
|
|
19
|
+
'this flush as sourceEventId, cause (network, http-5xx, missing-env:NAME, and similar, ' +
|
|
20
|
+
'never a message or URL), optional httpStatus and code, and attempts. diagnostic stays ' +
|
|
21
|
+
'the summary of the flush.', IDEMPOTENT_ADDITIVE),
|
|
22
|
+
tool('outbox_prune_rejected', 'Deletes rejected records (permanent rejections and quarantined records) from the worktree ' +
|
|
23
|
+
'outbox that were last written at least olderThanDays days ago (default 7; 0 deletes ' +
|
|
24
|
+
'all). Pending records are never touched. Returns prunedCount and the remaining counts.', MUTATING, {
|
|
25
|
+
olderThanDays: {
|
|
26
|
+
type: 'integer',
|
|
27
|
+
minimum: 0,
|
|
28
|
+
description: 'Minimum age in days of rejected records to delete (default 7).',
|
|
29
|
+
},
|
|
30
|
+
}),
|
|
31
|
+
];
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { ADDITIVE, AGENT, COVERAGE, IDEMPOTENT_ADDITIVE, IDENTITY, IDENTITY_REQUIRED, ID_PATTERN, MUTATING, OUTCOMES, PARENT_SESSION_ID, READ_ONLY, VERSION, tool, } from "./tools-schema.mjs";
|
|
2
|
+
import { OUTBOX_TOOLS } from "./tools-outbox.mjs";
|
|
2
3
|
import { PR_TOOLS } from "./tools-pr.mjs";
|
|
3
4
|
import { RETROSPECTIVE_TOOLS } from "./tools-retrospective.mjs";
|
|
4
5
|
export const TOOLS = [
|
|
@@ -36,14 +37,7 @@ export const TOOLS = [
|
|
|
36
37
|
tool('journal_entries', 'Returns every entry of one session, oldest first, as JSON: { sessionId, entries }. Each ' +
|
|
37
38
|
'entry is exactly as the blackboard returns it ({ sessionId, createdAt, data }), including ' +
|
|
38
39
|
'non-journal types such as retrospective and legacy entries without a feedback envelope.', READ_ONLY),
|
|
39
|
-
|
|
40
|
-
'pending) cover the caller sessionId only; worktreePendingCount covers every session. ' +
|
|
41
|
-
'rejectedCount (and worktreeRejectedCount) counts permanently rejected records kept aside.', READ_ONLY),
|
|
42
|
-
tool('outbox_flush', 'Delivers every retained record in the worktree outbox, whichever session wrote it, and ' +
|
|
43
|
-
'returns deliveredCount for the whole flush. pendingCount and status cover the remaining ' +
|
|
44
|
-
'records of the caller sessionId; worktreePendingCount covers every session. ' +
|
|
45
|
-
'A record with a permanent rejection moves to the rejected area and is listed in rejected ' +
|
|
46
|
-
'as sourceEventId and diagnostic.', IDEMPOTENT_ADDITIVE),
|
|
40
|
+
...OUTBOX_TOOLS,
|
|
47
41
|
tool('session_ensure', 'Idempotently creates a session, or verifies an existing one has the same identity. Child or ' +
|
|
48
42
|
"worker sessions must pass their orchestrator's session id as parentSessionId.", IDEMPOTENT_ADDITIVE, IDENTITY, IDENTITY_REQUIRED),
|
|
49
43
|
...RETROSPECTIVE_TOOLS,
|
package/docs/mcp-server.md
CHANGED
|
@@ -72,20 +72,21 @@ Every tool takes an explicit `sessionId` (`^[A-Za-z0-9._:-]+$`, at most 256 char
|
|
|
72
72
|
server never infers, and an optional `worktree`. Unknown arguments are rejected. Failures come back
|
|
73
73
|
as MCP tool errors (`isError: true`) with an actionable message rather than crashing the server.
|
|
74
74
|
|
|
75
|
-
| Tool
|
|
76
|
-
|
|
|
77
|
-
| `journal_append`
|
|
78
|
-
| `journal_entries`
|
|
79
|
-
| `outbox_status`
|
|
80
|
-
| `outbox_flush`
|
|
81
|
-
| `
|
|
82
|
-
| `
|
|
83
|
-
| `
|
|
84
|
-
| `
|
|
85
|
-
| `
|
|
86
|
-
| `
|
|
87
|
-
| `
|
|
88
|
-
| `
|
|
75
|
+
| Tool | Arguments besides `sessionId` and `worktree` | Returns |
|
|
76
|
+
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
77
|
+
| `journal_append` | `parentSessionId`, `agent`, `version`, `mode` (`interactive` or `autonomous`), `markdown`, `sourceEventId`, `workOutcome`, `repositories`, `feedbackCoverage`, optional `category` | `sessionId`, `timestamp`, delivery `status` (`delivered` with a verified receipt, or `pending`), `pendingCount`, `worktreePendingCount` |
|
|
78
|
+
| `journal_entries` | none | `sessionId` and `entries`, every entry oldest first |
|
|
79
|
+
| `outbox_status` | none | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`, `failures` and `rejected` (when any) |
|
|
80
|
+
| `outbox_flush` | none | `sessionId`, `status`, `pendingCount`, `worktreePendingCount`, `rejectedCount`, `worktreeRejectedCount`, `deliveredCount`, `rejected` and `failures` (when any) |
|
|
81
|
+
| `outbox_prune_rejected` | `olderThanDays` (integer, default 7; 0 prunes all) | `sessionId`, `prunedCount`, and the counts |
|
|
82
|
+
| `session_ensure` | `parentSessionId`, `agent`, `version` | `sessionId`, `status` (`created` or `exists`), `archived` |
|
|
83
|
+
| `retrospective_check` | optional `sourceEventId` | `sessionId`, `saved`, `entries` (`sourceEventId`, `timestamp`, `issues`, `prs` of each retrospective, oldest first) |
|
|
84
|
+
| `retrospective_save` | `parentSessionId`, `agent`, `version`, `mode`, `workOutcome`, `feedbackCoverage`, exactly one of `markdown` or `compose`, optional `repositories`, `sourceEventId`, `category`, `dryRun`, `knownSensitiveValues` (markdown only); or `previewToken` with identity, `mode` and `sourceEventId` | as `journal_append` plus `policy.warnings`; with `dryRun`, `markdown`, `previewToken` and `policy.warnings` |
|
|
85
|
+
| `snapshot_export` | optional `agent`, `version`, `parentSessionId`, `data`, `dataArrayContains`, `inactiveForHours` | `sessionId`, `path`, `counts`, `checksum`, `manifest`, `cleanupToken` |
|
|
86
|
+
| `snapshot_partition` | `cleanupToken`, optional `checksum`, `counts`, `maxSessions`, `maxBytes` | `sessionId`, `directory`, `partitions` (`path`, `counts`, `checksum`, `manifest` of each) |
|
|
87
|
+
| `snapshot_archive` | `cleanupToken`, `sessionIds` (1 to 100) | `sessionId`, `archived`, `skipped` (`sessionId`, `reason`; never entry content) |
|
|
88
|
+
| `snapshot_cleanup` | one of `cleanupToken` or `recoveryDirectory` | `sessionId`, `cleaned: true` |
|
|
89
|
+
| `session_archive` | none | `sessionId`, `archived: true` |
|
|
89
90
|
|
|
90
91
|
`journal_append` validates the whole feedback envelope with `validateFeedbackEnvelope` before
|
|
91
92
|
anything is written, so a missing required field writes nothing. It returns the verified read-back
|
|
@@ -134,7 +135,19 @@ worktree, whichever session wrote it, so its `deliveredCount` covers the whole f
|
|
|
134
135
|
or during `outbox_flush`, moves the record out of the pending set into the outbox's rejected area,
|
|
135
136
|
keeping its content. `rejectedCount` and `worktreeRejectedCount` report those records, and a
|
|
136
137
|
corrected retry with the same `sourceEventId` is accepted. `outbox_flush` also returns
|
|
137
|
-
`rejected: [{ sourceEventId, diagnostic }]` for what it moved
|
|
138
|
+
`rejected: [{ sourceEventId, diagnostic, cause }]` for what it moved, and the stored rejection keeps
|
|
139
|
+
that diagnostic and cause. A record that fails to deliver reports its non-secret cause, as
|
|
140
|
+
`failures: [{ sourceEventId, cause, httpStatus?, code?, attempts }]` on `outbox_flush` (this flush)
|
|
141
|
+
and `outbox_status` (the last failed flush of each pending record). `cause` is a closed vocabulary
|
|
142
|
+
(`network`, `timeout`, `http-5xx`, `http-4xx`, `http-401`, `http-403`, `http-408`, `http-429`,
|
|
143
|
+
`missing-env:<NAME>`, `invalid-url`, `client-unavailable`, `error:<ClassName>`), never a message,
|
|
144
|
+
URL, token, or response body; `diagnostic` stays the summary. A record that fails with the same
|
|
145
|
+
record-specific cause (`http-4xx` other than 401, 403, 408, 429, or `error:*`) on 5 consecutive
|
|
146
|
+
flushes is quarantined into the rejected area with diagnostic `delivery-quarantined`, so it no
|
|
147
|
+
longer counts as pending. Network errors, timeouts, 5xx, throttling, credential, and environment
|
|
148
|
+
faults never quarantine. The attempt count is stored with the record. `outbox_status` also lists
|
|
149
|
+
each kept rejection as `rejected`, and `outbox_prune_rejected` deletes rejected records last
|
|
150
|
+
written at least `olderThanDays` days ago. Flushing an empty
|
|
138
151
|
outbox does not create the directory. `snapshot_export` never accepts a destination: the
|
|
139
152
|
`agent-blackboard` client chooses a private file and returns its path. `session_archive` and
|
|
140
153
|
`snapshot_archive` are the destructive tools; archived metadata is immutable, while entries stay
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "vouchington-tooling",
|
|
3
|
-
"version": "3.0
|
|
3
|
+
"version": "3.1.0",
|
|
4
4
|
"description": "Vouchington CLI and extractable tooling libraries.",
|
|
5
5
|
"homepage": "https://github.com/vouchington/vouchington-tooling/tree/main/packages/vouchington-tooling#readme",
|
|
6
6
|
"bugs": {
|
|
Binary file
|
|
@@ -14,7 +14,8 @@ record. Read local `AGENTS.md` for the provider, credential, retention, and
|
|
|
14
14
|
subagent-identity rules.
|
|
15
15
|
|
|
16
16
|
Journal operations are tools of the `vouchington-tooling` MCP server (`vouchington mcp`):
|
|
17
|
-
`journal_append`, `journal_entries`, `outbox_status`, `outbox_flush`, `
|
|
17
|
+
`journal_append`, `journal_entries`, `outbox_status`, `outbox_flush`, `outbox_prune_rejected`,
|
|
18
|
+
`session_ensure`,
|
|
18
19
|
`snapshot_export`, `snapshot_archive`, and `session_archive`. Harnesses name them differently, so match the bare tool
|
|
19
20
|
name: `mcp__vouchington-tooling__<tool>`, `mcp__vouchington_tooling__<tool>` (the hyphen becomes an
|
|
20
21
|
underscore), or `vouchington-tooling__<tool>` reached through a `search_tool` and `use_tool` pair,
|
|
@@ -35,6 +36,14 @@ Every call takes an exact `sessionId`, never inferred, whose meaning depends on
|
|
|
35
36
|
of the pending set, not retained: `rejectedCount` and `worktreeRejectedCount` count the kept copies,
|
|
36
37
|
`outbox_flush` reports them as `rejected` (`sourceEventId` and `diagnostic`), and a corrected retry
|
|
37
38
|
with the same `sourceEventId` is accepted.
|
|
39
|
+
`outbox_flush` and `outbox_status` report why a pending record failed as `failures`
|
|
40
|
+
(`sourceEventId`, a non-secret `cause` such as `network`, `http-5xx`, or `missing-env:NAME`,
|
|
41
|
+
optional `httpStatus`, and `attempts`), so a stuck record is diagnosable without reading files.
|
|
42
|
+
A record that fails on the same record-specific cause (a 4xx other than 401, 403, 408, 429) for
|
|
43
|
+
5 consecutive flushes is quarantined into the rejected area as `delivery-quarantined` and no
|
|
44
|
+
longer counts as pending; transient and environment causes never quarantine. Rejections keep their
|
|
45
|
+
diagnostic, listed by `outbox_status` as `rejected`; `outbox_prune_rejected` (`olderThanDays`,
|
|
46
|
+
default 7, 0 for all) deletes the old ones.
|
|
38
47
|
|
|
39
48
|
Every call may take `worktree`, the absolute path of a worktree of the current repository (the
|
|
40
49
|
launch worktree by default). Writing or retrying an entry needs no provider skill, temporary file,
|
package/skills/manifest.json
CHANGED
|
@@ -4,57 +4,57 @@
|
|
|
4
4
|
{
|
|
5
5
|
"name": "blackboard",
|
|
6
6
|
"plugin": "vouchington-workflow",
|
|
7
|
-
"pluginVersion": "0.23.
|
|
7
|
+
"pluginVersion": "0.23.3",
|
|
8
8
|
"path": "blackboard/SKILL.md"
|
|
9
9
|
},
|
|
10
10
|
{
|
|
11
11
|
"name": "organize-github-issues",
|
|
12
12
|
"plugin": "vouchington-workflow",
|
|
13
|
-
"pluginVersion": "0.23.
|
|
13
|
+
"pluginVersion": "0.23.3",
|
|
14
14
|
"path": "organize-github-issues/SKILL.md"
|
|
15
15
|
},
|
|
16
16
|
{
|
|
17
17
|
"name": "pr-description",
|
|
18
18
|
"plugin": "vouchington-workflow",
|
|
19
|
-
"pluginVersion": "0.23.
|
|
19
|
+
"pluginVersion": "0.23.3",
|
|
20
20
|
"path": "pr-description/SKILL.md"
|
|
21
21
|
},
|
|
22
22
|
{
|
|
23
23
|
"name": "retrospective",
|
|
24
24
|
"plugin": "vouchington-workflow",
|
|
25
|
-
"pluginVersion": "0.23.
|
|
25
|
+
"pluginVersion": "0.23.3",
|
|
26
26
|
"path": "retrospective/SKILL.md"
|
|
27
27
|
},
|
|
28
28
|
{
|
|
29
29
|
"name": "retrospective-distill",
|
|
30
30
|
"plugin": "vouchington-workflow",
|
|
31
|
-
"pluginVersion": "0.23.
|
|
31
|
+
"pluginVersion": "0.23.3",
|
|
32
32
|
"path": "retrospective-distill/SKILL.md"
|
|
33
33
|
},
|
|
34
34
|
{
|
|
35
35
|
"name": "review-github-issue-taxonomy",
|
|
36
36
|
"plugin": "vouchington-workflow",
|
|
37
|
-
"pluginVersion": "0.23.
|
|
37
|
+
"pluginVersion": "0.23.3",
|
|
38
38
|
"path": "review-github-issue-taxonomy/SKILL.md",
|
|
39
39
|
"prerequisites": ["organize-github-issues"]
|
|
40
40
|
},
|
|
41
41
|
{
|
|
42
42
|
"name": "triage-loop",
|
|
43
43
|
"plugin": "vouchington-workflow",
|
|
44
|
-
"pluginVersion": "0.23.
|
|
44
|
+
"pluginVersion": "0.23.3",
|
|
45
45
|
"path": "triage-loop/SKILL.md"
|
|
46
46
|
},
|
|
47
47
|
{
|
|
48
48
|
"name": "triage-prs",
|
|
49
49
|
"plugin": "vouchington-workflow",
|
|
50
|
-
"pluginVersion": "0.23.
|
|
50
|
+
"pluginVersion": "0.23.3",
|
|
51
51
|
"path": "triage-prs/SKILL.md",
|
|
52
52
|
"prerequisites": ["pr-description", "retrospective"]
|
|
53
53
|
},
|
|
54
54
|
{
|
|
55
55
|
"name": "triage-sweep",
|
|
56
56
|
"plugin": "vouchington-workflow",
|
|
57
|
-
"pluginVersion": "0.23.
|
|
57
|
+
"pluginVersion": "0.23.3",
|
|
58
58
|
"path": "triage-sweep/SKILL.md",
|
|
59
59
|
"prerequisites": [
|
|
60
60
|
"triage-loop",
|
|
@@ -20,7 +20,9 @@ Use when completed retrospectives or journals should become durable follow-up wo
|
|
|
20
20
|
`git worktree list` reports, passing each path as `worktree`, and stop if any reports a
|
|
21
21
|
`worktreePendingCount` above 0. Use the worktree count, never `pendingCount` or `status`, which
|
|
22
22
|
cover only the caller's own session: the sessions to distill belong to other agents, and an
|
|
23
|
-
archived session refuses later delivery, so a retained record would never be distilled.
|
|
23
|
+
archived session refuses later delivery, so a retained record would never be distilled. A record
|
|
24
|
+
that repeatedly fails delivery is quarantined by `outbox_flush` into the rejected area
|
|
25
|
+
(`delivery-quarantined`), so it stops counting as pending; report any such rejection. Outboxes
|
|
24
26
|
in removed worktrees or on other machines cannot be drained this way, so apply the age cutoffs under
|
|
25
27
|
[session shapes](#session-shapes-and-eligibility) to give them time to deliver. Leave in-progress sessions intact. If a search
|
|
26
28
|
for `snapshot_export` (the tool names carry a harness prefix, see the
|