@cogitator-ai/bridge 0.10.2 → 0.12.0

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.
Files changed (104) hide show
  1. package/README.md +114 -22
  2. package/dist/adapter.d.ts +16 -1
  3. package/dist/adapter.d.ts.map +1 -1
  4. package/dist/adapters/claude.d.ts +44 -0
  5. package/dist/adapters/claude.d.ts.map +1 -1
  6. package/dist/adapters/claude.js +98 -2
  7. package/dist/adapters/claude.js.map +1 -1
  8. package/dist/adapters/codex.d.ts +8 -2
  9. package/dist/adapters/codex.d.ts.map +1 -1
  10. package/dist/adapters/codex.js +24 -5
  11. package/dist/adapters/codex.js.map +1 -1
  12. package/dist/adapters/hosted.d.ts +13 -1
  13. package/dist/adapters/hosted.d.ts.map +1 -1
  14. package/dist/adapters/hosted.js +25 -3
  15. package/dist/adapters/hosted.js.map +1 -1
  16. package/dist/checks.d.ts +10 -1
  17. package/dist/checks.d.ts.map +1 -1
  18. package/dist/checks.js +12 -0
  19. package/dist/checks.js.map +1 -1
  20. package/dist/client.d.ts +10 -1
  21. package/dist/client.d.ts.map +1 -1
  22. package/dist/client.js +16 -0
  23. package/dist/client.js.map +1 -1
  24. package/dist/dispatcher.d.ts +157 -4
  25. package/dist/dispatcher.d.ts.map +1 -1
  26. package/dist/dispatcher.js +644 -41
  27. package/dist/dispatcher.js.map +1 -1
  28. package/dist/errors.d.ts +1 -1
  29. package/dist/errors.d.ts.map +1 -1
  30. package/dist/errors.js.map +1 -1
  31. package/dist/host.d.ts +3 -1
  32. package/dist/host.d.ts.map +1 -1
  33. package/dist/host.js +1 -0
  34. package/dist/host.js.map +1 -1
  35. package/dist/index.d.ts +8 -6
  36. package/dist/index.d.ts.map +1 -1
  37. package/dist/index.js +5 -3
  38. package/dist/index.js.map +1 -1
  39. package/dist/inputs.d.ts +67 -3
  40. package/dist/inputs.d.ts.map +1 -1
  41. package/dist/inputs.js +26 -1
  42. package/dist/inputs.js.map +1 -1
  43. package/dist/job-record.d.ts +25 -0
  44. package/dist/job-record.d.ts.map +1 -1
  45. package/dist/job-record.js +19 -1
  46. package/dist/job-record.js.map +1 -1
  47. package/dist/letters.d.ts +1 -1
  48. package/dist/letters.d.ts.map +1 -1
  49. package/dist/letters.js +4 -0
  50. package/dist/letters.js.map +1 -1
  51. package/dist/limit.d.ts +37 -0
  52. package/dist/limit.d.ts.map +1 -0
  53. package/dist/limit.js +189 -0
  54. package/dist/limit.js.map +1 -0
  55. package/dist/protocol.d.ts +8 -1
  56. package/dist/protocol.d.ts.map +1 -1
  57. package/dist/protocol.js +6 -1
  58. package/dist/protocol.js.map +1 -1
  59. package/dist/recipes/built-in.d.ts.map +1 -1
  60. package/dist/recipes/built-in.js +6 -2
  61. package/dist/recipes/built-in.js.map +1 -1
  62. package/dist/recipes/debate.d.ts.map +1 -1
  63. package/dist/recipes/debate.js +3 -1
  64. package/dist/recipes/debate.js.map +1 -1
  65. package/dist/recipes/race.d.ts.map +1 -1
  66. package/dist/recipes/race.js +3 -1
  67. package/dist/recipes/race.js.map +1 -1
  68. package/dist/recipes/steps.d.ts +14 -11
  69. package/dist/recipes/steps.d.ts.map +1 -1
  70. package/dist/recipes/steps.js +34 -21
  71. package/dist/recipes/steps.js.map +1 -1
  72. package/dist/registry.d.ts +15 -2
  73. package/dist/registry.d.ts.map +1 -1
  74. package/dist/registry.js +18 -2
  75. package/dist/registry.js.map +1 -1
  76. package/dist/scoreboard.d.ts +169 -0
  77. package/dist/scoreboard.d.ts.map +1 -0
  78. package/dist/scoreboard.js +328 -0
  79. package/dist/scoreboard.js.map +1 -0
  80. package/dist/server.d.ts.map +1 -1
  81. package/dist/server.js +10 -1
  82. package/dist/server.js.map +1 -1
  83. package/dist/setup/claude.d.ts +3 -1
  84. package/dist/setup/claude.d.ts.map +1 -1
  85. package/dist/setup/claude.js +8 -2
  86. package/dist/setup/claude.js.map +1 -1
  87. package/dist/store/sqlite.d.ts +4 -1
  88. package/dist/store/sqlite.d.ts.map +1 -1
  89. package/dist/store/sqlite.js +20 -1
  90. package/dist/store/sqlite.js.map +1 -1
  91. package/dist/store/store.d.ts +6 -1
  92. package/dist/store/store.d.ts.map +1 -1
  93. package/dist/tools/guidance.d.ts.map +1 -1
  94. package/dist/tools/guidance.js +1 -0
  95. package/dist/tools/guidance.js.map +1 -1
  96. package/dist/tools/tools.d.ts.map +1 -1
  97. package/dist/tools/tools.js +47 -4
  98. package/dist/tools/tools.js.map +1 -1
  99. package/dist/types.d.ts +107 -2
  100. package/dist/types.d.ts.map +1 -1
  101. package/dist/types.js +35 -0
  102. package/dist/types.js.map +1 -1
  103. package/fakes/claude.mjs +49 -0
  104. package/package.json +2 -1
@@ -1,18 +1,21 @@
1
1
  import { EventEmitter } from 'node:events';
2
2
  import { existsSync } from 'node:fs';
3
3
  import { isAbsolute, resolve as resolvePath } from 'node:path';
4
- import { TaskManager, textPart, toMessage } from '@cogitator-ai/a2a';
4
+ import { TASK_AGENT_KEY, TaskManager, textPart, toMessage } from '@cogitator-ai/a2a';
5
5
  import { MAX_RECALL_LIMIT } from './board.js';
6
6
  import { runCheck, skippedCheck, summarizeChecks } from './checks.js';
7
7
  import { BridgeError } from './errors.js';
8
8
  import { deliveryBackoff, exhaustedBudget, formatDuration, nextDepth, resolveBudget, resolveLimits, } from './guards.js';
9
- import { AgentsFilterSchema, CreateJobInputSchema, DEFAULT_INBOX_LIMIT, DEFAULT_LIST_LIMIT, DEFAULT_VERDICT_WAIT_MS, DEFAULT_WAIT_MS, DeliveredInputSchema, EscalateInputSchema, InboxInputSchema, JobsFilterSchema, JournalQuerySchema, LettersFilterSchema, PersonAnswerInputSchema, SendLetterInputSchema, StuckInputSchema, VerdictInputSchema, VerificationInputSchema, AcceptInputSchema, DiffInputSchema, ForgetInputSchema, RecallInputSchema, RejectInputSchema, RememberInputSchema, WaitInputSchema, WithdrawInputSchema, } from './inputs.js';
9
+ import { AgentsFilterSchema, CreateJobInputSchema, DEFAULT_INBOX_LIMIT, DEFAULT_LIST_LIMIT, DEFAULT_VERDICT_WAIT_MS, DEFAULT_WAIT_MS, DeliveredInputSchema, EscalateInputSchema, InboxInputSchema, JobsFilterSchema, JournalQuerySchema, LettersFilterSchema, LimitedInputSchema, PersonAnswerInputSchema, SendLetterInputSchema, StuckInputSchema, VerdictInputSchema, VerificationInputSchema, AcceptInputSchema, DiffInputSchema, ForgetInputSchema, RecallInputSchema, RejectInputSchema, RememberInputSchema, ResultsInputSchema, SuggestInputSchema, WaitInputSchema, WithdrawInputSchema, } from './inputs.js';
10
+ import { parseFindings } from './findings.js';
10
11
  import { HANDOVER_GAP, buildHandover } from './handover.js';
