@jianxx/dsh-cc-model-aliases 0.3.0 → 0.4.1

package/lib/resolver.js

@@ -10,21 +10,50 @@
  * live settings edits take effect on the next spawn without re-registering
  * anything.
  *
- * Only the four builtin alias names have a fallback when they are unconfigured
- * — they resolve to "inherit the parent route" (`undefined`), matching the
- * deployment decision that a zero-config `model: sonnet` agent silently uses
- * the parent's current model. A custom (open-set) alias that is unconfigured
- * has no fallback: it passes through verbatim as a literal model id, with a
- * warning when it looks like an intended alias.
+ * Builtin alias names (Claude Code family plus the dsh-cc lane names) have a
+ * fallback when they are unconfigured — they resolve to "inherit the parent
+ * route" (`undefined`), matching the deployment decision that a zero-config
+ * `model: sonnet` / `model: draft` agent silently uses the parent's current
+ * model. A custom (open-set) alias that is unconfigured has no fallback: it
+ * passes through verbatim as a literal model id, with a warning when it looks
+ * like an intended alias.
  *
  * @module @jianxx/dsh-cc-model-aliases/resolver
  */
+/**
+ * Claude Code family aliases. Unconfigured → inherit the parent route.
+ * Case-insensitive; a configured value still wins over this fallback.
+ */
+export const CC_ALIASES = ['fable', 'opus', 'sonnet', 'haiku'];
+/**
+ * dsh-cc lane aliases. Unconfigured, a lane follows its CC peer
+ * ({@link LANE_PEERS}) so `model: sketch` shares a configured `haiku`
+ * route without a second settings entry. `architect` has no peer and
+ * inherits the parent (main-thread) route. A configured string-form
+ * target that names another alias is followed one hop.
+ *
+ * | lane | role | CC peer when unconfigured |
+ * |---|---|---|
+ * | `sketch` | fast, lightweight execution | haiku |
+ * | `draft` | balanced everyday coding | sonnet |
+ * | `blueprint` | deep reasoning | opus |
+ * | `masterplan` | maximum reasoning | fable |
+ * | `architect` | planning / orchestration | inherit (main thread) |
+ */
+export const LANE_ALIASES = ['sketch', 'draft', 'blueprint', 'masterplan', 'architect'];
+/** Unconfigured lane → CC family alias it shares a route with. */
+export const LANE_PEERS = {
+    sketch: 'haiku',
+    draft: 'sonnet',
+    blueprint: 'opus',
+    masterplan: 'fable',
+};
 /**
  * The builtin alias names that fall back to "inherit the parent route" when
  * unconfigured. Case-insensitive; a configured value still wins over this
  * fallback.
  */
