feat(cli): add --setup and offer it to ACP clients as a terminal login - #46

…t status on model errors

Two things that a run with an empty home showed.

1. A configuration that sets no model falls back to the provider "mock". LangChain has no such
   provider, so the turn failed with the text of a missing package ("init_chat_model ... pip
   install langchain"), and that sends the user the wrong way. `default_stream_fn()` now answers
   a model of the provider "mock" with an error event that says "No model is set. Run the agent
   with --setup, or add a [model] table to <agent.toml>." The scripted test LLM
   (PI_USE_MOCK=1) and the real providers are not touched; they take the same way as before.
2. `-p` printed an empty line and exited 0 when the model request failed, so a script could not
   tell a failure from an empty answer. `run_print` now writes `error: <reason>` to stderr and
   exits 1. Stdout still gets the text of an answer that came before the error, and nothing else.

- config.py: `no_model_message()`, one text for both paths.
- factory.py: `_say_when_no_model` wraps the LangChain stream function; `_error_stream` builds
  the stream of one error event the way a stream function must (it never raises).
- headless.py: the exit status and the stderr line.
- test_first_run_errors.py: 6 tests; the mock provider gets the message, a real provider still
  reaches the LangChain adapter, the scripted LLM is not touched, an ACP prompt shows
  "Error: <message>", `run_print` returns 1 with an empty stdout, and `python -m pi_agent_cli -p`
  exits 1 in a subprocess.

Checked:
- 4 of the 6 new tests fail on the code before this change, and all 6 pass with it.
- The tests that call `run_print` or `default_stream_fn()` (headless, headless trust, project
  resource trust, extension trust and notices, print shutdown, model reasoning, factory skills,
  and the new file): Windows 132 passed, 15 skipped (POSIX only); Linux (WSL) 146 passed,
  1 skipped.
- Ruff check and format check pass for the package.

…o it

An ACP client that can run a terminal login (Zed can) shows the authentication methods of an
agent when `session/new` fails with `auth_required`. The agent had `authMethods: []`, so a user
without a model or a key got a chat error and no way to fix it from the client. Now such a
client is offered `pi-agent-cli --setup`, and a new session that could not work is answered with
`auth_required`.

What a client announces decides the form of the method (auth_methods.py):
- `clientCapabilities.auth.terminal = true` (Zed declares it): a method of type `terminal`. The
  client runs the command that started the agent with `args` (`--setup`) added to it.
- only `_meta["terminal-auth"] = true` (older clients, and the registry validator): a method of
  the default type with `_meta["terminal-auth"]` = the command (`sys.executable -m
  pi_agent_cli --setup`) and `PI_HOME`, because the terminal has not the environment that the
  agent was started with.
- neither (the TUI zypi is one of these): `authMethods` stays `[]` and a new session opens as
  before; the first turn says what is missing (the previous commit).

agent.py:
- `initialize`: the method, as above. `authenticate` accepts the method id once the files are
  usable, answers `auth_required` while they are not, and `invalid_params` for any other id.
- `session/new`: when no model is set, or the variable named by `api_key_env` (and the variable
  that the provider's SDK reads, for openai, anthropic and deepseek) has no value, a client that
  can run the login gets `auth_required` (code -32000, a message that says what is missing and
  names the method), and no session is made. Other clients get their session.
- The agent reads `agent.toml` and `local.env` again at `session/new`, `session/load` and
  `session/resume`, but only while what it has cannot run a turn: `--setup` runs in the client's
  terminal while this process is up. A working configuration is never read again under a
  running agent. `session/load` and `session/resume` never refuse, because old history can be
  read without a model.
- Only an agent that reads its settings from the files offers this. A program that gives its own
  `config` or `stream_fn` (the tests, an embedding) is left alone.

config.py: `config_problem()` says why a configuration cannot run a turn (no network; the
scripted LLM `PI_USE_MOCK=1` has no problem), and `STANDARD_KEY_ENV`, which setup_command.py
uses for its default variable names too.

Checked:
- 32 new tests in test_acp_auth_methods.py: the form for each announcement (Zed, first class
  only, the registry validator, zypi, nothing, wrong values), the raw JSON of the `initialize`
  answer over stdio (the SDK drops an invalid item of `authMethods` without a word: a plain
  `AuthMethodTerminal` has no `type` and is not on the wire; this test fails on it), the gate of
  `session/new`, the read-again after `--setup`, `authenticate`, and `config_problem`.
- 11 mutations (plain terminal method, no capability gate, no PI_HOME in the legacy command, the
  wrong error code, `authenticate` for any id, `session/new` without the error, no read-again,
  always read again, `resume` that refuses, always offering, the provider's own variable
  ignored) are all caught.
- One live agent process, played as Zed would (Linux, pseudo-terminal): `initialize` answers one
  terminal method; `session/new` on an empty home answers -32000; the agent command with the
  method's `args` runs the dialog and exits 0; `session/new` on the same process gives a
  session whose model option is the model just saved; `authenticate` answers `{}`. This was not
  run inside Zed.
- The tests of the whole package pi-agent-cli: Windows 884 passed, 29 skipped; Linux (WSL) 910
  passed, 3 skipped.
- Ruff check and format check pass for the package.

…Es, changelog)

The three commits before this one add `--setup`, the terminal login in `initialize`, and two
fixes for a first run. This commit writes down what they do, why, and what was not checked.

- docs/specs/2026-10-28-acp-terminal-auth-setup-design.md: the problem, the facts that the
  design rests on (Zed adds the `args` of a terminal method to the agent command and does not
  call `authenticate` for it; the registry text says "replace"; the SDK drops an invalid item
  of `authMethods`; `zypi` announces no `auth` and must keep getting `[]`), the dialog, the two
  forms of the method, the gate and the read-again, the two fixes, the choices that were not
  taken, what was verified, and what was not (nothing was run inside Zed).
- packages/pi-agent-cli/AGENTS.md: the section "First run: `--setup` and the terminal login",
  two rows in the mode table, and rows for `setup_command.py` and `auth_methods.py`.
- AGENTS.md: the `pi-agent-cli` row points to the same topic.
- README.md and packages/pi-agent-cli/README.md: the first-run step for Zed, the command to run
  the dialog in a shell, and the way to set up by hand.
- agent.example.toml: a comment that `--setup` writes the `[model]` table and the key.
- CHANGELOG.md, Unreleased: Added `--setup` and the terminal login; Fixed the first-turn text
  and the exit status of `-p` (the second one is a behavior change for a script that read 0).

Checked:
- Every statement about the dialog and the gate was compared with the code of
  setup_command.py and agent.py (states, refusals, file handling, `authenticate`).
- The test counts in the spec match `pytest --collect-only` (40 + 32 + 6 = 78, and 2 more in
  test_config.py).
- What `zypi` announces was read in tui/crates/codegen/pi-pager/src/acp/mod.rs
  (`ClientCapabilities::new()` with `fs` and `terminal`, an empty `_meta`, no `auth`).
- Ruff check and format check pass for the whole repository. Only documentation changed in
  this commit, so no tests were run for it.