@awebai/oats 0.48.0 → 0.49.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 +226 -14
- package/docs/capabilities.md +256 -8
- package/docs/capability-manifest.schema.json +18 -5
- package/docs/configuration.md +6 -0
- package/docs/desktop-cli-api.md +368 -31
- package/docs/desktop.md +72 -5
- package/docs/execution-targets.md +17 -2
- package/docs/implementation.md +62 -1
- package/docs/integrations.md +7 -5
- package/docs/knowledge.md +167 -197
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +8 -8
- package/docs/release-notes/v0.49.0.md +770 -0
- package/docs/schedules.md +62 -39
- package/docs/servers.md +7 -0
- package/docs/souls-and-instances.md +381 -53
- package/docs/workspaces.md +2 -2
- 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 +5 -2
- package/lib/core.mjs +1109 -321
- package/lib/instance-events.mjs +6 -3
- package/lib/instance-git.mjs +11 -5
- package/lib/instance-inspect.mjs +14 -3
- 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/resolve.mjs +4 -4
- package/lib/retire-output.mjs +6 -1
- package/lib/schedule.mjs +1 -0
- package/lib/servers.mjs +32 -6
- package/lib/tree-copy.mjs +18 -7
- package/lib/triggers.mjs +201 -65
- package/lib/workspace.mjs +20 -5
- package/lib/worktree-hooks.mjs +392 -0
- package/lib/worktree.mjs +655 -0
- package/package-catalog.json +1 -1
- package/package.json +1 -1
package/docs/schedules.md
CHANGED
|
@@ -61,8 +61,8 @@ the rule is refused, `E_SCHEDULE_INVALID` or `E_TRIGGER_INVALID` with `field:
|
|
|
61
61
|
"description"`; a workspace file's header that breaks it is only a warning
|
|
62
62
|
(see [the header](#workspace-triggers-and-schedules)). It is stored as given
|
|
63
63
|
and is informational only: it never reaches a run's argv, environment, task,
|
|
64
|
-
template or reconcile. A capability that registers jobs
|
|
65
|
-
|
|
64
|
+
template or reconcile. A capability that registers command jobs can set it
|
|
65
|
+
so operators can tell those jobs apart; oats.okf 5.0 registers none. Set it
|
|
66
66
|
in the definition or with `--description=<text>` on `add`; change only it with
|
|
67
67
|
`update <id> --description=<text>` (see [Commands](#commands)). Local triggers
|
|
68
68
|
take it from OATS 0.43.0 (feature `automation-descriptions`); an older kernel
|
|
@@ -165,11 +165,17 @@ when the timer cannot reach it.
|
|
|
165
165
|
**only after a successful spawn**. Until then the event stays pending, is
|
|
166
166
|
retried at every poll, and is dropped when its PR closes. A tick that dies
|
|
167
167
|
between the spawn and the record spawns the event again on the next poll
|
|
168
|
-
(held by `perKey` while the first instance lives
|
|
168
|
+
(held by `perKey` while the first instance lives, under the same name with
|
|
169
|
+
spawn's `-2`), so a trigger's soul
|
|
169
170
|
should tolerate a second run on the same event.
|
|
171
|
+
- **Subject.** Each event has a `subject`, the thing it is about: a PR's
|
|
172
|
+
number, as a string. Two events of one PR (an `opened` and a later
|
|
173
|
+
`synchronize`) have different keys and one subject.
|
|
170
174
|
- **Concurrency.** `max` (default 1) bounds the trigger's live instances and
|
|
171
|
-
`perKey` (default 1) those of one PR, counted from the
|
|
172
|
-
`instance.json.trigger` records
|
|
175
|
+
`perKey` (default 1) those of one subject (a PR's number), counted from the
|
|
176
|
+
homes' `instance.json.trigger` records (a home spawned before 0.49.0 records
|
|
177
|
+
no subject and counts by its PR's repo and number); a retired instance frees
|
|
178
|
+
its slot. An event
|
|
173
179
|
over a bound stays pending (`held`). A newer push supersedes a pending
|
|
174
180
|
`synchronize` for an older head of the same PR.
|
|
175
181
|
- **The spawn** is `oats spawn`. `soul` is bare or qualified
|
|
@@ -180,9 +186,29 @@ when the timer cannot reach it.
|
|
|
180
186
|
setting (`E_TRIGGER_TEAMS` when the soul has no messaging capability).
|
|
181
187
|
`launchConfig`, `harness`, `model`, `yolo` and `backend` are as for
|
|
182
188
|
schedules.
|
|
189
|
+
- **The instance name** is spawn's own: `<stem>-<purpose>`, where the stem is
|
|
190
|
+
the slug of the soul's agent name (a package soul's is
|
|
191
|
+
`<package>--<soul>`, so its stem is long), read from one `oats spawn <soul>
|
|
192
|
+
--preview` (with the trigger's launch selection) per trigger per tick in
|
|
193
|
+
which it fires. Spawn never truncates or
|
|
194
|
+
rewrites a name and refuses one over 64 characters, and it adds `-2`, `-3`, …
|
|
195
|
+
when a name is taken, so the trigger keeps its names to **61 characters**,
|
|
196
|
+
three for that suffix. A name that fits is passed exactly as rendered. A
|
|
197
|
+
longer one gets a cut purpose: as much of the rendered purpose as fits, then
|
|
198
|
+
`-` and the first 6 hex characters of SHA-256 over the event key (two events
|
|
199
|
+
of one PR get different names; the same event, re-fired, the same name).
|
|
200
|
+
When a name needs cutting and the stem leaves no room even for `-<6 hex>`
|
|
201
|
+
(a stem over 54 characters), the event is not spawned: it stays pending
|
|
202
|
+
with `lastError.code: E_INSTANCE_NAME_INVALID`, naming the stem and its
|
|
203
|
+
length. A stem over 62 characters is too long even for the preview's own
|
|
204
|
+
numbered name (`<stem>-1`): it is refused with the same code, as too long
|
|
205
|
+
for a triggered spawn, and the message quotes the preview's refusal (which
|
|
206
|
+
names that numbered name and its length, not the stem's).
|
|
207
|
+
`oats trigger test <id> --json` shows each would-fire event's `instance` and
|
|
208
|
+
`nameCut`. A failed preview fails the spawn the same way, with its own code.
|
|
183
209
|
- **The event reaches the instance** as `OATS_TRIGGER_EVENT_FILE`
|
|
184
|
-
(`<home>/.oats/trigger-event.json`: `{ trigger, source, repo, number,
|
|
185
|
-
event, headSha, labels, observedAt, key }`), given to the spawn hooks and the
|
|
210
|
+
(`<home>/.oats/trigger-event.json`: `{ trigger, source, repo, number,
|
|
211
|
+
subject, url, event, headSha, labels, observedAt, key }`), given to the spawn hooks and the
|
|
186
212
|
harness, and is recorded in `instance.json.trigger`.
|
|
187
213
|
|
|
188
214
|
```sh
|
|
@@ -507,35 +533,32 @@ to its home.
|
|
|
507
533
|
fails, the spawn result still carries the instance receipt, plus
|
|
508
534
|
`wakeScheduleError` and a warning.
|
|
509
535
|
|
|
510
|
-
## Knowledge harvest
|
|
511
|
-
|
|
512
|
-
oats.okf
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
|
|
526
|
-
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
--install-host` installs it, and `--disable` disables the job without
|
|
540
|
-
stopping a running worker. The scheduler's launch receipts do not replace
|
|
541
|
-
oats.okf's own processing, delivery and acceptance receipts.
|
|
536
|
+
## Knowledge harvest and review
|
|
537
|
+
|
|
538
|
+
**oats.okf 5.0 does not schedule harvest jobs.** At important checkpoints a
|
|
539
|
+
working instance updates its notes, writes its own proposal (what to save,
|
|
540
|
+
why, and backing notes), and directly spawns the package harvester:
|
|
541
|
+
|
|
542
|
+
```sh
|
|
543
|
+
oats spawn oats.okf/knowledge-harvester --task-file <proposal> --relation unrelated
|
|
544
|
+
```
|
|
545
|
+
|
|
546
|
+
The unrelated harvester can outlive the proposing instance. It checks the
|
|
547
|
+
recorded source and its soul opt-out, accepted knowledge and open/recent
|
|
548
|
+
harvest PRs, then proposes an owned-node change through a normal reviewed
|
|
549
|
+
Git PR. Retirement does not automatically capture or harvest anything.
|
|
550
|
+
There is no host harvest switch, per-source command job, run-source command
|
|
551
|
+
or capture/drain/worker engine. The soul-only `knowledge: { harvest: off }`
|
|
552
|
+
keeps consultation while forbidding harvest of that soul's material.
|
|
553
|
+
|
|
554
|
+
**Review still uses a trigger.** Each harvest PR can be reviewed by
|
|
555
|
+
`oats.okf/knowledge-maintainer`, spawned from the package template
|
|
556
|
+
`oats.okf:harvest-review`: a workspace trigger file or a local
|
|
557
|
+
`oats trigger add --from oats.okf:harvest-review`. This is a PR-review
|
|
558
|
+
trigger, not a harvest scheduler or a kernel PR-opened capture hook.
|
|
559
|
+
|
|
560
|
+
Deployments upgrading from 4.x must settle registered sources before
|
|
561
|
+
changing the pin, then use the 5.0 guard-exempt host-key cleanup before new
|
|
562
|
+
spawns. See the [5.0 cutover sequence](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters). Provider
|
|
563
|
+
behaviour remains in the [oats.okf package](https://github.com/awebai/oats-okf);
|
|
564
|
+
none of this adds provider-specific behaviour to the scheduler or kernel.
|
package/docs/servers.md
CHANGED
|
@@ -311,6 +311,13 @@ its group from the saved routes. State is pulled on every call within
|
|
|
311
311
|
`--per-target` (default 20 s) of a total `--budget` (default 45 s); a group
|
|
312
312
|
not reached is reported with `E_ROSTER_BUDGET`. `--server <id>` narrows it.
|
|
313
313
|
|
|
314
|
+
The group's `probe` also relays the host's kernel features (0.49.0,
|
|
315
|
+
`probe.features`): the top-level `features` of the same `status --json`
|
|
316
|
+
answer, never a separate `version --json`, kept only when it is a valid list
|
|
317
|
+
of feature names and otherwise `null` (unknown, as from a host before
|
|
318
|
+
0.49.0); a failed probe has no `features` key
|
|
319
|
+
([the field](desktop-cli-api.md#the-remote-roster-oats-server-roster---json)).
|
|
320
|
+
|
|
314
321
|
**Harvest** runs the knowledge capability's `okf harvest --json` in the
|
|
315
322
|
instance's saved home on the server and relays its envelope.
|
|
316
323
|
|