@agwab/pi-workflow 0.2.1 → 0.3.0

package/node_modules/@agwab/pi-subagent/src/orchestrate/interrupt.ts

@@ -1,111 +1,187 @@
-import { appendRunEvent, readRunRecord, recordInterruptRequest, type RunAttemptRecord, type RunRecord } from "../artifacts/index.ts";
+import {
+	appendRunEvent,
+	readRunRecord,
+	recordInterruptRequest,
+	type RunAttemptRecord,
+	type RunRecord,
+} from "../artifacts/index.ts";
+import { resolveRunRef } from "./run-ref.ts";
 import { isTerminalStatus } from "./status.ts";
 
 export interface InterruptRunOptions {
-  cwd?: string;
-  runId: string;
-  runsDir?: string;
-  attemptId?: string;
-  /** @deprecated v1 compatibility alias. */
-  taskId?: string;
-  reason?: string;
-  signal?: NodeJS.Signals;
-  escalateAfterMs?: number;
-  killAfterMs?: number;
+	cwd?: string;
+	runId: string;
+	runsDir?: string;
+	attemptId?: string;
+	/** @deprecated v1 compatibility alias. */
+	taskId?: string;
+	reason?: string;
+	signal?: NodeJS.Signals;
+	escalateAfterMs?: number;
+	killAfterMs?: number;
 }
 
 export interface InterruptRunResult {
-  status: "interrupt-requested" | "not-found" | "already-terminal" | "unsupported";
-  runId: string;
-  signal: NodeJS.Signals;
-  interruptedAttempts: string[];
-  unsupportedAttempts: string[];
-  /** @deprecated v1 compatibility alias. */
-  interruptedTasks: string[];
-  /** @deprecated v1 compatibility alias. */
-  unsupportedTasks: string[];
-  record: RunRecord | null;
+	status:
+		| "interrupt-requested"
+		| "not-found"
+		| "already-terminal"
+		| "unsupported";
+	runId: string;
+	signal: NodeJS.Signals;
+	interruptedAttempts: string[];
+	unsupportedAttempts: string[];
+	/** @deprecated v1 compatibility alias. */
+	interruptedTasks: string[];
+	/** @deprecated v1 compatibility alias. */
+	unsupportedTasks: string[];
+	record: RunRecord | null;
 }
 
