@sgtbeatdown/pi-tasks 0.1.1 → 0.1.3

package/src/task-core.ts

@@ -0,0 +1,430 @@
+import {
+	MAX_RELAY_PAYLOAD_BYTES,
+	PARENT_ACKNOWLEDGMENT_OPERATION,
+	TASK_PROTOCOL_VERSION,
+	TERMINAL_INTENT_OPERATION,
+	TaskEnvelopeKind,
+	TaskOutboxDeliveryError,
+	TaskProtocolError,
+} from "./task-protocol";
+import type {
+	RelayDelivery,
+	RelayEnvelope,
+	TaskEndpoint,
+	TaskEvent,
+	TaskIntent,
+	TaskRecord,
+	TaskRelay,
+	TaskSnapshot,
+} from "./task-protocol";
+import type { TaskStore } from "./task-store";
+
+const RECEIVE_PAGE_SIZE = 100;
+const TARGET_NOT_REGISTERED_CODE = "TARGET_NOT_REGISTERED";
+const TERMINAL_STATUSES = new Set<TaskRecord["status"]>(["completed", "failed", "cancelled", "timed_out"]);
+const TERMINAL_EVENTS = new Set(["task.completed", "task.failed", "task.cancelled", "task.timed_out"]);
+const CANONICAL_EVENTS = new Set([
+	"task.created", "task.completed", "task.failed", "task.cancelled", "task.timed_out",
+	"task.information", "task.question", "task.answer", "task.delivery_receipt", "task.parent_acknowledged", "task.late_terminal",
+]);
+const RECEIVER_INTENT_TYPES = new Set<TaskIntent["type"]>([
+	"task.completed", "task.failed", "task.cancelled", "task.information", "task.question", "task.answer", "task.delivery_receipt",
+]);
+const IGNORE_OUTBOX_FAILURES: ReadonlySet<string> = new Set();
+
+export interface TaskCoreOptions {
+	readonly endpoint: TaskEndpoint;
+	readonly relay: TaskRelay;
+	readonly store: TaskStore;
+	readonly clock?: { readonly now: () => number };
+	readonly ids?: () => string;
+}
+
+export interface CreateTaskInput {
+	readonly target: TaskEndpoint;
+	readonly task: string;
+	readonly timeoutMs: number;
+}
+
+export interface SubmitIntentInput {
+	readonly taskId: string;
+	readonly type: TaskIntent["type"];
+	readonly payload: Record<string, unknown>;
+}
+
+export interface TaskCore {
+	readonly endpoint: TaskEndpoint;
+	connect(signal?: AbortSignal): Promise<void>;
+	createTask(input: CreateTaskInput, signal?: AbortSignal): Promise<{ readonly taskId: string }>;
+	getTask(taskId: string): TaskSnapshot | undefined;
+	listTasks(): readonly TaskSnapshot[];
+	flushOutbox(signal?: AbortSignal): Promise<void>;
+	receive(signal?: AbortSignal): Promise<readonly RelayDelivery[]>;
+	acknowledgeRelayDelivery(cursor: string, signal?: AbortSignal): Promise<void>;
+	submitIntent(input: SubmitIntentInput, signal?: AbortSignal): Promise<void>;
+	recordInsertion(input: { readonly taskId: string; readonly eventId: string }, signal?: AbortSignal): Promise<void>;
+	evaluateTimeouts(signal?: AbortSignal): Promise<void>;
+	acknowledgeParent(taskId: string, signal?: AbortSignal): Promise<void>;
+}
+
+type ReceivedEnvelope =
+	| { readonly kind: "assignment"; readonly task: Omit<TaskRecord, "events">; readonly event: TaskEvent }
+	| { readonly kind: "intent"; readonly task: TaskRecord; readonly intent: TaskIntent }
+	| { readonly kind: "canonical_event"; readonly task: TaskRecord; readonly event: TaskEvent };
+
+export function createTaskCore(options: TaskCoreOptions): TaskCore {
+	const clock = options.clock ?? { now: (): number => Date.now() };
+	const ids = options.ids ?? (() => crypto.randomUUID());
+
+	return {
+		endpoint: options.endpoint,
+		async connect(signal) {
+			const connection = await options.relay.connect({ endpoint: options.endpoint, protocolVersion: TASK_PROTOCOL_VERSION, receiveCursor: options.store.getReceiveCursor() }, signal);
+			if (!sameEndpoint(connection.endpoint, options.endpoint)) throw new TaskProtocolError("INVALID_CONNECTION", "relay connected a different endpoint");
+			throwIfAborted(signal);
+		},
+		async createTask(input, signal) {
+			if (input.task.length === 0 || !Number.isInteger(input.timeoutMs) || input.timeoutMs < 1) throw new TaskProtocolError("INVALID_TASK", "task and a positive timeout are required");
+			const target = await options.relay.resolve({ relay: input.target.relay, reference: input.target.id }, signal);
+			if (!isEndpoint(target)) throw new TaskProtocolError("INVALID_TARGET", "relay resolved an invalid task endpoint");
+			const now = clock.now();
+			const taskId = ids();
+			const task: Omit<TaskRecord, "events"> = {
+				taskId, protocolVersion: TASK_PROTOCOL_VERSION, origin: options.endpoint, target, task: input.task,
+				createdAt: now, expiresAt: now + input.timeoutMs, status: "active",
+			};
+			const created = event(task, ids(), "task.created", "1", options.endpoint, target, now, { task: input.task });
+			const assignment = envelope(ids(), options.endpoint, target, taskId, TaskEnvelopeKind.assignment, { task, event: created });
+			options.store.transaction(() => {
+				options.store.putTask(task);
+				options.store.appendEvent(created);
+				options.store.putOutbox(assignment);
+			});
+			try {
+				await flush(options, signal, new Set([assignment.envelopeId]));
+			} catch (error) {
+				throw operationError(error, taskId);
+			}
+			return { taskId };
+		},
+		getTask(taskId) { return options.store.getTask(taskId); },
+		listTasks() { return options.store.listTasks(); },
+		async flushOutbox(signal) { await flush(options, signal); },
+		async receive(signal) {
+			await flush(options, signal, IGNORE_OUTBOX_FAILURES);
+			const page = await options.relay.receive({ endpoint: options.endpoint, cursor: options.store.getReceiveCursor(), limit: RECEIVE_PAGE_SIZE }, signal);
+			if (!isInboxPage(page)) throw new TaskProtocolError("INVALID_INBOX", "relay returned an invalid inbox page");
+			const visibleDeliveries: RelayDelivery[] = [];
+			for (const delivery of page.deliveries) {
+				if (!isDelivery(delivery)) throw new TaskProtocolError("INVALID_DELIVERY", "relay returned an invalid delivery");
+				const received = validateReceivedEnvelope(options, delivery.envelope);
+				let persistedEnvelopeIds: readonly string[] = [];
+				options.store.transaction(() => {
+					if (!options.store.persistInbox(delivery.envelope, delivery.cursor)) return;
+					persistedEnvelopeIds = persistReceivedEnvelope(options, clock.now, ids, received);
+				});
+				if (persistedEnvelopeIds.length > 0) await flush(options, signal, new Set(persistedEnvelopeIds));
+				if (received.kind === "intent") {
+					await this.acknowledgeRelayDelivery(delivery.cursor, signal);
+					continue;
+				}
+				visibleDeliveries.push(delivery);
+			}
+			return visibleDeliveries;
+		},
+		async acknowledgeRelayDelivery(cursor, signal) {
+			if (!decimal(cursor)) throw new TaskProtocolError("INVALID_CURSOR", "relay cursor must be a non-negative integer");
+			await options.relay.acknowledgeDelivery({ endpoint: options.endpoint, cursor }, signal);
+			options.store.transaction(() => { options.store.setReceiveCursor(cursor); });
+		},
+		async submitIntent(input, signal) {
+			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;
+			options.store.transaction(() => {
+				const task = requiredTask(options.store, input.taskId);
+				receiverTerminal = !sameEndpoint(options.endpoint, task.origin) && TERMINAL_EVENTS.has(input.type);
+				persistedEnvelopeIds = persistIntent(options, clock.now, ids, task, input);
+			});
+			await flush(options, signal, new Set(persistedEnvelopeIds));
+			if (receiverTerminal) throwIfTerminalDeliveryBlocked(options.store, input.taskId);
+		},
+		async recordInsertion(input, signal) {
+			const task = requiredTask(options.store, input.taskId);
+			let persistedEnvelopeIds: readonly string[] = [];
+			options.store.transaction(() => {
+				if (options.store.putInsertionReceipt(input.taskId, input.eventId)) {
+					persistedEnvelopeIds = persistIntent(options, clock.now, ids, task, { taskId: input.taskId, type: "task.delivery_receipt", payload: { eventId: input.eventId } });
+				}
+			});
+			if (persistedEnvelopeIds.length > 0) await flush(options, signal, new Set(persistedEnvelopeIds));
+		},
+		async evaluateTimeouts(signal) {
+			const persistedEnvelopeIds: string[] = [];
+			for (const candidate of options.store.listTasks()) {
+				if (!sameEndpoint(candidate.origin, options.endpoint) || TERMINAL_STATUSES.has(candidate.status) || candidate.expiresAt > clock.now()) continue;
+				options.store.transaction(() => {
+					const task = options.store.getTask(candidate.taskId);
+					if (!task || !sameEndpoint(task.origin, options.endpoint) || TERMINAL_STATUSES.has(task.status) || task.expiresAt > clock.now()) return;
+					persistedEnvelopeIds.push(...canonicalize(options, clock.now, ids, task, { intentId: ids(), taskId: task.taskId, type: "task.cancelled", payload: {} }, "task.timed_out"));
+				});
+			}
+			if (persistedEnvelopeIds.length > 0) await flush(options, signal, new Set(persistedEnvelopeIds));
+		},
+		async acknowledgeParent(taskId, signal) {
+			let persistedEnvelopeIds: readonly string[] = [];
+			options.store.transaction(() => {
+				const task = requiredTask(options.store, taskId);
+				if (!sameEndpoint(task.origin, options.endpoint)) throw new TaskProtocolError("NOT_ORIGIN", "only origin may acknowledge a task");
+				if (!TERMINAL_STATUSES.has(task.status)) throw new TaskProtocolError("TASK_NOT_TERMINAL", "only a terminal task may be acknowledged", { retryable: false });
+				persistedEnvelopeIds = canonicalize(options, clock.now, ids, task, { intentId: ids(), taskId, type: "task.information", payload: {} }, "task.parent_acknowledged", PARENT_ACKNOWLEDGMENT_OPERATION);
+			});
+			await flush(options, signal, new Set(persistedEnvelopeIds));
+		},
+	};
+}
+
+function validateReceivedEnvelope(options: TaskCoreOptions, relayEnvelope: unknown): ReceivedEnvelope {
+	if (!isEnvelope(relayEnvelope)) throw new TaskProtocolError("INVALID_ENVELOPE", "relay envelope is malformed");
+	if (relayEnvelope.protocolVersion !== TASK_PROTOCOL_VERSION) throw new TaskProtocolError("INCOMPATIBLE_PROTOCOL", "received an incompatible task envelope");
+	if (!sameEndpoint(relayEnvelope.target, options.endpoint)) throw new TaskProtocolError("INVALID_TARGET", "relay envelope targets another endpoint");
+	const payload = parsePayload(relayEnvelope);
+	if (relayEnvelope.kind === TaskEnvelopeKind.assignment) return validateAssignment(relayEnvelope, payload);
+	if (relayEnvelope.kind === TaskEnvelopeKind.intent) return validateIntent(options, relayEnvelope, payload);
+	return validateCanonicalEvent(options, relayEnvelope, payload);
+}
+
+function validateAssignment(envelope: RelayEnvelope, payload: unknown): ReceivedEnvelope {
+	if (!isRecord(payload) || !isTaskRecordInput(payload.task) || !isTaskEvent(payload.event)) throw new TaskProtocolError("INVALID_ASSIGNMENT", "assignment payload is malformed");
+	const task = payload.task;
+	const created = payload.event;
+	if (envelope.taskId !== task.taskId || envelope.taskId !== created.taskId || task.protocolVersion !== TASK_PROTOCOL_VERSION
+		|| task.status !== "active" || task.expiresAt < task.createdAt || created.type !== "task.created" || created.sequence !== "1" || created.payload.task !== task.task
+		|| !sameEndpoint(envelope.source, task.origin) || !sameEndpoint(envelope.target, task.target)
+		|| !sameEndpoint(created.source, task.origin) || !sameEndpoint(created.target, task.target)) {
+		throw new TaskProtocolError("INVALID_ASSIGNMENT", "assignment envelope headers do not match its payload");
+	}
+	return { kind: "assignment", task, event: created };
+}
+
+function validateIntent(options: TaskCoreOptions, envelope: RelayEnvelope, payload: unknown): ReceivedEnvelope {
+	const task = requiredTask(options.store, envelope.taskId);
+	if (!sameEndpoint(task.origin, options.endpoint) || !sameEndpoint(envelope.source, task.target) || !sameEndpoint(envelope.target, task.origin)) {
+		throw new TaskProtocolError("UNAUTHORIZED_INTENT", "only the assigned receiver may submit an intent to origin");
+	}
+	if (!isTaskIntent(payload) || payload.taskId !== envelope.taskId || !RECEIVER_INTENT_TYPES.has(payload.type)) {
+		throw new TaskProtocolError("INVALID_INTENT", "intent envelope headers or payload are invalid");
+	}
+	return { kind: "intent", task, intent: payload };
+}
+
+function validateCanonicalEvent(options: TaskCoreOptions, envelope: RelayEnvelope, payload: unknown): ReceivedEnvelope {
+	const task = requiredTask(options.store, envelope.taskId);
+	if (!isTaskEvent(payload) || !CANONICAL_EVENTS.has(payload.type) || payload.taskId !== envelope.taskId
+		|| !sameEndpoint(envelope.source, task.origin) || (!sameEndpoint(envelope.target, task.target) && !sameEndpoint(envelope.target, task.origin))
+		|| !sameEndpoint(payload.source, task.origin) || !sameEndpoint(payload.target, task.target)) {
+		throw new TaskProtocolError("INVALID_EVENT", "canonical event envelope headers or payload are invalid");
+	}
+	if (!sameEndpoint(envelope.target, options.endpoint)) throw new TaskProtocolError("INVALID_TARGET", "canonical event targets another endpoint");
+	return { kind: "canonical_event", task, event: payload };
+}
+
+function persistReceivedEnvelope(options: TaskCoreOptions, now: () => number, ids: () => string, received: ReceivedEnvelope): readonly string[] {
+	if (received.kind === "assignment") {
+		options.store.putTask(received.task);
+		options.store.appendEvent(received.event);
+		return [];
+	}
+	if (received.kind === "intent") return canonicalize(options, now, ids, received.task, received.intent, received.intent.type);
+	if (options.store.appendEvent(received.event) && TERMINAL_EVENTS.has(received.event.type)) options.store.setStatus(received.task.taskId, statusFor(received.event.type));
+	return [];
+}
+
+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 envelopeId = ids();
+	const intent: TaskIntent = { intentId: ids(), taskId: input.taskId, type: input.type, payload: input.payload };
+	if (TERMINAL_EVENTS.has(input.type)) {
+		const reservation = options.store.reserveTaskOperation({
+			taskId: input.taskId,
+			operation: TERMINAL_INTENT_OPERATION,
+			logicalId: intent.intentId,
+			logicalType: intent.type,
+			envelopeIds: [envelopeId],
+		});
+		if (!reservation.created) {
+			if (reservation.record.logicalType !== intent.type) {
+				throw new TaskProtocolError("TERMINAL_INTENT_CONFLICT", "terminal task intent conflicts with the existing terminal action", {
+					retryable: false,
+					details: { taskId: input.taskId, existingType: reservation.record.logicalType, requestedType: intent.type },
+				});
+			}
+			return reservation.record.envelopeIds;
+		}
+	}
+	options.store.putIntent(intent.intentId, input.taskId, envelopeId);
+	options.store.putOutbox(envelope(envelopeId, options.endpoint, task.origin, input.taskId, TaskEnvelopeKind.intent, intent));
+	return [envelopeId];
+}
+
+function canonicalize(options: TaskCoreOptions, now: () => number, ids: () => string, task: TaskRecord, intent: TaskIntent, requestedType: string, operation?: string): readonly string[] {
+	const terminal = TERMINAL_EVENTS.has(requestedType);
+	const type = terminal && TERMINAL_STATUSES.has(task.status) ? "task.late_terminal" : requestedType;
+	const sequence = String(task.events.length + 1);
+	const canonical = event(task, ids(), type, sequence, options.endpoint, task.target, now(), { intentId: intent.intentId, ...intent.payload });
+	const targetEnvelope = envelope(ids(), options.endpoint, task.target, task.taskId, TaskEnvelopeKind.canonicalEvent, canonical);
+	const originEnvelope = sameEndpoint(task.origin, task.target) ? undefined : envelope(ids(), options.endpoint, task.origin, task.taskId, TaskEnvelopeKind.canonicalEvent, canonical);
+	const persistedEnvelopeIds = originEnvelope === undefined ? [targetEnvelope.envelopeId] : [targetEnvelope.envelopeId, originEnvelope.envelopeId];
+	if (operation !== undefined) {
+		const reservation = options.store.reserveTaskOperation({ taskId: task.taskId, operation, logicalId: canonical.eventId, logicalType: canonical.type, envelopeIds: persistedEnvelopeIds });
+		if (!reservation.created) return reservation.record.envelopeIds;
+	}
+	options.store.appendEvent(canonical);
+	if (TERMINAL_EVENTS.has(type)) options.store.setStatus(task.taskId, statusFor(type));
+	options.store.putOutbox(targetEnvelope);
+	if (originEnvelope !== undefined) options.store.putOutbox(originEnvelope);
+	return persistedEnvelopeIds;
+}
+
+async function flush(options: TaskCoreOptions, signal: AbortSignal | undefined, reportedEnvelopeIds?: ReadonlySet<string>): Promise<void> {
+	const failures: Array<{ readonly envelopeId: string; readonly error: unknown }> = [];
+	for (const record of options.store.outbox("pending")) {
+		try {
+			await options.relay.send(record.envelope, signal);
+			options.store.transaction(() => { options.store.markOutboxAccepted(record.envelope.envelopeId); });
+		} catch (error) {
+			if (signal?.aborted || (error instanceof TaskProtocolError && error.code === "ABORTED")) throw error;
+			if (error instanceof TaskProtocolError && error.code === TARGET_NOT_REGISTERED_CODE && !error.retryable) {
+				options.store.transaction(() => {
+					options.store.quarantineOutbox(record.envelope.envelopeId, {
+						errorCode: error.code,
+						reason: error.message,
+						details: error.details ?? {},
+						quarantinedAt: Date.now(),
+					});
+				});
+			}
+			failures.push({ envelopeId: record.envelope.envelopeId, error });
+		}
+	}
+	const reportedFailure = failures.find((failure) => reportedEnvelopeIds === undefined || reportedEnvelopeIds.has(failure.envelopeId));
+	if (reportedFailure) throw outboxDeliveryError(reportedFailure.error);
+}
+
+function outboxDeliveryError(error: unknown): TaskOutboxDeliveryError {
+	if (error instanceof TaskProtocolError) {
+		return new TaskOutboxDeliveryError(error.code, error.message, { retryable: error.retryable, details: error.details });
+	}
+	return new TaskOutboxDeliveryError("TASK_ERROR", error instanceof Error ? error.message : "task delivery failed");
+}
+
+function operationError(error: unknown, taskId: string): TaskProtocolError {
+	if (error instanceof TaskProtocolError) {
+		return new TaskProtocolError(error.code, error.message, { retryable: error.retryable, details: { ...error.details, taskId } });
+	}
+	return new TaskProtocolError("TASK_ERROR", error instanceof Error ? error.message : "task operation failed", { details: { taskId } });
+}
+
+function event(task: Omit<TaskRecord, "events">, eventId: string, type: string, sequence: string, source: TaskEndpoint, target: TaskEndpoint, occurredAt: number, payload: Record<string, unknown>): TaskEvent {
+	return { eventId, taskId: task.taskId, type, sequence, source, target, occurredAt, payload };
+}
+
+function envelope(envelopeId: string, source: TaskEndpoint, target: TaskEndpoint, taskId: string, kind: RelayEnvelope["kind"], payload: unknown): RelayEnvelope {
+	return { envelopeId, protocolVersion: TASK_PROTOCOL_VERSION, source, target, taskId, kind, payload: JSON.stringify(payload) };
+}
+
+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 throwIfTerminalDeliveryBlocked(store: TaskStore, taskId: string): void {
+	const delivery = requiredTask(store, taskId).terminalDelivery;
+	if (delivery.state !== "delivery_blocked") return;
+	throw new TaskOutboxDeliveryError(delivery.error.code, "terminal task delivery is blocked", {
+		retryable: false,
+		details: { ...delivery.error.details, taskId, envelopeId: delivery.envelopeId, origin: delivery.origin, blockedAt: delivery.blockedAt },
+	});
+}
+
+function requiredTask(store: TaskStore, taskId: string): TaskSnapshot {
+	const task = store.getTask(taskId);
+	if (!task) throw new TaskProtocolError("UNKNOWN_TASK", `unknown task: ${taskId}`);
+	return task;
+}
+
+function statusFor(type: string): TaskRecord["status"] {
+	if (type === "task.completed") return "completed";
+	if (type === "task.failed") return "failed";
+	if (type === "task.cancelled") return "cancelled";
+	return "timed_out";
+}
+
+function isInboxPage(value: unknown): value is { readonly deliveries: readonly RelayDelivery[]; readonly nextCursor: string; readonly hasMore: boolean } {
+	return isRecord(value) && Array.isArray(value.deliveries) && decimal(value.nextCursor) && typeof value.hasMore === "boolean";
+}
+
+function isDelivery(value: unknown): value is RelayDelivery {
+	return isRecord(value) && decimal(value.cursor) && isEnvelope(value.envelope);
+}
+
+function isEnvelope(value: unknown): value is RelayEnvelope {
+	return isRecord(value) && nonEmpty(value.envelopeId) && value.protocolVersion === TASK_PROTOCOL_VERSION && nonEmpty(value.taskId)
+		&& isEndpoint(value.source) && isEndpoint(value.target) && isEnvelopeKind(value.kind)
+		&& typeof value.payload === "string" && new TextEncoder().encode(value.payload).byteLength <= MAX_RELAY_PAYLOAD_BYTES;
+}
+
+function isTaskRecordInput(value: unknown): value is Omit<TaskRecord, "events"> {
+	return isRecord(value) && nonEmpty(value.taskId) && value.protocolVersion === TASK_PROTOCOL_VERSION && isEndpoint(value.origin) && isEndpoint(value.target)
+		&& nonEmpty(value.task) && finiteNumber(value.createdAt) && finiteNumber(value.expiresAt) && isTaskStatus(value.status);
+}
+
+function isTaskEvent(value: unknown): value is TaskEvent {
+	return isRecord(value) && nonEmpty(value.eventId) && nonEmpty(value.taskId) && nonEmpty(value.type) && positiveDecimal(value.sequence)
+		&& isEndpoint(value.source) && isEndpoint(value.target) && finiteNumber(value.occurredAt) && isRecord(value.payload);
+}
+
+function isTaskIntent(value: unknown): value is TaskIntent {
+	return isRecord(value) && nonEmpty(value.intentId) && nonEmpty(value.taskId) && typeof value.type === "string" && isRecord(value.payload);
+}
+
+function isEndpoint(value: unknown): value is TaskEndpoint {
+	return isRecord(value) && nonEmpty(value.relay) && nonEmpty(value.id);
+}
+
+function isEnvelopeKind(value: unknown): value is RelayEnvelope["kind"] {
+	return value === TaskEnvelopeKind.assignment || value === TaskEnvelopeKind.intent || value === TaskEnvelopeKind.canonicalEvent;
+}
+
+function isTaskStatus(value: unknown): value is TaskRecord["status"] {
+	return value === "active" || value === "completed" || value === "failed" || value === "cancelled" || value === "timed_out";
+}
+
+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 nonEmpty(value: unknown): value is string {
+	return typeof value === "string" && value.length > 0;
+}
+
+function finiteNumber(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value);
+}
+
+function decimal(value: unknown): value is string {
+	return typeof value === "string" && /^(0|[1-9][0-9]*)$/.test(value);
+}
+
+function positiveDecimal(value: unknown): value is string {
+	return typeof value === "string" && /^[1-9][0-9]*$/.test(value);
+}
+
+function throwIfAborted(signal: AbortSignal | undefined): void {
+	if (signal?.aborted) throw new TaskProtocolError("ABORTED", "task relay connection was cancelled");
+}

