docks-kit 0.22.13 → 0.22.22

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.
Files changed (57) hide show
  1. package/AGENTS.md +97 -83
  2. package/README.md +7 -7
  3. package/cli/docs/command-guards.md +12 -7
  4. package/cli/docs/flags.md +59 -9
  5. package/cli/docs/install.md +2 -2
  6. package/cli/docs/omp-context.md +27 -17
  7. package/cli/docs/omp-models.md +91 -70
  8. package/cli/docs/overview.md +1 -1
  9. package/cli/docs/platforms.md +4 -2
  10. package/cli/docs/plugins.md +8 -5
  11. package/cli/docs/sync-layers.md +6 -4
  12. package/cli/docs/toolchain.md +24 -14
  13. package/cli/src/argv.ts +7 -4
  14. package/cli/src/argvValidate.ts +2 -16
  15. package/cli/src/commands/docs.ts +1 -1
  16. package/cli/src/commands/omp.ts +81 -88
  17. package/cli/src/commands/sync.ts +6 -6
  18. package/cli/src/commands/tidy.ts +83 -26
  19. package/cli/src/engine-native/DESIGN.md +93 -56
  20. package/cli/src/engine-native/atomicWrite.ts +168 -8
  21. package/cli/src/engine-native/codexConfig.ts +2 -6
  22. package/cli/src/engine-native/codexPlugins.ts +1 -1
  23. package/cli/src/engine-native/codexSync.ts +137 -26
  24. package/cli/src/engine-native/codexToml.ts +4 -86
  25. package/cli/src/engine-native/deps.ts +51 -51
  26. package/cli/src/engine-native/exec.ts +3 -0
  27. package/cli/src/engine-native/harnesses.ts +5 -11
  28. package/cli/src/engine-native/index.ts +1 -1
  29. package/cli/src/engine-native/kitDb.ts +7 -7
  30. package/cli/src/engine-native/kitLock.ts +121 -0
  31. package/cli/src/engine-native/modes.ts +49 -31
  32. package/cli/src/engine-native/ompChild.ts +26 -0
  33. package/cli/src/engine-native/ompFastMode.ts +14 -7
  34. package/cli/src/engine-native/ompFileDeploy.ts +12 -6
  35. package/cli/src/engine-native/ompMarketplace.ts +25 -18
  36. package/cli/src/engine-native/ompOverlay.ts +23 -69
  37. package/cli/src/engine-native/ompPlugins.ts +23 -14
  38. package/cli/src/engine-native/ompRemovals.ts +97 -30
  39. package/cli/src/engine-native/ompSync.ts +66 -32
  40. package/cli/src/engine-native/os/targets.ts +16 -4
  41. package/cli/src/engine-native/os/types.ts +1 -1
  42. package/cli/src/engine-native/parseArgs.ts +27 -17
  43. package/cli/src/engine-native/processes.ts +16 -0
  44. package/cli/src/engine-native/scratch.ts +18 -0
  45. package/cli/src/engine-native/sharedTypes.d.ts +0 -2
  46. package/cli/src/engine-native/skillsInstall.ts +27 -2
  47. package/cli/src/engine-native/skillsPrune.ts +51 -49
  48. package/cli/src/engine-native/skillsRecords.ts +138 -0
  49. package/cli/src/engine-native/skillsSync.ts +16 -13
  50. package/cli/src/engine-native/syncDispatch.ts +186 -4
  51. package/cli/src/engine-native/tidy.ts +102 -119
  52. package/cli/src/engine-native/tomlLines.ts +92 -0
  53. package/cli/src/generated/sotPayload.ts +5 -5
  54. package/cli/src/main.ts +5 -30
  55. package/cli/src/manifests.ts +24 -4
  56. package/package.json +2 -2
  57. package/cli/src/engine-native/tidyLock.ts +0 -163
