@narumitw/pi-subagents 2.1.3 → 3.0.0

package/dist/chunks/usage-recording-store-CW3EH2SZ.ts

@@ -1,164 +0,0 @@
-// @generated by scripts/build-runtime.mjs; do not edit.
-// @ts-nocheck -- generated JavaScript uses a .ts extension for Pi's Jiti loader.
-
-// src/usage-recording-store.ts
-import { randomUUID } from "node:crypto";
-import { chmod, lstat, mkdir, readdir, rm, writeFile } from "node:fs/promises";
-import path from "node:path";
-var WRITER_PATTERN = /^runtime-[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.jsonl$/u;
-var MAX_EVENT_BYTES = 8 * 1024;
-var WRITE_TIMEOUT_MS = 2e3;
-var UsageEventStore = class {
-  path;
-  writerPath;
-  mutationTail = Promise.resolve();
-  lifecycle = new AbortController();
-  closed = false;
-  constructor(rootPath, options = {}) {
-    this.path = rootPath;
-    this.createId = options.createId ?? randomUUID;
-    this.now = options.now ?? Date.now;
-    this.writerPath = path.join(rootPath, `runtime-${validId(this.createId())}.jsonl`);
-  }
-  createId;
-  now;
-  append(event) {
-    if (this.closed) return Promise.reject(new Error("Usage recording storage is closed."));
-    const frame = encodeEvent(event);
-    return this.enqueue(
-      () => withTimeout(
-        (signal) => this.appendFrame(frame, signal),
-        this.lifecycle.signal,
-        WRITE_TIMEOUT_MS,
-        "Usage recording write timed out"
-      )
-    );
-  }
-  prune(retentionDays) {
-    if (this.closed) return Promise.reject(new Error("Usage recording storage is closed."));
-    return this.enqueue(
-      () => withTimeout(
-        async (signal) => {
-          await ensurePrivateDirectory(this.path);
-          signal.throwIfAborted();
-          const cutoff = this.now() - retentionDays * 24 * 60 * 60 * 1e3;
-          for (const entry of await readdir(this.path, { withFileTypes: true })) {
-            signal.throwIfAborted();
-            if (!entry.isFile() || !WRITER_PATTERN.test(entry.name)) continue;
-            const candidate = path.join(this.path, entry.name);
-            if (candidate === this.writerPath) continue;
-            let metadata;
-            try {
-              metadata = await lstat(candidate);
-            } catch (error) {
-              if (isNodeError(error) && error.code === "ENOENT") continue;
-              throw error;
-            }
-            if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.mtimeMs >= cutoff) {
-              continue;
-            }
-            await rm(candidate, { force: true });
-          }
-        },
-        this.lifecycle.signal,
-        WRITE_TIMEOUT_MS,
-        "Usage recording retention cleanup timed out"
-      )
-    );
-  }
-  async close() {
-    if (this.closed) return;
-    this.closed = true;
-    this.lifecycle.abort(new DOMException("Usage recording storage closed", "AbortError"));
-    await this.mutationTail;
-  }
-  enqueue(operation) {
-    const result = this.mutationTail.then(operation);
-    this.mutationTail = result.catch(() => void 0);
-    return result;
-  }
-  async appendFrame(frame, signal) {
-    await ensurePrivateDirectory(this.path);
-    signal.throwIfAborted();
-    await assertOptionalPrivateRegularFile(this.writerPath);
-    signal.throwIfAborted();
-    await writeFile(this.writerPath, frame, {
-      encoding: "utf8",
-      flag: "a",
-      mode: 384,
-      signal
-    });
-    if (process.platform !== "win32") await chmod(this.writerPath, 384);
-  }
-};
-function encodeEvent(event) {
-  const frame = `${JSON.stringify(event)}
-`;
-  if (Buffer.byteLength(frame) > MAX_EVENT_BYTES) {
-    throw new Error("Usage recording event exceeds the storage bound.");
-  }
-  return frame;
-}
-async function ensurePrivateDirectory(directoryPath) {
-  try {
-    const metadata = await lstat(directoryPath);
-    if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
-      throw new Error("Usage recording storage must be a regular directory, not a link.");
-    }
-  } catch (error) {
-    if (!isNodeError(error) || error.code !== "ENOENT") throw error;
-    await mkdir(directoryPath, { recursive: true, mode: 448 });
-    const metadata = await lstat(directoryPath);
-    if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
-      throw new Error("Usage recording storage must be a regular directory, not a link.");
-    }
-  }
-  if (process.platform !== "win32") await chmod(directoryPath, 448);
-}
-async function assertOptionalPrivateRegularFile(filePath) {
-  try {
-    const metadata = await lstat(filePath);
-    if (!metadata.isFile() || metadata.isSymbolicLink()) {
-      throw new Error("Usage recording writers must be regular files, not links.");
-    }
-    if (process.platform !== "win32") await chmod(filePath, 384);
-  } catch (error) {
-    if (isNodeError(error) && error.code === "ENOENT") return;
-    throw error;
-  }
-}
-async function withTimeout(operation, lifecycleSignal, timeoutMs, message) {
-  lifecycleSignal.throwIfAborted();
-  const controller = new AbortController();
-  const abortLifecycle = () => controller.abort(
-    lifecycleSignal.reason ?? new DOMException("Usage recording storage closed", "AbortError")
-  );
-  lifecycleSignal.addEventListener("abort", abortLifecycle, { once: true });
-  const timer = setTimeout(
-    () => controller.abort(new DOMException(message, "TimeoutError")),
-    timeoutMs
-  );
-  try {
-    return await operation(controller.signal);
-  } catch (error) {
-    if (controller.signal.aborted) throw controller.signal.reason;
-    throw error;
-  } finally {
-    clearTimeout(timer);
-    lifecycleSignal.removeEventListener("abort", abortLifecycle);
-  }
-}
-function validId(value) {
-  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(value)) {
-    throw new Error("Usage recording storage received an invalid writer identity.");
-  }
-  return value;
-}
-function isNodeError(error) {
-  return error instanceof Error && "code" in error;
-}
-export {
-  UsageEventStore,
-  encodeEvent
-};
-//# sourceMappingURL=usage-recording-store-CW3EH2SZ.ts.map

