@awebai/oats 0.50.0 → 0.52.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/README.md +1 -0
- package/bin/oats.mjs +153 -51
- package/docs/capabilities.md +11 -3
- package/docs/configuration.md +134 -88
- package/docs/desktop-cli-api.md +994 -71
- package/docs/desktop-instance-start.md +56 -0
- package/docs/desktop.md +10 -7
- package/docs/execution-targets.md +230 -59
- package/docs/first-team.md +3 -1
- package/docs/harness-trust.md +50 -2
- package/docs/implementation.md +73 -8
- package/docs/integrations.md +9 -8
- package/docs/knowledge-reference/acceptance.md +1 -0
- package/docs/knowledge-reference/harvester.md +5 -3
- package/docs/knowledge-reference/model.md +5 -3
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +43 -7
- package/docs/launch-prompt-completion.md +50 -48
- package/docs/oats-local.schema.json +4 -3
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +15 -5
- package/docs/release-notes/v0.44.0.md +1 -1
- package/docs/release-notes/v0.51.0.md +156 -0
- package/docs/release-notes/v0.52.0.md +933 -0
- package/docs/schedules.md +91 -4
- package/docs/servers.md +21 -2
- package/docs/souls-and-instances.md +113 -21
- package/docs/tui.md +152 -0
- package/docs/workspaces.md +2 -2
- package/lib/claim.mjs +266 -0
- package/lib/core.mjs +845 -166
- package/lib/errors.mjs +170 -0
- package/lib/harness-trust-write.mjs +68 -27
- package/lib/harness-trust.mjs +34 -16
- package/lib/instance-inspect.mjs +40 -11
- package/lib/instance-lifecycle.mjs +169 -47
- package/lib/launch-preference.mjs +16 -0
- package/lib/launch-prompt-completion.mjs +7 -43
- package/lib/launch-prompt-evidence.mjs +14 -7
- package/lib/launch-prompt-fixtures/README.md +86 -152
- package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
- package/lib/launch-prompt-fixtures.mjs +122 -109
- package/lib/launch-prompt-transport.mjs +2 -56
- package/lib/launch-prompts.mjs +102 -100
- package/lib/schedule-host.mjs +154 -22
- package/lib/schedule.mjs +73 -24
- package/lib/servers.mjs +20 -4
- package/lib/session-viewer.mjs +87 -10
- package/lib/system-tools.mjs +39 -0
- package/lib/tmux-server-scope.mjs +62 -0
- package/lib/triggers.mjs +4 -4
- package/lib/workspace.mjs +5 -11
- package/lib/worktree-hooks.mjs +116 -23
- package/lib/worktree.mjs +89 -102
- package/package-catalog.json +3 -3
- package/package.json +7 -2
- package/packages/client/capability-show-contract.mjs +230 -0
- package/packages/client/capability-warnings-contract.mjs +57 -0
- package/packages/client/cli-adapter.mjs +548 -0
- package/packages/client/cli-environment.mjs +53 -0
- package/packages/client/cli-locator.mjs +253 -0
- package/packages/client/cli-probe-contract.mjs +47 -0
- package/packages/client/client-terms.mjs +60 -0
- package/packages/client/deployment-contract.mjs +68 -0
- package/packages/client/deployment-data.mjs +483 -0
- package/packages/client/deployment-facts.mjs +34 -0
- package/packages/client/deployment-label.mjs +76 -0
- package/packages/client/deployment-observer.mjs +89 -0
- package/packages/client/deployment-panel.mjs +142 -0
- package/packages/client/deployment-read-cli.mjs +53 -0
- package/packages/client/display-text.mjs +44 -0
- package/packages/client/harness-names.mjs +30 -0
- package/packages/client/inspect-contract.mjs +62 -0
- package/packages/client/instance-acts.mjs +54 -0
- package/packages/client/instance-admission.mjs +45 -0
- package/packages/client/instance-events-contract.mjs +74 -0
- package/packages/client/instance-git-contract.mjs +80 -0
- package/packages/client/instance-presentation.mjs +22 -0
- package/packages/client/instance-tree.mjs +453 -0
- package/packages/client/kernel-environment.mjs +11 -0
- package/packages/client/launch-contract.mjs +51 -0
- package/packages/client/launch-prompt-outcome.mjs +165 -0
- package/packages/client/lifecycle-cli.mjs +61 -0
- package/packages/client/lifecycle-contract.mjs +372 -0
- package/packages/client/liveness-main.mjs +10 -0
- package/packages/client/liveness.mjs +35 -0
- package/packages/client/machine-contract.mjs +123 -0
- package/packages/client/own-environment.mjs +22 -0
- package/packages/client/panel-views.mjs +286 -0
- package/packages/client/readiness-contract.mjs +172 -0
- package/packages/client/refresh-loop.mjs +52 -0
- package/packages/client/remote-address.mjs +126 -0
- package/packages/client/remote-roster.mjs +67 -0
- package/packages/client/roster-sections.mjs +80 -0
- package/packages/client/spawn-apply-cli.mjs +104 -0
- package/packages/client/spawn-apply-contract.mjs +183 -0
- package/packages/client/spawn-decision.mjs +46 -0
- package/packages/client/spawn-messages.mjs +119 -0
- package/packages/client/spawn-preview-cli.mjs +32 -0
- package/packages/client/spawn-preview-contract.mjs +314 -0
- package/packages/client/team-members.mjs +41 -0
- package/packages/client/team-rows.mjs +45 -0
- package/packages/client/terminal-contract.mjs +57 -0
- package/packages/client/tmux-status.mjs +66 -0
- package/packages/client/waiting-on-you.mjs +88 -0
- package/packages/client/workspace-admission.mjs +45 -0
- package/packages/client/workspace-cli.mjs +142 -0
- package/packages/client/workspace-views.mjs +147 -0
- package/packages/tui/README.md +46 -0
- package/packages/tui/bin/tui.mjs +7 -0
- package/packages/tui/lib/actions.mjs +29 -0
- package/packages/tui/lib/client.mjs +4 -0
- package/packages/tui/lib/main.mjs +105 -0
- package/packages/tui/lib/term/keys.mjs +323 -0
- package/packages/tui/lib/term/screen.mjs +122 -0
- package/packages/tui/lib/term/style.mjs +43 -0
- package/packages/tui/lib/term/text.mjs +49 -0
- package/packages/tui/lib/term/tty.mjs +168 -0
- package/packages/tui/lib/term/width.mjs +124 -0
- package/packages/tui/lib/views/frame.mjs +62 -0
- package/packages/tui/lib/views/help.mjs +28 -0
- package/packages/tui/package.json +8 -0
- package/skills/oats-getting-started/SKILL.md +29 -22
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
- package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
- package/lib/launch-prompt-policy.mjs +0 -87
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/** Terminal-target liveness for kernel-reported rows. This is unchanged,
|
|
2
|
+
* v2-agnostic terminal observation: it consults tmux for the exact recorded
|
|
3
|
+
* target, never deployment files. A library only: the program that runs it out
|
|
4
|
+
* of the serving process is liveness-main.mjs (see packages/desktop/server/oats-web.mjs), so a slow
|
|
5
|
+
* terminal server cannot stall request handling. */
|
|
6
|
+
import { createTmuxStatusReader, DEFAULT_TMUX_SESSION } from './tmux-status.mjs';
|
|
7
|
+
import { unsupportedSession } from './instance-presentation.mjs';
|
|
8
|
+
|
|
9
|
+
export { DEFAULT_TMUX_SESSION };
|
|
10
|
+
const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
11
|
+
|
|
12
|
+
/** rows: [{ instance, running?, tmux?, sessionTarget?, runtimeState?, runtimeError? }] in, one liveness
|
|
13
|
+
* per row out. A Herdr-recorded row is never probed: it is unsupported, with the kernel's reason.
|
|
14
|
+
*
|
|
15
|
+
* The probe refines a row only when the kernel answered `running` true or false. A row it answered
|
|
16
|
+
* `running: null` is not probed: its `running`, `runtimeState` and `runtimeError` stay the kernel's,
|
|
17
|
+
* and the answer carries no `tmux`, so the merged row keeps the kernel's own. The kernel answers
|
|
18
|
+
* unknown for a server it could not read, for a missing socket file while a process works in the
|
|
19
|
+
* home, and for a record that cannot be read. Only its `runtimeError` text tells them apart, which
|
|
20
|
+
* no client reads; for the last two a probe would say "stopped" and be wrong. The cost: a kernel
|
|
21
|
+
* read that failed once shows the row as unknown until the next roster read. A row without a
|
|
22
|
+
* `running` key (no kernel sends one) is probed. */
|
|
23
|
+
export function observeLiveness(rows, { tmuxReader = createTmuxStatusReader(), session = DEFAULT_TMUX_SESSION } = {}) {
|
|
24
|
+
if (!Array.isArray(rows) || rows.length > 10000) throw new Error('Invalid liveness request');
|
|
25
|
+
return rows.map(row => {
|
|
26
|
+
if (!record(row) || typeof row.instance !== 'string') return { running: null, runtimeState: 'unreachable', runtimeError: 'Invalid terminal target' };
|
|
27
|
+
const unsupported = unsupportedSession(row);
|
|
28
|
+
if (unsupported) return { running: null, runtimeState: 'unsupported', runtimeError: unsupported.slice(0, 300), tmux: null };
|
|
29
|
+
// After the unsupported check: an older kernel's Herdr row is `unreachable` with a sessionTarget, and reads unsupported.
|
|
30
|
+
if (row.running === null) return { running: null, runtimeState: row.runtimeState ?? 'unreachable', ...(row.runtimeError ? { runtimeError: String(row.runtimeError).slice(0, 300) } : {}) };
|
|
31
|
+
const tmux = record(row.tmux) ? row.tmux : undefined;
|
|
32
|
+
const { tmux: observed, running, runtimeState, runtimeError } = tmuxReader({ instance: row.instance, tmux }, session);
|
|
33
|
+
return { tmux: observed, running, runtimeState, ...(runtimeError ? { runtimeError: String(runtimeError).slice(0, 300) } : {}) };
|
|
34
|
+
});
|
|
35
|
+
}
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
/* oats desktop — a workspace's own machines (#517): the gates, the Add a machine defaults and field
|
|
2
|
+
rules, and the step rows of `oats server connect --json` and `oats aweb connect --json` as the CLI
|
|
3
|
+
sends them (docs/desktop-cli-api.md; interface §2 and §4).
|
|
4
|
+
|
|
5
|
+
Step rows are data: `detail` and `remedy` are shown as the CLI words them, never rewritten. A row
|
|
6
|
+
the contract does not allow is dropped, never guessed.
|
|
7
|
+
|
|
8
|
+
Pure data; no node: imports so the renderer can share it with the server. */
|
|
9
|
+
|
|
10
|
+
/** The kernel's own rules (lib/servers.mjs): a registration id, and an OpenSSH host alias or name. */
|
|
11
|
+
export const MACHINE_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
|
|
12
|
+
export const SSH_HOST = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
|
|
13
|
+
const FOLDER_MAX = 1024;
|
|
14
|
+
|
|
15
|
+
export const CONNECT_STEPS = Object.freeze(['ssh', 'oats', 'git', 'deployment', 'register', 'readiness']);
|
|
16
|
+
export const AWEB_STEPS = Object.freeze(['aw', 'invite', 'join', 'readiness']);
|
|
17
|
+
/** Each status, as its row says it. */
|
|
18
|
+
export const STEP_LABELS = Object.freeze({ ok: 'ok', done: 'done', 'needs-human': 'needs you', skipped: 'waiting', failed: 'failed' });
|
|
19
|
+
|
|
20
|
+
const text = value => typeof value === 'string' && value.length > 0;
|
|
21
|
+
const features = cli => (cli?.ok && Array.isArray(cli.features) ? cli.features : []);
|
|
22
|
+
|
|
23
|
+
/** A workspace's own machines and Add a machine: kernel features servers-per-workspace and server-connect. */
|
|
24
|
+
export function machinesGated(cli) {
|
|
25
|
+
const f = features(cli);
|
|
26
|
+
return f.includes('servers-per-workspace') && f.includes('server-connect');
|
|
27
|
+
}
|
|
28
|
+
/** The messaging step (`oats aweb connect`) also needs capability-route. */
|
|
29
|
+
export function awebConnectGated(cli) {
|
|
30
|
+
return machinesGated(cli) && features(cli).includes('capability-route');
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
const basename = dir => String(dir || '').replace(/\/+$/, '').split('/').pop() || '';
|
|
34
|
+
/** The default Name: `<host>-<this deployment dir basename>`, made a valid registration id. */
|
|
35
|
+
export function machineName(host, deploymentDir) {
|
|
36
|
+
if (!text(host)) return '';
|
|
37
|
+
return `${host}-${basename(deploymentDir)}`.toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/-{2,}/g, '-')
|
|
38
|
+
.replace(/^-+/, '').slice(0, 64).replace(/-+$/, '');
|
|
39
|
+
}
|
|
40
|
+
/** The default Folder on that machine: `~/Agents/<this deployment dir basename>`. */
|
|
41
|
+
export function machineFolder(deploymentDir) {
|
|
42
|
+
return `~/Agents/${basename(deploymentDir)}`;
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/** The first field that the kernel would refuse, as `{ field, text }`, or null. */
|
|
46
|
+
export function machineFieldProblem({ id, host, folder }) {
|
|
47
|
+
if (!text(host)) return { field: 'host', text: 'Type the machine\'s ssh host alias.' };
|
|
48
|
+
if (!SSH_HOST.test(host)) return { field: 'host', text: 'Use an ssh host alias or host name from your ssh config (no user@, no options).' };
|
|
49
|
+
if (!text(id)) return { field: 'id', text: 'Give the machine a name.' };
|
|
50
|
+
if (!MACHINE_ID.test(id)) return { field: 'id', text: 'A name is lowercase letters, digits and dashes, up to 64 characters.' };
|
|
51
|
+
if (!text(folder) || !(folder.startsWith('/') || folder.startsWith('~/')) || folder.length > FOLDER_MAX || /[\u0000-\u001f\u007f]/.test(folder)) {
|
|
52
|
+
return { field: 'folder', text: 'The folder is a path on that machine, starting with / or ~/.' };
|
|
53
|
+
}
|
|
54
|
+
return null;
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
const STATUSES = new Set(Object.keys(STEP_LABELS));
|
|
58
|
+
/** One step row, or null when the contract does not allow it. Optional text fields are kept only as text. */
|
|
59
|
+
function stepRow(row, names) {
|
|
60
|
+
if (!row || typeof row !== 'object' || !names.includes(row.step) || !STATUSES.has(row.status)) return null;
|
|
61
|
+
const out = { step: row.step, status: row.status };
|
|
62
|
+
for (const key of ['code', 'detail', 'remedy', 'hint']) if (text(row[key])) out[key] = row[key];
|
|
63
|
+
return out;
|
|
64
|
+
}
|
|
65
|
+
const stepRows = (value, names) => (Array.isArray(value) ? value.slice(0, 32) : []).map(row => stepRow(row, names)).filter(Boolean);
|
|
66
|
+
|
|
67
|
+
/** A connect envelope (`server connect` or `aweb connect`) as `{ ok, ready, id, steps, error }`.
|
|
68
|
+
* A failed run's steps are `error.details.steps` (the steps so far, the failed one last). */
|
|
69
|
+
export function connectOutcome(envelope, names = CONNECT_STEPS) {
|
|
70
|
+
if (envelope?.ok === true && envelope.result && typeof envelope.result === 'object') {
|
|
71
|
+
const r = envelope.result;
|
|
72
|
+
return { ok: true, ready: r.ready === true, id: text(r.id) ? r.id : text(r.server) ? r.server : null, steps: stepRows(r.steps, names), error: null };
|
|
73
|
+
}
|
|
74
|
+
const error = envelope?.error;
|
|
75
|
+
return { ok: false, ready: false, id: null, steps: stepRows(error?.details?.steps, names),
|
|
76
|
+
error: { code: text(error?.code) ? error.code : 'E_CLI_PROTOCOL', message: text(error?.message) ? error.message : 'oats did not answer as expected' } };
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** Whether connect reached `register` (it registered the machine, now or before). */
|
|
80
|
+
export function registerReached(steps) {
|
|
81
|
+
return (Array.isArray(steps) ? steps : []).some(s => s?.step === 'register' && (s.status === 'ok' || s.status === 'done'));
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/** The commands a remedy names: its backticked spans, in order. */
|
|
85
|
+
export function stepCommands(remedy) {
|
|
86
|
+
if (!text(remedy)) return [];
|
|
87
|
+
return [...remedy.matchAll(/`([^`\n]+)`/g)].map(m => m[1].trim()).filter(Boolean);
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** Why a window offers no remote machine (`machineScope` in packages/desktop/server/oats-web.mjs), one line each. */
|
|
91
|
+
export const MACHINE_SCOPE_REASONS = Object.freeze({
|
|
92
|
+
'no-key': 'This deployment reports no workspace key, so no other machine can be matched to it.',
|
|
93
|
+
'no-local': 'This workspace has no deployment on this computer, so machines are added from one that does.',
|
|
94
|
+
});
|
|
95
|
+
|
|
96
|
+
/** How a consumer follows the server's backfill: the first re-read after BACKFILL_POLL_MS, each next one
|
|
97
|
+
* 1.5 times later, up to BACKFILL_POLL_MAX_MS apart. */
|
|
98
|
+
export const BACKFILL_POLL_MS = 2000;
|
|
99
|
+
export const BACKFILL_POLL_MAX_MS = 15_000;
|
|
100
|
+
/** Consecutive failed reads after which a consumer stops following (the server is gone or refusing). */
|
|
101
|
+
export const BACKFILL_READ_FAILURES = 5;
|
|
102
|
+
/** Read the list again while the server's answers say `backfilling` (packages/desktop/server/machines.mjs): `read()` answers
|
|
103
|
+
* the list, `use(answer)` takes each, `owns()` is the consumer's latest intent (false: stop, nothing used).
|
|
104
|
+
* It follows until an answer is settled: the backfill itself is bounded (each check has its own deadline),
|
|
105
|
+
* so the follow ends with it, at most one read per BACKFILL_POLL_MAX_MS. It stops early when the owner
|
|
106
|
+
* moves on, on stop(), or after BACKFILL_READ_FAILURES failed reads in a row. Returns stop(). */
|
|
107
|
+
export function followBackfill({ read, use, owns = () => true, delay = BACKFILL_POLL_MS, maxDelay = BACKFILL_POLL_MAX_MS, timers = globalThis }) {
|
|
108
|
+
let stopped = false, timer = null, wait = delay, failures = 0;
|
|
109
|
+
const next = () => {
|
|
110
|
+
if (stopped) return;
|
|
111
|
+
timer = timers.setTimeout(async () => {
|
|
112
|
+
timer = null;
|
|
113
|
+
let answer;
|
|
114
|
+
try { answer = await read(); failures = 0; }
|
|
115
|
+
catch { if (++failures < BACKFILL_READ_FAILURES) { wait = Math.min(maxDelay, wait * 1.5); next(); } return; }
|
|
116
|
+
if (stopped || !owns()) return;
|
|
117
|
+
use(answer);
|
|
118
|
+
if (answer?.backfilling === true) { wait = Math.min(maxDelay, wait * 1.5); next(); }
|
|
119
|
+
}, wait);
|
|
120
|
+
};
|
|
121
|
+
next();
|
|
122
|
+
return () => { stopped = true; if (timer !== null) timers.clearTimeout(timer); timer = null; };
|
|
123
|
+
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
// A Desktop process that runs as Node (the backend, the liveness collector) is started with the
|
|
2
|
+
// environment its parent was started with, so the packaged executable starts exactly as before,
|
|
3
|
+
// and then drops what the Desktop and its packaging added: everything it starts inherits the
|
|
4
|
+
// user's environment, with no change at the places that start a program.
|
|
5
|
+
//
|
|
6
|
+
// This must happen before anything else is loaded, because modules take their environment when
|
|
7
|
+
// they are loaded. So it is not a statement in a body: it is the FIRST import of the program's
|
|
8
|
+
// entry module (packages/desktop/server/oats-web.mjs, liveness-main.mjs). A module's imports are evaluated
|
|
9
|
+
// in source order, each one completely before the next. This module and the leaf it imports must
|
|
10
|
+
// have no other imports, so that nothing can load ahead of the step. A library must never import
|
|
11
|
+
// this: it changes the environment of whoever does.
|
|
12
|
+
import { cliEnvironment } from "./cli-environment.mjs";
|
|
13
|
+
|
|
14
|
+
/** The environment this process was started with. Its one use: the backend starts the collector with it. */
|
|
15
|
+
export const launchEnvironment = Object.freeze({ ...process.env });
|
|
16
|
+
|
|
17
|
+
// In place: process.env is never reassigned.
|
|
18
|
+
const user = cliEnvironment(launchEnvironment);
|
|
19
|
+
for (const name of Object.keys(launchEnvironment)) {
|
|
20
|
+
if (!Object.hasOwn(user, name)) delete process.env[name];
|
|
21
|
+
else if (user[name] !== launchEnvironment[name]) process.env[name] = user[name];
|
|
22
|
+
}
|
|
@@ -0,0 +1,286 @@
|
|
|
1
|
+
/** The deployments a client serves and the workspace views over them (#482, workspace-views.mjs; #855, 1d):
|
|
2
|
+
* what the switcher lists, what a panel holds, and which deployment a request is addressed to.
|
|
3
|
+
* A view is one per matched workspace identity, plus one per unattached deployment under that
|
|
4
|
+
* deployment's own id. Everything is built per call from what the client holds; never a CLI read.
|
|
5
|
+
*
|
|
6
|
+
* No state. Every function that reads what a client holds takes it as its first argument, `held`,
|
|
7
|
+
* reads it and never changes it. The client builds one per call from its own store:
|
|
8
|
+
*
|
|
9
|
+
* held = {
|
|
10
|
+
* ctxs, // string[]: this machine's deployments, in served order
|
|
11
|
+
* snapshot, // { byWs: Map<deployment id, entry | remote panel> } (deployment-panel.mjs entries)
|
|
12
|
+
* remoteGroups, // the last readable remote roster's groups (remote-roster.mjs)
|
|
13
|
+
* remembered, // the remembered remote identities: an object with get(id), note(id), all()
|
|
14
|
+
* rosterAnswered, // boolean: a roster answer arrived under the current CLI
|
|
15
|
+
* rosterFailure, // string | null: the roster read's failure while no answer has arrived
|
|
16
|
+
* cli, // the kernel record (cli-locator.mjs)
|
|
17
|
+
* observing, // Set<deployment id>: a read in flight
|
|
18
|
+
* remoteCollecting, // boolean: the remote roster is being read
|
|
19
|
+
* home, // string: the user's home directory, for the short label
|
|
20
|
+
* at, // string: the ISO time of this call
|
|
21
|
+
* }
|
|
22
|
+
*
|
|
23
|
+
* These functions read no clock: the one time they stamp is `held.at`, and the same `held` gives the
|
|
24
|
+
* same answer. A remote deployment's panel is remote-roster.mjs `remotePanel`, made at `held.at`; what
|
|
25
|
+
* a remote roster's answer becomes is that module's.
|
|
26
|
+
*
|
|
27
|
+
* `remembered` is the client's own store, passed in: this module calls its three reading methods and
|
|
28
|
+
* keeps nothing. `note(id)` answers the sentence left for a machine that moved to another workspace,
|
|
29
|
+
* or null. The store's writing method is never called from here.
|
|
30
|
+
*
|
|
31
|
+
* A function that reaches a sentence or a label takes the client's terms (client-terms.mjs) after its
|
|
32
|
+
* required arguments and before its optional ones, and throws without them.
|
|
33
|
+
*
|
|
34
|
+
* Not for a page: this module imports `node:path`, and so does deployment-panel.mjs. */
|
|
35
|
+
import { basename } from 'node:path';
|
|
36
|
+
import { remoteWorkspace, remotePanel } from './remote-roster.mjs';
|
|
37
|
+
import { readIdentity, attachment, buildViews, deploymentReason, deploymentReasonParts } from './workspace-views.mjs';
|
|
38
|
+
import { shortPath, deploymentLabel } from './deployment-label.mjs';
|
|
39
|
+
import { deploymentUnavailableText } from './deployment-facts.mjs';
|
|
40
|
+
import { publicDeployment } from './deployment-panel.mjs';
|
|
41
|
+
import { teamMembers } from './team-members.mjs';
|
|
42
|
+
import { requireTerms } from './client-terms.mjs';
|
|
43
|
+
|
|
44
|
+
/** Roots come ONLY from the kernel's observed `status.root`; before (or
|
|
45
|
+
* without) an observation there is nothing to act on. No layout guess. */
|
|
46
|
+
export function workspaceEntry(held, ctx) {
|
|
47
|
+
const deployment = held.snapshot.byWs.get(ctx)?.deployment;
|
|
48
|
+
const observed = deployment?.status === "observed";
|
|
49
|
+
return { id: ctx, name: (observed && deployment.workspace?.name) || basename(ctx) || ctx, scope: ctx, team: null,
|
|
50
|
+
roots: observed ? [deployment.root] : [] };
|
|
51
|
+
}
|
|
52
|
+
/** Every served deployment, in served order: the local deployments, then the
|
|
53
|
+
* remote roster groups, then (only while there is no roster answer at all) the remembered remote
|
|
54
|
+
* groups, which have no rows. An id here is a deployment id: every instance-addressed route
|
|
55
|
+
* resolves only these. */
|
|
56
|
+
export function deployments(held) {
|
|
57
|
+
return [...held.ctxs.map((ctx) => workspaceEntry(held, ctx)), ...held.remoteGroups.map(remoteWorkspace), ...rememberedGroups(held).map(remoteWorkspace)];
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/** Remembered remote groups shown only while no roster answer exists: not reached, no rows (Q3). */
|
|
61
|
+
export function rememberedGroups(held) {
|
|
62
|
+
if (held.rosterAnswered) return [];
|
|
63
|
+
const listed = new Set(held.remoteGroups.map((g) => g.id));
|
|
64
|
+
return held.remembered.all().filter((e) => !listed.has(e.id)).map((e) => ({
|
|
65
|
+
id: e.id, server: e.server, label: e.label, registrationPresent: true, remembered: true,
|
|
66
|
+
target: { workspace: e.path }, probe: { ok: false, error: { code: "E_REMOTE_ROSTER", message: held.rosterFailure || "no roster answer" } },
|
|
67
|
+
agentsRoot: undefined, workspace: null, souls: [], instances: [], retireFailures: [],
|
|
68
|
+
}));
|
|
69
|
+
}
|
|
70
|
+
const cliReadsRemotes = (held) => !!held.cli.ok && !!held.cli.remote?.includes("roster");
|
|
71
|
+
const identityFeature = (held) => !!held.cli.features?.includes("workspace-identity");
|
|
72
|
+
/** One deployment's identity, attachment, machine label and reason. */
|
|
73
|
+
export function deploymentInfo(held, d, terms) {
|
|
74
|
+
requireTerms(terms, 'deploymentInfo');
|
|
75
|
+
if (!d.remote) {
|
|
76
|
+
const entry = held.snapshot.byWs.get(d.id), observed = entry?.deployment;
|
|
77
|
+
const live = observed?.status === "observed";
|
|
78
|
+
// A failed re-read kept the last observation (deployment-panel.mjs `failedEntry`): its identity still places
|
|
79
|
+
// it in its view, but it is stale, not live, and says why. Still reachable: this computer's own deployment.
|
|
80
|
+
const readError = live && typeof entry.error === "string" ? entry.error : null;
|
|
81
|
+
const read = !live ? { status: "none" } : !identityFeature(held) ? { status: "feature" }
|
|
82
|
+
: observed.reachable?.identityInvalid ? { status: "invalid" } : readIdentity(observed.reachable);
|
|
83
|
+
const identity = read.status === "identity" ? read.identity : null;
|
|
84
|
+
const attach = attachment(identity);
|
|
85
|
+
// Not observed (yet): the reading or unavailable sentence, never a silent empty.
|
|
86
|
+
const unavailable = live ? null : deploymentUnavailableText(observed || { status: "pending" }, terms);
|
|
87
|
+
return { id: d.id, local: true, machine: terms.thisMachine, path: d.id, label: shortPath(d.id, { home: held.home }), name: d.name,
|
|
88
|
+
live: live && !readError, reachable: live, ...(readError ? { stale: true } : {}), identityFrom: identity ? "reported" : null, identity, attach,
|
|
89
|
+
teamLabel: identity?.defaultTeam?.label ?? null,
|
|
90
|
+
...reasonFields(deploymentReasonParts({ local: true, identityStatus: read.status, attach, ref: identity?.ref, unavailable, readError }, terms)),
|
|
91
|
+
note: attach.note === "standalone" ? deploymentReason({ local: true, attach: { unattached: "standalone" } }, terms) : null };
|
|
92
|
+
}
|
|
93
|
+
const g = d.group, machine = g.label || g.server;
|
|
94
|
+
const reached = g.probe?.ok === true;
|
|
95
|
+
let read = reached ? (identityFeature(held) ? readIdentity(g.workspace) : { status: "feature" }) : { status: "none" };
|
|
96
|
+
let identityFrom = read.status === "identity" ? "reported" : null;
|
|
97
|
+
if (!reached && (g.remembered || held.remembered.get(g.id))) {
|
|
98
|
+
const memory = held.remembered.get(g.id);
|
|
99
|
+
if (memory) { read = { status: "identity", identity: memory.workspace }; identityFrom = "remembered"; }
|
|
100
|
+
}
|
|
101
|
+
const identity = read.status === "identity" ? read.identity : null;
|
|
102
|
+
const attach = attachment(identity);
|
|
103
|
+
const reason = reasonFields(deploymentReasonParts({ local: false, machine, sshHost: g.target?.sshHost, probe: g.probe, identityStatus: read.status, attach,
|
|
104
|
+
ref: identity?.ref, cliReadsRemotes: cliReadsRemotes(held), rosterError: g.remembered ? held.rosterFailure : null }, terms));
|
|
105
|
+
const moved = held.remembered.note(g.id);
|
|
106
|
+
const standalone = attach.note === "standalone" ? deploymentReason({ local: false, attach: { unattached: "standalone" } }, terms) : null;
|
|
107
|
+
return { id: d.id, local: false, machine, path: g.target?.workspace || "", label: shortPath(g.target?.workspace || ""), name: d.name,
|
|
108
|
+
live: reached, reachable: reached, identityFrom, identity, attach, teamLabel: identity?.defaultTeam?.label ?? null,
|
|
109
|
+
...reason, note: [moved, standalone].filter(Boolean).join(" ") || null };
|
|
110
|
+
}
|
|
111
|
+
/** A reason's parts as a deployment's fields: `reason` (the full sentence), `short` and `fix` (UI spec, #482). */
|
|
112
|
+
export function reasonFields(parts) {
|
|
113
|
+
return parts ? { reason: parts.detail, short: parts.short, fix: parts.fix } : { reason: null, short: null, fix: [] };
|
|
114
|
+
}
|
|
115
|
+
/** The views and the per-deployment facts they rest on: `{ views, infos: Map<deploymentId, info> }`. */
|
|
116
|
+
export function viewModel(held, terms) {
|
|
117
|
+
requireTerms(terms, 'viewModel');
|
|
118
|
+
const infos = new Map(deployments(held).map((d) => [d.id, deploymentInfo(held, d, terms)]));
|
|
119
|
+
const views = buildViews([...infos.values()]).map((v) => {
|
|
120
|
+
const unattachedReason = v.unattached ? infos.get(v.primary)?.reason ?? null : null;
|
|
121
|
+
const unattachedShort = v.unattached ? infos.get(v.primary)?.short ?? null : null;
|
|
122
|
+
const ref = v.unattached ? infos.get(v.primary)?.identity?.ref ?? null : null;
|
|
123
|
+
return { ...v, ...(unattachedReason ? { reason: unattachedReason } : {}), ...(unattachedShort ? { short: unattachedShort } : {}), ...(ref ? { ref } : {}) };
|
|
124
|
+
});
|
|
125
|
+
return { views, infos };
|
|
126
|
+
}
|
|
127
|
+
/** The view a selector names: a view id, or a deployment id (answered with the view that holds it, so
|
|
128
|
+
* a selection saved before views opens its view). No selector means the first view. `model` is a
|
|
129
|
+
* view model already built for this call (`viewModel`); without one, it is built here. */
|
|
130
|
+
export function viewFor(held, wsId, terms, model) {
|
|
131
|
+
requireTerms(terms, 'viewFor');
|
|
132
|
+
if (model === undefined) model = viewModel(held, terms);
|
|
133
|
+
if (!wsId) return model.views[0] || null;
|
|
134
|
+
return model.views.find((v) => v.id === wsId) || model.views.find((v) => v.deployments.includes(wsId)) || null;
|
|
135
|
+
}
|
|
136
|
+
/** A deployment-level surface (header, capabilities, sync, automations, schedules, teams configuration,
|
|
137
|
+
* brain, launch configurations, spawn catalog): a deployment id as itself, a view id as that view's
|
|
138
|
+
* PRIMARY deployment (its first local one, else its first). Never used for an instance-addressed route,
|
|
139
|
+
* which resolves deployment ids only (`deployments(held).find`), so a view id there is refused. */
|
|
140
|
+
export function deploymentFor(held, wsId, terms) {
|
|
141
|
+
requireTerms(terms, 'deploymentFor');
|
|
142
|
+
const exact = wsId ? deployments(held).find((w) => w.id === wsId) : null;
|
|
143
|
+
if (exact) return exact;
|
|
144
|
+
const view = viewFor(held, wsId, terms);
|
|
145
|
+
return view ? deployments(held).find((w) => w.id === view.primary) || null : null;
|
|
146
|
+
}
|
|
147
|
+
/** A body that names an instance home (capabilities, launch configurations, schedules) addresses that
|
|
148
|
+
* instance: only an exact deployment id resolves it, never a view id. Anything else is deployment-level. */
|
|
149
|
+
const namesInstance = (request) => request?.selector?.home !== undefined || request?.spec?.home !== undefined;
|
|
150
|
+
export function surfaceDeployment(held, wsId, request, terms) {
|
|
151
|
+
requireTerms(terms, 'surfaceDeployment');
|
|
152
|
+
if (!wsId) return undefined; // these routes name their workspace: no selector is no workspace, never the first
|
|
153
|
+
return namesInstance(request) ? deployments(held).find((w) => w.id === wsId) : deploymentFor(held, wsId, terms);
|
|
154
|
+
}
|
|
155
|
+
/** The forge roster's context for a view (or a deployment id, read as its view): the union of its
|
|
156
|
+
* local deployments' rows and clones, under the view's id. */
|
|
157
|
+
export function viewForgeContext(held, wsId, terms) {
|
|
158
|
+
requireTerms(terms, 'viewForgeContext');
|
|
159
|
+
const view = viewFor(held, wsId, terms);
|
|
160
|
+
if (!view) return { workspace: undefined, cli: held.cli, instances: [], clones: [] };
|
|
161
|
+
const local = view.deployments.filter((id) => held.ctxs.includes(id));
|
|
162
|
+
const observed = local.map((id) => held.snapshot.byWs.get(id)).filter(Boolean);
|
|
163
|
+
return { workspace: { id: view.id, name: view.name, remote: local.length === 0 }, cli: held.cli,
|
|
164
|
+
instances: observed.flatMap((o) => o.instances || []), clones: observed.flatMap((o) => o.deployment?.workspaceStatus?.clones || []) };
|
|
165
|
+
}
|
|
166
|
+
/** One deployment's own rows (never its view's union): what an instance-addressed request may admit. */
|
|
167
|
+
export function deploymentRows(held, ws) {
|
|
168
|
+
return deploymentPanel(held, ws).instances || [];
|
|
169
|
+
}
|
|
170
|
+
/** The ids a client may let a caller select: every view id and every deployment id. */
|
|
171
|
+
export function isServed(held, id, terms) {
|
|
172
|
+
requireTerms(terms, 'isServed');
|
|
173
|
+
const model = viewModel(held, terms);
|
|
174
|
+
return model.views.some((v) => v.id === id) || model.infos.has(id);
|
|
175
|
+
}
|
|
176
|
+
/** The members of a view's deployments only, each tagged with its deployment (Q5; team-members.mjs);
|
|
177
|
+
* null for a selector that names no view. */
|
|
178
|
+
export function teamMembersFor(held, wsId, terms) {
|
|
179
|
+
requireTerms(terms, 'teamMembersFor');
|
|
180
|
+
const model = viewModel(held, terms);
|
|
181
|
+
const view = viewFor(held, wsId, terms, model);
|
|
182
|
+
if (!view) return null;
|
|
183
|
+
const members = view.deployments.map((id) => deployments(held).find((w) => w.id === id)).filter(Boolean);
|
|
184
|
+
return teamMembers({
|
|
185
|
+
deployments: members.filter((d) => !d.remote).map((d) => ({ deployment: deploymentTag(model.infos.get(d.id)), instances: held.snapshot.byWs.get(d.id)?.instances || [] })),
|
|
186
|
+
groups: members.filter((d) => d.remote).map((d) => ({ group: d.group, deployment: deploymentTag(model.infos.get(d.id)),
|
|
187
|
+
panel: held.snapshot.byWs.get(d.id) || remotePanel(d.group, held.at) })) });
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/** A workspace's own machines (#517): the view's key, the deployment every
|
|
191
|
+
* machine call runs in and its messaging slot. The key is the one the view's primary local deployment
|
|
192
|
+
* reports (keyFrom "workspace" only; a matched view's deployments all share it); without one, or with no
|
|
193
|
+
* local deployment, `key` is null and `reason` says which. null for a selector that names no view. */
|
|
194
|
+
export function machineScope(held, wsId, terms) {
|
|
195
|
+
requireTerms(terms, 'machineScope');
|
|
196
|
+
const model = viewModel(held, terms);
|
|
197
|
+
const view = viewFor(held, wsId, terms, model);
|
|
198
|
+
if (!view) return null;
|
|
199
|
+
const local = view.deployments.map((id) => model.infos.get(id)).find((info) => info?.local);
|
|
200
|
+
if (!local) return { key: null, deployment: null, messaging: null, reason: "no-local" };
|
|
201
|
+
const identity = local.identity;
|
|
202
|
+
const messaging = held.snapshot.byWs.get(local.id)?.deployment?.workspaceStatus?.defaults?.slots?.messaging?.name ?? null;
|
|
203
|
+
if (identity?.keyFrom !== "workspace" || typeof identity.key !== "string" || !identity.key) return { key: null, deployment: local.id, messaging, reason: "no-key" };
|
|
204
|
+
return { key: identity.key, deployment: local.id, messaging };
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
/** A deployment as the panel and the rows name it. */
|
|
208
|
+
export const deploymentTag = (info) => ({ id: info.id, machine: info.machine, path: info.path });
|
|
209
|
+
/** A deployment's entry in the panel's `deployments` list (roster-sections.mjs `deploymentState` reads one). */
|
|
210
|
+
export function deploymentEntry(info, primary) {
|
|
211
|
+
return { ...deploymentTag(info), label: info.label, local: info.local, reachable: info.reachable,
|
|
212
|
+
identityFrom: info.identityFrom, primary: info.id === primary, ...(info.stale ? { stale: true } : {}),
|
|
213
|
+
...(info.reason ? { reason: info.reason } : {}), ...(info.short ? { short: info.short } : {}),
|
|
214
|
+
...(info.reason && info.fix?.length ? { fix: [...info.fix] } : {}), ...(info.note ? { note: info.note } : {}) };
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/** One deployment's own panel, as served before views. */
|
|
218
|
+
export function deploymentPanel(held, ws) {
|
|
219
|
+
if (ws?.remote) return { ...remotePanel(ws.group, held.at), observedAt: null, refreshing: held.remoteCollecting };
|
|
220
|
+
const observed = ws ? held.snapshot.byWs.get(ws.id) : null;
|
|
221
|
+
const instances = observed?.instances || [];
|
|
222
|
+
return {
|
|
223
|
+
workspace: ws ? { id: ws.id, name: ws.name, team: null } : null,
|
|
224
|
+
team: null,
|
|
225
|
+
deployment: publicDeployment(observed?.deployment),
|
|
226
|
+
generatedAt: observed?.generatedAt || held.at,
|
|
227
|
+
// When the kernel observed the remotes this roster rests on, and whether a newer
|
|
228
|
+
// observation of this deployment is running right now (a client labels stale data).
|
|
229
|
+
observedAt: observed?.observedAt ?? null,
|
|
230
|
+
refreshing: !!ws && held.observing.has(ws.id),
|
|
231
|
+
running: instances.filter((i) => i.running).length,
|
|
232
|
+
instances,
|
|
233
|
+
// A failed re-read kept the last observation (deployment-panel.mjs `failedEntry`): the kernel's message and its bounded cause.
|
|
234
|
+
...(typeof observed?.error === "string" ? { error: observed.error } : {}),
|
|
235
|
+
...(observed?.errorCause ? { errorCause: observed.errorCause } : {}),
|
|
236
|
+
};
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/** Panel data is served from the latest observation and never blocks on a
|
|
240
|
+
* CLI read: a client's views and its readiness probes stay responsive. A view's panel is its
|
|
241
|
+
* primary deployment's panel (header, error, stamps) with the union of every deployment's rows,
|
|
242
|
+
* each row tagged with its deployment, and the view's deployments listed. */
|
|
243
|
+
export function panelData(held, wsId, terms) {
|
|
244
|
+
requireTerms(terms, 'panelData');
|
|
245
|
+
const model = viewModel(held, terms);
|
|
246
|
+
const view = viewFor(held, wsId, terms, model);
|
|
247
|
+
const choices = workspaceChoices(held, terms, model);
|
|
248
|
+
if (!view) return { ...deploymentPanel(held, null), workspaces: choices, deployments: [] };
|
|
249
|
+
const members = view.deployments.map((id) => deployments(held).find((w) => w.id === id)).filter(Boolean);
|
|
250
|
+
const panels = members.map((d) => [d, deploymentPanel(held, d)]);
|
|
251
|
+
const [, primary] = panels.find(([d]) => d.id === view.primary) || panels[0];
|
|
252
|
+
const instances = panels.flatMap(([d, p]) => (p.instances || []).map((row) => ({ ...row, deployment: deploymentTag(model.infos.get(d.id)) })));
|
|
253
|
+
return {
|
|
254
|
+
...primary,
|
|
255
|
+
// `primary`: the deployment a deployment-level request is addressed to (it echoes that deployment back).
|
|
256
|
+
workspace: { ...primary.workspace, id: view.id, name: view.name, primary: view.primary, ...(view.key ? { key: view.key, teamId: view.team } : {}) },
|
|
257
|
+
workspaces: choices,
|
|
258
|
+
deployments: view.deployments.map((id) => deploymentEntry(model.infos.get(id), view.primary)),
|
|
259
|
+
refreshing: panels.some(([, p]) => p.refreshing),
|
|
260
|
+
running: instances.filter((i) => i.running).length,
|
|
261
|
+
instances,
|
|
262
|
+
};
|
|
263
|
+
}
|
|
264
|
+
|
|
265
|
+
/** The switcher's list: views, not deployments. Each names its deployments (a client lets a caller
|
|
266
|
+
* select any of these ids); an unattached view keeps today's remote fields and says why. `model` is a
|
|
267
|
+
* view model already built for this call (`viewModel`); without one, it is built here. */
|
|
268
|
+
export function workspaceChoices(held, terms, model) {
|
|
269
|
+
requireTerms(terms, 'workspaceChoices');
|
|
270
|
+
if (model === undefined) model = viewModel(held, terms);
|
|
271
|
+
return model.views.map((v) => {
|
|
272
|
+
const primary = deployments(held).find((w) => w.id === v.primary);
|
|
273
|
+
const remoteOnly = v.deployments.every((id) => !model.infos.get(id)?.local);
|
|
274
|
+
// Without the CLI's workspace-identity feature nothing can match: every deployment keeps its own entry, listed as
|
|
275
|
+
// before views, not as "not matched" (each deployment's own reason still says why).
|
|
276
|
+
const unmatched = v.unattached && identityFeature(held);
|
|
277
|
+
return { id: v.id, name: v.name, team: null, deployments: [...v.deployments],
|
|
278
|
+
// The deployments' labels, in the same order, for a view that is not on screen ("This Mac · ~/Agents/oats").
|
|
279
|
+
deploymentLabels: v.deployments.map((id) => deploymentLabel(model.infos.get(id), terms)),
|
|
280
|
+
// The switcher's one-liner (UI spec, #482): the machines, in order and once each, and how many deployments aren't live.
|
|
281
|
+
machines: [...new Set(v.deployments.map((id) => model.infos.get(id)?.machine).filter(Boolean))],
|
|
282
|
+
notLive: v.deployments.filter((id) => !model.infos.get(id)?.live).length,
|
|
283
|
+
...(v.key ? { key: v.key } : {}), ...(unmatched ? { unattached: true } : {}), ...(unmatched && v.reason ? { reason: v.reason } : {}), ...(unmatched && v.short ? { short: v.short } : {}), ...(unmatched && v.ref ? { ref: v.ref } : {}),
|
|
284
|
+
...(remoteOnly && primary?.remote ? { server: primary.server, remote: true } : {}) };
|
|
285
|
+
});
|
|
286
|
+
}
|