pi-ptc-subagents 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -5,6 +5,40 @@ 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.1] - 2026-09-23
+
+PTC runs inside one agent turn no longer pay a cold start each. Nothing changes in
+what a program may call or return; the difference is latency and cancellation
+behaviour.
+
+### Changed
+
+- **Per-turn worker pool.** One warm `worker_threads` Worker per surface
+  (`run_code`, `workflow`) is kept for the duration of an agent turn and reused
+  across its PTC runs — ~0 ms against ~58 ms for a cold spawn (median of 5). The
+  pool is created lazily by the first PTC run of the turn, the two surfaces do not
+  share one, and the extension's `turn_end` hook retires it. Idle workers are
+  `unref()`-ed, so a warm pool never keeps `pi` alive. `runPtcProgram()` gains an
+  optional `pool` field; without it the original cold-start path runs unchanged.
+  ADR-0017.
+- **The worker entry is a real `dist/worker.js`.** The `data:` URL built from
+  `Function.prototype.toString()` is retired, so V8's code cache and Node's module
+  cache survive warm reuse. TypeScript the _model_ submits at run time is still
+  type-stripped inside the worker — that is `compileProgram`'s path, not the
+  bootstrap's.
+
+### Fixed
+
+- **Cancellation settles within a bound in every ordering.** A still-armed deadline
+  is the ceiling when a cancel arrives first; a worker that never answers a timeout
+  settles at `timeoutMs + graceMs`. A superseded run's frames can no longer settle
+  its successor, and an idle worker answers a cancel instead of making the host wait
+  out its grace window. ADR-0017 §10.
+- **`serializedBytes` no longer bills containers as zero bytes.** `[null × 100k]`
+  was counted as nothing, so a frame could slip past `maxMessageBytes`; the helper
+  now matches `JSON.stringify` byte-for-byte and sums `ArrayBuffer` / typed-array
+  leaves.
+
 ## [0.1.0] - 2026-09-22
 
 First npm release. Ports DSH PTC mode — Programmable Tool Calling, formerly

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ExtensionAPI, Skill } from "@earendil-works/pi-coding-agent";
-import { MessagePort } from "node:worker_threads";
+import { MessagePort, Worker } from "node:worker_threads";
 //#region src/mode/ptc-mode.d.ts
 /** The two surfaces this package exposes. `/ptc on` needs at least one of them active. */
 export declare const PTC_MODE_TOOL_NAMES: readonly string[];
