docks-kit 0.17.0 → 0.17.2

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

@@ -3,14 +3,14 @@
  * config for one run only, so every key that can cause paid spend is set here
  * and every other key falls through to the deployed paid config.
  */
-import { createHash } from "node:crypto"
-import type { OmpSessionModel } from "./harnesses"
+import { createHash } from "node:crypto";
+import type { OmpSessionModel } from "./harnesses";
 
 export interface CatalogModel {
-  readonly selector: string
-  readonly name: string
-  readonly thinking: ReadonlyArray<string>
-  readonly contextWindow: number
+  readonly selector: string;
+  readonly name: string;
+  readonly thinking: ReadonlyArray<string>;
+  readonly contextWindow: number;
 }
 
 /** Thinking levels from lowest to highest effort. */
@@ -21,7 +21,7 @@ export const THINKING_LADDER: ReadonlyArray<string> = [
   "high",
   "xhigh",
   "max",
-]
+];
 
 /**
  * One overlay file per model, so a second launcher on another model cannot
@@ -32,9 +32,9 @@ export const THINKING_LADDER: ReadonlyArray<string> = [
  * two distinct models on two distinct files.
  */
 export function overlayFileName(selector: string): string {
-  const safe = selector.replace(/[^A-Za-z0-9._-]/g, "-")
-  const digest = createHash("sha256").update(selector).digest("hex").slice(0, 8)
-  return `omp-free-${safe}-${digest}.yml`
+  const safe = selector.replace(/[^A-Za-z0-9._-]/g, "-");
+  const digest = createHash("sha256").update(selector).digest("hex").slice(0, 8);
+  return `omp-free-${safe}-${digest}.yml`;
 }
 
 /** Role keys in the order used by SoT/.omp/config.yml for readable diffs. */
@@ -51,7 +51,8 @@ const ROLE_ORDER: ReadonlyArray<string> = [
   "slow",
   "fable",
   "switch_fable",
-]
+  "astra",
+];
 
 /** Retry chain keys in the order used by SoT/.omp/config.yml. */
 const FALLBACK_ORDER: ReadonlyArray<string> = [
@@ -64,7 +65,8 @@ const FALLBACK_ORDER: ReadonlyArray<string> = [
   "commit",
   "switch_fable",
   "fable",
-]
+  "astra",
+];
 
 /**
  * Collect free models from parsed `omp models --json` output. The function is
@@ -73,36 +75,36 @@ const FALLBACK_ORDER: ReadonlyArray<string> = [
  */
 export function parseFreeModels(catalogJson: unknown): ReadonlyArray<CatalogModel> {
   if (typeof catalogJson !== "object" || catalogJson === null || Array.isArray(catalogJson)) {
-    return []
+    return [];
   }
-  const models = (catalogJson as Record<string, unknown>)["models"]
-  if (!Array.isArray(models)) return []
-  const found: Array<CatalogModel> = []
+  const models = (catalogJson as Record<string, unknown>)["models"];
+  if (!Array.isArray(models)) return [];
+  const found: Array<CatalogModel> = [];
   for (const row of models) {
-    if (typeof row !== "object" || row === null || Array.isArray(row)) continue
-    const record = row as Record<string, unknown>
-    const selector = record["selector"]
-    if (typeof selector !== "string" || selector.length === 0) continue
-    const cost = record["cost"]
-    if (typeof cost !== "object" || cost === null || Array.isArray(cost)) continue
-    const charges = cost as Record<string, unknown>
-    if (charges["input"] !== 0 || charges["output"] !== 0) continue
-    const rawName = record["name"]
-    const name = typeof rawName === "string" && rawName.length > 0 ? rawName : selector
-    const rawLevels = record["thinking"]
+    if (typeof row !== "object" || row === null || Array.isArray(row)) continue;
+    const record = row as Record<string, unknown>;
+    const selector = record["selector"];
+    if (typeof selector !== "string" || selector.length === 0) continue;
+    const cost = record["cost"];
+    if (typeof cost !== "object" || cost === null || Array.isArray(cost)) continue;
+    const charges = cost as Record<string, unknown>;
+    if (charges["input"] !== 0 || charges["output"] !== 0) continue;
+    const rawName = record["name"];
+    const name = typeof rawName === "string" && rawName.length > 0 ? rawName : selector;
+    const rawLevels = record["thinking"];
     // Keep only known ladder levels in ladder order so an unknown future
     // level never reaches a role value that omp would reject.
     const thinking = THINKING_LADDER.filter(
       (level) => Array.isArray(rawLevels) && (rawLevels as Array<unknown>).includes(level),
-    )
-    const rawWindow = record["contextWindow"]
+    );
+    const rawWindow = record["contextWindow"];
     const contextWindow =
-      typeof rawWindow === "number" && Number.isFinite(rawWindow) ? rawWindow : 0
-    found.push({ selector, name, thinking, contextWindow })
+      typeof rawWindow === "number" && Number.isFinite(rawWindow) ? rawWindow : 0;
+    found.push({ selector, name, thinking, contextWindow });
   }
   // Sort by selector so the picker list is stable across catalog orderings.
