@awebai/oats 0.69.23 → 0.70.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +112 -20
- package/docs/capabilities.md +697 -11
- package/docs/capability-manifest.schema.json +66 -0
- package/docs/configuration.md +27 -7
- package/docs/design/2026-11-19-sandboxes.md +595 -121
- package/docs/design/2026-11-20-provider-home-lifecycle.md +322 -0
- package/docs/design/README.md +7 -3
- package/docs/desktop-cli-api.md +330 -9
- package/docs/desktop.md +181 -48
- package/docs/execution-targets.md +210 -4
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +24 -3
- package/docs/integrations.md +2 -2
- package/docs/knowledge-capability-authoring.md +1 -1
- package/docs/knowledge-reference/proposal.md +10 -0
- package/docs/knowledge.md +20 -11
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.69.24.md +264 -0
- package/docs/release-notes/v0.70.0.md +155 -0
- package/docs/souls-and-instances.md +57 -0
- package/docs/trust-model.md +8 -1
- package/docs/tui.md +21 -1
- package/docs/upgrading.md +19 -5
- package/docs/workspaces.md +13 -5
- package/lib/automation-scope.mjs +1 -1
- package/lib/capability-show.mjs +20 -1
- package/lib/command-flags.mjs +2 -2
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1455 -203
- package/lib/errors.mjs +4 -1
- package/lib/home-integrity.mjs +329 -0
- package/lib/hook-env.mjs +107 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-events.mjs +32 -5
- package/lib/instance-git.mjs +9 -0
- package/lib/instance-inspect.mjs +107 -9
- package/lib/instance-lifecycle.mjs +15 -3
- package/lib/instance-listing.mjs +101 -8
- package/lib/instance-resolution.mjs +85 -2
- package/lib/instance-upgrade.mjs +170 -14
- package/lib/kernel-features.mjs +10 -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/remote.mjs +33 -1
- package/lib/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +12 -1
- package/lib/sandbox-allowances.mjs +329 -0
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +38 -5
- package/lib/session-inspect.mjs +123 -87
- package/lib/session-providers.mjs +575 -0
- package/lib/session-receipt.mjs +93 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- package/lib/upgrade-state.mjs +6 -1
- package/lib/worktree-hooks.mjs +18 -2
- package/lib/worktree.mjs +21 -7
- package/package-catalog.json +2 -2
- 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 +23 -1
- package/packages/client/deployment-panel.mjs +25 -3
- 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/liveness.mjs +15 -4
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/remote-roster.mjs +6 -1
- 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/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- package/skills/oats-getting-started/SKILL.md +3 -3
package/lib/instance-inspect.mjs
CHANGED
|
@@ -14,7 +14,7 @@ import { spawnSync } from "node:child_process";
|
|
|
14
14
|
import { accessSync, constants as fsConstants, existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
|
|
15
15
|
import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
|
|
16
16
|
import { capabilityManifests, skillEntriesIn, kernelBin, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, preparedSoulIdOf, stableSoulId, launchFolderTrust, previewLaunchEnvironment, removedLaunchEnv, homeDeclaredLaunchEnv, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
|
|
17
|
-
import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance, resolutionContractWarnings, soulCopyDigests, soulsOffered } from "./instance-resolution.mjs";
|
|
17
|
+
import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, homeSandboxSource, liveTeams, prepareInstance, resolutionContractWarnings, soulCopyDigests, soulsOffered } from "./instance-resolution.mjs";
|
|
18
18
|
import { declaredSettings, locatedContractWarnings } from "./capability-contract.mjs";
|
|
19
19
|
import { kernelCompatibility, unsafeRelPath } from "./resolve.mjs";
|
|
20
20
|
import { compareCodepoints, decodeText, FILES_PER_SKILL, SKILL_DOC_BUDGET, skillDocDescription, TEXT_LIMIT } from "./capability-show.mjs";
|
|
@@ -34,6 +34,10 @@ 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, recordsSessionProvider, sessionProvidersOf } from "./session-providers.mjs";
|
|
38
|
+
import { capabilityRuntimeOf, kernelModuleDir, moduleCopyProblemAt, providerHomeTrust, runDirOf } from "./home-integrity.mjs";
|
|
39
|
+
import { treeDisagreement } from "./tree-copy.mjs";
|
|
40
|
+
import { homeSandboxAllowances, sandboxWritePathsRefusal } from "./sandbox-allowances.mjs";
|
|
37
41
|
import { sameRepo } from "./repo-moves.mjs";
|
|
38
42
|
import { kernelNode } from "./stable-node.mjs";
|
|
39
43
|
|
|
@@ -92,11 +96,17 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
|
|
|
92
96
|
meta = upgradeHomeMeta(meta, realHome);
|
|
93
97
|
// Only the home's own module copies: without <home>/.oats/modules the kernel's
|
|
94
98
|
// manifest lookup would fall through to a classic config chain — never here.
|
|
99
|
+
// A provider home's modules are the ones its receipt records, read from the kernel's copies of
|
|
100
|
+
// them (lib/home-integrity.mjs): a home whose own modules directory or record of them is gone
|
|
101
|
+
// is read the same.
|
|
102
|
+
const trust = providerHomeTrust(realHome), trustedRows = trust ? capabilityRuntimeOf(realHome, meta, trust) : [];
|
|
95
103
|
let manifests = {}; const loadProblems = [];
|
|
96
|
-
|
|
104
|
+
// (A provider home whose receipt holds no composition lists no module: it says why, and what to do.)
|
|
105
|
+
if (trust?.problem) loadProblems.push({ code: "module-copy-untrusted", message: trust.problem });
|
|
106
|
+
if (trust || existsSync(join(realHome, ".oats", "modules"))) {
|
|
97
107
|
try { manifests = capabilityManifests(realHome); } catch (e) { loadProblems.push({ code: "module-manifest-invalid", message: e.message }); }
|
|
98
108
|
}
|
|
99
|
-
const modules = obj(meta.modules) ? meta.modules : {};
|
|
109
|
+
const modules = trust ? Object.fromEntries(Object.entries(trust.composition?.modules ?? {}).map(([id, m]) => [id, { from: m.from ?? null }])) : obj(meta.modules) ? meta.modules : {};
|
|
100
110
|
const agentsRoot = dirname(dirname(dirname(realHome)));
|
|
101
111
|
const deployment = dirname(agentsRoot);
|
|
102
112
|
// The deployment's removed team keys (team model 3) refuse every reader of its oats-local.yaml, before
|
|
@@ -148,9 +158,11 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
|
|
|
148
158
|
soul: { name: meta.agent, repoKey: ws.soul?.repoKey ?? null, commit: ws.soul?.commit ?? null, external, path: null, soulDir, definition, problems: [...problems, ...loadProblems],
|
|
149
159
|
...(obj(ws.soul?.package) && typeof ws.soul.package.id === "string" ? { package: { id: ws.soul.package.id, soul: ws.soul.name ?? meta.agent, version: ws.soul.package.version ?? null, commit: ws.soul.package.commit ?? ws.soul.commit ?? null, integrity: ws.soul.package.digest ?? null } } : {}) },
|
|
150
160
|
workspace: { key: ws.key ?? null, name: typeof ws.name === "string" ? ws.name : discovery?.workspace?.name ?? null, deployment, commit: ws.commit ?? null, standalone: ws.standalone === true },
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
161
|
+
// (A provider home's modules are run from the kernel's copies of them: lib/home-integrity.mjs.)
|
|
162
|
+
modules: Object.keys(modules).sort().map((name) => ({ name, from: modules[name]?.from ?? null, manifest: manifests[name] ?? null, dir: runDirOf(realHome, name, trust) })),
|
|
163
|
+
// (A provider home's settings are its receipt's rows', never its own record's: lib/home-integrity.mjs.)
|
|
164
|
+
payloads: trust ? Object.fromEntries(trustedRows.map((c) => [c.id, obj(c.settings) ? c.settings : {}])) : obj(meta.providers) ? meta.providers : {},
|
|
165
|
+
payloadOrigins: Object.fromEntries((trust ? trustedRows : Array.isArray(meta.capabilities) ? meta.capabilities : []).filter((c) => c && typeof c.id === "string").map((c) => [c.id, obj(c.settingsOrigins) ? c.settingsOrigins : {}])),
|
|
154
166
|
slots, slotsFrom: Object.fromEntries(LAYERS.map((l) => [l, obj(ws.layers?.[l]) ? ws.layers[l].from ?? null : null])), discovery, discoveryError, resolutionError: null,
|
|
155
167
|
lock: null, prepared: null,
|
|
156
168
|
};
|
|
@@ -524,6 +536,9 @@ export function inspectDocument(t, { kernel }) {
|
|
|
524
536
|
return {
|
|
525
537
|
operationsApi: INSPECT_OPERATIONS_API, kernel, subject: t.subject, workspace: t.workspace,
|
|
526
538
|
souls: [soulRow(t)], layers, capabilities,
|
|
539
|
+
// Feature session-providers: the session backends this soul's (or home's) capabilities supply
|
|
540
|
+
// beside the kernel's own, what `--backend` takes here: [{ name, capability }].
|
|
541
|
+
...sessionProviderKeys(t),
|
|
527
542
|
// The capabilities the soul turned off (feature desktop-facts): its `off` over a workspace/team entry
|
|
528
543
|
// (reason "off"), or a `<slot>: none` that dropped a workspace default (reason "slot-none", slot).
|
|
529
544
|
capabilitiesOff: (t.turnedOff || []).map(({ name, reason, slot, overrides }) => ({ id: name, off: true, from: "soul", reason, ...(slot ? { slot } : {}), overrides })),
|
|
@@ -674,6 +689,14 @@ const item = (subject, status, { required = true, reason = null, producer = "ker
|
|
|
674
689
|
({ subject, status, required, reason: bounded(reason), producer, evidence, remedy: bounded(remedy), ...rest,
|
|
675
690
|
...(Array.isArray(rest.problems) ? { problems: rest.problems.map((p) => (obj(p) && typeof p.message === "string" ? { ...p, message: bounded(p.message) } : p)) } : {}) });
|
|
676
691
|
|
|
692
|
+
/** `sessionProviders` of an inspect answer: the session backends the target's capabilities supply
|
|
693
|
+
* and a spawn can select there, `[{ name, capability }]` sorted by name (lib/session-providers.mjs
|
|
694
|
+
* offeredSessionProviders over the target's modules). A malformed declaration is none: what is
|
|
695
|
+
* wrong with it is `oats capabilities show`'s to say. */
|
|
696
|
+
function sessionProviderKeys(t) {
|
|
697
|
+
const { providers } = offeredSessionProviders((t.modules || []).filter((x) => x.manifest).map((x) => ({ id: x.name, manifest: x.manifest })));
|
|
698
|
+
return { sessionProviders: providers.map(({ name, capability }) => ({ name, capability })) };
|
|
699
|
+
}
|
|
677
700
|
/** The team/workspace facts a provider receives, as hooks get them (teamEnv), and the soul's name and
|
|
678
701
|
* stable id as its hooks and dispatched commands get them. Every ambient OATS_* is removed first. */
|
|
679
702
|
function providerEnv(t, capability, settings) {
|
|
@@ -697,12 +720,16 @@ function moduleExecutable(dir, script) {
|
|
|
697
720
|
* directory, the script contained in it (moduleExecutable), one JSON `request` on stdin, the
|
|
698
721
|
* environment providerEnv's for the request's `settings`, SIGKILL at `timeoutMs`, at most
|
|
699
722
|
* BINDING_LIMITS of stdout, decoded as exactly one strict JSON document (whitespace around it
|
|
700
|
-
* allowed).
|
|
723
|
+
* allowed). A provider home's OWN copy is never run (the kernel runs its copy of it,
|
|
724
|
+
* lib/home-integrity.mjs, which a caller is handed as `dir`): "no-executable", with `problem`.
|
|
725
|
+
* → { doc } or { failure: "no-command" | "no-executable" (script) | "incomplete"
|
|
701
726
|
* (timedOut, signal, overflow) | "exit" (status) | "invalid" }. The caller judges the document. */
|
|
702
727
|
export function runModuleCommand(t, mod, dir, command, request, { timeoutMs = 30000 } = {}) {
|
|
703
728
|
const spec = command ? mod.manifest?.commands?.[command] : null;
|
|
704
729
|
if (typeof spec !== "string" || !spec.trim()) return { failure: "no-command" };
|
|
705
730
|
const [script, ...args] = spec.trim().split(/\s+/);
|
|
731
|
+
const untrusted = dir ? moduleCopyProblemAt(dir) : null;
|
|
732
|
+
if (untrusted) return { failure: "no-executable", script, problem: untrusted };
|
|
706
733
|
const file = dir ? moduleExecutable(dir, script) : null;
|
|
707
734
|
if (!file) return { failure: "no-executable", script };
|
|
708
735
|
// The environment is providerEnv's: ambient OATS_/OAS_/PI_ identity removed, the rest
|
|
@@ -736,7 +763,7 @@ export function runProviderCheck(t, mod, dir, { timeoutMs = 30000 } = {}) {
|
|
|
736
763
|
input: { context: { kind: "workspace", workspace: t.workspace.key, deployment: t.deployment, soul: t.soul.name, instance: t.meta?.instance ?? null, home: t.home }, action: { kind: "readiness" } } };
|
|
737
764
|
const run = runModuleCommand(t, mod, dir, check, request, { timeoutMs });
|
|
738
765
|
if (run.failure === "no-command") return unavailable("provider-not-qualified", `${mod.name} declares binding.check but no command ${JSON.stringify(check)}`);
|
|
739
|
-
if (run.failure === "no-executable") return unavailable("resource-not-found", `${mod.name}: the check executable ${run.script} is unavailable`);
|
|
766
|
+
if (run.failure === "no-executable") return unavailable("resource-not-found", run.problem ?? `${mod.name}: the check executable ${run.script} is unavailable`);
|
|
740
767
|
if (run.failure === "incomplete") return unavailable("provider-unavailable", `${mod.name} check did not complete${run.timedOut || run.signal ? " in time" : ""}`);
|
|
741
768
|
if (run.failure === "exit") return unavailable("provider-unavailable", `${mod.name} check exited ${run.status}`);
|
|
742
769
|
const invalid = () => unavailable("provider-unavailable", `${mod.name} check answered invalid binding data`);
|
|
@@ -818,6 +845,10 @@ export const PROVIDER_CHECK_BUDGET_MS = 60_000;
|
|
|
818
845
|
/** `oats readiness --json` on the workspace model. */
|
|
819
846
|
export async function readinessDocument(t, { selector = null, remoteOptions, catalog = null, budgetMs = PROVIDER_CHECK_BUDGET_MS } = {}) {
|
|
820
847
|
const installed = [], configured = [], member = [], providers = [];
|
|
848
|
+
// A provider home whose receipt holds no composition (lib/home-integrity.mjs): the kernel runs
|
|
849
|
+
// none of its capabilities, so it lists no module below. It is not ready, and says why.
|
|
850
|
+
const untrusted = t.home ? providerHomeTrust(t.home)?.problem : null;
|
|
851
|
+
if (untrusted) installed.push(item(t.soul.name, "fail", { producer: "instance modules", code: "module-copy-untrusted", reason: untrusted, remedy: `oats retire ${t.subject.instance} --force, then spawn it again (its retire hooks cannot be identified, so --force removes the home without running them)` }));
|
|
821
852
|
const cap = (id) => ({ capability: { id } });
|
|
822
853
|
if (t.resolutionError && !isTeamRefusal(t.resolutionError)) {
|
|
823
854
|
installed.push(item(t.soul.name, "fail", { producer: "workspace resolution", code: t.resolutionError.code, reason: t.resolutionError.message, evidence: t.resolutionError.details, remedy: "oats sync (the lock must provide every package capability the soul resolves)" }));
|
|
@@ -870,6 +901,38 @@ export async function readinessDocument(t, { selector = null, remoteOptions, cat
|
|
|
870
901
|
}
|
|
871
902
|
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
903
|
}
|
|
904
|
+
// A session provider's own readiness (lib/session-providers.mjs, the optional `check` command),
|
|
905
|
+
// relayed verbatim as a providers item, as a binding check is. For a home: the provider it runs
|
|
906
|
+
// on, required. For a soul: every provider its capabilities offer, not required (the soul can
|
|
907
|
+
// launch on tmux); a member capability's runs from a spawned home, as its binding check does.
|
|
908
|
+
for (const mod of t.modules) {
|
|
909
|
+
const offered = Object.values(sessionProvidersOf(mod.manifest).providers).filter((p) => p.commands.check);
|
|
910
|
+
for (const provider of offered) {
|
|
911
|
+
const onIt = t.home ? t.meta?.backend === provider.name && t.meta?.session?.provider === mod.name : false;
|
|
912
|
+
if (t.home && !onIt) continue;
|
|
913
|
+
const subject = `${mod.name} session backend ${provider.name}`;
|
|
914
|
+
const push = (status, rest) => providers.push(item(subject, status, { required: !!t.home, producer: "session provider check", ...rest, ...cap(mod.name) }));
|
|
915
|
+
const unknown = (code, message) => push("unknown", { result: null, problems: [{ code, message }], reason: message });
|
|
916
|
+
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; }
|
|
917
|
+
let binding;
|
|
918
|
+
if (t.home) {
|
|
919
|
+
const found = homeSessionProvider(t.home, t.meta, mod.name, provider.name);
|
|
920
|
+
if (found.problem) { unknown("resource-not-found", found.problem); continue; }
|
|
921
|
+
binding = found.binding;
|
|
922
|
+
} else {
|
|
923
|
+
let dir = null;
|
|
924
|
+
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; } }
|
|
925
|
+
if (!dir) { unknown("resource-not-found", `${mod.name}: a member module runs from a spawned home; inspect an instance (--home) for its check`); continue; }
|
|
926
|
+
const settings = obj(t.payloads[mod.name]) ? t.payloads[mod.name] : {};
|
|
927
|
+
binding = { home: null, meta: {}, capability: mod.name, name: provider.name, provider, moduleDir: dir, cap: { id: mod.name, settings }, digest: null,
|
|
928
|
+
env: { ...providerEnv(t, mod.name, settings), OATS_EVENT: "session", OATS_BACKEND: provider.name } };
|
|
929
|
+
}
|
|
930
|
+
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())) });
|
|
931
|
+
if (checked.unavailable) { unknown("provider-unavailable", checked.unavailable); continue; }
|
|
932
|
+
const status = PROVIDER_STATUS_ITEM[checked.result.status];
|
|
933
|
+
push(status, { result: checked.result, reason: status === "pass" ? null : checked.result.problems[0]?.message ?? `the provider reports ${checked.result.status}` });
|
|
934
|
+
}
|
|
935
|
+
}
|
|
873
936
|
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
937
|
const requiredStatuses = Object.values(checks).flatMap((c) => c.items.filter((i) => i.required).map((i) => i.status));
|
|
875
938
|
const byCapability = [...new Set(Object.values(checks).flatMap((c) => c.items.map((i) => i.capability?.id).filter(Boolean)))].sort().map((id) => {
|
|
@@ -878,9 +941,44 @@ export async function readinessDocument(t, { selector = null, remoteOptions, cat
|
|
|
878
941
|
return { capability: { id }, checks: Object.fromEntries(Object.keys(checks).map((name) => [name, of(name).length ? roll(of(name)) : "not-applicable"])),
|
|
879
942
|
ownReady: statuses.length > 0 && statuses.every((s) => s === "pass" || s === "not-applicable") };
|
|
880
943
|
});
|
|
944
|
+
// A home on a session provider: what its next launch may widen its harness's sandbox by
|
|
945
|
+
// (lib/sandbox-allowances.mjs), computed as a start computes it, from the deployment's
|
|
946
|
+
// configuration as it is now. Each host with the capability and the setting that asked for it,
|
|
947
|
+
// each path with its reason, what is missing and what was left out; or why there is none.
|
|
948
|
+
let sandbox;
|
|
949
|
+
if (t.home && recordsSessionProvider(t.meta)) {
|
|
950
|
+
const source = await homeSandboxSource(t.home, { remoteOptions });
|
|
951
|
+
if (source.unavailable) sandbox = { unavailable: source.unavailable };
|
|
952
|
+
else {
|
|
953
|
+
try {
|
|
954
|
+
sandbox = homeSandboxAllowances({ source, home: realpathSync(t.home), moduleNames: Object.keys(obj(t.meta.modules) ? t.meta.modules : {}) });
|
|
955
|
+
// What a start would refuse of the paths, read without creating one.
|
|
956
|
+
const refused = sandboxWritePathsRefusal(sandbox.write);
|
|
957
|
+
if (refused) throw refused;
|
|
958
|
+
}
|
|
959
|
+
catch (e) { if (e?.code !== "E_BACKEND_SANDBOX_HOST") throw e; sandbox = { refused: { code: e.code, message: e.message, details: e.details ?? null } }; }
|
|
960
|
+
}
|
|
961
|
+
}
|
|
962
|
+
// A home on a session provider: the kernel runs its own copies of the home's modules, never the
|
|
963
|
+
// home's (lib/home-integrity.mjs). This says which of the home's own copies differ from the
|
|
964
|
+
// ones the kernel runs: what the agent or its harness uses is then not what the kernel runs.
|
|
965
|
+
// It changes nothing the kernel does, and is compared here only, never on the status path.
|
|
966
|
+
let kernelCopies;
|
|
967
|
+
if (t.home) {
|
|
968
|
+
const trust = providerHomeTrust(t.home);
|
|
969
|
+
if (trust?.composition) {
|
|
970
|
+
const differing = [];
|
|
971
|
+
for (const capability of Object.keys(trust.composition.modules).sort()) {
|
|
972
|
+
const compared = treeDisagreement(kernelModuleDir(t.home, capability, trust), join(t.home, ".oats", "modules", capability));
|
|
973
|
+
if (compared.entries.length) differing.push({ capability, differs: true });
|
|
974
|
+
else if (!compared.complete) differing.push({ capability, differs: null });
|
|
975
|
+
}
|
|
976
|
+
kernelCopies = { store: trust.composition.store, differing };
|
|
977
|
+
}
|
|
978
|
+
}
|
|
881
979
|
const subjectBlockers = Object.entries(checks).flatMap(([name, c]) => c.items.filter((i) => i.required && !i.capability && i.status !== "pass" && i.status !== "not-applicable").map((i) => ({ check: name, subject: i.subject, status: i.status })));
|
|
882
980
|
for (const g of byCapability) g.ready = g.ownReady && subjectBlockers.length === 0;
|
|
883
|
-
return { readinessApi: READINESS_API, subject: t.subject, selector, at: new Date().toISOString(), checks,
|
|
981
|
+
return { readinessApi: READINESS_API, subject: t.subject, selector, at: new Date().toISOString(), checks, ...(sandbox ? { sandbox } : {}), ...(kernelCopies ? { kernelCopies } : {}),
|
|
884
982
|
summary: { ready: requiredStatuses.length > 0 && requiredStatuses.every((s) => s === "pass" || s === "not-applicable"), required: requiredStatuses.length,
|
|
885
983
|
pass: requiredStatuses.filter((s) => s === "pass").length, fail: requiredStatuses.filter((s) => s === "fail").length, unknown: requiredStatuses.filter((s) => s === "unknown").length, byCapability, subjectBlockers },
|
|
886
984
|
notes: ["ready means every REQUIRED check passes; it is never inferred from an empty set",
|
|
@@ -138,7 +138,9 @@ export function setInstanceRelatedWork(ctx, root, name, { home, on }) {
|
|
|
138
138
|
* parentage is the only relation the kernel knows; it is reported as such. */
|
|
139
139
|
export function descendantsOf(root, name) {
|
|
140
140
|
const rows = [];
|
|
141
|
-
|
|
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 || []) {
|
|
142
144
|
const home = join(a._dir, "instances", inst.instance);
|
|
143
145
|
const meta = otherRecord(home);
|
|
144
146
|
if (meta) rows.push({ instance: inst.instance, agent: a.name, home, parent: meta.parentInstance ?? null });
|
|
@@ -161,6 +163,9 @@ export function descendantsOf(root, name) {
|
|
|
161
163
|
return out; // deepest first
|
|
162
164
|
}
|
|
163
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");
|
|
164
169
|
/** `state` is the session backend's word: "shell"/"stopped"/"not-launched" are
|
|
165
170
|
* idle; "unknown" means a NON-shell process is running whose identity tmux
|
|
166
171
|
* cannot name (the ordinary case for a launched harness). "Could not be
|
|
@@ -168,7 +173,7 @@ export function descendantsOf(root, name) {
|
|
|
168
173
|
* the kernel code of what failed, never a system error's (E_SESSION_UNAVAILABLE
|
|
169
174
|
* for one that has none; workFacts: E_GIT_FAILED). */
|
|
170
175
|
function sessionFacts(home) {
|
|
171
|
-
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 }; }
|
|
172
177
|
catch (e) { return { state: "unestablished", present: null, backend: null, established: false, reason: kernelCode(e, "E_SESSION_UNAVAILABLE") }; }
|
|
173
178
|
}
|
|
174
179
|
/** The instances attached to `tree`, a tree of the home of the instance `name` under `root` (its
|
|
@@ -233,7 +238,14 @@ export function planStop(ctx, root, name, { home, recursive = true, [OWN_HOLDING
|
|
|
233
238
|
const targets = [...kids.map((kid) => targetFacts(kid, otherRecord(kid.home), own)), targetFacts({ ...me, instance: name, depth: 0 }, targetRecord(me.home), own)];
|
|
234
239
|
// Reported activity: a running session or dirty work is mid-task; when the
|
|
235
240
|
// session could not be established and work is not observed, say unknown.
|
|
236
|
-
|
|
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;
|
|
237
249
|
const safety = targets.map((t) => [t.home, t.session.state, t.session.present, t.launched, t.retiring]);
|
|
238
250
|
const ambiguousEdges = (kids.ambiguous || []).map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, reason: c.reason }));
|
|
239
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,7 @@ 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 { liveSession, validWaitingMessage } from "./instance-events.mjs";
|
|
11
|
+
import { liveSession, liveWaiting, validWaitingMessage } from "./instance-events.mjs";
|
|
12
12
|
import { readBoardRow } from "./instance-board.mjs";
|
|
13
13
|
import { processLiveness } from "./worktree-hooks.mjs";
|
|
14
14
|
import { shownHolder } from "./claim.mjs";
|
|
@@ -19,10 +19,13 @@ import { readInstanceBackground } from "./instance-background.mjs";
|
|
|
19
19
|
import { readInstancePin } from "./instance-pin.mjs";
|
|
20
20
|
import { relatedWorkHeld } from "./instance-related-work.mjs";
|
|
21
21
|
import { readSpawnedBy } from "./spawned-by.mjs";
|
|
22
|
-
import { sessionEndOf } from "./session-end.mjs";
|
|
22
|
+
import { HOST_STOP_REASON, lostReasonOf, sessionEndOf } from "./session-end.mjs";
|
|
23
23
|
import { identityHolderState, recordSeen } from "./session-seen.mjs";
|
|
24
24
|
import { listAgents, capabilityAgentDirs } from "./soul-listing.mjs";
|
|
25
|
-
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 { moduleCopyReport, providerHomeTrust } from "./home-integrity.mjs";
|
|
28
|
+
import { SESSION_END } from "./session-resume-contract.mjs";
|
|
26
29
|
|
|
27
30
|
/** OATS 0.25 and earlier homed local souls and capability-defined agents at
|
|
28
31
|
* <scope>/local-agents/ (and <root>/local-agents|tmp-agents). The kernel never reads,
|
|
@@ -278,10 +281,82 @@ function statusTmuxPanes(snapshot, socket, session, io) {
|
|
|
278
281
|
return { ...snapshot, panes, windowIds };
|
|
279
282
|
} catch (e) { return { error: tmuxFailure(e, "tmux list-panes failed") }; }
|
|
280
283
|
}
|
|
284
|
+
/** The row of a home on a session provider, before its provider has been asked: the kernel's own
|
|
285
|
+
* facts, under the receipt's authority (instanceSessionTarget). → `{ fields, ask? }`: `fields` the
|
|
286
|
+
* row's `backend`, `session`, `tmux` (null), `open`, `running`, `runtimeState` (`unknown`, `shell`,
|
|
287
|
+
* `stopped` or `unreachable`; always there) and, for a home OATS stopped, `sessionEnd`; `ask`
|
|
288
|
+
* (`{ binding, endpoint }`) for a session the provider must be asked about.
|
|
289
|
+
* `session` is `{ provider }` and, on this host only, the endpoint's thread id (rowSession): the
|
|
290
|
+
* endpoint itself is never on a row (`oats session inspect --home` answers it, locally).
|
|
291
|
+
* A home OATS stopped, and one never launched, answer without the provider. A stopped home's
|
|
292
|
+
* `sessionEnd` is its stop receipt's (lib/session-end.mjs): `lost` when `oats host run`'s shutdown
|
|
293
|
+
* stopped it, which a resume brings back, else `stopped`. A receipt or a module copy that cannot
|
|
294
|
+
* be used is unknown (`unreachable`, with the reason), never stopped. */
|
|
295
|
+
function providerRow(home, meta) {
|
|
296
|
+
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 } });
|
|
297
|
+
let s;
|
|
298
|
+
try { s = instanceSessionTarget(home); } catch (e) { return unreachable(`${typeof e?.code === "string" ? e.code : "E_SESSION_UNAVAILABLE"}: ${e?.message ?? e}`); }
|
|
299
|
+
const recorded = s.session ?? s.planned;
|
|
300
|
+
// A record that names a session provider beside a receipt that authorises a tmux session, or none.
|
|
301
|
+
if (!recorded) return unreachable("E_RUNTIME_AUTHORITY_MISMATCH: instance metadata records a session provider and its independent session receipt does not");
|
|
302
|
+
// `moduleCopy` (lib/home-integrity.mjs moduleCopyReport): which copy of its modules the kernel
|
|
303
|
+
// runs, and whether the home's own record of them is the receipt's. Records only: nothing is hashed.
|
|
304
|
+
const moduleCopy = moduleCopyReport(meta, providerHomeTrust(home));
|
|
305
|
+
const fields = { backend: recorded.backend, session: rowSession(recorded.provider, recorded.endpoint ?? null), tmux: null, open: null, ...(moduleCopy ? { moduleCopy } : {}) };
|
|
306
|
+
// A launch that was sent and never recorded: unknown, never stopped (lib/session-providers.mjs launchSentOf).
|
|
307
|
+
if (s.unsettled) return unreachable(unsettledLaunchSaid(basename(home), s.unsettled.backend, s.unsettled.launchSent), fields.session);
|
|
308
|
+
if (!s.session) return { fields: { ...fields, running: false, runtimeState: "stopped" } };
|
|
309
|
+
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 } };
|
|
310
|
+
const found = homeSessionProvider(home, s.meta, s.session.provider, s.session.backend);
|
|
311
|
+
if (found.problem) return unreachable(found.problem, fields.session);
|
|
312
|
+
return { fields: { ...fields, running: null, runtimeState: "unreachable" }, ask: { binding: found.binding, endpoint: s.session.endpoint } };
|
|
313
|
+
}
|
|
314
|
+
/** The time one listing gives all its session providers together: a provider that hangs costs a
|
|
315
|
+
* status, a sweep or a plan this much at most, however many homes it has. */
|
|
316
|
+
const PROVIDER_LISTING_BUDGET_MS = 30_000;
|
|
317
|
+
/** Ask the providers about `asks` ([{ row, home, binding, endpoint, mayEnd }]) and write each answer
|
|
318
|
+
* into its row: one `inspectMany` call per group of homes that share one module copy, provider and
|
|
319
|
+
* settings (inspectManyGroup), at most INSPECT_MANY_MAX homes a call, and one `inspect` per home
|
|
320
|
+
* where a provider declares none (or its batch was bad: inspectProviderSessions). A provider that
|
|
321
|
+
* fails, refuses or answers outside the contract's words leaves the row unknown: `running: null`,
|
|
322
|
+
* `runtimeState: "unreachable"`. A session that is gone on a home OATS did not stop is a lost
|
|
323
|
+
* one (`sessionEnd: "lost"`, where the row may say how its session ended: `mayEnd`), which the
|
|
324
|
+
* sweep resumes under the home's cap. All the asks of one listing share PROVIDER_LISTING_BUDGET_MS. */
|
|
325
|
+
function answerProviderRows(asks, io) {
|
|
326
|
+
const deadline = Date.now() + PROVIDER_LISTING_BUDGET_MS;
|
|
327
|
+
// Each call's timeout: the verb's own (and a test's seam), never past what the listing has left.
|
|
328
|
+
const timeoutFor = () => Math.min(sessionProviderTimeout("inspect"), deadline - Date.now());
|
|
329
|
+
const groups = new Map(), single = [];
|
|
330
|
+
for (const ask of asks) {
|
|
331
|
+
const key = inspectManyGroup(ask.binding);
|
|
332
|
+
if (key === null) single.push(ask);
|
|
333
|
+
else groups.set(key, [...(groups.get(key) ?? []), ask]);
|
|
334
|
+
}
|
|
335
|
+
const answer = (ask, inspected) => {
|
|
336
|
+
if (inspected.unavailable) { Object.assign(ask.row, { running: null, runtimeState: "unreachable", runtimeError: inspected.unavailable }); return; }
|
|
337
|
+
const { state, running, open } = inspected.observed;
|
|
338
|
+
Object.assign(ask.row, { running, runtimeState: state, open });
|
|
339
|
+
delete ask.row.runtimeError;
|
|
340
|
+
// A producer's claim, read while the session is there and not in error (an idle session can be
|
|
341
|
+
// the one waiting on a person); the receipt already agreed (providerRow).
|
|
342
|
+
if (providerMayWait(inspected.observed)) ask.row.waitingOnYou = liveWaiting(ask.home);
|
|
343
|
+
if (inspected.observed.present === false && ask.mayEnd) ask.row.sessionEnd = SESSION_END.LOST;
|
|
344
|
+
};
|
|
345
|
+
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" }); }
|
|
346
|
+
for (const members of groups.values()) {
|
|
347
|
+
for (let at = 0; at < members.length; at += INSPECT_MANY_MAX) {
|
|
348
|
+
const chunk = members.slice(at, at + INSPECT_MANY_MAX);
|
|
349
|
+
inspectProviderSessions(chunk, { io, timeoutFor }).forEach((inspected, i) => answer(chunk[i], inspected));
|
|
350
|
+
}
|
|
351
|
+
}
|
|
352
|
+
}
|
|
281
353
|
/** `records`, when given, a Map the listing fills with each home's record as read (home → the JSON
|
|
282
354
|
* object its instance.json holds, before upgradeHomeMeta), for the rest of the same read to reuse
|
|
283
|
-
* instead of reading the file again (legacyCapturedHomes).
|
|
284
|
-
|
|
355
|
+
* instead of reading the file again (legacyCapturedHomes).
|
|
356
|
+
* `askProviders: false` (the host's shutdown listing): no session provider is asked. A provider
|
|
357
|
+
* home whose provider would be asked reads `running: null`, `runtimeState: "unreachable"`, with a
|
|
358
|
+
* `runtimeError` that says so: the listing then depends on no provider's answer, or time. */
|
|
359
|
+
export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { records, askProviders = true } = {}) {
|
|
285
360
|
// Liveness reads each home's RECORDED endpoint (a pre-0.31 home records pi-agents): the recorded
|
|
286
361
|
// socket, never the ambient $TMUX server: one window read and one pane read per socket/session,
|
|
287
362
|
// plus one lazy process scan for shell descendants, independent of the number of homes.
|
|
@@ -294,6 +369,9 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
294
369
|
return hostScan.ok ? { ok: true, processes: processesWorkingIn(hostScan.processes, home) } : hostScan;
|
|
295
370
|
};
|
|
296
371
|
const inspectPanes = createSessionPaneInspector(io);
|
|
372
|
+
// The homes on a session provider whose provider must be asked: asked together once every row is
|
|
373
|
+
// read (answerProviderRows), so that one call can answer for a provider's whole group.
|
|
374
|
+
const providerAsks = [];
|
|
297
375
|
const tmuxByEndpoint = new Map();
|
|
298
376
|
const windowsOf = (session, socket) => {
|
|
299
377
|
const key = JSON.stringify([socket ?? null, session]);
|
|
@@ -318,9 +396,14 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
318
396
|
const { rollbackIncomplete, spawnInProgress, retirePending, retire } = readRetireFacts(home);
|
|
319
397
|
// A home opened in Herdr (removed in 0.31.0) is listed, never observed: its row says so.
|
|
320
398
|
// A home whose record cannot be read is listed, never observed: where its session is, is in the record.
|
|
399
|
+
const herdr = record.state !== "unreadable" && recordsHerdr(meta, readJsonOrUndefined(findRetirementBaseline(home)));
|
|
400
|
+
// A home on a session provider is never read through tmux: its row is the kernel's facts
|
|
401
|
+
// and, where the provider must be asked, its answer (below, once every row is read).
|
|
402
|
+
const provided = record.state === "record" && !herdr && recordsSessionProvider(meta) ? providerRow(home, meta) : null;
|
|
321
403
|
const liveness = record.state === "unreadable" ? { running: null, runtimeState: "unreachable", runtimeError: `E_UNIDENTIFIED_INSTANCE_HOME: ${unreadableRecordSaid(record)}` }
|
|
322
|
-
:
|
|
404
|
+
: herdr
|
|
323
405
|
? { running: null, runtimeState: "unsupported", runtimeError: `E_HERDR_REMOVED: ${herdrInstanceRemoved(e.name).message}` }
|
|
406
|
+
: provided ? (({ sessionEnd: _own, ...fields }) => fields)(provided.fields)
|
|
324
407
|
: tmuxLiveness(windowsOf(meta.tmux?.session || tmuxSession, meta.tmux?.socket), meta.tmux?.window || meta.instance || e.name, scanOf(home),
|
|
325
408
|
// A home that records no socket and no launch (--no-launch) reads the default server only
|
|
326
409
|
// by default: that server's missing socket says nothing about it, and stays "not running".
|
|
@@ -363,7 +446,10 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
363
446
|
// Feature session-resume: how the last session of a launched home that does not run ended
|
|
364
447
|
// (lib/session-end.mjs): lost, stopped or exited. Absent while it runs or reads unknown, for a
|
|
365
448
|
// home never launched, and for one being set up, retired or quarantined.
|
|
366
|
-
|
|
449
|
+
// A home on a session provider reads it from its receipt (providerRow): `lost` for one stopped
|
|
450
|
+
// with the host, which a resume brings back, `stopped` for one an operator stopped; a session
|
|
451
|
+
// OATS did not stop has none.
|
|
452
|
+
const sessionEnd = record.state === "record" && liveness.running === false && meta.launched === true && !rollbackIncomplete && !spawnInProgress && !retirePending ? (provided ? provided.fields.sessionEnd ?? null : sessionEndOf(home, meta)) : null;
|
|
367
453
|
// Feature instance-color: the home's own colour record (lib/instance-color.mjs), a palette name or
|
|
368
454
|
// null, after the record so that nothing in instance.json stands in for it.
|
|
369
455
|
// Feature instance-pin: `pinned: true` while the home holds a valid pin (lib/instance-pin.mjs), absent
|
|
@@ -376,7 +462,13 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
376
462
|
// Feature instance-board: the agent's board (lib/instance-board.mjs), null for a home with no board
|
|
377
463
|
// file: its facts, and the questions of its current session, by the same read of the log as the claim.
|
|
378
464
|
const board = readBoardRow(home, { session, ...recordMeta });
|
|
379
|
-
|
|
465
|
+
// `backend`: `tmux` for a home on the kernel's own backend, a session provider's name otherwise
|
|
466
|
+
// (liveness carries it, with `session`); absent for a home whose record cannot be read and
|
|
467
|
+
// for one opened in Herdr, whose record says what it says.
|
|
468
|
+
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 } : {}) };
|
|
469
|
+
if (provided?.ask && askProviders) providerAsks.push({ row, home, ...provided.ask, mayEnd: meta.launched === true && !rollbackIncomplete && !spawnInProgress && !retirePending });
|
|
470
|
+
else if (provided?.ask) row.runtimeError = "its session provider was not asked (a listing that asks no provider)";
|
|
471
|
+
return row;
|
|
380
472
|
|
|
381
473
|
});
|
|
382
474
|
};
|
|
@@ -401,6 +493,7 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
|
|
|
401
493
|
out.push({ name, kind: "capability", capability: cap, description: cap ? `capability agent (${cap})` : "capability agent", dir, instances, ...(retireFailures.length ? { retireFailures } : {}) });
|
|
402
494
|
seen.add(name);
|
|
403
495
|
}
|
|
496
|
+
if (providerAsks.length) answerProviderRows(providerAsks, io);
|
|
404
497
|
// Feature session-resume: what this local listing saw of each home's session, for the sweep
|
|
405
498
|
// (lib/session-seen.mjs). It never changes the listing, and never throws or prints.
|
|
406
499
|
recordSeen(root, out.flatMap((a) => a.instances || []));
|
|
@@ -17,14 +17,14 @@
|
|
|
17
17
|
* Nothing here reads `oats-config.yaml`, an installed-capability directory or a
|
|
18
18
|
* per-soul `source:` — those do not exist in this model. */
|
|
19
19
|
import { existsSync, readFileSync, readdirSync, lstatSync, readlinkSync, realpathSync } from "node:fs";
|
|
20
|
-
import { join, resolve as resolvePath, dirname, relative, isAbsolute, sep } from "node:path";
|
|
20
|
+
import { basename, join, resolve as resolvePath, dirname, relative, isAbsolute, sep } from "node:path";
|
|
21
21
|
import { loadLocal, observeWorkspace } from "./workspace.mjs";
|
|
22
22
|
import { resolveSoul, kernelCompatibility, packageRef } from "./resolve.mjs";
|
|
23
23
|
import { BY_TEAM_REMOVED, isRemovedTeamKeys, isTeamRefusal, memberNameOf, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "./teams.mjs";
|
|
24
24
|
import { LOCAL_FILE, launchLayers, nearestSoulKeys } from "./launch-preference.mjs";
|
|
25
25
|
import { APPROVED_HOOKS, declaredSettings, locatedContractWarnings } from "./capability-contract.mjs";
|
|
26
26
|
import { materialize, moduleSkills, MODULES_DIR, plannedModuleSkills, SKILLS_DIR } from "./materialize.mjs";
|
|
27
|
-
import { contentDigest, fetchRemoteTree } from "./remote.mjs";
|
|
27
|
+
import { contentDigest, createReadSession, fetchRemoteTree } from "./remote.mjs";
|
|
28
28
|
import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync, symlinkSync } from "node:fs";
|
|
29
29
|
import { tmpdir } from "node:os";
|
|
30
30
|
import { randomBytes } from "node:crypto";
|
|
@@ -77,6 +77,27 @@ export function parseProviderFlags(pairs) {
|
|
|
77
77
|
return JSON.parse(JSON.stringify(out));
|
|
78
78
|
}
|
|
79
79
|
|
|
80
|
+
/** Why a discovery made without reaching any remote cannot say which soul a home is of: a member
|
|
81
|
+
* of the workspace that this host could not read (its cache does not hold it) → the cause, naming
|
|
82
|
+
* each such repository and the way out, or null when every member was read. A member that was
|
|
83
|
+
* read and is no member (no backlink, not listed) is not one of these. */
|
|
84
|
+
export function unreadMembersCause(discovery) {
|
|
85
|
+
if (discovery?.standalone === true) return null;
|
|
86
|
+
const unread = (discovery?.members || []).filter((m) => m.confirmed === false && m.reason === "cannot-read");
|
|
87
|
+
if (!unread.length) return null;
|
|
88
|
+
return `E_REMOTE_UNREADABLE: ${unread.map((m) => m.detail).join("; ")}. A member that was not read can hold this home's soul, or another of its name, so the deployment's configuration for the home cannot be told. Any oats command that reads the workspace (oats status) brings it to this host's cache; if this host cannot read that repository at all, name the member the home's soul is in as the deployment's own source (standalone: <member repository> in oats-local.yaml), which reads no workspace host`;
|
|
89
|
+
}
|
|
90
|
+
/** The soul a home under the agent directory `agentDir` is of, among the workspace's souls
|
|
91
|
+
* (`entries`) → `{ entry }`, or `{ unavailable: "<why>" }`. Nothing outside the home says which
|
|
92
|
+
* soul a home is but the directory it is in, so two souls that share that directory (the same
|
|
93
|
+
* bare name, in two members, or a member's and an external one) leave it untold: the cause names
|
|
94
|
+
* them and what the operator can do. */
|
|
95
|
+
export function homeSoulEntry(entries, agentDir) {
|
|
96
|
+
const here = entries.filter((entry) => agentDirOf(entry) === agentDir);
|
|
97
|
+
if (here.length === 1) return { entry: here[0] };
|
|
98
|
+
if (!here.length) return { unavailable: `E_SOUL_UNKNOWN: the workspace offers no soul whose agent directory is ${agentDir}` };
|
|
99
|
+
return { unavailable: `${here.length} souls of this workspace share the agent directory ${agentDir} (${here.map(qualifiedSoulName).join(", ")}), so which one this home is of cannot be told: rename one of them, or take one out of the workspace` };
|
|
100
|
+
}
|
|
80
101
|
/** The qualified name of a discovered soul: `<package>/<soul>` for a package soul,
|
|
81
102
|
* `<member name>/<soul>` for a member's, `<source repo name>/<soul>` for an external one. */
|
|
82
103
|
export function qualifiedSoulName(entry) {
|
|
@@ -286,6 +307,68 @@ export async function liveTeams(home, meta, { remoteOptions, remote } = {}) {
|
|
|
286
307
|
}
|
|
287
308
|
}
|
|
288
309
|
|
|
310
|
+
/**
|
|
311
|
+
* What a start or a restart of a session-provider home computes its sandbox allowances from
|
|
312
|
+
* (lib/sandbox-allowances.mjs): the DEPLOYMENT'S configuration, resolved for the home's soul as a
|
|
313
|
+
* spawn preview resolves it (workspace, lock, soul payload), WITHOUT REACHING ANY REMOTE: every
|
|
314
|
+
* repository is read as this host last read it (lib/remote.mjs, an offline read session: the head
|
|
315
|
+
* last observed here, from the cache), and the deployment's own oats-local.yaml and lock as they
|
|
316
|
+
* are now. So a launch never waits on the network or fails with it, and what `oats aweb setup`
|
|
317
|
+
* writes to oats-local.yaml reaches an existing home at its next launch. A repository this host's
|
|
318
|
+
* cache does not hold is a cause of `unavailable`, by name.
|
|
319
|
+
*
|
|
320
|
+
* NOTHING INSIDE THE HOME decides which deployment or which soul that is: a sandboxed agent can
|
|
321
|
+
* write its home, instance.json included. Both come from where the home IS: the deployment is the
|
|
322
|
+
* fourth ancestor of the home's real path (`<deployment>/agents/<agent>/instances/<instance>`),
|
|
323
|
+
* and it must hold its own oats-local.yaml; the soul is the one soul the workspace offers whose
|
|
324
|
+
* agent directory is `<agent>`. A home whose real path is elsewhere (an agents root reached
|
|
325
|
+
* through a link) has no deployment to read by this rule, and none is guessed.
|
|
326
|
+
*
|
|
327
|
+
* → `{ deployment, modules: [{ name, manifest }], slots, payloads, teams: [team id], defaultTeam }`, or
|
|
328
|
+
* `{ unavailable: "<why>" }` when that cannot be established or resolved (no deployment there, no
|
|
329
|
+
* such soul any more or several, a member remote that cannot be read, an invalid workspace): the
|
|
330
|
+
* cause, in one line. It never throws for those: what a launch does without allowances is the
|
|
331
|
+
* caller's rule.
|
|
332
|
+
*/
|
|
333
|
+
export async function homeSandboxSource(home, { remoteOptions, remote } = {}) {
|
|
334
|
+
let real;
|
|
335
|
+
try { real = realpathSync(home); } catch (e) { return { unavailable: `the home cannot be resolved (${e.code ?? e.message})` }; }
|
|
336
|
+
const deployment = dirname(dirname(dirname(dirname(real)))), agentDir = basename(dirname(dirname(real)));
|
|
337
|
+
if (basename(dirname(real)) !== "instances") return { unavailable: `${real} is not an instance home of a deployment (<deployment>/agents/<agent>/instances/<instance>)` };
|
|
338
|
+
// Never the caller's session: this read reaches no remote, whatever the command around it does.
|
|
339
|
+
const offline = createReadSession({ offline: true });
|
|
340
|
+
try {
|
|
341
|
+
const found = loadLocal(deployment);
|
|
342
|
+
if (!found.path || resolvePath(dirname(found.path)) !== deployment) return { unavailable: `${deployment}, where this home is, holds no deployment configuration (oats-local.yaml): the home's agents directory is reached through a symbolic link, or the home is not a deployment's` };
|
|
343
|
+
remoteOptions = { ...remoteOptions, session: offline };
|
|
344
|
+
const lock = readLockIfPresent(deployment);
|
|
345
|
+
const discovery = await discoverOrStandalone(found.local, { lock, deployment, remoteOptions, remote });
|
|
346
|
+
// A member this host did not read can hold the home's soul, or another of its name: with one
|
|
347
|
+
// unread, which soul the home is of is not told, whatever the members that were read offer.
|
|
348
|
+
const unread = unreadMembersCause(discovery);
|
|
349
|
+
if (unread) return { unavailable: unread };
|
|
350
|
+
const soul = homeSoulEntry(soulCandidates(discovery).map((c) => c.entry), agentDir);
|
|
351
|
+
if (soul.unavailable) return { unavailable: soul.unavailable };
|
|
352
|
+
|
|
353
|
+
// resolveSoul, not prepareInstance: a soul disabled for SPAWNING on this machine (souls.disabled)
|
|
354
|
+
// still has the homes it spawned, which start as any home does, with their allowances.
|
|
355
|
+
const resolution = await resolveSoul(discovery, soul.entry, { local: found.local, lock, spawn: {}, remoteOptions, remote });
|
|
356
|
+
return {
|
|
357
|
+
deployment,
|
|
358
|
+
modules: resolution.modules.map((m) => ({ name: m.name, manifest: m.manifest })), slots: resolution.slots ?? {}, payloads: resolution.payloads ?? {},
|
|
359
|
+
teams: (resolution.teams ?? []).map((row) => row.team).filter((team) => typeof team === "string"),
|
|
360
|
+
defaultTeam: typeof resolution.defaultTeam?.team === "string" ? resolution.defaultTeam.team : null,
|
|
361
|
+
};
|
|
362
|
+
} catch (e) {
|
|
363
|
+
if (typeof e?.code !== "string" || !e.code.startsWith("E_")) throw e;
|
|
364
|
+
// A repository this host can NEVER read (a member whose workspace host it has no access to: a
|
|
365
|
+
// spawn then works from the member alone) is never brought to the cache by any command: the
|
|
366
|
+
// way out is to say so in the deployment, which needs no read of that host.
|
|
367
|
+
const never = e.details?.reason === "not-cached" ? " If this host cannot read that repository at all, name the member as the deployment's own source (standalone: <member repository> in oats-local.yaml), which reads no workspace host" : "";
|
|
368
|
+
return { unavailable: `${e.code}: ${e.message}${never}` };
|
|
369
|
+
} finally { offline.close(); }
|
|
370
|
+
}
|
|
371
|
+
|
|
289
372
|
/**
|
|
290
373
|
* For `session start|restart --reselect-launch`: what the home's launch layers need of the workspace
|
|
291
374
|
* (lib/core.mjs homeLaunchLayers `offered`) to say which keys of souls.launch name no soul. The workspace
|