teapot-coding-agent 0.29.24 → 0.29.25

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,129 +1,85 @@
1
1
  /**
2
- * API-key pooling and rotation (#170) — "1プロバイダに複数のAPIキーを紐付けられるようにして
3
- * ローテーションとかできるように / レートリミットきたAPIキーを自動ローテ".
2
+ * Multiple API keys per provider (#170) — "複数鍵登録しといて、規定のリトライ回数を超えたら
3
+ * 次の鍵にローテ / 全キーを回ってもまだレートリミットだったらエラーで停止".
4
4
  *
5
- * ## What this is for
5
+ * ## The algorithm, deliberately small
6
6
  *
7
- * A provider entry used to hold ONE `apiKey`, so the only way to spread load was to
8
- * duplicate the whole provider (this config had `openrouter`, `openrouter-minimax`,
9
- * `openrouter-nemotron-3.5-lightning`, `openrouter-glm-5.2`, `openrouter-union-alpha` —
10
- * five entries differing only in `model`, all sharing one credential). Nothing could
11
- * rotate, so a rate-limited key stalled every agent on it at once.
7
+ * A request is made with the current key. The HTTP client already retries a rate limit
8
+ * a fixed number of times on that key (its own backoff ladder). When those retries are
9
+ * spent and the failure is STILL a rate limit, the pool moves to the next key and the
10
+ * whole ladder runs again on it. When the last key is exhausted too, the error is
11
+ * raised and the turn stops.
12
12
  *
13
- * ## The rules, and why they are the rules
13
+ * That is the entire policy:
14
14
  *
15
- * 1. **Round-robin, not random.** Random selection lets the same key be picked twice
16
- * in a row while another sits idle; with a small pool that is the difference
17
- * between spreading load and not. A cursor per pool makes consecutive picks
18
- * distinct.
15
+ * key1 [retry × N] -> key2 [retry × N] -> … -> raise
19
16
  *
20
- * 2. **A rate-limited key goes into COOLDOWN, it is not dropped.** A 429 is a
21
- * temporary statement about one key, so discarding it would be wrong and blocking
22
- * the whole provider would be worse. It returns to the pool when the cooldown
23
- * lapses — no timer, just a timestamp compared on read, because a timer per key
24
- * would keep resetting and complicate shutdown.
17
+ * ## What this intentionally does NOT do
25
18
  *
26
- * 3. **Never return null while the pool is non-empty.** If every key is cooling down
27
- * the LEAST-recently-limited one is used anyway. Refusing to make a request cannot
28
- * succeed; making it with the soonest-to-recover key at least tries, and the caller
29
- * still has its own retry ladder. This is the property that keeps rotation from
30
- * turning a single 429 into a hard failure.
19
+ * An earlier version of this file tracked per-key "recovered at" timestamps, parsed
20
+ * provider reset hints, classified a 429 as transient-vs-exhausted, and persisted spent
21
+ * accounts to disk. None of that was asked for, none of it was generic (the hint
22
+ * formats are provider-specific), and the operator's actual ask is the loop above. A
23
+ * simpler rule is also easier to reason about when it goes wrong: with this policy the
24
+ * only state is "which key am I on", and the only outcome is success or a raised error.
31
25
  *
32
- * 4. **Order is the config's order.** The operator's first key stays first, so
33
- * behaviour is predictable and the pool does not reshuffle behind their back.
26
+ * ## Provider-agnostic
34
27
  *
35
- * Pure and dependency-free so the rules can be tested directly; the caller owns the
36
- * pool instance and the clock.
28
+ * Nothing here knows about any particular endpoint. "Rate limited" is the HTTP 429 that
29
+ * every OpenAI-compatible provider uses; the caller decides which statuses qualify.
37
30
  */
38
- /** How long a rate-limited key is skipped by default. */
39
- export const KEY_COOLDOWN_MS = 60_000;
40
- /** Build a pool, dropping duplicates and blanks while keeping the config's order. */
31
+ /** Build a pool from config order, dropping blanks and duplicates. */
41
32
  export function makeKeyPool(keys) {
42
33
  const seen = new Set();
43
34
  const unique = [];
44
35
  for (const k of keys) {
45
- const t = k.trim();
36
+ const t = typeof k === "string" ? k.trim() : "";
46
37
  if (!t || seen.has(t))
47
38
  continue;
48
39
  seen.add(t);
49
40
  unique.push(t);
50
41
  }
51
- return { keys: unique, cursor: 0, cooldownUntil: new Map() };
42
+ return { keys: unique, current: 0 };
52
43
  }
