pi-squad 0.16.1 → 0.16.3

package/README.md

@@ -139,6 +139,8 @@ Bundled agent definitions are copied to `~/.pi/squad/agents/` on first run. Edit
 
 **@mention routing**: Agents write `@frontend what token format?` in their output. The router delivers it in real-time via RPC `steer()`.
 
+**Main-session request/reply**: `squad_message` resolves an agent name to its live task, durably records the full request, and writes the documented JSONL RPC command `{"type":"steer","message":"..."}` to the child. By default (`expectReply: true`), the next substantive agent response is durably marked as the reply, pushed into the main Pi session, and wakes it via follow-up delivery; ordinary later activity remains panel-only. The pending reply marker survives scheduler reconstruction. Use `expectReply: false` for fire-and-forget steering. pi-squad waits for Pi's final `agent_settled` event before closing the child; low-level `agent_end` never kills queued continuations.
+
 ### Smart Planner
 
 The planner creates task breakdowns with proper dependency ordering:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-squad",
-  "version": "0.16.1",
+  "version": "0.16.3",
   "description": "Multi-agent collaboration extension for pi — task decomposition, dependency management, parallel execution, TUI panel",
   "type": "module",
   "scripts": {

package/src/agent-pool.ts

@@ -270,16 +270,14 @@ export class AgentPool {
 	async steer(taskId: string, message: string): Promise<boolean> {
 		const agent = this.agents.get(taskId);
 		if (!agent || agent.aborted || agent.process.exitCode !== null) return false;
-		this.sendRpcCommand(agent.process, { type: "steer", message });
-		return true;
+		return this.sendRpcCommand(agent.process, { type: "steer", message });
 	}
 
 	/** Queue a follow-up message for after the current turn */
 	async followUp(taskId: string, message: string): Promise<boolean> {
 		const agent = this.agents.get(taskId);
 		if (!agent || agent.aborted || agent.process.exitCode !== null) return false;
-		this.sendRpcCommand(agent.process, { type: "follow_up", message });
-		return true;
+		return this.sendRpcCommand(agent.process, { type: "follow_up", message });
 	}
 
 	/** Abort the current operation */
@@ -301,7 +299,7 @@ export class AgentPool {
 		agent.process.kill("SIGTERM");
 		// Force kill after 5s
 		const timer = setTimeout(() => {
-			if (!agent.process.killed) agent.process.kill("SIGKILL");
+			if (agent.process.exitCode === null) agent.process.kill("SIGKILL");
 		}, 5000);
 		await new Promise<void>((resolve) => {
 			agent.process.on("exit", () => {
@@ -337,9 +335,17 @@ export class AgentPool {
 	// Internal
 	// =========================================================================
 
-	private sendRpcCommand(proc: ChildProcess, command: Record<string, unknown>): void {
-		if (!proc.stdin || proc.stdin.destroyed) return;
-		proc.stdin.write(serializeJsonLine(command));
+	private sendRpcCommand(proc: ChildProcess, command: Record<string, unknown>): boolean {
+		if (!proc.stdin || proc.stdin.destroyed) return false;
+		try {
+			// Writable.write(false) means backpressure, not rejection; the bytes are
+			// still buffered. Reaching write() without throwing means the JSONL
+			// command was handed to the child stream.
+			proc.stdin.write(serializeJsonLine(command));
+			return true;
+		} catch {
+			return false;
+		}
 	}
 
 	private handleRpcEvent(agent: AgentProcess, event: any): void {
@@ -394,10 +400,12 @@ export class AgentPool {
 				data: event,
 			});
 		} else if (event.type === "agent_end") {
-			// Pi RPC mode emits agent_end when the agent loop finishes.
-			// The RPC process stays alive waiting for more commands,
-			// so we need to explicitly kill it and emit our own agent_end.
-			debug("squad-pool", `agent_end from RPC: ${agent.agentName} (task: ${agent.taskId})`);
+			// agent_end is one low-level run. Pi may still process queued steer,
+			// follow-up, retry, or compaction continuations. Killing here races and
+			// drops main-session steering. agent_settled is the final lifecycle edge.
+			debug("squad-pool", `agent_end from RPC (awaiting settled): ${agent.agentName} (task: ${agent.taskId})`);
+		} else if (event.type === "agent_settled") {
+			debug("squad-pool", `agent_settled from RPC: ${agent.agentName} (task: ${agent.taskId})`);
 			// Mark the guard to prevent double-emit from proc.on("exit")
 			const guardFn = (agent as any)._agentEndEmitted;
 			if (guardFn) guardFn();
@@ -417,11 +425,12 @@ export class AgentPool {
 					filesModified: endActivity.modifiedFiles.size,
 				},
 			});
-			// Kill the RPC process since the agent's work is done
+			// The session is fully settled, so the RPC process can now close.
 			agent.process.kill("SIGTERM");
-			setTimeout(() => {
-				if (!agent.process.killed) agent.process.kill("SIGKILL");
+			const forceKill = setTimeout(() => {
+				if (agent.process.exitCode === null) agent.process.kill("SIGKILL");
 			}, 3000);
+			forceKill.unref();
 		} else if (event.type === "error") {
 			this.emit({
 				type: "error",

package/src/index.ts

@@ -504,11 +504,12 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "squad_message",
 		label: "Squad Message",
-		description: "Send a message to a specific agent or task in the running squad.",
+		description: "Send a request to a specific agent/task. The agent's next substantive assistant response is durably forwarded back to the main Pi session and wakes it.",
 		parameters: Type.Object({
 			message: Type.String({ description: "Message to send" }),
 			taskId: Type.Optional(Type.String({ description: "Target task ID" })),
 			agent: Type.Optional(Type.String({ description: "Target agent name" })),
+			expectReply: Type.Optional(Type.Boolean({ description: "Forward the agent's next substantive response back to main Pi and wake it (default true)" })),
 		}),
 
 		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
@@ -528,7 +529,7 @@ export default function (pi: ExtensionAPI) {
 				return { content: [{ type: "text" as const, text: "Could not determine target task. Provide taskId or an agent name that is currently running." }], details: undefined };
 			}
 
-			const sent = await activeScheduler!.sendHumanMessage(taskId, params.message);
+			const sent = await activeScheduler!.sendHumanMessage(taskId, params.message, params.expectReply ?? true);
 			const status = sent ? "delivered" : "queued for when the agent starts";
 
 			return { content: [{ type: "text" as const, text: `Message ${status}: "${params.message}"` }], details: undefined };
@@ -627,6 +628,14 @@ export default function (pi: ExtensionAPI) {
 								forceWidgetUpdate();
 								break;
 							}
+							case "orchestrator_reply": {
+								pi.sendMessage({
+									customType: "squad-agent-reply",
+									content: `[squad] Direct reply from '${event.agentName}' on task '${event.taskId}':\n${event.message}`,
+									display: true,
+								}, { triggerTurn: true, deliverAs: "followUp" });
+								break;
+							}
 							case "escalation": {
 								pi.sendMessage({
 									customType: "squad-escalation",
@@ -1708,6 +1717,17 @@ async function startSquad(
 				break;
 			}
 
+			case "orchestrator_reply": {
+				// Push the complete requested response back into the main session and
+				// wake it; ordinary task activity remains panel-only.
+				pi.sendMessage({
+					customType: "squad-agent-reply",
+					content: `[squad] Direct reply from '${event.agentName}' on task '${event.taskId}':\n${event.message}`,
+					display: true,
+				}, { triggerTurn: true, deliverAs: "followUp" });
+				break;
+			}
+
 			case "escalation": {
 				// Escalation — agent needs help. triggerTurn so the main agent
 				// can respond and relay help.

package/src/scheduler.ts

@@ -34,6 +34,7 @@ export type SchedulerEventType =
 	| "task_rework"
 	| "squad_review_required"
 	| "squad_failed"
+	| "orchestrator_reply"
 	| "escalation"
 	| "activity";
 
@@ -568,6 +569,26 @@ export class Scheduler {
 							// presentation layers may viewport them, but source data must never truncate.
 							text,
 						});
+
+						// A squad_message is a request/response channel, not fire-and-forget.
+						// Persist an acknowledgement marker before emitting so restart/focus
+						// changes cannot forward the same response twice.
+						if (this.hasPendingOrchestratorRequest(event.taskId)) {
+							store.appendMessage(this.squadId, event.taskId, {
+								ts: store.now(),
+								from: event.agentName,
+								type: "reply",
+								to: "orchestrator",
+								text: "Response forwarded to main orchestrator",
+							});
+							this.emit({
+								type: "orchestrator_reply",
+								squadId: this.squadId,
+								taskId: event.taskId,
+								agentName: event.agentName,
+								message: text,
+							});
+						}
 					}
 
 					// Track usage
@@ -1118,31 +1139,47 @@ export class Scheduler {
 	// External Actions
 	// =========================================================================
 
-	/** Send a human message to a task's agent */
-	async sendHumanMessage(taskId: string, message: string): Promise<boolean> {
+	/** Send a main-orchestrator request to a task's agent and await its next reply. */
+	async sendHumanMessage(taskId: string, message: string, expectsReply = true): Promise<boolean> {
+		const task = store.loadTask(this.squadId, taskId);
+		if (!task) return false;
+
 		store.appendMessage(this.squadId, taskId, {
 			ts: store.now(),
-			from: "human",
+			from: "orchestrator",
 			type: "message",
 			text: message,
+			expectsReply,
 		});
 
-		if (this.pool.isRunning(taskId)) {
-			return this.pool.steer(taskId, `[squad] Human: ${message}`);
-		}
-		// Queue for when agent spawns
-		const task = store.loadTask(this.squadId, taskId);
-		if (task) {
-			this.pool.queueMessage(task.agent, {
-				ts: store.now(),
-				from: "human",
-				type: "message",
-				text: message,
-			});
+		const request = expectsReply
+			? `[squad] Main orchestrator requests a direct response:\n${message}\n\nReply directly in your next assistant message. That complete message will be forwarded automatically to the main session.`
+			: `[squad] Main orchestrator message:\n${message}`;
+		if (this.pool.isRunning(taskId) && await this.pool.steer(taskId, request)) {
+			return true;
 		}
+
+		// Queue for when the assigned agent starts/restarts. The durable request
+		// marker lets a reconstructed scheduler still forward the eventual reply.
+		this.pool.queueMessage(task.agent, {
+			ts: store.now(),
+			from: "orchestrator",
+			type: "message",
+			text: expectsReply ? `${message}\n\n[Direct response required by main orchestrator]` : message,
+			expectsReply,
+		});
 		return false;
 	}
 
+	private hasPendingOrchestratorRequest(taskId: string): boolean {
+		let pending = false;
+		for (const message of store.loadMessages(this.squadId, taskId)) {
+			if (message.from === "orchestrator" && message.expectsReply) pending = true;
+			if (message.type === "reply" && message.to === "orchestrator") pending = false;
+		}
+		return pending;
+	}
+
 	/** Pause a running task */
 	async pauseTask(taskId: string): Promise<void> {
 		if (this.pool.isRunning(taskId)) {

package/src/skills/squad-supervisor/SKILL.md

@@ -130,7 +130,8 @@ Common escalation patterns:
 Use `squad_message` with:
 - `taskId` — target a specific task
 - `agent` — target whichever task an agent is working on
-- `message` — your instruction or answer
+- `message` — your instruction or question
+- `expectReply` — defaults to `true`; the agent's next substantive response is durably pushed back into the main Pi session and wakes you. Set `false` only for fire-and-forget steering.
 
 Keep messages **specific and actionable**:
 - Good: "Use RS256 for JWT signing. The secret is in env var JWT_SECRET."

package/src/types.ts

@@ -165,6 +165,8 @@ export interface TaskMessage {
 	type: MessageType;
 	text: string;
 	to?: string;
+	/** Main-orchestrator message expects the next substantive agent response. */
+	expectsReply?: boolean;
 	name?: string;
 	args?: Record<string, unknown>;
 }