@awebai/oats 0.47.0 → 0.49.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 (44) hide show
  1. package/bin/oats.mjs +293 -41
  2. package/docs/capabilities.md +264 -8
  3. package/docs/capability-manifest.schema.json +18 -5
  4. package/docs/configuration.md +7 -1
  5. package/docs/desktop-cli-api.md +439 -40
  6. package/docs/desktop.md +72 -5
  7. package/docs/execution-targets.md +19 -1
  8. package/docs/implementation.md +81 -1
  9. package/docs/integrations.md +7 -5
  10. package/docs/knowledge.md +167 -197
  11. package/docs/official-catalog.md +6 -5
  12. package/docs/packages.md +14 -14
  13. package/docs/release-notes/v0.48.0.md +106 -0
  14. package/docs/release-notes/v0.49.0.md +770 -0
  15. package/docs/schedules.md +62 -39
  16. package/docs/servers.md +7 -0
  17. package/docs/souls-and-instances.md +395 -52
  18. package/docs/workspaces.md +18 -3
  19. package/injects/work-checkout.md +17 -11
  20. package/injects/work-worktree.md +19 -13
  21. package/lib/capability-contract.mjs +100 -11
  22. package/lib/capability-show.mjs +5 -2
  23. package/lib/core.mjs +1147 -319
  24. package/lib/instance-events.mjs +6 -3
  25. package/lib/instance-git.mjs +11 -5
  26. package/lib/instance-inspect.mjs +14 -3
  27. package/lib/instance-lifecycle.mjs +106 -16
  28. package/lib/instance-resolution.mjs +15 -3
  29. package/lib/launch-prompt-policy.mjs +17 -3
  30. package/lib/packages.mjs +1 -0
  31. package/lib/real-path.mjs +27 -0
  32. package/lib/resolve.mjs +4 -4
  33. package/lib/retire-output.mjs +6 -1
  34. package/lib/schedule.mjs +1 -0
  35. package/lib/servers.mjs +32 -6
  36. package/lib/teams-verbs.mjs +40 -9
  37. package/lib/tree-copy.mjs +18 -7
  38. package/lib/triggers.mjs +201 -65
  39. package/lib/workspace.mjs +20 -5
  40. package/lib/worktree-hooks.mjs +392 -0
  41. package/lib/worktree.mjs +655 -0
  42. package/package-catalog.json +12 -5
  43. package/package.json +1 -1
  44. package/skills/oats-getting-started/SKILL.md +1 -1
@@ -54,8 +54,8 @@ members: # repo refs, NO @revision (E_WORKSPAC
54
54
  - git:github.com/acme/tools # a member that ALSO publishes a package (see below)
55
55
 
56
56
  packages: # the ONLY versioned things
57
- oats.framework: v1.7.0 # bare version → resolves through the official catalog
58
- oats.okf: v4.1.1
57
+ oats.framework: v1.8.0 # bare version → resolves through the official catalog
58
+ oats.okf: v5.0.0
59
59
  acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
60
60
 
61
61
  teams: # SHARED teams: the same provider team for everyone
@@ -421,11 +421,26 @@ the workspace). A soul's teams are edited by a PR to `oats-workspace.yaml`:
421
421
  ```
422
422
  oats teams [--json] # the teams, ids, the default, localTeams, the workspace's souls:, problems
423
423
  oats teams add <label> --team <id> [--description d] # declare a local team (the first one becomes the local default)
424
+ oats teams add <label> --team <id> --no-default # the mapping only; the same label and id again is reuse
424
425
  oats teams remove <label> # refused while it is the local default (E_TEAM_IN_USE) or shared (E_TEAM_SHARED)
425
426
  oats teams default <label> # the local default
427
+ oats teams default <label> --if-absent # ... only where there is no effective default
428
+ oats teams default <label> --expect <label0> # ... only where the effective default is <label0>
426
429
  oats soul teams <soul>|'*' [--json] # a soul's default and teams here, and which souls: key gave them
427
430
  ```
