@awebai/oats 0.51.0 → 0.52.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -0
- package/bin/oats.mjs +109 -37
- package/docs/capabilities.md +9 -2
- package/docs/configuration.md +134 -88
- package/docs/desktop-cli-api.md +927 -92
- package/docs/desktop-instance-start.md +56 -0
- package/docs/desktop.md +10 -7
- package/docs/execution-targets.md +144 -58
- package/docs/first-team.md +3 -1
- package/docs/harness-trust.md +50 -2
- package/docs/implementation.md +66 -9
- package/docs/integrations.md +9 -8
- package/docs/knowledge-reference/acceptance.md +1 -0
- package/docs/knowledge-reference/harvester.md +5 -3
- package/docs/knowledge-reference/model.md +5 -3
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +25 -2
- package/docs/launch-prompt-completion.md +50 -48
- package/docs/oats-local.schema.json +4 -3
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +15 -5
- package/docs/release-notes/v0.44.0.md +1 -1
- package/docs/release-notes/v0.52.0.md +933 -0
- package/docs/schedules.md +91 -4
- package/docs/souls-and-instances.md +95 -25
- package/docs/tui.md +152 -0
- package/docs/workspaces.md +2 -2
- package/lib/claim.mjs +186 -46
- package/lib/core.mjs +730 -185
- package/lib/errors.mjs +170 -0
- package/lib/harness-trust-write.mjs +68 -27
- package/lib/harness-trust.mjs +34 -16
- package/lib/instance-inspect.mjs +40 -11
- package/lib/instance-lifecycle.mjs +169 -47
- package/lib/launch-preference.mjs +16 -0
- package/lib/launch-prompt-completion.mjs +7 -43
- package/lib/launch-prompt-evidence.mjs +14 -7
- package/lib/launch-prompt-fixtures/README.md +86 -152
- package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
- package/lib/launch-prompt-fixtures.mjs +122 -109
- package/lib/launch-prompt-transport.mjs +2 -56
- package/lib/launch-prompts.mjs +102 -100
- package/lib/schedule-host.mjs +154 -22
- package/lib/schedule.mjs +73 -24
- package/lib/system-tools.mjs +39 -0
- package/lib/tmux-server-scope.mjs +62 -0
- package/lib/triggers.mjs +4 -4
- package/lib/workspace.mjs +5 -11
- package/lib/worktree-hooks.mjs +98 -20
- package/lib/worktree.mjs +83 -24
- package/package-catalog.json +3 -3
- package/package.json +7 -2
- package/packages/client/capability-show-contract.mjs +230 -0
- package/packages/client/capability-warnings-contract.mjs +57 -0
- package/packages/client/cli-adapter.mjs +548 -0
- package/packages/client/cli-environment.mjs +53 -0
- package/packages/client/cli-locator.mjs +253 -0
- package/packages/client/cli-probe-contract.mjs +47 -0
- package/packages/client/client-terms.mjs +60 -0
- package/packages/client/deployment-contract.mjs +68 -0
- package/packages/client/deployment-data.mjs +483 -0
- package/packages/client/deployment-facts.mjs +34 -0
- package/packages/client/deployment-label.mjs +76 -0
- package/packages/client/deployment-observer.mjs +89 -0
- package/packages/client/deployment-panel.mjs +142 -0
- package/packages/client/deployment-read-cli.mjs +53 -0
- package/packages/client/display-text.mjs +44 -0
- package/packages/client/harness-names.mjs +30 -0
- package/packages/client/inspect-contract.mjs +62 -0
- package/packages/client/instance-acts.mjs +54 -0
- package/packages/client/instance-admission.mjs +45 -0
- package/packages/client/instance-events-contract.mjs +74 -0
- package/packages/client/instance-git-contract.mjs +80 -0
- package/packages/client/instance-presentation.mjs +22 -0
- package/packages/client/instance-tree.mjs +453 -0
- package/packages/client/kernel-environment.mjs +11 -0
- package/packages/client/launch-contract.mjs +51 -0
- package/packages/client/launch-prompt-outcome.mjs +165 -0
- package/packages/client/lifecycle-cli.mjs +61 -0
- package/packages/client/lifecycle-contract.mjs +372 -0
- package/packages/client/liveness-main.mjs +10 -0
- package/packages/client/liveness.mjs +35 -0
- package/packages/client/machine-contract.mjs +123 -0
- package/packages/client/own-environment.mjs +22 -0
- package/packages/client/panel-views.mjs +286 -0
- package/packages/client/readiness-contract.mjs +172 -0
- package/packages/client/refresh-loop.mjs +52 -0
- package/packages/client/remote-address.mjs +126 -0
- package/packages/client/remote-roster.mjs +67 -0
- package/packages/client/roster-sections.mjs +80 -0
- package/packages/client/spawn-apply-cli.mjs +104 -0
- package/packages/client/spawn-apply-contract.mjs +183 -0
- package/packages/client/spawn-decision.mjs +46 -0
- package/packages/client/spawn-messages.mjs +119 -0
- package/packages/client/spawn-preview-cli.mjs +32 -0
- package/packages/client/spawn-preview-contract.mjs +314 -0
- package/packages/client/team-members.mjs +41 -0
- package/packages/client/team-rows.mjs +45 -0
- package/packages/client/terminal-contract.mjs +57 -0
- package/packages/client/tmux-status.mjs +66 -0
- package/packages/client/waiting-on-you.mjs +88 -0
- package/packages/client/workspace-admission.mjs +45 -0
- package/packages/client/workspace-cli.mjs +142 -0
- package/packages/client/workspace-views.mjs +147 -0
- package/packages/tui/README.md +46 -0
- package/packages/tui/bin/tui.mjs +7 -0
- package/packages/tui/lib/actions.mjs +29 -0
- package/packages/tui/lib/client.mjs +4 -0
- package/packages/tui/lib/main.mjs +105 -0
- package/packages/tui/lib/term/keys.mjs +323 -0
- package/packages/tui/lib/term/screen.mjs +122 -0
- package/packages/tui/lib/term/style.mjs +43 -0
- package/packages/tui/lib/term/text.mjs +49 -0
- package/packages/tui/lib/term/tty.mjs +168 -0
- package/packages/tui/lib/term/width.mjs +124 -0
- package/packages/tui/lib/views/frame.mjs +62 -0
- package/packages/tui/lib/views/help.mjs +28 -0
- package/packages/tui/package.json +8 -0
- package/skills/oats-getting-started/SKILL.md +29 -22
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
- package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
- package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
- package/lib/launch-prompt-policy.mjs +0 -87
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
/** Confirmed K6d input/data boundary. No kernel resolution or renderer key authority. */
|
|
2
|
+
import { retainedSpawnDetails } from './launch-prompt-outcome.mjs';
|
|
3
|
+
import { harnessOf } from './harness-names.mjs';
|
|
4
|
+
import { record, previewSupported, previewSelector, previewChoices, previewTarget, previewData, previewFailure, MAX_HOOKS } from './spawn-preview-contract.mjs';
|
|
5
|
+
import { spawnDecision, sameSpawnDecision } from './spawn-decision.mjs';
|
|
6
|
+
const exact = (v, keys) => record(v) && Object.keys(v).every(k => keys.includes(k));
|
|
7
|
+
const bytes = v => new TextEncoder().encode(v).byteLength;
|
|
8
|
+
function fits(v, max) { try { return bytes(JSON.stringify(v)) <= max; } catch { return false; } }
|
|
9
|
+
const text = (v, max) => typeof v === 'string' && !v.includes('\0') && bytes(v) <= max;
|
|
10
|
+
export const WAKE_OUTCOME_UNKNOWN = 'Agent created; wake outcome unavailable — check Schedules';
|
|
11
|
+
export const spawnReference = v => typeof v === 'string' && /^[a-f0-9]{64}$/.test(v);
|
|
12
|
+
export const spawnApplySupported = cli => previewSupported(cli) && cli.spawnApplyApi === 1
|
|
13
|
+
&& cli.features.length <= 128 && cli.features.every(f => typeof f === 'string')
|
|
14
|
+
&& cli.features.includes('spawn-apply-2') && cli.features.includes('spawn-idempotency-2');
|
|
15
|
+
/** The apply's CLI deadline. 60 s, unless the CLI declares feature worktree-event and the confirmed
|
|
16
|
+
* preview runs n > 0 `worktree` hooks: the kernel bounds each at 30 minutes, so 60 s + n × 30 min + 60 s.
|
|
17
|
+
* Derived from the preview the operator confirmed, never reread. */
|
|
18
|
+
export const SPAWN_APPLY_MS = 60000;
|
|
19
|
+
export const WORKTREE_HOOK_MS = 30 * 60000;
|
|
20
|
+
export function spawnApplyDeadlineMs(cli, preview) {
|
|
21
|
+
const n = Array.isArray(cli?.features) && cli.features.includes('worktree-event') && Array.isArray(preview?.worktreeHooks) ? preview.worktreeHooks.length : 0;
|
|
22
|
+
return n > 0 ? SPAWN_APPLY_MS + n * WORKTREE_HOOK_MS + SPAWN_APPLY_MS : SPAWN_APPLY_MS;
|
|
23
|
+
}
|
|
24
|
+
/** Whether a deadline is one spawnApplyDeadlineMs can produce (at most MAX_HOOKS hooks). */
|
|
25
|
+
export const spawnApplyDeadline = v => v === SPAWN_APPLY_MS
|
|
26
|
+
|| Number.isSafeInteger(v) && v > 2 * SPAWN_APPLY_MS && (v - 2 * SPAWN_APPLY_MS) % WORKTREE_HOOK_MS === 0 && (v - 2 * SPAWN_APPLY_MS) / WORKTREE_HOOK_MS <= MAX_HOOKS;
|
|
27
|
+
export function spawnApplyChoicesSupported(cli, choices, wakeRequested = false) {
|
|
28
|
+
const has = (values, value) => Array.isArray(values) && values.includes(value);
|
|
29
|
+
return !!choices && (!choices.harness || has(cli?.harnesses, choices.harness))
|
|
30
|
+
&& (!choices.backend || has(cli?.sessionBackends, choices.backend))
|
|
31
|
+
&& (choices.yolo === undefined || has(cli?.launchOptions, 'yolo'))
|
|
32
|
+
&& (!choices.launchConfig || has(cli?.features, 'launch-config'))
|
|
33
|
+
&& (!wakeRequested || has(cli?.features, 'schedule'))
|
|
34
|
+
&& (choices.name === undefined || has(cli?.features, 'spawn-name'))
|
|
35
|
+
&& (choices.identity === undefined || has(cli?.features, 'spawn-provider-payload'));
|
|
36
|
+
}
|
|
37
|
+
export function spawnWake(v) {
|
|
38
|
+
if (!exact(v, ['cron', 'tz', 'message', 'enabled']) || !text(v.cron, 256) || !v.cron.trim()
|
|
39
|
+
|| !text(v.tz, 128) || !v.tz.trim() || /[\x00-\x1f\x7f]/.test(v.cron + v.tz)
|
|
40
|
+
|| !text(v.message, 8192) || !v.message.trim() || v.enabled !== undefined && typeof v.enabled !== 'boolean') return null;
|
|
41
|
+
return { cron: v.cron, tz: v.tz, message: v.message, enabled: v.enabled ?? true };
|
|
42
|
+
}
|
|
43
|
+
export function spawnPrepareInput(v) {
|
|
44
|
+
if (!exact(v, ['action', 'selector', 'choices', 'task', 'wake']) || v.action !== 'prepare' || !fits(v, 65536)) return null;
|
|
45
|
+
const selector = previewSelector(v.selector), choices = previewChoices(v.choices);
|
|
46
|
+
const task = v.task === undefined ? '' : v.task;
|
|
47
|
+
if (!selector || !choices || !text(task, 32768) || !fits({ selector, choices }, 16384)) return null;
|
|
48
|
+
const wake = Object.hasOwn(v, 'wake') ? spawnWake(v.wake) : undefined;
|
|
49
|
+
if (wake === null) return null;
|
|
50
|
+
return { action: 'prepare', selector, choices, task, ...(wake ? { wake } : {}) };
|
|
51
|
+
}
|
|
52
|
+
export function spawnRefInput(v) {
|
|
53
|
+
return exact(v, ['action', 'spawnRef']) && ['apply', 'result'].includes(v.action) && spawnReference(v.spawnRef)
|
|
54
|
+
? { action: v.action, spawnRef: v.spawnRef } : null;
|
|
55
|
+
}
|
|
56
|
+
/** A READ success alone never creates an executable confirmation. */
|
|
57
|
+
export function spawnPreparedData(v, target) {
|
|
58
|
+
const data = previewData(v, target);
|
|
59
|
+
return data && spawnDecision(data.decision, { effectiveRequired: true }) && data.work !== 'attached'
|
|
60
|
+
&& data.preflight.status === 'complete' ? data : null;
|
|
61
|
+
}
|
|
62
|
+
export function spawnWakeOutcome(value, requested) {
|
|
63
|
+
if (value === undefined) return { requested: null, saved: null, error: null };
|
|
64
|
+
if (!record(value) || ![null, true, false].includes(value.requested) || ![null, true, false].includes(value.saved)
|
|
65
|
+
|| value.requested !== null && value.requested !== requested
|
|
66
|
+
|| value.requested !== true && value.saved !== null) return null;
|
|
67
|
+
let error = null;
|
|
68
|
+
if (value.error !== null) {
|
|
69
|
+
if (!record(value.error) || typeof value.error.code !== 'string' || !value.error.code || value.error.code.length > 128 || value.saved !== false) return null;
|
|
70
|
+
// Wake errors may contain task/credential/provider text. Only the reported
|
|
71
|
+
// failure fact crosses; neither raw message nor an arbitrary code is UI text.
|
|
72
|
+
error = { code: 'E_WAKE_SAVE_FAILED', message: 'The agent was created, but its wake schedule was not saved.' };
|
|
73
|
+
}
|
|
74
|
+
if (value.saved === false && !error) return null;
|
|
75
|
+
return { requested: value.requested, saved: value.saved, error };
|
|
76
|
+
}
|
|
77
|
+
/** A qualified creation receipt, not executable terminal/session instructions. */
|
|
78
|
+
export function spawnCreationReceipt(v, { target, preview, wakeRequested = false } = {}) {
|
|
79
|
+
const selected = previewTarget(target), expected = spawnDecision(preview?.decision, { effectiveRequired: true });
|
|
80
|
+
const decision = spawnDecision(v?.decision, { effectiveRequired: true });
|
|
81
|
+
if (!selected || !expected || !record(v) || !sameSpawnDecision(expected, decision)
|
|
82
|
+
|| v.agent !== selected.selector.soul || v.instance !== expected.instance || v.home !== expected.home
|
|
83
|
+
|| v.branch !== expected.branch || v.repo !== expected.effective.repo || v.work !== expected.effective.work
|
|
84
|
+
|| harnessOf(v) !== expected.effective.harness || v.model !== expected.effective.model
|
|
85
|
+
|| typeof v.launched !== 'boolean' || typeof v.replayed !== 'boolean'
|
|
86
|
+
|| v.yolo !== undefined && v.yolo !== expected.effective.yolo
|
|
87
|
+
|| !Array.isArray(v.warnings) || v.warnings.length > 512 || !v.warnings.every(w => typeof w === 'string' && w.length <= 4096)) return null;
|
|
88
|
+
let wake = spawnWakeOutcome(v.wake, wakeRequested);
|
|
89
|
+
// Older first-response compatibility: the CLI may have saved the wake outcome
|
|
90
|
+
// but failed to record it in the home. A reported save failure is still known.
|
|
91
|
+
if (v.wake === undefined && v.wakeScheduleError !== undefined) {
|
|
92
|
+
if (!wakeRequested) return null;
|
|
93
|
+
wake = spawnWakeOutcome({ requested: true, saved: false, error: v.wakeScheduleError }, true);
|
|
94
|
+
}
|
|
95
|
+
if (!wake) return null;
|
|
96
|
+
return { instance: v.instance, agent: v.agent, home: v.home, agentsRoot: selected.selector.agentsRoot,
|
|
97
|
+
workspace: selected.workspace, server: null, repo: v.repo, work: v.work, branch: v.branch,
|
|
98
|
+
harness: harnessOf(v), model: v.model, launched: v.launched, replayed: v.replayed, decision,
|
|
99
|
+
warningCount: v.warnings.length, wake };
|
|
100
|
+
}
|
|
101
|
+
/** Project the Desktop HTTP view again at the main/renderer trust boundaries. */
|
|
102
|
+
export function spawnApplyView(v, expected = {}) {
|
|
103
|
+
if (!record(v) || v.spawnApplyViewApi !== 1) return null;
|
|
104
|
+
const target = v.target === null ? null : previewTarget(v.target);
|
|
105
|
+
if (v.target !== null && !target || target && expected.workspace && target.workspace !== expected.workspace
|
|
106
|
+
|| target && expected.selector && (target.selector.soul !== expected.selector.soul || target.selector.agentsRoot !== expected.selector.agentsRoot)
|
|
107
|
+
|| v.spawnRef !== null && !spawnReference(v.spawnRef) || expected.ref && v.spawnRef !== null && v.spawnRef !== expected.ref) return null;
|
|
108
|
+
if (['unavailable', 'refused', 'unknown', 'stale', 'incomplete'].includes(v.status)) {
|
|
109
|
+
const out = spawnApplyFailure(v.reason?.code, { target, spawnRef: v.spawnRef, status: v.status, message: v.reason?.message });
|
|
110
|
+
if (v.status === 'incomplete') {
|
|
111
|
+
const incomplete = retainedSpawnDetails(v.incomplete);
|
|
112
|
+
if (v.reason?.code !== 'E_SPAWN_INCOMPLETE' || !target || !incomplete) return null;
|
|
113
|
+
out.incomplete = incomplete;
|
|
114
|
+
}
|
|
115
|
+
return out;
|
|
116
|
+
}
|
|
117
|
+
if (!['prepared', 'pending', 'complete', 'partial'].includes(v.status) || !target || !spawnReference(v.spawnRef)
|
|
118
|
+
|| typeof v.wakeRequested !== 'boolean') return null;
|
|
119
|
+
const preview = spawnPreparedData(v.preview, target);
|
|
120
|
+
if (!preview || !preview.backendStatus.installed) return null;
|
|
121
|
+
let receipt = null, reason = null;
|
|
122
|
+
if (['complete', 'partial'].includes(v.status)) {
|
|
123
|
+
if (!record(v.receipt) || !Number.isInteger(v.receipt.warningCount) || v.receipt.warningCount < 0 || v.receipt.warningCount > 512
|
|
124
|
+
|| v.receipt.workspace !== target.workspace || v.receipt.agentsRoot !== target.selector.agentsRoot || v.receipt.server !== null) return null;
|
|
125
|
+
receipt = spawnCreationReceipt({ ...v.receipt, warnings: Array(v.receipt.warningCount).fill('') }, { target, preview, wakeRequested: v.wakeRequested });
|
|
126
|
+
if (!receipt) return null;
|
|
127
|
+
const partial = v.wakeRequested && receipt.wake.saved !== true;
|
|
128
|
+
if ((v.status === 'partial') !== partial) return null;
|
|
129
|
+
if (partial) reason = receipt.wake.error ?? { code: 'E_WAKE_OUTCOME_UNKNOWN', message: WAKE_OUTCOME_UNKNOWN };
|
|
130
|
+
}
|
|
131
|
+
// The CLI deadline the broker set from this preview (spawnApplyDeadlineMs): the renderer follows a
|
|
132
|
+
// `pending` apply for this long (plus a margin). Absent from an older backend.
|
|
133
|
+
const applyWithinMs = spawnApplyDeadline(v.applyWithinMs) ? v.applyWithinMs : undefined;
|
|
134
|
+
return { spawnApplyViewApi: 1, status: v.status, target, spawnRef: v.spawnRef, preview, wakeRequested: v.wakeRequested,
|
|
135
|
+
receipt, reason, ...(applyWithinMs ? { applyWithinMs } : {}), ...(v.repeated === true ? { repeated: true } : {}) };
|
|
136
|
+
}
|
|
137
|
+
const errors = {
|
|
138
|
+
E_APPLY_UNAVAILABLE: 'Confirmed spawn requires preview API 2, apply API 1 and advertised spawn-preview-2, spawn-apply-2 and spawn-idempotency-2.',
|
|
139
|
+
E_BAD_ARGS: 'Provide one qualified spawn draft, or only its server-owned confirmation reference.',
|
|
140
|
+
E_PLAN_REQUIRED: 'Review this local spawn and explicitly confirm the server-owned decision.',
|
|
141
|
+
E_PLAN_CHANGED: 'The workspace, soul, anchor or CLI changed. Review a new confirmation.',
|
|
142
|
+
E_INTENT_EXPIRED: 'This confirmation is unavailable. A lost submitted intent does not prove that nothing happened; check the roster before reviewing another spawn.',
|
|
143
|
+
E_BUSY: 'The bounded spawn transaction capacity is in use. Wait for the current operation.',
|
|
144
|
+
E_PREFLIGHT_INCOMPLETE: 'The preview preflight did not complete. It is not an executable confirmation.',
|
|
145
|
+
E_BACKEND_UNAVAILABLE: 'The preview reports that the selected backend is not installed. Observe a new preview after it is available.',
|
|
146
|
+
E_INSTANCE_GONE: 'The previously observed confirmed instance is no longer present. Inspect the roster; this is not an automatic spawn retry.',
|
|
147
|
+
E_DECISION_STALE: 'The confirmed decision changed. Review a fresh preview and explicitly confirm again.',
|
|
148
|
+
E_IDEMPOTENCY_CONFLICT: 'This confirmation key belongs to a different recorded decision. Review a new confirmation; do not retry with a replacement key.',
|
|
149
|
+
E_PLACEMENT_TAKEN: 'Another spawn reserved the confirmed home. Review a new preview before confirming again.',
|
|
150
|
+
// spawn-name: explicit names are unique across the deployment; a taken name is never suffixed.
|
|
151
|
+
E_INSTANCE_NAME_TAKEN: 'Another instance took the confirmed name. Review a new preview before confirming again.',
|
|
152
|
+
E_OUTCOME_UNKNOWN: 'The spawn outcome is unknown. Check this same confirmation; never create a replacement key to retry it.',
|
|
153
|
+
E_SPAWN_INCOMPLETE: 'The confirmed home exists but spawn completion is unconfirmed. Inspect its existing session; do not spawn another instance to recover it.',
|
|
154
|
+
E_FORBIDDEN_FRAME: 'This frame cannot use spawn transactions.',
|
|
155
|
+
E_CLI_PROTOCOL: 'The CLI returned an invalid or mismatched confirmed-spawn result.',
|
|
156
|
+
E_CLI_FAILED: 'The installed CLI could not complete the confirmed-spawn request.',
|
|
157
|
+
E_CLI_TIMEOUT: 'The spawn command timed out. Creation may already have happened; do not start a new confirmation to retry it.',
|
|
158
|
+
E_CLI_OUTPUT_LIMIT: 'The spawn command exceeded its output limit. Its creation outcome is unconfirmed.',
|
|
159
|
+
E_INPUT_PREPARATION: 'Private spawn instruction files could not be prepared; no CLI was invoked.',
|
|
160
|
+
E_INTERRUPTED: 'The spawn was interrupted while its worktree hooks ran.',
|
|
161
|
+
E_REQUIRED_HOOK_FAILED: 'A required worktree hook failed.',
|
|
162
|
+
E_HOOK_ENVIRONMENT_CONTRACT: 'A worktree hook broke the hook environment contract.',
|
|
163
|
+
};
|
|
164
|
+
/** Feature worktree-event: a dispatched spawn failure with one of these codes and no
|
|
165
|
+
* `details.unconfirmed: true` was rolled back by the kernel (confirmed compensation): nothing
|
|
166
|
+
* was created. With the marker its cleanup is owed. Only these three; every other code keeps
|
|
167
|
+
* the unknown-unless-proven rule. */
|
|
168
|
+
export const ROLLED_BACK_CODES = ['E_INTERRUPTED', 'E_REQUIRED_HOOK_FAILED', 'E_HOOK_ENVIRONMENT_CONTRACT'];
|
|
169
|
+
/** The kernel's message travels only for ROLLED_BACK_CODES (it names the capability and its log);
|
|
170
|
+
* bounded here, and shown through displayLine. */
|
|
171
|
+
const kernelText = v => typeof v === 'string' && !!v.trim() && v.length <= 4096 && !v.includes('\0');
|
|
172
|
+
export function spawnApplyReason(code, kernelMessage) {
|
|
173
|
+
if (typeof code !== 'string') code = 'E_CLI_FAILED';
|
|
174
|
+
if (ROLLED_BACK_CODES.includes(code)) return { code, message: kernelText(kernelMessage) ? kernelMessage : errors[code] };
|
|
175
|
+
if (Object.hasOwn(errors, code)) return { code, message: errors[code] };
|
|
176
|
+
const reason = previewFailure(code).reason;
|
|
177
|
+
return reason.code === code && code !== 'E_CLI_FAILED' ? reason : { code: 'E_CLI_FAILED', message: errors.E_CLI_FAILED };
|
|
178
|
+
}
|
|
179
|
+
export function spawnApplyFailure(code, { target = null, spawnRef = null, status = 'unavailable', message } = {}) {
|
|
180
|
+
return { spawnApplyViewApi: 1, status: ['unavailable', 'unknown', 'refused', 'stale', 'incomplete'].includes(status) ? status : 'unavailable',
|
|
181
|
+
target: previewTarget(target), spawnRef: spawnReference(spawnRef) ? spawnRef : null,
|
|
182
|
+
preview: null, receipt: null, reason: spawnApplyReason(code, message) };
|
|
183
|
+
}
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
/** Producer-owned K6 decision data. Never compute revisions or derive argv from it. */
|
|
2
|
+
import { absolute, record } from './readiness-contract.mjs';
|
|
3
|
+
import { harnessOf, HARNESSES } from './harness-names.mjs';
|
|
4
|
+
const name = v => typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/.test(v);
|
|
5
|
+
const safe = v => typeof v === 'string' && v.length <= 4096
|
|
6
|
+
&& !/[\x00-\x1f\x7f]|https?:\/\/[^/\s]*@|(?:gh[pousr]_|github_pat_)[A-Za-z0-9_]{16,}/.test(v);
|
|
7
|
+
const nullable = v => v === null || safe(v);
|
|
8
|
+
export function spawnEffective(v) {
|
|
9
|
+
if (!record(v) || !absolute(v.repo) || !['worktree', 'checkout', 'directory', 'workspace', 'attached'].includes(v.work)
|
|
10
|
+
|| !HARNESSES.includes(harnessOf(v)) || !nullable(v.model) || !nullable(v.launchConfig)
|
|
11
|
+
|| v.yolo !== null && typeof v.yolo !== 'boolean' || v.backend !== 'tmux'
|
|
12
|
+
|| typeof v.childSpawns !== 'boolean') return null;
|
|
13
|
+
let relation = null;
|
|
14
|
+
if (v.relation !== null) {
|
|
15
|
+
const r = v.relation, a = r?.anchor;
|
|
16
|
+
if (!record(r) || !['child', 'sibling', 'parent'].includes(r.kind) || !record(a)
|
|
17
|
+
|| !name(a.instance) || !absolute(a.agentsRoot)) return null;
|
|
18
|
+
relation = { kind: r.kind, anchor: { instance: a.instance, agentsRoot: a.agentsRoot } };
|
|
19
|
+
}
|
|
20
|
+
return { repo: v.repo, work: v.work, harness: harnessOf(v), model: v.model, launchConfig: v.launchConfig,
|
|
21
|
+
yolo: v.yolo, backend: v.backend, childSpawns: v.childSpawns, relation };
|
|
22
|
+
}
|
|
23
|
+
export function spawnDecision(v, { effectiveRequired = false } = {}) {
|
|
24
|
+
if (!record(v) || !name(v.instance) || !absolute(v.home) || !nullable(v.branch)
|
|
25
|
+
|| typeof v.revision !== 'string' || !/^[a-f0-9]{24}$/.test(v.revision)) return null;
|
|
26
|
+
let base = null;
|
|
27
|
+
if (v.base !== null) {
|
|
28
|
+
if (!record(v.base) || !safe(v.base.ref) || !v.base.ref || typeof v.base.oid !== 'string'
|
|
29
|
+
|| !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(v.base.oid)) return null;
|
|
30
|
+
base = { ref: v.base.ref, oid: v.base.oid };
|
|
31
|
+
}
|
|
32
|
+
const hasEffective = Object.hasOwn(v, 'effective');
|
|
33
|
+
const effective = hasEffective ? spawnEffective(v.effective) : null;
|
|
34
|
+
if (hasEffective && !effective || effectiveRequired && !effective) return null;
|
|
35
|
+
if (effective && (effective.work === 'worktree' ? !v.branch || !base : v.branch !== null || base !== null)) return null;
|
|
36
|
+
// The workspace resolution the decision binds (a member that moved between
|
|
37
|
+
// preview and apply is E_DECISION_STALE); absent only before workspace v2.
|
|
38
|
+
if (Object.hasOwn(v, 'resolution') && (typeof v.resolution !== 'string' || !/^[a-f0-9]{24}$/.test(v.resolution))) return null;
|
|
39
|
+
return { instance: v.instance, home: v.home, branch: v.branch, base,
|
|
40
|
+
...(hasEffective ? { effective } : {}), ...(Object.hasOwn(v, 'resolution') ? { resolution: v.resolution } : {}), revision: v.revision };
|
|
41
|
+
}
|
|
42
|
+
/** Equality of projected strong decisions, not an attempt to recompute their hash. */
|
|
43
|
+
export function sameSpawnDecision(a, b) {
|
|
44
|
+
const left = spawnDecision(a, { effectiveRequired: true }), right = spawnDecision(b, { effectiveRequired: true });
|
|
45
|
+
return !!left && !!right && JSON.stringify(left) === JSON.stringify(right);
|
|
46
|
+
}
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
/** Plain-language wording for the Spawn dialog's problems.
|
|
2
|
+
*
|
|
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). The
|
|
5
|
+
* dialog shows the operator one sentence about what happened and what to do;
|
|
6
|
+
* the code and the technical message stay available behind "Details" for
|
|
7
|
+
* troubleshooting. Wording only: no decision here depends on the text. */
|
|
8
|
+
import { displayLine } from './display-text.mjs';
|
|
9
|
+
import { ROLLED_BACK_CODES } from './spawn-apply-contract.mjs';
|
|
10
|
+
|
|
11
|
+
const COMMON = {
|
|
12
|
+
E_BAD_ARGS: 'Some of these values can’t be used. Check the name and Developer settings.',
|
|
13
|
+
E_BUSY: 'Another spawn is in progress. Try again in a moment.',
|
|
14
|
+
E_FORBIDDEN_FRAME: 'This window can’t start a spawn.',
|
|
15
|
+
E_PREVIEW_UNAVAILABLE: 'Spawning needs a newer OATS. Update OATS, then open this dialog again.',
|
|
16
|
+
E_APPLY_UNAVAILABLE: 'Spawning needs a newer OATS. Update OATS, then open this dialog again.',
|
|
17
|
+
E_WORKSPACE_UNKNOWN: 'This workspace isn’t available anymore. Choose it again from the workspace menu.',
|
|
18
|
+
E_SOUL_UNKNOWN: 'This soul isn’t in the workspace anymore. Sync the workspace and try again.',
|
|
19
|
+
E_SOUL_AMBIGUOUS: 'Two repositories declare a soul with this name, so it can’t be spawned until one is renamed.',
|
|
20
|
+
E_UNSUPPORTED_MODE: 'This soul can’t be started on its own from here.',
|
|
21
|
+
'unsupported-remote-operation': 'The execution server decides this soul’s defaults.',
|
|
22
|
+
E_UNSUPPORTED_OPTION: 'One of the options you chose isn’t supported here. Set it back to the default and try again.',
|
|
23
|
+
E_RELATIVE_AMBIGUOUS: 'The instance you picked for the relationship can’t be told apart from another one. Pick it again.',
|
|
24
|
+
E_SESSION_UNKNOWN: 'The instance you picked for the relationship isn’t available anymore. Pick another one.',
|
|
25
|
+
E_HOME_MISMATCH: 'The instance you picked for the relationship isn’t available anymore. Pick another one.',
|
|
26
|
+
E_CHILD_SPAWNS_DISABLED: 'The parent you picked doesn’t allow child instances. Pick another one, or choose None.',
|
|
27
|
+
E_BRANCH_EXISTS: 'That branch already exists. Choose another branch in Developer settings.',
|
|
28
|
+
E_BASE_UNKNOWN: 'That base isn’t a branch, tag or commit in this soul’s repository. Check it in Developer settings.',
|
|
29
|
+
E_CLONE_MISSING: 'This soul’s repository isn’t cloned on this machine yet. Clone it, then try again — Details shows how.',
|
|
30
|
+
E_REQUIREMENT_INACTIVE: 'Something this soul needs isn’t set up yet. Check the soul in the Workspace view.',
|
|
31
|
+
E_LAUNCH_ENV_MISSING: 'The chosen launch configuration can’t start on this machine. Choose another in Developer settings.',
|
|
32
|
+
E_LAUNCH_EXECUTABLE: 'The chosen launch configuration can’t start on this machine. Choose another in Developer settings.',
|
|
33
|
+
E_LAUNCH_PROBE_UNSUPPORTED: 'The chosen launch configuration can’t be checked safely. Choose another in Developer settings.',
|
|
34
|
+
E_LAUNCH_CONFIG_UNKNOWN: 'That launch configuration no longer exists. Choose another in Developer settings.',
|
|
35
|
+
// 0.52.0: the kernel refuses a spawn that names no launch configuration where the harness has several and
|
|
36
|
+
// none is the default. The sentence names the dialog's own control; the kernel's message, which ends with
|
|
37
|
+
// its command-line fix, stays in Details.
|
|
38
|
+
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.',
|
|
39
|
+
// 0.30 launch preferences: shown in the kernel's own words when it sends them (spawnProblem: the
|
|
40
|
+
// message, then the reason's flat `fix`), which name the harness and where it was chosen; this is the fallback.
|
|
41
|
+
E_HARNESS_UNAVAILABLE: 'The harness this soul would run isn’t installed on this machine. Install it, or pick another harness above.',
|
|
42
|
+
E_MODEL_UNKNOWN: 'That model isn’t available for this harness. Pick another model, or keep the default.',
|
|
43
|
+
E_INSTANCE_NAME_INVALID: 'Use lowercase letters, numbers and dashes, at most 64 characters, and don’t reuse a soul’s name.',
|
|
44
|
+
E_INSTANCE_NAME_TAKEN: 'An instance with this name already exists. Choose another name.',
|
|
45
|
+
E_PACKAGE_MISSING: 'A package this soul uses isn’t installed yet. Run Sync in the Workspace view.',
|
|
46
|
+
E_PACKAGE_INTEGRITY: 'A package this soul uses no longer matches the lock. Run Sync in the Workspace view.',
|
|
47
|
+
E_TARGET_CHANGED: 'The workspace changed while this was loading. Reading it again…',
|
|
48
|
+
E_PLAN_CHANGED: 'The workspace changed while this was loading. Check the values and press Spawn again.',
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
const PREVIEW = {
|
|
52
|
+
E_CLI_TIMEOUT: 'OATS took too long to work out this soul’s defaults. Try again.',
|
|
53
|
+
E_CLI_OUTPUT_LIMIT: 'OATS couldn’t work out this soul’s defaults. Try again, or see Details.',
|
|
54
|
+
E_CLI_PROTOCOL: 'OATS couldn’t work out this soul’s defaults. Try again, or see Details.',
|
|
55
|
+
E_CLI_FAILED: 'OATS couldn’t work out this soul’s defaults. Try again, or see Details.',
|
|
56
|
+
};
|
|
57
|
+
|
|
58
|
+
const SPAWN = {
|
|
59
|
+
E_PLAN_REQUIRED: 'Check the values and press Spawn to confirm.',
|
|
60
|
+
E_DECISION_STALE: 'Something changed before the spawn went through. Nothing was created — check the updated values and press Spawn again.',
|
|
61
|
+
E_IDEMPOTENCY_CONFLICT: 'Something changed before the spawn went through. Nothing was created — check the updated values and press Spawn again.',
|
|
62
|
+
E_PLACEMENT_TAKEN: 'Another spawn just took this name. Nothing was created — check the new name and press Spawn again.',
|
|
63
|
+
E_INTENT_EXPIRED: 'This spawn request expired. Check the instance list before spawning again.',
|
|
64
|
+
E_PREFLIGHT_INCOMPLETE: 'OATS couldn’t finish checking this spawn. Try again.',
|
|
65
|
+
E_BACKEND_UNAVAILABLE: 'That session backend isn’t installed on this machine. Choose another in Developer settings.',
|
|
66
|
+
E_INSTANCE_GONE: 'The instance that was created isn’t there anymore. Check the instance list.',
|
|
67
|
+
E_OUTCOME_UNKNOWN: 'We couldn’t confirm whether the instance was created. Use Check result before spawning again.',
|
|
68
|
+
E_SPAWN_INCOMPLETE: 'The instance was created but didn’t finish starting. Open it from the instance list instead of spawning again.',
|
|
69
|
+
E_INPUT_PREPARATION: 'The opening instruction couldn’t be prepared, so nothing was started. Try again.',
|
|
70
|
+
E_CLI_TIMEOUT: 'OATS took too long to answer. The instance may already exist — use Check result before spawning again.',
|
|
71
|
+
E_CLI_OUTPUT_LIMIT: 'OATS couldn’t confirm the spawn. Use Check result before spawning again.',
|
|
72
|
+
E_CLI_PROTOCOL: 'OATS couldn’t complete the spawn. Try again, or see Details.',
|
|
73
|
+
E_CLI_FAILED: 'OATS couldn’t complete the spawn. Try again, or see Details.',
|
|
74
|
+
};
|
|
75
|
+
|
|
76
|
+
/** { text, detail } for a { code, message } reason. `stage` is 'preview'
|
|
77
|
+
* (reading defaults) or 'spawn' (after the operator pressed Spawn). */
|
|
78
|
+
export function spawnProblem(reason, stage = 'preview') {
|
|
79
|
+
const code = typeof reason?.code === 'string' ? reason.code : 'E_CLI_FAILED';
|
|
80
|
+
const own = stage === 'spawn' ? SPAWN : PREVIEW;
|
|
81
|
+
const message = typeof reason?.message === 'string' ? reason.message.trim() : '';
|
|
82
|
+
// A missing harness is said as the kernel words it, with its fix (launch preferences, 0.30).
|
|
83
|
+
const fix = typeof reason?.fix === 'string' ? reason.fix.trim() : '';
|
|
84
|
+
// The kernel's message usually already ends with its fix: said once.
|
|
85
|
+
const kernelWords = code === 'E_HARNESS_UNAVAILABLE' && message ? (fix && !message.includes(fix) ? `${message.replace(/[.\s]+$/, '')}: ${fix}` : message) : null;
|
|
86
|
+
const text = kernelWords ?? own[code] ?? COMMON[code] ?? (stage === 'spawn' ? SPAWN.E_CLI_FAILED : PREVIEW.E_CLI_FAILED);
|
|
87
|
+
return { text, code, detail: message ? `${code} · ${message}` : code };
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
/** The spawn catalog's state, for the soul chooser. */
|
|
91
|
+
export function catalogProblem(catalog) {
|
|
92
|
+
if (!catalog) return '';
|
|
93
|
+
const parts = [];
|
|
94
|
+
if (catalog.reason) parts.push('OATS couldn’t load this workspace’s souls, so the list may be out of date. Sync the workspace and try again.');
|
|
95
|
+
if (catalog.ambiguous?.length) parts.push(`Not offered because two repositories declare the same name: ${catalog.ambiguous.join(', ')}.`);
|
|
96
|
+
return parts.join(' ');
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/** Feature worktree-event (#802): the kernel rolled the spawn back (E_INTERRUPTED,
|
|
100
|
+
* E_REQUIRED_HOOK_FAILED, E_HOOK_ENVIRONMENT_CONTRACT without `unconfirmed`), so nothing
|
|
101
|
+
* was created; or its cleanup is owed (the same codes with it). The kernel's message names
|
|
102
|
+
* the capability and its log: it goes under Details, through displayLine. */
|
|
103
|
+
export function rolledBackProblem(reason, instance) {
|
|
104
|
+
const code = reason?.code;
|
|
105
|
+
if (!ROLLED_BACK_CODES.includes(code)) return null;
|
|
106
|
+
const text = code === 'E_INTERRUPTED'
|
|
107
|
+
? `The spawn of ${instance} was interrupted while its worktree was being set up, and was rolled back. Nothing was created.`
|
|
108
|
+
: `A capability couldn’t set up the worktree for ${instance}, so the spawn was rolled back. Nothing was created.`;
|
|
109
|
+
return { text, code, detail: kernelDetail(code, reason.message) };
|
|
110
|
+
}
|
|
111
|
+
export function cleanupOwedProblem(reason, instance) {
|
|
112
|
+
if (!ROLLED_BACK_CODES.includes(reason?.code)) return null;
|
|
113
|
+
return { text: `The spawn of ${instance} was stopped, but its cleanup didn’t finish. Retire ${instance} from the roster to complete it.`,
|
|
114
|
+
code: reason.code, detail: kernelDetail(reason.code, reason.message) };
|
|
115
|
+
}
|
|
116
|
+
function kernelDetail(code, message) {
|
|
117
|
+
const line = displayLine(message);
|
|
118
|
+
return line ? `${code} · ${line}` : code;
|
|
119
|
+
}
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/** Fixed read-only API2 argv. Never dispatch API1 or fall back to spawn. */
|
|
2
|
+
import { execFile } from 'node:child_process';
|
|
3
|
+
import { parseEnvelope } from './cli-adapter.mjs';
|
|
4
|
+
import { previewChoices, previewTarget, previewSupported, previewFailure, choiceArgv } from './spawn-preview-contract.mjs';
|
|
5
|
+
const failure = (code, message) => ({ schemaVersion: 1, ok: false, error: previewFailure(code, null, message).reason });
|
|
6
|
+
/** `io.exec` is a client's own `execFile` (the rule is at cli-adapter.mjs `runJson`). */
|
|
7
|
+
export function cliSpawnPreview(cli, options = {}, io = {}) {
|
|
8
|
+
// Defense at the actual exec owner as well as at HTTP admission.
|
|
9
|
+
if (!previewSupported(cli)) return Promise.resolve(failure('E_PREVIEW_UNAVAILABLE'));
|
|
10
|
+
const target = previewTarget(options.target), choices = previewChoices(options.choices);
|
|
11
|
+
if (!target || !choices || Object.keys(options).some(k => !['target', 'choices', 'maxAge'].includes(k))) return Promise.resolve(failure('E_BAD_ARGS'));
|
|
12
|
+
// Feature spawn-preview-max-age: reuse member heads the kernel observed within maxAge seconds. Only
|
|
13
|
+
// where the CLI advertises it (an older kernel refuses the flag); prepare and apply never pass it.
|
|
14
|
+
const maxAge = options.maxAge;
|
|
15
|
+
if (maxAge !== undefined && (!Number.isInteger(maxAge) || maxAge < 1 || maxAge > 3600)) return Promise.resolve(failure('E_BAD_ARGS'));
|
|
16
|
+
const reuse = maxAge !== undefined && Array.isArray(cli.features) && cli.features.includes('spawn-preview-max-age') ? ['--max-age', String(maxAge)] : [];
|
|
17
|
+
const argv = ['spawn', target.selector.soul, '--dir', target.context, '--agents-root', target.selector.agentsRoot, '--preview', ...choiceArgv(choices, cli), ...reuse, '--json'];
|
|
18
|
+
const env = { ...(io.env ?? process.env) };
|
|
19
|
+
for (const k of ['PI_AGENTS_ROOT', 'OATS_DEPLOYMENT', 'OATS_RESOLUTION', 'OATS_PREVIEW_PREFLIGHT_BUDGET_MS']) delete env[k];
|
|
20
|
+
return new Promise(resolve => {
|
|
21
|
+
try {
|
|
22
|
+
(io.exec ?? execFile)(cli.bin, argv, { cwd: target.context, env, shell: false, encoding: 'utf8', timeout: 30000, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
|
|
23
|
+
if (err?.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') return resolve(failure('E_CLI_OUTPUT_LIMIT'));
|
|
24
|
+
if (err?.killed) return resolve(failure('E_CLI_TIMEOUT'));
|
|
25
|
+
const doc = parseEnvelope(stdout);
|
|
26
|
+
if (doc?.ok === false) return resolve(failure(doc.error?.code, doc.error?.message));
|
|
27
|
+
if (err) return resolve(failure('E_CLI_FAILED'));
|
|
28
|
+
resolve(doc?.ok === true ? doc : failure('E_CLI_PROTOCOL'));
|
|
29
|
+
});
|
|
30
|
+
} catch { resolve(failure('E_CLI_FAILED')); }
|
|
31
|
+
});
|
|
32
|
+
}
|