@awebai/oats 0.66.0 → 0.68.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +166 -17
- package/docs/capabilities.md +58 -9
- package/docs/capability-manifest.schema.json +5 -1
- package/docs/design/2026-10-22-module-upgrade.md +192 -0
- package/docs/design/README.md +4 -0
- package/docs/desktop-cli-api.md +463 -13
- package/docs/desktop.md +363 -67
- package/docs/first-team.md +5 -3
- package/docs/implementation.md +46 -6
- package/docs/integrations.md +16 -4
- package/docs/knowledge.md +44 -27
- package/docs/layers.md +2 -2
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.67.0.md +366 -0
- package/docs/release-notes/v0.67.1.md +64 -0
- package/docs/release-notes/v0.68.0.md +504 -0
- package/docs/servers.md +8 -2
- package/docs/souls-and-instances.md +58 -6
- package/docs/tui.md +1033 -237
- package/docs/upgrading.md +164 -26
- package/docs/workspaces.md +2 -2
- package/lib/capability-contract.mjs +8 -7
- package/lib/core.mjs +331 -75
- package/lib/instance-color.mjs +58 -0
- package/lib/instance-events.mjs +1 -1
- package/lib/instance-inspect.mjs +107 -23
- package/lib/instance-lifecycle.mjs +21 -1
- package/lib/instance-naming.mjs +187 -0
- package/lib/instance-resolution.mjs +10 -6
- package/lib/instance-upgrade.mjs +1445 -0
- package/lib/materialize.mjs +287 -89
- package/lib/servers.mjs +24 -11
- package/lib/soul-composition.mjs +7 -3
- package/lib/upgrade-state.mjs +101 -0
- package/lib/workspace.mjs +4 -1
- package/lib/worktree.mjs +103 -12
- package/package-catalog.json +5 -4
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +52 -6
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +10 -2
- package/packages/client/deployment-data.mjs +5 -0
- package/packages/client/deployment-identity.mjs +40 -0
- package/packages/client/deployment-panel.mjs +9 -3
- package/packages/client/inspect-boundary.mjs +11 -7
- package/packages/client/inspect-cache.mjs +2 -2
- package/packages/client/instance-name.mjs +28 -0
- package/packages/client/instance-presentation.mjs +11 -0
- package/packages/client/keymap.mjs +133 -28
- package/packages/client/keys-file.mjs +126 -0
- package/packages/client/own-codes.mjs +4 -2
- package/packages/client/panel-views.mjs +78 -12
- package/packages/client/spawn-naming.mjs +32 -0
- package/packages/client/spawn-preview-cli.mjs +58 -7
- package/packages/client/spawn-preview-contract.mjs +59 -0
- package/packages/client/spawn-preview-facts.mjs +8 -4
- package/packages/client/spawn-preview.mjs +81 -3
- package/packages/client/team-members.mjs +4 -1
- package/packages/client/workspace-step.mjs +25 -0
- package/packages/tui/README.md +7 -7
- package/packages/tui/lib/actions.mjs +92 -25
- package/packages/tui/lib/client.mjs +9 -4
- package/packages/tui/lib/config.mjs +50 -9
- package/packages/tui/lib/main.mjs +65 -24
- package/packages/tui/lib/model.mjs +292 -75
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +469 -100
- package/packages/tui/lib/term/keys.mjs +22 -6
- package/packages/tui/lib/term/kitty.mjs +54 -11
- package/packages/tui/lib/term/screen.mjs +15 -6
- package/packages/tui/lib/term/through.mjs +66 -28
- package/packages/tui/lib/views/frame.mjs +223 -165
- package/packages/tui/lib/views/help.mjs +134 -29
- package/packages/tui/lib/views/instances.mjs +63 -22
- package/packages/tui/lib/views/palette.mjs +14 -4
- package/packages/tui/lib/views/souls.mjs +2 -2
- package/packages/tui/lib/views/switcher.mjs +6 -1
- package/packages/tui/lib/views/workspaces.mjs +55 -0
- package/skills/oats-getting-started/SKILL.md +96 -42
package/bin/oats.mjs
CHANGED
|
@@ -26,13 +26,14 @@ import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
|
|
|
26
26
|
import { fileURLToPath } from "node:url";
|
|
27
27
|
import { performance } from "node:perf_hooks";
|
|
28
28
|
import { doctorCaptureWarnings } from "../lib/doctor-capture.mjs";
|
|
29
|
+
import { assertNoPartialUpgrade } from "../lib/upgrade-state.mjs";
|
|
29
30
|
import { runtimeNameWarning, noteRuntimeName } from "../lib/deprecation.mjs";
|
|
30
31
|
import { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect, spawnRefusalDetails } from "../lib/errors.mjs";
|
|
31
32
|
import {
|
|
32
33
|
LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
|
|
33
34
|
capabilityManifests, capabilityTrust, capabilityExecutablePath,
|
|
34
35
|
officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
|
|
35
|
-
findInstanceHome, findInstanceHomes, homeLaunchLayers, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, 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, 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
37
|
FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
|
|
37
38
|
} from "../lib/core.mjs";
|
|
38
39
|
import {
|
|
@@ -60,18 +61,18 @@ import { kernelNode, stableNode } from "../lib/stable-node.mjs";
|
|
|
60
61
|
import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
|
|
61
62
|
|
|
62
63
|
import { observeInstanceGit, diffInstanceFile } from "../lib/instance-git.mjs";
|
|
63
|
-
import { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance as resolveInstanceForCli, STOP_WARNINGS } from "../lib/instance-lifecycle.mjs";
|
|
64
|
+
import { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance as resolveInstanceForCli, setInstanceColor, STOP_WARNINGS } from "../lib/instance-lifecycle.mjs";
|
|
64
65
|
import { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } from "../lib/retire-output.mjs";
|
|
65
66
|
import { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } from "../lib/retained-after-retire.mjs";
|
|
66
67
|
const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
|
|
67
|
-
import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument,
|
|
68
|
+
import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposition, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
|
|
68
69
|
import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
|
|
69
70
|
import { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } from "../lib/deployments.mjs";
|
|
70
71
|
import { observeResolvedDeployment } from "../lib/resolved-deployment.mjs";
|
|
71
72
|
|
|
72
73
|
const rawArgs = process.argv.slice(2);
|
|
73
74
|
/** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
|
|
74
|
-
const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "run-source", "self", "skills", "verbose", "yes", "yolo"]);
|
|
75
|
+
const KERNEL_SWITCHES = new Set(["allow-child-spawns", "apply", "check", "clear", "composed-skills", "delete-branch", "discard-worktree", "dry-run", "ephemeral", "force", "help", "host", "if-absent", "install-oats", "instructions", "json", "keep-dir", "keep-env", "no-child-spawns", "no-default", "no-launch", "no-recursive", "no-yolo", "plan", "policy", "preview", "print", "replace", "run-source", "self", "skills", "suggest-name", "verbose", "yes", "yolo"]);
|
|
75
76
|
/** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
|
|
76
77
|
* routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
|
|
77
78
|
* `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
|
|
@@ -107,7 +108,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
|
|
|
107
108
|
* probe) and in `status --json`, which a remote roster relays as the host's (feature
|
|
108
109
|
* server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
|
|
109
110
|
* time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
|
|
110
|
-
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"];
|
|
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"];
|
|
111
112
|
/** Commands `--server <id>` runs on a registered server. */
|
|
112
113
|
const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
|
|
113
114
|
const flag = (name) => {
|
|
@@ -572,10 +573,13 @@ async function inspectCmd() {
|
|
|
572
573
|
// Feature soul-skills: opt-in, soul subject only; without it no skill file is read.
|
|
573
574
|
const skills = args.includes("--skills");
|
|
574
575
|
if (skills && flag("home") !== undefined) return bail("E_BAD_ARGS", "--skills lists a soul's own skills before a spawn: it takes --soul, not --home (an instance's skills are in its home's .agents/skills/)");
|
|
576
|
+
// Feature soul-composed-skills: opt-in, soul subject only; it shares --instructions' one scratch composition.
|
|
577
|
+
const composedSkills = args.includes("--composed-skills");
|
|
578
|
+
if (composedSkills && flag("home") !== undefined) return bail("E_BAD_ARGS", "--composed-skills lists the skills a spawn of a soul would give its instance: it takes --soul, not --home (an instance's skills are in its home's .agents/skills/)");
|
|
575
579
|
let t = await workspaceTarget(bail, { command: "inspect" });
|
|
576
580
|
if (t) {
|
|
577
581
|
if (t.resolutionError) return bail(t.resolutionError.code, t.resolutionError.message, t.resolutionError.details ?? undefined);
|
|
578
|
-
if (instructions) t = await
|
|
582
|
+
if (instructions || composedSkills) t = await withComposition(t, { instructions, skills: composedSkills });
|
|
579
583
|
if (skills) t = await withSkills(t);
|
|
580
584
|
const doc = inspectDocument(t, { kernel: OATS_VERSION });
|
|
581
585
|
if (JSON_MODE) { jsonOk(withObservation(doc)); return; }
|
|
@@ -628,6 +632,11 @@ function printWorkspaceInspect(doc) {
|
|
|
628
632
|
for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
|
|
629
633
|
const composed = doc.souls[0].composedInstructions;
|
|
630
634
|
if (composed !== undefined) console.log(composed ? `\nComposed AGENTS.md (a spawn here, resolution ${composed.resolution ?? "?"}${composed.truncated ? ", truncated" : ""}):\n\n${composed.text}` : "\nComposed AGENTS.md: unavailable (see the problems above)");
|
|
635
|
+
const composedSkills = doc.souls[0].composedSkills;
|
|
636
|
+
if (composedSkills !== undefined) {
|
|
637
|
+
if (!composedSkills) console.log("\nComposed skills: unavailable (see the problems above)");
|
|
638
|
+
else { console.log(`\nComposed skills (a spawn here): ${composedSkills.length || "none"}`); for (const k of composedSkills) console.log(` ${k.name} ${k.source === "soul" ? "soul" : k.source.slice("module:".length)}`); }
|
|
639
|
+
}
|
|
631
640
|
}
|
|
632
641
|
|
|
633
642
|
/** `{ teams, defaultTeam, teamsSource }` for a session start of a workspace home: its teams read
|
|
@@ -1310,12 +1319,70 @@ function retiredInstanceAddresses(root, name, home) {
|
|
|
1310
1319
|
* instance's work tree. The instance is addressed qualified: an explicit
|
|
1311
1320
|
* --home, or a name under the --dir scope (team roots included) that resolves
|
|
1312
1321
|
* to exactly one home; several homes refuse with every candidate named. */
|
|
1313
|
-
function
|
|
1322
|
+
async function instanceUpgradeCmd(name, bail) {
|
|
1323
|
+
const usage = "usage: oats instance upgrade <instance> [--undo] (--plan | --plan-revision <rev> --idempotency-key <key>) [--home <abs>] [--dir <d>] [--json]";
|
|
1324
|
+
if (!name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
|
|
1325
|
+
if (serverFlagOf(args)) return bail("E_BAD_ARGS", "instance upgrade supports local homes only; run it on the deployment host");
|
|
1326
|
+
const home = flag("home"), revision = flag("plan-revision"), key = flag("idempotency-key");
|
|
1327
|
+
if (home === true || (home !== undefined && !isAbsolute(home))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
|
|
1328
|
+
const planOnly = args.includes("--plan"), undo = args.includes("--undo");
|
|
1329
|
+
if (revision === true || key === true || (planOnly && (revision !== undefined || key !== undefined))) return bail("E_BAD_ARGS", usage);
|
|
1330
|
+
dropAmbientRoot();
|
|
1331
|
+
try {
|
|
1332
|
+
const root = ensureRoot(dirFlag());
|
|
1333
|
+
const { planUpgrade, applyUpgrade } = await import("../lib/instance-upgrade.mjs");
|
|
1334
|
+
const result = planOnly ? await planUpgrade(dirFlag(), root, name, { home, undo })
|
|
1335
|
+
: await applyUpgrade(dirFlag(), root, name, { home, undo, planRevision: revision, idempotencyKey: key });
|
|
1336
|
+
if (JSON_MODE) { jsonOk(result); return; }
|
|
1337
|
+
console.log(`${undo ? "undo package upgrade" : "package upgrade"} ${name}: ${planOnly ? `plan ${result.planRevision}` : result.status}${result.replayed ? " (replayed receipt)" : ""}`);
|
|
1338
|
+
for (const row of result.modules) console.log(` ${row.capability}: ${row.from.version} @ ${row.from.commit.slice(0,12)} → ${row.to.version} @ ${row.to.commit.slice(0,12)}${row.provider?.decision === "refuse" ? `; refused: ${row.provider.reason}` : ""}`);
|
|
1339
|
+
for (const row of result.kept || []) console.log(` ${row.capability}: kept (${row.reason})`);
|
|
1340
|
+
for (const row of result.memberDrift || []) console.log(` ${row.module}: member drift (${row.reason || row.status}); respawn to move it`);
|
|
1341
|
+
if (planOnly) console.log(` home changed since spawn: ${result.homeChangedSinceSpawn ? "yes (retire preserves a recovery copy)" : "no"}`);
|
|
1342
|
+
if (planOnly) console.log(`apply with: oats instance upgrade ${name}${undo ? " --undo" : ""} --plan-revision ${result.planRevision} --idempotency-key <key>`);
|
|
1343
|
+
} catch (e) { return lifecycleFail(e, "E_UPGRADE_FAILED", { ...e.details, ...(e.plan ? { plan: e.plan } : {}), ...(e.candidates ? { candidates: e.candidates } : {}) }); }
|
|
1344
|
+
}
|
|
1345
|
+
|
|
1346
|
+
/** The flags `oats instance suggest-name` reads, each taking a value (`--json` aside). */
|
|
1347
|
+
const SUGGEST_NAME_FLAGS = new Set(["soul", "task", "task-file", "harness", "model", "launch-config", "dir"]);
|
|
1348
|
+
/** `oats instance suggest-name` (feature instance-suggest-name, awebai/oats#1490 §2): the name a spawn
|
|
1349
|
+
* of a soul would get by --suggest-name, chosen here for a spawn that may land on another machine
|
|
1350
|
+
* (lib/core.mjs suggestSpawnName). Never routed: --server is refused before the route dispatch. */
|
|
1351
|
+
async function instanceSuggestNameCmd(bail) {
|
|
1352
|
+
const usage = "usage: oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]";
|
|
1353
|
+
// A flag's value as given, the empty text included (`--task ""` is an empty task, not a missing one).
|
|
1354
|
+
const value = (name) => {
|
|
1355
|
+
const i = args.indexOf(`--${name}`);
|
|
1356
|
+
if (i < 0) return undefined;
|
|
1357
|
+
const v = inlineValues.has(name) ? inlineValues.get(name) : args[i + 1];
|
|
1358
|
+
if (v === undefined || (!inlineValues.has(name) && v.startsWith("--"))) return bail("E_BAD_ARGS", `--${name} needs a value; ${usage}`);
|
|
1359
|
+
return v;
|
|
1360
|
+
};
|
|
1361
|
+
for (let i = 2; i < args.length; i++) {
|
|
1362
|
+
const a = args[i];
|
|
1363
|
+
if (a === "--json") continue;
|
|
1364
|
+
if (!a.startsWith("--") || !SUGGEST_NAME_FLAGS.has(a.slice(2))) return bail("E_BAD_ARGS", `oats instance suggest-name: unexpected ${a.startsWith("--") ? "flag" : "argument"} ${JSON.stringify(a)}; ${usage}`);
|
|
1365
|
+
if (!inlineValues.has(a.slice(2))) i++;
|
|
1366
|
+
}
|
|
1367
|
+
const soul = value("soul"), task = value("task"), taskFile = value("task-file");
|
|
1368
|
+
if (soul === undefined) return bail("E_BAD_ARGS", `--soul is required; ${usage}`);
|
|
1369
|
+
if ((task === undefined) === (taskFile === undefined)) return bail("E_BAD_ARGS", `give the task with one of --task or --task-file; ${usage}`);
|
|
1370
|
+
let text = task;
|
|
1371
|
+
if (taskFile !== undefined) { try { text = readFileSync(taskFile, "utf8"); } catch (e) { return bail("E_BAD_ARGS", `--task-file ${taskFile} cannot be read (${e.code || "error"})`); } }
|
|
1372
|
+
let r;
|
|
1373
|
+
try { r = await suggestSpawnName({ dir: dirFlag(), soul, task: text, harness: value("harness"), model: value("model"), launchConfig: value("launch-config") }); }
|
|
1374
|
+
catch (e) { return bail(e.code || "E_BAD_ARGS", e.message, e.details); }
|
|
1375
|
+
if (JSON_MODE) { jsonOk(r); return; }
|
|
1376
|
+
console.log(r.name ?? namingLine(r.naming));
|
|
1377
|
+
}
|
|
1378
|
+
async function instanceCmd() {
|
|
1314
1379
|
const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
|
|
1315
1380
|
const sub = args[1], name = args[2];
|
|
1381
|
+
if (sub === "upgrade") return instanceUpgradeCmd(name, bail);
|
|
1316
1382
|
if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
|
|
1317
|
-
|
|
1318
|
-
|
|
1383
|
+
if (sub === "suggest-name") return instanceSuggestNameCmd(bail);
|
|
1384
|
+
const usage = "usage: oats instance waiting <set|clear> --producer <id> [--reason permission|question|attention] [--message <text>] [--home <abs>] [--dir <d>] [--json] | oats instance attention [--message <text>] [--clear] [--json] | oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--dir <d>] [--json] | oats instance git <instance> [--home <abs>] [--dir <d>] [--json] | oats instance diff <instance> --file <id> --revision <rev> [--index-revision <rev>] [--home <abs>] [--dir <d>] [--json] | oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d>] [--json] | oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json]";
|
|
1385
|
+
if (!["git", "diff", "stop", "events", "color"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
|
|
1319
1386
|
dropAmbientRoot();
|
|
1320
1387
|
if (sub === "events") {
|
|
1321
1388
|
// K7: typed producer events, bounded window; nothing inferred.
|
|
@@ -1348,6 +1415,29 @@ function instanceCmd() {
|
|
|
1348
1415
|
return;
|
|
1349
1416
|
} catch (e) { return bail(e.code || "E_EVENTS_FAILED", e.message, e.candidates ? { candidates: e.candidates } : undefined); }
|
|
1350
1417
|
}
|
|
1418
|
+
if (sub === "color") {
|
|
1419
|
+
// Feature instance-color: presentation only, so no plan; addressed as stop addresses an instance.
|
|
1420
|
+
const homeOpt = flag("home");
|
|
1421
|
+
if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
|
|
1422
|
+
const colorUsage = "usage: oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json]";
|
|
1423
|
+
// The words after the instance that are not a flag or the value of --home or --dir: the colour, at most one.
|
|
1424
|
+
const words = [];
|
|
1425
|
+
for (let i = 3; i < args.length; i++) { if (args[i] === "--home" || args[i] === "--dir") i++; else if (!args[i].startsWith("--")) words.push(args[i]); }
|
|
1426
|
+
const clear = args.includes("--clear");
|
|
1427
|
+
if (words.length > 1) return bail("E_BAD_ARGS", `oats instance color takes one colour; ${colorUsage}`);
|
|
1428
|
+
const value = words[0];
|
|
1429
|
+
if (value !== undefined && clear) return bail("E_BAD_ARGS", `give a colour or --clear, not both; ${colorUsage}`);
|
|
1430
|
+
if (value === undefined && !clear) return bail("E_BAD_ARGS", `give a colour or --clear; ${colorUsage}`);
|
|
1431
|
+
let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
|
|
1432
|
+
try {
|
|
1433
|
+
const r = setInstanceColor(dirFlag(), root, name, { home: homeOpt, color: clear ? null : value });
|
|
1434
|
+
if (JSON_MODE) { jsonOk(r); return; }
|
|
1435
|
+
console.log(`${r.instance}: ${r.color === null ? "no colour" : `colour ${r.color}`}${r.changed ? "" : " (unchanged)"}`);
|
|
1436
|
+
return;
|
|
1437
|
+
} catch (e) {
|
|
1438
|
+
return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
|
|
1439
|
+
}
|
|
1440
|
+
}
|
|
1351
1441
|
if (sub === "stop") {
|
|
1352
1442
|
// K3: plan → apply. The plan is what a confirmation shows; apply carries
|
|
1353
1443
|
// its revision back and refuses if reality moved.
|
|
@@ -2701,7 +2791,17 @@ const livenessWord = (i) => i.running === true ? "RUNNING" : i.running === false
|
|
|
2701
2791
|
* host through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an
|
|
2702
2792
|
* apply bound by --expect-decision: the dispatch allow-list (maxAgeRefusal) refuses it otherwise. */
|
|
2703
2793
|
const SPAWN_VALUE_FLAGS = new Set(["agents-root", "backend", "base", "branch", "dir", "expect-decision", "harness", "idempotency-key", "instance", "launch-config", "max-age", "model", "name", "parent", "purpose", "relation", "relative-root", "relative-to", "repo", "runtime", "task", "task-file", "trigger-event", "wake-cron", "wake-every", "wake-file", "wake-json", "wake-message", "wake-message-file", "wake-tz", "work", "work-dir"]);
|
|
2704
|
-
const SPAWN_SWITCHES = new Set(["allow-child-spawns", "json", "no-child-spawns", "no-launch", "no-yolo", "preview", "yolo"]);
|
|
2794
|
+
const SPAWN_SWITCHES = new Set(["allow-child-spawns", "json", "no-child-spawns", "no-launch", "no-yolo", "preview", "suggest-name", "yolo"]);
|
|
2795
|
+
/** `--suggest-name` (features spawn-suggest-name, spawn-apply-suggest-name): a preview's or an apply's,
|
|
2796
|
+
* with no --name, --purpose or --expect-decision. The kernel refuses the same (core.mjs spawnBody); the
|
|
2797
|
+
* CLI says it before anything is read or sent. */
|
|
2798
|
+
function suggestNameProblem(argv) {
|
|
2799
|
+
if (!argv.includes("--suggest-name")) return undefined;
|
|
2800
|
+
const given = (flag) => argv.some((a) => a.split("=")[0] === flag);
|
|
2801
|
+
if (given("--expect-decision")) return "--suggest-name chooses the name, and --expect-decision's decision already binds one: apply the previewed name with --name <instance> --expect-decision <revision>";
|
|
2802
|
+
if (given("--name") || given("--purpose")) return "--suggest-name chooses the name: it takes no --name or --purpose";
|
|
2803
|
+
return undefined;
|
|
2804
|
+
}
|
|
2705
2805
|
/** Why `argv` (after `spawn`, the soul first) is not a spawn, or undefined: a positional after the
|
|
2706
2806
|
* soul or a flag spawn does not read is never ignored. A value flag consumes its value exactly as
|
|
2707
2807
|
* flag() reads it; a missing value is the flag's own check. */
|
|
@@ -2728,12 +2828,21 @@ function herdrSpawnFlag() {
|
|
|
2728
2828
|
if (flag("herdr-socket") !== undefined) return "--herdr-socket";
|
|
2729
2829
|
return undefined;
|
|
2730
2830
|
}
|
|
2831
|
+
/** How a name was chosen (`naming`: features spawn-suggest-name, spawn-apply-suggest-name,
|
|
2832
|
+
* instance-suggest-name), for a text line; null without one. */
|
|
2833
|
+
function namingLine(naming) {
|
|
2834
|
+
if (naming?.source === "suggested") return `suggested by ${terminalText(naming.harness)}${naming.model ? ` (${terminalText(naming.model)})` : ""} in ${naming.ms} ms`;
|
|
2835
|
+
if (naming?.source === "numbered") return `numbered (${terminalText(naming.reason)}: ${terminalText(naming.message)})`;
|
|
2836
|
+
return null;
|
|
2837
|
+
}
|
|
2731
2838
|
/** A spawn preview's text: the local one, or a host's answer to a routed
|
|
2732
2839
|
* preview (`server`, its id), which this side printed the same way (#610). */
|
|
2733
2840
|
function printSpawnPreview(r, { server, soulFetched = false } = {}) {
|
|
2734
2841
|
// A host before 0.27 names the harness `runtime` (it still answers spawn-preview-2).
|
|
2735
2842
|
const harness = r.harness ?? r.runtime;
|
|
2736
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)" : ""}`);
|
|
2844
|
+
// Feature spawn-suggest-name: how the name was chosen.
|
|
2845
|
+
{ const line = namingLine(r.naming); if (line) console.log(`name: ${line}`); }
|
|
2737
2846
|
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");
|
|
2738
2847
|
for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
|
|
2739
2848
|
}
|
|
@@ -2752,7 +2861,7 @@ async function spawnCmd() {
|
|
|
2752
2861
|
};
|
|
2753
2862
|
checkDirectoryOptions(requestedWork); // before anything is resolved or written
|
|
2754
2863
|
const name = args[1];
|
|
2755
|
-
if (!name || name.startsWith("--")) bail("E_USAGE", "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug
|
|
2864
|
+
if (!name || name.startsWith("--")) bail("E_USAGE", "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>|--suggest-name] [--preview] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux] [--yolo|--no-yolo] [--model <m>] [--branch <b>] [--no-launch] [--json]");
|
|
2756
2865
|
// Retired boundary flags (maintainer transport ruling): fail LOUDLY before
|
|
2757
2866
|
// ANY side effect, including root discovery.
|
|
2758
2867
|
// Local souls (local-agents/) are gone with the workspace model: a soul is a member
|
|
@@ -2763,6 +2872,7 @@ async function spawnCmd() {
|
|
|
2763
2872
|
const nameFlag = flag("name");
|
|
2764
2873
|
if (nameFlag === true) bail("E_BAD_ARGS", "--name needs an instance name (a slug: lowercase letters and digits, single dashes between them)");
|
|
2765
2874
|
if (nameFlag !== undefined && flag("purpose") !== undefined) bail("E_BAD_ARGS", "--name and --purpose are mutually exclusive: --name is the exact instance name, --purpose derives <agent>-<purpose>");
|
|
2875
|
+
{ const problem = suggestNameProblem(args); if (problem) bail("E_BAD_ARGS", problem); }
|
|
2766
2876
|
// The slug rule is checked here too, before any side effect (soul fetch).
|
|
2767
2877
|
if (nameFlag !== undefined) { try { explicitInstanceName(String(nameFlag)); } catch (e) { bail(e.code, e.message); throw e; } }
|
|
2768
2878
|
if (args.includes("--ephemeral")) bail("E_BAD_ARGS", "--ephemeral was removed by the runtime-boundary ruling — declare the agent in a capability manifest (agents:) for automatic ephemeral semantics");
|
|
@@ -2957,6 +3067,7 @@ async function spawnCmd() {
|
|
|
2957
3067
|
// K6: --preview decides everything and touches nothing; --base <ref>
|
|
2958
3068
|
// selects a worktree's start point; --model @native-default is the
|
|
2959
3069
|
// explicit "harness's own default" (distinct from omitting --model).
|
|
3070
|
+
...(args.includes("--suggest-name") ? { suggestName: true } : {}),
|
|
2960
3071
|
...(args.includes("--preview") ? { preview: true, subject: { soul: name, agentsRoot: agentsRootFlag !== undefined ? String(agentsRootFlag) : null, dir: flag("dir") !== undefined && flag("dir") !== true ? String(flag("dir")) : null } } : {}),
|
|
2961
3072
|
...(flag("base") !== undefined && flag("base") !== true ? { baseRef: flag("base") } : {}),
|
|
2962
3073
|
// A confirmed preview binds this apply (K6b): drift → E_DECISION_STALE, nothing created.
|
|
@@ -3012,11 +3123,14 @@ async function spawnCmd() {
|
|
|
3012
3123
|
launchConfig: r.launch?.launchConfig ?? null, launch: r.launch || null, // already redacted by the kernel
|
|
3013
3124
|
// #796: the worktree hooks this spawn ran, with their logs; only when it ran any.
|
|
3014
3125
|
...(r.worktreeHooks ? { worktreeHooks: r.worktreeHooks } : {}),
|
|
3126
|
+
// Feature spawn-apply-suggest-name: how the name was chosen; only with --suggest-name.
|
|
3127
|
+
...(r.naming ? { naming: r.naming } : {}),
|
|
3015
3128
|
});
|
|
3016
3129
|
return;
|
|
3017
3130
|
}
|
|
3018
3131
|
console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux.window}"` : " — not launched"}`);
|
|
3019
3132
|
console.log(` home: ${shortPath(r.home)}`);
|
|
3133
|
+
{ const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
|
|
3020
3134
|
if (r.base) console.log(` base: ${r.base.oid.slice(0, 12)} (${r.base.ref === r.workspace?.soul?.repoKey ? `observed head of ${r.base.ref}` : r.base.ref})`);
|
|
3021
3135
|
for (const h of r.worktreeHooks || []) console.log(` setup: ${h.capability} worktree hook ${h.ok ? "ok" : "FAILED"} (log: ${shortPath(h.log)})`);
|
|
3022
3136
|
if (wakeSchedule) console.log(` wake: schedule ${wakeSchedule.id} (${wakeSchedule.cron} ${wakeSchedule.tz}), next ${wakeSchedule.nextRun || "disabled"}`);
|
|
@@ -3489,6 +3603,8 @@ async function sessionCmd() {
|
|
|
3489
3603
|
// recorded launch stays frozen (a changed preference never reaches an existing home on its own).
|
|
3490
3604
|
const reselectLaunch = args.includes("--reselect-launch");
|
|
3491
3605
|
if (reselectLaunch && launchConfig !== undefined) bad("--reselect-launch applies the launch preferences; --launch-config names one explicitly — choose one");
|
|
3606
|
+
// Refuse before launch selection or live-team discovery can prepare this home.
|
|
3607
|
+
assertNoPartialUpgrade(home);
|
|
3492
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)) };
|
|
3493
3609
|
if (args[1] === "restart") {
|
|
3494
3610
|
const grace = flag("stop-grace");
|
|
@@ -3518,6 +3634,11 @@ async function sessionCmd() {
|
|
|
3518
3634
|
console.log(JSON.stringify(result, null, 2));
|
|
3519
3635
|
// A start's launch-hook warnings, as spawn prints its own (stderr keeps stdout one JSON document).
|
|
3520
3636
|
for (const w of result?.warnings || []) console.error(` WARNING: ${terminalText(w)}`);
|
|
3637
|
+
if (result?.drift?.length) {
|
|
3638
|
+
const version = (v) => `${v.version ?? "?"} @ ${String(v.commit ?? "?").slice(0, 7)}`;
|
|
3639
|
+
const modules = result.drift.map((d) => `${d.capability} ${version(d.recorded)} → ${version(d.locked)}`).join(", ");
|
|
3640
|
+
console.error(terminalText(`${result.drift.length} package module(s) behind the lock (${modules}); to move them: oats instance stop ${shellQuote(result.instance)}; oats instance upgrade ${shellQuote(result.instance)} --plan`));
|
|
3641
|
+
}
|
|
3521
3642
|
}
|
|
3522
3643
|
} catch (e) { lifecycleFail(e, "E_SESSION_FAILED", e.details); }
|
|
3523
3644
|
}
|
|
@@ -4534,7 +4655,7 @@ async function serverRouteCmd() {
|
|
|
4534
4655
|
const herdr = herdrSpawnFlag();
|
|
4535
4656
|
if (herdr) { const e = herdrSettingRemoved(`${herdr} was given`); bail(e.code, e.message); }
|
|
4536
4657
|
const local = args.slice(1).filter((a, i, all) => a !== "--server" && all[i - 1] !== "--server");
|
|
4537
|
-
const problem = spawnArgvProblem(local);
|
|
4658
|
+
const problem = spawnArgvProblem(local) ?? suggestNameProblem(local);
|
|
4538
4659
|
if (problem) bail("E_BAD_ARGS", problem);
|
|
4539
4660
|
}
|
|
4540
4661
|
// Everything after the command word travels, minus the routing flags; a
|
|
@@ -4596,6 +4717,7 @@ async function serverRouteCmd() {
|
|
|
4596
4717
|
else if (cmd === "spawn") {
|
|
4597
4718
|
console.log(`Spawned ${r.instance} on ${id} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux?.window}" on ${r.target.sshHost}` : " — not launched"}`);
|
|
4598
4719
|
console.log(` remote home: ${r.home}`);
|
|
4720
|
+
{ const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
|
|
4599
4721
|
console.log(` route snapshot: ${r.snapshot ? shortPath(r.snapshot) : "none (see the warning)"}`);
|
|
4600
4722
|
for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
|
|
4601
4723
|
console.log(` attach: oats session attach --server ${shellQuote(id)} --instance ${shellQuote(r.instance)}`);
|
|
@@ -4690,7 +4812,8 @@ try {
|
|
|
4690
4812
|
// listResolved): a listed deployment costs one bounded read of the list. Never on --server (the remote's path is not this computer's), never for
|
|
4691
4813
|
// help, and silent: no output, no change to the command's answer or exit status.
|
|
4692
4814
|
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"]);
|
|
4693
|
-
|
|
4815
|
+
// `instance suggest-name` records nothing (#1490 §2): the oats-local.yaml it reads is not listed.
|
|
4816
|
+
if (LISTS_ITS_DEPLOYMENT.has(cmd) && flag("server") === undefined && !(cmd === "instance" && args[1] === "suggest-name") && !args.slice(1).some((a) => a === "--help" || a === "-h")) observeResolvedDeployment(listResolved);
|
|
4694
4817
|
if (cmd === "onboard") {
|
|
4695
4818
|
if (args.includes("--help") || args.includes("-h")) { if (JSON_MODE) jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); else usageFor(cmd); process.exit(0); }
|
|
4696
4819
|
await onboardCmd();
|
|
@@ -4702,6 +4825,9 @@ else {
|
|
|
4702
4825
|
// `okf harvest --help` spawned a harvester (BeadHub, 2026-09-05).
|
|
4703
4826
|
const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
|
|
4704
4827
|
if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); process.exit(0); } usageFor(cmd); process.exit(0); }
|
|
4828
|
+
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
|
+
// #1490 §2: the name is decided on the machine that asks, for a spawn that lands elsewhere.
|
|
4830
|
+
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)");
|
|
4705
4831
|
if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
|
|
4706
4832
|
else if (cmd === "server") await serverCmd();
|
|
4707
4833
|
else if (cmd === "deployments") deploymentsCmd();
|
|
@@ -4721,7 +4847,7 @@ else if (cmd === "update") {
|
|
|
4721
4847
|
}
|
|
4722
4848
|
else if (cmd === "harness") harnessTrustCmd();
|
|
4723
4849
|
else if (cmd === "readiness") await readinessCmd();
|
|
4724
|
-
else if (cmd === "instance") instanceCmd();
|
|
4850
|
+
else if (cmd === "instance") await instanceCmd();
|
|
4725
4851
|
else if (cmd === "worktree") await worktreeCmd();
|
|
4726
4852
|
else if (cmd === "root") console.log(resolve(new URL("..", import.meta.url).pathname));
|
|
4727
4853
|
else if (cmd === "sync") await syncCmd();
|
|
@@ -4961,6 +5087,12 @@ Usage:
|
|
|
4961
5087
|
instance.json providers.<capability>)
|
|
4962
5088
|
[--preview] decide everything, create no instance; --json
|
|
4963
5089
|
includes the decision revision for confirmation
|
|
5090
|
+
[--suggest-name] no --name, --purpose or --expect-decision: the
|
|
5091
|
+
soul's harness, on the machine that spawns, names
|
|
5092
|
+
the instance for its task (<descriptive>-<role>,
|
|
5093
|
+
made unique); else it is numbered, and
|
|
5094
|
+
naming.reason says why (claude and pi); on a
|
|
5095
|
+
preview or an apply
|
|
4964
5096
|
[--expect-decision <rev>] bind apply to the previewed decision; drift refuses
|
|
4965
5097
|
[--idempotency-key <key>] with --expect-decision, replay the completed receipt
|
|
4966
5098
|
for the same key and confirmed decision; a different
|
|
@@ -4993,13 +5125,15 @@ Usage:
|
|
|
4993
5125
|
oats inspect [--dir <scope>] [--soul <name> one authoritative JSON answer for a GUI: souls
|
|
4994
5126
|
[--agents-root <abs>]] [--home <abs>] (harness defaults, editability, instructions),
|
|
4995
5127
|
[--instructions] [--skills] installed capabilities with health, effective
|
|
4996
|
-
[--max-age <s>]
|
|
4997
|
-
|
|
5128
|
+
[--composed-skills] [--max-age <s>] layer bindings and activation, declared
|
|
5129
|
+
[--json] operations with availability; --home answers the
|
|
4998
5130
|
running home's recorded modules and their drift
|
|
4999
5131
|
from the deployment; --instructions (--soul only)
|
|
5000
5132
|
adds the AGENTS.md a spawn of the soul here would write;
|
|
5001
5133
|
--skills (--soul only) adds the soul's own skills, the
|
|
5002
|
-
ones a spawn copies, with each file's text
|
|
5134
|
+
ones a spawn copies, with each file's text;
|
|
5135
|
+
--composed-skills (--soul only) adds every skill a spawn
|
|
5136
|
+
would give the instance, its capabilities' included
|
|
5003
5137
|
oats operation run <layer>:<name> run an operation the soul's core capability for that
|
|
5004
5138
|
(--home <abs> | --soul <name> [--dir <d>]) layer declares (knowledge:harvest, knowledge:
|
|
5005
5139
|
[--arg k=v ...] [--json] inspect ...): resolved from the home's recorded
|
|
@@ -5096,12 +5230,27 @@ Usage:
|
|
|
5096
5230
|
oats instance attention [--message <text>] [--clear] [--json]
|
|
5097
5231
|
run by the agent from its home: "I need a human's
|
|
5098
5232
|
answer" (waiting --producer agent --reason attention)
|
|
5233
|
+
oats instance upgrade <instance> --plan [--undo] [--json]
|
|
5234
|
+
Preview package module moves and provider adoption; session must be stopped.
|
|
5235
|
+
oats instance upgrade <instance> --plan-revision <rev> --idempotency-key <key> [--undo] [--json]
|
|
5236
|
+
Move whole package modules to the verified lock; --undo uses the latest previous copies.
|
|
5099
5237
|
oats instance stop <instance> --plan [--no-recursive] [--json]
|
|
5100
5238
|
what Stop would touch: session state, recorded
|
|
5101
5239
|
children, dirty work; a planRevision to apply
|
|
5102
5240
|
oats instance stop <instance> --apply --plan-revision <rev> --idempotency-key <key>
|
|
5103
5241
|
quiesce (SIGTERM, bounded, never escalated),
|
|
5104
5242
|
children first; home/work/launch retained
|
|
5243
|
+
oats instance color <instance> (<color> | --clear) [--home <abs>] [--json]
|
|
5244
|
+
the instance's colour, presentation only: sand,
|
|
5245
|
+
sage, slate, mauve, clay or olive; --clear removes it
|
|
5246
|
+
oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi]
|
|
5247
|
+
[--model <m>] [--launch-config <n>] [--dir <d>] [--json]
|
|
5248
|
+
a name for a spawn of <soul> (only a name: it gives
|
|
5249
|
+
the role) by this machine's harness, as a preview's
|
|
5250
|
+
--suggest-name chooses it, not made unique (where it
|
|
5251
|
+
lands decides that); else numbered, and naming.reason
|
|
5252
|
+
says why. Reads only this machine's launch
|
|
5253
|
+
configurations; writes and reserves nothing; no --server
|
|
5105
5254
|
oats worktree add --purpose <p> --branch <b> --base <remote-branch> from an instance home: make the
|
|
5106
5255
|
[--repo <member key|clone path>] extra tree <home>/.work-<p> on a new branch at origin's
|
|
5107
5256
|
[--preview] [--json] <base> (the clone's refs are not moved), then run the
|
package/docs/capabilities.md
CHANGED
|
@@ -94,17 +94,19 @@ A self-contained package has an `oats.json`:
|
|
|
94
94
|
slot.
|
|
95
95
|
- `skills` entries can be skill directories or roots containing skills.
|
|
96
96
|
- `inject` is optional instance instruction Markdown.
|
|
97
|
-
- The hooks are `spawn`, `launch`, `retire` and `
|
|
98
|
-
([The worktree event](#the-worktree-event)
|
|
97
|
+
- The hooks are `spawn`, `launch`, `retire`, `worktree` and `upgrade`
|
|
98
|
+
([The worktree event](#the-worktree-event),
|
|
99
|
+
[The upgrade event](#the-upgrade-event)). A hook is a
|
|
99
100
|
command string, or `{ command, required }`. `required: true` is valid **only
|
|
100
101
|
on `spawn` and `worktree`**: a required spawn hook's failure fails the spawn
|
|
101
102
|
and rolls it back,
|
|
102
103
|
instead of producing an instance whose capability never configured itself —
|
|
103
104
|
an aweb identity that could not be minted leaves an agent believing it can be
|
|
104
105
|
woken by mail. A required `worktree` hook's failure fails the spawn the same
|
|
105
|
-
way, or removes the tree `oats worktree add` made.
|
|
106
|
-
best-effort and only
|
|
107
|
-
|
|
106
|
+
way, or removes the tree `oats worktree add` made. `launch` and `retire` stay
|
|
107
|
+
best-effort and only warn, so advisory work never becomes a spawn blocker.
|
|
108
|
+
`upgrade` has its own adoption and failure protocol and cannot be required.
|
|
109
|
+
`launch` and `retire` cannot be
|
|
108
110
|
required: they run outside a spawn transaction, so there is no moment to
|
|
109
111
|
enforce them. A `soul-scaffold` hook is tolerated and ignored.
|
|
110
112
|
- An **event this kernel does not run** (a newer kernel's) is accepted from
|
|
@@ -272,7 +274,7 @@ A self-contained package has an `oats.json`:
|
|
|
272
274
|
`.a*`);
|
|
273
275
|
- an exact name that is `.oats`, `.agents` or `.claude`, or that starts
|
|
274
276
|
with `.oats-events`, `.oats-stop`, `.oats-restart`, `.oats-rollback`,
|
|
275
|
-
`.oats-agents-md`, `.oats-start` or `.oats-
|
|
277
|
+
`.oats-agents-md`, `.oats-start`, `.oats-attachments` or `.oats-color`: the top-level
|
|
276
278
|
entries the kernel itself writes in an instance home;
|
|
277
279
|
- a prefix that starts with `.oats-`.
|
|
278
280
|
|
|
@@ -845,6 +847,53 @@ turn record's setup script (`packages/record/bin/setup.mjs`), which writes it
|
|
|
845
847
|
into the capture hooks and the capture service's unit. In the third case
|
|
846
848
|
`oats setup` carries the warning, a dry run included.
|
|
847
849
|
|
|
850
|
+
### The upgrade event
|
|
851
|
+
|
|
852
|
+
`OATS_EVENT=upgrade` lets a staged destination package module adopt the state
|
|
853
|
+
of a stopped instance, for `oats instance upgrade` and `--undo`. It runs from
|
|
854
|
+
the staged new copy, with the usual lifecycle environment plus:
|
|
855
|
+
|
|
856
|
+
- `OATS_UPGRADE_PHASE`: `plan` or `apply`;
|
|
857
|
+
- `OATS_META`: the old recorded `capabilityMeta[capability]`;
|
|
858
|
+
- `OATS_UPGRADE_FROM`: JSON containing the recorded `from`, `commit` and
|
|
859
|
+
`digest`;
|
|
860
|
+
- `OATS_UPGRADE_TO`: JSON containing the locked destination entry;
|
|
861
|
+
- `OATS_UPGRADE_MODULE_DIR`: the module's final `<home>/.oats/modules/<cap>`
|
|
862
|
+
directory. Register host artifacts against this path, never the staging path,
|
|
863
|
+
which is removed after the move.
|
|
864
|
+
|
|
865
|
+
In `plan`, the hook is read-only. It prints `{"adopt":true}`, or
|
|
866
|
+
`{"adopt":false,"reason":"…","remedy":"…"}`. A module with recorded
|
|
867
|
+
capability metadata, or whose recorded old or destination manifest declares
|
|
868
|
+
`spawn` or `launch`, must declare this
|
|
869
|
+
hook; otherwise the plan refuses it and names respawn as the remedy. A module
|
|
870
|
+
with neither state nor those hooks can move without an upgrade hook.
|
|
871
|
+
|
|
872
|
+
In `apply`, the hook may change provider state inside the home and its own
|
|
873
|
+
host registrations. On success it prints `{meta, warning?}` and exits zero;
|
|
874
|
+
the kernel records `meta` as the module's new capability metadata. Apply must
|
|
875
|
+
be idempotent. A non-zero exit must leave no effects of its own, using
|
|
876
|
+
atomicity or compensation. The kernel treats that result as a hook reporting
|
|
877
|
+
failure; rollback restores composed home bytes only, and provider host effects
|
|
878
|
+
remain the provider's responsibility. The refusal error retains a bounded
|
|
879
|
+
provider `warning`, or stderr when no warning was reported.
|
|
880
|
+
|
|
881
|
+
Before commit, a failed upgrade rolls back only if no hook succeeded and no
|
|
882
|
+
hook outcome is uncertain. A hook's non-zero result must be observed and
|
|
883
|
+
recorded in that invocation to establish that it reported failure. A killed
|
|
884
|
+
or interrupted hook has an uncertain outcome, even if no success was recorded;
|
|
885
|
+
the receipt preserves that uncertainty before retrying it. Once a hook succeeds
|
|
886
|
+
or becomes uncertain, the act only finishes forward. Retry may run the same
|
|
887
|
+
idempotent hook again; a later refusal does not permit restoring old modules.
|
|
888
|
+
Its `partial` receipt names the same idempotency key to retry pending work,
|
|
889
|
+
or respawn if it cannot finish. Start refuses a partial upgrade. See
|
|
890
|
+
[the operator workflow](upgrading.md#moving-existing-homes-to-locked-package-versions).
|
|
891
|
+
After swap and baseline commit the receipt, the kernel publishes the success
|
|
892
|
+
event and cleans staging. A failure after commit is retried without hooks or
|
|
893
|
+
copies; start is allowed with a warning naming that retry.
|
|
894
|
+
Undo uses the hook of the version being restored, so it requires that version
|
|
895
|
+
to support adoption too. The event must never declare `required: true`.
|
|
896
|
+
|
|
848
897
|
### The worktree event
|
|
849
898
|
|
|
850
899
|
`OATS_EVENT=worktree` (OATS 0.49.0) lets a capability set up a Git tree the
|
|
@@ -996,15 +1045,15 @@ latest-state capability.
|
|
|
996
1045
|
### oats.core: needs input
|
|
997
1046
|
|
|
998
1047
|
oats.core (2.4.0 and later, kernel 0.40.0 and later) tells the deployment
|
|
999
|
-
when an instance is
|
|
1048
|
+
when an instance is waiting on a human, in two independent ways. Each shows
|
|
1000
1049
|
on `oats status` and in `oats instance events`. The verbs' contract
|
|
1001
1050
|
(`oats instance waiting`, `oats instance attention`, the `waiting` event) is
|
|
1002
1051
|
in [desktop-cli-api.md](desktop-cli-api.md#waiting-on-you). Claims are
|
|
1003
1052
|
display-only: nothing in the kernel acts on them.
|
|
1004
1053
|
|
|
1005
1054
|
**The agent's own claim.** The oats.core inject and `/oats-operate` teach
|
|
1006
|
-
every instance this protocol.
|
|
1007
|
-
|
|
1055
|
+
every instance this protocol. Whenever it needs anything from a human (a
|
|
1056
|
+
question, a decision, an approval, a credential, any input it waits on), it runs
|
|
1008
1057
|
`oats instance attention --message "<one line>"` from its home and ends its
|
|
1009
1058
|
turn. Once it has the answer, it runs `oats instance attention --clear`. The
|
|
1010
1059
|
claim belongs to producer `agent`. Only `--clear` or the next session start,
|
|
@@ -302,6 +302,10 @@
|
|
|
302
302
|
},
|
|
303
303
|
"retire": {"$ref":"#/$defs/OptionalHook"},
|
|
304
304
|
"launch": {"$ref":"#/$defs/OptionalHook"},
|
|
305
|
+
"upgrade": {
|
|
306
|
+
"$ref":"#/$defs/OptionalHook",
|
|
307
|
+
"description":"Runs from the staged destination module for a stopped home's package upgrade or undo. OATS_UPGRADE_PHASE=plan is read-only and prints {adopt:true} or {adopt:false,reason,remedy}; apply prints {meta,warning?} on success. A non-zero apply must leave no provider effects through atomicity or compensation: kernel rollback covers composed home bytes only. Receives OATS_META (recorded state), OATS_UPGRADE_FROM (recorded from/commit/digest) and OATS_UPGRADE_TO (locked destination entry) as JSON. Never required."
|
|
308
|
+
},
|
|
305
309
|
"worktree": {
|
|
306
310
|
"description": "Runs once in each tree the kernel creates: ./work of a work: worktree spawn (after the spawn hooks) and each `oats worktree add`. Its cwd is the new tree; see docs/capabilities.md, The worktree event.",
|
|
307
311
|
"oneOf":[
|
|
@@ -362,7 +366,7 @@
|
|
|
362
366
|
"description": "Home entries the kernel owns cannot be declared.",
|
|
363
367
|
"anyOf": [
|
|
364
368
|
{"pattern": "^\\.(?:oats|agents|claude)$"},
|
|
365
|
-
{"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments)"},
|
|
369
|
+
{"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color)"},
|
|
366
370
|
{"pattern": "^\\.oats-.*\\*$"}
|
|
367
371
|
]
|
|
368
372
|
}
|