@awebai/oats 0.69.22 → 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 +185 -38
- package/docs/capabilities.md +365 -7
- package/docs/capability-manifest.schema.json +37 -1
- package/docs/configuration.md +27 -7
- package/docs/container.md +206 -228
- package/docs/design/2026-11-19-sandboxes.md +1352 -0
- package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
- package/docs/design/README.md +7 -0
- package/docs/desktop-cli-api.md +673 -81
- package/docs/desktop.md +241 -65
- package/docs/execution-targets.md +186 -3
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +6 -2
- package/docs/integrations.md +3 -3
- package/docs/knowledge-capability-authoring.md +10 -7
- package/docs/knowledge-reference/acceptance.md +21 -19
- package/docs/knowledge-reference/adoption.md +18 -4
- package/docs/knowledge-reference/model.md +11 -9
- package/docs/knowledge-reference/package-craft.md +2 -2
- package/docs/knowledge-reference/proposal.md +127 -0
- package/docs/knowledge-reference/provider-mapping.md +10 -10
- package/docs/knowledge-reference/reader-capture.md +26 -22
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -16
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +13 -13
- package/docs/release-notes/v0.69.23.md +231 -0
- package/docs/release-notes/v0.69.24.md +264 -0
- package/docs/servers.md +10 -6
- package/docs/souls-and-instances.md +96 -22
- package/docs/tui.md +25 -4
- package/docs/upgrading.md +19 -5
- package/docs/workspaces.md +14 -6
- package/lib/argv.mjs +6 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/capability-show.mjs +11 -1
- package/lib/command-flags.mjs +40 -3
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1201 -195
- package/lib/errors.mjs +4 -1
- package/lib/hook-env.mjs +106 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-board.mjs +337 -0
- package/lib/instance-events.mjs +48 -10
- package/lib/instance-inspect.mjs +44 -0
- package/lib/instance-lifecycle.mjs +34 -18
- package/lib/instance-listing.mjs +113 -16
- package/lib/instance-related-work.mjs +143 -0
- package/lib/kernel-features.mjs +13 -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 +151 -17
- 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 +3 -3
- 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 +27 -3
- package/packages/client/deployment-panel.mjs +27 -4
- 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/instance-tree.mjs +34 -4
- package/packages/client/keymap.mjs +5 -0
- package/packages/client/liveness.mjs +15 -4
- package/packages/client/mail-contract.mjs +130 -0
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/panel-views.mjs +7 -7
- package/packages/client/related-work.mjs +84 -0
- package/packages/client/remote-roster.mjs +9 -3
- 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/client/workspace-cli.mjs +13 -2
- package/packages/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- package/skills/oats-getting-started/SKILL.md +11 -8
- package/docs/knowledge-reference/harvester.md +0 -109
- package/lib/instance-same-work.mjs +0 -67
- package/packages/client/same-work.mjs +0 -49
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
/** An agent's own mail, read without acknowledging anything: the messaging layer's `messaging:mail` view operation
|
|
2
|
+
* (docs/desktop-cli-api.md, "Mail", `mailApi: 1`), run as `oats operation run messaging:mail --home <abs> [--arg
|
|
3
|
+
* limit=…] [--arg cursor=…] [--arg conversation=…] [--server <id>] --json`. Any messaging provider may answer it;
|
|
4
|
+
* oats.aweb is the first. The provider's values are opaque strings here: identity, message and conversation ids,
|
|
5
|
+
* team labels. Nothing in this module parses a provider-specific shape.
|
|
6
|
+
*
|
|
7
|
+
* The run's `result` is `{documents, mail}`: `documents` is the plain rendering every view carries, `mail` the
|
|
8
|
+
* structured field this module decodes, exactly as the contract states it (shapes are closed: an unknown key, a
|
|
9
|
+
* value outside its set or a bound passed is the whole answer unreadable, never a partial guess). An answer that
|
|
10
|
+
* says it acknowledged (`acknowledges` other than false) is unreadable too: a client never shows mail read by
|
|
11
|
+
* marking it read.
|
|
12
|
+
*
|
|
13
|
+
* Pure: no DOM, no IO, never throws. Shared by both clients (the Terminal UI renders the same sheet later). */
|
|
14
|
+
import { NOT_NOTE_TEXT } from './display-text.mjs';
|
|
15
|
+
|
|
16
|
+
export const MAIL_OPERATION = 'messaging:mail';
|
|
17
|
+
/** What a client asks for at a time (the contract's default) and at most. */
|
|
18
|
+
export const MAIL_PAGE = 50, MAIL_MAX_LIMIT = 200;
|
|
19
|
+
/** A body's bound, in UTF-8 bytes: past it the provider cuts and says `truncated: true`. */
|
|
20
|
+
export const MAIL_BODY_BYTES = 16 * 1024;
|
|
21
|
+
export const VERIFICATIONS = Object.freeze(['verified', 'unverified', 'failed', 'unknown']);
|
|
22
|
+
export const PRIORITIES = Object.freeze(['normal', 'high', 'unknown']);
|
|
23
|
+
export const DIRECTIONS = Object.freeze(['received', 'sent']);
|
|
24
|
+
export const PARTIAL_OLDEST_FIRST = 'oldest-first-only';
|
|
25
|
+
|
|
26
|
+
const MAIL_KEYS = ['mailApi', 'acknowledges', 'observedAt', 'identities', 'messages', 'conversations', 'hasMore', 'nextCursor'];
|
|
27
|
+
const IDENTITY_KEYS = ['team', 'alias', 'identity', 'primary', 'error'];
|
|
28
|
+
const MESSAGE_KEYS = ['id', 'conversationId', 'threadTitle', 'direction', 'team', 'from', 'to', 'subject', 'body', 'truncated',
|
|
29
|
+
'createdAt', 'readByAgent', 'encrypted', 'verification', 'priority'];
|
|
30
|
+
const PARTY_KEYS = ['alias', 'address', 'identity'];
|
|
31
|
+
const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/;
|
|
32
|
+
|
|
33
|
+
const record = v => !!v && typeof v === 'object' && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
|
|
34
|
+
const exact = (v, keys) => record(v) && Object.keys(v).length === keys.length && keys.every(k => Object.hasOwn(v, k));
|
|
35
|
+
/** Text: the contract bounds a body (16 KiB), a page (200 messages) and the whole result (256 KiB, which the transport
|
|
36
|
+
* bounds again), never a subject, a title, an alias or an id: those are any string, and only their display is cut. */
|
|
37
|
+
const text = (v, empty = false) => typeof v === 'string' && (empty || v.length > 0);
|
|
38
|
+
/** An opaque provider value (an id, a label, an alias): any non-empty string, never parsed. */
|
|
39
|
+
const opaque = v => text(v);
|
|
40
|
+
const iso = v => typeof v === 'string' && v.length <= 40 && ISO.test(v) && !Number.isNaN(Date.parse(v));
|
|
41
|
+
const utf8Bytes = s => {
|
|
42
|
+
let n = 0;
|
|
43
|
+
for (const ch of s) { const c = ch.codePointAt(0); n += c < 0x80 ? 1 : c < 0x800 ? 2 : c < 0x10000 ? 3 : 4; }
|
|
44
|
+
return n;
|
|
45
|
+
};
|
|
46
|
+
|
|
47
|
+
function party(p) {
|
|
48
|
+
return exact(p, PARTY_KEYS) && opaque(p.alias) && (p.address === null || opaque(p.address)) && opaque(p.identity);
|
|
49
|
+
}
|
|
50
|
+
/** The conversations of one identity that couldn't be read (contract v2's details, Juan's side's ask): present only with
|
|
51
|
+
* the error `conversation-unreadable`, absent otherwise; opaque ids in the order the read met them. It may be empty (a
|
|
52
|
+
* message with no conversation isn't named) and may list fewer than failed (its tail goes first under the 256 KiB bound). */
|
|
53
|
+
const UNREADABLE = 'unreadableConversations';
|
|
54
|
+
function identity(i) {
|
|
55
|
+
const listed = record(i) && Object.hasOwn(i, UNREADABLE);
|
|
56
|
+
if (listed && !(i.error === 'conversation-unreadable' && Array.isArray(i[UNREADABLE]) && i[UNREADABLE].every(opaque))) return false;
|
|
57
|
+
return exact(i, listed ? [...IDENTITY_KEYS, UNREADABLE] : IDENTITY_KEYS) && opaque(i.team) && opaque(i.alias) && opaque(i.identity) && typeof i.primary === 'boolean'
|
|
58
|
+
// An identity's error: the provider's word for it (oats.aweb: identity-missing, identity-unreadable, no-mail-read,
|
|
59
|
+
// threads-unreadable, conversation-unreadable, too-many-threads), opaque: a client words the ones it knows.
|
|
60
|
+
&& (i.error === null || opaque(i.error));
|
|
61
|
+
}
|
|
62
|
+
function message(m) {
|
|
63
|
+
return exact(m, MESSAGE_KEYS) && opaque(m.id) && (m.conversationId === null || opaque(m.conversationId)) && text(m.threadTitle, true)
|
|
64
|
+
&& DIRECTIONS.includes(m.direction) && opaque(m.team) && party(m.from) && party(m.to) && text(m.subject, true)
|
|
65
|
+
&& typeof m.body === 'string' && utf8Bytes(m.body) <= MAIL_BODY_BYTES && typeof m.truncated === 'boolean' && iso(m.createdAt)
|
|
66
|
+
&& typeof m.readByAgent === 'boolean' && typeof m.encrypted === 'boolean' && VERIFICATIONS.includes(m.verification)
|
|
67
|
+
&& PRIORITIES.includes(m.priority);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** The `mail` field of a `messaging:mail` run, decoded; null when the answer is not the contract's. The run is the
|
|
71
|
+
* `oats operation run --json` result (`{operationsApi: 2, operation, result, …}`).
|
|
72
|
+
* Returns `{ observedAt, identities, messages, partial: Set<conversationId>, hasMore, nextCursor }`. */
|
|
73
|
+
export function mailAnswer(run) {
|
|
74
|
+
if (!record(run) || run.operationsApi !== 2 || run.operation !== MAIL_OPERATION) return null;
|
|
75
|
+
const r = run.result;
|
|
76
|
+
if (!exact(r, ['documents', 'mail']) || !Array.isArray(r.documents)) return null;
|
|
77
|
+
const d = r.mail;
|
|
78
|
+
if (!exact(d, MAIL_KEYS) || d.mailApi !== 1 || d.acknowledges !== false || !iso(d.observedAt)) return null;
|
|
79
|
+
if (!Array.isArray(d.identities) || !d.identities.every(identity)) return null;
|
|
80
|
+
if (!Array.isArray(d.messages) || d.messages.length > MAIL_MAX_LIMIT || !d.messages.every(message)) return null;
|
|
81
|
+
if (!Array.isArray(d.conversations) || !d.conversations.every(c => exact(c, ['id', 'partial']) && opaque(c.id) && (c.partial === null || c.partial === PARTIAL_OLDEST_FIRST))) return null;
|
|
82
|
+
if (typeof d.hasMore !== 'boolean' || !(d.nextCursor === null || opaque(d.nextCursor))) return null;
|
|
83
|
+
// More to read needs the cursor that reads it; a cursor with nothing more is the provider's slip, and dropped.
|
|
84
|
+
if (d.hasMore && d.nextCursor === null) return null;
|
|
85
|
+
const keys = d.messages.map(messageKey);
|
|
86
|
+
if (new Set(keys).size !== keys.length) return null;
|
|
87
|
+
return {
|
|
88
|
+
observedAt: d.observedAt,
|
|
89
|
+
identities: structuredClone(d.identities),
|
|
90
|
+
messages: structuredClone(d.messages),
|
|
91
|
+
partial: new Set(d.conversations.filter(c => c.partial === PARTIAL_OLDEST_FIRST).map(c => c.id)),
|
|
92
|
+
hasMore: d.hasMore,
|
|
93
|
+
nextCursor: d.hasMore ? d.nextCursor : null,
|
|
94
|
+
};
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
/** A message's identity across pages: its team and its id (ids are the provider's, per identity). */
|
|
98
|
+
export const messageKey = m => JSON.stringify([m.team, m.id]);
|
|
99
|
+
|
|
100
|
+
/** Whether a cursor can travel as an operation argument (cli-adapter.mjs operationArgs: one line of at most 1024
|
|
101
|
+
* characters). One that can't is no way to the next page from this client: the sheet offers none. */
|
|
102
|
+
export const cursorUsable = c => typeof c === 'string' && c.length > 0 && c.length <= 1024 && !/[\x00-\x1f\x7f]/.test(c);
|
|
103
|
+
|
|
104
|
+
/** The arguments of one read: the first page (no cursor) or the page after `cursor`. Only declared arguments. */
|
|
105
|
+
export function mailArgs({ cursor = null, limit = MAIL_PAGE } = {}) {
|
|
106
|
+
const n = Number.isInteger(limit) ? Math.min(Math.max(limit, 1), MAIL_MAX_LIMIT) : MAIL_PAGE;
|
|
107
|
+
return { limit: String(n), ...(cursorUsable(cursor) ? { cursor } : {}) };
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/** A body as display lines: line breaks kept (CRLF and lone CR as one), tabs as spaces, every other character a note
|
|
111
|
+
* may not hold (control characters, bidi overrides and isolates, zero-width and tag characters) replaced with U+FFFD,
|
|
112
|
+
* so the reader sees something was there. For display only: never evidence of who wrote it. Trailing blank lines go. */
|
|
113
|
+
export function mailBodyLines(body) {
|
|
114
|
+
if (typeof body !== 'string') return [];
|
|
115
|
+
const every = new RegExp(NOT_NOTE_TEXT.source, 'gu');
|
|
116
|
+
const lines = body.replace(/\r\n?/g, '\n').split('\n').map(line => line.replace(/\t/g, ' ').replace(every, '\uFFFD'));
|
|
117
|
+
while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
|
|
118
|
+
return lines;
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/** How much of one line of provider text is shown: the rest is cut, with an ellipsis. */
|
|
122
|
+
export const MAIL_LINE_SHOWN = 512;
|
|
123
|
+
/** One line of provider text (a subject, an alias, a title, an identity's error) as shown: line breaks as spaces, the
|
|
124
|
+
* rest as mailBodyLines does, cut past MAIL_LINE_SHOWN characters (never inside a surrogate pair). */
|
|
125
|
+
export function mailLine(value) {
|
|
126
|
+
const line = mailBodyLines(typeof value === 'string' ? value.replace(/[\r\n]+/g, ' ') : '').join(' ').trim();
|
|
127
|
+
if (line.length <= MAIL_LINE_SHOWN) return line;
|
|
128
|
+
const cut = /[\uD800-\uDBFF]/.test(line[MAIL_LINE_SHOWN - 1]) ? MAIL_LINE_SHOWN - 1 : MAIL_LINE_SHOWN;
|
|
129
|
+
return `${line.slice(0, cut)}…`;
|
|
130
|
+
}
|
|
@@ -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());
|
|
@@ -46,7 +46,7 @@ import { teamMembers } from './team-members.mjs';
|
|
|
46
46
|
import { requireTerms } from './client-terms.mjs';
|
|
47
47
|
import { ROSTER_WORKSPACE_KEY } from './cli-adapter.mjs';
|
|
48
48
|
import { waitingClaim } from './waiting-on-you.mjs';
|
|
49
|
-
import {
|
|
49
|
+
import { relatedWorkDeclared, withRelatedWorkGate } from './related-work.mjs';
|
|
50
50
|
|
|
51
51
|
/** Roots come ONLY from the kernel's observed `status.root`; before (or
|
|
52
52
|
* without) an observation there is nothing to act on. No layout guess. */
|
|
@@ -311,19 +311,19 @@ export function deploymentEntry(info, primary) {
|
|
|
311
311
|
}
|
|
312
312
|
|
|
313
313
|
/** One deployment's own panel, as served before views. Each row carries whether its host declares
|
|
314
|
-
* instance-same-work
|
|
315
|
-
* this computer's rows, and the group's host too for another machine's. */
|
|
314
|
+
* instance-related-work or instance-same-work, stamped here and nowhere else (related-work.mjs `withRelatedWorkGate`):
|
|
315
|
+
* `held.cli` for this computer's rows, and the group's host too for another machine's. */
|
|
316
316
|
export function deploymentPanel(held, ws) {
|
|
317
317
|
// Another machine's panel never says who made its `error`: the key is removed here whatever the panel carried.
|
|
318
318
|
// A kept group's panel is made at the time it was read (#1124): a filtered read never makes it look newer.
|
|
319
319
|
if (ws?.remote) {
|
|
320
320
|
const { errorOrigin: _sent, ...panel } = remotePanel(ws.group, held.keptReadAt?.get?.(ws.group.id) ?? held.at);
|
|
321
|
-
const declared =
|
|
322
|
-
return { ...panel, instances: panel.instances.map((row) =>
|
|
321
|
+
const declared = relatedWorkDeclared(held.cli, ws.group);
|
|
322
|
+
return { ...panel, instances: panel.instances.map((row) => withRelatedWorkGate(row, declared)), observedAt: null, refreshing: held.remoteCollecting };
|
|
323
323
|
}
|
|
324
324
|
const observed = ws ? held.snapshot.byWs.get(ws.id) : null;
|
|
325
|
-
const declared =
|
|
326
|
-
const instances = (observed?.instances || []).map((row) =>
|
|
325
|
+
const declared = relatedWorkDeclared(held.cli);
|
|
326
|
+
const instances = (observed?.instances || []).map((row) => withRelatedWorkGate(row, declared)), kept = keptFailure(observed);
|
|
327
327
|
return {
|
|
328
328
|
workspace: ws ? { id: ws.id, name: ws.name, team: null } : null,
|
|
329
329
|
team: null,
|
|
@@ -0,0 +1,84 @@
|
|
|
1
|
+
/** Which lines a roster draws: a child's line to its parent, and the dotted link between two top-level siblings
|
|
2
|
+
* (awebai/oats#1577 for the child's line; the related-work lines for both). The one rule, shared by the Desktop's
|
|
3
|
+
* sidebar and command palette and by the TUI; no client keeps a copy. No flag, no line.
|
|
4
|
+
*
|
|
5
|
+
* What a host reports (docs/desktop-cli-api.md):
|
|
6
|
+
* - A host that declares `instance-related-work` puts `relatedWork: true` on a row whose related work is bound to
|
|
7
|
+
* its current parent (a row with a `parentInstance`), or, for a row with no parent, to its current
|
|
8
|
+
* `siblingInstance` (the root the sibling was spawned relative to, itself possibly a sibling of another root). It
|
|
9
|
+
* leaves the key out otherwise, and puts no `sameWork` on any row.
|
|
10
|
+
* - An older host, which declares only `instance-same-work`, puts `sameWork: true` on a child bound to its parent,
|
|
11
|
+
* and nothing on a sibling. Relayed through a CLI that declares `instance-related-work` (`--server`), such a
|
|
12
|
+
* host's `sameWork` arrives as `relatedWork` instead; the host's own feature list still lacks the new feature.
|
|
13
|
+
* - A host with neither feature reports no flag.
|
|
14
|
+
* The kernel has already bound the flag to the current parent or sibling: a client reads `=== true` and nothing
|
|
15
|
+
* more, and never compares names.
|
|
16
|
+
*
|
|
17
|
+
* The gate: which of the two features a row's host declares. A local row: this computer's CLI. A remote row: what
|
|
18
|
+
* this CLI relays and what the host itself lists (composed-gate.mjs `hostAdvertises`, through
|
|
19
|
+
* server-probe-features), the lesser of the two: a CLI relays only the flag it knows. Unknown is not supported: an
|
|
20
|
+
* unread or failed probe declares nothing. panel-views.mjs `deploymentPanel` stamps the gate's answer on each row
|
|
21
|
+
* it serves as `relatedWorkKnown` (`withRelatedWorkGate`), the feature's name, present only when the host declares
|
|
22
|
+
* one; it is the client's own field, never the kernel's.
|
|
23
|
+
*
|
|
24
|
+
* Pure: no DOM, no Node builtin, so a page loads it as it is. */
|
|
25
|
+
import { hostAdvertises, PROBE_FEATURES_FEATURE } from './composed-gate.mjs';
|
|
26
|
+
|
|
27
|
+
export const RELATED_WORK_FEATURE = 'instance-related-work';
|
|
28
|
+
export const SAME_WORK_FEATURE = 'instance-same-work';
|
|
29
|
+
|
|
30
|
+
const advertises = (list, feature) => Array.isArray(list) && list.includes(feature);
|
|
31
|
+
/** The feature a feature list declares, the newer first, or null. */
|
|
32
|
+
const levelOf = (has) => (has(RELATED_WORK_FEATURE) ? RELATED_WORK_FEATURE : has(SAME_WORK_FEATURE) ? SAME_WORK_FEATURE : null);
|
|
33
|
+
|
|
34
|
+
/** Which related-work feature a row's host declares: `RELATED_WORK_FEATURE`, `SAME_WORK_FEATURE` or null. `group` is
|
|
35
|
+
* null for this computer's rows, else the remote roster group the rows came from. A remote host's answer is the
|
|
36
|
+
* lesser of this CLI's (which flag it relays) and the host's own list; this CLI must also relay the hosts' lists. */
|
|
37
|
+
export function relatedWorkDeclared(cli, group = null) {
|
|
38
|
+
if (!cli?.ok || !Array.isArray(cli.features)) return null;
|
|
39
|
+
const local = levelOf((feature) => advertises(cli.features, feature));
|
|
40
|
+
if (group === null || local === null) return local;
|
|
41
|
+
if (!advertises(cli.features, PROBE_FEATURES_FEATURE)) return null;
|
|
42
|
+
const host = levelOf((feature) => hostAdvertises(group, feature));
|
|
43
|
+
return host === null ? null : local === RELATED_WORK_FEATURE ? host : SAME_WORK_FEATURE;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** A row with the gate's answer stamped: `relatedWorkKnown: <feature>` when `declared` names one of the two
|
|
47
|
+
* features, else no key. Whatever the row carried under that key is dropped first, so a host can never set it. */
|
|
48
|
+
export function withRelatedWorkGate(row, declared) {
|
|
49
|
+
const { relatedWorkKnown: _carried, ...rest } = row;
|
|
50
|
+
return declared === RELATED_WORK_FEATURE || declared === SAME_WORK_FEATURE ? { ...rest, relatedWorkKnown: declared } : rest;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
/** A row the client made itself (a pending spawn's) has no stamp: it takes its parent's, since a child is on its
|
|
54
|
+
* parent's host (instance-tree.mjs `resolveLinkId` never resolves across hosts). `parent` is the row its
|
|
55
|
+
* `parentInstance` resolves to, or null. Such a row carries no flag, so it draws no line. */
|
|
56
|
+
export const withParentGate = (row, parent) => withRelatedWorkGate(row, parent?.relatedWorkKnown);
|
|
57
|
+
|
|
58
|
+
const hasParent = (row) => typeof row?.parentInstance === 'string' && row.parentInstance !== '';
|
|
59
|
+
|
|
60
|
+
/** Whether a child draws the line to its parent: its host reports it related to its parent. On a host that
|
|
61
|
+
* declares `instance-related-work`, `relatedWork === true`; on one that declares only `instance-same-work`,
|
|
62
|
+
* `sameWork === true` (or `relatedWork === true`, as a relaying CLI turns it). Any other host: never. A root has no
|
|
63
|
+
* parent line to draw: a row without a `parentInstance` answers false. */
|
|
64
|
+
export function drawsParentLine(row) {
|
|
65
|
+
if (!hasParent(row)) return false;
|
|
66
|
+
if (row.relatedWorkKnown === RELATED_WORK_FEATURE) return row.relatedWork === true;
|
|
67
|
+
if (row.relatedWorkKnown === SAME_WORK_FEATURE) return row.sameWork === true || row.relatedWork === true;
|
|
68
|
+
return false;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** Whether a top-level row joins the sibling its `siblingInstance` names: its host declares
|
|
72
|
+
* `instance-related-work` and reports `relatedWork: true` on a row with no parent. An older host joins no sibling.
|
|
73
|
+
* Which row the link reaches, and whether it is drawn, is the tree's (instance-tree-view.mjs `treeConnectors`). */
|
|
74
|
+
export function drawsSiblingLink(row) {
|
|
75
|
+
return !hasParent(row) && row?.relatedWorkKnown === RELATED_WORK_FEATURE && row.relatedWork === true;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** Whether a row reports related work at all, to its parent or to its sibling: the words a screen reader hears. */
|
|
79
|
+
export const relatedWork = (row) => drawsParentLine(row) || drawsSiblingLink(row);
|
|
80
|
+
|
|
81
|
+
/** The order of one parent's children, a comparator for a stable sort or a first key before another: the
|
|
82
|
+
* children that draw their parent line first, then those that don't. So a parent's line ends at its last
|
|
83
|
+
* joined child and never passes a child it doesn't join. Within each part the caller's own order stands. */
|
|
84
|
+
export const drawingFirst = (a, b) => Number(!drawsParentLine(a)) - Number(!drawsParentLine(b));
|
|
@@ -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
|
-
|
|
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 = {
|
|
@@ -69,14 +70,19 @@ export function remotePanel(group, at) {
|
|
|
69
70
|
...(Object.hasOwn(i, "attributedHuman") ? { attributedHuman: attributedHumanData(i.attributedHuman) } : {}),
|
|
70
71
|
// #1247: the host's retire state, relayed unchanged when it is in the contract (retire-state.mjs), else absent.
|
|
71
72
|
...(retireData(sentRetire) ? { retire: retireData(sentRetire) } : {}),
|
|
72
|
-
//
|
|
73
|
-
// client's own field (
|
|
73
|
+
// The host's related-work flags, each true only (anything else reads unflagged). `relatedWorkKnown` is this
|
|
74
|
+
// client's own field (related-work.mjs), never a host's: whatever a host sent under it is dropped.
|
|
75
|
+
...(sentRelatedWork === true ? { relatedWork: true } : {}),
|
|
74
76
|
...(sentSameWork === true ? { sameWork: true } : {}),
|
|
75
77
|
// Feature instance-pin: the host's pin, true only (anything else reads unpinned; instance-tree.mjs rowPinned),
|
|
76
78
|
// and only from a host whose own feature list names it (composed-gate.mjs hostAdvertises: the group's
|
|
77
79
|
// probe.features, which a CLI with server-probe-features relays). The kernel relays a row's pinned whatever
|
|
78
80
|
// its host lists, so a stray field from an older host, or an unknown list, never pins a row here.
|
|
79
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) } : {}),
|
|
80
86
|
...(unsupported ? { running: null, runtimeState: "unsupported", runtimeError: unsupported } : {}),
|
|
81
87
|
};
|
|
82
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
|
}
|
|
@@ -10,7 +10,8 @@
|
|
|
10
10
|
* sync → `oats sync --dir D --json` (syncApi 1)
|
|
11
11
|
* onboard → `oats onboard DIR --workspace REF --json` (onboardApi 2)
|
|
12
12
|
* There is no package approval (packages-no-approval): declaring a package
|
|
13
|
-
* is the trust decision, so every success exits 0
|
|
13
|
+
* is the trust decision, so every success exits 0, but one: a sync whose
|
|
14
|
+
* sandbox failed exits 1 with its report (sandboxFailureReport). `--max-age` (feature
|
|
14
15
|
* observe-max-age) belongs to the three reads only and reaches argv only when
|
|
15
16
|
* the probe declares the feature; cliWorkspace drops it otherwise. */
|
|
16
17
|
import { execFile } from 'node:child_process';
|
|
@@ -97,6 +98,13 @@ export function workspaceArgv(options) {
|
|
|
97
98
|
return { argv: ['sync', '--dir', options.context, '--json'], cwd: options.context, timeout: WORKSPACE_WRITE_TIMEOUT };
|
|
98
99
|
}
|
|
99
100
|
|
|
101
|
+
/** Whether a sync's exit is its one non-zero success: exit 1 exactly, an `ok: true` answer, and a
|
|
102
|
+
* `result.sandboxes` entry whose `problems` is not empty (a failed sandbox; the lock is written). */
|
|
103
|
+
function sandboxFailureReport(options, error, document) {
|
|
104
|
+
if (options.action !== 'sync' || error?.code !== 1 || error.killed || error.signal) return false;
|
|
105
|
+
const sandboxes = document?.result?.sandboxes;
|
|
106
|
+
return Array.isArray(sandboxes) && sandboxes.some(entry => record(entry) && Array.isArray(entry.problems) && entry.problems.length > 0);
|
|
107
|
+
}
|
|
100
108
|
/** `io.exec` is a client's own `execFile` (the rule is at cli-adapter.mjs `runJson`). */
|
|
101
109
|
export function cliWorkspace(cli, options, terms, io = {}) {
|
|
102
110
|
requireTerms(terms, 'cliWorkspace');
|
|
@@ -138,7 +146,10 @@ export function cliWorkspace(cli, options, terms, io = {}) {
|
|
|
138
146
|
if (options.action === 'sync' && typeof reason.details?.why === 'string' && WHY_RE.test(reason.details.why)) out.why = reason.details.why;
|
|
139
147
|
return done({ ok: false, reason: out });
|
|
140
148
|
}
|
|
141
|
-
|
|
149
|
+
// Success is exit 0, with one exception: a sync whose sandbox failed (feature sandboxes) wrote the lock
|
|
150
|
+
// and answers its report with `ok: true` and exit 1, the failure in a sandbox entry's `problems`
|
|
151
|
+
// (docs/desktop-cli-api.md, `oats sync`). That one answer is a report; any other exit is a failure.
|
|
152
|
+
if (error && !sandboxFailureReport(options, error, document)) return fail('E_CLI_FAILED');
|
|
142
153
|
done({ ok: true, document });
|
|
143
154
|
});
|
|
144
155
|
} catch { fail('E_CLI_FAILED'); }
|
|
@@ -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 };
|