428
431
 
432
+ `--if-absent` and `--expect` make a setup safe to run against a deployment
433
+ whose default it has not chosen: the condition is the effective default that
434
+ `oats teams` reports (the local one, else the workspace's), judged when the
435
+ file is written, and a failed one (`E_TEAM_DEFAULT_MISMATCH`) reports what it
436
+ found and writes nothing. A soul's `souls:` default is not the deployment's
437
+ default and is not looked at. Concurrent `oats teams` writes on one deployment
438
+ are serialized, so of two racing conditional writes the later one refuses;
439
+ hand edits to `oats-local.yaml` and changes to `oats-workspace.yaml` are not
440
+ serialized with them. Each form refuses a flag it does not take (`E_USAGE`).
441
+ Callers check for the feature `teams-conditional-default` in `oats version
442
+ --json` first: an older kernel ignores these flags.
443
+
429
444
  The messaging provider's own setup creates provider teams (see the provider's
430
445
  documentation). The spawn preview, `inspect` and `oats souls` report a soul's
431
446
  `teams` and `defaultTeam`; readiness reports the team problems in
@@ -441,7 +456,7 @@ Why it is shaped this way: [team model 3](design/2026-10-02-team-model-3.md).
441
456
 
442
457
  | What it is | Where | Example |
443
458
  |---|---|---|
444
- | True of every instance of the soul | `soul.yaml` → `knowledge:` / `messaging:` / `tasks:` | `messaging: { channels: [acme-eng] }`; `knowledge: { harvest-runtime: claude }` |
459
+ | True of every instance of the soul | `soul.yaml` → `knowledge:` / `messaging:` / `tasks:` | `messaging: { channels: [acme-eng] }`; `knowledge: { harvest: off }` |
445
460
  | A fact about this machine | `oats-local.yaml` → `settings.<cap>.<key>` (absolute paths are refused in the workspace file) | `settings.oats.okf.state-dir: /Users/ana/.oats/okf` |
446
461
  | A fact about **this spawn** | `oats spawn … --provider <cap> key=value` (repeatable; dotted keys nest) → `instance.json.providers.<cap>` | `--provider oats.aweb identity.source=/abs/path/to/retained/.aw` |
447
462
 
@@ -12,23 +12,29 @@ in the same tree as the human and possibly other agents.
12
12
  ### Extra trees
13
13
 
14
14
  When the work needs another branch, or another repository of this deployment,
15
- create an extra tree in your home. `<clone>` is any clone of this deployment
16
- (`oats-local.yaml` `clones:`, or `<deployment>/<repo>`); `origin` is its remote
17
- for that repository; `<base>` is the remote branch the work starts from (the
18
- branch itself, when you rework an existing one):
15
+ create an extra tree in your home. Run this from your home; `<base>` is the
16
+ remote branch the work starts from (the branch itself, when you rework an
17
+ existing one):
19
18
 
20
- git -C <clone> worktree add --detach "$OATS_INSTANCE_HOME/.work-<purpose>"
21
- git -C "$OATS_INSTANCE_HOME/.work-<purpose>" fetch --refmap= origin <base>
22
- git -C "$OATS_INSTANCE_HOME/.work-<purpose>" switch -c <branch> FETCH_HEAD
19
+ oats worktree add --purpose <purpose> --branch <branch> --base <base>
23
20
 
24
- - This starts from the remote's current state and moves none of the clone's
25
- refs. Never start from a local branch of the clone, which may be stale.
21
+ It makes `.work-<purpose>` in your home, on a new `<branch>` at `origin`'s
22
+ `<base>`. The repository is yours unless `--repo <member key|clone path>`
23
+ names another; `--preview` shows what it would do.
24
+
25
+ - It starts from the remote's current state and moves none of the clone's
26
+ refs. Never start a tree from a local branch of the clone, which may be stale.
26
27
  - Name `<branch>` by the repository's own rules, else `agents/<instance>-<purpose>`.
