@awebai/oats 0.53.0 → 0.55.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 +17 -7
- package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
- package/docs/desktop-cli-api.md +44 -12
- package/docs/implementation.md +12 -4
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +14 -2
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.53.0.md +14 -0
- package/docs/release-notes/v0.54.0.md +142 -0
- package/docs/release-notes/v0.55.0.md +158 -0
- package/docs/servers.md +13 -3
- package/docs/souls-and-instances.md +2 -1
- package/docs/upgrading.md +14 -2
- package/docs/workspaces.md +122 -2
- package/lib/packages.mjs +5 -1
- package/lib/remote.mjs +255 -76
- package/lib/servers.mjs +82 -34
- package/lib/workspace.mjs +27 -9
- package/package-catalog.json +4 -4
- package/package.json +1 -1
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/workspace-views.mjs +4 -3
- package/packages/record/README.md +54 -13
- package/packages/record/bin/capture.mjs +107 -53
- package/packages/record/docs/capture-service.md +193 -0
- package/packages/record/docs/capture-status.schema.json +100 -0
- package/packages/record/lib/capture-aw.mjs +96 -94
- package/packages/record/lib/capture-cc.mjs +109 -187
- package/packages/record/lib/capture-db-reader.mjs +39 -0
- package/packages/record/lib/capture-issues.mjs +64 -0
- package/packages/record/lib/capture-scratch.mjs +111 -0
- package/packages/record/lib/capture-state.mjs +105 -0
- package/packages/record/lib/derived-state.mjs +60 -0
- package/packages/record/lib/formats.mjs +31 -31
- package/packages/record/lib/index-db.mjs +74 -34
- package/packages/record/lib/receipt-summary.mjs +62 -0
- package/packages/record/lib/session-snapshot.mjs +56 -1
- package/packages/record/lib/sqlite-rows.mjs +14 -0
- package/packages/record/lib/store.mjs +122 -43
- package/packages/record/lib/transcript-prefix.mjs +40 -0
- package/skills/oats-getting-started/SKILL.md +8 -2
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
|
|
@@ -4051,7 +4061,7 @@ async function experimentalCmd() {
|
|
|
4051
4061
|
/** `oats server add|list|remove|check`. A registration is where and how:
|
|
4052
4062
|
* an OpenSSH host alias, the remote workspace, the remote oats path. Keys
|
|
4053
4063
|
* and passwords never enter it; ssh owns those. */
|
|
4054
|
-
function serverCmd() {
|
|
4064
|
+
async function serverCmd() {
|
|
4055
4065
|
const bail = (code, msg, details) => (JSON_MODE ? jsonFail(code, msg, details) : die(msg));
|
|
4056
4066
|
const sub = args[1];
|
|
4057
4067
|
const usage = "usage: oats server add <id> --ssh <host-alias> --workspace </abs/path> [--oats <path>] [--path <dir:dir>] [--label <text>] [--replace] | connect <id> --ssh <host-alias> [--workspace-ref <ref>] [--dir </abs/path or ~/path on the host>] [--oats <path>] [--path <dir:dir>] [--label <text>] [--install-oats] [--replace] | list [--workspace-ref <ref>] | remove <id> | check <id> | roster [--server <id>] | forget <id> --instance <name> [--json]";
|
|
@@ -4073,12 +4083,12 @@ function serverCmd() {
|
|
|
4073
4083
|
}
|
|
4074
4084
|
if (sub === "roster") {
|
|
4075
4085
|
// The remote roster for the Desktop and operators: grouped by saved route
|
|
4076
|
-
// target, one bounded status pull per target, saved routes as the action
|
|
4086
|
+
// target, one bounded status pull per target, all at once, saved routes as the action
|
|
4077
4087
|
// authority. --server narrows to one registry id.
|
|
4078
4088
|
const only = flag("server") === true ? bail("E_BAD_ARGS", "--server needs a registered server id") : flag("server");
|
|
4079
4089
|
const ms = (name) => { const v = flag(name); if (v === undefined) return undefined; const n = Number(v); if (!Number.isInteger(n) || n < 1000) bail("E_BAD_ARGS", `--${name} takes whole milliseconds, at least 1000`); return n; };
|
|
4080
4090
|
let out;
|
|
4081
|
-
try { out = rosterGroups({ server: only, io: { budgetMs: ms("budget"), perTargetTimeoutMs: ms("per-target") } }); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
|
|
4091
|
+
try { out = await rosterGroups({ server: only, io: { budgetMs: ms("budget"), perTargetTimeoutMs: ms("per-target") } }); } catch (e) { bail(e.code || "E_SERVERS_UNREADABLE", e.message); }
|
|
4082
4092
|
if (JSON_MODE) { jsonOk(out); return; }
|
|
4083
4093
|
if (!out.groups.length) { console.log("no remote groups: no registrations and no saved routes"); return; }
|
|
4084
4094
|
for (const g of out.groups) {
|
|
@@ -4087,7 +4097,7 @@ function serverCmd() {
|
|
|
4087
4097
|
for (const i of g.instances) console.log(` • ${i.instance} ${i.missingRemotely ? "GONE on the host (saved route is stale: oats server forget)" : i.running === true ? "RUNNING" : i.running === false ? "idle" : "unknown"}${i.retirePending ? " RETIRING" : ""}${i.rollbackIncomplete ? " QUARANTINED" : ""}${i.savedRoute ? "" : " (observed only, no saved route)"}${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
|
|
4088
4098
|
for (const f of g.retireFailures || []) console.log(` ! deferred retirement of ${f.instance} (${f.agent}) FAILED there${f.error?.message ? `: ${f.error.message}` : ""}${f.retry ? ` — retry on the host: ${f.retry}` : ""}`);
|
|
4089
4099
|
}
|
|
4090
|
-
console.log(` bounds: ${out.bounds.perTargetTimeoutMs} ms per target within ${out.bounds.budgetMs} ms, ${out.bounds.elapsedMs} ms used
|
|
4100
|
+
console.log(` bounds: ${out.bounds.perTargetTimeoutMs} ms per target within ${out.bounds.budgetMs} ms, ${out.bounds.elapsedMs} ms used`);
|
|
4091
4101
|
return;
|
|
4092
4102
|
}
|
|
4093
4103
|
let servers;
|
|
@@ -4546,7 +4556,7 @@ else {
|
|
|
4546
4556
|
const wantsHelp = args.slice(1).some((a) => a === "--help" || a === "-h");
|
|
4547
4557
|
if (cmd && KERNEL_COMMANDS.has(cmd) && wantsHelp) { if (JSON_MODE) { jsonOk({ command: cmd, usage: usageLinesFor(cmd) }); process.exit(0); } usageFor(cmd); process.exit(0); }
|
|
4548
4558
|
if (flag("server") !== undefined && ROUTED_COMMANDS.has(cmd)) await serverRouteCmd();
|
|
4549
|
-
else if (cmd === "server") serverCmd();
|
|
4559
|
+
else if (cmd === "server") await serverCmd();
|
|
4550
4560
|
else if (cmd === "inspect") await inspectCmd();
|
|
4551
4561
|
else if (cmd === "operation") await operationCmd();
|
|
4552
4562
|
else if (cmd === "launch-config") await launchConfigCmd();
|
|
@@ -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
|
|
@@ -2806,9 +2827,14 @@ route target:
|
|
|
2806
2827
|
```
|
|
2807
2828
|
|
|
2808
2829
|
- **`probe`**: `{ok: true, features}` when the host's `status --json` was
|
|
2809
|
-
pulled, else `{ok: false, error: {code, message}}` (ssh failed
|
|
2810
|
-
answered `ok: false
|
|
2811
|
-
|
|
2830
|
+
pulled, else `{ok: false, error: {code, message}}` (ssh failed or timed
|
|
2831
|
+
out, `E_SSH`; or the host answered `ok: false`), with no `features` key.
|
|
2832
|
+
Every group is probed at once, each within its own deadline, so a group's
|
|
2833
|
+
`probe` depends only on its own host: one that does not answer in time is
|
|
2834
|
+
`E_SSH` with `ssh to <host> timed out: no answer within <n> s`, and every
|
|
2835
|
+
other group is unaffected. Before 0.55.0 the probes ran one after another
|
|
2836
|
+
against the total budget, and a group the budget did not reach was
|
|
2837
|
+
`E_ROSTER_BUDGET`; that code is no longer answered.
|
|
2812
2838
|
- **`probe.features`** (feature `server-probe-features`, OATS 0.49.0): the
|
|
2813
2839
|
host's kernel features, relayed from the top-level `features` of its
|
|
2814
2840
|
[`status --json`](#the-roster-oats-status---json), never probed: the roster
|
|
@@ -2824,7 +2850,7 @@ route target:
|
|
|
2824
2850
|
- **`workspace`** (feature `workspace-identity`, OATS 0.36.0): the host's
|
|
2825
2851
|
own `status --json` [`workspace` object](#workspace-identity-feature-workspace-identity-oats-0360),
|
|
2826
2852
|
relayed verbatim, or `null` when the host reports none (a deployment
|
|
2827
|
-
without `oats-local.yaml`, or a failed
|
|
2853
|
+
without `oats-local.yaml`, or a failed probe). A host before
|
|
2828
2854
|
0.36.0 answers the reachability-only object (`{reachable, code?, reason?,
|
|
2829
2855
|
message?}`) with no identity fields, so the identity is there only when
|
|
2830
2856
|
the object has a `key` field (which a 0.36.0 host always sends, `null` for
|
|
@@ -2863,6 +2889,12 @@ route target:
|
|
|
2863
2889
|
- `running` is `null` when unknown; `backend` is `tmux` for a row with a tmux
|
|
2864
2890
|
target, else `null`; `tmux`, `sessionTarget` (the recorded target of a home
|
|
2865
2891
|
a Herdr-era kernel opened) and `runtimeError` are as the host reports them.
|
|
2892
|
+
- **`bounds`**: `{budgetMs, perTargetTimeoutMs, elapsedMs}`. Each group's
|
|
2893
|
+
probe may take the smaller of `perTargetTimeoutMs` (`--per-target`,
|
|
2894
|
+
default 20 s) and `budgetMs` (`--budget`, default 45 s, the deadline of the
|
|
2895
|
+
whole answer); `elapsedMs` is what the answer took, about the slowest
|
|
2896
|
+
group's probe. Before 0.55.0 `bounds` also carried `skipped`, the number of
|
|
2897
|
+
groups the budget did not reach; it is gone with `E_ROSTER_BUDGET`.
|
|
2866
2898
|
|
|
2867
2899
|
<a id="servers-per-workspace"></a>
|
|
2868
2900
|
### Servers per workspace (feature `servers-per-workspace`)
|
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/integrations.md
CHANGED
package/docs/knowledge.md
CHANGED
|
@@ -6,7 +6,7 @@ kernel owns slot selection, composition and command dispatch; the capability
|
|
|
6
6
|
owns its knowledge format, instructions and promotion procedure. The model is
|
|
7
7
|
in [Knowledge, instances and evolving expertise](knowledge-theory.md).
|
|
8
8
|
|
|
9
|
-
This is the operator guide for **oats.okf 5.0.
|
|
9
|
+
This is the operator guide for **oats.okf 5.0.5**. Provider implementation and
|
|
10
10
|
recovery details belong to the [oats-okf README](https://github.com/awebai/oats-okf).
|
|
11
11
|
|
|
12
12
|
| Surface | What it holds |
|
|
@@ -23,7 +23,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
|
|
|
23
23
|
```yaml
|
|
24
24
|
# oats-workspace.yaml (excerpt)
|
|
25
25
|
packages:
|
|
26
|
-
oats.okf: v5.0.
|
|
26
|
+
oats.okf: v5.0.5
|
|
27
27
|
defaults:
|
|
28
28
|
knowledge: { oats.okf: { from: package } }
|
|
29
29
|
stores:
|
|
@@ -161,6 +161,18 @@ changes the soul declaration. `knowledge: none` removes the layer entirely.
|
|
|
161
161
|
automatic transcript capture, source registry, worker cursor or retire
|
|
162
162
|
harvest. An unrelated harvester can outlive its source; this is a
|
|
163
163
|
lifecycle property, not proof that missing source authority can be ignored.
|
|
164
|
+
|
|
165
|
+
One proposal per checkpoint, each concept a claim of its own in it, and
|
|
166
|
+
claims only for the nodes the source soul owns; a lesson for a node it only
|
|
167
|
+
reads goes in one line in the instance's hand-back, for that node's owner.
|
|
168
|
+
One harvester at a time, per instance (oats.okf 5.0.5): the source notes the
|
|
169
|
+
harvester's instance name and spawns no other while `oats status` still
|
|
170
|
+
lists it, since a harvester retires once it has handed over. What it learns
|
|
171
|
+
meanwhile goes into its next proposal; an instance that hands back with one
|
|
172
|
+
still listed names it and the claims still waiting. A harvester retained
|
|
173
|
+
after a publication failure stays listed, so it holds back its source's
|
|
174
|
+
later proposals: once that failure is dealt with, the operator retires it
|
|
175
|
+
(`oats retire <harvester>`).
|
|
164
176
|
3. **Judge and submit.** The harvester checks recorded source configuration,
|
|
165
177
|
accepted knowledge and open/recent harvest PRs. It reads named backing
|
|
166
178
|
notes, edits only owned nodes in its own Git checkout, validates the
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,10 +9,10 @@ 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.
|
|
13
|
-
| `oats.okf` | `v5.0.
|
|
14
|
-
| `oats.aweb` | `v1.27.
|
|
15
|
-
| `oats.engineering` | `v1.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.10.0` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
|
+
| `oats.okf` | `v5.0.5` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
|
+
| `oats.aweb` | `v1.27.2` | `oats.aweb` (messaging) | |
|
|
15
|
+
| `oats.engineering` | `v1.10.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
|
16
16
|
| `oats.authoring` | `v1.0.3` | `oats.authoring` | |
|
|
17
17
|
| `oats.cloning` | `v1.0.1` | `oats.cloning` | `cloner` |
|
|
18
18
|
| `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
|
|
@@ -29,7 +29,7 @@ no lock and adds nothing to an existing workspace.
|
|
|
29
29
|
## Find and use packages
|
|
30
30
|
|
|
31
31
|
- A workspace pins an official package by **bare version** in its
|
|
32
|
-
`packages:` map (`oats.okf: v5.0.
|
|
32
|
+
`packages:` map (`oats.okf: v5.0.5`); `oats sync` resolves it through the
|
|
33
33
|
catalog to an exact commit, fetches it, verifies its integrity and locks it.
|
|
34
34
|
A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
|
|
35
35
|
not join a team or adopt the publisher's workspace. See
|
package/docs/packages.md
CHANGED
|
@@ -44,14 +44,14 @@ whole organisation:
|
|
|
44
44
|
|
|
45
45
|
```yaml
|
|
46
46
|
packages:
|
|
47
|
-
oats.okf: v5.0.
|
|
47
|
+
oats.okf: v5.0.5 # bare version → the official catalog
|
|
48
48
|
acme.tools: git:github.com/acme/tools@v0.4.0 # direct ref: git:<repo>@<tag or full OID>
|
|
49
49
|
```
|
|
50
50
|
|
|
51
|
-
- **Bare version** (`v5.0.
|
|
51
|
+
- **Bare version** (`v5.0.5`, `5.0.5`, `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.
|
|
54
|
+
convention (`v5.0.5` 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,9 +74,9 @@ members:
|
|
|
74
74
|
- git:github.com/acme/agents
|
|
75
75
|
- git:github.com/acme/platform
|
|
76
76
|
packages:
|
|
77
|
-
oats.framework: v1.
|
|
78
|
-
oats.okf: v5.0.
|
|
79
|
-
oats.aweb: v1.27.
|
|
77
|
+
oats.framework: v1.10.0
|
|
78
|
+
oats.okf: v5.0.5
|
|
79
|
+
oats.aweb: v1.27.2
|
|
80
80
|
teams:
|
|
81
81
|
platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
|
|
82
82
|
defaults:
|
|
@@ -105,7 +105,7 @@ decision recorded in the lock.
|
|
|
105
105
|
$ oats sync
|
|
106
106
|
workspace acme (github.com/acme/agents @ 3f2a9c1e)
|
|
107
107
|
members agents ✓↔ (@ 3f2a9c1e) platform ✓↔ (@ 77c0a1b2) billing ✗ (no-backlink)
|
|
108
|
-
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.
|
|
108
|
+
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.0.5 ✓ (@ 73b85020)
|
|
109
109
|
changed acme.tools — → 0.4.0 (@ 47f4b816)
|
|
110
110
|
souls 9 discovered (6 members, 1 external, 2 package, 0 disabled here) · 0 private capabilities
|
|
111
111
|
teams platform (shared) · this deployment's: oats teams
|
|
@@ -134,7 +134,7 @@ Declaring a package in the workspace's `packages:` is the trust decision
|
|
|
134
134
|
## `oats package add | remove`
|
|
135
135
|
|
|
136
136
|
```bash
|
|
137
|
-
oats package add oats.aweb v1.27.
|
|
137
|
+
oats package add oats.aweb v1.27.2 # a catalog version
|
|
138
138
|
oats package add acme.tools git:github.com/acme/tools@v0.4.0
|
|
139
139
|
oats package remove acme.tools
|
|
140
140
|
```
|
|
@@ -160,8 +160,8 @@ same workspace commit hold identical locks.
|
|
|
160
160
|
"source": "catalog:oats.okf",
|
|
161
161
|
"url": "https://github.com/awebai/oats-okf.git",
|
|
162
162
|
"path": "oats-package",
|
|
163
|
-
"version": "5.0.
|
|
164
|
-
"commit": "
|
|
163
|
+
"version": "5.0.5",
|
|
164
|
+
"commit": "73b85020e52b8584cb15f153a39712f900e69918",
|
|
165
165
|
"integrity": "sha256-…",
|
|
166
166
|
"capabilities": ["oats.okf", "oats.okf-harvest", "oats.okf-maintenance"]
|
|
167
167
|
},
|
|
@@ -352,12 +352,12 @@ A soul that names one of the package's capabilities with
|
|
|
352
352
|
{
|
|
353
353
|
"policy": "docs/official-catalog.md",
|
|
354
354
|
"packages": {
|
|
355
|
-
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.
|
|
356
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.
|
|
355
|
+
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.0.5", "path": "oats-package" },
|
|
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`.
|