11
12
  import { isFinishedJobState, jobOf, jobRecordOf } from './job-record.js';
13
+ import { limitClock, limitOf } from './limit.js';
12
14
  import { expectationOf, forHistory, newLetterId, normalizeBody, oneLine, quoted, renderLetter, repeats, titleOf, } from './letters.js';
13
15
  import { canonicalPath, findCheckoutRoot, findProjectRoot, inCheckout, isInside } from './paths.js';
14
16
  import { DISCARDED_REFS, GitError, addJobWorktree, branchTip, busyWith, changesOf, checkoutOf, conflictsOf, patchOf, pointRef, removeJobWorktree, shownPath, snapshotOf, squashInto, } from './worktree.js';
15
- import { allocateAgentName, resolveAddress } from './registry.js';
17
+ import { AUTO_ADDRESS, NEW_SESSION, aliasOfHarness, allocateAgentName, harnessOfAlias, autoAddressOf, resolveAddress, } from './registry.js';
18
+ import { resultOf, suggestFrom, } from './scoreboard.js';
16
19
  import { BRIDGE_JOB_KEY, BRIDGE_SENDER, CallerIdentitySchema, DEFAULT_LIMITS, HarnessNameSchema, INBOX_DELIVERY, NO_CAPABILITIES, PERSON, } from './types.js';
17
20
  const ACTIVE_JOB_STATES = ['submitted', 'working', 'input-required'];
18
21
  const FINISHED_JOB_STATES = ['completed', 'failed', 'canceled'];
@@ -155,6 +158,17 @@ function asError(error) {
155
158
  }
156
159
  /** The ids the conductor of a recipe gives the letters it writes. */
157
160
  const RECIPE_LETTER_ID = /^(recipe|relay)-/;
161
+ /** How many finished jobs the scoreboard reads, the newest: more than a machine ends in its window. */
162
+ const SCORED_JOBS = 5_000;
163
+ /** How far ahead the end of a limit may lie to be believed: a monthly cap resets within this. */
164
+ const LIMIT_MAX_AHEAD_MS = 32 * 86_400_000;
165
+ /** A limit in words: `out of its limit until 15:07 (You've hit your usage limit)`. */
166
+ function limitWords(limit, now) {
167
+ const until = limitClock(Date.parse(limit.until), now);
168
+ return `out of its limit until ${until}${limit.told ? '' : ', when the bridge tries it again'}${limit.detail ? ` (${limit.detail})` : ''}`;
169
+ }
170
+ /** How many reviews of its work the record of a job keeps, the first ones. */
171
+ const REVIEWS_KEPT = 20;
158
172
  const NO_CONDUCTOR = 'This bridge carries out no recipes: its host gave it no conductor (recipeAdapter of @cogitator-ai/bridge/recipes)';
159
173
  /** `work`, or a rejection when it takes longer than `ms`. */
