@cogitator-ai/bridge 0.4.0 → 0.5.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 (81) hide show
  1. package/README.md +72 -23
  2. package/dist/adapter.d.ts +2 -1
  3. package/dist/adapter.d.ts.map +1 -1
  4. package/dist/adapters/hosted.d.ts +36 -4
  5. package/dist/adapters/hosted.d.ts.map +1 -1
  6. package/dist/adapters/hosted.js +188 -9
  7. package/dist/adapters/hosted.js.map +1 -1
  8. package/dist/client.d.ts +16 -1
  9. package/dist/client.d.ts.map +1 -1
  10. package/dist/client.js +24 -1
  11. package/dist/client.js.map +1 -1
  12. package/dist/dispatcher.d.ts +113 -3
  13. package/dist/dispatcher.d.ts.map +1 -1
  14. package/dist/dispatcher.js +493 -23
  15. package/dist/dispatcher.js.map +1 -1
  16. package/dist/errors.d.ts +1 -1
  17. package/dist/errors.d.ts.map +1 -1
  18. package/dist/errors.js.map +1 -1
  19. package/dist/guards.d.ts +3 -2
  20. package/dist/guards.d.ts.map +1 -1
  21. package/dist/guards.js +4 -3
  22. package/dist/guards.js.map +1 -1
  23. package/dist/host.d.ts +9 -0
  24. package/dist/host.d.ts.map +1 -1
  25. package/dist/host.js +2 -0
  26. package/dist/host.js.map +1 -1
  27. package/dist/index.d.ts +11 -5
  28. package/dist/index.d.ts.map +1 -1
  29. package/dist/index.js +6 -3
  30. package/dist/index.js.map +1 -1
  31. package/dist/inputs.d.ts +76 -1
  32. package/dist/inputs.d.ts.map +1 -1
  33. package/dist/inputs.js +31 -1
  34. package/dist/inputs.js.map +1 -1
  35. package/dist/job-record.d.ts +1 -0
  36. package/dist/job-record.d.ts.map +1 -1
  37. package/dist/job-record.js +1 -0
  38. package/dist/job-record.js.map +1 -1
  39. package/dist/letters.d.ts.map +1 -1
  40. package/dist/letters.js +23 -1
  41. package/dist/letters.js.map +1 -1
  42. package/dist/person-channel.d.ts +45 -0
  43. package/dist/person-channel.d.ts.map +1 -0
  44. package/dist/person-channel.js +154 -0
  45. package/dist/person-channel.js.map +1 -0
  46. package/dist/person-inbox.d.ts +30 -0
  47. package/dist/person-inbox.d.ts.map +1 -0
  48. package/dist/person-inbox.js +60 -0
  49. package/dist/person-inbox.js.map +1 -0
  50. package/dist/person.d.ts +52 -0
  51. package/dist/person.d.ts.map +1 -0
  52. package/dist/person.js +30 -0
  53. package/dist/person.js.map +1 -0
  54. package/dist/protocol.d.ts +6 -1
  55. package/dist/protocol.d.ts.map +1 -1
  56. package/dist/protocol.js +5 -1
  57. package/dist/protocol.js.map +1 -1
  58. package/dist/rights/index.d.ts +36 -0
  59. package/dist/rights/index.d.ts.map +1 -0
  60. package/dist/rights/index.js +186 -0
  61. package/dist/rights/index.js.map +1 -0
  62. package/dist/server.d.ts.map +1 -1
  63. package/dist/server.js +9 -0
  64. package/dist/server.js.map +1 -1
  65. package/dist/store/sqlite.d.ts +6 -1
  66. package/dist/store/sqlite.d.ts.map +1 -1
  67. package/dist/store/sqlite.js +74 -18
  68. package/dist/store/sqlite.js.map +1 -1
  69. package/dist/store/store.d.ts +6 -2
  70. package/dist/store/store.d.ts.map +1 -1
  71. package/dist/tools/guidance.d.ts.map +1 -1
  72. package/dist/tools/guidance.js +1 -0
  73. package/dist/tools/guidance.js.map +1 -1
  74. package/dist/tools/tools.d.ts.map +1 -1
  75. package/dist/tools/tools.js +27 -4
  76. package/dist/tools/tools.js.map +1 -1
  77. package/dist/types.d.ts +81 -1
  78. package/dist/types.d.ts.map +1 -1
  79. package/dist/types.js +29 -0
  80. package/dist/types.js.map +1 -1
  81. package/package.json +6 -1
@@ -3,12 +3,12 @@ import { isAbsolute, resolve as resolvePath } from 'node:path';
3
3
  import { TaskManager, textPart, toMessage } from '@cogitator-ai/a2a';
4
4
  import { BridgeError } from './errors.js';
5
5
  import { deliveryBackoff, exhaustedBudget, formatDuration, nextDepth, resolveBudget, resolveLimits, } from './guards.js';
