@arhen/pi-core-subagent 1.3.2 → 1.3.4

package/src/peek.ts

@@ -7,8 +7,8 @@
  */
 
 import { closeSync, openSync, readSync, statSync } from "node:fs";
-import { Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 
 /** Tail window: last 64KB of the child session file is plenty for a peek. */
 const TAIL_BYTES = 64 * 1024;
@@ -56,7 +56,9 @@ function eventLine(raw: string): [string, string] | null {
 	const out: [string, string][] = [];
 	for (const block of msg.content ?? []) {
 		if (block.type === "toolCall") {
-			const arg = Object.values(block.arguments ?? {}).find((v) => typeof v === "string" && v.trim() !== "") as string | undefined;
+			const arg = Object.values(block.arguments ?? {}).find((v) => typeof v === "string" && v.trim() !== "") as
+				| string
+				| undefined;
 			out.push(["→", `${block.name}${arg ? ` ${clip(arg, 120)}` : ""}`]);
 		} else if (block.type === "text" && block.text?.trim()) {
 			out.push([msg.role === "toolResult" ? "←" : "·", clip(block.text, 160)]);

package/src/schemas.ts

@@ -0,0 +1,88 @@
+/** Tool schemas — single source of truth. TaskInput/SubagentParamsShape are
+ *  derived from them, so the shapes can never drift from what the model sees. */
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+import { DEFAULT_CONCURRENCY, MAX_CONCURRENCY } from "./manager.ts";
+
+const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+const TaskItem = Type.Object({
+	id: Type.Optional(Type.String({ description: "Optional stable task id" })),
+	agent: Type.String({
+		minLength: 1,
+		description:
+			"Agent name you invent. Always define the agent inline: prompt (system prompt) + toolset (write: true for write access). Never create agent files.",
+	}),
+	task: Type.String({ minLength: 1, description: "Task for this agent" }),
+	prompt: Type.Optional(
+		Type.String({ description: "System prompt defining this agent's behavior. Optional — a minimal default is used." }),
+	),
+	write: Type.Optional(
+		Type.Boolean({
+			description: "true = write toolset (read, bash, edit, write); default false = read-only (read, grep, find, ls)",
+		}),
+	),
+	model: Type.Optional(Type.String({ description: "Model override (provider/model-id)" })),
+	thinking: Type.Optional(StringEnum(THINKING_LEVELS, { description: "Thinking level override" })),
+	cwd: Type.Optional(Type.String({ description: "Working directory for this task. Default: current project." })),
+	tools: Type.Optional(Type.Array(Type.String(), { description: "Explicit tool allowlist (overrides the toolset)" })),
+	maxRuntimeMs: Type.Optional(Type.Number({ description: "Per-task timeout (ms)" })),
+	needs: Type.Optional(
+		Type.Array(Type.String(), {
+			description: "Ids of tasks this one waits for; their outputs are prepended to this prompt.",
+		}),
+	),
+});
+
+export const SubagentParams = Type.Object({
+	agent: Type.Optional(Type.String({ minLength: 1, description: "Name you invent for this subagent (single mode)" })),
+	task: Type.Optional(Type.String({ minLength: 1, description: "Task (single mode)" })),
+	prompt: Type.Optional(Type.String({ description: "System prompt for this agent (single mode)" })),
+	write: Type.Optional(Type.Boolean({ description: "true = write toolset; default false = read-only (single mode)" })),
+	tools: Type.Optional(
+		Type.Array(Type.String(), { description: "Explicit tool allowlist (overrides the toolset) (single mode)" }),
+	),
+	tasks: Type.Optional(Type.Array(TaskItem, { description: "Parallel tasks" })),
+	chain: Type.Optional(Type.Array(TaskItem, { description: "Sequential tasks; {previous} = prior output" })),
+	model: Type.Optional(Type.String({ description: "Model override (single mode)" })),
+	thinking: Type.Optional(StringEnum(THINKING_LEVELS, { description: "Thinking level override (single mode)" })),
+	cwd: Type.Optional(Type.String({ description: "Working directory (single mode). Default: current project." })),
+	concurrency: Type.Optional(
+		Type.Number({ description: `Parallel concurrency (default ${DEFAULT_CONCURRENCY}, max ${MAX_CONCURRENCY})` }),
+	),
+	maxRuntimeMs: Type.Optional(
+		Type.Number({
+			description: "Per-task timeout, ms. Omit for no cap (default): tasks run until done, stalled, or user-aborted.",
+		}),
+	),
+	background: Type.Optional(
+		Type.Boolean({ description: "Fire-and-forget: return immediately with a runId; you'll be notified on completion" }),
+	),
+	notifyPerTask: Type.Optional(
+		Type.Boolean({
+			description:
+				"Wake you (queued follow-up turn) as each task completes — background runs only, since blocking runs can't be woken mid-tool. Default false.",
+		}),
+	),
+	allowIntercom: Type.Optional(
+		Type.Boolean({ description: "Let children ask you questions, notify you, and message sibling subagents" }),
+	),
+});
+
+/** Derived from the schemas — single source of truth, no hand-maintained mirror. */
+export type TaskInput = Static<typeof TaskItem>;
+export type SubagentParamsShape = Static<typeof SubagentParams>;
+
+export const RunIdParam = Type.Object({ runId: Type.String({ description: "Run id from subagent()" }) });
+export const ResultParam = Type.Object({
+	runId: Type.String(),
+	taskId: Type.Optional(Type.String({ description: "Specific task id; defaults to all" })),
+});
+export const AwaitParam = Type.Object({
+	runId: Type.String(),
+	timeoutMs: Type.Optional(Type.Number({ description: "Max wait (ms); default: until finished" })),
+});
+export const ReplyParam = Type.Object({
+	runId: Type.String(),
+	taskId: Type.String(),
+	message: Type.String({ description: "Answer for the child" }),
+});

package/src/types.ts

@@ -0,0 +1,70 @@
+/** Shared run/task types for the subagent extension. No imports. */
+
+export type RunMode = "single" | "parallel" | "chain";
+export type TaskStatus = "queued" | "starting" | "running" | "awaiting_parent" | "completed" | "failed" | "aborted";
+export type RunStatus = "queued" | "running" | "awaiting_parent" | "completed" | "failed" | "aborted";
+
+export const TERMINAL: TaskStatus[] = ["completed", "failed", "aborted"];
+
+/** Widget/command cap on rendered tasks; scheduler cap on spawned tasks. */
+export const MAX_TASKS = 16;
+
+export interface UsageStats {
+	input: number;
+	output: number;
+	cacheRead: number;
+	cacheWrite: number;
+	cost: number;
+	turns: number;
+}
+
+export interface TaskSnapshot {
+	id: string;
+	runId: string;
+	agent: string;
+	task: string;
+	cwd: string;
+	status: TaskStatus;
+	/** Resolved dependency edges (task ids). Empty/absent = wave 1. */
+	needs?: string[];
+	sessionId?: string;
+	sessionFile?: string;
+	startedAt?: number;
+	endedAt?: number;
+	toolCalls: number;
+	lastActivity?: string;
+	finalText?: string;
+	error?: string;
+	model?: string;
+	thinking?: string;
+	tools?: string[];
+	usage: UsageStats;
+	/** Sibling addresses for intercom tools (send_agent_message targets). */
+	roster?: string;
+}
+
+export interface RunSnapshot {
+	id: string;
+	mode: RunMode;
+	status: RunStatus;
+	background: boolean;
+	allowIntercom: boolean;
+	notifyPerTask: boolean;
+	createdAt: number;
+	startedAt?: number;
+	endedAt?: number;
+	concurrency: number;
+	tasks: TaskSnapshot[];
+	aggregateUsage: UsageStats;
+	/** True once the parent awaited this run — completion notices are redundant then. */
+	awaited?: boolean;
+}
+
+export interface RunDetails {
+	run: RunSnapshot;
+	background?: boolean;
+}
+
+export interface PendingReply {
+	resolve: (message: string) => void;
+}