@awebai/oats 0.69.23 → 0.70.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +112 -20
- package/docs/capabilities.md +697 -11
- package/docs/capability-manifest.schema.json +66 -0
- package/docs/configuration.md +27 -7
- package/docs/design/2026-11-19-sandboxes.md +595 -121
- package/docs/design/2026-11-20-provider-home-lifecycle.md +322 -0
- package/docs/design/README.md +7 -3
- package/docs/desktop-cli-api.md +330 -9
- package/docs/desktop.md +181 -48
- package/docs/execution-targets.md +210 -4
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +24 -3
- package/docs/integrations.md +2 -2
- package/docs/knowledge-capability-authoring.md +1 -1
- package/docs/knowledge-reference/proposal.md +10 -0
- package/docs/knowledge.md +20 -11
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.69.24.md +264 -0
- package/docs/release-notes/v0.70.0.md +155 -0
- package/docs/souls-and-instances.md +57 -0
- package/docs/trust-model.md +8 -1
- package/docs/tui.md +21 -1
- package/docs/upgrading.md +19 -5
- package/docs/workspaces.md +13 -5
- package/lib/automation-scope.mjs +1 -1
- package/lib/capability-show.mjs +20 -1
- package/lib/command-flags.mjs +2 -2
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1455 -203
- package/lib/errors.mjs +4 -1
- package/lib/home-integrity.mjs +329 -0
- package/lib/hook-env.mjs +107 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-events.mjs +32 -5
- package/lib/instance-git.mjs +9 -0
- package/lib/instance-inspect.mjs +107 -9
- package/lib/instance-lifecycle.mjs +15 -3
- package/lib/instance-listing.mjs +101 -8
- package/lib/instance-resolution.mjs +85 -2
- package/lib/instance-upgrade.mjs +170 -14
- package/lib/kernel-features.mjs +10 -1
- package/lib/node-version.mjs +9 -0
- package/lib/provider-call-child.mjs +60 -0
- package/lib/provider-resume.mjs +83 -0
- package/lib/provider-test-seams.mjs +20 -0
- package/lib/read-call.mjs +2 -0
- package/lib/remote.mjs +33 -1
- package/lib/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +12 -1
- package/lib/sandbox-allowances.mjs +329 -0
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +38 -5
- package/lib/session-inspect.mjs +123 -87
- package/lib/session-providers.mjs +575 -0
- package/lib/session-receipt.mjs +93 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- package/lib/upgrade-state.mjs +6 -1
- package/lib/worktree-hooks.mjs +18 -2
- package/lib/worktree.mjs +21 -7
- package/package-catalog.json +2 -2
- package/package.json +2 -1
- package/packages/client/capability-list.mjs +21 -0
- package/packages/client/cli-adapter.mjs +19 -4
- package/packages/client/cli-locator.mjs +5 -1
- package/packages/client/deployment-data.mjs +23 -1
- package/packages/client/deployment-panel.mjs +25 -3
- package/packages/client/home-board.mjs +33 -19
- package/packages/client/inspect-boundary.mjs +18 -8
- package/packages/client/instance-acts.mjs +30 -3
- package/packages/client/instance-board.mjs +206 -0
- package/packages/client/instance-presentation.mjs +55 -0
- package/packages/client/liveness.mjs +15 -4
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/remote-roster.mjs +6 -1
- package/packages/client/session-backends.mjs +31 -0
- package/packages/client/session-start.mjs +18 -6
- package/packages/client/spawn-apply-cli.mjs +5 -3
- package/packages/client/spawn-apply-contract.mjs +25 -2
- package/packages/client/spawn-apply.mjs +5 -1
- package/packages/client/spawn-messages.mjs +3 -0
- package/packages/client/terminal-contract.mjs +4 -0
- package/packages/client/waiting-on-you.mjs +12 -2
- package/packages/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- package/skills/oats-getting-started/SKILL.md +3 -3
|
@@ -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 });
|
|
@@ -173,18 +173,41 @@ const errors = {
|
|
|
173
173
|
E_INTERRUPTED: 'The spawn was interrupted while its worktree hooks ran.',
|
|
174
174
|
E_REQUIRED_HOOK_FAILED: 'A required worktree hook failed.',
|
|
175
175
|
E_HOOK_ENVIRONMENT_CONTRACT: 'A worktree hook broke the hook environment contract.',
|
|
176
|
+
// Feature sandboxes (D-S1-4): a spawn into a sandbox is bound and keyed by the kernel itself, never by a
|
|
177
|
+
// confirmed apply. Shown only when the kernel's own message cannot travel.
|
|
178
|
+
E_SANDBOX_PLACEMENT: 'This soul runs in a sandbox, which a confirmed spawn cannot reach. Spawn it with `oats spawn <soul>` (OATS binds it to the sandbox itself) or from a schedule.',
|
|
176
179
|
};
|
|
180
|
+
/** Refusals whose kernel message and `details: {reason, remedy}` travel: the kernel says why and what a
|
|
181
|
+
* person does next (feature sandboxes, E_SANDBOX_PLACEMENT). Nothing else of their details is kept. */
|
|
182
|
+
export const KERNEL_WORDED_CODES = ['E_SANDBOX_PLACEMENT'];
|
|
183
|
+
const MESSAGE_MAX = 2048, REMEDY_MAX = 1024;
|
|
184
|
+
const REASON = /^[a-z][a-z0-9-]{0,63}$/;
|
|
185
|
+
// As previewFailure bounds a kernel message: at most `max` characters, no control character but a
|
|
186
|
+
// newline, no credential-shaped text.
|
|
187
|
+
const boundedText = (v, max) => typeof v === 'string' && !!v.trim() && v.length <= max && !v.includes('\0')
|
|
188
|
+
&& !/[\x00-\x09\x0b-\x1f\x7f]|https?:\/\/[^/\s]*@|(?:gh[pousr]_|github_pat_)[A-Za-z0-9_]{16,}/.test(v);
|
|
189
|
+
/** A kernel-worded refusal's details as they travel: `reason` (a slug) and `remedy` (bounded text), each
|
|
190
|
+
* only when valid; null when neither is. */
|
|
191
|
+
export function kernelWordedDetails(details) {
|
|
192
|
+
if (!record(details)) return null;
|
|
193
|
+
const out = {
|
|
194
|
+
...(typeof details.reason === 'string' && REASON.test(details.reason) ? { reason: details.reason } : {}),
|
|
195
|
+
...(boundedText(details.remedy, REMEDY_MAX) ? { remedy: details.remedy } : {}),
|
|
196
|
+
};
|
|
197
|
+
return Object.keys(out).length ? out : null;
|
|
198
|
+
}
|
|
177
199
|
/** Feature worktree-event: a dispatched spawn failure with one of these codes and no
|
|
178
200
|
* `details.unconfirmed: true` was rolled back by the kernel (confirmed compensation): nothing
|
|
179
201
|
* was created. With the marker its cleanup is owed. Only these three; every other code keeps
|
|
180
202
|
* the unknown-unless-proven rule. */
|
|
181
203
|
export const ROLLED_BACK_CODES = ['E_INTERRUPTED', 'E_REQUIRED_HOOK_FAILED', 'E_HOOK_ENVIRONMENT_CONTRACT'];
|
|
182
|
-
/** The kernel's message travels
|
|
183
|
-
* bounded here, and shown through displayLine. */
|
|
204
|
+
/** The kernel's message travels for ROLLED_BACK_CODES (it names the capability and its log) and
|
|
205
|
+
* KERNEL_WORDED_CODES; bounded here, and shown through displayLine. */
|
|
184
206
|
const kernelText = v => typeof v === 'string' && !!v.trim() && v.length <= 4096 && !v.includes('\0');
|
|
185
207
|
export function spawnApplyReason(code, kernelMessage) {
|
|
186
208
|
if (typeof code !== 'string') code = 'E_CLI_FAILED';
|
|
187
209
|
if (ROLLED_BACK_CODES.includes(code)) return { code, message: kernelText(kernelMessage) ? kernelMessage : errors[code] };
|
|
210
|
+
if (KERNEL_WORDED_CODES.includes(code)) return { code, message: boundedText(kernelMessage, MESSAGE_MAX) ? kernelMessage : errors[code] };
|
|
188
211
|
if (Object.hasOwn(errors, code)) return { code, message: errors[code] };
|
|
189
212
|
const reason = previewFailure(code).reason;
|
|
190
213
|
return reason.code === code && code !== 'E_CLI_FAILED' ? reason : { code: 'E_CLI_FAILED', message: errors.E_CLI_FAILED };
|
|
@@ -15,7 +15,7 @@ import { cliSpawnApply } from './spawn-apply-cli.mjs';
|
|
|
15
15
|
import { admitSpawnSelection, PREVIEW_MAX_AGE_S } from './spawn-preview.mjs';
|
|
16
16
|
import { record } from './spawn-preview-contract.mjs';
|
|
17
17
|
import { spawnApplySupported, spawnApplyChoicesSupported, spawnPrepareInput, spawnRefInput, spawnPreparedData, spawnReference,
|
|
18
|
-
spawnCreationReceipt, spawnApplyFailure, spawnApplyDeadlineMs, ROLLED_BACK_CODES, WAKE_OUTCOME_UNKNOWN } from './spawn-apply-contract.mjs';
|
|
18
|
+
spawnCreationReceipt, spawnApplyFailure, spawnApplyDeadlineMs, ROLLED_BACK_CODES, KERNEL_WORDED_CODES, WAKE_OUTCOME_UNKNOWN } from './spawn-apply-contract.mjs';
|
|
19
19
|
/** The apply request answers within this; the proxy's own 65 s timeout then never fires on a healthy spawn. */
|
|
20
20
|
export const ANSWER_WITHIN_MS = 50000;
|
|
21
21
|
export const MAX_APPLIES = 4;
|
|
@@ -145,6 +145,10 @@ export function createSpawnApplyBoundary({ read, invoke = cliSpawnApply, exec, a
|
|
|
145
145
|
if (envelope.error.details?.unconfirmed === true) { entry.final = true; return denied(code, entry, 'unknown', message); }
|
|
146
146
|
return denied(code, entry, 'refused', message);
|
|
147
147
|
}
|
|
148
|
+
// Feature sandboxes (D-S1-4): a spawn into a sandbox is refused before anything is minted, kept or
|
|
149
|
+
// created (docs/desktop-cli-api.md, Sandbox refusals): refused, in the kernel's words, which end with
|
|
150
|
+
// what a person does next.
|
|
151
|
+
if (KERNEL_WORDED_CODES.includes(code)) return denied(code, entry, 'refused', envelope.error.message);
|
|
148
152
|
// A taken explicit name (spawn-name) refuses before any home is kept: the
|
|
149
153
|
// confirmation is consumed and a fresh preview reports the taken name.
|
|
150
154
|
if (['E_DECISION_STALE', 'E_IDEMPOTENCY_CONFLICT', 'E_PLACEMENT_TAKEN', 'E_INSTANCE_NAME_TAKEN'].includes(code)) return denied(code, entry, 'stale');
|
|
@@ -89,6 +89,9 @@ const SPAWN_FACTS = {
|
|
|
89
89
|
E_CLI_OUTPUT_LIMIT: said('OATS couldn’t confirm the spawn.', 'check-result'),
|
|
90
90
|
E_CLI_PROTOCOL: said('OATS couldn’t complete the spawn.', 'details'),
|
|
91
91
|
E_CLI_FAILED: said('OATS couldn’t complete the spawn.', 'details'),
|
|
92
|
+
// Feature sandboxes (D-S1-4): the kernel binds a spawn into a sandbox itself; its own remedy is the detail
|
|
93
|
+
// (`details`: a client shows it). Trying again cannot work: a client's words for this next say so per code.
|
|
94
|
+
E_SANDBOX_PLACEMENT: said('This soul runs in a sandbox, which a confirmed spawn can’t reach yet. Nothing was created. Spawn it with oats spawn in a terminal, or from a schedule.', 'details'),
|
|
92
95
|
// Wherever nothing is above the sentence and Details hold no kernel text: the whole of it is shared.
|
|
93
96
|
[UNMATCHED]: said('This machine’s launch preferences name a soul this workspace doesn’t offer, so OATS won’t choose a launch for this soul. To spawn now, pick a harness or a launch configuration for this spawn. To fix it for every spawn, correct the preference.'),
|
|
94
97
|
};
|
|
@@ -37,6 +37,10 @@ const messages = {
|
|
|
37
37
|
E_TERM_ATTACHMENT_FAILED: 'Could not prepare these attachments.',
|
|
38
38
|
E_TERM_ATTACHMENT_INTERRUPTED: 'Attachment interrupted; some file copies may already exist. No input was inserted.',
|
|
39
39
|
E_TERM_INPUT_LIMIT: 'Terminal input exceeds the safe write limit. Nothing was sent.',
|
|
40
|
+
// An answer (the agent view) refused because the terminal is in tmux's scrollback (copy mode): nothing was typed.
|
|
41
|
+
E_TERM_IN_MODE: 'The terminal is in its scrollback. Nothing was typed.',
|
|
42
|
+
// An answer refused because the pane's mode could not be read (or there is no local pane to read): nothing was typed.
|
|
43
|
+
E_TERM_MODE_UNKNOWN: 'The terminal could not be checked for its scrollback. Nothing was typed.',
|
|
40
44
|
E_TERM_TRANSPORT: 'The terminal service did not confirm the operation.',
|
|
41
45
|
E_HERDR_REMOVED: HERDR_REMOVED,
|
|
42
46
|
E_TERM_REMOTE_UNREACHABLE: serverMessages.E_TERM_REMOTE_UNREACHABLE('the server'),
|
|
@@ -7,6 +7,7 @@
|
|
|
7
7
|
import { record } from './readiness-contract.mjs';
|
|
8
8
|
import { eventsTimestamp, eventsId, eventsUnsafe, EVENTS_WITHHELD } from './instance-events-contract.mjs';
|
|
9
9
|
import { NOT_NOTE_TEXT } from './display-text.mjs';
|
|
10
|
+
import { sessionProvider } from './instance-presentation.mjs';
|
|
10
11
|
|
|
11
12
|
/** A claim's note: a non-empty string of at most 200 code points (not UTF-16 units: 101 emoji is a valid
|
|
12
13
|
* note), with none of NOT_NOTE_TEXT (the set's one definition is in display-text.mjs); unsafe text is
|
|
@@ -36,9 +37,18 @@ export function waitingOnYouData(v) {
|
|
|
36
37
|
* or a row the roster holds stale (`stale`: its last re-read failed), carries a last-known claim, which is
|
|
37
38
|
* unknown. A null or absent `runtimeState` is "not reported", never "not running" (#582): the kernel's
|
|
38
39
|
* remote roster sends null on every row, so a remote row is gated on the `running` its host reported; a
|
|
39
|
-
* local row always carries the concrete state Desktop liveness observed.
|
|
40
|
+
* local row always carries the concrete state Desktop liveness observed.
|
|
41
|
+
*
|
|
42
|
+
* A row on a session provider (instance-presentation.mjs `sessionProvider`: "bb", say) has another liveness
|
|
43
|
+
* gate, under the same two rules of currency: it shows the claim the kernel's row carries unless the row is
|
|
44
|
+
* stopped (`running === false`). Its `runtimeState` is never "running" (a provider's states are `unknown`,
|
|
45
|
+
* `shell`, `stopped`, `unreachable`), and an agent that waits on a person is idle there, which the kernel
|
|
46
|
+
* reports as `running: null`: the kernel is such a row's only reader, and it decides whether the row carries
|
|
47
|
+
* a claim at all. A home OATS stopped reads `running: false` and shows none. */
|
|
40
48
|
export function waitingClaim(row, { stale = false } = {}) {
|
|
41
|
-
if (stale || !record(row) || row.
|
|
49
|
+
if (stale || !record(row) || row.serverUnreached === true) return null;
|
|
50
|
+
if (sessionProvider(row)) return row.running === false ? null : waitingOnYouData(row.waitingOnYou);
|
|
51
|
+
if (row.running !== true) return null;
|
|
42
52
|
if (row.runtimeState != null && row.runtimeState !== 'running') return null;
|
|
43
53
|
return waitingOnYouData(row.waitingOnYou);
|
|
44
54
|
}
|
|
@@ -108,7 +108,11 @@ export function reachedMachines(state, at) {
|
|
|
108
108
|
* that was not reached (the shared home marks it) still carries the word of its last report,
|
|
109
109
|
* which is not its state now: it gets the shared word, so nothing reads as stopped, or as
|
|
110
110
|
* running, that is only not reached. */
|
|
111
|
-
const stateWord = (row) => (text(row.runtimeState) && row.serverUnreached !== true ? row.runtimeState : runtimeState(row));
|
|
111
|
+
const stateWord = (row) => (text(row.runtimeState) && row.serverUnreached !== true && !providerKnown(row) ? row.runtimeState : runtimeState(row));
|
|
112
|
+
/** A row on a session provider (the shared openAct's `no-terminal`) whose `running` the kernel answered: its
|
|
113
|
+
* `runtimeState` is the provider's word (`unknown` while it runs), which would contradict its mark, so its
|
|
114
|
+
* state is the shared word for its `running`. One the kernel answered `running: null` keeps the kernel's word. */
|
|
115
|
+
const providerKnown = (row) => typeof row.running === "boolean" && openAct(row)?.reason?.code === "no-terminal";
|
|
112
116
|
/** The word a list row shows beside its name, or null: only what its mark cannot say. That is a
|
|
113
117
|
* held home's state (Retiring… while a retire runs, or this run's own is in flight), else the
|
|
114
118
|
* shared label of the reason the row can't be reached or opened (remote-address.mjs rowReason:
|
|
@@ -528,7 +532,8 @@ const elsewhere = (row) => typeof row.server === "string" && row.server !== "";
|
|
|
528
532
|
* for a row of another machine (its preflight runs first)
|
|
529
533
|
* { open: false, said: { said, under } } opens nothing, and this says why
|
|
530
534
|
* Whether a row can be opened is the shared openAct's, switched on its reason's code, never on a
|
|
531
|
-
* sentence.
|
|
535
|
+
* sentence. A row on a session provider is never opened, from the list, the palette, the steps or a
|
|
536
|
+
* workspace's remembered tabs (they all ask here); its reason's link is printed under its sentence. The viewer is started with no key of its own (the TUI takes the back key before the
|
|
532
537
|
* pane sees it), so a kernel or a host of any version is opened alike. */
|
|
533
538
|
export function openDecision(state, row, acts) {
|
|
534
539
|
const name = row.instance, id = instanceId(row);
|
|
@@ -542,7 +547,13 @@ export function openDecision(state, row, acts) {
|
|
|
542
547
|
if (!act.enabled) {
|
|
543
548
|
if (act.reason.code === "not-running") return no(OPEN_WORDS.notRunning(name));
|
|
544
549
|
if (act.reason.code === "state-unknown") return no(OPEN_WORDS.stateUnknown(name));
|
|
545
|
-
|
|
550
|
+
// A row on a session provider (code `no-terminal`) has no terminal: the shared home's sentence says where
|
|
551
|
+
// the agent runs, and under it the link the provider offers (its label and its url, one text from outside),
|
|
552
|
+
// for the person to open themselves. The link carries no mark of who made it, and the TUI names no speaker
|
|
553
|
+
// of its own (test/tui-boundary.test.mjs): it stands in quotation marks, as any text nobody vouches for.
|
|
554
|
+
// Nothing is attached or started.
|
|
555
|
+
const link = act.reason.link ? spoken(`${act.reason.link.label}: ${act.reason.link.url}`, undefined, false) : null;
|
|
556
|
+
return no([], [...outside(reasonSpoken(act.reason)), ...outside(link)]);
|
|
546
557
|
}
|
|
547
558
|
if (!elsewhere(row)) return { open: true, id, name, machine, target: { home: row.home }, routed: false };
|
|
548
559
|
return { open: true, id, name, machine, target: { serverId: row.server, instance: row.instance, home: row.home }, routed: true };
|
|
@@ -10,7 +10,7 @@
|
|
|
10
10
|
// Selection is an identity (the shared `instanceId`), never an index, so it survives every read;
|
|
11
11
|
// the rows it moves among are the model's, in drawn order.
|
|
12
12
|
import { ACTIONS, LEADER_KEYS, backKeyLabel, bindings, chordKeys, chordsRead, paletteKeys } from "./actions.mjs";
|
|
13
|
-
import { CHORDS, chordFamilyFrom, collapseKey, workspaceStep, displayLine, instanceActs, instanceId, outcomeWords, pendingEntry, spawnProblem } from "./client.mjs";
|
|
13
|
+
import { CHORDS, chordFamilyFrom, collapseKey, workspaceStep, displayLine, instanceActs, instanceId, openAct, outcomeWords, pendingEntry, spawnProblem } from "./client.mjs";
|
|
14
14
|
import { defaultDetachKey } from "./config.mjs";
|
|
15
15
|
import { BACKGROUND_ID, backgroundOpen, BUTTON_ORDER, PIN_WORDS, pinDecision, pinLine, SPAWN_WORDS, LEADER_WORDS, SPLIT_WORDS, TAB_WORDS, actDecision, capabilitiesHeight, capabilitiesOf, capabilityUsersOf, disclosure, openDecision, paletteItems, paletteStep, preflightLine, returnedLine, roster, soulNames, soulOfAgent, soulsOf, spawnChoices, spawnChoicesKey, spawnLine, spawnPickerItems, spawnReady, spawnRing, spawnSelector, spawnedRow, switcher, switcherHeight, switcherWindow, memoryKey, memoryKeys, LIST_WORDS, WORKSPACE_WORDS, listChoice, listChoices, workspaceList } from "./model.mjs";
|
|
16
16
|
import { backKeyId, backKeySequences, isBackKey } from "./term/through.mjs";
|
|
@@ -1120,12 +1120,21 @@ const TAB_PICKS = Object.freeze({
|
|
|
1120
1120
|
|
|
1121
1121
|
/** The preflight of another machine's agent ended. Given up meanwhile (Esc, a suspend, a second
|
|
1122
1122
|
* open): dropped. Failed: the line that says so, unless it is the person's own giving up. Else
|
|
1123
|
-
* the viewer is started in the panel, unless the row it is for has gone from the roster since
|
|
1123
|
+
* the viewer is started in the panel, unless the row it is for has gone from the roster since, or
|
|
1124
|
+
* runs on a session provider now: the roster may have brought, while the preflight ran, the row of a
|
|
1125
|
+
* home that moved to one, which has no terminal (the shared open decision, asked again of the row as
|
|
1126
|
+
* it is now). Then nothing starts: the line says where it runs, as Enter on that row would, and a
|
|
1127
|
+
* restore says nothing, as for any tab it drops. A row that runs in tmux is started as before. */
|
|
1124
1128
|
function prepared(state, { id, error }) {
|
|
1125
1129
|
const opening = state.opening;
|
|
1126
1130
|
if (opening === null || opening.id !== id || opening.phase !== "preflight") return { state, effect: null };
|
|
1127
1131
|
if (error !== undefined) return { state: next(state, { opening: null, outcome: preflightLine(opening, error) }), effect: null };
|
|
1128
|
-
|
|
1132
|
+
const row = roster(state).instances.find((each) => instanceId(each) === id) ?? null;
|
|
1133
|
+
if (row === null) return { state: next(state, { opening: null }), effect: null };
|
|
1134
|
+
if (openAct(row)?.reason?.code === "no-terminal") {
|
|
1135
|
+
const decision = openDecision(state, row, instanceActs(row));
|
|
1136
|
+
return { state: next(state, { opening: null, ...(opening.restore ? {} : { outcome: decision.said }) }), effect: null };
|
|
1137
|
+
}
|
|
1129
1138
|
return { state: (opening.restore ? restoredTab : tabOpened)(next(state, { opening: null }), opening), effect: { panel: id } };
|
|
1130
1139
|
}
|
|
1131
1140
|
|
|
@@ -562,7 +562,7 @@ installed CLI's catalog:
|
|
|
562
562
|
node -e 'const c=require(process.argv[1]);console.log(c.packages["oats.framework"].ref,c.packages["oats.aweb"].ref)' "$(oats root)/package-catalog.json"
|
|
563
563
|
```
|
|
564
564
|
|
|
565
|
-
It prints the two refs, for example `oats-framework/v1.
|
|
565
|
+
It prints the two refs, for example `oats-framework/v1.28.0 v1.47.0`. If the
|
|
566
566
|
framework's version (after the `/`) is below `1.19.0`, or with aweb
|
|
567
567
|
`oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
|
|
568
568
|
skill: stop, and tell the person to wait for the next OATS
|
|
@@ -856,8 +856,8 @@ name: acme
|
|
|
856
856
|
members:
|
|
857
857
|
- git:github.com/acme/acme-oats # the host; the setup expert adds the others
|
|
858
858
|
packages:
|
|
859
|
-
oats.framework: v1.
|
|
860
|
-
oats.aweb: v1.
|
|
859
|
+
oats.framework: v1.28.0 # the installed CLI's catalog versions (below)
|
|
860
|
+
oats.aweb: v1.47.0 # messaging: agent identities, mail and chat
|
|
861
861
|
oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
|
|
862
862
|
defaults:
|
|
863
863
|
capabilities:
|