@awebai/oats 0.69.12 → 0.69.14
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 +216 -178
- package/bin/oats.mjs +176 -184
- package/docs/capabilities.md +4 -1
- package/docs/configuration.md +63 -5
- package/docs/container.md +246 -0
- package/docs/design/2026-09-23-workspace-module-contracts.md +2 -0
- package/docs/desktop-cli-api.md +376 -37
- package/docs/desktop-instance-start.md +4 -1
- package/docs/desktop.md +58 -12
- package/docs/execution-targets.md +69 -6
- package/docs/implementation.md +86 -29
- package/docs/integrations.md +3 -2
- package/docs/knowledge-and-learning.md +72 -0
- package/docs/oats-local.schema.json +11 -2
- package/docs/official-catalog.md +39 -5
- package/docs/packages.md +93 -14
- package/docs/release-lane.md +2 -1
- package/docs/release-notes/v0.69.13.md +767 -0
- package/docs/release-notes/v0.69.14.md +83 -0
- package/docs/schedules.md +26 -3
- package/docs/servers.md +181 -5
- package/docs/souls-and-instances.md +140 -11
- package/docs/tui.md +1 -1
- package/docs/upgrading.md +24 -5
- package/docs/workspaces.md +31 -5
- package/lib/claim.mjs +21 -5
- package/lib/command-flags.mjs +238 -0
- package/lib/core.mjs +791 -563
- package/lib/deployments.mjs +4 -3
- package/lib/dir-lock.mjs +126 -31
- package/lib/errors.mjs +1 -1
- package/lib/harness-token.mjs +110 -0
- package/lib/hot-reads.mjs +4 -3
- package/lib/instance-events.mjs +28 -6
- package/lib/instance-git.mjs +138 -13
- package/lib/instance-inspect.mjs +6 -1
- package/lib/instance-listing.mjs +80 -38
- package/lib/instance-resolution.mjs +56 -3
- package/lib/instance-upgrade.mjs +16 -20
- package/lib/launch-env-exec.sh +7 -0
- package/lib/launch-env.mjs +74 -0
- package/lib/launch-preference.mjs +19 -12
- package/lib/member-clone.mjs +7 -1
- package/lib/packages.mjs +74 -2
- package/lib/read-call.mjs +3 -0
- package/lib/reader.mjs +3 -2
- package/lib/refused-text.mjs +3 -2
- package/lib/remote.mjs +119 -27
- package/lib/retained-after-retire.mjs +2 -7
- package/lib/retire-git-forms.mjs +41 -0
- package/lib/retire-incomplete.mjs +96 -0
- package/lib/schedule.mjs +2 -1
- package/lib/servers.mjs +78 -23
- package/lib/session-resume.mjs +68 -53
- package/lib/session-seen.mjs +54 -5
- package/lib/start-env.mjs +13 -7
- package/lib/system-tools.mjs +1 -1
- package/lib/teams.mjs +11 -4
- package/lib/upgrade-state.mjs +13 -2
- package/lib/worktree.mjs +56 -7
- package/package-catalog.json +1 -1
- package/package.json +2 -1
- package/packages/client/instance-lifecycle.mjs +1 -1
- package/packages/client/lifecycle-contract.mjs +3 -1
- package/packages/client/session-resume-cli.mjs +2 -1
- package/packages/client/session-start.mjs +10 -7
- package/packages/client/workspace-cli.mjs +5 -1
- package/share/oats-login-receive +204 -0
- package/skills/oats-getting-started/SKILL.md +92 -25
- package/lib/tmux-config.mjs +0 -35
package/docs/workspaces.md
CHANGED
|
@@ -54,7 +54,7 @@ members: # repo refs, NO @revision (E_WORKSPAC
|
|
|
54
54
|
- git:github.com/acme/tools # a member that ALSO publishes a package (see below)
|
|
55
55
|
|
|
56
56
|
packages: # the ONLY versioned things
|
|
57
|
-
oats.framework: v1.
|
|
57
|
+
oats.framework: v1.23.0 # bare version → resolves through the official catalog
|
|
58
58
|
oats.okf: v5.8.0
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
|
@@ -336,6 +336,10 @@ output, `timeout` for a timeout). The partial cache, its fetch mode and its
|
|
|
336
336
|
commit pins are preserved, and a later read can retry the version probe.
|
|
337
337
|
This also applies to library reads without a session. A cache already using
|
|
338
338
|
whole trees stays in that mode when a later probe finds a newer Git.
|
|
339
|
+
With an older Git, a command says so once, however many repositories it
|
|
340
|
+
fetches: one `oats: warning` line naming the Git version and the 2.45 floor,
|
|
341
|
+
and saying that OATS fetches whole trees instead. A Git of 2.45 or later
|
|
342
|
+
removes the line.
|
|
339
343
|
|
|
340
344
|
**Repo-owned capabilities.** `private: true` in a capability's `oats.json`
|
|
341
345
|
makes it **repo-owned**: it is listed like any other capability (with
|
|
@@ -418,6 +422,23 @@ So the framework's own souls say `oats.okf: { from: package }` even though
|
|
|
418
422
|
member soul that is the expert in that capability (`oats-okf-expert`,
|
|
419
423
|
`oats-aweb-expert`, …), discoverable at latest state like any member soul.
|
|
420
424
|
|
|
425
|
+
**OATS's coordination is a member copy of the engineering template.** The
|
|
426
|
+
`oats` repository keeps its own copy of
|
|
427
|
+
[oats-project/oats-engineering-coordination](https://github.com/oats-project/oats-engineering-coordination)
|
|
428
|
+
at template-v3.0.1, adapted to OATS: `oats.engineering-expert`,
|
|
429
|
+
`oats.developer`, `oats.build`, `oats.code-review`, `oats.maintainer`,
|
|
430
|
+
`oats.landing-rules` and `oats.dispatcher`, in `capabilities/oats-<name>/`.
|
|
431
|
+
`capabilities/TEMPLATE-RELEASE` records the release, its commit and what was copied, and
|
|
432
|
+
`capabilities/THIRD-PARTY-NOTICES.md` the sources four of the build skills and the
|
|
433
|
+
developer's quality floor adapt. `oats.build` holds the build skills, and every soul that
|
|
434
|
+
builds composes it: the developers, and the engineering experts that build their own
|
|
435
|
+
specs. The framework's own souls compose them `from: here`, never the `oats.engineering` package's copies; the
|
|
436
|
+
landing rules point at the lane map, which stays the one home of OATS's lanes.
|
|
437
|
+
The reviewer is the template's `code-reviewer` soul, in `souls/`. The workspace
|
|
438
|
+
doesn't pin the `oats.engineering` package, frozen at v1.18.0
|
|
439
|
+
([official catalog](official-catalog.md#coordination-templates)), so each of
|
|
440
|
+
those ids has one source here: the member copy.
|
|
441
|
+
|
|
421
442
|
## Packages, lock, catalog
|
|
422
443
|
|
|
423
444
|
`packages:` values have two forms, a **bare version** resolved through the
|
|
@@ -438,6 +459,7 @@ the workspace's slot default):
|
|
|
438
459
|
```
|
|
439
460
|
from: package → some locked package provides `name` else E_PACKAGE_MISSING (run `oats sync`)
|
|
440
461
|
→ read its manifests at the locked commit; the lock's capability list must match else E_PACKAGE_INTEGRITY
|
|
462
|
+
→ at spawn, the package tree at the locked commit must digest to the lock's integrity else E_PACKAGE_INTEGRITY
|
|
441
463
|
→ copy; record package/version/commit/digest
|
|
442
464
|
from: <repo> → <repo> is a CONFIRMED member else E_NOT_A_MEMBER / E_MEMBERSHIP_UNCONFIRMED
|
|
443
465
|
(or `here`) → it has capabilities/<name>/oats.json else E_CAPABILITY_MISSING
|
|
@@ -527,7 +549,9 @@ souls: # per soul pattern: its default team an
|
|
|
527
549
|
`<member>/*` or `<package>/*`, and `"*"`, with the member and package names
|
|
528
550
|
`souls.disabled` uses (a member's name is its repository's). A bare soul name
|
|
529
551
|
is refused. A key that is neither a pattern nor a soul the workspace offers
|
|
530
|
-
is the warning `team-soul-unknown` (a typo guard).
|
|
552
|
+
is the warning `team-soul-unknown` (a typo guard). So is a `<prefix>/*`
|
|
553
|
+
pattern whose prefix matches no soul the workspace offers: a typo, or a
|
|
554
|
+
member or package that was renamed or dropped. `"*"` never warns.
|
|
531
555
|
- **The most specific key wins outright** for a soul's teams, and lists never
|
|
532
556
|
merge: the soul's own key, then `<member|package>/*`, then `"*"`. The
|
|
533
557
|
default comes from the most specific key that sets one. So
|
|
@@ -820,8 +844,10 @@ PATH STATE VIA
|
|
|
820
844
|
```
|
|
821
845
|
|
|
822
846
|
**Concurrency.** Every change runs under `~/.oats/config/deployments.lock`
|
|
823
|
-
(waiting up to 3 s for
|
|
824
|
-
replaces the file atomically.
|
|
847
|
+
(waiting up to 3 s for a holder that is running) and re-reads the file inside
|
|
848
|
+
it, and each write replaces the file atomically. The lock is a file that names
|
|
849
|
+
the process holding it: one left by a command that was killed is taken over by
|
|
850
|
+
the next command. Readers take no lock: they read a regular file
|
|
825
851
|
only, without following a link, up to 1 MiB. A missing file is an empty list.
|
|
826
852
|
|
|
827
853
|
**Errors:**
|
|
@@ -830,7 +856,7 @@ only, without following a link, up to 1 MiB. A missing file is an empty list.
|
|
|
830
856
|
|---|---|
|
|
831
857
|
| `E_DEPLOYMENTS_INVALID` | the file is not JSON, not an object, a link, over 1 MiB, or a row breaks the schema: "`<file>` cannot be read as this computer's deployments list (`<reason>`). Fix it, or move it aside and run `oats deployments add <dir>` for each deployment; nothing was changed" |
|
|
832
858
|
| `E_DEPLOYMENTS_VERSION` | `schemaVersion` is newer than this oats reads: "`<file>` was written by a newer oats (schema `<n>`); upgrade oats". The file is never rewritten down |
|
|
833
|
-
| `E_DEPLOYMENTS_BUSY` | the lock is still held after 3 s: "this computer's deployments list is locked (`<why>`); if no oats process is changing it, remove `<lock>` and retry; nothing was changed" |
|
|
859
|
+
| `E_DEPLOYMENTS_BUSY` | the lock is still held by a running process after 3 s, or cannot be judged: "this computer's deployments list is locked (`<why>`); if no oats process is changing it, remove `<lock>` and retry; nothing was changed". `<why>` says what was found: `pid <n> holds it`; `the record at <lock> is unreadable` (remove that file); that it cannot be established whether pid `<n>` still runs (check that pid by hand, then remove the file); or `<lock> is a lock directory written by an earlier kernel` (remove the directory once no older oats is running) |
|
|
834
860
|
| `E_DEPLOYMENTS_WRITE` | the write failed, or would make the file larger than 1 MiB: "cannot write `<file>` (`<system error>`); nothing was changed" |
|
|
835
861
|
| `E_DEPLOYMENTS_IMPORT` | `~/Agents` cannot be read for the first-use import: "cannot read `<dir>` to import its deployments (`<system error>`); make it readable, or move it aside, and retry; nothing was changed" |
|
|
836
862
|
|
package/lib/claim.mjs
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
/** The claim: one file that says which process is doing a thing that must happen once at a time.
|
|
2
2
|
* One protocol, used by `oats worktree add|remove` (the purpose's claim, lib/worktree.mjs
|
|
3
3
|
* `withClaim`) and by `oats retire` and `oats instance stop` (the home's claim, lib/core.mjs
|
|
4
|
-
* `claimHomeFor`)
|
|
4
|
+
* `claimHomeFor`), and by the lock of the kernel's shared files and of the machine's resume sweep
|
|
5
|
+
* (lib/dir-lock.mjs `withDirLock`, `acquireDirLock`).
|
|
5
6
|
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
7
|
+
* A claim left by a process that died is taken over, so a killed command can always be run
|
|
8
|
+
* again: the owner is named by pid AND start time (processLiveness), never by a
|
|
8
9
|
* pid alone, and a holder whose start cannot be read is never taken for gone.
|
|
9
10
|
*
|
|
10
11
|
* - Taking it: the owner's facts `{ pid, processStart, nonce, at }`, with what the caller adds to
|
|
@@ -87,6 +88,13 @@
|
|
|
87
88
|
* caller's answer for a step that could not be ended
|
|
88
89
|
* (`at` is kept); `ended` is a clause naming what it
|
|
89
90
|
* ended, when it ended something
|
|
91
|
+
* holderGone(holder) optional: whether a fact of the caller's own in the record
|
|
92
|
+
* says that `holder` is gone, whatever its pid reads as (the
|
|
93
|
+
* resume sweep's lock: taken in another boot, which no process
|
|
94
|
+
* outlives, while a pid and a start counted from the boot can
|
|
95
|
+
* both come again in the next). Asked in place of reading the
|
|
96
|
+
* process, by acquireClaim and by claimUnheld; such a holder
|
|
97
|
+
* is taken over as any gone one
|
|
90
98
|
* waitMs how long a live holder is waited for (default CLAIM_WAIT_MS)
|
|
91
99
|
* warnings optional array a takeover's warnings are pushed to
|
|
92
100
|
* facts optional object, what the caller's claim says besides its
|
|
@@ -223,7 +231,7 @@ export function claimUnheld(path, opts, otherwise) {
|
|
|
223
231
|
try { holder = JSON.parse(text); } catch { holder = null; }
|
|
224
232
|
// readClaim's own reading of bytes that are no claim, `unreadable` in a record included.
|
|
225
233
|
if (!holder || typeof holder !== "object" || holder.unreadable) throw opts.unreadableClaim(path, []);
|
|
226
|
-
const live =
|
|
234
|
+
const live = holderLiveness(holder, opts);
|
|
227
235
|
if (live.state !== "gone") throw opts.busy(holder, live.state === "unknown" ? live.reason : null, path, []);
|
|
228
236
|
const stuck = cannotBeTakenOver(holder, 0);
|
|
229
237
|
if (stuck) throw opts.cannotTakeOver(holder, path, stuck, []);
|
|
@@ -231,6 +239,14 @@ export function claimUnheld(path, opts, otherwise) {
|
|
|
231
239
|
}
|
|
232
240
|
}
|
|
233
241
|
|
|
242
|
+
/** Whether the holder a claim record names can still act, as processLiveness answers it, for the
|
|
243
|
+
* caller whose refusals are `opts`: gone when its `holderGone` says so, whatever the process reads
|
|
244
|
+
* as. The one reading of a holder for taking a claim (takeClaim) and for reading one (claimUnheld),
|
|
245
|
+
* and of a cache write lock's holder that names its boot and start (lib/remote.mjs isStaleLock). */
|
|
246
|
+
export function holderLiveness(holder, opts) {
|
|
247
|
+
return opts.holderGone?.(holder) ? { state: "gone" } : processLiveness(holder);
|
|
248
|
+
}
|
|
249
|
+
|
|
234
250
|
/** Take the claim `path` → this holding (`{ pid, processStart, nonce, at }`, with `opts.facts`), to
|
|
235
251
|
* pass to releaseClaim. Throws the caller's refusal when it cannot be taken, and claimUnavailable for
|
|
236
252
|
* any error that is not the kernel's. The directory exists. */
|
|
@@ -258,7 +274,7 @@ function takeClaim(path, opts, depth, endedSteps) {
|
|
|
258
274
|
catch (e) { if (e?.code !== "EEXIST") throw e; }
|
|
259
275
|
const holder = readClaim(path);
|
|
260
276
|
if (holder?.unreadable) throw opts.unreadableClaim(path, endedSteps);
|
|
261
|
-
const live = holder ?
|
|
277
|
+
const live = holder ? holderLiveness(holder, opts) : null;
|
|
262
278
|
// Unreadable is never taken for gone: the claim is kept, and the refusal names the way out.
|
|
263
279
|
if (live?.state === "unknown") throw busy(holder, live.reason, path, endedSteps);
|
|
264
280
|
const gone = live?.state === "gone";
|
|
@@ -0,0 +1,238 @@
|
|
|
1
|
+
/** lib/command-flags.mjs — the flags each state-changing kernel command defines (oats-project/oats#1791),
|
|
2
|
+
* and the one check of a command's argv against them, which the CLI's dispatch runs before the command
|
|
3
|
+
* runs and before a `--server` command is sent to its host: a flag the command does not define, a value
|
|
4
|
+
* on one of its switches, or an argument after its last one is refused with E_BAD_ARGS, never ignored, so
|
|
5
|
+
* a mistyped protective flag (`--keep-dirs` for `--keep-dir`) never does the unprotected thing. A command
|
|
6
|
+
* missing here is not checked. Kernel-private, not exported from `./core`. Dependency-free. */
|
|
7
|
+
|
|
8
|
+
export const RETIRE_DELETE_BRANCH_REFUSED = "oats retire no longer deletes branches: --delete-branch is not accepted. Retire without it; the branch is left in the repository. Inspect it there and delete it with Git if it is no longer wanted.";
|
|
9
|
+
export const RETIRE_USAGE = "usage: oats retire <instance> [--plan] [--plan-revision <rev> --idempotency-key <key>] [--home <path>] [--dir <d>] [--server <id>] [--self] [--discard-worktree] [--keep-dir] [--force] [--json]";
|
|
10
|
+
export const SPAWN_USAGE = "usage: oats spawn <agent> [--task <text>|--task-file <f>] [--purpose <slug>|--name <slug>|--suggest-name] [--preview] [--base <ref>] [--model <id>|@native-default] [--allow-child-spawns|--no-child-spawns] [--relation child|sibling|parent|unrelated --relative-to <instance> [--relative-root <agents-root>]] [--parent <instance>] [--same-work] [--repo <r>] [--work worktree|checkout|attached|workspace|directory] [--work-dir <owner-work>] [--harness pi|claude|codex] [--backend tmux] [--yolo|--no-yolo] [--background|--no-background] [--model <m>] [--branch <b>] [--no-launch] [--json]";
|
|
11
|
+
export const SYNC_USAGE = "usage: oats sync [--dir <deployment>] [--plan] [--json]";
|
|
12
|
+
export const APPROVAL_REMOVED = "package approval was removed; declaring a package in packages: is the trust decision";
|
|
13
|
+
export const TEAMS_USAGE = "usage: oats teams [--json] | oats teams add <label> --team <id> [--description <d>] [--no-default] | oats teams remove <label> | oats teams default <label> [--if-absent | --expect <label>] [--dir <deployment>] [--json]";
|
|
14
|
+
export const SOUL_LAUNCH_USAGE = "oats soul launch set <soul>|'*' (--launch-config <name>|none | --harness pi|claude|codex [--model <id>]) [--plan] [--dir <deployment>] [--json] | oats soul launch remove <soul>|'*'|<exact key> [--plan] [--dir <deployment>] [--json]";
|
|
15
|
+
export const WORKTREE_USAGE = "usage: oats worktree add --purpose <p> --branch <b> --base <remote-branch> [--repo <member key|clone path>] [--preview] [--json] | oats worktree remove --purpose <p> [--json]";
|
|
16
|
+
|
|
17
|
+
const WORKTREE_REFUSED = Object.freeze({
|
|
18
|
+
"--server": "oats worktree runs in an instance home on this machine; --server is not accepted",
|
|
19
|
+
"--dir": `oats worktree has no --dir: it acts on the instance home it runs in; ${WORKTREE_USAGE}`,
|
|
20
|
+
"--home": `oats worktree has no --home: it acts on the instance home it runs in; ${WORKTREE_USAGE}`,
|
|
21
|
+
});
|
|
22
|
+
const launchConfigWrite = (sub) => {
|
|
23
|
+
const refused = `launch-config ${sub} writes the deployment's oats-local.yaml: address it with --dir, not --home or --soul`;
|
|
24
|
+
return { "--home": refused, "--soul": refused };
|
|
25
|
+
};
|
|
26
|
+
const SESSION_VALUES = Object.freeze(["--home", "--instance", "--launch-config", "--harness", "--runtime", "--model", "--server"]);
|
|
27
|
+
const SESSION_SWITCHES = Object.freeze(["--reselect-launch", "--yolo", "--no-yolo", "--json"]);
|
|
28
|
+
const SCHEDULE_VALUES = Object.freeze(["--dir", "--server"]);
|
|
29
|
+
const schedule = (verb, switches = []) => ({ command: `schedule ${verb}`, operands: ["id"], values: SCHEDULE_VALUES, switches: [...switches, "--json"],
|
|
30
|
+
usage: `usage: oats schedule ${verb} <id>${switches.map((s) => ` [${s}]`).join("")} [--dir <workspace> | --server <id>] [--json]` });
|
|
31
|
+
const trigger = (verb) => ({ command: `trigger ${verb}`, operands: ["id"], values: ["--dir"], switches: ["--json"], usage: `usage: oats trigger ${verb} <id> [--dir <deployment>] [--json]` });
|
|
32
|
+
const INSTANCE_RECORD_VALUES = Object.freeze(["--home", "--dir", "--server"]);
|
|
33
|
+
const onOff = (verb) => ({ command: `instance ${verb}`, operands: ["instance", "state"], values: INSTANCE_RECORD_VALUES, switches: ["--json"],
|
|
34
|
+
usage: `usage: oats instance ${verb} <instance> on|off [--home <abs>] [--dir <d> | --server <id>] [--json]` });
|
|
35
|
+
const WAITING_VALUES = Object.freeze(["--producer", "--reason", "--message", "--home", "--dir"]);
|
|
36
|
+
const waiting = (verb) => ({ command: `instance waiting ${verb}`, operands: [], values: WAITING_VALUES, switches: ["--json"],
|
|
37
|
+
usage: `usage: oats instance waiting ${verb} --producer <id>${verb === "set" ? " --reason permission|question|attention" : ""} [--message=<text>] [--home <abs>] [--dir <d>] [--json]` });
|
|
38
|
+
const ATTENTION_USAGE = "usage: oats instance attention [--message=<text>] [--clear] [--json]";
|
|
39
|
+
const attentionHasNo = (flag) => `oats instance attention has no ${flag}: it records the agent's own claim on the instance it runs in ($OATS_INSTANCE_HOME); ${ATTENTION_USAGE}`;
|
|
40
|
+
const TRIGGER_RUN_SOURCE = Object.freeze(["--run-source", "--json"]);
|
|
41
|
+
const SESSION_ADDRESS = Object.freeze(["--home", "--instance", "--server"]);
|
|
42
|
+
/** Every `oats session` form refuses the captured path's selector in these words (bin's sessionCmd says them
|
|
43
|
+
* for the forms not declared here). */
|
|
44
|
+
export const NATIVE_RECORD_REFUSED = "--native-record outcome inspection is gone (the captured/portable path was removed in 0.26)";
|
|
45
|
+
const NATIVE_RECORD_GONE = Object.freeze({ "--native-record": NATIVE_RECORD_REFUSED });
|
|
46
|
+
/** A resume is this machine's (#1559, D1): a server resumes its own instances. */
|
|
47
|
+
export const RESUME_LOCAL_ONLY = "session resume and session start --resume act on this machine's instances only; a server runs oats session resume itself";
|
|
48
|
+
const UPDATE_TAKES_NO_PACKAGE = "oats update takes no package: pin package versions in oats-workspace.yaml (`oats package add <id> <version>`), then `oats sync`; bare `oats update [--check] [--yes]` updates the kernel";
|
|
49
|
+
const SPAWN_REMOVED_SOUL = (flag) => `${flag} created a local soul under local-agents/, which the workspace model removed — author souls/<name>/soul.yaml + AGENTS.md in a member repository, then \`oats sync\``;
|
|
50
|
+
/** `oats teams` and `oats soul launch` answer a flag they do not take with E_USAGE in their own words
|
|
51
|
+
* (docs/desktop-cli-api.md "oats teams", "oats soul launch"). */
|
|
52
|
+
const teamsUnknown = (form) => (flag) => ({ code: "E_USAGE", message: `${form} does not take ${flag} (an option this kernel does not know may need a newer kernel; nothing was changed) — ${TEAMS_USAGE}`, details: { flag } });
|
|
53
|
+
/** An `oats teams` form takes these, beyond `--dir` and `--json`; anything else is refused, never ignored:
|
|
54
|
+
* a kernel that ignored `--if-absent` would set unconditionally. */
|
|
55
|
+
const teams = (verb, values, switches) => ({ command: `teams ${verb}`, operands: ["label"], values: ["--dir", ...values], switches: [...switches, "--json"], unknown: teamsUnknown(`oats teams ${verb}`),
|
|
56
|
+
usage: `usage: oats teams ${verb} <label>${[...values.map((v) => ` [${v} <${v.slice(2)}>]`), ...switches.map((s) => ` [${s}]`)].join("")} [--dir <deployment>] [--json]` });
|
|
57
|
+
/** An `oats soul launch` form takes these; anything else is refused, never ignored: `--home` and `--soul`
|
|
58
|
+
* among them, since the soul is the argument and the file the deployment's. */
|
|
59
|
+
const soulLaunch = (verb, values) => ({ command: `soul launch ${verb}`, operands: [verb === "set" ? "soul" : "soul or key"], values: ["--dir", ...values], switches: ["--plan", "--json"],
|
|
60
|
+
unknown: (flag) => ({ code: "E_USAGE", message: `oats soul launch ${verb} does not take ${flag} (nothing was changed) — usage: ${SOUL_LAUNCH_USAGE}`, details: { flag } }),
|
|
61
|
+
// Every name it was given, in its own words: `remove dev writer` would remove dev alone.
|
|
62
|
+
extra: (args) => ({ code: "E_BAD_ARGS", message: `oats soul launch ${verb} takes one ${verb === "set" ? "soul" : "soul or key"}, and got ${args.length}: ${args.map((n) => JSON.stringify(n)).join(", ")} (nothing was changed) — usage: ${SOUL_LAUNCH_USAGE}` }),
|
|
63
|
+
usage: verb === "set" ? "usage: oats soul launch set <soul>|'*' (--launch-config <name>|none | --harness pi|claude|codex [--model <id>]) [--plan] [--dir <deployment>] [--json]" : "usage: oats soul launch remove <soul>|'*'|<exact key> [--plan] [--dir <deployment>] [--json]" });
|
|
64
|
+
|
|
65
|
+
/** Each command's argv, frozen to its arrays: `command` its words; `operands` the names of the arguments
|
|
66
|
+
* it takes after them, in order (one more is refused); `required` how many of them it needs (all, unless
|
|
67
|
+
* it says: a missing one is the command's own refusal, and E_USAGE here when `--server` is given);
|
|
68
|
+
* `values` the flags that take a value, `arity` those that take more than one word (`{ flag: words }`);
|
|
69
|
+
* `switches` the flags that take none; `refused` the flags it refuses with their own message; `usage`
|
|
70
|
+
* the line every shared refusal ends with. A row answers in its own words with `unknown(flag)` for a flag
|
|
71
|
+
* it does not define and `extra(args)` for an argument after its last (`args`: every argument it was
|
|
72
|
+
* given), each → { code, message, details? }. `--json` is a switch of every one. A value flag given no
|
|
73
|
+
* value is that flag's own refusal, by the command. */
|
|
74
|
+
export const COMMAND_FLAGS = Object.freeze([
|
|
75
|
+
{ command: "retire", operands: ["instance"], values: ["--plan-revision", "--idempotency-key", "--home", "--dir", "--server"], switches: ["--plan", "--self", "--discard-worktree", "--keep-dir", "--force", "--json"],
|
|
76
|
+
refused: { "--delete-branch": RETIRE_DELETE_BRANCH_REFUSED }, usage: RETIRE_USAGE },
|
|
77
|
+
// `--instance` is refused by a local spawn (with its replacement) but still travels to an older host
|
|
78
|
+
// through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an apply bound
|
|
79
|
+
// by --expect-decision: the dispatch allow-list (maxAgeRefusal) refuses it otherwise. `--herdr-socket`
|
|
80
|
+
// and `--backend herdr` are read to be refused (E_HERDR_REMOVED), here and on the route.
|
|
81
|
+
{ command: "spawn", operands: ["soul"],
|
|
82
|
+
values: ["--agents-root", "--backend", "--base", "--branch", "--dir", "--expect-decision", "--harness", "--herdr-socket", "--idempotency-key", "--instance", "--launch-config", "--max-age", "--model", "--name", "--parent", "--provider", "--purpose", "--relation", "--relative-root", "--relative-to", "--repo", "--runtime", "--server", "--task", "--task-file", "--trigger-event", "--wake-cron", "--wake-every", "--wake-file", "--wake-json", "--wake-message", "--wake-message-file", "--wake-tz", "--work", "--work-dir"],
|
|
83
|
+
arity: { "--provider": 2 },
|
|
84
|
+
switches: ["--allow-child-spawns", "--background", "--json", "--no-background", "--no-child-spawns", "--no-launch", "--no-yolo", "--preview", "--same-work", "--suggest-name", "--yolo"],
|
|
85
|
+
// Local souls (local-agents/) are gone with the workspace model: a soul is a member
|
|
86
|
+
// repository's souls/<name>, so spawn never writes one.
|
|
87
|
+
refused: { "--instructions-file": SPAWN_REMOVED_SOUL("--instructions-file"), "--def-file": SPAWN_REMOVED_SOUL("--def-file"),
|
|
88
|
+
"--ephemeral": "--ephemeral was removed by the runtime-boundary ruling — declare the agent in a capability manifest (agents:) for automatic ephemeral semantics" },
|
|
89
|
+
unknown: (flag) => ({ code: "E_BAD_ARGS", message: `oats spawn: unknown flag ${flag}` }),
|
|
90
|
+
extra: ([soul, a]) => ({ code: "E_BAD_ARGS", message: /^[A-Za-z0-9_.-]+=/.test(a)
|
|
91
|
+
? `oats spawn: unexpected argument ${JSON.stringify(a)} after the soul ${JSON.stringify(soul)}: a capability setting is given as --provider <capability> key=value (here: --provider <capability> ${a})`
|
|
92
|
+
: `oats spawn: unexpected argument ${JSON.stringify(a)} after the soul ${JSON.stringify(soul)}: spawn takes one soul` }),
|
|
93
|
+
usage: SPAWN_USAGE },
|
|
94
|
+
// An unknown flag or an argument of sync is refused before anything is read or written (#731).
|
|
95
|
+
{ command: "sync", operands: [], values: ["--dir"], switches: ["--plan", "--json"], refused: { "--approve": `--approve: ${APPROVAL_REMOVED}` }, usage: SYNC_USAGE },
|
|
96
|
+
{ command: "instance stop", operands: ["instance"], values: ["--plan-revision", "--idempotency-key", "--grace-ms", "--home", "--dir", "--server"], switches: ["--plan", "--apply", "--no-recursive", "--json"],
|
|
97
|
+
usage: "usage: oats instance stop <instance> (--plan | --apply --plan-revision <rev> --idempotency-key <key>) [--no-recursive] [--grace-ms <n>] [--home <abs>] [--dir <d> | --server <id>] [--json]" },
|
|
98
|
+
{ command: "instance upgrade", operands: ["instance"], values: ["--plan-revision", "--idempotency-key", "--home", "--dir"], switches: ["--undo", "--plan", "--json"],
|
|
99
|
+
refused: { "--server": "instance upgrade supports local homes only; run it on the deployment host" },
|
|
100
|
+
usage: "usage: oats instance upgrade <instance> [--undo] (--plan | --plan-revision <rev> --idempotency-key <key>) [--home <abs>] [--dir <d>] [--json]" },
|
|
101
|
+
{ command: "instance color", operands: ["instance", "color"], required: 1, values: INSTANCE_RECORD_VALUES, switches: ["--clear", "--json"],
|
|
102
|
+
usage: "usage: oats instance color <instance> (<color> | --clear) [--home <abs>] [--dir <d> | --server <id>] [--json]" },
|
|
103
|
+
onOff("background"),
|
|
104
|
+
onOff("same-work"),
|
|
105
|
+
waiting("set"),
|
|
106
|
+
waiting("clear"),
|
|
107
|
+
{ command: "instance attention", operands: [], values: ["--message"], switches: ["--clear", "--json"],
|
|
108
|
+
refused: Object.fromEntries(["--home", "--dir", "--producer", "--reason"].map((f) => [f, attentionHasNo(f)])), usage: ATTENTION_USAGE },
|
|
109
|
+
{ command: "instance suggest-name", operands: [], values: ["--soul", "--task", "--task-file", "--harness", "--model", "--launch-config", "--dir"], switches: ["--json"],
|
|
110
|
+
refused: { "--server": "instance suggest-name takes no --server: it runs this machine's harness, for a spawn that may land on another; the host it lands on makes the name unique (or names an unnamed --suggest-name spawn itself)" },
|
|
111
|
+
usage: "usage: oats instance suggest-name --soul <soul> (--task <t> | --task-file <f>) [--harness claude|pi] [--model <m>] [--launch-config <n>] [--dir <d>] [--json]" },
|
|
112
|
+
{ command: "worktree add", operands: [], values: ["--purpose", "--branch", "--base", "--repo"], switches: ["--preview", "--json"], refused: WORKTREE_REFUSED,
|
|
113
|
+
usage: "usage: oats worktree add --purpose <p> --branch <b> --base <remote-branch> [--repo <member key|clone path>] [--preview] [--json]" },
|
|
114
|
+
{ command: "worktree remove", operands: [], values: ["--purpose"], switches: ["--json"], refused: WORKTREE_REFUSED,
|
|
115
|
+
usage: "usage: oats worktree remove --purpose <p> [--json]" },
|
|
116
|
+
{ command: "session start", operands: [], refused: NATIVE_RECORD_GONE, values: SESSION_VALUES, switches: [...SESSION_SWITCHES, "--resume"],
|
|
117
|
+
usage: "usage: oats session start (--home <abs> | --server <id> (--instance <name> | --home <abs>)) [--launch-config <name>|none | --reselect-launch] [--harness pi|claude|codex] [--model <id>] [--yolo|--no-yolo] [--resume] [--json]" },
|
|
118
|
+
{ command: "session restart", operands: [], values: [...SESSION_VALUES, "--stop-grace"], switches: SESSION_SWITCHES,
|
|
119
|
+
refused: { ...NATIVE_RECORD_GONE, "--resume": "--resume exists on session start only: it brings back a session that was lost" },
|
|
120
|
+
usage: "usage: oats session restart (--home <abs> | --server <id> (--instance <name> | --home <abs>)) [--launch-config <name>|none | --reselect-launch] [--harness pi|claude|codex] [--model <id>] [--yolo|--no-yolo] [--stop-grace <seconds>] [--json]" },
|
|
121
|
+
{ command: "session resume", operands: [], values: ["--deployment"],
|
|
122
|
+
refused: { ...NATIVE_RECORD_GONE, "--server": RESUME_LOCAL_ONLY }, switches: ["--plan", "--json"], usage: "usage: oats session resume [--deployment <dir>] [--plan] [--json]" },
|
|
123
|
+
{ command: "session input", operands: [], refused: NATIVE_RECORD_GONE, values: ["--home", "--text-file"], switches: ["--json"], usage: "usage: oats session input --home <abs> [--text-file <path>] [--json]" },
|
|
124
|
+
{ command: "session receive", operands: [], refused: NATIVE_RECORD_GONE, values: ["--home", "--name"], switches: ["--json"], usage: "usage: oats session receive --home <abs> --name <file name> [--json]" },
|
|
125
|
+
{ command: "session upload", operands: [], refused: NATIVE_RECORD_GONE, values: ["--file", ...SESSION_ADDRESS], switches: ["--json"],
|
|
126
|
+
usage: "usage: oats session upload --file <path> (--home <abs> | --server <id> (--instance <name> | --home <abs>)) [--json]" },
|
|
127
|
+
{ command: "session attach", operands: [], refused: NATIVE_RECORD_GONE, values: ["--detach-key", ...SESSION_ADDRESS], switches: ["--no-status-line", "--print", "--json"],
|
|
128
|
+
usage: "usage: oats session attach (--home <abs> | --server <id> (--instance <name> | --home <abs>) [--print]) [--detach-key <key>] [--no-status-line]" },
|
|
129
|
+
{ command: "schedule add", operands: ["id"], required: 0, values: ["--file", "--spec-json", "--description", "--workspace", "--runs-on", "--owner", ...SCHEDULE_VALUES], switches: ["--json"],
|
|
130
|
+
usage: "usage: oats schedule add [<id>] (--file <spec.json> | --spec-json <json>) [--description=<text>] [--workspace <member> --runs-on <host> --owner <host>/<login>] [--dir <workspace> | --server <id>] [--json]" },
|
|
131
|
+
{ command: "schedule update", operands: ["id"], values: ["--file", "--spec-json", "--description", ...SCHEDULE_VALUES], switches: ["--json"],
|
|
132
|
+
usage: "usage: oats schedule update <id> (--file <spec.json> | --spec-json <json> [--description=<text>] | --description=<text>) [--dir <workspace> | --server <id>] [--json]" },
|
|
133
|
+
schedule("remove", ["--force"]),
|
|
134
|
+
schedule("run", ["--force"]),
|
|
135
|
+
schedule("enable"),
|
|
136
|
+
schedule("disable"),
|
|
137
|
+
schedule("reconcile", ["--clear"]),
|
|
138
|
+
{ command: "schedule tick", operands: [], values: SCHEDULE_VALUES, switches: ["--dry-run", "--host", "--json"], usage: "usage: oats schedule tick [--dry-run] [--host] [--dir <workspace> | --server <id>] [--json]" },
|
|
139
|
+
{ command: "schedule host install", operands: [], values: ["--max-concurrent", "--triggers-max-concurrent", "--os", ...SCHEDULE_VALUES], switches: ["--print", "--json"],
|
|
140
|
+
usage: "usage: oats schedule host install [--max-concurrent <N|default>] [--triggers-max-concurrent <N|none>] | --print [--os darwin|linux] [--dir <workspace> | --server <id>] [--json]" },
|
|
141
|
+
{ command: "schedule host uninstall", operands: [], values: SCHEDULE_VALUES, switches: ["--json"], usage: "usage: oats schedule host uninstall [--dir <workspace> | --server <id>] [--json]" },
|
|
142
|
+
{ command: "trigger add", operands: [], values: ["--file", "--from", "--set", "--id", "--description", "--workspace", "--runs-on", "--owner", "--dir"], switches: ["--json"],
|
|
143
|
+
usage: "usage: oats trigger add (--file <trigger.json> | --from <package>:<template> [--set <name>=<value>]… [--id <id>]) [--description=<text>] [--workspace <member> --runs-on <host> --owner <host>/<login>] [--dir <deployment>] [--json]" },
|
|
144
|
+
{ command: "trigger poll", operands: ["id"], values: ["--dir", "--max-age"], switches: TRIGGER_RUN_SOURCE, usage: "usage: oats trigger poll <id> --run-source [--max-age <s>] [--dir <deployment>] [--json]" },
|
|
145
|
+
{ command: "trigger test", operands: ["id"], values: ["--dir"], switches: TRIGGER_RUN_SOURCE, usage: "usage: oats trigger test <id> [--run-source] [--dir <deployment>] [--json]" },
|
|
146
|
+
trigger("remove"),
|
|
147
|
+
trigger("enable"),
|
|
148
|
+
trigger("disable"),
|
|
149
|
+
{ command: "teams", operands: [], values: ["--dir", "--max-age"], switches: ["--json"], unknown: teamsUnknown("oats teams"),
|
|
150
|
+
// A word where a form belongs: the forms' usage, as before.
|
|
151
|
+
extra: () => ({ code: "E_USAGE", message: TEAMS_USAGE }), usage: "usage: oats teams [--max-age <s>] [--dir <deployment>] [--json]" },
|
|
152
|
+
teams("add", ["--team", "--description"], ["--no-default"]),
|
|
153
|
+
teams("remove", [], []),
|
|
154
|
+
teams("default", ["--expect"], ["--if-absent"]),
|
|
155
|
+
soulLaunch("set", ["--launch-config", "--harness", "--model"]),
|
|
156
|
+
soulLaunch("remove", []),
|
|
157
|
+
{ command: "server check", operands: ["id"], values: [], switches: ["--json"], usage: "usage: oats server check <id> [--json]" },
|
|
158
|
+
{ command: "server remove", operands: ["id"], values: [], switches: ["--json"], usage: "usage: oats server remove <id> [--json]" },
|
|
159
|
+
{ command: "server forget", operands: ["id"], values: ["--instance"], switches: ["--json"], usage: "usage: oats server forget <id> --instance <name> [--json]" },
|
|
160
|
+
{ command: "package add", operands: ["id", "version"], values: ["--dir"], switches: ["--json"], usage: "usage: oats package add <id> <version|git:<repo>@<ref>> [--dir <d>] [--json]" },
|
|
161
|
+
{ command: "package remove", operands: ["id"], values: ["--dir"], switches: ["--json"], usage: "usage: oats package remove <id> [--dir <d>] [--json]" },
|
|
162
|
+
{ command: "launch-config set", operands: ["name"], values: ["--file", "--dir", "--server"], switches: ["--keep-env", "--json"], refused: launchConfigWrite("set"),
|
|
163
|
+
usage: "usage: oats launch-config set <name> --file <json> [--keep-env] [--dir <scope> | --server <id>] [--json]" },
|
|
164
|
+
{ command: "launch-config remove", operands: ["name"], values: ["--dir", "--server"], switches: ["--json"], refused: launchConfigWrite("remove"),
|
|
165
|
+
usage: "usage: oats launch-config remove <name> [--dir <scope> | --server <id>] [--json]" },
|
|
166
|
+
{ command: "automations refresh", operands: [], values: ["--dir"], switches: ["--json"], usage: "usage: oats automations refresh [--dir <deployment>] [--json]" },
|
|
167
|
+
// `oats update <package>` left with the installed tier (packages are pinned in the workspace file:
|
|
168
|
+
// `oats package add`); only the kernel self-update remains, and a package word is answered with that.
|
|
169
|
+
{ command: "update", operands: [], values: ["--dir"], switches: ["--check", "--yes", "--json"], refused: { "--to": UPDATE_TAKES_NO_PACKAGE },
|
|
170
|
+
extra: ([a]) => ({ code: "E_BAD_ARGS", message: UPDATE_TAKES_NO_PACKAGE, details: { argument: a } }), usage: "usage: oats update [--check] [--yes] [--dir <deployment>]" },
|
|
171
|
+
].map((c) => Object.freeze({ ...c, operands: Object.freeze([...c.operands]), required: c.required ?? c.operands.length, values: Object.freeze([...c.values]), switches: Object.freeze([...c.switches]),
|
|
172
|
+
arity: Object.freeze({ ...c.arity }), ...(c.refused ? { refused: Object.freeze({ ...c.refused }) } : {}) })));
|
|
173
|
+
|
|
174
|
+
/** The declaration of the command `argv` (the CLI's argv, after `oats`) runs: the one whose words its
|
|
175
|
+
* first words are, the longest of them; undefined for a command not declared here. */
|
|
176
|
+
export function commandFlags(argv) {
|
|
177
|
+
let found;
|
|
178
|
+
for (const c of COMMAND_FLAGS) {
|
|
179
|
+
const words = c.command.split(" ");
|
|
180
|
+
if (words.every((w, i) => argv[i] === w) && (!found || words.length > found.command.split(" ").length)) found = c;
|
|
181
|
+
}
|
|
182
|
+
return found;
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/** Why `argv` (the CLI's argv, after `oats`, as typed: `--flag=value` unexpanded) is not a command its
|
|
186
|
+
* declaration allows, as { code, message, details? }, or undefined (allowed, or not declared). The first
|
|
187
|
+
* problem from the left, E_BAD_ARGS unless the row answers in its own words: a refused flag (its own
|
|
188
|
+
* message), a flag the command does not define (`oats <command>: unknown flag <flag>`, or the row's
|
|
189
|
+
* `unknown`), a switch given a value with `=`, or an argument after its last (or the row's `extra`, given
|
|
190
|
+
* every argument); each shared one ends with the command's usage. A value flag with no value (none, or a word that starts with `--`) ends the
|
|
191
|
+
* check there with undefined: the command refuses it in its own words. Then, for a command given `--server`,
|
|
192
|
+
* a missing argument it requires: E_USAGE with the usage line, so that it is never sent (on this machine
|
|
193
|
+
* each command answers a missing argument itself). A value flag takes the next word (its `arity` words)
|
|
194
|
+
* as its value unless it starts with `--`, as the CLI's flag reader does (lib/argv.mjs flagValue); a value
|
|
195
|
+
* after `=` is its first. `--` is a flag like any other. */
|
|
196
|
+
export function commandArgvProblem(argv) {
|
|
197
|
+
const c = commandFlags(argv);
|
|
198
|
+
if (!c) return undefined;
|
|
199
|
+
const given = [];
|
|
200
|
+
let extra = null, routed = false;
|
|
201
|
+
for (let i = c.command.split(" ").length; i < argv.length; i++) {
|
|
202
|
+
const a = argv[i];
|
|
203
|
+
if (!a.startsWith("-")) {
|
|
204
|
+
if (given.length === c.operands.length && extra === null) extra = a;
|
|
205
|
+
given.push(a);
|
|
206
|
+
continue;
|
|
207
|
+
}
|
|
208
|
+
const eq = a.startsWith("--") ? a.indexOf("=") : -1;
|
|
209
|
+
const flag = eq > 2 ? a.slice(0, eq) : a;
|
|
210
|
+
// After an argument too many, the rest is read only for the arguments it holds.
|
|
211
|
+
if (extra === null) {
|
|
212
|
+
if (c.refused && Object.hasOwn(c.refused, flag)) return { code: "E_BAD_ARGS", message: c.refused[flag], details: { flag } };
|
|
213
|
+
if (c.switches.includes(flag)) {
|
|
214
|
+
if (flag !== a) return { code: "E_BAD_ARGS", message: `oats ${c.command}: ${flag} takes no value (got ${a})\n${c.usage}`, details: { flag } };
|
|
215
|
+
continue;
|
|
216
|
+
}
|
|
217
|
+
if (!c.values.includes(flag)) return c.unknown ? c.unknown(flag) : { code: "E_BAD_ARGS", message: `oats ${c.command}: unknown flag ${flag}\n${c.usage}`, details: { flag } };
|
|
218
|
+
if (flag === "--server") routed = true;
|
|
219
|
+
} else if (!c.values.includes(flag)) continue;
|
|
220
|
+
for (let words = (c.arity[flag] ?? 1) - (flag === a ? 0 : 1); words > 0; words--) {
|
|
221
|
+
// A value missing is a problem at this flag, the command's own: the check ends here, and the
|
|
222
|
+
// command answers it ("--dir needs a value"), never a flag further on.
|
|
223
|
+
// Its limit: a command that reads such a flag as absent on some path (instance stop --plan and
|
|
224
|
+
// --grace-ms) lets a later unknown flag pass on that path unrefused.
|
|
225
|
+
if (argv[i + 1] === undefined || argv[i + 1].startsWith("--")) { if (extra === null) return undefined; break; }
|
|
226
|
+
i++;
|
|
227
|
+
}
|
|
228
|
+
}
|
|
229
|
+
if (extra !== null) return c.extra ? c.extra(given) : { code: "E_BAD_ARGS", message: extraArgument(c, extra, given), details: { argument: extra } };
|
|
230
|
+
if (routed && given.length < c.required) return { code: "E_USAGE", message: c.usage };
|
|
231
|
+
return undefined;
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
function extraArgument(c, a, given) {
|
|
235
|
+
if (!c.operands.length) return `oats ${c.command}: unexpected argument ${JSON.stringify(a)}: ${c.command} takes no argument\n${c.usage}`;
|
|
236
|
+
const last = c.operands.length - 1;
|
|
237
|
+
return `oats ${c.command}: unexpected argument ${JSON.stringify(a)} after the ${c.operands[last]} ${JSON.stringify(given[last])}: ${c.command} takes ${c.operands.map((n) => `one ${n}`).join(" and ")}\n${c.usage}`;
|
|
238
|
+
}
|