53
- /**
54
- * Pick the next key, advancing the cursor.
55
- *
56
- * Returns null only when the pool is empty, which the caller treats as "this provider
57
- * has no credential" rather than as a rotation failure.
58
- */
59
- export function nextKey(pool, now) {
60
- if (pool.keys.length === 0)
44
+ /** The key in use, or null for an empty pool (or no pool at all). */
45
+ export function currentKey(pool) {
46
+ // tolerate a missing pool: most callers simply have no `keyPool`, and making every
47
+ // one of them guard first is how a `undefined.keys` crash reaches a 400 (measured)
48
+ if (!pool)
61
49
  return null;
62
- const n = pool.keys.length;
63
- // try each key at most once, starting from the cursor: the first not cooling down
64
- for (let i = 0; i < n; i++) {
65
- const idx = (pool.cursor + i) % n;
66
- const key = pool.keys[idx];
67
- const until = pool.cooldownUntil.get(key) ?? 0;
68
- if (until <= now) {
69
- pool.cursor = (idx + 1) % n;
70
- return key;
71
- }
72
- }
73
- // EVERY key is cooling down. Refusing to send cannot succeed, so hand out the one
74
- // that recovers soonest — see rule 3.
75
- let bestIdx = pool.cursor;
76
- let bestUntil = Infinity;
77
- for (let i = 0; i < n; i++) {
78
- const idx = (pool.cursor + i) % n;
79
- const until = pool.cooldownUntil.get(pool.keys[idx]) ?? 0;
80
- if (until < bestUntil) {
81
- bestUntil = until;
82
- bestIdx = idx;
83
- }
84
- }
85
- pool.cursor = (bestIdx + 1) % n;
86
- return pool.keys[bestIdx];
87
- }
88
- /** Mark a key rate-limited: it is skipped for `ms`, then returns to the pool. */
89
- export function coolDown(pool, key, now, ms = KEY_COOLDOWN_MS) {
90
- if (!pool.keys.includes(key))
91
- return;
92
- const until = now + ms;
93
- // never SHORTEN an existing cooldown: a second 429 while one is pending must not
94
- // bring the key back early
95
- const cur = pool.cooldownUntil.get(key) ?? 0;
96
- if (until > cur)
97
- pool.cooldownUntil.set(key, until);
98
- }
99
- /** Keys usable right now (diagnostics / the UI). */
100
- export function availableKeys(pool, now) {
101
- return pool.keys.filter((k) => (pool.cooldownUntil.get(k) ?? 0) <= now);
50
+ return pool.keys[pool.current] ?? null;
102
51
  }
103
52
  /**
104
- * Rotate to a different key after a failure, or null when there is no alternative.
53
+ * Move to the next key, or null when every key has already had its turn.
105
54
  *
106
- * `tried` is the key that just failed; it is put on cooldown first, so the rotation
107
- * cannot hand the same key back. Returns null when this pool has only one usable key
108
- * — the caller should then stop rotating and let its own retry ladder run, since
109
- * re-sending with the same credential proves nothing.
55
+ * Null is the "全キーを回ってもまだレートリミットだった" signal: the caller stops and raises
56
+ * the last error instead of cycling forever. No wraparound on purpose — wrapping would
57
+ * re-try keys whose retry ladder was just spent, turning a hard limit into an infinite
58
+ * loop.
110
59
  */
111
- export function rotateAfterFailure(pool, tried, now, ms = KEY_COOLDOWN_MS) {
112
- coolDown(pool, tried, now, ms);
113
- const next = nextKey(pool, now);
114
- if (next === null || next === tried)
60
+ export function nextKey(pool) {
61
+ const next = pool.current + 1;
62
+ if (next >= pool.keys.length)
115
63
  return null;
116
- return next;
64
+ pool.current = next;
65
+ return pool.keys[next];
66
+ }
67
+ /** Start over from the first key (a fresh turn gets the full cycle again). */
68
+ export function resetPool(pool) {
69
+ pool.current = 0;
70
+ }
71
+ /** How many keys this pool holds. */
72
+ export function poolSize(pool) {
73
+ return pool.keys.length;
117
74
  }
118
75
  /**
119
- * The HTTP statuses that mean "this KEY is the problem", so rotating can help.
76
+ * Is this failure a rate limit — the only kind rotating can fix?
120
77
  *
121
- * 429 is the reported case. 401/403 are included deliberately: a revoked or
122
- * exhausted key answers that way, and with a pool the operator very likely has a
123
- * second working one — this is the difference between rotation being useful and it
124
- * only covering exactly the one reported symptom. 5xx is NOT here: a provider
125
- * outage affects every key equally, so rotating just burns the pool.
78
+ * 429 is the universal spelling. 402 ("payment required") and 403 are included because
79
+ * an exhausted subscription and a quota-blocked key answer that way, and a second
80
+ * account is exactly what resolves them. Everything else (5xx, 400, a network error) is
81
+ * NOT rotated: it would fail identically on every key, so rotating just burns the cycle.
126
82
  */
127
- export function isKeyFailure(status) {
128
- return status === 429 || status === 401 || status === 403;
83
+ export function isRateLimitStatus(status) {
84
+ return status === 429 || status === 402 || status === 403;
129
85
  }
package/dist/agent/llm.js CHANGED
@@ -6,7 +6,7 @@
6
6
  * than hand-rolled.
7
7
  */
8
8
  import OpenAI from "openai";
9
- import { rotateAfterFailure, isKeyFailure } from "./key-pool.js";
9
+ import { isRateLimitStatus, nextKey } from "./key-pool.js";
10
10
  const clients = new WeakMap();
11
11
  /**
12
12
  * Rotate to another key after a KEY-level failure (#170), returning a config that
@@ -19,15 +19,15 @@ const clients = new WeakMap();
19
19
  * candidates are the failed one: retrying with the SAME credential cannot help, and
20
20
  * the caller's own staircase is the right response then.
21
21
  */
22
- export function rotateKey(cfg, now = Date.now()) {
22
+ export function rotateKey(cfg) {
23
23
  const pool = cfg.keyPool;
24
- if (!pool || pool.keys.length < 2)
24
+ if (!pool)
25
25
  return null;
26
- const next = rotateAfterFailure(pool, cfg.apiKey, now);
26
+ const next = nextKey(pool);
27
27
  if (!next)
28
- return null;
29
- // a new apiKey means a new OpenAI client below, which is correct: the credential
30
- // is baked into the client at construction
28
+ return null; // every key has had its turn
29
+ // a new apiKey means a new OpenAI client below, which is correct: the credential is
30
+ // baked into the client at construction
31
31
  return { ...cfg, apiKey: next };
32
32
  }
33
33
  /**
@@ -228,18 +228,15 @@ export function providerHeaders(baseUrl, sessionId) {
228
228
  function client(cfg) {
229
229
  let c = clients.get(cfg);
230
230
  if (!c) {
231
- // #170: with a POOL the SDK must NOT retry a 429 itself. Its backoff re-sends the
232
- // SAME rate-limited key four times — MEASURED, 6.7 s of backoff before the
233
- // rotation below ever saw the error — when the point of having another key is to
234
- // use it immediately. So a multi-key provider surfaces the status straight away
235
- // and `withKeyRotation` picks the next key; the agent's own ladder (5s/5s/30s) is
236
- // still there as the outer backstop for a 5xx, which no key can fix.
237
- const pooled = (cfg.keyPool?.keys.length ?? 0) > 1;
231
+ // #170: the SDK's retry ladder is deliberately KEPT for a pooled provider too.
232
+ // The operator's rule is "規定のリトライ回数を超えたら次の鍵にローテ", i.e. each key gets
233
+ // its own retries before the pool moves on — so `maxRetries` is the per-key budget
234
+ // and must not be zeroed.
238
235
  c = new OpenAI({
239
236
  baseURL: cfg.baseUrl,
240
237
  apiKey: cfg.apiKey,
241
238
  timeout: cfg.timeoutMs ?? 120_000,
242
- maxRetries: pooled ? 0 : 4,
239
+ maxRetries: cfg.maxRetries ?? 4, // per-key: rotation happens after these are spent
243
240
  defaultHeaders: providerHeaders(cfg.baseUrl, cfg.sessionId),
244
241
  });
245
242
  clients.set(cfg, c);
@@ -259,21 +256,24 @@ function client(cfg) {
259
256
  */
260
257
  async function withKeyRotation(cfg, run) {
261
258
  let cur = cfg;
262
- const attempts = Math.max(1, cfg.keyPool?.keys.length ?? 1);
263
259
  let lastErr;
264
- for (let i = 0; i < attempts; i++) {
260
+ for (let i = 0; i < Math.max(1, cfg.keyPool?.keys.length ?? 1); i++) {
265
261
  try {
262
+ // The client's own retry ladder runs inside `run`, so by the time this catch
263
+ // fires the FIRST key has already been retried its configured number of times.
264
+ // Only then do we move on — that is the operator's "規定のリトライ回数を超えたら".
266
265
  return { value: await run(cur), cfg: cur };
267
266
  }
268
267
  catch (err) {
269
268
  lastErr = err;
270
269
  const status = err?.status;
271
- if (typeof status !== "number" || !isKeyFailure(status))
270
+ if (typeof status !== "number" || !isRateLimitStatus(status))
272
271
  throw err;
273
272
  const rotated = rotateKey(cur);
273
+ // no key left: "全キーを回ってもまだレートリミットだったらエラーで停止"
274
274
  if (!rotated)
275
- throw err; // one key, or no alternative: the caller's ladder runs
276
- console.warn(`[teapot] key rate-limited/unusable (HTTP ${status}) — rotating to the next of ${cur.keyPool?.keys.length ?? 1} keys for this provider`);
275
+ throw err;
276
+ console.warn(`[teapot] rate limited (HTTP ${status}) on this key — moving to the next of ${cur.keyPool?.keys.length ?? 1} for this provider`);
277
277
  cur = rotated;
278
278
  }
279
279
  }
package/dist/master.js CHANGED
@@ -5,7 +5,7 @@
5
5
  */
6
6
  import { readFileSync, existsSync, mkdirSync, writeFileSync, readdirSync, statSync, lstatSync, renameSync, unlinkSync, openSync, closeSync, readSync, fsyncSync, } from "node:fs";
7
7
  import { randomUUID } from "node:crypto";
8
- import { availableKeys, makeKeyPool } from "./agent/key-pool.js";
8
+ import { currentKey, makeKeyPool, resetPool } from "./agent/key-pool.js";
9
9
  import { sessionTitleFrom } from "./session-title.js";
10
10
  import path from "node:path";
11
11
  import os from "node:os";
@@ -524,6 +524,8 @@ export class Master {
524
524
  if (keys.length === 0)
525
525
  return undefined;
526
526
  const existing = this.keyPools.get(name);
527
+ // reuse while the KEY LIST is unchanged, so the pool keeps its position in the
528
+ // cycle across spawns; a changed list is a new pool
527
529
  if (existing && existing.keys.length === keys.length && existing.keys.every((k, i) => k === keys[i])) {
528
530
  return existing;
529
531
  }
@@ -531,14 +533,29 @@ export class Master {
531
533
  this.keyPools.set(name, pool);
532
534
  return pool;
533
535
  }
534
- /** diagnostics: how many keys each provider holds, and how many are usable now */
535
- keyPoolReport(now = Date.now()) {
536
+ /**
537
+ * Diagnostics: each provider's keys and which one is in use.
538
+ *
539
+ * Deliberately shows only position, not "spent until" timestamps: this pool has no
540
+ * such state — a key is rotated past once its retries are spent, and a new turn
541
+ * starts the cycle again.
542
+ */
543
+ keyPoolReport() {
536
544
  return [...this.keyPools.entries()].map(([provider, pool]) => ({
537
545
  provider,
538
546
  keys: pool.keys.length,
539
- available: availableKeys(pool, now).length,
547
+ current: pool.current,
540
548
  }));
541
549
  }
550
+ /** start every provider's cycle over from its first key */
551
+ resetKeyPool(provider) {
552
+ const names = provider ? [provider] : [...this.keyPools.keys()];
553
+ for (const n of names) {
554
+ const pool = this.keyPools.get(n);
555
+ if (pool)
556
+ resetPool(pool);
557
+ }
558
+ }
542
559
  writeConfigAtomic(body) {
543
560
  // #144: `/dev/null` is a real, intentional value here — many callers (and
544
561
  // every test that does not care about persistence) pass it as "no config
@@ -839,7 +856,12 @@ export class Master {
839
856
  const pool = inlineKey ? undefined : this.keyPoolFor(provName, prov);
840
857
  const llm = {
841
858
  baseUrl: ac.baseUrl ?? prov?.baseUrl ?? this.config.llm.baseUrl,
842
- apiKey: inlineKey ?? pool?.keys[0] ?? prov?.apiKey ?? this.config.llm.apiKey,
859
+ // the pool's CURRENT key is the sticky one: a restart must resume on the
860
+ // account the operator's cycle had reached, not start over on a spent first one
861
+ apiKey: inlineKey ??
862
+ currentKey(pool) ??
863
+ prov?.apiKey ??
864
+ this.config.llm.apiKey,
843
865
  model: ac.model ?? prov?.model ?? this.config.llm.model,
844
866
  timeoutMs: 120_000,
845
867
  ...(pool && pool.keys.length > 1 ? { keyPool: pool } : {}),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "teapot-coding-agent",
3
- "version": "0.29.24",
3
+ "version": "0.29.25",
4
4
  "description": "A lightweight, always-on multi-agent harness for AI coding agents",
5
5
  "type": "module",
6
6
  "license": "AGPL-3.0-or-later",