omp-llm-role 1.0.0 → 1.2.0

package/src/features.ts

@@ -0,0 +1,105 @@
+/**
+ * Opt-in capability presets (issue #40): one named flag per capability, each
+ * applying the plugin's recommended settings to a role. This module is the
+ * single source of truth for the registry and the single implementation of the
+ * precedence rule (`expandFeatures`), consumed by `resolveSettings` and (phase 2)
+ * the explorer's rank/explain handlers.
+ *
+ * Dual-runtime rule: only `node:` builtins, relative imports with explicit `.ts`
+ * extensions, `import type` for types.
+ */
+
+import type { RoleDef } from "./engine.ts";
+
+export type FeatureId = "endpointCeilings" | "cachePricing" | "providerPinning" | "costCap";
+
+export type FeatureRow = {
+  id: FeatureId;
+  label: string;
+  description: string;
+  /** The recommended settings the flag applies. A bundle value is either a
+   * scalar knob or a per-model policy field (`preferOwnProvider`). */
+  recommended: { filters?: { tools?: boolean; minOutputTokens?: number; maxPriceUsdPerM?: number; preferredMinThroughput?: number }; cacheHitRate?: number; preferOwnProvider?: true };
+  /** What the flag buys, for `--list-features` and the docs. */
+  buys: string;
+};
+
+export const FEATURES: readonly FeatureRow[] = [
+  {
+    id: "endpointCeilings",
+    label: "Endpoint capability ceilings",
+    description: "Drop routes that cannot call tools and routes whose output ceiling is below 16 384 tokens",
+    recommended: { filters: { tools: true, minOutputTokens: 16384 } },
+    buys: "routes that cannot call tools and routes whose output ceiling is below 16 384 tokens leave the pool — a reasoning model is not cut off mid-thought",
+  },
+  {
+    id: "cachePricing",
+    label: "Cache-read pricing",
+    description: "Price the role on a cache-heavy agent loop's invoice (cacheHitRate 0.5) instead of the sticker price",
+    recommended: { cacheHitRate: 0.5 },
+    buys: "the role is priced on a cache-heavy agent loop's invoice (the endpoint's cacheReadPrice blended in) rather than the sticker price",
+  },
+  {
+    id: "providerPinning",
+    label: "Best-route provider pinning",
+    // Per-model policy, not a scalar slug: the sensible pin differs per model,
+    // so the bundle carries `preferOwnProvider` (evaluated against the model's
+    // best route at rank time). It changes no eligibility — a model with no
+    // candidate route keeps the default 1/price² blend.
+    description: "Bind each request to the model's best provider route (per-model policy; never drops a model) and prefer routes at or above 50 tok/s",
+    recommended: { preferOwnProvider: true, filters: { preferredMinThroughput: 50 } },
+    buys: "each request is bound to the model's best provider route — the selector gains @<slug> — and the fallback chain carries the same model on its next-best providers plus each fallback model on its best providers, so a down route fails over within the model's own routes; a soft 50 tok/s floor deprioritizes a pathologically slow route without dropping it",
+  },
+  {
+    id: "costCap",
+    label: "Cost cap",
+    description: "Drop the priciest tail of the eligible pool (maxPriceUsdPerM 10)",
+    recommended: { filters: { maxPriceUsdPerM: 10 } },
+    buys: "the priciest tail of the eligible pool leaves it, so the pick cannot be an expensive outlier",
+  },
+];
+
+export function featureById(id: string): FeatureRow | null {
+  return FEATURES.find((f) => f.id === id) ?? null;
+}
+
+/** Render a bundle as `key=value` pairs for `--list-features`. */
+function formatBundle(rec: FeatureRow["recommended"]): string {
+  const parts: string[] = [];
+  if (rec.filters?.tools !== undefined) parts.push(`filters.tools=${rec.filters.tools}`);
+  if (rec.filters?.minOutputTokens !== undefined) parts.push(`filters.minOutputTokens=${rec.filters.minOutputTokens}`);
+  if (rec.filters?.maxPriceUsdPerM !== undefined) parts.push(`filters.maxPriceUsdPerM=${rec.filters.maxPriceUsdPerM}`);
+  if (rec.filters?.preferredMinThroughput !== undefined) parts.push(`filters.preferredMinThroughput=${rec.filters.preferredMinThroughput}`);
+  if (rec.cacheHitRate !== undefined) parts.push(`cacheHitRate=${rec.cacheHitRate}`);
+  if (rec.preferOwnProvider !== undefined) parts.push(`preferOwnProvider=${rec.preferOwnProvider}`);
+  return parts.join(", ");
+}
+
+/** One human-readable line per feature for `--list-features`. */
+export function formatFeatures(): string {
+  return FEATURES.map((f) => `${f.id} — ${f.label}: ${f.buys} [${formatBundle(f.recommended)}]`).join("\n");
+}
+
+/** The ONE implementation of the precedence rule. Fills only the knobs the
+ * authored def does NOT already set, then strips `features` from the result.
+ * Never mutates `authored`. */
+export function expandFeatures(authored: RoleDef, globalFlags: Record<string, boolean>): RoleDef {
+  const out = structuredClone(authored) as RoleDef;
+  delete out.features;
+  for (const row of FEATURES) {
+    const authoredFlag = authored.features?.[row.id];
+    const on = authoredFlag !== undefined ? authoredFlag : globalFlags[row.id] === true;
+    if (!on) continue;
+    const rec = row.recommended;
+    if (rec.filters) {
+      const f = (out.filters ??= {});
+      if (rec.filters.tools !== undefined && f.tools === undefined) f.tools = rec.filters.tools;
+      if (rec.filters.minOutputTokens !== undefined && f.minOutputTokens === undefined) f.minOutputTokens = rec.filters.minOutputTokens;
+      if (rec.filters.maxPriceUsdPerM !== undefined && f.maxPriceUsdPerM === undefined) f.maxPriceUsdPerM = rec.filters.maxPriceUsdPerM;
+      if (rec.filters.preferredMinThroughput !== undefined && f.preferredMinThroughput === undefined) f.preferredMinThroughput = rec.filters.preferredMinThroughput;
+    }
+    if (rec.cacheHitRate !== undefined && out.cacheHitRate === undefined) out.cacheHitRate = rec.cacheHitRate;
+    if (rec.preferOwnProvider !== undefined && out.preferOwnProvider === undefined) out.preferOwnProvider = rec.preferOwnProvider;
+  }
+  return out;
+}

