@f5-sales-demo/xcsh 19.51.2

package/src/async/job-manager.ts

@@ -0,0 +1,416 @@
+import { logger } from "@f5xc-salesdemos/pi-utils";
+
+const DELIVERY_RETRY_BASE_MS = 500;
+const DELIVERY_RETRY_MAX_MS = 30_000;
+const DELIVERY_RETRY_JITTER_MS = 200;
+const DEFAULT_RETENTION_MS = 5 * 60 * 1000;
+const DEFAULT_MAX_RUNNING_JOBS = 15;
+
+export interface AsyncJob {
+	id: string;
+	type: "bash" | "task";
+	status: "running" | "completed" | "failed" | "cancelled";
+	startTime: number;
+	label: string;
+	abortController: AbortController;
+	promise: Promise<void>;
+	resultText?: string;
+	errorText?: string;
+}
+
+export interface AsyncJobManagerOptions {
+	onJobComplete: (jobId: string, text: string, job?: AsyncJob) => void | Promise<void>;
+	maxRunningJobs?: number;
+	retentionMs?: number;
+}
+
+interface AsyncJobDelivery {
+	jobId: string;
+	text: string;
+	attempt: number;
+	nextAttemptAt: number;
+	lastError?: string;
+}
+
+export interface AsyncJobDeliveryState {
+	queued: number;
+	delivering: boolean;
+	nextRetryAt?: number;
+	pendingJobIds: string[];
+}
+
+export interface AsyncJobRegisterOptions {
+	id?: string;
+	onProgress?: (text: string, details?: Record<string, unknown>) => void | Promise<void>;
+}
+
+export class AsyncJobManager {
+	readonly #jobs = new Map<string, AsyncJob>();
+	readonly #deliveries: AsyncJobDelivery[] = [];
+	readonly #suppressedDeliveries = new Set<string>();
+	readonly #watchedJobs = new Set<string>();
+	readonly #evictionTimers = new Map<string, NodeJS.Timeout>();
+	readonly #onJobComplete: AsyncJobManagerOptions["onJobComplete"];
+	readonly #maxRunningJobs: number;
+	readonly #retentionMs: number;
+	#deliveryLoop: Promise<void> | undefined;
+	#disposed = false;
+
+	constructor(options: AsyncJobManagerOptions) {
+		this.#onJobComplete = options.onJobComplete;
+		this.#maxRunningJobs = Math.max(1, Math.floor(options.maxRunningJobs ?? DEFAULT_MAX_RUNNING_JOBS));
+		this.#retentionMs = Math.max(0, Math.floor(options.retentionMs ?? DEFAULT_RETENTION_MS));
+	}
+
+	register(
+		type: "bash" | "task",
+		label: string,
+		run: (ctx: {
+			jobId: string;
+			signal: AbortSignal;
+			reportProgress: (text: string, details?: Record<string, unknown>) => Promise<void>;
+		}) => Promise<string>,
+		options?: AsyncJobRegisterOptions,
+	): string {
+		if (this.#disposed) {
+			throw new Error("Async job manager is disposed");
+		}
+		const runningCount = this.getRunningJobs().length;
+		if (runningCount >= this.#maxRunningJobs) {
+			throw new Error(
+				`Background job limit reached (${this.#maxRunningJobs}). Wait for running jobs to finish or cancel one.`,
+			);
+		}
+
+		const id = this.#resolveJobId(options?.id);
+		this.#suppressedDeliveries.delete(id);
+		const abortController = new AbortController();
+		const startTime = Date.now();
+
+		const job: AsyncJob = {
+			id,
+			type,
+			status: "running",
+			startTime,
+			label,
+			abortController,
+			promise: Promise.resolve(),
+		};
+
+		const reportProgress = async (text: string, details?: Record<string, unknown>): Promise<void> => {
+			if (!options?.onProgress) return;
+			try {
+				await options.onProgress(text, details);
+			} catch (error) {
+				logger.warn("Async job progress callback failed", {
+					jobId: id,
+					error: error instanceof Error ? error.message : String(error),
+				});
+			}
+		};
+		job.promise = (async () => {
+			try {
+				const text = await run({ jobId: id, signal: abortController.signal, reportProgress });
+				if (job.status === "cancelled") {
+					job.resultText = text;
+					this.#scheduleEviction(id);
+					return;
+				}
+				job.status = "completed";
+				job.resultText = text;
+				this.#enqueueDelivery(id, text);
+				this.#scheduleEviction(id);
+			} catch (error) {
+				if (job.status === "cancelled") {
+					job.errorText = error instanceof Error ? error.message : String(error);
+					this.#scheduleEviction(id);
+					return;
+				}
+				const errorText = error instanceof Error ? error.message : String(error);
+				job.status = "failed";
+				job.errorText = errorText;
+				this.#enqueueDelivery(id, errorText);
+				this.#scheduleEviction(id);
+			}
+		})();
+
+		this.#jobs.set(id, job);
+		return id;
+	}
+
+	cancel(id: string): boolean {
+		const job = this.#jobs.get(id);
+		if (!job) return false;
+		if (job.status !== "running") return false;
+		job.status = "cancelled";
+		job.abortController.abort();
+		this.#scheduleEviction(id);
+		return true;
+	}
+
+	getJob(id: string): AsyncJob | undefined {
+		return this.#jobs.get(id);
+	}
+
+	getRunningJobs(): AsyncJob[] {
+		return Array.from(this.#jobs.values()).filter(job => job.status === "running");
+	}
+
+	getRecentJobs(limit = 10): AsyncJob[] {
+		return Array.from(this.#jobs.values())
+			.filter(job => job.status !== "running")
+			.sort((a, b) => b.startTime - a.startTime)
+			.slice(0, limit);
+	}
+
+	getAllJobs(): AsyncJob[] {
+		return Array.from(this.#jobs.values());
+	}
+
+	getDeliveryState(): AsyncJobDeliveryState {
+		const nextRetryAt = this.#deliveries.reduce<number | undefined>((next, delivery) => {
+			if (next === undefined) return delivery.nextAttemptAt;
+			return Math.min(next, delivery.nextAttemptAt);
+		}, undefined);
+
+		return {
+			queued: this.#deliveries.length,
+			delivering: this.#deliveryLoop !== undefined,
+			nextRetryAt,
+			pendingJobIds: this.#deliveries.map(delivery => delivery.jobId),
+		};
+	}
+
+	hasPendingDeliveries(): boolean {
+		return this.#deliveries.length > 0;
+	}
+
+	watchJobs(jobIds: string[]): number {
+		const uniqueJobIds = Array.from(new Set(jobIds.map(id => id.trim()).filter(id => id.length > 0)));
+		for (const jobId of uniqueJobIds) {
+			this.#watchedJobs.add(jobId);
+		}
+		return uniqueJobIds.length;
+	}
+
+	unwatchJobs(jobIds: string[]): number {
+		const uniqueJobIds = Array.from(new Set(jobIds.map(id => id.trim()).filter(id => id.length > 0)));
+		let removed = 0;
+		for (const jobId of uniqueJobIds) {
+			if (this.#watchedJobs.delete(jobId)) {
+				removed += 1;
+			}
+		}
+		return removed;
+	}
+
+	acknowledgeDeliveries(jobIds: string[]): number {
+		const uniqueJobIds = Array.from(new Set(jobIds.map(id => id.trim()).filter(id => id.length > 0)));
+		if (uniqueJobIds.length === 0) return 0;
+
+		for (const jobId of uniqueJobIds) {
+			this.#suppressedDeliveries.add(jobId);
+		}
+
+		const before = this.#deliveries.length;
+		this.#deliveries.splice(
+			0,
+			this.#deliveries.length,
+			...this.#deliveries.filter(delivery => !this.isDeliverySuppressed(delivery.jobId)),
+		);
+		return before - this.#deliveries.length;
+	}
+
+	cancelAll(): void {
+		for (const job of this.getRunningJobs()) {
+			job.status = "cancelled";
+			job.abortController.abort();
+			this.#scheduleEviction(job.id);
+		}
+	}
+
+	async waitForAll(): Promise<void> {
+		await Promise.all(Array.from(this.#jobs.values()).map(job => job.promise));
+	}
+
+	async drainDeliveries(options?: { timeoutMs?: number }): Promise<boolean> {
+		const timeoutMs = options?.timeoutMs;
+		const hasDeadline = timeoutMs !== undefined;
+		const deadline = hasDeadline ? Date.now() + Math.max(timeoutMs, 0) : Number.POSITIVE_INFINITY;
+
+		while (this.hasPendingDeliveries()) {
+			this.#ensureDeliveryLoop();
+			const loop = this.#deliveryLoop;
+			if (!loop) {
+				continue;
+			}
+
+			if (!hasDeadline) {
+				await loop;
+				continue;
+			}
+
+			const remainingMs = deadline - Date.now();
+			if (remainingMs <= 0) {
+				return false;
+			}
+
+			await Promise.race([loop, Bun.sleep(remainingMs)]);
+			if (Date.now() >= deadline && this.hasPendingDeliveries()) {
+				return false;
+			}
+		}
+
+		return true;
+	}
+
+	async dispose(options?: { timeoutMs?: number }): Promise<boolean> {
+		this.#disposed = true;
+		this.#clearEvictionTimers();
+		this.cancelAll();
+		await this.waitForAll();
+		const drained = await this.drainDeliveries({ timeoutMs: options?.timeoutMs ?? 3_000 });
+		this.#clearEvictionTimers();
+		this.#jobs.clear();
+		this.#deliveries.length = 0;
+		this.#suppressedDeliveries.clear();
+		this.#watchedJobs.clear();
+		return drained;
+	}
+
+	#resolveJobId(preferredId?: string): string {
+		preferredId = preferredId?.trim();
+		if (!preferredId) {
+			let candidate = 1;
+			while (true) {
+				const id = `bg_${candidate}`;
+				if (!this.#jobs.has(id)) {
+					return id;
+				}
+				candidate += 1;
+			}
+		}
+
+		const base = preferredId.trim();
+		if (!this.#jobs.has(base)) return base;
+
+		let suffix = 2;
+		let candidate = `${base}-${suffix}`;
+		while (this.#jobs.has(candidate)) {
+			suffix += 1;
+			candidate = `${base}-${suffix}`;
+		}
+		return candidate;
+	}
+
+	#scheduleEviction(jobId: string): void {
+		if (this.#retentionMs <= 0) {
+			this.#jobs.delete(jobId);
+			this.#suppressedDeliveries.delete(jobId);
+			this.#watchedJobs.delete(jobId);
+			return;
+		}
+		const existing = this.#evictionTimers.get(jobId);
+		if (existing) {
+			clearTimeout(existing);
+		}
+		const timer = setTimeout(() => {
+			this.#evictionTimers.delete(jobId);
+			this.#jobs.delete(jobId);
+			this.#suppressedDeliveries.delete(jobId);
+			this.#watchedJobs.delete(jobId);
+		}, this.#retentionMs);
+		timer.unref();
+		this.#evictionTimers.set(jobId, timer);
+	}
+
+	#clearEvictionTimers(): void {
+		for (const timer of this.#evictionTimers.values()) {
+			clearTimeout(timer);
+		}
+		this.#evictionTimers.clear();
+	}
+
+	isDeliverySuppressed(jobId: string): boolean {
+		return this.#suppressedDeliveries.has(jobId) || this.#watchedJobs.has(jobId);
+	}
+
+	#enqueueDelivery(jobId: string, text: string): void {
+		// Skip delivery if already acknowledged
+		if (this.isDeliverySuppressed(jobId)) {
+			return;
+		}
+		this.#deliveries.push({
+			jobId,
+			text,
+			attempt: 0,
+			nextAttemptAt: Date.now(),
+		});
+		this.#ensureDeliveryLoop();
+	}
+
+	#ensureDeliveryLoop(): void {
+		if (this.#deliveryLoop) {
+			return;
+		}
+
+		this.#deliveryLoop = this.#runDeliveryLoop()
+			.catch(error => {
+				logger.error("Async job delivery loop crashed", { error: String(error) });
+			})
+			.finally(() => {
+				this.#deliveryLoop = undefined;
+				if (this.#deliveries.length > 0) {
+					this.#ensureDeliveryLoop();
+				}
+			});
+	}
+
+	async #runDeliveryLoop(): Promise<void> {
+		while (this.#deliveries.length > 0) {
+			const delivery = this.#deliveries[0];
+			if (this.isDeliverySuppressed(delivery.jobId)) {
+				this.#deliveries.shift();
+				continue;
+			}
+			const waitMs = delivery.nextAttemptAt - Date.now();
+			if (waitMs > 0) {
+				await Bun.sleep(waitMs);
+			}
+			if (this.#deliveries[0] !== delivery) {
+				continue;
+			}
+			// Check again after sleep
+			if (this.isDeliverySuppressed(delivery.jobId)) {
+				this.#deliveries.shift();
+				continue;
+			}
+
+			try {
+				await this.#onJobComplete(delivery.jobId, delivery.text, this.#jobs.get(delivery.jobId));
+				this.#deliveries.shift();
+			} catch (error) {
+				delivery.attempt += 1;
+				delivery.lastError = error instanceof Error ? error.message : String(error);
+				delivery.nextAttemptAt = Date.now() + this.#getRetryDelay(delivery.attempt);
+				this.#deliveries.shift();
+				if (!this.isDeliverySuppressed(delivery.jobId)) {
+					this.#deliveries.push(delivery);
+				}
+				logger.warn("Async job completion delivery failed", {
+					jobId: delivery.jobId,
+					attempt: delivery.attempt,
+					nextRetryAt: delivery.nextAttemptAt,
+					error: delivery.lastError,
+				});
+			}
+		}
+	}
+
+	#getRetryDelay(attempt: number): number {
+		const exp = Math.min(Math.max(attempt - 1, 0), 8);
+		const backoffMs = DELIVERY_RETRY_BASE_MS * 2 ** exp;
+		const jitterMs = Math.floor(Math.random() * DELIVERY_RETRY_JITTER_MS);
+		return Math.min(DELIVERY_RETRY_MAX_MS, backoffMs + jitterMs);
+	}
+}

