pi-better-subagents 0.22.1 → 0.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -25,6 +25,23 @@ launch starts it again. No separate background task or coordinator heartbeat is
25
25
  needed. Completion delivery retries use the callback batcher's own timer. Lost-run
26
26
  alerts retain supervision until their handoff is handled, so lost work is not silent.
27
27
 
28
+ ## Worker Ownership
29
+
30
+ Every child launch, including clean, batch and unsandboxed launches, loads a Pi
31
+ hook that keeps external CI/PR monitoring with its coordinator. Workers finish
32
+ their assigned implementation or diagnosis, run focused checks, push only when
33
+ authorized, write the result, and return. Pending CI is a valid handoff, not a pass.
34
+
35
+ The hook refuses recognized `gh run watch`, `gh pr checks --watch`, and bundled
36
+ delivery-watcher commands through `bash` and `run_application`. Short status reads,
37
+ failed-log retrieval, and legitimate long local tests and builds remain allowed.
38
+ If background tools are explicitly available to a child, recognized watcher
39
+ commands are refused there too. Coordinator sessions are unaffected.
40
+
41
+ This is an operational ownership guard, not a security boundary or a classifier
42
+ for arbitrary programs. Indirect scripts and custom polling implementations still
43
+ rely on the worker handoff contract. Command permissions and timeouts are unchanged.
44
+
28
45
  ## Install
29
46
 
