@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.
- package/bin/oats.mjs +112 -20
- package/docs/capabilities.md +697 -11
- package/docs/capability-manifest.schema.json +66 -0
- package/docs/configuration.md +27 -7
- package/docs/design/2026-11-19-sandboxes.md +595 -121
- package/docs/design/2026-11-20-provider-home-lifecycle.md +322 -0
- package/docs/design/README.md +7 -3
- package/docs/desktop-cli-api.md +330 -9
- package/docs/desktop.md +181 -48
- package/docs/execution-targets.md +210 -4
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +24 -3
- package/docs/integrations.md +2 -2
- package/docs/knowledge-capability-authoring.md +1 -1
- package/docs/knowledge-reference/proposal.md +10 -0
- package/docs/knowledge.md +20 -11
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.69.24.md +264 -0
- package/docs/release-notes/v0.70.0.md +155 -0
- package/docs/souls-and-instances.md +57 -0
- package/docs/trust-model.md +8 -1
- package/docs/tui.md +21 -1
- package/docs/upgrading.md +19 -5
- package/docs/workspaces.md +13 -5
- package/lib/automation-scope.mjs +1 -1
- package/lib/capability-show.mjs +20 -1
- package/lib/command-flags.mjs +2 -2
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1455 -203
- package/lib/errors.mjs +4 -1
- package/lib/home-integrity.mjs +329 -0
- package/lib/hook-env.mjs +107 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-events.mjs +32 -5
- package/lib/instance-git.mjs +9 -0
- package/lib/instance-inspect.mjs +107 -9
- package/lib/instance-lifecycle.mjs +15 -3
- package/lib/instance-listing.mjs +101 -8
- package/lib/instance-resolution.mjs +85 -2
- package/lib/instance-upgrade.mjs +170 -14
- package/lib/kernel-features.mjs +10 -1
- package/lib/node-version.mjs +9 -0
- package/lib/provider-call-child.mjs +60 -0
- package/lib/provider-resume.mjs +83 -0
- package/lib/provider-test-seams.mjs +20 -0
- package/lib/read-call.mjs +2 -0
- package/lib/remote.mjs +33 -1
- package/lib/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +12 -1
- package/lib/sandbox-allowances.mjs +329 -0
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +38 -5
- package/lib/session-inspect.mjs +123 -87
- package/lib/session-providers.mjs +575 -0
- package/lib/session-receipt.mjs +93 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- package/lib/upgrade-state.mjs +6 -1
- package/lib/worktree-hooks.mjs +18 -2
- package/lib/worktree.mjs +21 -7
- package/package-catalog.json +2 -2
- package/package.json +2 -1
- package/packages/client/capability-list.mjs +21 -0
- package/packages/client/cli-adapter.mjs +19 -4
- package/packages/client/cli-locator.mjs +5 -1
- package/packages/client/deployment-data.mjs +23 -1
- package/packages/client/deployment-panel.mjs +25 -3
- package/packages/client/home-board.mjs +33 -19
- package/packages/client/inspect-boundary.mjs +18 -8
- package/packages/client/instance-acts.mjs +30 -3
- package/packages/client/instance-board.mjs +206 -0
- package/packages/client/instance-presentation.mjs +55 -0
- package/packages/client/liveness.mjs +15 -4
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/remote-roster.mjs +6 -1
- package/packages/client/session-backends.mjs +31 -0
- package/packages/client/session-start.mjs +18 -6
- package/packages/client/spawn-apply-cli.mjs +5 -3
- package/packages/client/spawn-apply-contract.mjs +25 -2
- package/packages/client/spawn-apply.mjs +5 -1
- package/packages/client/spawn-messages.mjs +3 -0
- package/packages/client/terminal-contract.mjs +4 -0
- package/packages/client/waiting-on-you.mjs +12 -2
- package/packages/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- 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
|
}
|
package/docs/configuration.md
CHANGED
|
@@ -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`)
|
|
319
|
-
|
|
320
|
-
capabilities manage it at every start,
|
|
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
|
-
|
|
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`)
|
|
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
|