@awebai/oats 0.48.0 → 0.50.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/bin/oats.mjs +326 -28
- package/docs/capabilities.md +425 -8
- package/docs/capability-manifest.schema.json +60 -5
- package/docs/configuration.md +103 -0
- package/docs/desktop-cli-api.md +542 -47
- package/docs/desktop.md +85 -5
- package/docs/execution-targets.md +50 -9
- package/docs/implementation.md +74 -1
- package/docs/integrations.md +7 -5
- package/docs/knowledge.md +167 -197
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +28 -14
- package/docs/release-lane.md +41 -0
- package/docs/release-notes/v0.49.0.md +770 -0
- package/docs/release-notes/v0.50.0.md +279 -0
- package/docs/schedules.md +289 -53
- package/docs/servers.md +7 -0
- package/docs/souls-and-instances.md +450 -60
- package/docs/workspaces.md +3 -3
- package/injects/work-checkout.md +17 -11
- package/injects/work-worktree.md +19 -13
- package/lib/capability-contract.mjs +100 -11
- package/lib/capability-show.mjs +18 -2
- package/lib/core.mjs +1374 -394
- package/lib/instance-events.mjs +9 -10
- package/lib/instance-git.mjs +19 -10
- package/lib/instance-inspect.mjs +58 -18
- package/lib/instance-lifecycle.mjs +106 -16
- package/lib/instance-resolution.mjs +15 -3
- package/lib/launch-prompt-policy.mjs +17 -3
- package/lib/packages.mjs +1 -0
- package/lib/real-path.mjs +27 -0
- package/lib/refused-text.mjs +17 -0
- package/lib/resolve.mjs +4 -4
- package/lib/retained-after-retire.mjs +387 -0
- package/lib/retire-output.mjs +6 -1
- package/lib/schedule.mjs +9 -2
- package/lib/servers.mjs +32 -6
- package/lib/tree-copy.mjs +18 -7
- package/lib/trigger-sources.mjs +234 -0
- package/lib/triggers.mjs +705 -108
- package/lib/workspace.mjs +20 -5
- package/lib/worktree-hooks.mjs +392 -0
- package/lib/worktree.mjs +655 -0
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +1 -1
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
# OATS 0.50.0
|
|
2
|
+
|
|
3
|
+
2026-10-10
|
|
4
|
+
|
|
5
|
+
## Added
|
|
6
|
+
|
|
7
|
+
- **`oats doctor` lists what retires left behind (#703, part 2a).** These are
|
|
8
|
+
information lines only, with no new key. Doctor prints one
|
|
9
|
+
`retained-recovery:` line per recovery copy under each instances directory's
|
|
10
|
+
`.oats-retirement/recovery/`. Each line gives the path, the instance, `phase`
|
|
11
|
+
and `classes` from `recovery.json`, the size and whether `after-hooks/` is
|
|
12
|
+
there. A copy whose `recovery.json` is missing or unreadable is listed and
|
|
13
|
+
says so. Doctor also prints one `retained-worktree:` line per retained
|
|
14
|
+
worktree under `.agents/worktrees/<repo>/`, giving its repository, its
|
|
15
|
+
branch (or detached commit), and whether it is clean, with the uncommitted
|
|
16
|
+
classes when it isn't. Each line ends with the reachability fact for the
|
|
17
|
+
HEAD commit: whether a ref of the source repository other than the tree's
|
|
18
|
+
own branch reaches it, or how many commits no other ref reaches. A
|
|
19
|
+
recovery line also names a retained worktree on its branch. These are
|
|
20
|
+
facts to decide with, never "safe to delete". Each kind starts with a line
|
|
21
|
+
giving its total, then at most 50 items, then `… and N more`. In
|
|
22
|
+
`oats doctor --json` they are elements of the existing `information[]`, one
|
|
23
|
+
line each. The reads are read-only and run Git without helpers, so doctor
|
|
24
|
+
refreshes no index and follows no link. It doesn't ask for the status of a
|
|
25
|
+
repository that configures a content filter, and never enters a
|
|
26
|
+
submodule's work tree; the line says so. See [After a retire: inspect,
|
|
27
|
+
restore, dispose](../souls-and-instances.md#after-a-retire-inspect-restore-dispose).
|
|
28
|
+
|
|
29
|
+
- **Capability-declared trigger sources, feature `trigger-sources` (#669).**
|
|
30
|
+
A trigger can now watch more than GitHub pull requests. A capability
|
|
31
|
+
declares **trigger sources** in its manifest (`triggerSources`): each is
|
|
32
|
+
one of its own commands that, at each poll, lists the events due now. A
|
|
33
|
+
trigger names one as `on.source: "<capability>:<source>"`, with `on:
|
|
34
|
+
{ source, params?, events, poll? }`, and the kernel keeps everything after
|
|
35
|
+
the list on the same pipeline `github.pull_request` runs on: keys,
|
|
36
|
+
at-least-once recording, pending events, concurrency by subject, the
|
|
37
|
+
instance name, the event file and the spawn. Templates may name
|
|
38
|
+
`{trigger} {source} {subject} {event} {key} {url} {fields.<name>}`, and the
|
|
39
|
+
default purpose is `{trigger}-{subject}`; a `github.pull_request` template
|
|
40
|
+
may now also name `{subject}` and `{key}`. What a trigger means is checked
|
|
41
|
+
against the capability its soul composes at `trigger add`, at every poll
|
|
42
|
+
(before the source runs) and by `trigger test`: a failure is
|
|
43
|
+
`E_TRIGGER_SOURCE {capability, source, pointer?}` or
|
|
44
|
+
`E_TRIGGER_INVALID {field}`, and a poll that finds one shows it as the
|
|
45
|
+
trigger's `invalid: {code, message, field?, at}` in `list` and `status`.
|
|
46
|
+
A param value carrying a control, bidi or invisible character is refused
|
|
47
|
+
(`E_TRIGGER_INVALID`, `on.params.<name>`), and a stored one is printed by
|
|
48
|
+
`trigger list`, `status` and `show` with those characters replaced or
|
|
49
|
+
escaped.
|
|
50
|
+
- **The wire.** One JSON request on stdin, exactly one JSON answer on
|
|
51
|
+
stdout, killed at 30 s, in the environment a `readiness --soul` check
|
|
52
|
+
gets: ambient `OATS_*`, `OAS_*` and `PI_*` removed, no instance, no
|
|
53
|
+
credential from the kernel. A wire failure is `E_TRIGGER_POLL` with
|
|
54
|
+
`details.cause` (`exit`, `result`, `too-many-events`, `timeout`,
|
|
55
|
+
`refused`, `resolution`), records nothing and drops nothing. Each event
|
|
56
|
+
is checked alone (key, subject, event, an `https:` `url` on one of the
|
|
57
|
+
manifest's `urlHosts`, declared `fields`); an invalid one is dropped
|
|
58
|
+
alone and listed in `invalidEvents`. A `url` must be printable ASCII
|
|
59
|
+
with no space as written. A field value longer than 200 characters, or
|
|
60
|
+
carrying a control, bidi or invisible character, is invalid whatever its
|
|
61
|
+
pattern admits. The source's own text (a skipped item's `why`, a refusal's code and message) is capped, has every control,
|
|
62
|
+
bidi and invisible character replaced with U+FFFD, is never composed into
|
|
63
|
+
a task, and is printed only under `source says:`.
|
|
64
|
+
- **How a pending event ends.** By the current state: a good poll that no
|
|
65
|
+
longer lists a pending key drops it; a failed poll drops nothing.
|
|
66
|
+
Retention keeps 500 fired keys per trigger as before, but never evicts a
|
|
67
|
+
key the last good poll listed.
|
|
68
|
+
- **The tick stays inside its minute.** Capability-source polls run after
|
|
69
|
+
the schedules, most overdue first across every deployment the host
|
|
70
|
+
ticks, and only while they can end within 50
|
|
71
|
+
s of the tick's start; the rest are `poll-deferred` and go first next
|
|
72
|
+
tick, so no schedule is missed because of them.
|
|
73
|
+
- **`oats trigger poll <id> --run-source [--max-age <s>]`**, a new read
|
|
74
|
+
verb (on the `--max-age` allow-list), runs a trigger's source once and
|
|
75
|
+
records nothing. It and `oats trigger test <id> --run-source` **execute
|
|
76
|
+
the capability's source command**: "read verb" means records nothing,
|
|
77
|
+
not runs no provider code.
|
|
78
|
+
- **A manual run takes `--run-source`.** Without it, `trigger test` and
|
|
79
|
+
`trigger poll` of a capability source's trigger are refused with
|
|
80
|
+
`E_TRIGGER_SOURCE_RUN` (`details: {capability, source, flag}`, a
|
|
81
|
+
non-zero exit, the command to run again in the message): nothing of the
|
|
82
|
+
capability has executed and nothing has been written. A definition that
|
|
83
|
+
is invalid or whose meaning fails answers that first, flag or no flag.
|
|
84
|
+
The flag is caller intent, never trust consent: with it both run the
|
|
85
|
+
source whatever this host's `automations.trust` and the trigger's
|
|
86
|
+
`runsOn` say, which gate the host tick exactly as before (the tick
|
|
87
|
+
passes the flag to its own child). On a `github.pull_request` trigger
|
|
88
|
+
the flag is accepted and inert. `test` names the placement in `problems`
|
|
89
|
+
("run manually with --run-source; the tick will not run it here: …") and
|
|
90
|
+
always warns that the source's credential may not be visible to the host
|
|
91
|
+
timer.
|
|
92
|
+
- **Contained.** A malformed `triggerSources` never refuses the
|
|
93
|
+
capability: spawn, preview, readiness, discovery and the lock ignore it.
|
|
94
|
+
It is validated where a source is used, per source, and `oats
|
|
95
|
+
capabilities show --json` adds `triggerSources` as declared and
|
|
96
|
+
`triggerSourceProblems`. A provider declaring `triggerSources` does not
|
|
97
|
+
need to raise `compatibility.oats`: every workspace-model kernel ignores
|
|
98
|
+
the key, and only the host that runs a trigger naming the source needs
|
|
99
|
+
this release. An older kernel reading the same deployment refuses such a
|
|
100
|
+
trigger with `on.params: unknown key`, not with a message about
|
|
101
|
+
`on.source`: `trigger add` stores `on.params` (`{}` when none is given),
|
|
102
|
+
and that kernel checks the keys of `on` first.
|
|
103
|
+
- **Schema tooling.** Until this release the published
|
|
104
|
+
`docs/capability-manifest.schema.json` is closed at the top level
|
|
105
|
+
(`additionalProperties: false`), so any tool that validates a manifest
|
|
106
|
+
against an older copy of the schema flags `triggerSources`: this
|
|
107
|
+
repository's own `validate-project`, the package dry-run checks, a
|
|
108
|
+
provider's CI that pins the schema. The runtime ignores the key;
|
|
109
|
+
schema-validating tooling does not. Validate against this release's
|
|
110
|
+
schema, or declare the key once your tooling uses it.
|
|
111
|
+
- **Output keys are additive and `triggerApi` stays 1.** On a capability
|
|
112
|
+
source's rows only (absent, not `null`, on a `github.pull_request` row,
|
|
113
|
+
whose outputs are unchanged): `status` gains `source`, `invalidEvents`,
|
|
114
|
+
`skipped` and `invalid`, with `lastPoll` counting `events`,
|
|
115
|
+
`invalidEvents`, `skipped` and `filtered` (or `{ok: false, cause, error,
|
|
116
|
+
source?}`); `test` gains `source`, with `repo: null`; `instance.json.trigger`
|
|
117
|
+
gains `fields`, with `repo` and `number` `null`. Readers tell rows apart
|
|
118
|
+
by `on.source` and gate on `trigger-sources`.
|
|
119
|
+
See [schedules.md](../schedules.md#capability-sources),
|
|
120
|
+
[capabilities.md](../capabilities.md#trigger-sources-triggersources) and
|
|
121
|
+
[desktop-cli-api.md](../desktop-cli-api.md#oats-trigger).
|
|
122
|
+
|
|
123
|
+
- **Desktop: capability trigger sources (#669, #802).** With an OATS that
|
|
124
|
+
declares `trigger-sources`, a trigger that takes its events from a
|
|
125
|
+
capability's source shows which source it is and what the trigger passes
|
|
126
|
+
to it, what the source's last poll found or why it failed, and which
|
|
127
|
+
events OATS refused or the source skipped. A capability's page lists the
|
|
128
|
+
trigger sources it declares. Text from a source, from a trigger's file or
|
|
129
|
+
from a capability's manifest is shown as a quote that says whose it is,
|
|
130
|
+
never as the Desktop's own words, and never as a link or a button.
|
|
131
|
+
**Test** on such a trigger runs the capability's source command on this
|
|
132
|
+
computer, so it is no longer one click: it first shows what will run, on
|
|
133
|
+
which computer and with which parameters, and runs it once when you press
|
|
134
|
+
**Run test**. Opening that confirmation runs nothing. Testing records
|
|
135
|
+
nothing, spawns nothing and does not trust or start the trigger.
|
|
136
|
+
`github.pull_request` triggers keep their one-click Test. With an older
|
|
137
|
+
OATS nothing changes.
|
|
138
|
+
|
|
139
|
+
## Changed
|
|
140
|
+
|
|
141
|
+
- **The Desktop accepts OATS CLIs `>=0.25.8 <0.51.0`.** The compatibility band
|
|
142
|
+
admits 0.50. Upgrade the CLI and the Desktop together: a 0.49.0 Desktop
|
|
143
|
+
refuses a 0.50.0 CLI. The Desktop's informed Test on a capability source's
|
|
144
|
+
trigger is gated on feature `trigger-sources`; the other feature gates are
|
|
145
|
+
unchanged.
|
|
146
|
+
|
|
147
|
+
- **The workspace pins oats.aweb 1.24.0** (tag on a7d976d4). Retire's
|
|
148
|
+
recovery copy no longer keeps an instance's aweb private keys, and retire
|
|
149
|
+
exits nonzero when leaving a joined team fails (except `team_not_hosted`), so
|
|
150
|
+
the home and the key that can still leave the team are kept. Readiness and
|
|
151
|
+
an approved Claude channel launch read the machine's Claude Code managed
|
|
152
|
+
settings and warn whether they admit the aweb channel plugin; the skill
|
|
153
|
+
documents the approved channel route as the recommended unattended setup.
|
|
154
|
+
The package's OATS floor rises to `>=0.42.0`. Homes spawned before this
|
|
155
|
+
version keep what they were spawned with; deployments adopt it with
|
|
156
|
+
`oats sync`.
|
|
157
|
+
|
|
158
|
+
- **The official catalog and `mirrors/oats-aweb` carry oats.aweb 1.24.0.** The
|
|
159
|
+
catalog's ref is `v1.24.0`, and the mirror is the package at that tag
|
|
160
|
+
(a7d976d4), byte for byte, so the workspace pin, the catalog and the mirror
|
|
161
|
+
agree.
|
|
162
|
+
|
|
163
|
+
- **oats.framework 1.9.0: oats.core 2.5.0 and oats.setup 2.5.0.** Instruction
|
|
164
|
+
text only; no kernel, schema or provider contract changes. It also carries
|
|
165
|
+
the skill text for 0.49.0's worktree commands and trigger names, which
|
|
166
|
+
0.49.0 shipped in the kernel while the package stayed at 1.8.0. The
|
|
167
|
+
official catalog and the workspace pin `oats-framework/v1.9.0`; deployments
|
|
168
|
+
adopt it with `oats sync`, and homes spawned before keep the skills they
|
|
169
|
+
were spawned with.
|
|
170
|
+
- **oats.core 2.5.0:** `oats-operate` covers the extra trees an instance
|
|
171
|
+
makes in its home with `oats worktree add|remove` (from OATS 0.49.0,
|
|
172
|
+
#801), that retiring an instance stops its recorded children first
|
|
173
|
+
(#782), what `oats doctor` lists of what retires left (#836), and the
|
|
174
|
+
event a triggered run reads: its `subject` (#798) and an event from a
|
|
175
|
+
capability's trigger source (#845).
|
|
176
|
+
- **oats.setup 2.5.0:** `oats-automations` covers triggers on a
|
|
177
|
+
capability's source, with `--run-source` for trying one by hand (OATS
|
|
178
|
+
0.50.0, #845), and how trigger instance names are cut to fit (from OATS
|
|
179
|
+
0.49.0, #798). `oats-workspace-config` gains the host step "Claude
|
|
180
|
+
channel delivery (approved route)", and `oats-onboarding` points to it
|
|
181
|
+
(#844).
|
|
182
|
+
- Both skills name the kernel version in which each of these starts, so
|
|
183
|
+
the package's floors do not move.
|
|
184
|
+
- A kernel release whose pull requests touched `oats-package/` now ships a
|
|
185
|
+
framework release with it:
|
|
186
|
+
[release-lane.md](../release-lane.md#releasing-oatsframework).
|
|
187
|
+
|
|
188
|
+
## Fixed
|
|
189
|
+
|
|
190
|
+
- **Retire: a worktree on a long branch is re-homed instead of refused
|
|
191
|
+
(#821).** A retire keeps a worktree (`work/`, or an extra `.work-*` tree) by
|
|
192
|
+
moving it to `<deployment>/.agents/worktrees/<repo>/<leaf>`, the leaf being
|
|
193
|
+
the whole branch name as one path component. A branch whose flattened name
|
|
194
|
+
went over NAME_MAX made `git worktree move` fail with ENAMETOOLONG. The retire
|
|
195
|
+
then refused with `E_WORK_PRESERVATION_FAILED`, until the branch was renamed
|
|
196
|
+
or the worktree discarded with `--discard-worktree`. The leaf is now at most 231 bytes before its `-N`. A
|
|
197
|
+
longer one is cut, its trailing `-` trimmed, and followed by `-` and 6 hex of
|
|
198
|
+
the SHA-256 of the full branch name, so it stays readable and unique per
|
|
199
|
+
branch. A leaf that already fits is unchanged, and the retire plan's
|
|
200
|
+
`movedTo` names the same path the retire uses
|
|
201
|
+
([souls-and-instances.md](../souls-and-instances.md#extra-trees-at-retire)).
|
|
202
|
+
|
|
203
|
+
- **Retire: a failed recovery copy is cleaned up even when a read-only
|
|
204
|
+
directory in it has a name that isn't UTF-8 (#827).** When a recovery copy
|
|
205
|
+
fails, the retire makes each directory of its staging copy writable and
|
|
206
|
+
removes it. It listed names as text, so it couldn't reach a read-only
|
|
207
|
+
directory (a Go module cache, `0555`) whose name isn't valid UTF-8, and the
|
|
208
|
+
staging directory was left in recovery storage. The refusal was still the
|
|
209
|
+
original `E_WORK_PRESERVATION_FAILED` and named the leftover to remove by
|
|
210
|
+
hand. Nothing was lost. Names are now listed and joined as bytes, as the
|
|
211
|
+
copier writes them, and the staging directory is removed. The refusal text is
|
|
212
|
+
unchanged.
|
|
213
|
+
|
|
214
|
+
- **The process scan reads `/proc` on Linux, and doctor names a host with no
|
|
215
|
+
scan (#625).** Whether a live process works in an instance home came only
|
|
216
|
+
from `lsof`, which many Linux hosts lack. There retire refused whenever it
|
|
217
|
+
needed the scan (a home without its session receipt, a missing recorded
|
|
218
|
+
tmux socket, a Herdr home), and nothing said why before the refusal. Now
|
|
219
|
+
the scan reads `/proc` on Linux (each process's `cwd` link, `comm` and
|
|
220
|
+
`stat`) and runs `lsof` elsewhere, as before; the answer is unchanged: a
|
|
221
|
+
pid and a program name, never an argument list. A process that ends during
|
|
222
|
+
the scan is skipped. A `/proc` that cannot be read fails the scan, never
|
|
223
|
+
answers "none". `oats doctor` (text, and `--json` in `information`, no new
|
|
224
|
+
key) adds a `process-scan-unavailable` line only on a host with neither,
|
|
225
|
+
saying what it blocks and to install `lsof`. A refusal for a missing `lsof`
|
|
226
|
+
now says to install it. The stated limit is unchanged: neither mechanism
|
|
227
|
+
sees a process this user may not inspect (another user's, or a
|
|
228
|
+
non-dumpable one such as `ssh-agent`), so such a process working in a home
|
|
229
|
+
does not stop a retire; refusing whenever one exists would refuse on every
|
|
230
|
+
host. The harness OATS launches runs as the user and is seen. See
|
|
231
|
+
[souls and instances](../souls-and-instances.md#the-process-scan).
|
|
232
|
+
|
|
233
|
+
- **A tmux server whose socket file was removed no longer reads as stopped
|
|
234
|
+
(#624).** A tmux server keeps running when its socket file is removed, and
|
|
235
|
+
tmux then answers as it does after a reboot (`No such file or directory`).
|
|
236
|
+
`oats status` showed such an instance as not running, `oats session
|
|
237
|
+
start`/`restart` created a second server at the recorded socket path and
|
|
238
|
+
launched a second harness in the same home, and `oats instance stop`
|
|
239
|
+
reported it idle. Now a missing socket file counts as stopped only when no
|
|
240
|
+
process works in the home, as retire already required (#622). Otherwise,
|
|
241
|
+
or when the process scan cannot run, status shows the row `running: null`,
|
|
242
|
+
`runtimeState: "unreachable"` with a `runtimeError` that names the
|
|
243
|
+
processes (existing values), start and restart refuse with
|
|
244
|
+
`E_SESSION_UNKNOWN` and create nothing, and stop refuses with
|
|
245
|
+
`E_SESSION_UNAVAILABLE`. Retire, which already scanned, now also scans
|
|
246
|
+
when an older tmux words a missing socket file as `failed to connect to
|
|
247
|
+
server: No such file or directory`; it took that as stopped. The message
|
|
248
|
+
names tmux's own remedy: the server
|
|
249
|
+
recreates its socket file when its process receives `SIGUSR1`. OATS never
|
|
250
|
+
sends it. A socket file that no server listens on is still stopped, with
|
|
251
|
+
no scan, and after a reboot (no process in the home) nothing changes. Any
|
|
252
|
+
process working in the home blocks start and stop while the socket file
|
|
253
|
+
is missing, a shell left in that directory included; the message names its
|
|
254
|
+
pid and program. See [Sessions](../execution-targets.md#missing-socket).
|
|
255
|
+
|
|
256
|
+
## Documentation
|
|
257
|
+
|
|
258
|
+
- **Claude channel delivery: the approved route, as a host setup step.**
|
|
259
|
+
Claude seats on aweb channel delivery no longer need to stop at Claude's
|
|
260
|
+
“WARNING: Loading development channels” prompt. With the `oats.aweb` setting
|
|
261
|
+
`claudeChannelMode: approved` (host-only) and `delivery: channel`, Claude
|
|
262
|
+
starts with `--channels plugin:aweb-channel@awebai-marketplace` and admits
|
|
263
|
+
the plugin when a root-owned managed-settings file on the machine lists it
|
|
264
|
+
(`/etc/claude-code/managed-settings.json` on Linux,
|
|
265
|
+
`/Library/Application Support/ClaudeCode/managed-settings.json` on macOS,
|
|
266
|
+
with `channelsEnabled: true` and the `aweb-channel` /
|
|
267
|
+
`awebai-marketplace` entry in `allowedChannelPlugins`). It does not depend
|
|
268
|
+
on the Claude version and needs no launch-prompt consent. A human admin
|
|
269
|
+
with sudo writes that file; OATS never does. Setting `allowedChannelPlugins`
|
|
270
|
+
replaces Anthropic's default channel allowlist on the host, and on an
|
|
271
|
+
account governed by server-managed settings or MDM the file is ignored (the
|
|
272
|
+
organization admin sets the keys there). Existing homes keep the mode they
|
|
273
|
+
were spawned with: respawn one to adopt the route. The contract is
|
|
274
|
+
[Claude channel delivery: the approved route](../configuration.md#claude-channel-delivery-the-approved-route);
|
|
275
|
+
the operator's ordered steps, with the banner checks, are the `oats.setup`
|
|
276
|
+
host step “Claude channel delivery (approved route)” in
|
|
277
|
+
`/oats-workspace-config`, which also names the file in its
|
|
278
|
+
where-each-fact-lives table; `/oats-onboarding` card 4 calls the step. No
|
|
279
|
+
kernel or CLI behaviour changes.
|