-function sendProcessSignal(attempt: RunAttemptRecord, signal: NodeJS.Signals): boolean {
-  const pid = attempt.process?.pid;
-  if (pid === undefined) return false;
-  try {
-    const target = process.platform === "win32" ? pid : -(attempt.process?.processGroupId ?? pid);
-    process.kill(target, signal);
-    return true;
-  } catch {
-    try {
-      process.kill(pid, signal);
-      return true;
-    } catch {
-      return false;
-    }
-  }
+function sendProcessSignal(
+	attempt: RunAttemptRecord,
+	signal: NodeJS.Signals,
+): boolean {
+	const pid = attempt.process?.pid;
+	if (pid === undefined) return false;
+	try {
+		const target =
+			process.platform === "win32"
+				? pid
+				: -(attempt.process?.processGroupId ?? pid);
+		process.kill(target, signal);
+		return true;
+	} catch {
+		try {
+			process.kill(pid, signal);
+			return true;
+		} catch {
+			return false;
+		}
+	}
 }
 
-function runningAttempts(record: RunRecord, targetAttemptId?: string): RunAttemptRecord[] {
-  return record.attempts.filter((attempt) => {
-    if (targetAttemptId !== undefined && attempt.attemptId !== targetAttemptId) return false;
-    return attempt.status === "running" || attempt.status === "pending";
-  });
+function runningAttempts(
+	record: RunRecord,
+	targetAttemptId?: string,
+): RunAttemptRecord[] {
+	return record.attempts.filter((attempt) => {
+		if (targetAttemptId !== undefined && attempt.attemptId !== targetAttemptId)
+			return false;
+		return attempt.status === "running" || attempt.status === "pending";
+	});
 }
 
-async function escalate(options: InterruptRunOptions, signal: NodeJS.Signals): Promise<void> {
-  const record = await readRunRecord(options).catch(() => null);
-  if (record === null || isTerminalStatus(record.status)) return;
-  for (const attempt of runningAttempts(record, options.attemptId ?? options.taskId)) sendProcessSignal(attempt, signal);
-  await appendRunEvent(options, { type: "run.interrupt_requested", status: record.status, message: `interrupt escalation ${signal}`, data: { signal } }).catch(() => undefined);
+async function escalate(
+	options: InterruptRunOptions,
+	signal: NodeJS.Signals,
+): Promise<void> {
+	const ref = await resolveRunRef(options);
+	const record = await readRunRecord(ref).catch(() => null);
+	if (record === null || isTerminalStatus(record.status)) return;
+	for (const attempt of runningAttempts(
+		record,
+		options.attemptId ?? options.taskId,
+	))
+		sendProcessSignal(attempt, signal);
+	await appendRunEvent(ref, {
+		type: "run.interrupt_requested",
+		status: record.status,
+		message: `interrupt escalation ${signal}`,
+		data: { signal },
+	}).catch(() => undefined);
 }
 
-function result(status: InterruptRunResult["status"], runId: string, signal: NodeJS.Signals, interruptedAttempts: string[], unsupportedAttempts: string[], record: RunRecord | null): InterruptRunResult {
-  return {
-    status,
-    runId,
-    signal,
-    interruptedAttempts,
-    unsupportedAttempts,
-    interruptedTasks: interruptedAttempts,
-    unsupportedTasks: unsupportedAttempts,
-    record,
-  };
+function result(
+	status: InterruptRunResult["status"],
+	runId: string,
+	signal: NodeJS.Signals,
+	interruptedAttempts: string[],
+	unsupportedAttempts: string[],
+	record: RunRecord | null,
+): InterruptRunResult {
+	return {
+		status,
+		runId,
+		signal,
+		interruptedAttempts,
+		unsupportedAttempts,
+		interruptedTasks: interruptedAttempts,
+		unsupportedTasks: unsupportedAttempts,
+		record,
+	};
 }
 
-export async function interruptRun(options: InterruptRunOptions): Promise<InterruptRunResult> {
-  const signal = options.signal ?? "SIGINT";
-  const record = await readRunRecord(options);
-  if (record === null) {
-    return result("not-found", options.runId, signal, [], [], null);
-  }
-  if (isTerminalStatus(record.status)) {
-    return result("already-terminal", options.runId, signal, [], [], record);
-  }
+export async function interruptRun(
+	options: InterruptRunOptions,
+): Promise<InterruptRunResult> {
+	const signal = options.signal ?? "SIGINT";
+	const ref = await resolveRunRef(options);
+	const record = await readRunRecord(ref);
+	if (record === null) {
+		return result("not-found", options.runId, signal, [], [], null);
+	}
+	if (isTerminalStatus(record.status)) {
+		return result("already-terminal", options.runId, signal, [], [], record);
+	}
 
-  const candidates = runningAttempts(record, options.attemptId ?? options.taskId);
-  const interruptedAttempts: string[] = [];
-  const unsupportedAttempts: string[] = [];
-  for (const attempt of candidates) {
-    if (sendProcessSignal(attempt, signal)) interruptedAttempts.push(attempt.attemptId);
-    else unsupportedAttempts.push(attempt.attemptId);
-  }
+	const candidates = runningAttempts(
+		record,
+		options.attemptId ?? options.taskId,
+	);
+	const interruptedAttempts: string[] = [];
+	const unsupportedAttempts: string[] = [];
+	for (const attempt of candidates) {
+		if (sendProcessSignal(attempt, signal))
+			interruptedAttempts.push(attempt.attemptId);
+		else unsupportedAttempts.push(attempt.attemptId);
+	}
 
-  if (interruptedAttempts.length === 0) {
-    await appendRunEvent(options, { type: "run.interrupt_requested", status: record.status, message: "interrupt unsupported: no interruptable process metadata", data: { signal, unsupportedAttempts } });
-    return result("unsupported", options.runId, signal, interruptedAttempts, unsupportedAttempts, record);
-  }
+	if (interruptedAttempts.length === 0) {
+		await appendRunEvent(ref, {
+			type: "run.interrupt_requested",
+			status: record.status,
+			message: "interrupt unsupported: no interruptable process metadata",
+			data: { signal, unsupportedAttempts },
+		});
+		return result(
+			"unsupported",
+			options.runId,
+			signal,
+			interruptedAttempts,
+			unsupportedAttempts,
+			record,
+		);
+	}
 
-  const updated = await recordInterruptRequest(options, signal, options.reason ?? null);
-  await appendRunEvent(options, {
-    type: "run.interrupt_requested",
-    status: updated.status,
-    message: `interrupt requested with ${signal}`,
-    data: { signal, interruptedAttempts, unsupportedAttempts, reason: options.reason ?? null },
-  });
+	const updated = await recordInterruptRequest(
+		ref,
+		signal,
+		options.reason ?? null,
+	);
+	await appendRunEvent(ref, {
+		type: "run.interrupt_requested",
+		status: updated.status,
+		message: `interrupt requested with ${signal}`,
+		data: {
+			signal,
+			interruptedAttempts,
+			unsupportedAttempts,
+			reason: options.reason ?? null,
+		},
+	});
 
-  const termDelay = options.escalateAfterMs ?? 1_000;
-  const killDelay = options.killAfterMs ?? 3_000;
-  setTimeout(() => void escalate(options, "SIGTERM"), termDelay).unref?.();
-  setTimeout(() => void escalate(options, "SIGKILL"), killDelay).unref?.();
+	const termDelay = options.escalateAfterMs ?? 1_000;
+	const killDelay = options.killAfterMs ?? 3_000;
+	setTimeout(() => void escalate(ref, "SIGTERM"), termDelay).unref?.();
+	setTimeout(() => void escalate(ref, "SIGKILL"), killDelay).unref?.();
 
-  return result("interrupt-requested", options.runId, signal, interruptedAttempts, unsupportedAttempts, updated);
+	return result(
+		"interrupt-requested",
+		options.runId,
+		signal,
+		interruptedAttempts,
+		unsupportedAttempts,
+		updated,
+	);
 }

package/node_modules/@agwab/pi-subagent/src/orchestrate/reconcile.ts

@@ -1,98 +1,144 @@
 import { readFile } from "node:fs/promises";
 import { isAbsolute, resolve, sep } from "node:path";
 import {
-  appendRunEvent,
-  commitAttemptResultIfActive,
-  readRunRecord,
-  upsertRunAttempt,
-  type ResultEnvelope,
-  type RunAttemptRecord,
-  type RunRef,
-  type RunRecord,
+	appendRunEvent,
+	commitAttemptResultIfActive,
+	readRunRecord,
+	upsertRunAttempt,
+	type ResultEnvelope,
+	type RunAttemptRecord,
+	type RunRef,
+	type RunRecord,
 } from "../artifacts/index.ts";
+import { resolveRunRef } from "./run-ref.ts";
 import { isTerminalStatus } from "./status.ts";
 
 export interface ReconcileSubagentRunOptions extends RunRef {
-  staleAfterMs?: number;
+	staleAfterMs?: number;
 }
 
 export interface ReconcileSubagentRunResult {
-  status: "not-found" | "already-terminal" | "running" | "committed-result" | "marked-stale";
-  runId: string;
-  record: RunRecord | null;
+	status:
+		| "not-found"
+		| "already-terminal"
+		| "running"
+		| "committed-result"
+		| "marked-stale";
+	runId: string;
+	record: RunRecord | null;
 }
 
 function safeArtifactPath(attempt: RunAttemptRecord): string | null {
-  if (attempt.resultPath === undefined || attempt.artifactCwd === undefined) return null;
-  if (isAbsolute(attempt.resultPath) || attempt.resultPath.split("/").includes("..")) return null;
-  return resolve(attempt.artifactCwd, attempt.resultPath.split("/").join(sep));
+	if (attempt.resultPath === undefined || attempt.artifactCwd === undefined)
+		return null;
+	if (
+		isAbsolute(attempt.resultPath) ||
+		attempt.resultPath.split("/").includes("..")
+	)
+		return null;
+	return resolve(attempt.artifactCwd, attempt.resultPath.split("/").join(sep));
 }
 
-async function readAttemptResult(attempt: RunAttemptRecord): Promise<ResultEnvelope | null> {
-  const path = safeArtifactPath(attempt);
-  if (path === null) return null;
-  try {
-    return JSON.parse(await readFile(path, "utf8")) as ResultEnvelope;
-  } catch {
-    return null;
-  }
+async function readAttemptResult(
+	attempt: RunAttemptRecord,
+): Promise<ResultEnvelope | null> {
+	const path = safeArtifactPath(attempt);
+	if (path === null) return null;
+	try {
+		return JSON.parse(await readFile(path, "utf8")) as ResultEnvelope;
+	} catch {
+		return null;
+	}
 }
 
 function pidAlive(pid: number | undefined): boolean {
-  if (pid === undefined) return false;
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
+	if (pid === undefined) return false;
+	try {
+		process.kill(pid, 0);
+		return true;
+	} catch {
+		return false;
+	}
 }
 
 function processAlive(attempt: RunAttemptRecord): boolean {
-  return pidAlive(attempt.process?.pid) || pidAlive(attempt.process?.workerPid);
+	return pidAlive(attempt.process?.pid) || pidAlive(attempt.process?.workerPid);
 }
 
-function heartbeatFresh(attempt: RunAttemptRecord, staleAfterMs: number): boolean {
-  if (attempt.heartbeatAt === undefined) return false;
-  const time = Date.parse(attempt.heartbeatAt);
-  return Number.isFinite(time) && Date.now() - time <= staleAfterMs;
+function heartbeatFresh(
+	attempt: RunAttemptRecord,
+	staleAfterMs: number,
+): boolean {
+	if (attempt.heartbeatAt === undefined) return false;
+	const time = Date.parse(attempt.heartbeatAt);
+	return Number.isFinite(time) && Date.now() - time <= staleAfterMs;
 }
 
 function activeAttempt(record: RunRecord): RunAttemptRecord | undefined {
-  const activeId = record.activeAttemptId ?? record.latestAttemptId ?? undefined;
-  return activeId === undefined ? record.attempts.at(-1) : record.attempts.find((attempt) => attempt.attemptId === activeId) ?? record.attempts.at(-1);
+	const activeId =
+		record.activeAttemptId ?? record.latestAttemptId ?? undefined;
+	return activeId === undefined
+		? record.attempts.at(-1)
+		: (record.attempts.find((attempt) => attempt.attemptId === activeId) ??
+				record.attempts.at(-1));
 }
 
-export async function reconcileSubagentRun(options: ReconcileSubagentRunOptions): Promise<ReconcileSubagentRunResult> {
-  const staleAfterMs = options.staleAfterMs ?? 30_000;
-  const record = await readRunRecord(options);
-  if (record === null) return { status: "not-found", runId: options.runId, record: null };
-  if (isTerminalStatus(record.status)) return { status: "already-terminal", runId: options.runId, record };
+export async function reconcileSubagentRun(
+	options: ReconcileSubagentRunOptions,
+): Promise<ReconcileSubagentRunResult> {
+	const staleAfterMs = options.staleAfterMs ?? 30_000;
+	const ref = await resolveRunRef(options);
+	const record = await readRunRecord(ref);
+	if (record === null)
+		return { status: "not-found", runId: options.runId, record: null };
+	if (isTerminalStatus(record.status))
+		return { status: "already-terminal", runId: options.runId, record };
 
-  const attempt = activeAttempt(record);
-  if (attempt === undefined) return { status: "running", runId: options.runId, record };
+	const attempt = activeAttempt(record);
+	if (attempt === undefined)
+		return { status: "running", runId: options.runId, record };
 
-  const result = await readAttemptResult(attempt);
-  if (result !== null && result.attemptId === attempt.attemptId && isTerminalStatus(result.status)) {
-    const committed = await commitAttemptResultIfActive(options, result);
-    await appendRunEvent(options, { type: "reconcile.completed", attemptId: attempt.attemptId, status: result.status, message: committed.committed ? "committed terminal attempt result" : "terminal attempt result was stale" }).catch(() => undefined);
-    return { status: committed.committed ? "committed-result" : "running", runId: options.runId, record: committed.record };
-  }
+	const result = await readAttemptResult(attempt);
+	if (
+		result !== null &&
+		result.attemptId === attempt.attemptId &&
+		isTerminalStatus(result.status)
+	) {
+		const committed = await commitAttemptResultIfActive(ref, result);
+		await appendRunEvent(ref, {
+			type: "reconcile.completed",
+			attemptId: attempt.attemptId,
+			status: result.status,
+			message: committed.committed
+				? "committed terminal attempt result"
+				: "terminal attempt result was stale",
+		}).catch(() => undefined);
+		return {
+			status: committed.committed ? "committed-result" : "running",
+			runId: options.runId,
+			record: committed.record,
+		};
+	}
 
-  if (processAlive(attempt) || heartbeatFresh(attempt, staleAfterMs)) {
-    return { status: "running", runId: options.runId, record };
-  }
+	if (processAlive(attempt) || heartbeatFresh(attempt, staleAfterMs)) {
+		return { status: "running", runId: options.runId, record };
+	}
 
-  const updated = await upsertRunAttempt({
-    ...options,
-    attemptId: attempt.attemptId,
-    status: "failed",
-    backend: attempt.backend,
-    failureKind: "stale",
-    startedAt: attempt.startedAt,
-    completedAt: new Date(),
-    activate: true,
-  });
-  await appendRunEvent(options, { type: "reconcile.failed", attemptId: attempt.attemptId, status: "failed", message: "active attempt is stale/orphaned" }).catch(() => undefined);
-  return { status: "marked-stale", runId: options.runId, record: updated };
+	const updated = await upsertRunAttempt({
+		...ref,
+		attemptId: attempt.attemptId,
+		status: "failed",
+		backend: attempt.backend,
+		failureKind: "stale",
+		startedAt: attempt.startedAt,
+		completedAt: new Date(),
+		activate: true,
+	});
+	await appendRunEvent(ref, {
+		type: "reconcile.failed",
+		attemptId: attempt.attemptId,
+		status: "failed",
+		message: "active attempt is stale/orphaned",
+	}).catch(() => undefined);
+	return { status: "marked-stale", runId: options.runId, record: updated };
 }