docks-kit 0.17.0 → 0.17.1

package/AGENTS.md

@@ -75,7 +75,7 @@ omp SoT notes:
 - Sync installs `pi-intercom` at the verified version from `SoT/toolchain.json`.
 - The omp CLI is upstream-owned and self-updating through `omp update`. Sync never installs or upgrades the CLI.
 - `docks-kit omp [--model <selector>|--pick] [args...]` starts one interactive omp session on a single free model. It renders a run overlay to `~/.cache/docks-kit/omp-free-<model>-<digest>.yml` (mode 0600) and passes it through omp's repeatable `--config` flag. `ompOverlay.ts overlayFileName` gives each model its own file, because omp can re-read the overlay during a live session and a second launcher on another model must not rewrite it. Deployed `~/.omp/agent/` files stay untouched, so the next plain `omp` run uses the paid configuration again. Remaining arguments forward verbatim to omp.
-- The session model persists per machine in `~/.docks-kit/state.json` under `ompSession`, next to `harnesses`. The default is `opencode-zen/muse-spark-1.3-contributor-free` at `xhigh`. `ompOverlay.ts ladderCeiling, advisorLevelFor` derive both the session level and the advisor level from the ladder of the chosen model, never from a fixed list: free ladders are not uniform, three free models publish no `medium`, and two publish no ladder, which the overlay renders as bare selectors. The picker lists only zero-cost catalog models.
+- The session model persists per machine in `~/.docks-kit/state.json` under `ompSession`, next to `harnesses`. The default is `opencode-zen/muse-spark-1.3-contributor-free` at `xhigh`. `ompOverlay.ts ladderCeiling, advisorLevelFor` derive both levels from the ladder of the chosen model for the `--model` path, and `ompOverlay.ts planEffortChoice` drives the `--pick` wizard, which asks whether every role shares one level and otherwise takes one level for the main roles and one for the advisor from that model's own ladder. Levels never come from a fixed list: free ladders are not uniform, three free models publish no `medium`, and two publish no ladder, which the overlay renders as bare selectors. The picker lists only zero-cost catalog models.
 
 For per-tool SoT layouts (`SoT/.claude/`, `SoT/.codex/`, `SoT/.omp/`), see the matching SoT directory.
 

package/README.md

@@ -48,6 +48,7 @@ docks-kit harnesses                             view or change this machine's se
 docks-kit update [--no-sync]                    self-update the kit (autodetects checkout vs global install), then sync
 docks-kit model <claude|codex> [value]          get/set the DEPLOYED model (TTY picker)
 docks-kit models [claude|codex]                 model catalogs (`--json`)
+docks-kit omp [--model <m>|--pick] [args...]    one omp session on a free model, nothing deployed changes
 docks-kit toolchain [check|ensure <tool>]       verified-version floors for external tools
 docks-kit status [--json]                       deployed-vs-SoT drift + toolchain + counts
 docks-kit plugins list [--json]                 enabledPlugins tri-state vs installed

package/cli/docs/omp-models.md

@@ -254,21 +254,42 @@ fail when the session starts.
 
 The choice persists per machine in `~/.docks-kit/state.json` under
 `ompSession`, next to `harnesses`. It survives across sessions. It is never
-committed. `--model <selector>` records one selector. `--pick` opens an
-interactive picker.
+committed. `--model <selector>` records one selector and derives both levels
+from the catalog row. `--pick` opens an interactive wizard.
 
 The picker lists only models the live `omp models --json` catalog reports at
 zero input and output cost (26 entries on 2026-09-11). This path cannot start
 a paid session. The catalog can advertise a free model that the account
 cannot call; omp reports that provider error unchanged.
 
+After the model, the wizard asks about thinking levels. `ompOverlay.ts
+planEffortChoice` decides which questions apply, because omp accepts a
+`:level` suffix only for a level the chosen model publishes:
+
+- No ladder: the wizard asks nothing and the overlay omits every level.
+- One level: the wizard states that level and asks nothing.
+- Two or more levels: the wizard asks whether every role uses the same
+  level. Yes takes the highest level the model offers. No asks one level for
+  all roles except the advisor, then one level for the advisor.
+
+The advisor question leads with a recommendation from `ompOverlay.ts
+advisorRecommendation`: two steps down the model own ladder, clamped to the
+lowest level that model publishes. The recommendation is the first row
+because `Prompt.Select` starts on the first entry and accepts no initial
+index, so `Enter` takes it. The full ladder follows in ladder order. A
+recommendation equal to the chosen level is omitted rather than duplicated.
+
+A session whose advisor differs from the other roles reports both on the
+launch line.
+
 An omp login is required. The kit owns no login flow. It surfaces omp's own
 authentication error unchanged.
 
 When the catalog renames the free variant, change only the default selector
