pi-crew 0.10.2 → 0.10.4

package/src/hooks/registry.ts

@@ -42,6 +42,65 @@ export function getHooks(name: HookName): HookDefinition[] {
 	return registry.get(name) ?? [];
 }
 
+// PERF (2026-08-24): constant sanitizer state hoisted to module scope — it was
+// rebuilt (12 normalize+toLowerCase + Set + 3 closures) on EVERY hook execution.
+const POLLUTED_KEYS = new Set(
+	[
+		"__proto__",
+		"constructor",
+		"prototype",
+		"hasOwnProperty",
+		"toString",
+		"valueOf",
+		"isPrototypeOf",
+		"propertyIsEnumerable",
+		"__defineGetter__",
+		"__defineSetter__",
+		"__lookupGetter__",
+		"__lookupSetter__",
+	].map((k) => k.toLowerCase().normalize("NFKC")),
+);
+function sanitizeMergeData(data: Record<string, unknown>): Record<string, unknown> {
+	const clean: Record<string, unknown> = {};
+	for (const [k, v] of Object.entries(data)) {
+		if (!POLLUTED_KEYS.has(k.toLowerCase().normalize("NFKC"))) {
+			if (v !== null && typeof v === "object") {
+				if (Array.isArray(v)) {
+					// Sanitize array elements that are objects
+					clean[k] = v.map((item) =>
+						item !== null && typeof item === "object" && !Array.isArray(item)
+							? sanitizeMergeData(item as Record<string, unknown>)
+							: item,
+					);
+				} else {
+					clean[k] = sanitizeMergeData(v as Record<string, unknown>);
+				}
+			} else {
+				clean[k] = v;
+			}
+		}
+	}
+	return clean;
+}
+// Sanitize ctx by stripping dangerous property names before passing to handlers.
+// Hook authors must NOT set these keys directly on ctx: [...POLLUTED_KEYS]
+// This sanitization runs at the start of executeHook to prevent prototype pollution attacks.
+function sanitizeContext(ctx: HookContext): HookContext {
+	for (const key of Object.keys(ctx)) {
+		if (POLLUTED_KEYS.has(key.toLowerCase().normalize("NFKC"))) {
+			delete ctx[key];
+		}
+	}
+	return ctx;
+}
+function sanitizeErrorMessage(message: string): string {
+	// Remove file paths, environment variable references, and other potentially sensitive data
+	return message
+		.replace(/\/[^:\s]+/g, "[path]")
+		.replace(/\b[A-Z_0-9]+\s*=/g, "[env]")
+		.replace(/\b\d+\.\d+\.\d+\.\d+\b/g, "[ip]");
+}
+
 export async function executeHook(name: HookName, ctx: HookContext): Promise<HookExecutionReport> {
 	const hooks = getHooks(name);
 	if (hooks.length === 0) return { hookName: name, outcome: "allow", durationMs: 0 };
@@ -62,62 +121,6 @@ export async function executeHook(name: HookName, ctx: HookContext): Promise<Hoo
 		return ctx.includeGlobalHooks !== false;
 	});
 	if (scopedHooks.length === 0) return { hookName: name, outcome: "allow", durationMs: 0 };
-	const POLLUTED_KEYS = new Set(
-		[
-			"__proto__",
-			"constructor",
-			"prototype",
-			"hasOwnProperty",
-			"toString",
-			"valueOf",
-			"isPrototypeOf",
-			"propertyIsEnumerable",
-			"__defineGetter__",
-			"__defineSetter__",
-			"__lookupGetter__",
-			"__lookupSetter__",
-		].map((k) => k.toLowerCase().normalize("NFKC")),
-	);
-	function sanitizeMergeData(data: Record<string, unknown>): Record<string, unknown> {
-		const clean: Record<string, unknown> = {};
-		for (const [k, v] of Object.entries(data)) {
-			if (!POLLUTED_KEYS.has(k.toLowerCase().normalize("NFKC"))) {
-				if (v !== null && typeof v === "object") {
-					if (Array.isArray(v)) {
-						// Sanitize array elements that are objects
-						clean[k] = v.map((item) =>
-							item !== null && typeof item === "object" && !Array.isArray(item)
-								? sanitizeMergeData(item as Record<string, unknown>)
-								: item,
-						);
-					} else {
-						clean[k] = sanitizeMergeData(v as Record<string, unknown>);
-					}
-				} else {
-					clean[k] = v;
-				}
-			}
-		}
-		return clean;
-	}
-	// Sanitize ctx by stripping dangerous property names before passing to handlers.
-	// Hook authors must NOT set these keys directly on ctx: [...POLLUTED_KEYS]
-	// This sanitization runs at the start of executeHook to prevent prototype pollution attacks.
-	function sanitizeContext(ctx: HookContext): HookContext {
-		for (const key of Object.keys(ctx)) {
-			if (POLLUTED_KEYS.has(key.toLowerCase().normalize("NFKC"))) {
-				delete ctx[key];
-			}
-		}
-		return ctx;
-	}
-	function sanitizeErrorMessage(message: string): string {
-		// Remove file paths, environment variable references, and other potentially sensitive data
-		return message
-			.replace(/\/[^:\s]+/g, "[path]")
-			.replace(/\b[A-Z_0-9]+\s*=/g, "[env]")
-			.replace(/\b\d+\.\d+\.\d+\.\d+\b/g, "[ip]");
-	}
 	const start = Date.now();
 	const diagnostics: string[] = [];
 	let capturedModifications: Record<string, unknown> | undefined;