package/dist/chunks/usage-recording-store-CW3EH2SZ.ts.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../src/usage-recording-store.ts"],
-  "sourcesContent": ["import { randomUUID } from \"node:crypto\";\nimport { chmod, lstat, mkdir, readdir, rm, writeFile } from \"node:fs/promises\";\nimport path from \"node:path\";\n\nconst WRITER_PATTERN =\n\t/^runtime-[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\.jsonl$/u;\nconst MAX_EVENT_BYTES = 8 * 1024;\nconst WRITE_TIMEOUT_MS = 2_000;\n\nexport interface UsageEventStorePort {\n\treadonly path: string;\n\tappend(event: unknown): Promise<void>;\n\tprune(retentionDays: number): Promise<void>;\n\tclose(): Promise<void>;\n}\n\nexport class UsageEventStore implements UsageEventStorePort {\n\treadonly path: string;\n\tprivate readonly writerPath: string;\n\tprivate mutationTail: Promise<void> = Promise.resolve();\n\tprivate readonly lifecycle = new AbortController();\n\tprivate closed = false;\n\n\tconstructor(rootPath: string, options: { createId?: () => string; now?: () => number } = {}) {\n\t\tthis.path = rootPath;\n\t\tthis.createId = options.createId ?? randomUUID;\n\t\tthis.now = options.now ?? Date.now;\n\t\tthis.writerPath = path.join(rootPath, `runtime-${validId(this.createId())}.jsonl`);\n\t}\n\n\tprivate readonly createId: () => string;\n\tprivate readonly now: () => number;\n\n\tappend(event: unknown): Promise<void> {\n\t\tif (this.closed) return Promise.reject(new Error(\"Usage recording storage is closed.\"));\n\t\tconst frame = encodeEvent(event);\n\t\treturn this.enqueue(() =>\n\t\t\twithTimeout(\n\t\t\t\t(signal) => this.appendFrame(frame, signal),\n\t\t\t\tthis.lifecycle.signal,\n\t\t\t\tWRITE_TIMEOUT_MS,\n\t\t\t\t\"Usage recording write timed out\",\n\t\t\t),\n\t\t);\n\t}\n\n\tprune(retentionDays: number): Promise<void> {\n\t\tif (this.closed) return Promise.reject(new Error(\"Usage recording storage is closed.\"));\n\t\treturn this.enqueue(() =>\n\t\t\twithTimeout(\n\t\t\t\tasync (signal) => {\n\t\t\t\t\tawait ensurePrivateDirectory(this.path);\n\t\t\t\t\tsignal.throwIfAborted();\n\t\t\t\t\tconst cutoff = this.now() - retentionDays * 24 * 60 * 60 * 1000;\n\t\t\t\t\tfor (const entry of await readdir(this.path, { withFileTypes: true })) {\n\t\t\t\t\t\tsignal.throwIfAborted();\n\t\t\t\t\t\tif (!entry.isFile() || !WRITER_PATTERN.test(entry.name)) continue;\n\t\t\t\t\t\tconst candidate = path.join(this.path, entry.name);\n\t\t\t\t\t\tif (candidate === this.writerPath) continue;\n\t\t\t\t\t\tlet metadata: Awaited<ReturnType<typeof lstat>>;\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tmetadata = await lstat(candidate);\n\t\t\t\t\t\t} catch (error) {\n\t\t\t\t\t\t\tif (isNodeError(error) && error.code === \"ENOENT\") continue;\n\t\t\t\t\t\t\tthrow error;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tif (!metadata.isFile() || metadata.isSymbolicLink() || metadata.mtimeMs >= cutoff) {\n\t\t\t\t\t\t\tcontinue;\n\t\t\t\t\t\t}\n\t\t\t\t\t\tawait rm(candidate, { force: true });\n\t\t\t\t\t}\n\t\t\t\t},\n\t\t\t\tthis.lifecycle.signal,\n\t\t\t\tWRITE_TIMEOUT_MS,\n\t\t\t\t\"Usage recording retention cleanup timed out\",\n\t\t\t),\n\t\t);\n\t}\n\n\tasync close(): Promise<void> {\n\t\tif (this.closed) return;\n\t\tthis.closed = true;\n\t\tthis.lifecycle.abort(new DOMException(\"Usage recording storage closed\", \"AbortError\"));\n\t\tawait this.mutationTail;\n\t}\n\n\tprivate enqueue(operation: () => Promise<void>): Promise<void> {\n\t\tconst result = this.mutationTail.then(operation);\n\t\tthis.mutationTail = result.catch(() => undefined);\n\t\treturn result;\n\t}\n\n\tprivate async appendFrame(frame: string, signal: AbortSignal): Promise<void> {\n\t\tawait ensurePrivateDirectory(this.path);\n\t\tsignal.throwIfAborted();\n\t\tawait assertOptionalPrivateRegularFile(this.writerPath);\n\t\tsignal.throwIfAborted();\n\t\tawait writeFile(this.writerPath, frame, {\n\t\t\tencoding: \"utf8\",\n\t\t\tflag: \"a\",\n\t\t\tmode: 0o600,\n\t\t\tsignal,\n\t\t});\n\t\tif (process.platform !== \"win32\") await chmod(this.writerPath, 0o600);\n\t}\n}\n\nexport function encodeEvent(event: unknown): string {\n\tconst frame = `${JSON.stringify(event)}\\n`;\n\tif (Buffer.byteLength(frame) > MAX_EVENT_BYTES) {\n\t\tthrow new Error(\"Usage recording event exceeds the storage bound.\");\n\t}\n\treturn frame;\n}\n\nasync function ensurePrivateDirectory(directoryPath: string): Promise<void> {\n\ttry {\n\t\tconst metadata = await lstat(directoryPath);\n\t\tif (!metadata.isDirectory() || metadata.isSymbolicLink()) {\n\t\t\tthrow new Error(\"Usage recording storage must be a regular directory, not a link.\");\n\t\t}\n\t} catch (error) {\n\t\tif (!isNodeError(error) || error.code !== \"ENOENT\") throw error;\n\t\tawait mkdir(directoryPath, { recursive: true, mode: 0o700 });\n\t\tconst metadata = await lstat(directoryPath);\n\t\tif (!metadata.isDirectory() || metadata.isSymbolicLink()) {\n\t\t\tthrow new Error(\"Usage recording storage must be a regular directory, not a link.\");\n\t\t}\n\t}\n\tif (process.platform !== \"win32\") await chmod(directoryPath, 0o700);\n}\n\nasync function assertOptionalPrivateRegularFile(filePath: string): Promise<void> {\n\ttry {\n\t\tconst metadata = await lstat(filePath);\n\t\tif (!metadata.isFile() || metadata.isSymbolicLink()) {\n\t\t\tthrow new Error(\"Usage recording writers must be regular files, not links.\");\n\t\t}\n\t\tif (process.platform !== \"win32\") await chmod(filePath, 0o600);\n\t} catch (error) {\n\t\tif (isNodeError(error) && error.code === \"ENOENT\") return;\n\t\tthrow error;\n\t}\n}\n\nasync function withTimeout<T>(\n\toperation: (signal: AbortSignal) => Promise<T>,\n\tlifecycleSignal: AbortSignal,\n\ttimeoutMs: number,\n\tmessage: string,\n): Promise<T> {\n\tlifecycleSignal.throwIfAborted();\n\tconst controller = new AbortController();\n\tconst abortLifecycle = () =>\n\t\tcontroller.abort(\n\t\t\tlifecycleSignal.reason ?? new DOMException(\"Usage recording storage closed\", \"AbortError\"),\n\t\t);\n\tlifecycleSignal.addEventListener(\"abort\", abortLifecycle, { once: true });\n\tconst timer = setTimeout(\n\t\t() => controller.abort(new DOMException(message, \"TimeoutError\")),\n\t\ttimeoutMs,\n\t);\n\ttry {\n\t\treturn await operation(controller.signal);\n\t} catch (error) {\n\t\tif (controller.signal.aborted) throw controller.signal.reason;\n\t\tthrow error;\n\t} finally {\n\t\tclearTimeout(timer);\n\t\tlifecycleSignal.removeEventListener(\"abort\", abortLifecycle);\n\t}\n}\n\nfunction validId(value: string): string {\n\tif (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(value)) {\n\t\tthrow new Error(\"Usage recording storage received an invalid writer identity.\");\n\t}\n\treturn value;\n}\n\nfunction isNodeError(error: unknown): error is NodeJS.ErrnoException {\n\treturn error instanceof Error && \"code\" in error;\n}\n"],
-  "mappings": "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",
-  "names": []
-}

