@awebai/oats 0.69.21 → 0.69.23
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 +131 -23
- package/docs/capabilities.md +12 -2
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/container.md +290 -5
- package/docs/design/2026-11-18-kernel-test-ownership.md +82 -0
- package/docs/design/2026-11-19-aweb-suite-retirement.md +123 -0
- package/docs/design/2026-11-19-sandboxes.md +878 -0
- package/docs/design/README.md +3 -0
- package/docs/desktop-cli-api.md +416 -72
- package/docs/desktop.md +377 -148
- package/docs/implementation.md +15 -2
- package/docs/integrations.md +3 -3
- package/docs/knowledge-capability-authoring.md +10 -7
- package/docs/knowledge-reference/acceptance.md +21 -19
- package/docs/knowledge-reference/adoption.md +18 -4
- package/docs/knowledge-reference/model.md +11 -9
- package/docs/knowledge-reference/package-craft.md +2 -2
- package/docs/knowledge-reference/proposal.md +117 -0
- package/docs/knowledge-reference/provider-mapping.md +10 -10
- package/docs/knowledge-reference/reader-capture.md +26 -22
- package/docs/knowledge-theory.md +1 -1
- package/docs/knowledge.md +5 -5
- package/docs/official-catalog.md +47 -4
- package/docs/packages.md +13 -13
- package/docs/release-lane.md +8 -6
- package/docs/release-notes/v0.69.22.md +221 -0
- package/docs/release-notes/v0.69.23.md +231 -0
- package/docs/servers.md +10 -6
- package/docs/souls-and-instances.md +51 -22
- package/docs/tui.md +48 -7
- package/docs/upgrading.md +17 -5
- package/docs/workspaces.md +2 -2
- package/lib/argv.mjs +6 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/command-flags.mjs +39 -2
- package/lib/core.mjs +25 -14
- package/lib/instance-board.mjs +337 -0
- package/lib/instance-events.mjs +48 -10
- package/lib/instance-lifecycle.mjs +19 -15
- package/lib/instance-listing.mjs +18 -10
- package/lib/instance-related-work.mjs +143 -0
- package/lib/kernel-features.mjs +4 -1
- package/lib/servers.mjs +123 -13
- package/package-catalog.json +3 -3
- package/package.json +1 -1
- package/packages/client/above-tested.mjs +3 -2
- package/packages/client/capability-list.mjs +69 -0
- package/packages/client/capability-origin.mjs +54 -0
- package/packages/client/cli-adapter.mjs +9 -1
- package/packages/client/deployment-data.mjs +7 -2
- package/packages/client/deployment-panel.mjs +4 -1
- package/packages/client/home-board.mjs +50 -0
- package/packages/client/instance-pin.mjs +28 -0
- package/packages/client/instance-record-outcome.mjs +31 -0
- package/packages/client/instance-tree.mjs +96 -24
- package/packages/client/keymap.mjs +16 -3
- package/packages/client/mail-contract.mjs +130 -0
- package/packages/client/panel-views.mjs +7 -7
- package/packages/client/related-work.mjs +84 -0
- package/packages/client/remote-roster.mjs +11 -3
- package/packages/client/roster-sections.mjs +10 -7
- package/packages/client/soul-role.mjs +44 -0
- package/packages/client/waiting-on-you.mjs +10 -0
- package/packages/client/workspace-cli.mjs +13 -2
- package/packages/tui/lib/actions.mjs +11 -4
- package/packages/tui/lib/client.mjs +3 -1
- package/packages/tui/lib/main.mjs +16 -2
- package/packages/tui/lib/model.mjs +48 -5
- package/packages/tui/lib/store.mjs +28 -2
- package/skills/oats-getting-started/SKILL.md +97 -24
- package/docs/knowledge-reference/harvester.md +0 -109
- package/lib/instance-same-work.mjs +0 -67
- package/packages/client/same-work.mjs +0 -49
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
/** A soul's role, and the order souls are listed in, for every client (the Desktop's Souls grid and table, and
|
|
2
|
+
* the Terminal UI later): maintainers, experts, developers, operations, then the rest, each alphabetical. (Not the
|
|
3
|
+
* row's `soulKind`, which is where the soul comes from: member, package or external.)
|
|
4
|
+
*
|
|
5
|
+
* The kernel reports no role for a soul (oats-project/oats#1980 asks for one), so the role is read from the soul's
|
|
6
|
+
* name, one rule:
|
|
7
|
+
* 1. operations: any word of the name is setup, operator, operators, admin, ops or operations
|
|
8
|
+
* (`acme-oats-setup-expert`, `ops-admin`): a setup soul is operations even when it ends in -expert;
|
|
9
|
+
* 2. else the last word: maintainer → maintainer, expert → expert, developer → developer;
|
|
10
|
+
* 3. else other.
|
|
11
|
+
* A word is a run of the name between `-`, `_`, `.` and `/`, case aside, so a package soul's qualified name
|
|
12
|
+
* (`oats.engineering/code-reviewer`) reads the same as its bare one. The description is not read: a sentence
|
|
13
|
+
* that says a soul "operates" something would misfile it, and the name is what the soul's author chose.
|
|
14
|
+
*
|
|
15
|
+
* A kernel `role` fact on the soul row would replace this rule (#1980): then `soulRole` reads it, and every client
|
|
16
|
+
* keeps calling the same two functions.
|
|
17
|
+
*
|
|
18
|
+
* soulRole(row) -> 'maintainer' | 'expert' | 'developer' | 'operations' | 'other'
|
|
19
|
+
* SOUL_ROLES the roles, in list order
|
|
20
|
+
* SOUL_ROLE_WORDS a role in words, singular ("developer"); the Desktop's Souls call it the soul's kind
|
|
21
|
+
* compareSoulsByRole(a, b) list order: role, then name; for Array.prototype.sort
|
|
22
|
+
*
|
|
23
|
+
* No state, no DOM. */
|
|
24
|
+
|
|
25
|
+
export const SOUL_ROLES = Object.freeze(['maintainer', 'expert', 'developer', 'operations', 'other']);
|
|
26
|
+
export const SOUL_ROLE_WORDS = Object.freeze({ maintainer: 'maintainer', expert: 'expert', developer: 'developer', operations: 'operations', other: 'other' });
|
|
27
|
+
const OPERATIONS = new Set(['setup', 'operator', 'operators', 'admin', 'ops', 'operations']);
|
|
28
|
+
const LAST = Object.freeze({ maintainer: 'maintainer', expert: 'expert', developer: 'developer' });
|
|
29
|
+
|
|
30
|
+
const nameOf = row => typeof row === 'string' ? row : typeof row?.name === 'string' ? row.name : '';
|
|
31
|
+
const words = name => name.toLowerCase().split(/[-_./]+/).filter(Boolean);
|
|
32
|
+
|
|
33
|
+
/** The soul's role, from its name (a row with a `name`, or the name itself). */
|
|
34
|
+
export function soulRole(row) {
|
|
35
|
+
const parts = words(nameOf(row));
|
|
36
|
+
if (parts.some(part => OPERATIONS.has(part))) return 'operations';
|
|
37
|
+
const last = parts.at(-1);
|
|
38
|
+
return last !== undefined && Object.hasOwn(LAST, last) ? LAST[last] : 'other';
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** List order inside a group: the role's place in SOUL_ROLES, then the name. */
|
|
42
|
+
export function compareSoulsByRole(a, b) {
|
|
43
|
+
return SOUL_ROLES.indexOf(soulRole(a)) - SOUL_ROLES.indexOf(soulRole(b)) || nameOf(a).localeCompare(nameOf(b));
|
|
44
|
+
}
|
|
@@ -43,6 +43,16 @@ export function waitingClaim(row, { stale = false } = {}) {
|
|
|
43
43
|
return waitingOnYouData(row.waitingOnYou);
|
|
44
44
|
}
|
|
45
45
|
|
|
46
|
+
/** The rows that need you, newest claim first (the Desktop's palette and Home, the TUI's list later: one order for
|
|
47
|
+
* both clients, the Desktop UI rework, slice 4): each row's claim through the one gate (waitingClaim; `stale(row)`
|
|
48
|
+
* says a row is held stale), as `{ row, claim }`. Equal times keep the rows' own order. */
|
|
49
|
+
export function needsYouRows(rows, { stale = () => false } = {}) {
|
|
50
|
+
return (Array.isArray(rows) ? rows : []).map((row, at) => ({ row, at, claim: waitingClaim(row, { stale: stale(row) }) }))
|
|
51
|
+
.filter(({ claim }) => claim)
|
|
52
|
+
.sort((a, b) => Date.parse(b.claim.since) - Date.parse(a.claim.since) || a.at - b.at)
|
|
53
|
+
.map(({ row, claim }) => ({ row, claim }));
|
|
54
|
+
}
|
|
55
|
+
|
|
46
56
|
const LABELS = Object.freeze({ permission: 'Waiting for a tool approval', question: 'Asked you a question', attention: 'Asked for your attention' });
|
|
47
57
|
/** The reason in words. The raw reason is never rendered: an unknown one reads "Needs input". */
|
|
48
58
|
export const waitingLabel = claim => Object.hasOwn(LABELS, claim?.reason ?? '') ? LABELS[claim.reason] : 'Needs input';
|
|
@@ -10,7 +10,8 @@
|
|
|
10
10
|
* sync → `oats sync --dir D --json` (syncApi 1)
|
|
11
11
|
* onboard → `oats onboard DIR --workspace REF --json` (onboardApi 2)
|
|
12
12
|
* There is no package approval (packages-no-approval): declaring a package
|
|
13
|
-
* is the trust decision, so every success exits 0
|
|
13
|
+
* is the trust decision, so every success exits 0, but one: a sync whose
|
|
14
|
+
* sandbox failed exits 1 with its report (sandboxFailureReport). `--max-age` (feature
|
|
14
15
|
* observe-max-age) belongs to the three reads only and reaches argv only when
|
|
15
16
|
* the probe declares the feature; cliWorkspace drops it otherwise. */
|
|
16
17
|
import { execFile } from 'node:child_process';
|
|
@@ -97,6 +98,13 @@ export function workspaceArgv(options) {
|
|
|
97
98
|
return { argv: ['sync', '--dir', options.context, '--json'], cwd: options.context, timeout: WORKSPACE_WRITE_TIMEOUT };
|
|
98
99
|
}
|
|
99
100
|
|
|
101
|
+
/** Whether a sync's exit is its one non-zero success: exit 1 exactly, an `ok: true` answer, and a
|
|
102
|
+
* `result.sandboxes` entry whose `problems` is not empty (a failed sandbox; the lock is written). */
|
|
103
|
+
function sandboxFailureReport(options, error, document) {
|
|
104
|
+
if (options.action !== 'sync' || error?.code !== 1 || error.killed || error.signal) return false;
|
|
105
|
+
const sandboxes = document?.result?.sandboxes;
|
|
106
|
+
return Array.isArray(sandboxes) && sandboxes.some(entry => record(entry) && Array.isArray(entry.problems) && entry.problems.length > 0);
|
|
107
|
+
}
|
|
100
108
|
/** `io.exec` is a client's own `execFile` (the rule is at cli-adapter.mjs `runJson`). */
|
|
101
109
|
export function cliWorkspace(cli, options, terms, io = {}) {
|
|
102
110
|
requireTerms(terms, 'cliWorkspace');
|
|
@@ -138,7 +146,10 @@ export function cliWorkspace(cli, options, terms, io = {}) {
|
|
|
138
146
|
if (options.action === 'sync' && typeof reason.details?.why === 'string' && WHY_RE.test(reason.details.why)) out.why = reason.details.why;
|
|
139
147
|
return done({ ok: false, reason: out });
|
|
140
148
|
}
|
|
141
|
-
|
|
149
|
+
// Success is exit 0, with one exception: a sync whose sandbox failed (feature sandboxes) wrote the lock
|
|
150
|
+
// and answers its report with `ok: true` and exit 1, the failure in a sandbox entry's `problems`
|
|
151
|
+
// (docs/desktop-cli-api.md, `oats sync`). That one answer is a report; any other exit is a failure.
|
|
152
|
+
if (error && !sandboxFailureReport(options, error, document)) return fail('E_CLI_FAILED');
|
|
142
153
|
done({ ok: true, document });
|
|
143
154
|
});
|
|
144
155
|
} catch { fail('E_CLI_FAILED'); }
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
// The keys the TUI shares with the Desktop are not written here: an action with no `keys` of its own
|
|
9
9
|
// takes its default keys from the shared keymap (packages/client/keymap.mjs PLAIN_KEYS), and the
|
|
10
10
|
// leader's table is the shared one (LEADER, below). What only the TUI has (q, Ctrl+C, Ctrl+Z, Ctrl+L,
|
|
11
|
-
// Ctrl+K, Tab, Esc, Delete, C, i) keeps its keys here. packages/tui/test/keymap.test.mjs pins both.
|
|
11
|
+
// Ctrl+K, Tab, Esc, Delete, C, i, p) keeps its keys here. packages/tui/test/keymap.test.mjs pins both.
|
|
12
12
|
import { CHORDS, DEFAULT_CHORD_FAMILY, LEADER_TABLE, PALETTE_KEYS, chordKeyOf, plainKeys } from "./client.mjs";
|
|
13
13
|
// An action's words, for the help (views/help.mjs): a view takes the shared home's keymap through this module only.
|
|
14
14
|
export { doesLabel } from "./client.mjs";
|
|
@@ -75,6 +75,12 @@ export const ACTIONS = Object.freeze([
|
|
|
75
75
|
{ id: "spawn-another", label: "spawn another", views: [["instances", "spawn another agent of the selected agent's soul: the preview, and Enter spawns it"], ["souls", "the same as n"]] },
|
|
76
76
|
// Offered only while a spawn's outcome is not known: it asks the kernel once, never spawns again.
|
|
77
77
|
{ id: "spawn-check", keys: ["C"], label: "check spawn", views: [["instances", "check the result of a spawn whose outcome is not known, while one is"]] },
|
|
78
|
+
// Pinned instances (feature instance-pin; docs/tui.md, "Pinning"): at once, no confirmation (a pin only orders the
|
|
79
|
+
// list, and the same key undoes it). `p` is a new default key: a tui.json that gives it to another action is
|
|
80
|
+
// refused at the start with the line that says so (config.mjs), until that action moves or pin gets another key.
|
|
81
|
+
// Lower-case, unlike the four acts above: it opens no confirmation and changes nothing but the order. Its help
|
|
82
|
+
// line fits one row of the help: the shared pin and the feature's line are in docs/tui.md and on the status line.
|
|
83
|
+
{ id: "pin", keys: ["p"], label: "pin", views: [["instances", "pin the selected agent at the top of its list or unpin it, as oats instance pin <name> on|off; needs instance-pin"]] },
|
|
78
84
|
{ id: "help", label: "help" },
|
|
79
85
|
{ id: "close", keys: ["escape"], label: "close" },
|
|
80
86
|
{ id: "quit", keys: ["q", "ctrl+c"], label: "quit" },
|
|
@@ -93,9 +99,10 @@ export const ACTIONS = Object.freeze([
|
|
|
93
99
|
* and from any other focus it only cancels the leader (lib/store.mjs `twice`). */
|
|
94
100
|
export const LEADER = LEADER_TABLE;
|
|
95
101
|
/** What the leader does that no action of ACTIONS does (lib/store.mjs `led`): `workspace-previous`
|
|
96
|
-
* and `workspace-next` (the workspace before or after the open one in the list of workspaces)
|
|
97
|
-
* `list` (the list's focus, which Esc gives)
|
|
98
|
-
|
|
102
|
+
* and `workspace-next` (the workspace before or after the open one in the list of workspaces),
|
|
103
|
+
* `list` (the list's focus, which Esc gives), and `sidebar` (the shared table's `b`, the Desktop's
|
|
104
|
+
* sidebar: here the list, hidden by the shown terminal taking the whole screen, or given back). */
|
|
105
|
+
export const LEADER_OWN = Object.freeze(["workspace-previous", "workspace-next", "list", "sidebar"]);
|
|
99
106
|
/** What a chord does that neither the leader's table nor an action does (lib/store.mjs `led`):
|
|
100
107
|
* `tab-1` to `tab-8`, the focused group's Nth tab shown, and `tab-9`, its last (as the Desktop and
|
|
101
108
|
* the browsers do). No key after the leader does them: LEADER has no row for them. */
|
|
@@ -12,6 +12,8 @@ export { cliDeploymentRead } from "../../client/deployment-read-cli.mjs";
|
|
|
12
12
|
export { cliDeploymentList } from "../../client/deployment-list-cli.mjs";
|
|
13
13
|
export { deploymentsListSupported } from "../../client/deployment-list.mjs";
|
|
14
14
|
export { cliRemoteRoster } from "../../client/cli-adapter.mjs";
|
|
15
|
+
// Pinned instances (feature instance-pin): the pin key runs the kernel's verb, read by the shared home.
|
|
16
|
+
export { pinInstance } from "../../client/instance-pin.mjs";
|
|
15
17
|
export { createDeploymentObserver, mapBounded, MAX_DEPLOYMENT_OBSERVATIONS } from "../../client/deployment-observer.mjs";
|
|
16
18
|
export { createWarmReader } from "../../client/warm-reader.mjs";
|
|
17
19
|
export { createRefreshLoop } from "../../client/refresh-loop.mjs";
|
|
@@ -23,7 +25,7 @@ export { remoteRosterState } from "../../client/remote-roster.mjs";
|
|
|
23
25
|
export { observeIdentities, identityMemory } from "../../client/remote-identity-memory.mjs";
|
|
24
26
|
export { workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION } from "../../client/workspace-choices.mjs";
|
|
25
27
|
export { shortPath, deploymentLabel, machineLabels } from "../../client/deployment-label.mjs";
|
|
26
|
-
export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome, instanceSiblings, backgroundPlacement, BACKGROUND_FEATURE } from "../../client/instance-tree.mjs";
|
|
28
|
+
export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome, instanceSiblings, backgroundPlacement, BACKGROUND_FEATURE, PIN_FEATURE } from "../../client/instance-tree.mjs";
|
|
27
29
|
export { rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment, rosterSectionKey, sidebarSections } from "../../client/roster-sections.mjs";
|
|
28
30
|
export { runtimeState, runtimeCounts, originLead, siblingText, instanceColor } from "../../client/instance-presentation.mjs";
|
|
29
31
|
export { instanceDisplayName } from "../../client/instance-display-name.mjs";
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
import { homedir } from "node:os";
|
|
13
13
|
import { resolve } from "node:path";
|
|
14
14
|
import { bindings } from "./actions.mjs";
|
|
15
|
-
import { TERMS, capabilityCatalogKey, cliDeploymentList, deploymentsListSupported, createCapabilityCatalog, createLifecycleBoundary, createLifecycleConfirmation, createRetiresInFlight, createSoulCatalog, createSpawnApplyBoundary, createSpawnPreview, createSpawnTransaction, createResumeTrigger, displayLine, heldHome, pendingEntry, prepareRemoteTerm, runResumeSweep, sessionAttachArgv, soulCatalogKey, startInstance } from "./client.mjs";
|
|
15
|
+
import { TERMS, capabilityCatalogKey, cliDeploymentList, deploymentsListSupported, createCapabilityCatalog, createLifecycleBoundary, createLifecycleConfirmation, createRetiresInFlight, createSoulCatalog, createSpawnApplyBoundary, createSpawnPreview, createSpawnTransaction, createResumeTrigger, displayLine, heldHome, pendingEntry, prepareRemoteTerm, runResumeSweep, sessionAttachArgv, soulCatalogKey, startInstance, pinInstance } from "./client.mjs";
|
|
16
16
|
import { loadConfig, loadKeys } from "./config.mjs";
|
|
17
17
|
import { ACT_WORDS, LIST_WORDS, actContext, actCwd, listRowsOf, localDeployments, model, outcomeOf, reachedMachines, resumeObservation, roster, spawnContext } from "./model.mjs";
|
|
18
18
|
import { createPanel, sweep } from "./panel.mjs";
|
|
@@ -100,7 +100,7 @@ function errorLines(error) {
|
|
|
100
100
|
* chord family (lib/config.mjs), replaceable so no test reads a user's file. `createResumeTrigger`
|
|
101
101
|
* is the shared trigger of the kernel's machine sweep (packages/client session-resume-trigger.mjs). */
|
|
102
102
|
const EFFECTS = Object.freeze({ loadConfig, loadKeys, findDeployment, probeKernel, createReader, createIdentityReads, deploymentList: cliDeploymentList, startExec, admitDeployment, prepareRemoteTerm, createPanel, sweep,
|
|
103
|
-
runDir: CHANGE_FILES.dir, removeDir: CHANGE_FILES.remove, realpath, tellable, startInstance, createLifecycleConfirmation, createLifecycleBoundary, createSoulCatalog,
|
|
103
|
+
runDir: CHANGE_FILES.dir, removeDir: CHANGE_FILES.remove, realpath, tellable, startInstance, pinInstance, createLifecycleConfirmation, createLifecycleBoundary, createSoulCatalog,
|
|
104
104
|
createCapabilityCatalog, createSpawnPreview, createSpawnApplyBoundary, createSpawnTransaction, createResumeTrigger });
|
|
105
105
|
|
|
106
106
|
/** The timers a run lends the shared spawn: the apply's deadline and its grace (the boundary's
|
|
@@ -487,6 +487,7 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
|
|
|
487
487
|
if (effect.act) openConfirmation(effect.act);
|
|
488
488
|
if (effect.call) callConfirmation(effect.call);
|
|
489
489
|
if (effect.start) startAct(effect.start);
|
|
490
|
+
if (effect.pin) pinAct(effect.pin);
|
|
490
491
|
if (effect.refresh) refresh(effect.refresh);
|
|
491
492
|
if (effect.souls === "settle" && state.open !== null) settleSouls(state.open);
|
|
492
493
|
if (effect.souls === "reread" && state.open !== null) rereadSouls(state.open);
|
|
@@ -601,6 +602,19 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
|
|
|
601
602
|
.then(() => effects.startInstance(probe.cli, row, {}, { restart: verb === "restart", deployments: localDeployments(state, clock()), realpath: effects.realpath, localCwd: actCwd(state), exec, terms: TERMS, group: contextOf(row?.deployment?.id).workspace?.group }))
|
|
602
603
|
.then((answer) => heard({ acted: { n, answer } }), () => heard({ acted: { n, answer: null } }));
|
|
603
604
|
}
|
|
605
|
+
/** Pin or unpin the row the store decided on (feature instance-pin; lib/model.mjs pinDecision): the kernel's verb,
|
|
606
|
+
* through the shared pinInstance, on this machine with `--dir` its deployment, on another routed with `--server`,
|
|
607
|
+
* as a stop is. It is a change (reader.changeExec): never ended by the TUI, and named on the way out while it
|
|
608
|
+
* runs. Its answer goes to the store as `{ pinned }`, which reads the rows again. */
|
|
609
|
+
function pinAct({ id, row, pinned }) {
|
|
610
|
+
const name = row.instance, workspace = contextOf(row.deployment?.id).workspace;
|
|
611
|
+
const remote = !!(workspace?.remote || workspace?.server);
|
|
612
|
+
const args = { instance: name, home: row.home, pinned, ...(remote ? { server: workspace?.server } : { context: workspace?.scope }) };
|
|
613
|
+
const exec = (bin, argv, options, callback) => reader.changeExec(bin, argv, { ...options, label: { verb: "pin", name } }, callback);
|
|
614
|
+
Promise.resolve()
|
|
615
|
+
.then(() => effects.pinInstance(probe.cli.bin, args, { exec, ...(remote ? { cwd: actCwd(state) } : {}) }))
|
|
616
|
+
.then((answer) => heard({ pinned: { id, name, pinned, answer } }), () => heard({ pinned: { id, name, pinned, answer: null } }));
|
|
617
|
+
}
|
|
604
618
|
|
|
605
619
|
/** Open the agent the store decided on (lib/model.mjs openDecision). On this machine the viewer
|
|
606
620
|
* starts in the panel at once. On another, the shared preflight runs first over the reader's
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
// in. What it adds is the TUI's: the window, the clock times, and which fact stands on which line.
|
|
8
8
|
import {
|
|
9
9
|
TERMS, panelData, localDeploymentIds, displayLine, DETAIL_WITHHELD, originLead, instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree,
|
|
10
|
-
hasInstanceChildren, heldHome, instanceSiblings, siblingText, rosterSections, rosterSectionKey, sidebarSections, backgroundPlacement, BACKGROUND_FEATURE, deploymentState, rowStale, primaryDeployment, isMultiDeployment, runtimeState, runtimeCounts, instanceColor, instanceDisplayName,
|
|
10
|
+
hasInstanceChildren, heldHome, instanceSiblings, siblingText, rosterSections, rosterSectionKey, sidebarSections, backgroundPlacement, BACKGROUND_FEATURE, PIN_FEATURE, deploymentState, rowStale, primaryDeployment, isMultiDeployment, runtimeState, runtimeCounts, instanceColor, instanceDisplayName,
|
|
11
11
|
waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText, instanceActs, rowReason,
|
|
12
12
|
identityMemory, viewModel, listedViews, workspaceChoices, workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION, shortPath, machineLabels,
|
|
13
13
|
openAct, deployments as heldDeployments, localScrollKeys, hostScrollKeys, attachExit, preflightFailure, kernelLines,
|
|
@@ -149,6 +149,8 @@ export const BACKGROUND_ID = "\u0000background";
|
|
|
149
149
|
* and kept for the run per workspace as `collapsed` is (by `state.open`): `state.background` holds the
|
|
150
150
|
* ones open. */
|
|
151
151
|
export const backgroundOpen = (state) => state.background.has(state.open);
|
|
152
|
+
/** Whether this run's kernel lists the pin's feature (instance-pin): a row's `pinned` orders the list only then. */
|
|
153
|
+
export const pinsListed = (state) => Array.isArray(state.cli?.features) && state.cli.features.includes(PIN_FEATURE);
|
|
152
154
|
|
|
153
155
|
/** The key prefix of each run of instances related to no other, as the shared grouping names it
|
|
154
156
|
* (`independent:<id>`). Read by key, not by label: a cluster whose root is named `independent` has that
|
|
@@ -172,7 +174,10 @@ function build(state, at) {
|
|
|
172
174
|
// `ordered`: every row in the shared order of the whole roster, whatever is filtered, folded or in the
|
|
173
175
|
// Background section (the lists of a soul's instances read it).
|
|
174
176
|
const ordered = [];
|
|
175
|
-
|
|
177
|
+
// Pinned first (feature instance-pin), as in the Desktop: only when this run's kernel lists the feature; without
|
|
178
|
+
// it a row's `pinned` is ignored and the order is the roster's own.
|
|
179
|
+
const pins = pinsListed(state);
|
|
180
|
+
for (const part of rosterSections(instances, instances, deployments, TERMS, { pins })) for (const group of part.groups) for (const cluster of group.clusters) ordered.push(...cluster.instances);
|
|
176
181
|
// The rows the Background section holds (#1579), the shared placement's: only when this run's kernel
|
|
177
182
|
// lists the feature; without it a row's `background` is ignored and nothing below changes.
|
|
178
183
|
const placement = backgroundPlacement(instances, Array.isArray(state.cli?.features) && state.cli.features.includes(BACKGROUND_FEATURE));
|
|
@@ -186,14 +191,14 @@ function build(state, at) {
|
|
|
186
191
|
// left out makes an ambiguous name unique. The key without a placement is the deployment's alone.
|
|
187
192
|
const deploymentOf = rosterSectionKey(deployments), bySection = new Map();
|
|
188
193
|
for (const row of instances) { const key = deploymentOf(row); if (!bySection.has(key)) bySection.set(key, []); bySection.get(key).push(row); }
|
|
189
|
-
const siblings = new Map([...bySection.values()].flatMap((own) => [...instanceSiblings(own)]));
|
|
194
|
+
const siblings = new Map([...bySection.values()].flatMap((own) => [...instanceSiblings(own, { pins })]));
|
|
190
195
|
const matched = soul !== null ? filterInstanceTree(instances, soul.name, (row) => soul.names.includes(row.agent)) : filterInstanceTree(instances, query);
|
|
191
196
|
const visible = matched.filter((i) => instanceVisibleInTree(i, instances, state.collapsed, state.open, filtering, { section }));
|
|
192
197
|
const stale = (row) => rowStale(row, deployments);
|
|
193
198
|
// The main tree's sections, and the Background section after them, each a tree of its own (the shared
|
|
194
199
|
// sidebarSections). A filter draws the section open, so its matches show, and changes nothing stored;
|
|
195
200
|
// the heading counts the rows the filter leaves in it.
|
|
196
|
-
const { main: sections, background } = sidebarSections(instances, visible, deployments, TERMS, { placement, open: backgroundOpen(state) || filtering, listed: matched, stale });
|
|
201
|
+
const { main: sections, background } = sidebarSections(instances, visible, deployments, TERMS, { placement, open: backgroundOpen(state) || filtering, listed: matched, stale, pins });
|
|
197
202
|
// How many instances each collapse folds away under its row: every descendant of the row in its
|
|
198
203
|
// own section, as the shared walk finds them when it is asked with that collapse alone (so a
|
|
199
204
|
// fold further down hides none of them from the count). A filter folds nothing away.
|
|
@@ -878,7 +883,7 @@ export function paletteItems(state, at = new Date(0).toISOString()) {
|
|
|
878
883
|
sibling: siblingText(r.siblings.get(instanceId(row))), text: `${row.instance} ${machine ?? ""}`,
|
|
879
884
|
};
|
|
880
885
|
};
|
|
881
|
-
for (const section of rosterSections(r.instances, openable, r.deployments, TERMS, { lastFocus })) for (const group of section.groups) {
|
|
886
|
+
for (const section of rosterSections(r.instances, openable, r.deployments, TERMS, { lastFocus, pins: pinsListed(state) })) for (const group of section.groups) {
|
|
882
887
|
const rows = group.clusters.flatMap((cluster) => cluster.instances).map(item).filter(matched);
|
|
883
888
|
if (!rows.length) continue;
|
|
884
889
|
// A group is named, and kept apart, by its deployment where there are several (the Desktop's palette.mjs).
|
|
@@ -1140,6 +1145,44 @@ export function actDecision(state, row, acts, verb) {
|
|
|
1140
1145
|
return { open: true, verb, id, name, kind: lifecycle ? "lifecycle" : "start", machine, label: machine, home: row.home ?? null };
|
|
1141
1146
|
}
|
|
1142
1147
|
|
|
1148
|
+
/** The TUI's own words around the pin key (feature instance-pin; docs/tui.md, "Pinning"), as parts the way
|
|
1149
|
+
* ACT_WORDS are. `unavailable` says why the key does nothing on a kernel that does not list the feature, and the
|
|
1150
|
+
* command that pins. */
|
|
1151
|
+
export const PIN_WORDS = Object.freeze({
|
|
1152
|
+
unavailable: [{ own: "This OATS can't pin instances: it doesn't list instance-pin. With a newer one, p or `oats instance pin <name> on|off` pins." }],
|
|
1153
|
+
pinning: (name, pinned) => [{ own: pinned ? "Pinning " : "Unpinning " }, { shown: name }, { own: "…" }],
|
|
1154
|
+
still: (name) => [{ own: "The pin of " }, { shown: name }, { own: " is still changing." }],
|
|
1155
|
+
done: (name, pinned) => [{ shown: name }, { own: pinned ? " is pinned to the top of its machine's list." : " is unpinned." }],
|
|
1156
|
+
notChanged: (name) => [{ own: "The pin of " }, { shown: name }, { own: " was not changed." }],
|
|
1157
|
+
unconfirmed: (name) => [{ own: "OATS didn't confirm the pin of " }, { shown: name }, { own: ". The list shows it once it is read again." }],
|
|
1158
|
+
});
|
|
1159
|
+
|
|
1160
|
+
/** What the pin key does on `row` (`acts`: its instanceActs answer): `{ open: true, id, name, pinned }`, `pinned`
|
|
1161
|
+
* the value it sets (Unpin on a pinned row, else Pin), or `{ open: false, said }`, the line that says why not:
|
|
1162
|
+
* without the feature, while this run's pin of the row is still changing, or on a row that offers no act of a
|
|
1163
|
+
* client's own (a held, retiring or unaddressable home: the shared reason). A remote row's host without the
|
|
1164
|
+
* feature is the kernel's to refuse (E_REMOTE_INCOMPATIBLE: nothing is sent), said as its refusal. */
|
|
1165
|
+
export function pinDecision(state, row, acts) {
|
|
1166
|
+
const name = row.instance, id = instanceId(row);
|
|
1167
|
+
const no = (said, under = []) => ({ open: false, said: Object.freeze({ said, under }) });
|
|
1168
|
+
if (!pinsListed(state)) return no(PIN_WORDS.unavailable);
|
|
1169
|
+
if (state.pinning?.has(id)) return no(PIN_WORDS.still(name));
|
|
1170
|
+
const held = acts.blocked ?? acts.limited;
|
|
1171
|
+
if (held) return no([], outside(reasonSpoken(held)));
|
|
1172
|
+
return { open: true, id, name, pinned: row.pinned !== true };
|
|
1173
|
+
}
|
|
1174
|
+
|
|
1175
|
+
/** The line after a pin's answer (packages/client instance-pin.mjs pinOutcome): the change, the kernel's refusal
|
|
1176
|
+
* under the TUI's sentence, or that OATS did not confirm it (the list read after it says what is true). */
|
|
1177
|
+
export function pinLine(name, pinned, answer) {
|
|
1178
|
+
if (answer?.status === "ok" && answer.pinned === pinned) return Object.freeze({ said: PIN_WORDS.done(name, pinned), under: Object.freeze([]) });
|
|
1179
|
+
if (answer?.status === "refused") {
|
|
1180
|
+
const said = kernelLines(answer.reason?.message, undefined, TERMS);
|
|
1181
|
+
return Object.freeze({ said: PIN_WORDS.notChanged(name), under: Object.freeze(said.length ? said : outside(displayLine(answer.reason?.code))) });
|
|
1182
|
+
}
|
|
1183
|
+
return Object.freeze({ said: PIN_WORDS.unconfirmed(name), under: Object.freeze([]) });
|
|
1184
|
+
}
|
|
1185
|
+
|
|
1143
1186
|
/** What a start's or a restart's answer (the shared startInstance's) shows, as the act view's
|
|
1144
1187
|
* lines: `{ said }` the TUI's own sentence in parts, `{ text }` a shared sentence or the kernel's
|
|
1145
1188
|
* line (each already as the shared home words it). Chosen by the answer's fields and codes, never
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
import { ACTIONS, LEADER_KEYS, backKeyLabel, bindings, chordKeys, chordsRead, paletteKeys } from "./actions.mjs";
|
|
13
13
|
import { CHORDS, chordFamilyFrom, collapseKey, workspaceStep, displayLine, instanceActs, instanceId, outcomeWords, pendingEntry, spawnProblem } from "./client.mjs";
|
|
14
14
|
import { defaultDetachKey } from "./config.mjs";
|
|
15
|
-
import { BACKGROUND_ID, backgroundOpen, BUTTON_ORDER, SPAWN_WORDS, LEADER_WORDS, SPLIT_WORDS, TAB_WORDS, actDecision, capabilitiesHeight, capabilitiesOf, capabilityUsersOf, disclosure, openDecision, paletteItems, paletteStep, preflightLine, returnedLine, roster, soulNames, soulOfAgent, soulsOf, spawnChoices, spawnChoicesKey, spawnLine, spawnPickerItems, spawnReady, spawnRing, spawnSelector, spawnedRow, switcher, switcherHeight, switcherWindow, memoryKey, memoryKeys, LIST_WORDS, WORKSPACE_WORDS, listChoice, listChoices, workspaceList } from "./model.mjs";
|
|
15
|
+
import { BACKGROUND_ID, backgroundOpen, BUTTON_ORDER, PIN_WORDS, pinDecision, pinLine, SPAWN_WORDS, LEADER_WORDS, SPLIT_WORDS, TAB_WORDS, actDecision, capabilitiesHeight, capabilitiesOf, capabilityUsersOf, disclosure, openDecision, paletteItems, paletteStep, preflightLine, returnedLine, roster, soulNames, soulOfAgent, soulsOf, spawnChoices, spawnChoicesKey, spawnLine, spawnPickerItems, spawnReady, spawnRing, spawnSelector, spawnedRow, switcher, switcherHeight, switcherWindow, memoryKey, memoryKeys, LIST_WORDS, WORKSPACE_WORDS, listChoice, listChoices, workspaceList } from "./model.mjs";
|
|
16
16
|
import { backKeyId, backKeySequences, isBackKey } from "./term/through.mjs";
|
|
17
17
|
import { windowOf } from "./views/scroll.mjs";
|
|
18
18
|
import { SPLIT_MIN, splitFits } from "./views/split.mjs";
|
|
@@ -133,7 +133,7 @@ export function initialState({ deployment = null, cli, home, entry = null, actio
|
|
|
133
133
|
selected: null, collapsed: new Set(), background: new Set(), filter: NO_FILTER, focus: "list", top: 0, loose: false, detailTop: 0, places: new Map(), unread: new Map(), unreadKeys: new Map(), workspaceCursor: null, colour,
|
|
134
134
|
switcher: NO_SWITCHER,
|
|
135
135
|
listed: NO_LIST, identities: new Map(),
|
|
136
|
-
helpTop: 0, actions, ascii, detachKey, opening: null, terminal: null, outcome: null, act: null, acted: 0, starting: new Map(), retiring: new Set(),
|
|
136
|
+
helpTop: 0, actions, ascii, detachKey, opening: null, terminal: null, outcome: null, act: null, acted: 0, starting: new Map(), retiring: new Set(), pinning: new Set(),
|
|
137
137
|
leaderKey: backKeyId(detachKey), leader: null, keyboard: null, keysRead, mac: platform === "darwin", chords: chordKeys(platform === "darwin", actions, CHORDS, keysRead.family, backKeyId(detachKey)), palette: null, paletteKeys: paletteKeys(platform === "darwin"), recent: new Map(), layouts: new Map(), restoring: null, leftFocus: null, souls: NO_SOULS, capabilities: NO_CAPABILITIES,
|
|
138
138
|
spawn: null, spawning: null, spawnCheck: null, arriving: null, previews: 0, tabs: Object.freeze([]), split: null, group: 0, aside: null,
|
|
139
139
|
notice: null,
|
|
@@ -737,6 +737,23 @@ function resumedHeard(state, reading) {
|
|
|
737
737
|
return { state, effect: null };
|
|
738
738
|
}
|
|
739
739
|
|
|
740
|
+
/** The pin key on `row` (feature instance-pin; lib/model.mjs pinDecision): at once, no confirmation. The line under
|
|
741
|
+
* the sidebar's title says it is changing, the row is held from a second press until the answer, and the loop runs
|
|
742
|
+
* the kernel's verb (`{ pin }`); a key it does nothing for says why on that line. */
|
|
743
|
+
function pinOn(state, row) {
|
|
744
|
+
const decision = pinDecision(state, row, instanceActs(row));
|
|
745
|
+
if (!decision.open) return { state: next(state, { outcome: decision.said }), effect: null };
|
|
746
|
+
const pinning = new Set(state.pinning); pinning.add(decision.id);
|
|
747
|
+
const outcome = Object.freeze({ said: PIN_WORDS.pinning(decision.name, decision.pinned), under: Object.freeze([]) });
|
|
748
|
+
return { state: next(state, { pinning, outcome }), effect: { pin: Object.freeze({ id: decision.id, row, pinned: decision.pinned }) } };
|
|
749
|
+
}
|
|
750
|
+
/** A pin answered (lib/main.mjs): the line says how, the row is free again, and the rows are read again, so the
|
|
751
|
+
* list moves (a refusal changes nothing, and the read says so too). */
|
|
752
|
+
function pinHeard(state, { id, name, pinned, answer }) {
|
|
753
|
+
const pinning = new Set(state.pinning); pinning.delete(id);
|
|
754
|
+
return { state: next(state, { pinning, outcome: pinLine(name, pinned, answer) }), effect: { refresh: { live: true } } };
|
|
755
|
+
}
|
|
756
|
+
|
|
740
757
|
/** A Remove answered (lib/main.mjs): the switcher says how, and the list is read again. */
|
|
741
758
|
function removedHeard(state, { name, ok, reason = null }) {
|
|
742
759
|
const line = Object.freeze(ok ? { removed: name } : { notRemoved: name, message: reason?.message ?? "" });
|
|
@@ -1477,6 +1494,13 @@ function led(state, does, event, keymap) {
|
|
|
1477
1494
|
const stay = { state, effect: null }, t = state.terminal;
|
|
1478
1495
|
const inTerminal = t?.focus === "terminal" && state.view === "instances";
|
|
1479
1496
|
if (does === "list") return toList(state);
|
|
1497
|
+
// The shared table's `b` (the Desktop's sidebar; the Desktop UI rework, slice 4): the list is the TUI's sidebar. With
|
|
1498
|
+
// a terminal shown, it takes the whole screen with the focus (as zoom does), and zoomed, the list comes back with the
|
|
1499
|
+
// focus (as Esc does). With none shown the list is all there is: nothing.
|
|
1500
|
+
if (does === "sidebar") {
|
|
1501
|
+
if (t === null || state.view !== "instances") return stay;
|
|
1502
|
+
return t.zoom ? toList(state) : { state: terminalWith(state, { focus: "terminal", zoom: true }), effect: null };
|
|
1503
|
+
}
|
|
1480
1504
|
if (does === "palette") return { state: paletteOpened(state, event, inTerminal ? "terminal" : "list"), effect: null };
|
|
1481
1505
|
if (does === "zoom" || does === "close-terminal") {
|
|
1482
1506
|
if (t === null) return stay;
|
|
@@ -1661,6 +1685,7 @@ function reduced(state, event, keymap) {
|
|
|
1661
1685
|
if (event.retiring !== undefined) return { state: next(state, { retiring: new Set(event.retiring) }), effect: null };
|
|
1662
1686
|
if (event.listed !== undefined) return listedHeard(state, event.listed);
|
|
1663
1687
|
if (event.removed !== undefined) return removedHeard(state, event.removed);
|
|
1688
|
+
if (event.pinned !== undefined) return pinHeard(state, event.pinned);
|
|
1664
1689
|
// The machine sweep's reading: no line, at most a live read.
|
|
1665
1690
|
if (event.resumed !== undefined) return resumedHeard(state, event.resumed);
|
|
1666
1691
|
// Shown once, in the line under the sidebar's title, as the line after an open is.
|
|
@@ -1762,6 +1787,7 @@ function reduced(state, event, keymap) {
|
|
|
1762
1787
|
return refused === true ? { state, effect: null } : refused !== null ? { state: next(state, { outcome: refused }), effect: null } : splitKey(state, action, false);
|
|
1763
1788
|
}
|
|
1764
1789
|
case "stop": case "retire": case "start": case "restart": return at < 0 ? stay : actOn(state, r.items[at].row, action);
|
|
1790
|
+
case "pin": return at < 0 || !r.items[at].row ? stay : pinOn(state, r.items[at].row);
|
|
1765
1791
|
case "detail": return at < 0 ? stay : { state: next(state, { focus: state.focus === "detail" ? "list" : "detail" }), effect: null };
|
|
1766
1792
|
case "up": case "down": case "top": case "bottom": case "page-up": case "page-down": {
|
|
1767
1793
|
if (state.focus === "detail") return { state: next(state, { detailTop: scrolled(state.detailTop) }), effect: null };
|
|
@@ -209,10 +209,10 @@ the final values in one short message before you go on. The rules:
|
|
|
209
209
|
- New: the **workspace name**: lowercase letters and digits, words joined
|
|
210
210
|
by single `-` (`^[a-z0-9]+(?:-[a-z0-9]+)*$`), for example `acme`. Refuse
|
|
211
211
|
`agents`: OATS keeps instance homes in a folder of that name. Default:
|
|
212
|
-
their project's name
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
for a name.
|
|
212
|
+
their project's name: its repository's name when it has one, else its
|
|
213
|
+
folder's (the repository's wins when they differ), normalised as in the
|
|
214
|
+
machine's round, with repeated `-` collapsed and a leading or trailing
|
|
215
|
+
`-` dropped (`My_App_` gives `my-app`); with no project, ask for a name.
|
|
216
216
|
- **New workspace: the host,** the one repository that holds the
|
|
217
217
|
workspace's files:
|
|
218
218
|
- **One repository (a monorepo):** that repository, the files at its root;
|
|
@@ -249,15 +249,16 @@ the final values in one short message before you go on. The rules:
|
|
|
249
249
|
`U` (`https://…`, the API URL their server gives its users), and whether
|
|
250
250
|
their server uses the public AWID registry. Answers given in the prompt
|
|
251
251
|
that started you are used without asking. When it uses a private
|
|
252
|
-
registry,
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
hosted aweb now (the hosted defaults above, `N` among them, shown in one
|
|
256
|
-
short message) or waiting for that release. Otherwise, tell them, in
|
|
252
|
+
registry, ask its address too, the registry origin `RG` (`https://…`,
|
|
253
|
+
the scheme and host only, with no path), also not a secret. Step 9
|
|
254
|
+
records it for this deployment. Then tell them, in
|
|
257
255
|
plain words, what must already be in place on their side, since you
|
|
258
256
|
make none of it: the namespace's controller key on this computer, for
|
|
259
257
|
this computer account; the `_awid.ND` DNS record published for that
|
|
260
|
-
key; and their server reachable at `U`.
|
|
258
|
+
key; and their server reachable at `U`. On a private registry, that
|
|
259
|
+
record must name their registry: a key prepared without
|
|
260
|
+
`--registry RG` gives a record for the public registry, so tell them
|
|
261
|
+
to check that its value carries `registry=RG`. Step 9
|
|
261
262
|
checks them, read-only. On their own server there is no account `N` and
|
|
262
263
|
no step 5: the team is `<workspace>:ND`, created in step 9 in their
|
|
263
264
|
namespace, and `A` is `<workspace>-root` as on hosted. Never offer it on
|
|
@@ -561,7 +562,7 @@ installed CLI's catalog:
|
|
|
561
562
|
node -e 'const c=require(process.argv[1]);console.log(c.packages["oats.framework"].ref,c.packages["oats.aweb"].ref)' "$(oats root)/package-catalog.json"
|
|
562
563
|
```
|
|
563
564
|
|
|
564
|
-
It prints the two refs, for example `oats-framework/v1.
|
|
565
|
+
It prints the two refs, for example `oats-framework/v1.27.0 v1.46.0`. If the
|
|
565
566
|
framework's version (after the `/`) is below `1.19.0`, or with aweb
|
|
566
567
|
`oats.aweb`'s is below `v1.33.1`, this OATS release is older than this
|
|
567
568
|
skill: stop, and tell the person to wait for the next OATS
|
|
@@ -601,14 +602,18 @@ release's `oats.aweb` was tested with, which `oats.aweb` publishes in its
|
|
|
601
602
|
`aw-compat.json`: hosted aweb upgrades its server before a new `aw` comes
|
|
602
603
|
out, but their own server has no such order. Read that version at the exact
|
|
603
604
|
`oats.aweb` release the installed CLI's catalog names, never at `main`.
|
|
604
|
-
|
|
605
|
+
On a private registry (step 1), add ` private` at the end of the line,
|
|
606
|
+
after the catalog's path: that branch needs a later `oats.aweb`. This
|
|
607
|
+
prints `TESTED <version>`, or why it can't:
|
|
605
608
|
|
|
606
609
|
```bash
|
|
607
|
-
node -e 'const c=require(process.argv[1]).packages["oats.aweb"],m=/^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(c.url),v=/^v(\d+)\.(\d+)\.(\d+)$/.exec(c.ref);if(!m){console.log("NOT_GITHUB "+c.url);process.exit(1)}if(!v||v.slice(1).reduce((d,x,i)=>d||x-[
|
|
610
|
+
node -e 'const c=require(process.argv[1]).packages["oats.aweb"],m=/^https:\/\/github\.com\/([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(c.url),v=/^v(\d+)\.(\d+)\.(\d+)$/.exec(c.ref);if(!m){console.log("NOT_GITHUB "+c.url);process.exit(1)}if(process.argv.length>3||![undefined,"private"].includes(process.argv[2])){console.log("FAILED usage");process.exit(1)}const f=process.argv[2]?[1,43,0]:[1,42,1];if(!v||v.slice(1).reduce((d,x,i)=>d||x-f[i],0)<0){console.log("TOO_OLD "+c.ref);process.exit(1)}const u="https://raw.githubusercontent.com/"+m[1]+"/"+m[2]+"/"+c.ref+"/"+c.path+"/capabilities/oats-aweb/aw-compat.json";fetch(u).then(r=>{if(!r.ok)throw new Error("HTTP "+r.status+" "+u);return r.json()}).then(j=>{if(Object.keys(j).sort().join()!=="min,tested"||typeof j.tested!=="string"||!/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(-(0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(\.(0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(\+[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$/.test(j.tested))throw new Error("unexpected "+JSON.stringify(j));console.log("TESTED "+j.tested)}).catch(e=>{console.log("FAILED "+e.message);process.exit(1)})' "$(oats root)/package-catalog.json"
|
|
608
611
|
```
|
|
609
612
|
|
|
610
613
|
- **`TOO_OLD`:** this OATS release's `oats.aweb` is older than `v1.42.1`,
|
|
611
|
-
the first that sets up a team on a person's own server
|
|
614
|
+
the first that sets up a team on a person's own server, or, on a private
|
|
615
|
+
registry, older than `v1.43.0`, the first that records the registry
|
|
616
|
+
(`oats aweb setup --registry`).
|
|
612
617
|
**`NOT_GITHUB` or `FAILED`:** the tested version can't be read. Either
|
|
613
618
|
way, the own-server branch stops here. Tell the person in one sentence,
|
|
614
619
|
and offer hosted aweb now (step 1's hosted defaults, `N` among them,
|
|
@@ -851,8 +856,8 @@ name: acme
|
|
|
851
856
|
members:
|
|
852
857
|
- git:github.com/acme/acme-oats # the host; the setup expert adds the others
|
|
853
858
|
packages:
|
|
854
|
-
oats.framework: v1.
|
|
855
|
-
oats.aweb: v1.
|
|
859
|
+
oats.framework: v1.27.0 # the installed CLI's catalog versions (below)
|
|
860
|
+
oats.aweb: v1.46.0 # messaging: agent identities, mail and chat
|
|
856
861
|
oats.machine: v0.1.1 # on a machine found-list only: the machine's steward
|
|
857
862
|
defaults:
|
|
858
863
|
capabilities:
|
|
@@ -902,7 +907,10 @@ workspace: git:github.com/acme/acme-oats
|
|
|
902
907
|
repos/<owner>/<repo>/branches/<branch> --jq .protected` prints `true`,
|
|
903
908
|
`gh api repos/<owner>/<repo>/rules/branches/<branch> --jq length` prints
|
|
904
909
|
more than 0, or either fails), or the push is refused: push a branch
|
|
905
|
-
instead, open a pull request, tell them, and stop until it is merged.
|
|
910
|
+
instead, open a pull request, tell them, and stop until it is merged. A
|
|
911
|
+
403 from the rules read saying the feature needs an upgrade ("Upgrade to
|
|
912
|
+
GitHub Pro or make this repository public") is not a failure: the
|
|
913
|
+
repository's plan has no rulesets, so it counts as 0.
|
|
906
914
|
- If `git config user.name` or `git config user.email` prints nothing in
|
|
907
915
|
`D/<repo>`, commit with the name step 1's yes covered:
|
|
908
916
|
`-c user.name="<their name>" -c user.email="<their noreply address>"`,
|
|
@@ -1019,6 +1027,30 @@ below; for another capability, follow its own setup skill, and stop if its
|
|
|
1019
1027
|
readiness still reports a problem.
|
|
1020
1028
|
|
|
1021
1029
|
**With aweb (`oats.aweb`):**
|
|
1030
|
+
|
|
1031
|
+
**Their own aweb server on a private registry (step 1): record it first,**
|
|
1032
|
+
before item 1, with `RG` written in. Skip this on the public registry and
|
|
1033
|
+
on hosted aweb.
|
|
1034
|
+
|
|
1035
|
+
```bash
|
|
1036
|
+
cd "D" && oats aweb setup --soul S --registry RG
|
|
1037
|
+
```
|
|
1038
|
+
|
|
1039
|
+
It writes only `settings.oats.aweb.registry` in `D/oats-local.yaml`, the
|
|
1040
|
+
one setting that admits a private registry here: every later `oats aweb`
|
|
1041
|
+
command and every agent of `D` reads its registry from it. Never set
|
|
1042
|
+
`AWID_REGISTRY_URL` instead: oats.aweb refuses a private registry given
|
|
1043
|
+
that way (`registry-setting-required`), item 1's check included, until
|
|
1044
|
+
this setting is recorded. Success prints one line of JSON whose
|
|
1045
|
+
`registry` is `RG` as an origin (the host in lowercase, no trailing `/`).
|
|
1046
|
+
Its `next` lists "Restart resident serve" and "Restart wake": both are
|
|
1047
|
+
expected and need nothing from you, since this new deployment has no
|
|
1048
|
+
resident yet and item 6 installs the broker after this. An
|
|
1049
|
+
`E_SETUP_REGISTRY` refusal that starts `settings.oats.aweb.registry:`
|
|
1050
|
+
says what is wrong with the address (a path, `/api`, a query): ask the
|
|
1051
|
+
person for the registry's origin again and run this again. Anything
|
|
1052
|
+
else: stop, spawn nothing, and tell the person what it shows.
|
|
1053
|
+
|
|
1022
1054
|
1. **Check:**
|
|
1023
1055
|
|
|
1024
1056
|
```bash
|
|
@@ -1230,8 +1262,45 @@ readiness still reports a problem.
|
|
|
1230
1262
|
`delivery: session`: its own channel wakes it (step 4). Any other setup
|
|
1231
1263
|
expert is woken only by the host wake broker, and oats.aweb refuses to
|
|
1232
1264
|
spawn or start it while no broker runs (`wake-daemon-not-running`). The
|
|
1233
|
-
broker is the person's own user service, so it is theirs to start.
|
|
1234
|
-
|
|
1265
|
+
broker is the person's own user service, so it is theirs to start.
|
|
1266
|
+
|
|
1267
|
+
**On a private registry (step 1), first check the install yourself,**
|
|
1268
|
+
read-only: the broker must carry `RG`, and the status check below can't
|
|
1269
|
+
see which registry a running broker serves.
|
|
1270
|
+
|
|
1271
|
+
```bash
|
|
1272
|
+
cd "D" && oats aweb wake install --plan --json
|
|
1273
|
+
```
|
|
1274
|
+
|
|
1275
|
+
It changes nothing, and it refuses whatever the install would refuse.
|
|
1276
|
+
Only `"ok": true` lets you go on to their install below: then no other
|
|
1277
|
+
broker runs on this computer account, or the one that runs is the
|
|
1278
|
+
install's own and already carries `RG`, so the status check below
|
|
1279
|
+
proves the right broker. Otherwise its `error.code` decides:
|
|
1280
|
+
- **`E_WAKE_REGISTRY_CONFLICT`:** this computer account already runs a
|
|
1281
|
+
wake broker for another registry, or for none, most likely for
|
|
1282
|
+
another deployment, and one account's broker serves one registry.
|
|
1283
|
+
Stop, spawn nothing, and tell the person in plain words; the choice is
|
|
1284
|
+
theirs: run this deployment under another computer account, or move
|
|
1285
|
+
the other one, as the message says. Never uninstall the broker or
|
|
1286
|
+
deregister another deployment's homes yourself.
|
|
1287
|
+
- **`E_WAKE_UNSUPPORTED`** (a container, or a machine with neither
|
|
1288
|
+
launchd nor systemd): there is no service to install, and the plain
|
|
1289
|
+
`aw wake run` below would not carry `RG`. Stop and spawn nothing.
|
|
1290
|
+
Tell the person in one sentence, and offer a Claude or pi setup
|
|
1291
|
+
expert instead, which its own channel wakes: with that harness, this
|
|
1292
|
+
item is skipped.
|
|
1293
|
+
- **Any other refusal** (for example a broker started by hand or by
|
|
1294
|
+
another supervisor, `E_WAKE_RUNNING_UNSUPERVISED`, or a service the
|
|
1295
|
+
install didn't write, `E_WAKE_UNIT_CONFLICT`): stop and spawn nothing.
|
|
1296
|
+
A broker that is running now would pass the status check without
|
|
1297
|
+
carrying `RG`. Tell the person in plain words what its message says;
|
|
1298
|
+
the fix is theirs, and the message names it. Once they say it's done,
|
|
1299
|
+
run this check again. Never stop, uninstall or deregister a broker
|
|
1300
|
+
yourself.
|
|
1301
|
+
|
|
1302
|
+
Open their own terminal ("How to work") running this, with `D` filled
|
|
1303
|
+
in:
|
|
1235
1304
|
|
|
1236
1305
|
```text
|
|
1237
1306
|
cd "D" && oats aweb wake install
|
|
@@ -1239,7 +1308,8 @@ readiness still reports a problem.
|
|
|
1239
1308
|
|
|
1240
1309
|
In a container, or on a machine with neither launchd nor systemd (the
|
|
1241
1310
|
command answers `E_WAKE_UNSUPPORTED`), there is no service to install:
|
|
1242
|
-
the line is `aw wake run`, kept running as a
|
|
1311
|
+
on the public registry, the line is `aw wake run`, kept running as a
|
|
1312
|
+
supervised process.
|
|
1243
1313
|
|
|
1244
1314
|
Then check it yourself:
|
|
1245
1315
|
|
|
@@ -1323,8 +1393,10 @@ are cloned, knowledge tools, messaging wanted or not>
|
|
|
1323
1393
|
the person (new workspace), or T owned by aweb account <handle>
|
|
1324
1394
|
(signed in at step 5), or new account N signed up (machine found-list),
|
|
1325
1395
|
or joined L by invite (existing), or team T on their own aweb server U,
|
|
1326
|
-
namespace ND,
|
|
1327
|
-
|
|
1396
|
+
namespace ND, registry public | RG (recorded in
|
|
1397
|
+
`settings.oats.aweb.registry`), aw <tested> (oats.aweb's tested
|
|
1398
|
+
version) or "aw <version> is newer than the tested <tested>; kept", its
|
|
1399
|
+
key at
|
|
1328
1400
|
<team key path> | not set up (the setup expert has no messaging)
|
|
1329
1401
|
- Harness channel mode: development, confirmed by OATS at each start
|
|
1330
1402
|
(Claude with aweb) | none (Codex, pi or no messaging)
|
|
@@ -1493,8 +1565,9 @@ the setup expert, not in this message. You are done.
|
|
|
1493
1565
|
aweb server, checked against step 9's create.
|
|
1494
1566
|
- **On their own aweb server:** make or touch the namespace's controller key
|
|
1495
1567
|
(`aw id namespace prepare-controller`, `~/.awid`), set or ask for
|
|
1496
|
-
`AWEB_API_KEY`,
|
|
1497
|
-
`
|
|
1568
|
+
`AWEB_API_KEY`, set `AWID_REGISTRY_URL` (a private registry is
|
|
1569
|
+
recorded by `oats aweb setup --registry` only), or write a hosted
|
|
1570
|
+
`default:…aweb.ai` team or `localTeams` into the workspace.
|
|
1498
1571
|
- **Write a setup soul into the workspace:** the setup expert is
|
|
1499
1572
|
`oats.framework`'s.
|
|
1500
1573
|
- **The Desktop:** never download it through a browser, skip a verification
|