@awebai/oats 0.69.23 → 0.69.24

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 (74) hide show
  1. package/bin/oats.mjs +56 -17
  2. package/docs/capabilities.md +353 -5
  3. package/docs/capability-manifest.schema.json +36 -0
  4. package/docs/configuration.md +27 -7
  5. package/docs/design/2026-11-19-sandboxes.md +595 -121
  6. package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
  7. package/docs/design/README.md +7 -3
  8. package/docs/desktop-cli-api.md +257 -9
  9. package/docs/desktop.md +181 -48
  10. package/docs/execution-targets.md +186 -3
  11. package/docs/first-team.md +11 -0
  12. package/docs/implementation.md +5 -1
  13. package/docs/integrations.md +2 -2
  14. package/docs/knowledge-capability-authoring.md +1 -1
  15. package/docs/knowledge-reference/proposal.md +10 -0
  16. package/docs/knowledge.md +20 -11
  17. package/docs/official-catalog.md +2 -2
  18. package/docs/packages.md +7 -7
  19. package/docs/release-notes/v0.69.24.md +264 -0
  20. package/docs/souls-and-instances.md +45 -0
  21. package/docs/tui.md +21 -1
  22. package/docs/upgrading.md +12 -5
  23. package/docs/workspaces.md +13 -5
  24. package/lib/capability-show.mjs +11 -1
  25. package/lib/command-flags.mjs +2 -2
  26. package/lib/compile-cache.mjs +1 -1
  27. package/lib/core.mjs +1176 -181
  28. package/lib/errors.mjs +4 -1
  29. package/lib/hook-env.mjs +106 -0
  30. package/lib/host-run.mjs +11 -3
  31. package/lib/instance-inspect.mjs +44 -0
  32. package/lib/instance-lifecycle.mjs +15 -3
  33. package/lib/instance-listing.mjs +97 -8
  34. package/lib/kernel-features.mjs +10 -1
  35. package/lib/node-version.mjs +9 -0
  36. package/lib/provider-call-child.mjs +60 -0
  37. package/lib/provider-resume.mjs +83 -0
  38. package/lib/provider-test-seams.mjs +20 -0
  39. package/lib/read-call.mjs +2 -0
  40. package/lib/reserved-launch-env.mjs +8 -1
  41. package/lib/retire-admission.mjs +5 -1
  42. package/lib/schedule.mjs +14 -4
  43. package/lib/servers.mjs +28 -4
  44. package/lib/session-inspect.mjs +104 -13
  45. package/lib/session-providers.mjs +528 -0
  46. package/lib/session-resume.mjs +68 -15
  47. package/lib/stable-node.mjs +3 -0
  48. package/lib/triggers.mjs +3 -1
  49. package/package-catalog.json +2 -2
  50. package/package.json +2 -1
  51. package/packages/client/capability-list.mjs +21 -0
  52. package/packages/client/cli-adapter.mjs +19 -4
  53. package/packages/client/cli-locator.mjs +5 -1
  54. package/packages/client/deployment-data.mjs +23 -1
  55. package/packages/client/deployment-panel.mjs +25 -3
  56. package/packages/client/home-board.mjs +33 -19
  57. package/packages/client/inspect-boundary.mjs +18 -8
  58. package/packages/client/instance-acts.mjs +30 -3
  59. package/packages/client/instance-board.mjs +206 -0
  60. package/packages/client/instance-presentation.mjs +55 -0
  61. package/packages/client/liveness.mjs +15 -4
  62. package/packages/client/own-codes.mjs +5 -1
  63. package/packages/client/remote-roster.mjs +6 -1
  64. package/packages/client/session-backends.mjs +31 -0
  65. package/packages/client/session-start.mjs +18 -6
  66. package/packages/client/spawn-apply-cli.mjs +5 -3
  67. package/packages/client/spawn-apply-contract.mjs +25 -2
  68. package/packages/client/spawn-apply.mjs +5 -1
  69. package/packages/client/spawn-messages.mjs +3 -0
  70. package/packages/client/terminal-contract.mjs +4 -0
  71. package/packages/client/waiting-on-you.mjs +12 -2
  72. package/packages/tui/lib/model.mjs +14 -3
  73. package/packages/tui/lib/store.mjs +12 -3
  74. package/skills/oats-getting-started/SKILL.md +3 -3
