@awebai/oats 0.66.0 → 0.67.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 +66 -13
- package/docs/capabilities.md +4 -4
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/desktop-cli-api.md +217 -6
- package/docs/desktop.md +101 -22
- package/docs/implementation.md +6 -5
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- 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/servers.md +3 -2
- package/docs/souls-and-instances.md +20 -3
- package/docs/tui.md +570 -176
- package/docs/upgrading.md +107 -25
- package/docs/workspaces.md +1 -1
- package/lib/capability-contract.mjs +2 -2
- package/lib/core.mjs +126 -54
- package/lib/instance-color.mjs +58 -0
- 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 +5 -1
- package/lib/materialize.mjs +62 -11
- package/lib/servers.mjs +15 -6
- package/lib/soul-composition.mjs +7 -3
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +37 -5
- 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 +3 -1
- 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 +85 -24
- package/packages/client/keys-file.mjs +122 -0
- package/packages/client/own-codes.mjs +4 -2
- package/packages/client/panel-views.mjs +62 -9
- package/packages/client/spawn-naming.mjs +31 -0
- package/packages/client/spawn-preview-cli.mjs +22 -7
- package/packages/client/spawn-preview-contract.mjs +24 -0
- package/packages/client/spawn-preview-facts.mjs +8 -4
- package/packages/client/spawn-preview.mjs +47 -2
- package/packages/tui/README.md +3 -3
- package/packages/tui/lib/actions.mjs +57 -14
- package/packages/tui/lib/client.mjs +8 -4
- package/packages/tui/lib/config.mjs +50 -9
- package/packages/tui/lib/main.mjs +40 -13
- package/packages/tui/lib/model.mjs +167 -63
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +148 -54
- package/packages/tui/lib/term/keys.mjs +19 -5
- package/packages/tui/lib/term/kitty.mjs +36 -11
- package/packages/tui/lib/term/through.mjs +61 -28
- package/packages/tui/lib/views/frame.mjs +158 -79
- package/packages/tui/lib/views/help.mjs +109 -26
- package/packages/tui/lib/views/instances.mjs +59 -20
- 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/skills/oats-getting-started/SKILL.md +13 -8
package/bin/oats.mjs
CHANGED
|
@@ -60,18 +60,18 @@ import { kernelNode, stableNode } from "../lib/stable-node.mjs";
|
|
|
60
60
|
import { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } from "../lib/attachments.mjs";
|
|
61
61
|
|
|
62
62
|
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";
|
|
63
|
+
import { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance as resolveInstanceForCli, setInstanceColor, STOP_WARNINGS } from "../lib/instance-lifecycle.mjs";
|
|
64
64
|
import { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } from "../lib/retire-output.mjs";
|
|
65
65
|
import { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } from "../lib/retained-after-retire.mjs";
|
|
66
66
|
const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
|
|
67
|
-
import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument,
|
|
67
|
+
import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposition, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } from "../lib/instance-inspect.mjs";
|
|
68
68
|
import { readEvents, setWaiting, incarnationOf } from "../lib/instance-events.mjs";
|
|
69
69
|
import { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } from "../lib/deployments.mjs";
|
|
70
70
|
import { observeResolvedDeployment } from "../lib/resolved-deployment.mjs";
|
|
71
71
|
|
|
72
72
|
const rawArgs = process.argv.slice(2);
|
|
73
73
|
/** 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"]);
|
|
74
|
+
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
75
|
/** `--flag=value` is `--flag value`: every kernel reader (flag(), valueFlag(), the onboard and
|
|
76
76
|
* routed-command loops) then applies the spaced form's validation to it. `problem` is an empty
|
|
77
77
|
* `--flag=`, a switch given a value, or a value that is itself an option (`--model=--yolo`):
|
|
@@ -107,7 +107,7 @@ const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental",
|
|
|
107
107
|
* probe) and in `status --json`, which a remote roster relays as the host's (feature
|
|
108
108
|
* server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
|
|
109
109
|
* 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"];
|
|
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", "soul-composed-skills", "instance-color", "spawn-suggest-name"];
|
|
111
111
|
/** Commands `--server <id>` runs on a registered server. */
|
|
112
112
|
const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
|
|
113
113
|
const flag = (name) => {
|
|
@@ -572,10 +572,13 @@ async function inspectCmd() {
|
|
|
572
572
|
// Feature soul-skills: opt-in, soul subject only; without it no skill file is read.
|
|
573
573
|
const skills = args.includes("--skills");
|
|
574
574
|
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/)");
|
|
575
|
+
// Feature soul-composed-skills: opt-in, soul subject only; it shares --instructions' one scratch composition.
|
|
576
|
+
const composedSkills = args.includes("--composed-skills");
|
|
577
|
+
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
578
|
let t = await workspaceTarget(bail, { command: "inspect" });
|
|
576
579
|
if (t) {
|
|
577
580
|
if (t.resolutionError) return bail(t.resolutionError.code, t.resolutionError.message, t.resolutionError.details ?? undefined);
|
|
578
|
-
if (instructions) t = await
|
|
581
|
+
if (instructions || composedSkills) t = await withComposition(t, { instructions, skills: composedSkills });
|
|
579
582
|
if (skills) t = await withSkills(t);
|
|
580
583
|
const doc = inspectDocument(t, { kernel: OATS_VERSION });
|
|
581
584
|
if (JSON_MODE) { jsonOk(withObservation(doc)); return; }
|
|
@@ -628,6 +631,11 @@ function printWorkspaceInspect(doc) {
|
|
|
628
631
|
for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
|
|
629
632
|
const composed = doc.souls[0].composedInstructions;
|
|
630
633
|
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)");
|
|
634
|
+
const composedSkills = doc.souls[0].composedSkills;
|
|
635
|
+
if (composedSkills !== undefined) {
|
|
636
|
+
if (!composedSkills) console.log("\nComposed skills: unavailable (see the problems above)");
|
|
637
|
+
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)}`); }
|
|
638
|
+
}
|
|
631
639
|
}
|
|
632
640
|
|
|
633
641
|
/** `{ teams, defaultTeam, teamsSource }` for a session start of a workspace home: its teams read
|
|
@@ -1314,8 +1322,8 @@ function instanceCmd() {
|
|
|
1314
1322
|
const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
|
|
1315
1323
|
const sub = args[1], name = args[2];
|
|
1316
1324
|
if (sub === "waiting" || sub === "attention") return instanceWaitingCmd(sub, bail);
|
|
1317
|
-
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]";
|
|
1318
|
-
if (!["git", "diff", "stop", "events"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
|
|
1325
|
+
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]";
|
|
1326
|
+
if (!["git", "diff", "stop", "events", "color"].includes(sub) || !name || name.startsWith("--")) return bail("E_BAD_ARGS", usage);
|
|
1319
1327
|
dropAmbientRoot();
|
|
1320
1328
|
if (sub === "events") {
|
|
1321
1329
|
// K7: typed producer events, bounded window; nothing inferred.
|
|
@@ -1348,6 +1356,29 @@ function instanceCmd() {
|
|
|
1348
1356
|
return;
|
|
1349
1357
|
} catch (e) { return bail(e.code || "E_EVENTS_FAILED", e.message, e.candidates ? { candidates: e.candidates } : undefined); }
|
|
1350
1358
|
}
|
|
1359
|
+
if (sub === "color") {
|
|
1360
|
+
// Feature instance-color: presentation only, so no plan; addressed as stop addresses an instance.
|
|
1361
|
+
const homeOpt = flag("home");
|
|
1362
|
+
if (homeOpt === true || (homeOpt !== undefined && !isAbsolute(homeOpt))) return bail("E_BAD_ARGS", "--home needs an absolute instance home");
|
|
1363
|
+
const colorUsage = "usage: oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json]";
|
|
1364
|
+
// The words after the instance that are not a flag or the value of --home or --dir: the colour, at most one.
|
|
1365
|
+
const words = [];
|
|
1366
|
+
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]); }
|
|
1367
|
+
const clear = args.includes("--clear");
|
|
1368
|
+
if (words.length > 1) return bail("E_BAD_ARGS", `oats instance color takes one colour; ${colorUsage}`);
|
|
1369
|
+
const value = words[0];
|
|
1370
|
+
if (value !== undefined && clear) return bail("E_BAD_ARGS", `give a colour or --clear, not both; ${colorUsage}`);
|
|
1371
|
+
if (value === undefined && !clear) return bail("E_BAD_ARGS", `give a colour or --clear; ${colorUsage}`);
|
|
1372
|
+
let root; try { root = ensureRoot(dirFlag()); } catch (e) { return lifecycleFail(e, "E_NO_ROOT"); }
|
|
1373
|
+
try {
|
|
1374
|
+
const r = setInstanceColor(dirFlag(), root, name, { home: homeOpt, color: clear ? null : value });
|
|
1375
|
+
if (JSON_MODE) { jsonOk(r); return; }
|
|
1376
|
+
console.log(`${r.instance}: ${r.color === null ? "no colour" : `colour ${r.color}`}${r.changed ? "" : " (unchanged)"}`);
|
|
1377
|
+
return;
|
|
1378
|
+
} catch (e) {
|
|
1379
|
+
return lifecycleFail(e, "E_LIFECYCLE_FAILED", e.candidates ? { candidates: e.candidates } : e.details);
|
|
1380
|
+
}
|
|
1381
|
+
}
|
|
1351
1382
|
if (sub === "stop") {
|
|
1352
1383
|
// K3: plan → apply. The plan is what a confirmation shows; apply carries
|
|
1353
1384
|
// its revision back and refuses if reality moved.
|
|
@@ -2701,7 +2732,15 @@ const livenessWord = (i) => i.running === true ? "RUNNING" : i.running === false
|
|
|
2701
2732
|
* host through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an
|
|
2702
2733
|
* apply bound by --expect-decision: the dispatch allow-list (maxAgeRefusal) refuses it otherwise. */
|
|
2703
2734
|
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"]);
|
|
2735
|
+
const SPAWN_SWITCHES = new Set(["allow-child-spawns", "json", "no-child-spawns", "no-launch", "no-yolo", "preview", "suggest-name", "yolo"]);
|
|
2736
|
+
/** `--suggest-name` (feature spawn-suggest-name): a preview's, with no --name or --purpose. The kernel
|
|
2737
|
+
* refuses the same (core.mjs spawnBody); the CLI says it before anything is read or sent. */
|
|
2738
|
+
function suggestNameProblem(argv) {
|
|
2739
|
+
if (!argv.includes("--suggest-name")) return undefined;
|
|
2740
|
+
if (!argv.includes("--preview")) return "--suggest-name is a preview's: it chooses the name a spawn would get; pass --preview";
|
|
2741
|
+
if (argv.some((a) => ["--name", "--purpose"].includes(a.split("=")[0]))) return "--suggest-name chooses the name: it takes no --name or --purpose";
|
|
2742
|
+
return undefined;
|
|
2743
|
+
}
|
|
2705
2744
|
/** Why `argv` (after `spawn`, the soul first) is not a spawn, or undefined: a positional after the
|
|
2706
2745
|
* soul or a flag spawn does not read is never ignored. A value flag consumes its value exactly as
|
|
2707
2746
|
* flag() reads it; a missing value is the flag's own check. */
|
|
@@ -2734,6 +2773,9 @@ function printSpawnPreview(r, { server, soulFetched = false } = {}) {
|
|
|
2734
2773
|
// A host before 0.27 names the harness `runtime` (it still answers spawn-preview-2).
|
|
2735
2774
|
const harness = r.harness ?? r.runtime;
|
|
2736
2775
|
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)" : ""}`);
|
|
2776
|
+
// Feature spawn-suggest-name: how the name was chosen.
|
|
2777
|
+
if (r.naming?.source === "suggested") console.log(`name: suggested by ${terminalText(r.naming.harness)}${r.naming.model ? ` (${terminalText(r.naming.model)})` : ""} in ${r.naming.ms} ms`);
|
|
2778
|
+
else if (r.naming?.source === "numbered") console.log(`name: numbered (${terminalText(r.naming.reason)}: ${terminalText(r.naming.message)})`);
|
|
2737
2779
|
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
2780
|
for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
|
|
2739
2781
|
}
|
|
@@ -2752,7 +2794,7 @@ async function spawnCmd() {
|
|
|
2752
2794
|
};
|
|
2753
2795
|
checkDirectoryOptions(requestedWork); // before anything is resolved or written
|
|
2754
2796
|
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>] [--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]");
|
|
2797
|
+
if (!name || name.startsWith("--")) bail("E_USAGE", "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>] [--preview [--suggest-name]] [--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
2798
|
// Retired boundary flags (maintainer transport ruling): fail LOUDLY before
|
|
2757
2799
|
// ANY side effect, including root discovery.
|
|
2758
2800
|
// Local souls (local-agents/) are gone with the workspace model: a soul is a member
|
|
@@ -2763,6 +2805,7 @@ async function spawnCmd() {
|
|
|
2763
2805
|
const nameFlag = flag("name");
|
|
2764
2806
|
if (nameFlag === true) bail("E_BAD_ARGS", "--name needs an instance name (a slug: lowercase letters and digits, single dashes between them)");
|
|
2765
2807
|
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>");
|
|
2808
|
+
{ const problem = suggestNameProblem(args); if (problem) bail("E_BAD_ARGS", problem); }
|
|
2766
2809
|
// The slug rule is checked here too, before any side effect (soul fetch).
|
|
2767
2810
|
if (nameFlag !== undefined) { try { explicitInstanceName(String(nameFlag)); } catch (e) { bail(e.code, e.message); throw e; } }
|
|
2768
2811
|
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 +3000,7 @@ async function spawnCmd() {
|
|
|
2957
3000
|
// K6: --preview decides everything and touches nothing; --base <ref>
|
|
2958
3001
|
// selects a worktree's start point; --model @native-default is the
|
|
2959
3002
|
// explicit "harness's own default" (distinct from omitting --model).
|
|
3003
|
+
...(args.includes("--suggest-name") ? { suggestName: true } : {}),
|
|
2960
3004
|
...(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
3005
|
...(flag("base") !== undefined && flag("base") !== true ? { baseRef: flag("base") } : {}),
|
|
2962
3006
|
// A confirmed preview binds this apply (K6b): drift → E_DECISION_STALE, nothing created.
|
|
@@ -4534,7 +4578,7 @@ async function serverRouteCmd() {
|
|
|
4534
4578
|
const herdr = herdrSpawnFlag();
|
|
4535
4579
|
if (herdr) { const e = herdrSettingRemoved(`${herdr} was given`); bail(e.code, e.message); }
|
|
4536
4580
|
const local = args.slice(1).filter((a, i, all) => a !== "--server" && all[i - 1] !== "--server");
|
|
4537
|
-
const problem = spawnArgvProblem(local);
|
|
4581
|
+
const problem = spawnArgvProblem(local) ?? suggestNameProblem(local);
|
|
4538
4582
|
if (problem) bail("E_BAD_ARGS", problem);
|
|
4539
4583
|
}
|
|
4540
4584
|
// Everything after the command word travels, minus the routing flags; a
|
|
@@ -4961,6 +5005,10 @@ Usage:
|
|
|
4961
5005
|
instance.json providers.<capability>)
|
|
4962
5006
|
[--preview] decide everything, create no instance; --json
|
|
4963
5007
|
includes the decision revision for confirmation
|
|
5008
|
+
[--suggest-name] with --preview, no --name or --purpose: the soul's
|
|
5009
|
+
harness names the instance for its task
|
|
5010
|
+
(<descriptive>-<role>); else it is numbered, and
|
|
5011
|
+
naming.reason says why (claude and pi)
|
|
4964
5012
|
[--expect-decision <rev>] bind apply to the previewed decision; drift refuses
|
|
4965
5013
|
[--idempotency-key <key>] with --expect-decision, replay the completed receipt
|
|
4966
5014
|
for the same key and confirmed decision; a different
|
|
@@ -4993,13 +5041,15 @@ Usage:
|
|
|
4993
5041
|
oats inspect [--dir <scope>] [--soul <name> one authoritative JSON answer for a GUI: souls
|
|
4994
5042
|
[--agents-root <abs>]] [--home <abs>] (harness defaults, editability, instructions),
|
|
4995
5043
|
[--instructions] [--skills] installed capabilities with health, effective
|
|
4996
|
-
[--max-age <s>]
|
|
4997
|
-
|
|
5044
|
+
[--composed-skills] [--max-age <s>] layer bindings and activation, declared
|
|
5045
|
+
[--json] operations with availability; --home answers the
|
|
4998
5046
|
running home's recorded modules and their drift
|
|
4999
5047
|
from the deployment; --instructions (--soul only)
|
|
5000
5048
|
adds the AGENTS.md a spawn of the soul here would write;
|
|
5001
5049
|
--skills (--soul only) adds the soul's own skills, the
|
|
5002
|
-
ones a spawn copies, with each file's text
|
|
5050
|
+
ones a spawn copies, with each file's text;
|
|
5051
|
+
--composed-skills (--soul only) adds every skill a spawn
|
|
5052
|
+
would give the instance, its capabilities' included
|
|
5003
5053
|
oats operation run <layer>:<name> run an operation the soul's core capability for that
|
|
5004
5054
|
(--home <abs> | --soul <name> [--dir <d>]) layer declares (knowledge:harvest, knowledge:
|
|
5005
5055
|
[--arg k=v ...] [--json] inspect ...): resolved from the home's recorded
|
|
@@ -5102,6 +5152,9 @@ Usage:
|
|
|
5102
5152
|
oats instance stop <instance> --apply --plan-revision <rev> --idempotency-key <key>
|
|
5103
5153
|
quiesce (SIGTERM, bounded, never escalated),
|
|
5104
5154
|
children first; home/work/launch retained
|
|
5155
|
+
oats instance color <instance> (<color> | --clear) [--home <abs>] [--json]
|
|
5156
|
+
the instance's colour, presentation only: sand,
|
|
5157
|
+
sage, slate, mauve, clay or olive; --clear removes it
|
|
5105
5158
|
oats worktree add --purpose <p> --branch <b> --base <remote-branch> from an instance home: make the
|
|
5106
5159
|
[--repo <member key|clone path>] extra tree <home>/.work-<p> on a new branch at origin's
|
|
5107
5160
|
[--preview] [--json] <base> (the clone's refs are not moved), then run the
|
package/docs/capabilities.md
CHANGED
|
@@ -272,7 +272,7 @@ A self-contained package has an `oats.json`:
|
|
|
272
272
|
`.a*`);
|
|
273
273
|
- an exact name that is `.oats`, `.agents` or `.claude`, or that starts
|
|
274
274
|
with `.oats-events`, `.oats-stop`, `.oats-restart`, `.oats-rollback`,
|
|
275
|
-
`.oats-agents-md`, `.oats-start` or `.oats-
|
|
275
|
+
`.oats-agents-md`, `.oats-start`, `.oats-attachments` or `.oats-color`: the top-level
|
|
276
276
|
entries the kernel itself writes in an instance home;
|
|
277
277
|
- a prefix that starts with `.oats-`.
|
|
278
278
|
|
|
@@ -996,15 +996,15 @@ latest-state capability.
|
|
|
996
996
|
### oats.core: needs input
|
|
997
997
|
|
|
998
998
|
oats.core (2.4.0 and later, kernel 0.40.0 and later) tells the deployment
|
|
999
|
-
when an instance is
|
|
999
|
+
when an instance is waiting on a human, in two independent ways. Each shows
|
|
1000
1000
|
on `oats status` and in `oats instance events`. The verbs' contract
|
|
1001
1001
|
(`oats instance waiting`, `oats instance attention`, the `waiting` event) is
|
|
1002
1002
|
in [desktop-cli-api.md](desktop-cli-api.md#waiting-on-you). Claims are
|
|
1003
1003
|
display-only: nothing in the kernel acts on them.
|
|
1004
1004
|
|
|
1005
1005
|
**The agent's own claim.** The oats.core inject and `/oats-operate` teach
|
|
1006
|
-
every instance this protocol.
|
|
1007
|
-
|
|
1006
|
+
every instance this protocol. Whenever it needs anything from a human (a
|
|
1007
|
+
question, a decision, an approval, a credential, any input it waits on), it runs
|
|
1008
1008
|
`oats instance attention --message "<one line>"` from its home and ends its
|
|
1009
1009
|
turn. Once it has the answer, it runs `oats instance attention --clear`. The
|
|
1010
1010
|
claim belongs to producer `agent`. Only `--clear` or the next session start,
|
|
@@ -362,7 +362,7 @@
|
|
|
362
362
|
"description": "Home entries the kernel owns cannot be declared.",
|
|
363
363
|
"anyOf": [
|
|
364
364
|
{"pattern": "^\\.(?:oats|agents|claude)$"},
|
|
365
|
-
{"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments)"},
|
|
365
|
+
{"pattern": "^\\.oats-(?:events|stop|restart|rollback|agents-md|start|attachments|color)"},
|
|
366
366
|
{"pattern": "^\\.oats-.*\\*$"}
|
|
367
367
|
]
|
|
368
368
|
}
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -119,6 +119,8 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
119
119
|
| `souls-capabilities` | `capabilities` on `oats souls --json` rows: the capabilities each soul composes, keyed like `oats capabilities` rows, with `from`, OATS 0.45.0 ([`oats capabilities` and `oats souls`](#oats-capabilities---dir---json--capabilitiesapi-1--oats-souls---dir---json--soulsapi-1)) | |
|
|
120
120
|
| `soul-composed-instructions` | `oats inspect --soul <soul> --instructions` and its `souls[].composedInstructions`: the AGENTS.md a spawn of the soul here would write, with the soul body and each composed block as ranges, OATS 0.46.0 ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
|
|
121
121
|
| `soul-skills` | `oats inspect --soul <soul> --skills` and its `souls[].skills`: the soul's own skills, the ones a spawn of it copies, with each file's text ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
|
|
122
|
+
| `soul-composed-skills` | `oats inspect --soul <soul> --composed-skills` and its `souls[].composedSkills`: every skill a spawn of the soul gives its instance, its own and its capabilities', each with its `source` and each file's text ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)). The same kernels name each capability skill of `spawn --preview`'s `skills[]` as the spawn does ([The preview](#the-preview)) | |
|
|
123
|
+
| `spawn-suggest-name` | `oats spawn <soul> --preview --suggest-name`: the preview also chooses the name, from the task, through the soul's own harness, and says how in `naming` ([The suggested name](#the-suggested-name-feature-spawn-suggest-name)). Suggested names work on claude and pi; codex is numbered (`unsupported-harness`). Routed, the host needs the feature | |
|
|
122
124
|
| `teams-conditional-default` | `oats teams default <label> --if-absent \| --expect <label>` and `E_TEAM_DEFAULT_MISMATCH`; `oats teams add … --no-default` and its `reused` answer; `E_TEAM_EXISTS` `observed`; unknown flags on `oats teams` refused, OATS 0.48.0 ([`oats teams`](#oats-teams)). A kernel without it ignores the flags: `--if-absent` there is an unconditional set, so check the feature before passing them | |
|
|
123
125
|
| `worktree-event` | the `worktree` hook event; `oats worktree add\|remove` ([`oats worktree`](#oats-worktree)); `worktreeHooks` on `spawn --preview` and on the spawn result and `spawned` event; `spawnInProgress` on `oats status --json` instance rows; the `worktree-added` event kind; `E_INTERRUPTED` and `E_WORKTREE_DIRTY`, OATS 0.49.0 | |
|
|
124
126
|
| `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
|
|
@@ -135,6 +137,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
135
137
|
| `spawn-kernel-codes` | `oats spawn`, apply and `--preview`, answers the kernel's own code, as raised, whatever stage of the spawn raised it; `E_SPAWN_FAILED` is for an error with no kernel code (with `details.cause`, as the lifecycle commands' general codes have it). A code says nothing about how far the spawn got: `details.unconfirmed` does. Details are those each code had before; OATS 0.56.0 ([spawn errors](#spawn-errors)). A kernel without it answers `E_SPAWN_FAILED` for most kernel codes its kernel stage raised: there, that code may hide one | |
|
|
136
138
|
| `roster-workspace-key` | `oats server roster --workspace-key <key>`, repeatable: only the groups that can belong to one of the given workspaces are probed and returned (registered for one of them, registered with no known `workspaceKey`, or saved routes only); the answer's shape is unchanged, OATS 0.56.0 ([The remote roster](#roster-workspace-key)). Gate on the probe: a kernel without it ignores the flag and probes and answers every group | |
|
|
137
139
|
| `spawn-apply-max-age` | `--max-age <s>` on a spawn apply bound by `--expect-decision <revision>`: the apply reuses member heads as the preview does, its decision fence unchanged, and its answer carries no `observation` block, OATS 0.58.0 ([Apply](#apply)). Gate on the probe: a kernel without it refuses the flag on an apply (`E_BAD_ARGS`) | |
|
|
140
|
+
| `instance-color` | `oats instance color <instance> (<color> \| --clear)`, local and `--server` ([An instance's colour](#an-instances-colour-oats-instance-color)); `color` on `oats status --json` instance rows, on `oats server roster --json` rows and on `oats inspect --home` `instance` (`null` for none). Gate on the probe, locally or in the host's `probe.features`: an older kernel's rows have no `color` | `instanceColorApi: 1` (payload only) |
|
|
138
141
|
| `deployments-list` | `oats deployments [list]\|add\|remove\|import --json`, this computer's list of its deployments (`~/.oats/config/deployments.json`); `listed` on `oats onboard --json`; a kernel command run in an unlisted deployment lists it ([This computer's deployments](#this-computers-deployments-oats-deployments)). Gate on the probe: there is no fallback scan | `deploymentsApi: 1` |
|
|
139
142
|
| `status-retire-state` | `retire` on `oats status --json` instance rows and on remote roster rows: whether a retire of the home is running, cannot be told, failed or was interrupted, read only from the files beside the home, OATS 0.59.0 ([`retire`](#row-retire)). `retirePending` is unchanged. Gate on the probe: a kernel without it never carries the field, so its absence there says nothing | |
|
|
140
143
|
|
|
@@ -437,7 +440,7 @@ A module's origin (`from`) is `{kind: "member", repoKey, commit}` or `{kind:
|
|
|
437
440
|
### `oats inspect`
|
|
438
441
|
|
|
439
442
|
```text
|
|
440
|
-
oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills]) [--max-age <s>] --json
|
|
443
|
+
oats inspect (--home <abs> | --soul <name> [--dir <d>] [--instructions] [--skills] [--composed-skills]) [--max-age <s>] --json
|
|
441
444
|
```
|
|
442
445
|
|
|
443
446
|
An instance subject, abridged:
|
|
@@ -463,7 +466,7 @@ An instance subject, abridged:
|
|
|
463
466
|
"recordedDefaultTeam":{"label":"eng","team":null,"from":"soul"},
|
|
464
467
|
"knowledge":{"provider":"oats.okf","version":"2.1.3","operations":[{"name":"status","kind":"view","available":true,"reason":null}]},
|
|
465
468
|
"instance":{"home":"/w/agents/rm/instances/rm-1","instance":"rm-1","agent":"rm","harness":"pi","model":null,"yolo":null,"launched":false,
|
|
466
|
-
"createdAt":"2026-09-28T10:08:01.281Z","resolution":"abacbdb5a7975098d77007c8","soulDir":"/w/agents/rm/souls/66566512168e",
|
|
469
|
+
"createdAt":"2026-09-28T10:08:01.281Z","color":null,"resolution":"abacbdb5a7975098d77007c8","soulDir":"/w/agents/rm/souls/66566512168e",
|
|
467
470
|
"instructions":{"file":"/w/agents/rm/instances/rm-1/AGENTS.md","text":"…","truncated":false,
|
|
468
471
|
"sources":[{"source":"capability:oats.okf","file":"/w/agents/rm/instances/rm-1/.oats/modules/oats.okf/injects/okf.md"}]}},
|
|
469
472
|
"identity":null,
|
|
@@ -479,7 +482,7 @@ An instance subject, abridged:
|
|
|
479
482
|
| `capabilities`, `capabilitiesOff` | the resolved modules (by id) and the ones the soul turned off |
|
|
480
483
|
| `teams`, `defaultTeam`, `teamsSource`, `recordedDefaultTeam` | [Where teams appear](#where-teams-appear); `recordedDefaultTeam` is home only |
|
|
481
484
|
| `knowledge` | `{provider, version, operations: [{name, kind, available, reason}]}` for the knowledge slot (`null`s and `[]` when empty) |
|
|
482
|
-
| `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order |
|
|
485
|
+
| `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order. `color` (feature `instance-color`) is the instance's colour or `null` ([An instance's colour](#an-instances-colour-oats-instance-color)) |
|
|
483
486
|
| `identity` | home only (absent for a soul): the served identity a messaging provider recorded, `{…, provider}`, or `null`. Read on every call, so after a start whose launch hook returned new `meta` it is that start's record, not the spawn's |
|
|
484
487
|
| `problems` | below |
|
|
485
488
|
| `warnings` | always present (0.49.0): [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490); for `--home`, `path` is home-relative |
|
|
@@ -588,6 +591,48 @@ probe does not advertise `soul-skills` is refused with `E_REMOTE_INCOMPATIBLE`,
|
|
|
588
591
|
and nothing is sent. Every text is untrusted repository content: render it as
|
|
589
592
|
plain text or through a sanitising renderer.
|
|
590
593
|
|
|
594
|
+
`composedSkills` (feature `soul-composed-skills`) is present only with
|
|
595
|
+
`--composed-skills`, which takes a soul subject (`--home` is `E_BAD_ARGS`) and
|
|
596
|
+
combines with `--instructions` and `--skills`; without the flag the key is
|
|
597
|
+
absent and nothing extra is composed. It lists every skill an instance of this
|
|
598
|
+
soul gets: the soul's own and each capability's.
|
|
599
|
+
|
|
600
|
+
```json
|
|
601
|
+
"composedSkills":[{"name":"oats-operate","source":"module:oats.core","path":".oats/modules/oats.core/skills/oats-operate",
|
|
602
|
+
"description":"…","files":[{"path":".oats/modules/oats.core/skills/oats-operate/SKILL.md","bytes":1234,"text":"…","binary":false,"truncated":false}],
|
|
603
|
+
"filesTruncated":false},
|
|
604
|
+
{"name":"release-checklist","source":"soul","path":"skills/release-checklist","description":"Cutting a release.",
|
|
605
|
+
"files":[…],"filesTruncated":false}]
|
|
606
|
+
```
|
|
607
|
+
|
|
608
|
+
- One row per skill, sorted by `name` in codepoint order. `source` is
|
|
609
|
+
`"soul"` or `"module:<capability id>"`, the vocabulary of `instance.json`
|
|
610
|
+
`skills` and of the spawn preview.
|
|
611
|
+
- `path` is POSIX. A soul skill's is relative to the soul directory, as in
|
|
612
|
+
`skills`; a capability skill's is relative to the instance home, where the
|
|
613
|
+
instance carries the capability's copy (`.oats/modules/<id>/…`). Each
|
|
614
|
+
file's `path` starts with its skill's.
|
|
615
|
+
- The rest of a row, and every rule for its files, is `skills`' above, with
|
|
616
|
+
one difference: the whole field carries at most 2 MiB (2,097,152 bytes) of
|
|
617
|
+
`text`, summed over every file in answer order, whichever source it comes
|
|
618
|
+
from. Problems name `composedSkills: ` instead of `skills: `.
|
|
619
|
+
- It is computed by the same scratch materialization as `--instructions`
|
|
620
|
+
(one serves both when both are given): the soul's skills by the
|
|
621
|
+
enumerator spawn uses, read from the soul copy, and the capability skills
|
|
622
|
+
materialize placed, read from the scratch copy before it is removed. It
|
|
623
|
+
runs no hooks and writes nothing in the deployment.
|
|
624
|
+
- It is `null` when a spawn would refuse a collision between a soul skill and
|
|
625
|
+
a capability skill (names compare case-insensitively), with the problem
|
|
626
|
+
`{code: "E_SKILL_DUPLICATE", message: "composedSkills: skill \"<name>\"
|
|
627
|
+
from soul collides with module <id>'s skill"}`, the sentence spawn refuses
|
|
628
|
+
with. It is `null` when the soul resolves but cannot be composed here, with
|
|
629
|
+
the composition's code and sentence, naming `composedSkills`. It is `null`
|
|
630
|
+
with `soul-skills-unreadable` when the soul's own skills cannot be listed.
|
|
631
|
+
|
|
632
|
+
Routed with `--server <id>`, `--composed-skills` travels to the host; a host
|
|
633
|
+
whose probe does not advertise `soul-composed-skills` is refused with
|
|
634
|
+
`E_REMOTE_INCOMPATIBLE`, and nothing is sent.
|
|
635
|
+
|
|
591
636
|
**Layers.** `id` is the capability filling the slot or `null`. `from`
|
|
592
637
|
(feature `layers-from`) is `"soul"` or `"workspace"`, `null` for an empty slot
|
|
593
638
|
or a home spawned before it was recorded.
|
|
@@ -2430,7 +2475,13 @@ it to a temporary copy (`soulFetched: true`).
|
|
|
2430
2475
|
- `capabilities[]` (`{name, origin}`, `origin` `package:<id>@<v>` or
|
|
2431
2476
|
`member:<repoKey>@<commit>`) and `skills[]` (the soul's own skills as
|
|
2432
2477
|
strings, module skills as `{name, source: "module:<cap>"}`) are display
|
|
2433
|
-
only: bind to `modules[]` and `decision`.
|
|
2478
|
+
only: bind to `modules[]` and `decision`. A module skill's `name` is a
|
|
2479
|
+
skill the spawn copies, by the rule it copies by: a manifest entry that
|
|
2480
|
+
holds skill directories lists each of them, and a manifest with no
|
|
2481
|
+
`skills` lists each `skills/<dir>/` holding a `SKILL.md`, read at the
|
|
2482
|
+
module's commit (feature `soul-composed-skills`; earlier kernels named such
|
|
2483
|
+
an entry by its own directory, `skills`, and listed nothing for a manifest
|
|
2484
|
+
with no `skills`).
|
|
2434
2485
|
- `resolution` (24 hex) hashes `declRevision` (the declarations) and
|
|
2435
2486
|
`payloadRevision` (the merged payloads). `workspace` is the host key;
|
|
2436
2487
|
`standalone` marks a standalone view. `task` is the task text or `null`.
|
|
@@ -2450,6 +2501,102 @@ it to a temporary copy (`soulFetched: true`).
|
|
|
2450
2501
|
new head and revision. An apply with `--expect-decision` may reuse heads
|
|
2451
2502
|
too (feature `spawn-apply-max-age`, [Apply](#apply)).
|
|
2452
2503
|
|
|
2504
|
+
#### The suggested name (feature `spawn-suggest-name`)
|
|
2505
|
+
|
|
2506
|
+
```text
|
|
2507
|
+
oats spawn <soul> --preview --suggest-name --task-file <f> [the flags of a real spawn] [--json]
|
|
2508
|
+
```
|
|
2509
|
+
|
|
2510
|
+
A preview that also chooses the instance's name, from the task (`--task-file`,
|
|
2511
|
+
or `--task <text>`). Like every preview it writes nothing and runs no hooks.
|
|
2512
|
+
- `--suggest-name` without `--preview`, or with `--name` or `--purpose`, is
|
|
2513
|
+
`E_BAD_ARGS`.
|
|
2514
|
+
- **The call.** The kernel makes one non-interactive call through the
|
|
2515
|
+
harness, executable and environment the spawn would launch (the launch
|
|
2516
|
+
configuration's `env`, not its `args`), with this prompt on stdin, never in
|
|
2517
|
+
argv:
|
|
2518
|
+
|
|
2519
|
+
> Name an agent for this task: 2–4 lowercase words joined by hyphens, describing the work, not the role. Reply with the name only.
|
|
2520
|
+
>
|
|
2521
|
+
> Task:
|
|
2522
|
+
> <the task text, at most 4000 characters>
|
|
2523
|
+
|
|
2524
|
+
It runs from a fresh empty temporary directory, removed afterwards, with no
|
|
2525
|
+
`OATS_INSTANCE*` variable, without a shell, in its own process group. It is
|
|
2526
|
+
made after the preview's harness checks (the executable's lookup and the
|
|
2527
|
+
harness package probes, from where the home will be) and before anything
|
|
2528
|
+
that depends on the name (placement, branch, home). It takes what those
|
|
2529
|
+
checks leave of the preview's one 20 s preflight budget, which is not
|
|
2530
|
+
raised for it: the group is killed after 20 s, or when the budget runs out
|
|
2531
|
+
first. Its time counts in `preflight.elapsedMs`; `preflight.status` stays
|
|
2532
|
+
that of the checks, so a numbered preview after a `timeout` is confirmed
|
|
2533
|
+
like any other. At most 4 KiB of its output is read.
|
|
2534
|
+
- **It starts none of the user's code: no MCP server, hook, plugin,
|
|
2535
|
+
extension or project setting, and no tool on either harness.** Three
|
|
2536
|
+
exceptions are stated:
|
|
2537
|
+
- Claude Code's own built-in plugins (`cc-plugin-*@builtin`) load as
|
|
2538
|
+
they always do, `--bare` included.
|
|
2539
|
+
- Hooks in the host's managed policy (`managed-settings.json`) still
|
|
2540
|
+
apply: they are the host admin's.
|
|
2541
|
+
- pi runs its own credential commands (`!command` keys and headers in
|
|
2542
|
+
models.json), as every pi launch does: they are its login.
|
|
2543
|
+
|
|
2544
|
+
A claude login through `apiKeyHelper` is not read (`--setting-sources
|
|
2545
|
+
""`): such a user gets `harness-failed` and a numbered name.
|
|
2546
|
+
|
|
2547
|
+
Each harness's argv is proven to start nothing else
|
|
2548
|
+
(`scripts/naming-isolation-proof.mjs`, a recorded run against fixtures,
|
|
2549
|
+
rerun by an operator after a harness upgrade). The proof covers claude
|
|
2550
|
+
2.1.288 and pi 1.3.0, on Linux; macOS is not proven.
|
|
2551
|
+
- **claude**, model `haiku`: `-p --tools "" --strict-mcp-config
|
|
2552
|
+
--setting-sources "" --disable-slash-commands --no-session-persistence
|
|
2553
|
+
--output-format text --model haiku`. Its native login is kept, which
|
|
2554
|
+
`--bare` would not keep.
|
|
2555
|
+
- **pi**, the instance's model: `-p --no-session --no-tools
|
|
2556
|
+
--no-extensions --no-mcp --no-skills --no-prompt-templates --no-themes
|
|
2557
|
+
--no-context-files --no-approve [--model <m>]`.
|
|
2558
|
+
- **codex** is not supported. Its naming call is not proven to start
|
|
2559
|
+
nothing, so a codex soul is numbered with `unsupported-harness`.
|
|
2560
|
+
- **The name.**
|
|
2561
|
+
1. The reply's first non-empty line, as a slug.
|
|
2562
|
+
2. Without one or more trailing `-<role>`. The role is the last word of the
|
|
2563
|
+
soul's name, after any package qualifier.
|
|
2564
|
+
3. At most 4 words, cut at a word boundary to fit
|
|
2565
|
+
`64 − 1 − len(role)`.
|
|
2566
|
+
4. Nothing left, or only the role, is `invalid-reply`.
|
|
2567
|
+
5. The name is `<descriptive>-<role>`. A name that is taken (an instance,
|
|
2568
|
+
a soul or a live window, as for `--name`) gets `-2`, `-3`, and so on.
|
|
2569
|
+
- **The answer** is the full preview, plus `naming`:
|
|
2570
|
+
|
|
2571
|
+
```json
|
|
2572
|
+
"naming": { "source": "suggested", "ms": 2310, "harness": "claude", "model": "haiku" }
|
|
2573
|
+
```
|
|
2574
|
+
|
|
2575
|
+
```json
|
|
2576
|
+
"naming": { "source": "numbered", "reason": "timeout", "message": "claude gave no name within 20 s", "ms": 20000 }
|
|
2577
|
+
```
|
|
2578
|
+
|
|
2579
|
+
- With `source: "suggested"`, `instance`, `home`, `branch` and `decision`
|
|
2580
|
+
are those of a preview with `--name <instance>`: an apply with `--name
|
|
2581
|
+
<instance> --expect-decision <revision>` matches it.
|
|
2582
|
+
- With `source: "numbered"`, they are today's numbered name, and the apply
|
|
2583
|
+
goes without `--name`.
|
|
2584
|
+
- `reason` is one of a closed set:
|
|
2585
|
+
- `no-task`: no task, or a blank one; no call is made.
|
|
2586
|
+
- `unsupported-harness`: no call is made.
|
|
2587
|
+
- `timeout`.
|
|
2588
|
+
- `harness-failed`: a nonzero exit, a signal, or no executable. `message`
|
|
2589
|
+
gives the exit or the signal, never the output.
|
|
2590
|
+
- `invalid-reply`.
|
|
2591
|
+
- `model` is `null` when the harness runs its own default.
|
|
2592
|
+
- A failure is never an error: the preview answers.
|
|
2593
|
+
- The text preview prints `name: suggested by claude (haiku) in 2310 ms` or
|
|
2594
|
+
`name: numbered (<reason>: <message>)`.
|
|
2595
|
+
- **`--server`:** the call runs on the target machine, through the routed
|
|
2596
|
+
preview, and the task travels as a routed spawn's does. A host that does
|
|
2597
|
+
not advertise `spawn-suggest-name` is refused (`E_REMOTE_INCOMPATIBLE`)
|
|
2598
|
+
before the spawn is sent.
|
|
2599
|
+
|
|
2453
2600
|
**Provider settings.**
|
|
2454
2601
|
- `providers` is the `--provider` map as typed.
|
|
2455
2602
|
- `settings.<cap>`: the merged payload (manifest defaults, then workspace,
|
|
@@ -2583,6 +2730,9 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
|
|
|
2583
2730
|
`E_INSTANCE_NAME_TAKEN {instance, home, session?}`; a typed name never gets
|
|
2584
2731
|
a silent `-2`.
|
|
2585
2732
|
- The name is part of the decision.
|
|
2733
|
+
- `--preview --suggest-name` (feature `spawn-suggest-name`) chooses a
|
|
2734
|
+
descriptive name for the task, `<descriptive>-<role>`, which the apply then
|
|
2735
|
+
passes as `--name` ([The suggested name](#the-suggested-name-feature-spawn-suggest-name)).
|
|
2586
2736
|
|
|
2587
2737
|
### Spawn origin
|
|
2588
2738
|
|
|
@@ -3006,6 +3156,12 @@ its absence.
|
|
|
3006
3156
|
An older kernel's `running` is the window's presence, and it checks a row
|
|
3007
3157
|
with a claim against its session (as `oats session inspect` observes it),
|
|
3008
3158
|
reading `null` unless a harness runs there.
|
|
3159
|
+
- **`color`** (feature `instance-color`): the instance's colour, one of
|
|
3160
|
+
`sand`, `sage`, `slate`, `mauve`, `clay`, `olive`, or `null` for none,
|
|
3161
|
+
from the home's own record ([An instance's colour](#an-instances-colour-oats-instance-color));
|
|
3162
|
+
a `color` in `instance.json` never stands in for it. Every row has it,
|
|
3163
|
+
an unreadable record's row included (`null`). Presentation only: it is not
|
|
3164
|
+
identity and never addresses anything.
|
|
3009
3165
|
- <a id="row-retire"></a>**`retire`** (feature `status-retire-state`, OATS
|
|
3010
3166
|
0.59.0): `{state, since, self, code?, message?}` while a retire of the home
|
|
3011
3167
|
is running, scheduled or owed; absent otherwise, and from older kernels.
|
|
@@ -3166,7 +3322,7 @@ route target:
|
|
|
3166
3322
|
"soul":{"repoKey":"github.com/acme/team","commit":"66566512…","current":"9c1e04ab…","status":"moved"},
|
|
3167
3323
|
"modules":[{"name":"oats.okf","from":{"kind":"package","package":"oats.okf","version":"2.1.3","commit":"ab897841…","integrity":"sha256-bada35…","repoKey":"github.com/awebai/oats-okf"},
|
|
3168
3324
|
"commit":"ab897841…","current":{"commit":"ab897841…","version":"2.1.3"},"status":"current"}],
|
|
3169
|
-
"retirePending":false,"rollbackIncomplete":false,
|
|
3325
|
+
"color":"sage","retirePending":false,"rollbackIncomplete":false,
|
|
3170
3326
|
"savedRoute":false,"addressable":true,"missingRemotely":false}],
|
|
3171
3327
|
"retireFailures":[]}
|
|
3172
3328
|
```
|
|
@@ -3461,6 +3617,7 @@ instance's own machine: the local command, with `--server <id>` added.
|
|
|
3461
3617
|
| `oats instance git\|diff <name> --server <id> …` | `instance-git` | `instance-git`, `instanceGitApi: 1` |
|
|
3462
3618
|
| `oats instance stop <name> --server <id> (--plan \| --apply …)` | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
|
|
3463
3619
|
| `oats retire <name> --server <id> --plan`, and the guarded apply (`--plan-revision`, `--idempotency-key`) | `lifecycle-plans` | `lifecycle-plans`, `lifecycleApi: 1` |
|
|
3620
|
+
| `oats instance color <name> (<color> \| --clear) --server <id>` | none | `instance-color` |
|
|
3464
3621
|
|
|
3465
3622
|
- The flags are the local command's. The instance is addressed like every
|
|
3466
3623
|
routed instance command ([servers.md](servers.md#run-there)): `--home` as
|
|
@@ -3731,7 +3888,7 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
|
|
|
3731
3888
|
|
|
3732
3889
|
### Waiting on you
|
|
3733
3890
|
|
|
3734
|
-
Feature `waiting-on-you` (OATS 0.40.0): an instance
|
|
3891
|
+
Feature `waiting-on-you` (OATS 0.40.0): an instance waiting on a human (a
|
|
3735
3892
|
permission prompt, a question, an agent asking for an answer) says so through
|
|
3736
3893
|
a producer's claim. **Claims are display-only:** nothing in the kernel acts
|
|
3737
3894
|
on `waitingOnYou`. In particular `oats session input` behaves exactly as
|
|
@@ -5379,6 +5536,60 @@ removal begins, and only with the home kept (`reached.home: "kept"`). A
|
|
|
5379
5536
|
typed refusal keeps its code, its details and its own words; the inspections'
|
|
5380
5537
|
and the recovery's refusals end with the sentence of their phase, once.
|
|
5381
5538
|
|
|
5539
|
+
## An instance's colour (`oats instance color`)
|
|
5540
|
+
|
|
5541
|
+
Feature `instance-color` (awebai/oats#1421).
|
|
5542
|
+
|
|
5543
|
+
```text
|
|
5544
|
+
oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d>] [--json]
|
|
5545
|
+
```
|
|
5546
|
+
|
|
5547
|
+
The colour is presentation, not identity. Anyone may change it at any time,
|
|
5548
|
+
the agent on its own instance included, and it is never an address.
|
|
5549
|
+
|
|
5550
|
+
- **The palette** is closed: `sand`, `sage`, `slate`, `mauve`, `clay`,
|
|
5551
|
+
`olive`, the clients' own (`packages/client/soul-colors.mjs`).
|
|
5552
|
+
- **The record** is `<home>/.oats-color.json`, `{"colorApi": 1, "color":
|
|
5553
|
+
"sage", "at": "<ISO time>"}`, mode 0600, written atomically. `--clear`
|
|
5554
|
+
removes it. It is a kernel-owned home file: a capability cannot declare it
|
|
5555
|
+
as its own, and it is no change to the home at retire.
|
|
5556
|
+
- **A reader** takes a regular file only, without following a link, of at
|
|
5557
|
+
most 4 KiB. Anything that is not such a valid record reads as no colour
|
|
5558
|
+
(`null`), never as an error.
|
|
5559
|
+
- **The instance** is addressed as `oats instance stop` addresses it, and
|
|
5560
|
+
refused with the same answers: not found, ambiguous, a `--home` that is not
|
|
5561
|
+
its home, a record that cannot be read.
|
|
5562
|
+
|
|
5563
|
+
The answer:
|
|
5564
|
+
|
|
5565
|
+
```json
|
|
5566
|
+
{"instanceColorApi":1,"instance":"dev-a","home":"/w/agents/dev/instances/dev-a","color":"sage","changed":true}
|
|
5567
|
+
```
|
|
5568
|
+
|
|
5569
|
+
`color` is `null` after `--clear`. Setting the colour the instance already
|
|
5570
|
+
has answers `changed: false` and writes nothing; so does clearing an instance
|
|
5571
|
+
with no colour.
|
|
5572
|
+
|
|
5573
|
+
| Code | When |
|
|
5574
|
+
|---|---|
|
|
5575
|
+
| `E_BAD_ARGS` | The colour is not in the palette: `"<value>" is not an instance colour: use one of sand, sage, slate, mauve, clay, olive, or --clear`. Also: both a colour and `--clear`, neither, or two colours |
|
|
5576
|
+
| *(as `oats instance stop`)* | Instance resolution: `E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`, `E_UNIDENTIFIED_INSTANCE_HOME` |
|
|
5577
|
+
| `E_INSTANCE_RETIRING` | A retire of the home is in flight (its pending marker, or a live retire holding the home's lifecycle claim, which the command reads and never takes, as `oats worktree add` reads it), or the home is quarantined. Nothing was written |
|
|
5578
|
+
| `E_LIFECYCLE_BUSY` | The home's claim file cannot be read as a claim, or a retire's liveness cannot be read, as for `oats worktree add` |
|
|
5579
|
+
|
|
5580
|
+
Routed with `--server <id>`, the command runs on the host
|
|
5581
|
+
([Routed reads and plans](#routed-reads-and-plans)); a host whose probe does
|
|
5582
|
+
not advertise `instance-color` is refused with `E_REMOTE_INCOMPATIBLE`, and
|
|
5583
|
+
nothing is sent.
|
|
5584
|
+
|
|
5585
|
+
Where it is read: `color` on [status rows](#the-roster-oats-status---json),
|
|
5586
|
+
on [remote roster rows](#the-remote-roster-oats-server-roster---json) (only a
|
|
5587
|
+
palette name is relayed, anything else is `null`), and on `oats inspect
|
|
5588
|
+
--home` as `instance.color`. A client draws a row's colour by one rule,
|
|
5589
|
+
`instanceColor(row)` in `packages/client/instance-presentation.mjs`: the
|
|
5590
|
+
row's palette name, else none. Colour never says a state alone: a client's
|
|
5591
|
+
mark keeps the state by its shape.
|
|
5592
|
+
|
|
5382
5593
|
## Sessions and launch configurations
|
|
5383
5594
|
|
|
5384
5595
|
### Input
|