@selesai/code 0.8.3 → 0.8.4

package/dist/extensions/pi-subagents/test/unit/workflow-launch-params.test.ts

@@ -0,0 +1,113 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { prepareWorkflowLaunchParams } from "../../src/runs/foreground/subagent-executor.ts";
+
+describe("workflow launch params", () => {
+	it("keeps omitted workflow child async foreground", () => {
+		assert.deepEqual(
+			prepareWorkflowLaunchParams(
+				{},
+				{ agent: "worker", task: "Run" },
+				"workflow-run",
+				"run",
+			),
+			{
+				agent: "worker",
+				task: "Run",
+				async: false,
+				workflowParentRunId: "workflow-run",
+				workflowKey: "run",
+			},
+		);
+	});
+
+	it("preserves explicit async workflow children", () => {
+		assert.deepEqual(
+			prepareWorkflowLaunchParams(
+				{},
+				{ agent: "worker", task: "Run", async: true },
+				"workflow-run",
+				"run",
+			),
+			{
+				agent: "worker",
+				task: "Run",
+				async: true,
+				workflowParentRunId: "workflow-run",
+				workflowKey: "run",
+			},
+		);
+	});
+
+	it("places workflow child gates inside managed worktree tasks", () => {
+		assert.deepEqual(
+			prepareWorkflowLaunchParams(
+				{},
+				{ agent: "worker", task: "Implement", worktree: true, gate: "npm test" },
+				"workflow-run",
+				"gated",
+			),
+			{
+				worktree: true,
+				async: false,
+				workflowParentRunId: "workflow-run",
+				workflowKey: "gated",
+				tasks: [{
+					agent: "worker",
+					task: "Implement",
+					acceptance: { level: "verified", verify: [{ id: "gate", command: "npm test" }] },
+				}],
+			},
+		);
+	});
+
+	it("rejects gate defaults on retained resume items", () => {
+		assert.throws(
+			() => prepareWorkflowLaunchParams(
+				{ gate: "npm test" },
+				{ resume: "retained-run", task: "Continue" },
+				"workflow-run",
+				"continue",
+			),
+			/gate is not supported with retained resume/,
+		);
+		assert.throws(
+			() => prepareWorkflowLaunchParams(
+				{},
+				{ resume: "retained-run", task: "Continue", gate: "npm test" },
+				"workflow-run",
+				"continue",
+			),
+			/gate is not supported with retained resume/,
+		);
+	});
+
+	it("preserves execution limits when routing retained resume items", () => {
+		assert.deepEqual(
+			prepareWorkflowLaunchParams(
+				{ turnBudget: { maxTurns: 8 }, toolBudget: { hard: 12, block: ["read"] } },
+				{
+					resume: " retained-run ",
+					task: "Continue carefully",
+					maxRuntimeMs: 5_000,
+					turnBudget: { maxTurns: 3, graceTurns: 1 },
+					toolBudget: { soft: 2, hard: 4, block: "*" },
+				},
+				"workflow-run",
+				"continue",
+				{ missionDetached: true },
+			),
+			{
+				action: "resume",
+				id: "retained-run",
+				message: "Continue carefully",
+				workflowParentRunId: "workflow-run",
+				workflowKey: "continue",
+				mission: false,
+				timeoutMs: 5_000,
+				turnBudget: { maxTurns: 3, graceTurns: 1 },
+				toolBudget: { soft: 2, hard: 4, block: "*" },
+			},
+		);
+	});
+});

package/dist/extensions/pi-subagents/test/unit/worktree.test.ts

