@henryqw/pi-subagent 18.0.1 → 22.0.1

package/extensions/task-name.ts

@@ -1,4 +1,4 @@
-import { DISPLAY_TEXT_CONTRACT, hasDisplayControlCharacters } from "@henryqw/pi-subagent";
+import { DISPLAY_TEXT_CONTRACT } from "@henryqw/pi-subagent";
 import { Type, type Static } from "typebox";
 
 const TASK_NAME_MAX_LENGTH = 29 as const;
@@ -22,7 +22,6 @@ export const TaskNameSchema = Type.String({
 export type TaskName = Static<typeof TaskNameSchema>;
 
 export function normalizeTaskName(value: TaskName, path: string): TaskName {
-	if (hasDisplayControlCharacters(value)) throw new Error(`${path} must not contain C0/C1 control characters.`);
 	const normalized = value.trim();
 	if (!normalized) throw new Error(`${path} must be non-empty text.`);
 	return normalized;

package/extensions/workflow.ts

@@ -2,7 +2,8 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import { DISPLAY_TEXT_CONTRACT } from "@henryqw/pi-subagent";
 import { PROFILE_NAMES } from "@henryqw/pi-task-models";
 import { Type, type Static } from "typebox";
-import { Check } from "typebox/value";
+import { Check, Errors } from "typebox/value";
+import { ExecuteRequestSchema, parseExecuteRequest, type ExecuteRequest } from "../dist/schema.js";
 import { TaskNameSchema, normalizeTaskName } from "./task-name.ts";
 
 export const MAX_WORKFLOW_ENTRIES = 8;
@@ -11,47 +12,42 @@ const RoleSchema = Type.String({ minLength: 1, pattern: DISPLAY_TEXT_CONTRACT.pa
 const TaskSchema = Type.String({ minLength: 1, description: "Bounded task packet" });
 const ModelSchema = Type.String({ minLength: 1, pattern: DISPLAY_TEXT_CONTRACT.pattern, description: "Designated model as provider/modelId; replaces the selected route model" });
 const ModelClassSchema = StringEnum(PROFILE_NAMES, { description: "Task model profile" });
+const DirectKindSchema = StringEnum(["text"] as const);
 
 export const DelegationSchema = Type.Object({
 	role: RoleSchema,
 	name: TaskNameSchema,
 	task: TaskSchema,
+	kind: Type.Optional(DirectKindSchema),
 	model: Type.Optional(ModelSchema),
 	modelClass: Type.Optional(ModelClassSchema),
 }, { additionalProperties: false });
 
-export const WorkflowSchema = Type.Object({
+export const DirectWorkflowSchema = Type.Object({
+	mode: Type.Literal("direct"),
 	role: Type.Optional(RoleSchema),
 	name: Type.Optional(TaskNameSchema),
 	task: Type.Optional(TaskSchema),
+	kind: Type.Optional(DirectKindSchema),
 	model: Type.Optional(ModelSchema),
 	modelClass: Type.Optional(ModelClassSchema),
-	tasks: Type.Optional(Type.Array(DelegationSchema, {
-		minItems: 1,
-		maxItems: MAX_WORKFLOW_ENTRIES,
-		description: "Independent delegations to run concurrently",
-	})),
-	chain: Type.Optional(Type.Array(DelegationSchema, {
-		minItems: 1,
-		maxItems: MAX_WORKFLOW_ENTRIES,
-		description: "Dependent delegations to run sequentially",
-	})),
-	background: Type.Optional(Type.Boolean({ description: "Run the selected workflow without blocking" })),
-}, {
-	additionalProperties: false,
-	description: "Exactly one mode: role, name, and task; tasks; or chain",
-});
-
-export type Delegation = Static<typeof DelegationSchema>;
+	tasks: Type.Optional(Type.Array(DelegationSchema, { minItems: 1, maxItems: MAX_WORKFLOW_ENTRIES })),
+	chain: Type.Optional(Type.Array(DelegationSchema, { minItems: 1, maxItems: MAX_WORKFLOW_ENTRIES })),
+}, { additionalProperties: false, description: "Direct mode: exactly one compact single, tasks, or chain workflow" });
+
+export const DelegateTaskSchema = Type.Union([DirectWorkflowSchema, ExecuteRequestSchema]);
+export const WorkflowSchema = DirectWorkflowSchema;
+
+export type Delegation = Static<typeof DelegationSchema> & { kind: "text" };
 export type WorkflowMode = "single" | "parallel" | "chain";
 export type ParsedWorkflow =
-	| { mode: "single"; background: boolean; delegations: [Delegation] }
-	| { mode: "parallel"; background: boolean; delegations: Delegation[] }
-	| { mode: "chain"; background: boolean; delegations: Delegation[] };
+	| { mode: "single"; delegations: [Delegation] }
+	| { mode: "parallel"; delegations: Delegation[] }
+	| { mode: "chain"; delegations: Delegation[] };
+export type ParsedDelegateTask = { mode: "direct"; workflow: ParsedWorkflow } | { mode: "isolated"; request: ExecuteRequest };
 
-type WorkflowInput = Static<typeof WorkflowSchema>;
-
-const DELEGATION_KEYS = ["role", "name", "task", "model", "modelClass"] as const;
+type DirectInput = Static<typeof DirectWorkflowSchema>;
+const DELEGATION_KEYS = ["role", "name", "task", "kind", "model", "modelClass"] as const;
 
 function text(value: string, path: string): string {
 	const normalized = value.trim();
@@ -59,17 +55,18 @@ function text(value: string, path: string): string {
 	return normalized;
 }
 
-function normalizeDelegation(value: Delegation, path: string): Delegation {
+function normalizeDelegation(value: Static<typeof DelegationSchema>, path: string): Delegation {
 	return {
 		role: text(value.role, `${path}.role`),
 		name: normalizeTaskName(value.name, `${path}.name`),
 		task: text(value.task, `${path}.task`),
+		kind: "text",
 		...(value.model === undefined ? {} : { model: text(value.model, `${path}.model`) }),
 		...(value.modelClass === undefined ? {} : { modelClass: value.modelClass }),
 	};
 }
 
-function hasDelegation(value: WorkflowInput): value is WorkflowInput & Delegation {
+function hasDelegation(value: DirectInput): value is DirectInput & Static<typeof DelegationSchema> {
 	return Object.hasOwn(value, "role") && Object.hasOwn(value, "name") && Object.hasOwn(value, "task");
 }
 
@@ -78,108 +75,75 @@ function workflowMode(value: unknown): WorkflowMode | undefined {
 	const single = DELEGATION_KEYS.some((key) => Object.hasOwn(value, key));
 	const parallel = Object.hasOwn(value, "tasks");
 	const chain = Object.hasOwn(value, "chain");
-	if (Number(single) + Number(parallel) + Number(chain) !== 1) {
-		throw new Error("workflow must select exactly one mode: role, name, and task; tasks; or chain.");
-	}
+	if (Number(single) + Number(parallel) + Number(chain) !== 1) throw new Error("direct workflow must select exactly one of single, tasks, or chain.");
 	return single ? "single" : parallel ? "parallel" : "chain";
 }
 
 export function parseWorkflow(value: unknown): ParsedWorkflow {
 	const mode = workflowMode(value);
-	if (!Check(WorkflowSchema, value)) throw new Error("workflow must match the declared tool schema.");
-	if (!mode) throw new Error("workflow must select exactly one mode: role, name, and task; tasks; or chain.");
-	const input = value;
-	const background = input.background ?? false;
+	if (!Check(DirectWorkflowSchema, value)) {
+		const issue = Errors(DirectWorkflowSchema, value)[0];
+		throw new Error(`direct workflow must match the declared tool schema${issue ? ` at ${issue.instancePath || "/"}: ${issue.message}` : ""}. Direct mode is read-only; use mode isolated for changesets.`);
+	}
+	if (!mode) throw new Error("direct workflow must select exactly one of single, tasks, or chain.");
+	const input = value as DirectInput;
 	if (mode === "single") {
-		if (!hasDelegation(input)) throw new Error("workflow requires role, name, and task.");
-		return { mode, background, delegations: [normalizeDelegation(input, "workflow")] };
+		if (!hasDelegation(input)) throw new Error("direct workflow requires role, name, and task.");
+		return { mode, delegations: [normalizeDelegation(input, "workflow")] };
 	}
-	if (mode === "parallel") return {
-		mode,
-		background,
-		delegations: input.tasks!.map((delegation, index) => normalizeDelegation(delegation, `tasks[${index}]`)),
-	};
-	return {
-		mode,
-		background,
-		delegations: input.chain!.map((delegation, index) => normalizeDelegation(delegation, `chain[${index}]`)),
-	};
+	if (mode === "parallel") return { mode, delegations: input.tasks!.map((item, index) => normalizeDelegation(item, `tasks[${index}]`)) };
+	return { mode, delegations: input.chain!.map((item, index) => normalizeDelegation(item, `chain[${index}]`)) };
 }
 
-export type WorkflowEntry = {
-	id: string;
-	index: number;
-	delegation: Delegation;
-};
+export function parseDelegateTask(value: unknown): ParsedDelegateTask {
+	if (value && typeof value === "object" && !Array.isArray(value) && (value as { mode?: unknown }).mode === "isolated") {
+		return { mode: "isolated", request: parseExecuteRequest(value) };
+	}
+	return { mode: "direct", workflow: parseWorkflow(value) };
+}
 
+export type WorkflowEntry = { id: string; index: number; delegation: Delegation };
 export function identifyWorkflowEntries(toolCallId: string, workflow: ParsedWorkflow): WorkflowEntry[] {
-	return workflow.delegations.map((delegation, index) => ({
-		id: `${toolCallId}:${workflow.mode}:${index}`,
-		index,
-		delegation,
-	}));
+	return workflow.delegations.map((delegation, index) => ({ id: `${toolCallId}:${workflow.mode}:${index}`, index, delegation }));
 }
 
-export type DelegationExecution<T> =
-	| { ok: true; assistantOutput: string; result: T }
-	| { ok: false; result: T };
+export type DelegationRunner = (entry: WorkflowEntry) => string | Promise<string>;
 
-export type DelegationRunner<T> = (
-	entry: WorkflowEntry,
-) => DelegationExecution<T> | Promise<DelegationExecution<T>>;
-
-export type WorkflowEntryOutcome<T> =
-	| { status: "succeeded"; entry: WorkflowEntry; assistantOutput: string; result: T }
-	| { status: "failed"; entry: WorkflowEntry; result: T }
-	| { status: "rejected"; entry: WorkflowEntry; reason: unknown };
-
-async function runEntry<T>(entry: WorkflowEntry, run: DelegationRunner<T>): Promise<WorkflowEntryOutcome<T>> {
+async function runEntry(entry: WorkflowEntry, run: DelegationRunner): Promise<string | undefined> {
 	try {
-		const execution = await run(entry);
-		return execution.ok
-			? { status: "succeeded", entry, assistantOutput: execution.assistantOutput, result: execution.result }
-			: { status: "failed", entry, result: execution.result };
-	} catch (reason) {
-		return { status: "rejected", entry, reason };
+		return await run(entry);
+	} catch {
+		return undefined;
 	}
 }
 
-/** Run only foreground policy. Callback failures are `rejected`; parent aborts are rethrown after started work settles. */
-export async function runForegroundWorkflow<T>(
+export async function runForegroundWorkflow(
 	toolCallId: string,
 	workflow: ParsedWorkflow,
-	run: DelegationRunner<T>,
+	run: DelegationRunner,
 	signal?: AbortSignal,
-): Promise<WorkflowEntryOutcome<T>[]> {
-	if (workflow.background) throw new Error("Background workflows cannot use foreground orchestration.");
+): Promise<void> {
 	signal?.throwIfAborted();
 	const entries = identifyWorkflowEntries(toolCallId, workflow);
 	if (workflow.mode === "single") {
-		const outcome = await runEntry(entries[0]!, run);
+		await runEntry(entries[0]!, run);
 		signal?.throwIfAborted();
-		return [outcome];
+		return;
 	}
 	if (workflow.mode === "parallel") {
-		const outcomes = await Promise.all(entries.map((entry) => runEntry(entry, run)));
+		await Promise.all(entries.map((entry) => runEntry(entry, run)));
 		signal?.throwIfAborted();
-		return outcomes;
+		return;
 	}
-
-	const outcomes: WorkflowEntryOutcome<T>[] = [];
 	let previous = "";
 	for (const entry of entries) {
-		const chained = {
+		const selected = {
 			...entry,
-			delegation: {
-				...entry.delegation,
-				task: entry.delegation.task.replaceAll("{previous}", () => previous),
-			},
+			delegation: { ...entry.delegation, task: entry.delegation.task.replaceAll("{previous}", () => previous) },
 		};
-		const outcome = await runEntry(chained, run);
+		const output = await runEntry(selected, run);
 		signal?.throwIfAborted();
-		outcomes.push(outcome);
-		if (outcome.status !== "succeeded") break;
-		previous = outcome.assistantOutput;
+		if (output === undefined) break;
+		previous = output;
 	}
-	return outcomes;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@henryqw/pi-subagent",
-  "version": "18.0.1",
-  "description": "Delegate bounded single, parallel, or chained tasks to isolated Pi roles.",
+  "version": "22.0.1",
+  "description": "Delegate bounded direct work or durable checked isolated task graphs to Pi roles.",
   "keywords": [
     "pi-package",
     "pi",
@@ -19,8 +19,10 @@
     "extensions",
     "docs",
     "examples",
+    "example.png",
     "README.md",
-    "CONTEXT.md"
+    "CONTEXT.md",
+    "skills"
   ],
   "types": "./dist/index.d.ts",
   "exports": {
@@ -58,17 +60,23 @@
     "extensions": [
       "./extensions/subagent.ts"
     ],
+    "skills": [
+      "./skills"
+    ],
     "image": "https://raw.githubusercontent.com/HenryQW/pi-harness/main/extensions/pi-subagent/example.png"
   },
   "dependencies": {
     "@henryqw/pi-config-store": "^2.0.0",
+    "@henryqw/pi-herdr": "^0.4.7",
     "@henryqw/pi-multi-codex": "^2.0.0",
-    "@henryqw/pi-process": "^0.1.0",
-    "@henryqw/pi-task-models": "^7.0.0"
+    "@henryqw/pi-process": "^0.2.0",
+    "@henryqw/pi-task-models": "^7.0.0",
+    "proper-lockfile": "^4.1.2"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "0.87.0",
     "@earendil-works/pi-coding-agent": "0.87.0",
-    "@earendil-works/pi-tui": "0.87.0"
+    "@earendil-works/pi-tui": "0.87.0",
+    "@types/proper-lockfile": "^4.1.4"
   }
 }

package/skills/pi-subagent/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: pi-subagent
+description: Delegate bounded direct work or run durable checked isolated task graphs.
+---
+
+# Choose and authorize delegation
+
+Use this Skill only from Main.
+
+Record the requested outcome, allowed scope and exclusions, local delegation/check/review/integration permission, and any external-action permission before substantial work. A clear small request can supply this authorization directly. Ask again only for a material scope or contract change, a missing decision or authorization, a user-owned conflict, or a consequential action outside that scope.
+
+Keep trivial, mechanically verifiable work in Main. Choose the user-requested mode when one is explicit. Otherwise:
+
+- Use `mode: direct` for bounded read-only research, analysis, and review with known read-only Roles.
+- Use `mode: isolated` for implementation and other writing tasks, independently checked changes, or an exploratory or discardable candidate. A single isolated task is valid.
+- Keep one implementation owner for tightly coupled work. Size alone does not justify splitting it.
+- Never silently fall back from isolated to direct. Scope growth requires a checkpoint and replan, not migration of dirty work.
+
+Roles describe responsibility and capabilities; they do not select isolation. Bash, MCP tools, unknown tools, and arbitrary extensions are potentially writing. The checkout coordinator reduces races among Pi-owned calls but is not an OS sandbox and cannot control external processes.
+
+# Direct requests
+
+Use one compact `role`/`name`/`task` packet, `tasks` for independent packets, or `chain` for dependent packets. Only text tasks are accepted; a write-capable Role, `kind: changeset`, checks, and judgment require isolated mode. The tool returns a handle after launching Herdr tabs in the current workspace. Main receives the verified result as a follow-up after the workflow finishes, without interrupting an active turn. If observation stops, open `/subagent` to inspect exact recorded tabs and session files on this session branch; recorded does not prove still running.
+
+# Isolated requests
+
+Give the request a unique ID and goal. Give each task a unique ID, kind, Role, model class, bounded requirements, deliverable, `dependsOn`, and `contextFrom`. Changesets require focused task checks, and a graph containing changesets requires final checks. The root must have a `package.json` test script; `pnpm test` is added to final checks if missing and runs against the combined tip before Main promotion. Text context may name only completed text tasks and preserves declared order.
+
+Every changeset advances automatically after preliminary checks pass. While a locally owned changeset task is actively working, the user may open `/subagent` to queue bounded same-worker revisions or withdraw all still-pending instructions into the native editor and submit one replacement. Cancellation after withdrawal leaves the originals removed; already-claimed instructions cannot be recalled. Each revision must produce a new clean commit and rerun preliminary checks. When no queued revision remains, the runner seals and durably records the exact ready candidate without waiting for input. There is no guaranteed post-completion editing window, and late follow-ups fail visibly.
+
+A ready candidate does not integrate automatically. Inspect `subagent_status` and use `subagent_stage` with the exact `generation`, `taskId`, `attempt`, candidate `tip`, and `expectedTip` to select and merge candidates into the owned integration checkout in explicit order. Resolve conflicts there and verify with `resolve`; never edit Main to resolve them. For dependents, `subagent_integrate advance` runs ready tasks against the exact staged snapshot. When selected work is staged, use `subagent_integrate validate` on the exact `combinedTip` for full root checks and optional final judgment; `promote` requires passing evidence and unchanged Main. One Main-authored committed correction to a definitively failed combined validation can be recorded with `correct`, then revalidated. Only proven promotion triggers selected-worker termination and verified cleanup. Failures, ambiguity, conflicts, interruption, child-limit exhaustion, or Main drift retain work and never waive checks or identity guards. The extension never pushes, opens a pull request, publishes, or deploys.
+
+Use `subagent_status` to inspect durable state without mutation, including candidate identities, generations, and retained resources. `subagent_resume` handles only the reported retry/verify/finalize continuation; it cannot replace Main's stage/integrate decisions or reset policy/corrections. `subagent_stage reject` or `revise` freezes a generation containing the candidate and invalidates dependent attempts; restage chosen work in a new generation. If Main advances cleanly before promotion, use `subagent_integrate refresh` with exact old/new Main and combined-tip identities; restage immutable candidates into the new generation and rerun combined validation. Dirty or divergent Main blocks refresh. At most two unreleased integration worktrees may coexist. Rejected candidates and superseded generations remain retained until Main explicitly calls `subagent_integrate release` with the exact generation and tip; for a rejected worker include its task ID and attempt after releasing all generations using it. Dirty/conflicted or unproved resources block release without force deletion. Impossible fresh dependent work after rejection needs a new request. `subagent_abort` cannot discard retained candidates or integration generations; it may finish once all are released. Old v4 state is rejected (current state is v5), not migrated. Status, abort, process I/O, termination, and verified post-promotion cleanup keep finite safety budgets.
+
+All launches use the global policy in `config/pi-subagent/config.json`: productive concurrency, per-child turns/tokens, and idle timeout. Ephemeral children also have a hard runtime limit; isolated requests have a correction cap. Productive requests have no whole-run wall-clock deadline. Request fields cannot replenish or override limits.