@@ -188,7 +188,7 @@ export declare function buildPtcSkillsSection(skills: readonly Skill[], format?:
  *   realm (no VM) and ship no `agent()` (G1 #13 → B), so there is nothing to cap.
  * - `sandbox-unavailable` is not an error kind either: ADR-0007 ships no OS sandbox.
  */
-/** The two worker surfaces. Each run gets a fresh worker with exactly one of them. */
+/** The two worker surfaces. A worker is spawned with exactly one of them and keeps it. */
 type PtcSurface = "run_code" | "workflow";
 interface PtcConfig {
   /** Default elapsed deadline for a run, including nested binding waits (R1 §1). */
@@ -226,6 +226,28 @@ interface PtcConfig {
   maxOldGenerationSizeMb: number;
   /** 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.
+   */
+  poolSize: number;
+  /**
+   * How long `runPtcProgram({ pool })` will wait for an available worker before
+   * failing the run with `kind: workerExit`. Decoupled from `timeoutMs` because
+   * acquire-wait is bounded by the pool's responsiveness, not the run's overall
+   * deadline. Default 30 000 ms.
+   */
+  poolAcquireTimeoutMs: number;
+  /**
+   * Ceiling on how long a pool's `drain()` waits for in-flight workers to release
+   * themselves before terminating them outright: a worker whose `release()` never
+   * arrives (a stuck dispatcher promise, an unobserved crash) must bound the turn-end
+   * hook rather than hang it. Not `graceMs` above, which is a *run's* cooperative-cancel
+   * window; this one is the *pool's* window at retirement, and drain resolves either way.
+   * Default 5 000 ms.
+   */
+  drainGraceMs: number;
 }
 export declare const DEFAULT_CONFIG: Readonly<PtcConfig>;
 /**
@@ -370,6 +392,80 @@ interface CreateBuiltinBindingsOptions {
  */
 export declare function createBuiltinBindings(options: CreateBuiltinBindingsOptions): BindingTable;
 //#endregion
+//#region src/runtime/worker-pool.d.ts
+/** Options the dispatcher hands to `new Worker(...)`. */
+type WorkerPoolWorkerOptions = ConstructorParameters<typeof Worker>[1];
+interface WorkerPoolOptions {
+  /**
+   * Build a fresh worker URL for each spawn. The pool calls this only when it actually
+   * needs to grow the resident count, so a heavy `buildWorkerUrl` is amortised across
+   * warm reuses.
+   */
+  buildWorkerUrl: () => URL;
+  /** Maximum resident workers; acquire when full queues the caller. Default 4. */
+  size?: number;
+  /** Acquire-wait bound; default 30 000 ms. */
+  acquireTimeoutMs?: number;
+  /**
+   * Bound on how long `drain()` waits for in-flight workers to be released before it
+   * terminates them anyway. Default 5 000 ms. Drain resolves either way — expiry is not
+   * an error, it just means a worker was retired without a clean release.
+   */
+  drainGraceMs?: number;
+  /** Options passed verbatim to `new Worker(url, options)` when spawning. */
+  workerOptions: WorkerPoolWorkerOptions;
+}
+interface WorkerPoolStats {
+  resident: number;
+  inFlight: number;
+  waiters: number;
+  totalAcquires: number;
+  poolExhaustions: number;
+}
+/**
+ * A fixed-capacity FIFO-served worker pool. Not safe for concurrent `acquire()` calls
+ * beyond Node's microtask interleaving guarantees — callers (`runPtcProgram`) await
+ * `acquire` before scheduling anything that touches the pool, so the only concurrent
+ * surface is `release()` against an in-flight worker.
+ */
+export declare class WorkerPool {
+  #private;
+  constructor(options: WorkerPoolOptions);
+  /**
+   * Acquire an idle worker, spawn a new one if below capacity, or queue until capacity
+   * opens up. Throws `Error("pool acquire timed out after ${acquireTimeoutMs} ms")` on
+   * timeout; the dispatcher wraps that message with a `pool acquire failed: ` prefix (ADR-0017 §4).
+   */
+  acquire(): Promise<Worker>;
+  /**
+   * Hand a worker back to the pool. If a waiter is queued, hand the worker directly to
+   * them (no idle round-trip). Otherwise park the worker in `idle` — unless it has
+   * already exited, in which case retire it.
+   */
+  release(worker: Worker): void;
+  /**
+   * Last time `release()` was called for `worker`. The dispatcher reads this to
+   * publish `ptc:worker:reset-time` on a warm `ready` frame: `now - lastSettledAt`
+   * is the worker's per-run reset cost (ADR-0017 Addendum). `undefined` for a worker
+   * the pool never released (cold-start).
+   */
+  lastSettledAt(worker: Worker): number | undefined;
+  /**
+   * Wait for every in-flight worker to be released — bounded by `drainGraceMs` — then
+   * terminate every resident worker and reject every queued waiter. After `drain()`
+   * returns the pool is unusable.
+   *
+   * The bound matters: `drain()` is awaited from the pi `turn_end` hook, so a worker
+   * whose `release()` never arrives (a stuck dispatcher promise, an unobserved crash)
+   * must not hold the turn open. Workers still in flight when the grace expires are
+   * terminated with the idle ones, and `drain()` resolves normally — a single bad worker
+   * is not a reason to fail the turn boundary.
+   */
+  drain(): Promise<void>;
+  /** Read-only snapshot of the pool's counters; useful for tests and diagnostics. */
+  stats(): WorkerPoolStats;
+}
+//#endregion
 //#region src/runtime/dispatcher.d.ts
 interface RunPtcProgramOptions {
   /** Program body: an async function body (`return`/`await` at the top level). */
@@ -389,12 +485,26 @@ interface RunPtcProgramOptions {
   signal?: AbortSignal;
   /** Identifier carried to the worker; generated when omitted. */
   runId?: string;
+  /**
+   * Optional worker pool (ADR-0017). Absent = spawn a fresh worker and terminate it
+   * at run end (the original cold-start path). Present = the dispatcher acquires a
+   * worker from the pool at run start and releases it back at run end. Acquire waits
+   * are bounded by `config.poolAcquireTimeoutMs`; on timeout the run fails with
+   * `kind: workerExit`.
+   */
+  pool?: WorkerPool;
 }
 /**
- * One image hoisted out of a successful binding result (DSH parity — see ADR-0014).
+ * One image hoisted out of a successful binding result (DSH parity — see ADR-0014,
+ * ADR-0017 §8).
  *
- * `data` is base64 exactly as pi's own `read` tool returns it, so the tool layer can forward it as
- * an `ImageContent` block without re-encoding.
+ * `data` is base64 exactly as pi's own `read` tool returns it, so the tool layer can
+ * forward it as an `ImageContent` block without re-encoding. The host↔worker wire carries
+ * base64 too: the worker's channel is lossless JSON (a program may return part of a
+ * binding result), and a `MessagePort` transferList of raw bytes could not survive that
+ * contract — a transferred `ArrayBuffer` would be unusable as a program's return value.
+ * Keeping one representation end to end means zero conversions between the binding and
+ * pi's image adapter.
  */
 interface PtcImage {
   data: string;
@@ -413,9 +523,11 @@ interface PtcRunOutcome {
    * Images hoisted out of successful binding results, in call order.
    *
    * Every image a program's tool calls produced, with no cap and no dedupe: how many images a run
-   * attaches is the program's business, exactly as it is in DSH. Present only when at least one was
-   * hoisted — a failed or cancelled run attaches nothing, because the tool layer throws for it
-   * (`codeRunFailedError`) and its image would never reach the model.
+   * attaches is the program's business, exactly as it is in DSH. Each entry carries base64 `data`,
+   * the representation pi's image adapter consumes, so the tool layer forwards it untouched.
+   * Present only when at least one was hoisted — a failed or cancelled run attaches nothing
+   * (ADR-0014 §2), because the tool layer throws for it (`codeRunFailedError`) and its image would
+   * never reach the model.
    */
   images?: PtcImage[];
   /** Failure details; absent on success. */
@@ -430,8 +542,29 @@ interface PtcRunOutcome {
  */
 export declare function runPtcProgram(options: RunPtcProgramOptions): Promise<PtcRunOutcome>;
 //#endregion
+//#region src/runtime/turn-pools.d.ts
+interface TurnPoolsOptions {
+  /** Per-turn limit overrides on top of `DEFAULT_CONFIG` (pool size, acquire bound, V8 caps). */
+  config?: Partial<PtcConfig>;
+}
+export declare class TurnPools {
+  #private;
+  constructor(options?: TurnPoolsOptions);
+  /**
+   * The pool for one surface, created on first request. Warm workers from an earlier
+   * run in this turn are served by the same pool (that is the point); a fresh
+   * `TurnPools` is how a turn gets a fresh set.
+   */
+  get(surface: PtcSurface): WorkerPool;
+  /**
+   * Terminate every pool this holder created. Idempotent, and safe to call from a turn
+   * boundary hook: a second call finds nothing to drain.
+   */
+  drain(): Promise<void>;
+}
+//#endregion
 //#region src/index.d.ts
 export default function ptcSubagents(pi: ExtensionAPI): void;
 //#endregion
-export type { Binding, BindingContext, BindingTable, CreateBuiltinBindingsOptions, DefaultModeConfig, ModeBlockReason, ModeEntryDecision, ModeEntryInput, ModeHideStrategy, PersistedModeState, PtcConfig, PtcErrorKind, PtcErrorShape, PtcJsonValue, PtcModeState, PtcRunOutcome, PtcSurface, RunPtcProgramOptions };
+export type { Binding, BindingContext, BindingTable, CreateBuiltinBindingsOptions, DefaultModeConfig, ModeBlockReason, ModeEntryDecision, ModeEntryInput, ModeHideStrategy, PersistedModeState, PtcConfig, PtcErrorKind, PtcErrorShape, PtcImage, PtcJsonValue, PtcModeState, PtcRunOutcome, PtcSurface, RunPtcProgramOptions, TurnPoolsOptions, WorkerPoolOptions, WorkerPoolStats, WorkerPoolWorkerOptions };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/mode/ptc-mode.ts","../src/mode/skills-section.ts","../src/runtime/limits.ts","../src/runtime/protocol.ts","../src/tools/text.ts","../src/runtime/bindings.ts","../src/runtime/dispatcher.ts","../src/index.ts"],"mappings":";;;;qBA2Ca;;;;;;;;;;qBAWA;;qBAGA;;qBAGA;;qBAGA;;KAGD;;;;;;;;;;;;;qBAcC,uBAAuB;;UAGnB;EACf;;EAEA;;EAEA;;;wBAIc,oBAAoB;;;;;UAQnB;EACf;EACA;;;UAQe;EACf;EACA;EACA;;;;;;;;;wBAUc,sBAAsB,mBAAmB;;KAwC7C;;KAGA;EACN;EAAa;EAAyB;;EACtC;EAAc,QAAQ;;;UAGX;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA,OAAO;;;wBASO,YAAY,sBAAsB;;;;;;;;wBAclC,YAAY,2BAA2B,MAAM;;;;;;;;;;;;;;;wBAqB7C,gBAAgB,OAAO,iBAAiB;;;;;;;wBA4BxC,cAAc,OAAO,cAAc;;;;;wBAQnC,4BACd,OAAO,cACP;;;;;;;;;;;wBAgBc,mBACd,WAAW,gCACX;EACG;EAAyB;;;;;;;;;wBAoBd,qBAAqB,6BAA6B,MAAM;;;;qBCvR3D;;qBAOA;;;;;;;wBASG,qBAAqB;;;;;;;;;;wBAarB,sBACd,iBAAiB,SACjB,UAAS,QAAQ,SAAS;;;;;;;;;;;;;;;;;;KCtChB;UAEK;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;EAOA;;;;EAIA;;;;;EAKA;;;EAGA;;EAEA;;EAEA;;EAEA;;qBAGW,gBAAgB,SAAS;;;;;;;qBAqBzB;;;;;;;wBAeG,gBAAgB,SAAQ,OAAO,aAA2B;;;;;;;wBAe1D,cAAc,YAAW,QAAQ,aAAkB;;;;;;;wBAmBnD,mBACd,+BACA,SAAQ;;;;cC9GJ;WACJ;WACA;WACA;WACA;;qBAEW,wBAAwB;;cAG/B;WACJ;WACA;WACA;WACA;WACA;WACA;WACA;;qBAEW,0BAA0B;cAGjC;WACJ;WACA;WACA;WACA;WACA;;qBAEW,sBAAsB;cAG7B;;WAEJ;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;qBAEW,uBAAuB;KACxB,uBAAuB,6BAA6B;;UAK/C;GACA,cAAA;;KAEL,kDAAkD,iBAAiB;UAE9D;EACf,MAAM;EACN;EACA;;;;;qBCvDW;;wBAwBG,UAAU;;;;;;;;;wBAgBV,aAAa;;;;;;wBA6Ib,iBAAiB,OAAO;;;;qBC7K3B;KASD,6BAA6B;qBAiB5B,gCAAgC;UAE5B;;EAEf,SAAS;;EAET;;EAEA;;EAEA;;UAGe;WACN;EACT,QAAQ,eAAe,SAAS,iBAAiB;;KAGvC,eAAe,oBAAoB;UAkC9B;;EAEf;;EAEA;;;;;;;;;wBAUc,sBAAsB,SAAS,+BAA+B;;;UCnF7D;;EAEf;EACA,SAAS;;EAET;;EAEA,UAAU;;EAEV;;EAEA;;EAEA,SAAS,QAAQ;;EAEjB,SAAS;;EAET;;;;;;;;UASe;EACf;EACA;;UAGe;;EAEf;;EAEA;;EAEA;;EAEA,QAAQ;;;;;;;;;EASR,SAAS;;EAET,QAAQ;;;;;;;;;wBAwBY,cAAc,SAAS,uBAAuB,QAAQ;;;wBCUpD,aAAa,IAAI"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/mode/ptc-mode.ts","../src/mode/skills-section.ts","../src/runtime/limits.ts","../src/runtime/protocol.ts","../src/tools/text.ts","../src/runtime/bindings.ts","../src/runtime/worker-pool.ts","../src/runtime/dispatcher.ts","../src/runtime/turn-pools.ts","../src/index.ts"],"mappings":";;;;qBA2Ca;;;;;;;;;;qBAWA;;qBAGA;;qBAGA;;qBAGA;;KAGD;;;;;;;;;;;;;qBAcC,uBAAuB;;UAGnB;EACf;;EAEA;;EAEA;;;wBAIc,oBAAoB;;;;;UAQnB;EACf;EACA;;;UAQe;EACf;EACA;EACA;;;;;;;;;wBAUc,sBAAsB,mBAAmB;;KAwC7C;;KAGA;EACN;EAAa;EAAyB;;EACtC;EAAc,QAAQ;;;UAGX;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA,OAAO;;;wBASO,YAAY,sBAAsB;;;;;;;;wBAclC,YAAY,2BAA2B,MAAM;;;;;;;;;;;;;;;wBAqB7C,gBAAgB,OAAO,iBAAiB;;;;;;;wBA4BxC,cAAc,OAAO,cAAc;;;;;wBAQnC,4BACd,OAAO,cACP;;;;;;;;;;;wBAgBc,mBACd,WAAW,gCACX;EACG;EAAyB;;;;;;;;;wBAoBd,qBAAqB,6BAA6B,MAAM;;;;qBCvR3D;;qBAOA;;;;;;;wBASG,qBAAqB;;;;;;;;;;wBAarB,sBACd,iBAAiB,SACjB,UAAS,QAAQ,SAAS;;;;;;;;;;;;;;;;;;KCtChB;UAEK;;EAEf;;EAEA;;EAEA;;EAEA;;EAEA;;;;;;;EAOA;;;;EAIA;;;;;EAKA;;;EAGA;;EAEA;;EAEA;;EAEA;;;;;;EAMA;;;;;;;EAOA;;;;;;;;;EASA;;qBAGW,gBAAgB,SAAS;;;;;;;qBAwBzB;;;;;;;wBAeG,gBAAgB,SAAQ,OAAO,aAA2B;;;;;;;wBAe1D,cAAc,YAAW,QAAQ,aAAkB;;;;;;;wBAmBnD,mBACd,+BACA,SAAQ;;;;cCvIJ;WACJ;WACA;WACA;WACA;;qBAEW,wBAAwB;;cAG/B;WACJ;WACA;WACA;WACA;WACA;WACA;WACA;;qBAEW,0BAA0B;cAGjC;WACJ;WACA;WACA;WACA;WACA;;qBAEW,sBAAsB;cAG7B;;WAEJ;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;WAEA;;qBAEW,uBAAuB;KACxB,uBAAuB,6BAA6B;;UAK/C;GACA,cAAA;;KAEL,kDAAkD,iBAAiB;UAE9D;EACf,MAAM;EACN;EACA;;;;;qBCvDW;;wBAwBG,UAAU;;;;;;;;;wBAgBV,aAAa;;;;;;wBA6Ib,iBAAiB,OAAO;;;;qBC7K3B;KASD,6BAA6B;qBAiB5B,gCAAgC;UAE5B;;EAEf,SAAS;;EAET;;EAEA;;EAEA;;UAGe;WACN;EACT,QAAQ,eAAe,SAAS,iBAAiB;;KAGvC,eAAe,oBAAoB;UAkC9B;;EAEf;;EAEA;;;;;;;;;wBAUc,sBAAsB,SAAS,+BAA+B;;;;KCjFlE,0BAA0B,6BAA6B;UAiClD;;;;;;EAMf,sBAAsB;;EAEtB;;EAEA;;;;;;EAMA;;EAEA,eAAe;;UAqCA;EACf;EACA;EACA;EACA;EACA;;;;;;;;qBASW;;EAyBX,YAAY,SAAS;;;;;;EA4CrB,WAAiB,QAAQ;;;;;;EA4DzB,QAAQ,QAAQ;;;;;;;EAuChB,cAAc,QAAQ;;;;;;;;;;;;EAetB,SAAe;;EA4Bf,SAAS;;;;UC7SM;;EAEf;EACA,SAAS;;EAET;;EAEA,UAAU;;EAEV;;EAEA;;EAEA,SAAS,QAAQ;;EAEjB,SAAS;;EAET;;;;;;;;EAQA,OAAO;;;;;;;;;;;;;;UAeQ;EACf;EACA;;UAGe;;EAEf;;EAEA;;EAEA;;EAEA,QAAQ;;;;;;;;;;;EAWR,SAAS;;EAET,QAAQ;;;;;;;;;wBAgGY,cAAc,SAAS,uBAAuB,QAAQ;;;UCtM3D;;EAEf,SAAS,QAAQ;;qBAGN;;EAIX,YAAY,UAAS;;;;;;EASrB,IAAI,SAAS,aAAa;;;;;EAuC1B,SAAe;;;;wBCyDO,aAAa,IAAI"}