@sgtbeatdown/pi-tasks 0.1.12 → 0.1.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sgtbeatdown/pi-tasks",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "Memory-only endpoint-owned Pi agent delegation through Wolfpack relay v2.",
   "module": "src/index.ts",
   "exports": {

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

@@ -74,8 +74,8 @@ Assignment completion ends the assigned task, not the reusable role session. Whe
 1. create a role session through the readiness path above, or select an existing role by stable ID and verify its structured liveness, canonical project, Pi harness, and registered `taskEndpoint`. Never use terminal output as readiness evidence.
 2. call `agent_task_send` with the opaque endpoint and concise instructions in `task`. The tool returns after relay acceptance only, not Pi insertion or model execution. If submission reports a retryable delivery error after local persistence, use the structured task ID from the error and inspect it rather than creating an unrelated replacement.
 3. after `agent_task_send`, continue useful independent coordinator work. When none remains, yield the current turn and let structured task follow-up wake the parent; do not poll `agent_task_status` or `agent_task_inbox` merely to wait. Reserve those tools for concrete progress evidence or recovery, and call `agent_task_wait` only when the user explicitly asks to block.
-4. use `agent_task_message` for `question`, `answer`, or `information` flow within the active endpoint lifetime. Do not use rendered text, terminal output, or logs as lifecycle evidence.
-5. assignees call `agent_task_done` as their final action with the assigned task ID, terminal status, concise summary, and optional structured result, error, and artifact declarations. Report source modifications in `result.changedFiles`; artifacts are receiver-project-relative regular files for a parent to inspect, not changed-file lists: `{ "result": { "changedFiles": ["src/extension.ts"] }, "artifacts": [{ "path": "verification/task-2.md" }] }`. No prose completion afterward.
+4. while continuing work or asking for input, use `agent_task_message` for intermediate `question`, `answer`, or `information` flow within the active endpoint lifetime. Do not use rendered text, terminal output, or logs as lifecycle evidence.
+5. assignees call exactly one final `agent_task_done` with the assigned task ID, terminal status, and concise completion or blocker summary, plus optional structured result, error, and artifact declarations. Intermediate messages remain allowed; do not send a separate terminal information message before `agent_task_done`. Report source modifications in `result.changedFiles`; artifacts are receiver-project-relative regular files for a parent to inspect, not changed-file lists: `{ "result": { "changedFiles": ["src/extension.ts"] }, "artifacts": [{ "path": "verification/task-2.md" }] }`. No prose completion afterward.
 6. the parent independently verifies files, diff, tests, and artifacts. Then call `agent_task_ack({ taskId })` for that one terminal task and explicitly retain or close the spawned role session.
 
 ## v2 delivery and recovery

package/src/configured-task-core.ts

@@ -1,4 +1,4 @@
-import type { TaskCore } from "./task-core";
+import type { TaskCore, WakeRequest } from "./task-core";
 import { TaskProtocolError } from "./task-protocol";
 import { createTaskStore } from "./task-store";
 import { createVolatileTaskSession } from "./volatile-task-session";
@@ -36,6 +36,11 @@ export async function createConfiguredTaskCore(options: ConfiguredTaskCoreOption
     const active = new Set<Promise<unknown>>();
     let closed = false, closing: Promise<void> | undefined;
     const owned = { ...core } as OwnedTaskCore;
+    const track = <T>(result: Promise<T>): Promise<T> => {
+      active.add(result);
+      void result.then(() => active.delete(result), () => active.delete(result));
+      return result;
+    };
     for (const [key, value] of Object.entries(core)) {
       if (typeof value !== "function") continue;
       Object.defineProperty(owned, key, { enumerable: true, value: (...args: unknown[]) => {
@@ -43,10 +48,14 @@ export async function createConfiguredTaskCore(options: ConfiguredTaskCoreOption
         // Core methods may call sibling methods through `this` (notably intent ACK).
         // Keep their original receiver while the outer promise owns the full operation.
         const result: unknown = value.apply(core, args);
-        if (!(result instanceof Promise)) return result;
-        active.add(result);
-        void result.then(() => active.delete(result), () => active.delete(result));
-        return result;
+        if (key === "recordWakeRequest") {
+          const request = result as WakeRequest;
+          return { flush: (signal?: AbortSignal): Promise<void> => {
+            if (closed) throw new TaskProtocolError("RELAY_CLOSED", "task session is closed", { retryable: false });
+            return track(request.flush(signal));
+          } };
+        }
+        return result instanceof Promise ? track(result) : result;
       } });
     }
     owned.close = () => {

package/src/extension.ts

@@ -142,6 +142,14 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 			async recordInsertion(input, insertionSignal) {
 				if (isCurrent()) await activeCore.recordInsertion(input, insertionSignal);
 			},
+			recordWakeRequest(input) {
+				if (!isCurrent()) throw new TaskProtocolError("RELAY_CLOSED", "task lifecycle was replaced", { retryable: false });
+				const request = activeCore.recordWakeRequest(input);
+				return { flush: async (flushSignal?: AbortSignal): Promise<void> => {
+					if (!isCurrent()) throw new TaskProtocolError("RELAY_CLOSED", "task lifecycle was replaced", { retryable: false });
+					await request.flush(flushSignal);
+				} };
+			},
 		};
 		const inboxOutboxError = await deliverTaskInbox({
 			sendMessage(message, options) { if (isCurrent()) pi.sendMessage(message, options); },

package/src/task-core.ts

@@ -27,6 +27,7 @@ const RECEIVE_PAGE_SIZE = 100;
 const DELIVERY_EVIDENCE_OPERATION = "delivery_evidence";
 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 CONVERSATIONAL_EVENTS = new Set(["task.information", "task.question", "task.answer"]);
 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",
@@ -60,6 +61,11 @@ export type SubmitIntentOutcome =
 	| { readonly authority: "origin"; readonly canonicalEvent: { readonly type: string; readonly reused: boolean } }
 	| { readonly authority: "receiver" };
 
+/** Local wake-request evidence is persisted before Pi wake emission; relay delivery is flushed afterward. */
+export interface WakeRequest {
+	flush(signal?: AbortSignal): Promise<void>;
+}
+
 export interface TaskCore {
 	readonly endpoint: TaskEndpoint;
 	connect(signal?: AbortSignal): Promise<void>;
@@ -72,6 +78,7 @@ export interface TaskCore {
 	submitIntent(input: SubmitIntentInput, signal?: AbortSignal): Promise<void>;
 	submitIntentWithOutcome?(input: SubmitIntentInput, signal?: AbortSignal): Promise<SubmitIntentOutcome>;
 	recordInsertion(input: { readonly taskId: string; readonly eventId: string }, signal?: AbortSignal): Promise<void>;
+	recordWakeRequest(input: { readonly taskId: string; readonly eventId: string }): WakeRequest;
 	evaluateTimeouts(signal?: AbortSignal): Promise<void>;
 	acknowledgeParent(taskId: string, signal?: AbortSignal): Promise<void>;
 }
@@ -213,6 +220,21 @@ export function createTaskCore(options: TaskCoreOptions): TaskCore {
 			});
 			await flushDeliveryEvidence(options, signal, input.taskId, persistedEnvelopeIds, evidence);
 		},
+		recordWakeRequest(input) {
+			const task = requiredTask(options.store, input.taskId);
+			const evidence: DeliveryEvidence = { eventId: input.eventId, stage: TaskDeliveryStage.wakeRequested, state: TaskDeliveryEvidenceState.confirmed };
+			let persistedEnvelopeIds: readonly string[] = [];
+			options.store.transaction(() => {
+				persistedEnvelopeIds = persistIntent(options, clock.now, ids, task, {
+					taskId: input.taskId,
+					type: "task.delivery_receipt",
+					payload: { eventId: input.eventId, stage: evidence.stage, state: evidence.state },
+				}, deliveryEvidenceOperation(evidence)).envelopeIds;
+			});
+			return { flush: async (signal?: AbortSignal): Promise<void> => {
+				await flushDeliveryEvidence(options, signal, input.taskId, persistedEnvelopeIds, evidence);
+			} };
+		},
 		async evaluateTimeouts(signal) {
 			const persistedEnvelopeIds: string[] = [];
 			for (const candidate of options.store.listTasks()) {
@@ -303,7 +325,9 @@ function persistIntent(options: TaskCoreOptions, now: () => number, ids: () => s
 	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);
+		// The origin already recorded its own conversational event; echo only peer-authored conversations back for model incorporation.
+		const echoCanonicalEventToOrigin = !CONVERSATIONAL_EVENTS.has(input.type);
+		const canonical = canonicalize(options, now, ids, task, { intentId: ids(), taskId: input.taskId, type: input.type, payload: input.payload }, input.type, operation, echoCanonicalEventToOrigin);
 		return { envelopeIds: canonical.envelopeIds, outcome: { authority: "origin", canonicalEvent: { type: canonical.eventType, reused: canonical.reused } } };
 	}
 	const envelopeId = ids();
@@ -363,21 +387,22 @@ interface Canonicalization {
 	readonly reused: boolean;
 }
 
-function canonicalize(options: TaskCoreOptions, now: () => number, ids: () => string, task: TaskRecord, intent: TaskIntent, requestedType: string, operation?: string): Canonicalization {
+function canonicalize(options: TaskCoreOptions, now: () => number, ids: () => string, task: TaskRecord, intent: TaskIntent, requestedType: string, operation?: string, echoCanonicalEventToOrigin = true): Canonicalization {
 	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, 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];
+	const suppressSelfTargetConversationEcho = !echoCanonicalEventToOrigin && sameEndpoint(task.origin, task.target);
+	const targetEnvelope = suppressSelfTargetConversationEcho ? undefined : envelope(ids(), options.endpoint, task.target, task.taskId, TaskEnvelopeKind.canonicalEvent, canonical, canonical.occurredAt);
+	const originEnvelope = !echoCanonicalEventToOrigin || sameEndpoint(task.origin, task.target) ? undefined : envelope(ids(), options.endpoint, task.origin, task.taskId, TaskEnvelopeKind.canonicalEvent, canonical, canonical.occurredAt);
+	const persistedEnvelopeIds = [targetEnvelope, originEnvelope].flatMap((item) => item === undefined ? [] : [item.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 { envelopeIds: reservation.record.envelopeIds, eventType: reservation.record.logicalType, reused: true };
 	}
 	options.store.appendEvent(canonical);
 	if (TERMINAL_EVENTS.has(type)) options.store.setStatus(task.taskId, statusFor(type));
-	options.store.putOutbox(targetEnvelope);
+	if (targetEnvelope !== undefined) options.store.putOutbox(targetEnvelope);
 	if (originEnvelope !== undefined) options.store.putOutbox(originEnvelope);
 	return { envelopeIds: persistedEnvelopeIds, eventType: type, reused: false };
 }

package/src/task-inbox.ts

@@ -6,6 +6,7 @@ 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";
+const TERMINAL_EVENT_TYPES = new Set(["task.completed", "task.failed", "task.cancelled", "task.timed_out"]);
 
 interface InboxContext {
 	readonly isIdle: () => boolean;
@@ -77,10 +78,11 @@ export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: Inb
 			const insertionError = await settleDeliveryEvidence(() => core.recordInsertion(eventDetails, signal));
 			outboxError ??= insertionError;
 			let wakeAccepted = taskMessageKeys(context.sessionManager.getEntries(), TASK_WAKE_CUSTOM_TYPE).has(eventKey);
-			if (!wakeAccepted) {
+			const wakeSuppressed = !wakeAccepted && hasAcknowledgedLocalOriginTerminal(core, event);
+			if (!wakeAccepted && !wakeSuppressed) {
 				if (!context.isIdle()) return outboxError;
-				const wakeRequestError = await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.wakeRequested, state: TaskDeliveryEvidenceState.confirmed }, signal);
-				outboxError ??= wakeRequestError;
+				// This synchronous local write closes the ACK/wake race; do not await relay I/O before Pi emits the wake.
+				const wakeRequest = core.recordWakeRequest(eventDetails);
 				pi.sendMessage({
 					customType: TASK_WAKE_CUSTOM_TYPE,
 					content: "Process the pending Pi task event.",
@@ -89,9 +91,13 @@ export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: Inb
 				}, { triggerTurn: true, deliverAs: "followUp" });
 				wakeAccepted = taskMessageKeys(context.sessionManager.getEntries(), TASK_WAKE_CUSTOM_TYPE).has(eventKey);
 				if (!wakeAccepted) return outboxError;
+				const wakeRequestError = await settleDeliveryEvidence(() => wakeRequest.flush(signal));
+				outboxError ??= wakeRequestError;
+			}
+			if (wakeAccepted) {
+				const wakeAcceptanceError = await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.wakeAccepted, state: TaskDeliveryEvidenceState.confirmed }, signal);
+				outboxError ??= wakeAcceptanceError;
 			}
-			const wakeAcceptanceError = await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.wakeAccepted, state: TaskDeliveryEvidenceState.confirmed }, signal);
-			outboxError ??= wakeAcceptanceError;
 		}
 		await core.acknowledgeRelayDelivery(delivery.cursor, signal);
 		pi.appendEntry(TASK_CURSOR_CUSTOM_TYPE, { cursor: delivery.cursor });
@@ -131,6 +137,14 @@ function isModelVisible(type: string): boolean {
 	return !["task.delivery_receipt", "task.parent_acknowledged", "task.late_terminal"].includes(type);
 }
 
+function hasAcknowledgedLocalOriginTerminal(core: TaskCore, event: TaskEvent): boolean {
+	if (!TERMINAL_EVENT_TYPES.has(event.type)) 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 ?? "")}`;
 	const body = typeof event.payload.message === "string" ? `\n\n${event.payload.message}` : "";