@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.
Files changed (47) hide show
  1. package/bin/oats.mjs +326 -28
  2. package/docs/capabilities.md +425 -8
  3. package/docs/capability-manifest.schema.json +60 -5
  4. package/docs/configuration.md +103 -0
  5. package/docs/desktop-cli-api.md +542 -47
  6. package/docs/desktop.md +85 -5
  7. package/docs/execution-targets.md +50 -9
  8. package/docs/implementation.md +74 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +4 -4
  12. package/docs/packages.md +28 -14
  13. package/docs/release-lane.md +41 -0
  14. package/docs/release-notes/v0.49.0.md +770 -0
  15. package/docs/release-notes/v0.50.0.md +279 -0
  16. package/docs/schedules.md +289 -53
  17. package/docs/servers.md +7 -0
  18. package/docs/souls-and-instances.md +450 -60
  19. package/docs/workspaces.md +3 -3
  20. package/injects/work-checkout.md +17 -11
  21. package/injects/work-worktree.md +19 -13
  22. package/lib/capability-contract.mjs +100 -11
  23. package/lib/capability-show.mjs +18 -2
  24. package/lib/core.mjs +1374 -394
  25. package/lib/instance-events.mjs +9 -10
  26. package/lib/instance-git.mjs +19 -10
  27. package/lib/instance-inspect.mjs +58 -18
  28. package/lib/instance-lifecycle.mjs +106 -16
  29. package/lib/instance-resolution.mjs +15 -3
  30. package/lib/launch-prompt-policy.mjs +17 -3
  31. package/lib/packages.mjs +1 -0
  32. package/lib/real-path.mjs +27 -0
  33. package/lib/refused-text.mjs +17 -0
  34. package/lib/resolve.mjs +4 -4
  35. package/lib/retained-after-retire.mjs +387 -0
  36. package/lib/retire-output.mjs +6 -1
  37. package/lib/schedule.mjs +9 -2
  38. package/lib/servers.mjs +32 -6
  39. package/lib/tree-copy.mjs +18 -7
  40. package/lib/trigger-sources.mjs +234 -0
  41. package/lib/triggers.mjs +705 -108
  42. package/lib/workspace.mjs +20 -5
  43. package/lib/worktree-hooks.mjs +392 -0
  44. package/lib/worktree.mjs +655 -0
  45. package/package-catalog.json +3 -3
  46. package/package.json +1 -1
  47. package/skills/oats-getting-started/SKILL.md +1 -1
@@ -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
@@ -101,6 +193,12 @@ default. A home not yet created uses its resolved existing directory ancestor
101
193
  plus its intended suffix; launch checks the created home's identity again.
102
194
  No existing home is enabled automatically. Removing an entry disables consent
103
195
  for future launches.
196
+ On a case-insensitive filesystem (the macOS default) one home has several
197
+ letter-case spellings, and a key in any of them is valid. A key spelled exactly
198
+ as the home is launched decides. Otherwise the single key naming the same
199
+ directory decides, and `consentSource` points at that key. Several keys naming
200
+ it in different case, with none spelled exactly, decide nothing: no consent.
201
+ Consent never reaches another directory.
104
202
 
105
203
  The sole confirmation covered is Claude's development-channel prompt for
106
204
  `plugin:aweb-channel@awebai-marketplace`. The provider's `claudeChannelMode`
@@ -108,6 +206,8 @@ selects arguments; it does not grant consent. Approved-mode arguments, another
108
206
  plugin, multiple plugins or contradictory channel arguments cannot qualify.
109
207
  Environment values, spawn flags and saved launch recipes cannot enable consent.
110
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).
111
211
 
112
212
  Preview reports effective `launchPromptAnswers.awebDevelopmentChannel` and
113
213
  `consentSource` without terminal capture or input. `--no-launch` never answers.
@@ -392,6 +492,9 @@ is safe to delete.
392
492
  - **Per-instance provider facts:** `oats spawn <soul> --provider <cap> key=value`,
393
493
  recorded in the instance's `instance.json`.
394
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)).
395
498
 
396
499
  ## Inspecting the effective configuration
397
500