@siuver/omp-debug-mode 0.1.4 → 0.1.6

package/src/evidence.ts

@@ -1,196 +1,325 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
-import type { DebugState, EvidenceArtifact, EvidenceMethod, EvidenceRequest } from "./state";
-
-/** Upper bound on accepted plan entries so one model reply cannot flood the gate. */
-export const MAX_EVIDENCE_REQUESTS = 12;
-
-const METHODS: readonly EvidenceMethod[] = ["agent_inspection", "runtime_probe", "user_report", "user_artifact"];
-
-export interface EvidencePlanParseResult {
-	found: boolean;
-	valid: boolean;
-	requests: EvidenceRequest[];
-	error?: string;
-}
-
-function isNonEmptyString(value: unknown): value is string {
-	return typeof value === "string" && value.trim().length > 0;
-}
-
-function isNonEmptyStringArray(value: unknown): value is string[] {
-	return Array.isArray(value) && value.length > 0 && value.every(isNonEmptyString);
-}
-
-function hasOnlyUniqueValues(values: readonly string[]): boolean {
-	return new Set(values).size === values.length;
-}
-
-/**
- * Parse the `<evidence_plan>` block from a model reply. Validation is
- * all-or-nothing: any malformed or invalid entry rejects the whole plan so a
- * partial plan can never silently drop a hypothesis.
- */
-export function parseEvidencePlan(text: string, round: number): EvidencePlanParseResult {
-	const match = /<evidence_plan>([\s\S]*?)<\/evidence_plan>/.exec(text);
-	if (!match) return { found: false, valid: false, requests: [] };
-	const fail = (error: string): EvidencePlanParseResult => ({ found: true, valid: false, requests: [], error });
-
-	let parsed: unknown;
-	try {
-		parsed = JSON.parse(match[1].trim());
-	} catch (error) {
-		return fail(`malformed JSON in <evidence_plan>: ${(error as Error).message}`);
-	}
-	if (!Array.isArray(parsed)) return fail("<evidence_plan> must contain a JSON array");
-	if (parsed.length === 0) return fail("<evidence_plan> array must not be empty");
-	if (parsed.length > MAX_EVIDENCE_REQUESTS) {
-		return fail(`<evidence_plan> has ${parsed.length} entries; at most ${MAX_EVIDENCE_REQUESTS} are allowed`);
-	}
-
-	const requests: EvidenceRequest[] = [];
-	const seenIds = new Set<string>();
-	for (const entry of parsed) {
-		if (typeof entry !== "object" || entry === null) return fail("every evidence plan entry must be an object");
-		const record = entry as Record<string, unknown>;
-		if (!isNonEmptyString(record.id)) return fail("every evidence plan entry needs a non-empty id");
-		if (seenIds.has(record.id)) return fail(`duplicate evidence request id ${record.id}`);
-		seenIds.add(record.id);
-		if (!isNonEmptyStringArray(record.hypothesisIds) || !hasOnlyUniqueValues(record.hypothesisIds)) {
-			return fail(`request ${record.id} needs one or more unique non-empty hypothesisIds`);
-		}
-		if (!METHODS.includes(record.method as EvidenceMethod)) {
-			return fail(`request ${record.id} has unknown method ${JSON.stringify(record.method)}`);
-		}
-		if (!isNonEmptyString(record.title)) return fail(`request ${record.id} needs a non-empty title`);
-		if (!isNonEmptyString(record.rationale)) {
-			return fail(`request ${record.id} needs a non-empty rationale explaining why this method is decisive`);
-		}
-		if (!isNonEmptyStringArray(record.instructions)) {
-			return fail(`request ${record.id} needs one or more non-empty instructions`);
-		}
-		if (record.artifactHint !== undefined && !isNonEmptyString(record.artifactHint)) {
-			return fail(`request ${record.id} has an empty artifactHint`);
-		}
-		requests.push({
-			id: record.id,
-			hypothesisIds: record.hypothesisIds,
-			method: record.method as EvidenceMethod,
-			title: record.title,
-			rationale: record.rationale,
-			instructions: record.instructions,
-			...(record.artifactHint === undefined ? {} : { artifactHint: record.artifactHint }),
-			round,
-		});
-	}
-	return { found: true, valid: true, requests };
-}
-
-export type ArtifactValidation =
-	| { ok: true; artifact: Omit<EvidenceArtifact, "id" | "addedAt" | "requestId"> }
-	| { ok: false; reason: string };
-
-/**
- * Resolve a user-supplied path and capture filesystem metadata only. The file
- * is referenced in place: its contents are never read, copied or deleted here.
- */
-export function validateEvidenceArtifact(rawPath: string, cwd: string): ArtifactValidation {
-	const trimmed = rawPath.trim();
-	if (trimmed.length === 0) return { ok: false, reason: "no evidence file path provided" };
-	const absolute = path.resolve(cwd, trimmed);
-	let stats: fs.Stats;
-	try {
-		stats = fs.statSync(absolute);
-	} catch (error) {
-		return { ok: false, reason: `cannot stat ${absolute}: ${(error as Error).message}` };
-	}
-	if (!stats.isFile()) return { ok: false, reason: `${absolute} is not a regular file` };
-	try {
-		fs.accessSync(absolute, fs.constants.R_OK);
-	} catch {
-		return { ok: false, reason: `${absolute} is not readable` };
-	}
-	return {
-		ok: true,
-		artifact: { path: absolute, name: path.basename(absolute), size: stats.size, mtimeMs: stats.mtimeMs },
-	};
-}
-
-/** Record a user-supplied artifact, deduplicating by exact absolute path. */
-export function addEvidenceArtifact(
-	state: DebugState,
-	rawPath: string,
-	cwd: string,
-	requestId: string | null,
-	now = Date.now(),
-): { state: DebugState; artifact: EvidenceArtifact } | { error: string } {
-	if (requestId !== null && !state.evidenceRequests.some(request => request.id === requestId)) {
-		return { error: `unknown evidence request id ${requestId}` };
-	}
-	const validation = validateEvidenceArtifact(rawPath, cwd);
-	if (!validation.ok) return { error: validation.reason };
-	const base = validation.artifact;
-	const existing = state.evidenceArtifacts.find(artifact => artifact.path === base.path);
-	if (existing) {
-		const artifact: EvidenceArtifact = { ...existing, ...base, requestId };
-		return {
-			state: { ...state, evidenceArtifacts: state.evidenceArtifacts.map(a => (a.path === base.path ? artifact : a)) },
-			artifact,
-		};
-	}
-	const artifact: EvidenceArtifact = { id: `artifact-${now.toString(36)}`, requestId, ...base, addedAt: now };
-	return { state: { ...state, evidenceArtifacts: [...state.evidenceArtifacts, artifact] }, artifact };
-}
-
-/**
- * Human-readable evidence description for the blackboard and the model-facing
- * tool. Availability is re-checked on every call: a missing or unreadable file
- * is never treated as captured evidence.
- */
-export function describeEvidence(state: DebugState, round?: number): string {
-	const requests = round === undefined ? state.evidenceRequests : state.evidenceRequests.filter(r => r.round === round);
-	if (requests.length === 0 && state.evidenceArtifacts.length === 0 && state.evidenceObservations.length === 0) {
-		return "(none)";
-	}
-	const lines: string[] = [];
-	for (const request of requests) {
-		const linked = state.evidenceArtifacts.filter(artifact => artifact.requestId === request.id);
-		const reports = state.evidenceObservations.filter(observation => observation.requestIds.includes(request.id));
-		const hint = request.artifactHint ? `, artifactHint: ${request.artifactHint}` : "";
-		const coverage =
-			request.method === "user_artifact"
-				? linked.length > 0
-					? "artifact attached"
-					: "PENDING artifact"
-				: request.method === "user_report"
-					? reports.length > 0
-						? "report submitted"
-						: "PENDING report"
-					: "agent-collected";
-		lines.push(
-			`- ${request.id} [${request.method}] ${request.title} (${coverage})${hint}\n  hypotheses: ${request.hypothesisIds.join(", ")}\n  rationale: ${request.rationale}\n  instructions: ${request.instructions.join(" | ")}`,
-		);
-	}
-	for (const observation of state.evidenceObservations) {
-		lines.push(`- ${observation.id} [user observation, round ${observation.round}] ${observation.text}`);
-	}
-	for (const artifact of state.evidenceArtifacts) {
-		let stats: fs.Stats;
-		try {
-			stats = fs.statSync(artifact.path);
-			fs.accessSync(artifact.path, fs.constants.R_OK);
-		} catch {
-			lines.push(`- ${artifact.id} [artifact] ${artifact.path} — UNAVAILABLE (file missing or unreadable)`);
-			continue;
-		}
-		if (!stats.isFile()) {
-			lines.push(`- ${artifact.id} [artifact] ${artifact.path} — UNAVAILABLE (no longer a regular file)`);
-			continue;
-		}
-		const linked = artifact.requestId ? `, request ${artifact.requestId}` : ", unlinked";
-		lines.push(
-			`- ${artifact.id} [artifact] ${artifact.path} — available${linked}, ${stats.size} bytes, mtime ${new Date(stats.mtimeMs).toISOString()}`,
-		);
-	}
-	return lines.join("\n");
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import {
+	type DebugSession,
+	type DebugState,
+	type EvidenceArtifact,
+	type EvidenceMethod,
+	type EvidenceRequest,
+	type EvidenceView,
+	currentRound,
+	pendingRequests,
+} from "./state";
+
+/** Upper bound on accepted plan entries so one model reply cannot flood the gate. */
+export const MAX_EVIDENCE_REQUESTS = 12;
+
+const METHODS: readonly EvidenceMethod[] = ["agent_inspection", "runtime_probe", "user_report", "user_artifact"];
+
+export interface EvidencePlanParseResult {
+	found: boolean;
+	valid: boolean;
+	requests: EvidenceRequest[];
+	error?: string;
+}
+
+function isNonEmptyString(value: unknown): value is string {
+	return typeof value === "string" && value.trim().length > 0;
+}
+
+function isNonEmptyStringArray(value: unknown): value is string[] {
+	return Array.isArray(value) && value.length > 0 && value.every(isNonEmptyString);
+}
+
+function hasOnlyUniqueValues(values: readonly string[]): boolean {
+	return new Set(values).size === values.length;
+}
+
+export type EvidenceRequestsValidation =
+	| { ok: true; requests: EvidenceRequest[] }
+	| { ok: false; error: string };
+
+/**
+ * Validate evidence plan entries. All-or-nothing: any malformed or invalid
+ * entry rejects the whole plan so a partial plan can never silently drop a
+ * hypothesis. Shared by the `hand_off_to_user` tool and the legacy
+ * `<evidence_plan>` tag parser, so both accept exactly the same shape and a
+ * rejection always says the same thing.
+ */
+export function validateEvidenceRequests(entries: unknown): EvidenceRequestsValidation {
+	const fail = (error: string): EvidenceRequestsValidation => ({ ok: false, error });
+	if (!Array.isArray(entries)) return fail("the evidence plan must be a JSON array");
+	if (entries.length === 0) return fail("the evidence plan array must not be empty");
+	if (entries.length > MAX_EVIDENCE_REQUESTS) {
+		return fail(`the evidence plan has ${entries.length} entries; at most ${MAX_EVIDENCE_REQUESTS} are allowed`);
+	}
+
+	const requests: EvidenceRequest[] = [];
+	const seenIds = new Set<string>();
+	for (const entry of entries) {
+		if (typeof entry !== "object" || entry === null) return fail("every evidence plan entry must be an object");
+		const record = entry as Record<string, unknown>;
+		if (!isNonEmptyString(record.id)) return fail("every evidence plan entry needs a non-empty id");
+		if (seenIds.has(record.id)) return fail(`duplicate evidence request id ${record.id}`);
+		seenIds.add(record.id);
+		if (!isNonEmptyStringArray(record.hypothesisIds) || !hasOnlyUniqueValues(record.hypothesisIds)) {
+			return fail(`request ${record.id} needs one or more unique non-empty hypothesisIds`);
+		}
+		if (!METHODS.includes(record.method as EvidenceMethod)) {
+			return fail(`request ${record.id} has unknown method ${JSON.stringify(record.method)}`);
+		}
+		if (!isNonEmptyString(record.title)) return fail(`request ${record.id} needs a non-empty title`);
+		if (!isNonEmptyString(record.rationale)) {
+			return fail(`request ${record.id} needs a non-empty rationale explaining why this method is decisive`);
+		}
+		if (!isNonEmptyStringArray(record.instructions)) {
+			return fail(`request ${record.id} needs one or more non-empty instructions`);
+		}
+		if (record.artifactHint !== undefined && !isNonEmptyString(record.artifactHint)) {
+			return fail(`request ${record.id} has an empty artifactHint`);
+		}
+		requests.push({
+			id: record.id,
+			hypothesisIds: record.hypothesisIds,
+			method: record.method as EvidenceMethod,
+			title: record.title,
+			rationale: record.rationale,
+			instructions: record.instructions,
+			...(record.artifactHint === undefined ? {} : { artifactHint: record.artifactHint }),
+		});
+	}
+	return { ok: true, requests };
+}
+
+/**
+ * Parse the legacy `<evidence_plan>` block from a model reply. Kept so a plan
+ * described in prose is still recorded rather than lost — but a parsed block no
+ * longer closes a round: the turn is sent back for the `hand_off_to_user` call,
+ * which is the only closure.
+ */
+export function parseEvidencePlan(text: string): EvidencePlanParseResult {
+	const match = /<evidence_plan>([\s\S]*?)<\/evidence_plan>/.exec(text);
+	if (!match) return { found: false, valid: false, requests: [] };
+
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(match[1].trim());
+	} catch (error) {
+		return {
+			found: true,
+			valid: false,
+			requests: [],
+			error: `malformed JSON in <evidence_plan>: ${(error as Error).message}`,
+		};
+	}
+	const validation = validateEvidenceRequests(parsed);
+	if (!validation.ok) return { found: true, valid: false, requests: [], error: validation.error };
+	return { found: true, valid: true, requests: validation.requests };
+}
+
+/** First argument of `/debug-evidence` when the file answers no request. */
+export const UNLINKED_SELECTOR = "-";
+
+export type EvidenceArgument =
+	| { ok: true; requestId: string | null; rawPath: string | undefined }
+	| { ok: false; error: string };
+
+/** A request as a link target: which round declared it, and whether it is settled. */
+interface RequestTarget {
+	request: EvidenceRequest;
+	round: number;
+	current: boolean;
+	pending: boolean;
+}
+
+/**
+ * Every request that can be linked to, best candidate first: this round before
+ * older rounds, and within this round the ones still waiting on the user.
+ */
+function requestTargets(session: DebugSession): RequestTarget[] {
+	const round = currentRound(session);
+	const pending = new Set(pendingRequests(session, round).map(request => request.id));
+	const targets: RequestTarget[] = [];
+	for (const candidate of session.rounds) {
+		for (const request of candidate.plan ?? []) {
+			targets.push({
+				request,
+				round: candidate.index,
+				current: candidate.index === round.index,
+				pending: pending.has(request.id),
+			});
+		}
+	}
+	return targets.sort((a, b) => {
+		if (a.current !== b.current) return a.current ? -1 : 1;
+		if (a.pending !== b.pending) return a.pending ? -1 : 1;
+		return b.round - a.round;
+	});
+}
+
+function knownIds(session: DebugSession): string[] {
+	return requestTargets(session).map(target => target.request.id);
+}
+
+function describeKnownIds(ids: readonly string[]): string {
+	return ids.length > 0 ? ids.join(", ") : "(none — no evidence request exists yet)";
+}
+
+/**
+ * Parse `/debug-evidence <request-id|-> [path]`.
+ *
+ * The first token is always a link selector, never part of the path. Deciding
+ * that by looking the token up in session state is what used to make
+ * `/debug-evidence E1 frame.rdc` resolve `<cwd>/E1 frame.rdc` as one path
+ * whenever E1 was not a currently pending artifact request, and the failure was
+ * reported as a missing file rather than as an unrecognised id.
+ */
+export function parseEvidenceArgument(args: string, session: DebugSession): EvidenceArgument {
+	const trimmed = args.trim();
+	const ids = knownIds(session);
+	if (!trimmed) {
+		return {
+			ok: false,
+			error:
+				`name what the file answers first: /debug-evidence <request-id|${UNLINKED_SELECTOR}> [path]. ` +
+				`Known request ids: ${describeKnownIds(ids)}.`,
+		};
+	}
+	const token = trimmed.split(/\s+/, 1)[0];
+	const rest = trimmed.slice(token.length).trim();
+	const rawPath = rest.length > 0 ? rest : undefined;
+	if (token === UNLINKED_SELECTOR) return { ok: true, requestId: null, rawPath };
+	if (ids.includes(token)) return { ok: true, requestId: token, rawPath };
+	return {
+		ok: false,
+		error:
+			`${JSON.stringify(token)} is not an evidence request id. Known request ids: ${describeKnownIds(ids)}. ` +
+			`Pass ${UNLINKED_SELECTOR} as the first argument to attach a file that answers no request.`,
+	};
+}
+
+/** Structurally an `AutocompleteItem`, declared here so no host type is vendored. */
+export interface EvidenceCompletion {
+	value: string;
+	label: string;
+	description?: string;
+	hint?: string;
+}
+
+function describeTarget(target: RequestTarget): string {
+	const status = target.current ? (target.pending ? "pending" : "satisfied") : `round ${target.round}`;
+	return `${target.request.method} · ${target.request.title} — ${status}`;
+}
+
+/**
+ * Complete the link selector under the editor. Must stay synchronous and free
+ * of side effects: the host calls it on every keystroke.
+ *
+ * Whitespace in the prefix means the selector is settled, so returning null
+ * hands the rest of the argument to the host's own file-path completion.
+ */
+export function evidenceCompletions(argumentPrefix: string, state: DebugState): EvidenceCompletion[] | null {
+	if (/\s/.test(argumentPrefix) || !state.active) return null;
+	const prefix = argumentPrefix.trim().toLowerCase();
+	const items: EvidenceCompletion[] = [
+		{
+			value: `${UNLINKED_SELECTOR} `,
+			label: UNLINKED_SELECTOR,
+			description: "Attach a file that answers no request",
+			hint: "<path>",
+		},
+	];
+	for (const target of requestTargets(state)) {
+		items.push({
+			value: `${target.request.id} `,
+			label: target.request.id,
+			description: describeTarget(target),
+			hint: "<path>",
+		});
+	}
+	const matched = items.filter(item => item.label.toLowerCase().startsWith(prefix));
+	return matched.length > 0 ? matched : null;
+}
+
+export type ArtifactValidation =
+	| { ok: true; artifact: Omit<EvidenceArtifact, "id" | "addedAt" | "requestId"> }
+	| { ok: false; reason: string };
+
+/**
+ * Resolve a user-supplied path and capture filesystem metadata only. The file
+ * is referenced in place: its contents are never read, copied or deleted here.
+ */
+export function validateEvidenceArtifact(rawPath: string, cwd: string): ArtifactValidation {
+	const trimmed = rawPath.trim();
+	if (trimmed.length === 0) return { ok: false, reason: "no evidence file path provided" };
+	const absolute = path.resolve(cwd, trimmed);
+	let stats: fs.Stats;
+	try {
+		stats = fs.statSync(absolute);
+	} catch (error) {
+		return { ok: false, reason: `cannot stat ${absolute}: ${(error as Error).message}` };
+	}
+	if (!stats.isFile()) return { ok: false, reason: `${absolute} is not a regular file` };
+	try {
+		fs.accessSync(absolute, fs.constants.R_OK);
+	} catch {
+		return { ok: false, reason: `${absolute} is not readable` };
+	}
+	return {
+		ok: true,
+		artifact: { path: absolute, name: path.basename(absolute), size: stats.size, mtimeMs: stats.mtimeMs },
+	};
+}
+
+/**
+ * Human-readable evidence description for the blackboard and the model-facing
+ * tool. Availability is re-checked on every call: a missing or unreadable file
+ * is never treated as captured evidence.
+ */
+export function describeEvidence(view: EvidenceView): string {
+	const { requests, artifacts, observations } = view;
+	if (requests.length === 0 && artifacts.length === 0 && observations.length === 0) {
+		return "(none)";
+	}
+	const lines: string[] = [];
+	for (const request of requests) {
+		const linked = artifacts.filter(artifact => artifact.requestId === request.id);
+		const reports = observations.filter(observation => observation.requestIds.includes(request.id));
+		const hint = request.artifactHint ? `, artifactHint: ${request.artifactHint}` : "";
+		const coverage =
+			request.method === "user_artifact"
+				? linked.length > 0
+					? "artifact attached"
+					: "PENDING artifact"
+				: request.method === "user_report"
+					? reports.length > 0
+						? "report submitted"
+						: "PENDING report"
+					: "agent-collected";
+		lines.push(
+			`- ${request.id} [${request.method}] ${request.title} (${coverage})${hint}\n  hypotheses: ${request.hypothesisIds.join(", ")}\n  rationale: ${request.rationale}\n  instructions: ${request.instructions.join(" | ")}`,
+		);
+	}
+	for (const observation of observations) {
+		lines.push(`- ${observation.id} [user observation, round ${observation.round}] ${observation.text}`);
+	}
+	for (const artifact of artifacts) {
+		let stats: fs.Stats;
+		try {
+			stats = fs.statSync(artifact.path);
+			fs.accessSync(artifact.path, fs.constants.R_OK);
+		} catch {
+			lines.push(`- ${artifact.id} [artifact] ${artifact.path} — UNAVAILABLE (file missing or unreadable)`);
+			continue;
+		}
+		if (!stats.isFile()) {
+			lines.push(`- ${artifact.id} [artifact] ${artifact.path} — UNAVAILABLE (no longer a regular file)`);
+			continue;
+		}
+		const linked = artifact.requestId ? `, request ${artifact.requestId}` : ", unlinked";
+		lines.push(
+			`- ${artifact.id} [artifact] ${artifact.path} — available${linked}, ${stats.size} bytes, mtime ${new Date(stats.mtimeMs).toISOString()}`,
+		);
+	}
+	return lines.join("\n");
+}