@awebai/oats 0.69.23 → 0.70.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 (88) hide show
  1. package/bin/oats.mjs +112 -20
  2. package/docs/capabilities.md +697 -11
  3. package/docs/capability-manifest.schema.json +66 -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 +322 -0
  7. package/docs/design/README.md +7 -3
  8. package/docs/desktop-cli-api.md +330 -9
  9. package/docs/desktop.md +181 -48
  10. package/docs/execution-targets.md +210 -4
  11. package/docs/first-team.md +11 -0
  12. package/docs/implementation.md +24 -3
  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/release-notes/v0.70.0.md +155 -0
  21. package/docs/souls-and-instances.md +57 -0
  22. package/docs/trust-model.md +8 -1
  23. package/docs/tui.md +21 -1
  24. package/docs/upgrading.md +19 -5
  25. package/docs/workspaces.md +13 -5
  26. package/lib/automation-scope.mjs +1 -1
  27. package/lib/capability-show.mjs +20 -1
  28. package/lib/command-flags.mjs +2 -2
  29. package/lib/compile-cache.mjs +1 -1
  30. package/lib/core.mjs +1455 -203
  31. package/lib/errors.mjs +4 -1
  32. package/lib/home-integrity.mjs +329 -0
  33. package/lib/hook-env.mjs +107 -0
  34. package/lib/host-run.mjs +11 -3
  35. package/lib/instance-events.mjs +32 -5
  36. package/lib/instance-git.mjs +9 -0
  37. package/lib/instance-inspect.mjs +107 -9
  38. package/lib/instance-lifecycle.mjs +15 -3
  39. package/lib/instance-listing.mjs +101 -8
  40. package/lib/instance-resolution.mjs +85 -2
  41. package/lib/instance-upgrade.mjs +170 -14
  42. package/lib/kernel-features.mjs +10 -1
  43. package/lib/node-version.mjs +9 -0
  44. package/lib/provider-call-child.mjs +60 -0
  45. package/lib/provider-resume.mjs +83 -0
  46. package/lib/provider-test-seams.mjs +20 -0
  47. package/lib/read-call.mjs +2 -0
  48. package/lib/remote.mjs +33 -1
  49. package/lib/reserved-launch-env.mjs +8 -1
  50. package/lib/retire-admission.mjs +12 -1
  51. package/lib/sandbox-allowances.mjs +329 -0
  52. package/lib/schedule.mjs +14 -4
  53. package/lib/servers.mjs +38 -5
  54. package/lib/session-inspect.mjs +123 -87
  55. package/lib/session-providers.mjs +575 -0
  56. package/lib/session-receipt.mjs +93 -0
  57. package/lib/session-resume.mjs +68 -15
  58. package/lib/stable-node.mjs +3 -0
  59. package/lib/triggers.mjs +3 -1
  60. package/lib/upgrade-state.mjs +6 -1
  61. package/lib/worktree-hooks.mjs +18 -2
  62. package/lib/worktree.mjs +21 -7
  63. package/package-catalog.json +2 -2
  64. package/package.json +2 -1
  65. package/packages/client/capability-list.mjs +21 -0
  66. package/packages/client/cli-adapter.mjs +19 -4
  67. package/packages/client/cli-locator.mjs +5 -1
  68. package/packages/client/deployment-data.mjs +23 -1
  69. package/packages/client/deployment-panel.mjs +25 -3
  70. package/packages/client/home-board.mjs +33 -19
  71. package/packages/client/inspect-boundary.mjs +18 -8
  72. package/packages/client/instance-acts.mjs +30 -3
  73. package/packages/client/instance-board.mjs +206 -0
  74. package/packages/client/instance-presentation.mjs +55 -0
  75. package/packages/client/liveness.mjs +15 -4
  76. package/packages/client/own-codes.mjs +5 -1
  77. package/packages/client/remote-roster.mjs +6 -1
  78. package/packages/client/session-backends.mjs +31 -0
  79. package/packages/client/session-start.mjs +18 -6
  80. package/packages/client/spawn-apply-cli.mjs +5 -3
  81. package/packages/client/spawn-apply-contract.mjs +25 -2
  82. package/packages/client/spawn-apply.mjs +5 -1
  83. package/packages/client/spawn-messages.mjs +3 -0
  84. package/packages/client/terminal-contract.mjs +4 -0
  85. package/packages/client/waiting-on-you.mjs +12 -2
  86. package/packages/tui/lib/model.mjs +14 -3
  87. package/packages/tui/lib/store.mjs +12 -3
  88. 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,36 @@
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
+ "wire": { "type": "string", "pattern": "^[0-9]{1,3}\\.[0-9]{1,3}$", "description": "The version of the session-provider wire this provider speaks (docs/capabilities.md, The call). A kernel calls only a provider that declares its own version: one that declares another, or none (a provider from before the key, wire 1.2), is refused E_BACKEND_WIRE, naming both." },
270
+ "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." },
271
+ "commands": {
272
+ "type": "object",
273
+ "required": ["launch", "inspect", "input", "stop"],
274
+ "additionalProperties": false,
275
+ "description": "The provider's verbs, each naming one of this manifest's commands.",
276
+ "properties": {
277
+ "launch": { "type": "string", "minLength": 1, "description": "Starts the instance's session; answers the endpoint the kernel records." },
278
+ "inspect": { "type": "string", "minLength": 1, "description": "Answers one session's { present, state, running, open? }." },
279
+ "input": { "type": "string", "minLength": 1, "description": "Sends one text to the session; answers { submitted: true, verified } only when it was dispatched." },
280
+ "stop": { "type": "string", "minLength": 1, "description": "Stops the session; answers { stopped: true }." },
281
+ "inspectMany": { "type": "string", "minLength": 1, "description": "Optional: inspects several homes' sessions in one call (oats status)." },
282
+ "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." }
283
+ }
284
+ }
285
+ }
286
+ }
287
+ },
251
288
  "triggerSources": {
252
289
  "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
290
  "type": "object",
@@ -317,6 +354,34 @@
317
354
  "additionalProperties": {"$ref":"#/$defs/OptionalHook"},
318
355
  "description": "Lifecycle events to commands. An event this kernel does not run (a newer kernel's) is accepted with a warning and ignored, unless it is declared required: that is refused. Kernels before 0.49.0 refuse every unknown event."
319
356
  },