@@ -165,6 +165,13 @@
165
165
  "description": "Applies only when every named capability setting has the given effective value (a requirement conditional on configuration, e.g. delivery: channel).",
166
166
  "additionalProperties": {}
167
167
  },
168
+ "backends": {
169
+ "type": "array",
170
+ "description": "The session backends this requirement is for (feature session-providers): \"tmux\", \"session-provider\" (any session provider), or both. Without the key the requirement applies to every backend. A manifest that uses it needs a kernel that lists session-providers: an older kernel applies the row to every launch.",
171
+ "minItems": 1,
172
+ "uniqueItems": true,
173
+ "items": { "enum": ["tmux", "session-provider"] }
174
+ },
168
175
  "minVersion": {
169
176
  "type": "string",
170
177
  "description": "Lowest acceptable installed version of the package, read from the package.json under the install directory the harness's listing names; an older or absent manifest fails the requirement with the install remedy.",
@@ -248,6 +255,35 @@
248
255
  }
249
256
  }
250
257
  },
258
+ "sessionProviders": {
259
+ "description": "Session providers (feature session-providers): session backends this capability supplies beside the kernel's own tmux. `oats spawn --backend <name>` (a schedule's backend, a trigger's spawn.backend) selects one among the instance's capabilities; the kernel then calls the named commands for that instance's session, each with one JSON request on stdin and one JSON answer on stdout (docs/capabilities.md, Session providers). Validated only where a provider is used, never when the capability loads: a malformed declaration cannot be selected (E_BACKEND_UNKNOWN) and nothing else changes. What JSON Schema cannot say is checked there too: each command names one of this manifest's commands.",
260
+ "type": "object",
261
+ "maxProperties": 16,
262
+ "propertyNames": { "pattern": "^[a-z0-9][a-z0-9-]{0,39}$", "not": { "enum": ["tmux", "session-provider", "herdr"] } },
263
+ "additionalProperties": {
264
+ "type": "object",
265
+ "required": ["commands", "harnesses"],
266
+ "additionalProperties": false,
267
+ "properties": {
268
+ "description": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^\\u0000-\\u001f\\u007f-\\u009f\\u2028\\u2029]*$" },
269
+ "harnesses": { "type": "array", "minItems": 1, "maxItems": 16, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{0,39}$" }, "description": "The harnesses this backend runs. A spawn or a start on another is refused E_BACKEND_HARNESS before anything is created or stopped." },
270
+ "commands": {
271
+ "type": "object",
272
+ "required": ["launch", "inspect", "input", "stop"],
273
+ "additionalProperties": false,
274
+ "description": "The provider's verbs, each naming one of this manifest's commands.",
275
+ "properties": {
276
+ "launch": { "type": "string", "minLength": 1, "description": "Starts the instance's session; answers the endpoint the kernel records." },
277
+ "inspect": { "type": "string", "minLength": 1, "description": "Answers one session's { present, state, running, open? }." },
278
+ "input": { "type": "string", "minLength": 1, "description": "Sends one text to the session; answers { submitted: true, verified } only when it was dispatched." },
279
+ "stop": { "type": "string", "minLength": 1, "description": "Stops the session; answers { stopped: true }." },
280
+ "inspectMany": { "type": "string", "minLength": 1, "description": "Optional: inspects several homes' sessions in one call (oats status)." },
281
+ "check": { "type": "string", "minLength": 1, "description": "Optional: the provider's readiness for a home or a soul, { status, problems, warnings }. oats readiness relays it, and the kernel asks it right before every launch." }
282
+ }
283
+ }
284
+ }
285
+ }
286
+ },
251
287
  "triggerSources": {
252
288
  "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
289
  "type": "object",
@@ -40,7 +40,6 @@ launch-configs: # named ways this host starts a har
40
40
  personal:
41
41
  harness: claude
42
42
  executable: "./bin/claude-wrapper.sh" # relative → against this deployment directory
43
- args: ["--verbose"]
44
43
  env:
45
44
  CLAUDE_CONFIG_DIR: { fromEnv: PERSONAL_CLAUDE_DIR }
46
45
  model: opus
@@ -304,6 +303,19 @@ configuration is a host choice: a soul never names one.
304
303
  crosses harnesses.
305
304
  - The executable must be a regular executable file; it is never run to probe
306
305
  it.
306
+ - **`args` and package verification.** When any active capability declares
307
+ an applicable harness package requirement for the selected harness, a
308
+ configuration with any non-empty `args` is refused at spawn with
309
+ `E_LAUNCH_PROBE_UNSUPPORTED`; nothing is created. With `oats.aweb`, every
310
+ Claude launch has such a requirement. The package probe runs
311
+ `claude plugin list --json`, which cannot carry the launch's args;
312
+ arguments such as `--settings` can change which plugins load, so that
313
+ probe could not verify the actual launch. There is no passthrough or
314
+ exception for permission flags. Put native settings in the user
315
+ `settings.json` of the Claude config the launch uses: for agents only,
316
+ set `CLAUDE_CONFIG_DIR` through the configuration's `env`, which the
317
+ probe does carry. The other supported route is a wrapper `executable`,
318
+ which both the launch and the package probe use.
307
319
  - `oats launch-config list` shows the effective entries;
308
320
  `oats launch-config set <name> --file <json>` and
309
321
  `oats launch-config remove <name>` rewrite only this block, under the
@@ -315,9 +327,10 @@ configuration is a host choice: a soul never names one.
315
327
  `deprecated-runtime-name` warning.
316
328
  - **Claude's permissions** are Claude's own settings, not OATS keys. They go
317
329
  in the user settings of the Claude config a launch uses (its
318
- `CLAUDE_CONFIG_DIR`, else `~/.claude`), or `--permission-mode` goes in a
319
- configuration's `args`. Never in a home's `.claude/settings.json`: the
320
- capabilities manage it at every start, and Claude ignores auto mode there.
330
+ `CLAUDE_CONFIG_DIR`, else `~/.claude`): set
331
+ `"permissions": {"defaultMode": "auto"}` there for auto mode. Never in a
332
+ home's `.claude/settings.json`: the capabilities manage it at every start,
333
+ and Claude ignores auto mode there.
321
334
  oats.setup's `/oats-agent-permissions` (oats.framework 1.13.0) teaches the
