pi-subagents 0.17.4 → 0.18.0

package/run-status.ts

@@ -0,0 +1,134 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { AgentToolResult } from "@mariozechner/pi-agent-core";
+import { formatAsyncRunList, listAsyncRuns } from "./async-status.ts";
+import { ASYNC_DIR, RESULTS_DIR, type Details } from "./types.ts";
+import { findByPrefix, readStatus } from "./utils.ts";
+
+export interface RunStatusParams {
+	action?: "status";
+	id?: string;
+	runId?: string;
+	dir?: string;
+}
+
+function activityText(activityState: unknown, lastActivityAt: unknown): string | undefined {
+	if (typeof lastActivityAt !== "number") return undefined;
+	const seconds = Math.floor(Math.max(0, Date.now() - lastActivityAt) / 1000);
+	return activityState === "needs_attention" ? `no activity for ${seconds}s` : `active ${seconds}s ago`;
+}
+
+export function inspectSubagentStatus(params: RunStatusParams): AgentToolResult<Details> {
+	if (!params.id && !params.runId && !params.dir) {
+		try {
+			const runs = listAsyncRuns(ASYNC_DIR, { states: ["queued", "running"] });
+			return {
+				content: [{ type: "text", text: formatAsyncRunList(runs) }],
+				details: { mode: "single", results: [] },
+			};
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text", text: message }],
+				isError: true,
+				details: { mode: "single", results: [] },
+			};
+		}
+	}
+
+	let asyncDir: string | null = null;
+	let resolvedId = params.id ?? params.runId;
+
+	if (params.dir) {
+		asyncDir = path.resolve(params.dir);
+	} else if (resolvedId) {
+		const direct = path.join(ASYNC_DIR, resolvedId);
+		if (fs.existsSync(direct)) {
+			asyncDir = direct;
+		} else {
+			const match = findByPrefix(ASYNC_DIR, resolvedId);
+			if (match) {
+				asyncDir = match;
+				resolvedId = path.basename(match);
+			}
+		}
+	}
+
+	const resultPath = resolvedId && !asyncDir ? findByPrefix(RESULTS_DIR, resolvedId, ".json") : null;
+
+	if (!asyncDir && !resultPath) {
+		return {
+			content: [{ type: "text", text: "Async run not found. Provide id or dir." }],
+			isError: true,
+			details: { mode: "single", results: [] },
+		};
+	}
+
+	if (asyncDir) {
+		let status;
+		try {
+			status = readStatus(asyncDir);
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text", text: message }],
+				isError: true,
+				details: { mode: "single", results: [] },
+			};
+		}
+		const logPath = path.join(asyncDir, `subagent-log-${resolvedId ?? "unknown"}.md`);
+		const eventsPath = path.join(asyncDir, "events.jsonl");
+		if (status) {
+			const stepsTotal = status.steps?.length ?? 1;
+			const current = status.currentStep !== undefined ? status.currentStep + 1 : undefined;
+			const stepLine = current !== undefined ? `Step: ${current}/${stepsTotal}` : `Steps: ${stepsTotal}`;
+			const started = new Date(status.startedAt).toISOString();
+			const updated = status.lastUpdate ? new Date(status.lastUpdate).toISOString() : "n/a";
+			const statusActivityText = status.state === "running" ? activityText(status.activityState, status.lastActivityAt) : undefined;
+
+			const lines = [
+				`Run: ${status.runId}`,
+				`State: ${status.state}`,
+				statusActivityText ? `Activity: ${statusActivityText}` : undefined,
+				`Mode: ${status.mode}`,
+				stepLine,
+				`Started: ${started}`,
+				`Updated: ${updated}`,
+				`Dir: ${asyncDir}`,
+			].filter((line): line is string => Boolean(line));
+			for (const [index, step] of (status.steps ?? []).entries()) {
+				const stepActivityText = step.status === "running" ? activityText(step.activityState, step.lastActivityAt) : undefined;
+				lines.push(`Step ${index + 1}: ${step.agent} ${step.status}${stepActivityText ? `, ${stepActivityText}` : ""}`);
+			}
+			if (status.sessionFile) lines.push(`Session: ${status.sessionFile}`);
+			if (fs.existsSync(logPath)) lines.push(`Log: ${logPath}`);
+			if (fs.existsSync(eventsPath)) lines.push(`Events: ${eventsPath}`);
+
+			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [] } };
+		}
+	}
+
+	if (resultPath) {
+		try {
+			const raw = fs.readFileSync(resultPath, "utf-8");
+			const data = JSON.parse(raw) as { id?: string; success?: boolean; summary?: string; exitCode?: number; state?: string };
+			const status = data.success ? "complete" : data.state === "paused" || data.exitCode === 0 ? "paused" : "failed";
+			const lines = [`Run: ${data.id ?? resolvedId}`, `State: ${status}`, `Result: ${resultPath}`];
+			if (data.summary) lines.push("", data.summary);
+			return { content: [{ type: "text", text: lines.join("\n") }], details: { mode: "single", results: [] } };
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return {
+				content: [{ type: "text", text: `Failed to read async result file: ${message}` }],
+				isError: true,
+				details: { mode: "single", results: [] },
+			};
+		}
+	}
+
+	return {
+		content: [{ type: "text", text: "Status file not found." }],
+		isError: true,
+		details: { mode: "single", results: [] },
+	};
+}

