@skydiveai/pi-extensions 0.1.0-beta.6 → 0.1.0-beta.601

package/dist/index.mjs

@@ -21,6 +21,7 @@ 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 { quote } from "shell-quote";
 import { createWriteStream } from "node:fs";
 import { finished } from "node:stream/promises";
 import { createLocalBashOperations } from "@earendil-works/pi-coding-agent";
@@ -1690,8 +1691,8 @@ function sandboxClient() {
 	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
@@ -1709,11 +1710,7 @@ async function fetchHarnessFlags() {
 			}, "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({
 			err,
@@ -1772,7 +1769,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;
@@ -1921,20 +1922,16 @@ 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
@@ -1943,15 +1940,21 @@ function createPlatformExtensions({ sessionId, channelContext }) {
 const log$9 = 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;
+new Promise((resolve) => {
+	resolveFirstPoll = resolve;
+});
+function markFirstPollSettled() {
+	if (firstPollSettled) return;
+	firstPollSettled = true;
+	resolveFirstPoll?.();
+}
 /** Last-polled value of a flag, or `null` if not yet resolved. */
-function getPolledFlag(name) {
-	return name === "contextManagement" ? contextManagement : subagent;
+function getPolledFlag(_name) {
+	return contextManagement;
 }
 /**
 * Subscribe to changes of a flag. The callback fires only on a *transition*
@@ -1964,9 +1967,8 @@ 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) {
@@ -1977,10 +1979,13 @@ function apply(name, next) {
 	}
 }
 async function pollOnce() {
-	const flags = await fetchHarnessFlags();
-	if (!flags) return;
-	apply("contextManagement", flags.contextManagement ?? null);
-	apply("subagent", flags.subagent ?? null);
+	try {
+		const flags = await fetchHarnessFlags();
+		if (!flags) return;
+		apply("contextManagement", flags.contextManagement ?? null);
+	} catch (err) {
+		log$9.debug({ err }, "feature-flag poll threw");
+	}
 }
 /**
 * Start the shared background poll (idempotent). No-op when there's no
@@ -1991,7 +1996,7 @@ async function pollOnce() {
 function startFeatureFlagPoller() {
 	if (pollerStarted || !hasFlagSource()) return;
 	pollerStarted = true;
-	pollOnce();
+	pollOnce().finally(markFirstPollSettled);
 	setInterval(() => void pollOnce(), FLAG_POLL_INTERVAL_MS).unref?.();
 }
 //#endregion
@@ -2736,7 +2741,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)_"}`;
 }
@@ -2758,9 +2763,19 @@ const log$2 = 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." }),
+	title: Type.String({
+		description: "A SHORT name for this task — 3-6 words, sentence case, no trailing period. This is what the person in the chat sees as the row for this subagent, so name the work, do not restate the prompt. Good: \"Audit the billing gate\", \"Compare competitor pricing\", \"Draft the migration\". Bad: \"You are looking at apps/anyone/web and should check every component…\".",
+		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,
@@ -2775,7 +2790,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, persona?, model? }]. 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,
@@ -2791,25 +2807,37 @@ function buildTool(messageId) {
 			};
 			const spawnTasks = tasks.map((t) => ({
 				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
 				});
+				const { taskIds } = spawned;
 				log$2.info({
 					event: "subagent_spawned",
 					count: taskIds.length
 				}, "subagent tasks queued");
-				const lines = taskIds.map((id, i) => `- ${id}: ${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);
@@ -2830,31 +2858,37 @@ 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();
-		pi.on("session_start", async () => {
-			if (getPolledFlag("subagent") === true) {
-				pi.registerTool(buildTool(messageId));
-				log$2.info({ event: "subagent_enabled" }, "subagent tool registered");
-			}
+		let registered = false;
+		const registerOnce = () => {
+			if (registered) return;
+			registered = true;
+			pi.registerTool(buildTool(messageId));
+			log$2.info({ event: "subagent_enabled" }, "subagent tool registered");
+		};
+		pi.on("session_start", () => {
+			registerOnce();
 		});
 	};
 }
 //#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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skydiveai/pi-extensions",
-  "version": "0.1.0-beta.6",
+  "version": "0.1.0-beta.601",
   "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"