@tonbo/cli 0.0.5 → 0.0.7

package/README.md

@@ -7,32 +7,44 @@ npm install --global @tonbo/cli
 tonbo --version
 ```
 
-The V1 CLI deploys a PI-based Agent directly from a local directory without requiring Git or Tonbo calls in the Agent source. Initialize the current directory interactively:
+The CLI deploys an Agent directly from a local directory without requiring Git or Tonbo calls in the Agent source. Initialize the current directory interactively:
 
 ```console
 tonbo init
-? Inference model [claude-sonnet-4-5]:
+? How should Tonbo run this project?
+❯ PI CLI (`pi`)  Run pi directly with AGENTS.md and optional project-local .pi resources.
+  PI SDK app     Run a custom Node.js entrypoint built on the PI SDK.
 Created .tonbo.
+Harness: PI
+Mode: PI CLI
 Next: tonbo project create <slug>
 ```
 
+Use the arrow keys to select an available execution target and Enter to confirm. `AGENTS.md` is Harness-neutral and never identifies PI by itself. When `.pi/settings.json` exists, the shared source inspector identifies the PI Harness, reports its project-local packages, and narrows the prompt to the native PI or PI SDK execution modes. Unsupported and planned Harnesses are not shown.
+
 The generated `.tonbo` is TOML:
 
 ```toml
 version = 1
 
-[execution]
-mode = "managed"
+[agent]
 runtime = "pi"
 
+[agent.driver]
+kind = "native"
+
 [inference]
 model = "claude-sonnet-4-5"
+```
 
-[session_capture]
-adapter = "pi-jsonl-v3"
+The default inference model is written without prompting. Override it explicitly with `--model`. Automation must make ambiguous choices explicit; an existing declaration requires interactive confirmation or `--force`:
+
+```console
+tonbo init --harness pi --driver native
+tonbo init --harness pi --driver command --agent-entry dist/agent.mjs
 ```
 
-For automation, use `tonbo init --model <model>`; an existing declaration requires interactive confirmation or `--force`. Then authenticate, bind the directory and deploy its current contents:
+Then authenticate, bind the directory and deploy its current contents:
 
 ```console
 tonbo login
@@ -63,9 +75,61 @@ ssh my-project@tonbo.sh
 
 The SSH username selects the globally unique Project; the signed public key identifies the Tonbo user and is checked against Project membership and IAM at connection time. The shell and HTTP turns may coexist on the singleton runtime, allowing the shell to observe the Agent while it works. Session writer fencing protects durable conversation history; ordinary workspace files retain Linux process concurrency semantics.
 
-The platform injects scoped inference access and the managed PI runtime writes the declared session format through the session-aware filesystem. Do not put a model-provider API key or a Tonbo credential in `.tonbo`.
+The platform injects scoped inference access and owns PI Session capture. Do not put a model-provider API key or a Tonbo credential in `.tonbo`.
+
+Deploy snapshots regular files under `.tonbo`, excluding `.git`, `node_modules`, PI package caches, local environment files and patterns in `.tonboignore`. Equal contents produce the same revision. Coding tools start in the persistent Artifacts workspace, while `AGENTS.md` and trusted `.pi` extensions, skills, prompts and settings load from the uploaded revision.
+
+## Supported PI project shapes
+
+### 1. Project-local Agent
+
+Keep the normal PI project layout. Tonbo runs the same `AGENTS.md`, `.pi/APPEND_SYSTEM.md`, `.pi/settings.json`, `.pi/extensions`, `.pi/skills` and `.pi/prompts` that local `pi` loads:
+
+```console
+pi
+tonbo init
+tonbo project create my-agent
+tonbo deploy
+tonbo run "Start the task."
+```
+
+### 2. PI Package project
+
+Use PI's project-local package declaration as the single source of truth. A package is a PI resource, not another Tonbo execution mode: `tonbo init` recognizes `.pi/settings.json`, then the native PI driver loads the packages. Install an immutable package reference locally, verify it with PI, and deploy the project; Tonbo excludes `.pi/npm` and `.pi/git` caches and restores packages inside the isolated runtime:
+
+```console
+pi install -l npm:@acme/my-pi-agent@1.2.3
+pi
+tonbo init
+tonbo deploy
+```
+
+Remote npm packages must use an exact version. Git packages must use a full 40-character commit, for example `git:github.com/acme/my-pi-agent@0123456789abcdef0123456789abcdef01234567`. Movable tags, branches, ranges and `latest` fail deployment.
+
+### 3. PI SDK app
+
+Choose `PI SDK app` with the arrow selector, use `--driver command --agent-entry <file>` in automation, or declare a command driver directly:
+
+```toml
+version = 1
+
+[agent]
+runtime = "pi"
+secrets = ["GITHUB_TOKEN"]
+
+[agent.driver]
+kind = "command"
+protocol = "pi-rpc-v1"
+command = ["node", "dist/agent.mjs"]
+
+[build]
+command = ["npm", "run", "build"]
+
+[inference]
+model = "claude-sonnet-4-5"
+```
 
-Deploy snapshots regular files under `.tonbo`, excluding `.git`, `node_modules`, local environment files and patterns in `.tonboignore`. Equal contents produce the same revision. Coding tools start in the persistent Artifacts workspace, while `.pi` extensions, skills and prompts load from the uploaded revision.
+`tonbo deploy` runs the build command before creating the source snapshot. The entrypoint must keep stdout exclusively for PI RPC and send logs to stderr. It receives `PI_CODING_AGENT_MODULE`, `PI_CODING_AGENT_DIR`, `PI_CODING_AGENT_SESSION_DIR`, `TONBO_PI_SESSION_FILE`, `TONBO_PI_SESSION_ID`, `TONBO_PI_PROVIDER`, `TONBO_PI_MODEL` and `TONBO_PI_RPC_PROTOCOL`. Load the platform PI SDK from `PI_CODING_AGENT_MODULE`, open `TONBO_PI_SESSION_FILE`, create an `AgentSessionRuntime`, and pass it to `runRpcMode()`. This lets the app customize tools and runtime services without forking PI while preserving Tonbo's durable Session and Turn protocol.
 
 For a non-interactive invocation, provide a current Tonbo CLI OAuth access token and an explicit Project:
 
@@ -79,6 +143,8 @@ Node.js 22 or newer is required. Human OAuth tokens are stored at `${XDG_CONFIG_
 ## Related design
 
 - [Design documentation map](../../docs/design/README.md)
+- [Agent source inspection and onboarding](../../docs/design/agent-source-onboarding.md)
+- [Shared source inspector](../../packages/agent-source-inspector/README.md)
 - [Project resource model](../../docs/design/project-resource-model.md)
 - [ADR-0008: Tonbo CLI onboarding and credential boundaries](../../apps/user-center/docs/decisions/adr-0008-tonbo-cli-onboarding.md)
 - [Management API v1](../../contracts/management/openapi-v1.yaml)