@agentchatham/cli 2.28.0 → 2.30.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)
@@ -47,6 +52,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`)

package/README.md

@@ -53,8 +53,35 @@ 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 |