@sgtbeatdown/pi-tasks 0.1.0 → 0.1.2

package/src/legacy-extension.ts

@@ -0,0 +1,248 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+
+import {
+	DEFAULT_TASK_TIMEOUT_MS,
+	GatewayClientError,
+	MAX_TASK_TIMEOUT_MS,
+	MIN_TASK_TIMEOUT_MS,
+	createWolfpackGatewayClient,
+	type TaskCompletionInput,
+	type TaskStatus,
+	type WolfpackGatewayClient,
+} from "./gateway-client";
+import { deliverTaskInbox, restoredInboxCursor } from "./legacy-task-inbox";
+
+const BACKGROUND_POLL_MS = 5_000;
+const WAIT_POLL_MS = 250;
+const SUMMARY_MAX_CHARS = 1_200;
+
+const AddressParams = Type.Object({
+	machine: Type.String({ minLength: 1, description: "local or a canonical Wolfpack machine identity" }),
+	sessionId: Type.String({ minLength: 1, description: "Stable opaque Wolfpack broker session id" }),
+});
+
+const ContextRefParams = Type.Object({
+	path: Type.String({ minLength: 1 }),
+	selector: Type.Optional(Type.String()),
+	purpose: Type.Optional(Type.String()),
+});
+
+const SendParams = Type.Object({
+	to: AddressParams,
+	task: Type.String({ minLength: 1, maxLength: 16 * 1024 }),
+	context: Type.Optional(Type.Object({
+		summary: Type.Optional(Type.String({ minLength: 1, maxLength: 16 * 1024 })),
+		refs: Type.Optional(Type.Array(ContextRefParams)),
+	})),
+	role: Type.Optional(Type.String()),
+	preflight: Type.Optional(Type.Object({ requiredProject: Type.Optional(Type.String()) })),
+	metadata: Type.Optional(Type.Object({
+		phaseId: Type.Optional(Type.String()),
+		issueId: Type.Optional(Type.String()),
+		verificationTier: Type.Optional(Type.String()),
+		rootCause: Type.Optional(Type.String()),
+	})),
+	onCompletePrompt: Type.Optional(Type.String({ maxLength: 4_000 })),
+	timeoutMs: Type.Optional(Type.Integer({ minimum: MIN_TASK_TIMEOUT_MS, maximum: MAX_TASK_TIMEOUT_MS })),
+	idempotencyKey: Type.Optional(Type.String({ minLength: 1 })),
+});
+
+const TaskIdParams = Type.Object({ taskId: Type.String({ minLength: 1 }) });
+const WaitParams = Type.Object({ taskId: Type.String({ minLength: 1 }), timeoutMs: Type.Optional(Type.Integer({ minimum: MIN_TASK_TIMEOUT_MS, maximum: MAX_TASK_TIMEOUT_MS })) });
+const InboxParams = Type.Object({ includeAcknowledged: Type.Optional(Type.Boolean({ default: false })) });
+const MessageParams = Type.Object({
+	taskId: Type.String({ minLength: 1 }),
+	type: StringEnum(["question", "answer", "information"] as const),
+	message: Type.String({ minLength: 1, maxLength: 16 * 1024 }),
+	replyToMessageId: Type.Optional(Type.String({ minLength: 1 })),
+});
+const DoneParams = Type.Object({
+	taskId: Type.String({ minLength: 1 }),
+	status: StringEnum(["completed", "failed", "cancelled"] as const),
+	summary: Type.String({ minLength: 1, maxLength: SUMMARY_MAX_CHARS }),
+	result: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+	error: Type.Optional(Type.Object({ code: Type.String(), message: Type.String(), retryable: Type.Boolean() })),
+	artifacts: Type.Optional(Type.Array(Type.Object({ path: Type.String({ minLength: 1, description: "artifact paths must name receiver-project-relative regular files to inspect; artifacts are not a changed-file list." }), mimeType: Type.Optional(Type.String()), description: Type.Optional(Type.String()) }))),
+});
+
+export function registerAgentTaskTools(pi: ExtensionAPI, client: WolfpackGatewayClient = createWolfpackGatewayClient()): void {
+	let backgroundTimer: ReturnType<typeof setInterval> | undefined;
+	let inboxContext: ExtensionContext | undefined;
+	const refreshInbox = createSingleFlightInboxRefresh(async () => {
+		if (!inboxContext) return;
+		const cursor = restoredInboxCursor(inboxContext.sessionManager.getEntries());
+		await deliverTaskInbox(pi, client, inboxContext, cursor);
+	});
+
+	pi.on("session_start", async (_event, ctx) => {
+		inboxContext = ctx;
+		ctx.ui.setStatus("wolfpack-tasks", ctx.ui.theme.fg("dim", `tasks: ${client.callerSession}`));
+		backgroundTimer = setInterval(() => {
+			void refreshInbox().catch(() => ctx.ui.setStatus("wolfpack-tasks", ctx.ui.theme.fg("warning", "tasks: unavailable")));
+		}, BACKGROUND_POLL_MS);
+		await refreshInbox().catch(() => undefined);
+	});
+	pi.on("agent_end", async (_event, ctx) => {
+		inboxContext = ctx;
+		setTimeout(() => { void refreshInbox().catch(() => undefined); }, 0);
+	});
+	pi.on("session_shutdown", () => {
+		if (backgroundTimer) clearInterval(backgroundTimer);
+		backgroundTimer = undefined;
+		inboxContext = undefined;
+	});
+
+	pi.registerTool({
+		name: "agent_task_send", label: "Send Agent Task", description: "Durably send a bounded task to an existing Wolfpack Pi session.",
+		promptSnippet: "Send nonblocking structured tasks through the local Wolfpack gateway",
+		promptGuidelines: ["Use agent_task_send for normal nonblocking delegation; do not wait unless the user explicitly asks."],
+		parameters: SendParams,
+		async execute(_toolCallId, params, signal) {
+			try {
+				const receipt = await client.send(params, signal);
+				return toolResult(receipt, `## task accepted\n- task: \`${receipt.taskId}\`\n- target: \`${params.to.machine}/${params.to.sessionId}\`\n- delivery: pending adapter insertion (confirmed by \`task.delivered\`)\n${warnings(receipt.warnings)}`);
+			} catch (error) { return clientError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+	});
+
+	pi.registerTool({
+		name: "agent_task_status", label: "Task Status", description: "Read compact structured task status from Wolfpack.", parameters: TaskIdParams,
+		async execute(_toolCallId, params, signal) {
+			try { const status = await client.status(params.taskId, signal); return statusResult(status); } catch (error) { return clientError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+	});
+
+	pi.registerTool({
+		name: "agent_task_wait", label: "Wait Agent Task", description: "Block only when explicitly invoked until a task reaches a terminal state or this wait times out.", parameters: WaitParams,
+		async execute(_toolCallId, params, signal, onUpdate) {
+			const deadline = Date.now() + (params.timeoutMs ?? DEFAULT_TASK_TIMEOUT_MS);
+			try {
+				for (;;) {
+					throwIfAborted(signal);
+					const status = await client.status(params.taskId, signal);
+					if (terminal(status.status)) return statusResult(status);
+					if (Date.now() >= deadline) return toolResult({ taskId: params.taskId, status: status.status, error: { code: "WAIT_TIMEOUT", retryable: true } }, `## task wait\n- task: \`${params.taskId}\`\n- status: ${status.status}\n- wait timed out`);
+					onUpdate?.({ content: [{ type: "text", text: `waiting for ${params.taskId}...` }], details: {} });
+					await sleep(Math.min(WAIT_POLL_MS, Math.max(1, deadline - Date.now())), signal);
+				}
+			} catch (error) { return clientError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+	});
+
+	pi.registerTool({
+		name: "agent_task_inbox", label: "Task Inbox", description: "Read inbox task events without acknowledging them.", parameters: InboxParams,
+		async execute(_toolCallId, params, signal) {
+			try {
+				let cursor = "0";
+				const taskIds = new Set<string>();
+				for (;;) {
+					const page = await client.inbox(cursor, params.includeAcknowledged ?? false, signal);
+					for (const event of page.events) taskIds.add(event.taskId);
+					if (!page.hasMore) break;
+					cursor = page.nextCursor;
+				}
+				const tasks = await Promise.all([...taskIds].map((taskId) => client.status(taskId, signal)));
+				return toolResult({ tasks }, `## task inbox\n${tasks.length === 0 ? "- empty" : tasks.map((task) => `- \`${task.task.taskId}\`: ${task.status}${task.completion ? ` — ${task.completion.summary}` : ""}`).join("\n")}`);
+			} catch (error) { return clientError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+	});
+
+	pi.registerTool({
+		name: "agent_task_ack", label: "Acknowledge Agent Task", description: "Acknowledge one independently verified terminal task.", parameters: TaskIdParams,
+		async execute(_toolCallId, params, signal) {
+			try { return toolResult(await client.ack(params.taskId, signal), `## task acknowledged\n- task: \`${params.taskId}\``); } catch (error) { return clientError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+	});
+
+	pi.registerTool({
+		name: "agent_task_message", label: "Message Agent Task", description: "Durably send a question, answer, or information event for a task.", parameters: MessageParams,
+		async execute(_toolCallId, params, signal) {
+			try {
+				const [identity, status] = await Promise.all([client.sessionStatus(signal), client.status(params.taskId, signal)]);
+				const receipt = await client.message(params, signal);
+				const receiverQuestion = params.type === "question" && identity.sessionId === status.task.target.sessionId;
+				return { ...toolResult(receipt, `## task ${params.type}\n- task: \`${params.taskId}\`\n${params.message}`), ...(receiverQuestion ? { terminate: true } : {}) };
+			} catch (error) { return clientError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+	});
+
+	pi.registerTool({
+		name: "agent_task_cancel", label: "Cancel Agent Task", description: "Request cancellation for a non-terminal task through Wolfpack.", parameters: TaskIdParams,
+		async execute(_toolCallId, params, signal) {
+			try { const receipt = await client.cancel(params.taskId, signal); return toolResult(receipt, `## task cancellation requested\n- task: \`${params.taskId}\`${warnings(receipt.warnings)}`); } catch (error) { return clientError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+	});
+
+	pi.registerTool({
+		name: "agent_task_done", label: "Complete Agent Task", description: "Finish an assigned task with a structured terminal result. Report source modifications in result.changedFiles; artifacts are receiver-project-relative regular files to inspect, not a changed-file list. Use exactly once as the final action.",
+		promptSnippet: "Complete an assigned task: report changed files in result.changedFiles and artifacts separately", promptGuidelines: ["Report source modifications under result.changedFiles. Reserve artifacts for receiver-project-relative regular files a parent should inspect, not changed-file lists.", "Use agent_task_done exactly once as the final action for an assigned task."], parameters: DoneParams,
+		async execute(_toolCallId, params, signal) {
+			try {
+				const result: TaskCompletionInput = { summary: params.summary, ...(params.result && { result: params.result }), ...(params.error && { error: params.error }), ...(params.artifacts && { artifacts: params.artifacts }) };
+				const receipt = await client.complete({ taskId: params.taskId, status: params.status, result }, signal);
+				return { ...toolResult(receipt, `## task ${params.status}\n- task: \`${params.taskId}\`\n- ${params.summary}${warnings(receipt.warnings)}`), terminate: true };
+			} catch (error) { return clientError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+	});
+}
+
+export function createSingleFlightInboxRefresh(refresh: () => Promise<void>): () => Promise<void> {
+	let inFlight: Promise<void> | undefined;
+	return (): Promise<void> => {
+		if (inFlight) return inFlight;
+		const current = refresh().finally(() => {
+			if (inFlight === current) inFlight = undefined;
+		});
+		inFlight = current;
+		return current;
+	};
+}
+
+export default function piTasks(pi: ExtensionAPI): void {
+	registerAgentTaskTools(pi);
+}
+
+function statusResult(status: TaskStatus): AgentToolResult<unknown> {
+	return toolResult(status, `## task status\n- task: \`${status.task.taskId}\`\n- status: ${status.status}${status.completion ? `\n- summary: ${status.completion.summary}` : ""}${warnings(status.warnings)}`);
+}
+
+function toolResult(details: unknown, markdown: string): AgentToolResult<unknown> {
+	return { content: [{ type: "text", text: markdown }], details };
+}
+
+function clientError(error: unknown): AgentToolResult<unknown> {
+	const gateway = error instanceof GatewayClientError ? error : new GatewayClientError("CLIENT_ERROR", error instanceof Error ? error.message : "task gateway request failed", true);
+	const path = gateway.path === undefined ? {} : { path: gateway.path };
+	return toolResult(
+		{ error: { code: gateway.code, message: gateway.message, retryable: gateway.retryable, ...path } },
+		`## task gateway error\n- ${gateway.code}: ${gateway.message}${gateway.path === undefined ? "" : `\n- path: \`${gateway.path}\``}`,
+	);
+}
+
+function warnings(values: readonly { readonly code: string; readonly message: string }[]): string {
+	return values.length === 0 ? "" : `\n## gateway warnings\n${values.map((value) => `- ${value.code}: ${value.message}`).join("\n")}`;
+}
+
+function terminal(status: string): boolean {
+	return status === "completed" || status === "failed" || status === "cancelled" || status === "timed_out";
+}
+
+function text(result: { readonly content?: readonly unknown[] }): string {
+	const first = result.content?.[0];
+	return first && typeof first === "object" && "type" in first && first.type === "text" && "text" in first && typeof first.text === "string" ? first.text : "";
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) throw new GatewayClientError("ABORTED", "task wait was cancelled", true);
+}
+
+async function sleep(milliseconds: number, signal: AbortSignal | undefined): Promise<void> {
+	await new Promise<void>((resolve, reject) => {
+		const timeout = setTimeout(resolve, milliseconds);
+		const abort = (): void => { clearTimeout(timeout); reject(new GatewayClientError("ABORTED", "task wait was cancelled", true)); };
+		signal?.addEventListener("abort", abort, { once: true });
+	});
+}

package/src/legacy-task-inbox.ts

@@ -0,0 +1,148 @@
+import type { TaskAssignment, TaskEvent, TaskStatus, WolfpackGatewayClient } from "./gateway-client";
+
+const TASK_EVENT_CUSTOM_TYPE = "wolfpack-task-event";
+const TASK_CURSOR_CUSTOM_TYPE = "wolfpack-task-cursor";
+
+interface InboxContext {
+	readonly hasPendingMessages: () => boolean;
+	readonly sessionManager: {
+		readonly buildContextEntries: () => readonly unknown[];
+		readonly getEntries: () => readonly unknown[];
+	};
+}
+
+interface InboxPi {
+	sendMessage(message: { readonly customType: string; readonly content: string; readonly display: boolean; readonly details: TaskEventDetails }, options: { readonly triggerTurn: true; readonly deliverAs: "followUp" }): void;
+	appendEntry(customType: string, data: { readonly cursor: string }): void;
+}
+
+interface TaskEventDetails {
+	readonly taskId: string;
+	readonly eventId: string;
+}
+
+interface InboxClient {
+	inbox(cursor: string, includeAcknowledged: boolean): Promise<{ readonly events: readonly TaskEvent[]; readonly nextCursor: string; readonly hasMore: boolean }>;
+	status(taskId: string): Promise<TaskStatus>;
+	delivered(taskId: string, eventId: string): Promise<unknown>;
+}
+
+export async function deliverTaskInbox(pi: InboxPi, client: InboxClient, ctx: InboxContext, initialCursor: string): Promise<string> {
+	if (ctx.hasPendingMessages()) return initialCursor;
+	const entries = ctx.sessionManager.getEntries();
+	const incorporated = incorporatedEvents(entries);
+	const includeAcknowledged = initialCursor === "0" && !hasPersistedCursor(entries);
+	let cursor = initialCursor;
+	for (;;) {
+		const page = await client.inbox(cursor, includeAcknowledged);
+		for (const event of page.events) {
+			const disposition = inboxDisposition(event.type);
+			if (disposition === "internal") continue;
+			if (disposition === "unknown") throw new Error(`unknown task inbox event type: ${event.type}`);
+			if (ctx.hasPendingMessages()) return cursor;
+			const eventKey = key(event.taskId, event.id);
+			const snapshot = await client.status(event.taskId);
+			if (ctx.hasPendingMessages()) return cursor;
+			if (incorporated.has(eventKey)) {
+				if (event.destination.sessionId === snapshot.task.target.sessionId) await client.delivered(event.taskId, event.id);
+				continue;
+			}
+			if (terminalHistoryAcknowledged(snapshot)) continue;
+			pi.sendMessage({
+				customType: TASK_EVENT_CUSTOM_TYPE,
+				content: renderTaskEvent(event, snapshot),
+				display: true,
+				details: { taskId: event.taskId, eventId: event.id },
+			}, { triggerTurn: true, deliverAs: "followUp" });
+			if (!incorporatedEvents(ctx.sessionManager.getEntries()).has(eventKey)) return cursor;
+			incorporated.add(eventKey);
+			if (event.destination.sessionId === snapshot.task.target.sessionId) await client.delivered(event.taskId, event.id);
+		}
+		// Inbox cursors are machine-local delivery sequences, never task event sequences.
+		cursor = page.nextCursor;
+		pi.appendEntry(TASK_CURSOR_CUSTOM_TYPE, { cursor });
+		if (!page.hasMore) return cursor;
+	}
+}
+
+function hasPersistedCursor(entries: readonly unknown[]): boolean {
+	return entries.some((entry) => isRecord(entry) && entry.type === "custom" && entry.customType === TASK_CURSOR_CUSTOM_TYPE && isRecord(entry.data) && decimal(entry.data.cursor));
+}
+
+function inboxDisposition(type: string): "model-visible" | "internal" | "unknown" {
+	if (type === "task.created" || type === "task.question" || type === "task.answer" || type === "task.information" || terminalEvent(type) || type === "task.cancel_requested") return "model-visible";
+	if (type === "task.received" || type === "task.receipt_confirmed" || type === "task.delivered" || type === "message.delivered" || type === "task.parent_ack_pending" || type === "task.parent_acknowledged" || type === "event.delivery_failed" || type === "task.late_terminal") return "internal";
+	return "unknown";
+}
+
+function terminalHistoryAcknowledged(snapshot: TaskStatus): boolean {
+	return ["completed", "failed", "cancelled", "timed_out"].includes(snapshot.status) && snapshot.events.some((event) => event.type === "task.parent_acknowledged");
+}
+
+export function restoredInboxCursor(entries: readonly unknown[]): string {
+	let cursor = "0";
+	for (const entry of entries) {
+		if (!isRecord(entry) || entry.type !== "custom" || entry.customType !== TASK_CURSOR_CUSTOM_TYPE || !isRecord(entry.data) || !decimal(entry.data.cursor)) continue;
+		cursor = entry.data.cursor;
+	}
+	return cursor;
+}
+
+export function incorporatedEvents(entries: readonly unknown[]): Set<string> {
+	const events = new Set<string>();
+	for (const entry of entries) {
+		if (!isRecord(entry) || entry.type !== "custom_message" || entry.customType !== TASK_EVENT_CUSTOM_TYPE || !isRecord(entry.details) || !nonEmpty(entry.details.taskId) || !nonEmpty(entry.details.eventId)) continue;
+		events.add(key(entry.details.taskId, entry.details.eventId));
+	}
+	return events;
+}
+
+export function renderTaskEvent(event: TaskEvent, snapshot: TaskStatus): string {
+	const header = `task: \`${event.taskId}\` · event: \`${event.id}\``;
+	if (event.type === "task.created") return renderAssignment(header, snapshot.task, snapshot.warnings);
+	const message = event.message ? `\n\n${event.message}` : "";
+	const completion = event.completion ?? snapshot.completion;
+	const completionText = completion ? `\n\n**summary:** ${completion.summary}` : "";
+	const parentPrompt = terminalEvent(event.type) && event.destination.sessionId === snapshot.task.source.sessionId && snapshot.task.onCompletePrompt
+		? `\n\n## parent follow-up\n${snapshot.task.onCompletePrompt}`
+		: "";
+	const warnings = renderWarnings(snapshot.warnings);
+	return `## task ${label(event.type)}\n${header}${message}${completionText}${parentPrompt}${warnings}`;
+}
+
+function renderAssignment(header: string, assignment: TaskAssignment, warnings: readonly { readonly code: string; readonly message: string }[]): string {
+	const role = assignment.role ? `\n\n## role\n${assignment.role}` : "";
+	const context = assignment.context?.summary ? `\n\n## context\n${assignment.context.summary}` : "";
+	const refs = assignment.context?.refs?.length
+		? `\n\n## selected refs\n${assignment.context.refs.map((ref) => `- \`${ref.path}\`${ref.selector ? ` — ${ref.selector}` : ""}${ref.purpose ? ` — ${ref.purpose}` : ""}`).join("\n")}`
+		: "";
+	return `## task assignment\n${header}\n\n${assignment.task}${role}${context}${refs}${renderWarnings(warnings)}`;
+}
+
+function renderWarnings(warnings: readonly { readonly code: string; readonly message: string }[]): string {
+	return warnings.length === 0 ? "" : `\n\n## gateway warnings\n${warnings.map((warning) => `- ${warning.code}: ${warning.message}`).join("\n")}`;
+}
+
+function label(type: string): string {
+	return type.replace(/^task\./, "").replaceAll("_", " ");
+}
+
+function terminalEvent(type: string): boolean {
+	return type === "task.completed" || type === "task.failed" || type === "task.cancelled" || type === "task.timed_out";
+}
+
+function key(taskId: string, eventId: string): string {
+	return `${taskId}\u0000${eventId}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function nonEmpty(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0;
+}
+
+function decimal(value: unknown): value is string {
+	return typeof value === "string" && /^(0|[1-9][0-9]*)$/.test(value);
+}

package/src/metrics-cli.ts

@@ -0,0 +1,20 @@
+import { analyzeTaskStoreMetrics } from "./metrics";
+import { buildTaskBoard } from "./task-board";
+
+export async function runTaskMetricsCli(args: readonly string[]): Promise<number> {
+	const tasksRoot = args[0];
+	if (!tasksRoot) {
+		console.error("usage: bun run task-metrics <tasksRoot> [--board]");
+		return 1;
+	}
+
+	const report = args.includes("--board")
+		? await buildTaskBoard(tasksRoot)
+		: await analyzeTaskStoreMetrics(tasksRoot);
+	console.log(JSON.stringify(report, null, 2));
+	return 0;
+}
+
+if (import.meta.main) {
+	process.exitCode = await runTaskMetricsCli(process.argv.slice(2));
+}