322
335
  setup: auto mode, narrow allow rules for the `oats` and `gh` reads,
323
336
  `oats spawn` and reading `aw` mail and chat, and what stays gated.
@@ -334,10 +347,14 @@ person; nothing in OATS writes it.
334
347
  launch-configs:
335
348
  claude-auto:
336
349
  harness: claude
337
- args: ["--permission-mode", "auto"]
350
+ env:
351
+ CLAUDE_CONFIG_DIR: { fromEnv: AGENTS_CLAUDE_DIR }
338
352
  default: true
339
353
  ```
340
354
 
355
+ Here `AGENTS_CLAUDE_DIR` names an agents-only Claude config directory;
356
+ its user `settings.json` sets `"permissions": {"defaultMode": "auto"}`.
357
+
341
358
  - **One key.** The file holds `launch-configs:` and nothing else. Its entries
342
359
  have exactly the schema of the deployment's block and the same checks.
343
360
  - **Missing or broken.** A missing file declares nothing. A file that is there
@@ -385,7 +402,8 @@ launch-configs:
385
402
  `default: true` makes a configuration this host's baseline for its harness
386
403
  (0.32, feature `launch-config-default`). Use it for what every launch of a
387
404
  harness on this machine needs, whatever soul or preference chose it: an
388
- account directory (`CLAUDE_CONFIG_DIR`), a wrapper `executable`, an argument.
405
+ account directory (`CLAUDE_CONFIG_DIR`) or a wrapper `executable`. Its `args`
406
+ are subject to the package-verification refusal above.
389
407
 
390
408
  - **When it applies:** a new launch that picks the harness without naming a
391
409
  configuration: a soul's `launch:`, an inline `souls.launch` preference,
@@ -632,7 +650,9 @@ came from, the executable, args, env, model, yolo, and each capability's
632
650
  launch contribution with its settings and trust, and the kernel that launched
633
651
  it (`kernelBin`, re-written by every start). One renderer turns it into
634
652
  the `command`. Configuration `args` go after the harness's own options and
635
- before capability arguments; every argument is single-quoted.
653
+ before capability arguments; every argument is single-quoted. The
654
+ [package-verification refusal](#launch-configurations) applies to these
655
+ `args`.
636
656
 
637
657
  **Starting and restarting a home.** `oats session start --home <abs>` runs
638
658
  the recorded recipe. With `--launch-config`, `--harness` or `--yolo`, the