@agentchatham/cli 2.28.0 → 2.34.0

package/CLAUDE.md

@@ -19,10 +19,15 @@ boot paths:   up <inv> [agent_id]    → bindOrRegister (registration.ts) → bo
               agentchatham <dir>     → ensureIdentity (SDK) → bootAgent
 cli package:  src/cli/index.ts       — barrel (parseCliArgs + CliArgs/Command + run* handlers)
               src/cli/args.ts        — arg parsing
-              src/cli/commands.ts    — subcommand handlers (register/list/update/remove/info)
+              src/cli/commands.ts    — ALL subcommand handlers (register/list/update/remove/info,
+                                        setup-github/github-token/git-credential). One file: a
+                                        handler is `run<Command>`, and nothing else lives here
 register:     src/registration.ts    — bindOrRegister: idempotent register-or-bind for `up` (by agent_id)
               src/identity.ts        — findAgentDir: locate an agent dir by its `-<agent_id>` suffix
               src/bootstrap.ts       — runBootstrap stub for `-b` (image scripts; later phase)
+github:       src/github/setup.ts    — the GitHub integration; see "GitHub integration" below
+host tools:   pluginSetup.ts:run()   — the ONE child-process runner (git, claude, openclaw).
+                                        Exported for github/setup.ts; do not re-spawn by hand
 storage:      src/agentConfig.ts     — per-agent cli.json (read/writeAgentConfig: harness+mode); NO cli dep,
                                         so registration.ts reuses it without depending on cli/
 slash-cmds:   src/commands/          — agent in-chat slash-commands (distinct from cli/commands.ts)