-  found.sort((a, b) => (a.selector < b.selector ? -1 : a.selector > b.selector ? 1 : 0))
-  return found
+  found.sort((a, b) => (a.selector < b.selector ? -1 : a.selector > b.selector ? 1 : 0));
+  return found;
 }
 
 /**
@@ -112,9 +114,9 @@ export function parseFreeModels(catalogJson: unknown): ReadonlyArray<CatalogMode
  */
 export function ladderCeiling(levels: ReadonlyArray<string>): string | undefined {
   for (let index = THINKING_LADDER.length - 1; index >= 0; index -= 1) {
-    if (levels.includes(THINKING_LADDER[index] as string)) return THINKING_LADDER[index] as string
+    if (levels.includes(THINKING_LADDER[index] as string)) return THINKING_LADDER[index] as string;
   }
-  return undefined
+  return undefined;
 }
 
 /**
@@ -124,14 +126,51 @@ export function ladderCeiling(levels: ReadonlyArray<string>): string | undefined
  * never exceeds the ladder ceiling by construction.
  */
 export function advisorLevelFor(levels: ReadonlyArray<string>): string | undefined {
-  const known = THINKING_LADDER.filter((level) => levels.includes(level))
-  if (known.length === 0) return undefined
-  const mediumIndex = THINKING_LADDER.indexOf("medium")
-  let advisor: string | undefined
+  const known = THINKING_LADDER.filter((level) => levels.includes(level));
+  if (known.length === 0) return undefined;
+  const mediumIndex = THINKING_LADDER.indexOf("medium");
+  let advisor: string | undefined;
   for (const level of known) {
-    if ((THINKING_LADDER.indexOf(level) as number) <= (mediumIndex as number)) advisor = level
+    if ((THINKING_LADDER.indexOf(level) as number) <= (mediumIndex as number)) advisor = level;
   }
-  return advisor ?? (known[0] as string)
+  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)];
 }
 
 /**
@@ -140,29 +179,30 @@ export function advisorLevelFor(levels: ReadonlyArray<string>): string | undefin
  * selectors with no thinking keys so the deployed values apply.
  */
 export function renderFreeOverlay(model: OmpSessionModel): string {
-  const thinking = typeof model.thinking === "string" && model.thinking.trim() !== "" ? model.thinking : undefined
-  const lines: Array<string> = ["# Generated per run by docks-kit omp. Edits are overwritten."]
+  const thinking =
+    typeof model.thinking === "string" && model.thinking.trim() !== "" ? model.thinking : undefined;
+  const lines: Array<string> = ["# Generated per run by docks-kit omp. Edits are overwritten."];
   if (thinking !== undefined) {
-    lines.push(`defaultThinkingLevel: ${thinking}`, "modelRoles:")
+    lines.push(`defaultThinkingLevel: ${thinking}`, "modelRoles:");
     const advisor =
       typeof model.advisorThinking === "string" && model.advisorThinking.trim() !== ""
         ? model.advisorThinking
-        : thinking
+        : thinking;
     for (const role of ROLE_ORDER) {
-      lines.push(`  ${role}: ${model.selector}:${role === "advisor" ? advisor : thinking}`)
+      lines.push(`  ${role}: ${model.selector}:${role === "advisor" ? advisor : thinking}`);
     }
-    lines.push("task:", `  maxEffort: ${thinking}`)
+    lines.push("task:", `  maxEffort: ${thinking}`);
   } else {
-    lines.push("modelRoles:")
+    lines.push("modelRoles:");
     for (const role of ROLE_ORDER) {
-      lines.push(`  ${role}: ${model.selector}`)
+      lines.push(`  ${role}: ${model.selector}`);
     }
   }
-  lines.push("retry:", "  fallbackChains:")
+  lines.push("retry:", "  fallbackChains:");
   for (const chain of FALLBACK_ORDER) {
-    lines.push(`    ${chain}: []`)
+    lines.push(`    ${chain}: []`);
   }
-  return `${lines.join("\n")}\n`
+  return `${lines.join("\n")}\n`;
 }
 
 /** Build the omp argv with the overlay flag ahead of the forwarded args. */
