@skydiveai/pi-extensions 0.1.0-beta.41 → 0.1.0-beta.413

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,
@@ -1921,20 +1918,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 +1936,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 +1963,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 +1975,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 +1992,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 +2737,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 +2759,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 +2786,7 @@ 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."
 		].join(" "),
 		promptSnippet: "subagent — delegate tasks to isolated subagent runs; each rewakes you with its result when done",
 		parameters: SubagentParams,
@@ -2791,8 +2802,10 @@ 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({
@@ -2803,7 +2816,7 @@ function buildTool(messageId) {
 					event: "subagent_spawned",
 					count: taskIds.length
 				}, "subagent tasks queued");
-				const lines = taskIds.map((id, i) => `- ${id}: ${spawnTasks[i]?.task ?? ""}`).join("\n");
+				const lines = taskIds.map((id, i) => `- ${id}: ${spawnTasks[i]?.title ?? spawnTasks[i]?.task ?? ""}`).join("\n");
 				return {
 					content: [{
 						type: "text",
@@ -2830,31 +2843,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.41",
+  "version": "0.1.0-beta.413",
   "homepage": "https://skydive.com",
   "license": "MIT",
   "author": "Create, Inc.",
@@ -45,6 +45,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"