@narumitw/pi-subagents 3.0.1 → 3.1.0

package/README.md

@@ -7,8 +7,10 @@ Pi Subagents runs Pi jobs in separate child processes and supports authenticated
 ## ✨ Features
 
 - Runs each job in an isolated Pi child process and returns its job ID immediately.
-- Uses the task to define the child's specialization and the tool list to limit its capabilities.
+- Uses the task to define the child's specialization and explicit tools, skills, and extensions to define its capabilities.
 - Defaults work tools to `read`, `grep`, `find`, and `ls`.
+- Can attach validated local skills and trusted local extensions to one job without enabling automatic discovery.
+- Verifies requested extension tools before sending the task to the child model.
 - Inherits the main agent's effective model and uses its thinking level by default.
 - Gives the main agent and every child a context-specific `subagent_send` contract for bidirectional requests and responses.
 - Gives every child `subagent_wait` for an answer to a child-originated request.
@@ -20,7 +22,6 @@ Pi Subagents runs Pi jobs in separate child processes and supports authenticated
 ## 📦 Install
 
 The version 3 runtime documented here is not yet published to npm.
-
 The npm package still contains the legacy 2.x runtime and does not provide the tools below.
 
 Install the repository source as one Pi package:
@@ -49,40 +50,28 @@ pi --no-extensions -e ./packages/pi-subagents
 ```
 
 The package entry is generated at `dist/index.ts` and loaded through Pi's Jiti runtime.
-
 An unbuilt local package directory cannot load its declared extension entry.
 
 Pi extensions and children with `bash`, `powershell`, `edit`, or `write` execute with your user permissions.
-
 Review the source before installing or invoking the extension.
 
 ## 🚀 Quick start
 
 Call `subagent_spawn` with a self-contained task and only the work tools that task needs.
 
-The package intentionally does not register or publish a skill.
-
-Create a project skill under `.pi/skills/<your-skill>/SKILL.md` or a global skill under `~/.pi/agent/skills/<your-skill>/SKILL.md` when you want reusable delegation policy.
-
-Choose a name, trigger description, tool policy, task format, and verification workflow for your own use case.
-
-The repository-only [`using-pi-subagents` example](https://github.com/narumiruna/pi-extensions/tree/main/packages/pi-subagents/skills/using-pi-subagents) demonstrates one possible design without imposing it on installed users.
-
 The call returns a `jobId` immediately, and the job continues in the background.
-
 Continue useful main-agent work until the result is required or a completion arrives.
 
-Call `subagent_send` with `recipient: jobId` to ask an active child a question.
-
-If `subagent_wait` returns `reason: "subagent_message"`, handle the visible request or response and wait for the job again only when needed.
+Use messaging only when needed:
 
-Answer a child-originated request by calling `subagent_send` with its `requestId`.
+- Call `subagent_send` with `recipient: jobId` to ask an active child a question.
+- If `subagent_wait` returns `reason: "subagent_message"`, handle the visible request or response and wait for the job again only when needed.
+- Answer a child-originated request by calling `subagent_send` with its `requestId`.
 
 Completion messages follow Pi's global tool-output expansion state and the `app.tools.expand` binding (`Ctrl+O` by default).
 
-In TUI mode, the above-editor widget shows each queued or running job's ID, state, elapsed time, timeout, and selected work tools.
-
-The widget omits the fixed communication tools, disappears when no jobs remain active, and clears when the session ends.
+In TUI mode, the above-editor widget shows each queued or running job's ID, state, elapsed time, timeout, and selected core and extension tool names.
+It omits fixed communication tools, attachment paths, and resource totals, disappears when no jobs remain active, and clears when the session ends.
 
 ## 🛠️ Tools
 
@@ -90,7 +79,7 @@ The main Pi session exposes five fixed tools:
 
 | Tool | Parameters | Purpose |
 | --- | --- | --- |
-| `subagent_spawn` | `task`, optional `tools`, `thinkingLevel`, `timeout` | Start one subagent job and return its `jobId`. |
+| `subagent_spawn` | `task`, optional `tools`, `skills`, `extensions`, `thinkingLevel`, `timeout` | Start one subagent job and return its `jobId`. |
 | `subagent_inspect` | none | List privacy-filtered retained-job metadata. |
 | `subagent_cancel` | `jobId` | Idempotently cancel one queued or running job. |
 | `subagent_wait` | `jobId`, optional `timeout` | Wait for a job or return early for an incoming child message. |
@@ -103,120 +92,84 @@ Every child exposes these communication tools in addition to its selected work t
 | `subagent_send` | optional `requestId`, plus `message` | Omit `requestId` to send a new request to main, or provide it to answer one pending main-agent request. |
 | `subagent_wait` | `requestId`, optional `timeout` | Wait for the main agent's plain-text response to a child-originated request. |
 
-Main and child processes receive separate provider-visible `subagent_send` definitions for their own context.
-
-The main agent starts a request with an active job ID as `recipient` and omits `requestId`.
-
-The main agent answers a child request with `requestId` and omits `recipient`.
+Main and child processes receive separate provider-visible `subagent_send` definitions for their own context:
 
-A child starts a request to main by omitting `requestId`.
-
-A child answers a main-agent request by providing `requestId`.
+- The main agent starts a request with an active job ID as `recipient` and omits `requestId`.
+- The main agent answers a child request with `requestId` and omits `recipient`.
+- A child starts a request to main by omitting `requestId`.
+- A child answers a main-agent request by providing `requestId`.
 
 Execution and wait timeouts use seconds, accept finite numbers greater than zero through 2,147,483.647, and have no default.
-
 Omitting a job execution timeout lets the child run until it exits, is cancelled, the session shuts down, or the Pi process exits.
-
 A wait timeout or caller cancellation stops only that wait and does not cancel its job or message request.
-
 An incoming main-agent request interrupts an active child `subagent_wait` after RPC steering is queued so the child can receive the new request.
-
 The interrupted child-originated request remains active and may be waited on again.
 
 Tasks are limited to 50 KiB of UTF-8 text.
-
 Requests and responses are limited to 48 KiB and 1,992 lines so their protocol envelopes fit Pi's 50 KiB and 2,000-line model-text bounds without truncating accepted content.
-
 Each job may have up to four unresolved or answered-but-not-consumed requests across both directions.
-
 The terminal states are `completed`, `partial`, `failed`, `timed_out`, and `cancelled`.
+`subagent_inspect` never returns complete task text, child output, prompts, selected tools, attachment paths or totals, context, credentials, environment variables, requests, responses, or secrets.
 
-`subagent_inspect` never returns complete task text, child output, prompts, selected tools, context, credentials, environment variables, requests, responses, or secrets.
-
-See [`docs/tools.md`](./docs/tools.md) for the concise schema reference.
+See [`docs/tools.md`](./docs/tools.md) for the concise schema reference, [`docs/attachments.md`](./docs/attachments.md) for attachment validation, and [`docs/messaging.md`](./docs/messaging.md) for messaging behavior.
 
 ## ⚙️ Job configuration
 
 The task should state the child's role, objective, scope, constraints, and expected result.
+For reusable delegation policy, you can create your own project skill under `.pi/skills/<your-skill>/SKILL.md` or global skill under `~/.pi/agent/skills/<your-skill>/SKILL.md`.
+Choose its name, trigger, tool policy, task format, and verification workflow for your use case.
+The package intentionally registers and publishes no skill; the repository-only [`using-pi-subagents` example](https://github.com/narumiruna/pi-extensions/tree/main/packages/pi-subagents/skills/using-pi-subagents) is an optional starting point.
+
+`subagent_spawn` accepts this additive configuration:
+
+```ts
+{
+  task: string;
+  tools?: Array<"read" | "bash" | "powershell" | "edit" | "write" | "grep" | "find" | "ls">;
+  skills?: string[];
+  extensions?: Array<{ path: string; tools: string[] }>;
+  thinkingLevel?: "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+  timeout?: number;
+}
+```
 
-The optional `tools` list limits what the child can do.
-
-Accepted names are `read`, `bash`, `powershell`, `edit`, `write`, `grep`, `find`, and `ls`.
-
-Unavailable or extension-only tool names are rejected before a job is queued.
-
-Omitting `tools` selects `read`, `grep`, `find`, and `ls`.
-
-Passing an empty list gives the child no work tools.
-
+The optional `tools` list selects Pi core work tools.
+Omitting it selects `read`, `grep`, `find`, and `ls`, while an empty list gives the child no core work tools.
 The runtime always adds `subagent_send` and child `subagent_wait` and removes duplicate names.
+Adding `edit` or `write` lets the child modify files, while `bash` or `powershell` grants unrestricted command execution.
 
-Adding `edit` or `write` lets the child modify files.
+The optional `skills` list attaches local Pi skills through progressive disclosure without injecting their full bodies or adding tools.
+Every attached skill path must contain at least one loadable skill, every non-ignored declared skill must load successfully, and skill names must be unique across attachments.
 
-Adding `bash` or `powershell` grants unrestricted command execution and can also modify the workspace.
+Each `extensions` entry loads a trusted local extension file or directory and selects its initial extension tools.
+An empty `tools` list loads provider or lifecycle behavior without initially exposing extension tools.
+The parent checks that each requested tool comes from its specified attachment before the child model receives the task.
+Attached extensions run with the child's user permissions and are not a sandbox.
 
-The optional `thinkingLevel` accepts `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, or `max`.
+Attachments must be existing local paths, not npm, Git, or URL sources.
+Project-local attachments and resources resolved from their packages require project trust, including paths that symlink into the project.
+A job accepts up to 16 skill paths, 16 extension entries, and 64 selected work tools.
+The child inherits the main agent's effective model and thinking level by default; there is no per-job model override.
+Parent-only extension providers require an attached extension that registers them in the child.
+Process-local runtime API keys, including a parent-only `--api-key`, are unavailable to the child; use stored or inherited environment credentials.
 