160
174
  function within(work, ms, what) {
@@ -202,8 +216,11 @@ export class BridgeDispatcher extends EventEmitter {
202
216
  rights;
203
217
  person;
204
218
  board;
219
+ fallback;
205
220
  /** When each agent's other parties were last told it waits at its window, see `stuck` */
206
221
  stuckTold = new Map();
222
+ /** The agents a listing of their harness showed waiting at their window, until it shows them not */
223
+ stuckNow = new Set();
207
224
  /** Those waiting for the verdict of a permission request, by its id, see `verdict` */
208
225
  verdictWaiters = new Map();
209
226
  /** What the person route is told, one thing after another */
@@ -227,6 +244,10 @@ export class BridgeDispatcher extends EventEmitter {
227
244
  * adapter reports back, since it may have handed the job's first letter over itself
228
245
  */
229
246
  starting = new Set();
247
+ /** Session starts that wait their turn, see `startSession` */
248
+ startQueue = [];
249
+ /** How many sessions adapters are starting right now */
250
+ startsRunning = 0;
230
251
  /** The waiter of each agent that has one, see `wait` */
231
252
  waiters = new Map();
232
253
  /**
@@ -254,6 +275,7 @@ export class BridgeDispatcher extends EventEmitter {
254
275
  this.rights = options.rights;
255
276
  this.person = options.person;
256
277
  this.board = options.board;
278
+ this.fallback = (options.routing?.fallback ?? []).map((harness) => parse(HarnessNameSchema, harness, 'Cannot use the fallback'));
257
279
  for (const adapter of options.adapters ?? []) {
258
280
  const harness = parse(HarnessNameSchema, adapter.harness, 'Cannot use the adapter');
259
281
  if (this.adapters.has(harness)) {
@@ -358,6 +380,11 @@ export class BridgeDispatcher extends EventEmitter {
358
380
  async createJob(caller, input) {
359
381
  const request = parse(CreateJobInputSchema, input, 'Cannot create the job');
360
382
  this.checkBody(request.body);
383
+ const auto = autoAddressOf(request.to);
384
+ if (auto && request.recipe) {
385
+ throw new BridgeError('invalid_input', `A recipe goes to the conductor of the bridge, not to ${AUTO_ADDRESS}: name ${AUTO_ADDRESS} in the input of the recipe, where it says who does a step`);
386
+ }
387
+ const choice = auto ? await this.choiceFor(caller, request) : undefined;
361
388
  const handover = request.recipe ? undefined : await this.handoverFor(caller, request);
362
389
  const withContext = handover ? `${request.body}${HANDOVER_GAP}${handover}` : request.body;
363
390
  const body = withContext.length <= this.limits.maxBodyLength ? withContext : request.body;
@@ -372,20 +399,44 @@ export class BridgeDispatcher extends EventEmitter {
372
399
  this.taskText(sent) !== request.body) {
373
400
  throw new BridgeError('invalid_letter', `The letter id ${request.letterId} belongs to another letter. Give a new job a new id`, { letter: request.letterId });
374
401
  }
375
- return { job: this.requireJob(sent.job).job, letter: sent, duplicate: true };
402
+ const known = this.requireJob(sent.job).job;
403
+ return {
404
+ job: known,
405
+ letter: sent,
406
+ duplicate: true,
407
+ ...(known.routed && { routed: known.routed }),
408
+ };
376
409
  }
377
410
  }
378
411
  if (request.recipe && this.conductors().length === 0) {
379
412
  throw new BridgeError('invalid_input', NO_CONDUCTOR, { recipe: request.recipe.name });
380
413
  }
381
- const resolution = resolveAddress(this.store, request.to, {
414
+ const addressed = {
382
415
  project: from.project,
383
416
  caller: from.name,
384
417
  now: this.now(),
385
418
  canSpawn: (harness) => this.adapters.get(harness)?.createSession !== undefined,
386
- fresh: request.worktree === true || request.recipe !== undefined,
387
- });
419
+ fresh: request.worktree === true || request.recipe !== undefined || auto?.fresh === true,
420
+ };
421
+ const reviewed = request.reviewOf === undefined ? undefined : this.checkReviewAsked(from, request.reviewOf);
422
+ const taken = choice
423
+ ? this.takeChoice(choice, from, addressed, reviewed && this.store.getAgent(reviewed.to)?.harness)
424
+ : undefined;
425
+ const resolution = taken?.resolution ?? resolveAddress(this.store, request.to, addressed);
388
426
  this.checkRecipeAsked(resolution, request.recipe);
427
+ const limited = this.limitRefusal(resolution);
428
+ if (limited) {
429
+ this.journal(tx, {
430
+ type: 'letter.rejected',
431
+ agent: from.name,
432
+ data: {
433
+ reason: limited.code,
434
+ to: request.to,
435
+ title: request.title ?? titleOf(request.body),
436
+ },
437
+ });
438
+ return new Refusal(limited);
439
+ }
389
440
  if (this.closing && resolution.kind === 'spawn') {
390
441
  throw new BridgeError('not_running', 'The bridge dispatcher is closing and starts no session now. Hand the job over again when it runs');
391
442
  }
@@ -430,7 +481,7 @@ export class BridgeDispatcher extends EventEmitter {
430
481
  if (request.worktree)
431
482
  this.checkWorktreeAsked(from, resolution, cwd);
432
483
  const now = this.now();
433
- const refusal = this.handOverRefusal(from, resolution, request.body, cwd, now);
484
+ const refusal = this.handOverRefusal(from, resolution, request.body, cwd, now, !!taken);
434
485
  if (refusal) {
435
486
  this.journal(tx, {
436
487
  type: 'letter.rejected',
@@ -473,7 +524,10 @@ export class BridgeDispatcher extends EventEmitter {
473
524
  project: from.project,
474
525
  cwd,
475
526
  ...(body !== request.body && { taskLength: request.body.length }),
527
+ ...(request.type && { type: request.type }),
476
528
  ...(request.recipe && { recipe: request.recipe }),
529
+ ...(request.reviewOf !== undefined && { reviewOf: request.reviewOf }),
530
+ ...(taken && { routed: taken.reason }),
477
531
  ...(request.worktree && { isolation: 'worktree' }),
478
532
  checks: request.checks ?? [],
479
533
  budget,
@@ -493,7 +547,15 @@ export class BridgeDispatcher extends EventEmitter {
493
547
  type: 'job.created',
494
548
  job: number,
495
549
  agent: from.name,
496
- data: { title: record.title, from: from.name, to: to.name, depth, cwd },
550
+ data: {
551
+ title: record.title,
552
+ from: from.name,
553
+ to: to.name,
554
+ depth,
555
+ cwd,
556
+ ...(record.type && { type: record.type }),
557
+ ...(taken && { routed: taken.reason }),
558
+ },
497
559
  });
498
560
  const letter = this.acceptLetter(tx, {
499
561
  id: firstLetterId,
@@ -508,7 +570,12 @@ export class BridgeDispatcher extends EventEmitter {
508
570
  tx.wake.delete(to.name);
509
571
  tx.spawns.push({ agent: to.name, job: number, letter: letter.id });
510
572
  }
511
- return { job: this.jobFrom(task), letter, duplicate: false };
573
+ return {
574
+ job: this.jobFrom(task),
575
+ letter,
576
+ duplicate: false,
577
+ ...(taken && { routed: taken.reason }),
578
+ };
512
579
  });
513
580
  if (outcome instanceof Refusal)
514
581
  throw outcome.error;
@@ -609,7 +676,7 @@ export class BridgeDispatcher extends EventEmitter {
609
676
  const reason = exhausted === 'letters'
610
677
  ? `the job used all ${job.budget.letters} letters of its budget`
611
678
  : ranOutOfTime(job);
612
- await this.failJob(tx, job.number, reason);
679
+ await this.failJob(tx, job.number, reason, exhausted === 'letters' ? 'other' : 'timeout');
613
680
  return new Refusal(new BridgeError('budget_exhausted', `Job ${job.number} has failed: ${reason}. The letter was not delivered`, {
614
681
  job: job.number,
615
682
  exhausted,
@@ -656,6 +723,7 @@ export class BridgeDispatcher extends EventEmitter {
656
723
  if (forPerson) {
657
724
  tx.asked.push({ letter: letter.id, again: false });
658
725
  await this.startWaiting(job.number, now);
726
+ await this.neededPerson(job.number);
659
727
  }
660
728
  if (answered && request.kind === 'answer') {
661
729
  this.markHandled(tx, answered);
@@ -666,14 +734,25 @@ export class BridgeDispatcher extends EventEmitter {
666
734
  }
667
735
  if (request.kind === 'report') {
668
736
  const state = letter.outcome === 'failed' ? 'failed' : 'completed';
737
+ if (state === 'completed') {
738
+ this.liftLimit(tx, from.harness, `${from.name} finished a job`);
739
+ }
669
740
  await this.transition(tx, job.number, state, forHistory(request.body, letter.id));
670
741
  if (state === 'failed')
671
- await this.patchRecord(job.taskId, { reason: `reported as failed by ${from.name}` });
742
+ await this.patchRecord(job.taskId, {
743
+ reason: `reported as failed by ${from.name}`,
744
+ failure: 'reported',
745
+ });
672
746
  if (changes && job.worktree && !job.worktree.end) {
673
747
  await this.patchRecord(job.taskId, { changes });
674
748
  }
675
- if (request.findings)
676
- await this.patchRecord(job.taskId, { findings: request.findings });
749
+ const findings = request.findings ??
750
+ (job.reviewOf !== undefined ? parseFindings(request.body) : undefined);
751
+ if (findings)
752
+ await this.patchRecord(job.taskId, { findings });
753
+ if (findings && state === 'completed' && job.reviewOf !== undefined) {
754
+ await this.noteReview(job, from.name, findings, now);
755
+ }
677
756
  if (state === 'completed' && job.checks.length > 0) {
678
757
  this.store.updateLetter(letter.id, { state: 'held' });
679
758
  await this.patchRecord(job.taskId, {
@@ -760,6 +839,7 @@ export class BridgeDispatcher extends EventEmitter {
760
839
  });
761
840
  tx.asked.push({ letter: letter.id, again: false });
762
841
  await this.startWaiting(job.number, now);
842
+ await this.neededPerson(job.number);
763
843
  return updated;
764
844
  });
765
845
  }
@@ -819,13 +899,17 @@ export class BridgeDispatcher extends EventEmitter {
819
899
  */
820
900
  async stuck(caller, input) {
821
901
  const request = parse(StuckInputSchema, input, 'Cannot note that the session waits');
822
- return this.asCaller(caller, async (tx) => this.noteStuck(tx, this.requireCaller(caller), request.what));
902
+ return this.asCaller(caller, async (tx) => this.noteStuck(tx, this.requireCaller(caller), request.what, 'hook'));
823
903
  }
824
- noteStuck(tx, agent, what) {
904
+ /**
905
+ * Notes that a session waits for a person at its own window. `seen` says how the bridge
906
+ * learned of it: a `hook` runs once for each dialog, a `listing` of the harness shows the same
907
+ * wait again every time it is asked, so only the first sight of it counts as one more time
908
+ * the jobs of the session needed the person. Whoever handed those jobs over is told, and not
909
+ * again within `limits.windowNoticeMs`.
910
+ */
911
+ async noteStuck(tx, agent, what, seen) {
825
912
  const now = this.now();
826
- const told = this.stuckTold.get(agent.name);
827
- if (told !== undefined && now - told < this.limits.windowNoticeMs)
828
- return [];
829
913
  const jobs = this.store
830
914
  .jobTasks({ to: agent.name, states: ACTIVE_JOB_STATES })
831
915
  .flatMap((task) => jobOf(task) ?? [])
@@ -833,6 +917,14 @@ export class BridgeDispatcher extends EventEmitter {
833
917
  .sort((a, b) => a.number - b.number);
834
918
  if (jobs.length === 0)
835
919
  return [];
920
+ const again = seen === 'listing' && this.stuckNow.has(agent.name);
921
+ this.stuckNow.add(agent.name);
922
+ if (!again)
923
+ for (const job of jobs)
924
+ await this.neededPerson(job.number);
925
+ const told = this.stuckTold.get(agent.name);
926
+ if (told !== undefined && now - told < this.limits.windowNoticeMs)
927
+ return [];
836
928
  this.stuckTold.set(agent.name, now);
837
929
  for (const job of jobs) {
838
930
  this.systemNote(tx, job, job.from, `${agent.name} waits for a person at its own window, and job #${job.number} stands still until they answer there. It shows:\n${quoted(what)}\nNobody can answer that from here. If the user is with you, tell them in one line.`);
@@ -1443,6 +1535,194 @@ export class BridgeDispatcher extends EventEmitter {
1443
1535
  .filter((adapter) => adapter.recipeProblem !== undefined)
1444
1536
  .map((adapter) => adapter.harness);
1445
1537
  }
1538
+ /**
1539
+ * A review names the job it reviews, and only somebody with a say in that job may: one of its
1540
+ * two agents, whoever handed it over, or the conductor of a recipe, which reviews by the word
1541
+ * of whoever started it.
1542
+ */
1543
+ checkReviewAsked(from, reviewed) {
1544
+ const { job } = this.requireJob(reviewed);
1545
+ if (job.recipe) {
1546
+ throw new BridgeError('invalid_input', `Job ${reviewed} is a recipe: review the job of the step that did the work`, { job: reviewed });
1547
+ }
1548
+ const party = from.name === job.from || from.name === job.to;
1549
+ if (party || this.conducts(from) || this.handedOver(from.name, job))
1550
+ return job;
1551
+ throw new BridgeError('not_a_party', `Job ${reviewed} is between ${job.from} and ${job.to}: only they, or whoever handed it over, have its work reviewed`, { job: reviewed });
1552
+ }
1553
+ /**
1554
+ * Counts what a review found on the record of the job it reviewed, once for each review. A
1555
+ * review by the agent that did the work, and one that agent had made of its own work, count
1556
+ * for nothing: nobody rates itself. The first reviews of a job are the ones kept, so a later
1557
+ * one cannot push an earlier one out.
1558
+ */
1559
+ async noteReview(review, by, findings, now) {
1560
+ if (review.reviewOf === undefined)
1561
+ return;
1562
+ const task = this.store.taskOfJob(review.reviewOf);
1563
+ const reviewed = task && jobOf(task);
1564
+ if (!reviewed || by === reviewed.to || this.ruledBy(review) === reviewed.to)
1565
+ return;
1566
+ const known = reviewed.reviews ?? [];
1567
+ if (known.length >= REVIEWS_KEPT || known.some((kept) => kept.job === review.number))
1568
+ return;
1569
+ const counted = {
1570
+ job: review.number,
1571
+ by,
1572
+ at: this.iso(now),
1573
+ blocker: 0,
1574
+ major: 0,
1575
+ minor: 0,
1576
+ nit: 0,
1577
+ };
1578
+ for (const finding of findings)
1579
+ counted[finding.severity] += 1;
1580
+ await this.patchRecord(reviewed.taskId, { reviews: [...known, counted] });
1581
+ }
1582
+ /** Notes that a job needed the person once more: the scoreboard counts how often it did. */
1583
+ async neededPerson(number) {
1584
+ const { job } = this.requireJob(number);
1585
+ await this.patchRecord(job.taskId, { personNeeded: (job.personNeeded ?? 0) + 1 });
1586
+ }
1587
+ /** The harnesses a job can be handed to with nobody named, in the order of the adapters. */
1588
+ routable() {
1589
+ return [...this.adapters.values()]
1590
+ .filter((adapter) => adapter.createSession !== undefined && !adapter.recipeProblem)
1591
+ .map((adapter) => adapter.harness);
1592
+ }
1593
+ /**
1594
+ * What became of the jobs that ended within the window of the scoreboard, newest first. The
1595
+ * window is measured from when a job ended, whenever it was handed over, among the newest
1596
+ * `SCORED_JOBS` finished jobs.
1597
+ */
1598
+ scored() {
1599
+ const harnesses = new Map();
1600
+ const harnessOf = (agent) => {
1601
+ if (!harnesses.has(agent))
1602
+ harnesses.set(agent, this.store.getAgent(agent)?.harness);
1603
+ return harnesses.get(agent);
1604
+ };
1605
+ const since = this.now() - this.limits.scoreWindowMs;
1606
+ return this.store
1607
+ .jobTasks({ states: ['completed', 'failed'], limit: SCORED_JOBS })
1608
+ .flatMap((task) => {
1609
+ const job = jobOf(task);
1610
+ const harness = job && harnessOf(job.to);
1611
+ if (!job || !harness || this.adapters.get(harness)?.recipeProblem)
1612
+ return [];
1613
+ const result = resultOf(job, harness);
1614
+ return result && Date.parse(result.endedAt) >= since ? [result] : [];
1615
+ });
1616
+ }
1617
+ /**
1618
+ * Who a job handed to `auto` goes to, worked out before the job is created: the suggestion of
1619
+ * the scoreboard, and the sessions of the caller's project that would not wake for a letter,
1620
+ * which `auto` passes over for a fresh session. Undefined for a job that was handed over
1621
+ * before under the same letter id: it is with whoever got it then.
1622
+ */
1623
+ async choiceFor(caller, request) {
1624
+ const { letterId, type } = request;
1625
+ const known = await this.enqueue(async () => ({
1626
+ sent: letterId !== undefined && this.store.getLetter(letterId) !== undefined,
1627
+ project: this.store.getAgent(caller)?.project,
1628
+ harnesses: this.routable(),
1629
+ }));
1630
+ if (known.sent)
1631
+ return undefined;
1632
+ const suggestion = await this.suggest(type === undefined ? {} : { type });
1633
+ const { project, harnesses } = known;
1634
+ const sessions = project === undefined
1635
+ ? []
1636
+ : await this.enqueue(async () => this.store
1637
+ .listAgents({ project, statuses: ['active'] })
1638
+ .filter((agent) => agent.name !== caller && harnesses.includes(agent.harness)));
1639
+ const asleep = new Set();
1640
+ for (const agent of sessions) {
1641
+ if (!(await this.wakes(agent.name)))
1642
+ asleep.add(agent.name);
1643
+ }
1644
+ return { suggestion, asleep };
1645
+ }
1646
+ /** The agents a caller works for: those that handed it its jobs, and those above them. */
1647
+ worksFor(caller) {
1648
+ const above = new Set();
1649
+ for (const task of this.store.jobTasks({ to: caller, states: ACTIVE_JOB_STATES })) {
1650
+ const job = jobOf(task);
1651
+ if (!job)
1652
+ continue;
1653
+ for (const link of this.chainOf(job.number))
1654
+ above.add(link.from);
1655
+ }
1656
+ return above;
1657
+ }
1658
+ /**
1659
+ * Finds the agent a job handed to `auto` goes to: the best of the suggestion first, then the
1660
+ * others a job can go to. Each is tried by its harness word, and by a fresh session where the
1661
+ * session that is there would not wake, several fit, or the session is one the caller works
1662
+ * for, which would then wait for the caller while the caller waits for it. A harness the
1663
+ * bridge cannot start a session of right now is passed over for the next. `avoid` names a
1664
+ * harness to take after the others: the one that did the work a review is of. The harnesses
1665
+ * of last resort come after all of those, so one of them takes the job only when no other
1666
+ * harness could, whether that one ran into its limit or simply has no session to give.
1667
+ *
1668
+ * @throws BridgeError `no_session` when the job can go to none of them
1669
+ */
1670
+ takeChoice(choice, from, context, avoid) {
1671
+ const { suggestion, asleep } = choice;
1672
+ const open = suggestion.candidates.filter((candidate) => candidate.available);
1673
+ const first = open.find((candidate) => candidate.harness === suggestion.best);
1674
+ const ranked = first ? [first, ...open.filter((candidate) => candidate !== first)] : open;
1675
+ const rank = (candidate) => (candidate.lastResort ? 2 : 0) + (candidate.harness === avoid ? 1 : 0);
1676
+ const order = [...ranked].sort((a, b) => rank(a) - rank(b));
1677
+ const above = this.worksFor(from.name);
1678
+ const passed = [];
1679
+ for (const candidate of order) {
1680
+ const name = aliasOfHarness(candidate.harness);
1681
+ let refused;
1682
+ for (const address of [candidate.harness, `${candidate.harness}:${NEW_SESSION}`]) {
1683
+ let resolution;
1684
+ try {
1685
+ resolution = resolveAddress(this.store, address, context);
1686
+ }
1687
+ catch (error) {
1688
+ if (!(error instanceof BridgeError) ||
1689
+ (error.code !== 'ambiguous_agent' && error.code !== 'no_session')) {
1690
+ throw error;
1691
+ }
1692
+ if (error.code === 'no_session')
1693
+ refused = error.message;
1694
+ continue;
1695
+ }
1696
+ if (resolution.kind === 'agent') {
1697
+ const { agent } = resolution;
1698
+ if (asleep.has(agent.name) || above.has(agent.name))
1699
+ continue;
1700
+ }
1701
+ else {
1702
+ const full = this.startingRefusal();
1703
+ if (full) {
1704
+ refused = full.message;
1705
+ continue;
1706
+ }
1707
+ }
1708
+ const reason = candidate.harness === suggestion.best
1709
+ ? suggestion.reason
1710
+ : `${suggestion.reason}. ${passed.length > 0
1711
+ ? `The job could not go there (${passed.join('. ')})`
1712
+ : `${aliasOfHarness(avoid ?? '')} did the work this job reviews`}, so ${name} took it`;
1713
+ return { resolution, reason };
1714
+ }
1715
+ passed.push(`${name}: ${refused ?? 'its session would not wake for the job'}`);
1716
+ }
1717
+ throw new BridgeError('no_session', `${AUTO_ADDRESS} found no agent the job can go to. ${passed.length > 0 ? passed.join('. ') : suggestion.reason}`, { harnesses: order.map((candidate) => candidate.harness) });
1718
+ }
1719
+ /** Why the bridge starts no session right now, when too many are being started already. */
1720
+ startingRefusal() {
1721
+ const starting = this.store.listAgents({ statuses: ['starting'] }).length;
1722
+ if (starting < this.limits.maxStartingSessions)
1723
+ return undefined;
1724
+ return new BridgeError('no_session', `The bridge is already starting ${starting} sessions, the most at once. Hand the job over again when they are up`, { starting, max: this.limits.maxStartingSessions });
1725
+ }
1446
1726
  /**
1447
1727
  * Refuses a recipe the conductor cannot start, and a job for the conductor that names none.
1448
1728
  * Every recipe gets a conductor of its own, so a recipe is addressed by the harness word of
@@ -2313,6 +2593,286 @@ export class BridgeDispatcher extends EventEmitter {
2313
2593
  return fitting(this.store.readJournal({ ...request, limit: request.limit ?? DEFAULT_LIST_LIMIT }), size);
2314
2594
  });
2315
2595
  }
2596
+ /**
2597
+ * Notes that the harness of the calling session ran into the limit of its subscription or its
2598
+ * key: an adapter says so when a turn fails with it, a hook of the harness when the harness
2599
+ * tells one. Until the limit is over (the time the harness named, `limits.limitRetryMs` from
2600
+ * now when it named none) no job is handed to that harness: `auto` passes it over, and a job
2601
+ * addressed to it is refused with `limit_reached`. The jobs the session carries out go to
2602
+ * another agent, the one `suggest` names for their type among those that take jobs, with what
2603
+ * the session left in the folder of each. A job nobody else can take fails, and not by the
2604
+ * doing of its agent.
2605
+ *
2606
+ * A time that is past, or further ahead than a limit lasts, is taken for no time at all.
2607
+ *
2608
+ * @throws BridgeError `not_registered`
2609
+ */
2610
+ async limited(caller, input = {}) {
2611
+ const request = parse(LimitedInputSchema, input, 'Cannot note the limit');
2612
+ const now = this.now();
2613
+ const said = request.until === undefined ? undefined : Date.parse(request.until);
2614
+ const until = said !== undefined && said > now && said - now <= LIMIT_MAX_AHEAD_MS ? said : undefined;
2615
+ await this.asCaller(caller, async () => this.requireCaller(caller));
2616
+ return this.outOfLimit(caller, { ...(until !== undefined && { until }), detail: request.detail ?? '' }, false);
2617
+ }
2618
+ /** The harnesses that are out of their limit right now. */
2619
+ async limitsInForce() {
2620
+ return this.enqueue(async () => this.limitsNow());
2621
+ }
2622
+ /**
2623
+ * Takes the limit of a harness back before its time: the person knows it is over, such as
2624
+ * after they changed their plan. `agent` is a harness word (`codex`, `claude`) or the name of
2625
+ * one of its agents. Returns whether there was a limit.
2626
+ *
2627
+ * @throws BridgeError `unknown_agent` for a name nobody has
2628
+ */
2629
+ async unlimit(agent) {
2630
+ return this.mutate(async (tx) => {
2631
+ const harness = agent.includes('@')
2632
+ ? this.store.getAgent(agent.trim())?.harness
2633
+ : parse(HarnessNameSchema, harnessOfAlias(agent), 'Cannot lift the limit');
2634
+ if (harness === undefined) {
2635
+ throw new BridgeError('unknown_agent', `There is no agent ${agent}`, { address: agent });
2636
+ }
2637
+ return this.liftLimit(tx, harness, 'the person said it is over');
2638
+ });
2639
+ }
2640
+ limitsNow() {
2641
+ const now = this.now();
2642
+ return this.store.listLimits().filter((limit) => Date.parse(limit.until) > now);
2643
+ }
2644
+ limitOfHarness(harness) {
2645
+ return this.limitsNow().find((limit) => limit.harness === harness);
2646
+ }
2647
+ /** Why a job cannot go to the harness an address names, when that harness is out of its limit. */
2648
+ limitRefusal(resolution) {
2649
+ const harness = resolution.kind === 'agent' ? resolution.agent.harness : resolution.harness;
2650
+ const limit = this.limitOfHarness(harness);
2651
+ if (!limit)
2652
+ return undefined;
2653
+ return new BridgeError('limit_reached', `${aliasOfHarness(harness)} is ${limitWords(limit, this.now())}. Hand the job to another agent, or to ${AUTO_ADDRESS} for the one that takes jobs now`, { harness, until: limit.until });
2654
+ }
2655
+ /** Forgets the limit of a harness. Returns whether it had one. */
2656
+ liftLimit(tx, harness, why) {
2657
+ if (!this.store.listLimits().some((limit) => limit.harness === harness))
2658
+ return false;
2659
+ this.store.dropLimit(harness);
2660
+ this.journal(tx, { type: 'harness.unlimited', data: { harness, why } });
2661
+ return true;
2662
+ }
2663
+ /**
2664
+ * What the bridge does when the harness of an agent ran into its limit: notes the limit, and
2665
+ * hands the jobs the agent carries out to others. A limit that is noted already stays as it is
2666
+ * unless the new one lasts longer: a session that names no time must not cut short the time
2667
+ * another one named. `unstarted` says the session never came up, so the agent is gone and not
2668
+ * merely out of work. So is the session of a harness that waits for its mail itself, such as
2669
+ * Claude Code: a turn that ended on an error runs no hook that waits, so nothing wakes the
2670
+ * session until a person opens it, and it is back in the book as soon as it calls.
2671
+ */
2672
+ async outOfLimit(agentName, signal, unstarted) {
2673
+ const noted = await this.mutate(async (tx) => {
2674
+ const agent = this.store.getAgent(agentName);
2675
+ if (!agent)
2676
+ throw new BridgeError('not_registered', `There is no agent ${agentName}`);
2677
+ const now = this.now();
2678
+ const before = this.limitOfHarness(agent.harness);
2679
+ const until = signal.until ?? now + this.limits.limitRetryMs;
2680
+ const limit = before && Date.parse(before.until) >= until
2681
+ ? before
2682
+ : {
2683
+ harness: agent.harness,
2684
+ until: this.iso(until),
2685
+ told: signal.until !== undefined,
2686
+ detail: oneLine(signal.detail).slice(0, 300),
2687
+ since: before?.since ?? this.iso(now),
2688
+ agent: agent.name,
2689
+ };
2690
+ this.store.putLimit(limit);
2691
+ const adapter = this.adapters.get(agent.harness);
2692
+ const deaf = adapter !== undefined && adapter.deliver === undefined;
2693
+ if ((unstarted && agent.status === 'starting') || (deaf && agent.status === 'active')) {
2694
+ this.waiters.get(agent.name)?.end('closed');
2695
+ this.store.putAgent({ ...agent, status: 'gone' });
2696
+ this.journal(tx, {
2697
+ type: 'agent.gone',
2698
+ agent: agent.name,
2699
+ data: {
2700
+ error: unstarted
2701
+ ? `the ${agent.harness} session did not start: ${limit.detail}`
2702
+ : `its turn ended on the limit of ${agent.harness}, and nothing wakes the session until it is opened again`,
2703
+ },
2704
+ });
2705
+ }
2706
+ const jobs = this.store
2707
+ .jobTasks({ to: agent.name, states: ACTIVE_JOB_STATES })
2708
+ .flatMap((task) => jobOf(task) ?? [])
2709
+ .sort((a, b) => a.number - b.number);
2710
+ this.journal(tx, {
2711
+ type: 'harness.limited',
2712
+ agent: agent.name,
2713
+ data: {
2714
+ harness: agent.harness,
2715
+ until: limit.until,
2716
+ told: limit.told,
2717
+ detail: limit.detail,
2718
+ },
2719
+ });
2720
+ if (!before) {
2721
+ tx.notices.push({
2722
+ agent: agent.name,
2723
+ jobs,
2724
+ text: `${aliasOfHarness(agent.harness)} is ${limitWords(limit, now)}. The bridge hands it no job until then${jobs.length > 0 ? ', and its jobs go to other agents' : ''}`,
2725
+ });
2726
+ }
2727
+ return { agent, limit, jobs: jobs.map((job) => ({ number: job.number, type: job.type })) };
2728
+ });
2729
+ const redirected = [];
2730
+ const failed = [];
2731
+ for (const job of noted.jobs) {
2732
+ const suggestion = await this.suggest(job.type === undefined ? {} : { type: job.type });
2733
+ const to = await this.mutate((tx) => this.redirect(tx, job.number, noted.agent, noted.limit, suggestion));
2734
+ if (to === undefined)
2735
+ continue;
2736
+ if (to === null)
2737
+ failed.push(job.number);
2738
+ else
2739
+ redirected.push({ job: job.number, to });
2740
+ }
2741
+ return { limit: noted.limit, redirected, failed };
2742
+ }
2743
+ /**
2744
+ * Hands a job whose agent ran into the limit of its harness to a fresh session of another
2745
+ * harness, which goes on in the folder of the job with what is there and gets the time of the
2746
+ * job anew. The letters of the job that waited are done with, the jobs handed over from inside
2747
+ * it are canceled, and whoever handed the job over is told. The agent that had it is told only
2748
+ * when its sessions fetch their mail themselves: a letter pushed to a session that is out of
2749
+ * its limit would start a turn that fails on it again. Returns the new agent, null when nobody
2750
+ * could take the job and it failed, undefined when the job needs no new agent any more.
2751
+ */
2752
+ async redirect(tx, number, old, limit, suggestion) {
2753
+ const { job } = this.requireJob(number);
2754
+ if (isFinishedJobState(job.state) || job.to !== old.name)
2755
+ return undefined;
2756
+ const now = this.now();
2757
+ const next = suggestion.candidates
2758
+ .filter((candidate) => candidate.available && candidate.harness !== old.harness)
2759
+ .sort((a, b) => Number(b.harness === suggestion.best) - Number(a.harness === suggestion.best) ||
2760
+ Number(a.lastResort === true) - Number(b.lastResort === true))
2761
+ .find((candidate) => this.adapters.get(candidate.harness)?.createSession !== undefined);
2762
+ const why = `ran into the limit of ${aliasOfHarness(old.harness)} (${limit.detail || 'it takes no more requests'})`;
2763
+ if (!next) {
2764
+ await this.failJob(tx, number, `${old.name} ${why}, and no other agent takes jobs now. ${aliasOfHarness(old.harness)} is back at ${limitClock(Date.parse(limit.until), now)}`);
2765
+ return null;
2766
+ }
2767
+ const adapter = this.adapters.get(next.harness);
2768
+ const to = {
2769
+ name: allocateAgentName(this.store, next.harness, job.project),
2770
+ harness: next.harness,
2771
+ sessionId: '',
2772
+ project: job.project,
2773
+ cwd: job.cwd,
2774
+ delivery: adapter?.delivery ?? INBOX_DELIVERY,
2775
+ capabilities: adapter?.capabilities ?? NO_CAPABILITIES,
2776
+ status: 'starting',
2777
+ registeredAt: this.iso(now),
2778
+ lastSeenAt: this.iso(now),
2779
+ };
2780
+ this.store.putAgent(to);
2781
+ this.closeLetters(tx, number);
2782
+ await this.stopWaiting(number, now, false);
2783
+ await this.cancelChildren(tx, job);
2784
+ if (job.state === 'input-required') {
2785
+ await this.transition(tx, number, 'working', `Handed to ${to.name}`);
2786
+ }
2787
+ const task = await this.store.tasks.get(job.taskId);
2788
+ const record = task && jobRecordOf(task);
2789
+ if (!task || !record)
2790
+ throw new BridgeError('storage', `Job ${number} lost its record`);
2791
+ const { reportAskedAt: _asked, ...kept } = record;
2792
+ const parent = record.parent === undefined ? undefined : this.jobIfAny(record.parent);
2793
+ await this.store.tasks.update(job.taskId, {
2794
+ metadata: {
2795
+ ...task.metadata,
2796
+ [TASK_AGENT_KEY]: to.name,
2797
+ [BRIDGE_JOB_KEY]: {
2798
+ ...kept,
2799
+ to: to.name,
2800
+ lettersUsed: record.lettersUsed + 1,
2801
+ deadlineAt: this.iso(Math.min(now + record.budget.durationMs, parent ? Date.parse(parent.deadlineAt) : Infinity)),
2802
+ redirects: [
2803
+ ...(record.redirects ?? []),
2804
+ { from: old.name, to: to.name, at: this.iso(now), why },
2805
+ ],
2806
+ },
2807
+ },
2808
+ });
2809
+ const [first] = this.store.listLetters({ job: number, kinds: ['task'], limit: 1 });
2810
+ if (!first)
2811
+ throw new BridgeError('storage', `The first letter of job ${number} is lost`);
2812
+ const letter = this.acceptLetter(tx, {
2813
+ id: this.letterId(),
2814
+ job: number,
2815
+ kind: 'task',
2816
+ from: job.from,
2817
+ to: to.name,
2818
+ body: first.body,
2819
+ replyDueAt: this.iso(now + job.budget.replyTimeoutMs),
2820
+ });
2821
+ tx.wake.delete(to.name);
2822
+ tx.spawns.push({ agent: to.name, job: number, letter: letter.id });
2823
+ const fresh = this.requireJob(number).job;
2824
+ this.journal(tx, {
2825
+ type: 'job.redirected',
2826
+ job: number,
2827
+ agent: old.name,
2828
+ data: { from: old.name, to: to.name, why },
2829
+ });
2830
+ this.systemNote(tx, fresh, job.from, `Job #${number}: ${old.name} ${why}, so the bridge handed the job to ${to.name}, which goes on in the folder of the job with what is there. Its questions and its report come from ${to.name} now. Nothing for you to do.`);
2831
+ if (this.adapters.get(old.harness)?.deliver === undefined) {
2832
+ this.systemNote(tx, fresh, old.name, `Job #${number} is no longer yours: your harness ran into its limit, and the bridge handed the job to ${to.name}. Stop working on it.`);
2833
+ }
2834
+ return to.name;
2835
+ }
2836
+ /**
2837
+ * What became of the jobs that ended within the window of the scoreboard
2838
+ * (`limits.scoreWindowMs`), newest first: who carried each out, its type, whether anything
2839
+ * confirmed its result, what its reviews found, how long it took, how many letters, and how
2840
+ * many times it needed the person. Canceled jobs and recipes are not among them.
2841
+ */
2842
+ async results(input = {}) {
2843
+ const request = parse(ResultsInputSchema, input, 'Cannot list the results');
2844
+ return this.enqueue(async () => this.scored()
2845
+ .filter((result) => (request.type === undefined || result.type === request.type) &&
2846
+ (request.harness === undefined || result.harness === request.harness) &&
2847
+ (request.agent === undefined || result.agent === request.agent))
2848
+ .slice(0, request.limit ?? DEFAULT_LIST_LIMIT));
2849
+ }
2850
+ /**
2851
+ * Who a job should go to, by how earlier jobs went: every harness the bridge can start a
2852
+ * session of with its rate of jobs that held and the interval of that rate, the one `auto`
2853
+ * would take now, and why. With too few checked jobs it says so, and goes by the order of the
2854
+ * adapters instead of a rating it does not have.
2855
+ */
2856
+ async suggest(input = {}) {
2857
+ const request = parse(SuggestInputSchema, input, 'Cannot suggest an agent');
2858
+ const { results, harnesses, limits } = await this.enqueue(async () => ({
2859
+ results: this.scored(),
2860
+ harnesses: this.routable(),
2861
+ limits: new Map(this.limitsNow().map((limit) => [limit.harness, limit])),
2862
+ }));
2863
+ const now = this.now();
2864
+ return suggestFrom(results, {
2865
+ ...(request.type !== undefined && { type: request.type }),
2866
+ minJobs: this.limits.scoreMinJobs,
2867
+ windowMs: this.limits.scoreWindowMs,
2868
+ harnesses,
2869
+ lastResort: this.fallback.filter((harness) => harnesses.includes(harness)),
2870
+ unavailable: (harness) => {
2871
+ const limit = limits.get(harness);
2872
+ return limit && limitWords(limit, now);
2873
+ },
2874
+ });
2875
+ }
2316
2876
  /**
2317
2877
  * The harnesses the bridge can start a session of for a job. The conductor of recipes is none
2318
2878
  * of them: it takes a recipe, not a job.
@@ -2363,6 +2923,7 @@ export class BridgeDispatcher extends EventEmitter {
2363
2923
  .filter((adapter) => adapter.createSession !== undefined && !adapter.recipeProblem)
2364
2924
  .map((adapter) => adapter.harness),
2365
2925
  waiting: [...this.waiters.keys()].sort(),
2926
+ limited: this.limitsNow(),
2366
2927
  }));
2367
2928
  }
2368
2929
  /**
@@ -2386,7 +2947,7 @@ export class BridgeDispatcher extends EventEmitter {
2386
2947
  continue;
2387
2948
  if (this.waitsForPerson(late.number))
2388
2949
  continue;
2389
- await this.failJob(tx, late.number, ranOutOfTime(late));
2950
+ await this.failJob(tx, late.number, ranOutOfTime(late), 'timeout');
2390
2951
  failed.push(late.number);
2391
2952
  }
2392
2953
  for (const letter of this.store.listLetters({ replyDueBy: now })) {
@@ -2439,9 +3000,13 @@ export class BridgeDispatcher extends EventEmitter {
2439
3000
  reminded.push(letter.id);
2440
3001
  continue;
2441
3002
  }
2442
- await this.failJob(tx, job.number, `${letter.to} did not ${pickup ? 'take' : 'answer'} the ${letter.kind} ${letter.id} in ${formatDuration(2 * job.budget.replyTimeoutMs)}`);
3003
+ await this.failJob(tx, job.number, `${letter.to} did not ${pickup ? 'take' : 'answer'} the ${letter.kind} ${letter.id} in ${formatDuration(2 * job.budget.replyTimeoutMs)}`, letter.to === job.to ? 'silent' : 'other');
2443
3004
  failed.push(job.number);
2444
3005
  }
3006
+ for (const limit of this.store.listLimits()) {
3007
+ if (Date.parse(limit.until) <= now)
3008
+ this.liftLimit(tx, limit.harness, 'its time is over');
3009
+ }
2445
3010
  failed.push(...(await this.remindOfReports(tx, now)));
2446
3011
  failed.push(...(await this.retireAgents(tx, now)));
2447
3012
  for (const agent of this.store.queuedRecipients())
@@ -2478,7 +3043,7 @@ export class BridgeDispatcher extends EventEmitter {
2478
3043
  continue;
2479
3044
  if (this.inTurn(this.store.getAgent(job.to)))
2480
3045
  continue;
2481
- await this.failJob(tx, job.number, `${job.to} ended its turn without a report and did not react to the reminder in ${formatDuration(patience)}`);
3046
+ await this.failJob(tx, job.number, `${job.to} ended its turn without a report and did not react to the reminder in ${formatDuration(patience)}`, 'silent');
2482
3047
  failed.push(job.number);
2483
3048
  }
2484
3049
  for (const [name, waiter] of this.waiters) {
@@ -2559,12 +3124,15 @@ export class BridgeDispatcher extends EventEmitter {
2559
3124
  .then((sessions) => this.mutate(async (tx) => {
2560
3125
  await this.applyPresence(tx, harness, new Set(sessions.map((session) => session.sessionId)), adapter.ownsSessions === true, asked, new Set(sessions.flatMap((session) => (session.busy ? [session.sessionId] : []))));
2561
3126
  for (const session of sessions) {
2562
- if (!session.waitingFor)
2563
- continue;
2564
3127
  const agent = this.store.agentOfSession(harness, session.sessionId);
3128
+ if (!session.waitingFor) {
3129
+ if (agent)
3130
+ this.stuckNow.delete(agent.name);
3131
+ continue;
3132
+ }
2565
3133
  if (agent?.status !== 'active')
2566
3134
  continue;
2567
- this.noteStuck(tx, agent, `It waits for: ${session.waitingFor}`);
3135
+ await this.noteStuck(tx, agent, `It waits for: ${session.waitingFor}`, 'listing');
2568
3136
  }
2569
3137
  }))
2570
3138
  .finally(() => this.listing.delete(harness)));
@@ -2883,12 +3451,16 @@ export class BridgeDispatcher extends EventEmitter {
2883
3451
  this.store.updateLetter(task.id, { clear: ['replyDueAt'] });
2884
3452
  }
2885
3453
  }
2886
- async failJob(tx, number, reason) {
3454
+ /**
3455
+ * Fails a job. `failure` says whose doing it was: the scoreboard holds only what its agent did
3456
+ * against the agent.
3457
+ */
3458
+ async failJob(tx, number, reason, failure = 'other') {
2887
3459
  const { job } = this.requireJob(number);
2888
3460
  if (isFinishedJobState(job.state))
2889
3461
  return;
2890
3462
  await this.transition(tx, number, 'failed', reason);
2891
- await this.patchRecord(job.taskId, { reason });
3463
+ await this.patchRecord(job.taskId, { reason, failure });
2892
3464
  this.closeLetters(tx, number);
2893
3465
  await this.stopWaiting(number, this.now(), false);
2894
3466
  this.noteOutcome(tx, number);
@@ -2923,17 +3495,20 @@ export class BridgeDispatcher extends EventEmitter {
2923
3495
  }
2924
3496
  /**
2925
3497
  * Why an agent may not hand this job over right now, if it may not: it is the job it already
2926
- * handed to the same agent and that is still in progress, it has too many jobs out, it hands
2927
- * jobs over too fast, or too many sessions are being started.
3498
+ * handed to the same agent and that is still in progress (for a job left to `auto`: one it
3499
+ * left to `auto` before, whoever got it), it has too many jobs out, it hands jobs over too
3500
+ * fast, or too many sessions are being started.
2928
3501
  */
2929
- handOverRefusal(from, resolution, body, cwd, now) {
3502
+ handOverRefusal(from, resolution, body, cwd, now, routed = false) {
2930
3503
  const open = this.store
2931
3504
  .jobTasks({ from: from.name, states: ACTIVE_JOB_STATES })
2932
3505
  .flatMap((task) => jobOf(task) ?? []);
2933
3506
  const wanted = normalizeBody(body);
2934
- const sameAgent = (job) => resolution.kind === 'agent'
2935
- ? job.to === resolution.agent.name
2936
- : this.store.getAgent(job.to)?.harness === resolution.harness;
3507
+ const sameAgent = (job) => routed
3508
+ ? job.routed !== undefined
3509
+ : resolution.kind === 'agent'
3510
+ ? job.to === resolution.agent.name
3511
+ : this.store.getAgent(job.to)?.harness === resolution.harness;
2937
3512
  const same = open.find((job) => {
2938
3513
  if (job.cwd !== cwd || !sameAgent(job))
2939
3514
  return false;
@@ -2950,13 +3525,7 @@ export class BridgeDispatcher extends EventEmitter {
2950
3525
  if (recent >= this.limits.jobsPerHour) {
2951
3526
  return new BridgeError('budget_exhausted', `You handed over ${recent} jobs in the last hour, the most there may be. This looks like a loop: stop and tell the person what is going on`, { recent, max: this.limits.jobsPerHour });
2952
3527
  }
2953
- if (resolution.kind === 'spawn') {
2954
- const starting = this.store.listAgents({ statuses: ['starting'] }).length;
2955
- if (starting >= this.limits.maxStartingSessions) {
2956
- return new BridgeError('no_session', `The bridge is already starting ${starting} sessions, the most at once. Hand the job over again when they are up`, { starting, max: this.limits.maxStartingSessions });
2957
- }
2958
- }
2959
- return undefined;
3528
+ return resolution.kind === 'spawn' ? this.startingRefusal() : undefined;
2960
3529
  }
2961
3530
  /**
2962
3531
  * A finished job waits for nothing: its own letter and the questions nobody answered are done
@@ -3222,11 +3791,29 @@ export class BridgeDispatcher extends EventEmitter {
3222
3791
  nextAttemptAt: this.iso(this.now() + deliveryBackoff(attempts, this.limits)),
3223
3792
  });
3224
3793
  }
3794
+ /**
3795
+ * Starts the session of an agent for a job, or queues the start when as many sessions are
3796
+ * being started as may be at once (`limits.maxStartingSessions`). A job handed over by an
3797
+ * agent is refused before it gets here, so what waits in the queue is what the bridge itself
3798
+ * hands on: the jobs of an agent that ran into its limit, each of which needs a session.
3799
+ */
3225
3800
  startSession(agentName, jobNumber, letterId) {
3226
3801
  this.starting.add(agentName);
3802
+ if (this.startsRunning >= this.limits.maxStartingSessions) {
3803
+ this.startQueue.push({ agent: agentName, job: jobNumber, letter: letterId });
3804
+ return;
3805
+ }
3806
+ this.launchSession(agentName, jobNumber, letterId);
3807
+ }
3808
+ launchSession(agentName, jobNumber, letterId) {
3809
+ this.startsRunning += 1;
3227
3810
  this.track(this.runSessionStart(agentName, jobNumber, letterId).finally(() => {
3811
+ this.startsRunning -= 1;
3228
3812
  if (this.starting.delete(agentName))
3229
3813
  this.wakeIfKnown(agentName);
3814
+ const next = this.closing ? undefined : this.startQueue.shift();
3815
+ if (next)
3816
+ this.launchSession(next.agent, next.job, next.letter);
3230
3817
  }));
3231
3818
  }
3232
3819
  wakeIfKnown(agentName) {
@@ -3238,12 +3825,23 @@ export class BridgeDispatcher extends EventEmitter {
3238
3825
  }));
3239
3826
  }
3240
3827
  async runSessionStart(agentName, jobNumber, letterId) {
3241
- const request = await this.enqueue(async () => {
3828
+ const request = await this.mutate(async (tx) => {
3242
3829
  const agent = this.store.getAgent(agentName);
3243
3830
  const letter = this.store.getLetter(letterId);
3244
3831
  if (!agent || !letter)
3245
3832
  return undefined;
3246
3833
  const { job } = this.requireJob(jobNumber);
3834
+ if (isFinishedJobState(job.state) || job.to !== agentName) {
3835
+ if (agent.status === 'starting') {
3836
+ this.store.putAgent({ ...agent, status: 'gone' });
3837
+ this.journal(tx, {
3838
+ type: 'agent.gone',
3839
+ agent: agentName,
3840
+ data: { error: `job #${jobNumber} was over before its session was started` },
3841
+ });
3842
+ }
3843
+ return undefined;
3844
+ }
3247
3845
  return { agent, job, letter: renderLetter(letter, job) };
3248
3846
  });
3249
3847
  const adapter = request && this.adapters.get(request.agent.harness);
@@ -3266,6 +3864,11 @@ export class BridgeDispatcher extends EventEmitter {
3266
3864
  }
3267
3865
  catch (error) {
3268
3866
  const message = asError(error).message;
3867
+ const signal = limitOf(message, this.now());
3868
+ if (signal) {
3869
+ await this.outOfLimit(agentName, signal, true);
3870
+ return;
3871
+ }
3269
3872
  await this.mutate(async (tx) => {
3270
3873
  const agent = this.store.getAgent(agentName);
3271
3874
  if (agent?.status !== 'starting')