teapot-coding-agent 0.29.22 → 0.29.24

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.
@@ -110,7 +110,7 @@ export function updateForEvent(e, opts) {
110
110
  };
111
111
  }
112
112
  case "tool_result": {
113
- const name = String(d.name ?? "tool");
113
+ const _name = String(d.name ?? "tool");
114
114
  return {
115
115
  sessionUpdate: "tool_call_update",
116
116
  toolCallId: String(d.callId ?? e.type),
@@ -2014,7 +2014,7 @@ export class Agent {
2014
2014
  const maxAttempts = 4;
2015
2015
  // fail fast, escalate late: most provider hiccups recover in seconds;
2016
2016
  // only sustained failure earns a long cooldown (operator request)
2017
- const waits = [5_000, 5_000, 30_000];
2017
+ const waits = this.opts.llmRetryWaitsMs ?? [5_000, 5_000, 30_000];
2018
2018
  for (let attempt = 1;; attempt++) {
2019
2019
  if (this.stopRequested)
2020
2020
  throw Object.assign(new Error("stopped"), { name: "StopRequested" });
@@ -0,0 +1,129 @@
1
+ /**
2
+ * API-key pooling and rotation (#170) — "1プロバイダに複数のAPIキーを紐付けられるようにして
3
+ * ローテーションとかできるように / レートリミットきたAPIキーを自動ローテ".
4
+ *
5
+ * ## What this is for
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.
12
+ *
13
+ * ## The rules, and why they are the rules
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.
19
+ *
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.
25
+ *
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.
31
+ *
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.
34
+ *
35
+ * Pure and dependency-free so the rules can be tested directly; the caller owns the
36
+ * pool instance and the clock.
37
+ */
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. */
41
+ export function makeKeyPool(keys) {
42
+ const seen = new Set();
43
+ const unique = [];
44
+ for (const k of keys) {
45
+ const t = k.trim();
46
+ if (!t || seen.has(t))
47
+ continue;
48
+ seen.add(t);
49
+ unique.push(t);
50
+ }
51
+ return { keys: unique, cursor: 0, cooldownUntil: new Map() };
52
+ }
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)
61
+ 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);
102
+ }
103
+ /**
104
+ * Rotate to a different key after a failure, or null when there is no alternative.
105
+ *
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.
110
+ */
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)
115
+ return null;
116
+ return next;
117
+ }
118
+ /**
119
+ * The HTTP statuses that mean "this KEY is the problem", so rotating can help.
120
+ *
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.
126
+ */
127
+ export function isKeyFailure(status) {
128
+ return status === 429 || status === 401 || status === 403;
129
+ }
package/dist/agent/llm.js CHANGED
@@ -6,7 +6,30 @@
6
6
  * than hand-rolled.
7
7
  */
8
8
  import OpenAI from "openai";
9
+ import { rotateAfterFailure, isKeyFailure } from "./key-pool.js";
9
10
  const clients = new WeakMap();