@@ -178,8 +178,8 @@ describe("worktree", () => {
 		assert.equal(
 			findWorktreeTaskCwdConflict(
 				[
-					{ agent: "builder-a" },
-					{ agent: "builder-b", cwd: sharedCwd },
+					{ agent: "worker-a" },
+					{ agent: "worker-b", cwd: sharedCwd },
 				],
 				sharedCwd,
 			),
@@ -191,7 +191,7 @@ describe("worktree", () => {
 		const sharedCwd = path.join("/tmp", "repo");
 		assert.equal(
 			findWorktreeTaskCwdConflict(
-				[{ agent: "builder-a", cwd: "." }],
+				[{ agent: "worker-a", cwd: "." }],
 				sharedCwd,
 			),
 			undefined,
@@ -202,14 +202,14 @@ describe("worktree", () => {
 		const sharedCwd = path.join("/tmp", "repo");
 		const conflict = findWorktreeTaskCwdConflict(
 			[
-				{ agent: "builder-a", cwd: sharedCwd },
-				{ agent: "builder-b", cwd: path.join(sharedCwd, "packages", "app") },
+				{ agent: "worker-a", cwd: sharedCwd },
+				{ agent: "worker-b", cwd: path.join(sharedCwd, "packages", "app") },
 			],
 			sharedCwd,
 		);
 		assert.deepEqual(conflict, {
 			index: 1,
-			agent: "builder-b",
+			agent: "worker-b",
 			cwd: path.join(sharedCwd, "packages", "app"),
 		});
 	});
@@ -338,7 +338,7 @@ describe("worktree", () => {
 			setup = createWorktrees(repoDir, "captured", 1);
 			const worktreePath = setup.worktrees[0]!.path;
 			fs.writeFileSync(path.join(worktreePath, "tracked.txt"), "captured\n", "utf-8");
-			const diffs = diffWorktrees(setup, ["builder"], path.join(repoDir, "artifacts", "captured"));
+			const diffs = diffWorktrees(setup, ["worker"], path.join(repoDir, "artifacts", "captured"));
 			assert.equal(diffs[0]?.error, undefined);
 			assert.ok(fs.statSync(diffs[0]!.patchPath).size > 0);
 

package/dist/extensions/pi-subagents/test/unit/writer-budget-guidance.test.ts

@@ -7,11 +7,11 @@ const readProjectFile = (file: string): string => readFileSync(join(process.cwd(
 
 describe("writer budget guidance", () => {
 	it("keeps hard turn and tool caps off mutation-capable workers", () => {
-		const readme = readProjectFile("README.md");
+		const toolReference = readProjectFile("docs/tool-reference.md");
 		const skill = readProjectFile("skills/pi-subagents/SKILL.md");
 		const reviewLoop = readProjectFile("prompts/review-loop.md");
 
-		for (const text of [readme, skill, reviewLoop]) {
+		for (const text of [toolReference, skill, reviewLoop]) {
 			assert.match(text, /As a conservative orchestration policy, do not (?:pass|set) `turnBudget`(?:, a hard `toolBudget`, or a tight `usageBudget`| or a hard `toolBudget`)/);
 			assert.match(text, /default tool budget blocks read\/search tools rather than mutation tools/i);
 			assert.match(text, /checkpoint after the current tool returns/);
@@ -19,12 +19,12 @@ describe("writer budget guidance", () => {
 			assert.match(text, /build\/test state/);
 			assert.match(text, /commit or PR state/);
 		}
-		assert.match(readme, /elapsed timeout is not a mutation-safe boundary/i);
+		assert.match(toolReference, /elapsed timeout is not a mutation-safe boundary/i);
 	});
 
 	it("documents deferred hard-limit termination at tool-using boundaries", () => {
-		const readme = readProjectFile("README.md");
-		assert.match(readme, /termination occurs at the next assistant boundary/);
-		assert.match(readme, /`termination-deferred`/);
+		const toolReference = readProjectFile("docs/tool-reference.md");
+		assert.match(toolReference, /termination occurs at the next assistant boundary/);
+		assert.match(toolReference, /`termination-deferred`/);
 	});
 });

package/dist/extensions/workflow/extension.ts

@@ -1,24 +1,26 @@
-// ponytail: single pi extension that mounts every workflow mode. One load
-// resolves a single writer tool + N start/end tool pairs. Avoids the per-mode
-// load conflict (multiple extension modules would each try to register the
-// shared writer).
+// ponytail: thin shell. Registers the four /workflow-* commands and launches
+// each mode's scripted workflow through pi-subagents' launchSlashSubagent.
 
 import type { ExtensionAPI } from "@selesai/code";
-import { __resetWorkflowRegistryForTests, createWorkflowExtension } from "./adapter.ts";
-import { prototypeMode } from "./modes/prototype.ts";
-import { quicktypeMode } from "./modes/quicktype.ts";
-import { taskMode } from "./modes/task.ts";
-import { loopMode } from "./modes/loop.ts";
-
-export { __resetWorkflowRegistryForTests };
-
-const MODES = [prototypeMode, quicktypeMode, taskMode, loopMode] as const;
+import { launchSlashSubagent } from "../pi-subagents/src/slash/slash-commands.ts";
+import { buildLoopScript, buildPrototypeScript, buildQuicktypeScript, buildTaskScript } from "./modes.ts";
 
 export default function workflowModesExtension(pi: ExtensionAPI): void {
-  for (const mode of MODES) {
-    createWorkflowExtension(mode.config, {
-      commandName: mode.commandName,
-      commandDescription: mode.commandDescription,
-    })(pi);
-  }
+  const register = (name: string, description: string, build: (goal: string) => string) =>
+    pi.registerCommand(name, {
+      description,
+      handler: async (args, ctx) => {
+        const goal = args.trim();
+        if (!goal) {
+          ctx.ui.notify(`${description}\nUsage: /${name} <goal>`, "info");
+          return;
+        }
+        launchSlashSubagent(pi, ctx, { workflowScript: build(goal), async: true, agentScope: "both" });
+      },
+    });
+
+  register("workflow-task", "Run the task workflow (plan → reuse → handoff → auto build↔review loop) as a scripted workflow.", buildTaskScript);
+  register("workflow-prototype", "Run the full prototype workflow (research → plan → reuse → handoff → auto loop → audit) as a scripted workflow.", buildPrototypeScript);
+  register("workflow-quicktype", "Run the quicker prototype workflow without research (plan → reuse → handoff → auto loop → audit) as a scripted workflow.", buildQuicktypeScript);
+  register("workflow-loop", "Run a direct auto build↔review loop for an already-agreed plan as a scripted workflow.", buildLoopScript);
 }

package/dist/extensions/workflow/modes.ts

@@ -0,0 +1,65 @@
+// ponytail: four workflow modes as pi-subagents workflowScript builders.
+// One-shot-and-sleep: phases run as runs.run steps and the loop auto-repeats
+// until the reviewer reports clean. A workflowScript has no checkpoints, so
+// there are no human gates.
+
+function js(value: string): string {
+  return JSON.stringify(value);
+}
+
+const AUTO_LOOP = String.raw`
+const autoLoop = async (goal, context) => {
+  let round = 1;
+  while (true) {
+    const build = await runs.run('build-' + round, {
+      agent: 'builder',
+      task: 'Implement the approved work in the workspace and run relevant checks.\n\nSource of truth (handoff/plan):\n' + context + '\n\nGoal:\n' + goal + (round > 1 ? '\n\nAddress the previous review feedback first.' : ''),
+    });
+    const review = await runs.run('review-' + round, {
+      agent: 'commentator',
+      task: 'Independently review the uncommitted diff and report concrete evidence (what you inspected and what you ran). Do not modify the workspace.\n\nAcceptance criteria (source of truth):\n' + context + '\n\nBuilder completion summary:\n' + build.output + '\n\nEnd with exactly one line: WORKFLOW_REVIEW_STATUS: clean OR WORKFLOW_REVIEW_STATUS: blocking.',
+    });
+    if (/WORKFLOW_REVIEW_STATUS\s*:\s*clean/i.test(review.output)) {
+      return { result: 'clean', rounds: round };
+    }
+    round += 1;
+  }
+};`;
+
+export function buildLoopScript(goal: string): string {
+  return String.raw`const goal = ${js(goal)};
+${AUTO_LOOP}
+return await autoLoop(goal, goal);`;
+}
+
+export function buildTaskScript(goal: string): string {
+  return String.raw`const goal = ${js(goal)};
+const plan = await runs.run('plan', { agent: 'architect', task: 'Produce a concrete implementation plan for: ' + goal + '. Cover what to build, how, in what order, which files and components, and the finished result. Return inline.' });
+const reuse = await runs.run('reuse', { agent: 'explorer', task: 'Explore the codebase for reusable patterns relevant to: ' + plan.output + '. Point at relevant areas and dependencies; skip cleanly if wholly new. Return inline.' });
+const handoff = await runs.run('handoff', { agent: 'recapper', task: 'Compile a self-contained handoff from the plan and reuse findings so fresh agents understand the goal, constraints, and acceptance criteria without re-planning.\n\nPlan:\n' + plan.output + '\n\nReuse findings:\n' + reuse.output + '\n\nReturn inline.' });
+${AUTO_LOOP}
+return await autoLoop(goal, handoff.output);`;
+}
+
+export function buildPrototypeScript(goal: string): string {
+  return String.raw`const goal = ${js(goal)};
+const research = await runs.run('research', { agent: 'researcher', task: 'Research the external, fast-changing knowledge this task depends on (libraries, SDKs, APIs, unfamiliar alternatives). Task: ' + goal + '. Synthesize actionable findings with sources. Return inline.' });
+const plan = await runs.run('plan', { agent: 'architect', task: 'Produce a concrete build plan from the research findings.\n\nResearch:\n' + research.output + '\n\nRequest:\n' + goal + '\n\nReturn inline.' });
+const reuse = await runs.run('reuse', { agent: 'explorer', task: 'Explore the codebase for reusable patterns relevant to: ' + plan.output + '. Return inline.' });
+const handoff = await runs.run('handoff', { agent: 'recapper', task: 'Compile a self-contained handoff from the plan and reuse findings.\n\nPlan:\n' + plan.output + '\n\nReuse:\n' + reuse.output + '\n\nReturn inline.' });
+${AUTO_LOOP}
+const loop = await autoLoop(goal, handoff.output);
+const audit = await runs.run('audit', { agent: 'commentator', task: 'Final audit of the uncommitted changes for correctness, plan adherence, and over-engineering (cut bloat, dead flexibility, reinvented stdlib). Plan:\n' + plan.output + '\n\nReport concrete evidence. Do not modify the workspace.' });
+return { ...loop, audited: true };`;
+}
+
+export function buildQuicktypeScript(goal: string): string {
+  return String.raw`const goal = ${js(goal)};
+const plan = await runs.run('plan', { agent: 'architect', task: 'Produce a concrete build plan for: ' + goal + '. Cover what to build, how, in what order, which components, and the finished result. Return inline.' });
+const reuse = await runs.run('reuse', { agent: 'explorer', task: 'Explore the codebase for reusable patterns relevant to: ' + plan.output + '. Return inline.' });
+const handoff = await runs.run('handoff', { agent: 'recapper', task: 'Compile a self-contained handoff from the plan and reuse findings.\n\nPlan:\n' + plan.output + '\n\nReuse:\n' + reuse.output + '\n\nReturn inline.' });
+${AUTO_LOOP}
+const loop = await autoLoop(goal, handoff.output);
+const audit = await runs.run('audit', { agent: 'commentator', task: 'Final audit of the uncommitted changes for correctness, plan adherence, and over-engineering (cut bloat, dead flexibility, reinvented stdlib). Plan:\n' + plan.output + '\n\nReport concrete evidence. Do not modify the workspace.' });
+return { ...loop, audited: true };`;
+}

package/dist/skills/pi-subagents/SKILL.md

@@ -2,17 +2,24 @@
 name: pi-subagents
 description: |
   Delegate work to builtin or custom subagents with single-agent, chain,
-  parallel, async, forked-context, and intercom-coordinated workflows. Use
-  for advisory review, implementation handoffs, and multi-step tasks where a
-  single agent should stay in control while other agents contribute context,
-  planning, or execution.
+  parallel, scripted, async, forked-context, mission-backed, and
+  intercom-coordinated workflows. Use for advisory review, implementation
+  handoffs, and multi-step tasks where a single agent stays in control while
+  other agents contribute context, planning, or execution.
 ---
 
 # Pi Subagents
 
-This skill is for the main parent orchestrator only. Do not inject or follow it inside spawned child subagents. The parent session owns delegation, orchestration, review fanout, and final fix-builder launches. Ordinary children should not run their own subagent workflows; the explicit exception is a delegated fanout child whose resolved builtin `tools` includes `subagent`, and that child may use `subagent` only for the fanout work the parent assigned.
+This skill is for the main parent orchestrator only. Do not inject or follow it inside spawned child subagents. The parent session owns delegation, orchestration, review fanout, and final fix-worker launches. Ordinary children should not run their own subagent workflows; the explicit exception is a delegated fanout child whose resolved builtin `tools` includes `subagent`, and that child may use `subagent` only for the fanout work the parent assigned.
 
-Use this skill when the parent orchestrator needs to launch a specialized subagent, compose multiple agents into a workflow, or create/edit agents and chains on demand.
+Use this skill when the parent orchestrator needs one specialized child or composed orchestration. The `subagent` tool has four first-class execution modes:
+
+- **SINGLE** — `{ agent, task }` for one child (omit `task` for a self-contained agent).
+- **CHAIN** — `{ chain: [{ agent, task }, ...] }` for sequential steps with `{previous}`, `{outputs.name}`, `phase`/`label`, `outputSchema`, and `{ checkpoint: "name" }` human gates.
+- **PARALLEL** — `{ tasks: [{ agent, task }, ...], concurrency? }` for top-level parallel children, plus in-chain `{ parallel: [...] }` groups and dynamic `expand`/`collect` fanout.
+- **SCRIPTED WORKFLOW** — `{ workflowScript }` with `runs.run`/`runs.all` and ordinary JavaScript for sequence, parallelism, branching, retries, gate monitors, and aggregation. Use `return runs.run("main", { agent, task })` for one child and `runs.all([...])` for coordinated waves. Scripts start asynchronously by default; pass `async:false` only for a small foreground run.
+
+Prefer the declarative modes when the shape is known up front; reach for `workflowScript` when coordination needs dynamic branching or aggregation. Saved `.chain.md` / `.chain.json` workflows (run with `/run-chain`) make repeatable multi-agent flows shareable without rewriting the chain each time.
 
 ## How to use this router
 
@@ -21,23 +28,21 @@ Read the matching reference file before acting. Paths are relative to this `SKIL
 | Task | Read |
 | --- | --- |
 | Decide whether to delegate, choose agents, compare tool versus slash commands, apply prompt techniques, or understand builtin roles | `references/prompting-and-roles.md` |
-| Run single, parallel, chain, async, scheduled, forked, worktree, watchdog, clarify, commentator, or intercom-coordinated workflows | `references/execution-controls.md` |
+| Run single, chain, parallel, scripted, async, scheduled, mission-backed, forked, worktree, watchdog, clarify, oracle, or intercom-coordinated workflows | `references/execution-controls.md` |
 | List/create/update/delete/eject/disable agents or chains, edit agent files, use prompt-template integration, or expose extension RPC | `references/management-authoring-rpc.md` |
 | Check safety constraints, best practices, standard workflows, or error handling | `references/constraints-and-recipes.md` |
 
-Selesai default: use Fable-style parent orchestration for complex work (multiple moving parts, unclear acceptance, cross-cutting code, meaningful user impact, expensive validation, or broad review surface). Lightweight one-off delegation stays lightweight.
-
-Routing rule: keep tiny targeted reads and simple answers with the parent. For broad local investigation, external research, or mutation work, call `{ action: "list" }`, choose an executable entry from its runtime metadata, then delegate. Treat list output—not hardcoded role names—as the agent-selection authority.
-
 For broad or uncertain requests, read more than one reference. For complex work, start with `references/prompting-and-roles.md` and `references/execution-controls.md`, then consult `references/constraints-and-recipes.md` before launching or reviewing child work.
 
 ## Always-on constraints
 
 - Keep the parent as orchestrator and final decision-maker.
 - Use one writer per cwd/worktree unless isolated worktrees are intentional.
-- For parallel fanout, compare child prompts before launch. Do not send clone prompts with only issue numbers, titles, or broad file globs swapped; each child needs a lane-specific task, source seam, prior evidence, and decision that remains distinct without the item number.
+- For cross-codebase work, record the target repo, explicit `cwd`, authority boundary, and expected output before launch. Do not assume the parent session cwd is the child repo.
+- For parallel fanout, compare child prompts before launch. Do not send clone prompts with only issue numbers, titles, or broad file globs swapped; each child needs a lane-specific task, source seam, prior evidence, and decision that remains distinct without the item number. Launch that fanout as one async `workflowScript` or parallel `tasks` group with stable keys and aggregate output unless there is truly only one child.
 - Prefer fresh-context review/validation fanout, then synthesize and apply fixes in the parent.
-- Use async/background only when work can proceed independently; do not poll just to wait. For planned human gates in chains, use `{ checkpoint: "name", message?: "..." }` and approve or reject paused async checkpoints with `approve-checkpoint` / `reject-checkpoint`.
+- Use async/background by default when work can proceed independently; do not poll just to wait. For planned human gates, use `{ checkpoint: "name", message?: "..." }` chain steps and approve or reject paused checkpoints with `approve-checkpoint` / `reject-checkpoint`. For adaptive gates, branch in `workflowScript`.
 - Preserve capability ceilings, including child tool restrictions and session-scoped allowed-agent restrictions.
-- Escalate unresolved product, architecture, or safety decisions upward instead of letting a child decide silently.
-- As a conservative orchestration policy, do not pass `turnBudget`, a hard `toolBudget`, or a tight `usageBudget` to mutation-capable builders. The default tool budget blocks read/search tools rather than mutation tools, and reported usage has no reservation model. If a builder is interrupted after a tool call starts, checkpoint after the current tool returns with changed files, build/test state, and commit or PR state.
+- Escalate unresolved product, architecture, authority, release, merge, or safety decisions upward instead of letting a child decide silently.
+- Treat receipts, CI, review bots, and external-run records as evidence, not authority to merge, close, comment, publish, or release.
+- As a conservative orchestration policy, do not pass `turnBudget`, a hard `toolBudget`, or a tight `usageBudget` to mutation-capable workers. The default tool budget blocks read/search tools rather than mutation tools, and reported usage has no reservation model. If a worker is interrupted after a tool call starts, checkpoint after the current tool returns with changed files, build/test state, and commit or PR state.