@hheei/pi-subagents 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hheei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# @hheei/pi-subagents
+
+Run several independent Pi child sessions from one Pi session, each with its own Pi session
+file, its own RPC runtime, and its own durable identity.
+
+The package is a single concrete extension with one `pi.extensions` entry
+(`dist/extension.js`). The same entry runs on both sides: the parent branch registers the
+model-facing tools, commands, and widget; the child branch registers only the reporting
+bridge and session-leave reporting.
+
+Current behavior is defined by [`docs/pi-subagents/spec.md`](../../docs/pi-subagents/spec.md).
+[`docs/pi-subagents/PLAN.md`](../../docs/pi-subagents/PLAN.md) and
+[`docs/pi-subagents/PLAN-delivery-presentation.md`](../../docs/pi-subagents/PLAN-delivery-presentation.md)
+are design sources, not the live contract. Remaining pause-handshake work is tracked in
+[`docs/pi-subagents/tickets.md`](../../docs/pi-subagents/tickets.md) SUB-08.
+
+## Parent tools
+
+| Tool | Purpose |
+| --- | --- |
+| `spawn_subagent({ task, agent, cwd? })` | Start one background RPC child and return when the runtime is ready. Do not poll `get`/`list` for the child's work; reports arrive as `pi-subagent-report` messages. |
+| `send_subagent({ id, message, mode? })` | Send `steer`, `follow_up`, or `auto` input to a specific child. Do not poll afterwards. |
+| `get_subagent({ id })` | Inspect one child: state, mode, session, summary, usage, runtime freshness, and inherited model/thinking. Use this for identity or state, not to wait. |
+| `list_subagents({})` | List children owned by this parent session. Use this for ids or current state, not to wait. |
+| `stop_subagent({ id })` | Persist a stopped intent, then end the runtime. |
+
+There is no batch-spawn tool: parallel children come from Pi's own parallel tool calls.
+`agent` is required; this package ships no built-in default agent, so an unresolved or
+missing agent name fails before any process starts.
+
+The child branch registers exactly one tool, `contact_parent({ reason, message })`, with
+reasons `progress_update`, `important_finding`, `need_decision`, and `blocked`. Calling it
+wakes the parent. If a child ends a turn without reporting, it may receive a follow-up
+nudge to call `contact_parent`; the child session is never auto-exited. Delay defaults to
+5s (`PI_SUBAGENTS_NUDGE_DELAY_MS`); set `PI_SUBAGENTS_NUDGE_DISABLE=1` to turn it off.
+
+`get_subagent` / `list_subagents` include `interactive`, `freshness`, `updatedAt`, and the
+resolved `model` / `thinking` with whether each came from the agent or the parent.
+Reports delivered to the parent are titled with the agent display name and child id.
+
+## Agent definitions
+
+Agent Markdown files are discovered in this order, most specific first, by `name`:
+
+```text
+<cwd>/.pi/agents/*.md
+<cwd>/.agents/agents/*.md
+~/.pi/agent/agents/*.md
+```
+
+Frontmatter is parsed with Pi's `parseFrontmatter` and then validated against this
+package's schema. Supported fields: `name`, `display_name`, `description`, `hidden`,
+`model`, `thinking`, `tools`, `exclude_tools`, `extensions`, `skills`, `interactive`.
+`interactive` defaults to `false` and is frozen into the launch snapshot. The Markdown body
+becomes the child's agent instructions.
+
+Validation happens before launch and fails closed:
+
+- unknown fields, and the recognized-but-unimplemented `exclude_extensions`,
+  `preload_skills`, `max_turns`, `max_tokens` fields;
+- `model` that is not an exact `provider/model-id` present in Pi's `ModelRegistry`;
+- invalid `thinking` levels, conflicting `tools`/`exclude_tools`, missing resource paths;
+- any policy that would remove the `contact_parent` bridge.
+
+`model` and `thinking` fall back to the parent session's current values, and the resolved
+result records whether each value came from the agent (`agent`) or the parent (`parent`).
+Models are never chosen by fuzzy match.
+
+## Launch configuration
+
+One builder produces every child process description. It resolves the Pi invocation, the
+full argv, cwd, session placement, model/thinking, tool/extension/skill selection, the
+assembled prompt, and the non-secret bridge environment, then reports `mode` and `stdio`
+separately. Values that contain spaces stay single argv atoms, and no shell is involved.
+
+Session identity is always explicit: a session that has never been flushed is created with
+`--session-id <id> --session-dir <dir>`, and a flushed session is opened by path. No path
+opens an absent file, so a child can never silently acquire a random session id.
+`extensions: false` keeps this package's absolute `-e <entry>` bridge argument while
+disabling discovery, so a child never loses `contact_parent` and never gains a manager.
+
+## Presentation hosts
+
+A HostAdapter only carries a native TUI. It receives the same LaunchSpec the RPC runner
+uses, probes real host capability, and never re-resolves agent, model, or Pi flags.
+
+`/attach-subagent <id>` opens an RPC child as native Pi in Herdr or cmux. With no
+id, `/subagents` or the attach shortcut uses `ctx.ui.select`. An idle child switches
+immediately. A busy child waits for the current turn's `turn_end`, then closes the
+RPC writer. Timeout or cancel keeps the RPC writer and fails visibly. Session files
+that have never flushed refuse attach. There is no model-facing attach tool.
+
+- Default selection is Herdr, then cmux. An explicit unavailable host fails visibly and
+  does not fall back.
+- Probe talks to the live session (`herdr pane current` inside `HERDR_ENV=1`, `cmux ping`
+  plus `capabilities`). A binary on PATH is not enough.
+- Herdr attach splits with `--cwd` / `--env` and runs the quoted command+argv. cmux attach
+  uses `new-split --command`. Neither path invents a second argv.
+- Observation uses host process APIs where they exist. A pane still being open is not
+  evidence that the Pi process is alive. Command timeout is not rollback: the attachment
+  is returned so the caller can inspect it, and nothing is closed automatically.
+- Cleanup closes only the pane or surface this transition created and still owns.
+- After a confirmed TUI process exit (`/quit`, pane close, crash), the same runner restores
+  RPC on session A and waits for input. Crash adds an extra diagnostic. A pane event with a
+  still-live process does not detach.
+- `/new`, `/resume` other, and `/fork` unbind A only after the TUI is confirmed on session
+  B. A returns to RPC; B is a native Pi session, not a subagent, and cannot `contact_parent`
+  as A. `/reload` and `/resume` of A do not detach. This package does not intercept a
+  user opening the same session with native `/resume` outside the managed path.
+- A confirmed user interrupt (Pi `stopReason: aborted`) notifies the parent and stays on
+  the TUI. Nothing is auto-resumed.
+
+## Persistence
+
+Each parent session gets its own registry file under
+`<agent-dir>/pi-subagents/registry/<parentSessionId>.json`, written through ext-core's
+atomic, cross-process-locked JSON root update. Nothing is written to `settings.json`.
+
+A record holds the child id, parent session id, session id/path, cwd, initial task, active
+or stopped intent, the non-secret launch configuration, state and mode, last-known summary
+and usage, and the reconnect metadata (`runtimeIdentity`, `endpoint`, optional `pid`).
+Revisions are monotonic; stale writers and updates aimed at a replaced runtime are
+rejected. Corruption, unsupported versions, parent mismatch, and identity mismatch fail
+closed instead of returning partial state. API keys and controller tokens are never
+persisted.
+
+Spawn order is fixed: resolve, persist intent, then start the runner. If the registry write
+fails, no child process is started, and a session that has already flushed must still prove
+its id on disk before anything opens it.
+
+Parent reload reconnects a surviving runner by `runtimeIdentity` and endpoint. Replacement
+starts only after the old runner PID is confirmed dead (a reused PID is not treated as
+ours). Pending input is marked interrupted and never replayed. A flushed session whose
+file is missing fails closed; a never-flushed child keeps its original session id.
+
+## Observation and commands
+
+An interactive TUI parent shows an above-editor widget of live children (`starting`,
+`running`, `idle`). It is a projection of `list()`:
+no second running set, no border, no file polling. Rows use the agent display name when
+present, mark `last known` when the runner is not connected, and show elapsed time since
+spawn. Headless/RPC parents do not mount it.
+
+`setStatus` shows a compact `running` / `idle` / `tui` / `failed` line, including
+`interrupted` when that diagnostic is set. `/subagents` lists, inspects, attaches, sends,
+or stops through `ctx.ui.select`. `/attach-subagent` and `/stop-subagent` accept an id or
+open the same picker. Shortcuts `ctrl+shift+a` and `ctrl+shift+s` call the same manager
+operations. Spawn/send/get/list/stop results render through ext-core ToolTui so collapsed
+output still keeps the full details.
+
+A TUI child shows one borderless identity line (agent, `contact_parent`, tool count). It
+is not a control surface.
+
+## Notes
+
+- `@hheei/pi-ext-core` is a production dependency, not a separately loaded extension.
+- Child processes are deliberately independent of the parent process lifetime; parent
+  cleanup releases local connections only.
+- This package does not use ext-core's in-process `startSubagent`: that contract cancels the
+  child when the parent shuts down, which is incompatible with surviving, reconnectable
+  children.

