@genee/omp-opsx-addon 0.3.0 → 0.5.0

package/lib/agent-defs.ts

@@ -5,7 +5,7 @@ const MARKER = '<!-- @genee/omp-opsx-addon -->';
 const CODE_REVIEWER_MD = (model?: string) => `---
 name: code-reviewer
 description: OpenSpec 代码审查 agent，审查代码实现并执行全局验证
-tools: read, bash, glob, grep${model ? `\nmodel: ${model}` : ''}
+tools: read, bash, glob, grep${model ? `\nmodel: "${model}"` : ''}
 ---
 
 你是一位资深代码审查员。你根据 OpenSpec 提案和设计文档审查代码实现，并在审阅的同时执行最后一次全局验证。
@@ -71,7 +71,7 @@ ${MARKER}
 const PROPOSAL_REVIEWER_MD = (model?: string) => `---
 name: proposal-reviewer
 description: OpenSpec 提案审查 agent，审查提案质量
-tools: read, bash, glob, grep${model ? `\nmodel: ${model}` : ''}
+tools: read, bash, glob, grep${model ? `\nmodel: "${model}"` : ''}
 ---
 
 你是一位资深需求审查员。你审查 OpenSpec 提案的完整性和质量。
@@ -123,7 +123,7 @@ ${MARKER}
 const CODER_MD = (model?: string) => `---
 name: coder
 description: OpenSpec 变更实现 agent，同步 tasks.md 进度
-tools: read, write, edit, bash, glob, grep, todo${model ? `\nmodel: ${model}` : ''}
+tools: read, write, edit, bash, glob, grep, todo${model ? `\nmodel: "${model}"` : ''}
 skill: openspec-apply-change
 ---
 
@@ -184,7 +184,7 @@ ${MARKER}
 const PLANNER_MD = (model?: string) => `---
 name: planner
 description: OpenSpec 提案规划 agent
-tools: read, write, edit, bash, glob, grep, todo${model ? `\nmodel: ${model}` : ''}\nskill: openspec-propose
+tools: read, write, edit, bash, glob, grep, todo${model ? `\nmodel: "${model}"` : ''}\nskill: openspec-propose
 ---
 
 你是一个 OpenSpec 提案规划 agent。负责创建和更新 OpenSpec 变更提案文档。

package/lib/edit-variant-pin.ts

