docks-kit 0.20.10 → 0.21.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.
@@ -3,6 +3,7 @@ import { Console, Effect, Option } from "effect";
3
3
  import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
4
4
  import { bail } from "../engine";
5
5
  import { capture, p, spawnHost, which } from "../engine-native/exec";
6
+ import { kitCacheDir } from "../engine-native/scratch";
6
7
  import {
7
8
  DEFAULT_OMP_SESSION_MODEL,
8
9
  engineHome,
@@ -15,6 +16,7 @@ import {
15
16
  advisorRecommendation,
16
17
  buildOmpArgs,
17
18
  ladderCeiling,
19
+ ompChildEnvironment,
18
20
  overlayFileName,
19
21
  planEffortChoice,
20
22
  parseFreeModels,
@@ -79,20 +81,20 @@ export function resolveFreeSelector(
79
81
  }
80
82
 
81
83
  /**
82
- * The omp profile that the forwarded arguments select. omp reads
83
- * `--profile <name>` or `--profile=<name>` before a `--`, the last one wins,
84
- * and it rejects a missing or empty name. The catalog check must query the
85
- * profile the session runs, so it reads the arguments the same way.
84
+ * Every omp profile that the forwarded arguments can select, in argv order.
85
+ * omp reads `--profile <name>` or `--profile=<name>`, the last one wins, and
86
+ * it rejects a missing or empty name. The scan does not stop at `--`,
87
+ * because omp can read that `--` as the value of a flag such as
88
+ * `--system-prompt` and still select a later profile.
86
89
  */
87
90
  export type ForwardedProfile =
88
- | { readonly ok: true; readonly profile: string | undefined }
91
+ | { readonly ok: true; readonly profiles: ReadonlyArray<string> }
89
92
  | { readonly ok: false; readonly message: string };
90
93
 
91
94
  export function forwardedProfile(forwarded: ReadonlyArray<string>): ForwardedProfile {
92
- let profile: string | undefined;
95
+ const profiles: Array<string> = [];
93
96
  for (let index = 0; index < forwarded.length; index++) {
94
97
  const arg = forwarded[index]!;
95
- if (arg === "--") break;
96
98
  let value: string | undefined;
97
99
  if (arg === "--profile") {
98
100
  value = forwarded[index + 1];
@@ -104,9 +106,48 @@ export function forwardedProfile(forwarded: ReadonlyArray<string>): ForwardedPro
104
106
  continue;
105
107
  }
106
108
  if (value === "") return { ok: false, message: "--profile requires a profile name" };
107
- profile = value;
109
+ profiles.push(value);
108
110
  }
109
- return { ok: true, profile };
111
+ return { ok: true, profiles };
112
+ }
113
+
114
+ // omp flags that can select a model the free overlay does not control.
115
+ const MODEL_SELECTING_FLAGS: Record<string, true> = {
116
+ "--config": true,
117
+ "--model": true,
118
+ "--smol": true,
119
+ "--slow": true,
120
+ "--plan": true,
121
+ "--models": true,
122
+ "--provider": true,
123
+ "--prewalk-into": true,
124
+ "--plan-yolo-into": true,
125
+ };
126
+
127
+ export type ForwardedFlagCheck =
128
+ | { readonly ok: true }
129
+ | { readonly ok: false; readonly message: string };
130
+
131
+ /**
132
+ * Reject a forwarded omp flag that can select a model outside the free
133
+ * session. The scan does not stop at `--`, because omp can read that `--` as
134
+ * the value of a flag and then parse the next token as a flag.
135
+ */
136
+ export function rejectedForwardedFlag(forwarded: ReadonlyArray<string>): ForwardedFlagCheck {
137
+ for (const arg of forwarded) {
138
+ const equals = arg.indexOf("=");
139
+ const flag = equals === -1 ? arg : arg.slice(0, equals);
140
+ if (MODEL_SELECTING_FLAGS[flag] !== true) continue;
141
+ const configNote =
142
+ flag === "--config"
143
+ ? " To load another config, list it in PI_CONFIG_FILES, which omp loads below the overlay."
144
+ : "";
145
+ return {
146
+ ok: false,
147
+ message: `Forwarded ${flag} can select a model outside the free session. For a free model, put --model <selector> before other arguments or use --pick; for a paid model, run omp directly.${configNote}`,
148
+ };
149
+ }
150
+ return { ok: true };
110
151
  }
111
152
 
112
153
  const loadFreeCatalog = (
@@ -212,6 +253,11 @@ const pickLevels = (catalogModel: CatalogModel) =>
212
253
 
213
254
  export const ompCommand = Command.make("omp", { model, pick, fast, args }, (config) =>
214
255
  Effect.gen(function* () {
256
+ // Check the forwarded arguments before omp, the catalog, or kit.db, so a
257
+ // rejected launch starts no process and writes nothing.
258
+ const forwardedFlag = rejectedForwardedFlag(config.args);
259
+ if (!forwardedFlag.ok) return yield* bail(forwardedFlag.message);
260
+
215
261
  if (Option.isSome(config.model) && config.pick) {
216
262
  return yield* bail("Pass either --model <selector> or --pick, not both");
217
263
  }
@@ -250,13 +296,24 @@ export const ompCommand = Command.make("omp", { model, pick, fast, args }, (conf
250
296
  if (config.pick && (!process.stdin.isTTY || !process.stdout.isTTY)) {
251
297
  return yield* bail("Picking needs a terminal; pass --model <selector> instead");
252
298
  }
253
- // Every launch reads the live catalog once, because a remembered or
254
- // default model can be renamed, repriced, or lose its provider login.
255
- // omp then silently starts a paid default model instead. The catalog
256
- // comes from the profile that the forwarded arguments select.
299
+ // Every launch reads the live catalog, because a remembered or default
300
+ // model can be renamed, repriced, or lose its provider login. omp then
301
+ // silently starts a paid default model instead. omp can run the
302
+ // environment's profile or any forwarded one, so the session model must
303
+ // be free in the catalog of each.
257
304
  const profile = forwardedProfile(config.args);
258
305
  if (!profile.ok) return yield* bail(profile.message);
259
- const free = yield* loadFreeCatalog(omp, profile.profile);
306
+ const candidates: Array<string | undefined> = [undefined];
307
+ for (const name of profile.profiles) {
308
+ if (!candidates.includes(name)) candidates.push(name);
309
+ }
310
+ const catalogs: Array<ReadonlyArray<CatalogModel>> = [];
311
+ for (const candidate of candidates) {
312
+ catalogs.push(yield* loadFreeCatalog(omp, candidate));
313
+ }
314
+ // --model and --pick choose from the catalog of the last forwarded
315
+ // profile, which omp selects when no flag consumes it.
316
+ const free = catalogs[candidates.indexOf(profile.profiles.at(-1))]!;
260
317
  // The value the launcher writes is the value it runs, so a concurrent
261
318
  // launcher or a failed read of kit.db cannot change this session.
262
319
  let chosen: OmpSessionModel | undefined;
@@ -297,24 +354,27 @@ export const ompCommand = Command.make("omp", { model, pick, fast, args }, (conf
297
354
  };
298
355
  }
299
356
 
300
- if (chosen !== undefined) {
301
- const remembered = chosen;
302
- yield* Effect.sync(() => writeOmpSessionModel(home, remembered));
303
- }
304
-
305
357
  const session: OmpSessionModel =
306
358
  chosen ?? (yield* Effect.sync(() => readOmpSessionModel(home))) ?? DEFAULT_OMP_SESSION_MODEL;
307
- if (!free.some((candidate) => candidate.selector === session.selector)) {
359
+ const freeInEveryProfile = catalogs.every((catalog) =>
360
+ catalog.some((candidate) => candidate.selector === session.selector),
361
+ );
362
+ if (!freeInEveryProfile) {
308
363
  return yield* bail(
309
364
  `free model '${session.selector}' is not available in the omp catalog (renamed, repriced, or provider not logged in); log in to its provider or choose another with --model or --pick`,
310
365
  );
311
366
  }
312
367
 
368
+ if (chosen !== undefined) {
369
+ const remembered = chosen;
370
+ yield* Effect.sync(() => writeOmpSessionModel(home, remembered));
371
+ }
372
+
313
373
  // A stable cache path, not a temp file deleted at exit, because omp may
314
374
  // re-read the overlay during a live session. The name carries a digest of
315
375
  // the rendered overlay, so a second launcher on another model or level
316
376
  // cannot rewrite the file a running session still reads.
317
- const directory = p(home, ".cache", "docks-kit");
377
+ const directory = kitCacheDir(home);
318
378
  const overlayPath = p(directory, overlayFileName(session));
319
379
  yield* Effect.sync(() => {
320
380
  // `mode` applies only when mkdir creates the path, so an existing
@@ -343,8 +403,20 @@ export const ompCommand = Command.make("omp", { model, pick, fast, args }, (conf
343
403
  `Starting omp with ${session.selector} at ${levelText}${advisorText} (session only; deployed config unchanged)`,
344
404
  );
345
405
 
406
+ // An exported model variable would set its role above the overlay, so the
407
+ // session gets the overlay value and the user sees what changed.
408
+ const childEnvironment = ompChildEnvironment(process.env, overlayPath, session);
409
+ for (const name of childEnvironment.replaced) {
410
+ yield* Console.error(
411
+ `${name} is set; this session uses ${childEnvironment.env[name]} instead`,
412
+ );
413
+ }
414
+
346
415
  const child = yield* Effect.sync(() =>
347
- spawnHost("omp", buildOmpArgs(overlayPath, config.args), { stdio: "inherit" }),
416
+ spawnHost("omp", buildOmpArgs(overlayPath, session, config.args), {
417
+ stdio: "inherit",
418
+ env: childEnvironment.env,
419
+ }),
348
420
  );
349
421
  if (child.error !== undefined) {
350
422
  return yield* bail(
@@ -356,6 +428,6 @@ export const ompCommand = Command.make("omp", { model, pick, fast, args }, (conf
356
428
  }),
357
429
  ).pipe(
358
430
  Command.withDescription(
359
- "Start omp with every chat-model role set to the remembered free model for this run only. The web-search role keeps the deployed provider order, which can include a paid model. No deployed configuration changes; --model or --pick remembers a new free default. Every launch checks the model against the live free catalog. --fast instead toggles OpenAI/Codex fast mode in the deployed omp config and exits.",
431
+ "Start omp with every chat-model role set to the remembered free model for this run only. The launcher starts 'omp launch' with an explicit --model, so omp reads a forwarded subcommand name as message text and a resumed session keeps the free model. It rejects forwarded flags that can select another model (--config, --model, --smol, --slow, --plan, --models, --provider, --prewalk-into, --plan-yolo-into); run omp directly for a paid model or a subcommand. The web-search role keeps the deployed provider order, which can include a paid model. No deployed configuration changes; --model or --pick remembers a new free default. Every launch checks the model against the live free catalog of each candidate profile. --fast instead toggles OpenAI/Codex fast mode in the deployed omp config and exits.",
360
432
  ),
361
433
  );
@@ -0,0 +1,75 @@
1
+ import { tmpdir } from "node:os";
2
+
3
+ import { Argument, Command } from "effect/unstable/cli";
4
+ import { Console, Effect } from "effect";
5
+
6
+ import { bail } from "../engine";
7
+ import { engineHome } from "../engine-native/harnesses";
8
+ import {
9
+ allowedRemovalRoots,
10
+ createScratchDir,
11
+ removeTemporaryPath,
12
+ scratchRoot,
13
+ } from "../engine-native/scratch";
14
+
15
+ const action = Argument.String("action").pipe(
16
+ Argument.withDescription("new <label> | remove <path>..."),
17
+ );
18
+ const operands: Argument.Argument<ReadonlyArray<string>> = Argument.String("operands").pipe(
19
+ Argument.withDescription("The label for new, or the paths for remove"),
20
+ Argument.variadic(),
21
+ );
22
+
23
+ export const scratchCommand = Command.make("scratch", { action, operands }, (config) =>
24
+ Effect.gen(function* () {
25
+ const home = engineHome();
26
+ switch (config.action) {
27
+ case "new": {
28
+ const [label, ...rest] = config.operands;
29
+ if (label === undefined || rest.length > 0)
30
+ return yield* bail("scratch new needs one label");
31
+ let created: string;
32
+ try {
33
+ created = createScratchDir(scratchRoot(home), label);
34
+ } catch (cause) {
35
+ return yield* bail(cause instanceof Error ? cause.message : String(cause));
36
+ }
37
+ yield* Console.log(created);
38
+ return;
39
+ }
40
+ case "remove": {
41
+ if (config.operands.length === 0) {
42
+ return yield* bail("scratch remove needs at least one path");
43
+ }
44
+ const roots = allowedRemovalRoots({
45
+ home,
46
+ scratch: scratchRoot(home),
47
+ tmp: tmpdir(),
48
+ platform: process.platform,
49
+ });
50
+ let refused = false;
51
+ for (const operand of config.operands) {
52
+ const outcome = removeTemporaryPath(operand, roots, home);
53
+ if (outcome.kind === "removed") {
54
+ yield* Console.log(`removed ${outcome.path}`);
55
+ } else {
56
+ refused = true;
57
+ yield* Console.log(`refused ${outcome.path}: ${outcome.reason}`);
58
+ }
59
+ }
60
+ if (refused) {
61
+ yield* Effect.sync(() => {
62
+ process.exitCode = 1;
63
+ });
64
+ }
65
+ return;
66
+ }
67
+ default:
68
+ return yield* bail(`Unknown scratch action '${config.action}'; use new or remove`);
69
+ }
70
+ }),
71
+ ).pipe(
72
+ Command.withDescription(
73
+ "Create an agent temporary directory, or remove agent temporary files and directories; removal accepts only paths inside the scratch root, the system temporary directory, or /var/tmp.",
74
+ ),
75
+ );
@@ -0,0 +1,91 @@
1
+ import { resolve } from "node:path";
2
+
3
+ import { Command, Flag } from "effect/unstable/cli";
4
+ import { Console, Effect, Option } from "effect";
5
+
6
+ import { bail } from "../engine";
7
+ import { engineHome } from "../engine-native/harnesses";
8
+ import { scratchRoot } from "../engine-native/scratch";
9
+ import {
10
+ actionSubject,
11
+ actionVerb,
12
+ agentWorktreeRoot,
13
+ applyTidy,
14
+ defaultTidyHost,
15
+ mainRepository,
16
+ planTidy,
17
+ type TidyInputs,
18
+ } from "../engine-native/tidy";
19
+ import { buildTidyReport } from "../engine-native/tidyReport";
20
+
21
+ const apply = Flag.Boolean("apply").pipe(
22
+ Flag.withDescription("Perform the listed actions"),
23
+ Flag.withDefault(false),
24
+ );
25
+ const repo = Flag.String("repo").pipe(
26
+ Flag.withDescription("Take worktree candidates only from this repository, at any location"),
27
+ Flag.optional,
28
+ );
29
+ const report = Flag.Boolean("report").pipe(
30
+ Flag.withDescription("Also list other disk and memory use (read-only)"),
31
+ Flag.withDefault(false),
32
+ );
33
+
34
+ export const tidyCommand = Command.make("tidy", { apply, repo, report }, (config) =>
35
+ Effect.gen(function* () {
36
+ const host = defaultTidyHost();
37
+ const home = engineHome();
38
+ let repository: string | undefined;
39
+ if (Option.isSome(config.repo)) {
40
+ const typed = config.repo.value;
41
+ repository = yield* Effect.promise(() => mainRepository(resolve(process.cwd(), typed), host));
42
+ if (repository === undefined) return yield* bail(`--repo ${typed} is not a git repository`);
43
+ }
44
+ const inputs: TidyInputs = {
45
+ home,
46
+ worktreeRoot: agentWorktreeRoot(home, process.env),
47
+ scratchRoot: scratchRoot(home),
48
+ ...(repository === undefined ? {} : { repo: repository }),
49
+ };
50
+
51
+ const plan = yield* Effect.promise(() => planTidy(inputs, host));
52
+ for (const action of plan.actions) {
53
+ yield* Console.log(`${actionVerb(action)} ${actionSubject(action)}: ${action.reason}`);
54
+ }
55
+ for (const kept of plan.kept) yield* Console.log(`keep ${kept.subject}: ${kept.reason}`);
56
+ for (const note of plan.notes) yield* Console.log(`note: ${note}`);
57
+
58
+ if (plan.actions.length === 0) {
59
+ yield* Console.log("Nothing to tidy.");
60
+ } else if (config.apply) {
61
+ const outcome = yield* Effect.promise(() => applyTidy(plan, inputs, host));
62
+ for (const line of outcome.lines) yield* Console.log(line);
63
+ if (outcome.failures > 0) {
64
+ yield* Effect.sync(() => {
65
+ process.exitCode = 1;
66
+ });
67
+ }
68
+ } else {
69
+ // In --repo mode a bare `tidy --apply` would perform a different plan.
70
+ const applyCommand =
71
+ repository === undefined
72
+ ? "docks-kit tidy --apply"
73
+ : `docks-kit tidy --repo ${repository} --apply`;
74
+ yield* Console.log(
75
+ `Dry run: ${plan.actions.length} actions. Run '${applyCommand}' to perform them.`,
76
+ );
77
+ }
78
+
79
+ if (config.report) {
80
+ const sections = yield* Effect.promise(() => buildTidyReport(inputs, host, plan.docker));
81
+ for (const section of sections) {
82
+ yield* Console.log(`== ${section.title}`);
83
+ for (const line of section.lines) yield* Console.log(line);
84
+ }
85
+ }
86
+ }),
87
+ ).pipe(
88
+ Command.withDescription(
89
+ "List or remove safe agent leftovers (merged idle worktrees, their containers, orphaned processes in agent directories, idle scratch directories); --report lists other disk and memory use.",
90
+ ),
91
+ );
@@ -0,0 +1,94 @@
1
+ /**
2
+ * EngineNative omp kit plugin: writes the embedded `SoT/.omp/plugin/` package
3
+ * into the kit-owned directory `~/.docks-kit/omp-plugin`, which
4
+ * `ompPlugins.ts syncPlugins` links into omp. The kit owns the directory, so
5
+ * a sync replaces changed files without `.bak` copies and removes files that
6
+ * the payload no longer lists. Split from ompSync.ts; the orchestration still
7
+ * lives there.
8
+ */
9
+ import {
10
+ chmodSync,
11
+ existsSync,
12
+ lstatSync,
13
+ readFileSync,
14
+ readdirSync,
15
+ rmdirSync,
16
+ unlinkSync,
17
+ writeFileSync,
18
+ } from "node:fs";
19
+
20
+ import { GENERATED_PACKAGE_VERSION } from "../generated/sotPayload";
21
+ import { payloadBytes, payloadDisplayPath, payloadPaths } from "../payload";
22
+ import { p } from "./exec";
23
+ import type { Ctx } from "./index";
24
+ import { ensureDirectory } from "./ompFileDeploy";
25
+
26
+ export const KIT_PLUGIN_NAME = "docks-kit-omp";
27
+
28
+ const SOURCE_PREFIX = "SoT/.omp/plugin/";
29
+
30
+ export function kitPluginDir(home: string): string {
31
+ return p(home, ".docks-kit", "omp-plugin");
32
+ }
33
+
34
+ /** Removes every entry under `directory` that is not a target, then empty directories. */
35
+ function pruneStale(directory: string, targets: ReadonlySet<string>): boolean {
36
+ let changed = false;
37
+ for (const name of readdirSync(directory)) {
38
+ const entry = p(directory, name);
39
+ const stat = lstatSync(entry);
40
+ if (stat.isDirectory()) {
41
+ changed = pruneStale(entry, targets) || changed;
42
+ if (readdirSync(entry).length === 0) {
43
+ rmdirSync(entry);
44
+ changed = true;
45
+ }
46
+ } else if (!targets.has(entry)) {
47
+ unlinkSync(entry);
48
+ changed = true;
49
+ }
50
+ }
51
+ return changed;
52
+ }
53
+
54
+ export function syncKitPlugin(ctx: Ctx): void {
55
+ const { change, echo, verbose } = ctx.services.logger;
56
+ const pluginDir = kitPluginDir(ctx.home);
57
+ const files = payloadPaths(SOURCE_PREFIX).map((source) => ({
58
+ source,
59
+ target: p(pluginDir, source.slice(SOURCE_PREFIX.length)),
60
+ }));
61
+
62
+ if (ctx.dryRun) {
63
+ for (const { source, target } of files) {
64
+ echo(`[dry-run] cp ${payloadDisplayPath(source)} -> ${target}`);
65
+ }
66
+ return;
67
+ }
68
+
69
+ let changed = false;
70
+ for (const { source, target } of files) {
71
+ let content = payloadBytes(source);
72
+ if (source === `${SOURCE_PREFIX}package.json`) {
73
+ // The SoT manifest carries a placeholder version; the kit version replaces it.
74
+ const manifest = JSON.parse(content.toString("utf8")) as Record<string, unknown>;
75
+ manifest["version"] = GENERATED_PACKAGE_VERSION;
76
+ content = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`);
77
+ }
78
+ ensureDirectory(target.slice(0, target.lastIndexOf("/")));
79
+ if (existsSync(target) && readFileSync(target).equals(content)) continue;
80
+ writeFileSync(target, content, { mode: 0o600 });
81
+ chmodSync(target, 0o600);
82
+ changed = true;
83
+ }
84
+ if (existsSync(pluginDir)) {
85
+ changed = pruneStale(pluginDir, new Set(files.map(({ target }) => target))) || changed;
86
+ }
87
+
88
+ if (changed) {
89
+ change("omp kit plugin files synced");
90
+ ctx.nextStepTriggers.ompRestart = true;
91
+ } else {
92
+ verbose("omp kit plugin files already in sync");
93
+ }
94
+ }
@@ -1,15 +1,17 @@
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. omp merges the
5
- * overlay key by key, so each deployed retry chain that is not in
6
- * FALLBACK_ORDER stays as deployed. The `web` role and its retry chain are
7
- * not in the overlay, so the deployed web-search provider order applies, and
8
- * that order can include a paid chat model. A deployed `plan`, `slow`, or
9
- * `designer` chain also stays and can name a paid model. Every other key
10
- * falls through to the deployed config.
4
+ * model and empties the 13 retry chains in FALLBACK_ORDER and the chains keyed
5
+ * by the free model. omp merges the overlay key by key, so each deployed retry
6
+ * chain that is not in FALLBACK_ORDER stays as deployed. The `web` role and
7
+ * its retry chain are not in the overlay, so the deployed web-search provider
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.
11
12
  */
12
13
  import { createHash } from "node:crypto";
14
+ import { delimiter } from "node:path";
13
15
  import type { OmpSessionModel } from "./harnesses";
14
16
 
15
17
  export interface CatalogModel {
@@ -199,42 +201,110 @@ export function advisorRecommendation(
199
201
  return known[Math.max(0, index - 2)];
200
202
  }
201
203
 
204
+ /** A thinking level the overlay can render, or undefined for a blank one. */
205
+ function renderableLevel(level: string | undefined): string | undefined {
206
+ return typeof level === "string" && level.trim() !== "" ? level : undefined;
207
+ }
208
+
209
+ /**
210
+ * The value the overlay gives one role. The overlay, the session `--model`,
211
+ * and the child environment all use it, so the three cannot drift apart. A
212
+ * model without a level gets the bare selector so the deployed level applies.
213
+ */
214
+ function roleValue(model: OmpSessionModel, role: string): string {
215
+ 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}`;
220
+ }
221
+
202
222
  /**
203
223
  * Render the run overlay as YAML text. Empty fallback chains keep a retry
204
224
  * from falling back onto a paid model. A model without a level renders bare
205
225
  * selectors with no thinking keys so the deployed values apply.
206
226
  */
207
227
  export function renderFreeOverlay(model: OmpSessionModel): string {
208
- const thinking =
209
- typeof model.thinking === "string" && model.thinking.trim() !== "" ? model.thinking : undefined;
228
+ const thinking = renderableLevel(model.thinking);
210
229
  const lines: Array<string> = ["# Generated per run by docks-kit omp. Edits are overwritten."];
211
- if (thinking !== undefined) {
212
- lines.push(`defaultThinkingLevel: ${thinking}`, "modelRoles:");
213
- const advisor =
214
- typeof model.advisorThinking === "string" && model.advisorThinking.trim() !== ""
215
- ? model.advisorThinking
216
- : thinking;
217
- for (const role of ROLE_ORDER) {
218
- lines.push(` ${role}: ${model.selector}:${role === "advisor" ? advisor : thinking}`);
219
- }
220
- lines.push("task:", ` maxEffort: ${thinking}`);
221
- } else {
222
- lines.push("modelRoles:");
223
- for (const role of ROLE_ORDER) {
224
- lines.push(` ${role}: ${model.selector}`);
225
- }
230
+ if (thinking !== undefined) lines.push(`defaultThinkingLevel: ${thinking}`);
231
+ lines.push("modelRoles:");
232
+ for (const role of ROLE_ORDER) {
233
+ lines.push(` ${role}: ${roleValue(model, role)}`);
226
234
  }
235
+ if (thinking !== undefined) lines.push("task:", ` maxEffort: ${thinking}`);
227
236
  lines.push("retry:", " fallbackChains:");
228
237
  for (const chain of FALLBACK_ORDER) {
229
238
  lines.push(` ${chain}: []`);
230
239
  }
240
+ // A chain keyed by the selector outranks a role chain, so a project or
241
+ // PI_CONFIG_FILES chain for the free model could otherwise reach a paid
242
+ // model. The session can run the model at any level, `off` included.
243
+ for (const level of [undefined, "off", ...THINKING_LADDER]) {
244
+ const key = level === undefined ? model.selector : `${model.selector}:${level}`;
245
+ lines.push(` ${JSON.stringify(key)}: []`);
246
+ }
231
247
  return `${lines.join("\n")}\n`;
232
248
  }
233
249
 
234
- /** Build the omp argv with the overlay flag ahead of the forwarded args. */
250
+ /**
251
+ * Build the omp argv. `launch` first makes omp read every forwarded word as
252
+ * message text, so no omp subcommand, with its own model selection, runs
253
+ * through the launcher. The explicit `--model` outranks a restored session
254
+ * model, so `--continue` and `--resume` keep the free model.
255
+ */
235
256
  export function buildOmpArgs(
236
257
  overlayPath: string,
258
+ session: OmpSessionModel,
237
259
  passthrough: ReadonlyArray<string>,
238
260
  ): ReadonlyArray<string> {
239
- return ["--config", overlayPath, ...passthrough];
261
+ return [
262
+ "launch",
263
+ "--config",
264
+ overlayPath,
265
+ "--model",
266
+ roleValue(session, "default"),
267
+ ...passthrough,
268
+ ];
269
+ }
270
+
271
+ // 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
+ ];
277
+
278
+ export interface OmpChildEnvironment {
279
+ readonly env: Record<string, string | undefined>;
280
+ /** Model variables whose non-empty parent value the overlay value replaced. */
281
+ readonly replaced: ReadonlyArray<string>;
282
+ }
283
+
284
+ /**
285
+ * The omp session environment. The model variables get the overlay role
286
+ * values, because removing them would let a `.env` file refill them. The
287
+ * overlay joins PI_CONFIG_FILES, so an omp that the session's bash tool
288
+ * starts loads it too.
289
+ */
290
+ export function ompChildEnvironment(
291
+ parent: Readonly<Record<string, string | undefined>>,
292
+ overlayPath: string,
293
+ session: OmpSessionModel,
294
+ ): OmpChildEnvironment {
295
+ const inherited = (parent["PI_CONFIG_FILES"] ?? "")
296
+ .split(delimiter)
297
+ .filter((entry) => entry !== "");
298
+ const env: Record<string, string | undefined> = {
299
+ ...parent,
300
+ PI_CONFIG_FILES: [...inherited, overlayPath].join(delimiter),
301
+ };
302
+ const replaced: Array<string> = [];
303
+ for (const [name, role] of MODEL_ENV_ROLES) {
304
+ const value = roleValue(session, role);
305
+ const previous = parent[name];
306
+ if (previous !== undefined && previous !== "" && previous !== value) replaced.push(name);
307
+ env[name] = value;
308
+ }
309
+ return { env, replaced };
240
310
  }