357
+ "sandboxDomains": {
358
+ "description": "Sandbox allowances (docs/capabilities.md, Sandbox allowances): the hosts a session provider may add to its harness's sandbox for an instance whose messaging, knowledge or tasks slot this capability fills. Each entry names one of this capability's settings; the kernel reads the setting's value from the deployment's configuration (never from an instance home) and takes its host: a URL's host, a bare host, or, for a map from team id to one of those, the hosts of the instance's own teams. Only a capability that declares `layer` may carry the key, and only the capability that fills the slot contributes: on any other capability a session-provider launch is refused (E_BACKEND_SANDBOX_HOST), never the line dropped. A tmux launch does not read it. A kernel from before session providers ignores the key. One rule this schema does not express: a setting is named by ONE line (two lines for the same setting, of either form, refuse the launch).",
359
+ "type": "array",
360
+ "minItems": 1,
361
+ "maxItems": 16,
362
+ "items": {
363
+ "oneOf": [
364
+ {
365
+ "type": "object",
366
+ "required": ["setting"],
367
+ "properties": {
368
+ "setting": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$", "description": "The key of one of this capability's settings, whose value is a URL, a bare host, or a map from team id to one of those." },
369
+ "optional": { "type": "boolean", "description": "true: the session works without this host. A value the deployment does not hold is then reported and is no reason for a session provider to refuse a launch." }
370
+ },
371
+ "additionalProperties": false
372
+ },
373
+ {
374
+ "type": "object",
375
+ "required": ["settingFile", "urls"],
376
+ "properties": {
377
+ "settingFile": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$", "description": "The key of one of this capability's settings, whose value is the path of a JSON file of the deployment (never inside an instance home; a regular file reached through no symbolic link, at most 64 KiB, strict JSON)." },
378
+ "urls": { "type": "string", "pattern": "^(/([^/~]|~[01])+){1,16}$", "not": { "pattern": "/\\*(/.*)?/\\*(/|$)" }, "maxLength": 400, "description": "A JSON pointer into that file, of which at most one segment may be `*` (every key of an object, every element of an array): each string there that is a URL or a git remote gives its host, at most 16 hosts a file." }
379
+ },
380
+ "additionalProperties": false
381
+ }
382
+ ]
383
+ }
384
+ },
320
385
  "settings": {
321
386
  "type": "object",
322
387
  "description": "Declared capability settings: name to { default, values?, description }. Documentation for the values a soul, oats-local.yaml or `oats spawn --provider` supplies; undeclared settings are still accepted.",
@@ -400,5 +465,6 @@
400
465
  "additionalProperties": false
401
466
  }
402
467
  },
468
+ "dependentRequired": { "sandboxDomains": ["layer"] },
403
469
  "additionalProperties": false
404
470
  }
@@ -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