-Omitting `thinkingLevel` captures the main agent's effective level when `subagent_spawn` executes.
-
-The child inherits the main agent's effective provider and model when `subagent_spawn` executes.
-
-Spawn rejects providers registered by a parent extension because child processes disable unrelated extensions.
-
-Spawn also rejects process-local runtime API keys, including a parent-only `--api-key` value.
-
-Use stored or environment credentials that child processes can read.
-
-The extension does not expose a per-job model override.
+See [Attachment behavior](./docs/attachments.md) for detailed path checks, package preflight, tool ownership, and resource limits.
 
 ## 🔄 Messaging, lifecycle, and retention
 
-The session starts one TCP broker on `127.0.0.1` with an operating-system-assigned ephemeral port.
-
-Each job receives one cryptographically random token bound to its job identity and session generation.
-
-The parent passes the broker credentials once through a private inherited pipe instead of placing them in the child's initial environment or command line.
-
-The child bridge reads and closes that descriptor before model tool execution.
+A main-originated request to a queued job waits for Pi RPC readiness before delivery. After delivery starts, cancellation stops only the caller's wait; the request may still arrive. An interrupted child-originated request remains active and can be waited on again.
 
-Each child runs in Pi RPC mode so the parent can inject a main-originated request through `steer` after the initial prompt is accepted.
+The first accepted `subagent_send` response wins; repeated responses do not replace it. The execution timeout starts only after Pi accepts the RPC prompt. Jobs reach exactly one terminal state, and inspection retains up to 32 terminal records for up to 24 hours within the current session.
 
-Each child broker call uses one request-scoped connection, while a response wait uses an abortable long poll.
+The broker uses loopback connections and per-job credentials passed through a private pipe, not the child's initial environment or command line. Cancelling a job or replacing the session revokes those credentials, stops pending work, and prevents stale completion delivery.
 
