@awebai/oats 0.56.0 → 0.57.1
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 +18 -10
- package/docs/configuration.md +17 -27
- package/docs/desktop-cli-api.md +59 -3
- package/docs/desktop.md +25 -4
- package/docs/execution-targets.md +6 -1
- package/docs/implementation.md +106 -5
- package/docs/integrations.md +8 -4
- package/docs/knowledge.md +93 -38
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +12 -12
- package/docs/release-notes/v0.57.0.md +283 -0
- package/docs/release-notes/v0.57.1.md +275 -0
- package/docs/schedules.md +8 -3
- package/docs/servers.md +18 -0
- package/docs/souls-and-instances.md +126 -15
- package/docs/tui.md +333 -95
- package/docs/workspaces.md +2 -2
- package/lib/core.mjs +439 -126
- package/lib/instance-lifecycle.mjs +45 -9
- package/lib/session-viewer.mjs +29 -4
- package/lib/worktree.mjs +23 -2
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +9 -7
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +34 -0
- package/packages/client/inspect-boundary.mjs +157 -0
- package/packages/client/inspect-cache.mjs +86 -0
- package/packages/client/instance-lifecycle.mjs +10 -3
- package/packages/client/keyed-catalog.mjs +132 -0
- package/packages/client/launch-prompt-outcome.mjs +1 -1
- package/packages/client/launch-view.mjs +46 -0
- package/packages/client/session-attach.mjs +7 -5
- package/packages/client/soul-catalog.mjs +77 -0
- package/packages/client/soul-colors.mjs +31 -0
- package/packages/client/soul-facts.mjs +85 -0
- package/packages/client/soul-rows.mjs +48 -0
- package/packages/client/spawn-apply-cli.mjs +11 -6
- package/packages/client/spawn-apply.mjs +212 -0
- package/packages/client/spawn-messages.mjs +131 -85
- package/packages/client/spawn-preview-contract.mjs +3 -0
- package/packages/client/spawn-preview-facts.mjs +119 -0
- package/packages/client/spawn-preview.mjs +152 -0
- package/packages/client/spawn-transaction.mjs +136 -0
- package/packages/tui/README.md +43 -13
- package/packages/tui/lib/actions.mjs +18 -2
- package/packages/tui/lib/client.mjs +4 -0
- package/packages/tui/lib/config.mjs +9 -14
- package/packages/tui/lib/main.mjs +241 -55
- package/packages/tui/lib/model.mjs +230 -29
- package/packages/tui/lib/panel.mjs +955 -0
- package/packages/tui/lib/read.mjs +134 -24
- package/packages/tui/lib/store.mjs +184 -31
- package/packages/tui/lib/term/capture.mjs +260 -0
- package/packages/tui/lib/term/screen.mjs +44 -8
- package/packages/tui/lib/term/style.mjs +78 -6
- package/packages/tui/lib/term/text.mjs +24 -4
- package/packages/tui/lib/term/through.mjs +213 -0
- package/packages/tui/lib/term/tty.mjs +7 -60
- package/packages/tui/lib/views/act.mjs +85 -0
- package/packages/tui/lib/views/frame.mjs +153 -37
- package/packages/tui/lib/views/help.mjs +22 -14
- package/skills/oats-getting-started/SKILL.md +4 -3
- package/packages/tui/lib/open.mjs +0 -45
|
@@ -0,0 +1,212 @@
|
|
|
1
|
+
/** One client's confirmed-spawn broker across all workspaces: a client makes its own (createSpawnApplyBoundary)
|
|
2
|
+
* and owns it, and two share nothing (references, keys, the active applies, byte reservations).
|
|
3
|
+
* RAM custody only. No kernel imports, placement logic, persistent instructions,
|
|
4
|
+
* implicit retry, name-based recovery, or mutation from result/prepare.
|
|
5
|
+
*
|
|
6
|
+
* Long spawns (#802): an apply runs the CLI for the deadline its confirmed preview implies
|
|
7
|
+
* (spawnApplyDeadlineMs: 60 s, or 60 s + n × 30 min + 60 s for n `worktree` hooks). The apply
|
|
8
|
+
* request answers within ANSWER_WITHIN_MS: with the outcome if the CLI settled, else `pending`;
|
|
9
|
+
* the CLI keeps running here and `result` reads its outcome. Up to MAX_APPLIES applies run at
|
|
10
|
+
* once per boundary, one per workspace and soul. */
|
|
11
|
+
import { retainedSpawnDetails, LAUNCH_DIAGNOSTIC_BYTES, FLAG_IGNORED_BYTES } from './launch-prompt-outcome.mjs';
|
|
12
|
+
import { randomBytes } from 'node:crypto';
|
|
13
|
+
import { performance } from 'node:perf_hooks';
|
|
14
|
+
import { cliSpawnApply } from './spawn-apply-cli.mjs';
|
|
15
|
+
import { admitSpawnSelection } from './spawn-preview.mjs';
|
|
16
|
+
import { record } from './spawn-preview-contract.mjs';
|
|
17
|
+
import { spawnApplySupported, spawnApplyChoicesSupported, spawnPrepareInput, spawnRefInput, spawnPreparedData, spawnReference,
|
|
18
|
+
spawnCreationReceipt, spawnApplyFailure, spawnApplyDeadlineMs, ROLLED_BACK_CODES, WAKE_OUTCOME_UNKNOWN } from './spawn-apply-contract.mjs';
|
|
19
|
+
/** The apply request answers within this; the proxy's own 65 s timeout then never fires on a healthy spawn. */
|
|
20
|
+
export const ANSWER_WITHIN_MS = 50000;
|
|
21
|
+
export const MAX_APPLIES = 4;
|
|
22
|
+
const clone = v => structuredClone(v);
|
|
23
|
+
const byteSize = v => Buffer.byteLength(JSON.stringify(v));
|
|
24
|
+
const scopeKey = c => JSON.stringify([c?.workspace?.id, c?.workspace?.scope, c?.workspace?.remote, c?.workspace?.server,
|
|
25
|
+
c?.cli?.bin, c?.cli?.version, c?.cli?.spawnPreviewApi, c?.cli?.spawnApplyApi, c?.cli?.features, c?.cli?.harnesses, c?.cli?.sessionBackends, c?.cli?.launchOptions]);
|
|
26
|
+
/** `read` is required: the client's own preview's `prepareRead` (spawn-preview.mjs createSpawnPreview). Prepare
|
|
27
|
+
* reads through the dialog's cache: a fresh held answer for exactly these choices is the decision (no second
|
|
28
|
+
* CLI read); apply's --expect-decision is the drift guard. No held answer: a fresh read.
|
|
29
|
+
* exec optional: the client's own execFile, passed to `invoke` as `invoke(cli, options, { exec })` for every
|
|
30
|
+
* apply (cli-adapter.mjs `runJson` has the rule); without it `invoke` is given no third argument and
|
|
31
|
+
* cliSpawnApply's own default runs. An apply is a change: its options carry `detached: true`
|
|
32
|
+
* whatever exec is given, which runs it in a session of its own (as execFileInSession does). On a
|
|
33
|
+
* worktree-event kernel cliSpawnApply ends the child at the deadline through what exec returns
|
|
34
|
+
* (`child.kill`): a given exec must return the child. One that returns nothing leaves that apply
|
|
35
|
+
* unended at its deadline; there is no fallback here. On a kernel without worktree-event the options'
|
|
36
|
+
* `timeout` is the apply's only deadline: exec must honour it as execFileInSession does, killing the
|
|
37
|
+
* child when it passes and reporting `killed` even if the child then exits cleanly. */
|
|
38
|
+
export function createSpawnApplyBoundary({ read, invoke = cliSpawnApply, exec,
|
|
39
|
+
now = () => performance.now(), mint = () => randomBytes(32).toString('hex'), answerWithinMs = ANSWER_WITHIN_MS,
|
|
40
|
+
timer = (fn, ms) => { const t = setTimeout(fn, ms); return () => clearTimeout(t); } } = {}) {
|
|
41
|
+
if (typeof read !== 'function') throw new TypeError('createSpawnApplyBoundary: read (the client\'s prepareRead) is required');
|
|
42
|
+
const prepared = new Map(), submitted = new Map(), active = new Set(), io = exec ? [{ exec }] : [];
|
|
43
|
+
let preparing = 0, reservedBytes = 0;
|
|
44
|
+
const denied = (code, entry = null, status = 'unavailable', message) => spawnApplyFailure(code, { target: entry?.target, spawnRef: entry?.ref, status, message });
|
|
45
|
+
const sweep = () => { for (const map of [prepared, submitted]) for (const [ref, entry] of map) if (!entry.pending && entry.expires <= now()) map.delete(ref); };
|
|
46
|
+
const usedBytes = () => reservedBytes + [...prepared.values(), ...submitted.values()].reduce((sum, e) => sum + e.bytes, 0);
|
|
47
|
+
const freshId = () => {
|
|
48
|
+
const id = mint();
|
|
49
|
+
return spawnReference(id) && !prepared.has(id) && !submitted.has(id) && ![...submitted.values()].some(e => e.key === id) ? id : null;
|
|
50
|
+
};
|
|
51
|
+
function select(input, getContext) {
|
|
52
|
+
const c = getContext();
|
|
53
|
+
if (!spawnApplySupported(c?.cli)) return { error: 'E_APPLY_UNAVAILABLE' };
|
|
54
|
+
if (!spawnApplyChoicesSupported(c.cli, input.choices, !!input.wake)) return { error: 'E_UNSUPPORTED_OPTION' };
|
|
55
|
+
const s = admitSpawnSelection(input.selector, input.choices, c);
|
|
56
|
+
if (s.error) return s;
|
|
57
|
+
const soul = c.agents.find(a => a.name === input.selector.soul && a.agentsRoot === input.selector.agentsRoot);
|
|
58
|
+
const anchor = input.choices.relation.anchor;
|
|
59
|
+
if (soul?.captured || anchor && c.instances?.some(i => i.instance === anchor.instance && i.agentsRoot === anchor.agentsRoot && i.captured)) return { error: 'E_UNSUPPORTED_MODE' };
|
|
60
|
+
return { ...s, scope: scopeKey(c) };
|
|
61
|
+
}
|
|
62
|
+
const same = (a, b) => !b.error && a.identity === b.identity && a.scope === b.scope;
|
|
63
|
+
const ownsScope = (e, getContext) => { try { const c = getContext(); return spawnApplySupported(c?.cli) && !c.workspace?.remote && !c.workspace?.server && scopeKey(c) === e.scope; } catch { return false; } };
|
|
64
|
+
const display = (entry, status, receipt = null, reason = null, extra = {}) => ({ spawnApplyViewApi: 1, status, target: entry.target, spawnRef: entry.ref,
|
|
65
|
+
preview: entry.preview, wakeRequested: !!entry.input.wake, receipt, reason, applyWithinMs: entry.deadlineMs, ...extra });
|
|
66
|
+
async function prepare(input, getContext) {
|
|
67
|
+
const selection = select(input, getContext);
|
|
68
|
+
if (selection.error) return denied(selection.error);
|
|
69
|
+
const reservation = byteSize(input);
|
|
70
|
+
if (prepared.size + preparing >= 32 || usedBytes() + reservation > 8 * 1024 * 1024) return denied('E_BUSY');
|
|
71
|
+
preparing++; reservedBytes += reservation;
|
|
72
|
+
let observed;
|
|
73
|
+
try { observed = await read({ action: 'preview', selector: clone(input.selector), choices: clone(input.choices) }, getContext); }
|
|
74
|
+
catch { observed = { status: 'unavailable', reason: { code: 'E_CLI_FAILED' } }; }
|
|
75
|
+
finally { preparing--; reservedBytes -= reservation; }
|
|
76
|
+
const current = select(input, getContext);
|
|
77
|
+
if (!same(selection, current)) return denied('E_PLAN_CHANGED', { target: selection.target });
|
|
78
|
+
if (observed?.status !== 'available') return denied(observed?.reason?.code, { target: selection.target });
|
|
79
|
+
if (observed.data?.preflight?.status !== 'complete') return denied('E_PREFLIGHT_INCOMPLETE', { target: selection.target });
|
|
80
|
+
const preview = spawnPreparedData(observed.data, selection.target);
|
|
81
|
+
if (!preview) return denied('E_CLI_PROTOCOL', { target: selection.target });
|
|
82
|
+
if (!preview.backendStatus.installed) return denied('E_BACKEND_UNAVAILABLE', { target: selection.target });
|
|
83
|
+
const entry = { ...selection, input: clone(input), preview, ref: freshId(), key: null, expires: now() + 300000,
|
|
84
|
+
pending: false, reply: null, final: false, seenHome: false, seenBirth: null, bytes: 0, deadlineMs: spawnApplyDeadlineMs(selection.cli, preview) };
|
|
85
|
+
if (!entry.ref) return denied('E_BUSY', entry);
|
|
86
|
+
// Reserve bounded outcome storage before dispatch. A settled reply shares
|
|
87
|
+
// this immutable preview internally; public responses are always cloned.
|
|
88
|
+
// A reply keeps one of two bounded texts, never both: a retained launch's diagnostics, or the
|
|
89
|
+
// fact a receipt carries when Claude Code ignored the channel option. The larger bound covers either.
|
|
90
|
+
entry.bytes = byteSize(entry) + 3 * byteSize(preview.decision) + 2 * byteSize(entry.target) + 4096 + Math.max(LAUNCH_DIAGNOSTIC_BYTES, FLAG_IGNORED_BYTES);
|
|
91
|
+
if (usedBytes() + entry.bytes > 8 * 1024 * 1024) return denied('E_BUSY', entry);
|
|
92
|
+
prepared.set(entry.ref, entry);
|
|
93
|
+
return display(entry, 'prepared');
|
|
94
|
+
}
|
|
95
|
+
function observedGone(entry, getContext) {
|
|
96
|
+
// A prior positive observation can block retry after disappearance/replacement.
|
|
97
|
+
// Absence alone is NOT success/retirement proof and does not close a concurrent
|
|
98
|
+
// retire race. The kernel key's documented lifetime is only its surviving home.
|
|
99
|
+
const rows = getContext().instances || [];
|
|
100
|
+
const matches = rows.filter(i => i.instance === entry.preview.decision.instance && i.home === entry.preview.decision.home
|
|
101
|
+
&& i.agent === entry.input.selector.soul && i.agentsRoot === entry.input.selector.agentsRoot && !i.server && !i.remote);
|
|
102
|
+
const own = matches.length === 1 && matches[0].spawnIdempotencyKey === entry.key ? matches[0] : null;
|
|
103
|
+
if (own) {
|
|
104
|
+
const birth = typeof own.createdAt === 'string' && own.createdAt.length <= 128 ? own.createdAt : null;
|
|
105
|
+
if (entry.seenBirth !== null && entry.seenBirth !== birth) return true;
|
|
106
|
+
entry.seenHome = true; entry.seenBirth = birth; return false;
|
|
107
|
+
}
|
|
108
|
+
return entry.seenHome || matches.some(i => typeof i.spawnIdempotencyKey === 'string' && i.spawnIdempotencyKey !== entry.key);
|
|
109
|
+
}
|
|
110
|
+
function interpret(result, entry, cli) {
|
|
111
|
+
const envelope = result?.envelope;
|
|
112
|
+
if (typeof result?.started !== 'boolean' || envelope?.schemaVersion !== 1 || typeof envelope.ok !== 'boolean') return denied('E_OUTCOME_UNKNOWN', entry, 'unknown');
|
|
113
|
+
if (envelope.ok) {
|
|
114
|
+
if (!result.started) return denied('E_OUTCOME_UNKNOWN', entry, 'unknown');
|
|
115
|
+
const receipt = spawnCreationReceipt(envelope.result, { target: entry.target, preview: entry.preview, wakeRequested: !!entry.input.wake });
|
|
116
|
+
if (!receipt) return denied('E_OUTCOME_UNKNOWN', entry, 'unknown');
|
|
117
|
+
const partial = !!entry.input.wake && receipt.wake.saved !== true;
|
|
118
|
+
const reason = !partial ? null : receipt.wake.error ?? { code: 'E_WAKE_OUTCOME_UNKNOWN', message: WAKE_OUTCOME_UNKNOWN };
|
|
119
|
+
return display(entry, partial ? 'partial' : 'complete', receipt, reason);
|
|
120
|
+
}
|
|
121
|
+
const code = envelope.error?.code;
|
|
122
|
+
if (!result.started) return denied(code, entry, 'refused');
|
|
123
|
+
if (code === 'E_SPAWN_INCOMPLETE') {
|
|
124
|
+
const d = retainedSpawnDetails(envelope.error.details);
|
|
125
|
+
if (!d || d.instance !== entry.preview.decision.instance || d.home !== entry.preview.decision.home) return denied('E_OUTCOME_UNKNOWN', entry, 'unknown');
|
|
126
|
+
return { ...denied(code, entry, 'incomplete'), incomplete: d };
|
|
127
|
+
}
|
|
128
|
+
// worktree-event: the kernel rolled these back. Without the unconfirmed marker its compensation
|
|
129
|
+
// was confirmed: refused, nothing created. With it, cleanup is owed: unknown, and final (a
|
|
130
|
+
// re-apply of the same key would not finish it; retiring the quarantined home does).
|
|
131
|
+
if (ROLLED_BACK_CODES.includes(code) && cli?.features?.includes('worktree-event')) {
|
|
132
|
+
const message = envelope.error.message;
|
|
133
|
+
if (envelope.error.details?.unconfirmed === true) { entry.final = true; return denied(code, entry, 'unknown', message); }
|
|
134
|
+
return denied(code, entry, 'refused', message);
|
|
135
|
+
}
|
|
136
|
+
// A taken explicit name (spawn-name) refuses before any home is kept: the
|
|
137
|
+
// confirmation is consumed and a fresh preview reports the taken name.
|
|
138
|
+
if (['E_DECISION_STALE', 'E_IDEMPOTENCY_CONFLICT', 'E_PLACEMENT_TAKEN', 'E_INSTANCE_NAME_TAKEN'].includes(code)) return denied(code, entry, 'stale');
|
|
139
|
+
// Do not infer rollback from arbitrary kernel/hook failures. Only the
|
|
140
|
+
// explicit binding/reservation/incomplete contracts above establish scope.
|
|
141
|
+
return denied('E_OUTCOME_UNKNOWN', entry, 'unknown');
|
|
142
|
+
}
|
|
143
|
+
function get(ref, getContext) {
|
|
144
|
+
const e = submitted.get(ref) || prepared.get(ref);
|
|
145
|
+
if (!e) return { failure: denied('E_INTENT_EXPIRED') };
|
|
146
|
+
if (!ownsScope(e, getContext)) return { failure: denied('E_PLAN_CHANGED', e) };
|
|
147
|
+
return { entry: e };
|
|
148
|
+
}
|
|
149
|
+
const sameSoul = (a, b) => a.target.workspace === b.target.workspace && a.input.selector.soul === b.input.selector.soul
|
|
150
|
+
&& a.input.selector.agentsRoot === b.input.selector.agentsRoot;
|
|
151
|
+
async function apply(entry, getContext, settled) {
|
|
152
|
+
if (entry.pending) return display(entry, 'pending');
|
|
153
|
+
if (entry.reply && (entry.reply.status !== 'unknown' || entry.final)) return { ...entry.reply, repeated: true };
|
|
154
|
+
if (active.size >= MAX_APPLIES || [...active].some(e => sameSoul(e, entry)) || !submitted.has(entry.ref) && submitted.size >= 32) return denied('E_BUSY', entry);
|
|
155
|
+
const current = select(entry.input, getContext);
|
|
156
|
+
if (!same(entry, current)) return denied('E_PLAN_CHANGED', entry);
|
|
157
|
+
if (entry.key && observedGone(entry, getContext)) {
|
|
158
|
+
entry.reply = denied('E_INSTANCE_GONE', entry, 'refused'); return entry.reply;
|
|
159
|
+
}
|
|
160
|
+
const key = entry.key || freshId();
|
|
161
|
+
if (!key) return denied('E_BUSY', entry);
|
|
162
|
+
// Reserve key, slot and submitted record BEFORE any await. Key persists on
|
|
163
|
+
// this intent through unknown results; neither result nor retry can mint one.
|
|
164
|
+
entry.key = key; entry.pending = true; entry.expires = Infinity; active.add(entry);
|
|
165
|
+
prepared.delete(entry.ref); submitted.set(entry.ref, entry);
|
|
166
|
+
const run = (async () => {
|
|
167
|
+
let reply;
|
|
168
|
+
try {
|
|
169
|
+
const latest = select(entry.input, getContext);
|
|
170
|
+
if (!same(entry, latest)) reply = denied('E_PLAN_CHANGED', entry, 'refused');
|
|
171
|
+
else {
|
|
172
|
+
const result = await invoke(latest.cli, { target: clone(entry.target), choices: clone(entry.input.choices), task: entry.input.task,
|
|
173
|
+
...(entry.input.wake ? { wake: clone(entry.input.wake) } : {}), decision: clone(entry.preview.decision), key: entry.key, deadlineMs: entry.deadlineMs }, ...io);
|
|
174
|
+
reply = interpret(result, entry, latest.cli);
|
|
175
|
+
}
|
|
176
|
+
} catch { reply = denied('E_OUTCOME_UNKNOWN', entry, 'unknown'); }
|
|
177
|
+
// This result belongs to its original entry even if a view/workspace changed.
|
|
178
|
+
// The caller's current context is checked separately on both settlement paths.
|
|
179
|
+
entry.reply = reply; // internal preview sharing; every outward response is cloned
|
|
180
|
+
entry.pending = false; entry.expires = now() + 30 * 60000; active.delete(entry);
|
|
181
|
+
return reply;
|
|
182
|
+
})();
|
|
183
|
+
// Answer within answerWithinMs: the outcome, or `pending` while the CLI keeps running here.
|
|
184
|
+
let cancel = () => {};
|
|
185
|
+
const late = new Promise(resolve => { cancel = timer(() => resolve(null), answerWithinMs); });
|
|
186
|
+
const reply = await Promise.race([run, late]);
|
|
187
|
+
cancel();
|
|
188
|
+
if (!reply) {
|
|
189
|
+
void run.then(() => { try { settled?.(); } catch { /* a refresh must not lose an outcome */ } });
|
|
190
|
+
return display(entry, 'pending');
|
|
191
|
+
}
|
|
192
|
+
return ownsScope(entry, getContext) ? reply : denied('E_OUTCOME_UNKNOWN', entry, 'unknown');
|
|
193
|
+
}
|
|
194
|
+
/** `settled()` is called when an apply answered `pending` settles later (the route refreshes then). */
|
|
195
|
+
return async function spawnApplyRequest(request, getContext, { settled } = {}) {
|
|
196
|
+
try {
|
|
197
|
+
sweep();
|
|
198
|
+
if (!record(request)) return denied('E_BAD_ARGS');
|
|
199
|
+
if (request.action === 'prepare') {
|
|
200
|
+
const input = spawnPrepareInput(request);
|
|
201
|
+
return clone(input ? await prepare(input, getContext) : denied('E_BAD_ARGS'));
|
|
202
|
+
}
|
|
203
|
+
const r = spawnRefInput(request);
|
|
204
|
+
if (!r) return denied('E_BAD_ARGS');
|
|
205
|
+
const found = get(r.spawnRef, getContext);
|
|
206
|
+
if (found.failure) return clone(found.failure);
|
|
207
|
+
const e = found.entry;
|
|
208
|
+
if (r.action === 'result') return clone(e.pending ? display(e, 'pending') : e.reply || display(e, 'prepared'));
|
|
209
|
+
return clone(await apply(e, getContext, settled));
|
|
210
|
+
} catch { return denied('E_CLI_FAILED'); }
|
|
211
|
+
};
|
|
212
|
+
}
|
|
@@ -1,113 +1,128 @@
|
|
|
1
|
-
/** Plain-language wording for
|
|
1
|
+
/** Plain-language wording for a spawn's problems and outcomes, shared by every client (#855, 6b-2).
|
|
2
2
|
*
|
|
3
3
|
* The preview/apply contracts carry a stable code and a technical message
|
|
4
|
-
* (the kernel's own text for kernel refusals — paths, hashes, commands).
|
|
5
|
-
*
|
|
6
|
-
* the code and the technical message stay available
|
|
7
|
-
* troubleshooting.
|
|
4
|
+
* (the kernel's own text for kernel refusals — paths, hashes, commands). A
|
|
5
|
+
* client shows the operator what happened (`fact`) and, in its own words, what
|
|
6
|
+
* to do (`next`); the code and the technical message stay available as
|
|
7
|
+
* `detail` for troubleshooting. The Desktop's sentences are composed in
|
|
8
|
+
* packages/desktop/renderer/spawn-words.mjs. Wording only: no decision here
|
|
9
|
+
* depends on the text. */
|
|
8
10
|
import { displayLine } from './display-text.mjs';
|
|
9
11
|
import { ROLLED_BACK_CODES } from './spawn-apply-contract.mjs';
|
|
12
|
+
import { retainedSpawnMessage } from './launch-prompt-outcome.mjs';
|
|
10
13
|
|
|
11
14
|
const UNMATCHED = 'E_LAUNCH_PREFERENCE_UNMATCHED';
|
|
12
15
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
E_CHILD_SPAWNS_DISABLED: 'The parent you picked doesn’t allow child instances. Pick another one, or choose None.',
|
|
29
|
-
E_BRANCH_EXISTS: 'That branch already exists. Choose another branch in Developer settings.',
|
|
30
|
-
E_BASE_UNKNOWN: 'That base isn’t a branch, tag or commit in this soul’s repository. Check it in Developer settings.',
|
|
31
|
-
E_CLONE_MISSING: 'This soul’s repository isn’t cloned on this machine yet. Clone it, then try again — Details shows how.',
|
|
32
|
-
E_LAUNCH_ENV_MISSING: 'The chosen launch configuration can’t start on this machine. Choose another in Developer settings.',
|
|
33
|
-
E_LAUNCH_EXECUTABLE: 'The chosen launch configuration can’t start on this machine. Choose another in Developer settings.',
|
|
34
|
-
E_LAUNCH_PROBE_UNSUPPORTED: 'The chosen launch configuration can’t be checked safely. Choose another in Developer settings.',
|
|
35
|
-
E_LAUNCH_CONFIG_UNKNOWN: 'That launch configuration no longer exists. Choose another in Developer settings.',
|
|
36
|
-
// 0.52.0: the kernel refuses a spawn that names no launch configuration where the harness has several and
|
|
37
|
-
// none is the default. The sentence names the dialog's own control; the kernel's message, which ends with
|
|
38
|
-
// its command-line fix, stays in Details.
|
|
39
|
-
E_LAUNCH_CONFIG_AMBIGUOUS: 'This machine has more than one launch configuration for this soul’s harness, and none is the default. Choose one under Launch configuration in Developer settings.',
|
|
40
|
-
// 0.30 launch preferences: shown in the kernel's own words when it sends them (spawnProblem: the
|
|
41
|
-
// message, then the reason's flat `fix`), which name the harness and where it was chosen; this is the fallback.
|
|
42
|
-
E_HARNESS_UNAVAILABLE: 'The harness this soul would run isn’t installed on this machine. Install it, or pick another harness above.',
|
|
43
|
-
// 0.53.0: the kernel refuses a spawn that names no launch while `souls.launch` holds a key that names no
|
|
44
|
-
// soul. This sentence points at the controls above it and at Details, so it is read only where both are
|
|
45
|
-
// there: at the preview, with the kernel's message and fix quoted under Details (spawnProblem's `kernel`
|
|
46
|
-
// parts). Everywhere else the shorter one of SPAWN is read.
|
|
47
|
-
[UNMATCHED]: '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 above, or a launch configuration in Developer settings. To fix it for every spawn, correct the preference (Details).',
|
|
48
|
-
E_MODEL_UNKNOWN: 'That model isn’t available for this harness. Pick another model, or keep the default.',
|
|
49
|
-
E_INSTANCE_NAME_INVALID: 'Use lowercase letters, numbers and dashes, at most 64 characters, and don’t reuse a soul’s name.',
|
|
50
|
-
E_INSTANCE_NAME_TAKEN: 'An instance with this name already exists. Choose another name.',
|
|
51
|
-
E_PACKAGE_MISSING: 'A package this soul uses isn’t installed yet. Run Sync in the Workspace view.',
|
|
52
|
-
E_PACKAGE_INTEGRITY: 'A package this soul uses no longer matches the lock. Run Sync in the Workspace view.',
|
|
53
|
-
E_TARGET_CHANGED: 'The workspace changed while this was loading. Reading it again…',
|
|
54
|
-
E_PLAN_CHANGED: 'The workspace changed while this was loading. Check the values and press Spawn again.',
|
|
55
|
-
};
|
|
16
|
+
/** The act that follows a problem or an outcome, where the sentence a client shows names one (#855, 6b-2): the
|
|
17
|
+
* client says it in its own words, naming its own controls. Closed and frozen: a new code is a SURFACE change,
|
|
18
|
+
* with the TUI's lead told.
|
|
19
|
+
* change-options change an option of this spawn
|
|
20
|
+
* review-again look at the values again and confirm again
|
|
21
|
+
* check-result read the outcome again before spawning again
|
|
22
|
+
* update-oats update OATS, then try again
|
|
23
|
+
* choose-workspace choose the workspace again
|
|
24
|
+
* sync-workspace sync the workspace
|
|
25
|
+
* details the kernel's detail says more
|
|
26
|
+
* retire retire the instance to finish its cleanup
|
|
27
|
+
* view-schedules open the schedules
|
|
28
|
+
* open-from-list open the instance from the instance list */
|
|
29
|
+
export const SPAWN_NEXT = Object.freeze(['change-options', 'review-again', 'check-result', 'update-oats', 'choose-workspace',
|
|
30
|
+
'sync-workspace', 'details', 'retire', 'view-schedules', 'open-from-list']);
|
|
56
31
|
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
32
|
+
/** The shared fact of each code, and its `next` where the sentence goes on to name an act. What every client
|
|
33
|
+
* says alike stays in the fact: the instance list, syncing the workspace, "Try again.", "Pick it again.". */
|
|
34
|
+
const said = (fact, next = null) => Object.freeze({ fact, next });
|
|
35
|
+
const COMMON_FACTS = {
|
|
36
|
+
E_BAD_ARGS: said('Some of these values can’t be used.', 'change-options'),
|
|
37
|
+
E_BUSY: said('Another spawn is in progress. Try again in a moment.'),
|
|
38
|
+
E_PREVIEW_UNAVAILABLE: said('Spawning needs a newer OATS.', 'update-oats'),
|
|
39
|
+
E_APPLY_UNAVAILABLE: said('Spawning needs a newer OATS.', 'update-oats'),
|
|
40
|
+
E_WORKSPACE_UNKNOWN: said('This workspace isn’t available anymore.', 'choose-workspace'),
|
|
41
|
+
E_SOUL_UNKNOWN: said('This soul isn’t in the workspace anymore. Sync the workspace and try again.'),
|
|
42
|
+
E_SOUL_AMBIGUOUS: said('Two repositories declare a soul with this name, so it can’t be spawned until one is renamed.'),
|
|
43
|
+
E_UNSUPPORTED_MODE: said('This soul can’t be started on its own from here.'),
|
|
44
|
+
'unsupported-remote-operation': said('The execution server decides this soul’s defaults.'),
|
|
45
|
+
E_UNSUPPORTED_OPTION: said('One of the options you chose isn’t supported here. Set it back to the default and try again.'),
|
|
46
|
+
E_RELATIVE_AMBIGUOUS: said('The instance you picked for the relationship can’t be told apart from another one. Pick it again.'),
|
|
47
|
+
E_SESSION_UNKNOWN: said('The instance you picked for the relationship isn’t available anymore. Pick another one.'),
|
|
48
|
+
E_HOME_MISMATCH: said('The instance you picked for the relationship isn’t available anymore. Pick another one.'),
|
|
49
|
+
E_CHILD_SPAWNS_DISABLED: said('The parent you picked doesn’t allow child instances.', 'change-options'),
|
|
50
|
+
E_BRANCH_EXISTS: said('That branch already exists.', 'change-options'),
|
|
51
|
+
E_BASE_UNKNOWN: said('That base isn’t a branch, tag or commit in this soul’s repository.', 'change-options'),
|
|
52
|
+
E_CLONE_MISSING: said('This soul’s repository isn’t cloned on this machine yet. Clone it, then try again.', 'details'),
|
|
53
|
+
E_LAUNCH_ENV_MISSING: said('The chosen launch configuration can’t start on this machine.', 'change-options'),
|
|
54
|
+
E_LAUNCH_EXECUTABLE: said('The chosen launch configuration can’t start on this machine.', 'change-options'),
|
|
55
|
+
E_LAUNCH_PROBE_UNSUPPORTED: said('The chosen launch configuration can’t be checked safely.', 'change-options'),
|
|
56
|
+
E_LAUNCH_CONFIG_UNKNOWN: said('That launch configuration no longer exists.', 'change-options'),
|
|
57
|
+
E_LAUNCH_CONFIG_AMBIGUOUS: said('This machine has more than one launch configuration for this soul’s harness, and none is the default.', 'change-options'),
|
|
58
|
+
// The fallback, where the kernel sent no words of its own (spawnProblem quotes them, with no `next`).
|
|
59
|
+
E_HARNESS_UNAVAILABLE: said('The harness this soul would run isn’t installed on this machine.', 'change-options'),
|
|
60
|
+
// At the preview, with the kernel's message and fix as `kernel` parts: the client names its own controls.
|
|
61
|
+
[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.', 'change-options'),
|
|
62
|
+
E_MODEL_UNKNOWN: said('That model isn’t available for this harness. Pick another model, or keep the default.'),
|
|
63
|
+
E_INSTANCE_NAME_INVALID: said('Use lowercase letters, numbers and dashes, at most 64 characters, and don’t reuse a soul’s name.'),
|
|
64
|
+
E_INSTANCE_NAME_TAKEN: said('An instance with this name already exists. Choose another name.'),
|
|
65
|
+
E_PACKAGE_MISSING: said('A package this soul uses isn’t installed yet.', 'sync-workspace'),
|
|
66
|
+
E_PACKAGE_INTEGRITY: said('A package this soul uses no longer matches the lock.', 'sync-workspace'),
|
|
67
|
+
E_TARGET_CHANGED: said('The workspace changed while this was loading. Reading it again…'),
|
|
68
|
+
E_PLAN_CHANGED: said('The workspace changed while this was loading.', 'review-again'),
|
|
62
69
|
};
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
70
|
+
const PREVIEW_FACTS = {
|
|
71
|
+
E_CLI_TIMEOUT: said('OATS took too long to work out this soul’s defaults. Try again.'),
|
|
72
|
+
E_CLI_OUTPUT_LIMIT: said('OATS couldn’t work out this soul’s defaults.', 'details'),
|
|
73
|
+
E_CLI_PROTOCOL: said('OATS couldn’t work out this soul’s defaults.', 'details'),
|
|
74
|
+
E_CLI_FAILED: said('OATS couldn’t work out this soul’s defaults.', 'details'),
|
|
75
|
+
};
|
|
76
|
+
const SPAWN_FACTS = {
|
|
77
|
+
E_DECISION_STALE: said('Something changed before the spawn went through. Nothing was created.', 'review-again'),
|
|
78
|
+
E_IDEMPOTENCY_CONFLICT: said('Something changed before the spawn went through. Nothing was created.', 'review-again'),
|
|
79
|
+
E_PLACEMENT_TAKEN: said('Another spawn just took this name. Nothing was created.', 'review-again'),
|
|
80
|
+
E_INTENT_EXPIRED: said('This spawn request expired. Check the instance list before spawning again.'),
|
|
81
|
+
E_PREFLIGHT_INCOMPLETE: said('OATS couldn’t finish checking this spawn. Try again.'),
|
|
82
|
+
E_BACKEND_UNAVAILABLE: said('That session backend isn’t installed on this machine.', 'change-options'),
|
|
83
|
+
E_INSTANCE_GONE: said('The instance that was created isn’t there anymore. Check the instance list.'),
|
|
84
|
+
E_OUTCOME_UNKNOWN: said('We couldn’t confirm whether the instance was created.', 'check-result'),
|
|
85
|
+
E_SPAWN_INCOMPLETE: said('The instance was created but didn’t finish starting. Open it from the instance list instead of spawning again.'),
|
|
86
|
+
E_INPUT_PREPARATION: said('The opening instruction couldn’t be prepared, so nothing was started. Try again.'),
|
|
87
|
+
E_CLI_TIMEOUT: said('OATS took too long to answer. The instance may already exist.', 'check-result'),
|
|
88
|
+
E_CLI_OUTPUT_LIMIT: said('OATS couldn’t confirm the spawn.', 'check-result'),
|
|
89
|
+
E_CLI_PROTOCOL: said('OATS couldn’t complete the spawn.', 'details'),
|
|
90
|
+
E_CLI_FAILED: said('OATS couldn’t complete the spawn.', 'details'),
|
|
91
|
+
// Wherever nothing is above the sentence and Details hold no kernel text: the whole of it is shared.
|
|
92
|
+
[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.'),
|
|
83
93
|
};
|
|
84
94
|
|
|
85
|
-
/** {
|
|
95
|
+
/** { fact, next, code, detail } for a { code, message } reason. `stage` is 'preview'
|
|
86
96
|
* (reading defaults) or 'spawn' (after the operator pressed Spawn).
|
|
87
97
|
*
|
|
88
98
|
* For an unmatched launch preference whose reason carries the kernel's `fix`, the answer also has
|
|
89
99
|
* `kernel: { message, fix }`: the kernel's two texts, the strings as they came, for the client to quote
|
|
90
|
-
* under the kernel's name (the lead is the client's, `originLead` with its terms)
|
|
100
|
+
* under the kernel's name (the lead is the client's, `originLead` with its terms), and the fact is the
|
|
101
|
+
* sentence's lead, with the client's controls as `next`. `detail` is then the
|
|
91
102
|
* code alone, so that no reader of `detail` shows a kernel text without its speaker. A `fix` decides it
|
|
92
103
|
* because `previewFailure` keeps one only beside the kernel's own message, never beside a table's sentence:
|
|
93
104
|
* a reason without one (a press, a kernel that sent none, a message that did not travel) reads
|
|
94
|
-
* `code · message` as every other code does.
|
|
105
|
+
* `code · message` as every other code does.
|
|
106
|
+
*
|
|
107
|
+
* `fact` is what happened, in words every client shows alike, and `next` the act that follows (SPAWN_NEXT),
|
|
108
|
+
* or null where the fact says all: the client puts its own words for `next` after the fact. A code the
|
|
109
|
+
* tables do not know reads the stage's E_CLI_FAILED fact, with its own code. */
|
|
95
110
|
export function spawnProblem(reason, stage = 'preview') {
|
|
96
111
|
const code = typeof reason?.code === 'string' ? reason.code : 'E_CLI_FAILED';
|
|
97
|
-
const own = stage === 'spawn' ? SPAWN : PREVIEW;
|
|
98
112
|
const message = typeof reason?.message === 'string' ? reason.message.trim() : '';
|
|
99
113
|
// A missing harness is said as the kernel words it, with its fix (launch preferences, 0.30).
|
|
100
114
|
const fix = typeof reason?.fix === 'string' ? reason.fix.trim() : '';
|
|
101
115
|
if (code === UNMATCHED) {
|
|
102
116
|
const kernel = fix ? { message: typeof reason.message === 'string' ? reason.message : '', fix: reason.fix } : null;
|
|
103
|
-
// The
|
|
104
|
-
if (kernel) return {
|
|
105
|
-
return {
|
|
117
|
+
// The client's controls are named only where Details hold the kernel's texts.
|
|
118
|
+
if (kernel) return { ...(stage === 'preview' ? COMMON_FACTS : SPAWN_FACTS)[UNMATCHED], code, detail: code, kernel };
|
|
119
|
+
return { ...SPAWN_FACTS[UNMATCHED], code, detail: message ? `${code} · ${message}` : code };
|
|
106
120
|
}
|
|
107
121
|
// The kernel's message usually already ends with its fix: said once.
|
|
108
122
|
const kernelWords = code === 'E_HARNESS_UNAVAILABLE' && message ? (fix && !message.includes(fix) ? `${message.replace(/[.\s]+$/, '')}: ${fix}` : message) : null;
|
|
109
|
-
const
|
|
110
|
-
|
|
123
|
+
const facts = stage === 'spawn' ? SPAWN_FACTS : PREVIEW_FACTS;
|
|
124
|
+
const words = kernelWords ? said(kernelWords) : facts[code] ?? COMMON_FACTS[code] ?? facts.E_CLI_FAILED;
|
|
125
|
+
return { fact: words.fact, next: words.next, code, detail: message ? `${code} · ${message}` : code };
|
|
111
126
|
}
|
|
112
127
|
|
|
113
128
|
/** The spawn catalog's state, for the soul chooser. */
|
|
@@ -126,16 +141,47 @@ export function catalogProblem(catalog) {
|
|
|
126
141
|
export function rolledBackProblem(reason, instance) {
|
|
127
142
|
const code = reason?.code;
|
|
128
143
|
if (!ROLLED_BACK_CODES.includes(code)) return null;
|
|
129
|
-
const
|
|
144
|
+
const fact = code === 'E_INTERRUPTED'
|
|
130
145
|
? `The spawn of ${instance} was interrupted while its worktree was being set up, and was rolled back. Nothing was created.`
|
|
131
146
|
: `A capability couldn’t set up the worktree for ${instance}, so the spawn was rolled back. Nothing was created.`;
|
|
132
|
-
return {
|
|
147
|
+
return { fact, next: null, code, detail: kernelDetail(code, reason.message) };
|
|
133
148
|
}
|
|
149
|
+
/** `instance` travels with the answer: the client names it in its words for `next` (retire). */
|
|
134
150
|
export function cleanupOwedProblem(reason, instance) {
|
|
135
151
|
if (!ROLLED_BACK_CODES.includes(reason?.code)) return null;
|
|
136
|
-
return {
|
|
152
|
+
return { fact: `The spawn of ${instance} was stopped, but its cleanup didn’t finish.`, next: 'retire', instance,
|
|
137
153
|
code: reason.code, detail: kernelDetail(reason.code, reason.message) };
|
|
138
154
|
}
|
|
155
|
+
|
|
156
|
+
/** A spawn transaction's outcome in shared words (spawn-transaction.mjs `kind`), as { fact, next } for the
|
|
157
|
+
* client to say with its own words for `next`; `instance` is the name the spawn was given. null for a kind whose
|
|
158
|
+
* words are its reason's (unknown, refused: spawnProblem(outcome.reason, 'spawn')).
|
|
159
|
+
* created complete: "Created <i>." (launched), "Created <i> — not launched." (open-from-list);
|
|
160
|
+
* partial: the reason's message (view-schedules), or, for a wake whose outcome is unknown,
|
|
161
|
+
* "Agent created; wake outcome unavailable." (the boundary's message names the Desktop's
|
|
162
|
+
* Schedules: that act is view-schedules); incomplete: the retained spawn's sentence
|
|
163
|
+
* not-yet-visible created, and not in the instance list as a running session in time (open-from-list)
|
|
164
|
+
* pending-expired still running at the deadline (check-result)
|
|
165
|
+
* cleanup-owed cleanupOwedProblem's (retire); rolled-back: rolledBackProblem's
|
|
166
|
+
* never-submitted prepared, never applied (review-again)
|
|
167
|
+
* drifted the values changed since they were confirmed (review-again) */
|
|
168
|
+
export function outcomeWords(kind, view, instance) {
|
|
169
|
+
if (kind === 'created') {
|
|
170
|
+
if (view?.status === 'incomplete') return said(retainedSpawnMessage(view.incomplete));
|
|
171
|
+
if (view?.status === 'partial' && view.reason?.code === 'E_WAKE_OUTCOME_UNKNOWN') return said('Agent created; wake outcome unavailable.', 'view-schedules');
|
|
172
|
+
if (view?.status === 'partial') return said(view.reason?.message || `Created ${instance}.`, 'view-schedules');
|
|
173
|
+
return view?.receipt?.launched === false ? said(`Created ${instance} — not launched.`, 'open-from-list') : said(`Created ${instance}.`);
|
|
174
|
+
}
|
|
175
|
+
if (kind === 'not-yet-visible') return said(`Created ${instance} — not yet visible as a running session.`, 'open-from-list');
|
|
176
|
+
if (kind === 'pending-expired') return said('The spawn is still running.', 'check-result');
|
|
177
|
+
if (kind === 'cleanup-owed' || kind === 'rolled-back') {
|
|
178
|
+
const problem = (kind === 'cleanup-owed' ? cleanupOwedProblem : rolledBackProblem)(view?.reason, instance);
|
|
179
|
+
return problem ? said(problem.fact, problem.next) : null;
|
|
180
|
+
}
|
|
181
|
+
if (kind === 'never-submitted') return said('That spawn was never submitted.', 'review-again');
|
|
182
|
+
if (kind === 'drifted') return said('These values changed since you last looked.', 'review-again');
|
|
183
|
+
return null;
|
|
184
|
+
}
|
|
139
185
|
function kernelDetail(code, message) {
|
|
140
186
|
const line = displayLine(message);
|
|
141
187
|
return line ? `${code} · ${line}` : code;
|
|
@@ -180,6 +180,9 @@ export function previewChoices(v) {
|
|
|
180
180
|
}
|
|
181
181
|
return out;
|
|
182
182
|
}
|
|
183
|
+
/** The choices of a spawn with no field touched (#855, 6b-2): what a client sends before the operator changes
|
|
184
|
+
* anything (the soul's own model, no relation). A fresh object each call, for the client to change. */
|
|
185
|
+
export const defaultSpawnChoices = () => previewChoices({});
|
|
183
186
|
/** The spawn flags for admitted choices — shared by preview and apply. The
|
|
184
187
|
* harness flag is the kernel's (feature harness: --harness; a released kernel: --runtime). */
|
|
185
188
|
export function choiceArgv(choices, cli) {
|