@sgtbeatdown/pi-tasks 0.1.3 → 0.1.5

package/README.md

@@ -36,6 +36,8 @@ Wolfpack's relay owns durable mailbox delivery and peer forwarding; Pi owns task
 
 Set `PI_TASK_WORKER=1` only when launching a task-only worker. The exact value enables a fail-closed model `tool_call` gate; an absent value or any other value leaves ordinary interactive Pi behavior unchanged. Before assignment, only `agent_task_inbox`, `agent_task_status`, and `agent_task_wait` are allowed. Other current and future model tools are blocked with the stable reason `PI_TASK_WORKER_ASSIGNMENT_REQUIRED`. Explicit user `!`/`!!` shell commands are outside Pi's model `tool_call` event and are not intercepted.
 
+`PI_TASK_WORKER=1` sessions are leaf roles. Workers cannot call `agent_task_send`; workers cannot call `agent_task_cancel`; workers cannot call `agent_task_ack`. These coordinator-tool attempts are blocked with the stable reason `PI_TASK_WORKER_COORDINATION_FORBIDDEN`, not the pre-assignment reason. `agent_task_message` is limited to the eligible incorporated assignment named by its input `taskId`. Generic role-orchestration guidance applies only to non-worker coordinators.
+
 The gate opens only when the current Pi session contains a structured `pi-tasks-event` entry for `task.created` and the same event belongs to a locally persisted active task targeted to the current endpoint. Rendered prompt text, terminal output, unknown events, foreign tasks, and stale terminal tasks do not authorize execution. On restart, durable session evidence reopens the gate only while the matching local task remains eligible.
 
 Preflighting `agent_task_done` marks that task as closing before sibling calls are preflighted. Ordinary tools remain blocked for a closing, pending-terminal, accepted-terminal, or `delivery_blocked` task; an idempotent `agent_task_done` retry for that same assigned task remains allowed. Another independently active assignment can still authorize work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sgtbeatdown/pi-tasks",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Durable Pi agent delegation through the Wolfpack task gateway.",
   "module": "src/index.ts",
   "exports": {

package/skills/wolfpack-pi-task-delegation/SKILL.md

@@ -29,8 +29,23 @@ The default `agent_task_send` schema is exactly `to`, `task`, and optional `time
 
 For a multi-step project phase, retain one persistent implementer and one persistent read-only reviewer. Reuse a healthy role session for corrections and follow-up review; a completed task finishes one assignment, not the underlying session. Do not rotate a healthy role session for routine corrections. Rotate only for phase completion, material context degradation, harness failure, or required specialist independence. Keep at most one active assignment per role unless the user explicitly approves parallel work.
 
+`PI_TASK_WORKER=1` sessions are leaf roles. Workers cannot call `agent_task_send`; workers cannot call `agent_task_cancel`; workers cannot call `agent_task_ack`. These coordinator-tool attempts are blocked with the stable reason `PI_TASK_WORKER_COORDINATION_FORBIDDEN`, not the pre-assignment reason. They may use `agent_task_message` only for the eligible incorporated assignment named by its input `taskId`. Generic role-orchestration guidance applies only to non-worker coordinators. Task workers must not create, rotate, or close Wolfpack sessions through shell or session-control tools.
+
 After every verified and acknowledged terminal task, explicitly retain a parent-spawned session only when concrete follow-up is likely; otherwise close it through canonical Wolfpack session control. Workers never close their own sessions. terminal `send` is only for explicit human steering; it is not task state, completion evidence, or a substitute for `agent_task_message`.
 
+## delegation lifecycle
+
+| event | owner | command | session outcome |
+| --- | --- | --- | --- |
+| assignment completion | worker | `agent_task_done` | unchanged |
+| task acknowledgment | parent | `agent_task_ack` | unchanged |
+| role session retention | parent | `none` | retained for reuse |
+| role session teardown | parent | `wolfpack kill <session-or-id> --json` | exact stable session id terminated |
+| teardown verification | parent | `wolfpack list --json` | exact stable session id absent |
+| Pi exit | none | `/quit` | not Wolfpack teardown |
+
+Assignment completion ends the assigned task, not the reusable role session. When no further reuse is likely, the parent—not the worker—must pass the exact stable session ID to `wolfpack kill <session-or-id> --json`, then inspect `wolfpack list --json` and verify that ID is absent. `/quit` exits Pi; it is not Wolfpack teardown. Workers never close themselves.
+
 ## v2 workflow
 
 1. create or select the role session, verify its structured project and terminal readiness, then obtain its registered `taskEndpoint`.

package/src/abortable-sleep.ts

@@ -0,0 +1,16 @@
+export async function abortableSleep(milliseconds: number, signal: AbortSignal | undefined, cancellationError: () => Error): Promise<void> {
+	if (signal?.aborted) throw cancellationError();
+	await new Promise<void>((resolve, reject) => {
+		const removeAbortListener = (): void => signal?.removeEventListener("abort", abort);
+		const timeout = setTimeout(() => {
+			removeAbortListener();
+			resolve();
+		}, milliseconds);
+		const abort = (): void => {
+			clearTimeout(timeout);
+			removeAbortListener();
+			reject(cancellationError());
+		};
+		signal?.addEventListener("abort", abort, { once: true });
+	});
+}

package/src/extension.ts

@@ -3,6 +3,7 @@ import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
+import { abortableSleep } from "./abortable-sleep";
 import { deliverTaskInbox, incorporatedTaskEvents } from "./task-inbox";
 import { TaskOutboxDeliveryError, TaskProtocolError } from "./task-protocol";
 import { createWolfpackTaskCore } from "./wolfpack-task-relay";
@@ -17,7 +18,9 @@ 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"]);
+const COORDINATOR_ONLY_TASK_TOOLS = new Set(["agent_task_send", "agent_task_cancel", "agent_task_ack"]);
 export const WORKER_GATE_DENIAL_CODE = "PI_TASK_WORKER_ASSIGNMENT_REQUIRED";
+export const WORKER_COORDINATION_FORBIDDEN_CODE = "PI_TASK_WORKER_COORDINATION_FORBIDDEN";
 
 const EndpointParams = Type.Object({
 	relay: Type.String({ minLength: 1, description: "relay identifier" }),
@@ -129,11 +132,12 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 
 	pi.on("tool_call", async (event, context) => {
 		if (!workerGateEnabled || PRE_ASSIGNMENT_TOOLS.has(event.toolName)) return undefined;
+		if (COORDINATOR_ONLY_TASK_TOOLS.has(event.toolName)) return { block: true, reason: WORKER_COORDINATION_FORBIDDEN_CODE };
 		try {
 			const activeCore = await configuredCore(context.signal);
 			const assignments = assignedWorkerTasks(activeCore, context.sessionManager.getEntries());
+			const taskId = inputTaskId(event.input);
 			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 };
@@ -141,6 +145,10 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 				closingTaskIds.add(assigned.taskId);
 				return undefined;
 			}
+			if (event.toolName === "agent_task_message") {
+				const assigned = taskId === undefined ? undefined : assignments.find((task) => task.taskId === taskId);
+				return assigned !== undefined && eligibleWorkerTask(assigned, closingTaskIds) ? undefined : { block: true, reason: WORKER_GATE_DENIAL_CODE };
+			}
 			if (assignments.some((task) => eligibleWorkerTask(task, closingTaskIds))) return undefined;
 		} catch {
 			// Authorization evidence unavailable or malformed: fail closed with the stable public reason.
@@ -205,7 +213,7 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 					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);
+					await abortableSleep(Math.max(1, Math.min(WAIT_POLL_MS, deadline - Date.now())), signal, () => new Error("task wait was cancelled"));
 				}
 			} catch (error) { return taskError(error); }
 		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
@@ -228,7 +236,17 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 	});
 	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); } },
+		async execute(_id, params, signal) {
+			try {
+				const activeCore = await configuredCore(signal);
+				try {
+					await activeCore.submitIntent({ taskId: params.taskId, type: "task.cancelled", payload: {} }, signal);
+					return toolResult({ taskId: params.taskId }, `## task cancellation requested\n- task: \`${params.taskId}\``);
+				} catch (error) {
+					return blockedCancellationResult(activeCore, params.taskId, error) ?? taskError(error);
+				}
+			} catch (error) { return taskError(error); }
+		},
 		renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
 	pi.registerTool({
@@ -275,6 +293,29 @@ function taskError(error: unknown): AgentToolResult<unknown> {
 	return toolResult({ error: { code: "TASK_ERROR", message, retryable: true } }, `## task error\n- ${message}`);
 }
 
+function blockedCancellationResult(core: TaskCore, taskId: string, error: unknown): AgentToolResult<unknown> | undefined {
+	if (!(error instanceof TaskOutboxDeliveryError) || error.code !== TARGET_NOT_REGISTERED_CODE || error.retryable || error.details?.taskId !== taskId) return undefined;
+	const task = core.getTask(taskId);
+	if (task?.status !== "cancelled" || !sameEndpoint(task.origin, core.endpoint)) return undefined;
+	const details = { ...error.details };
+	delete details.taskId;
+	delete details.envelopeId;
+	delete details.target;
+	delete details.blockedAt;
+	return toolResult({
+		taskId,
+		status: "cancelled",
+		warnings: [{
+			code: error.code,
+			message: error.message,
+			retryable: false,
+			delivery: "blocked",
+			target: task.target,
+			details,
+		}],
+	}, `## task cancelled\n- task: \`${taskId}\`\n- canonical status: cancelled\n- target delivery: blocked; receiver incorporation not confirmed`);
+}
+
 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";
 }
@@ -303,6 +344,10 @@ function sameEndpoint(left: TaskEndpoint, right: TaskEndpoint): boolean {
 	return left.relay === right.relay && left.id === right.id;
 }
 
+function inputTaskId(input: unknown): string | undefined {
+	return isRecord(input) && typeof input.taskId === "string" ? input.taskId : undefined;
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -311,11 +356,3 @@ 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 });
-	});
-}