package/schemas.ts

@@ -57,12 +57,32 @@ export const ParallelStepSchema = Type.Object({
 // Note: Using Type.Any() for Google API compatibility (doesn't support anyOf)
 export const ChainItem = Type.Any({ description: "Chain step: either {agent, task?, ...} for sequential or {parallel: [...]} for concurrent execution" });
 
+export const ControlOverrides = Type.Object({
+	enabled: Type.Optional(Type.Boolean({ description: "Enable/disable subagent control attention tracking for this run" })),
+	needsAttentionAfterMs: Type.Optional(Type.Integer({ minimum: 1, description: "No-observed-activity window before a run needs attention" })),
+	notifyOn: Type.Optional(Type.Array(Type.String({ enum: ["needs_attention"] }), {
+		description: "Control event types that should notify the parent/orchestrator. Defaults to needs_attention.",
+	})),
+	notifyChannels: Type.Optional(Type.Array(Type.String({ enum: ["event", "async", "intercom"] }), {
+		description: "Notification channels to use when available. Defaults to event, async, and intercom.",
+	})),
+});
+
 export const SubagentParams = Type.Object({
 	agent: Type.Optional(Type.String({ description: "Agent name (SINGLE mode) or target for management get/update/delete" })),
 	task: Type.Optional(Type.String({ description: "Task (SINGLE mode)" })),
 	// Management action (when present, tool operates in management mode)
 	action: Type.Optional(Type.String({
-		description: "Management action: 'list' (discover agents/chains), 'get' (full detail), 'create', 'update', 'delete'. Omit for execution mode."
+		description: "Action: management ('list','get','create','update','delete') or control ('status','interrupt'). Omit for execution mode."
+	})),
+	id: Type.Optional(Type.String({
+		description: "Run id or prefix for action='status' or action='interrupt'."
+	})),
+	runId: Type.Optional(Type.String({
+		description: "Target run ID for action='interrupt'. Defaults to the most recently active controllable run in this session. Prefer id for new calls."
+	})),
+	dir: Type.Optional(Type.String({
+		description: "Async run directory for action='status'."
 	})),
 	// Chain identifier for management (can't reuse 'chain' — that's the execution array)
 	chainName: Type.Optional(Type.String({
@@ -96,14 +116,9 @@ export const SubagentParams = Type.Object({
 	),
 	// Clarification TUI
 	clarify: Type.Optional(Type.Boolean({ description: "Show TUI to preview/edit before execution (default: true for chains, false for single/parallel). Implies sync mode." })),
+	control: Type.Optional(ControlOverrides),
 	// Solo agent overrides
 	output: Type.Optional(Type.Any({ description: "Output file for single agent (string), or false to disable. Relative paths resolve against cwd." })),
 	skill: Type.Optional(SkillOverride),
 	model: Type.Optional(Type.String({ description: "Override model for single agent (e.g. 'anthropic/claude-sonnet-4')" })),
 });
-
-export const StatusParams = Type.Object({
-	action: Type.Optional(Type.String({ description: "Action: 'list' to show active async runs, or omit to inspect one run by id/dir" })),
-	id: Type.Optional(Type.String({ description: "Async run id or prefix" })),
-	dir: Type.Optional(Type.String({ description: "Async run directory (overrides id search)" })),
-});

package/skills/pi-subagents/SKILL.md

@@ -20,11 +20,12 @@ agents into a workflow, or create/edit agents and chains on demand.
 - **Recon and planning**: use `scout` or `context-builder`, then `planner`
 - **Parallel exploration**: run multiple non-conflicting tasks concurrently
 - **Long-running work**: launch async/background runs and inspect them later
+- **Subagent control**: watch needs-attention signals and soft-interrupt only when a delegated run is genuinely blocked
 - **Agent authoring**: create, update, or override agents and chains for a project
 
 ## Tool vs Slash Commands
 
-Agents can use the `subagent(...)` and `subagent_status(...)` tools directly.
+Agents can use the `subagent(...)` tool directly for execution, management, status, and control.
 Humans often use the slash-command layer instead:
 
 - `/run` — launch a single agent
@@ -44,14 +45,14 @@ and user/project agents override builtins with the same name.
 | Agent | Purpose | Model | Typical output / role |
 |-------|---------|-------|------------------------|
 | `scout` | Fast codebase recon | `openai-codex/gpt-5.4-mini` | Writes `context.md` handoff material |
-| `planner` | Creates implementation plans | `openai-codex/gpt-5.4` | Writes `plan.md` |
-| `worker` | General implementation | `openai-codex/gpt-5.4` | Edits code directly |
-| `reviewer` | Review-and-fix specialist | `openai-codex/gpt-5.3-codex:high` | Can edit/fix reviewed code |
-| `context-builder` | Requirements/codebase handoff builder | `openai-codex/gpt-5.4` | Writes structured context files |
-| `researcher` | Web research brief generator | `openai-codex/gpt-5.4` | Writes `research.md` |
+| `planner` | Creates implementation plans | `openai-codex/gpt-5.5` | Writes `plan.md` |
+| `worker` | General implementation | `openai-codex/gpt-5.5` | Edits code directly |
+| `reviewer` | Review-and-fix specialist | `openai-codex/gpt-5.5` | Can edit/fix reviewed code |
+| `context-builder` | Requirements/codebase handoff builder | `openai-codex/gpt-5.5` | Writes structured context files |
+| `researcher` | Web research brief generator | `openai-codex/gpt-5.5` | Writes `research.md` |
 | `delegate` | Lightweight generic delegate | inherits parent model | No fixed output; generic delegated work |
-| `oracle` | Decision-consistency advisory review | `openai-codex/gpt-5.4:high` | Advisory review, intercom coordination |
-| `oracle-executor` | Implementation after approval | `openai-codex/gpt-5.3-codex:high` | Single-writer implementation after approval |
+| `oracle` | Decision-consistency advisory review | `openai-codex/gpt-5.5` | Advisory review, intercom coordination |
+| `oracle-executor` | Implementation after approval | `openai-codex/gpt-5.5` | Single-writer implementation after approval |
 
 Override builtin defaults via settings before copying full agent files when a
 small tweak is enough.
@@ -144,8 +145,42 @@ subagent({
 })
 ```
 
-Inspect async runs with the `subagent_status(...)` tool or the
-`/subagents-status` slash command.
+Inspect async runs with `subagent({ action: "status", id: "..." })`, `subagent({ action: "status" })` for active runs, or the `/subagents-status` slash command.
+
+### Subagent control
+
+Subagent control is the runtime visibility and intervention layer for delegated runs. It is separate from lifecycle status. Lifecycle status says whether a child is `queued`, `running`, `paused`, `complete`, or `failed`. Activity reporting is factual: it tracks the last observed activity time and the current tool when known. It does not pretend to know that a child is truly stuck.
+
+Default behavior is intentionally conservative. When no activity has been observed past the configured threshold, the run emits a `needs_attention` control event. Foreground runs can push this as a `subagent:control-event` event, and async runs persist it to `events.jsonl` so the parent tracker can surface it without constant manual polling. Notification-worthy control events are also inserted into the visible transcript so both the user and the parent agent can see them, with a proactive hint plus concrete `nudge`, `status`, and `interrupt` options. Visible notifications fire once per child run and attention state.
+
+Use soft interrupt when a child is clearly blocked or drifting and the parent needs to regain control:
+
+```typescript
+subagent({ action: "interrupt" })
+```
+
+Pass `id` when targeting a specific controllable run:
+
+```typescript
+subagent({ action: "interrupt", id: "abc123" })
+```
+
+A soft interrupt cancels the current child turn and leaves the run paused. It does not mean the delegated task succeeded or failed. After an interrupt, decide the next explicit action: resume with clearer instructions, replace the task, ask the user, or stop the workflow.
+
+Per-run control thresholds can be overridden when a task legitimately runs without observable output for longer than usual:
+
+```typescript
+subagent({
+  agent: "worker",
+  task: "Run the slow migration test suite",
+  control: {
+    needsAttentionAfterMs: 300000,
+    notifyOn: ["needs_attention"]
+  }
+})
+```
+
+If the run already has an active intercom bridge target, needs-attention notifications can also prepare a compact intercom ping for the orchestrator. When a child route is available, the ping tells the orchestrator which agent needs attention and includes the exact `intercom({ action: "send", to: "..." })` target for a nudge. Do not invent a target or ask the child to self-report when no bridge exists.
 
 ## Clarify TUI
 
@@ -334,6 +369,7 @@ particular agent or with forked context.
   filtered contexts.
 - **Default subagent nesting depth is 2.** Deeper recursive delegation is blocked
   unless configured otherwise.
+- **Attention signals are not lifecycle state.** `needs_attention` means no activity has been observed past the configured threshold. `paused` means the child turn was intentionally interrupted or is awaiting direction; it is not the same as `failed`.
 - **Intercom asks are blocking.** A session can only maintain one pending outbound
   ask wait state at a time.
 - **Keep conversational authority clear.** Advisory subagents should not silently
@@ -362,6 +398,10 @@ Give subagents specific tasks rather than vague mandates.
 If a subagent encounters an unapproved product, architecture, or scope choice,
 it should coordinate back via `intercom` instead of deciding alone.
 
+### Intervene only on clear control signals
+
+Use subagent control proactively when a delegated run emits `needs_attention`, or when a human asks you to regain control. Do not interrupt just because a child has briefly produced no output. Silence can be normal during long tool calls, test runs, or model reasoning.
+
 ### Name sessions meaningfully
 
 Use `/name` so intercom targeting stays stable.

package/subagent-control.ts

@@ -0,0 +1,148 @@
+import {
+	type ActivityState,
+	type ControlConfig,
+	type ControlEvent,
+	type ControlEventType,
+	type ControlNotificationChannel,
+	type ResolvedControlConfig,
+} from "./types.ts";
+
+const CONTROL_EVENT_TYPES: ControlEventType[] = ["needs_attention"];
+const CONTROL_NOTIFICATION_CHANNELS: ControlNotificationChannel[] = ["event", "async", "intercom"];
+const DEFAULT_NOTIFY_ON: ControlEventType[] = ["needs_attention"];
+
+export const DEFAULT_CONTROL_CONFIG: ResolvedControlConfig = {
+	enabled: true,
+	needsAttentionAfterMs: 60_000,
+	notifyOn: DEFAULT_NOTIFY_ON,
+	notifyChannels: CONTROL_NOTIFICATION_CHANNELS,
+};
+
+function parsePositiveInt(value: unknown): number | undefined {
+	if (typeof value !== "number") return undefined;
+	if (!Number.isFinite(value) || !Number.isInteger(value) || value < 1) return undefined;
+	return value;
+}
+
+function parseControlList<T extends string>(value: unknown, allowed: readonly T[]): T[] | undefined {
+	if (!Array.isArray(value)) return undefined;
+	if (value.length === 0) return [];
+	const allowedSet = new Set(allowed);
+	const parsed = value.filter((entry): entry is T => typeof entry === "string" && allowedSet.has(entry as T));
+	return parsed.length > 0 ? Array.from(new Set(parsed)) : undefined;
+}
+
+export function resolveControlConfig(
+	globalConfig?: ControlConfig,
+	override?: ControlConfig,
+): ResolvedControlConfig {
+	const enabled = override?.enabled ?? globalConfig?.enabled ?? DEFAULT_CONTROL_CONFIG.enabled;
+	const needsAttentionAfterMs = parsePositiveInt(override?.needsAttentionAfterMs)
+		?? parsePositiveInt(globalConfig?.needsAttentionAfterMs)
+		?? DEFAULT_CONTROL_CONFIG.needsAttentionAfterMs;
+	const notifyOn = parseControlList(override?.notifyOn, CONTROL_EVENT_TYPES)
+		?? parseControlList(globalConfig?.notifyOn, CONTROL_EVENT_TYPES)
+		?? DEFAULT_CONTROL_CONFIG.notifyOn;
+	const notifyChannels = parseControlList(override?.notifyChannels, CONTROL_NOTIFICATION_CHANNELS)
+		?? parseControlList(globalConfig?.notifyChannels, CONTROL_NOTIFICATION_CHANNELS)
+		?? DEFAULT_CONTROL_CONFIG.notifyChannels;
+	return {
+		enabled,
+		needsAttentionAfterMs,
+		notifyOn: [...notifyOn],
+		notifyChannels: [...notifyChannels],
+	};
+}
+
+export function deriveActivityState(input: {
+	config: ResolvedControlConfig;
+	startedAt: number;
+	lastActivityAt?: number;
+	now?: number;
+}): ActivityState | undefined {
+	if (!input.config.enabled) return undefined;
+	const now = input.now ?? Date.now();
+	const lastActivity = input.lastActivityAt ?? input.startedAt;
+	const ageMs = Math.max(0, now - lastActivity);
+	return ageMs > input.config.needsAttentionAfterMs ? "needs_attention" : undefined;
+}
+
+export function shouldEmitControlEvent(
+	config: ResolvedControlConfig,
+	from: ActivityState | undefined,
+	to: ActivityState | undefined,
+): boolean {
+	return config.enabled && from !== to && to === "needs_attention";
+}
+
+export function buildControlEvent(input: {
+	from?: ActivityState;
+	to: ActivityState;
+	runId: string;
+	agent: string;
+	index?: number;
+	ts?: number;
+	lastActivityAt?: number;
+}): ControlEvent {
+	const ts = input.ts ?? Date.now();
+	const elapsedMs = input.lastActivityAt ? Math.max(0, ts - input.lastActivityAt) : undefined;
+	const elapsedSeconds = elapsedMs !== undefined ? Math.floor(elapsedMs / 1000) : undefined;
+	const message = elapsedSeconds !== undefined
+		? `${input.agent} needs attention (no observed activity for ${elapsedSeconds}s)`
+		: `${input.agent} needs attention`;
+	return {
+		type: "needs_attention",
+		from: input.from,
+		to: input.to,
+		ts,
+		runId: input.runId,
+		agent: input.agent,
+		index: input.index,
+		message,
+	};
+}
+
+export function shouldNotifyControlEvent(config: ResolvedControlConfig, event: ControlEvent): boolean {
+	return config.enabled && config.notifyOn.includes(event.type);
+}
+
+export function controlNotificationKey(event: ControlEvent, childIntercomTarget?: string): string {
+	const childKey = childIntercomTarget ?? (event.index !== undefined ? `${event.runId}:${event.index}` : event.runId);
+	return `${childKey}:${event.type}`;
+}
+
+export function claimControlNotification(config: ResolvedControlConfig, event: ControlEvent, seenKeys: Set<string>, childIntercomTarget?: string): boolean {
+	if (!shouldNotifyControlEvent(config, event)) return false;
+	const key = controlNotificationKey(event, childIntercomTarget);
+	if (seenKeys.has(key)) return false;
+	seenKeys.add(key);
+	return true;
+}
+
+export function formatControlNoticeMessage(event: ControlEvent, childIntercomTarget?: string): string {
+	const runTarget = event.runId;
+	const nudgeCommand = childIntercomTarget
+		? `intercom({ action: "send", to: "${childIntercomTarget}", message: "What are you blocked on? Reply with the smallest next step or ask for a decision." })`
+		: undefined;
+	return [
+		`Subagent needs attention: ${event.agent}`,
+		`Run: ${runTarget}${event.index !== undefined ? ` step ${event.index + 1}` : ""}`,
+		`Signal: ${event.message}`,
+		"Hint: Inspect status first unless the run is clearly blocked.",
+		childIntercomTarget
+			? `Nudge: ${nudgeCommand}`
+			: "Nudge: no child message route registered",
+		`Status: subagent({ action: "status", id: "${runTarget}" })`,
+		`Interrupt: subagent({ action: "interrupt", id: "${runTarget}" })`,
+	].join("\n");
+}
+
+export function formatControlIntercomMessage(event: ControlEvent, childIntercomTarget?: string): string {
+	return [
+		"subagent needs attention",
+		"",
+		`${event.agent} needs attention in run ${event.runId}.`,
+		"",
+		formatControlNoticeMessage(event, childIntercomTarget),
+	].join("\n");
+}