@awebai/oats 0.49.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 +104 -18
- package/docs/capabilities.md +169 -0
- package/docs/capability-manifest.schema.json +42 -0
- package/docs/configuration.md +97 -0
- package/docs/desktop-cli-api.md +176 -18
- package/docs/desktop.md +13 -0
- package/docs/execution-targets.md +33 -7
- package/docs/implementation.md +18 -6
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +21 -7
- package/docs/release-lane.md +41 -0
- package/docs/release-notes/v0.50.0.md +279 -0
- package/docs/schedules.md +228 -15
- package/docs/souls-and-instances.md +69 -7
- package/docs/workspaces.md +1 -1
- package/lib/capability-show.mjs +14 -1
- package/lib/core.mjs +272 -80
- package/lib/instance-events.mjs +3 -7
- package/lib/instance-git.mjs +8 -5
- package/lib/instance-inspect.mjs +44 -15
- package/lib/refused-text.mjs +17 -0
- package/lib/retained-after-retire.mjs +387 -0
- package/lib/schedule.mjs +8 -2
- package/lib/trigger-sources.mjs +234 -0
- package/lib/triggers.mjs +521 -60
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +1 -1
package/docs/desktop-cli-api.md
CHANGED
|
@@ -117,6 +117,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
117
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)) | |
|
|
118
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
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) |
|
|
120
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)) | |
|
|
121
122
|
|
|
122
123
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
@@ -220,6 +221,7 @@ oats status | workspace status | souls | capabilities | inspect --soul|--home
|
|
|
220
221
|
| teams | soul teams <soul> … --max-age <seconds> --json
|
|
221
222
|
oats spawn <soul> … --preview --max-age <seconds> --json (feature spawn-preview-max-age)
|
|
222
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)
|
|
223
225
|
```
|
|
224
226
|
|
|
225
227
|
- **Values:** whole seconds, `0` to `86400`. `0` is live: it reuses nothing.
|
|
@@ -279,8 +281,8 @@ oats capabilities show <name> … --max-age <seconds> --json (feature capabilit
|
|
|
279
281
|
`E_BAD_ARGS` first), with
|
|
280
282
|
`E_BAD_ARGS` "--max-age is not accepted by \`oats <form>\`: only the read
|
|
281
283
|
verbs reuse observations (status, workspace status, souls, capabilities,
|
|
282
|
-
capabilities show, inspect --soul|--home, spawn --preview,
|
|
283
|
-
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,
|
|
284
286
|
with `--server`, "--max-age cannot be combined with --server: observation
|
|
285
287
|
reuse is local to this machine".
|
|
286
288
|
A capability command's argv (`oats <namespace> …`) is its provider's: the
|
|
@@ -1000,6 +1002,15 @@ nothing reads a working clone.
|
|
|
1000
1002
|
[capability warnings](#capability-warnings-hook-event-unsupported-oats-0490).
|
|
1001
1003
|
Their `path` is the repository-relative form, unlike the paths above. The
|
|
1002
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)).
|
|
1003
1014
|
- With `--max-age` (`0` included) both the show and the `--file` answer gain
|
|
1004
1015
|
the [`observation`](#observation-reuse-feature-observe-max-age-oats-0311)
|
|
1005
1016
|
block `{observedAt, reused, localRevision}`.
|
|
@@ -1094,7 +1105,8 @@ nonzero exit, as for every command: `E_BAD_ARGS`, `E_CAPABILITY_UNKNOWN`,
|
|
|
1094
1105
|
(`E_LOCAL_MISSING`, `E_LOCK_SCHEMA`, …).
|
|
1095
1106
|
|
|
1096
1107
|
**Without `--json`** the show prints a short listing for an operator: the
|
|
1097
|
-
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
|
|
1098
1110
|
problems. `--file` prints the text; a binary file prints a one-line note
|
|
1099
1111
|
instead, and a truncated file prints its text followed by a one-line note.
|
|
1100
1112
|
|
|
@@ -1130,6 +1142,12 @@ capabilities | package <id>'s capabilities> were not checked …`, never an
|
|
|
1130
1142
|
empty list read as "no warning". Older kernels answer no such `warnings` key
|
|
1131
1143
|
(inspect, readiness, show, doctor) and refuse the capability instead.
|
|
1132
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
|
+
|
|
1133
1151
|
### Desktop facts
|
|
1134
1152
|
|
|
1135
1153
|
Feature `desktop-facts`: facts the kernel reports so the Desktop never derives
|
|
@@ -2220,7 +2238,11 @@ its absence.
|
|
|
2220
2238
|
claim is kept as `recordedHome`/`recordedInstance`), `running` (read from
|
|
2221
2239
|
the row's recorded tmux socket and session, never the caller's `$TMUX`;
|
|
2222
2240
|
`null` with `runtimeState: "unreachable"` and the tmux error as
|
|
2223
|
-
`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
|
|
2224
2246
|
Herdr-era kernel recorded, with `runtimeState: "unsupported"` and
|
|
2225
2247
|
`runtimeError: "E_HERDR_REMOVED: …"`, the recorded `sessionTarget` staying
|
|
2226
2248
|
in the row),
|
|
@@ -2917,7 +2939,10 @@ the instance back.
|
|
|
2917
2939
|
idempotencyKey, planRevision, at, ok, results, retained: ["home", "work",
|
|
2918
2940
|
"transcript", "launch"], replayed: false}`. A result is `{instance, home,
|
|
2919
2941
|
ok: true, stopped, alreadyIdle, state}` or `{instance, home, ok: false,
|
|
2920
|
-
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`.
|
|
2921
2946
|
- `ok: false`: at least one target still runs (text mode exits 1).
|
|
2922
2947
|
- A replay is the stored receipt (`<home>/.oats-stop-receipt.<key>.json`)
|
|
2923
2948
|
with `replayed: true`.
|
|
@@ -2955,8 +2980,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
2955
2980
|
true, note}` when the session is observably gone: instance.json records no
|
|
2956
2981
|
launch, or the recorded tmux server is not running, or the recorded window
|
|
2957
2982
|
is gone and no pane on that server works in the home, and in every case no
|
|
2958
|
-
live process on the host has its working directory in the home
|
|
2959
|
-
|
|
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
|
|
2960
2986
|
without quiescing (hooks run, work is preserved). Otherwise it stays
|
|
2961
2987
|
`unestablished`, with a `note` saying why, and retire refuses with
|
|
2962
2988
|
`E_RUNTIME_ENDPOINT_UNKNOWN`, `--force` included. `notes` repeats either
|
|
@@ -3038,7 +3064,10 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
3038
3064
|
|
|
3039
3065
|
Plain `retire` keeps a worktree-mode instance's work: the worktree is moved
|
|
3040
3066
|
(`git worktree move`) to `<deployment>/.agents/worktrees/<repo>/<branch>` (a
|
|
3041
|
-
`-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
|
|
3042
3071
|
extra tree that is not clean is moved the same way; a clean one is removed.
|
|
3043
3072
|
|
|
3044
3073
|
```text
|
|
@@ -3338,6 +3367,10 @@ selection flags. See [the start workflow](desktop-instance-start.md).
|
|
|
3338
3367
|
`E_SESSION_UNKNOWN`, the receipt kept, nothing started. The message names
|
|
3339
3368
|
that target and the way out: stop it, then `oats session restart`, which
|
|
3340
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)).
|
|
3341
3374
|
- A lost response does not mean the launch failed: check status before a
|
|
3342
3375
|
retry. A remote home's saved route names its execution host.
|
|
3343
3376
|
- Errors: `E_BAD_ARGS`, `E_SESSION_UNKNOWN`, `E_UNSUPPORTED_MODE`,
|
|
@@ -3545,11 +3578,13 @@ oats schedule update <id> --description=<text> [--dir <d>] --json
|
|
|
3545
3578
|
### `oats trigger`
|
|
3546
3579
|
|
|
3547
3580
|
```text
|
|
3548
|
-
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
|
|
3549
3582
|
```
|
|
3550
3583
|
|
|
3551
3584
|
Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
|
|
3552
|
-
"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)).
|
|
3553
3588
|
|
|
3554
3589
|
- `list`: `{triggerApi, scope, host, snapshot, triggers, scheduler}`.
|
|
3555
3590
|
`show`, `add`, `update`, `enable`, `disable` → `{trigger}`; `remove` → `{removed,
|
|
@@ -3561,17 +3596,29 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
|
|
|
3561
3596
|
- `id` is always qualified (`local/<id>` or `<member>/<id>`); verbs accept
|
|
3562
3597
|
`local/<id>` or a bare local id.
|
|
3563
3598
|
- `on`: `{source: "github.pull_request", repo, events: [opened | reopened |
|
|
3564
|
-
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}`.
|
|
3565
3602
|
- `spawn`: `{soul, purpose, task, teams, launchConfig?, harness?, model?,
|
|
3566
3603
|
yolo?, backend?}`. `purpose` and `task` template over `{repo}`,
|
|
3567
|
-
`{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
|
|
3568
3607
|
distinct labels passed as `--provider <messaging cap> join=<labels>`; a
|
|
3569
3608
|
soul without messaging refuses `E_TRIGGER_TEAMS {soul, teams}`.
|
|
3570
3609
|
- `template?`: `{package, version, commit, template}`.
|
|
3571
3610
|
- `lastRun`: `{at, instance, home, event, number, subject, key}`
|
|
3572
3611
|
(`subject`, 0.49.0: the event's subject, a PR's number as a string;
|
|
3573
|
-
for a run recorded before 0.49.0, its number
|
|
3574
|
-
next poll here, `null` before
|
|
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`).
|
|
3575
3622
|
- `status [<id>]` → `{triggerApi, scope, triggers: [{id, name, enabled,
|
|
3576
3623
|
runsHere, reason, enabledHere, repo, soul, concurrency: {max, perKey},
|
|
3577
3624
|
liveCount, live: [{instance, home, repo, number, subject, event}], lastPoll:
|
|
@@ -3582,6 +3629,36 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
|
|
|
3582
3629
|
`subject` (0.49.0) is the event's subject, the thing `perKey` counts: a
|
|
3583
3630
|
PR's number, as a string. A record written before 0.49.0 has none, and
|
|
3584
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.
|
|
3585
3662
|
- `test <id>` → `{triggerApi, id, ok, placement: {runsOn, owner, host,
|
|
3586
3663
|
runsHere, reason, detail?, enabledHere}, gh: {ok, account,
|
|
3587
3664
|
credentialSource, reachesHostTimer, note, detail}, repo: {key, readable,
|
|
@@ -3596,20 +3673,96 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
|
|
|
3596
3673
|
purpose was cut to fit ([schedules.md](schedules.md#triggers)); both are
|
|
3597
3674
|
`null` when the soul does not resolve or its name is too long for a
|
|
3598
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`.
|
|
3599
3740
|
- A triggered instance records `instance.json.trigger`: `{id, key, source,
|
|
3600
3741
|
repo, number, subject, url, event, headSha, observedAt, eventFile}`
|
|
3601
3742
|
(`subject` since 0.49.0; `null` when the event had none). Its event file is
|
|
3602
3743
|
`OATS_TRIGGER_EVENT_FILE`: `{trigger, source, repo, number, subject, url,
|
|
3603
|
-
event, headSha, labels, observedAt, key}`.
|
|
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}`.
|
|
3604
3748
|
- `update <id> --description=<text>` (feature `automation-descriptions`)
|
|
3605
3749
|
changes only a local trigger's description; `--description=` (empty)
|
|
3606
3750
|
removes it. It sets `updatedAt` and leaves fired and pending events
|
|
3607
3751
|
untouched. `<id>` is `local/<id>` or the bare id; a workspace trigger
|
|
3608
3752
|
refuses `E_AUTOMATION_WORKSPACE`. Any other flag is `E_BAD_ARGS` ("only
|
|
3609
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).
|
|
3610
3757
|
- Errors: `E_TRIGGER_INVALID {field}`, `E_TRIGGER_EXISTS`,
|
|
3611
|
-
`E_TRIGGER_UNKNOWN`, `E_TRIGGER_TEAMS`, `
|
|
3612
|
-
|
|
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`,
|
|
3613
3766
|
`E_PACKAGE_MANIFEST`, `E_LOCAL_MISSING`.
|
|
3614
3767
|
|
|
3615
3768
|
<a id="automations-shared-rows"></a>
|
|
@@ -3681,7 +3834,12 @@ registered). `maxConcurrent` is the effective scheduled-job cap (default 5);
|
|
|
3681
3834
|
`number`, `subject`, `url`, `instance`, `nameCut`; a dry run previews the
|
|
3682
3835
|
soul as a tick does, and reports a preview failure or a name that cannot
|
|
3683
3836
|
fit as `spawn-failed`), `invalid` and
|
|
3684
|
-
`not-here`. A
|
|
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
|
|
3685
3843
|
snapshot refresh is `{workspace, action: "error", error}`.
|
|
3686
3844
|
|
|
3687
3845
|
<a id="the-harness-rename-feature-harness-oats-0270"></a>
|
package/docs/desktop.md
CHANGED
|
@@ -288,6 +288,19 @@ arguments as written, an operation and its home), its run state and where it
|
|
|
288
288
|
comes from. Writing summaries needs OATS 0.43 or later; an older OATS still
|
|
289
289
|
shows the ones it reports.
|
|
290
290
|
|
|
291
|
+
A trigger can take its events from a source a capability declares instead of
|
|
292
|
+
GitHub pull requests (OATS 0.50.0 or later). Its page shows the source and
|
|
293
|
+
what the trigger passes to it, what the source's last poll found or why it
|
|
294
|
+
failed, and which events OATS refused or the source skipped. Text that comes
|
|
295
|
+
from the source, from the trigger's file or from the capability's manifest is
|
|
296
|
+
shown as a quote with a line saying whose it is; it is never a link or a
|
|
297
|
+
button. **Test** on a pull-request trigger reads GitHub and reports what would
|
|
298
|
+
fire. **Test** on such a capability trigger runs the capability's source
|
|
299
|
+
command on this computer, so it first shows what will run and with which
|
|
300
|
+
parameters, and runs it once only when you press **Run test**. Nothing is
|
|
301
|
+
recorded or spawned, and testing does not trust or start a trigger that this
|
|
302
|
+
computer doesn't trust.
|
|
303
|
+
|
|
291
304
|
The Spawn dialog also has an optional **Recurring wake-up** setting. It binds
|
|
292
305
|
the schedule to the newly created home, preserving that agent's identity and
|
|
293
306
|
work. A wake starts that same home if it is stopped, then sends the saved
|
|
@@ -486,12 +486,33 @@ tmux -L oats kill-server # replace it: ends EVERY sessio
|
|
|
486
486
|
- `-L oats` reaches the server of the environment you type it in
|
|
487
487
|
(`TMUX_TMPDIR`). For the server an instance is on, use the socket from its
|
|
488
488
|
row in `oats status --json`: `tmux -S <socket> …`.
|
|
489
|
-
- A tmux server whose socket file is missing
|
|
490
|
-
|
|
491
|
-
that
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
489
|
+
- <a id="missing-socket"></a>A tmux server whose socket file is missing
|
|
490
|
+
(`error connecting to <socket> (No such file or directory)`) is not proof
|
|
491
|
+
that it exited: a server outlives its removed socket file (a
|
|
492
|
+
temporary-files cleaner, a removed socket directory), and tmux gives the
|
|
493
|
+
same words after a reboot, when the server is gone. So OATS reads it as
|
|
494
|
+
stopped only when no process works in the instance's home
|
|
495
|
+
([the process scan](souls-and-instances.md#the-process-scan)): the row is
|
|
496
|
+
not running and a start creates the window again, as after a reboot. When
|
|
497
|
+
a process works there, or the scan cannot run, the state is not
|
|
498
|
+
established: `oats status` shows the row `running: null` with
|
|
499
|
+
`runtimeState: "unreachable"` and a `runtimeError` that names the
|
|
500
|
+
processes (pid and program, at most five) or the scan's error;
|
|
501
|
+
`oats session start` and `restart` refuse with `E_SESSION_UNKNOWN` and
|
|
502
|
+
create no server at that path; `oats instance stop` refuses with
|
|
503
|
+
`E_SESSION_UNAVAILABLE`, never "already idle". tmux recreates a removed
|
|
504
|
+
socket file when its server process receives `SIGUSR1`
|
|
505
|
+
(`kill -USR1 <pid of that tmux server>`); OATS names that and never sends
|
|
506
|
+
it. Any process working in the
|
|
507
|
+
home counts, a shell left in that directory included, as for retire: the
|
|
508
|
+
message names its pid and program, so end it or leave the directory. A
|
|
509
|
+
socket file no server listens on (`no server running on <socket>`) is
|
|
510
|
+
definitive: stopped, with no scan
|
|
511
|
+
([#624](https://github.com/awebai/oats/issues/624)). This holds for every
|
|
512
|
+
tmux server OATS reads, not only the `oats` server, and for a home that
|
|
513
|
+
records no socket and reads your default server. A home that records
|
|
514
|
+
neither a socket nor a launch (`--no-launch`) reads as not running
|
|
515
|
+
whatever works in it.
|
|
495
516
|
|
|
496
517
|
<a id="existing-instances"></a>
|
|
497
518
|
#### Existing instances
|
|
@@ -582,6 +603,8 @@ included, opens on [the OATS tmux server](#the-oats-tmux-server).
|
|
|
582
603
|
pane is reused in place. A missing window, or one whose tmux server cannot
|
|
583
604
|
be reached, is created again on the OATS tmux server, and the start warns when that is
|
|
584
605
|
not the server the home recorded ([Existing instances](#existing-instances)).
|
|
606
|
+
A server whose socket file is missing counts as gone only when no process
|
|
607
|
+
works in the home ([missing socket file](#missing-socket)).
|
|
585
608
|
- A state that cannot be established is refused (`E_SESSION_UNKNOWN`). Two
|
|
586
609
|
starts of one home serialize (`E_SESSION_START_BUSY`). A home being retired
|
|
587
610
|
is refused (`E_INSTANCE_RETIRING`).
|
|
@@ -743,7 +766,10 @@ children and uncommitted work, with a `planRevision`. `--apply --plan-revision
|
|
|
743
766
|
<rev> --idempotency-key <key>` stops the instance and its recorded children
|
|
744
767
|
first (`--no-recursive` stops only the instance), with the same bounded
|
|
745
768
|
SIGTERM. Restart the instance later with `oats session start` or
|
|
746
|
-
`oats session restart`.
|
|
769
|
+
`oats session restart`. An instance whose recorded tmux socket file is
|
|
770
|
+
missing while a process works in its home, or the process scan cannot run,
|
|
771
|
+
is not reported idle: its result is `E_SESSION_UNAVAILABLE` and nothing is
|
|
772
|
+
stopped ([missing socket file](#missing-socket)).
|
|
747
773
|
|
|
748
774
|
### Inspect, input and attach
|
|
749
775
|
|
package/docs/implementation.md
CHANGED
|
@@ -58,6 +58,8 @@ published to npm. Its developer docs are in
|
|
|
58
58
|
| `soul-composition.mjs` | the instructions a spawn of a soul would write, composed without a spawn (kernel half + materialize into a scratch home): the one path behind `doctor --soul` and `inspect --soul --instructions` |
|
|
59
59
|
| `teams.mjs`, `teams-verbs.mjs` | the team model and the `oats teams` verbs |
|
|
60
60
|
| `schedule.mjs`, `schedule-host.mjs`, `triggers.mjs`, `automations.mjs` | schedules, triggers and the host timer |
|
|
61
|
+
| `trigger-sources.mjs` | a capability's `triggerSources`: the use-time validator (per source, never from the manifest contract or discovery) and the source wire's answer and event rules; `triggers.mjs` runs a source with `instance-inspect.mjs`'s `runModuleCommand`, the provider-check runner |
|
|
62
|
+
| `refused-text.mjs` | the one set of characters the kernel never stores or prints in text it did not write (`REFUSED_TEXT`), and `safeText`, which replaces them |
|
|
61
63
|
| `schedule-command.mjs`, `schedule-command-child.mjs` | synchronous scheduler adapter and asynchronous child supervisor: bounded output, TERM/KILL escalation and observed exit; no changes to synchronous tick/lock callbacks |
|
|
62
64
|
| `operator-dispatch.mjs` | capability commands run from a deployment, and its module store |
|
|
63
65
|
| `operator-coverage.mjs` | whether a soul the workspace offers composes `oats.setup`, for the workspace and each team (readiness and doctor warnings), and the cache-only remote offline doctor resolves through |
|
|
@@ -68,6 +70,7 @@ published to npm. Its developer docs are in
|
|
|
68
70
|
| `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
|
|
69
71
|
| `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`) as problems and warnings (`manifestContract`: an unknown, non-required hook event is a warning every reader reports), the hook environment rules, the readiness wire |
|
|
70
72
|
| `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
|
|
73
|
+
| `retained-after-retire.mjs` | what retires left behind (recovery copies, retained worktrees) as `oats doctor` information lines: read-only, Git through `instance-git.mjs`'s helper-free reads |
|
|
71
74
|
| `servers.mjs` | routing commands to a registered server |
|
|
72
75
|
| `launch-prompt-evidence.mjs` | private bounded storage of exact post-answer unmatched or structurally completed frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
|
|
73
76
|
| `launch-prompt-completion.mjs` | pure, qualified post-answer completion reporting using a finite bottom input/footer table and 21 question markers; never an input matcher |
|
|
@@ -408,7 +411,8 @@ A kernel suite is green on Linux CI **and** on a Mac with a loaded schedule
|
|
|
408
411
|
unit, a live operator tmux server and Apple git, run from inside an instance
|
|
409
412
|
home. A pull request that could not be run there says so in its hand-over. The
|
|
410
413
|
suite's own prerequisites are Node ≥ 22.12 (the leftover check loads the kernel
|
|
411
|
-
with `require`), git ≥ 2.45,
|
|
414
|
+
with `require`), git ≥ 2.45, tmux, and lsof where `/proc` cannot be read
|
|
415
|
+
(awebai/oats#783, #625). The
|
|
412
416
|
helpers in `test/helpers/host-fixture.mjs` hold the host isolation, and the
|
|
413
417
|
shared fixture (`v2Deployment`) applies all of it, so a suite built on it
|
|
414
418
|
inherits it (awebai/oats#816):
|
|
@@ -438,13 +442,21 @@ inherits it (awebai/oats#816):
|
|
|
438
442
|
no host service manager is reachable at all.
|
|
439
443
|
- **No leftover processes.** The fixture's cleanup fails when a process still
|
|
440
444
|
works in its base: `assertNoFixtureProcesses(base)`, over the kernel's own
|
|
441
|
-
`processesInHome` (lsof). It catches a hook's or a CLI's grandchild that
|
|
445
|
+
`processesInHome` (`/proc` on Linux, lsof where `/proc` is absent). It catches a hook's or a CLI's grandchild that
|
|
442
446
|
outlived the test, once its parent has exited. The scan leaves out its caller
|
|
443
447
|
and the caller's direct children, so a test's own forgotten child is not
|
|
444
448
|
found here: that is the test's bug to fix. A process still exiting gets 2 s.
|
|
445
449
|
Nothing is killed, the base is removed, and the failure names each pid and
|
|
446
450
|
command. A test that leaves a process running on purpose (a group the kernel
|
|
447
|
-
must not signal) ends it itself before that check, on failure too
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
451
|
+
must not signal) ends it itself before that check, on failure too, through
|
|
452
|
+
`fx.beforeCleanup(fn)`: the cleanup runs those synchronous functions first,
|
|
453
|
+
in order, and still runs when one throws. Never end it with a later `t.after`: node:test
|
|
454
|
+
runs `t.after` hooks in the order they were added, so a hook added after the
|
|
455
|
+
fixture's runs after the check (`test/worktree-event.test.mjs`).
|
|
456
|
+
- **Cleanup even when a test fails.** Pass the test context,
|
|
457
|
+
`v2Deployment({ t })`: the fixture registers its own cleanup with
|
|
458
|
+
`t.after` when it is created, so a test that throws, rejects or times out
|
|
459
|
+
still removes its base (awebai/oats#830). `fx.cleanup` does its work once,
|
|
460
|
+
and later calls return quietly, so an explicit `fx.cleanup()` or a test's own
|
|
461
|
+
`t.after(fx.cleanup)` can stay beside it. A fixture that fails while it is
|
|
462
|
+
built removes its base itself.
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,9 +9,9 @@ or workspace membership alone does not make a package official.
|
|
|
9
9
|
|
|
10
10
|
| package | release | capabilities | package souls |
|
|
11
11
|
|---|---|---|---|
|
|
12
|
-
| `oats.framework` | `oats-framework/v1.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.9.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
13
|
| `oats.okf` | `v5.0.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
|
-
| `oats.aweb` | `v1.
|
|
14
|
+
| `oats.aweb` | `v1.24.0` | `oats.aweb` (messaging) | |
|
|
15
15
|
| `oats.engineering` | `v1.9.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
|
16
16
|
| `oats.authoring` | `v1.0.3` | `oats.authoring` | |
|
|
17
17
|
| `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
|
package/docs/packages.md
CHANGED
|
@@ -51,7 +51,7 @@ packages:
|
|
|
51
51
|
- **Bare version** (`v5.0.0`, `5.0.0`, `1.0.0-rc.1`): the id is looked up in
|
|
52
52
|
the official catalog — `package-catalog.json` in the `oats` repo, or the file
|
|
53
53
|
named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
|
|
54
|
-
convention (`v5.0.0` or `oats-framework/v1.
|
|
54
|
+
convention (`v5.0.0` or `oats-framework/v1.9.0`) and the payload path. An id
|
|
55
55
|
the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
|
|
56
56
|
a package outside the catalog"). The catalog is the reviewed official list
|
|
57
57
|
([official-catalog.md](official-catalog.md)) and the only way a
|
|
@@ -74,9 +74,9 @@ members:
|
|
|
74
74
|
- git:github.com/acme/agents
|
|
75
75
|
- git:github.com/acme/platform
|
|
76
76
|
packages:
|
|
77
|
-
oats.framework: v1.
|
|
77
|
+
oats.framework: v1.9.0
|
|
78
78
|
oats.okf: v5.0.0
|
|
79
|
-
oats.aweb: v1.
|
|
79
|
+
oats.aweb: v1.24.0
|
|
80
80
|
teams:
|
|
81
81
|
platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
|
|
82
82
|
defaults:
|
|
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
|
|
|
134
134
|
## `oats package add | remove`
|
|
135
135
|
|
|
136
136
|
```bash
|
|
137
|
-
oats package add oats.aweb v1.
|
|
137
|
+
oats package add oats.aweb v1.24.0 # a catalog version
|
|
138
138
|
oats package add acme.tools git:github.com/acme/tools@v0.4.0
|
|
139
139
|
oats package remove acme.tools
|
|
140
140
|
```
|
|
@@ -290,6 +290,20 @@ overrides it; a workspace trigger made `from:` it shows its file header's
|
|
|
290
290
|
description, else the template's. A kernel before 0.43.0 refuses the key, so
|
|
291
291
|
a package whose template sets it needs `compatibility.oats: ">=0.43.0"`.
|
|
292
292
|
|
|
293
|
+
A template may name a capability's trigger source (feature
|
|
294
|
+
`trigger-sources`): its
|
|
295
|
+
`definition.on` is `{ source: "<capability>:<source>", params?, events,
|
|
296
|
+
poll? }`, and a parameter's `path` may point into `on.params` (for example
|
|
297
|
+
`on.params.prefix`). `add --from` checks what it means against the soul it
|
|
298
|
+
spawns, as for any capability-source trigger
|
|
299
|
+
([schedules.md](schedules.md#capability-sources)). A package does **not**
|
|
300
|
+
raise `compatibility.oats` for such a template: a template is read only by
|
|
301
|
+
`add --from`, so a kernel without feature `trigger-sources` refuses that one
|
|
302
|
+
`add --from` (`E_TRIGGER_INVALID` on `on.source`, or on `on.params` when the
|
|
303
|
+
template sets it), reports a workspace trigger made from it as a problem of
|
|
304
|
+
its snapshot, and uses the package's capabilities and souls as before. A
|
|
305
|
+
floor would refuse them all on every older host.
|
|
306
|
+
|
|
293
307
|
## Compatibility floors
|
|
294
308
|
|
|
295
309
|
A soul may state floors on package versions — constraints, not sources:
|
|
@@ -339,11 +353,11 @@ A soul that names one of the package's capabilities with
|
|
|
339
353
|
"policy": "docs/official-catalog.md",
|
|
340
354
|
"packages": {
|
|
341
355
|
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.0", "path": "oats-package" },
|
|
342
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.9.0", "path": "oats-package" }
|
|
343
357
|
}
|
|
344
358
|
}
|
|
345
359
|
```
|
|
346
360
|
|
|
347
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.
|
|
348
|
-
resolves to tag `oats-framework/v1.
|
|
361
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.9.0`
|
|
362
|
+
resolves to tag `oats-framework/v1.9.0`. Resolving through the catalog never
|
|
349
363
|
advances a lock by itself: `oats sync` does, and says so.
|
package/docs/release-lane.md
CHANGED
|
@@ -216,3 +216,44 @@ re-checks a published inventory against the source and its origin; it attests
|
|
|
216
216
|
what the remote advertised when queried, so released tags must never move.
|
|
217
217
|
`--generate --source <clone>` captures a working tree for development and
|
|
218
218
|
always records `release.status: pending`.
|
|
219
|
+
|
|
220
|
+
## Releasing `oats.framework`
|
|
221
|
+
|
|
222
|
+
The distribution package in `oats-package/` (`oats.core`, `oats.setup`,
|
|
223
|
+
`oats.support`, `oats.knowledge-theory`) is not published by `release.yml` or
|
|
224
|
+
by this lane. A deployment takes it from this repository at the tag
|
|
225
|
+
`oats-framework/v<version>`, through the catalog ref or its workspace pin. A
|
|
226
|
+
skill changed under `oats-package/` therefore reaches deployments only when
|
|
227
|
+
that tag moves, whatever kernel version carried the change.
|
|
228
|
+
|
|
229
|
+
**A kernel release whose pull requests touched `oats-package/` ships a
|
|
230
|
+
framework release with it.** To see whether one is owed:
|
|
231
|
+
|
|
232
|
+
```bash
|
|
233
|
+
git diff --stat "$(git describe --tags --abbrev=0 --match 'oats-framework/v*' origin/main)" origin/main -- oats-package
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
When the diff is not empty:
|
|
237
|
+
|
|
238
|
+
1. **The framework prep PR.** Bump `version` in the `oats.json` of each
|
|
239
|
+
changed capability and in `oats-package/oats-package.json`, and add the
|
|
240
|
+
release-notes entry. Read the skill lines added since the last tag: a
|
|
241
|
+
command or behaviour that an older kernel the capability still admits does
|
|
242
|
+
not have names the version it starts in. Guidance text alone does not
|
|
243
|
+
raise a capability's `compatibility.oats`.
|
|
244
|
+
2. **The tag.** After the PR merges, put the annotated tag
|
|
245
|
+
`oats-framework/v<version>` on its merge commit and push it. No workflow
|
|
246
|
+
runs on this tag.
|
|
247
|
+
3. **The pin**, in the kernel release-prep PR: `package-catalog.json`
|
|
248
|
+
(`ref`), `oats-workspace.yaml`, and the version literals in
|
|
249
|
+
`docs/official-catalog.md`, `docs/packages.md`, `docs/workspaces.md`,
|
|
250
|
+
`skills/oats-getting-started/SKILL.md` and
|
|
251
|
+
`test/release-packaging.test.mjs`. The pin does not ride the first PR:
|
|
252
|
+
the tag needs the bumped manifest on `main` first, and CI reads the
|
|
253
|
+
catalog's ref from the remote. Two tests in
|
|
254
|
+
`test/hook-events-forward-tolerant.test.mjs` sync a deployment that takes
|
|
255
|
+
the official catalog's packages, so the pin's CI fails with
|
|
256
|
+
`E_REMOTE_UNREADABLE` until the tag is pushed. (The clean-room smoke does
|
|
257
|
+
not read it: it tags its own copy of `oats-package/`.) A green CI proves
|
|
258
|
+
that the tag exists, not which commit it names: the pin's reviewer
|
|
259
|
+
confirms on the remote that it names the first PR's merge commit.
|