package/src/task-inbox.ts

@@ -1,78 +1,60 @@
-import type { TaskAssignment, TaskEvent, TaskStatus, WolfpackGatewayClient } from "./gateway-client";
+import type { TaskCore } from "./task-core";
+import { TaskEnvelopeKind, TaskProtocolError } from "./task-protocol";
+import type { RelayDelivery, TaskEvent } from "./task-protocol";
 
-const TASK_EVENT_CUSTOM_TYPE = "wolfpack-task-event";
-const TASK_CURSOR_CUSTOM_TYPE = "wolfpack-task-cursor";
+const TASK_EVENT_CUSTOM_TYPE = "pi-tasks-event";
+const TASK_CURSOR_CUSTOM_TYPE = "pi-tasks-relay-cursor";
 
 interface InboxContext {
-	readonly isIdle: () => boolean;
 	readonly hasPendingMessages: () => boolean;
-	readonly sessionManager: { readonly buildContextEntries: () => readonly unknown[] };
+	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: true }): void;
+	sendMessage(message: { readonly customType: string; readonly content: string; readonly display: boolean; readonly details: TaskEventDetails }, options: { readonly triggerTurn: true; readonly deliverAs: "followUp" }): void;
 	appendEntry(customType: string, data: { readonly cursor: string }): void;
 }
 
