@sgtbeatdown/pi-tasks 0.1.0 → 0.1.2

package/src/extension.ts

@@ -3,306 +3,264 @@ import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
-import { buildBackgroundTaskNotificationPrompt, selectUnpromptedTerminalTasks } from "./auto-notify";
-import type { TaskCommunicationLayer } from "./task-communication";
-import { createFilesystemTaskStore } from "./stores/filesystem";
-import { createWolfpackTaskTransport } from "./transports/wolfpack";
-import { buildAssignment, compactTaskResult } from "./protocol";
-import type { AgentTaskRecord, TaskResultPayload, TerminalTaskStatus } from "./types";
-import { DEFAULT_TIMEOUT_MS, TASK_PROTOCOL_VERSION } from "./types";
+import { deliverTaskInbox } from "./task-inbox";
+import { TaskOutboxDeliveryError, TaskProtocolError } from "./task-protocol";
+import { createWolfpackTaskCore } from "./wolfpack-task-relay";
+import type { TaskCore } from "./task-core";
 
+const DEFAULT_TASK_TIMEOUT_MS = 30 * 60 * 1_000;
+const MIN_TASK_TIMEOUT_MS = 1_000;
+const MAX_TASK_TIMEOUT_MS = 86_400_000;
+const BACKGROUND_POLL_MS = 5_000;
+const TARGET_NOT_REGISTERED_CODE = "TARGET_NOT_REGISTERED";
 const WAIT_POLL_MS = 250;
-const BACKGROUND_POLL_MS = 5000;
+const SUMMARY_MAX_CHARS = 1_200;
 
