teapot-coding-agent 0.29.23 → 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.
@@ -0,0 +1,85 @@
1
+ /**
2
+ * Multiple API keys per provider (#170) — "複数鍵登録しといて、規定のリトライ回数を超えたら
3
+ * 次の鍵にローテ / 全キーを回ってもまだレートリミットだったらエラーで停止".
4
+ *
5
+ * ## The algorithm, deliberately small
6
+ *
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
+ *
13
+ * That is the entire policy:
14
+ *
15
+ * key1 [retry × N] -> key2 [retry × N] -> … -> raise
16
+ *
17
+ * ## What this intentionally does NOT do
18
+ *
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.
25
+ *
26
+ * ## Provider-agnostic
27
+ *
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.
30
+ */
31
+ /** Build a pool from config order, dropping blanks and duplicates. */
32
+ export function makeKeyPool(keys) {
33
+ const seen = new Set();
34
+ const unique = [];
35
+ for (const k of keys) {
36
+ const t = typeof k === "string" ? k.trim() : "";
37
+ if (!t || seen.has(t))
38
+ continue;
39
+ seen.add(t);
40
+ unique.push(t);
41
+ }
42
+ return { keys: unique, current: 0 };
43
+ }
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)
49
+ return null;
50
+ return pool.keys[pool.current] ?? null;
51
+ }
52
+ /**
53
+ * Move to the next key, or null when every key has already had its turn.
54
+ *
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.
59
+ */
60
+ export function nextKey(pool) {
61
+ const next = pool.current + 1;
62
+ if (next >= pool.keys.length)
63
+ return null;
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;
74
+ }
75
+ /**
76
+ * Is this failure a rate limit — the only kind rotating can fix?
77
+ *
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.
82
+ */
83
+ export function isRateLimitStatus(status) {
84
+ return status === 429 || status === 402 || status === 403;
85
+ }
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 { isRateLimitStatus, nextKey } 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) {
23
+ const pool = cfg.keyPool;
24
+ if (!pool)
25
+ return null;
26
+ const next = nextKey(pool);
27
+ if (!next)
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
+ 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: 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.
208
235
  c = new OpenAI({
209
236
  baseURL: cfg.baseUrl,
210
237
  apiKey: cfg.apiKey,
211
238
  timeout: cfg.timeoutMs ?? 120_000,
212
- maxRetries: 4, // SDK handles backoff for 429/5xx/network errors
239
+ maxRetries: cfg.maxRetries ?? 4, // per-key: rotation happens after these are spent
213
240
  defaultHeaders: providerHeaders(cfg.baseUrl, cfg.sessionId),
214
241
  });
215
242
  clients.set(cfg, c);
216
243
  }
217
244
  return c;
218
245
  }
246
+ /**
247
+ * Run a request, rotating to another key when the failure is KEY-level (#170).
248
+ *
249
+ * Bounded by the pool size: each rotation parks the key that just failed, so the walk
250
+ * cannot revisit one and cannot loop forever. A non-key failure (a 500, a malformed
251
+ * request, an abort) is rethrown untouched — rotating on those would burn every key
252
+ * for a problem none of them caused.
253
+ *
254
+ * The LAST failure is the one propagated, so the operator sees the error from the
255
+ * final key rather than whichever happened to fail first.
256
+ */
257
+ async function withKeyRotation(cfg, run) {
258
+ let cur = cfg;
259
+ let lastErr;
260
+ for (let i = 0; i < Math.max(1, cfg.keyPool?.keys.length ?? 1); i++) {
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 "規定のリトライ回数を超えたら".
265
+ return { value: await run(cur), cfg: cur };
266
+ }
267
+ catch (err) {
268
+ lastErr = err;
269
+ const status = err?.status;
270
+ if (typeof status !== "number" || !isRateLimitStatus(status))
271
+ throw err;
272
+ const rotated = rotateKey(cur);
273
+ // no key left: "全キーを回ってもまだレートリミットだったらエラーで停止"
274
+ if (!rotated)
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
+ 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 { currentKey, makeKeyPool, resetPool } 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,52 @@ 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
+ // 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
529
+ if (existing && existing.keys.length === keys.length && existing.keys.every((k, i) => k === keys[i])) {
530
+ return existing;
531
+ }
532
+ const pool = makeKeyPool(keys);
533
+ this.keyPools.set(name, pool);
534
+ return pool;
535
+ }
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() {
544
+ return [...this.keyPools.entries()].map(([provider, pool]) => ({
545
+ provider,
546
+ keys: pool.keys.length,
547
+ current: pool.current,
548
+ }));
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
+ }
441
559
  writeConfigAtomic(body) {
442
560
  // #144: `/dev/null` is a real, intentional value here — many callers (and
443
561
  // every test that does not care about persistence) pass it as "no config
@@ -730,11 +848,23 @@ export class Master {
730
848
  if (!prov && !ac.baseUrl && !this.config.llm.baseUrl) {
731
849
  throw new Error(`agent ${ac.id}: unknown provider "${provName}" and no fallback`);
732
850
  }
851
+ // #170: an INLINE `ac.apiKey` is this agent's own credential, so it must NOT be
852
+ // joined to the provider's pool — the pool belongs to the named provider, and
853
+ // folding a one-off override in would rotate an agent onto keys its operator did
854
+ // not choose for it. Only the named provider gets a pool.
855
+ const inlineKey = typeof ac.apiKey === "string" && ac.apiKey.trim() ? ac.apiKey.trim() : undefined;
856
+ const pool = inlineKey ? undefined : this.keyPoolFor(provName, prov);
733
857
  const llm = {
734
858
  baseUrl: ac.baseUrl ?? prov?.baseUrl ?? this.config.llm.baseUrl,
735
- apiKey: ac.apiKey ?? 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,
736
865
  model: ac.model ?? prov?.model ?? this.config.llm.model,
737
866
  timeoutMs: 120_000,
867
+ ...(pool && pool.keys.length > 1 ? { keyPool: pool } : {}),
738
868
  };
739
869
  if (!llm.model)
740
870
  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.23",
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",