@tonbo/cli 0.0.6 → 0.1.0

package/README.md

@@ -7,41 +7,76 @@ 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. Sign in, then initialize the current directory interactively:
 
 ```console
+tonbo login
 tonbo init
-? Agent shape: [1] PI project  [2] PI Package project  [3] PI SDK app [1]:
-? Inference model [claude-sonnet-4-5]:
-Created .tonbo.
-Next: tonbo project create <slug>
+No Harness-specific configuration was found in this project.
+? Which supported Harness should Tonbo use?
+❯ PI (`pi`)  Run this project with the pi command.
+? How should this Agent connect to Tonbo?
+❯ Create a new project  Create it only after you confirm the complete configuration.
+  Use an existing project
+  Set up later
+? Project name [my-agent]:
+
+Tonbo Agent configuration:
+  Project:       Create my-agent in my-account (permanent address assigned after creation)
+  Harness:       PI
+  Execution:     PI CLI (`pi`)
+  Model:         claude-sonnet-4-5
+? Create project and .tonbo with this configuration?
+❯ Create project and .tonbo
+  Edit configuration  Change the project, Harness, execution mode, model, or SDK entrypoint.
+  Cancel
+Created project my-agent and .tonbo.
+Project: my-agent (my-agent-my-account.tonbo.sh)
+Organization: my-account
+Application: https://my-agent-my-account.tonbo.sh
+Harness: PI
+Mode: PI CLI
+Next: tonbo deploy
 ```
 
+Use the arrow keys and Enter to select a supported Harness and either create or select the one Project owned by this source tree. Project creation and file writes wait until the final review; cancelling leaves both local and cloud state unchanged. `AGENTS.md` is Harness-neutral and never identifies PI by itself. When `.pi/settings.json` exists, the shared source inspector identifies the PI Harness and reports its project-local packages. A regular PI project defaults to the native PI CLI; choose `Edit configuration` only when changing the Project, execution mode, model, or another setting. Unsupported and planned Harnesses are not shown.
+
 The generated `.tonbo` is TOML:
 
 ```toml
-version = 1
+# Tonbo Project Agent configuration.
+# Edit this file directly or run `tonbo init` to reconfigure.
+version = 2
+agent = "my-agent-my-account.tonbo.sh"
 
-[agent]
+[harness]
 runtime = "pi"
 
-[agent.driver]
+[harness.driver]
 kind = "native"
 
 [inference]
 model = "claude-sonnet-4-5"
 ```
 
-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:
+The immutable full Project hostname is the only durable Project authority in the source tree; it is not a credential. This keeps Projects with the same name in different Organizations unambiguous. `deploy`, `run`, `ssh` and `secret` refuse an unbound declaration. `tonbo project use <name-hostname-or-id>` accepts any convenient selector, resolves it through the signed-in account and writes the selected `project-organization.tonbo.sh` hostname into `.tonbo`; rebinding an existing declaration requires interactive confirmation or `--force`. UUIDs remain internal API identities and are never committed by the CLI.
+
+The default inference model is written without prompting. Override it explicitly with `--model`. Headless initialization makes Harness and driver choices explicit and may bind the resulting declaration with `project use`:
+
+```console
+tonbo init --harness pi --driver native
+tonbo init --harness pi --driver command --agent-entry dist/agent.mjs
+tonbo project use my-project-my-account.tonbo.sh
+```
+
+After interactive initialization, deploy the current contents:
 
 ```console
-tonbo login
-tonbo project create my-project
 tonbo deploy
 tonbo run "Reply with exactly READY."
 ```
 
-Use `tonbo project use my-project` instead when the Project already exists.
+Choose `Use an existing project` during `init` when the Project already exists. `tonbo project create <name>` and `tonbo project use <name-hostname-or-id>` remain explicit automation and recovery commands.
 
 `run` creates a durable Session and prints its ID in `--json` output. Pass that identity back to continue the same PI conversation:
 
@@ -49,23 +84,52 @@ Use `tonbo project use my-project` instead when the Project already exists.
 tonbo run --session 4d8e9501-... "Continue the previous task."
 ```
 
-Open the same singleton runtime and persistent `/workspace` interactively:
+Every `tonbo deploy` creates one immutable Deployment: the uploaded source, the `.tonbo` settings and the git provenance of the source root (commit, branch, subject, author and whether the tree was dirty) when the directory is inside a git work tree. Git is optional; without it the Deployment records `tonbo deploy` as its source. Deployments are named by their commit subject, or by their short id (the first eight hex characters) when there is no commit, and every command that takes a Deployment accepts any unambiguous id prefix. The Project's Production pointer names the one Deployment that serves its hostname; `deploy` moves Production to the new Deployment and prints the Deployment, its Production state and the exact standard OpenSSH command for the bound Project and its username:
 
 ```console