package/dist/chunks/workspace-WDKLN72J.ts

@@ -1,11 +0,0 @@
-// @generated by scripts/build-runtime.mjs; do not edit.
-// @ts-nocheck -- generated JavaScript uses a .ts extension for Pi's Jiti loader.
-import {
-  WorkspaceManager,
-  assertWorkspaceIsolationReady
-} from "./chunk-6KJ34M6S.ts";
-export {
-  WorkspaceManager,
-  assertWorkspaceIsolationReady
-};
-//# sourceMappingURL=workspace-WDKLN72J.ts.map

package/dist/chunks/workspace-WDKLN72J.ts.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": [],
-  "sourcesContent": [],
-  "mappings": "",
-  "names": []
-}

package/docs/async-runtime-protocol.md

@@ -1,84 +0,0 @@
-# Async runtime protocol
-
-This document defines `pi-subagents:completion-requirement:v1` and the current runtime boundary for final-answer-dependent detached work.
-
-## Requirement identity
-
-A caller marks one `subagent_spawn` or `subagent_send` turn with `completionRequirement: "required"`.
-The runtime binds that requirement to the accepted `agentId`, executor-owned `runId`, and monotonically increasing turn generation.
-Agent names and task paths are display and addressing aids and never replace exact run identity.
-Omitting the field or using `background` preserves prior behavior and does not create a final-answer dependency.
-
-## State ownership
-
-`AgentRegistry` owns requirement transitions with the child turn and persisted completion outbox.
-Tool-result `details.agent.completionRequirements` provides fork-sensitive branch evidence.
-Session restoration retains exact requirements found on the active branch and treats sessions without visible subagent state as a possible compacted continuation.
-The successful lifecycle tool result and delivered completion message are the ordinary model-visible requirement handoff.
-When a resume changes a pending run to cancelled and interrupted while its stale handoff remains in model context, `before_agent_start` appends one hidden versioned transition after that handoff.
-This append-only transition also applies when leading summaries retain the stale handoff, prevents duplicate publication on later turns, and participates in fork-sensitive branch reconstruction.
-If leading compaction or branch summaries remove the handoff, the `context` hook restores one canonical hidden `pi-subagent-required-completions` fallback immediately after the summaries.
-A branch-local custom session entry records the exact restored boundary so reload and tree navigation reconstruct the correct historical fallback.
-The fallback remains at that fixed boundary for the leading-summary epoch, while a later completion or cancellation transition supersedes it at the conversation tail.
-`CompletionDeliveryBroker` owns exact completion visibility acknowledgement and asks the registry to mark the corresponding requirement visible.
-No timer, waiter, or UI object owns requirement truth.
-
-## States
-
-A newly accepted exact run enters `pending`.
-A durably persisted terminal completion moves the exact run to `available` and records its completion ID and terminal child state.
-Observation of that exact completion ID in the intended parent context moves the run to `visible`.
-Interruption, close, restore of a non-running owner, or shutdown moves an unfinished requirement to `cancelled` with an explicit terminal state.
-Duplicate completion delivery and acknowledgement are idempotent.
-A follow-up receives a new run ID and generation and creates a requirement only when that follow-up explicitly requests one.
-The runtime bounds retained requirement records per agent and rejects a sixty-fifth unresolved required run before acceptance so every unresolved exact identity fits in the canonical parent context.
-
-## Parent behavior
-
-Pending and available requirements remain final-answer dependencies.
-A newly established canonical fallback omits requirements already visible at that boundary.
-A fallback retained from an earlier request remains historical prefix context after visibility changes, and the later completion message supplies the superseding state.
-Cancelled requirements are terminal and must be reported rather than silently treated as successful evidence.
-A failed, partial, interrupted, stale, or cancelled child never satisfies mutating acceptance or independent-verification requirements merely because its turn settled.
-
-## Prompt-cache boundary
-
-Provider-visible subagent tool definitions and prompt metadata remain stable within one configured tool-surface epoch.
-A versioned hidden session-guidance message carries the bounded agent catalog, completion delivery, capacity, cwd policy, and consultation resource policy without placing mutable values in leading tool metadata.
-The initial guidance contract is persisted once before the first agent turn when no equivalent retained contract exists.
-A successfully applied live policy change appends a superseding guidance contract without triggering a model turn.
-Compaction restores missing guidance and required-completion fallbacks in deterministic order after leading summaries.
-These rules preserve normalized cache-eligible prefixes across ordinary turns but do not guarantee a provider-reported cache hit.
-
-## Budget termination
-
-Omitted limits use runtime or agent policy and are recorded as runtime-sourced telemetry.
-Explicit timeout, idle, turn, and tool-call limits remain compatible and are recorded as explicit sources.
-A limit stop with non-empty successful bounded finalization becomes a typed `partial` outcome with the exact termination reason.
-Empty finalization, failed finalization, malformed required structured output, and transport failures remain failed or contract-invalid.
-Partial evidence is available to the parent but is not successful verification or mutating acceptance.
-
-## Pi core boundary
-
-The inspected supported Pi runtime emits provider `message_update` events before the TUI, RPC, JSON, and SDK surfaces display them.
-An extension `message_end` handler can replace the finalized same-role message but cannot retract previously displayed deltas.
-Steering is queued after the extension `input` event, direct RPC steering bypasses that event, and tool abort signals do not observe every accepted steer.
-Therefore an extension cannot provide a hard pre-display final-answer barrier or a reliably steer-interruptible join across all supported modes.
-`subagent_await` remains the bounded non-polling compatibility join and accurately states that queued steering is blocked until the tool settles.
-
-A future core implementation would need replay-safe post-enqueue input activity, exact session-owned blocker handles, pre-display buffering or suppression, bounded timeout, and abort, replacement, reload, shutdown, and headless-mode semantics.
-This repository does not modify or publish Pi core packages for this work.
-
-## Codex reference
-
-Codex `wait_agent` uses replay-safe pending activity plus an event-driven watch receiver for mailbox and steering activity.
-Codex completion context uses a typed `FINAL_ANSWER` envelope with explicit task, sender, and payload fields.
-Codex rollout budgets use shared runtime-owned accounting and acknowledge reminders only after context insertion.
-These patterns inform waiting, completion identity, and budget ownership, but Codex also does not provide an absolute pre-display final-answer barrier.
-
-## Compatibility fallback
-
-Older persisted agents without requirement metadata behave as background work.
-Current Pi versions continue using bounded persisted at-least-once completion delivery and optional idle-root auto-resume.
-The package must not claim that prompt guidance, context injection, automatic delivery, or finalized-message replacement is a hard barrier.
-The deprecated synchronous `subagent` tool remains available for unmatched chain, fan-in, panel, workflow, and compatibility callers.

