@skydiveai/pi-extensions 0.1.0-beta.88 → 0.1.0-beta.882

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");
@@ -1679,20 +1683,77 @@ function apiBaseUrl() {
 }
 //#endregion
 //#region src/extensions/platform.ts
+/**
+* Platform extension — bridges the agent harness to the Skydive platform daemon.
+*
+* Responsibilities:
+* - Heartbeat: periodic POST to the API so the sandbox manager knows the
+*   agent is alive. Throttled to once per minute, triggered by tool events.
+* - Session tracking: registers the session with the daemon on start,
+*   streams tool_call / tool_result events so the daemon can track which
+*   session is actively executing, and signals session end on agent_end.
+* - Channel context: passes the SKYDIVE_CHANNEL_CONTEXT (containing the
+*   messageId) to the daemon so file writes can be attributed to the
+*   correct conversation.
+*
+* All daemon POSTs are fire-and-forget — failures are logged but never
+* block the agent. The daemon may not be running (e.g. local dev without
+* a sandbox), and that's fine.
+*/
 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
-* null when indeterminate (no api url, or the request failed) so the shared
+* Is this box still an unclaimed warm-pool sandbox? (ANY-6000, the
+* feature-flags half of the ANY-5184 pool 403 wave.)
+*
+* `GET /sandbox/feature-flags` is agent-only, so the shared poller's request
+* from a pool box can only 403 — a guaranteed-failing GET every 60s for the
+* life of the pool phase. The discriminator is the sandbox token's `type`
+* claim, read UNVERIFIED (this box never holds the signing secret): not an
+* authorization decision, only "should I bother calling?", and the api still
+* authorizes every request.
+*
+* Read per call from the daemon's persisted env file, NOT process.env:
+* claiming a pool box rebinds the token in place (the daemon rewrites this
+* file) while the harness's process.env keeps the boot snapshot, so a
+* process-env gate would leave a claimed box permanently skipping — trading a
+* wasted request for silently frozen flags, which is strictly worse. "Cannot
+* tell" (no file, no token, unparseable payload) reports false so the poll
+* proceeds.
+*/
+const daemonEnvIdentitySchema = z.object({
+	ANYONE_SANDBOX_TOKEN: z.string().optional(),
+	SKYDIVE_SANDBOX_TOKEN: z.string().optional()
+}).passthrough();
+const tokenTypeSchema = z.object({ type: z.string() }).passthrough();
+async function isPoolIdentity() {
+	try {
+		const envFile = process.env.ANYONE_DAEMON_ENV_CACHE ?? "/tmp/.anyone/daemon-env.json";
+		const env = daemonEnvIdentitySchema.safeParse(JSON.parse(await readFile(envFile, "utf8")));
+		if (!env.success) return false;
+		const token = env.data.ANYONE_SANDBOX_TOKEN ?? env.data.SKYDIVE_SANDBOX_TOKEN;
+		if (typeof token !== "string" || token === "") return false;
+		const payload = token.split(".")[1];
+		if (!payload) return false;
+		const claims = tokenTypeSchema.safeParse(JSON.parse(Buffer.from(payload, "base64url").toString("utf8")));
+		return claims.success && claims.data.type === "onboarding-pool";
+	} catch (_err) {
+		return false;
+	}
+}
+/**
+* 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, the request failed, or the box is an
+* unclaimed pool sandbox whose token the route would 403) 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
 * polled values there instead of issuing their own GET.
@@ -1700,22 +1761,19 @@ function sandboxClient() {
 async function fetchHarnessFlags() {
 	const client = sandboxClient();
 	if (!client) return null;
+	if (await isPoolIdentity()) return null;
 	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 +1784,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 +1796,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 +1805,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 +1830,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 +1883,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 +1914,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 +1923,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 +1972,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 +1983,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 +2014,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 +2028,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 +2044,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 +2152,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 +2217,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 +2235,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 +2253,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 +2266,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 +2503,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 +2537,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 +2551,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 +2564,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 +2583,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 +2630,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 +2645,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 +2670,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 +2782,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 +2802,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 +2820,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 +2829,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 +2851,9 @@ 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.",
+			"Steering: to add context, correct course, or answer a question a subagent needs mid-run, post to its conversation with `platform conversations post <conversationId> --message \"...\"`. If the subagent is still running, your message lands as a live steer picked up in that same turn; if it has gone idle, it queues as its next turn. This is the same primitive as any conversation message — there is no separate steer channel."
 		].join(" "),
 		promptSnippet: "subagent — delegate tasks to isolated subagent runs; each rewakes you with its result when done",
 		parameters: SubagentParams,
@@ -2824,28 +2871,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 ? ` — conversation ${conv}` : ""}`;
+				}).join("\n");
+				const peerHint = spawned.tasks.length ? "\nEach subagent runs on its own conversation (id shown per task above). To SEE what one is doing while it runs, read it with `platform conversations show <conversationId>`. To STEER one mid-run — add context, correct course, answer a question — post to its conversation with `platform conversations post <conversationId> --message \"...\"`; it lands as a live steer if the subagent is still running, or as its next turn if it has gone idle." : "";
 				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 +2920,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 +3927,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.88",
+  "version": "0.1.0-beta.882",
   "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"