pi-opencode-cli-bridge 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 luongnv89
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# pi-opencode-cli-bridge
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Use the local [OpenCode CLI](https://opencode.ai) as a model backend for [Pi Coding Agent](https://pi.dev).
+
+This is an unofficial bridge, not an OpenCode or Pi product. It registers the `opencode-cli` provider and sends model requests through `opencode run`.
+
+## Why this fork exists
+
+The bridge started as `opencode-pi`. Rodrigo Jager's fork then kept OpenCode's native tool declarations on each request, which OpenCode's free tier expects, and blocked their execution with a plugin. On Pi 1.2 that version stopped working: Pi now carries the system prompt and tool list inside the transcript, and every request crashed with `message.content.map is not a function`.
+
+This fork fixes that and closes the gaps found while reviewing the code:
+
+- **Works with Pi 1.2.** The current system prompt, prompt sections and tool changes are read from the transcript, so tool calls work again.
+- **Native OpenCode tools cannot run, even if the safety plugin fails.** A test with the real CLI showed that the plugin alone failed open: if it was missing or crashed at startup, OpenCode wrote files. The bridge's agent now also requires permission for every native tool, which `opencode run` refuses automatically.
+- **No hung turns or orphaned processes.** Timeouts and cancellation kill the OpenCode process group, even when it ignores `SIGTERM`.
+- **Unexpected CLI output no longer crashes Pi.** Malformed events end the turn with an error.
+- **Clean shutdown.** Pi waits for temporary directories and OpenCode session records to be removed.
+- **Standard Pi provider hooks.** `onPayload`, `onResponse` and `onProviderStreamEvent` work as with built-in providers.
+- **Its own npm package**, with the original authors credited.
+
+## Credits and fork history
+
+This package builds on other people's work:
+
+- **[luongnv89 and the pi-extensions contributors](https://github.com/luongnv89/pi-extensions/tree/main/extensions/opencode-pi)** created the original `opencode-pi` extension.
+- **[Rodrigo Manuel Jager Pinheiro](https://github.com/rodrigojager/opencode-pi)** extracted the extension and added the native-tool execution blocker for compatibility with OpenCode's free-tier request validation, plus Windows executable resolution.
+- **[Gybra](https://github.com/Gybra/pi-opencode-cli-bridge)** maintains this fork, adds Pi 1.2 transcript compatibility, process and protocol hardening, provider hooks, a second native-tool guard with real-CLI integration tests, and packages it under a distinct name.
+
+The original MIT copyright notice is preserved in [LICENSE](LICENSE). The new package name does not change that attribution.
+
+## Requirements
+
+- Node.js **22.19.0 or newer**.
+- Pi Coding Agent **1.2.0 or newer**; the development SDK is pinned to 1.2.0.
+- OpenCode installed on the same machine and available on `PATH`, or selected with `OPENCODE_PI_BIN`. Tested with OpenCode 1.19.0; other versions, including 2.x, are unverified.
+
+Check OpenCode before starting Pi:
+
+```sh
+opencode --version
+opencode models opencode --verbose
+```
+
+## Install
+
+Install from npm with Pi's package manager:
+
+```sh
+pi install npm:pi-opencode-cli-bridge
+```
+
+Or track the GitHub repository directly:
+
+```sh
+pi install git:github.com/Gybra/pi-opencode-cli-bridge
+```
+
+Then restart Pi or run `/reload`. For the first switch from another bridge, restarting avoids retaining an old provider in memory.
+
+If you already installed another `opencode-pi` source, use `pi list` and remove that source first. For example:
+
+```sh
+pi uninstall npm:opencode-pi
+# Or, if this is the source shown by pi list:
+pi uninstall git:github.com/rodrigojager/opencode-pi
+```
+
+The npm packages `opencode-pi`, `pi-opencode` and `pi-opencode-bridge` are different packages.
+
+Manage the installation with `pi list`, `pi update <source>` and `pi uninstall <source>`, using the source you installed (`npm:pi-opencode-cli-bridge` or `git:github.com/Gybra/pi-opencode-cli-bridge`).
+
+## Usage
+
+Choose an OpenCode model from `/model`, or start Pi directly:
+
+```sh
+pi --provider opencode-cli --model opencode/deepseek-v4.1-flash-free --thinking off
+```
+
+For an isolated text smoke test:
+
+```sh
+pi -p --no-session --provider opencode-cli --model opencode/deepseek-v4.1-flash-free --thinking off "Reply with exactly OK"
+```
+
+Model availability changes. Refresh the list with `/opencode-pi update` if the example model is no longer listed. Bundled free models do not require an OpenCode login; availability and server-side acceptance are controlled by OpenCode.
+
+The provider ID `opencode-cli` and the command `/opencode-pi` retain their upstream names for compatibility:
+
+```text
+/opencode-pi status
+/opencode-pi models
+/opencode-pi test
+/opencode-pi update
+/opencode-pi help
+```
+
+The `test` command prints diagnostic commands; it does not send a model request itself.
+
+## Configuration
+
+| Environment variable | Purpose |
+| --- | --- |
+| `OPENCODE_PI_BIN` | Path to the OpenCode executable. Defaults to `opencode`. |
+| `OPENCODE_PI_MODELS` | Comma- or space-separated model IDs. IDs without a provider prefix receive `opencode/`. |
+
+An explicit model list skips startup discovery and starts with conservative fallback capabilities. Run `/opencode-pi update` to discover image input, reasoning variants, token limits and costs.
+
+Without an override, discovery selects active models whose reported input and output costs are zero. When cost metadata is missing, selection falls back to the upstream free-model naming rules. Review costs before explicitly selecting a paid model.
+
+## How it works
+
+1. The extension discovers models through the local CLI.
+2. It replays Pi's transcript system messages to recover the current system prompt and tool declarations, including later changes.
+3. It creates a temporary OpenCode project containing a `pi-model` agent and a `tool.execute.before` plugin. Native tool declarations remain on the request. Execution is stopped twice: the plugin throws before any native tool runs, and the agent sets every permission to `ask`, which non-interactive `opencode run` rejects automatically. The second layer still holds if the plugin is missing or fails to load.
+4. It sends the prompt over standard input to `opencode run --format json`. User and tool-result images are written to temporary files and attached only when the model supports images.
+5. Text markers such as `<pi_tool_call>{"name":"read","arguments":{"path":"example.txt"}}</pi_tool_call>` become Pi tool calls. Tool names must be in the current Pi tool list; execution then follows Pi's normal validation and permission pipeline.
+6. Successful continuation turns reuse an OpenCode session and send only the new transcript. Changes to the model, prompt, tools or transcript prefix start a fresh session.
+
+Pi's provider instrumentation hooks follow the CLI transport, not OpenCode's internal HTTP traffic:
+
+- `onPayload` receives `{ prompt }`, the exact text written to the CLI's standard input. Returning `{ prompt: "..." }` replaces it; any other non-`undefined` value fails the turn. A turn with a payload hook always starts a fresh OpenCode session.
+- `onResponse` is called once the subprocess has started, with `status: 0` (no HTTP status exists) and the header `x-pi-transport: opencode-cli`.
+- `onProviderStreamEvent` receives each validated `--format json` event in order, and is awaited before the event is processed.
+- Provider-scoped `env` values are passed to the subprocess. The bridge's own configuration directory and update-check settings always take precedence.
+
+Reasoning variants, image support and token limits follow CLI discovery. Token usage is taken from CLI events when available, otherwise estimated. Session records and temporary project directories are cleaned up on a best-effort basis.
+
+## Security, privacy and limits
+
+- Prompts, system instructions, tool declarations, conversation text and attached images pass to OpenCode and its model provider. Do not send confidential data unless that provider's policies are suitable.
+- The extension does not directly extract credentials or call model HTTP endpoints. The OpenCode subprocess still runs as your user and can use its own configuration, credentials and inherited environment.
+- The native-tool guard is a guard rail, **not a sandbox**. An integration test runs the real OpenCode 1.19.0 CLI against a local model fixture that requests native `write` and `bash` calls, and checks that neither runs with the plugin intact, missing, or failing at startup. Other OpenCode versions, tools contributed by your own global OpenCode configuration (for example MCP servers), and a hostile local process are not covered.
+- Pi and OpenCode can both retain local conversation data. Best-effort cleanup is not a guarantee of secure deletion.
+- Free-tier model availability and accepted request shapes can change. This fork makes no guarantee of continued access or compliance with a hosted provider's terms; review the applicable terms yourself.
+- Live tests with DeepSeek v4.1 Flash Free used thinking off. The first high-thinking test timed out; no default thinking setting is changed by this package.
+- Timeouts and cancellation escalate from `SIGTERM` to `SIGKILL` on the CLI's process group after 250 ms. Malformed or unexpected CLI events end the turn with an error instead of crashing Pi. Shutdown waits for session cleanup.
+
+See [SECURITY.md](SECURITY.md) for the trust boundaries and [docs/code-review.md](https://github.com/Gybra/pi-opencode-cli-bridge/blob/main/docs/code-review.md) for what was fixed and what remains. This is an experimental, unaudited fork.
+
+## Development
+
+```sh
+npm ci --ignore-scripts
+npm run typecheck
+npm test
+OPENCODE_PI_INTEGRATION_BIN="$(which opencode)" npm run test:integration
+npm pack --dry-run
+```
+
+`npm test` uses a fake OpenCode executable. `npm run test:integration` needs the real OpenCode CLI at exactly version 1.19.0 (on `PATH` or in `OPENCODE_PI_INTEGRATION_BIN`), runs it with isolated home and data directories against a local model fixture, and makes no network request. Neither suite needs API credentials. Development SDKs are pinned; Pi supplies those packages at runtime. The npm archive includes the extension source, README, security policy and license, not tests or installed dependencies.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/SECURITY.md

@@ -0,0 +1,18 @@
+# Security policy
+
+## Reporting a problem
+
+Never include prompts, conversation history, images, API keys, auth files or session databases in a public report. Use a minimal, sanitized reproduction. For sensitive findings, contact the repository maintainer privately before disclosing details.
+
+## Trust boundaries
+
+- This extension and the OpenCode executable run with your user's operating-system permissions. Neither is a sandbox.
+- Requests are delegated to the real OpenCode CLI. The extension does not directly read credentials, but the subprocess inherits the environment and uses OpenCode's own configuration and authentication.
+- System instructions, tool declarations, transcript text and image attachments can reach the selected model provider. Provider retention and training policies apply.
+- The current Pi tool list is checked before marker responses become Pi tool calls. Pi remains responsible for argument validation and tool permission checks.
+- Native OpenCode tools are blocked twice: a generated `tool.execute.before` plugin, and an agent permission of `ask` for everything, which non-interactive `opencode run` rejects. Native declarations remain visible to the model. Both layers depend on OpenCode 1.19.0 behavior, verified by an integration test with the real CLI. They are not a security boundary against a hostile local process, your own OpenCode configuration (it is loaded and may add tools or agent overrides), or other OpenCode versions.
+- Temporary project directories and OpenCode session records are removed best-effort. Pi's own conversation history is not deleted by the extension.
+
+## Known gaps
+
+The [code review](https://github.com/Gybra/pi-opencode-cli-bridge/blob/main/docs/code-review.md) records the findings fixed in 0.1.0 and the residual risks. Only the latest release is maintained. There is no independently audited security guarantee.

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "pi-opencode-cli-bridge",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Bridge the OpenCode CLI into Pi Coding Agent",
+  "type": "module",
+  "main": "./src/index.ts",
+  "files": [
+    "src/index.ts",
+    "src/process.ts",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test --test-timeout=30000 dist/index.test.js dist/process.test.js",
+    "test:integration": "npm run build && node --test --test-timeout=120000 dist/native-tools.integration.test.js",
+    "prepublishOnly": "npm run typecheck && npm test && npm run test:integration"
+  },
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ],
+    "image": "https://raw.githubusercontent.com/luongnv89/pi-extensions/main/assets/pi-opencode-cli-model-list.png"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "opencode",
+    "bridge",
+    "free-models",
+    "custom-provider"
+  ],
+  "author": "pi-extensions contributors",
+  "contributors": [
+    { "name": "luongnv89", "url": "https://github.com/luongnv89" },
+    { "name": "Rodrigo Manuel Jager Pinheiro", "url": "https://github.com/rodrigojager" },
+    { "name": "Gybra", "url": "https://github.com/Gybra" }
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Gybra/pi-opencode-cli-bridge.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Gybra/pi-opencode-cli-bridge/issues"
+  },
+  "homepage": "https://github.com/Gybra/pi-opencode-cli-bridge",
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.2.0",
+    "@earendil-works/pi-ai": "1.2.0",
+    "@types/node": "22.20.4",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}