-A main-originated request to a queued job waits for RPC readiness before delivery is accepted.
-
-After RPC accepts the steering message, the runtime interrupts active child response waits so the queued request can reach the child model.
-
-Caller cancellation before RPC delivery starts rolls the request back.
-
-Once RPC delivery starts, cancellation stops only the caller's wait; the request may still arrive and remains answerable until delivery fails or the job terminates.
-
-The interrupted child-originated requests remain active and retryable.
-
-The first accepted `subagent_send` response wins.
-
-Repeated responses acknowledge the existing answer without replacing it.
-
-A child may retry `subagent_wait` after a wait timeout because the underlying request remains active.
-
-A new job starts as `queued`, transitions to `running`, and reaches exactly one terminal state.
-
-The runtime retains up to 32 recent terminal records for up to 24 hours within the current extension session.
-
-Inspection reports older records removed by retention bounds through `omitted.jobs`.
-
-Cancelling or terminalizing a job revokes its token and rejects pending child waits before stale output can replace the terminal state.
-
-Session replacement and shutdown cancel active work, suppress stale completion delivery, revoke credentials, close sockets, and stop the broker.
+See [Messaging and lifecycle](./docs/messaging.md) for delivery, retry, retention, and shutdown details.
 
 ## 🔀 Migrating from 2.x
 
 Version 3.0 replaces the previous orchestration runtime.
-
 It does not migrate legacy settings, persisted jobs, retained conversations, or recovery state.
-
 Finish or record any required work before upgrading, then start a fresh Pi session so stored calls do not request removed tool names.
-
 Use these replacements where the new job model supports the previous intent:
 
 | Previous interface | Version 3 interface |
@@ -229,73 +182,64 @@ Use these replacements where the new job model supports the previous intent:
 | Running main-to-child questions | Main and child `subagent_send` |
 
 The version 3 `subagent_send` contracts are not compatible with the legacy retained-agent follow-up tool of the same name.
-
 The `/subagents` command, extension settings, legacy retained follow-ups, `subagent_mailbox`, `subagent_consult`, custom agent catalogs, advanced orchestration, alternate transports, trust-aware cwd policy, and extension-owned worktrees have no direct replacement.
-
 Describe the child's specialization in `task` and grant only the required work tools through `tools`.
 
 ## 🔒 Security and privacy
 
 The selected work tools run in the current working directory.
-
 The default list contains no shell or file-mutation tool.
-
 It is not a filesystem sandbox because its read tools can inspect files available to the user account.
-
 Selecting `bash`, `powershell`, `edit`, or `write` permits workspace mutation with the Pi process environment and user permissions.
 
-Every child disables session persistence, unrelated extensions, skills, and prompt templates.
-
-Provider selection therefore supports Pi's child-visible built-in and configured providers, not providers registered only by a parent extension.
-
-Credentials must be available independently to the child through Pi's stored credentials or its inherited environment.
+Every child disables session persistence and automatic discovery of extensions, skills, and prompt templates.
+Only the communication bridge and explicitly attached resources are added back for that job.
+Provider selection supports Pi's child-visible built-in and configured providers plus providers registered by an attached extension.
+Credentials must be available independently to the child through Pi's stored credentials or inherited environment.
 
 The broker accepts only loopback TCP connections with an active per-job token.
-
 The token is bootstrapped through a private inherited pipe and is absent from the child's initial environment and command line.
 
 A child request or response is visible main-agent model context, but its envelope explicitly identifies it as untrusted subagent content rather than user authorization.
-
 A child message cannot grant permission for writes, shell commands, credential access, or other privileged actions.
-
 A main-agent request is visible child model context, but it cannot expand the child's selected tools or grant capabilities the child did not receive at spawn time.
 
-Terminal controls and bidirectional controls are stripped before untrusted child text is displayed.
+An attached skill contributes model instructions and may direct already selected tools to bundled helpers.
+An attached extension is fully privileged executable code with the child process's user permissions, can run during factory and lifecycle hooks, can alter prompts or tool behavior, and can change active tools after startup.
+Its requested tool list controls the initial provider-visible loadout but is not an operating-system sandbox.
+Canonical attachment paths are passed to Pi in the child command line, but parent-generated inspection, completion, and broker metadata omit them and child diagnostic errors redact requested attachment roots before publication.
+Attached code and model output remain untrusted and can disclose paths they can access, so attach only code you trust.
 
+Terminal controls and bidirectional controls are stripped before untrusted child text is displayed.
 Tasks, repository context, requests, responses, and inspected file content may be sent to the selected model provider.
-
 Parallel writers require disjoint ownership or workspace isolation outside this extension.
 
 ## 🚧 Limitations
 
