@awebai/oats 0.68.0 → 0.69.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 +102 -22
- package/docs/capabilities.md +49 -5
- package/docs/configuration.md +68 -2
- package/docs/desktop-cli-api.md +355 -12
- package/docs/desktop-instance-start.md +88 -3
- package/docs/desktop.md +147 -13
- package/docs/execution-targets.md +514 -62
- package/docs/harness-trust.md +3 -1
- package/docs/implementation.md +28 -11
- package/docs/integrations.md +1 -1
- package/docs/oats-local.schema.json +2 -2
- package/docs/official-catalog.md +4 -3
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.68.1.md +102 -0
- package/docs/release-notes/v0.69.0.md +658 -0
- package/docs/release-notes/v0.69.1.md +25 -0
- package/docs/servers.md +44 -5
- package/docs/souls-and-instances.md +11 -7
- package/docs/tui.md +114 -31
- package/docs/upgrading.md +14 -5
- package/docs/workspaces.md +1 -1
- package/lib/core.mjs +345 -89
- package/lib/file-pieces.mjs +49 -0
- package/lib/instance-events.mjs +25 -4
- package/lib/launch-prompt-fixtures/README.md +62 -0
- package/lib/launch-prompt-fixtures/resume-confirmation.json +32 -0
- package/lib/launch-prompt-fixtures.mjs +49 -0
- package/lib/launch-prompt-resume.mjs +55 -0
- package/lib/login-environment.mjs +27 -9
- package/lib/schedule.mjs +3 -3
- package/lib/servers.mjs +117 -23
- package/lib/session-end.mjs +82 -0
- package/lib/session-input.mjs +43 -9
- package/lib/session-resume-contract.mjs +32 -0
- package/lib/session-resume.mjs +310 -0
- package/lib/session-seen.mjs +163 -0
- package/lib/session-viewer.mjs +147 -44
- package/lib/soul-composition.mjs +2 -1
- package/lib/start-env.mjs +110 -0
- package/lib/tmux-server-scope.mjs +139 -14
- package/lib/workspace.mjs +38 -4
- package/package-catalog.json +10 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +9 -0
- package/packages/client/cli-locator.mjs +3 -2
- package/packages/client/deployment-data.mjs +7 -0
- package/packages/client/deployment-panel.mjs +3 -0
- package/packages/client/file-output-exec.mjs +98 -0
- package/packages/client/instance-display-name.mjs +18 -0
- package/packages/client/launch-prompt-outcome.mjs +25 -13
- package/packages/client/own-codes.mjs +2 -0
- package/packages/client/session-attach.mjs +35 -5
- package/packages/client/session-resume-cli.mjs +64 -0
- package/packages/client/session-resume-trigger.mjs +167 -0
- package/packages/client/session-resume.mjs +332 -0
- package/packages/client/tmux-status.mjs +30 -7
- package/packages/client/waiting-on-you.mjs +11 -4
- package/packages/client/workspace-step.mjs +17 -5
- package/packages/record/lib/last-conversation.mjs +123 -0
- package/packages/record/lib/session-roots.mjs +10 -1
- package/packages/tui/README.md +1 -1
- package/packages/tui/lib/client.mjs +2 -1
- package/packages/tui/lib/main.mjs +5 -3
- package/packages/tui/lib/model.mjs +57 -15
- package/packages/tui/lib/store.mjs +8 -7
- package/packages/tui/lib/term/text.mjs +12 -9
- package/packages/tui/lib/views/capabilities.mjs +6 -6
- package/packages/tui/lib/views/frame.mjs +72 -7
- package/packages/tui/lib/views/help.mjs +9 -4
- package/packages/tui/lib/views/instances.mjs +46 -29
- package/packages/tui/lib/views/souls.mjs +9 -8
- package/skills/oats-getting-started/SKILL.md +117 -4
package/bin/oats.mjs
CHANGED
|
@@ -33,7 +33,7 @@ import {
|
|
|
33
33
|
LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
|
|
34
34
|
capabilityManifests, capabilityTrust, capabilityExecutablePath,
|
|
35
35
|
officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
|
|
36
|
-
findInstanceHome, findInstanceHomes, homeLaunchLayers, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, suggestSpawnName, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, launchStartNotices, launchReportFor, explicitInstanceName, retireInstance, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
|
|
36
|
+
findInstanceHome, findInstanceHomes, homeLaunchLayers, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, suggestSpawnName, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, machineLaunchConfigs, machineLaunchConfigsFile, launchStartNotices, launchReportFor, explicitInstanceName, retireInstance, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
|
|
37
37
|
FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
|
|
38
38
|
} from "../lib/core.mjs";
|
|
39
39
|
import {
|
|
@@ -52,6 +52,7 @@ import * as remoteModule from "../lib/remote.mjs";
|
|
|
52
52
|
import { activateLocalInputs, localRevision } from "../lib/local-inputs.mjs";
|
|
53
53
|
import YAML from "yaml";
|
|
54
54
|
import { attachArgv, checkRemote, connectServer, forgetSnapshot, getServer, inspectRemote, startRemote, restartRemote, launchConfigRemote, scheduleRemote, listSnapshots, learnWorkspaceKey, readServers, redactArgv, reportedWorkspaceKey, rosterGroups, routeCapability, routeCommand, runRemote, serverFlagOf, targetOf, updateServers, validateServer, workspaceKeyOfStatus, workspaceMismatch, SERVERS_FILE } from "../lib/servers.mjs";
|
|
55
|
+
import { readSessionViewer } from "../lib/session-viewer.mjs";
|
|
55
56
|
import { spawnSync as spawnSyncProc } from "node:child_process";
|
|
56
57
|
import { tickTriggers } from "../lib/triggers.mjs";
|
|
57
58
|
import * as A from "../lib/automations.mjs";
|
|
@@ -69,6 +70,7 @@ import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withCompos
|
|
|
69
70
|
import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
|
|
70
71
|
import { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } from "../lib/deployments.mjs";
|
|
71
72
|
import { observeResolvedDeployment } from "../lib/resolved-deployment.mjs";
|
|
73
|
+
import { SESSION_RESUME_FEATURE } from "../lib/session-resume-contract.mjs";
|
|
72
74
|
|
|
73
75
|
const rawArgs = process.argv.slice(2);
|
|
74
76
|
/** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
|
|
@@ -108,7 +110,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
|
|
|
108
110
|
* probe) and in `status --json`, which a remote roster relays as the host's (feature
|
|
109
111
|
* server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
|
|
110
112
|
* time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
|
|
111
|
-
const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "instance-suggest-name", "spawn-apply-suggest-name"];
|
|
113
|
+
const KERNEL_FEATURES = ["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE];
|
|
112
114
|
/** Commands `--server <id>` runs on a registered server. */
|
|
113
115
|
const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
|
|
114
116
|
const flag = (name) => {
|
|
@@ -824,6 +826,19 @@ function doctorRetained(ws) {
|
|
|
824
826
|
const kept = retainedWorktrees(deployment);
|
|
825
827
|
return [retainedRecoveryLines(join(deployment, "agents"), kept), retainedWorktreeLines(kept)].filter((block) => block.length);
|
|
826
828
|
}
|
|
829
|
+
/** The machine's launch configurations file (awebai/oats#1506) as doctor reports it: its path, whether
|
|
830
|
+
* it is there, its entries' names and whether it is valid. A broken file is reported, never a failure
|
|
831
|
+
* of doctor; the launches it would affect refuse it. */
|
|
832
|
+
function doctorMachineLaunchConfigs() {
|
|
833
|
+
const file = machineLaunchConfigsFile();
|
|
834
|
+
try {
|
|
835
|
+
const machine = machineLaunchConfigs();
|
|
836
|
+
return { file, present: machine !== null, ok: true, configurations: Object.keys(machine?.configs ?? {}).sort() };
|
|
837
|
+
} catch (e) {
|
|
838
|
+
if (e?.code !== "E_LAUNCH_CONFIG_INVALID") throw e;
|
|
839
|
+
return { file, present: true, ok: false, configurations: [], error: e.message };
|
|
840
|
+
}
|
|
841
|
+
}
|
|
827
842
|
async function doctorWorkspaceJson(ctx, soulName, ws) {
|
|
828
843
|
const composition = await doctorComposition(ctx, soulName, ws, (code, msg, details) => jsonFail(code, msg, details));
|
|
829
844
|
const agentsRoot = join(dirname(ws.local.path), "agents");
|
|
@@ -839,6 +854,7 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
|
|
|
839
854
|
workspace: { file: ws.local.path, ref: ws.local.workspace },
|
|
840
855
|
workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
|
|
841
856
|
information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
|
|
857
|
+
machineLaunchConfigs: doctorMachineLaunchConfigs(),
|
|
842
858
|
composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
|
|
843
859
|
...(problems.length ? { problems } : {}),
|
|
844
860
|
warnings: [...hookEvents.warnings, ...(soulName ? [] : doctorCaptureWarnings())],
|
|
@@ -876,6 +892,9 @@ async function doctor(dir) {
|
|
|
876
892
|
doctorVersionSkew(dirname(ws.local.path));
|
|
877
893
|
const composition = await doctorComposition(ctx, soulName, ws, (code, msg) => die(`${msg} [${code}]`));
|
|
878
894
|
printDoctorWorkspace(ws);
|
|
895
|
+
const machine = doctorMachineLaunchConfigs();
|
|
896
|
+
console.log("\nThis machine's launch configurations:");
|
|
897
|
+
console.log(` ${shortPath(machine.file)} ${!machine.present ? "(none: no file)" : machine.ok ? (machine.configurations.join(", ") || "(none declared)") : `ERROR: ${terminalText(machine.error)}`}`);
|
|
879
898
|
const agentsRoot = join(dirname(ws.local.path), "agents");
|
|
880
899
|
const localTeams = doctorLocalTeams(ws.local.value);
|
|
881
900
|
for (const p of [...legacyLayoutProblems(agentsRoot), readableInstanceHomes(agentsRoot)].filter(Boolean)) console.log(`\n! ${p.code}: ${p.message}`);
|
|
@@ -984,6 +1003,15 @@ function readLaunchConfigsModel(local) {
|
|
|
984
1003
|
for (const [n, e] of Object.entries(map)) out[n] = normalizeLaunchConfig(e);
|
|
985
1004
|
return out;
|
|
986
1005
|
}
|
|
1006
|
+
/** Whether the machine's launch configurations file declares `name`; a broken file declares nothing here
|
|
1007
|
+
* (the launches it affects refuse it). */
|
|
1008
|
+
/** The file a launch configuration of this machine was declared in, from its `source` directory. */
|
|
1009
|
+
function launchConfigFile(source) {
|
|
1010
|
+
return source === dirname(machineLaunchConfigsFile()) ? machineLaunchConfigsFile() : join(source, "oats-local.yaml");
|
|
1011
|
+
}
|
|
1012
|
+
function machineDeclares(name) {
|
|
1013
|
+
try { return Object.hasOwn(machineLaunchConfigs()?.configs ?? {}, name); } catch (e) { if (e?.code === "E_LAUNCH_CONFIG_INVALID") return false; throw e; }
|
|
1014
|
+
}
|
|
987
1015
|
/** What a GUI or an operator sees of one configuration. Environment values
|
|
988
1016
|
* never leave the file: a literal is answered as {redacted: true} (literals
|
|
989
1017
|
* are non-secret by contract, but no value is shown anywhere) and a
|
|
@@ -1092,10 +1120,10 @@ async function launchConfigCmd() {
|
|
|
1092
1120
|
let configurations;
|
|
1093
1121
|
try { configurations = effective(); } catch (e) { bail(e.code || "E_LAUNCH_CONFIG_INVALID", e.message); }
|
|
1094
1122
|
if (JSON_MODE) { jsonOk({ context: dir, level, file, selected, configurations }); return; }
|
|
1095
|
-
if (!configurations.length) { console.log(`No launch configurations are declared${file ? ` in ${shortPath(file)}` : ` (no oats-local.yaml in reach of ${dir})`}`); return; }
|
|
1123
|
+
if (!configurations.length) { console.log(`No launch configurations are declared${file ? ` in ${shortPath(file)}` : ` (no oats-local.yaml in reach of ${dir})`} or in ${shortPath(machineLaunchConfigsFile())}`); return; }
|
|
1096
1124
|
for (const c of configurations) {
|
|
1097
1125
|
const env = Object.entries(c.env).map(([n, v]) => v.fromEnv ? `${n}=$${v.fromEnv}` : `${n}=<redacted>`).join(" ");
|
|
1098
|
-
console.log(`${c.name}: ${c.harness}${c.default ? ` (this machine's ${c.harness} default)` : ""}${c.executable ? ` ${c.executable}` : ""}${c.args.length ? ` ${c.args.map((a) => JSON.stringify(a)).join(" ")}` : ""}${env ? ` [${env}]` : ""}${c.model ? ` model ${c.model}` : ""}${c.yolo !== null ? ` yolo ${c.yolo}` : ""}`);
|
|
1126
|
+
console.log(`${c.name}: ${c.harness}${c.default ? ` (this machine's ${c.harness} default)` : ""}${c.executable ? ` ${c.executable}` : ""}${c.args.length ? ` ${c.args.map((a) => JSON.stringify(a)).join(" ")}` : ""}${env ? ` [${env}]` : ""}${c.model ? ` model ${c.model}` : ""}${c.yolo !== null ? ` yolo ${c.yolo}` : ""} (from ${shortPath(launchConfigFile(c.source))})${c.shadows.length ? ` (replaces ${c.shadows.map(shortPath).join(", ")}'s)` : ""}`);
|
|
1099
1127
|
}
|
|
1100
1128
|
return;
|
|
1101
1129
|
}
|
|
@@ -1141,16 +1169,18 @@ async function launchConfigCmd() {
|
|
|
1141
1169
|
const declaredHere = Object.hasOwn(model, name);
|
|
1142
1170
|
before = declaredHere ? publicLaunchConfig(model[name]) : null;
|
|
1143
1171
|
if (sub === "remove") {
|
|
1144
|
-
if (!declaredHere) throw refusal("E_LAUNCH_CONFIG_UNKNOWN", `${name} is not declared in ${shortPath(file)}`);
|
|
1172
|
+
if (!declaredHere) throw refusal("E_LAUNCH_CONFIG_UNKNOWN", `${name} is not declared in ${shortPath(file)}${machineDeclares(name) ? `; it is this machine's, in ${shortPath(machineLaunchConfigsFile())}, which OATS never writes` : ""}`);
|
|
1145
1173
|
delete model[name];
|
|
1146
1174
|
} else {
|
|
1147
1175
|
let written = entry;
|
|
1148
1176
|
if (keepEnv) {
|
|
1149
1177
|
// An editor that saw only redacted values keeps the environment of the
|
|
1150
1178
|
// declared definition of that name: a one-time copy into the complete
|
|
1151
|
-
// replacement entry.
|
|
1152
|
-
|
|
1153
|
-
|
|
1179
|
+
// replacement entry. A name only this machine declares keeps the machine
|
|
1180
|
+
// entry's, so the first save of a machine row writes the entry that shadows it.
|
|
1181
|
+
let current = declaredHere ? model[name] : undefined;
|
|
1182
|
+
if (!current) { try { const machine = machineLaunchConfigs()?.configs ?? {}; if (Object.hasOwn(machine, name)) current = machine[name]; } catch (e) { throw refusal(e.code || "E_LAUNCH_CONFIG_INVALID", e.message, e.details); } }
|
|
1183
|
+
if (!current) throw refusal("E_LAUNCH_CONFIG_UNKNOWN", `--keep-env: no launch configuration ${name} is declared in ${shortPath(file)} or in ${shortPath(machineLaunchConfigsFile())}, so there is no environment to keep; declare it with env`);
|
|
1154
1184
|
if (Object.keys(current.env || {}).length) written = { ...entry, env: { ...current.env } };
|
|
1155
1185
|
try { validateLaunchConfig(name, written, `--file ${f}`); } catch (e) { throw refusal(e.code || "E_LAUNCH_CONFIG_INVALID", e.message); }
|
|
1156
1186
|
}
|
|
@@ -2754,7 +2784,7 @@ async function status() {
|
|
|
2754
2784
|
const observation = maxAgeGiven === null ? {} : { observation: observationBlock() };
|
|
2755
2785
|
// `features` (feature server-probe-features): this kernel's own list, as `version --json` answers
|
|
2756
2786
|
// it, so a remote roster relays the host's without probing it. Never part of a reused observation.
|
|
2757
|
-
console.log(JSON.stringify({ root, agents: data, ...observation, features: KERNEL_FEATURES, ...(ws ? { workspace: { ...(ws.unreachable ? { reachable: false, ...ws.unreachable } : { reachable: true }), ...workspaceIdentity(ws.local, ws.discovery) } } : {}), ...(problems.length ? { problems } : {}), ...envelopeWarnings() }, null, 2)); return;
|
|
2787
|
+
console.log(JSON.stringify({ root, agents: data, ...observation, features: KERNEL_FEATURES, sessionViewer: readSessionViewer(), ...(ws ? { workspace: { ...(ws.unreachable ? { reachable: false, ...ws.unreachable } : { reachable: true }), ...workspaceIdentity(ws.local, ws.discovery) } } : {}), ...(problems.length ? { problems } : {}), ...envelopeWarnings() }, null, 2)); return;
|
|
2758
2788
|
}
|
|
2759
2789
|
console.log(`oats status — agents root ${shortPath(root)}\n`);
|
|
2760
2790
|
if (ws?.unreachable) console.log(` workspace: unreachable (${ws.unreachable.reason}) — drift unknown\n`);
|
|
@@ -2840,7 +2870,7 @@ function namingLine(naming) {
|
|
|
2840
2870
|
function printSpawnPreview(r, { server, soulFetched = false } = {}) {
|
|
2841
2871
|
// A host before 0.27 names the harness `runtime` (it still answers spawn-preview-2).
|
|
2842
2872
|
const harness = r.harness ?? r.runtime;
|
|
2843
|
-
console.log(`preview ${r.agent} → ${r.instance}${server ? ` on ${server}` : ""} (${r.work}${r.branch ? `, branch ${r.branch}${r.base ? ` from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}` : ""}) harness ${harness}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}${r.launchConfig ? ` via launch configuration ${r.launchConfig}${r.launchConfigDefault ? ` (${server ? "the server's" : "this machine's"} ${harness} default)` : ""}` : ""}${r.yolo ? " YOLO" : ""}; nothing was created${soulFetched ? " (the soul source was fetched to a temporary copy, not kept)" : ""}`);
|
|
2873
|
+
console.log(`preview ${r.agent} → ${r.instance}${server ? ` on ${server}` : ""} (${r.work}${r.branch ? `, branch ${r.branch}${r.base ? ` from ${r.base.ref}@${r.base.oid.slice(0, 12)}` : ""}` : ""}) harness ${harness}${r.model ? ` model ${r.model}` : ` (${r.modelSource})`}${r.launchConfig ? ` via launch configuration ${r.launchConfig}${r.launchConfigDefault ? ` (${server ? "the server's" : "this machine's"} ${harness} default)` : ""}${r.launchConfigSource ? ` from ${server ? terminalText(r.launchConfigSource) : shortPath(launchConfigFile(r.launchConfigSource))}` : ""}` : ""}${r.yolo ? " YOLO" : ""}; nothing was created${soulFetched ? " (the soul source was fetched to a temporary copy, not kept)" : ""}`);
|
|
2844
2874
|
// Feature spawn-suggest-name: how the name was chosen.
|
|
2845
2875
|
{ const line = namingLine(r.naming); if (line) console.log(`name: ${line}`); }
|
|
2846
2876
|
if (Array.isArray(r.worktreeHooks)) console.log(r.worktreeHooks.length ? `worktree hooks: ${r.worktreeHooks.map((h) => `${h.capability}${h.required ? " (required)" : ""}`).join(", ")}` : "worktree hooks: none");
|
|
@@ -3579,14 +3609,37 @@ async function sessionCmd() {
|
|
|
3579
3609
|
if (args[1] === "attach") {
|
|
3580
3610
|
if (JSON_MODE) throw Object.assign(new Error("session attach is interactive; omit --json"), { code: "E_BAD_ARGS" });
|
|
3581
3611
|
// --detach-key (feature session-attach-detach-key): the one key that leaves this viewer, with
|
|
3582
|
-
// status 20. Without it every key reaches the agent and there is
|
|
3612
|
+
// status 20. Without it every key but the viewer's scrollback key reaches the agent and there is
|
|
3613
|
+
// no keyboard exit.
|
|
3583
3614
|
// What earlier attaches left (a viewer whose attach died without detaching): one line, on
|
|
3584
3615
|
// stderr, before the client takes the terminal, and only when something was removed.
|
|
3585
3616
|
const onSwept = ({ sessions, tables }) => {
|
|
3586
3617
|
const n = (count, what) => `${count} ${what}${count === 1 ? "" : "s"}`;
|
|
3587
3618
|
if (sessions + tables > 0) console.error(`oats: removed ${n(sessions, "leftover viewer session")} and ${n(tables, "key table")} of earlier attaches`);
|
|
3588
3619
|
};
|
|
3589
|
-
|
|
3620
|
+
// --no-status-line (feature session-attach-no-status-line): a viewer without its status line,
|
|
3621
|
+
// the scroll keys, for a caller that shows them itself.
|
|
3622
|
+
process.exitCode = await attachInstanceSession(home, { detachKey: valueFlag("detach-key"), statusLine: !args.includes("--no-status-line"), onSwept });
|
|
3623
|
+
return;
|
|
3624
|
+
}
|
|
3625
|
+
if (args[1] === "resume") {
|
|
3626
|
+
// The machine sweep (feature session-resume, #1559): lib/session-resume.mjs. No --home: one home
|
|
3627
|
+
// is `session start --resume`.
|
|
3628
|
+
const usage = "usage: oats session resume [--deployment <dir>] [--plan] [--json]";
|
|
3629
|
+
for (let i = 2; i < args.length; i++) {
|
|
3630
|
+
const a = args[i];
|
|
3631
|
+
if (a === "--deployment") { i++; continue; }
|
|
3632
|
+
if (a.startsWith("--deployment=") || a === "--plan" || a === "--json") continue;
|
|
3633
|
+
throw Object.assign(new Error(a.startsWith("-") ? `oats session resume: unknown flag ${a}\n${usage}` : `oats session resume takes no argument ${JSON.stringify(a)}\n${usage}`), { code: "E_BAD_ARGS" });
|
|
3634
|
+
}
|
|
3635
|
+
const deployment = flag("deployment");
|
|
3636
|
+
if (deployment === true || (typeof deployment === "string" && !deployment.trim())) throw Object.assign(new Error(`--deployment needs a deployment directory\n${usage}`), { code: "E_BAD_ARGS" });
|
|
3637
|
+
const { resumeSessions } = await import("../lib/session-resume.mjs");
|
|
3638
|
+
const answer = await resumeSessions({ deployment, plan: args.includes("--plan"), kernel: { execPath: process.execPath, bin: CLI_BIN } });
|
|
3639
|
+
if (JSON_MODE) { jsonOk(answer); return; }
|
|
3640
|
+
for (const d of answer.deployments) console.log(`${d.deployment}: ${d.swept ? "swept" : `not swept (${d.reason}${d.code ? `, ${d.code}` : ""})`}`);
|
|
3641
|
+
for (const r of answer.rows) console.log(` ${r.instance} ${answer.plan ? "would be " : ""}${r.outcome}${r.reason ? ` (${r.reason}${r.code ? `, ${r.code}` : ""})` : ""}${r.message ? `: ${terminalText(r.message)}` : ""}`);
|
|
3642
|
+
if (!answer.rows.length) console.log("nothing to resume");
|
|
3590
3643
|
return;
|
|
3591
3644
|
}
|
|
3592
3645
|
if (args[1] === "inspect") result = inspectInstanceSession(home);
|
|
@@ -3603,9 +3656,17 @@ async function sessionCmd() {
|
|
|
3603
3656
|
// recorded launch stays frozen (a changed preference never reaches an existing home on its own).
|
|
3604
3657
|
const reselectLaunch = args.includes("--reselect-launch");
|
|
3605
3658
|
if (reselectLaunch && launchConfig !== undefined) bad("--reselect-launch applies the launch preferences; --launch-config names one explicitly — choose one");
|
|
3659
|
+
// --resume (feature session-resume): the recorded launch as it is, in the home's last conversation;
|
|
3660
|
+
// refused with a launch choice before anything of the home is read.
|
|
3661
|
+
const resume = args.includes("--resume");
|
|
3662
|
+
if (resume) {
|
|
3663
|
+
if (args[1] === "restart") bad("--resume exists on session start only: it brings back a session that was lost");
|
|
3664
|
+
const chosen = ["--launch-config", "--harness", "--model", "--yolo", "--no-yolo", "--reselect-launch"].filter((f) => args.some((a) => a === f || a.startsWith(`${f}=`)));
|
|
3665
|
+
if (chosen.length) bad(`--resume runs the launch this home recorded; it cannot be combined with ${chosen.join(", ")}; nothing was read or started`);
|
|
3666
|
+
}
|
|
3606
3667
|
// Refuse before launch selection or live-team discovery can prepare this home.
|
|
3607
3668
|
assertNoPartialUpgrade(home);
|
|
3608
|
-
const opts = { model: model || undefined, launchConfig, harness, yolo: yoloFlag(), ...(reselectLaunch ? { reselectLaunch: true, launchOffered: await homeLaunchOffered(home, { named: harness !== undefined }) } : {}), env: process.env, ...(await homeLiveTeams(home)) };
|
|
3669
|
+
const opts = { model: model || undefined, launchConfig, harness, yolo: yoloFlag(), ...(reselectLaunch ? { reselectLaunch: true, launchOffered: await homeLaunchOffered(home, { named: harness !== undefined }) } : {}), ...(resume ? { resume: true } : {}), env: process.env, ...(await homeLiveTeams(home)) };
|
|
3609
3670
|
if (args[1] === "restart") {
|
|
3610
3671
|
const grace = flag("stop-grace");
|
|
3611
3672
|
if (grace !== undefined) { if (grace === true || !/^\d+$/.test(String(grace)) || Number(grace) < 1 || Number(grace) > 300) bad("--stop-grace needs a number of seconds (1..300) to wait for the harness after SIGTERM"); opts.stopGraceMs = Number(grace) * 1000; }
|
|
@@ -3628,7 +3689,7 @@ async function sessionCmd() {
|
|
|
3628
3689
|
const file = flag("file");
|
|
3629
3690
|
if (!file || file === true) throw Object.assign(new Error("session upload needs --file <local path>"), { code: "E_BAD_ARGS" });
|
|
3630
3691
|
result = uploadAttachment({ file, home: home === true ? undefined : home });
|
|
3631
|
-
} else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|restart|receive|upload --home /absolute/home [--text-file path] [--detach-key key] [--model id] [--launch-config name|none | --reselect-launch] [--harness pi|claude|codex] [--yolo|--no-yolo] [--stop-grace seconds] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
|
|
3692
|
+
} else throw Object.assign(new Error("usage: oats session inspect|input|attach|start|restart|receive|upload --home /absolute/home [--text-file path] [--detach-key key] [--no-status-line] [--model id] [--launch-config name|none | --reselect-launch] [--harness pi|claude|codex] [--yolo|--no-yolo] [--stop-grace seconds] [--name file] [--file path] [--json]"), { code: "E_BAD_ARGS" });
|
|
3632
3693
|
if (JSON_MODE) jsonOk(result);
|
|
3633
3694
|
else {
|
|
3634
3695
|
console.log(JSON.stringify(result, null, 2));
|
|
@@ -4255,7 +4316,7 @@ function versionCmd() {
|
|
|
4255
4316
|
// Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
|
|
4256
4317
|
// runs on resolve/materialize (contract §6); a feature the binary does not implement is
|
|
4257
4318
|
// never listed.
|
|
4258
|
-
console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: KERNEL_FEATURES, automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1 }));
|
|
4319
|
+
console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: KERNEL_FEATURES, automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1, sessionViewer: readSessionViewer() }));
|
|
4259
4320
|
return;
|
|
4260
4321
|
}
|
|
4261
4322
|
console.log(`@awebai/oats ${OATS_VERSION} (desktop API v1)`);
|
|
@@ -4637,7 +4698,7 @@ async function serverRouteCmd() {
|
|
|
4637
4698
|
const detachKey = valueFlag("detach-key");
|
|
4638
4699
|
if (detachKey !== undefined) process.on("SIGQUIT", () => {});
|
|
4639
4700
|
let route;
|
|
4640
|
-
try { route = attachArgv(id, { ...addr, detachKey }, { skipVersionCheck: args.includes("--print") }); }
|
|
4701
|
+
try { route = attachArgv(id, { ...addr, detachKey, statusLine: !args.includes("--no-status-line") }, { skipVersionCheck: args.includes("--print") }); }
|
|
4641
4702
|
// ssh failing before the viewer (the version probe, a name resolved through the host's roster)
|
|
4642
4703
|
// is the failure ssh has under it: exit 255, on which a caller reconnects. Every other refusal,
|
|
4643
4704
|
// and an ssh that never started (no link can come back), exits 1.
|
|
@@ -4779,7 +4840,10 @@ try {
|
|
|
4779
4840
|
const kernelArgv = (KERNEL_COMMANDS.has(cmd) && !OWN_ARGV_COMMANDS.has(cmd)) || (ROUTED_COMMANDS.has(cmd) && flag("server") !== undefined);
|
|
4780
4841
|
if (argvProblem && kernelArgv) cmdFail("E_BAD_ARGS", argvProblem);
|
|
4781
4842
|
const end = args.indexOf("--"), head = end < 0 ? args : args.slice(0, end);
|
|
4782
|
-
|
|
4843
|
+
// `session resume --deployment <dir>` (feature session-resume) reuses the name for a deployment
|
|
4844
|
+
// the sweep is limited to, not a captured selector.
|
|
4845
|
+
const resumeSweep = cmd === "session" && args[1] === "resume";
|
|
4846
|
+
const selector = head.find((a) => /^--(deployment|resolution|artifact-set)$/.test(a) && !(resumeSweep && a === "--deployment"));
|
|
4783
4847
|
const refuse = (message, details) => { if (JSON_MODE) jsonFail("E_UNSUPPORTED_MODE", message, details); die(message); };
|
|
4784
4848
|
if (selector) refuse(`${selector}: a captured selector is refused (the captured/portable path was removed in 0.26); run the command in its workspace deployment or instance home instead`, { selector });
|
|
4785
4849
|
// --max-age (feature observe-max-age): ONE allow-list for every kernel command, here — never a
|
|
@@ -4813,7 +4877,8 @@ try {
|
|
|
4813
4877
|
// help, and silent: no output, no change to the command's answer or exit status.
|
|
4814
4878
|
const LISTS_ITS_DEPLOYMENT = new Set(["automations", "capabilities", "doctor", "harness", "inspect", "instance", "launch-config", "operation", "package", "pane", "readiness", "retire", "schedule", "session", "soul", "souls", "spawn", "status", "sync", "teams", "trigger", "update", "workspace", "worktree"]);
|
|
4815
4879
|
// `instance suggest-name` records nothing (#1490 §2): the oats-local.yaml it reads is not listed.
|
|
4816
|
-
|
|
4880
|
+
// `session resume` reads the list and never writes it (#1559).
|
|
4881
|
+
if (LISTS_ITS_DEPLOYMENT.has(cmd) && flag("server") === undefined && !(cmd === "instance" && args[1] === "suggest-name") && !(cmd === "session" && args[1] === "resume") && !args.slice(1).some((a) => a === "--help" || a === "-h")) observeResolvedDeployment(listResolved);
|
|
4817
4882
|
if (cmd === "onboard") {
|
|
4818
4883
|
if (args.includes("--help") || args.includes("-h")) { if (JSON_MODE) jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); else usageFor(cmd); process.exit(0); }
|
|
4819
4884
|
await onboardCmd();
|
|
@@ -4828,6 +4893,8 @@ if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ co
|
|
|
4828
4893
|
if (cmd === "instance" && args[1] === "upgrade" && flag("server") !== undefined) cmdFail("E_BAD_ARGS", "instance upgrade supports local homes only; run it on the deployment host");
|
|
4829
4894
|
// #1490 §2: the name is decided on the machine that asks, for a spawn that lands elsewhere.
|
|
4830
4895
|
if (cmd === "instance" && args[1] === "suggest-name" && flag("server") !== undefined) cmdFail("E_BAD_ARGS", "instance suggest-name takes no --server: it runs this machine's harness, for a spawn that may land on another; the host it lands on makes the name unique (or names an unnamed --suggest-name spawn itself)");
|
|
4896
|
+
// Session resume is local only (#1559, D1): a server resumes its own instances.
|
|
4897
|
+
if (cmd === "session" && flag("server") !== undefined && (args[1] === "resume" || args.includes("--resume"))) cmdFail("E_BAD_ARGS", "session resume and session start --resume act on this machine's instances only; a server runs oats session resume itself");
|
|
4831
4898
|
if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
|
|
4832
4899
|
else if (cmd === "server") await serverCmd();
|
|
4833
4900
|
else if (cmd === "deployments") deploymentsCmd();
|
|
@@ -4965,8 +5032,10 @@ Usage:
|
|
|
4965
5032
|
oats session inspect|attach --server <id> inspect (envelope) or attach a viewer (ssh PTY) for a
|
|
4966
5033
|
--instance <name> | --home <abs> remote instance, by its saved route or the server's
|
|
4967
5034
|
[--detach-key <key>] roster (--print shows attach); oats 0.22.2 or later.
|
|
4968
|
-
|
|
4969
|
-
advertise session-attach-detach-key
|
|
5035
|
+
[--no-status-line] attach --detach-key: as below; the server must
|
|
5036
|
+
advertise session-attach-detach-key.
|
|
5037
|
+
--no-status-line: as below; a server without
|
|
5038
|
+
session-attach-no-status-line shows the line
|
|
4970
5039
|
oats session start --server <id> start a stopped remote instance in its existing home
|
|
4971
5040
|
--instance <name> | --home <abs> by its saved route or the server's roster; it must advertise
|
|
4972
5041
|
[--model <m>] [--json] session-start (oats 0.22.9 or later)
|
|
@@ -5002,11 +5071,15 @@ Usage:
|
|
|
5002
5071
|
oats deployments import --from desktop <path>... [--json]
|
|
5003
5072
|
the Desktop's one-time import of its own lists
|
|
5004
5073
|
oats session inspect|input|attach --home <absolute-home> [--text-file <path>] [--json]
|
|
5005
|
-
oats session attach --home <absolute-home> [--detach-key <key>]
|
|
5074
|
+
oats session attach --home <absolute-home> [--detach-key <key>] [--no-status-line]
|
|
5006
5075
|
a viewer of one instance. <key> (C-<letter>, M-<letter
|
|
5007
5076
|
or digit>, F1 to F12; 'C-\\' is the suggested one)
|
|
5008
5077
|
leaves it with exit status 20; without one no key
|
|
5009
|
-
leaves it
|
|
5078
|
+
leaves it. Shift+PageUp scrolls back (tmux copy mode:
|
|
5079
|
+
PageUp, PageDown, q leaves), and so does C-b [ in a
|
|
5080
|
+
viewer without a key, whose status line says so
|
|
5081
|
+
(--no-status-line: none); every other key goes to
|
|
5082
|
+
the agent, C-b and the key after it included
|
|
5010
5083
|
oats schedule list|show <id>|test <id>|add <id> --file <spec.json>|update <id> --file <spec.json>
|
|
5011
5084
|
enable|disable|run|remove|reconcile <id> workspace-scoped, host-owned schedules (spawn,
|
|
5012
5085
|
tick [--dry-run] [--host] command or wake jobs on a five-field cron with an
|
|
@@ -5044,6 +5117,13 @@ Usage:
|
|
|
5044
5117
|
[--reselect-launch] applies the launch preferences now (oats-local.yaml
|
|
5045
5118
|
souls.launch, the soul's launch); a changed preference
|
|
5046
5119
|
never reaches an existing home without it or a respawn
|
|
5120
|
+
oats session start --resume --home <abs> start a home whose session was LOST (a reboot, a dead
|
|
5121
|
+
tmux server) in its own last conversation, the
|
|
5122
|
+
recorded launch as is; fresh on TASK.md when none is
|
|
5123
|
+
found (docs/execution-targets.md#resume-after-a-shutdown)
|
|
5124
|
+
oats session resume [--deployment <dir>] resume every lost session of this computer's
|
|
5125
|
+
[--plan] [--json] deployments (one sweep per machine; at most 3 resumes
|
|
5126
|
+
of a home per boot); --plan starts nothing
|
|
5047
5127
|
oats session restart --home <abs-home> stop the running harness (SIGTERM, bounded wait,
|
|
5048
5128
|
[same flags] [--stop-grace <s>] never escalated) and start it again in place under
|
|
5049
5129
|
the same lock; a stop that is not observed is
|
package/docs/capabilities.md
CHANGED
|
@@ -1044,7 +1044,8 @@ latest-state capability.
|
|
|
1044
1044
|
|
|
1045
1045
|
### oats.core: needs input
|
|
1046
1046
|
|
|
1047
|
-
oats.core (2.4.0
|
|
1047
|
+
oats.core (since 2.4.0, which needs kernel 0.40.0; 2.8.0 needs 0.49.0, as
|
|
1048
|
+
"Across `oats instance upgrade`" below says) tells the deployment
|
|
1048
1049
|
when an instance is waiting on a human, in two independent ways. Each shows
|
|
1049
1050
|
on `oats status` and in `oats instance events`. The verbs' contract
|
|
1050
1051
|
(`oats instance waiting`, `oats instance attention`, the `waiting` event) is
|
|
@@ -1091,10 +1092,31 @@ home. Before 2.4.1 it set and cleared the claim of the home its environment
|
|
|
1091
1092
|
named, and its `Stop` and `SessionEnd` clears could erase that instance's
|
|
1092
1093
|
real claim.
|
|
1093
1094
|
|
|
1095
|
+
**A set carries what the session waits on** (oats.core 2.8.0,
|
|
1096
|
+
[#1502](https://github.com/awebai/oats/issues/1502)). The script reads the
|
|
1097
|
+
hook's JSON input, at most 64 KiB and for at most 1 s, and its
|
|
1098
|
+
`bin/claude-waiting-message.mjs` makes the claim's `--message` from it. On
|
|
1099
|
+
Claude Code 2.1.300:
|
|
1100
|
+
- an `AskUserQuestion` gives its first question's own words
|
|
1101
|
+
(`tool_input.questions[0].question`), with `(+N more)` when it asks
|
|
1102
|
+
several;
|
|
1103
|
+
- a `Notification` gives its `message`: "Claude needs your permission to use
|
|
1104
|
+
Bash" for a permission prompt, "Claude Code needs your input" for an
|
|
1105
|
+
elicitation dialog.
|
|
1106
|
+
|
|
1107
|
+
The text is made one line, the kernel's refused characters are replaced with
|
|
1108
|
+
U+FFFD, and it is cut to 200 code points with `…`, so the kernel accepts it.
|
|
1109
|
+
An input with no text, or a reader that fails or takes over 1 s, sets the
|
|
1110
|
+
claim without one. A new text for the same reason is a change, so the claim
|
|
1111
|
+
is set again. A set records its intent before it reads the text, and only
|
|
1112
|
+
the latest event's text is ever applied. So a clear or a question that comes
|
|
1113
|
+
while an earlier set is still reading stands, and the earlier text never
|
|
1114
|
+
lands over it.
|
|
1115
|
+
|
|
1094
1116
|
Claude Code shows an AskUserQuestion through its permission dialog, so that
|
|
1095
1117
|
dialog's own `permission_prompt` follows the question's set: the script keeps
|
|
1096
|
-
the current reason in its marker
|
|
1097
|
-
open question. A granted tool that fails fires `PostToolUseFailure`, not
|
|
1118
|
+
the current reason in its marker (and the text beside it), and a permission
|
|
1119
|
+
prompt never relabels an open question or replaces its text. A granted tool that fails fires `PostToolUseFailure`, not
|
|
1098
1120
|
`PostToolUse`, so that clears too.
|
|
1099
1121
|
|
|
1100
1122
|
**Subagents' tool calls do not clear.** Background and parallel subagents
|
|
@@ -1143,7 +1165,8 @@ clears it.
|
|
|
1143
1165
|
in the home (`.oats/modules/oats.core`), which a start does not refresh. A
|
|
1144
1166
|
home spawned with an oats.core that does not read the variable therefore
|
|
1145
1167
|
writes its hook's own node path at every start: a restart repairs its
|
|
1146
|
-
hooks after each Node upgrade, and a respawn
|
|
1168
|
+
hooks after each Node upgrade, and a respawn, or an upgrade of its
|
|
1169
|
+
oats.core (below), gives it the lasting path. A
|
|
1147
1170
|
launch preview writes nothing. Every pass answers `{}`: no launch arguments and no env. Codex
|
|
1148
1171
|
and pi homes get nothing.
|
|
1149
1172
|
- **It never hurts the session.** Claude Code reads a hook's stdout and exit
|
|
@@ -1216,6 +1239,25 @@ clears it.
|
|
|
1216
1239
|
exactly `.claude/settings.json`. oats.core writes it at spawn before the
|
|
1217
1240
|
retirement baseline is taken, and again at every start.
|
|
1218
1241
|
|
|
1242
|
+
**Across `oats instance upgrade`.** oats.core 2.8.0 declares an `upgrade`
|
|
1243
|
+
hook ([the upgrade event](#the-upgrade-event)), not required, so a stopped
|
|
1244
|
+
home whose oats.core moves to it is upgraded rather than respawned. The
|
|
1245
|
+
hook that runs is the destination's, so this covers homes spawned on any
|
|
1246
|
+
earlier oats.core, with or without the emitter. oats.core records no
|
|
1247
|
+
capability metadata, and its settings entries name the module copy's path,
|
|
1248
|
+
`.oats/modules/oats.core`, which an upgrade keeps; the next start's launch
|
|
1249
|
+
hook rewrites them. So `plan` adopts a home whose recorded
|
|
1250
|
+
`capabilityMeta["oats.core"]` is absent or `{}`, or a falsy value (`null`,
|
|
1251
|
+
`false`, `0`, `""`), which the kernel passes in `OATS_META` as `{}`. It
|
|
1252
|
+
refuses any other value as state it cannot vouch for, with the remedy
|
|
1253
|
+
`respawn the instance: oats retire <instance>, then oats spawn`. `apply`
|
|
1254
|
+
returns `{"meta":{}}`, which the kernel records as
|
|
1255
|
+
`capabilityMeta["oats.core"]`, and exits 1 with a JSON `warning` on any other
|
|
1256
|
+
metadata. Neither phase reads the home or calls the host. oats.core 2.8.0
|
|
1257
|
+
requires OATS 0.49.0: an earlier kernel drops a capability that declares a
|
|
1258
|
+
hook event it does not know, so it would lose oats.core whole. Only OATS
|
|
1259
|
+
0.68.0 and later run the hook.
|
|
1260
|
+
|
|
1219
1261
|
**Why the project settings file, not `--settings`.** On Claude Code
|
|
1220
1262
|
2.1.288, Claude honours only the last `--settings` flag on a command line:
|
|
1221
1263
|
that file replaces earlier ones wholesale, even one with no hooks. The
|
|
@@ -1281,7 +1323,9 @@ again" permission rules there.
|
|
|
1281
1323
|
so its `Stop` and `SessionEnd` clears can erase the home's own live
|
|
1282
1324
|
`oats.core` claim ([#557](https://github.com/awebai/oats/issues/557)).
|
|
1283
1325
|
- A Claude instance spawned before the upgrade gets the emitter only when
|
|
1284
|
-
it is respawned
|
|
1326
|
+
it is respawned, or when `oats instance upgrade` moves its oats.core to
|
|
1327
|
+
2.8.0 or later and it starts again. Its launch hook comes from its
|
|
1328
|
+
recorded module copy.
|
|
1285
1329
|
|
|
1286
1330
|
## Operations a capability declares
|
|
1287
1331
|
|
package/docs/configuration.md
CHANGED
|
@@ -251,6 +251,15 @@ v<semver>` after the logo, which may be caught mid-animation), the error and the
|
|
|
251
251
|
|
|
252
252
|
A restart where the notice shows records `flag-ignored`.
|
|
253
253
|
|
|
254
|
+
**Known limit: a split window.** The confirmation still requires the agent's
|
|
255
|
+
window to have one pane. A start or restart in place on a window that has
|
|
256
|
+
another pane (oats.setup's no-echo prompt, for example) relaunches Claude in
|
|
257
|
+
the agent's pane
|
|
258
|
+
([which pane is the agent's](execution-targets.md#which-pane-is-the-agents))
|
|
259
|
+
but answers nothing: the home records `launchPrompts.status: "blocked"`, and
|
|
260
|
+
Claude waits at its development-channel prompt for a person, as after any
|
|
261
|
+
blocked start. Close the other pane before the restart.
|
|
262
|
+
|
|
254
263
|
**The two settings that stop it.** OATS confirms the prompt only because the
|
|
255
264
|
deployment launches Claude with the development-channel flag. To keep the prompt
|
|
256
265
|
for a person, stop launching that way: `settings.oats.aweb.delivery: session`
|
|
@@ -279,8 +288,8 @@ instance's terminal and press Enter yourself.
|
|
|
279
288
|
## Launch configurations
|
|
280
289
|
|
|
281
290
|
An entry has `harness` (`pi` \| `claude` \| `codex`, required), `executable`
|
|
282
|
-
(a bare name looked up on `PATH`, or a path relative to
|
|
283
|
-
|
|
291
|
+
(a bare name looked up on `PATH`, or a path relative to the directory of the
|
|
292
|
+
file that declares it), `args` (literal, no shell), `env` (a literal string, or
|
|
284
293
|
`{ fromEnv: NAME }` resolved on the host at start), `model`, `yolo` and
|
|
285
294
|
`default` (0.32; see [the harness default](#the-harness-default)). A launch
|
|
286
295
|
configuration is a host choice: a soul never names one.
|
|
@@ -315,6 +324,63 @@ configuration is a host choice: a soul never names one.
|
|
|
315
324
|
`oats spawn` and reading `aw` mail and chat, and what stays gated.
|
|
316
325
|
`yolo` is separate and is meant for isolated machines.
|
|
317
326
|
|
|
327
|
+
### This machine's launch configurations
|
|
328
|
+
|
|
329
|
+
`~/.oats/config/launch-configs.yaml` (`$OATS_HOME_DIR/config/` when
|
|
330
|
+
`OATS_HOME_DIR` is set) declares launch configurations for every deployment
|
|
331
|
+
on this machine. The person writes it, or an installer running as the
|
|
332
|
+
person; nothing in OATS writes it.
|
|
333
|
+
|
|
334
|
+
```yaml
|
|
335
|
+
launch-configs:
|
|
336
|
+
claude-auto:
|
|
337
|
+
harness: claude
|
|
338
|
+
args: ["--permission-mode", "auto"]
|
|
339
|
+
default: true
|
|
340
|
+
```
|
|
341
|
+
|
|
342
|
+
- **One key.** The file holds `launch-configs:` and nothing else. Its entries
|
|
343
|
+
have exactly the schema of the deployment's block and the same checks.
|
|
344
|
+
- **Missing or broken.** A missing file declares nothing. A file that is there
|
|
345
|
+
but cannot be read, is not valid YAML, is empty, lacks `launch-configs:`,
|
|
346
|
+
has any other top-level key, or holds an invalid entry is refused
|
|
347
|
+
(`E_LAUNCH_CONFIG_INVALID`, naming the file). The refusal reaches every
|
|
348
|
+
listing, preview, spawn and start that reads launch configurations. It is
|
|
349
|
+
never skipped. `oats doctor` reports the file and does not fail on it.
|
|
350
|
+
- **Precedence, by name.** Each deployment reads the machine's entries under
|
|
351
|
+
its own. A deployment entry with the same name replaces the machine's
|
|
352
|
+
whole: no field of the machine's entry is kept. Its `shadows` names the
|
|
353
|
+
machine file. With no deployment in reach, the machine's entries alone
|
|
354
|
+
apply.
|
|
355
|
+
- **Precedence, for the default.** The [harness default](#the-harness-default)
|
|
356
|
+
is per harness. A deployment's `default: true` for a harness wins over the
|
|
357
|
+
machine's: the machine's entry for that harness stays listed, but not as
|
|
358
|
+
default. The machine's default applies when the deployment declares none
|
|
359
|
+
for that harness. Two defaults for one harness within one file are refused,
|
|
360
|
+
as in the deployment.
|
|
361
|
+
- **`source`** is the directory an entry was declared in: the deployment
|
|
362
|
+
directory, or `~/.oats/config`. A relative `executable` resolves against
|
|
363
|
+
it.
|
|
364
|
+
- **Where it shows.**
|
|
365
|
+
- `oats launch-config list` (and `--json`) gives each entry's `source` and
|
|
366
|
+
`shadows`.
|
|
367
|
+
- `oats spawn --preview` names the machine file when it supplied the
|
|
368
|
+
configuration; the JSON carries `launchConfigSource`.
|
|
369
|
+
- `oats doctor --json` reports the file under `machineLaunchConfigs`:
|
|
370
|
+
`file`, `present`, `ok`, `configurations` (the names) and, when broken,
|
|
371
|
+
`error`.
|
|
372
|
+
- **Writes.** `oats launch-config set|remove` writes only the deployment's
|
|
373
|
+
`oats-local.yaml`. Setting a name the machine also declares adds a
|
|
374
|
+
deployment entry that shadows it, and removing that entry uncovers the
|
|
375
|
+
machine's again. Desktop's launch-configuration editor writes the same
|
|
376
|
+
way: saving a row whose source is the machine file writes a deployment
|
|
377
|
+
entry of that name, which then shadows the machine's.
|
|
378
|
+
- **Homes.** A spawn records the configuration as it was, the machine's like
|
|
379
|
+
the deployment's (`launchConfigSource` is the directory it came from). A
|
|
380
|
+
start or restart runs the recorded recipe; a later edit of either file
|
|
381
|
+
reaches a home only through `--launch-config <name>`, `--reselect-launch`
|
|
382
|
+
or a respawn.
|
|
383
|
+
|
|
318
384
|
### The harness default
|
|
319
385
|
|
|
320
386
|
`default: true` makes a configuration this host's baseline for its harness
|