@fitchmultz/pi-subagents 0.49.1 → 0.50.0

package/CHANGELOG.md

@@ -1,6 +1,28 @@
 # Changelog
 
-## Unreleased
+## [0.50.0] - Unreleased
+
+### Breaking
+
+- Replace the multi-profile workflow engine with one implicit native agent type and three tools: `delegate`, `agent_runs`, and `intercom`. The invoking agent supplies the entire assignment; user agent Markdown and profile/model catalogs no longer configure delegation. Remove `load_subagent`, `subagent`, `load_intercom`, `contact_supervisor`, conditional `structured_output`, chains/fanout DSL, profile administration, Claude Code backend, and durable supervisor-question revival.
+- Use one same-OS-user broker namespace, independent of project and agent directory. Main agents communicate across groups; children communicate only with their main and siblings and cannot spawn. During cutover, drain work and reload every participating Pi session onto the same approved version before resuming bridge traffic; old namespaces are not transparently joined.
+- Retire remote launch/resume/control, saved-session/transcript/catalog/group/broadcast and synchronous ask/reply routes. Grok bots retain authenticated peer discovery and durable messaging, not remote agent orchestration or observation. Replies use correlated `send`; ACK transfers complete reply duties to the consumer mailbox. Upgrade the helper and Box client/worker as a reviewed pair, including offline receipt reconciliation and saved prompt/routine migration. Preserve journals, mail, quota and reservation history for rollback.
+- Ignore the deprecated client `launch` configuration key with a metadata warning; it grants no capability. Other unknown configuration fields still fail closed and report the offending field safely. Existing credentials and settings are not automatically rewritten.
+
+### Added
+
+- Read-only TUI agent status and `/agents` list/watch, without a model turn or human dispatch controls. Watches show native published text, tool calls and results, not unpublished provider token deltas.
+- Stable paged `intercom last` reads without waking the recipient, metadata-only run inventory, and explicit per-run guidance admission, receipt-publication and process-exit facts.
+
+### Fixed
+
+- Preserve orchestration tool results in forked child context instead of filtering the coordinating agent's evidence.
+- Keep Stop commands scoped to their target actor generation; an unadmitted predecessor Stop cannot mark a successor stopped.
+- Disclose stale guidance to model-visible inspection callers; never hide rejected follow-ups only in extension details.
+- Require a concrete resolved recipient for asks before sending; retain exact reply-sender identity checks across peer registration races.
+- Include length-ended completed responses in `last`; ignore unpublished launch directories during listing/reconciliation while retaining their native session evidence. Preserve published uncertain launch claims, visible corruption errors and conservative cold-Stop process identity checks.
+
+This is an unpublished breaking-release candidate. Merge, publication, installation and paired bridge cutover remain separate approval gates; no live runtime is changed by this PR.
 
 ## [0.49.1] - 2026-10-15
 

package/README.md

@@ -1,109 +1,103 @@
 # pi-subagents
 
