@awebai/oats 0.69.7 → 0.69.9
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/README.md +8 -5
- package/bin/oats.mjs +46 -17
- package/docs/capabilities.md +45 -0
- package/docs/desktop-cli-api.md +110 -16
- package/docs/desktop.md +29 -2
- package/docs/first-team.md +3 -2
- package/docs/implementation.md +4 -3
- package/docs/integrations.md +1 -1
- package/docs/named-test-runs.md +1 -1
- package/docs/official-catalog.md +3 -3
- package/docs/packages.md +7 -7
- package/docs/release-lane.md +5 -5
- package/docs/release-notes/v0.69.8.md +48 -0
- package/docs/release-notes/v0.69.9.md +92 -0
- package/docs/souls-and-instances.md +3 -1
- package/docs/upgrading.md +12 -5
- package/docs/workspaces.md +1 -1
- package/lib/core.mjs +45 -19
- package/lib/instance-listing.mjs +32 -2
- package/lib/kernel-features.mjs +1 -1
- package/lib/reserved-launch-env.mjs +2 -0
- package/lib/servers.mjs +8 -4
- package/lib/spawned-by.mjs +18 -0
- package/lib/status-words.mjs +32 -0
- package/package-catalog.json +4 -3
- package/package.json +1 -1
- package/packages/client/instance-name.mjs +20 -5
- package/packages/client/needs-input-reporting-gap.mjs +25 -0
- package/packages/client/spawn-preview-contract.mjs +3 -4
- package/skills/oats-getting-started/SKILL.md +367 -242
package/README.md
CHANGED
|
@@ -35,12 +35,15 @@ The [official catalog](docs/official-catalog.md) is the reviewed list of officia
|
|
|
35
35
|
curl -fsSL https://raw.githubusercontent.com/awebai/oats/main/skills/oats-getting-started/SKILL.md
|
|
36
36
|
```
|
|
37
37
|
|
|
38
|
-
If you are a person, give your coding agent (Claude Code, Codex, pi or any other) this page and say "set up OATS for
|
|
38
|
+
If you are a person, give your coding agent (Claude Code, Codex, pi or any other) this page and say "set up OATS for this project". It then:
|
|
39
39
|
|
|
40
|
-
- **Asks first, in one round:** your project, its repositories, the knowledge tools you use, and
|
|
41
|
-
- **Installs OATS
|
|
42
|
-
- **
|
|
43
|
-
- **
|
|
40
|
+
- **Asks first, in one round:** your project, its repositories and where the workspace should live, the knowledge tools you use, and how your agents message each other ([aweb](https://aweb.ai) by default).
|
|
41
|
+
- **Installs OATS, OATS Desktop and the messaging CLI.**
|
|
42
|
+
- **Creates your workspace's team:** you sign in to your aweb account in your browser, and one command creates the team, owned by your account, that every agent you spawn joins.
|
|
43
|
+
- **Writes your workspace** in one commit, in your repository or a new private one: the workspace and its team, nothing else. Or it joins this machine to an existing workspace.
|
|
44
|
+
- **Spawns the setup expert and opens the Desktop on it.** The setup expert is an OATS agent that turns OATS's defaults into your own coordination, knowledge and tasks capabilities, with you. You type only passwords, logins and tokens.
|
|
45
|
+
|
|
46
|
+
You end with a working workspace, the Desktop open on it, and its setup expert running.
|
|
44
47
|
|
|
45
48
|
Download the skill, don't web-fetch it: a tool that summarises pages would lose its exact commands.
|
|
46
49
|
|
package/bin/oats.mjs
CHANGED
|
@@ -53,7 +53,7 @@ const {
|
|
|
53
53
|
LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
|
|
54
54
|
capabilityManifests, capabilityTrust, capabilityExecutablePath,
|
|
55
55
|
officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
|
|
56
|
-
findInstanceHome, findInstanceHomes, homeLaunchLayers, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, suggestSpawnName, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, machineLaunchConfigs, machineLaunchConfigsFile, launchStartNotices, launchReportFor, explicitInstanceName, retireInstance, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, upgradeHoldsClaim, writeHomeRecord, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
|
|
56
|
+
findInstanceHome, findInstanceHomes, homeLaunchLayers, processScanInformation, enclosingInstanceHome, logicalCwd, readableInstanceHomes, workspaceOf, ensureRoot, findRoot, findAgent, findAgentAt, legacyLocalAgents, legacyCapturedHomes, listAgents, listInstances, servedIdentityLine, spawnInstanceAsync, suggestSpawnName, instanceSoulDir, stableSoulId, preparedSoulIdOf, recordedKernelBin, launchConfigsAt, machineLaunchConfigs, machineLaunchConfigsFile, launchStartNotices, launchReportFor, explicitInstanceName, MAX_INSTANCE_NAME, retireInstance, RETIRE_SELECTED_HOME, RETIRE_UNDER_CLAIM, inspectInstanceSession, inputInstanceSession, attachInstanceSession, startInstanceSession, upgradeHoldsClaim, writeHomeRecord, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
|
|
57
57
|
FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
|
|
58
58
|
} = await kernelImport("core", () => import("../lib/core.mjs"));
|
|
59
59
|
const {
|
|
@@ -84,7 +84,7 @@ const { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_B
|
|
|
84
84
|
const { observeInstanceGit, diffInstanceFile } = await kernelImport("instance-git", () => import("../lib/instance-git.mjs"));
|
|
85
85
|
const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstanceSameWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
|
|
86
86
|
const { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } = await kernelImport("retire-output", () => import("../lib/retire-output.mjs"));
|
|
87
|
-
const { livenessWord, lostLine, statusWord } = await kernelImport("status-words", () => import("../lib/status-words.mjs"));
|
|
87
|
+
const { livenessWord, lostLine, statusWord, waitingLine } = await kernelImport("status-words", () => import("../lib/status-words.mjs"));
|
|
88
88
|
const { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } = await kernelImport("retained-after-retire", () => import("../lib/retained-after-retire.mjs"));
|
|
89
89
|
const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
|
|
90
90
|
const { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposition, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } = await kernelImport("instance-inspect", () => import("../lib/instance-inspect.mjs"));
|
|
@@ -2601,7 +2601,7 @@ function printStatus({ root, agents: data, ws, problems }, verbose) {
|
|
|
2601
2601
|
{ const lost = lostLine(i); if (lost) console.log(` ${lost}`); }
|
|
2602
2602
|
// Feature waiting-on-you: non-null only on a running row; the reader has
|
|
2603
2603
|
// already validated the message (one line, no control characters).
|
|
2604
|
-
|
|
2604
|
+
{ const waiting = waitingLine(i); if (waiting) console.log(` ${waiting}`); }
|
|
2605
2605
|
const key = i.home ?? `${a.name}/${i.instance}`;
|
|
2606
2606
|
if (i.identity) console.log(` identity: ${servedIdentityLine(i.identity)}`);
|
|
2607
2607
|
// The kernel the home's plain `oats` runs (its last launch's), when it is not this one.
|
|
@@ -3695,8 +3695,9 @@ async function onboardCmd() {
|
|
|
3695
3695
|
const { OPERATOR_CAPABILITY } = await import("../lib/operator-coverage.mjs");
|
|
3696
3696
|
const wsName = standalone ? null : synced.discovery.workspace?.name;
|
|
3697
3697
|
const conventional = typeof wsName === "string" && wsName ? `${wsName}-oats-setup-expert` : null;
|
|
3698
|
-
const
|
|
3699
|
-
const
|
|
3698
|
+
const chosenExpert = setupExpertOf(synced.discovery, { conventional, workspaceName: wsName, capability: OPERATOR_CAPABILITY });
|
|
3699
|
+
const setupExpert = chosenExpert?.soul ?? null;
|
|
3700
|
+
const spawnHint = setupExpert ? `oats spawn ${setupExpert} --dir ${shortPath(dir)}${chosenExpert.name ? ` --name ${chosenExpert.name}` : ""}` : null;
|
|
3700
3701
|
const anySoulHint = `oats spawn <soul> --dir ${shortPath(dir)}${soulNames.length ? ` (e.g. ${soulNames.slice(0, 3).join(", ")})` : ""}`;
|
|
3701
3702
|
// A member's clone goes beside oats-local.yaml under its repo name; `agents/` is the instance
|
|
3702
3703
|
// homes, so a member called "agents" is cloned as `agents-repo/` (design doc §4). The HOST is
|
|
@@ -3746,18 +3747,24 @@ Next:
|
|
|
3746
3747
|
3. ${setupExpert ? `Spawn ${setupExpert}, this workspace's OATS setup expert
|
|
3747
3748
|
(it holds ${OPERATOR_CAPABILITY}), to guide the rest:` : `No soul here holds ${OPERATOR_CAPABILITY} — add a ${conventional ? `${conventional} soul` : "soul"} that declares it,
|
|
3748
3749
|
or spawn any listed soul:`}
|
|
3749
|
-
${spawnHint ?? anySoulHint}`);
|
|
3750
|
+
${spawnHint ?? anySoulHint}${chosenExpert?.why ? `\n (${chosenExpert.why})` : ""}`);
|
|
3750
3751
|
}
|
|
3751
3752
|
|
|
3752
|
-
/** The soul
|
|
3753
|
-
|
|
3754
|
-
|
|
3755
|
-
|
|
3756
|
-
*
|
|
3757
|
-
*
|
|
3758
|
-
*
|
|
3759
|
-
*
|
|
3760
|
-
|
|
3753
|
+
/** The framework's package soul that sets up a workspace (awebai/oats#1665 D1). */
|
|
3754
|
+
const FRAMEWORK_SETUP_SOUL = { package: "oats.framework", name: "oats-setup-expert" };
|
|
3755
|
+
|
|
3756
|
+
/** The soul `oats onboard` names as the workspace's OATS setup expert (awebai/oats#1314, #1665 D1), among
|
|
3757
|
+
* the souls a spawn can name (soulCandidates) whose own soul.yaml declares `capability` (oats.setup) with
|
|
3758
|
+
* `{ from: … }`, from any source (`off` is no declaration), in this order: the workspace's own soul named
|
|
3759
|
+
* `conventional` (`<workspace name>-oats-setup-expert`, null in a standalone view, which has no workspace
|
|
3760
|
+
* name); else oats.framework's package soul `oats-setup-expert`; else the first by name; else null. A soul
|
|
3761
|
+
* is never chosen by its name alone. Only the soul's own declaration is read, never a resolution:
|
|
3762
|
+
* oats.setup that reaches a soul through the workspace defaults alone is not seen.
|
|
3763
|
+
* → null, or { soul, name, why }: `soul` is the name to spawn it by (the bare name, else
|
|
3764
|
+
* `<member>/<soul>` (`<package>/<soul>`), else `<member repo key>/<soul>`, the first that names this soul
|
|
3765
|
+
* alone); `name` is the instance name for the package soul (packageInstanceName), else null; `why` says
|
|
3766
|
+
* why that name is not the conventional one, else null. */
|
|
3767
|
+
function setupExpertOf(discovery, { conventional, workspaceName, capability }) {
|
|
3761
3768
|
const candidates = soulCandidates(discovery);
|
|
3762
3769
|
const declares = (entry) => {
|
|
3763
3770
|
const caps = entry.definition?.capabilities;
|
|
@@ -3766,13 +3773,35 @@ function setupExpertOf(discovery, { conventional, capability }) {
|
|
|
3766
3773
|
};
|
|
3767
3774
|
const order = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
|
|
3768
3775
|
const entries = candidates.map((c) => c.entry).sort((a, b) => order(a.name, b.name) || order(qualifiedSoulName(a), qualifiedSoulName(b)));
|
|
3769
|
-
const
|
|
3776
|
+
const isFrameworkSoul = (e) => e.package === FRAMEWORK_SETUP_SOUL.package && e.name === FRAMEWORK_SETUP_SOUL.name;
|
|
3777
|
+
const chosen = (conventional && entries.find((e) => e.name === conventional && typeof e.package !== "string" && declares(e)))
|
|
3778
|
+
|| entries.find((e) => isFrameworkSoul(e) && declares(e))
|
|
3779
|
+
|| entries.find(declares);
|
|
3770
3780
|
if (!chosen) return null;
|
|
3771
3781
|
// The shortest name a spawn resolves to exactly this soul: two members can share a repository
|
|
3772
3782
|
// basename (github.com/a/agents, github.com/b/agents), so the last form is the full repo key.
|
|
3773
3783
|
const forms = [chosen.name, qualifiedSoulName(chosen), ...(typeof chosen.package === "string" ? [] : [`${chosen.repoKey}/${chosen.name}`])];
|
|
3774
3784
|
const only = (name) => { const hits = candidates.filter((c) => c.matches(name)); return hits.length === 1 && hits[0].entry === chosen; };
|
|
3775
|
-
|
|
3785
|
+
const soul = forms.find(only) ?? forms[forms.length - 1];
|
|
3786
|
+
return { soul, ...(isFrameworkSoul(chosen) && workspaceName ? packageInstanceName(discovery, workspaceName) : { name: null, why: null }) };
|
|
3787
|
+
}
|
|
3788
|
+
|
|
3789
|
+
/** The instance name the framework's setup soul is spawned by, for the workspace `workspaceName`:
|
|
3790
|
+
* `<workspace>-oats-setup-expert`; `<workspace>-oats-setup` when a soul of this workspace already holds
|
|
3791
|
+
* that name (spawn refuses an instance name that is a soul's); else none, and spawn names it. A name
|
|
3792
|
+
* over the instance-name limit is none too: onboarding never refuses on a long workspace name.
|
|
3793
|
+
* → { name, why }, `why` null for the conventional name. */
|
|
3794
|
+
function packageInstanceName(discovery, workspaceName) {
|
|
3795
|
+
const souls = new Set();
|
|
3796
|
+
for (const m of discovery.members || []) for (const s of m.souls || []) if (typeof s?.name === "string") souls.add(s.name);
|
|
3797
|
+
for (const x of discovery.external || []) if (typeof x?.soul?.name === "string") souls.add(x.soul.name);
|
|
3798
|
+
for (const s of discovery.packageSouls || []) if (typeof s?.name === "string") souls.add(s.name);
|
|
3799
|
+
const conventional = `${workspaceName}-oats-setup-expert`, fallback = `${workspaceName}-oats-setup`;
|
|
3800
|
+
const shared = "and an instance may not share a soul's name";
|
|
3801
|
+
if (conventional.length > MAX_INSTANCE_NAME) return { name: null, why: `no --name: ${conventional} would be ${conventional.length} characters, over the ${MAX_INSTANCE_NAME}-character instance-name limit; spawn names it` };
|
|
3802
|
+
if (!souls.has(conventional)) return { name: conventional, why: null };
|
|
3803
|
+
if (!souls.has(fallback)) return { name: fallback, why: `named ${fallback}: this workspace has a soul named ${conventional}, ${shared}` };
|
|
3804
|
+
return { name: null, why: `no --name: this workspace has souls named ${conventional} and ${fallback}, ${shared}; spawn names it` };
|
|
3776
3805
|
}
|
|
3777
3806
|
|
|
3778
3807
|
/** `oats onboard <dir> [--workspace <ref>] --check`: what onboarding <dir> here would meet, read-only (the
|
package/docs/capabilities.md
CHANGED
|
@@ -614,6 +614,42 @@ When the program has changed, the launch runs the new one and says so: a warning
|
|
|
614
614
|
in the answer and a `launch-warning` event in the home, both naming the path the
|
|
615
615
|
hooks were given and the path it runs.
|
|
616
616
|
|
|
617
|
+
A spawn hook also gets `OATS_SPAWNER_HOME` (feature `spawn-attribution`): the
|
|
618
|
+
absolute home of the instance whose session ran the spawn, as the kernel
|
|
619
|
+
validated it and recorded it in `instance.json` `spawnedBy`
|
|
620
|
+
([Spawned by](desktop-cli-api.md#spawned-by)). The hook's own
|
|
621
|
+
`OATS_INSTANCE_HOME` is the new instance's, so this is how a provider learns
|
|
622
|
+
who spawned it. Unlike `spawnOrigin`, which is informational, it selects who
|
|
623
|
+
signs: a messaging capability that attributes identities issues the new one
|
|
624
|
+
from this spawner, and from the deployment's own agent when it is absent. It is set only for a spawn
|
|
625
|
+
hook, and only when there is a spawner. It is absent when a person spawned (a
|
|
626
|
+
shell, the Desktop, an automation), when the caller's session was found gone,
|
|
627
|
+
when the caller's home is another deployment's, and for a `--server` spawn
|
|
628
|
+
whose caller is not a live home on that host. A spawner whose session cannot
|
|
629
|
+
be read is kept. It is independent of `--relation` and of `parentInstance`.
|
|
630
|
+
It is reserved like `OATS_HARNESS_EXECUTABLE`: a launch configuration, a
|
|
631
|
+
trigger or a hook's `env` cannot set it, an inherited value is dropped from
|
|
632
|
+
every hook's environment, from the environment a launch or a tmux server
|
|
633
|
+
starts with and from a scheduled job's, and it never reaches the harness's
|
|
634
|
+
pane, even from an existing server's environment. The kernel reads the caller from its environment only, so a harness that
|
|
635
|
+
strips its session's environment reads as a person's spawn: that changes the
|
|
636
|
+
recorded parent, never the human.
|
|
637
|
+
|
|
638
|
+
Read its absence as a person's spawn only when the kernel lists
|
|
639
|
+
`spawn-attribution` (`oats version --json` `features`): an older kernel never
|
|
640
|
+
sets it, so there absence says nothing. A provider gates the behaviour that
|
|
641
|
+
depends on it on that feature at run time, not with `compatibility.oats`,
|
|
642
|
+
which would refuse every capability of the package on an older host.
|
|
643
|
+
|
|
644
|
+
A messaging capability may record, in the served identity it records
|
|
645
|
+
(`identity` in its hook meta), an optional `attribution: {mode:
|
|
646
|
+
"human"|"none"|"unknown", human: {id, label}|null, parent: {id}|null}`. The
|
|
647
|
+
kernel never interprets its strings; it shows the human's `label` as
|
|
648
|
+
`attributedHuman` on status rows, read through the messaging slot under a
|
|
649
|
+
waiting claim's message rule ([Attributed human](desktop-cli-api.md#attributed-human)).
|
|
650
|
+
Absent means today's behaviour. `spawnedBy` and `attribution` report: no
|
|
651
|
+
kernel decision reads them.
|
|
652
|
+
|
|
617
653
|
A dispatched command (`oats <namespace> <command>`, from an instance home or
|
|
618
654
|
from the deployment directory) receives:
|
|
619
655
|
|
|
@@ -1196,6 +1232,15 @@ own dialog, and the kernel can't see which load. `reported` doesn't mean every
|
|
|
1196
1232
|
dialog: [What a hold leaves open](schedules.md#what-a-hold-leaves-open) names what
|
|
1197
1233
|
it can't see, the Claude dialogs that fire no hook among them.
|
|
1198
1234
|
|
|
1235
|
+
**A pi home with no provider** (oats.core 2.12.0). pi starts with no provider, takes
|
|
1236
|
+
its prompt and shows no error, so the home reads as running while nothing happens.
|
|
1237
|
+
On a real pass, spawn and launch hooks run `OATS_HARNESS_EXECUTABLE --list-models`,
|
|
1238
|
+
bounded at 3 s, and warn only when pi answers "No models available". The warning
|
|
1239
|
+
never refuses. No executable handed, a failed or slow probe, or any other answer
|
|
1240
|
+
says nothing. The hook sees the calling process's environment, not the pane's, so
|
|
1241
|
+
a pi folder (`PI_CODING_AGENT_DIR`) or key that only the launch or the pane has can
|
|
1242
|
+
warn on a pi that works.
|
|
1243
|
+
|
|
1199
1244
|
**One home per settings file.** The launch hook bakes the home it writes the
|
|
1200
1245
|
settings for into every command, as its real path (oats.core 2.4.1). The
|
|
1201
1246
|
script acts only when the session's `$OATS_INSTANCE_HOME` names that same
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -168,6 +168,7 @@ see the [official catalog](official-catalog.md) for current pins.
|
|
|
168
168
|
| `status-liveness` | the local liveness on `oats status --json` instance rows is complete: `running` and `runtimeState` are read live at every call, from the row's recorded tmux server under the pane and shell-descendant rule, with `false` for a shell only on positive evidence and `null` when the reading is inconclusive ([The roster](#the-roster-oats-status---json)). A client needs no liveness probe of its own beside the roster where the probe lists it, whether the read goes through the warm reader or the CLI. Independent of `warm-reader` | |
|
|
169
169
|
| `wake-hold` | a scheduled wake sends no key while the home has a live `permission`, `question` or unknown-reason claim, or a claims read that can't be trusted: the run is `skipped`, `reason: "waiting-on-you"`, `pending: true`, with `held` ([A held wake](schedules.md#a-held-wake)); the `wake-held` event ([the event kinds](#events)); `wakeHold` on every successful `session inspect --json` ([Inspect, input and attach](execution-targets.md#inspect-input-and-attach)), from the hook answer `dialogClaims` ([Commands and hooks](capabilities.md#commands-and-hooks)). Gate on the feature, then on `wakeHold`: the feature says this kernel holds, `wakeHold` whether this home's dialogs become claims, and `unknown` is not covered | |
|
|
170
170
|
| `lifecycle-claim-start` | every `oats session start` and `oats session restart`, and a scheduled start, holds the home's lifecycle claim for the whole start (#1602), as `details.action: "start"`: a retire, a stop apply or an upgrade apply that arrives while it runs is refused `E_LIFECYCLE_BUSY` with `details.action: "start"`; the start or restart is refused `E_INSTANCE_RETIRING` beside a retire and `E_LIFECYCLE_BUSY` (with `details.holder` and `details.action`) beside a stop or an upgrade, before any effect; two starts still answer `E_SESSION_START_BUSY` ([Commands that meet on one home](#lifecycle-pairs)). A restart holds one claim across its stop and its launch. A kernel without it takes no claim for these, and reads a `start` holder as a retire | |
|
|
171
|
+
| `spawn-attribution` | the kernel validates who spawned an instance: `spawnedBy` (`{instance, home}` or `null`) in `instance.json`, on the `spawned` event and on `oats status --json` rows and remote rows, and `OATS_SPAWNER_HOME` for spawn hooks ([Spawned by](#spawned-by)); `attributedHuman` on `oats status --json` rows and on remote rows ([Attributed human](#attributed-human)). Absent: no `spawnedBy` and no `attributedHuman`, and a capability must not read a missing `OATS_SPAWNER_HOME` as a person's spawn | |
|
|
171
172
|
|
|
172
173
|
Payload-only integers, never in the probe: `onboardApi: 2`, `syncApi: 1`,
|
|
173
174
|
`workspaceStatusApi: 1`, `capabilitiesApi: 1`, the `oats souls` document's
|
|
@@ -996,23 +997,35 @@ same argument, given once). The ref is checked before anything is written.
|
|
|
996
997
|
existing clone (the `clones:` entry, else `<dir>/<name>`), else where to
|
|
997
998
|
clone it: `<dir>/<name>`, or `<dir>/agents-repo` for a member named
|
|
998
999
|
`agents`. `url` is `null` when unknown.
|
|
999
|
-
- `next.spawn` is `oats spawn <soul> --dir <dir
|
|
1000
|
-
|
|
1001
|
-
`
|
|
1002
|
-
(confirmed members', external
|
|
1003
|
-
repository's own), the setup expert is:
|
|
1004
|
-
1. the soul named `<workspace name>-oats-setup-expert`
|
|
1005
|
-
`oats.setup`, where the workspace name is the `name:` of
|
|
1000
|
+
- `next.spawn` is a command string, `oats spawn <soul> --dir <dir>
|
|
1001
|
+
[--name <instance>]`, naming the workspace's OATS setup expert, else
|
|
1002
|
+
`null` (OATS 0.61.0; before it, only a soul named `oats-operator-expert`
|
|
1003
|
+
was named). Among the souls onboarding lists (confirmed members', external
|
|
1004
|
+
and package souls; standalone, the repository's own), the setup expert is:
|
|
1005
|
+
1. the workspace's own soul named `<workspace name>-oats-setup-expert`
|
|
1006
|
+
that declares `oats.setup`, where the workspace name is the `name:` of
|
|
1006
1007
|
`oats-workspace.yaml` (`sync.workspace.name`); a standalone view has no
|
|
1007
1008
|
workspace name, so this step does not apply there;
|
|
1008
|
-
2. otherwise
|
|
1009
|
-
|
|
1009
|
+
2. otherwise `oats.framework`'s package soul `oats-setup-expert`, when it
|
|
1010
|
+
declares `oats.setup`;
|
|
1011
|
+
3. otherwise the first soul by name that declares `oats.setup`;
|
|
1012
|
+
4. otherwise none: `null`.
|
|
1010
1013
|
|
|
1011
1014
|
A soul declares `oats.setup` when its own `soul.yaml` names it under
|
|
1012
1015
|
`capabilities:` as `{ from: … }`, from any source (`package`, `here` or a
|
|
1013
1016
|
member key); `oats.setup: off` does not count. A soul is never chosen by
|
|
1014
|
-
its name alone:
|
|
1015
|
-
not declare `oats.setup` falls through to
|
|
1017
|
+
its name alone: a soul named `<workspace name>-oats-setup-expert` or
|
|
1018
|
+
`oats-setup-expert` that does not declare `oats.setup` falls through to
|
|
1019
|
+
the next step.
|
|
1020
|
+
|
|
1021
|
+
Only the package soul of step 2 gets `--name`: `<workspace
|
|
1022
|
+
name>-oats-setup-expert`; `<workspace name>-oats-setup` when a soul of the
|
|
1023
|
+
workspace already holds the first name (spawn refuses an instance name that
|
|
1024
|
+
is a soul's); none when that is taken too, or when the name would pass the
|
|
1025
|
+
64-character instance-name limit. Spawn then names the instance itself;
|
|
1026
|
+
onboarding never refuses on a long workspace name. The text output says why
|
|
1027
|
+
a name other than the first is suggested. A soul of steps 1 and 3 is
|
|
1028
|
+
spawned with no `--name`.
|
|
1016
1029
|
|
|
1017
1030
|
Only the soul's own declaration is read, not its resolved composition:
|
|
1018
1031
|
`oats.setup` that reaches a soul only through the workspace's `defaults:`
|
|
@@ -2969,6 +2982,58 @@ Idempotent spawn replay returns the recorded value. Remote rows relay the
|
|
|
2969
2982
|
host's value unchanged, including historical values, and use `null` when the
|
|
2970
2983
|
host does not supply one. Consumers must allow for those historical meanings.
|
|
2971
2984
|
|
|
2985
|
+
<a id="spawned-by"></a>
|
|
2986
|
+
### Spawned by
|
|
2987
|
+
|
|
2988
|
+
From feature `spawn-attribution`, every new home records `spawnedBy`: the
|
|
2989
|
+
instance whose session ran the spawn, `{instance, home}` (the canonical
|
|
2990
|
+
absolute home), or `null`. `instance.json` and the `spawned` event's `data`
|
|
2991
|
+
carry it as recorded. The `oats status --json` row carries it only in that
|
|
2992
|
+
shape: an `instance` that is an instance name and an absolute `home`, and no
|
|
2993
|
+
other key; anything else (a hand-edited record) reads `null`. A home spawned
|
|
2994
|
+
before the feature has no key on its row. It is apart from lineage: `parentInstance`, `relation`
|
|
2995
|
+
and `relativeTo` say nothing about it, and a spawn with `--relation unrelated`
|
|
2996
|
+
from an instance still has a spawner.
|
|
2997
|
+
|
|
2998
|
+
It is read by the same check as [Spawn origin](#spawn-origin), plus the
|
|
2999
|
+
spawner's liveness. The caller is the instance that check confirms; the
|
|
3000
|
+
kernel then reads its session by its own liveness read (the `running` of
|
|
3001
|
+
`oats session inspect`, feature `session-inspect-running`, and of status
|
|
3002
|
+
rows), which has three answers:
|
|
3003
|
+
|
|
3004
|
+
- **Running:** the spawner is that instance.
|
|
3005
|
+
- **Found gone** (a fallback shell, a dead or absent pane, a home that never
|
|
3006
|
+
launched, or its tmux server gone): `null`.
|
|
3007
|
+
- **Cannot tell** (its tmux server cannot be read, its session receipt cannot
|
|
3008
|
+
be used): the spawner is kept. As far as anyone knows, that instance runs
|
|
3009
|
+
this command. The spawn is never refused.
|
|
3010
|
+
|
|
3011
|
+
So `spawnedBy` non-null implies `spawnOrigin: "instance"`, and
|
|
3012
|
+
`spawnOrigin: "instance"` with `spawnedBy: null` means the spawner's session
|
|
3013
|
+
was found gone. `spawnOrigin: "operator"` always has `spawnedBy: null`: a
|
|
3014
|
+
person's shell, the Desktop, an automation (a scheduled job's environment
|
|
3015
|
+
carries no instance), and a home of another deployment. A `--server` spawn
|
|
3016
|
+
sends no caller environment to the host, so its spawner is `null` unless the
|
|
3017
|
+
caller is a live home on that host.
|
|
3018
|
+
|
|
3019
|
+
Limits:
|
|
3020
|
+
|
|
3021
|
+
- It reads the environment only, so a harness that strips its session's
|
|
3022
|
+
environment reads as a person's spawn. That changes the recorded parent,
|
|
3023
|
+
never the human.
|
|
3024
|
+
- The caller is read from an unauthenticated environment, so any process of
|
|
3025
|
+
the same OS user can name a live instance as its spawner. That is accepted
|
|
3026
|
+
under the custody answer: a convention under the same OS user, not a
|
|
3027
|
+
boundary.
|
|
3028
|
+
- `spawnedBy` and the messaging identity's `attribution`
|
|
3029
|
+
([Attributed human](#attributed-human)) report, and no kernel decision
|
|
3030
|
+
reads them.
|
|
3031
|
+
- `spawnedBy` is written once, at spawn. Retire's lineage repair doesn't
|
|
3032
|
+
touch it, and it can name a home that no longer exists.
|
|
3033
|
+
|
|
3034
|
+
Spawn hooks get it as `OATS_SPAWNER_HOME` when it is not `null`
|
|
3035
|
+
([capabilities.md](capabilities.md#commands-and-hooks)).
|
|
3036
|
+
|
|
2972
3037
|
<a id="spawn-errors"></a>
|
|
2973
3038
|
### Spawn errors
|
|
2974
3039
|
|
|
@@ -3335,7 +3400,7 @@ its absence.
|
|
|
3335
3400
|
read** (OATS 0.52.0) is listed like every other, and one such home never
|
|
3336
3401
|
fails the listing. Its row has the fields of a home with no `instance.json`
|
|
3337
3402
|
and nothing from the record: `instance`, `home`, the Desktop facts
|
|
3338
|
-
(`startedAt`, `identityAddress`, `modelFrom`, each `null`), `waitingOnYou:
|
|
3403
|
+
(`startedAt`, `identityAddress`, `modelFrom`, `attributedHuman`, each `null`), `waitingOnYou:
|
|
3339
3404
|
null`, `rollbackIncomplete` and `retirePending` when present, and `running:
|
|
3340
3405
|
null` with `runtimeState: "unreachable"` and `runtimeError:
|
|
3341
3406
|
"E_UNIDENTIFIED_INSTANCE_HOME: <home>/instance.json cannot be read
|
|
@@ -3553,6 +3618,26 @@ restart, else `createdAt` for a launched home, else `null`. `modelFrom` is
|
|
|
3553
3618
|
`"harness-default"`, or `null` for an older home. `identityAddress` is the
|
|
3554
3619
|
messaging identity's `address` (else `alias`), or `null`.
|
|
3555
3620
|
|
|
3621
|
+
<a id="attributed-human"></a>
|
|
3622
|
+
**Attributed human** (feature `spawn-attribution`): `attributedHuman` is on
|
|
3623
|
+
every instance row, the label of the human the instance's messaging identity
|
|
3624
|
+
is attributed to, or `null`. The messaging capability may record an optional
|
|
3625
|
+
`attribution` in the served identity it records (`identity`):
|
|
3626
|
+
`{mode: "human"|"none"|"unknown", human: {id, label}|null, parent: {id}|null}`,
|
|
3627
|
+
with opaque strings the kernel never interprets. The row reads it by slot,
|
|
3628
|
+
never by name: only the identity of the capability whose layer is `messaging`
|
|
3629
|
+
counts. The row's `identity` falls back to any capability that recorded one;
|
|
3630
|
+
this never does, so no other capability can name a human on a row.
|
|
3631
|
+
It is the `label` when `mode` is `"human"`, else `null`; an absent
|
|
3632
|
+
`attribution` is `null` too, never shown as "none". The label is untrusted
|
|
3633
|
+
text, held to a waiting claim's `message` rule ([Waiting on you](#waiting-on-you)):
|
|
3634
|
+
one line of 1 to 200 characters with no refused character (a control
|
|
3635
|
+
character, a line break, a bidi control), else `null`. An omitted `human` or
|
|
3636
|
+
`parent` is `null`. A malformed `attribution` (an unknown `mode`, a `human` without a
|
|
3637
|
+
string `id` and `label`, a `parent` without a string `id`) reads as absent and
|
|
3638
|
+
never fails the row. `identity` on the row and in `oats inspect` carries the
|
|
3639
|
+
`attribution` as recorded.
|
|
3640
|
+
|
|
3556
3641
|
<a id="the-remote-roster-oats-server-roster---json"></a>
|
|
3557
3642
|
### The remote roster (`oats server roster --json`)
|
|
3558
3643
|
|
|
@@ -3627,7 +3712,8 @@ route target:
|
|
|
3627
3712
|
`identityAddress`, `teams`, `startedAt`, `createdAt`, `model`,
|
|
3628
3713
|
`runtimeState`, `parentInstance`, `siblingInstance`, `relation`,
|
|
3629
3714
|
`relativeTo` and `spawnOrigin`, and (relayed from 0.42.1) `work`, `repo`,
|
|
3630
|
-
`branch`, `modelFrom`, `soul` and `modules`,
|
|
3715
|
+
`branch`, `modelFrom`, `soul` and `modules`, and (feature
|
|
3716
|
+
`spawn-attribution`) `attributedHuman` and `spawnedBy`, are always present, `null`
|
|
3631
3717
|
when the host does not supply them (an older host, a fact it never
|
|
3632
3718
|
recorded, or a saved route the host no longer lists). Each is the
|
|
3633
3719
|
[local row's](#the-roster-oats-status---json) fact of the same name,
|
|
@@ -3635,7 +3721,10 @@ route target:
|
|
|
3635
3721
|
is a path on the host, never read here, and `soul` and `modules` are the
|
|
3636
3722
|
host's own drift observation (against its own members and lock), not
|
|
3637
3723
|
recomputed: `modules` is the drift rows, or the recorded map when the host
|
|
3638
|
-
could not read its workspace, as on a local row.
|
|
3724
|
+
could not read its workspace, as on a local row. `attributedHuman` passes
|
|
3725
|
+
the [local row's](#attributed-human) label rule again on this side, and
|
|
3726
|
+
`spawnedBy` the [local row's](#spawned-by) shape rule: a value either
|
|
3727
|
+
refuses is `null`.
|
|
3639
3728
|
- **`waitingOnYou`** (0.40.2, [Waiting on you](#waiting-on-you)) is on a row
|
|
3640
3729
|
only when the host's kernel reports it: a row from a host before 0.40.0,
|
|
3641
3730
|
and a saved route the host did not list, have no such key. Absent means
|
|
@@ -4482,8 +4571,13 @@ oats instance attention [--message <text>] [--clear] --json
|
|
|
4482
4571
|
- **Where it shows.** `waitingOnYou` on the events read, on `oats status
|
|
4483
4572
|
--json` instance rows (running rows only) and on `oats session inspect
|
|
4484
4573
|
--json` (beside `state`, whose enum is unchanged; `null` unless the harness
|
|
4485
|
-
is running). Plain `oats status` prints `! needs input (<reason>)
|
|
4486
|
-
<message>` under a running instance's row while it holds
|
|
4574
|
+
is running). Plain `oats status` prints `! needs input (<reason>) since
|
|
4575
|
+
<start>, <elapsed>: <message>` under a running instance's row while it holds
|
|
4576
|
+
a claim (the message and its colon are omitted when absent). The start is
|
|
4577
|
+
local to the CLI machine: `HH:MM` today, `Mon D HH:MM` on another day in
|
|
4578
|
+
the same year, or `YYYY-MM-DD HH:MM` in another year. Elapsed time is floored
|
|
4579
|
+
to `under a minute`, `N min`, `N h` or `N d`. A future start omits elapsed
|
|
4580
|
+
time; an unparseable start retains the line without any time.
|
|
4487
4581
|
- **Cost.** To compute the field, `oats status` reads the home log of each
|
|
4488
4582
|
running row (the workspace log only when the home log is absent), with
|
|
4489
4583
|
the same bounded read as the events read: at most the last 4 MiB, so a
|
package/docs/desktop.md
CHANGED
|
@@ -153,7 +153,33 @@ recently added workspaces there, once.
|
|
|
153
153
|
opened, or your home directory when there is none (never ~/Downloads);
|
|
154
154
|
**Choose oats…** opens in the directory of the chosen or discovered CLI.
|
|
155
155
|
|
|
156
|
-
Launch flags for scripted use: `--dir <workspace>` and
|
|
156
|
+
Launch flags for scripted use: `--dir <workspace>`, `--instance <name>` and
|
|
157
|
+
`OATS_DESKTOP_PORT`.
|
|
158
|
+
|
|
159
|
+
### Opening on an instance
|
|
160
|
+
|
|
161
|
+
`--instance <name>` beside `--dir <deployment>` opens the deployment's window
|
|
162
|
+
with that instance selected in the roster, as **Show in roster** selects it:
|
|
163
|
+
its row is revealed (a collapsed parent or the Background section opens) and
|
|
164
|
+
takes the keyboard focus. Press Enter to open its terminal. On a first launch
|
|
165
|
+
and on a launch while Desktop runs, it behaves the same way.
|
|
166
|
+
|
|
167
|
+
- **It only selects.** Nothing starts, attaches or is written, and Desktop
|
|
168
|
+
reads nothing for it beyond the roster reads it makes anyway.
|
|
169
|
+
- **The name must be an instance name**, the one `oats spawn --name` takes. Any
|
|
170
|
+
other value is ignored, and the window says the instance named at launch
|
|
171
|
+
isn't a valid instance name, without repeating the value.
|
|
172
|
+
- **Only the `--dir` deployment's own instances count.** Its other machines and
|
|
173
|
+
other workspaces never match. A name that isn't there yet (a spawn still
|
|
174
|
+
finishing) is waited for, over the roster's next reads, for about 30
|
|
175
|
+
seconds; then the window says "No instance <name> in this workspace". A name
|
|
176
|
+
two of its instances share selects nothing, and the window says so.
|
|
177
|
+
- **Your choice wins.** Selecting anything, typing or clicking while it waits
|
|
178
|
+
drops it. A later launch's `--instance` replaces it.
|
|
179
|
+
- Without `--dir`, with a `--dir` that isn't a deployment, or from a folder
|
|
180
|
+
that is one but no `--dir`, `--instance` is ignored and the launch behaves
|
|
181
|
+
as it would without it. A Desktop older than this one ignores it too, and
|
|
182
|
+
opens the workspace.
|
|
157
183
|
|
|
158
184
|
### One window per workspace
|
|
159
185
|
|
|
@@ -182,7 +208,8 @@ workspace on a server: `name — server`).
|
|
|
182
208
|
to restore, one window opens on the last workspace you used.
|
|
183
209
|
- **Launching again.** Running the app again (`open -a "OATS Desktop" --args
|
|
184
210
|
--dir <deployment>`, or from inside a deployment) adds that deployment if
|
|
185
|
-
needed and brings its window to the front, opening one if it has none
|
|
211
|
+
needed and brings its window to the front, opening one if it has none, with
|
|
212
|
+
its `--instance` selected ([Opening on an instance](#opening-on-an-instance)). Any
|
|
186
213
|
other launch brings the most recently used window to the front. A launch of
|
|
187
214
|
another version also offers to restart into it ([Updating](#updating)).
|
|
188
215
|
- **Closing.** Closing a window leaves the other windows, and their
|
package/docs/first-team.md
CHANGED
|
@@ -2,8 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
**The quick way:** the README's [Start here](../README.md#start-here): your
|
|
4
4
|
coding agent downloads the `oats-getting-started` skill verbatim and follows
|
|
5
|
-
it. It installs OATS, creates your workspace
|
|
6
|
-
|
|
5
|
+
it. It installs OATS, creates your workspace and its team (or joins an
|
|
6
|
+
existing workspace), and spawns the workspace's setup expert, `oats.framework`'s
|
|
7
|
+
`oats-setup-expert`, which does the rest with you. This page is the manual
|
|
7
8
|
path, for writing a workspace by hand.
|
|
8
9
|
|
|
9
10
|
The model is in [workspaces.md](workspaces.md), packages in
|
package/docs/implementation.md
CHANGED
|
@@ -28,8 +28,9 @@ reference pages ([workspaces](workspaces.md), [souls and instances](souls-and-in
|
|
|
28
28
|
through the home's `oats` link, before any PATH or global lookup (the
|
|
29
29
|
order is in [its README](../packages/pi/README.md)).
|
|
30
30
|
- **`oats.framework`** (`oats-package/`): the `oats.core`, `oats.setup`,
|
|
31
|
-
`oats.support` and `oats.knowledge-theory`
|
|
32
|
-
`knowledge-theory-expert`
|
|
31
|
+
`oats.onboarding`, `oats.support` and `oats.knowledge-theory`
|
|
32
|
+
capabilities and the `knowledge-theory-expert` and `oats-setup-expert`
|
|
33
|
+
souls,
|
|
33
34
|
released as a package under its own `oats-framework/v<version>` tags.
|
|
34
35
|
`oats.core` is the one with executables: its spawn and launch hook and the
|
|
35
36
|
Claude Code waiting emitter (`capabilities/oats-core/bin/`).
|
|
@@ -543,7 +544,7 @@ A pull request that touches `packages/tui/`, `packages/client/`, a
|
|
|
543
544
|
`test/tui-*.test.mjs` file or the workflow itself also runs
|
|
544
545
|
[`tui-macos.yml`](../.github/workflows/tui-macos.yml): every TUI test file,
|
|
545
546
|
`packages/tui/test/*.test.mjs` and `test/tui-*.test.mjs`, one file at a time
|
|
546
|
-
and each test within five minutes, on `macos-
|
|
547
|
+
and each test within five minutes, on `macos-15` with tmux installed, in about
|
|
547
548
|
five minutes. Its last step fails the run if a test left a tmux server on the
|
|
548
549
|
default `oats` socket, as a hand-started run checks after each file; it does
|
|
549
550
|
not give each file a process group of its own, as a hand-started run does. The
|
package/docs/integrations.md
CHANGED
package/docs/named-test-runs.md
CHANGED
|
@@ -246,7 +246,7 @@ These are constants of the scripts, not inputs:
|
|
|
246
246
|
| time for one file, then its process group is killed | 5 minutes | 20 minutes |
|
|
247
247
|
| time for the job | 60 minutes | 240 minutes |
|
|
248
248
|
| wait for the user manager | none | 60 seconds at the validation step |
|
|
249
|
-
| runner | `macos-
|
|
249
|
+
| runner | `macos-15` (arm64), Node 22 | `ubuntu-24.04` (x64), Node 22 |
|
|
250
250
|
|
|
251
251
|
A Linux file gets 20 minutes because the files that qualify the record
|
|
252
252
|
capture at scale ([#1108](https://github.com/awebai/oats/issues/1108)) run
|
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.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.19.0` (this repository) | `oats.core`, `oats.setup`, `oats.onboarding`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert`, `oats-setup-expert` |
|
|
13
13
|
| `oats.okf` | `v5.7.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
|
-
| `oats.aweb` | `v1.
|
|
15
|
-
| `oats.engineering` | `v1.
|
|
14
|
+
| `oats.aweb` | `v1.33.1` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
|
|
15
|
+
| `oats.engineering` | `v1.18.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.1.0` | `oats.cloning` | `cloner` |
|
|
18
18
|
| `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
|
package/docs/packages.md
CHANGED
|
@@ -51,7 +51,7 @@ packages:
|
|
|
51
51
|
- **Bare version** (`v5.7.0`, `5.7.0`, `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.7.0` or `oats-framework/v1.
|
|
54
|
+
convention (`v5.7.0` or `oats-framework/v1.19.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.
|
|
77
|
+
oats.framework: v1.19.0
|
|
78
78
|
oats.okf: v5.7.0
|
|
79
|
-
oats.aweb: v1.
|
|
79
|
+
oats.aweb: v1.33.1
|
|
80
80
|
teams:
|
|
81
81
|
platform: { team: "platform:acme.aweb.ai", description: Platform engineering }
|
|
82
82
|
defaults:
|
|
@@ -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.
|
|
137
|
+
oats package add oats.aweb v1.33.1 # 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
|
```
|
|
@@ -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.7.0", "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.19.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.19.0`
|
|
362
|
+
resolves to tag `oats-framework/v1.19.0`. Resolving through the catalog never
|
|
363
363
|
advances a lock by itself: `oats sync` does, and says so.
|
package/docs/release-lane.md
CHANGED
|
@@ -222,7 +222,7 @@ and packages it depends on, and what its entry points call of a cache.
|
|
|
222
222
|
version of an id from the row, so it refuses a step without it.
|
|
223
223
|
|
|
224
224
|
**`release.yml` and `build-installers.yml` name their runners by version
|
|
225
|
-
too** (`ubuntu-24.04`, as they name `macos-
|
|
225
|
+
too** (`ubuntu-24.04`, as they name `macos-15`), never by a label that GitHub
|
|
226
226
|
moves to another system by itself (`ubuntu-latest`). The Linux installers are
|
|
227
227
|
built on that runner, and what they need of a system follows the system that
|
|
228
228
|
built them.
|
|
@@ -231,7 +231,7 @@ break on the new system shows in pull-request CI first and not at a release.
|
|
|
231
231
|
|
|
232
232
|
The labels `release.yml` and `build-installers.yml` may name are a list beside
|
|
233
233
|
the table of actions in `test/workflow-no-cache.test.mjs`: `ubuntu-24.04` and
|
|
234
|
-
`macos-
|
|
234
|
+
`macos-15`. Every job of the two runs on a label of that list, and both build
|
|
235
235
|
on the same Linux. A label is added to the list by whoever decides the runner,
|
|
236
236
|
as an action's row is by whoever read it.
|
|
237
237
|
|
|
@@ -401,7 +401,7 @@ DMG/ZIP/AppImage/DEB artifacts exist, both packaged macOS `.app` bundles
|
|
|
401
401
|
pass strict deep codesign verification of their complete ad-hoc signatures
|
|
402
402
|
(`codesign --verify --deep --strict`), node-pty's packaged `spawn-helper` is
|
|
403
403
|
executable, and node-pty loads and spawns under the packaged Electron ABI.
|
|
404
|
-
The macOS x64 leg cross-builds on macos-
|
|
404
|
+
The macOS x64 leg cross-builds on macos-15 and installs Rosetta 2 so that its
|
|
405
405
|
x64 Electron + node-pty ABI probe really executes; a wrong-architecture
|
|
406
406
|
native module fails that leg.
|
|
407
407
|
|
|
@@ -480,8 +480,8 @@ always records `release.status: pending`.
|
|
|
480
480
|
## Releasing `oats.framework`
|
|
481
481
|
|
|
482
482
|
The distribution package in `oats-package/` (`oats.core`, `oats.setup`,
|
|
483
|
-
`oats.support`, `oats.knowledge-theory`) is not published
|
|
484
|
-
by this lane. A deployment takes it from this repository at the tag
|
|
483
|
+
`oats.onboarding`, `oats.support`, `oats.knowledge-theory`) is not published
|
|
484
|
+
by `release.yml` or by this lane. A deployment takes it from this repository at the tag
|
|
485
485
|
`oats-framework/v<version>`, through the catalog ref or its workspace pin. A
|
|
486
486
|
skill changed under `oats-package/` therefore reaches deployments only when
|
|
487
487
|
that tag moves, whatever kernel version carried the change.
|