@tecorb/agent-pool 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to `@tecorb/agent-pool`. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/).
+
+## 0.1.0 - 2026-10-15
+
+The first release.
+
+### Added
+
+- **Accounts:** add several Claude subscriptions, each with its own isolated Claude Code login (`subscription add`, `list`, `status`, `use`, `rename`, `login`, `mark`, `priority`, `remove`). Duplicate accounts are refused; plans come only from Claude Code.
+- **Availability:** usage from Claude Code's status line and error hooks; missing data is shown as Unknown and estimates are labeled.
+- **Projects and workers:** `project init`, `run`, `worker list | status | stop | restart`, `session list | status`, one worker per project, crash recovery with a Git comparison.
+- **Context and handoffs:** `.agent-pool/context.md` kept current while you work; `handoff create | list | resume` with stale detection.
+- **Switching:** `worker switch` with a Git safety gate that never touches your working tree.
+- **Daemon:** workers survive a closed terminal; detach with Ctrl+] then d, reattach with `worker attach`; `daemon start | stop | restart | status`; `events [--follow]`.
+- **Automatic switching:** `autoSwitch` auto (default), ask or off; only on a confirmed limit, never during a running tool, with loop guards.
+- **Diagnostics:** `init`, `doctor`, `config list | get | set | path`, `--json` on every read command.
+- **Security:** no tokens, cookies, API keys or passwords are ever stored; Claude Code login files are never read; processes start without a shell; Git access is read-only.
+
+### Known limitations
+
+- The terminal library `@lydell/node-pty` is pinned to a beta version (1.2.0-beta.15), the only maintained build that installs without a compiler on every supported platform.
+- An automatic switch on a real usage limit, and how Claude Code reacts when the daemon dies, are tested with a fake Claude Code only.

package/COMPLIANCE.md