@@ -0,0 +1,121 @@
1
+ /**
2
+ * Kit locks: an SQLite `BEGIN IMMEDIATE` transaction on a dedicated database
3
+ * file. Only `node:` imports, so that a test child process can load this
4
+ * module alone.
5
+ *
6
+ * - The lock is the RESERVED lock of the transaction. At most one connection,
7
+ * in any process, holds it.
8
+ * - `BEGIN IMMEDIATE` takes RESERVED with no wait for other readers. With
9
+ * `BEGIN EXCLUSIVE`, two racers that each hold SHARED can both fail.
10
+ * - The OS releases the lock when the holder process ends for any reason. A
11
+ * paused holder keeps it.
12
+ * - The database stays in rollback journal mode. Never set WAL on a lock file.
13
+ * - A module-level set keeps each open connection, so that the garbage
14
+ * collector cannot close a lock that a caller dropped.
15
+ * - Only this module opens a lock file. Each run takes each lock once.
16
+ */
17
+ import { chmodSync, mkdirSync } from "node:fs";
18
+ import { dirname } from "node:path";
19
+ import { DatabaseSync } from "node:sqlite";
20
+ import { setTimeout as sleepMs } from "node:timers/promises";
21
+
22
+ /** The default time between two tries. */
23
+ const POLL_MS = 50;
24
+ /** SQLite primary result code SQLITE_BUSY: another connection holds a conflicting lock. */
25
+ const SQLITE_BUSY = 5;
26
+
27
+ export interface KitLockOptions {
28
+ /** Try until `now()` passes the start plus `waitMs`. 0 tries once, with no sleep. */
29
+ readonly waitMs: number;
30
+ /** The time between two tries. */
31
+ readonly pollMs?: number;
32
+ /** The clock in ms; `Date.now` by default. */
33
+ readonly now?: () => number;
34
+ /** The wait between two tries. */
35
+ readonly sleep?: (ms: number) => Promise<void>;
36
+ /**
37
+ * True by default: make the lock directory and set its mode to 0700. False
38
+ * for a lock in a folder that the caller made, so the folder keeps its mode.
39
+ */
40
+ readonly privateDirectory?: boolean;
41
+ }
42
+
43
+ /** A held lock. Give it to `releaseKitLock` exactly once. */
44
+ export interface KitLock {
45
+ readonly path: string;
46
+ readonly connection: DatabaseSync;
47
+ }
48
+
49
+ export type KitLockResult =
50
+ | { readonly kind: "acquired"; readonly lock: KitLock }
51
+ | { readonly kind: "held" };
52
+
53
+ /** The connection of each held lock. The garbage collector cannot close a connection in this set. */
54
+ const heldConnections = new Set<DatabaseSync>();
55
+
56
+ /** True for an SQLite error with the primary result code SQLITE_BUSY. */
57
+ function isBusy(cause: unknown): boolean {
58
+ if (typeof cause !== "object" || cause === null || !("errcode" in cause)) return false;
59
+ return typeof cause.errcode === "number" && (cause.errcode & 0xff) === SQLITE_BUSY;
60
+ }
61
+
62
+ /** Start the write transaction. False when another connection holds the lock. */
63
+ function tryBegin(connection: DatabaseSync): boolean {
64
+ try {
65
+ connection.exec("BEGIN IMMEDIATE");
66
+ return true;
67
+ } catch (cause) {
68
+ if (isBusy(cause)) return false;
69
+ throw cause;
70
+ }
71
+ }
72
+
73
+ /**
74
+ * Take the lock at `path`. Make its directory with mode 0700 when necessary,
75
+ * unless `privateDirectory` is false. Return `held` when another connection,
76
+ * in this process or in another process, keeps the lock past the wait bound.
77
+ */
78
+ export async function acquireKitLock(
79
+ path: string,
80
+ options: KitLockOptions,
81
+ ): Promise<KitLockResult> {
82
+ const now = options.now ?? Date.now;
83
+ const sleep = options.sleep ?? ((ms: number) => sleepMs(ms));
84
+ const pollMs = options.pollMs ?? POLL_MS;
85
+ const deadline = now() + options.waitMs;
86
+
87
+ if (options.privateDirectory !== false) {
88
+ const directory = dirname(path);
89
+ mkdirSync(directory, { recursive: true, mode: 0o700 });
90
+ chmodSync(directory, 0o700);
91
+ }
92
+ const connection = new DatabaseSync(path);
93
+ try {
94
+ // A busy lock must fail at once; this loop does the wait.
95
+ connection.exec("PRAGMA busy_timeout = 0");
96
+ for (;;) {
97
+ if (tryBegin(connection)) {
98
+ heldConnections.add(connection);
99
+ return { kind: "acquired", lock: { path, connection } };
100
+ }
101
+ const remaining = deadline - now();
102
+ if (remaining <= 0) break;
103
+ await sleep(Math.min(pollMs, remaining));
104
+ }
105
+ } catch (cause) {
106
+ connection.close();
107
+ throw cause;
108
+ }
109
+ connection.close();
110
+ return { kind: "held" };
111
+ }
112
+
113
+ /** Release the lock: end the transaction and close the connection. */
114
+ export function releaseKitLock(lock: KitLock): void {
115
+ heldConnections.delete(lock.connection);
116
+ try {
117
+ lock.connection.exec("ROLLBACK");
118
+ } finally {
119
+ lock.connection.close();
120
+ }
121
+ }
@@ -3,7 +3,7 @@
3
3
  * golden-tested messages, same exit codes.
