@awebai/oats 0.53.0 → 0.54.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 +12 -2
- package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
- package/docs/desktop-cli-api.md +29 -8
- package/docs/implementation.md +12 -4
- package/docs/official-catalog.md +1 -1
- package/docs/packages.md +5 -5
- package/docs/release-notes/v0.53.0.md +14 -0
- package/docs/release-notes/v0.54.0.md +142 -0
- package/docs/souls-and-instances.md +2 -1
- package/docs/upgrading.md +14 -2
- package/docs/workspaces.md +121 -1
- package/lib/packages.mjs +5 -1
- package/lib/remote.mjs +255 -76
- package/lib/workspace.mjs +27 -9
- package/package-catalog.json +1 -1
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/skills/oats-getting-started/SKILL.md +7 -1
package/bin/oats.mjs
CHANGED
|
@@ -42,6 +42,7 @@ import { PI_BRIDGE, piBridgeFolders, piBridgeSkewWarnings, planPiBridges, piBrid
|
|
|
42
42
|
import { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, unlockedPackages, workspaceWarnings, memberRowByKey } from "../lib/workspace.mjs";
|
|
43
43
|
import { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "../lib/teams.mjs";
|
|
44
44
|
import { LAUNCH_KEY_UNCHECKED, LAUNCH_PREFERENCE_UNMATCHED, launchKeyQuoted, launchKeysUnmatched, launchLayers, soulLaunchCommand, unmatchedKeyMessage } from "../lib/launch-preference.mjs";
|
|
45
|
+
import { terminalText } from "../lib/refused-text.mjs";
|
|
45
46
|
import { soulsOffered } from "../lib/instance-resolution.mjs";
|
|
46
47
|
import { parseConfigData } from "../lib/config-data.mjs";
|
|
47
48
|
import * as remoteModule from "../lib/remote.mjs";
|
|
@@ -2270,14 +2271,23 @@ async function itemsCmd(kind) {
|
|
|
2270
2271
|
// `oats souls` reads souls.launch for every soul it lists: a key that names none of them is a problem
|
|
2271
2272
|
// of this read, one row per key (the souls a spawn would refuse carry it as launch.problem).
|
|
2272
2273
|
const unmatched = kind === "souls" ? launchKeysUnmatched({ local: ctx.local, offered: soulsOffered(discovery) }).unmatched.map(unmatchedProblemRow) : [];
|
|
2273
|
-
|
|
2274
|
+
const problems = [...discovery.problems, ...unmatched];
|
|
2275
|
+
if (JSON_MODE) { jsonOk(withObservation({ [`${kind}Api`]: 1, standalone: standalone || undefined, workspace: { name: workspaceName(discovery), key: discovery.key, commit: discovery.commit }, [kind]: items, problems })); return; }
|
|
2274
2276
|
console.log(`${kind} of workspace ${workspaceName(discovery)} (${discovery.key} @ ${short(discovery.commit)})${standalone ? ` — ${standaloneNote(discovery)}` : ""}\n`);
|
|
2275
2277
|
if (!items.length) console.log(" (none)");
|
|
2276
2278
|
else if (kind === "souls") printTable(["name", "origin", "teams here", "work"], items.map((s) => [s.name, s.origin, s.teams === null ? "(invalid: oats teams)" : s.teams.map((t) => (t.default ? `${t.label}*` : t.label)).join(",") || "—", s.work ?? "—"]));
|
|
2277
2279
|
else printTable(["name", "origin", "layer"], items.map((c) => [c.private ? `${c.name} (repo-owned)` : c.name, c.origin, c.layer ?? "—"]));
|
|
2278
2280
|
const unsynced = Object.keys(discovery.workspace?.packages || {}).filter((id) => !lock.packages[id]);
|
|
2279
2281
|
if (kind === "capabilities" && unsynced.length) console.log(`\n package capabilities of ${unsynced.join(", ")} appear after \`oats sync\``);
|
|
2280
|
-
for (const p of
|
|
2282
|
+
for (const p of problems) console.log(`\n${catalogProblemLine(p)}`);
|
|
2283
|
+
}
|
|
2284
|
+
|
|
2285
|
+
/** Owner fields decide context, never message text. A problem source is display data;
|
|
2286
|
+
* render that projection without changing the operational external source. */
|
|
2287
|
+
function catalogProblemLine(p) {
|
|
2288
|
+
const owner = p.repoKey || p.package || (p.source ? remoteModule.redactUrl(p.source, null, { pinned: true }) : null);
|
|
2289
|
+
const where = owner ? ` [${terminalText(`${owner}: ${p.path}`)}]` : "";
|
|
2290
|
+
return `! ${p.code}: ${p.message}${where}`;
|
|
2281
2291
|
}
|
|
2282
2292
|
|
|
2283
2293
|
/** A key of souls.launch that names no soul (lib/launch-preference.mjs launchKeysUnmatched's row) as a
|
|
@@ -62,6 +62,9 @@ symlink enters as `symlink:<target>`; empty directories and a top-level `.git/`
|
|
|
62
62
|
The cache may be wiped at any time. Operations on one cache repo are serialized.
|
|
63
63
|
- Failures: `E_REMOTE_UNREADABLE { url, key, reason }`, `reason` ∈ `auth`, `not-found`, `network`,
|
|
64
64
|
`timeout`, `unknown`. Nothing half-succeeds.
|
|
65
|
+
- Reference-bearing diagnostics use `redactUrl`, including parser refusals, package and
|
|
66
|
+
workspace validation errors, and quoted Git text; the [display rule](../workspaces.md#repository-references-in-diagnostics)
|
|
67
|
+
removes user information without changing the reference used for transport.
|
|
65
68
|
|
|
66
69
|
---
|
|
67
70
|
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -680,10 +680,17 @@ Feature `workspace-v2`, `workspaceApi: 2`. Model: [workspaces.md](workspaces.md)
|
|
|
680
680
|
not resolve, a connection refused, reset or closed, a transport that could
|
|
681
681
|
not reach the remote). A failure whose text shows nothing the kernel
|
|
682
682
|
recognises is `unknown` (0.53.0; it read `network` before), and its message
|
|
683
|
-
then ends with
|
|
684
|
-
<line>`.
|
|
685
|
-
|
|
686
|
-
|
|
683
|
+
then ends with a last-line diagnostic: `cannot read remote <url> (unknown):
|
|
684
|
+
<line>`. Git's words are shown only under the
|
|
685
|
+
[whole-line disclosure rule](workspaces.md#repository-references-in-diagnostics);
|
|
686
|
+
otherwise `<line>` is the contract's fixed Git notice. Permitted text remains
|
|
687
|
+
one line of at most 300 characters with control characters removed. This
|
|
688
|
+
supersedes the earlier rule that a scrubbed Git line was always shown.
|
|
689
|
+
Only stderr supplies this last-line diagnostic. Empty or whitespace-only
|
|
690
|
+
stderr leaves the message at `(unknown)`, without an error-message fallback;
|
|
691
|
+
an output overflow without a stderr line uses a kernel-owned budget notice. Other diagnostic routes'
|
|
692
|
+
existing error-message fallbacks retain the same original-operation context
|
|
693
|
+
and disclosure rule.
|
|
687
694
|
`cache` (OATS 0.33.0) is local: the
|
|
688
695
|
remote cache on this machine could not be written (a git lock still held,
|
|
689
696
|
another oats process still writing it, or a lock file one left when it
|
|
@@ -694,7 +701,10 @@ Feature `workspace-v2`, `workspaceApi: 2`. Model: [workspaces.md](workspaces.md)
|
|
|
694
701
|
`status` / `workspace status`, the Desktop keeps the `message` (shown as
|
|
695
702
|
given) and only a bounded cause: `details.reason` (matching
|
|
696
703
|
`^[a-z][a-z-]{0,31}$`) and the host of `details.url`. No path, pid, lock,
|
|
697
|
-
`cacheDir` or other detail field crosses to the renderer.
|
|
704
|
+
`cacheDir` or other detail field crosses to the renderer. `details.url` is a
|
|
705
|
+
display value under the [repository diagnostic contract](workspaces.md#repository-references-in-diagnostics),
|
|
706
|
+
so it may withhold the reference and supply no host; it is not a transport URL.
|
|
707
|
+
It keys only on
|
|
698
708
|
`code` + `details.reason`: `cache` words the roster "OATS cache
|
|
699
709
|
problem" with the message in full; `network` / `timeout` read "Couldn't
|
|
700
710
|
reach <host>"; any other reason, `unknown` among them, keeps the generic
|
|
@@ -931,7 +941,19 @@ oats souls [--dir <d>] [--max-age <s>] --json
|
|
|
931
941
|
Every item of every confirmed member, the external souls, and the locked
|
|
932
942
|
packages' capabilities and souls, sorted by name, then origin. Both carry
|
|
933
943
|
`workspace: {name, key, commit}`, `problems` and, on a standalone view,
|
|
934
|
-
`standalone: true`.
|
|
944
|
+
`standalone: true`. Text mode prints every `problems` row on stdout under
|
|
945
|
+
the table, in the same order as JSON: discovery problems, then unmatched
|
|
946
|
+
`souls.launch` keys for `oats souls`. The line is `! <code>: <message>`,
|
|
947
|
+
preserving the kernel code and message. A row with an owner (`repoKey`,
|
|
948
|
+
`package` or `source`) adds ` [<where>]`: its existing `path`, preceded by
|
|
949
|
+
`repoKey: ` or `package: ` when present. A source-owned row shows its diagnostic
|
|
950
|
+
source display followed by its path; the source uses the shared
|
|
951
|
+
[repository-reference display policy](workspaces.md#repository-references-in-diagnostics)
|
|
952
|
+
and may be withheld as a whole. Operational external sources remain exact. Context uses
|
|
953
|
+
the kernel's terminal text escaping. Ownerless rows, including unmatched
|
|
954
|
+
launch keys, have no bracket. Partial listings still exit 0; JSON success
|
|
955
|
+
semantics and fatal refusals are unchanged. A problem does not necessarily
|
|
956
|
+
mean an item is absent from the table.
|
|
935
957
|
|
|
936
958
|
```json
|
|
937
959
|
{"soulsApi":1,"workspace":{"name":"northwind","key":"github.com/nw/agents","commit":"66566512…"},
|
|
@@ -978,8 +1000,7 @@ problem`, (feature `souls-capabilities`) `capabilities`, and (feature
|
|
|
978
1000
|
as in the refusal's `details.keys`. `message` is at most 1024 characters
|
|
979
1001
|
and ends with the two commands, in their order. Each soul a spawn would
|
|
980
1002
|
refuse carries the refusal as `launch.problem`: the souls with no entry of
|
|
981
|
-
their own.
|
|
982
|
-
<message>`.
|
|
1003
|
+
their own.
|
|
983
1004
|
- `teams` and `defaultTeam` (feature `team-model-3`) are a
|
|
984
1005
|
[TeamRow](#the-team-row-teamrow) list and a
|
|
985
1006
|
[DefaultTeam](#the-default-defaultteam); both `null` when the soul's teams
|
package/docs/implementation.md
CHANGED
|
@@ -86,7 +86,7 @@ and the rules its tests pin.
|
|
|
86
86
|
|
|
87
87
|
| module | owns |
|
|
88
88
|
|---|---|
|
|
89
|
-
| `remote.mjs` | repo refs, reading Git remotes, content digests |
|
|
89
|
+
| `remote.mjs` | repo refs, reading Git remotes, content digests; `redactUrl` owns [reference display construction and withholding](workspaces.md#repository-references-in-diagnostics). Selected original refused references first use the contract's bounded plain-value rule; other values supply only validated scheme/SCP, host, supported port and path components, or are withheld whole. Raw host/path fragments inherit plain eligibility only from the original selected source, never from the fragment alone; nonplain originals cannot use that exception. Plain-reference recognition is not a secret detector: credential-like text within the permitted alphabet stays visible. Display recognition shares the parser's character rules without calling its error path, and never changes admission or transport. Explicit pinned-source context retains only a constructed reference plus a validated 40-hex commit, remains idempotent, and has no plain fallback; the default context does not infer pins. Each rejection boundary explicitly names its rejected-input fields; the seven selected argument fields use the same bounded plain-value predicate through the renderer, including spaces and colons and without trimming or decoding, never a global field-name rule. Rejected-input messages quote the rendered fields through a formatter at that boundary, so rejected words cannot replace identical words in the fixed reason. Valid operational values are untouched. Refusal context owns the explanation once; forwarding preserves it. `scrubGitLine` delegates the linked whole-Git-line disclosure rule to the renderer before control/length formatting: only proven unchanged original operation refs plus an original line without `@` permit disclosure; all other lines become the fixed notice, with no substring recovery. Construction tests audit raw Git error-text access and quoting routes; generated invariants cover selected diagnostic routes |
|
|
90
90
|
| `local-inputs.mjs` | the local configuration a command read, for `observation.localRevision` |
|
|
91
91
|
| `workspace.mjs` | workspace, membership and soul files; discovery |
|
|
92
92
|
| `resolve.mjs` | a soul's resolution: capabilities, slots, provenance |
|
|
@@ -332,9 +332,17 @@ A failed git call is classified from what it shows (`classifyRemoteFailure`):
|
|
|
332
332
|
our own timer's kill is `timeout`, another signal `killed`, a failed write of
|
|
333
333
|
the cache `cache`, and otherwise git's text decides, read without the object
|
|
334
334
|
ids it names. A text that shows nothing the kernel recognises is `unknown`,
|
|
335
|
-
never `network
|
|
336
|
-
|
|
337
|
-
|
|
335
|
+
never `network`. `gitLastLine` reads only stderr for an `unknown` failure:
|
|
336
|
+
empty or whitespace-only stderr supplies no line; an output overflow without
|
|
337
|
+
a stderr line supplies a kernel-owned budget notice. It does not substitute an error message; other
|
|
338
|
+
routes' existing error-message fallbacks are unchanged. A stderr line passes
|
|
339
|
+
through `scrubGitLine`, which delegates the
|
|
340
|
+
[whole-line disclosure rule](workspaces.md#repository-references-in-diagnostics)
|
|
341
|
+
to the renderer with the original line and original operation references before
|
|
342
|
+
formatting.
|
|
343
|
+
When disclosure is not proved safe, it returns the contract's fixed Git notice;
|
|
344
|
+
it does not try to recover a safe fragment. Classification and kernel-owned
|
|
345
|
+
reason text do not depend on whether Git's words can be shown.
|
|
338
346
|
|
|
339
347
|
Every write to a cache repo (its `git init`, config, fetches and pins) holds
|
|
340
348
|
the repo's cross-process write lock, `<cache>/.locks/<repo>.lock`
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,7 +9,7 @@ or workspace membership alone does not make a package official.
|
|
|
9
9
|
|
|
10
10
|
| package | release | capabilities | package souls |
|
|
11
11
|
|---|---|---|---|
|
|
12
|
-
| `oats.framework` | `oats-framework/v1.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.10.0` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
13
|
| `oats.okf` | `v5.0.3` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
14
|
| `oats.aweb` | `v1.27.1` | `oats.aweb` (messaging) | |
|
|
15
15
|
| `oats.engineering` | `v1.9.1` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
package/docs/packages.md
CHANGED
|
@@ -51,7 +51,7 @@ packages:
|
|
|
51
51
|
- **Bare version** (`v5.0.3`, `5.0.3`, `1.0.0-rc.1`): the id is looked up in
|
|
52
52
|
the official catalog — `package-catalog.json` in the `oats` repo, or the file
|
|
53
53
|
named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
|
|
54
|
-
convention (`v5.0.3` or `oats-framework/v1.
|
|
54
|
+
convention (`v5.0.3` or `oats-framework/v1.10.0`) and the payload path. An id
|
|
55
55
|
the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
|
|
56
56
|
a package outside the catalog"). The catalog is the reviewed official list
|
|
57
57
|
([official-catalog.md](official-catalog.md)) and the only way a
|
|
@@ -74,7 +74,7 @@ members:
|
|
|
74
74
|
- git:github.com/acme/agents
|
|
75
75
|
- git:github.com/acme/platform
|
|
76
76
|
packages:
|
|
77
|
-
oats.framework: v1.
|
|
77
|
+
oats.framework: v1.10.0
|
|
78
78
|
oats.okf: v5.0.3
|
|
79
79
|
oats.aweb: v1.27.1
|
|
80
80
|
teams:
|
|
@@ -353,11 +353,11 @@ A soul that names one of the package's capabilities with
|
|
|
353
353
|
"policy": "docs/official-catalog.md",
|
|
354
354
|
"packages": {
|
|
355
355
|
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.3", "path": "oats-package" },
|
|
356
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.10.0", "path": "oats-package" }
|
|
357
357
|
}
|
|
358
358
|
}
|
|
359
359
|
```
|
|
360
360
|
|
|
361
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.
|
|
362
|
-
resolves to tag `oats-framework/v1.
|
|
361
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.10.0`
|
|
362
|
+
resolves to tag `oats-framework/v1.10.0`. Resolving through the catalog never
|
|
363
363
|
advances a lock by itself: `oats sync` does, and says so.
|
|
@@ -11,6 +11,20 @@ to do on a host, and what: restart the instances and, where schedules run,
|
|
|
11
11
|
install the host timer again; before that, install the CLI again where it is
|
|
12
12
|
installed inside the Node version.
|
|
13
13
|
|
|
14
|
+
- **Where the Desktop is installed, install Desktop 0.53.0 before the CLI
|
|
15
|
+
([#1107](https://github.com/awebai/oats/issues/1107)).** A 0.52.0 Desktop
|
|
16
|
+
refuses a 0.53.0 CLI and lists no instance until it is replaced. Desktop
|
|
17
|
+
0.53.0 accepts the older CLI in the meantime. This includes an
|
|
18
|
+
`oats update` whose plan installs the CLI.
|
|
19
|
+
|
|
20
|
+
- **A host that comes from 0.51 or earlier does 0.52.0's
|
|
21
|
+
[Upgrade steps](v0.52.0.md#upgrade) first, in their order.** One of them is
|
|
22
|
+
easy to miss because it is a host tool and not OATS: aw 1.36.33 or later,
|
|
23
|
+
before `oats sync`. The sync to this release's catalog locks oats.aweb
|
|
24
|
+
1.27.1, which refuses every new spawn below that version. After the sync,
|
|
25
|
+
`oats readiness --soul <name>` shows it as a failed provider check, with
|
|
26
|
+
the install that cures it.
|
|
27
|
+
|
|
14
28
|
- **Once the CLI is 0.53.0, run `oats update` in each deployment that
|
|
15
29
|
launches pi instances.** It now moves the pi bridge in every pi folder that
|
|
16
30
|
deployment's launch configurations name, and `oats doctor` warns about each
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
# OATS 0.54.0
|
|
2
|
+
|
|
3
|
+
2026-10-13
|
|
4
|
+
|
|
5
|
+
## Upgrade
|
|
6
|
+
|
|
7
|
+
- **Nothing is required.** Install the Desktop first and the CLI second, as
|
|
8
|
+
[Upgrading](../upgrading.md) says: a 0.53.0 Desktop refuses a 0.54.0 CLI.
|
|
9
|
+
|
|
10
|
+
- **To get the skill `/oats-token-saving`,** pin `oats.framework: v1.10.0`
|
|
11
|
+
in your workspace and run `oats sync`. Instances already running keep the
|
|
12
|
+
briefing and the skills they were spawned with; new spawns get the new
|
|
13
|
+
ones. See Added and Provider updates.
|
|
14
|
+
|
|
15
|
+
- **A script that reads a refusal about a repository reference** (its
|
|
16
|
+
message, or `details.ref`, `details.url`, `details.value`) now reads a
|
|
17
|
+
display form: user information is never in it; a refused value made only
|
|
18
|
+
of letters, digits, spaces and `._/+-:` is shown as written; any other
|
|
19
|
+
value that cannot be rebuilt from its parts is replaced whole by a fixed
|
|
20
|
+
text. See Changed and Fixed
|
|
21
|
+
([#1077](https://github.com/awebai/oats/issues/1077)). Codes and field
|
|
22
|
+
shapes are unchanged, and so is the reference Git itself is given.
|
|
23
|
+
|
|
24
|
+
- **The official catalog's versions in this release** are oats.framework
|
|
25
|
+
1.10.0, oats.okf 5.0.3, oats.aweb 1.27.1 and oats.engineering 1.9.1: see
|
|
26
|
+
Provider updates. Pin what your workspace uses, then run `oats sync`.
|
|
27
|
+
|
|
28
|
+
## Added
|
|
29
|
+
|
|
30
|
+
- **`oats.core`: the skill `/oats-token-saving`, and three lines of its
|
|
31
|
+
briefing** ([#1103](https://github.com/awebai/oats/issues/1103)). A message
|
|
32
|
+
between instances costs twice: the sender writes it, and the receiver is
|
|
33
|
+
woken, reads it with its whole context and often answers. The skill gives
|
|
34
|
+
one test before sending, "who will do something different because of this,
|
|
35
|
+
and what?", and the rules that follow from it:
|
|
36
|
+
- **to whom:** only the instance that will act on it, with no copies and no
|
|
37
|
+
sending to every holder of a role;
|
|
38
|
+
- **what not to send:** acknowledgements and courtesy, progress and status,
|
|
39
|
+
what a shared record already shows, someone else's words passed along, and
|
|
40
|
+
the story of how the sender got there. A message that needs a confirmation
|
|
41
|
+
says so and gets one line back;
|
|
42
|
+
- **don't ask for what you can read,** and never ask for progress reports or
|
|
43
|
+
set a helper up to send them;
|
|
44
|
+
- **what a message holds:** first what the receiver must do, exact
|
|
45
|
+
references, one topic, one message per task boundary. A spec, a brief or a
|
|
46
|
+
review's findings is the long message, sent once as a file or a link;
|
|
47
|
+
- **what is never cut:** what moves work, what a role owes, and what is owed
|
|
48
|
+
on a record (a verdict on the pull request, a decision on its issue, the
|
|
49
|
+
evidence of a hand-over, the report of a fault or of one's own mistake).
|
|
50
|
+
|
|
51
|
+
The skill is provider-neutral: it names no messaging capability, and how to
|
|
52
|
+
send stays with that capability's own skill. The `oats.core` briefing, which
|
|
53
|
+
every instance with `oats.core` reads, gains the test in three lines, so it
|
|
54
|
+
applies before the skill is loaded. An instance spawned before the release
|
|
55
|
+
that carries this keeps its briefing; new spawns get it
|
|
56
|
+
([`oats.core`](../souls-and-instances.md)).
|
|
57
|
+
|
|
58
|
+
## Changed
|
|
59
|
+
|
|
60
|
+
- **The Desktop accepts OATS CLIs `>=0.25.8 <0.55.0`.** The compatibility band
|
|
61
|
+
admits 0.54. Upgrade the CLI and the Desktop together: a 0.53.0 Desktop
|
|
62
|
+
refuses a 0.54.0 CLI. No new gate on the band. `oats tui` runs the kernel it
|
|
63
|
+
ships with and is held to the same band.
|
|
64
|
+
|
|
65
|
+
- **Diagnostic messages, details, provenance and workspace `cannot-read` values
|
|
66
|
+
now preserve bounded plain refused values, construct displays that omit user
|
|
67
|
+
information (including SSH users), or withhold the reference, while the seven
|
|
68
|
+
rejected argument fields share the bounded plain rule and Git lines are shown
|
|
69
|
+
only for unchanged original operation references
|
|
70
|
+
and no literal `@` in the original line, replacing
|
|
71
|
+
[#1075](https://github.com/awebai/oats/issues/1075)'s scrubbed-line behavior
|
|
72
|
+
([#1077](https://github.com/awebai/oats/issues/1077)).**
|
|
73
|
+
|
|
74
|
+
## Fixed
|
|
75
|
+
|
|
76
|
+
- **Repository diagnostics no longer copy user information from selected
|
|
77
|
+
references ([#1077](https://github.com/awebai/oats/issues/1077)).** Messages,
|
|
78
|
+
reference-bearing details and provenance, schema problems and workspace
|
|
79
|
+
`cannot-read` fields use a display constructed from recognised host and path
|
|
80
|
+
components, with a verbatim exception for original refused values of 1–256
|
|
81
|
+
ASCII letters, digits, spaces or `._/+-:` characters. The same predicate
|
|
82
|
+
serves the seven selected rejected arguments; it never trims or decodes an
|
|
83
|
+
input. Malformed or mixed values outside that rule are withheld whole,
|
|
84
|
+
including harmless text, while known declaration files and key locations
|
|
85
|
+
remain available. Raw derived fragments qualify for the plain exception only
|
|
86
|
+
through their original selected source, never from a nonplain source. Plain
|
|
87
|
+
recognition is not a secret detector: credential-like text within the
|
|
88
|
+
permitted alphabet remains visible.
|
|
89
|
+
Git's own line is shown only when all original operation references are
|
|
90
|
+
proved unchanged by display construction and the original line contains no
|
|
91
|
+
`@`; otherwise the whole line becomes a fixed notice directing the operator
|
|
92
|
+
to run the operation by hand. No substring is recovered. This replaces the
|
|
93
|
+
quoted-line disclosure behavior shipped for unknown Git failures.
|
|
94
|
+
See the [diagnostic display contract](../workspaces.md#repository-references-in-diagnostics).
|
|
95
|
+
Standalone file/path meanings, command-consumed values and Git's original
|
|
96
|
+
transport reference are unchanged.
|
|
97
|
+
Explicit pinned-source diagnostics keep a constructed reference and its
|
|
98
|
+
validated commit, or withhold the whole source without a plain fallback.
|
|
99
|
+
Rejected argument values use the contract's bounded plain-value rule and
|
|
100
|
+
neutral withholding notice; valid operational arguments are unchanged. Unknown Git failures quote only
|
|
101
|
+
stderr: empty stderr adds no line unless output overflow needs a kernel budget notice.
|
|
102
|
+
|
|
103
|
+
- **Repository and package refusals explain an omitted reference without
|
|
104
|
+
exposing it ([#1077](https://github.com/awebai/oats/issues/1077)).** The
|
|
105
|
+
originating refusal explains withholding or user-information omission once;
|
|
106
|
+
existing message slots keep the explanation when forwarding it. HTTP(S)
|
|
107
|
+
userinfo refusals keep their specific cause and credential-helper advice,
|
|
108
|
+
and package refusals keep their own reason. Admission, codes and field shapes
|
|
109
|
+
are unchanged.
|
|
110
|
+
|
|
111
|
+
- `oats souls` and `oats capabilities` now show every catalog discovery
|
|
112
|
+
problem below their text tables, including unreadable locked package
|
|
113
|
+
souls. Diagnostics stay on stdout in JSON order, with the kernel's code
|
|
114
|
+
and message; partial listings still exit 0
|
|
115
|
+
([#1098](https://github.com/awebai/oats/issues/1098)).
|
|
116
|
+
|
|
117
|
+
## Provider updates
|
|
118
|
+
|
|
119
|
+
- **oats.framework 1.10.0: oats.core 2.6.0.** One new skill and three lines
|
|
120
|
+
of instruction text in oats.core; no hook, command, schema or provider
|
|
121
|
+
contract changes, and the capability floors are unchanged (oats.core
|
|
122
|
+
`>=0.40.0`).
|
|
123
|
+
- oats.core gains the skill `/oats-token-saving` and names it in its
|
|
124
|
+
briefing, as the entry under Added says
|
|
125
|
+
([#1103](https://github.com/awebai/oats/issues/1103)). The two commands
|
|
126
|
+
the skill tells an instance to read before asking, `oats status` and
|
|
127
|
+
`oats instance events <instance>`, exist in every kernel oats.core
|
|
128
|
+
admits.
|
|
129
|
+
- A deployment gets it by pinning `oats.framework: v1.10.0` and running
|
|
130
|
+
`oats sync`. Instances already running keep the briefing and the skills
|
|
131
|
+
they were spawned with; new spawns get the new ones.
|
|
132
|
+
|
|
133
|
+
## Documentation
|
|
134
|
+
|
|
135
|
+
- **Upgrading: the Desktop goes before the CLI
|
|
136
|
+
([#1107](https://github.com/awebai/oats/issues/1107)).**
|
|
137
|
+
[Upgrading OATS on a host](../upgrading.md) now says so, and why: a
|
|
138
|
+
Desktop refuses a CLI of a newer minor version, so with the CLI moved
|
|
139
|
+
first it lists no instance until it is replaced. The Upgrade section of
|
|
140
|
+
the [0.53.0 notes](v0.53.0.md#upgrade) gained that step, and one for a
|
|
141
|
+
host that comes from 0.51 or earlier: 0.52.0's steps first, the aw client
|
|
142
|
+
among them, before `oats sync`.
|
|
@@ -98,7 +98,8 @@ is a code change, reviewed in its repo.
|
|
|
98
98
|
### OATS operational knowledge is a capability
|
|
99
99
|
|
|
100
100
|
An agent's knowledge of OATS itself (status, spawn, retire, finding other
|
|
101
|
-
souls
|
|
101
|
+
souls, and keeping its messages to other instances few and short:
|
|
102
|
+
`/oats-token-saving`) is ordinary capability content: **`oats.core`** (package
|
|
102
103
|
`oats.framework`). Workspaces give it to every soul through
|
|
103
104
|
`defaults.capabilities: { oats.core: { from: package } }`; a soul may say
|
|
104
105
|
`oats.core: off`. **`oats.setup`** (same package) carries the whole-architecture
|
package/docs/upgrading.md
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
# Upgrading OATS on a host
|
|
2
2
|
|
|
3
|
-
Upgrading OATS means three things, in this order, on each host
|
|
3
|
+
Upgrading OATS means three things, in this order, on each host, and one
|
|
4
|
+
before them where the Desktop is installed:
|
|
4
5
|
|
|
6
|
+
0. **The Desktop**, where it is installed: the new version's, before the CLI.
|
|
5
7
|
1. **The CLI** (`@awebai/oats`, the kernel).
|
|
6
8
|
2. **The pi bridge** (`@awebai/oats-pi`), in every pi folder the host's
|
|
7
9
|
deployments launch pi with: `oats update`, in each deployment.
|
|
@@ -18,6 +20,13 @@ every version between yours and the new one in the
|
|
|
18
20
|
changes, and what else must change with it (the Desktop, another tool, a
|
|
19
21
|
package pin). This page is the part that is the same for every release.
|
|
20
22
|
|
|
23
|
+
**Why the Desktop goes first.** A Desktop accepts a CLI up to its own minor
|
|
24
|
+
version and refuses a newer one: with the CLI moved first, the Desktop that
|
|
25
|
+
is still running lists no instance until it is replaced. The new Desktop
|
|
26
|
+
accepts the older CLI in the meantime. The CLI can move by two commands, the
|
|
27
|
+
`npm install` below and an `oats update` whose plan installs it: step 0 comes
|
|
28
|
+
before either.
|
|
29
|
+
|
|
21
30
|
**Package versions are a different thing.** `oats update` moves the CLI and
|
|
22
31
|
the bridge, never a package. A deployment's capabilities come from the
|
|
23
32
|
packages pinned in `oats-workspace.yaml`; change a pin, then run `oats sync`
|
|
@@ -26,6 +35,7 @@ packages pinned in `oats-workspace.yaml`; change a pin, then run `oats sync`
|
|
|
26
35
|
## The steps
|
|
27
36
|
|
|
28
37
|
```sh
|
|
38
|
+
# 0. where the Desktop is installed: the new version's Desktop first
|
|
29
39
|
npm install -g @awebai/oats # 1. the CLI
|
|
30
40
|
oats update # 2. in a deployment: the plan, then it asks before it runs
|
|
31
41
|
oats doctor # 3. in the same deployment
|
|
@@ -41,7 +51,9 @@ Without a terminal (a script, an agent's shell) it runs only with `--yes`.
|
|
|
41
51
|
|
|
42
52
|
`oats update` also does step 1: when npm lists a newer `@awebai/oats`, its
|
|
43
53
|
plan starts with that install, and the bridges move to that same version in
|
|
44
|
-
the same run.
|
|
54
|
+
the same run. So where the Desktop is installed, step 0 comes before such an
|
|
55
|
+
`oats update` too: `oats update --check` shows whether the plan holds that
|
|
56
|
+
install, and runs nothing.
|
|
45
57
|
|
|
46
58
|
**`oats update` only moves forward.** It never installs an older CLI or an
|
|
47
59
|
older bridge than the one in place:
|
package/docs/workspaces.md
CHANGED
|
@@ -54,7 +54,7 @@ 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.
|
|
57
|
+
oats.framework: v1.10.0 # bare version → resolves through the official catalog
|
|
58
58
|
oats.okf: v5.0.3
|
|
59
59
|
acme.tools: git:github.com/acme/tools@v0.4.0 # outside the catalog → git:<repo>@<tag|OID>; still a package
|
|
60
60
|
|
|
@@ -159,6 +159,116 @@ facts for automations, and launch configurations. The full reference is
|
|
|
159
159
|
Written by `oats sync`; the only persisted state at the deployment besides
|
|
160
160
|
`oats-local.yaml`. See [packages.md](packages.md).
|
|
161
161
|
|
|
162
|
+
## Repository references in diagnostics
|
|
163
|
+
|
|
164
|
+
Selected repository references in diagnostics are display values. A selected
|
|
165
|
+
original refused reference is shown verbatim when it is 1–256 characters long
|
|
166
|
+
and contains only ASCII letters, digits, spaces, `.`, `_`, `/`, `+`, `-` and
|
|
167
|
+
`:`. This bounded plain-value rule tests the whole original string: no trimming,
|
|
168
|
+
decoding, control-character removal or truncation makes a value eligible.
|
|
169
|
+
Plain-reference recognition is not a secret detector: credential-like text
|
|
170
|
+
that meets this alphabet remains visible. Otherwise, display is constructed
|
|
171
|
+
from recognised components.
|
|
172
|
+
An unambiguous scheme or scp-style reference supplies only its scheme, host,
|
|
173
|
+
supported port and path, using the repository parser's character rules. User
|
|
174
|
+
information is never a display component: `ssh://git@host/org/repo` and
|
|
175
|
+
`git@host:org/repo` both display as `ssh://host/org/repo`. Display recognition
|
|
176
|
+
can also remove user information from a well-formed HTTP(S) URL that the
|
|
177
|
+
repository parser refuses; it does not admit that URL for use by Git.
|
|
178
|
+
|
|
179
|
+
**The fixed withheld display is `[repository reference withheld]`.** It replaces
|
|
180
|
+
the whole selected value when neither the bounded plain-value rule nor
|
|
181
|
+
unambiguous component construction applies, including malformed or mixed
|
|
182
|
+
references outside the plain rule. Harmless host or path text in that value
|
|
183
|
+
is withheld too. A literal input equal to the fixed display looks the same;
|
|
184
|
+
the display is not an identifier or a value to pass back to a command.
|
|
185
|
+
Standalone `file:` references and filesystem paths retain their path meanings.
|
|
186
|
+
|
|
187
|
+
A diagnostic field that explicitly carries a pinned source uses the same
|
|
188
|
+
constructor with pinned-source context: a recognised reference followed by `@`
|
|
189
|
+
and a validated 40-hex-character commit can retain that commit in its display.
|
|
190
|
+
If either part cannot be recognised, the whole source is withheld: pinned
|
|
191
|
+
sources have no bounded plain-value fallback. Rendering an already constructed
|
|
192
|
+
pinned source does not change it. This context does not change default
|
|
193
|
+
reference rendering or admit a new source form. Local/file reference semantics
|
|
194
|
+
and operational external-source values remain unchanged.
|
|
195
|
+
|
|
196
|
+
The same decision applies to the selected reference in error messages,
|
|
197
|
+
`details.ref`, `details.url`, `details.value`, `provenance.value`, nested
|
|
198
|
+
reference keys and values, and reference-bearing workspace and soul schema
|
|
199
|
+
problems. Discovery problem rows' `source` is also a diagnostic display.
|
|
200
|
+
Seven explicitly rejected argument fields have a separate context in the same
|
|
201
|
+
renderer: `transport`, `commit`, `at`, `path`, `depth`, `limit` and `destDir`.
|
|
202
|
+
A rejected string is preserved only when the whole original string satisfies
|
|
203
|
+
the same bounded plain-value rule above, including its space and colon
|
|
204
|
+
characters. No trimming, decoding, control handling or truncation is applied
|
|
205
|
+
to establish eligibility.
|
|
206
|
+
**The fixed rejected-value display is `[value withheld]`, and its neutral explanation is “(the value was withheld)”.**
|
|
207
|
+
Every other rejected string uses that display in the quoted message value and
|
|
208
|
+
matching details/provenance. Existing nonstring and container handling is
|
|
209
|
+
unchanged; nested strings use this same context. The renderer owns the
|
|
210
|
+
explanation once per originating refusal. This is a bounded display rule, not
|
|
211
|
+
a secret detector: a plain token made only of the permitted characters is not
|
|
212
|
+
protected. Selection belongs to the particular rejection; a field's name
|
|
213
|
+
alone never selects it. Valid argument values and other operational values
|
|
214
|
+
remain exact; pinned-source, schema and Git-line contexts keep their own rules.
|
|
215
|
+
Quoted or JSON-escaped copies and host/path fragments derived from a withheld
|
|
216
|
+
value cannot reveal its remainder. A raw host/path fragment can use the plain
|
|
217
|
+
exception only when its original selected source qualifies for that exception;
|
|
218
|
+
a fragment from a nonplain original never becomes eligible merely
|
|
219
|
+
because the fragment looks plain. Unrelated schema values and opaque provider
|
|
220
|
+
payloads are not scanned. Query and fragment contents are not searched for
|
|
221
|
+
individual secret values; a selected remote reference with an unrecognised
|
|
222
|
+
suffix outside the plain rule is withheld as a whole.
|
|
223
|
+
|
|
224
|
+
A refusal retains its code and reason. When the whole reference is withheld,
|
|
225
|
+
the kernel message explains that once per originating refusal. When a
|
|
226
|
+
constructed display omits user information, the refusal carries the neutral
|
|
227
|
+
clause “(its user information is not shown)”. An HTTP(S) userinfo refusal keeps
|
|
228
|
+
its specific cause and advice to give credentials to Git through a credential
|
|
229
|
+
helper, rather than in the URL; package refusals keep their own reason.
|
|
230
|
+
Workspace and membership message slots carry an existing refusal's explanation
|
|
231
|
+
when they forward it, including schema `problems[].message`, without adding
|
|
232
|
+
another copy. Pattern-only schema problems use the same selected-value display
|
|
233
|
+
without inventing a parser refusal. Known declaration files and key locations
|
|
234
|
+
remain available beside the safe diagnostic value; APIs that do not know a
|
|
235
|
+
location do not invent one.
|
|
236
|
+
|
|
237
|
+
Git's own diagnostic text has a whole-line disclosure rule. A line may be
|
|
238
|
+
shown only when every original operation reference is known and unchanged by
|
|
239
|
+
the display constructor, and the original line contains no literal `@`.
|
|
240
|
+
Missing original-reference evidence fails that check. Check the original text
|
|
241
|
+
before removing control characters or shortening the line; formatting must not
|
|
242
|
+
hide a reason to withhold it. A permitted line keeps the existing control
|
|
243
|
+
handling and length bound.
|
|
244
|
+
|
|
245
|
+
For an unknown Git failure, the last-line diagnostic comes only from stderr.
|
|
246
|
+
Empty or whitespace-only stderr leaves the message at the failure reason;
|
|
247
|
+
there is no error-message fallback on this route. An output overflow without a stderr line uses a
|
|
248
|
+
kernel-owned budget notice. Other diagnostic routes that already use an error
|
|
249
|
+
message fallback keep their behavior and the whole-line disclosure rule.
|
|
250
|
+
|
|
251
|
+
**The fixed Git notice is “Git's diagnostic was withheld; run the same Git operation by hand to see Git's own words.”**
|
|
252
|
+
Every other Git line is replaced by that notice. No substring or token is
|
|
253
|
+
recovered from a withheld line. This replaces the quoted-line disclosure rule
|
|
254
|
+
shipped with the unknown-failure diagnostic: a bounded, scrubbed fragment alone
|
|
255
|
+
is no longer enough to display Git's words. Classification still reads Git's
|
|
256
|
+
result, so the failure code and reason remain useful when its text is withheld.
|
|
257
|
+
Kernel-owned messages and schema problem prose keep their selected-reference
|
|
258
|
+
rendering; they are not Git lines. Transport failures do not gain a
|
|
259
|
+
repository-refusal clause.
|
|
260
|
+
|
|
261
|
+
These diagnostic fields are for people. Accepted parser results, repository
|
|
262
|
+
identity keys and other values consumed by commands remain exact, including
|
|
263
|
+
operational `from` values and external rows' `source`; so does the original
|
|
264
|
+
reference handed to Git. Diagnostic rendering changes neither the
|
|
265
|
+
accepted syntax nor transport. A client may extract a host from a constructed
|
|
266
|
+
display; it must also handle the fixed withheld display without a host.
|
|
267
|
+
Desktop's external-soul view still displays the operational external `source`
|
|
268
|
+
value directly; that separate output route is tracked in
|
|
269
|
+
[#1111](https://github.com/awebai/oats/issues/1111). The diagnostic display rule
|
|
270
|
+
does not make that raw consumer safe.
|
|
271
|
+
|
|
162
272
|
## Membership and trust
|
|
163
273
|
|
|
164
274
|
**Reciprocal membership is a hard gate.** A repo is a member only when
|
|
@@ -486,6 +596,16 @@ URL — with the operator's own git configuration (`GIT_TERMINAL_PROMPT=0`, ssh
|
|
|
486
596
|
BatchMode: nothing ever prompts). Neither the repo that defines a capability nor
|
|
487
597
|
the repo that hosts the workspace needs to be cloned.
|
|
488
598
|
|
|
599
|
+
`oats souls` and `oats capabilities` print every catalog discovery problem
|
|
600
|
+
below their tables on stdout, in the same order as `--json` `problems`.
|
|
601
|
+
`oats souls` adds unmatched `souls.launch` keys after discovery problems.
|
|
602
|
+
Each line preserves `! <code>: <message>`. When the problem has an owner,
|
|
603
|
+
a bracket identifies its path and, where present, repository key or package;
|
|
604
|
+
external problems show their [diagnostic source display](#repository-references-in-diagnostics)
|
|
605
|
+
and declaration path, while operational external sources remain exact. These listings still exit 0
|
|
606
|
+
when some items cannot be read. A diagnostic can also describe an item that
|
|
607
|
+
remains listed; inspect its code and message.
|
|
608
|
+
|
|
489
609
|
**The only thing that needs a clone is a soul's work target** (`work:
|
|
490
610
|
worktree | checkout`). The kernel finds it, first hit wins: (1) `oats spawn
|
|
491
611
|
… --repo <abs path>`; (2) `oats-local.yaml` `clones: { <repo key>: <abs
|
package/lib/packages.mjs
CHANGED
|
@@ -290,7 +290,11 @@ export function parsePackageRequest(id, value, catalog) {
|
|
|
290
290
|
const c = classifyPackageValue(value);
|
|
291
291
|
if (c.problem) {
|
|
292
292
|
const code = typeof value === "string" && value.trim().startsWith("git:") ? "E_REPO_REF" : "E_WORKSPACE_SCHEMA";
|
|
293
|
-
|
|
293
|
+
const safe = { id, value: defaultRemote.redactUrl(value, null, { reference: true }), path: `/packages/${id}`,
|
|
294
|
+
problems: [defaultRemote.redactUrl(c.problem, value, { known: false })] };
|
|
295
|
+
const message = defaultRemote.redactUrl(`packages.${safe.id}: ${safe.problems[0]}, got ${JSON.stringify(safe.value)}`,
|
|
296
|
+
value, { known: false, refusal: true });
|
|
297
|
+
throw oatsError(code, message, safe);
|
|
294
298
|
}
|
|
295
299
|
if (c.kind === "git") return { kind: "git", remoteRef: c.repo, at: c.at, path: DEFAULT_PACKAGE_PATH };
|
|
296
300
|
const text = value.trim();
|