27
- If it already exists in that clone, `switch -c` refuses: use `<instance>/<branch>`.
28
+ If it already exists in that clone, `add` refuses: use `<instance>/<branch>`.
28
29
  Never `-C`/`-B`, which reset a branch someone else may own.
30
+ - If a capability of yours sets up new trees, `add` runs that setup, which
31
+ may take minutes: give it a long timeout, or run it in the background and
32
+ wait for it to exit. A killed `add` rolls back; run it again. Once it has
33
+ finished, running it again with the same arguments does nothing.
29
34
  - The tree has no upstream: push with `git push origin HEAD:<remote-branch>`
30
35
  (`<base>` when you rework an existing branch).
31
36
  - Before your task closes, merge each extra tree into your PR branch, or push its
32
37
  branch and name it in your hand-back; then
33
- `git -C <clone> worktree remove "$OATS_INSTANCE_HOME/.work-<purpose>"`.
38
+ `oats worktree remove --purpose <purpose>`, which keeps the branch and
39
+ refuses a tree with uncommitted work.
34
40
  Retirement keeps a tree that still holds uncommitted work, but don't rely on it.
@@ -4,8 +4,8 @@ Your `./work` is a **git worktree on your own branch** — a full checkout that
4
4
  yours alone: build, test and commit there, on your branch.
5
5
 
6
6
  - **Never work in a shared checkout** (the repo's main checkout, or any clone
7
- others use): don't edit, commit or switch branches there. Against a clone you
8
- run only `worktree add`/`remove` below. If unsure, `pwd`.
7
+ others use): don't edit, commit or switch branches there. A clone is touched
8
+ only through `oats worktree add`/`remove` below. If unsure, `pwd`.
9
9
  - Everything you change happens in `work/` or your extra trees — **including your
10
10
  own soul** when it lives in this repo: soul edits are branch changes, reviewed
11
11
  and merged like code.
@@ -14,23 +14,29 @@ yours alone: build, test and commit there, on your branch.
14
14
  ### Extra trees
15
15
 
16
16
  When the work needs another branch, or another repository of this deployment,
17
- create an extra tree in your home. `<clone>` is any clone of this deployment
18
- (`oats-local.yaml` `clones:`, or `<deployment>/<repo>`); `origin` is its remote
19
- for that repository; `<base>` is the remote branch the work starts from (the
20
- branch itself, when you rework an existing one):
17
+ create an extra tree in your home. Run this from your home; `<base>` is the
18
+ remote branch the work starts from (the branch itself, when you rework an
19
+ existing one):
21
20
 
22
- git -C <clone> worktree add --detach "$OATS_INSTANCE_HOME/.work-<purpose>"
23
- git -C "$OATS_INSTANCE_HOME/.work-<purpose>" fetch --refmap= origin <base>
24
- git -C "$OATS_INSTANCE_HOME/.work-<purpose>" switch -c <branch> FETCH_HEAD
21
+ oats worktree add --purpose <purpose> --branch <branch> --base <base>
25
22
 
26
- - This starts from the remote's current state and moves none of the clone's
27
- refs. Never start from a local branch of the clone, which may be stale.
23
+ It makes `.work-<purpose>` in your home, on a new `<branch>` at `origin`'s
24
+ `<base>`. The repository is yours unless `--repo <member key|clone path>`
25
+ names another; `--preview` shows what it would do.
26
+
27
+ - It starts from the remote's current state and moves none of the clone's
28
+ refs. Never start a tree from a local branch of the clone, which may be stale.
28
29
  - Name `<branch>` by the repository's own rules, else `agents/<instance>-<purpose>`.
29
- If it already exists in that clone, `switch -c` refuses: use `<instance>/<branch>`.
30
+ If it already exists in that clone, `add` refuses: use `<instance>/<branch>`.
30
31
  Never `-C`/`-B`, which reset a branch someone else may own.
