pi-ptc-subagents 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -5,6 +5,61 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.3] - 2026-09-23
+
+### Added
+
+- **PTC rows show what the program is doing while it runs.** Two partial-state
+  visuals on the `ptc_run_code` / `ptc_workflow` row, both absent until now:
+  - a **shimmer** on the call row — same text, one character at a time bright,
+    the highlight sweeping at 150ms — so a running row is distinguishable from a
+    settled one in a column (ADR-0020);
+  - a **sub-call tree** under it: one row per binding call the program made,
+    live from the moment the call is made, with its own five-state status
+    (`running` / `ok` / `error` / `cancelled` / `rejected`) and duration,
+    visible without expanding the row and capped at 32 with a `+N more` tail
+    (ADR-0021). A failed run shows the failure text but no sub-call tree: the
+    tool throws (pi's convention), and pi builds that error result with an empty
+    `details`, so the tracked calls are dropped with it.
+
+### Changed
+
+- **Build pipeline: minify + source-map exclusion.** `pnpm run build`
+  (`vp pack`) now produces minified `dist/*.js` (rolldown's built-in oxc
+  minifier; no new dependency). The npm tarball excludes `dist/**/*.map`
+  via the `package.json#files` whitelist — sourcemaps stay on disk for
+  local stack traces, but no longer ship. Tarball shrinks from 168.7 kB
+  packed / 548.6 kB unpacked (v0.1.2 baseline) to 40.5 kB / 113.6 kB
+  (−76% / −79%); `dist/*.js` total shrinks from 161,303 B to 53,959 B
+  (−66.5%). All 39 public exports retain their original names. ADR-0019.
+
+## [0.1.2] - 2026-09-23
+
+### Fixed
+
+- **`pi.dispatch` is registered in production again.** The injection check compared the
+  binding-name array by reference against `DEFAULT_BINDING_NAMES`; production resolves
+  names through a `.filter()` that always returns a fresh array, so the comparison never
+  held and shipped sessions had no `pi.dispatch` at all. Injection now keys off a new
+  `includeDispatch` option (defaulting to "the caller passed no explicit `names`"), and
+  both shipped tools pass it explicitly. ADR-0016.
+- **The dispatch concurrency cap honours `dispatchConcurrency` (default 8) and rejects
+  immediately instead of queueing.** The dispatcher used to read `maxParallelSubCalls`
+  (default 10) and FIFO-queue the overflow; per ADR-0016 §2 the N+1th concurrent
+  `pi.dispatch` now resolves at once with `{ status: "rejected", errorMessage:
+"dispatch concurrency limit reached" }`. The cap applies to `pi.dispatch` only and
+  has its own counter; builtin binding fan-out keeps DSH's `maxParallelSubCalls` (10)
+  FIFO-queueing semantics (ADR-0004), so in-flight builtin calls never consume
+  dispatch slots.
+- **The depth-limit rejection message is verbatim again.** The program receives
+  exactly `dispatch depth limit reached`, matching what the child's
+  `<pi-ptc-context>` hint promises — the diagnostic suffix is gone.
+- **`maxDispatchDepth` bounds recursion again.** Every run reported depth 0 and
+  children never inherited it, so the depth check could never fire. `dispatch()` now
+  stamps `PI_PTC_DEPTH` on the child subprocess's environment, the extension
+  entrypoint reads it back, and `runPtcProgram()` accepts a `depth` baseline that
+  reaches the binding context. ADR-0016 Recursive section.
+
 ## [0.1.1] - 2026-09-23
 
 PTC runs inside one agent turn no longer pay a cold start each. Nothing changes in

package/dist/index.d.ts

@@ -201,16 +201,24 @@ interface PtcConfig {
   maxMessageBytes: number;
   /** Admission control for simultaneously in-flight worker→host binding calls (ADR-0004). */
   maxPendingCalls: number;
-  /** Concurrent binding dispatches; DSH's `maxParallelSubCalls` (ADR-0004 consequence).
-   *  Renamed in spirit by ADR-0016 section 2: the cap that really matters for
-   *  resource safety is the per-run `dispatchConcurrency` below. This field
-   *  is kept for backward compatibility (and for the in-process builtin
-   *  binding fan-out) but is no longer the authoritative limit on the
-   *  parallel binding `pi.dispatch`. */
+  /**
+   * Concurrent builtin binding dispatches; DSH's `maxParallelSubCalls`
+   * (ADR-0004 consequence), mirrored verbatim (10). The overflow
+   * FIFO-queues for a slot instead of failing. This is the authoritative
+   * cap for the builtin fan-out path — independent of
+   * `dispatchConcurrency`, with its own counter: neither cap throttles
+   * the other.
+   */
   maxParallelSubCalls: number;
-  /** Per-run hard cap on concurrently in-flight `pi.dispatch(...)` calls.
-   *  Default 8, matches pi's `subagent` extension `MAX_PARALLEL_TASKS`.
-   *  ADR-0016 section 2. */
+  /**
+   * Per-run hard cap on concurrently in-flight `pi.dispatch(...)` calls,
+   * enforced by the dispatcher: the next concurrent call resolves
+   * immediately with `{ status: "rejected", errorMessage: "dispatch
+   * concurrency limit reached" }` — never queued, never spawned.
+   * Default 8, matches pi's `subagent` extension `MAX_PARALLEL_TASKS`.
+   * ADR-0016 section 2. Independent of `maxParallelSubCalls`: builtin
+   * calls never consume a dispatch slot and vice versa.
+   */
   dispatchConcurrency: number;
   /** Maximum recursion depth for `pi.dispatch`. The child PTC run spawned by
    *  the (depth+1)-th dispatch is allowed only when childDepth <= maxDispatchDepth.
@@ -227,9 +235,10 @@ interface PtcConfig {
   /** V8 young-generation cap handed to `new Worker({ resourceLimits })` (F2). */
   maxYoungGenerationSizeMb: number;
   /**
-   * Per-turn worker pool capacity (ADR-0017 §3). Decoupled from `maxParallelSubCalls`
-   * because pool capacity is "resident workers" while `maxParallelSubCalls` is
-   * "in-flight calls" — two different ceilings. Default 4.
+   * Per-turn worker pool capacity (ADR-0017 §3). Decoupled from
+   * `dispatchConcurrency` because pool capacity is "resident workers" while
+   * `dispatchConcurrency` is "in-flight calls" — two different ceilings.
+   * Default 4.
    */
   poolSize: number;
   /**
@@ -335,6 +344,27 @@ interface PtcErrorShape {
   message: string;
   stack?: string;
 }
+/**
+ * One binding call the program made, as the dispatcher recorded it.
+ *
+ * Host-side only: this shape never crosses the wire — the existing `call` /
+ * `call-result` frames already carry every fact, and the host reconstructs the
+ * record at the seam where the facts are known (`SubCallTracker`,
+ * `src/runtime/sub-call-tracker.ts`). A snapshot reaches the renderer
+ * via `PtcToolDetails.subCalls`.
+ */
+type SubCallStatus = "running" | "ok" | "error" | "cancelled" | "rejected";
+interface SubCallRecord {
+  callId: number;
+  name: string;
+  args: unknown;
+  status: SubCallStatus;
+  startMs: number;
+  endMs?: number;
+  durationMs?: number;
+  resultSummary?: string;
+  errorMessage?: string;
+}
 //#endregion
 //#region src/tools/text.d.ts
 /** Hard cap for one rendered line; longer lines are truncated with `…`. */
@@ -361,6 +391,15 @@ export declare function renderModelValue(value: PtcJsonValue): string;
 /** pi's built-in tools that can be exposed as bindings, in native order. */
 export declare const BUILTIN_BINDING_NAMES: readonly ["read", "bash", "edit", "write", "grep", "find", "ls"];
 type BuiltinBindingName = (typeof BUILTIN_BINDING_NAMES)[number];
+/**
+ * Bindings exposed when the caller does not pass an explicit name list.
+ *
+ * `bash` is included on purpose: DSH's PTC preset still mounts `tool-bash`/`tool-pwsh`
+ * (R1 §2 — PTC mode hides the tools from the wire list and re-exposes the same registry
+ * as bindings), so a PTC program written against DSH may run shell commands. Leaving it
+ * out would silently shrink the surface relative to DSH. Callers that want a read-only
+ * PTC surface pass an explicit subset.
+ */
 export declare const DEFAULT_BINDING_NAMES: readonly BuiltinBindingName[];
 interface BindingContext {
   /** Aborted when the run is cancelled, times out, or settles. */
@@ -382,6 +421,16 @@ interface CreateBuiltinBindingsOptions {
   cwd: string;
   /** Subset of {@link BUILTIN_BINDING_NAMES}; defaults to all of them (bash included). */
   names?: readonly string[];
+  /**
+   * Whether the parallel binding `pi.dispatch` (ADR-0016) joins the table. Defaults to
+   * "did the caller curate the surface": `true` when `names` is omitted, `false` when an
+   * explicit list is passed (R3's read-only PTC surface pattern). Deciding on whether
+   * `names` was provided — not on array identity with {@link DEFAULT_BINDING_NAMES} —
+   * matters because production callers resolve names through a `.filter()` that always
+   * returns a fresh array. The two shipped tools pass `true` explicitly: the dispatch
+   * binding is part of every production surface.
+   */
+  includeDispatch?: boolean;
 }
 /**
  * Build the binding table for one run.
@@ -483,6 +532,14 @@ interface RunPtcProgramOptions {
   config?: Partial<PtcConfig>;
   /** Cancels the run; the worker gets a cooperative cancel window before termination. */
   signal?: AbortSignal;
+  /**
+   * Depth of this run in the `pi.dispatch` recursion chain (ADR-0016 Recursive section):
+   * 0 for the parent turn's run, 1+ for a run inside a child spawned by `pi.dispatch`.
+   * Handed to the binding context so the dispatch binding can bound recursion. The
+   * extension entrypoint derives it from `PI_PTC_DEPTH`; direct library use defaults
+   * to 0.
+   */
+  depth?: number;
   /** Identifier carried to the worker; generated when omitted. */
   runId?: string;
   /**
@@ -493,6 +550,18 @@ interface RunPtcProgramOptions {
    * `kind: workerExit`.
    */
   pool?: WorkerPool;
+  /**
+   * Called every time a sub-call starts or ends, so the caller can push a live partial result
+   * and have the tree visible while the run is in flight (ADR-0021 §4). Never called after the
+   * run settles — `finish` owns the terminal snapshot. Absent means "no live updates wanted"
+   * (direct library use, tests that only assert the terminal outcome).
+   *
+   * The argument is a **thunk**, not the snapshot itself: a wide `Promise.all` produces an
+   * event per call, and `snapshot()` copies every record. Building it eagerly would make N
+   * sequential calls cost O(N²) copies for pushes that the caller's throttle mostly drops.
+   * Call it only when a push is actually due.
+   */
+  onSubCallChange?: (snapshot: () => readonly SubCallRecord[]) => void;
 }
 /**
  * One image hoisted out of a successful binding result (DSH parity — see ADR-0014,
@@ -532,6 +601,15 @@ interface PtcRunOutcome {
   images?: PtcImage[];
   /** Failure details; absent on success. */
   error?: PtcErrorShape;
+  /**
+   * One record per binding call the program made (ADR-0021).
+   *
+   * Present only when the dispatcher tracked sub-calls for the surface in question (always,
+   * post-ADR-0021 — the dispatcher wires `SubCallTracker` for every run). Order is host-side
+   * dispatch order; the renderer reads it as a point-in-time snapshot. Absent for runs that settled
+   * before the tracker was constructed (the pre-`Promise` abort and pool-acquire-failed paths).
+   */
+  subCalls?: readonly SubCallRecord[];
 }
 /**
  * Run one PTC program in a fresh worker and resolve with its outcome.