pi-ptc-subagents 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+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.0] - 2026-09-22
+
+First npm release. Ports DSH PTC mode — Programmable Tool Calling, formerly
+DSH "Code Mode" — to `pi`. Behaviour tracks
+[`deepseek-ai/deepseek-harness`](https://github.com/deepseek-ai/deepseek-harness).
+Not a new design. Re-alignment.
+
+Install with `pi install npm:pi-ptc-subagents`. PTC tools register on next
+`pi` startup. No postinstall hook. No setup.
+
+### Added
+
+- **`ptc_run_code`**. Model submits a JS/TS program. Multiple tools execute
+  in one shot. Return value and collected logs return to context. Worker
+  protocol, dispatcher, and surfaces back it.
+- **`ptc_workflow`**. Narration over `ptc_run_code`. Uses the in-program
+  `log()` helper.
+- **`pi.dispatch` binding**. PTC programs fan out to a fresh per-call `pi`
+  subprocess. DSH parity.
+- **Builtin bindings**. `read`, `bash`, `edit`, `write`, `grep`, `find`,
+  `ls`. Callable from a PTC program as `tools.<name>(args)`. DSH parity.
+- **Hoisted images**. Successful bindings lift image blocks onto the PTC
+  tool result. The model sees the picture. The program never carries it
+  through the return value. Parity with `dsh-tools`'s `exec.deferContext`.
+- **Value-tree rendering**. Container completion values render as a tree.
+  One row per property or array index. Bounded by depth and width caps.
+  Withheld amount is shown in-band. Scalar values render as one-line hints.
+- **Truncation contract**. Model-facing text honors `pi`'s truncation cap.
+  Container values render as compact PTC rows.
+- **Skills restored**. The skills section `pi` withholds is restored. PTC
+  programs call them as bindings. DSH parity.
+- **Build verification scripts**. `verify:dist`, `json-to-tui`,
+  `preview-ptc-render`. Run before publishing.
+
+### Changed
+
+- Build pipeline switched to `vite-plus` (`vp pack`). Type declarations
+  bundle via `rolldown-plugin-dts`.
+- Tooling moved to pnpm 12.5.1. `vitest` coverage pinned. Lockfile
+  determinism set via `minimumReleaseAge: 0`.
+- Lint and format moved to `oxlint` (type-aware) and `oxfmt`.
+
+### Fixed
+
+- `pi.dispatch` now spawns `pi` directly. The host script used to swallow
+  the child's exit.
+- `maxPendingCalls` stays in the worker. The caller no longer trips on
+  arrivals.
+- Bindings mirror the session's active tools. A session that disables a
+  tool also disables it inside PTC programs.
+- pnpm overrides dropped. No-op under pnpm 12.5.1.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,191 @@
+# pi-ptc-subagents
+
+DSH-style **PTC mode** (Programmable Tool Calling) for [pi](https://pi.dev):
+the model writes a JS/TS program that calls pi's tools from inside a worker,
+and only the program's return value plus its logs come back to the model.
+
+## Status
+
+Pre-1.0, but functional: `ptc_run_code` and `ptc_workflow` are registered and run
+programs through the same tested worker machinery (dispatcher, wire protocol,
+budgets, built-in bindings). The implementation is written clean-room from
+[DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) PTC
+behaviour (tracked as a wayfinder map in this repo's issues).
+
+## Install
+
+```bash
+pi install npm:pi-ptc-subagents
+```
+
+From a local checkout: `pnpm install && pnpm run build && pi install /abs/path/to/this/repo` (or `npm install && npm run build && …` — the lockfile is `pnpm-lock.yaml`; with npm you'll need `npm i` to regenerate `package-lock.json`).
+
+pi reads the `pi.extensions` manifest field, so no extra setup steps are
+required — install it and the extension is on for the next pi startup.
+
+## Tools
+
+- `ptc_run_code` — run a JS/TS program that composes tool calls; the program
+  reaches tools as `tools.read(...)`, `tools.write(...)`, etc. (all seven
+  built-ins, `bash` included); its return value and `console.log` output are
+  reported back.
+- `ptc_workflow` — structured variant with `meta` + plain-JSON `args`, plus the
+  workflow helpers (`log`, `phase`, `parallel`, `pipeline`). There is no
+  `agent()` helper on either surface.
+
+Long output follows pi's own truncation contract ([ADR-0015](./docs/adr/0015-pi-truncation-contract.md)):
+
+the text block keeps the tail (50 KB / 2000 lines) and the untruncated text is written to a temp file
+
+the next program can `tools.read`; the collapsed row then shows `truncated` in its meta.
+
+## Dispatch (fan-out to per-call pi subprocesses)
+
+PTC programs can spawn a fresh `pi` subprocess per call via the **`pi.dispatch(...)`** binding ([ADR-0016](./docs/adr/0016-ptc-dispatch-binding.md)). Use it to fan out to a specialist agent — the child subprocess loads the named agent's markdown from `~/.pi/agent/agents/<name>.md` (or `.pi/agents/<name>.md` for project-scope agents), runs that agent's tool set and system prompt in isolation, and returns a structured result.
+
+```ts
+// inside a ptc_run_code program
+const result = await pi.dispatch({
+  agent: "scout",
+  task: "find all auth code in src/",
+  cwd: process.cwd(),
+});
+
+// result.status: "fulfilled" | "rejected"  (the binding never throws)
+// result.text:   final assistant text
+// result.usage:  { input, output, cacheRead, cacheWrite, cost, turns }
+// result.exitCode, result.durationMs, result.stderr?, result.errorMessage?
+```
+
+**Fan out in parallel** with the rest of PTC's tools — dispatch is a binding, not a model-visible lifecycle tool, so the dispatcher handles concurrency the same way it does for any other tool call:
+
+```ts
+const [read, scoutA, scoutB] = await Promise.all([
+  tools.read({ path: "package.json" }),
+  pi.dispatch({ agent: "scout", task: "review auth" }),
+  pi.dispatch({ agent: "scout", task: "review db" }),
+]);
+```
+
+**Bounded.** Three knobs keep fan-out from running away:
+
+- `PtcConfig.dispatchConcurrency` (default **8**) — hard cap on concurrently in-flight `pi.dispatch` calls per run. The N+1th concurrent call resolves immediately with `{ status: "rejected", errorMessage: "dispatch concurrency limit reached" }` instead of queuing or spawning.
+- `PtcConfig.maxDispatchDepth` (default **3**) — recursion bound. The child subprocess loads pi-ptc too, so it can write its own PTC programs and call `pi.dispatch` itself; the `childDepth = parentDepth + 1` is rejected when it would exceed `maxDispatchDepth`. The child sees a `<pi-ptc-context depth="N" max-depth="M">…</pi-ptc-context>` hint appended to its system prompt so it can budget its recursion.
+- `signal` — when the parent run is cancelled (deadline, abort, user Esc), every in-flight child receives `SIGTERM` followed by `SIGKILL` after a 5-second grace window, the same shape as pi's `examples/extensions/subagent/index.ts` reference.
+
+**Opt out.** Pass an explicit binding subset to `createBuiltinBindings` to opt out — the parallel binding is mixed in only when the caller accepts the default set:
+
+```ts
+// in a hypothetical runner that wants to keep reads-only:
+createBuiltinBindings({ cwd: "/abs/path", names: ["read", "grep"] });
+// `pi.dispatch` is NOT in the resulting table.
+```
+
+**Not a subagent.** The term _subagent_ is overloaded in this field (DSH's `subagent` is a different thing; pi's `examples/extensions/subagent/` extension is also a different thing). pi-ptc uses _parallel binding_ and _concurrent tool call_ throughout; see `CONTEXT.md` for the canonical terms.
+
+## TUI rendering
+
+Both tools register custom `renderCall` / `renderResult` hooks, so a PTC run reads as a program
+rather than as yet another file operation ([ADR-0013](./docs/adr/0013-ptc-row-compact-summary.md)):
+
+```
+PTC  Find AssistantMessageComponent instantiations
+  ├─ file: "chat-viewport.ts"                 • 1 output line · 1.42s
+  ├─ instantiations: Array(3)
+  │  ├─ [0] {file: "chat-viewport.ts", line: 23}
+  │  ├─ [1] {file: "chat-viewport.ts", line: 47}
+  │  └─ [2] {file: "chat-viewport.ts", line: 91}
+  └─ totalLines: 47
+```
+
+The call row is the tool label plus the model's `description`. Under it, the completion value is
+shown as a **tree**: an object or array with content gives one row per property (or index), nested
+containers recurse behind `├─` / `└─` / `│` connectors, and a small all-scalar container collapses
+onto one row (`{file: "a", line: 12}`). Depth caps at 4 levels, 6 children per container and 120
+characters per row; whatever is withheld is reported (`…+N more keys`, a trailing `…`). A scalar
+value is one line instead — `→ 47`, `→ {}`, `done` when the program returned nothing, or
+`failed: <reason>` in red. The run's countable facts — output lines, workflow phases, attached
+images, warnings, duration — stay pinned to the right edge of the area's first row. Nothing is ever
+printed as escaped JSON. Expanding a row (ctrl+e) adds the code head, phase roll-up, `console.log`
+output and plan-drift warnings, each block labelled and capped. `renderShell` stays at pi's default,
+so these rows keep the same box and colors as the built-in tools.
+
+## Images
+
+An image read _inside_ a program — `await tools.read({ path: "shot.png" })` — is attached to the PTC
+tool result as a real image block, so the model sees the picture instead of a marker string or a wall
+of base64. This is what DSH does by deferring a context message after the run
+([ADR-0014](./docs/adr/0014-image-hoisting.md)). Nothing is capped or deduped: every image the program's
+tool calls produced is attached, in call order, because how much context a run spends is the program's
+call. The collapsed row's meta shows the count (`· 1 image`), so the volume is visible without being
+policed. The program receives the image either way.
+
+## PTC default mode
+
+On a TUI start — install, restart, done — the session narrows its tool loadout so the built-in
+tools are reachable only _from inside a program_:
+
+```
+PTC  Verify the inserted image file
+  → {file, clipNow}                        • 6 output lines · 1 image · 536ms
+```
+
+The model calls `ptc_run_code` / `ptc_workflow`, and reaches `read` / `bash` / `edit` / `write` /
+`grep` / `find` / `ls` through `tools.<name>(args)` inside the program. Tools contributed by _other_
+extensions (`web_search`, `todo`, …) stay directly callable — they cannot become bindings
+(`pi.getAllTools()` returns metadata, not `execute`), so hiding one would make it unreachable for
+the session. The mode's rationale and rejected alternatives are in [ADR-0010](./docs/adr/0010-ptc-default-mode.md).
+
+**Turning it off.** For one session: `/ptc off` (and `/ptc on`, `/ptc` for status). Permanently:
+
+```jsonc
+// ~/.pi/agent/ptc.json
+{ "defaultMode": false }
+```
+
+**Where it does not run.** Print / JSON / RPC sessions are left exactly as launched, and so is a
+session started with an explicit tool restriction (`--tools`, `--exclude-tools`,
+`--no-builtin-tools`) — the extension does not override what you asked for. If another extension
+changes the tool set while the mode is on, the mode yields and tells you.
+
+**The important consequence:** in a TUI session, bindings come from the loadout recorded _before_
+the mode narrowed it. That is what keeps `tools.read(…)` working — and it is why a `--tools`
+restriction still holds: the snapshot is read from `pi.getActiveTools()`, so it can never contain
+tools your session was not launched with.
+
+## Trust posture (read me)
+
+- Installing this package grants it the same machine access as any pi
+  extension: PTC programs run as **you**, with no OS-level sandbox (ADR-0007).
+- Bindings mirror the session's **enabled** built-in tools (`pi.getActiveTools()`):
+  a session started with `--tools …` / `--no-builtin-tools` can only reach those
+  tools from inside a PTC program (a default session has `read`, `bash`, `edit`,
+  `write` — enable more to bind more).
+- Tool calls made from inside a PTC program execute directly and **bypass**
+  pi's `tool_call` hooks (permission gates, path guards) — see ADR-0005. Do not
+  rely on those guards to constrain tool use while this extension is enabled.
+
+## Development
+
+```bash
+pnpm install
+pnpm run typecheck    # tsc --noEmit
+pnpm run lint         # oxlint          (`pnpm run lint:fix` applies fixes)
+pnpm run fmt          # oxfmt (writes); `pnpm run fmt:check` verifies
+pnpm test             # vp test --run --coverage (Vitest 4; coverage via @vitest/coverage-v8)
+pnpm run test:watch   # vp test (interactive)
+pnpm run test:ui      # vp test --ui (local browser UI; not for CI)
+pnpm exec vp test --run tests/render-ptc.test.ts  # renderer unit tests only
+pnpm run build        # vp pack + declaration emit
+pnpm run verify:dist  # exercise renderCall/renderResult through the built dist (no LLM needed)
+node scripts/preview-ptc-render.mjs   # print the rendered rows with real theme colors
+```
+
+Tooling: [oxc](https://oxc.rs) — `oxlint` + `oxfmt` (official defaults) — alongside
+`rolldown` (also oxc-powered), `vite-plus` (bundles Vitest 4), and TypeScript 7.
+
+See ADR-0009 for the Vitest adoption decision (reopens ADR-0008's earlier deferment).
+
+## License
+
+Apache-2.0