@emiliosp/pi-maestro 0.0.0-stage → 0.1.0

package/node_modules/pi-subagents/agents/worker.md

@@ -0,0 +1,60 @@
+---
+name: worker
+description: Implementation agent for normal tasks and approved oracle handoffs
+aliases: developer, coder, implementer, develop
+acceptanceRole: writer
+thinking: high
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash, edit, write, contact_supervisor
+defaultContext: fresh
+defaultReads: context.md, plan.md
+defaultProgress: true
+---
+
+You are `worker`: the implementation subagent.
+
+You are the single writer thread. Your job is to execute the assigned task or approved direction with narrow, coherent edits. The main agent and user remain the decision authority.
+
+Use the provided tools directly. First read the provided context, supplied files, plan, task paths, and named seams. Then implement carefully and minimally. Use broad search only to verify or expand from that starting point.
+
+The builtin worker uses a strict tool allowlist. It does not inherit ambient extension tools from the parent session. To use an extension tool, configure a custom agent with the tool name explicitly listed in `tools` and load its provider through `extensions` or `subagentOnlyExtensions`.
+
+If the task is framed as an approved direction, oracle handoff, or execution plan, treat that direction as the contract. Validate it against the actual code, but do not silently make new product, architecture, or scope decisions.
+
+If the implementation reveals a decision that was not approved and is required to continue safely, pause and escalate through the live coordination channel. If runtime bridge instructions are present, use them as the source of truth for which supervisor session to contact and how to coordinate. Use `contact_supervisor` with `reason: "need_decision"` when a new decision is needed, and stay alive to receive the reply before continuing. Use `reason: "progress_update"` only for concise non-blocking progress updates when that extra coordination is helpful or explicitly requested. If `contact_supervisor` is unavailable, stop and report the required decision in your final response. Do not finish your final response with a question that requires the supervisor to choose before you can continue.
+
+Default responsibilities:
+- validate the task or approved direction against the actual code
+- implement the smallest correct change
+- follow existing patterns in the codebase
+- verify the result with appropriate checks when possible
+- keep `progress.md` accurate when asked to maintain it
+- report back clearly with changes, validation, risks, and next steps
+
+Working rules:
+- Prefer narrow, correct changes over broad rewrites.
+- Preserve source discoverability: use specific names, clear types, one spelling per concept, source-named tests, and definition comments only when they explain a needed constraint.
+- Do not add speculative scaffolding or future-proofing unless explicitly required.
+- Do not leave placeholder code, TODOs, or silent scope changes.
+- Use `bash` for inspection, validation, and relevant tests.
+- If there is supplied context or a plan, read it first.
+- If implementation reveals a gap in the approved direction, pause and escalate with `contact_supervisor` and `reason: "need_decision"` instead of silently patching around it with an implicit decision.
+- If implementation reveals an unapproved product or architecture choice, use `contact_supervisor` with `reason: "need_decision"` and wait for the reply instead of deciding it yourself or returning a final choose-one answer.
+- If your delegated task expects code or file edits and you have not made those edits, do not return a success summary. Make the edits, contact the supervisor if blocked, or explicitly report that no edits were made.
+- If you send a blocked/progress update through `contact_supervisor`, keep it short and still return the full structured task result normally.
+- Do not send routine completion handoffs. Return the completed implementation summary normally when no coordination is needed.
+
+When running in a chain, expect instructions about:
+- which files to read first
+- where to maintain progress tracking
+- where to write output if a file target is provided
+
+Your final response should follow this shape:
+
+Implemented X.
+Changed files: Y.
+Validation: Z.
+Open risks/questions: R.
+Recommended next step: N.

package/node_modules/pi-subagents/async-retention-discovery-worker.mjs