@@ -176,6 +179,9 @@ export async function executeHook(name: HookName, ctx: HookContext): Promise<Hoo
 }
 
 export function appendHookEvent(manifest: TeamRunManifest, report: HookExecutionReport): void {
+	// REVIEW FIX (2026-09-10): reverted M2b buffered conversion — hook.executed
+	// events are read back synchronously (recovery-hooks tests, hooks audit
+	// display) and are low-frequency (per hook execution).
 	appendEvent(manifest.eventsPath, {
 		type: "hook.executed",
 		runId: manifest.runId,

package/src/prompt/inbox-poll.ts

@@ -0,0 +1,90 @@
+/**
+ * inbox-poll.ts — Task 5 (SDD 2026-08-26-loadout-nesting-messaging) worker
+ * inbox pickup.
+ *
+ * The worker-side `message` tool (D9 / §15.2) writes durable mailbox
+ * entries (`kind:"message"` | `"notify"`). This module is the RECEIVE side:
+ * the poll loop that shares the ask/delegate cadence picks up new
+ * `kind:"message"` entries addressed to THIS task and surfaces them as
+ * fenced context at the next turn boundary via `pi.sendMessage` with
+ * `deliverAs:"steer"`.
+ *
+ * Contract (mirrors the broker's recipient resolution in handleMsgSend):
+ *   - only `kind:"message"` enters the pickup (notify → fire-and-forget,
+ *     steer/response/follow-up → other channels);
+ *   - only entries whose mailbox task is THIS worker (`taskId === this`):
+ *     sibling DMs are written to the sibling's task mailbox, group-broadcast
+ *     recipient copies are written to each recipient's task mailbox, and
+ *     `to:"parent"` reports land in the run-level inbox (taskId undefined)
+ *     which is ORCHESTRATOR territory — a worker must never read it;
+ *   - a worker must never pick up a message whose `from` is itself (§15.3
+ *     anti-spoof / self-echo: the broker overrides `from` to the sender's
+ *     authenticated taskId, so a group broadcast returns to its sender and
+ *     must be dropped at consume time);
+ *   - dedup by message id across polls via a caller-owned seen-set and/or a
+ *     `sinceTs` watermark — one message delivers once.
+ */
+import { type MailboxMessage, readAllMailboxMessages } from "../state/coordination/mailbox.ts";
+import type { TeamRunManifest } from "../state/types.ts";
+
+export interface WorkerInboxPickup {
+	stateRoot: string;
+	runId: string;
+	taskId: string;
+	/** Watermark: only messages with `createdAt > sinceTs` are considered. */
+	sinceTs?: string;
+	/** Mutable seen-id set for cross-poll dedup (the poll loop owns it). */
+	seenIds?: Set<string>;
+}
+
+/**
+ * Read the worker's inbox mailbox and return the messages that should be
+ * surfaced as fenced context on the next turn.
+ *
+ * Stateless apart from the optional caller-owned `seenIds`/`sinceTs` — safe
+ * to call on every 500ms poll tick.
+ */
+export function pollWorkerInbox(pickup: WorkerInboxPickup): MailboxMessage[] {
+	const { stateRoot, runId, taskId } = pickup;
+	if (!stateRoot || !runId || !taskId) return [];
+	const manifest = { stateRoot, runId } as unknown as TeamRunManifest;
+	let messages: MailboxMessage[];
+	try {
+		// readAllMailboxMessages already merges run-level inbox + every task
+		// mailbox; we route TO this worker below (never trust a caller-scoped
+		// file path).
+		messages = readAllMailboxMessages(manifest, "inbox");
+	} catch {
+		// Transient read error (lock contention, rotated file) — never throw
+		// out of a poll tick; the next 500ms tick retries.
+		return [];
+	}
+
+	const seen = pickup.seenIds;
+	const picked: MailboxMessage[] = [];
+	const byId = new Set<string>();
+	for (const m of messages) {
+		// Kind gate: only durable `message`s (per §15.2). Notify is
+		// fire-and-forget (its own channel), steer/response/follow-up are
+		// other delivery paths.
+		if (m.kind !== "message") continue;
+		// §15.3 self-echo: a broadcast the worker itself sent must not
+		// re-surface on its own next turn.
+		if (m.from === taskId) continue;
+		// Routing: the entry must be in THIS task's mailbox — never the
+		// run-level inbox (orchestrator's parent channel) nor a sibling's.
+		if (m.taskId !== taskId) continue;
+		if (m.status === "acknowledged") continue;
+		// sinceTs watermark (ISO string compare).
+		if (pickup.sinceTs !== undefined && m.createdAt <= pickup.sinceTs) continue;
+		// Cross-call seen-set dedup.
+		if (seen?.has(m.id)) continue;
+		// Within-call id dedup (duplicate file rows → one delivery).
+		if (byId.has(m.id)) continue;
+		byId.add(m.id);
+		seen?.add(m.id);
+		picked.push(m);
+	}
+	// Deterministic delivery order (same sort readAllMailboxMessages applies).
+	return picked;
+}

package/src/prompt/message-tool.ts

@@ -0,0 +1,166 @@
+/**
+ * message-tool.ts — D9 / §15.2 worker-side `message` tool.
+ *
+ * The worker's NON-BLOCKING outbound channel (unlike `ask`, this never parks
+ * the task). Three targets:
+ *   - `to: "parent"`  → notify the orchestrator (run-level inbox read by the
+ *     main session; wake-pattern inject happens host-side, see §15.2).
+ *   - `to: <taskId>`  → DM a sibling task.
+ *   - `to: "group"`   → broadcast every worker that did group_join.
+ *
+ * Delivery is the broker `msg.send` method (already server-side role-gated
+ * since Step 0 — workers may send with `from` always overridden to their
+ * authenticated taskId, `to` restricted to parent/sibling/group, kind
+ * notify|message). A broker outage falls back to the same "unavailable"
+ * notice the ask/delegate tools return — never a hang.
+ *
+ * Dormant-until-env (ask/delegate precedent): registered ONLY when
+ * `PI_CREW_MSG_ENABLED === "1"` (child-pi-spawn sets it unconditionally); a
+ * layer-2 dormant check re-verifies inside execute. Tests inject a mock
+ * broker client directly, which bypasses the env gate.
+ *
+ * Local rate-limit: 10 messages/minute per tool instance (sliding window) —
+ * the 11th within the window returns a `rate-limited` warning instead of
+ * sending, so two workers cannot loop message each other to death.
+ */
+
+import { type Static, Type } from "@sinclair/typebox";
+import { getCrewEnv } from "../config/env-vars.ts";
+import { CrewBrokerClient } from "../runtime/broker/crew-broker-client.ts";
+
+export const PI_CREW_MSG_ENABLED_ENV = "PI_CREW_MSG_ENABLED";
+
+/** D9 §15.3: body length cap mirrors the ask/delegate bounded-payload bounds;
+ *  the broker additionally enforces the 256 KiB frame cap server-side. */
+const MSG_BODY_MAX_CHARS = 8192;
+const MSG_SUBJECT_MAX_CHARS = 256;
+const MSG_TO_MAX_CHARS = 256;
+/** §15.2 rate-limit: 10 messages/min/task, sliding window. */
+const MSG_RATE_LIMIT_MAX = 10;
+const MSG_RATE_LIMIT_WINDOW_MS = 60_000;
+
+export const MessageToolParamsSchema = Type.Object({
+	to: Type.Union([Type.Literal("parent"), Type.Literal("group"), Type.String({ minLength: 1, maxLength: MSG_TO_MAX_CHARS })]),
+	kind: Type.Union([Type.Literal("notify"), Type.Literal("message")]),
+	subject: Type.Optional(Type.String({ minLength: 1, maxLength: MSG_SUBJECT_MAX_CHARS })),
+	body: Type.String({ minLength: 1, maxLength: MSG_BODY_MAX_CHARS }),
+	priority: Type.Optional(Type.Union([Type.Literal("urgent"), Type.Literal("normal"), Type.Literal("low")])),
+});
+export type MessageToolParams = Static<typeof MessageToolParamsSchema>;
+
+/** Minimal broker-client surface the message tool needs (structural subset of
+ *  CrewBrokerClient — tests substitute a recorder). */
+export interface MessageBrokerClientSurface {
+	request(method: string, params: unknown): Promise<{ ok: true; value: unknown } | { ok: false; fallback?: boolean; errorCode?: string }>;
+	close?(): Promise<void>;
+}
+
+export interface MessageToolDeps {
+	/** Env source override (tests). Production reads via getCrewEnv. */
+	env?: NodeJS.ProcessEnv;
+	/** Test seam / injectable clock for the 10/min sliding window. */
+	now?: () => number;
+	/** Test seam: replace the per-call broker client. */
+	makeBrokerClient?: (o: { runId: string; taskId: string; socketPath: string; token: string }) => MessageBrokerClientSurface;
+}
+
+export interface MessageTool {
+	name: "message";
+	description: string;
+	inputSchema: object;
+	execute: (params: MessageToolParams) => Promise<{ status: string; text: string }>;
+}
+
+/** Layer-1 dormant-until-env gate (ask precedent: default-param env — reads
+ *  the injected env object, never a raw process.env.PI_CREW_* member, so the
+ *  check:env-vars gate stays green). */
+export function shouldRegisterMessageTool(env: NodeJS.ProcessEnv = process.env): boolean {
+	return env[PI_CREW_MSG_ENABLED_ENV] === "1";
+}
+
+export function createMessageTool(deps: MessageToolDeps = {}): MessageTool {
+	const now = deps.now ?? Date.now;
+	const get = (name: string): string | undefined => (deps.env ? deps.env[name] : getCrewEnv(name));
+	// Sliding window of send timestamps (ms). Pruned lazily on each send.
+	const sentAt: number[] = [];
+
+	/** Layer-2 dormant check: registered-only-when-env is the primary gate;
+	 *  an injected mock client (tests) deliberately bypasses it so the core
+	 *  send path is exercised without env plumbing. */
+	const isActive = (): boolean => get(PI_CREW_MSG_ENABLED_ENV) === "1" || deps.makeBrokerClient !== undefined;
+
+	/** True when the 10/min window is exhausted (the caller skips the send). */
+	const isRateLimited = (): boolean => {
+		const t = now();
+		while (sentAt.length > 0 && t - sentAt[0]! >= MSG_RATE_LIMIT_WINDOW_MS) sentAt.shift();
+		if (sentAt.length >= MSG_RATE_LIMIT_MAX) return true;
+		sentAt.push(t);
+		return false;
+	};
+
+	const brokerUnavailable = (): { status: string; text: string } => ({
+		status: "unavailable",
+		text: "[message] broker unavailable — include the note in your final result instead.",
+	});
+
+	return {
+		name: "message",
+		description:
+			"Send a non-blocking message: notify the orchestrator of progress/risks (`to:'parent'`), DM another worker by task id, or broadcast the group. Unlike `ask`, this never waits.",
+		inputSchema: MessageToolParamsSchema,
+		async execute(params) {
+			if (!isActive()) {
+				return {
+					status: "unavailable",
+					text: "[message] is dormant in this worker (PI_CREW_MSG_ENABLED not set) — include the note in your final result instead.",
+				};
+			}
+			if (isRateLimited()) {
+				// §15.2: 10 messages/min/task; a warning instead of a silent drop
+				// keeps the model informed the note was NOT delivered.
+				return {
+					status: "rate-limited",
+					text: "[message] rate-limited (10 messages/minute) — this message was NOT sent; include the note in your final result instead.",
+				};
+			}
+			const runId = get("PI_CREW_BROKER_RUN_ID") ?? "";
+			const taskId = get("PI_CREW_TASK_ID") ?? get("PI_CREW_BROKER_TASK_ID") ?? "";
+			const socketPath = get("PI_CREW_BROKER_SOCKET") ?? "";
+			const token = get("PI_CREW_BROKER_TOKEN") ?? "";
+			const client = deps.makeBrokerClient
+				? deps.makeBrokerClient({ runId, taskId, socketPath, token })
+				: (() => {
+						// Production: the broker credentials are only present for
+						// broker-eligible workers (child-pi-spawn). Scaffold/mock
+						// workers fast-fail with a structured notice, never a hang.
+						if (!runId || !taskId || !socketPath || !token) return null;
+						return new CrewBrokerClient({ runId, taskId, socketPath, token });
+					})();
+			if (!client) return brokerUnavailable();
+			const requestParams: Record<string, unknown> = { to: params.to, kind: params.kind, body: params.body };
+			if (params.subject) requestParams.subject = params.subject;
+			if (params.priority) requestParams.priority = params.priority;
+			try {
+				const sent = await client.request("msg.send", requestParams);
+				if (!sent.ok) {
+					// Broker rejection (role gate / policy / auth / fallback) — all
+					// fast-fail, non-blocking.
+					return brokerUnavailable();
+				}
+				return {
+					status: "sent",
+					text: `Message (${params.kind}) delivered to '${params.to}'.`,
+				};
+			} catch (error) {
+				void error;
+				return brokerUnavailable();
+			} finally {
+				// Only the production-created client needs closing; an injected
+				// test recorder owns its own lifecycle.
+				if (!deps.makeBrokerClient && client.close) {
+					void client.close().catch(() => undefined);
+				}
+			}
+		},
+	};
+}