4
4
  */
5
5
  import { p } from "./exec";
6
- import { readFileSync } from "node:fs";
6
+ import { existsSync, readFileSync } from "node:fs";
7
7
  import { payloadText } from "../payload";
8
8
 
9
9
  import { codexHome } from "./codexPaths";
@@ -14,12 +14,13 @@ import { isObject, parseJson, type Json } from "./jq";
14
14
  import { printModels, validateClaudeModel, validateCodexModel } from "./models";
15
15
  import { defaultLiveInputs, resolveCatalog } from "./liveModels";
16
16
  import { bunBootstrap } from "./bun";
17
+ import { withFolderLocks, withSyncLock } from "./syncDispatch";
17
18
  import { upgradeLspServers } from "./claudeLsp";
18
19
  import { belowFloor, field, installedVersion, outdatedReport, present, report } from "./toolchain";
19
20
  import { topLevelTomlString } from "../manifests";
20
21
 
21
22
  export async function modeModel(ctx: Ctx, args: ReadonlyArray<string>): Promise<number> {
22
- const { echo, err, warn } = ctx.services.logger;
23
+ const { err } = ctx.services.logger;
23
24
  let tool: "claude" | "codex" | "" = "";
24
25
  let value = "";
25
26
  for (const arg of args) {
@@ -36,39 +37,56 @@ export async function modeModel(ctx: Ctx, args: ReadonlyArray<string>): Promise<
36
37
  err("Usage: model <claude|codex> [value] [--dry-run]");
37
38
  return 2;
38
39
  }
40
+ if (value === "") return await showModel(ctx, tool);
41
+ // A write does the same read-modify-write of settings.json and config.toml as a sync.
42
+ return await withSyncLock(ctx, args, async () => {
43
+ // `model codex` writes config.toml in the Codex folder, which syncs of
44
+ // other homes can share. It creates no folder, so a missing one needs no lock.
45
+ const codexDir = codexHome(ctx.home);
46
+ const folders = tool === "codex" && existsSync(codexDir) ? [codexDir] : [];
47
+ return await withFolderLocks(ctx, folders, () => writeModel(ctx, tool, value));
48
+ });
49
+ }
50
+
51
+ /** Print the deployed model, the SoT model, and the model catalog of `tool`. */
52
+ async function showModel(ctx: Ctx, tool: "claude" | "codex"): Promise<number> {
53
+ const { echo, err, warn } = ctx.services.logger;
39
54
  const catalog = await resolveCatalog(tool, defaultLiveInputs(ctx.home));
40
- if (value === "") {
41
- if (tool === "claude") {
42
- const deployed = p(ctx.home, ".claude", "settings.json");
43
- const result = readConfig(deployed);
44
- if (result.kind === "missing") {
45
- warn("~/.claude/settings.json missing");
46
- return 0;
47
- }
48
- if (result.kind === "read-error") {
49
- err(`Failed to read ~/.claude/settings.json: ${String(result.error)}`);
50
- return 1;
51
- }
52
- echo(`deployed: ${jsonModelText(result.data)}`);
53
- echo(`SoT: ${jsonModelText(payloadText("SoT/.claude/settings.json"))}`);
54
- } else {
55
- const deployed = p(codexHome(ctx.home), "config.toml");
56
- const result = readConfig(deployed);
57
- if (result.kind === "missing") {
58
- warn(`${deployed} missing`);
59
- return 0;
60
- }
61
- if (result.kind === "read-error") {
62
- err(`Failed to read ${deployed}: ${String(result.error)}`);
63
- return 1;
64
- }
65
- echo(`deployed: ${topLevelTomlString(result.data, "model") ?? ""}`);
66
- echo(`SoT: ${topLevelTomlString(payloadText("SoT/.codex/config.toml"), "model") ?? ""}`);
55
+ if (tool === "claude") {
56
+ const deployed = p(ctx.home, ".claude", "settings.json");
57
+ const result = readConfig(deployed);
58
+ if (result.kind === "missing") {
59
+ warn("~/.claude/settings.json missing");
60
+ return 0;
67
61
  }
68
- printModels(ctx, catalog);
69
- return 0;
62
+ if (result.kind === "read-error") {
63
+ err(`Failed to read ~/.claude/settings.json: ${String(result.error)}`);
64
+ return 1;
65
+ }
66
+ echo(`deployed: ${jsonModelText(result.data)}`);
67
+ echo(`SoT: ${jsonModelText(payloadText("SoT/.claude/settings.json"))}`);
68
+ } else {
69
+ const deployed = p(codexHome(ctx.home), "config.toml");
70
+ const result = readConfig(deployed);
71
+ if (result.kind === "missing") {
72
+ warn(`${deployed} missing`);
73
+ return 0;
74
+ }
75
+ if (result.kind === "read-error") {
76
+ err(`Failed to read ${deployed}: ${String(result.error)}`);
77
+ return 1;
78
+ }
79
+ echo(`deployed: ${topLevelTomlString(result.data, "model") ?? ""}`);
80
+ echo(`SoT: ${topLevelTomlString(payloadText("SoT/.codex/config.toml"), "model") ?? ""}`);
70
81
  }
82
+ printModels(ctx, catalog);
83
+ return 0;
84
+ }
71
85
 
86
+ /** Validate `value` against the model catalog of `tool`, then write it. */
87
+ async function writeModel(ctx: Ctx, tool: "claude" | "codex", value: string): Promise<number> {
88
+ const { err } = ctx.services.logger;
89
+ const catalog = await resolveCatalog(tool, defaultLiveInputs(ctx.home));
72
90
  if (tool === "claude") {
73
91
  if (!validateClaudeModel(ctx, value, catalog)) {
74
92
  printModels(ctx, catalog);
@@ -0,0 +1,26 @@
1
+ /**
2
+ * The `omp` child processes of a sync. Every `omp` command that the
3
+ * marketplace and plugin passes run starts through `spawnOmp`, so each child
4
+ * writes into the data root that the sync locked.
5
+ */
6
+ import { spawnProcess, type AsyncProcessOptions, type AsyncProcessResult } from "./exec";
7
+ import type { OmpPaths } from "./ompPaths";
8
+
9
+ /**
10
+ * Run `omp args` pinned to the data root of `paths`, the root that the sync
11
+ * locked. omp adopts `$XDG_DATA_HOME/omp` as its data root once that folder
12
+ * exists, and another sync can create it after this sync took its locks.
13
+ * When the locked data root is the config root, the child gets no
14
+ * `XDG_DATA_HOME`, so its resolver keeps the config root. When the locked
15
+ * data root is the XDG root, the child gets the environment of this process.
16
+ */
17
+ export function spawnOmp(
18
+ paths: OmpPaths,
19
+ args: ReadonlyArray<string>,
20
+ stdio: AsyncProcessOptions["stdio"],
21
+ ): Promise<AsyncProcessResult> {
22
+ if (paths.dataRoot !== paths.configRoot) return spawnProcess("omp", args, { stdio });
23
+ const env = { ...process.env };
24
+ delete env["XDG_DATA_HOME"];
25
+ return spawnProcess("omp", args, { stdio, env });
26
+ }
@@ -4,9 +4,11 @@
4
4
  * OpenAI and OpenAI-Codex models; `none` omits `service_tier`. The SoT does not
5
5
  * declare `tier.openai`, so the additive sync merge keeps the toggled value.
6
6
  */
7
- import { chmodSync, existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
7
+ import { existsSync, readFileSync } from "node:fs";
8
8
  import { isMap, parseDocument } from "yaml";
9
9
 
10
+ import { replaceFile } from "./atomicWrite";
11
+
10
12
  export const FAST_ON_TIER = "priority";
11
13
  export const FAST_OFF_TIER = "none";
12
14
 
@@ -42,15 +44,20 @@ export function toggleOpenAiFast(configText: string): FastToggle {
42
44
  return { previous, next, text: doc.toString() };
43
45
  }
44
46
 
45
- /** Toggle `tier.openai` in the deployed config.yml with an atomic 0600 write. */
46
- export function toggleDeployedOpenAiFast(configPath: string): FastToggle {
47
+ /** Throw the error of the toggle when the deployed config.yml is missing. */
48
+ export function requireDeployedConfig(configPath: string): void {
47
49
  if (!existsSync(configPath)) {
48
50
  throw new Error(`${configPath} does not exist; run 'docks-kit sync omp' first`);
49
51
  }
52
+ }
53
+
54
+ /**
55
+ * Toggle `tier.openai` in the deployed config.yml with an atomic 0600 write.
56
+ * replaceFile writes through a symlinked config.yml, so the link stays.
57
+ */
58
+ export function toggleDeployedOpenAiFast(configPath: string): FastToggle {
59
+ requireDeployedConfig(configPath);
50
60
  const toggle = toggleOpenAiFast(readFileSync(configPath, "utf8"));
51
- const temporary = `${configPath}.tmp`;
52
- writeFileSync(temporary, toggle.text, { mode: 0o600 });
53
- chmodSync(temporary, 0o600);
54
- renameSync(temporary, configPath);
61
+ replaceFile(configPath, toggle.text, { mode: 0o600 });
55
62
  return toggle;
56
63
  }
@@ -36,7 +36,7 @@ function writePrivateFile(target: string, content: string): void {
36
36
  chmodSync(target, 0o600);
37
37
  }
38
38
 
39
- function backupPrivateFile(target: string): void {
39
+ export function backupPrivateFile(target: string): void {
40
40
  copyFileSync(target, `${target}.bak`);
41
41
  chmodSync(`${target}.bak`, 0o600);
42
42
  }
@@ -69,12 +69,17 @@ export function syncWholeFile(
69
69
  ctx.nextStepTriggers.ompRestart = true;
70
70
  }
71
71
 
72
+ /**
73
+ * Merges the SoT YAML into the deployed file. Returns true when this call wrote
74
+ * `<target>.bak`, so a later pass on the same file in this sync keeps that
75
+ * pre-sync backup instead of replacing it with the merged bytes.
76
+ */
72
77
  export function syncMergedYaml(
73
78
  ctx: Ctx,
74
79
  sourcePath: OmpTextPayloadPath,
75
80
  target: string,
76
81
  merge: (sotText: string, deployedText: string) => string,
77
- ): void {
82
+ ): boolean {
78
83
  const { change, echo, verbose } = ctx.services.logger;
79
84
  const source = payloadDisplayPath(sourcePath);
80
85
  const sotText = payloadText(sourcePath);
@@ -83,23 +88,23 @@ export function syncMergedYaml(
83
88
  if (!existsSync(target)) {
84
89
  if (ctx.dryRun) {
85
90
  echo(`[dry-run] cp ${source} -> ${target}`);
86
- return;
91
+ return false;
87
92
  }
88
93
  writePrivateFile(target, sotText);
89
94
  change(`omp ${name} installed`);
90
95
  ctx.nextStepTriggers.ompRestart = true;
91
- return;
96
+ return false;
92
97
  }
93
98
 
94
99
  const deployedText = readFileSync(target, "utf8");
95
100
  const merged = merge(sotText, deployedText);
96
101
  if (merged === deployedText) {
97
102
  verbose(`omp ${name} already in sync`);
98
- return;
103
+ return false;
99
104
  }
100
105
  if (ctx.dryRun) {
101
106
  echo(`[dry-run] merge ${source} -> ${target} (backup at ${target}.bak)`);
102
- return;
107
+ return false;
103
108
  }
104
109
 
105
110
  backupPrivateFile(target);
@@ -107,4 +112,5 @@ export function syncMergedYaml(
107
112
  replaceFile(target, merged, { mode: 0o600 });
108
113
  change(`omp ${name} merged (backup at ${name}.bak)`);
109
114
  ctx.nextStepTriggers.ompRestart = true;
115
+ return true;
110
116
  }
@@ -5,10 +5,12 @@
5
5
  */
6
6
  import { existsSync, readFileSync } from "node:fs";
7
7
 
8
- import { processFailureSummary, spawnProcess } from "./exec";
8
+ import { p, processFailureSummary } from "./exec";
9
9
  import { recordFailure } from "./failures";
10
10
  import type { Ctx } from "./index";
11
11
  import { isObject, parseJson } from "./jq";
12
+ import { spawnOmp } from "./ompChild";
13
+ import type { OmpPaths } from "./ompPaths";
12
14
 
13
15
  const MARKETPLACE_NAME = "docks";
14
16
  const MARKETPLACE_SOURCE = "https://github.com/DocksDocks/docks.git";
@@ -42,17 +44,16 @@ function registryHasDocks(registryFile: string): boolean {
42
44
  * the active registry lists docks, only the legacy registry lists it, or
43
45
  * neither does. In the middle state the kit never copies user data itself; it
44
46
  * takes the refresh path, whose own resolution inside omp performs that
45
- * adoption and leaves the active registry present.
47
+ * adoption and leaves the active registry present. `paths` are the omp paths
48
+ * that the sync locked.
46
49
  */
47
- export async function syncMarketplace(
48
- ctx: Ctx,
49
- registryFile: string,
50
- legacyRegistryFile?: string,
51
- ): Promise<void> {
50
+ export async function syncMarketplace(ctx: Ctx, paths: OmpPaths): Promise<void> {
52
51
  const { change, clearProgress, echo, progress, verbose } = ctx.services.logger;
53
- const registered = registryHasDocks(registryFile);
52
+ const registered = registryHasDocks(p(paths.dataRoot, "marketplaces.json"));
54
53
  const adoptable =
55
- !registered && legacyRegistryFile !== undefined && registryHasDocks(legacyRegistryFile);
54
+ !registered &&
55
+ paths.dataRoot !== paths.configRoot &&
56
+ registryHasDocks(p(paths.configRoot, "marketplaces.json"));
56
57
 
57
58
  // syncPlugins owns the single skip message for both missing CLIs, and it runs
58
59
  // right after this pass. Without omp no marketplace command can run at all,
@@ -77,9 +78,11 @@ export async function syncMarketplace(
77
78
 
78
79
  if (!registered && !adoptable) {
79
80
  progress("Registering omp docks marketplace...");
80
- const result = await spawnProcess("omp", ["plugin", "marketplace", "add", MARKETPLACE_SOURCE], {
81
- stdio: ["ignore", "pipe", "pipe"],
82
- });
81
+ const result = await spawnOmp(
82
+ paths,
83
+ ["plugin", "marketplace", "add", MARKETPLACE_SOURCE],
84
+ ["ignore", "pipe", "pipe"],
85
+ );
83
86
  clearProgress();
84
87
  if (result.error === undefined && result.exitCode === 0) {
85
88
  change("omp docks marketplace registered");
@@ -102,9 +105,11 @@ export async function syncMarketplace(
102
105
  // does that and fetches nothing, so it stays inside the flag's contract
103
106
  // while leaving the active registry present.
104
107
  progress("Adopting omp docks marketplace registry...");
105
- const listed = await spawnProcess("omp", ["plugin", "marketplace", "list"], {
106
- stdio: ["ignore", "ignore", "pipe"],
107
- });
108
+ const listed = await spawnOmp(
109
+ paths,
110
+ ["plugin", "marketplace", "list"],
111
+ ["ignore", "ignore", "pipe"],
112
+ );
108
113
  clearProgress();
109
114
  if (listed.error === undefined && listed.exitCode === 0) {
110
115
  change("omp docks marketplace registry adopted; refresh-only update skipped");
@@ -118,9 +123,11 @@ export async function syncMarketplace(
118
123
  }
119
124
 
120
125
  progress("Updating omp docks marketplace...");
121
- const result = await spawnProcess("omp", ["plugin", "marketplace", "update", MARKETPLACE_NAME], {
122
- stdio: ["ignore", "pipe", "pipe"],
123
- });
126
+ const result = await spawnOmp(
127
+ paths,
128
+ ["plugin", "marketplace", "update", MARKETPLACE_NAME],
129
+ ["ignore", "pipe", "pipe"],
130
+ );
124
131
  clearProgress();
125
132
  if (result.error === undefined && result.exitCode === 0) {
126
133
  verbose("omp docks marketplace refreshed");
@@ -1,14 +1,14 @@
1
1
  /**
2
2
  * Run overlay for `docks-kit omp`. The overlay merges over the deployed omp
3
3
  * config for one run only. It sets the 16 roles in ROLE_ORDER to the free
4
- * model and empties the 13 retry chains in FALLBACK_ORDER and the chains keyed
4
+ * model and empties the 12 retry chains in FALLBACK_ORDER and the chains keyed
5
5
  * by the free model. omp merges the overlay key by key, so each deployed retry
6
6
  * chain that is not in FALLBACK_ORDER stays as deployed. The `web` role and
7
7
  * its retry chain are not in the overlay, so the deployed web-search provider
8
8
  * order applies, and that order can include a paid chat model. A deployed
9
- * `plan`, `slow`, or `designer` chain also stays, but a retry of the free
10
- * model uses the empty chain keyed by that model first. Every other key falls
11
- * through to the deployed config.
9
+ * `advisor`, `plan`, `slow`, or `designer` chain also stays, but a retry of
10
+ * the free model uses the empty chain keyed by that model first. Every other
11
+ * key falls through to the deployed config.
12
12
  */
13
13
  import { createHash } from "node:crypto";
14
14
  import { delimiter } from "node:path";
@@ -35,7 +35,7 @@ export const THINKING_LADDER: ReadonlyArray<string> = [
35
35
  * One overlay file per distinct model and level combination, so a second
36
36
  * launcher cannot rewrite the file a running session still reads. omp
37
37
  * reloads a changed overlay mid-session, so the digest covers the exact
38
- * rendered overlay: the selector, both levels, and every rendered key. A
38
+ * rendered overlay: the selector, the level, and every rendered key. A
39
39
  * selector carries a slash and may carry other characters a host rejects in
40
40
  * a file name, so unsafe characters in the readable prefix become hyphens.
41
41
  */
@@ -47,14 +47,16 @@ export function overlayFileName(model: OmpSessionModel): string {
47
47
 
48
48
  /**
49
49
  * Role keys in the order used by SoT/.omp/config.yml for readable diffs. The
50
- * SoT does not set `memory` and `judge`, so they come last. An unset role
51
- * falls back to the omp built-in priority chain, which can name a paid model.
52
- * The `web` role is left out on purpose, so the deployed web-search provider
53
- * order applies.
50
+ * SoT does not set `advisor`, `memory`, and `judge`, so they come last. An
51
+ * unset role falls back to the omp built-in priority chain, which can name a
52
+ * paid model. omp takes the `/advisor on` model from the `advisor` role and
53
+ * uses `slow` only when that role is unset, so the overlay pins `advisor`
54
+ * too: a deployed or project advisor role would otherwise send the advisor
55
+ * to a paid model. The `web` role is left out on purpose, so the
56
+ * deployed web-search provider order applies.
54
57
  */
55
58
  const ROLE_ORDER: ReadonlyArray<string> = [
56
59
  "smol",
57
- "advisor",
58
60
  "designer",
59
61
  "plan",
60
62
  "commit",
@@ -67,6 +69,7 @@ const ROLE_ORDER: ReadonlyArray<string> = [
67
69
  "switch_fable",
68
70
  "astra",
69
71
  "reviewer",
72
+ "advisor",
70
73
  "memory",
71
74
  "judge",
72
75
  ];
@@ -78,7 +81,6 @@ const ROLE_ORDER: ReadonlyArray<string> = [
78
81
  */
79
82
  const FALLBACK_ORDER: ReadonlyArray<string> = [
80
83
  "default",
81
- "advisor",
82
84
  "task",
83
85
  "vision",
84
86
  "smol",
@@ -147,29 +149,12 @@ export function ladderCeiling(levels: ReadonlyArray<string>): string | undefined
147
149
  return undefined;
148
150
  }
149
151
 
150
- /**
151
- * Resolve the advisor level from the model own ladder. The advisor runs
152
- * quick review passes, so it takes the highest level at or below medium,
153
- * and the lowest level when the ladder starts above medium. The result
154
- * never exceeds the ladder ceiling by construction.
155
- */
156
- export function advisorLevelFor(levels: ReadonlyArray<string>): string | undefined {
157
- const known = THINKING_LADDER.filter((level) => levels.includes(level));
158
- if (known.length === 0) return undefined;
159
- const mediumIndex = THINKING_LADDER.indexOf("medium");
160
- let advisor: string | undefined;
161
- for (const level of known) {
162
- if ((THINKING_LADDER.indexOf(level) as number) <= (mediumIndex as number)) advisor = level;
163
- }
164
- return advisor ?? (known[0] as string);
165
- }
166
-
167
152
  /**
168
153
  * What the picker may ask about thinking levels for one model. omp accepts a
169
154
  * `:level` suffix on a role only for a level the model publishes, so the
170
155
  * question set comes from the model own ladder: no ladder means no question,
171
- * a single level means no choice to make, and two or more levels mean the
172
- * user can split the advisor from the other roles.
156
+ * a single level means no choice to make, and two or more levels mean one
157
+ * level choice for every role.
173
158
  */
174
159
  export type EffortPlan =
175
160
  | { readonly kind: "none" }
@@ -184,39 +169,19 @@ export function planEffortChoice(levels: ReadonlyArray<string>): EffortPlan {
184
169
  return { kind: "choose", levels: known, highest: known[known.length - 1] as string };
185
170
  }
186
171
 
187
- /**
188
- * Recommend an advisor level for a chosen main level. The advisor runs quick
189
- * review passes, so it sits two steps down the model own ladder, and it
190
- * clamps to the lowest level the model publishes. Steps count positions in
191
- * that model ladder, not the global ladder, so a sparse ladder such as
192
- * `high, max` still recommends a real level.
193
- */
194
- export function advisorRecommendation(
195
- levels: ReadonlyArray<string>,
196
- main: string,
197
- ): string | undefined {
198
- const known = THINKING_LADDER.filter((level) => levels.includes(level));
199
- const index = known.indexOf(main);
200
- if (index < 0) return known[0];
201
- return known[Math.max(0, index - 2)];
202
- }
203
-
204
172
  /** A thinking level the overlay can render, or undefined for a blank one. */
205
173
  function renderableLevel(level: string | undefined): string | undefined {
206
174
  return typeof level === "string" && level.trim() !== "" ? level : undefined;
207
175
  }
208
176
 
209
177
  /**
210
- * The value the overlay gives one role. The overlay, the session `--model`,
178
+ * The value the overlay gives every role. The overlay, the session `--model`,
211
179
  * and the child environment all use it, so the three cannot drift apart. A
212
180
  * model without a level gets the bare selector so the deployed level applies.
213
181
  */
214
- function roleValue(model: OmpSessionModel, role: string): string {
182
+ function roleValue(model: OmpSessionModel): string {
215
183
  const thinking = renderableLevel(model.thinking);
216
- if (thinking === undefined) return model.selector;
217
- const level =
218
- role === "advisor" ? (renderableLevel(model.advisorThinking) ?? thinking) : thinking;
219
- return `${model.selector}:${level}`;
184
+ return thinking === undefined ? model.selector : `${model.selector}:${thinking}`;
220
185
  }
221
186
 
222
187
  /**
@@ -230,7 +195,7 @@ export function renderFreeOverlay(model: OmpSessionModel): string {
230
195
  if (thinking !== undefined) lines.push(`defaultThinkingLevel: ${thinking}`);
231
196
  lines.push("modelRoles:");
232
197
  for (const role of ROLE_ORDER) {
233
- lines.push(` ${role}: ${roleValue(model, role)}`);
198
+ lines.push(` ${role}: ${roleValue(model)}`);
234
199
  }
235
200
  if (thinking !== undefined) lines.push("task:", ` maxEffort: ${thinking}`);
236
201
  lines.push("retry:", " fallbackChains:");
@@ -258,22 +223,11 @@ export function buildOmpArgs(
258
223
  session: OmpSessionModel,
259
224
  passthrough: ReadonlyArray<string>,
260
225
  ): ReadonlyArray<string> {
261
- return [
262
- "launch",
263
- "--config",
264
- overlayPath,
265
- "--model",
266
- roleValue(session, "default"),
267
- ...passthrough,
268
- ];
226
+ return ["launch", "--config", overlayPath, "--model", roleValue(session), ...passthrough];
269
227
  }
270
228
 
271
229
  // Variables that omp reads at launch to set a role above every config layer.
272
- const MODEL_ENV_ROLES: ReadonlyArray<readonly [string, string]> = [
273
- ["PI_SMOL_MODEL", "smol"],
274
- ["PI_SLOW_MODEL", "slow"],
275
- ["PI_PLAN_MODEL", "plan"],
276
- ];
230
+ const MODEL_ENV_NAMES: ReadonlyArray<string> = ["PI_SMOL_MODEL", "PI_SLOW_MODEL", "PI_PLAN_MODEL"];
277
231
 
278
232
  export interface OmpChildEnvironment {
279
233
  readonly env: Record<string, string | undefined>;
@@ -300,8 +254,8 @@ export function ompChildEnvironment(
300
254
  PI_CONFIG_FILES: [...inherited, overlayPath].join(delimiter),
301
255
  };
302
256
  const replaced: Array<string> = [];
303
- for (const [name, role] of MODEL_ENV_ROLES) {
304
- const value = roleValue(session, role);
257
+ const value = roleValue(session);
258
+ for (const name of MODEL_ENV_NAMES) {
305
259
  const previous = parent[name];
306
260
  if (previous !== undefined && previous !== "" && previous !== value) replaced.push(name);
307
261
  env[name] = value;