@awebai/oats 0.48.0 → 0.50.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +326 -28
- package/docs/capabilities.md +425 -8
- package/docs/capability-manifest.schema.json +60 -5
- package/docs/configuration.md +103 -0
- package/docs/desktop-cli-api.md +542 -47
- package/docs/desktop.md +85 -5
- package/docs/execution-targets.md +50 -9
- package/docs/implementation.md +74 -1
- package/docs/integrations.md +7 -5
- package/docs/knowledge.md +167 -197
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +28 -14
- package/docs/release-lane.md +41 -0
- package/docs/release-notes/v0.49.0.md +770 -0
- package/docs/release-notes/v0.50.0.md +279 -0
- package/docs/schedules.md +289 -53
- package/docs/servers.md +7 -0
- package/docs/souls-and-instances.md +450 -60
- package/docs/workspaces.md +3 -3
- package/injects/work-checkout.md +17 -11
- package/injects/work-worktree.md +19 -13
- package/lib/capability-contract.mjs +100 -11
- package/lib/capability-show.mjs +18 -2
- package/lib/core.mjs +1374 -394
- package/lib/instance-events.mjs +9 -10
- package/lib/instance-git.mjs +19 -10
- package/lib/instance-inspect.mjs +58 -18
- package/lib/instance-lifecycle.mjs +106 -16
- package/lib/instance-resolution.mjs +15 -3
- package/lib/launch-prompt-policy.mjs +17 -3
- package/lib/packages.mjs +1 -0
- package/lib/real-path.mjs +27 -0
- package/lib/refused-text.mjs +17 -0
- package/lib/resolve.mjs +4 -4
- package/lib/retained-after-retire.mjs +387 -0
- package/lib/retire-output.mjs +6 -1
- package/lib/schedule.mjs +9 -2
- package/lib/servers.mjs +32 -6
- package/lib/tree-copy.mjs +18 -7
- package/lib/trigger-sources.mjs +234 -0
- package/lib/triggers.mjs +705 -108
- package/lib/workspace.mjs +20 -5
- package/lib/worktree-hooks.mjs +392 -0
- package/lib/worktree.mjs +655 -0
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +1 -1
package/docs/desktop-cli-api.md
CHANGED
|
@@ -22,7 +22,9 @@ kernel emits it.
|
|
|
22
22
|
Conventions: paths are absolute; a `commit` is a full 40-hex id; `integrity`
|
|
23
23
|
and `digest` are `sha256-<hex>`; times are ISO-8601 UTC; repository keys are
|
|
24
24
|
canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
|
|
25
|
-
`/w` as the deployment and shorten ids and digests with `…`.
|
|
25
|
+
`/w` as the deployment and shorten ids and digests with `…`. Package versions
|
|
26
|
+
in example payloads are illustrative snapshots, not deployment pin advice;
|
|
27
|
+
see the [official catalog](official-catalog.md) for current pins.
|
|
26
28
|
|
|
27
29
|
## The probe
|
|
28
30
|
|
|
@@ -40,7 +42,8 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
|
|
|
40
42
|
"team-model-3","settings-declared","capabilities-private","layers-from","harness","package-souls","triggers","automations","desktop-facts","launch-preference",
|
|
41
43
|
"preview-composed-from","observe-max-age","spawn-preview-max-age","launch-config-default","capability-show","capture-file",
|
|
42
44
|
"workspace-identity","server-connect","capability-route","servers-per-workspace","operator-default-soul","waiting-on-you",
|
|
43
|
-
"automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default"
|
|
45
|
+
"automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default",
|
|
46
|
+
"server-probe-features","worktree-event"],
|
|
44
47
|
"automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
|
|
45
48
|
"readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
|
|
46
49
|
"capabilityShowApi":1}
|
|
@@ -113,6 +116,9 @@ canonical (`github.com/<org>/<repo>`, or `local/<abs-path>`). Examples use
|
|
|
113
116
|
| `souls-capabilities` | `capabilities` on `oats souls --json` rows: the capabilities each soul composes, keyed like `oats capabilities` rows, with `from`, OATS 0.45.0 ([`oats capabilities` and `oats souls`](#oats-capabilities---dir---json--capabilitiesapi-1--oats-souls---dir---json--soulsapi-1)) | |
|
|
114
117
|
| `soul-composed-instructions` | `oats inspect --soul <soul> --instructions` and its `souls[].composedInstructions`: the AGENTS.md a spawn of the soul here would write, with the soul body and each composed block as ranges, OATS 0.46.0 ([`oats inspect`](#oats-inspect---home-----soul----dir----json--operationsapi-2)) | |
|
|
115
118
|
| `teams-conditional-default` | `oats teams default <label> --if-absent \| --expect <label>` and `E_TEAM_DEFAULT_MISMATCH`; `oats teams add … --no-default` and its `reused` answer; `E_TEAM_EXISTS` `observed`; unknown flags on `oats teams` refused, OATS 0.48.0 ([`oats teams`](#oats-teams)). A kernel without it ignores the flags: `--if-absent` there is an unconditional set, so check the feature before passing them | |
|
|
119
|
+
| `worktree-event` | the `worktree` hook event; `oats worktree add\|remove` ([`oats worktree`](#oats-worktree)); `worktreeHooks` on `spawn --preview` and on the spawn result and `spawned` event; `spawnInProgress` on `oats status --json` instance rows; the `worktree-added` event kind; `E_INTERRUPTED` and `E_WORKTREE_DIRTY`, OATS 0.49.0 | |
|
|
120
|
+
| `trigger-sources` | capability-declared trigger sources: `on.source: "<capability>:<source>"` triggers and their added row keys, `oats trigger poll`, `--run-source` on `trigger test` and `trigger poll` (`E_TRIGGER_SOURCE_RUN` without it), `E_TRIGGER_SOURCE`, `E_TRIGGER_POLL` `details.cause`, and `triggerSources`/`triggerSourceProblems` on `oats capabilities show`, OATS 0.50.0 ([`oats trigger`](#oats-trigger)) | `triggerApi: 1` (payload only) |
|
|
121
|
+
| `server-probe-features` | `features` on `oats status --json` (this kernel's own list, as `version --json` answers it), and each `oats server roster --json` group's `probe.features`: the host's list, relayed from that status answer after validation, `null` when unknown, OATS 0.49.0 ([The remote roster](#the-remote-roster-oats-server-roster---json)) | |
|
|
116
122
|
|
|
117
123
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
118
124
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -215,6 +221,7 @@ oats status | workspace status | souls | capabilities | inspect --soul|--home
|
|
|
215
221
|
| teams | soul teams <soul> … --max-age <seconds> --json
|
|
216
222
|
oats spawn <soul> … --preview --max-age <seconds> --json (feature spawn-preview-max-age)
|
|
217
223
|
oats capabilities show <name> … --max-age <seconds> --json (feature capability-show)
|
|
224
|
+
oats trigger poll <id> --run-source … --max-age <seconds> --json (feature trigger-sources)
|
|
218
225
|
```
|
|
219
226
|
|
|
220
227
|
- **Values:** whole seconds, `0` to `86400`. `0` is live: it reuses nothing.
|
|
@@ -274,8 +281,8 @@ oats capabilities show <name> … --max-age <seconds> --json (feature capabilit
|
|
|
274
281
|
`E_BAD_ARGS` first), with
|
|
275
282
|
`E_BAD_ARGS` "--max-age is not accepted by \`oats <form>\`: only the read
|
|
276
283
|
verbs reuse observations (status, workspace status, souls, capabilities,
|
|
277
|
-
capabilities show, inspect --soul|--home, spawn --preview,
|
|
278
|
-
forms of teams and soul teams)" and,
|
|
284
|
+
capabilities show, inspect --soul|--home, spawn --preview, trigger poll,
|
|
285
|
+
and the read forms of teams and soul teams)" and,
|
|
279
286
|
with `--server`, "--max-age cannot be combined with --server: observation
|
|
280
287
|
reuse is local to this machine".
|
|
281
288
|
A capability command's argv (`oats <namespace> …`) is its provider's: the
|
|
@@ -370,6 +377,7 @@ An instance subject, abridged:
|
|
|
370
377
|
| `instance` | `null` for a soul; the home's facts above. `instructions.sources` lists each composed inject in order |
|
|
371
378
|
| `identity` | home only (absent for a soul): the served identity a messaging provider recorded, `{…, provider}`, or `null`. Read on every call, so after a start whose launch hook returned new `meta` it is that start's record, not the spawn's |
|
|
372
379
|
| `problems` | below |
|
|
380
|
+
| `warnings` | always present (0.49.0): [capability warnings](#capability-warnings-hook-event-unsupported-oats-0490); for `--home`, `path` is home-relative |
|
|
373
381
|
|
|
374
382
|
**Soul row** (`soulsApi: 2`). For a home it is read from the recorded
|
|
375
383
|
`soulDir` (`path` and `kind` are `null`); for a soul it is the member's current
|
|
@@ -492,6 +500,9 @@ oats readiness (--home <abs> | --soul <name> [--dir <d>]) [--policy] --json
|
|
|
492
500
|
ready}` (`ready` also needs no subject blocker). `subjectBlockers[]` is
|
|
493
501
|
`{check, subject, status}` for each failing required item not about a
|
|
494
502
|
capability. `notes` is prose.
|
|
503
|
+
- `warnings` (0.49.0) is always present: the
|
|
504
|
+
[capability warnings](#capability-warnings-hook-event-unsupported-oats-0490)
|
|
505
|
+
of the subject's capabilities. They are not items and change no status.
|
|
495
506
|
|
|
496
507
|
**`installed`**, one item per module with `evidence: {from}`. `--home`
|
|
497
508
|
(producer `instance modules`): passes when the home's copy holds `oats.json`
|
|
@@ -755,7 +766,10 @@ applies: gate `sync --plan` on `version` 0.44.0 or later, never by trying.
|
|
|
755
766
|
"no-catalog", catalog, path, message}`), `E_AUTOMATION_SCHEMA` and
|
|
756
767
|
`E_AUTOMATION_DUPLICATE` (with `kind`). A problem never aborts the sync.
|
|
757
768
|
- `warnings[]`: `soul-private-ignored {code, soul, repoKey, path, message}`
|
|
758
|
-
for a soul.yaml still carrying `private
|
|
769
|
+
for a soul.yaml still carrying `private`; then (0.49.0)
|
|
770
|
+
`hook-event-unsupported {code, capability, path, message}` per hook event a
|
|
771
|
+
listed member capability declares and this kernel does not run
|
|
772
|
+
([capability warnings](#capability-warnings-hook-event-unsupported-oats-0490)).
|
|
759
773
|
- Errors: `E_LOCAL_MISSING`, `E_WORKSPACE_SCHEMA {path, problems}`,
|
|
760
774
|
`E_REMOTE_UNREADABLE`, `E_LOCK_SCHEMA`, `E_PACKAGE_MISSING`,
|
|
761
775
|
`E_PACKAGE_INTEGRITY`, `E_PACKAGE_MANIFEST`, `E_REPO_REF`, `E_BAD_ARGS`.
|
|
@@ -983,6 +997,20 @@ nothing reads a working clone.
|
|
|
983
997
|
is a list of `{name, path, description, files, filesTruncated}`, each file
|
|
984
998
|
`{path, bytes}`, or `null`. `problems` is a list of `{code, message,
|
|
985
999
|
path}`.
|
|
1000
|
+
- `warnings` (0.49.0) is always present, on the show and the `--file`
|
|
1001
|
+
answer: the capability's
|
|
1002
|
+
[capability warnings](#capability-warnings-hook-event-unsupported-oats-0490).
|
|
1003
|
+
Their `path` is the repository-relative form, unlike the paths above. The
|
|
1004
|
+
text form prints them (to stderr with `--file`).
|
|
1005
|
+
- `triggerSources` (feature `trigger-sources`), after
|
|
1006
|
+
`warnings`, only when the manifest declares the key: the declaration
|
|
1007
|
+
exactly as written, whatever its shape (untrusted text: render it as
|
|
1008
|
+
text). `triggerSourceProblems: [{source, pointer, message}]` follows only
|
|
1009
|
+
when the declaration has problems: the ones a trigger naming a source
|
|
1010
|
+
would get as `E_TRIGGER_SOURCE`, `source` `null` for a top-level problem,
|
|
1011
|
+
`pointer` a JSON pointer into the manifest. A malformed declaration never
|
|
1012
|
+
refuses the command and adds nothing to `problems`
|
|
1013
|
+
([capabilities.md](capabilities.md#trigger-sources-triggersources)).
|
|
986
1014
|
- With `--max-age` (`0` included) both the show and the `--file` answer gain
|
|
987
1015
|
the [`observation`](#observation-reuse-feature-observe-max-age-oats-0311)
|
|
988
1016
|
block `{observedAt, reused, localRevision}`.
|
|
@@ -1077,11 +1105,49 @@ nonzero exit, as for every command: `E_BAD_ARGS`, `E_CAPABILITY_UNKNOWN`,
|
|
|
1077
1105
|
(`E_LOCAL_MISSING`, `E_LOCK_SCHEMA`, …).
|
|
1078
1106
|
|
|
1079
1107
|
**Without `--json`** the show prints a short listing for an operator: the
|
|
1080
|
-
inject's path and size, each skill with its files and sizes,
|
|
1108
|
+
inject's path and size, each skill with its files and sizes, the trigger
|
|
1109
|
+
sources (name, command, events, description) and their problems, and the
|
|
1081
1110
|
problems. `--file` prints the text; a binary file prints a one-line note
|
|
1082
1111
|
instead, and a truncated file prints its text followed by a one-line note.
|
|
1083
1112
|
|
|
1084
1113
|
<a id="desktop-facts-feature-desktop-facts-oats-0290"></a>
|
|
1114
|
+
### Capability warnings (`hook-event-unsupported`, OATS 0.49.0)
|
|
1115
|
+
|
|
1116
|
+
A capability may declare a hook event this kernel does not run (a newer
|
|
1117
|
+
kernel's). It composes, the event never runs, and each answer that shows the
|
|
1118
|
+
capability carries one warning per such event
|
|
1119
|
+
([capabilities.md](capabilities.md#manifest)):
|
|
1120
|
+
|
|
1121
|
+
```json
|
|
1122
|
+
{"code":"hook-event-unsupported","capability":"acme.tool",
|
|
1123
|
+
"path":"github.com/acme/agents:capabilities/acme-tool/oats.json#/hooks/on-merge",
|
|
1124
|
+
"message":"capability acme.tool declares hook \"on-merge\", which this kernel does not run; it is ignored (this kernel runs soul-scaffold, spawn, retire, launch, worktree)"}
|
|
1125
|
+
```
|
|
1126
|
+
|
|
1127
|
+
| Answer | Where | Covers |
|
|
1128
|
+
|---|---|---|
|
|
1129
|
+
| `oats sync`, `oats workspace status` | `warnings[]`, beside `soul-private-ignored` | every listed member capability |
|
|
1130
|
+
| `oats capabilities show` (and `--file`) | `warnings[]`, always present | the capability shown |
|
|
1131
|
+
| `oats inspect`, `oats readiness` | `warnings[]`, always present | `--soul`: the soul's resolved modules; `--home`: the home's module copies |
|
|
1132
|
+
| `oats doctor --json` | `warnings[]` | `--soul`: the soul's resolved modules; without it, every member capability and every locked package's, from this machine's cache |
|
|
1133
|
+
| `oats spawn --preview`, `oats spawn` | `warnings[]`, strings | the message of each, for the soul's resolved modules, each at most 1000 characters and at most 32 lines (past that, one line naming how many more); a same-key replay answers them from the home's module copies |
|
|
1134
|
+
|
|
1135
|
+
`path` is never an absolute host path. It is `<repoKey>:<dir>/oats.json#<pointer>`
|
|
1136
|
+
for a member capability, `package:<id>:<dir>/oats.json#<pointer>` for a
|
|
1137
|
+
package capability (`<dir>` relative to the repository), and, for `--home`,
|
|
1138
|
+
`.oats/modules/<name>/oats.json#<pointer>`, relative to the home: the copy
|
|
1139
|
+
actually read. Without `--soul`, doctor reads only this machine's cache; what
|
|
1140
|
+
it cannot answer is one `information[]` line `hook-events-unchecked: <member
|
|
1141
|
+
capabilities | package <id>'s capabilities> were not checked …`, never an
|
|
1142
|
+
empty list read as "no warning". Older kernels answer no such `warnings` key
|
|
1143
|
+
(inspect, readiness, show, doctor) and refuse the capability instead.
|
|
1144
|
+
|
|
1145
|
+
`oats doctor --json` also lists what retires left behind in `information[]`:
|
|
1146
|
+
one `retained-recovery:` and one `retained-worktree:` line per item, after a
|
|
1147
|
+
line that gives each kind's total, and at most 50 items per kind
|
|
1148
|
+
([After a retire](souls-and-instances.md#after-a-retire-inspect-restore-dispose)).
|
|
1149
|
+
Each element is one line of text with no newline. The answer has no new key.
|
|
1150
|
+
|
|
1085
1151
|
### Desktop facts
|
|
1086
1152
|
|
|
1087
1153
|
Feature `desktop-facts`: facts the kernel reports so the Desktop never derives
|
|
@@ -1718,6 +1784,7 @@ it to a temporary copy (`soulFetched: true`).
|
|
|
1718
1784
|
"preflight":{"status":"complete","budgetMs":20000,"elapsedMs":53},"backendStatus":{"name":"tmux","installed":true,"started":false},
|
|
1719
1785
|
"harness":"pi","model":null,"modelSource":"native default","launchConfig":null,"backend":"tmux",
|
|
1720
1786
|
"branch":"agents/rm-api","base":{"ref":"github.com/nw/agents","oid":"66566512…"},"worktree":"/w/agents/rm/instances/rm-api/work",
|
|
1787
|
+
"worktreeHooks":[{"capability":"nw-tools","required":true}],
|
|
1721
1788
|
"relation":null,"parentInstance":null,"policy":{"childSpawns":{"allowed":true,"origin":{"kind":"default","detail":"no spawn option: children allowed"}}},
|
|
1722
1789
|
"executable":"/usr/local/bin/pi",
|
|
1723
1790
|
"capabilities":[{"name":"nw-tools","origin":"member:github.com/nw/agents@66566512…"},{"name":"oats.okf","origin":"package:oats.okf@2.1.3"}],
|
|
@@ -1737,7 +1804,17 @@ it to a temporary copy (`soulFetched: true`).
|
|
|
1737
1804
|
observed>}`, fetched into the clone at apply (`E_REMOTE_UNREADABLE` when it
|
|
1738
1805
|
cannot be); otherwise `HEAD`. `E_BRANCH_EXISTS` and `E_BASE_UNKNOWN` refuse
|
|
1739
1806
|
preview and apply alike.
|
|
1807
|
+
- `worktreeHooks` (feature `worktree-event`, OATS 0.49.0): for a `worktree`
|
|
1808
|
+
spawn, the capabilities whose `worktree` hook the spawn would fire, in the
|
|
1809
|
+
order they run, as `[{capability, required}]` (`[]` when none declares
|
|
1810
|
+
one); `null` in every other mode. `worktree` stays the path string. The
|
|
1811
|
+
text preview prints `worktree hooks: a, b (required)` or `worktree hooks:
|
|
1812
|
+
none` ([the worktree event](capabilities.md#the-worktree-event)).
|
|
1740
1813
|
- `subject` echoes `{soul, agentsRoot, dir}` byte-exact.
|
|
1814
|
+
- `warnings`, present only when there is one, is an array of strings: the
|
|
1815
|
+
launch-prompt notice, and (0.49.0) the message of each
|
|
1816
|
+
[capability warning](#capability-warnings-hook-event-unsupported-oats-0490)
|
|
1817
|
+
of the resolved modules. The apply's `warnings` carries the same messages.
|
|
1741
1818
|
|
|
1742
1819
|
**Launch.**
|
|
1743
1820
|
- `harness`, `model`, `modelSource`, `launchConfig`, `backend`, `yolo`
|
|
@@ -1884,7 +1961,12 @@ with `--expect-decision` records the key and decision in `instance.json`.
|
|
|
1884
1961
|
read `tmux` for the target.
|
|
1885
1962
|
- When they apply: `yolo`, `decision` and
|
|
1886
1963
|
`replayed` (bound apply), `wake` (keyed apply), `wakeSchedule` and
|
|
1887
|
-
`wakeScheduleError` (a requested wake)
|
|
1964
|
+
`wakeScheduleError` (a requested wake), `worktreeHooks` (feature
|
|
1965
|
+
`worktree-event`: only when the spawn ran `worktree` hooks, the receipt
|
|
1966
|
+
`[{capability, ok, required, log, exitCode, signal?, timedOut?,
|
|
1967
|
+
contract?}]`, `log` being the hook's log file).
|
|
1968
|
+
- A spawn that runs `worktree` hooks can take up to 30 minutes per hook
|
|
1969
|
+
([the worktree event](capabilities.md#the-worktree-event)).
|
|
1888
1970
|
|
|
1889
1971
|
<a id="instance-names"></a>
|
|
1890
1972
|
### Instance names
|
|
@@ -1930,6 +2012,9 @@ Feature `spawn-name`. `--name <slug>` is the exact name, with no prefix.
|
|
|
1930
2012
|
| `E_LAUNCH_*`, `E_MODEL_UNKNOWN`, `E_UNSUPPORTED_HARNESS` | | the launch selection is refused |
|
|
1931
2013
|
| `E_LAUNCH_SHIM` | | the home's `oats` (`<home>/.oats/bin/oats`) cannot be written; the spawn is rolled back |
|
|
1932
2014
|
| `E_SCHEDULE_INVALID` | | a bad wake (`--wake-json`, `--wake-file`, `--wake-*`) |
|
|
2015
|
+
| `E_INTERRUPTED` | `{signal, hooks}` | SIGINT, SIGTERM or SIGHUP while the spawn's `worktree` hooks ran (feature `worktree-event`): the running hook's process group is ended, the spawn is rolled back as for a required hook failure, and the process exits 128 + the signal number |
|
|
2016
|
+
| `E_REQUIRED_HOOK_FAILED` | `{hooks}`, plus `unconfirmed: true` when compensation cannot finish | a required `spawn` or `worktree` hook failed or timed out; the spawn is rolled back. `hooks` holds the receipt of the event that failed: one entry per hook that ran, `{capability, ok, required, log, exitCode?, signal?, timedOut?, contract?}`, paths only. `log` is `null` for a spawn hook (it keeps no log) and once the rollback removed the home; a retained home keeps a `worktree` hook's log path. Never `home`. Before 0.49.0 a required spawn hook's failure answered `E_SPAWN_FAILED` |
|
|
2017
|
+
| `E_HOOK_ENVIRONMENT_CONTRACT` | the same as `E_REQUIRED_HOOK_FAILED`, the failed entry with `contract: "environment"` | a `spawn` hook answered an `env` its manifest does not allow, or a `worktree` hook answered `env` at all |
|
|
1933
2018
|
| `E_SPAWN_FAILED` | `{unconfirmed: true}` when compensation cannot finish | anything else |
|
|
1934
2019
|
|
|
1935
2020
|
Spawn failure envelopes carry `error.details.unconfirmed: true` when an existing
|
|
@@ -1938,6 +2023,116 @@ cleanup. The keyed-spawn details retain `instance`, `home` and `launched`.
|
|
|
1938
2023
|
Confirmed completed compensation does not set this marker. This is an additive
|
|
1939
2024
|
producer migration; existing text-based compatibility checks remain.
|
|
1940
2025
|
|
|
2026
|
+
<a id="oats-worktree"></a>
|
|
2027
|
+
### `oats worktree`
|
|
2028
|
+
|
|
2029
|
+
Feature `worktree-event` (OATS 0.49.0). An instance's extra trees,
|
|
2030
|
+
`<home>/.work-<purpose>`, made and removed from its home
|
|
2031
|
+
([extra trees](souls-and-instances.md#extra-trees)). There is no `--home`,
|
|
2032
|
+
`--dir` or `--server`: the home is `$OATS_INSTANCE_HOME` (or `$OATS_HOME`),
|
|
2033
|
+
else the home enclosing the working directory.
|
|
2034
|
+
|
|
2035
|
+
```text
|
|
2036
|
+
oats worktree add --purpose <p> --branch <b> --base <remote-branch> [--repo <member key|clone path>] [--preview] [--json]
|
|
2037
|
+
oats worktree remove --purpose <p> [--json]
|
|
2038
|
+
```
|
|
2039
|
+
|
|
2040
|
+
`add` creates the tree with Git, fires the `worktree` hooks
|
|
2041
|
+
([the worktree event](capabilities.md#the-worktree-event)), writes
|
|
2042
|
+
`<home>/.oats/trees/<p>.json` and appends a `worktree-added` event. It can run
|
|
2043
|
+
for minutes; the hooks' output goes to stderr, and stdout holds only the
|
|
2044
|
+
envelope. A reader that closes either pipe early only stops reading: the add
|
|
2045
|
+
runs to its end (and its record to `ready`), the hooks' logs are whole, and
|
|
2046
|
+
what could not be printed is dropped. Its result:
|
|
2047
|
+
|
|
2048
|
+
```json
|
|
2049
|
+
{"purpose":"docs","path":"/w/agents/dev/instances/dev-1/.work-docs","clone":"/w/docs","remote":"https://github.com/nw/docs.git",
|
|
2050
|
+
"member":"github.com/nw/docs","branch":"agents/dev-1-docs","base":"main","baseOid":"9f2c41d0…","state":"ready",
|
|
2051
|
+
"hooks":[{"capability":"nw-setup","ok":true,"required":true,"log":"/w/agents/dev/instances/dev-1/.oats/logs/worktree-docs-nw-setup.log","exitCode":0}],
|
|
2052
|
+
"record":"/w/agents/dev/instances/dev-1/.oats/trees/docs.json","resumed":false,"warnings":[]}
|
|
2053
|
+
```
|
|
2054
|
+
|
|
2055
|
+
- `remote` never carries credentials; `member` is a member key or `null`.
|
|
2056
|
+
- `resumed: true`: a `ready` record with the same clone, branch and base was
|
|
2057
|
+
found; nothing ran, and the result is the recorded receipt.
|
|
2058
|
+
- `treeMissing: true` appears when a non-required hook removed or moved the
|
|
2059
|
+
tree.
|
|
2060
|
+
- `--preview` fetches and writes nothing: `{preview: true, purpose, path,
|
|
2061
|
+
clone, remote, member, branch, base, record, resume, hooks}`, `resume`
|
|
2062
|
+
being `null` or `"recover"` (an interrupted add is rolled back first), and
|
|
2063
|
+
`hooks` the hooks that would run, `[{capability, required}]`. When the tree
|
|
2064
|
+
is already made, it is the recorded receipt with `preview: true`,
|
|
2065
|
+
`resume: "noop"` and `hooksToRun: []`.
|
|
2066
|
+
|
|
2067
|
+
`remove` answers `{purpose, path, removed: true, rolledBack, branch,
|
|
2068
|
+
branchKept, branchKeptReason?, warnings?}`. After removing a `ready` tree,
|
|
2069
|
+
`rolledBack` is `false` and `branchKept` is `true`. When it completed an
|
|
2070
|
+
interrupted add's rollback, `rolledBack` is `true` and `branchKept` says
|
|
2071
|
+
whether the branch still exists. The rollback deletes the branch only when
|
|
2072
|
+
that add created it, no worktree has it checked out, and it still points at
|
|
2073
|
+
the commit the add created it at. A branch kept for one of those reasons is
|
|
2074
|
+
named in `branchKeptReason`, and is not debt.
|
|
2075
|
+
|
|
2076
|
+
The rollback signals a hook process group that the interrupted add left only
|
|
2077
|
+
when the group's leader is alive with its recorded start time. A group whose
|
|
2078
|
+
leader has exited is never signalled, because its id may already belong to
|
|
2079
|
+
an unrelated group. Instead `warnings` names it, so that leftover processes
|
|
2080
|
+
can be ended by hand.
|
|
2081
|
+
|
|
2082
|
+
Every `add` or `remove` that reads a record it may act on holds the
|
|
2083
|
+
purpose's claim, `<home>/.oats/trees/<purpose>.lock`. The claim is a file
|
|
2084
|
+
that names its holder by pid and start time. A second command waits up to
|
|
2085
|
+
3 s for a live holder, then answers `E_LIFECYCLE_BUSY` (`details.lock`,
|
|
2086
|
+
`details.pid`). A claim whose holder has died, for example one killed in the
|
|
2087
|
+
middle of a recovery, is taken over by the next command. So a killed `add`
|
|
2088
|
+
or `remove` can always be run again.
|
|
2089
|
+
|
|
2090
|
+
A killed parent does not take its running git with it. So every git step
|
|
2091
|
+
that changes a tree, a ref or the worktree list runs in its own process
|
|
2092
|
+
group, and is recorded (pid and start time) before it starts: in the claim,
|
|
2093
|
+
or for an `add`'s own steps, in the tree record. A takeover or recovery
|
|
2094
|
+
first ends a recorded git step that still runs, signalling it only while its
|
|
2095
|
+
leader runs with the recorded start time (SIGTERM, which git answers by
|
|
2096
|
+
removing its lock files, then SIGKILL). Only then does it act, so a dead
|
|
2097
|
+
command's git never finishes late on a tree or branch made after it. A git
|
|
2098
|
+
step that times out is cleared from the record only once its whole process
|
|
2099
|
+
group is gone. A git step that cannot be ended keeps the claim, or the
|
|
2100
|
+
record, and the command answers `E_LIFECYCLE_BUSY`.
|
|
2101
|
+
|
|
2102
|
+
A recorded hook group or git step that still has members while its leader's
|
|
2103
|
+
start cannot be read (where `ps` fails) is never signalled and never passed
|
|
2104
|
+
over: the leader may still be that hook or git step. The command answers
|
|
2105
|
+
`E_LIFECYCLE_BUSY`, keeping the claim or the record and touching nothing
|
|
2106
|
+
else. Its message names the group, its recorded start, why the start cannot
|
|
2107
|
+
be read and the way out: check the group by hand; if it is that step, end it
|
|
2108
|
+
(`kill -TERM -- -<pgid>`) and retry; if it is not, remove the claim or the
|
|
2109
|
+
record it names (a record with what that add left) and retry. A claim's refusal
|
|
2110
|
+
carries `details.gitPid` and `details.gitStart`.
|
|
2111
|
+
|
|
2112
|
+
A failed `add` reports the same facts about its rollback in `details`:
|
|
2113
|
+
`rolledBack`, `branchKept`, `branchKeptReason` and `warnings`.
|
|
2114
|
+
|
|
2115
|
+
| Code | When |
|
|
2116
|
+
|---|---|
|
|
2117
|
+
| `E_BAD_ARGS` | not run from an instance home; `--dir`, `--home` or `--server`; a missing value; a value starting with `-`; an invalid purpose, branch or base; `remove` of a purpose with no record (a tree made with raw Git is removed with `git worktree remove`) |
|
|
2118
|
+
| `E_INSTANCE_RETIRING` | `add` in a quarantined home, or one being retired |
|
|
2119
|
+
| `E_CLONE_MISSING` | the repository is not found, or is not a Git repository |
|
|
2120
|
+
| `E_CLONE_MISMATCH` | the path is a linked worktree, or the clone has no `origin` |
|
|
2121
|
+
| `E_BRANCH_EXISTS` | the branch exists in the clone (before the tree is made, or made by another `add` at the same moment); `details.remedy` is `<instance>/<branch>` |
|
|
2122
|
+
| `E_GIT_FAILED` | a Git step failed on its own (`git worktree add`, or `git switch` while the branch does not exist), with Git's message: `git <sub> failed in <dir>: …`; the tree is removed |
|
|
2123
|
+
| `E_PLACEMENT_TAKEN` | a `ready` record with another clone, branch or base (`details.differ`); `.work-<p>` with no record, or a file or symbolic link there; an unreadable record |
|
|
2124
|
+
| `E_LIFECYCLE_BUSY` | an add of that purpose is still running (pid and start time verified); another add or remove of that purpose holds its claim (`details.lock`); or an interrupted add's rollback could not be completed (`details.owed`) |
|
|
2125
|
+
| `E_REMOTE_UNREADABLE` | the fetch of `<base>` from `origin` failed; the tree is removed |
|
|
2126
|
+
| `E_BASE_UNKNOWN` | the new HEAD is not the fetched commit; the message names both |
|
|
2127
|
+
| `E_REQUIRED_HOOK_FAILED`, `E_HOOK_ENVIRONMENT_CONTRACT` | a required `worktree` hook failed or timed out, or a hook answered `env`; the tree is removed (`details.hooks`, `details.rolledBack`) |
|
|
2128
|
+
| `E_INTERRUPTED` | SIGINT, SIGTERM or SIGHUP while the hooks ran; the tree is removed and the process exits 128 + the signal number (`details.signal`) |
|
|
2129
|
+
| `E_WORKTREE_DIRTY` | `remove`: Git refused a tree with uncommitted or untracked work (`details.git` is Git's message); the record is kept. Commit and push, or discard, then retry |
|
|
2130
|
+
| `E_WORK_PRESERVATION_FAILED` | `remove`: Git refused for another reason, or the tree is still there; the record is kept |
|
|
2131
|
+
|
|
2132
|
+
A rollback that cannot finish keeps the record and says so in the message
|
|
2133
|
+
(`details.rolledBack: false`, `details.owed`); the next `add` or `remove` of
|
|
2134
|
+
that purpose finishes it.
|
|
2135
|
+
|
|
1941
2136
|
## `instance.json` and the roster
|
|
1942
2137
|
|
|
1943
2138
|
<a id="instancejson"></a>
|
|
@@ -1976,6 +2171,15 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
|
|
|
1976
2171
|
the copy at `<home>/.oats/modules/<cap>/`. Module skills are copied flat to
|
|
1977
2172
|
`<home>/.agents/skills/<skill>/` (homes spawned by 0.30.1 or earlier keep
|
|
1978
2173
|
`<home>/.agents/skills/<cap>/<skill>/`).
|
|
2174
|
+
- `branch`: for a worktree instance, the branch its worktree was created on.
|
|
2175
|
+
For an attached or checkout instance, the branch the tree's HEAD named at
|
|
2176
|
+
the spawn, or `null` when HEAD was detached or named a ref OATS carries no
|
|
2177
|
+
branch name for (one whose name is not valid UTF-8); never the word
|
|
2178
|
+
`"HEAD"`. The key is absent when the tree's HEAD could not be read, and for
|
|
2179
|
+
directory and workspace instances. A home spawned before 0.49.0 may record
|
|
2180
|
+
`"HEAD"` for a detached tree; [`oats instance git`](#instance-git-state-oats-instance-gitdiff-instancegitapi-1-oats-0247)
|
|
2181
|
+
reads it as no recorded branch. The roster row and the spawn result carry
|
|
2182
|
+
the same value (the spawn result has `null` where the key is absent).
|
|
1979
2183
|
- `base` (a worktree instance): `{ref, oid}`, the commit its branch started
|
|
1980
2184
|
at, as the spawn result states it (see Placement under the spawn preview).
|
|
1981
2185
|
- `providers.<cap>`: the merged payload (`{}` when none).
|
|
@@ -2001,8 +2205,10 @@ the keyed-spawn fields `decision`, `spawnIdempotencyKey`, `spawnCompleted` and
|
|
|
2001
2205
|
oats status [--dir <d>] [--max-age <s>] --json
|
|
2002
2206
|
```
|
|
2003
2207
|
|
|
2004
|
-
Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}`
|
|
2208
|
+
Not an envelope: `{root, agents, observation?, features, workspace?, problems?, warnings?}`
|
|
2005
2209
|
(`observation` only with [`--max-age`](#observation-reuse-feature-observe-max-age-oats-0311)).
|
|
2210
|
+
It carries no `schemaVersion`: a remote caller recognizes the bare roster by
|
|
2211
|
+
its absence.
|
|
2006
2212
|
|
|
2007
2213
|
```json
|
|
2008
2214
|
{"root":"/w/agents",
|
|
@@ -2013,6 +2219,7 @@ Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}
|
|
|
2013
2219
|
"modules":[{"name":"oats.okf","from":{"kind":"package","package":"oats.okf","version":"2.1.3","commit":"ab897841…","integrity":"sha256-bada35…","repoKey":"github.com/awebai/oats-okf"},
|
|
2014
2220
|
"commit":"ab897841…","current":{"commit":"ab897841…","version":"2.1.3"},"status":"current"}],
|
|
2015
2221
|
"soul":{"repoKey":"github.com/nw/agents","commit":"66566512…","current":"66566512…","status":"current"}}]}],
|
|
2222
|
+
"features":["retire-home","session-start","…","server-probe-features"],
|
|
2016
2223
|
"workspace":{"reachable":true,"key":"github.com/nw/agents","ref":"git:github.com/nw/agents","keyFrom":"workspace","standalone":false,"defaultTeam":{"label":"eng","team":"eng:nw.aweb.ai"},
|
|
2017
2224
|
"teams":{"eng":"eng:nw.aweb.ai","mine":"mine:ana.aweb.ai","ops":null},"teamsFrom":"observed"}}
|
|
2018
2225
|
```
|
|
@@ -2031,12 +2238,26 @@ Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}
|
|
|
2031
2238
|
claim is kept as `recordedHome`/`recordedInstance`), `running` (read from
|
|
2032
2239
|
the row's recorded tmux socket and session, never the caller's `$TMUX`;
|
|
2033
2240
|
`null` with `runtimeState: "unreachable"` and the tmux error as
|
|
2034
|
-
`runtimeError` when that server cannot be read
|
|
2241
|
+
`runtimeError` when that server cannot be read, and also when its socket
|
|
2242
|
+
file is missing while a process works in the home or the process scan
|
|
2243
|
+
cannot run, `runtimeError` then naming the processes or the scan's error
|
|
2244
|
+
([#624](execution-targets.md#missing-socket); with no process in the home
|
|
2245
|
+
a missing socket file reads `false`, as after a reboot); `null` for a home a
|
|
2035
2246
|
Herdr-era kernel recorded, with `runtimeState: "unsupported"` and
|
|
2036
2247
|
`runtimeError: "E_HERDR_REMOVED: …"`, the recorded `sessionTarget` staying
|
|
2037
2248
|
in the row),
|
|
2038
2249
|
`identity` when a provider recorded one, `rollbackIncomplete` and
|
|
2039
2250
|
`retirePending` when present, and the Desktop facts below.
|
|
2251
|
+
- **`spawnInProgress`** (feature `worktree-event`, OATS 0.49.0): `true` only
|
|
2252
|
+
while a spawn that is running its `worktree` hooks is verifiably alive (its
|
|
2253
|
+
pid runs with the recorded start time). Such a home holds the quarantine marker
|
|
2254
|
+
with an `inProgress` field ([capabilities.md](capabilities.md#manifest)),
|
|
2255
|
+
and its row carries `spawnInProgress: true` and **no**
|
|
2256
|
+
`rollbackIncomplete`: a live spawn, not a failed one. Once that process is
|
|
2257
|
+
gone, or when its start time cannot be read (where `ps` fails), the row
|
|
2258
|
+
carries `rollbackIncomplete` as for any quarantine, its `inProgress` naming
|
|
2259
|
+
the pid; retire still refuses an unreadable one with `E_LIFECYCLE_BUSY`
|
|
2260
|
+
until `--force`. Absent otherwise, and from older kernels.
|
|
2040
2261
|
- **`waitingOnYou`** (feature `waiting-on-you`): `{since, producer, reason,
|
|
2041
2262
|
message}` when the row is `running: true` and a producer holds a live claim
|
|
2042
2263
|
that the instance needs input from a human, else `null` (unknown, not "not
|
|
@@ -2060,6 +2281,12 @@ Not an envelope: `{root, agents, observation?, workspace?, problems?, warnings?}
|
|
|
2060
2281
|
message}` (modules then stay the recorded map), plus the deployment's
|
|
2061
2282
|
[workspace identity](#workspace-identity-feature-workspace-identity-oats-0360)
|
|
2062
2283
|
either way. Absent without `oats-local.yaml`.
|
|
2284
|
+
- **`features`** (feature `server-probe-features`, OATS 0.49.0): the
|
|
2285
|
+
running kernel's own feature list, the same array as `version --json`
|
|
2286
|
+
`features`, so a [remote roster](#the-remote-roster-oats-server-roster---json)
|
|
2287
|
+
relays a host's features from the status answer it already pulls. It is
|
|
2288
|
+
emitted at output time, never part of a reused observation. A kernel
|
|
2289
|
+
before 0.49.0 omits it.
|
|
2063
2290
|
- `problems`: the legacy-home rows ([dispatch errors](#dispatch-errors)).
|
|
2064
2291
|
`warnings`: envelope warnings. `--team` is `E_BAD_ARGS` (an envelope).
|
|
2065
2292
|
|
|
@@ -2139,7 +2366,7 @@ route target:
|
|
|
2139
2366
|
```json
|
|
2140
2367
|
{"id":"build:3f2a…","server":"build","label":"Build box","registrationPresent":true,
|
|
2141
2368
|
"target":{"sshHost":"build-host","workspace":"/srv/team","oatsPath":"oats"},
|
|
2142
|
-
"probe":{"ok":true},"agentsRoot":"/srv/team/agents",
|
|
2369
|
+
"probe":{"ok":true,"features":["retire-home","session-start","…","server-probe-features"]},"agentsRoot":"/srv/team/agents",
|
|
2143
2370
|
"workspace":{"reachable":true,"key":"github.com/acme/team","ref":"git:github.com/acme/team","keyFrom":"workspace","standalone":false,"defaultTeam":{"label":"default","team":"acme:team"},
|
|
2144
2371
|
"teams":{"default":"acme:team"},"teamsFrom":"observed"},
|
|
2145
2372
|
"souls":[{"name":"dev","harness":"claude","work":"worktree","agentsRoot":"/srv/team/agents"}],
|
|
@@ -2157,6 +2384,22 @@ route target:
|
|
|
2157
2384
|
"retireFailures":[]}
|
|
2158
2385
|
```
|
|
2159
2386
|
|
|
2387
|
+
- **`probe`**: `{ok: true, features}` when the host's `status --json` was
|
|
2388
|
+
pulled, else `{ok: false, error: {code, message}}` (ssh failed, the host
|
|
2389
|
+
answered `ok: false`, or `E_ROSTER_BUDGET`: the roster's budget ran out
|
|
2390
|
+
before this target), with no `features` key.
|
|
2391
|
+
- **`probe.features`** (feature `server-probe-features`, OATS 0.49.0): the
|
|
2392
|
+
host's kernel features, relayed from the top-level `features` of its
|
|
2393
|
+
[`status --json`](#the-roster-oats-status---json), never probed: the roster
|
|
2394
|
+
runs no `version --json` and stores nothing. The answer is untrusted, so it
|
|
2395
|
+
is relayed only when it is an array of at most 256 entries, each a string
|
|
2396
|
+
of at most 64 characters matching `^[a-z0-9]+(?:-[a-z0-9]+)*$`; then it is
|
|
2397
|
+
the host's list as answered (order and any duplicate kept). Anything else,
|
|
2398
|
+
even one bad entry among good ones, is `null`: never a filtered list. A
|
|
2399
|
+
host before 0.49.0 omits the key, so its group reads `null` too, whatever
|
|
2400
|
+
its version. Read it as `Array.isArray(probe?.features)`: not an array
|
|
2401
|
+
means unknown; `[]` is a valid answer (a host with no features), not
|
|
2402
|
+
unknown.
|
|
2160
2403
|
- **`workspace`** (feature `workspace-identity`, OATS 0.36.0): the host's
|
|
2161
2404
|
own `status --json` [`workspace` object](#workspace-identity-feature-workspace-identity-oats-0360),
|
|
2162
2405
|
relayed verbatim, or `null` when the host reports none (a deployment
|
|
@@ -2372,6 +2615,11 @@ tree: `E_NO_WORKTREE`.
|
|
|
2372
2615
|
|
|
2373
2616
|
- `observation.revision` is the HEAD oid (or `unborn`); `branch` is `null`
|
|
2374
2617
|
when detached.
|
|
2618
|
+
- `recorded` is what the spawn recorded in `instance.json`: `branch` (`null`
|
|
2619
|
+
when none was recorded) and `repo`. `drift` is `true` only when a branch
|
|
2620
|
+
was recorded and the tree is not on it. A home spawned before 0.49.0 may
|
|
2621
|
+
record the word `"HEAD"` for a detached attached or checkout tree; no
|
|
2622
|
+
branch has that name, so it reads as `branch: null` with `drift: false`.
|
|
2375
2623
|
- `upstream` without one is all `null` (unknown, not zero). `base` compares
|
|
2376
2624
|
with the default branch's merge-base; `source` is `origin/HEAD` or
|
|
2377
2625
|
`well-known`; none found is all `null` plus a note.
|
|
@@ -2396,8 +2644,11 @@ readOnly: {helpers: "disabled", optionalLocks: "off", objectsWritten: 0}}`.
|
|
|
2396
2644
|
- `against` is the observed revision (the working tree against that commit,
|
|
2397
2645
|
index included) or `"empty"` for an untracked file. A binary file has an
|
|
2398
2646
|
empty patch; over 256 KiB, `truncated: true`.
|
|
2399
|
-
- The read runs without external diff, textconv, fsmonitor, hooks,
|
|
2400
|
-
caller's Git environment or global config, and writes nothing
|
|
2647
|
+
- The read runs without external diff, textconv, fsmonitor, hooks, lazy
|
|
2648
|
+
fetch, the caller's Git environment or global config, and writes nothing
|
|
2649
|
+
(`readOnly`). An object a partial clone lacks is not fetched: the read
|
|
2650
|
+
fails with `E_GIT_FAILED` (with Git 2.44 or later; an older Git ignores
|
|
2651
|
+
`GIT_NO_LAZY_FETCH`).
|
|
2401
2652
|
- If HEAD or the index moved, the id is not in the current observation, or
|
|
2402
2653
|
anything moved during the read: `E_STALE_OBSERVATION` with
|
|
2403
2654
|
`details.observation`. Re-observe; never render a diff of another tree.
|
|
@@ -2437,7 +2688,11 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
|
|
|
2437
2688
|
older logs hold it), `child-spawn-refused`, `launch-warning` (0.30: a
|
|
2438
2689
|
`launch` hook's warning at session start/restart, `data: {message}`),
|
|
2439
2690
|
`recomposed` (from earlier kernels), `waiting` (0.40: a producer's claim,
|
|
2440
|
-
[Waiting on you](#waiting-on-you))
|
|
2691
|
+
[Waiting on you](#waiting-on-you)), `worktree-added` (0.49.0, feature
|
|
2692
|
+
`worktree-event`: `oats worktree add` made an extra tree, `data: {purpose,
|
|
2693
|
+
path, branch, base, baseOid, remote, member, hooks}`, `remote` without
|
|
2694
|
+
credentials, `member` a key or `null`, `hooks` the `worktree` hooks'
|
|
2695
|
+
receipt). `producer` is `kernel`, a capability id,
|
|
2441
2696
|
or another producer id (`agent`). Older rows may carry `eventsApi: 1`.
|
|
2442
2697
|
`launched` is written by spawn and, since 0.40, once per session start or
|
|
2443
2698
|
restart, as soon as the session exists (`data: {harness, backend,
|
|
@@ -2447,6 +2702,9 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
|
|
|
2447
2702
|
is dated at the receipt's launch time. The boundary is complete per log: a
|
|
2448
2703
|
log that missed it gets a copy of the same row (same time and data), never
|
|
2449
2704
|
a second one.
|
|
2705
|
+
- `spawned` carries `worktreeHooks` (the receipt `[{capability, ok,
|
|
2706
|
+
required, log, exitCode, …}]`) in its `data` only when the spawn ran
|
|
2707
|
+
`worktree` hooks (0.49.0).
|
|
2450
2708
|
- `retired` (`data: {agent, keepDir, self, quarantine, workRecovery, hooks,
|
|
2451
2709
|
reason?}`) is written to the workspace log only,
|
|
2452
2710
|
`<deployment>/.agents/events/<agent>--<instance>.jsonl`, which outlives the
|
|
@@ -2467,8 +2725,8 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
|
|
|
2467
2725
|
- **Incarnation.** Each row carries the writing home's `createdAt` (or
|
|
2468
2726
|
`null` for old rows); the top-level `incarnation` is the current home's (or
|
|
2469
2727
|
`null`). Earlier incarnations are returned as this address's history.
|
|
2470
|
-
- **Address.** `--home` must be a home of `<instance>` (`E_HOME_MISMATCH`)
|
|
2471
|
-
A home has one address in storage, its real path (since 0.40.2): rows are
|
|
2728
|
+
- **Address.** `--home` must be a home of `<instance>` (`E_HOME_MISMATCH`),
|
|
2729
|
+
or a retired one (below). A home has one address in storage, its real path (since 0.40.2): rows are
|
|
2472
2730
|
written and matched under it, whatever spelling a writer or reader used (a
|
|
2473
2731
|
deployment reached through a symlink, a symlinked agents root). The answer
|
|
2474
2732
|
keeps the spelling it was asked in: the top-level `home` and every
|
|
@@ -2497,6 +2755,27 @@ oats instance events <instance> [--limit <n>] [--since <iso>] [--home <abs>] [--
|
|
|
2497
2755
|
`oats status --dir <symlink>` could not see, are read now. They cannot
|
|
2498
2756
|
surface a stale claim: such a session wrote its clears and its session
|
|
2499
2757
|
boundaries under the real path too, so that history is complete.
|
|
2758
|
+
- **A retired instance** (#642) answers from its workspace log, which
|
|
2759
|
+
outlives the home. This applies only when no live home resolves: a live
|
|
2760
|
+
home of `<instance>` under the scope is always answered as above. Without
|
|
2761
|
+
`--home`, the kernel lists `<deployment>/.agents/events/*--<instance>.jsonl`
|
|
2762
|
+
(the deployment is the directory holding the scope's agents root) and takes
|
|
2763
|
+
the agent from the file name. One log answers for
|
|
2764
|
+
`<agents root>/<agent>/instances/<instance>`. Several (one name retired
|
|
2765
|
+
under two agents) refuse with `E_AMBIGUOUS_INSTANCE`, the message naming
|
|
2766
|
+
the count and asking for `--home`, and `details.candidates[]` listing each
|
|
2767
|
+
as `{root, agent, home}`. No log is `E_SESSION_UNKNOWN`, as before. A
|
|
2768
|
+
`--home` naming a removed home answers only when it is
|
|
2769
|
+
`<agents root>/<agent>/instances/<instance>` (compared by real path, so a
|
|
2770
|
+
symlinked spelling of the root is the same address) and
|
|
2771
|
+
`<deployment>/.agents/events/<agent>--<instance>.jsonl` exists; the agent
|
|
2772
|
+
is taken from the path. The logs are read from the scope's spelling of the
|
|
2773
|
+
home, and the answer's `home` (and each row's) is the `--home` as given.
|
|
2774
|
+
Any other removed `--home` is `E_HOME_MISMATCH`.
|
|
2775
|
+
The answer has the same shape as a live home's: the `home` source is
|
|
2776
|
+
`absent`, and `incarnation` is `null` (no `instance.json` remains), so
|
|
2777
|
+
`waitingOnYou` is `null` and `waitingClaims` is empty. The rows keep the
|
|
2778
|
+
incarnation they were written with.
|
|
2500
2779
|
- **Window.** `count` is the rows after `--since`; `returned` the window
|
|
2501
2780
|
(`--limit`, default 200, 1–2000); `truncated` means rows were cut or a
|
|
2502
2781
|
source was a tail. `lastEvent` is `{kind, at, producer, incarnation}` of
|
|
@@ -2660,7 +2939,10 @@ the instance back.
|
|
|
2660
2939
|
idempotencyKey, planRevision, at, ok, results, retained: ["home", "work",
|
|
2661
2940
|
"transcript", "launch"], replayed: false}`. A result is `{instance, home,
|
|
2662
2941
|
ok: true, stopped, alreadyIdle, state}` or `{instance, home, ok: false,
|
|
2663
|
-
code, message, stillRunning: [pid]}`.
|
|
2942
|
+
code, message, stillRunning: [pid]}`. `code` is `E_SESSION_UNAVAILABLE` when
|
|
2943
|
+
whether the instance runs cannot be established, among them a recorded
|
|
2944
|
+
tmux socket file that is missing while a process works in the home
|
|
2945
|
+
([#624](execution-targets.md#missing-socket)): never `alreadyIdle`.
|
|
2664
2946
|
- `ok: false`: at least one target still runs (text mode exits 1).
|
|
2665
2947
|
- A replay is the stored receipt (`<home>/.oats-stop-receipt.<key>.json`)
|
|
2666
2948
|
with `replayed: true`.
|
|
@@ -2698,8 +2980,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
2698
2980
|
true, note}` when the session is observably gone: instance.json records no
|
|
2699
2981
|
launch, or the recorded tmux server is not running, or the recorded window
|
|
2700
2982
|
is gone and no pane on that server works in the home, and in every case no
|
|
2701
|
-
live process on the host has its working directory in the home
|
|
2702
|
-
|
|
2983
|
+
live process on the host has its working directory in the home
|
|
2984
|
+
([the process scan](souls-and-instances.md#the-process-scan): `/proc` on
|
|
2985
|
+
Linux, `lsof` elsewhere; a scan that cannot run counts as not absent). Retire then proceeds
|
|
2703
2986
|
without quiescing (hooks run, work is preserved). Otherwise it stays
|
|
2704
2987
|
`unestablished`, with a `note` saying why, and retire refuses with
|
|
2705
2988
|
`E_RUNTIME_ENDPOINT_UNKNOWN`, `--force` included. `notes` repeats either
|
|
@@ -2718,7 +3001,13 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
2718
3001
|
(`retirement.disposable.home`): `not copied: <roots> (<capability>)`, the
|
|
2719
3002
|
roots as written in the manifest, in the order the baseline stores them
|
|
2720
3003
|
(sorted by capability, then root), one group per capability, groups
|
|
2721
|
-
separated by `; `. At most 16 roots are listed,
|
|
3004
|
+
separated by `; `. At most 16 roots are listed, and only as many as fit in
|
|
3005
|
+
about 1024 characters; the rest are `, and N more`. When not even one
|
|
3006
|
+
fits, the tail is `not copied: N declared roots, too long to list here`.
|
|
3007
|
+
The recovery path is never cut: when it is too long for the note, the
|
|
3008
|
+
note reads `recovery: the home is copied to the recovery directory beside
|
|
3009
|
+
the home … (its path is too long for this note: the retire receipt names
|
|
3010
|
+
it as workRecovery.path, and the retire summary prints it)`.
|
|
2722
3011
|
The second is the line above in worktree mode, `recovery: work/ is copied
|
|
2723
3012
|
there when it is not empty` in directory mode, and absent in checkout,
|
|
2724
3013
|
attached and workspace modes. They are strings in `notes`: no other key
|
|
@@ -2741,16 +3030,44 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
2741
3030
|
- `reason`: `null` for `"remove"`, why the tree is not clean for
|
|
2742
3031
|
`"retain"`, why it is refused for `"refuse"`.
|
|
2743
3032
|
|
|
2744
|
-
`notes` also carries one string per tree that says the same.
|
|
3033
|
+
`notes` also carries one string per tree that says the same. When one is
|
|
3034
|
+
too long for a note, its longest parts (branch, repository, target,
|
|
3035
|
+
reason) are replaced, longest first, by a pointer to `facts.extraWorktrees`;
|
|
3036
|
+
the tree's path stays whole, or, when the path alone is too long, the note
|
|
3037
|
+
says `an extra worktree whose path is too long for this note …;
|
|
3038
|
+
facts.extraWorktrees in the plan JSON lists it`. The trees are
|
|
2745
3039
|
part of `planRevision`: a tree created, removed, dirtied or cleaned between
|
|
2746
3040
|
the plan and the apply, or a change of its disposition or target (another
|
|
2747
3041
|
directory taking the `<leaf>-N` it would move to, for example), refuses a
|
|
2748
3042
|
guarded apply with `E_PLAN_STALE` before anything runs. A reader that does
|
|
2749
3043
|
not know the key can ignore it; the `notes` strings say the same.
|
|
3044
|
+
- Every string in `notes` is at most 4096 characters, and a plan has at most
|
|
3045
|
+
64 of them, the limits the Desktop reads (0.49.0, #658). The extra trees
|
|
3046
|
+
are the only notes whose number is not fixed: when they would pass 64, the
|
|
3047
|
+
last tree note kept says `and N more extra worktrees (facts.extraWorktrees
|
|
3048
|
+
in the plan JSON lists every one)`. A note never cuts a name or a path:
|
|
3049
|
+
the drift note gives way, longest name first, to a pointer to
|
|
3050
|
+
`facts.work.branch` or `facts.recordedBranch`; a session note whose reason
|
|
3051
|
+
is too long (a process's command line, a tmux error) points to
|
|
3052
|
+
`facts.session.note`.
|
|
3053
|
+
- A worktree-mode plan whose recorded children include attached instances
|
|
3054
|
+
that use this home's `work/` (`instance.json` `work: "attached"`, `work` a
|
|
3055
|
+
link to `<home>/work`, directly or through another link) has one note naming them (0.49.0, #718): `attached
|
|
3056
|
+
child instance(s) <names> use this home's work/ as their work: a retire
|
|
3057
|
+
that keeps the worktree repoints their work link to it; with
|
|
3058
|
+
--discard-worktree the worktree is removed and their work link will
|
|
3059
|
+
dangle`. It holds for either choice; no other key changes. A relink that
|
|
3060
|
+
fails is a string in the receipt's `warnings`.
|
|
3061
|
+
- `facts.recordedBranch` is `null` where the home records the word `"HEAD"`
|
|
3062
|
+
(a detached checkout or attached spawn before 0.49.0, #641): it is not a
|
|
3063
|
+
branch name, so `facts.work.drift` is `false` for it as well.
|
|
2750
3064
|
|
|
2751
3065
|
Plain `retire` keeps a worktree-mode instance's work: the worktree is moved
|
|
2752
3066
|
(`git worktree move`) to `<deployment>/.agents/worktrees/<repo>/<branch>` (a
|
|
2753
|
-
`-2` suffix if taken; `detached-<oid12>` when detached), state intact.
|
|
3067
|
+
`-2` suffix if taken; `detached-<oid12>` when detached), state intact. The
|
|
3068
|
+
`<branch>` leaf is the branch flattened to one path component, and a long one
|
|
3069
|
+
is cut and hashed to fit NAME_MAX
|
|
3070
|
+
([souls-and-instances.md](souls-and-instances.md#extra-trees-at-retire)). An
|
|
2754
3071
|
extra tree that is not clean is moved the same way; a clean one is removed.
|
|
2755
3072
|
|
|
2756
3073
|
```text
|
|
@@ -2783,10 +3100,20 @@ A first retire prints the **raw receipt**, not an envelope:
|
|
|
2783
3100
|
entry is gone is never touched: it is an incomplete item (`git worktree
|
|
2784
3101
|
<path>: its admin entry is missing; …`), and `--force` refuses it with
|
|
2785
3102
|
`E_WORK_PRESERVATION_FAILED`.
|
|
2786
|
-
- `--discard-worktree` removes the worktree
|
|
2787
|
-
|
|
2788
|
-
|
|
2789
|
-
|
|
3103
|
+
- `--discard-worktree` removes the worktree, and verifies that it is gone (nothing
|
|
3104
|
+
at `work/`, not in `git worktree list`); a removal that did not happen, or
|
|
3105
|
+
cannot be verified, refuses with `E_WORK_PRESERVATION_FAILED` and keeps the
|
|
3106
|
+
home, `--force` included. One exception: with no entry at all at `work/`
|
|
3107
|
+
(a dangling link is an entry) and a repository that cannot be read,
|
|
3108
|
+
`retention.worktree` is `"absent"`, never `"removed"`, and a quarantine
|
|
3109
|
+
retry keeps `could not verify removal` as an incomplete item, which only
|
|
3110
|
+
`--force` clears ([souls-and-instances.md](souls-and-instances.md)). No retire deletes a branch, a
|
|
3111
|
+
retried or `--force`d quarantine included, with the one exception below.
|
|
3112
|
+
`branchDeleted` means exactly "retire's own `--delete-branch`", which is
|
|
3113
|
+
refused, so it is always `false`; it does not say whether a branch was
|
|
3114
|
+
deleted. `spawnCompensation` (below) is the one place a branch deletion by
|
|
3115
|
+
retire is reported. `retention.branchDeleted` and
|
|
3116
|
+
`retention.branchDeletionSkipped` are not written. `--delete-branch` is refused with `E_BAD_ARGS` (`oats
|
|
2790
3117
|
retire no longer deletes branches: …`) before any effect: before a plan
|
|
2791
3118
|
revision is compared and before a recorded child is stopped. A failed
|
|
2792
3119
|
spawn's quarantine that still owes the branch the spawn created stays
|
|
@@ -2798,6 +3125,23 @@ A first retire prints the **raw receipt**, not an envelope:
|
|
|
2798
3125
|
Git cannot show it gone (`git branch <b>: could not verify whether it still
|
|
2799
3126
|
exists (…)`). Such a home cannot be completed from Desktop: the operator
|
|
2800
3127
|
deletes the branch with Git and retries, or uses `--force` from the CLI.
|
|
3128
|
+
- **The one exception** (feature `worktree-event`, OATS 0.49.0): a spawn
|
|
3129
|
+
killed while its `worktree` hooks ran (SIGKILL, or its rollback cut short)
|
|
3130
|
+
leaves a marker with `inProgress.branch` and `inProgress.baseOid`. Once
|
|
3131
|
+
that process is verified dead, retire ends the leftover hook process group,
|
|
3132
|
+
runs the retire hooks, removes the worktree and verifies the removal, and
|
|
3133
|
+
only then deletes the branch with an atomic compare-and-delete (`git
|
|
3134
|
+
update-ref -d refs/heads/<b> <baseOid>`), finishing the spawn's own
|
|
3135
|
+
compensation: a branch still at its creation commit holds no work. When
|
|
3136
|
+
the tip moved, the branch is checked out in any worktree, or the ref cannot
|
|
3137
|
+
be read, it is not deleted, and the retry stays incomplete with the
|
|
3138
|
+
"branch left" item above (the home is kept). `branchDeleted` stays
|
|
3139
|
+
`false` (retire's own `--delete-branch`); the step is reported in the
|
|
3140
|
+
additive `spawnCompensation`, the one place such a deletion is reported:
|
|
3141
|
+
`{branch, branchDeleted: true}`, or `{branch, branchDeleted: false, reason}`
|
|
3142
|
+
(`reason`: the tip moved, it is checked out in a worktree, it could not be
|
|
3143
|
+
read, or Git refused), present only when the step was reached. Desktop's
|
|
3144
|
+
retire-receipt reader accepts it as an unknown field.
|
|
2801
3145
|
- Before the worktree is removed, HEAD is read again: a HEAD that moved since
|
|
2802
3146
|
the retire's last inspection stops it with `E_WORK_PRESERVATION_FAILED`
|
|
2803
3147
|
(`the worktree's HEAD changed after it was inspected, so the worktree was
|
|
@@ -2925,9 +3269,15 @@ Refusals (envelopes): `E_PLAN_STALE`, `E_CHILDREN_RUNNING`,
|
|
|
2925
3269
|
`E_WORK_PRESERVATION_FAILED` (the home is kept; retry, or
|
|
2926
3270
|
`--discard-worktree` when it is `work/` that could not be re-homed: it does
|
|
2927
3271
|
not apply to an extra tree), `E_WORK_INSPECTION_FAILED` (the home is kept; the
|
|
2928
|
-
message names the entry or the state that could not be read
|
|
3272
|
+
message names the entry or the state that could not be read, or the directory
|
|
3273
|
+
Git reads as the top level of a `work/` whose `core.worktree` names another
|
|
3274
|
+
one),
|
|
2929
3275
|
`E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
|
|
2930
|
-
`E_NO_ROOT`, `E_LIFECYCLE_FAILED
|
|
3276
|
+
`E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (feature
|
|
3277
|
+
`worktree-event`: the home is a spawn still running its `worktree` hooks, a
|
|
3278
|
+
row with `spawnInProgress: true`, `--force` included; or one whose start time
|
|
3279
|
+
cannot be read, a `rollbackIncomplete` row, until `--force`; or a hook or git
|
|
3280
|
+
group whose leader's start cannot be read, until `--force`). A recovery whose Git status disagrees with
|
|
2931
3281
|
the source's carries `details: {home, statusDisagreement: {repo, rows: [{path,
|
|
2932
3282
|
source, recovery}], total}}` (the first 10 paths). Usage errors are text on
|
|
2933
3283
|
stderr, not envelopes.
|
|
@@ -3017,6 +3367,10 @@ selection flags. See [the start workflow](desktop-instance-start.md).
|
|
|
3017
3367
|
`E_SESSION_UNKNOWN`, the receipt kept, nothing started. The message names
|
|
3018
3368
|
that target and the way out: stop it, then `oats session restart`, which
|
|
3019
3369
|
goes ahead once that target no longer runs. Never edit or remove a receipt by hand.
|
|
3370
|
+
- A recorded tmux socket file that is missing while a process works in the
|
|
3371
|
+
home, or the process scan cannot run, is not a stopped server:
|
|
3372
|
+
`E_SESSION_UNKNOWN`, nothing started and no server created at that path
|
|
3373
|
+
([#624](execution-targets.md#missing-socket)).
|
|
3020
3374
|
- A lost response does not mean the launch failed: check status before a
|
|
3021
3375
|
retry. A remote home's saved route names its execution host.
|
|
3022
3376
|
- Errors: `E_BAD_ARGS`, `E_SESSION_UNKNOWN`, `E_UNSUPPORTED_MODE`,
|
|
@@ -3224,11 +3578,13 @@ oats schedule update <id> --description=<text> [--dir <d>] --json
|
|
|
3224
3578
|
### `oats trigger`
|
|
3225
3579
|
|
|
3226
3580
|
```text
|
|
3227
|
-
oats trigger list | show <id> | status [<id>] | test <id> | add (--file <json> | --from <package>:<template> [--set k=v]) [--description=<text>] | update <id> --description=<text> | enable <id> | disable <id> | remove <id> --json
|
|
3581
|
+
oats trigger list | show <id> | status [<id>] | test <id> [--run-source] | poll <id> --run-source [--max-age <s>] | add (--file <json> | --from <package>:<template> [--set k=v]) [--description=<text>] | update <id> --description=<text> | enable <id> | disable <id> | remove <id> --json
|
|
3228
3582
|
```
|
|
3229
3583
|
|
|
3230
3584
|
Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
|
|
3231
|
-
"trigger"`).
|
|
3585
|
+
"trigger"`). A trigger's source is the built-in `github.pull_request` or, with
|
|
3586
|
+
feature `trigger-sources`, `<capability>:<source>`, a source a
|
|
3587
|
+
capability declares ([schedules.md](schedules.md#capability-sources)).
|
|
3232
3588
|
|
|
3233
3589
|
- `list`: `{triggerApi, scope, host, snapshot, triggers, scheduler}`.
|
|
3234
3590
|
`show`, `add`, `update`, `enable`, `disable` → `{trigger}`; `remove` → `{removed,
|
|
@@ -3240,42 +3596,173 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
|
|
|
3240
3596
|
- `id` is always qualified (`local/<id>` or `<member>/<id>`); verbs accept
|
|
3241
3597
|
`local/<id>` or a bare local id.
|
|
3242
3598
|
- `on`: `{source: "github.pull_request", repo, events: [opened | reopened |
|
|
3243
|
-
ready_for_review | labeled | synchronize], labels, base?, poll}
|
|
3599
|
+
ready_for_review | labeled | synchronize], labels, base?, poll}`, or for a
|
|
3600
|
+
capability source `{source: "<capability>:<source>", params: {<name>:
|
|
3601
|
+
<string>}, events: [<the source's event names>], poll}`.
|
|
3244
3602
|
- `spawn`: `{soul, purpose, task, teams, launchConfig?, harness?, model?,
|
|
3245
3603
|
yolo?, backend?}`. `purpose` and `task` template over `{repo}`,
|
|
3246
|
-
`{number}`, `{url}`, `{event}`, `{trigger}`, `{headSha}
|
|
3604
|
+
`{number}`, `{url}`, `{event}`, `{trigger}`, `{headSha}`, `{subject}` and
|
|
3605
|
+
`{key}`; a capability source's over `{trigger}`, `{source}`, `{subject}`,
|
|
3606
|
+
`{event}`, `{key}`, `{url}` and `{fields.<name>}`. `teams` are
|
|
3247
3607
|
distinct labels passed as `--provider <messaging cap> join=<labels>`; a
|
|
3248
3608
|
soul without messaging refuses `E_TRIGGER_TEAMS {soul, teams}`.
|
|
3249
3609
|
- `template?`: `{package, version, commit, template}`.
|
|
3250
|
-
- `lastRun`: `{at, instance, home, event, number, key}
|
|
3251
|
-
|
|
3610
|
+
- `lastRun`: `{at, instance, home, event, number, subject, key}`
|
|
3611
|
+
(`subject`, 0.49.0: the event's subject, a PR's number as a string;
|
|
3612
|
+
for a run recorded before 0.49.0, its number; a capability source's
|
|
3613
|
+
run has `number: null`); `nextDue`: the next poll here, `null` before
|
|
3614
|
+
the first.
|
|
3615
|
+
- `invalid?`: `{code, message, field?}` when the stored definition no
|
|
3616
|
+
longer validates, as before. A capability source's trigger whose last
|
|
3617
|
+
meaning check failed at a poll carries `invalid: {code, message, field?,
|
|
3618
|
+
at}` instead (`code` `E_TRIGGER_SOURCE` or `E_TRIGGER_INVALID`; `at` when
|
|
3619
|
+
the check ran), until a good poll. `invalid` always means the trigger
|
|
3620
|
+
itself is invalid; an event the source answered badly is an *invalid
|
|
3621
|
+
event* (`invalidEvents`).
|
|
3252
3622
|
- `status [<id>]` → `{triggerApi, scope, triggers: [{id, name, enabled,
|
|
3253
3623
|
runsHere, reason, enabledHere, repo, soul, concurrency: {max, perKey},
|
|
3254
|
-
liveCount, live: [{instance, home, repo, number, event}], lastPoll:
|
|
3255
|
-
true, prs, matching} | {at, ok: false, error} | null, nextPollAt,
|
|
3256
|
-
pending: [{key, event, number, url, observedAt}], fired:
|
|
3257
|
-
instance, home, event, number}] (newest 50), firedTotal,
|
|
3258
|
-
code, message, key?} | null}]}`. It writes nothing.
|
|
3624
|
+
liveCount, live: [{instance, home, repo, number, subject, event}], lastPoll:
|
|
3625
|
+
{at, ok: true, prs, matching} | {at, ok: false, error} | null, nextPollAt,
|
|
3626
|
+
nextDue, pending: [{key, event, number, subject, url, observedAt}], fired:
|
|
3627
|
+
[{key, at, instance, home, event, number, subject}] (newest 50), firedTotal,
|
|
3628
|
+
lastError: {at, code, message, key?} | null}]}`. It writes nothing.
|
|
3629
|
+
`subject` (0.49.0) is the event's subject, the thing `perKey` counts: a
|
|
3630
|
+
PR's number, as a string. A record written before 0.49.0 has none, and
|
|
3631
|
+
its number is reported.
|
|
3632
|
+
- **A capability source's `status` row** (feature `trigger-sources`) has
|
|
3633
|
+
`repo: null`, `number: null` in `pending[]`, `fired[]` and `live[]`, and
|
|
3634
|
+
adds `source: {capability, name}`, `invalidEvents: [{text, rule}]` (the
|
|
3635
|
+
last good poll's, at most 20; `rule` is `shape`, `unknown-key`, `key`,
|
|
3636
|
+
`subject`, `event`, `url`, `fields` or `duplicate-key`, `text` the first
|
|
3637
|
+
200 characters of the event's JSON), `skipped: [{subject, why}]` (the last
|
|
3638
|
+
good poll's, at most 100) and, when its last meaning check failed,
|
|
3639
|
+
`invalid: {code, message, field?, at}`. Its `lastPoll` is `{at, ok: true,
|
|
3640
|
+
events, invalidEvents, skipped, filtered}` (counts) or `{at, ok: false,
|
|
3641
|
+
cause, error, source?}`, and `lastError` may carry the same `source`.
|
|
3642
|
+
`cause` is `exit`, `result`, `too-many-events`, `timeout`, `refused` or
|
|
3643
|
+
`resolution`; `source: {code, message?}` is the source's own refusal.
|
|
3644
|
+
`why`, `source.code` and `source.message` are the source's untrusted text,
|
|
3645
|
+
capped (200, 128, 500 characters) with control, separator, bidi,
|
|
3646
|
+
invisible and tag characters replaced by U+FFFD: render them as text,
|
|
3647
|
+
marked as the source's.
|
|
3648
|
+
- **Presence and staleness.** `source`, `invalidEvents` and `skipped` are
|
|
3649
|
+
always present on a capability source's status row. The two lists are
|
|
3650
|
+
`[]` until the trigger's first good poll and hold the last good poll's
|
|
3651
|
+
lists after that. A failed poll (`lastPoll.ok: false`) and a failed
|
|
3652
|
+
meaning check (`invalid`, which leaves `lastPoll` as it was) leave them
|
|
3653
|
+
unchanged, so they can be older than `lastPoll.at`, `lastError.at` and
|
|
3654
|
+
`invalid.at`. The lists are the current source's: changing a trigger's
|
|
3655
|
+
`on.source` empties them and `pending`, and clears `invalid`, `lastPoll`
|
|
3656
|
+
and `lastError` (`fired` stays), in what `status` and `list` answer at
|
|
3657
|
+
once and in the state at the next tick.
|
|
3658
|
+
- **Arrays versus counts.** In `trigger test`'s `source` (`ok: true`) and
|
|
3659
|
+
in `trigger poll`'s answer, `events`, `invalidEvents` and `skipped` are
|
|
3660
|
+
arrays and `filtered` is a count. In `lastPoll` (`ok: true`) and in the
|
|
3661
|
+
tick's `polled` row, all four are counts.
|
|
3259
3662
|
- `test <id>` → `{triggerApi, id, ok, placement: {runsOn, owner, host,
|
|
3260
3663
|
runsHere, reason, detail?, enabledHere}, gh: {ok, account,
|
|
3261
3664
|
credentialSource, reachesHostTimer, note, detail}, repo: {key, readable,
|
|
3262
3665
|
fullName, permissions: {push, maintain, admin}, canMerge} | {key, readable:
|
|
3263
3666
|
false, error}, soul: {resolves, name, agent, messaging} | {resolves: false,
|
|
3264
3667
|
name, error}, teams: {requested, undeclared | null, messaging}, wouldFire:
|
|
3265
|
-
[{key, repo, number, event, url, held?}],
|
|
3266
|
-
spawned: false}`. `ok` counts `problems`
|
|
3267
|
-
cannot reach is a warning.
|
|
3268
|
-
|
|
3269
|
-
|
|
3668
|
+
[{key, repo, number, subject, event, url, instance, nameCut, held?}],
|
|
3669
|
+
pollError?, problems, warnings, spawned: false}`. `ok` counts `problems`
|
|
3670
|
+
only; a credential the host timer cannot reach is a warning. `instance`
|
|
3671
|
+
and `nameCut` (0.49.0) are the name the spawn would be asked to derive
|
|
3672
|
+
(`<stem>-<purpose as passed>`, before spawn's `-<n>`) and whether its
|
|
3673
|
+
purpose was cut to fit ([schedules.md](schedules.md#triggers)); both are
|
|
3674
|
+
`null` when the soul does not resolve or its name is too long for a
|
|
3675
|
+
triggered spawn (that error is then in `problems`).
|
|
3676
|
+
- **`test <id> --run-source` of a capability source's trigger** runs the
|
|
3677
|
+
source (it executes the capability's source command, whatever the host's
|
|
3678
|
+
trust and `runsOn` say, and so only with the flag: see **`--run-source`**
|
|
3679
|
+
below) and answers `{triggerApi, id, ok, placement, gh, repo: null,
|
|
3680
|
+
soul, teams, source, wouldFire, problems, warnings, spawned: false}`, no
|
|
3681
|
+
`pollError`. `gh` is `null` unless the trigger has an `owner` (then as
|
|
3682
|
+
above, for the owner's host). `source` is `{capability, name, ok: true,
|
|
3683
|
+
events, invalidEvents, skipped, filtered}`, `{capability, name, ok: false,
|
|
3684
|
+
filtered: 0, invalid: {code, message, field?, at}, events: [],
|
|
3685
|
+
invalidEvents: [], skipped: []}` when its meaning fails, or `{capability,
|
|
3686
|
+
name, ok: false, filtered: 0, cause, error: {code, message}, source?,
|
|
3687
|
+
events: [], invalidEvents: [], skipped: []}` when the poll fails.
|
|
3688
|
+
Without `--run-source`, `test` answers a trigger whose meaning or
|
|
3689
|
+
resolution fails as above (exit 0, `source.ok: false`: no capability code
|
|
3690
|
+
runs to say so), and a trigger whose meaning holds with
|
|
3691
|
+
`E_TRIGGER_SOURCE_RUN`. `wouldFire` rows are `{key, subject,
|
|
3692
|
+
event, url?, instance, nameCut, held?}`. When the tick would not run the
|
|
3693
|
+
trigger here, `problems` holds `run manually with --run-source; the tick
|
|
3694
|
+
will not run it here: <reason>` (with the placement's detail). `warnings` always holds
|
|
3695
|
+
"this source's credential may not be visible to the host timer: it runs
|
|
3696
|
+
with only PATH and OATS_HOME_DIR set, so keep the source's login in its
|
|
3697
|
+
own store, not in an exported variable".
|
|
3698
|
+
- **`poll <id> --run-source`** (feature `trigger-sources`) runs a capability
|
|
3699
|
+
source's trigger's source once, its meaning checked first, and answers
|
|
3700
|
+
`{triggerApi, id, source: {capability, name}, events: [{key, subject,
|
|
3701
|
+
event, url?, fields}], invalidEvents: [{text, rule}], skipped: [{subject,
|
|
3702
|
+
why}], filtered}`, plus `observation` with `--max-age`. `events` are the
|
|
3703
|
+
valid events the trigger selects, `key` as the source wrote it (stored
|
|
3704
|
+
prefixed `<trigger>:`); `filtered` counts the valid events whose `event`
|
|
3705
|
+
the trigger does not select. It records nothing and spawns nothing, but it
|
|
3706
|
+
executes the capability's source command. A failed poll is `E_TRIGGER_POLL`
|
|
3707
|
+
with `details: {cause, source?}`; a meaning failure is `E_TRIGGER_SOURCE`
|
|
3708
|
+
`{capability, source, pointer?}` or `E_TRIGGER_INVALID {field}`; without
|
|
3709
|
+
the flag it is `E_TRIGGER_SOURCE_RUN`; a `github.pull_request` trigger is
|
|
3710
|
+
`E_BAD_ARGS`, with or without the flag. Without `--max-age` it observes
|
|
3711
|
+
the members live.
|
|
3712
|
+
- **`--run-source`** (feature `trigger-sources`): by hand, `test` and `poll`
|
|
3713
|
+
run a capability source's command only with this switch (it takes no
|
|
3714
|
+
value). It is caller intent, never trust consent: with it they run the
|
|
3715
|
+
source whatever the host's `automations.trust` and the trigger's `runsOn`
|
|
3716
|
+
say, and trust, `runsOn` and `owner` gate the tick exactly as before (the
|
|
3717
|
+
tick passes the flag to its own child). Without it, on a capability
|
|
3718
|
+
source's trigger: `E_TRIGGER_SOURCE_RUN`, `ok: false`, a non-zero exit,
|
|
3719
|
+
`details: {capability, source, flag: "--run-source"}`, and a message
|
|
3720
|
+
naming the command to run again (`oats trigger test|poll <id>
|
|
3721
|
+
--run-source`), and the trigger's `runsOn` when that is another host: it
|
|
3722
|
+
holds only the id, the capability and source names and `runsOn`, never
|
|
3723
|
+
text of the source's. Nothing of the capability has executed and nothing
|
|
3724
|
+
has been written in the deployment, the soul's copy under `agents/` and
|
|
3725
|
+
the capability's directory in the module store included. The
|
|
3726
|
+
order is fixed: a valid definition (`E_TRIGGER_INVALID`), then its meaning
|
|
3727
|
+
and the soul's resolution (`E_TRIGGER_SOURCE`, `E_TRIGGER_INVALID
|
|
3728
|
+
{field}`, `E_TRIGGER_POLL` `cause: "resolution"`), then this gate, then
|
|
3729
|
+
the run. On a `github.pull_request` trigger the flag is accepted and
|
|
3730
|
+
inert: `test` answers byte for byte the same.
|
|
3731
|
+
- **What a `triggerApi: 1` reader sees.** `triggerApi` stays 1. `on.source`
|
|
3732
|
+
is an open string: tell rows apart by it, and gate on `trigger-sources`.
|
|
3733
|
+
The keys above (`source`, `invalidEvents`, `skipped`, a meaning failure's
|
|
3734
|
+
`invalid`, `test`'s `source`) appear only on capability-source rows and
|
|
3735
|
+
are absent, not `null`, on a `github.pull_request` row, whose outputs are
|
|
3736
|
+
exactly as before. On a capability source's rows the PR-only fields are
|
|
3737
|
+
`null` (`repo`, `number`) or absent (`on.repo`, `on.labels`, `on.base`,
|
|
3738
|
+
`wouldFire[].repo`), and `lastPoll` carries the counts above instead of
|
|
3739
|
+
`prs` and `matching`.
|
|
3740
|
+
- A triggered instance records `instance.json.trigger`: `{id, key, source,
|
|
3741
|
+
repo, number, subject, url, event, headSha, observedAt, eventFile}`
|
|
3742
|
+
(`subject` since 0.49.0; `null` when the event had none). Its event file is
|
|
3743
|
+
`OATS_TRIGGER_EVENT_FILE`: `{trigger, source, repo, number, subject, url,
|
|
3744
|
+
event, headSha, labels, observedAt, key}`. For a capability source the
|
|
3745
|
+
record has `repo: null`, `number: null`, `headSha: null` and adds `fields`,
|
|
3746
|
+
and the event file is `{trigger, source, subject, event, key, url?,
|
|
3747
|
+
fields, observedAt}`.
|
|
3270
3748
|
- `update <id> --description=<text>` (feature `automation-descriptions`)
|
|
3271
3749
|
changes only a local trigger's description; `--description=` (empty)
|
|
3272
3750
|
removes it. It sets `updatedAt` and leaves fired and pending events
|
|
3273
3751
|
untouched. `<id>` is `local/<id>` or the bare id; a workspace trigger
|
|
3274
3752
|
refuses `E_AUTOMATION_WORKSPACE`. Any other flag is `E_BAD_ARGS` ("only
|
|
3275
3753
|
--description is supported for now"). An older kernel has no `update`.
|
|
3754
|
+
- `add` of a capability source's trigger checks its meaning against the
|
|
3755
|
+
soul's resolution before anything is written (`E_TRIGGER_SOURCE`,
|
|
3756
|
+
`E_TRIGGER_INVALID {field}`, or the soul's own resolution error).
|
|
3276
3757
|
- Errors: `E_TRIGGER_INVALID {field}`, `E_TRIGGER_EXISTS`,
|
|
3277
|
-
`E_TRIGGER_UNKNOWN`, `E_TRIGGER_TEAMS`, `
|
|
3278
|
-
|
|
3758
|
+
`E_TRIGGER_UNKNOWN`, `E_TRIGGER_TEAMS`, `E_TRIGGER_SOURCE {capability,
|
|
3759
|
+
source, pointer?}` (a capability source that is undeclared or malformed,
|
|
3760
|
+
whose capability the soul does not compose, or whose command is not a file
|
|
3761
|
+
inside the capability; `pointer` is a JSON pointer into the manifest),
|
|
3762
|
+
`E_TRIGGER_POLL` (`details.cause` and `details.source` for a capability
|
|
3763
|
+
source), `E_TRIGGER_SOURCE_RUN {capability, source, flag}` (`test` or
|
|
3764
|
+
`poll` of a capability source's trigger without `--run-source`: nothing
|
|
3765
|
+
ran, nothing was written), `E_TRIGGER_FAILED`, `E_BAD_ARGS`, `E_PACKAGE_MISSING`,
|
|
3279
3766
|
`E_PACKAGE_MANIFEST`, `E_LOCAL_MISSING`.
|
|
3280
3767
|
|
|
3281
3768
|
<a id="automations-shared-rows"></a>
|
|
@@ -3343,8 +3830,16 @@ registered). `maxConcurrent` is the effective scheduled-job cap (default 5);
|
|
|
3343
3830
|
- The tick's `considered[]` holds schedule rows and trigger rows `{workspace,
|
|
3344
3831
|
trigger, action, …}` with actions `not-due`, `poll-failed`, `polled`
|
|
3345
3832
|
(`prs`, `matching`), `held`, `fired` (`key`, `instance`, `home`),
|
|
3346
|
-
`spawn-failed` (`key`, `code`, `error`), `would-fire`, `
|
|
3347
|
-
`
|
|
3833
|
+
`spawn-failed` (`key`, `code`, `error`), `would-fire` (`key`, `event`,
|
|
3834
|
+
`number`, `subject`, `url`, `instance`, `nameCut`; a dry run previews the
|
|
3835
|
+
soul as a tick does, and reports a preview failure or a name that cannot
|
|
3836
|
+
fit as `spawn-failed`), `invalid` and
|
|
3837
|
+
`not-here`. A capability source's trigger adds `poll-deferred`
|
|
3838
|
+
(`deadline`: its poll could not end by 50 s after the tick started; it
|
|
3839
|
+
goes first next tick), its `polled` carries `events`, `invalidEvents`,
|
|
3840
|
+
`skipped` and `filtered`, `poll-failed` a `cause`, `invalid` a failed
|
|
3841
|
+
meaning check, and its `would-fire` has no `number`, and no `url` when the
|
|
3842
|
+
event has none. A workspace schedule's state key is `<member>~<id>`. A failed
|
|
3348
3843
|
snapshot refresh is `{workspace, action: "error", error}`.
|
|
3349
3844
|
|
|
3350
3845
|
<a id="the-harness-rename-feature-harness-oats-0270"></a>
|