@awebai/oats 0.49.0 → 0.51.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 +150 -34
- package/docs/capabilities.md +172 -2
- package/docs/capability-manifest.schema.json +42 -0
- package/docs/configuration.md +97 -0
- package/docs/desktop-cli-api.md +268 -22
- package/docs/desktop.md +13 -0
- package/docs/execution-targets.md +120 -9
- package/docs/implementation.md +26 -6
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +20 -7
- 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.50.0.md +279 -0
- package/docs/release-notes/v0.51.0.md +156 -0
- package/docs/schedules.md +228 -15
- package/docs/servers.md +21 -2
- package/docs/souls-and-instances.md +92 -8
- package/docs/workspaces.md +2 -2
- package/lib/capability-show.mjs +14 -1
- package/lib/claim.mjs +126 -0
- package/lib/core.mjs +428 -102
- 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/servers.mjs +20 -4
- package/lib/session-viewer.mjs +87 -10
- package/lib/trigger-sources.mjs +234 -0
- package/lib/triggers.mjs +521 -60
- package/lib/worktree-hooks.mjs +24 -9
- package/lib/worktree.mjs +14 -86
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/skills/oats-getting-started/SKILL.md +1 -1
|
@@ -248,6 +248,48 @@
|
|
|
248
248
|
}
|
|
249
249
|
}
|
|
250
250
|
},
|
|
251
|
+
"triggerSources": {
|
|
252
|
+
"description": "Trigger sources (#669): each a command of this capability that, at each poll, lists the events due now; a trigger names one as on.source \"<capability>:<source>\". Validated only where a source is used (trigger add, a poll, trigger test and trigger poll), never when the capability loads: a malformed declaration fails the triggers naming it (E_TRIGGER_SOURCE) and nothing else. Checked at use only, not by this schema: every pattern compiles; command names a key of commands; a parameter default matches its pattern. A pattern is ECMA-262 with the u flag, matched anchored as ^(?:…)$; the default parameter value pattern is ^[A-Za-z0-9._/:@ ,*-]{0,200}$ and the default field pattern ^[A-Za-z0-9._/:@-]{1,200}$. Whatever its pattern admits, an event's field value is at most 200 code points and carries no control, bidi, invisible or tag character.",
|
|
253
|
+
"type": "object",
|
|
254
|
+
"maxProperties": 16,
|
|
255
|
+
"propertyNames": { "pattern": "^[a-z0-9][a-z0-9-]{0,39}$" },
|
|
256
|
+
"additionalProperties": {
|
|
257
|
+
"type": "object",
|
|
258
|
+
"required": ["command", "events"],
|
|
259
|
+
"additionalProperties": false,
|
|
260
|
+
"properties": {
|
|
261
|
+
"command": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "description": "One of this manifest's commands: the source's program, run once per poll (one JSON request on stdin, one JSON answer on stdout)." },
|
|
262
|
+
"description": { "type": "string", "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]*$" },
|
|
263
|
+
"events": { "type": "array", "minItems": 1, "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" } },
|
|
264
|
+
"parameters": {
|
|
265
|
+
"type": "object",
|
|
266
|
+
"maxProperties": 16,
|
|
267
|
+
"propertyNames": { "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,39}$" },
|
|
268
|
+
"additionalProperties": {
|
|
269
|
+
"type": "object",
|
|
270
|
+
"additionalProperties": false,
|
|
271
|
+
"properties": {
|
|
272
|
+
"required": { "type": "boolean" },
|
|
273
|
+
"default": { "type": "string", "maxLength": 200 },
|
|
274
|
+
"description": { "type": "string", "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]*$" },
|
|
275
|
+
"pattern": { "type": "string", "minLength": 1 }
|
|
276
|
+
}
|
|
277
|
+
}
|
|
278
|
+
},
|
|
279
|
+
"fields": {
|
|
280
|
+
"type": "object",
|
|
281
|
+
"maxProperties": 16,
|
|
282
|
+
"propertyNames": { "pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,39}$" },
|
|
283
|
+
"additionalProperties": {
|
|
284
|
+
"type": "object",
|
|
285
|
+
"additionalProperties": false,
|
|
286
|
+
"properties": { "pattern": { "type": "string", "minLength": 1 } }
|
|
287
|
+
}
|
|
288
|
+
},
|
|
289
|
+
"urlHosts": { "type": "array", "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "maxLength": 253, "pattern": "^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?(?:\\.[a-z0-9](?:[a-z0-9-]*[a-z0-9])?)*$" } }
|
|
290
|
+
}
|
|
291
|
+
}
|
|
292
|
+
},
|
|
251
293
|
"hooks": {
|
|
252
294
|
"type": "object",
|
|
253
295
|
"properties": {
|
package/docs/configuration.md
CHANGED
|
@@ -78,6 +78,98 @@ Which teams a soul may join, and its default, are committed in the workspace's
|
|
|
78
78
|
commit instead). How teams are resolved, and what a messaging provider does
|
|
79
79
|
with them, is in [workspaces.md](workspaces.md#teams).
|
|
80
80
|
|
|
81
|
+
## Claude channel delivery: the approved route
|
|
82
|
+
|
|
83
|
+
Claude seats on aweb channel delivery start without Claude's “WARNING:
|
|
84
|
+
Loading development channels” prompt through the **approved route**: the
|
|
85
|
+
`oats.aweb` setting `claudeChannelMode: approved` starts Claude with
|
|
86
|
+
`--channels plugin:aweb-channel@awebai-marketplace`, and Claude shows no
|
|
87
|
+
development prompt. Claude admits the plugin when a root-owned machine
|
|
88
|
+
managed-settings file lists it. The route does not depend on the Claude
|
|
89
|
+
version and needs no OATS mechanism beyond these settings. The operator's
|
|
90
|
+
ordered procedure is the `oats.setup` host step “Claude channel delivery
|
|
91
|
+
(approved route)” in `/oats-workspace-config`, which `/oats-onboarding` card 4
|
|
92
|
+
calls; the provider's side is `/oats-aweb` §4.
|
|
93
|
+
|
|
94
|
+
**The managed-settings file** is a host change made by a human admin with
|
|
95
|
+
sudo. OATS never writes it.
|
|
96
|
+
|
|
97
|
+
| | |
|
|
98
|
+
|---|---|
|
|
99
|
+
| Location | Linux: `/etc/claude-code/managed-settings.json`; macOS: `/Library/Application Support/ClaudeCode/managed-settings.json` |
|
|
100
|
+
| Owner and mode | root, `0644` |
|
|
101
|
+
| Content | exactly `{"channelsEnabled": true, "allowedChannelPlugins": [{"plugin": "aweb-channel", "marketplace": "awebai-marketplace"}]}` |
|
|
102
|
+
| Existing file | merge these two keys into it; never overwrite other keys |
|
|
103
|
+
| Drop-ins | Claude also reads `managed-settings.d/*.json` beside the file |
|
|
104
|
+
|
|
105
|
+
Setting `allowedChannelPlugins` **replaces Anthropic's default channel
|
|
106
|
+
allowlist** on that host. That list is the official discord, telegram,
|
|
107
|
+
fakechat and imessage plugins; a host that uses any of them must list them
|
|
108
|
+
too.
|
|
109
|
+
|
|
110
|
+
**Precedence.** Claude reads its managed policy from the first source
|
|
111
|
+
present: server-managed settings (a claude.ai Team/Enterprise organization's
|
|
112
|
+
admin console), then an MDM profile (`com.anthropic.claudecode` on macOS), then
|
|
113
|
+
the file. On an account governed by server-managed settings or MDM the file is
|
|
114
|
+
ignored, and the organization admin sets the same two keys there instead.
|
|
115
|
+
Pro/Max accounts and plain API-key use have no server-managed settings, so the
|
|
116
|
+
file applies. `channelsEnabled: true` is required for API-key users whenever
|
|
117
|
+
any managed policy exists, and for Team/Enterprise subscribers; Pro/Max ignore
|
|
118
|
+
it. It is harmless there: always include it.
|
|
119
|
+
|
|
120
|
+
**OATS side**, in this host's `oats-local.yaml` under `settings.oats.aweb`:
|
|
121
|
+
|
|
122
|
+
```yaml
|
|
123
|
+
settings:
|
|
124
|
+
oats.aweb:
|
|
125
|
+
claudeChannelMode: approved # host-only
|
|
126
|
+
delivery: channel # host-wide; or per spawn: --provider oats.aweb delivery=channel
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
With channel delivery, pi uses its `@awebai/pi` extension and Codex always
|
|
130
|
+
uses the host broker.
|
|
131
|
+
|
|
132
|
+
**The plugin.** `aweb-channel` must be installed from the marketplace named
|
|
133
|
+
`awebai-marketplace` (GitHub `awebai/claude-plugins`) and enabled, in the
|
|
134
|
+
Claude config directory the host's Claude launch configuration uses (its
|
|
135
|
+
`CLAUDE_CONFIG_DIR`, else `~/.claude`).
|
|
136
|
+
|
|
137
|
+
**Existing homes** keep the delivery and channel mode recorded at their spawn.
|
|
138
|
+
Respawn a home to adopt the route. Setup never restarts running agents
|
|
139
|
+
without the operator's word.
|
|
140
|
+
|
|
141
|
+
**No launch-prompt opt-in** is needed in approved mode: the
|
|
142
|
+
[exact-home consent](#exact-home-launch-prompt-consent) applies only to
|
|
143
|
+
development mode, and qualifies only Claude 2.1.289 on `darwin-arm64`.
|
|
144
|
+
|
|
145
|
+
**Verify:**
|
|
146
|
+
|
|
147
|
+
1. `oats spawn <soul> --preview` shows `settings.oats.aweb.claudeChannelMode:
|
|
148
|
+
approved` and `delivery: channel`.
|
|
149
|
+
2. The started session shows no development prompt, and its banner shows
|
|
150
|
+
“Channels (experimental) messages from plugin:aweb-channel@awebai-marketplace
|
|
151
|
+
inject directly in this session”, followed by “restart without --channels
|
|
152
|
+
to stop”. At normal terminal widths the banner wraps over two rows: look
|
|
153
|
+
for each part, not for one string.
|
|
154
|
+
3. The banner says none of `not on the approved channels allowlist`,
|
|
155
|
+
`not on your org's approved channels list`, `blocked by org policy` or
|
|
156
|
+
`plugin not installed`.
|
|
157
|
+
4. Receive is proven only by the `/oats-aweb` nonce exchange.
|
|
158
|
+
|
|
159
|
+
**Failure banners**, their cause and remedy:
|
|
160
|
+
|
|
161
|
+
| What the session shows | Cause | Remedy |
|
|
162
|
+
|---|---|---|
|
|
163
|
+
| `not on the approved channels allowlist` | the effective managed policy has no `allowedChannelPlugins` (no file, the file not read, or the key missing), so Anthropic's default list applied | write or fix the file |
|
|
164
|
+
| `not on your org's approved channels list` | the effective policy has an `allowedChannelPlugins` without this plugin and marketplace pair: the names in the file are wrong, or a higher source (server-managed settings or MDM) supplies its own list | fix the entry, or have the organization admin add it |
|
|
165
|
+
| `blocked by org policy` (then “Inbound messages will be silently dropped”) | the effective policy lacks `channelsEnabled: true`, which Team/Enterprise subscribers need, and API-key use whenever any managed policy exists | add the key, or have the organization admin set it |
|
|
166
|
+
| `plugin:aweb-channel@awebai-marketplace · plugin not installed` | the plugin is not installed in the launch's Claude config directory | install and enable it there |
|
|
167
|
+
| the development prompt still appears | the home started in development mode, not approved: the host setting is missing, or the home was spawned before the change | set `claudeChannelMode: approved`, then respawn the home |
|
|
168
|
+
|
|
169
|
+
**Limits.** Channels are an Anthropic research preview. Anthropic's
|
|
170
|
+
account-level feature flag gates channels on every route. The allowlist
|
|
171
|
+
matches the marketplace by name.
|
|
172
|
+
|
|
81
173
|
## Exact-home launch prompt consent
|
|
82
174
|
|
|
83
175
|
`launchPromptAnswers` belongs only in the host's `oats-local.yaml`. It is
|
|
@@ -114,6 +206,8 @@ selects arguments; it does not grant consent. Approved-mode arguments, another
|
|
|
114
206
|
plugin, multiple plugins or contradictory channel arguments cannot qualify.
|
|
115
207
|
Environment values, spawn flags and saved launch recipes cannot enable consent.
|
|
116
208
|
Existing harness folder-trust configuration remains independent.
|
|
209
|
+
The version-independent route, with no prompt to answer, is
|
|
210
|
+
[the approved route](#claude-channel-delivery-the-approved-route).
|
|
117
211
|
|
|
118
212
|
Preview reports effective `launchPromptAnswers.awebDevelopmentChannel` and
|
|
119
213
|
`consentSource` without terminal capture or input. `--no-launch` never answers.
|
|
@@ -398,6 +492,9 @@ is safe to delete.
|
|
|
398
492
|
- **Per-instance provider facts:** `oats spawn <soul> --provider <cap> key=value`,
|
|
399
493
|
recorded in the instance's `instance.json`.
|
|
400
494
|
- **Shared teams, stores and defaults:** the workspace file.
|
|
495
|
+
- **Claude's channel admission:** Claude's own managed policy (server-managed
|
|
496
|
+
settings, an MDM profile or the root-owned managed-settings file; see
|
|
497
|
+
[the approved route](#claude-channel-delivery-the-approved-route)).
|
|
401
498
|
|
|
402
499
|
## Inspecting the effective configuration
|
|
403
500
|
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -43,7 +43,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
43
43
|
"preview-composed-from","observe-max-age","spawn-preview-max-age","launch-config-default","capability-show","capture-file",
|
|
44
44
|
"workspace-identity","server-connect","capability-route","servers-per-workspace","operator-default-soul","waiting-on-you",
|
|
45
45
|
"automation-descriptions","souls-capabilities","soul-composed-instructions","teams-conditional-default",
|
|
46
|
-
"server-probe-features","worktree-event"],
|
|
46
|
+
"server-probe-features","worktree-event","session-attach-detach-key"],
|
|
47
47
|
"automationsApi":1,"workspaceApi":2,"instanceGitApi":1,"spawnApplyApi":1,"soulsApi":2,"lifecycleApi":1,
|
|
48
48
|
"readinessApi":2,"spawnPreviewApi":2,"eventsApi":2,"scheduleHistoryApi":3,"scheduleApi":2,"operationsApi":2,
|
|
49
49
|
"capabilityShowApi":1}
|
|
@@ -117,7 +117,9 @@ 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)) | |
|
|
122
|
+
| `session-attach-detach-key` | `oats session attach … --detach-key <key>`, local and `--server`: the one key that detaches that viewer, and exit status 20 when it did, OATS 0.51.0 ([execution-targets.md](execution-targets.md#inspect-input-and-attach)). Gate on the probe and never try: a kernel without it ignores the flag and opens a viewer with no exit. A routed attach refuses a host without it (`E_REMOTE_INCOMPATIBLE`, `details: {"feature":"session-attach-detach-key"}`) | |
|
|
121
123
|
|
|
122
124
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
123
125
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -220,6 +222,7 @@ oats status | workspace status | souls | capabilities | inspect --soul|--home
|
|
|
220
222
|
| teams | soul teams <soul> … --max-age <seconds> --json
|
|
221
223
|
oats spawn <soul> … --preview --max-age <seconds> --json (feature spawn-preview-max-age)
|
|
222
224
|
oats capabilities show <name> … --max-age <seconds> --json (feature capability-show)
|
|
225
|
+
oats trigger poll <id> --run-source … --max-age <seconds> --json (feature trigger-sources)
|
|
223
226
|
```
|
|
224
227
|
|
|
225
228
|
- **Values:** whole seconds, `0` to `86400`. `0` is live: it reuses nothing.
|
|
@@ -279,8 +282,8 @@ oats capabilities show <name> … --max-age <seconds> --json (feature capabilit
|
|
|
279
282
|
`E_BAD_ARGS` first), with
|
|
280
283
|
`E_BAD_ARGS` "--max-age is not accepted by \`oats <form>\`: only the read
|
|
281
284
|
verbs reuse observations (status, workspace status, souls, capabilities,
|
|
282
|
-
capabilities show, inspect --soul|--home, spawn --preview,
|
|
283
|
-
forms of teams and soul teams)" and,
|
|
285
|
+
capabilities show, inspect --soul|--home, spawn --preview, trigger poll,
|
|
286
|
+
and the read forms of teams and soul teams)" and,
|
|
284
287
|
with `--server`, "--max-age cannot be combined with --server: observation
|
|
285
288
|
reuse is local to this machine".
|
|
286
289
|
A capability command's argv (`oats <namespace> …`) is its provider's: the
|
|
@@ -1000,6 +1003,15 @@ nothing reads a working clone.
|
|
|
1000
1003
|
[capability warnings](#capability-warnings-hook-event-unsupported-oats-0490).
|
|
1001
1004
|
Their `path` is the repository-relative form, unlike the paths above. The
|
|
1002
1005
|
text form prints them (to stderr with `--file`).
|
|
1006
|
+
- `triggerSources` (feature `trigger-sources`), after
|
|
1007
|
+
`warnings`, only when the manifest declares the key: the declaration
|
|
1008
|
+
exactly as written, whatever its shape (untrusted text: render it as
|
|
1009
|
+
text). `triggerSourceProblems: [{source, pointer, message}]` follows only
|
|
1010
|
+
when the declaration has problems: the ones a trigger naming a source
|
|
1011
|
+
would get as `E_TRIGGER_SOURCE`, `source` `null` for a top-level problem,
|
|
1012
|
+
`pointer` a JSON pointer into the manifest. A malformed declaration never
|
|
1013
|
+
refuses the command and adds nothing to `problems`
|
|
1014
|
+
([capabilities.md](capabilities.md#trigger-sources-triggersources)).
|
|
1003
1015
|
- With `--max-age` (`0` included) both the show and the `--file` answer gain
|
|
1004
1016
|
the [`observation`](#observation-reuse-feature-observe-max-age-oats-0311)
|
|
1005
1017
|
block `{observedAt, reused, localRevision}`.
|
|
@@ -1094,7 +1106,8 @@ nonzero exit, as for every command: `E_BAD_ARGS`, `E_CAPABILITY_UNKNOWN`,
|
|
|
1094
1106
|
(`E_LOCAL_MISSING`, `E_LOCK_SCHEMA`, …).
|
|
1095
1107
|
|
|
1096
1108
|
**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,
|
|
1109
|
+
inject's path and size, each skill with its files and sizes, the trigger
|
|
1110
|
+
sources (name, command, events, description) and their problems, and the
|
|
1098
1111
|
problems. `--file` prints the text; a binary file prints a one-line note
|
|
1099
1112
|
instead, and a truncated file prints its text followed by a one-line note.
|
|
1100
1113
|
|
|
@@ -1130,6 +1143,12 @@ capabilities | package <id>'s capabilities> were not checked …`, never an
|
|
|
1130
1143
|
empty list read as "no warning". Older kernels answer no such `warnings` key
|
|
1131
1144
|
(inspect, readiness, show, doctor) and refuse the capability instead.
|
|
1132
1145
|
|
|
1146
|
+
`oats doctor --json` also lists what retires left behind in `information[]`:
|
|
1147
|
+
one `retained-recovery:` and one `retained-worktree:` line per item, after a
|
|
1148
|
+
line that gives each kind's total, and at most 50 items per kind
|
|
1149
|
+
([After a retire](souls-and-instances.md#after-a-retire-inspect-restore-dispose)).
|
|
1150
|
+
Each element is one line of text with no newline. The answer has no new key.
|
|
1151
|
+
|
|
1133
1152
|
### Desktop facts
|
|
1134
1153
|
|
|
1135
1154
|
Feature `desktop-facts`: facts the kernel reports so the Desktop never derives
|
|
@@ -2220,7 +2239,11 @@ its absence.
|
|
|
2220
2239
|
claim is kept as `recordedHome`/`recordedInstance`), `running` (read from
|
|
2221
2240
|
the row's recorded tmux socket and session, never the caller's `$TMUX`;
|
|
2222
2241
|
`null` with `runtimeState: "unreachable"` and the tmux error as
|
|
2223
|
-
`runtimeError` when that server cannot be read
|
|
2242
|
+
`runtimeError` when that server cannot be read, and also when its socket
|
|
2243
|
+
file is missing while a process works in the home or the process scan
|
|
2244
|
+
cannot run, `runtimeError` then naming the processes or the scan's error
|
|
2245
|
+
([#624](execution-targets.md#missing-socket); with no process in the home
|
|
2246
|
+
a missing socket file reads `false`, as after a reboot); `null` for a home a
|
|
2224
2247
|
Herdr-era kernel recorded, with `runtimeState: "unsupported"` and
|
|
2225
2248
|
`runtimeError: "E_HERDR_REMOVED: …"`, the recorded `sessionTarget` staying
|
|
2226
2249
|
in the row),
|
|
@@ -2917,7 +2940,10 @@ the instance back.
|
|
|
2917
2940
|
idempotencyKey, planRevision, at, ok, results, retained: ["home", "work",
|
|
2918
2941
|
"transcript", "launch"], replayed: false}`. A result is `{instance, home,
|
|
2919
2942
|
ok: true, stopped, alreadyIdle, state}` or `{instance, home, ok: false,
|
|
2920
|
-
code, message, stillRunning: [pid]}`.
|
|
2943
|
+
code, message, stillRunning: [pid]}`. `code` is `E_SESSION_UNAVAILABLE` when
|
|
2944
|
+
whether the instance runs cannot be established, among them a recorded
|
|
2945
|
+
tmux socket file that is missing while a process works in the home
|
|
2946
|
+
([#624](execution-targets.md#missing-socket)): never `alreadyIdle`.
|
|
2921
2947
|
- `ok: false`: at least one target still runs (text mode exits 1).
|
|
2922
2948
|
- A replay is the stored receipt (`<home>/.oats-stop-receipt.<key>.json`)
|
|
2923
2949
|
with `replayed: true`.
|
|
@@ -2955,8 +2981,9 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
2955
2981
|
true, note}` when the session is observably gone: instance.json records no
|
|
2956
2982
|
launch, or the recorded tmux server is not running, or the recorded window
|
|
2957
2983
|
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
|
-
|
|
2984
|
+
live process on the host has its working directory in the home
|
|
2985
|
+
([the process scan](souls-and-instances.md#the-process-scan): `/proc` on
|
|
2986
|
+
Linux, `lsof` elsewhere; a scan that cannot run counts as not absent). Retire then proceeds
|
|
2960
2987
|
without quiescing (hooks run, work is preserved). Otherwise it stays
|
|
2961
2988
|
`unestablished`, with a `note` saying why, and retire refuses with
|
|
2962
2989
|
`E_RUNTIME_ENDPOINT_UNKNOWN`, `--force` included. `notes` repeats either
|
|
@@ -3038,7 +3065,10 @@ oats retire <instance> --plan [--home <abs>] [--dir <d>] --json
|
|
|
3038
3065
|
|
|
3039
3066
|
Plain `retire` keeps a worktree-mode instance's work: the worktree is moved
|
|
3040
3067
|
(`git worktree move`) to `<deployment>/.agents/worktrees/<repo>/<branch>` (a
|
|
3041
|
-
`-2` suffix if taken; `detached-<oid12>` when detached), state intact.
|
|
3068
|
+
`-2` suffix if taken; `detached-<oid12>` when detached), state intact. The
|
|
3069
|
+
`<branch>` leaf is the branch flattened to one path component, and a long one
|
|
3070
|
+
is cut and hashed to fit NAME_MAX
|
|
3071
|
+
([souls-and-instances.md](souls-and-instances.md#extra-trees-at-retire)). An
|
|
3042
3072
|
extra tree that is not clean is moved the same way; a clean one is removed.
|
|
3043
3073
|
|
|
3044
3074
|
```text
|
|
@@ -3205,7 +3235,8 @@ A first retire prints the **raw receipt**, not an envelope:
|
|
|
3205
3235
|
`capabilityMeta`, `warnings`, `wakeSchedulesRemoved`.
|
|
3206
3236
|
- A deferred self-retire (`--self`) prints `{retired, agent, deferred: true,
|
|
3207
3237
|
pendingMarker, resultPath, logPath, completesInSec, completionPid}`, or
|
|
3208
|
-
`{…, alreadyScheduled: true, requestedAt}
|
|
3238
|
+
`{…, alreadyScheduled: true, requestedAt}` while one is scheduled and its
|
|
3239
|
+
completion has not started (below).
|
|
3209
3240
|
|
|
3210
3241
|
**Recorded children**, on every apply (plain, guarded and `--self`), as the
|
|
3211
3242
|
plan says: each child the plan lists is stopped first (bounded SIGTERM,
|
|
@@ -3230,12 +3261,96 @@ retry}` to `resultPath`. Before 0.48.0 only a guarded apply stopped children.
|
|
|
3230
3261
|
`--idempotency-key` together.
|
|
3231
3262
|
- A used key replays its receipt as an **envelope** with `replayed: true`
|
|
3232
3263
|
(receipts live beside the instances directory and outlive the home).
|
|
3233
|
-
- The revision is checked against a fresh plan: `E_PLAN_STALE {plan}`.
|
|
3264
|
+
- The revision is checked against a fresh plan: `E_PLAN_STALE {plan}`. That
|
|
3265
|
+
plan is read once, when the retire holds the home's claim (below): it is
|
|
3266
|
+
the state the retire starts from, and one apply appends one
|
|
3267
|
+
`retire-planned` event. Against a retire in flight or a scheduled
|
|
3268
|
+
self-retire the answer is `E_LIFECYCLE_BUSY` and no plan is read, whatever
|
|
3269
|
+
the plan would read by then: a retire in flight has usually changed it (it
|
|
3270
|
+
stops the session of a launched instance before its hooks run). Before the
|
|
3271
|
+
claim an apply only replays a used key and resolves the home
|
|
3272
|
+
(`E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`, `E_HOME_MISMATCH`).
|
|
3234
3273
|
- The children stopped are those of the revalidated plan, and a refusal
|
|
3235
3274
|
carries it: `E_CHILDREN_RUNNING {childrenStopped, plan}`.
|
|
3236
3275
|
- A first guarded retire prints the raw receipt with `planRevision`,
|
|
3237
3276
|
`idempotencyKey` and `replayed: false`.
|
|
3238
3277
|
|
|
3278
|
+
**One retire of a home at a time** (0.51.0, #863). Every retire that applies (plain,
|
|
3279
|
+
guarded, `--self` and its detached completion; with `--server`, on the host)
|
|
3280
|
+
holds the home's claim,
|
|
3281
|
+
`<instances>/.oats-retirement/claims/<instance>.lock`, from the moment it
|
|
3282
|
+
has resolved the home until it ends, by success or by any refusal or failure.
|
|
3283
|
+
The claim is a file that names its holder by pid and start time. It lies
|
|
3284
|
+
beside the homes, never inside one: a home's bytes are what its retire
|
|
3285
|
+
observes, copies and removes. A second retire of that home does not wait: it
|
|
3286
|
+
answers `E_LIFECYCLE_BUSY` at once (exit 1; the text form prints the
|
|
3287
|
+
message), before it stops a session or a child, writes a recovery, runs a
|
|
3288
|
+
hook or changes a file of the home. **`--force` does not bypass it**, and
|
|
3289
|
+
`--plan` takes no claim and refuses nothing new. A guarded apply answers it
|
|
3290
|
+
before `E_PLAN_STALE`: under the claim the answers come in this order: the
|
|
3291
|
+
home is gone (`E_SESSION_UNKNOWN`), a self-retire is scheduled
|
|
3292
|
+
(`E_LIFECYCLE_BUSY`), the plan is stale (`E_PLAN_STALE`), then the retire. A claim whose holder has
|
|
3293
|
+
died, for example a retire killed while its hooks ran, is taken over by the
|
|
3294
|
+
next retire of that name. So a killed retire can always be run again. The
|
|
3295
|
+
claim does not end what the killed retire left running: one of its retire
|
|
3296
|
+
hooks may still be running when the next retire takes the claim over and
|
|
3297
|
+
runs the hooks again (#865). Until
|
|
3298
|
+
that name is retired again its claim file stays where it is, and it is safe
|
|
3299
|
+
to remove once its pid is gone. A retire that ends removes its claim file;
|
|
3300
|
+
the `claims/` directory itself stays, empty.
|
|
3301
|
+
|
|
3302
|
+
`details` is `{instance, home, lock, pid, since}`: `lock` is the file that
|
|
3303
|
+
names the holder, `since` when the holder took it. Every message is one
|
|
3304
|
+
line and says that nothing was done:
|
|
3305
|
+
|
|
3306
|
+
- A live holder: `a retire of <name> is already running (pid <pid>, since
|
|
3307
|
+
<at>); nothing was done — wait for it to finish`.
|
|
3308
|
+
- A holder whose start time cannot be read (where `ps` fails, or a claim
|
|
3309
|
+
that records none) is never taken for gone, and its claim is never taken
|
|
3310
|
+
over. `details.unknown` is the reason. The message names the pid, its
|
|
3311
|
+
recorded start, the reason and the way out: check that pid by hand, and if
|
|
3312
|
+
it is not an `oats retire`, remove `<lock>`, then retry.
|
|
3313
|
+
- A claim file that is not a readable claim is never removed. `details` is
|
|
3314
|
+
`{instance, home, lock}`; the message names the file and says to inspect
|
|
3315
|
+
it and remove it if no `oats retire` holds it.
|
|
3316
|
+
- The retire's own start time cannot be read, so it could not hold the claim
|
|
3317
|
+
verifiably: `details` is `{instance, home, lock}`, and the message gives
|
|
3318
|
+
the reader's own reason (the `/proc` read, or what `ps` answered).
|
|
3319
|
+
|
|
3320
|
+
A scheduled self-retire counts from the moment it is scheduled. Its pending
|
|
3321
|
+
marker (`pendingMarker`) records the completion process as `completionPid`
|
|
3322
|
+
and `completionStart` (`null` when the start could not be read). While that
|
|
3323
|
+
process lives, every other retire of the instance is refused the same way,
|
|
3324
|
+
`--self --keep-dir` included: `a retire of <name> is already scheduled (its
|
|
3325
|
+
completion, pid <pid>, requested at <requestedAt>); nothing was done — wait
|
|
3326
|
+
for it to finish`, with `details.lock` the pending marker, `details.pid` the
|
|
3327
|
+
completion and `details.since` the marker's `requestedAt`. A completion
|
|
3328
|
+
whose start cannot be read is refused as a holder's is (`details.unknown`),
|
|
3329
|
+
the file to remove being the pending marker. A second `--self` answers
|
|
3330
|
+
`alreadyScheduled: true` only while the completion has not started. While
|
|
3331
|
+
the first `--self` is still scheduling, or once the completion holds the
|
|
3332
|
+
claim, it is refused the claim and answers `E_LIFECYCLE_BUSY` like any other
|
|
3333
|
+
retire, where it answered `alreadyScheduled: true` before 0.51.0. The marker refuses nothing once its completion has
|
|
3334
|
+
left its outcome at `resultPath` (it failed) or is gone (it died), nor when
|
|
3335
|
+
it names no completion (a marker written before 0.51.0): `oats retire
|
|
3336
|
+
<instance>` then retries the retirement, as before. The completion waits up
|
|
3337
|
+
to 3 s for the retire that scheduled it to release the claim, then takes it
|
|
3338
|
+
as any retire does; one that meets another retire still running is refused,
|
|
3339
|
+
and records that at `resultPath` like any failed completion.
|
|
3340
|
+
|
|
3341
|
+
The home is resolved again once the claim is held. One that another retire
|
|
3342
|
+
removed in between answers `E_SESSION_UNKNOWN`, as a retire of a retired
|
|
3343
|
+
instance does. If the name is by then the home of another agent, the retire
|
|
3344
|
+
starts over on that home, under that home's claim; after two such changes it
|
|
3345
|
+
answers `E_LIFECYCLE_BUSY` (`the home of <name> changed while its claim was
|
|
3346
|
+
being taken …; nothing was done — retry`, `details: {instance, home, lock}`).
|
|
3347
|
+
A retire of a name that has no home also removes a claim of that name whose
|
|
3348
|
+
holder is gone, left by a retire that was killed after it removed the home.
|
|
3349
|
+
|
|
3350
|
+
The claim orders retires only. `oats instance stop`, `oats session start`
|
|
3351
|
+
and `oats worktree add` do not take it and are not refused by it, and `oats
|
|
3352
|
+
status` does not show a held claim (#866).
|
|
3353
|
+
|
|
3239
3354
|
Refusals (envelopes): `E_PLAN_STALE`, `E_CHILDREN_RUNNING`,
|
|
3240
3355
|
`E_WORK_PRESERVATION_FAILED` (the home is kept; retry, or
|
|
3241
3356
|
`--discard-worktree` when it is `work/` that could not be re-homed: it does
|
|
@@ -3244,7 +3359,9 @@ message names the entry or the state that could not be read, or the directory
|
|
|
3244
3359
|
Git reads as the top level of a `work/` whose `core.worktree` names another
|
|
3245
3360
|
one),
|
|
3246
3361
|
`E_SESSION_UNKNOWN`, `E_AMBIGUOUS_INSTANCE`,
|
|
3247
|
-
`E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (
|
|
3362
|
+
`E_NO_ROOT`, `E_LIFECYCLE_FAILED`, `E_LIFECYCLE_BUSY` (another retire of the
|
|
3363
|
+
home is running or scheduled, `--force` included: one retire of a home at a
|
|
3364
|
+
time, above; or, feature
|
|
3248
3365
|
`worktree-event`: the home is a spawn still running its `worktree` hooks, a
|
|
3249
3366
|
row with `spawnInProgress: true`, `--force` included; or one whose start time
|
|
3250
3367
|
cannot be read, a `rollbackIncomplete` row, until `--force`; or a hook or git
|
|
@@ -3338,6 +3455,10 @@ selection flags. See [the start workflow](desktop-instance-start.md).
|
|
|
3338
3455
|
`E_SESSION_UNKNOWN`, the receipt kept, nothing started. The message names
|
|
3339
3456
|
that target and the way out: stop it, then `oats session restart`, which
|
|
3340
3457
|
goes ahead once that target no longer runs. Never edit or remove a receipt by hand.
|
|
3458
|
+
- A recorded tmux socket file that is missing while a process works in the
|
|
3459
|
+
home, or the process scan cannot run, is not a stopped server:
|
|
3460
|
+
`E_SESSION_UNKNOWN`, nothing started and no server created at that path
|
|
3461
|
+
([#624](execution-targets.md#missing-socket)).
|
|
3341
3462
|
- A lost response does not mean the launch failed: check status before a
|
|
3342
3463
|
retry. A remote home's saved route names its execution host.
|
|
3343
3464
|
- Errors: `E_BAD_ARGS`, `E_SESSION_UNKNOWN`, `E_UNSUPPORTED_MODE`,
|
|
@@ -3545,11 +3666,13 @@ oats schedule update <id> --description=<text> [--dir <d>] --json
|
|
|
3545
3666
|
### `oats trigger`
|
|
3546
3667
|
|
|
3547
3668
|
```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
|
|
3669
|
+
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
3670
|
```
|
|
3550
3671
|
|
|
3551
3672
|
Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
|
|
3552
|
-
"trigger"`).
|
|
3673
|
+
"trigger"`). A trigger's source is the built-in `github.pull_request` or, with
|
|
3674
|
+
feature `trigger-sources`, `<capability>:<source>`, a source a
|
|
3675
|
+
capability declares ([schedules.md](schedules.md#capability-sources)).
|
|
3553
3676
|
|
|
3554
3677
|
- `list`: `{triggerApi, scope, host, snapshot, triggers, scheduler}`.
|
|
3555
3678
|
`show`, `add`, `update`, `enable`, `disable` → `{trigger}`; `remove` → `{removed,
|
|
@@ -3561,17 +3684,29 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
|
|
|
3561
3684
|
- `id` is always qualified (`local/<id>` or `<member>/<id>`); verbs accept
|
|
3562
3685
|
`local/<id>` or a bare local id.
|
|
3563
3686
|
- `on`: `{source: "github.pull_request", repo, events: [opened | reopened |
|
|
3564
|
-
ready_for_review | labeled | synchronize], labels, base?, poll}
|
|
3687
|
+
ready_for_review | labeled | synchronize], labels, base?, poll}`, or for a
|
|
3688
|
+
capability source `{source: "<capability>:<source>", params: {<name>:
|
|
3689
|
+
<string>}, events: [<the source's event names>], poll}`.
|
|
3565
3690
|
- `spawn`: `{soul, purpose, task, teams, launchConfig?, harness?, model?,
|
|
3566
3691
|
yolo?, backend?}`. `purpose` and `task` template over `{repo}`,
|
|
3567
|
-
`{number}`, `{url}`, `{event}`, `{trigger}`, `{headSha}
|
|
3692
|
+
`{number}`, `{url}`, `{event}`, `{trigger}`, `{headSha}`, `{subject}` and
|
|
3693
|
+
`{key}`; a capability source's over `{trigger}`, `{source}`, `{subject}`,
|
|
3694
|
+
`{event}`, `{key}`, `{url}` and `{fields.<name>}`. `teams` are
|
|
3568
3695
|
distinct labels passed as `--provider <messaging cap> join=<labels>`; a
|
|
3569
3696
|
soul without messaging refuses `E_TRIGGER_TEAMS {soul, teams}`.
|
|
3570
3697
|
- `template?`: `{package, version, commit, template}`.
|
|
3571
3698
|
- `lastRun`: `{at, instance, home, event, number, subject, key}`
|
|
3572
3699
|
(`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
|
|
3700
|
+
for a run recorded before 0.49.0, its number; a capability source's
|
|
3701
|
+
run has `number: null`); `nextDue`: the next poll here, `null` before
|
|
3702
|
+
the first.
|
|
3703
|
+
- `invalid?`: `{code, message, field?}` when the stored definition no
|
|
3704
|
+
longer validates, as before. A capability source's trigger whose last
|
|
3705
|
+
meaning check failed at a poll carries `invalid: {code, message, field?,
|
|
3706
|
+
at}` instead (`code` `E_TRIGGER_SOURCE` or `E_TRIGGER_INVALID`; `at` when
|
|
3707
|
+
the check ran), until a good poll. `invalid` always means the trigger
|
|
3708
|
+
itself is invalid; an event the source answered badly is an *invalid
|
|
3709
|
+
event* (`invalidEvents`).
|
|
3575
3710
|
- `status [<id>]` → `{triggerApi, scope, triggers: [{id, name, enabled,
|
|
3576
3711
|
runsHere, reason, enabledHere, repo, soul, concurrency: {max, perKey},
|
|
3577
3712
|
liveCount, live: [{instance, home, repo, number, subject, event}], lastPoll:
|
|
@@ -3582,6 +3717,36 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
|
|
|
3582
3717
|
`subject` (0.49.0) is the event's subject, the thing `perKey` counts: a
|
|
3583
3718
|
PR's number, as a string. A record written before 0.49.0 has none, and
|
|
3584
3719
|
its number is reported.
|
|
3720
|
+
- **A capability source's `status` row** (feature `trigger-sources`) has
|
|
3721
|
+
`repo: null`, `number: null` in `pending[]`, `fired[]` and `live[]`, and
|
|
3722
|
+
adds `source: {capability, name}`, `invalidEvents: [{text, rule}]` (the
|
|
3723
|
+
last good poll's, at most 20; `rule` is `shape`, `unknown-key`, `key`,
|
|
3724
|
+
`subject`, `event`, `url`, `fields` or `duplicate-key`, `text` the first
|
|
3725
|
+
200 characters of the event's JSON), `skipped: [{subject, why}]` (the last
|
|
3726
|
+
good poll's, at most 100) and, when its last meaning check failed,
|
|
3727
|
+
`invalid: {code, message, field?, at}`. Its `lastPoll` is `{at, ok: true,
|
|
3728
|
+
events, invalidEvents, skipped, filtered}` (counts) or `{at, ok: false,
|
|
3729
|
+
cause, error, source?}`, and `lastError` may carry the same `source`.
|
|
3730
|
+
`cause` is `exit`, `result`, `too-many-events`, `timeout`, `refused` or
|
|
3731
|
+
`resolution`; `source: {code, message?}` is the source's own refusal.
|
|
3732
|
+
`why`, `source.code` and `source.message` are the source's untrusted text,
|
|
3733
|
+
capped (200, 128, 500 characters) with control, separator, bidi,
|
|
3734
|
+
invisible and tag characters replaced by U+FFFD: render them as text,
|
|
3735
|
+
marked as the source's.
|
|
3736
|
+
- **Presence and staleness.** `source`, `invalidEvents` and `skipped` are
|
|
3737
|
+
always present on a capability source's status row. The two lists are
|
|
3738
|
+
`[]` until the trigger's first good poll and hold the last good poll's
|
|
3739
|
+
lists after that. A failed poll (`lastPoll.ok: false`) and a failed
|
|
3740
|
+
meaning check (`invalid`, which leaves `lastPoll` as it was) leave them
|
|
3741
|
+
unchanged, so they can be older than `lastPoll.at`, `lastError.at` and
|
|
3742
|
+
`invalid.at`. The lists are the current source's: changing a trigger's
|
|
3743
|
+
`on.source` empties them and `pending`, and clears `invalid`, `lastPoll`
|
|
3744
|
+
and `lastError` (`fired` stays), in what `status` and `list` answer at
|
|
3745
|
+
once and in the state at the next tick.
|
|
3746
|
+
- **Arrays versus counts.** In `trigger test`'s `source` (`ok: true`) and
|
|
3747
|
+
in `trigger poll`'s answer, `events`, `invalidEvents` and `skipped` are
|
|
3748
|
+
arrays and `filtered` is a count. In `lastPoll` (`ok: true`) and in the
|
|
3749
|
+
tick's `polled` row, all four are counts.
|
|
3585
3750
|
- `test <id>` → `{triggerApi, id, ok, placement: {runsOn, owner, host,
|
|
3586
3751
|
runsHere, reason, detail?, enabledHere}, gh: {ok, account,
|
|
3587
3752
|
credentialSource, reachesHostTimer, note, detail}, repo: {key, readable,
|
|
@@ -3596,20 +3761,96 @@ Event-driven spawns. Local definitions live in `oats-schedules.json` (`kind:
|
|
|
3596
3761
|
purpose was cut to fit ([schedules.md](schedules.md#triggers)); both are
|
|
3597
3762
|
`null` when the soul does not resolve or its name is too long for a
|
|
3598
3763
|
triggered spawn (that error is then in `problems`).
|
|
3764
|
+
- **`test <id> --run-source` of a capability source's trigger** runs the
|
|
3765
|
+
source (it executes the capability's source command, whatever the host's
|
|
3766
|
+
trust and `runsOn` say, and so only with the flag: see **`--run-source`**
|
|
3767
|
+
below) and answers `{triggerApi, id, ok, placement, gh, repo: null,
|
|
3768
|
+
soul, teams, source, wouldFire, problems, warnings, spawned: false}`, no
|
|
3769
|
+
`pollError`. `gh` is `null` unless the trigger has an `owner` (then as
|
|
3770
|
+
above, for the owner's host). `source` is `{capability, name, ok: true,
|
|
3771
|
+
events, invalidEvents, skipped, filtered}`, `{capability, name, ok: false,
|
|
3772
|
+
filtered: 0, invalid: {code, message, field?, at}, events: [],
|
|
3773
|
+
invalidEvents: [], skipped: []}` when its meaning fails, or `{capability,
|
|
3774
|
+
name, ok: false, filtered: 0, cause, error: {code, message}, source?,
|
|
3775
|
+
events: [], invalidEvents: [], skipped: []}` when the poll fails.
|
|
3776
|
+
Without `--run-source`, `test` answers a trigger whose meaning or
|
|
3777
|
+
resolution fails as above (exit 0, `source.ok: false`: no capability code
|
|
3778
|
+
runs to say so), and a trigger whose meaning holds with
|
|
3779
|
+
`E_TRIGGER_SOURCE_RUN`. `wouldFire` rows are `{key, subject,
|
|
3780
|
+
event, url?, instance, nameCut, held?}`. When the tick would not run the
|
|
3781
|
+
trigger here, `problems` holds `run manually with --run-source; the tick
|
|
3782
|
+
will not run it here: <reason>` (with the placement's detail). `warnings` always holds
|
|
3783
|
+
"this source's credential may not be visible to the host timer: it runs
|
|
3784
|
+
with only PATH and OATS_HOME_DIR set, so keep the source's login in its
|
|
3785
|
+
own store, not in an exported variable".
|
|
3786
|
+
- **`poll <id> --run-source`** (feature `trigger-sources`) runs a capability
|
|
3787
|
+
source's trigger's source once, its meaning checked first, and answers
|
|
3788
|
+
`{triggerApi, id, source: {capability, name}, events: [{key, subject,
|
|
3789
|
+
event, url?, fields}], invalidEvents: [{text, rule}], skipped: [{subject,
|
|
3790
|
+
why}], filtered}`, plus `observation` with `--max-age`. `events` are the
|
|
3791
|
+
valid events the trigger selects, `key` as the source wrote it (stored
|
|
3792
|
+
prefixed `<trigger>:`); `filtered` counts the valid events whose `event`
|
|
3793
|
+
the trigger does not select. It records nothing and spawns nothing, but it
|
|
3794
|
+
executes the capability's source command. A failed poll is `E_TRIGGER_POLL`
|
|
3795
|
+
with `details: {cause, source?}`; a meaning failure is `E_TRIGGER_SOURCE`
|
|
3796
|
+
`{capability, source, pointer?}` or `E_TRIGGER_INVALID {field}`; without
|
|
3797
|
+
the flag it is `E_TRIGGER_SOURCE_RUN`; a `github.pull_request` trigger is
|
|
3798
|
+
`E_BAD_ARGS`, with or without the flag. Without `--max-age` it observes
|
|
3799
|
+
the members live.
|
|
3800
|
+
- **`--run-source`** (feature `trigger-sources`): by hand, `test` and `poll`
|
|
3801
|
+
run a capability source's command only with this switch (it takes no
|
|
3802
|
+
value). It is caller intent, never trust consent: with it they run the
|
|
3803
|
+
source whatever the host's `automations.trust` and the trigger's `runsOn`
|
|
3804
|
+
say, and trust, `runsOn` and `owner` gate the tick exactly as before (the
|
|
3805
|
+
tick passes the flag to its own child). Without it, on a capability
|
|
3806
|
+
source's trigger: `E_TRIGGER_SOURCE_RUN`, `ok: false`, a non-zero exit,
|
|
3807
|
+
`details: {capability, source, flag: "--run-source"}`, and a message
|
|
3808
|
+
naming the command to run again (`oats trigger test|poll <id>
|
|
3809
|
+
--run-source`), and the trigger's `runsOn` when that is another host: it
|
|
3810
|
+
holds only the id, the capability and source names and `runsOn`, never
|
|
3811
|
+
text of the source's. Nothing of the capability has executed and nothing
|
|
3812
|
+
has been written in the deployment, the soul's copy under `agents/` and
|
|
3813
|
+
the capability's directory in the module store included. The
|
|
3814
|
+
order is fixed: a valid definition (`E_TRIGGER_INVALID`), then its meaning
|
|
3815
|
+
and the soul's resolution (`E_TRIGGER_SOURCE`, `E_TRIGGER_INVALID
|
|
3816
|
+
{field}`, `E_TRIGGER_POLL` `cause: "resolution"`), then this gate, then
|
|
3817
|
+
the run. On a `github.pull_request` trigger the flag is accepted and
|
|
3818
|
+
inert: `test` answers byte for byte the same.
|
|
3819
|
+
- **What a `triggerApi: 1` reader sees.** `triggerApi` stays 1. `on.source`
|
|
3820
|
+
is an open string: tell rows apart by it, and gate on `trigger-sources`.
|
|
3821
|
+
The keys above (`source`, `invalidEvents`, `skipped`, a meaning failure's
|
|
3822
|
+
`invalid`, `test`'s `source`) appear only on capability-source rows and
|
|
3823
|
+
are absent, not `null`, on a `github.pull_request` row, whose outputs are
|
|
3824
|
+
exactly as before. On a capability source's rows the PR-only fields are
|
|
3825
|
+
`null` (`repo`, `number`) or absent (`on.repo`, `on.labels`, `on.base`,
|
|
3826
|
+
`wouldFire[].repo`), and `lastPoll` carries the counts above instead of
|
|
3827
|
+
`prs` and `matching`.
|
|
3599
3828
|
- A triggered instance records `instance.json.trigger`: `{id, key, source,
|
|
3600
3829
|
repo, number, subject, url, event, headSha, observedAt, eventFile}`
|
|
3601
3830
|
(`subject` since 0.49.0; `null` when the event had none). Its event file is
|
|
3602
3831
|
`OATS_TRIGGER_EVENT_FILE`: `{trigger, source, repo, number, subject, url,
|
|
3603
|
-
event, headSha, labels, observedAt, key}`.
|
|
3832
|
+
event, headSha, labels, observedAt, key}`. For a capability source the
|
|
3833
|
+
record has `repo: null`, `number: null`, `headSha: null` and adds `fields`,
|
|
3834
|
+
and the event file is `{trigger, source, subject, event, key, url?,
|
|
3835
|
+
fields, observedAt}`.
|
|
3604
3836
|
- `update <id> --description=<text>` (feature `automation-descriptions`)
|
|
3605
3837
|
changes only a local trigger's description; `--description=` (empty)
|
|
3606
3838
|
removes it. It sets `updatedAt` and leaves fired and pending events
|
|
3607
3839
|
untouched. `<id>` is `local/<id>` or the bare id; a workspace trigger
|
|
3608
3840
|
refuses `E_AUTOMATION_WORKSPACE`. Any other flag is `E_BAD_ARGS` ("only
|
|
3609
3841
|
--description is supported for now"). An older kernel has no `update`.
|
|
3842
|
+
- `add` of a capability source's trigger checks its meaning against the
|
|
3843
|
+
soul's resolution before anything is written (`E_TRIGGER_SOURCE`,
|
|
3844
|
+
`E_TRIGGER_INVALID {field}`, or the soul's own resolution error).
|
|
3610
3845
|
- Errors: `E_TRIGGER_INVALID {field}`, `E_TRIGGER_EXISTS`,
|
|
3611
|
-
`E_TRIGGER_UNKNOWN`, `E_TRIGGER_TEAMS`, `
|
|
3612
|
-
|
|
3846
|
+
`E_TRIGGER_UNKNOWN`, `E_TRIGGER_TEAMS`, `E_TRIGGER_SOURCE {capability,
|
|
3847
|
+
source, pointer?}` (a capability source that is undeclared or malformed,
|
|
3848
|
+
whose capability the soul does not compose, or whose command is not a file
|
|
3849
|
+
inside the capability; `pointer` is a JSON pointer into the manifest),
|
|
3850
|
+
`E_TRIGGER_POLL` (`details.cause` and `details.source` for a capability
|
|
3851
|
+
source), `E_TRIGGER_SOURCE_RUN {capability, source, flag}` (`test` or
|
|
3852
|
+
`poll` of a capability source's trigger without `--run-source`: nothing
|
|
3853
|
+
ran, nothing was written), `E_TRIGGER_FAILED`, `E_BAD_ARGS`, `E_PACKAGE_MISSING`,
|
|
3613
3854
|
`E_PACKAGE_MANIFEST`, `E_LOCAL_MISSING`.
|
|
3614
3855
|
|
|
3615
3856
|
<a id="automations-shared-rows"></a>
|
|
@@ -3681,7 +3922,12 @@ registered). `maxConcurrent` is the effective scheduled-job cap (default 5);
|
|
|
3681
3922
|
`number`, `subject`, `url`, `instance`, `nameCut`; a dry run previews the
|
|
3682
3923
|
soul as a tick does, and reports a preview failure or a name that cannot
|
|
3683
3924
|
fit as `spawn-failed`), `invalid` and
|
|
3684
|
-
`not-here`. A
|
|
3925
|
+
`not-here`. A capability source's trigger adds `poll-deferred`
|
|
3926
|
+
(`deadline`: its poll could not end by 50 s after the tick started; it
|
|
3927
|
+
goes first next tick), its `polled` carries `events`, `invalidEvents`,
|
|
3928
|
+
`skipped` and `filtered`, `poll-failed` a `cause`, `invalid` a failed
|
|
3929
|
+
meaning check, and its `would-fire` has no `number`, and no `url` when the
|
|
3930
|
+
event has none. A workspace schedule's state key is `<member>~<id>`. A failed
|
|
3685
3931
|
snapshot refresh is `{workspace, action: "error", error}`.
|
|
3686
3932
|
|
|
3687
3933
|
<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
|