@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/servers.mjs
CHANGED
|
@@ -28,15 +28,18 @@ import { readWaitingClaim, validWaitingMessage } from "./instance-events.mjs";
|
|
|
28
28
|
import { readRetireState } from "./retire-state.mjs";
|
|
29
29
|
import { SESSION_END } from "./session-resume-contract.mjs";
|
|
30
30
|
import { paletteColor } from "./instance-color.mjs";
|
|
31
|
+
import { relatedWorkBinding } from "./instance-related-work.mjs";
|
|
31
32
|
import { readSpawnedBy } from "./spawned-by.mjs";
|
|
32
33
|
import { withDirLock } from "./dir-lock.mjs";
|
|
33
34
|
import { shellWord } from "./shell-word.mjs";
|
|
34
35
|
import { DETACH_KEY_FEATURE, requireDetachKey } from "./session-viewer.mjs";
|
|
35
36
|
import { LOGIN_CAPTURE_MAX_BYTES, LOGIN_SHELLS, loginPathEmitter, quoteFor, readLoginFrame } from "./login-environment.mjs";
|
|
36
37
|
import { compareSemver } from "./semver.mjs";
|
|
37
|
-
import { SPAWN_TASK_STDIN_FEATURE } from "./kernel-features.mjs";
|
|
38
|
+
import { SESSION_PROVIDERS_FEATURE, SPAWN_TASK_STDIN_FEATURE } from "./kernel-features.mjs";
|
|
39
|
+
import { relayedProviderRow, withoutRelayedEndpoint } from "./session-providers.mjs";
|
|
38
40
|
import { sameRepo } from "./repo-moves.mjs";
|
|
39
41
|
import { OATS_PACKAGE_NAME } from "./version.mjs";
|
|
42
|
+
import { readRemoteBoard } from "./instance-board.mjs";
|
|
40
43
|
export { compareSemver } from "./semver.mjs";
|
|
41
44
|
|
|
42
45
|
const OATS_HOME_DIR = () => process.env.OATS_HOME_DIR || join(homedir(), ".oats");
|
|
@@ -328,9 +331,24 @@ export function operatorSshArgv(alias, words) {
|
|
|
328
331
|
|
|
329
332
|
// ------------------------------------------------------------------ running
|
|
330
333
|
|
|
334
|
+
/** A host's envelope without a session provider's locator (feature session-providers): a provider
|
|
335
|
+
* home's endpoint, and the thread id a status row carries on its own host, are for the host where
|
|
336
|
+
* the home lives, and are never relayed. An answer's own `session` (a spawn's, a start's, an
|
|
337
|
+
* inspect's) and every roster row's are cut to `{ provider }`, whatever the host sent. */
|
|
338
|
+
function withoutProviderLocators(envelope) {
|
|
339
|
+
const result = envelope?.result;
|
|
340
|
+
if (envelope?.ok !== true || !result || typeof result !== "object") return envelope;
|
|
341
|
+
const rows = (agents) => agents.map((a) => (a && Array.isArray(a.instances) ? { ...a, instances: a.instances.map(withoutRelayedEndpoint) } : a));
|
|
342
|
+
const roster = (doc) => (doc && Array.isArray(doc.agents) ? { ...doc, agents: rows(doc.agents) } : doc);
|
|
343
|
+
const cut = Array.isArray(result.roots) ? { ...result, roots: result.roots.map(roster) } : roster(withoutRelayedEndpoint(result));
|
|
344
|
+
return { ...envelope, result: cut };
|
|
345
|
+
}
|
|
331
346
|
/** Parse the remote kernel's JSON envelope; anything else on stdout is a
|
|
332
347
|
* routing failure with the raw text attached, never a guess. */
|
|
333
348
|
export function parseRemoteEnvelope(stdout) {
|
|
349
|
+
return withoutProviderLocators(parseRemoteEnvelopeAsSent(stdout));
|
|
350
|
+
}
|
|
351
|
+
function parseRemoteEnvelopeAsSent(stdout) {
|
|
334
352
|
const text = String(stdout || "").trim();
|
|
335
353
|
let doc;
|
|
336
354
|
try {
|
|
@@ -497,6 +515,7 @@ export function dropRemoteProbes(serverId) {
|
|
|
497
515
|
|
|
498
516
|
function probeRemote(target, io) {
|
|
499
517
|
const { envelope } = runRemote(target, ["version", "--json"], { ...io, timeoutMs: 60000 });
|
|
518
|
+
if (!envelope.ok) throw relayedFailure(envelope, "version --json");
|
|
500
519
|
const probe = envelope.result || {};
|
|
501
520
|
if (probe.desktopApi !== 1 || typeof probe.version !== "string") {
|
|
502
521
|
throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats at ${target.sshHost} answered an unknown version payload: ${JSON.stringify(probe).slice(0, 200)}`);
|
|
@@ -559,7 +578,10 @@ export function checkRemoteSupport(remote, target, oatsArgs, roster) {
|
|
|
559
578
|
// A wake schedule at spawn is saved by the host: it must advertise schedules.
|
|
560
579
|
if (["--wake-json", "--wake-every", "--wake-cron"].some((f) => oatsArgs.includes(f)) && !remote.features.includes("schedule")) refuse("a wake schedule at spawn (the host must advertise the schedule feature)");
|
|
561
580
|
const backend = flagOf("--backend");
|
|
562
|
-
|
|
581
|
+
// A backend that is none of the host's built-in ones is a session provider (a capability's, resolved
|
|
582
|
+
// against the instance's modules there): relayed only to a host that lists the feature. A host
|
|
583
|
+
// without it knows tmux alone, and is never asked for another.
|
|
584
|
+
if (backend && !remote.sessionBackends.includes(backend) && !remote.features.includes(SESSION_PROVIDERS_FEATURE)) refuse(`session backend ${backend} (a session provider: the host must advertise ${SESSION_PROVIDERS_FEATURE})`);
|
|
563
585
|
if (oatsArgs.includes("--yolo") && !remote.launchOptions.includes("yolo")) refuse("the yolo launch option");
|
|
564
586
|
return { harness, backend, yolo: oatsArgs.includes("--yolo") };
|
|
565
587
|
}
|
|
@@ -744,8 +766,9 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
|
|
|
744
766
|
// Feature instance-background: an older host would refuse the flag as unknown, or place the instance
|
|
745
767
|
// in the main list; either is said here, before anything is sent.
|
|
746
768
|
if (oatsArgs.includes("--background") || oatsArgs.includes("--no-background")) requireRemoteFeature(remote, target, "instance-background");
|
|
747
|
-
//
|
|
748
|
-
|
|
769
|
+
// Feature instance-related-work: the flag as this host takes it (relatedWorkSpawnArgs), or refused here,
|
|
770
|
+
// before anything is sent; never dropped.
|
|
771
|
+
if (oatsArgs.includes("--related-work") || oatsArgs.includes("--same-work")) oatsArgs = relatedWorkSpawnArgs(remote, target, oatsArgs, status.result);
|
|
749
772
|
const spawnOnHost = (args) => runRemote(target, json(withScope(["spawn", ...hostHarnessArgs(remote, args)])), { ...io, input: task });
|
|
750
773
|
// A spawn that brings neither a decision nor a key is bound here: the host's preview decides, and
|
|
751
774
|
// the apply carries that decision and a key of this request, so the same spawn sent again with
|
|
@@ -884,7 +907,7 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
|
|
|
884
907
|
}
|
|
885
908
|
if (cmd === "status") {
|
|
886
909
|
const { envelope, stderr } = runRemote(target, json(withScope(["status", ...oatsArgs])), io);
|
|
887
|
-
return { envelope: envelope.ok ? { ...envelope, result: { ...envelope.result, server: serverId, target, snapshots: listSnapshots(serverId) } } : envelope, stderr };
|
|
910
|
+
return { envelope: envelope.ok ? { ...envelope, result: { ...relatedWorkRows(envelope.result), server: serverId, target, snapshots: listSnapshots(serverId) } } : envelope, stderr };
|
|
888
911
|
}
|
|
889
912
|
if (OPERATIONS_COMMANDS.has(cmd)) {
|
|
890
913
|
// The operations contract (inspect, operation run): the
|
|
@@ -914,6 +937,8 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
|
|
|
914
937
|
if (cmd === "inspect" && args.includes("--instructions")) requireRemoteFeature(remote, target, "soul-composed-instructions");
|
|
915
938
|
// `inspect --skills` (feature soul-skills): the same, for the soul's own skills.
|
|
916
939
|
if (cmd === "inspect" && args.includes("--skills")) requireRemoteFeature(remote, target, "soul-skills");
|
|
940
|
+
// `inspect --board` (feature instance-board): the same, for the board's history and context.
|
|
941
|
+
if (cmd === "inspect" && args.includes("--board")) requireRemoteFeature(remote, target, "instance-board");
|
|
917
942
|
// `inspect --composed-skills` (feature soul-composed-skills): the same, for every skill a spawn would give.
|
|
918
943
|
if (cmd === "inspect" && args.includes("--composed-skills")) requireRemoteFeature(remote, target, "soul-composed-skills");
|
|
919
944
|
const scoped = args.includes("--dir") || args.includes("--home") ? args : [...args, "--dir", target.workspace];
|
|
@@ -923,6 +948,94 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
|
|
|
923
948
|
throw serverError("E_USAGE", `--server routes spawn, retire, status, session, okf harvest, schedule, inspect, operation, readiness and instance only (not ${cmd})`);
|
|
924
949
|
}
|
|
925
950
|
|
|
951
|
+
// ------------------------------------------------- related work on an older host
|
|
952
|
+
|
|
953
|
+
/** Whether a host's `features` say it is a kernel from before the related-work rename: it advertises
|
|
954
|
+
* instance-same-work (the flag by its old name, a parent binding only) and not instance-related-work. Only
|
|
955
|
+
* there is the flag sent by its old spelling, and a sibling binding refused. */
|
|
956
|
+
export function sameWorkOnly(features) {
|
|
957
|
+
return Array.isArray(features) && features.includes("instance-same-work") && !features.includes("instance-related-work");
|
|
958
|
+
}
|
|
959
|
+
|
|
960
|
+
/** The binding a routed spawn of `oatsArgs` would record, read from its arguments and the host's roster
|
|
961
|
+
* `roster` (its `status --json`): "parent" for `--parent`, `--relation child` and an attached spawn; for
|
|
962
|
+
* `--relation sibling|parent`, the binding the anchor's row gives (relatedWorkBinding, as the host's kernel
|
|
963
|
+
* chooses it): "sibling" when any row of that name gives a sibling, so that a sibling binding is never sent
|
|
964
|
+
* as a parent one; null when nothing here says (no relation, an anchor the roster does not list): the host
|
|
965
|
+
* answers that spawn itself. */
|
|
966
|
+
function routedSpawnBinding(oatsArgs, roster) {
|
|
967
|
+
const valueOf = (flag) => { const i = oatsArgs.indexOf(flag); return i >= 0 && oatsArgs[i + 1] && !oatsArgs[i + 1].startsWith("--") ? oatsArgs[i + 1] : undefined; };
|
|
968
|
+
const relation = valueOf("--relation"), relativeTo = valueOf("--relative-to");
|
|
969
|
+
if (valueOf("--parent") !== undefined || relation === "child") return "parent";
|
|
970
|
+
if ((relation === "sibling" || relation === "parent") && relativeTo) {
|
|
971
|
+
const anchors = (roster?.agents || []).flatMap((a) => a.instances || []).filter((i) => i?.instance === relativeTo);
|
|
972
|
+
// A sibling shares the anchor's parent, else links to the anchor; a new parent takes the anchor's slot.
|
|
973
|
+
const kinds = anchors.map((a) => relatedWorkBinding(relation === "sibling" ? { parentInstance: a.parentInstance, siblingInstance: a.instance } : a));
|
|
974
|
+
if (kinds.some((b) => b?.sibling)) return "sibling";
|
|
975
|
+
return kinds.some((b) => b?.parent) ? "parent" : null;
|
|
976
|
+
}
|
|
977
|
+
return !relation && valueOf("--work") === "attached" ? "parent" : null;
|
|
978
|
+
}
|
|
979
|
+
|
|
980
|
+
/** `oatsArgs` of a routed spawn that carries `--related-work` or its deprecated alias `--same-work`, as the
|
|
981
|
+
* host takes it: by a host that advertises instance-related-work, as `--related-work` (so that it says no
|
|
982
|
+
* deprecation of its own); by a host with only instance-same-work (sameWorkOnly), as `--same-work` when
|
|
983
|
+
* the spawn's binding is a parent or not known here (the host then refuses a spawn that records no parent
|
|
984
|
+
* itself), and refused with E_REMOTE_INCOMPATIBLE for a sibling binding, which that kernel cannot record;
|
|
985
|
+
* any other host refuses it (E_REMOTE_INCOMPATIBLE). */
|
|
986
|
+
function relatedWorkSpawnArgs(remote, target, oatsArgs, roster) {
|
|
987
|
+
const spelled = (flag) => oatsArgs.map((a) => (a === "--related-work" || a === "--same-work" ? flag : a)).filter((a, i, all) => a !== flag || all.indexOf(flag) === i);
|
|
988
|
+
if (remote.features.includes("instance-related-work")) return spelled("--related-work");
|
|
989
|
+
if (!sameWorkOnly(remote.features)) requireRemoteFeature(remote, target, "instance-related-work");
|
|
990
|
+
if (routedSpawnBinding(oatsArgs, roster) === "sibling") throw siblingNeedsRelatedWork(remote, target);
|
|
991
|
+
return spelled("--same-work");
|
|
992
|
+
}
|
|
993
|
+
|
|
994
|
+
const siblingNeedsRelatedWork = (remote, target) => serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise instance-related-work, which a sibling binding needs (its instance-same-work binds a parent only); upgrade it there; nothing was sent`);
|
|
995
|
+
|
|
996
|
+
/** `args` of `instance related-work <instance> on|off …` (after `instance`, the route's --home pushed) for a
|
|
997
|
+
* host with only instance-same-work: the verb by its old name. `on` for an instance whose row on the host
|
|
998
|
+
* records no parent and a sibling is refused (E_REMOTE_INCOMPATIBLE): that kernel binds a parent only.
|
|
999
|
+
* `off`, and `on` for a row with a parent or none the roster lists, go as asked: the host answers them. */
|
|
1000
|
+
function relatedWorkSurfaceArgs(remote, target, args, io) {
|
|
1001
|
+
// The state is the one word after the instance that is no flag and no flag's value (as bin reads it).
|
|
1002
|
+
const words = [];
|
|
1003
|
+
for (let i = 2; i < args.length; i++) { if (args[i] === "--home" || args[i] === "--dir") i++; else if (!args[i].startsWith("--")) words.push(args[i]); }
|
|
1004
|
+
if (words.length === 1 && words[0] === "on") {
|
|
1005
|
+
const valueOf = (flag) => { const i = args.indexOf(flag); return i >= 0 && args[i + 1] !== undefined && !args[i + 1].startsWith("--") ? args[i + 1] : undefined; };
|
|
1006
|
+
const home = valueOf("--home");
|
|
1007
|
+
// The lineage is read in the scope the verb is sent to: its explicit --dir, else the registered workspace.
|
|
1008
|
+
const status = runRemote(target, ["status", "--json", "--dir", valueOf("--dir") ?? target.workspace], { ...io, input: undefined }).envelope;
|
|
1009
|
+
if (!status.ok) throw serverError(status.error?.code || "E_REMOTE", `cannot read ${args[1]} on ${target.sshHost} before setting its related work: ${status.error?.message || "status failed"}`);
|
|
1010
|
+
const row = (status.result?.agents || []).flatMap((a) => a.instances || []).find((i) => i?.home && resolve(i.home) === resolve(home));
|
|
1011
|
+
if (row && relatedWorkBinding(row)?.sibling) throw siblingNeedsRelatedWork(remote, target);
|
|
1012
|
+
}
|
|
1013
|
+
return ["same-work"];
|
|
1014
|
+
}
|
|
1015
|
+
|
|
1016
|
+
/** A host's `status --json` result with each instance row's flag in this kernel's words, as rowRelatedWork
|
|
1017
|
+
* reads it (the roster's rule): `relatedWork: true` or no key, and `sameWork: true` only beside it.
|
|
1018
|
+
* Everything else is the host's answer as it gave it. */
|
|
1019
|
+
function relatedWorkRows(result) {
|
|
1020
|
+
if (!result || typeof result !== "object" || !Array.isArray(result.agents)) return result;
|
|
1021
|
+
const features = hostFeatures(result);
|
|
1022
|
+
const row = (i) => {
|
|
1023
|
+
if (!i || typeof i !== "object") return i;
|
|
1024
|
+
const { sameWork: _sameWork, relatedWork: _relatedWork, ...rest } = i;
|
|
1025
|
+
return { ...rest, ...rowRelatedWork(i, features) };
|
|
1026
|
+
};
|
|
1027
|
+
return { ...result, agents: result.agents.map((a) => (a && typeof a === "object" && Array.isArray(a.instances) ? { ...a, instances: a.instances.map(row) } : a)) };
|
|
1028
|
+
}
|
|
1029
|
+
|
|
1030
|
+
/** The answer of an older host's `instance same-work`, `{ instance, sameWork }`, in this kernel's words, as
|
|
1031
|
+
* this kernel's verb answers: `relatedWork` beside its `sameWork` (an older host binds a parent only). A
|
|
1032
|
+
* refusal is relayed as is. */
|
|
1033
|
+
function relatedWorkAnswer(envelope) {
|
|
1034
|
+
if (!envelope?.ok || !envelope.result || typeof envelope.result !== "object" || !Object.hasOwn(envelope.result, "sameWork")) return envelope;
|
|
1035
|
+
const on = envelope.result.sameWork === true;
|
|
1036
|
+
return { ...envelope, result: { ...envelope.result, relatedWork: on, sameWork: on } };
|
|
1037
|
+
}
|
|
1038
|
+
|
|
926
1039
|
/** The Desktop's per-instance reads and lifecycle plans, as the host's kernel
|
|
927
1040
|
* answers them: the feature and API number the host must advertise first. */
|
|
928
1041
|
const HOST_SURFACES = {
|
|
@@ -938,8 +1051,9 @@ const HOST_SURFACES = {
|
|
|
938
1051
|
"instance background": { feature: "instance-background" },
|
|
939
1052
|
// Feature instance-pin: the feature alone, as instance background.
|
|
940
1053
|
"instance pin": { feature: "instance-pin" },
|
|
941
|
-
// Feature instance-
|
|
942
|
-
|
|
1054
|
+
// Feature instance-related-work: the feature alone, as instance color; a host with only instance-same-work
|
|
1055
|
+
// is asked by the old name (relatedWorkSurfaceArgs).
|
|
1056
|
+
"instance related-work": { feature: "instance-related-work" },
|
|
943
1057
|
};
|
|
944
1058
|
|
|
945
1059
|
function requireSurface(remote, target, surface) {
|
|
@@ -948,16 +1062,18 @@ function requireSurface(remote, target, surface) {
|
|
|
948
1062
|
}
|
|
949
1063
|
}
|
|
950
1064
|
|
|
951
|
-
/** `readiness`, `instance events|git|diff|stop|color|background|pin|
|
|
1065
|
+
/** `readiness`, `instance events|git|diff|stop|color|background|pin|related-work` and `retire --plan` on the
|
|
952
1066
|
* host: the instance is addressed as every routed session command addresses
|
|
953
1067
|
* it (its name through a saved route or the host's roster, or an exact
|
|
954
1068
|
* --home), the scope is an explicit --dir on the host or the registered
|
|
955
1069
|
* workspace (readiness of a home is its own context), and the host's
|
|
956
1070
|
* envelope is relayed unchanged. */
|
|
957
1071
|
function routeHostSurface(serverId, cmd, oatsArgs, io) {
|
|
1072
|
+
// `instance same-work` is the deprecated alias of `instance related-work` (the dispatch said so): one route.
|
|
1073
|
+
if (cmd === "instance" && oatsArgs[0] === "same-work") oatsArgs = ["related-work", ...oatsArgs.slice(1)];
|
|
958
1074
|
const key = cmd === "instance" ? `instance ${oatsArgs[0]}` : cmd === "retire" ? "retire plan" : cmd;
|
|
959
1075
|
const surface = HOST_SURFACES[key];
|
|
960
|
-
if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff, stop, color, background, pin and
|
|
1076
|
+
if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff, stop, color, background, pin and related-work only (not ${key})`);
|
|
961
1077
|
const args = [...oatsArgs];
|
|
962
1078
|
const valueOf = (flag) => { const i = args.indexOf(flag); return i >= 0 && args[i + 1] !== undefined && !args[i + 1].startsWith("--") ? args[i + 1] : undefined; };
|
|
963
1079
|
const name = cmd === "readiness" ? undefined : args[cmd === "instance" ? 1 : 0];
|
|
@@ -970,10 +1086,14 @@ function routeHostSurface(serverId, cmd, oatsArgs, io) {
|
|
|
970
1086
|
target = route.target;
|
|
971
1087
|
if (home === undefined) args.push("--home", route.home);
|
|
972
1088
|
} else target = targetOf(io.server || getServer(serverId));
|
|
973
|
-
|
|
1089
|
+
const remote = checkRemote(target, io);
|
|
1090
|
+
// An older host knows `instance related-work` by its old name only: asked by that name, or refused.
|
|
1091
|
+
const oldName = key === "instance related-work" && sameWorkOnly(remote.features);
|
|
1092
|
+
if (oldName) args.splice(0, 1, ...relatedWorkSurfaceArgs(remote, target, args, io));
|
|
1093
|
+
else requireSurface(remote, target, surface);
|
|
974
1094
|
if (!args.includes("--dir") && !(cmd === "readiness" && home !== undefined)) args.push("--dir", target.workspace);
|
|
975
1095
|
const { envelope, stderr } = runRemote(target, [cmd, ...args, "--json"], io);
|
|
976
|
-
return { envelope, stderr };
|
|
1096
|
+
return { envelope: oldName ? relatedWorkAnswer(envelope) : envelope, stderr };
|
|
977
1097
|
}
|
|
978
1098
|
|
|
979
1099
|
// ------------------------------------------------------------------- roster
|
|
@@ -1021,6 +1141,11 @@ const rowBackground = (i) => (i.background === true ? { background: true } : {})
|
|
|
1021
1141
|
/** `pinned` (feature instance-pin) as `background`: relayed ONLY when the host's row says exactly `true`;
|
|
1022
1142
|
* absent is the only reading of "not pinned", so any other value (`"true"`, `1`) is dropped, never false. */
|
|
1023
1143
|
const rowPinned = (i) => (i.pinned === true ? { pinned: true } : {});
|
|
1144
|
+
/** `board` (feature instance-board) as the host's row says it, read by this kernel's own rule
|
|
1145
|
+
* (lib/instance-board.mjs readRemoteBoard: every fact and question within its rules and the whole within
|
|
1146
|
+
* the row bound, else an empty board): relayed ONLY when the host's row has the key, so a host whose
|
|
1147
|
+
* kernel predates the feature says nothing. */
|
|
1148
|
+
const rowBoard = (i) => (Object.hasOwn(i, "board") ? { board: readRemoteBoard(i.board) } : {});
|
|
1024
1149
|
/** `retire` (feature status-retire-state) as `waitingOnYou` is, relayed ONLY when the host's row has the
|
|
1025
1150
|
* key: a host whose kernel predates the feature omits it, and its rows say nothing. Absent is the
|
|
1026
1151
|
* only reading of "no retire", so a value the kernel's own read refuses is dropped, never null. */
|
|
@@ -1028,9 +1153,14 @@ const rowRetire = (i) => {
|
|
|
1028
1153
|
const retire = Object.hasOwn(i, "retire") ? readRetireState(i.retire) : undefined;
|
|
1029
1154
|
return retire ? { retire } : {};
|
|
1030
1155
|
};
|
|
1031
|
-
/** `
|
|
1032
|
-
* `
|
|
1033
|
-
|
|
1156
|
+
/** `relatedWork` (feature instance-related-work) as `background`: relayed ONLY as `true`, when the host's row
|
|
1157
|
+
* says `relatedWork: true`, or, from a host whose `features` (hostFeatures) have instance-same-work and not
|
|
1158
|
+
* instance-related-work, `sameWork: true`: that older kernel's flag, a parent binding by the old name. Anything
|
|
1159
|
+
* else, and a host that omits it, is absent. Beside it, `sameWork: true` (feature instance-same-work, the
|
|
1160
|
+
* compatibility layer) when the host's row says exactly that: a parent binding, which every host reports by
|
|
1161
|
+
* both names; never without `relatedWork`. The one rule of both keys, for the roster and the routed status. */
|
|
1162
|
+
const rowRelatedWork = (i, features) => (i.relatedWork === true || (sameWorkOnly(features) && i.sameWork === true)
|
|
1163
|
+
? { relatedWork: true, ...(i.sameWork === true ? { sameWork: true } : {}) } : {});
|
|
1034
1164
|
/** `sessionEnd` (feature session-resume, #1628) as `retire` is: relayed ONLY when the host's row has the
|
|
1035
1165
|
* key, which a host whose kernel predates the feature never sends, so its rows say nothing. A value that
|
|
1036
1166
|
* is not one of the contract's (lib/session-resume-contract.mjs SESSION_END) drops the key. */
|
|
@@ -1136,10 +1266,12 @@ export async function rosterGroups({ server, workspaceKeys, io = {} } = {}) {
|
|
|
1136
1266
|
const snap = routeOf(i);
|
|
1137
1267
|
g.instances.push({
|
|
1138
1268
|
server: g.server, instance: i.instance, agent: a.name, home: i.home || snap?.home, agentsRoot: result.root,
|
|
1139
|
-
|
|
1269
|
+
// A session provider's row (feature session-providers): its backend's name, `session`, `open`
|
|
1270
|
+
// and `runtimeState`, relayed in the kernel's own shapes only (relayedProviderRow).
|
|
1271
|
+
harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null, ...(relayedProviderRow(i) ?? {}),
|
|
1140
1272
|
...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
|
|
1141
1273
|
running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
|
|
1142
|
-
...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowPinned(i), ...
|
|
1274
|
+
...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowPinned(i), ...rowBoard(i), ...rowRelatedWork(i, g.probe.features), ...rowSessionEnd(i),
|
|
1143
1275
|
// Every row the host reports is addressed by its home, saved
|
|
1144
1276
|
// route or not; savedRoute says only that it was spawned from here.
|
|
1145
1277
|
retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, addressable: true, missingRemotely: false,
|
|
@@ -1553,7 +1685,9 @@ function probeHostOats(target, io) {
|
|
|
1553
1685
|
const r = runHostCommand(target, [target.oatsPath, "version", "--json"], { ...io, timeoutMs: 60000 });
|
|
1554
1686
|
if (r.status === 255) throw sshFailed(target, r);
|
|
1555
1687
|
if (r.status === 126 || r.status === 127) return { missing: true };
|
|
1556
|
-
const
|
|
1688
|
+
const envelope = parseRemoteEnvelope(r.stdout);
|
|
1689
|
+
if (!envelope.ok) throw relayedFailure(envelope, "version --json");
|
|
1690
|
+
const probe = envelope.result || {};
|
|
1557
1691
|
if (probe.desktopApi !== 1 || typeof probe.version !== "string") throw serverError("E_REMOTE_INCOMPATIBLE", `${target.oatsPath} at ${target.sshHost} answered an unknown version payload: ${JSON.stringify(probe).slice(0, 200)}`);
|
|
1558
1692
|
return { version: probe.version, features: Array.isArray(probe.features) ? probe.features.map(String) : [] };
|
|
1559
1693
|
}
|
package/lib/session-inspect.mjs
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
|
-
/** inspectInstanceSession: what a home's
|
|
2
|
-
* recorded launch and receipts, the retirement baseline, the Herdr refusal)
|
|
3
|
-
*
|
|
1
|
+
/** inspectInstanceSession: what a home's session is, read under the home's runtime authority (its
|
|
2
|
+
* recorded launch and receipts, the retirement baseline, the Herdr refusal): a tmux session's agent
|
|
3
|
+
* pane and its liveness, or, for a home on a session provider (lib/session-providers.mjs), the
|
|
4
|
+
* provider's own answer. A leaf (awebai/oats#1630): `oats session inspect` reads it without loading core.mjs, which
|
|
4
5
|
* imports these helpers and re-exports what it exported. */
|
|
5
6
|
import { realPathOrNearest, canonicalHomePath } from "./real-path.mjs";
|
|
6
7
|
import { existsSync, readFileSync, lstatSync } from "node:fs";
|
|
@@ -9,6 +10,7 @@ import { createHash } from "node:crypto";
|
|
|
9
10
|
import { inspectSessionTarget } from "./session-input.mjs";
|
|
10
11
|
import { liveWaiting } from "./instance-events.mjs";
|
|
11
12
|
import { oatsError, herdrInstanceRemoved } from "./errors.mjs";
|
|
13
|
+
import { homeSessionProvider, isSessionProviderName, inspectProviderSession, launchSentOf, providerEndpointDifferences, providerRuntimeOf, unsettledLaunchSaid } from "./session-providers.mjs";
|
|
12
14
|
|
|
13
15
|
/** A cleanup descriptor is usable only if it can DRIVE the retry, so it is checked
|
|
14
16
|
* as the strict contract its one producer writes — the rollback above — and to the
|
|
@@ -112,15 +114,53 @@ function refuseHerdrHome(home) {
|
|
|
112
114
|
if (recordsHerdr(readJsonOrUndefined(join(home, "instance.json")), readJsonOrUndefined(findRetirementBaseline(home)))) throw herdrInstanceRemoved(basename(home));
|
|
113
115
|
}
|
|
114
116
|
|
|
117
|
+
/** What a receipt authorises: `{ launched: false }` (with `planned: { backend, provider }` for a home
|
|
118
|
+
* that will launch on a session provider), `{ launched: true, tmux }` for a tmux session, or
|
|
119
|
+
* `{ launched: true, session }` for a session provider's (`session`: providerRuntimeOf's
|
|
120
|
+
* `{ backend, provider, endpoint, stoppedAt }`); undefined when it is none of these. */
|
|
115
121
|
function runtimeAuthorityOf(baseline) {
|
|
116
122
|
const runtime = baseline?.runtime;
|
|
117
123
|
if (!isPlainObject(runtime) || typeof runtime.launched !== "boolean") return undefined;
|
|
118
|
-
if (!runtime.launched)
|
|
124
|
+
if (!runtime.launched) {
|
|
125
|
+
if (runtime.backend === undefined && runtime.provider === undefined) return { launched: false };
|
|
126
|
+
if (!isSessionProviderName(runtime.backend) || typeof runtime.provider !== "string" || !runtime.provider || runtime.launchSent !== undefined) return undefined;
|
|
127
|
+
return { launched: false, planned: { backend: runtime.backend, provider: runtime.provider, launchSent: null } };
|
|
128
|
+
}
|
|
119
129
|
if (runtime.sessionTarget !== undefined) return undefined;
|
|
130
|
+
// A launch that was sent for a home never launched, and has no recorded outcome (lib/session-providers.mjs
|
|
131
|
+
// launchSentOf): no endpoint yet. The home is still a planned one, whose record says not launched.
|
|
132
|
+
if (runtime.tmux === undefined && runtime.endpoint === undefined) {
|
|
133
|
+
const launchSent = launchSentOf(runtime);
|
|
134
|
+
if (!launchSent || !isSessionProviderName(runtime.backend) || typeof runtime.provider !== "string" || !runtime.provider) return undefined;
|
|
135
|
+
return { launched: false, planned: { backend: runtime.backend, provider: runtime.provider, launchSent } };
|
|
136
|
+
}
|
|
137
|
+
if (runtime.tmux === undefined) {
|
|
138
|
+
const session = providerRuntimeOf(runtime);
|
|
139
|
+
return session ? { launched: true, session: { backend: session.backend, provider: session.provider, endpoint: session.endpoint, stoppedAt: session.stoppedAt, launchSent: session.launchSent } } : undefined;
|
|
140
|
+
}
|
|
120
141
|
const tmux = runtime.tmux;
|
|
121
142
|
if (!isPlainObject(tmux) || ![tmux.session, tmux.window, tmux.socket].every((v) => typeof v === "string" && v.length > 0)) return undefined;
|
|
122
143
|
return { launched: true, tmux: { session: tmux.session, window: tmux.window, socket: resolve(tmux.socket) } };
|
|
123
144
|
}
|
|
145
|
+
/** The fields of instance.json's session that differ from the receipt's, for a home on a session
|
|
146
|
+
* provider, launched (`authority.session`) or planned (`authority.planned`: no endpoint yet). */
|
|
147
|
+
function providerDifferences(meta, authority) {
|
|
148
|
+
// While the receipt says a launch is unsettled, the record's endpoint is not compared: the
|
|
149
|
+
// launch that would have written it may have ended at any point (docs/design/2026-11-20-provider-home-lifecycle.md).
|
|
150
|
+
if (authority.session && !authority.session.launchSent) return providerEndpointDifferences(meta, authority.session);
|
|
151
|
+
const named = authority.session ?? authority.planned;
|
|
152
|
+
return [
|
|
153
|
+
...(meta?.backend === named.backend ? [] : ["backend"]),
|
|
154
|
+
...(meta?.session?.provider === named.provider ? [] : ["session.provider"]),
|
|
155
|
+
];
|
|
156
|
+
}
|
|
157
|
+
/** The fields of instance.json's endpoint, of whichever backend the receipt records, that differ
|
|
158
|
+
* from the receipt's: tmux's labels, or a session provider's. A receipt that records no endpoint
|
|
159
|
+
* (never launched, planned on tmux) has none to differ from. */
|
|
160
|
+
function endpointDifferences(meta, authority) {
|
|
161
|
+
if (authority.session || authority.planned) return providerDifferences(meta, authority);
|
|
162
|
+
return authority.launched ? tmuxEndpointDifferences(meta, authority) : [];
|
|
163
|
+
}
|
|
124
164
|
|
|
125
165
|
/** The fields of instance.json's tmux endpoint that differ from the one the independent receipt
|
|
126
166
|
* authorises, as fixed labels in a fixed order: `tmux.session`, `tmux.window`, `tmux.socket`. */
|
|
@@ -133,6 +173,8 @@ function tmuxEndpointDifferences(meta, authority) {
|
|
|
133
173
|
}
|
|
134
174
|
/** instance.json's tmux endpoint is the one the independent receipt authorises. */
|
|
135
175
|
function tmuxEndpointAgrees(meta, authority) { return tmuxEndpointDifferences(meta, authority).length === 0; }
|
|
176
|
+
/** instance.json's endpoint, of whichever backend the receipt records, is the one it authorises. */
|
|
177
|
+
function endpointAgrees(meta, authority) { return endpointDifferences(meta, authority).length === 0; }
|
|
136
178
|
|
|
137
179
|
/** Whether a blocked or incomplete launch prompt explains metadata's `launched: false` beside a
|
|
138
180
|
* launched receipt. */
|
|
@@ -142,18 +184,23 @@ function promptRetained(meta, authority) {
|
|
|
142
184
|
/** A blocked prompt is a retained runtime, not evidence that no process exists.
|
|
143
185
|
* The independent launched receipt and exact endpoint agreement remain mandatory. */
|
|
144
186
|
function launchStateAgrees(meta, authority) {
|
|
145
|
-
|
|
187
|
+
// A launch that was sent for a home never launched (lib/session-providers.mjs launchSentOf): the
|
|
188
|
+
// record says `launched: true` meanwhile, so that a kernel from before session providers refuses
|
|
189
|
+
// the home; the two files are written one after the other, so either value agrees.
|
|
190
|
+
if ((authority.session ?? authority.planned)?.launchSent) return true;
|
|
191
|
+
return meta.launched === authority.launched || (promptRetained(meta, authority) && !authority.session && tmuxEndpointAgrees(meta, authority));
|
|
146
192
|
}
|
|
147
193
|
|
|
148
194
|
/** The refusal for instance.json that disagrees with the independent receipt. `details.fields` names
|
|
149
195
|
* what differs, from a fixed vocabulary in a fixed order: `launched` (unless a blocked or incomplete
|
|
150
|
-
* launch prompt explains metadata's `launched: false`), then
|
|
151
|
-
* tmux
|
|
196
|
+
* launch prompt explains metadata's `launched: false`), then each differing endpoint field: for a
|
|
197
|
+
* launched tmux receipt `tmux.session`, `tmux.window`, `tmux.socket`; for a session provider's
|
|
198
|
+
* `backend`, `session.provider`, `session.endpoint`. Labels only: never a path, a value or the receipt. Callers throw it only once
|
|
152
199
|
* their own comparison has refused, so these labels diagnose a refusal and never decide one. */
|
|
153
200
|
function authorityMismatch(message, meta, authority) {
|
|
154
201
|
const fields = [
|
|
155
|
-
...(meta.launched === authority.launched || promptRetained(meta, authority) ? [] : ["launched"]),
|
|
156
|
-
...(
|
|
202
|
+
...(meta.launched === authority.launched || promptRetained(meta, authority) || (authority.session ?? authority.planned)?.launchSent ? [] : ["launched"]),
|
|
203
|
+
...endpointDifferences(meta, authority),
|
|
157
204
|
];
|
|
158
205
|
return Object.assign(oatsError("E_RUNTIME_AUTHORITY_MISMATCH", message), { details: { fields } });
|
|
159
206
|
}
|
|
@@ -194,9 +241,17 @@ function instanceSessionTarget(home, { absentMeta } = {}) {
|
|
|
194
241
|
if (!isPlainObject(meta)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read ${recordPath}: it holds no JSON object`);
|
|
195
242
|
const authority = baseline.version === RETIRE_BASELINE_VERSION && receiptRecordsHome(baseline, canonicalHomePath(home)) && runtimeAuthorityOf(baseline);
|
|
196
243
|
if (!authority) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or invalid for ${home}`);
|
|
197
|
-
if (!launchStateAgrees(meta, authority) ||
|
|
198
|
-
|
|
244
|
+
if (!launchStateAgrees(meta, authority) || !endpointAgrees(meta, authority)) throw authorityMismatch("instance metadata disagrees with independent session receipt", meta, authority);
|
|
245
|
+
// `unsettled`: a launch that was sent to the home's provider and never recorded, whether the home
|
|
246
|
+
// was launched before or not: `{ backend, provider, launchSent }`, or null. The one place that says so.
|
|
247
|
+
const recorded = authority.session ?? authority.planned ?? null;
|
|
248
|
+
return { home, target: authority.tmux ? { backend: "tmux", ...authority.tmux } : undefined, meta,
|
|
249
|
+
...(authority.session ? { session: authority.session } : {}), ...(authority.planned ? { planned: authority.planned } : {}),
|
|
250
|
+
unsettled: recorded?.launchSent ? { backend: recorded.backend, provider: recorded.provider, launchSent: recorded.launchSent } : null };
|
|
199
251
|
}
|
|
252
|
+
/** The answer for a tmux-only path that meets a home on a session provider (`s`: instanceSessionTarget's
|
|
253
|
+
* answer): the home has no tmux endpoint to read or act on. Undefined for any other home. */
|
|
254
|
+
function providerHomeOf(s) { return s.session ?? s.planned; }
|
|
200
255
|
|
|
201
256
|
/** `wakeHold` (feature wake-hold): whether this home's capabilities said its dialogs become the claims
|
|
202
257
|
* a wake holds on, from the home's record (instance.json `dialogClaims`): `on-claims` if any entry is
|
|
@@ -207,11 +262,47 @@ function wakeHoldOf(meta) {
|
|
|
207
262
|
return answers.includes("reported") ? "on-claims" : answers.includes("none") ? "not-exposed" : "unknown";
|
|
208
263
|
}
|
|
209
264
|
|
|
210
|
-
/**
|
|
265
|
+
/** What a provider home's `session` is in an answer: the capability that supplies its backend and
|
|
266
|
+
* the endpoint the kernel recorded (null before the first launch). */
|
|
267
|
+
export function sessionOf(session) { return { provider: session.provider, endpoint: session.endpoint ?? null }; }
|
|
268
|
+
/** A launched provider home's session, as inspect answers it (docs/desktop-cli-api.md): the
|
|
269
|
+
* provider's own `{ present, state, running, open }`, with the kernel's `backend`, `session`,
|
|
270
|
+
* `waitingOnYou` and `wakeHold`; no pane and no size. Kernel-owned: a home OATS stopped (`stoppedAt`)
|
|
271
|
+
* answers stopped WITHOUT calling the provider, so a session the provider would restart on the next
|
|
272
|
+
* input reads as OATS left it. A provider that fails, refuses or answers outside the contract's
|
|
273
|
+
* words is E_SESSION_UNAVAILABLE, never stopped. `waitingOnYou` is a producer's claim, read
|
|
274
|
+
* whenever the session is not stopped (providerMayWait): an idle session can be the one waiting
|
|
275
|
+
* on a person. */
|
|
276
|
+
function inspectProviderHome(s, wakeHold, io) {
|
|
277
|
+
const answer = { home: s.home, backend: s.session.backend };
|
|
278
|
+
const kernel = { wakeHold, session: sessionOf(s.session) };
|
|
279
|
+
if (s.session.stoppedAt !== null) return { ...answer, present: false, state: "stopped", running: false, waitingOnYou: null, ...kernel, open: null };
|
|
280
|
+
const found = homeSessionProvider(s.home, s.meta, s.session.provider, s.session.backend);
|
|
281
|
+
if (found.problem) throw oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${found.problem}`);
|
|
282
|
+
const inspected = inspectProviderSession(found.binding, s.session.endpoint, { io });
|
|
283
|
+
if (inspected.unavailable) throw oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${inspected.unavailable}`);
|
|
284
|
+
const { present, state, running, open } = inspected.observed;
|
|
285
|
+
return { ...answer, present, state, running, waitingOnYou: providerMayWait(inspected.observed) ? liveWaiting(s.home) : null, ...kernel, open };
|
|
286
|
+
}
|
|
287
|
+
/** Whether a provider's session, as observed, can be waiting on a human: whenever it is not stopped
|
|
288
|
+
* (`running` true or null). An agent that waits on a question is idle where its provider runs it,
|
|
289
|
+
* so it reads `running: null`: the claim is shown then too. Never for a session that is gone (a
|
|
290
|
+
* lost one included) or in error, nor for a home OATS stopped, which is never observed. */
|
|
291
|
+
function providerMayWait(observed) { return observed.present === true && observed.running !== false; }
|
|
292
|
+
|
|
293
|
+
/** `io` (`{ exec }`) is the tmux and process-table seam inspectSessionTarget takes; for a home on a
|
|
294
|
+
* session provider, `io.spawnSync` is the provider call's. */
|
|
211
295
|
export function inspectInstanceSession(home, { io, absentMeta } = {}) {
|
|
212
296
|
if (typeof home === "string" && isAbsolute(home) && !existsSync(home)) return { home: realPathOrNearest(home), backend: null, present: false, state: "stopped", running: false, waitingOnYou: null, wakeHold: wakeHoldOf(null) };
|
|
213
297
|
const s = instanceSessionTarget(home, { absentMeta });
|
|
214
298
|
const wakeHold = wakeHoldOf(s.meta);
|
|
299
|
+
// A launch that was sent and never recorded (launchSentOf), on a home launched before or not: a
|
|
300
|
+
// session may run that no record names. Unknown, never "not launched" or "stopped", until a stop
|
|
301
|
+
// or a start has settled it.
|
|
302
|
+
if (s.unsettled) throw oatsError("E_SESSION_UNAVAILABLE", unsettledLaunchSaid(basename(s.home), s.unsettled.backend, s.unsettled.launchSent));
|
|
303
|
+
if (s.session) return inspectProviderHome(s, wakeHold, io);
|
|
304
|
+
// A home that will launch on a session provider says which: nothing was launched yet.
|
|
305
|
+
if (s.planned) return { home: s.home, backend: s.planned.backend, present: false, state: "not-launched", running: false, waitingOnYou: null, wakeHold, session: sessionOf(s.planned), open: null };
|
|
215
306
|
if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched", running: false, waitingOnYou: null, wakeHold };
|
|
216
307
|
let observed;
|
|
217
308
|
try { observed = inspectSessionTarget(s.target, io, { includeSize: true }); }
|
|
@@ -226,4 +317,4 @@ export function inspectInstanceSession(home, { io, absentMeta } = {}) {
|
|
|
226
317
|
* fallback shell nor a dead pane. Only such a session can be waiting on a human. */
|
|
227
318
|
function harnessRunning(observed) { return observed?.present === true && observed.state !== "shell" && observed.state !== "stopped"; }
|
|
228
319
|
|
|
229
|
-
export { RETIRE_BASELINE_VERSION, authorityMismatch, harnessRunning, instanceSessionTarget, instancesRetirementRoot, isPlainObject, launchStateAgrees, missingSessionReceipt, readJsonOrUndefined, receiptHomeIdentity, receiptRecordsHome, recordsHerdr, refuseHerdrHome, runtimeAuthorityOf, tmuxEndpointAgrees };
|
|
320
|
+
export { RETIRE_BASELINE_VERSION, authorityMismatch, endpointAgrees, harnessRunning, providerHomeOf, providerMayWait, instanceSessionTarget, instancesRetirementRoot, isPlainObject, launchStateAgrees, missingSessionReceipt, readJsonOrUndefined, receiptHomeIdentity, receiptRecordsHome, recordsHerdr, refuseHerdrHome, runtimeAuthorityOf, tmuxEndpointAgrees };
|