@awebai/oats 0.65.0 → 0.67.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +11 -5
- package/bin/oats.mjs +74 -20
- package/docs/capabilities.md +4 -4
- package/docs/capability-manifest.schema.json +1 -1
- package/docs/desktop-cli-api.md +222 -10
- package/docs/desktop.md +101 -22
- package/docs/implementation.md +16 -6
- package/docs/integrations.md +1 -1
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-lane.md +16 -0
- package/docs/release-notes/v0.66.0.md +183 -0
- package/docs/release-notes/v0.67.0.md +366 -0
- package/docs/release-notes/v0.67.1.md +64 -0
- package/docs/servers.md +5 -4
- package/docs/souls-and-instances.md +20 -3
- package/docs/tui.md +658 -143
- package/docs/upgrading.md +107 -25
- package/docs/workspaces.md +9 -2
- package/lib/capability-contract.mjs +2 -2
- package/lib/core.mjs +126 -54
- package/lib/deployments.mjs +21 -5
- package/lib/instance-color.mjs +58 -0
- package/lib/instance-inspect.mjs +107 -23
- package/lib/instance-lifecycle.mjs +21 -1
- package/lib/instance-naming.mjs +187 -0
- package/lib/instance-resolution.mjs +5 -1
- package/lib/materialize.mjs +62 -11
- package/lib/servers.mjs +15 -6
- package/lib/soul-composition.mjs +7 -3
- package/package-catalog.json +2 -2
- package/package.json +1 -1
- package/packages/client/cli-adapter.mjs +37 -5
- package/packages/client/cli-locator.mjs +2 -2
- package/packages/client/composed-gate.mjs +10 -2
- package/packages/client/deployment-data.mjs +5 -0
- package/packages/client/deployment-identity.mjs +40 -0
- package/packages/client/deployment-panel.mjs +3 -1
- package/packages/client/inspect-boundary.mjs +11 -7
- package/packages/client/inspect-cache.mjs +2 -2
- package/packages/client/instance-name.mjs +28 -0
- package/packages/client/instance-presentation.mjs +11 -0
- package/packages/client/keymap.mjs +99 -11
- package/packages/client/keys-file.mjs +122 -0
- package/packages/client/machine-contract.mjs +1 -5
- package/packages/client/own-codes.mjs +4 -2
- package/packages/client/panel-views.mjs +62 -9
- package/packages/client/spawn-naming.mjs +31 -0
- package/packages/client/spawn-preview-cli.mjs +22 -7
- package/packages/client/spawn-preview-contract.mjs +24 -0
- package/packages/client/spawn-preview-facts.mjs +8 -4
- package/packages/client/spawn-preview.mjs +47 -2
- package/packages/record/bin/setup.mjs +10 -2
- package/packages/record/docs/capture-service.md +45 -6
- package/packages/record/lib/capture-service-install.mjs +6 -95
- package/packages/record/lib/capture-setup-write.mjs +233 -0
- package/packages/tui/README.md +9 -8
- package/packages/tui/lib/actions.mjs +108 -64
- package/packages/tui/lib/client.mjs +8 -3
- package/packages/tui/lib/config.mjs +208 -26
- package/packages/tui/lib/main.mjs +91 -20
- package/packages/tui/lib/model.mjs +167 -61
- package/packages/tui/lib/read.mjs +53 -1
- package/packages/tui/lib/store.mjs +156 -47
- package/packages/tui/lib/term/keys.mjs +150 -34
- package/packages/tui/lib/term/kitty.mjs +223 -0
- package/packages/tui/lib/term/through.mjs +174 -27
- package/packages/tui/lib/term/tty.mjs +43 -12
- package/packages/tui/lib/views/frame.mjs +158 -79
- package/packages/tui/lib/views/help.mjs +143 -21
- package/packages/tui/lib/views/instances.mjs +59 -20
- package/packages/tui/lib/views/palette.mjs +14 -4
- package/packages/tui/lib/views/souls.mjs +2 -2
- package/packages/tui/lib/views/switcher.mjs +6 -1
- package/skills/oats-getting-started/SKILL.md +107 -34
package/lib/servers.mjs
CHANGED
|
@@ -25,6 +25,7 @@ import { parseStrictJson } from "./canonical-json.mjs";
|
|
|
25
25
|
import { noteRuntimeName } from "./deprecation.mjs";
|
|
26
26
|
import { readWaitingClaim } from "./instance-events.mjs";
|
|
27
27
|
import { readRetireState } from "./retire-state.mjs";
|
|
28
|
+
import { paletteColor } from "./instance-color.mjs";
|
|
28
29
|
import { withDirLock } from "./dir-lock.mjs";
|
|
29
30
|
import { shellWord } from "./core.mjs";
|
|
30
31
|
import { DETACH_KEY_FEATURE, requireDetachKey } from "./session-viewer.mjs";
|
|
@@ -661,6 +662,8 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
|
|
|
661
662
|
// spawn-preview-2 is proven to answer --preview without spawning.
|
|
662
663
|
const preview = oatsArgs.includes("--preview");
|
|
663
664
|
if (preview) requireRemoteFeature(remote, target, "spawn-preview-2");
|
|
665
|
+
// #1421 §3: the naming call runs on the host, through its routed preview.
|
|
666
|
+
if (oatsArgs.includes("--suggest-name")) requireRemoteFeature(remote, target, "spawn-suggest-name");
|
|
664
667
|
const { envelope, stderr } = runRemote(target, json(withScope(["spawn", ...hostHarnessArgs(remote, oatsArgs)])), io);
|
|
665
668
|
if (preview && envelope.ok && envelope.result?.preview === true && envelope.result.spawnPreviewApi === 2) {
|
|
666
669
|
// The host's preview with the two fields a routed spawn adds; never a
|
|
@@ -785,6 +788,8 @@ export function routeCommand(serverId, cmd, oatsArgs, io = {}) {
|
|
|
785
788
|
if (cmd === "inspect" && args.includes("--instructions")) requireRemoteFeature(remote, target, "soul-composed-instructions");
|
|
786
789
|
// `inspect --skills` (feature soul-skills): the same, for the soul's own skills.
|
|
787
790
|
if (cmd === "inspect" && args.includes("--skills")) requireRemoteFeature(remote, target, "soul-skills");
|
|
791
|
+
// `inspect --composed-skills` (feature soul-composed-skills): the same, for every skill a spawn would give.
|
|
792
|
+
if (cmd === "inspect" && args.includes("--composed-skills")) requireRemoteFeature(remote, target, "soul-composed-skills");
|
|
788
793
|
const scoped = args.includes("--dir") || args.includes("--home") ? args : [...args, "--dir", target.workspace];
|
|
789
794
|
const { envelope, stderr } = runRemote(target, json([cmd, ...scoped]), io);
|
|
790
795
|
return { envelope: envelope.result && typeof envelope.result === "object" ? { ...envelope, result: { ...envelope.result, server: serverId, ...(route ? { route: { home: route.home, instance: route.snapshot?.instance || null, frozen: !!route.snapshot } } : {}) } } : envelope, stderr };
|
|
@@ -801,15 +806,17 @@ const HOST_SURFACES = {
|
|
|
801
806
|
"instance diff": { feature: "instance-git", api: "instanceGitApi", version: 1 },
|
|
802
807
|
"instance stop": { feature: "lifecycle-plans", api: "lifecycleApi", version: 1 },
|
|
803
808
|
"retire plan": { feature: "lifecycle-plans", api: "lifecycleApi", version: 1 },
|
|
809
|
+
// Feature instance-color: the feature alone (its answer's instanceColorApi is not a probe key).
|
|
810
|
+
"instance color": { feature: "instance-color" },
|
|
804
811
|
};
|
|
805
812
|
|
|
806
813
|
function requireSurface(remote, target, surface) {
|
|
807
|
-
if (!remote.features.includes(surface.feature) || remote[surface.api] !== surface.version) {
|
|
808
|
-
throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise ${surface.feature} (${surface.api} ${surface.version}); upgrade it there; nothing was sent`);
|
|
814
|
+
if (!remote.features.includes(surface.feature) || (surface.api !== undefined && remote[surface.api] !== surface.version)) {
|
|
815
|
+
throw serverError("E_REMOTE_INCOMPATIBLE", `remote oats ${remote.version} at ${target.sshHost} does not advertise ${surface.feature}${surface.api !== undefined ? ` (${surface.api} ${surface.version})` : ""}; upgrade it there; nothing was sent`);
|
|
809
816
|
}
|
|
810
817
|
}
|
|
811
818
|
|
|
812
|
-
/** `readiness`, `instance events|git|diff|stop` and `retire --plan` on the
|
|
819
|
+
/** `readiness`, `instance events|git|diff|stop|color` and `retire --plan` on the
|
|
813
820
|
* host: the instance is addressed as every routed session command addresses
|
|
814
821
|
* it (its name through a saved route or the host's roster, or an exact
|
|
815
822
|
* --home), the scope is an explicit --dir on the host or the registered
|
|
@@ -818,7 +825,7 @@ function requireSurface(remote, target, surface) {
|
|
|
818
825
|
function routeHostSurface(serverId, cmd, oatsArgs, io) {
|
|
819
826
|
const key = cmd === "instance" ? `instance ${oatsArgs[0]}` : cmd === "retire" ? "retire plan" : cmd;
|
|
820
827
|
const surface = HOST_SURFACES[key];
|
|
821
|
-
if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff and
|
|
828
|
+
if (!surface) throw serverError("E_USAGE", `--server routes instance events, git, diff, stop and color only (not ${key})`);
|
|
822
829
|
const args = [...oatsArgs];
|
|
823
830
|
const valueOf = (flag) => { const i = args.indexOf(flag); return i >= 0 && args[i + 1] !== undefined && !args[i + 1].startsWith("--") ? args[i + 1] : undefined; };
|
|
824
831
|
const name = cmd === "readiness" ? undefined : args[cmd === "instance" ? 1 : 0];
|
|
@@ -864,8 +871,10 @@ function listSnapshotServers() {
|
|
|
864
871
|
* record (`repo` is a path on the host, never read here); `soul` and `modules`
|
|
865
872
|
* carry the host's drift observation against its own members and lock, not
|
|
866
873
|
* recomputed here (#675). */
|
|
867
|
-
export const REMOTE_ROW_FACTS = ["identity", "identityAddress", "teams", "startedAt", "createdAt", "model", "runtimeState", "parentInstance", "siblingInstance", "relation", "relativeTo", "spawnOrigin", "work", "repo", "branch", "modelFrom", "soul", "modules"];
|
|
868
|
-
|
|
874
|
+
export const REMOTE_ROW_FACTS = ["identity", "identityAddress", "teams", "startedAt", "createdAt", "model", "runtimeState", "parentInstance", "siblingInstance", "relation", "relativeTo", "spawnOrigin", "work", "repo", "branch", "modelFrom", "soul", "modules", "color"];
|
|
875
|
+
/** Each fact as the host answered it, null when it did not; `color` (feature instance-color) only as a palette
|
|
876
|
+
* name (lib/instance-color.mjs paletteColor), anything else null. */
|
|
877
|
+
const rowFacts = (i = {}) => Object.fromEntries(REMOTE_ROW_FACTS.map((k) => [k, k === "color" ? paletteColor(i[k]) : i[k] ?? null]));
|
|
869
878
|
/** `waitingOnYou` (feature waiting-on-you) is relayed ONLY when the host's row has the
|
|
870
879
|
* key, so it is not one of REMOTE_ROW_FACTS: a host whose kernel predates the feature
|
|
871
880
|
* omits it, and absent ("not reported") must stay distinct from null ("no claim"). The
|
package/lib/soul-composition.mjs
CHANGED
|
@@ -40,8 +40,11 @@ function clampSpan({ start, end }, length) {
|
|
|
40
40
|
* home-relative and `materialized: true`);
|
|
41
41
|
* - composedInstructions: inspect's `{ file: null, text, truncated, resolution, body, sources }`,
|
|
42
42
|
* `text` capped at `cap` and every range clamped to it.
|
|
43
|
-
* Throws an E_ coded error when the soul cannot be composed here. `materialize` is a test seam.
|
|
44
|
-
|
|
43
|
+
* Throws an E_ coded error when the soul cannot be composed here. `materialize` is a test seam.
|
|
44
|
+
* `inScratch({ outcome, scratch })`, when given, runs once the composition is proven and before the
|
|
45
|
+
* scratch home is removed, so another read of the same materialization (inspect's composedSkills)
|
|
46
|
+
* needs no second one; its value is returned as `scratchResult`. */
|
|
47
|
+
export async function composeSoulInstructions({ deployment, prepared, soulDir, cap = COMPOSED_TEXT_CAP, materialize = materializePrepared, inScratch }) {
|
|
45
48
|
const soulName = prepared.soulEntry?.name ?? agentDirOf(prepared.soulEntry);
|
|
46
49
|
let agent, composition, body;
|
|
47
50
|
try {
|
|
@@ -78,8 +81,9 @@ export async function composeSoulInstructions({ deployment, prepared, soulDir, c
|
|
|
78
81
|
const parts = renderInstructionParts(body, blocks);
|
|
79
82
|
const length = Math.min(parts.text.length, cap);
|
|
80
83
|
const kernelBlocks = composition.blocks.length;
|
|
84
|
+
const scratchResult = inScratch ? await inScratch({ outcome, scratch }) : undefined;
|
|
81
85
|
return {
|
|
82
|
-
text: parts.text, blocks, resolved: composition.resolved, oatsCoreDeclared: composition.oatsCoreDeclared,
|
|
86
|
+
text: parts.text, blocks, resolved: composition.resolved, oatsCoreDeclared: composition.oatsCoreDeclared, scratchResult,
|
|
83
87
|
composedInstructions: {
|
|
84
88
|
file: null, text: parts.text.slice(0, length), truncated: parts.text.length > length,
|
|
85
89
|
resolution: prepared.resolution?.revision ?? null,
|
package/package-catalog.json
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
},
|
|
9
9
|
"oats.aweb": {
|
|
10
10
|
"url": "https://github.com/awebai/oats-aweb.git",
|
|
11
|
-
"ref": "v1.
|
|
11
|
+
"ref": "v1.30.0",
|
|
12
12
|
"path": "oats-package"
|
|
13
13
|
},
|
|
14
14
|
"oats.jira": {
|
|
@@ -43,7 +43,7 @@
|
|
|
43
43
|
},
|
|
44
44
|
"oats.framework": {
|
|
45
45
|
"url": "https://github.com/awebai/oats.git",
|
|
46
|
-
"ref": "oats-framework/v1.13.
|
|
46
|
+
"ref": "oats-framework/v1.13.5",
|
|
47
47
|
"path": "oats-package"
|
|
48
48
|
}
|
|
49
49
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@awebai/oats",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.67.1",
|
|
4
4
|
"description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agents",
|
|
@@ -31,6 +31,7 @@ import { gitFileId, gitRevision, gitIndexRevision, gitObservation } from './inst
|
|
|
31
31
|
import { validMaxAge, maxAgeArgv } from './deployment-contract.mjs';
|
|
32
32
|
import { MACHINE_ID, machineFieldProblem } from './machine-contract.mjs';
|
|
33
33
|
import { kernelMade } from './kernel-made.mjs';
|
|
34
|
+
import { SOUL_COLORS } from './soul-colors.mjs';
|
|
34
35
|
|
|
35
36
|
const ENVELOPE_TIMEOUT_MS = 60_000;
|
|
36
37
|
|
|
@@ -151,11 +152,19 @@ export function writeTaskFile(taskText, io = {}) {
|
|
|
151
152
|
* fixed list of options), so this home's own default for it is `execFileInSession`. Such a child is given no
|
|
152
153
|
* deadline (`timeout: 0`, the default of an apply): execFileInSession arms its kill only for a positive one,
|
|
153
154
|
* and the caller's own wait ends instead (cliStart's START_WAIT_MS; instance-lifecycle.mjs APPLY_WAIT_MS). */
|
|
154
|
-
|
|
155
|
+
/** What a kernel answer may print, bytes of stdout: every read but a soul inspection that carries its skills' text. */
|
|
156
|
+
export const ENVELOPE_MAX_BUFFER = 4 * 1024 * 1024;
|
|
157
|
+
/** A soul inspection with `--skills` and/or `--composed-skills`: their texts' budgets (1 MiB and 2 MiB of UTF-8,
|
|
158
|
+
* docs/desktop-cli-api.md) as JSON may print them, six bytes a byte (the kernel reads a control character as text,
|
|
159
|
+
* and JSON escapes it as `\u0001`): 18 MiB, beside the two AGENTS.md (200,000 characters each, sixfold too) and the
|
|
160
|
+
* rest of the answer, with room to spare. */
|
|
161
|
+
export const SKILLS_INSPECT_MAX_BUFFER = 32 * 1024 * 1024;
|
|
162
|
+
|
|
163
|
+
function runJson(bin, argv, { cwd, exec, timeout = ENVELOPE_TIMEOUT_MS, parse = parseEnvelope, strictExit = false, detached = false, maxBuffer = ENVELOPE_MAX_BUFFER } = {}) {
|
|
155
164
|
const run = exec ?? (detached ? execFileInSession : execFile);
|
|
156
165
|
return new Promise((resolveP, rejectP) => {
|
|
157
166
|
try {
|
|
158
|
-
run(bin, argv, { cwd, encoding: "utf8", timeout, maxBuffer
|
|
167
|
+
run(bin, argv, { cwd, encoding: "utf8", timeout, maxBuffer, shell: false, ...(detached ? { detached: true } : {}) },
|
|
159
168
|
(err, stdout) => {
|
|
160
169
|
// New reads require a clean exit for success. Keep the historical
|
|
161
170
|
// envelope-wins policy for existing mutations unless opted in.
|
|
@@ -616,9 +625,26 @@ export function operationArgs(args) {
|
|
|
616
625
|
if (entries.length > 8 || entries.some(([k, v]) => !/^[a-z][a-z0-9-]{0,63}$/.test(k) || typeof v !== 'string' || !v || v.length > 1024 || /[\x00-\x1f\x7f]/.test(v))) return null;
|
|
617
626
|
return entries.flatMap(([k, v]) => ['--arg', `${k}=${v}`]);
|
|
618
627
|
}
|
|
628
|
+
/** An instance's colour (feature instance-color, awebai/oats#1421 §2): `oats instance color <instance>
|
|
629
|
+
* (<color> | --clear) --home <home> (--dir <context> | --server <server>) --json`, addressed as `oats
|
|
630
|
+
* instance stop` is (lifecycle-cli.mjs: a routed command never carries --dir). `color` is a palette name
|
|
631
|
+
* (soul-colors.mjs SOUL_COLORS) or null to clear; anything else is refused here and nothing runs. A read's
|
|
632
|
+
* deadline: 30 s, 45 s routed. The envelope comes back as the kernel printed it; the caller decodes it. */
|
|
633
|
+
export async function cliInstanceColor(bin, { instance, home, context, server, color }, io = {}) {
|
|
634
|
+
const fail = code => ({ schemaVersion: 1, ok: false, error: { code } });
|
|
635
|
+
if (typeof bin !== "string" || !isAbsolute(bin) || typeof instance !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(instance)
|
|
636
|
+
|| typeof home !== "string" || !isAbsolute(home) || home.includes("\0") || !(color === null || SOUL_COLORS.includes(color))
|
|
637
|
+
|| (server !== undefined ? !/^[a-z0-9][a-z0-9-]{0,63}$/.test(server ?? "") : typeof context !== "string" || !isAbsolute(context))) return fail("E_BAD_ARGS");
|
|
638
|
+
const argv = ["instance", "color", instance, ...(color === null ? ["--clear"] : [color]), "--home", home,
|
|
639
|
+
...(server !== undefined ? ["--server", server] : ["--dir", context]), "--json"];
|
|
640
|
+
const limit = server !== undefined ? 45_000 : 30_000;
|
|
641
|
+
return runJson(bin, argv, { cwd: server !== undefined ? io.cwd : context, exec: io.exec, strictExit: true,
|
|
642
|
+
timeout: Number.isFinite(io.timeout) && io.timeout > 0 ? Math.min(io.timeout, limit) : limit });
|
|
643
|
+
}
|
|
644
|
+
|
|
619
645
|
/** `maxAge` (feature observe-max-age) is inspect's alone; `features` is the probe's list and
|
|
620
|
-
* gates the flags (also `instructions` and `
|
|
621
|
-
export async function cliCapability(bin, { action, context, server, soul, agentsRoot, home, operation, args, localCwd, maxAge, instructions = false, skills = false, features }, io = {}) {
|
|
646
|
+
* gates the flags (also `instructions`, `skills` and `composedSkills`), so an undeclared kernel gets the flagless argv even when a value is given. */
|
|
647
|
+
export async function cliCapability(bin, { action, context, server, soul, agentsRoot, home, operation, args, localCwd, maxAge, instructions = false, skills = false, composedSkills = false, features }, io = {}) {
|
|
622
648
|
const bad = message => { throw Object.assign(new Error(message), { code: 'E_BAD_ARGS' }); };
|
|
623
649
|
const value = (v, label) => {
|
|
624
650
|
if (typeof v !== 'string' || !v || v.startsWith('-') || v.includes('\0')) bad(`Invalid ${label}`);
|
|
@@ -652,7 +678,13 @@ export async function cliCapability(bin, { action, context, server, soul, agents
|
|
|
652
678
|
// way; routed, the caller asks only for a host whose roster row names soul-skills (composed-gate.mjs hostReportsSkills).
|
|
653
679
|
if (skills && (action !== 'inspect' || !soul || home)) bad('Skills belong to a soul inspection');
|
|
654
680
|
const skillsArgv = skills && Array.isArray(features) && features.includes('soul-skills') ? ['--skills'] : [];
|
|
655
|
-
|
|
681
|
+
// --composed-skills (feature soul-composed-skills) adds every skill a spawn gives the instance (souls[0].composedSkills):
|
|
682
|
+
// inspect --soul only, gated the same way; routed, only for a host whose roster row names it (hostComposesSkills).
|
|
683
|
+
if (composedSkills && (action !== 'inspect' || !soul || home)) bad('Composed skills belong to a soul inspection');
|
|
684
|
+
const composedSkillsArgv = composedSkills && Array.isArray(features) && features.includes('soul-composed-skills') ? ['--composed-skills'] : [];
|
|
685
|
+
return await runJson(bin, [...argv, ...target, ...composed, ...skillsArgv, ...composedSkillsArgv, ...maxAgeArgv(features, maxAge), '--json'], {
|
|
656
686
|
cwd: localCwd, exec: io.exec, timeout: io.timeout ?? (action === 'run' ? 300_000 : ENVELOPE_TIMEOUT_MS),
|
|
687
|
+
// The skills' text makes the answer larger than any other read: an allowance of its own, still bounded.
|
|
688
|
+
maxBuffer: skillsArgv.length || composedSkillsArgv.length ? SKILLS_INSPECT_MAX_BUFFER : ENVELOPE_MAX_BUFFER,
|
|
657
689
|
});
|
|
658
690
|
}
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
// Every candidate is canonicalized to an absolute executable and accepted
|
|
14
14
|
// ONLY if executable and `<bin> version --json` returns the v1 probe:
|
|
15
15
|
// {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
|
|
16
|
-
// Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.
|
|
16
|
+
// Desktop accepts desktopApi === 1 and semver >=0.26.0 <0.68.0 (the band is
|
|
17
17
|
// spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
|
|
18
18
|
// API version — not source adjacency — is authoritative.
|
|
19
19
|
//
|
|
@@ -52,7 +52,7 @@ export const DESKTOP_API = 1;
|
|
|
52
52
|
// carry a `description` for every kind and `<kind> update <id> --description`
|
|
53
53
|
// sets one (feature `automation-descriptions`, which gates the Desktop's
|
|
54
54
|
// summary writes). The Desktop v1 surface is otherwise unchanged.
|
|
55
|
-
export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0,
|
|
55
|
+
export const ACCEPT_RANGE = { min: [0, 26, 0], maxExclusive: [0, 68, 0] };
|
|
56
56
|
/** The band as humans read it — derived, never hand-spelled, so the probe
|
|
57
57
|
* rejection reason, the backend's /api status and the degradation card can
|
|
58
58
|
* never disagree with the numbers actually enforced above. */
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
/** When a soul field the host composes or reports is asked for: the composed AGENTS.md (feature
|
|
2
|
-
* soul-composed-instructions, `inspect --soul --instructions`)
|
|
3
|
-
* `inspect --soul --skills`, `souls[0].skills`)
|
|
2
|
+
* soul-composed-instructions, `inspect --soul --instructions`), the soul's own skills (feature soul-skills,
|
|
3
|
+
* `inspect --soul --skills`, `souls[0].skills`) and every skill a spawn gives its instance (feature
|
|
4
|
+
* soul-composed-skills, `inspect --soul --composed-skills`, `souls[0].composedSkills`). The one gate module for all three, shared by the renderer (whether the
|
|
4
5
|
* soul page asks) and the server (whether the ask reaches the CLI); DOM-free so the server can import it.
|
|
5
6
|
*
|
|
6
7
|
* A local soul: this computer's CLI advertises the feature. A routed soul (`--server`): the host answers, so this
|
|
@@ -11,6 +12,7 @@
|
|
|
11
12
|
* (`E_REMOTE_INCOMPATIBLE`) and never by probing: the roster row is the answer. */
|
|
12
13
|
export const COMPOSED_FEATURE = 'soul-composed-instructions';
|
|
13
14
|
export const SKILLS_FEATURE = 'soul-skills';
|
|
15
|
+
export const COMPOSED_SKILLS_FEATURE = 'soul-composed-skills';
|
|
14
16
|
export const PROBE_FEATURES_FEATURE = 'server-probe-features';
|
|
15
17
|
|
|
16
18
|
const advertises = (cli, feature) => !!cli?.ok && Array.isArray(cli.features) && cli.features.includes(feature);
|
|
@@ -32,3 +34,9 @@ export const skillsSupported = cli => advertises(cli, SKILLS_FEATURE);
|
|
|
32
34
|
export const routedSkillsSupported = cli => skillsSupported(cli) && advertises(cli, PROBE_FEATURES_FEATURE);
|
|
33
35
|
/** A roster group's host reports a soul's skills: its last roster read succeeded and its own list names the feature. */
|
|
34
36
|
export const hostReportsSkills = (cli, group) => routedSkillsSupported(cli) && hostAdvertises(group, SKILLS_FEATURE);
|
|
37
|
+
/** This computer's CLI lists every skill a spawn of a soul gives its instance, capabilities' included. */
|
|
38
|
+
export const composedSkillsSupported = cli => advertises(cli, COMPOSED_SKILLS_FEATURE);
|
|
39
|
+
/** This computer's CLI can route the composed-skills request and relays the hosts' own feature lists in the roster. */
|
|
40
|
+
export const routedComposedSkillsSupported = cli => composedSkillsSupported(cli) && advertises(cli, PROBE_FEATURES_FEATURE);
|
|
41
|
+
/** A roster group's host lists composed skills: its last roster read succeeded and its own list names the feature. */
|
|
42
|
+
export const hostComposesSkills = (cli, group) => routedComposedSkillsSupported(cli) && hostAdvertises(group, COMPOSED_SKILLS_FEATURE);
|
|
@@ -9,6 +9,7 @@ import { launchOf, REPORT_FROM } from './launch-contract.mjs';
|
|
|
9
9
|
import { readIdentity } from './workspace-views.mjs';
|
|
10
10
|
import { waitingOnYouData } from './waiting-on-you.mjs';
|
|
11
11
|
import { retireData } from './retire-state.mjs';
|
|
12
|
+
import { instanceColor } from './instance-presentation.mjs';
|
|
12
13
|
const text = value => typeof value === 'string' && value.length <= 8192 && !value.includes('\0');
|
|
13
14
|
const absolute = value => text(value) && isAbsolute(value) && resolve(value) === value;
|
|
14
15
|
const own = (value, key) => Object.hasOwn(value, key);
|
|
@@ -214,6 +215,10 @@ export function deploymentStatusData(document, deployment) {
|
|
|
214
215
|
// check()ed: a value out of the contract is dropped and the row reads as if it had none.
|
|
215
216
|
if (own(instance, 'retire')) { const retire = retireData(instance.retire); if (retire) row.retire = retire; }
|
|
216
217
|
if (own(instance, 'rollbackIncomplete')) row.rollbackIncomplete = true;
|
|
218
|
+
// Feature instance-color: the instance's colour, a palette name exactly (instance-presentation.mjs
|
|
219
|
+
// instanceColor, the one rule of which colour a row shows). Validated, never check()ed: anything
|
|
220
|
+
// else is dropped and the row reads as one with no colour.
|
|
221
|
+
if (own(instance, 'color') && instanceColor(instance) !== null) row.color = instanceColor(instance);
|
|
217
222
|
// #802 (feature worktree-event): a spawn running its worktree hooks, verifiably alive. Boolean true only;
|
|
218
223
|
// any other value is dropped, never checked: the row stays an ordinary one.
|
|
219
224
|
if (own(instance, 'spawnInProgress') && instance.spawnInProgress === true) row.spawnInProgress = true;
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
/** A deployment's workspace identity, read before a client serves it (#482): the `workspace` object of
|
|
2
|
+
* `oats status --dir <path> --json`, the read an observed deployment gets, so a deployment of this
|
|
3
|
+
* computer's list can be matched to its workspace (panel-views.mjs `listedViews`) before it is opened.
|
|
4
|
+
* One read, bounded as every deployment read is (deployment-read-cli.mjs: its time and size limits), and
|
|
5
|
+
* projected by the observer's own projection (deployment-data.mjs `deploymentStatusData`): nothing of the
|
|
6
|
+
* answer but its `workspace` object is kept. No retry and no cache: what the answers become is the
|
|
7
|
+
* caller's (`held.learned`, panel-views.mjs). */
|
|
8
|
+
import { cliDeploymentRead } from './deployment-read-cli.mjs';
|
|
9
|
+
import { deploymentStatusData } from './deployment-data.mjs';
|
|
10
|
+
import { deploymentFailure } from './deployment-contract.mjs';
|
|
11
|
+
|
|
12
|
+
/** Whether a kernel record (cli-locator.mjs) reports workspace identities at all: without the feature
|
|
13
|
+
* no read can match anything, and a client makes none. */
|
|
14
|
+
export const identityReadable = (cli) => cli?.ok === true && Array.isArray(cli.features) && cli.features.includes('workspace-identity');
|
|
15
|
+
|
|
16
|
+
/** The answer for a read its caller's total budget ended, or one that never began before it ended: timed
|
|
17
|
+
* out, as a read past its own time limit answers. */
|
|
18
|
+
export const identityTimedOut = () => deploymentFailure('E_CLI_TIMEOUT');
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Read the identity of deployment `path` (absolute, canonical: a row of this computer's list).
|
|
22
|
+
* `options.maxAge` rides on the read as it does on an observation's; `io` is cliDeploymentRead's
|
|
23
|
+
* (`exec`, `env`).
|
|
24
|
+
* @returns {Promise<{ ok: true, workspace: object | null } | { ok: false, reason: { code, message, origin? } }>}
|
|
25
|
+
* `workspace` is the projected `workspace` object (deployment-data.mjs: its reachability and, with
|
|
26
|
+
* feature workspace-identity, the identity fields, or `identityInvalid`), null when the kernel reported
|
|
27
|
+
* none; a failure is the reader's reason as it came, or the projection's code. Never rejected.
|
|
28
|
+
*/
|
|
29
|
+
export async function cliDeploymentIdentity(cli, path, options = {}, io = {}) {
|
|
30
|
+
let answer;
|
|
31
|
+
try {
|
|
32
|
+
answer = await cliDeploymentRead(cli, { action: 'status', context: path, ...(options.maxAge !== undefined ? { maxAge: options.maxAge } : {}) }, io);
|
|
33
|
+
} catch { return deploymentFailure('E_CLI_FAILED'); }
|
|
34
|
+
if (!answer?.ok) return answer?.reason ? { ok: false, reason: answer.reason } : deploymentFailure('E_CLI_PROTOCOL');
|
|
35
|
+
try {
|
|
36
|
+
return { ok: true, workspace: deploymentStatusData(answer.document, path).workspace ?? null };
|
|
37
|
+
} catch (error) {
|
|
38
|
+
return deploymentFailure(error?.code === 'E_DEPLOYMENT_SCOPE' ? 'E_DEPLOYMENT_SCOPE' : 'E_CLI_PROTOCOL');
|
|
39
|
+
}
|
|
40
|
+
}
|
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
* test/inventory.test.mjs holds that its page reaches no module that imports a Node builtin. */
|
|
13
13
|
import { dirname } from 'node:path';
|
|
14
14
|
import { livenessOrigin } from './liveness.mjs';
|
|
15
|
-
import { knownOrigin, hasRuntimeError, byRuntimeState } from './instance-presentation.mjs';
|
|
15
|
+
import { knownOrigin, hasRuntimeError, byRuntimeState, instanceColor } from './instance-presentation.mjs';
|
|
16
16
|
import { retireData } from './retire-state.mjs';
|
|
17
17
|
|
|
18
18
|
const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
|
|
@@ -108,6 +108,8 @@ export function panelInstance(i) {
|
|
|
108
108
|
// Needs input (PR K): the validated claim (or null, unknown) as status reported it; absent stays absent.
|
|
109
109
|
// The client's liveness is merged before projection, so running/runtimeState beside it are the probe's.
|
|
110
110
|
...(i.waitingOnYou !== undefined ? { waitingOnYou: i.waitingOnYou } : {}),
|
|
111
|
+
// Feature instance-color: the row's colour as instanceColor reads it, present only when it is one.
|
|
112
|
+
...(instanceColor(i) !== null ? { color: instanceColor(i) } : {}),
|
|
111
113
|
team: i.team || null,
|
|
112
114
|
};
|
|
113
115
|
}
|
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
* maxAge seconds the kernel may reuse remote observations on a miss (a local inspect only)
|
|
10
10
|
* exec how the CLI is run (cli-adapter.mjs `runJson`'s `io.exec`); without it, execFile
|
|
11
11
|
*
|
|
12
|
-
* request { action: 'inspect', selector: { soul, agentsRoot } | { home }, refresh?, instructions?, skills? }
|
|
12
|
+
* request { action: 'inspect', selector: { soul, agentsRoot } | { home }, refresh?, instructions?, skills?, composedSkills? }
|
|
13
13
|
* context { workspace, cli, agents, instances, localCwd, catalogKey }
|
|
14
14
|
*
|
|
15
15
|
* It resolves the kernel's result with `observedAt` and `refreshing`, and throws an Error with a stable `code`
|
|
@@ -28,7 +28,7 @@ import { cliCapability, operationArgs } from './cli-adapter.mjs';
|
|
|
28
28
|
import { inspectKey } from './inspect-cache.mjs';
|
|
29
29
|
import { observationData } from './deployment-data.mjs';
|
|
30
30
|
import { OBSERVE_MAX_AGE_FEATURE } from './deployment-contract.mjs';
|
|
31
|
-
import { hostComposes, hostReportsSkills } from './composed-gate.mjs';
|
|
31
|
+
import { hostComposes, hostReportsSkills, hostComposesSkills } from './composed-gate.mjs';
|
|
32
32
|
import { canAddressRemote, unaddressableSentence, hostReason, shownLabel, unroutableReason } from './remote-address.mjs';
|
|
33
33
|
|
|
34
34
|
const fail = (message, code = 'E_BAD_ARGS') => { throw Object.assign(new Error(message), { code }); };
|
|
@@ -37,7 +37,7 @@ const TEAM_LABEL = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
|
|
|
37
37
|
|
|
38
38
|
/** Admit a capability request in its context, or throw. `actions`: the actions the caller serves (an inspect
|
|
39
39
|
* boundary serves only 'inspect'); any other is the same refusal as an unknown one. Returns what the call needs:
|
|
40
|
-
* `{ action, server, label, refresh, instructions, skills, soul, agentsRoot, home, context, key }`, where
|
|
40
|
+
* `{ action, server, label, refresh, instructions, skills, composedSkills, soul, agentsRoot, home, context, key }`, where
|
|
41
41
|
* `context` is the --dir the CLI runs in and `key` the inspect cache's key for the subject. */
|
|
42
42
|
export function capabilityAdmission(request, { workspace, cli, agents = [], instances = [], catalogKey = null }, actions = ['inspect', 'run']) {
|
|
43
43
|
if (!workspace) fail('Select a known workspace', 'E_WORKSPACE_UNKNOWN');
|
|
@@ -74,6 +74,10 @@ export function capabilityAdmission(request, { workspace, cli, agents = [], inst
|
|
|
74
74
|
// reports them (composed-gate.mjs hostReportsSkills); otherwise it is dropped and the read is today's.
|
|
75
75
|
if (request.skills !== undefined && (action !== 'inspect' || typeof request.skills !== 'boolean' || selector.soul === undefined)) fail('Invalid skills flag');
|
|
76
76
|
const skills = request.skills === true && (!server || hostReportsSkills(cli, workspace.group));
|
|
77
|
+
// composedSkills (feature soul-composed-skills): every skill a spawn gives the instance (`souls[0].composedSkills`),
|
|
78
|
+
// the same way again: inspect of a soul only; routed only when the held row says the host lists them (hostComposesSkills).
|
|
79
|
+
if (request.composedSkills !== undefined && (action !== 'inspect' || typeof request.composedSkills !== 'boolean' || selector.soul === undefined)) fail('Invalid composed skills flag');
|
|
80
|
+
const composedSkills = request.composedSkills === true && (!server || hostComposesSkills(cli, workspace.group));
|
|
77
81
|
let soul, agentsRoot, home, key;
|
|
78
82
|
let context = workspace.scope;
|
|
79
83
|
if (selector.home !== undefined) {
|
|
@@ -95,17 +99,17 @@ export function capabilityAdmission(request, { workspace, cli, agents = [], inst
|
|
|
95
99
|
const agent = matches[0];
|
|
96
100
|
soul = agent.name; agentsRoot = agent.agentsRoot;
|
|
97
101
|
context = dirname(agentsRoot);
|
|
98
|
-
key = inspectKey({ deployment: workspace.scope, server, kind: 'soul', soul, agentsRoot, catalogKey, instructions, skills });
|
|
102
|
+
key = inspectKey({ deployment: workspace.scope, server, kind: 'soul', soul, agentsRoot, catalogKey, instructions, skills, composedSkills });
|
|
99
103
|
} else fail('Select a soul or an instance home (inspection has no scope subject)');
|
|
100
|
-
return { action, server, label, refresh, instructions, skills, soul, agentsRoot, home, context, key };
|
|
104
|
+
return { action, server, label, refresh, instructions, skills, composedSkills, soul, agentsRoot, home, context, key };
|
|
101
105
|
}
|
|
102
106
|
|
|
103
107
|
/** The CLI call's options for an admitted request (cli-adapter.mjs `cliCapability`). */
|
|
104
|
-
export function capabilityCall(request, { action, server, refresh, instructions, skills, soul, agentsRoot, home, context }, { workspace, cli, localCwd, maxAge }) {
|
|
108
|
+
export function capabilityCall(request, { action, server, refresh, instructions, skills, composedSkills, soul, agentsRoot, home, context }, { workspace, cli, localCwd, maxAge }) {
|
|
105
109
|
return {
|
|
106
110
|
action, context, server, soul, agentsRoot, home,
|
|
107
111
|
operation: request.operation, ...(request.args !== undefined ? { args: request.args } : {}), ...(instructions ? { instructions } : {}),
|
|
108
|
-
...(skills ? { skills } : {}),
|
|
112
|
+
...(skills ? { skills } : {}), ...(composedSkills ? { composedSkills } : {}),
|
|
109
113
|
localCwd: server ? localCwd : context || workspace.scope,
|
|
110
114
|
// --max-age travels only on a LOCAL inspect (reuse is local only: the kernel refuses it with --server)
|
|
111
115
|
// and only when the probe declared observe-max-age (the adapter's call).
|
|
@@ -19,11 +19,11 @@ export const INSPECT_CACHE_TTL_MS = HELD_TTL_MS;
|
|
|
19
19
|
/** Every field travels, absent ones as null: two subjects that differ in any
|
|
20
20
|
coordinate never share an entry (same soul name under two agents roots, the
|
|
21
21
|
same home before and after a restart, a catalog that changed under a soul). */
|
|
22
|
-
export function inspectKey({ deployment, server = null, kind, soul, agentsRoot, catalogKey, home, instance, identity, instructions = false, skills = false }) {
|
|
22
|
+
export function inspectKey({ deployment, server = null, kind, soul, agentsRoot, catalogKey, home, instance, identity, instructions = false, skills = false, composedSkills = false }) {
|
|
23
23
|
if (kind !== 'soul' && kind !== 'home') throw Object.assign(new Error('Inspect cache keys name a soul or a home'), { code: 'E_BAD_ARGS' });
|
|
24
24
|
const part = value => value === undefined ? null : value;
|
|
25
25
|
return JSON.stringify([part(deployment), part(server), kind, part(soul), part(agentsRoot), part(catalogKey), part(home), part(instance),
|
|
26
|
-
Array.isArray(identity) ? identity.map(part) : part(identity), instructions === true, skills === true]);
|
|
26
|
+
Array.isArray(identity) ? identity.map(part) : part(identity), instructions === true, skills === true, composedSkills === true]);
|
|
27
27
|
}
|
|
28
28
|
|
|
29
29
|
export function createInspectCache({ limit = INSPECT_CACHE_LIMIT, ttlMs = INSPECT_CACHE_TTL_MS, now = () => Date.now() } = {}) {
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
/** The instance-name rule a typed name follows before it reaches `oats spawn --name`: the soul's role is its
|
|
2
|
+
* suffix. One copy for the clients (the Desktop's spawn dialog today); the kernel keeps its own for the
|
|
3
|
+
* suggestion it will make, and test/client-instance-name.test.mjs pins the cases both must agree on.
|
|
4
|
+
*
|
|
5
|
+
* A soul's role is the last word of its name: `oats-desktop-expert` → `expert`, `code-reviewer` → `reviewer`,
|
|
6
|
+
* `cloner` → `cloner`. A package qualifier is dropped first (what follows the last `/` or `--`, as the
|
|
7
|
+
* identity marks read a name: renderer/identity-marks.mjs markText), so `acme-pkg--keeper` → `keeper`.
|
|
8
|
+
* A typed name gets the role once: `desktop-improvements` → `desktop-improvements-expert`, while
|
|
9
|
+
* `desktop-improvements-expert` and `expert` stay as typed. Nothing here validates a name: the
|
|
10
|
+
* kernel owns that grammar and refuses a name that breaks it (E_INSTANCE_NAME_INVALID).
|
|
11
|
+
* DOM-free and import-free, with no module state. */
|
|
12
|
+
|
|
13
|
+
/** The role of a soul name: its last `-`-separated word after any package qualifier; '' when there is none. */
|
|
14
|
+
export function soulRole(soulName) {
|
|
15
|
+
if (typeof soulName !== 'string') return '';
|
|
16
|
+
const slash = soulName.lastIndexOf('/'), dashes = soulName.lastIndexOf('--');
|
|
17
|
+
const bare = soulName.slice(Math.max(slash < 0 ? 0 : slash + 1, dashes < 0 ? 0 : dashes + 2));
|
|
18
|
+
return bare.slice(bare.lastIndexOf('-') + 1);
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** `name` with the role of `soulName` as its suffix, unless it already ends in `-<role>` or is the role itself;
|
|
22
|
+
* the name as given when the soul has no role, and '' for no name (the kernel numbers it). */
|
|
23
|
+
export function nameWithRole(name, soulName) {
|
|
24
|
+
if (typeof name !== 'string' || !name) return '';
|
|
25
|
+
const role = soulRole(soulName);
|
|
26
|
+
if (!role || name === role || name.endsWith(`-${role}`)) return name;
|
|
27
|
+
return `${name}-${role}`;
|
|
28
|
+
}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { HERDR_REMOVED } from "./terminal-contract.mjs";
|
|
2
2
|
import { requireTerms } from './client-terms.mjs';
|
|
3
|
+
import { SOUL_COLORS } from './soul-colors.mjs';
|
|
3
4
|
|
|
4
5
|
export function runtimeState(instance) {
|
|
5
6
|
return instance.running === true ? "running" : instance.running === false ? "stopped" : "unknown";
|
|
@@ -15,6 +16,16 @@ export function byRuntimeState(a, b) {
|
|
|
15
16
|
return RUNTIME_ORDER[runtimeState(a)] - RUNTIME_ORDER[runtimeState(b)] || String(a.instance).localeCompare(String(b.instance));
|
|
16
17
|
}
|
|
17
18
|
|
|
19
|
+
/** Which colour an instance's row shows (feature instance-color, awebai/oats#1421 §2): the row's own `color`
|
|
20
|
+
* when it is a palette name exactly (soul-colors.mjs SOUL_COLORS, which the kernel's INSTANCE_COLORS equals),
|
|
21
|
+
* else null, and null draws the row as it looks without one. The one rule every client draws by: the kernel
|
|
22
|
+
* already validated what it relays, and anything else a row carries is no colour. Colour never says a
|
|
23
|
+
* state alone: a client's mark keeps the state by its shape. */
|
|
24
|
+
export function instanceColor(row) {
|
|
25
|
+
const color = row?.color;
|
|
26
|
+
return typeof color === 'string' && SOUL_COLORS.includes(color) ? color : null;
|
|
27
|
+
}
|
|
28
|
+
|
|
18
29
|
/** The words for an instance's siblings (#1312; the list `instanceSiblings` answers, instance-tree.mjs):
|
|
19
30
|
* null for none, else `sibling of a`, `sibling of a and b`, `sibling of a, b and c`, the names in the
|
|
20
31
|
* order given. The same in every client. */
|
|
@@ -1,23 +1,32 @@
|
|
|
1
|
-
/** The keys both clients share: the leader, the table read after it,
|
|
2
|
-
* of instances. Written down once, here; the Desktop
|
|
3
|
-
*
|
|
4
|
-
* test/keymap
|
|
1
|
+
/** The keys both clients share: the leader, the table read after it, the plain keys of the list
|
|
2
|
+
* of instances, the chords, and the palette's own keys. Written down once, here; the Desktop and the TUI read their defaults
|
|
3
|
+
* from it (packages/tui/lib/actions.mjs LEADER is LEADER_TABLE, and the TUI's test
|
|
4
|
+
* packages/tui/test/keymap.test.mjs fails on a `does` the TUI does not handle).
|
|
5
5
|
*
|
|
6
6
|
* Pure data and readers: no state, no DOM, no imports. Every value is frozen.
|
|
7
7
|
*
|
|
8
8
|
* Key ids are the TUI's spelling (packages/tui/lib/term/keys.mjs keyId): one character as itself,
|
|
9
9
|
* case kept (`n`, `N`, `|`, `?`, `/`, `-`); named keys `up` `down` `left` `right` `tab` `escape`
|
|
10
|
-
* `space` `enter` `home` `end` `pageup` `pagedown`; modifiers as `ctrl+` / `alt+`
|
|
10
|
+
* `space` `enter` `home` `end` `pageup` `pagedown`; modifiers as `ctrl+` / `alt+` / `shift+`
|
|
11
|
+
* prefixes, in that order. A chord adds two: `shift+` with Ctrl or Alt and a letter or an arrow
|
|
12
|
+
* (`ctrl+alt+shift+e`, `alt+shift+up`), and `cmd+`, first, for macOS's Command (`cmd+k`, the
|
|
13
|
+
* Desktop's ⌘K), which a terminal never passes to a program.
|
|
11
14
|
*
|
|
12
|
-
* leaderKey(isMac)
|
|
13
|
-
* leaderDoes(key)
|
|
14
|
-
* plainKeys(does)
|
|
15
|
-
* leaderRows()
|
|
15
|
+
* leaderKey(isMac) -> the leader's key id on that platform "ctrl+x" on both
|
|
16
|
+
* leaderDoes(key) -> what the leader then does for a key id, or null
|
|
17
|
+
* plainKeys(does) -> the plain key ids of an action (empty when it has none)
|
|
18
|
+
* leaderRows() -> LEADER_TABLE
|
|
19
|
+
* chordKey(does, isMac, family) -> the chord's key id on that platform and in that family, or null
|
|
20
|
+
* chordKeyOf(entry, isMac, family) -> the same for a CHORDS row
|
|
21
|
+
* paletteKey(does, isMac) -> the palette's own key id on that platform, or null
|
|
16
22
|
*
|
|
17
23
|
* `does` names an action, not a client's code: each client maps it to its own. */
|
|
18
24
|
|
|
19
|
-
/** The leader per platform: Ctrl
|
|
20
|
-
|
|
25
|
+
/** The leader per platform: Ctrl+X on both, as Emacs has it (#1433). Without the kitty keyboard
|
|
26
|
+
* protocol it is one byte, 0x18, in every terminal; pressed twice it sends that byte to the program
|
|
27
|
+
* (the shell's Ctrl+X Ctrl+E, nano's exit). The Desktop leaves it to Cut in an editable field on
|
|
28
|
+
* Linux and Windows (packages/desktop/docs/desktop-keyboard.md, "The leader"). */
|
|
29
|
+
export const LEADER = Object.freeze({ mac: "ctrl+x", other: "ctrl+x" });
|
|
21
30
|
|
|
22
31
|
/** The keys read after the leader, in the TUI's order, and what each does. `terminal`: named in
|
|
23
32
|
* the hint only while a terminal is open. The leader pressed twice is not here: it is the user's
|
|
@@ -82,6 +91,66 @@ export const PLAIN_KEYS = Object.freeze([
|
|
|
82
91
|
{ does: "help", keys: ["?"] },
|
|
83
92
|
].map((entry) => Object.freeze({ ...entry, keys: Object.freeze([...entry.keys]) })));
|
|
84
93
|
|
|
94
|
+
/** The chords: one key that does what the leader then a key does, from every focus, the same in
|
|
95
|
+
* both clients, per platform (`mac`, `other`). The Desktop's DEFAULT_KEYMAP reads these entries from
|
|
96
|
+
* here (CHORDS_READ, docs/desktop-keyboard.md); the TUI binds the `other` ones, and the `mac` ones
|
|
97
|
+
* without `cmd+`, from every focus (docs/tui.md, "Chords"). The leader stays the key that always
|
|
98
|
+
* works: help, the views and the acts (stop, restart, start, retire) are reached by it alone.
|
|
99
|
+
*
|
|
100
|
+
* One family, so that no terminal's own keys take them (the matrix in docs/tui.md, "Chords"):
|
|
101
|
+
* Ctrl+Alt with a letter or a digit for an action, Alt+Shift with the leader's arrow to move. On
|
|
102
|
+
* macOS the Desktop holds ⌘ (⌘⌥ for the rows new in phase 3). A Ctrl+Alt chord reaches the TUI only
|
|
103
|
+
* under the kitty keyboard protocol (ESC then Ctrl+K is what Ctrl+Alt+K sends without it); an
|
|
104
|
+
* Alt+Shift arrow has a sequence of its own (`CSI 1;4A`) and reaches it with or without. `tab-N`
|
|
105
|
+
* shows the Nth tab of the focused group, `tab-9` its last. The Desktop's Ctrl+Tab, Ctrl+1/2/3 (the
|
|
106
|
+
* stages) and Ctrl+, are the Desktop's own and are not here.
|
|
107
|
+
*
|
|
108
|
+
* `shift` is the row's key in the Ctrl+Shift family, the option a user picks in keys.json
|
|
109
|
+
* (packages/client/keys-file.mjs) for a terminal that passes Ctrl+Shift apart from Ctrl: foot and
|
|
110
|
+
* Alacritty (docs/tui.md, "Which family for my terminal"). Seven rows move (K palette, P spawn,
|
|
111
|
+
* S workspaces, M zoom, W close, E split right, D split down: the maintainer's cut, a43470ce); the
|
|
112
|
+
* others keep their `other` key in both families: the Alt+Shift arrows, since Ctrl+Shift+arrow
|
|
113
|
+
* selects text in inputs and editors; Ctrl+Alt+1–9, since Ctrl+Shift+digit is a shifted symbol on
|
|
114
|
+
* most layouts; group-next and filter, whose Ctrl+Shift A and F a terminal or an agent takes; and
|
|
115
|
+
* edit-instance, the Desktop's alone, Ctrl+Alt+R in both. macOS has no family: `mac` is the only key there. */
|
|
116
|
+
export const CHORDS = Object.freeze([
|
|
117
|
+
{ does: "palette", mac: "cmd+k", other: "ctrl+alt+k", shift: "ctrl+shift+k" },
|
|
118
|
+
{ does: "spawn", mac: "cmd+p", other: "ctrl+alt+p", shift: "ctrl+shift+p" },
|
|
119
|
+
{ does: "workspaces", mac: "cmd+alt+o", other: "ctrl+alt+o", shift: "ctrl+shift+s" },
|
|
120
|
+
{ does: "previous", mac: "cmd+alt+up", other: "alt+shift+up" },
|
|
121
|
+
{ does: "next", mac: "cmd+alt+down", other: "alt+shift+down" },
|
|
122
|
+
{ does: "tab-previous", mac: "cmd+alt+left", other: "alt+shift+left" },
|
|
123
|
+
{ does: "tab-next", mac: "cmd+alt+right", other: "alt+shift+right" },
|
|
124
|
+
...Array.from({ length: 9 }, (_, i) => ({ does: `tab-${i + 1}`, mac: `cmd+alt+${i + 1}`, other: `ctrl+alt+${i + 1}` })),
|
|
125
|
+
{ does: "zoom", mac: "cmd+alt+z", other: "ctrl+alt+z", shift: "ctrl+shift+m" },
|
|
126
|
+
{ does: "close-terminal", mac: "cmd+w", other: "ctrl+alt+w", shift: "ctrl+shift+w" },
|
|
127
|
+
{ does: "split-right", mac: "cmd+\\", other: "ctrl+alt+e", shift: "ctrl+shift+e" },
|
|
128
|
+
{ does: "split-down", mac: "cmd+shift+\\", other: "ctrl+alt+shift+e", shift: "ctrl+shift+d" },
|
|
129
|
+
{ does: "group-next", mac: "cmd+alt+a", other: "ctrl+alt+a" },
|
|
130
|
+
{ does: "filter", mac: "cmd+f", other: "ctrl+alt+f" },
|
|
131
|
+
// The Desktop's alone for now (#1421): its name and colour dialog. No leader key; the TUI has no
|
|
132
|
+
// such action, so it binds no key for it (chordKeys skips a `does` it does not handle). Not one of
|
|
133
|
+
// the seven the Ctrl+Shift family moves: Ctrl+Alt+R in both families (the maintainer's ruling).
|
|
134
|
+
{ does: "edit-instance", mac: "cmd+alt+r", other: "ctrl+alt+r" },
|
|
135
|
+
].map((entry) => Object.freeze({ ...entry, shift: entry.shift ?? entry.other })));
|
|
136
|
+
|
|
137
|
+
/** The palette's own keys, read only while the palette is open: there they win over every binding
|
|
138
|
+
* (the Desktop's ⌘N, `app.chooseSoul`; the chords `previous` and `next`), so they are not CHORDS,
|
|
139
|
+
* which are bound from every focus. The selection goes to the first row of the next group, or of
|
|
140
|
+
* the one before, and wraps (docs/tui.md, "The palette"; packages/desktop/docs/desktop-keyboard.md).
|
|
141
|
+
* On macOS the TUI has none: a terminal never passes ⌘. The previous group is ⌥⌘N, not ⇧⌘N: that is
|
|
142
|
+
* the Desktop's File → New Window, a key its menu shows, which the palette does not shadow. */
|
|
143
|
+
export const PALETTE_KEYS = Object.freeze([
|
|
144
|
+
{ does: "palette-next-group", mac: "cmd+n", other: "alt+shift+down" },
|
|
145
|
+
{ does: "palette-previous-group", mac: "cmd+alt+n", other: "alt+shift+up" },
|
|
146
|
+
].map((entry) => Object.freeze({ ...entry })));
|
|
147
|
+
|
|
148
|
+
/** The chord families on Linux and Windows: the default and the option (CHORDS `other` and `shift`),
|
|
149
|
+
* with the name a client shows for each. */
|
|
150
|
+
export const CHORD_FAMILIES = Object.freeze(["ctrl+alt", "ctrl+shift"]);
|
|
151
|
+
export const DEFAULT_CHORD_FAMILY = "ctrl+alt";
|
|
152
|
+
export const CHORD_FAMILY_LABELS = Object.freeze({ "ctrl+alt": "Ctrl+Alt", "ctrl+shift": "Ctrl+Shift" });
|
|
153
|
+
|
|
85
154
|
const NONE = Object.freeze([]);
|
|
86
155
|
|
|
87
156
|
/** The leader's key id on macOS (`true`) or elsewhere. */
|
|
@@ -104,3 +173,22 @@ export function plainKeys(does) {
|
|
|
104
173
|
export function leaderRows() {
|
|
105
174
|
return LEADER_TABLE;
|
|
106
175
|
}
|
|
176
|
+
|
|
177
|
+
/** The key id of the CHORDS row `entry` on macOS (`true`) or elsewhere, in `family` (CHORD_FAMILIES;
|
|
178
|
+
* anything else is the default), which macOS ignores. */
|
|
179
|
+
export function chordKeyOf(entry, isMac, family = DEFAULT_CHORD_FAMILY) {
|
|
180
|
+
return isMac ? entry.mac : family === "ctrl+shift" ? entry.shift : entry.other;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/** The key id of the chord that does `does` on macOS (`true`) or elsewhere, in `family` (chordKeyOf),
|
|
184
|
+
* or null when none does. */
|
|
185
|
+
export function chordKey(does, isMac, family = DEFAULT_CHORD_FAMILY) {
|
|
186
|
+
const entry = CHORDS.find((each) => each.does === does);
|
|
187
|
+
return entry === undefined ? null : chordKeyOf(entry, isMac, family);
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/** The key id of the palette's own key that does `does` on macOS (`true`) or elsewhere, or null. */
|
|
191
|
+
export function paletteKey(does, isMac) {
|
|
192
|
+
const entry = PALETTE_KEYS.find((each) => each.does === does);
|
|
193
|
+
return entry === undefined ? null : isMac ? entry.mac : entry.other;
|
|
194
|
+
}
|