-tonbo ssh
+$ tonbo deploy
+Deployed project my-project.
+Organization: my-account
+Deployment: Fix greeting (0f3a7c21)
+Source: 0123456 · main
+Production: promoting (generation 4)
+Application: https://my-project-my-account.tonbo.sh
+
+Agent process: starts with the first turn and stays warm while the runtime is active.
+
+Start the Agent:
+  tonbo run "<prompt>"
+
+Connect with SSH:
+  ssh my-project.my-account@tonbo.sh
+```
+
+When the new Deployment has the same contents as the Production Deployment it replaces, `deploy` says so; the record is still created. `tonbo deploy --no-promote` creates the Deployment without moving Production, for example to stage a build and promote it later:
+
+```console
+tonbo deploy --no-promote
+tonbo deployments                      # ID  NAME  STATUS  PRODUCTION  SOURCE  CREATED  BY
+tonbo deployments show 0f3a7c21        # datasheet and Rollouts for one Deployment
+tonbo deployments promote 0f3a7c21     # move Production to a Deployment
+tonbo deployments rollback             # move Production back to the previous Production Deployment
+tonbo deployments rollback 9b8c1d22    # or to a named one
 ```
 
-`tonbo login` registers public keys found at the conventional `~/.ssh/id_ed25519.pub`, `id_ecdsa.pub` and `id_rsa.pub` paths. Register a key at another path with `tonbo ssh-key add <path.pub>` and revoke a lost or retired key with `tonbo ssh-key remove SHA256:...`. After that, the CLI is not part of the SSH connection; ordinary OpenSSH works directly:
+`tonbo deployments` (alias `tonbo deployments list`) marks the current Production Deployment with `●` and earlier ones with `○`; `STATUS` is the Deployment's relationship to Production: `current`, `promoting`, `failed`, `stopped`, `previous` or `none`. Promotion and rollback compare-and-swap the Production generation, so two people moving Production at once cannot silently overwrite each other; a conflict is reported and the command can be retried after checking `tonbo deployments`. `tonbo project show` prints the Production Deployment and its state alongside the Project addresses.
+
+Use `tonbo project show` to rediscover the username, application address and SSH command later. `tonbo login` registers public keys found at the conventional `~/.ssh/id_ed25519.pub`, `id_ecdsa.pub` and `id_rsa.pub` paths. Register a key at another path with `tonbo ssh-key add <path.pub>` and revoke a lost or retired key with `tonbo ssh-key remove SHA256:...`. The CLI is not part of the SSH connection; ordinary OpenSSH, `scp` and `rsync` connect directly:
 
 ```console
-ssh my-project@tonbo.sh
+ssh my-project.my-account@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 SSH user name is the Project qualified by its username; the signed public key identifies the Tonbo user and is checked against membership and IAM at connection time. The CLI resolves the Project name in `.tonbo` and prints the server-authoritative destination, so users never need to remember or assemble a username. 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.
+
+Deploy does not create a hidden Session just to prewarm PI. The first real `tonbo run` starts the Session-bound PI RPC process; successful Turns keep that process hot, including across native Session switches. The process is disposable cache rather than durable state: pause, replacement and uncertain failures remove it, and the next Turn restores authority from the durable Session JSONL.
 
 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.
+Deploy snapshots regular files under `.tonbo`, excluding `.git`, `node_modules`, PI package caches, local environment files and patterns in `.tonboignore`. Coding tools start in the persistent Artifacts workspace, while `AGENTS.md` and trusted `.pi` extensions, skills, prompts and settings load from the Deployment's uploaded source.
 
 ## Supported PI project shapes
 
@@ -76,14 +140,13 @@ Keep the normal PI project layout. Tonbo runs the same `AGENTS.md`, `.pi/APPEND_
 ```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. 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:
+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
@@ -96,16 +159,16 @@ Remote npm packages must use an exact version. Git packages must use a full 40-c
 
 ### 3. PI SDK app
 
-Choose `PI SDK app` in `tonbo init`, or declare a command driver directly:
+Choose `Edit configuration`, change `Execution mode` to `PI SDK app`, and confirm the resulting summary. In automation, use `--driver command --agent-entry <file>`, or declare a command driver directly:
 
 ```toml
-version = 1
+version = 2
 
-[agent]
+[harness]
 runtime = "pi"
 secrets = ["GITHUB_TOKEN"]
 
-[agent.driver]
+[harness.driver]
 kind = "command"
 protocol = "pi-rpc-v1"
 command = ["node", "dist/agent.mjs"]
@@ -119,11 +182,11 @@ model = "claude-sonnet-4-5"
 
 `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:
+For a non-interactive invocation, provide a current Tonbo CLI OAuth access token; the committed `.tonbo` supplies the only Project context:
 
 ```console
-TONBO_ACCESS_TOKEN=... tonbo --json deploy --project project-id
-TONBO_ACCESS_TOKEN=... tonbo --json run --project project-id "health check"
+TONBO_ACCESS_TOKEN=... tonbo --json deploy
+TONBO_ACCESS_TOKEN=... tonbo --json run "health check"
 ```
 
 Node.js 22 or newer is required. Human OAuth tokens are stored at `${XDG_CONFIG_HOME:-$HOME/.config}/tonbo/credentials.json`; the CLI atomically replaces that file with owner-only permissions and never writes it into an Agent directory.
@@ -131,6 +194,9 @@ 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)
+- [Project Deployments, Production and Rollouts](../../docs/design/project-deployments.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)