6
- import { AgentsFilterSchema, CreateJobInputSchema, DEFAULT_INBOX_LIMIT, DEFAULT_LIST_LIMIT, DEFAULT_WAIT_MS, DeliveredInputSchema, InboxInputSchema, JobsFilterSchema, JournalQuerySchema, LettersFilterSchema, SendLetterInputSchema, VerificationInputSchema, WaitInputSchema, } from './inputs.js';
6
+ import { AgentsFilterSchema, CreateJobInputSchema, DEFAULT_INBOX_LIMIT, DEFAULT_LIST_LIMIT, DEFAULT_VERDICT_WAIT_MS, DEFAULT_WAIT_MS, DeliveredInputSchema, EscalateInputSchema, InboxInputSchema, JobsFilterSchema, JournalQuerySchema, LettersFilterSchema, PersonAnswerInputSchema, SendLetterInputSchema, VerdictInputSchema, VerificationInputSchema, WaitInputSchema, } from './inputs.js';
7
7
  import { isFinishedJobState, jobOf, jobRecordOf } from './job-record.js';
8
8
  import { expectationOf, forHistory, newLetterId, normalizeBody, oneLine, quoted, renderLetter, repeats, titleOf, } from './letters.js';
9
9
  import { canonicalPath, findCheckoutRoot, findProjectRoot, isInside } from './paths.js';
10
10
  import { allocateAgentName, resolveAddress } from './registry.js';
11
- import { BRIDGE_JOB_KEY, BRIDGE_SENDER, CallerIdentitySchema, DEFAULT_LIMITS, HarnessNameSchema, INBOX_DELIVERY, NO_CAPABILITIES, } from './types.js';
11
+ import { BRIDGE_JOB_KEY, BRIDGE_SENDER, CallerIdentitySchema, DEFAULT_LIMITS, HarnessNameSchema, INBOX_DELIVERY, NO_CAPABILITIES, PERSON, } from './types.js';
12
12
  const ACTIVE_JOB_STATES = ['submitted', 'working', 'input-required'];
13
13
  const UNREAD_STATES = ['queued', 'delivered'];
14
14
  const NEEDS_ANSWER = ['question', 'permission'];
