@arhen/pi-core-subagent 1.3.7 → 1.3.9

package/README.md

@@ -241,6 +241,7 @@ Background (default) + intercom — the run returns a runId immediately; you sta
 | `subagent_result` | full output of a run or one task |
 | `await_subagent` | block until a run finishes (optional `timeoutMs`) |
 | `reply_subagent` | answer a child's `ask_parent` question |
+| `steer_subagent` | inject a steering message into a running child's session (queues as steer if mid-turn; lands at its next model boundary) |
 | `subagent_cancel` | abort a running/queued run |
 
 ### Per-task fields

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arhen/pi-core-subagent",
-	"version": "1.3.7",
+	"version": "1.3.9",
 	"type": "module",
 	"description": "pi extension: fast in-process subagents with a dependency-graph scheduler (needs edges gate tasks and carry upstream output into dependent prompts), plus background runs, intercom and agent-to-agent mailbox. Leader defines agents inline.",
 	"license": "MIT",

package/src/index.ts

@@ -33,6 +33,7 @@ import {
 	ReplyParam,
 	ResultParam,
 	RunIdParam,
+	SteerParam,
 	SubagentParams,
 	type SubagentParamsShape,
 } from "./schemas.ts";
@@ -76,7 +77,8 @@ export default function (pi: ExtensionAPI) {
 		);
 	};
 	pi.registerCommand("subagents", {
-		description: "List subagent runs. `/subagents peek` opens the browsable pane; `/subagents auto-bg on|off` toggles background-by-default.",
+		description:
+			"List subagent runs. `/subagents peek` opens the browsable pane; `/subagents auto-bg on|off` toggles background-by-default.",
 		handler: async (args, ctx) => {
 			const arg = String(args ?? "")
 				.trim()
@@ -86,9 +88,15 @@ export default function (pi: ExtensionAPI) {
 				const value = arg.split(/\s+/)[1];
 				if (value === "on" || value === "off") {
 					const next = manager.setAutoBg(value === "on");
-					ctx.ui.notify(`auto-bg ${next ? "on" : "off"} — subagent calls default to ${next ? "background" : "blocking (inline result)"}.`, "info");
+					ctx.ui.notify(
+						`auto-bg ${next ? "on" : "off"} — subagent calls default to ${next ? "background" : "blocking (inline result)"}.`,
+						"info",
+					);
 				} else {
-					ctx.ui.notify(`auto-bg is ${manager.autoBgOn ? "on" : "off"} — use \`/subagents auto-bg on|off\` to change it.`, "info");
+					ctx.ui.notify(
+						`auto-bg is ${manager.autoBgOn ? "on" : "off"} — use \`/subagents auto-bg on|off\` to change it.`,
+						"info",
+					);
 				}
 				return;
 			}
@@ -128,7 +136,7 @@ export default function (pi: ExtensionAPI) {
 		// ponytail: this string is billed on every request. No example block — an example
 		// biases the model toward one shape; guidelines + JSON schema describe all of them.
 		description:
-			'Run isolated subagents (own context, own session). You invent each agent: name, optional system prompt, toolset (read-only default, write:true to edit). Use `agent`+`task` for one, `tasks` for many. `needs` declares dependency edges: a task waits for its needs and receives their outputs prepended to its prompt. background is the default (returns a runId immediately; toggle via `/subagents auto-bg off`); set background:false when you need the result inline in this turn. allowIntercom:true lets children talk to you and each other.',
+			"Run isolated subagents (own context, own session). You invent each agent: name, optional system prompt, toolset (read-only default, write:true to edit). Use `agent`+`task` for one, `tasks` for many. `needs` declares dependency edges: a task waits for its needs and receives their outputs prepended to its prompt. background is the default (returns a runId immediately; toggle via `/subagents auto-bg off`); set background:false when you need the result inline in this turn. allowIntercom:true lets children talk to you and each other.",
 		promptSnippet: "Define and delegate work to specialized subagents.",
 		promptGuidelines: [
 			"Use subagent when independent review, testing, research, or parallel analysis improves quality.",
@@ -309,6 +317,33 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerTool<typeof SteerParam, { steered?: string[] }>({
+		name: "steer_subagent",
+		label: "Steer Subagent",
+		description:
+			"Inject a steering message into a running subagent's session (queues as steer if the child is mid-turn; delivered at its next model boundary).",
+		parameters: SteerParam,
+		async execute(_id, params) {
+			const { runId, taskId, message } = params as { runId: string; taskId?: string; message: string };
+			const ok = manager.steerTask(runId, taskId, message);
+			if (!ok)
+				return {
+					content: [{ type: "text", text: `No running task(s) for ${runId}${taskId ? `/${taskId}` : ""}.` }],
+					isError: true,
+					details: {},
+				};
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Steering message queued for ${runId}${taskId ? `/${taskId}` : " (all running tasks)"}.`,
+					},
+				],
+				details: {},
+			};
+		},
+	});
+
 	pi.registerTool<typeof RunIdParam, { aborted?: number }>({
 		name: "subagent_cancel",
 		label: "Subagent Cancel",

package/src/manager.ts

@@ -193,7 +193,10 @@ export class SubagentManager {
 	private runs = new Map<string, RunSnapshot>();
 	private settlers = new Map<string, (run: RunSnapshot) => void>();
 	private pendingReplies = new Map<string, PendingReply>();
-	private liveChildren = new Map<string, { abort: () => void; dispose: () => void; touchWatchdog: () => void }>();
+	private liveChildren = new Map<
+		string,
+		{ abort: () => void; dispose: () => void; touchWatchdog: () => void; steer: (message: string) => void }
+	>();
 	private mailboxes: Mailbox = createMailbox();
 	private runControllers = new Map<string, AbortController>();
 	private widgetTimers = new Map<string, ReturnType<typeof setTimeout>>(); // per-run stream throttle
@@ -217,7 +220,9 @@ export class SubagentManager {
 	/** Flip the background-by-default flag; persists to the agent dir. Returns the new value. */
 	setAutoBg(on: boolean): boolean {
 		this.autoBg = on;
-		void writeFile(join(getAgentDir(), "subagents-config.json"), JSON.stringify({ autoBg: on }, null, 2)).catch(() => {});
+		void writeFile(join(getAgentDir(), "subagents-config.json"), JSON.stringify({ autoBg: on }, null, 2)).catch(
+			() => {},
+		);
 		return on;
 	}
 
@@ -719,6 +724,13 @@ export class SubagentManager {
 				abort: () => void child?.abort(),
 				dispose: () => watchdog.dispose(),
 				touchWatchdog: () => watchdog.touch(),
+				// Inject a steering message mid-run; queues as steer if the child is streaming.
+				steer: (message) =>
+					void child?.prompt(message, { streamingBehavior: "steer" }).catch((err) =>
+						this.pi.sendUserMessage(`[steer_subagent] ${err instanceof Error ? err.message : String(err)}`, {
+							deliverAs: "followUp",
+						}),
+					),
 			});
 
 			const maxRuntimeMs = input.maxRuntimeMs ?? DEFAULT_RUNTIME_MS;
@@ -982,6 +994,16 @@ export class SubagentManager {
 		return { run: cloneRun(run), background: true };
 	}
 
+	/** Push a steering message into a live child's session. Returns false when unknown or not running. */
+	steerTask(runId: string, taskId: string | undefined, message: string): boolean {
+		const run = this.runs.get(runId);
+		if (!run) return false;
+		const ids = taskId ? [taskId] : run.tasks.map((t) => t.id).filter((id) => this.liveChildren.has(`${runId}:${id}`));
+		if (ids.length === 0) return false;
+		for (const id of ids) this.liveChildren.get(`${runId}:${id}`)?.steer(message);
+		return true;
+	}
+
 	/** Abort ONE task; siblings keep running. Returns false when unknown or already finished. */
 	cancelTask(runId: string, taskId: string, ctx?: ExtensionContext): boolean {
 		const run = this.runs.get(runId);

package/src/schemas.ts

@@ -91,3 +91,8 @@ export const ReplyParam = Type.Object({
 	taskId: Type.String(),
 	message: Type.String({ description: "Answer for the child" }),
 });
+export const SteerParam = Type.Object({
+	runId: Type.String(),
+	taskId: Type.Optional(Type.String({ description: "Specific task id; defaults to all still-running tasks" })),
+	message: Type.String({ description: "Steering message to inject into the child's session" }),
+});