@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
|
@@ -10,7 +10,8 @@ import { readIdentity } from './workspace-views.mjs';
|
|
|
10
10
|
import { waitingOnYouData } from './waiting-on-you.mjs';
|
|
11
11
|
import { attributedHumanData } from './attributed-human.mjs';
|
|
12
12
|
import { retireData } from './retire-state.mjs';
|
|
13
|
-
import { instanceColor } from './instance-presentation.mjs';
|
|
13
|
+
import { instanceColor, openLink, sessionThreadId } from './instance-presentation.mjs';
|
|
14
|
+
import { boardData } from './instance-board.mjs';
|
|
14
15
|
const text = value => typeof value === 'string' && value.length <= 8192 && !value.includes('\0');
|
|
15
16
|
const absolute = value => text(value) && isAbsolute(value) && resolve(value) === value;
|
|
16
17
|
const own = (value, key) => Object.hasOwn(value, key);
|
|
@@ -215,6 +216,24 @@ export function deploymentStatusData(document, deployment) {
|
|
|
215
216
|
}
|
|
216
217
|
if (own(instance, 'tmux')) row.tmux = instance.tmux === null ? null : fields(instance.tmux, ['session', 'window', 'socket']);
|
|
217
218
|
if (own(instance, 'sessionTarget')) row.sessionTarget = sessionTarget(instance.sessionTarget);
|
|
219
|
+
// Session providers (feature session-providers): where the instance runs, when it is not tmux's. Validated,
|
|
220
|
+
// never check()ed: `backend` is kept when it is text that is not empty (instance-presentation.mjs `sessionProvider` reads it:
|
|
221
|
+
// "tmux", or anything else, which is a provider's and never asked of tmux), else dropped, and the row reads
|
|
222
|
+
// as one with none (a tmux row). "herdr" is not kept: a Herdr-recorded row of this machine is known by its
|
|
223
|
+
// `sessionTarget` or its `runtimeState`, as before session providers, and a row that only names the backend
|
|
224
|
+
// reads as it always did. Of `session` the
|
|
225
|
+
// row keeps the provider's capability and, on this machine's rows, the thread id (`session.threadId`), both
|
|
226
|
+
// for display only; of `open` the link a client may show in place of a terminal (`openLink`: an http(s) url).
|
|
227
|
+
// A value this reader's text check refuses (over-long, or with a NUL) is not carried, and still is no tmux's:
|
|
228
|
+
// the row then names the contract's reserved word for any provider, which is never a provider's name.
|
|
229
|
+
if (own(instance, 'backend') && typeof instance.backend === 'string' && instance.backend.length > 0 && instance.backend !== 'herdr')
|
|
230
|
+
row.backend = text(instance.backend) ? instance.backend : 'session-provider';
|
|
231
|
+
if (own(instance, 'session') && record(instance.session)) {
|
|
232
|
+
const provider = instance.session.provider, threadId = sessionThreadId(instance);
|
|
233
|
+
const session = { ...(text(provider) && provider.length > 0 && provider.length <= 200 ? { provider } : {}), ...(threadId !== null ? { threadId } : {}) };
|
|
234
|
+
if (Object.keys(session).length) row.session = session;
|
|
235
|
+
}
|
|
236
|
+
if (own(instance, 'open')) { const link = openLink(instance); if (link !== null) row.open = link; }
|
|
218
237
|
if (own(instance, 'retirePending')) row.retirePending = true;
|
|
219
238
|
// #1247 (feature status-retire-state): the retire that runs, or failed, or was interrupted. Validated, never
|
|
220
239
|
// check()ed: a value out of the contract is dropped and the row reads as if it had none.
|
|
@@ -241,6 +260,9 @@ export function deploymentStatusData(document, deployment) {
|
|
|
241
260
|
// (related-work.mjs). Boolean true only; any other value is dropped, never checked: the row reads unflagged.
|
|
242
261
|
if (own(instance, 'relatedWork') && instance.relatedWork === true) row.relatedWork = true;
|
|
243
262
|
if (own(instance, 'sameWork') && instance.sameWork === true) row.sameWork = true;
|
|
263
|
+
// Feature instance-board: the agent's facts and questions (instance-board.mjs). Validated, never check()ed: a
|
|
264
|
+
// malformed board reads as none (null), its malformed entries are left out. Absent stays absent.
|
|
265
|
+
if (own(instance, 'board')) row.board = boardData(instance.board);
|
|
244
266
|
if (own(instance, 'modules')) row.modules = modules(instance.modules);
|
|
245
267
|
if (own(instance, 'soul')) row.soul = soulSource(instance.soul);
|
|
246
268
|
if (own(instance, 'workspace')) row.workspace = recordedWorkspace(instance.workspace);
|
|
@@ -14,10 +14,15 @@
|
|
|
14
14
|
* test/inventory.test.mjs holds that its page reaches no module that imports a Node builtin. */
|
|
15
15
|
import { dirname } from 'node:path';
|
|
16
16
|
import { livenessOrigin } from './liveness.mjs';
|
|
17
|
-
import { knownOrigin, hasRuntimeError, byRuntimeState, instanceColor } from './instance-presentation.mjs';
|
|
17
|
+
import { knownOrigin, hasRuntimeError, byRuntimeState, instanceColor, sessionProvider } from './instance-presentation.mjs';
|
|
18
18
|
import { retireData } from './retire-state.mjs';
|
|
19
19
|
|
|
20
20
|
const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
21
|
+
/** The `backend` a row of this machine carries on, or undefined: the row's own, but never "herdr". A Herdr-recorded
|
|
22
|
+
* row of this machine is known by its `sessionTarget` or its `runtimeState` (instance-presentation.mjs
|
|
23
|
+
* `unsupportedSession`), as before session providers; one that only names the backend reads as it always did.
|
|
24
|
+
* deployment-data.mjs already drops it from a kernel's row; this serves the rows that reach the panel another way. */
|
|
25
|
+
const localBackend = (row) => (row.backend === 'herdr' ? undefined : row.backend);
|
|
21
26
|
|
|
22
27
|
/** One row per instance of a roster (deployment-data.mjs `deploymentStatusData`): the kernel's row,
|
|
23
28
|
* with `agent`, `description` and `team` from its soul and `agentsRoot` from the roster, and `soulKey`, the
|
|
@@ -53,6 +58,9 @@ export function kernelLiveness(cli) {
|
|
|
53
58
|
* `running` is the kernel's answer: the collector leaves a row it answered `null` as the kernel has it. */
|
|
54
59
|
export function livenessInput(rows) {
|
|
55
60
|
return rows.map((i) => ({ instance: i.instance, running: i.running, tmux: i.tmux, sessionTarget: i.sessionTarget,
|
|
61
|
+
// A row on a session provider is never probed (liveness.mjs): the collector knows it by its `backend`. Never
|
|
62
|
+
// "herdr": a Herdr-recorded row of this machine is known by its `sessionTarget` or its state, as before.
|
|
63
|
+
...(localBackend(i) !== undefined ? { backend: localBackend(i) } : {}),
|
|
56
64
|
runtimeState: i.runtimeState, runtimeError: i.runtimeError }));
|
|
57
65
|
}
|
|
58
66
|
|
|
@@ -105,6 +113,13 @@ export function panelInstance(i) {
|
|
|
105
113
|
// Who made that text: only beside a `runtimeError`, and only one of the three speakers.
|
|
106
114
|
...(hasRuntimeError(i) && knownOrigin(i.runtimeErrorOrigin) ? { runtimeErrorOrigin: i.runtimeErrorOrigin } : {}),
|
|
107
115
|
tmux: i.tmux, git: null,
|
|
116
|
+
// Session providers: the row's backend ("tmux" or a provider's name), the provider's capability and thread
|
|
117
|
+
// id, and the link it offers in place of a terminal, each as deployment-data.mjs validated it; absent stays
|
|
118
|
+
// absent. instance-presentation.mjs `sessionProvider` and instance-acts.mjs `openAct` read them. "herdr" is no
|
|
119
|
+
// backend of a row of this machine (`localBackend`).
|
|
120
|
+
...(localBackend(i) !== undefined ? { backend: localBackend(i) } : {}),
|
|
121
|
+
...(i.session !== undefined ? { session: i.session } : {}),
|
|
122
|
+
...(i.open !== undefined ? { open: i.open } : {}),
|
|
108
123
|
// Workspace-model v2 facts exactly as `oats status --json` reported them:
|
|
109
124
|
// module drift rows (or the recorded map when the workspace is
|
|
110
125
|
// unreachable), the soul source and the served identity. Identity is
|
|
@@ -142,6 +157,8 @@ export function panelInstance(i) {
|
|
|
142
157
|
...(i.background === true ? { background: true } : {}),
|
|
143
158
|
// Feature instance-pin: exactly true, else absent (instance-tree.mjs rowPinned).
|
|
144
159
|
...(i.pinned === true ? { pinned: true } : {}),
|
|
160
|
+
// Feature instance-board: the board deployment-data.mjs validated (instance-board.mjs), or null; absent stays absent.
|
|
161
|
+
...(i.board !== undefined ? { board: i.board } : {}),
|
|
145
162
|
team: i.team || null,
|
|
146
163
|
};
|
|
147
164
|
}
|
|
@@ -152,10 +169,15 @@ export function panelInstance(i) {
|
|
|
152
169
|
*
|
|
153
170
|
* The merged row's `runtimeErrorOrigin` is set here or removed, whatever the row carried: when the
|
|
154
171
|
* answer holds the `runtimeError`, the answer's speaker; when the answer has none and the kernel's row
|
|
155
|
-
* had one (a probed row the kernel reported with a text), the text is the kernel's, so "kernel".
|
|
172
|
+
* had one (a probed row the kernel reported with a text), the text is the kernel's, so "kernel".
|
|
173
|
+
*
|
|
174
|
+
* A row on a session provider (instance-presentation.mjs `sessionProvider`) takes nothing from its answer: the
|
|
175
|
+
* collector knows nothing of it, so whatever it printed for the row, and the unknown answer written for every row
|
|
176
|
+
* when the collector failed (`livenessAnswers`), is left out. Its `running`, `runtimeState` and `runtimeError` are
|
|
177
|
+
* the kernel's, whole, and its text's speaker is the kernel. */
|
|
156
178
|
export function panelInstances(rows, answers) {
|
|
157
179
|
return rows.map((row, index) => {
|
|
158
|
-
const answer = answers[index], { runtimeErrorOrigin: _carried, ...merged } = { ...row, ...answer };
|
|
180
|
+
const answer = sessionProvider(row) ? undefined : answers[index], { runtimeErrorOrigin: _carried, ...merged } = { ...row, ...answer };
|
|
159
181
|
const origin = record(answer) && Object.hasOwn(answer, "runtimeError") ? answer.runtimeErrorOrigin : "kernel";
|
|
160
182
|
return panelInstance(hasRuntimeError(merged) ? { ...merged, runtimeErrorOrigin: origin } : merged);
|
|
161
183
|
}).sort(byRuntimeState);
|
|
@@ -1,44 +1,58 @@
|
|
|
1
|
-
/** Home's board and its flat list of agents (Desktop UI rework,
|
|
2
|
-
* TUI can render the same Home later. Pure, no DOM, never throws. Rows are `oats status --json` instance rows
|
|
3
|
-
* the roster holds them; nothing here reorders the roster (needs-input-preserves-liveness-and-recognition: the
|
|
1
|
+
/** Home's board and its flat list of agents (Desktop UI rework, slices 2 and 2b): the groupings both clients draw,
|
|
2
|
+
* so the TUI can render the same Home later. Pure, no DOM, never throws. Rows are `oats status --json` instance rows
|
|
3
|
+
* as the roster holds them; nothing here reorders the roster (needs-input-preserves-liveness-and-recognition: the
|
|
4
4
|
* urgency order lives on Home only).
|
|
5
5
|
*
|
|
6
|
-
* homeBoard(rows, { stale }) -> { needsYou: [{ row, claim }], running: [row] }
|
|
6
|
+
* homeBoard(rows, { stale, pins }) -> { needsYou: [{ row, claim }], running: [row], counts: { agents, running, needYou, stopped, unknown } }
|
|
7
7
|
* needsYou: every row with a claim it may show (waiting-on-you.mjs `waitingClaim`, the one liveness gate,
|
|
8
8
|
* `stale(row)` the roster's held-stale rule), newest claim first (its `since`), then the roster's
|
|
9
|
-
* order.
|
|
10
|
-
*
|
|
9
|
+
* order.
|
|
10
|
+
* running: every other live row, in the roster's order (pinned first where `pins`, as homeAgents): Home shows
|
|
11
|
+
* the first few, cropped and expandable (slice 2b, Amendment 1: Pepe, 2026-11-20).
|
|
12
|
+
* counts: the summary line's numbers. agents: every row. needYou: the rows in needsYou. running: every other live row
|
|
13
|
+
* (`running === true`, no reported state but `running`, a reached server; a row on a session
|
|
14
|
+
* provider on `running === true` and a reached server alone). stopped: every other row
|
|
15
|
+
* that says `running: false`. unknown: the rest (no runtime fact, an unreached server, another
|
|
16
|
+
* reported state). Each row is counted once, so the four add up to agents. There is no working/idle
|
|
11
17
|
* fact yet (the activity contract is not built), and none is inferred
|
|
12
|
-
* (instance-activity-is-reported-not-inferred): a live row is "running".
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
18
|
+
* (instance-activity-is-reported-not-inferred): a live row is "running".
|
|
19
|
+
* homeAgents(rows, { pins }) -> rows: every agent, running or stopped, in the roster's order: pinned rows first
|
|
20
|
+
* where the roster shows pins (`pins`: the CLI lists PIN_FEATURE; instance-tree.mjs `rowPinned`,
|
|
21
|
+
* #1974's shared order), then newest spawn first (`rosterOrder`).
|
|
16
22
|
* startedBy(row) -> string | null: who started it, the row's attributed human (attributed-human.mjs), else
|
|
17
23
|
* its parent's name (`parentInstance`), else null. */
|
|
18
24
|
import { waitingClaim } from './waiting-on-you.mjs';
|
|
19
|
-
import { rosterOrder } from './instance-tree.mjs';
|
|
25
|
+
import { rosterOrder, rowPinned } from './instance-tree.mjs';
|
|
20
26
|
import { attributedHumanData } from './attributed-human.mjs';
|
|
21
27
|
import { instanceDisplayName } from './instance-display-name.mjs';
|
|
28
|
+
import { sessionProvider } from './instance-presentation.mjs';
|
|
22
29
|
|
|
23
30
|
const record = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
|
|
24
31
|
const rowsOf = (rows) => (Array.isArray(rows) ? rows.filter((row) => record(row) && typeof row.instance === 'string' && row.instance) : []);
|
|
25
32
|
const since = (claim) => { const t = Date.parse(claim.since); return Number.isFinite(t) ? t : -Infinity; };
|
|
26
|
-
|
|
33
|
+
// A row on a session provider is live on `running === true` alone: its `runtimeState` is the provider's word
|
|
34
|
+
// ("unknown" while it runs), never tmux's "running".
|
|
35
|
+
const live = (row) => row.running === true && row.serverUnreached !== true
|
|
36
|
+
&& (row.runtimeState == null || row.runtimeState === 'running' || sessionProvider(row) !== null);
|
|
27
37
|
|
|
28
|
-
export function homeBoard(rows, { stale = () => false } = {}) {
|
|
29
|
-
const needsYou = [], running = [];
|
|
38
|
+
export function homeBoard(rows, { stale = () => false, pins = false } = {}) {
|
|
39
|
+
const needsYou = [], running = [], counts = { agents: 0, running: 0, needYou: 0, stopped: 0, unknown: 0 };
|
|
30
40
|
for (const row of rowsOf(rows)) {
|
|
41
|
+
counts.agents++;
|
|
31
42
|
const claim = waitingClaim(row, { stale: stale(row) === true });
|
|
32
43
|
if (claim) needsYou.push({ row, claim });
|
|
33
|
-
else if (live(row)) running.push(row);
|
|
44
|
+
else if (live(row)) { counts.running++; running.push(row); }
|
|
45
|
+
else if (row.running === false) counts.stopped++;
|
|
46
|
+
else counts.unknown++;
|
|
34
47
|
}
|
|
35
48
|
needsYou.sort((a, b) => since(b.claim) - since(a.claim) || rosterOrder(a.row, b.row));
|
|
36
|
-
|
|
37
|
-
return { needsYou, running };
|
|
49
|
+
counts.needYou = needsYou.length;
|
|
50
|
+
return { needsYou, running: homeAgents(running, { pins }), counts };
|
|
38
51
|
}
|
|
39
52
|
|
|
40
|
-
export function homeAgents(rows) {
|
|
41
|
-
|
|
53
|
+
export function homeAgents(rows, { pins = false } = {}) {
|
|
54
|
+
const pinned = (row) => (rowPinned(row, pins) ? 1 : 0);
|
|
55
|
+
return rowsOf(rows).sort((a, b) => pinned(b) - pinned(a) || rosterOrder(a, b));
|
|
42
56
|
}
|
|
43
57
|
|
|
44
58
|
export function startedBy(row) {
|
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
* maxAge seconds the kernel may reuse remote observations on a miss (a local inspect only)
|
|
10
10
|
* exec how the CLI is run (cli-adapter.mjs `runJson`'s `io.exec`); without it, execFile
|
|
11
11
|
*
|
|
12
|
-
* request { action: 'inspect', selector: { soul, agentsRoot } | { home }, refresh?, instructions?, skills?, composedSkills? }
|
|
12
|
+
* request { action: 'inspect', selector: { soul, agentsRoot } | { home }, refresh?, instructions?, skills?, composedSkills?, board? }
|
|
13
13
|
* context { workspace, cli, agents, instances, localCwd, catalogKey }
|
|
14
14
|
*
|
|
15
15
|
* It resolves the kernel's result with `observedAt` and `refreshing`, and throws an Error with a stable `code`
|
|
@@ -28,7 +28,8 @@ import { cliCapability, operationArgs } from './cli-adapter.mjs';
|
|
|
28
28
|
import { inspectKey } from './inspect-cache.mjs';
|
|
29
29
|
import { observationData } from './deployment-data.mjs';
|
|
30
30
|
import { OBSERVE_MAX_AGE_FEATURE } from './deployment-contract.mjs';
|
|
31
|
-
import { hostComposes, hostReportsSkills, hostComposesSkills } from './composed-gate.mjs';
|
|
31
|
+
import { hostComposes, hostReportsSkills, hostComposesSkills, hostAdvertises, PROBE_FEATURES_FEATURE } from './composed-gate.mjs';
|
|
32
|
+
import { BOARD_FEATURE } from './instance-board.mjs';
|
|
32
33
|
import { canAddressRemote, unaddressableSentence, hostReason, shownLabel, unroutableReason } from './remote-address.mjs';
|
|
33
34
|
|
|
34
35
|
const fail = (message, code = 'E_BAD_ARGS') => { throw Object.assign(new Error(message), { code }); };
|
|
@@ -37,7 +38,7 @@ const TEAM_LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
|
|
|
37
38
|
|
|
38
39
|
/** Admit a capability request in its context, or throw. `actions`: the actions the caller serves (an inspect
|
|
39
40
|
* boundary serves only 'inspect'); any other is the same refusal as an unknown one. Returns what the call needs:
|
|
40
|
-
* `{ action, server, label, refresh, instructions, skills, composedSkills, soul, agentsRoot, home, context, key }`, where
|
|
41
|
+
* `{ action, server, label, refresh, instructions, skills, composedSkills, board, soul, agentsRoot, home, context, key }`, where
|
|
41
42
|
* `context` is the --dir the CLI runs in and `key` the inspect cache's key for the subject. */
|
|
42
43
|
export function capabilityAdmission(request, { workspace, cli, agents = [], instances = [], catalogKey = null }, actions = ['inspect', 'run']) {
|
|
43
44
|
if (!workspace) fail('Select a known workspace', 'E_WORKSPACE_UNKNOWN');
|
|
@@ -78,6 +79,13 @@ export function capabilityAdmission(request, { workspace, cli, agents = [], inst
|
|
|
78
79
|
// the same way again: inspect of a soul only; routed only when the held row says the host lists them (hostComposesSkills).
|
|
79
80
|
if (request.composedSkills !== undefined && (action !== 'inspect' || typeof request.composedSkills !== 'boolean' || selector.soul === undefined)) fail('Invalid composed skills flag');
|
|
80
81
|
const composedSkills = request.composedSkills === true && (!server || hostComposesSkills(cli, workspace.group));
|
|
82
|
+
// board (feature instance-board): the agent's board with each fact's history and each question's context
|
|
83
|
+
// (`inspect --home --board`), inspect of a home only, read-only. Sent only to a CLI that advertises the feature;
|
|
84
|
+
// routed only when the held roster row says the host has it too (its own probe.features, relayed by a CLI with
|
|
85
|
+
// server-probe-features); otherwise it is dropped and the read is today's, which carries no history.
|
|
86
|
+
if (request.board !== undefined && (action !== 'inspect' || typeof request.board !== 'boolean' || selector.home === undefined)) fail('Invalid board flag');
|
|
87
|
+
const has = feature => !!cli?.ok && Array.isArray(cli.features) && cli.features.includes(feature);
|
|
88
|
+
const board = request.board === true && has(BOARD_FEATURE) && (!server || (has(PROBE_FEATURES_FEATURE) && hostAdvertises(workspace.group, BOARD_FEATURE)));
|
|
81
89
|
let soul, agentsRoot, home, key;
|
|
82
90
|
let context = workspace.scope;
|
|
83
91
|
if (selector.home !== undefined) {
|
|
@@ -101,15 +109,15 @@ export function capabilityAdmission(request, { workspace, cli, agents = [], inst
|
|
|
101
109
|
context = dirname(agentsRoot);
|
|
102
110
|
key = inspectKey({ deployment: workspace.scope, server, kind: 'soul', soul, agentsRoot, catalogKey, instructions, skills, composedSkills });
|
|
103
111
|
} else fail('Select a soul or an instance home (inspection has no scope subject)');
|
|
104
|
-
return { action, server, label, refresh, instructions, skills, composedSkills, soul, agentsRoot, home, context, key };
|
|
112
|
+
return { action, server, label, refresh, instructions, skills, composedSkills, board, soul, agentsRoot, home, context, key };
|
|
105
113
|
}
|
|
106
114
|
|
|
107
115
|
/** The CLI call's options for an admitted request (cli-adapter.mjs `cliCapability`). */
|
|
108
|
-
export function capabilityCall(request, { action, server, refresh, instructions, skills, composedSkills, soul, agentsRoot, home, context }, { workspace, cli, localCwd, maxAge }) {
|
|
116
|
+
export function capabilityCall(request, { action, server, refresh, instructions, skills, composedSkills, board, soul, agentsRoot, home, context }, { workspace, cli, localCwd, maxAge }) {
|
|
109
117
|
return {
|
|
110
118
|
action, context, server, soul, agentsRoot, home,
|
|
111
119
|
operation: request.operation, ...(request.args !== undefined ? { args: request.args } : {}), ...(instructions ? { instructions } : {}),
|
|
112
|
-
...(skills ? { skills } : {}), ...(composedSkills ? { composedSkills } : {}),
|
|
120
|
+
...(skills ? { skills } : {}), ...(composedSkills ? { composedSkills } : {}), ...(board ? { board } : {}),
|
|
113
121
|
localCwd: server ? localCwd : context || workspace.scope,
|
|
114
122
|
// --max-age travels only on a LOCAL inspect (reuse is local only: the kernel refuses it with --server)
|
|
115
123
|
// and only when the probe declared observe-max-age (the adapter's call).
|
|
@@ -140,10 +148,12 @@ export function createInspectBoundary({ invoke = cliCapability, cache = null, ma
|
|
|
140
148
|
async inspect(request, context) {
|
|
141
149
|
const { workspace, cli, localCwd } = context;
|
|
142
150
|
const admitted = capabilityAdmission(request, context, ['inspect']);
|
|
143
|
-
const { server, refresh, key } = admitted;
|
|
151
|
+
const { server, refresh, key, board } = admitted;
|
|
144
152
|
const call = () => invoke(cli.bin, capabilityCall(request, admitted, { workspace, cli, localCwd, maxAge }), io);
|
|
145
153
|
let envelope, observedAt, refreshing = false;
|
|
146
|
-
|
|
154
|
+
// A board read never goes through the cache, not even to join a flight in the air: the view reads the board when
|
|
155
|
+
// it changed, so a flight begun before that change answers for an earlier board (instance-board.mjs).
|
|
156
|
+
if (cache && !board) {
|
|
147
157
|
// A remote workspace has no state key and no invalidation signal here: its inspections are shared
|
|
148
158
|
// between concurrent requests but never served from an earlier visit (store: false).
|
|
149
159
|
// Live (observes the remotes afresh): a refresh, a routed inspect (reuse is local only, so it never carries
|
|
@@ -10,6 +10,8 @@
|
|
|
10
10
|
* { code: 'unsupported-session', sentence, origin? }
|
|
11
11
|
* { code: 'not-running', sentence } an `open` act's only (`openAct`)
|
|
12
12
|
* { code: 'state-unknown', sentence } an `open` act's only
|
|
13
|
+
* { code: 'no-terminal', sentence, link? } an `open` act's only: the row runs on a session provider
|
|
14
|
+
* link: { label, url }, what the provider offers instead
|
|
13
15
|
*
|
|
14
16
|
* A client may switch on `code`, and on `key` or `kind` when it needs to; never on the sentence.
|
|
15
17
|
* The sentences are the ones the shared tables already produce. Two of them can be text this home did
|
|
@@ -49,12 +51,28 @@
|
|
|
49
51
|
* running === true inspect, restart, stop, retire
|
|
50
52
|
* running === false inspect, start, stop, retire
|
|
51
53
|
* running unknown inspect, stop, retire
|
|
54
|
+
* A row on a session provider (instance-presentation.mjs `sessionProvider`: "bb", say) is offered by the
|
|
55
|
+
* same last three lines, from the `running` the kernel reports for it: the kernel starts, stops and retires
|
|
56
|
+
* it through its provider.
|
|
52
57
|
*
|
|
53
58
|
* openAct(instance) -> { verb: 'open', enabled, reason: Reason | null } | null
|
|
54
59
|
*
|
|
55
60
|
* Whether the row's terminal can be opened, and why not. It is not one of `acts`: it is read from
|
|
56
|
-
* `instanceActs`'s answer and from
|
|
61
|
+
* `instanceActs`'s answer, and of the row only from whether it runs on a session provider, so the order
|
|
62
|
+
* above is written once.
|
|
57
63
|
* blocked or limited is set null: the row's own reason says why, and a client adds no act
|
|
64
|
+
* a Herdr-recorded row not enabled, with Start's own reason (unsupported-session), as below
|
|
65
|
+
* a row on a session provider not enabled (no-terminal), whatever its state: it has no terminal.
|
|
66
|
+
* The sentence names where the agent runs ("Runs in a bb thread; open it
|
|
67
|
+
* in bb."), this home's own, built from the provider's name when the
|
|
68
|
+
* row's `backend` is one (`sessionProviderName`); a row whose `backend`
|
|
69
|
+
* is any other text says "Runs outside tmux; it has no terminal to
|
|
70
|
+
* open.", and none of that text. `link` is
|
|
71
|
+
* the row's `open` (`openLink`: `{ label, url }`, an http(s) url), there
|
|
72
|
+
* only for a row of this machine that carries one: another machine's url
|
|
73
|
+
* is its own loopback. A client may show `link` as an external link (the
|
|
74
|
+
* label through `displayLine`); none attaches, splits or opens a
|
|
75
|
+
* terminal for the row, and none restores a remembered tab for it.
|
|
58
76
|
* restart is listed, enabled enabled: the row runs
|
|
59
77
|
* start is listed, enabled not enabled (not-running)
|
|
60
78
|
* start is listed, not enabled not enabled, with that act's own reason (unsupported-session)
|
|
@@ -63,12 +81,12 @@
|
|
|
63
81
|
* client's, and is not here.
|
|
64
82
|
*/
|
|
65
83
|
import { heldHome } from './instance-tree.mjs';
|
|
66
|
-
import { unsupportedSession } from './instance-presentation.mjs';
|
|
84
|
+
import { unsupportedSession, sessionProvider, sessionProviderName, openLink } from './instance-presentation.mjs';
|
|
67
85
|
import { canAddressRemote, rowReason } from './remote-address.mjs';
|
|
68
86
|
|
|
69
87
|
const act = (verb, reason = null, secondary = false) => ({ verb, enabled: !reason, reason, ...(secondary ? { secondary: true } : {}) });
|
|
70
88
|
// An `open` act's own two codes, and the one sentence both carry.
|
|
71
|
-
const NOT_RUNNING = 'not-running', STATE_UNKNOWN = 'state-unknown';
|
|
89
|
+
const NOT_RUNNING = 'not-running', STATE_UNKNOWN = 'state-unknown', NO_TERMINAL = 'no-terminal';
|
|
72
90
|
const NO_LIVE_TERMINAL = 'No live terminal is reported.';
|
|
73
91
|
|
|
74
92
|
export function instanceActs(instance) {
|
|
@@ -97,6 +115,15 @@ export function instanceActs(instance) {
|
|
|
97
115
|
export function openAct(instance) {
|
|
98
116
|
const { blocked, limited, acts } = instanceActs(instance);
|
|
99
117
|
if (blocked || limited) return null;
|
|
118
|
+
// A session provider's row has no terminal in any state. After the held and unaddressable rows, whose own
|
|
119
|
+
// reason stands; a Herdr-recorded row is no provider's (`sessionProvider`) and keeps Start's reason below.
|
|
120
|
+
const provider = sessionProvider(instance);
|
|
121
|
+
if (provider) {
|
|
122
|
+
const link = instance.server ? null : openLink(instance);
|
|
123
|
+
// The sentence is this home's own, shown as written: only a provider's name is set in it, never other text of the row.
|
|
124
|
+
const sentence = sessionProviderName(provider) ? `Runs in a ${provider} thread; open it in ${provider}.` : 'Runs outside tmux; it has no terminal to open.';
|
|
125
|
+
return act('open', { code: NO_TERMINAL, sentence, ...(link ? { link } : {}) });
|
|
126
|
+
}
|
|
100
127
|
const restart = acts.find(({ verb }) => verb === 'restart'), start = acts.find(({ verb }) => verb === 'start');
|
|
101
128
|
if (restart?.enabled) return act('open');
|
|
102
129
|
if (start?.enabled) return act('open', { code: NOT_RUNNING, sentence: NO_LIVE_TERMINAL });
|
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
/** The agent's board (feature `instance-board`, `boardApi: 1`; docs/desktop-cli-api.md, "The agent's board"): the
|
|
2
|
+
* facts an agent keeps in a person's view and the questions it asks them, as the kernel reports them on an
|
|
3
|
+
* `oats status --json` row (`board`) and, with history and context, on `oats inspect --home <h> --board --json`.
|
|
4
|
+
* Agent-reported and display only (instance-activity-is-reported-not-inferred): nothing here reads a terminal.
|
|
5
|
+
*
|
|
6
|
+
* One shared design: both clients read the board through this module, so the facts a client shows, the order,
|
|
7
|
+
* the bounds and the answer it types are the same everywhere. Pure, no DOM, never throws. A contract module: the
|
|
8
|
+
* server imports it (deployment-data, remote-roster), so it imports contract modules only.
|
|
9
|
+
*
|
|
10
|
+
* Every text is validated against the kernel's own bounds, and a value out of the contract drops only itself:
|
|
11
|
+
* a malformed fact or question is left out, the rest of the board stays. The row's `board` is absent without the
|
|
12
|
+
* feature and `null` when the home has no board file; both read as "no board" (`boardData` → null), and a row
|
|
13
|
+
* whose kernel lacks the feature keeps today's terminal and waiting row (`rowHasBoard`). */
|
|
14
|
+
import { record } from './readiness-contract.mjs';
|
|
15
|
+
import { NOT_NOTE_TEXT, UNSAFE } from './display-text.mjs';
|
|
16
|
+
|
|
17
|
+
export const BOARD_FEATURE = 'instance-board';
|
|
18
|
+
export const BOARD_API = 1;
|
|
19
|
+
/** The kernel's bounds (contract v4): facts per board, open questions, options per question, history per fact. */
|
|
20
|
+
export const BOARD_LIMITS = Object.freeze({ facts: 12, questions: 9, optionsMin: 2, optionsMax: 4, history: 20,
|
|
21
|
+
label: 40, value: 80, unit: 16, option: 60, question: 200, context: 2000, link: 512 });
|
|
22
|
+
/** The facts shown before the fold. */
|
|
23
|
+
export const FACTS_SHOWN = 3;
|
|
24
|
+
/** The producer of the board's own needs-input claim (reason `attention`). */
|
|
25
|
+
export const BOARD_PRODUCER = 'oats.board';
|
|
26
|
+
/** The claim reasons that say a harness's own dialog is on the agent's screen (a screen an Enter answers). */
|
|
27
|
+
export const DIALOG_REASONS = Object.freeze(['permission', 'question']);
|
|
28
|
+
|
|
29
|
+
const KEY = /^[a-z0-9][a-z0-9-]{0,15}$/;
|
|
30
|
+
const points = v => [...v].length;
|
|
31
|
+
/** A one-line text of at most `max` code points: non-empty, not only spaces, none of the refused characters. */
|
|
32
|
+
const line = (v, max) => typeof v === 'string' && v.trim() !== '' && points(v) <= max && !NOT_NOTE_TEXT.test(v);
|
|
33
|
+
/** The kernel's time: an ISO-8601 instant that parses. */
|
|
34
|
+
const instant = v => typeof v === 'string' && v.length <= 40 && /^\d{4}-\d{2}-\d{2}T/.test(v) && Number.isFinite(Date.parse(v));
|
|
35
|
+
/** An absolute https: URL of at most 512 ASCII characters, with a host and no credentials. */
|
|
36
|
+
export function boardLink(v) {
|
|
37
|
+
if (typeof v !== 'string' || !v || v.length > BOARD_LIMITS.link || !/^[\x21-\x7e]+$/.test(v)) return null;
|
|
38
|
+
let url;
|
|
39
|
+
try { url = new URL(v); } catch { return null; }
|
|
40
|
+
if (url.protocol !== 'https:' || !url.hostname || url.username || url.password) return null;
|
|
41
|
+
return { href: v, host: url.hostname };
|
|
42
|
+
}
|
|
43
|
+
/** Whether a text the agent wrote may be shown as it is: valid, and not UNSAFE (a secret, a credentialed URL), which
|
|
44
|
+
* the display filter would withhold whole. */
|
|
45
|
+
const shown = v => !UNSAFE.test(v);
|
|
46
|
+
|
|
47
|
+
function fact(v) {
|
|
48
|
+
if (!record(v) || typeof v.key !== 'string' || !KEY.test(v.key) || !line(v.label, BOARD_LIMITS.label)
|
|
49
|
+
|| !line(v.value, BOARD_LIMITS.value) || !instant(v.at)) return null;
|
|
50
|
+
const unit = v.unit == null ? null : line(v.unit, BOARD_LIMITS.unit) ? v.unit : undefined;
|
|
51
|
+
const link = v.link == null ? null : boardLink(v.link) ?? undefined;
|
|
52
|
+
if (unit === undefined || link === undefined) return null;
|
|
53
|
+
// An address the display filter would withhold (a token in its query, a known secret's shape) is never shown, nor
|
|
54
|
+
// opened: the fact stays, with no link, like any fact the agent gave none.
|
|
55
|
+
return { key: v.key, label: v.label, value: v.value, unit, link: link && shown(link.href) ? link : null, at: v.at, withheld: !shown(v.label) || !shown(v.value) || (unit !== null && !shown(unit)) };
|
|
56
|
+
}
|
|
57
|
+
function question(v) {
|
|
58
|
+
if (!record(v) || typeof v.id !== 'string' || !KEY.test(v.id) || !line(v.question, BOARD_LIMITS.question) || !instant(v.since)
|
|
59
|
+
|| !Array.isArray(v.options) || v.options.length < BOARD_LIMITS.optionsMin || v.options.length > BOARD_LIMITS.optionsMax
|
|
60
|
+
|| !v.options.every(o => line(o, BOARD_LIMITS.option))) return null;
|
|
61
|
+
return { id: v.id, question: v.question, options: [...v.options], hasContext: v.hasContext === true, since: v.since,
|
|
62
|
+
// A text the display filter withholds is never shown, so it is never typed either (answerText).
|
|
63
|
+
withheld: !shown(v.question), optionsWithheld: v.options.map(o => !shown(o)) };
|
|
64
|
+
}
|
|
65
|
+
/** The first of each key (facts) or id (questions), in the kernel's order, up to `max`. */
|
|
66
|
+
function unique(list, make, by, max) {
|
|
67
|
+
const out = [], seen = new Set();
|
|
68
|
+
for (const item of list) {
|
|
69
|
+
if (out.length >= max) break;
|
|
70
|
+
const made = make(item);
|
|
71
|
+
if (made && !seen.has(made[by])) { seen.add(made[by]); out.push(made); }
|
|
72
|
+
}
|
|
73
|
+
return out;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/** A row's `board`, validated: `{ facts, questions, malformed, dropped }` (facts in the order first set, questions in
|
|
77
|
+
* the order asked), or null when the row has none (absent or `null`: the home has no board file). A value that is not
|
|
78
|
+
* a board is `malformed` (nothing shown from it), and `dropped` counts the entries left out as out of the contract, so
|
|
79
|
+
* the view can say the board was not read whole: neither ever reads as "no questions". Never throws. */
|
|
80
|
+
export function boardData(v) {
|
|
81
|
+
if (v === null || v === undefined) return null;
|
|
82
|
+
if (!record(v)) return { facts: [], questions: [], malformed: true, dropped: 0 };
|
|
83
|
+
const lists = Array.isArray(v.facts ?? []) && Array.isArray(v.questions ?? []);
|
|
84
|
+
const rawFacts = Array.isArray(v.facts) ? v.facts : [], rawQuestions = Array.isArray(v.questions) ? v.questions : [];
|
|
85
|
+
const facts = unique(rawFacts, fact, 'key', BOARD_LIMITS.facts), questions = unique(rawQuestions, question, 'id', BOARD_LIMITS.questions);
|
|
86
|
+
return { facts, questions, malformed: !lists,
|
|
87
|
+
dropped: Math.min(rawFacts.length, BOARD_LIMITS.facts) - facts.length + Math.min(rawQuestions.length, BOARD_LIMITS.questions) - questions.length };
|
|
88
|
+
}
|
|
89
|
+
/** Whether the agent view replaces the plain terminal for this row: its kernel reports the board (the CLI lists
|
|
90
|
+
* BOARD_FEATURE and the row carries the field, `null` included). A remote row carries `board` only when its host
|
|
91
|
+
* relays it. Without it the tab is today's terminal with its waiting row. */
|
|
92
|
+
export const rowHasBoard = (row, features) => record(row) && Object.hasOwn(row, 'board')
|
|
93
|
+
&& Array.isArray(features) && features.includes(BOARD_FEATURE);
|
|
94
|
+
|
|
95
|
+
/** `oats inspect --home <h> --board --json`'s board, validated, as one of five outcomes the view tells apart:
|
|
96
|
+
* - `{ state: 'ok', facts, questions }`: each fact's `history` (`[{ value, at }]`, oldest first, at most 20, each value
|
|
97
|
+
* within the contract's bounds) and each question's `context` (boardContext, or null) with its `since`;
|
|
98
|
+
* - `{ state: 'none' }`: the answer's board is `null` (the home has no board file);
|
|
99
|
+
* - `{ state: 'unsupported' }`: the answer has no board at all (an OATS, or a routed host, without the feature: the
|
|
100
|
+
* backend dropped the flag);
|
|
101
|
+
* - `{ state: 'malformed' }`: the answer is not an inspection, or its board is not one.
|
|
102
|
+
* The fifth, `failed` (the read refused or failed), is the caller's. The board is the answer's `board`, or its
|
|
103
|
+
* `instance.board`. Never throws. */
|
|
104
|
+
export function boardDetailData(v) {
|
|
105
|
+
if (!record(v)) return { state: 'malformed' };
|
|
106
|
+
const has = Object.hasOwn(v, 'board') ? 'board' : record(v.instance) && Object.hasOwn(v.instance, 'board') ? 'instance' : null;
|
|
107
|
+
if (!has) return { state: 'unsupported' };
|
|
108
|
+
const board = has === 'board' ? v.board : v.instance.board;
|
|
109
|
+
if (board === null) return { state: 'none' };
|
|
110
|
+
if (!record(board) || !Array.isArray(board.facts ?? []) || !Array.isArray(board.questions ?? [])) return { state: 'malformed' };
|
|
111
|
+
const facts = new Map(), questions = new Map();
|
|
112
|
+
for (const f of Array.isArray(board.facts) ? board.facts : []) {
|
|
113
|
+
if (!record(f) || typeof f.key !== 'string' || !KEY.test(f.key) || facts.has(f.key)) continue;
|
|
114
|
+
const history = (Array.isArray(f.history) ? f.history : [])
|
|
115
|
+
.filter(h => record(h) && line(h.value, BOARD_LIMITS.value) && instant(h.at))
|
|
116
|
+
.slice(-BOARD_LIMITS.history).map(h => ({ value: h.value, at: h.at }));
|
|
117
|
+
facts.set(f.key, { history });
|
|
118
|
+
if (facts.size >= BOARD_LIMITS.facts) break;
|
|
119
|
+
}
|
|
120
|
+
for (const q of Array.isArray(board.questions) ? board.questions : []) {
|
|
121
|
+
if (!record(q) || typeof q.id !== 'string' || !KEY.test(q.id) || questions.has(q.id)) continue;
|
|
122
|
+
// Its `since` too: the view shows a context only under the occurrence it was read for.
|
|
123
|
+
questions.set(q.id, { context: boardContext(q.context), since: instant(q.since) ? q.since : null });
|
|
124
|
+
if (questions.size >= BOARD_LIMITS.questions) break;
|
|
125
|
+
}
|
|
126
|
+
return { state: 'ok', facts, questions };
|
|
127
|
+
}
|
|
128
|
+
/** A question's context: lines of text (LF only), at most 2000 code points, none of the refused characters but the
|
|
129
|
+
* line feed, not UNSAFE; null otherwise. Kept as the agent wrote it, line breaks included: shown as a quote. */
|
|
130
|
+
export function boardContext(v) {
|
|
131
|
+
if (typeof v !== 'string' || !v.trim() || points(v) > BOARD_LIMITS.context) return null;
|
|
132
|
+
if (v.split('\n').some(l => NOT_NOTE_TEXT.test(l)) || UNSAFE.test(v)) return null;
|
|
133
|
+
return v;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
/** A sparkline's points from a fact's history: the numeric values (the first number in each value, so "0.4312"
|
|
137
|
+
* and "41 %" both read), oldest first. Null under two numbers: a line needs two points. */
|
|
138
|
+
export function sparkValues(history) {
|
|
139
|
+
if (!Array.isArray(history)) return null;
|
|
140
|
+
const values = [];
|
|
141
|
+
for (const h of history) {
|
|
142
|
+
const m = typeof h?.value === 'string' ? h.value.match(/-?\d+(?:[.,]\d+)?/) : null;
|
|
143
|
+
if (m) values.push(Number(m[0].replace(',', '.')));
|
|
144
|
+
}
|
|
145
|
+
return values.length >= 2 && values.every(Number.isFinite) ? values : null;
|
|
146
|
+
}
|
|
147
|
+
|
|
148
|
+
/** The facts the strip shows, in the kernel's order: `shown` (at most FACTS_SHOWN, unless `unfolded`), `folded`
|
|
149
|
+
* (the rest of the visible ones) and `hidden` (those the person hid on this computer). `hiddenKeys`: a Map from a
|
|
150
|
+
* fact's key to the value it was hidden at; a fact whose value has changed since shows again (the agent said
|
|
151
|
+
* something new). `limit`: fewer shown where the pane is short (the agent view's budget). */
|
|
152
|
+
export function factsView(facts, hiddenKeys = new Map(), { unfolded = false, limit = FACTS_SHOWN } = {}) {
|
|
153
|
+
const visible = [], hidden = [];
|
|
154
|
+
for (const f of facts) (hiddenKeys.has(f.key) && hiddenKeys.get(f.key) === f.value ? hidden : visible).push(f);
|
|
155
|
+
const cut = unfolded ? visible.length : limit;
|
|
156
|
+
return { shown: visible.slice(0, cut), folded: visible.slice(cut), hidden };
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
/** Whether a live claim says the agent's terminal shows a harness dialog: any positive claim, from any producer, whose
|
|
160
|
+
* reason is `permission` or `question` (waiting-claims-may-only-withhold-automated-input). `claims`: the row's
|
|
161
|
+
* `waitingOnYou` and, read while the view is open, the events read's `waitingClaims`. Unknown is not a dialog:
|
|
162
|
+
* the card never sends on its own, so the person's Enter, with the terminal in view, stays the consent. */
|
|
163
|
+
export function dialogOpen(claims) {
|
|
164
|
+
return (Array.isArray(claims) ? claims : [claims]).some(c => record(c) && c.waiting !== false
|
|
165
|
+
&& typeof c.reason === 'string' && DIALOG_REASONS.includes(c.reason));
|
|
166
|
+
}
|
|
167
|
+
/** Whether a claim is the board's own (its questions show in the question zone, not in the waiting row). */
|
|
168
|
+
export const boardClaim = claim => record(claim) && claim.producer === BOARD_PRODUCER;
|
|
169
|
+
|
|
170
|
+
/** What pressing option `index` (0-based) of `q` types on the agent's input line: `<id>: <option>`, one line, never
|
|
171
|
+
* a bare digit and never a line end, so nothing is sent until the person presses Enter. Null when there is nothing
|
|
172
|
+
* the person can see to type: no such option, or an option the display filter withholds. */
|
|
173
|
+
export function answerText(q, index) {
|
|
174
|
+
if (!record(q) || typeof q.id !== 'string' || !KEY.test(q.id) || !Array.isArray(q.options)) return null;
|
|
175
|
+
const option = q.options[index];
|
|
176
|
+
if (!line(option, BOARD_LIMITS.option) || q.optionsWithheld?.[index] === true || !shown(option)) return null;
|
|
177
|
+
return `${q.id}: ${option}`;
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
/** "question 2 of 3", or null for a single question. */
|
|
181
|
+
export const questionCount = (index, total) => total > 1 ? `question ${index + 1} of ${total}` : null;
|
|
182
|
+
/** The index after turning by `step` (±1) among `total` questions, wrapping at the ends. */
|
|
183
|
+
export const turnQuestion = (index, step, total) => total > 0 ? ((index + step) % total + total) % total : 0;
|
|
184
|
+
|
|
185
|
+
/** A fact's change, as the strip says it: "updated just now", "updated 4 min ago", "updated 3 h ago",
|
|
186
|
+
* "updated 2 d ago", then the date. A future time (clock skew) reads "just now". */
|
|
187
|
+
export function updatedText(at, now = Date.now()) {
|
|
188
|
+
const ms = now - Date.parse(at);
|
|
189
|
+
if (!Number.isFinite(ms)) return '';
|
|
190
|
+
const s = Math.max(0, Math.floor(ms / 1000));
|
|
191
|
+
if (s < 60) return 'updated just now';
|
|
192
|
+
const m = Math.floor(s / 60); if (m < 60) return `updated ${m} min ago`;
|
|
193
|
+
const h = Math.floor(m / 60); if (h < 24) return `updated ${h} h ago`;
|
|
194
|
+
const d = Math.floor(h / 24); if (d < 30) return `updated ${d} d ago`;
|
|
195
|
+
return `updated ${new Date(Date.parse(at)).toISOString().slice(0, 10)}`;
|
|
196
|
+
}
|
|
197
|
+
/** When the view reads the detail again (the maintainer's condition, 2026-11-19): a fact's `at` changed (or a fact
|
|
198
|
+
* came or went), or a question with context was asked (an occurrence: questionOccurrence). Never on an unchanged poll. */
|
|
199
|
+
export const detailSignature = board => board ? JSON.stringify([board.facts.map(f => [f.key, f.at]),
|
|
200
|
+
board.questions.filter(q => q.hasContext).map(questionOccurrence)]) : 'none';
|
|
201
|
+
/** A question's occurrence: its id and when it was asked. An id the agent clears and asks again (a new `since`) is
|
|
202
|
+
* another question, with its own answer and its own context, even when no poll saw it cleared in between. */
|
|
203
|
+
export const questionOccurrence = q => `${q.id}@${q.since}`;
|
|
204
|
+
/** A board's identity for repaints: changes when a fact's value or time, or the set of questions, changes. */
|
|
205
|
+
export const boardSignature = board => board ? JSON.stringify([board.facts.map(f => [f.key, f.value, f.unit, f.link?.href ?? null, f.at, f.label]),
|
|
206
|
+
board.questions.map(q => [q.id, q.question, q.options, q.hasContext, q.since])]) : 'none';
|
|
@@ -54,6 +54,61 @@ export function unsupportedSession(instance) {
|
|
|
54
54
|
return (instance?.sessionTarget !== undefined && instance?.sessionTarget !== null) || instance?.backend === "herdr" ? stem : null;
|
|
55
55
|
}
|
|
56
56
|
|
|
57
|
+
/** A session provider's name, by the session-provider contract: 1 to 40 lowercase letters, digits and dashes.
|
|
58
|
+
* Here it also starts with a letter or a digit: a name is a `--backend` value, and one that starts with a dash
|
|
59
|
+
* is an option to the CLI's parser. `tmux` is the kernel's own backend and `session-provider` the contract's
|
|
60
|
+
* word for any provider: both are reserved, never a provider's name. This is the rule for a name a client
|
|
61
|
+
* sends (`--backend`, cli-adapter.mjs), offers (session-backends.mjs) or sets in a sentence of its own
|
|
62
|
+
* (instance-acts.mjs); which row runs on a provider is `sessionProvider`'s, wider on purpose. Not on the
|
|
63
|
+
* stable surface. */
|
|
64
|
+
const PROVIDER_NAME = /^[a-z0-9][a-z0-9-]{0,39}$/;
|
|
65
|
+
export const sessionProviderName = (value) => typeof value === "string" && value !== "tmux" && value !== "session-provider" && PROVIDER_NAME.test(value);
|
|
66
|
+
|
|
67
|
+
/** The session provider a row runs on, as the row's `backend` says it, or null for a row that runs in tmux. A provider (a
|
|
68
|
+
* capability's session backend, "bb" say) has no tmux target and no terminal: a client takes such a row's
|
|
69
|
+
* `running`, `runtimeState` and `runtimeError` from the kernel as given, never probes tmux for it
|
|
70
|
+
* (liveness.mjs) and opens, splits or restores no terminal for it (instance-acts.mjs `openAct`).
|
|
71
|
+
*
|
|
72
|
+
* It is the row's `backend` whenever that is text that is not empty and not "tmux": any such row is not tmux's, so none is ever
|
|
73
|
+
* asked of tmux, also one whose value is no name the contract allows (`sessionProviderName`): what is answered
|
|
74
|
+
* is then the row's own text, for display only through `displayLine`, and never set in a sentence or sent as
|
|
75
|
+
* an argument. A row with no `backend` (an older kernel's, or an older routed host's) is a tmux row, as one
|
|
76
|
+
* with "tmux" is, and reads as it always did; so does one whose `backend` is not text, or is empty: an empty
|
|
77
|
+
* `backend` names no backend, the kernel never sends one, and reading it as a provider's would take a tmux
|
|
78
|
+
* home's terminal away. A Herdr-recorded row
|
|
79
|
+
* (`unsupportedSession`, `backend: "herdr"` included) is never one: its own reason comes first, everywhere.
|
|
80
|
+
* Not on the stable surface: a client reads `openAct`'s answer. */
|
|
81
|
+
export function sessionProvider(instance) {
|
|
82
|
+
if (unsupportedSession(instance)) return null;
|
|
83
|
+
const backend = instance?.backend;
|
|
84
|
+
return typeof backend === "string" && backend !== "" && backend !== "tmux" ? backend : null;
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** What a provider offers in place of a terminal: the row's `open`, `{ label, url }`, or null. Kept only
|
|
88
|
+
* when both are text and the url is an http or https one with no credentials in it: a client opens nothing
|
|
89
|
+
* else in a browser. The label is the provider's own text: a client shows it through display-text.mjs
|
|
90
|
+
* `displayLine`. Not on the stable surface. */
|
|
91
|
+
// Together under display-text.mjs MAX_DISPLAY_LINE, so a client can show the label and the url as one line, whole.
|
|
92
|
+
const MAX_LINK_LABEL = 200, MAX_LINK_URL = 1800;
|
|
93
|
+
export function openLink(instance) {
|
|
94
|
+
const open = instance?.open;
|
|
95
|
+
if (open === null || typeof open !== "object" || Array.isArray(open)) return null;
|
|
96
|
+
const { label, url } = open;
|
|
97
|
+
if (typeof label !== "string" || !label || label.length > MAX_LINK_LABEL || typeof url !== "string" || !url || url.length > MAX_LINK_URL) return null;
|
|
98
|
+
let parsed;
|
|
99
|
+
try { parsed = new URL(url); } catch { return null; }
|
|
100
|
+
if (!["http:", "https:"].includes(parsed.protocol) || parsed.username || parsed.password) return null;
|
|
101
|
+
return { label, url };
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** The id of the provider's thread a row runs in: `session.threadId` when it is text, else null. Only a
|
|
105
|
+
* status row of this machine carries it: a row relayed from another host never does, and nothing here may
|
|
106
|
+
* depend on it. For display only, through `displayLine`: it addresses nothing. Not on the stable surface. */
|
|
107
|
+
export function sessionThreadId(instance) {
|
|
108
|
+
const id = instance?.session?.threadId;
|
|
109
|
+
return typeof id === "string" && id && id.length <= 200 ? id : null;
|
|
110
|
+
}
|
|
111
|
+
|
|
57
112
|
/** Who wrote what `unsupportedSession` answers for a row as the kernel or a host reported it: "kernel"
|
|
58
113
|
* for the row's own text, null for the stand-in written here (and for a row it answers null for). Asked
|
|
59
114
|
* where the text is chosen (liveness.mjs, remote-roster.mjs), of the reported row: a panel's row already
|