dsh-autotier 0.1.0

package/src/schema.ts

@@ -0,0 +1,295 @@
+/**
+ * The raw (possibly partial) configuration surface of dsh-autotier: the
+ * Schemastery schema the Loader validates and the settings UI renders, plus the
+ * interfaces it resolves to. The judgement that turns a raw config into a
+ * resolved one lives in `config.ts`, so this module stays free of executable
+ * logic (a schema module must not mix function values into its declarations).
+ *
+ * @module dsh-autotier/schema
+ */
+
+import z from '@deepseek-ai/schemastery'
+import {
+  COST_MODES,
+  EFFORT_IDS,
+  ROUTING_MODES,
+  type CostMode,
+  type EffortId,
+  type RoutingMode,
+  type Scenario,
+} from './types.ts'
+
+/** One fallback landing in a tier's chain (provider/model only; effort follows the target tier). */
+export interface FallbackEntry {
+  provider?: string
+  model?: string
+}
+
+/** One tier's landing plus its fallback chain. */
+export interface TierConfig {
+  provider?: string
+  model?: string
+  effort?: EffortId
+  followSession?: boolean
+  fallback?: FallbackEntry[]
+}
+
+/** The image-capable landing used when a turn carries images. */
+export interface VisionConfig {
+  provider?: string
+  model?: string
+}
+
+/** One declarative intent rule: highest priority match wins. */
+export interface IntentRule {
+  id?: string
+  when?: { patterns?: string[]; tools?: string[]; cwd?: string }
+  tier?: 'cheap' | 'strong'
+  priority?: number
+}
+
+/** Low-confidence judge (a cheap model classifies intent only). */
+export interface JudgeConfig {
+  enabled?: boolean
+  /** Empty = pick the first catalog model whose id contains `flash`. */
+  model?: string
+  temperature?: number
+  maxTokens?: number
+  cooldownMs?: number
+  timeoutMs?: number
+  /** Consecutive judge failures after which this turn skips the judge. */
+  unavailableSkip?: number
+}
+
+/** Per-scenario switches; a disabled scenario never routes itself. */
+export type ScenarioToggles = { [K in Scenario]?: boolean }
+
+/** Intent classification and arbitration. */
+export interface IntentConfig {
+  /** Confidence at or above which the rule layer decides without the judge. */
+  ruleThreshold?: number
+  /** Attempt-first middle band; disabled until calibration lands. */
+  attemptBand?: { enabled?: boolean; tauLow?: number }
+  /** Application-side double threshold that stops tier flapping. */
+  hysteresis?: { toStrong?: number; toCheap?: number }
+  rules?: IntentRule[]
+  judge?: JudgeConfig
+  scenarios?: ScenarioToggles
+  costMode?: CostMode
+}
+
+/** High-risk guard switches. */
+export interface GuardConfig {
+  enabled?: boolean
+  /** Tiers whose execution the guard protects (only `cheap` is meaningful). */
+  tiers?: ('cheap')[]
+  /** Command/tool names or path prefixes that never trip the guard. */
+  whitelist?: string[]
+  /** Self-modification surfaces that force strong-tier review. */
+  protectedPaths?: string[]
+  /** Relationship with dsh-defend: `auto` audits coexistence, `none` stays silent. */
+  interopDefend?: 'auto' | 'none'
+}
+
+/** Failure escalation and TTL fallback. */
+export interface EscalationConfig {
+  threshold?: number
+  windowMs?: number
+  ttlMs?: number
+  fallbackTtlMs?: number
+  /** Count same-signature recurrences instead of every failure. */
+  signature?: boolean
+}
+
+/**
+ * Raw (possibly partial) plugin configuration. Every field is optional because
+ * the resolver supplies the defaults; {@link resolveConfig} turns it into the
+ * fully-resolved {@link ResolvedConfig}.
+ */
+export interface Config {
+  tiers?: { strong?: TierConfig; cheap?: TierConfig; vision?: VisionConfig }
+  intent?: IntentConfig
+  guard?: GuardConfig
+  escalation?: EscalationConfig
+  routingMode?: RoutingMode
+}
+
+
+/** The default strong tier: the catalog's quality-critical model at high effort. */
+export const DEFAULT_STRONG = {
+  provider: 'deepseek-official',
+  model: 'deepseek-v4-pro',
+  effort: 'high' as const,
+  followSession: false,
+}
+
+/** The default cheap tier: the catalog's routine/parallel model at low effort. */
+export const DEFAULT_CHEAP = {
+  provider: 'deepseek-official',
+  model: 'deepseek-v4-flash',
+  effort: 'low' as const,
+  followSession: true,
+}
+
+/** The default vision landing: the catalog's only image-capable model. */
+export const DEFAULT_VISION = {
+  provider: 'deepseek-official',
+  model: 'deepseek-v4-flash-vision-exp',
+}
+
+/**
+ * One tier schema per tier, so a partially-specified tier gets the same
+ * per-field defaults as the whole-object default (a shared schema would make
+ * `Config({ tiers: { cheap: { model } } })` disagree with `resolveConfig` on
+ * `followSession` and `effort`).
+ */
+const strongTier = z.object({
+  provider: z.string().default(DEFAULT_STRONG.provider),
+  model: z.string().default(DEFAULT_STRONG.model),
+  // Adapter-owned vocabulary: off | low | high | max. A value outside this set
+  // is a dead configuration (every request fails with UNSUPPORTED_REASONING_EFFORT).
+  effort: z.union([...EFFORT_IDS]).default(DEFAULT_STRONG.effort),
+  followSession: z.boolean().default(DEFAULT_STRONG.followSession),
+  fallback: z.array(z.object({
+    provider: z.string().default('deepseek-official'),
+    model: z.string().default(''),
+  })).default([]),
+})
+
+const cheapTier = z.object({
+  provider: z.string().default(DEFAULT_CHEAP.provider),
+  model: z.string().default(DEFAULT_CHEAP.model),
+  effort: z.union([...EFFORT_IDS]).default(DEFAULT_CHEAP.effort),
+  followSession: z.boolean().default(DEFAULT_CHEAP.followSession),
+  fallback: z.array(z.object({
+    provider: z.string().default('deepseek-official'),
+    model: z.string().default(''),
+  })).default([]),
+})
+
+/** Schemastery schema: the loader validates and fills defaults before `apply`. */
+export const Config: z<Config> = z.object({
+  tiers: z.object({
+    strong: strongTier.default({ ...DEFAULT_STRONG, fallback: [] }),
+    cheap: cheapTier.default({ ...DEFAULT_CHEAP, fallback: [] }),
+    vision: z.object({
+      provider: z.string().default('deepseek-official'),
+      model: z.string().default('deepseek-v4-flash-vision-exp'),
+    }).default({ ...DEFAULT_VISION }),
+  }).default({
+    strong: { ...DEFAULT_STRONG, fallback: [] },
+    cheap: { ...DEFAULT_CHEAP, fallback: [] },
+    vision: { ...DEFAULT_VISION },
+  }),
+  intent: z.object({
+    ruleThreshold: z.number().min(0.000001).max(1).default(0.7),
+    attemptBand: z.object({
+      enabled: z.boolean().default(false),
+      tauLow: z.number().min(0).max(1).default(0.45),
+    }).default({ enabled: false, tauLow: 0.45 }),
+    hysteresis: z.object({
+      toStrong: z.number().min(0).max(1).default(0.8),
+      toCheap: z.number().min(0).max(1).default(0.6),
+    }).default({ toStrong: 0.8, toCheap: 0.6 }),
+    rules: z.array(z.object({
+      id: z.string().default(''),
+      when: z.object({
+        patterns: z.array(z.string()).default([]),
+        tools: z.array(z.string()).default([]),
+        cwd: z.string().default(''),
+      }).default({ patterns: [], tools: [], cwd: '' }),
+      tier: z.union(['cheap', 'strong']).default('strong'),
+      priority: z.number().default(0),
+    })).default([]),
+    judge: z.object({
+      enabled: z.boolean().default(true),
+      model: z.string().default(''),
+      temperature: z.number().min(0).max(2).default(0),
+      maxTokens: z.number().step(1).min(1).max(4_096).default(16),
+      cooldownMs: z.number().min(0).max(3_600_000).default(30_000),
+      timeoutMs: z.number().min(1).max(120_000).default(2_000),
+      unavailableSkip: z.number().step(1).min(0).max(100).default(2),
+    }).default({
+      enabled: true,
+      model: '',
+      temperature: 0,
+      maxTokens: 16,
+      cooldownMs: 30_000,
+      timeoutMs: 2_000,
+      unavailableSkip: 2,
+    }),
+    scenarios: z.object({
+      coding: z.boolean().default(true),
+      review: z.boolean().default(true),
+      planning: z.boolean().default(true),
+      retrieval: z.boolean().default(true),
+      batch: z.boolean().default(true),
+      daily: z.boolean().default(true),
+      longText: z.boolean().default(true),
+      multimodal: z.boolean().default(true),
+    }).default({
+      coding: true,
+      review: true,
+      planning: true,
+      retrieval: true,
+      batch: true,
+      daily: true,
+      longText: true,
+      multimodal: true,
+    }),
+    costMode: z.union([...COST_MODES]).default('balanced'),
+  }).default({
+    ruleThreshold: 0.7,
+    attemptBand: { enabled: false, tauLow: 0.45 },
+    hysteresis: { toStrong: 0.8, toCheap: 0.6 },
+    rules: [],
+    judge: {
+      enabled: true,
+      model: '',
+      temperature: 0,
+      maxTokens: 16,
+      cooldownMs: 30_000,
+      timeoutMs: 2_000,
+      unavailableSkip: 2,
+    },
+    scenarios: {
+      coding: true,
+      review: true,
+      planning: true,
+      retrieval: true,
+      batch: true,
+      daily: true,
+      longText: true,
+      multimodal: true,
+    },
+    costMode: 'balanced',
+  }),
+  guard: z.object({
+    enabled: z.boolean().default(true),
+    tiers: z.array(z.union(['cheap'])).default(['cheap']),
+    whitelist: z.array(z.string()).default([]),
+    protectedPaths: z.array(z.string()).default(['.dsh', 'AGENTS.md', 'package.json', '.github/workflows']),
+    interopDefend: z.union(['auto', 'none']).default('auto'),
+  }).default({
+    enabled: true,
+    tiers: ['cheap'],
+    whitelist: [],
+    protectedPaths: ['.dsh', 'AGENTS.md', 'package.json', '.github/workflows'],
+    interopDefend: 'auto',
+  }),
+  escalation: z.object({
+    threshold: z.number().step(1).min(1).max(100).default(2),
+    windowMs: z.number().min(1).max(86_400_000).default(60_000),
+    ttlMs: z.number().min(1).max(86_400_000).default(180_000),
+    fallbackTtlMs: z.number().min(1).max(86_400_000).default(300_000),
+    signature: z.boolean().default(true),
+  }).default({
+    threshold: 2,
+    windowMs: 60_000,
+    ttlMs: 180_000,
+    fallbackTtlMs: 300_000,
+    signature: true,
+  }),
+  routingMode: z.union([...ROUTING_MODES]).default('auto'),
+})
+