-export const BUILTIN_ALIASES = ['fable', 'opus', 'sonnet', 'haiku'];
+export const BUILTIN_ALIASES = [...CC_ALIASES, ...LANE_ALIASES];
 /** The set of builtin names, lowercased, for O(1) membership checks. */
 const BUILTIN_SET = new Set(BUILTIN_ALIASES);
 /**
@@ -55,45 +84,133 @@ export function mergeAliasMaps(config, settings) {
     }
     return merged;
 }
+export function createModelResolver(getAliases, options) {
+    const inspect = createModelInspector(getAliases, options);
+    const resolveDetailed = (model) => {
+        const verdict = inspect(model);
+        if (verdict.kind === 'inherit') {
+            return { selector: model === undefined || model.trim().length === 0 ? undefined : model.trim(), via: 'inherit', route: undefined };
+        }
+        const selector = model?.trim();
+        if (verdict.kind === 'route') {
+            return { selector, via: 'alias', route: verdict.route };
+        }
+        // Upstream's inspector reports the literal passthrough for BOTH a custom
+        // alias name and a followed string-form target; our `DetailedRoute` keeps
+        // the finer split: when the literal route's model differs from the
+        // selector, the selector was a CONFIGURED alias followed to its target,
+        // so the provenance is `alias`, not `literal`.
+        const followed = verdict.route !== undefined && verdict.route.model !== undefined && verdict.route.model !== selector;
+        return { selector: followed ? selector : verdict.route?.model, via: followed ? 'alias' : 'literal', route: verdict.route };
+    };
+    // `resolve` is derived from `resolveDetailed` so the classification and the
+    // route always come from the SAME merged map — no double lookup, and the
+    // legacy route behavior stays byte-identical by construction.
+    const resolve = (model) => resolveDetailed(model).route;
+    return Object.assign(resolve, { resolveDetailed });
+}
 /**
- * Build a `resolveModel` closure for an agent provider. The alias source is a
- * thunk evaluated on every invocation, so the closure reads the live settings
- * and merges fresh each spawn (see the plan's liveness requirement).
- * @param getAliases - returns the effective alias map for this invocation (the
- *   caller composes config + live settings via {@link mergeAliasMaps}).
- * @param options - optional warning hook for unsigned custom aliases; the
- *   message is emitted (defaulting to `console.warn`) when a model that is not
- *   a configured alias and not a builtin looks like an intended alias (a bare
- *   lowercase alphabetic word) and is passed through verbatim.
- * @returns the resolution function mapping a frontmatter `model` to a route, or
- *   `undefined` for no override.
+ * Build an inspector that classifies one frontmatter `model` the same way
+ * {@link createModelResolver} resolves it, additionally reporting provenance
+ * (kind / via / hop) for tooling like `/doctor`. The `route` field is exactly
+ * what `resolve()` returns for the same input.
+ * @param getAliases - returns the effective alias map for this invocation.
+ * @param options - same warning hook as {@link createModelResolver}.
+ * @returns the inspection function mapping a frontmatter `model` to an
+ *   {@link AliasInspection}.
  */