package/docs/implementation-notes/pi-subagents-capability-matrix.md

@@ -1,62 +0,0 @@
-# pi-subagents capability matrix
-
-This matrix records the maintained capability boundaries of `@narumitw/pi-subagents`.
-The package README owns public schemas and usage.
-Source and focused tests are the executable authority.
-
-| Capability | Status and boundary | Evidence |
-| --- | --- | --- |
-| Blocking orchestration | Deprecated `subagent` remains a compatibility tool for single, parallel, chain, fan-in, panel, and explicit dependency workflows; the complete request is preflighted before launch and its schema and execution contract remain supported | `src/execution.ts`, `src/panel-execution.ts`, blocking execution and workflow tests |
-| Detached addressable agents | `subagent_spawn` returns an opaque id and canonical task path without waiting for completion | `src/stateful-registration.ts`, registry and stateful registration tests |
-| Follow-up and retained lifecycle | `subagent_send` starts follow-up work; `subagent_await` blocks for one current turn without interrupting on wait timeout or cancellation; `subagent_manage` supports only interrupt and close; `subagent_mailbox` owns queue-only send and acknowledged read | `src/stateful-tool-params.ts`, registry and lifecycle tests |
-| Metadata-only inspection | `subagent_inspect` is registered in every workflow and never launches children, changes lifecycle state, or reads or acknowledges mailbox content | `src/inspect.ts`, `test/inspect.test.ts` |
-| Synchronous read-only consultation | `subagent_consult` runs one ephemeral child with extensions disabled and only the effective subset of `read`, `grep`, `find`, and `ls` | `src/consult.ts`, `src/consult-policy.ts`, `test/consult.test.ts` |
-| Workflow-dependent tool surface | `all` registers eight tools including supported `subagent_await` and `subagent_consult` plus deprecated `subagent`; `async-only` registers detached lifecycle plus inspection; `blocking-only` registers deprecated `subagent` plus supported consultation and inspection; `disabled` registers inspection only | `src/subagents-extension.ts`, settings UI and registration tests |
-| Transport selection | Stateful execution supports `subprocess`, `in-process`, `rpc`, and `auto`; subprocess remains the compatibility default and selection never falls back after acceptance | `src/create-stateful-transport.ts`, transport tests |
-| Automatic transport | Read-only built-in tools select in-process, write-capable built-ins select RPC, and extension or custom tools select fresh subprocess execution | `src/auto-transport.ts`, automatic transport tests |
-| In-process SDK boundary | In-process children use public session-service and model-resolution APIs, disable child extensions, and reject unsupported tools without widening or fallback | `src/in-process-transport.ts`, in-process transport tests |
-| Persistent RPC transport | One retained agent lazily owns at most one exact-loaded Pi RPC child; `agent_settled` is the completion boundary and accepted work is never replayed automatically | `src/rpc-transport.ts`, [`pi-subagents-rpc-v1.md`](pi-subagents-rpc-v1.md) |
-| Detached completion delivery | `next-turn` is the default non-waking delivery; opt-in `auto-resume` steers completion into active root context without a wake, or requests at most one in-flight synthesis turn when the root is idle and has no pending input; exact completion IDs remain pending until context acknowledgement | `src/completion-delivery.ts`, completion-delivery tests |
-| Deterministic timeout and cleanup | Work, idle, turn, and tool budgets use bounded abort and process or session cleanup; explicit parent interruption never starts timeout finalization | runner, transport, timeout, and cleanup tests |
-| Bounded protocol and output | Model-facing content and safe projections are bounded to 50 KiB or 2,000 lines | `src/protocol.ts`, `src/limits.ts`, rendering and inspection tests |
-| Partial structured outcomes | Blocking, detached, and consultation paths preserve bounded post-launch evidence and usage; structured-v2 keeps claims, artifacts, verification, limitations, and unresolved dependencies | result-contract, runner, consultation, and orchestration tests |
-| Enforced delegation contracts | Optional `pi-subagents:delegation:v2` contracts validate declared capabilities, dependencies, evidence, side-effect policy, and supported enforcement without claiming unsupported path, network, or secret guarantees | `src/delegation-contract.ts`, contract and workflow tests |
-| Recursion guard | `PI_SUBAGENT_DEPTH` and `PI_SUBAGENT_MAX_DEPTH` bound nested delegation | `src/execution.ts`, runtime policy and runner tests |
-| Hierarchical ownership | Parent, root, depth, children, and authenticated task paths are persisted; subtree interrupt and close run child-first | `src/registry.ts`, registry and orchestration tests |
-| Bounded mailbox and peer delivery | Mailboxes support acknowledgement and deduplication; inspection exposes only counts; nested peer delivery uses session-scoped authenticated channels | registry, peer transport, mailbox, and inspection tests |
-| Shared and isolated workspaces | Shared-workspace agents may write concurrently by default; deprecated `allowConcurrentWrites` is a no-op; opt-in clean-Git worktrees provide disposable repository isolation | `src/stateful-registration.ts`, `src/workspace.ts`, workspace tests |
-| Separate active and retained capacity | FIFO active-turn scheduling and retained-agent limits are independent and hierarchy depth and child counts are bounded separately | `src/registry.ts`, capacity and fairness tests |
-| Parent context selection | Context supports none, all, summary, recent N user turns, and selected entry ids; projection is text-only, sanitized, and bounded | `src/context.ts`, context protocol tests |
-| Target trust resolution | Current workspace uses session trust; external targets use the nearest saved `ProjectTrustStore` decision, with a nearer denial winning | `src/cwd-policy.ts`, `test/cwd-policy.test.ts` |
-| Consultation target policy | Consultation defaults to any existing target and removes inherited target and project resources when effective trust is absent | `src/consult.ts`, consultation cwd and trust tests |
-| General delegation target policy | Delegation defaults to trusted targets; blocking and detached requests are preflighted and every transport receives the same resolved trust decision | execution, stateful, cwd-policy, and transport tests |
-| Durable logical history | Versioned private state restores inert; retained transports seed bounded sanitized context and logical history once after explicit follow-up | `src/persistence.ts`, persistence and orchestration tests |
-| Automatic side-effect resume | Restored records never restart work; semantic resource skew requires explicit revalidation before a follow-up | persistence, semantic snapshot, and lifecycle tests |
-| Stable tool schema | Registered tool membership does not change across retained-agent state transitions; workflow changes require reload | registration and settings UI tests |
-| Native transcript switching | Unsupported because Pi exposes no supported child transcript or session switch handle | public SDK boundary review |
-| Approval, sandbox, and header inheritance | Unsupported as a general guarantee and reported explicitly in result policy metadata | result policy and transport tests |
-| Filesystem isolation | Optional disposable worktree only; cwd and trust policies are not OS sandboxes and do not restrict absolute paths, processes, network, or credentials | `src/workspace.ts`, README security boundary |
-| Extension-owned autonomous planning | Removed; topology belongs to the main agent or a caller-authored workflow request | built-in catalog, execution, and registration tests |
-
-## Read-only boundary
-
-`subagent_inspect` is side-effect-free at the extension capability boundary.
-It uses pure settings and metadata snapshots, applies project-trust gates before project discovery, and omits prompts, history, context content, mailbox content, credential-bearing model fields, and unsafe paths.
-
-`subagent_consult` is synchronous and non-retained.
-Missing agent tool configuration selects the read-only default set, an explicit empty list selects no tools, and any explicit list is intersected with the supported read-only built-ins.
-Extensions, sessions, lifecycle tools, shell execution, and file mutation tools are disabled.
-Pre-launch failures throw.
-Once a child starts, bounded partial evidence and nested usage are retained and the finalized Pi tool result is marked as an error when consultation fails.
-
-These are executor and resource-loading guarantees, not filesystem, network, process, or confidentiality sandboxes.
-A consultation can read an accessible absolute path when explicitly asked and calls the configured model over the network.
-
-## Runtime ownership boundary
-
-The logical registry owns ids, hierarchy, capacity, mailboxes, completion delivery, persistence, semantic revalidation, and workspace cleanup.
-Each retained turn owns one transport session or process according to its fixed effective transport.
-Close, expiry, replacement, reload, and shutdown abort work and release transport and disposable-workspace ownership.
-
-Pi core still owns provider execution, active-turn admission, message ordering, retries, compaction, interactive transcript selection, and global scheduling.
-The extension does not claim inherited approval or sandbox policy, provider-header hooks, extension state, or a core-owned child-session tree.