-constant. A ladder change needs no code change, because both levels come from
-the catalog row of the chosen model. Refresh the recorded default and the
-ladder counts in these docs in the same commit.
+constant. A ladder change needs no code change. Under `--model` both levels
+are derived from the catalog row of the chosen model, and under `--pick` the
+user chooses them from the ladder that same row publishes. Refresh the
+recorded default and the ladder counts in these docs in the same commit.
 
 ## Maintenance
 

package/cli/src/commands/omp.ts

@@ -12,9 +12,11 @@ import {
 } from "../engine-native/harnesses"
 import {
   advisorLevelFor,
+  advisorRecommendation,
   buildOmpArgs,
   ladderCeiling,
   overlayFileName,
+  planEffortChoice,
   parseFreeModels,
   renderFreeOverlay,
   type CatalogModel
@@ -91,6 +93,64 @@ const loadFreeCatalog = (omp: string): Effect.Effect<ReadonlyArray<CatalogModel>
     return free
   })
 
+/**
+ * Ask for the thinking levels of one model. Every choice comes from that
+ * model own ladder, because omp rejects a `:level` suffix the model does not
+ * publish. A model with no ladder and a model with one level are settled
+ * without a question.
+ */
+const pickLevels = (model: CatalogModel) =>
+  Effect.gen(function* () {
+    const plan = planEffortChoice(model.thinking)
+    if (plan.kind === "none") {
+      yield* Console.error(`${model.name} publishes no thinking levels; the model default applies`)
+      return { thinking: undefined, advisorThinking: undefined }
+    }
+    if (plan.kind === "fixed") {
+      yield* Console.error(`${model.name} publishes one thinking level: ${plan.level}`)
+      return { thinking: plan.level, advisorThinking: plan.level }
+    }
+    const uniform = yield* Prompt.Select({
+      message: "Use the same thinking level for every role?",
+      choices: [
+        { title: "Yes", value: true, description: `every role runs at ${plan.highest}, the highest this model offers` },
+        { title: "No", value: false, description: "set the advisor apart from the other roles" }
+      ]
+    })
+    if (uniform) return { thinking: plan.highest, advisorThinking: plan.highest }
+    const ladderChoices = plan.levels.map((level) => ({
+      title: level,
+      value: level,
+      description:
+        level === plan.highest ? "highest this model offers" : level === plan.levels[0] ? "lowest this model offers" : ""
+    }))
+    const thinking = yield* Prompt.Select({
+      message: "Thinking level for all roles except the advisor",
+      choices: ladderChoices
+    })
+    const suggested = advisorRecommendation(plan.levels, thinking)
+    // The list leads with the suggestion, because Prompt.Select always starts
+    // on the first entry and offers no initial index. The full ladder follows
+    // in ladder order, so a different level stays one keypress away. A
+    // suggestion equal to the main level would only duplicate a row.
+    const advisorChoices =
+      suggested === undefined || suggested === thinking
+        ? ladderChoices
+        : [
+            {
+              title: suggested,
+              value: suggested,
+              description: `recommended, two levels below ${thinking}`
+            },
+            ...ladderChoices
+          ]
+    const advisorThinking = yield* Prompt.Select({
+      message: "Thinking level for the advisor role",
+      choices: advisorChoices
+    })
+    return { thinking, advisorThinking }
+  })
+
 export const ompCommand = Command.make("omp", { model, pick, args }, (config) =>
   Effect.gen(function* () {
     if (Option.isSome(config.model) && config.pick) {
@@ -139,9 +199,14 @@ export const ompCommand = Command.make("omp", { model, pick, args }, (config) =>
       })
       const match = free.find((candidate) => candidate.selector === chosen)
       if (match === undefined) return yield* bail(`Model '${chosen}' is not in the free catalog`)
-      const thinking = ladderCeiling(match.thinking)
-      const advisorThinking = advisorLevelFor(match.thinking)
-      yield* Effect.sync(() => writeOmpSessionModel(home, { selector: match.selector, thinking, advisorThinking }))
+      const chosenLevels = yield* pickLevels(match)
+      yield* Effect.sync(() =>
+        writeOmpSessionModel(home, {
+          selector: match.selector,
+          thinking: chosenLevels.thinking,
+          advisorThinking: chosenLevels.advisorThinking
+        })
+      )
     }
 
     const session: OmpSessionModel = (yield* Effect.sync(() => readOmpSessionModel(home))) ??
@@ -163,12 +228,17 @@ export const ompCommand = Command.make("omp", { model, pick, args }, (config) =>
     })
 
     // A level-free model states the model default so the line never shows
-    // an undefined level.
-    const hasLevel = typeof session.thinking === "string" && session.thinking.trim() !== ""
+    // an undefined level. The advisor appears only when it differs, because
+    // a uniform session has nothing extra to report.
+    const level = typeof session.thinking === "string" && session.thinking.trim() !== "" ? session.thinking : undefined
+    const advisor =
+      typeof session.advisorThinking === "string" && session.advisorThinking.trim() !== ""
+        ? session.advisorThinking
+        : undefined
+    const levelText = level === undefined ? "the model default thinking level" : `${level} thinking`
+    const advisorText = advisor !== undefined && advisor !== level ? `, advisor at ${advisor}` : ""
     yield* Console.error(
-      hasLevel
-        ? `Starting omp with ${session.selector} at ${session.thinking} thinking (session only; deployed config unchanged)`
-        : `Starting omp with ${session.selector} at the model default thinking level (session only; deployed config unchanged)`
+      `Starting omp with ${session.selector} at ${levelText}${advisorText} (session only; deployed config unchanged)`
     )
 
     const child = yield* Effect.sync(() =>

package/cli/src/engine-native/ompOverlay.ts

@@ -134,6 +134,43 @@ export function advisorLevelFor(levels: ReadonlyArray<string>): string | undefin
   return advisor ?? (known[0] as string)
 }
 
+/**
+ * What the picker may ask about thinking levels for one model. omp accepts a
+ * `:level` suffix on a role only for a level the model publishes, so the
+ * question set comes from the model own ladder: no ladder means no question,
+ * a single level means no choice to make, and two or more levels mean the
+ * user can split the advisor from the other roles.
+ */
+export type EffortPlan =
+  | { readonly kind: "none" }
+  | { readonly kind: "fixed"; readonly level: string }
+  | { readonly kind: "choose"; readonly levels: ReadonlyArray<string>; readonly highest: string }
+
+export function planEffortChoice(levels: ReadonlyArray<string>): EffortPlan {
+  const known = THINKING_LADDER.filter((level) => levels.includes(level))
+  const only = known[0]
+  if (only === undefined) return { kind: "none" }
+  if (known.length === 1) return { kind: "fixed", level: only }
+  return { kind: "choose", levels: known, highest: known[known.length - 1] as string }
+}
+
+/**
+ * Recommend an advisor level for a chosen main level. The advisor runs quick
+ * review passes, so it sits two steps down the model own ladder, and it
+ * clamps to the lowest level the model publishes. Steps count positions in
+ * that model ladder, not the global ladder, so a sparse ladder such as
+ * `high, max` still recommends a real level.
+ */
+export function advisorRecommendation(
+  levels: ReadonlyArray<string>,
+  main: string
+): string | undefined {
+  const known = THINKING_LADDER.filter((level) => levels.includes(level))
+  const index = known.indexOf(main)
+  if (index < 0) return known[0]
+  return known[Math.max(0, index - 2)]
+}
+
 /**
  * Render the run overlay as YAML text. Empty fallback chains keep a retry
  * from falling back onto a paid model. A model without a level renders bare

package/cli/src/generated/sotPayload.ts

@@ -1,7 +1,7 @@
 // Generated by cli/scripts/generate-sot-payload.ts. DO NOT EDIT.
 // Edit SoT/, notification.mp3, or package.json, then run: bun cli/scripts/generate-sot-payload.ts
 
-export const GENERATED_PACKAGE_VERSION = "0.17.0"
+export const GENERATED_PACKAGE_VERSION = "0.17.1"
 
 export const GENERATED_PAYLOAD_TEXT = {
   "SoT/.agents/skills.txt": "# Universal AI-agent skill manifest intentionally empty.\n# Global skill discovery is opt-in: add one <owner>/<repo> slug per line.\n# EngineNative ignores comments and blank lines.\n",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docks-kit",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "Portable AI coding agent config kit — SoT sync engine + typed CLI for Claude Code, Codex, and universal agent skills",
   "type": "module",
   "license": "MIT",