package/src/async/support.ts

@@ -0,0 +1,5 @@
+import type { Settings } from "../config/settings";
+
+export function isBackgroundJobSupportEnabled(settings: Pick<Settings, "get">): boolean {
+	return settings.get("async.enabled") || settings.get("bash.autoBackground.enabled");
+}

package/src/autoresearch/apply-contract-to-state.ts

@@ -0,0 +1 @@
+export { applyAutoresearchContractToExperimentState } from "./contract";

package/src/autoresearch/command-resume.md

@@ -0,0 +1,17 @@
+Resume autoresearch from the attached notes.
+
+@{{autoresearch_md_path}}
+
+{{branch_status_line}}
+{{#if has_resume_context}}
+
+Additional context from the user:
+
+{{resume_context}}
+{{/if}}
+
+Use the notes as the source of truth for the current direction, scope, and constraints.
+- inspect recent git history for context
+- inspect `autoresearch.jsonl` if it exists
+- continue the most promising unfinished direction on the current protected branch
+- keep iterating until interrupted or until the configured iteration cap is reached

package/src/autoresearch/contract.ts

@@ -0,0 +1,205 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { inferMetricUnitFromName, normalizeAutoresearchPath } from "./helpers";
+import type { AutoresearchContract, ExperimentState, MetricDirection } from "./types";
+
+const HEADING_REGEX = /^##\s+(.+?)\s*$/;
+const LIST_ITEM_REGEX = /^\s*[-*]\s+(.*)$/;
+const KEY_VALUE_REGEX = /^\s*[-*]\s+([^:]+):\s*(.*)$/;
+function tryReadFile(filePath: string): string | null {
+	try {
+		return fs.readFileSync(filePath, "utf8");
+	} catch {
+		return null;
+	}
+}
+export function readAutoresearchContract(workDir: string) {
+	const contractPath = path.join(workDir, "autoresearch.md");
+	const content = tryReadFile(contractPath);
+	if (content === null)
+		return {
+			contract: {
+				benchmark: { command: null, primaryMetric: null, metricUnit: "", direction: null, secondaryMetrics: [] },
+				scopePaths: [],
+				offLimits: [],
+				constraints: [],
+			},
+			errors: [`${contractPath} does not exist. Create it before initializing autoresearch.`],
+			path: contractPath,
+		};
+	const contract = parseAutoresearchContract(content);
+	return { contract, errors: validateAutoresearchContract(contract), path: contractPath };
+}
+export function parseAutoresearchContract(markdown: string): AutoresearchContract {
+	const sections = extractSections(markdown);
+	return {
+		benchmark: parseBenchmarkSection(sections.get("benchmark") ?? ""),
+		scopePaths: parseListSection(sections.get("files in scope") ?? "", normalizeContractPathSpec),
+		offLimits: parseListSection(sections.get("off limits") ?? "", normalizeContractPathSpec),
+		constraints: parseListSection(sections.get("constraints") ?? ""),
+	};
+}
+function validateAutoresearchContract(contract: AutoresearchContract): string[] {
+	const errors: string[] = [];
+	if (!contract.benchmark.command) errors.push("Benchmark.command is required in autoresearch.md.");
+	if (!contract.benchmark.primaryMetric) errors.push("Benchmark.primary metric is required in autoresearch.md.");
+	if (!contract.benchmark.direction)
+		errors.push("Benchmark.direction must be `lower` or `higher` in autoresearch.md.");
+	if (contract.scopePaths.length === 0)
+		errors.push("Files in Scope must contain at least one path in autoresearch.md.");
+	for (const [label, paths] of [
+		["Files in Scope", contract.scopePaths],
+		["Off Limits", contract.offLimits],
+	] as const)
+		for (const p of paths)
+			if (path.posix.isAbsolute(p) || p === ".." || p.startsWith("../"))
+				errors.push(`${label} contains an invalid path: ${p}`);
+	return errors;
+}
+export function loadAutoresearchScriptSnapshot(workDir: string) {
+	const benchmarkScriptPath = path.join(workDir, "autoresearch.sh");
+	const checksScriptPath = path.join(workDir, "autoresearch.checks.sh");
+	const benchmarkScript = tryReadFile(benchmarkScriptPath);
+	return {
+		benchmarkScript: benchmarkScript ?? "",
+		benchmarkScriptPath,
+		checksScript: tryReadFile(checksScriptPath),
+		checksScriptPath,
+		errors:
+			benchmarkScript === null
+				? [`${benchmarkScriptPath} does not exist. Create it before initializing autoresearch.`]
+				: [],
+	};
+}
+export function normalizeAutoresearchList(values: readonly string[]): string[] {
+	return [...new Set(values.map(v => v.trim()).filter(Boolean))];
+}
+export function normalizeContractPathSpec(value: string): string {
+	return normalizeAutoresearchPath(path.posix.normalize(value.trim().replaceAll("\\", "/")));
+}
+export function pathMatchesContractPath(pathValue: string, specValue: string): boolean {
+	const normalizedPath = normalizeContractPathSpec(pathValue);
+	const normalizedSpec = normalizeContractPathSpec(specValue);
+	if (normalizedSpec === ".") return true;
+	return normalizedPath === normalizedSpec || normalizedPath.startsWith(`${normalizedSpec}/`);
+}
+export function contractListsEqual(left: readonly string[], right: readonly string[]): boolean {
+	const a = normalizeAutoresearchList(left);
+	const b = normalizeAutoresearchList(right);
+	return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+export function contractPathListsEqual(left: readonly string[], right: readonly string[]): boolean {
+	const norm = (values: readonly string[]) =>
+		normalizeAutoresearchList(values.map(normalizeContractPathSpec)).sort((l, r) => l.localeCompare(r));
+	const a = norm(left);
+	const b = norm(right);
+	return a.length === b.length && a.every((v, i) => v === b[i]);
+}
+function extractSections(markdown: string): Map<string, string> {
+	const sections = new Map<string, string>();
+	let heading: string | null = null;
+	let content: string[] = [];
+	for (const line of markdown.split("\n")) {
+		const match = line.match(HEADING_REGEX);
+		if (match) {
+			if (heading) sections.set(heading, content.join("\n").trim());
+			heading = match[1]?.trim().toLowerCase() ?? null;
+			content = [];
+		} else if (heading) {
+			content.push(line);
+		}
+	}
+	if (heading) sections.set(heading, content.join("\n").trim());
+	return sections;
+}
+function parseBenchmarkSection(section: string): AutoresearchContract["benchmark"] {
+	const entries = new Map<string, string>();
+	const lines = section.split("\n");
+	for (let index = 0; index < lines.length; index += 1) {
+		const rawLine = lines[index] ?? "";
+		const match = rawLine.match(KEY_VALUE_REGEX);
+		if (!match) continue;
+		const key = (match[1] ?? "").toLowerCase().replace(/[^a-z0-9]+/g, "");
+		let value = (match[2] ?? "").trim();
+		if (key === "secondarymetrics") {
+			const nestedItems: string[] = [];
+			for (let nestedIndex = index + 1; nestedIndex < lines.length; nestedIndex += 1) {
+				const nestedLine = lines[nestedIndex] ?? "";
+				if (nestedLine.match(KEY_VALUE_REGEX)) break;
+				const nestedMatch = nestedLine.match(/^\s{2,}[-*]\s+(.*)$/);
+				if (!nestedMatch && nestedLine.trim().length > 0) break;
+				if (!nestedMatch) continue;
+				nestedItems.push((nestedMatch[1] ?? "").trim());
+				index = nestedIndex;
+			}
+			if (nestedItems.length > 0) value = [value, ...nestedItems].filter(Boolean).join(", ");
+		}
+		entries.set(key, value);
+	}
+
+	const directionRaw = entries.get("direction");
+	const direction: MetricDirection | null =
+		directionRaw === "lower" || directionRaw === "higher" ? directionRaw : null;
+	return {
+		command: entries.get("command")?.trim() || null,
+		primaryMetric: entries.get("primarymetric")?.trim() || null,
+		metricUnit: entries.get("metricunit")?.trim() ?? "",
+		direction,
+		secondaryMetrics: entries.get("secondarymetrics")
+			? normalizeAutoresearchList(
+					entries
+						.get("secondarymetrics")!
+						.split(",")
+						.map(e => e.trim())
+						.filter(Boolean),
+				)
+			: [],
+	};
+}
+function parseListSection(section: string, normalizeItem?: (value: string) => string): string[] {
+	const items: string[] = [];
+	let activeItem: string | null = null;
+	for (const rawLine of section.split("\n")) {
+		const line = rawLine.trimEnd();
+		if (line.trim().length === 0) continue;
+		const match = rawLine.match(LIST_ITEM_REGEX);
+		if (match) {
+			if (activeItem) items.push(activeItem);
+			activeItem = (match[1] ?? "").trim();
+			continue;
+		}
+		if (activeItem && /^\s{2,}\S/.test(rawLine)) {
+			activeItem = `${activeItem} ${line.trim()}`;
+			continue;
+		}
+		if (activeItem) {
+			items.push(activeItem);
+			activeItem = null;
+		}
+		items.push(line.trim());
+	}
+	if (activeItem) items.push(activeItem);
+	const normalizedItems = normalizeAutoresearchList(items);
+	return normalizeItem ? normalizedItems.map(normalizeItem) : normalizedItems;
+}
+/**
+ * Updates session fields from a validated `autoresearch.md` parse (same fields as `init_experiment`).
+ * Does not touch `name`, `currentSegment`, `results`, `bestMetric`, `confidence`, or `maxExperiments`.
+ */
+export function applyAutoresearchContractToExperimentState(
+	contract: AutoresearchContract,
+	state: ExperimentState,
+): void {
+	const benchmarkContract = contract.benchmark;
+	state.metricName = benchmarkContract.primaryMetric ?? state.metricName;
+	state.metricUnit = benchmarkContract.metricUnit;
+	state.bestDirection = benchmarkContract.direction ?? "lower";
+	state.secondaryMetrics = benchmarkContract.secondaryMetrics.map(name => ({
+		name,
+		unit: inferMetricUnitFromName(name),
+	}));
+	state.benchmarkCommand = benchmarkContract.command?.trim() ?? state.benchmarkCommand;
+	state.scopePaths = [...contract.scopePaths];
+	state.offLimits = [...contract.offLimits];
+	state.constraints = [...contract.constraints];
+}