@@ -0,0 +1,55 @@
+# Compliance
+
+> **You are responsible for complying with the terms of service of each provider whose accounts you add to Agent Pool.**
+
+Agent Pool prints this notice once, on your first `agent-pool run`, and `agent-pool doctor` repeats it as an info line. This page explains what Agent Pool does, and never does, with the accounts you add.
+
+## Scope: one person, one machine
+
+- Agent Pool is for a single developer who owns several Claude subscriptions and uses them on their own computer.
+- It is not a service, a proxy or a way to share accounts. It has no server, no user management and no network listener.
+- It runs the official Claude Code (`claude`) as an interactive program in a terminal, exactly as you would yourself, one worker per project.
+
+## The official binary only
+
+- Agent Pool runs the `claude` binary that Anthropic ships, found on your `PATH` or at the native installer location. It does not reimplement, patch or proxy Claude Code, and it does not call the Claude API itself.
+- It makes no model calls of its own. It does not use `claude -p` or the Agent SDK for internal tasks.
+- Each subscription gets its own Claude Code configuration directory (`CLAUDE_CONFIG_DIR` under `~/.agent-pool/environments`). Claude Code keeps the login there itself.
+
+## Credentials
+
+What Agent Pool does:
+
+- It signs in with `claude auth login`, run with your terminal attached, so you type into Claude Code's own browser login. Agent Pool never sees what you type.
+- It reads the account with `claude auth status` (email, organization, plan) and stores the email as the account identity.
+- It signs out with `claude auth logout` when you cancel an add or remove a subscription, and deletes the managed directory only after Claude Code reports that it is signed out.
+- It removes variables that would make Claude Code use something other than your subscription login (for example `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_BASE_URL`, the Bedrock and Vertex switches) from every worker's environment. `doctor` names the ones present in your shell, never their values.
+
+What Agent Pool never does:
+
+- It never reads, copies or moves Claude Code credential files, `.claude.json` or Keychain entries. When it shares your `~/.claude` setup (`CLAUDE.md`, commands, agents, skills, output styles) into a managed directory, a name denylist keeps credential and key files out at every depth.
+- It never stores tokens, cookies, API keys, passwords or session secrets in its database, config, logs, project files or Git. Every log line, event and printed line passes through redaction, and the test suite runs with fake tokens in the environment and scans everything it wrote for them (the canary scan).
+- It never sends anything over the network.
+
+## What Agent Pool stores
+
+In `~/.agent-pool` (folders 0700 and files 0600 on macOS and Linux; the user profile's permissions on Windows):
+
+- subscription labels, the account email, the plan name Claude Code reports, and availability: the usage percentages and reset times from Claude Code's status line, never prompt or response text;
+- projects, workers, sessions and their segments, handoffs, switches and an event log;
+- your configuration (`config/config.yaml`), including when this notice was shown;
+- runtime files: project locks, the daemon lock and its per-boot token, the latest status line fields.
+
+In each project, `.agent-pool/` holds `context.md`, the handoffs and `project.json`. It is excluded from Git through `.git/info/exclude` unless you choose to commit context and handoffs.
+
+## The background daemon
+
+- The daemon keeps workers running when a terminal closes. It listens only on a Unix domain socket in `~/.agent-pool/runtime` (socket 0600, folder 0700) on macOS and Linux, or a named pipe on Windows. There is no TCP listener.
+- Every connection must prove that it knows a random token that is created at each start in a 0600 file. Both sides prove it with a keyed hash, so the token itself never crosses the socket, and a program pretending to be the daemon learns nothing.
+- On Windows, Node.js cannot set the access list of a named pipe. The default list gives other users read access only, which is not enough to open the two-way connection the daemon needs; together with the per-user pipe name and the token proof, that is the protection there.
+
+## Automatic switching
+
+- When the daemon owns a worker, `autoSwitch` decides what happens when that subscription reaches its limit: `auto` (the default) moves the work to your next available subscription through a handoff, `ask` asks you first, and `off` only records the event.
+- Only a confirmed limit or an unavailable subscription triggers a switch. Network, server and unknown errors never do.
+- A switch moves your own work between your own subscriptions on your own machine. If a provider's terms do not allow this for your accounts, set `autoSwitch` to `off` with `agent-pool config set autoSwitch off`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tecorb Technologies
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,166 @@
-# Temporary Holding Version
+# AI Agent Pool
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`agent-pool` is a local CLI that runs Claude Code across the Claude subscriptions you own. Each subscription gets its own isolated Claude Code environment with its own login. When one subscription reaches its usage limit, the work moves to the next one through a handoff file, without touching your working tree. A background daemon keeps Claude Code running when you close the terminal, and you can reattach from any terminal.
+
+> **You are responsible for complying with the terms of service of each provider whose accounts you add to Agent Pool.**
+>
+> Agent Pool shows this once, on your first `agent-pool run`. See `COMPLIANCE.md` (included in this package) for what Agent Pool does and never does with your accounts.
+
+## Requirements
+
+- Node.js 22.13 or later (22 LTS or 24)
+- Claude Code 2.1.268 or later, installed with the native installer (or Homebrew or WinGet), logged in through Agent Pool
+- Git 2.30 or later (recommended: without Git, the safety checks around switching are reduced)
+- macOS (arm64 or x64), Linux (x64 or arm64) or Windows (x64)
+
+## Install
+
+```sh
+npm install -g @tecorb/agent-pool
+agent-pool --version
+```
+
+The package is `@tecorb/agent-pool` (the unscoped name was taken on npm); the command is `agent-pool`.
+
+## Quickstart
+
+1. **Create the local state** in `~/.agent-pool` (or `$AGENT_POOL_HOME`, which must be an absolute path) and check the installation:
+
+   ```sh
+   agent-pool init
+   agent-pool doctor
+   ```
+
+2. **Add your subscriptions.** Each one opens Claude Code's own browser login in its own environment; Agent Pool never sees your credentials.
+
+   ```sh
+   agent-pool subscription add      # for example "Work"
+   agent-pool subscription add      # for example "Personal"
+   agent-pool subscription list
+   ```
+
+   A new subscription shows availability Unknown until Claude Code reports usage. Set the order Agent Pool tries them in with `agent-pool subscription priority`.
+
+3. **Register a project**, at its Git root:
+
+   ```sh
+   cd ~/code/my-project
+   agent-pool project init
+   ```
+
+   `.agent-pool/` is added to `.git/info/exclude`; your tracked `.gitignore` is never edited.
+
+4. **Run Claude Code:**
+
+   ```sh
+   agent-pool run --subscription work --task "Fix the parser"
+   ```
+
+   Agent Pool prints which subscription it chose and why, checks the login, records a Git snapshot and starts Claude Code. The first launch on each subscription and in each project shows Claude Code's own onboarding and folder trust questions; answer them as usual.
+
+5. **Detach and reattach.** Press **Ctrl+] then d** to detach: Claude Code keeps running in the daemon. Closing the terminal window has the same effect. From any terminal:
+
+   ```sh
+   agent-pool worker attach
+   ```
+
+   The screen is redrawn exactly as you left it. Running `agent-pool run` again in the project also attaches.
+
+6. **Switch by hand** when you want to, from a second terminal:
+
+   ```sh
+   agent-pool worker switch --to personal
+   ```
+
+   Agent Pool writes a handoff (`.agent-pool/handoffs/...`), stops the worker gracefully, checks that the working tree did not change, and starts Claude Code on the other subscription with the handoff as its first task. Uncommitted, staged and untracked work stays in place.
+
+7. **Let it switch automatically.** With the default `autoSwitch: auto`, when the daemon sees a confirmed usage limit it does the same switch without asking and prints one line, for example:
+
+   ```
+   Switched from "Work" to "Personal": limit reached (high). Handoff: .agent-pool/handoffs/20261011t101500z-hnd_....md
+   ```
+
+   ```sh
+   agent-pool config set autoSwitch ask    # ask first
+   agent-pool config set autoSwitch off    # never switch automatically
+   agent-pool events --follow              # watch availability and switching events
+   ```
+
+## How it works
+
+- **Isolation.** Each subscription has its own `CLAUDE_CONFIG_DIR` under `~/.agent-pool/environments`, so logins, settings and session history stay separate. Your `~/.claude` setup (CLAUDE.md, commands, agents, skills, output styles, settings) is copied in, never credential files.
+- **Availability** comes from Claude Code's status line (`rate_limits`, five-hour and seven-day windows) and its StopFailure hook. Missing data is shown as Unknown and estimates are labeled; Agent Pool never invents a number.
+- **Context and handoffs.** Claude Code is asked (through an appended system prompt, not your CLAUDE.md) to keep `.agent-pool/context.md` current while it works; Agent Pool keeps a Git and session block in the same file. A handoff copies it with a Git snapshot, so the next subscription can continue even after the previous one hit its limit.
+- **The daemon** owns the Claude Code processes and keeps each screen in a headless terminal emulator. `agent-pool run` starts it when `daemon.enabled` is true (the default for new installations; if an older config file says `false`, `run` and `doctor` tell you). It listens only on a local socket (a named pipe on Windows), never on the network.
+
+### Automatic switching
+
+| `autoSwitch`     | On a confirmed limit                                                                              |
+| ---------------- | ------------------------------------------------------------------------------------------------- |
+| `auto` (default) | Switches to the next available subscription in priority order, then prints a one-line summary     |
+| `ask`            | Asks in the attached terminal; with no terminal attached, the question waits until you attach     |
+| `off`            | Records the event; the worker stays where it is (Claude Code continues by itself after the reset) |
+
+- Only `LIMIT_REACHED` or `SUBSCRIPTION_UNAVAILABLE` with high confidence triggers a switch. Network errors, server errors, crashes and anything uncertain only produce a notice.
+- A switch happens only while Claude Code is waiting for input or after it exited, never during a running tool.
+- The target must be logged in and Available (from fresh provider data, or estimated after a reset); Limited is used only when nothing is Available; Unknown never.
+- Loop guards: at most `switching.maxPerSessionPerHour` automatic switches per session per hour (default 3), a cooldown of `switching.cooldownMinutes` before switching back to a subscription (default 15), and a full stop, with the earliest known reset, when no subscription can serve.
+- If no terminal is attached, the summary is shown on your next attach and is always in `agent-pool events`.
+- Automatic switching needs the daemon (`daemon.enabled: true`).
+
+### If the daemon stops
+
+`agent-pool daemon stop` refuses while workers run (use `--force` to stop them gracefully first). If the daemon process dies unexpectedly, the pseudo terminals close with it: Claude Code receives a hangup on macOS and Linux, and Windows ends the process when its pseudo console closes. Your files and Git state are untouched; `.agent-pool/context.md` holds the last checkpoint. The next daemon marks those workers FAILED, and the next `agent-pool run` in the project offers to restart, or to write a handoff and restart.
+
+## Commands
+
+| Area          | Commands                                                                                                   |
+| ------------- | ---------------------------------------------------------------------------------------------------------- |
+| Setup         | `init`, `doctor`, `config list \| get \| set \| path`                                                      |
+| Subscriptions | `subscription add \| list \| status \| use \| rename \| login \| mark \| priority \| remove`               |
+| Projects      | `project init \| status \| context`                                                                        |
+| Work          | `run [--detach]`, `worker list \| status \| attach \| stop \| restart \| switch`, `session list \| status` |
+| Handoffs      | `handoff create \| list \| resume`                                                                         |
+| Daemon        | `daemon start \| stop \| restart \| status`, `events [--follow]`                                           |
+
+Every read command supports `--json`. Run `agent-pool <command> --help` for details.
+
+## Platform support
+
+Agent Pool's native dependencies ship prebuilt binaries, so installing needs no compiler on the supported platforms:
+
+| Dependency                                  | Prebuilt for                                                                              | How                                                   |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------- |
+| `better-sqlite3` 13                         | darwin-arm64, darwin-x64, linux-x64, linux-arm64 (glibc and musl), win32-x64, win32-arm64 | N-API prebuilds inside the package, no install script |
+| `@lydell/node-pty` 1.2.0-beta.15            | darwin, linux and win32, each x64 and arm64                                               | one optional package per platform                     |
+| `@xterm/headless`, `@xterm/addon-serialize` | everywhere                                                                                | pure JavaScript                                       |
+
+`@lydell/node-pty` is pinned to a beta version on purpose: it is the only maintained build of node-pty that ships prebuilt binaries for every platform above.
+
+On another platform, `better-sqlite3` must be built from source (`npm rebuild better-sqlite3`, which needs a C++ toolchain), and a missing terminal module shows up as the failing "Terminal (PTY)" check in `agent-pool doctor`.
+
+## Troubleshooting
+
+- **`agent-pool doctor` first.** It checks Node.js, the local folders and their permissions, the config, the database, Git, the terminal module, the daemon, Claude Code (found, version, override variables in your shell), every subscription's login and the current project.
+- **"Claude Code was not found" on Windows** with an npm-only install: npm puts a `.cmd` shim on `PATH`, which Agent Pool does not run (it never uses a shell). Install Claude Code with the native installer.
+- **"The daemon socket path is too long"**: Unix socket paths are limited to about 103 bytes. Use a shorter `AGENT_POOL_HOME`, or set `daemon.enabled` to `false`.
+- **The daemon does not start**: run `agent-pool daemon serve` in a terminal to see the error, and look in `~/.agent-pool/logs`.
+- **"The daemon speaks protocol N"** after an upgrade: run `agent-pool daemon restart` when no worker is running.
+- **"Terminal (PTY)" fails in doctor**: the platform package of `@lydell/node-pty` was not installed; reinstall Agent Pool without `--omit=optional`.
+- **A worker keeps the old subscription** after a limit: check `agent-pool events --type autoswitch.`. It says why (for example, no other subscription had fresh availability, a loop guard, `autoSwitch off`, or a network error rather than a limit).
+- **The new session stops at the folder trust question** after a switch: the target subscription has not opened this project before. Answer it in the attached terminal (`agent-pool worker attach`).
+- **Detaching does not work**: some terminals capture Ctrl+]. Close the terminal window instead; the worker keeps running.
+- **`AGENT_POOL_HOME` outside your user profile on Windows**: Agent Pool relies on the profile's access control list there, so protect that folder yourself.
+- **Secrets in your shell**: `ANTHROPIC_API_KEY` and similar variables are removed from every worker's environment, so Claude Code uses the subscription login; doctor names them.
+
+## Security model
+
+- No tokens, cookies, API keys, passwords or session secrets are stored in the database, config, logs or project files. Everything written passes through redaction, and the end-to-end tests run with fake tokens in the environment and scan everything they wrote for them.
+- Claude Code credential files and Keychain entries are never read, copied or moved.
+- Processes start only through a wrapper that takes an absolute executable path and an argument array, never a shell.
+- Agent Pool runs only read-only Git commands. The one exception, an optional WIP commit before a switch (`git.checkpointCommit`, off by default), always asks first.
+- On macOS and Linux, folders are created with mode 0700 and files with mode 0600, and the daemon socket with 0600. On Windows, Agent Pool relies on the access control list of your user profile.
+
+## License
+
+MIT. See `LICENSE` and `CHANGELOG.md`, both included in this package.