221 lines
7.0 KiB
Markdown
221 lines
7.0 KiB
Markdown
# Subagent Wrapper Semantic Completion Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Ensure the subagent tool completes once the wrapper has seen terminal assistant output, even if the spawned `pi` child process lingers instead of exiting promptly.
|
|
|
|
**Architecture:** Keep the fix on the smallest shared surface: `src/wrapper/cli.mjs`. Add a short grace-and-cleanup path that starts only after a terminal normalized `assistant_text` event, preserve the semantic result data already captured from that event, and leave monitor, runner selection, schema, and tmux helpers unchanged. Cover the behavior with a regression test in `src/wrapper/cli.test.ts` that reproduces the current stuck state.
|
|
|
|
**Tech Stack:** Node.js `child_process`, `fs/promises`, ESM `.mjs`, `tsx --test`, Pi JSON event normalization
|
|
|
|
---
|
|
|
|
## Worktree and file structure
|
|
|
|
This plan assumes work happens in a dedicated worktree already created during brainstorming.
|
|
|
|
**Modify**
|
|
- `src/wrapper/cli.test.ts` — add regression coverage for terminal output followed by a lingering child process
|
|
- `src/wrapper/cli.mjs` — add wrapper-internal grace period and forced cleanup after semantic completion
|
|
|
|
**Do not modify**
|
|
- `src/monitor.ts`
|
|
- `src/process-runner.ts`
|
|
- `src/tmux-runner.ts`
|
|
- `src/tmux.ts`
|
|
- model/schema/tool registration files
|
|
|
|
### Task 1: Finish lingering wrapper runs after terminal assistant output
|
|
|
|
**Files:**
|
|
- Modify: `src/wrapper/cli.test.ts`
|
|
- Modify: `src/wrapper/cli.mjs`
|
|
- Test: `src/wrapper/cli.test.ts`
|
|
|
|
- [ ] **Step 1: Write the failing regression test**
|
|
|
|
Add this test near the other wrapper regression tests in `src/wrapper/cli.test.ts`:
|
|
|
|
```ts
|
|
test("wrapper exits and writes result.json after terminal output even if the pi child lingers", async () => {
|
|
const dir = await mkdtemp(join(tmpdir(), "pi-subagents-wrapper-"));
|
|
const metaPath = join(dir, "meta.json");
|
|
const resultPath = join(dir, "result.json");
|
|
const piPath = join(dir, "pi");
|
|
|
|
await writeFile(
|
|
piPath,
|
|
[
|
|
`#!${process.execPath}`,
|
|
"console.log(JSON.stringify({type:'message_end',message:{role:'assistant',content:[{type:'text',text:'done'}],model:'openai/gpt-5',stopReason:'stop'}}));",
|
|
"setTimeout(() => {}, 10_000);",
|
|
].join("\n"),
|
|
"utf8",
|
|
);
|
|
await chmod(piPath, 0o755);
|
|
|
|
await writeFile(
|
|
metaPath,
|
|
JSON.stringify(
|
|
{
|
|
runId: "run-1",
|
|
mode: "single",
|
|
agent: "scout",
|
|
agentSource: "builtin",
|
|
task: "inspect auth",
|
|
cwd: dir,
|
|
requestedModel: "openai/gpt-5",
|
|
resolvedModel: "openai/gpt-5",
|
|
startedAt: "2026-04-09T00:00:00.000Z",
|
|
sessionPath: join(dir, "child-session.jsonl"),
|
|
eventsPath: join(dir, "events.jsonl"),
|
|
resultPath,
|
|
stdoutPath: join(dir, "stdout.log"),
|
|
stderrPath: join(dir, "stderr.log"),
|
|
transcriptPath: join(dir, "transcript.log"),
|
|
systemPromptPath: join(dir, "system-prompt.md"),
|
|
},
|
|
null,
|
|
2,
|
|
),
|
|
"utf8",
|
|
);
|
|
|
|
const wrapperPath = join(dirname(fileURLToPath(import.meta.url)), "cli.mjs");
|
|
const child = spawn(process.execPath, [wrapperPath, metaPath], {
|
|
env: { ...process.env, PATH: dir },
|
|
stdio: ["ignore", "pipe", "pipe"],
|
|
});
|
|
|
|
const exitCode = await waitForExit(child);
|
|
assert.equal(exitCode, 0);
|
|
|
|
const result = JSON.parse(await readFile(resultPath, "utf8"));
|
|
assert.equal(result.exitCode, 0);
|
|
assert.equal(result.stopReason, "stop");
|
|
assert.equal(result.finalText, "done");
|
|
assert.equal(result.resolvedModel, "openai/gpt-5");
|
|
});
|
|
```
|
|
|
|
- [ ] **Step 2: Run the wrapper tests to verify the new test fails for the right reason**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
npx tsx --test src/wrapper/cli.test.ts
|
|
```
|
|
|
|
Expected: FAIL in the new test with `wrapper did not exit within 1500ms` from `waitForExit`, proving the wrapper still waits forever after terminal output when the child process lingers.
|
|
|
|
- [ ] **Step 3: Add shared timing helpers at the top of the wrapper**
|
|
|
|
Insert these declarations near the top of `src/wrapper/cli.mjs`, below the imports:
|
|
|
|
```js
|
|
const SEMANTIC_EXIT_GRACE_MS = 250;
|
|
const FORCED_EXIT_GRACE_MS = 250;
|
|
|
|
async function sleep(ms) {
|
|
await new Promise((resolve) => setTimeout(resolve, ms));
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Wire terminal-event cleanup into `runWrapper` with the smallest shared change**
|
|
|
|
Make these exact edits inside `src/wrapper/cli.mjs`.
|
|
|
|
Add the new wrapper state immediately after the existing local state declarations inside `runWrapper`:
|
|
|
|
```js
|
|
let childClosed = false;
|
|
let completionCleanupStarted = false;
|
|
let child;
|
|
|
|
const forceChildExitAfterSemanticCompletion = async () => {
|
|
if (completionCleanupStarted) return;
|
|
completionCleanupStarted = true;
|
|
|
|
await sleep(SEMANTIC_EXIT_GRACE_MS);
|
|
if (childClosed) return;
|
|
|
|
child.kill("SIGTERM");
|
|
|
|
await sleep(FORCED_EXIT_GRACE_MS);
|
|
if (childClosed) return;
|
|
|
|
child.kill("SIGKILL");
|
|
};
|
|
```
|
|
|
|
Change the `assistant_text` branch in `handleStdoutLine` to preserve the captured semantic result and trigger cleanup only when a terminal stop reason is present:
|
|
|
|
```js
|
|
if (normalized.type === "assistant_text") {
|
|
finalText = normalized.text;
|
|
resolvedModel = normalized.model ?? resolvedModel;
|
|
stopReason = normalized.stopReason ?? stopReason;
|
|
usage = normalized.usage ?? usage;
|
|
|
|
if (normalized.stopReason) {
|
|
void forceChildExitAfterSemanticCompletion();
|
|
}
|
|
}
|
|
```
|
|
|
|
Change the child spawn assignment from `const child = spawn(...)` to:
|
|
|
|
```js
|
|
child = spawn("pi", args, {
|
|
cwd: meta.cwd,
|
|
env: childEnv,
|
|
stdio: ["ignore", "pipe", "pipe"],
|
|
});
|
|
```
|
|
|
|
Update the exit handlers so the cleanup helper can see when the child has already finished naturally:
|
|
|
|
```js
|
|
child.on("error", (error) => {
|
|
spawnError = error;
|
|
childClosed = true;
|
|
finish(1);
|
|
});
|
|
|
|
child.on("close", (code) => {
|
|
childClosed = true;
|
|
finish(code ?? (spawnError ? 1 : 0));
|
|
});
|
|
```
|
|
|
|
This keeps all existing result-shaping logic in place, preserves best-effort artifact logging, preserves `PI_SUBAGENTS_CHILD=1`, and makes normal completion depend on the semantic terminal event rather than an indefinitely lingering process.
|
|
|
|
- [ ] **Step 5: Run the wrapper tests again and verify they all pass**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
npx tsx --test src/wrapper/cli.test.ts
|
|
```
|
|
|
|
Expected: PASS. In particular, `wrapper exits and writes result.json after terminal output even if the pi child lingers` should now pass, and the existing initiator / child-env / artifact-write regression tests should remain green.
|
|
|
|
- [ ] **Step 6: Run the full package test suite**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
npm test
|
|
```
|
|
|
|
Expected: all package tests PASS, including wrapper, runner, extension, and monitor coverage.
|
|
|
|
- [ ] **Step 7: Commit the finished bug fix**
|
|
|
|
Run:
|
|
|
|
```bash
|
|
git add src/wrapper/cli.mjs src/wrapper/cli.test.ts
|
|
git commit -m "fix: finish lingering subagent wrapper runs"
|
|
```
|