package/src/legacy-extension.ts

@@ -3,6 +3,7 @@ import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
+import { abortableSleep } from "./abortable-sleep";
 import {
 	DEFAULT_TASK_TIMEOUT_MS,
 	GatewayClientError,
@@ -126,7 +127,7 @@ export function registerAgentTaskTools(pi: ExtensionAPI, client: WolfpackGateway
 					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);
+					await abortableSleep(Math.min(WAIT_POLL_MS, Math.max(1, deadline - Date.now())), signal, () => new GatewayClientError("ABORTED", "task wait was cancelled", true));
 				}
 			} catch (error) { return clientError(error); }
 		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
@@ -238,11 +239,3 @@ function text(result: { readonly content?: readonly unknown[] }): string {
 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/task-core.ts

@@ -1,5 +1,6 @@
 import {
 	MAX_RELAY_PAYLOAD_BYTES,
+	ORIGIN_CANCELLATION_OPERATION,
 	PARENT_ACKNOWLEDGMENT_OPERATION,
 	TASK_PROTOCOL_VERSION,
 	TERMINAL_INTENT_OPERATION,
@@ -141,12 +142,20 @@ export function createTaskCore(options: TaskCoreOptions): TaskCore {
 			if (!RECEIVER_INTENT_TYPES.has(input.type) || !isRecord(input.payload)) throw new TaskProtocolError("INVALID_INTENT", "intent type or payload is invalid");
 			let persistedEnvelopeIds: readonly string[] = [];
 			let receiverTerminal = false;
+			let originCancellation = false;
 			options.store.transaction(() => {
 				const task = requiredTask(options.store, input.taskId);
 				receiverTerminal = !sameEndpoint(options.endpoint, task.origin) && TERMINAL_EVENTS.has(input.type);
+				originCancellation = sameEndpoint(options.endpoint, task.origin) && input.type === "task.cancelled";
 				persistedEnvelopeIds = persistIntent(options, clock.now, ids, task, input);
 			});
-			await flush(options, signal, new Set(persistedEnvelopeIds));
+			try {
+				await flush(options, signal, new Set(persistedEnvelopeIds));
+			} catch (error) {
+				if (originCancellation) throwIfCancellationDeliveryBlocked(options, input.taskId, persistedEnvelopeIds);
+				throw error;
+			}
+			if (originCancellation) throwIfCancellationDeliveryBlocked(options, input.taskId, persistedEnvelopeIds);
 			if (receiverTerminal) throwIfTerminalDeliveryBlocked(options.store, input.taskId);
 		},
 		async recordInsertion(input, signal) {
@@ -242,7 +251,8 @@ function persistReceivedEnvelope(options: TaskCoreOptions, now: () => number, id
 
 function persistIntent(options: TaskCoreOptions, now: () => number, ids: () => string, task: TaskRecord, input: SubmitIntentInput): readonly string[] {
 	if (sameEndpoint(options.endpoint, task.origin)) {
-		return canonicalize(options, now, ids, task, { intentId: ids(), taskId: input.taskId, type: input.type, payload: input.payload }, input.type);
+		const operation = input.type === "task.cancelled" ? ORIGIN_CANCELLATION_OPERATION : undefined;
+		return canonicalize(options, now, ids, task, { intentId: ids(), taskId: input.taskId, type: input.type, payload: input.payload }, input.type, operation);
 	}
 	const envelopeId = ids();
 	const intent: TaskIntent = { intentId: ids(), taskId: input.taskId, type: input.type, payload: input.payload };
@@ -339,6 +349,16 @@ function parsePayload(envelope: RelayEnvelope): unknown {
 	try { return JSON.parse(envelope.payload) as unknown; } catch { throw new TaskProtocolError("INVALID_PAYLOAD", "relay envelope payload is not valid task protocol JSON"); }
 }
 
+function throwIfCancellationDeliveryBlocked(options: TaskCoreOptions, taskId: string, envelopeIds: readonly string[]): void {
+	const task = requiredTask(options.store, taskId);
+	const blocked = options.store.quarantinedOutbox().find((record) => envelopeIds.includes(record.envelope.envelopeId) && sameEndpoint(record.envelope.target, task.target));
+	if (blocked === undefined) return;
+	throw new TaskOutboxDeliveryError(blocked.errorCode, blocked.reason, {
+		retryable: false,
+		details: { ...blocked.details, taskId, envelopeId: blocked.envelope.envelopeId, target: task.target, blockedAt: blocked.quarantinedAt },
+	});
+}
+
 function throwIfTerminalDeliveryBlocked(store: TaskStore, taskId: string): void {
 	const delivery = requiredTask(store, taskId).terminalDelivery;
 	if (delivery.state !== "delivery_blocked") return;

package/src/task-inbox.ts

@@ -55,15 +55,6 @@ export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: Inb
 	}
 }
 
-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;
-}
-
 function inboxEvent(delivery: RelayDelivery): TaskEvent {
 	try {
 		const payload = JSON.parse(delivery.envelope.payload) as unknown;
@@ -113,7 +104,3 @@ function key(taskId: string, eventId: string): string {
 function isRecord(value: unknown): value is Record<string, unknown> {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
-
-function decimal(value: unknown): value is string {
-	return typeof value === "string" && /^(0|[1-9][0-9]*)$/.test(value);
-}

package/src/task-protocol.ts

@@ -1,5 +1,6 @@
 export const TASK_PROTOCOL_VERSION = "pi-tasks/v2" as const;
 export const MAX_RELAY_PAYLOAD_BYTES = 48 * 1024;
+export const ORIGIN_CANCELLATION_OPERATION = "origin_cancellation";
 export const PARENT_ACKNOWLEDGMENT_OPERATION = "parent_acknowledgment";
 export const TERMINAL_INTENT_OPERATION = "terminal_intent";