@a-t-h-i/bot-lobby 0.6.79 → 0.7.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/THIRD_PARTY_NOTICES.md +0 -1
- package/package.json +1 -1
- package/prompts/lobby-chat.md +1 -1
- package/prompts/master.md +15 -2
- package/prompts/panel.md +4 -4
- package/prompts/planner.md +2 -2
- package/prompts/worker.md +6 -1
- package/src/ask/tool.ts +1 -1
- package/src/classifier/effort.ts +5 -0
- package/src/classifier/files.ts +7 -0
- package/src/classifier/knowledge.ts +88 -0
- package/src/classifier/lobby.ts +1 -1
- package/src/desk/board-client.ts +1 -1
- package/src/desk/board.ts +1 -1
- package/src/execution/assignment.ts +77 -1
- package/src/execution/delegation.ts +80 -27
- package/src/execution/verification.ts +216 -0
- package/src/knowledge/catalog-tools.ts +1 -1
- package/src/knowledge/catalogue.ts +21 -6
- package/src/knowledge/compactor.ts +212 -5
- package/src/knowledge/oracle-digest.ts +2 -2
- package/src/knowledge/paths.ts +9 -0
- package/src/knowledge/repo-map.ts +1 -0
- package/src/knowledge/retrieval.ts +8 -2
- package/src/knowledge/store.ts +68 -14
- package/src/lobby/chat-agents.ts +57 -8
- package/src/lobby/feed.ts +2 -2
- package/src/lobby/knowledge.ts +3 -3
- package/src/lobby/pi-commands.ts +1 -1
- package/src/lobby/planner.ts +6 -6
- package/src/lobby/prompts.ts +2 -2
- package/src/lobby/runtime.ts +4 -4
- package/src/lobby/service.ts +88 -51
- package/src/master/master.ts +87 -14
- package/src/master/scout-prefetch.ts +14 -1
- package/src/pi/commands.ts +28 -10
- package/src/pi/events.ts +21 -10
- package/src/pi/owner.ts +21 -3
- package/src/pi/start-task.ts +9 -6
- package/src/pi/switch-pending.ts +24 -0
- package/src/pi/tools.ts +14 -0
- package/src/roles/worker.ts +33 -3
- package/src/schemas/configuration.ts +9 -0
- package/src/schemas/task.ts +18 -0
- package/src/schemas/verification.ts +38 -0
- package/src/state/metrics.ts +32 -2
- package/src/webui/api/knowledge.ts +1 -1
- package/src/webui/api/tasks.ts +1 -1
- package/src/webui/dev/fake-service.ts +7 -7
- package/src/workflow/track.ts +65 -3
- package/src/workflow/workflow.ts +142 -17
- package/webui/dist/assets/{CodeSurface-DZdLN-w3.js → CodeSurface-FHm02AXI.js} +1 -1
- package/webui/dist/assets/{TerminalView-CRwPTCho.js → TerminalView-Be3q2ej_.js} +1 -1
- package/webui/dist/assets/{index-CiUnrnfa.js → index-B_7Iioqo.js} +45 -45
- package/webui/dist/assets/index-DPP8sEwW.css +2 -0
- package/webui/dist/build.json +59 -59
- package/webui/dist/index.html +2 -2
- package/webui/dist/assets/index-CTNZ-wc_.css +0 -2
|
@@ -0,0 +1,216 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The verification engine: runs a project's final checks (typecheck, unit
|
|
3
|
+
* tests, build, browser fixtures) through one shared path so completion,
|
|
4
|
+
* `scripts/verify-final.ts` and any concurrent caller execute each check once
|
|
5
|
+
* per fingerprint. Heavy checks run here only — never between intermediate
|
|
6
|
+
* worker steps. Keys cover sources, configuration, dependencies, commands and
|
|
7
|
+
* execution environment, so a recorded pass can be reused while nothing it
|
|
8
|
+
* covered changed, and browser fixtures always consume freshly built assets:
|
|
9
|
+
* `web:check` depends on `web:build` and keys on the built `build.json`.
|
|
10
|
+
*/
|
|
11
|
+
import { createHash } from "node:crypto";
|
|
12
|
+
import { spawn, spawnSync, type ChildProcess } from "node:child_process";
|
|
13
|
+
import { existsSync, readdirSync, statSync } from "node:fs";
|
|
14
|
+
import { join } from "node:path";
|
|
15
|
+
import { readFileSync } from "node:fs";
|
|
16
|
+
import type { VerificationReport, VerifyResult, VerifyState } from "../schemas/verification.ts";
|
|
17
|
+
import { POSIX, signalGroup } from "./pi-runner.ts";
|
|
18
|
+
|
|
19
|
+
/** What a check prints; injected so tests run without spawning anything. */
|
|
20
|
+
export type VerifyExec = (command: string, args: readonly string[], options: { cwd: string; timeoutMs: number; signal?: AbortSignal }) => Promise<{ code: number | null; output: string; timedOut: boolean }>;
|
|
21
|
+
|
|
22
|
+
export const DEFAULT_TIMEOUT_MS = 30 * 60_000;
|
|
23
|
+
|
|
24
|
+
export interface VerifyCheck {
|
|
25
|
+
id: string;
|
|
26
|
+
command: string;
|
|
27
|
+
args: readonly string[];
|
|
28
|
+
timeoutMs: number;
|
|
29
|
+
/** Files and directories (walked, without node_modules and dist) that key the result. */
|
|
30
|
+
inputs: readonly string[];
|
|
31
|
+
/** Ids that must pass first; a failed dependency makes this check unavailable. */
|
|
32
|
+
dependsOn?: readonly string[];
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
function killVerificationTree(child: ChildProcess): void {
|
|
36
|
+
if (POSIX) signalGroup(child, "SIGKILL");
|
|
37
|
+
else if (child.pid !== undefined) spawnSync("taskkill", ["/PID", String(child.pid), "/T", "/F"], { timeout: 5_000, windowsHide: true });
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function captureOutput(child: ChildProcess): () => string {
|
|
41
|
+
let output = "";
|
|
42
|
+
const read = (part: Buffer) => { output = (output + part.toString()).slice(-200_000); };
|
|
43
|
+
child.stdout?.on("data", read);
|
|
44
|
+
child.stderr?.on("data", read);
|
|
45
|
+
return () => output;
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** Spawn a check the way the engine runs commands; kill its tree on timeout or abort. */
|
|
49
|
+
export const execVerify: VerifyExec = (command, args, options) => new Promise((resolve) => {
|
|
50
|
+
if (options.signal?.aborted) { resolve({ code: null, output: "", timedOut: false }); return; }
|
|
51
|
+
const child = spawn(command, args, { cwd: options.cwd, env: process.env, detached: POSIX, stdio: ["ignore", "pipe", "pipe"] });
|
|
52
|
+
const output = captureOutput(child);
|
|
53
|
+
let done = false;
|
|
54
|
+
let timedOut = false;
|
|
55
|
+
const abort = () => killVerificationTree(child);
|
|
56
|
+
const finish = (code: number | null) => {
|
|
57
|
+
if (done) return;
|
|
58
|
+
done = true;
|
|
59
|
+
clearTimeout(timer);
|
|
60
|
+
options.signal?.removeEventListener("abort", abort);
|
|
61
|
+
resolve({ code, output: output(), timedOut });
|
|
62
|
+
};
|
|
63
|
+
const timer = setTimeout(() => { timedOut = true; killVerificationTree(child); }, options.timeoutMs).unref();
|
|
64
|
+
options.signal?.addEventListener("abort", abort, { once: true });
|
|
65
|
+
child.on("error", () => finish(null));
|
|
66
|
+
child.on("close", finish);
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
/** Directories never walked for fingerprints: outputs and installed packages. */
|
|
70
|
+
const SKIP = new Set(["node_modules", "dist", ".git"]);
|
|
71
|
+
|
|
72
|
+
function walk(top: string, dir: string, out: string[]): void {
|
|
73
|
+
let entries;
|
|
74
|
+
try {
|
|
75
|
+
entries = readdirSync(join(top, dir), { withFileTypes: true });
|
|
76
|
+
} catch {
|
|
77
|
+
return;
|
|
78
|
+
}
|
|
79
|
+
for (const entry of entries) {
|
|
80
|
+
if (entry.isDirectory()) {
|
|
81
|
+
if (!SKIP.has(entry.name)) walk(top, join(dir, entry.name), out);
|
|
82
|
+
} else if (entry.isFile()) out.push(join(dir, entry.name));
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** Inputs as they stand: a content hash per file (an edit that restores size and mtime still changes it), gone files keyed as gone. */
|
|
87
|
+
export function checkFingerprint(top: string, check: VerifyCheck): string {
|
|
88
|
+
const hash = createHash("sha256");
|
|
89
|
+
hash.update(JSON.stringify([check.command, check.args, process.version, process.platform, process.arch,
|
|
90
|
+
Object.entries(process.env).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)]));
|
|
91
|
+
const files: string[] = [];
|
|
92
|
+
for (const input of check.inputs) {
|
|
93
|
+
const full = join(top, input);
|
|
94
|
+
if (!existsSync(full)) files.push(input);
|
|
95
|
+
else if (statSync(full).isDirectory()) walk(top, input, files);
|
|
96
|
+
else files.push(input);
|
|
97
|
+
}
|
|
98
|
+
for (const file of [...new Set(files)].sort()) {
|
|
99
|
+
let stamp = "gone";
|
|
100
|
+
try {
|
|
101
|
+
stamp = createHash("sha256").update(readFileSync(join(top, file))).digest("hex");
|
|
102
|
+
} catch {
|
|
103
|
+
// A deleted or unreadable input keys as gone.
|
|
104
|
+
}
|
|
105
|
+
hash.update(`\0${file}\0${stamp}`);
|
|
106
|
+
}
|
|
107
|
+
return hash.digest("hex").slice(0, 24);
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
export interface FinalCheckSpec {
|
|
111
|
+
script: string;
|
|
112
|
+
check: Omit<VerifyCheck, "command" | "args">;
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** The checks a project's own scripts define, in run order; absent scripts are not applicable. */
|
|
116
|
+
export const FINAL_CHECK_SPECS: readonly FinalCheckSpec[] = [
|
|
117
|
+
{ script: "typecheck", check: { id: "typecheck", timeoutMs: 10 * 60_000, inputs: ["package.json", "package-lock.json", "tsconfig.json", "src", "webui/tsconfig.json", "webui/src"] } },
|
|
118
|
+
{ script: "test", check: { id: "test", timeoutMs: 60 * 60_000, inputs: ["package.json", "package-lock.json", "tsconfig.json", "src", "test"] } },
|
|
119
|
+
{ script: "web:build", check: { id: "web:build", timeoutMs: 10 * 60_000, inputs: ["package.json", "package-lock.json", "webui", "src/lobby/prompts.ts", "src/webui/protocol.ts"] } },
|
|
120
|
+
{ script: "web:check", check: { id: "web:check", timeoutMs: 60 * 60_000, inputs: ["package.json", "package-lock.json", "playwright.config.ts", "test/web", "webui/dist/build.json", "src"], dependsOn: ["web:build"] } },
|
|
121
|
+
];
|
|
122
|
+
|
|
123
|
+
/** Read a project's final checks from its package.json scripts. */
|
|
124
|
+
export function finalChecks(top: string): VerifyCheck[] {
|
|
125
|
+
let scripts: Record<string, string> | undefined;
|
|
126
|
+
try {
|
|
127
|
+
scripts = JSON.parse(readFileSync(join(top, "package.json"), "utf8")).scripts;
|
|
128
|
+
} catch {
|
|
129
|
+
return [];
|
|
130
|
+
}
|
|
131
|
+
return FINAL_CHECK_SPECS.flatMap((spec) => {
|
|
132
|
+
const script = scripts?.[spec.script];
|
|
133
|
+
return typeof script === "string" && script.trim() ? [{ ...spec.check, command: "npm", args: ["run", spec.script] }] : [];
|
|
134
|
+
});
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
const inFlight = new Map<string, Promise<VerifyResult>>();
|
|
138
|
+
|
|
139
|
+
function resultOf(id: string, state: VerifyState, summary: string, fingerprint: string, ms = 0, output?: string, reused = false): VerifyResult {
|
|
140
|
+
return { id, state, at: new Date().toISOString(), ms, fingerprint, summary, ...(output ? { output } : {}), ...(reused ? { reused: true } : {}) };
|
|
141
|
+
}
|
|
142
|
+
|
|
143
|
+
/** Run one check: single-flight per fingerprint, so concurrent callers share the work. */
|
|
144
|
+
function runCheck(top: string, check: VerifyCheck, exec: VerifyExec, signal: AbortSignal | undefined): Promise<VerifyResult> {
|
|
145
|
+
const fingerprint = checkFingerprint(top, check);
|
|
146
|
+
const key = `${top}:${check.id}:${fingerprint}`;
|
|
147
|
+
const existing = inFlight.get(key);
|
|
148
|
+
if (existing) return existing;
|
|
149
|
+
const started = Date.now();
|
|
150
|
+
const run = exec(check.command, check.args, { cwd: top, timeoutMs: check.timeoutMs, ...(signal ? { signal } : {}) })
|
|
151
|
+
.then((outcome): VerifyResult => {
|
|
152
|
+
const ms = Date.now() - started;
|
|
153
|
+
if (signal?.aborted) return resultOf(check.id, "cancelled", `${check.id} was cancelled; a cancelled check is not a pass — complete again to re-run it`, fingerprint, ms);
|
|
154
|
+
if (outcome.timedOut) return resultOf(check.id, "fail", `${check.id} timed out after ${Math.round(check.timeoutMs / 60_000)} min`, fingerprint, ms, outcome.output.slice(-4_000));
|
|
155
|
+
if (outcome.code === 0) return resultOf(check.id, "pass", `${check.id} passed`, fingerprint, ms);
|
|
156
|
+
if (outcome.code === null) return resultOf(check.id, "unavailable", `${check.id} could not run (command not found or terminated); an unavailable check is not a pass`, fingerprint, ms, outcome.output.slice(-4_000));
|
|
157
|
+
return resultOf(check.id, "fail", `${check.id} failed with exit ${outcome.code}`, fingerprint, ms, outcome.output.slice(-4_000));
|
|
158
|
+
})
|
|
159
|
+
.catch((error: unknown) => resultOf(check.id, "unavailable", `${check.id} could not run: ${error instanceof Error ? error.message : String(error)}`, fingerprint, Date.now() - started))
|
|
160
|
+
.finally(() => { if (inFlight.get(key) === run) inFlight.delete(key); });
|
|
161
|
+
inFlight.set(key, run);
|
|
162
|
+
return run;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
export interface VerificationInput {
|
|
166
|
+
top: string;
|
|
167
|
+
checks: readonly VerifyCheck[];
|
|
168
|
+
/** The task's last report: a pass whose fingerprint still matches is reused, not re-run. */
|
|
169
|
+
previous?: VerificationReport;
|
|
170
|
+
exec?: VerifyExec;
|
|
171
|
+
signal?: AbortSignal;
|
|
172
|
+
now?: () => Date;
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/** Run the final checks once per fingerprint; the report refuses nothing itself — completion does. */
|
|
176
|
+
export async function runVerification(input: VerificationInput): Promise<VerificationReport> {
|
|
177
|
+
const exec = input.exec ?? execVerify;
|
|
178
|
+
const results: VerifyResult[] = [];
|
|
179
|
+
for (const check of input.checks) {
|
|
180
|
+
const fingerprint = checkFingerprint(input.top, check);
|
|
181
|
+
const failedDependency = check.dependsOn?.find((dep) => results.find((result) => result.id === dep)?.state !== "pass");
|
|
182
|
+
if (failedDependency) {
|
|
183
|
+
results.push(resultOf(check.id, "unavailable", `${check.id} was not run: ${failedDependency} did not pass`, fingerprint));
|
|
184
|
+
continue;
|
|
185
|
+
}
|
|
186
|
+
if (input.signal?.aborted) {
|
|
187
|
+
results.push(resultOf(check.id, "cancelled", `${check.id} was cancelled before execution; a cancelled check is not a pass`, fingerprint));
|
|
188
|
+
continue;
|
|
189
|
+
}
|
|
190
|
+
const prior = input.previous?.results.find((result) => result.id === check.id);
|
|
191
|
+
if (!input.signal?.aborted && prior?.state === "pass" && prior.fingerprint === fingerprint) {
|
|
192
|
+
results.push({ ...prior, at: (input.now ?? (() => new Date()))().toISOString(), reused: true });
|
|
193
|
+
} else results.push(await runCheck(input.top, check, exec, input.signal));
|
|
194
|
+
}
|
|
195
|
+
invalidateChangedInputs(input.top, input.checks, results);
|
|
196
|
+
const state = results.length === 0 || results.every((result) => result.state === "pass") ? "passing" : "failing";
|
|
197
|
+
const fingerprint = createHash("sha256").update(results.map((result) => `${result.id}:${result.fingerprint}:${result.state}`).join("\n")).digest("hex").slice(0, 24);
|
|
198
|
+
return { at: (input.now ?? (() => new Date()))().toISOString(), state, fingerprint, results, ...(results.length === 0 ? { note: "no applicable checks: the project defines none of typecheck, test, web:build, web:check" } : {}) };
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
/** Checks cannot pass on inputs that changed while this run was in flight. */
|
|
202
|
+
function invalidateChangedInputs(top: string, checks: readonly VerifyCheck[], results: VerifyResult[]): void {
|
|
203
|
+
for (const result of results) {
|
|
204
|
+
const check = checks.find((entry) => entry.id === result.id)!;
|
|
205
|
+
if (result.state !== "pass" || result.fingerprint === checkFingerprint(top, check)) continue;
|
|
206
|
+
result.state = "fail";
|
|
207
|
+
result.summary = `${result.id} inputs changed during verification; run it again on the current tree`;
|
|
208
|
+
delete result.reused;
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/** One line per check, failures with their output pointer — what to fix and how to re-verify. */
|
|
213
|
+
export function verificationSummary(report: VerificationReport): string {
|
|
214
|
+
if (report.note) return report.note;
|
|
215
|
+
return report.results.map((result) => `${result.id}: ${result.summary}${result.reused ? " (reused: unchanged since the last pass)" : ""}`).join("; ");
|
|
216
|
+
}
|
|
@@ -113,7 +113,7 @@ function registerListTool(pi: ExtensionAPI, configDir: string): void {
|
|
|
113
113
|
name: LIST_BOOKMARKS_TOOL,
|
|
114
114
|
label: "List assignment bookmarks",
|
|
115
115
|
description:
|
|
116
|
-
"List the bookmarked knowledge references selected for this task and assignment (by the classifier or the
|
|
116
|
+
"List the bookmarked knowledge references selected for this task and assignment (by the classifier or the orchestrator), with the reason each was picked and who it is for. "
|
|
117
117
|
+ "Every line is revalidated against the current catalogue and your access: stale or unauthorized references are never shown. "
|
|
118
118
|
+ "Open a reference with open_knowledge; search beyond the bookmarks with search_knowledge.",
|
|
119
119
|
parameters: Type.Object({}),
|
|
@@ -20,9 +20,9 @@
|
|
|
20
20
|
* land through a unique temp file and an atomic rename.
|
|
21
21
|
*/
|
|
22
22
|
import { createHash, randomUUID } from "node:crypto";
|
|
23
|
-
import { mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
|
|
24
|
-
import { dirname, join, sep } from "node:path";
|
|
25
|
-
import { AGENT_DIR_NAMES, KNOWLEDGE_FILES, knowledgeDir, type KnowledgeAgent } from "./paths.ts";
|
|
23
|
+
import { mkdirSync, readdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
|
|
24
|
+
import { basename, dirname, join, sep } from "node:path";
|
|
25
|
+
import { AGENT_DIR_NAMES, KNOWLEDGE_FILES, historyDir, knowledgeDir, type KnowledgeAgent } from "./paths.ts";
|
|
26
26
|
import { parseEntries, type EntryKind } from "./edit.ts";
|
|
27
27
|
import { fileNotesPath, readFileNotes } from "./file-notes.ts";
|
|
28
28
|
|
|
@@ -63,7 +63,7 @@ export function generationOfRef(ref: string): string | undefined {
|
|
|
63
63
|
const SECRET_PATTERN = /(api[-_]?key|secret|password|passwd|credential|private[- ]key)\s*[:=]/i;
|
|
64
64
|
|
|
65
65
|
export type CatalogueKind = "knowledge" | "standard" | "decision" | "completed" | "finding";
|
|
66
|
-
export type CatalogueOrigin = "knowledge-file" | "file-note";
|
|
66
|
+
export type CatalogueOrigin = "knowledge-file" | "knowledge-history" | "file-note";
|
|
67
67
|
export type CatalogueScope = "project" | "task";
|
|
68
68
|
export type Freshness = "current" | "changed" | "stale";
|
|
69
69
|
export type Coverage = "complete" | "partial" | "stale" | "unavailable";
|
|
@@ -213,8 +213,10 @@ function kindOf(file: string): CatalogueKind {
|
|
|
213
213
|
|
|
214
214
|
/**
|
|
215
215
|
* The accepted sources: every agent's four knowledge files in every data
|
|
216
|
-
* tree (the live one and the read-only pre-rename ones)
|
|
217
|
-
*
|
|
216
|
+
* tree (the live one and the read-only pre-rename ones), plus the permanent
|
|
217
|
+
* history files archiving keeps (they are searchable, never pruned).
|
|
218
|
+
* Nothing else — no repository contents, no session transcripts, no
|
|
219
|
+
* scratchpads — is indexed.
|
|
218
220
|
*/
|
|
219
221
|
export function knowledgeSourceRefs(dataRoots: readonly string[]): SourceRef[] {
|
|
220
222
|
const refs: SourceRef[] = [];
|
|
@@ -224,11 +226,24 @@ export function knowledgeSourceRefs(dataRoots: readonly string[]): SourceRef[] {
|
|
|
224
226
|
const path = canonicalSource(dataRoot, join(knowledgeDir(dataRoot, agent), file));
|
|
225
227
|
if (path) refs.push({ key: `kf:${path}`, file: path, agent, kind: kindOf(file), origin: "knowledge-file" });
|
|
226
228
|
}
|
|
229
|
+
for (const file of historyFiles(dataRoot, agent)) {
|
|
230
|
+
const path = canonicalSource(dataRoot, file);
|
|
231
|
+
if (path) refs.push({ key: `kf:${path}`, file: path, agent, kind: kindOf(basename(file)), origin: "knowledge-history" });
|
|
232
|
+
}
|
|
227
233
|
}
|
|
228
234
|
}
|
|
229
235
|
return refs;
|
|
230
236
|
}
|
|
231
237
|
|
|
238
|
+
/** The agent's archived knowledge files that exist under permanent history/, as absolute paths. */
|
|
239
|
+
function historyFiles(dataRoot: string, agent: KnowledgeAgent): string[] {
|
|
240
|
+
try {
|
|
241
|
+
return readdirSync(historyDir(dataRoot, agent)).filter((file) => KNOWLEDGE_FILES[agent].includes(file)).map((file) => join(historyDir(dataRoot, agent), file));
|
|
242
|
+
} catch {
|
|
243
|
+
return [];
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
|
|
232
247
|
/** The scouts' file notes, one source with one passage per note. */
|
|
233
248
|
export function fileNoteSourceRef(dataRoot: string | undefined): SourceRef | undefined {
|
|
234
249
|
if (!dataRoot) return undefined;
|
|
@@ -1,8 +1,12 @@
|
|
|
1
|
-
import { mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
|
|
2
|
-
import { basename, join } from "node:path";
|
|
1
|
+
import { appendFileSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
|
|
2
|
+
import { basename, dirname, join } from "node:path";
|
|
3
3
|
import type { KnowledgeAgent } from "./paths.ts";
|
|
4
|
-
import { AGENT_DIR_NAMES, KNOWLEDGE_FILES, knowledgeDir } from "./paths.ts";
|
|
5
|
-
import {
|
|
4
|
+
import { AGENT_DIR_NAMES, KNOWLEDGE_FILES, historyDir, knowledgeDir } from "./paths.ts";
|
|
5
|
+
import { refreshCatalogue } from "./catalogue.ts";
|
|
6
|
+
import { readNotes } from "./notes.ts";
|
|
7
|
+
import { pinnedEntries } from "./ledger.ts";
|
|
8
|
+
import { withFileLock } from "../desk/lock.ts";
|
|
9
|
+
import { readFirstExisting, readFileOr, writeFileAtomic } from "./store.ts";
|
|
6
10
|
|
|
7
11
|
export interface OversizedFile {
|
|
8
12
|
agent: KnowledgeAgent;
|
|
@@ -59,7 +63,210 @@ export function compactKnowledgeFile(entry: {
|
|
|
59
63
|
const stamp = (entry.now ?? new Date()).toISOString().replace(/[:.]/g, "-");
|
|
60
64
|
const archive = join(dir, `${basename(entry.file)}.${stamp}.bak`);
|
|
61
65
|
writeFileSync(archive, previous, "utf8");
|
|
62
|
-
|
|
66
|
+
writeFileAtomic(path, `${entry.content.trim()}\n`);
|
|
63
67
|
pruneArchives(dir, entry.file, Math.max(1, entry.backupCount));
|
|
64
68
|
return { archive, before: previous.length, after: entry.content.trim().length };
|
|
65
69
|
}
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Permanent, searchable history: a `history/` sibling of the rotating
|
|
73
|
+
* `archive/` backups. Backup rotation only ever prunes `archive/<Agent>/*.bak`;
|
|
74
|
+
* nothing under `history/` is pruned, so archived material stays findable.
|
|
75
|
+
* The directory itself lives in paths.ts, where the catalogue can index it.
|
|
76
|
+
*/
|
|
77
|
+
export function historyPath(dataRoot: string, agent: KnowledgeAgent, file: string): string {
|
|
78
|
+
return join(historyDir(dataRoot, agent), basename(file));
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** The material being removed, appended to permanent history under a dated heading before anything is replaced. */
|
|
82
|
+
function appendHistory(dataRoot: string, agent: KnowledgeAgent, file: string, material: string, now: Date): string {
|
|
83
|
+
const path = historyPath(dataRoot, agent, file);
|
|
84
|
+
const heading = `# Archived from ${basename(file)} · ${now.toISOString()}`;
|
|
85
|
+
withFileLock(path, () => {
|
|
86
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
87
|
+
appendFileSync(path, `\n\n${heading}\n\n${material.trim()}\n`, "utf8");
|
|
88
|
+
});
|
|
89
|
+
return path;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** A heading line with everything until the next heading of the same or higher level. */
|
|
93
|
+
interface Section {
|
|
94
|
+
heading: string;
|
|
95
|
+
body: string;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/** Split markdown into heading-led sections; leading text before the first heading is its own section. */
|
|
99
|
+
function splitIntoSections(content: string): Section[] {
|
|
100
|
+
const lines = content.split("\n");
|
|
101
|
+
const sections: Section[] = [];
|
|
102
|
+
let current: Section | undefined;
|
|
103
|
+
for (const line of lines) {
|
|
104
|
+
if (/^#{1,6} /.test(line)) {
|
|
105
|
+
if (current) sections.push(current);
|
|
106
|
+
current = { heading: line, body: "" };
|
|
107
|
+
} else if (current) {
|
|
108
|
+
current.body += `${line}\n`;
|
|
109
|
+
} else {
|
|
110
|
+
current = { heading: "", body: `${line}\n` };
|
|
111
|
+
}
|
|
112
|
+
}
|
|
113
|
+
if (current) sections.push(current);
|
|
114
|
+
return sections;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
function renderSections(sections: readonly Section[]): string {
|
|
118
|
+
return sections.map((section) => `${section.heading}\n${section.body}`.trim()).join("\n\n");
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
function normalized(text: string): string {
|
|
122
|
+
return text.replace(/\s+/g, " ").trim().toLowerCase();
|
|
123
|
+
}
|
|
124
|
+
|
|
125
|
+
/** Actual pinned entries and matching user annotations always survive. */
|
|
126
|
+
function isProtectedSection(section: Section, protectedEntries: readonly string[]): boolean {
|
|
127
|
+
const text = `${section.heading}\n${section.body}`;
|
|
128
|
+
return text.includes("> Note from the user")
|
|
129
|
+
|| protectedEntries.some((entry) => entry.trim().length > 0 && text.includes(entry));
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
/** A section that says it was superseded is clearly historical; age alone never archives. */
|
|
133
|
+
function isSuperseded(section: Section): boolean {
|
|
134
|
+
const text = `${section.heading}\n${section.body}`;
|
|
135
|
+
if (/\b(?:unresolved|pending)\b|\b(?:not(?:\s+been|\s+yet)?|never)\s+superseded\b/i.test(text)) return false;
|
|
136
|
+
return /^#{1,6}\s+Superseded(?:\s|$)/i.test(section.heading)
|
|
137
|
+
|| /^Status:\s*superseded\s*$/im.test(section.body);
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
export interface MaintenancePlan {
|
|
141
|
+
/** What stays in the active file. */
|
|
142
|
+
keep: string;
|
|
143
|
+
/** What leaves the active file for permanent history. */
|
|
144
|
+
removed: string;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* The conservative maintenance policy: only exact duplicate sections and
|
|
149
|
+
* clearly historical material (completed-task logs, sections explicitly marked
|
|
150
|
+
* superseded) leave the active file. Pinned rules, user annotations, the
|
|
151
|
+
* title section and anything ambiguous stay; age alone never archives.
|
|
152
|
+
*/
|
|
153
|
+
export function planMaintenance(file: string, content: string, protectedEntries: readonly string[] = []): MaintenancePlan {
|
|
154
|
+
const sections = splitIntoSections(content);
|
|
155
|
+
const completed = basename(file) === "completed-tasks.md";
|
|
156
|
+
const seen = new Set<string>();
|
|
157
|
+
const keep: Section[] = [];
|
|
158
|
+
const removed: Section[] = [];
|
|
159
|
+
sections.forEach((section, index) => {
|
|
160
|
+
const text = `${section.heading}\n${section.body}`;
|
|
161
|
+
const duplicate = normalized(text).length > 0 && seen.has(normalized(text));
|
|
162
|
+
seen.add(normalized(text));
|
|
163
|
+
const historical = completed ? index > 0 : isSuperseded(section);
|
|
164
|
+
if (index === 0 || isProtectedSection(section, protectedEntries) || (!duplicate && !historical)) keep.push(section);
|
|
165
|
+
else removed.push(section);
|
|
166
|
+
});
|
|
167
|
+
return { keep: renderSections(keep), removed: renderSections(removed) };
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
export type MaintenanceStatus = "maintained" | "busy" | "unchanged" | "failed";
|
|
171
|
+
|
|
172
|
+
export interface MaintenanceResult {
|
|
173
|
+
agent: KnowledgeAgent;
|
|
174
|
+
file: string;
|
|
175
|
+
status: MaintenanceStatus;
|
|
176
|
+
before: number;
|
|
177
|
+
after: number;
|
|
178
|
+
/** The permanent history entry that received the removed material. */
|
|
179
|
+
history: string;
|
|
180
|
+
error?: string;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
export interface MaintenanceEntry {
|
|
184
|
+
dataRoot: string;
|
|
185
|
+
agent: KnowledgeAgent;
|
|
186
|
+
file: string;
|
|
187
|
+
backupCount: number;
|
|
188
|
+
now?: Date;
|
|
189
|
+
/** A rewritten active file to keep (the Master's compact semantics); absent plans maintenance from the conservative policy. */
|
|
190
|
+
content?: string;
|
|
191
|
+
/** Test seam: called after the history copy is durable, before the active file is replaced. */
|
|
192
|
+
afterArchive?: () => void | Promise<void>;
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/** One maintenance run per file at a time: a second run on an in-flight file is blocked, never interleaved. */
|
|
196
|
+
const inFlight = new Set<string>();
|
|
197
|
+
|
|
198
|
+
/**
|
|
199
|
+
* Safe automatic maintenance of one knowledge file. The material being
|
|
200
|
+
* removed — the whole previous version — is written to permanent history
|
|
201
|
+
* BEFORE the active file is replaced, and the replacement itself is atomic
|
|
202
|
+
* (temp file + rename), so an interrupted run leaves either the old file or
|
|
203
|
+
* the fully-written new one, and never loses the history copy. The catalogue
|
|
204
|
+
* is refreshed afterwards; a crashed run simply re-indexes on next use.
|
|
205
|
+
*/
|
|
206
|
+
export async function maintainKnowledgeFile(entry: MaintenanceEntry): Promise<MaintenanceResult> {
|
|
207
|
+
if (!KNOWLEDGE_FILES[entry.agent].includes(entry.file)) {
|
|
208
|
+
throw new Error(`"${entry.file}" is not a knowledge file for ${entry.agent}`);
|
|
209
|
+
}
|
|
210
|
+
const key = join(entry.dataRoot, AGENT_DIR_NAMES[entry.agent], entry.file);
|
|
211
|
+
if (inFlight.has(key)) return { ...maintenanceBase(entry), status: "busy" };
|
|
212
|
+
inFlight.add(key);
|
|
213
|
+
try {
|
|
214
|
+
return await maintainSnapshot(entry);
|
|
215
|
+
} finally {
|
|
216
|
+
inFlight.delete(key);
|
|
217
|
+
}
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
function maintenanceBase(entry: MaintenanceEntry) {
|
|
221
|
+
return { agent: entry.agent, file: entry.file, before: 0, after: 0, history: historyPath(entry.dataRoot, entry.agent, entry.file) };
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
async function maintainSnapshot(entry: MaintenanceEntry): Promise<MaintenanceResult> {
|
|
225
|
+
const path = join(knowledgeDir(entry.dataRoot, entry.agent), entry.file);
|
|
226
|
+
const previous = readFileOr(path);
|
|
227
|
+
const keep = entry.content ?? planMaintenance(entry.file, previous, maintenanceProtections(entry)).keep;
|
|
228
|
+
const base = { ...maintenanceBase(entry), before: previous.length, after: keep.trim().length };
|
|
229
|
+
if (previous.trim() === keep.trim()) return { ...base, status: "unchanged" };
|
|
230
|
+
appendHistory(entry.dataRoot, entry.agent, entry.file, previous, entry.now ?? new Date());
|
|
231
|
+
await entry.afterArchive?.();
|
|
232
|
+
if (!writeFileAtomic(path, `${keep.trim()}\n`, previous)) {
|
|
233
|
+
return { ...base, after: readFileOr(path).length, status: "failed", error: "Knowledge changed during maintenance; retry on the current file." };
|
|
234
|
+
}
|
|
235
|
+
refreshMaintenanceCatalogue(entry.dataRoot);
|
|
236
|
+
return { ...base, status: "maintained" };
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
function refreshMaintenanceCatalogue(dataRoot: string): void {
|
|
240
|
+
try {
|
|
241
|
+
refreshCatalogue([dataRoot]);
|
|
242
|
+
} catch {
|
|
243
|
+
// Recoverable: the next catalogue use re-indexes the current files.
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
function maintenanceProtections(entry: MaintenanceEntry): string[] {
|
|
248
|
+
const notes = readNotes(entry.dataRoot).filter((note) => note.agent === entry.agent && note.file === entry.file);
|
|
249
|
+
return [...pinnedEntries(entry.dataRoot, entry.agent, entry.file), ...notes.map((note) => note.entry)];
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
export interface MaintenanceSchedule {
|
|
253
|
+
/** Resolves with the maintenance outcome; never rejects (a failure is a "failed" result). */
|
|
254
|
+
done: Promise<MaintenanceResult>;
|
|
255
|
+
}
|
|
256
|
+
|
|
257
|
+
/**
|
|
258
|
+
* Schedule maintenance to run after the current response, outside the
|
|
259
|
+
* response-critical path: the caller proceeds immediately, the file work
|
|
260
|
+
* happens on the next event-loop turn, and failures resolve (not reject) so
|
|
261
|
+
* an unobserved failure can never surface as an unhandled rejection.
|
|
262
|
+
*/
|
|
263
|
+
export function scheduleKnowledgeMaintenance(entry: MaintenanceEntry): MaintenanceSchedule {
|
|
264
|
+
const done = new Promise<MaintenanceResult>((resolve) => {
|
|
265
|
+
setImmediate(() => {
|
|
266
|
+
maintainKnowledgeFile(entry).then(resolve, (error: unknown) => {
|
|
267
|
+
resolve({ agent: entry.agent, file: entry.file, status: "failed", before: 0, after: 0, history: historyPath(entry.dataRoot, entry.agent, entry.file), error: error instanceof Error ? error.message : String(error) });
|
|
268
|
+
});
|
|
269
|
+
});
|
|
270
|
+
});
|
|
271
|
+
return { done };
|
|
272
|
+
}
|
|
@@ -54,13 +54,13 @@ export function shareDigest(dataRoot: string, items: readonly DigestItem[], now
|
|
|
54
54
|
const added: Partial<Record<KnowledgeAgent, number>> = {};
|
|
55
55
|
for (const item of items) {
|
|
56
56
|
const text = item.kind === "decision" ? item.text : `- ${item.text}`;
|
|
57
|
-
if (applyKnowledge({ dataRoot, agent: item.agent, kind: item.kind, text, now, by: "
|
|
57
|
+
if (applyKnowledge({ dataRoot, agent: item.agent, kind: item.kind, text, now, by: "Orchestrator", what: "filed this when it compacted its context", source: "Compaction" }).result === "added") added[item.agent] = (added[item.agent] ?? 0) + 1;
|
|
58
58
|
}
|
|
59
59
|
return added;
|
|
60
60
|
}
|
|
61
61
|
|
|
62
62
|
/** "2 for the designer, 1 for QA" */
|
|
63
63
|
export function describeShared(added: Partial<Record<KnowledgeAgent, number>>): string {
|
|
64
|
-
const names: Record<KnowledgeAgent, string> = { master: "the
|
|
64
|
+
const names: Record<KnowledgeAgent, string> = { master: "the orchestrator", designer: "the designer", backend: "backend", qa: "QA" };
|
|
65
65
|
return AGENTS.filter((agent) => added[agent]).map((agent) => `${added[agent]} for ${names[agent]}`).join(", ");
|
|
66
66
|
}
|
package/src/knowledge/paths.ts
CHANGED
|
@@ -11,6 +11,15 @@ export const AGENT_DIR_NAMES: Record<KnowledgeAgent, string> = {
|
|
|
11
11
|
qa: "QA",
|
|
12
12
|
};
|
|
13
13
|
|
|
14
|
+
/**
|
|
15
|
+
* Permanent, searchable history: a `history/` sibling of the rotating
|
|
16
|
+
* `archive/` backups. Nothing under `history/` is pruned, so archived
|
|
17
|
+
* material stays findable.
|
|
18
|
+
*/
|
|
19
|
+
export function historyDir(dataRoot: string, agent: KnowledgeAgent): string {
|
|
20
|
+
return join(dataRoot, "history", AGENT_DIR_NAMES[agent]);
|
|
21
|
+
}
|
|
22
|
+
|
|
14
23
|
/** Domain-specific standards file per agent (§21). */
|
|
15
24
|
export const STANDARDS_FILE: Record<KnowledgeAgent, string> = {
|
|
16
25
|
master: "standards.md",
|
|
@@ -225,6 +225,7 @@ export function withRepoMap(hinter: FileHinter, scope: FileScope, settings: () =
|
|
|
225
225
|
const [likely, mapped] = await Promise.all([hinter.block(query, signal, context), map]);
|
|
226
226
|
return [withoutMapped(likely, mapped), mapped].filter(Boolean).join("\n\n");
|
|
227
227
|
},
|
|
228
|
+
paths: (query, signal) => hinter.paths?.(query, signal) ?? Promise.resolve([]),
|
|
228
229
|
tools: () => hinter.tools(),
|
|
229
230
|
};
|
|
230
231
|
}
|
|
@@ -193,8 +193,14 @@ function rankEntries(entries: readonly CatalogueEntry[], allowed: Map<string, st
|
|
|
193
193
|
.map((ranked) => ranked.entry);
|
|
194
194
|
}
|
|
195
195
|
|
|
196
|
+
/** Where a reference lives: the file's name, with `history/` in front of archived material so the two never read alike. */
|
|
197
|
+
function whereOf(entry: CatalogueEntry): string {
|
|
198
|
+
const file = basename(sourceFile(entry.sourceKey));
|
|
199
|
+
return `${entry.origin === "knowledge-history" ? "history/" : ""}${file}${entry.locator.heading ? ` > ${entry.locator.heading}` : ""}`;
|
|
200
|
+
}
|
|
201
|
+
|
|
196
202
|
function formatRef(entry: CatalogueEntry, notes: readonly KnowledgeNote[], conflict?: string): string {
|
|
197
|
-
const where =
|
|
203
|
+
const where = whereOf(entry);
|
|
198
204
|
const fresh = entry.freshness === "changed" ? `changed (r${entry.revision}; verify)` : entry.freshness;
|
|
199
205
|
const conflicts = conflictIds(entry, notes);
|
|
200
206
|
const marks = [
|
|
@@ -355,7 +361,7 @@ function annotationBlock(entry: CatalogueEntry, notes: readonly KnowledgeNote[],
|
|
|
355
361
|
}
|
|
356
362
|
|
|
357
363
|
async function metadataLines(entry: CatalogueEntry, access: Access, notes: readonly KnowledgeNote[]): Promise<string[]> {
|
|
358
|
-
const where =
|
|
364
|
+
const where = whereOf(entry);
|
|
359
365
|
const conflicts = conflictIds(entry, notes);
|
|
360
366
|
const dependency = await dependencyLine(entry, access);
|
|
361
367
|
return [
|