@sgtbeatdown/wolfpack-tasks 0.0.0-stage → 0.2.0

package/src/task-errors.ts

@@ -0,0 +1,111 @@
+// The single error-code registry. It imports nothing from task-protocol so that module can re-export from here.
+
+export type TaskErrorClass = "transport" | "capacity" | "protocol" | "state" | "auth" | "delivery";
+
+/** Class for a code missing from the registry, e.g. a newer server's. */
+export const UNKNOWN_TASK_ERROR_CLASS = "error";
+
+interface TaskErrorSpec {
+	readonly class: TaskErrorClass;
+	/** Default for throwers without better information; an explicit per-throw `retryable` always wins. */
+	readonly retryable: boolean;
+	readonly message: string;
+	/** A transport rejection with this code is retryable whatever the server flag says. */
+	readonly forceRetry?: true;
+	/** The volatile binding behind this response is gone; the session retires it. */
+	readonly resetsBinding?: true;
+	/** Relay task state was lost; the extension rebinds automatically. */
+	readonly relayLoss?: true;
+	/** A non-retryable send outcome that quarantines the envelope as blocked delivery. */
+	readonly blocksDelivery?: true;
+}
+
+export const TASK_ERRORS: Readonly<Record<string, TaskErrorSpec>> = {
+	// transport
+	RELAY_UNAVAILABLE: { class: "transport", retryable: true, forceRetry: true, message: "relay is unavailable" },
+	PEER_UNREACHABLE: { class: "transport", retryable: true, forceRetry: true, message: "peer relay is unreachable" },
+	RELAY_TIMEOUT: { class: "transport", retryable: true, message: "relay request timed out" },
+	RELAY_BUSY: { class: "transport", retryable: true, message: "relay handshake is already in progress" },
+	ABORTED: { class: "transport", retryable: true, message: "request was aborted" },
+	INVALID_RESPONSE: { class: "transport", retryable: true, message: "relay response is malformed" },
+	// capacity
+	RELAY_CAPACITY: { class: "capacity", retryable: true, forceRetry: true, message: "relay is at capacity" },
+	TASK_CAPACITY: { class: "capacity", retryable: false, message: "active task state is full" },
+	PAYLOAD_TOO_LARGE: { class: "capacity", retryable: false, message: "task payload is too large" },
+	TASK_DELIVERY_DEFERRED: { class: "capacity", retryable: true, message: "task delivery deferred by the local work budget or retry cooldown" },
+	// auth and policy
+	RELAY_AUTH_REQUIRED: { class: "auth", retryable: false, message: "Wolfpack authentication required" },
+	PEER_POLICY_REQUIRED: { class: "auth", retryable: false, message: "peer relay policy does not allow this request" },
+	UNAUTHORIZED_INTENT: { class: "auth", retryable: false, message: "intent is not authorized for this task" },
+	PI_TASK_WORKER_ASSIGNMENT_REQUIRED: { class: "auth", retryable: false, message: "worker tools require an active assignment" },
+	PI_TASK_WORKER_COORDINATION_FORBIDDEN: { class: "auth", retryable: false, message: "workers cannot coordinate other tasks" },
+	// relay and task state
+	RELAY_RESET: { class: "state", retryable: false, resetsBinding: true, relayLoss: true, message: "relay lifetime was reset" },
+	RELAY_REBIND_REQUIRED: { class: "state", retryable: false, relayLoss: true, message: "relay binding must be replaced" },
+	RELAY_STATE_LOST: { class: "state", retryable: false, message: "relay task state was lost" },
+	REGISTRATION_EXPIRED: { class: "state", retryable: false, resetsBinding: true, message: "relay registration expired" },
+	SOURCE_MISMATCH: { class: "state", retryable: false, resetsBinding: true, message: "relay source does not match the binding" },
+	CALLER_DEAD: { class: "state", retryable: false, resetsBinding: true, message: "calling session is gone" },
+	CALLER_NOT_FOUND: { class: "state", retryable: false, resetsBinding: true, message: "calling session is not found" },
+	RELAY_CLOSED: { class: "state", retryable: false, message: "task lifetime is closed" },
+	UNKNOWN_TASK: { class: "state", retryable: false, message: "unknown task" },
+	TASK_NOT_FOUND: { class: "state", retryable: false, message: "task is not active in this endpoint lifetime" },
+	TASK_NOT_TERMINAL: { class: "state", retryable: false, message: "only a terminal task may be acknowledged" },
+	TERMINAL_INTENT_CONFLICT: { class: "state", retryable: false, message: "a different terminal intent was already submitted" },
+	NOT_ORIGIN: { class: "state", retryable: false, message: "only the origin may perform this operation" },
+	NOT_PARTICIPANT: { class: "state", retryable: false, message: "endpoint is not a task participant" },
+	REASSIGNMENT_REFUSED: { class: "state", retryable: false, message: "task cannot be reassigned" },
+	TASK_ERROR: { class: "state", retryable: true, message: "task operation failed" },
+	// delivery
+	TARGET_NOT_REGISTERED: { class: "delivery", retryable: false, blocksDelivery: true, message: "target is not registered" },
+	INVALID_RELAY_METADATA: { class: "delivery", retryable: false, blocksDelivery: true, message: "relay metadata is invalid" },
+	DELIVERY_UNCONFIRMED: { class: "delivery", retryable: false, blocksDelivery: true, message: "peer delivery outcome is unknown" },
+	ENVELOPE_EXPIRED: { class: "delivery", retryable: false, blocksDelivery: true, message: "envelope expired before delivery" },
+	ENVELOPE_CONFLICT: { class: "delivery", retryable: false, blocksDelivery: true, message: "envelope id was reused with different content" },
+	CROSS_RELAY_ENDPOINT: { class: "delivery", retryable: false, blocksDelivery: true, message: "endpoint belongs to another relay" },
+	UNREGISTERED_TARGET: { class: "delivery", retryable: true, message: "target is not registered for this protocol" },
+	UNREGISTERED_SOURCE: { class: "delivery", retryable: true, message: "source is not registered for this protocol" },
+	UNKNOWN_RELAY: { class: "delivery", retryable: true, message: "target belongs to another relay" },
+	// protocol
+	RELAY_PROFILE_REQUIRED: { class: "protocol", retryable: false, message: "compatible memory-owned relay required" },
+	INCOMPATIBLE_PROTOCOL: { class: "protocol", retryable: false, message: "incompatible task protocol" },
+	INVALID_REQUEST: { class: "protocol", retryable: false, message: "relay rejected the request as invalid" },
+	INVALID_CONNECTION: { class: "protocol", retryable: true, message: "relay connected a different endpoint" },
+	INVALID_ACCEPTANCE: { class: "protocol", retryable: true, message: "relay acceptance is malformed" },
+	INVALID_INBOX: { class: "protocol", retryable: true, message: "relay inbox page is malformed" },
+	INVALID_DELIVERY: { class: "protocol", retryable: true, message: "relay returned an invalid or unordered delivery" },
+	INVALID_CURSOR: { class: "protocol", retryable: true, message: "relay cursor is invalid" },
+	INVALID_ENVELOPE: { class: "protocol", retryable: true, message: "relay envelope is malformed" },
+	INVALID_PAYLOAD: { class: "protocol", retryable: true, message: "relay envelope payload is invalid" },
+	INVALID_TARGET: { class: "protocol", retryable: true, message: "target is invalid" },
+	INVALID_ENDPOINT: { class: "protocol", retryable: true, message: "endpoint is invalid" },
+	INVALID_ENDPOINT_REFERENCE: { class: "protocol", retryable: true, message: "endpoint reference is invalid" },
+	INVALID_TASK: { class: "protocol", retryable: true, message: "task and a positive timeout are required" },
+	INVALID_ASSIGNMENT: { class: "protocol", retryable: true, message: "assignment is invalid" },
+	INVALID_INTENT: { class: "protocol", retryable: true, message: "task intent is invalid" },
+	INVALID_EVENT: { class: "protocol", retryable: true, message: "task event is invalid" },
+	INVALID_INBOX_EVENT: { class: "protocol", retryable: true, message: "relay envelope does not contain a valid model event" },
+	UNKNOWN_EVENT: { class: "protocol", retryable: true, message: "unknown task event type" },
+};
+
+function codes(flag: (spec: TaskErrorSpec) => boolean | undefined): ReadonlySet<string> {
+	return new Set(Object.entries(TASK_ERRORS).flatMap(([code, spec]) => flag(spec) ? [code] : []));
+}
+
+export const RETRY_CODES = codes(spec => spec.forceRetry);
+export const RESET_CODES = codes(spec => spec.resetsBinding);
+export const RELAY_LOSS_CODES = codes(spec => spec.relayLoss);
+const BLOCKED_OUTBOX_DELIVERY_CODES = codes(spec => spec.blocksDelivery);
+
+export function isBlockedOutboxDeliveryCode(code: string): boolean {
+	return BLOCKED_OUTBOX_DELIVERY_CODES.has(code);
+}
+
+export function taskErrorClass(code: string): TaskErrorClass | typeof UNKNOWN_TASK_ERROR_CLASS {
+	return TASK_ERRORS[code]?.class ?? UNKNOWN_TASK_ERROR_CLASS;
+}
+
+/** The registry message, or the code itself for an unregistered code. */
+export function taskErrorMessage(code: string): string {
+	return TASK_ERRORS[code]?.message ?? code;
+}