package/src/service.ts

@@ -0,0 +1,131 @@
+/**
+ * `ctx.autotier`: the Service Provider for autotier's public read surface. The
+ * service owns the live resolved configuration, the compiled rule table and the
+ * fingerprint posteriors, and serves the status snapshot that `/tier status`,
+ * the `tier_status` tool and any third-party consumer read. Routing decisions
+ * themselves live in `policy.ts`/`routing.ts`; this class is the stable contract
+ * other plugins may depend on.
+ * @module dsh-autotier/service
+ */
+
+import { Service, type Context } from '@deepseek-ai/cordis'
+import type { SettingsScope } from '@deepseek-ai/dsh-settings'
+import { resolveConfig, type Config, type ResolvedConfig } from './config.ts'
+import { compileRules, PosteriorTable, type CompiledRule } from './intent.ts'
+import type { AutotierStatus, EffortId, TierRoute } from './types.ts'
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** The autotier routing service (absent when the plugin is not composed). */
+    autotier: AutotierService
+  }
+}
+
+/** Dependencies the service needs from the plugin's `apply`. */
+export interface AutotierServiceOptions {
+  /** The live settings scope; its value is re-resolved on every committed change. */
+  scope: SettingsScope<Config>
+  /** The configuration resolved at mount time (the composition base layer). */
+  config: ResolvedConfig
+}
+
+/** Project one resolved tier config onto the public route shape. */
+function routeOf(tier: { provider: string; model: string; effort: EffortId; followSession: boolean }): TierRoute {
+  if (tier.followSession) return { provider: tier.provider, model: tier.model }
+  return { provider: tier.provider, model: tier.model, effort: tier.effort }
+}
+
+/**
+ * Service Provider for `ctx.autotier`. Registration rides the owning fiber: the
+ * plugin unloading removes the service with every listener it owns.
+ */
+export class AutotierService extends Service {
+  private readonly scope: SettingsScope<Config>
+  private readonly posteriorTable = new PosteriorTable()
+  private resolved: ResolvedConfig
+  private compiled: CompiledRule[]
+
+  /**
+   * Register the service as `ctx.autotier` and start following the settings
+   * namespace.
+   * @param ctx - the owning plugin context.
+   * @param options - the live settings scope and the mount-time configuration.
+   */
+  constructor(ctx: Context, options: AutotierServiceOptions) {
+    super(ctx, 'autotier')
+    this.scope = options.scope
+    this.resolved = options.config
+    this.compiled = compileRules(options.config.intent.rules)
+    ctx.effect(() => this.scope.watch((next) => {
+      // A committed settings write replaces the whole resolved policy. A value
+      // the schema accepted but the cross-field judge rejects keeps the last
+      // good policy: settings.register's validate hook already refused the
+      // write, so reaching here with an invalid value is impossible.
+      this.resolved = resolveConfig(next)
+      this.compiled = compileRules(this.resolved.intent.rules)
+    }))
+  }
+
+  /** The live resolved configuration. */
+  config(): ResolvedConfig {
+    return this.resolved
+  }
+
+  /** The compiled declarative rule table, ordered by descending priority. */
+  rules(): readonly CompiledRule[] {
+    return this.compiled
+  }
+
+  /** The per-fingerprint win-rate posteriors. */
+  posteriors(): PosteriorTable {
+    return this.posteriorTable
+  }
+
+  /**
+   * The registered provider/model catalog, as the minimal serializable subset a
+   * configuration UI needs. Never hardcoded: it reads the live `ctx.llm`
+   * registry, so a model the adapter does not advertise cannot be selected.
+   * @returns one entry per registered provider with its models.
+   */
+  async catalog(): Promise<{ provider: string; models: { id: string; name: string; inputModalities: readonly string[] }[] }[]> {
+    const entries: { provider: string; models: { id: string; name: string; inputModalities: readonly string[] }[] }[] = []
+    for (const provider of this.ctx.llm.listProviders()) {
+      let models: readonly { id: string; name: string; inputModalities?: readonly string[] }[] = []
+      try {
+        models = await this.ctx.llm.listModels(provider.id)
+      } catch {
+        models = []
+      }
+      entries.push({
+        provider: provider.id,
+        models: models.map(model => ({
+          id: model.id,
+          name: model.name,
+          inputModalities: model.inputModalities ?? ['text'],
+        })),
+      })
+    }
+    return entries
+  }
+
+  /** Read-only status snapshot. */
+  status(): AutotierStatus {
+    const config = this.resolved
+    return {
+      mode: config.routingMode,
+      tiers: {
+        strong: routeOf(config.tiers.strong),
+        cheap: routeOf(config.tiers.cheap),
+        vision: { provider: config.tiers.vision.provider, model: config.tiers.vision.model },
+      },
+      guard: { enabled: config.guard.enabled, tiers: config.guard.tiers },
+      escalation: {
+        threshold: config.escalation.threshold,
+        windowMs: config.escalation.windowMs,
+        ttlMs: config.escalation.ttlMs,
+        fallbackTtlMs: config.escalation.fallbackTtlMs,
+        signature: config.escalation.signature,
+      },
+    }
+  }
+}

