{"_id":"@eddieparc/senpi-multiaccounts","name":"@eddieparc/senpi-multiaccounts","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@eddieparc/senpi-multiaccounts","version":"0.1.0","description":"Senpi addon: multi-account subscriptions for Claude, OpenAI Codex and Kiro — per-account usage, cache-preserving routing, usage-aware placement and 429 failover.","type":"module","license":"MIT","repository":{"type":"git","url":"git+https://github.com/eddieparc/senpi-multiaccounts.git"},"homepage":"https://github.com/eddieparc/senpi-multiaccounts#readme","bugs":{"url":"https://github.com/eddieparc/senpi-multiaccounts/issues"},"keywords":["pi-package","senpi","senpi-extension","claude","openai-codex","kiro","multi-account","provider-accounts"],"publishConfig":{"access":"public"},"pi":{"extensions":["./dist/index.js"]},"scripts":{"build":"tsc -p tsconfig.build.json","test":"vitest run","typecheck":"tsc --noEmit","prepare":"[ -f tsconfig.build.json ] && npm run build || exit 0","prepublishOnly":"npm run typecheck && npm run test && npm run build"},"peerDependencies":{"@code-yeongyu/senpi":">=2026.8.1"},"devDependencies":{"@code-yeongyu/senpi":"^2026.8.1","@types/node":"^24.13.3","typescript":"^5.9.3","vitest":"^4.1.10"},"gitHead":"52b69a31645e7a16bd63a3e3067f625f631d0772","_id":"@eddieparc/senpi-multiaccounts@0.1.0","_nodeVersion":"24.14.0","_npmVersion":"11.11.0","dist":{"integrity":"sha512-YcC6gOOqJDzvyho3YJ1k5rHNGl7mP8m9/9Pinnk2fXp1fRqTbFbTBChD2XM8q7jeyEioPWnBR4wnuXqjoldE9w==","shasum":"49122eeba39e6f86d93318d56a0bb3327fa19559","tarball":"https://registry.npmjs.org/@eddieparc/senpi-multiaccounts/-/senpi-multiaccounts-0.1.0.tgz","fileCount":93,"unpackedSize":349616,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIF2DN5c/BLZYOoYv2X/LzCtUmspdJVg0MfjJaezuGnMZAiAzH7OLQ9xwzet/BqvTEitJJal+AGN/fYd3WLpcUkkhRA=="}]},"_npmUser":{"name":"eddieparc","email":"jgp3620@gmail.com"},"directories":{},"maintainers":[{"name":"eddieparc","email":"jgp3620@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/senpi-multiaccounts_0.1.0_1785718789391_0.5010889314541171"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-03T00:59:49.270Z","0.1.0":"2026-08-03T00:59:49.558Z","modified":"2026-08-03T00:59:49.825Z"},"maintainers":[{"name":"eddieparc","email":"jgp3620@gmail.com"}],"description":"Senpi addon: multi-account subscriptions for Claude, OpenAI Codex and Kiro — per-account usage, cache-preserving routing, usage-aware placement and 429 failover.","homepage":"https://github.com/eddieparc/senpi-multiaccounts#readme","keywords":["pi-package","senpi","senpi-extension","claude","openai-codex","kiro","multi-account","provider-accounts"],"repository":{"type":"git","url":"git+https://github.com/eddieparc/senpi-multiaccounts.git"},"bugs":{"url":"https://github.com/eddieparc/senpi-multiaccounts/issues"},"license":"MIT","readme":"# senpi-multiaccounts\n\nMulti-account subscriptions for [senpi](https://github.com/code-yeongyu/senpi) — Claude,\nOpenAI Codex and Kiro — with per-account usage, cache-preserving routing, usage-aware\nplacement and automatic 429 failover.\n\nStock senpi is the base layer and is never modified. This addon sits on top of it and\nfills only the gaps stock leaves.\n\n> ### Purpose and scope\n>\n> **This is an open-source project published for learning and research purposes.** It\n> exists to explore how senpi's extension API composes providers, how prompt-cache\n> affinity interacts with account rotation, and how subscription rate limits surface\n> through a provider SDK.\n>\n> It automates nothing you could not do by hand: it signs in with **your own**\n> subscriptions, through each vendor's normal OAuth flow, and stores the resulting\n> tokens in senpi's own `auth.json`. It does not share, pool, resell or redistribute\n> accounts, and it does not bypass any vendor's authentication, billing or rate limits\n> — when a subscription is exhausted this addon simply reports it and stops using that\n> account until the vendor's own reset time.\n>\n> You are responsible for complying with the terms of service of every provider you\n> configure. Review them before using multiple accounts. Provided as-is, without\n> warranty, under the MIT licence.\n\n## What this addon adds\n\n| Capability | Status | Where it comes from |\n|---|---|---|\n| **Kiro** subscription provider (Google / GitHub / AWS Builder ID) | **shipped, live-verified** | this addon |\n| Multi-account pool with pin, rotation, 429 failover and timed failback | **shipped, live-verified** | this addon |\n| Cache-preserving conversation affinity + usage-aware placement | shipped | this addon |\n| Per-account and full logout; `cache-first` / `balanced` / `spread` modes | shipped | this addon |\n| `/usage` dashboard across every subscription | shipped | this addon |\n| **TokenRouter** provider (117 models behind one key) | **shipped, live-verified** | this addon |\n| **OpenGateway** provider (Kimi K3 Ultrafast) | shipped | this addon |\n| **OpenAI Codex account pool** with live per-account quota | **shipped, live-verified** | this addon |\n| **Claude per-account usage** (5h / weekly / model-scoped windows) | **shipped, live-verified** | this addon |\n| Claude account manager in provider configuration, plus `/claude-accounts` | shipped | local senpi patch + this addon |\n| Quota exhaustion blocks routing until the vendor reset | shipped | this addon |\n| Anthropic account pool, streaming and failover | stock | `/claude-account` |\n| Alibaba Token Plan, OpenCode Go | stock | API-key providers |\n\nNothing marked *stock* is reimplemented here; the addon only surfaces it in the usage\ndashboard.\n\n**Kiro is the supported provider in this release.** It is verified against the live API:\nfour models (`claude-opus-5`, `claude-opus-4.7`, `claude-sonnet-4.6`, `claude-haiku-4.5`),\ntwo real accounts, per-account pinning, failover onto a second account when the first is\nrejected, automatic token refresh, and recovery after a cooldown expires.\n\n### Two stock bugs found while building this\n\nBoth were reported upstream rather than worked around here:\n\n- [senpi#503](https://github.com/code-yeongyu/senpi/pull/503) — `/fast` can never succeed.\n  The command is registered only for `openai-codex`, but the catalog generator emits\n  `-fast` priority variants only for the direct `openai` provider. Measured against\n  `chatgpt.com`, `service_tier: \"priority\"` returns HTTP 200 and is then served at normal\n  tier, while senpi bills it at up to 2.5x — so synthesising the missing variants would be\n  a placebo that inflates reported cost. Fast mode is therefore **not** implemented here;\n  the PR corrects the misleading message instead.\n- [senpi#505](https://github.com/code-yeongyu/senpi/pull/505) — Claude multi-account never\n  rotates. Plan exhaustion arrives as prose (\"You've hit your weekly limit\") or as a bare\n  `error_during_execution` with the cause only in `terminal_reason`, and neither was\n  classified as a rate limit, so the exhausted account was never blocked.\n\n## Install\n\nRequires senpi `>= 2026.8.1`.\n\n**One command** — from the npm registry:\n\n```bash\nnpm install @eddieparc/senpi-multiaccounts\n```\n\nThe git route works too and compiles on install:\n\n```bash\nnpm install github:eddieparc/senpi-multiaccounts\n```\n\nnpm runs the package's `prepare` script for a git dependency, so `dist/` is\ncompiled during install. Then point senpi at the built entry:\n\n```text\nsenpi -e ./node_modules/@eddieparc/senpi-multiaccounts\n```\n\n**From source** — the path this repo is developed against:\n\n```bash\ngit clone https://github.com/eddieparc/senpi-multiaccounts.git\ncd senpi-multiaccounts\nnpm install\nnpm run build\n```\n\nThen either load it per-run (substitute your own checkout path):\n\n```text\nsenpi -e /absolute/path/to/senpi-multiaccounts\n```\n\nor let senpi add the local package to its user settings:\n\n```bash\nsenpi remove npm:@eddieparc/senpi-accounts\nsenpi install /absolute/path/to/senpi-multiaccounts/dist/index.js\n```\n\nThe first command removes the former Kiro-only package. Keeping both packages\nloaded would register the same provider and `/usage` command twice. Install the\nbuilt entry point, not the repository root: senpi enumerates a bare directory\nand would otherwise load `dist/` and `src/` as separate extensions.\n\nVerify it loaded — this should print the Kiro models:\n\n```text\nsenpi -e /absolute/path/to/senpi-multiaccounts --list-models | grep kiro\n```\n\n## Kiro setup\n\n```\n/login kiro\n```\n\n`/login kiro` is a full account manager, not just a one-shot login:\n\n| Action | What it does |\n|---|---|\n| Add an account | Google / GitHub / AWS Builder ID sign-in, then names the slot |\n| Log out of one account | Deletes one account, leaving the rest intact |\n| Log out of every account | Empties the pool, clearing the pin and bindings too |\n| Pin / Clear the pin | Force every request onto one account |\n| Clear a block | Lift a rate-limit or auth block early |\n| Scheduling mode | `cache-first` (default), `balanced` or `spread` |\n| Migration policy | `auto` (default), `ask` or `never` — see [Migration policy](#migration-policy) |\n\nBoth logout paths live inside `/login kiro`, which is the account manager. Full\nlogout asks for confirmation first, and clears the pin and conversation bindings\nalong with the accounts so nothing points at a slot that no longer exists.\n\nThen pick a model:\n\n```\n/model kiro/claude-opus-5\n```\n\nThe built-in catalog follows Kiro CLI 2.15.2 and includes its Claude, GPT-5.6,\nDeepSeek, MiniMax, GLM and Qwen options. Availability still depends on the\nselected account. To replace the catalog without waiting for a package update:\n\n```bash\nexport KIRO_MODELS_OVERRIDE=auto,claude-sonnet-5,gpt-5.6-sol\n```\n\nAutomatic completion probing is intentionally disabled because probes consume\ncredits and one pooled account's entitlement does not describe the whole pool.\n\nFor redacted Kiro protocol and request-failure diagnostics:\n\n```bash\nexport KIRO_DEBUG=1\n```\n\nThe log is written to `$SENPI_CODING_AGENT_DIR/debug/debug.log`. Credentials and\nauthorization values are redacted, and logging is off by default.\n\n### Adding a second or third Kiro account\n\nKiro federates Google sign-in through its own Cognito pool, and Google keeps a\nbrowser-wide SSO cookie. Two consequences:\n\n- Signing out of **Kiro** alone is not enough — Google silently re-authenticates the\n  same identity server-side, before any client-side `prompt=select_account` can apply.\n- Aside browser profiles do **not** help: they share one Google cookie jar, so every\n  profile presents the same default Google account.\n\nSo a second Kiro account needs the Google account switched first. This sequence\nworks:\n\n1. Sign out of Kiro: `https://app.kiro.dev/home` → account menu → **Sign Out**.\n2. Sign in to Google as the target account at `https://accounts.google.com/`.\n   These accounts use a **passkey**, so this step needs a human at the machine\n   (Touch ID); it cannot be automated.\n3. Confirm the switch stuck — `https://app.kiro.dev/signin` should say\n   \"currently signed in via Google as: <target>\".\n4. Run the scripted login; it binds whichever identity Kiro now holds.\n\nAll three Kiro auth methods were exercised and all three resolve to whichever\nidentity the browser/AWS session already holds:\n\n| Method | Result |\n|---|---|\n| Google | Kiro's Cognito session re-federates the current Google account |\n| GitHub | same Cognito session behaviour |\n| AWS Builder ID | device-code flow completes (`요청 승인됨`) but returns the same AWS identity |\n\nSo switching accounts is a browser/AWS session action, not something the addon\ncan drive. The duplicate guard below exists precisely because these flows all\n*succeed* while silently returning the identity you already had.\n\nVerify which identity was actually captured — the login prints the email:\n\n```\nUSAGE 0/0 jgplabs@gmail.com\nSAVED jgplabs\n```\n\nIf it prints the wrong address, the Google session did not switch; repeat step 2.\nAccounts are keyed by name, so a duplicate simply stores the same identity twice and\nyields no extra quota.\n\n### Scripted login\n\nFor CI or headless setup:\n\n```text\nSENPI_CODING_AGENT_DIR=~/.senpi/agent \\\n  npx tsx scripts/login.mts <account-name> [google|github|builder-id]\n```\n\nIt prints the authorize URL, captures the localhost callback automatically, and appends\nthe account to the pool.\n\n## Other subscriptions\n\n**Alibaba Token Plan** and **OpenCode Go** are stock providers that authenticate\nwith an API key, so they need nothing from this addon:\n\n```\n/login alibaba-token-plan     # or set ALIBABA_TOKEN_PLAN_API_KEY\n/login opencode-go            # or set OPENCODE_API_KEY\n```\n\nBoth appear in `/usage` once configured. Verified state on the development machine:\n`opencode-go` is registered and listed in `/usage` (`configured (API key; no quota\nendpoint)`), but a live completion returns `401 CreditsError: Insufficient balance` — a\nbilling state, not an addon fault. `alibaba-token-plan` is **not configured here**, so it\nis unverified end to end; stock already lists its models (`deepseek-v4-pro`, `glm-5.2`,\n`kimi-k2.7-code`, ...), and it needs only the key above.\n\n## Claude (Anthropic)\n\nThe account pool itself is stock: senpi streams through the Claude Agent SDK and\nfails over on its own. The accompanying local senpi patch makes the stock\n`claude-sdk-oauth` OAuth entry open an account manager when accounts already\nexist, just like Kiro. Add, per-account logout, full logout, pin and unblock are\nall available there. The same controls remain scriptable through this addon:\n\n```\n/claude-accounts                      # list with live per-account usage\n/claude-accounts pin <name>           # force every request onto one account\n/claude-accounts unpin\n/claude-accounts unblock <name>       # lift a rate-limit block early\n/claude-accounts logout <name|all>\n```\n\nThe command is deliberately plural so it coexists with stock's `/claude-account`\nrather than shadowing it.\n\nUsage comes from `https://api.anthropic.com/api/oauth/usage`, which reports the same\nthree windows the desktop apps show: a 5-hour session window, a weekly window across\nevery model, and a weekly window scoped to one model family. That last one carries its\nown display name in the payload (it was Opus, it is now Fable), so the label is read\nfrom the response rather than hardcoded.\n\nMeasured across three live accounts:\n\n```\nSubscription usage:\n  claude-sdk-oauth  default:    7% 5h 4h 7m · 38% week 4d 22h · 51% Fable 4d 22h — available\n  claude-sdk-oauth  jgplabs:    0% 5h · 7% week 5d 1h · 4% Fable 5d 1h — available\n  claude-sdk-oauth  jgplabs01:  14% 5h 3h 57m · 100% week 3d 15h · 100% Fable 3d 15h — blocked (quota)\n```\n\n`jgplabs01` is the case that motivated this: its weekly window is fully spent, and the\nold dashboard reported the pool as `3/3 accounts available`. A slot count cannot answer\n\"how much have I got left\", which is the one question `/usage` exists for.\n\nAn exhausted unscoped window is persisted as `blockReason: \"quota\"` until its\nvendor-provided reset timestamp. Kiro, Claude and Codex therefore stop routing to\nzero-remaining accounts before a request fails. A Fable-only exhausted window is\nmodel-scoped and does not retire the whole Claude subscription.\n\nAn expired access token answers the usage endpoint with HTTP 401, which would read as\n\"headroom unknown\" and silently drop the account from the dashboard, so a stale slot is\nrefreshed first. Anthropic rotates the refresh token on every exchange, so the rotated\npair is written straight back into stock's own record — keeping the new access token\nwithout persisting the new refresh token would leave stock holding a token the server\nhas already retired. The write preserves stock's sentinel `access` / `refresh` /\n`expires` fields verbatim; only `accounts` and `pinned` are touched.\n\n### TokenRouter\n\nTokenRouter fronts ~117 models behind one OpenAI-compatible endpoint, and stock senpi\nhas no `tokenrouter` provider — so the models are unreachable however the key is stored.\nThis addon registers the provider id, which is what puts TokenRouter in the `/login`\nlist:\n\n```\n/login tokenrouter            # or set TOKENROUTER_API_KEY\n```\n\nIssue the key at [tokenrouter.com](https://www.tokenrouter.com) under Console -> API\nKeys. There is no account pool: TokenRouter meters one account, so rotating keys would\nbuy nothing, and this is a single-credential provider like stock's `opencode-go`.\n\nThe catalog ships `moonshotai/kimi-k3`, `moonshotai/kimi-k3-free`,\n`deepseek/deepseek-v4-pro`, `qwen/qwen3.7-max` and `z-ai/glm-5.2`;\n`TOKENROUTER_MODELS_OVERRIDE=<comma-separated ids>` adds any other id the router serves.\nA catalog is mandatory rather than cosmetic — an extension-registered provider inherits\nno models, and without one `--provider tokenrouter` fails as `Unknown provider`.\n\nTwo measured quirks are encoded in the catalog's `compat` profile rather than left for a\nuser to hit:\n\n| Request senpi sends by default | TokenRouter's answer |\n|---|---|\n| `role: \"developer\"` | `HTTP 400 role 'developer' is not allowed` |\n| `store: false` | `HTTP 200` with a whitespace body and no completion |\n\nBoth made a turn fail as `422 openai_error` while a plain `curl` succeeded, so every\nmodel declares `supportsDeveloperRole: false` and `supportsStore: false`.\n\n**`kimi-k3-free` is slow, not broken.** The free tier queued for 395s on a cold call\nbefore returning a normal `HTTP 200`. senpi bounds the wait to the first stream event at\n90s by default, so a free-tier turn needs that raised:\n\n```json\n{\n  \"retry\": { \"provider\": { \"streamStartTimeoutMs\": 600000, \"streamIdleTimeoutMs\": 600000 } }\n}\n```\n\nPaid `moonshotai/kimi-k3` answers in 6-9s and needs no such setting.\n\n### OpenGateway\n\nOpenGateway is an OpenAI-compatible gateway that stock senpi does not know, so its\nmodels are unreachable no matter where the key is stored. Registering the provider id is\nwhat puts it in the `/login` list, and senpi's own API-key prompt then stores, replaces\nand drops the key:\n\n```\n/login opengateway            # or set OPENGATEWAY_API_KEY\n```\n\nThe catalog ships `moonshotai/kimi-k3-ultrafast`. OpenGateway publishes neither token\nlimits nor pricing, so the limits mirror Kimi K3 elsewhere in senpi and cost stays zero\nrather than inventing billing data. Like TokenRouter this is a single-credential\nprovider: one metered account, so there is no pool to rotate.\n\n**OpenAI Codex** works out of the box as stock `openai-codex`, and that is the\nrecommended path.\n\nPooling several ChatGPT subscriptions is **experimental** in this release and opt-in:\n\n```bash\nexport SENPI_ACCOUNTS_CODEX_POOL=1\n```\n\nThat registers a `codex-pool` provider which delegates streaming to stock's Codex\nResponses implementation while adding the same account pool, affinity and failover as\nKiro. Manage it with `/login codex-pool`.\n\nPer-account quota is live: `https://chatgpt.com/backend-api/codex/usage` reports\n`rate_limit.primary_window` (and a secondary window on plans that have one) plus the\nplan type and the account's email, so `balanced` placement now actually has numbers to\nplace by. It previously reported every slot as unknown, which silently degraded\n`balanced` to plain affinity while the menu still offered it.\n\nIt remains marked experimental because it depends on resolving stock's Codex streamer at runtime —\nsenpi is a peer dependency, so that resolution is anchored on the running senpi process.\nIf it cannot be resolved the provider degrades on its own and Kiro is unaffected.\n\n## How routing works\n\nThe scarce resource is not quota alone but the upstream **prompt-prefix cache**. Moving a\nconversation to a different account makes that account's cache cold, which usually costs\nmore than the quota it saves. So:\n\n1. **Affinity first.** A conversation is fingerprinted from its first user message and\n   pinned to one account. Later turns reuse it, keeping the cache warm.\n2. **Quota only when the cache is cold.** For a conversation that has not been placed\n   before, `balanced` mode picks the account with the most headroom using\n   power-of-two-choices, which spreads load without herding onto one account.\n3. **429 failover last.** A rate-limited, quota-exhausted, auth-failed or 5xx account is\n   blocked and the request is replayed on the next account. Timed blocks expire on their\n   own (failback); auth blocks persist until re-login.\n\nHeadroom comes from Kiro's own usage-limits endpoint, read from the `CREDIT` row of\n`usageBreakdownList` — the same numbers the\n[account page](https://app.kiro.dev/settings/account) shows. Snapshots are cached for 30s\nwith a 2s ceiling per refresh, so routing never waits on a quota lookup, and an expired\naccess token is refreshed before probing (a stale token answers HTTP 403, which would\notherwise read as \"headroom unknown\" and quietly drop that account from placement).\n\nMeasured across three live Pro Max accounts, `balanced` mode places cold conversations by\nheadroom and leaves the most-used account untouched; the per-mode figures are in\n[Scheduling modes](#scheduling-modes). When no provider reports a limit, placement\ndegrades to an even\nspread rather than herding onto one account.\n\n### Scheduling modes\n\n| Mode | Behaviour |\n|---|---|\n| `cache-first` (default) | Hold one account per conversation. Maximises cache hits. |\n| `balanced` | Same, but new conversations go to the account with the most quota left. |\n| `spread` | Round-robin every request. Best load spread, ignores the cache. |\n\nMeasured over the three live Pro Max accounts at 70.3% / 90.1% / 98.1% headroom, 300 cold\nconversations each:\n\n| Mode | Placement |\n|---|---|\n| `cache-first` | `jgplabs01` 111, `jgp3620` 98, `jgplabs` 91 — hashed, quota ignored |\n| `balanced` | `jgplabs01` 194, `jgplabs` 106, `jgp3620` **0** — most-used account starved |\n| `spread` | 100 / 100 / 100 — exactly even |\n\nThe same conversation key placed twice returns the same account with `reusedBinding=true`,\nso affinity holds across turns.\n\nThe conversation key is senpi's session id when the runtime supplies one, and a hash of the\nfirst user message otherwise. The session id is preferred because it does not move:\ncompaction replaces the first user message with the summary, which changed a content-derived\nkey mid-conversation and dropped the binding on a conversation whose cache was warm.\n\n### Upstream congestion is not an account fault\n\nKiro's CodeWhisperer backend answers a busy moment with prose and no HTTP status:\n\n```\nEncountered unexpectedly high load when processing the request, please try again.\n```\n\nThat used to block the account for 60s. One request walks the whole pool, so a\ntwenty-second backend hiccup blocked all three accounts and the next request was\nrefused with \"All accounts are blocked (rate limited or awaiting re-login)\" while\nevery subscription still had quota — 22%, 60% and 35% in the observed incident.\n\nCongestion is now **transient**: the same account is retried after a short bounded\ndelay (400ms, doubling, capped at 2s), which also keeps its warm prompt cache. Only\nafter repeated congestion on one account is it sidelined, for seconds rather than a\nminute, and never when it is the last selectable account. A genuine HTTP 5xx still\nblocks immediately.\n\n| Symptom | Treated as | Effect on the account |\n|---|---|---|\n| `429`, rate limit, throttled | account is over its limit | blocked, failover |\n| quota / entitlement / billing | subscription exhausted | blocked, failover |\n| `401` / `403`, bad token | needs re-login | blocked until `/login` |\n| HTTP `5xx`, bad gateway | broken request | blocked briefly, failover |\n| \"high load\", \"try again\", \"at capacity\" | **upstream is busy** | **not blocked; retried** |\n\nThe block window also grows properly now. `blockAccount` always computed\n`base * 2**attempt`, but the attempt counter lived in a map rebuilt on every\nrequest, so it was always 0 and every block lasted exactly 60s. The streak is\npersisted on the account and cleared by a success, so repeated failures back off\n60s → 120s → 240s.\n\nWhen the pool genuinely has nothing left, the error says so in full:\n\n```\nAll 3 account(s) are blocked (server_error); earliest retry in 47s (jgplabs);\nquota is not the limiting factor here.\n```\n\n`/usage` names the reason too, so it can no longer report `available` for an\naccount that placement is refusing to use:\n\n```\nkiro  jgplabs: 22% remaining, available\nkiro  jgplabs01: 60% remaining, blocked 47s (server_error)\nkiro  jgp3620: 35% remaining, needs re-login\n```\n\n### Migration policy\n\nA conversation can lose the account holding its warm prompt cache in two very different\nways, and only one of them is worth telling you about:\n\n| Case | What it means | Policy applies |\n|---|---|---|\n| **Detour** | The account is rate limited, quota blocked or briefly failing. The block is a wall-clock window that expires, so the binding is kept and the conversation returns once it lifts. | No — always allowed |\n| **Permanent rebind** | The bound account has left the pool (logged out, removed). The cache is gone with it. | Yes |\n\n```\n/kiro-account migrate <auto|ask|never>\n```\n\n| Policy | Behaviour on a permanent rebind |\n|---|---|\n| `auto` (default) | Move to another account silently. |\n| `ask` | Move, and report which account the conversation left. |\n| `never` | Refuse: the request fails instead of silently moving to a cold account. |\n\nThe policy is also reachable from the `/login kiro` menu as **Migration policy**, and the\ncurrent value is shown by `/kiro-account list`.\n\nNotices never interrupt a stream: they are emitted after placement and are suppressed in\nnon-interactive modes (`print`, RPC without UI), where no one is watching. A failure inside\nthe notification is swallowed rather than surfaced as a request failure.\n\n`never` is for keeping a conversation and its cache on exactly one account, at the cost of\nthe turn that would have moved it. It does not block a detour, because a detour is\nreversible.\n\n### Interaction with senpi's own fallback\n\nsenpi has a **model-level** fallback (`SelectorCooldowns` + fallback chains). This addon\nis **account-level** and sits underneath it:\n\n```\nrequest\n └─ addon: pick account → on 429 retry on the next account   (senpi never sees this)\n     └─ only when every account is blocked, the error surfaces\n         └─ senpi: suppress the model, fall back to the next model\n```\n\nWhen the pool is fully blocked, the addon raises `AllAccountsBlockedError` carrying\n`retryAfterMs` set to the real unblock time. senpi's cooldown prefers an explicit\n`retryAfterMs` over its keyword heuristics, so the model is suppressed for exactly as long\nas the pool is down instead of senpi's default 30-minute quota bucket.\n\n## Commands\n\n| Command | Purpose |\n|---|---|\n| `/login kiro` | Account manager: add, log out (one or all), pin, unblock, set scheduling mode |\n| `/login codex-pool` | Same manager for ChatGPT accounts, including migration policy |\n| `/claude-accounts` | Claude accounts with per-account usage; pin, unpin, unblock, logout |\n| `/usage` | Remaining usage across addon and stock subscriptions, per account |\n| `/senpi-multiaccounts` | Provider health, including any degraded provider |\n\n## Reliability\n\nEach provider is an isolated package under `src/providers/`, loaded lazily inside its own\ntry/catch. A provider that fails to load, build or register is reported as degraded and\nskipped; every other provider still registers. Providers never import each other.\n\nCredentials live in senpi's own `auth.json`, written atomically with `0600` permissions.\nA corrupt `auth.json` is never overwritten.\n\n### Keychain (optional, macOS)\n\n`src/core/keychain.ts` can hold pools in the macOS Keychain instead of the filesystem.\nIt is **off by default** because `auth.json` already matches stock's protection, and it\nis only used when `keychainAvailable()` proves a full write/read round-trip succeeds —\npresence of the `security` binary is not enough, since a locked or access-denied keychain\nwould silently drop credentials.\n\nThe probe asks `security default-keychain` before attempting anything. An isolated `HOME`\n(CI, a sandbox, the README doc-check) has no login keychain, and a write in that state\nmakes macOS raise a modal \"keychain could not be found\" dialog that blocks the run until\nsomeone clicks it. Reporting unavailable is the correct answer there, and it costs no\nwrite.\n\n## Publishing\n\nPublished to the npm registry as\n[`@eddieparc/senpi-multiaccounts`](https://www.npmjs.com/package/@eddieparc/senpi-multiaccounts).\nA scoped package defaults to restricted access, which answers `402 Payment Required` on a\nfree account, so `publishConfig.access` is `public` in `package.json` and no flag is\nneeded.\n\nReleases go out from CI over\n[trusted publishing](https://docs.npmjs.com/trusted-publishers): `.github/workflows/release.yml`\nauthenticates to the registry with a short-lived OIDC token, so no npm credential is\nstored anywhere and no publish needs an interactive 2FA approval. Bump the version, then\npush the tag:\n\n```bash\nnpm version patch          # or minor / major\ngit push origin main --follow-tags\n```\n\nThe workflow also accepts a manual `workflow_dispatch` run. Either way `prepublishOnly`\nruns typecheck, the full suite and the build first, so an unverified tree cannot reach the\nregistry, and npm attaches a signed provenance statement because the publish is attributable\nto the workflow that produced it.\n\nPublishing this way depends on three things staying in agreement, and npm only reports a\nmismatch when a publish actually runs:\n\n- the trusted publisher registered on npmjs.com names `eddieparc` / `senpi-multiaccounts` /\n  `release.yml`, case-sensitive and including the extension\n- the workflow keeps `permissions: id-token: write`\n- `repository.url` in `package.json` matches the GitHub repository\n\nRenaming the workflow file therefore breaks releases until the npm setting is renamed to\nmatch.\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck\nnpm test\nnpm run build\n```\n","readmeFilename":"README.md","_rev":"1-94927e1a8355885b836ae25f724e8bf0"}