-interface TaskEventDetails {
+export interface TaskEventDetails {
 	readonly taskId: string;
 	readonly eventId: string;
 }
 
-interface InboxClient {
-	inbox(cursor: string, includeAcknowledged: boolean): Promise<{ readonly events: readonly TaskEvent[]; readonly nextCursor: string; readonly hasMore: boolean }>;
-	status(taskId: string): Promise<TaskStatus>;
-	delivered(taskId: string, eventId: string): Promise<unknown>;
-}
-
-export async function deliverTaskInbox(pi: InboxPi, client: InboxClient, ctx: InboxContext, initialCursor: string): Promise<string> {
-	if (!ctx.isIdle() || ctx.hasPendingMessages()) return initialCursor;
-	const entries = ctx.sessionManager.buildContextEntries();
-	const incorporated = incorporatedEvents(entries);
-	const includeAcknowledged = initialCursor === "0" && !hasPersistedCursor(entries);
-	let cursor = initialCursor;
-	for (;;) {
-		const page = await client.inbox(cursor, includeAcknowledged);
-		for (const event of page.events) {
-			if (!modelRelevant(event)) continue;
-			if (!ctx.isIdle() || ctx.hasPendingMessages()) return cursor;
-			const eventKey = key(event.taskId, event.id);
-			const snapshot = await client.status(event.taskId);
-			if (!ctx.isIdle() || ctx.hasPendingMessages()) return cursor;
-			if (incorporated.has(eventKey)) {
-				if (event.destination.sessionId === snapshot.task.target.sessionId) await client.delivered(event.taskId, event.id);
-				continue;
+/** Inserts durable Pi evidence before allowing the relay mailbox cursor to advance. */
+export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: InboxContext, pendingInsertions: Set<string>, signal?: AbortSignal): Promise<void> {
+	if (context.hasPendingMessages()) return;
+	const deliveries = await core.receive(signal);
+	for (const delivery of deliveries) {
+		if (delivery.envelope.kind === TaskEnvelopeKind.intent) {
+			await core.acknowledgeRelayDelivery(delivery.cursor, signal);
+			pi.appendEntry(TASK_CURSOR_CUSTOM_TYPE, { cursor: delivery.cursor });
+			continue;
+		}
+		const event = inboxEvent(delivery);
+		if (!isKnownEvent(event.type)) throw new TaskProtocolError("UNKNOWN_EVENT", `unknown task inbox event type: ${event.type}`);
+		if (context.hasPendingMessages()) return;
+		const eventKey = key(event.taskId, event.eventId);
+		const incorporated = incorporatedEvents(context.sessionManager.getEntries()).has(eventKey);
+		if (incorporated) pendingInsertions.delete(eventKey);
+		if (!incorporated && isModelVisible(event.type)) {
+			if (!pendingInsertions.has(eventKey)) {
+				pi.sendMessage({
+					customType: TASK_EVENT_CUSTOM_TYPE,
+					content: renderTaskEvent(event),
+					display: true,
+					details: { taskId: event.taskId, eventId: event.eventId },
+				}, { triggerTurn: true, deliverAs: "followUp" });
+				pendingInsertions.add(eventKey);
 			}
-			if (terminalHistoryAcknowledged(snapshot)) continue;
-			pi.sendMessage({
-				customType: TASK_EVENT_CUSTOM_TYPE,
-				content: renderTaskEvent(event, snapshot),
-				display: true,
-				details: { taskId: event.taskId, eventId: event.id },
-			}, { triggerTurn: true });
-			if (!incorporatedEvents(ctx.sessionManager.buildContextEntries()).has(eventKey)) return cursor;
-			incorporated.add(eventKey);
-			if (event.destination.sessionId === snapshot.task.target.sessionId) await client.delivered(event.taskId, event.id);
+			if (!incorporatedEvents(context.sessionManager.getEntries()).has(eventKey)) return;
+			pendingInsertions.delete(eventKey);
 		}
-		// Inbox cursors are machine-local delivery sequences, never task event sequences.
-		cursor = page.nextCursor;
-		pi.appendEntry(TASK_CURSOR_CUSTOM_TYPE, { cursor });
-		if (!page.hasMore) return cursor;
+		if (isModelVisible(event.type)) await core.recordInsertion({ taskId: event.taskId, eventId: event.eventId }, signal);
+		await core.acknowledgeRelayDelivery(delivery.cursor, signal);
+		pi.appendEntry(TASK_CURSOR_CUSTOM_TYPE, { cursor: delivery.cursor });
 	}
 }
 
-function hasPersistedCursor(entries: readonly unknown[]): boolean {
-	return entries.some((entry) => isRecord(entry) && entry.type === "custom" && entry.customType === TASK_CURSOR_CUSTOM_TYPE && isRecord(entry.data) && decimal(entry.data.cursor));
-}
-
-function modelRelevant(event: TaskEvent): boolean {
-	return event.type === "task.created" || event.type === "task.question" || event.type === "task.answer" || event.type === "task.information" || terminalEvent(event.type) || event.type === "task.cancel_requested";
-}
-
-function terminalHistoryAcknowledged(snapshot: TaskStatus): boolean {
-	return ["completed", "failed", "cancelled", "timed_out"].includes(snapshot.status) && snapshot.events.some((event) => event.type === "task.parent_acknowledged");
-}
-
 export function restoredInboxCursor(entries: readonly unknown[]): string {
 	let cursor = "0";
 	for (const entry of entries) {
@@ -82,46 +64,46 @@ export function restoredInboxCursor(entries: readonly unknown[]): string {
 	return cursor;
 }
 
-export function incorporatedEvents(entries: readonly unknown[]): Set<string> {
-	const events = new Set<string>();
-	for (const entry of entries) {
-		if (!isRecord(entry) || entry.type !== "custom_message" || entry.customType !== TASK_EVENT_CUSTOM_TYPE || !isRecord(entry.details) || !nonEmpty(entry.details.taskId) || !nonEmpty(entry.details.eventId)) continue;
-		events.add(key(entry.details.taskId, entry.details.eventId));
-	}
-	return events;
+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");
 }
 
-export function renderTaskEvent(event: TaskEvent, snapshot: TaskStatus): string {
-	const header = `task: \`${event.taskId}\` · event: \`${event.id}\``;
-	if (event.type === "task.created") return renderAssignment(header, snapshot.task, snapshot.warnings);
-	const message = event.message ? `\n\n${event.message}` : "";
-	const completion = event.completion ?? snapshot.completion;
-	const completionText = completion ? `\n\n**summary:** ${completion.summary}` : "";
-	const parentPrompt = terminalEvent(event.type) && snapshot.task.onCompletePrompt
-		? `\n\n## parent follow-up\n${snapshot.task.onCompletePrompt}`
-		: "";
-	const warnings = renderWarnings(snapshot.warnings);
-	return `## task ${label(event.type)}\n${header}${message}${completionText}${parentPrompt}${warnings}`;
+function isKnownEvent(type: string): boolean {
+	return ["task.created", "task.completed", "task.failed", "task.cancelled", "task.timed_out", "task.information", "task.question", "task.answer", "task.delivery_receipt", "task.parent_acknowledged", "task.late_terminal"].includes(type);
 }
 
-function renderAssignment(header: string, assignment: TaskAssignment, warnings: readonly { readonly code: string; readonly message: string }[]): string {
-	const context = assignment.context?.summary ? `\n\n## context\n${assignment.context.summary}` : "";
-	const refs = assignment.context?.refs?.length
-		? `\n\n## selected refs\n${assignment.context.refs.map((ref) => `- \`${ref.path}\`${ref.selector ? ` — ${ref.selector}` : ""}${ref.purpose ? ` — ${ref.purpose}` : ""}`).join("\n")}`
-		: "";
-	return `## task assignment\n${header}\n\n${assignment.task}${context}${refs}${renderWarnings(warnings)}`;
+function isModelVisible(type: string): boolean {
+	return !["task.delivery_receipt", "task.parent_acknowledged", "task.late_terminal"].includes(type);
 }
 
-function renderWarnings(warnings: readonly { readonly code: string; readonly message: string }[]): string {
-	return warnings.length === 0 ? "" : `\n\n## gateway warnings\n${warnings.map((warning) => `- ${warning.code}: ${warning.message}`).join("\n")}`;
+function renderTaskEvent(event: TaskEvent): string {
+	if (event.type === "task.created") return `## task assignment\ntask: \`${event.taskId}\` · event: \`${event.eventId}\`\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}`;
 }
 
-function label(type: string): string {
-	return type.replace(/^task\./, "").replaceAll("_", " ");
+export function incorporatedTaskEvents(entries: readonly unknown[]): readonly TaskEventDetails[] {
+	const events: TaskEventDetails[] = [];
+	for (const entry of entries) {
+		if (!isRecord(entry) || entry.type !== "custom_message" || entry.customType !== TASK_EVENT_CUSTOM_TYPE || !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;
 }
 
-function terminalEvent(type: string): boolean {
-	return type === "task.completed" || type === "task.failed" || type === "task.cancelled" || type === "task.timed_out";
+function incorporatedEvents(entries: readonly unknown[]): Set<string> {
+	return new Set(incorporatedTaskEvents(entries).map((event) => key(event.taskId, event.eventId)));
+}
+
+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 {
@@ -132,10 +114,6 @@ function isRecord(value: unknown): value is Record<string, unknown> {
 	return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-function nonEmpty(value: unknown): value is string {
-	return typeof value === "string" && value.length > 0;
-}
-
 function decimal(value: unknown): value is string {
 	return typeof value === "string" && /^(0|[1-9][0-9]*)$/.test(value);
 }