-`pi-subagents` lets [Pi](https://github.com/earendil-works/pi/tree/main/packages/coding-agent) delegate tasks to child sessions. Use it for code review, research, or implementation while you continue in the parent session.
-
-![A Pi parent session delegates independent tasks to scout and reviewer children, then receives their saved results.](.github/readme/delegation.png)
-
-## Install and start
-
-Requires **Pi 1.0.0+** and **Node 24.21.0+**. Use macOS or Linux. Windows is not supported.
+One Pi extension for delegation and local agent communication. Three tools, one
+agent type, no profile bodies.
 
 ```bash
 pi install npm:@fitchmultz/pi-subagents
-pi
 ```
 
-Enter a task in Pi:
+A main session supplies the child's complete assignment:
 
-```text
-Use scout to explain the authentication code in this project.
+```js
+delegate({
+  prompt:
+    "Inspect the authentication changes. Return concrete defects with file and line evidence. Do not edit files.",
+  name: "auth-review",
+});
 ```
 
-The built-in agents are ready to use. See the [installation reference](docs/reference.md#installation) for Git installs and local checkouts.
-
-## Run tasks
-
-Ask Pi for a child by role and task:
-
-```text
-Have worker implement this approved plan, then ask reviewer to check the changes.
+Delegation is asynchronous by default. `async: false` waits for the result.
+`context: "fresh"` is the default; `context: "fork"` preserves the native
+conversation, including prior tool results. There is no hidden role prompt,
+report-writing suffix, profile selection, or model fallback catalog.
+
+```js
+agent_runs({ action: "list" });
+agent_runs({ action: "inspect", id: "<run-id>" });
+agent_runs({
+  action: "continue",
+  id: "<run-id>",
+  prompt: "Now inspect the refresh-token path. Do not edit.",
+});
+agent_runs({ action: "wait", id: "<run-id>" });
+agent_runs({ action: "stop", id: "<run-id>" });
 ```
 
-Children run in the background by default. You can also use commands:
-
-| Task                 | Command                                                         |
-| -------------------- | --------------------------------------------------------------- |
-| Review a diff        | `/run reviewer "Review this diff"`                              |
-| Run parallel tasks   | `/parallel scout "Inspect frontend" -> scout "Inspect backend"` |
-| Run a sequence       | `/chain scout "Map auth" -> planner "Plan a refactor"`          |
-| Run a saved workflow | `/run-chain scout-planner -- refactor authentication`           |
-
-Add `--fg` to wait for the result. The [`forceTopLevelAsync` setting](docs/reference.md#forcetoplevelasync) disables waits when enabled.
-
-The saved workflow example requires a [chain file](docs/reference.md#chain-files) named `scout-planner`. See the [command reference](docs/reference.md#direct-commands) for all options.
-
-## Choose a role and model
-
-| Task                         | Built-in agents                                                                         |
-| ---------------------------- | --------------------------------------------------------------------------------------- |
-| Read code or gather evidence | `scout`, `context-builder`, `researcher`                                                |
-| Plan or check a decision     | `planner`, `oracle`                                                                     |
-| Implement or repair a change | `worker`, `debugger`, `fixer`, `delegate`                                               |
-| Review a change              | `reviewer`, `reviewer-gpt`, `reviewer-claude`, `reviewer-security`, `reviewer-ponytail` |
-| Design, write or monitor     | `ui-designer`, `writer`, `watcher`                                                      |
-
-Ask Pi to show the effective profiles. Select an available model if a profile default is unavailable.
-
-[Model settings](docs/reference.md#changing-a-builtin-agents-model) let you change a role without a copy of its agent file. Custom agents use `~/.pi/agent/agents/` or your project's `.pi/agents/`.
-
-## Read results and continue work
-
-The **Agents** area shows active tasks and tasks that need attention. Open `/agents` to browse active and finished conversations.
-
-The shortcut is **Option+Shift+M** on macOS and **Alt+Shift+M** elsewhere.
-
-- Open a conversation to read the child's report or send a message.
-- Press F2 to inspect details or request cancellation with Stop.
-- Select Continue to start follow-up work from a saved child session.
-- Press Esc to return to the parent session.
+## Talk to agents
 
-Resume the same saved parent session with `pi --session /path/to/parent.jsonl` to recover runs and questions.
-
-See the [conversation reference](docs/reference.md#try-this-first) for shortcuts, drafts and history search.
-
-## Limits and warnings
-
-Each child uses your provider account and can spend tokens. See [usage accounting](docs/reference.md#usage-accounting) for details.
-
-Children normally inherit Pi's tools, extensions, project instructions and skills. Restrict [tools](docs/reference.md#tool-and-extension-selection) and [project trust](docs/reference.md#projecttrust) when a child must have limited access.
-
-Intercom is included. It lets Pi sessions exchange messages and lets a child ask its parent for a decision.
-
-Read the [Intercom guide](docs/intercom.md) for setup and host limits. The [secure bridge](docs/intercom-bridge.md) adds unattended remote messaging, durable inboxes, groups, live/saved session discovery, spawn/resume and native controls for an authenticated remote agent.
-
-Indexed history requires SQLite 3.53.4 through Node's built-in `node:sqlite` binding. Other SQLite versions fail. See the [storage requirements](docs/performance.md#storage-budgets-and-recovery) and [host startup costs](docs/performance.md#necessary-costs-and-limits).
-
-## Update and troubleshoot
-
-An update can leave active sessions on old code. Close all Pi sessions that use this installation before an update.
-
-Run this command from a separate terminal:
-
-```bash
-pi update --extension npm:@fitchmultz/pi-subagents
+```js
+intercom({ action: "list" });
+intercom({ action: "send", to: "auth-review", message: "Focus on token rotation." });
+intercom({ action: "last", to: "auth-review" });
 ```
 
-Start new Pi processes after the update. `/reload` does not reliably activate changed JavaScript.
-
-Run `/subagents-doctor` to check delegation and Intercom setup. See the [installation reference](docs/reference.md#installation) for Git updates, local rebuilds and broker restarts.
-
-## Documentation
-
-- [Full reference](docs/reference.md): profiles, commands, configuration, workflows and saved run records.
-- [Development](docs/development.md): builds, CI, compatibility checks and optional model smoke tests.
-- [Example prompts](prompts/): saved examples for common tasks.
-- [Changelog](CHANGELOG.md): changes by version.
-
-## License
-
-[MIT](LICENSE).
+`send` steers by default. `last` reads the peer's last completed assistant response
+without waking it; large responses are paged, not silently truncated. Discovery
+works across project directories and Pi agent directories under the same OS user.
+
+A main and its children form one group:
+
+- Every pair within that group can discover and communicate with each other.
+- Main sessions can discover, message, and read other mains.
+- Children cannot discover or address another group's agents—even by exact ID.
+- Only mains can delegate. There is one child level, not recursive spawning.
+
+These are coordination rules, not an OS sandbox against same-user code. A peer
+list contains connected, eligible sessions, not every Pi process on the machine.
+
+## Watch agents without prompting them
+
+In interactive Pi, the agent status line reports active children. Open `/agents`
+to list runs and watch a child's native published text, tool calls and results.
+This is read-only: it neither spends a model turn nor dispatches, steers or stops
+work. Unpublished provider token deltas are not a journal stream. Agents still
+own delegation and communication; human observation is not a second workflow UI.
+
+## What stays explicit
+
+Launch acceptance is not completion. Broker acceptance is not recipient journal
+persistence or a reply. A stop request is not proof of process exit. Saved run
+inspection reports these states separately, and does not invent a successful
+result when a process disappears.
+
+Children use native Pi sessions and the selected host's SDK, resources, tools,
+project instructions, and model configuration. Optional `cwd` and `model`
+overrides belong to a launch; ordinary continuation reuses its saved conversation
+and launch configuration. No user agent Markdown files are edited or consulted
+as profiles.
+
+## Migration and documentation
+
+This rebuild deliberately removes the profile editor, workflow/chain/fanout DSL,
+Claude Code backend, custom agent overlays, supervisor-question revival protocol,
+and remote launch/control/catalog APIs. Grok bots retain messaging but lose remote
+spawn/resume/session/transcript/group/broadcast access; those retired commands are
+not bridge-outage symptoms. Update saved bot prompts/routines to correlated
+`send` before cutover.
+
+Existing installations must finish in-flight work and reload **every participating
+Pi session** onto the same approved version before resuming remote traffic. Old
+and new brokers do not forward across namespaces. Keep the prior package and saved
+state for rollback; qualify the helper and Box client/worker as an immutable pair,
+with the companion's offline receipt-reconciliation gate. This repository change
+does not deploy or restart anything.
+
+- [Tools and lifecycle](docs/reference.md)
+- [Local messaging and broker migration](docs/intercom.md)
+- [Authenticated remote messaging / Grok companion](docs/intercom-bridge.md)
+- [Development and qualification](docs/development.md)
+- [Diagnosis, baseline, and measurable rebuild gates](docs/single-agent-rebuild.md)
+
+Supports official Pi and the maintained `fitchmultz/pi` fork; the two hosts are
+qualified separately. Node.js 24.21 or newer is required. MIT licensed.

package/dist/agent/contracts.js

@@ -0,0 +1,122 @@
+import { Type } from "./typebox.js";
+export const thinkingSchema = Type.Union([
+    Type.Literal("off"),
+    Type.Literal("minimal"),
+    Type.Literal("low"),
+    Type.Literal("medium"),
+    Type.Literal("high"),
+    Type.Literal("xhigh"),
+    Type.Literal("max"),
+]);
+export const launchSchema = Type.Object({
+    version: Type.Literal(1),
+    id: Type.String(),
+    rootId: Type.String(),
+    predecessor: Type.Optional(Type.String()),
+    owner: Type.String(),
+    cwd: Type.String(),
+    agentDir: Type.String(),
+    sdk: Type.String(),
+    entry: Type.String(),
+    sessionFile: Type.String(),
+    sessionId: Type.String(),
+    prompt: Type.String(),
+    context: Type.Union([Type.Literal("fresh"), Type.Literal("fork")]),
+    provider: Type.String(),
+    model: Type.String(),
+    thinking: thinkingSchema,
+    trusted: Type.Boolean(),
+    name: Type.Optional(Type.String()),
+    createdAt: Type.Number(),
+});
+export const processSchema = Type.Object({
+    pid: Type.Integer({ minimum: 1 }),
+    identity: Type.String(),
+    token: Type.String(),
+});
+export const attachmentSchema = Type.Object({
+    pid: Type.Integer({ minimum: 1 }),
+    identity: Type.String(),
+    generation: Type.String(),
+    attached: Type.Boolean(),
+});
+export const usageSchema = Type.Object({
+    input: Type.Number({ minimum: 0 }),
+    output: Type.Number({ minimum: 0 }),
+    cacheRead: Type.Number({ minimum: 0 }),
+    cacheWrite: Type.Number({ minimum: 0 }),
+    totalTokens: Type.Number({ minimum: 0 }),
+    reasoning: Type.Optional(Type.Number({ minimum: 0 })),
+    cacheWrite1h: Type.Optional(Type.Number({ minimum: 0 })),
+    cost: Type.Object({
+        input: Type.Number({ minimum: 0 }),
+        output: Type.Number({ minimum: 0 }),
+        cacheRead: Type.Number({ minimum: 0 }),
+        cacheWrite: Type.Number({ minimum: 0 }),
+        total: Type.Number({ minimum: 0 }),
+    }),
+});
+export const contributionsSchema = Type.Array(Type.Object({
+    id: Type.String({ minLength: 1 }),
+    provider: Type.String(),
+    model: Type.String(),
+    usage: usageSchema,
+}));
+export const resultSchema = Type.Object({
+    id: Type.String(),
+    owner: Type.String(),
+    status: Type.Union([Type.Literal("completed"), Type.Literal("failed"), Type.Literal("stopped")]),
+    endedAt: Type.Number(),
+    terminalEntryId: Type.Optional(Type.String()),
+    error: Type.Optional(Type.String()),
+    contributions: Type.Optional(contributionsSchema),
+    accountingError: Type.Optional(Type.String()),
+    accountingPending: Type.Optional(Type.Object({
+        terminalCandidate: Type.String(),
+        baseline: Type.Array(Type.String()),
+    })),
+});
+export const commandSchema = Type.Object({
+    id: Type.String(),
+    runId: Type.String(),
+    action: Type.Union([Type.Literal("run"), Type.Literal("steer"), Type.Literal("stop")]),
+    prompt: Type.Optional(Type.String()),
+    actorToken: Type.Optional(Type.String()),
+    createdAt: Type.Number(),
+});
+export const successorSchema = Type.Object({ id: Type.String() });
+export const exitSchema = Type.Object({
+    pid: Type.Integer(),
+    code: Type.Union([Type.Integer(), Type.Null()]),
+    signal: Type.Union([Type.String(), Type.Null()]),
+    at: Type.Number(),
+});
+export const admissionSchema = Type.Object({
+    id: Type.String(),
+    action: Type.String(),
+    runId: Type.Optional(Type.String()),
+    state: Type.Optional(Type.Union([Type.Literal("accepted"), Type.Literal("stale")])),
+    at: Type.Number(),
+});
+export const delegateSchema = Type.Object({
+    prompt: Type.String({ minLength: 1 }),
+    name: Type.Optional(Type.String({ minLength: 1 })),
+    cwd: Type.Optional(Type.String({ minLength: 1 })),
+    model: Type.Optional(Type.String({ minLength: 1, description: "Exact provider/model ID; no fallback." })),
+    context: Type.Optional(Type.Union([Type.Literal("fresh"), Type.Literal("fork")])),
+    async: Type.Optional(Type.Boolean({ default: true })),
+}, { additionalProperties: false });
+export const runsSchema = Type.Object({
+    action: Type.Union([
+        Type.Literal("list"),
+        Type.Literal("inspect"),
+        Type.Literal("continue"),
+        Type.Literal("stop"),
+        Type.Literal("wait"),
+    ]),
+    id: Type.Optional(Type.String()),
+    prompt: Type.Optional(Type.String({ minLength: 1 })),
+    async: Type.Optional(Type.Boolean({ default: true })),
+    offset: Type.Optional(Type.Integer({ minimum: 0 })),
+    length: Type.Optional(Type.Integer({ minimum: 4, maximum: 262144 })),
+}, { additionalProperties: false });

package/dist/agent/cwd.js

@@ -0,0 +1,51 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { write } from "./storage.js";
+export function localCwdOwner(source) {
+    return /(?:^|[/\\:@])(?:pi-)?change-working-dir(?:[/\\@:.>]|$)/.test(`${source.source}/${source.path}`);
+}
+function hasOwner(pi) {
+    return (pi.getAllTools().some((tool) => tool.name === "change_dir" || localCwdOwner(tool.sourceInfo)) ||
+        pi
+            .getCommands()
+            .some((command) => command.source === "extension" &&
+            (/^cwd(?::\d+)?$/.test(command.name) || localCwdOwner(command.sourceInfo))));
+}
+function reply(request) {
+    if (request.result?.error !== undefined && request.result.error !== "") {
+        throw new Error(request.result.error);
+    }
+    if (request.result && (request.result.cwd === undefined || request.result.cwd === "")) {
+        throw new Error("Directory owner returned no execution directory.");
+    }
+    return request.result?.cwd;
+}
+export function executionCwd(pi, ctx) {
+    const request = { sessionManager: ctx.sessionManager };
+    pi.events.emit("pi-change-working-dir:resolve-execution-cwd", request);
+    const cwd = reply(request);
+    if (cwd === undefined && hasOwner(pi)) {
+        throw new Error("Loaded directory owner did not resolve cwd; update pi-change-working-dir.");
+    }
+    return cwd ?? ctx.cwd;
+}
+export function initializeCwd(pi, ctx, cwd, directory) {
+    // A saved continuation restores its owner's latest selection, not its frozen launch directory.
+    const current = executionCwd(pi, ctx);
+    const marker = path.join(directory, "cwd-initialized.json");
+    if (fs.existsSync(marker)) {
+        return;
+    }
+    if (hasOwner(pi) || fs.realpathSync(current) !== fs.realpathSync(ctx.cwd)) {
+        const request = { sessionManager: ctx.sessionManager, path: cwd };
+        pi.events.emit("pi-change-working-dir:set-execution-cwd", request);
+        const selected = reply(request);
+        if (selected === undefined || fs.realpathSync(selected) !== fs.realpathSync(cwd)) {
+            throw new Error("Directory owner did not initialize the requested child cwd.");
+        }
+    }
+    else if (fs.realpathSync(ctx.cwd) !== fs.realpathSync(cwd)) {
+        throw new Error("Native child directory does not match launch cwd.");
+    }
+    write(marker, { cwd }, true);
+}

package/dist/agent/host.js

@@ -0,0 +1,82 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { findPackageJSON } from "node:module";
+import { fileURLToPath, pathToFileURL } from "node:url";
+function isPackage(root) {
+    const file = path.join(root, "package.json");
+    if (!fs.existsSync(file)) {
+        return false;
+    }
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    return (typeof value === "object" &&
+        value !== null &&
+        "name" in value &&
+        value.name === "@earendil-works/pi-coding-agent");
+}
+function launcherPackage() {
+    const entry = process.argv.at(1);
+    if (entry === undefined) {
+        return;
+    }
+    let directory = path.dirname(fs.realpathSync(entry));
+    while (directory !== path.dirname(directory)) {
+        if (isPackage(directory)) {
+            return directory;
+        }
+        directory = path.dirname(directory);
+    }
+    return undefined;
+}
+export function packageRoot() {
+    const configured = process.env.PI_PACKAGE_DIR;
+    if (configured !== undefined && configured.length > 0) {
+        if (!isPackage(configured)) {
+            throw new Error("PI_PACKAGE_DIR is not a Pi SDK.");
+        }
+        return configured;
+    }
+    const launcher = launcherPackage();
+    if (launcher !== undefined) {
+        return launcher;
+    }
+    const manifest = findPackageJSON("@earendil-works/pi-coding-agent", import.meta.url);
+    if (manifest === undefined) {
+        throw new Error("Cannot locate the native Pi SDK.");
+    }
+    return path.dirname(manifest);
+}
+export async function loadSDK(root) {
+    // Selected host SDK, not a second package-local runtime hidden behind Jiti aliases.
+    // oxlint-disable-next-line typescript/no-unsafe-assignment
+    const sdk = await import(__rewriteRelativeImportExtension(pathToFileURL(path.join(root, "dist/index.js")).href));
+    return sdk;
+}
+export function runtimeEntry() {
+    return fileURLToPath(new URL(import.meta.url.endsWith(".ts") ? "../index.ts" : "../index.js", import.meta.url));
+}
+export function isChild() {
+    const root = process.env.PI_INTERCOM_ROOT_SESSION_ID;
+    const parent = process.env.PI_INTERCOM_PARENT_SESSION_ID;
+    if (root === undefined && parent === undefined) {
+        return false;
+    }
+    if (root === undefined ||
+        parent === undefined ||
+        root.length === 0 ||
+        parent.length === 0 ||
+        root !== parent) {
+        throw new Error("Malformed child identity; delegation is disabled.");
+    }
+    return true;
+}
+export function errorText(error) {
+    return error instanceof Error ? error.message : JSON.stringify(error);
+}