package/dist/agent-resolver.d.ts

@@ -0,0 +1,37 @@
+import type { ResolvedAgentPolicy, ThinkingLevel } from "./domain.js";
+export interface ModelRegistryLike {
+    /** `ModelRegistry.find` from the Pi extension context: exact provider/id lookup. */
+    find(provider: string, modelId: string): unknown | undefined;
+}
+export interface ParentAgentDefaults {
+    /** Parent's current model, inherited only when the definition does not name one. */
+    readonly model: {
+        readonly provider: string;
+        readonly id: string;
+    };
+    /** Parent's current thinking level, inherited only when the definition does not name one. */
+    readonly thinking: ThinkingLevel;
+}
+export interface ResolveAgentOptions {
+    readonly name: string;
+    readonly cwd: string;
+    readonly modelRegistry: ModelRegistryLike;
+    readonly parent: ParentAgentDefaults;
+    /** Absolute path to this package's extension entry, always kept in the child extension selection. */
+    readonly bridgeExtensionPath: string;
+    readonly homeDirectory?: string;
+}
+export interface DiscoveredAgent {
+    readonly name: string;
+    readonly path: string;
+    readonly frontmatter: Record<string, unknown>;
+    readonly body: string;
+}
+export declare function discoverAgents(cwd: string, homeDirectory?: string): Promise<readonly DiscoveredAgent[]>;
+/**
+ * Resolves one agent definition into an immutable, non-secret policy snapshot.
+ * Unknown fields, deferred fields, unknown models, invalid thinking levels,
+ * conflicting tool policy, and a disabled `contact_parent` bridge all fail here,
+ * before any child process exists.
+ */
+export declare function resolveAgent(options: ResolveAgentOptions): Promise<ResolvedAgentPolicy>;

