@cogitator-ai/bridge 0.0.0-stage → 0.3.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.
- package/LICENSE +21 -0
- package/README.md +330 -2
- package/dist/adapter.d.ts +123 -0
- package/dist/adapter.d.ts.map +1 -0
- package/dist/adapter.js +2 -0
- package/dist/adapter.js.map +1 -0
- package/dist/adapters/claude.d.ts +90 -0
- package/dist/adapters/claude.d.ts.map +1 -0
- package/dist/adapters/claude.js +359 -0
- package/dist/adapters/claude.js.map +1 -0
- package/dist/adapters/codex.d.ts +58 -0
- package/dist/adapters/codex.d.ts.map +1 -0
- package/dist/adapters/codex.js +330 -0
- package/dist/adapters/codex.js.map +1 -0
- package/dist/adapters/exec.d.ts +57 -0
- package/dist/adapters/exec.d.ts.map +1 -0
- package/dist/adapters/exec.js +149 -0
- package/dist/adapters/exec.js.map +1 -0
- package/dist/adapters/hosted.d.ts +168 -0
- package/dist/adapters/hosted.d.ts.map +1 -0
- package/dist/adapters/hosted.js +361 -0
- package/dist/adapters/hosted.js.map +1 -0
- package/dist/client.d.ts +81 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +216 -0
- package/dist/client.js.map +1 -0
- package/dist/dispatcher.d.ts +296 -0
- package/dist/dispatcher.d.ts.map +1 -0
- package/dist/dispatcher.js +1524 -0
- package/dist/dispatcher.js.map +1 -0
- package/dist/errors.d.ts +10 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +16 -0
- package/dist/errors.js.map +1 -0
- package/dist/guards.d.ts +36 -0
- package/dist/guards.d.ts.map +1 -0
- package/dist/guards.js +85 -0
- package/dist/guards.js.map +1 -0
- package/dist/host.d.ts +49 -0
- package/dist/host.d.ts.map +1 -0
- package/dist/host.js +150 -0
- package/dist/host.js.map +1 -0
- package/dist/index.d.ts +50 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +32 -0
- package/dist/index.js.map +1 -0
- package/dist/inputs.d.ts +184 -0
- package/dist/inputs.d.ts.map +1 -0
- package/dist/inputs.js +116 -0
- package/dist/inputs.js.map +1 -0
- package/dist/job-record.d.ts +47 -0
- package/dist/job-record.d.ts.map +1 -0
- package/dist/job-record.js +65 -0
- package/dist/job-record.js.map +1 -0
- package/dist/letters.d.ts +49 -0
- package/dist/letters.d.ts.map +1 -0
- package/dist/letters.js +96 -0
- package/dist/letters.js.map +1 -0
- package/dist/paths.d.ts +38 -0
- package/dist/paths.d.ts.map +1 -0
- package/dist/paths.js +149 -0
- package/dist/paths.js.map +1 -0
- package/dist/protocol.d.ts +83 -0
- package/dist/protocol.d.ts.map +1 -0
- package/dist/protocol.js +71 -0
- package/dist/protocol.js.map +1 -0
- package/dist/registry.d.ts +62 -0
- package/dist/registry.d.ts.map +1 -0
- package/dist/registry.js +185 -0
- package/dist/registry.js.map +1 -0
- package/dist/server.d.ts +31 -0
- package/dist/server.d.ts.map +1 -0
- package/dist/server.js +254 -0
- package/dist/server.js.map +1 -0
- package/dist/store/sqlite.d.ts +56 -0
- package/dist/store/sqlite.d.ts.map +1 -0
- package/dist/store/sqlite.js +737 -0
- package/dist/store/sqlite.js.map +1 -0
- package/dist/store/store.d.ts +128 -0
- package/dist/store/store.d.ts.map +1 -0
- package/dist/store/store.js +2 -0
- package/dist/store/store.js.map +1 -0
- package/dist/testing/conformance.d.ts +65 -0
- package/dist/testing/conformance.d.ts.map +1 -0
- package/dist/testing/conformance.js +217 -0
- package/dist/testing/conformance.js.map +1 -0
- package/dist/testing/fake-harnesses.d.ts +101 -0
- package/dist/testing/fake-harnesses.d.ts.map +1 -0
- package/dist/testing/fake-harnesses.js +291 -0
- package/dist/testing/fake-harnesses.js.map +1 -0
- package/dist/testing/index.d.ts +5 -0
- package/dist/testing/index.d.ts.map +1 -0
- package/dist/testing/index.js +3 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/types.d.ts +286 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +132 -0
- package/dist/types.js.map +1 -0
- package/dist/waiter.d.ts +36 -0
- package/dist/waiter.d.ts.map +1 -0
- package/dist/waiter.js +92 -0
- package/dist/waiter.js.map +1 -0
- package/fakes/claude.mjs +450 -0
- package/fakes/codex.mjs +391 -0
- package/fakes/lib.mjs +507 -0
- package/package.json +76 -3
|
@@ -0,0 +1,1524 @@
|
|
|
1
|
+
import { EventEmitter } from 'node:events';
|
|
2
|
+
import { isAbsolute, resolve as resolvePath } from 'node:path';
|
|
3
|
+
import { TaskManager, textPart, toMessage } from '@cogitator-ai/a2a';
|
|
4
|
+
import { BridgeError } from './errors.js';
|
|
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';
|
|
7
|
+
import { isFinishedJobState, jobOf, jobRecordOf } from './job-record.js';
|
|
8
|
+
import { expectationOf, forHistory, newLetterId, normalizeBody, oneLine, quoted, renderLetter, repeats, titleOf, } from './letters.js';
|
|
9
|
+
import { canonicalPath, findCheckoutRoot, findProjectRoot, isInside } from './paths.js';
|
|
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';
|
|
12
|
+
const ACTIVE_JOB_STATES = ['submitted', 'working', 'input-required'];
|
|
13
|
+
const UNREAD_STATES = ['queued', 'delivered'];
|
|
14
|
+
const NEEDS_ANSWER = ['question', 'permission'];
|
|
15
|
+
const REMINDER_QUOTE_LENGTH = 500;
|
|
16
|
+
/**
|
|
17
|
+
* The most characters of letter text one answer carries. A line of the socket holds 16 MiB, and
|
|
18
|
+
* an answer that does not fit would be lost after the call already changed what it returned
|
|
19
|
+
*/
|
|
20
|
+
const MAX_ANSWER_CHARS = 2_000_000;
|
|
21
|
+
/** Why a job that passed its deadline failed, with the time it really had. */
|
|
22
|
+
function ranOutOfTime(job) {
|
|
23
|
+
const had = Date.parse(job.deadlineAt) - Date.parse(job.createdAt);
|
|
24
|
+
return had < job.budget.durationMs && job.parent !== undefined
|
|
25
|
+
? `it ran longer than the ${formatDuration(had)} that job #${job.parent}, which it is part of, had left`
|
|
26
|
+
: `it ran longer than its ${formatDuration(job.budget.durationMs)} budget`;
|
|
27
|
+
}
|
|
28
|
+
/**
|
|
29
|
+
* As many of `items`, in order, as fit `budget` characters by `sizeOf`. The first one is taken
|
|
30
|
+
* even when it alone is over the budget, unless `orNone` says an empty answer is fine.
|
|
31
|
+
*/
|
|
32
|
+
function fitting(items, sizeOf, budget = MAX_ANSWER_CHARS, orNone = false) {
|
|
33
|
+
const taken = [];
|
|
34
|
+
let size = 0;
|
|
35
|
+
for (const item of items) {
|
|
36
|
+
size += sizeOf(item);
|
|
37
|
+
if ((taken.length > 0 || orNone) && size > budget)
|
|
38
|
+
break;
|
|
39
|
+
taken.push(item);
|
|
40
|
+
}
|
|
41
|
+
return taken;
|
|
42
|
+
}
|
|
43
|
+
const STATE_RANK = {
|
|
44
|
+
queued: 0,
|
|
45
|
+
delivered: 1,
|
|
46
|
+
read: 2,
|
|
47
|
+
handled: 3,
|
|
48
|
+
};
|
|
49
|
+
/** A call the bridge refuses after writing down why: what it wrote stays, the caller gets the error. */
|
|
50
|
+
class Refusal {
|
|
51
|
+
error;
|
|
52
|
+
constructor(error) {
|
|
53
|
+
this.error = error;
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
function parse(schema, input, what) {
|
|
57
|
+
const parsed = schema.safeParse(input);
|
|
58
|
+
if (parsed.success)
|
|
59
|
+
return parsed.data;
|
|
60
|
+
const issue = parsed.error.issues[0];
|
|
61
|
+
const path = issue.path.length > 0 ? `${issue.path.join('.')}: ` : '';
|
|
62
|
+
throw new BridgeError('invalid_input', `${what}: ${path}${issue.message}`);
|
|
63
|
+
}
|
|
64
|
+
function userMessage(text) {
|
|
65
|
+
return toMessage({ role: 'user', parts: [textPart(text)] });
|
|
66
|
+
}
|
|
67
|
+
function asError(error) {
|
|
68
|
+
return error instanceof Error ? error : new Error(String(error));
|
|
69
|
+
}
|
|
70
|
+
/** `work`, or a rejection when it takes longer than `ms`. */
|
|
71
|
+
function within(work, ms, what) {
|
|
72
|
+
return new Promise((resolve, reject) => {
|
|
73
|
+
const timer = setTimeout(() => reject(new Error(`${what} took longer than ${ms} ms`)), ms);
|
|
74
|
+
work.then((value) => {
|
|
75
|
+
clearTimeout(timer);
|
|
76
|
+
resolve(value);
|
|
77
|
+
}, (error) => {
|
|
78
|
+
clearTimeout(timer);
|
|
79
|
+
reject(asError(error));
|
|
80
|
+
});
|
|
81
|
+
});
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* The bridge itself: it keeps jobs, letters and the address book, decides who a letter is for,
|
|
85
|
+
* applies the limits and hands letters to the adapters of the harnesses. It never calls a model
|
|
86
|
+
* and never waits for an agent: every call answers at once, and whatever comes later arrives as
|
|
87
|
+
* a letter.
|
|
88
|
+
*
|
|
89
|
+
* One dispatcher runs per machine. Calls are handled one at a time, each in a transaction of the
|
|
90
|
+
* store, so a call either leaves everything it did or nothing.
|
|
91
|
+
*
|
|
92
|
+
* @example
|
|
93
|
+
* ```ts
|
|
94
|
+
* const store = await SqliteBridgeStore.open(':memory:');
|
|
95
|
+
* const bridge = new BridgeDispatcher({ store });
|
|
96
|
+
* const claude = await bridge.register({ harness: 'claude-code', sessionId: 'a', cwd: '/work/app' });
|
|
97
|
+
* const codex = await bridge.register({ harness: 'codex', sessionId: 'b', cwd: '/work/app' });
|
|
98
|
+
*
|
|
99
|
+
* const { job } = await bridge.createJob(claude.name, { to: 'codex', body: 'Write the tests' });
|
|
100
|
+
* const [task] = await bridge.inbox(codex.name);
|
|
101
|
+
* await bridge.send(codex.name, { job: job.number, kind: 'report', body: 'Done: 14 tests' });
|
|
102
|
+
* ```
|
|
103
|
+
*/
|
|
104
|
+
export class BridgeDispatcher extends EventEmitter {
|
|
105
|
+
limits;
|
|
106
|
+
store;
|
|
107
|
+
tasks;
|
|
108
|
+
adapters = new Map();
|
|
109
|
+
now;
|
|
110
|
+
letterId;
|
|
111
|
+
onError;
|
|
112
|
+
assertWritable;
|
|
113
|
+
queue = Promise.resolve();
|
|
114
|
+
deliveries = new Map();
|
|
115
|
+
background = new Set();
|
|
116
|
+
/**
|
|
117
|
+
* Agents whose session an adapter is starting right now. Nothing is pushed to them until the
|
|
118
|
+
* adapter reports back, since it may have handed the job's first letter over itself
|
|
119
|
+
*/
|
|
120
|
+
starting = new Set();
|
|
121
|
+
/** The waiter of each agent that has one, see `wait` */
|
|
122
|
+
waiters = new Map();
|
|
123
|
+
/**
|
|
124
|
+
* Letters somebody holds right now: a waiter that has not confirmed them yet, or an adapter in
|
|
125
|
+
* the middle of pushing one. Nobody else is given a letter in hand, so a session reached two
|
|
126
|
+
* ways does not get it twice
|
|
127
|
+
*/
|
|
128
|
+
inHand = new Map();
|
|
129
|
+
/** What each harness with an adapter that lists its sessions said of them, see `checkPresence` */
|
|
130
|
+
presence = new Map();
|
|
131
|
+
listing = new Set();
|
|
132
|
+
presenceCheckedAt = Number.NEGATIVE_INFINITY;
|
|
133
|
+
/** Set once `close` was called: nothing new is delivered, what runs is waited for */
|
|
134
|
+
closing = false;
|
|
135
|
+
closed = false;
|
|
136
|
+
constructor(options) {
|
|
137
|
+
super();
|
|
138
|
+
this.store = options.store;
|
|
139
|
+
this.tasks = new TaskManager({ taskStore: options.store.tasks });
|
|
140
|
+
this.limits = resolveLimits(DEFAULT_LIMITS, options.limits);
|
|
141
|
+
this.now = options.now ?? Date.now;
|
|
142
|
+
this.letterId = options.newLetterId ?? newLetterId;
|
|
143
|
+
this.onError = options.onError ?? (() => undefined);
|
|
144
|
+
this.assertWritable = options.assertWritable;
|
|
145
|
+
for (const adapter of options.adapters ?? []) {
|
|
146
|
+
const harness = parse(HarnessNameSchema, adapter.harness, 'Cannot use the adapter');
|
|
147
|
+
if (this.adapters.has(harness)) {
|
|
148
|
+
throw new BridgeError('invalid_input', `Two adapters for the harness ${harness}`);
|
|
149
|
+
}
|
|
150
|
+
this.adapters.set(harness, adapter);
|
|
151
|
+
}
|
|
152
|
+
for (const adapter of this.adapters.values())
|
|
153
|
+
adapter.attach?.(this);
|
|
154
|
+
}
|
|
155
|
+
/**
|
|
156
|
+
* Puts the calling session into the address book, or finds it there. A session is known by
|
|
157
|
+
* its harness and the harness's own id, so calling again from the same session returns the
|
|
158
|
+
* same agent.
|
|
159
|
+
*/
|
|
160
|
+
async register(identity) {
|
|
161
|
+
const caller = parse(CallerIdentitySchema, identity, 'Cannot register the session');
|
|
162
|
+
return this.mutate(async (tx) => {
|
|
163
|
+
const now = this.iso();
|
|
164
|
+
const cwd = canonicalPath(caller.cwd);
|
|
165
|
+
const project = canonicalPath(caller.project ?? findProjectRoot(cwd));
|
|
166
|
+
const adapter = this.adapters.get(caller.harness);
|
|
167
|
+
const reach = {
|
|
168
|
+
delivery: adapter?.delivery ?? INBOX_DELIVERY,
|
|
169
|
+
capabilities: adapter?.capabilities ?? NO_CAPABILITIES,
|
|
170
|
+
};
|
|
171
|
+
const known = this.store.agentOfSession(caller.harness, caller.sessionId);
|
|
172
|
+
if (known) {
|
|
173
|
+
const agent = {
|
|
174
|
+
...known,
|
|
175
|
+
...reach,
|
|
176
|
+
cwd,
|
|
177
|
+
project,
|
|
178
|
+
...(caller.sessionName && { sessionName: caller.sessionName }),
|
|
179
|
+
status: 'active',
|
|
180
|
+
lastSeenAt: now,
|
|
181
|
+
};
|
|
182
|
+
this.store.putAgent(agent);
|
|
183
|
+
if (known.status !== 'active') {
|
|
184
|
+
this.journal(tx, {
|
|
185
|
+
type: 'agent.registered',
|
|
186
|
+
agent: agent.name,
|
|
187
|
+
data: { harness: agent.harness, returned: true },
|
|
188
|
+
});
|
|
189
|
+
tx.wake.add(agent.name);
|
|
190
|
+
}
|
|
191
|
+
return agent;
|
|
192
|
+
}
|
|
193
|
+
const started = caller.agentName ? this.store.getAgent(caller.agentName) : undefined;
|
|
194
|
+
if (started?.harness === caller.harness &&
|
|
195
|
+
started.status === 'starting' &&
|
|
196
|
+
started.project === project) {
|
|
197
|
+
const agent = {
|
|
198
|
+
...started,
|
|
199
|
+
...reach,
|
|
200
|
+
sessionId: caller.sessionId,
|
|
201
|
+
...(caller.sessionName && { sessionName: caller.sessionName }),
|
|
202
|
+
status: 'active',
|
|
203
|
+
lastSeenAt: now,
|
|
204
|
+
};
|
|
205
|
+
this.store.putAgent(agent);
|
|
206
|
+
this.journal(tx, {
|
|
207
|
+
type: 'agent.registered',
|
|
208
|
+
agent: agent.name,
|
|
209
|
+
data: { harness: agent.harness, started: true },
|
|
210
|
+
});
|
|
211
|
+
tx.wake.add(agent.name);
|
|
212
|
+
return agent;
|
|
213
|
+
}
|
|
214
|
+
const agent = {
|
|
215
|
+
name: allocateAgentName(this.store, caller.harness, project),
|
|
216
|
+
harness: caller.harness,
|
|
217
|
+
sessionId: caller.sessionId,
|
|
218
|
+
...(caller.sessionName && { sessionName: caller.sessionName }),
|
|
219
|
+
project,
|
|
220
|
+
cwd,
|
|
221
|
+
...reach,
|
|
222
|
+
status: 'active',
|
|
223
|
+
registeredAt: now,
|
|
224
|
+
lastSeenAt: now,
|
|
225
|
+
};
|
|
226
|
+
this.store.putAgent(agent);
|
|
227
|
+
this.journal(tx, {
|
|
228
|
+
type: 'agent.registered',
|
|
229
|
+
agent: agent.name,
|
|
230
|
+
data: { harness: agent.harness, project },
|
|
231
|
+
});
|
|
232
|
+
return agent;
|
|
233
|
+
});
|
|
234
|
+
}
|
|
235
|
+
/**
|
|
236
|
+
* Hands a job to another agent and returns at once with its number. The one it is for is
|
|
237
|
+
* found by address, and started when no session fits and the harness's adapter can start one.
|
|
238
|
+
*
|
|
239
|
+
* @throws BridgeError `not_registered`, `unknown_agent`, `ambiguous_agent`, `no_session`,
|
|
240
|
+
* `depth_exceeded`, `invalid_input`
|
|
241
|
+
*/
|
|
242
|
+
async createJob(caller, input) {
|
|
243
|
+
const request = parse(CreateJobInputSchema, input, 'Cannot create the job');
|
|
244
|
+
this.checkBody(request.body);
|
|
245
|
+
const outcome = await this.asCaller(caller, async (tx) => {
|
|
246
|
+
const from = this.requireCaller(caller);
|
|
247
|
+
if (request.letterId) {
|
|
248
|
+
const sent = this.store.getLetter(request.letterId);
|
|
249
|
+
if (sent) {
|
|
250
|
+
if (sent.kind !== 'task' || sent.from !== from.name || sent.body !== request.body) {
|
|
251
|
+
throw new BridgeError('invalid_letter', `The letter id ${request.letterId} belongs to another letter. Give a new job a new id`, { letter: request.letterId });
|
|
252
|
+
}
|
|
253
|
+
return { job: this.requireJob(sent.job).job, letter: sent, duplicate: true };
|
|
254
|
+
}
|
|
255
|
+
}
|
|
256
|
+
const resolution = resolveAddress(this.store, request.to, {
|
|
257
|
+
project: from.project,
|
|
258
|
+
caller: from.name,
|
|
259
|
+
now: this.now(),
|
|
260
|
+
canSpawn: (harness) => this.adapters.get(harness)?.createSession !== undefined,
|
|
261
|
+
});
|
|
262
|
+
const carriedOut = this.store
|
|
263
|
+
.jobTasks({ to: from.name, states: ACTIVE_JOB_STATES })
|
|
264
|
+
.flatMap((task) => jobOf(task) ?? []);
|
|
265
|
+
let parent;
|
|
266
|
+
if (request.parent !== undefined) {
|
|
267
|
+
parent = carriedOut.find((job) => job.number === request.parent);
|
|
268
|
+
if (!parent) {
|
|
269
|
+
throw new BridgeError('invalid_input', `Job ${request.parent} is not a job you are carrying out, so it cannot be the parent of a new one`, { parent: request.parent });
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
else {
|
|
273
|
+
parent = carriedOut.reduce((deepest, job) => (deepest && deepest.depth >= job.depth ? deepest : job), undefined);
|
|
274
|
+
}
|
|
275
|
+
let depth;
|
|
276
|
+
try {
|
|
277
|
+
depth = nextDepth(parent?.depth, this.limits);
|
|
278
|
+
}
|
|
279
|
+
catch (error) {
|
|
280
|
+
if (!(error instanceof BridgeError))
|
|
281
|
+
throw error;
|
|
282
|
+
this.journal(tx, {
|
|
283
|
+
type: 'letter.rejected',
|
|
284
|
+
agent: from.name,
|
|
285
|
+
data: {
|
|
286
|
+
reason: error.code,
|
|
287
|
+
to: request.to,
|
|
288
|
+
title: request.title ?? titleOf(request.body),
|
|
289
|
+
},
|
|
290
|
+
});
|
|
291
|
+
return new Refusal(error);
|
|
292
|
+
}
|
|
293
|
+
const budget = resolveBudget(request.budget, this.limits);
|
|
294
|
+
const cwd = request.cwd
|
|
295
|
+
? canonicalPath(isAbsolute(request.cwd) ? request.cwd : resolvePath(from.cwd, request.cwd))
|
|
296
|
+
: from.cwd;
|
|
297
|
+
if (!isInside(from.project, cwd) && !isInside(findCheckoutRoot(from.cwd), cwd)) {
|
|
298
|
+
throw new BridgeError('invalid_input', `A job is done inside the project it is handed over in (${from.project}) or the checkout you work in, and ${cwd} is outside both`, { cwd, project: from.project });
|
|
299
|
+
}
|
|
300
|
+
const now = this.now();
|
|
301
|
+
const refusal = this.handOverRefusal(from, resolution, request.body, cwd, now);
|
|
302
|
+
if (refusal) {
|
|
303
|
+
this.journal(tx, {
|
|
304
|
+
type: 'letter.rejected',
|
|
305
|
+
agent: from.name,
|
|
306
|
+
data: {
|
|
307
|
+
reason: refusal.code,
|
|
308
|
+
to: request.to,
|
|
309
|
+
title: request.title ?? titleOf(request.body),
|
|
310
|
+
},
|
|
311
|
+
});
|
|
312
|
+
return new Refusal(refusal);
|
|
313
|
+
}
|
|
314
|
+
let to;
|
|
315
|
+
if (resolution.kind === 'agent') {
|
|
316
|
+
to = resolution.agent;
|
|
317
|
+
}
|
|
318
|
+
else {
|
|
319
|
+
const adapter = this.adapters.get(resolution.harness);
|
|
320
|
+
to = {
|
|
321
|
+
name: allocateAgentName(this.store, resolution.harness, from.project),
|
|
322
|
+
harness: resolution.harness,
|
|
323
|
+
sessionId: '',
|
|
324
|
+
...(resolution.sessionName && { sessionName: resolution.sessionName }),
|
|
325
|
+
project: from.project,
|
|
326
|
+
cwd,
|
|
327
|
+
delivery: adapter?.delivery ?? INBOX_DELIVERY,
|
|
328
|
+
capabilities: adapter?.capabilities ?? NO_CAPABILITIES,
|
|
329
|
+
status: 'starting',
|
|
330
|
+
registeredAt: this.iso(now),
|
|
331
|
+
lastSeenAt: this.iso(now),
|
|
332
|
+
};
|
|
333
|
+
this.store.putAgent(to);
|
|
334
|
+
}
|
|
335
|
+
const number = this.store.nextJobNumber();
|
|
336
|
+
const record = {
|
|
337
|
+
number,
|
|
338
|
+
title: request.title ?? titleOf(request.body),
|
|
339
|
+
from: from.name,
|
|
340
|
+
to: to.name,
|
|
341
|
+
project: from.project,
|
|
342
|
+
cwd,
|
|
343
|
+
checks: request.checks ?? [],
|
|
344
|
+
budget,
|
|
345
|
+
lettersUsed: 1,
|
|
346
|
+
depth,
|
|
347
|
+
...(parent && { parent: parent.number }),
|
|
348
|
+
createdAt: this.iso(now),
|
|
349
|
+
deadlineAt: this.iso(Math.min(now + budget.durationMs, parent ? Date.parse(parent.deadlineAt) : Infinity)),
|
|
350
|
+
};
|
|
351
|
+
const firstLetterId = request.letterId ?? this.letterId();
|
|
352
|
+
const history = userMessage(forHistory(request.body, firstLetterId));
|
|
353
|
+
const task = await this.tasks.createTask(history, undefined, {
|
|
354
|
+
agentName: to.name,
|
|
355
|
+
metadata: { [BRIDGE_JOB_KEY]: record },
|
|
356
|
+
});
|
|
357
|
+
this.journal(tx, {
|
|
358
|
+
type: 'job.created',
|
|
359
|
+
job: number,
|
|
360
|
+
agent: from.name,
|
|
361
|
+
data: { title: record.title, from: from.name, to: to.name, depth, cwd },
|
|
362
|
+
});
|
|
363
|
+
const letter = this.accept(tx, {
|
|
364
|
+
id: firstLetterId,
|
|
365
|
+
job: number,
|
|
366
|
+
kind: 'task',
|
|
367
|
+
from: from.name,
|
|
368
|
+
to: to.name,
|
|
369
|
+
body: request.body,
|
|
370
|
+
replyDueAt: this.iso(now + budget.replyTimeoutMs),
|
|
371
|
+
});
|
|
372
|
+
if (resolution.kind === 'spawn') {
|
|
373
|
+
tx.wake.delete(to.name);
|
|
374
|
+
tx.spawns.push({ agent: to.name, job: number, letter: letter.id });
|
|
375
|
+
}
|
|
376
|
+
return { job: this.jobFrom(task), letter, duplicate: false };
|
|
377
|
+
});
|
|
378
|
+
if (outcome instanceof Refusal)
|
|
379
|
+
throw outcome.error;
|
|
380
|
+
return outcome;
|
|
381
|
+
}
|
|
382
|
+
/**
|
|
383
|
+
* Sends a letter on a job to its other party: a question, an answer, a report that ends the
|
|
384
|
+
* job, a note. The call returns once the bridge has the letter, the answer comes as a letter.
|
|
385
|
+
*
|
|
386
|
+
* @throws BridgeError `not_registered`, `unknown_job`, `not_a_party`, `job_finished`,
|
|
387
|
+
* `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)
|
|
389
|
+
*/
|
|
390
|
+
async send(caller, input) {
|
|
391
|
+
const request = parse(SendLetterInputSchema, input, 'Cannot send the letter');
|
|
392
|
+
this.checkBody(request.body);
|
|
393
|
+
const outcome = await this.asCaller(caller, async (tx) => {
|
|
394
|
+
const from = this.requireCaller(caller);
|
|
395
|
+
if (request.id) {
|
|
396
|
+
const sent = this.store.getLetter(request.id);
|
|
397
|
+
if (sent) {
|
|
398
|
+
if (sent.from !== from.name ||
|
|
399
|
+
sent.job !== request.job ||
|
|
400
|
+
sent.kind !== request.kind ||
|
|
401
|
+
sent.body !== request.body) {
|
|
402
|
+
throw new BridgeError('invalid_letter', `The letter id ${request.id} belongs to another letter. Give a new letter a new id`, { letter: request.id });
|
|
403
|
+
}
|
|
404
|
+
return { letter: sent, job: this.requireJob(sent.job).job, duplicate: true };
|
|
405
|
+
}
|
|
406
|
+
}
|
|
407
|
+
const { job } = this.requireJob(request.job);
|
|
408
|
+
if (from.name !== job.from && from.name !== job.to) {
|
|
409
|
+
throw new BridgeError('not_a_party', `Job ${job.number} is between ${job.from} and ${job.to}`, {
|
|
410
|
+
job: job.number,
|
|
411
|
+
});
|
|
412
|
+
}
|
|
413
|
+
if (isFinishedJobState(job.state)) {
|
|
414
|
+
throw new BridgeError('job_finished', `Job ${job.number} is ${job.state}${job.reason ? ` (${job.reason})` : ''}. Hand over a new job to go on`, { job: job.number, state: job.state });
|
|
415
|
+
}
|
|
416
|
+
const to = from.name === job.to ? job.from : job.to;
|
|
417
|
+
const isAssignee = from.name === job.to;
|
|
418
|
+
if (request.kind === 'report' && !isAssignee) {
|
|
419
|
+
throw new BridgeError('invalid_letter', `Only ${job.to}, who carries job ${job.number} out, reports on it`);
|
|
420
|
+
}
|
|
421
|
+
const answered = this.answeredLetter(request, job, from.name);
|
|
422
|
+
const previous = this.store.listLetters({
|
|
423
|
+
job: job.number,
|
|
424
|
+
from: from.name,
|
|
425
|
+
to,
|
|
426
|
+
newestFirst: true,
|
|
427
|
+
limit: 1,
|
|
428
|
+
})[0];
|
|
429
|
+
if (repeats(previous, request.kind, request.body, answered?.id)) {
|
|
430
|
+
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
|
+
this.journal(tx, {
|
|
432
|
+
type: 'letter.rejected',
|
|
433
|
+
job: job.number,
|
|
434
|
+
agent: from.name,
|
|
435
|
+
data: { reason: error.code, kind: request.kind, to, previous: previous.id },
|
|
436
|
+
});
|
|
437
|
+
return new Refusal(error);
|
|
438
|
+
}
|
|
439
|
+
const now = this.now();
|
|
440
|
+
const exhausted = exhaustedBudget(job, now, request.kind);
|
|
441
|
+
if (exhausted) {
|
|
442
|
+
const reason = exhausted === 'letters'
|
|
443
|
+
? `the job used all ${job.budget.letters} letters of its budget`
|
|
444
|
+
: ranOutOfTime(job);
|
|
445
|
+
await this.failJob(tx, job.number, reason);
|
|
446
|
+
return new Refusal(new BridgeError('budget_exhausted', `Job ${job.number} has failed: ${reason}. The letter was not delivered`, {
|
|
447
|
+
job: job.number,
|
|
448
|
+
exhausted,
|
|
449
|
+
}));
|
|
450
|
+
}
|
|
451
|
+
for (const waiting of this.store.listLetters({
|
|
452
|
+
job: job.number,
|
|
453
|
+
to: from.name,
|
|
454
|
+
states: ['delivered'],
|
|
455
|
+
})) {
|
|
456
|
+
this.markRead(tx, waiting);
|
|
457
|
+
}
|
|
458
|
+
if (isAssignee && job.state === 'submitted')
|
|
459
|
+
await this.pickUp(tx, job);
|
|
460
|
+
const letter = this.accept(tx, {
|
|
461
|
+
id: request.id ?? this.letterId(),
|
|
462
|
+
job: job.number,
|
|
463
|
+
kind: request.kind,
|
|
464
|
+
from: from.name,
|
|
465
|
+
to,
|
|
466
|
+
body: request.body,
|
|
467
|
+
...(answered && { inReplyTo: answered.id }),
|
|
468
|
+
...(request.kind === 'report' && { outcome: request.outcome ?? 'completed' }),
|
|
469
|
+
...(expectationOf(request.kind) === 'reply' && {
|
|
470
|
+
replyDueAt: this.iso(now + job.budget.replyTimeoutMs),
|
|
471
|
+
}),
|
|
472
|
+
});
|
|
473
|
+
await this.patchRecord(job.taskId, { lettersUsed: job.lettersUsed + 1 });
|
|
474
|
+
if (answered && request.kind === 'answer')
|
|
475
|
+
this.markHandled(tx, answered);
|
|
476
|
+
if (request.kind === 'report') {
|
|
477
|
+
const state = letter.outcome === 'failed' ? 'failed' : 'completed';
|
|
478
|
+
await this.transition(tx, job.number, state, forHistory(request.body, letter.id));
|
|
479
|
+
if (state === 'failed')
|
|
480
|
+
await this.patchRecord(job.taskId, { reason: `reported as failed by ${from.name}` });
|
|
481
|
+
this.closeLetters(tx, job.number, letter.id);
|
|
482
|
+
await this.cancelChildren(tx, job);
|
|
483
|
+
}
|
|
484
|
+
else if (isAssignee && NEEDS_ANSWER.includes(request.kind)) {
|
|
485
|
+
await this.transition(tx, job.number, 'input-required', forHistory(request.body, letter.id));
|
|
486
|
+
}
|
|
487
|
+
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
|
+
}
|
|
497
|
+
}
|
|
498
|
+
return { letter, job: this.requireJob(job.number).job, duplicate: false };
|
|
499
|
+
});
|
|
500
|
+
if (outcome instanceof Refusal)
|
|
501
|
+
throw outcome.error;
|
|
502
|
+
return outcome;
|
|
503
|
+
}
|
|
504
|
+
/**
|
|
505
|
+
* The letters waiting for the caller, oldest first, each with the text to show. Taking them
|
|
506
|
+
* marks them read, and taking a job's first letter starts the job. One call returns `limit`
|
|
507
|
+
* letters at most (20 by default) and no more text than fits one answer: only the letters
|
|
508
|
+
* returned are marked, the rest wait for the next call. A session that may have missed an
|
|
509
|
+
* answer asks again with `unhandled`, which adds the newest of the letters it took before and
|
|
510
|
+
* has not answered or put away, in the room the new letters leave: what was not seen yet
|
|
511
|
+
* always comes first. `afterSeq` looks further than one call returns.
|
|
512
|
+
*/
|
|
513
|
+
async inbox(caller, input = {}) {
|
|
514
|
+
const request = parse(InboxInputSchema, input, 'Cannot read the inbox');
|
|
515
|
+
return this.asCaller(caller, async (tx) => {
|
|
516
|
+
const agent = this.requireCaller(caller);
|
|
517
|
+
const limit = request.limit ?? DEFAULT_INBOX_LIMIT;
|
|
518
|
+
const scope = {
|
|
519
|
+
to: agent.name,
|
|
520
|
+
...(request.job !== undefined && { job: request.job }),
|
|
521
|
+
...(request.afterSeq !== undefined && { afterSeq: request.afterSeq }),
|
|
522
|
+
};
|
|
523
|
+
const unread = this.store.listLetters({ ...scope, states: UNREAD_STATES, limit });
|
|
524
|
+
const taken = request.unhandled && unread.length < limit
|
|
525
|
+
? this.store.listLetters({
|
|
526
|
+
...scope,
|
|
527
|
+
states: ['read'],
|
|
528
|
+
limit: limit - unread.length,
|
|
529
|
+
newestFirst: request.afterSeq === undefined,
|
|
530
|
+
})
|
|
531
|
+
: [];
|
|
532
|
+
const size = (letter) => 2 * letter.body.length;
|
|
533
|
+
const fresh = fitting(unread, size);
|
|
534
|
+
const left = MAX_ANSWER_CHARS - fresh.reduce((sum, letter) => sum + size(letter), 0);
|
|
535
|
+
const again = fresh.length === unread.length ? fitting(taken, size, left, fresh.length > 0) : [];
|
|
536
|
+
const letters = [...again, ...fresh].sort((a, b) => a.seq - b.seq);
|
|
537
|
+
const rendered = [];
|
|
538
|
+
for (const letter of letters) {
|
|
539
|
+
const { job } = this.requireJob(letter.job);
|
|
540
|
+
let current = letter;
|
|
541
|
+
if (!request.peek && UNREAD_STATES.includes(letter.state)) {
|
|
542
|
+
current = this.markRead(tx, letter);
|
|
543
|
+
if (letter.kind === 'task' && job.state === 'submitted')
|
|
544
|
+
await this.pickUp(tx, job);
|
|
545
|
+
}
|
|
546
|
+
rendered.push(renderLetter(current, job));
|
|
547
|
+
}
|
|
548
|
+
return rendered;
|
|
549
|
+
});
|
|
550
|
+
}
|
|
551
|
+
/**
|
|
552
|
+
* Waits for the caller's mail: answers at once when letters are queued for it, otherwise as
|
|
553
|
+
* soon as one arrives, or with none when `timeoutMs` passes. This is how a session nothing can
|
|
554
|
+
* be pushed into still wakes: a process of its harness waits here and hands what it gets to
|
|
555
|
+
* the session, as `cogitator bridge wait` does in a hook of Claude Code. The letters stay
|
|
556
|
+
* queued until the waiter says it handed them over (`delivered`), so a waiter that dies with
|
|
557
|
+
* them in hand loses nothing. A session has one waiter: a new one ends the one before it.
|
|
558
|
+
* Aborting `signal` ends the wait, as the socket server does when the connection closes.
|
|
559
|
+
*/
|
|
560
|
+
async wait(caller, input = {}, signal) {
|
|
561
|
+
const request = parse(WaitInputSchema, input, 'Cannot wait for letters');
|
|
562
|
+
const limit = request.limit ?? DEFAULT_INBOX_LIMIT;
|
|
563
|
+
const outcome = await this.asCaller(caller, async () => {
|
|
564
|
+
const agent = this.requireCaller(caller);
|
|
565
|
+
this.waiters.get(agent.name)?.end('replaced');
|
|
566
|
+
this.letGo(agent.name);
|
|
567
|
+
if (signal?.aborted || this.closing)
|
|
568
|
+
return { letters: [], reason: 'closed' };
|
|
569
|
+
const letters = this.starting.has(agent.name) ? [] : this.queuedFor(agent.name, limit);
|
|
570
|
+
if (letters.length > 0) {
|
|
571
|
+
this.hand(agent.name, letters, signal);
|
|
572
|
+
return { letters, reason: 'letters' };
|
|
573
|
+
}
|
|
574
|
+
return {
|
|
575
|
+
later: this.arm(agent.name, limit, request.timeoutMs ?? DEFAULT_WAIT_MS, signal),
|
|
576
|
+
};
|
|
577
|
+
});
|
|
578
|
+
return 'later' in outcome ? outcome.later : outcome;
|
|
579
|
+
}
|
|
580
|
+
/**
|
|
581
|
+
* Says the caller's waiter handed these letters to its session. A job handed over this way
|
|
582
|
+
* counts as taken, as one an adapter pushed does. A letter that is not queued any more, such
|
|
583
|
+
* as one the session read from its inbox meanwhile, stays as it is.
|
|
584
|
+
*
|
|
585
|
+
* @throws BridgeError `unknown_letter` for a letter that is not addressed to the caller
|
|
586
|
+
*/
|
|
587
|
+
async delivered(caller, letterIds) {
|
|
588
|
+
const { letters: ids } = parse(DeliveredInputSchema, { letters: [...letterIds] }, 'Cannot mark the letters delivered');
|
|
589
|
+
return this.asCaller(caller, async (tx) => {
|
|
590
|
+
const agent = this.requireCaller(caller);
|
|
591
|
+
const marked = [];
|
|
592
|
+
for (const id of new Set(ids)) {
|
|
593
|
+
if (this.store.getLetter(id)?.to !== agent.name) {
|
|
594
|
+
throw new BridgeError('unknown_letter', `There is no letter ${id} addressed to you`, {
|
|
595
|
+
letter: id,
|
|
596
|
+
});
|
|
597
|
+
}
|
|
598
|
+
await this.markDelivered(tx, id, { via: 'wait' });
|
|
599
|
+
const letter = this.store.getLetter(id);
|
|
600
|
+
if (letter)
|
|
601
|
+
marked.push(letter);
|
|
602
|
+
}
|
|
603
|
+
tx.wake.add(agent.name);
|
|
604
|
+
return marked;
|
|
605
|
+
});
|
|
606
|
+
}
|
|
607
|
+
arm(name, limit, timeoutMs, signal) {
|
|
608
|
+
return new Promise((resolve) => {
|
|
609
|
+
const waiter = {
|
|
610
|
+
limit,
|
|
611
|
+
signal,
|
|
612
|
+
end: (reason, letters = []) => {
|
|
613
|
+
if (this.waiters.get(name) === waiter)
|
|
614
|
+
this.waiters.delete(name);
|
|
615
|
+
clearTimeout(timer);
|
|
616
|
+
signal?.removeEventListener('abort', onAbort);
|
|
617
|
+
resolve({ letters, reason });
|
|
618
|
+
},
|
|
619
|
+
};
|
|
620
|
+
const timer = setTimeout(() => waiter.end('timeout'), timeoutMs);
|
|
621
|
+
const onAbort = () => waiter.end('closed');
|
|
622
|
+
signal?.addEventListener('abort', onAbort, { once: true });
|
|
623
|
+
this.waiters.set(name, waiter);
|
|
624
|
+
});
|
|
625
|
+
}
|
|
626
|
+
/**
|
|
627
|
+
* The letters queued for an agent that nobody holds, oldest first, as many as one answer
|
|
628
|
+
* carries.
|
|
629
|
+
*/
|
|
630
|
+
queuedFor(name, limit) {
|
|
631
|
+
const queued = this.store
|
|
632
|
+
.listLetters({ to: name, states: ['queued'], limit })
|
|
633
|
+
.filter((letter) => !this.held(letter.id));
|
|
634
|
+
return fitting(queued, (letter) => 2 * letter.body.length).map((letter) => renderLetter(letter, this.requireJob(letter.job).job));
|
|
635
|
+
}
|
|
636
|
+
held(letterId) {
|
|
637
|
+
const holder = this.inHand.get(letterId);
|
|
638
|
+
if (!holder)
|
|
639
|
+
return false;
|
|
640
|
+
if (holder.until > this.now())
|
|
641
|
+
return true;
|
|
642
|
+
this.inHand.delete(letterId);
|
|
643
|
+
return false;
|
|
644
|
+
}
|
|
645
|
+
/**
|
|
646
|
+
* Notes that a waiter was given these letters. They are in its hand until it confirms them,
|
|
647
|
+
* its connection closes, a newer waiter of the session takes over, or `deliveryTimeoutMs`
|
|
648
|
+
* passes, whichever comes first.
|
|
649
|
+
*/
|
|
650
|
+
hand(name, letters, signal) {
|
|
651
|
+
const holder = { agent: name, until: this.now() + this.limits.deliveryTimeoutMs };
|
|
652
|
+
for (const letter of letters)
|
|
653
|
+
this.inHand.set(letter.id, holder);
|
|
654
|
+
signal?.addEventListener('abort', () => {
|
|
655
|
+
let dropped = false;
|
|
656
|
+
for (const letter of letters) {
|
|
657
|
+
if (this.inHand.get(letter.id) !== holder)
|
|
658
|
+
continue;
|
|
659
|
+
this.inHand.delete(letter.id);
|
|
660
|
+
dropped = true;
|
|
661
|
+
}
|
|
662
|
+
if (dropped)
|
|
663
|
+
this.wakeIfKnown(name);
|
|
664
|
+
}, { once: true });
|
|
665
|
+
}
|
|
666
|
+
/** Frees what the waiters of an agent hold: a newer waiter is about to take their place. */
|
|
667
|
+
letGo(name) {
|
|
668
|
+
for (const [letterId, holder] of this.inHand) {
|
|
669
|
+
if (holder.agent === name && !holder.pushing)
|
|
670
|
+
this.inHand.delete(letterId);
|
|
671
|
+
}
|
|
672
|
+
}
|
|
673
|
+
/**
|
|
674
|
+
* Says the caller is done with a letter that needs no answer. A question, a permission request
|
|
675
|
+
* and a job's first letter are not dismissed this way: they are marked read, and are done with
|
|
676
|
+
* once answered or reported on.
|
|
677
|
+
*
|
|
678
|
+
* @throws BridgeError `unknown_letter` for a letter that is not addressed to the caller
|
|
679
|
+
*/
|
|
680
|
+
async acknowledge(caller, letterId) {
|
|
681
|
+
return this.asCaller(caller, async (tx) => {
|
|
682
|
+
const agent = this.requireCaller(caller);
|
|
683
|
+
const letter = this.store.getLetter(letterId);
|
|
684
|
+
if (letter?.to !== agent.name) {
|
|
685
|
+
throw new BridgeError('unknown_letter', `There is no letter ${letterId} addressed to you`, {
|
|
686
|
+
letter: letterId,
|
|
687
|
+
});
|
|
688
|
+
}
|
|
689
|
+
if (expectationOf(letter.kind) !== 'none') {
|
|
690
|
+
const read = this.markRead(tx, letter);
|
|
691
|
+
if (letter.kind === 'task') {
|
|
692
|
+
const { job } = this.requireJob(letter.job);
|
|
693
|
+
if (job.state === 'submitted')
|
|
694
|
+
await this.pickUp(tx, job);
|
|
695
|
+
}
|
|
696
|
+
return read;
|
|
697
|
+
}
|
|
698
|
+
return this.markHandled(tx, letter);
|
|
699
|
+
});
|
|
700
|
+
}
|
|
701
|
+
/**
|
|
702
|
+
* Cancels a job. Only the agent that handed it over can, the one carrying it out reports it
|
|
703
|
+
* as failed instead.
|
|
704
|
+
*
|
|
705
|
+
* @throws BridgeError `not_a_party`, `job_finished`
|
|
706
|
+
*/
|
|
707
|
+
async cancel(caller, number, reason) {
|
|
708
|
+
return this.asCaller(caller, async (tx) => {
|
|
709
|
+
const agent = this.requireCaller(caller);
|
|
710
|
+
const { job } = this.requireJob(number);
|
|
711
|
+
if (agent.name !== job.from) {
|
|
712
|
+
throw new BridgeError('not_a_party', `Only ${job.from}, who handed job ${number} over, can cancel it. Report it as failed instead`, { job: number });
|
|
713
|
+
}
|
|
714
|
+
if (isFinishedJobState(job.state)) {
|
|
715
|
+
throw new BridgeError('job_finished', `Job ${number} is already ${job.state}`, {
|
|
716
|
+
job: number,
|
|
717
|
+
state: job.state,
|
|
718
|
+
});
|
|
719
|
+
}
|
|
720
|
+
const given = reason ? oneLine(reason) : '';
|
|
721
|
+
await this.cancelJob(tx, number, given ? `canceled by ${agent.name}: ${given}` : `canceled by ${agent.name}`, given
|
|
722
|
+
? `Job #${number} was canceled by ${agent.name}. Stop working on it. Their reason:\n${quoted(given)}`
|
|
723
|
+
: `Job #${number} was canceled by ${agent.name}. Stop working on it.`);
|
|
724
|
+
return this.requireJob(number).job;
|
|
725
|
+
});
|
|
726
|
+
}
|
|
727
|
+
/**
|
|
728
|
+
* Records whether the checks of a job confirmed its result. It is a call of the process that
|
|
729
|
+
* hosts the dispatcher and is not served on the socket: the agent that carries a job out
|
|
730
|
+
* must not be the one to say its result holds.
|
|
731
|
+
*/
|
|
732
|
+
async recordVerification(number, verification) {
|
|
733
|
+
const request = parse(VerificationInputSchema, verification, 'Cannot record the verification');
|
|
734
|
+
return this.mutate(async (tx) => {
|
|
735
|
+
const { job } = this.requireJob(number);
|
|
736
|
+
const recorded = {
|
|
737
|
+
verified: request.verified,
|
|
738
|
+
checkedAt: this.iso(),
|
|
739
|
+
...(request.summary !== undefined && { summary: request.summary }),
|
|
740
|
+
};
|
|
741
|
+
await this.patchRecord(job.taskId, { verification: recorded });
|
|
742
|
+
this.journal(tx, {
|
|
743
|
+
type: 'job.verified',
|
|
744
|
+
job: number,
|
|
745
|
+
data: {
|
|
746
|
+
verified: recorded.verified,
|
|
747
|
+
...(recorded.summary !== undefined && { summary: recorded.summary }),
|
|
748
|
+
},
|
|
749
|
+
});
|
|
750
|
+
return this.requireJob(number).job;
|
|
751
|
+
});
|
|
752
|
+
}
|
|
753
|
+
/** @throws BridgeError `unknown_job` */
|
|
754
|
+
async job(number) {
|
|
755
|
+
return this.enqueue(async () => this.requireJob(number).job);
|
|
756
|
+
}
|
|
757
|
+
/** Jobs, newest first, 200 at most unless `limit` says otherwise */
|
|
758
|
+
async jobs(filter = {}) {
|
|
759
|
+
const request = parse(JobsFilterSchema, filter, 'Cannot list jobs');
|
|
760
|
+
return this.enqueue(async () => this.store
|
|
761
|
+
.jobTasks({ ...request, limit: request.limit ?? DEFAULT_LIST_LIMIT })
|
|
762
|
+
.flatMap((task) => jobOf(task) ?? []));
|
|
763
|
+
}
|
|
764
|
+
async agents(filter = {}) {
|
|
765
|
+
const request = parse(AgentsFilterSchema, filter, 'Cannot list agents');
|
|
766
|
+
return this.enqueue(async () => this.store.listAgents(request));
|
|
767
|
+
}
|
|
768
|
+
/**
|
|
769
|
+
* Letters, oldest first, 200 at most unless `limit` says otherwise and no more text than fits
|
|
770
|
+
* one answer. Go on from the last one with `afterSeq`
|
|
771
|
+
*/
|
|
772
|
+
async letters(filter = {}) {
|
|
773
|
+
const request = parse(LettersFilterSchema, filter, 'Cannot list letters');
|
|
774
|
+
return this.enqueue(async () => fitting(this.store.listLetters({ ...request, limit: request.limit ?? DEFAULT_LIST_LIMIT }), (letter) => letter.body.length));
|
|
775
|
+
}
|
|
776
|
+
/**
|
|
777
|
+
* Entries of the journal, oldest first: the first 200 unless `limit` says otherwise, or the
|
|
778
|
+
* last `tail`, and no more text than fits one answer. Go on from the last one with `afterSeq`
|
|
779
|
+
*/
|
|
780
|
+
async readJournal(query = {}) {
|
|
781
|
+
const request = parse(JournalQuerySchema, query, 'Cannot read the journal');
|
|
782
|
+
const size = (entry) => typeof entry.data?.body === 'string' ? entry.data.body.length : 0;
|
|
783
|
+
return this.enqueue(async () => {
|
|
784
|
+
if (request.tail !== undefined) {
|
|
785
|
+
const newestFirst = this.store.readJournal(request).reverse();
|
|
786
|
+
return fitting(newestFirst, size).reverse();
|
|
787
|
+
}
|
|
788
|
+
return fitting(this.store.readJournal({ ...request, limit: request.limit ?? DEFAULT_LIST_LIMIT }), size);
|
|
789
|
+
});
|
|
790
|
+
}
|
|
791
|
+
async status() {
|
|
792
|
+
return this.enqueue(async () => ({
|
|
793
|
+
agents: this.store.listAgents({ statuses: ['active', 'starting'] }).length,
|
|
794
|
+
activeJobs: this.store.jobTasks({ states: ACTIVE_JOB_STATES }).length,
|
|
795
|
+
queuedLetters: this.store.countLetters({ states: ['queued'] }),
|
|
796
|
+
adapters: [...this.adapters.keys()],
|
|
797
|
+
waiting: [...this.waiters.keys()].sort(),
|
|
798
|
+
}));
|
|
799
|
+
}
|
|
800
|
+
/**
|
|
801
|
+
* What time does to jobs: fails those that ran past their budget, reminds the recipient of a
|
|
802
|
+
* letter that got no reaction and fails the job when the reminder got none either, and tries
|
|
803
|
+
* the deliveries that are due again. The host calls it on a timer.
|
|
804
|
+
*/
|
|
805
|
+
async sweep() {
|
|
806
|
+
const result = await this.mutate(async (tx) => {
|
|
807
|
+
const now = this.now();
|
|
808
|
+
const failed = [];
|
|
809
|
+
const reminded = [];
|
|
810
|
+
const overdue = this.store
|
|
811
|
+
.jobTasks({ states: ACTIVE_JOB_STATES, deadlineBy: now })
|
|
812
|
+
.flatMap((task) => jobOf(task) ?? [])
|
|
813
|
+
.sort((a, b) => a.number - b.number);
|
|
814
|
+
for (const late of overdue) {
|
|
815
|
+
if (isFinishedJobState(this.requireJob(late.number).job.state))
|
|
816
|
+
continue;
|
|
817
|
+
await this.failJob(tx, late.number, ranOutOfTime(late));
|
|
818
|
+
failed.push(late.number);
|
|
819
|
+
}
|
|
820
|
+
for (const letter of this.store.listLetters({ replyDueBy: now })) {
|
|
821
|
+
const fresh = this.store.getLetter(letter.id);
|
|
822
|
+
if (!fresh?.replyDueAt)
|
|
823
|
+
continue;
|
|
824
|
+
const { job } = this.requireJob(letter.job);
|
|
825
|
+
if (isFinishedJobState(job.state) || fresh.state === 'handled') {
|
|
826
|
+
this.store.updateLetter(letter.id, { clear: ['replyDueAt'] });
|
|
827
|
+
continue;
|
|
828
|
+
}
|
|
829
|
+
const pickup = expectationOf(letter.kind) === 'pickup';
|
|
830
|
+
if (!fresh.remindedAt) {
|
|
831
|
+
this.store.updateLetter(letter.id, {
|
|
832
|
+
remindedAt: this.iso(now),
|
|
833
|
+
replyDueAt: this.iso(now + job.budget.replyTimeoutMs),
|
|
834
|
+
});
|
|
835
|
+
const quote = letter.body.length > REMINDER_QUOTE_LENGTH
|
|
836
|
+
? `${letter.body.slice(0, REMINDER_QUOTE_LENGTH)}...`
|
|
837
|
+
: letter.body;
|
|
838
|
+
this.systemNote(tx, job, letter.to, `Reminder: the ${letter.kind} ${letter.id} from ${letter.from} still waits for ${pickup ? 'you to take it' : 'your answer'}. ` +
|
|
839
|
+
`Without it job #${job.number} fails in ${formatDuration(job.budget.replyTimeoutMs)}. It says:\n${quoted(quote)}`);
|
|
840
|
+
this.journal(tx, {
|
|
841
|
+
type: 'letter.reminded',
|
|
842
|
+
job: job.number,
|
|
843
|
+
letter: letter.id,
|
|
844
|
+
agent: letter.to,
|
|
845
|
+
});
|
|
846
|
+
reminded.push(letter.id);
|
|
847
|
+
continue;
|
|
848
|
+
}
|
|
849
|
+
await this.failJob(tx, job.number, `${letter.to} did not ${pickup ? 'take' : 'answer'} the ${letter.kind} ${letter.id} in ${formatDuration(2 * job.budget.replyTimeoutMs)}`);
|
|
850
|
+
failed.push(job.number);
|
|
851
|
+
}
|
|
852
|
+
failed.push(...(await this.retireAgents(tx, now)));
|
|
853
|
+
for (const agent of this.store.queuedRecipients())
|
|
854
|
+
tx.wake.add(agent);
|
|
855
|
+
return { failed: [...new Set(failed)], reminded };
|
|
856
|
+
});
|
|
857
|
+
this.checkPresence();
|
|
858
|
+
return result;
|
|
859
|
+
}
|
|
860
|
+
/**
|
|
861
|
+
* Asks the adapters that can list their sessions which of them still run, once in
|
|
862
|
+
* `limits.presenceCheckMs`. A session that was listed and then is not, two times in a row, is
|
|
863
|
+
* gone, and its jobs fail with that reason rather than after the reply timeout: one miss may
|
|
864
|
+
* be a session between two states of its harness. A session with a waiter armed is there
|
|
865
|
+
* whatever the list says. One that was never listed (its harness shows it nowhere) is left to
|
|
866
|
+
* the idle rule, unless the adapter runs every session of its harness itself (`ownsSessions`):
|
|
867
|
+
* then what it does not list is gone at once. A session heard from after the list was asked
|
|
868
|
+
* for is not judged by it: it may have started meanwhile.
|
|
869
|
+
*/
|
|
870
|
+
checkPresence() {
|
|
871
|
+
if (this.closing)
|
|
872
|
+
return;
|
|
873
|
+
const now = this.now();
|
|
874
|
+
if (now - this.presenceCheckedAt < this.limits.presenceCheckMs)
|
|
875
|
+
return;
|
|
876
|
+
this.presenceCheckedAt = now;
|
|
877
|
+
for (const [harness, adapter] of this.adapters) {
|
|
878
|
+
if (!adapter.liveSessions || this.listing.has(harness))
|
|
879
|
+
continue;
|
|
880
|
+
this.listing.add(harness);
|
|
881
|
+
const asked = now;
|
|
882
|
+
this.track(within(adapter.liveSessions(), this.limits.deliveryTimeoutMs, `Listing the ${harness} sessions`)
|
|
883
|
+
.then((sessions) => this.mutate((tx) => this.applyPresence(tx, harness, new Set(sessions.map((session) => session.sessionId)), adapter.ownsSessions === true, asked)))
|
|
884
|
+
.finally(() => this.listing.delete(harness)));
|
|
885
|
+
}
|
|
886
|
+
}
|
|
887
|
+
async applyPresence(tx, harness, live, certain, asked) {
|
|
888
|
+
const known = this.presence.get(harness) ?? { live, seen: new Set(), missed: new Set() };
|
|
889
|
+
const missed = new Set();
|
|
890
|
+
for (const sessionId of live)
|
|
891
|
+
known.seen.add(sessionId);
|
|
892
|
+
for (const agent of this.store.listAgents({ harness, statuses: ['active'] })) {
|
|
893
|
+
const id = agent.sessionId;
|
|
894
|
+
if (live.has(id) || this.waiters.has(agent.name) || this.starting.has(agent.name))
|
|
895
|
+
continue;
|
|
896
|
+
if (Date.parse(agent.lastSeenAt) >= asked)
|
|
897
|
+
continue;
|
|
898
|
+
if (!certain && !known.seen.has(id))
|
|
899
|
+
continue;
|
|
900
|
+
if (!certain && !known.missed.has(id)) {
|
|
901
|
+
missed.add(id);
|
|
902
|
+
continue;
|
|
903
|
+
}
|
|
904
|
+
known.seen.delete(id);
|
|
905
|
+
await this.agentGone(tx, agent, `the session of ${agent.name} is not running any more`);
|
|
906
|
+
}
|
|
907
|
+
this.presence.set(harness, { live, seen: known.seen, missed });
|
|
908
|
+
}
|
|
909
|
+
/**
|
|
910
|
+
* Takes sessions that are not there out of the address book, so a harness word keeps reaching
|
|
911
|
+
* the session that is: one whose start never finished (the dispatcher that started it is
|
|
912
|
+
* gone) fails its jobs, one that has been silent for `limits.agentIdleMs` and has no job in
|
|
913
|
+
* progress just leaves. Returns the jobs it failed.
|
|
914
|
+
*/
|
|
915
|
+
async retireAgents(tx, now) {
|
|
916
|
+
const failed = [];
|
|
917
|
+
for (const agent of this.store.listAgents({ statuses: ['starting'] })) {
|
|
918
|
+
if (this.starting.has(agent.name))
|
|
919
|
+
continue;
|
|
920
|
+
failed.push(...(await this.agentGone(tx, agent, `the session of ${agent.name} never started: the dispatcher stopped while starting it`)));
|
|
921
|
+
}
|
|
922
|
+
const silent = this.store.listAgents({
|
|
923
|
+
statuses: ['active'],
|
|
924
|
+
seenBefore: now - this.limits.agentIdleMs,
|
|
925
|
+
});
|
|
926
|
+
for (const agent of silent) {
|
|
927
|
+
if (this.waiters.has(agent.name))
|
|
928
|
+
continue;
|
|
929
|
+
if (this.presence.get(agent.harness)?.live.has(agent.sessionId))
|
|
930
|
+
continue;
|
|
931
|
+
const busy = this.store.jobTasks({ party: agent.name, states: ACTIVE_JOB_STATES, limit: 1 });
|
|
932
|
+
if (busy.length > 0)
|
|
933
|
+
continue;
|
|
934
|
+
this.store.putAgent({ ...agent, status: 'gone' });
|
|
935
|
+
this.journal(tx, {
|
|
936
|
+
type: 'agent.gone',
|
|
937
|
+
agent: agent.name,
|
|
938
|
+
data: { reason: 'idle', lastSeenAt: agent.lastSeenAt },
|
|
939
|
+
});
|
|
940
|
+
}
|
|
941
|
+
return failed;
|
|
942
|
+
}
|
|
943
|
+
/** Marks an agent gone and fails every job it was to carry out. Returns those jobs. */
|
|
944
|
+
async agentGone(tx, agent, reason) {
|
|
945
|
+
this.store.putAgent({ ...agent, status: 'gone' });
|
|
946
|
+
this.journal(tx, { type: 'agent.gone', agent: agent.name, data: { error: reason } });
|
|
947
|
+
const failed = [];
|
|
948
|
+
for (const task of this.store.jobTasks({ to: agent.name, states: ACTIVE_JOB_STATES })) {
|
|
949
|
+
const job = jobOf(task);
|
|
950
|
+
if (!job)
|
|
951
|
+
continue;
|
|
952
|
+
await this.failJob(tx, job.number, reason);
|
|
953
|
+
failed.push(job.number);
|
|
954
|
+
}
|
|
955
|
+
return failed;
|
|
956
|
+
}
|
|
957
|
+
/** Resolves once every call made so far is handled and every delivery it started has ended. */
|
|
958
|
+
async idle() {
|
|
959
|
+
for (;;) {
|
|
960
|
+
await this.queue;
|
|
961
|
+
const running = [...this.deliveries.values(), ...this.background];
|
|
962
|
+
if (running.length === 0)
|
|
963
|
+
return;
|
|
964
|
+
await Promise.allSettled(running);
|
|
965
|
+
}
|
|
966
|
+
}
|
|
967
|
+
/**
|
|
968
|
+
* Ends the waits, waits for the calls being handled, the deliveries and the session starts they
|
|
969
|
+
* began, closes the adapters, then takes no more. A session a call asks for after this began
|
|
970
|
+
* is not started: the next dispatcher finds it never started and fails its job. A delivery that hangs is given up on after `limits.deliveryTimeoutMs` and a
|
|
971
|
+
* session start after `limits.sessionStartTimeoutMs`, so this always ends.
|
|
972
|
+
*/
|
|
973
|
+
async close() {
|
|
974
|
+
this.closing = true;
|
|
975
|
+
for (const waiter of [...this.waiters.values()])
|
|
976
|
+
waiter.end('closed');
|
|
977
|
+
await this.idle();
|
|
978
|
+
await Promise.all([...this.adapters.values()].map(async (adapter) => {
|
|
979
|
+
try {
|
|
980
|
+
await adapter.close?.();
|
|
981
|
+
}
|
|
982
|
+
catch (error) {
|
|
983
|
+
this.onError(asError(error));
|
|
984
|
+
}
|
|
985
|
+
}));
|
|
986
|
+
this.closed = true;
|
|
987
|
+
}
|
|
988
|
+
iso(ms = this.now()) {
|
|
989
|
+
return new Date(ms).toISOString();
|
|
990
|
+
}
|
|
991
|
+
checkBody(body) {
|
|
992
|
+
if (body.length > this.limits.maxBodyLength) {
|
|
993
|
+
throw new BridgeError('invalid_input', `The letter is ${body.length} characters long, the limit is ${this.limits.maxBodyLength}. Put the details in a file and name it`);
|
|
994
|
+
}
|
|
995
|
+
}
|
|
996
|
+
async enqueue(work) {
|
|
997
|
+
if (this.closed)
|
|
998
|
+
throw new BridgeError('not_running', 'The bridge dispatcher is closed');
|
|
999
|
+
const run = this.queue.then(work, work);
|
|
1000
|
+
this.queue = run.catch(() => undefined);
|
|
1001
|
+
return run;
|
|
1002
|
+
}
|
|
1003
|
+
mutate(work) {
|
|
1004
|
+
return this.enqueue(() => this.transact(work));
|
|
1005
|
+
}
|
|
1006
|
+
/**
|
|
1007
|
+
* A call made as an agent, as one entry of the queue: first the sign of life is stored, on its
|
|
1008
|
+
* own, so a call the bridge then refuses still counts, then the call itself.
|
|
1009
|
+
*/
|
|
1010
|
+
asCaller(caller, work) {
|
|
1011
|
+
return this.enqueue(async () => {
|
|
1012
|
+
await this.transact(async (tx) => this.heardFrom(tx, caller));
|
|
1013
|
+
return this.transact(work);
|
|
1014
|
+
});
|
|
1015
|
+
}
|
|
1016
|
+
async transact(work) {
|
|
1017
|
+
const tx = { entries: [], wake: new Set(), spawns: [] };
|
|
1018
|
+
const result = await this.store.transaction(() => {
|
|
1019
|
+
this.assertWritable?.();
|
|
1020
|
+
return work(tx);
|
|
1021
|
+
});
|
|
1022
|
+
for (const entry of tx.entries) {
|
|
1023
|
+
try {
|
|
1024
|
+
this.emit('journal', entry);
|
|
1025
|
+
}
|
|
1026
|
+
catch (error) {
|
|
1027
|
+
this.onError(asError(error));
|
|
1028
|
+
}
|
|
1029
|
+
}
|
|
1030
|
+
if (!this.closing) {
|
|
1031
|
+
for (const spawn of tx.spawns)
|
|
1032
|
+
this.startSession(spawn.agent, spawn.job, spawn.letter);
|
|
1033
|
+
}
|
|
1034
|
+
for (const agent of tx.wake)
|
|
1035
|
+
this.wake(agent);
|
|
1036
|
+
return result;
|
|
1037
|
+
}
|
|
1038
|
+
journal(tx, entry) {
|
|
1039
|
+
tx.entries.push(this.store.appendJournal({ at: this.iso(), ...entry }));
|
|
1040
|
+
}
|
|
1041
|
+
/**
|
|
1042
|
+
* Notes that a session called: the time, and that a session the bridge took for gone is
|
|
1043
|
+
* there again.
|
|
1044
|
+
*/
|
|
1045
|
+
heardFrom(tx, name) {
|
|
1046
|
+
const known = this.store.getAgent(name);
|
|
1047
|
+
if (!known || known.status === 'starting' || known.sessionId === '')
|
|
1048
|
+
return;
|
|
1049
|
+
this.store.putAgent({ ...known, status: 'active', lastSeenAt: this.iso() });
|
|
1050
|
+
if (known.status !== 'gone')
|
|
1051
|
+
return;
|
|
1052
|
+
this.journal(tx, {
|
|
1053
|
+
type: 'agent.registered',
|
|
1054
|
+
agent: name,
|
|
1055
|
+
data: { harness: known.harness, returned: true },
|
|
1056
|
+
});
|
|
1057
|
+
tx.wake.add(name);
|
|
1058
|
+
}
|
|
1059
|
+
requireCaller(name) {
|
|
1060
|
+
const agent = this.store.getAgent(name);
|
|
1061
|
+
if (agent?.status !== 'active') {
|
|
1062
|
+
throw new BridgeError('not_registered', `${name} is not a session the bridge knows. Register the session first`, { agent: name });
|
|
1063
|
+
}
|
|
1064
|
+
return agent;
|
|
1065
|
+
}
|
|
1066
|
+
requireJob(number) {
|
|
1067
|
+
const task = this.store.taskOfJob(number);
|
|
1068
|
+
const job = task && jobOf(task);
|
|
1069
|
+
if (!task || !job)
|
|
1070
|
+
throw new BridgeError('unknown_job', `There is no job ${number}`, { job: number });
|
|
1071
|
+
return { task, job };
|
|
1072
|
+
}
|
|
1073
|
+
jobFrom(task) {
|
|
1074
|
+
const job = jobOf(task);
|
|
1075
|
+
if (!job)
|
|
1076
|
+
throw new BridgeError('storage', `Task ${task.id} lost its job record`);
|
|
1077
|
+
return job;
|
|
1078
|
+
}
|
|
1079
|
+
async patchRecord(taskId, patch) {
|
|
1080
|
+
const task = await this.store.tasks.get(taskId);
|
|
1081
|
+
const record = task && jobRecordOf(task);
|
|
1082
|
+
if (!task || !record)
|
|
1083
|
+
throw new BridgeError('storage', `Task ${taskId} lost its job record`);
|
|
1084
|
+
await this.store.tasks.update(taskId, {
|
|
1085
|
+
metadata: { ...task.metadata, [BRIDGE_JOB_KEY]: { ...record, ...patch } },
|
|
1086
|
+
});
|
|
1087
|
+
}
|
|
1088
|
+
async transition(tx, number, to, message) {
|
|
1089
|
+
const { job } = this.requireJob(number);
|
|
1090
|
+
if (job.state === to && to !== 'input-required')
|
|
1091
|
+
return;
|
|
1092
|
+
if (to === 'canceled') {
|
|
1093
|
+
await this.tasks.cancelTask(job.taskId);
|
|
1094
|
+
}
|
|
1095
|
+
else if (to === 'working' && job.state === 'input-required') {
|
|
1096
|
+
await this.tasks.continueTask(job.taskId, userMessage(message ?? ''));
|
|
1097
|
+
}
|
|
1098
|
+
else if (to === 'submitted') {
|
|
1099
|
+
throw new BridgeError('storage', `Job ${number} cannot go back to submitted`);
|
|
1100
|
+
}
|
|
1101
|
+
else {
|
|
1102
|
+
await this.tasks.advanceTask(job.taskId, {
|
|
1103
|
+
state: to,
|
|
1104
|
+
...(message !== undefined && to !== 'working' && { message }),
|
|
1105
|
+
});
|
|
1106
|
+
}
|
|
1107
|
+
if (job.state !== to) {
|
|
1108
|
+
this.journal(tx, { type: 'job.state', job: number, data: { from: job.state, to } });
|
|
1109
|
+
}
|
|
1110
|
+
}
|
|
1111
|
+
async pickUp(tx, job) {
|
|
1112
|
+
await this.transition(tx, job.number, 'working');
|
|
1113
|
+
for (const task of this.store.listLetters({ job: job.number, to: job.to, kinds: ['task'] })) {
|
|
1114
|
+
if (UNREAD_STATES.includes(task.state))
|
|
1115
|
+
this.markRead(tx, task);
|
|
1116
|
+
else if (task.replyDueAt)
|
|
1117
|
+
this.store.updateLetter(task.id, { clear: ['replyDueAt'] });
|
|
1118
|
+
}
|
|
1119
|
+
}
|
|
1120
|
+
async failJob(tx, number, reason) {
|
|
1121
|
+
const { job } = this.requireJob(number);
|
|
1122
|
+
if (isFinishedJobState(job.state))
|
|
1123
|
+
return;
|
|
1124
|
+
await this.transition(tx, number, 'failed', reason);
|
|
1125
|
+
await this.patchRecord(job.taskId, { reason });
|
|
1126
|
+
this.closeLetters(tx, number);
|
|
1127
|
+
const text = `Job #${number} has failed: ${reason}.`;
|
|
1128
|
+
this.systemNote(tx, job, job.from, text);
|
|
1129
|
+
this.systemNote(tx, job, job.to, `${text} Stop working on it.`);
|
|
1130
|
+
await this.cancelChildren(tx, job);
|
|
1131
|
+
}
|
|
1132
|
+
async cancelJob(tx, number, reason, note) {
|
|
1133
|
+
const { job } = this.requireJob(number);
|
|
1134
|
+
if (isFinishedJobState(job.state))
|
|
1135
|
+
return;
|
|
1136
|
+
await this.transition(tx, number, 'canceled', reason);
|
|
1137
|
+
await this.patchRecord(job.taskId, { reason });
|
|
1138
|
+
this.closeLetters(tx, number);
|
|
1139
|
+
this.systemNote(tx, job, job.to, note);
|
|
1140
|
+
await this.cancelChildren(tx, job);
|
|
1141
|
+
}
|
|
1142
|
+
/** A job that is over takes the jobs handed over from inside it with it: nobody waits for them. */
|
|
1143
|
+
async cancelChildren(tx, parent) {
|
|
1144
|
+
const children = this.store.jobTasks({ parent: parent.number, states: ACTIVE_JOB_STATES });
|
|
1145
|
+
for (const task of children) {
|
|
1146
|
+
const child = jobOf(task);
|
|
1147
|
+
if (!child)
|
|
1148
|
+
continue;
|
|
1149
|
+
const reason = `job #${parent.number}, which it was part of, is over`;
|
|
1150
|
+
await this.cancelJob(tx, child.number, reason, `Job #${child.number} was canceled: ${reason}. Stop working on it.`);
|
|
1151
|
+
this.systemNote(tx, child, child.from, `Job #${child.number} was canceled: ${reason}.`);
|
|
1152
|
+
}
|
|
1153
|
+
}
|
|
1154
|
+
/**
|
|
1155
|
+
* Why an agent may not hand this job over right now, if it may not: it is the job it already
|
|
1156
|
+
* handed to the same agent and that is still in progress, it has too many jobs out, it hands
|
|
1157
|
+
* jobs over too fast, or too many sessions are being started.
|
|
1158
|
+
*/
|
|
1159
|
+
handOverRefusal(from, resolution, body, cwd, now) {
|
|
1160
|
+
const open = this.store
|
|
1161
|
+
.jobTasks({ from: from.name, states: ACTIVE_JOB_STATES })
|
|
1162
|
+
.flatMap((task) => jobOf(task) ?? []);
|
|
1163
|
+
const wanted = normalizeBody(body);
|
|
1164
|
+
const sameAgent = (job) => resolution.kind === 'agent'
|
|
1165
|
+
? job.to === resolution.agent.name
|
|
1166
|
+
: this.store.getAgent(job.to)?.harness === resolution.harness;
|
|
1167
|
+
const same = open.find((job) => {
|
|
1168
|
+
if (job.cwd !== cwd || !sameAgent(job))
|
|
1169
|
+
return false;
|
|
1170
|
+
const first = this.store.listLetters({ job: job.number, kinds: ['task'], limit: 1 })[0];
|
|
1171
|
+
return first !== undefined && normalizeBody(first.body) === wanted;
|
|
1172
|
+
});
|
|
1173
|
+
if (same) {
|
|
1174
|
+
return new BridgeError('loop_detected', `You already handed this job to ${same.to} as job #${same.number}, and it is still ${same.state}. Wait for its report, or cancel it first`, { job: same.number });
|
|
1175
|
+
}
|
|
1176
|
+
if (open.length >= this.limits.maxOpenJobs) {
|
|
1177
|
+
return new BridgeError('budget_exhausted', `You have ${open.length} jobs out that are still in progress, the most there may be. Wait for their reports or cancel some`, { open: open.length, max: this.limits.maxOpenJobs });
|
|
1178
|
+
}
|
|
1179
|
+
const recent = this.store.jobTasks({ from: from.name, createdSince: now - 3_600_000 }).length;
|
|
1180
|
+
if (recent >= this.limits.jobsPerHour) {
|
|
1181
|
+
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 });
|
|
1182
|
+
}
|
|
1183
|
+
if (resolution.kind === 'spawn') {
|
|
1184
|
+
const starting = this.store.listAgents({ statuses: ['starting'] }).length;
|
|
1185
|
+
if (starting >= this.limits.maxStartingSessions) {
|
|
1186
|
+
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 });
|
|
1187
|
+
}
|
|
1188
|
+
}
|
|
1189
|
+
return undefined;
|
|
1190
|
+
}
|
|
1191
|
+
/**
|
|
1192
|
+
* A finished job waits for nothing: its own letter and the questions nobody answered are done
|
|
1193
|
+
* with, and no letter of it is due any more.
|
|
1194
|
+
*/
|
|
1195
|
+
closeLetters(tx, number, except) {
|
|
1196
|
+
for (const letter of this.store.listLetters({ job: number })) {
|
|
1197
|
+
if (letter.id === except)
|
|
1198
|
+
continue;
|
|
1199
|
+
if (expectationOf(letter.kind) !== 'none' && letter.state !== 'handled') {
|
|
1200
|
+
this.markHandled(tx, letter);
|
|
1201
|
+
}
|
|
1202
|
+
else if (letter.replyDueAt) {
|
|
1203
|
+
this.store.updateLetter(letter.id, { clear: ['replyDueAt'] });
|
|
1204
|
+
}
|
|
1205
|
+
}
|
|
1206
|
+
}
|
|
1207
|
+
accept(tx, fields) {
|
|
1208
|
+
const letter = this.store.insertLetter({
|
|
1209
|
+
...fields,
|
|
1210
|
+
state: 'queued',
|
|
1211
|
+
createdAt: this.iso(),
|
|
1212
|
+
attempts: 0,
|
|
1213
|
+
});
|
|
1214
|
+
this.journal(tx, {
|
|
1215
|
+
type: 'letter.queued',
|
|
1216
|
+
job: letter.job,
|
|
1217
|
+
letter: letter.id,
|
|
1218
|
+
agent: letter.from,
|
|
1219
|
+
data: {
|
|
1220
|
+
kind: letter.kind,
|
|
1221
|
+
from: letter.from,
|
|
1222
|
+
to: letter.to,
|
|
1223
|
+
body: letter.body,
|
|
1224
|
+
...(letter.inReplyTo && { inReplyTo: letter.inReplyTo }),
|
|
1225
|
+
...(letter.outcome && { outcome: letter.outcome }),
|
|
1226
|
+
},
|
|
1227
|
+
});
|
|
1228
|
+
tx.wake.add(letter.to);
|
|
1229
|
+
return letter;
|
|
1230
|
+
}
|
|
1231
|
+
/** A letter the bridge writes itself. It costs the job nothing and is never held back as a repeat. */
|
|
1232
|
+
systemNote(tx, job, to, body) {
|
|
1233
|
+
return this.accept(tx, {
|
|
1234
|
+
id: this.letterId(),
|
|
1235
|
+
job: job.number,
|
|
1236
|
+
kind: 'note',
|
|
1237
|
+
from: BRIDGE_SENDER,
|
|
1238
|
+
to,
|
|
1239
|
+
body,
|
|
1240
|
+
});
|
|
1241
|
+
}
|
|
1242
|
+
answeredLetter(request, job, caller) {
|
|
1243
|
+
if (request.inReplyTo) {
|
|
1244
|
+
const target = this.store.getLetter(request.inReplyTo);
|
|
1245
|
+
if (target?.job !== job.number) {
|
|
1246
|
+
throw new BridgeError('invalid_letter', `Job ${job.number} has no letter ${request.inReplyTo} to reply to`, {
|
|
1247
|
+
letter: request.inReplyTo,
|
|
1248
|
+
});
|
|
1249
|
+
}
|
|
1250
|
+
if (request.kind !== 'answer')
|
|
1251
|
+
return target;
|
|
1252
|
+
if (target.to !== caller || !NEEDS_ANSWER.includes(target.kind)) {
|
|
1253
|
+
throw new BridgeError('invalid_letter', `The letter ${target.id} is not a question to you, so it takes no answer`, {
|
|
1254
|
+
letter: target.id,
|
|
1255
|
+
});
|
|
1256
|
+
}
|
|
1257
|
+
if (target.state === 'handled') {
|
|
1258
|
+
throw new BridgeError('invalid_letter', `The ${target.kind} ${target.id} is already answered`, {
|
|
1259
|
+
letter: target.id,
|
|
1260
|
+
});
|
|
1261
|
+
}
|
|
1262
|
+
return target;
|
|
1263
|
+
}
|
|
1264
|
+
if (request.kind !== 'answer')
|
|
1265
|
+
return undefined;
|
|
1266
|
+
const open = this.store.listLetters({
|
|
1267
|
+
job: job.number,
|
|
1268
|
+
to: caller,
|
|
1269
|
+
kinds: NEEDS_ANSWER,
|
|
1270
|
+
states: ['queued', 'delivered', 'read'],
|
|
1271
|
+
});
|
|
1272
|
+
if (open.length === 1)
|
|
1273
|
+
return open[0];
|
|
1274
|
+
if (open.length === 0) {
|
|
1275
|
+
throw new BridgeError('invalid_letter', `Nothing on job ${job.number} waits for your answer. Send a note instead`, {
|
|
1276
|
+
job: job.number,
|
|
1277
|
+
});
|
|
1278
|
+
}
|
|
1279
|
+
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) });
|
|
1280
|
+
}
|
|
1281
|
+
markRead(tx, letter) {
|
|
1282
|
+
if (STATE_RANK[letter.state] >= STATE_RANK.read)
|
|
1283
|
+
return letter;
|
|
1284
|
+
const updated = this.store.updateLetter(letter.id, {
|
|
1285
|
+
state: 'read',
|
|
1286
|
+
readAt: this.iso(),
|
|
1287
|
+
clear: expectationOf(letter.kind) === 'pickup'
|
|
1288
|
+
? ['nextAttemptAt', 'replyDueAt']
|
|
1289
|
+
: ['nextAttemptAt'],
|
|
1290
|
+
});
|
|
1291
|
+
this.journal(tx, { type: 'letter.read', job: letter.job, letter: letter.id, agent: letter.to });
|
|
1292
|
+
return updated;
|
|
1293
|
+
}
|
|
1294
|
+
markHandled(tx, letter) {
|
|
1295
|
+
if (letter.state === 'handled')
|
|
1296
|
+
return letter;
|
|
1297
|
+
const now = this.iso();
|
|
1298
|
+
const updated = this.store.updateLetter(letter.id, {
|
|
1299
|
+
state: 'handled',
|
|
1300
|
+
handledAt: now,
|
|
1301
|
+
...(letter.readAt === undefined && { readAt: now }),
|
|
1302
|
+
clear: ['nextAttemptAt', 'replyDueAt'],
|
|
1303
|
+
});
|
|
1304
|
+
this.journal(tx, {
|
|
1305
|
+
type: 'letter.handled',
|
|
1306
|
+
job: letter.job,
|
|
1307
|
+
letter: letter.id,
|
|
1308
|
+
agent: letter.to,
|
|
1309
|
+
});
|
|
1310
|
+
return updated;
|
|
1311
|
+
}
|
|
1312
|
+
/**
|
|
1313
|
+
* Records that an adapter handed a letter to its session. A job handed over this way counts as
|
|
1314
|
+
* taken: the harness has it and woke the session, which may work without calling the bridge
|
|
1315
|
+
* until it reports. The letter is read only once the session calls about the job.
|
|
1316
|
+
*/
|
|
1317
|
+
async markDelivered(tx, letterId, data) {
|
|
1318
|
+
this.inHand.delete(letterId);
|
|
1319
|
+
const letter = this.store.getLetter(letterId);
|
|
1320
|
+
if (letter?.state !== 'queued')
|
|
1321
|
+
return;
|
|
1322
|
+
const taken = expectationOf(letter.kind) === 'pickup';
|
|
1323
|
+
this.store.updateLetter(letterId, {
|
|
1324
|
+
state: 'delivered',
|
|
1325
|
+
deliveredAt: this.iso(),
|
|
1326
|
+
clear: taken ? ['nextAttemptAt', 'lastError', 'replyDueAt'] : ['nextAttemptAt', 'lastError'],
|
|
1327
|
+
});
|
|
1328
|
+
this.journal(tx, {
|
|
1329
|
+
type: 'letter.delivered',
|
|
1330
|
+
job: letter.job,
|
|
1331
|
+
letter: letter.id,
|
|
1332
|
+
agent: letter.to,
|
|
1333
|
+
...(data && { data }),
|
|
1334
|
+
});
|
|
1335
|
+
if (taken && this.requireJob(letter.job).job.state === 'submitted') {
|
|
1336
|
+
await this.transition(tx, letter.job, 'working');
|
|
1337
|
+
}
|
|
1338
|
+
}
|
|
1339
|
+
track(work) {
|
|
1340
|
+
const tracked = work
|
|
1341
|
+
.catch((error) => this.onError(asError(error)))
|
|
1342
|
+
.finally(() => this.background.delete(tracked));
|
|
1343
|
+
this.background.add(tracked);
|
|
1344
|
+
}
|
|
1345
|
+
/** Delivers what waits for an agent, one letter after another, in the order they were accepted. */
|
|
1346
|
+
wake(agent) {
|
|
1347
|
+
const previous = this.deliveries.get(agent) ?? Promise.resolve();
|
|
1348
|
+
const next = previous
|
|
1349
|
+
.then(() => this.deliverTo(agent))
|
|
1350
|
+
.catch((error) => this.onError(asError(error)))
|
|
1351
|
+
.finally(() => {
|
|
1352
|
+
if (this.deliveries.get(agent) === next)
|
|
1353
|
+
this.deliveries.delete(agent);
|
|
1354
|
+
});
|
|
1355
|
+
this.deliveries.set(agent, next);
|
|
1356
|
+
}
|
|
1357
|
+
async deliverTo(name) {
|
|
1358
|
+
for (;;) {
|
|
1359
|
+
if (this.closing)
|
|
1360
|
+
return;
|
|
1361
|
+
const next = await this.enqueue(async () => {
|
|
1362
|
+
if (this.starting.has(name))
|
|
1363
|
+
return undefined;
|
|
1364
|
+
const agent = this.store.getAgent(name);
|
|
1365
|
+
if (agent?.status !== 'active')
|
|
1366
|
+
return undefined;
|
|
1367
|
+
const waiter = this.waiters.get(name);
|
|
1368
|
+
if (waiter) {
|
|
1369
|
+
const letters = this.queuedFor(name, waiter.limit);
|
|
1370
|
+
if (letters.length > 0) {
|
|
1371
|
+
this.hand(name, letters, waiter.signal);
|
|
1372
|
+
waiter.end('letters', letters);
|
|
1373
|
+
}
|
|
1374
|
+
return undefined;
|
|
1375
|
+
}
|
|
1376
|
+
const adapter = this.adapters.get(agent.harness);
|
|
1377
|
+
const deliver = adapter?.capabilities.push ? adapter.deliver?.bind(adapter) : undefined;
|
|
1378
|
+
if (!deliver)
|
|
1379
|
+
return undefined;
|
|
1380
|
+
const letter = this.store.listLetters({
|
|
1381
|
+
to: name,
|
|
1382
|
+
states: ['queued'],
|
|
1383
|
+
attemptsBelow: this.limits.deliveryAttempts,
|
|
1384
|
+
limit: 1,
|
|
1385
|
+
})[0];
|
|
1386
|
+
if (!letter || this.held(letter.id))
|
|
1387
|
+
return undefined;
|
|
1388
|
+
if (letter.nextAttemptAt && Date.parse(letter.nextAttemptAt) > this.now())
|
|
1389
|
+
return undefined;
|
|
1390
|
+
const { job } = this.requireJob(letter.job);
|
|
1391
|
+
this.inHand.set(letter.id, {
|
|
1392
|
+
agent: name,
|
|
1393
|
+
until: this.now() + this.limits.deliveryTimeoutMs,
|
|
1394
|
+
pushing: true,
|
|
1395
|
+
});
|
|
1396
|
+
return { agent, deliver, job, letter: renderLetter(letter, job) };
|
|
1397
|
+
});
|
|
1398
|
+
if (!next)
|
|
1399
|
+
return;
|
|
1400
|
+
let note;
|
|
1401
|
+
try {
|
|
1402
|
+
const receipt = await within(next.deliver({ agent: next.agent, letter: next.letter, job: next.job }), this.limits.deliveryTimeoutMs, `Delivering the letter ${next.letter.id} to ${name}`);
|
|
1403
|
+
note = receipt?.note;
|
|
1404
|
+
}
|
|
1405
|
+
catch (error) {
|
|
1406
|
+
this.inHand.delete(next.letter.id);
|
|
1407
|
+
await this.mutate(async (tx) => this.deliveryFailed(tx, next.letter.id, asError(error)));
|
|
1408
|
+
return;
|
|
1409
|
+
}
|
|
1410
|
+
this.inHand.delete(next.letter.id);
|
|
1411
|
+
await this.mutate((tx) => this.markDelivered(tx, next.letter.id, note ? { note } : undefined));
|
|
1412
|
+
}
|
|
1413
|
+
}
|
|
1414
|
+
deliveryFailed(tx, letterId, error) {
|
|
1415
|
+
const letter = this.store.getLetter(letterId);
|
|
1416
|
+
if (letter?.state !== 'queued')
|
|
1417
|
+
return;
|
|
1418
|
+
const attempts = letter.attempts + 1;
|
|
1419
|
+
if (attempts >= this.limits.deliveryAttempts) {
|
|
1420
|
+
this.store.updateLetter(letterId, {
|
|
1421
|
+
attempts,
|
|
1422
|
+
lastError: error.message,
|
|
1423
|
+
clear: ['nextAttemptAt'],
|
|
1424
|
+
});
|
|
1425
|
+
this.journal(tx, {
|
|
1426
|
+
type: 'letter.undelivered',
|
|
1427
|
+
job: letter.job,
|
|
1428
|
+
letter: letter.id,
|
|
1429
|
+
agent: letter.to,
|
|
1430
|
+
data: { attempts, error: error.message },
|
|
1431
|
+
});
|
|
1432
|
+
return;
|
|
1433
|
+
}
|
|
1434
|
+
this.store.updateLetter(letterId, {
|
|
1435
|
+
attempts,
|
|
1436
|
+
lastError: error.message,
|
|
1437
|
+
nextAttemptAt: this.iso(this.now() + deliveryBackoff(attempts, this.limits)),
|
|
1438
|
+
});
|
|
1439
|
+
}
|
|
1440
|
+
startSession(agentName, jobNumber, letterId) {
|
|
1441
|
+
this.starting.add(agentName);
|
|
1442
|
+
this.track(this.runSessionStart(agentName, jobNumber, letterId).finally(() => {
|
|
1443
|
+
if (this.starting.delete(agentName))
|
|
1444
|
+
this.wakeIfKnown(agentName);
|
|
1445
|
+
}));
|
|
1446
|
+
}
|
|
1447
|
+
wakeIfKnown(agentName) {
|
|
1448
|
+
if (this.closing)
|
|
1449
|
+
return;
|
|
1450
|
+
this.track(this.enqueue(async () => {
|
|
1451
|
+
if (this.store.getAgent(agentName)?.status === 'active')
|
|
1452
|
+
this.wake(agentName);
|
|
1453
|
+
}));
|
|
1454
|
+
}
|
|
1455
|
+
async runSessionStart(agentName, jobNumber, letterId) {
|
|
1456
|
+
const request = await this.enqueue(async () => {
|
|
1457
|
+
const agent = this.store.getAgent(agentName);
|
|
1458
|
+
const letter = this.store.getLetter(letterId);
|
|
1459
|
+
if (!agent || !letter)
|
|
1460
|
+
return undefined;
|
|
1461
|
+
const { job } = this.requireJob(jobNumber);
|
|
1462
|
+
return { agent, job, letter: renderLetter(letter, job) };
|
|
1463
|
+
});
|
|
1464
|
+
const adapter = request && this.adapters.get(request.agent.harness);
|
|
1465
|
+
if (!request || !adapter?.createSession)
|
|
1466
|
+
return;
|
|
1467
|
+
let created;
|
|
1468
|
+
try {
|
|
1469
|
+
created = await within(adapter.createSession({
|
|
1470
|
+
agentName,
|
|
1471
|
+
harness: request.agent.harness,
|
|
1472
|
+
project: request.agent.project,
|
|
1473
|
+
cwd: request.agent.cwd,
|
|
1474
|
+
...(request.agent.sessionName && { sessionName: request.agent.sessionName }),
|
|
1475
|
+
job: request.job,
|
|
1476
|
+
firstLetter: request.letter,
|
|
1477
|
+
}), this.limits.sessionStartTimeoutMs, `Starting a ${request.agent.harness} session`);
|
|
1478
|
+
if (!created.sessionId.trim())
|
|
1479
|
+
throw new Error('the adapter returned no session id');
|
|
1480
|
+
}
|
|
1481
|
+
catch (error) {
|
|
1482
|
+
const message = asError(error).message;
|
|
1483
|
+
await this.mutate(async (tx) => {
|
|
1484
|
+
const agent = this.store.getAgent(agentName);
|
|
1485
|
+
if (agent?.status !== 'starting')
|
|
1486
|
+
return;
|
|
1487
|
+
await this.agentGone(tx, agent, `the bridge could not start a ${request.agent.harness} session: ${message}`);
|
|
1488
|
+
});
|
|
1489
|
+
return;
|
|
1490
|
+
}
|
|
1491
|
+
await this.mutate(async (tx) => {
|
|
1492
|
+
const agent = this.store.getAgent(agentName);
|
|
1493
|
+
if (!agent)
|
|
1494
|
+
return;
|
|
1495
|
+
const other = this.store.agentOfSession(agent.harness, created.sessionId);
|
|
1496
|
+
let name = agentName;
|
|
1497
|
+
if (other && other.name !== agentName) {
|
|
1498
|
+
this.store.mergeAgent(agentName, other.name);
|
|
1499
|
+
name = other.name;
|
|
1500
|
+
}
|
|
1501
|
+
else {
|
|
1502
|
+
this.store.putAgent({
|
|
1503
|
+
...agent,
|
|
1504
|
+
sessionId: created.sessionId,
|
|
1505
|
+
...(created.sessionName && { sessionName: created.sessionName }),
|
|
1506
|
+
status: 'active',
|
|
1507
|
+
lastSeenAt: this.iso(),
|
|
1508
|
+
});
|
|
1509
|
+
if (agent.status === 'starting') {
|
|
1510
|
+
this.journal(tx, {
|
|
1511
|
+
type: 'agent.registered',
|
|
1512
|
+
agent: name,
|
|
1513
|
+
data: { harness: agent.harness, started: true },
|
|
1514
|
+
});
|
|
1515
|
+
}
|
|
1516
|
+
}
|
|
1517
|
+
if (created.deliveredFirstLetter)
|
|
1518
|
+
await this.markDelivered(tx, letterId);
|
|
1519
|
+
if (name !== agentName)
|
|
1520
|
+
tx.wake.add(name);
|
|
1521
|
+
});
|
|
1522
|
+
}
|
|
1523
|
+
}
|
|
1524
|
+
//# sourceMappingURL=dispatcher.js.map
|