package/src/state.ts

@@ -0,0 +1,134 @@
+/**
+ * Per-agent routing state and the replayable tier projection.
+ *
+ * Two different kinds of state live here, on purpose:
+ *
+ * - **Runtime state** (escalation counters, fallback position, judge cooldown,
+ *   the per-input decision cache, the hysteresis anchor) is mutable and NOT
+ *   derivable from the session log, so it lives in a `WeakMap<Agent, RouteState>`.
+ *   `ctx.sessionProjections` is a read-only fold registry — it exposes
+ *   `register`/`stateOf`/`snapshot` and has no setter — so runtime state cannot
+ *   live there; the earlier design note that said otherwise is corrected here.
+ * - **Derived state** (which route the last request actually used, and whether
+ *   plan mode is active) IS a pure fold over `request/header` and `plan/mode`,
+ *   so it is registered as a host+wire projection key. That makes the effective
+ *   tier replayable from the log and visible to clients.
+ *
+ * @module dsh-autotier/state
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+// Type-only import: pulls the `plan/mode` SessionEventMap augmentation the host
+// plan-mode package declares. Erased at runtime, so the peer stays optional.
+import type {} from '@deepseek-ai/dsh-plan-mode'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { createRouteState, type RouteState } from './policy.ts'
+
+/** The projection key autotier owns. */
+export const TIER_PROJECTION_KEY = 'autotier'
+
+/** Host fold state for the tier projection (plain JSON by contract). */
+export interface TierProjectionState {
+  provider: string
+  model: string
+  /** Empty string = the route carries no explicit effort. */
+  effort: string
+  plan: boolean
+}
+
+/**
+ * The subset of `ctx.sessionProjections` this plugin uses. Typed structurally
+ * on purpose: the service is an optional peer, so the plugin must not depend on
+ * its declaration-merged key table at type level (a consumer without the peer
+ * would fail to type-check). The runtime contract is the same.
+ */
+interface ProjectionRegistryLike {
+  register(definition: {
+    key: string
+    stateVersion: number
+    stateSchema: { parse(value: unknown): unknown }
+    init: (header: unknown, inheritedEventCount: number) => TierProjectionState
+    apply: (state: TierProjectionState, event: SessionEvent) => TierProjectionState
+    wire: {
+      viewSchema: { parse(value: unknown): unknown }
+      view(state: TierProjectionState): TierProjectionState
+    }
+  }): () => void
+  stateOf(session: Session, key: string): TierProjectionState | undefined
+}
+
+/** Minimal zod-compatible schemas for the projection state and wire view. */
+const projectionSchema = {
+  parse(value: unknown): TierProjectionState {
+    const record = (value ?? {}) as Record<string, unknown>
+    return {
+      provider: typeof record.provider === 'string' ? record.provider : '',
+      model: typeof record.model === 'string' ? record.model : '',
+      effort: typeof record.effort === 'string' ? record.effort : '',
+      plan: record.plan === true,
+    }
+  },
+}
+
+/**
+ * Register the tier projection when the registry is composed.
+ * @param ctx - the plugin context; the registration rides its fiber.
+ * @returns the registration disposer, or undefined when the registry is absent.
+ */
+export function registerTierProjection(ctx: Context): (() => void) | undefined {
+  const registry = ctx.get('sessionProjections') as unknown as ProjectionRegistryLike | undefined
+  if (registry === undefined) {
+    ctx.logger.warn('dsh-autotier: sessionProjections is absent; the replayable tier projection is disabled')
+    return undefined
+  }
+  return registry.register({
+    key: TIER_PROJECTION_KEY,
+    stateVersion: 1,
+    stateSchema: projectionSchema,
+    init: () => ({ provider: '', model: '', effort: '', plan: false }),
+    apply: (state, event) => {
+      if (event.type === 'plan/mode') {
+        const plan = (event.data as { active?: unknown }).active === true
+        return plan === state.plan ? state : { ...state, plan }
+      }
+      if (event.type !== 'request/header') return state
+      const config = (event.data as { header?: { config?: { provider?: unknown; model?: unknown; reasoningEffort?: unknown } } })
+        .header?.config
+      if (config === undefined) return state
+      const next: TierProjectionState = {
+        provider: typeof config.provider === 'string' ? config.provider : '',
+        model: typeof config.model === 'string' ? config.model : '',
+        effort: typeof config.reasoningEffort === 'string' ? config.reasoningEffort : '',
+        plan: state.plan,
+      }
+      const same = next.provider === state.provider && next.model === state.model
+        && next.effort === state.effort && next.plan === state.plan
+      return same ? state : next
+    },
+    wire: {
+      viewSchema: projectionSchema,
+      view: state => state,
+    },
+  })
+}
+
+/** The per-agent runtime state store. */
+export class AgentStateStore {
+  private readonly states = new WeakMap<Agent, RouteState>()
+
+  /** The state for one agent, created on first use. */
+  for(agent: Agent): RouteState {
+    let state = this.states.get(agent)
+    if (state === undefined) {
+      state = createRouteState()
+      this.states.set(agent, state)
+    }
+    return state
+  }
+
+  /** Whether one agent already has state (diagnostics). */
+  has(agent: Agent): boolean {
+    return this.states.has(agent)
+  }
+}