@fitchmultz/pi-subagents 0.44.7 → 0.46.0

package/scripts/run-tests.mjs

@@ -4,10 +4,14 @@ import { mkdtempSync, readdirSync, rmSync } from "node:fs";
 import { availableParallelism, tmpdir } from "node:os";
 import { join } from "node:path";
 
-const DEFAULT_TIMEOUT_MS = { unit: 300_000, integration: 900_000 };
+// ponytail: integration is sized for the 3-vCPU macOS hosted runner, where the suite takes
+// about 840-910 s; lower it once the test campaign shrinks the suite.
+const DEFAULT_TIMEOUT_MS = { unit: 300_000, integration: 1_200_000 };
 
 function usage() {
-  console.log(`Usage: node scripts/run-tests.mjs [unit|integration|all] [--timeout-ms <ms>]\n\nRuns the local TypeScript test suites through Node's test runner.\n\nModes:\n  unit         Run test/unit/*.test.ts\n  integration  Run test/integration/*.test.ts\n  all          Run unit, then integration\n\nOptions:\n  --timeout-ms <ms>  Per-suite watchdog timeout in milliseconds\n  -h, --help         Show this help\n\nEnvironment:\n  PI_TEST_TIMEOUT_MS  Per-suite timeout when --timeout-ms is omitted (default: unit 300000, integration 900000)\n\nExit codes:\n  0  selected suite(s) passed\n  1  tests failed, timed out, or could not start\n  2  invalid arguments`);
+  console.log(
+    `Usage: node scripts/run-tests.mjs [unit|integration|all] [--timeout-ms <ms>]\n\nRuns the local TypeScript test suites through Node's test runner.\n\nModes:\n  unit         Run test/unit/*.test.ts\n  integration  Run test/integration/*.test.ts\n  all          Run unit, then integration\n\nOptions:\n  --timeout-ms <ms>  Per-suite watchdog timeout in milliseconds\n  -h, --help         Show this help\n\nEnvironment:\n  PI_TEST_TIMEOUT_MS  Per-suite timeout when --timeout-ms is omitted (default: unit 300000, integration 1200000)\n\nExit codes:\n  0  selected suite(s) passed\n  1  tests failed, timed out, or could not start\n  2  invalid arguments`,
+  );
 }
 
 function parsePositiveInteger(value, source) {
@@ -17,7 +21,9 @@ function parsePositiveInteger(value, source) {
   }
   const parsed = Number(value);
   if (!Number.isSafeInteger(parsed) || parsed <= 0) {
-    console.error(`${source} must be a positive safe integer number of milliseconds, got: ${value}`);
+    console.error(
+      `${source} must be a positive safe integer number of milliseconds, got: ${value}`,
+    );
     process.exit(2);
   }
   return parsed;
@@ -75,18 +81,15 @@ function testFiles(dir) {
 function sanitizedEnv() {
   const env = { ...process.env };
   for (const key of Object.keys(env)) {
-    if (key.startsWith("PI_SUBAGENT_")) delete env[key];
+    if (key.startsWith("PI_SUBAGENT_")) {
+      delete env[key];
+    }
   }
   return env;
 }
 
-function runNodeTest(label, imports, files, timeoutMs, concurrency) {
-  const args = [
-    ...imports.flatMap((specifier) => ["--import", specifier]),
-    ...(concurrency ? [`--test-concurrency=${concurrency}`] : []),
-    "--test",
-    ...files,
-  ];
+function runNodeTest(label, files, timeoutMs, concurrency) {
+  const args = [...(concurrency ? [`--test-concurrency=${concurrency}`] : []), "--test", ...files];
   const startedAt = Date.now();
   const tempRoot = mkdtempSync(join(tmpdir(), "pi-subagents-test-"));
   const env = sanitizedEnv();
@@ -114,7 +117,9 @@ function runNodeTest(label, imports, files, timeoutMs, concurrency) {
     if (result.error.code === "ETIMEDOUT") {
       console.error(`${label} timed out after ${timeoutMs}ms (elapsed ${elapsedMs}ms).`);
       console.error(`Command: ${process.execPath} ${args.join(" ")}`);
-      console.error("Set PI_TEST_TIMEOUT_MS or pass --timeout-ms <ms> to adjust the local watchdog.");
+      console.error(
+        "Set PI_TEST_TIMEOUT_MS or pass --timeout-ms <ms> to adjust the local watchdog.",
+      );
       return 1;
     }
     console.error(`Failed to start ${label}: ${result.error.message}`);
@@ -129,8 +134,15 @@ function runNodeTest(label, imports, files, timeoutMs, concurrency) {
 }
 
 const { mode, timeoutMs } = parseArgs(process.argv.slice(2));
-const unit = () => runNodeTest("unit tests", [], testFiles("test/unit"), timeoutMs ?? DEFAULT_TIMEOUT_MS.unit);
-const integration = () => runNodeTest("integration tests", [], testFiles("test/integration"), timeoutMs ?? DEFAULT_TIMEOUT_MS.integration, Math.min(4, Math.max(1, availableParallelism() - 1)));
+const unit = () =>
+  runNodeTest("unit tests", testFiles("test/unit"), timeoutMs ?? DEFAULT_TIMEOUT_MS.unit);
+const integration = () =>
+  runNodeTest(
+    "integration tests",
+    testFiles("test/integration"),
+    timeoutMs ?? DEFAULT_TIMEOUT_MS.integration,
+    Math.min(4, Math.max(1, availableParallelism())),
+  );
 
 let status;
 switch (mode) {
@@ -142,7 +154,9 @@ switch (mode) {
     break;
   case "all":
     status = unit();
-    if (status === 0) status = integration();
+    if (status === 0) {
+      status = integration();
+    }
     break;
 }
 

package/skills/pi-intercom/SKILL.md

@@ -41,13 +41,13 @@ Coordinate named Pi sessions on the same machine with the least context loss and
 3. Pick the displayed name or target ID exactly. If names collide, use the target shown by `list`. Never message the current session.
 4. Choose the lightest action:
 
-| Action | Use for | Effect |
-| --- | --- | --- |
-| `send` | Guidance, answers, corrections, blockers, context, or other non-blocking coordination | Defaults to steer: it wakes idle recipients or reaches busy recipients at the next tool boundary, then returns after broker acceptance. Use explicit queue only when delay is intentional and passive only for human-visible breadcrumbs. |
-| `ask` | A required answer when this process must remain alive waiting for it | Use `delivery:"steer"`; waits up to `askTimeoutMs` (default 2 minutes). Default asks to peers reporting `accepts_asks:false` return `delivered:true`, `replied:false`, `reason:"peer_busy"`, while explicit steer asks keep waiting; not passive. |
-| `reply` | Answering an inbound ask | Uses the active ask, or the single pending ask |
-| `pending` | Multiple or delayed inbound asks | Lists unresolved asks so you can disambiguate |
-| `status` | Troubleshooting connection state | Shows connection, active session count, and the same live recipient capability/guidance rows as `list` |
+| Action    | Use for                                                                               | Effect                                                                                                                                                                                                                                            |
+| --------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `send`    | Guidance, answers, corrections, blockers, context, or other non-blocking coordination | Defaults to steer: it wakes idle recipients or reaches busy recipients at the next tool boundary, then returns after broker acceptance. Use explicit queue only when delay is intentional and passive only for human-visible breadcrumbs.         |
+| `ask`     | A required answer when this process must remain alive waiting for it                  | Use `delivery:"steer"`; waits up to `askTimeoutMs` (default 2 minutes). Default asks to peers reporting `accepts_asks:false` return `delivered:true`, `replied:false`, `reason:"peer_busy"`, while explicit steer asks keep waiting; not passive. |
+| `reply`   | Answering an inbound ask                                                              | Uses the active ask, or the single pending ask                                                                                                                                                                                                    |
+| `pending` | Multiple or delayed inbound asks                                                      | Lists unresolved asks so you can disambiguate                                                                                                                                                                                                     |
+| `status`  | Troubleshooting connection state                                                      | Shows connection, active session count, and the same live recipient capability/guidance rows as `list`                                                                                                                                            |
 
 5. Write compact messages with objective, scope, relevant files, stop boundary, and expected reply. Attachments only when the recipient needs the extra context.
 6. For live agent-to-agent coordination, use non-blocking `send`; omitted delivery steers by default. Then end the turn or continue independent work. Use explicit queue only when delay is intentional; optional `delivery:"queue", queueMode:"replace", threadId:"<non-empty>"` keeps only the latest undelivered update for that thread.
@@ -66,11 +66,11 @@ Child-side reasons only: blocking `need_decision` or `interview_request` when th
 
 Supervisor-side: while connected, `intercom` `reply` answers formatted child escalations. After reload/reconnect, resume the same saved supervisor session, list `agent_runs({ action: "questions" })`, and use `agent_runs({ action: "answer", id, questionId, message })`. These questions do not use the ordinary ask timeout. A nudge is not an answer. Saved answers reach a live waiter or revive an exited child's saved session; a receipt does not mean the work completed. Use `agent_runs({ action: "stop", id })` to cancel a pending question and its live waiter.
 
-| Type | Meaning | Supervisor response |
-| --- | --- | --- |
-| `need_decision` | Child cannot safely continue without one decision or approval | Reply promptly with a clear decision |
+| Type                | Meaning                                                          | Supervisor response                     |
+| ------------------- | ---------------------------------------------------------------- | --------------------------------------- |
+| `need_decision`     | Child cannot safely continue without one decision or approval    | Reply promptly with a clear decision    |
 | `interview_request` | Child cannot safely continue without multiple structured answers | Reply with JSON using the requested ids |
-| `progress_update` | Child steers a material discovery needed during active work | Read it; reply only if redirecting |
+| `progress_update`   | Child steers a material discovery needed during active work      | Read it; reply only if redirecting      |
 
 Interview replies use plain JSON or a fenced JSON block. `info` questions are context only and need no response entries:
 

package/skills/pi-intercom/references/peer-sessions.md

@@ -48,8 +48,13 @@ tmux -S "$SOCKET" attach -t "$SESSION"
 After the peer starts:
 
 ```typescript
-intercom({ action: "list" })
-intercom({ action: "send", to: "worker", delivery: "steer", message: "Smoke test: send exactly OK back to this session with delivery steer." })
+intercom({ action: "list" });
+intercom({
+  action: "send",
+  to: "worker",
+  delivery: "steer",
+  message: "Smoke test: send exactly OK back to this session with delivery steer.",
+});
 ```
 
 Expected reply:

package/skills/pi-subagents/SKILL.md

@@ -24,7 +24,7 @@ Use this skill to coordinate focused Pi sessions. The original agent owns integr
 - A reviewer timeout is not sign-off. Foreground reviewer budgets are raised to a safe floor; planner/researcher budgets are raised only from local history. Rerun, resume, or split timed-out work.
 - Subagent execution defaults to async/background. Launch a small bounded fanout as separate single-agent runs so each completion wakes the parent, with at most one writer. Continue useful parent work while children run; if none remains, end the turn and wait for completion instead of polling. Use one `tasks` call for non-review fanout when all child results are required together, when shared concurrency/task limits are needed, or when multiple writers require `worktree: true`; the parent receives one aggregate completion. Check status only when the user asks or the run may be blocked or stale.
 - An incomplete active Pi goal follows the same async workflow: if child evidence gates the next step, end the current turn and continue after automatic completion delivery. Do not advance past missing evidence. Use `async: false` for explicitly chosen foreground execution or a non-interactive one-shot caller that needs the result on stdout.
-- Use `acceptance` for goal-style requests and plan/spec/broad-fix worker handoffs; put criteria, evidence, verify commands, stop rules, and loop cap there instead of burying them only in task prose. Revived runs inherit that contract unless the resume call explicitly overrides `acceptance`.
+- Use `acceptance` for goal-style requests and plan/spec/broad-fix worker handoffs; put criteria, evidence, verify commands, stop rules, and loop cap there instead of burying them only in task prose. Require only checks the child can run in its environment; keep checks that need unavailable services, credentials, devices, or deploys for the parent. Revived runs inherit that contract unless the resume call explicitly overrides `acceptance`.
 - Omit `acceptance` from review-only tasks unless the user explicitly requests a same-session acceptance contract; it adds a finalization turn and does not provide independent review.
 - Independent review stays parent-controlled: never put `review` inside `acceptance`; launch reviewer subagents separately after the worker completes.
 - Do not set `acceptance` on static parallel groups or dynamic fanout aggregate groups; set it on each child task/template that owns a session.