@@ -117,7 +117,7 @@ export function applyEditVariantPin(pi: ExtensionAPI, pin: Record<string, string
         | { override(path: string, value: unknown): void; getAgentDir?: () => string }
         | undefined;
     if (!settings) {
-        console.warn('[omp-opsx-addon] pi.pi.settings unavailable; edit variant pin skipped');
+        pi.logger?.warn('[omp-opsx-addon] pi.pi.settings unavailable; edit variant pin skipped');
         return;
     }
 
@@ -139,18 +139,18 @@ export function applyEditVariantPin(pi: ExtensionAPI, pin: Record<string, string
 
         const configPath = resolveGlobalConfigPath(agentDir);
         if (!configPath) {
-            console.warn(
+            pi.logger?.warn(
                 `[omp-opsx-addon] edit variant pin failed: no global config.yml found under ${agentDir}`,
             );
             return;
         }
         const outcome = persistEditVariantPin(configPath, pin);
         if (outcome === 'written') {
-            console.warn(
+            pi.logger?.warn(
                 `[omp-opsx-addon] edit variant pin persisted to ${configPath} (effective from the next session)`,
             );
         }
     } catch (err) {
-        console.warn('[omp-opsx-addon] edit variant pin failed:', err);
+        pi.logger?.warn('[omp-opsx-addon] edit variant pin failed', { err });
     }
 }

package/lib/logger.ts

@@ -0,0 +1,33 @@
+/**
+ * 插件日志通道（模块级注入）。
+ *
+ * 主进程日志不再走 console.*（会在 omp TUI 里打爆界面），改走宿主
+ * pi.logger（滚动文件日志）。lib 模块拿不到 pi 对象，故提供模块级 holder：
+ * 入口 setOpsxLogger(pi.logger) 注入，lib 侧 getLogger() 读取。
+ * 未注入（测试场景直接调用叶子函数）时默认 console，输出与迁移前一致。
+ */
+
+/** 窄化日志接口：宿主 pi.logger 与 console 的结构交集，仅本插件使用的四级方法。 */
+export interface OpsxLogger {
+  error(message: string, context?: Record<string, unknown>): void;
+  warn(message: string, context?: Record<string, unknown>): void;
+  info(message: string, context?: Record<string, unknown>): void;
+  debug(message: string, context?: Record<string, unknown>): void;
+}
+
+/** 模块级当前 logger，默认 console（未注入/测试场景保持旧行为）。 */
+let current: OpsxLogger = console;
+
+/** 插件入口注入宿主 pi.logger（进程级单例，多实例重复注入幂等）。
+ *  空值注入忽略：保持 getLogger() 恒可用（console 兜底）——测试 mock 的
+ *  pi 对象可能不含 logger，此时视同未注入，输出与迁移前一致。 */
+export function setOpsxLogger(logger: OpsxLogger): void {
+  if (logger) {
+    current = logger;
+  }
+}
+
+/** 读取当前 logger。 */
+export function getLogger(): OpsxLogger {
+  return current;
+}

package/lib/model-roles.ts

@@ -0,0 +1,270 @@
+/**
+ * pick-model → OMP modelRoles application.
+ *
+ * change: pick-model-role-targeting — selector results are applied by TIER
+ * via session-scoped `settings.overrideModelRoles` instead of per-agent
+ * `task.agentModelOverrides` writes.
+ *
+ * change: pick-model-batch-all-roles — the overlay covers EVERY role known to
+ * the host (`getKnownRoleIds(settings)`: the 10 built-in roles plus custom
+ * roles from cycleOrder/modelRoles/modelTags). `buildRoleOverridePlan` maps
+ * each known role to a tier (default table, overridable via
+ * `model_role_tiers`), feeds it the single picked model for that tier, and
+ * records skip reasons (`skip` config sentinel, capability gate such as
+ * vision/image, or no picked model for the tier). The landing sequence is
+ * unchanged: clearOverride('modelRoles') → overrideModelRoles(payload) →
+ * empty-string neutralization of persisted per-agent pins.
+ */
+import { type ModelRole } from '@oh-my-pi/pi-coding-agent/config/model-roles';
+import type { Model, Api } from '@oh-my-pi/pi-catalog/types';
+import type { SelectionContext } from '../index.js';
+import type { TierName } from './model-tiers.js';
+import { OPSX_ROLES } from './unified-config.js';
+
+/** Per-agent names written into `task.agentModelOverrides` neutralization. */
+const AGENT_MODEL_KEYS: Record<string, string> = {
+    coder: 'coder',
+    reviewer: 'code-reviewer',
+    planner: 'planner',
+    'proposal-reviewer': 'proposal-reviewer',
+};
+
+/** Opsx role → OMP tier role alias (without `@`). */
+export const ROLE_TO_OMP_ALIAS: Record<string, string> = {
+    coder: 'smol',
+    reviewer: 'default',
+    planner: 'default',
+    'proposal-reviewer': 'default',
+};
+
+/**
+ * Built-in OMP model role → default tier (change: pick-model-batch-all-roles
+ * D2). Key source is `MODEL_ROLE_IDS`; the `satisfies` clause forces the
+ * table to cover every built-in role — no hardcoded role list is enumerated
+ * in code.
+ */
+export const OMP_ROLE_TO_TIER = {
+    tiny: 'tiny',
+    smol: 'mid',
+    task: 'mid',
+    commit: 'low',
+    default: 'high',
+    designer: 'high',
+    vision: 'high',
+    slow: 'top',
+    plan: 'top',
+    advisor: 'top',
+} satisfies Record<ModelRole, TierName>;
+
+/**
+ * Capability requirements per role (D3). A role only receives a model that
+ * passes its predicate; when no candidate qualifies the role is skipped
+ * (reason `capability`) rather than written an incapable model. The table
+ * is extensible; vision is the only gated role today.
+ *
+ * `Model.input` is a required `("text"|"image")[]` in the catalog; a
+ * non-array value is treated conservatively as text-only.
+ */
+export const ROLE_CAPABILITY: Record<string, (model: Model<Api>) => boolean> = {
+    vision: (model) => Array.isArray(model.input) && model.input.includes('image'),
+};
+
+/** Why a known role was left out of the overlay payload. */
+export type RoleSkipReason = 'skip' | 'capability' | 'no-pick';
+
+/** A role omitted from the overlay payload, with the reason. */
+export interface SkippedRole {
+    role: string;
+    reason: RoleSkipReason;
+}
+
+/** The full-role overlay plan consumed by `applyRoleModelOverrides`. */
+export interface RoleOverridePlan {
+    /** role → 'provider/id' written to `overrideModelRoles`. */
+    overrides: Record<string, string>;
+    /** Roles not written (config skip / capability gate / no picked model). */
+    skipped: SkippedRole[];
+}
+
+/** Inputs for `buildRoleOverridePlan`. */
+export interface BuildRoleOverridePlanInput {
+    /** All roles the host knows (built-in + custom), from `getKnownRoleIds`. */
+    knownRoleIds: readonly string[];
+    /** Parsed `model_role_tiers` config (role → tier override or 'skip'). */
+    ompRoleTiers: Record<string, TierName | 'skip'>;
+    /**
+     * Tier → picked `provider/id` for that tier. mid/high reuse the opsx
+     * selector picks (coder/reviewer); tiny/low/top are supplemental picks
+     * over the same candidate set. `undefined` means the tier has no pick
+     * (every role mapped to it is skipped with reason `no-pick`).
+     */
+    tierPicks: Partial<Record<TierName, string | undefined>>;
+    /**
+     * Capability-gated picks keyed by role (e.g. vision picked from
+     * image-capable candidates only). `undefined` means no qualifying model.
+     */
+    capabilityPicks?: Record<string, string | undefined>;
+}
+
+/** Roles whose fallback tier was already warned about (one warning per role). */
+const warnedCustomRoles = new Set<string>();
+
+/**
+ * Resolve the tier an OMP model role should follow: explicit
+ * `model_role_tiers` value (including the `skip` sentinel) → built-in
+ * default table → `high` fallback for custom roles (warned once per role;
+ * D7: custom roles are treated as primary roles unless configured).
+ */
+export function resolveOmpRoleTier(
+    role: string,
+    ompRoleTiers: Record<string, TierName | 'skip'>,
+    warn: (msg: string) => void = () => {},
+): TierName | 'skip' {
+    const configured = ompRoleTiers[role];
+    if (configured !== undefined) return configured;
+    if (role in OMP_ROLE_TO_TIER) return OMP_ROLE_TO_TIER[role as ModelRole];
+    if (!warnedCustomRoles.has(role)) {
+        warnedCustomRoles.add(role);
+        warn(`[omp-opsx-addon] custom model role "${role}" has no tier mapping; using high (set model_role_tiers.${role} to tune or 'skip' to exclude)`);
+    }
+    return 'high';
+}
+
+/**
+ * Build the full-role overlay plan (D2/D3/D4/D7): for every known role,
+ * resolve its tier (or `skip`), apply capability gating, then assign the
+ * single picked model for the tier. Roles without a pick are recorded with
+ * a reason and omitted from the payload — after `clearOverride` they fall
+ * back to the user's config layer (or stay unconfigured).
+ */
+export function buildRoleOverridePlan(
+    input: BuildRoleOverridePlanInput,
+    warn: (msg: string) => void = () => {},
+): RoleOverridePlan {
+    const overrides: Record<string, string> = {};
+    const skipped: SkippedRole[] = [];
+    for (const role of input.knownRoleIds) {
+        const tier = resolveOmpRoleTier(role, input.ompRoleTiers, warn);
+        if (tier === 'skip') {
+            skipped.push({ role, reason: 'skip' });
+            continue;
+        }
+        if (role in ROLE_CAPABILITY) {
+            // Capability-gated roles (vision) use their own candidate set;
+            // a missing pick means no qualifying model OR no pick at all —
+            // both surface as `capability` (D3: never write an incapable model).
+            const picked = input.capabilityPicks?.[role];
+            if (!picked) {
+                skipped.push({ role, reason: 'capability' });
+                continue;
+            }
+            overrides[role] = picked;
+            continue;
+        }
+        const picked = input.tierPicks[tier];
+        if (!picked) {
+            skipped.push({ role, reason: 'no-pick' });
+            continue;
+        }
+        overrides[role] = picked;
+    }
+    return { overrides, skipped };
+}
+
+/**
+ * Model string for the agent frontmatter `model:` field.
+ *
+ * - auto role  → the tier role alias (`@smol` for coder, `@default` for the
+ *   high-tier roles) so resolution binds to the tier at the frontmatter layer;
+ * - omp-alias  → `@<alias>` (e.g. `@slow`);
+ * - pinned     → the concrete `provider/model` (or bare model id);
+ * - no value   → undefined (template omits the `model:` line).
+ */
+export function frontmatterModel(role: string, value: { kind: string } & Record<string, unknown>): string | undefined {
+    if (value.kind === 'auto') return `@${ROLE_TO_OMP_ALIAS[role] ?? 'default'}`;
+    if (value.kind === 'omp-alias' && typeof value.alias === 'string') return `@${value.alias}`;
+    if (value.kind === 'provider-model' && typeof value.provider === 'string' && typeof value.modelId === 'string') {
+        return `${value.provider}/${value.modelId}`;
+    }
+    if (value.kind === 'model' && typeof value.modelId === 'string') return value.modelId;
+    return undefined;
+}
+
+/**
+ * Explicit model string for the dispatch `task(..., model:"...")` call, or
+ * undefined when resolution must flow through the tier role.
+ *
+ * auto roles never pass a model — requestModel is the top-priority layer and
+ * a concrete model would shadow the frontmatter `@alias`; omp-alias roles
+ * (e.g. @slow, roleModels value without `/`) likewise resolve through
+ * frontmatter. Only a concrete provider/model pin stays explicit.
+ */
+export function dispatchModelHint(role: string, selection: SelectionContext): string | undefined {
+    if (selection.roleKind?.[role as keyof SelectionContext['roleKind']] === 'auto') return undefined;
+    const picked = selection.selectorResults[role as keyof SelectionContext['selectorResults']]?.picked;
+    if (picked) return `${picked.provider}/${picked.id}`;
+    const hint = selection.roleModels[role as keyof SelectionContext['roleModels']];
+    return hint && hint.includes('/') ? hint : undefined;
+}
+
+/**
+ * Runtime neutralization for persisted per-agent pins.
+ *
+ * Empty STRING values (not 'off'/'false'): the OMP model-resolution chain
+ * expands `''` to zero patterns (Rdt@12103716 returns on empty trim;
+ * VT@12104171 flattens to []), so the settingsOverride layer (LNs@12104228)
+ * falls through to the frontmatter `@alias` layer; while cross-layer merge
+ * (#X/#Se@11863299 — scalar leaf replace, only `undefined` skipped) lets the
+ * runtime `''` shadow the global config pin. 'off'/'false' are NOT empty:
+ * they come back as literal patterns and short-circuit the frontmatter layer.
+ */
+export function agentOverrideNeutralization(): Record<string, string> {
+    const neutral: Record<string, string> = {};
+    for (const role of OPSX_ROLES) neutral[AGENT_MODEL_KEYS[role]] = '';
+    return neutral;
+}
+
+/** Minimal Settings surface this module needs (host-process `pi.pi.settings`). */
+export interface RoleSettings {
+    clearOverride(key: string): void;
+    overrideModelRoles(roles: Record<string, string>): void;
+    override(key: string, value: unknown): void;
+}
+
+/**
+ * Apply the selector result to OMP model roles (session-scoped).
+ *
+ * Sequence (design D1/D5/D7): clear the session modelRoles overlay first
+ * (overrideModelRoles only adds and skips falsy values, so stale roles from
+ * a previous constraint would otherwise linger) → write the full-role plan
+ * payload (roles skipped for config `skip`, capability gating, or no picked
+ * model are omitted and fall back to the config layer after the clear) →
+ * neutralize persisted per-agent pins with empty strings. Never writes
+ * disk; the runtime overlay is released with the session.
+ */
+export function applyRoleModelOverrides(
+    settings: RoleSettings | null | undefined,
+    sel: SelectionContext,
+    warn: (msg: string) => void = () => {},
+): void {
+    if (!settings) {
+        warn('[omp-opsx-addon] pi.pi.settings unavailable; model role overrides skipped');
+        return;
+    }
+    settings.clearOverride('modelRoles');
+    settings.overrideModelRoles(sel.roleOverrides);
+    settings.override('task.agentModelOverrides', agentOverrideNeutralization());
+    const applied = Object.keys(sel.roleOverrides);
+    const skippedText = sel.skippedRoles.length > 0
+        ? `; skipped: ${sel.skippedRoles.map((s) => `${s.role}(${s.reason})`).join(', ')}`
+        : '';
+    const skipWarns = sel.skippedRoles.filter((s) => s.reason !== 'skip');
+    warn(`[omp-opsx-addon] modelRoles applied (${applied.length} roles: ${applied.join(', ') || 'none'})${skippedText}; per-agent pins neutralized`);
+    for (const s of skipWarns) {
+        if (s.reason === 'capability') {
+            warn(`[omp-opsx-addon] model role "${s.role}": no capable model in selection; skipped (role keeps configured/default value; change selector/allowlist or set model_role_tiers.${s.role}: skip)`);
+        } else {
+            warn(`[omp-opsx-addon] model role "${s.role}": no model picked for its tier; skipped (role keeps configured/default value)`);
+        }
+    }
+}