package/src/project-registry.ts

@@ -0,0 +1,65 @@
+/**
+ * The plugin's memory of the projects where `/project-roles` was used: a small
+ * JSON file in the **global** agent dir (never a project's `.omp`), so the
+ * explorer can list every project-scoped role set without scanning the
+ * filesystem.
+ *
+ * Written by the project-aware `runUpdater` on any project-scoped run — before
+ * the day-gate early return, so a day-stamped no-op session start still
+ * registers — pruned of entries whose project lock file is gone, and replaced
+ * atomically (temp + rename) so two sessions in different repos cannot
+ * interleave into a corrupt file. Reading is pure and tolerant: a missing or
+ * unparseable file yields [].
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { isRecord } from "./guards.ts";
+import { projectLockPath } from "./settings.ts";
+import { agentDir } from "./state.ts";
+
+/** Registry file name inside the agent dir. */
+export const PROJECT_REGISTRY_FILE = "llm-role-projects.json";
+
+export type ProjectRegistryEntry = { root: string; lastUsed: string };
+
+/** Read the registry. Missing, unparseable, or unexpected-shape → []. */
+export function readProjectRegistry(dir = agentDir()): ProjectRegistryEntry[] {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(join(dir, PROJECT_REGISTRY_FILE), "utf8"));
+  } catch {
+    return [];
+  }
+  if (!isRecord(parsed) || !Array.isArray(parsed.projects)) return [];
+  const out: ProjectRegistryEntry[] = [];
+  for (const entry of parsed.projects) {
+    if (!isRecord(entry) || typeof entry.root !== "string" || entry.root.length === 0) continue;
+    out.push({ root: entry.root, lastUsed: typeof entry.lastUsed === "string" ? entry.lastUsed : "" });
+  }
+  return out;
+}
+
+/** Atomic replace (temp + rename) so concurrent writers cannot corrupt the file. */
+function writeProjectRegistry(entries: ProjectRegistryEntry[], dir: string): void {
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, PROJECT_REGISTRY_FILE);
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify({ projects: entries }, null, 2)}\n`);
+  renameSync(tmp, path);
+}
+
+/**
+ * Upsert `root` (stamped now) and prune entries whose project lock file is gone.
+ * Best-effort: a write failure is logged, never thrown — the registry is a
+ * convenience index, not a run prerequisite.
+ */
+export function registerProject(root: string, dir = agentDir()): void {
+  try {
+    const kept = readProjectRegistry(dir).filter((entry) => entry.root !== root && existsSync(projectLockPath(entry.root)));
+    kept.push({ root, lastUsed: new Date().toISOString() });
+    writeProjectRegistry(kept, dir);
+  } catch (err) {
+    console.error(`omp-llm-role: could not update the project registry: ${err instanceof Error ? err.message : err}`);
+  }
+}

package/src/project-setup.ts

@@ -0,0 +1,382 @@
+/**
+ * `/project-roles` core: a discovered project profile -> a project-scoped role
+ * set (kept shipped roles, dropped ones, new fitted roles) written to the
+ * project plugin settings lock file, plus the project agents for the new roles.
+ *
+ * Dual-runtime safe: `node:` builtins + relative `.ts` imports only, no SDK
+ * import. The extension command does the LLM work (profile discovery, benchmark
+ * discovery, agent authoring) and calls `setupProject`; the project-aware
+ * updater (a later task) writes the project `modelRoles`.
+ *
+ * All-or-nothing: every check (names, metrics, weight math, the force gate, the
+ * agent-file collisions) runs before any write, so a rejected plan leaves the
+ * lock file and the agents dir untouched.
+ */
+
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { AGENT_NAME_RE, RESERVED_AGENT_NAMES, projectAgentsDir } from "./agent-file.ts";
+import {
+  applyFocusBenchmarks,
+  checkWeightMath,
+  createAgent,
+  resolveRole,
+  tokenizeArgs,
+  type AgentSpec,
+  type CreateAgentRequest,
+  type FocusCoverage,
+} from "./agent-create.ts";
+import type { RoleDef, SuffixLevel } from "./engine.ts";
+import { FEATURES, featureById } from "./features.ts";
+import { isRecord } from "./guards.ts";
+import { validateRole, writeRoleSettings } from "./role-settings.ts";
+import { DEFAULT_ROLES, isKnownMetric, readPluginSettingsMap, resolveSettings, roleUniverse } from "./settings.ts";
+
+/** One role the profile proposes: a shipped role to keep/drop, or a new role to fit. */
+export type ProposedRole = {
+  name: string;
+  purpose: string;
+  /** For a shipped role: keep (default) or drop. A new role with `keep: false` is not added. */
+  keep?: boolean;
+  /** Metric names the new role is ranked on (links resolved by the extension). */
+  benchmarks?: string[];
+  thinking?: SuffixLevel;
+  tools?: string[];
+  /** The architect's output, when the extension ran it. */
+  spec?: AgentSpec;
+};
+
+/** The discovered project usecase. */
+export type ProjectProfile = {
+  summary: string;
+  domain: string;
+  primaryWork: string[];
+  stack: string[];
+  needs: string[];
+  roles: ProposedRole[];
+};
+
+export type SetupProjectOpts = {
+  /** omp's project dir: `<cwd>/.omp`. */
+  projectDir: string;
+  /** The project plugin settings lock file (`<projectDir>/plugins/omp-plugins.lock.json`). */
+  lockPath: string;
+  /** The project `config.yml` (`<projectDir>/config.yml`); written by the project-aware updater. */
+  configPath: string;
+  dryRun: boolean;
+  force: boolean;
+  yes: boolean;
+  coverage?: FocusCoverage;
+  /**
+   * Capability flags to author on every new project role (`--feature`). Passed
+   * through to each planned request, so `resolveRole` sets `def.features` and
+   * the flag is persisted (not the knobs it expands to).
+   */
+  features?: Record<string, boolean>;
+  /** Role validator; defaults to the plugin's own `validateRole`. */
+  validate?: (name: string, def: RoleDef) => string[];
+};
+
+export type SetupProjectResult =
+  | {
+      ok: true;
+      kept: string[];
+      dropped: string[];
+      added: string[];
+      /** The project's effective role set (kept shipped defs + new defs). */
+      roles: Record<string, RoleDef>;
+      /** Archetype id each new role was fitted to, keyed by role name. */
+      archetypes: Record<string, string>;
+      /** The project agent `.md` paths (planned on a dry run, written otherwise). */
+      agents: string[];
+      warnings: string[];
+    }
+  | { ok: false; errors: string[] };
+
+/** True when the project lock file already carries a project role config. */
+function hasProjectRoleConfig(lockPath: string): boolean {
+  const raw = readPluginSettingsMap({ global: lockPath, project: null });
+  const nested = raw.roles;
+  if (isRecord(nested) && Object.keys(nested).length > 0) return true;
+  return Object.keys(raw).some((key) => key.startsWith("roles."));
+}
+
+export function setupProject(profile: ProjectProfile, opts: SetupProjectOpts): SetupProjectResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+
+  // 1. Validate the profile's role names.
+  const seen = new Set<string>();
+  for (const role of profile.roles) {
+    const name = role.name.trim();
+    if (!AGENT_NAME_RE.test(name)) errors.push(`role "${name}" must match [A-Za-z0-9_-]+`);
+    else if (name.toLowerCase() in RESERVED_AGENT_NAMES) errors.push(`role "${name}" is reserved by omp (main/sub are session sentinels)`);
+    if (seen.has(name)) errors.push(`role "${name}" is listed twice`);
+    seen.add(name);
+  }
+  if (errors.length > 0) return { ok: false, errors };
+
+  // 2. Resolve the role set: shipped roles default to keep, `keep: false` drops
+  //    one, every other name is a new role fitted from the archetype table.
+  const wanted = new Set(Object.keys(DEFAULT_ROLES));
+  const dropped: string[] = [];
+  const newRoles: ProposedRole[] = [];
+  for (const role of profile.roles) {
+    const name = role.name.trim();
+    const shipped = name in DEFAULT_ROLES;
+    if (role.keep === false) {
+      if (shipped) {
+        wanted.delete(name);
+        dropped.push(name);
+      }
+      continue;
+    }
+    if (shipped) continue;
+    wanted.add(name);
+    newRoles.push(role);
+  }
+  const kept = Object.keys(DEFAULT_ROLES).filter((name) => wanted.has(name));
+
+  // Fit and validate each new role's weights.
+  const validate = opts.validate ?? validateRole;
+  const plans: { name: string; request: CreateAgentRequest; def: RoleDef; archetype: string }[] = [];
+  for (const role of newRoles) {
+    const name = role.name.trim();
+    if (role.purpose.trim() === "") {
+      errors.push(`role ${name}: purpose is required`);
+      continue;
+    }
+    for (const metric of role.benchmarks ?? []) {
+      if (!isKnownMetric(metric)) errors.push(`role ${name}: unknown metric "${metric}"`);
+    }
+    const request: CreateAgentRequest = {
+      name,
+      purpose: role.purpose,
+      thinking: role.thinking,
+      tools: role.tools,
+      spec: role.spec,
+      features: opts.features,
+      extraBenchmarks: role.benchmarks ?? [],
+      coverage: opts.coverage,
+      scope: "project",
+      projectAnchor: dirname(opts.projectDir),
+      force: opts.force,
+      dryRun: opts.dryRun,
+      lockPath: opts.lockPath,
+    };
+    const resolved = resolveRole(request);
+    if ("errors" in resolved) {
+      errors.push(...resolved.errors);
+      continue;
+    }
+    const bench = applyFocusBenchmarks(resolved.def.weights, request.extraBenchmarks ?? [], opts.coverage);
+    resolved.def.weights = bench.weights;
+    errors.push(...checkWeightMath(name, resolved.def.weights, resolved.def.required));
+    errors.push(...validate(name, resolved.def));
+    if (bench.dropped.length > 0) warnings.push(`role ${name}: focus benchmarks beyond the cap were dropped: ${bench.dropped.join(", ")}`);
+    plans.push({ name, request, def: resolved.def, archetype: resolved.archetype.id });
+  }
+  if (errors.length > 0) return { ok: false, errors };
+
+  // 3. The force gate and the agent-file collisions: every check before any write.
+  if (hasProjectRoleConfig(opts.lockPath) && !opts.force) {
+    errors.push(`${opts.lockPath} already has a project role config — pass --force to overwrite`);
+  }
+  const agentsDir = projectAgentsDir(dirname(opts.projectDir));
+  const agentPaths = plans.map((plan) => join(agentsDir, `${plan.name}.md`));
+  for (const agentPath of agentPaths) {
+    if (existsSync(agentPath) && !opts.force) errors.push(`${agentPath} already exists — pass --force to overwrite`);
+  }
+  if (errors.length > 0) return { ok: false, errors };
+
+  // 4. The project role set: `enabled: false` for every universe role the project
+  //    does not want, plus the new roles' defs.
+  const projectRaw = readPluginSettingsMap({ global: opts.lockPath, project: null });
+  const { settings: projectResolved } = resolveSettings(projectRaw);
+  const universe = roleUniverse(projectRaw, projectResolved.roles);
+  const dirty: Record<string, RoleDef> = {};
+  for (const name of Object.keys(universe)) {
+    if (wanted.has(name)) continue;
+    dirty[name] = { ...universe[name].def, enabled: false };
+  }
+  for (const plan of plans) dirty[plan.name] = plan.def;
+
+  const roles: Record<string, RoleDef> = {};
+  for (const name of kept) roles[name] = DEFAULT_ROLES[name];
+  for (const plan of plans) roles[plan.name] = plan.def;
+
+  const added = plans.map((plan) => plan.name);
+  const archetypes: Record<string, string> = {};
+  for (const plan of plans) archetypes[plan.name] = plan.archetype;
+  if (opts.dryRun) return { ok: true, kept, dropped, added, roles, archetypes, agents: agentPaths, warnings };
+
+  // 5. Write the project plugin settings, then create the project agents.
+  if (Object.keys(dirty).length > 0) {
+    const written = writeRoleSettings(opts.lockPath, dirty, { dryRun: false });
+    if (!written.ok) return { ok: false, errors: written.errors };
+  }
+  for (const plan of plans) {
+    const result = createAgent({ ...plan.request, dryRun: false });
+    if (!result.ok) return { ok: false, errors: result.errors };
+  }
+
+  return { ok: true, kept, dropped, added, roles, archetypes, agents: agentPaths, warnings };
+}
+
+// ---------------------------------------------------------------------------
+// `/project-roles` argument parsing and the plan report, shared by the omp
+// command (which receives the raw text typed after the command name) and the
+// tests (which pass the same raw text). One parser, so the two cannot drift.
+// ---------------------------------------------------------------------------
+
+export const PROJECT_ROLES_USAGE = [
+  "Usage: /project-roles [options]",
+  "",
+  "  Discovers the project's usecase from its own artifacts (README, package.json,",
+  "  AGENTS.md, docs, git log, file tree), proposes a project-scoped role set, and",
+  "  applies it: the project plugin settings, the new roles' agents, and the",
+  "  project's modelRoles in <cwd>/.omp/config.yml.",
+  "",
+  "  --purpose <text>   override the discovered usecase (one sentence)",
+  "  --roles <spec>     override the role set: comma-separated entries;",
+  "                     `-name` drops a shipped role, `name` keeps/adds one,",
+  "                     `name=purpose` adds a new role with that purpose",
+  "  --feature <id,...> capability flag(s) to author on every new project role",
+  "                     (see /create-agent --list-features); repeatable, merged",
+  "  --force            overwrite an existing project role config",
+  "  --yes              apply without prompting",
+  "  --dry-run          print the plan without writing",
+  "  --json             print the result as JSON",
+].join("\n");
+
+/**
+ * Parse a `--roles` spec: comma-separated entries. `-name` drops a shipped role;
+ * `name` keeps a shipped role (or adds a new one, purpose defaulting to the
+ * name); `name=purpose` adds a new role with that purpose. Returns the proposed
+ * roles, or an error string.
+ */
+export function parseRolesSpec(spec: string): ProposedRole[] | string {
+  const roles: ProposedRole[] = [];
+  for (const raw of spec.split(",")) {
+    const entry = raw.trim();
+    if (entry === "") continue;
+    if (entry.startsWith("-")) {
+      const name = entry.slice(1).trim();
+      if (name === "") return `--roles: "-" needs a role name`;
+      roles.push({ name, purpose: "", keep: false });
+      continue;
+    }
+    const eq = entry.indexOf("=");
+    if (eq === -1) {
+      roles.push({ name: entry, purpose: entry in DEFAULT_ROLES ? "" : entry });
+      continue;
+    }
+    const name = entry.slice(0, eq).trim();
+    const purpose = entry.slice(eq + 1).trim();
+    if (name === "" || purpose === "") return `--roles: expected name=purpose, got "${entry}"`;
+    roles.push({ name, purpose });
+  }
+  if (roles.length === 0) return `--roles: no roles given`;
+  return roles;
+}
+
+export type ParsedProjectRolesArgs =
+  | { ok: true; purpose: string | undefined; roles: ProposedRole[] | undefined; features: Record<string, boolean> | undefined; force: boolean; yes: boolean; dryRun: boolean; json: boolean; help: boolean }
+  | { ok: false; error: string };
+
+/** Parse the raw text after `/project-roles` (tokenized here, so the command and
+ * the tests share one parser). */
+export function parseProjectRolesArgs(raw: string): ParsedProjectRolesArgs {
+  const argv = tokenizeArgs(raw);
+  let purpose: string | undefined;
+  let roles: ProposedRole[] | undefined;
+  let features: Record<string, boolean> | undefined;
+  let force = false;
+  let yes = false;
+  let dryRun = false;
+  let json = false;
+  let help = false;
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    if (flag === "--help" || flag === "-h") {
+      help = true;
+      continue;
+    }
+    if (flag === "--force") {
+      force = true;
+      continue;
+    }
+    if (flag === "--yes") {
+      yes = true;
+      continue;
+    }
+    if (flag === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
+    if (flag === "--json") {
+      json = true;
+      continue;
+    }
+    if (flag !== "--purpose" && flag !== "--roles" && flag !== "--feature") return { ok: false, error: `unknown flag "${flag}"\n\n${PROJECT_ROLES_USAGE}` };
+    const value = argv[++i];
+    if (value === undefined) return { ok: false, error: `${flag} requires a value\n\n${PROJECT_ROLES_USAGE}` };
+    if (flag === "--purpose") purpose = value;
+    else if (flag === "--feature") {
+      const ids = value.split(",").map((token) => token.trim()).filter((token) => token.length > 0);
+      if (ids.length === 0) return { ok: false, error: `--feature: no capability id given\n\n${PROJECT_ROLES_USAGE}` };
+      const merged = features ?? {};
+      for (const id of ids) {
+        if (featureById(id) === null) {
+          return { ok: false, error: `--feature: unknown capability "${id}" — one of ${FEATURES.map((f) => f.id).join(", ")}\n\n${PROJECT_ROLES_USAGE}` };
+        }
+        merged[id] = true;
+      }
+      features = merged;
+    } else {
+      const parsed = parseRolesSpec(value);
+      if (typeof parsed === "string") return { ok: false, error: `${parsed}\n\n${PROJECT_ROLES_USAGE}` };
+      roles = parsed;
+    }
+  }
+  return { ok: true, purpose, roles, features, force, yes, dryRun, json, help };
+}
+
+/** Apply the `--purpose`/`--roles` overrides to a discovered profile. */
+export function applyProfileOverrides(profile: ProjectProfile, over: { purpose?: string; roles?: ProposedRole[] }): ProjectProfile {
+  return {
+    ...profile,
+    ...(over.purpose !== undefined ? { summary: over.purpose } : {}),
+    ...(over.roles !== undefined ? { roles: over.roles } : {}),
+  };
+}
+
+/** The human-readable plan for a `/project-roles` run. `topPicks` maps a new
+ * role name to its ranked leader (computed by the extension from the ranking
+ * universe); `warnings` are the divergence/coverage notes. */
+export function formatProjectRolesReport(
+  profile: ProjectProfile,
+  result: Extract<SetupProjectResult, { ok: true }>,
+  opts: { topPicks?: Record<string, string>; warnings?: readonly string[] } = {},
+): string {
+  const lines: string[] = ["project-roles: plan"];
+  lines.push(`  kept:    ${result.kept.join(", ") || "(none)"}`);
+  lines.push(`  dropped: ${result.dropped.join(", ") || "(none)"}`);
+  lines.push(`  added:   ${result.added.join(", ") || "(none)"}`);
+  for (const name of result.added) {
+    const def = result.roles[name];
+    const proposed = profile.roles.find((role) => role.name.trim() === name);
+    const weights = Object.entries(def.weights).map(([metric, weight]) => `${metric}=${weight}`).join(", ");
+    const focus = proposed?.benchmarks !== undefined && proposed.benchmarks.length > 0 ? proposed.benchmarks.join(", ") : "(archetype default)";
+    const top = opts.topPicks?.[name];
+    lines.push(`  @${name} [${result.archetypes[name] ?? "?"}]`);
+    lines.push(`    weights: ${weights}`);
+    lines.push(`    focus:   ${focus}`);
+    const features = Object.entries(def.features ?? {});
+    if (features.length > 0) lines.push(`    features: ${features.map(([id, on]) => `${id}=${on}`).join(",")}`);
+    if (top !== undefined) lines.push(`    top pick: ${top}`);
+  }
+  for (const warning of opts.warnings ?? []) lines.push(`  warning: ${warning}`);
+  for (const warning of result.warnings) lines.push(`  warning: ${warning}`);
+  return lines.join("\n");
+}

package/src/prompts/agent-creation-architect.md

@@ -1,3 +1,5 @@
+<!-- vendored from omp 18.4.8 (agent-creation-architect); re-sync on upgrade — see docs/dev/agent-authoring.md -->
+
 You: AI agent architect; translate user requirements → precisely tuned agent configurations.
 
 Agent creation: consider project-specific `CLAUDE.md` instructions; align new agents with established project patterns.

package/src/prompts/project-profile-architect.md

@@ -0,0 +1,33 @@
+<!-- plugin-authored: the /project-roles profile-discovery architect -->
+
+You: project analyst; read a repository's own artifacts and describe its usecase as a model-role set.
+
+Given the repository artifacts (README, package.json, AGENTS.md, docs listing, git log, file tree), infer:
+1. The project's one-line usecase (`summary`) and its domain (`domain`, e.g. "data science", "web app", "docs").
+2. Its primary work (`primaryWork`, e.g. "backend API", "data pipelines") and its stack (`stack`, e.g. "Python", "Postgres").
+3. The capabilities its agents need (`needs`): metric names from the plugin's known set where possible (e.g. `math`, `reasoning`, `code`, `writing`, `long_context`, `tool_calling`, `vision`, `agents`, `search`).
+4. The role set (`roles`): the shipped roles to keep or drop, and any new specialist roles.
+
+Shipped roles: `default`, `smol`, `slow`, `vision`, `plan`, `commit`, `tiny`, `task`, `advisor`, `designer`. A shipped role is kept by default; set `"keep": false` to drop one the project does not need (e.g. drop `vision` and `designer` for a backend service). A new role is an entry whose name is not a shipped role; give it a one-sentence `purpose` and, when a specific benchmark should drive it, a `benchmarks` list of metric names.
+
+Output MUST be a valid JSON object with exactly these fields:
+
+```json
+{
+  "summary": "A one-line description of the project's usecase",
+  "domain": "A short domain label",
+  "primaryWork": ["The main kinds of work the project does"],
+  "stack": ["The languages, frameworks and services it uses"],
+  "needs": ["The capability metrics its agents need"],
+  "roles": [
+    { "name": "a shipped role to keep or drop, or a new role name", "purpose": "one sentence; the routing description", "keep": true, "benchmarks": ["metric names"] }
+  ]
+}
+```
+
+Rules:
+- Role names MUST match `[A-Za-z0-9_-]+` and MUST NOT be `main` or `sub`.
+- A new role's `purpose` MUST be one sentence describing the specialist work.
+- Keep the plan minimal: keep the shipped roles that fit, drop only the ones the project does not need, and add only the roles the project's specialist work requires.
+- NEVER invent benchmark metric names; use the plugin's known metrics.
+- `keep` is only meaningful for a shipped role; omit it for a new role.

package/src/prompts/project-profile-user.md

@@ -0,0 +1,8 @@
+Repository artifacts:
+
+{{artifacts}}
+
+{{purpose}}
+
+MUST return only the JSON object required by the system instructions.
+NEVER include markdown fences.

package/src/provider-display.ts

@@ -0,0 +1,67 @@
+/**
+ * Provider display: keep the live session model's `name` suffixed with its
+ * upstream provider pin, so omp's model segment renders e.g.
+ * `DeepSeek V4.1 Flash @coreweave/fp8`.
+ *
+ * omp's built-in model segment renders `state.model.name || state.model.id`
+ * only and exposes no extension hook to add to it; the only lever is the live
+ * model object's `name` (the exact object `ctx.models.current()` returns). This
+ * module is pure and dual-runtime (no `@oh-my-pi/*` import) — the extension
+ * wiring only calls it.
+ */
+import { splitThinkingSuffix } from "./availability.ts";
+import { isRecord } from "./guards.ts";
+
+/** The single upstream route of a compat routing block, or null. Mirrors omp's
+ * `getSingleRoutingOnly`: exactly one entry, a non-empty string. */
+function singleOnly(routing: unknown): string | null {
+  if (!isRecord(routing) || !Array.isArray(routing.only) || routing.only.length !== 1) return null;
+  const upstream = routing.only[0];
+  return typeof upstream === "string" && upstream ? upstream : null;
+}
+
+/**
+ * The provider pin carried by a model's compat routing block:
+ * `compat.openRouterRouting.only[0]`, else `compat.vercelGatewayRouting.only[0]`.
+ * Null when absent, when `only` is not exactly one entry, or when the entry is
+ * not a non-empty string.
+ */
+export function providerPinOf(model: unknown): string | null {
+  if (!isRecord(model) || !isRecord(model.compat)) return null;
+  const compat = model.compat;
+  return singleOnly(compat.openRouterRouting) ?? singleOnly(compat.vercelGatewayRouting);
+}
+
+/**
+ * The trailing `@<slug>` of a selector (`openrouter/<id>@<slug>:<level>`),
+ * after stripping a trailing thinking suffix (`:high`, `:auto`, …). Null when
+ * there is no `@` or the slug is empty. Strip order mirrors `currentRankingId`
+ * in `src/availability.ts`: level first, then `@`.
+ */
+export function providerPinOfSelector(selector: string): string | null {
+  const { base } = splitThinkingSuffix(selector);
+  const at = base.lastIndexOf("@");
+  if (at === -1) return null;
+  const slug = base.slice(at + 1);
+  return slug || null;
+}
+
+/**
+ * Strip any previous ` @<slug>` suffix from `name`, then append ` @<pin>` when
+ * `pin` is non-null. Idempotent; a null pin returns the base name (suffix
+ * stripped). Plain text only — no theme tokens, no ANSI.
+ */
+export function withProviderSuffix(name: string, pin: string | null): string {
+  const base = name.replace(/\s@\S+$/, "");
+  return pin === null ? base : `${base} @${pin}`;
+}
+
+/**
+ * Set `model.name` to `withProviderSuffix(model.name, pin)` when `model` is a
+ * record with a string `name`; a no-op otherwise.
+ */
+export function applyProviderDisplay(model: unknown, pin: string | null): void {
+  if (isRecord(model) && typeof model.name === "string") {
+    model.name = withProviderSuffix(model.name, pin);
+  }
+}