@genee/omp-opsx-addon 0.8.0 → 0.10.0

package/lib/continuity-guard.ts

@@ -0,0 +1,117 @@
+/**
+ * Continuity guard (programme smart-model-selection W4 / change:
+ * difficulty-routed-selection) — same-session model stickiness at automatic
+ * recompute points (Higress 思路: conservative reuse is the DEFAULT state,
+ * not a timer state machine — no TTL, no counters).
+ *
+ * Rule (design D5): at an auto recompute, a write-set role's incumbent pick
+ * is PINNED whenever it remains viable (its selector still appears in the
+ * fresh candidate pool — not exhausted / unreachable / excluded /
+ * selector-filtered out). The pin outranks every tie-break: a faster or
+ * cheaper candidate cannot displace the incumbent on its own. A switch is
+ * justified only when
+ *   (a) the new band strictly upgrades the incumbent's band AND the
+ *       classification confidence ≥ `continuity_guard.weight`,
+ *   (b) stall escalation is in effect (a system-initiated escalation is a
+ *       legitimate switch reason), or
+ *   (c) the incumbent left the pool (availability outranks stickiness).
+ *
+ * An unknown incumbent band (routing enabled mid-session, prior result
+ * carries no band record) compares as the neutral `standard`: complex /
+ * reasoning may still switch at sufficient confidence, `simple` never
+ * triggers an upgrade switch.
+ *
+ * Explicit user commands (/pick-model refresh / reset / selector / choices,
+ * role-scope) BYPASS the guard — explicit instruction > guard — and do not
+ * classify. The guard is a post-selection adjustment: it never inserts keys
+ * into the frozen sort chain and never filters the candidate pool.
+ */
+
+import { bandRank, type TaskBand } from './complexity-router.js';
+import type { SelectorResult } from './model-selector.js';
+
+/** `continuity_guard` config (design D7; owned here, SpeedAwareConfig 先例). */
+export interface ContinuityGuardConfig {
+    enabled: boolean;
+    /** Minimum confidence for an upgrade-driven switch; (0,1], default 0.6. */
+    weight: number;
+}
+
+/** Default switch-confidence weight (0.6: higher = stickier). */
+export const DEFAULT_WEIGHT = 0.6;
+
+/** Guard outcome: keep the fresh picks (`pass`) or reuse the incumbent (`pin`). */
+export type GuardDecision = 'pass' | 'pin';
+
+export interface GuardInput {
+    /** Master switch (off → always pass; the caller normally gates earlier). */
+    enabled: boolean;
+    /** Minimum classification confidence for an upgrade switch, (0,1]. */
+    weight: number;
+    /** Explicit command path — bypasses the guard entirely. */
+    explicit: boolean;
+    /** Prior pick for the role; null = no incumbent (trivial pass). */
+    incumbent: SelectorResult | null;
+    /** Incumbent's selector still present in the fresh candidate pool. */
+    incumbentViable: boolean;
+    /** Newly classified band. */
+    newBand: TaskBand;
+    /** Band recorded on the incumbent; null = unknown → neutral standard. */
+    incumbentBand: TaskBand | null;
+    /** Classification confidence of the new prompt. */
+    confidence: number;
+    /** Stall escalation in effect this recompute. */
+    stallEscalated: boolean;
+}
+
+export interface GuardOutcome {
+    decision: GuardDecision;
+    /** The incumbent result to carry forward (decision === 'pin' only). */
+    pinned?: SelectorResult;
+}
+
+/**
+ * Decide pin vs pass for one write-set role (design D5). Pure function —
+ * the assembly layer owns viability (pool membership) and application.
+ */
+export function decideGuard(input: GuardInput): GuardOutcome {
+    if (!input.enabled || input.explicit) return { decision: 'pass' };
+    if (!input.incumbent || !input.incumbentViable) return { decision: 'pass' };
+    if (input.stallEscalated) return { decision: 'pass' };
+    // Unknown incumbent band compares as the neutral standard (design D5):
+    // complex/reasoning can still switch at sufficient confidence, simple
+    // never outranks standard.
+    const priorBand = input.incumbentBand ?? 'standard';
+    const upgraded = bandRank(input.newBand) > bandRank(priorBand);
+    if (upgraded && input.confidence >= input.weight) return { decision: 'pass' };
+    return { decision: 'pin', pinned: input.incumbent };
+}
+
+/**
+ * Carry the incumbent forward with a `guard=pin` annotation (design D9):
+ * shallow-copies the prior result, appends `, band=<band>` when the prior
+ * reason carries no band record yet (routing enabled mid-session), then
+ * ` guard=pin` to pickedReason and to the decision log's picked line. The
+ * input result is never mutated; re-pinning an already-pinned result is
+ * idempotent (no duplicate segments).
+ */
+export function pinPriorPick(prev: SelectorResult, band: TaskBand): SelectorResult {
+    const baseReason = prev.pickedReason ?? `${prev.role}: pinned by continuity guard`;
+    // A pinned result may return as the NEXT recompute's incumbent (the guard
+    // reads the cached selection) — pinning must stay idempotent.
+    let reason = baseReason;
+    if (!reason.includes('band=')) reason = `${reason}, band=${band}`;
+    if (!reason.includes('guard=pin')) reason = `${reason} guard=pin`;
+
+    const segments = prev.decision.split(' | ');
+    const pickedIndex = segments.findIndex((s) => s.startsWith('picked='));
+    if (pickedIndex >= 0) {
+        if (!segments[pickedIndex].includes('guard=pin')) {
+            segments[pickedIndex] = `${segments[pickedIndex]} guard=pin`;
+        }
+    } else if (!prev.decision.includes('guard=pin')) {
+        segments.push('guard=pin');
+    }
+
+    return { ...prev, pickedReason: reason, decision: segments.join(' | ') };
+}