@@ -30,6 +35,9 @@ errors:       src/errors/            — ErrorClass/TurnError vocabulary + forma
 abstraction:  src/provider.ts        — ProviderAgent / ProviderAdapter interfaces
 adapters:     src/providers/*/       — one per provider, implements ProviderAdapter
                                         <name>/errors.ts classifies that harness's failures
+                                        opencode/ drives `opencode serve` via @opencode-ai/sdk; the
+                                        model is `<provider>/<model>` and the provider key comes
+                                        from env (OPENROUTER_API_KEY), never from this repo
               src/providers/shared/  — prose + errno tables the classifiers fall back on
 loop:         src/dispatcher.ts      — buffer, retry, watermarks; private to /cli
 format:       src/prompts.ts         — formatters; input is ParsedNotification not raw events
@@ -47,6 +55,43 @@ infra:        src/lifecycle.ts       — shutdown choreography
 - WS loop: `monitorProvider` owns connect/reconnect. Never call `connectClient` directly.
 - Identity CRUD: `registerIdentity`, `loadIdentity` from SDK.
 
+## GitHub integration
+
+Agents never hold a long-lived GitHub credential. Every git operation mints a
+fresh, usually single-repo, ~1h installation token from the backend, which holds
+the org's GitHub App installation (agent_chatham `docs/plans/integrations.md`
+§3.2). Nothing is written to disk, ever.
+
+**The mint is the SDK's**, per §7 of that plan. Do not re-implement it here, and
+do not reach for `fetch` in this repo. The SDK exposes two doors and this repo
+uses the unusual one:
+
+- `githubTokenFromIdentity(dirName, {repositories})` — what these commands call.
+  REST, authenticating from `identity.json`, because the credential helper is a
+  fresh process per git operation with no live socket — and must not touch the
+  wrapping key / OS keyring for the same reason.
+- `githubToken(client, …)` — the socket path, and what the SDK's `github_token`
+  MCP tool calls. That is how a *harness* gets a token for `gh`; the CLI has no
+  client in these code paths.
+
+What remains here is genuinely CLI and lives in two places: `src/github/setup.ts`
+(the `git config` writes and the managed-boot hook), and `cli/commands.ts` — the
+three handlers plus git's credential protocol, private to the one handler that
+speaks it.
+
+Rules:
+
+- **The helper's stdout is the wire.** Anything printed there is parsed by git as
+  credential data, so failures log to stderr and exit 1 — never stdout.
+- **Silence is a valid answer.** A non-github.com host gets no output at all, so
+  git falls through to the user's own helpers. `store`/`erase` are no-ops.
+- **Scope is opt-in.** `setup-github` writes repo-local config by default; only
+  a managed VM, which is the agent's own host, gets `--global`.
+- **Boot does not reconfigure.** `maybeSetupGithub` asks git whether the helper
+  is already set and returns if it is: `up` runs on every VM start, and the git
+  config it writes is host state, not per-run state. Reconfiguring is explicit
+  (`agentchatham setup-github --global`).
+
 ## Adding a new provider
 
 1. Add name to the `Harness` union in `src/provider.ts` (and `VALID_HARNESSES`)
@@ -61,8 +106,10 @@ infra:        src/lifecycle.ts       — shutdown choreography
 ## Error classification
 
 Each harness classifies its own errors in `src/providers/<name>/errors.ts`, because
-the four share no error types: Claude has typed stream events, Cursor typed error
-subclasses, Codex and Gemini carry their cause as prose inside stream events.
+the harnesses share no error types: Claude has typed stream events, Cursor typed error
+subclasses, Codex and Gemini carry their cause as prose inside stream events, and
+OpenCode reports a tagged union on the assistant message whose `APIError` carries the
+upstream HTTP status.
 
 `src/errors/` holds what is common and nothing else:
 

package/README.md

@@ -53,13 +53,40 @@ The process runs in the foreground, streaming logs to stdout/stderr. `Ctrl-C` (o
 | `agentchatham update <dirName> <key>:<value>…` | Update agent config (e.g. `harness:claude`, `mode:cli`). |
 | `agentchatham rm <dirName>` | Remove an agent. |
 | `agentchatham ls` | List all registered agents. |
+| `agentchatham setup-github [<dirName>] [--global]` | Wire git to the org's GitHub integration (see below). Defaults to the current repo. |
+| `agentchatham github-token [<dirName>] [--repo <name>]…` | Mint a short-lived GitHub token and print it. `--repo` narrows it; repeatable. |
+| `agentchatham git-credential [<dirName>] <action>` | Git credential helper. Invoked by git, not by you. |
 | `agentchatham help` | Print usage. |
 
+Where `<dirName>` is optional it resolves the same way `agentchatham` with no arguments does: the `AGENT_CHATHAM_AGENT` binding, else the single registered agent.
+
+### GitHub
+
+The agent never holds a GitHub credential. `setup-github` points git's credential helper at the CLI, and from then on every `clone`/`fetch`/`push` against `github.com` mints a fresh, single-repo, ~1h installation token for that one operation — nothing is written to disk:
+
+```bash
+# Once per repo (or --global on a machine that is the agent's own):
+agentchatham setup-github
+
+git clone https://github.com/acme/widget.git   # just works; no PAT, no ssh key
+```
+
+It also sets `user.name` / `user.email` to the agent's identity, so its commits are attributed to the agent.
+
+`gh` and raw API calls don't read git credential helpers, so mint explicitly for those:
+
+```bash
+export GH_TOKEN=$(agentchatham github-token)
+gh pr create --fill
+```
+
+Both require an org admin to have connected GitHub on the Integrations page; until then they exit 1 saying so. Managed VMs run `setup-github --global` themselves on first boot.
+
 ### Options (for `up` and `register`)
 
 | Flag | Env | Description |
 |---|---|---|
-| `--harness <name>` | `AGENT_CHATHAM_HARNESS` | Harness: `codex`, `claude`, `cursor`, `gemini`. Default: `claude`. |
+| `--harness <name>` | `AGENT_CHATHAM_HARNESS` | Harness: `codex`, `claude`, `cursor`, `gemini`, `opencode`. Default: `claude`. |
 | `--model <name>` | `AGENT_CHATHAM_MODEL` | Model for the harness (e.g. `opus`, `sonnet`). Default: server-chosen. |
 | `--mode <name>` | `AGENT_CHATHAM_MODE` | Registration mode: `cli`, `plugin`. Default: `cli`. |
 | `--fn`, `--first-name <s>` | `AGENT_CHATHAM_FIRST_NAME` | Display first name. |
@@ -137,6 +164,16 @@ accessible only via paid Gemini and Gemini Enterprise Agent Platform API keys.
 
 To pick the model, set it at registration with `--model` (e.g. `--model gemini-2.5-pro`), same as any other harness.
 
+### OpenCode
+
+Install the binary (`npm install -g opencode-ai`) — the CLI drives it through `opencode serve`.
+OpenCode is a multi-provider harness; the model names the provider too: `--model openrouter/anthropic/claude-sonnet-4.6`
+(the default). The provider's key is read from the environment by OpenCode itself; for OpenRouter set
+`OPENROUTER_API_KEY` (get one at https://openrouter.ai/keys).
+
+The agent runs with a private OpenCode config (`OPENCODE_CONFIG_DIR` points at a temp dir): your own
+`~/.config/opencode/opencode.json` — MCP servers, agents, keybinds — is not applied to it.
+
 ## Local development
 
 ```bash
@@ -189,7 +226,7 @@ Covers dispatcher concurrency (buffer, FIFO serialisation, abort, retry, backfil
 │  WS client ◀──── @agentchatham/sdk (monitorProvider) ────▶ server     │
 │      │                                                                 │
 │      ▼  ParsedNotification                                             │
-│  Dispatcher  ──▶  ProviderAgent  (codex | claude | cursor | gemini)   │
+│  Dispatcher  ──▶  ProviderAgent  (codex|claude|cursor|gemini|opencode)│
 │  (buffer,         (one instance                                        │
 │   retry,           per daemon)                                         │
 │   watermarks)           │                                              │