@sgtbeatdown/pi-tasks 0.1.0 → 0.1.2

package/src/task-core.ts

@@ -0,0 +1,383 @@
+import {
+	MAX_RELAY_PAYLOAD_BYTES,
+	TASK_PROTOCOL_VERSION,
+	TaskEnvelopeKind,
+	TaskOutboxDeliveryError,
+	TaskProtocolError,
+} from "./task-protocol";
+import type {
+	RelayDelivery,
+	RelayEnvelope,
+	TaskEndpoint,
+	TaskEvent,
+	TaskIntent,
+	TaskRecord,
+	TaskRelay,
+} from "./task-protocol";
+import type { TaskStore } from "./task-store";
+
+const RECEIVE_PAGE_SIZE = 100;
+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 {
+	connect(signal?: AbortSignal): Promise<void>;
+	createTask(input: CreateTaskInput, signal?: AbortSignal): Promise<{ readonly taskId: string }>;
+	getTask(taskId: string): TaskRecord | undefined;
+	listTasks(): readonly TaskRecord[];
+	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 {
+		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");
+			const task = requiredTask(options.store, input.taskId);
+			let persistedEnvelopeIds: readonly string[] = [];
+			options.store.transaction(() => {
+				persistedEnvelopeIds = persistIntent(options, clock.now, ids, task, input);
+			});
+			await flush(options, signal, new Set(persistedEnvelopeIds));
+		},
+		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) {
+			const task = requiredTask(options.store, taskId);
+			if (!sameEndpoint(task.origin, options.endpoint)) throw new TaskProtocolError("NOT_ORIGIN", "only origin may acknowledge a task");
+			let persistedEnvelopeIds: readonly string[] = [];
+			options.store.transaction(() => {
+				persistedEnvelopeIds = canonicalize(options, clock.now, ids, task, { intentId: ids(), taskId, type: "task.information", payload: {} }, "task.parent_acknowledged");
+			});
+			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 };
+	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): 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 persistedEnvelopeIds: string[] = [];
+	options.store.appendEvent(canonical);
+	if (TERMINAL_EVENTS.has(type)) options.store.setStatus(task.taskId, statusFor(type));
+	const targetEnvelope = envelope(ids(), options.endpoint, task.target, task.taskId, TaskEnvelopeKind.canonicalEvent, canonical);
+	options.store.putOutbox(targetEnvelope);
+	persistedEnvelopeIds.push(targetEnvelope.envelopeId);
+	if (!sameEndpoint(task.origin, task.target)) {
+		const originEnvelope = envelope(ids(), options.endpoint, task.origin, task.taskId, TaskEnvelopeKind.canonicalEvent, canonical);
+		options.store.putOutbox(originEnvelope);
+		persistedEnvelopeIds.push(originEnvelope.envelopeId);
+	}
+	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;
+			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 requiredTask(store: TaskStore, taskId: string): TaskRecord {
+	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

@@ -0,0 +1,109 @@
+import type { TaskCore } from "./task-core";
+import { TaskEnvelopeKind, TaskProtocolError } from "./task-protocol";
+import type { RelayDelivery, TaskEvent } from "./task-protocol";
+
+const TASK_EVENT_CUSTOM_TYPE = "pi-tasks-event";
+const TASK_CURSOR_CUSTOM_TYPE = "pi-tasks-relay-cursor";
+
+interface InboxContext {
+	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: true; readonly deliverAs: "followUp" }): void;
+	appendEntry(customType: string, data: { readonly cursor: string }): void;
+}
+
+interface TaskEventDetails {
+	readonly taskId: string;
+	readonly eventId: string;
+}
+
+/** Inserts durable Pi evidence before allowing the relay mailbox cursor to advance. */
+export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: InboxContext, 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);
+		if (!incorporatedEvents(context.sessionManager.getEntries()).has(eventKey) && isModelVisible(event.type)) {
+			pi.sendMessage({
+				customType: TASK_EVENT_CUSTOM_TYPE,
+				content: renderTaskEvent(event),
+				display: true,
+				details: { taskId: event.taskId, eventId: event.eventId },
+			}, { triggerTurn: true, deliverAs: "followUp" });
+			if (!incorporatedEvents(context.sessionManager.getEntries()).has(eventKey)) return;
+		}
+		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 });
+	}
+}
+
+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;
+		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");
+}
+
+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 isModelVisible(type: string): boolean {
+	return !["task.delivery_receipt", "task.parent_acknowledged", "task.late_terminal"].includes(type);
+}
+
+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 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) || typeof entry.details.taskId !== "string" || typeof entry.details.eventId !== "string") continue;
+		events.add(key(entry.details.taskId, entry.details.eventId));
+	}
+	return 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);
+}
+
+function decimal(value: unknown): value is string {
+	return typeof value === "string" && /^(0|[1-9][0-9]*)$/.test(value);
+}

package/src/task-protocol.ts

@@ -0,0 +1,129 @@
+export const TASK_PROTOCOL_VERSION = "pi-tasks/v2" as const;
+export const MAX_RELAY_PAYLOAD_BYTES = 48 * 1024;
+
+export interface TaskEndpoint {
+	readonly relay: string;
+	readonly id: string;
+}
+
+/** 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;
+	/** 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;
+}
+
+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>;
+	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 interface TaskIntent {
+	readonly intentId: string;
+	readonly taskId: string;
+	readonly type: "task.completed" | "task.failed" | "task.cancelled" | "task.information" | "task.question" | "task.answer" | "task.delivery_receipt";
+	readonly payload: Record<string, unknown>;
+}
+
+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";
+	}
+}

package/src/task-relay-conformance.ts

@@ -0,0 +1,23 @@
+import { expect, test } from "bun:test";
+
+import { TASK_PROTOCOL_VERSION } from "./task-protocol";
+import type { TaskRelay } from "./task-protocol";
+
+/** Shared assertions external relay adapters can run against their implementation. */
+export function runTaskRelayConformance(createRelay: () => TaskRelay): void {
+	test("enforces registration, accepts duplicate envelopes once, and retains delivery until acknowledgement", async () => {
+		const relay = createRelay();
+		const source = { relay: relay.id, id: "source" };
+		const target = { relay: relay.id, id: "target" };
+		await relay.connect({ endpoint: source, protocolVersion: TASK_PROTOCOL_VERSION, receiveCursor: "0" });
+		await relay.connect({ endpoint: target, protocolVersion: TASK_PROTOCOL_VERSION, receiveCursor: "0" });
+		await expect(relay.resolve({ relay: relay.id, reference: "missing" })).rejects.toThrow("not registered");
+		const envelope = { envelopeId: "envelope-1", protocolVersion: TASK_PROTOCOL_VERSION, source, target, taskId: "task-1", kind: "assignment" as const, payload: "{}" };
+		await relay.send(envelope);
+		await relay.send(envelope);
+		const page = await relay.receive({ endpoint: target, cursor: "0", limit: 10 });
+		expect(page.deliveries).toHaveLength(1);
+		await relay.acknowledgeDelivery({ endpoint: target, cursor: page.nextCursor });
+		expect((await relay.receive({ endpoint: target, cursor: page.nextCursor, limit: 10 })).deliveries).toHaveLength(0);
+	});
+}