@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/servers.mjs
CHANGED
|
@@ -35,7 +35,9 @@ import { shellWord } from "./shell-word.mjs";
|
|
|
35
35
|
import { DETACH_KEY_FEATURE, requireDetachKey } from "./session-viewer.mjs";
|
|
36
36
|
import { LOGIN_CAPTURE_MAX_BYTES, LOGIN_SHELLS, loginPathEmitter, quoteFor, readLoginFrame } from "./login-environment.mjs";
|
|
37
37
|
import { compareSemver } from "./semver.mjs";
|
|
38
|
-
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";
|
|
40
|
+
import { readModuleCopy } from "./home-integrity.mjs";
|
|
39
41
|
import { sameRepo } from "./repo-moves.mjs";
|
|
40
42
|
import { OATS_PACKAGE_NAME } from "./version.mjs";
|
|
41
43
|
import { readRemoteBoard } from "./instance-board.mjs";
|
|
@@ -330,9 +332,24 @@ export function operatorSshArgv(alias, words) {
|
|
|
330
332
|
|
|
331
333
|
// ------------------------------------------------------------------ running
|
|
332
334
|
|
|
335
|
+
/** A host's envelope without a session provider's locator (feature session-providers): a provider
|
|
336
|
+
* home's endpoint, and the thread id a status row carries on its own host, are for the host where
|
|
337
|
+
* the home lives, and are never relayed. An answer's own `session` (a spawn's, a start's, an
|
|
338
|
+
* inspect's) and every roster row's are cut to `{ provider }`, whatever the host sent. */
|
|
339
|
+
function withoutProviderLocators(envelope) {
|
|
340
|
+
const result = envelope?.result;
|
|
341
|
+
if (envelope?.ok !== true || !result || typeof result !== "object") return envelope;
|
|
342
|
+
const rows = (agents) => agents.map((a) => (a && Array.isArray(a.instances) ? { ...a, instances: a.instances.map(withoutRelayedEndpoint) } : a));
|
|
343
|
+
const roster = (doc) => (doc && Array.isArray(doc.agents) ? { ...doc, agents: rows(doc.agents) } : doc);
|
|
344
|
+
const cut = Array.isArray(result.roots) ? { ...result, roots: result.roots.map(roster) } : roster(withoutRelayedEndpoint(result));
|
|
345
|
+
return { ...envelope, result: cut };
|
|
346
|
+
}
|
|
333
347
|
/** Parse the remote kernel's JSON envelope; anything else on stdout is a
|
|
334
348
|
* routing failure with the raw text attached, never a guess. */
|
|
335
349
|
export function parseRemoteEnvelope(stdout) {
|
|
350
|
+
return withoutProviderLocators(parseRemoteEnvelopeAsSent(stdout));
|
|
351
|
+
}
|
|
352
|
+
function parseRemoteEnvelopeAsSent(stdout) {
|
|
336
353
|
const text = String(stdout || "").trim();
|
|
337
354
|
let doc;
|
|
338
355
|
try {
|
|
@@ -499,6 +516,7 @@ export function dropRemoteProbes(serverId) {
|
|
|
499
516
|
|
|
500
517
|
function probeRemote(target, io) {
|
|
501
518
|
const { envelope } = runRemote(target, ["version", "--json"], { ...io, timeoutMs: 60000 });
|
|
519
|
+
if (!envelope.ok) throw relayedFailure(envelope, "version --json");
|
|
502
520
|
const probe = envelope.result || {};
|
|
503
521
|
if (probe.desktopApi !== 1 || typeof probe.version !== "string") {
|
|
504
522
|
throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats at ${target.sshHost} answered an unknown version payload: ${JSON.stringify(probe).slice(0, 200)}`);
|
|
@@ -561,7 +579,10 @@ export function checkRemoteSupport(remote, target, oatsArgs, roster) {
|
|
|
561
579
|
// A wake schedule at spawn is saved by the host: it must advertise schedules.
|
|
562
580
|
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)");
|
|
563
581
|
const backend = flagOf("--backend");
|
|
564
|
-
|
|
582
|
+
// A backend that is none of the host's built-in ones is a session provider (a capability's, resolved
|
|
583
|
+
// against the instance's modules there): relayed only to a host that lists the feature. A host
|
|
584
|
+
// without it knows tmux alone, and is never asked for another.
|
|
585
|
+
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})`);
|
|
565
586
|
if (oatsArgs.includes("--yolo") && !remote.launchOptions.includes("yolo")) refuse("the yolo launch option");
|
|
566
587
|
return { harness, backend, yolo: oatsArgs.includes("--yolo") };
|
|
567
588
|
}
|
|
@@ -1129,6 +1150,14 @@ const rowBoard = (i) => (Object.hasOwn(i, "board") ? { board: readRemoteBoard(i.
|
|
|
1129
1150
|
/** `retire` (feature status-retire-state) as `waitingOnYou` is, relayed ONLY when the host's row has the
|
|
1130
1151
|
* key: a host whose kernel predates the feature omits it, and its rows say nothing. Absent is the
|
|
1131
1152
|
* only reading of "no retire", so a value the kernel's own read refuses is dropped, never null. */
|
|
1153
|
+
/** `moduleCopy` (a provider home's: which copy of its modules its kernel runs, and whether the home's
|
|
1154
|
+
* record of them is the receipt's; lib/home-integrity.mjs) as `retire` is: relayed ONLY when the
|
|
1155
|
+
* host's row has the key and this kernel's own read takes its value. A tmux home's row, and a
|
|
1156
|
+
* host whose kernel predates it, say nothing. */
|
|
1157
|
+
const rowModuleCopy = (i) => {
|
|
1158
|
+
const moduleCopy = Object.hasOwn(i, "moduleCopy") ? readModuleCopy(i.moduleCopy) : undefined;
|
|
1159
|
+
return moduleCopy ? { moduleCopy } : {};
|
|
1160
|
+
};
|
|
1132
1161
|
const rowRetire = (i) => {
|
|
1133
1162
|
const retire = Object.hasOwn(i, "retire") ? readRetireState(i.retire) : undefined;
|
|
1134
1163
|
return retire ? { retire } : {};
|
|
@@ -1246,10 +1275,12 @@ export async function rosterGroups({ server, workspaceKeys, io = {} } = {}) {
|
|
|
1246
1275
|
const snap = routeOf(i);
|
|
1247
1276
|
g.instances.push({
|
|
1248
1277
|
server: g.server, instance: i.instance, agent: a.name, home: i.home || snap?.home, agentsRoot: result.root,
|
|
1249
|
-
|
|
1278
|
+
// A session provider's row (feature session-providers): its backend's name, `session`, `open`
|
|
1279
|
+
// and `runtimeState`, relayed in the kernel's own shapes only (relayedProviderRow).
|
|
1280
|
+
harness: i.harness || i.runtime || null, backend: i.tmux ? "tmux" : null, ...(relayedProviderRow(i) ?? {}),
|
|
1250
1281
|
...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}), ...(i.tmux ? { tmux: i.tmux } : {}),
|
|
1251
1282
|
running: typeof i.running === "boolean" ? i.running : null, ...(i.runtimeError ? { runtimeError: i.runtimeError } : {}),
|
|
1252
|
-
...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowBackground(i), ...rowPinned(i), ...rowBoard(i), ...rowRelatedWork(i, g.probe.features), ...rowSessionEnd(i),
|
|
1283
|
+
...rowFacts(i), ...rowWaiting(i), ...rowRetire(i), ...rowModuleCopy(i), ...rowBackground(i), ...rowPinned(i), ...rowBoard(i), ...rowRelatedWork(i, g.probe.features), ...rowSessionEnd(i),
|
|
1253
1284
|
// Every row the host reports is addressed by its home, saved
|
|
1254
1285
|
// route or not; savedRoute says only that it was spawned from here.
|
|
1255
1286
|
retirePending: !!i.retirePending, rollbackIncomplete: !!i.rollbackIncomplete, savedRoute: !!snap, addressable: true, missingRemotely: false,
|
|
@@ -1663,7 +1694,9 @@ function probeHostOats(target, io) {
|
|
|
1663
1694
|
const r = runHostCommand(target, [target.oatsPath, "version", "--json"], { ...io, timeoutMs: 60000 });
|
|
1664
1695
|
if (r.status === 255) throw sshFailed(target, r);
|
|
1665
1696
|
if (r.status === 126 || r.status === 127) return { missing: true };
|
|
1666
|
-
const
|
|
1697
|
+
const envelope = parseRemoteEnvelope(r.stdout);
|
|
1698
|
+
if (!envelope.ok) throw relayedFailure(envelope, "version --json");
|
|
1699
|
+
const probe = envelope.result || {};
|
|
1667
1700
|
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)}`);
|
|
1668
1701
|
return { version: probe.version, features: Array.isArray(probe.features) ? probe.features.map(String) : [] };
|
|
1669
1702
|
}
|
package/lib/session-inspect.mjs
CHANGED
|
@@ -1,14 +1,17 @@
|
|
|
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
|
-
import { existsSync, readFileSync
|
|
7
|
-
import { isAbsolute, join, resolve,
|
|
8
|
-
import {
|
|
7
|
+
import { existsSync, readFileSync } from "node:fs";
|
|
8
|
+
import { isAbsolute, join, resolve, basename } from "node:path";
|
|
9
|
+
import { RETIRE_BASELINE_VERSION, findRetirementBaseline, instancesRetirementRoot, isPlainObject, legacyRetirementBaselinePath, readJsonOrUndefined, receiptHomeIdentity, receiptRecordsHome, retirementBaselinePath } from "./session-receipt.mjs";
|
|
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 { receiptTrust, trustedRecord } from "./home-integrity.mjs";
|
|
14
|
+
import { homeSessionProvider, isSessionProviderName, inspectProviderSession, launchSentOf, providerEndpointDifferences, providerRuntimeOf, unsettledLaunchSaid } from "./session-providers.mjs";
|
|
12
15
|
|
|
13
16
|
/** A cleanup descriptor is usable only if it can DRIVE the retry, so it is checked
|
|
14
17
|
* as the strict contract its one producer writes — the rollback above — and to the
|
|
@@ -27,76 +30,6 @@ import { oatsError, herdrInstanceRemoved } from "./errors.mjs";
|
|
|
27
30
|
*
|
|
28
31
|
* Anything else reads as ABSENT — no more retryable than a missing marker — so the
|
|
29
32
|
* home fails closed by default and `--force` can clear it. */
|
|
30
|
-
function isPlainObject(v) { return !!v && typeof v === "object" && !Array.isArray(v); }
|
|
31
|
-
|
|
32
|
-
// The stored digests are versioned apart (`digestVersion`, BASELINE_DIGEST_VERSION): this version
|
|
33
|
-
// also gates runtime, directory-home and provider-exclusion authority, so a bump would refuse them all.
|
|
34
|
-
const RETIRE_BASELINE_VERSION = 2;
|
|
35
|
-
|
|
36
|
-
function retirementStateRoot(home) {
|
|
37
|
-
// Independent of the bytes it authenticates, but colocated with the agent's
|
|
38
|
-
// already instance-owned storage rather than the source repository or user
|
|
39
|
-
// config home. Retiring <instances>/<name> never removes this sibling.
|
|
40
|
-
return instancesRetirementRoot(dirname(home));
|
|
41
|
-
}
|
|
42
|
-
/** The retirement state of the homes in the instances directory `instances`. */
|
|
43
|
-
function instancesRetirementRoot(instances) {
|
|
44
|
-
return join(instances, ".oats-retirement");
|
|
45
|
-
}
|
|
46
|
-
|
|
47
|
-
/** A home's identity as a receipt records it: its on-disk spelling, own name included. A home that
|
|
48
|
-
* is a symlink is not followed: its parent's on-disk spelling and its name as given (a home
|
|
49
|
-
* exchanged for a symlink is not the home it points at). */
|
|
50
|
-
function receiptHomeIdentity(home) {
|
|
51
|
-
let st;
|
|
52
|
-
try { st = lstatSync(home); } catch { /* not there: spelled as the nearest existing ancestor */ }
|
|
53
|
-
return st && !st.isSymbolicLink() ? canonicalHomePath(home) : join(canonicalHomePath(dirname(home)), basename(home));
|
|
54
|
-
}
|
|
55
|
-
|
|
56
|
-
/** Whether a receipt's recorded home is this home, whatever spelling either was written in.
|
|
57
|
-
* `current` is the home as the caller resolves it for the comparison. */
|
|
58
|
-
function receiptRecordsHome(baseline, current) {
|
|
59
|
-
return typeof baseline?.home === "string" && receiptHomeIdentity(baseline.home) === current;
|
|
60
|
-
}
|
|
61
|
-
|
|
62
|
-
function retirementBaselineFile(identity) {
|
|
63
|
-
return join(retirementStateRoot(identity), "baselines", `${createHash("sha256").update(identity).digest("hex")}.json`);
|
|
64
|
-
}
|
|
65
|
-
|
|
66
|
-
/** Where a spawn writes a home's receipt: keyed by its canonical identity. */
|
|
67
|
-
export function retirementBaselinePath(home) {
|
|
68
|
-
return retirementBaselineFile(receiptHomeIdentity(home));
|
|
69
|
-
}
|
|
70
|
-
|
|
71
|
-
/** Where a kernel before 0.49.0 wrote it: keyed by the parent's realpath in the spawn's own
|
|
72
|
-
* spelling, which on a case-insensitive filesystem need not be the on-disk one. */
|
|
73
|
-
function legacyRetirementBaselinePath(home) {
|
|
74
|
-
return retirementBaselineFile(join(realPathOrNearest(dirname(home)), basename(home)));
|
|
75
|
-
}
|
|
76
|
-
|
|
77
|
-
/** The receipt every reader uses: the canonical one if it exists, else one an earlier kernel left
|
|
78
|
-
* under this caller's spelling, else the canonical path (absent). Read-only: a receipt found at the
|
|
79
|
-
* legacy key is used where it is, never moved, copied or rewritten elsewhere.
|
|
80
|
-
*
|
|
81
|
-
* Limits. A legacy receipt written under spelling S is found only from S, or from the canonical
|
|
82
|
-
* spelling when that is S: a third spelling of such a home misses it (address the home as
|
|
83
|
-
* `oats status` prints it, the spawn's spelling). Receipts outlive retire, so a reused name can
|
|
84
|
-
* leave an earlier incarnation's receipt behind; the canonical one wins, which is right for every
|
|
85
|
-
* home spawned from 0.49.0 on. It is wrong in one case: two incarnations of the same name, both
|
|
86
|
-
* spawned by a kernel before 0.49.0 under different spellings, the earlier one under the canonical
|
|
87
|
-
* spelling. The later home then reads the earlier one's receipt. Its stale endpoint disagrees with
|
|
88
|
-
* instance.json (E_RUNTIME_AUTHORITY_MISMATCH) unless the later incarnation sits at the same
|
|
89
|
-
* endpoint, where session control already targets the right session. Retire finds the home
|
|
90
|
-
* fingerprint changed and preserves the home, less the stale receipt's disposable roots; a
|
|
91
|
-
* directory-work disagreement is E_WORK_INSPECTION_FAILED; and a start's record rewrites the stale
|
|
92
|
-
* file, as a kernel before 0.49.0 already does when a caller's spelling matches an earlier
|
|
93
|
-
* incarnation's. */
|
|
94
|
-
export function findRetirementBaseline(home) {
|
|
95
|
-
const canonical = retirementBaselinePath(home);
|
|
96
|
-
if (existsSync(canonical)) return canonical;
|
|
97
|
-
const legacy = legacyRetirementBaselinePath(home);
|
|
98
|
-
return legacy !== canonical && existsSync(legacy) ? legacy : canonical;
|
|
99
|
-
}
|
|
100
33
|
|
|
101
34
|
/** Herdr (removed in 0.31.0) is recognised in a home only to refuse: its instance.json records a
|
|
102
35
|
* Herdr session target or `backend: "herdr"`, or its independent receipt records a session target
|
|
@@ -105,22 +38,59 @@ function recordsHerdr(meta, baseline) {
|
|
|
105
38
|
return (isPlainObject(meta) && (meta.sessionTarget !== undefined || meta.backend === "herdr"))
|
|
106
39
|
|| (isPlainObject(baseline?.runtime) && baseline.runtime.sessionTarget !== undefined);
|
|
107
40
|
}
|
|
108
|
-
function readJsonOrUndefined(path) { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return undefined; } }
|
|
109
41
|
/** Refuse any session operation on a home opened in Herdr, from its files as they are (either may be
|
|
110
42
|
* missing or unreadable): before any receipt validation, so the refusal is never an endpoint error. */
|
|
111
43
|
function refuseHerdrHome(home) {
|
|
112
44
|
if (recordsHerdr(readJsonOrUndefined(join(home, "instance.json")), readJsonOrUndefined(findRetirementBaseline(home)))) throw herdrInstanceRemoved(basename(home));
|
|
113
45
|
}
|
|
114
46
|
|
|
47
|
+
/** What a receipt authorises: `{ launched: false }` (with `planned: { backend, provider }` for a home
|
|
48
|
+
* that will launch on a session provider), `{ launched: true, tmux }` for a tmux session, or
|
|
49
|
+
* `{ launched: true, session }` for a session provider's (`session`: providerRuntimeOf's
|
|
50
|
+
* `{ backend, provider, endpoint, stoppedAt }`); undefined when it is none of these. */
|
|
115
51
|
function runtimeAuthorityOf(baseline) {
|
|
116
52
|
const runtime = baseline?.runtime;
|
|
117
53
|
if (!isPlainObject(runtime) || typeof runtime.launched !== "boolean") return undefined;
|
|
118
|
-
if (!runtime.launched)
|
|
54
|
+
if (!runtime.launched) {
|
|
55
|
+
if (runtime.backend === undefined && runtime.provider === undefined) return { launched: false };
|
|
56
|
+
if (!isSessionProviderName(runtime.backend) || typeof runtime.provider !== "string" || !runtime.provider || runtime.launchSent !== undefined) return undefined;
|
|
57
|
+
return { launched: false, planned: { backend: runtime.backend, provider: runtime.provider, launchSent: null } };
|
|
58
|
+
}
|
|
119
59
|
if (runtime.sessionTarget !== undefined) return undefined;
|
|
60
|
+
// A launch that was sent for a home never launched, and has no recorded outcome (lib/session-providers.mjs
|
|
61
|
+
// launchSentOf): no endpoint yet. The home is still a planned one, whose record says not launched.
|
|
62
|
+
if (runtime.tmux === undefined && runtime.endpoint === undefined) {
|
|
63
|
+
const launchSent = launchSentOf(runtime);
|
|
64
|
+
if (!launchSent || !isSessionProviderName(runtime.backend) || typeof runtime.provider !== "string" || !runtime.provider) return undefined;
|
|
65
|
+
return { launched: false, planned: { backend: runtime.backend, provider: runtime.provider, launchSent } };
|
|
66
|
+
}
|
|
67
|
+
if (runtime.tmux === undefined) {
|
|
68
|
+
const session = providerRuntimeOf(runtime);
|
|
69
|
+
return session ? { launched: true, session: { backend: session.backend, provider: session.provider, endpoint: session.endpoint, stoppedAt: session.stoppedAt, launchSent: session.launchSent } } : undefined;
|
|
70
|
+
}
|
|
120
71
|
const tmux = runtime.tmux;
|
|
121
72
|
if (!isPlainObject(tmux) || ![tmux.session, tmux.window, tmux.socket].every((v) => typeof v === "string" && v.length > 0)) return undefined;
|
|
122
73
|
return { launched: true, tmux: { session: tmux.session, window: tmux.window, socket: resolve(tmux.socket) } };
|
|
123
74
|
}
|
|
75
|
+
/** The fields of instance.json's session that differ from the receipt's, for a home on a session
|
|
76
|
+
* provider, launched (`authority.session`) or planned (`authority.planned`: no endpoint yet). */
|
|
77
|
+
function providerDifferences(meta, authority) {
|
|
78
|
+
// While the receipt says a launch is unsettled, the record's endpoint is not compared: the
|
|
79
|
+
// launch that would have written it may have ended at any point (docs/design/2026-11-20-provider-home-lifecycle.md).
|
|
80
|
+
if (authority.session && !authority.session.launchSent) return providerEndpointDifferences(meta, authority.session);
|
|
81
|
+
const named = authority.session ?? authority.planned;
|
|
82
|
+
return [
|
|
83
|
+
...(meta?.backend === named.backend ? [] : ["backend"]),
|
|
84
|
+
...(meta?.session?.provider === named.provider ? [] : ["session.provider"]),
|
|
85
|
+
];
|
|
86
|
+
}
|
|
87
|
+
/** The fields of instance.json's endpoint, of whichever backend the receipt records, that differ
|
|
88
|
+
* from the receipt's: tmux's labels, or a session provider's. A receipt that records no endpoint
|
|
89
|
+
* (never launched, planned on tmux) has none to differ from. */
|
|
90
|
+
function endpointDifferences(meta, authority) {
|
|
91
|
+
if (authority.session || authority.planned) return providerDifferences(meta, authority);
|
|
92
|
+
return authority.launched ? tmuxEndpointDifferences(meta, authority) : [];
|
|
93
|
+
}
|
|
124
94
|
|
|
125
95
|
/** The fields of instance.json's tmux endpoint that differ from the one the independent receipt
|
|
126
96
|
* authorises, as fixed labels in a fixed order: `tmux.session`, `tmux.window`, `tmux.socket`. */
|
|
@@ -133,6 +103,8 @@ function tmuxEndpointDifferences(meta, authority) {
|
|
|
133
103
|
}
|
|
134
104
|
/** instance.json's tmux endpoint is the one the independent receipt authorises. */
|
|
135
105
|
function tmuxEndpointAgrees(meta, authority) { return tmuxEndpointDifferences(meta, authority).length === 0; }
|
|
106
|
+
/** instance.json's endpoint, of whichever backend the receipt records, is the one it authorises. */
|
|
107
|
+
function endpointAgrees(meta, authority) { return endpointDifferences(meta, authority).length === 0; }
|
|
136
108
|
|
|
137
109
|
/** Whether a blocked or incomplete launch prompt explains metadata's `launched: false` beside a
|
|
138
110
|
* launched receipt. */
|
|
@@ -142,18 +114,23 @@ function promptRetained(meta, authority) {
|
|
|
142
114
|
/** A blocked prompt is a retained runtime, not evidence that no process exists.
|
|
143
115
|
* The independent launched receipt and exact endpoint agreement remain mandatory. */
|
|
144
116
|
function launchStateAgrees(meta, authority) {
|
|
145
|
-
|
|
117
|
+
// A launch that was sent for a home never launched (lib/session-providers.mjs launchSentOf): the
|
|
118
|
+
// record says `launched: true` meanwhile, so that a kernel from before session providers refuses
|
|
119
|
+
// the home; the two files are written one after the other, so either value agrees.
|
|
120
|
+
if ((authority.session ?? authority.planned)?.launchSent) return true;
|
|
121
|
+
return meta.launched === authority.launched || (promptRetained(meta, authority) && !authority.session && tmuxEndpointAgrees(meta, authority));
|
|
146
122
|
}
|
|
147
123
|
|
|
148
124
|
/** The refusal for instance.json that disagrees with the independent receipt. `details.fields` names
|
|
149
125
|
* 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
|
|
126
|
+
* launch prompt explains metadata's `launched: false`), then each differing endpoint field: for a
|
|
127
|
+
* launched tmux receipt `tmux.session`, `tmux.window`, `tmux.socket`; for a session provider's
|
|
128
|
+
* `backend`, `session.provider`, `session.endpoint`. Labels only: never a path, a value or the receipt. Callers throw it only once
|
|
152
129
|
* their own comparison has refused, so these labels diagnose a refusal and never decide one. */
|
|
153
130
|
function authorityMismatch(message, meta, authority) {
|
|
154
131
|
const fields = [
|
|
155
|
-
...(meta.launched === authority.launched || promptRetained(meta, authority) ? [] : ["launched"]),
|
|
156
|
-
...(
|
|
132
|
+
...(meta.launched === authority.launched || promptRetained(meta, authority) || (authority.session ?? authority.planned)?.launchSent ? [] : ["launched"]),
|
|
133
|
+
...endpointDifferences(meta, authority),
|
|
157
134
|
];
|
|
158
135
|
return Object.assign(oatsError("E_RUNTIME_AUTHORITY_MISMATCH", message), { details: { fields } });
|
|
159
136
|
}
|
|
@@ -194,9 +171,31 @@ function instanceSessionTarget(home, { absentMeta } = {}) {
|
|
|
194
171
|
if (!isPlainObject(meta)) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `cannot read ${recordPath}: it holds no JSON object`);
|
|
195
172
|
const authority = baseline.version === RETIRE_BASELINE_VERSION && receiptRecordsHome(baseline, canonicalHomePath(home)) && runtimeAuthorityOf(baseline);
|
|
196
173
|
if (!authority) throw oatsError("E_RUNTIME_ENDPOINT_UNKNOWN", `independent session receipt is missing or invalid for ${home}`);
|
|
197
|
-
|
|
198
|
-
|
|
174
|
+
// A home that is being spawned: its receipt is there (a directory home's is written before the
|
|
175
|
+
// spawn's hooks run; planned, never launched) and its record is still the one its files were
|
|
176
|
+
// composed with (lib/materialize.mjs: its modules, and no agent, no launch, no backend yet).
|
|
177
|
+
// The spawn's hooks, and a provider's readiness check, run in between. Nothing contradicts
|
|
178
|
+
// anything: the session is not recorded yet, and a read says so (a presence read that a hook
|
|
179
|
+
// sets off lands here on every spawn).
|
|
180
|
+
const composedOnly = meta.agent === undefined && meta.launch === undefined && meta.backend === undefined && meta.tmux === undefined;
|
|
181
|
+
if (composedOnly && (authority.planned ? !authority.planned.launchSent : authority.launched !== true)) {
|
|
182
|
+
// (Whether that spawn still runs is not told here: one that ended before its record reads the same.)
|
|
183
|
+
throw oatsError("E_SESSION_UNAVAILABLE", `${basename(home)} is being spawned, or its spawn ended before its record was written: its session ${authority.planned ? `is planned on ${authority.planned.backend}` : "is planned"}, and its record is not there yet`);
|
|
184
|
+
}
|
|
185
|
+
if (!launchStateAgrees(meta, authority) || !endpointAgrees(meta, authority)) throw authorityMismatch("instance metadata disagrees with independent session receipt", meta, authority);
|
|
186
|
+
// `unsettled`: a launch that was sent to the home's provider and never recorded, whether the home
|
|
187
|
+
// was launched before or not: `{ backend, provider, launchSent }`, or null. The one place that says so.
|
|
188
|
+
const recorded = authority.session ?? authority.planned ?? null;
|
|
189
|
+
// A provider home's capability rows (settings, hook commands) are its receipt's, never its own
|
|
190
|
+
// record's, which its agent can write (lib/home-integrity.mjs): every verb reads them here.
|
|
191
|
+
meta = trustedRecord(meta, receiptTrust(baseline, home));
|
|
192
|
+
return { home, target: authority.tmux ? { backend: "tmux", ...authority.tmux } : undefined, meta,
|
|
193
|
+
...(authority.session ? { session: authority.session } : {}), ...(authority.planned ? { planned: authority.planned } : {}),
|
|
194
|
+
unsettled: recorded?.launchSent ? { backend: recorded.backend, provider: recorded.provider, launchSent: recorded.launchSent } : null };
|
|
199
195
|
}
|
|
196
|
+
/** The answer for a tmux-only path that meets a home on a session provider (`s`: instanceSessionTarget's
|
|
197
|
+
* answer): the home has no tmux endpoint to read or act on. Undefined for any other home. */
|
|
198
|
+
function providerHomeOf(s) { return s.session ?? s.planned; }
|
|
200
199
|
|
|
201
200
|
/** `wakeHold` (feature wake-hold): whether this home's capabilities said its dialogs become the claims
|
|
202
201
|
* a wake holds on, from the home's record (instance.json `dialogClaims`): `on-claims` if any entry is
|
|
@@ -207,11 +206,47 @@ function wakeHoldOf(meta) {
|
|
|
207
206
|
return answers.includes("reported") ? "on-claims" : answers.includes("none") ? "not-exposed" : "unknown";
|
|
208
207
|
}
|
|
209
208
|
|
|
210
|
-
/**
|
|
209
|
+
/** What a provider home's `session` is in an answer: the capability that supplies its backend and
|
|
210
|
+
* the endpoint the kernel recorded (null before the first launch). */
|
|
211
|
+
export function sessionOf(session) { return { provider: session.provider, endpoint: session.endpoint ?? null }; }
|
|
212
|
+
/** A launched provider home's session, as inspect answers it (docs/desktop-cli-api.md): the
|
|
213
|
+
* provider's own `{ present, state, running, open }`, with the kernel's `backend`, `session`,
|
|
214
|
+
* `waitingOnYou` and `wakeHold`; no pane and no size. Kernel-owned: a home OATS stopped (`stoppedAt`)
|
|
215
|
+
* answers stopped WITHOUT calling the provider, so a session the provider would restart on the next
|
|
216
|
+
* input reads as OATS left it. A provider that fails, refuses or answers outside the contract's
|
|
217
|
+
* words is E_SESSION_UNAVAILABLE, never stopped. `waitingOnYou` is a producer's claim, read
|
|
218
|
+
* whenever the session is not stopped (providerMayWait): an idle session can be the one waiting
|
|
219
|
+
* on a person. */
|
|
220
|
+
function inspectProviderHome(s, wakeHold, io) {
|
|
221
|
+
const answer = { home: s.home, backend: s.session.backend };
|
|
222
|
+
const kernel = { wakeHold, session: sessionOf(s.session) };
|
|
223
|
+
if (s.session.stoppedAt !== null) return { ...answer, present: false, state: "stopped", running: false, waitingOnYou: null, ...kernel, open: null };
|
|
224
|
+
const found = homeSessionProvider(s.home, s.meta, s.session.provider, s.session.backend);
|
|
225
|
+
if (found.problem) throw oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${found.problem}`);
|
|
226
|
+
const inspected = inspectProviderSession(found.binding, s.session.endpoint, { io });
|
|
227
|
+
if (inspected.unavailable) throw oatsError("E_SESSION_UNAVAILABLE", `cannot inspect session: ${inspected.unavailable}`);
|
|
228
|
+
const { present, state, running, open } = inspected.observed;
|
|
229
|
+
return { ...answer, present, state, running, waitingOnYou: providerMayWait(inspected.observed) ? liveWaiting(s.home) : null, ...kernel, open };
|
|
230
|
+
}
|
|
231
|
+
/** Whether a provider's session, as observed, can be waiting on a human: whenever it is not stopped
|
|
232
|
+
* (`running` true or null). An agent that waits on a question is idle where its provider runs it,
|
|
233
|
+
* so it reads `running: null`: the claim is shown then too. Never for a session that is gone (a
|
|
234
|
+
* lost one included) or in error, nor for a home OATS stopped, which is never observed. */
|
|
235
|
+
function providerMayWait(observed) { return observed.present === true && observed.running !== false; }
|
|
236
|
+
|
|
237
|
+
/** `io` (`{ exec }`) is the tmux and process-table seam inspectSessionTarget takes; for a home on a
|
|
238
|
+
* session provider, `io.spawnSync` is the provider call's. */
|
|
211
239
|
export function inspectInstanceSession(home, { io, absentMeta } = {}) {
|
|
212
240
|
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
241
|
const s = instanceSessionTarget(home, { absentMeta });
|
|
214
242
|
const wakeHold = wakeHoldOf(s.meta);
|
|
243
|
+
// A launch that was sent and never recorded (launchSentOf), on a home launched before or not: a
|
|
244
|
+
// session may run that no record names. Unknown, never "not launched" or "stopped", until a stop
|
|
245
|
+
// or a start has settled it.
|
|
246
|
+
if (s.unsettled) throw oatsError("E_SESSION_UNAVAILABLE", unsettledLaunchSaid(basename(s.home), s.unsettled.backend, s.unsettled.launchSent));
|
|
247
|
+
if (s.session) return inspectProviderHome(s, wakeHold, io);
|
|
248
|
+
// A home that will launch on a session provider says which: nothing was launched yet.
|
|
249
|
+
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
250
|
if (!s.target) return { home: s.home, backend: null, present: false, state: "not-launched", running: false, waitingOnYou: null, wakeHold };
|
|
216
251
|
let observed;
|
|
217
252
|
try { observed = inspectSessionTarget(s.target, io, { includeSize: true }); }
|
|
@@ -226,4 +261,5 @@ export function inspectInstanceSession(home, { io, absentMeta } = {}) {
|
|
|
226
261
|
* fallback shell nor a dead pane. Only such a session can be waiting on a human. */
|
|
227
262
|
function harnessRunning(observed) { return observed?.present === true && observed.state !== "shell" && observed.state !== "stopped"; }
|
|
228
263
|
|
|
229
|
-
|
|
264
|
+
// (The receipt's own primitives are lib/session-receipt.mjs's, exported here as they were.)
|
|
265
|
+
export { RETIRE_BASELINE_VERSION, findRetirementBaseline, retirementBaselinePath, authorityMismatch, endpointAgrees, harnessRunning, providerHomeOf, providerMayWait, instanceSessionTarget, instancesRetirementRoot, isPlainObject, launchStateAgrees, missingSessionReceipt, readJsonOrUndefined, receiptHomeIdentity, receiptRecordsHome, recordsHerdr, refuseHerdrHome, runtimeAuthorityOf, tmuxEndpointAgrees };
|