@skydiveai/pi-extensions 0.1.0-beta.76 → 0.1.0-beta.763

package/dist/index.mjs

@@ -21,6 +21,10 @@ import { BatchSpanProcessor, NodeTracerProvider } from "@opentelemetry/sdk-trace
 import { ATTR_SERVICE_NAME } from "@opentelemetry/semantic-conventions";
 import { hc } from "hono/client";
 import { parse } from "yaml";
+import { execFile } from "node:child_process";
+import { availableParallelism } from "node:os";
+import { promisify } from "node:util";
+import { quote } from "shell-quote";
 import { createWriteStream } from "node:fs";
 import { finished } from "node:stream/promises";
 import { createLocalBashOperations } from "@earendil-works/pi-coding-agent";
@@ -255,7 +259,7 @@ function createHealthHandler({ metadata }) {
 * read on the hot path before every LLM call), it falls back to the default
 * for that knob and logs once.
 */
-const log$13 = logger.child({ module: "context-management-config" });
+const log$14 = logger.child({ module: "context-management-config" });
 const DEFAULT_CONTEXT_MANAGEMENT_CONFIG = {
 	enabled: false,
 	perResultMaxBytes: 16 * 1024,
@@ -303,7 +307,7 @@ function resolveContextManagementConfig(env = process.env) {
 		maxModelCallsPerTurn: env.SKYDIVE_CTX_MAX_MODEL_CALLS
 	});
 	if (!parsed.success) {
-		log$13.warn({
+		log$14.warn({
 			event: "context_management_config_invalid",
 			err: parsed.error
 		}, "falling back to default context-management config");
@@ -437,7 +441,7 @@ const CAPABILITY_SOUL_NUDGE = "New capability gained — once the current task i
 * or `ToolDefinition[]`. Files starting with `_` or `.` are skipped, so
 * `tools/_example.ts` documents the shape without registering.
 */
-const log$12 = logger.child({ module: "local-tools-extension" });
+const log$13 = logger.child({ module: "local-tools-extension" });
 const TOOLS_DIRNAME = "tools";
 const fileState = /* @__PURE__ */ new Map();
 let pendingLocalToolsUpdate = null;
@@ -581,7 +585,7 @@ async function reconcileAndQueue({ pi, dir, reason }) {
 		dir
 	});
 	if (reason !== "session_start" && summaryHasChanges$1(summary)) pendingLocalToolsUpdate = summary;
-	log$12.info({
+	log$13.info({
 		event: "local_tools_reconcile",
 		reason,
 		total_tools: summary.totalTools,
@@ -603,7 +607,7 @@ const localToolsExtension = (pi) => {
 				reason: "session_start"
 			});
 		} catch (err) {
-			log$12.error({
+			log$13.error({
 				err,
 				event: "local_tools_reconcile_failed"
 			}, "local tools reconcile failed");
@@ -615,7 +619,7 @@ const localToolsExtension = (pi) => {
 		try {
 			current = await listToolFiles(dir);
 		} catch (err) {
-			log$12.warn({
+			log$13.warn({
 				err,
 				event: "local_tools_listing_failed"
 			}, "tools/ listing failed");
@@ -637,7 +641,7 @@ const localToolsExtension = (pi) => {
 				reason: "auto_reload"
 			});
 		} catch (err) {
-			log$12.error({
+			log$13.error({
 				err,
 				event: "local_tools_auto_reload_failed"
 			}, "auto-reload after tools/ change failed");
@@ -862,7 +866,7 @@ async function loadMcpConfig(path) {
 * Clients are keyed by JSON-stringified config and reused across
 * reloads — only changed configs reconnect.
 */
-const log$11 = logger.child({ module: "mcp-extension" });
+const log$12 = logger.child({ module: "mcp-extension" });
 async function closeConnected(connected) {
 	try {
 		await connected.client.close();
@@ -1226,7 +1230,7 @@ var McpExtension = class {
 		});
 		this.lastConfigMtimeMs = await readConfigMtimeMs(configPath);
 		if (reason !== "session_start" && summaryHasChanges(summary)) this.pendingMcpUpdate = summary;
-		log$11.info({
+		log$12.info({
 			event: "mcp_reconcile",
 			reason,
 			total_tools: summary.totalTools,
@@ -1249,7 +1253,7 @@ var McpExtension = class {
 						reason: "session_start"
 					});
 				} catch (err) {
-					log$11.error({
+					log$12.error({
 						err,
 						event: "mcp_reconcile_failed"
 					}, "MCP reconcile failed");
@@ -1261,7 +1265,7 @@ var McpExtension = class {
 				try {
 					mtime = await readConfigMtimeMs(configPath);
 				} catch (err) {
-					log$11.warn({
+					log$12.warn({
 						err,
 						event: "mcp_mtime_check_failed"
 					}, "mtime check on mcp.config.json failed");
@@ -1275,7 +1279,7 @@ var McpExtension = class {
 						reason: "auto_reload"
 					});
 				} catch (err) {
-					log$11.error({
+					log$12.error({
 						err,
 						event: "mcp_auto_reload_failed"
 					}, "auto-reload after mcp.config.json change failed");
@@ -1683,15 +1687,15 @@ const HEARTBEAT_THROTTLE_MS = 6e4;
 const TOOL_HEARTBEAT_INTERVAL_MS = 5e3;
 const MAX_TOOL_HEARTBEATS = 1440 * 60 * 1e3 / TOOL_HEARTBEAT_INTERVAL_MS;
 const DAEMON_URL = "http://localhost:38994";
-const log$10 = logger.child({ module: "platform-ext" });
+const log$11 = logger.child({ module: "platform-ext" });
 function sandboxClient() {
 	const apiUrl = apiBaseUrl();
 	if (!apiUrl) return null;
 	return hc(`${apiUrl}/api/v1/sandbox`);
 }
 /**
-* Fetch every harness feature flag in one GET (`{ contextManagement, subagent,
-* ... }` — see apps/anyone/api/src/routes/sandbox-feature-flags.ts). Returns
+* Fetch every harness feature flag in one GET (`{ contextManagement, ... }`
+* — see apps/anyone/api/src/routes/sandbox-feature-flags.ts). Returns
 * null when indeterminate (no api url, or the request failed) so the shared
 * poller keeps the last-known values rather than flipping on a transient error.
 * This is the single fetch behind `feature-flags-poll.ts`; extensions read the
@@ -1703,19 +1707,15 @@ async function fetchHarnessFlags() {
 	try {
 		const res = await client["feature-flags"].$get();
 		if (!res.ok) {
-			log$10.debug({
+			log$11.debug({
 				status: res.status,
 				event: "feature_flags_fetch_failed"
 			}, "feature-flags fetch failed");
 			return null;
 		}
-		const body = await res.json();
-		return {
-			contextManagement: body.contextManagement ?? null,
-			subagent: body.subagent ?? null
-		};
+		return { contextManagement: (await res.json()).contextManagement ?? null };
 	} catch (err) {
-		log$10.debug({
+		log$11.debug({
 			err,
 			event: "feature_flags_fetch_error"
 		}, "feature-flags request errored");
@@ -1726,7 +1726,7 @@ function postHeartbeat({ messageId }) {
 	const client = sandboxClient();
 	if (!client) return;
 	client.heartbeat.$post({ json: { messageId } }).catch((err) => {
-		log$10.debug({
+		log$11.debug({
 			err,
 			event: "heartbeat_failed"
 		}, "heartbeat failed");
@@ -1738,7 +1738,7 @@ async function resolveConversationFromApi(messageId) {
 	try {
 		const res = await client["message-conversation"].$get({ query: { messageId } });
 		if (!res.ok) {
-			log$10.warn({
+			log$11.warn({
 				status: res.status,
 				messageId,
 				event: "resolve_conversation_failed"
@@ -1747,7 +1747,7 @@ async function resolveConversationFromApi(messageId) {
 		}
 		return (await res.json()).conversationId ?? null;
 	} catch (err) {
-		log$10.warn({
+		log$11.warn({
 			err,
 			messageId,
 			event: "resolve_conversation_error"
@@ -1772,7 +1772,11 @@ async function postSubagentSpawn({ messageId, tasks }) {
 		tasks
 	} });
 	if (!res.ok) throw new Error(`subagent-spawn POST failed: ${res.status}`);
-	return { taskIds: (await res.json()).taskIds };
+	const body = await res.json();
+	return {
+		taskIds: body.taskIds,
+		tasks: body.tasks ?? []
+	};
 }
 function createHeartbeatThrottle({ messageId }) {
 	let lastAt = 0;
@@ -1821,7 +1825,7 @@ function createToolHeartbeat({ messageId }) {
 			}
 			heartbeatCount++;
 			if (heartbeatCount > MAX_TOOL_HEARTBEATS) {
-				log$10.warn({
+				log$11.warn({
 					heartbeatCount,
 					activeToolCalls: [...activeToolCalls]
 				}, "tool heartbeat max reached, stopping");
@@ -1852,7 +1856,7 @@ function postToDaemon(path, body) {
 		headers: { "content-type": "application/json" },
 		body: JSON.stringify(body)
 	}).catch((err) => {
-		log$10.debug({
+		log$11.debug({
 			err,
 			path,
 			event: "daemon_post_failed"
@@ -1861,7 +1865,7 @@ function postToDaemon(path, body) {
 }
 function createPlatformExtensions({ sessionId, channelContext }) {
 	return (pi) => {
-		log$10.info({
+		log$11.info({
 			sessionId,
 			hasChannelContext: Boolean(channelContext)
 		}, "platform extension initialized");
@@ -1910,7 +1914,7 @@ function createPlatformExtensions({ sessionId, channelContext }) {
 			});
 		});
 		pi.on("agent_end", () => {
-			log$10.info({ sessionId }, "session ending");
+			log$11.info({ sessionId }, "session ending");
 			postToDaemon("/session/end", { sessionId });
 		});
 	};
@@ -1921,37 +1925,29 @@ function createPlatformExtensions({ sessionId, channelContext }) {
 * Shared harness feature-flag poll.
 *
 * The api exposes one `/feature-flags` GET that returns every harness flag in a
-* single response (`{ contextManagement, subagent, commandFlags }` — see
+* single response (`{ contextManagement, commandFlags }` — see
 * apps/anyone/api/src/routes/sandbox-feature-flags.ts). Rather than each
 * extension issuing its own GET — and, worse, a *blocking* GET on the
 * pre-first-token `session_start` path — a single background poller fetches
 * that response once per interval and fans the values out to every subscriber.
 *
-* Why one poller: the subagent extension gates its tool registration on the
-* `subagent` flag. If it awaited a fresh GET inside `session_start` the tool
-* schema (part of the prefill) couldn't be finalized until a serial
-* sandbox→api round-trip settled, adding a net-new pre-token network hop on
-* every session, flag on or off. Reading the last-polled value instead keeps
-* the hot path allocation-only. A cold cache reads as `null` (fail-open to
-* unregistered); a newly-flipped flag takes effect on the next poll, matching
-* how context-management already treats its flag.
+* Why one poller: context-management consumes the `contextManagement` flag
+* without a blocking GET on the pre-first-token `session_start` path. Reading
+* the last-polled value keeps the hot path allocation-only; a cold cache reads
+* as `null` and a newly-flipped flag takes effect on the next poll.
 *
 * The poll is fire-and-forget and self-unref'd — it never keeps the process
 * alive and an indeterminate result (no api url / transient failure) leaves the
 * last-known values untouched so a blip can't silently flip behavior.
 */
-const log$9 = logger.child({ module: "feature-flags-poll" });
+const log$10 = logger.child({ module: "feature-flags-poll" });
 const FLAG_POLL_INTERVAL_MS = 6e4;
 let contextManagement = null;
-let subagent = null;
-const subscribers = {
-	contextManagement: /* @__PURE__ */ new Set(),
-	subagent: /* @__PURE__ */ new Set()
-};
+const subscribers = { contextManagement: /* @__PURE__ */ new Set() };
 let pollerStarted = false;
 let firstPollSettled = false;
 let resolveFirstPoll = null;
-const firstPollPromise = new Promise((resolve) => {
+new Promise((resolve) => {
 	resolveFirstPoll = resolve;
 });
 function markFirstPollSettled() {
@@ -1960,20 +1956,8 @@ function markFirstPollSettled() {
 	resolveFirstPoll?.();
 }
 /** Last-polled value of a flag, or `null` if not yet resolved. */
-function getPolledFlag(name) {
-	return name === "contextManagement" ? contextManagement : subagent;
-}
-/**
-* Await the first poll already kicked by `startFeatureFlagPoller` (never a new
-* GET). Resolves when that poll settles, immediately if it already has, or
-* immediately when there's no flag source to poll. Callers on the hot path
-* should race this against their own short timeout so a slow/failed flag
-* service cannot delay first-token; a timeout just means the caller reads the
-* still-cold cache and falls back to its default, exactly as before.
-*/
-function awaitFirstFlagPoll() {
-	if (firstPollSettled || !hasFlagSource()) return Promise.resolve();
-	return firstPollPromise;
+function getPolledFlag(_name) {
+	return contextManagement;
 }
 /**
 * Subscribe to changes of a flag. The callback fires only on a *transition*
@@ -1986,13 +1970,12 @@ function onFlagChange(name, cb) {
 }
 function apply(name, next) {
 	if (next === null) return;
-	const prev = name === "contextManagement" ? contextManagement : subagent;
-	if (name === "contextManagement") contextManagement = next;
-	else subagent = next;
+	const prev = contextManagement;
+	contextManagement = next;
 	if (next !== prev) for (const cb of subscribers[name]) try {
 		cb(next);
 	} catch (err) {
-		log$9.warn({
+		log$10.warn({
 			err,
 			flag: name
 		}, "flag subscriber threw");
@@ -2003,9 +1986,8 @@ async function pollOnce() {
 		const flags = await fetchHarnessFlags();
 		if (!flags) return;
 		apply("contextManagement", flags.contextManagement ?? null);
-		apply("subagent", flags.subagent ?? null);
 	} catch (err) {
-		log$9.debug({ err }, "feature-flag poll threw");
+		log$10.debug({ err }, "feature-flag poll threw");
 	}
 }
 /**
@@ -2112,7 +2094,7 @@ function transformContextMessages(messages, config, now) {
 }
 //#endregion
 //#region src/extensions/context-management.ts
-const log$8 = logger.child({ module: "context-management-extension" });
+const log$9 = logger.child({ module: "context-management-extension" });
 function isAnthropicMessagesPayload(payload) {
 	if (typeof payload !== "object" || payload === null) return false;
 	const candidate = payload;
@@ -2177,13 +2159,13 @@ function createContextManagementExtension() {
 		setContextManagementFlagOverride(getPolledFlag("contextManagement"));
 		onFlagChange("contextManagement", (enabled) => {
 			setContextManagementFlagOverride(enabled);
-			log$8.info({
+			log$9.info({
 				event: "context_management_flag_update",
 				enabled
 			}, "context-management flag updated from platform");
 		});
 		startFeatureFlagPoller();
-		log$8.info({
+		log$9.info({
 			event: "context_management_registered",
 			enabled: initial.enabled,
 			flagSource: hasFlagSource(),
@@ -2195,13 +2177,13 @@ function createContextManagementExtension() {
 			const { messages } = event;
 			try {
 				const result = transformContextIfEnabled(messages, getContextManagementConfig(), Date.now());
-				if (result.stats && (result.stats.clearedResults > 0 || result.stats.trimmedResults > 0)) log$8.info({
+				if (result.stats && (result.stats.clearedResults > 0 || result.stats.trimmedResults > 0)) log$9.info({
 					event: "context_management_applied",
 					...result.stats
 				}, "trimmed/cleared tool output before LLM call");
 				return { messages: result.messages };
 			} catch (err) {
-				log$8.error({
+				log$9.error({
 					err,
 					event: "context_management_transform_failed"
 				}, "context transform failed; passing messages through unchanged");
@@ -2213,7 +2195,7 @@ function createContextManagementExtension() {
 }
 //#endregion
 //#region src/extensions/current-time.ts
-const log$7 = logger.child({ module: "current-time-extension" });
+const log$8 = logger.child({ module: "current-time-extension" });
 const PI_DATE_LINE = /^Current date:.*$/m;
 function formatCurrentTimeLine(now) {
 	return `Current date: ${now.getUTCFullYear()}-${String(now.getUTCMonth() + 1).padStart(2, "0")}-${String(now.getUTCDate()).padStart(2, "0")} (${new Intl.DateTimeFormat("en-US", {
@@ -2226,7 +2208,7 @@ const currentTimeExtension = (pi) => {
 		const line = formatCurrentTimeLine(/* @__PURE__ */ new Date());
 		const base = event.systemPrompt;
 		if (PI_DATE_LINE.test(base)) {
-			log$7.info({ event: "pi_date_line_present" }, "pi base prompt carries its own 'Current date:' line again; replacing it in place (pi prompt format may have changed)");
+			log$8.info({ event: "pi_date_line_present" }, "pi base prompt carries its own 'Current date:' line again; replacing it in place (pi prompt format may have changed)");
 			return { systemPrompt: base.replace(PI_DATE_LINE, line) };
 		}
 		return { systemPrompt: `${base}\n${line}` };
@@ -2463,7 +2445,7 @@ function renderIndex(entries) {
 }
 //#endregion
 //#region src/extensions/memory.ts
-const log$6 = logger.child({ module: "memory-extension" });
+const log$7 = logger.child({ module: "memory-extension" });
 /**
 * The standing instructions for the memory system. Always injected (even with
 * an empty `.memory/`) so the agent knows it can persist notes. `users/` is
@@ -2497,7 +2479,7 @@ const memoryExtension = (pi) => {
 				index
 			});
 		} catch (err) {
-			log$6.warn({
+			log$7.warn({
 				err,
 				event: "memory_index_failed"
 			}, "memory index build failed; injecting instructions only");
@@ -2511,7 +2493,7 @@ const memoryExtension = (pi) => {
 };
 //#endregion
 //#region src/extensions/platform-memory.ts
-const log$5 = logger.child({ module: "platform-memory-extension" });
+const log$6 = logger.child({ module: "platform-memory-extension" });
 /**
 * Resolve the human on this turn via the API, keyed by the message id.
 * `/sandbox/channel-context` only returns a sender for a platform-known
@@ -2524,13 +2506,13 @@ const log$5 = logger.child({ module: "platform-memory-extension" });
 async function resolveTurnUser(messageId) {
 	const client = sandboxClient();
 	if (!client) {
-		log$5.debug({ event: "resolve_turn_user_no_api_url" }, "no API url in env; withholding user memory");
+		log$6.debug({ event: "resolve_turn_user_no_api_url" }, "no API url in env; withholding user memory");
 		return null;
 	}
 	try {
 		const res = await client["channel-context"].$get({ query: { messageId } });
 		if (!res.ok) {
-			log$5.warn({
+			log$6.warn({
 				event: "resolve_turn_user_failed",
 				status: res.status
 			}, "channel-context returned non-ok; withholding user memory");
@@ -2543,7 +2525,7 @@ async function resolveTurnUser(messageId) {
 			displayName: sender.displayName
 		};
 	} catch (err) {
-		log$5.warn({
+		log$6.warn({
 			err,
 			event: "resolve_turn_user_failed"
 		}, "failed to resolve current user; withholding user memory");
@@ -2590,7 +2572,7 @@ function createPlatformMemoryExtension({ channelContext }) {
 					user
 				});
 			} catch (err) {
-				log$5.warn({
+				log$6.warn({
 					err,
 					event: "user_memory_index_failed"
 				}, "user memory index build failed; skipping injection");
@@ -2605,7 +2587,7 @@ function createPlatformMemoryExtension({ channelContext }) {
 }
 //#endregion
 //#region src/extensions/self-trace.ts
-const log$4 = logger.child({ module: "self-trace-extension" });
+const log$5 = logger.child({ module: "self-trace-extension" });
 /**
 * Reports the agent's own execution as OpenTelemetry spans:
 * agent.session → agent.run → agent.turn.N → tool.NAME, with token/cost
@@ -2630,7 +2612,7 @@ const selfTraceExtension = (pi) => {
 		sessionSpan = tracer.startSpan("agent.session", { attributes: { "agent.model": modelId } }, remoteCtx);
 		sessionCtx = trace.setSpan(remoteCtx, sessionSpan);
 		const sc = sessionSpan.spanContext();
-		log$4.info({
+		log$5.info({
 			event: "self_trace_session_start",
 			trace_id: sc.traceId,
 			span_id: sc.spanId,
@@ -2742,13 +2724,13 @@ const selfTraceExtension = (pi) => {
 * Lives in the harness package — soul.md is content from the agent's
 * own git repo, not from the platform — so its handling stays here.
 */
-const log$3 = logger.child({ module: "soul-extension" });
+const log$4 = logger.child({ module: "soul-extension" });
 async function readSoul(cwd) {
 	try {
 		return (await readFile(join(cwd, "soul.md"), "utf8")).trim() || null;
 	} catch (err) {
 		if (err?.code === "ENOENT") return null;
-		log$3.warn({
+		log$4.warn({
 			err,
 			event: "soul_read_failed"
 		}, "soul.md read failed");
@@ -2762,7 +2744,7 @@ function soulSection(cwd, soul) {
 
 **\`soul.md\` is where behavior lives.** Any standing instruction about how you should act — a rule a user wants you to follow going forward, a tone or format preference, a workflow convention, a "from now on, always/never …" — belongs here, not in \`.memory/\`. Memory records *what happened* (facts, events, findings); soul defines *how you behave*. When a user gives you a durable behavioral rule, write it to \`soul.md\`. If you find behavioral rules that ended up in \`.memory/\`, treat that as misfiled and move them here.
 
-Keep it current. When you gain a durable new capability — a tool you build, a skill or integration you set up, a service you connect — or a user hands you a lasting behavioral rule, record it in \`soul.md\` so a future conversation knows it's part of you rather than rediscovering it from scratch. Edit it (then \`git add soul.md && git commit && git push\`) to redefine yourself; picked up on the next message.
+Keep it current. When you gain a durable new capability — a tool you build, a skill or integration you set up, a service you connect, a secret or auth credential you wire in — or a user hands you a lasting behavioral rule, record it in \`soul.md\` so a future conversation knows it's part of you rather than rediscovering it from scratch. Do this the moment you gain the capability, and for a credential that means the moment it verifies with a real call, not after a human points out that you forgot. Connecting a capability is itself a durable change worth recording, not merely a step toward the task in front of you. Edit \`soul.md\` (then \`git add soul.md && git commit && git push\`) to redefine yourself; picked up on the next message.
 
 ${soul ? soul : "_(empty — write to `soul.md` to define your persona)_"}`;
 }
@@ -2780,8 +2762,7 @@ const soulExtension = (pi) => {
 };
 //#endregion
 //#region src/extensions/subagent/index.ts
-const log$2 = logger.child({ module: "subagent-ext" });
-const COLD_START_FLAG_WAIT_MS = 750;
+const log$3 = logger.child({ module: "subagent-ext" });
 const MAX_TASKS = 8;
 const TaskItem = Type.Object({
 	task: Type.String({ description: "The task to delegate to a subagent run." }),
@@ -2790,8 +2771,14 @@ const TaskItem = Type.Object({
 		maxLength: 120
 	}),
 	persona: Type.Optional(Type.String({ description: "Optional extra system prompt / role for this task, applied ON TOP of the child run's own default persona (your full identity and soul are still there underneath). Omit to run with just your default persona." })),
-	model: Type.Optional(Type.String({ description: "Optional model id to run this subagent on (e.g. \"anthropic/claude-opus-4-8\"). Must be a real catalogued model. Omit to run on your own model. If you are locked to a Google-compliant model, only compliant models are accepted." }))
+	model: Type.Optional(Type.String({ description: "Optional model id to run this subagent on. PREFER A LOWER-COST, FASTER MODEL when the task is well-scoped and does not need your full reasoning depth — most delegated subtasks (searching, summarizing, mechanical edits, gathering or reformatting data, running a check) run just as well on a lighter model and cost far less. Reserve a top-tier model for subtasks that genuinely need deep reasoning or careful judgment. Must be a real catalogued model id. Omit to inherit your own model. If you are locked to a Google-compliant model, only compliant models are accepted." })),
+	timeoutMinutes: Type.Optional(Type.Integer({
+		description: "Optional wall-clock timeout for this subagent, in minutes. If the run is still going after this long it is ended and you are rewoken with a timeout result, so a hung subagent can never strand you. Omit for the default (30 minutes). Raise it for genuinely long work (a big migration, a large audit); lower it for a quick lookup. Range 1-360.",
+		minimum: 1,
+		maximum: 360
+	}))
 });
+const DEFAULT_SUBAGENT_TIMEOUT_MS = 30 * 6e4;
 const SubagentParams = Type.Object({ tasks: Type.Array(TaskItem, {
 	description: "One or more tasks to delegate. Each spawns an isolated subagent run linked to this conversation; they run in parallel and each rewakes you with its result when it finishes.",
 	minItems: 1,
@@ -2806,7 +2793,8 @@ function buildTool(messageId) {
 			"Delegate one or more tasks to subagent runs — fresh isolated copies of yourself, each with its own context window, linked to this conversation.",
 			"Use it to parallelize independent work, to keep a large or noisy subtask out of your own context, or to run a task under a specialized persona.",
 			"Fire-and-forget: this returns immediately after queueing. It does NOT wait for results. Each subagent runs on its own and, when it finishes, sends you its result on this thread — so queue the work, then keep going or end your turn. To chain, re-delegate after a result lands.",
-			"Pass tasks: [{ task, title, persona?, model? }]. title is a short 3-6 word name for the task — it is shown to the person in the chat as that subagent's row, so name the work rather than restating the prompt. persona is an optional extra system prompt layered ON TOP of your default persona for that task (it adds to, it does not replace, your identity); omit it to run with just your default persona. model is an optional model id for that task; omit it to run on your own model."
+			"Pass tasks: [{ task, title, persona?, model? }]. title is a short 3-6 word name for the task — it is shown to the person in the chat as that subagent's row, so name the work rather than restating the prompt. persona is an optional extra system prompt layered ON TOP of your default persona for that task (it adds to, it does not replace, your identity); omit it to run with just your default persona. model is an optional model id for that task — prefer a lower-cost, faster model for well-scoped subtasks that don't need deep reasoning, and reserve a top-tier model for the ones that do; omit it to inherit your own model.",
+			"Peering: each queued task comes back with its own conversation id. A subagent is a real linked conversation, so to see what one is doing RIGHT NOW while it runs — its reasoning, the tools it has called and their results, its progress — read that conversation with `platform conversations show <conversationId>` (you are already authorized; it is your own delegated run). Check in that way instead of waiting blind for the final result. The read reflects the child's persisted state, which lags a few seconds behind live (tool results land as they complete; in-progress reasoning can be up to ~5s stale), so peek between checkpoints rather than polling in a tight loop."
 		].join(" "),
 		promptSnippet: "subagent — delegate tasks to isolated subagent runs; each rewakes you with its result when done",
 		parameters: SubagentParams,
@@ -2824,28 +2812,39 @@ function buildTool(messageId) {
 				task: t.task,
 				title: t.title ?? null,
 				persona: t.persona ?? null,
-				model: t.model ?? null
+				model: t.model ?? null,
+				timeoutMs: t.timeoutMinutes != null ? t.timeoutMinutes * 6e4 : DEFAULT_SUBAGENT_TIMEOUT_MS
 			}));
 			try {
-				const { taskIds } = await postSubagentSpawn({
+				const spawned = await postSubagentSpawn({
 					messageId,
 					tasks: spawnTasks
 				});
-				log$2.info({
+				const { taskIds } = spawned;
+				log$3.info({
 					event: "subagent_spawned",
 					count: taskIds.length
 				}, "subagent tasks queued");
-				const lines = taskIds.map((id, i) => `- ${id}: ${spawnTasks[i]?.title ?? spawnTasks[i]?.task ?? ""}`).join("\n");
+				const convByTask = new Map(spawned.tasks.map((t) => [t.taskId, t.conversationId]));
+				const lines = taskIds.map((id, i) => {
+					const label = spawnTasks[i]?.title ?? spawnTasks[i]?.task ?? "";
+					const conv = convByTask.get(id);
+					return `- ${id}: ${label}${conv ? ` — peek: conversations show ${conv}` : ""}`;
+				}).join("\n");
+				const peerHint = spawned.tasks.length ? "\nTo see what a subagent is doing while it runs, read its conversation with `platform conversations show <conversationId>` (shown per task above)." : "";
 				return {
 					content: [{
 						type: "text",
-						text: `Queued ${taskIds.length} subagent ${taskIds.length === 1 ? "run" : "runs"}. Each runs on its own and will send you its result on this thread when it finishes — keep working or end your turn meanwhile.\n${lines}`
+						text: `Queued ${taskIds.length} subagent ${taskIds.length === 1 ? "run" : "runs"}. Each runs on its own and will send you its result on this thread when it finishes — keep working or end your turn meanwhile.\n${lines}${peerHint}`
 					}],
-					details: { taskIds }
+					details: {
+						taskIds,
+						tasks: spawned.tasks
+					}
 				};
 			} catch (err) {
 				const message = err instanceof Error ? err.message : String(err);
-				log$2.warn({
+				log$3.warn({
 					err,
 					event: "subagent_spawn_failed"
 				}, "subagent spawn failed");
@@ -2862,39 +2861,249 @@ function buildTool(messageId) {
 	};
 }
 /**
-* Gated on `harness-subagent-enabled`, read from the shared feature-flag poll.
 * The factory takes the session's channel context to resolve the originating
 * messageId — the api links each spawned run to the conversation that message
 * belongs to and rewakes it on completion (nothing about the parent is piped
-* from the sandbox beyond that id).
+* from the sandbox beyond that id). The tool is registered unconditionally at
+* session_start.
 */
 function createSubagentExtension({ channelContext }) {
 	return (pi) => {
 		const messageId = extractMessageId(channelContext);
-		startFeatureFlagPoller();
 		let registered = false;
 		const registerOnce = () => {
 			if (registered) return;
 			registered = true;
 			pi.registerTool(buildTool(messageId));
-			log$2.info({ event: "subagent_enabled" }, "subagent tool registered");
+			log$3.info({ event: "subagent_enabled" }, "subagent tool registered");
 		};
-		onFlagChange("subagent", (enabled) => {
-			if (enabled) registerOnce();
-		});
-		pi.on("session_start", async () => {
-			if (getPolledFlag("subagent") === null) await Promise.race([awaitFirstFlagPoll(), new Promise((resolve) => setTimeout(resolve, COLD_START_FLAG_WAIT_MS).unref?.())]);
-			if (getPolledFlag("subagent") === true) registerOnce();
+		pi.on("session_start", () => {
+			registerOnce();
 		});
 	};
 }
 //#endregion
+//#region src/extensions/resource-pressure-warning.ts
+/**
+* Mid-run resource-pressure warning to the agent.
+*
+* The sandbox already detects pressure — the boot scripts cap the
+* user-workload cgroup (memory.high/memory.max) and watchers log warn/crit
+* edges for memory and disk — but nothing told the *agent*, so a turn burned
+* straight to the OOM kill (or a full disk) and only learned about it from
+* the post-mortem notice. This extension closes that gap in-process: while a
+* turn is active it polls the agent cgroup and the root filesystem and, the
+* first time usage crosses a warn threshold, folds a system notification into
+* the open turn so the agent can checkpoint, shed work (constrain
+* parallelism, kill a background hog, clean scratch space), or request a
+* bigger tier BEFORE the kill.
+*
+* The notification is triggered by the two conditions that actually kill
+* work — memory near the cgroup hard cap, disk near full — and reports a
+* snapshot of all the relevant stats (memory, CPU utilization, disk) so the
+* agent can tell which resource is the problem and how much headroom the
+* others have.
+*
+* Edge-triggered, once per trigger per turn: the fired flags reset on
+* agent_start, so a turn that rides a threshold gets one warning per
+* resource, not a stream. Polling only runs while the agent is active — an
+* idle sandbox's resource usage is not the agent's problem and there is no
+* open turn to deliver into anyway.
+*
+* Best-effort throughout: any read failure (cgroup absent, controller not
+* delegated, non-cgroup-v2 host, df missing) reads as "no signal" for that
+* stat and the extension warns on what it can see — it must never break a
+* turn over an observability feature.
+*/
+const execFileAsync = promisify(execFile);
+const log$2 = logger.child({ module: "resource-pressure-warning" });
+const POLL_INTERVAL_MS = 1e4;
+function envOverride(name) {
+	for (const prefix of ["SKYDIVE_", "ANYONE_"]) {
+		const value = process.env[`${prefix}${name}`];
+		if (value != null && value !== "") return value;
+	}
+	return null;
+}
+function cgroupDir() {
+	return envOverride("AGENT_CGROUP") ?? "/sys/fs/cgroup/agent";
+}
+function diskRoot() {
+	return envOverride("DISK_ROOT") ?? "/";
+}
+/**
+* Read a cgroup v2 scalar file. Returns a number, or null for "max"
+* (uncapped), an empty/absent file, or any read/parse error — an uncapped or
+* unreadable limit means there is nothing meaningful to warn against.
+*/
+async function readScalar(file) {
+	try {
+		const raw = (await readFile(`${cgroupDir()}/${file}`, "utf8")).trim();
+		if (raw === "" || raw === "max") return null;
+		const n = Number(raw);
+		return Number.isFinite(n) ? n : null;
+	} catch (_error) {
+		return null;
+	}
+}
+/**
+* Read a cgroup v2 "flat keyed" file (one `key value` pair per line, e.g.
+* cpu.stat) and return the counter for `key`, or null when absent.
+*/
+async function readKeyedCounter(file, key) {
+	try {
+		const raw = await readFile(`${cgroupDir()}/${file}`, "utf8");
+		for (const line of raw.split("\n")) {
+			const [k, v] = line.trim().split(/\s+/);
+			if (k === key) {
+				const n = Number(v);
+				return Number.isFinite(n) ? n : null;
+			}
+		}
+		return null;
+	} catch (_error) {
+		return null;
+	}
+}
+/**
+* Live memory usage as an integer percent of the hard cap, or null when
+* either side is unreadable/uncapped. Exported for tests.
+*/
+async function readMemUsePct() {
+	const [current, max] = await Promise.all([readScalar("memory.current"), readScalar("memory.max")]);
+	if (current === null || max === null || max <= 0) return null;
+	return {
+		pct: Math.floor(current / max * 100),
+		currentBytes: current,
+		maxBytes: max
+	};
+}
+/**
+* Root filesystem used% (df -P Capacity column), or null on any failure.
+* Exported for tests.
+*/
+async function readDiskUsePct() {
+	try {
+		const { stdout } = await execFileAsync("df", ["-P", diskRoot()]);
+		const dataRow = stdout.trim().split("\n")[1];
+		if (dataRow == null) return null;
+		const capacity = dataRow.trim().split(/\s+/)[4];
+		if (capacity == null) return null;
+		const pct = Number(capacity.replace("%", ""));
+		return Number.isFinite(pct) ? pct : null;
+	} catch (_error) {
+		return null;
+	}
+}
+/**
+* CPU utilization sampler. cgroup v2 exposes cumulative CPU time
+* (cpu.stat usage_usec); utilization is the delta between two samples over
+* the wall time between them, normalized by core count. The first call after
+* construction has no previous sample and returns null.
+*/
+function createCpuSampler() {
+	let prevUsageUsec = null;
+	let prevAtMs = null;
+	return async () => {
+		const usage = await readKeyedCounter("cpu.stat", "usage_usec");
+		const now = Date.now();
+		const prev = prevUsageUsec;
+		const prevAt = prevAtMs;
+		prevUsageUsec = usage;
+		prevAtMs = now;
+		if (usage === null || prev === null || prevAt === null) return null;
+		const wallUsec = (now - prevAt) * 1e3;
+		if (wallUsec <= 0) return null;
+		const cores = availableParallelism();
+		const pct = Math.round((usage - prev) / (wallUsec * cores) * 100);
+		return Math.max(0, Math.min(100, pct));
+	};
+}
+function fmtMb(bytes) {
+	return Math.round(bytes / 1024 / 1024);
+}
+/** The model-facing warning text. Exported for tests. */
+function resourcePressureWarningText(trigger, { mem, cpuPct, diskPct }) {
+	const stats = [];
+	if (mem) stats.push(`memory ${mem.pct}% of cap (${fmtMb(mem.currentBytes)}/${fmtMb(mem.maxBytes)} MB)`);
+	if (cpuPct !== null) stats.push(`CPU ${cpuPct}%`);
+	if (diskPct !== null) stats.push(`disk ${diskPct}% full`);
+	const lead = trigger === "memory" ? `Your sandbox is at ${mem?.pct}% of its memory cap. If usage keeps climbing, the kernel will kill the offending process and this turn may die with it.` : `Your sandbox's disk is ${diskPct}% full. If it fills completely, writes will start failing and this turn may die with them.`;
+	const remedy = trigger === "memory" ? "checkpoint in-flight work (commit and push), then reduce the footprint — constrain parallelism, run heavy steps sequentially, or kill background processes you no longer need." : "checkpoint in-flight work (commit and push), then free space — clean build artifacts, caches, and scratch files you no longer need.";
+	return `<system_notification>${lead} Current usage: ${stats.join(", ")}. Act now: ${remedy} If the workload genuinely needs more resources, request a bigger sandbox with \`platform compute request\`. This is an automated resource warning, not a message from the user; continue the task, adjusted.</system_notification>`;
+}
+const resourcePressureWarningExtension = (pi) => {
+	let agentActive = false;
+	let warnedMemThisTurn = false;
+	let warnedDiskThisTurn = false;
+	let timer = null;
+	const sampleCpu = createCpuSampler();
+	async function checkOnce() {
+		if (!agentActive || warnedMemThisTurn && warnedDiskThisTurn) return;
+		const [mem, cpuPct, diskPct] = await Promise.all([
+			readMemUsePct(),
+			sampleCpu(),
+			readDiskUsePct()
+		]);
+		let trigger = null;
+		if (!warnedMemThisTurn && mem !== null && mem.pct >= 80) {
+			trigger = "memory";
+			warnedMemThisTurn = true;
+		} else if (!warnedDiskThisTurn && diskPct !== null && diskPct >= 80) {
+			trigger = "disk";
+			warnedDiskThisTurn = true;
+		}
+		if (trigger === null) return;
+		log$2.warn({
+			trigger,
+			mem,
+			cpuPct,
+			diskPct
+		}, "resource pressure warning delivered to agent");
+		await pi.sendMessage({
+			customType: "anyone-resource-pressure-warning",
+			content: resourcePressureWarningText(trigger, {
+				mem,
+				cpuPct,
+				diskPct
+			}),
+			display: false
+		}, {
+			triggerTurn: true,
+			deliverAs: "followUp"
+		});
+	}
+	pi.on("agent_start", async () => {
+		agentActive = true;
+		warnedMemThisTurn = false;
+		warnedDiskThisTurn = false;
+		if (!timer) {
+			timer = setInterval(() => {
+				checkOnce().catch((err) => {
+					log$2.error({ err }, "resource pressure check failed");
+				});
+			}, POLL_INTERVAL_MS);
+			timer.unref?.();
+		}
+	});
+	pi.on("agent_end", async () => {
+		agentActive = false;
+		if (timer) {
+			clearInterval(timer);
+			timer = null;
+		}
+	});
+};
+//#endregion
 //#region src/extensions/tool-call-env.ts
 const TOOL_CALL_ID_VAR = "TOOL_CALL_ID";
+function shellQuoteValue(value) {
+	return quote([value]);
+}
 function withToolCallId({ command, toolCallId }) {
-	return `export ${TOOL_CALL_ID_VAR}=${toolCallId}; ${command}`;
+	return `export ${TOOL_CALL_ID_VAR}=${shellQuoteValue(toolCallId)}; ${command}`;
 }
-const PLATFORM_EXPORT = new RegExp(`^\\s*export\\s+(?:${TOOL_CALL_ID_VAR}|ANYONE_\\w+|SKYDIVE_\\w+)=(?:"(?:\\\\.|[^"])*"|'[^']*'|[^;\\s]*)\\s*;\\s*`);
+const PLATFORM_EXPORT = new RegExp(`^\\s*export\\s+(?:${TOOL_CALL_ID_VAR}|ANYONE_\\w+|SKYDIVE_\\w+)=(?:"(?:\\\\.|[^"])*"|'(?:'\\\\''|[^'])*'|[^;\\s]*)\\s*;\\s*`);
 function stripPlatformExportsForDisplay(command) {
 	let c = command;
 	let m;
@@ -3659,7 +3868,8 @@ function platformExtensions({ sessionId, channelContext }) {
 		selfTraceExtension,
 		createBackgroundTasksExtension({ channelContext }),
 		createSubagentExtension({ channelContext }),
-		createContextManagementExtension()
+		createContextManagementExtension(),
+		resourcePressureWarningExtension
 	];
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skydiveai/pi-extensions",
-  "version": "0.1.0-beta.76",
+  "version": "0.1.0-beta.763",
   "homepage": "https://skydive.com",
   "license": "MIT",
   "author": "Create, Inc.",
@@ -17,12 +17,6 @@
   },
   "publishConfig": {
     "access": "public",
-    "exports": {
-      ".": {
-        "types": "./dist/index.d.mts",
-        "default": "./dist/index.mjs"
-      }
-    },
     "registry": "https://registry.npmjs.org"
   },
   "scripts": {
@@ -45,6 +39,7 @@
     "@skydiveai/pi-server": "^0.1.0",
     "hono": "^4.6.14",
     "pino": "^9.6.0",
+    "shell-quote": "^1.8.4",
     "typebox": "^1.1.34",
     "yaml": "^2.8.3",
     "zod": "^3.25.0"