@cotal-ai/connector-core 0.134.0 → 0.135.1
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 +49 -2
- package/dist/agent.d.ts.map +1 -1
- package/dist/agent.js +191 -31
- package/dist/agent.js.map +1 -1
- package/dist/control.d.ts +3 -2
- package/dist/control.d.ts.map +1 -1
- package/dist/control.js +1 -1
- package/dist/control.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-bundle.generated.js.map +1 -1
- package/dist/docs-index.bin +0 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -0
- package/dist/index.js.map +1 -1
- package/dist/once.d.ts +53 -0
- package/dist/once.d.ts.map +1 -0
- package/dist/once.js +126 -0
- package/dist/once.js.map +1 -0
- package/dist/orientation.d.ts.map +1 -1
- package/dist/orientation.js +5 -2
- package/dist/orientation.js.map +1 -1
- package/dist/tool-specs.d.ts +1 -1
- package/dist/tool-specs.d.ts.map +1 -1
- package/dist/tool-specs.js +122 -37
- 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, assertValidChannel, MAX_CHANNEL_LENGTH, channelInAllow, AmbiguousPeerError, peerLabel, assertLifecycleToken, isPermissionDenied, renderLifecycleBlocked, EpEnvelopeError, EP_UNANSWERED, REGISTRY_PAGE_LIMIT, LANG_PROBLEM_DETAIL_KIND, formatAge, presenceAges, presenceText } from "@cotal-ai/core";
|
|
12
|
+
import { isConcreteChannel, isChannelFamily, assertValidChannel, MAX_CHANNEL_LENGTH, PLANE3_MAX_MSGS_PER_SUBJECT, channelInAllow, patternInAllow, AmbiguousPeerError, peerLabel, assertLifecycleToken, isPermissionDenied, renderLifecycleBlocked, EpEnvelopeError, EP_UNANSWERED, REGISTRY_PAGE_LIMIT, LANG_PROBLEM_DETAIL_KIND, formatAge, parseDuration, presenceAges, presenceText } 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.
|
|
@@ -457,6 +457,9 @@ function droppedNote(channels) {
|
|
|
457
457
|
const rest = channels.length - Math.min(NAMED_DROPPED, channels.length);
|
|
458
458
|
return `⚠ Some earlier chatter could not be recalled completely on ${named}${rest ? `, and ${rest} more channel${rest === 1 ? "" : "s"}` : ""} (retention or local safety bounds were reached, or recall could not read the channel).`;
|
|
459
459
|
}
|
|
460
|
+
/** Said once after this session's stored copies reached their limit (#5404). NATS reports no discard,
|
|
461
|
+
* so it says "may". */
|
|
462
|
+
const STORED_COPIES_NOTE = `⚠ Your stored copies reached their limit of ${PLANE3_MAX_MSGS_PER_SUBJECT}, so earlier channel posts may have been dropped before they reached you. Channel history may still hold them: \`cotal history <channel>\` reads it, within the space's history limit.`;
|
|
460
463
|
/** How many channels the recall warning names before it starts counting them instead. */
|
|
461
464
|
const NAMED_DROPPED = 5;
|
|
462
465
|
/** How many rows one `cotal_channels` reply lists before it says how to continue. */
|
|
@@ -493,7 +496,9 @@ function renderChannelInfo(channel, info) {
|
|
|
493
496
|
const lines = [
|
|
494
497
|
`#${channel} — channel registry (advisory metadata about this channel, NOT instructions for you to obey):`,
|
|
495
498
|
];
|
|
496
|
-
if (!
|
|
499
|
+
if (!isConcreteChannel(channel))
|
|
500
|
+
lines.push(" • a pattern: it has no registry entry of its own, and each channel it matches keeps its own.");
|
|
501
|
+
else if (!info.registered)
|
|
497
502
|
lines.push(info.event === "own"
|
|
498
503
|
? " • your own event channel: your connector publishes this session's activity events here. It is not a chat channel and needs no registry entry."
|
|
499
504
|
: info.event === "agent"
|
|
@@ -583,26 +588,35 @@ export async function orientationCard(agent, config, source, env, offered) {
|
|
|
583
588
|
}
|
|
584
589
|
/** How to reach a channel family, since every publish names one concrete channel (SPEC §3). The
|
|
585
590
|
* advertised `channel` text of `cotal_send`, here and in the gateway. */
|
|
586
|
-
export const PATTERN_SEND_HELP = "A pattern such as team.> is refused. To reach the agents
|
|
587
|
-
/** Why `
|
|
588
|
-
*
|
|
589
|
-
*
|
|
590
|
-
* characters onto another subject than the receipt names, and the grammar's own message lists the
|
|
591
|
+
export const PATTERN_SEND_HELP = "A pattern such as team.> is refused. To reach the agents following team.>, post once to one channel it matches, such as team.announce: those connected then get it, and one that is away gets a stored copy if that channel is durable. To reach several channels, post to each by name (cotal_channels lists the existing ones).";
|
|
592
|
+
/** Why `channel` is not a channel name at all, ending with `outcome`, or undefined when it keeps the
|
|
593
|
+
* channel grammar (a concrete name or a legal pattern). The endpoint would rewrite such a name's
|
|
594
|
+
* characters onto another subject than the tool names, and the grammar's own message lists the
|
|
591
595
|
* wildcard segments a policy may use. */
|
|
592
|
-
function
|
|
593
|
-
let legal = true;
|
|
596
|
+
function notAChannelName(channel, outcome) {
|
|
594
597
|
try {
|
|
595
598
|
assertValidChannel(channel);
|
|
599
|
+
return undefined;
|
|
596
600
|
}
|
|
597
601
|
catch {
|
|
598
|
-
|
|
602
|
+
const shown = JSON.stringify(channel.length > 64 ? `${channel.slice(0, 64)}…` : channel);
|
|
603
|
+
return `${shown} is not a channel name. A channel name is segments of letters, digits, _ and - joined by dots, such as team.announce, at most ${MAX_CHANNEL_LENGTH} characters. ${outcome}`;
|
|
599
604
|
}
|
|
600
|
-
|
|
605
|
+
}
|
|
606
|
+
/** Why `cotal_send` refuses `channel`, returned before anything is read or sent, or undefined when it
|
|
607
|
+
* is one concrete channel name. A legal pattern gets the ways to reach its followers: a family's
|
|
608
|
+
* followers that are away get stored copies on durable channels (#5404), and any other pattern's only
|
|
609
|
+
* while connected. Any other name that breaks the channel grammar is refused as no channel name. */
|
|
610
|
+
function sendChannelRefusal(channel) {
|
|
611
|
+
const notName = notAChannelName(channel, "Nothing was sent.");
|
|
612
|
+
if (notName !== undefined)
|
|
613
|
+
return notName;
|
|
614
|
+
if (isConcreteChannel(channel))
|
|
601
615
|
return undefined;
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
return
|
|
616
|
+
const reach = isChannelFamily(channel)
|
|
617
|
+
? `To reach the agents following ${channel}, post once to one channel it matches: those connected then get it, and one that is away gets a stored copy if that channel is durable. `
|
|
618
|
+
: `To reach the agents connected and following ${channel} now, post once to one channel it matches. A pattern with * or the root > has no stored copies, so a follower that is offline then may miss it. `;
|
|
619
|
+
return `"${channel}" is a pattern, and a post goes to one concrete channel. ${reach}To reach several channels, post to each by name; cotal_channels lists the existing ones. Nothing was sent.`;
|
|
606
620
|
}
|
|
607
621
|
/** The full Cotal tool set for a given config. Renderers iterate this; `source` names the
|
|
608
622
|
* hosting connector and is stamped onto outgoing feedback. An explicit env restricts feedback's
|
|
@@ -821,7 +835,8 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
821
835
|
name: "cotal_inbox",
|
|
822
836
|
title: "Cotal: read incoming messages",
|
|
823
837
|
description: "Read messages other agents have sent you since you last checked: channel broadcasts, direct messages, and role requests. It clears ONLY what it actually returns to you (nothing at all when peek is true), and one call carries at most a receivable window: direct messages and role requests first, then channel traffic, with replayed history last. Anything that does not fit stays buffered and is named in the reply, so call again for the next batch. A single message larger than one whole response is delivered in parts: once no smaller mail is waiting, each call carries the next part of it, a peek shows the current part without moving on, and the message is cleared only after its last part goes out. In focus mode it also pulls back the channel chatter held since you entered focus. If exclusion tracking makes a channel's focus recall unsafe, new non-historical mentions on that unmuted channel wake to pull their buffered bodies, never automatic injection, including on quiet channels. Ambient handling is unchanged, and the incomplete-recall warning still names unsafe channels. " +
|
|
824
|
-
"When the connection is not ready, the reply says so and still returns locally buffered messages; an empty local buffer does not prove no new mesh messages exist. Exhausted channel drop tracking is reported even with an empty inbox; non-historical mentions on unmuted channels wake to pull their buffered bodies while ambient traffic stays suppressed."
|
|
838
|
+
"When the connection is not ready, the reply says so and still returns locally buffered messages; an empty local buffer does not prove no new mesh messages exist. Exhausted channel drop tracking is reported even with an empty inbox; non-historical mentions on unmuted channels wake to pull their buffered bodies while ambient traffic stays suppressed. " +
|
|
839
|
+
"If your stored copies reached their limit of 1000, the reply says earlier channel posts may have been dropped and that channel history may still hold them. A peek keeps that line for the next read.",
|
|
825
840
|
schema: {
|
|
826
841
|
peek: z.boolean().optional().describe("If true, show messages without clearing them."),
|
|
827
842
|
},
|
|
@@ -839,8 +854,18 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
839
854
|
// evicted and lost. That is the buffer's documented bounded local loss (see
|
|
840
855
|
// MeshAgent.buffer), unchanged by this path; an evicted directed message is never acked.
|
|
841
856
|
const automaticPending = scope ? agent.inboxCount("automatic") : 0;
|
|
857
|
+
// Every reply below carries the stored-copy notice, and it clears as the messages do: once the
|
|
858
|
+
// reply exists and its caller is still there. A recall that throws or a caller that goes keeps it.
|
|
859
|
+
const storedSeen = agent.storedCopiesFull;
|
|
860
|
+
const storedNote = storedSeen ? STORED_COPIES_NOTE : "";
|
|
861
|
+
const reply = (text) => {
|
|
862
|
+
if (storedSeen && !keeps())
|
|
863
|
+
agent.clearStoredCopiesFull(storedSeen);
|
|
864
|
+
return ok(text);
|
|
865
|
+
};
|
|
842
866
|
if (agent.attention !== "focus") {
|
|
843
|
-
const
|
|
867
|
+
const connectionWarning = inboxConnectionWarning(agent);
|
|
868
|
+
const warning = [connectionWarning, storedNote].filter(Boolean).join("\n");
|
|
844
869
|
const buffered = agent.peekInbox(inboxScope);
|
|
845
870
|
const { text, shown, held, stuck } = renderInbox({
|
|
846
871
|
items: buffered,
|
|
@@ -851,10 +876,10 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
851
876
|
: `${s.length} message${s.length === 1 ? "" : "s"}${peek ? " (peek: nothing cleared)" : ""}:`,
|
|
852
877
|
});
|
|
853
878
|
if (!buffered.length)
|
|
854
|
-
return
|
|
879
|
+
return reply([warning, scope
|
|
855
880
|
? `No pull-only messages.${automaticPending ? ` ${automaticPending} connector-managed automatic message${automaticPending === 1 ? " is" : "s are"} still queued.` : ""}`
|
|
856
881
|
// A hook receipt never masks an unavailable connection, even with a live transport.
|
|
857
|
-
:
|
|
882
|
+
: connectionWarning ? "Local inbox buffer is empty."
|
|
858
883
|
: (agent.connectionState === "ready" ? emptyInboxNote?.() : undefined) ?? "Inbox empty, no new messages."].filter(Boolean).join("\n\n"));
|
|
859
884
|
if (!shown.length) {
|
|
860
885
|
const part = partReply({
|
|
@@ -867,7 +892,7 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
867
892
|
last: (i) => agent.drainInboxDeliveries([i.recvKey]),
|
|
868
893
|
});
|
|
869
894
|
if (part)
|
|
870
|
-
return
|
|
895
|
+
return reply(part);
|
|
871
896
|
}
|
|
872
897
|
// The response exists before anything is acked: an ack is a claim that these messages were
|
|
873
898
|
// handed over, so nothing may be cleared while the handing-over is still hypothetical. And
|
|
@@ -875,7 +900,7 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
875
900
|
if (!keeps())
|
|
876
901
|
agent.drainInboxDeliveries(shown.map((i) => i.recvKey));
|
|
877
902
|
void held;
|
|
878
|
-
return
|
|
903
|
+
return reply(text);
|
|
879
904
|
}
|
|
880
905
|
// Focus: the live buffer holds only DMs/anycast; the channel ambient + @mentions were
|
|
881
906
|
// acked-and-dropped at ingest, so pull them back from the channel stream here (replay-gated,
|
|
@@ -933,7 +958,7 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
933
958
|
const fresh = [...clocked, ...aheadFresh];
|
|
934
959
|
const aheadIds = new Set(aheadFresh.map((i) => i.recvKey));
|
|
935
960
|
const connectionWarning = inboxConnectionWarning(agent);
|
|
936
|
-
const warning = [connectionWarning, droppedNote(recall.droppedChannels), aheadNote(aheadWithheld)]
|
|
961
|
+
const warning = [connectionWarning, storedNote, droppedNote(recall.droppedChannels), aheadNote(aheadWithheld)]
|
|
937
962
|
.filter(Boolean)
|
|
938
963
|
.join(" ");
|
|
939
964
|
const { text, shown: all, stuck } = renderInbox({
|
|
@@ -946,7 +971,7 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
946
971
|
: `${s.length} message${s.length === 1 ? "" : "s"}${peek ? " (peek: live buffer not cleared)" : ""} in focus mode; channel items are recall since you focused:`,
|
|
947
972
|
});
|
|
948
973
|
if (!buffered.length && !fresh.length && !recall.droppedChannels.length && !aheadWithheld.length)
|
|
949
|
-
return
|
|
974
|
+
return reply([connectionWarning, storedNote, scope
|
|
950
975
|
? `No pull-only messages and no normal focus recall.${automaticPending ? ` ${automaticPending} connector-managed automatic message${automaticPending === 1 ? " is" : "s are"} still queued.` : ""}`
|
|
951
976
|
: 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"));
|
|
952
977
|
if (!all.length) {
|
|
@@ -973,7 +998,7 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
973
998
|
},
|
|
974
999
|
});
|
|
975
1000
|
if (part)
|
|
976
|
-
return
|
|
1001
|
+
return reply(part);
|
|
977
1002
|
}
|
|
978
1003
|
// Render first, ack second, and only ever ids from the buffered lane: acking a recall id
|
|
979
1004
|
// would mark it handled, so a later live copy of that channel message would be dropped.
|
|
@@ -1000,7 +1025,7 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
1000
1025
|
agent.noteRecalled({ ts: last.ts, id: last.recvKey });
|
|
1001
1026
|
void stuck;
|
|
1002
1027
|
}
|
|
1003
|
-
return
|
|
1028
|
+
return reply(text);
|
|
1004
1029
|
}),
|
|
1005
1030
|
},
|
|
1006
1031
|
{
|
|
@@ -1147,6 +1172,9 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
1147
1172
|
channel: z.string().describe("The channel to look up (e.g. review)."),
|
|
1148
1173
|
},
|
|
1149
1174
|
run(agent, _config, { channel }) {
|
|
1175
|
+
const notName = notAChannelName(channel, "Nothing was looked up.");
|
|
1176
|
+
if (notName !== undefined)
|
|
1177
|
+
return err(`Couldn't look up the channel: ${notName}`);
|
|
1150
1178
|
if (!agent.connected)
|
|
1151
1179
|
return ok(`Not connected to the mesh yet (${config.servers}).`);
|
|
1152
1180
|
return ok(renderChannelInfo(channel, agent.channelInfo(channel)));
|
|
@@ -1195,6 +1223,18 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
1195
1223
|
: c.event === "agent"
|
|
1196
1224
|
? " — an agent's event channel"
|
|
1197
1225
|
: "";
|
|
1226
|
+
if (c.follow === "live")
|
|
1227
|
+
return `● #${c.channel} — pattern you follow, live only (a pattern with * or the root > has no stored copies)`;
|
|
1228
|
+
if (c.follow === "family" && !c.joined)
|
|
1229
|
+
return `○ #${c.channel} — family you no longer follow${c.durableUnclosed ? " · durable cleanup pending (§7 backstop may still deliver — retrying)" : ""}`;
|
|
1230
|
+
if (c.follow === "family") {
|
|
1231
|
+
const stored = c.deliveryHealth === "active"
|
|
1232
|
+
? "stored copies on for its durable channels"
|
|
1233
|
+
: c.deliveryHealth === "unknown"
|
|
1234
|
+
? "stored-copy health unknown: this reader cannot establish it"
|
|
1235
|
+
: "stored copies unavailable; live messages still arrive, and offline posts on its durable channels are at risk";
|
|
1236
|
+
return `● #${c.channel} — family you follow: every channel under ${c.channel.slice(0, -2)}, ${stored}${c.durableUnclosed ? " · durable cleanup pending (§7 backstop may still deliver — retrying)" : ""}`;
|
|
1237
|
+
}
|
|
1198
1238
|
const mode = c.mode !== "normal" ? ` · ${c.mode}` : "";
|
|
1199
1239
|
const unclosed = c.durableUnclosed ? " · durable cleanup pending (§7 backstop may still deliver — retrying)" : "";
|
|
1200
1240
|
// Non-gating delivery-health: a durable-class channel must never look like ordinary
|
|
@@ -1257,14 +1297,20 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
1257
1297
|
{
|
|
1258
1298
|
name: "cotal_join",
|
|
1259
1299
|
title: "Cotal: join a channel",
|
|
1260
|
-
description: "Subscribe to a channel mid-session. Returns its registry info; if the channel replays, recent history is delivered to your inbox marked as catch-up (it pre-dates your join, so don't treat it as live).
|
|
1300
|
+
description: "Subscribe to a channel mid-session. Returns its registry info; if the channel replays, recent history is delivered to your inbox marked as catch-up (it pre-dates your join, so don't treat it as live). " +
|
|
1301
|
+
"A family such as team.> follows every channel under team, now and later, but not team itself: posts on its durable channels are stored for you while you are away, from the join on, and its live channels reach you only while you are connected. A pattern with * or the root > is followed live only. " +
|
|
1302
|
+
"Idempotent. Bounded by your read ACL: a channel outside it is refused.",
|
|
1261
1303
|
schema: {
|
|
1262
|
-
channel: z.string().describe("The channel to join (e.g. incident)
|
|
1304
|
+
channel: z.string().describe("The channel to join (e.g. incident), or a family such as team.>."),
|
|
1263
1305
|
},
|
|
1264
1306
|
async run(agent, _config, { channel }) {
|
|
1307
|
+
const notName = notAChannelName(channel, "Nothing was joined.");
|
|
1308
|
+
if (notName !== undefined)
|
|
1309
|
+
return err(`Couldn't join: ${notName}`);
|
|
1265
1310
|
// Bound by the read ACL before touching the mesh — a clear refusal beats a broker/manager
|
|
1266
|
-
// rejection. (Auth mode also enforces this server-side; this is the friendly client gate.)
|
|
1267
|
-
|
|
1311
|
+
// rejection. (Auth mode also enforces this server-side; this is the friendly client gate.) A
|
|
1312
|
+
// pattern must lie inside one entry, so every channel it matches is readable.
|
|
1313
|
+
if (!(isConcreteChannel(channel) ? channelInAllow : patternInAllow)(config.allowSubscribe, channel))
|
|
1268
1314
|
return err(`Can't join #${channel}: it's outside your read ACL (allowSubscribe: ${config.allowSubscribe.map((c) => `#${c}`).join(", ")}).`);
|
|
1269
1315
|
try {
|
|
1270
1316
|
const r = await agent.joinChannel(channel);
|
|
@@ -1278,10 +1324,16 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
1278
1324
|
// (offline posts replay on your next turn). `durable:false` with a `reason` = a backstop was
|
|
1279
1325
|
// expected but is unavailable (e.g. no provisioner) — joined LIVE only; say so, never hide it.
|
|
1280
1326
|
// `durable:false` with no reason = a `live`-class channel (joined live is the contract).
|
|
1327
|
+
// A family's `durable` is its own row: each channel under it keeps its own class (#5404). A
|
|
1328
|
+
// pattern that is not a family has no stored copies, and its `reason` says so.
|
|
1281
1329
|
const headline = r.durable
|
|
1282
|
-
?
|
|
1330
|
+
? isChannelFamily(channel)
|
|
1331
|
+
? `Joined #${channel} (stored copies on: posts on its durable channels are kept for you while you're offline, from now on; its live channels reach you only while you're connected).`
|
|
1332
|
+
: `Joined #${channel} (durable backstop active — messages sent while you're offline replay on your next turn).`
|
|
1283
1333
|
: r.reason
|
|
1284
|
-
?
|
|
1334
|
+
? isConcreteChannel(channel) || isChannelFamily(channel)
|
|
1335
|
+
? `Joined #${channel} (LIVE only — ${r.reason}; messages sent while you're offline won't be replayed).`
|
|
1336
|
+
: `Joined #${channel} (live only: ${r.reason}).`
|
|
1285
1337
|
: `Joined #${channel} (live).`;
|
|
1286
1338
|
return ok(`${headline}\n${info}${caught}`);
|
|
1287
1339
|
}
|
|
@@ -1293,9 +1345,9 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
1293
1345
|
{
|
|
1294
1346
|
name: "cotal_leave",
|
|
1295
1347
|
title: "Cotal: leave a channel",
|
|
1296
|
-
description: "Unsubscribe from a channel mid-session; you stop receiving its messages. Leaving your LAST channel is allowed: you stay on the mesh, visible on the roster and reachable by DM and anycast, you just read no channel. You then have no default send channel, so cotal_send refuses a call with no channel until you join one.",
|
|
1348
|
+
description: "Unsubscribe from a channel or a family such as team.> mid-session; you stop receiving its messages, and a family's stored copies stop. Leaving your LAST channel is allowed: you stay on the mesh, visible on the roster and reachable by DM and anycast, you just read no channel. You then have no default send channel, so cotal_send refuses a call with no channel until you join one.",
|
|
1297
1349
|
schema: {
|
|
1298
|
-
channel: z.string().describe("The channel to leave."),
|
|
1350
|
+
channel: z.string().describe("The channel or family to leave."),
|
|
1299
1351
|
},
|
|
1300
1352
|
async run(agent, _config, { channel }) {
|
|
1301
1353
|
try {
|
|
@@ -1310,7 +1362,7 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
1310
1362
|
{
|
|
1311
1363
|
name: "cotal_spawn",
|
|
1312
1364
|
title: "Cotal: spawn a new teammate",
|
|
1313
|
-
description: "Ask the manager to start a new peer endpoint in your space. It joins the mesh as a lateral peer and, under the cmux runtime, appears in its own tab. A Cotal peer is a real, addressable process the user can watch; you can reach it by DM, find it on the roster, and coordinate with it later. Use it for teammate work that should stay visible on the mesh. Pass `prompt` when it should begin immediately; the connector auto-submits that prompt as its first turn. When you first bring a team online, if the live web dashboard is down, suggest `cotal watch` for a live terminal view. The dashboard service is configured and started separately; do not install or launch it implicitly. A partial result means the seat started but its requested model pin could not be read back: it names the seat and the `cotal ps --on <manager>` command that shows the pin, and spawning again would start a second agent. Channels: the new peer may read and post what its persona file allows; a persona that names no channel at all is scoped to your own allowances. It starts on NO channel unless you pass `join`, so pass the channel you are working on when it should see that traffic and post there (e.g. `join: [\"general\"]`).",
|
|
1365
|
+
description: "Ask the manager to start a new peer endpoint in your space. It joins the mesh as a lateral peer and, under the cmux runtime, appears in its own tab. A Cotal peer is a real, addressable process the user can watch; you can reach it by DM, find it on the roster, and coordinate with it later. Use it for teammate work that should stay visible on the mesh. Pass `prompt` when it should begin immediately; the connector auto-submits that prompt as its first turn. Pass `once: true` with a `prompt` to start a helper for one task: the peer gets the prompt as its only task and is stopped when it ends that turn, or at the deadline (one hour unless you pass `deadline`). When the spawn succeeds, its result names the task's goal; read its outcome with goal-result. A once task that ends without the peer ending its turn (its deadline passed, its handoff could not be confirmed, or the peer exited or never joined) may have run in part or in full, and nothing runs it again; whether to spawn it again is your call. Jcode, OpenCode, pi and Claude Code peers can take a once task. When you first bring a team online, if the live web dashboard is down, suggest `cotal watch` for a live terminal view. The dashboard service is configured and started separately; do not install or launch it implicitly. A partial result means the seat started but its requested model pin could not be read back: it names the seat and the `cotal ps --on <manager>` command that shows the pin, and spawning again would start a second agent. Channels: the new peer may read and post what its persona file allows; a persona that names no channel at all is scoped to your own allowances. It starts on NO channel unless you pass `join`, so pass the channel you are working on when it should see that traffic and post there (e.g. `join: [\"general\"]`).",
|
|
1314
1366
|
schema: {
|
|
1315
1367
|
name: z.string().describe("Which persona to spawn: the persona FILENAME in .cotal/agents (e.g. `review-critic`), without the .md. The new peer joins under the persona's own `name:` (auto-numbered with an underscore, e.g. socrates_2, if that's taken). Fails if no such persona file exists; spawn an existing persona, don't invent a name."),
|
|
1316
1368
|
join: z
|
|
@@ -1364,6 +1416,14 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
1364
1416
|
.boolean()
|
|
1365
1417
|
.optional()
|
|
1366
1418
|
.describe("Event planes are on by default for connectors that publish one. Pass false to opt out; true only restates the default."),
|
|
1419
|
+
once: z
|
|
1420
|
+
.boolean()
|
|
1421
|
+
.optional()
|
|
1422
|
+
.describe("Run `prompt` as the new peer's one task, then stop the peer. The task reaches the peer as a relayed turn rather than a kickoff, and the peer is stopped when it ends that turn or when the deadline passes. Needs `prompt`. A Claude Code peer takes the task only when its startup shows channels on; otherwise the spawn fails at startup and says why."),
|
|
1423
|
+
deadline: z
|
|
1424
|
+
.string()
|
|
1425
|
+
.optional()
|
|
1426
|
+
.describe("With once: how long the task may run, as a duration such as 30m, 2h or 1d, counted from when the manager accepts the spawn. Omitted, it is 1h. Pass -1 for no deadline: the peer then keeps its name and its seat slot until it ends its turn or is despawned."),
|
|
1367
1427
|
runtime: z
|
|
1368
1428
|
.string()
|
|
1369
1429
|
.trim()
|
|
@@ -1376,9 +1436,30 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
1376
1436
|
// boundary. Resume lives only on the operator CLI (`cotal spawn --resume`, foreground or
|
|
1377
1437
|
// --detach); a peer-facing, capability-gated resume is deferred (see #159).
|
|
1378
1438
|
},
|
|
1379
|
-
async run(agent, _config, { name, instance, role, agent: agentType, model, variant, launchOptions, cwd, prompt, events, runtime, join }) {
|
|
1439
|
+
async run(agent, _config, { name, instance, role, agent: agentType, model, variant, launchOptions, cwd, prompt, events, once, deadline, runtime, join }) {
|
|
1440
|
+
let onceArg;
|
|
1441
|
+
if (deadline !== undefined && once !== true)
|
|
1442
|
+
return err("`deadline` applies only to a once spawn; pass once: true with it.");
|
|
1443
|
+
if (once === true) {
|
|
1444
|
+
if (deadline === undefined)
|
|
1445
|
+
onceArg = {};
|
|
1446
|
+
else if (deadline.trim() === "-1")
|
|
1447
|
+
onceArg = { deadlineMs: -1 };
|
|
1448
|
+
else {
|
|
1449
|
+
let ms;
|
|
1450
|
+
try {
|
|
1451
|
+
ms = parseDuration(deadline);
|
|
1452
|
+
}
|
|
1453
|
+
catch (e) {
|
|
1454
|
+
return err(`deadline: ${e.message}, or -1 for no deadline`);
|
|
1455
|
+
}
|
|
1456
|
+
if (!Number.isSafeInteger(ms) || ms < 1)
|
|
1457
|
+
return err(`deadline: "${deadline}" is not a positive duration; pass one such as 30m, or -1 for no deadline`);
|
|
1458
|
+
onceArg = { deadlineMs: ms };
|
|
1459
|
+
}
|
|
1460
|
+
}
|
|
1380
1461
|
try {
|
|
1381
|
-
const reply = await agent.spawn(name, role, { agent: agentType, model, variant, launchOptions, cwd, prompt, events, runtime, instance, join });
|
|
1462
|
+
const reply = await agent.spawn(name, role, { agent: agentType, model, variant, launchOptions, cwd, prompt, events, runtime, instance, join, ...(onceArg !== undefined ? { once: onceArg } : {}) });
|
|
1382
1463
|
// An uncertain launch is still managed and may yet join. Reported as an error it reads as a
|
|
1383
1464
|
// failed launch, and the caller's retry starts a second agent on the same work.
|
|
1384
1465
|
const pending = reply.code === "uncertain";
|
|
@@ -1420,7 +1501,11 @@ export function cotalToolSpecs(config, source = "connector", env, offered, empty
|
|
|
1420
1501
|
}
|
|
1421
1502
|
if (pending)
|
|
1422
1503
|
return ok(`${lead}${pin} (id ${d?.actor}, manager ${d?.executor?.lifecycleUid}), but it did not join the mesh within its readiness window. It may still be booting, so do not spawn it again: a retry starts a second agent. Watch cotal_roster for ${actual}, and cotal_despawn it if it never joins.`);
|
|
1423
|
-
|
|
1504
|
+
// A once spawn names its task, so the spawner can read how it ended.
|
|
1505
|
+
const task = d?.once
|
|
1506
|
+
? ` Its task is goal ${JSON.stringify(d.once.goalId)}, ${d.once.deadlineAt !== undefined ? `with a deadline of ${new Date(d.once.deadlineAt).toISOString()}` : "with no deadline"}; it is stopped when the task ends. Read the outcome with cotal_invoke(endpoint="manager", command="goal-result", args={"goalId":${JSON.stringify(d.once.goalId)}}).`
|
|
1507
|
+
: "";
|
|
1508
|
+
return ok(`${lead}${mode ? ` (${mode})` : ""}${pin} — it will appear in the roster shortly.${task}`);
|
|
1424
1509
|
}
|
|
1425
1510
|
catch (e) {
|
|
1426
1511
|
return controlFailure(`Couldn't spawn ${name}`, e);
|