package/src/task-inbox.ts

@@ -0,0 +1,292 @@
+import type { TaskCore } from "./task-core";
+import { createTaskWorkScope } from "./task-work-scope";
+import type { TaskShipment, TaskWorkScope } from "./task-work-scope";
+import { TASK_EVENT_TYPES, TaskDeliveryEvidenceState, TaskDeliveryStage, TaskEnvelopeKind, TaskOutboxDeliveryError, TaskProtocolError, isBlockedOutboxDeliveryCode } from "./task-protocol";
+import type { RelayDelivery, TaskEvent } from "./task-protocol";
+
+const TASK_EVENT_CUSTOM_TYPE = "pi-tasks-event";
+const TASK_WAKE_CUSTOM_TYPE = "pi-tasks-wake";
+const TASK_CURSOR_CUSTOM_TYPE = "pi-tasks-relay-cursor";
+const TASK_RECORD_CUSTOM_TYPE = "pi-tasks-event-record";
+
+interface InboxContext {
+	readonly isIdle: () => boolean;
+	readonly hasPendingMessages: () => boolean;
+	readonly sessionManager: { readonly getEntries: () => readonly unknown[] };
+}
+
+interface InboxPi {
+	sendMessage(
+		message: { readonly customType: string; readonly content: string; readonly display: boolean; readonly details: TaskEventDetails },
+		options: { readonly triggerTurn: false } | { readonly triggerTurn: true; readonly deliverAs: "followUp" },
+	): void;
+	appendEntry(customType: string, data: { readonly cursor: string } | TaskEventDetails): void;
+}
+
+export interface TaskEventDetails {
+	readonly taskId: string;
+	readonly eventId: string;
+	/** Historical evidence only; never used to rebuild active task state. */
+	readonly event?: TaskEvent;
+}
+
+type DeliveryEvidencePayload =
+	| { readonly stage: typeof TaskDeliveryStage.receiverRecorded | typeof TaskDeliveryStage.wakeAccepted; readonly state: typeof TaskDeliveryEvidenceState.confirmed }
+	| { readonly stage: typeof TaskDeliveryStage.piInsertion; readonly state: typeof TaskDeliveryEvidenceState.blocked; readonly retryable: true };
+
+/** Relay items carry delivery receipts; origin-local items never emit receipts, insertion records or ACKs. */
+interface RelayReceipts {
+	readonly signal: AbortSignal;
+	readonly work: TaskWorkScope;
+}
+
+/** Persists model-visible Pi evidence before advancing the relay cursor or retiring a local item, then starts one separate turn. */
+export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: InboxContext, signal?: AbortSignal, work = createTaskWorkScope(signal, "phased")): Promise<TaskOutboxDeliveryError | undefined> {
+	// Explicit phases: intake, presentation, required sends, ACKs, then old-work retry.
+	if (!work.phased) throw new TypeError("inbox delivery requires a phased work scope");
+	signal = work.signal;
+	let outboxError: TaskOutboxDeliveryError | undefined;
+	let failure: unknown;
+	const receipts: RelayReceipts = { signal, work };
+	try {
+		// Intake persists and canonicalizes without sending; earlier required sends of this pass are already queued.
+		const items = await core.intakeInbox(signal, work);
+		// Presentation persists Pi evidence only. Each relay item ends in an ACK, so stop at the remaining budget.
+		const budget = work.remainingAcknowledgements();
+		const presented: { readonly cursor: string; readonly shipments: readonly TaskShipment[] }[] = [];
+		// Shipments queued from here on are this presentation's delivery receipts.
+		const receiptsFrom = work.shipments.length;
+		try {
+			// The first held model-visible item holds every later visible item, so none overtakes it;
+			// later control facts and self-authored copies are still archived and ACKed.
+			let held = false;
+			for (const item of items) {
+				if (item.kind === "local") {
+					if (held && isPresentedToModel(core, item.event)) continue;
+					if (!await presentEvent(pi, core, context, item.event, undefined)) { held = true; continue; }
+					core.completeLocalPresentation(item.event.eventId);
+					continue;
+				}
+				if (presented.length >= budget) break;
+				const delivery = item.delivery;
+				const mark = work.shipments.length;
+				if (delivery.envelope.kind !== TaskEnvelopeKind.intent) {
+					const event = inboxEvent(delivery);
+					if (held && isPresentedToModel(core, event)) continue;
+					if (!await presentEvent(pi, core, context, event, receipts)) { held = true; continue; }
+				}
+				presented.push({ cursor: delivery.cursor, shipments: work.shipments.slice(mark) });
+			}
+		} catch (error) {
+			// Items presented before the failure still ship and ACK; the failure surfaces at the end.
+			if (work.signal.aborted) throw error;
+			failure = error;
+		}
+		// Required sends in persist order. A receipt blocked for good is reported and does not hold its ACK.
+		await core.shipRequired(signal, work);
+		for (const [index, shipment] of work.shipments.entries()) {
+			if (shipment.failure === undefined) continue;
+			if (index >= receiptsFrom && isBlockedDeliveryFailure(shipment.failure)) outboxError ??= shipment.failure;
+			else failure ??= shipment.failure;
+		}
+		// ACK only items whose receipts were accepted or blocked for good.
+		try {
+			for (const { cursor, shipments } of presented) {
+				if (shipments.some(shipment => !shipment.shipped || (shipment.failure !== undefined && !isBlockedDeliveryFailure(shipment.failure)))) continue;
+				await core.acknowledgeRelayDelivery(cursor, signal, work);
+				pi.appendEntry(TASK_CURSOR_CUSTOM_TYPE, { cursor });
+			}
+			await core.repairAcknowledgements(signal, work);
+		} catch (error) {
+			if (work.signal.aborted) throw error;
+			failure ??= error;
+		}
+	} finally {
+		// Completed, held or failed delivery yields the remaining bounded share to old work.
+		if (!work.signal.aborted) try { await core.flushOutbox(work.signal, work); } catch (error) {
+			if (!(error instanceof TaskOutboxDeliveryError)) throw error;
+			outboxError ??= error;
+		}
+	}
+	// Collected failures surface only after presentation, ACKs and the bounded flush had their share.
+	if (failure !== undefined) throw failure;
+	return outboxError;
+}
+
+/**
+ * Idle gate, insertion, rescan, wake and wake evidence for one event. Returns false when presentation is held.
+ * Receipts collapse to the highest stage reached in this refresh (the origin derives the stages it implies),
+ * plus `pi_insertion` blocked when insertion was not observed.
+ */
+async function presentEvent(pi: InboxPi, core: TaskCore, context: InboxContext, event: TaskEvent, receipts: RelayReceipts | undefined): Promise<boolean> {
+	const eventDetails = { taskId: event.taskId, eventId: event.eventId };
+	const eventKey = key(event.taskId, event.eventId);
+	if (!isPresentedToModel(core, event)) {
+		// Archive control facts and confirmed self-authored conversations without model insertion or wake,
+		// even while Pi is busy. This is evidence only: no task state or delivery queue is reconstructed.
+		if (!taskEntryEvidence(context.sessionManager).recorded.has(eventKey)) pi.appendEntry(TASK_RECORD_CUSTOM_TYPE, { ...eventDetails, event });
+		return true;
+	}
+	if (context.hasPendingMessages()) return false;
+	const recordReceiver = async () => {
+		if (receipts && (event.type === "task.created" || event.type === "task.reassigned")) await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.receiverRecorded, state: TaskDeliveryEvidenceState.confirmed }, receipts);
+	};
+	const recordInsertion = async () => {
+		if (receipts) await core.recordInsertion(eventDetails, receipts.signal, receipts.work);
+	};
+	const incorporated = () => taskEntryEvidence(context.sessionManager).incorporated.get(event.taskId)?.has(event.eventId) === true;
+	if (!incorporated()) {
+		if (!context.isIdle()) { await recordReceiver(); return false; }
+		pi.sendMessage({
+			customType: TASK_EVENT_CUSTOM_TYPE,
+			content: renderTaskEvent(event),
+			display: true,
+			details: { ...eventDetails, event },
+		}, { triggerTurn: false });
+		if (!incorporated()) {
+			await recordReceiver();
+			if (receipts) await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.piInsertion, state: TaskDeliveryEvidenceState.blocked, retryable: true }, receipts);
+			return false;
+		}
+	}
+	if (taskEntryEvidence(context.sessionManager).wakes.has(eventKey)) {
+		if (receipts) await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.wakeAccepted, state: TaskDeliveryEvidenceState.confirmed }, receipts);
+		return true;
+	}
+	if (hasAcknowledgedLocalOriginTerminal(core, event)) { await recordInsertion(); return true; }
+	if (!context.isIdle()) { await recordInsertion(); return false; }
+	// This synchronous local write closes the ACK/wake race; do not await relay I/O before Pi emits the wake.
+	const wakeRequest = receipts && core.recordWakeRequest(eventDetails, receipts.work);
+	let wakeAccepted = false;
+	try {
+		pi.sendMessage({
+			customType: TASK_WAKE_CUSTOM_TYPE,
+			content: "Process the pending Pi task event.",
+			display: false,
+			details: eventDetails,
+		}, { triggerTurn: true, deliverAs: "followUp" });
+		wakeAccepted = taskEntryEvidence(context.sessionManager).wakes.has(eventKey);
+	} finally {
+		// An unaccepted or throwing wake must not leave a wake_accepted record for the outbox flush.
+		if (!wakeAccepted) wakeRequest?.discard();
+	}
+	if (!wakeAccepted) { await recordInsertion(); return false; }
+	if (receipts && wakeRequest) await wakeRequest.flush(receipts.signal);
+	return true;
+}
+
+/** Persists the receipt; the phased pass ships it before the item's ACK. */
+async function recordDeliveryEvidence(core: TaskCore, event: TaskEventDetails, evidence: DeliveryEvidencePayload, receipts: RelayReceipts): Promise<void> {
+	await core.submitIntent({ taskId: event.taskId, type: "task.delivery_receipt", payload: { eventId: event.eventId, ...evidence } }, receipts.signal, receipts.work);
+}
+
+function isBlockedDeliveryFailure(error: unknown): error is TaskOutboxDeliveryError {
+	return error instanceof TaskOutboxDeliveryError && !error.retryable && isBlockedOutboxDeliveryCode(error.code);
+}
+
+function inboxEvent(delivery: RelayDelivery): TaskEvent {
+	try {
+		const payload = JSON.parse(delivery.envelope.payload) as unknown;
+		if (!isRecord(payload)) throw new Error("not an object");
+		if (delivery.envelope.kind === TaskEnvelopeKind.assignment && isTaskEvent(payload.event)) return payload.event;
+		if (delivery.envelope.kind === TaskEnvelopeKind.canonicalEvent && isTaskEvent(payload)) return payload;
+	} catch { /* normalize malformed opaque payloads to a protocol error */ }
+	throw new TaskProtocolError("INVALID_INBOX_EVENT", "relay envelope does not contain a valid model event");
+}
+
+/** Model insertion and wake apply; otherwise the event is archived. Throws for an unknown event type. */
+function isPresentedToModel(core: TaskCore, event: TaskEvent): boolean {
+	const type = TASK_EVENT_TYPES[event.type];
+	if (type === undefined) throw new TaskProtocolError("UNKNOWN_EVENT", `unknown task inbox event type: ${event.type}`);
+	return type.visible && !core.isSelfAuthoredConversation(event);
+}
+
+function hasAcknowledgedLocalOriginTerminal(core: TaskCore, event: TaskEvent): boolean {
+	if (TASK_EVENT_TYPES[event.type]?.terminal !== true) return false;
+	const task = core.getTask(event.taskId);
+	if (task === undefined || task.origin.relay !== core.endpoint.relay || task.origin.id !== core.endpoint.id) return false;
+	const terminalIndex = task.events.findIndex((candidate) => candidate.eventId === event.eventId && candidate.type === event.type);
+	return terminalIndex >= 0 && task.events.slice(terminalIndex + 1).some((candidate) => candidate.type === "task.parent_acknowledged");
+}
+
+function renderTaskEvent(event: TaskEvent): string {
+	if (event.type === "task.created") return `## task assignment\ntask: \`${event.taskId}\` · event: \`${event.eventId}\`\n\n${String(event.payload.task ?? "")}`;
+	// The successor sees the task itself; earlier history stays in the task record (agent_task_status).
+	if (event.type === "task.reassigned") return `## task assignment (reassigned)\ntask: \`${event.taskId}\` · event: \`${event.eventId}\`\n\nthe previous target was lost; earlier task history is in agent_task_status.\n\n${String(event.payload.task ?? "")}`;
+	const body = typeof event.payload.message === "string" ? `\n\n${event.payload.message}` : "";
+	const summary = typeof event.payload.summary === "string" ? `\n\n**summary:** ${event.payload.summary}` : "";
+	return `## task ${event.type.replace(/^task\./, "").replaceAll("_", " ")}\ntask: \`${event.taskId}\` · event: \`${event.eventId}\`${body}${summary}`;
+}
+
+export function incorporatedTaskEvents(entries: readonly unknown[]): readonly TaskEventDetails[] {
+	return taskMessageDetails(entries, TASK_EVENT_CUSTOM_TYPE);
+}
+
+function taskMessageDetails(entries: readonly unknown[], customType: string): readonly TaskEventDetails[] {
+	const events: TaskEventDetails[] = [];
+	for (const entry of entries) {
+		if (!isRecord(entry) || entry.type !== "custom_message" || entry.customType !== customType || !isRecord(entry.details) || typeof entry.details.taskId !== "string" || typeof entry.details.eventId !== "string") continue;
+		events.push({ taskId: entry.details.taskId, eventId: entry.details.eventId });
+	}
+	return events;
+}
+
+/** Session evidence keys, derived from entries only; never task state. */
+export interface TaskEntryEvidence {
+	/** Incorporated `pi-tasks-event` event ids by task id. */
+	readonly incorporated: ReadonlyMap<string, ReadonlySet<string>>;
+	/** `pi-tasks-event-record` keys. */
+	readonly recorded: ReadonlySet<string>;
+	/** `pi-tasks-wake` keys. */
+	readonly wakes: ReadonlySet<string>;
+}
+
+interface EntryMemo extends TaskEntryEvidence {
+	readonly incorporated: Map<string, Set<string>>;
+	readonly recorded: Set<string>;
+	readonly wakes: Set<string>;
+	length: number;
+	last: unknown;
+}
+
+const entryMemos = new WeakMap<object, EntryMemo>();
+
+/**
+ * Evidence for this session manager, extended with appended entries only. Pi entries are immutable and appended,
+ * so an unchanged entry at the last indexed position means nothing before it changed; anything else rescans.
+ */
+export function taskEntryEvidence(sessionManager: InboxContext["sessionManager"]): TaskEntryEvidence {
+	const entries = sessionManager.getEntries();
+	let memo = entryMemos.get(sessionManager);
+	if (!memo || entries.length < memo.length || (memo.length > 0 && entries[memo.length - 1] !== memo.last)) {
+		memo = { incorporated: new Map(), recorded: new Set(), wakes: new Set(), length: 0, last: undefined };
+		entryMemos.set(sessionManager, memo);
+	}
+	for (let index = memo.length; index < entries.length; index++) indexEntry(memo, entries[index]);
+	if (entries.length > memo.length) { memo.length = entries.length; memo.last = entries[entries.length - 1]; }
+	return memo;
+}
+
+function indexEntry(memo: EntryMemo, entry: unknown): void {
+	if (!isRecord(entry)) return;
+	const details = entry.type === "custom" ? entry.data : entry.type === "custom_message" ? entry.details : undefined;
+	if (!isRecord(details) || typeof details.taskId !== "string" || typeof details.eventId !== "string") return;
+	if (entry.type === "custom" && entry.customType === TASK_RECORD_CUSTOM_TYPE) memo.recorded.add(key(details.taskId, details.eventId));
+	else if (entry.type === "custom_message" && entry.customType === TASK_WAKE_CUSTOM_TYPE) memo.wakes.add(key(details.taskId, details.eventId));
+	else if (entry.type === "custom_message" && entry.customType === TASK_EVENT_CUSTOM_TYPE) {
+		const events = memo.incorporated.get(details.taskId) ?? new Set<string>();
+		events.add(details.eventId); memo.incorporated.set(details.taskId, events);
+	}
+}
+
+function isTaskEvent(value: unknown): value is TaskEvent {
+	return isRecord(value) && typeof value.eventId === "string" && typeof value.taskId === "string" && typeof value.type === "string" && typeof value.sequence === "string" && isRecord(value.source) && isRecord(value.target) && typeof value.occurredAt === "number" && isRecord(value.payload);
+}
+
+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);
+}

