@awebai/oats 0.63.0 → 0.65.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +14 -1
- package/bin/oats.mjs +158 -26
- package/docs/desktop-cli-api.md +127 -3
- package/docs/desktop.md +14 -5
- package/docs/execution-targets.md +9 -5
- package/docs/first-team.md +6 -0
- package/docs/implementation.md +17 -3
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-notes/v0.64.0.md +105 -0
- package/docs/release-notes/v0.65.0.md +187 -0
- package/docs/souls-and-instances.md +26 -6
- package/docs/tui.md +416 -238
- package/docs/upgrading.md +2 -1
- package/docs/workspaces.md +125 -1
- package/lib/core.mjs +43 -11
- package/lib/deployments.mjs +325 -0
- package/lib/resolved-deployment.mjs +37 -0
- package/lib/session-input.mjs +12 -2
- package/lib/workspace.mjs +2 -0
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/deployment-label.mjs +2 -2
- package/packages/client/deployment-list-cli.mjs +98 -0
- package/packages/client/deployment-list.mjs +91 -0
- package/packages/client/instance-tree.mjs +53 -3
- package/packages/client/keymap.mjs +106 -0
- package/packages/client/own-codes.mjs +2 -0
- package/packages/client/panel-views.mjs +1 -1
- package/packages/client/roster-sections.mjs +22 -6
- package/packages/client/workspace-admission.mjs +2 -1
- package/packages/tui/README.md +4 -4
- package/packages/tui/lib/actions.mjs +29 -5
- package/packages/tui/lib/client.mjs +3 -1
- package/packages/tui/lib/config.mjs +21 -14
- package/packages/tui/lib/main.mjs +108 -31
- package/packages/tui/lib/model.mjs +71 -41
- package/packages/tui/lib/read.mjs +15 -45
- package/packages/tui/lib/store.mjs +158 -39
- package/packages/tui/lib/term/through.mjs +40 -18
- package/packages/tui/lib/views/act.mjs +17 -13
- package/packages/tui/lib/views/frame.mjs +418 -421
- package/packages/tui/lib/views/help.mjs +41 -19
- package/packages/tui/lib/views/instances.mjs +38 -9
- package/packages/tui/lib/views/switcher.mjs +65 -21
- package/skills/oats-getting-started/SKILL.md +440 -170
package/README.md
CHANGED
|
@@ -25,6 +25,19 @@ For example, a kernel expert, a UX expert and a customer-support expert can shar
|
|
|
25
25
|
|
|
26
26
|
The [official catalog](docs/official-catalog.md) is the reviewed list of official packages. A workspace trusts a package by declaring it; being listed doesn't declare it.
|
|
27
27
|
|
|
28
|
+
## Start here
|
|
29
|
+
|
|
30
|
+
Ask your coding agent (Claude Code, Codex, pi or any other) to download the `oats-getting-started` skill verbatim and follow it:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
curl -fsSL https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
- **It asks first:** your project, its repositories and the knowledge tools you use.
|
|
37
|
+
- **It installs OATS and OATS Desktop,** then creates your workspace with its own setup expert, or joins this machine to an existing workspace.
|
|
38
|
+
- **It hands over to that setup expert,** an OATS agent that sets up the rest with you. You type only passwords, logins and tokens.
|
|
39
|
+
- **Download it, don't web-fetch it:** a tool that summarises pages would lose its exact commands.
|
|
40
|
+
|
|
28
41
|
## Why OATS
|
|
29
42
|
|
|
30
43
|
OATS grew from a practical need: we wanted control over our agent setups—not just which model answered a prompt, but also:
|
|
@@ -212,7 +225,7 @@ oats onboard ~/acme --workspace git:github.com/acme/agents # this machine's de
|
|
|
212
225
|
oats spawn <soul> --task "First concrete task"
|
|
213
226
|
```
|
|
214
227
|
|
|
215
|
-
The [first-team guide](docs/first-team.md) walks through writing the workspace, its members and a first soul; the [release notes](docs/release-notes/) state the supported scope of each version.
|
|
228
|
+
[Start here](#start-here) does all of this for you. The [first-team guide](docs/first-team.md) walks through writing the workspace, its members and a first soul; the [release notes](docs/release-notes/) state the supported scope of each version.
|
|
216
229
|
|
|
217
230
|
Further documentation:
|
|
218
231
|
|
package/bin/oats.mjs
CHANGED
|
@@ -66,6 +66,8 @@ import { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } from
|
|
|
66
66
|
const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
|
|
67
67
|
import { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposedInstructions, 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
|
+
import { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } from "../lib/deployments.mjs";
|
|
70
|
+
import { observeResolvedDeployment } from "../lib/resolved-deployment.mjs";
|
|
69
71
|
|
|
70
72
|
const rawArgs = process.argv.slice(2);
|
|
71
73
|
/** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
|
|
@@ -98,14 +100,14 @@ function expandInlineValues(argv) {
|
|
|
98
100
|
const { argv: args, problem: argvProblem, inline: inlineValues } = expandInlineValues(rawArgs);
|
|
99
101
|
let cmd = args[0];
|
|
100
102
|
const HELP_WORDS = new Set(["help", "--help", "-h"]);
|
|
101
|
-
const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "tui", "update", "version", "workspace", "worktree"]);
|
|
103
|
+
const KERNEL_COMMANDS = new Set(["harness", "automations", "trigger", "capture", "capabilities", "deployments", "doctor", "inspect", "instance", "operation", "package", "readiness", "souls", "soul", "teams", "launch-config", "experimental", "onboard", "pane", "recall", "retire", "root", "schedule", "server", "session", "setup", "spawn", "status", "sync", "tui", "update", "version", "workspace", "worktree"]);
|
|
102
104
|
/** Commands whose argv another parser reads (packages/record, packages/experimental and packages/tui parse process.argv). */
|
|
103
105
|
const OWN_ARGV_COMMANDS = new Set(["capture", "recall", "setup", "experimental", "tui"]);
|
|
104
106
|
/** The kernel features this binary implements: `features` in `version --json` (the Desktop API v1
|
|
105
107
|
* probe) and in `status --json`, which a remote roster relays as the host's (feature
|
|
106
108
|
* server-probe-features, lib/servers.mjs hostFeatures). ONE list for both, emitted at output
|
|
107
109
|
* time, never stored. A name must pass hostFeatures's check (test/cli-json-contract.test.mjs). */
|
|
108
|
-
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"];
|
|
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"];
|
|
109
111
|
/** Commands `--server <id>` runs on a registered server. */
|
|
110
112
|
const ROUTED_COMMANDS = new Set(["spawn", "retire", "status", "session", "okf", "schedule", "inspect", "operation", "launch-config", "readiness", "instance"]);
|
|
111
113
|
const flag = (name) => {
|
|
@@ -2839,9 +2841,8 @@ async function spawnCmd() {
|
|
|
2839
2841
|
// Lineage is explicit: --relation child|sibling|parent|unrelated anchors the new
|
|
2840
2842
|
// instance to --relative-to <instance>. --parent X is sugar for
|
|
2841
2843
|
// --relative-to X --relation child (agents spawning sub-agents pass their own
|
|
2842
|
-
// name, e.g. --parent "$OATS_INSTANCE"). Without a relation, the spawn
|
|
2843
|
-
//
|
|
2844
|
-
// never treated as parentage.
|
|
2844
|
+
// name, e.g. --parent "$OATS_INSTANCE"). Without a relation, the spawn lands
|
|
2845
|
+
// top-level; caller attribution never supplies parentage.
|
|
2845
2846
|
const parent = flag("parent");
|
|
2846
2847
|
if (parent !== undefined && (parent === true || !String(parent).trim())) bail("E_BAD_ARGS", "--parent needs an instance name");
|
|
2847
2848
|
let relation = flag("relation");
|
|
@@ -3536,6 +3537,74 @@ async function tuiCmd() {
|
|
|
3536
3537
|
await import(new URL("../packages/tui/bin/tui.mjs", import.meta.url));
|
|
3537
3538
|
}
|
|
3538
3539
|
|
|
3540
|
+
/**
|
|
3541
|
+
* `oats deployments [list] | add [<dir>] | remove <path> | import --from desktop <path>... [--json]`:
|
|
3542
|
+
* this computer's list of its deployments (lib/deployments.mjs; docs/workspaces.md "This computer's
|
|
3543
|
+
* deployments"). Runs anywhere, needs no deployment, never routes to another machine. `--via
|
|
3544
|
+
* tui|desktop` (add) is the clients' and is not in the usage.
|
|
3545
|
+
*/
|
|
3546
|
+
function deploymentsCmd() {
|
|
3547
|
+
const usage = "usage: oats deployments [list] | add [<dir>] | remove <path> | import --from desktop <path>... [--json]";
|
|
3548
|
+
const fail = (code, message, details) => cmdFail(code, message, details);
|
|
3549
|
+
const positional = [];
|
|
3550
|
+
const values = {};
|
|
3551
|
+
for (let i = 1; i < args.length; i++) {
|
|
3552
|
+
const a = args[i];
|
|
3553
|
+
if (a === "--json") continue;
|
|
3554
|
+
if (a === "--server") return fail("E_BAD_ARGS", "oats deployments lists this computer's deployments: --server is not accepted");
|
|
3555
|
+
if (a === "--via" || a === "--from") {
|
|
3556
|
+
const v = args[i + 1];
|
|
3557
|
+
if (v === undefined || v.startsWith("--")) return fail("E_BAD_ARGS", `${a} needs a value\n${usage}`);
|
|
3558
|
+
if (values[a.slice(2)] !== undefined) return fail("E_BAD_ARGS", `${a} is given twice\n${usage}`);
|
|
3559
|
+
values[a.slice(2)] = v; i++; continue;
|
|
3560
|
+
}
|
|
3561
|
+
if (a.startsWith("--")) return fail("E_BAD_ARGS", `unknown flag ${a}\n${usage}`);
|
|
3562
|
+
positional.push(a);
|
|
3563
|
+
}
|
|
3564
|
+
const sub = positional.length ? positional.shift() : "list";
|
|
3565
|
+
if (!["list", "add", "remove", "import"].includes(sub)) return fail("E_BAD_ARGS", `unknown subcommand ${JSON.stringify(sub)}\n${usage}`);
|
|
3566
|
+
if (values.via !== undefined && sub !== "add") return fail("E_BAD_ARGS", `--via is for oats deployments add\n${usage}`);
|
|
3567
|
+
if (values.from !== undefined && sub !== "import") return fail("E_BAD_ARGS", `--from is for oats deployments import\n${usage}`);
|
|
3568
|
+
const run = (fn) => { try { return fn(); } catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_")) return fail(e.code, e.message, e.details); throw e; } };
|
|
3569
|
+
|
|
3570
|
+
if (sub === "list") {
|
|
3571
|
+
if (positional.length) return fail("E_BAD_ARGS", usage);
|
|
3572
|
+
const result = run(() => listDeployments());
|
|
3573
|
+
if (JSON_MODE) return jsonOk(result);
|
|
3574
|
+
if (!result.deployments.length) {
|
|
3575
|
+
console.log(`no deployments listed (${shortPath(result.file)}): create one with \`oats onboard <dir> --workspace <ref>\`, or add one with \`oats deployments add <dir>\``);
|
|
3576
|
+
return;
|
|
3577
|
+
}
|
|
3578
|
+
const rows = [["PATH", "STATE", "VIA"], ...result.deployments.map((d) => [shortPath(d.path), d.state, d.via ?? ""])];
|
|
3579
|
+
const [pathWidth, stateWidth] = [0, 1].map((i) => Math.max(...rows.map((r) => r[i].length)));
|
|
3580
|
+
for (const r of rows) console.log(`${r[0].padEnd(pathWidth)} ${r[1].padEnd(stateWidth)} ${r[2]}`.trimEnd());
|
|
3581
|
+
return;
|
|
3582
|
+
}
|
|
3583
|
+
if (sub === "add") {
|
|
3584
|
+
if (positional.length > 1) return fail("E_BAD_ARGS", usage);
|
|
3585
|
+
if (values.via !== undefined && !CLIENT_VIA.includes(values.via)) return fail("E_BAD_ARGS", `--via takes ${CLIENT_VIA.join(" or ")}, got ${JSON.stringify(values.via)}`);
|
|
3586
|
+
const from = resolve(positional[0] ?? process.cwd());
|
|
3587
|
+
const found = deploymentAtOrAbove(from);
|
|
3588
|
+
if (!found) return fail("E_LOCAL_MISSING", `no oats-local.yaml at or above ${from}: it is not in a deployment (\`oats onboard <dir> --workspace <ref>\` creates one)`, { dir: from });
|
|
3589
|
+
const result = run(() => addDeployment(found, { via: values.via ?? "cli" }));
|
|
3590
|
+
if (JSON_MODE) return jsonOk(result);
|
|
3591
|
+
console.log(result.added ? `listed ${shortPath(result.path)}` : `${shortPath(result.path)} is already listed; nothing was changed`);
|
|
3592
|
+
return;
|
|
3593
|
+
}
|
|
3594
|
+
if (sub === "remove") {
|
|
3595
|
+
if (positional.length !== 1) return fail("E_BAD_ARGS", `oats deployments remove takes one path\n${usage}`);
|
|
3596
|
+
const result = run(() => removeDeployment(positional[0]));
|
|
3597
|
+
if (JSON_MODE) return jsonOk(result);
|
|
3598
|
+
console.log(result.removed ? `removed ${shortPath(result.path)} from this computer's list (nothing on disk was touched)` : `${shortPath(result.path)} is not listed; nothing was changed`);
|
|
3599
|
+
return;
|
|
3600
|
+
}
|
|
3601
|
+
// import
|
|
3602
|
+
if (values.from !== "desktop") return fail("E_BAD_ARGS", `oats deployments import needs --from desktop\n${usage}`);
|
|
3603
|
+
const result = run(() => importDesktopDeployments(positional));
|
|
3604
|
+
if (JSON_MODE) return jsonOk(result);
|
|
3605
|
+
console.log(result.imported ? `imported the Desktop's deployments: ${result.added.length} listed` : `the Desktop's deployments were imported already (${result.at}); nothing was changed`);
|
|
3606
|
+
}
|
|
3607
|
+
|
|
3539
3608
|
/** `oats onboard [<dir>] --workspace <repo ref> [--json]` — workspace model v2 (decision 9).
|
|
3540
3609
|
*
|
|
3541
3610
|
* Realizes a workspace on this machine in the directory the operator chooses
|
|
@@ -3653,8 +3722,14 @@ async function onboardCmd() {
|
|
|
3653
3722
|
// cannot see forge visibility, so it states the rule rather than judging.
|
|
3654
3723
|
const hostIsMember = members.some((m) => m.key === synced.discovery.key);
|
|
3655
3724
|
const hosting = { host: synced.discovery.key, hostIsMember, rule: "If any member is private, host oats-workspace.yaml in a private repo that is not a public member (a dedicated <org>/workspace repo); public contributors then use the standalone case (from: here capabilities + oats.core)." };
|
|
3656
|
-
|
|
3725
|
+
// This computer's deployments list gains what was created (awebai/oats#1390); a failed add never
|
|
3726
|
+
// fails the onboard, it is answered in `listed`.
|
|
3727
|
+
let listed = true;
|
|
3728
|
+
try { addDeployment(dir, { via: "onboard" }); }
|
|
3729
|
+
catch (e) { listed = { code: typeof e?.code === "string" && e.code.startsWith("E_") ? e.code : "E_DEPLOYMENTS_WRITE", message: String(e?.message ?? e) }; }
|
|
3730
|
+
const result = { onboardApi: 2, standalone: standalone || undefined, local: localFile, dir, agents: join(dir, "agents"), lock: synced.lockFile, sync: synced.report, hosting, next: { clone: clones, spawn: spawnHint, souls: soulNames.slice(0, 3) }, listed };
|
|
3657
3731
|
if (JSON_MODE) { jsonOk(result); return; }
|
|
3732
|
+
if (listed !== true) console.error(`oats: ${shortPath(dir)} was onboarded, but not added to this computer's deployments list: ${listed.message}`);
|
|
3658
3733
|
|
|
3659
3734
|
console.log(`Onboarded ${shortPath(dir)} into workspace ${workspaceName(synced.discovery)} (${synced.discovery.key} @ ${short(synced.discovery.commit)}).${standalone ? `\n (${standaloneNote(synced.discovery, { from: " from here" })})` : ""}\n`);
|
|
3660
3735
|
printSyncReport(ctx, synced);
|
|
@@ -4607,6 +4682,14 @@ try {
|
|
|
4607
4682
|
die(message);
|
|
4608
4683
|
}
|
|
4609
4684
|
}
|
|
4685
|
+
// This computer's deployments list (awebai/oats#1390, amendment 1 and its performance budget): a
|
|
4686
|
+
// kernel command that resolves a local deployment lists it when it is not listed yet. The one table
|
|
4687
|
+
// of those commands is here. The check runs on the command's own resolution, once, at exit, on
|
|
4688
|
+
// the canonical root when the command resolved one (lib/resolved-deployment.mjs; lib/deployments.mjs
|
|
4689
|
+
// listResolved): a listed deployment costs one bounded read of the list. Never on --server (the remote's path is not this computer's), never for
|
|
4690
|
+
// help, and silent: no output, no change to the command's answer or exit status.
|
|
4691
|
+
const LISTS_ITS_DEPLOYMENT = new Set(["automations", "capabilities", "doctor", "harness", "inspect", "instance", "launch-config", "operation", "package", "pane", "readiness", "retire", "schedule", "session", "soul", "souls", "spawn", "status", "sync", "teams", "trigger", "update", "workspace", "worktree"]);
|
|
4692
|
+
if (LISTS_ITS_DEPLOYMENT.has(cmd) && flag("server") === undefined && !args.slice(1).some((a) => a === "--help" || a === "-h")) observeResolvedDeployment(listResolved);
|
|
4610
4693
|
if (cmd === "onboard") {
|
|
4611
4694
|
if (args.includes("--help") || args.includes("-h")) { if (JSON_MODE) jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); else usageFor(cmd); process.exit(0); }
|
|
4612
4695
|
await onboardCmd();
|
|
@@ -4620,6 +4703,7 @@ const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
|
|
|
4620
4703
|
if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); process.exit(0); } usageFor(cmd); process.exit(0); }
|
|
4621
4704
|
if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
|
|
4622
4705
|
else if (cmd === "server") await serverCmd();
|
|
4706
|
+
else if (cmd === "deployments") deploymentsCmd();
|
|
4623
4707
|
else if (cmd === "inspect") await inspectCmd();
|
|
4624
4708
|
else if (cmd === "operation") await operationCmd();
|
|
4625
4709
|
else if (cmd === "launch-config") await launchConfigCmd();
|
|
@@ -4775,9 +4859,21 @@ Usage:
|
|
|
4775
4859
|
and prints the
|
|
4776
4860
|
next steps (clone members you work IN, spawn the
|
|
4777
4861
|
workspace's setup expert (the soul holding oats.setup));
|
|
4778
|
-
creates no soul, spawns nothing
|
|
4862
|
+
creates no soul, spawns nothing; lists <dir> in this
|
|
4863
|
+
computer's deployments (below)
|
|
4779
4864
|
[--check] --check: write nothing; report <dir> (~ = this home),
|
|
4780
4865
|
its state and whether Git reads the workspace remote
|
|
4866
|
+
oats deployments [list] [--json] this computer's deployments (~/.oats/config/
|
|
4867
|
+
deployments.json): path, state (ok, missing,
|
|
4868
|
+
not-a-deployment, unreadable) and how each was listed.
|
|
4869
|
+
Onboard lists what it creates, and a kernel command run
|
|
4870
|
+
in an unlisted deployment lists it; ~/Agents is
|
|
4871
|
+
imported once, on first use
|
|
4872
|
+
oats deployments add [<dir>] [--json] list the deployment at or above <dir> (default: here)
|
|
4873
|
+
oats deployments remove <path> [--json] take <path> off the list (nothing on disk is touched);
|
|
4874
|
+
nothing lists it again but an explicit add or onboard
|
|
4875
|
+
oats deployments import --from desktop <path>... [--json]
|
|
4876
|
+
the Desktop's one-time import of its own lists
|
|
4781
4877
|
oats session inspect|input|attach --home <absolute-home> [--text-file <path>] [--json]
|
|
4782
4878
|
oats session attach --home <absolute-home> [--detach-key <key>]
|
|
4783
4879
|
a viewer of one instance. <key> (C-<letter>, M-<letter
|
|
@@ -4829,30 +4925,66 @@ Usage:
|
|
|
4829
4925
|
spawn hooks); --model replaces the recorded model
|
|
4830
4926
|
for this and later starts; a live harness is refused
|
|
4831
4927
|
oats spawn <agent> [--task <text> | --task-file <f>] spawn an instance (tmux; --no-launch
|
|
4832
|
-
[--purpose <slug>
|
|
4833
|
-
[--
|
|
4834
|
-
|
|
4835
|
-
|
|
4836
|
-
|
|
4837
|
-
[--
|
|
4838
|
-
|
|
4839
|
-
[--
|
|
4840
|
-
|
|
4841
|
-
|
|
4842
|
-
|
|
4843
|
-
|
|
4928
|
+
[--purpose <slug> | --name <slug>] = scaffold only); the agent is a workspace
|
|
4929
|
+
[--repo <path>] soul or a capability-defined agent
|
|
4930
|
+
--purpose derives <agent>-<purpose>;
|
|
4931
|
+
--name is exact (no prefix), unused in the
|
|
4932
|
+
deployment, a slug and not a soul name
|
|
4933
|
+
[--dir <scope>] [--agents-root <abs>] deployment scope; --agents-root must match
|
|
4934
|
+
that deployment's agents root
|
|
4935
|
+
[--parent <instance>] sugar for --relative-to X --relation child
|
|
4936
|
+
[--relation child|sibling|parent|unrelated] anchor with --relative-to (except unrelated);
|
|
4937
|
+
[--relative-to <instance>] default: unrelated, top-level
|
|
4938
|
+
[--relative-root <agents-root>] disambiguates same-named anchors
|
|
4939
|
+
[--work worktree|checkout|attached|workspace|directory] override the soul's work mode
|
|
4940
|
+
[--work-dir <owner-work>] attached: the owner's work tree (always a child)
|
|
4941
|
+
[--branch <b>] [--base <ref>] worktree branch and starting ref;
|
|
4942
|
+
--base: worktree only; defaults to the soul
|
|
4943
|
+
commit observed by spawn (#445)
|
|
4844
4944
|
directory: owned home/work, config context may
|
|
4845
4945
|
be non-Git; rejects --work-dir and --branch
|
|
4846
|
-
[--
|
|
4847
|
-
|
|
4848
|
-
|
|
4946
|
+
[--harness pi|claude|codex] [--launch-config <name>|none] explicit launch selection;
|
|
4947
|
+
otherwise oats-local.yaml souls.launch.<soul>,
|
|
4948
|
+
then souls.launch."*", then the soul's launch:, then pi;
|
|
4949
|
+
a harness uses its host default configuration if set;
|
|
4950
|
+
none selects the bare harness; a named configuration
|
|
4951
|
+
is a unit (a conflicting --harness is refused)
|
|
4952
|
+
[--model <id>|@native-default] override the selected model; @native-default
|
|
4953
|
+
selects the harness's own model default
|
|
4954
|
+
[--backend tmux] [--yolo|--no-yolo] session backend and launch permission option
|
|
4955
|
+
[--no-launch] [--json] scaffold without launching; JSON result envelope
|
|
4956
|
+
[--allow-child-spawns|--no-child-spawns] this instance's child-spawn policy (default:
|
|
4957
|
+
allowed); enforced by OATS, not an OS sandbox
|
|
4849
4958
|
[--provider <capability> <key>=<value>] a provider setting for this spawn only
|
|
4850
4959
|
(repeatable; dotted keys nest; recorded in
|
|
4851
4960
|
instance.json providers.<capability>)
|
|
4852
|
-
[--preview
|
|
4853
|
-
|
|
4854
|
-
|
|
4855
|
-
|
|
4961
|
+
[--preview] decide everything, create no instance; --json
|
|
4962
|
+
includes the decision revision for confirmation
|
|
4963
|
+
[--expect-decision <rev>] bind apply to the previewed decision; drift refuses
|
|
4964
|
+
[--idempotency-key <key>] with --expect-decision, replay the completed receipt
|
|
4965
|
+
for the same key and confirmed decision; a different
|
|
4966
|
+
decision conflicts, an unfinished spawn refuses
|
|
4967
|
+
[--max-age <s>] reuse heads up to <s> seconds old (0-86400; 0 live),
|
|
4968
|
+
on preview or --expect-decision apply only;
|
|
4969
|
+
refused with --server; decision binding still holds
|
|
4970
|
+
[--wake-file <json-file> | --wake-json <json-text>] wake object: {cron, tz, message, enabled}
|
|
4971
|
+
--wake-json wins over --wake-file; either overrides
|
|
4972
|
+
--wake-every and --wake-cron
|
|
4973
|
+
[--wake-every <N> | --wake-cron <expr>] alternative: cron */N minutes (1-59) or explicit cron
|
|
4974
|
+
requires --wake-message <text> or --wake-message-file <f>;
|
|
4975
|
+
--wake-message-file wins over --wake-message
|
|
4976
|
+
[--wake-tz <zone>] optional for cron/every (default: local zone);
|
|
4977
|
+
saved after spawn, bound to the new home
|
|
4978
|
+
--runtime <harness> compatibility alias for --harness (deprecated)
|
|
4979
|
+
--instance <name> compatibility token for older routed hosts;
|
|
4980
|
+
refused locally: use --purpose or --name
|
|
4981
|
+
--trigger-event <json-file> internal trigger-runner event input, copied to
|
|
4982
|
+
<home>/.oats/trigger-event.json, exposed through
|
|
4983
|
+
OATS_TRIGGER_EVENT_FILE and recorded in
|
|
4984
|
+
instance.json.trigger (docs/schedules.md)
|
|
4985
|
+
[--help|-h] global help switches: show usage and exit
|
|
4986
|
+
oats spawn <agent> ... --server <id> routed spawn on the server's installed oats;
|
|
4987
|
+
--server is consumed before the local flag scanner
|
|
4856
4988
|
oats retire <instance> [--force] retire an instance (window, hooks,
|
|
4857
4989
|
[--self] worktree, home); --self = retire the
|
|
4858
4990
|
[--keep-dir] [--json] CALLING instance: the window dies, then
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -46,7 +46,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
46
46
|
"server-probe-features","worktree-event","trigger-sources","session-attach-detach-key",
|
|
47
47
|
"lifecycle-kernel-codes","schedule-run-warnings","lifecycle-claim-stop","launch-prompt-dev-channel",
|
|
48
48
|
"soul-launch","retire-plan-own-worktree","spawn-kernel-codes","soul-skills","roster-workspace-key","spawn-apply-max-age",
|
|
49
|
-
"status-retire-state","session-inspect-size","session-inspect-running"],
|
|
49
|
+
"status-retire-state","session-inspect-size","session-inspect-running","deployments-list"],
|
|
50
50
|
"automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
|
|
51
51
|
"readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
|
|
52
52
|
"capabilityShowApi":1}
|
|
@@ -135,6 +135,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
135
135
|
| `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
136
|
| `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
137
|
| `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`) | |
|
|
138
|
+
| `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` |
|
|
138
139
|
| `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 | |
|
|
139
140
|
|
|
140
141
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
@@ -884,7 +885,8 @@ same argument, given once). The ref is checked before anything is written.
|
|
|
884
885
|
"next":{"clone":[{"key":"github.com/acme/agents","name":"agents","url":"https://github.com/acme/agents.git","dir":"/w/agents-repo","present":false,"host":true},
|
|
885
886
|
{"key":"github.com/acme/platform","name":"platform","url":"https://github.com/acme/platform.git","dir":"/w/platform","present":true,"host":false}],
|
|
886
887
|
"spawn":"oats spawn acme-oats-setup-expert --dir /w",
|
|
887
|
-
"souls":["acme-oats-setup-expert","platform-engineer","release-manager"]}
|
|
888
|
+
"souls":["acme-oats-setup-expert","platform-engineer","release-manager"]},
|
|
889
|
+
"listed":true}
|
|
888
890
|
```
|
|
889
891
|
|
|
890
892
|
- `sync` is the full [`oats sync`](#oats-sync) report (abridged above).
|
|
@@ -922,6 +924,10 @@ same argument, given once). The ref is checked before anything is written.
|
|
|
922
924
|
share a repository name, `<member repo key>/<soul>`. The text output's step 3 names
|
|
923
925
|
the same soul, or, with none, the conventional name to add.
|
|
924
926
|
`next.souls` is the first three soul names, sorted.
|
|
927
|
+
- `listed` (feature `deployments-list`): `true` once the deployment is on this
|
|
928
|
+
computer's deployments list ([This computer's deployments](#this-computers-deployments-oats-deployments)),
|
|
929
|
+
else `{code, message}` with the list's error (`E_DEPLOYMENTS_*`). A failed
|
|
930
|
+
add never fails the onboard. `--check` lists nothing.
|
|
925
931
|
- Errors: `E_BAD_ARGS` (usage, no `--workspace`, a repeated directory, an
|
|
926
932
|
unknown flag), `E_REPO_REF`, `E_ALREADY_ONBOARDED {local, dir}` (this
|
|
927
933
|
directory already has `oats-local.yaml`), `E_ONBOARD_FAILED {dir}`. A
|
|
@@ -929,6 +935,82 @@ same argument, given once). The ref is checked before anything is written.
|
|
|
929
935
|
carries `details: {…, dir, rolledBack: true}`; a later failure keeps the
|
|
930
936
|
files and carries `details: {…, dir, local}`.
|
|
931
937
|
|
|
938
|
+
<a id="this-computers-deployments-oats-deployments"></a>
|
|
939
|
+
### This computer's deployments (`oats deployments`)
|
|
940
|
+
|
|
941
|
+
Feature `deployments-list`. The kernel's per-user list of the deployments on
|
|
942
|
+
this computer ([workspaces.md](workspaces.md#this-computers-deployments)).
|
|
943
|
+
Every verb runs from anywhere, needs no deployment, takes no `--server`
|
|
944
|
+
(`E_BAD_ARGS`) and never routes to another machine. Each runs the first-use
|
|
945
|
+
`~/Agents` import before it answers.
|
|
946
|
+
|
|
947
|
+
```text
|
|
948
|
+
oats deployments [list] --json
|
|
949
|
+
oats deployments add [<dir>] [--via tui|desktop] --json
|
|
950
|
+
oats deployments remove <path> --json
|
|
951
|
+
oats deployments import --from desktop <path>... --json
|
|
952
|
+
```
|
|
953
|
+
|
|
954
|
+
Every answer is a closed key set ([Shapes are closed](#scope)):
|
|
955
|
+
|
|
956
|
+
| Verb | `result` keys, exactly |
|
|
957
|
+
|---|---|
|
|
958
|
+
| `list` | `deploymentsApi`, `file`, `deployments`, `imports`; each row `path`, `name`, `state`, `addedAt`, `via` |
|
|
959
|
+
| `add` | `path`, `added` |
|
|
960
|
+
| `remove` | `path`, `removed` |
|
|
961
|
+
| `import` | `imported`, `at`, `added` on the first run; `imported`, `at` on every later one |
|
|
962
|
+
|
|
963
|
+
A key added to any of them later is a contract change: it is announced here
|
|
964
|
+
first, and accepted by the readers in `packages/client/deployment-list.mjs`
|
|
965
|
+
before a kernel that writes it ships. A change of meaning moves
|
|
966
|
+
`deploymentsApi` to 2. A tombstone stays inside the file: its `removed` and
|
|
967
|
+
`removedAt` never reach an answer, and a tombstoned row is never listed.
|
|
968
|
+
|
|
969
|
+
**`list`** (the default verb):
|
|
970
|
+
|
|
971
|
+
```json
|
|
972
|
+
{"deploymentsApi":1,"file":"/home/me/.oats/config/deployments.json",
|
|
973
|
+
"deployments":[{"path":"/home/me/acme","name":"acme","state":"ok","addedAt":"2026-10-19T10:00:00.000Z","via":"onboard"}],
|
|
974
|
+
"imports":{"agents-dir":"2026-10-19T10:00:00.000Z"}}
|
|
975
|
+
```
|
|
976
|
+
|
|
977
|
+
- The answer is exactly these four keys, and each row exactly
|
|
978
|
+
`{path, name, state, addedAt, via}`. A row `remove` took out is never in
|
|
979
|
+
it, and fields of the file the answer does not name never reach it.
|
|
980
|
+
- Rows are sorted by `path`. `name` is the last segment of `path`.
|
|
981
|
+
- `state`: `ok`, `missing`, `not-a-deployment` or `unreadable`, from
|
|
982
|
+
existence checks only. A row is a suggestion: a client admits the
|
|
983
|
+
deployment again before it serves it.
|
|
984
|
+
- `via`: `onboard`, `tui`, `desktop`, `cli`, `import:agents-dir` or
|
|
985
|
+
`import:desktop`, for information only.
|
|
986
|
+
- `imports`: the one-time markers as stored (`agents-dir`, `desktop`), each
|
|
987
|
+
the time it ran.
|
|
988
|
+
|
|
989
|
+
**`add`** lists the deployment at or above `<dir>` (default: the working
|
|
990
|
+
directory), canonical, and clears a `remove`. → `{"path":"/home/me/acme","added":true}`;
|
|
991
|
+
`added: false` when it was listed already, and nothing is written. `--via
|
|
992
|
+
tui|desktop` names the client that adds it (default `cli`); any other value is
|
|
993
|
+
`E_BAD_ARGS`. Outside every deployment: `E_LOCAL_MISSING {dir}`.
|
|
994
|
+
|
|
995
|
+
**`remove`** takes the row whose stored path is `<path>` resolved (no walk up,
|
|
996
|
+
so a row whose directory is gone can be removed); nothing on disk is touched.
|
|
997
|
+
→ `{"path":"/home/me/acme","removed":true}`; `removed: false`, exit 0, when
|
|
998
|
+
`<path>` is not listed. The row is kept as a tombstone: nothing but `add` or
|
|
999
|
+
`onboard` lists that path again.
|
|
1000
|
+
|
|
1001
|
+
**`import --from desktop`** is the Desktop's one-time migration of its own
|
|
1002
|
+
lists. The first run lists every absolute path given, whatever its state, and
|
|
1003
|
+
sets `imports.desktop`, in one write →
|
|
1004
|
+
`{"imported":true,"at":"<marker>","added":["/home/me/acme"]}` (`added`: the
|
|
1005
|
+
paths it listed; zero paths are accepted). Every later run changes nothing →
|
|
1006
|
+
`{"imported":false,"at":"<marker>"}`. A relative path is `E_BAD_ARGS` before
|
|
1007
|
+
anything is written. A path `remove` took out is not listed again.
|
|
1008
|
+
|
|
1009
|
+
Errors of every verb: `E_DEPLOYMENTS_INVALID {file, reason}`,
|
|
1010
|
+
`E_DEPLOYMENTS_VERSION {file, schemaVersion}`, `E_DEPLOYMENTS_BUSY {file, lock}`,
|
|
1011
|
+
`E_DEPLOYMENTS_WRITE {file}`, `E_DEPLOYMENTS_IMPORT {dir}` ([the messages](workspaces.md#this-computers-deployments)),
|
|
1012
|
+
and `E_BAD_ARGS`.
|
|
1013
|
+
|
|
932
1014
|
### `oats sync`
|
|
933
1015
|
|
|
934
1016
|
```text
|
|
@@ -2241,6 +2323,11 @@ containing them ships. For operator recovery, see
|
|
|
2241
2323
|
|
|
2242
2324
|
## Spawn
|
|
2243
2325
|
|
|
2326
|
+
Use `oats spawn --help` (also the spawn section of `oats help`) for the
|
|
2327
|
+
existing flag inventory, including compatibility and internal inputs. Help
|
|
2328
|
+
needs no deployment; the preview and apply contracts below govern confirmation
|
|
2329
|
+
and replay.
|
|
2330
|
+
|
|
2244
2331
|
### The preview
|
|
2245
2332
|
|
|
2246
2333
|
```text
|
|
@@ -2287,7 +2374,8 @@ it to a temporary copy (`soulFetched: true`).
|
|
|
2287
2374
|
([Instance names](#instance-names)). `home` and `worktree` (worktree mode,
|
|
2288
2375
|
else `null`) are canonical: never derive paths.
|
|
2289
2376
|
- `repo`: `--repo`, else the `clones:` entry, else `<deployment>/<member>`.
|
|
2290
|
-
- `branch` defaults to `agents/<instance>` (`--branch
|
|
2377
|
+
- In worktree mode, `branch` defaults to `agents/<instance>` (`--branch <b>`
|
|
2378
|
+
overrides); `base` is
|
|
2291
2379
|
`--base` resolved to `oid`. Without `--base`, when `repo` is a clone of the
|
|
2292
2380
|
soul's repository, `base` is `{ref: <repo key>, oid: <the commit the spawn
|
|
2293
2381
|
observed>}`, fetched into the clone at apply (`E_REMOTE_UNREADABLE` when it
|
|
@@ -2495,6 +2583,42 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
|
|
|
2495
2583
|
a silent `-2`.
|
|
2496
2584
|
- The name is part of the decision.
|
|
2497
2585
|
|
|
2586
|
+
### Spawn origin
|
|
2587
|
+
|
|
2588
|
+
For new instances from OATS 0.64.0, `spawnOrigin` describes the caller:
|
|
2589
|
+
`instance` when `OATS_INSTANCE` and/or `OATS_INSTANCE_HOME` identify an extant
|
|
2590
|
+
instance home in this deployment, otherwise `operator`. It is recorded in
|
|
2591
|
+
`instance.json` and reported unchanged by the spawn result and status JSON.
|
|
2592
|
+
|
|
2593
|
+
- A home alone must be absolute and resolve canonically to a home here, with a
|
|
2594
|
+
readable instance record whose name agrees with its directory.
|
|
2595
|
+
- A name alone must resolve uniquely to such a home here.
|
|
2596
|
+
- With both supplied, the name and canonical home must agree. An explicit
|
|
2597
|
+
valid home can disambiguate a duplicated historical name.
|
|
2598
|
+
- Invalid, stale, foreign or contradictory supplied evidence records
|
|
2599
|
+
`operator`, with no fallback to another signal. The working directory,
|
|
2600
|
+
`OATS_HOME`, `PI_AGENT_*`, relation and attached ownership do not supply
|
|
2601
|
+
caller identity. A stopped but extant home counts; no process or tmux
|
|
2602
|
+
liveness check is made.
|
|
2603
|
+
|
|
2604
|
+
A shell, Desktop or console caller without valid instance context records
|
|
2605
|
+
`operator`, even with `--parent`. A caller with valid instance context records
|
|
2606
|
+
`instance`, even without a relation. A shell that inherits that context also
|
|
2607
|
+
records `instance`. `parentInstance`, `relativeTo` and `relation` still describe
|
|
2608
|
+
lineage independently; existing child-spawn policy enforcement is unchanged.
|
|
2609
|
+
This field is informational attribution, not agent-authorship proof, an
|
|
2610
|
+
identity credential, a security boundary or an authorization input. There is
|
|
2611
|
+
no flag to choose it.
|
|
2612
|
+
|
|
2613
|
+
For a remote spawn (`--server`), attribution uses the host-side caller context.
|
|
2614
|
+
Caller identity is not forwarded, so the origin is normally `operator`.
|
|
2615
|
+
|
|
2616
|
+
Existing homes keep their recorded value, including the relation-based meaning
|
|
2617
|
+
recorded by earlier kernels; an absent value stays absent in local status.
|
|
2618
|
+
Idempotent spawn replay returns the recorded value. Remote rows relay the
|
|
2619
|
+
host's value unchanged, including historical values, and use `null` when the
|
|
2620
|
+
host does not supply one. Consumers must allow for those historical meanings.
|
|
2621
|
+
|
|
2498
2622
|
<a id="spawn-errors"></a>
|
|
2499
2623
|
### Spawn errors
|
|
2500
2624
|
|
package/docs/desktop.md
CHANGED
|
@@ -120,14 +120,23 @@ OATS deployment — the directory (the operator's choice) holding
|
|
|
120
120
|
`oats-local.yaml` and `agents/`. A folder that is not a deployment is never
|
|
121
121
|
opened: started from Finder, with nothing open to restore, the window shows
|
|
122
122
|
the workspace switcher instead. It lists the deployments on this computer
|
|
123
|
-
under **On this computer
|
|
124
|
-
|
|
125
|
-
|
|
123
|
+
under **On this computer**: those on this computer's deployments list
|
|
124
|
+
(`oats deployments`, see [Workspaces](workspaces.md)) and a saved one,
|
|
125
|
+
that are not open. Click one to open it in this window. A deployment the list
|
|
126
|
+
holds but that can't be opened says why: missing (the folder is gone, or its
|
|
127
|
+
volume isn't mounted), not a deployment any more, or can't be checked. **Remove**
|
|
128
|
+
beside a row takes it off the list (Right Arrow, then Enter, from the
|
|
129
|
+
keyboard); nothing on disk changes. With an oats that has no such list, the
|
|
130
|
+
switcher shows the saved deployments and says "This oats can't list this
|
|
131
|
+
computer's deployments. Update oats." **Add local workspace… → Browse**
|
|
132
|
+
points it at any other deployment.
|
|
126
133
|
A picked folder without `oats-local.yaml` is offered onboarding instead. The
|
|
127
134
|
Desktop never parses the deployment: its members, lock state and header come
|
|
128
135
|
from `oats workspace status`, and its instances from the deployment's one
|
|
129
136
|
`agents/` root.
|
|
130
|
-
|
|
137
|
+
Every deployment you open (an add, or the one the app was launched on) is
|
|
138
|
+
put on this computer's deployments list, so it is offered next time. The first launch of this Desktop moves its own list of
|
|
139
|
+
recently added workspaces there, once.
|
|
131
140
|
**Browse** opens in the folder holding the workspace most recently added or
|
|
132
141
|
opened, or your home directory when there is none (never ~/Downloads);
|
|
133
142
|
**Choose oats…** opens in the directory of the chosen or discovered CLI.
|
|
@@ -295,7 +304,7 @@ feature (OATS 0.36.0); without it each deployment has its own entry.
|
|
|
295
304
|
- **Deployments.** The **Deployments** page (formerly the Active overview)
|
|
296
305
|
shows the workspace's overview trees. **All** stacks one section per
|
|
297
306
|
deployment, each headed by its machine and folder ("This Mac ·
|
|
298
|
-
~/
|
|
307
|
+
~/acme", "altair · ~/northwind"). Then each deployment has a tab of
|
|
299
308
|
its own, named by its machine ("altair"; "This Mac · oats-v2" when this Mac
|
|
300
309
|
holds two). A workspace with one deployment shows just that deployment's
|
|
301
310
|
tab. The tab you chose is remembered per workspace. With two or more
|
|
@@ -58,7 +58,7 @@ exists. A fallback shell reads `running: false` with `runtimeState: "shell"`;
|
|
|
58
58
|
a retained dead pane also reads `false`. A wrapper shell with a live non-shell
|
|
59
59
|
descendant still reads `true`. Status shares session inspection's pane rule,
|
|
60
60
|
with one batched pane read per socket/session and one lazy process scan across
|
|
61
|
-
all
|
|
61
|
+
all panes that need it. A recorded server or pane that cannot be read gives
|
|
62
62
|
`running: null` with `runtimeState: "unreachable"`. The environment variables are read when the spawn runs, and `oats
|
|
63
63
|
inspect --json` reports the session a new spawn would open in as `session`
|
|
64
64
|
(`{tmuxSession}`). A spawn refuses an instance name that is a live window in the
|
|
@@ -1073,12 +1073,16 @@ oats session attach --home /abs/home --detach-key 'C-\'
|
|
|
1073
1073
|
wrapper shell included; `false` for a fallback shell (`state: shell`, where
|
|
1074
1074
|
`present` stays `true`), an absent or dead pane or a missing home
|
|
1075
1075
|
(`stopped`) and a home that never launched (`not-launched`). It costs no
|
|
1076
|
-
second observation: at most one process-table read,
|
|
1077
|
-
|
|
1076
|
+
second observation: at most one process-table read, only for a pane whose
|
|
1077
|
+
command is a shell, empty or the literal `unset`. An empty or `unset` label
|
|
1078
|
+
uses the pane PID's own process name from that same scan to establish a shell
|
|
1079
|
+
before checking descendants; an unreadable or non-shell own process stays
|
|
1080
|
+
`unknown` (`running: true`). `running` is activity at the authorized
|
|
1078
1081
|
endpoint. It does not say the agent is generating, idle, healthy or ready
|
|
1079
1082
|
for input, nor that it consumed a wake, and it does not prove which
|
|
1080
|
-
executable runs if a process inside the pane was replaced. When the
|
|
1081
|
-
|
|
1083
|
+
executable runs if a process inside the pane was replaced. When the backend
|
|
1084
|
+
cannot be read, a required process-table read for an explicitly labelled
|
|
1085
|
+
shell fails, or the pane answer is
|
|
1082
1086
|
malformed or split, inspect is an error as before, never `running: false`.
|
|
1083
1087
|
That includes a tmux server that is gone (`no server running on` its
|
|
1084
1088
|
socket, as after a reboot): status reads that row as `running: false`, and
|
package/docs/first-team.md
CHANGED
|
@@ -1,5 +1,11 @@
|
|
|
1
1
|
# Run your first OATS team
|
|
2
2
|
|
|
3
|
+
**The quick way:** the README's [Start here](../README.md#start-here): your
|
|
4
|
+
coding agent downloads the `oats-getting-started` skill verbatim and follows
|
|
5
|
+
it. It installs OATS, creates your workspace with its own setup expert soul (or joins
|
|
6
|
+
an existing workspace), and hands over to that expert. This page is the manual
|
|
7
|
+
path, for writing a workspace by hand.
|
|
8
|
+
|
|
3
9
|
The model is in [workspaces.md](workspaces.md), packages in
|
|
4
10
|
[packages.md](packages.md), and the deployment layout this page creates in
|
|
5
11
|
[configuration.md](configuration.md).
|
package/docs/implementation.md
CHANGED
|
@@ -53,9 +53,10 @@ effect of reading: for each deployment opened in a run it runs the kernel
|
|
|
53
53
|
of the same install and the shared liveness collector as children, through
|
|
54
54
|
the shared observer and refresh loop; it runs that kernel's read of the
|
|
55
55
|
other machines (`oats server roster --json`), one at a time and awaited by
|
|
56
|
-
no cycle; it ends every child; and it makes the
|
|
57
|
-
system the workspace switcher needs (
|
|
58
|
-
|
|
56
|
+
no cycle; it ends every child; and it makes the one look at the file
|
|
57
|
+
system the workspace switcher needs (whether a picked row is a deployment).
|
|
58
|
+
This computer's list of deployments is the kernel's: `lib/main.mjs` reads
|
|
59
|
+
and changes it through the shared `cliDeploymentList`. `lib/store.mjs` is the state and a pure
|
|
59
60
|
`reduce(state, event)`; `lib/model.mjs` turns the state into the rows to
|
|
60
61
|
draw by calling the shared readers through `lib/client.mjs`, the one module
|
|
61
62
|
that imports `packages/client/`; `lib/views/` are pure functions from that
|
|
@@ -126,6 +127,8 @@ and the rules its tests pin.
|
|
|
126
127
|
| `read-ahead.mjs`, `read-ahead-worker.mjs` | read-ahead for the tree digests (`fingerprintTrees`): while a digest reads a tree on the calling thread, a planner thread walks it in the digest's order and a few reader threads read the next files into the page cache, within a window of bytes and files ahead of the digest. The digest still reads and hashes every byte itself, so no value or error depends on it; one that cannot start or falls behind costs speed only |
|
|
127
128
|
| `session-input.mjs` | session inspection and input transport. `createSessionPaneInspector` interprets one window's panes for both lifecycle inspection and status, sharing a lazy process scan across a status read; `core.mjs` batches pane reads per socket/session and applies its shared `harnessRunning` predicate |
|
|
128
129
|
| `servers.mjs` | routing commands to a registered server |
|
|
130
|
+
| `deployments.mjs` | this computer's deployments ([workspaces.md](workspaces.md#this-computers-deployments)): the per-user files `<OATS_HOME_DIR>/config/deployments.json` (the list, 0600 in a 0700 `config/`) and `config/deployments.lock` (`withDirLock`, waited for up to 3 s), the bounded no-follow read, the atomic write, the first-use `~/Agents` import (the real `$HOME`) and the five `E_DEPLOYMENTS_*` codes. `oats deployments`, onboard's `listed` and the auto-add write through it. `listResolved` is the auto-add: `bin/oats.mjs` sets it as the observer of `resolved-deployment.mjs` for the commands in its one table (`LISTS_ITS_DEPLOYMENT`), so it runs once per process on the deployment the command itself resolved. A listed deployment costs one bounded read (no lock, write, process or realpath), another spelling of it a realpath; a spelled root in a linked worktree or submodule (a `.git` file above it) is left to the commands that resolve its canonical root; only a path not listed is canonicalized and takes the lock, without waiting for it. It never throws or prints |
|
|
131
|
+
| `resolved-deployment.mjs` | the deployment a command resolved: `loadLocal` (`workspace.mjs`) reports the directory it found as spelled, `ensureRoot` (`core.mjs`) the canonical one, and the observer the CLI set is called once, at exit, with the first canonical root (else the first spelled one), so an earlier spelling never stands for a root the command canonicalized. A no-op until the CLI sets one, so library callers and tests are unaffected. Dependency-free |
|
|
129
132
|
| `launch-prompt-evidence.mjs` | private bounded storage of exact unmatched, stable-screen completed or flag-ignored notice frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
|
|
130
133
|
| `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
|
|
131
134
|
| `launch-prompt-fixtures.mjs` | the development-channel tolerance list (`launch-prompt-fixtures/dev-channel-confirmation.json`): engagement from the argv, the enumerated normalization, equality matching, the `flag-ignored` notice block, the running-session banner hint, what differed, and the Claude version read from the executable's path |
|
|
@@ -501,6 +504,17 @@ the rule:
|
|
|
501
504
|
preload in `OATS_TEST_RUN_DIR`, and the preload takes that variable out of
|
|
502
505
|
the file's environment before any code of the file runs. No test sees it,
|
|
503
506
|
nor any process a test starts.
|
|
507
|
+
- The preload also gives each file an `OATS_HOME_DIR` of its own,
|
|
508
|
+
`<n>.oats-home` beside its directory, holding a deployments list whose
|
|
509
|
+
`~/Agents` import is marked done (awebai/oats#1390). Any kernel command run
|
|
510
|
+
in a deployment adds that deployment to this computer's list, so a test
|
|
511
|
+
that runs the CLI with the environment it was given never writes the
|
|
512
|
+
person's `~/.oats`, nor reads their `~/Agents`. A test that names an
|
|
513
|
+
`OATS_HOME_DIR` of its own beside the person's `HOME` seeds the same marker
|
|
514
|
+
(`test/helpers/host-fixture.mjs` `deploymentsImported`); a fixture with a
|
|
515
|
+
`HOME` of its own needs nothing. When the run has ended, a row added to the
|
|
516
|
+
person's list during the run under a temporary directory fails the run,
|
|
517
|
+
naming it.
|
|
504
518
|
- When the run has ended it reads each file's directory. If one is not empty
|
|
505
519
|
the run fails, even if every test passed, and names each file and what it
|
|
506
520
|
left.
|