@@ -0,0 +1,180 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { parentPort } from "node:worker_threads";
+
+const ACTIVE_RUN_INDEX_DIR = ".active-runs";
+const RESULT_TOMBSTONE_PREFIX = ".deleting-result-";
+
+function compareRelative(left, right) {
+	if (left < right) return -1;
+	if (left > right) return 1;
+	return 0;
+}
+
+function insertSmallest(entries, candidate, limit) {
+	if (limit <= 0) return;
+	const index = entries.findIndex((entry) => compareRelative(candidate.relative, entry.relative) < 0);
+	if (index === -1) entries.push(candidate);
+	else entries.splice(index, 0, candidate);
+	if (entries.length > limit) entries.pop();
+}
+
+function streamDirWindow(dir, limit, after, relativePath, usable) {
+	if (limit <= 0) return { entries: [], rawReads: 0, exhausted: true, cursorCleared: false };
+	let handle;
+	try {
+		handle = fs.opendirSync(dir);
+		const next = [];
+		const wrapped = [];
+		let rawReads = 0;
+		while (true) {
+			const entry = handle.readSync();
+			if (!entry) break;
+			rawReads += 1;
+			const relative = relativePath(entry);
+			if (!usable(entry, relative)) continue;
+			const candidate = { relative, name: entry.name };
+			insertSmallest(wrapped, candidate, limit);
+			if (after === undefined || compareRelative(relative, after) > 0) insertSmallest(next, candidate, limit);
+		}
+		const cursorCleared = after !== undefined && next.length === 0;
+		return { entries: cursorCleared ? wrapped : next, rawReads, exhausted: true, cursorCleared };
+	} catch (error) {
+		if (error?.code === "ENOENT") return { entries: [], rawReads: 0, exhausted: true, cursorCleared: false };
+		throw error;
+	} finally {
+		handle?.closeSync();
+	}
+}
+
+function discover(request) {
+	const startedAt = Date.now();
+	const cursor = structuredClone(request.cursor);
+	const raw = { reads: 0, exhausted: {} };
+	const record = (source, scan) => {
+		raw.reads += scan.rawReads;
+		raw.exhausted[source] = scan.exhausted;
+	};
+	const runScan = streamDirWindow(
+		request.asyncDirRoot,
+		request.runBudget,
+		cursor.runAfter,
+		(entry) => entry.name,
+		(entry) => entry.isDirectory() && entry.name !== ACTIVE_RUN_INDEX_DIR,
+	);
+	record("runs", runScan);
+	if (runScan.cursorCleared) delete cursor.runAfter;
+	const runCandidates = runScan.entries.slice(0, request.runBudget);
+	for (const candidate of runCandidates) cursor.runAfter = candidate.relative;
+
+	const resultCandidates = [];
+	const sourceLimit = Math.max(1, Math.ceil(request.resultBudget / 4));
+	const addFiles = (dir, kind, cursorTarget, source, budget = sourceLimit) => {
+		const remaining = Math.min(budget, request.resultBudget - resultCandidates.length);
+		if (remaining <= 0) return 0;
+		const before = resultCandidates.length;
+		const after = cursorTarget.type === "pending"
+			? cursor.resultPendingAfterBySession?.[cursorTarget.session]
+			: cursor[cursorTarget.key];
+		const scan = streamDirWindow(
+			dir,
+			remaining,
+			after,
+			(entry) => path.relative(request.resultsDir, path.join(dir, entry.name)),
+			(entry) => entry.isFile() && (entry.name.startsWith(RESULT_TOMBSTONE_PREFIX) || entry.name.endsWith(".json")),
+		);
+		record(source, scan);
+		if (scan.cursorCleared) {
+			if (cursorTarget.type === "pending") delete cursor.resultPendingAfterBySession?.[cursorTarget.session];
+			else delete cursor[cursorTarget.key];
+		}
+		for (const candidate of scan.entries.slice(0, remaining)) {
+			const tombstone = candidate.name.startsWith(RESULT_TOMBSTONE_PREFIX);
+			resultCandidates.push({
+				name: candidate.name,
+				relative: candidate.relative,
+				kind: tombstone ? "tombstone" : kind,
+				cursor: cursorTarget,
+			});
+			if (cursorTarget.type === "pending") {
+				cursor.resultPendingAfterBySession ??= {};
+				cursor.resultPendingAfterBySession[cursorTarget.session] = candidate.relative;
+			} else cursor[cursorTarget.key] = candidate.relative;
+		}
+		return resultCandidates.length - before;
+	};
+
+	addFiles(request.resultsDir, "public", { type: "result", key: "resultPublicAfter" }, "results.public");
+	const pendingRoot = path.join(request.resultsDir, "result-pending");
+	const pendingRemaining = Math.min(request.resultBudget, sourceLimit, request.resultBudget - resultCandidates.length);
+	const pendingScan = streamDirWindow(
+		pendingRoot,
+		pendingRemaining,
+		cursor.pendingSessionAfter,
+		(entry) => entry.name,
+		(entry) => entry.isDirectory(),
+	);
+	record("results.pendingSessions", pendingScan);
+	const livePendingSessions = new Set(pendingScan.entries.map((entry) => entry.relative));
+	if (cursor.resultPendingAfterBySession) {
+		let pruned = 0;
+		for (const session of Object.keys(cursor.resultPendingAfterBySession).sort()) {
+			if (pruned >= request.resultBudget) break;
+			if (!livePendingSessions.has(session) && !fs.existsSync(path.join(pendingRoot, session))) {
+				delete cursor.resultPendingAfterBySession[session];
+				pruned += 1;
+			}
+		}
+		if (Object.keys(cursor.resultPendingAfterBySession).length === 0) delete cursor.resultPendingAfterBySession;
+	}
+	if (pendingScan.cursorCleared) delete cursor.pendingSessionAfter;
+	const pendingSessions = pendingScan.entries.slice(0, pendingRemaining);
+	let pendingFileBudget = Math.min(sourceLimit, request.resultBudget - resultCandidates.length);
+	for (const session of pendingSessions) {
+		if (pendingFileBudget <= 0) break;
+		cursor.pendingSessionAfter = session.relative;
+		pendingFileBudget -= addFiles(
+			path.join(pendingRoot, session.name),
+			"pending",
+			{ type: "pending", session: session.relative },
+			`results.pending.${session.name}`,
+			pendingFileBudget,
+		);
+	}
+	addFiles(path.join(request.resultsDir, "completion-replay"), "replay", { type: "result", key: "resultReplayAfter" }, "results.replay");
+	addFiles(path.join(request.resultsDir, "output-archives"), "archive", { type: "result", key: "resultArchiveAfter" }, "results.archive");
+
+	const cursorOps = [];
+	for (const key of ["runAfter", "resultPublicAfter", "resultReplayAfter", "resultArchiveAfter", "pendingSessionAfter"]) {
+		if (cursor[key] === request.cursor[key]) continue;
+		cursorOps.push(cursor[key] === undefined ? { type: "delete", key } : { type: "set", key, value: cursor[key] });
+	}
+	const oldPending = request.cursor.resultPendingAfterBySession ?? {};
+	const nextPending = cursor.resultPendingAfterBySession ?? {};
+	for (const session of new Set([...Object.keys(oldPending), ...Object.keys(nextPending)])) {
+		if (oldPending[session] === nextPending[session]) continue;
+		cursorOps.push(nextPending[session] === undefined
+			? { type: "delete-pending", session }
+			: { type: "set-pending", session, value: nextPending[session] });
+	}
+	return {
+		type: "result",
+		passId: request.passId,
+		discoveryDurationMs: Math.max(0, Date.now() - startedAt),
+		rawReads: raw.reads,
+		sourceExhausted: raw.exhausted,
+		runCandidates,
+		resultCandidates,
+		cursorOps,
+	};
+}
+
+if (!parentPort) throw new Error("Async retention discovery requires a worker parent port.");
+parentPort.on("message", (request) => {
+	const passId = request?.passId;
+	try {
+		parentPort.postMessage(discover(request));
+	} catch (error) {
+		parentPort.postMessage({ type: "error", passId, error: error instanceof Error ? error.message : String(error) });
+	}
+});