32
+ - If a capability of yours sets up new trees, `add` runs that setup, which
33
+ may take minutes: give it a long timeout, or run it in the background and
34
+ wait for it to exit. A killed `add` rolls back; run it again. Once it has
35
+ finished, running it again with the same arguments does nothing.
31
36
  - The tree has no upstream: push with `git push origin HEAD:<remote-branch>`
32
37
  (`<base>` when you rework an existing branch).
33
38
  - Before your task closes, merge each extra tree into your PR branch, or push its
34
39
  branch and name it in your hand-back; then
35
- `git -C <clone> worktree remove "$OATS_INSTANCE_HOME/.work-<purpose>"`.
40
+ `oats worktree remove --purpose <purpose>`, which keeps the branch and
41
+ refuses a tree with uncommitted work.
36
42
  Retirement keeps a tree that still holds uncommitted work, but don't rely on it.
@@ -6,11 +6,16 @@
6
6
  *
7
7
  * Covers what the kernel enforces when it RUNS a capability, checked where the
8
8
  * manifest is READ instead: the launch environment a capability may declare
9
- * (names, namespaces), its hooks (approved events, declaration shape, `required`
10
- * only on spawn, the script inside the capability), and a provider payload's
11
- * value against the manifest's `settings.<key>.values`. Dependency-free. */
9
+ * (names, namespaces), its hooks (approved events, an unknown one a warning unless
10
+ * required; declaration shape, `required` only on spawn and worktree, the script
11
+ * inside the capability), and a provider payload's value against the manifest's
12
+ * `settings.<key>.values`. Dependency-free. */
12
13
 
13
- export const APPROVED_HOOKS = new Set(["soul-scaffold", "spawn", "retire", "launch"]);
14
+ export const APPROVED_HOOKS = new Set(["soul-scaffold", "spawn", "retire", "launch", "worktree"]);
15
+ /** The events whose hook may be declared `required: true`: each has a moment
16
+ * that can fail closed (a spawn's transaction; `oats worktree add`, which
17
+ * removes the tree it made). */
18
+ export const REQUIRABLE_HOOKS = new Set(["spawn", "worktree"]);
14
19
  export const PORTABLE_ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
