@kaiba-cloud/orbital-harness-pi 0.0.0-stage → 0.0.2

package/README.md

@@ -1,3 +1,122 @@
-# Temporary Holding Version
+# Orbital harness: Pi
 
-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.
+`@kaiba-cloud/orbital-harness-pi` runs the agents of an [Orbital](https://www.npmjs.com/package/@kaiba-cloud/orbital) team on the [Pi coding agent](https://www.npmjs.com/package/@mariozechner/pi-coding-agent).
+It is a harness plugin for the `harnesses` port of Orbital.
+It has the harness id `pi` and the harness folder `.pi`.
+
+Each turn runs Pi in the workspace of the session, on the model API of your provider key.
+Pi has its own tools `read`, `bash`, `edit` and `write`.
+The turn also gives Pi the orbital tools over MCP.
+
+The package is not a program of its own.
+It needs `@kaiba-cloud/orbital`, and Orbital runs it.
+
+## Install
+
+1. Install Orbital.
+
+   ```bash
+   npm i -g @kaiba-cloud/orbital
+   ```
+
+2. In your repository, install the harness.
+
+   ```bash
+   orbital install pi
+   ```
+
+   The command does these steps:
+
+   - It installs `@kaiba-cloud/orbital-harness-pi` at the version of Orbital in the plugin cache of the Orbital home.
+   - It writes `.pi/orbital.yaml` when the file is absent.
+   - It names the plugin in `.pi/orbital.yaml` as `npm:@kaiba-cloud/orbital-harness-pi@<version>`, so a clone of the project finds it.
+   - It prints a note that Pi reaches the orbital tools over MCP in each turn.
+
+   The install of this harness writes no other file.
+   A second run changes nothing.
+
+| Flag | Meaning |
+|---|---|
+| `--plugin <source>` | Take the adapter from this plugin: an npm package, a git URL or a folder. |
+| `--user` | Name the plugin in your user config, not in `.pi/orbital.yaml`. |
+| `--force` | Overwrite a file or a setting that Orbital did not write. |
+| `--workspace <path>` | The project. Default: the current directory. |
+
+## The provider key
+
+A Pi turn calls a model with your key.
+The agent names the model as `<provider>:<model>` in the `model:` key of its agent file.
+Store the key of that provider on the machine.
+Orbital asks for the key at a hidden prompt, or reads it from stdin.
+
+```bash
+orbital providers set anthropic
+```
+
+`orbital providers set` takes the providers `anthropic`, `openai`, `google` and `cloudflare`.
+
+- The turn finds the key by the provider in the model name.
+- Pi keeps the key in memory only.
+- The sandbox of the node lets the turn reach the host of that provider.
+- If the key is absent, the turn fails with the command that stores it.
+- If the agent has no model, or the model has no `<provider>:` part, the turn fails and names the form.
+- If Pi does not know the model, the turn fails with `Pi knows no model <provider>:<model>.`
+
+## An agent on Pi
+
+An agent file in `.pi/agents` runs on `pi` by default.
+Write the model in the file:
+
+```markdown
+---
+name: auditor
+description: Reads a change and reports the problems.
+model: anthropic:claude-sonnet-5-5
+---
+You audit a change in the workspace. You report each problem with its file and line.
+```
+
+## A team member on Pi
+
+A member of a team runs on the harness that its charter names.
+The charter is a harness folder file, such as `.claude/teams/review/CHARTER.md`.
+The member `auditor` runs on Pi, and the lead runs on Claude Code:
+
+```markdown
+---
+apiVersion: orbital/v1alpha1
+name: review
+objective: Review each change before it merges.
+lead: lead
+members:
+  - name: lead
+    harness: claude
+  - name: auditor
+    harness: pi
+---
+The lead hands each change to the auditor and reports the result.
+```
+
+The agent file of `auditor` can be in any harness folder of the project.
+An agent name is unique in a project.
+Run `orbital check` to check the team.
+
+## What the harness supports
+
+| Feature | Support |
+|---|---|
+| Transcript | Supported. Each answer of Pi is a text part. Each reasoning block is a thinking part, and Pi marks some as redacted: the harness drops those. Each tool call is a tool call part, and each tool result is a tool result part. |
+| Tools | Pi runs `read`, `bash`, `edit` and `write`. The orbital tools come from the MCP server that the turn gives, and each one is a Pi tool of the same name. An image in a tool result shows as `[image]`. |
+| Telemetry | Supported. Each turn reports, for each model, the input, output, cache read and cache write tokens, the cost that Pi reports, and the count of model calls. |
+| Resume | Supported. Pi writes its session files in the folder `pi` of the session folder. A later turn of the session continues the most recent file there. |
+| Stop | Supported. SIGTERM and SIGINT abort the Pi session, and the turn exits with code 143. |
+| Shared browser | Not supported. Pi has no browser tools. |
+| Skills | Not supported. The turn starts Pi with the loading of skills turned off. |
+
+## Known limits
+
+- A turn needs `model: <provider>:<model>` on the agent. Pi has no default model.
+- The turn turns off the retry of Pi. A failed model call fails the turn.
+- A turn that ends with a Pi error or an abort fails and gives the message of Pi as the reason.
+- The package pins `@mariozechner/pi-coding-agent` and `@mariozechner/pi-ai` at version 0.73.1.
+- The install of the harness connects nothing in the files of Pi. Each turn gives the orbital tools to Pi.