30
47
  ```sh
@@ -93,13 +110,18 @@ line says so, for example
93
110
 
94
111
  ## When To Use
95
112
 
113
+ Skills can use the same role definitions on Pi and Codex through the standalone
114
+ `pi-agent-catalog` JSON CLI, without starting Pi. The CLI checks supplied host
115
+ capabilities and returns a worker plan; it never launches workers or substitutes
116
+ prompt text for model selection. See [shared worker catalog](docs/worker-catalog.md).
117
+
96
118
  Use this package for independent coding, review, research, or verification work that can finish later. Do not use it for steps that need immediate foreground interaction or user clarification.
97
119
 
98
120
  ## Compatibility
99
121
 
100
122
  | Requirement | Support |
101
123
  |-------------|---------|
102
- | Pi | Required |
124
+ | Pi | Required for worker execution through this extension; not for standalone catalog planning |
103
125
  | Install method | `pi install npm:pi-better-subagents` |
104
126
  | macOS sandboxing | Supported when enabled |
105
127
  | Linux sandboxing | Requires usable `bubblewrap` when enabled |
@@ -0,0 +1,29 @@
1
+ #!/usr/bin/env node
2
+ import { readFileSync, realpathSync } from 'node:fs';
3
+ import { pathToFileURL } from 'node:url';
4
+
5
+ export async function runCli(args = process.argv.slice(2), input = () => readFileSync(0, 'utf8')) {
6
+ if (args.includes('--help')) {
7
+ console.log('pi-agent-catalog [resolve-workers] < request.json\nResolves shared agent roles against explicit host model and effort capabilities. No workers are launched.');
8
+ return 0;
9
+ }
10
+ if (args.length > 1 || (args.length === 1 && args[0] !== 'resolve-workers')) {
11
+ console.error('Usage: pi-agent-catalog [resolve-workers] < request.json');
12
+ return 2;
13
+ }
14
+ try {
15
+ // Register only for this import. The portable resolver never loads Pi extensions or credentials.
16
+ const { tsImport } = await import('tsx/esm/api');
17
+ const { planWorkers } = await tsImport('./worker-catalog.ts', import.meta.url);
18
+ const text = input();
19
+ if (Buffer.byteLength(text) > 1024 * 1024) throw new Error('worker request exceeds 1 MiB');
20
+ console.log(JSON.stringify(planWorkers(JSON.parse(text))));
21
+ return 0;
22
+ } catch (error) {
23
+ console.error(`pi-agent-catalog: ${error.message}`);
24
+ console.log(JSON.stringify({ version: 1, ok: false, code: 'worker-catalog-error', reason: error.message }));
25
+ return 2;
26
+ }
27
+ }
28
+
29
+ if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) process.exitCode = await runCli();
@@ -0,0 +1,130 @@
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+ import { parse } from "shell-quote";
3
+ import { STEER_FILE_ENV } from "./child-steer.ts";
4
+
5
+ export const WORKER_HANDOFF = "Worker ownership: complete your assigned implementation or diagnosis, run focused checks, push only when authorized, write the requested result, then return. Pending CI is a handoff, not a failed implementation or a CI pass. The coordinator owns CI/PR monitoring, review scheduling, readiness, enqueueing and merge. Do not start external delivery watchers or background monitoring. Short status reads and failed-log retrieval for diagnosis are allowed. Legitimate local tests and builds may run to completion within their command limits.";
6
+ const REFUSAL = "Worker ownership: CI/PR monitoring belongs to the coordinator. Return the PR/run ID, pushed HEAD and current evidence with CI pending; do not retry the watcher through another tool or script. Local tests/builds and short diagnostic status/log reads remain allowed.";
7
+ const WATCH_SCRIPTS = new Set(["watch-pr-delivery.mjs", "watch-delivery.mjs", "watch-candidate-delivery.mjs"]);
8
+ const nameOf = (value: string) => value.replaceAll("\\", "/").split("/").at(-1)!.replace(/\.exe$/i, "");
9
+
10
+ // Preserve command boundaries without treating multiline strings or heredoc data as commands.
11
+ function commandLines(command: string): string[] {
12
+ const lines: string[] = [];
13
+ const documents: { delimiter: string; tabs: boolean }[] = [];
14
+ let quote = "", escaped = false, out = "";
15
+ for (const line of command.split("\n")) {
16
+ if (documents.length) {
17
+ const document = documents[0]!;
18
+ if ((document.tabs ? line.replace(/^\t+/, "") : line) === document.delimiter) documents.shift();
19
+ continue;
20
+ }
21
+ let comment = false;
22
+ for (const char of `${line}\n`) {
23
+ if (!quote && !escaped && char === "#" && (!out || /[\s;&|()<>]$/.test(out))) comment = true;
24
+ if (comment && char !== "\n") continue;
25
+ if (escaped) { out += char === "\n" ? "" : `\\${char}`; escaped = false; continue; }
26
+ if (char === "\\" && quote !== "'") { escaped = true; continue; }
27
+ if (char === quote) quote = "";
28
+ else if (!quote && (char === "'" || char === '"')) quote = char;
29
+ if (char !== "\n" || quote) { out += char; continue; }
30
+ lines.push(out);
31
+ try {
32
+ const tokens = parse(out);
33
+ for (let i = 0; i < tokens.length; i++) {
34
+ const token = tokens[i], delimiter = tokens[i + 1];
35
+ if (typeof token === "object" && "op" in token && ["<<", "<<-"].includes(token.op) && typeof delimiter === "string") {
36
+ documents.push({ delimiter, tabs: token.op === "<<-" });
37
+ }
38
+ }
39
+ } catch { /* The command tool, not this operational guard, validates shell syntax. */ }
40
+ out = "";
41
+ }
42
+ }
43
+ if (out) lines.push(out);
44
+ return lines;
45
+ }
46
+
47
+ function shellWatcher(command: string, depth: number): boolean {
48
+ if (depth > 3) return false;
49
+ let tokens;
50
+ try { tokens = commandLines(command).flatMap((line) => [...parse(line), { op: ";" as const }]); } catch { return false; }
51
+ let words: string[] = [];
52
+ let redirect = false;
53
+ for (const token of tokens) {
54
+ if (typeof token === "string" || ("op" in token && token.op === "glob")) {
55
+ if (redirect) { redirect = false; continue; }
56
+ words.push(typeof token === "string" ? token : token.pattern);
57
+ } else if ("op" in token && ["<", ">", ">>", ">&", "<&", ">|", "<>", "&>", "&>>", "<<", "<<-", "<<<"].includes(token.op)) {
58
+ if (words.length === 1 && /^\d+$/.test(words[0]!)) words = [];
59
+ redirect = true;
60
+ } else {
61
+ if (argvWatcher(words, depth + 1)) return true;
62
+ words = [];
63
+ redirect = false;
64
+ }
65
+ }
66
+ return argvWatcher(words, depth + 1);
67
+ }
68
+
69
+ function argvWatcher(input: readonly string[], depth = 0): boolean {
70
+ if (depth > 4) return false;
71
+ let words = [...input];
72
+ while (/^[A-Za-z_][A-Za-z_0-9]*=/.test(words[0] ?? "")) words.shift();
73
+ if (nameOf(words[0] ?? "") === "env") {
74
+ words.shift();
75
+ while (words.length) {
76
+ if (["-u", "--unset", "-C", "--chdir"].includes(words[0]!)) words.splice(0, 2);
77
+ else if (words[0] === "--" || words[0]!.startsWith("-") || /^[A-Za-z_][A-Za-z_0-9]*=/.test(words[0]!)) words.shift();
78
+ else break;
79
+ }
80
+ }
81
+ const program = nameOf(words.shift() ?? "");
82
+ if (["bash", "sh", "zsh", "dash"].includes(program)) {
83
+ const at = words.findIndex((word) => /^-[^-]*c/.test(word));
84
+ return at >= 0 && typeof words[at + 1] === "string" && shellWatcher(words[at + 1]!, depth + 1);
85
+ }
86
+ if (words.includes("--help") || words.includes("-h")) return false;
87
+ if (program === "gh") {
88
+ while (words.length) {
89
+ if (["--repo", "-R", "--hostname"].includes(words[0]!)) words.splice(0, 2);
90
+ else if (/^(?:--repo=.+|--hostname=.+|-R.+)$/.test(words[0]!)) words.shift();
91
+ else break;
92
+ }
93
+ return (words[0] === "run" && words[1] === "watch") ||
94
+ (words[0] === "pr" && words[1] === "checks" && words.slice(2).some((word) => ["--watch", "--watch=true"].includes(word)));
95
+ }
96
+ if (WATCH_SCRIPTS.has(program)) return true;
97
+ if (program === "node" || program === "nodejs") {
98
+ while (words[0]?.startsWith("-")) {
99
+ if (["-e", "--eval", "-p", "--print"].includes(words[0])) return false;
100
+ const takesValue = ["--import", "--loader", "--require", "-r"].includes(words[0]);
101
+ words.splice(0, takesValue ? 2 : 1);
102
+ }
103
+ return WATCH_SCRIPTS.has(nameOf(words[0] ?? ""));
104
+ }
105
+ return false;
106
+ }
107
+
108
+ /** Recognizes supported watcher entrypoints, not arbitrary program semantics or a security boundary. */
109
+ export function workerMonitoringRefusal(toolName: string, input: unknown): string | undefined {
110
+ if (!input || typeof input !== "object") return;
111
+ const value = input as Record<string, unknown>;
112
+ const argv = toolName === "run_application" && typeof value.executable === "string" &&
113
+ (value.args === undefined || (Array.isArray(value.args) && value.args.every((arg) => typeof arg === "string")))
114
+ ? [value.executable, ...((value.args ?? []) as string[])] : undefined;
115
+ if (argv && argvWatcher(argv)) return REFUSAL;
116
+ if (["bash", "remote_bash", "bg_task", "bg_task_spawn", "bg_task_watch"].includes(toolName)) {
117
+ if (typeof value.command === "string" && shellWatcher(value.command, 0)) return REFUSAL;
118
+ if (Array.isArray(value.argv) && value.argv.every((arg) => typeof arg === "string") && argvWatcher(value.argv)) return REFUSAL;
119
+ }
120
+ }
121
+
122
+ export default function childOwnership(pi: Pick<ExtensionAPI, "on">, env: NodeJS.ProcessEnv = process.env): void {
123
+ // This marker is supplied by the parent on every child launch, including clean/unsandboxed runs.
124
+ if (!env[STEER_FILE_ENV]) return;
125
+ pi.on("before_agent_start", (event) => ({ systemPrompt: `${event.systemPrompt}\n\n${WORKER_HANDOFF}` }));
126
+ pi.on("tool_call", (event) => {
127
+ const reason = workerMonitoringRefusal(event.toolName, event.input);
128
+ if (reason) return { block: true, reason };
129
+ });
130
+ }
@@ -1,6 +1,6 @@
1
1
  # Native agent catalog (`pi-agent/v1`)
2
2
 
3
- Portable role and named-agent definitions for `pi-better-subagents`. This is the local contract for DEV-23 / GitHub #289. It is not an Agentier importer, a Codex runtime, or a second launch path.
3
+ Portable role and named-agent definitions for `pi-better-subagents`. This is the local contract for DEV-23 / GitHub #289. It is not an Agentier importer or a second launch path. The [shared worker catalog](worker-catalog.md) exposes these definitions to skills on Pi and Codex through host-specific planning, without launching workers itself.
4
4
 
5
5
  Normative behavior is DEV-23 and the accepted ADR `docs/adr/0003-native-agent-catalog-live-inheritance.md`. Field names below are the engineering schema those decisions require.
6
6
 
@@ -1,6 +1,6 @@
1
1
  # Agent model resolution
2
2
 
3
- Resolver for DEV-23 model and effort choices. `model-resolution.ts` and `tier-policy.ts` do not spawn a child and do not edit the catalog. Lifecycle calls them before `spawnSubagentRun`.
3
+ Resolver for DEV-23 model and effort choices. `model-resolution-core.ts` owns portable resolution; `model-resolution.ts` supplies Pi's effort-support helper. Neither spawns a child or edits the catalog. Lifecycle calls the Pi adapter before `spawnSubagentRun`. Skills on other hosts use the [shared worker catalog](worker-catalog.md).
4
4
 
5
5
  Normative rules are R3, R4, R8, and the resolver half of R10. Prose parsing and real Pi delegation stay with the acceptance unit.
6
6
 
@@ -0,0 +1,116 @@
1
+ # Shared worker catalog
2
+
3
+ Skills request roles; the harness catalog owns their instructions, preferred
4
+ models, and effort. Skills must not turn a model recommendation into an explicit
5
+ launch override. This interface plans workers; it does not launch them.
6
+
7
+ `pi-agent-catalog [resolve-workers]` reads one JSON request from stdin and emits
8
+ one JSON plan. Install the harness or subagents npm package to expose the binary,
9
+ or run its `agent-catalog.mjs` directly. No Pi session, credentials, provider
10
+ discovery, extensions, or network connection is needed. The CLI uses the packaged
11
+ `tsx` loader; the portable TypeScript API is `pi-better-subagents/catalog`.
12
+
13
+ ## Request
14
+
15
+ ```json
16
+ {
17
+ "version": 1,
18
+ "harness": "codex",
19
+ "cwd": "/workspace/project",
20
+ "projectTrusted": false,
21
+ "available": [
22
+ {
23
+ "model": "openai/gpt-6.1-sol",
24
+ "nativeModel": "gpt-6.1-sol",
25
+ "supportedEfforts": ["low", "medium", "high"]
26
+ },
27
+ {
28
+ "model": "openai/gpt-6-luna",
29
+ "nativeModel": "gpt-6-luna",
30
+ "supportedEfforts": ["low", "medium", "high"]
31
+ },
32
+ {
33
+ "model": "openai/gpt-6-astra",
34
+ "nativeModel": "gpt-6-astra",
35
+ "supportedEfforts": ["low", "medium", "high"]
36
+ }
37
+ ],
38
+ "launchCapabilities": {
39
+ "model": true,
40
+ "effort": true,
41
+ "instructions": true
42
+ },
43
+ "hostPreferences": {
44
+ "developer": {"model": "openai/gpt-6.1-sol", "effort": "high"}
45
+ }
46
+ }
47
+ ```
48
+
49
+ This is an example shape, not evidence that these models or controls are available
50
+ in any Codex installation. The caller supplies capabilities from its current host.
51
+ Do not copy an availability list from Pi, infer supported effort from a model name,
52
+ or treat a configured model as available without runtime evidence. A native model
53
+ name maps to exactly one canonical `provider/model`; ambiguous mappings fail.
54
+
55
+ The catalog still uses project > personal > bundled definitions. Personal storage
56
+ is `userRoot`, then `PI_CODING_AGENT_DIR`, then `~/.pi/agent`, shared across hosts.
57
+ The CLI never scans `.codex/agents` or writes user configuration. Project catalog
58
+ files contribute only when `projectTrusted` is explicitly true. Host preferences
59
+ are supplied configuration, not another copied catalog or a write to a role.
60
+
61
+ Optional `overrides` selects `implementer`, `explorer`, `diagnoser`, or `reviewer`:
62
+
63
+ ```json
64
+ {"overrides": {"implementer": {"model": "deepseek/deepseek-flash@max"}}}
65
+ ```
66
+
67
+ Model and effort resolve independently: task override > host preference > catalog
68
+ default. A model-only override keeps the resolved effort. Unsupported explicit
69
+ model/effort choices block; inherited effort can use the catalog's documented
70
+ nearest-level adjustment. Pi retains its existing tier/foreground fallback policy.
71
+ Codex and Claude Code require an explicit configured `tiers` policy or
72
+ `fallbackToForeground: true` to permit those default-model substitutions. An
73
+ explicit task or host model is never silently substituted.
74
+
75
+ ## Plan And Execution
76
+
77
+ The plan maps implementer and diagnoser to Developer, explorer to Explorer, and
78
+ reviewer to Reviewer. Every worker reports `role`, `model`, `nativeModel`, `effort`,
79
+ `instructions`, `selection`, `catalogDigest`, `diagnostics`,
80
+ and `launch`. All four use the same immutable catalog snapshot. A reviewer that
81
+ resolves to the implementer's model blocks preflight; the skill must not invent
82
+ another model to make the check pass.
83
+
84
+ - **Pi:** `launch` is `{role: "developer"}` by default. Only explicit task or host
85
+ model/effort choices add `model` or `thinking`. The coordinator adds its task
86
+ prompt, alias, workspace, and authorized controls to the existing spawn tool.
87
+ Live Pi launch resolution remains authoritative, including branch-local session
88
+ preferences that an out-of-process CLI cannot read. Record the actual launch
89
+ provenance, not just the preflight prediction.
90
+ - **Codex / Claude Code:** `launch` contains the verified native `model`, `effort`,
91
+ and resolved role `instructions`. The adapter uses actual launch/configuration
92
+ controls supported by its current surface and appends the task instructions.
93
+ If the surface cannot apply a required field, do not launch. Saying a model name
94
+ in a worker prompt is not model selection. This API is a plan, not a claim that
95
+ every native `spawn_agent` surface supports per-call model or effort fields.
96
+
97
+ The catalog grants no sandbox, tool, filesystem, credential, or delegation
98
+ permissions. Existing host launch controls still apply.
99
+
100
+ On a blocked plan, `ok` is false and **every** `launch` is null. A model recorded
101
+ in an unsuccessful decision is diagnostic evidence, not launch authorization.
102
+ The CLI returns status 0 for a valid plan, including a blocked plan, and status 2
103
+ for malformed input or an invocation error. Consumers must check `ok`, not just
104
+ the process exit status. No automatic retry, install, or post-start substitution
105
+ is performed.
106
+
107
+ ## Modules
108
+
109
+ - `catalog-schema.ts`, `catalog-store.ts`, `catalog-resolver.ts`: existing shared
110
+ definitions and live inheritance, unchanged storage format.
111
+ - `model-resolution-core.ts`: portable availability and effort resolution, with
112
+ host-provided supported effort levels or an injected effort-support function.
113
+ - `model-resolution.ts`: Pi wrapper, supplying `getSupportedThinkingLevels` from
114
+ Pi's registry. Existing Pi callers retain their API and semantics.
115
+ - `worker-catalog.ts`: workflow slots, host adaptation, independence, and a single
116
+ batch snapshot. It does not import a Pi SDK.
package/index.ts CHANGED
@@ -1786,9 +1786,10 @@ export default function (pi: ExtensionAPI) {
1786
1786
  const { args: resolvedExtArgs, missing } = extensionArgs(resolution, resolveExtensionPath);
1787
1787
  const trustedExtArgs = [...new Set(taskTools?.trusted.map((tool) => tool.loadPath) ?? [])]
1788
1788
  .filter((path) => !resolvedExtArgs.includes(path)).flatMap((path) => ["--extension", path]);
1789
- // The harness's own child control extension (no tools, no command I/O) rides along in every
1790
- // mode, including clean: it is how a soft-deadline steer reaches the child session.
1791
- const extArgs = [...resolvedExtArgs, ...trustedExtArgs, "--extension", childSteerExtensionPath()]
1789
+ // Harness child controls ride along in every mode, including clean and unsandboxed runs.
1790
+ // They deliver deadline steers and keep external monitoring with the coordinator.
1791
+ const extArgs = [...resolvedExtArgs, ...trustedExtArgs,
1792
+ "--extension", childSteerExtensionPath(), "--extension", join(selfDir(), "child-ownership.ts")]
1792
1793
  .map((value, index, all) => sandboxEnabled && all[index - 1] === "--extension" ? canonicalizePath(value) : value);
1793
1794
  if (sandboxEnabled && resolution.mode === "inherit") {
1794
1795
  throw new Error("Task confinement requires explicit extensions; inheritExtensions is unsupported while sandboxing is enabled.");