15
20
  export const CAPABILITY_ENV_ID_RE = /^[a-z][a-z0-9]*\.[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
16
21
  export const CORE_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME"]);
@@ -34,9 +39,25 @@ export function hookScriptEscapes(command) {
34
39
  }
35
40
 
36
41
  /** Every contract problem of one manifest → [{ pointer, message }] (empty when it is sound).
37
- * Messages name the capability; `pointer` is the JSON pointer inside oats.json. */
42
+ * The problems of `manifestContract`, for a reader that has no warning channel. */
38
43
  export function manifestContractProblems(m) {
44
+ return manifestContract(m).problems;
45
+ }
46
+
47
+ /** One manifest against the kernel contract → { problems, warnings }, each
48
+ * [{ pointer, message }] (warnings also carry `code`). A problem refuses the
49
+ * manifest; a warning names what this kernel ignores in a manifest it accepts.
50
+ * Messages name the capability; `pointer` is the JSON pointer inside oats.json.
51
+ *
52
+ * An unknown hook event is forward-tolerant (0.49.0): a newer kernel's event
53
+ * declared as a command, `{ command }` or `{ command, required: false }` is a
54
+ * warning and never runs here, so the next new event does not drop every
55
+ * capability that adopts it on an older host. Declared `required: true`, it
56
+ * stays refused: skipping a hook its author declared essential is fail-open.
57
+ * The declaration's shape and its script are checked as for a known event. */
58
+ export function manifestContract(m) {
39
59
  const problems = [];
60
+ const warnings = [];
40
61
  const id = m?.capability;
41
62
  const bad = (pointer, message) => problems.push({ pointer, message: `capability ${id} ${message}` });
42
63
 
@@ -76,15 +97,19 @@ export function manifestContractProblems(m) {
76
97
  if (hooks.length && !/^[a-z][a-z0-9]*\./.test(String(id))) bad("/hooks", "declares hooks but its id has no dotted lowercase vendor component (e.g. acme.tool); only a dotted id can carry hooks");
77
98
  for (const [event, value] of hooks) {
78
99
  const at = `/hooks/${pointerKey(event)}`;
79
- if (!APPROVED_HOOKS.has(event)) { bad(at, `declares unsupported hook "${event}" (${[...APPROVED_HOOKS].join(", ")})`); continue; }
100
+ const known = APPROVED_HOOKS.has(event);
101
+ const sound = problems.length;
80
102
  const extraKeys = isObject(value) ? Object.keys(value).filter((k) => !["command", "required", "inputs"].includes(k)) : [];
81
103
  const command = typeof value === "string" ? value : isObject(value) && typeof value.command === "string" ? value.command : undefined;
82
104
  if (command === undefined || !command.trim() || extraKeys.length) { bad(at, `hook "${event}" must be a command string or { command, required, inputs }${extraKeys.length ? ` (unknown: ${extraKeys.join(", ")})` : ""}`); continue; }
83
105
  if (isObject(value) && value.required !== undefined && typeof value.required !== "boolean") bad(`${at}/required`, `hook "${event}": "required" must be a boolean`);
84
- // Only a spawn hook can fail a spawn; marking others required would promise
85
- // an enforcement that has no defined moment to act.
86
- else if (isObject(value) && value.required === true && event !== "spawn") bad(`${at}/required`, `hook "${event}" cannot be required — only the spawn hook is enforced (retire, launch and soul-scaffold run outside a spawn transaction)`);
106
+ // An unknown event its author declared essential cannot be skipped.
107
+ else if (!known && isObject(value) && value.required === true) bad(at, `declares unsupported hook "${event}" (${[...APPROVED_HOOKS].join(", ")})`);
108
+ // Only a spawn or worktree hook can fail what it serves; marking others
109
+ // required would promise an enforcement that has no defined moment to act.
110
+ else if (known && isObject(value) && value.required === true && !REQUIRABLE_HOOKS.has(event)) bad(`${at}/required`, `hook "${event}" cannot be required — only the spawn and worktree hooks are enforced (retire, launch and soul-scaffold run outside a transaction that can fail closed)`);
87
111
  if (hookScriptEscapes(command)) bad(isObject(value) ? `${at}/command` : at, `hook "${event}" script ${JSON.stringify(command.trim().split(/\s+/)[0])} escapes the capability directory; a hook script is a path inside it`);
112
+ if (!known && problems.length === sound) warnings.push({ code: "hook-event-unsupported", pointer: at, message: `capability ${id} declares hook "${event}", which this kernel does not run; it is ignored (this kernel runs ${[...APPROVED_HOOKS].join(", ")})` });
88
113
  }
89
114
 
90
115
  if (m.retirement !== undefined) {
@@ -98,7 +123,17 @@ export function manifestContractProblems(m) {
98
123
  if (roots === undefined) continue;
99
124
  const at = `/retirement/disposable/${scope}`;
100
125
  if (!Array.isArray(roots) || roots.some((root) => typeof root !== "string")) { bad(at, `manifest retirement.disposable.${scope} must be an array of relative roots`); continue; }
101
- if (scope !== "home") continue;
126
+ if (scope === "work") {
127
+ const sound = [];
128
+ roots.forEach((root, i) => {
129
+ if (disposableWorkRootProblem(root)) { bad(`${at}/${i}`, `manifest retirement.disposable.work entry ${JSON.stringify(root)} must be a relative path under work/ with no empty, "." or ".." segment`); return; }
130
+ const normalized = normalizeDisposableWorkRoot(root);
131
+ const other = sound.find((r) => disposableWorkRootsOverlap(r.normalized, normalized));
132
+ if (other) bad(`${at}/${i}`, `manifest retirement.disposable.work entry ${JSON.stringify(root)} overlaps entry ${JSON.stringify(other.root)}: the same root, or one inside the other`);
133
+ else sound.push({ root, normalized });
134
+ });
135
+ continue;
136
+ }
102
137
  roots.forEach((root, i) => {
103
138
  const problem = disposableHomeRootProblem(root);
104
139
  if (problem === "shape") bad(`${at}/${i}`, `manifest retirement.disposable.home entry ${JSON.stringify(root)} must name one hidden top-level home entry (".name", or ".prefix-*")`);
@@ -107,7 +142,29 @@ export function manifestContractProblems(m) {
107
142
  }
108
143
  }
109
144
  }
110
- return problems;
145
+ return { problems, warnings };
146
+ }
147
+
148
+ /** A manifest's contract warnings as a command reports them: [{ code, capability, path, message }],
149
+ * `path` the warning's JSON pointer under `at`, where the manifest is read
150
+ * (`<repoKey>:<dir>/oats.json` for a member's, `package:<id>:<dir>/oats.json` for a package's,
151
+ * a file path for a home's module copy). Empty for a manifest with none. */
152
+ export function locatedContractWarnings(manifest, at) {
153
+ return manifestContract(manifest).warnings.map((w) => ({ code: w.code, capability: manifest.capability, path: `${at}#${w.pointer}`, message: w.message }));
154
+ }
155
+
156
+ /** Contract warnings as the spawn and its preview carry them, among their other warning strings:
157
+ * each message clipped to CONTRACT_WARNING_TEXT characters, and at most CONTRACT_WARNING_LINES of
158
+ * them, then one line naming how many more (inspect lists every one, unclipped). A hook event's
159
+ * name is unbounded; the Desktop reads a spawn's warnings as at most 512 strings of at most 4096
160
+ * characters, and refuses the whole receipt past that. */
161
+ export const CONTRACT_WARNING_TEXT = 1000;
162
+ export const CONTRACT_WARNING_LINES = 32;
163
+ export function contractWarningMessages(warnings) {
164
+ const clip = (text) => (text.length > CONTRACT_WARNING_TEXT ? `${text.slice(0, CONTRACT_WARNING_TEXT - 1)}…` : text);
165
+ const shown = warnings.length > CONTRACT_WARNING_LINES ? warnings.slice(0, CONTRACT_WARNING_LINES - 1) : warnings;
166
+ const more = warnings.length - shown.length;
167
+ return [...shown.map((w) => clip(w.message)), ...(more ? [`${more} more hook events this kernel does not run are ignored (oats inspect lists every one)`] : [])];
111
168
  }
112
169
 
113
170
  /** `retirement.disposable.home`: provider-owned top-level entries of an instance
@@ -145,6 +202,38 @@ export function disposableHomeRootMatches(root, name) {
145
202
  return root.endsWith("*") ? name.startsWith(root.slice(0, -1)) : name === root;
146
203
  }
147
204
 
205
+ /** `retirement.disposable.work`: roots under an instance's work/ that a
206
+ * capability generates. The grammar is the one spawn applies where it records
207
+ * the roots (lib/core.mjs retirementDisposableRoots), so a manifest this
208
+ * accepts is one spawn records: a backslash reads as `/`, one leading `./` and
209
+ * one trailing `/` are dropped, and what is left is non-empty with no empty,
210
+ * `.` or `..` segment. An absolute path is refused as any host's spawn refuses
211
+ * it, a Windows one (`C:/x`) included: a manifest is read on every host. Spawn
212
+ * alone refuses a root that is a symlink in the work, or roots of different
213
+ * capabilities that overlap. The published schema
214
+ * (docs/capability-manifest.schema.json) states the same grammar. */
215
+ const ABSOLUTE_PATH_RE = /^(?:[/\\]|[A-Za-z]:[/\\])/;
216
+
217
+ /** Why `root` is not a declarable work root: "absolute", "segment" (empty
218
+ * after normalization, or an empty, "." or ".." segment), "shape" (not a
219
+ * non-empty string), or undefined when it is sound. */
220
+ export function disposableWorkRootProblem(root) {
221
+ if (typeof root !== "string" || !root) return "shape";
222
+ if (ABSOLUTE_PATH_RE.test(root)) return "absolute";
223
+ const normalized = normalizeDisposableWorkRoot(root);
224
+ return !normalized || normalized.split("/").some((part) => !part || part === "." || part === "..") ? "segment" : undefined;
225
+ }
226
+
227
+ /** A work root as spawn records it. */
228
+ function normalizeDisposableWorkRoot(root) {
229
+ return root.replaceAll("\\", "/").replace(/^\.\//, "").replace(/\/$/, "");
230
+ }
231
+
232
+ /** Whether two normalized work roots overlap: the same root, or one inside the other. */
233
+ function disposableWorkRootsOverlap(a, b) {
234
+ return a === b || a.startsWith(`${b}/`) || b.startsWith(`${a}/`);
235
+ }
236
+
148
237
  /** The setting keys a manifest declares (`settings.<key>`), sorted: names only, never their
149
238
  * descriptions or defaults. The spawn preview and inspect expose them so a client can gate
150
239
  * a choice on a declared key (e.g. a messaging provider's `join`). */
@@ -22,6 +22,7 @@ import { posix } from "node:path";
22
22
  import YAML from "yaml";
23
23
  import { oatsError } from "./errors.mjs";
24
24
  import { bindRemote } from "./packages.mjs";
25
+ import { locatedContractWarnings } from "./capability-contract.mjs";
25
26
  import { capabilitySkills, lockedCapability, lockedPackageCapabilities, manifestFilePath, memberRef, unsafeRelPath } from "./resolve.mjs";
26
27
  import { memberRowByKey } from "./workspace.mjs";
27
28
 
@@ -165,6 +166,8 @@ async function listing(source, { remote, remoteOptions }) {
165
166
  }
166
167
 
167
168
  const header = (source) => ({ capabilityShowApi: CAPABILITY_SHOW_API, name: source.name, kind: source.kind });
169
+ /** What the capability declares and this kernel ignores (an unknown hook event), where its manifest is read. */
170
+ const contractWarnings = (source) => locatedContractWarnings(source.manifest, source.kind === "package" ? `package:${source.package}:${source.dir}/oats.json` : `${source.repoKey}:${source.dir}/oats.json`);
168
171
 
169
172
  /** The show answer (capabilityShowApi 1): the inject with its text, each skill with its description and files. */
170
173
  export async function capabilityShow(source, { remote, remoteOptions }) {
@@ -192,7 +195,7 @@ export async function capabilityShow(source, { remote, remoteOptions }) {
192
195
  skills.push({ name: skill.name, path: skill.path, description, files: skill.files, filesTruncated: skill.filesTruncated });
193
196
  }
194
197
  }
195
- return { ...header(source), repoKey: source.repoKey, package: source.package, version: source.version, commit, path: dir, inject, skills, problems };
198
+ return { ...header(source), repoKey: source.repoKey, package: source.package, version: source.version, commit, path: dir, inject, skills, problems, warnings: contractWarnings(source) };
196
199
  }
197
200
 
198
201
  /** The `--file` answer: one file the show lists (the inject, or a listed skill file), at the row's commit.
@@ -204,5 +207,5 @@ export async function capabilityFile(source, path, { remote, remoteOptions }) {
204
207
  const known = (listed.inject?.safe && listed.inject.path === path) || (listed.skills ?? []).some((s) => (s.files ?? []).some((f) => f.path === path));
205
208
  if (!known) throw fail("E_CAPABILITY_FILE_UNKNOWN", `${path} is not a file \`oats capabilities show ${source.name}\` lists (the inject, or a skill's files)`, { path, name: source.name });
206
209
  const { bytes, size } = await bindRemote(remote, remoteOptions).readRemoteFile(source.ref, source.commit, posix.join(source.dir, path));
207
- return { ...header(source), commit: source.commit, file: { path, bytes: size, ...decodeText(bytes) } };
210
+ return { ...header(source), commit: source.commit, file: { path, bytes: size, ...decodeText(bytes) }, warnings: contractWarnings(source) };
208
211
  }