@awebai/oats 0.69.23 → 0.69.24
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 +56 -17
- package/docs/capabilities.md +353 -5
- package/docs/capability-manifest.schema.json +36 -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 +320 -0
- package/docs/design/README.md +7 -3
- package/docs/desktop-cli-api.md +257 -9
- package/docs/desktop.md +181 -48
- package/docs/execution-targets.md +186 -3
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +5 -1
- 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/souls-and-instances.md +45 -0
- package/docs/tui.md +21 -1
- package/docs/upgrading.md +12 -5
- package/docs/workspaces.md +13 -5
- package/lib/capability-show.mjs +11 -1
- package/lib/command-flags.mjs +2 -2
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1176 -181
- package/lib/errors.mjs +4 -1
- package/lib/hook-env.mjs +106 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-inspect.mjs +44 -0
- package/lib/instance-lifecycle.mjs +15 -3
- package/lib/instance-listing.mjs +97 -8
- 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/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +5 -1
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +28 -4
- package/lib/session-inspect.mjs +104 -13
- package/lib/session-providers.mjs +528 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- 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
|
@@ -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
|
|
@@ -4,14 +4,19 @@
|
|
|
4
4
|
* of the serving process is liveness-main.mjs (see packages/desktop/server/oats-web.mjs), so a slow
|
|
5
5
|
* terminal server cannot stall request handling. */
|
|
6
6
|
import { createTmuxStatusReader, DEFAULT_TMUX_SESSION } from './tmux-status.mjs';
|
|
7
|
-
import { unsupportedSession, unsupportedSessionOrigin } from './instance-presentation.mjs';
|
|
7
|
+
import { unsupportedSession, unsupportedSessionOrigin, sessionProvider } from './instance-presentation.mjs';
|
|
8
8
|
|
|
9
9
|
export { DEFAULT_TMUX_SESSION };
|
|
10
10
|
const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
11
11
|
|
|
12
|
-
/** rows: [{ instance, running?, tmux?, sessionTarget?, runtimeState?, runtimeError? }] in, one liveness
|
|
12
|
+
/** rows: [{ instance, running?, tmux?, sessionTarget?, backend?, runtimeState?, runtimeError? }] in, one liveness
|
|
13
13
|
* per row out. A Herdr-recorded row is never probed: it is unsupported, with the kernel's reason.
|
|
14
14
|
*
|
|
15
|
+
* A row on a session provider (instance-presentation.mjs `sessionProvider`: its `backend` is a provider's
|
|
16
|
+
* name, "bb" say) is never probed either: it has no tmux target, so the reader would call it stopped. Its
|
|
17
|
+
* `running`, `runtimeState` and `runtimeError` stay the kernel's, as for a `running: null` row, and the
|
|
18
|
+
* answer carries no `tmux`. A row with no `backend`, or with "tmux", is read as before.
|
|
19
|
+
*
|
|
15
20
|
* The probe refines a row only when the kernel answered `running` true or false. A row it answered
|
|
16
21
|
* `running: null` is not probed: its `running`, `runtimeState` and `runtimeError` stay the kernel's,
|
|
17
22
|
* and the answer carries no `tmux`, so the merged row keeps the kernel's own. The kernel answers
|
|
@@ -27,6 +32,11 @@ export function observeLiveness(rows, { tmuxReader = createTmuxStatusReader(), s
|
|
|
27
32
|
const unsupported = unsupportedSession(row);
|
|
28
33
|
if (unsupported) return { running: null, runtimeState: 'unsupported', runtimeError: unsupported.slice(0, 300), tmux: null };
|
|
29
34
|
// After the unsupported check: an older kernel's Herdr row is `unreachable` with a sessionTarget, and reads unsupported.
|
|
35
|
+
if (sessionProvider(row)) {
|
|
36
|
+
const running = typeof row.running === 'boolean' ? row.running : null;
|
|
37
|
+
return { running, ...(row.runtimeState !== undefined || running === null ? { runtimeState: row.runtimeState ?? 'unreachable' } : {}),
|
|
38
|
+
...(row.runtimeError ? { runtimeError: String(row.runtimeError).slice(0, 300) } : {}) };
|
|
39
|
+
}
|
|
30
40
|
if (row.running === null) return { running: null, runtimeState: row.runtimeState ?? 'unreachable', ...(row.runtimeError ? { runtimeError: String(row.runtimeError).slice(0, 300) } : {}) };
|
|
31
41
|
const tmux = record(row.tmux) ? row.tmux : undefined;
|
|
32
42
|
const { tmux: observed, running, runtimeState, runtimeError } = tmuxReader({ instance: row.instance, tmux }, session);
|
|
@@ -37,12 +47,13 @@ export function observeLiveness(rows, { tmuxReader = createTmuxStatusReader(), s
|
|
|
37
47
|
/** Who makes the `runtimeError` of a row's answer, when the answer has one: "kernel", "terminal-probe",
|
|
38
48
|
* or null for the stand-in of an older kernel's Herdr row. By the order `observeLiveness` takes, which is
|
|
39
49
|
* a function of the row alone: an invalid row and a probed one are the terminal check's, a Herdr row's
|
|
40
|
-
* text is the kernel's or the stand-in, and a row
|
|
50
|
+
* text is the kernel's or the stand-in, and a row on a session provider and one the kernel answered
|
|
51
|
+
* `running: null` keep the kernel's.
|
|
41
52
|
* The collector's answer crosses a process as JSON, so the speaker is not put on that wire: the reader of
|
|
42
53
|
* the answers asks here, of the row it sent (deployment-panel.mjs `livenessAnswers`). Not on the stable surface. */
|
|
43
54
|
export function livenessOrigin(row) {
|
|
44
55
|
if (!record(row) || typeof row.instance !== 'string') return 'terminal-probe';
|
|
45
56
|
if (unsupportedSession(row)) return unsupportedSessionOrigin(row);
|
|
46
|
-
if (row.running === null) return 'kernel';
|
|
57
|
+
if (sessionProvider(row) || row.running === null) return 'kernel';
|
|
47
58
|
return 'terminal-probe';
|
|
48
59
|
}
|
|
@@ -22,6 +22,9 @@ export const CLIENT_OWN_CODES = Object.freeze([
|
|
|
22
22
|
'E_APPLY_UNAVAILABLE', 'E_BACKEND_UNAVAILABLE', 'E_BUSY', 'E_FORBIDDEN_FRAME', 'E_INPUT_PREPARATION', 'E_INSTANCE_GONE',
|
|
23
23
|
'E_INTENT_EXPIRED', 'E_OUTCOME_UNKNOWN', 'E_PREFLIGHT_INCOMPLETE', 'E_PREVIEW_UNAVAILABLE', 'E_SUPERSEDED', 'E_TARGET_CHANGED',
|
|
24
24
|
'E_UNSUPPORTED_OPTION', 'E_WAKE_OUTCOME_UNKNOWN', 'E_WAKE_SAVE_FAILED',
|
|
25
|
+
// The kernel's code for a confirmed spawn into a sandbox (feature sandboxes, D-S1-4), listed only until
|
|
26
|
+
// this tree's kernel writes it: the sandboxes kernel change (S1) writes it and removes it from here.
|
|
27
|
+
'E_SANDBOX_PLACEMENT',
|
|
25
28
|
// Stop, start, restart and remove, and the plan a person confirms (a spawn's plan too).
|
|
26
29
|
'E_LIFECYCLE_UNAVAILABLE', 'E_OPTION_UNAVAILABLE', 'E_PLAN_CHANGED', 'E_PLAN_EXPIRED', 'E_PLAN_LIMIT', 'E_PLAN_REQUIRED',
|
|
27
30
|
'E_HOME_UNVERIFIED', 'E_START_UNCONFIRMED',
|
|
@@ -35,7 +38,8 @@ export const CLIENT_OWN_CODES = Object.freeze([
|
|
|
35
38
|
// A terminal.
|
|
36
39
|
'E_TERM_ATTACHMENT_FAILED', 'E_TERM_ATTACHMENT_INTERRUPTED', 'E_TERM_BAD_ARGS', 'E_TERM_BUSY', 'E_TERM_CAP',
|
|
37
40
|
'E_TERM_CLOSE_PENDING', 'E_TERM_CLOSING', 'E_TERM_CONTEXT_CHANGED', 'E_TERM_FORBIDDEN_FRAME', 'E_TERM_INPUT_LIMIT',
|
|
38
|
-
'
|
|
41
|
+
// The agent view's answer refused for the pane's mode (terminal-owner answer): in tmux's copy mode, or not readable.
|
|
42
|
+
'E_TERM_IN_MODE', 'E_TERM_LEASE', 'E_TERM_MODE_UNKNOWN', 'E_TERM_NOT_READY', 'E_TERM_OPEN_FAILED', 'E_TERM_OUTPUT_LIMIT', 'E_TERM_PREPARE_TIMEOUT',
|
|
39
43
|
'E_TERM_READY_TIMEOUT', 'E_TERM_REMOTE_GONE', 'E_TERM_REMOTE_NO_ANSWER', 'E_TERM_REMOTE_NO_SSH',
|
|
40
44
|
'E_TERM_REMOTE_UNREACHABLE', 'E_TERM_REUSED', 'E_TERM_TRANSPORT',
|
|
41
45
|
].sort());
|
|
@@ -8,6 +8,7 @@ import { readIdentity } from "./workspace-views.mjs";
|
|
|
8
8
|
import { sameRepo } from "./repo-moves.mjs";
|
|
9
9
|
import { hostAdvertises } from "./composed-gate.mjs";
|
|
10
10
|
import { PIN_FEATURE } from "./instance-tree.mjs";
|
|
11
|
+
import { BOARD_FEATURE, boardData } from "./instance-board.mjs";
|
|
11
12
|
/** Projection of the installed CLI's remote roster. Never reads remote paths locally. */
|
|
12
13
|
export function remoteWorkspace(group) {
|
|
13
14
|
return {
|
|
@@ -49,7 +50,7 @@ export function remotePanel(group, at) {
|
|
|
49
50
|
const described = name => { const soul = (group.souls || []).find((a) => a?.name === name); return typeof soul?.description === "string" ? soul.description : null; };
|
|
50
51
|
// A Herdr-recorded row is unsupported whatever the host's probe said: it cannot open or start.
|
|
51
52
|
const instances = (group.instances || []).map(({ runtime: _released, runtimeErrorOrigin: _sent, retire: sentRetire, sameWork: sentSameWork,
|
|
52
|
-
relatedWork: sentRelatedWork, relatedWorkKnown: _gate, pinned: sentPinned, ...i }) => {
|
|
53
|
+
relatedWork: sentRelatedWork, relatedWorkKnown: _gate, pinned: sentPinned, board: sentBoard, ...i }) => {
|
|
53
54
|
const unsupported = unsupportedSession(i);
|
|
54
55
|
const origin = unsupported ? unsupportedSessionOrigin(i) : group.probe.ok || (group.probe.error?.message && madeByKernel(group.probe.error)) ? "kernel" : "roster-read";
|
|
55
56
|
const row = {
|
|
@@ -78,6 +79,10 @@ export function remotePanel(group, at) {
|
|
|
78
79
|
// probe.features, which a CLI with server-probe-features relays). The kernel relays a row's pinned whatever
|
|
79
80
|
// its host lists, so a stray field from an older host, or an unknown list, never pins a row here.
|
|
80
81
|
...(sentPinned === true && hostAdvertises(group, PIN_FEATURE) ? { pinned: true } : {}),
|
|
82
|
+
// Feature instance-board: the agent's facts and questions (instance-board.mjs), validated again here, and only
|
|
83
|
+
// from a host whose own feature list names it, as the pin is; anything else leaves the row with no board field,
|
|
84
|
+
// so its tab is today's terminal. `null`: the host has the feature and the home has no board.
|
|
85
|
+
...(sentBoard !== undefined && hostAdvertises(group, BOARD_FEATURE) ? { board: boardData(sentBoard) } : {}),
|
|
81
86
|
...(unsupported ? { running: null, runtimeState: "unsupported", runtimeError: unsupported } : {}),
|
|
82
87
|
};
|
|
83
88
|
return hasRuntimeError(row) && origin ? { ...row, runtimeErrorOrigin: origin } : row;
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
/** The session backends a spawn or a schedule may name, as the kernel lists them. Two lists, one meaning each:
|
|
2
|
+
*
|
|
3
|
+
* `sessionBackends` of `oats version --json` the kernel's own: `["tmux"]` (an older kernel may still say
|
|
4
|
+
* "herdr", which OATS removed: never offered, never sent)
|
|
5
|
+
* `sessionProviders` of `oats inspect --json` the session providers a home or a soul can use, each supplied
|
|
6
|
+
* by one of its capabilities (feature session-providers)
|
|
7
|
+
*
|
|
8
|
+
* A client offers and accepts these names and no other: a `--backend` value (cli-adapter.mjs `spawnArgv`) and a
|
|
9
|
+
* schedule's `backend` it reads back into a form are held to them. Pure: no I/O, never throws. */
|
|
10
|
+
import { sessionProviderName } from './instance-presentation.mjs';
|
|
11
|
+
|
|
12
|
+
const record = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
|
|
13
|
+
|
|
14
|
+
/** The provider names an inspection lists, in its order, each once: the `name` of each row of its top-level
|
|
15
|
+
* `sessionProviders` (`[{ name, capability }]`). Only a name the contract allows (instance-presentation.mjs
|
|
16
|
+
* `sessionProviderName`) and never "herdr", which OATS removed; anything else, and an inspection without the
|
|
17
|
+
* list, lists none. */
|
|
18
|
+
export function sessionProviderNames(inspection) {
|
|
19
|
+
const listed = record(inspection) && Array.isArray(inspection.sessionProviders) ? inspection.sessionProviders : [];
|
|
20
|
+
return [...new Set(listed.map((row) => (record(row) ? row.name : undefined)).filter((name) => sessionProviderName(name) && name !== 'herdr'))];
|
|
21
|
+
}
|
|
22
|
+
|
|
23
|
+
/** A list of backend names as a client may offer or send them: its strings, never empty, never "herdr". */
|
|
24
|
+
export const listedBackends = (names) => (Array.isArray(names) ? names.filter((name) => typeof name === 'string' && name && name !== 'herdr') : []);
|
|
25
|
+
|
|
26
|
+
/** Every backend name the kernel lists: its own (`cli.sessionBackends`; "tmux" alone for a probe record without the
|
|
27
|
+
* list, as before the probe reported it) and then the providers of `inspection`, when one is given. */
|
|
28
|
+
export function sessionBackendNames(cli, inspection = null) {
|
|
29
|
+
const own = Array.isArray(cli?.sessionBackends) ? listedBackends(cli.sessionBackends) : ['tmux'];
|
|
30
|
+
return [...new Set([...own, ...sessionProviderNames(inspection)])];
|
|
31
|
+
}
|
|
@@ -21,6 +21,7 @@ import { retainedSpawnDetails } from './launch-prompt-outcome.mjs';
|
|
|
21
21
|
import { answeringFeatures, busyHolder } from './lifecycle-contract.mjs';
|
|
22
22
|
import { displayLine } from './display-text.mjs';
|
|
23
23
|
import { requireTerms } from './client-terms.mjs';
|
|
24
|
+
import { sessionProviderName } from './instance-presentation.mjs';
|
|
24
25
|
|
|
25
26
|
/** The gate is page-safe and lives apart (start-gate.mjs); a client takes it from here, with the rest of the rule. */
|
|
26
27
|
export { startGate };
|
|
@@ -93,16 +94,27 @@ const START_REUSED = Object.freeze(['new', 'pane', 'adopted']);
|
|
|
93
94
|
/** Whether `v` is the receipt of a completed start or restart of `row`, as the kernel answers one
|
|
94
95
|
* (docs/desktop-cli-api.md, `oats session start`: `{instance, agent, home, harness, backend, model, launchConfig,
|
|
95
96
|
* yolo, target, startedAt, restartCount, reused, warnings}`): the row's instance, in the row's home (the kernel
|
|
96
|
-
* answers with its real path: `canonical`, the verified local home), on the
|
|
97
|
-
*
|
|
98
|
-
*
|
|
97
|
+
* answers with its real path: `canonical`, the verified local home), on the backend the receipt itself names, and
|
|
98
|
+
* the other fields a start always carries. What was started is what the receipt says, not what the row read before
|
|
99
|
+
* the start said: a home's backend can move at a start. The receipt's `backend` picks its shape:
|
|
100
|
+
* "tmux" with its target (`{backend, session, window, socket}`, more keys allowed)
|
|
101
|
+
* a session provider (instance-presentation.mjs `sessionProviderName`) with `session: {provider, endpoint?}` and
|
|
102
|
+
* no terminal target (`target` null or absent).
|
|
103
|
+
* A start on this machine carries the endpoint, an object; a routed one (`--server`) carries the
|
|
104
|
+
* provider alone, the endpoint never leaving its host: required here, refused there
|
|
105
|
+
* A receipt that names no backend, or anything else, is no receipt this client knows. Read where the CLI is newer
|
|
106
|
+
* than this client was tested with, so a format it does not know is not taken for one. */
|
|
99
107
|
function startReceipt(v, row, canonical) {
|
|
100
108
|
const record = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
|
|
101
109
|
const text = (x) => typeof x === 'string' && x.length > 0;
|
|
110
|
+
const routed = !!row.server;
|
|
111
|
+
const session = (x) => (x.backend === 'tmux'
|
|
112
|
+
? record(x.target) && x.target.backend === 'tmux' && text(x.target.session) && text(x.target.window)
|
|
113
|
+
&& text(x.target.socket) && x.target.socket.startsWith('/')
|
|
114
|
+
: sessionProviderName(x.backend) && (x.target === null || x.target === undefined) && record(x.session) && text(x.session.provider)
|
|
115
|
+
&& (routed ? x.session.endpoint === undefined : record(x.session.endpoint)));
|
|
102
116
|
return record(v) && v.instance === row.instance && text(v.home) && (v.home === row.home || (canonical !== null && v.home === canonical))
|
|
103
|
-
&& text(v.agent) && text(v.harness) && v.
|
|
104
|
-
&& record(v.target) && v.target.backend === 'tmux' && text(v.target.session) && text(v.target.window)
|
|
105
|
-
&& text(v.target.socket) && v.target.socket.startsWith('/')
|
|
117
|
+
&& text(v.agent) && text(v.harness) && text(v.startedAt) && session(v)
|
|
106
118
|
&& Number.isSafeInteger(v.restartCount) && v.restartCount >= 0 && START_REUSED.includes(v.reused)
|
|
107
119
|
&& Array.isArray(v.warnings) && v.warnings.every((w) => typeof w === 'string');
|
|
108
120
|
}
|
|
@@ -6,7 +6,7 @@ import { parseEnvelope, writeTaskFile, execFileInSession } from './cli-adapter.m
|
|
|
6
6
|
import { absolute, record, previewTarget, choiceArgv } from './spawn-preview-contract.mjs';
|
|
7
7
|
import { spawnDecision } from './spawn-decision.mjs';
|
|
8
8
|
import { spawnApplySupported, spawnApplyChoicesSupported, spawnPrepareInput, spawnReference, spawnApplyReason, spawnApplyDeadline,
|
|
9
|
-
SPAWN_APPLY_MS, ROLLED_BACK_CODES } from './spawn-apply-contract.mjs';
|
|
9
|
+
SPAWN_APPLY_MS, ROLLED_BACK_CODES, KERNEL_WORDED_CODES, kernelWordedDetails } from './spawn-apply-contract.mjs';
|
|
10
10
|
const failure = (code, started = false) => ({ started, envelope: { schemaVersion: 1, ok: false, error: spawnApplyReason(code) } });
|
|
11
11
|
const named = v => typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/.test(v);
|
|
12
12
|
const worktreeEvent = cli => Array.isArray(cli?.features) && cli.features.includes('worktree-event');
|
|
@@ -17,9 +17,11 @@ function refusal(doc, cli) {
|
|
|
17
17
|
// worktree-event: the three rolled-back codes keep the kernel's own message (it names the
|
|
18
18
|
// capability and its log), and whether its compensation was confirmed.
|
|
19
19
|
const rolledBack = worktreeEvent(cli) && ROLLED_BACK_CODES.includes(doc.error?.code);
|
|
20
|
-
const
|
|
20
|
+
const worded = KERNEL_WORDED_CODES.includes(doc.error?.code);
|
|
21
|
+
const error = spawnApplyReason(doc.error?.code, rolledBack || worded ? doc.error?.message : undefined);
|
|
21
22
|
let details;
|
|
22
|
-
if (
|
|
23
|
+
if (worded) details = kernelWordedDetails(doc.error?.details) ?? undefined;
|
|
24
|
+
else if (rolledBack) {
|
|
23
25
|
if (doc.error?.details?.unconfirmed === true) details = { unconfirmed: true };
|
|
24
26
|
} else if (error.code === 'E_DECISION_STALE') {
|
|
25
27
|
const decision = spawnDecision(doc.error?.details?.decision, { effectiveRequired: true });
|