vouchington-tooling 3.0.1 → 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/host-lock/with-host-lock-diagnostics.test-helpers.d.mts +10 -0
- package/dist/host-lock/with-host-lock-diagnostics.test-helpers.mjs +27 -0
- package/dist/host-lock/with-host-lock.test-helpers.d.mts +0 -10
- package/dist/host-lock/with-host-lock.test-helpers.mjs +7 -28
- 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
- package/skills/triage-loop/SKILL.md +71 -21
- package/skills/triage-sweep/SKILL.md +32 -11
|
@@ -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";
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
type Completion = {
|
|
2
|
+
code: number | null;
|
|
3
|
+
stderr: string;
|
|
4
|
+
};
|
|
5
|
+
export declare function assertWithLockDiagnostics({ lockRoot, lockName, guard }: {
|
|
6
|
+
lockRoot: string;
|
|
7
|
+
lockName: string;
|
|
8
|
+
guard: string;
|
|
9
|
+
}, results: Completion[], assertion: () => void): Promise<void>;
|
|
10
|
+
export {};
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import { readdir, stat } from 'node:fs/promises';
|
|
2
|
+
async function describePath(path) {
|
|
3
|
+
try {
|
|
4
|
+
await stat(path);
|
|
5
|
+
}
|
|
6
|
+
catch {
|
|
7
|
+
return 'absent';
|
|
8
|
+
}
|
|
9
|
+
const entries = await readdir(path).catch(() => undefined);
|
|
10
|
+
return entries === undefined ? 'present' : `present [${entries.join(', ')}]`;
|
|
11
|
+
}
|
|
12
|
+
// On failure, rethrows with the lock dir, guard, and both wrappers' exit codes
|
|
13
|
+
// and stderr so a recurrence of an overlapping-holders flake names the cause.
|
|
14
|
+
export async function assertWithLockDiagnostics({ lockRoot, lockName, guard }, results, assertion) {
|
|
15
|
+
try {
|
|
16
|
+
assertion();
|
|
17
|
+
}
|
|
18
|
+
catch (error) {
|
|
19
|
+
const diagnostics = [
|
|
20
|
+
`lock dir ${lockRoot}/${lockName}.lock.d: ${await describePath(`${lockRoot}/${lockName}.lock.d`)}`,
|
|
21
|
+
`reap dir: ${await describePath(`${lockRoot}/${lockName}.lock.reap.d`)}`,
|
|
22
|
+
`guard ${guard}: ${await describePath(guard)}`,
|
|
23
|
+
...results.map((result, index) => `wrapper ${index + 1}: code=${result.code} stderr=${JSON.stringify(result.stderr)}`),
|
|
24
|
+
];
|
|
25
|
+
throw new Error(`${String(error)}\n${diagnostics.join('\n')}`, { cause: error });
|
|
26
|
+
}
|
|
27
|
+
}
|
|
@@ -19,13 +19,3 @@ export declare function withFinalTimeoutProbe(home: string, assertProbe: ({ lock
|
|
|
19
19
|
stderr: string;
|
|
20
20
|
}>;
|
|
21
21
|
}) => Promise<void>): Promise<void>;
|
|
22
|
-
type Completion = {
|
|
23
|
-
code: number | null;
|
|
24
|
-
stderr: string;
|
|
25
|
-
};
|
|
26
|
-
export declare function assertWithLockDiagnostics({ lockRoot, lockName, guard }: {
|
|
27
|
-
lockRoot: string;
|
|
28
|
-
lockName: string;
|
|
29
|
-
guard: string;
|
|
30
|
-
}, results: Completion[], assertion: () => void): Promise<void>;
|
|
31
|
-
export {};
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { execFile, spawn } from 'node:child_process';
|
|
2
|
-
import { mkdtemp, mkdir,
|
|
2
|
+
import { mkdtemp, mkdir, rm, stat, writeFile } from 'node:fs/promises';
|
|
3
3
|
import { tmpdir } from 'node:os';
|
|
4
4
|
import { join } from 'node:path';
|
|
5
5
|
import { promisify } from 'node:util';
|
|
@@ -40,6 +40,11 @@ export function spawnHostLock(home, name, timeoutSeconds, command, env = {}, ext
|
|
|
40
40
|
stdio: ['ignore', 'pipe', 'pipe'],
|
|
41
41
|
});
|
|
42
42
|
}
|
|
43
|
+
// macOS Bash 3.2 (`set -m`) can race the parent and forked child both calling
|
|
44
|
+
// setpgid under CPU load and print this warning. The process group is still
|
|
45
|
+
// established by the winner, and the warning is owned by the shell, not by
|
|
46
|
+
// with-host-lock, so assertions on the wrapper's own stderr drop it.
|
|
47
|
+
const benignJobControlWarning = /^.*: (?:child )?setpgid \(\d+ to \d+\): Operation not permitted\n/gm;
|
|
43
48
|
export function completion(child) {
|
|
44
49
|
return new Promise((resolve, reject) => {
|
|
45
50
|
let stderr = '';
|
|
@@ -47,7 +52,7 @@ export function completion(child) {
|
|
|
47
52
|
stderr += String(chunk);
|
|
48
53
|
});
|
|
49
54
|
child.once('error', reject);
|
|
50
|
-
child.once('close', (code) => resolve({ code, stderr }));
|
|
55
|
+
child.once('close', (code) => resolve({ code, stderr: stderr.replace(benignJobControlWarning, '') }));
|
|
51
56
|
});
|
|
52
57
|
}
|
|
53
58
|
export async function waitForPath(path) {
|
|
@@ -122,29 +127,3 @@ exec "$HOST_LOCK_REAL_SLEEP" "$@"
|
|
|
122
127
|
await Promise.all([ownerDone, ...(contenderDone ? [contenderDone] : [])]);
|
|
123
128
|
}
|
|
124
129
|
}
|
|
125
|
-
async function describePath(path) {
|
|
126
|
-
try {
|
|
127
|
-
await stat(path);
|
|
128
|
-
}
|
|
129
|
-
catch {
|
|
130
|
-
return 'absent';
|
|
131
|
-
}
|
|
132
|
-
const entries = await readdir(path).catch(() => undefined);
|
|
133
|
-
return entries === undefined ? 'present' : `present [${entries.join(', ')}]`;
|
|
134
|
-
}
|
|
135
|
-
// On failure, rethrows with the lock dir, guard, and both wrappers' exit codes
|
|
136
|
-
// and stderr so a recurrence of an overlapping-holders flake names the cause.
|
|
137
|
-
export async function assertWithLockDiagnostics({ lockRoot, lockName, guard }, results, assertion) {
|
|
138
|
-
try {
|
|
139
|
-
assertion();
|
|
140
|
-
}
|
|
141
|
-
catch (error) {
|
|
142
|
-
const diagnostics = [
|
|
143
|
-
`lock dir ${lockRoot}/${lockName}.lock.d: ${await describePath(`${lockRoot}/${lockName}.lock.d`)}`,
|
|
144
|
-
`reap dir: ${await describePath(`${lockRoot}/${lockName}.lock.reap.d`)}`,
|
|
145
|
-
`guard ${guard}: ${await describePath(guard)}`,
|
|
146
|
-
...results.map((result, index) => `wrapper ${index + 1}: code=${result.code} stderr=${JSON.stringify(result.stderr)}`),
|
|
147
|
-
];
|
|
148
|
-
throw new Error(`${String(error)}\n${diagnostics.join('\n')}`, { cause: error });
|
|
149
|
-
}
|
|
150
|
-
}
|
|
@@ -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
|