package/src/task-protocol.ts

@@ -0,0 +1,243 @@
+export const TASK_PROTOCOL_VERSION = "pi-tasks/v2" as const;
+export const MAX_RELAY_PAYLOAD_BYTES = 48 * 1024;
+export const INVALID_RELAY_METADATA = "INVALID_RELAY_METADATA";
+export const ORIGIN_CANCELLATION_OPERATION = "origin_cancellation";
+export const PARENT_ACKNOWLEDGMENT_OPERATION = "parent_acknowledgment";
+export const TERMINAL_INTENT_OPERATION = "terminal_intent";
+
+export { isBlockedOutboxDeliveryCode } from "./task-errors";
+
+export interface TaskEventTypeSpec {
+	/** Inserted into the model and woken; otherwise archived as evidence only. */
+	readonly visible: boolean;
+	/** Ends the task; `status` is the task status it sets. */
+	readonly terminal: boolean;
+	readonly status?: Exclude<TaskRecord["status"], "active">;
+	/** Peer conversation that carries the sender's intent identity. */
+	readonly conversational: boolean;
+	/** Origin-local delivery evidence, never forwarded to the worker. */
+	readonly evidence: boolean;
+	/** A receiver may submit it as a raw intent. */
+	readonly intent: boolean;
+}
+
+const eventType = (flags: Partial<TaskEventTypeSpec>): TaskEventTypeSpec => ({ visible: true, terminal: false, conversational: false, evidence: false, intent: false, ...flags });
+
+/** Every canonical task event type this protocol version accepts, with its handling. */
+export const TASK_EVENT_TYPES: Readonly<Record<string, TaskEventTypeSpec>> = {
+	"task.created": eventType({}),
+	/** Origin moved an active task to its lost target's successor; travels as an assignment carrying the history. */
+	"task.reassigned": eventType({}),
+	"task.completed": eventType({ terminal: true, status: "completed", intent: true }),
+	"task.failed": eventType({ terminal: true, status: "failed", intent: true }),
+	"task.cancelled": eventType({ terminal: true, status: "cancelled", intent: true }),
+	"task.timed_out": eventType({ terminal: true, status: "timed_out" }),
+	"task.information": eventType({ conversational: true, intent: true }),
+	"task.question": eventType({ conversational: true, intent: true }),
+	"task.answer": eventType({ conversational: true, intent: true }),
+	"task.delivery_receipt": eventType({ visible: false, evidence: true, intent: true }),
+	"task.parent_acknowledged": eventType({ visible: false }),
+	"task.late_terminal": eventType({ visible: false }),
+};
+
+export function taskEventTypes(predicate: (type: TaskEventTypeSpec) => boolean): ReadonlySet<string> {
+	return new Set(Object.entries(TASK_EVENT_TYPES).flatMap(([type, spec]) => predicate(spec) ? [type] : []));
+}
+
+/**
+ * Ordered receiver_recorded < pi_inserted < wake_accepted; a later stage implies the earlier ones.
+ * Receivers emit the highest stage reached per refresh plus pi_insertion blocked. wake_requested is
+ * accepted from 0.1.15 receivers but no longer emitted.
+ */
+export const TaskDeliveryStage = {
+	receiverRecorded: "receiver_recorded",
+	piInsertion: "pi_insertion",
+	piInserted: "pi_inserted",
+	wakeRequested: "wake_requested",
+	wakeAccepted: "wake_accepted",
+} as const;
+
+export const TaskDeliveryEvidenceState = {
+	confirmed: "confirmed",
+	blocked: "blocked",
+} as const;
+
+export interface TaskEndpoint {
+	readonly relay: string;
+	readonly id: string;
+}
+
+/** Endpoint-owned transport binding; not task lifecycle or relay replay state. */
+export interface RelayTransportBinding {
+	readonly profile: "volatile-v1";
+	readonly epoch: string;
+	readonly endpoint: TaskEndpoint;
+	readonly generation: string;
+	readonly callerSession: string;
+	readonly url: string;
+	readonly reset?: true;
+}
+
+/** A provider-defined reference which core resolves without interpreting. */
+export interface RelayTargetReference {
+	readonly relay: string;
+	readonly reference: string;
+}
+
+export interface RelayConnectInput {
+	readonly endpoint: TaskEndpoint;
+	readonly protocolVersion: string;
+	readonly receiveCursor: string;
+}
+
+export interface RelayConnection {
+	readonly endpoint: TaskEndpoint;
+	readonly receiveCursor: string;
+}
+
+export const TaskEnvelopeKind = {
+	assignment: "assignment",
+	intent: "intent",
+	canonicalEvent: "canonical_event",
+} as const;
+
+export type TaskEnvelopeKind = (typeof TaskEnvelopeKind)[keyof typeof TaskEnvelopeKind];
+
+export interface RelayEnvelope {
+	readonly envelopeId: string;
+	readonly protocolVersion: string;
+	readonly source: TaskEndpoint;
+	readonly target: TaskEndpoint;
+	readonly taskId: string;
+	readonly kind: TaskEnvelopeKind;
+	/** Immutable transport creation time, persisted with new outbox envelopes.
+	 * Received/legacy records may omit it; Wolfpack sends require it. */
+	readonly createdAt?: string;
+	/** Opaque to relays. The endpoint protocol defines its JSON representation. */
+	readonly payload: string;
+}
+
+export interface RelayAcceptance {
+	readonly envelopeId: string;
+}
+
+export interface RelayReceiveRequest {
+	readonly endpoint: TaskEndpoint;
+	readonly cursor: string;
+	readonly limit: number;
+}
+
+export interface RelayDelivery {
+	readonly cursor: string;
+	readonly envelope: RelayEnvelope;
+}
+
+export interface RelayInboxPage {
+	readonly deliveries: readonly RelayDelivery[];
+	readonly nextCursor: string;
+	readonly hasMore: boolean;
+}
+
+export interface RelayDeliveryAck {
+	readonly endpoint: TaskEndpoint;
+	readonly cursor: string;
+	/** Durable cursor-to-envelope binding, for identical ACK retry after reopen. */
+	readonly envelopeId?: string;
+}
+
+export interface TaskRelay {
+	readonly id: string;
+	connect(input: RelayConnectInput, signal?: AbortSignal): Promise<RelayConnection>;
+	resolve(input: RelayTargetReference, signal?: AbortSignal): Promise<TaskEndpoint>;
+	send(input: RelayEnvelope, signal?: AbortSignal): Promise<RelayAcceptance>;
+	receive(input: RelayReceiveRequest, signal?: AbortSignal): Promise<RelayInboxPage>;
+	/** Acknowledge this delivery only, never an implicit cursor prefix. */
+	acknowledgeDelivery(input: RelayDeliveryAck, signal?: AbortSignal): Promise<void>;
+}
+
+export interface TaskEvent {
+	readonly eventId: string;
+	readonly taskId: string;
+	readonly type: string;
+	readonly sequence: string;
+	readonly source: TaskEndpoint;
+	readonly target: TaskEndpoint;
+	readonly occurredAt: number;
+	readonly payload: Record<string, unknown>;
+}
+
+export interface TaskRecord {
+	readonly taskId: string;
+	readonly protocolVersion: string;
+	readonly origin: TaskEndpoint;
+	readonly target: TaskEndpoint;
+	readonly task: string;
+	readonly createdAt: number;
+	readonly expiresAt: number;
+	readonly status: "active" | "completed" | "failed" | "cancelled" | "timed_out";
+	readonly events: readonly TaskEvent[];
+}
+
+export type TerminalTaskIntentType = "task.completed" | "task.failed" | "task.cancelled";
+
+export type TaskDeliveryStage = (typeof TaskDeliveryStage)[keyof typeof TaskDeliveryStage];
+export type TaskDeliveryEvidenceState = (typeof TaskDeliveryEvidenceState)[keyof typeof TaskDeliveryEvidenceState];
+
+export interface TaskIntent {
+	readonly intentId: string;
+	readonly taskId: string;
+	readonly type: TerminalTaskIntentType | "task.information" | "task.question" | "task.answer" | "task.delivery_receipt";
+	readonly payload: Record<string, unknown>;
+}
+
+interface TerminalDeliveryIdentity {
+	readonly intentId: string;
+	readonly intentType: TerminalTaskIntentType;
+	readonly envelopeId: string;
+	readonly origin: TaskEndpoint;
+}
+
+interface TerminalDeliveryPending extends TerminalDeliveryIdentity {
+	readonly state: "pending";
+}
+
+interface TerminalDeliveryAccepted extends TerminalDeliveryIdentity {
+	readonly state: "accepted";
+}
+
+interface TerminalDeliveryBlocked extends TerminalDeliveryIdentity {
+	readonly state: "delivery_blocked";
+	readonly blockedAt: number;
+	readonly error: { readonly code: string; readonly retryable: false; readonly details: Readonly<Record<string, unknown>> };
+}
+
+export type TerminalDeliveryState =
+	| { readonly state: "not_submitted" }
+	| TerminalDeliveryPending
+	| TerminalDeliveryAccepted
+	| TerminalDeliveryBlocked;
+
+export interface TaskSnapshot extends TaskRecord {
+	readonly terminalDelivery: TerminalDeliveryState;
+}
+
+export class TaskProtocolError extends Error {
+	readonly code: string;
+	readonly retryable: boolean;
+	readonly details: Readonly<Record<string, unknown>> | undefined;
+
+	constructor(code: string, message: string, options: { readonly retryable?: boolean; readonly details?: Readonly<Record<string, unknown>> } = {}) {
+		super(message);
+		this.name = "TaskProtocolError";
+		this.code = code;
+		this.retryable = options.retryable ?? true;
+		this.details = options.details;
+	}
+}
+
+export class TaskOutboxDeliveryError extends TaskProtocolError {
+	constructor(code: string, message: string, options: { readonly retryable?: boolean; readonly details?: Readonly<Record<string, unknown>> } = {}) {
+		super(code, message, options);
+		this.name = "TaskOutboxDeliveryError";
+	}
+}