@@ -110,6 +110,12 @@ export class BridgeDispatcher extends EventEmitter {
110
110
  letterId;
111
111
  onError;
112
112
  assertWritable;
113
+ rights;
114
+ person;
115
+ /** Those waiting for the verdict of a permission request, by its id, see `verdict` */
116
+ verdictWaiters = new Map();
117
+ /** What the person route is told, one thing after another */
118
+ personNews = Promise.resolve();
113
119
  queue = Promise.resolve();
114
120
  deliveries = new Map();
115
121
  background = new Set();
@@ -142,6 +148,8 @@ export class BridgeDispatcher extends EventEmitter {
142
148
  this.letterId = options.newLetterId ?? newLetterId;
143
149
  this.onError = options.onError ?? (() => undefined);
144
150
  this.assertWritable = options.assertWritable;
151
+ this.rights = options.rights;
152
+ this.person = options.person;
145
153
  for (const adapter of options.adapters ?? []) {
146
154
  const harness = parse(HarnessNameSchema, adapter.harness, 'Cannot use the adapter');
147
155
  if (this.adapters.has(harness)) {
@@ -151,6 +159,7 @@ export class BridgeDispatcher extends EventEmitter {
151
159
  }
152
160
  for (const adapter of this.adapters.values())
153
161
  adapter.attach?.(this);
162
+ this.person?.attach?.(this);
154
163
  }
155
164
  /**
156
165
  * Puts the calling session into the address book, or finds it there. A session is known by
@@ -176,6 +185,7 @@ export class BridgeDispatcher extends EventEmitter {
176
185
  cwd,
177
186
  project,
178
187
  ...(caller.sessionName && { sessionName: caller.sessionName }),
188
+ ...(caller.permissionMode && { permissionMode: caller.permissionMode }),
179
189
  status: 'active',
180
190
  lastSeenAt: now,
181
191
  };
@@ -199,6 +209,7 @@ export class BridgeDispatcher extends EventEmitter {
199
209
  ...reach,
200
210
  sessionId: caller.sessionId,
201
211
  ...(caller.sessionName && { sessionName: caller.sessionName }),
212
+ ...(caller.permissionMode && { permissionMode: caller.permissionMode }),
202
213
  status: 'active',
203
214
  lastSeenAt: now,
204
215
  };
@@ -216,6 +227,7 @@ export class BridgeDispatcher extends EventEmitter {
216
227
  harness: caller.harness,
217
228
  sessionId: caller.sessionId,
218
229
  ...(caller.sessionName && { sessionName: caller.sessionName }),
230
+ ...(caller.permissionMode && { permissionMode: caller.permissionMode }),
219
231
  project,
220
232
  cwd,
221
233
  ...reach,
@@ -383,13 +395,20 @@ export class BridgeDispatcher extends EventEmitter {
383
395
  * Sends a letter on a job to its other party: a question, an answer, a report that ends the
384
396
  * job, a note. The call returns once the bridge has the letter, the answer comes as a letter.
385
397
  *
398
+ * A permission request that names its call (`ask`) is judged first by the rules of the agent
399
+ * that handed the job over: what they forbid is refused at once, what they allow is that
400
+ * agent's to answer, and the rest waits for the person. So the one carrying a job out never
401
+ * gets leave the one who handed it over does not have. The decision comes through `verdict`.
402
+ *
386
403
  * @throws BridgeError `not_registered`, `unknown_job`, `not_a_party`, `job_finished`,
387
404
  * `invalid_letter`, `loop_detected` (the same letter twice in a row), `budget_exhausted` (the
388
- * job ran out of letters or time, and has failed)
405
+ * job ran out of letters or time, and has failed), `needs_person` (an agent allowing what only
406
+ * the person can)
389
407
  */
390
408
  async send(caller, input) {
391
409
  const request = parse(SendLetterInputSchema, input, 'Cannot send the letter');
392
410
  this.checkBody(request.body);
411
+ const rights = request.ask ? await this.rightsFor(request.job, request.ask) : undefined;
393
412
  const outcome = await this.asCaller(caller, async (tx) => {
394
413
  const from = this.requireCaller(caller);
395
414
  if (request.id) {
@@ -418,7 +437,28 @@ export class BridgeDispatcher extends EventEmitter {
418
437
  if (request.kind === 'report' && !isAssignee) {
419
438
  throw new BridgeError('invalid_letter', `Only ${job.to}, who carries job ${job.number} out, reports on it`);
420
439
  }
440
+ if (request.ask && !isAssignee) {
441
+ throw new BridgeError('invalid_letter', `Only ${job.to}, who carries job ${job.number} out, asks leave for a call`);
442
+ }
421
443
  const answered = this.answeredLetter(request, job, from.name);
444
+ if (request.kind === 'answer' && answered) {
445
+ if (answered.ask && !request.verdict) {
446
+ throw new BridgeError('invalid_letter', `The permission request ${answered.id} takes a decision: allow or deny`, { letter: answered.id });
447
+ }
448
+ if (!answered.ask && request.verdict) {
449
+ throw new BridgeError('invalid_letter', `The ${answered.kind} ${answered.id} takes an answer in words, not a decision`, { letter: answered.id });
450
+ }
451
+ if (answered.ask && answered.needsPerson && request.verdict === 'allow') {
452
+ const error = new BridgeError('needs_person', `The permission request ${answered.id} is the person's to allow: your own rules would have you ask them too. They were asked. You can refuse it`, { job: job.number, letter: answered.id });
453
+ this.journal(tx, {
454
+ type: 'letter.rejected',
455
+ job: job.number,
456
+ agent: from.name,
457
+ data: { reason: error.code, kind: request.kind, to, inReplyTo: answered.id },
458
+ });
459
+ return new Refusal(error);
460
+ }
461
+ }
422
462
  const previous = this.store.listLetters({
423
463
  job: job.number,
424
464
  from: from.name,
@@ -426,7 +466,8 @@ export class BridgeDispatcher extends EventEmitter {
426
466
  newestFirst: true,
427
467
  limit: 1,
428
468
  })[0];
429
- if (repeats(previous, request.kind, request.body, answered?.id)) {
469
+ if (repeats(previous, request.kind, request.body, answered?.id) &&
470
+ !this.wasAllowed(previous)) {
430
471
  const error = new BridgeError('loop_detected', `This ${request.kind} says what your last letter on job ${job.number} said, so it was not delivered. Say something new, report or cancel the job`, { job: job.number, previous: previous.id });
431
472
  this.journal(tx, {
432
473
  type: 'letter.rejected',
@@ -437,7 +478,8 @@ export class BridgeDispatcher extends EventEmitter {
437
478
  return new Refusal(error);
438
479
  }
439
480
  const now = this.now();
440
- const exhausted = exhaustedBudget(job, now, request.kind);
481
+ const clockHeld = now >= Date.parse(job.deadlineAt) && this.waitsForPerson(job.number);
482
+ const exhausted = exhaustedBudget(job, now, request.kind, clockHeld);
441
483
  if (exhausted) {
442
484
  const reason = exhausted === 'letters'
443
485
  ? `the job used all ${job.budget.letters} letters of its budget`
@@ -457,6 +499,12 @@ export class BridgeDispatcher extends EventEmitter {
457
499
  }
458
500
  if (isAssignee && job.state === 'submitted')
459
501
  await this.pickUp(tx, job);
502
+ const forPerson = rights === 'ask' && this.person !== undefined;
503
+ const refused = rights === 'deny'
504
+ ? `The rules of ${job.from} forbid this, so it is refused`
505
+ : rights === 'ask' && !forPerson
506
+ ? 'Only the person can allow this, and this bridge has no way to reach them, so it is refused'
507
+ : undefined;
460
508
  const letter = this.accept(tx, {
461
509
  id: request.id ?? this.letterId(),
462
510
  job: job.number,
@@ -466,41 +514,363 @@ export class BridgeDispatcher extends EventEmitter {
466
514
  body: request.body,
467
515
  ...(answered && { inReplyTo: answered.id }),
468
516
  ...(request.kind === 'report' && { outcome: request.outcome ?? 'completed' }),
469
- ...(expectationOf(request.kind) === 'reply' && {
470
- replyDueAt: this.iso(now + job.budget.replyTimeoutMs),
517
+ ...(request.ask && { ask: request.ask }),
518
+ ...(request.verdict && { verdict: request.verdict }),
519
+ ...(forPerson && { needsPerson: true, personAskedAt: this.iso(now) }),
520
+ ...(expectationOf(request.kind) === 'reply' &&
521
+ !refused && {
522
+ replyDueAt: this.iso(now + (forPerson ? this.limits.personReplyTimeoutMs : job.budget.replyTimeoutMs)),
471
523
  }),
472
524
  });
473
525
  await this.patchRecord(job.taskId, { lettersUsed: job.lettersUsed + 1 });
474
- if (answered && request.kind === 'answer')
526
+ if (refused) {
527
+ const settled = this.refuse(tx, letter, refused);
528
+ return { letter: settled, job: this.requireJob(job.number).job, duplicate: false };
529
+ }
530
+ if (forPerson) {
531
+ tx.asked.push({ letter: letter.id, again: false });
532
+ await this.startWaiting(job.number, now);
533
+ }
534
+ if (answered && request.kind === 'answer') {
475
535
  this.markHandled(tx, answered);
536
+ if (answered.ask)
537
+ this.markHandled(tx, letter);
538
+ if (answered.needsPerson)
539
+ await this.stopWaiting(job.number, now, false);
540
+ }
476
541
  if (request.kind === 'report') {
477
542
  const state = letter.outcome === 'failed' ? 'failed' : 'completed';
478
543
  await this.transition(tx, job.number, state, forHistory(request.body, letter.id));
479
544
  if (state === 'failed')
480
545
  await this.patchRecord(job.taskId, { reason: `reported as failed by ${from.name}` });
481
546
  this.closeLetters(tx, job.number, letter.id);
547
+ await this.stopWaiting(job.number, now, false);
482
548
  await this.cancelChildren(tx, job);
483
549
  }
484
550
  else if (isAssignee && NEEDS_ANSWER.includes(request.kind)) {
485
551
  await this.transition(tx, job.number, 'input-required', forHistory(request.body, letter.id));
486
552
  }
487
553
  else if (request.kind === 'answer' && !isAssignee) {
488
- const open = this.store.countLetters({
489
- job: job.number,
490
- from: job.to,
491
- kinds: NEEDS_ANSWER,
492
- states: ['queued', 'delivered', 'read'],
493
- });
494
- if (open === 0 && this.requireJob(job.number).job.state === 'input-required') {
495
- await this.transition(tx, job.number, 'working', forHistory(request.body, letter.id));
496
- }
554
+ await this.resumeIfAnswered(tx, job, forHistory(request.body, letter.id));
497
555
  }
498
- return { letter, job: this.requireJob(job.number).job, duplicate: false };
556
+ return {
557
+ letter: this.store.getLetter(letter.id) ?? letter,
558
+ job: this.requireJob(job.number).job,
559
+ duplicate: false,
560
+ };
499
561
  });
500
562
  if (outcome instanceof Refusal)
501
563
  throw outcome.error;
502
564
  return outcome;
503
565
  }
566
+ /**
567
+ * Passes a question or a permission request addressed to the caller on to the person: the
568
+ * answer is theirs to give now, and goes to the one who asked. The caller can still answer it
569
+ * itself, except to allow a call its own rules leave to the person. Passing a letter on twice
570
+ * changes nothing.
571
+ *
572
+ * @throws BridgeError `unknown_letter` for a letter that is not addressed to the caller,
573
+ * `invalid_letter` for one that takes no answer or waits no more, `no_person` when the bridge
574
+ * has no way to reach the person
575
+ */
576
+ async escalate(caller, input) {
577
+ const request = parse(EscalateInputSchema, input, 'Cannot pass the letter on');
578
+ return this.asCaller(caller, async (tx) => {
579
+ const agent = this.requireCaller(caller);
580
+ const letter = request.letter === undefined
581
+ ? this.openLetter(request.job ?? 0, agent.name)
582
+ : this.store.getLetter(request.letter);
583
+ if (letter?.to !== agent.name) {
584
+ throw new BridgeError('unknown_letter', `There is no letter ${request.letter} addressed to you`, { letter: request.letter });
585
+ }
586
+ const { job } = this.requireJob(letter.job);
587
+ if (!NEEDS_ANSWER.includes(letter.kind) ||
588
+ letter.state === 'handled' ||
589
+ isFinishedJobState(job.state)) {
590
+ throw new BridgeError('invalid_letter', `The ${letter.kind} ${letter.id} waits for no answer, so there is nothing to pass on`, { letter: letter.id });
591
+ }
592
+ if (letter.needsPerson)
593
+ return letter;
594
+ if (!this.person) {
595
+ throw new BridgeError('no_person', 'This bridge has no way to reach the person. Ask them yourself, in your own window', { letter: letter.id });
596
+ }
597
+ const now = this.now();
598
+ const updated = this.store.updateLetter(letter.id, {
599
+ needsPerson: true,
600
+ personAskedAt: this.iso(now),
601
+ replyDueAt: this.iso(now + this.limits.personReplyTimeoutMs),
602
+ clear: ['remindedAt'],
603
+ });
604
+ this.journal(tx, {
605
+ type: 'letter.escalated',
606
+ job: job.number,
607
+ letter: letter.id,
608
+ agent: agent.name,
609
+ });
610
+ tx.asked.push({ letter: letter.id, again: false });
611
+ await this.startWaiting(job.number, now);
612
+ return updated;
613
+ });
614
+ }
615
+ /**
616
+ * Takes what the person said to a letter that waits for them: `allow` or `deny` for a
617
+ * permission request that names its call, words for anything else. The answer goes to the one
618
+ * who asked, signed `person`. Whoever calls this speaks for the person, so it is not served to
619
+ * agents: a route to the person calls it, see `PersonRoute`.
620
+ *
621
+ * @throws BridgeError `unknown_letter` when no such letter waits for the person,
622
+ * `invalid_letter` when it waits no more or the answer is of the wrong kind
623
+ */
624
+ async personAnswer(input) {
625
+ const request = parse(PersonAnswerInputSchema, input, "Cannot take the person's answer");
626
+ if (request.body !== undefined)
627
+ this.checkBody(request.body);
628
+ return this.mutate(async (tx) => {
629
+ const target = this.store.getLetter(request.letter);
630
+ if (!target?.needsPerson || !NEEDS_ANSWER.includes(target.kind)) {
631
+ throw new BridgeError('unknown_letter', `No letter ${request.letter} waits for the person`, { letter: request.letter });
632
+ }
633
+ const { job } = this.requireJob(target.job);
634
+ if (target.state === 'handled' || isFinishedJobState(job.state)) {
635
+ throw new BridgeError('invalid_letter', `The ${target.kind} ${target.id} waits no more: ${isFinishedJobState(job.state) ? `job #${job.number} is ${job.state}` : 'it is answered'}`, { letter: target.id, job: job.number });
636
+ }
637
+ if (target.ask && !request.verdict) {
638
+ throw new BridgeError('invalid_letter', `The permission request ${target.id} takes a decision: allow or deny`, { letter: target.id });
639
+ }
640
+ if (!target.ask && (request.verdict || request.body === undefined)) {
641
+ throw new BridgeError('invalid_letter', `The ${target.kind} ${target.id} takes an answer in words`, { letter: target.id });
642
+ }
643
+ const body = request.body ??
644
+ (request.verdict === 'allow' ? 'Allowed by the person' : 'Refused by the person');
645
+ const letter = this.accept(tx, {
646
+ id: this.letterId(),
647
+ job: job.number,
648
+ kind: 'answer',
649
+ from: PERSON,
650
+ to: target.from,
651
+ body,
652
+ inReplyTo: target.id,
653
+ ...(request.verdict && { verdict: request.verdict }),
654
+ });
655
+ this.markHandled(tx, target);
656
+ const sent = target.ask ? this.markHandled(tx, letter) : letter;
657
+ await this.stopWaiting(job.number, this.now(), true);
658
+ await this.resumeIfAnswered(tx, job, forHistory(body, letter.id));
659
+ return { letter: sent, job: this.requireJob(job.number).job, duplicate: false };
660
+ });
661
+ }
662
+ /** The letters that wait for the person, oldest first, each with its job and the text to show. */
663
+ async forPerson() {
664
+ return this.enqueue(async () => this.store
665
+ .listLetters({ needsPerson: true, states: ['queued', 'delivered', 'read'] })
666
+ .map((letter) => {
667
+ const { job } = this.requireJob(letter.job);
668
+ return { letter: renderLetter(letter, job), job };
669
+ }));
670
+ }
671
+ /**
672
+ * Whether a permission request the caller sent is decided. Answers at once when it is,
673
+ * otherwise as soon as it is, or with `waiting` when `timeoutMs` passes: the caller asks
674
+ * again. A request whose job ended before anybody answered counts as refused.
675
+ *
676
+ * @throws BridgeError `unknown_letter` for anything but a permission request of the caller
677
+ * that names its call
678
+ */
679
+ async verdict(caller, input, signal) {
680
+ const request = parse(VerdictInputSchema, input, 'Cannot look the verdict up');
681
+ const timeoutMs = request.timeoutMs ?? DEFAULT_VERDICT_WAIT_MS;
682
+ const first = await this.asCaller(caller, async () => {
683
+ const agent = this.requireCaller(caller);
684
+ const letter = this.store.getLetter(request.letter);
685
+ if (letter?.from !== agent.name || letter.kind !== 'permission' || !letter.ask) {
686
+ throw new BridgeError('unknown_letter', `You sent no permission request ${request.letter} that names its call`, { letter: request.letter });
687
+ }
688
+ const decision = this.decisionOf(letter);
689
+ if (decision.state === 'decided' || timeoutMs === 0 || signal?.aborted || this.closing) {
690
+ return decision;
691
+ }
692
+ return { later: this.untilDecided(letter.id, timeoutMs, signal) };
693
+ });
694
+ if (!('later' in first))
695
+ return first;
696
+ await first.later;
697
+ if (this.closed)
698
+ return { state: 'waiting' };
699
+ return this.enqueue(async () => {
700
+ const letter = this.store.getLetter(request.letter);
701
+ return letter ? this.decisionOf(letter) : { state: 'waiting' };
702
+ });
703
+ }
704
+ decisionOf(letter) {
705
+ if (letter.state !== 'handled')
706
+ return { state: 'waiting' };
707
+ const answer = this.store
708
+ .listLetters({ inReplyTo: letter.id, kinds: ['answer'], newestFirst: true })
709
+ .find((candidate) => candidate.verdict !== undefined);
710
+ if (answer?.verdict) {
711
+ return { state: 'decided', verdict: answer.verdict, reason: answer.body, by: answer.from };
712
+ }
713
+ const { job } = this.requireJob(letter.job);
714
+ return {
715
+ state: 'decided',
716
+ verdict: 'deny',
717
+ reason: `Nobody answered before job #${job.number} was ${job.state}${job.reason ? ` (${job.reason})` : ''}`,
718
+ by: BRIDGE_SENDER,
719
+ };
720
+ }
721
+ /** Resolves when the request gets its verdict, `ms` pass, or `signal` aborts. */
722
+ untilDecided(letterId, ms, signal) {
723
+ return new Promise((resolve) => {
724
+ const waiting = this.verdictWaiters.get(letterId) ?? new Set();
725
+ this.verdictWaiters.set(letterId, waiting);
726
+ const look = () => {
727
+ clearTimeout(timer);
728
+ signal?.removeEventListener('abort', look);
729
+ waiting.delete(look);
730
+ if (waiting.size === 0 && this.verdictWaiters.get(letterId) === waiting) {
731
+ this.verdictWaiters.delete(letterId);
732
+ }
733
+ resolve();
734
+ };
735
+ const timer = setTimeout(look, ms);
736
+ signal?.addEventListener('abort', look, { once: true });
737
+ waiting.add(look);
738
+ });
739
+ }
740
+ /**
741
+ * What the rules of the agent that handed a job over make of a call. A job handed over from
742
+ * inside a job is bound by every agent up the chain: the call is theirs to allow only when it
743
+ * is each one's, and forbidden when any of them may not make it. A judge that throws, and a
744
+ * bridge without one, leave the call to the person: nothing is allowed by accident.
745
+ */
746
+ async rightsFor(number, ask) {
747
+ if (!this.rights)
748
+ return 'ask';
749
+ let rights = 'allow';
750
+ try {
751
+ for (let at = number; at !== undefined;) {
752
+ const job = this.jobIfAny(at);
753
+ if (!job)
754
+ return 'ask';
755
+ const said = await this.rights({ job, delegator: this.store.getAgent(job.from), ask });
756
+ if (said === 'deny')
757
+ return 'deny';
758
+ if (said === 'ask')
759
+ rights = 'ask';
760
+ at = job.parent;
761
+ }
762
+ }
763
+ catch (error) {
764
+ this.onError(asError(error));
765
+ return 'ask';
766
+ }
767
+ return rights;
768
+ }
769
+ jobIfAny(number) {
770
+ const task = this.store.taskOfJob(number);
771
+ return task && jobOf(task) ? this.requireJob(number).job : undefined;
772
+ }
773
+ /** Whether a permission request was answered with `allow`: the same call may be asked for again. */
774
+ wasAllowed(letter) {
775
+ if (letter?.kind !== 'permission' || !letter.ask)
776
+ return false;
777
+ const decision = this.decisionOf(letter);
778
+ return decision.state === 'decided' && decision.verdict === 'allow';
779
+ }
780
+ /**
781
+ * Refuses a permission request on the spot, in the bridge's own name: the request is done
782
+ * with, and its sender finds the refusal through `verdict`.
783
+ */
784
+ refuse(tx, request, reason) {
785
+ const settled = this.markHandled(tx, request);
786
+ const answer = this.accept(tx, {
787
+ id: this.letterId(),
788
+ job: request.job,
789
+ kind: 'answer',
790
+ from: BRIDGE_SENDER,
791
+ to: request.from,
792
+ body: reason,
793
+ inReplyTo: request.id,
794
+ verdict: 'deny',
795
+ });
796
+ this.markHandled(tx, answer);
797
+ return settled;
798
+ }
799
+ /**
800
+ * Whether a job waits for the person right now: a letter of it does, or a job handed over
801
+ * from inside it waits for them.
802
+ */
803
+ waitsForPerson(number) {
804
+ const own = this.store.countLetters({
805
+ job: number,
806
+ needsPerson: true,
807
+ states: ['queued', 'delivered', 'read'],
808
+ });
809
+ if (own > 0)
810
+ return true;
811
+ return this.store.jobTasks({ parent: number, states: ACTIVE_JOB_STATES }).some((task) => {
812
+ const child = jobOf(task);
813
+ return child !== undefined && this.waitsForPerson(child.number);
814
+ });
815
+ }
816
+ /** A job and the jobs it was handed over from inside of, the nearest first, while they run. */
817
+ chainOf(number) {
818
+ const chain = [];
819
+ for (let at = number; at !== undefined;) {
820
+ const job = this.jobIfAny(at);
821
+ if (!job)
822
+ break;
823
+ if (!isFinishedJobState(job.state))
824
+ chain.push(job);
825
+ at = job.parent;
826
+ }
827
+ return chain;
828
+ }
829
+ /**
830
+ * Notes that a job began to wait for the person, and with it every job it is part of: none
831
+ * of them is failed by its deadline while the wait lasts.
832
+ */
833
+ async startWaiting(number, now) {
834
+ for (const job of this.chainOf(number)) {
835
+ if (!job.personWaitSince) {
836
+ await this.patchRecord(job.taskId, { personWaitSince: this.iso(now) });
837
+ }
838
+ }
839
+ }
840
+ /**
841
+ * Settles the wait of a job and of every job it is part of after a letter that waited for the
842
+ * person was dealt with. Time spent waiting for the person is not time the agents worked:
843
+ * when the person answered (`answered`), the deadline moves by as long as the job waited so
844
+ * far. When an agent dealt with the letter itself, or the job ended, nothing is given back, so
845
+ * agents cannot buy a job time by leaving letters to the person and taking them back. A job
846
+ * that still waits for another letter goes on waiting.
847
+ */
848
+ async stopWaiting(number, now, answered) {
849
+ for (const job of this.chainOf(number)) {
850
+ if (!job.personWaitSince)
851
+ continue;
852
+ const waited = Math.max(0, now - Date.parse(job.personWaitSince));
853
+ const still = this.waitsForPerson(job.number);
854
+ await this.patchRecord(job.taskId, {
855
+ ...(answered && { deadlineAt: this.iso(Date.parse(job.deadlineAt) + waited) }),
856
+ personWaitSince: still
857
+ ? this.iso(answered ? now : Date.parse(job.personWaitSince))
858
+ : undefined,
859
+ });
860
+ }
861
+ }
862
+ /** Puts a job that waited for an answer back to work once nothing of it waits for one. */
863
+ async resumeIfAnswered(tx, job, said) {
864
+ const open = this.store.countLetters({
865
+ job: job.number,
866
+ from: job.to,
867
+ kinds: NEEDS_ANSWER,
868
+ states: ['queued', 'delivered', 'read'],
869
+ });
870
+ if (open === 0 && this.requireJob(job.number).job.state === 'input-required') {
871
+ await this.transition(tx, job.number, 'working', said);
872
+ }
873
+ }
504
874
  /**
505
875
  * The letters waiting for the caller, oldest first, each with the text to show. Taking them
506
876
  * marks them read, and taking a job's first letter starts the job. One call returns `limit`
@@ -817,6 +1187,8 @@ export class BridgeDispatcher extends EventEmitter {
817
1187
  for (const late of overdue) {
818
1188
  if (isFinishedJobState(this.requireJob(late.number).job.state))
819
1189
  continue;
1190
+ if (this.waitsForPerson(late.number))
1191
+ continue;
820
1192
  await this.failJob(tx, late.number, ranOutOfTime(late));
821
1193
  failed.push(late.number);
822
1194
  }
@@ -829,6 +1201,27 @@ export class BridgeDispatcher extends EventEmitter {
829
1201
  this.store.updateLetter(letter.id, { clear: ['replyDueAt'] });
830
1202
  continue;
831
1203
  }
1204
+ if (fresh.needsPerson) {
1205
+ const patience = this.limits.personReplyTimeoutMs;
1206
+ if (!fresh.remindedAt) {
1207
+ this.store.updateLetter(letter.id, {
1208
+ remindedAt: this.iso(now),
1209
+ replyDueAt: this.iso(now + patience),
1210
+ });
1211
+ tx.asked.push({ letter: letter.id, again: true });
1212
+ this.journal(tx, {
1213
+ type: 'letter.reminded',
1214
+ job: job.number,
1215
+ letter: letter.id,
1216
+ agent: PERSON,
1217
+ });
1218
+ reminded.push(letter.id);
1219
+ continue;
1220
+ }
1221
+ await this.failJob(tx, job.number, `the person did not answer the ${letter.kind} ${letter.id} in ${formatDuration(2 * patience)}`);
1222
+ failed.push(job.number);
1223
+ continue;
1224
+ }
832
1225
  const pickup = expectationOf(letter.kind) === 'pickup';
833
1226
  if (!fresh.remindedAt) {
834
1227
  this.store.updateLetter(letter.id, {
@@ -977,6 +1370,8 @@ export class BridgeDispatcher extends EventEmitter {
977
1370
  this.closing = true;
978
1371
  for (const waiter of [...this.waiters.values()])
979
1372
  waiter.end('closed');
1373
+ for (const letter of [...this.verdictWaiters.keys()])
1374
+ this.announce(letter);
980
1375
  await this.idle();
981
1376
  await Promise.all([...this.adapters.values()].map(async (adapter) => {
982
1377
  try {
@@ -1017,7 +1412,14 @@ export class BridgeDispatcher extends EventEmitter {
1017
1412
  });
1018
1413
  }
1019
1414
  async transact(work) {
1020
- const tx = { entries: [], wake: new Set(), spawns: [] };
1415
+ const tx = {
1416
+ entries: [],
1417
+ wake: new Set(),
1418
+ spawns: [],
1419
+ asked: [],
1420
+ settled: [],
1421
+ decided: new Set(),
1422
+ };
1021
1423
  const result = await this.store.transaction(() => {
1022
1424
  this.assertWritable?.();
1023
1425
  return work(tx);
@@ -1036,8 +1438,59 @@ export class BridgeDispatcher extends EventEmitter {
1036
1438
  }
1037
1439
  for (const agent of tx.wake)
1038
1440
  this.wake(agent);
1441
+ for (const letter of tx.decided)
1442
+ this.announce(letter);
1443
+ this.tellPerson(tx);
1039
1444
  return result;
1040
1445
  }
1446
+ /** Lets those who wait for the verdict of a permission request look again. */
1447
+ announce(letterId) {
1448
+ const waiting = this.verdictWaiters.get(letterId);
1449
+ if (!waiting)
1450
+ return;
1451
+ this.verdictWaiters.delete(letterId);
1452
+ for (const look of waiting)
1453
+ look();
1454
+ }
1455
+ /**
1456
+ * Hands the person route what a call changed for it, after the call is stored and in the
1457
+ * order it happened. A route that throws, or takes longer than a delivery may, stops nothing:
1458
+ * the letter still waits in the bridge, and what comes after it is still told.
1459
+ */
1460
+ tellPerson(tx) {
1461
+ const route = this.person;
1462
+ if (!route || this.closing || tx.asked.length + tx.settled.length === 0)
1463
+ return;
1464
+ const rendered = (id) => {
1465
+ const letter = this.store.getLetter(id);
1466
+ if (!letter)
1467
+ return undefined;
1468
+ const { job } = this.requireJob(letter.job);
1469
+ return { letter: renderLetter(letter, job), job };
1470
+ };
1471
+ const news = [];
1472
+ const settled = new Set(tx.settled);
1473
+ for (const { letter: id, again } of tx.asked) {
1474
+ if (settled.has(id))
1475
+ continue;
1476
+ const found = rendered(id);
1477
+ if (found)
1478
+ news.push(() => route.ask({ ...found, again }));
1479
+ }
1480
+ for (const id of settled) {
1481
+ const found = rendered(id);
1482
+ if (found)
1483
+ news.push(() => route.settle(found));
1484
+ }
1485
+ for (const tell of news) {
1486
+ this.personNews = this.personNews
1487
+ .then(() => within(Promise.resolve().then(tell), this.limits.deliveryTimeoutMs, 'Telling the person of a letter'))
1488
+ .catch((error) => {
1489
+ this.onError(asError(error));
1490
+ });
1491
+ }
1492
+ this.track(this.personNews);
1493
+ }
1041
1494
  journal(tx, entry) {
1042
1495
  tx.entries.push(this.store.appendJournal({ at: this.iso(), ...entry }));
1043
1496
  }
@@ -1127,6 +1580,7 @@ export class BridgeDispatcher extends EventEmitter {
1127
1580
  await this.transition(tx, number, 'failed', reason);
1128
1581
  await this.patchRecord(job.taskId, { reason });
1129
1582
  this.closeLetters(tx, number);
1583
+ await this.stopWaiting(number, this.now(), false);
1130
1584
  const text = `Job #${number} has failed: ${reason}.`;
1131
1585
  this.systemNote(tx, job, job.from, text);
1132
1586
  this.systemNote(tx, job, job.to, `${text} Stop working on it.`);
@@ -1139,6 +1593,7 @@ export class BridgeDispatcher extends EventEmitter {
1139
1593
  await this.transition(tx, number, 'canceled', reason);
1140
1594
  await this.patchRecord(job.taskId, { reason });
1141
1595
  this.closeLetters(tx, number);
1596
+ await this.stopWaiting(number, this.now(), false);
1142
1597
  this.systemNote(tx, job, job.to, note);
1143
1598
  await this.cancelChildren(tx, job);
1144
1599
  }
@@ -1226,6 +1681,9 @@ export class BridgeDispatcher extends EventEmitter {
1226
1681
  body: letter.body,
1227
1682
  ...(letter.inReplyTo && { inReplyTo: letter.inReplyTo }),
1228
1683
  ...(letter.outcome && { outcome: letter.outcome }),
1684
+ ...(letter.ask && { ask: letter.ask }),
1685
+ ...(letter.verdict && { verdict: letter.verdict }),
1686
+ ...(letter.needsPerson && { needsPerson: true }),
1229
1687
  },
1230
1688
  });
1231
1689
  tx.wake.add(letter.to);
@@ -1266,8 +1724,16 @@ export class BridgeDispatcher extends EventEmitter {
1266
1724
  }
1267
1725
  if (request.kind !== 'answer')
1268
1726
  return undefined;
1727
+ return this.openLetter(job.number, caller);
1728
+ }
1729
+ /**
1730
+ * The one letter of a job that waits for the caller's answer.
1731
+ *
1732
+ * @throws BridgeError `invalid_letter` when none does, or several do
1733
+ */
1734
+ openLetter(number, caller) {
1269
1735
  const open = this.store.listLetters({
1270
- job: job.number,
1736
+ job: number,
1271
1737
  to: caller,
1272
1738
  kinds: NEEDS_ANSWER,
1273
1739
  states: ['queued', 'delivered', 'read'],
@@ -1275,11 +1741,11 @@ export class BridgeDispatcher extends EventEmitter {
1275
1741
  if (open.length === 1)
1276
1742
  return open[0];
1277
1743
  if (open.length === 0) {
1278
- throw new BridgeError('invalid_letter', `Nothing on job ${job.number} waits for your answer. Send a note instead`, {
1279
- job: job.number,
1744
+ throw new BridgeError('invalid_letter', `Nothing on job ${number} waits for your answer. Send a note instead`, {
1745
+ job: number,
1280
1746
  });
1281
1747
  }
1282
- throw new BridgeError('invalid_letter', `Several letters on job ${job.number} wait for your answer: ${open.map((letter) => letter.id).join(', ')}. Say which one with inReplyTo`, { job: job.number, letters: open.map((letter) => letter.id) });
1748
+ throw new BridgeError('invalid_letter', `Several letters on job ${number} wait for your answer: ${open.map((letter) => letter.id).join(', ')}. Say which one with inReplyTo`, { job: number, letters: open.map((letter) => letter.id) });
1283
1749
  }
1284
1750
  markRead(tx, letter) {
1285
1751
  if (STATE_RANK[letter.state] >= STATE_RANK.read)
@@ -1310,6 +1776,10 @@ export class BridgeDispatcher extends EventEmitter {
1310
1776
  letter: letter.id,
1311
1777
  agent: letter.to,
1312
1778
  });
1779
+ if (letter.needsPerson)
1780
+ tx.settled.push(letter.id);
1781
+ if (letter.kind === 'permission' && letter.ask)
1782
+ tx.decided.add(letter.id);
1313
1783
  return updated;
1314
1784
  }
1315
1785
  /**