package/docs/implementation-notes/pi-subagents-current-direction.md

@@ -1,99 +0,0 @@
-# pi-subagents current direction
-
-This note is the entry point for current `@narumitw/pi-subagents` planning.
-
-## Current product shape
-
-`pi-subagents` is a delegation runtime, not an automatic planner.
-
-The main agent decides whether to delegate and how to split work.
-
-The built-in catalog is intentionally small:
-
-| Built-in | Purpose | Default tools |
-| --- | --- | --- |
-| `explorer` | Bounded read-only repository exploration with cited paths and evidence. | `read`, `grep`, `find`, `ls` |
-| `worker` | Write-capable parallel implementation, command execution, and fixes. | Pi default tools |
-
-Removed built-ins and tools are not part of the active surface:
-
-- `planner`;
-- `reviewer`;
-- `general`;
-- `general-purpose`; and
-- `subagent_auto`.
-
-## Delegation rules
-
-Use no subagent for simple, latency-sensitive, conversational, tightly coupled, or single-lane implementation work that the main agent can do directly.
-
-Use `explorer` when a bounded read-only search can save main-context space or run independently.
-
-Keep overall planning, immediate critical-path work, integration, final verification, and the final answer in the main agent.
-
-A worker may directly implement a bounded slice with clear ownership when it can run independently beside useful non-overlapping main-agent work.
-
-Use one async `worker` only when the main agent has named that local work to continue immediately and the worker result has a supported delivery and integration path.
-
-If the main agent has no such local work, it should implement directly instead of spawning one worker.
-
-Use two or more workers only for disjoint implementation slices whose parallel progress justifies coordination, and keep integration ownership in the main agent.
-
-A single worker without concurrent main-agent work remains an explicit escape hatch for a user-requested specialist model, tool profile, or isolation boundary rather than the ordinary implementation path.
-
-Use custom user or project agents for specialist review, verification, or shell-capable read-mostly work.
-
-Custom project agents remain subject to existing trust and confirmation behavior.
-
-Review should usually be handled by the main agent plus review skills and deterministic checks.
-
-Use custom verifier agents only when independent child verification is explicitly worth the added cost and coordination.
-
-## Tool-surface direction
-
-`all` remains the compatibility default, while `async-only` remains an optional smaller tool surface.
-
-`async-only` exposes `subagent_spawn`, `subagent_send`, `subagent_manage`, `subagent_mailbox`, and `subagent_inspect`.
-`all` additionally exposes supported `subagent_await` and `subagent_consult` plus deprecated blocking `subagent` for compatibility.
-
-`subagent_spawn` is preferred only when detached execution creates real parallelism rather than moving the main agent's only useful task into a child.
-
-After spawning one worker, the main agent should immediately continue the named non-overlapping work instead of only announcing the spawn, waiting, polling, or ending the turn.
-
-Final-answer-dependent detached work needs a supported synthesis path such as opt-in `auto-resume`; default `next-turn` delivery remains appropriate only when the current response does not depend on the result.
-
-Blocking `subagent` is deprecated for new work but remains available with its existing schema and execution behavior for established callers and explicit requests whose chain, fan-in, panel, or workflow semantics lack a detached replacement.
-
-No removal release or date is set until those compatibility modes have a separately approved replacement or migration.
-
-`subagent_consult` remains a supported synchronous read-only exception.
-
-`subagent_await` remains a supported intentional join after useful overlapping parent work is complete.
-
-The four async lifecycle tools remain split because start, follow-up, lifecycle, and queue operations have distinct contracts.
-`subagent_await` remains separate because waiting blocks the parent, its timeout never interrupts the child, and the async-only workflow must omit it.
-
-Changing the default, removing deprecated `subagent`, or consolidating lifecycle tools needs a separate approved migration decision.
-
-## Active follow-ups
-
-None.
-
-New implementation work should respond to demonstrated user needs rather than extending automatic or adaptive routing speculatively.
-
-## Current reference notes
-
-- Git history for the completed main-agent-led delegation guidance records the accepted delegation rubric and verification evidence.
-- Git history for the completed async-first tool-surface work records the earlier tool-surface decision and implementation evidence.
-- [`pi-subagents-capability-matrix.md`](pi-subagents-capability-matrix.md) records maintained capability, detached lifecycle, transport, trust, and runtime-ownership boundaries.
-- [`pi-subagents-rpc-v1.md`](pi-subagents-rpc-v1.md) records the persistent RPC transport contract.
-
-## Historical evidence
-
-The consolidated [research synthesis](../../../../docs/research/coding-agent-subagents-research.md) records the architecture conclusions available at the research cutoff.
-
-The companion [evidence catalog](../../../../docs/research/coding-agent-subagents-evidence-catalog.md) preserves paper-level results, caveats, and primary sources.
-
-Superseded automation, proactivity, and old runtime notes were removed to keep the active docs small.
-
-Git history remains the record of earlier research drafts and raw search transcripts.

