docks-kit 0.4.0 → 0.6.0

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

@@ -7,6 +7,7 @@
 import { p } from "./exec"
 import { readFileSync, renameSync, writeFileSync } from "node:fs"
 
+import { resolveEffort } from "../efforts"
 import type { Ctx } from "./index"
 
 export function replaceTopLevelSetting(content: string, key: string, replacement: string): string {
@@ -48,27 +49,59 @@ export function replaceTopLevelSettingInFile(file: string, key: string, replacem
   return true
 }
 
-export function syncCodexModel(ctx: Ctx, model: string): void {
+interface CodexSettingEdit {
+  readonly tag: string
+  readonly key: "model" | "model_reasoning_effort"
+  readonly value: string
+  readonly changed: string
+  readonly unchanged: string
+}
+
+function syncCodexSetting(ctx: Ctx, edit: CodexSettingEdit): void {
   const { change, echo, verbose, warn } = ctx.services.logger
   const userCodexSettings = p(ctx.home, ".codex", "config.toml")
 
-  if (model === "") return
-
   if (ctx.dryRun) {
-    echo(`[dry-run] (--codex-model) set model = "${model}" in ${userCodexSettings}`)
+    echo(`[dry-run] (${edit.tag}) set ${edit.key} = "${edit.value}" in ${userCodexSettings}`)
     return
   }
 
   try {
     readFileSync(userCodexSettings)
   } catch {
-    warn(`(--codex-model) ${userCodexSettings} missing — skipped`)
+    warn(`(${edit.tag}) ${userCodexSettings} missing — skipped`)
     return
   }
-  if (replaceTopLevelSettingInFile(userCodexSettings, "model", `model = "${model}"`)) {
-    change(`Model: deployed Codex model set to ${model} (SoT unchanged; flag-less sync reverts)`)
+  if (replaceTopLevelSettingInFile(userCodexSettings, edit.key, `${edit.key} = "${edit.value}"`)) {
+    change(edit.changed)
     ctx.nextStepTriggers.codexRestart = true
   } else {
-    verbose(`Model: deployed Codex model already ${model}`)
+    verbose(edit.unchanged)
   }
 }
+
+export function syncCodexModel(ctx: Ctx, model: string): void {
+  if (model === "") return
+  syncCodexSetting(ctx, {
+    tag: "--codex-model",
+    key: "model",
+    value: model,
+    changed: `Model: deployed Codex model set to ${model} (SoT unchanged; flag-less sync reverts)`,
+    unchanged: `Model: deployed Codex model already ${model}`
+  })
+}
+
+export function syncCodexEffort(ctx: Ctx, effort: string): void {
+  if (effort === "") return
+  const resolved = resolveEffort("codex", effort)
+  const useDefault = effort === "default"
+  syncCodexSetting(ctx, {
+    tag: "--codex-effort",
+    key: "model_reasoning_effort",
+    value: resolved,
+    changed: useDefault
+      ? `Effort: deployed Codex model_reasoning_effort set to ${resolved} (SoT default)`
+      : `Effort: deployed Codex model_reasoning_effort set to ${resolved} (SoT unchanged; flag-less sync reverts)`,
+    unchanged: `Effort: deployed Codex model_reasoning_effort already ${resolved}`
+  })
+}

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

@@ -15,7 +15,14 @@ import { claudeNextSteps, claudeSummary, claudeSync } from "./claudeSync"
 import { codexNextSteps, codexSummary, codexSync } from "./codexSync"
 import { skillsNextSteps, skillsSummary, skillsSync } from "./skillsSync"
 import { modeModel, modeToolchain } from "./modes"
-import { ExitError, parseArgs, validateModelFlags } from "./parseArgs"
+import { ExitError, parseArgs, validateModifierFlags } from "./parseArgs"
+
+export type ModifierFlag =
+  | "--claude-model"
+  | "--claude-effort"
+  | "--claude-advisor"
+  | "--codex-model"
+  | "--codex-effort"
 
 export interface Ctx {
   readonly repoDir: string
@@ -31,7 +38,12 @@ export interface Ctx {
   claudePermissive: boolean
   claudePlugins: Array<string>
   claudeModel: string
+  claudeEffort: string
+  claudeAdvisor: string
   codexModel: string
+  codexEffort: string
+  /** Distinguishes an explicitly empty modifier from an option that was not supplied. */
+  modifierFlags?: Set<ModifierFlag>
   /** Injected capability seam (logger/deps/platform) — see services.ts. */
   readonly services: EngineServices
   bunRuntime?: BunRuntimeState
@@ -66,7 +78,11 @@ function makeCtx(services: EngineServices): Ctx {
     claudePermissive: env["CLAUDE_PERMISSIVE"] === "1",
     claudePlugins: (env["CLAUDE_PLUGINS"] ?? "").split(" ").filter((s) => s !== ""),
     claudeModel: env["CLAUDE_MODEL"] ?? "",
+    claudeEffort: "",
+    claudeAdvisor: "",
     codexModel: env["CODEX_MODEL"] ?? "",
+    codexEffort: "",
+    modifierFlags: new Set(),
     services,
     targetFilterSet: false,
     syncClaude: false,
@@ -79,7 +95,7 @@ function makeCtx(services: EngineServices): Ctx {
 function engineSync(ctx: Ctx, args: ReadonlyArray<string>): number {
   const { echo } = ctx.services.logger
   parseArgs(ctx, args)
-  validateModelFlags(ctx)
+  validateModifierFlags(ctx)
 
   const claudeRan = ctx.syncClaude
   const claudeRuntime = claudeRan ? claudeSync(ctx) : undefined

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

@@ -6,7 +6,7 @@ import { p } from "./exec"
 import { readFileSync } from "node:fs"
 import { payloadText } from "../payload"
 
-import { syncClaudeModel } from "./claudeModel"
+import { syncClaudeModel } from "./claudeSettingsModifiers"
 import { syncCodexModel } from "./codexToml"
 import type { Ctx } from "./index"
 import { isObject, parseJson, type Json } from "./jq"

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

@@ -4,7 +4,17 @@
  * early parser exit and is caught once in runEngineNative.
  */
 
-import type { Ctx } from "./index"
+import type { Ctx, ModifierFlag } from "./index"
+import {
+  CLAUDE_ADVISOR_STATES,
+  advisorCatalog,
+  advisorFlagGrammar,
+  advisorValueGrammar,
+  effortCatalog,
+  effortFlagGrammar,
+  effortValueGrammar,
+  isEffortModifierValue
+} from "../efforts"
 import { printModels, validateClaudeModel, validateCodexModel } from "./models"
 
 export class ExitError extends Error {
@@ -14,6 +24,13 @@ export class ExitError extends Error {
 }
 
 const KNOWN_CLAUDE_OPTIN_PLUGINS = ["supabase", "n8n"]
+const MODIFIER_FLAGS = new Set<ModifierFlag>([
+  "--claude-model",
+  "--claude-effort",
+  "--claude-advisor",
+  "--codex-model",
+  "--codex-effort"
+])
 
 function usage(ctx: Ctx): void {
   const { echo } = ctx.services.logger
@@ -41,6 +58,8 @@ function usage(ctx: Ctx): void {
   echo(
     "  --claude-model=<m>            set deployed ~/.claude/settings.json model (aliases: best|opus|fable|sonnet|haiku, full claude-* IDs, or 'default' to unset)"
   )
+  echo(`  ${effortFlagGrammar("claude").padEnd(39)} set deployed effortLevel`)
+  echo(`  ${advisorFlagGrammar().padEnd(39)} set deployed advisor state`)
   echo(
     "  --claude-compact-window=<n>   set deployed autocompact window in tokens (e.g. 680000 or 680k) for disposable sessions"
   )
@@ -48,6 +67,7 @@ function usage(ctx: Ctx): void {
     "  --claude-permissive           empty permissions.ask/deny in deployed settings (sandboxes/containers; unattended commits + pushes)"
   )
   echo("  --codex-model=<m>             set deployed ~/.codex/config.toml model (e.g. gpt-5.5)")
+  echo(`  ${effortFlagGrammar("codex").padEnd(39)} set deployed model_reasoning_effort`)
   echo("")
   echo("Sticky opt-ins (installed + enabled until --prune)")
   echo(
@@ -81,9 +101,42 @@ function selectTarget(ctx: Ctx, target: string): void {
   ctx.targetFilterSet = true
 }
 
+function setModifier(ctx: Ctx, flag: ModifierFlag, value: string): void {
+  switch (flag) {
+    case "--claude-model":
+      ctx.claudeModel = value
+      break
+    case "--claude-effort":
+      ctx.claudeEffort = value
+      break
+    case "--claude-advisor":
+      ctx.claudeAdvisor = value
+      break
+    case "--codex-model":
+      ctx.codexModel = value
+      break
+    case "--codex-effort":
+      ctx.codexEffort = value
+      break
+  }
+  const flags = ctx.modifierFlags ?? new Set<ModifierFlag>()
+  flags.add(flag)
+  ctx.modifierFlags = flags
+}
+
+function isModifierFlag(value: string): value is ModifierFlag {
+  return MODIFIER_FLAGS.has(value as ModifierFlag)
+}
+
 export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
   const { err } = ctx.services.logger
-  for (const arg of args) {
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] ?? ""
+    if (isModifierFlag(arg) && args[index + 1] === "") {
+      setModifier(ctx, arg, "")
+      index += 1
+      continue
+    }
     switch (arg) {
       case "claude":
       case "codex":
@@ -116,6 +169,18 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
         printModels(ctx, "codex")
         err("--codex-model requires a value: --codex-model=<model>")
         throw new ExitError(2)
+      case "--claude-effort":
+        printCatalog(ctx, effortCatalog("claude"))
+        err(`--claude-effort requires a value: ${effortFlagGrammar("claude")}`)
+        throw new ExitError(2)
+      case "--codex-effort":
+        printCatalog(ctx, effortCatalog("codex"))
+        err(`--codex-effort requires a value: ${effortFlagGrammar("codex")}`)
+        throw new ExitError(2)
+      case "--claude-advisor":
+        printCatalog(ctx, advisorCatalog())
+        err(`--claude-advisor requires a value: ${advisorFlagGrammar()}`)
+        throw new ExitError(2)
       case "--claude-compact-window":
         err("--claude-compact-window requires a value: --claude-compact-window=<tokens> (e.g. 680k)")
         throw new ExitError(2)
@@ -159,9 +224,15 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
         break
     }
     if (arg.startsWith("--claude-model=")) {
-      ctx.claudeModel = arg.slice("--claude-model=".length)
+      setModifier(ctx, "--claude-model", arg.slice("--claude-model=".length))
     } else if (arg.startsWith("--codex-model=")) {
-      ctx.codexModel = arg.slice("--codex-model=".length)
+      setModifier(ctx, "--codex-model", arg.slice("--codex-model=".length))
+    } else if (arg.startsWith("--claude-effort=")) {
+      setModifier(ctx, "--claude-effort", arg.slice("--claude-effort=".length))
+    } else if (arg.startsWith("--codex-effort=")) {
+      setModifier(ctx, "--codex-effort", arg.slice("--codex-effort=".length))
+    } else if (arg.startsWith("--claude-advisor=")) {
+      setModifier(ctx, "--claude-advisor", arg.slice("--claude-advisor=".length))
     } else if (arg.startsWith("--claude-compact-window=")) {
       const parsed = parseCompactWindow(arg.slice("--claude-compact-window=".length))
       if (parsed === undefined) {
@@ -184,9 +255,15 @@ export function parseArgs(ctx: Ctx, args: ReadonlyArray<string>): void {
   }
 }
 
-export function validateModelFlags(ctx: Ctx): void {
+function printCatalog(ctx: Ctx, catalog: string): void {
+  for (const line of catalog.split("\n")) ctx.services.logger.echo(line)
+}
+
+export function validateModifierFlags(ctx: Ctx): void {
   const { err, warn } = ctx.services.logger
-  if (ctx.claudeModel !== "") {
+  const supplied = (flag: ModifierFlag, value: string): boolean =>
+    value !== "" || ctx.modifierFlags?.has(flag) === true
+  if (supplied("--claude-model", ctx.claudeModel)) {
     if (!ctx.syncClaude) {
       warn("--claude-model ignored: claude target not selected")
       ctx.claudeModel = ""
@@ -196,7 +273,27 @@ export function validateModelFlags(ctx: Ctx): void {
       throw new ExitError(2)
     }
   }
-  if (ctx.codexModel !== "") {
+  if (supplied("--claude-effort", ctx.claudeEffort)) {
+    if (!ctx.syncClaude) {
+      warn("--claude-effort ignored: claude target not selected")
+      ctx.claudeEffort = ""
+    } else if (!isEffortModifierValue("claude", ctx.claudeEffort)) {
+      printCatalog(ctx, effortCatalog("claude"))
+      err(`Invalid Claude effort '${ctx.claudeEffort}' — valid: ${effortValueGrammar("claude")}`)
+      throw new ExitError(2)
+    }
+  }
+  if (supplied("--claude-advisor", ctx.claudeAdvisor)) {
+    if (!ctx.syncClaude) {
+      warn("--claude-advisor ignored: claude target not selected")
+      ctx.claudeAdvisor = ""
+    } else if (!CLAUDE_ADVISOR_STATES.some((state) => state === ctx.claudeAdvisor)) {
+      printCatalog(ctx, advisorCatalog())
+      err(`Invalid Claude advisor state '${ctx.claudeAdvisor}' — valid: ${advisorValueGrammar()}`)
+      throw new ExitError(2)
+    }
+  }
+  if (supplied("--codex-model", ctx.codexModel)) {
     if (!ctx.syncCodex) {
       warn("--codex-model ignored: codex target not selected")
       ctx.codexModel = ""
@@ -206,4 +303,14 @@ export function validateModelFlags(ctx: Ctx): void {
       throw new ExitError(2)
     }
   }
+  if (supplied("--codex-effort", ctx.codexEffort)) {
+    if (!ctx.syncCodex) {
+      warn("--codex-effort ignored: codex target not selected")
+      ctx.codexEffort = ""
+    } else if (!isEffortModifierValue("codex", ctx.codexEffort)) {
+      printCatalog(ctx, effortCatalog("codex"))
+      err(`Invalid Codex effort '${ctx.codexEffort}' — valid: ${effortValueGrammar("codex")}`)
+      throw new ExitError(2)
+    }
+  }
 }

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

@@ -0,0 +1,94 @@
+import { spawnSync } from "node:child_process"
+
+import { isObject, parseJson } from "./jq"
+
+const SESSION_RELAY_PLUGIN_ID = "session-relay@docks"
+
+export type SessionRelayReadinessReason =
+  | "codex_cli_unavailable"
+  | "plugin_list_failed"
+  | "invalid_plugin_list"
+  | "plugin_missing"
+  | "plugin_ambiguous"
+  | "plugin_not_installed"
+  | "plugin_disabled"
+
+export interface SessionRelayReadiness {
+  readonly schema: 1
+  readonly state: "ready" | "unavailable"
+  readonly reason: SessionRelayReadinessReason | null
+  readonly version: string | null
+  readonly installed: boolean
+  readonly enabled: boolean
+  readonly scope: "new_sessions"
+}
+
+export interface CodexPluginListProbe {
+  readonly status: number | null
+  readonly stdout: string
+  readonly errorCode: string | null
+}
+
+function unavailable(
+  reason: SessionRelayReadinessReason,
+  fields: { version?: string | null; installed?: boolean; enabled?: boolean } = {}
+): SessionRelayReadiness {
+  return {
+    schema: 1,
+    state: "unavailable",
+    reason,
+    version: fields.version ?? null,
+    installed: fields.installed ?? false,
+    enabled: fields.enabled ?? false,
+    scope: "new_sessions"
+  }
+}
+
+export function classifySessionRelayReadiness(probe: CodexPluginListProbe): SessionRelayReadiness {
+  if (probe.errorCode === "ENOENT") return unavailable("codex_cli_unavailable")
+  if (probe.errorCode !== null || probe.status !== 0) return unavailable("plugin_list_failed")
+
+  const value = parseJson(probe.stdout)
+  if (value === undefined || !isObject(value) || !Array.isArray(value["installed"])) {
+    return unavailable("invalid_plugin_list")
+  }
+
+  const matches = value["installed"].filter(
+    (entry) => isObject(entry) && entry["pluginId"] === SESSION_RELAY_PLUGIN_ID
+  )
+  if (matches.length === 0) return unavailable("plugin_missing")
+  if (matches.length !== 1) return unavailable("plugin_ambiguous")
+
+  const row = matches[0]
+  if (row === undefined || !isObject(row)) return unavailable("invalid_plugin_list")
+  const version = row["version"]
+  const installed = row["installed"]
+  const enabled = row["enabled"]
+  if (typeof version !== "string" || version.length === 0 || typeof installed !== "boolean" || typeof enabled !== "boolean") {
+    return unavailable("invalid_plugin_list")
+  }
+  if (!installed) return unavailable("plugin_not_installed", { version, enabled })
+  if (!enabled) return unavailable("plugin_disabled", { version, installed })
+
+  return {
+    schema: 1,
+    state: "ready",
+    reason: null,
+    version,
+    installed,
+    enabled,
+    scope: "new_sessions"
+  }
+}
+
+export function sessionRelayReadiness(): SessionRelayReadiness {
+  const result = spawnSync("codex", ["plugin", "list", "--json"], {
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "ignore"]
+  })
+  return classifySessionRelayReadiness({
+    status: result.status,
+    stdout: result.stdout ?? "",
+    errorCode: (result.error as NodeJS.ErrnoException | undefined)?.code ?? null
+  })
+}