11
+ /**
12
+ * Rotate to another key after a KEY-level failure (#170), returning a config that
13
+ * uses it — or null when there is nothing to rotate to.
14
+ *
15
+ * Only the `apiKey` differs; the pool (and therefore the shared cooldown state) is
16
+ * the same object, so the key we just failed stays parked for every other agent too.
17
+ *
18
+ * Returns null when the pool has one key, has no pool at all, or the only other
19
+ * candidates are the failed one: retrying with the SAME credential cannot help, and
20
+ * the caller's own staircase is the right response then.
21
+ */
22
+ export function rotateKey(cfg, now = Date.now()) {
23
+ const pool = cfg.keyPool;
24
+ if (!pool || pool.keys.length < 2)
25
+ return null;
26
+ const next = rotateAfterFailure(pool, cfg.apiKey, now);
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
31
+ return { ...cfg, apiKey: next };
32
+ }
10
33
  /**
11
34
  * Reasoning effort for a request body (#47, #150).
12
35
  *
@@ -205,17 +228,57 @@ export function providerHeaders(baseUrl, sessionId) {
205
228
  function client(cfg) {
206
229
  let c = clients.get(cfg);
207
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;
208
238
  c = new OpenAI({
209
239
  baseURL: cfg.baseUrl,
210
240
  apiKey: cfg.apiKey,
211
241
  timeout: cfg.timeoutMs ?? 120_000,
212
- maxRetries: 4, // SDK handles backoff for 429/5xx/network errors
242
+ maxRetries: pooled ? 0 : 4,
213
243
  defaultHeaders: providerHeaders(cfg.baseUrl, cfg.sessionId),
214
244
  });
215
245
  clients.set(cfg, c);
216
246
  }
217
247
  return c;
218
248
  }
249
+ /**
250
+ * Run a request, rotating to another key when the failure is KEY-level (#170).
251
+ *
252
+ * Bounded by the pool size: each rotation parks the key that just failed, so the walk
253
+ * cannot revisit one and cannot loop forever. A non-key failure (a 500, a malformed
254
+ * request, an abort) is rethrown untouched — rotating on those would burn every key
255
+ * for a problem none of them caused.
256
+ *
257
+ * The LAST failure is the one propagated, so the operator sees the error from the
258
+ * final key rather than whichever happened to fail first.
259
+ */
260
+ async function withKeyRotation(cfg, run) {
261
+ let cur = cfg;
262
+ const attempts = Math.max(1, cfg.keyPool?.keys.length ?? 1);
263
+ let lastErr;
264
+ for (let i = 0; i < attempts; i++) {
265
+ try {
266
+ return { value: await run(cur), cfg: cur };
267
+ }
268
+ catch (err) {
269
+ lastErr = err;
270
+ const status = err?.status;
271
+ if (typeof status !== "number" || !isKeyFailure(status))
272
+ throw err;
273
+ const rotated = rotateKey(cur);
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`);
277
+ cur = rotated;
278
+ }
279
+ }
280
+ throw lastErr;
281
+ }
219
282
  /**
220
283
  * Providers occasionally glue MULTIPLE tool calls into one entry, or leak
221
284
  * their internal framing into the name field (seen live: a name of
@@ -463,13 +526,16 @@ function safeShape(res) {
463
526
  const STREAM_REJECTED_STATUS = new Set([400, 404, 405, 406, 415, 422, 501]);
464
527
  export async function chat(cfg, messages, tools, signal, onDelta) {
465
528
  try {
466
- const res = await client(cfg).chat.completions.create({
467
- model: cfg.model,
529
+ // #170: a KEY-level failure (429 especially) rotates to the provider's next key
530
+ // and retries immediately, rather than handing a rate limit straight to the
531
+ // caller's backoff ladder — with several keys this usually just works.
532
+ const { value: res } = await withKeyRotation(cfg, (c) => client(c).chat.completions.create({
533
+ model: c.model,
468
534
  messages: sanitize(messages),
469
535
  ...(tools.length ? { tools } : {}),
470
- ...effortForRequest(cfg),
471
- ...cacheControlForRequest(cfg),
472
- }, { signal });
536
+ ...effortForRequest(c),
537
+ ...cacheControlForRequest(c),
538
+ }, { signal }));
473
539
  // #50: a gateway may answer with `null` (or any non-object) on some proxy
474
540
  // error paths, so the guard is on `rm`, not on `res` being truthy —
475
541
  // reading `res.choices` unguarded threw a bare TypeError that named neither
@@ -564,17 +630,22 @@ export async function chatStream(cfg, messages, tools, signal, onDelta) {
564
630
  let text = "";
565
631
  let reasoning = "";
566
632
  try {
567
- const stream = await client(cfg).chat.completions.create({
568
- model: cfg.model,
633
+ // #170: the KEY-level rotation covers this path the same way as chat(). It can
634
+ // only start a NEW stream — if a key fails MID-stream the text already sent to
635
+ // the UI stands, and `gotChunk` below stops us from silently restarting and
636
+ // duplicating it. A 429 on a stream is a REJECTION (no chunks yet), which is the
637
+ // case rotation is for.
638
+ const { value: stream } = await withKeyRotation(cfg, (c) => client(c).chat.completions.create({
639
+ model: c.model,
569
640
  messages: sanitize(messages),
570
641
  ...(tools.length ? { tools } : {}),
571
- ...effortForRequest(cfg),
572
- ...cacheControlForRequest(cfg),
642
+ ...effortForRequest(c),
643
+ ...cacheControlForRequest(c),
573
644
  stream: true,
574
645
  // ask providers to include the final usage chunk in streaming mode
575
646
  // (OpenAI-compatible; harmless where unsupported)
576
647
  stream_options: { include_usage: true },
577
- }, { signal });
648
+ }, { signal }));
578
649
  const calls = {};
579
650
  let finishReason;
580
651
  let usage;
@@ -10,6 +10,16 @@ import { z } from "zod";
10
10
  export const ProviderSchema = z.object({
11
11
  baseUrl: z.union([z.string().url("baseUrl must be a valid URL"), z.literal("")]).optional(),
12
12
  apiKey: z.string().optional(),
13
+ /**
14
+ * Several credentials for ONE provider, rotated round-robin (#170). Blank entries
15
+ * are rejected rather than silently dropped: the operator wrote them, and a key
16
+ * that vanishes without a word is how "I added 3 keys but it still rate-limits"
17
+ * happens.
18
+ */
19
+ apiKeys: z
20
+ .array(z.string().min(1, "an api key entry must not be empty"))
21
+ .max(50, "at most 50 keys per provider")
22
+ .optional(),
13
23
  model: z.string().optional(),
14
24
  });
15
25
  export const AgentEntrySchema = z.object({
package/dist/master.js CHANGED
@@ -5,6 +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
9
  import { sessionTitleFrom } from "./session-title.js";
9
10
  import path from "node:path";
10
11
  import os from "node:os";
@@ -198,6 +199,62 @@ export function resolveConfigPath(explicitPath) {
198
199
  return path.resolve("teapot.config.json");
199
200
  }
200
201
  let masterRawConfig = {};
202
+ /**
203
+ * Normalise a provider entry's credentials into `apiKeys` (#170).
204
+ *
205
+ * Both spellings are read, and the result is written back in the shape the UI and
206
+ * the pool consume. The rules:
207
+ *
208
+ * - `apiKeys` present -> used as-is (trimmed, blanks and duplicates dropped)
209
+ * - `apiKey` only -> becomes `apiKeys: [apiKey]` (the OLD shape, which is
210
+ * every config written before this feature)
211
+ * - neither -> left alone (a local endpoint may need no key)
212
+ *
213
+ * `apiKey` is KEPT in step with `apiKeys[0]` rather than deleted, because other
214
+ * readers still expect it (the setup wizard, `/api/providers`, hand-edited files) and
215
+ * a migration that removes a field the operator can see is a migration they will
216
+ * report as data loss.
217
+ *
218
+ * Returns a NEW entry; the caller decides whether to persist.
219
+ */
220
+ export function migrateProviderKeys(p) {
221
+ const seen = new Set();
222
+ const clean = (list) => {
223
+ const out = [];
224
+ for (const k of list) {
225
+ const t = typeof k === "string" ? k.trim() : "";
226
+ if (!t || seen.has(t))
227
+ continue;
228
+ seen.add(t);
229
+ out.push(t);
230
+ }
231
+ return out;
232
+ };
233
+ // `apiKeys` is AUTHORITATIVE once present. The single `apiKey` only SEEDS the pool
234
+ // when there is no list — appending it as well would resurrect a credential the
235
+ // operator had already replaced (they set a list precisely because the old key was
236
+ // exhausted), and the pool would happily rotate back onto it.
237
+ const hasList = Array.isArray(p.apiKeys);
238
+ const keys = hasList
239
+ ? clean(p.apiKeys)
240
+ : clean(typeof p.apiKey === "string" ? [p.apiKey] : []);
241
+ if (keys.length === 0) {
242
+ // no credential at all (a local endpoint may need none): do not invent an empty
243
+ // array, which would read as "this provider has keys" to anything counting them
244
+ const { apiKeys: _drop, ...rest } = p;
245
+ return rest;
246
+ }
247
+ // `apiKey` is kept in step with the FIRST key rather than deleted: other readers
248
+ // still expect it (the setup wizard, `/api/providers`), and a migration that
249
+ // removes a field the operator can see reads as data loss.
250
+ return { ...p, apiKeys: keys, apiKey: keys[0] };
251
+ }
252
+ /** Every key for a provider, in order, with the legacy single key folded in. */
253
+ export function providerKeys(p) {
254
+ if (!p)
255
+ return [];
256
+ return migrateProviderKeys(p).apiKeys ?? [];
257
+ }
201
258
  export function loadConfig(configPath) {
202
259
  if (!existsSync(configPath))
203
260
  return DEFAULT_CONFIG;
@@ -209,7 +266,10 @@ export function loadConfig(configPath) {
209
266
  ...user,
210
267
  dataDir: user.dataDir ? path.resolve(user.dataDir.replace(/^~/, os.homedir())) : DEFAULT_CONFIG.dataDir,
211
268
  llm: { ...DEFAULT_CONFIG.llm, ...user.llm },
212
- providers: { ...user.providers },
269
+ // #170: fold a legacy single `apiKey` into `apiKeys` on load, so every consumer
270
+ // below sees one shape. Done here rather than at each use site because the pool,
271
+ // the UI and the spawn path all need the same answer.
272
+ providers: Object.fromEntries(Object.entries(user.providers ?? {}).map(([name, p]) => [name, migrateProviderKeys(p)])),
213
273
  };
214
274
  }
215
275
  /** Raw parsed user config (for lossless persistence of web edits). */
@@ -332,6 +392,18 @@ export function sanitizeAgentId(id) {
332
392
  }
333
393
  export class Master {
334
394
  agents = new Map();
395
+ /**
396
+ * ONE key pool per provider name (#170), shared by every agent on it.
397
+ *
398
+ * Shared on purpose: a 429 is a statement about the CREDENTIAL, not about the
399
+ * agent that happened to send the request. Per-agent pools would let agent B walk
400
+ * straight back into the key agent A just got rate-limited on — the rotation would
401
+ * exist and do nothing, which is the failure shape this repo keeps re-learning.
402
+ *
403
+ * Keyed by PROVIDER NAME rather than baseUrl: two entries for the same endpoint may
404
+ * legitimately hold different credentials, and those must not be merged.
405
+ */
406
+ keyPools = new Map();
335
407
  /**
336
408
  * pid of the process that replaced us in a live update, or null while we are
337
409
  * still the server. `restartServer()` sets it; `index.ts` reads it to keep
@@ -438,6 +510,35 @@ export class Master {
438
510
  this.saveConfig();
439
511
  }
440
512
  /** write-and-rename, so config.json is never observed empty or half-written */
513
+ /**
514
+ * The shared pool for a provider, created on first use (#170).
515
+ *
516
+ * Cached so the cooldown state survives across agents AND across a provider being
517
+ * re-read: rebuilding the pool on every spawn would forget that a key is cooling
518
+ * down and hand it straight back out. Rebuilt only if the KEY LIST changes (the
519
+ * operator edited the provider), which is when the old cooldowns stop being
520
+ * meaningful.
521
+ */
522
+ keyPoolFor(name, prov) {
523
+ const keys = providerKeys(prov);
524
+ if (keys.length === 0)
525
+ return undefined;
526
+ const existing = this.keyPools.get(name);
527
+ if (existing && existing.keys.length === keys.length && existing.keys.every((k, i) => k === keys[i])) {
528
+ return existing;
529
+ }
530
+ const pool = makeKeyPool(keys);
531
+ this.keyPools.set(name, pool);
532
+ return pool;
533
+ }
534
+ /** diagnostics: how many keys each provider holds, and how many are usable now */
535
+ keyPoolReport(now = Date.now()) {
536
+ return [...this.keyPools.entries()].map(([provider, pool]) => ({
537
+ provider,
538
+ keys: pool.keys.length,
539
+ available: availableKeys(pool, now).length,
540
+ }));
541
+ }
441
542
  writeConfigAtomic(body) {
442
543
  // #144: `/dev/null` is a real, intentional value here — many callers (and
443
544
  // every test that does not care about persistence) pass it as "no config
@@ -730,11 +831,18 @@ export class Master {
730
831
  if (!prov && !ac.baseUrl && !this.config.llm.baseUrl) {
731
832
  throw new Error(`agent ${ac.id}: unknown provider "${provName}" and no fallback`);
732
833
  }
834
+ // #170: an INLINE `ac.apiKey` is this agent's own credential, so it must NOT be
835
+ // joined to the provider's pool — the pool belongs to the named provider, and
836
+ // folding a one-off override in would rotate an agent onto keys its operator did
837
+ // not choose for it. Only the named provider gets a pool.
838
+ const inlineKey = typeof ac.apiKey === "string" && ac.apiKey.trim() ? ac.apiKey.trim() : undefined;
839
+ const pool = inlineKey ? undefined : this.keyPoolFor(provName, prov);
733
840
  const llm = {
734
841
  baseUrl: ac.baseUrl ?? prov?.baseUrl ?? this.config.llm.baseUrl,
735
- apiKey: ac.apiKey ?? prov?.apiKey ?? this.config.llm.apiKey,
842
+ apiKey: inlineKey ?? pool?.keys[0] ?? prov?.apiKey ?? this.config.llm.apiKey,
736
843
  model: ac.model ?? prov?.model ?? this.config.llm.model,
737
844
  timeoutMs: 120_000,
845
+ ...(pool && pool.keys.length > 1 ? { keyPool: pool } : {}),
738
846
  };
739
847
  if (!llm.model)
740
848
  throw new Error(`agent ${ac.id}: no model configured (set model on the agent or on its provider)`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "teapot-coding-agent",
3
- "version": "0.29.22",
3
+ "version": "0.29.24",
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",