-The extension does not load arbitrary extension tools or parent-registered model providers in child processes.
-
-Process-local runtime API keys are not forwarded to children.
-
-The extension does not provide custom agents, per-job models, custom system prompts, peer-to-peer child messaging, retained conversations, user-directed follow-up work, mailboxes, Agent Teams, chains, fan-in aggregators, panels, workflow DAGs, dynamic scheduling, verification orchestration, nested subagents, or extension-owned semantic memory.
-
-Bidirectional messages use request-response coordination, not a retained conversational session.
-
-The main agent must verify child claims against the actual diff and deterministic checks.
-
-Child requests and responses trigger a main-agent turn, but asynchronous job completions do not wake an otherwise idle model turn automatically.
-
-Jobs, broker requests, and retained results do not survive extension reload, session replacement, or process exit.
+- Attachments must be existing local files or directories; package, Git, URL, and automatic parent-resource inheritance are unsupported.
+- An attached extension may recreate a parent-registered provider, but parent in-memory extension state and runtime-only API keys are not forwarded.
+- The extension does not provide custom agents, per-job models, custom system prompts, peer-to-peer child messaging, retained conversations, user-directed follow-up work, mailboxes, Agent Teams, chains, fan-in aggregators, panels, workflow DAGs, dynamic scheduling, verification orchestration, nested subagents, or extension-owned semantic memory.
+- Bidirectional messages use request-response coordination, not a retained conversational session.
+- The main agent must verify child claims against the actual diff and deterministic checks.
+- Child requests and responses trigger a main-agent turn, but asynchronous job completions do not wake an otherwise idle model turn automatically.
+- Jobs, broker requests, and retained results do not survive extension reload, session replacement, or process exit.
 
 ## 🗂️ Package layout
 
 ```text
 packages/pi-subagents/
-├── dist/                        # Generated Jiti runtime and child bridge
-├── docs/                        # Concise tools and design references
-├── scripts/                     # Deterministic runtime builder
-├── skills/using-pi-subagents/  # Repository-only example delegation skill
-├── src/                         # Extension, broker, child bridge, and subprocess runtime
-├── test/                        # Protocol, lifecycle, process, and policy tests
-├── package.json                 # Pi extension declaration
-└── README.md                    # User guide and safety boundaries
+├── src/                               # Authoritative implementation and helpers
+│   ├── index.ts                       # Thin Pi entrypoint
+│   └── subagents.ts                   # Job, broker, and child lifecycle
+├── dist/                              # Generated Jiti runtime, child bridge, and readiness probe
+├── scripts/build-runtime.mjs          # Runtime builder
+├── docs/                              # Published reference documentation
+├── skills/using-pi-subagents/         # Repository-only example; not published
+└── test/                              # Behavior and lifecycle coverage
 ```
 
+The generated runtime is built from `src/index.ts` and does not import back into `src`.
+
 ## 🔎 Keywords
 
 Pi, subagents, delegation, subagent jobs, least privilege, main-agent messaging, cancellation, job lifecycle.

package/dist/child-communication-bridge.ts

@@ -1,18 +1,20 @@
 // @generated by scripts/build-runtime.mjs; do not edit.
 // @ts-nocheck -- generated entries use .ts extensions for Pi's Jiti loader.
+import {
+  createChildCommunicationExtension
+} from "./chunks/chunk-ZOAFWLDJ.ts";
 import {
   MAX_FRAME_BYTES,
   MAX_IDENTIFIER_LENGTH,
-  captureBrokerCredentials,
-  createChildCommunicationExtension
-} from "./chunks/chunk-UKTWUQRM.js";
+  captureChildBootstrap
+} from "./chunks/chunk-YMVSJ5GE.ts";
 
 // src/child-communication-bridge.ts
 import net from "node:net";
 var CONNECT_TIMEOUT_MS = 2e3;
 var SEND_RESPONSE_TIMEOUT_MS = 5e3;
