pi-crew 0.1.45 → 0.1.46

package/src/extension/run-maintenance.ts

@@ -1,43 +1,62 @@
-import * as fs from "node:fs";
-import type { TeamRunManifest } from "../state/types.ts";
-import { resolveRealContainedPath } from "../utils/safe-paths.ts";
-import { projectCrewRoot } from "../utils/paths.ts";
-import { listRuns } from "./run-index.ts";
-import { logInternalError } from "../utils/internal-error.ts";
-
-export interface PruneRunsResult {
-	kept: string[];
-	removed: string[];
-}
-
-function isFinished(run: TeamRunManifest): boolean {
-	return run.status === "completed" || run.status === "failed" || run.status === "cancelled" || run.status === "blocked";
-}
-
-function isSafeToPrune(cwd: string, run: TeamRunManifest): boolean {
-	try {
-		const crewRoot = projectCrewRoot(cwd);
-		resolveRealContainedPath(crewRoot, run.stateRoot);
-		resolveRealContainedPath(crewRoot, run.artifactsRoot);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-export function pruneFinishedRuns(cwd: string, keep: number): PruneRunsResult {
-	const crewRoot = projectCrewRoot(cwd);
-	const finished = listRuns(cwd).filter((run) => run.cwd === cwd && isFinished(run)).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
-	const kept = finished.slice(0, keep).map((run) => run.runId);
-	const removed: string[] = [];
-	for (const run of finished.slice(keep)) {
-		if (!isSafeToPrune(cwd, run)) {
-			logInternalError("prune.path-unsafe", new Error(`Skipping unsafe prune: stateRoot=${run.stateRoot}, artifactsRoot=${run.artifactsRoot}`), `runId=${run.runId}`);
-			continue;
-		}
-		fs.rmSync(run.stateRoot, { recursive: true, force: true });
-		fs.rmSync(run.artifactsRoot, { recursive: true, force: true });
-		removed.push(run.runId);
-	}
-	return { kept, removed };
-}
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { TeamRunManifest } from "../state/types.ts";
+import { resolveRealContainedPath } from "../utils/safe-paths.ts";
+import { projectCrewRoot } from "../utils/paths.ts";
+import { listRuns } from "./run-index.ts";
+import { logInternalError } from "../utils/internal-error.ts";
+import { redactSecrets } from "../utils/redaction.ts";
+
+export interface PruneRunsResult {
+	kept: string[];
+	removed: string[];
+	auditPath?: string;
+}
+
+export interface PruneRunsOptions {
+	intent?: string;
+}
+
+function isFinished(run: TeamRunManifest): boolean {
+	return run.status === "completed" || run.status === "failed" || run.status === "cancelled" || run.status === "blocked";
+}
+
+function isSafeToPrune(cwd: string, run: TeamRunManifest): boolean {
+	try {
+		const crewRoot = projectCrewRoot(cwd);
+		resolveRealContainedPath(crewRoot, run.stateRoot);
+		resolveRealContainedPath(crewRoot, run.artifactsRoot);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+function appendPruneAudit(cwd: string, payload: Record<string, unknown>): string | undefined {
+	try {
+		const filePath = path.join(projectCrewRoot(cwd), "audit", "prune.jsonl");
+		fs.mkdirSync(path.dirname(filePath), { recursive: true });
+		fs.appendFileSync(filePath, `${JSON.stringify(redactSecrets({ ...payload, auditedAt: new Date().toISOString() }))}\n`, "utf-8");
+		return filePath;
+	} catch (error) {
+		logInternalError("prune.audit-write", error, `cwd=${cwd}`);
+		return undefined;
+	}
+}
+
+export function pruneFinishedRuns(cwd: string, keep: number, options: PruneRunsOptions = {}): PruneRunsResult {
+	const finished = listRuns(cwd).filter((run) => run.cwd === cwd && isFinished(run)).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+	const kept = finished.slice(0, keep).map((run) => run.runId);
+	const removed: string[] = [];
+	for (const run of finished.slice(keep)) {
+		if (!isSafeToPrune(cwd, run)) {
+			logInternalError("prune.path-unsafe", new Error(`Skipping unsafe prune: stateRoot=${run.stateRoot}, artifactsRoot=${run.artifactsRoot}`), `runId=${run.runId}`);
+			continue;
+		}
+		fs.rmSync(run.stateRoot, { recursive: true, force: true });
+		fs.rmSync(run.artifactsRoot, { recursive: true, force: true });
+		removed.push(run.runId);
+	}
+	const auditPath = appendPruneAudit(cwd, { action: "prune", keep, intent: options.intent, kept, removed });
+	return { kept, removed, auditPath };
+}

package/src/extension/team-tool/api.ts

@@ -5,7 +5,7 @@ import { loadRunManifestById, saveRunManifest, saveRunTasks, updateRunStatus } f
 import { withRunLockSync } from "../../state/locks.ts";
 import { canTransitionTaskStatus, isTeamTaskStatus } from "../../state/contracts.ts";
 import { claimTask, releaseTaskClaim, transitionClaimedTaskStatus } from "../../state/task-claims.ts";
-import { acknowledgeMailboxMessage, appendMailboxMessage, readDeliveryState, readMailbox, readMailboxMessage, validateMailbox, type MailboxDirection } from "../../state/mailbox.ts";
+import { acknowledgeMailboxMessage, appendFollowUpMessage, appendMailboxMessage, appendSteeringMessage, readDeliveryState, readMailbox, readMailboxMessage, validateMailbox, type MailboxDirection } from "../../state/mailbox.ts";
 import { appendEvent, readEvents, readEventsCursor } from "../../state/event-log.ts";
 import { resolveCrewRuntime } from "../../runtime/runtime-resolver.ts";
 import { probeLiveSessionRuntime } from "../../subagents/live/session-runtime.ts";
@@ -14,7 +14,7 @@ import { touchWorkerHeartbeat } from "../../runtime/worker-heartbeat.ts";
 import { agentOutputPath, readCrewAgentEventsCursor, readCrewAgentStatus, readCrewAgents } from "../../runtime/crew-agent-records.ts";
 import { buildAgentDashboard, readAgentOutput } from "../../runtime/agent-observability.ts";
 import { readForegroundControlStatus, writeForegroundInterruptRequest } from "../../runtime/foreground-control.ts";
-import { getLiveAgent, listLiveAgents, resumeLiveAgent, steerLiveAgent, stopLiveAgent } from "../../subagents/live/manager.ts";
+import { followUpLiveAgent, getLiveAgent, listLiveAgents, resumeLiveAgent, steerLiveAgent, stopLiveAgent } from "../../subagents/live/manager.ts";
 import { appendLiveAgentControlRequest } from "../../subagents/live/control.ts";
 import { liveControlRealtimeMessage, publishLiveControlRealtime } from "../../subagents/live/realtime.ts";
 import { resolveRealContainedPath } from "../../utils/safe-paths.ts";
@@ -212,7 +212,7 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 		const agent = readCrewAgents(loaded.manifest).find((item) => item.id === agentId || item.taskId === agentId);
 		if (!agent) return result("API nudge-agent requires config.agentId matching an agent id or task id.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 		const messageText = typeof cfg.message === "string" && cfg.message.trim() ? cfg.message.trim() : "Please report your current status, blocker, or smallest next step.";
-		const message = appendMailboxMessage(loaded.manifest, { direction: "inbox", from: "leader", to: agent.taskId, taskId: agent.taskId, body: messageText });
+		const message = appendSteeringMessage(loaded.manifest, { taskId: agent.taskId, to: agent.taskId, body: messageText, priority: "normal", data: { source: "nudge-agent" } });
 		appendEvent(loaded.manifest.eventsPath, { type: "agent.nudged", runId: loaded.manifest.runId, taskId: agent.taskId, message: messageText, data: { agentId: agent.id, mailboxMessageId: message.id } });
 		ctx.events?.emit?.("crew.mailbox.message", { runId: loaded.manifest.runId, id: message.id, direction: message.direction, from: message.from, to: message.to, taskId: message.taskId, source: "nudge-agent" });
 		return result(JSON.stringify({ agentId: agent.id, mailboxMessage: message }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
@@ -220,7 +220,7 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 	if (operation === "list-live-agents") {
 		return result(JSON.stringify(listLiveAgents().filter((agent) => agent.runId === loaded.manifest.runId), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 	}
-	if (operation === "steer-agent" || operation === "stop-agent" || operation === "resume-agent" || operation === "interrupt-agent") {
+	if (operation === "steer-agent" || operation === "follow-up-agent" || operation === "stop-agent" || operation === "resume-agent" || operation === "interrupt-agent") {
 		const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
 		if (!agentId) return result(`API ${operation} requires config.agentId.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 		const message = typeof cfg.message === "string" && cfg.message.trim() ? cfg.message.trim() : undefined;
@@ -228,7 +228,22 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 		try {
 			const live = getLiveAgent(agentId);
 			if (live && live.runId !== loaded.manifest.runId) return result(`Live agent '${agentId}' does not belong to run ${loaded.manifest.runId}.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
-			if (operation === "steer-agent") return result(JSON.stringify(await steerLiveAgent(agentId, message ?? "Please report current status and wrap up if possible."), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			if (!live && (operation === "steer-agent" || operation === "follow-up-agent")) throw new Error(`Live agent '${agentId}' not found.`);
+			const liveTaskId = live?.taskId;
+			if ((operation === "steer-agent" || operation === "follow-up-agent") && !liveTaskId) throw new Error(`Live agent '${agentId}' not found.`);
+			const targetTaskId = liveTaskId ?? agentId;
+			if (operation === "steer-agent") {
+				const text = message ?? "Please report current status and wrap up if possible.";
+				const realtime = await steerLiveAgent(agentId, text);
+				const mailboxMessage = appendSteeringMessage(loaded.manifest, { taskId: targetTaskId, body: text, status: "delivered", data: { source: "steer-agent", realtime: true } });
+				return result(JSON.stringify({ realtime, mailboxMessage }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			}
+			if (operation === "follow-up-agent") {
+				if (!prompt) return result("API follow-up-agent requires config.prompt or config.message.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+				const realtime = await followUpLiveAgent(agentId, prompt);
+				const mailboxMessage = appendFollowUpMessage(loaded.manifest, { taskId: targetTaskId, body: prompt, status: "delivered", data: { source: "follow-up-agent", realtime: true } });
+				return result(JSON.stringify({ realtime, mailboxMessage }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+			}
 			if (operation === "resume-agent") {
 				if (!prompt) return result("API resume-agent requires config.prompt or config.message.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 				return result(JSON.stringify(await resumeLiveAgent(agentId, prompt), null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
@@ -243,12 +258,14 @@ export async function handleApi(params: TeamToolParamsValue, ctx: TeamContext):
 			const task = loaded.tasks.find((item) => item.id === agent.taskId);
 			if (!task) return result(`API ${operation} agent '${agentId}' does not match a run task.`, { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 			if (operation === "resume-agent" && !prompt) return result("API resume-agent requires config.prompt or config.message.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
+			if (operation === "follow-up-agent" && !prompt) return result("API follow-up-agent requires config.prompt or config.message.", { action: "api", status: "error", runId: loaded.manifest.runId }, true);
 			try {
-				const request = appendLiveAgentControlRequest(loaded.manifest, { taskId: task.id, agentId: agent.id, operation: operation === "resume-agent" ? "resume" : operation === "steer-agent" ? "steer" : "stop", message: operation === "resume-agent" ? prompt : message });
+				const request = appendLiveAgentControlRequest(loaded.manifest, { taskId: task.id, agentId: agent.id, operation: operation === "resume-agent" ? "resume" : operation === "follow-up-agent" ? "follow-up" : operation === "steer-agent" ? "steer" : "stop", message: operation === "resume-agent" || operation === "follow-up-agent" ? prompt : message });
+				const mailboxMessage = operation === "steer-agent" ? appendSteeringMessage(loaded.manifest, { taskId: task.id, to: agent.id, body: message ?? "Please report current status and wrap up if possible.", status: "delivered", data: { source: "steer-agent", liveControlRequestId: request.id } }) : operation === "follow-up-agent" && prompt ? appendFollowUpMessage(loaded.manifest, { taskId: task.id, to: agent.id, body: prompt, status: "delivered", data: { source: "follow-up-agent", liveControlRequestId: request.id } }) : undefined;
 				publishLiveControlRealtime(request);
 				ctx.events?.emit?.("pi-crew:live-control", liveControlRealtimeMessage(request));
-				appendEvent(loaded.manifest.eventsPath, { type: "agent.control.queued", runId: loaded.manifest.runId, taskId: agent.taskId, message: `Queued ${request.operation} control request for live agent.`, data: { request, realtime: true } });
-				return result(JSON.stringify({ queued: true, request }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
+				appendEvent(loaded.manifest.eventsPath, { type: "agent.control.queued", runId: loaded.manifest.runId, taskId: agent.taskId, message: `Queued ${request.operation} control request for live agent.`, data: { request, mailboxMessageId: mailboxMessage?.id, realtime: true } });
+				return result(JSON.stringify({ queued: true, request, mailboxMessage }, null, 2), { action: "api", status: "ok", runId: loaded.manifest.runId, artifactsRoot: loaded.manifest.artifactsRoot });
 			} catch (queueError) {
 				const message = queueError instanceof Error ? queueError.message : String(queueError);
 				return result(message, { action: "api", status: "error", runId: loaded.manifest.runId }, true);

package/src/extension/team-tool/cancel.ts

@@ -3,6 +3,8 @@ import { withRunLockSync } from "../../state/locks.ts";
 import { loadRunManifestById, saveRunTasks, updateRunStatus } from "../../state/state-store.ts";
 import { saveCrewAgents, recordFromTask } from "../../runtime/crew-agent-records.ts";
 import { writeForegroundInterruptRequest } from "../../runtime/foreground-control.ts";
+import { cancellationReasonFromUnknown } from "../../runtime/cancellation.ts";
+import { appendEvent } from "../../state/event-log.ts";
 import { logInternalError } from "../../utils/internal-error.ts";
 import type { PiTeamsToolResult } from "../tool-result.ts";
 import { result, type TeamContext } from "./context.ts";
@@ -55,6 +57,25 @@ export function abortOwned(
 	return result;
 }
 
+function configFromParams(params: TeamToolParamsValue): Record<string, unknown> | undefined {
+	return params.config && typeof params.config === "object" && !Array.isArray(params.config) ? params.config : undefined;
+}
+
+function cancelReasonFromParams(params: TeamToolParamsValue): { code: string; message: string } {
+	const config = configFromParams(params);
+	const rawReason = config?.reason ?? config?.cancelReason;
+	const reason = rawReason === undefined ? { code: "caller_cancelled" as const, message: "Run cancelled by user request." } : cancellationReasonFromUnknown(rawReason);
+	return { code: reason.code, message: reason.message };
+}
+
+function intentFromParams(params: TeamToolParamsValue): string | undefined {
+	const config = configFromParams(params);
+	const rawIntent = config?.intent ?? config?._intent;
+	if (typeof rawIntent !== "string") return undefined;
+	const intent = rawIntent.replace(/\s+/g, " ").trim();
+	return intent ? intent.slice(0, 500) : undefined;
+}
+
 export function handleCancel(params: TeamToolParamsValue, ctx: TeamContext): PiTeamsToolResult {
 	if (!params.runId) return result("Cancel requires runId.", { action: "cancel", status: "error" }, true);
 	const loaded = loadRunManifestById(ctx.cwd, params.runId);
@@ -65,13 +86,17 @@ export function handleCancel(params: TeamToolParamsValue, ctx: TeamContext): PiT
 		// Classify tasks for foreign-aware cancellation
 		const abortResult = abortOwned(loaded.manifest.runId, undefined, ctx);
 		if (abortResult.abortedIds.length === 0 && abortResult.foreignIds.length > 0) {
-			return result(`Run ${loaded.manifest.runId} belongs to another session; not cancelled.`, { action: "cancel", status: "error", runId: loaded.manifest.runId, foreignIds: abortResult.foreignIds } as never, true);
+			return result(`Run ${loaded.manifest.runId} belongs to another session; not cancelled.`, { action: "cancel", status: "error", runId: loaded.manifest.runId, foreignIds: abortResult.foreignIds }, true);
 		}
 		const cancellableIds = new Set(abortResult.abortedIds);
+		const cancelReason = cancelReasonFromParams(params);
+		const cancelIntent = intentFromParams(params);
+		const cancelData = cancelIntent ? { reason: cancelReason.code, intent: cancelIntent } : { reason: cancelReason.code };
+		const cancelMessage = `${cancelReason.message} (${cancelReason.code})`;
 
 		const tasks = loaded.tasks.map((task) => {
 			if (cancellableIds.has(task.id) && (task.status === "queued" || task.status === "running" || task.status === "waiting")) {
-				return { ...task, status: "cancelled" as const, finishedAt: new Date().toISOString(), error: "Run cancelled by user request." };
+				return { ...task, status: "cancelled" as const, finishedAt: new Date().toISOString(), error: cancelMessage };
 			}
 			return task;
 		});
@@ -82,11 +107,14 @@ export function handleCancel(params: TeamToolParamsValue, ctx: TeamContext): PiT
 			logInternalError("team-tool.handleCancel.crewAgents", error, `runId=${loaded.manifest.runId}`);
 		}
 		try {
-			writeForegroundInterruptRequest(loaded.manifest, "Run cancelled by user request.");
+			writeForegroundInterruptRequest(loaded.manifest, cancelMessage);
 		} catch (error) {
 			logInternalError("team-tool.handleCancel.interruptRequest", error, `runId=${loaded.manifest.runId}`);
 		}
-		const updated = updateRunStatus(loaded.manifest, "cancelled", "Run cancelled by user request. Already-finished worker processes are not retroactively changed.");
+		for (const taskId of abortResult.abortedIds) {
+			appendEvent(loaded.manifest.eventsPath, { type: "task.cancelled", runId: loaded.manifest.runId, taskId, message: cancelMessage, data: cancelData });
+		}
+		const updated = updateRunStatus(loaded.manifest, "cancelled", `${cancelMessage} Already-finished worker processes are not retroactively changed.`, { data: cancelData });
 
 		// Build descriptive message including foreign/missing info
 		const parts = [`Cancelled run ${updated.runId}.`];
@@ -101,6 +129,7 @@ export function handleCancel(params: TeamToolParamsValue, ctx: TeamContext): PiT
 			abortedIds: abortResult.abortedIds,
 			missingIds: abortResult.missingIds,
 			foreignIds: abortResult.foreignIds,
+			intent: cancelIntent,
 		});
 	});
 }

package/src/extension/team-tool/context.ts

@@ -15,6 +15,11 @@ export type TeamContext = Pick<ExtensionContext, "cwd"> & Partial<Pick<Extension
 	onJsonEvent?: (taskId: string, runId: string, event: unknown) => void;
 };
 
+export function withSessionId<T extends Pick<ExtensionContext, "sessionManager">>(ctx: T): T & { sessionId?: string } {
+	const sessionId = ctx.sessionManager.getSessionId();
+	return sessionId ? { ...ctx, sessionId } : { ...ctx };
+}
+
 export function result(text: string, details: TeamToolDetails, isError = false): PiTeamsToolResult {
 	return toolResult(text, details, isError);
 }