@caupulican/pi-adaptative 0.81.32 → 0.81.35

package/docs/windows.md

@@ -1,17 +1,110 @@
-# Windows Setup
+# Windows
 
-Pi requires a bash shell on Windows. Checked locations (in order):
+Pi supports native Windows on x64 and ARM64. The Node.js package runs under Windows Node.js; release archives contain a native `pi.exe`. WSL is optional, not required.
 
-1. Custom path from `~/.pi/agent/settings.json`
-2. Git Bash (`C:\Program Files\Git\bin\bash.exe`)
-3. `bash.exe` on PATH (Cygwin, MSYS2, WSL)
+## Prerequisites
 
-For most users, [Git for Windows](https://git-scm.com/download/win) is sufficient.
+- Windows 10 or newer
+- Node.js 22.19 or newer for the npm package
+- [Git for Windows](https://git-scm.com/download/win), including Git Bash
+- Windows Terminal, WezTerm, or the VS Code terminal for the best keyboard support
 
-## Custom Shell Path
+Pi keeps Bash as the command-tool contract on every platform so tool calls and project scripts have the same semantics. On Windows, Pi resolves Bash in this order:
+
+1. `shellPath` in `%USERPROFILE%\.pi\agent\settings.json`
+2. Git Bash under `Program Files`
+3. `bash.exe` on `PATH` from MSYS2, Cygwin, or WSL
+
+Git for Windows is the recommended native setup. Using its Bash subprocess does not make Pi a WSL application.
+
+To configure another Bash:
 
 ```json
 {
   "shellPath": "C:\\cygwin64\\bin\\bash.exe"
 }
 ```
+
+## Install
+
+With npm:
+
+```powershell
+npm install -g --ignore-scripts @caupulican/pi-adaptative
+pi
+```
+
+Or download `pi-windows-x64.zip` or `pi-windows-arm64.zip` from the matching GitHub release, extract it, and run `pi.exe`.
+
+## Capability contract
+
+A Windows release is expected to preserve the same Pi features as Linux and macOS. Platform prerequisites and operating-system concepts are called out explicitly instead of being silently downgraded.
+
+| Capability | Windows contract | Repository acceptance evidence |
+| --- | --- | --- |
+| CLI, print, JSON, and RPC modes | Native | Full package build and test suite on `windows-latest` |
+| Interactive TUI and configurable keybindings | Native | TUI tests on Windows; packaged `win32-console-mode.node`; Windows Terminal mappings below |
+| `read`, `write`, `edit`, `grep`, `find`, and `bash` tools | Native; Bash prerequisite | Coding-agent tests on Windows; release `pi.exe` executes Bash through RPC |
+| Provider APIs, OAuth, API-key auth, model routing, and retries | Native | AI, agent, and coding-agent tests on Windows; live credentials are not used in CI |
+| Extensions, skills, prompts, themes, and pi packages | Native | Discovery, loading, reload, package-manager, and isolation tests on Windows |
+| Sessions, branching, compaction, context storage, export, and sharing | Native | Agent and coding-agent session tests on Windows |
+| Background delegation, goal continuation, reflection, and worker queues | Native | Delegation and liveness suites on Windows; no tmux dependency |
+| Clipboard text, clipboard images, and image processing | Native | Windows native clipboard binding is packaged per architecture; conversion tests run headlessly |
+| Managed `rg`, `fd`, Ollama, and Transformers runtimes | Native where the upstream runtime supports the architecture | Platform selection, install, process, and lifecycle tests on Windows |
+| Toolkit scripts | Native | PowerShell, Bash, and `uv` runners use the same bounded process lifecycle |
+| External editor and browser launch | Native | Windows process-launch tests; `$EDITOR`/`$VISUAL` and the default browser remain user choices |
+| Self-update | npm and pnpm global installs | Windows native-dependency quarantine and update-path tests |
+| Release binary | Native x64 and ARM64 | Each archive runs `--version`, `--help`, `--list-models`, RPC state, and an RPC Bash command on its matching GitHub-hosted Windows architecture |
+| tmux agent manager | Available only when a real tmux is supplied by WSL, MSYS2, or Cygwin | Optional integration; core background delegation does not require tmux |
+| Suspend with `Ctrl+Z` | Not an applicable Windows process concept | Pi reports the platform limitation instead of hanging or pretending to suspend |
+
+The source-of-truth gates are [CI](https://github.com/Caupulican/pi-adaptative/actions/workflows/ci.yml) and [release binaries](https://github.com/Caupulican/pi-adaptative/actions/workflows/build-binaries.yml). Linux-only inspection is not accepted as Windows proof: the CI workflow runs the repository on a real Windows host, and the release workflow runs each Windows executable on its matching x64 or ARM64 host before publishing it.
+
+Headless CI cannot assert a user's clipboard contents, complete an OAuth consent screen, or judge a terminal emulator's rendering. It does verify the code paths, native modules, process lifecycle, and release executables. Those external interactions remain terminal-, account-, or service-dependent rather than Windows capability downgrades.
+
+## Windows Terminal keys
+
+Windows Terminal consumes some modified key combinations unless they are forwarded. Open its JSON settings (`Ctrl+Shift+,`) and add these actions:
+
+```json
+{
+  "actions": [
+    {
+      "command": { "action": "sendInput", "input": "\u001b[13;2u" },
+      "keys": "shift+enter"
+    },
+    {
+      "command": { "action": "sendInput", "input": "\u001b[13;3u" },
+      "keys": "alt+enter"
+    }
+  ]
+}
+```
+
+- `Shift+Enter` inserts a newline.
+- `Alt+Enter` queues a follow-up. This replaces Windows Terminal's default fullscreen binding.
+
+See [Terminal setup](terminal-setup.md) for VS Code, WezTerm, and other terminals.
+
+## Troubleshooting
+
+### No Bash shell found
+
+Install Git for Windows or set `shellPath` to an existing `bash.exe`. Confirm it from PowerShell:
+
+```powershell
+& "C:\Program Files\Git\bin\bash.exe" --version
+```
+
+### Modified Enter does not reach Pi
+
+Apply the Windows Terminal mappings above, then fully close and reopen the terminal.
+
+### Native module fails to load
+
+Confirm that the package or archive matches the machine architecture (`x64` or `arm64`). Reinstall without lifecycle scripts:
+
+```powershell
+npm uninstall -g @caupulican/pi-adaptative
+npm install -g --ignore-scripts @caupulican/pi-adaptative
+```

package/docs/work-directory.md

@@ -0,0 +1,41 @@
+# Transient work directory
+
+Pi-owned transient files live under one multi-tenant root:
+
+```text
+~/.pi/agent/work/<category>/<tenant>/<run-id>/
+```
+
+`PI_ADAPTATIVE_CODING_AGENT_DIR` still relocates the whole agent directory. Pi exposes the resolved work root to child processes as `PI_WORK_ROOT`.
+
+## Contract
+
+- `category`, `tenant`, and `run-id` are lowercase portable path segments, at most 64 characters.
+- Windows-reserved names, traversal, separators, trailing dots, and case-ambiguous uppercase names are rejected on every platform.
+- Every owned run has `.pi-work-run.json` metadata.
+- Active processes hold PID/host lease markers under `.leases/`.
+- Cleanup never follows symlinks, never deletes directories without a matching ownership manifest, and rechecks leases under an exclusive cleanup marker before removal.
+- Retention is bounded by age, run count, total bytes, scanned runs, recursive entries, and directory depth. An incomplete size scan is treated as over-budget instead of undercounted.
+- Released work remains available for diagnostics until retention removes it. A caller that owns a one-shot run may release and delete it immediately.
+
+The default per-tenant retention policy is 30 days, 64 inactive runs, 512 MiB, 10,000 scanned runs, and 100,000 recursively scanned entries. Active runs are never removed to satisfy those limits.
+
+## Repository API
+
+Extensions and internal code can use the public helpers:
+
+```ts
+import { acquireWorkRun, getProcessWorkRun, pruneWorkTenant } from "@caupulican/pi-adaptative";
+```
+
+- `acquireWorkRun(...)` returns a unique or named leased run. Call `release()` when the operation ends.
+- `getProcessWorkRun(...)` reuses one leased run for process-scoped output.
+- `pruneWorkTenant(...)` applies bounded retention to one category and tenant.
+
+Use a named run only for transient coordination that must be shared across Pi processes. Use a generated run for commands, reports, downloads, tests, benchmarks, probes, and output spills.
+
+## Not transient
+
+Configuration and durable user data stay outside `work/`: `settings.json`, `auth.json`, `models.json`, `sessions/`, `state/`, `skills/`, `extensions/`, `prompts/`, `themes/`, profiles, backups, and managed binaries.
+
+Do not put Automata memory or its graph in Pi's work directory. Automata remains an external memory system.

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "0.81.32",
+  "version": "0.81.35",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "0.81.32",
+      "version": "0.81.35",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-anthropic",
   "private": true,
-  "version": "0.81.32",
+  "version": "0.81.35",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "0.81.32",
+  "version": "0.81.35",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-sandbox",
-	"version": "0.81.32",
+	"version": "0.81.35",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-sandbox",
-			"version": "0.81.32",
+			"version": "0.81.35",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "^0.0.26"
 			}

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-sandbox",
 	"private": true,
-	"version": "0.81.32",
+	"version": "0.81.35",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-with-deps",
-  "version": "0.81.32",
+  "version": "0.81.35",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-with-deps",
-      "version": "0.81.32",
+      "version": "0.81.35",
       "dependencies": {
         "ms": "^2.1.3"
       },

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-with-deps",
   "private": true,
-  "version": "0.81.32",
+  "version": "0.81.35",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/npm-shrinkwrap.json

@@ -1,17 +1,17 @@
 {
 	"name": "@caupulican/pi-adaptative",
-	"version": "0.81.32",
+	"version": "0.81.35",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "@caupulican/pi-adaptative",
-			"version": "0.81.32",
+			"version": "0.81.35",
 			"license": "MIT",
 			"dependencies": {
-				"@caupulican/pi-agent-core": "^0.81.32",
-				"@caupulican/pi-ai": "^0.81.32",
-				"@caupulican/pi-tui": "^0.81.32",
+				"@caupulican/pi-agent-core": "^0.81.35",
+				"@caupulican/pi-ai": "^0.81.35",
+				"@caupulican/pi-tui": "^0.81.35",
 				"@ff-labs/fff-node": "0.9.6",
 				"@silvia-odwyer/photon-node": "0.3.4",
 				"chalk": "5.6.2",
@@ -475,11 +475,11 @@
 			}
 		},
 		"node_modules/@caupulican/pi-agent-core": {
-			"version": "0.81.32",
-			"resolved": "https://registry.npmjs.org/@caupulican/pi-agent-core/-/pi-agent-core-0.81.32.tgz",
+			"version": "0.81.35",
+			"resolved": "https://registry.npmjs.org/@caupulican/pi-agent-core/-/pi-agent-core-0.81.35.tgz",
 			"license": "MIT",
 			"dependencies": {
-				"@caupulican/pi-ai": "^0.81.32",
+				"@caupulican/pi-ai": "^0.81.35",
 				"ignore": "7.0.5",
 				"typebox": "1.1.38",
 				"yaml": "2.9.0"
@@ -489,8 +489,8 @@
 			}
 		},
 		"node_modules/@caupulican/pi-ai": {
-			"version": "0.81.32",
-			"resolved": "https://registry.npmjs.org/@caupulican/pi-ai/-/pi-ai-0.81.32.tgz",
+			"version": "0.81.35",
+			"resolved": "https://registry.npmjs.org/@caupulican/pi-ai/-/pi-ai-0.81.35.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"@anthropic-ai/sdk": "0.91.1",
@@ -542,8 +542,8 @@
 			}
 		},
 		"node_modules/@caupulican/pi-tui": {
-			"version": "0.81.32",
-			"resolved": "https://registry.npmjs.org/@caupulican/pi-tui/-/pi-tui-0.81.32.tgz",
+			"version": "0.81.35",
+			"resolved": "https://registry.npmjs.org/@caupulican/pi-tui/-/pi-tui-0.81.35.tgz",
 			"license": "MIT",
 			"dependencies": {
 				"get-east-asian-width": "1.6.0",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@caupulican/pi-adaptative",
-	"version": "0.81.32",
+	"version": "0.81.35",
 	"description": "Adaptive fork of Pi coding agent for self-evolving agent harness experiments",
 	"type": "module",
 	"piConfig": {
@@ -73,9 +73,9 @@
 		"prepublishOnly": "npm run clean && npm run build && npm run shrinkwrap"
 	},
 	"dependencies": {
-		"@caupulican/pi-agent-core": "^0.81.32",
-		"@caupulican/pi-ai": "^0.81.32",
-		"@caupulican/pi-tui": "^0.81.32",
+		"@caupulican/pi-agent-core": "^0.81.35",
+		"@caupulican/pi-ai": "^0.81.35",
+		"@caupulican/pi-tui": "^0.81.35",
 		"@ff-labs/fff-node": "0.9.6",
 		"@silvia-odwyer/photon-node": "0.3.4",
 		"chalk": "5.6.2",