@@ -170,5 +210,5 @@ export function buildOmpArgs(
   overlayPath: string,
   passthrough: ReadonlyArray<string>,
 ): ReadonlyArray<string> {
-  return ["--config", overlayPath, ...passthrough]
+  return ["--config", overlayPath, ...passthrough];
 }

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

@@ -7,35 +7,35 @@
  * Resolution reads the environment and probes directory existence only, so a
  * dry run stays free of omp subcommands.
  */
-import { existsSync } from "node:fs"
-import { isAbsolute, resolve } from "node:path"
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
 
-import { p } from "./exec"
+import { p } from "./exec";
 
 /** Upstream CONFIG_DIR_NAME; PI_CONFIG_DIR renames this directory under home. */
-const DEFAULT_CONFIG_DIR_NAME = ".omp"
+const DEFAULT_CONFIG_DIR_NAME = ".omp";
 /** Upstream APP_NAME, the fixed segment under an XDG category root. */
-const APP_NAME = "omp"
+const APP_NAME = "omp";
 /** Upstream PROFILE_NAME_RE. An invalid name degrades to the default profile. */
-const PROFILE_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/
+const PROFILE_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
 /** Windows device aliases upstream rejects, bare or with any extension. */
-const WINDOWS_RESERVED_BASENAME_RE = /^(?:CON|PRN|AUX|NUL|COM[0-9]|LPT[0-9])(?:\..*)?$/i
+const WINDOWS_RESERVED_BASENAME_RE = /^(?:CON|PRN|AUX|NUL|COM[0-9]|LPT[0-9])(?:\..*)?$/i;
 
 export interface OmpPaths {
   /** undefined for the default profile, else the normalized profile name */
-  readonly profile: string | undefined
+  readonly profile: string | undefined;
   /** config root for the active profile */
-  readonly configRoot: string
+  readonly configRoot: string;
   /** directory holding AGENTS.md, config.yml, mcp.json - never XDG-redirected */
-  readonly agentDir: string
+  readonly agentDir: string;
   /** root holding marketplaces.json and plugins/ - XDG-redirected when adopted */
-  readonly dataRoot: string
+  readonly dataRoot: string;
 }
 
 export interface OmpPathInputs {
-  readonly home: string
-  readonly env: Record<string, string | undefined>
-  readonly platform: NodeJS.Platform
+  readonly home: string;
+  readonly env: Record<string, string | undefined>;
+  readonly platform: NodeJS.Platform;
 }
 
 /**
@@ -44,36 +44,47 @@ export interface OmpPathInputs {
  * var cannot crash a bare import.
  */
 function normalizeProfile(value: string | undefined): string | undefined {
-  const name = value?.trim()
-  if (name === undefined || name === "" || name === "default") return undefined
-  if (name === "." || name === ".." || name.endsWith(".")) return undefined
-  if (!PROFILE_NAME_RE.test(name) || WINDOWS_RESERVED_BASENAME_RE.test(name)) return undefined
-  return name
+  const name = value?.trim();
+  if (name === undefined || name === "" || name === "default") return undefined;
+  if (name === "." || name === ".." || name.endsWith(".")) return undefined;
+  if (!PROFILE_NAME_RE.test(name) || WINDOWS_RESERVED_BASENAME_RE.test(name)) return undefined;
+  return name;
 }
 
 /** Upstream applies `path.resolve` to PI_CODING_AGENT_DIR, so cwd anchors a relative value. */
 function resolveAgentOverride(value: string): string {
-  return isAbsolute(value) ? value : resolve(process.cwd(), value)
+  return isAbsolute(value) ? value : resolve(process.cwd(), value);
 }
 
 export function ompPaths({ home, env, platform }: OmpPathInputs): OmpPaths {
   // OMP_PROFILE wins whenever it is defined, including when explicitly empty;
   // PI_PROFILE is only the legacy fallback.
-  const profile = normalizeProfile(env["OMP_PROFILE"] !== undefined ? env["OMP_PROFILE"] : env["PI_PROFILE"])
+  const profile = normalizeProfile(
+    env["OMP_PROFILE"] !== undefined ? env["OMP_PROFILE"] : env["PI_PROFILE"],
+  );
 
   // PI_CONFIG_DIR is a config root dirname joined under home, not a path.
-  const configDirName = env["PI_CONFIG_DIR"]
-  const baseRoot = p(home, configDirName !== undefined && configDirName !== "" ? configDirName : DEFAULT_CONFIG_DIR_NAME)
-  const configRoot = profile === undefined ? baseRoot : p(baseRoot, "profiles", profile)
+  const configDirName = env["PI_CONFIG_DIR"];
+  const baseRoot = p(
+    home,
+    configDirName !== undefined && configDirName !== "" ? configDirName : DEFAULT_CONFIG_DIR_NAME,
+  );
+  const configRoot = profile === undefined ? baseRoot : p(baseRoot, "profiles", profile);
 
   // A named profile derives its own agent directory and ignores the override.
-  const agentOverride = env["PI_CODING_AGENT_DIR"]
-  const defaultAgentDir = p(configRoot, "agent")
-  const agentDir = profile === undefined && agentOverride !== undefined && agentOverride !== ""
-    ? resolveAgentOverride(agentOverride)
-    : defaultAgentDir
+  const agentOverride = env["PI_CODING_AGENT_DIR"];
+  const defaultAgentDir = p(configRoot, "agent");
+  const agentDir =
+    profile === undefined && agentOverride !== undefined && agentOverride !== ""
+      ? resolveAgentOverride(agentOverride)
+      : defaultAgentDir;
 
-  return { profile, configRoot, agentDir, dataRoot: xdgDataRoot(env, platform, profile, agentDir === defaultAgentDir) ?? configRoot }
+  return {
+    profile,
+    configRoot,
+    agentDir,
+    dataRoot: xdgDataRoot(env, platform, profile, agentDir === defaultAgentDir) ?? configRoot,
+  };
 }
 
 /**
@@ -87,15 +98,15 @@ function xdgDataRoot(
   env: Record<string, string | undefined>,
   platform: NodeJS.Platform,
   profile: string | undefined,
-  agentDirIsDefault: boolean
+  agentDirIsDefault: boolean,
 ): string | undefined {
-  if (!agentDirIsDefault) return undefined
-  if (platform !== "linux" && platform !== "darwin") return undefined
+  if (!agentDirIsDefault) return undefined;
+  if (platform !== "linux" && platform !== "darwin") return undefined;
 
-  const dataHome = env["XDG_DATA_HOME"]
-  if (dataHome === undefined || dataHome === "") return undefined
+  const dataHome = env["XDG_DATA_HOME"];
+  if (dataHome === undefined || dataHome === "") return undefined;
 
-  const appRoot = p(dataHome, APP_NAME)
-  const candidate = profile === undefined ? appRoot : p(appRoot, "profiles", profile)
-  return existsSync(candidate) ? candidate : undefined
+  const appRoot = p(dataHome, APP_NAME);
+  const candidate = profile === undefined ? appRoot : p(appRoot, "profiles", profile);
+  return existsSync(candidate) ? candidate : undefined;
 }

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

@@ -0,0 +1,170 @@
+/**
+ * EngineNative omp plugin pass: marketplace-plugin install/upgrade plus the
+ * pinned pi-intercom npm plugin. Split from ompSync.ts; the orchestration
+ * still lives there.
+ */
+import { spawnProcess } from "./exec";
+import { recordFailure } from "./failures";
+import type { Ctx } from "./index";
+import { isObject, parseJson } from "./jq";
+import { firstOutputLine } from "./ompMarketplace";
+import { field } from "./toolchain";
+
+const MARKETPLACE_PLUGIN_IDS = ["docks@docks", "plan-lifecycle@docks"] as const;
+
+// -------------------------------------------------------------- plugins ----
+
+interface InstalledPlugins {
+  readonly marketplace: Set<string>;
+  readonly npm: Map<string, string>;
+}
+
+async function installedPluginIdsFromCli(): Promise<InstalledPlugins | undefined> {
+  const result = await spawnProcess("omp", ["plugin", "list", "--json"], {
+    stdio: ["ignore", "pipe", "ignore"],
+  });
+  if (result.error !== undefined || result.exitCode !== 0) return undefined;
+
+  const value = parseJson(result.stdout);
+  if (
+    value === undefined ||
+    !isObject(value) ||
+    !Array.isArray(value["marketplace"]) ||
+    !Array.isArray(value["npm"])
+  ) {
+    return undefined;
+  }
+
+  // `omp plugin list --json` reports marketplace rows as
+  // `{ id: "<plugin>@<marketplace>", scope, entries: [...] }` - the composite id
+  // is already the token `omp plugin install/upgrade` takes. omp emits one row
+  // per scope holding the plugin, so a match found only in a `project` row
+  // means the user scope is empty and `upgrade --scope user` would fail; only a
+  // `user` row counts as installed for this pipeline.
+  const marketplace = new Set<string>();
+  for (const row of value["marketplace"]) {
+    if (!isObject(row) || typeof row["id"] !== "string" || row["scope"] !== "user") continue;
+    marketplace.add(row["id"]);
+  }
+
+  const npm = new Map<string, string>();
+  for (const row of value["npm"]) {
+    if (!isObject(row) || typeof row["name"] !== "string" || typeof row["version"] !== "string")
+      continue;
+    npm.set(row["name"], row["version"]);
+  }
+  return { marketplace, npm };
+}
+
+async function runPluginCommand(
+  ctx: Ctx,
+  plugin: string,
+  args: ReadonlyArray<string>,
+): Promise<boolean> {
+  const { clearProgress, progress } = ctx.services.logger;
+  progress(`Updating omp plugin ${plugin}...`);
+  const result = await spawnProcess("omp", args, { stdio: ["ignore", "pipe", "pipe"] });
+  clearProgress();
+  if (result.error === undefined && result.exitCode === 0) return true;
+
+  recordFailure(
+    ctx,
+    `omp plugin operation failed for ${plugin}: ${firstOutputLine(result)}; run manually: omp ${args.join(" ")}`,
+  );
+  return false;
+}
+
+export async function syncPlugins(ctx: Ctx): Promise<number> {
+  const { change, clearProgress, echo, progress, verbose, warn } = ctx.services.logger;
+
+  if (ctx.dryRun) {
+    const piIntercomPin = field("pi-intercom", "verified");
+    for (const pluginId of MARKETPLACE_PLUGIN_IDS) {
+      echo(`[dry-run] omp plugin install --scope user ${pluginId}`);
+    }
+    if (piIntercomPin === "") {
+      warn(
+        "pi-intercom install skipped because SoT/toolchain.json has no verified pi-intercom pin",
+      );
+    } else {
+      echo(`[dry-run] omp install pi-intercom@${piIntercomPin}`);
+    }
+    return 0;
+  }
+
+  if (ctx.services.deps.probe("omp").state === "missing") {
+    ctx.services.deps.warnMissing(
+      "omp",
+      ctx.services.logger,
+      "deployed omp config only — marketplace and plugin passes skipped; re-run sync after installing",
+    );
+    return 0;
+  }
+  if (ctx.services.deps.probe("git").state === "missing") {
+    ctx.services.deps.warnMissing(
+      "git",
+      ctx.services.logger,
+      "plugin marketplaces are git repos — omp plugin refresh skipped; re-run sync after installing",
+    );
+    return 0;
+  }
+  const piIntercomPin = field("pi-intercom", "verified");
+
+  progress("Checking installed omp plugins...");
+  const installed = await installedPluginIdsFromCli();
+  clearProgress();
+  if (installed === undefined) {
+    warn("omp plugin inventory unavailable — falling back to the full refresh path");
+  }
+
+  let pluginsInstalled =
+    installed === undefined
+      ? 0
+      : MARKETPLACE_PLUGIN_IDS.filter((pluginId) => installed.marketplace.has(pluginId)).length +
+        (piIntercomPin !== "" && installed.npm.has("pi-intercom") ? 1 : 0);
+  let operationsSucceeded = 0;
+
+  for (const pluginId of MARKETPLACE_PLUGIN_IDS) {
+    const present = installed?.marketplace.has(pluginId) === true;
+    if (present && ctx.skipPluginRefresh === true) {
+      verbose(`omp plugin ${pluginId} already installed; refresh-only update skipped`);
+      continue;
+    }
+
+    const args = present
+      ? ["plugin", "upgrade", "--scope", "user", pluginId]
+      : ["plugin", "install", "--scope", "user", pluginId];
+    if (await runPluginCommand(ctx, pluginId, args)) {
+      operationsSucceeded++;
+      if (!present) pluginsInstalled++;
+    }
+  }
+
+  if (piIntercomPin === "") {
+    warn("pi-intercom install skipped because SoT/toolchain.json has no verified pi-intercom pin");
+  } else {
+    const installedVersion = installed?.npm.get("pi-intercom");
+    const present = installedVersion !== undefined;
+    if (installedVersion === piIntercomPin) {
+      verbose(`omp npm plugin pi-intercom already installed at ${piIntercomPin}`);
+    } else if (present && ctx.skipPluginRefresh === true) {
+      verbose("omp npm plugin pi-intercom already installed; refresh-only update skipped");
+    } else {
+      const args = present
+        ? ["install", "--force", `pi-intercom@${piIntercomPin}`]
+        : ["install", `pi-intercom@${piIntercomPin}`];
+      if (await runPluginCommand(ctx, "pi-intercom", args)) {
+        operationsSucceeded++;
+        if (!present) pluginsInstalled++;
+      }
+    }
+  }
+
+  if (operationsSucceeded > 0) {
+    change(`omp plugins synced (plugins: ~${operationsSucceeded})`);
+    ctx.nextStepTriggers.ompRestart = true;
+  } else {
+    verbose("omp plugins already in sync");
+  }
+  return pluginsInstalled;
+}