@awebai/oats 0.69.14 → 0.69.16
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/bin/oats.mjs +79 -18
- package/docs/capabilities.md +57 -14
- package/docs/container.md +111 -17
- package/docs/desktop-cli-api.md +215 -19
- package/docs/desktop.md +3 -3
- package/docs/execution-targets.md +15 -3
- package/docs/first-team.md +4 -3
- package/docs/implementation.md +19 -9
- package/docs/integrations.md +9 -8
- package/docs/knowledge-and-learning.md +2 -2
- package/docs/knowledge-theory.md +17 -15
- package/docs/knowledge.md +202 -179
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +13 -13
- package/docs/release-notes/v0.69.15.md +444 -0
- package/docs/release-notes/v0.69.16.md +169 -0
- package/docs/schedules.md +168 -34
- package/docs/servers.md +64 -3
- package/docs/souls-and-instances.md +100 -19
- package/docs/upgrading.md +26 -6
- package/docs/workspaces.md +2 -2
- package/lib/claim.mjs +2 -3
- package/lib/command-flags.mjs +4 -2
- package/lib/core.mjs +215 -72
- package/lib/dir-lock.mjs +17 -0
- package/lib/errors.mjs +2 -1
- package/lib/host-run.mjs +218 -0
- package/lib/host-stop-child.mjs +21 -0
- package/lib/instance-git.mjs +32 -6
- package/lib/instance-lifecycle.mjs +4 -3
- package/lib/instance-listing.mjs +35 -6
- package/lib/kernel-features.mjs +4 -1
- package/lib/read-call.mjs +1 -1
- package/lib/remote.mjs +17 -14
- package/lib/schedule.mjs +237 -20
- package/lib/servers.mjs +83 -5
- package/lib/session-end.mjs +28 -8
- package/lib/session-resume.mjs +10 -18
- package/lib/session-seen.mjs +4 -64
- package/lib/status-words.mjs +11 -4
- package/lib/system-tools.mjs +1 -36
- package/lib/worktree-hooks.mjs +6 -175
- package/lib/worktree.mjs +19 -10
- package/package-catalog.json +3 -3
- package/package.json +4 -1
- package/packages/record/README.md +56 -21
- package/packages/record/docs/capture-service.md +8 -5
- package/packages/record/docs/turn-record-sot.md +9 -0
- package/packages/record/lib/capture-health.mjs +6 -4
- package/packages/record/lib/capture-lock.mjs +31 -27
- package/packages/record/lib/capture-retained-scratch.mjs +4 -3
- package/packages/record/lib/capture-scratch.mjs +2 -1
- package/packages/record/lib/derived-state.mjs +4 -2
- package/packages/record/lib/index-db.mjs +4 -2
- package/packages/record/lib/lock-holder.mjs +21 -0
- package/packages/record/lib/private-files.mjs +18 -0
- package/packages/record/lib/process-identity.mjs +310 -0
- package/packages/record/lib/store.mjs +31 -25
- package/skills/oats-getting-started/SKILL.md +9 -6
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
# OATS 0.69.16
|
|
2
|
+
|
|
3
|
+
0.69.16 moves OATS onto oats.okf 6: there is no knowledge harvester any more,
|
|
4
|
+
and an instance proposes what it learned itself, as a pull request the
|
|
5
|
+
knowledge maintainer reviews (`oats okf propose`). The official catalog pins
|
|
6
|
+
oats.okf 6.0.1, oats.aweb 1.39.0 and oats.framework 1.24.0, and OATS's own
|
|
7
|
+
texts, souls and template copy follow. The team agent image now runs
|
|
8
|
+
`oats host run`.
|
|
9
|
+
|
|
10
|
+
## Upgrade
|
|
11
|
+
|
|
12
|
+
- **Either order of the Desktop and the CLI works.**
|
|
13
|
+
[Upgrading](../upgrading.md) installs the Desktop first, and a host that
|
|
14
|
+
installed the CLI first is fine too: the 0.69.16 Desktop accepts OATS CLIs
|
|
15
|
+
`>=0.26.0 <0.70.0`, as the 0.69.15 Desktop does.
|
|
16
|
+
- **Package pins:** oats.okf 6.0.1 (from 5.8.0), oats.aweb 1.39.0 (from
|
|
17
|
+
1.37.0) and oats.framework 1.24.0 (from 1.23.0). A deployment that pins
|
|
18
|
+
them takes the steps below; one that keeps its own pins changes nothing
|
|
19
|
+
until it moves them.
|
|
20
|
+
|
|
21
|
+
- **A deployment that takes oats.okf 6.0.1 does these by hand**, from its
|
|
22
|
+
deployment directory (oats.okf's
|
|
23
|
+
[Upgrading to 6.0](https://github.com/oats-project/oats-okf/blob/v6.0.1/README.md#upgrading-to-60)
|
|
24
|
+
has each step's commands; [knowledge.md](../knowledge.md#pin-and-select-the-package)
|
|
25
|
+
the summary):
|
|
26
|
+
1. Delete the harvester's launch preference, if any:
|
|
27
|
+
`oats soul launch remove oats.okf/knowledge-harvester --plan`, then
|
|
28
|
+
without `--plan`.
|
|
29
|
+
2. Delete every `--provider oats.okf harvest=…` spawn flag from the
|
|
30
|
+
scripts and briefs that spawn instances. Remove a leftover host
|
|
31
|
+
`harvest` key with `oats okf setup --remove-legacy-settings --soul
|
|
32
|
+
<soul>` (`--plan` first).
|
|
33
|
+
3. Add the `proposal-review` trigger beside `harvest-review`: an existing
|
|
34
|
+
`harvest-review` watches only the 5.x label `okf-harvest`, so it never
|
|
35
|
+
reviews a 6.0 proposal. For a workspace file, copy it under the template
|
|
36
|
+
`oats.okf:proposal-review` and the id `okf-proposal-review`, keeping its
|
|
37
|
+
`set:`, `runsOn` and `owner`. On its review host, if `oats-local.yaml`
|
|
38
|
+
lists named `automations: trust:` entries, add
|
|
39
|
+
`- <member>/okf-proposal-review` beside the old one, then check that
|
|
40
|
+
`oats trigger show <member>/okf-proposal-review --json` answers
|
|
41
|
+
`runsHere: true`. For a local trigger, read its values with `oats
|
|
42
|
+
trigger show <id> --json` and repeat them as `--set` values on `oats
|
|
43
|
+
trigger add --from oats.okf:proposal-review`. Remove `harvest-review`
|
|
44
|
+
(and its trust line) once no 5.x harvester can open an `okf-harvest`
|
|
45
|
+
PR.
|
|
46
|
+
4. Protect every Git base's accepted branch (pull requests only, merged by
|
|
47
|
+
the knowledge maintainer's account), and give each proposing host's
|
|
48
|
+
account branch-create access on the knowledge repository, never
|
|
49
|
+
accepted-branch push; optionally set `screen-terms-file`
|
|
50
|
+
([Settings](../knowledge.md#settings)).
|
|
51
|
+
5. Retire the harvesters `oats status` still lists, once they have handed
|
|
52
|
+
over. A retired source's claims are proposed with the operator form,
|
|
53
|
+
`oats okf propose --home <retirement recovery directory> --soul <soul>`
|
|
54
|
+
(`--plan`, `--check`, `--apply`).
|
|
55
|
+
- **OATS's own workspace** adds `oats-triggers/okf-proposal-review.yaml`
|
|
56
|
+
beside `okf-harvest-review.yaml`. On the host it names, add its trust line
|
|
57
|
+
as in step 3 unless that host trusts `"*"`.
|
|
58
|
+
|
|
59
|
+
- **oats.aweb 1.39.0 tests aw 1.36.56** (from 1.36.53). The floor stays
|
|
60
|
+
aw 1.36.33. `aw-newer-than-tested` now warns only above 1.36.56, and the
|
|
61
|
+
pin it names is `npm i -g @awebai/aw@1.36.56`. Install that version on
|
|
62
|
+
each host where readiness asks for it.
|
|
63
|
+
- **pi homes: remove or filter `@awebai/claude-skills` in the launch's pi
|
|
64
|
+
folder.** From oats.aweb 1.38.0, home readiness warns
|
|
65
|
+
`pi-skills-package-loaded` when that pi folder lists
|
|
66
|
+
`npm:@awebai/claude-skills` without `"skills": []`. Remove the entry, or
|
|
67
|
+
filter it. With @awebai/pi 0.5.0 or later installed there,
|
|
68
|
+
`pi-extension-skills-loaded` no longer asks for the skills filter.
|
|
69
|
+
- **Bringing your own team** (`oats aweb setup --create <label> --namespace
|
|
70
|
+
<domain>`) needs aw 1.36.53 or later, and refuses an older aw before it
|
|
71
|
+
creates anything.
|
|
72
|
+
|
|
73
|
+
- **Rebuild the [team agent image](../container.md) and recreate its
|
|
74
|
+
container.** The image pins OATS 0.69.15 and its entrypoint runs
|
|
75
|
+
`oats host run`; an existing container keeps the old entrypoint, the
|
|
76
|
+
10-second stop timeout and no healthcheck until it is made again from the
|
|
77
|
+
new image and `container/agent/compose.agent.yaml` (`docker compose ... up
|
|
78
|
+
-d`). `container/agent/accept.sh` refuses a container whose stop timeout
|
|
79
|
+
is not 45 seconds or whose healthcheck is not the service file's.
|
|
80
|
+
- **A platform that does not read the Compose file** gives the container a
|
|
81
|
+
stop timeout of 45 seconds itself: `oats host run` gives each harness 20
|
|
82
|
+
seconds to end, and Docker's default of 10 kills the agents before they
|
|
83
|
+
are stopped in order.
|
|
84
|
+
- **Register the deployment for schedules once**, after `server connect`:
|
|
85
|
+
`oats schedule host install --register-only --server team-agent`. The
|
|
86
|
+
operator's OATS must be 0.69.15 or later for the option.
|
|
87
|
+
|
|
88
|
+
## Changed
|
|
89
|
+
|
|
90
|
+
- **The official catalog pins oats.okf 6.0.1** (from 5.8.0, crossing 6.0.0),
|
|
91
|
+
and OATS's own workspace takes it. 6.0 removes the knowledge harvester: an
|
|
92
|
+
instance proposes its knowledge by pull request at its checkpoints (`oats
|
|
93
|
+
okf propose`), and the knowledge maintainer reviews it. `oats.okf-harvest`
|
|
94
|
+
and `oats.okf/knowledge-harvester` stay as refusing stubs until 7.0. It
|
|
95
|
+
also reads a bridged knowledge base by subject (`okf.json` version 2, and
|
|
96
|
+
the `subjects`, `subject`, `claims` and `verdicts` verbs); a base that is
|
|
97
|
+
not bridged, and a version-1 soul, are served as before. The generated
|
|
98
|
+
mirror under `mirrors/oats-okf*` is finalized from the v6.0.1 tag
|
|
99
|
+
([oats.okf's CHANGELOG](https://github.com/oats-project/oats-
|
|
100
|
+
okf/blob/v6.0.1/CHANGELOG.md)).
|
|
101
|
+
|
|
102
|
+
- **OATS's texts follow oats.okf 6: an instance proposes its own knowledge.**
|
|
103
|
+
The docs, the souls and the `oats.framework` skills no longer name a
|
|
104
|
+
harvester to launch, wait for or retire: at each knowledge checkpoint an
|
|
105
|
+
instance with a duty to propose runs `oats okf propose` itself, and the
|
|
106
|
+
knowledge maintainer's review gates the pull request
|
|
107
|
+
([knowledge.md](../knowledge.md#the-flow),
|
|
108
|
+
[schedules.md](../schedules.md#knowledge-proposal-review)). A finished
|
|
109
|
+
instance's done line is one of "done, proposed: <PR URLs>", "done, nothing
|
|
110
|
+
to propose: <reason>" or "done, no duty to propose"; "done, proposal
|
|
111
|
+
pending: <slug and why>" means it is not finished yet.
|
|
112
|
+
|
|
113
|
+
- **`oats.framework` 1.24.0 carries OATS's texts for oats.okf 6 and the pi
|
|
114
|
+
folder steps for @awebai/pi 0.5.0.**
|
|
115
|
+
- `oats.setup` 2.15.0:
|
|
116
|
+
- `/oats-onboarding`, `/oats-automations` and `/oats-agent-permissions`
|
|
117
|
+
describe oats.okf 6.0.1: an instance proposes its own knowledge with
|
|
118
|
+
`oats okf propose`, the `oats.okf:proposal-review` trigger reviews it,
|
|
119
|
+
and there is no harvester to set up.
|
|
120
|
+
- `/oats-host-delivery`'s pi step asks for the skills filter only below
|
|
121
|
+
@awebai/pi 0.5.0, and keeps @awebai/claude-skills out of OATS pi
|
|
122
|
+
folders.
|
|
123
|
+
- `oats.coordination-setup` 1.0.1's `/coordination-best-practices` says
|
|
124
|
+
knowledge is proposed at checkpoints, not harvested.
|
|
125
|
+
|
|
126
|
+
The commands these name come from oats.okf 6, which the catalog pins. None
|
|
127
|
+
needs a newer OATS than each capability already admits.
|
|
128
|
+
|
|
129
|
+
- **OATS's copy of the engineering template moves to template-v3.0.2**, which
|
|
130
|
+
makes the same change in the coordination skills and injects.
|
|
131
|
+
|
|
132
|
+
- **The official catalog pins oats.aweb 1.39.0** (from 1.37.0, crossing
|
|
133
|
+
1.38.0), and OATS's own workspace takes it. It brings:
|
|
134
|
+
- from 1.38.0, the pi skills-filter change above;
|
|
135
|
+
- from 1.39.0, a bring-your-own-team create that runs to the end
|
|
136
|
+
(registers the team, publishes and verifies its team-server record, and
|
|
137
|
+
resumes when re-run); a public `aw-compat.json` stating the aw floor and
|
|
138
|
+
the tested aw; and owner-only draft files for mail and chat bodies
|
|
139
|
+
instead of fixed `/tmp` paths.
|
|
140
|
+
|
|
141
|
+
`mirrors/oats-aweb` and `mirrors/oats-aweb-tasks` are copied from the
|
|
142
|
+
v1.39.0 tag
|
|
143
|
+
([oats.aweb's CHANGELOG](https://github.com/awebai/oats-aweb/blob/v1.39.0/CHANGELOG.md)).
|
|
144
|
+
|
|
145
|
+
- **The team agent image runs the kernel's periodic work.** Its entrypoint
|
|
146
|
+
starts sshd in the background and ends in `exec oats host run`, so that
|
|
147
|
+
command is tini's direct child, the process the runtime's SIGTERM reaches
|
|
148
|
+
and the container waits for. At start it resumes the sessions lost when
|
|
149
|
+
the container last stopped, then runs the schedule tick each minute for
|
|
150
|
+
the registered deployments; on `docker stop` it stops the agents in order
|
|
151
|
+
and the next start resumes them
|
|
152
|
+
([container.md](../container.md#the-kernels-periodic-work)).
|
|
153
|
+
- The image pins OATS 0.69.15, the first release with `oats host run`.
|
|
154
|
+
- The Compose service sets `stop_grace_period: 45s`.
|
|
155
|
+
- The Compose service has a healthcheck that opens sshd's port,
|
|
156
|
+
`127.0.0.1:2222`, every 30 seconds. `oats host run` does not supervise
|
|
157
|
+
sshd, and Docker does not restart an unhealthy container: when
|
|
158
|
+
`docker inspect --format '{{.State.Health.Status}}'` reads `unhealthy`,
|
|
159
|
+
`docker restart` the container.
|
|
160
|
+
- The acceptance script requires the 45-second stop timeout and that
|
|
161
|
+
healthcheck in the container's inspect evidence.
|
|
162
|
+
|
|
163
|
+
## Documentation
|
|
164
|
+
|
|
165
|
+
- **The pi skills filter is for @awebai/pi below 0.5.0, and @awebai/claude-skills stays out of OATS pi folders.**
|
|
166
|
+
- **Why:** @awebai/pi 0.5.0 bundles no skills. They now ship on their own in @awebai/claude-skills, which pi would load in every session that uses the folder.
|
|
167
|
+
- **`/oats-host-delivery`** (`oats.framework`): the pi step of channel delivery makes the extension's entry `{"source": "npm:@awebai/pi", "skills": []}` only below 0.5.0.
|
|
168
|
+
- **The getting-started onboarding:** it still sets the filter whatever the version, because it's harmless on 0.5.0.
|
|
169
|
+
- Both now say never to install @awebai/claude-skills in a pi folder that OATS homes use, because a home gets its skills from its capabilities. This matches oats.aweb 1.38.0, whose readiness warns `pi-extension-skills-loaded` only below 0.5.0 and adds `pi-skills-package-loaded`.
|
package/docs/schedules.md
CHANGED
|
@@ -31,6 +31,10 @@ while the machine slept are skipped, never replayed; there are no retries and
|
|
|
31
31
|
no queue. A schedule on a registered server keeps running while your laptop
|
|
32
32
|
sleeps.
|
|
33
33
|
|
|
34
|
+
A host with neither launchd nor a systemd user manager (a container) has no
|
|
35
|
+
timer: there `oats host run`, a foreground process, runs the same tick at
|
|
36
|
+
second 0 of every minute ([Without a host timer](#without-a-host-timer)).
|
|
37
|
+
|
|
34
38
|
The design is in the
|
|
35
39
|
[knowledge-operations design record](design/2026-09-26-okf-knowledge-operations.md#23-triggers)
|
|
36
40
|
(§2.3 and §2.3a).
|
|
@@ -41,7 +45,7 @@ The design is in the
|
|
|
41
45
|
| --- | --- |
|
|
42
46
|
| `<deployment>/oats-schedules.json` | This machine's local definitions, `{version: 1, jobs: {<id>: …}}`, local triggers included (`kind: "trigger"`). |
|
|
43
47
|
| `<deployment>/.agents/automations/snapshot.json` | The workspace definitions discovered from the members. |
|
|
44
|
-
| `<deployment>/.agents/schedules/` | Run state: `state.json` (last minute and recent runs per job), `triggers.json` (polls, pending events, fired keys) and one
|
|
48
|
+
| `<deployment>/.agents/schedules/` | Run state: `state.json` (last minute and recent runs per job), `triggers.json` (polls, pending events, fired keys) and one slot directory per running job, `locks/<id>/` with its record `owner.json`. |
|
|
45
49
|
| `~/.oats/schedules/registry.json` | The deployments this host ticks, `maxConcurrent` (absent: default 5 running scheduled jobs) and `triggersMaxConcurrent` (absent: no host cap on trigger-spawned live instances). The two caps are separate. |
|
|
46
50
|
|
|
47
51
|
One host lock, `~/.oats/schedules/host.lock`, serializes ticks, run-now,
|
|
@@ -71,6 +75,71 @@ A lock whose holder is gone and whose record cannot be taken over (a record
|
|
|
71
75
|
without the identifier a takeover needs) is reported the same way, with the
|
|
72
76
|
file that must be removed.
|
|
73
77
|
|
|
78
|
+
**A job's slot is never there without its record.** The slot a running job
|
|
79
|
+
holds against `maxConcurrent`, `.agents/schedules/locks/<id>/`, is no lock
|
|
80
|
+
between processes: the host lock serializes everything that takes or
|
|
81
|
+
releases it, and it stands for the job's run until that run's instance ends.
|
|
82
|
+
Its record is written in `.agents/schedules/.slot-<id>/`, which is then
|
|
83
|
+
renamed to the slot, and a release renames the slot back there before
|
|
84
|
+
removing it. A command killed while it takes or releases a slot leaves the
|
|
85
|
+
slot with its record or no slot, and at most that directory, which the next
|
|
86
|
+
take or release of the slot removes.
|
|
87
|
+
|
|
88
|
+
**A slot whose record cannot be read stops only its job.** A slot directory
|
|
89
|
+
without its record (which an earlier oats could leave), a record that does
|
|
90
|
+
not parse, or something else at the slot's path says nothing about whether
|
|
91
|
+
the run it stands for still runs. OATS never writes into it or removes it
|
|
92
|
+
for you. The tick reports that job `invalid`, with the error `the slot <path>
|
|
93
|
+
has no readable record; check oats schedule show <id>; once its last run is
|
|
94
|
+
not running, run oats schedule reconcile <id> --clear to release the slot`
|
|
95
|
+
(`E_SCHEDULE_INVALID`), and ticks the deployment's other jobs as usual; the
|
|
96
|
+
slot counts against `maxConcurrent` until it is released. `oats schedule
|
|
97
|
+
run <id>` refuses with the same words. `oats schedule reconcile <id>`
|
|
98
|
+
answers `reconciled: "unknown"` with that sentence as its `remedy` and
|
|
99
|
+
leaves the slot; once you have checked, `reconcile <id> --clear` releases
|
|
100
|
+
it (`reconciled: "cleared"`), and reconciles an attempt beside it as
|
|
101
|
+
`--clear` does any attempt. `oats doctor` lists the slot as a
|
|
102
|
+
`schedule-slot-unreadable` problem ([Unresolved attempts](#what-a-run-reports)).
|
|
103
|
+
|
|
104
|
+
**A slot whose schedule is not defined is held until a person releases it.**
|
|
105
|
+
A schedule that is gone can leave its slot behind, readable or not, and it may
|
|
106
|
+
stand for a run that is still going. A local schedule is gone when it is no
|
|
107
|
+
longer in `oats-schedules.json`. A workspace schedule is gone when the saved
|
|
108
|
+
automation snapshot says so: its member was read at a commit, the snapshot
|
|
109
|
+
has no problem of that member that could hide a schedule (a schedule file
|
|
110
|
+
that could not be read or parsed, which may carry any id, or a member that
|
|
111
|
+
could not be listed), and no schedule has its id. That is decided from the
|
|
112
|
+
snapshot as it was last saved: reconcile and doctor refresh nothing, and
|
|
113
|
+
both name the snapshot's time. A workspace schedule that is disabled,
|
|
114
|
+
untrusted or placed on another host still has its entry there: it is not
|
|
115
|
+
gone, and reconcile refuses it as before (`E_AUTOMATION_NOT_HERE`). Without a
|
|
116
|
+
snapshot nothing is gone.
|
|
117
|
+
|
|
118
|
+
No tick reads the slot of a schedule that is gone, and every tick counts it
|
|
119
|
+
against `maxConcurrent` until it is released. `oats schedule reconcile <id>`
|
|
120
|
+
answers `{schedule: null, reconciled: "unknown", remedy}` with what it found
|
|
121
|
+
(the slot, how the schedule is known to be gone, and the run its record
|
|
122
|
+
names: its due minute and, for a wake, the home of its instance; a spawn's or
|
|
123
|
+
a command's record names no instance) and changes nothing. Once you have
|
|
124
|
+
checked `oats status`, `reconcile <id> --clear` releases the slot, resolves a
|
|
125
|
+
retained launch attempt as cleared (as for a defined job) and removes the
|
|
126
|
+
job's state: `{schedule: null, reconciled: "cleared", cleared: [...]}`, which
|
|
127
|
+
lists `"slot"`, `"attempt"` and `"state"` as each was there. A schedule that is
|
|
128
|
+
gone with retained state and no slot is reconciled the same way: reconcile
|
|
129
|
+
answers that it has retained state (and a launch attempt with no recorded
|
|
130
|
+
result, when there is one) and points to `--clear`, which answers `cleared:
|
|
131
|
+
["attempt", "state"]`. `oats doctor` lists the slot as a
|
|
132
|
+
`schedule-slot-orphaned` problem, and the `schedule-unresolved` row of a
|
|
133
|
+
retained attempt names the same `reconcile <id> --clear`.
|
|
134
|
+
|
|
135
|
+
A workspace schedule that is absent from the snapshot but cannot be shown gone
|
|
136
|
+
stays refused (`E_SCHEDULE_UNKNOWN`), and doctor lists its slot as
|
|
137
|
+
`schedule-slot-orphaned` with the step that applies: when its member is not
|
|
138
|
+
in the snapshot (removed from the workspace, or not read), check `oats
|
|
139
|
+
status` and remove the slot by hand, at the path doctor names; when its
|
|
140
|
+
member has a schedule file that could not be read, fix that file and run
|
|
141
|
+
`oats automations refresh`.
|
|
142
|
+
|
|
74
143
|
## Kinds
|
|
75
144
|
|
|
76
145
|
Every definition carries `id`, `enabled`, `cron`, `tz` and `kind`. `cron` has
|
|
@@ -152,9 +221,9 @@ refuses the key on a trigger.
|
|
|
152
221
|
again only at due minutes, so a harness that keeps exiting is not restarted
|
|
153
222
|
in a loop. Unobservable or still starting: skipped, delivery kept pending.
|
|
154
223
|
Word wake messages so that receiving one again is harmless.
|
|
155
|
-
- **operation** `{…, operation, home}` — runs a provider operation
|
|
156
|
-
|
|
157
|
-
<layer>:<name> --home <home>`. The provider is whatever fills that layer
|
|
224
|
+
- **operation** `{…, operation, home}` — runs a provider operation
|
|
225
|
+
(`<layer>:<name>`, one the capability filling that layer declares) in the
|
|
226
|
+
instance at `home` through `oats operation run <layer>:<name> --home <home>`. The provider is whatever fills that layer
|
|
158
227
|
when the job runs. Tracking is that of a command job.
|
|
159
228
|
|
|
160
229
|
`--wake-every N` at spawn time means `*/N * * * *`: every 7 fires at :00, :07,
|
|
@@ -175,11 +244,11 @@ reports `gh.credentialSource` (`keyring`, `config`, `env:<VAR>`) and warns
|
|
|
175
244
|
when the timer cannot reach it.
|
|
176
245
|
|
|
177
246
|
```json
|
|
178
|
-
{ "id": "okf-
|
|
179
|
-
"description": "Review every
|
|
247
|
+
{ "id": "okf-proposal-review", "enabled": true, "kind": "trigger",
|
|
248
|
+
"description": "Review every knowledge proposal PR on the knowledge base",
|
|
180
249
|
"on": { "source": "github.pull_request", "repo": "github.com/acme/knowledge",
|
|
181
250
|
"events": ["opened", "reopened", "ready_for_review"],
|
|
182
|
-
"labels": ["okf-
|
|
251
|
+
"labels": ["okf-proposal"], "base": "main", "poll": "2m" },
|
|
183
252
|
"spawn": { "soul": "oats.okf/knowledge-maintainer", "purpose": "review-pr-{number}",
|
|
184
253
|
"task": "Review knowledge-base PR {repo}#{number}. Load knowledge-review first.",
|
|
185
254
|
"harness": "claude", "model": "opus" },
|
|
@@ -259,7 +328,7 @@ when the timer cannot reach it.
|
|
|
259
328
|
|
|
260
329
|
```sh
|
|
261
330
|
oats trigger add --file trigger.json [--description=<text>] # or:
|
|
262
|
-
oats trigger add --from oats.okf:
|
|
331
|
+
oats trigger add --from oats.okf:proposal-review --set repo=github.com/acme/knowledge [--id <id>] [--description=<text>]
|
|
263
332
|
oats trigger update <id> --description=<text> # the description only; --description= clears it
|
|
264
333
|
oats trigger list | show <id> | enable <id> | disable <id> | remove <id>
|
|
265
334
|
oats trigger test <id> # dry run: gh credentials, repo permissions, the soul, what WOULD fire
|
|
@@ -507,11 +576,11 @@ with the kind's suffix anywhere in the member (`.yml` works too), for example
|
|
|
507
576
|
`oats-package/`, `.git/` and `node_modules/` are never scanned.
|
|
508
577
|
|
|
509
578
|
```yaml
|
|
510
|
-
# <member>/oats-triggers/okf-
|
|
579
|
+
# <member>/oats-triggers/okf-proposal-review.yaml
|
|
511
580
|
kind: oats-trigger
|
|
512
581
|
schemaVersion: 1
|
|
513
|
-
description: Review every
|
|
514
|
-
from: oats.okf:
|
|
582
|
+
description: Review every knowledge proposal PR on the knowledge base
|
|
583
|
+
from: oats.okf:proposal-review # a package template at the locked commit, then its parameters
|
|
515
584
|
set: { repo: github.com/acme/knowledge }
|
|
516
585
|
runsOn: kb-bot-server # the host.name that runs it
|
|
517
586
|
owner: github.com/acme-kb-bot # the GitHub account it acts as
|
|
@@ -633,6 +702,7 @@ oats schedule host install # register this deployment and install the one
|
|
|
633
702
|
oats schedule host install --max-concurrent 3 --triggers-max-concurrent 2
|
|
634
703
|
oats schedule host install --max-concurrent default --triggers-max-concurrent none
|
|
635
704
|
oats schedule host install --print [--os darwin|linux] # what install would write; changes nothing
|
|
705
|
+
oats schedule host install --register-only # register this deployment and install no timer (oats host run ticks)
|
|
636
706
|
oats schedule host status | uninstall
|
|
637
707
|
oats spawn <agent> ... --wake-every 15 --wake-message "Anything new?" # or --wake-file spec.json
|
|
638
708
|
```
|
|
@@ -686,6 +756,25 @@ five. Correct it with `oats schedule host install --max-concurrent N` (or
|
|
|
686
756
|
An absent value still means five. Set caps through the CLI; do not edit the
|
|
687
757
|
registry by hand.
|
|
688
758
|
|
|
759
|
+
### Without a host timer
|
|
760
|
+
|
|
761
|
+
`oats schedule host install --register-only` records the deployment in the
|
|
762
|
+
host registry, with any caps given, and installs no unit. It asks neither
|
|
763
|
+
launchd nor systemd for anything, so it works where neither exists. It does
|
|
764
|
+
not go with `--print` (`E_BAD_ARGS`). Its answer is install's: `scheduler`
|
|
765
|
+
with `registered: true` and `installed: false`, and no warnings.
|
|
766
|
+
|
|
767
|
+
On such a host `oats host run` is the ticker
|
|
768
|
+
([desktop-cli-api.md](desktop-cli-api.md#the-host-run-oats-host-run)): each minute it
|
|
769
|
+
runs `oats schedule tick --host` for the scopes the registry lists, and with
|
|
770
|
+
none it ticks nothing and says so. It refuses to start while a host timer is
|
|
771
|
+
active (`E_HOST_RUN_TIMER_ACTIVE`), so a host has one ticker, never two.
|
|
772
|
+
With `--server`, `--register-only` is sent only to a destination that
|
|
773
|
+
advertises `schedule` and `schedule-host-register-only`. Any other is
|
|
774
|
+
refused with `E_REMOTE_INCOMPATIBLE` before anything is sent, because a
|
|
775
|
+
destination that does not know the option ignores it and installs a timer.
|
|
776
|
+
Upgrade OATS on the destination.
|
|
777
|
+
|
|
689
778
|
### The host timer's unit
|
|
690
779
|
|
|
691
780
|
The unit is a launchd user agent (`~/Library/LaunchAgents/ai.oats.schedule-tick.plist`,
|
|
@@ -842,9 +931,51 @@ schedule whose saved state supports reconciliation, `remedy` names
|
|
|
842
931
|
`oats schedule reconcile <id>`, with `--clear` for unproven command/operation
|
|
843
932
|
effects (check the roster and host by hand first), and `--dir <scope>` for
|
|
844
933
|
another deployment. Invalid or unsupported saved inputs instead receive a
|
|
845
|
-
warning to preserve state and inspect effects with the deployment owner.
|
|
934
|
+
warning to preserve state and inspect effects with the deployment owner. A
|
|
935
|
+
job whose slot has no readable record gets the slot's remedy below.
|
|
846
936
|
A warning never changes doctor's exit status.
|
|
847
937
|
|
|
938
|
+
`oats doctor` also lists each slot whose record cannot be read, in the same
|
|
939
|
+
deployments, as its own problem. The text form is `! schedule-slot-unreadable:
|
|
940
|
+
<message>` with the remedy on the next line; in `--json` it is a `problems[]`
|
|
941
|
+
item:
|
|
942
|
+
|
|
943
|
+
```text
|
|
944
|
+
{ code: "schedule-slot-unreadable", severity: "warning", scope, id, message, remedy }
|
|
945
|
+
```
|
|
946
|
+
|
|
947
|
+
`message` names the job and the slot's path; `remedy` is `check oats schedule
|
|
948
|
+
show <id>; once its last run is not running, run oats schedule reconcile <id>
|
|
949
|
+
--clear to release the slot`, with `--dir <scope>` on both commands for
|
|
950
|
+
another deployment. A workspace schedule that this host does not run
|
|
951
|
+
(disabled, untrusted, placed on another host, as the saved snapshot and
|
|
952
|
+
`oats-local.yaml` say offline), or that it cannot tell it runs, is refused by
|
|
953
|
+
reconcile here: its message says why, and its remedy is `once oats status
|
|
954
|
+
shows no run of schedule <id> here, remove the slot by hand: rm -r --
|
|
955
|
+
'<path>'`. No doctor row names a `--clear` that reconcile would refuse.
|
|
956
|
+
Doctor reads the slot as the tick does and changes nothing. A readable slot of a defined job, and no slot, are not listed.
|
|
957
|
+
|
|
958
|
+
A slot whose schedule is gone, readable or not, is listed as a
|
|
959
|
+
`schedule-slot-orphaned` problem instead, of the same shape (`! schedule-slot-orphaned:
|
|
960
|
+
<message>`, the remedy on the next line). Its message says how the schedule
|
|
961
|
+
is known gone (`which is not defined`, or `which as of <takenAt> is not in
|
|
962
|
+
the workspace (run oats automations refresh if that is stale)`) and what the
|
|
963
|
+
slot's record names (`has no readable record`, or `holds the run due
|
|
964
|
+
<minute> of the instance at <home>`, or `… of an instance its record does
|
|
965
|
+
not name`). Its remedy is `once oats status shows the instance at <home> is
|
|
966
|
+
not running, run oats schedule reconcile <id> --clear to release the slot`,
|
|
967
|
+
or, when the record names no instance, `once no run of schedule <id> is
|
|
968
|
+
running (oats status lists the instances it started), run oats schedule
|
|
969
|
+
reconcile <id> --clear to release the slot`. The `schedule-unresolved` row of
|
|
970
|
+
a gone workspace schedule's retained attempt names the same remedy. A
|
|
971
|
+
workspace schedule absent from the snapshot that cannot be shown gone is
|
|
972
|
+
listed as `schedule-slot-orphaned` too, with `which is not in the
|
|
973
|
+
workspace's snapshot of <takenAt>`, why, and its step: `check oats status for
|
|
974
|
+
a run of schedule <id>; once none is running, remove the slot by hand: rm -r
|
|
975
|
+
-- '<path>'` for a member not in the snapshot, `fix <file> in member
|
|
976
|
+
<member> and run oats automations refresh; doctor then says whether
|
|
977
|
+
schedule <id> is gone` for a file that could not be read.
|
|
978
|
+
|
|
848
979
|
Workspace guidance uses only validated local settings and the saved automation
|
|
849
980
|
snapshot. A known opt-out, missing saved definition, different assigned host or
|
|
850
981
|
absent trust explains why retained-state reconciliation is currently unavailable.
|
|
@@ -991,35 +1122,38 @@ more than that:
|
|
|
991
1122
|
fails, the spawn result still carries the instance receipt, plus
|
|
992
1123
|
`wakeScheduleError` and a warning.
|
|
993
1124
|
|
|
994
|
-
## Knowledge
|
|
1125
|
+
## Knowledge proposal review
|
|
995
1126
|
|
|
996
|
-
**oats.okf
|
|
997
|
-
|
|
998
|
-
|
|
999
|
-
|
|
1000
|
-
|
|
1001
|
-
and no spawn under memory pressure or below 8 GB available; otherwise defer
|
|
1002
|
-
and hand back the pending claims. Most checkpoints propose nothing. When the
|
|
1003
|
-
skill's gates pass, the instance directly spawns the package harvester:
|
|
1127
|
+
**oats.okf 6 schedules no knowledge job.** Its IMPORTANT inject and
|
|
1128
|
+
compulsory `okf-propose` skill give the duty to propose, not TASK.md. At each
|
|
1129
|
+
knowledge checkpoint an instance with that duty proposes its durable,
|
|
1130
|
+
non-duplicate claims itself, from its home, as one pull request on the
|
|
1131
|
+
knowledge base:
|
|
1004
1132
|
|
|
1005
1133
|
```sh
|
|
1006
|
-
oats
|
|
1134
|
+
oats okf propose --plan --slug <slug> # stages the proposal in the home
|
|
1135
|
+
oats okf propose --check --slug <slug> # the diff and its digest
|
|
1136
|
+
oats okf propose --apply --slug <slug> --digest <digest>
|
|
1007
1137
|
```
|
|
1008
1138
|
|
|
1009
|
-
|
|
1010
|
-
|
|
1011
|
-
|
|
1012
|
-
|
|
1013
|
-
|
|
1014
|
-
|
|
1015
|
-
keeps consultation while forbidding harvest of that soul's material.
|
|
1139
|
+
`--apply` pushes a create-only `okf-proposal/<date>-<id>` branch and opens
|
|
1140
|
+
one PR labelled `okf-proposal`; most checkpoints propose nothing. No worker
|
|
1141
|
+
is spawned, nobody waits for the PR, and retirement captures nothing. There
|
|
1142
|
+
is no host switch, per-source job or capture engine. The soul-only
|
|
1143
|
+
`knowledge: { harvest: off }` keeps consultation while giving that soul no
|
|
1144
|
+
duty to propose ([The soul's opt-out](knowledge.md#the-souls-opt-out)).
|
|
1016
1145
|
|
|
1017
|
-
**Review still uses a trigger.** Each
|
|
1146
|
+
**Review still uses a trigger.** Each proposal PR can be reviewed by
|
|
1018
1147
|
`oats.okf/knowledge-maintainer`, spawned from the package template
|
|
1019
|
-
`oats.okf:
|
|
1020
|
-
`oats trigger add --from oats.okf:
|
|
1021
|
-
|
|
1022
|
-
|
|
1148
|
+
`oats.okf:proposal-review`: a workspace trigger file or a local
|
|
1149
|
+
`oats trigger add --from oats.okf:proposal-review`. Through 6.x the template
|
|
1150
|
+
`oats.okf:harvest-review` watches only the 5.x label `okf-harvest`: keep it
|
|
1151
|
+
beside `proposal-review` only while a 5.x harvester may still open such a
|
|
1152
|
+
PR. These are PR-review triggers, not a knowledge scheduler or a kernel
|
|
1153
|
+
PR-opened capture hook.
|
|
1154
|
+
|
|
1155
|
+
A deployment moving from 5.x takes the hand steps in
|
|
1156
|
+
[Pin and select the package](knowledge.md#pin-and-select-the-package).
|
|
1023
1157
|
Deployments upgrading from 4.x must settle registered sources before
|
|
1024
1158
|
changing the pin, then use the 5.0 guard-exempt host-key cleanup before new
|
|
1025
1159
|
spawns. See the [5.0 cutover sequence](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters). Provider
|
package/docs/servers.md
CHANGED
|
@@ -425,7 +425,9 @@ Every routed ssh call carries these options, before `--` and the host:
|
|
|
425
425
|
failed: …`). When ssh never started on this machine, the `--json` envelope
|
|
426
426
|
says so with `error.details: {"sshStarted": false}`; without details, ssh
|
|
427
427
|
ran and the link failed
|
|
428
|
-
([desktop-cli-api.md](desktop-cli-api.md#ssh-failures-e_ssh)).
|
|
428
|
+
([desktop-cli-api.md](desktop-cli-api.md#ssh-failures-e_ssh)). A link that
|
|
429
|
+
fails under a routed spawn carries the decision and the key to run it
|
|
430
|
+
again with ([Run there](#run-there)).
|
|
429
431
|
|
|
430
432
|
## Run there
|
|
431
433
|
|
|
@@ -440,9 +442,27 @@ Arguments are quoted for the remote shell. Local files (`--task-file`,
|
|
|
440
442
|
`--wake-file`, a schedule or launch-configuration `--file`) are read here and
|
|
441
443
|
sent as text or on stdin, never as paths.
|
|
442
444
|
|
|
445
|
+
<a id="a-routed-spawns-task"></a>
|
|
446
|
+
**A routed spawn's task is on no command line, for a server that advertises
|
|
447
|
+
`spawn-task-stdin`.** The text of `--task` or of `--task-file` goes to such a
|
|
448
|
+
server on the standard input of the ssh session, to the server's preview and
|
|
449
|
+
to its spawn alike, and the remote command carries `--task-file -` in its
|
|
450
|
+
place: the text is in the arguments of neither the local `ssh` process nor
|
|
451
|
+
the server's `oats`, where every user of either machine could read it in the
|
|
452
|
+
process list. A server that does not advertise `spawn-task-stdin` cannot read
|
|
453
|
+
it there, and gets it as an argument of the remote command: the spawn
|
|
454
|
+
succeeds, the task is readable in both process lists while it runs (this
|
|
455
|
+
machine's, in the `ssh` command, and the server's), and the answer carries
|
|
456
|
+
one warning that says so: `remote oats <version> at <host> does not
|
|
457
|
+
advertise spawn-task-stdin, so the task was passed as an argument, visible
|
|
458
|
+
in this machine's process list (the ssh command) and the host's while the
|
|
459
|
+
spawn runs; upgrade the host`. Upgrade OATS on the server to keep tasks off
|
|
460
|
+
both command lines. A `--wake-message` and a
|
|
461
|
+
schedule's spec still travel as arguments.
|
|
462
|
+
|
|
443
463
|
| Command | Where it runs | The server must advertise |
|
|
444
464
|
|---|---|---|
|
|
445
|
-
| `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-name` for `--name`; `spawn-preview-2` for `--preview`; `spawn-suggest-name` for `--suggest-name` on a preview, `spawn-apply-suggest-name` on an apply; `instance-background` for `--background` or `--no-background`; `instance-same-work` for `--same-work` |
|
|
465
|
+
| `spawn` | registered workspace | the requested harness, backend and yolo option; `launch-config` for `--launch-config`; `schedule` for a wake schedule; `spawn-name` for `--name`; `spawn-task-stdin` for a `--task` or `--task-file` kept off the command line (without it: the task as an argument, and a warning; [a routed spawn's task](#a-routed-spawns-task)); `spawn-preview-2` for `--preview`; `spawn-preview-2`, `spawn-apply-2` and `spawn-idempotency-2` for a spawn bound to its preview and a key (without them: one call and a warning); `spawn-suggest-name` for `--suggest-name` on a preview, `spawn-apply-suggest-name` on an apply; `instance-background` for `--background` or `--no-background`; `instance-same-work` for `--same-work` |
|
|
446
466
|
| `status` | registered workspace | |
|
|
447
467
|
| `retire` | the instance's home | `retire-home` to retire by exact home |
|
|
448
468
|
| `session inspect`, `session attach` | the instance's home | `session`; `session-attach-detach-key` for `attach --detach-key`; `session-attach-no-status-line` for `attach --no-status-line`, which a host without it ignores |
|
|
@@ -472,6 +492,44 @@ checked against the harness it would use (the flag, or the soul's default as
|
|
|
472
492
|
the remote roster reports it). A host that advertises no harness list is
|
|
473
493
|
assumed to run only pi and claude, on tmux, with no launch options.
|
|
474
494
|
|
|
495
|
+
**A routed spawn.** `oats spawn <soul> --server <id>` runs the spawn's checks
|
|
496
|
+
here (`E_ROUTE_CHANGED`, `E_ROUTE_EXISTS`, the harness and options), then
|
|
497
|
+
asks the server's kernel in two calls:
|
|
498
|
+
|
|
499
|
+
1. its preview (`spawn … --preview`), which decides the name and everything
|
|
500
|
+
else and creates nothing;
|
|
501
|
+
2. the spawn itself, bound to that decision and to a key made for this
|
|
502
|
+
request (`--expect-decision <revision> --idempotency-key <key>`).
|
|
503
|
+
|
|
504
|
+
The answer is the server's keyed answer (`decision`, `replayed`, `wake`
|
|
505
|
+
beside the rest) plus `server`, `target` and `snapshot`, and the route is
|
|
506
|
+
saved. With `--suggest-name` the preview chooses the name and the spawn
|
|
507
|
+
carries it as `--name`; the answer keeps the preview's `naming`. This needs
|
|
508
|
+
the server's `spawn-suggest-name` and `spawn-name` too.
|
|
509
|
+
|
|
510
|
+
- **A link that fails under the second call** (a lost connection, a
|
|
511
|
+
timeout) is `E_SSH`, and the server may have started the spawn. The
|
|
512
|
+
message ends with the fix, and `--json` carries it:
|
|
513
|
+
`error.details: {decision, idempotencyKey, fix}`. Run the same spawn again
|
|
514
|
+
with `--expect-decision <decision.revision> --idempotency-key
|
|
515
|
+
<idempotencyKey>` (and `--name <decision.instance>` in place of
|
|
516
|
+
`--suggest-name`): the server answers the instance the first attempt
|
|
517
|
+
created (`replayed: true`), or creates it, and the route is saved. An
|
|
518
|
+
attempt still running there answers `E_SPAWN_INCOMPLETE`, naming the
|
|
519
|
+
instance. Run again without the two flags, the spawn is a separate request
|
|
520
|
+
and may create a second instance.
|
|
521
|
+
- **A name taken between the two calls** (another spawn on the server took
|
|
522
|
+
it) is `E_DECISION_STALE`; nothing was created. Run the spawn again.
|
|
523
|
+
- **A spawn that brings `--expect-decision` or `--idempotency-key`** travels
|
|
524
|
+
as given, in one call: the caller previewed (`--server <id> --preview`) and
|
|
525
|
+
holds the key.
|
|
526
|
+
- **A server that does not advertise `spawn-preview-2`, `spawn-apply-2` and
|
|
527
|
+
`spawn-idempotency-2`** gets the spawn in one call, as given, and the
|
|
528
|
+
answer carries a warning: if the link drops while it spawns, the spawn
|
|
529
|
+
cannot be retried safely, since the instance may exist there and a second
|
|
530
|
+
run would create another. Check `oats status --server <id>` before running
|
|
531
|
+
it again, or upgrade OATS there.
|
|
532
|
+
|
|
475
533
|
**A routed preview.** `oats spawn <soul> --server <id> --preview` runs the
|
|
476
534
|
spawn's checks here (`E_ROUTE_CHANGED`, `E_ROUTE_EXISTS`, the harness and
|
|
477
535
|
options), then asks the server's kernel for its preview. It prints the local
|
|
@@ -611,7 +669,10 @@ It relays the host's viewer fact the same way, `probe.sessionViewer`
|
|
|
611
669
|
host's viewer takes `C-b [`, or `null` when unknown.
|
|
612
670
|
|
|
613
671
|
**Harvest** runs the knowledge capability's `okf harvest --json` in the
|
|
614
|
-
instance's saved home on the server and relays its envelope.
|
|
672
|
+
instance's saved home on the server and relays its envelope. oats.okf 5.0
|
|
673
|
+
and later refuse that command with `E_REMOVED`: an instance proposes its
|
|
674
|
+
knowledge from its own home with `oats okf propose`
|
|
675
|
+
([the flow](knowledge.md#the-flow)).
|
|
615
676
|
|
|
616
677
|
## What this machine keeps
|
|
617
678
|
|