@awebai/oats 0.65.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/README.md +11 -5
- package/bin/oats.mjs +74 -20
- package/docs/capabilities.md +4 -4
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/desktop-cli-api.md +222 -10
- package/docs/desktop.md +101 -22
- package/docs/implementation.md +16 -6
- package/docs/integrations.md +1 -1
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.66.0.md +183 -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 +5 -4
- package/docs/souls-and-instances.md +20 -3
- package/docs/tui.md +658 -143
- package/docs/upgrading.md +107 -25
- package/docs/workspaces.md +9 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/core.mjs +126 -54
- package/lib/deployments.mjs +21 -5
- 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 +2 -2
- 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 +99 -11
- package/packages/client/keys-file.mjs +122 -0
- package/packages/client/machine-contract.mjs +1 -5
- 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/record/bin/setup.mjs +10 -2
- package/packages/record/docs/capture-service.md +45 -6
- package/packages/record/lib/capture-service-install.mjs +6 -95
- package/packages/record/lib/capture-setup-write.mjs +233 -0
- package/packages/tui/README.md +9 -8
- package/packages/tui/lib/actions.mjs +108 -64
- package/packages/tui/lib/client.mjs +8 -3
- package/packages/tui/lib/config.mjs +208 -26
- package/packages/tui/lib/main.mjs +91 -20
- package/packages/tui/lib/model.mjs +167 -61
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +156 -47
- package/packages/tui/lib/term/keys.mjs +150 -34
- package/packages/tui/lib/term/kitty.mjs +223 -0
- package/packages/tui/lib/term/through.mjs +174 -27
- package/packages/tui/lib/term/tty.mjs +43 -12
- package/packages/tui/lib/views/frame.mjs +158 -79
- package/packages/tui/lib/views/help.mjs +143 -21
- 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 +107 -34
package/README.md
CHANGED
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
**Free, open source, provider- and harness-agnostic, and decentralised by design.**
|
|
4
4
|
|
|
5
|
+
> **Coding agent setting up OATS for someone?** Go to [Start here](#start-here): it tells you what to download and run next.
|
|
6
|
+
|
|
5
7
|
[](https://www.npmjs.com/package/@awebai/oats)
|
|
6
8
|
[](https://github.com/awebai/oats/releases)
|
|
7
9
|
[](https://nodejs.org/)
|
|
@@ -27,16 +29,20 @@ The [official catalog](docs/official-catalog.md) is the reviewed list of officia
|
|
|
27
29
|
|
|
28
30
|
## Start here
|
|
29
31
|
|
|
30
|
-
|
|
32
|
+
**If you are a coding agent and your person asked you to set up, install or try OATS, do this next:** download the `oats-getting-started` skill with the command below, then follow it step by step. It is the whole procedure; don't improvise one from this README.
|
|
31
33
|
|
|
32
34
|
```bash
|
|
33
35
|
curl -fsSL https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md
|
|
34
36
|
```
|
|
35
37
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
- **
|
|
39
|
-
- **
|
|
38
|
+
If you are a person, give your coding agent (Claude Code, Codex, pi or any other) this page and say "set up OATS for me". It then:
|
|
39
|
+
|
|
40
|
+
- **Asks first, in one round:** your project, its repositories, the knowledge tools you use, and a username for agent messaging.
|
|
41
|
+
- **Installs OATS and OATS Desktop,** then creates your workspace in one commit: the workspace, a messaging team, a setup expert and a first developer. Or it joins this machine to an existing workspace.
|
|
42
|
+
- **Gives your agents identities and messaging:** one command signs up a hosted [aweb](https://aweb.ai) team for the new workspace, with no API key and no pull requests to merge.
|
|
43
|
+
- **Hands over to the setup expert,** an OATS agent that sets up the rest with you. You type only passwords, logins and tokens.
|
|
44
|
+
|
|
45
|
+
Download the skill, don't web-fetch it: a tool that summarises pages would lose its exact commands.
|
|
40
46
|
|
|
41
47
|
## Why OATS
|
|
42
48
|
|
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.
|
|
@@ -4325,12 +4369,13 @@ async function serverCmd() {
|
|
|
4325
4369
|
} catch (e) { bail(e.code || "E_SSH", e.message, e.details); }
|
|
4326
4370
|
}
|
|
4327
4371
|
|
|
4328
|
-
/** `oats server connect <id> --ssh <host>`: this deployment's workspace on a host,
|
|
4329
|
-
* (lib/servers.mjs connectServer).
|
|
4330
|
-
*
|
|
4372
|
+
/** `oats server connect <id> --ssh <host> --dir <path>`: this deployment's workspace on a host,
|
|
4373
|
+
* registered (lib/servers.mjs connectServer). The workspace ref defaults from the deployment it
|
|
4374
|
+
* runs in; the folder on the host never has a default, inside a deployment too (awebai/oats#1390,
|
|
4375
|
+
* step b): only the person knows where it goes. */
|
|
4331
4376
|
function serverConnectCmd(bail) {
|
|
4332
4377
|
const id = args[2];
|
|
4333
|
-
if (!id || id.startsWith("--")) bail("E_USAGE", "usage: oats server connect <id> --ssh <host-alias>
|
|
4378
|
+
if (!id || id.startsWith("--")) bail("E_USAGE", "usage: oats server connect <id> --ssh <host-alias> --dir </abs/path or ~/path on the host> [--workspace-ref <ref>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] [--json]");
|
|
4334
4379
|
const val = (name) => { const v = flag(name); return v === true ? bail("E_BAD_ARGS", `--${name} needs a value`) : v; };
|
|
4335
4380
|
const sshHost = val("ssh");
|
|
4336
4381
|
if (!sshHost) bail("E_BAD_ARGS", "--ssh <host-alias> is required: the OpenSSH host alias of the machine to connect");
|
|
@@ -4339,8 +4384,8 @@ function serverConnectCmd(bail) {
|
|
|
4339
4384
|
const workspaceRef = val("workspace-ref") ?? local?.local.workspace;
|
|
4340
4385
|
if (!workspaceRef) bail("E_BAD_ARGS", "--workspace-ref <ref> is required outside a deployment (inside one it defaults to oats-local.yaml workspace:)");
|
|
4341
4386
|
try { remoteModule.parseRepoRef(workspaceRef); } catch (e) { bail(e.code || "E_REPO_REF", e.message, e.details); }
|
|
4342
|
-
const dir = val("dir")
|
|
4343
|
-
if (!dir) bail("E_BAD_ARGS",
|
|
4387
|
+
const dir = val("dir");
|
|
4388
|
+
if (!dir) bail("E_BAD_ARGS", `--dir <path on the host> is required: the folder on ${sshHost} for this deployment (absolute, or ~/… resolved there)`);
|
|
4344
4389
|
let res;
|
|
4345
4390
|
try {
|
|
4346
4391
|
res = connectServer({ id, sshHost, workspaceRef, dir, oatsPath: val("oats"), path: val("path"), label: val("label"), installOats: args.includes("--install-oats"), replace: args.includes("--replace"), localVersion: OATS_VERSION });
|
|
@@ -4533,7 +4578,7 @@ async function serverRouteCmd() {
|
|
|
4533
4578
|
const herdr = herdrSpawnFlag();
|
|
4534
4579
|
if (herdr) { const e = herdrSettingRemoved(`${herdr} was given`); bail(e.code, e.message); }
|
|
4535
4580
|
const local = args.slice(1).filter((a, i, all) => a !== "--server" && all[i - 1] !== "--server");
|
|
4536
|
-
const problem = spawnArgvProblem(local);
|
|
4581
|
+
const problem = spawnArgvProblem(local) ?? suggestNameProblem(local);
|
|
4537
4582
|
if (problem) bail("E_BAD_ARGS", problem);
|
|
4538
4583
|
}
|
|
4539
4584
|
// Everything after the command word travels, minus the routing flags; a
|
|
@@ -4812,7 +4857,7 @@ Usage:
|
|
|
4812
4857
|
[--workspace-ref <ref>] (filled in when missing) and Git readability;
|
|
4813
4858
|
list --workspace-ref = one workspace's servers
|
|
4814
4859
|
oats server connect <id> --ssh <alias> put this deployment's workspace on that machine and
|
|
4815
|
-
|
|
4860
|
+
--dir <path> [--workspace-ref <ref>] register it: ssh, oats, git, deployment, register,
|
|
4816
4861
|
[--oats <p>] [--path <dir:dir>] readiness, each re-checked every run; --install-oats
|
|
4817
4862
|
[--label <t>] [--install-oats] installs this version with npm there; human steps
|
|
4818
4863
|
[--replace] [--json] come back with the exact remedy (docs/servers.md)
|
|
@@ -4960,6 +5005,10 @@ Usage:
|
|
|
4960
5005
|
instance.json providers.<capability>)
|
|
4961
5006
|
[--preview] decide everything, create no instance; --json
|
|
4962
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)
|
|
4963
5012
|
[--expect-decision <rev>] bind apply to the previewed decision; drift refuses
|
|
4964
5013
|
[--idempotency-key <key>] with --expect-decision, replay the completed receipt
|
|
4965
5014
|
for the same key and confirmed decision; a different
|
|
@@ -4992,13 +5041,15 @@ Usage:
|
|
|
4992
5041
|
oats inspect [--dir <scope>] [--soul <name> one authoritative JSON answer for a GUI: souls
|
|
4993
5042
|
[--agents-root <abs>]] [--home <abs>] (harness defaults, editability, instructions),
|
|
4994
5043
|
[--instructions] [--skills] installed capabilities with health, effective
|
|
4995
|
-
[--max-age <s>]
|
|
4996
|
-
|
|
5044
|
+
[--composed-skills] [--max-age <s>] layer bindings and activation, declared
|
|
5045
|
+
[--json] operations with availability; --home answers the
|
|
4997
5046
|
running home's recorded modules and their drift
|
|
4998
5047
|
from the deployment; --instructions (--soul only)
|
|
4999
5048
|
adds the AGENTS.md a spawn of the soul here would write;
|
|
5000
5049
|
--skills (--soul only) adds the soul's own skills, the
|
|
5001
|
-
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
|
|
5002
5053
|
oats operation run <layer>:<name> run an operation the soul's core capability for that
|
|
5003
5054
|
(--home <abs> | --soul <name> [--dir <d>]) layer declares (knowledge:harvest, knowledge:
|
|
5004
5055
|
[--arg k=v ...] [--json] inspect ...): resolved from the home's recorded
|
|
@@ -5101,6 +5152,9 @@ Usage:
|
|
|
5101
5152
|
oats instance stop <instance> --apply --plan-revision <rev> --idempotency-key <key>
|
|
5102
5153
|
quiesce (SIGTERM, bounded, never escalated),
|
|
5103
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
|
|
5104
5158
|
oats worktree add --purpose <p> --branch <b> --base <remote-branch> from an instance home: make the
|
|
5105
5159
|
[--repo <member key|clone path>] extra tree <home>/.work-<p> on a new branch at origin's
|
|
5106
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
|
}
|