@primusclaw/connector 0.1.5 → 0.1.6

package/README.md

@@ -41,10 +41,10 @@ If npm answers `EACCES`, point its global prefix at a directory you own (`npm co
 ```sh
 claw-connector init      # writes agents.toml and prints where: ~/.config/claw-connector/agents.toml unless XDG_CONFIG_HOME or CLAW_CONNECTOR_HOME is set
 claw-connector status    # after you edit it: prints a "problem:" line if the file is wrong
-claw-connector doctor    # starts each agent's adapter, opens a session (no prompt) and checks the modes it offers
+claw-connector doctor    # checks the machine (step 5), then starts each agent's adapter, opens a session (no prompt) and checks the modes it offers
 ```
 
-`init` runs the same check as `doctor` at the end. `doctor` says `ok` for an agent whose phone sessions will open, and otherwise a
+`init` runs the adapter check of `doctor` at the end. `doctor` says `ok` for an agent whose phone sessions will open, and otherwise a
 `problem:` line with the fix, for example an agent whose sessions would be refused with `mode_unavailable`.
 
 By default every agent asks before it writes a file or runs a command, and your phone answers each question. To let phone sessions run
@@ -88,13 +88,32 @@ Only `claw-connector stop` (or stopping the service) stops it for good: a `kill`
 with exit 75, and it is started again.
 It uses `systemd --user` on Linux and launchd on macOS. On Linux, run `loginctl enable-linger $USER` once (`service install` says so
 when it is needed) so it also runs while you are logged out. In a container without systemd, `service install` starts a small
-supervisor and writes `keepalive.sh`; have the container's startup command and a 5-minute cron job run that script (it does nothing
-when the supervisor is up) so a restarted container comes back by itself. See [Keeping it running](#keeping-it-running).
+supervisor, writes `keepalive.sh` and adds it to your crontab when a cron daemon runs; when none does it says so, and the container's
+startup command must run that script (it does nothing when the supervisor is up) for a restarted container to come back. Keys the
+agents read from your shell (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`...) are kept for the service in a 0600 file, never in the unit.
+See [Keeping it running](#keeping-it-running).
 
 To try it in the foreground instead, `claw-connector run` prints `connecting claude to https://claw.example.com/claw-api as
 "<machine name>"` and stays up until Ctrl-C, which stops it and every agent it started.
 
-**5. See it in Clawy**
+**5. Check the machine**
+
+```sh
+claw-connector doctor
+```
+
+`doctor` checks what makes a first phone session fail far from the machine that caused it, and prints one fix per problem:
+Node.js 22 or newer; each agent's program on `PATH` (and on the `PATH` the installed service starts it with, which is not your
+shell's); whether Claude Code and Codex are signed in (`claude auth status`, `codex login status`, or the model provider's key
+variable in `~/.codex/config.toml`); the `roots` writable; `HTTPS_PROXY` and `https_proxy` not set to different values; a service
+installed (and, for `keepalive.sh`, something calling it); and Claw answering, including whether Node.js trusts its certificate
+(Node does not read the system's CA store by default: behind a company CA set `NODE_USE_SYSTEM_CA=1` or `NODE_EXTRA_CA_CERTS`). Then it
+runs the adapter check of step 2. It exits 1 when something will stop sessions (`--json`: `ok` is the adapters' verdict,
+`machine_ok` and `environment` the machine's). The
+running connector repeats the machine checks with its own environment (in a child process, so a stalled disk cannot stall
+it) every 15 minutes, and at once when `doctor` runs (it signals the connector), and Clawy's `/agents` card shows what it found under the machine ("Codex is not signed in: run `codex login` on that machine").
+
+**6. See it in Clawy**
 
 In Clawy (or any chat client built on Claw), send `/agents`. The agents of this machine are listed, online while `run` is up.
 A session started there runs on this machine, inside one of your `roots`, and each permission request comes back as a card in the chat.
@@ -122,7 +141,9 @@ id = "codex"
 preset = "codex"
 roots = ["~/work/repo-a", "~/work/repo-b"]
 [agents.env]                       # passed to the adapter; the model settings live here, never in Claw
-OPENAI_API_KEY = "..."             # or leave your own environment / CODEX_HOME to supply it
+OPENAI_API_KEY = "..."             # or leave your own environment / CODEX_HOME to supply it; with only a key, the
+                                   # connector signs Codex in with it (Codex keeps it in its auth.json, like
+                                   # "codex login --with-api-key")
 
 [[agents]]
 id = "mine"
@@ -155,7 +176,10 @@ connector's state directory, and the install is tried again in the background te
 `claude-attach` does not start new conversations: it takes over Claude Code conversations that already exist on this
 machine (see [Taking over an existing conversation](#taking-over-an-existing-conversation)).
 
-An agent with no `roots` is never offered. A configuration problem is reported at start-up, not skipped.
+An agent with no `roots` is never offered. A configuration problem is reported at start-up, not skipped. A root that does
+not exist, or whose disk does not answer (a network mount that is down or not mounted yet), is not a configuration problem:
+`run` warns about it and keeps going, and that root's sessions are refused (`cwd_not_found`, `root_unavailable`) until it is
+back. Reading `agents.toml` never touches a root.
 
 ## Running without per-step approval
 
@@ -222,7 +246,24 @@ All of these run on your machine and fail closed.
 
 - **Directories.** A session's working directory is resolved (symlinks included) and must be inside one of the agent's
   `roots`; otherwise no process is started and the session is closed with `cwd_outside_roots`. The agent runs in the
-  resolved path.
+  resolved path. A folder can be given the way people type it: `~` and `~/x` are the agent's home directory (its
+  `[agents.env]` `HOME`, else the connector's), and a relative name (`repo`, `repo/sub`) is looked up under each root and
+  taken when exactly one has it (`cwd_ambiguous` when several do); a root's own last segment names that root. A relative
+  name never climbs out (`..`). Every look at the disk on the way to opening a session is asynchronous with a 10-second
+  limit, so a root on a stalled network mount refuses its own sessions (`root_unavailable`), never those under a healthy
+  root, and never freezes the connector or its heartbeat. A restored session whose root does not answer is kept: its
+  commands are rejected `root_unavailable` until it does, and `close` still closes it.
+- **Signed in before ready.** A new session of an agent that reports its sign-in (Claude Code does) and reports none is
+  refused at once with `agent_auth_required`, instead of opening and failing at its first message; a session that
+  already exists is kept and its prompts say why. A prompt refused for the same reason later
+  (an expired login) ends its turn with `error: "agent_auth_required"` and the fix, and the next prompt starts the agent
+  afresh, so a sign-in done on the machine meanwhile is picked up. An adapter that needs a sign-in and offers an
+  `api-key` method (Codex) is told to `authenticate` with it when its environment has `OPENAI_API_KEY` or `CODEX_API_KEY`;
+  the key itself is never sent, the adapter reads its own environment.
+- **Why, in one sentence.** Every refusal (`session_closed`, `command_rejected`, and a `turn_end` that failed for a known
+  reason) carries its stable `reason` code and a `hint`: one English sentence of what to do about it (sign in with which
+  command, which folder to pick, `claw-connector doctor`), with no path and nothing secret, for a client to show beside
+  its own translation of the code.
 - **Ask mode, read back.** After the adapter creates a session, the connector sets the agent's ask mode and reads the
   mode back from the adapter. Your own agent settings may start an adapter in a mode that never asks (bypass, full
   access); an adapter that does not confirm the ask mode, or that warns it will not invoke its permission callback, is
@@ -242,6 +283,9 @@ All of these run on your machine and fail closed.
   which cannot write. `approval = "never"` selects `agent` and starts `agent --force acp` (`--force` is a root flag of the
   Cursor CLI, "force allow commands unless explicitly denied"; it is accepted before or after `acp`). Cursor
   has no `session/resume`; the connector uses `session/load` and marks the replayed history `replay: true`.
+  A Cursor agent that asks therefore answers and plans but changes no file: its capabilities say `edits: false` with an
+  `edits_hint`, `read_only_modes` lists `ask` and `plan` (each such mode in `session_started` carries `read_only: true`),
+  `run` prints a note, and the sample `agents.toml` says so above the Cursor block.
 - **Permissions.** Each permission request becomes a card with the options **the adapter offered**, passed through with
   their own ids and kinds (`allow_once`, `allow_always`, `reject_once`). An answer must be one of those ids; any other is refused
   and the request stays open. An unanswered request is answered `cancelled` after 10 minutes, and a cancel,
@@ -371,6 +415,7 @@ session stops the agent process; it never deletes the conversation.
 | `run [--supervised]` | Connect and serve. Exit code 78 means starting it again will not help: the connector was revoked, Claw or the identity service refused the sign-in (at start, or for two minutes in a row while running), or there is no usable `agents.toml` or sign-in; the reason is kept in `needs-login.json`, and until `login` removes it `run` exits 78 at once without contacting Claw. `--supervised` marks a run the service started. Any other non-zero exit is worth a restart. A unit written by hand for 0.1.2 and older (`RestartPreventExitStatus=3`): replace it with `claw-connector service install`, which writes the same file. |
 | `service install\|uninstall\|status [--supervisor systemd\|launchd\|script] [--env NAME ...]` | Keep `run` up (see [Keeping it running](#keeping-it-running)). `install` stops a `run` started by hand so the service takes over; `status` also lists the last five disconnects and why. |
 | `status [--json]` | Running or not, paused, signed in, agents, adapter processes, the last disconnect and its reason (`last down:`), a `problem:` line when a new sign-in is needed, and a `warning:` line for each agent whose sessions will be refused because Claude's own settings default to `bypassPermissions` (see [Running without per-step approval](#running-without-per-step-approval)). |
+| `doctor [--agent ID] [--json]` | Check this machine and print one fix per problem (see step 5 of the quick start), then each agent's adapter (step 2); exit 1 when something stops sessions. The report is kept in `doctor.json`; a running connector is signalled to check again and sends what it finds to Claw (each agent's `capabilities.health`). |
 | `pause` / `resume` | Stop every agent within a second and stay offline, or undo that. |
 | `stop` | Stop the running connector and every agent it started. |
 | `logout` | Stop, revoke this machine's connector at Claw (with a key, `DELETE /v1/remote-agents/connectors/:cid`; with a device sign-in, the connector-side `POST .../connectors/:cid/revoke`), ask the identity service to revoke the sign-in, and delete it from this machine. The next sign-in registers a new connector. When Claw cannot be reached or refuses (a Claw from before the connector-side route refuses a device sign-in), the sign-in is still deleted, but `logout` says the connector was not revoked, prints the `curl` that revokes it with a Claw API key of yours, keeps its id (so a later sign-in reuses it), and exits 1. |
@@ -383,12 +428,12 @@ the connector sees it within a heartbeat, stops every agent and exits without re
 
 ## Files
 
-`~/.config/claw-connector/` (or `$XDG_CONFIG_HOME/claw-connector/`): `agents.toml`, `credentials.json` (0600; a file other users can read is
-refused). `~/.local/state/claw-connector/` (or `$XDG_STATE_HOME/claw-connector/`): `connector.json` (the connector's identity and the
+`~/.config/claw-connector/` (or `$XDG_CONFIG_HOME/claw-connector/`, or `$CLAW_CONNECTOR_CONFIG_DIR`): `agents.toml`, `credentials.json`
+(0600; a file other users can read is refused), and `service-env.json` (0600, the agents' sign-in variables `service install` kept). `~/.local/state/claw-connector/` (or `$XDG_STATE_HOME/claw-connector/`): `connector.json` (the connector's identity and the
 commands handled), `sessions.json`, `outbox/` (events not yet acknowledged by Claw), `audit.jsonl` (spawn, directory
 decisions, every command received, every permission request and answer, every automatic approval, mode changes),
-`logs/`, `children.json`, `connector.pid`, `disconnects.jsonl`, `needs-login.json` (only after a run that needs a new sign-in), and with
-the script supervisor `supervisor.pid`, `keepalive.sh` and `run.log`. `CLAW_CONNECTOR_HOME=/some/dir` keeps all of it under one directory.
+`logs/`, `children.json`, `connector.pid`, `disconnects.jsonl`, `needs-login.json` (only after a run that needs a new sign-in), `doctor.json`
+(the last `doctor` report), and with the script supervisor `supervisor.pid`, `keepalive.sh`, `keepalive-last` (when it last ran) and `run.log`. `CLAW_CONNECTOR_HOME=/some/dir` keeps all of it under one directory.
 
 ## Keeping it running
 
@@ -401,32 +446,68 @@ the script supervisor `supervisor.pid`, `keepalive.sh` and `run.log`. `CLAW_CONN
   Log: `run.log` in the state directory.
 - **script** (a container without systemd; an `systemctl` that answers "Running in chroot" counts as none): `claw-connector supervise`
   runs in the background and restarts the connector 5 seconds after it dies; `keepalive.sh` in the state directory starts that
-  supervisor unless it is alive (recorded pid and start time) or a sign-in is needed. Nothing restarts the supervisor after the container
-  restarts, so call `keepalive.sh` from the container's startup command and from a 5-minute cron job. Log: `run.log`.
+  supervisor unless it is alive (recorded pid and start time) or a sign-in is needed. Where a cron daemon runs, `install` adds an
+  `@reboot` and a 5-minute line that call `keepalive.sh` to your crontab (once; `uninstall` removes them). Where none runs (most
+  containers), `install` says so: nothing brings the connector back after a restart until the container's startup command (or
+  `~/.bashrc`) runs `sh keepalive.sh`. Log: `run.log`.
+
+**A container whose home directory does not outlive it** (a dev pod): when `agents.toml` and the sign-in sit on the container's own
+file system (overlay, tmpfs), `init` and `service install` say so. Keep them on storage that survives the container with
+`CLAW_CONNECTOR_CONFIG_DIR=/mnt/<your persistent volume>/claw-connector` (only the configuration and sign-in move; pid files, the outbox
+and logs stay on the local disk), set in your shell profile and in the container's startup command, which then runs
+`claw-connector service ensure` (after installing the package again, if it lived on the container's file system too).
 
 A successful `login` starts an installed service again, so after a revocation or a refused key signing in is the whole fix.
 `keepalive.sh` and the script supervisor start nothing while only a person can help (no `agents.toml`, not signed in,
 `needs-login.json`); under launchd every exit 78 is turned into a clean exit, which launchd does not restart. The service
 installed for a state directory is recorded in its `service.json`.
 
-The unit carries `PATH` (so the agents are found), `CLAW_CONNECTOR_HOME`, `XDG_CONFIG_HOME`, `XDG_STATE_HOME`, `CLAUDE_CONFIG_DIR`,
-`CODEX_HOME`, the CA and proxy variables and `LANG` from the shell that ran `install` (a proxy URL with a password in it only when named with `--env`, e.g. `--env HTTPS_PROXY`); `--env NAME` adds another, except a name that looks
-like a credential (`KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `CREDENTIAL`), which is never written into a unit. Run `install` again after
-changing any of them, or after moving Node. With a service installed, `claw-connector stop` stops the connector until the next login,
+The unit carries `PATH` (so the agents are found), `CLAW_CONNECTOR_HOME`, `CLAW_CONNECTOR_CONFIG_DIR`, `XDG_CONFIG_HOME`, `XDG_STATE_HOME`,
+`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, the CA and proxy variables (with `NODE_USE_SYSTEM_CA` and `NODE_USE_ENV_PROXY`), `LANG`, `IS_SANDBOX`, the npm registry and proxy settings, and every
+plain setting of the agents (`ANTHROPIC_*`, `CLAUDE_CODE_*`, `OPENAI_*`, `CODEX_*`, `CURSOR_*` that is not named like a credential:
+`ANTHROPIC_BASE_URL`, `ANTHROPIC_MODEL`, `CLAUDE_CODE_USE_BEDROCK`...) from the shell that ran `install` (a proxy URL with a password in
+it only when named with `--env`, e.g. `--env HTTPS_PROXY`); `--env NAME` adds another.
+
+The agents' own sign-in variables are never written into a unit. When the shell that runs `install` has `ANTHROPIC_API_KEY`,
+`ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_CUSTOM_HEADERS`, `OPENAI_API_KEY`, `CODEX_API_KEY`, `CURSOR_API_KEY`, the
+AWS keys, a variable Codex's `config.toml` names as a provider's `env_key`, or an `--env` name that looks like a credential (`KEY`,
+`TOKEN`, `SECRET`, `PASSWORD`, `CREDENTIAL`), they are kept in `service-env.json` beside `credentials.json` (mode 0600) and every `run`
+gives them to the agents that do not set them in `[agents.env]` (a configuration directory its group or others may write is first made 0700; one owned by another account is refused). `install` prints their names, never their values; `service status`
+lists them; `uninstall` deletes the file. Without this a connector that works in a terminal loses its agents' sign-in as a service,
+and each session fails at its first message. `CLAW_CONNECTOR_KEY` is never copied. Run `install` again after changing any of them, or
+after moving Node. With a service installed, `claw-connector stop` stops the connector until the next login,
 boot or keep-alive check; to stay offline use `pause`, or `service uninstall`.
 
 **Why it went down.** Every disconnect is appended to `disconnects.jsonl` in the state directory: `server_closed` (a Claw release or
 restart, `superseded` by another run, `token_expired`; reconnected at once), `stream_lost` (the network, with the error), `stopped`,
-`revoked`, `auth_failed`, `failed`, and `process_died` (the previous run never shut down: killed, crashed or the machine restarted;
-dated by its last heartbeat). `status` shows the latest, `service status` the last five.
+`revoked`, `auth_failed`, `failed`, `process_died` (the previous run never shut down: killed, crashed or the machine restarted;
+dated by its last heartbeat), and `connector_limit_reached` (Claw already holds the most connectors one person may have: remove a
+machine you no longer use, in the chat with `/agents` or with `claw-connector logout` on it; the run stays up and tries again every 10
+minutes instead of being restarted every 5 seconds). `status` shows the latest, `service status` the last five.
 
 ## Restarts and crashes
 
-A prompt counts as handled only when it reaches the agent (or is dropped by a cancel, a close or a stop), so a connector that
-dies with a prompt still queued is sent that prompt again by Claw instead of losing it. A permission request waiting
-for an answer lives in the adapter, which dies with the connector: the next run closes such a card (`cancelled`, by
-`connector_restart`), so a phone is not left with a button that does nothing. Session state, unacknowledged events and
-their sequence numbers are on disk; a session resumes in a fresh adapter on its next prompt.
+A prompt counts as handled only when it reaches the agent (or is dropped by a cancel or a close), so a connector that
+dies, or is stopped or restarted by its supervisor, with a prompt still queued is sent that prompt again by Claw instead of
+losing it. A permission request waiting for an answer lives in the adapter, which dies with the connector: the next run
+closes such a card (`cancelled`, by `connector_restart`), so a phone is not left with a button that does nothing. Session
+state, unacknowledged events and their sequence numbers are on disk; a session resumes in a fresh adapter on its next prompt
+(Claude Code's `session/resume`, the conversation intact).
+
+The turn an agent is running is on disk too, from the moment its prompt reaches the agent until its `turn_end`. The next run
+(after a crash, a kill, a pod restart, `stop`, or an upgrade) finds it and:
+
+- carries it on when the agent was waiting for a person's permission for a tool call (not a plan or a question card), the agent
+  always asks (no `approval = "never"`, no `allow_unsafe_modes`) and its session was in a mode that asks, the connector is not
+  paused, and it was away no longer than a card lives (10 minutes): the agent is told the connector restarted and to go on, so
+  it asks again and a new card comes; the prompt's own `turn_end` still ends it. It only asks, so nothing runs that nobody
+  approved. Nothing is carried on before the run has signed in (a revoked connector carries on nothing);
+- otherwise ends it with `turn_end` `{"stopReason": "error", "error": "connector_restarted"}`, naming its prompt (`cmd_id`,
+  `cmd_seq`), so a phone stops waiting for it. The agent is not re-run by itself; the next message resumes the conversation.
+
+Every session used in the last 4 hours, and every one with a turn found this way, then gets one `session_recovered` event
+(`interrupted`: a turn was cut off; `continuing`: it is being carried on; `cmd_id` and `cmd_seq` of that turn), which a chat
+shows as "recovered". A stop by the kill switch (`pause`, a revocation) still ends every turn and drops the queue.
 
 Known limit: the working-directory check resolves the path and starts the adapter in the resolved path, but another process of
 the same user that can rewrite a directory in that path could swap a symlink between the check and the start. The