@sgtbeatdown/pi-tasks 0.1.8 → 0.1.10

package/src/task-core.ts

@@ -1,5 +1,6 @@
 import {
 	MAX_RELAY_PAYLOAD_BYTES,
+	INVALID_RELAY_METADATA,
 	ORIGIN_CANCELLATION_OPERATION,
 	PARENT_ACKNOWLEDGMENT_OPERATION,
 	TASK_PROTOCOL_VERSION,
@@ -24,7 +25,7 @@ import type { TaskStore } from "./task-store";
 
 const RECEIVE_PAGE_SIZE = 100;
 const DELIVERY_EVIDENCE_OPERATION = "delivery_evidence";
-const TARGET_NOT_REGISTERED_CODE = "TARGET_NOT_REGISTERED";
+const TERMINAL_DELIVERY_CODES = new Set(["TARGET_NOT_REGISTERED", INVALID_RELAY_METADATA, "DELIVERY_UNCONFIRMED", "ENVELOPE_EXPIRED", "ENVELOPE_CONFLICT", "CROSS_RELAY_ENDPOINT"]);
 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([
@@ -84,6 +85,19 @@ type ReceivedEnvelope =
 export function createTaskCore(options: TaskCoreOptions): TaskCore {
 	const clock = options.clock ?? { now: (): number => Date.now() };
 	const ids = options.ids ?? (() => crypto.randomUUID());
+	const acknowledgeRelayDelivery = async (cursor: string, signal?: AbortSignal): Promise<void> => {
+		if (!decimal(cursor)) throw new TaskProtocolError("INVALID_CURSOR", "relay cursor must be a non-negative integer");
+		const envelopeId = options.store.pendingRelayEnvelopeId(options.endpoint, cursor);
+		if (envelopeId === undefined) throw new TaskProtocolError("INVALID_CURSOR", "relay delivery is not pending in this endpoint scope");
+		options.store.transaction(() => options.store.requestRelayAcknowledgement(options.endpoint, cursor));
+		await options.relay.acknowledgeDelivery({ endpoint: options.endpoint, cursor, envelopeId }, signal);
+		options.store.transaction(() => options.store.acknowledgeRelayCursor(options.endpoint, cursor));
+	};
+	const retryRequestedAcknowledgements = async (signal?: AbortSignal): Promise<void> => {
+		for (const cursor of options.store.requestedRelayAcknowledgements(options.endpoint)) {
+			if (options.store.pendingRelayEnvelopeId(options.endpoint, cursor) !== undefined) await acknowledgeRelayDelivery(cursor, signal);
+		}
+	};
 	const submitIntentWithOutcome = async (input: SubmitIntentInput, signal?: AbortSignal): Promise<SubmitIntentOutcome> => {
 		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[] = [];
@@ -121,6 +135,7 @@ export function createTaskCore(options: TaskCoreOptions): TaskCore {
 			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);
+			await retryRequestedAcknowledgements(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");
@@ -133,7 +148,7 @@ export function createTaskCore(options: TaskCoreOptions): TaskCore {
 				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 });
+			const assignment = envelope(ids(), options.endpoint, target, taskId, TaskEnvelopeKind.assignment, { task, event: created }, now);
 			options.store.transaction(() => {
 				options.store.putTask(task);
 				options.store.appendEvent(created);
@@ -150,12 +165,23 @@ export function createTaskCore(options: TaskCoreOptions): TaskCore {
 		listTasks() { return options.store.listTasks(); },
 		async flushOutbox(signal) { await flush(options, signal); },
 		async receive(signal) {
+			await retryRequestedAcknowledgements(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);
+			const cursor = options.store.getReceiveCursor();
+			const page = await options.relay.receive({ endpoint: options.endpoint, cursor, limit: RECEIVE_PAGE_SIZE }, signal);
 			if (!isInboxPage(page)) throw new TaskProtocolError("INVALID_INBOX", "relay returned an invalid inbox page");
+			let previous = BigInt(cursor);
+			for (const delivery of page.deliveries) {
+				if (!isDelivery(delivery) || !sameEndpoint(delivery.envelope.target, options.endpoint) || BigInt(delivery.cursor) <= previous) throw new TaskProtocolError("INVALID_DELIVERY", "relay returned an invalid or unordered delivery");
+				previous = BigInt(delivery.cursor);
+			}
+			if (BigInt(page.nextCursor) < previous) throw new TaskProtocolError("INVALID_INBOX", "relay page cursor precedes its deliveries");
+			// Track the entire observed prefix before an intent can ACK a later
+			// delivery. Keep only pending IDs plus a high-water mark, durably.
+			options.store.transaction(() => options.store.trackRelayDeliveries(options.endpoint, page.deliveries.map(delivery => ({ cursor: delivery.cursor, envelopeId: delivery.envelope.envelopeId }))));
 			const visibleDeliveries: RelayDelivery[] = [];
 			for (const delivery of page.deliveries) {
-				if (!isDelivery(delivery)) throw new TaskProtocolError("INVALID_DELIVERY", "relay returned an invalid delivery");
+				if (options.store.pendingRelayEnvelopeId(options.endpoint, delivery.cursor) === undefined) continue;
 				const received = validateReceivedEnvelope(options, delivery.envelope);
 				let persistedEnvelopeIds: readonly string[] = [];
 				options.store.transaction(() => {
@@ -171,11 +197,7 @@ export function createTaskCore(options: TaskCoreOptions): TaskCore {
 			}
 			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); });
-		},
+		acknowledgeRelayDelivery,
 		async submitIntent(input, signal) { await submitIntentWithOutcome(input, signal); },
 		submitIntentWithOutcome,
 		async recordInsertion(input, signal) {
@@ -279,6 +301,7 @@ interface PersistedIntent {
 }
 
 function persistIntent(options: TaskCoreOptions, now: () => number, ids: () => string, task: TaskRecord, input: SubmitIntentInput, reservedOperation?: string): PersistedIntent {
+	if (!sameEndpoint(options.endpoint, task.origin) && !sameEndpoint(options.endpoint, task.target)) throw new TaskProtocolError("NOT_PARTICIPANT", "historical task belongs to a different endpoint", { retryable: false });
 	if (sameEndpoint(options.endpoint, task.origin)) {
 		const operation = input.type === "task.cancelled" ? ORIGIN_CANCELLATION_OPERATION : reservedOperation;
 		const canonical = canonicalize(options, now, ids, task, { intentId: ids(), taskId: input.taskId, type: input.type, payload: input.payload }, input.type, operation);
@@ -306,7 +329,7 @@ function persistIntent(options: TaskCoreOptions, now: () => number, ids: () => s
 		}
 	}
 	options.store.putIntent(intent.intentId, input.taskId, envelopeId);
-	options.store.putOutbox(envelope(envelopeId, options.endpoint, task.origin, input.taskId, TaskEnvelopeKind.intent, intent));
+	options.store.putOutbox(envelope(envelopeId, options.endpoint, task.origin, input.taskId, TaskEnvelopeKind.intent, intent, now()));
 	return { envelopeIds: [envelopeId], outcome: { authority: "receiver" } };
 }
 
@@ -324,7 +347,7 @@ function deliveryEvidence(input: SubmitIntentInput): DeliveryEvidence | undefine
 	if (stage === TaskDeliveryStage.piInsertion && state === TaskDeliveryEvidenceState.blocked && input.payload.retryable === true) {
 		return { eventId: input.payload.eventId, stage, state, retryable: true };
 	}
-	if ((stage === TaskDeliveryStage.receiverPersisted || stage === TaskDeliveryStage.piInserted || stage === TaskDeliveryStage.wakeRequested || stage === TaskDeliveryStage.wakeAccepted)
+	if ((stage === TaskDeliveryStage.receiverRecorded || stage === TaskDeliveryStage.piInserted || stage === TaskDeliveryStage.wakeRequested || stage === TaskDeliveryStage.wakeAccepted)
 		&& state === TaskDeliveryEvidenceState.confirmed) {
 		return { eventId: input.payload.eventId, stage, state };
 	}
@@ -346,8 +369,8 @@ function canonicalize(options: TaskCoreOptions, now: () => number, ids: () => st
 	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 targetEnvelope = envelope(ids(), options.endpoint, task.target, task.taskId, TaskEnvelopeKind.canonicalEvent, canonical, canonical.occurredAt);
+	const originEnvelope = sameEndpoint(task.origin, task.target) ? undefined : envelope(ids(), options.endpoint, task.origin, task.taskId, TaskEnvelopeKind.canonicalEvent, canonical, canonical.occurredAt);
 	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 });
@@ -378,7 +401,7 @@ async function flush(options: TaskCoreOptions, signal: AbortSignal | undefined,
 			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) {
+			if (error instanceof TaskProtocolError && TERMINAL_DELIVERY_CODES.has(error.code) && !error.retryable) {
 				options.store.transaction(() => {
 					options.store.quarantineOutbox(record.envelope.envelopeId, {
 						errorCode: error.code,
@@ -413,8 +436,8 @@ function event(task: Omit<TaskRecord, "events">, eventId: string, type: string,
 	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 envelope(envelopeId: string, source: TaskEndpoint, target: TaskEndpoint, taskId: string, kind: RelayEnvelope["kind"], payload: unknown, createdAt: number): RelayEnvelope {
+	return { envelopeId, protocolVersion: TASK_PROTOCOL_VERSION, source, target, taskId, kind, payload: JSON.stringify(payload), createdAt: new Date(createdAt).toISOString() };
 }
 
 function parsePayload(envelope: RelayEnvelope): unknown {
@@ -460,7 +483,7 @@ function throwIfTerminalDeliveryBlocked(store: TaskStore, taskId: string): void
 
 function requiredTask(store: TaskStore, taskId: string): TaskSnapshot {
 	const task = store.getTask(taskId);
-	if (!task) throw new TaskProtocolError("UNKNOWN_TASK", `unknown task: ${taskId}`);
+	if (!task) throw new TaskProtocolError("UNKNOWN_TASK", `unknown task: ${taskId}`, { retryable: false });
 	return task;
 }
 

package/src/task-inbox.ts

@@ -5,6 +5,7 @@ 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;
@@ -17,16 +18,18 @@ interface InboxPi {
 		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 }): 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.receiverPersisted | typeof TaskDeliveryStage.wakeRequested | typeof TaskDeliveryStage.wakeAccepted; readonly state: typeof TaskDeliveryEvidenceState.confirmed }
+	| { readonly stage: typeof TaskDeliveryStage.receiverRecorded | typeof TaskDeliveryStage.wakeRequested | typeof TaskDeliveryStage.wakeAccepted; readonly state: typeof TaskDeliveryEvidenceState.confirmed }
 	| { readonly stage: typeof TaskDeliveryStage.piInsertion; readonly state: typeof TaskDeliveryEvidenceState.blocked; readonly retryable: true };
 
 /** Persists model-visible Pi evidence before advancing the relay cursor, then starts one separate turn. */
@@ -44,8 +47,13 @@ export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: Inb
 		if (context.hasPendingMessages()) return;
 		const eventDetails = { taskId: event.taskId, eventId: event.eventId };
 		const eventKey = key(event.taskId, event.eventId);
+		if (!isModelVisible(event.type) && !recordedEventKeys(context.sessionManager.getEntries()).has(eventKey)) {
+			// Archive receipts/parent ACK/late-terminal facts without waking the model.
+			// This is evidence only: no task state or delivery queue is reconstructed.
+			pi.appendEntry(TASK_RECORD_CUSTOM_TYPE, { ...eventDetails, event });
+		}
 		if (event.type === "task.created") {
-			await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.receiverPersisted, state: TaskDeliveryEvidenceState.confirmed }, signal);
+			await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.receiverRecorded, state: TaskDeliveryEvidenceState.confirmed }, signal);
 		}
 		let incorporated = incorporatedEvents(context.sessionManager.getEntries()).has(eventKey);
 		if (!incorporated && isModelVisible(event.type)) {
@@ -54,7 +62,7 @@ export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: Inb
 				customType: TASK_EVENT_CUSTOM_TYPE,
 				content: renderTaskEvent(event),
 				display: true,
-				details: eventDetails,
+				details: { ...eventDetails, event },
 			}, { triggerTurn: false });
 			incorporated = incorporatedEvents(context.sessionManager.getEntries()).has(eventKey);
 			if (!incorporated) {
@@ -126,6 +134,12 @@ function taskMessageDetails(entries: readonly unknown[], customType: string): re
 	return events;
 }
 
+function recordedEventKeys(entries: readonly unknown[]): Set<string> {
+	return new Set(entries.flatMap(entry => isRecord(entry) && entry.type === "custom" && entry.customType === TASK_RECORD_CUSTOM_TYPE
+		&& isRecord(entry.data) && typeof entry.data.taskId === "string" && typeof entry.data.eventId === "string"
+		? [key(entry.data.taskId, entry.data.eventId)] : []));
+}
+
 function taskMessageKeys(entries: readonly unknown[], customType: string): Set<string> {
 	return new Set(taskMessageDetails(entries, customType).map((event) => key(event.taskId, event.eventId)));
 }

package/src/task-protocol.ts

@@ -1,11 +1,12 @@
 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 const TaskDeliveryStage = {
-	receiverPersisted: "receiver_persisted",
+	receiverRecorded: "receiver_recorded",
 	piInsertion: "pi_insertion",
 	piInserted: "pi_inserted",
 	wakeRequested: "wake_requested",
@@ -22,6 +23,17 @@ export interface TaskEndpoint {
 	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;
@@ -54,6 +66,9 @@ export interface RelayEnvelope {
 	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;
 }
@@ -82,6 +97,8 @@ export interface RelayInboxPage {
 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 {
@@ -90,6 +107,7 @@ export interface TaskRelay {
 	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>;
 }
 

package/src/task-relay-conformance.ts

@@ -5,6 +5,16 @@ import type { TaskRelay } from "./task-protocol";
 
 /** Shared assertions external relay adapters can run against their implementation. */
 export function runTaskRelayConformance(createRelay: () => TaskRelay): void {
+	test("acknowledging a later delivery retains earlier unacknowledged mail", async () => {
+		const relay = createRelay();
+		const source = { relay: relay.id, id: "source" }, target = { relay: relay.id, id: "target" };
+		for (const endpoint of [source, target]) await relay.connect({ endpoint, protocolVersion: TASK_PROTOCOL_VERSION, receiveCursor: "0" });
+		for (const envelopeId of ["first", "second"]) await relay.send({ envelopeId, protocolVersion: TASK_PROTOCOL_VERSION, source, target, taskId: "task", kind: "assignment", payload: "{}", createdAt: new Date().toISOString() });
+		const page = await relay.receive({ endpoint: target, cursor: "0", limit: 10 });
+		expect(page.deliveries).toHaveLength(2);
+		await relay.acknowledgeDelivery({ endpoint: target, cursor: page.deliveries[1]!.cursor });
+		expect((await relay.receive({ endpoint: target, cursor: "0", limit: 10 })).deliveries.map(d => d.envelope.envelopeId)).toContain("first");
+	});
 	test("enforces registration, accepts duplicate envelopes once, and retains delivery until acknowledgement", async () => {
 		const relay = createRelay();
 		const source = { relay: relay.id, id: "source" };
@@ -12,7 +22,7 @@ export function runTaskRelayConformance(createRelay: () => TaskRelay): void {
 		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: "{}" };
+		const envelope = { envelopeId: "envelope-1", protocolVersion: TASK_PROTOCOL_VERSION, source, target, taskId: "task-1", kind: "assignment" as const, payload: "{}", createdAt: new Date(0).toISOString() };
 		await relay.send(envelope);
 		await relay.send(envelope);
 		const page = await relay.receive({ endpoint: target, cursor: "0", limit: 10 });