@skydiveai/pi-extensions 0.1.0-beta.14 → 0.1.0-beta.142

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";
@@ -1949,11 +1950,33 @@ const subscribers = {
 	subagent: /* @__PURE__ */ new Set()
 };
 let pollerStarted = false;
+let firstPollSettled = false;
+let resolveFirstPoll = null;
+const firstPollPromise = 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;
 }
 /**
+* 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;
+}
+/**
 * Subscribe to changes of a flag. The callback fires only on a *transition*
 * (skipped while the value is unchanged), so a subscriber registered before the
 * first poll still learns the initial value. Returns an unsubscribe fn.
@@ -1977,10 +2000,14 @@ 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);
+		apply("subagent", flags.subagent ?? 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 +2018,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 +2763,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)_"}`;
 }
@@ -2755,9 +2782,14 @@ 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 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." }))
 });
@@ -2775,7 +2807,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; omit it to run on your own model."
 		].join(" "),
 		promptSnippet: "subagent — delegate tasks to isolated subagent runs; each rewakes you with its result when done",
 		parameters: SubagentParams,
@@ -2791,6 +2823,7 @@ function buildTool(messageId) {
 			};
 			const spawnTasks = tasks.map((t) => ({
 				task: t.task,
+				title: t.title ?? null,
 				persona: t.persona ?? null,
 				model: t.model ?? null
 			}));
@@ -2803,7 +2836,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",
@@ -2840,21 +2873,32 @@ 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");
+		};
+		onFlagChange("subagent", (enabled) => {
+			if (enabled) registerOnce();
+		});
 		pi.on("session_start", async () => {
-			if (getPolledFlag("subagent") === true) {
-				pi.registerTool(buildTool(messageId));
-				log$2.info({ event: "subagent_enabled" }, "subagent tool registered");
-			}
+			if (getPolledFlag("subagent") === null) await Promise.race([awaitFirstFlagPoll(), new Promise((resolve) => setTimeout(resolve, COLD_START_FLAG_WAIT_MS).unref?.())]);
+			if (getPolledFlag("subagent") === true) 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.14",
+  "version": "0.1.0-beta.142",
   "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"