package/docs/implementation-notes/pi-subagents-rpc-v1.md

@@ -1,153 +0,0 @@
-# pi-subagents RPC v1
-
-`pi-subagents:v1` is the extension-owned transport and metadata contract layered over Pi's built-in RPC JSONL protocol.
-
-It does not add commands to Pi RPC or alter Pi command and event payloads.
-
-## Envelope
-
-Extension-owned progress, run inspection, and completion metadata may include these bounded fields:
-
-```json
-{
-  "protocol": "pi-subagents:v1",
-  "agentId": "sa_…",
-  "transport": "rpc",
-  "phase": "starting | ready | accepted | running | finalizing | retrying | compacting | settled | failed | interrupted",
-  "timing": {},
-  "provider": "…",
-  "model": "…",
-  "thinkingLevel": "medium",
-  "usage": {}
-}
-```
-
-Fields are additive and optional within v1.
-
-A breaking lifecycle or envelope change requires another protocol identifier.
-
-Raw prompts, chain-of-thought, credentials, headers, environment values, full stderr, and raw tool arguments never enter the envelope.
-
-## Usage accounting
-
-Pi 0.84.2 RPC `message_update.usage` values are cumulative for the current assistant message.
-
-RPC v1 keeps the latest validated update as one replaceable in-flight snapshot instead of adding successive updates together.
-
-A valid `message_end.message.usage` is authoritative for the finalized assistant message.
-
-When final usage has no valid token or total-cost field, RPC v1 commits the latest valid in-flight snapshot instead.
-
-A new assistant `message_start` commits usage from an interrupted prior attempt before tracking the new cumulative stream.
-
-Timeout finalization commits the interrupted work snapshot before clearing captured output and starting the bounded summary attempt.
-
-Progress and terminal outcomes expose the safe sum of committed usage plus the current in-flight snapshot.
-
-Only non-negative finite values no larger than `Number.MAX_SAFE_INTEGER` enter telemetry, and `totalTokens` is derived from valid components only when no valid reported total exists.
-
-The `turns` field continues to count finalized assistant messages only, so interrupted attempts and tool-result messages do not increment it.
-
-Usage progress contains only normalized token counts, total cost, and finalized-turn count, and never adds raw RPC events, prompts, content, reasoning, credentials, headers, or environment values to the envelope.
-
-## Lifecycle
-
-One retained `agentId` lazily owns at most one RPC child.
-
-The child starts through the exact loaded Pi package with `--mode rpc --no-session --no-extensions`.
-
-A correlated `get_state` response is the readiness handshake.
-
-The task timeout begins only after readiness.
-
-Optional idle, assistant-turn, and tool-call budgets begin with prompt execution and observe only completed assistant messages or tool results as meaningful progress.
-
-The transport subscribes before sending `prompt`.
-
-A successful prompt response means accepted, not completed.
-
-`agent_end` is a low-level run boundary and cannot complete a retained turn.
-
-`agent_settled` is the authoritative completion boundary after retries, compaction, and queued continuations settle.
-
-Abort and timeout send the Pi RPC `abort` command and wait for settlement within a bounded grace period.
-
-After a work, idle, assistant-turn, or tool-call budget stop settles, the transport creates a bounded redacted checkpoint and sends one bounded finalization prompt that requests only a summary of already gathered evidence and explicitly forbids further tool use.
-
-Pi RPC does not currently replace an existing child session's active tool set for one turn, so the finalization deadline and abort path remain authoritative if the model disregards that instruction.
-
-The finalization turn has a separate model-work deadline of at most 45 seconds, followed only by bounded abort and process-cleanup grace, and never replays the timed-out task.
-
-Explicit parent interruption does not start finalization.
-
-A child that does not settle after work or finalization abort is terminated and cannot be reused.
-
-An accepted or ambiguously accepted task is never replayed automatically.
-
-Process exit marks the turn failed or interrupted with bounded partial evidence.
-
-Budget-stopped outcomes keep exit `124` and add a `pi-subagents:termination:v1` report with the stop reason, selected limit, deterministic `pi-subagents:checkpoint:v1`, side-effect warning, and finalization status.
-
-Release, expiry, close, session replacement, reload, and shutdown abort owned work and terminate the process group until captured streams close.
-
-Extension UI requests fail closed in v1.
-
-## Resources and tools
-
-RPC v1 supports Pi built-in tools only.
-
-Child extensions stay disabled to prevent recursive `pi-subagents` loading and duplicate extension side effects.
-
-Custom or extension tools fail before RPC child creation with a subprocess recommendation.
-
-The selected cwd, project-trust decision, role prompt, model, thinking level, context, mailbox input, execution budgets, recursion depth, and output bounds retain their existing owners.
-
-`subagent_spawn.timeoutMs`, `idleTimeoutMs`, `maxTurns`, and `maxToolCalls` are retained as agent defaults, while the same fields on `subagent_send` override only one follow-up turn.
-
-RPC session-file persistence stays disabled because `AgentPersistence` owns sanitized logical recovery records.
-
-A restored record starts no process until an explicit follow-up arrives.
-
-Its first new RPC turn seeds bounded sanitized parent context and logical history exactly once.
-
-## Automatic selection
-
-`stateful.transport: "auto"` selects exactly one transport before child creation.
-
-Read-only built-in tool sets select `in-process` for the lowest startup overhead.
-
-The current built-in `explorer` default uses only `read`, `grep`, `find`, and `ls`, so it remains eligible for this route.
-
-Write-capable built-in tool sets select `rpc` for a persistent separate process.
-
-Extension or custom tools select the existing fresh `subprocess` path.
-
-The selection remains fixed for the retained agent's current runtime lifetime.
-
-A restored inert record is preflighted again on its first explicit follow-up.
-
-No startup or post-acceptance failure triggers automatic fallback.
-
-## Execution defaults
-
-Fast, Balanced, and Deep execution profiles were removed.
-
-The built-in `explorer` defaults to `low` thinking for bounded read-only exploration.
-
-The built-in `worker` inherits model and thinking unless a caller, frontmatter, or per-agent setting selects a value.
-
-Execution defaults do not change tools, transport, completion delivery, parent context, or explicit tool-call limits.
-
-## Measurement
-
-Run `just benchmark-subagents` for serial offline startup and retained state-command measurements.
-
-The benchmark makes no provider request and therefore measures transport overhead rather than model quality or latency.
-
-A provider-backed smoke is optional and must stop after one clear external quota, credential, or entitlement failure.
-
-A seven-sample isolated-agent run on 2026-08-09 recorded 27.728 ms median deterministic fresh subprocess turn overhead with 0.782 ms MAD, 0.073 ms first retained RPC turn with 0.006 ms MAD, 0.037 ms retained RPC follow-up with 0.004 ms MAD, 445.631 ms real Pi RPC readiness with 9.765 ms MAD, 0.893 ms retained real Pi RPC `get_state` with 0.036 ms MAD, 3.759 ms in-process session creation with 0.198 ms MAD, and 0.001 ms retained in-process state access with 0.000 ms MAD.
-
-The deterministic turn measurements use a fake Pi while the readiness and SDK measurements use an isolated real Pi installation without credentials.
-
-The measurement supports retained transports as startup-overhead improvements without claiming provider-turn latency or quality.