-const SendParams = Type.Object({
-	to: Type.String({ description: "Target session, worker, or transport-specific address" }),
-	task: Type.String({ description: "Task instructions to send to the target" }),
-	timeoutMs: Type.Optional(Type.Integer({ minimum: 1000, maximum: 86_400_000 })),
-	idempotencyKey: Type.Optional(Type.String()),
-});
-
-const TaskIdParams = Type.Object({
-	taskId: Type.String({ description: "Task id, e.g. task_..." }),
+const EndpointParams = Type.Object({
+	relay: Type.String({ minLength: 1, description: "relay identifier" }),
+	id: Type.String({ minLength: 1, description: "opaque endpoint identifier" }),
 });
-
-const WaitParams = Type.Object({
-	taskId: Type.String({ description: "Task id, e.g. task_..." }),
-	timeoutMs: Type.Optional(Type.Integer({ minimum: 1000, maximum: 86_400_000 })),
-});
-
-const InboxParams = Type.Object({
-	ack: Type.Optional(Type.Boolean({ default: false })),
-	includeAcknowledged: Type.Optional(Type.Boolean({ default: false })),
-});
-
-const CancelParams = Type.Object({
-	taskId: Type.String({ description: "Task id, e.g. task_..." }),
-	reason: Type.Optional(Type.String()),
+const SendParams = Type.Object({
+	to: EndpointParams,
+	task: Type.String({ minLength: 1, maxLength: 16 * 1024 }),
+	timeoutMs: Type.Optional(Type.Integer({ minimum: MIN_TASK_TIMEOUT_MS, maximum: MAX_TASK_TIMEOUT_MS })),
 });
-
+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 MessageParams = Type.Object({ taskId: Type.String({ minLength: 1 }), type: StringEnum(["question", "answer", "information"] as const), message: Type.String({ minLength: 1, maxLength: 16 * 1024 }) });
 const DoneParams = Type.Object({
-	taskId: Type.String({ description: "Task id from the assignment" }),
-	status: StringEnum(["completed", "failed", "cancelled", "rejected"] as const),
-	summary: Type.String({ description: "Compact summary, max 1200 chars" }),
-	error: Type.Optional(
-		Type.Object({
-			code: Type.String(),
-			message: Type.String(),
-			retryable: Type.Boolean(),
-		}),
-	),
+	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())),
-	artifacts: Type.Optional(
-		Type.Array(
-			Type.Object({
-				name: Type.String(),
-				path: Type.Optional(Type.String()),
-				mimeType: Type.Optional(Type.String()),
-				description: Type.Optional(Type.String()),
-			}),
-		),
-	),
+	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 are receiver-project-relative regular files" }), mimeType: Type.Optional(Type.String()), description: Type.Optional(Type.String()) }))),
 });
 
-export function createDefaultTaskCommunicationLayer(pi: ExtensionAPI): TaskCommunicationLayer {
-	return {
-		store: createFilesystemTaskStore(),
-		transport: createWolfpackTaskTransport({
-			exec: (command, args, options) => pi.exec(command, [...args], options),
-		}),
+export type ConfiguredCoreFactory = (signal?: AbortSignal) => Promise<TaskCore>;
+
+/** Reuses a successful configured core while allowing the next lifecycle operation to retry a failed setup. */
+export function createConfiguredCoreLoader(factory: ConfiguredCoreFactory): ConfiguredCoreFactory {
+	let corePromise: Promise<TaskCore> | undefined;
+	return async (signal?: AbortSignal): Promise<TaskCore> => {
+		if (corePromise) return corePromise;
+		const candidate = Promise.resolve().then(() => factory(signal));
+		corePromise = candidate;
+		try {
+			return await candidate;
+		} catch (error) {
+			if (corePromise === candidate) corePromise = undefined;
+			throw error;
+		}
 	};
 }
 
-export function registerAgentTaskTools(pi: ExtensionAPI, communication: TaskCommunicationLayer): void {
-	const { store, transport } = communication;
+/** Registers v2 endpoint-owned tools using a configured durable Wolfpack relay by default. */
+export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefined = undefined, createCore: ConfiguredCoreFactory = (signal) => createWolfpackTaskCore({}, signal)): void {
+	let inboxContext: ExtensionContext | undefined;
 	let backgroundTimer: ReturnType<typeof setInterval> | undefined;
-	const notifiedTaskIds = new Set<string>();
-	const autoPromptedTaskIds = new Set<string>();
-
-	pi.on("session_start", async (_event, ctx) => {
-		const sessionName = transport.getCurrentSessionName(process.env);
-		ctx.ui.setStatus("wolfpack-tasks", ctx.ui.theme.fg("dim", `tasks: ${sessionName}`));
-
-		backgroundTimer = setInterval(() => {
-			void refreshInboxStatus(ctx.cwd, sessionName, ctx).catch(() => {
-				ctx.ui.setStatus("wolfpack-tasks", ctx.ui.theme.fg("warning", "tasks: unavailable"));
-			});
-		}, BACKGROUND_POLL_MS);
-
-		await refreshInboxStatus(ctx.cwd, sessionName, ctx).catch(() => undefined);
-	});
-
-	pi.on("agent_end", async (_event, ctx) => {
-		const sessionName = transport.getCurrentSessionName(process.env);
-		setTimeout(() => {
-			void refreshInboxStatus(ctx.cwd, sessionName, ctx).catch(() => undefined);
-		}, 0);
-	});
-
-	pi.on("session_shutdown", async () => {
-		if (backgroundTimer) {
-			clearInterval(backgroundTimer);
-			backgroundTimer = undefined;
+	let lifecycleEpoch = 0;
+	const configuredCore: ConfiguredCoreFactory = core === undefined ? createConfiguredCoreLoader(createCore) : async (): Promise<TaskCore> => core;
+	const refreshInbox = createSingleFlightInboxRefresh(async (signal) => {
+		const context = inboxContext;
+		if (!context) return undefined;
+		const activeCore = await configuredCore(signal);
+		if (inboxContext !== context) return undefined;
+		let outboxError: unknown;
+		try {
+			await activeCore.flushOutbox(signal);
+		} catch (error) {
+			outboxError = error;
 		}
-	});
-
-	async function refreshInboxStatus(projectDir: string, sessionName: string, ctx: ExtensionContext): Promise<void> {
-		const inbox = await store.listInbox(projectDir, sessionName, { includeAcknowledged: false });
-		const count = inbox.length;
-		ctx.ui.setStatus("wolfpack-tasks", ctx.ui.theme.fg(count > 0 ? "accent" : "dim", `tasks: ${count} inbox`));
-		for (const task of inbox) {
-			if (notifiedTaskIds.has(task.id)) continue;
-			notifiedTaskIds.add(task.id);
-			ctx.ui.notify(`task ${task.id} ${task.status}: ${task.targetSession}`, task.status === "completed" ? "info" : "warning");
+		if (inboxContext !== context) return undefined;
+		try {
+			await activeCore.evaluateTimeouts(signal);
+		} catch (error) {
+			outboxError ??= error;
 		}
-		triggerIdleInboxPrompt(inbox, ctx);
-	}
-
-	function triggerIdleInboxPrompt(inbox: readonly AgentTaskRecord[], ctx: ExtensionContext): void {
-		if (!ctx.isIdle() || ctx.hasPendingMessages()) return;
-
-		const tasksToPrompt = selectUnpromptedTerminalTasks(inbox, autoPromptedTaskIds);
-		if (tasksToPrompt.length === 0) return;
-
+		if (inboxContext !== context) return undefined;
+		const isCurrent = (): boolean => inboxContext === context;
+		const guardedCore: TaskCore = {
+			...activeCore,
+			async receive(receiveSignal) {
+				const deliveries = await activeCore.receive(receiveSignal);
+				return isCurrent() ? deliveries : [];
+			},
+			async acknowledgeRelayDelivery(cursor, acknowledgementSignal) {
+				if (isCurrent()) await activeCore.acknowledgeRelayDelivery(cursor, acknowledgementSignal);
+			},
+			async recordInsertion(input, insertionSignal) {
+				if (isCurrent()) await activeCore.recordInsertion(input, insertionSignal);
+			},
+		};
+		await deliverTaskInbox({
+			sendMessage(message, options) { if (isCurrent()) pi.sendMessage(message, options); },
+			appendEntry(customType, data) { if (isCurrent()) pi.appendEntry(customType, data); },
+		}, guardedCore, {
+			hasPendingMessages: (): boolean => !isCurrent() || context.hasPendingMessages(),
+			sessionManager: context.sessionManager,
+		}, signal);
+		return outboxError;
+	});
+	const refreshLifecycle = async (context: ExtensionContext, epoch: number): Promise<void> => {
+		const isCurrent = (): boolean => lifecycleEpoch === epoch && inboxContext === context;
 		try {
-			pi.sendUserMessage(buildBackgroundTaskNotificationPrompt(tasksToPrompt));
-			for (const task of tasksToPrompt) {
-				autoPromptedTaskIds.add(task.id);
+			const activeCore = await configuredCore();
+			let connectionError: unknown;
+			try {
+				await activeCore.connect();
+			} catch (error) {
+				connectionError = error;
 			}
-		} catch {
-			ctx.ui.notify("task results ready; parent is busy, will retry", "info");
+			if (!isCurrent()) return;
+			const outboxError = await refreshInbox();
+			if (!isCurrent()) return;
+			const lifecycleError = outboxError ?? connectionError;
+			const status = lifecycleError === undefined ? undefined : outboxFailureStatus(lifecycleError);
+			context.ui.setStatus("pi-tasks", status === undefined ? undefined : context.ui.theme.fg("warning", status));
+		} catch (error) {
+			if (isCurrent()) context.ui.setStatus("pi-tasks", context.ui.theme.fg("warning", outboxFailureStatus(error)));
 		}
-	}
-
-	pi.registerTool({
-		name: "agent_task_send",
-		label: "Send Agent Task",
-		description: "Send a structured task to another agent/session/worker and return immediately without waiting.",
-		promptSnippet: "Send nonblocking structured tasks to other agents/sessions/workers",
-		promptGuidelines: [
-			"Use agent_task_send instead of natural-language polling when delegating work to another agent/session/worker",
-			"After agent_task_send returns, keep working unless the user explicitly asks to wait for the task.",
-		],
-		parameters: SendParams,
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			const parentSession = transport.getCurrentSessionName(process.env);
-
-			const createdTask = await store.createOrReuseDispatchedTask({
-				projectDir: ctx.cwd,
-				parentSession,
-				targetSession: params.to,
-				taskText: params.task,
-				assignment: (taskId: string) => buildAssignment({ taskId, fromSession: parentSession, instructions: params.task }),
-				timeoutMs: params.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-				idempotencyKey: params.idempotencyKey,
-				targetTaskProtocol: TASK_PROTOCOL_VERSION,
-			});
-			const task = createdTask.task;
-			if (!createdTask.created) {
-				return taskToolResult(compactTaskResult(task, await store.readTaskResult(ctx.cwd, task.id)));
-			}
-
-			const assignment = buildAssignment({ taskId: task.id, fromSession: parentSession, instructions: params.task });
-			const dispatch = await transport.dispatchTask({ projectDir: ctx.cwd, task, target: params.to, assignment, signal });
-			if (!dispatch.ok) {
-				const rejected = await store.completeTask(ctx.cwd, task.id, "rejected", {
-					summary: `dispatch failed: ${dispatch.message}`,
-					error: {
-						code: "dispatch_failed",
-						message: dispatch.message,
-						retryable: dispatch.retryable,
-					},
-				});
-				return taskToolResult(compactTaskResult(rejected, await store.readTaskResult(ctx.cwd, task.id)));
-			}
+	};
 
-			return taskToolResult({
-				schemaVersion: 1,
-				taskId: task.id,
-				status: task.status,
-				summary: `dispatched to ${params.to}`,
-				artifacts: [task.assignmentRef].filter((value): value is string => Boolean(value)),
-				error: null,
-			});
-		},
-		renderResult(result, _options, theme) {
-			return new Text(theme.fg("accent", getText(result)));
-		},
+	pi.on("session_start", async (_event, context) => {
+		const epoch = ++lifecycleEpoch;
+		inboxContext = context;
+		if (backgroundTimer) clearInterval(backgroundTimer);
+		backgroundTimer = setInterval(() => {
+			const currentContext = inboxContext;
+			if (currentContext) void refreshLifecycle(currentContext, epoch);
+		}, BACKGROUND_POLL_MS);
+		await refreshLifecycle(context, epoch);
+	});
+	pi.on("agent_end", async (_event, context) => {
+		const epoch = lifecycleEpoch;
+		inboxContext = context;
+		await refreshLifecycle(context, epoch);
+	});
+	pi.on("session_shutdown", () => {
+		lifecycleEpoch += 1;
+		if (backgroundTimer) clearInterval(backgroundTimer);
+		backgroundTimer = undefined;
+		inboxContext = undefined;
 	});
 
 	pi.registerTool({
-		name: "agent_task_status",
-		label: "Task Status",
-		description: "Read compact structured status for a task.",
-		parameters: TaskIdParams,
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const task = await store.expireTaskIfOverdue(ctx.cwd, params.taskId);
-			return taskToolResult(compactTaskResult(task, await store.readTaskResult(ctx.cwd, params.taskId)));
+		name: "agent_task_send", label: "Send Agent Task", description: "Persist an endpoint-owned task and submit its opaque assignment envelope to a relay.", parameters: SendParams,
+		async execute(_id, params, signal) {
+			try {
+				const sent = await (await configuredCore(signal)).createTask({ target: params.to, task: params.task, timeoutMs: params.timeoutMs ?? DEFAULT_TASK_TIMEOUT_MS }, signal);
+				return toolResult(sent, `## task accepted\n- task: \`${sent.taskId}\`\n- target: \`${params.to.relay}/${params.to.id}\`\n- delivery: relay acceptance only`);
+			} catch (error) { return taskError(error); }
 		},
+		renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
-
 	pi.registerTool({
-		name: "agent_task_wait",
-		label: "Wait Agent Task",
-		description: "Wait in tool code for a task to become terminal. Use only when the user wants the result now.",
-		parameters: WaitParams,
-		async execute(_toolCallId, params, _signal, onUpdate, ctx) {
-			const waitMs = params.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-			const sessionName = transport.getCurrentSessionName(process.env);
-			const progressTimer = setInterval(() => {
-				onUpdate?.({ content: [{ type: "text", text: `waiting for ${params.taskId}...` }], details: {} });
-			}, 2000);
+		name: "agent_task_status", label: "Task Status", description: "Read local endpoint-owned task state; status is unavailable while its origin is offline.", parameters: TaskIdParams,
+		async execute(_id, params, signal) {
 			try {
-				const task = await store.waitForTask(ctx.cwd, params.taskId, { timeoutMs: waitMs, pollMs: WAIT_POLL_MS, ackParentSession: sessionName });
-				return taskToolResult(compactTaskResult(task, await store.readTaskResult(ctx.cwd, params.taskId)));
-			} catch (error) {
-				const task = await store.readTask(ctx.cwd, params.taskId);
-				return taskToolResult({
-					schemaVersion: 1,
-					taskId: task.id,
-					status: task.status,
-					summary: error instanceof Error ? error.message : "task wait failed",
-					artifacts: task.resultRef ? [task.resultRef] : [],
-					error: { code: "wait_timeout", message: "task wait timed out", retryable: true },
-				});
-			} finally {
-				clearInterval(progressTimer);
-			}
-		},
+				const task = (await configuredCore(signal)).getTask(params.taskId);
+				return task ? toolResult(task, `## task status\n- task: \`${task.taskId}\`\n- status: ${task.status}`) : taskError(new Error("unknown local task"));
+			} catch (error) { return taskError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
-
 	pi.registerTool({
-		name: "agent_task_inbox",
-		label: "Task Inbox",
-		description: "List terminal tasks for this parent session. Results are only shown to the model when this tool is called.",
-		parameters: InboxParams,
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const sessionName = transport.getCurrentSessionName(process.env);
-			const tasks = await store.listInbox(ctx.cwd, sessionName, { includeAcknowledged: params.includeAcknowledged ?? false });
-			const compact = [];
-			for (const task of tasks) {
-				compact.push(compactTaskResult(task, await store.readTaskResult(ctx.cwd, task.id)));
-				if (params.ack) {
-					await store.ackTask(ctx.cwd, task.id, sessionName);
+		name: "agent_task_wait", label: "Wait Agent Task", description: "Wait for a locally-known endpoint-owned task to reach a terminal state.", parameters: WaitParams,
+		async execute(_id, params, signal, onUpdate) {
+			const deadline = Date.now() + (params.timeoutMs ?? DEFAULT_TASK_TIMEOUT_MS);
+			try {
+				for (;;) {
+					await refreshInbox(signal);
+					const task = (await configuredCore(signal)).getTask(params.taskId);
+					if (!task) return taskError(new Error("unknown local task"));
+					if (terminal(task.status)) return toolResult(task, `## task status\n- task: \`${task.taskId}\`\n- status: ${task.status}`);
+					if (Date.now() >= deadline) return toolResult({ taskId: params.taskId, status: task.status }, `## task wait\n- task: \`${params.taskId}\`\n- status: ${task.status}\n- wait timed out`);
+					onUpdate?.({ content: [{ type: "text", text: `waiting for ${params.taskId}...` }], details: {} });
+					await sleep(Math.min(WAIT_POLL_MS, deadline - Date.now()), signal);
 				}
-			}
-			return taskToolResult({ tasks: compact });
-		},
+			} catch (error) { return taskError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
-
 	pi.registerTool({
-		name: "agent_task_cancel",
-		label: "Cancel Agent Task",
-		description: "Cancel a non-terminal task in the shared task store.",
-		parameters: CancelParams,
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const task = await store.cancelTask(ctx.cwd, params.taskId, params.reason);
-			return taskToolResult(compactTaskResult(task, await store.readTaskResult(ctx.cwd, params.taskId)));
+		name: "agent_task_inbox", label: "Task Inbox", description: "Read local task records after processing relay deliveries without acknowledging task lifecycle.", parameters: Type.Object({}),
+		async execute(_id, _params, signal) {
+			try {
+				await refreshInbox(signal);
+				const tasks = (await configuredCore(signal)).listTasks();
+				return toolResult({ tasks }, `## task inbox\n${tasks.map((task) => `- \`${task.taskId}\`: ${task.status}`).join("\n") || "- empty"}`);
+			} catch (error) { return taskError(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 structured status. Use exactly once as the final action for assigned tasks.",
-		promptSnippet: "Complete an assigned task with a terminating structured result",
-		promptGuidelines: [
-			"Use agent_task_done exactly once as the final action for pi.task.assignment.v1 tasks.",
-			"After calling agent_task_done, do not emit another assistant response in prose.",
-		],
-		parameters: DoneParams,
-		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const status = params.status as TerminalTaskStatus;
-			const payload: TaskResultPayload = {
-				summary: params.summary,
-				...(params.result && { result: params.result }),
-				...(params.error && { error: params.error }),
-				...(params.artifacts && { artifacts: params.artifacts }),
-			};
-			const task = await store.completeTask(ctx.cwd, params.taskId, status, payload);
-			return {
-				...taskToolResult(compactTaskResult(task, await store.readTaskResult(ctx.cwd, params.taskId))),
-				terminate: true,
-			};
-		},
+		name: "agent_task_message", label: "Message Agent Task", description: "Persist a message intent before relay submission.", parameters: MessageParams,
+		async execute(_id, params, signal) { try { await (await configuredCore(signal)).submitIntent({ taskId: params.taskId, type: `task.${params.type}`, payload: { message: params.message } }, signal); return toolResult({ taskId: params.taskId }, `## task ${params.type}\n- task: \`${params.taskId}\``); } catch (error) { return taskError(error); } },
+		renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+	});
+	pi.registerTool({
+		name: "agent_task_cancel", label: "Cancel Agent Task", description: "Persist cancellation before relay submission.", parameters: TaskIdParams,
+		async execute(_id, params, signal) { try { await (await configuredCore(signal)).submitIntent({ taskId: params.taskId, type: "task.cancelled", payload: {} }, signal); return toolResult({ taskId: params.taskId }, `## task cancellation requested\n- task: \`${params.taskId}\``); } catch (error) { return taskError(error); } },
+		renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+	});
+	pi.registerTool({
+		name: "agent_task_ack", label: "Acknowledge Agent Task", description: "Record parent acknowledgement as an origin-owned logical event.", parameters: TaskIdParams,
+		async execute(_id, params, signal) { try { await (await configuredCore(signal)).acknowledgeParent(params.taskId, signal); return toolResult({ taskId: params.taskId }, `## task acknowledged\n- task: \`${params.taskId}\``); } catch (error) { return taskError(error); } },
+		renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+	});
+	pi.registerTool({
+		name: "agent_task_done", label: "Complete Agent Task", description: "Persist a terminal task intent before relay submission.", parameters: DoneParams,
+		async execute(_id, params, signal) {
+			try {
+				await (await configuredCore(signal)).submitIntent({ taskId: params.taskId, type: `task.${params.status}`, payload: { summary: params.summary, ...(params.result === undefined ? {} : { result: params.result }), ...(params.error === undefined ? {} : { error: params.error }), ...(params.artifacts === undefined ? {} : { artifacts: params.artifacts }) } }, signal);
+				return { ...toolResult({ taskId: params.taskId }, `## task ${params.status}\n- task: \`${params.taskId}\`\n- ${params.summary}`), terminate: true };
+			} catch (error) { return taskError(error); }
+		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
 }
 
+export function createSingleFlightInboxRefresh<TValue>(refresh: (signal?: AbortSignal) => Promise<TValue>): (signal?: AbortSignal) => Promise<TValue> {
+	let inFlight: Promise<TValue> | undefined;
+	return (signal): Promise<TValue> => {
+		if (inFlight) return inFlight;
+		const current = refresh(signal).finally(() => {
+			if (inFlight === current) inFlight = undefined;
+		});
+		inFlight = current;
+		return current;
+	};
+}
+
 export default function piTasks(pi: ExtensionAPI): void {
-	registerAgentTaskTools(pi, createDefaultTaskCommunicationLayer(pi));
+	registerAgentTaskTools(pi);
 }
 
-function taskToolResult(details: unknown): AgentToolResult<unknown> {
-	return {
-		content: [{ type: "text", text: JSON.stringify(details) }],
-		details,
-	};
+function toolResult(details: unknown, markdown: string): AgentToolResult<unknown> {
+	return { content: [{ type: "text", text: markdown }], details };
 }
 
-function getText(result: { readonly content?: readonly unknown[] }): string {
-	const first = result.content?.[0];
-	if (!first || typeof first !== "object" || !("type" in first) || first.type !== "text" || !("text" in first)) {
-		return "";
+function taskError(error: unknown): AgentToolResult<unknown> {
+	const message = error instanceof Error ? error.message : "task operation failed";
+	if (error instanceof TaskProtocolError) {
+		return toolResult({ ...error.details, error: { code: error.code, message, retryable: error.retryable } }, `## task error\n- ${message}`);
 	}
-	return typeof first.text === "string" ? first.text : "";
+	return toolResult({ error: { code: "TASK_ERROR", message, retryable: true } }, `## task error\n- ${message}`);
+}
+
+function outboxFailureStatus(error: unknown): "tasks: relay unavailable" | "tasks: outbox degraded" {
+	return error instanceof TaskOutboxDeliveryError && error.code === TARGET_NOT_REGISTERED_CODE ? "tasks: outbox degraded" : "tasks: relay unavailable";
+}
+
+function terminal(status: string): boolean {
+	return ["completed", "failed", "cancelled", "timed_out"].includes(status);
+}
+
+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 : "";
+}
+
+async function sleep(milliseconds: number, signal: AbortSignal | undefined): Promise<void> {
+	if (signal?.aborted) throw new Error("task wait was cancelled");
+	await new Promise<void>((resolve, reject) => {
+		const timer = setTimeout(resolve, Math.max(1, milliseconds));
+		signal?.addEventListener("abort", () => { clearTimeout(timer); reject(new Error("task wait was cancelled")); }, { once: true });
+	});
 }