@cotal-ai/connector-core 0.154.0 → 0.155.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/dist/agent.d.ts +91 -3
- package/dist/agent.d.ts.map +1 -1
- package/dist/agent.js +333 -35
- package/dist/agent.js.map +1 -1
- package/dist/docs-bundle.bin +0 -0
- package/dist/docs-bundle.generated.d.ts +1 -1
- package/dist/docs-bundle.generated.js +6 -6
- package/dist/docs-index.bin +0 -0
- package/dist/framing.d.ts.map +1 -1
- package/dist/framing.js +4 -0
- package/dist/framing.js.map +1 -1
- package/dist/gateway.d.ts.map +1 -1
- package/dist/gateway.js +56 -35
- package/dist/gateway.js.map +1 -1
- package/dist/inline-delivery.d.ts +4 -2
- package/dist/inline-delivery.d.ts.map +1 -1
- package/dist/inline-delivery.js +5 -2
- package/dist/inline-delivery.js.map +1 -1
- package/dist/tool-specs.d.ts +6 -0
- package/dist/tool-specs.d.ts.map +1 -1
- package/dist/tool-specs.js +189 -34
- package/dist/tool-specs.js.map +1 -1
- package/package.json +3 -3
package/dist/tool-specs.js
CHANGED
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
*/
|
|
10
10
|
import { execFileSync } from "node:child_process";
|
|
11
11
|
import { z } from "zod";
|
|
12
|
-
import { isConcreteChannel, isChannelFamily, assertValidChannel, MAX_CHANNEL_LENGTH, channelInAllow, patternInAllow, AmbiguousPeerError, peerLabel, sharedNameIds, assertLifecycleToken, isPermissionDenied, renderLifecycleBlocked, EpEnvelopeError, EP_UNANSWERED, REGISTRY_PAGE_LIMIT, LANG_PROBLEM_DETAIL_KIND, formatAge, parseDuration, presenceAges, presenceText } from "@cotal-ai/core";
|
|
12
|
+
import { isConcreteChannel, isChannelFamily, assertValidChannel, MAX_CHANNEL_LENGTH, channelInAllow, patternInAllow, AmbiguousPeerError, peerLabel, sharedNameIds, assertLifecycleToken, isPermissionDenied, renderLifecycleBlocked, EpEnvelopeError, EP_UNANSWERED, REGISTRY_PAGE_LIMIT, LANG_PROBLEM_DETAIL_KIND, formatAge, parseDuration, presenceAges, presenceText, isAnycastSeq } from "@cotal-ai/core";
|
|
13
13
|
import { afterRecallMark } from "./agent.js";
|
|
14
14
|
// The neutralization and the per-item rendering live in `framing.ts`, one convention shared with
|
|
15
15
|
// the auto-injected block, and are used here rather than restated. See that file for the rule.
|
|
@@ -20,14 +20,74 @@ import { buildOrientation, presenceLiveness, renderOrientation } from "./orienta
|
|
|
20
20
|
import { runDocs } from "./docs.js";
|
|
21
21
|
const ok = (text) => ({ text });
|
|
22
22
|
const err = (text) => ({ text, isError: true });
|
|
23
|
+
/** How many holders a `cotal_anycast` result names before it counts the rest. */
|
|
24
|
+
const NAMED_HOLDERS = 8;
|
|
25
|
+
/** A holder by name and id. Both reach this from peers or the record, so neither may break a line. */
|
|
26
|
+
function holderLabel(h) {
|
|
27
|
+
return `${attributionSafe(h.name)} (${attributionSafe(h.id)})`;
|
|
28
|
+
}
|
|
29
|
+
/** The holders of a role, by name and id, from one roster read; `when` says which read. */
|
|
30
|
+
function holdersLine(holders, when = "at send") {
|
|
31
|
+
if (holders === undefined)
|
|
32
|
+
return `holders unknown ${when}: the presence view was not current`;
|
|
33
|
+
if (!holders.length)
|
|
34
|
+
return `0 holders online ${when}`;
|
|
35
|
+
const named = holders.slice(0, NAMED_HOLDERS).map(holderLabel).join(", ");
|
|
36
|
+
const more = holders.length > NAMED_HOLDERS ? ` and ${holders.length - NAMED_HOLDERS} more` : "";
|
|
37
|
+
return `${holders.length === 1 ? "holder" : "holders"} online ${when}: ${named}${more}`;
|
|
38
|
+
}
|
|
39
|
+
const TAKEN_MEANS = "Taken means that holder's connector was about to show it to its agent, not that the agent read, ran or finished it.";
|
|
40
|
+
function takenFollowUp(taker) {
|
|
41
|
+
return `Ask ${attributionSafe(taker.name)} with cotal_dm about the work, or use cotal_run for work you need followed to the end.`;
|
|
42
|
+
}
|
|
43
|
+
const UNKNOWN_OUTCOME = "Its outcome is unknown: a holder on an older connector may have taken it without a recorded take, it may have been dropped as malformed, or its record expired a day after it left the queue.";
|
|
44
|
+
function removalLine(status) {
|
|
45
|
+
if (status.removal === "deleted")
|
|
46
|
+
return "It was removed from the queue before any holder took it.";
|
|
47
|
+
if (status.removal === "already-gone")
|
|
48
|
+
return "It had already left the queue when the delivery daemon went to remove it: an earlier removal whose answer was lost may have taken it off, the queue may have been recreated, or a holder on an older connector, which records no take, may have taken it.";
|
|
49
|
+
return "No holder can take it now; the delivery daemon has not finished removing it from the queue.";
|
|
50
|
+
}
|
|
51
|
+
/** A request's status, as `cotal_anycast` with `seq` reports it (SPEC §8.1). */
|
|
52
|
+
function renderAnycastStatus(status, holders) {
|
|
53
|
+
const seq = status.seq;
|
|
54
|
+
if (status.state === "unknown")
|
|
55
|
+
return `No request seq ${seq} from you is on the queue, and the delivery daemon holds no record of it. ${UNKNOWN_OUTCOME}`;
|
|
56
|
+
if (status.state === "cancelled")
|
|
57
|
+
return `Request seq ${seq} on @${status.role} is cancelled. ${removalLine(status)}`;
|
|
58
|
+
if (status.state === "waiting")
|
|
59
|
+
return `Request seq ${seq} on @${status.role} is waiting on the queue, and no holder has taken it (${holdersLine(holders, "now")}). ` +
|
|
60
|
+
`A busy holder may already have it. If that holder does not confirm it in time, it goes back on the queue for a holder. Cancel it with seq ${seq} and cancel: true.`;
|
|
61
|
+
const before = status.previous
|
|
62
|
+
? ` Before that, ${holderLabel(status.previous)} took it and did not confirm it before its ack wait ran out, so ${attributionSafe(status.previous.name)} may also have started it.`
|
|
63
|
+
: "";
|
|
64
|
+
return `Request seq ${seq} on @${status.role} was taken by ${holderLabel(status.taker)} at ${new Date(status.at).toISOString()}.${before} ` +
|
|
65
|
+
`${TAKEN_MEANS} ${takenFollowUp(status.taker)}`;
|
|
66
|
+
}
|
|
67
|
+
/** A cancel's outcome, as `cotal_anycast` with `seq` and `cancel: true` reports it (SPEC §8.1). */
|
|
68
|
+
function renderAnycastCancel(status) {
|
|
69
|
+
const seq = status.seq;
|
|
70
|
+
if (status.state === "cancelled")
|
|
71
|
+
return `Cancelled request seq ${seq} on @${status.role}. ${removalLine(status)}`;
|
|
72
|
+
if (status.state === "taken")
|
|
73
|
+
return `Not cancelled: request seq ${seq} on @${status.role} was already taken by ${holderLabel(status.taker)}. ${TAKEN_MEANS} ${takenFollowUp(status.taker)}`;
|
|
74
|
+
if (status.state === "unknown")
|
|
75
|
+
return `Not cancelled: no request seq ${seq} from you is on the queue, and the delivery daemon holds no record of it. ${UNKNOWN_OUTCOME}`;
|
|
76
|
+
return `Not cancelled: request seq ${seq} on @${status.role} is still waiting. Try the cancel again.`;
|
|
77
|
+
}
|
|
23
78
|
/** A local inbox read cannot establish that a session is receiving from the mesh. */
|
|
24
79
|
function inboxConnectionWarning(agent) {
|
|
25
80
|
const state = agent.connectionState;
|
|
26
81
|
const channelIssue = agent.channelDeliveryIssue;
|
|
82
|
+
// A role request whose take the delivery daemon could not decide is held, not shown (SPEC §8.1).
|
|
83
|
+
const held = agent.heldTakes();
|
|
84
|
+
const heldIssue = held.count && held.detail
|
|
85
|
+
? `${held.count} role request${held.count === 1 ? " is" : "s are"} held and not shown: ${held.detail}`
|
|
86
|
+
: undefined;
|
|
27
87
|
if (state === "ready" || state === "stalled")
|
|
28
|
-
return channelIssue
|
|
88
|
+
return [channelIssue, heldIssue].filter(Boolean).join("\n");
|
|
29
89
|
const issue = agent.connectionIssue;
|
|
30
|
-
return [channelIssue, `Mesh connection is not ready (${state})${issue ? `: ${issue.slice(0, 500)}` : "."}\nLocally buffered messages are still readable; an empty buffer does not mean no new mesh messages.`].filter(Boolean).join("\n");
|
|
90
|
+
return [channelIssue, heldIssue, `Mesh connection is not ready (${state})${issue ? `: ${issue.slice(0, 500)}` : "."}\nLocally buffered messages are still readable; an empty buffer does not mean no new mesh messages.`].filter(Boolean).join("\n");
|
|
31
91
|
}
|
|
32
92
|
/** Cap on the JSON text a generic endpoint tool returns into the session. */
|
|
33
93
|
const ENDPOINT_RESULT_MAX_CHARS = 200_000;
|
|
@@ -260,6 +320,8 @@ export function renderInbox(opts) {
|
|
|
260
320
|
const strict = strictIds.has(i.recvKey);
|
|
261
321
|
if (strict && strictGap)
|
|
262
322
|
continue;
|
|
323
|
+
if (opts.only && !opts.only.has(i.recvKey))
|
|
324
|
+
continue;
|
|
263
325
|
const cost = itemCost(i);
|
|
264
326
|
if (used + cost > budget) {
|
|
265
327
|
// In the ordered lane even a message no response could carry whole is a gap: the mark would
|
|
@@ -295,6 +357,65 @@ export function renderInbox(opts) {
|
|
|
295
357
|
}
|
|
296
358
|
return { text, shown, held, stuck };
|
|
297
359
|
}
|
|
360
|
+
/** How many times one read chooses its reply again after a take of a request it chose is refused. */
|
|
361
|
+
export const READ_TAKE_ROUNDS = 8;
|
|
362
|
+
/**
|
|
363
|
+
* Render one reply over the inbox preview, take the held role requests it carries (or the one it
|
|
364
|
+
* carries part of), then render it again over what may be shown now (SPEC §8.1). The second pass
|
|
365
|
+
* shows only what the first chose, so a reply never takes a request it does not show. It renders a
|
|
366
|
+
* subset of the first pass's items in the same order, so it fits wherever the first did. `extra`
|
|
367
|
+
* rides after the buffer and needs no take, such as focus recall. `warning` is read at each render,
|
|
368
|
+
* so the reply reports what the takes left held. A read whose caller is gone takes nothing.
|
|
369
|
+
*/
|
|
370
|
+
async function takeForReply(agent, scope, opts, extra = []) {
|
|
371
|
+
const { warning, signal, ...render } = opts;
|
|
372
|
+
let pending;
|
|
373
|
+
let preview = [];
|
|
374
|
+
let chosen = new Set();
|
|
375
|
+
let shown = new Set();
|
|
376
|
+
let part;
|
|
377
|
+
let taken = new Set();
|
|
378
|
+
let showable;
|
|
379
|
+
const undecided = new Set();
|
|
380
|
+
for (let round = 0; round < READ_TAKE_ROUNDS && !signal?.aborted; round++) {
|
|
381
|
+
const got = await agent.takeChosen(scope, (p) => {
|
|
382
|
+
// A read carries only what was pending when it began, so mail arriving meanwhile cannot push
|
|
383
|
+
// out a request an earlier round took.
|
|
384
|
+
pending ??= new Set(p.map((i) => i.recvKey));
|
|
385
|
+
preview = p.filter((i) => pending.has(i.recvKey));
|
|
386
|
+
const candidates = showable ? preview.filter((i) => showable.has(i.recvKey)) : preview;
|
|
387
|
+
const first = renderInbox({ ...render, warning: warning(), items: [...candidates, ...extra] });
|
|
388
|
+
shown = new Set(first.shown.map((i) => i.recvKey));
|
|
389
|
+
part = first.shown.length ? undefined : candidates.find((i) => first.stuck.has(i.recvKey));
|
|
390
|
+
const picked = [...candidates.filter((i) => shown.has(i.recvKey)), ...(part ? [part] : [])];
|
|
391
|
+
chosen = new Set(picked.map((i) => i.recvKey));
|
|
392
|
+
return picked;
|
|
393
|
+
});
|
|
394
|
+
taken = new Set(got.map((i) => i.recvKey));
|
|
395
|
+
// A refused take leaves room another message can use, so the reply is chosen again without it. A
|
|
396
|
+
// take still undecided would only repeat its wait if chosen again, so the reply is chosen once
|
|
397
|
+
// more from what needs no take, and the undecided request waits for a later read.
|
|
398
|
+
const missed = [...chosen].filter((k) => !taken.has(k));
|
|
399
|
+
if (!missed.length || showable)
|
|
400
|
+
break;
|
|
401
|
+
const open = new Set(agent.inboxPreview(scope).map((i) => i.recvKey));
|
|
402
|
+
for (const k of missed)
|
|
403
|
+
if (open.has(k))
|
|
404
|
+
undecided.add(k);
|
|
405
|
+
if (undecided.size)
|
|
406
|
+
showable = new Set(agent.peekInbox(scope).map((i) => i.recvKey));
|
|
407
|
+
}
|
|
408
|
+
// A chosen request whose take was refused or is still undecided leaves this reply entirely. A reply
|
|
409
|
+
// chosen again from what needs no take offers only that, so a request never asked is not named.
|
|
410
|
+
const live = new Set(agent.inboxKeys(scope));
|
|
411
|
+
const offered = preview.filter((i) => live.has(i.recvKey) && !undecided.has(i.recvKey) && (!chosen.has(i.recvKey) || taken.has(i.recvKey)) && (!showable || showable.has(i.recvKey)));
|
|
412
|
+
return {
|
|
413
|
+
reply: renderInbox({ ...render, warning: warning(), items: [...offered, ...extra], only: shown }),
|
|
414
|
+
offered,
|
|
415
|
+
buffered: agent.peekInbox(scope),
|
|
416
|
+
part: part && taken.has(part.recvKey) ? part : undefined,
|
|
417
|
+
};
|
|
418
|
+
}
|
|
298
419
|
const NOTE_TIERS = ["full", "compact", "none"];
|
|
299
420
|
/** What one rendered item costs a response: its own text plus the newline that joins it. */
|
|
300
421
|
function itemCost(i) {
|
|
@@ -915,28 +1036,31 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
915
1036
|
return ok(text);
|
|
916
1037
|
};
|
|
917
1038
|
if (agent.attention !== "focus") {
|
|
918
|
-
|
|
919
|
-
const
|
|
920
|
-
const buffered = agent.peekInbox(inboxScope);
|
|
921
|
-
const { text, shown, held, stuck } = renderInbox({
|
|
922
|
-
items: buffered,
|
|
1039
|
+
// A peek shows bodies too, so a peek takes what it shows like any read.
|
|
1040
|
+
const { reply: rendered, offered, buffered, part: taken } = await takeForReply(agent, inboxScope, {
|
|
923
1041
|
peek,
|
|
924
|
-
warning,
|
|
1042
|
+
warning: () => [inboxConnectionWarning(agent), storedNote].filter(Boolean).join("\n"),
|
|
1043
|
+
signal: call?.signal,
|
|
925
1044
|
head: (s) => pulls
|
|
926
1045
|
? `${s.length} pull-only message${s.length === 1 ? "" : "s"} (cleared; automatic traffic remains connector-managed):`
|
|
927
1046
|
: `${s.length} message${s.length === 1 ? "" : "s"}${peek ? ` (peek: nothing cleared${stillDelivered})` : ""}:`,
|
|
928
1047
|
});
|
|
929
|
-
|
|
1048
|
+
const { text, shown, held, stuck } = rendered;
|
|
1049
|
+
// Asked after the takes: one this read asked for can have been held since.
|
|
1050
|
+
const connectionWarning = inboxConnectionWarning(agent);
|
|
1051
|
+
const warning = [connectionWarning, storedNote].filter(Boolean).join("\n");
|
|
1052
|
+
if (!offered.length) {
|
|
930
1053
|
return reply([warning, pulls
|
|
931
1054
|
? `No pull-only messages.${automaticPending ? ` ${automaticPending} connector-managed automatic message${automaticPending === 1 ? " is" : "s are"} still queued; peek to read ${automaticPending === 1 ? "it" : "them"} now.` : ""}`
|
|
932
1055
|
// A hook receipt never masks an unavailable connection, even with a live transport.
|
|
933
1056
|
: connectionWarning ? "Local inbox buffer is empty."
|
|
934
1057
|
: (agent.connectionState === "ready" ? emptyInboxNote?.() : undefined) ?? "Inbox empty, no new messages."].filter(Boolean).join("\n\n"));
|
|
1058
|
+
}
|
|
935
1059
|
if (!shown.length) {
|
|
936
1060
|
const part = partReply({
|
|
937
1061
|
agent,
|
|
938
|
-
item: buffered.find((i) => stuck.has(i.recvKey)),
|
|
939
|
-
offered
|
|
1062
|
+
item: taken ?? buffered.find((i) => stuck.has(i.recvKey)),
|
|
1063
|
+
offered,
|
|
940
1064
|
stuck,
|
|
941
1065
|
peek: keeps(),
|
|
942
1066
|
warning,
|
|
@@ -960,9 +1084,6 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
960
1084
|
const before = new Set(agent.peekInbox("all").map((i) => i.recvKey));
|
|
961
1085
|
const underway = new Set([...(partOffsets.get(agent)?.keys() ?? [])].filter((k) => !before.has(k)));
|
|
962
1086
|
const recall = await agent.recallAmbient(underway);
|
|
963
|
-
// Read after recall, which can hand an id-less message back into the buffer (#662).
|
|
964
|
-
const buffered = agent.peekInbox(inboxScope);
|
|
965
|
-
const bufferedIds = new Set(buffered.map((i) => i.recvKey));
|
|
966
1087
|
// RECALL HAS TO ADVANCE, or windowing it starves it. Recall is re-derived from an unchanged
|
|
967
1088
|
// frontier on every call, so showing its first window and stopping there returned the same
|
|
968
1089
|
// prefix forever while the reply promised a next batch: measured as three identical replies
|
|
@@ -1008,20 +1129,25 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
1008
1129
|
aheadFresh.sort(byTsThenId);
|
|
1009
1130
|
const fresh = [...clocked, ...aheadFresh];
|
|
1010
1131
|
const aheadIds = new Set(aheadFresh.map((i) => i.recvKey));
|
|
1011
|
-
const
|
|
1012
|
-
const warning = [connectionWarning, storedNote, droppedNote(recall.droppedChannels), aheadNote(aheadWithheld)]
|
|
1132
|
+
const focusWarning = () => [inboxConnectionWarning(agent), storedNote, droppedNote(recall.droppedChannels), aheadNote(aheadWithheld)]
|
|
1013
1133
|
.filter(Boolean)
|
|
1014
1134
|
.join(" ");
|
|
1015
|
-
|
|
1016
|
-
|
|
1135
|
+
// Taken after recall, which can hand an id-less message back into the buffer (#662).
|
|
1136
|
+
const { reply: rendered, offered, buffered, part: taken } = await takeForReply(agent, inboxScope, {
|
|
1017
1137
|
peek,
|
|
1018
|
-
warning,
|
|
1138
|
+
warning: focusWarning,
|
|
1139
|
+
signal: call?.signal,
|
|
1019
1140
|
strictIds: new Set(clocked.map((i) => i.recvKey)),
|
|
1020
1141
|
head: (s) => pulls
|
|
1021
1142
|
? `${s.length} message${s.length === 1 ? "" : "s"}. Buffered pull-only items were cleared; normal focus channel items are read-only recall:`
|
|
1022
1143
|
: `${s.length} message${s.length === 1 ? "" : "s"}${peek ? ` (peek: live buffer not cleared${stillDelivered})` : ""} in focus mode; channel items are recall since you focused:`,
|
|
1023
|
-
});
|
|
1024
|
-
|
|
1144
|
+
}, fresh);
|
|
1145
|
+
const bufferedIds = new Set(buffered.map((i) => i.recvKey));
|
|
1146
|
+
const { text, shown: all, stuck } = rendered;
|
|
1147
|
+
// Asked after the takes: one this read asked for can have been held since.
|
|
1148
|
+
const connectionWarning = inboxConnectionWarning(agent);
|
|
1149
|
+
const warning = focusWarning();
|
|
1150
|
+
if (!offered.length && !fresh.length && !recall.droppedChannels.length && !aheadWithheld.length)
|
|
1025
1151
|
return reply([connectionWarning, storedNote, pulls
|
|
1026
1152
|
? `No pull-only messages and no normal focus recall.${automaticPending ? ` ${automaticPending} connector-managed automatic message${automaticPending === 1 ? " is" : "s are"} still queued; peek to read ${automaticPending === 1 ? "it" : "them"} now.` : ""}`
|
|
1027
1153
|
: connectionWarning ? "Local inbox buffer and available focus recall are empty." : "Inbox empty, no new messages, and no channel chatter since you entered focus."].filter(Boolean).join("\n\n"));
|
|
@@ -1030,12 +1156,13 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
1030
1156
|
// have: the mark for the ordered lane, whose first item is the only one it may take, or the
|
|
1031
1157
|
// ahead record, so the mark never passes a message that has not been handed over.
|
|
1032
1158
|
const first = clocked[0];
|
|
1033
|
-
const item =
|
|
1159
|
+
const item = taken ??
|
|
1160
|
+
buffered.find((i) => stuck.has(i.recvKey)) ??
|
|
1034
1161
|
(first && stuck.has(first.recvKey) ? first : aheadFresh.find((i) => stuck.has(i.recvKey)));
|
|
1035
1162
|
const part = partReply({
|
|
1036
1163
|
agent,
|
|
1037
1164
|
item,
|
|
1038
|
-
offered: [...
|
|
1165
|
+
offered: [...offered, ...fresh],
|
|
1039
1166
|
stuck,
|
|
1040
1167
|
peek: keeps(),
|
|
1041
1168
|
warning,
|
|
@@ -1161,26 +1288,54 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
1161
1288
|
name: "cotal_anycast",
|
|
1162
1289
|
title: "Cotal: ask any agent of a role",
|
|
1163
1290
|
description: "Ask whoever holds a role. Use it only when the team was built for it, with agents that hold the role to take requests, such as a pool of reviewers started with cotal_spawn and role. " +
|
|
1164
|
-
"The request waits until one of them takes it, which can take a while if they are all busy. Without such a pool, mention a named agent on the task's channel, send a DM, or spawn a helper. " +
|
|
1291
|
+
"The request waits on the role's queue until one of them takes it, which can take a while if they are all busy, and one sent while no agent holds the role is kept for the next that does. Without such a pool, mention a named agent on the task's channel, send a DM, or spawn a helper. " +
|
|
1292
|
+
"The result gives the request's seq and the holders online at send. Except on an open mesh, you get a notice naming the holder that takes it, seq alone reads the request's status, and seq with cancel: true cancels it while it still waits. A cancel is refused once a holder took the request. " +
|
|
1165
1293
|
"Anycast does not follow the work after someone takes it. To follow work to the end, use cotal_run. " +
|
|
1166
1294
|
'Example: `{role: "review-frontend", text: "Review issue #812, the checkout button. Post your findings on #review.checkout."}`',
|
|
1167
1295
|
schema: {
|
|
1168
|
-
role: z.string().describe("
|
|
1169
|
-
text: z.string().describe("
|
|
1296
|
+
role: z.string().optional().describe("Send: the role to address (e.g. reviewer). Give it with text."),
|
|
1297
|
+
text: z.string().optional().describe("Send: the request."),
|
|
1298
|
+
seq: z.number().optional().describe("Status or cancel: the seq a send returned. Give it alone for the request's status."),
|
|
1299
|
+
cancel: z.boolean().optional().describe("Cancel: true, with seq, cancels that request while it still waits."),
|
|
1170
1300
|
},
|
|
1171
|
-
async run(agent,
|
|
1301
|
+
async run(agent, config, { role, text: msg, seq, cancel }) {
|
|
1302
|
+
// One call does one thing, and a call that is not exactly one of them changes nothing.
|
|
1303
|
+
const sending = role !== undefined || msg !== undefined;
|
|
1304
|
+
const asking = seq !== undefined || cancel !== undefined;
|
|
1305
|
+
if (sending && asking)
|
|
1306
|
+
return err("cotal_anycast does one thing per call: send with role and text, read a status with seq, or cancel with seq and cancel: true. Nothing was sent, read or cancelled.");
|
|
1307
|
+
if (asking) {
|
|
1308
|
+
if (seq === undefined)
|
|
1309
|
+
return err("cancel needs the seq of the request to cancel. Nothing was cancelled.");
|
|
1310
|
+
if (!isAnycastSeq(seq))
|
|
1311
|
+
return err(`seq must be a whole number of at least 1, the seq a send returned; got ${seq}. Nothing was read or cancelled.`);
|
|
1312
|
+
if (cancel === false)
|
|
1313
|
+
return err("cancel takes only true. Give seq alone for the request's status. Nothing was read or cancelled.");
|
|
1314
|
+
if (!isAuthed(config))
|
|
1315
|
+
return err("This is an open mesh: it runs no delivery daemon, so it keeps no record of a request after its send, and a request cannot be read or cancelled by seq.");
|
|
1316
|
+
try {
|
|
1317
|
+
const status = cancel ? await agent.cancelAnycast(seq) : await agent.anycastStatus(seq);
|
|
1318
|
+
const holders = status.state === "waiting" ? await agent.roleHolders(status.role) : undefined;
|
|
1319
|
+
return ok(cancel ? renderAnycastCancel(status) : renderAnycastStatus(status, holders));
|
|
1320
|
+
}
|
|
1321
|
+
catch (e) {
|
|
1322
|
+
return err(`Couldn't ${cancel ? "cancel" : "read the status of"} request seq ${seq}: ${e.message}`);
|
|
1323
|
+
}
|
|
1324
|
+
}
|
|
1325
|
+
if (role === undefined || msg === undefined)
|
|
1326
|
+
return err("A send needs both role and text. Nothing was sent.");
|
|
1172
1327
|
try {
|
|
1173
|
-
const { ack, holdersAtSend
|
|
1328
|
+
const { ack, holdersAtSend } = await agent.anycast(role, msg);
|
|
1174
1329
|
const dup = ack.duplicate ? " duplicate publication." : "";
|
|
1175
|
-
const at = n === undefined
|
|
1176
|
-
? "holders unknown at send: the presence view was not current"
|
|
1177
|
-
: `${n} holder${n === 1 ? "" : "s"} online at send`;
|
|
1178
1330
|
// Zero holders is not a failure: the queue keeps the request for whoever takes the role
|
|
1179
1331
|
// next. Say so, so it reads neither as delivered nor as lost.
|
|
1180
|
-
const none =
|
|
1332
|
+
const none = holdersAtSend?.length === 0
|
|
1181
1333
|
? ` No present agent holds @${role}, so the request waits on its queue until one does. Roles match exactly; cotal_roster shows the roles present.`
|
|
1182
1334
|
: "";
|
|
1183
|
-
|
|
1335
|
+
const follow = isAuthed(config)
|
|
1336
|
+
? ` You get a notice naming the holder that takes it. Read its status with seq ${ack.seq}, or cancel it with seq ${ack.seq} and cancel: true while it waits.`
|
|
1337
|
+
: "";
|
|
1338
|
+
return ok(`Request stored as seq ${ack.seq} on the @${role} queue (${holdersLine(holdersAtSend)}; delivery not confirmed).${dup}${none}${follow}`);
|
|
1184
1339
|
}
|
|
1185
1340
|
catch (e) {
|
|
1186
1341
|
return err(`Couldn't send: ${e.message}`);
|