-var captured = captureBrokerCredentials();
-var childCommunicationBridge = captured ? createChildCommunicationExtension(createBrokerClient(captured)) : () => void 0;
+var captured = captureChildBootstrap();
+var childCommunicationBridge = captured ? createChildCommunicationExtension(createBrokerClient(captured.communication)) : () => void 0;
 var child_communication_bridge_default = childCommunicationBridge;
 function createBrokerClient(credentials) {
   return {
@@ -79,10 +81,7 @@ function requestBroker(credentials, request, signal, responseTimeoutMs) {
     socket.once("connect", () => {
       clearTimeout(connectTimer);
       if (responseTimeoutMs !== void 0) {
-        responseTimer = setTimeout(
-          () => finish(new Error("Subagent broker response timed out.")),
-          responseTimeoutMs
-        );
+        responseTimer = setTimeout(() => finish(new Error("Subagent broker response timed out.")), responseTimeoutMs);
         responseTimer.unref();
       }
       socket.write(`${JSON.stringify(request)}
@@ -117,9 +116,7 @@ function requestBroker(credentials, request, signal, responseTimeoutMs) {
   });
 }
 function brokerError(response) {
-  return new Error(
-    typeof response.error === "string" ? response.error : "Subagent broker rejected the request."
-  );
+  return new Error(typeof response.error === "string" ? response.error : "Subagent broker rejected the request.");
 }
 function abortError(message) {
   const error = new Error(message);

package/dist/child-communication-bridge.ts.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../src/child-communication-bridge.ts"],
-  "sourcesContent": ["import net from \"node:net\";\nimport type { ExtensionFactory } from \"@earendil-works/pi-coding-agent\";\nimport { captureBrokerCredentials } from \"./broker-credentials.js\";\nimport {\n\ttype ChildCommunicationClient,\n\tcreateChildCommunicationExtension,\n} from \"./child-communication-tools.js\";\nimport { MAX_FRAME_BYTES, MAX_IDENTIFIER_LENGTH } from \"./message-broker.js\";\nimport type { BrokerCredentials } from \"./types.js\";\n\nconst CONNECT_TIMEOUT_MS = 2_000;\nconst SEND_RESPONSE_TIMEOUT_MS = 5_000;\n\nconst captured = captureBrokerCredentials();\n\nconst childCommunicationBridge: ExtensionFactory = captured\n\t? createChildCommunicationExtension(createBrokerClient(captured))\n\t: () => undefined;\n\nexport default childCommunicationBridge;\n\nexport function createBrokerClient(credentials: BrokerCredentials): ChildCommunicationClient {\n\treturn {\n\t\tasync send(params, signal) {\n\t\t\tconst response = await requestBroker(\n\t\t\t\tcredentials,\n\t\t\t\t{ type: \"send\", token: credentials.token, ...params },\n\t\t\t\tsignal,\n\t\t\t\tSEND_RESPONSE_TIMEOUT_MS,\n\t\t\t);\n\t\t\tif (response.ok !== true) throw brokerError(response);\n\t\t\tif (\n\t\t\t\ttypeof response.requestId !== \"string\" ||\n\t\t\t\t!response.requestId ||\n\t\t\t\tresponse.requestId.length > MAX_IDENTIFIER_LENGTH ||\n\t\t\t\ttypeof response.accepted !== \"boolean\" ||\n\t\t\t\ttypeof response.duplicate !== \"boolean\"\n\t\t\t) {\n\t\t\t\tthrow new Error(\"Subagent broker returned an invalid send acknowledgement.\");\n\t\t\t}\n\t\t\treturn {\n\t\t\t\trequestId: response.requestId,\n\t\t\t\taccepted: response.accepted,\n\t\t\t\tduplicate: response.duplicate,\n\t\t\t};\n\t\t},\n\t\tasync wait(requestId, timeoutMs, signal) {\n\t\t\tconst response = await requestBroker(\n\t\t\t\tcredentials,\n\t\t\t\t{\n\t\t\t\t\ttype: \"wait\",\n\t\t\t\t\ttoken: credentials.token,\n\t\t\t\t\trequestId,\n\t\t\t\t\t...(timeoutMs !== undefined ? { timeoutMs } : {}),\n\t\t\t\t},\n\t\t\t\tsignal,\n\t\t\t);\n\t\t\tif (response.ok !== true) throw brokerError(response);\n\t\t\tif (typeof response.response !== \"string\") {\n\t\t\t\tthrow new Error(\"Subagent broker returned an invalid plain-text response.\");\n\t\t\t}\n\t\t\treturn response.response;\n\t\t},\n\t};\n}\n\nfunction requestBroker(\n\tcredentials: BrokerCredentials,\n\trequest: Record<string, unknown>,\n\tsignal?: AbortSignal,\n\tresponseTimeoutMs?: number,\n): Promise<Record<string, unknown>> {\n\tif (signal?.aborted) return Promise.reject(abortError(\"Subagent broker request was cancelled.\"));\n\treturn new Promise((resolve, reject) => {\n\t\tconst socket = net.createConnection({ host: credentials.host, port: credentials.port });\n\t\tlet response = Buffer.alloc(0);\n\t\tlet settled = false;\n\t\tlet responseTimer: NodeJS.Timeout | undefined;\n\t\tconst connectTimer = setTimeout(\n\t\t\t() => finish(new Error(\"Subagent broker connection timed out.\")),\n\t\t\tCONNECT_TIMEOUT_MS,\n\t\t);\n\t\tconnectTimer.unref();\n\t\tconst onAbort = () => finish(abortError(\"Subagent broker request was cancelled.\"));\n\t\tconst finish = (error?: Error, value?: Record<string, unknown>) => {\n\t\t\tif (settled) return;\n\t\t\tsettled = true;\n\t\t\tclearTimeout(connectTimer);\n\t\t\tif (responseTimer) clearTimeout(responseTimer);\n\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\tsocket.destroy();\n\t\t\tif (error) reject(error);\n\t\t\telse resolve(value ?? {});\n\t\t};\n\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t\tsocket.once(\"connect\", () => {\n\t\t\tclearTimeout(connectTimer);\n\t\t\tif (responseTimeoutMs !== undefined) {\n\t\t\t\tresponseTimer = setTimeout(\n\t\t\t\t\t() => finish(new Error(\"Subagent broker response timed out.\")),\n\t\t\t\t\tresponseTimeoutMs,\n\t\t\t\t);\n\t\t\t\tresponseTimer.unref();\n\t\t\t}\n\t\t\tsocket.write(`${JSON.stringify(request)}\\n`);\n\t\t});\n\t\tsocket.on(\"data\", (chunk: Buffer) => {\n\t\t\tif (settled) return;\n\t\t\tresponse = Buffer.concat([response, chunk]);\n\t\t\tif (response.byteLength > MAX_FRAME_BYTES) {\n\t\t\t\tfinish(new Error(\"Subagent broker response exceeded its size limit.\"));\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tconst newline = response.indexOf(0x0a);\n\t\t\tif (newline < 0) return;\n\t\t\tconst trailing = response\n\t\t\t\t.subarray(newline + 1)\n\t\t\t\t.toString(\"utf8\")\n\t\t\t\t.trim();\n\t\t\tif (trailing) {\n\t\t\t\tfinish(new Error(\"Subagent broker returned more than one response frame.\"));\n\t\t\t\treturn;\n\t\t\t}\n\t\t\ttry {\n\t\t\t\tconst parsed = JSON.parse(response.subarray(0, newline).toString(\"utf8\")) as unknown;\n\t\t\t\tif (!isRecord(parsed)) throw new Error();\n\t\t\t\tfinish(undefined, parsed);\n\t\t\t} catch {\n\t\t\t\tfinish(new Error(\"Subagent broker returned malformed JSON.\"));\n\t\t\t}\n\t\t});\n\t\tsocket.once(\"error\", (error) => finish(error));\n\t\tsocket.once(\"close\", () => {\n\t\t\tif (!settled) finish(new Error(\"Subagent broker closed without a response.\"));\n\t\t});\n\t});\n}\n\nfunction brokerError(response: Record<string, unknown>): Error {\n\treturn new Error(\n\t\ttypeof response.error === \"string\" ? response.error : \"Subagent broker rejected the request.\",\n\t);\n}\n\nfunction abortError(message: string): Error {\n\tconst error = new Error(message);\n\terror.name = \"AbortError\";\n\treturn error;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n"],
-  "mappings": "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",
+  "sourcesContent": ["import net from \"node:net\";\nimport type { ExtensionFactory } from \"@earendil-works/pi-coding-agent\";\nimport { captureChildBootstrap } from \"./broker-credentials.js\";\nimport { type ChildCommunicationClient, createChildCommunicationExtension } from \"./child-communication-tools.js\";\nimport { MAX_FRAME_BYTES, MAX_IDENTIFIER_LENGTH } from \"./message-broker.js\";\nimport type { BrokerCredentials } from \"./types.js\";\n\nconst CONNECT_TIMEOUT_MS = 2_000;\nconst SEND_RESPONSE_TIMEOUT_MS = 5_000;\n\nconst captured = captureChildBootstrap();\n\nconst childCommunicationBridge: ExtensionFactory = captured\n  ? createChildCommunicationExtension(createBrokerClient(captured.communication))\n  : () => undefined;\n\nexport default childCommunicationBridge;\n\nexport function createBrokerClient(credentials: BrokerCredentials): ChildCommunicationClient {\n  return {\n    async send(params, signal) {\n      const response = await requestBroker(\n        credentials,\n        { type: \"send\", token: credentials.token, ...params },\n        signal,\n        SEND_RESPONSE_TIMEOUT_MS,\n      );\n      if (response.ok !== true) throw brokerError(response);\n      if (\n        typeof response.requestId !== \"string\" ||\n        !response.requestId ||\n        response.requestId.length > MAX_IDENTIFIER_LENGTH ||\n        typeof response.accepted !== \"boolean\" ||\n        typeof response.duplicate !== \"boolean\"\n      ) {\n        throw new Error(\"Subagent broker returned an invalid send acknowledgement.\");\n      }\n      return {\n        requestId: response.requestId,\n        accepted: response.accepted,\n        duplicate: response.duplicate,\n      };\n    },\n    async wait(requestId, timeoutMs, signal) {\n      const response = await requestBroker(\n        credentials,\n        {\n          type: \"wait\",\n          token: credentials.token,\n          requestId,\n          ...(timeoutMs !== undefined ? { timeoutMs } : {}),\n        },\n        signal,\n      );\n      if (response.ok !== true) throw brokerError(response);\n      if (typeof response.response !== \"string\") {\n        throw new Error(\"Subagent broker returned an invalid plain-text response.\");\n      }\n      return response.response;\n    },\n  };\n}\n\nfunction requestBroker(\n  credentials: BrokerCredentials,\n  request: Record<string, unknown>,\n  signal?: AbortSignal,\n  responseTimeoutMs?: number,\n): Promise<Record<string, unknown>> {\n  if (signal?.aborted) return Promise.reject(abortError(\"Subagent broker request was cancelled.\"));\n  return new Promise((resolve, reject) => {\n    const socket = net.createConnection({ host: credentials.host, port: credentials.port });\n    let response = Buffer.alloc(0);\n    let settled = false;\n    let responseTimer: NodeJS.Timeout | undefined;\n    const connectTimer = setTimeout(\n      () => finish(new Error(\"Subagent broker connection timed out.\")),\n      CONNECT_TIMEOUT_MS,\n    );\n    connectTimer.unref();\n    const onAbort = () => finish(abortError(\"Subagent broker request was cancelled.\"));\n    const finish = (error?: Error, value?: Record<string, unknown>) => {\n      if (settled) return;\n      settled = true;\n      clearTimeout(connectTimer);\n      if (responseTimer) clearTimeout(responseTimer);\n      signal?.removeEventListener(\"abort\", onAbort);\n      socket.destroy();\n      if (error) reject(error);\n      else resolve(value ?? {});\n    };\n    signal?.addEventListener(\"abort\", onAbort, { once: true });\n    socket.once(\"connect\", () => {\n      clearTimeout(connectTimer);\n      if (responseTimeoutMs !== undefined) {\n        responseTimer = setTimeout(() => finish(new Error(\"Subagent broker response timed out.\")), responseTimeoutMs);\n        responseTimer.unref();\n      }\n      socket.write(`${JSON.stringify(request)}\\n`);\n    });\n    socket.on(\"data\", (chunk: Buffer) => {\n      if (settled) return;\n      response = Buffer.concat([response, chunk]);\n      if (response.byteLength > MAX_FRAME_BYTES) {\n        finish(new Error(\"Subagent broker response exceeded its size limit.\"));\n        return;\n      }\n      const newline = response.indexOf(0x0a);\n      if (newline < 0) return;\n      const trailing = response\n        .subarray(newline + 1)\n        .toString(\"utf8\")\n        .trim();\n      if (trailing) {\n        finish(new Error(\"Subagent broker returned more than one response frame.\"));\n        return;\n      }\n      try {\n        const parsed = JSON.parse(response.subarray(0, newline).toString(\"utf8\")) as unknown;\n        if (!isRecord(parsed)) throw new Error();\n        finish(undefined, parsed);\n      } catch {\n        finish(new Error(\"Subagent broker returned malformed JSON.\"));\n      }\n    });\n    socket.once(\"error\", (error) => finish(error));\n    socket.once(\"close\", () => {\n      if (!settled) finish(new Error(\"Subagent broker closed without a response.\"));\n    });\n  });\n}\n\nfunction brokerError(response: Record<string, unknown>): Error {\n  return new Error(typeof response.error === \"string\" ? response.error : \"Subagent broker rejected the request.\");\n}\n\nfunction abortError(message: string): Error {\n  const error = new Error(message);\n  error.name = \"AbortError\";\n  return error;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n"],
+  "mappings": "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",
   "names": []
 }

package/dist/child-readiness-probe.ts

@@ -0,0 +1,68 @@
+// @generated by scripts/build-runtime.mjs; do not edit.
+// @ts-nocheck -- generated entries use .ts extensions for Pi's Jiti loader.
+import {
+  toolSourceId
+} from "./chunks/chunk-3FCHXUKZ.ts";
+import {
+  MAX_READINESS_FRAME_BYTES,
+  takeCapturedReadiness
+} from "./chunks/chunk-YMVSJ5GE.ts";
+
+// src/child-readiness-probe.ts
+import * as fs from "node:fs";
+var captured = takeCapturedReadiness();
+var childReadinessProbe = captured ? createChildReadinessProbe(captured) : () => void 0;
+var child_readiness_probe_default = childReadinessProbe;
+function createChildReadinessProbe(readiness, writeFrame = writeReadinessFrame, close = closeDescriptor) {
+  return (pi) => {
+    let settled = false;
+    const publish = (value) => {
+      if (settled) return;
+      settled = true;
+      const frame = `${JSON.stringify(value)}
+`;
+      if (Buffer.byteLength(frame, "utf8") > MAX_READINESS_FRAME_BYTES) {
+        close(readiness.fd);
+        throw new Error("Pi-subagents readiness frame exceeded its size limit.");
+      }
+      try {
+        writeFrame(readiness.fd, frame);
+      } finally {
+        close(readiness.fd);
+      }
+    };
+    pi.on("resources_discover", () => {
+      const active = new Set(pi.getActiveTools());
+      const missing = readiness.expectedTools.filter((tool) => !active.has(tool));
+      if (missing.length > 0) {
+        publish({ ok: false, error: `Unavailable subagent tools: ${missing.join(", ")}.` });
+        return;
+      }
+      const sources = new Map(pi.getAllTools().map((tool) => [tool.name, tool.sourceInfo.path]));
+      publish({
+        ok: true,
+        sources: readiness.expectedTools.map((tool) => {
+          const source = sources.get(tool);
+          return source ? toolSourceId(source) : "";
+        })
+      });
+    });
+    pi.on("session_shutdown", () => {
+      publish({ ok: false, error: "Subagent child shut down before readiness completed." });
+    });
+  };
+}
+function writeReadinessFrame(fd, frame) {
+  fs.writeFileSync(fd, frame, "utf8");
+}
+function closeDescriptor(fd) {
+  try {
+    fs.closeSync(fd);
+  } catch {
+  }
+}
+export {
+  createChildReadinessProbe,
+  child_readiness_probe_default as default
+};
+//# sourceMappingURL=child-readiness-probe.ts.map

package/dist/child-readiness-probe.ts.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/child-readiness-probe.ts"],
+  "sourcesContent": ["import * as fs from \"node:fs\";\nimport type { ExtensionFactory } from \"@earendil-works/pi-coding-agent\";\nimport { toolSourceId } from \"./attachment-utils.js\";\nimport { MAX_READINESS_FRAME_BYTES, takeCapturedReadiness } from \"./broker-credentials.js\";\n\nexport interface ChildReadinessState {\n  fd: number;\n  expectedTools: string[];\n}\n\nconst captured = takeCapturedReadiness();\n\nconst childReadinessProbe: ExtensionFactory = captured ? createChildReadinessProbe(captured) : () => undefined;\n\nexport default childReadinessProbe;\n\nexport function createChildReadinessProbe(\n  readiness: ChildReadinessState,\n  writeFrame: (fd: number, frame: string) => void = writeReadinessFrame,\n  close: (fd: number) => void = closeDescriptor,\n): ExtensionFactory {\n  return (pi) => {\n    let settled = false;\n    const publish = (value: { ok: true; sources: string[] } | { ok: false; error: string }) => {\n      if (settled) return;\n      settled = true;\n      const frame = `${JSON.stringify(value)}\\n`;\n      if (Buffer.byteLength(frame, \"utf8\") > MAX_READINESS_FRAME_BYTES) {\n        close(readiness.fd);\n        throw new Error(\"Pi-subagents readiness frame exceeded its size limit.\");\n      }\n      try {\n        writeFrame(readiness.fd, frame);\n      } finally {\n        close(readiness.fd);\n      }\n    };\n\n    pi.on(\"resources_discover\", () => {\n      const active = new Set(pi.getActiveTools());\n      const missing = readiness.expectedTools.filter((tool) => !active.has(tool));\n      if (missing.length > 0) {\n        publish({ ok: false, error: `Unavailable subagent tools: ${missing.join(\", \")}.` });\n        return;\n      }\n      const sources = new Map(pi.getAllTools().map((tool) => [tool.name, tool.sourceInfo.path]));\n      publish({\n        ok: true,\n        sources: readiness.expectedTools.map((tool) => {\n          const source = sources.get(tool);\n          return source ? toolSourceId(source) : \"\";\n        }),\n      });\n    });\n\n    pi.on(\"session_shutdown\", () => {\n      publish({ ok: false, error: \"Subagent child shut down before readiness completed.\" });\n    });\n  };\n}\n\nfunction writeReadinessFrame(fd: number, frame: string): void {\n  fs.writeFileSync(fd, frame, \"utf8\");\n}\n\nfunction closeDescriptor(fd: number): void {\n  try {\n    fs.closeSync(fd);\n  } catch {\n    // The descriptor may already be closed after a failed write.\n  }\n}\n"],
+  "mappings": ";;;;;;;;;;;AAAA,YAAY,QAAQ;AAUpB,IAAM,WAAW,sBAAsB;AAEvC,IAAM,sBAAwC,WAAW,0BAA0B,QAAQ,IAAI,MAAM;AAErG,IAAO,gCAAQ;AAER,SAAS,0BACd,WACA,aAAkD,qBAClD,QAA8B,iBACZ;AAClB,SAAO,CAAC,OAAO;AACb,QAAI,UAAU;AACd,UAAM,UAAU,CAAC,UAA0E;AACzF,UAAI,QAAS;AACb,gBAAU;AACV,YAAM,QAAQ,GAAG,KAAK,UAAU,KAAK,CAAC;AAAA;AACtC,UAAI,OAAO,WAAW,OAAO,MAAM,IAAI,2BAA2B;AAChE,cAAM,UAAU,EAAE;AAClB,cAAM,IAAI,MAAM,uDAAuD;AAAA,MACzE;AACA,UAAI;AACF,mBAAW,UAAU,IAAI,KAAK;AAAA,MAChC,UAAE;AACA,cAAM,UAAU,EAAE;AAAA,MACpB;AAAA,IACF;AAEA,OAAG,GAAG,sBAAsB,MAAM;AAChC,YAAM,SAAS,IAAI,IAAI,GAAG,eAAe,CAAC;AAC1C,YAAM,UAAU,UAAU,cAAc,OAAO,CAAC,SAAS,CAAC,OAAO,IAAI,IAAI,CAAC;AAC1E,UAAI,QAAQ,SAAS,GAAG;AACtB,gBAAQ,EAAE,IAAI,OAAO,OAAO,+BAA+B,QAAQ,KAAK,IAAI,CAAC,IAAI,CAAC;AAClF;AAAA,MACF;AACA,YAAM,UAAU,IAAI,IAAI,GAAG,YAAY,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,MAAM,KAAK,WAAW,IAAI,CAAC,CAAC;AACzF,cAAQ;AAAA,QACN,IAAI;AAAA,QACJ,SAAS,UAAU,cAAc,IAAI,CAAC,SAAS;AAC7C,gBAAM,SAAS,QAAQ,IAAI,IAAI;AAC/B,iBAAO,SAAS,aAAa,MAAM,IAAI;AAAA,QACzC,CAAC;AAAA,MACH,CAAC;AAAA,IACH,CAAC;AAED,OAAG,GAAG,oBAAoB,MAAM;AAC9B,cAAQ,EAAE,IAAI,OAAO,OAAO,uDAAuD,CAAC;AAAA,IACtF,CAAC;AAAA,EACH;AACF;AAEA,SAAS,oBAAoB,IAAY,OAAqB;AAC5D,EAAG,iBAAc,IAAI,OAAO,MAAM;AACpC;AAEA,SAAS,gBAAgB,IAAkB;AACzC,MAAI;AACF,IAAG,aAAU,EAAE;AAAA,EACjB,QAAQ;AAAA,EAER;AACF;",
+  "names": []
+}

package/dist/chunks/chunk-3FCHXUKZ.ts

@@ -0,0 +1,98 @@
+// @generated by scripts/build-runtime.mjs; do not edit.
+// @ts-nocheck -- generated entries use .ts extensions for Pi's Jiti loader.
+import {
+  sanitizeTerminalText
+} from "./chunk-YMVSJ5GE.ts";
+
+// src/attachment-utils.ts
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { readFile, stat } from "node:fs/promises";
+import * as path from "node:path";
+var ATTACHMENT_IGNORE_FILE_NAMES = [".gitignore", ".ignore", ".fdignore"];
+function throwInvalidAttachmentIgnoreFile() {
+  throw new Error("Subagent attachment ignore files must be regular files.");
+}
+function throwIfAttachmentAborted(signal) {
+  if (!signal?.aborted) return;
+  const error = new Error("Subagent attachment validation was cancelled.");
+  error.name = "AbortError";
+  throw error;
+}
+function isAbortError(error) {
+  return error instanceof Error && error.name === "AbortError";
+}
+function prefixIgnorePattern(line, prefix) {
+  const trimmed = line.trim();
+  if (!trimmed || trimmed.startsWith("#") && !trimmed.startsWith("\\#")) return null;
+  let pattern = line;
+  let negated = false;
+  if (pattern.startsWith("!")) {
+    negated = true;
+    pattern = pattern.slice(1);
+  } else if (pattern.startsWith("\\!")) {
+    pattern = pattern.slice(1);
+  }
+  if (pattern.startsWith("/")) pattern = pattern.slice(1);
+  const prefixed = prefix ? `${prefix}${pattern}` : pattern;
+  return negated ? `!${prefixed}` : prefixed;
+}
+async function addAttachmentIgnoreRules(ignoreMatcher, directory, rootDirectory, signal, accountForFile) {
+  const relativeDirectory = path.relative(rootDirectory, directory);
+  const prefix = relativeDirectory ? `${toPosixPath(relativeDirectory)}/` : "";
+  for (const filename of ATTACHMENT_IGNORE_FILE_NAMES) {
+    throwIfAttachmentAborted(signal);
+    const ignorePath = path.join(directory, filename);
+    let ignoreStats;
+    try {
+      ignoreStats = await stat(ignorePath);
+    } catch (error) {
+      if (isAbortError(error)) throw error;
+      throwIfAttachmentAborted(signal);
+      continue;
+    }
+    if (!ignoreStats.isFile()) throwInvalidAttachmentIgnoreFile();
+    accountForFile(ignorePath, ignoreStats.size);
+    try {
+      const content = await readFile(ignorePath, { encoding: "utf8", signal });
+      throwIfAttachmentAborted(signal);
+      const patterns = content.split(/\r?\n/u).map((line) => prefixIgnorePattern(line, prefix)).filter((line) => line !== null);
+      if (patterns.length > 0) ignoreMatcher.add(patterns);
+    } catch (error) {
+      if (isAbortError(error)) throw error;
+      throwIfAttachmentAborted(signal);
+    }
+  }
+}
+function toPosixPath(value) {
+  return value.split(path.sep).join("/");
+}
+function toolSourceId(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+function realpath(value, label) {
+  try {
+    return realpathSync(value);
+  } catch {
+    throw new Error(`${label} path does not exist: ${sanitizeTerminalText(value).slice(0, 512)}`);
+  }
+}
+function isWithin(root, candidate) {
+  const relative2 = path.relative(root, candidate);
+  return relative2 === "" || !relative2.startsWith(`..${path.sep}`) && relative2 !== ".." && !path.isAbsolute(relative2);
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export {
+  throwIfAttachmentAborted,
+  isAbortError,
+  addAttachmentIgnoreRules,
+  toPosixPath,
+  toolSourceId,
+  realpath,
+  isWithin,
+  isRecord
+};
+//# sourceMappingURL=chunk-3FCHXUKZ.ts.map