@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.
Files changed (88) hide show
  1. package/bin/oats.mjs +112 -20
  2. package/docs/capabilities.md +697 -11
  3. package/docs/capability-manifest.schema.json +66 -0
  4. package/docs/configuration.md +27 -7
  5. package/docs/design/2026-11-19-sandboxes.md +595 -121
  6. package/docs/design/2026-11-20-provider-home-lifecycle.md +322 -0
  7. package/docs/design/README.md +7 -3
  8. package/docs/desktop-cli-api.md +330 -9
  9. package/docs/desktop.md +181 -48
  10. package/docs/execution-targets.md +210 -4
  11. package/docs/first-team.md +11 -0
  12. package/docs/implementation.md +24 -3
  13. package/docs/integrations.md +2 -2
  14. package/docs/knowledge-capability-authoring.md +1 -1
  15. package/docs/knowledge-reference/proposal.md +10 -0
  16. package/docs/knowledge.md +20 -11
  17. package/docs/official-catalog.md +2 -2
  18. package/docs/packages.md +7 -7
  19. package/docs/release-notes/v0.69.24.md +264 -0
  20. package/docs/release-notes/v0.70.0.md +155 -0
  21. package/docs/souls-and-instances.md +57 -0
  22. package/docs/trust-model.md +8 -1
  23. package/docs/tui.md +21 -1
  24. package/docs/upgrading.md +19 -5
  25. package/docs/workspaces.md +13 -5
  26. package/lib/automation-scope.mjs +1 -1
  27. package/lib/capability-show.mjs +20 -1
  28. package/lib/command-flags.mjs +2 -2
  29. package/lib/compile-cache.mjs +1 -1
  30. package/lib/core.mjs +1455 -203
  31. package/lib/errors.mjs +4 -1
  32. package/lib/home-integrity.mjs +329 -0
  33. package/lib/hook-env.mjs +107 -0
  34. package/lib/host-run.mjs +11 -3
  35. package/lib/instance-events.mjs +32 -5
  36. package/lib/instance-git.mjs +9 -0
  37. package/lib/instance-inspect.mjs +107 -9
  38. package/lib/instance-lifecycle.mjs +15 -3
  39. package/lib/instance-listing.mjs +101 -8
  40. package/lib/instance-resolution.mjs +85 -2
  41. package/lib/instance-upgrade.mjs +170 -14
  42. package/lib/kernel-features.mjs +10 -1
  43. package/lib/node-version.mjs +9 -0
  44. package/lib/provider-call-child.mjs +60 -0
  45. package/lib/provider-resume.mjs +83 -0
  46. package/lib/provider-test-seams.mjs +20 -0
  47. package/lib/read-call.mjs +2 -0
  48. package/lib/remote.mjs +33 -1
  49. package/lib/reserved-launch-env.mjs +8 -1
  50. package/lib/retire-admission.mjs +12 -1
  51. package/lib/sandbox-allowances.mjs +329 -0
  52. package/lib/schedule.mjs +14 -4
  53. package/lib/servers.mjs +38 -5
  54. package/lib/session-inspect.mjs +123 -87
  55. package/lib/session-providers.mjs +575 -0
  56. package/lib/session-receipt.mjs +93 -0
  57. package/lib/session-resume.mjs +68 -15
  58. package/lib/stable-node.mjs +3 -0
  59. package/lib/triggers.mjs +3 -1
  60. package/lib/upgrade-state.mjs +6 -1
  61. package/lib/worktree-hooks.mjs +18 -2
  62. package/lib/worktree.mjs +21 -7
  63. package/package-catalog.json +2 -2
  64. package/package.json +2 -1
  65. package/packages/client/capability-list.mjs +21 -0
  66. package/packages/client/cli-adapter.mjs +19 -4
  67. package/packages/client/cli-locator.mjs +5 -1
  68. package/packages/client/deployment-data.mjs +23 -1
  69. package/packages/client/deployment-panel.mjs +25 -3
  70. package/packages/client/home-board.mjs +33 -19
  71. package/packages/client/inspect-boundary.mjs +18 -8
  72. package/packages/client/instance-acts.mjs +30 -3
  73. package/packages/client/instance-board.mjs +206 -0
  74. package/packages/client/instance-presentation.mjs +55 -0
  75. package/packages/client/liveness.mjs +15 -4
  76. package/packages/client/own-codes.mjs +5 -1
  77. package/packages/client/remote-roster.mjs +6 -1
  78. package/packages/client/session-backends.mjs +31 -0
  79. package/packages/client/session-start.mjs +18 -6
  80. package/packages/client/spawn-apply-cli.mjs +5 -3
  81. package/packages/client/spawn-apply-contract.mjs +25 -2
  82. package/packages/client/spawn-apply.mjs +5 -1
  83. package/packages/client/spawn-messages.mjs +3 -0
  84. package/packages/client/terminal-contract.mjs +4 -0
  85. package/packages/client/waiting-on-you.mjs +12 -2
  86. package/packages/tui/lib/model.mjs +14 -3
  87. package/packages/tui/lib/store.mjs +12 -3
  88. 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, slice 2): the groupings both clients draw, so the
2
- * TUI can render the same Home later. Pure, no DOM, never throws. Rows are `oats status --json` instance rows as
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. running: every other live row (`running === true`, no reported state but `running`, a
10
- * reached server), newest spawn first (instance-tree.mjs `rosterOrder`). There is no working/idle
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". Stopped and unknown rows
13
- * aren't on the board (D11). The "New" group (stopped or finished since you last looked) has no
14
- * fact to read, so it isn't here.
15
- * homeAgents(rows) -> rows: every agent, running or stopped, in the roster's order (newest spawn first).
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
- const live = (row) => row.running === true && row.serverUnreached !== true && (row.runtimeState == null || row.runtimeState === 'running');
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
- running.sort(rosterOrder);
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
- return rowsOf(rows).sort(rosterOrder);
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
- if (cache) {
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 nothing else of the row, so the order above is written once.
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