@sgtbeatdown/pi-tasks 0.1.1 → 0.1.3

package/src/extension.ts

@@ -3,205 +3,308 @@ import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-
 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 "./task-inbox";
+import { deliverTaskInbox, incorporatedTaskEvents } from "./task-inbox";
+import { TaskOutboxDeliveryError, TaskProtocolError } from "./task-protocol";
+import { createWolfpackTaskCore } from "./wolfpack-task-relay";
+import type { TaskCore } from "./task-core";
+import type { TaskEndpoint, TaskSnapshot } from "./task-protocol";
 
+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 SUMMARY_MAX_CHARS = 1_200;
+const PRE_ASSIGNMENT_TOOLS = new Set(["agent_task_inbox", "agent_task_status", "agent_task_wait"]);
+export const WORKER_GATE_DENIAL_CODE = "PI_TASK_WORKER_ASSIGNMENT_REQUIRED";
 
-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 EndpointParams = Type.Object({
+	relay: Type.String({ minLength: 1, description: "relay identifier" }),
+	id: Type.String({ minLength: 1, description: "opaque endpoint identifier" }),
 });
-
-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,
+	to: EndpointParams,
 	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({ ack: Type.Optional(Type.Boolean({ default: false })), 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 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({ minLength: 1 }),
-	status: StringEnum(["completed", "failed", "cancelled"] as const),
-	summary: Type.String({ minLength: 1, maxLength: SUMMARY_MAX_CHARS }),
+	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 }), mimeType: Type.Optional(Type.String()), description: Type.Optional(Type.String()) }))),
+	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 registerAgentTaskTools(pi: ExtensionAPI, client: WolfpackGatewayClient = createWolfpackGatewayClient()): void {
-	let backgroundTimer: ReturnType<typeof setInterval> | undefined;
+export type ConfiguredCoreFactory = (signal?: AbortSignal) => Promise<TaskCore>;
 
-	const refreshInbox = async (ctx: ExtensionContext): Promise<void> => {
-		const cursor = restoredInboxCursor(ctx.sessionManager.getEntries());
-		await deliverTaskInbox(pi, client, ctx, cursor);
+/** 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;
+		}
+	};
+}
+
+/** 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;
+	let lifecycleEpoch = 0;
+	const pendingInsertions = new Set<string>();
+	const closingTaskIds = new Set<string>();
+	const workerGateEnabled = process.env.PI_TASK_WORKER === "1";
+	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;
+		}
+		if (inboxContext !== context) return undefined;
+		try {
+			await activeCore.evaluateTimeouts(signal);
+		} catch (error) {
+			outboxError ??= error;
+		}
+		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,
+		}, pendingInsertions, signal);
+		return outboxError;
+	});
+	const refreshLifecycle = async (context: ExtensionContext, epoch: number): Promise<void> => {
+		const isCurrent = (): boolean => lifecycleEpoch === epoch && inboxContext === context;
+		try {
+			const activeCore = await configuredCore();
+			let connectionError: unknown;
+			try {
+				await activeCore.connect();
+			} catch (error) {
+				connectionError = error;
+			}
+			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.on("session_start", async (_event, ctx) => {
-		ctx.ui.setStatus("wolfpack-tasks", ctx.ui.theme.fg("dim", `tasks: ${client.callerSession}`));
+	pi.on("tool_call", async (event, context) => {
+		if (!workerGateEnabled || PRE_ASSIGNMENT_TOOLS.has(event.toolName)) return undefined;
+		try {
+			const activeCore = await configuredCore(context.signal);
+			const assignments = assignedWorkerTasks(activeCore, context.sessionManager.getEntries());
+			if (event.toolName === "agent_task_done") {
+				const taskId = isRecord(event.input) && typeof event.input.taskId === "string" ? event.input.taskId : undefined;
+				const assigned = taskId === undefined ? undefined : assignments.find((task) => task.taskId === taskId);
+				if (assigned === undefined || (!eligibleWorkerTask(assigned, closingTaskIds) && assigned.terminalDelivery.state === "not_submitted" && !closingTaskIds.has(assigned.taskId))) {
+					return { block: true, reason: WORKER_GATE_DENIAL_CODE };
+				}
+				closingTaskIds.add(assigned.taskId);
+				return undefined;
+			}
+			if (assignments.some((task) => eligibleWorkerTask(task, closingTaskIds))) return undefined;
+		} catch {
+			// Authorization evidence unavailable or malformed: fail closed with the stable public reason.
+		}
+		return { block: true, reason: WORKER_GATE_DENIAL_CODE };
+	});
+
+	pi.on("session_start", async (_event, context) => {
+		pendingInsertions.clear();
+		closingTaskIds.clear();
+		const epoch = ++lifecycleEpoch;
+		inboxContext = context;
+		if (backgroundTimer) clearInterval(backgroundTimer);
 		backgroundTimer = setInterval(() => {
-			void refreshInbox(ctx).catch(() => ctx.ui.setStatus("wolfpack-tasks", ctx.ui.theme.fg("warning", "tasks: unavailable")));
+			const currentContext = inboxContext;
+			if (currentContext) void refreshLifecycle(currentContext, epoch);
 		}, BACKGROUND_POLL_MS);
-		await refreshInbox(ctx).catch(() => undefined);
+		await refreshLifecycle(context, epoch);
 	});
-	pi.on("agent_end", async (_event, ctx) => {
-		setTimeout(() => { void refreshInbox(ctx).catch(() => undefined); }, 0);
+	pi.on("agent_end", async (_event, context) => {
+		const epoch = lifecycleEpoch;
+		inboxContext = context;
+		await refreshLifecycle(context, epoch);
 	});
 	pi.on("session_shutdown", () => {
+		pendingInsertions.clear();
+		closingTaskIds.clear();
+		lifecycleEpoch += 1;
 		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) {
+		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 receipt = await client.send(params, signal);
-				return toolResult(receipt, `## task received\n- task: \`${receipt.taskId}\`\n- target: \`${params.to.machine}/${params.to.sessionId}\`\n${warnings(receipt.warnings)}`);
-			} catch (error) { return clientError(error); }
-		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+				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_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); }
+		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 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_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) {
+		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 (;;) {
-					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`);
+					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, Math.max(1, deadline - Date.now())), signal);
+					await sleep(Math.min(WAIT_POLL_MS, deadline - Date.now()), signal);
 				}
-			} catch (error) { return clientError(error); }
+			} 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: "Read inbox task events and optionally acknowledge terminal parent tasks.", parameters: InboxParams,
-		async execute(_toolCallId, params, signal) {
+		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 {
-				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)));
-				if (params.ack) await Promise.all(tasks.filter((task) => terminal(task.status)).map((task) => client.ack(task.task.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))); },
+				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_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))); },
+		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: "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))); },
+		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_done", label: "Complete Agent Task", description: "Finish an assigned task with a structured terminal result. Use exactly once as the final action.",
-		promptSnippet: "Complete an assigned task with a terminating structured result", promptGuidelines: ["Use agent_task_done exactly once as the final action for an assigned task."], parameters: DoneParams,
-		async execute(_toolCallId, params, signal) {
+		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 {
-				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); }
+				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 default function piTasks(pi: ExtensionAPI): void {
-	registerAgentTaskTools(pi);
+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;
+	};
 }
 
-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)}`);
+export default function piTasks(pi: ExtensionAPI): void {
+	registerAgentTaskTools(pi);
 }
 
 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);
-	return toolResult({ error: { code: gateway.code, message: gateway.message, retryable: gateway.retryable } }, `## task gateway error\n- ${gateway.code}: ${gateway.message}`);
+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 toolResult({ error: { code: "TASK_ERROR", message, retryable: true } }, `## task error\n- ${message}`);
 }
 
-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 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 status === "completed" || status === "failed" || status === "cancelled" || status === "timed_out";
+	return ["completed", "failed", "cancelled", "timed_out"].includes(status);
+}
+
+function assignedWorkerTasks(core: TaskCore, entries: readonly unknown[]): readonly TaskSnapshot[] {
+	const assignments = new Map<string, TaskSnapshot>();
+	for (const evidence of incorporatedTaskEvents(entries)) {
+		const task = core.getTask(evidence.taskId);
+		if (!task || !sameEndpoint(task.target, core.endpoint)) continue;
+		const created = task.events.find((event) => event.eventId === evidence.eventId);
+		if (!created || created.type !== "task.created" || !sameEndpoint(created.target, core.endpoint) || !sameEndpoint(created.source, task.origin)) continue;
+		assignments.set(task.taskId, task);
+	}
+	return [...assignments.values()];
+}
+
+function eligibleWorkerTask(task: TaskSnapshot, closingTaskIds: ReadonlySet<string>): boolean {
+	return task.status === "active" && task.terminalDelivery.state === "not_submitted" && !closingTaskIds.has(task.taskId);
+}
+
+function sameEndpoint(left: TaskEndpoint, right: TaskEndpoint): boolean {
+	return left.relay === right.relay && left.id === right.id;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
 function text(result: { readonly content?: readonly unknown[] }): string {
@@ -209,14 +312,10 @@ function text(result: { readonly content?: readonly unknown[] }): string {
 	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> {
+	if (signal?.aborted) throw new Error("task wait was cancelled");
 	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 });
+		const timer = setTimeout(resolve, Math.max(1, milliseconds));
+		signal?.addEventListener("abort", () => { clearTimeout(timer); reject(new Error("task wait was cancelled")); }, { once: true });
 	});
 }

package/src/gateway-client.ts

@@ -20,12 +20,14 @@ export type GatewayErrorCode =
 export class GatewayClientError extends Error {
 	readonly code: GatewayErrorCode;
 	readonly retryable: boolean;
+	readonly path?: string;
 
-	constructor(code: GatewayErrorCode, message: string, retryable: boolean) {
+	constructor(code: GatewayErrorCode, message: string, retryable: boolean, path?: string) {
 		super(message);
 		this.name = "GatewayClientError";
 		this.code = code;
 		this.retryable = retryable;
+		this.path = path;
 	}
 }
 
@@ -187,7 +189,7 @@ export function createWolfpackGatewayClient(options: WolfpackGatewayClientOption
 				signal: controller.signal,
 			});
 			const parsed = await parseJson(response);
-			if (isErrorEnvelope(parsed)) throw new GatewayClientError(parsed.error.code, parsed.error.message, parsed.error.retryable);
+			if (isErrorEnvelope(parsed)) throw new GatewayClientError(parsed.error.code, parsed.error.message, parsed.error.retryable, parsed.error.path);
 			if (!response.ok) throw new GatewayClientError("MALFORMED_RESPONSE", `wolfpack returned HTTP ${response.status} without a task error envelope`, true);
 			if (!isOkEnvelope(parsed)) throw new GatewayClientError("MALFORMED_RESPONSE", "wolfpack returned an invalid task response", true);
 			return parsed;
@@ -278,11 +280,28 @@ function serializeBody(body: unknown): string {
 }
 
 function validateSend(input: SendTaskInput): void {
-	if (!isAddress(input.to) || !nonEmpty(input.task) || bytes(input.task) > MAX_TASK_BYTES) throw new GatewayClientError("INVALID_REQUEST", "task and target address are required and bounded", false);
-	if (input.context?.summary !== undefined && (!nonEmpty(input.context.summary) || bytes(input.context.summary) > MAX_CONTEXT_SUMMARY_BYTES)) throw new GatewayClientError("INVALID_REQUEST", "context summary exceeds the 16KiB initial limit", false);
-	if (bytes(JSON.stringify(input)) > MAX_ASSIGNMENT_ENVELOPE_BYTES) throw new GatewayClientError("INVALID_REQUEST", "assignment envelope exceeds the 48KiB initial limit", false);
+	const path = sendValidationPath(input);
+	if (path !== undefined) throw new GatewayClientError("INVALID_REQUEST", "task and target address are required and bounded", false, path);
+	if (input.context?.summary !== undefined && (!nonEmpty(input.context.summary) || bytes(input.context.summary) > MAX_CONTEXT_SUMMARY_BYTES)) throw new GatewayClientError("INVALID_REQUEST", "context summary exceeds the 16KiB initial limit", false, "/context/summary");
+	if (bytes(JSON.stringify(input)) > MAX_ASSIGNMENT_ENVELOPE_BYTES) throw new GatewayClientError("INVALID_REQUEST", "assignment envelope exceeds the 48KiB initial limit", false, "");
 	const timeoutMs = input.timeoutMs ?? DEFAULT_TASK_TIMEOUT_MS;
-	if (!Number.isInteger(timeoutMs) || timeoutMs < MIN_TASK_TIMEOUT_MS || timeoutMs > MAX_TASK_TIMEOUT_MS) throw new GatewayClientError("INVALID_REQUEST", "task timeout must be from 1000ms through 24h", false);
+	if (!Number.isInteger(timeoutMs) || timeoutMs < MIN_TASK_TIMEOUT_MS || timeoutMs > MAX_TASK_TIMEOUT_MS) throw new GatewayClientError("INVALID_REQUEST", "task timeout must be from 1000ms through 24h", false, "/timeoutMs");
+}
+
+function sendValidationPath(input: SendTaskInput): string | undefined {
+	if (!isRecord(input.to)) return "/to";
+	if (!nonEmpty(input.to.machine)) return "/to/machine";
+	if (!nonEmpty(input.to.sessionId)) return "/to/sessionId";
+	if (!nonEmpty(input.task) || bytes(input.task) > MAX_TASK_BYTES) return "/task";
+	if (input.preflight?.requiredProject !== undefined && !nonEmpty(input.preflight.requiredProject)) return "/preflight/requiredProject";
+	if (input.context?.refs !== undefined) {
+		if (!Array.isArray(input.context.refs)) return "/context/refs";
+		for (const [index, ref] of input.context.refs.entries()) {
+			if (!isRecord(ref)) return `/context/refs/${index}`;
+			if (!nonEmpty(ref.path)) return `/context/refs/${index}/path`;
+		}
+	}
+	return undefined;
 }
 
 function validateMessage(input: MessageTaskInput): void {
@@ -328,8 +347,13 @@ function isOkEnvelope(value: unknown): value is Record<string, unknown> & { read
 	return isRecord(value) && value.ok === true;
 }
 
-function isErrorEnvelope(value: unknown): value is { readonly ok: false; readonly error: { readonly code: string; readonly message: string; readonly retryable: boolean } } {
-	return isRecord(value) && value.ok === false && isRecord(value.error) && nonEmpty(value.error.code) && typeof value.error.message === "string" && typeof value.error.retryable === "boolean";
+function isErrorEnvelope(value: unknown): value is { readonly ok: false; readonly error: { readonly code: string; readonly message: string; readonly retryable: boolean; readonly path?: string } } {
+	return isRecord(value) && value.ok === false && isRecord(value.error) && nonEmpty(value.error.code) && typeof value.error.message === "string" && typeof value.error.retryable === "boolean"
+		&& (value.error.path === undefined || jsonPointer(value.error.path));
+}
+
+function jsonPointer(value: unknown): value is string {
+	return typeof value === "string" && /^(?:|\/(?:[^~/]|~[01])*)*$/.test(value);
 }
 
 function assignment(value: unknown): value is TaskAssignment {