-export function createModelResolver(getAliases, options) {
+export function createModelInspector(getAliases, options) {
     const warn = options?.warn ?? ((message) => console.warn(message));
     return (model) => {
         if (model === undefined || model.trim().length === 0)
-            return undefined;
+            return { kind: 'inherit' };
         const trimmed = model.trim();
         const folded = trimmed.toLowerCase();
         if (folded === 'inherit')
-            return undefined;
+            return { kind: 'inherit' };
         const aliases = getAliases();
         const hit = aliases.get(folded);
         if (hit !== undefined && hit !== null) {
-            return typeof hit === 'string' ? { model: hit } : { provider: hit.provider, model: hit.model };
+            if (typeof hit === 'string') {
+                const followed = followStringTarget(hit, aliases, folded);
+                const foldedTarget = hit.trim().toLowerCase();
+                if (followed.kind === 'route')
+                    return { kind: 'route', via: 'one-hop', hop: foldedTarget, route: followed.route };
+                if (followed.kind === 'inherit')
+                    return { kind: 'inherit', via: 'one-hop', hop: foldedTarget };
+                return { kind: 'literal', route: { model: hit } };
+            }
+            // Object form: forward the route fields that are present. `provider` and
+            // `reasoningEffort` are optional (absent = inherit / no stamp); `model`
+            // is always set on a schema-valid object entry. Object targets are
+            // concrete routes — they are not followed as alias names.
+            return {
+                kind: 'route',
+                via: 'configured',
+                route: {
+                    ...(hit.provider === undefined ? {} : { provider: hit.provider }),
+                    ...(hit.model === undefined ? {} : { model: hit.model }),
+                    ...(hit.reasoningEffort === undefined ? {} : { reasoningEffort: hit.reasoningEffort }),
+                },
+            };
+        }
+        // Unconfigured lane → follow its CC peer (`sketch` → `haiku`, …).
+        // `architect` has no peer and falls through to inherit. Choice: when the
+        // peer resolves to a configured route we report `via: 'alias'` (the lane
+        // shares the peer alias's route); when the peer is itself unconfigured the
+        // lane inherits, so `via: 'inherit'` — matching today's `resolve()`.
+        const peer = LANE_PEERS[folded];
+        if (peer !== undefined) {
+            const followed = followStringTarget(peer, aliases, folded);
+            if (followed.kind === 'route')
+                return { kind: 'route', via: 'peer', hop: peer, route: followed.route };
+            return { kind: 'inherit', via: 'peer', hop: peer };
         }
         // Unconfigured builtin alias → inherit the parent route ("current model").
         if (BUILTIN_SET.has(folded))
-            return undefined;
+            return { kind: 'inherit', via: 'builtin' };
         // Custom alias that is unconfigured: warn when it looks like an intended
         // alias, then pass through verbatim as a literal model id (no regression
         // for literal ids such as `deepseek-chat`).
         if (/^[a-z]+$/.test(folded)) {
             warn(`cc-model-aliases: model "${trimmed}" is not a configured alias and is not builtin; passing through verbatim as a literal model id`);
         }
-        return { model: trimmed };
+        return { kind: 'literal', route: { model: trimmed } };
     };
 }
+/**
+ * Follow a string-form target one hop when it names another alias.
+ *
+ * - `sketch: haiku` with haiku configured → haiku's route
+ * - `sketch: haiku` with haiku unconfigured (builtin) → inherit
+ * - `sketch: inherit` → inherit
+ * - `sketch: deepseek-chat` (not an alias) → literal, caller keeps the string
+ *
+ * A second hop is not followed (`sketch: draft` + `draft: haiku` stops at
+ * the literal `"haiku"`), which keeps cycles from looping. Object-form
+ * targets are never followed as names.
+ */
+function followStringTarget(target, aliases, from) {
+    const folded = target.trim().toLowerCase();
+    if (folded.length === 0 || folded === from || folded === 'inherit')
+        return { kind: 'inherit' };
+    const next = aliases.get(folded);
+    if (next !== undefined && next !== null) {
+        if (typeof next === 'string')
+            return { kind: 'route', route: { model: next } };
+        return {
+            kind: 'route',
+            route: {
+                ...(next.provider === undefined ? {} : { provider: next.provider }),
+                ...(next.model === undefined ? {} : { model: next.model }),
+                ...(next.reasoningEffort === undefined ? {} : { reasoningEffort: next.reasoningEffort }),
+            },
+        };
+    }
+    if (BUILTIN_SET.has(folded))
+        return { kind: 'inherit' };
+    return { kind: 'literal' };
+}
 /** Compact-fill a record's own string keys, folding each to lowercase. */
 function foldKeys(record) {
     const out = new Map();

package/lib/resolver.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"resolver.js","sourceRoot":"","sources":["../src/resolver.ts"],"names":[],"mappings":"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"}

package/lib/schema.d.ts

@@ -6,9 +6,10 @@
  * delete an alias — values are a model id or an explicit `{provider, model}`
  * route. The settings overlay (`model-aliases` namespace) may additionally be
  * `null` for a key, which deletes a same-named config-default entry during
- * merge. Object-form targets require a non-empty `provider` and `model` so a
- * half-written route is rejected at schema-validation time rather than
- * surfacing as an empty-field override at spawn.
+ * merge. Object-form targets require a non-empty `model`; `provider` is
+ * optional (inherit the parent provider) but must be non-empty when present.
+ * A half-written route is rejected at the service write-time validate rather
+ * than surfacing as an empty-field override at spawn.
  *
  * The settings overlay is a shallow record keyed by alias name; the 5-cascade
  * layer merge inside settings is recursively deep (existing cascade
@@ -28,9 +29,11 @@ import type { AliasTarget } from './types.ts';
 export declare const ConfigAliasSchema: z<string | ({
     provider?: string | null;
     model?: string | null;
+    reasoningEffort?: string | null;
 } & import("@deepseek-ai/cosmokit").Dict), string | Schemastery.ObjectT<{
     provider: z<string, string>;
     model: z<string, string>;
+    reasoningEffort: z<string, string>;
 }>>;
 /**
  * Schema for a settings `model-aliases` value: a model id, an explicit route,
@@ -39,9 +42,11 @@ export declare const ConfigAliasSchema: z<string | ({
 export declare const SettingsAliasSchema: z<string | ({
     provider?: string | null;
     model?: string | null;
+    reasoningEffort?: string | null;
 } & import("@deepseek-ai/cosmokit").Dict) | null, string | Schemastery.ObjectT<{
     provider: z<string, string>;
     model: z<string, string>;
+    reasoningEffort: z<string, string>;
 }> | null>;
 /**
  * Schema for the whole config `modelAliases` record.
@@ -49,9 +54,11 @@ export declare const SettingsAliasSchema: z<string | ({
 export declare const ConfigAliasesSchema: z<import("@deepseek-ai/cosmokit").Dict<string | ({
     provider?: string | null;
     model?: string | null;
+    reasoningEffort?: string | null;
 } & import("@deepseek-ai/cosmokit").Dict), string>, import("@deepseek-ai/cosmokit").Dict<string | Schemastery.ObjectT<{
     provider: z<string, string>;
     model: z<string, string>;
+    reasoningEffort: z<string, string>;
 }>, string>>;
 /**
  * Schema for the whole settings `model-aliases` section.
@@ -59,9 +66,11 @@ export declare const ConfigAliasesSchema: z<import("@deepseek-ai/cosmokit").Dict
 export declare const SettingsAliasesSchema: z<import("@deepseek-ai/cosmokit").Dict<string | ({
     provider?: string | null;
     model?: string | null;
+    reasoningEffort?: string | null;
 } & import("@deepseek-ai/cosmokit").Dict) | null, string>, import("@deepseek-ai/cosmokit").Dict<string | Schemastery.ObjectT<{
     provider: z<string, string>;
     model: z<string, string>;
+    reasoningEffort: z<string, string>;
 }> | null, string>>;
 /** The validated shape of one config entry (modelled on the schema). */
 export type ConfigAliasEntry = Exclude<AliasTarget, null>;

package/lib/schema.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAW7C;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;GAAwC,CAAA;AAEtE;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;UAAuD,CAAA;AAEvF;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;YAA4B,CAAA;AAE5D;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;;;mBAA8B,CAAA;AAEhE,wEAAwE;AACxE,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,CAAA;AACzD,2EAA2E;AAC3E,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAAA"}
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AACxC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAiB7C;;;;GAIG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;GAAwC,CAAA;AAEtE;;;GAGG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;UAAuD,CAAA;AAEvF;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;YAA4B,CAAA;AAE5D;;GAEG;AACH,eAAO,MAAM,qBAAqB;;;;;;;;mBAA8B,CAAA;AAEhE,wEAAwE;AACxE,MAAM,MAAM,gBAAgB,GAAG,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,CAAA;AACzD,2EAA2E;AAC3E,MAAM,MAAM,kBAAkB,GAAG,WAAW,CAAA"}

package/lib/schema.js

@@ -6,9 +6,10 @@
  * delete an alias — values are a model id or an explicit `{provider, model}`
  * route. The settings overlay (`model-aliases` namespace) may additionally be
  * `null` for a key, which deletes a same-named config-default entry during
- * merge. Object-form targets require a non-empty `provider` and `model` so a
- * half-written route is rejected at schema-validation time rather than
- * surfacing as an empty-field override at spawn.
+ * merge. Object-form targets require a non-empty `model`; `provider` is
+ * optional (inherit the parent provider) but must be non-empty when present.
+ * A half-written route is rejected at the service write-time validate rather
+ * than surfacing as an empty-field override at spawn.
  *
  * The settings overlay is a shallow record keyed by alias name; the 5-cascade
  * layer merge inside settings is recursively deep (existing cascade
@@ -21,10 +22,16 @@
 import z from '@deepseek-ai/schemastery';
 /** A target that only names a model id (provider inherits the parent route). */
 const MODEL_ONLY = z.string().min(1);
-/** A target that pins an explicit `{provider, model}` route. */
+/**
+ * A target that pins an explicit route: `model` is required; `provider` is
+ * optional (inherit the parent provider) but must be non-empty when present;
+ * `reasoningEffort` is an optional opaque non-empty string whose legal
+ * spellings belong to the target model's adapter.
+ */
 const EXPLICIT_ROUTE = z.object({
     provider: z.string().min(1),
     model: z.string().min(1),
+    reasoningEffort: z.string().min(1),
 });
 /**
  * Schema for a deployment `config` alias value: a model id or an explicit

package/lib/schema.js.map

@@ -1 +1 @@
-{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAGxC,gFAAgF;AAChF,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;AAEpC,gEAAgE;AAChE,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACzB,CAAC,CAAA;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,CAAA;AAEtE;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,UAAU,EAAE,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AAEvF;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAA;AAE5D;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAA"}
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAGxC,gFAAgF;AAChF,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAA;AAEpC;;;;;GAKG;AACH,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IAC9B,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3B,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACxB,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACnC,CAAC,CAAA;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC,CAAA;AAEtE;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,UAAU,EAAE,cAAc,EAAE,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAA;AAEvF;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAA;AAE5D;;GAEG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAA"}

package/lib/service.d.ts

@@ -16,7 +16,7 @@
  */
 import z from '@deepseek-ai/schemastery';
 import type { Context } from '@deepseek-ai/cordis';
-import type { AliasTarget, ResolvedRoute } from './types.ts';
+import type { AliasInspection, AliasTarget, DetailedRoute, ResolvedRoute } from './types.ts';
 /** Plugin configuration: deployment-default alias map. */
 export interface Config {
     /** Deployment defaults (alias name → model id or `{provider, model}` route). */
@@ -24,10 +24,20 @@ export interface Config {
 }
 /** Runtime config schema (config-layer aliases never hold null). */
 export declare const Config: z<Config>;
+/** The settings namespace carrying the live `model-aliases` overlay. */
+export declare const MODEL_ALIASES_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
 /** The shape consumers resolve through. */
 export interface ModelRoutes {
     /** Resolve one frontmatter `model` to a dsh route, or undefined to inherit. */
     resolve(model: string | undefined): ResolvedRoute | undefined;
+    /**
+     * Atomic detailed resolution: `{selector, via, route}` from ONE settings
+     * snapshot — `via` records how the selector was classified (alias / literal
+     * / inherit) so callers can capture provenance without a second, racy lookup.
+     */
+    resolveDetailed(model: string | undefined): DetailedRoute;
+    /** Inspect one frontmatter `model` with provenance (for `/doctor` reporting). */
+    inspect(model: string | undefined): AliasInspection;
 }
 /** Cordis plugin id. */
 export declare const name = "cc-model-routes";
@@ -38,4 +48,24 @@ export declare const name = "cc-model-routes";
  * @param config - deployment defaults.
  */
 export declare function apply(ctx: Context, config?: Config): void;
+/**
+ * Host-plane alias read WITHOUT owning the namespace: resolve through the
+ * `ccModelRoutes` service when one is mounted, otherwise read the live
+ * `model-aliases` settings overlay directly. Never re-registers the namespace
+ * — the isolated `cc-model-routes` plugin row already owns that registration,
+ * and `settings.register` throws on a duplicate namespace.
+ * @param ctx - the host context (no plugin instance required).
+ * @param alias - frontmatter model alias, or undefined to inherit.
+ * @returns the resolved route, or undefined to inherit the parent route.
+ */
+export declare function resolveAlias(ctx: Context, alias: string | undefined): ResolvedRoute | undefined;
+/**
+ * Host-plane DETAILED alias read: the provenance-carrying counterpart of
+ * {@link resolveAlias}, with the same service-then-overlay fallback and the
+ * same single-snapshot guarantee (classification and route from one map).
+ * @param ctx - the host context (no plugin instance required).
+ * @param alias - frontmatter model alias, or undefined to inherit.
+ * @returns the atomic detailed resolution for the alias.
+ */
+export declare function resolveDetailedAlias(ctx: Context, alias: string | undefined): DetailedRoute;
 //# sourceMappingURL=service.d.ts.map

package/lib/service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AACxC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAKlD,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE5D,0DAA0D;AAC1D,MAAM,WAAW,MAAM;IACrB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAA;CAC1D;AAED,oEAAoE;AACpE,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAAmD,CAAA;AAKhF,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,CAAA;CAC9D;AAED,wBAAwB;AACxB,eAAO,MAAM,IAAI,oBAAoB,CAAA;AAErC;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI,CAuB7D"}
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AACxC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AASlD,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE5F,0DAA0D;AAC1D,MAAM,WAAW,MAAM;IACrB,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC,CAAA;CAC1D;AAED,oEAAoE;AACpE,eAAO,MAAM,MAAM,EAAE,CAAC,CAAC,MAAM,CAAmD,CAAA;AAEhF,wEAAwE;AACxE,eAAO,MAAM,uBAAuB,uDAAqC,CAAA;AAEzE,2CAA2C;AAC3C,MAAM,WAAW,WAAW;IAC1B,+EAA+E;IAC/E,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,CAAA;IAC7D;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAAA;IACzD,iFAAiF;IACjF,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,eAAe,CAAA;CACpD;AAED,wBAAwB;AACxB,eAAO,MAAM,IAAI,oBAAoB,CAAA;AAErC;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI,CA2C7D;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS,CAS/F;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,CAS3F"}

package/lib/service.js

@@ -17,11 +17,12 @@
 import z from '@deepseek-ai/schemastery';
 import { settingsNamespace } from '@deepseek-ai/dsh-settings';
 import { ConfigAliasesSchema, SettingsAliasesSchema } from "./schema.js";
-import { createModelResolver, mergeAliasMaps } from "./resolver.js";
+import { createModelInspector, createModelResolver, mergeAliasMaps } from "./resolver.js";
+import { overlayStampedEffort, stampedEffortOf } from "./effort.js";
 /** Runtime config schema (config-layer aliases never hold null). */
 export const Config = z.object({ modelAliases: ConfigAliasesSchema });
 /** The settings namespace carrying the live `model-aliases` overlay. */
-const MODEL_ALIASES_NAMESPACE = settingsNamespace('model-aliases');
+export const MODEL_ALIASES_NAMESPACE = settingsNamespace('model-aliases');
 /** Cordis plugin id. */
 export const name = 'cc-model-routes';
 /**
@@ -38,14 +39,70 @@ export function apply(ctx, config = {}) {
         validate: (value) => {
             for (const [alias, target] of Object.entries(value)) {
                 if (target !== null && typeof target === 'object') {
-                    if (target.provider.trim().length === 0 || target.model.trim().length === 0) {
-                        throw new Error(`cc-model-aliases: model alias "${alias}" must specify a non-empty provider and model`);
+                    if (typeof target.model !== 'string' || target.model.trim().length === 0) {
+                        throw new Error(`cc-model-aliases: model alias "${alias}" must specify a non-empty model`);
+                    }
+                    if (target.provider !== undefined && target.provider.trim().length === 0) {
+                        throw new Error(`cc-model-aliases: model alias "${alias}" must specify a non-empty provider when present`);
                     }
                 }
             }
         },
     });
-    const resolve = createModelResolver(() => mergeAliasMaps(config.modelAliases, scope?.get?.()), { warn: message => ctx.logger.warn(message) });
-    ctx.provide('ccModelRoutes', { resolve });
+    const aliasSources = () => mergeAliasMaps(config.modelAliases, scope?.get?.());
+    const warnOptions = { warn: (message) => ctx.logger.warn(message) };
+    const resolver = createModelResolver(aliasSources, warnOptions);
+    const inspect = createModelInspector(aliasSources, warnOptions);
+    const resolveDetailed = resolver.resolveDetailed;
+    // Both consumption shapes must be published: the Task tool's resume-pin
+    // capture calls `resolveDetailed` — publishing only `resolve` makes every
+    // captured background spawn throw TypeError at spawn time. `inspect` keeps
+    // the upstream provenance form (`/doctor`) available alongside.
+    ctx.provide('ccModelRoutes', { resolve: resolver, resolveDetailed, inspect });
+    // Host-side effort overlay: a child spawned through an alias whose route
+    // declared `reasoningEffort` carries it on its options as an undeclared
+    // runtime extra key (stamped by the Task tool / plugin-loader). buildRequest
+    // deep-freezes its seed config and may restore an explicit parent /effort
+    // from a fork seed's request/header — the alias contract wins, so overlay
+    // AFTER `next()` with a shallow copy (never in place). Root agents carry no
+    // stamp on options, so this is a no-op for them.
+    ctx.on('agent/request', async ({ agent }, next) => {
+        const resolved = await next();
+        return overlayStampedEffort(resolved, stampedEffortOf(agent.options));
+    });
+}
+/**
+ * Host-plane alias read WITHOUT owning the namespace: resolve through the
+ * `ccModelRoutes` service when one is mounted, otherwise read the live
+ * `model-aliases` settings overlay directly. Never re-registers the namespace
+ * — the isolated `cc-model-routes` plugin row already owns that registration,
+ * and `settings.register` throws on a duplicate namespace.
+ * @param ctx - the host context (no plugin instance required).
+ * @param alias - frontmatter model alias, or undefined to inherit.
+ * @returns the resolved route, or undefined to inherit the parent route.
+ */
+export function resolveAlias(ctx, alias) {
+    const routes = ctx.get('ccModelRoutes');
+    if (routes !== undefined)
+        return routes.resolve(alias);
+    const settings = ctx.get('settings');
+    const overlay = settings?.get?.(MODEL_ALIASES_NAMESPACE);
+    return createModelResolver(() => mergeAliasMaps(undefined, overlay), { warn: message => ctx.logger.warn(message) })(alias);
+}
+/**
+ * Host-plane DETAILED alias read: the provenance-carrying counterpart of
+ * {@link resolveAlias}, with the same service-then-overlay fallback and the
+ * same single-snapshot guarantee (classification and route from one map).
+ * @param ctx - the host context (no plugin instance required).
+ * @param alias - frontmatter model alias, or undefined to inherit.
+ * @returns the atomic detailed resolution for the alias.
+ */
+export function resolveDetailedAlias(ctx, alias) {
+    const routes = ctx.get('ccModelRoutes');
+    if (routes !== undefined)
+        return routes.resolveDetailed(alias);
+    const settings = ctx.get('settings');
+    const overlay = settings?.get?.(MODEL_ALIASES_NAMESPACE);
+    return createModelResolver(() => mergeAliasMaps(undefined, overlay), { warn: message => ctx.logger.warn(message) }).resolveDetailed(alias);
 }
 //# sourceMappingURL=service.js.map

package/lib/service.js.map

@@ -1 +1 @@
-{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAGxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACxE,OAAO,EAAE,mBAAmB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AASnE,oEAAoE;AACpE,MAAM,CAAC,MAAM,MAAM,GAAc,CAAC,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,mBAAmB,EAAE,CAAC,CAAA;AAEhF,wEAAwE;AACxE,MAAM,uBAAuB,GAAG,iBAAiB,CAAC,eAAe,CAAC,CAAA;AAQlE,wBAAwB;AACxB,MAAM,CAAC,MAAM,IAAI,GAAG,iBAAiB,CAAA;AAErC;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAC,GAAY,EAAE,SAAiB,EAAE;IACrD,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,UAAU,CAAiC,CAAA;IACpE,MAAM,KAAK,GAAG,QAAQ,EAAE,QAAQ,CAAC,uBAAuB,EAAE,qBAAqB,EAAE;QAC/E,2EAA2E;QAC3E,0CAA0C;QAC1C,QAAQ,EAAE,CAAC,KAAyC,EAAE,EAAE;YACtD,KAAK,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;gBACpD,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;oBAClD,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;wBAC5E,MAAM,IAAI,KAAK,CAAC,kCAAkC,KAAK,+CAA+C,CAAC,CAAA;oBACzG,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;KACF,CAAC,CAAA;IACF,MAAM,OAAO,GAAG,mBAAmB,CACjC,GAAG,EAAE,CAAC,cAAc,CAClB,MAAM,CAAC,YAAY,EACnB,KAAK,EAAE,GAAG,EAAE,EAAoD,CACjE,EACD,EAAE,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAC9C,CAAA;IACD,GAAG,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,OAAO,EAAE,CAAC,CAAA;AAC3C,CAAC"}
+{"version":3,"file":"service.js","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"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"}

package/lib/types.d.ts

@@ -17,28 +17,83 @@
  * When `start()` passes this on as `agentOptions`, only the fields that are
  * present (`provider` and/or `model`) override the delegation; a route omitting
  * `provider` inherits the parent's provider, and one omitting `model` inherits
- * the parent's model. `undefined` means "no override" — the child inherits the
- * parent route wholesale (the `inherit` sentinel and the builtin fallback both
- * resolve to this).
+ * the parent's model. `reasoningEffort`, when present, is stamped onto the
+ * child's options (a runtime extra key) and applied to every child request by
+ * the host `agent/request` listener in the routes service. `undefined` means
+ * "no override" — the child inherits the parent route wholesale (the `inherit`
+ * sentinel and the builtin fallback both resolve to this).
  */
 export interface ResolvedRoute {
     /** The provider to route to; omit to inherit the parent's provider. */
     readonly provider?: string | undefined;
     /** The model id (or resolved alias model) to use; omit to inherit. */
     readonly model?: string | undefined;
+    /**
+     * Reasoning effort stamped from the alias target (object form only); an
+     * opaque non-empty string whose legal spellings belong to the target model's
+     * adapter (`max`, `xhigh`, `high`, …). Absent → no effort stamp.
+     */
+    readonly reasoningEffort?: string | undefined;
+}
+/**
+ * What an alias lookup resolved to, for provenance reporting (`/doctor`).
+ *
+ * - `route`: a concrete route was produced (configured object, or a followed
+ *   string/peer target).
+ * - `inherit`: no override — the child inherits the parent route.
+ * - `literal`: the alias name is passed through verbatim as a model id.
+ */
+export type AliasInspectKind = 'route' | 'inherit' | 'literal';
+/**
+ * Where the classification came from: a directly configured entry, a peer
+ * lane's entry, a one-hop string target, or the builtin fallback.
+ */
+export type AliasInspectVia = 'configured' | 'peer' | 'one-hop' | 'builtin';
+/**
+ * Provenance of one alias resolution. `route` is exactly what
+ * `resolve()` returned for the same input; `via`/`hop` are omitted when not
+ * meaningful (e.g. the literal passthrough and the bare inherit cases).
+ */
+export interface AliasInspection {
+    readonly kind: AliasInspectKind;
+    readonly route?: ResolvedRoute;
+    readonly via?: AliasInspectVia;
+    readonly hop?: string;
+}
+/**
+ * One atomic resolution result: the effective route PLUS its provenance,
+ * captured from a single settings snapshot (never re-derived later). `via`
+ * records how `selector` was classified:
+ * - `inherit`: no override (`undefined`, blank, the `inherit` sentinel, an
+ *   unconfigured builtin, or an unresolvable lane peer) — the parent route
+ *   stands and `route` is undefined.
+ * - `alias`: a configured alias (or a lane peer sharing a configured peer's
+ *   route) — `route` is the alias's resolved route.
+ * - `literal`: passed through verbatim as a model id — `route` is
+ *   `{ model: selector }` with `provider` absent.
+ */
+export interface DetailedRoute {
+    /** The trimmed selector that was resolved (undefined for blank/undefined input). */
+    readonly selector: string | undefined;
+    /** How the selector was classified, from the same snapshot as `route`. */
+    readonly via: 'alias' | 'literal' | 'inherit';
+    /** The resolved route (undefined exactly when `via` is `inherit`). */
+    readonly route: ResolvedRoute | undefined;
 }
 /**
  * One alias target as authored in config or settings.
  *
  * A string form names only a model id (`sonnet: deepseek-chat`); the provider
  * inherits the parent route. An object form additionally pins a provider
- * (`opus: { provider: ..., model: ... }`), breaking the current frontmatter
- * limitation of never being able to override the provider. In the settings
- * layer a configured entry may instead be `null`, which deletes a same-named
- * config-default entry (see {@link mergeAliasMaps}).
+ * (`opus: { provider: ..., model: ... }`) — `provider` is optional so an alias
+ * can inherit the parent provider while still pinning a model and effort — and
+ * may carry a `reasoningEffort` stamped onto spawns of this alias. In the
+ * settings layer a configured entry may instead be `null`, which deletes a
+ * same-named config-default entry (see {@link mergeAliasMaps}).
  */
 export type AliasTarget = string | {
-    readonly provider: string;
+    readonly provider?: string;
     readonly model: string;
+    readonly reasoningEffort?: string;
 } | null;
 //# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACpC;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAA"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACtC,sEAAsE;IACtE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACnC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAC9C;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,CAAA;AAE9D;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAA;AAE3E;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,aAAa,CAAA;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,eAAe,CAAA;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAAA;IAC7C,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,CAAA;CAC1C;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,WAAW,GACjB,MAAM,GACN;IAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,GACzF,IAAI,CAAA"}