@cotal-ai/connector-core 0.133.13 → 0.135.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 +71 -4
- package/dist/agent.d.ts.map +1 -1
- package/dist/agent.js +228 -33
- package/dist/agent.js.map +1 -1
- package/dist/briefing.d.ts +27 -0
- package/dist/briefing.d.ts.map +1 -0
- package/dist/briefing.js +58 -0
- package/dist/briefing.js.map +1 -0
- package/dist/config.d.ts +1 -1
- package/dist/config.d.ts.map +1 -1
- package/dist/config.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.d.ts.map +1 -1
- package/dist/docs-bundle.generated.js +13 -6
- package/dist/docs-bundle.generated.js.map +1 -1
- package/dist/docs-index.bin +0 -0
- package/dist/gateway.d.ts.map +1 -1
- package/dist/gateway.js +6 -2
- package/dist/gateway.js.map +1 -1
- package/dist/index.d.ts +2 -0
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/manager-call.d.ts +7 -1
- package/dist/manager-call.d.ts.map +1 -1
- package/dist/manager-call.js +39 -1
- package/dist/manager-call.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 +11 -3
- package/dist/orientation.d.ts.map +1 -1
- package/dist/orientation.js +29 -8
- package/dist/orientation.js.map +1 -1
- package/dist/tool-specs.d.ts +14 -1
- package/dist/tool-specs.d.ts.map +1 -1
- package/dist/tool-specs.js +197 -50
- package/dist/tool-specs.js.map +1 -1
- package/package.json +3 -3
package/dist/agent.js
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
import { AsyncLocalStorage } from "node:async_hooks";
|
|
2
2
|
import { EventEmitter } from "node:events";
|
|
3
3
|
import { hostname } from "node:os";
|
|
4
|
-
import { normalizeMentions, RUN_LAUNCH_DEADLINE_MS, subjectMatches, isConcreteChannel, assertValidChannel, channelInAllow, eventChannelPrincipal, resolvePeer as resolvePeerInRoster, peerLabel, CotalEndpoint, acquireLocalConsumer, BASELINE_LIFECYCLE_ENDPOINT, BIND_SPLIT_REISSUES, assertLifecycleToken, EpEnvelopeError, isPublishPermissionDenied, unansweredRequest, EP_UNANSWERED, controlReplyFrom, controlReplyFromThrown, runAgentBearer, partsToText, assertValidRole, turnNoticeFilter, } from "@cotal-ai/core";
|
|
4
|
+
import { normalizeMentions, RUN_LAUNCH_DEADLINE_MS, subjectMatches, isConcreteChannel, isChannelFamily, assertValidChannel, channelInAllow, eventChannelPrincipal, resolvePeer as resolvePeerInRoster, peerLabel, CotalEndpoint, acquireLocalConsumer, BASELINE_LIFECYCLE_ENDPOINT, BIND_SPLIT_REISSUES, assertLifecycleToken, EpEnvelopeError, isPublishPermissionDenied, unansweredRequest, EP_UNANSWERED, controlReplyFrom, controlReplyFromThrown, runAgentBearer, partsToText, assertValidRole, turnNoticeFilter, renderOnceTask, } from "@cotal-ai/core";
|
|
5
5
|
import { TURN_PULL_RETRY_MS } from "./turn-poll.js";
|
|
6
|
+
import { ONCE_HANDOFF_MS, claimOnceHandoff, confirmOnceHandoff, endOnceHandoff, exitOnceSeat, onOnceHandoffTimeout, onceHandoffState, sealOnceHandoff, stopOnceHandoffTimer } from "./once.js";
|
|
6
7
|
import { attributionSafe } from "./framing.js";
|
|
7
|
-
import { invokeUserManager } from "./manager-call.js";
|
|
8
|
+
import { invokeUserManager, withUserManagerListing } from "./manager-call.js";
|
|
8
9
|
/** Client-side floor for a spawn action's submit + follow. The manager acceptance carries the exact
|
|
9
10
|
* connector-selected readiness budget, and core extends the follow through that budget plus
|
|
10
11
|
* delivery margin. This floor still outlives the manager's generic 30s default and protects
|
|
@@ -108,17 +109,35 @@ const STATIC_SLOT_OBSERVATION_DETAIL = "ai.cotal.manager.static-slot-observation
|
|
|
108
109
|
const MAX_SETTLED_TURNS = 32;
|
|
109
110
|
/** The refusal for a yield on a turn the run settled first, so a seat that was shown the turn
|
|
110
111
|
* learns why the run will not take its result instead of being told no turn exists. */
|
|
111
|
-
function settledTurnError(goalId,
|
|
112
|
-
|
|
112
|
+
function settledTurnError(goalId, t) {
|
|
113
|
+
const deadline = t.deadlineAt !== undefined ? ` (deadline ${new Date(t.deadlineAt).toISOString()})` : "";
|
|
114
|
+
return `turn "${goalId}" was already settled ${t.once !== undefined ? "by its manager" : "by the run"}${deadline}, so this yield was not recorded`;
|
|
113
115
|
}
|
|
114
116
|
/** Largest epoch-ms a `Date` can hold; past it `toISOString()` throws. */
|
|
115
117
|
const MAX_DATE_MS = 8.64e15;
|
|
116
|
-
/** A `turn-pending` row as the manager contract declares it, with a deadline a `Date` can format.
|
|
118
|
+
/** A `turn-pending` row as the manager contract declares it, with a deadline a `Date` can format.
|
|
119
|
+
* Only a once task's row may omit its deadline. */
|
|
117
120
|
function isPendingTurn(t) {
|
|
118
121
|
const r = t;
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
+
if (typeof r !== "object" || r === null || typeof r.goalId !== "string" || typeof r.payload !== "string")
|
|
123
|
+
return false;
|
|
124
|
+
if (!Number.isSafeInteger(r.acceptedAt) || r.acceptedAt < 0)
|
|
125
|
+
return false;
|
|
126
|
+
if (r.once !== undefined && r.once !== true)
|
|
127
|
+
return false;
|
|
128
|
+
if (r.deadlineAt === undefined)
|
|
129
|
+
return r.once === true;
|
|
130
|
+
return Number.isSafeInteger(r.deadlineAt) && r.deadlineAt >= 1 && r.deadlineAt <= MAX_DATE_MS;
|
|
131
|
+
}
|
|
132
|
+
/** Who a once task came from, as the manager wrote it beside the prompt. */
|
|
133
|
+
function onceSpawner(payload) {
|
|
134
|
+
try {
|
|
135
|
+
const spawner = JSON.parse(payload).once?.spawner;
|
|
136
|
+
return typeof spawner === "string" && spawner.length > 0 ? spawner : undefined;
|
|
137
|
+
}
|
|
138
|
+
catch {
|
|
139
|
+
return undefined;
|
|
140
|
+
}
|
|
122
141
|
}
|
|
123
142
|
import { createHash, randomUUID } from "node:crypto";
|
|
124
143
|
/** #662: what an id-less channel delivery shares with its stream copy. Both are the same published
|
|
@@ -233,6 +252,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
233
252
|
ep;
|
|
234
253
|
config;
|
|
235
254
|
launchEnv;
|
|
255
|
+
options;
|
|
236
256
|
inbox = [];
|
|
237
257
|
/** Ids already SURFACED to the model (handled) — bounded, commit-aware dedup ACROSS a drain. The
|
|
238
258
|
* live↔durable transition window can deliver the two copies of one message far enough apart that the
|
|
@@ -259,6 +279,9 @@ export class MeshAgent extends EventEmitter {
|
|
|
259
279
|
protectedPullOnlyIds = new Set();
|
|
260
280
|
protectedDropIds = new Set();
|
|
261
281
|
dropUnsafe = false;
|
|
282
|
+
/** How many times the endpoint saw this session's stored copies at their limit (#5404) since a
|
|
283
|
+
* cotal_inbox reply last carried the notice. */
|
|
284
|
+
_storedCopiesFull = 0;
|
|
262
285
|
_connected = false;
|
|
263
286
|
/** Raw NATS transport liveness, separate from `_connected` (the full Cotal bind/readiness). */
|
|
264
287
|
_transportConnected = false;
|
|
@@ -385,6 +408,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
385
408
|
constructor(config, env, options = {}) {
|
|
386
409
|
super();
|
|
387
410
|
this.config = config;
|
|
411
|
+
this.options = options;
|
|
388
412
|
this.launchEnv = env === undefined ? undefined : { ...env };
|
|
389
413
|
// Seed per-channel attention from the operator's file default (one-way: the runtime never writes
|
|
390
414
|
// back — the persona file is a shared template). muted/quiet are validated disjoint at file load.
|
|
@@ -437,6 +461,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
437
461
|
// A warning is a condition the endpoint is already surviving. Log it through the same bounded
|
|
438
462
|
// operator sink, but never turn it into connectionIssue: readiness is still true.
|
|
439
463
|
this.ep.on("warning", (e) => this.handleEndpointWarning(e));
|
|
464
|
+
this.ep.on("stored-copies-full", () => { this._storedCopiesFull++; });
|
|
440
465
|
// Two guards, and the comments sit out here so neither anchors a mutation on prose. An
|
|
441
466
|
// in-flight initial bind or rebuild can finish after stop() cleared local state, and shutdown is
|
|
442
467
|
// terminal for this MeshAgent, so a late endpoint edge must not resurrect transport. Separately,
|
|
@@ -575,6 +600,17 @@ export class MeshAgent extends EventEmitter {
|
|
|
575
600
|
get stopping() {
|
|
576
601
|
return this._stopping;
|
|
577
602
|
}
|
|
603
|
+
/** How many times this session's stored copies reached their limit since a cotal_inbox reply last
|
|
604
|
+
* said so, so older channel posts may have been dropped before they reached it (#5404). Zero when
|
|
605
|
+
* there is nothing to say. */
|
|
606
|
+
get storedCopiesFull() {
|
|
607
|
+
return this._storedCopiesFull;
|
|
608
|
+
}
|
|
609
|
+
/** A reply carrying the stored-copy notice went out, read when the count was `seen`. Clear what
|
|
610
|
+
* it covered; a limit seen while that reply was being built stays for the next one. */
|
|
611
|
+
clearStoredCopiesFull(seen) {
|
|
612
|
+
this._storedCopiesFull = Math.max(0, this._storedCopiesFull - seen);
|
|
613
|
+
}
|
|
578
614
|
/** Session-local channel degradation, independent of transport liveness. */
|
|
579
615
|
get channelDeliveryIssue() {
|
|
580
616
|
return this.dropUnsafe
|
|
@@ -1605,7 +1641,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
1605
1641
|
pendingWake(skip) {
|
|
1606
1642
|
// An unsurfaced run turn is directed-strength: it wakes regardless of attention, exactly like
|
|
1607
1643
|
// a DM — a run is waiting on this seat, and holding it costs the run its deadline.
|
|
1608
|
-
const turns = [...this.activeTurns.values()].filter((t) => !t.surfaced).length;
|
|
1644
|
+
const turns = [...this.activeTurns.values()].filter((t) => !t.surfaced && this.offerable(t)).length;
|
|
1609
1645
|
return turns + this.inboxWake(skip);
|
|
1610
1646
|
}
|
|
1611
1647
|
/** The inbox half of {@link pendingWake}: buffered items that should wake the agent, without run
|
|
@@ -2005,17 +2041,35 @@ export class MeshAgent extends EventEmitter {
|
|
|
2005
2041
|
* runtime; from here it just joins the mesh as a lateral peer. `opts.agent` picks
|
|
2006
2042
|
* the harness (absent it, the persona's `agent:` pin, else the manager's default), `opts.model` /
|
|
2007
2043
|
* `opts.variant` override the persona file's model selectors, `opts.prompt` submits the new
|
|
2008
|
-
* peer's first turn, `opts.runtime` chooses the terminal runtime of this one seat, and `opts.cwd` roots it at a different folder/repo
|
|
2044
|
+
* peer's first turn (or, with `opts.once`, is its one task, after which the manager stops it), `opts.runtime` chooses the terminal runtime of this one seat, and `opts.cwd` roots it at a different folder/repo
|
|
2009
2045
|
* than the manager's workspace — the same knobs the operator's `cotal spawn --detach` carries, so
|
|
2010
2046
|
* the agent and operator spawn doors share one control-op contract. (Session `resume` is
|
|
2011
2047
|
* intentionally NOT forwarded here: forking a host-local `~/.claude` transcript is an
|
|
2012
|
-
* operator-local intent, kept off the peer-facing spawn door — see #159.)
|
|
2048
|
+
* operator-local intent, kept off the peer-facing spawn door — see #159.)
|
|
2049
|
+
*
|
|
2050
|
+
* Channels: `opts.join` names concrete channels the new peer joins on top of its persona's read
|
|
2051
|
+
* set, each checked here against THIS agent's read ACL before anything is sent (a spawn never
|
|
2052
|
+
* widens). The request also carries this agent's own read/post ACL as `callerAcl`; the manager
|
|
2053
|
+
* consults it only for a persona that names no channel field, so such a helper is scoped to its
|
|
2054
|
+
* spawner. The joined set is never copied: without `join`, a channel-less persona starts on none. */
|
|
2013
2055
|
async spawn(name, role, opts) {
|
|
2014
2056
|
await this.requireConnected();
|
|
2015
2057
|
const raw = opts?.model;
|
|
2016
2058
|
if (raw !== undefined && !raw.trim())
|
|
2017
2059
|
return { ok: false, error: "model: must not be empty" };
|
|
2018
2060
|
const requested = raw?.trim();
|
|
2061
|
+
for (const ch of opts?.join ?? []) {
|
|
2062
|
+
try {
|
|
2063
|
+
assertValidChannel(ch);
|
|
2064
|
+
}
|
|
2065
|
+
catch (e) {
|
|
2066
|
+
return { ok: false, error: `join: ${e.message}` };
|
|
2067
|
+
}
|
|
2068
|
+
if (!isConcreteChannel(ch))
|
|
2069
|
+
return { ok: false, error: `join: "${ch}" must be a concrete channel (no wildcard)` };
|
|
2070
|
+
if (!channelInAllow(this.config.allowSubscribe, ch))
|
|
2071
|
+
return { ok: false, error: `join: "${ch}" is not within your read ACL (allowSubscribe) [${this.config.allowSubscribe.join(", ")}]; a spawn can only hand on channels you may read yourself` };
|
|
2072
|
+
}
|
|
2019
2073
|
let instance;
|
|
2020
2074
|
try {
|
|
2021
2075
|
const selected = opts?.instance ?? this.openManagerInstance();
|
|
@@ -2026,7 +2080,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
2026
2080
|
}
|
|
2027
2081
|
if (this.config.userAuth && instance !== undefined && this.config.managerInstanceId !== undefined && instance !== this.config.managerInstanceId)
|
|
2028
2082
|
return { ok: false, error: "the requested manager instance differs from this credential's instance authority" };
|
|
2029
|
-
const args = { name, role, agent: opts?.agent, model: requested || undefined, variant: opts?.variant, launchOptions: opts?.launchOptions, cwd: opts?.cwd, prompt: opts?.prompt, events: opts?.events, runtime: opts?.runtime };
|
|
2083
|
+
const args = { name, role, agent: opts?.agent, model: requested || undefined, variant: opts?.variant, launchOptions: opts?.launchOptions, cwd: opts?.cwd, prompt: opts?.prompt, events: opts?.events, runtime: opts?.runtime, join: opts?.join, callerAcl: { allowSubscribe: this.config.allowSubscribe, allowPublish: this.config.allowPublish }, once: opts?.once };
|
|
2030
2084
|
// P2 item 2 (2b): spawn is an ACTION — follow the acceptance to the terminal so cotal_spawn
|
|
2031
2085
|
// stays synchronous (the MCP reply carries the live outcome, not the pre-launch acceptance).
|
|
2032
2086
|
const reply = await this.managerInvoke("spawn", args, { deadlineMs: SPAWN_TIMEOUT_MS, follow: true, ...(instance !== undefined ? { instanceId: instance } : {}) });
|
|
@@ -2095,6 +2149,23 @@ export class MeshAgent extends EventEmitter {
|
|
|
2095
2149
|
return { ok: false, error: `inspect returned a non-string model for "${name}"` };
|
|
2096
2150
|
return { ok: true, model };
|
|
2097
2151
|
}
|
|
2152
|
+
/** The registry listing as this session's manager-call credential sees it (SPEC 13.20), asked
|
|
2153
|
+
* over a connection opened on that credential and described on this session's own. On a static
|
|
2154
|
+
* mesh manager calls ride this session's credential, and a host-issued bearer has no manager-call
|
|
2155
|
+
* credential: `none` says which. `unbound`: that credential carries no listing binding. */
|
|
2156
|
+
async listManagerEndpoints(input, instance) {
|
|
2157
|
+
const user = this.config.userAuth;
|
|
2158
|
+
if (!user)
|
|
2159
|
+
return { none: "manager calls ride this session's own credential on this mesh, so the session view covers them" };
|
|
2160
|
+
if (!user.bearerCmd)
|
|
2161
|
+
return { none: "this session's bearer comes from its host, which issues no manager-call bearer, so the manager view has no credential" };
|
|
2162
|
+
const managerInstanceId = instance ?? this.config.managerInstanceId;
|
|
2163
|
+
const token = await this.managerCallBearer([...user.bearerCmd, "--manager-call", ...(managerInstanceId ? ["--manager-instance", managerInstanceId] : [])]).catch((e) => {
|
|
2164
|
+
throw e instanceof Error ? new Error(e.message.replace("--manager-instance <instanceId>", "the instance argument")) : e;
|
|
2165
|
+
});
|
|
2166
|
+
const exp = bearerExpiryMs(token);
|
|
2167
|
+
return withUserManagerListing({ ...this.config, managerInstanceId }, token, exp === undefined ? undefined : exp / 1000, async (nc, listing) => listing === undefined ? { unbound: true } : this.ep.listEndpointsOver(nc, listing, input));
|
|
2168
|
+
}
|
|
2098
2169
|
/** Manager-call bearers this session holds, by the exact bearer argv (so by selected manager;
|
|
2099
2170
|
* the space, owner, actor and lifecycle are this session's own). One exchange serves every call
|
|
2100
2171
|
* until {@link MANAGER_BEARER_MARGIN_MS} before the bearer expires, and concurrent calls share it.
|
|
@@ -2405,6 +2476,12 @@ export class MeshAgent extends EventEmitter {
|
|
|
2405
2476
|
armTurnRelay() {
|
|
2406
2477
|
if (!this.hasTurnRelay())
|
|
2407
2478
|
return;
|
|
2479
|
+
// A once task whose dispatch outlived its bound is sealed and reported by this seat's newest
|
|
2480
|
+
// MeshAgent, which is the one connected.
|
|
2481
|
+
onOnceHandoffTimeout((uid, goalId) => {
|
|
2482
|
+
if (uid === this.onceUid() && sealOnceHandoff(uid, goalId))
|
|
2483
|
+
void this.reportUnconfirmed(goalId);
|
|
2484
|
+
});
|
|
2408
2485
|
if (!this.turnNoticeArmed) {
|
|
2409
2486
|
let caller;
|
|
2410
2487
|
try {
|
|
@@ -2473,11 +2550,23 @@ export class MeshAgent extends EventEmitter {
|
|
|
2473
2550
|
for (const t of turns) {
|
|
2474
2551
|
if (this.activeTurns.has(t.goalId) || this.yieldedSincePull.has(t.goalId))
|
|
2475
2552
|
continue;
|
|
2476
|
-
|
|
2477
|
-
|
|
2553
|
+
// A once task this process already handed over stays handed over: a rebuilt MeshAgent
|
|
2554
|
+
// finds its state in the process registry and neither offers it again nor loses its yield.
|
|
2555
|
+
const once = t.once ? { spawner: onceSpawner(t.payload) } : undefined;
|
|
2556
|
+
const surfaced = once !== undefined && onceHandoffState(this.onceUid(), t.goalId) === "confirmed";
|
|
2557
|
+
this.activeTurns.set(t.goalId, { goalId: t.goalId, payload: t.payload, acceptedAt: t.acceptedAt, ...(t.deadlineAt !== undefined ? { deadlineAt: t.deadlineAt } : {}), ...(once ? { once } : {}), surfaced });
|
|
2558
|
+
if (!surfaced)
|
|
2559
|
+
fresh += 1;
|
|
2560
|
+
if (once !== undefined && !surfaced && this.options.onceClaimBound)
|
|
2561
|
+
this.boundOnceClaim(t.goalId);
|
|
2478
2562
|
}
|
|
2479
2563
|
if (fresh > 0)
|
|
2480
2564
|
this.requestWake();
|
|
2565
|
+
// A manager that does not hold this once seat, and has settled its task, tells it to end itself.
|
|
2566
|
+
if (r.data.stop === true) {
|
|
2567
|
+
this.log("the manager does not hold this once seat and its task has ended; ending this seat");
|
|
2568
|
+
void exitOnceSeat();
|
|
2569
|
+
}
|
|
2481
2570
|
}
|
|
2482
2571
|
finally {
|
|
2483
2572
|
this.turnPollBusy = false;
|
|
@@ -2546,9 +2635,13 @@ export class MeshAgent extends EventEmitter {
|
|
|
2546
2635
|
// A turn past its deadline is already settled at the manager, which refuses its yield, though
|
|
2547
2636
|
// this cache holds it until the next pull settles it here.
|
|
2548
2637
|
const now = Date.now();
|
|
2549
|
-
const waiting = [...this.activeTurns.values()].filter((t) => !t.surfaced && t.deadlineAt > now).sort((a, b) => a.acceptedAt - b.acceptedAt);
|
|
2638
|
+
const waiting = [...this.activeTurns.values()].filter((t) => !t.surfaced && (t.deadlineAt === undefined || t.deadlineAt > now) && this.offerable(t)).sort((a, b) => a.acceptedAt - b.acceptedAt);
|
|
2550
2639
|
if (!waiting.length)
|
|
2551
2640
|
return undefined;
|
|
2641
|
+
// A once seat holds its task and nothing else (the manager refuses it any other turn).
|
|
2642
|
+
const once = waiting.find((t) => t.once !== undefined);
|
|
2643
|
+
if (once !== undefined)
|
|
2644
|
+
return { text: renderOnceTask({ goalId: once.goalId, payload: once.payload, spawner: once.once?.spawner, deadlineAt: once.deadlineAt }), goalIds: [once.goalId], once: true };
|
|
2552
2645
|
const blocks = waiting.map((t) => {
|
|
2553
2646
|
let context = t.payload;
|
|
2554
2647
|
let ask = "";
|
|
@@ -2559,7 +2652,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
2559
2652
|
ask = renderAskRequest(p);
|
|
2560
2653
|
}
|
|
2561
2654
|
catch { /* opaque payload — surface it as it came */ }
|
|
2562
|
-
return `— turn ${t.goalId} (deadline ${new Date(t.deadlineAt).toISOString()}):\n${context}${ask}`;
|
|
2655
|
+
return `— turn ${t.goalId}${t.deadlineAt !== undefined ? ` (deadline ${new Date(t.deadlineAt).toISOString()})` : ""}:\n${context}${ask}`;
|
|
2563
2656
|
});
|
|
2564
2657
|
const text = `🎯 Cotal — a run handed you ${waiting.length === 1 ? "its turn" : `${waiting.length} turns`}:\n` +
|
|
2565
2658
|
`${blocks.join("\n")}\n` +
|
|
@@ -2575,10 +2668,90 @@ export class MeshAgent extends EventEmitter {
|
|
|
2575
2668
|
return;
|
|
2576
2669
|
for (const id of goalIds) {
|
|
2577
2670
|
const t = this.activeTurns.get(id);
|
|
2671
|
+
// A sealed once task is not surfaced: its handoff ended unconfirmed and has been reported.
|
|
2672
|
+
if (t?.once !== undefined && !confirmOnceHandoff(this.onceUid(), id))
|
|
2673
|
+
continue;
|
|
2578
2674
|
if (t)
|
|
2579
2675
|
t.surfaced = true;
|
|
2580
2676
|
}
|
|
2581
2677
|
}
|
|
2678
|
+
/** Take the permit to hand these turns to the harness, at the dispatch site, after every gate
|
|
2679
|
+
* that can return without sending and right before the native send, with no await between. All
|
|
2680
|
+
* or nothing for the once task among them: false means another caller holds it or its handoff
|
|
2681
|
+
* already ended, and the caller sends no once task. Run turns need no permit and are offered
|
|
2682
|
+
* again as before. */
|
|
2683
|
+
claimTurns(goalIds) {
|
|
2684
|
+
// A once task settled since the caller's peek is still a once task: its handoff has ended, and
|
|
2685
|
+
// it takes no permit.
|
|
2686
|
+
return claimOnceHandoff(this.onceUid(), goalIds.filter((id) => (this.activeTurns.get(id) ?? this.settledTurns.get(id))?.once !== undefined));
|
|
2687
|
+
}
|
|
2688
|
+
/** The adapter gave up on a dispatch that carried these turns. A claimed once task is sealed and
|
|
2689
|
+
* reported to the manager; it is never offered again, because the harness may have it. */
|
|
2690
|
+
releaseTurns(goalIds) {
|
|
2691
|
+
for (const id of goalIds) {
|
|
2692
|
+
if (this.activeTurns.get(id)?.once === undefined)
|
|
2693
|
+
continue;
|
|
2694
|
+
if (sealOnceHandoff(this.onceUid(), id))
|
|
2695
|
+
void this.reportUnconfirmed(id);
|
|
2696
|
+
}
|
|
2697
|
+
}
|
|
2698
|
+
/** The dispatch carrying these turns left the seat, and its acceptance arrives with the model's
|
|
2699
|
+
* response: stop the once task's handoff timer, which measures the dispatch only. */
|
|
2700
|
+
noteTurnsDispatched(goalIds) {
|
|
2701
|
+
for (const id of goalIds)
|
|
2702
|
+
if (this.activeTurns.get(id)?.once !== undefined)
|
|
2703
|
+
stopOnceHandoffTimer(this.onceUid(), id);
|
|
2704
|
+
}
|
|
2705
|
+
/** Seal and report a once task still unclaimed {@link ONCE_HANDOFF_MS} after this seat pulled it. */
|
|
2706
|
+
boundOnceClaim(goalId) {
|
|
2707
|
+
const timer = setTimeout(() => {
|
|
2708
|
+
if (!this.activeTurns.has(goalId) || onceHandoffState(this.onceUid(), goalId) !== "pending")
|
|
2709
|
+
return;
|
|
2710
|
+
this.log(`once task ${goalId}: pulled ${ONCE_HANDOFF_MS}ms ago and never handed to the session; reporting it unconfirmed`);
|
|
2711
|
+
if (this.claimTurns([goalId]))
|
|
2712
|
+
this.releaseTurns([goalId]);
|
|
2713
|
+
}, ONCE_HANDOFF_MS);
|
|
2714
|
+
timer.unref?.();
|
|
2715
|
+
}
|
|
2716
|
+
/** A turn the harness may be handed: any run turn, and a once task whose handoff has not begun. */
|
|
2717
|
+
offerable(t) {
|
|
2718
|
+
return t.once === undefined || onceHandoffState(this.onceUid(), t.goalId) === "pending";
|
|
2719
|
+
}
|
|
2720
|
+
/** The key a once task's handoff state is kept under in this process. */
|
|
2721
|
+
onceUid() {
|
|
2722
|
+
return this.config.lifecycleUid ?? this.config.name;
|
|
2723
|
+
}
|
|
2724
|
+
/** Tell the manager a once task's handoff was not confirmed (`turn-unconfirmed`), so it fails the
|
|
2725
|
+
* task and stops this seat. Retried with backoff for one handoff bound while the manager cannot
|
|
2726
|
+
* be reached; any answer that is not transient ends the retry. A report that has not landed by
|
|
2727
|
+
* then ends this seat instead, and the manager's proof of that exit settles the task. A seat that
|
|
2728
|
+
* cannot end itself keeps reporting, at most a minute apart, until a manager answers or this
|
|
2729
|
+
* process ends. */
|
|
2730
|
+
async reportUnconfirmed(goalId) {
|
|
2731
|
+
const until = Date.now() + ONCE_HANDOFF_MS;
|
|
2732
|
+
let delay = 1_000;
|
|
2733
|
+
let exitTried = false;
|
|
2734
|
+
for (;;) {
|
|
2735
|
+
const r = await this.managerInvoke("turn-unconfirmed", { goalId }, { target: { mode: "self" } })
|
|
2736
|
+
.catch((e) => ({ ok: false, error: e.message, code: undefined }));
|
|
2737
|
+
const transient = !r.ok && (r.code === undefined || r.code === "unavailable" || r.code === "deadline-exceeded");
|
|
2738
|
+
if (!transient) {
|
|
2739
|
+
this.log(`once task ${goalId}: its handoff was not confirmed; reported to the manager (${r.ok ? "the task failed" : r.error ?? "refused"})`);
|
|
2740
|
+
return;
|
|
2741
|
+
}
|
|
2742
|
+
if (!exitTried && Date.now() + delay > until) {
|
|
2743
|
+
exitTried = true;
|
|
2744
|
+
this.log(`once task ${goalId}: its handoff was not confirmed and the manager could not be told; ending this seat so its exit settles the task`);
|
|
2745
|
+
if (await exitOnceSeat())
|
|
2746
|
+
return;
|
|
2747
|
+
this.log(`once task ${goalId}: this seat cannot end itself; reporting until a manager answers`);
|
|
2748
|
+
}
|
|
2749
|
+
if (this._stopping)
|
|
2750
|
+
return;
|
|
2751
|
+
await new Promise((resolve) => setTimeout(resolve, delay));
|
|
2752
|
+
delay = Math.min(delay * 2, exitTried ? 60_000 : 10_000);
|
|
2753
|
+
}
|
|
2754
|
+
}
|
|
2582
2755
|
/** Yield one active turn back to the run (`turn-yield`, self-mode). Without `turn` it targets
|
|
2583
2756
|
* the OLDEST surfaced turn — the one the current session turn is working on. The entry is
|
|
2584
2757
|
* dropped locally only when the manager's answer settles it, by this yield or by a terminal
|
|
@@ -2598,9 +2771,9 @@ export class MeshAgent extends EventEmitter {
|
|
|
2598
2771
|
: [...this.activeTurns.values()].filter((x) => x.surfaced).sort((a, b) => a.acceptedAt - b.acceptedAt)[0];
|
|
2599
2772
|
if (!t) {
|
|
2600
2773
|
const id = opts.turn ?? [...this.settledTurns.keys()].at(-1);
|
|
2601
|
-
const
|
|
2602
|
-
if (id !== undefined &&
|
|
2603
|
-
return { ok: false, error: settledTurnError(id,
|
|
2774
|
+
const settled = id === undefined ? undefined : this.settledTurns.get(id);
|
|
2775
|
+
if (id !== undefined && settled !== undefined)
|
|
2776
|
+
return { ok: false, error: settledTurnError(id, settled) };
|
|
2604
2777
|
return { ok: false, error: opts.turn !== undefined ? `no active turn "${opts.turn}" on this seat` : "no turn is active — nothing to yield" };
|
|
2605
2778
|
}
|
|
2606
2779
|
// The surfaced gate holds for an explicit id too: a yield for a payload the session has not
|
|
@@ -2617,7 +2790,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
2617
2790
|
// only `succeeded` is a yield that landed.
|
|
2618
2791
|
if (r.data?.state !== "succeeded") {
|
|
2619
2792
|
this.settleTurn(t);
|
|
2620
|
-
return { ok: false, error: settledTurnError(t.goalId, t
|
|
2793
|
+
return { ok: false, error: settledTurnError(t.goalId, t) };
|
|
2621
2794
|
}
|
|
2622
2795
|
this.activeTurns.delete(t.goalId);
|
|
2623
2796
|
// A poll that ran while this yield was in flight saw the turn gone and took it for the run's
|
|
@@ -2627,8 +2800,11 @@ export class MeshAgent extends EventEmitter {
|
|
|
2627
2800
|
}
|
|
2628
2801
|
/** Drop an active turn the run settled without this seat's yield, remembering its deadline. */
|
|
2629
2802
|
settleTurn(t) {
|
|
2803
|
+
// A once task settled without this seat (its deadline, or a stop) ends its handoff too.
|
|
2804
|
+
if (t.once !== undefined)
|
|
2805
|
+
endOnceHandoff(this.onceUid(), t.goalId);
|
|
2630
2806
|
this.activeTurns.delete(t.goalId);
|
|
2631
|
-
this.settledTurns.set(t.goalId, t.deadlineAt);
|
|
2807
|
+
this.settledTurns.set(t.goalId, { ...(t.deadlineAt !== undefined ? { deadlineAt: t.deadlineAt } : {}), ...(t.once !== undefined ? { once: true } : {}) });
|
|
2632
2808
|
if (this.settledTurns.size > MAX_SETTLED_TURNS)
|
|
2633
2809
|
this.settledTurns.delete(this.settledTurns.keys().next().value);
|
|
2634
2810
|
}
|
|
@@ -2948,7 +3124,9 @@ export class MeshAgent extends EventEmitter {
|
|
|
2948
3124
|
}
|
|
2949
3125
|
/** Discoverable channel list: every channel with traffic or a registry entry, tagged with
|
|
2950
3126
|
* its one-line description, replay policy, and whether WE are subscribed (self only — never
|
|
2951
|
-
* other peers' membership). The companion to cotal_join.
|
|
3127
|
+
* other peers' membership). The companion to cotal_join. Each pattern WE follow is a row too,
|
|
3128
|
+
* marked `follow`: a family (`team.>`) with the health of its own stored copies, any other pattern
|
|
3129
|
+
* as live only. */
|
|
2952
3130
|
async listChannels() {
|
|
2953
3131
|
const mine = this.ep.joinedChannels();
|
|
2954
3132
|
const pending = this.ep.pendingDurableLeaves();
|
|
@@ -2990,18 +3168,19 @@ export class MeshAgent extends EventEmitter {
|
|
|
2990
3168
|
// be established (the reader lacks the grant, or the responder errored) renders "unknown",
|
|
2991
3169
|
// distinct from the degraded of a daemon that answered but holds no membership for this owner —
|
|
2992
3170
|
// and from the undefined of a channel where health does not apply (not durable-class, not
|
|
2993
|
-
// joined, open mode).
|
|
2994
|
-
|
|
2995
|
-
|
|
2996
|
-
|
|
2997
|
-
|
|
2998
|
-
|
|
2999
|
-
|
|
3000
|
-
|
|
3001
|
-
|
|
3002
|
-
|
|
3171
|
+
// joined, open mode). A channel or family is held by its own row or a family row above it (#5404),
|
|
3172
|
+
// since that family's stored copies cover it.
|
|
3173
|
+
const held = (channel) => !leaseReadable
|
|
3174
|
+
? "unknown"
|
|
3175
|
+
: daemonMemberships !== undefined && leaseLive && daemonMemberships.some((m) => m.channel === channel || (isChannelFamily(m.channel) && subjectMatches(m.channel, channel)))
|
|
3176
|
+
? "active"
|
|
3177
|
+
: "degraded";
|
|
3178
|
+
// Health applies where stored copies were asked for: the channel itself or a family over it. A
|
|
3179
|
+
// channel read only through a pattern with * or the root > is live only and has none.
|
|
3180
|
+
const health = (channel, stored) => stored && this.ep.channelDeliveryClass(channel) === "durable" ? held(channel) : undefined;
|
|
3003
3181
|
const rows = (await this.ep.listChannels()).map((c) => {
|
|
3004
3182
|
const joined = mine.some((p) => subjectMatches(p, c.channel));
|
|
3183
|
+
const stored = mine.some((p) => p === c.channel || (isChannelFamily(p) && subjectMatches(p, c.channel)));
|
|
3005
3184
|
return {
|
|
3006
3185
|
channel: c.channel,
|
|
3007
3186
|
description: c.config?.description,
|
|
@@ -3010,12 +3189,27 @@ export class MeshAgent extends EventEmitter {
|
|
|
3010
3189
|
// A live sub was refused while a Plane-3 durable membership stayed open; its §7 tombstone is
|
|
3011
3190
|
// still retrying. Surface it so the channel is never shown as ordinary "not subscribed" (ux).
|
|
3012
3191
|
durableUnclosed: unclosed.has(c.channel),
|
|
3013
|
-
deliveryHealth: health(c.channel,
|
|
3192
|
+
deliveryHealth: health(c.channel, stored),
|
|
3014
3193
|
messages: c.messages,
|
|
3015
3194
|
mode: this.channelMode(c.channel) ?? "normal",
|
|
3016
3195
|
event: this.eventChannelOf(c.channel),
|
|
3017
3196
|
};
|
|
3018
3197
|
});
|
|
3198
|
+
for (const pattern of mine) {
|
|
3199
|
+
if (isConcreteChannel(pattern))
|
|
3200
|
+
continue;
|
|
3201
|
+
const family = isChannelFamily(pattern);
|
|
3202
|
+
rows.push({
|
|
3203
|
+
channel: pattern,
|
|
3204
|
+
replay: this.ep.channelReplay(pattern),
|
|
3205
|
+
joined: true,
|
|
3206
|
+
durableUnclosed: unclosed.has(pattern),
|
|
3207
|
+
deliveryHealth: family ? held(pattern) : undefined,
|
|
3208
|
+
messages: 0,
|
|
3209
|
+
mode: "normal",
|
|
3210
|
+
follow: family ? "family" : "live",
|
|
3211
|
+
});
|
|
3212
|
+
}
|
|
3019
3213
|
// A channel in refused-sub durable cleanup can have NO traffic AND no registry entry, so listChannels()
|
|
3020
3214
|
// omits it — UNION it in so the durable-unclosed state can never disappear by omission (ux/security).
|
|
3021
3215
|
const present = new Set(rows.map((r) => r.channel));
|
|
@@ -3032,6 +3226,7 @@ export class MeshAgent extends EventEmitter {
|
|
|
3032
3226
|
messages: 0,
|
|
3033
3227
|
mode: this.channelMode(ch) ?? "normal",
|
|
3034
3228
|
event: this.eventChannelOf(ch),
|
|
3229
|
+
...(isChannelFamily(ch) ? { follow: "family" } : {}),
|
|
3035
3230
|
});
|
|
3036
3231
|
}
|
|
3037
3232
|
return rows;
|