@awebai/oats 0.69.22 → 0.69.24
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/bin/oats.mjs +185 -38
- package/docs/capabilities.md +365 -7
- package/docs/capability-manifest.schema.json +37 -1
- package/docs/configuration.md +27 -7
- package/docs/container.md +206 -228
- package/docs/design/2026-11-19-sandboxes.md +1352 -0
- package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
- package/docs/design/README.md +7 -0
- package/docs/desktop-cli-api.md +673 -81
- package/docs/desktop.md +241 -65
- package/docs/execution-targets.md +186 -3
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +6 -2
- package/docs/integrations.md +3 -3
- package/docs/knowledge-capability-authoring.md +10 -7
- package/docs/knowledge-reference/acceptance.md +21 -19
- package/docs/knowledge-reference/adoption.md +18 -4
- package/docs/knowledge-reference/model.md +11 -9
- package/docs/knowledge-reference/package-craft.md +2 -2
- package/docs/knowledge-reference/proposal.md +127 -0
- package/docs/knowledge-reference/provider-mapping.md +10 -10
- package/docs/knowledge-reference/reader-capture.md +26 -22
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -16
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +13 -13
- package/docs/release-notes/v0.69.23.md +231 -0
- package/docs/release-notes/v0.69.24.md +264 -0
- package/docs/servers.md +10 -6
- package/docs/souls-and-instances.md +96 -22
- package/docs/tui.md +25 -4
- package/docs/upgrading.md +19 -5
- package/docs/workspaces.md +14 -6
- package/lib/argv.mjs +6 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/capability-show.mjs +11 -1
- package/lib/command-flags.mjs +40 -3
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1201 -195
- package/lib/errors.mjs +4 -1
- package/lib/hook-env.mjs +106 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-board.mjs +337 -0
- package/lib/instance-events.mjs +48 -10
- package/lib/instance-inspect.mjs +44 -0
- package/lib/instance-lifecycle.mjs +34 -18
- package/lib/instance-listing.mjs +113 -16
- package/lib/instance-related-work.mjs +143 -0
- package/lib/kernel-features.mjs +13 -1
- package/lib/node-version.mjs +9 -0
- package/lib/provider-call-child.mjs +60 -0
- package/lib/provider-resume.mjs +83 -0
- package/lib/provider-test-seams.mjs +20 -0
- package/lib/read-call.mjs +2 -0
- package/lib/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +5 -1
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +151 -17
- package/lib/session-inspect.mjs +104 -13
- package/lib/session-providers.mjs +528 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- package/package-catalog.json +3 -3
- package/package.json +2 -1
- package/packages/client/capability-list.mjs +21 -0
- package/packages/client/cli-adapter.mjs +19 -4
- package/packages/client/cli-locator.mjs +5 -1
- package/packages/client/deployment-data.mjs +27 -3
- package/packages/client/deployment-panel.mjs +27 -4
- package/packages/client/home-board.mjs +33 -19
- package/packages/client/inspect-boundary.mjs +18 -8
- package/packages/client/instance-acts.mjs +30 -3
- package/packages/client/instance-board.mjs +206 -0
- package/packages/client/instance-presentation.mjs +55 -0
- package/packages/client/instance-tree.mjs +34 -4
- package/packages/client/keymap.mjs +5 -0
- package/packages/client/liveness.mjs +15 -4
- package/packages/client/mail-contract.mjs +130 -0
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/panel-views.mjs +7 -7
- package/packages/client/related-work.mjs +84 -0
- package/packages/client/remote-roster.mjs +9 -3
- package/packages/client/session-backends.mjs +31 -0
- package/packages/client/session-start.mjs +18 -6
- package/packages/client/spawn-apply-cli.mjs +5 -3
- package/packages/client/spawn-apply-contract.mjs +25 -2
- package/packages/client/spawn-apply.mjs +5 -1
- package/packages/client/spawn-messages.mjs +3 -0
- package/packages/client/terminal-contract.mjs +4 -0
- package/packages/client/waiting-on-you.mjs +12 -2
- package/packages/client/workspace-cli.mjs +13 -2
- package/packages/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- package/skills/oats-getting-started/SKILL.md +11 -8
- package/docs/knowledge-reference/harvester.md +0 -109
- package/lib/instance-same-work.mjs +0 -67
- package/packages/client/same-work.mjs +0 -49
package/lib/instance-events.mjs
CHANGED
|
@@ -25,7 +25,9 @@
|
|
|
25
25
|
*
|
|
26
26
|
* Producers write claims as `waiting` rows through `setWaiting` (the CLI's
|
|
27
27
|
* `oats instance waiting` and `oats instance attention`): data
|
|
28
|
-
* `{waitingOnYou, reason?, message?}`, appended only on a change
|
|
28
|
+
* `{waitingOnYou, reason?, message?, session?}`, appended only on a change; `session`
|
|
29
|
+
* (the board's claim, lib/instance-board.mjs) binds a positive claim to the session it was
|
|
30
|
+
* derived in, so it never counts in another (claimsOf). A claim
|
|
29
31
|
* authorizes nothing; it may only withhold an automated keystroke: a scheduled
|
|
30
32
|
* wake holds on a live `permission`, `question` or unknown-reason claim
|
|
31
33
|
* (waitingHold). Every other reader takes it as evidence for display.
|
|
@@ -41,6 +43,7 @@
|
|
|
41
43
|
* one home's, so its `home` is the address that was asked about, and a consumer
|
|
42
44
|
* that checks "the rows' home is the home I asked for" keeps holding. */
|
|
43
45
|
import { appendFileSync, closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync } from "node:fs";
|
|
46
|
+
import { createHash } from "node:crypto";
|
|
44
47
|
import { basename, dirname, isAbsolute, join, resolve } from "node:path";
|
|
45
48
|
import { REFUSED_TEXT, safeText } from "./refused-text.mjs";
|
|
46
49
|
|
|
@@ -85,6 +88,12 @@ function cutToUnits(text, max) {
|
|
|
85
88
|
* incarnation's latest one is not live. */
|
|
86
89
|
export const WAITING_BOUNDARY_KINDS = ["launched", "restarted", "stopped"];
|
|
87
90
|
const sessionBoundary = (r) => (r.producer ?? "kernel") === "kernel" && WAITING_BOUNDARY_KINDS.includes(r.kind);
|
|
91
|
+
/** The id of the session a boundary row begins, or null for no boundary: what a session-bound claim
|
|
92
|
+
* (setWaiting `session`) and a board question (lib/instance-board.mjs) record. `<kind>@<at>#<digest of
|
|
93
|
+
* its data>`: two boundaries of one millisecond are told apart by what they record (a launch's
|
|
94
|
+
* `startId`, a stop's receipt), never by their place in a bounded read, and the same row written
|
|
95
|
+
* again (a start boundary repaired into the other log, recordStartBoundary) is the same session. */
|
|
96
|
+
const sessionIdOf = (r) => (r ? `${r.kind}@${r.at}#${createHash("sha256").update(JSON.stringify(r.data ?? null)).digest("hex").slice(0, 16)}` : null);
|
|
88
97
|
/** The closed set of reasons a positive claim carries. A claim authorizes nothing; it may only
|
|
89
98
|
* withhold an automated keystroke. `attention` never marks a screen an Enter answers: a producer
|
|
90
99
|
* that wants one uses `question`, and review catches that. */
|
|
@@ -232,6 +241,10 @@ function append(a, event, { workspaceOnly = false, incarnation, at } = {}) {
|
|
|
232
241
|
return { ok: results.some((r) => r.ok), row, results };
|
|
233
242
|
}
|
|
234
243
|
|
|
244
|
+
/** Whether a read of one log holds the whole log: it was absent, or read in full (not a tail, not
|
|
245
|
+
* refused). */
|
|
246
|
+
const wholeRead = (log) => log.source.status === "ok" || log.source.status === "absent";
|
|
247
|
+
|
|
235
248
|
/** Bounded, descriptor-safe read of one log: lstat → regular file only → read
|
|
236
249
|
* at most the last MAX_BYTES. Returns rows plus the source's integrity facts, and
|
|
237
250
|
* `lastTorn`: where the last torn row sat, as the index in `rows` of the row after it
|
|
@@ -300,8 +313,10 @@ function admit(home, reads) {
|
|
|
300
313
|
* unknown stays unknown, it never resurrects an earlier incarnation's
|
|
301
314
|
* positive. A row older than the incarnation's latest kernel session
|
|
302
315
|
* boundary belongs to an ended session and is not a claim at all, nor is a
|
|
303
|
-
* row whose producer is neither `kernel` nor a valid producer id.
|
|
304
|
-
|
|
316
|
+
* row whose producer is neither `kernel` nor a valid producer id. `complete`:
|
|
317
|
+
* whether every log read was whole (wholeRead); a session-bound row needs it,
|
|
318
|
+
* or a boundary of the incarnation in the rows, to count (below). */
|
|
319
|
+
function claimsOf(rows, incarnation, { complete }) {
|
|
305
320
|
const claims = new Map();
|
|
306
321
|
if (incarnation === null) return claims;
|
|
307
322
|
const current = rows.filter((r) => r.incarnation === incarnation);
|
|
@@ -309,8 +324,14 @@ function claimsOf(rows, incarnation) {
|
|
|
309
324
|
// millisecond keep their append order, and a claim appended before the
|
|
310
325
|
// boundary in that millisecond is still before it.
|
|
311
326
|
const boundary = current.findLastIndex(sessionBoundary);
|
|
327
|
+
const session = sessionIdOf(current[boundary]);
|
|
312
328
|
for (const r of current.slice(boundary + 1)) {
|
|
313
329
|
if (!r.data || typeof r.data.waitingOnYou !== "boolean") continue;
|
|
330
|
+
// A session-bound row (setWaiting `session`) counts only in the session it names, and only where
|
|
331
|
+
// the read proves the current session: a boundary of the incarnation in the rows, or a whole read
|
|
332
|
+
// (with none, the first session). One appended after a boundary its writer had not seen, or read
|
|
333
|
+
// where the current boundary may have fallen out of a tail, says nothing. Unbound rows are as before.
|
|
334
|
+
if (Object.hasOwn(r.data, "session") && (r.data.session !== session || (boundary < 0 && !complete))) continue;
|
|
314
335
|
const p = r.producer ?? "kernel";
|
|
315
336
|
// A row the read rule refuses (a hand-edited log: its producer, its time) says nothing.
|
|
316
337
|
const claim = readWaitingClaim({ since: r.at, producer: p, reason: r.data.reason, message: r.data.message });
|
|
@@ -344,7 +365,7 @@ export function readEvents(given, { limit = 200, since = null, asked } = {}) {
|
|
|
344
365
|
const { home, instance, incarnation, homeLog, workspaceLog } = address;
|
|
345
366
|
const a = readLog(homeLog, "home"), b = readLog(workspaceLog, "workspace");
|
|
346
367
|
const { rows, foreign } = admit(home, [a, b]);
|
|
347
|
-
const claims = claimsOf(rows, incarnation);
|
|
368
|
+
const claims = claimsOf(rows, incarnation, { complete: wholeRead(a) && wholeRead(b) });
|
|
348
369
|
const waitingClaims = [...claims.values()];
|
|
349
370
|
const positive = positiveOf(claims);
|
|
350
371
|
const filtered = since ? rows.filter((r) => r.at > since) : rows;
|
|
@@ -374,11 +395,26 @@ export function readEvents(given, { limit = 200, since = null, asked } = {}) {
|
|
|
374
395
|
* or a session boundary writes goes to both. `meta`: the home's record, when the caller has just
|
|
375
396
|
* read it (lib/instance-listing.mjs listInstances), so that one read parses it once. */
|
|
376
397
|
export function liveWaiting(home, { meta } = {}) {
|
|
398
|
+
return liveSession(home, { meta }).waitingOnYou;
|
|
399
|
+
}
|
|
400
|
+
|
|
401
|
+
/** The instance's current session as one read of its log shows it (liveWaiting's read):
|
|
402
|
+
* `{ incarnation, session, sessionKnown, waitingOnYou }`. `session` is the id of the incarnation's
|
|
403
|
+
* latest kernel session boundary (`launched`, `restarted`, `stopped`; `<kind>@<at>`), null when the
|
|
404
|
+
* read holds none. `sessionKnown` says whether the read proves it: false when the log was read as a
|
|
405
|
+
* tail (its last MAX_BYTES) that holds no boundary of this incarnation, where an earlier one may
|
|
406
|
+
* have been cut off. A board question counts only in the session it was asked in
|
|
407
|
+
* (lib/instance-board.mjs). An unknown incarnation is `{ incarnation: null, session: null,
|
|
408
|
+
* sessionKnown: false, waitingOnYou: null }`. */
|
|
409
|
+
export function liveSession(home, { meta } = {}) {
|
|
377
410
|
const a = addressOf(home, meta);
|
|
378
|
-
if (a.incarnation === null) return null;
|
|
411
|
+
if (a.incarnation === null) return { incarnation: null, session: null, sessionKnown: false, waitingOnYou: null };
|
|
379
412
|
let log = readLog(a.homeLog, "home");
|
|
380
413
|
if (log.source.status === "absent") log = readLog(a.workspaceLog, "workspace");
|
|
381
|
-
|
|
414
|
+
const rows = admit(a.home, [log]).rows;
|
|
415
|
+
const boundary = rows.filter((r) => r.incarnation === a.incarnation).findLast(sessionBoundary);
|
|
416
|
+
const sessionKnown = !!boundary || wholeRead(log);
|
|
417
|
+
return { incarnation: a.incarnation, session: sessionIdOf(boundary), sessionKnown, waitingOnYou: waitingShape(positiveOf(claimsOf(rows, a.incarnation, { complete: wholeRead(log) }))) };
|
|
382
418
|
}
|
|
383
419
|
|
|
384
420
|
/** What holds a scheduled wake at this home: null (no hold), `{claimReason, producer}` (a claim), or
|
|
@@ -403,7 +439,7 @@ export function waitingHold(given) {
|
|
|
403
439
|
if (status === "tail" && boundary < 0) return unreadable(`the ${path} events log's tail holds no session boundary`);
|
|
404
440
|
if (log.lastTorn > boundary) return unreadable(`the ${path} events log has a torn row in this session`);
|
|
405
441
|
}
|
|
406
|
-
const claims = [...claimsOf(admit(a.home, logs).rows, a.incarnation).values()].filter((c) => c.waiting && c.reason !== "attention");
|
|
442
|
+
const claims = [...claimsOf(admit(a.home, logs).rows, a.incarnation, { complete: logs.every(wholeRead) }).values()].filter((c) => c.waiting && c.reason !== "attention");
|
|
407
443
|
const newest = claims.sort((x, y) => x.since.localeCompare(y.since)).at(-1);
|
|
408
444
|
return newest ? { claimReason: newest.reason, producer: newest.producer } : null;
|
|
409
445
|
}
|
|
@@ -420,13 +456,15 @@ const waitingError = (code, message) => Object.assign(new Error(message), { code
|
|
|
420
456
|
* E_SESSION_UNKNOWN; a write either log refused is E_EVENTS_FAILED (a retry
|
|
421
457
|
* repairs it). The answer's `home` is the home as the caller spelled it; the row
|
|
422
458
|
* records the real path. Evidence, not authority: nothing else is touched. */
|
|
423
|
-
export function setWaiting(given, { producer, waiting, reason, message } = {}) {
|
|
459
|
+
export function setWaiting(given, { producer, waiting, reason, message, session } = {}) {
|
|
424
460
|
if (typeof producer !== "string" || !WAITING_PRODUCER_RE.test(producer)) throw waitingError("E_BAD_ARGS", `--producer must match ${WAITING_PRODUCER_RE.source}`);
|
|
425
461
|
if (producer === "kernel") throw waitingError("E_BAD_ARGS", "--producer kernel is reserved for the kernel's own events");
|
|
426
462
|
if (typeof waiting !== "boolean") throw waitingError("E_BAD_ARGS", "waiting must be set or clear");
|
|
427
463
|
if (waiting) {
|
|
428
464
|
if (!WAITING_REASONS.includes(reason)) throw waitingError("E_BAD_ARGS", `--reason must be one of ${WAITING_REASONS.join(", ")}`);
|
|
429
465
|
if (message !== undefined && !validWaitingMessage(message)) throw waitingError("E_BAD_ARGS", `--message must be one line of 1 to ${WAITING_MESSAGE_MAX} characters with no control character, line separator, bidi control (U+202A-202E, U+2066-2069), U+200B, U+2060, U+FEFF or tag character`);
|
|
466
|
+
// A session-bound claim (in-process only: the board's) names the session it was derived in.
|
|
467
|
+
if (session !== undefined && session !== null && typeof session !== "string") throw waitingError("E_BAD_ARGS", "session must be a session id or null");
|
|
430
468
|
} else {
|
|
431
469
|
if (reason !== undefined) throw waitingError("E_BAD_ARGS", "--reason is for set, not clear");
|
|
432
470
|
if (message !== undefined) throw waitingError("E_BAD_ARGS", "--message is for set, not clear");
|
|
@@ -435,11 +473,11 @@ export function setWaiting(given, { producer, waiting, reason, message } = {}) {
|
|
|
435
473
|
const { home, incarnation } = a;
|
|
436
474
|
if (incarnation === null) throw waitingError("E_SESSION_UNKNOWN", `${given} is not an instance home (no readable instance.json)`);
|
|
437
475
|
const live = [readLog(a.homeLog, "home"), readLog(a.workspaceLog, "workspace")]
|
|
438
|
-
.map((log) => { const c = claimsOf(admit(home, [log]).rows, incarnation).get(producer); return c?.waiting ? c : null; });
|
|
476
|
+
.map((log) => { const c = claimsOf(admit(home, [log]).rows, incarnation, { complete: wholeRead(log) }).get(producer); return c?.waiting ? c : null; });
|
|
439
477
|
const agrees = (c) => (waiting ? !!c && c.reason === reason && c.message === (message ?? null) : !c);
|
|
440
478
|
const answer = (changed, claim) => answered(a, { eventsApi: EVENTS_API, instance: a.instance, home, producer, changed, waitingOnYou: waitingShape(claim) });
|
|
441
479
|
if (live.every(agrees)) return answer(false, waiting ? live[0] : null);
|
|
442
|
-
const data = waiting ? { waitingOnYou: true, reason, ...(message !== undefined ? { message } : {}) } : { waitingOnYou: false };
|
|
480
|
+
const data = waiting ? { waitingOnYou: true, reason, ...(message !== undefined ? { message } : {}), ...(session !== undefined ? { session } : {}) } : { waitingOnYou: false };
|
|
443
481
|
const res = append(a, { producer, kind: "waiting", data }, { incarnation });
|
|
444
482
|
const failed = (res.results || []).filter((r) => !r.ok);
|
|
445
483
|
if (!res.ok || failed.length) throw waitingError("E_EVENTS_FAILED", `could not record the waiting claim in ${failed.map((r) => `${r.path} (${r.reason})`).join(", ") || res.reason}; retry to complete it`);
|
package/lib/instance-inspect.mjs
CHANGED
|
@@ -34,6 +34,7 @@ import { readInstancePin } from "./instance-pin.mjs";
|
|
|
34
34
|
/** Bounds of a provider check's answer (bytes, nesting, entries), as the released binding wire set them. */
|
|
35
35
|
const BINDING_LIMITS = Object.freeze({ maxBytes: 1024 * 1024, maxDepth: 32, maxEntries: 16384 });
|
|
36
36
|
import { parseStrictJson } from "./canonical-json.mjs";
|
|
37
|
+
import { checkProviderSession, homeSessionProvider, offeredSessionProviders, sessionProvidersOf } from "./session-providers.mjs";
|
|
37
38
|
import { sameRepo } from "./repo-moves.mjs";
|
|
38
39
|
import { kernelNode } from "./stable-node.mjs";
|
|
39
40
|
|
|
@@ -524,6 +525,9 @@ export function inspectDocument(t, { kernel }) {
|
|
|
524
525
|
return {
|
|
525
526
|
operationsApi: INSPECT_OPERATIONS_API, kernel, subject: t.subject, workspace: t.workspace,
|
|
526
527
|
souls: [soulRow(t)], layers, capabilities,
|
|
528
|
+
// Feature session-providers: the session backends this soul's (or home's) capabilities supply
|
|
529
|
+
// beside the kernel's own, what `--backend` takes here: [{ name, capability }].
|
|
530
|
+
...sessionProviderKeys(t),
|
|
527
531
|
// The capabilities the soul turned off (feature desktop-facts): its `off` over a workspace/team entry
|
|
528
532
|
// (reason "off"), or a `<slot>: none` that dropped a workspace default (reason "slot-none", slot).
|
|
529
533
|
capabilitiesOff: (t.turnedOff || []).map(({ name, reason, slot, overrides }) => ({ id: name, off: true, from: "soul", reason, ...(slot ? { slot } : {}), overrides })),
|
|
@@ -674,6 +678,14 @@ const item = (subject, status, { required = true, reason = null, producer = "ker
|
|
|
674
678
|
({ subject, status, required, reason: bounded(reason), producer, evidence, remedy: bounded(remedy), ...rest,
|
|
675
679
|
...(Array.isArray(rest.problems) ? { problems: rest.problems.map((p) => (obj(p) && typeof p.message === "string" ? { ...p, message: bounded(p.message) } : p)) } : {}) });
|
|
676
680
|
|
|
681
|
+
/** `sessionProviders` of an inspect answer: the session backends the target's capabilities supply
|
|
682
|
+
* and a spawn can select there, `[{ name, capability }]` sorted by name (lib/session-providers.mjs
|
|
683
|
+
* offeredSessionProviders over the target's modules). A malformed declaration is none: what is
|
|
684
|
+
* wrong with it is `oats capabilities show`'s to say. */
|
|
685
|
+
function sessionProviderKeys(t) {
|
|
686
|
+
const { providers } = offeredSessionProviders((t.modules || []).filter((x) => x.manifest).map((x) => ({ id: x.name, manifest: x.manifest })));
|
|
687
|
+
return { sessionProviders: providers.map(({ name, capability }) => ({ name, capability })) };
|
|
688
|
+
}
|
|
677
689
|
/** The team/workspace facts a provider receives, as hooks get them (teamEnv), and the soul's name and
|
|
678
690
|
* stable id as its hooks and dispatched commands get them. Every ambient OATS_* is removed first. */
|
|
679
691
|
function providerEnv(t, capability, settings) {
|
|
@@ -870,6 +882,38 @@ export async function readinessDocument(t, { selector = null, remoteOptions, cat
|
|
|
870
882
|
}
|
|
871
883
|
else providers.push(item(mod.name, "unknown", { producer: "provider binding check", result: null, problems: out.problems, reason: out.problems[0]?.message ?? null, ...cap(mod.name) }));
|
|
872
884
|
}
|
|
885
|
+
// A session provider's own readiness (lib/session-providers.mjs, the optional `check` command),
|
|
886
|
+
// relayed verbatim as a providers item, as a binding check is. For a home: the provider it runs
|
|
887
|
+
// on, required. For a soul: every provider its capabilities offer, not required (the soul can
|
|
888
|
+
// launch on tmux); a member capability's runs from a spawned home, as its binding check does.
|
|
889
|
+
for (const mod of t.modules) {
|
|
890
|
+
const offered = Object.values(sessionProvidersOf(mod.manifest).providers).filter((p) => p.commands.check);
|
|
891
|
+
for (const provider of offered) {
|
|
892
|
+
const onIt = t.home ? t.meta?.backend === provider.name && t.meta?.session?.provider === mod.name : false;
|
|
893
|
+
if (t.home && !onIt) continue;
|
|
894
|
+
const subject = `${mod.name} session backend ${provider.name}`;
|
|
895
|
+
const push = (status, rest) => providers.push(item(subject, status, { required: !!t.home, producer: "session provider check", ...rest, ...cap(mod.name) }));
|
|
896
|
+
const unknown = (code, message) => push("unknown", { result: null, problems: [{ code, message }], reason: message });
|
|
897
|
+
if (Date.now() >= deadline) { unknown("time-budget-exhausted", `time budget exhausted: the providers check stops after ${Math.round(budgetMs / 1000)} s per readiness read`); continue; }
|
|
898
|
+
let binding;
|
|
899
|
+
if (t.home) {
|
|
900
|
+
const found = homeSessionProvider(t.home, t.meta, mod.name, provider.name);
|
|
901
|
+
if (found.problem) { unknown("resource-not-found", found.problem); continue; }
|
|
902
|
+
binding = found.binding;
|
|
903
|
+
} else {
|
|
904
|
+
let dir = null;
|
|
905
|
+
if (mod.module && t.lock) { try { dir = await ensureModuleTree(t.deployment, mod.module, t.lock, { catalog, remoteOptions }); } catch (e) { unknown(e.code || "provider-unavailable", e.message); continue; } }
|
|
906
|
+
if (!dir) { unknown("resource-not-found", `${mod.name}: a member module runs from a spawned home; inspect an instance (--home) for its check`); continue; }
|
|
907
|
+
const settings = obj(t.payloads[mod.name]) ? t.payloads[mod.name] : {};
|
|
908
|
+
binding = { home: null, meta: {}, capability: mod.name, name: provider.name, provider, moduleDir: dir, cap: { id: mod.name, settings }, digest: null,
|
|
909
|
+
env: { ...providerEnv(t, mod.name, settings), OATS_EVENT: "session", OATS_BACKEND: provider.name } };
|
|
910
|
+
}
|
|
911
|
+
const checked = checkProviderSession(binding, { home: t.home ?? null, soul: t.home ? null : t.soul.name, settings: binding.cap.settings }, { timeoutMs: Math.max(1, Math.min(20_000, deadline - Date.now())) });
|
|
912
|
+
if (checked.unavailable) { unknown("provider-unavailable", checked.unavailable); continue; }
|
|
913
|
+
const status = PROVIDER_STATUS_ITEM[checked.result.status];
|
|
914
|
+
push(status, { result: checked.result, reason: status === "pass" ? null : checked.result.problems[0]?.message ?? `the provider reports ${checked.result.status}` });
|
|
915
|
+
}
|
|
916
|
+
}
|
|
873
917
|
const checks = { installed: { status: roll(installed), items: installed }, configured: { status: roll(configured), items: configured }, member: { status: roll(member), items: member }, providers: { status: roll(providers), items: providers } };
|
|
874
918
|
const requiredStatuses = Object.values(checks).flatMap((c) => c.items.filter((i) => i.required).map((i) => i.status));
|
|
875
919
|
const byCapability = [...new Set(Object.values(checks).flatMap((c) => c.items.map((i) => i.capability?.id).filter(Boolean)))].sort().map((id) => {
|
|
@@ -21,7 +21,7 @@ import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
|
21
21
|
import { INSTANCE_COLOR_API, INSTANCE_COLORS, writeInstanceColor } from "./instance-color.mjs";
|
|
22
22
|
import { INSTANCE_BACKGROUND_API, writeInstanceBackground } from "./instance-background.mjs";
|
|
23
23
|
import { INSTANCE_PIN_API, writeInstancePin } from "./instance-pin.mjs";
|
|
24
|
-
import {
|
|
24
|
+
import { relatedWorkBinding, relatedWorkHeld, writeRelatedWork } from "./instance-related-work.mjs";
|
|
25
25
|
import { resolveInstance } from "./instance-address.mjs";
|
|
26
26
|
export { resolveInstance } from "./instance-address.mjs";
|
|
27
27
|
|
|
@@ -110,23 +110,27 @@ export function setInstancePin(ctx, root, name, { home, pinned }) {
|
|
|
110
110
|
return { instancePinApi: INSTANCE_PIN_API, instance: name, home: me.home, pinned, changed };
|
|
111
111
|
}
|
|
112
112
|
|
|
113
|
-
/** `oats instance
|
|
114
|
-
*
|
|
115
|
-
*
|
|
116
|
-
* `
|
|
117
|
-
*
|
|
118
|
-
*
|
|
119
|
-
|
|
120
|
-
|
|
113
|
+
/** `oats instance related-work <instance> on|off` (feature instance-related-work), and its deprecated alias
|
|
114
|
+
* `oats instance same-work` (feature instance-same-work): bind the flag of the home
|
|
115
|
+
* `name` resolves to to its recorded parent, else to its recorded sibling (`on`, relatedWorkBinding), or
|
|
116
|
+
* remove it (`off`). Addressed, and refused beside a retire or in a quarantined home, exactly as
|
|
117
|
+
* setInstanceColor is. `on` needs a recorded `parentInstance` or `siblingInstance` (E_BAD_ARGS with
|
|
118
|
+
* neither) and rebinds a record bound to an old relation; the same binding again writes nothing. `off`
|
|
119
|
+
* succeeds whatever stands there, binding or none. → `{ instance, relatedWork, sameWork }`, the rule
|
|
120
|
+
* (relatedWorkHeld) read after the write: `relatedWork` whether it holds, `sameWork` whether it holds as a
|
|
121
|
+
* parent binding (the old verb's answer, for an older client). */
|
|
122
|
+
export function setInstanceRelatedWork(ctx, root, name, { home, on }) {
|
|
123
|
+
if (typeof on !== "boolean") throw oatsError("E_BAD_ARGS", "instance related-work takes on or off");
|
|
121
124
|
const me = resolveTarget(ctx, root, name, { home });
|
|
122
125
|
if (existsSync(join(me.home, ".oats-rollback-incomplete.json"))) throw oatsError("E_INSTANCE_RETIRING", `${me.home} is a quarantined home (or a spawn still in progress); finish its retirement (oats retire); the flag was not changed`);
|
|
123
126
|
if (existsSync(retirePendingMarkerPath(me.home))) throw oatsError("E_INSTANCE_RETIRING", `${name} is being retired; the flag was not changed`);
|
|
124
|
-
refuseBesideRetire("instance
|
|
125
|
-
const
|
|
126
|
-
const
|
|
127
|
-
if (on &&
|
|
128
|
-
|
|
129
|
-
|
|
127
|
+
refuseBesideRetire("instance related-work", me.home);
|
|
128
|
+
const lineage = targetRecord(me.home) ?? {};
|
|
129
|
+
const binding = relatedWorkBinding(lineage);
|
|
130
|
+
if (on && binding === null) throw oatsError("E_BAD_ARGS", `${name} would record no parent or sibling instance: related work is declared against a recorded parent or sibling; the flag was not changed`);
|
|
131
|
+
writeRelatedWork(me.home, on ? binding : null);
|
|
132
|
+
const held = relatedWorkHeld(me.home, lineage);
|
|
133
|
+
return { instance: name, relatedWork: held !== null, sameWork: !!held?.parent };
|
|
130
134
|
}
|
|
131
135
|
|
|
132
136
|
/** Every instance under the roots whose recorded parent chain reaches `name`,
|
|
@@ -134,7 +138,9 @@ export function setInstanceSameWork(ctx, root, name, { home, on }) {
|
|
|
134
138
|
* parentage is the only relation the kernel knows; it is reported as such. */
|
|
135
139
|
export function descendantsOf(root, name) {
|
|
136
140
|
const rows = [];
|
|
137
|
-
|
|
141
|
+
// One listing, and no session provider asked: only names and records are read here.
|
|
142
|
+
const listed = listInstances(root, undefined, undefined, { askProviders: false });
|
|
143
|
+
for (const a of listAgents(root)) for (const i of listed.filter((x) => x.name === a.name)) for (const inst of i.instances || []) {
|
|
138
144
|
const home = join(a._dir, "instances", inst.instance);
|
|
139
145
|
const meta = otherRecord(home);
|
|
140
146
|
if (meta) rows.push({ instance: inst.instance, agent: a.name, home, parent: meta.parentInstance ?? null });
|
|
@@ -157,6 +163,9 @@ export function descendantsOf(root, name) {
|
|
|
157
163
|
return out; // deepest first
|
|
158
164
|
}
|
|
159
165
|
|
|
166
|
+
/** What the session's inspect said of its activity (`running`: true, false, or null for not known),
|
|
167
|
+
* kept beside the facts for planStop's `midTask` and never part of a plan's JSON. */
|
|
168
|
+
const REPORTED_RUNNING = Symbol("reportedRunning");
|
|
160
169
|
/** `state` is the session backend's word: "shell"/"stopped"/"not-launched" are
|
|
161
170
|
* idle; "unknown" means a NON-shell process is running whose identity tmux
|
|
162
171
|
* cannot name (the ordinary case for a launched harness). "Could not be
|
|
@@ -164,7 +173,7 @@ export function descendantsOf(root, name) {
|
|
|
164
173
|
* the kernel code of what failed, never a system error's (E_SESSION_UNAVAILABLE
|
|
165
174
|
* for one that has none; workFacts: E_GIT_FAILED). */
|
|
166
175
|
function sessionFacts(home) {
|
|
167
|
-
try { const s = inspectInstanceSession(home); return { state: s.state, present: s.present, backend: s.backend ?? null, established: true }; }
|
|
176
|
+
try { const s = inspectInstanceSession(home); return { state: s.state, present: s.present, backend: s.backend ?? null, established: true, [REPORTED_RUNNING]: s.running ?? null }; }
|
|
168
177
|
catch (e) { return { state: "unestablished", present: null, backend: null, established: false, reason: kernelCode(e, "E_SESSION_UNAVAILABLE") }; }
|
|
169
178
|
}
|
|
170
179
|
/** The instances attached to `tree`, a tree of the home of the instance `name` under `root` (its
|
|
@@ -229,7 +238,14 @@ export function planStop(ctx, root, name, { home, recursive = true, [OWN_HOLDING
|
|
|
229
238
|
const targets = [...kids.map((kid) => targetFacts(kid, otherRecord(kid.home), own)), targetFacts({ ...me, instance: name, depth: 0 }, targetRecord(me.home), own)];
|
|
230
239
|
// Reported activity: a running session or dirty work is mid-task; when the
|
|
231
240
|
// session could not be established and work is not observed, say unknown.
|
|
232
|
-
|
|
241
|
+
// A session provider's session says its activity itself (its inspect's `running`): true is
|
|
242
|
+
// activity, and one that is there and reports none (null) is not reported as activity: unknown.
|
|
243
|
+
// (A tmux pane's state "unknown" is a process tmux cannot name, the ordinary launched harness:
|
|
244
|
+
// activity, as before.)
|
|
245
|
+
const onProvider = (s) => s.established && s.present === true && s.backend !== null && s.backend !== "tmux";
|
|
246
|
+
const unknownActivity = (s) => onProvider(s) && s[REPORTED_RUNNING] === null;
|
|
247
|
+
const active = (s) => (onProvider(s) ? s[REPORTED_RUNNING] === true : running(s));
|
|
248
|
+
for (const t of targets) t.midTask = active(t.session) || (t.work.observed && t.work.changed + t.work.untracked > 0) ? true : (!t.session.established || unknownActivity(t.session) || !t.work.observed) ? "unknown" : false;
|
|
233
249
|
const safety = targets.map((t) => [t.home, t.session.state, t.session.present, t.launched, t.retiring]);
|
|
234
250
|
const ambiguousEdges = (kids.ambiguous || []).map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, reason: c.reason }));
|
|
235
251
|
const plan = { lifecycleApi: LIFECYCLE_API, action: "stop", instance: name, home: me.home, recursive, at: new Date().toISOString(),
|
package/lib/instance-listing.mjs
CHANGED
|
@@ -8,7 +8,8 @@ import { readFileSync, readdirSync, lstatSync, existsSync, statSync, openSync, c
|
|
|
8
8
|
import { join, dirname, resolve, basename } from "node:path";
|
|
9
9
|
import { noteRuntimeName } from "./deprecation.mjs";
|
|
10
10
|
import { createSessionPaneInspector, AGENT_PANE_OPTION } from "./session-input.mjs";
|
|
11
|
-
import { liveWaiting, validWaitingMessage } from "./instance-events.mjs";
|
|
11
|
+
import { liveSession, liveWaiting, validWaitingMessage } from "./instance-events.mjs";
|
|
12
|
+
import { readBoardRow } from "./instance-board.mjs";
|
|
12
13
|
import { processLiveness } from "./worktree-hooks.mjs";
|
|
13
14
|
import { shownHolder } from "./claim.mjs";
|
|
14
15
|
import { isInstant as isInstantString, readRetireState } from "./retire-state.mjs";
|
|
@@ -16,12 +17,14 @@ import { herdrInstanceRemoved, oatsError } from "./errors.mjs";
|
|
|
16
17
|
import { readInstanceColor } from "./instance-color.mjs";
|
|
17
18
|
import { readInstanceBackground } from "./instance-background.mjs";
|
|
18
19
|
import { readInstancePin } from "./instance-pin.mjs";
|
|
19
|
-
import {
|
|
20
|
+
import { relatedWorkHeld } from "./instance-related-work.mjs";
|
|
20
21
|
import { readSpawnedBy } from "./spawned-by.mjs";
|
|
21
|
-
import { sessionEndOf } from "./session-end.mjs";
|
|
22
|
+
import { HOST_STOP_REASON, lostReasonOf, sessionEndOf } from "./session-end.mjs";
|
|
22
23
|
import { identityHolderState, recordSeen } from "./session-seen.mjs";
|
|
23
24
|
import { listAgents, capabilityAgentDirs } from "./soul-listing.mjs";
|
|
24
|
-
import { recordsHerdr, readJsonOrUndefined, findRetirementBaseline, instanceSessionTarget, harnessRunning, isPlainObject, instancesRetirementRoot } from "./session-inspect.mjs";
|
|
25
|
+
import { recordsHerdr, readJsonOrUndefined, findRetirementBaseline, instanceSessionTarget, harnessRunning, isPlainObject, instancesRetirementRoot, providerMayWait } from "./session-inspect.mjs";
|
|
26
|
+
import { INSPECT_MANY_MAX, sessionProviderTimeout, homeSessionProvider, recordsSessionProvider, inspectManyGroup, inspectProviderSession, inspectProviderSessions, rowSession, unsettledLaunchSaid } from "./session-providers.mjs";
|
|
27
|
+
import { SESSION_END } from "./session-resume-contract.mjs";
|
|
25
28
|
|
|
26
29
|
/** OATS 0.25 and earlier homed local souls and capability-defined agents at
|
|
27
30
|
* <scope>/local-agents/ (and <root>/local-agents|tmp-agents). The kernel never reads,
|
|
@@ -277,10 +280,79 @@ function statusTmuxPanes(snapshot, socket, session, io) {
|
|
|
277
280
|
return { ...snapshot, panes, windowIds };
|
|
278
281
|
} catch (e) { return { error: tmuxFailure(e, "tmux list-panes failed") }; }
|
|
279
282
|
}
|
|
283
|
+
/** The row of a home on a session provider, before its provider has been asked: the kernel's own
|
|
284
|
+
* facts, under the receipt's authority (instanceSessionTarget). → `{ fields, ask? }`: `fields` the
|
|
285
|
+
* row's `backend`, `session`, `tmux` (null), `open`, `running`, `runtimeState` (`unknown`, `shell`,
|
|
286
|
+
* `stopped` or `unreachable`; always there) and, for a home OATS stopped, `sessionEnd`; `ask`
|
|
287
|
+
* (`{ binding, endpoint }`) for a session the provider must be asked about.
|
|
288
|
+
* `session` is `{ provider }` and, on this host only, the endpoint's thread id (rowSession): the
|
|
289
|
+
* endpoint itself is never on a row (`oats session inspect --home` answers it, locally).
|
|
290
|
+
* A home OATS stopped, and one never launched, answer without the provider. A stopped home's
|
|
291
|
+
* `sessionEnd` is its stop receipt's (lib/session-end.mjs): `lost` when `oats host run`'s shutdown
|
|
292
|
+
* stopped it, which a resume brings back, else `stopped`. A receipt or a module copy that cannot
|
|
293
|
+
* be used is unknown (`unreachable`, with the reason), never stopped. */
|
|
294
|
+
function providerRow(home, meta) {
|
|
295
|
+
const unreachable = (why, session) => ({ fields: { backend: meta.backend, session: session ?? rowSession(typeof meta.session?.provider === "string" ? meta.session.provider : null, null), tmux: null, open: null, running: null, runtimeState: "unreachable", runtimeError: why } });
|
|
296
|
+
let s;
|
|
297
|
+
try { s = instanceSessionTarget(home); } catch (e) { return unreachable(`${typeof e?.code === "string" ? e.code : "E_SESSION_UNAVAILABLE"}: ${e?.message ?? e}`); }
|
|
298
|
+
const recorded = s.session ?? s.planned;
|
|
299
|
+
// A record that names a session provider beside a receipt that authorises a tmux session, or none.
|
|
300
|
+
if (!recorded) return unreachable("E_RUNTIME_AUTHORITY_MISMATCH: instance metadata records a session provider and its independent session receipt does not");
|
|
301
|
+
const fields = { backend: recorded.backend, session: rowSession(recorded.provider, recorded.endpoint ?? null), tmux: null, open: null };
|
|
302
|
+
// A launch that was sent and never recorded: unknown, never stopped (lib/session-providers.mjs launchSentOf).
|
|
303
|
+
if (s.unsettled) return unreachable(unsettledLaunchSaid(basename(home), s.unsettled.backend, s.unsettled.launchSent), fields.session);
|
|
304
|
+
if (!s.session) return { fields: { ...fields, running: false, runtimeState: "stopped" } };
|
|
305
|
+
if (s.session.stoppedAt !== null) return { fields: { ...fields, running: false, runtimeState: "stopped", sessionEnd: lostReasonOf(home, s.meta) === HOST_STOP_REASON ? SESSION_END.LOST : SESSION_END.STOPPED } };
|
|
306
|
+
const found = homeSessionProvider(home, s.meta, s.session.provider, s.session.backend);
|
|
307
|
+
if (found.problem) return unreachable(found.problem, fields.session);
|
|
308
|
+
return { fields: { ...fields, running: null, runtimeState: "unreachable" }, ask: { binding: found.binding, endpoint: s.session.endpoint } };
|
|
309
|
+
}
|
|
310
|
+
/** The time one listing gives all its session providers together: a provider that hangs costs a
|
|
311
|
+
* status, a sweep or a plan this much at most, however many homes it has. */
|
|
312
|
+
const PROVIDER_LISTING_BUDGET_MS = 30_000;
|
|
313
|
+
/** Ask the providers about `asks` ([{ row, home, binding, endpoint, mayEnd }]) and write each answer
|
|
314
|
+
* into its row: one `inspectMany` call per group of homes that share one module copy, provider and
|
|
315
|
+
* settings (inspectManyGroup), at most INSPECT_MANY_MAX homes a call, and one `inspect` per home
|
|
316
|
+
* where a provider declares none (or its batch was bad: inspectProviderSessions). A provider that
|
|
317
|
+
* fails, refuses or answers outside the contract's words leaves the row unknown: `running: null`,
|
|
318
|
+
* `runtimeState: "unreachable"`. A session that is gone on a home OATS did not stop is a lost
|
|
319
|
+
* one (`sessionEnd: "lost"`, where the row may say how its session ended: `mayEnd`), which the
|
|
320
|
+
* sweep resumes under the home's cap. All the asks of one listing share PROVIDER_LISTING_BUDGET_MS. */
|
|
321
|
+
function answerProviderRows(asks, io) {
|
|
322
|
+
const deadline = Date.now() + PROVIDER_LISTING_BUDGET_MS;
|
|
323
|
+
// Each call's timeout: the verb's own (and a test's seam), never past what the listing has left.
|
|
324
|
+
const timeoutFor = () => Math.min(sessionProviderTimeout("inspect"), deadline - Date.now());
|
|
325
|
+
const groups = new Map(), single = [];
|
|
326
|
+
for (const ask of asks) {
|
|
327
|
+
const key = inspectManyGroup(ask.binding);
|
|
328
|
+
if (key === null) single.push(ask);
|
|
329
|
+
else groups.set(key, [...(groups.get(key) ?? []), ask]);
|
|
330
|
+
}
|
|
331
|
+
const answer = (ask, inspected) => {
|
|
332
|
+
if (inspected.unavailable) { Object.assign(ask.row, { running: null, runtimeState: "unreachable", runtimeError: inspected.unavailable }); return; }
|
|
333
|
+
const { state, running, open } = inspected.observed;
|
|
334
|
+
Object.assign(ask.row, { running, runtimeState: state, open });
|
|
335
|
+
delete ask.row.runtimeError;
|
|
336
|
+
// A producer's claim, read while the session is there and not in error (an idle session can be
|
|
337
|
+
// the one waiting on a person); the receipt already agreed (providerRow).
|
|
338
|
+
if (providerMayWait(inspected.observed)) ask.row.waitingOnYou = liveWaiting(ask.home);
|
|
339
|
+
if (inspected.observed.present === false && ask.mayEnd) ask.row.sessionEnd = SESSION_END.LOST;
|
|
340
|
+
};
|
|
341
|
+
for (const ask of single) { const timeoutMs = timeoutFor(); answer(ask, timeoutMs > 0 ? inspectProviderSession(ask.binding, ask.endpoint, { io, timeoutMs }) : { unavailable: "the time this listing gives its session providers was spent before this one was asked" }); }
|
|
342
|
+
for (const members of groups.values()) {
|
|
343
|
+
for (let at = 0; at < members.length; at += INSPECT_MANY_MAX) {
|
|
344
|
+
const chunk = members.slice(at, at + INSPECT_MANY_MAX);
|
|
345
|
+
inspectProviderSessions(chunk, { io, timeoutFor }).forEach((inspected, i) => answer(chunk[i], inspected));
|
|
346
|
+
}
|
|
347
|
+
}
|
|
348
|
+
}
|
|
280
349
|
/** `records`, when given, a Map the listing fills with each home's record as read (home → the JSON
|
|
281
350
|
* object its instance.json holds, before upgradeHomeMeta), for the rest of the same read to reuse
|
|
282
|
-
* instead of reading the file again (legacyCapturedHomes).
|
|
283
|
-
|
|
351
|
+
* instead of reading the file again (legacyCapturedHomes).
|
|
352
|
+
* `askProviders: false` (the host's shutdown listing): no session provider is asked. A provider
|
|
353
|
+
* home whose provider would be asked reads `running: null`, `runtimeState: "unreachable"`, with a
|
|
354
|
+
* `runtimeError` that says so: the listing then depends on no provider's answer, or time. */
|
|
355
|
+
export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { records, askProviders = true } = {}) {
|
|
284
356
|
// Liveness reads each home's RECORDED endpoint (a pre-0.31 home records pi-agents): the recorded
|
|
285
357
|
// socket, never the ambient $TMUX server: one window read and one pane read per socket/session,
|
|
286
358
|
// plus one lazy process scan for shell descendants, independent of the number of homes.
|
|
@@ -293,6 +365,9 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
293
365
|
return hostScan.ok ? { ok: true, processes: processesWorkingIn(hostScan.processes, home) } : hostScan;
|
|
294
366
|
};
|
|
295
367
|
const inspectPanes = createSessionPaneInspector(io);
|
|
368
|
+
// The homes on a session provider whose provider must be asked: asked together once every row is
|
|
369
|
+
// read (answerProviderRows), so that one call can answer for a provider's whole group.
|
|
370
|
+
const providerAsks = [];
|
|
296
371
|
const tmuxByEndpoint = new Map();
|
|
297
372
|
const windowsOf = (session, socket) => {
|
|
298
373
|
const key = JSON.stringify([socket ?? null, session]);
|
|
@@ -317,9 +392,14 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
317
392
|
const { rollbackIncomplete, spawnInProgress, retirePending, retire } = readRetireFacts(home);
|
|
318
393
|
// A home opened in Herdr (removed in 0.31.0) is listed, never observed: its row says so.
|
|
319
394
|
// A home whose record cannot be read is listed, never observed: where its session is, is in the record.
|
|
395
|
+
const herdr = record.state !== "unreadable" && recordsHerdr(meta, readJsonOrUndefined(findRetirementBaseline(home)));
|
|
396
|
+
// A home on a session provider is never read through tmux: its row is the kernel's facts
|
|
397
|
+
// and, where the provider must be asked, its answer (below, once every row is read).
|
|
398
|
+
const provided = record.state === "record" && !herdr && recordsSessionProvider(meta) ? providerRow(home, meta) : null;
|
|
320
399
|
const liveness = record.state === "unreadable" ? { running: null, runtimeState: "unreachable", runtimeError: `E_UNIDENTIFIED_INSTANCE_HOME: ${unreadableRecordSaid(record)}` }
|
|
321
|
-
:
|
|
400
|
+
: herdr
|
|
322
401
|
? { running: null, runtimeState: "unsupported", runtimeError: `E_HERDR_REMOVED: ${herdrInstanceRemoved(e.name).message}` }
|
|
402
|
+
: provided ? (({ sessionEnd: _own, ...fields }) => fields)(provided.fields)
|
|
323
403
|
: tmuxLiveness(windowsOf(meta.tmux?.session || tmuxSession, meta.tmux?.socket), meta.tmux?.window || meta.instance || e.name, scanOf(home),
|
|
324
404
|
// A home that records no socket and no launch (--no-launch) reads the default server only
|
|
325
405
|
// by default: that server's missing socket says nothing about it, and stays "not running".
|
|
@@ -345,30 +425,46 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
345
425
|
// its home log); null otherwise, and null means unknown. Pane liveness is
|
|
346
426
|
// already observed in the batch; still require the independent receipt
|
|
347
427
|
// to agree before showing a claim, just as session inspect does.
|
|
348
|
-
|
|
428
|
+
const recordMeta = record.state === "record" ? { meta: record.meta } : {};
|
|
429
|
+
const session = liveness.running === true ? liveSession(home, recordMeta) : undefined;
|
|
430
|
+
let waitingOnYou = session ? session.waitingOnYou : null;
|
|
349
431
|
if (waitingOnYou) {
|
|
350
432
|
try { const s = instanceSessionTarget(home); if (!s.target) waitingOnYou = null; }
|
|
351
433
|
catch { waitingOnYou = null; }
|
|
352
434
|
}
|
|
353
|
-
// `retire` is only ever the value read above, and `background`, `pinned` and `
|
|
435
|
+
// `retire` is only ever the value read above, and `background`, `pinned`, `relatedWork` and `board` the home's own
|
|
354
436
|
// records (below): a record that carries any of them (hand-edited, or copied from a row) never stands in
|
|
355
|
-
// for it.
|
|
356
|
-
const { retire: _recordedRetire, background: _recordedBackground, pinned: _recordedPinned, sameWork: _recordedSameWork, ...recorded } = meta;
|
|
437
|
+
// for it. Nor does a `sameWork` key, the flag's old name (below).
|
|
438
|
+
const { retire: _recordedRetire, background: _recordedBackground, pinned: _recordedPinned, relatedWork: _recordedRelatedWork, sameWork: _recordedSameWork, board: _recordedBoard, ...recorded } = meta;
|
|
357
439
|
// `spawnedBy` (feature spawn-attribution) is the record's own, read in place by its rule (lib/spawned-by.mjs):
|
|
358
440
|
// a malformed one is null, and a home spawned before the feature has no key.
|
|
359
441
|
if (Object.hasOwn(recorded, "spawnedBy")) recorded.spawnedBy = readSpawnedBy(recorded.spawnedBy);
|
|
360
442
|
// Feature session-resume: how the last session of a launched home that does not run ended
|
|
361
443
|
// (lib/session-end.mjs): lost, stopped or exited. Absent while it runs or reads unknown, for a
|
|
362
444
|
// home never launched, and for one being set up, retired or quarantined.
|
|
363
|
-
|
|
445
|
+
// A home on a session provider reads it from its receipt (providerRow): `lost` for one stopped
|
|
446
|
+
// with the host, which a resume brings back, `stopped` for one an operator stopped; a session
|
|
447
|
+
// OATS did not stop has none.
|
|
448
|
+
const sessionEnd = record.state === "record" && liveness.running === false && meta.launched === true && !rollbackIncomplete && !spawnInProgress && !retirePending ? (provided ? provided.fields.sessionEnd ?? null : sessionEndOf(home, meta)) : null;
|
|
364
449
|
// Feature instance-color: the home's own colour record (lib/instance-color.mjs), a palette name or
|
|
365
450
|
// null, after the record so that nothing in instance.json stands in for it.
|
|
366
451
|
// Feature instance-pin: `pinned: true` while the home holds a valid pin (lib/instance-pin.mjs), absent
|
|
367
452
|
// otherwise, never false.
|
|
368
|
-
// Feature instance-
|
|
369
|
-
// its
|
|
370
|
-
|
|
371
|
-
|
|
453
|
+
// Feature instance-related-work: `relatedWork: true` only while the home's flag is bound to the relation
|
|
454
|
+
// its record still has (lib/instance-related-work.mjs relatedWorkHeld); absent otherwise, never false.
|
|
455
|
+
// Feature instance-same-work, the compatibility layer: `sameWork: true` beside it for a parent binding
|
|
456
|
+
// only, as an older client reads it; absent otherwise.
|
|
457
|
+
const related = record.state === "record" ? relatedWorkHeld(home, meta) : null;
|
|
458
|
+
// Feature instance-board: the agent's board (lib/instance-board.mjs), null for a home with no board
|
|
459
|
+
// file: its facts, and the questions of its current session, by the same read of the log as the claim.
|
|
460
|
+
const board = readBoardRow(home, { session, ...recordMeta });
|
|
461
|
+
// `backend`: `tmux` for a home on the kernel's own backend, a session provider's name otherwise
|
|
462
|
+
// (liveness carries it, with `session`); absent for a home whose record cannot be read and
|
|
463
|
+
// for one opened in Herdr, whose record says what it says.
|
|
464
|
+
const row = { ...recorded, ...claims, home, instance: e.name, ...(record.state === "record" && !herdr && !provided ? { backend: "tmux" } : {}), ...facts, color: readInstanceColor(home), ...(readInstanceBackground(home) ? { background: true } : {}), ...(readInstancePin(home) ? { pinned: true } : {}), ...(related ? { relatedWork: true } : {}), ...(related?.parent ? { sameWork: true } : {}), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(sessionEnd ? { sessionEnd } : {}), waitingOnYou, board, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
|
|
465
|
+
if (provided?.ask && askProviders) providerAsks.push({ row, home, ...provided.ask, mayEnd: meta.launched === true && !rollbackIncomplete && !spawnInProgress && !retirePending });
|
|
466
|
+
else if (provided?.ask) row.runtimeError = "its session provider was not asked (a listing that asks no provider)";
|
|
467
|
+
return row;
|
|
372
468
|
|
|
373
469
|
});
|
|
374
470
|
};
|
|
@@ -393,6 +489,7 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
393
489
|
out.push({ name, kind: "capability", capability: cap, description: cap ? `capability agent (${cap})` : "capability agent", dir, instances, ...(retireFailures.length ? { retireFailures } : {}) });
|
|
394
490
|
seen.add(name);
|
|
395
491
|
}
|
|
492
|
+
if (providerAsks.length) answerProviderRows(providerAsks, io);
|
|
396
493
|
// Feature session-resume: what this local listing saw of each home's session, for the sweep
|
|
397
494
|
// (lib/session-seen.mjs). It never changes the listing, and never throws or prints.
|
|
398
495
|
recordSeen(root, out.flatMap((a) => a.instances || []));
|