@narumitw/pi-subagents 3.0.2 → 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.
@@ -68,8 +70,8 @@ Use messaging only when needed:
 
 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
 
@@ -77,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. |
@@ -107,9 +109,9 @@ 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, context, credentials, environment variables, requests, responses, or secrets.
+`subagent_inspect` never returns complete task text, child output, prompts, selected tools, attachment paths or totals, 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
 
@@ -118,50 +120,50 @@ For reusable delegation policy, you can create your own project skill under `.pi
 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.
 
-The optional `tools` list limits what the child can do:
+`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 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.
 
-- 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 runtime always adds `subagent_send` and child `subagent_wait` and removes duplicate names.
+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 `edit` or `write` lets the child modify files.
-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`.
-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.
+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.
 
-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.
-
-Each child runs in Pi RPC mode so the parent can inject a main-originated request through `steer` after the initial prompt is accepted.
-Each child broker call uses one request-scoped connection, while a response wait uses an abortable long poll.
-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.
+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.
+
+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.
+
+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.
+
+See [Messaging and lifecycle](./docs/messaging.md) for delivery, retry, retention, and shutdown details.
 
 ## 🔀 Migrating from 2.x
 
@@ -190,9 +192,10 @@ 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.
@@ -201,14 +204,20 @@ A child request or response is visible main-agent model context, but its envelop
 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.
 
+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.
+- 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.
@@ -222,7 +231,7 @@ packages/pi-subagents/
 ├── src/                               # Authoritative implementation and helpers
 │   ├── index.ts                       # Thin Pi entrypoint
 │   └── subagents.ts                   # Job, broker, and child lifecycle
-├── dist/                              # Generated Jiti runtime and child bridge
+├── 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

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-7JQOB375.ts";
+  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 {

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 { 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 = captureBrokerCredentials();\n\nconst childCommunicationBridge: ExtensionFactory = captured\n  ? createChildCommunicationExtension(createBrokerClient(captured))\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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",
+  "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

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/attachment-utils.ts"],
+  "sourcesContent": ["import { createHash } from \"node:crypto\";\nimport { realpathSync } from \"node:fs\";\nimport { readFile, stat } from \"node:fs/promises\";\nimport * as path from \"node:path\";\nimport type ignore from \"ignore\";\nimport { sanitizeTerminalText } from \"./message-broker.js\";\n\nconst ATTACHMENT_IGNORE_FILE_NAMES = [\".gitignore\", \".ignore\", \".fdignore\"];\n\nexport type IgnoreMatcher = ReturnType<typeof ignore>;\n\nfunction throwInvalidAttachmentIgnoreFile(): never {\n  throw new Error(\"Subagent attachment ignore files must be regular files.\");\n}\n\nexport function throwIfAttachmentAborted(signal: AbortSignal | undefined): void {\n  if (!signal?.aborted) return;\n  const error = new Error(\"Subagent attachment validation was cancelled.\");\n  error.name = \"AbortError\";\n  throw error;\n}\n\nexport function isAbortError(error: unknown): boolean {\n  return error instanceof Error && error.name === \"AbortError\";\n}\n\nfunction prefixIgnorePattern(line: string, prefix: string): string | null {\n  const trimmed = line.trim();\n  if (!trimmed || (trimmed.startsWith(\"#\") && !trimmed.startsWith(\"\\\\#\"))) return null;\n  let pattern = line;\n  let negated = false;\n  if (pattern.startsWith(\"!\")) {\n    negated = true;\n    pattern = pattern.slice(1);\n  } else if (pattern.startsWith(\"\\\\!\")) {\n    pattern = pattern.slice(1);\n  }\n  if (pattern.startsWith(\"/\")) pattern = pattern.slice(1);\n  const prefixed = prefix ? `${prefix}${pattern}` : pattern;\n  return negated ? `!${prefixed}` : prefixed;\n}\n\nexport async function addAttachmentIgnoreRules(\n  ignoreMatcher: IgnoreMatcher,\n  directory: string,\n  rootDirectory: string,\n  signal: AbortSignal | undefined,\n  accountForFile: (ignorePath: string, bytes: number) => void,\n): Promise<void> {\n  const relativeDirectory = path.relative(rootDirectory, directory);\n  const prefix = relativeDirectory ? `${toPosixPath(relativeDirectory)}/` : \"\";\n  for (const filename of ATTACHMENT_IGNORE_FILE_NAMES) {\n    throwIfAttachmentAborted(signal);\n    const ignorePath = path.join(directory, filename);\n    let ignoreStats: Awaited<ReturnType<typeof stat>>;\n    try {\n      ignoreStats = await stat(ignorePath);\n    } catch (error) {\n      if (isAbortError(error)) throw error;\n      throwIfAttachmentAborted(signal);\n      continue;\n    }\n    if (!ignoreStats.isFile()) throwInvalidAttachmentIgnoreFile();\n    accountForFile(ignorePath, ignoreStats.size);\n    try {\n      const content = await readFile(ignorePath, { encoding: \"utf8\", signal });\n      throwIfAttachmentAborted(signal);\n      const patterns = content\n        .split(/\\r?\\n/u)\n        .map((line) => prefixIgnorePattern(line, prefix))\n        .filter((line): line is string => line !== null);\n      if (patterns.length > 0) ignoreMatcher.add(patterns);\n    } catch (error) {\n      if (isAbortError(error)) throw error;\n      throwIfAttachmentAborted(signal);\n      // Pi ignores unreadable ignore files.\n    }\n  }\n}\n\nexport function toPosixPath(value: string): string {\n  return value.split(path.sep).join(\"/\");\n}\n\nexport function toolSourceId(value: string): string {\n  return createHash(\"sha256\").update(value).digest(\"hex\");\n}\n\nexport function realpath(value: string, label: string): string {\n  try {\n    return realpathSync(value);\n  } catch {\n    throw new Error(`${label} path does not exist: ${sanitizeTerminalText(value).slice(0, 512)}`);\n  }\n}\n\nexport function isWithin(root: string, candidate: string): boolean {\n  const relative = path.relative(root, candidate);\n  return relative === \"\" || (!relative.startsWith(`..${path.sep}`) && relative !== \"..\" && !path.isAbsolute(relative));\n}\n\nexport function isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n"],
+  "mappings": ";;;;;;;AAAA,SAAS,kBAAkB;AAC3B,SAAS,oBAAoB;AAC7B,SAAS,UAAU,YAAY;AAC/B,YAAY,UAAU;AAItB,IAAM,+BAA+B,CAAC,cAAc,WAAW,WAAW;AAI1E,SAAS,mCAA0C;AACjD,QAAM,IAAI,MAAM,yDAAyD;AAC3E;AAEO,SAAS,yBAAyB,QAAuC;AAC9E,MAAI,CAAC,QAAQ,QAAS;AACtB,QAAM,QAAQ,IAAI,MAAM,+CAA+C;AACvE,QAAM,OAAO;AACb,QAAM;AACR;AAEO,SAAS,aAAa,OAAyB;AACpD,SAAO,iBAAiB,SAAS,MAAM,SAAS;AAClD;AAEA,SAAS,oBAAoB,MAAc,QAA+B;AACxE,QAAM,UAAU,KAAK,KAAK;AAC1B,MAAI,CAAC,WAAY,QAAQ,WAAW,GAAG,KAAK,CAAC,QAAQ,WAAW,KAAK,EAAI,QAAO;AAChF,MAAI,UAAU;AACd,MAAI,UAAU;AACd,MAAI,QAAQ,WAAW,GAAG,GAAG;AAC3B,cAAU;AACV,cAAU,QAAQ,MAAM,CAAC;AAAA,EAC3B,WAAW,QAAQ,WAAW,KAAK,GAAG;AACpC,cAAU,QAAQ,MAAM,CAAC;AAAA,EAC3B;AACA,MAAI,QAAQ,WAAW,GAAG,EAAG,WAAU,QAAQ,MAAM,CAAC;AACtD,QAAM,WAAW,SAAS,GAAG,MAAM,GAAG,OAAO,KAAK;AAClD,SAAO,UAAU,IAAI,QAAQ,KAAK;AACpC;AAEA,eAAsB,yBACpB,eACA,WACA,eACA,QACA,gBACe;AACf,QAAM,oBAAyB,cAAS,eAAe,SAAS;AAChE,QAAM,SAAS,oBAAoB,GAAG,YAAY,iBAAiB,CAAC,MAAM;AAC1E,aAAW,YAAY,8BAA8B;AACnD,6BAAyB,MAAM;AAC/B,UAAM,aAAkB,UAAK,WAAW,QAAQ;AAChD,QAAI;AACJ,QAAI;AACF,oBAAc,MAAM,KAAK,UAAU;AAAA,IACrC,SAAS,OAAO;AACd,UAAI,aAAa,KAAK,EAAG,OAAM;AAC/B,+BAAyB,MAAM;AAC/B;AAAA,IACF;AACA,QAAI,CAAC,YAAY,OAAO,EAAG,kCAAiC;AAC5D,mBAAe,YAAY,YAAY,IAAI;AAC3C,QAAI;AACF,YAAM,UAAU,MAAM,SAAS,YAAY,EAAE,UAAU,QAAQ,OAAO,CAAC;AACvE,+BAAyB,MAAM;AAC/B,YAAM,WAAW,QACd,MAAM,QAAQ,EACd,IAAI,CAAC,SAAS,oBAAoB,MAAM,MAAM,CAAC,EAC/C,OAAO,CAAC,SAAyB,SAAS,IAAI;AACjD,UAAI,SAAS,SAAS,EAAG,eAAc,IAAI,QAAQ;AAAA,IACrD,SAAS,OAAO;AACd,UAAI,aAAa,KAAK,EAAG,OAAM;AAC/B,+BAAyB,MAAM;AAAA,IAEjC;AAAA,EACF;AACF;AAEO,SAAS,YAAY,OAAuB;AACjD,SAAO,MAAM,MAAW,QAAG,EAAE,KAAK,GAAG;AACvC;AAEO,SAAS,aAAa,OAAuB;AAClD,SAAO,WAAW,QAAQ,EAAE,OAAO,KAAK,EAAE,OAAO,KAAK;AACxD;AAEO,SAAS,SAAS,OAAe,OAAuB;AAC7D,MAAI;AACF,WAAO,aAAa,KAAK;AAAA,EAC3B,QAAQ;AACN,UAAM,IAAI,MAAM,GAAG,KAAK,yBAAyB,qBAAqB,KAAK,EAAE,MAAM,GAAG,GAAG,CAAC,EAAE;AAAA,EAC9F;AACF;AAEO,SAAS,SAAS,MAAc,WAA4B;AACjE,QAAMA,YAAgB,cAAS,MAAM,SAAS;AAC9C,SAAOA,cAAa,MAAO,CAACA,UAAS,WAAW,KAAU,QAAG,EAAE,KAAKA,cAAa,QAAQ,CAAM,gBAAWA,SAAQ;AACpH;AAEO,SAAS,SAAS,OAAkD;AACzE,SAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;",
+  "names": ["relative"]
+}