package/lib/family-filter.ts

@@ -8,6 +8,9 @@
  * semantics regardless of selector shape.
  */
 
+import { MODEL_ROLE_IDS } from '@oh-my-pi/pi-coding-agent/config/model-roles';
+import { ROLE_TO_OMP_ALIAS } from './model-roles.js';
+
 /** Lowercase and split on any run of non-alphanumeric characters into tokens. */
 export function normalizeTokens(s: string): string[] {
     return s
@@ -116,6 +119,50 @@ export function listProviders(models: readonly { provider: string; id: string }[
     return counts;
 }
 
+/** Opsx agent-name aliases accepted by the `[roleList:]` prefix → canonical model role. */
+export const AGENT_ROLE_SCOPE_ALIASES: Record<string, string> = {
+    ...ROLE_TO_OMP_ALIAS,
+    'code-reviewer': 'default',
+};
+
+/** Usage-error raised by role-scope resolution; the parser converts it to an error result. */
+export class RoleScopeUsageError extends Error {}
+
+/** Full legal roleList vocabulary, inlined into usage errors (built-ins + agent aliases + `all`). */
+export function roleScopeVocabularyText(): string {
+    const aliases = Object.keys(AGENT_ROLE_SCOPE_ALIASES);
+    return `合法 role 词表：内置 model role ${MODEL_ROLE_IDS.join(' / ')}；agent 别名 ${aliases.join(' / ')}；all（全部 role，等价无前缀）`;
+}
+
+/**
+ * Resolve comma-separated roleList entries into canonical model role ids
+ * (change: pick-model-role-scope). Matching is case-insensitive; agent
+ * aliases (`coder` / `reviewer` / `code-reviewer` / `planner` /
+ * `proposal-reviewer`) map to their canonical modelRole id; `all` collapses
+ * the whole scope to null (= global constraint, same as no prefix). The
+ * result is deduplicated in first-occurrence (input) order so the choices
+ * `scope=` segment is deterministic. Unknown entries throw `RoleScopeUsageError`
+ * with the full vocabulary inlined.
+ */
+export function resolveRoleScopeEntries(entries: readonly string[]): string[] | null {
+    const resolved: string[] = [];
+    for (const raw of entries) {
+        const entry = raw.trim().toLowerCase();
+        if (entry.length === 0) continue;
+        if (entry === 'all') return null;
+        const canonical = (MODEL_ROLE_IDS as readonly string[]).includes(entry)
+            ? entry
+            : Object.hasOwn(AGENT_ROLE_SCOPE_ALIASES, entry)
+                ? AGENT_ROLE_SCOPE_ALIASES[entry]
+                : undefined;
+        if (!canonical) {
+            throw new RoleScopeUsageError(`未知 role 定向条目 "${entry}"。${roleScopeVocabularyText()}`);
+        }
+        if (!resolved.includes(canonical)) resolved.push(canonical);
+    }
+    return resolved;
+}
+
 const RESERVED_SUBCOMMANDS: Record<string, AutoModelParseResult> = {
     choices: { kind: 'choices' },
     u: { kind: 'update' },
@@ -130,7 +177,13 @@ export type AutoModelParseResult =
     | { kind: 'update' }
     | { kind: 'refresh' }
     | { kind: 'reset' }
-    | { kind: 'selector'; selectors: string[] | null; china: boolean }
+    | {
+        kind: 'selector';
+        selectors: string[] | null;
+        china: boolean;
+        /** Canonical modelRole ids of the `[roleList:]` prefix; absent/null = global constraint. */
+        roleScope?: string[] | null;
+    }
     | { kind: 'error'; message: string };
 
 /**
@@ -143,6 +196,13 @@ export type AutoModelParseResult =
  * - Selectors are only lowercased (the `*`/`/` structure is preserved, no token
  *   splitting) and split on whitespace — a selector containing `/` is kept whole.
  * - Any unknown `-`/`--` flag is a usage error.
+ * - `[roleList:]<selector>` prefix (change: pick-model-role-scope): recognized on
+ *   the first selector token only; the colon is a RESERVED character — a colon
+ *   token that does not establish a roleList intent (single word not in the
+ *   vocabulary, e.g. `zhipu:glm`, starred or not, anywhere in the command) is a
+ *   usage error with the full vocabulary inlined, never a selector (the bare-word
+ *   matcher splits on non-alphanumerics, so a colon token falling through would
+ *   silently OR-apply as a global constraint).
  */
 export function parseAutoModelArgs(args: string): AutoModelParseResult {
     const tokens = args
@@ -158,6 +218,10 @@ export function parseAutoModelArgs(args: string): AutoModelParseResult {
 
     const selectors: string[] = [];
     let china = false;
+    // undefined = no `[roleList:]` prefix seen; otherwise the resolved scope
+    // (null when the prefix was `all`).
+    let roleScope: string[] | null | undefined;
+    let seenSelectorToken = false;
     for (const tok of tokens) {
         if (tok === '--china') {
             china = true;
@@ -165,10 +229,59 @@ export function parseAutoModelArgs(args: string): AutoModelParseResult {
             return { kind: 'error', message: `未知参数: ${tok}` };
         } else if (Object.hasOwn(RESERVED_SUBCOMMANDS, tok)) {
             return { kind: 'error', message: `保留字 "${tok}" 不能与 selector/flag 混用` };
+        } else if (tok.includes(':')) {
+            if (seenSelectorToken || roleScope !== undefined) {
+                return {
+                    kind: 'error',
+                    message: `"${tok}" 含冒号，但 role 定向前缀仅识别于第一个 selector token。${roleScopeVocabularyText()}`,
+                };
+            }
+            const colon = tok.indexOf(':');
+            const entries = tok
+                .slice(0, colon)
+                .split(',')
+                .map((e) => e.trim())
+                .filter((e) => e.length > 0);
+            // roleList intent ⟺ multiple comma entries, or a single entry in the
+            // vocabulary (built-in role, agent alias, or `all`).
+            const intent =
+                entries.length > 1 ||
+                (entries.length === 1 &&
+                    (entries[0] === 'all' ||
+                        (MODEL_ROLE_IDS as readonly string[]).includes(entries[0]) ||
+                        Object.hasOwn(AGENT_ROLE_SCOPE_ALIASES, entries[0])));
+            if (!intent) {
+                return {
+                    kind: 'error',
+                    message: `"${tok}" 含冒号，但前缀不是 role 定向（冒号为保留字符，不能用于 selector）。${roleScopeVocabularyText()}`,
+                };
+            }
+            try {
+                roleScope = resolveRoleScopeEntries(entries);
+            } catch (e) {
+                if (e instanceof RoleScopeUsageError) return { kind: 'error', message: e.message };
+                throw e;
+            }
+            const rest = tok.slice(colon + 1);
+            if (rest.length > 0) selectors.push(rest);
+            seenSelectorToken = true;
         } else {
             selectors.push(tok);
+            seenSelectorToken = true;
         }
     }
 
-    return { kind: 'selector', selectors: selectors.length > 0 ? [...new Set(selectors)] : null, china };
+    if (selectors.length === 0) {
+        if (roleScope !== undefined) {
+            return { kind: 'error', message: `role 定向前缀后缺少 selector。${roleScopeVocabularyText()}` };
+        }
+        return { kind: 'selector', selectors: null, china };
+    }
+    const result: AutoModelParseResult = {
+        kind: 'selector',
+        selectors: [...new Set(selectors)],
+        china,
+    };
+    if (roleScope) result.roleScope = roleScope;
+    return result;
 }

package/lib/model-roles.ts

@@ -5,21 +5,26 @@
  * 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
+ * change: pick-model-ux (supersedes pick-model-batch-all-roles) — the overlay
+ * writes ONLY the minimal write set {smol, default, slow, vision}: smol ← mid
+ * pick (coder), default ← high pick (reviewer), slow ← the sole supplemental
+ * (top) pick, vision ← capability-gated pick. `buildRoleOverridePlan` maps
+ * each write-set 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) →
+ * vision/image, or no picked model for the tier). Roles outside the write set
+ * resolve through OMP native chains: designer via default inheritance,
+ * commit/tiny via enumeration fallbacks terminating at smol, task via
+ * primary-session inheritance, plan as a graceful no-op, advisor via the
+ * static slow chain, custom roles via the config layer. 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';
+import { OPSX_AGENTS } from './unified-config.js';
 
 /** Per-agent names written into `task.agentModelOverrides` neutralization. */
 const AGENT_MODEL_KEYS: Record<string, string> = {
@@ -38,10 +43,10 @@ export const ROLE_TO_OMP_ALIAS: Record<string, string> = {
 };
 
 /**
- * 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.
+ * Built-in OMP model role → default tier. The `satisfies` clause forces the
+ * table to cover every built-in role. Entries outside the write set stay
+ * relevant as the tier-key source for role-scope slot resolution
+ * (`scopedTierSlots`), which may point any scope role at its slot.
  */
 export const OMP_ROLE_TO_TIER = {
     tiny: 'tiny',
@@ -69,6 +74,14 @@ export const ROLE_CAPABILITY: Record<string, (model: Model<Api>) => boolean> = {
     vision: (model) => Array.isArray(model.input) && model.input.includes('image'),
 };
 
+/**
+ * Minimal write set (change: pick-model-ux design D5): the ONLY roles the
+ * plugin writes into `overrideModelRoles`. Every other role resolves through
+ * OMP native chains that terminate at these writes; `model_role_tiers`
+ * entries for other roles are inert for the write plan.
+ */
+export const OMP_WRITE_SET_ROLES = ['smol', 'default', 'slow', 'vision'] as const;
+
 /** Why a known role was left out of the overlay payload. */
 export type RoleSkipReason = 'skip' | 'capability' | 'no-pick';
 
@@ -88,8 +101,6 @@ export interface RoleOverridePlan {
 
 /** 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'>;
     /**
@@ -106,45 +117,36 @@ export interface BuildRoleOverridePlanInput {
     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).
+ * Resolve the tier a role's slot follows: explicit `model_role_tiers` value
+ * (including the `skip` sentinel) → built-in default table → `high`
+ * fallback. The fallback is only reachable for non-table scope roles in
+ * `scopedTierSlots` (role-scope slot resolution); the write plan iterates
+ * `OMP_WRITE_SET_ROLES`, all of which are table keys.
  */
 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).
+ * Build the minimal write-set overlay plan (design D5): for each role in
+ * `OMP_WRITE_SET_ROLES`, 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). Roles outside the write set are never iterated.
  */
-export function buildRoleOverridePlan(
-    input: BuildRoleOverridePlanInput,
-    warn: (msg: string) => void = () => {},
-): RoleOverridePlan {
+export function buildRoleOverridePlan(input: BuildRoleOverridePlanInput): RoleOverridePlan {
     const overrides: Record<string, string> = {};
     const skipped: SkippedRole[] = [];
-    for (const role of input.knownRoleIds) {
-        const tier = resolveOmpRoleTier(role, input.ompRoleTiers, warn);
+    for (const role of OMP_WRITE_SET_ROLES) {
+        const tier = resolveOmpRoleTier(role, input.ompRoleTiers);
         if (tier === 'skip') {
             skipped.push({ role, reason: 'skip' });
             continue;
@@ -220,7 +222,7 @@ export function dispatchModelHint(role: string, selection: SelectionContext): st
  */
 export function agentOverrideNeutralization(): Record<string, string> {
     const neutral: Record<string, string> = {};
-    for (const role of OPSX_ROLES) neutral[AGENT_MODEL_KEYS[role]] = '';
+    for (const role of OPSX_AGENTS) neutral[AGENT_MODEL_KEYS[role]] = '';
     return neutral;
 }
 
@@ -236,10 +238,10 @@ export interface RoleSettings {
  *
  * 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
+ * a previous constraint would otherwise linger) → write the minimal write-set
+ * 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(