@gajae-code/coding-agent 0.12.21 → 0.13.0

package/dist/types/commands/sdk.d.ts

@@ -52,25 +52,31 @@ export declare const SESSION_HOST_DETACHED_IDLE_GRACE_MS: number;
  */
 export declare const SESSION_HOST_FIRST_ATTACH_GRACE_MS: number;
 /**
- * Resolves once this host is provably abandoned: either it has been detached
- * from every client for the full idle grace, or nobody has come for it at all
- * for the full first-attach grace.
+ * Resolves once the host is provably abandoned: either it has been detached
+ * from every client for a full idle grace, or nobody has come for it at all
+ * for a full first-attach grace.
  *
  * `readAttachedClients` reports the host's own live client/socket subscription
- * count; `undefined` means the SDK endpoint publishes no such evidence yet and
- * is deliberately *not* treated as detachment, so a host can never be reaped on
- * missing evidence — only on observed absence of clients.
+ * count; `undefined` means the SDK endpoint publishes no such evidence — before
+ * startup, after teardown, or when every reader itself fails. That ambiguity is
+ * never instant detachment: it cannot reap on the poll that first sees it, it
+ * can only open a window. Which window depends on what was already observed. A
+ * host never seen attached accrues against the first-attach bound. A host that
+ * was seen attached and has since lost its evidence is in the *more* suspicious
+ * state — a runtime that retracted its registration during teardown looks
+ * exactly like this — so it accrues against the detached idle bound, alongside
+ * an observed count of zero. Every reachable state therefore carries a finite
+ * bound.
  *
  * `readWorkInFlight` reports whether the host is running agent work right now.
- * Work is positive proof that a client did come for this host: a prompt can
- * only arrive over the endpoint a client dialed. So for a host that has never
- * been *observed* attached — a client that connected, prompted and dropped
- * between two 30s polls, or a client count that is momentarily unreadable — the
- * first-attach window is measured from the last moment work was in flight
- * rather than from process start. That still bounds a host whose SDK runtime
- * never came up: with no transport it can never receive a prompt, so it never
- * reports work and its window keeps running from start. And any real turn ends,
- * after which the window resumes; live work defers the bound, never removes it.
+ * Work is positive proof a client did come for this host: a prompt can only
+ * arrive over an endpoint a client dialed. Live work therefore restarts both
+ * windows, which is what keeps a mid-prompt host alive whether its count reads
+ * zero or stops being readable at all. That still bounds a host whose SDK
+ * runtime never came up: with no transport it can never receive a prompt, so it
+ * never reports work and its window keeps running from process start. And any
+ * real turn ends, after which the window resumes; live work defers a bound, it
+ * never removes it.
  */
 export declare function watchSessionHostClientAttachment(deps: {
     readAttachedClients: () => number | undefined;

package/dist/types/config/file-lock-gc.d.ts

@@ -7,6 +7,8 @@ export declare const FILE_LOCK_GC_MAX_WALK_ENTRIES = 20000;
 export interface FileLocksGcCollectOptions {
     /** Override per-root entry budget (tests). Defaults to {@link FILE_LOCK_GC_MAX_WALK_ENTRIES}. */
     maxWalkEntries?: number;
+    /** Override global lock roots for isolated collection tests. */
+    roots?: readonly string[];
 }
 /**
  * Discover + classify file-lock records. Each known lock root gets its own walk

package/dist/types/config/model-equivalence.d.ts

@@ -19,8 +19,23 @@ export interface CanonicalModelIndex {
     records: CanonicalModelRecord[];
     byId: Map<string, CanonicalModelRecord>;
     bySelector: Map<string, string>;
+    /**
+     * Final-slash-segment lookup aliases: normalized alias key -> normalized
+     * variant selectors ("provider/id") of every variant whose model id ends in
+     * that segment. Variant-level: an alias never widens to sibling variants in
+     * the same canonical record that end in a different segment. Multi-target
+     * when distinct variants collide on the same segment. Built without
+     * rewriting the canonical or runtime identity of any variant.
+     */
+    aliases: Map<string, string[]>;
 }
 export declare function formatCanonicalVariantSelector(model: Model<Api>): string;
+/**
+ * Normalize a model id into its final-slash-segment alias key (trimmed and
+ * lowercased). A bare id without a slash yields the id itself; a multi-level
+ * id yields its last path segment. Returns undefined for empty ids.
+ */
+export declare function getFinalSlashSegmentAliasKey(modelId: string): string | undefined;
 /**
  * Compare equivalent provider variants using the caller's ranking policy.
  *
@@ -29,8 +44,13 @@ export declare function formatCanonicalVariantSelector(model: Model<Api>): strin
  * source, input plus cache-read cost, and original catalog order. Callers that
  * do not have a canonical index can omit those axes while retaining a stable,
  * total comparison.
+ *
+ * `providerRankFirst` swaps the first two axes so configured provider rank wins
+ * over vision support; canonical/alias resolution uses this order while every
+ * existing caller keeps the legacy vision-first order by default.
  */
 export declare function compareEquivalentModelVariants(left: Model<Api>, right: Model<Api>, options?: {
+    providerRankFirst?: boolean;
     providerRank?: ReadonlyMap<string, number>;
     canonicalId?: string;
     leftSourceRank?: number;

package/dist/types/config/model-profile-activation.d.ts

@@ -1,11 +1,12 @@
 import { ThinkingLevel } from "@gajae-code/agent-core";
 import type { Api, Model } from "@gajae-code/ai/core";
-import type { AgentSession } from "../session/agent-session";
+import type { AgentSession, DefaultFallbackRuntimeState } from "../session/agent-session";
 export { resolveModelProfileName } from "./model-profile-contract";
 import { type GjcModelAssignmentTargetId, type ModelRegistry } from "./model-registry";
 import { type ModelSelectorValue } from "./model-selector-value";
 import type { Settings } from "./settings";
 type ModelProfileActivationSession = Pick<AgentSession, "model" | "thinkingLevel" | "sessionId" | "getConfiguredModelChain" | "setConfiguredModelChain"> & {
+    credentialSessionId?: string;
     setModelTemporary?: AgentSession["setModelTemporary"];
     setActiveModelProfile?: (name: string | undefined) => void;
     getActiveModelProfile?: () => string | undefined;
@@ -19,18 +20,29 @@ type ModelProfileActivationSession = Pick<AgentSession, "model" | "thinkingLevel
         agentModelOverrides: readonly string[];
     };
     getSessionDefaultModelSelector?: () => string | undefined;
-    recordResumeDefaultModel?: (selector: string) => void;
+    recordResumeDefaultModel?: (selector: string | undefined) => void;
     seedDefaultFallbackResolution?: (activeIndex: number, skips: Array<{
         selector: string;
         reason: string;
     }>) => void;
+    getDefaultFallbackRuntimeState?: () => DefaultFallbackRuntimeState;
+    restoreDefaultFallbackRuntimeState?: (state: DefaultFallbackRuntimeState) => void;
+    restoreModelSelectionForRollback?: AgentSession["restoreModelSelectionForRollback"];
+    modelRegistry?: Pick<ModelRegistry, "getSessionCanonicalVariant" | "restoreSessionCanonicalVariant" | "clearCanonicalVariant" | "getAvailable" | "lookupAliasExists" | "resolveModelByLookupAlias" | "authStorage" | "isCredentiallessProvider">;
+    getConfiguredModelChainState?: (role: string) => ConfiguredModelChainState | undefined;
+};
+type ConfiguredModelChainState = {
+    entries: readonly string[];
+    origin: string;
+    identity?: string;
+    explicitHead: boolean;
 };
 export interface PrepareModelProfileActivationOptions {
     session: ModelProfileActivationSession;
-    modelRegistry: Pick<ModelRegistry, "getModelProfile" | "getModelProfiles" | "getAvailableModelProfileNames" | "getApiKeyForProvider" | "getAll" | "resolveCanonicalModel" | "getCanonicalVariants" | "getCanonicalId"> & {
+    modelRegistry: Pick<ModelRegistry, "getModelProfile" | "getModelProfiles" | "getAvailableModelProfileNames" | "getApiKeyForProvider" | "getAll" | "resolveCanonicalModel" | "getCanonicalVariants" | "getCanonicalId"> & Partial<Pick<ModelRegistry, "getAvailable" | "resolveModelByLookupAlias" | "lookupAliasExists" | "clearCanonicalVariant" | "seedCanonicalVariant" | "getSessionCanonicalVariant" | "restoreSessionCanonicalVariant" | "getConfiguredProviderIds">> & {
         getError?: ModelRegistry["getError"];
     };
-    settings: Pick<Settings, "get" | "getGlobal">;
+    settings: Pick<Settings, "get" | "getGlobal" | "getOverride">;
     profileName: string;
 }
 export interface ApplyModelProfileActivationOptions {
@@ -42,14 +54,24 @@ export interface PreparedModelProfileActivation {
     session: ModelProfileActivationSession & {
         setModelTemporary: AgentSession["setModelTemporary"];
     };
-    settings: Pick<Settings, "clearOverride" | "get" | "getGlobal" | "override" | "set" | "unset" | "flush">;
+    settings: Pick<Settings, "clearOverride" | "get" | "getGlobal" | "getOverride" | "override" | "set" | "unset" | "flush" | "flushOrThrow">;
     previousModel: Model<Api> | undefined;
     previousThinkingLevel: ThinkingLevel | undefined;
     previousAgentModelOverrides: Record<string, ModelSelectorValue>;
     previousModelRoles: Record<string, ModelSelectorValue>;
+    previousPersistedModelRoles: Record<string, ModelSelectorValue> | undefined;
+    previousPersistedAgentModelOverrides: Record<string, ModelSelectorValue> | undefined;
+    previousModelRolesOverride: Record<string, ModelSelectorValue> | undefined;
+    previousAgentModelOverridesOverride: Record<string, ModelSelectorValue> | undefined;
+    previousDefaultProfileOverride: string | undefined;
+    previousPersistedDefaultProfile: string | undefined;
+    previousPersistedDefaultThinkingLevel: Exclude<ThinkingLevel, "inherit"> | undefined;
+    previousDefaultThinkingLevelOverride: ThinkingLevel | undefined;
     baseAgentModelOverrides: Record<string, ModelSelectorValue>;
     baseModelRoles: Record<string, ModelSelectorValue>;
     previousDefaultChain: readonly string[] | undefined;
+    previousDefaultChainState: ConfiguredModelChainState | undefined;
+    previousDefaultFallbackRuntimeState: DefaultFallbackRuntimeState | undefined;
     defaultModel: Model<Api> | undefined;
     defaultThinkingLevel: ThinkingLevel | undefined;
     /** Full configured default fallback chain with resolvable entries clamped. */
@@ -72,20 +94,27 @@ export interface PreparedModelProfileActivation {
      * resume default without promoting a transient model to it.
      */
     previousSessionDefaultModel: string | undefined;
+    /**
+     * Exact concrete sticky selector ("provider/id") snapshotted from the
+     * registry BEFORE the session sticky canonical variant is invalidated during
+     * prepare. Captured verbatim — never re-derived from the live model — so a
+     * transient live-model switch cannot corrupt the restored sticky. Rollback
+     * restores this exact selector when present; otherwise the sticky is cleared
+     * so a stale provider cannot silently resurrect.
+     */
+    previousCanonicalVariant: string | undefined;
+    /** Registry used to resolve and restore the session sticky canonical variant. */
+    modelRegistry: PrepareModelProfileActivationOptions["modelRegistry"];
 }
 export interface MaterializeModelProfileAssignmentOptions {
-    session: Pick<ModelProfileActivationSession, "model" | "thinkingLevel" | "getConfiguredModelChain" | "setActiveModelProfile" | "getActiveModelProfile"> & {
-        clearProfileInstalledOverrides?: () => void;
-    };
-    settings: Pick<Settings, "clearOverride" | "get" | "override" | "set" | "unset">;
+    session: Pick<ModelProfileActivationSession, "model" | "thinkingLevel" | "sessionId" | "credentialSessionId" | "getConfiguredModelChain" | "getConfiguredModelChainState" | "setConfiguredModelChain" | "setActiveModelProfile" | "getActiveModelProfile" | "getDefaultFallbackRuntimeState" | "restoreDefaultFallbackRuntimeState" | "modelRegistry" | "clearProfileInstalledOverrides">;
+    settings: Pick<Settings, "clearOverride" | "get" | "getGlobal" | "getOverride" | "override" | "set" | "unset">;
     role: GjcModelAssignmentTargetId;
     selector: string;
 }
 export interface MaterializeModelProfileAssignmentsOptions {
-    session: Pick<ModelProfileActivationSession, "model" | "thinkingLevel" | "getConfiguredModelChain" | "setActiveModelProfile" | "getActiveModelProfile"> & {
-        clearProfileInstalledOverrides?: () => void;
-    };
-    settings: Pick<Settings, "clearOverride" | "get" | "override" | "set" | "unset">;
+    session: Pick<ModelProfileActivationSession, "model" | "thinkingLevel" | "sessionId" | "credentialSessionId" | "getConfiguredModelChain" | "getConfiguredModelChainState" | "setConfiguredModelChain" | "setActiveModelProfile" | "getActiveModelProfile" | "getDefaultFallbackRuntimeState" | "restoreDefaultFallbackRuntimeState" | "modelRegistry" | "clearProfileInstalledOverrides">;
+    settings: Pick<Settings, "clearOverride" | "get" | "getGlobal" | "getOverride" | "override" | "set" | "unset">;
     assignments: ReadonlyMap<GjcModelAssignmentTargetId, string> | Partial<Record<GjcModelAssignmentTargetId, string>>;
 }
 export declare function materializeActiveModelProfileAssignment(options: MaterializeModelProfileAssignmentOptions): boolean;
@@ -94,7 +123,8 @@ export declare class ModelProfileCredentialError extends Error {
     readonly code = "authentication_failed";
     readonly profileLabel: string;
     readonly providers: readonly string[];
-    constructor(profileLabel: string, providers: readonly string[]);
+    readonly role: string | undefined;
+    constructor(profileLabel: string, providers: readonly string[], role?: string);
 }
 export declare function formatModelProfileCredentialError(profileLabel: string, providers: readonly string[]): string;
 export declare function prepareModelProfileActivation(options: PrepareModelProfileActivationOptions): Promise<PreparedModelProfileActivation>;
@@ -104,16 +134,31 @@ export interface MaterializeModelProfileForDeletionResult {
     agentModelOverrides: Record<string, ModelSelectorValue>;
     previousModelRoles: Record<string, ModelSelectorValue>;
     previousAgentModelOverrides: Record<string, ModelSelectorValue>;
+    previousPersistedModelRoles: Record<string, ModelSelectorValue> | undefined;
+    previousPersistedAgentModelOverrides: Record<string, ModelSelectorValue> | undefined;
+    previousModelRolesOverride: Record<string, ModelSelectorValue> | undefined;
+    previousAgentModelOverridesOverride: Record<string, ModelSelectorValue> | undefined;
+    previousDefaultProfileOverride: string | undefined;
     previousDefaultProfile: string | undefined;
     previousPersistedDefaultProfile: string | undefined;
     previousActiveModelProfile: string | undefined;
+    previousDefaultChainState: ConfiguredModelChainState | undefined;
+    previousDefaultFallbackRuntimeState: DefaultFallbackRuntimeState | undefined;
+    /**
+     * Restores the session sticky canonical variant that was snapshotted before
+     * materialization cleared it. Internal closure capturing the registry,
+     * session, and exact pre-clear selector — avoids threading a registry
+     * through the restore options. Optional so callers that never materialized
+     * (or use a registry without sticky support) can still restore settings.
+     */
+    restoreSessionCanonicalVariant?: () => void;
 }
 export declare function materializeModelProfileForDeletion(options: PrepareModelProfileActivationOptions & {
-    settings: Pick<Settings, "clearOverride" | "flush" | "get" | "getGlobal" | "override" | "set" | "unset">;
+    settings: Pick<Settings, "clearOverride" | "flushOrThrow" | "get" | "getGlobal" | "override" | "set" | "unset">;
 }): Promise<MaterializeModelProfileForDeletionResult>;
 export declare function restoreMaterializedModelProfileForDeletion(options: {
-    settings: Pick<Settings, "flush" | "override" | "set">;
-    session: Pick<ModelProfileActivationSession, "setActiveModelProfile">;
+    settings: Pick<Settings, "clearOverride" | "flushOrThrow" | "override" | "set" | "unset">;
+    session: Pick<ModelProfileActivationSession, "setActiveModelProfile" | "setConfiguredModelChain" | "restoreDefaultFallbackRuntimeState">;
     snapshot: MaterializeModelProfileForDeletionResult;
 }): Promise<void>;
 export declare function activateModelProfile(options: PrepareModelProfileActivationOptions, applyOptions?: ApplyModelProfileActivationOptions): Promise<void>;

package/dist/types/config/model-profiles.d.ts

@@ -31,6 +31,16 @@ export declare function deriveModelProfileMappedProviders(definition: Pick<Model
  */
 export declare function aggregateModelProfileRequiredProviders(requiredProviders: readonly string[], _definition: Pick<ModelProfileDefinition, "modelMapping">): string[];
 export declare const BUILTIN_MODEL_PROFILES: readonly ModelProfileDefinition[];
+/**
+ * Providers that built-in model presets pin via qualified `<provider>/<model>`
+ * selectors. When `modelProfile.proxyProvider` is set, selectors for these
+ * providers are rewritten to `<proxy>/<model>` at activation time when their
+ * direct provider is unauthenticated, or unconditionally when
+ * `modelProfile.proxyMode` is `always`. Bare-alias (open-weights) profiles are
+ * not included: they already resolve through any authenticated provider,
+ * including a configured proxy.
+ */
+export declare const PROXY_ROUTABLE_PROVIDER_IDS: ReadonlySet<string>;
 export interface ModelProfilePresentation {
     displayName: string;
     providerGroup: string;

package/dist/types/config/model-registry.d.ts

@@ -12,7 +12,9 @@ export type { ProviderDiscoveryState, ProviderDiscoveryStatus } from "./model-di
 import { type CanonicalModelIndex, type CanonicalModelRecord, type CanonicalModelVariant, type ModelEquivalenceConfig } from "./model-equivalence";
 import { type ModelProfileDefinition } from "./model-profiles";
 import { GJC_MODEL_ASSIGNMENT_TARGET_IDS, type ModelProfileConfig } from "./models-config-schema";
+import { type EffectiveProviderAuth } from "./provider-selection-policy";
 import { type Settings } from "./settings";
+export type { EffectiveProviderAuth, ProviderSelectionPolicy } from "./provider-selection-policy";
 export type { CanonicalModelIndex, CanonicalModelRecord, CanonicalModelVariant, ModelEquivalenceConfig };
 export { isAuthenticated, kNoAuth };
 export type ModelRole = "default";
@@ -290,7 +292,7 @@ export declare const ModelsConfigFile: ConfigFile<{
     profiles?: Record<string, {
         required_providers: string[];
         display_name?: string | undefined;
-        model_mapping: Partial<Record<"architect" | "critic" | "default" | "executor" | "planner", string | string[]>>;
+        model_mapping: Partial<Record<"architect" | "critic" | "default" | "executor" | "image" | "planner", string | string[]>>;
     }> | undefined;
 }>;
 /** Provider override config (baseUrl, headers, apiKey, compat, transport) without custom models */
@@ -326,6 +328,8 @@ export interface CanonicalModelQueryOptions {
     candidates?: readonly Model<Api>[];
     /** Stable session identity used to keep a canonical variant sticky within a session. */
     sessionId?: string;
+    /** Credential-selection session used to classify effective provider auth. Defaults to sessionId. */
+    credentialSessionId?: string;
 }
 /**
  * Model registry - loads and manages models, resolves API keys via AuthStorage.
@@ -371,7 +375,69 @@ export declare class ModelRegistry {
     getConfiguredProviderIds(): readonly string[];
     getCanonicalModels(options?: CanonicalModelQueryOptions): CanonicalModelRecord[];
     getCanonicalVariants(canonicalId: string, options?: CanonicalModelQueryOptions): CanonicalModelVariant[];
+    /**
+     * Resolve an exact canonical id to a concrete model.
+     *
+     * Canonical ids remain exact lookup keys, but their provider variant uses the
+     * same provider-rank-first policy as preset aliases. Availability filtering
+     * remains opt-in through `availableOnly`; final-segment aliases never fall
+     * back implicitly — use {@link resolveModelByLookupAlias} for alias intent.
+     */
     resolveCanonicalModel(canonicalId: string, options?: CanonicalModelQueryOptions): Model<Api> | undefined;
+    /**
+     * Resolve a final-slash-segment alias to a concrete model, explicitly.
+     *
+     * The alias gathers every matching variant selector from the variant-level
+     * alias index — never sibling variants in the same canonical record that end
+     * in a different segment — then ranks all eligible variants together by the
+     * centralized provider policy (provider-rank-first axis order), with the
+     * canonical/exactness axis preserved relative to the alias lookup key
+     * (`model.id === alias` beats slash-prefixed ids before source/cost/catalog
+     * ties). Fails closed: availability/disabled filtering applies even to
+     * supplied candidate arrays, alias variants are intersected with the
+     * filtered candidate selectors before ranking, and zero eligible candidates
+     * returns an authoritative `undefined` without rewriting the variant's
+     * model/wire ids. Winners stay sticky per session.
+     */
+    resolveModelByLookupAlias(alias: string, options?: CanonicalModelQueryOptions): Model<Api> | undefined;
+    /**
+     * Whether a final-slash-segment alias is known in the current canonical
+     * index. Knownness is decided from the full multi-target alias index and is
+     * independent of availability: a known-but-unavailable alias still reports
+     * `true` while {@link resolveModelByLookupAlias} returns an authoritative
+     * `undefined`.
+     */
+    lookupAliasExists(alias: string): boolean;
+    /**
+     * Effective credential provenance for a provider, derived from existing
+     * AuthStorage/session credential surfaces (never from token shape).
+     * Session-specific provenance wins; API-key surfaces (runtime, config,
+     * custom/manual, stored api_key) beat OAuth presence; OAuth remains the
+     * provenance when it is the effective remaining stored credential;
+     * unknown/keyless providers fall back to non-OAuth.
+     */
+    getEffectiveProviderAuth(provider: string, sessionId?: string): EffectiveProviderAuth;
+    /**
+     * Forget a session's remembered canonical variant so the next resolution
+     * for that session re-ranks from scratch (explicit reselection
+     * integration). Returns whether an entry was actually removed.
+     */
+    clearCanonicalVariant(sessionId: string): boolean;
+    /**
+     * Snapshot a session's remembered sticky canonical variant selector — the exact
+     * concrete "provider/id" selector, captured verbatim rather than re-derived
+     * from any live model. Returns undefined when the session has no remembered
+     * variant. The caller owns restoring it later via
+     * {@link restoreSessionCanonicalVariant}.
+     */
+    getSessionCanonicalVariant(sessionId: string): string | undefined;
+    /**
+     * Restore a session's sticky canonical variant selector exactly, preserving the
+     * concrete provider/model previously remembered (never re-derived from a live
+     * model). The selector must still be present in the canonical index, otherwise
+     * the stale variant is left untouched and `false` is returned.
+     */
+    restoreSessionCanonicalVariant(sessionId: string, selector: string): boolean;
     getCanonicalId(model: Model<Api>): string | undefined;
     /**
      * Seed a child canonical scope from a concrete parent model without touching
@@ -398,6 +464,7 @@ export declare class ModelRegistry {
      * Check whether auth is configured for a provider.
      */
     hasConfiguredProviderAuth(provider: string): boolean;
+    isCredentiallessProvider(provider: string): boolean;
     getDiscoverableProviders(): string[];
     getProviderDiscoveryState(provider: string): ProviderDiscoveryState | undefined;
     /**

package/dist/types/config/model-resolver.d.ts

@@ -45,7 +45,7 @@ export interface ModelMatchPreferences {
     /** Providers to deprioritize when no recent usage is available. */
     deprioritizeProviders?: string[];
 }
-export type CanonicalModelRegistry = Partial<Pick<ModelRegistry, "resolveCanonicalModel" | "getCanonicalVariants" | "getCanonicalId" | "seedCanonicalVariant">>;
+export type CanonicalModelRegistry = Partial<Pick<ModelRegistry, "resolveCanonicalModel" | "getCanonicalVariants" | "getCanonicalId" | "seedCanonicalVariant" | "resolveModelByLookupAlias" | "lookupAliasExists" | "clearCanonicalVariant">>;
 export type ModelLookupRegistry = Pick<ModelRegistry, "getAvailable"> & Partial<CanonicalModelRegistry>;
 type CliModelRegistry = Pick<ModelRegistry, "getAll"> & Partial<CanonicalModelRegistry>;
 type InitialModelRegistry = Pick<ModelRegistry, "getAvailable">;
@@ -67,11 +67,15 @@ export interface ResolveSelectorOptions {
     modelRegistry?: CanonicalModelRegistry;
     preferences?: ModelMatchPreferences;
     sessionId?: string;
+    credentialSessionId?: string;
+    aliasIntent?: "preset-equivalent" | "reject";
 }
 /**
  * Resolve one selector through ordered exact, canonical, bare-id, provider-fuzzy,
- * substring/alias, and glob stages. Thinking is split only after a full selector
- * cannot resolve, which preserves OpenRouter route suffixes in concrete IDs.
+ * substring/alias, and glob stages. A preset-equivalent alias intent adds a
+ * final-slash-segment alias stage between strict-exact and substring/fuzzy.
+ * Thinking is split only after a full selector cannot resolve, which preserves
+ * OpenRouter route suffixes in concrete IDs.
  */
 export declare function resolveSelector(selector: string, candidates: Model<Api>[], options?: ResolveSelectorOptions): ParsedModelResult;
 /** @internal Exported for testing and legacy adapters. */
@@ -79,6 +83,8 @@ export declare function parseModelPattern(pattern: string, availableModels: Mode
     allowInvalidThinkingSelectorFallback?: boolean;
     modelRegistry?: CanonicalModelRegistry;
     sessionId?: string;
+    credentialSessionId?: string;
+    aliasIntent?: "preset-equivalent" | "reject";
 }): ParsedModelResult;
 /**
  * Expand a role alias like "pi/default" to the configured model string.
@@ -107,6 +113,8 @@ export declare function resolveModelRoleValue(roleValue: ModelSelectorValue | un
     matchPreferences?: ModelMatchPreferences;
     modelRegistry?: CanonicalModelRegistry;
     sessionId?: string;
+    credentialSessionId?: string;
+    aliasIntent?: "preset-equivalent" | "reject";
 }): ResolvedModelRoleValue;
 export declare function extractExplicitThinkingSelector(value: ModelSelectorValue | undefined, settings?: Settings): ThinkingLevel | undefined;
 /**
@@ -126,7 +134,7 @@ export declare function resolveModelFromSettings(options: {
 /**
  * Resolve a list of override patterns to the first matching model.
  */
-export declare function resolveModelOverride(modelPatterns: string[], modelRegistry: ModelLookupRegistry, settings?: Settings, sessionId?: string): {
+export declare function resolveModelOverride(modelPatterns: string[], modelRegistry: ModelLookupRegistry, settings?: Settings, sessionId?: string, aliasIntent?: "preset-equivalent" | "reject"): {
     model?: Model<Api>;
     thinkingLevel?: ThinkingLevel;
     explicitThinkingLevel: boolean;
@@ -140,6 +148,9 @@ export declare function resolveModelOverride(modelPatterns: string[], modelRegis
  */
 export interface ModelChainResolutionOptions {
     managedFallback?: boolean;
+    aliasIntent?: "preset-equivalent" | "reject";
+    canonicalSessionId?: string | null;
+    credentialSessionId?: string;
 }
 export declare function resolveModelChainWithAuth(modelPatterns: readonly string[], modelRegistry: ModelLookupRegistry & Pick<ModelRegistry, "getApiKey">, settings?: Settings, sessionId?: string, options?: ModelChainResolutionOptions): Promise<{
     model?: Model<Api>;

package/dist/types/config/models-config-schema.d.ts

@@ -140,7 +140,7 @@ export declare const OpenAICompatSchema: z.ZodObject<{
     }>>;
 }, z.core.$strip>;
 export declare const GJC_MODEL_EFFORT_IDS: readonly ["minimal", "low", "medium", "high", "xhigh", "max"];
-export declare const GJC_MODEL_ASSIGNMENT_TARGET_IDS: readonly ["default", "executor", "architect", "planner", "critic"];
+export declare const GJC_MODEL_ASSIGNMENT_TARGET_IDS: readonly ["default", "executor", "architect", "planner", "critic", "image"];
 export declare const EffortSchema: z.ZodEnum<{
     high: "high";
     low: "low";
@@ -158,15 +158,17 @@ export declare const ProfileRoleSchema: z.ZodEnum<{
     critic: "critic";
     default: "default";
     executor: "executor";
+    image: "image";
     planner: "planner";
 }>;
-export declare const ProfileModelSelectorPattern: string;
+export declare const ProfileModelSelectorPattern = "^(?:[^,/]+/[^,]*[^,:]|[^/,]*[^/,:])$";
 export declare const ProfileModelSelectorSchema: z.ZodString;
 export declare const ProfileModelMappingSchema: z.ZodRecord<z.ZodEnum<{
     architect: "architect";
     critic: "critic";
     default: "default";
     executor: "executor";
+    image: "image";
     planner: "planner";
 }> & z.core.$partial, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
 export declare const ProfileDefinitionSchema: z.ZodObject<{
@@ -177,6 +179,7 @@ export declare const ProfileDefinitionSchema: z.ZodObject<{
         critic: "critic";
         default: "default";
         executor: "executor";
+        image: "image";
         planner: "planner";
     }> & z.core.$partial, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
 }, z.core.$strict>;
@@ -188,6 +191,7 @@ export declare const ProfilesSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
         critic: "critic";
         default: "default";
         executor: "executor";
+        image: "image";
         planner: "planner";
     }> & z.core.$partial, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
 }, z.core.$strict>>;
@@ -823,6 +827,7 @@ export declare const ModelsConfigSchema: z.ZodObject<{
             critic: "critic";
             default: "default";
             executor: "executor";
+            image: "image";
             planner: "planner";
         }> & z.core.$partial, z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
     }, z.core.$strict>>>;

package/dist/types/config/provider-selection-policy.d.ts

@@ -0,0 +1,62 @@
+import type { Api, Model } from "@gajae-code/ai/core";
+/**
+ * Effective credential provenance for a provider, derived from credential
+ * surfaces (never from token shape).
+ *
+ * - `"oauth"`: requests are authenticated with an OAuth-provisioned credential,
+ *   including OAuth flows whose access tokens happen to look like API keys
+ *   (e.g. GitHub Copilot `ghu_` tokens).
+ * - `"key"`: a manual or configured API key (stored `api_key`, CLI `--api-key`
+ *   runtime override, `models.yml` `apiKey`/`apiKeyEnv`, or environment key).
+ * - `"keyless"`: no credential is required (local servers, `auth: none`).
+ * - `"unknown"`: no credential surface is present.
+ */
+export type EffectiveProviderAuth = "oauth" | "key" | "keyless" | "unknown";
+export interface ProviderSelectionPolicyInput {
+    /** Explicit `modelProviderOrder` from settings; trimmed and case-insensitive. */
+    explicitProviderOrder: readonly string[];
+    /** Effective auth provenance per lowercased provider id. */
+    effectiveAuth: ReadonlyMap<string, EffectiveProviderAuth>;
+    /** Registry catalog provider ids, lowercased, first-wins catalog order. */
+    catalogProviders: readonly string[];
+    /** Registry catalog model selectors ("provider/id"), lowercased, first-wins catalog order. */
+    catalogModels: readonly string[];
+}
+export interface ProviderSelectionPolicy {
+    /**
+     * Total-order rank for a provider: explicit providers `0..n-1`, omitted
+     * effective-OAuth providers `n`, omitted non-OAuth/unknown/keyless providers
+     * `n+1`. Unknown providers that were never cataloged still receive the
+     * non-OAuth rank unless their effective auth is OAuth.
+     */
+    rank(provider: string): number;
+    /** Lowercased explicit provider ids, in explicit order (deduped). */
+    explicitProviders(): readonly string[];
+    /** Whether a provider was listed explicitly. */
+    isExplicit(provider: string): boolean;
+    /** Ordered distinct provider ids: explicit order first, then catalog order. */
+    orderedProviders(): readonly string[];
+    /** Stable catalog index per lowercased provider id (registry-owned tie data). */
+    providerCatalogIndex(provider: string): number;
+    /** Stable catalog index per lowercased model selector (registry-owned tie data). */
+    modelCatalogIndex(selector: string): number;
+}
+/**
+ * Build a pure provider selection policy over explicit user order, effective
+ * credential provenance, and registry-owned catalog tie data. The policy never
+ * reads settings, auth storage, or the model catalog itself — callers pass the
+ * current values in so ranking stays deterministic and testable.
+ */
+export declare function createProviderSelectionPolicy(input: ProviderSelectionPolicyInput): ProviderSelectionPolicy;
+export interface ProviderSelectionCatalog {
+    /** Lowercased provider ids in first-wins registry catalog order. */
+    readonly catalogProviders: readonly string[];
+    /** Lowercased model selectors in first-wins registry catalog order. */
+    readonly catalogModels: readonly string[];
+}
+/**
+ * Derive stable provider/model tie data from the registry catalog order, not
+ * from a caller-supplied candidate array. First occurrence wins so reordering
+ * candidates never changes ranking.
+ */
+export declare function buildProviderSelectionCatalog(models: readonly Model<Api>[]): ProviderSelectionCatalog;