@awebai/oats 0.69.4 → 0.69.5
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 +68 -49
- package/docs/configuration.md +12 -0
- package/docs/desktop-cli-api.md +8 -1
- package/docs/execution-targets.md +25 -3
- package/docs/implementation.md +10 -3
- package/docs/integrations.md +2 -2
- package/docs/knowledge.md +9 -6
- package/docs/official-catalog.md +5 -5
- package/docs/packages.md +14 -14
- package/docs/release-notes/v0.69.5.md +146 -0
- package/docs/tui.md +2 -1
- package/docs/upgrading.md +16 -5
- package/docs/workspaces.md +2 -2
- package/lib/agents-root.mjs +51 -0
- package/lib/automation-api.mjs +7 -0
- package/lib/automation-scope.mjs +35 -0
- package/lib/automations.mjs +2 -1
- package/lib/compile-cache.mjs +36 -0
- package/lib/core.mjs +39 -1348
- package/lib/deployment-path.mjs +127 -0
- package/lib/deployments.mjs +2 -2
- package/lib/drift.mjs +95 -0
- package/lib/hot-reads.mjs +131 -0
- package/lib/instance-address.mjs +21 -0
- package/lib/instance-lifecycle.mjs +4 -16
- package/lib/instance-listing.mjs +730 -0
- package/lib/instance-resolution.mjs +5 -166
- package/lib/materialize.mjs +2 -87
- package/lib/member-clone.mjs +188 -0
- package/lib/package-catalog.mjs +93 -0
- package/lib/packages.mjs +4 -24
- package/lib/reserved-launch-env.mjs +20 -0
- package/lib/resolved-deployment.mjs +1 -1
- package/lib/schedule.mjs +5 -29
- package/lib/semver.mjs +12 -0
- package/lib/servers.mjs +10 -12
- package/lib/session-end.mjs +3 -2
- package/lib/session-inspect.mjs +219 -0
- package/lib/soul-listing.mjs +216 -0
- package/lib/status-words.mjs +30 -0
- package/lib/version.mjs +9 -0
- package/lib/write-file-atomic.mjs +28 -0
- package/package-catalog.json +4 -4
- package/package.json +1 -1
- package/packages/tui/lib/store.mjs +7 -3
- package/skills/oats-getting-started/SKILL.md +3 -3
package/bin/oats.mjs
CHANGED
|
@@ -25,52 +25,66 @@ import { constants as osConstants, homedir, tmpdir } from "node:os";
|
|
|
25
25
|
import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
|
|
26
26
|
import { fileURLToPath } from "node:url";
|
|
27
27
|
import { performance } from "node:perf_hooks";
|
|
28
|
-
import {
|
|
29
|
-
import {
|
|
30
|
-
import {
|
|
31
|
-
|
|
32
|
-
|
|
28
|
+
import { spawnSync as spawnSyncProc } from "node:child_process";
|
|
29
|
+
import { enableCliCompileCache } from "../lib/compile-cache.mjs";
|
|
30
|
+
import { hotImport, hotRead } from "../lib/hot-reads.mjs";
|
|
31
|
+
|
|
32
|
+
// Node's compile cache is on before the kernel is parsed (lib/compile-cache.mjs): static imports are
|
|
33
|
+
// all parsed and linked before this module's body runs, so they are Node built-ins and the two small
|
|
34
|
+
// dependency-free modules above, and the kernel and `yaml` are imported here, in order, once it is on.
|
|
35
|
+
enableCliCompileCache();
|
|
36
|
+
// A hot read (lib/hot-reads.mjs) imports only the leaves it uses, never core.mjs: each line below takes
|
|
37
|
+
// the leaves its names come from, and every other command imports every module, in this order. A hot
|
|
38
|
+
// read takes its names from lib/hot-reads.mjs: a name newly used on a hot read's path must be listed
|
|
39
|
+
// there, under its line, or its first use throws (a tripwire); test/cli-hot-reads.test.mjs pins what
|
|
40
|
+
// each hot read must not load. Each line names its module and imports it by one string literal.
|
|
41
|
+
const HOT_READ = hotRead(process.argv.slice(2));
|
|
42
|
+
const kernelImport = (name, load) => (HOT_READ ? hotImport(HOT_READ, name) : load());
|
|
43
|
+
const { doctorCaptureWarnings } = await kernelImport("doctor-capture", () => import("../lib/doctor-capture.mjs"));
|
|
44
|
+
const { assertNoPartialUpgrade } = await kernelImport("upgrade-state", () => import("../lib/upgrade-state.mjs"));
|
|
45
|
+
const { runtimeNameWarning, noteRuntimeName } = await kernelImport("deprecation", () => import("../lib/deprecation.mjs"));
|
|
46
|
+
const { errorCause, herdrSettingRemoved, isAnswerCode, kernelCode, OWN_NAME_FAILURES, reportDefect, spawnRefusalDetails } = await kernelImport("errors", () => import("../lib/errors.mjs"));
|
|
47
|
+
const {
|
|
33
48
|
LAYERS, OATS_VERSION, manifestOperations, upgradeHomeMeta,
|
|
34
49
|
capabilityManifests, capabilityTrust, capabilityExecutablePath,
|
|
35
50
|
officialPackageCatalog, officialCatalogFile, officialCapabilityAliases, resolvedFromHome, resolvedFromPrepared, teamEnv, isWorkspaceHome, preWorkspaceHome, isCapturedHome, capturedHomeRefusal, composeInstanceAgentsMd, parseYamlNested, withConfigFile,
|
|
36
51
|
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, defaultRepo, RELATIONS, validateLaunchConfig, validateLaunchConfigDefaults, renderLaunchRecipe, describeLaunchCommand, redactLaunchRecipe, withSafeTaskPrompt, LAUNCH_HARNESSES, planLaunch, redactLaunchCommand, restartInstanceSession,
|
|
37
52
|
FAILED_SPAWN_BRANCH_LEFT, RETIRE_DELETE_BRANCH_REFUSED,
|
|
38
|
-
}
|
|
39
|
-
|
|
53
|
+
} = await kernelImport("core", () => import("../lib/core.mjs"));
|
|
54
|
+
const {
|
|
40
55
|
writeFileAtomic, LOCK_FILE, canonicalLock, readLock, readLockIfPresent, writeLock, resolvePackages, memoizedRemote,
|
|
41
|
-
classifyPackageValue, parsePackageRequest }
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
import { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } from "../lib/retained-after-retire.mjs";
|
|
56
|
+
classifyPackageValue, parsePackageRequest } = await kernelImport("packages", () => import("../lib/packages.mjs"));
|
|
57
|
+
const { harnessTrust } = await kernelImport("harness-trust-write", () => import("../lib/harness-trust-write.mjs"));
|
|
58
|
+
const { previewLaunchEnvironment, previewPaneEnvironment } = await kernelImport("core", () => import("../lib/core.mjs"));
|
|
59
|
+
const { PI_BRIDGE, piBridgeFolders, piBridgeSkewWarnings, planPiBridges, piBridgePlanLines, piBridgeStepProblem, piBridgeFailure, kernelLookup, kernelLookupResult, planCliUpdate, desktopFirstLine, bridgeLookup, bridgeLookupProblem } = await kernelImport("pi-bridge", () => import("../lib/pi-bridge.mjs"));
|
|
60
|
+
const { loadLocal, validateWorkspace, validateLocal, discoverPackageSouls, unlockedPackages, workspaceWarnings, memberRowByKey } = await kernelImport("workspace", () => import("../lib/workspace.mjs"));
|
|
61
|
+
const { discoveredTeamKeys, isTeamRefusal, localTeamsClosedProblem, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } = await kernelImport("teams", () => import("../lib/teams.mjs"));
|
|
62
|
+
const { LAUNCH_KEY_UNCHECKED, LAUNCH_PREFERENCE_UNMATCHED, launchKeyQuoted, launchKeysUnmatched, launchLayers, soulLaunchCommand, unmatchedKeyMessage } = await kernelImport("launch-preference", () => import("../lib/launch-preference.mjs"));
|
|
63
|
+
const { terminalText } = await kernelImport("refused-text", () => import("../lib/refused-text.mjs"));
|
|
64
|
+
const { qualifiedSoulName, soulCandidates, soulsOffered } = await kernelImport("instance-resolution", () => import("../lib/instance-resolution.mjs"));
|
|
65
|
+
const { parseConfigData } = await kernelImport("config-data", () => import("../lib/config-data.mjs"));
|
|
66
|
+
const remoteModule = await kernelImport("remote", () => import("../lib/remote.mjs"));
|
|
67
|
+
const { activateLocalInputs, localRevision } = await kernelImport("local-inputs", () => import("../lib/local-inputs.mjs"));
|
|
68
|
+
const { default: YAML } = await kernelImport("yaml", () => import("yaml"));
|
|
69
|
+
const { attachArgv, checkRemote, connectServer, forgetSnapshot, getServer, inspectRemote, startRemote, restartRemote, launchConfigRemote, scheduleRemote, listSnapshots, learnWorkspaceKey, readServers, redactArgv, reportedWorkspaceKey, rosterGroups, routeCapability, routeCommand, runRemote, serverFlagOf, targetOf, updateServers, validateServer, workspaceKeyOfStatus, workspaceMismatch, SERVERS_FILE } = await kernelImport("servers", () => import("../lib/servers.mjs"));
|
|
70
|
+
const { readSessionViewer } = await kernelImport("session-viewer", () => import("../lib/session-viewer.mjs"));
|
|
71
|
+
const { tickTriggers } = await kernelImport("triggers", () => import("../lib/triggers.mjs"));
|
|
72
|
+
const A = await kernelImport("automations", () => import("../lib/automations.mjs"));
|
|
73
|
+
const { parseEnvelopeText, unresolvedScheduleAttempts, scheduleScopeOf, listSchedules, describe: describeSchedule, testSchedule, addSchedule, updateSchedule, updateScheduleDescription, setEnabled: setScheduleEnabled, removeSchedule, runNow: runScheduleNow, reconcile: reconcileSchedule, tickHost, tickWorkspace, scopeAutomations, scheduleKind, registerWorkspace, unregisterWorkspace, readRegistry, schedulerStatus, saveWakeForHome, removeWakeForHome, wakeFromFlags, withHostLock, scheduleError, SCHEDULE_API } = await kernelImport("schedule", () => import("../lib/schedule.mjs"));
|
|
74
|
+
const { hostUnitFiles, hostUnitStatus, installHostUnit, uninstallHostUnit } = await kernelImport("schedule-host", () => import("../lib/schedule-host.mjs"));
|
|
75
|
+
const { kernelNode, stableNode } = await kernelImport("stable-node", () => import("../lib/stable-node.mjs"));
|
|
76
|
+
const { receiveAttachment, uploadAttachment, readStreamBounded, MAX_ATTACHMENT_BYTES } = await kernelImport("attachments", () => import("../lib/attachments.mjs"));
|
|
77
|
+
const { observeInstanceGit, diffInstanceFile } = await kernelImport("instance-git", () => import("../lib/instance-git.mjs"));
|
|
78
|
+
const { planStop, applyStop, planRetire, retireDefaultsLine, stopClosingLine, descendantsOf, resolveInstance: resolveInstanceForCli, setInstanceColor, setInstanceBackground, setInstanceSameWork, STOP_WARNINGS } = await kernelImport("instance-lifecycle", () => import("../lib/instance-lifecycle.mjs"));
|
|
79
|
+
const { extraWorktreeLines, formatBytes, warningLines, workRecoveryLines } = await kernelImport("retire-output", () => import("../lib/retire-output.mjs"));
|
|
80
|
+
const { livenessWord, lostLine, statusWord } = await kernelImport("status-words", () => import("../lib/status-words.mjs"));
|
|
81
|
+
const { retainedRecoveryLines, retainedWorktreeLines, retainedWorktrees } = await kernelImport("retained-after-retire", () => import("../lib/retained-after-retire.mjs"));
|
|
68
82
|
const await_import_lifecycle = () => ({ resolveInstance: resolveInstanceForCli });
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
83
|
+
const { homeTarget, soulTarget, isWorkspaceContext, inspectDocument, withComposition, withSkills, readinessDocument, policyOf, policySoul, manifestMissingRequires, INSPECT_OPERATIONS_API } = await kernelImport("instance-inspect", () => import("../lib/instance-inspect.mjs"));
|
|
84
|
+
const { readEvents, setWaiting, incarnationOf } = await kernelImport("instance-events", () => import("../lib/instance-events.mjs"));
|
|
85
|
+
const { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } = await kernelImport("deployments", () => import("../lib/deployments.mjs"));
|
|
86
|
+
const { observeResolvedDeployment } = await kernelImport("resolved-deployment", () => import("../lib/resolved-deployment.mjs"));
|
|
87
|
+
const { SESSION_RESUME_FEATURE } = await kernelImport("session-resume-contract", () => import("../lib/session-resume-contract.mjs"));
|
|
74
88
|
|
|
75
89
|
const rawArgs = process.argv.slice(2);
|
|
76
90
|
/** The kernel's switches: a value never rides one (`--yolo=false` must not turn yolo on). */
|
|
@@ -1776,7 +1790,7 @@ function standaloneCatalogVersion(ref) {
|
|
|
1776
1790
|
async function discoverForCli(ctx, bail) {
|
|
1777
1791
|
// The standalone case (decisions 10/25) is a discovery too: the repo's own view
|
|
1778
1792
|
// plus the kernel's oats.core default — discoverOrStandalone decides.
|
|
1779
|
-
try { const { discoverOrStandalone } = await import("../lib/
|
|
1793
|
+
try { const { discoverOrStandalone } = await import("../lib/member-clone.mjs"); return await discoverOrStandalone(ctx.local, { deployment: ctx.deploymentDir, remoteOptions: ctx.remoteOptions }); }
|
|
1780
1794
|
catch (e) {
|
|
1781
1795
|
if (typeof e?.code === "string" && e.code.startsWith("E_")) return bail(e.code, e.message, e.details ?? e.provenance);
|
|
1782
1796
|
throw e;
|
|
@@ -2225,7 +2239,7 @@ function sharedTeamRows(discovery) {
|
|
|
2225
2239
|
* computer (member clones and the rule that found each, disabled souls, the lock); file locations with
|
|
2226
2240
|
* browsable urls; each catalog package's newer version, when the official catalog has one. */
|
|
2227
2241
|
async function workspaceStatusFacts(result, discovery, lock, ctx) {
|
|
2228
|
-
const { memberCloneOf } = await import("../lib/
|
|
2242
|
+
const { memberCloneOf } = await import("../lib/member-clone.mjs");
|
|
2229
2243
|
const { browseUrl } = remoteModule;
|
|
2230
2244
|
const defaults = discovery.standalone === true ? {} : (discovery.workspace?.defaults ?? {});
|
|
2231
2245
|
const rows = (entries) => Object.entries(entries && typeof entries === "object" ? entries : {}).map(([name, v]) => ({ name, from: v === "off" ? null : v?.from ?? null, off: v === "off" })).sort((a, b) => (a.name < b.name ? -1 : 1));
|
|
@@ -2242,7 +2256,7 @@ async function workspaceStatusFacts(result, discovery, lock, ctx) {
|
|
|
2242
2256
|
});
|
|
2243
2257
|
result.disabledSouls = [...(Array.isArray(ctx.local?.souls?.disabled) ? ctx.local.souls.disabled : [])];
|
|
2244
2258
|
result.lock = { path: join(ctx.deploymentDir, LOCK_FILE), lockfileVersion: lock.lockfileVersion ?? null };
|
|
2245
|
-
const { compareSemver } = await import("../lib/
|
|
2259
|
+
const { compareSemver } = await import("../lib/semver.mjs");
|
|
2246
2260
|
let catalog = null; try { catalog = officialPackageCatalog(); } catch { catalog = null; }
|
|
2247
2261
|
const cat = catalog && typeof catalog === "object" ? (catalog.packages && typeof catalog.packages === "object" && !("url" in catalog.packages) ? catalog.packages : catalog) : {};
|
|
2248
2262
|
for (const p of result.packages) {
|
|
@@ -2668,12 +2682,12 @@ async function statusDrift(data) {
|
|
|
2668
2682
|
let discovery;
|
|
2669
2683
|
// The standalone view (decisions 10/25) is a discovery too: drift of a standalone
|
|
2670
2684
|
// instance is computed against its member's current state, not reported "unreachable".
|
|
2671
|
-
try { const { discoverOrStandalone } = await import("../lib/
|
|
2685
|
+
try { const { discoverOrStandalone } = await import("../lib/member-clone.mjs"); discovery = await discoverOrStandalone(ctx.local, { lock, remoteOptions: remoteOptionsFromEnv() }); }
|
|
2672
2686
|
catch (e) {
|
|
2673
2687
|
const reason = e?.details?.reason ? `${e.code}: ${e.details.reason}` : (e?.code || e?.message || "unknown");
|
|
2674
2688
|
return { drift: new Map(), soul: new Map(), souls, unreachable: { code: e?.code ?? null, reason, message: e?.message ?? String(e) }, local: ctx.local, discovery: null };
|
|
2675
2689
|
}
|
|
2676
|
-
const { driftOf, soulDriftOf } = await import("../lib/
|
|
2690
|
+
const { driftOf, soulDriftOf } = await import("../lib/drift.mjs");
|
|
2677
2691
|
const drift = new Map();
|
|
2678
2692
|
const soul = new Map();
|
|
2679
2693
|
for (const a of data) for (const i of a.instances || []) {
|
|
@@ -2834,7 +2848,8 @@ async function status() {
|
|
|
2834
2848
|
if (a.description) console.log(` ${a.description}`);
|
|
2835
2849
|
for (const i of a.instances) {
|
|
2836
2850
|
// Feature instance-background: the row is marked; it is listed like any other.
|
|
2837
|
-
console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${
|
|
2851
|
+
console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${statusWord(i)} (branch ${i.branch || "?"}, ${i.work || "?"})${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
|
|
2852
|
+
{ const lost = lostLine(i); if (lost) console.log(` ${lost}`); }
|
|
2838
2853
|
// Feature waiting-on-you: non-null only on a running row; the reader has
|
|
2839
2854
|
// already validated the message (one line, no control characters).
|
|
2840
2855
|
if (i.running === true && i.waitingOnYou) console.log(` ! needs input (${i.waitingOnYou.reason ?? "unknown"})${i.waitingOnYou.message ? `: ${i.waitingOnYou.message}` : ""}`);
|
|
@@ -2854,8 +2869,6 @@ async function status() {
|
|
|
2854
2869
|
}
|
|
2855
2870
|
}
|
|
2856
2871
|
|
|
2857
|
-
/** A status row's liveness in text: `running` null (a server that cannot be read, a Herdr home) is unknown, never idle. */
|
|
2858
|
-
const livenessWord = (i) => i.running === true ? "RUNNING" : i.running === false ? "idle" : "unknown";
|
|
2859
2872
|
/** The flags `oats spawn` reads: those taking a value, and switches. `--provider` takes two words.
|
|
2860
2873
|
* `--instance` is refused by a local spawn (with its replacement) but still travels to an older
|
|
2861
2874
|
* host through `--server`, whose route reads it. `--max-age` reaches here only on a preview or an
|
|
@@ -4462,7 +4475,10 @@ async function serverCmd() {
|
|
|
4462
4475
|
for (const g of out.groups) {
|
|
4463
4476
|
console.log(` ${g.server}${g.label && g.label !== g.server ? ` ${g.label}` : ""} [${g.id}] ssh ${g.target.sshHost} workspace ${g.target.workspace}${g.registrationPresent ? "" : " (registration removed or changed; saved routes only)"}`);
|
|
4464
4477
|
console.log(g.probe?.ok ? ` reachable, ${g.souls.length} soul(s)` : ` UNREACHABLE: ${g.probe?.error?.message || "?"}`);
|
|
4465
|
-
for (const i of g.instances)
|
|
4478
|
+
for (const i of g.instances) {
|
|
4479
|
+
console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${i.missingRemotely ? "GONE on the host (saved route is stale: oats server forget)" : livenessWord(i)}${i.retirePending ? " RETIRING" : ""}${i.rollbackIncomplete ? " QUARANTINED" : ""}${i.savedRoute ? "" : " (observed only, no saved route)"}${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
|
|
4480
|
+
const lost = lostLine(i, { host: g.target.sshHost || g.server }); if (lost) console.log(` ${lost}`);
|
|
4481
|
+
}
|
|
4466
4482
|
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}` : ""}`);
|
|
4467
4483
|
}
|
|
4468
4484
|
console.log(` bounds: ${out.bounds.perTargetTimeoutMs} ms per target within ${out.bounds.budgetMs} ms, ${out.bounds.elapsedMs} ms used`);
|
|
@@ -4859,7 +4875,10 @@ async function serverRouteCmd() {
|
|
|
4859
4875
|
console.log(`oats status — server ${id} (ssh ${r.target.sshHost}, workspace ${r.target.workspace})\n`);
|
|
4860
4876
|
for (const a of r.agents || []) {
|
|
4861
4877
|
console.log(` ${a.name} [work: ${a.work || "checkout"}, repo: ${a.repo || "?"}]`);
|
|
4862
|
-
for (const i of a.instances || [])
|
|
4878
|
+
for (const i of a.instances || []) {
|
|
4879
|
+
console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${statusWord(i)}${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
|
|
4880
|
+
const lost = lostLine(i, { host: r.target.sshHost || id }); if (lost) console.log(` ${lost}`);
|
|
4881
|
+
}
|
|
4863
4882
|
}
|
|
4864
4883
|
const snaps = r.snapshots || [];
|
|
4865
4884
|
if (snaps.length) console.log(`\n spawned from this machine: ${snaps.map((s) => s.instance).join(", ")}`);
|
package/docs/configuration.md
CHANGED
|
@@ -655,6 +655,18 @@ home has its own copy under `<home>/.oats/modules/<capability>/`
|
|
|
655
655
|
([souls-and-instances.md](souls-and-instances.md)). The store is a cache; it
|
|
656
656
|
is safe to delete.
|
|
657
657
|
|
|
658
|
+
## The compile cache
|
|
659
|
+
|
|
660
|
+
Every `oats` command keeps Node's compile cache in `~/.oats/compile-cache`
|
|
661
|
+
(`$OATS_HOME_DIR/compile-cache` when `OATS_HOME_DIR` is set), so a command
|
|
662
|
+
does not recompile the kernel each time it starts. The CLI creates the
|
|
663
|
+
directory mode 0700. It is a cache: delete it at any time; it holds one
|
|
664
|
+
subdirectory per Node version, so it grows a little with each Node upgrade.
|
|
665
|
+
Node's own variables override it: `NODE_COMPILE_CACHE=<dir>` moves it there,
|
|
666
|
+
and `NODE_DISABLE_COMPILE_CACHE=1` turns it off. A cache that cannot be
|
|
667
|
+
written means no cache, never a different answer. Hooks and other processes the
|
|
668
|
+
CLI starts do not inherit it.
|
|
669
|
+
|
|
658
670
|
## What is not in it
|
|
659
671
|
|
|
660
672
|
- **Which capabilities a soul gets:** the soul's `capabilities:` plus the
|
package/docs/desktop-cli-api.md
CHANGED
|
@@ -3332,7 +3332,8 @@ its absence.
|
|
|
3332
3332
|
`lost` (the host went down, its tmux server died, or the harness was killed
|
|
3333
3333
|
by a signal: the sweep brings it back when it can vouch for the loss,
|
|
3334
3334
|
[Which losses come back](execution-targets.md#which-losses-come-back)), `stopped` (stopped with OATS:
|
|
3335
|
-
`oats instance stop`, Desktop's Stop
|
|
3335
|
+
`oats instance stop`, Desktop's Stop, or an `oats session restart` whose
|
|
3336
|
+
relaunch did not happen) or `exited` (the harness ended by
|
|
3336
3337
|
itself: `/exit`, its own error). Present only on a row that reads
|
|
3337
3338
|
`running: false` and records `launched: true`, a row at its fallback shell
|
|
3338
3339
|
(`runtimeState: "shell"`) included; absent while it runs or reads unknown
|
|
@@ -3621,6 +3622,12 @@ route target:
|
|
|
3621
3622
|
whose kernel predates the feature, and a saved route the host did not list
|
|
3622
3623
|
carry no key ([`sameWork`](#row-same-work)). `oats status --server <id>
|
|
3623
3624
|
--json` relays the host's answer verbatim, `sameWork` included.
|
|
3625
|
+
- **`sessionEnd`** (feature `session-resume`; relayed from 0.69.5) is on a row only
|
|
3626
|
+
when the host's row has the key, with the host's value: a host whose kernel
|
|
3627
|
+
predates the feature, a row the host reports without it (one that runs,
|
|
3628
|
+
for example), and a saved route the host did not list carry none. Its
|
|
3629
|
+
meaning and when the host sends it are the [local row's](#row-session-end).
|
|
3630
|
+
A value that is not `lost`, `stopped` or `exited` drops the key.
|
|
3624
3631
|
- **`addressable`** (0.31): `true` for every row the host reports. Routed
|
|
3625
3632
|
session and lifecycle commands reach it by `--home`, or by name when the
|
|
3626
3633
|
name is unique on the host ([addressing](servers.md#run-there); a shared
|
|
@@ -1185,6 +1185,16 @@ it ends, before it ends it, so a home it was retiring reads `stopped`, never
|
|
|
1185
1185
|
stop record itself cannot be written (a full disk) and the retire then fails
|
|
1186
1186
|
as well: that home reads `lost`, as it did before 0.69.2.
|
|
1187
1187
|
|
|
1188
|
+
`oats session restart` records the stop of the session it replaces the same
|
|
1189
|
+
way, before it asks the harness to end (#1601): a restart whose relaunch
|
|
1190
|
+
fails, or that dies between the stop and the relaunch, leaves a home that
|
|
1191
|
+
reads `stopped`, so no resume starts again the launch it was replacing. The
|
|
1192
|
+
relaunch records a new start, which that record does not name. A restart
|
|
1193
|
+
whose stop is refused (`E_SESSION_STOP_FAILED`, the harness still there after
|
|
1194
|
+
the grace) keeps its record: should that harness die later, the home reads
|
|
1195
|
+
`stopped`, not `lost`. A restart of a home that does not run stops nothing and
|
|
1196
|
+
records nothing, so it keeps its reading.
|
|
1197
|
+
|
|
1188
1198
|
#### How a session's end is read
|
|
1189
1199
|
|
|
1190
1200
|
A launched home that does not run reads one of three ends, `sessionEnd` on
|
|
@@ -1198,10 +1208,18 @@ for its current start (`startId` in `instance.json`):
|
|
|
1198
1208
|
| an exit marker that names it with a signal's status (128 and up: the harness alone was killed, an out-of-memory kill for example) | `lost` | when the sweep can vouch for the loss ([below](#which-losses-come-back)) |
|
|
1199
1209
|
| neither (the host went down, or the tmux server died under the live harness) | `lost` | when the sweep can vouch for the loss |
|
|
1200
1210
|
|
|
1211
|
+
In text, `oats status`, `oats status --server <id>` and `oats server roster`
|
|
1212
|
+
print a `lost` row as `LOST`, where a `stopped` or `exited` row, or one
|
|
1213
|
+
without `sessionEnd`, prints `idle`, with one line under it naming the way
|
|
1214
|
+
back: `oats session start --resume --home <home>`, or the next sweep (`oats
|
|
1215
|
+
session resume`, which OATS Desktop and `oats tui` run when they open) when
|
|
1216
|
+
it can vouch for the loss. Both act on this machine's homes only, so a row
|
|
1217
|
+
of another host names the host to run them on.
|
|
1218
|
+
|
|
1201
1219
|
The window a spawn or a start makes writes the exit marker,
|
|
1202
1220
|
`.oats-start-exited`, when the harness exits; `oats instance stop` writes its
|
|
1203
|
-
record, `.oats-stop.json`, and so
|
|
1204
|
-
(0.69.2). Both are kernel-private files of the home, not a
|
|
1221
|
+
record, `.oats-stop.json`, and so do a retire, before it ends the window
|
|
1222
|
+
(0.69.2), and `oats session restart`, before it stops the harness (#1601). Both are kernel-private files of the home, not a
|
|
1205
1223
|
contract: read `sessionEnd`. A shutdown kills the window's shell with the
|
|
1206
1224
|
harness, so a lost session leaves no marker. A home spawned before 0.69 and
|
|
1207
1225
|
never restarted since names no start: it reads `stopped` only after a stop,
|
|
@@ -1325,13 +1343,17 @@ resumes it. So:
|
|
|
1325
1343
|
- a loss first seen a day ago or more, or a session that died before any read
|
|
1326
1344
|
of OATS saw it run, stays down.
|
|
1327
1345
|
|
|
1328
|
-
|
|
1346
|
+
Three limits follow from reading only what OATS saw:
|
|
1329
1347
|
|
|
1330
1348
|
- **After upgrading to 0.69**, open OATS Desktop or `oats tui`, or run `oats
|
|
1331
1349
|
status`, once before you restart the computer, or nothing from before the
|
|
1332
1350
|
upgrade comes back.
|
|
1333
1351
|
- A whole boot with no OATS read leaves that boot unknown: what ran in it and
|
|
1334
1352
|
was lost there is not resumed.
|
|
1353
|
+
- Clause 4 does not reach across a reboot. On a computer where nothing read
|
|
1354
|
+
OATS for more than a day before a restart (every agent already down, no
|
|
1355
|
+
client open), the first sweep after the restart can bring back a session
|
|
1356
|
+
that was lost during that quiet spell.
|
|
1335
1357
|
|
|
1336
1358
|
Without a boot id (neither Linux nor macOS: both have one), clause 4 applies
|
|
1337
1359
|
to every loss and the 3-resumes-per-boot guard (below) is off.
|
package/docs/implementation.md
CHANGED
|
@@ -23,7 +23,10 @@ reference pages ([workspaces](workspaces.md), [souls and instances](souls-and-in
|
|
|
23
23
|
and may never add one: with a dependency it could no longer ship in this
|
|
24
24
|
tarball.
|
|
25
25
|
- **`@awebai/oats-pi`** (`packages/pi/`): a thin pi adapter that exposes an
|
|
26
|
-
instance's own resources. It registers no agent tools.
|
|
26
|
+
instance's own resources. It registers no agent tools. It ships no kernel:
|
|
27
|
+
`extension/core-loader.mjs` imports the kernel that launched the instance,
|
|
28
|
+
through the home's `oats` link, before any PATH or global lookup (the
|
|
29
|
+
order is in [its README](../packages/pi/README.md)).
|
|
27
30
|
- **`oats.framework`** (`oats-package/`): the `oats.core`, `oats.setup`,
|
|
28
31
|
`oats.support` and `oats.knowledge-theory` capabilities and the
|
|
29
32
|
`knowledge-theory-expert` soul,
|
|
@@ -71,7 +74,7 @@ and the rules its tests pin.
|
|
|
71
74
|
|
|
72
75
|
| path | contents |
|
|
73
76
|
|---|---|
|
|
74
|
-
| `bin/oats.mjs` | the CLI: argument parsing, JSON envelopes, the verbs |
|
|
77
|
+
| `bin/oats.mjs` | the CLI: argument parsing, JSON envelopes, the verbs. Its only static imports are Node built-ins and two dependency-free modules, `lib/compile-cache.mjs` and `lib/hot-reads.mjs`: it turns Node's compile cache on first, then imports the kernel and `yaml` with top-level `await import()`, in their order, because static imports are all parsed and linked before a module's body runs. A hot read (`version`, `session inspect`, `status`, `workspace status`, `instance events`, `instance waiting clear`, given only their own flags) imports only the leaves it uses, never `core.mjs` ([`hot-reads.mjs`](#kernel-modules)); every other command imports every module. A hot read takes its names from `lib/hot-reads.mjs`: a name newly used on a hot read's path must be listed there, under its import line, or its first use throws (a tripwire), and `test/cli-hot-reads.test.mjs` pins what each hot read must not load |
|
|
75
78
|
| `lib/` | the kernel (below) |
|
|
76
79
|
| `injects/` | the kernel and work-mode instruction blocks composed into every instance |
|
|
77
80
|
| `skills/` | bootstrap skills shipped with the kernel |
|
|
@@ -96,6 +99,9 @@ and the rules its tests pin.
|
|
|
96
99
|
| `capability-show.mjs` | `oats capabilities show`: one catalog row's inject and skill files, read at its commit. Its text rules (`decodeText`, `skillDocDescription`, the limits) are also the rules of `inspect --soul --skills` (`instance-inspect.mjs` `soulSkills`), which reads a soul copy's own skills locally, and of `--composed-skills` (`composedSkillsIn`), which adds the capability skills of the scratch composition |
|
|
97
100
|
| `materialize.mjs` | the shared home composer for spawn and module upgrade: `stageMaterialize` stages module copies and derived files, then a durable rename journal commits or rolls back a replacement in an existing home; `moduleSkills` is the one rule for which skills a module gives, read over the fetched tree, or over a remote listing for the spawn preview (`plannedModuleSkills`) |
|
|
98
101
|
| `instance-upgrade.mjs` | `planUpgrade` and `applyUpgrade`: verified package-module staging, provider adoption, idempotent forward completion, undo and retirement baseline refresh for a stopped local home, using the shared composer for derived home files |
|
|
102
|
+
| `compile-cache.mjs` | the CLI's Node compile cache (awebai/oats#1630): `$OATS_HOME_DIR/compile-cache`, made 0700, unless the caller's `NODE_COMPILE_CACHE` or `NODE_DISABLE_COMPILE_CACHE` decides; any failure is no cache and prints nothing, and `NODE_COMPILE_CACHE` is never put in the environment children inherit ([configuration](configuration.md#the-compile-cache)). Node built-ins only; kernel-private, not in `./core` |
|
|
103
|
+
| `hot-reads.mjs` | the CLI's hot reads (awebai/oats#1630): each one's form (its words and the flags it takes) and, for each import line of `bin/oats.mjs`, the leaves it loads in that line's place; a line it does not list loads nothing, and any other argv loads everything. A name a read does not list is a tripwire: destructuring it is free, and any use throws a `HotReadUnlisted` defect naming the read, the line and the name. `test/cli-hot-reads.test.mjs` runs each read with a load hook and pins what it must not load. Kernel-private, not in `./core` |
|
|
104
|
+
| `version.mjs`, `deployment-path.mjs`, `write-file-atomic.mjs`, `agents-root.mjs`, `soul-listing.mjs`, `instance-address.mjs`, `session-inspect.mjs`, `instance-listing.mjs`, `drift.mjs`, `package-catalog.mjs`, `member-clone.mjs`, `reserved-launch-env.mjs`, `automation-scope.mjs`, `automation-api.mjs`, `semver.mjs` | the leaves the hot reads load instead of the modules that re-export them (awebai/oats#1630): the version; the canonical deployment path; the atomic file write; the agents root; souls and instance homes; `resolveInstance`; `inspectInstanceSession`; `listInstances` and the status rows; soul and module drift; the official package catalog; discovery and member clones; the reserved launch environment; the automation scope; the automation API versions; `compareSemver`. Each name is still exported, under the same name, from the module it left (`core.mjs`, `packages.mjs`, `instance-lifecycle.mjs`, `materialize.mjs`, `instance-resolution.mjs`, `schedule.mjs`, `automations.mjs`, `servers.mjs`), so `./core` is unchanged (`test/core-exports.test.mjs`), and no leaf imports `core.mjs` or the module it left. Code a hot read reaches goes in a leaf, never in `core.mjs` |
|
|
99
105
|
| `upgrade-state.mjs` | upgrade receipt state and the partial-upgrade guard used before session start; receipts remain lifecycle state, and provider adoption stays in the module's upgrade hook |
|
|
100
106
|
| `core.mjs` | spawn, retire, sessions, hooks, launch recipes, instance metadata. A home's record (`instance.json`) is read with `readHomeRecord`, which never throws: a record, an absent one, or one that is there and cannot be read, with the reason. Code that walks other homes (the listing, a retire's lineage repair) uses it, so that one home's record decides only for that home; `identifiedHomeRecord` is the one refusal (`E_UNIDENTIFIED_INSTANCE_HOME`) a lifecycle verb makes when it has resolved its home: `resolveRetireHome`, `startInstanceSession`, and `resolveTarget` in `instance-lifecycle.mjs` for the stop and retire plans. A plan reads its own home's record with `targetRecord` (the same refusal) and any other home's with `otherRecord` (absent or unreadable: nobody's parent or child) |
|
|
101
107
|
| `instruction-composition.mjs` | the generated `AGENTS.md`; `renderInstructionParts` is the span-reporting renderer (`renderInstructionText` is its text) |
|
|
@@ -127,6 +133,7 @@ and the rules its tests pin.
|
|
|
127
133
|
| `login-environment.mjs` | the user's login environment a server OATS starts gets: the login shell's answer as one nonce-framed block on its stdout, bounded and accepted only whole ([execution targets](execution-targets.md#the-servers-start-environment)) |
|
|
128
134
|
| `capability-contract.mjs`, `provider-binding.mjs` | manifest validation (launch environment, hooks, `retirement`) as problems and warnings (`manifestContract`: an unknown, non-required hook event is a warning every reader reports), the hook environment rules, the readiness wire |
|
|
129
135
|
| `retire-output.mjs` | the lines `oats retire` prints for preserved work, one function for the local and the remote path |
|
|
136
|
+
| `status-words.mjs` | the word `oats status`, `oats status --server` and `oats server roster` print for an instance row (RUNNING, LOST, idle, unknown, RETIRING; the roster keeps its own suffixes) and the line under a LOST row that names the way back; rows in, strings out, the JSON untouched |
|
|
130
137
|
| `retire-state.mjs` | a status row's `retire` (feature `status-retire-state`): `readRetireState`, the one read of the value, which the local row (`core.mjs` `retireStateOf`, from the marker, its result and the home's claim) and the remote roster's relay (`servers.mjs` `rowRetire`) both go through. Pure; status only reads, so nothing here takes a claim, removes a file or signals a process |
|
|
131
138
|
| `retained-after-retire.mjs` | what retires left behind (recovery copies, retained worktrees) as `oats doctor` information lines: read-only, Git through `instance-git.mjs`'s helper-free reads |
|
|
132
139
|
| `read-ahead.mjs`, `read-ahead-worker.mjs` | read-ahead for the tree digests (`fingerprintTrees`): while a digest reads a tree on the calling thread, a planner thread walks it in the digest's order and a few reader threads read the next files into the page cache, within a window of bytes and files ahead of the digest. The digest still reads and hashes every byte itself, so no value or error depends on it; one that cannot start or falls behind costs speed only |
|
|
@@ -134,7 +141,7 @@ and the rules its tests pin.
|
|
|
134
141
|
| `session-input.mjs` | session inspection and input transport. `resolveAgentPane` is the one rule for which of a window's panes is the agent's (the `@oats-agent` mark, `AGENT_PANE_OPTION`, that the launches in `core.mjs` set); `harnessProcesses` (Stop) and the viewer use it too. `createSessionPaneInspector` resolves the agent's pane, then interprets it for both lifecycle inspection and status, sharing a lazy process scan across a status read; `core.mjs` batches pane reads per socket/session and applies its shared `harnessRunning` predicate |
|
|
135
142
|
| `servers.mjs` | routing commands to a registered server |
|
|
136
143
|
| `deployments.mjs` | this computer's deployments ([workspaces.md](workspaces.md#this-computers-deployments)): the per-user files `<OATS_HOME_DIR>/config/deployments.json` (the list, 0600 in a 0700 `config/`) and `config/deployments.lock` (`withDirLock`, waited for up to 3 s), the bounded no-follow read, the atomic write, the first-use `~/Agents` import (the real `$HOME`) and the five `E_DEPLOYMENTS_*` codes. `oats deployments`, onboard's `listed` and the auto-add write through it. `listResolved` is the auto-add: `bin/oats.mjs` sets it as the observer of `resolved-deployment.mjs` for the commands in its one table (`LISTS_ITS_DEPLOYMENT`), so it runs once per process on the deployment the command itself resolved. A listed deployment costs one bounded read (no lock, write, process or realpath), another spelling of it a realpath; a spelled root in a linked worktree or submodule (a `.git` file above it) is left to the commands that resolve its canonical root; a root under a temporary directory (`underTemporaryDirectory`, awebai/oats#1397) is never auto-added; only a path not listed is canonicalized and takes the lock, without waiting for it. It never throws or prints |
|
|
137
|
-
| `resolved-deployment.mjs` | the deployment a command resolved: `loadLocal` (`workspace.mjs`) reports the directory it found as spelled, `ensureRoot` (`
|
|
144
|
+
| `resolved-deployment.mjs` | the deployment a command resolved: `loadLocal` (`workspace.mjs`) reports the directory it found as spelled, `ensureRoot` (`agents-root.mjs`) the canonical one, and the observer the CLI set is called once, at exit, with the first canonical root (else the first spelled one), so an earlier spelling never stands for a root the command canonicalized. A no-op until the CLI sets one, so library callers and tests are unaffected. Dependency-free |
|
|
138
145
|
| `launch-prompt-evidence.mjs` | private bounded storage of exact unmatched, stable-screen completed or flag-ignored notice frames, original-home identity checks and receipt-last publication; no terminal operations or public raw text |
|
|
139
146
|
| `launch-prompt-completion.mjs` | the 21 question markers that block after the development-channel Enter; reporting only, never an input matcher |
|
|
140
147
|
| `launch-prompt-fixtures.mjs` | the development-channel tolerance list (`launch-prompt-fixtures/dev-channel-confirmation.json`): engagement from the argv, the enumerated normalization, equality matching, the `flag-ignored` notice block, the running-session banner hint, what differed, and the Claude version read from the executable's path |
|
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.
|
|
9
|
+
This is the operator guide for **oats.okf 5.6.0** (OATS **>=0.69.2**). 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 |
|
|
@@ -25,7 +25,7 @@ recovery details belong to the [oats-okf README](https://github.com/awebai/oats-
|
|
|
25
25
|
```yaml
|
|
26
26
|
# oats-workspace.yaml (excerpt)
|
|
27
27
|
packages:
|
|
28
|
-
oats.okf: v5.
|
|
28
|
+
oats.okf: v5.6.0
|
|
29
29
|
defaults:
|
|
30
30
|
knowledge: { oats.okf: { from: package } }
|
|
31
31
|
stores:
|
|
@@ -50,10 +50,11 @@ settings:
|
|
|
50
50
|
|
|
51
51
|
Upgrading from 4.x requires the ordered
|
|
52
52
|
[5.0 cutover](release-notes/v0.49.0.md#oatsokf-50-cutover--order-matters), not
|
|
53
|
-
just editing a version line.
|
|
54
|
-
|
|
53
|
+
just editing a version line. 5.6.0 requires OATS >=0.69.2: its
|
|
54
|
+
`knowledge-harvester` and `knowledge-maintainer` souls say `background: true`,
|
|
55
|
+
which an older kernel refuses. Upgrade OATS first, then the package.
|
|
55
56
|
|
|
56
|
-
**Upgrade:** pin `oats.okf: v5.
|
|
57
|
+
**Upgrade:** pin `oats.okf: v5.6.0` and run `oats sync`. Only new spawns get
|
|
57
58
|
the capability-owned harvest duty, skill and spawn-recorded policy. Existing
|
|
58
59
|
homes keep their copied provider even after a session restart; from 5.4.0, a
|
|
59
60
|
stopped 5.x home can move with `oats instance upgrade` (OATS 0.68.0 and
|
|
@@ -65,7 +66,9 @@ remain. From 5.2.x, 5.3.0 adds the long-lived-role checkpoints and the
|
|
|
65
66
|
checkpoint line in `log.md`, drops the available-memory gate, and has the
|
|
66
67
|
proposer name each harvester (`--name`, below). 5.5.0 adds the incarnation to
|
|
67
68
|
the proposal's `Source:` line (below): a harvester on 5.4.0 or older refuses
|
|
68
|
-
that line, so run `oats sync` to 5.5.0 before instances on 5.5.0
|
|
69
|
+
that line, so run `oats sync` to 5.5.0 or later before instances on 5.5.0
|
|
70
|
+
propose. 5.6.0 lists new harvesters and knowledge maintainers under the
|
|
71
|
+
clients' Background section; existing ones do not move.
|
|
69
72
|
|
|
70
73
|
### Bindings document
|
|
71
74
|
|
package/docs/official-catalog.md
CHANGED
|
@@ -9,12 +9,12 @@ 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.16.
|
|
13
|
-
| `oats.okf` | `v5.
|
|
14
|
-
| `oats.aweb` | `v1.32.
|
|
12
|
+
| `oats.framework` | `oats-framework/v1.16.3` (this repository) | `oats.core`, `oats.setup`, `oats.support`, `oats.knowledge-theory` | `knowledge-theory-expert` |
|
|
13
|
+
| `oats.okf` | `v5.6.0` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
|
|
14
|
+
| `oats.aweb` | `v1.32.1` | `oats.aweb` (messaging), `oats.aweb-tasks` (tasks) | |
|
|
15
15
|
| `oats.engineering` | `v1.17.2` | `oats.engineering-expert`, `oats.developer`, `oats.code-review`, `oats.maintainer` | `code-reviewer` |
|
|
16
16
|
| `oats.authoring` | `v1.0.3` | `oats.authoring` | |
|
|
17
|
-
| `oats.cloning` | `v1.0
|
|
17
|
+
| `oats.cloning` | `v1.1.0` | `oats.cloning` | `cloner` |
|
|
18
18
|
| `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
|
|
19
19
|
| `oats.linear` | `v1.0.1` | `oats.linear` (tasks) | |
|
|
20
20
|
| `oats.apps` | `v1.0.0` | `oats.folio`, `oats.library` | |
|
|
@@ -30,7 +30,7 @@ no lock and adds nothing to an existing workspace.
|
|
|
30
30
|
## Find and use packages
|
|
31
31
|
|
|
32
32
|
- A workspace pins an official package by **bare version** in its
|
|
33
|
-
`packages:` map (`oats.okf: v5.
|
|
33
|
+
`packages:` map (`oats.okf: v5.6.0`); `oats sync` resolves it through the
|
|
34
34
|
catalog to an exact commit, fetches it, verifies its integrity and locks it.
|
|
35
35
|
A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
|
|
36
36
|
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.
|
|
47
|
+
oats.okf: v5.6.0 # 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.
|
|
51
|
+
- **Bare version** (`v5.6.0`, `5.6.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.
|
|
54
|
+
convention (`v5.6.0` or `oats-framework/v1.16.3`) 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.16.
|
|
78
|
-
oats.okf: v5.
|
|
79
|
-
oats.aweb: v1.32.
|
|
77
|
+
oats.framework: v1.16.3
|
|
78
|
+
oats.okf: v5.6.0
|
|
79
|
+
oats.aweb: v1.32.1
|
|
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.
|
|
108
|
+
packages acme.tools 0.4.0 ✓ (@ 47f4b816) oats.okf 5.6.0 ✓ (@ ec169fd6)
|
|
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.32.
|
|
137
|
+
oats package add oats.aweb v1.32.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
|
```
|
|
@@ -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.
|
|
164
|
-
"commit": "
|
|
163
|
+
"version": "5.6.0",
|
|
164
|
+
"commit": "ec169fd6ab20abea1eea26fe8eff3a9b547e7210",
|
|
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.
|
|
356
|
-
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.16.
|
|
355
|
+
"oats.okf": { "url": "https://github.com/awebai/oats-okf.git", "ref": "v5.6.0", "path": "oats-package" },
|
|
356
|
+
"oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.16.3", "path": "oats-package" }
|
|
357
357
|
}
|
|
358
358
|
}
|
|
359
359
|
```
|
|
360
360
|
|
|
361
|
-
`ref` carries the tag convention: a workspace's `oats.framework: v1.16.
|
|
362
|
-
resolves to tag `oats-framework/v1.16.
|
|
361
|
+
`ref` carries the tag convention: a workspace's `oats.framework: v1.16.3`
|
|
362
|
+
resolves to tag `oats-framework/v1.16.3`. Resolving through the catalog never
|
|
363
363
|
advances a lock by itself: `oats sync` does, and says so.
|