package/dist/agent-resolver.js

@@ -0,0 +1,232 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+import { CONTACT_PARENT_TOOL_NAME, isRecord, isThinkingLevel } from "./domain.js";
+/**
+ * Agent definition fields this version actually implements. Anything outside this
+ * table fails before launch; `DEFERRED_FIELDS` exists only to give those known
+ * candidates a clearer message than an outright typo.
+ */
+const SUPPORTED_FIELDS = {
+    name: true,
+    display_name: true,
+    description: true,
+    hidden: true,
+    model: true,
+    thinking: true,
+    tools: true,
+    exclude_tools: true,
+    extensions: true,
+    skills: true,
+    interactive: true,
+};
+/** Recognized candidate fields with no execution semantics yet; silently ignoring them is prohibited. */
+const DEFERRED_FIELDS = {
+    exclude_extensions: true,
+    preload_skills: true,
+    max_turns: true,
+    max_tokens: true,
+};
+function readableError(path, message) {
+    return new Error(`Invalid agent definition ${path}: ${message}`);
+}
+function requiredString(value, field, path) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw readableError(path, `${field} must be a non-empty string`);
+    }
+    return value.trim();
+}
+function optionalString(value, field, path) {
+    if (value === undefined)
+        return undefined;
+    return requiredString(value, field, path);
+}
+function stringList(value, field, path) {
+    if (value === undefined)
+        return [];
+    const raw = typeof value === "string" ? value.split(",") : value;
+    if (!Array.isArray(raw))
+        throw readableError(path, `${field} must be a string or string array`);
+    const values = raw.map((item) => requiredString(item, field, path));
+    if (new Set(values).size !== values.length) {
+        throw readableError(path, `${field} selects the same entry twice`);
+    }
+    return values;
+}
+const LOCAL_PATH_PATTERN = /^(?:[A-Za-z]:[\\/]|[~/]|\.{1,2}[\\/])/;
+/** Local selections become absolute paths next to the definition; package specs are left for Pi to resolve. */
+function resolveResourcePaths(value, field, path) {
+    return stringList(value, field, path).map((item) => {
+        if (!LOCAL_PATH_PATTERN.test(item))
+            return item;
+        const trimmed = item.startsWith("~/") ? join(homedir(), item.slice(2)) : item;
+        return resolve(dirname(path), trimmed);
+    });
+}
+async function resourceSelection(value, field, path) {
+    if (value === undefined || value === true)
+        return { discovery: true, paths: [] };
+    if (value === false)
+        return { discovery: false, paths: [] };
+    const paths = resolveResourcePaths(value, field, path);
+    for (const selected of paths) {
+        if (!isAbsolute(selected))
+            continue;
+        const exists = await stat(selected).then(() => true, () => false);
+        if (!exists)
+            throw readableError(path, `${field} entry does not exist: ${selected}`);
+    }
+    return { discovery: true, paths };
+}
+async function markdownFiles(directory) {
+    let entries;
+    try {
+        entries = await readdir(directory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    return entries
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+        .map((entry) => join(directory, entry.name))
+        .sort((left, right) => left.localeCompare(right));
+}
+/** Most specific scope first; the first definition of a name wins deterministically. */
+function agentDirectories(cwd, homeDirectory) {
+    return [
+        join(cwd, ".pi", "agents"),
+        join(cwd, ".agents", "agents"),
+        join(homeDirectory, ".pi", "agent", "agents"),
+    ];
+}
+async function readAgentDefinition(path) {
+    const content = await readFile(path, "utf8").catch((error) => {
+        throw new Error(`Unable to read agent definition ${path}`, { cause: error });
+    });
+    const parsed = parseFrontmatter(content);
+    if (!isRecord(parsed.frontmatter))
+        throw readableError(path, "frontmatter must be an object");
+    return {
+        name: requiredString(parsed.frontmatter.name, "name", path),
+        path,
+        frontmatter: parsed.frontmatter,
+        body: parsed.body,
+    };
+}
+export async function discoverAgents(cwd, homeDirectory = homedir()) {
+    const selected = new Map();
+    for (const directory of agentDirectories(resolve(cwd), resolve(homeDirectory))) {
+        for (const path of await markdownFiles(directory)) {
+            const agent = await readAgentDefinition(path);
+            if (!selected.has(agent.name))
+                selected.set(agent.name, agent);
+        }
+    }
+    return [...selected.values()];
+}
+function resolveModel(value, defaults, registry, path) {
+    if (value === undefined) {
+        if (registry.find(defaults.model.provider, defaults.model.id) === undefined) {
+            throw readableError(path, `parent model ${defaults.model.provider}/${defaults.model.id} is unavailable`);
+        }
+        return { ...defaults.model, source: "parent" };
+    }
+    const reference = requiredString(value, "model", path);
+    const slash = reference.indexOf("/");
+    if (slash <= 0 || slash === reference.length - 1) {
+        throw readableError(path, "model must use the exact provider/model-id form");
+    }
+    const provider = reference.slice(0, slash);
+    const id = reference.slice(slash + 1);
+    if (registry.find(provider, id) === undefined) {
+        throw readableError(path, `unknown model ${provider}/${id}`);
+    }
+    return { provider, id, source: "agent" };
+}
+/**
+ * Resolves one agent definition into an immutable, non-secret policy snapshot.
+ * Unknown fields, deferred fields, unknown models, invalid thinking levels,
+ * conflicting tool policy, and a disabled `contact_parent` bridge all fail here,
+ * before any child process exists.
+ */
+export async function resolveAgent(options) {
+    const agents = await discoverAgents(options.cwd, options.homeDirectory);
+    const discovered = agents.find((agent) => agent.name === options.name);
+    if (discovered === undefined)
+        throw new Error(`Unknown agent ${options.name}`);
+    const path = discovered.path;
+    for (const field of Object.keys(discovered.frontmatter)) {
+        if (SUPPORTED_FIELDS[field] === true)
+            continue;
+        if (DEFERRED_FIELDS[field] === true) {
+            throw readableError(path, `${field} is not part of the V1 agent contract`);
+        }
+        throw readableError(path, `unsupported field ${field}`);
+    }
+    // `discovered.name` is already the definition's own `name`; the lookup above proved they match.
+    const name = discovered.name;
+    const hidden = discovered.frontmatter.hidden ?? false;
+    if (typeof hidden !== "boolean")
+        throw readableError(path, "hidden must be boolean");
+    const body = discovered.body.trim();
+    if (body === "")
+        throw readableError(path, "Markdown body must not be empty");
+    const tools = stringList(discovered.frontmatter.tools, "tools", path);
+    const excludeTools = stringList(discovered.frontmatter.exclude_tools, "exclude_tools", path);
+    if (excludeTools.includes(CONTACT_PARENT_TOOL_NAME)) {
+        throw readableError(path, `exclude_tools cannot disable the required ${CONTACT_PARENT_TOOL_NAME} bridge`);
+    }
+    const overlap = tools.find((tool) => excludeTools.includes(tool));
+    if (overlap !== undefined)
+        throw readableError(path, `tool ${overlap} is both allowed and excluded`);
+    if (tools.length > 0 && !tools.includes(CONTACT_PARENT_TOOL_NAME)) {
+        throw readableError(path, `tools must include the required ${CONTACT_PARENT_TOOL_NAME} bridge`);
+    }
+    const thinkingValue = discovered.frontmatter.thinking;
+    if (thinkingValue !== undefined && !isThinkingLevel(thinkingValue)) {
+        throw readableError(path, "thinking is invalid");
+    }
+    const extensionSelection = await resourceSelection(discovered.frontmatter.extensions, "extensions", path);
+    const bridgeExtensionPath = resolve(options.bridgeExtensionPath);
+    const extensionPaths = [
+        ...extensionSelection.paths.filter((selected) => selected !== bridgeExtensionPath),
+        bridgeExtensionPath,
+    ];
+    const skills = await resourceSelection(discovered.frontmatter.skills, "skills", path);
+    const displayName = optionalString(discovered.frontmatter.display_name, "display_name", path);
+    const description = optionalString(discovered.frontmatter.description, "description", path);
+    const interactiveValue = discovered.frontmatter.interactive;
+    if (interactiveValue !== undefined && typeof interactiveValue !== "boolean") {
+        throw readableError(path, "interactive must be boolean");
+    }
+    const interactive = interactiveValue === true;
+    return Object.freeze({
+        agent: Object.freeze({
+            name,
+            ...(displayName === undefined ? {} : { displayName }),
+            ...(description === undefined ? {} : { description }),
+            hidden,
+            sourcePath: path,
+            instructions: body,
+        }),
+        model: Object.freeze(resolveModel(discovered.frontmatter.model, options.parent, options.modelRegistry, path)),
+        thinking: Object.freeze({
+            level: thinkingValue ?? options.parent.thinking,
+            source: thinkingValue === undefined ? "parent" : "agent",
+        }),
+        tools: Object.freeze(tools),
+        excludeTools: Object.freeze(excludeTools),
+        extensions: Object.freeze({
+            discovery: extensionSelection.discovery,
+            paths: Object.freeze(extensionPaths),
+        }),
+        skills: Object.freeze({
+            discovery: skills.discovery,
+            paths: Object.freeze([...skills.paths]),
+        }),
+        interactive,
+    });
+}

package/dist/child-bridge.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Child-branch session binding. The TUI process may /reload the same session,
+ * /quit, or switch to an unrelated session B. Only a confirmed leave of A
+ * unbinds the bridge; shutdown or switch requests alone do not.
+ */
+import type { ExtensionAPI, SessionStartEvent } from "@earendil-works/pi-coding-agent";
+import type { ChildIdentity } from "./domain.js";
+import { PauseGate } from "./pause-gate.js";
+export type ChildLifecycleKind = "left_session" | "tui_quit" | "user_interrupt";
+export interface ChildBridgeState {
+    bound: boolean;
+    boundSessionId: string;
+    readonly gate: PauseGate;
+}
+export interface ChildPauseSocket {
+    connect?(signal?: AbortSignal): Promise<void>;
+    reportPaused(generation: number, signal?: AbortSignal): Promise<void>;
+    onEvent(listener: (event: unknown) => void): () => void;
+    close(): void;
+}
+export interface ChildBridgeOptions {
+    readonly pauseSocket?: ChildPauseSocket;
+    readonly gate?: PauseGate;
+    readonly connect?: (socket: ChildPauseSocket, signal?: AbortSignal) => Promise<void>;
+}
+export declare function boundSessionIdFromEnv(env?: NodeJS.ProcessEnv): string | undefined;
+export declare function shouldLeaveBoundSession(params: {
+    readonly boundSessionId: string;
+    readonly currentSessionId: string;
+    readonly reason: SessionStartEvent["reason"];
+}): boolean;
+export declare function isConfirmedUserInterrupt(messages: readonly {
+    role?: string;
+    stopReason?: string;
+}[] | undefined): boolean;
+export declare function lastActivityText(messages: readonly {
+    role?: string;
+    content?: unknown;
+}[] | undefined): string;
+/** Registers the child-only tools, identity widget, and session-leave reporting. */
+export declare function registerChildBridge(pi: ExtensionAPI, identity: ChildIdentity, options?: ChildBridgeOptions): ChildBridgeState;