dsh-autotier 0.1.0

package/src/tiers.ts

@@ -0,0 +1,212 @@
+/**
+ * Pure tier arithmetic: the adapter-owned effort ladder, tier-route
+ * application, the effort-first escalation ladder, and the fallback-chain
+ * classifier/advance helpers.
+ *
+ * The fallback vocabulary is ported from `dsh-tier-router`'s `lib/pure.js`
+ * (MIT; see `THIRD_PARTY_NOTICES.md`), with two corrections: the effort ladder
+ * is DeepSeek's `off | low | high | max` (upstream's `medium` does not exist and
+ * would fail every request with `UNSUPPORTED_REASONING_EFFORT`), and the
+ * classification is split into permanent/transient so the request-error handler
+ * can honour the division of labour with `dsh-llm-retry` (permanent codes switch
+ * the chain immediately; transient codes wait for retry exhaustion).
+ *
+ * @module dsh-autotier/tiers
+ */
+
+import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
+import type { EffortId, TierId, TierRoute } from './types.ts'
+
+/** The adapter-owned effort ladder, cheapest to strongest. */
+export const EFFORT_LADDER = ['off', 'low', 'high', 'max'] as const satisfies readonly EffortId[]
+
+/** Position of one effort on the ladder (0..3); unknown ids rank lowest. */
+export function effortRank(effort: string): number {
+  const index = (EFFORT_LADDER as readonly string[]).indexOf(effort)
+  return index === -1 ? 0 : index
+}
+
+/**
+ * The next effort step above `current`, never above `ceiling`.
+ * @param current - the effort currently in force.
+ * @param ceiling - the strongest effort to consider (default `max`).
+ * @returns the next effort id, or null when already at or above the ceiling.
+ */
+export function nextEffortStep(current: EffortId, ceiling: EffortId = 'max'): EffortId | null {
+  const start = effortRank(current)
+  const stop = effortRank(ceiling)
+  if (start >= stop) return null
+  return EFFORT_LADDER[start + 1] ?? null
+}
+
+/** Whether two routes land on the same provider/model/effort triple. */
+export function routeEquals(a: TierRoute, b: TierRoute): boolean {
+  return a.provider === b.provider && a.model === b.model && a.effort === b.effort
+}
+
+/** One adapter-owned effort id as the LLM call config expects it (branded at the seam). */
+function brandedEffort(effort: string): NonNullable<LlmCallConfig['reasoningEffort']> {
+  // The adapter's `ReasoningEffortId` is a branded string; the brand is opaque
+  // by design, and our vocabulary is validated against it before it gets here.
+  return effort as unknown as NonNullable<LlmCallConfig['reasoningEffort']>
+}
+
+/**
+ * Apply one tier route to a request configuration. The sampling scalars the
+ * session already chose (`temperature`, `maxTokens`, `stop`) are preserved
+ * exactly; the provider/model/effort triple is replaced. Returns the input
+ * object unchanged when the route already matches, so the caller can skip a
+ * logged header change.
+ *
+ * @param base - the configuration the loop proposed.
+ * @param target - the tier landing to apply.
+ * @returns the replacement configuration (or `base` when identical).
+ */
+export function resolveRoute(base: LlmCallConfig, target: TierRoute): LlmCallConfig {
+  const sameLanding = base.provider === target.provider && base.model === target.model
+  if (sameLanding && (target.effort === undefined || base.reasoningEffort === target.effort)) return base
+  const next: LlmCallConfig = { provider: target.provider, model: target.model }
+  // An absent target effort means "follow the session": carry the effort the
+  // request already carries instead of dropping it (a dropped effort silently
+  // falls back to the adapter default, which is the strongest one).
+  const effort = target.effort ?? base.reasoningEffort
+  if (effort !== undefined) next.reasoningEffort = brandedEffort(effort)
+  if (base.temperature !== undefined) next.temperature = base.temperature
+  if (base.maxTokens !== undefined) next.maxTokens = base.maxTokens
+  if (base.stop !== undefined) next.stop = base.stop
+  return next
+}
+
+/** One rung of the effort-first escalation ladder. */
+export interface EscalationRung {
+  /** The landing this rung applies. */
+  readonly route: TierRoute
+  /** The tier the rung belongs to (an effort rung on the cheap model is still cheap). */
+  readonly tier: TierId
+  /** Why this rung exists, for logs and `/tier status`. */
+  readonly note: string
+}
+
+/**
+ * Build the effort-first escalation ladder: raise the current model's effort
+ * one step at a time (the KV prefix survives, and the official model-selection
+ * notice is not emitted for an effort-only change) before paying for a model
+ * switch. When both tiers share one model the ladder collapses to a single
+ * effort-only rung.
+ *
+ * @param base - the configuration the loop proposed for the failing step.
+ * @param cheap - the cheap tier landing.
+ * @param strong - the strong tier landing.
+ * @returns the ordered rungs; empty when escalation cannot change anything.
+ */
+export function escalationLadder(base: LlmCallConfig, cheap: TierRoute, strong: TierRoute): EscalationRung[] {
+  const rungs: EscalationRung[] = []
+  const baseEffort = (base.reasoningEffort ?? cheap.effort ?? 'low') as EffortId
+  const onCheapModel = base.provider === cheap.provider && base.model === cheap.model
+  const sharedModel = strong.provider === cheap.provider && strong.model === cheap.model
+  if (sharedModel) {
+    if (strong.effort !== undefined && strong.effort !== baseEffort) {
+      rungs.push({
+        route: { provider: strong.provider, model: strong.model, effort: strong.effort },
+        tier: 'strong',
+        note: `effort-only escalation on the shared model (${baseEffort} -> ${strong.effort})`,
+      })
+    }
+    return rungs
+  }
+  if (onCheapModel) {
+    let step = nextEffortStep(baseEffort)
+    while (step !== null) {
+      rungs.push({
+        route: { provider: cheap.provider, model: cheap.model, effort: step },
+        tier: 'cheap',
+        note: `cheap-tier effort rung ${step}`,
+      })
+      step = nextEffortStep(step)
+    }
+  }
+  rungs.push({
+    route: strong.effort === undefined
+      ? { provider: strong.provider, model: strong.model }
+      : { provider: strong.provider, model: strong.model, effort: strong.effort },
+    tier: 'strong',
+    note: 'switch to the strong model',
+  })
+  return rungs
+}
+
+/** Failure codes that mean the route itself is unusable: switch the chain now. */
+export const FALLBACK_PERMANENT_CODES = [
+  'UNKNOWN_MODEL',
+  'MISSING_CREDENTIAL',
+  'INVALID_CREDENTIAL',
+  'QUOTA',
+] as const
+
+/** Failure codes owned by `dsh-llm-retry` first: switch the chain only after retries are exhausted. */
+export const FALLBACK_TRANSIENT_CODES = ['RATE_LIMIT', 'SERVER', 'TIMEOUT', 'TRANSPORT'] as const
+
+/** Failure codes that must never switch the model. */
+export const FALLBACK_IGNORE_CODES = [
+  'CONTEXT_WINDOW_EXCEEDED',
+  'UNSUPPORTED_REASONING_EFFORT',
+  'ABORTED',
+  'EMPTY_RESPONSE',
+] as const
+
+/** How one failure relates to the fallback chain. */
+export type FallbackClass = 'permanent' | 'transient' | 'ignore' | 'unknown'
+
+/**
+ * Classify one failed model request for the fallback machinery.
+ * @param failure - the normalized failure facts (`code` and optional `status`).
+ * @returns the chain verdict.
+ */
+export function classifyFallback(failure: { code?: unknown; status?: unknown } | undefined): FallbackClass {
+  if (failure === undefined || failure === null || typeof failure !== 'object') return 'unknown'
+  const code = typeof failure.code === 'string' ? failure.code : undefined
+  if (code !== undefined) {
+    if ((FALLBACK_PERMANENT_CODES as readonly string[]).includes(code)) return 'permanent'
+    if ((FALLBACK_TRANSIENT_CODES as readonly string[]).includes(code)) return 'transient'
+    if ((FALLBACK_IGNORE_CODES as readonly string[]).includes(code)) return 'ignore'
+  }
+  if (typeof failure.status === 'number' && failure.status >= 500) return 'transient'
+  return 'unknown'
+}
+
+/** One agent's position in one tier's fallback chain. */
+export interface FallbackRecord {
+  /** The tier whose chain this record belongs to. */
+  tier: TierId
+  /** Index in that tier's chain; -1 means the tier's own landing. */
+  index: number
+  /** Epoch millis until which the record stays in force. */
+  until: number
+}
+
+/** Whether a fallback record is currently pinning the agent to a chain entry. */
+export function fallbackActive(record: FallbackRecord | undefined, now: number): boolean {
+  return record !== undefined && record.index >= 0 && record.until > now
+}
+
+/**
+ * Advance a fallback record one step down one tier's chain.
+ * @param record - the current record (absent or from another tier = start of this chain).
+ * @param tier - the tier whose chain is being walked.
+ * @param chainLength - the number of configured fallback entries.
+ * @param now - current epoch millis.
+ * @param ttlMs - how long the new entry stays in force.
+ * @returns the next record, or null when the chain is exhausted.
+ */
+export function advanceFallback(
+  record: FallbackRecord | undefined,
+  tier: TierId,
+  chainLength: number,
+  now: number,
+  ttlMs: number,
+): FallbackRecord | null {
+  const index = record !== undefined && record.tier === tier ? record.index : -1
+  const next = index + 1
+  if (next >= chainLength) return null
+  return { tier, index: next, until: now + (Number.isFinite(ttlMs) && ttlMs > 0 ? ttlMs : 300_000) }
+}

package/src/tools.ts

@@ -0,0 +1,128 @@
+/**
+ * The two read-only tools: `tier_status` reports the live routing state, and
+ * `tier_route` dry-runs the classifier on one intent string without sending a
+ * model request.
+ * @module dsh-autotier/tools
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { defineTool, type ToolDefinition } from '@deepseek-ai/dsh-tools'
+import { classifyIntent } from './intent.ts'
+import { escalationActive } from './policy.ts'
+import type { AutotierService } from './service.ts'
+import type { AgentStateStore } from './state.ts'
+
+/** Services the tools read. */
+export interface ToolServices {
+  readonly service: AutotierService
+  readonly states: AgentStateStore
+}
+
+/** Render one canonical value as a single text block. */
+function textBlock(value: unknown): { type: 'text'; text: string }[] {
+  return [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }]
+}
+
+/** Build the `tier_status` tool. */
+export function tierStatusTool({ service, states }: ToolServices): ToolDefinition {
+  return defineTool({
+    name: 'tier_status',
+    description:
+      'Report the live dsh-autotier routing state: the configured tier landings, the effective mode for this session, the last intent classification, and whether a failure escalation or fallback is in force. Read-only.',
+    parameters: {},
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          mode: { type: 'string' },
+          strong: { type: 'string' },
+          cheap: { type: 'string' },
+          vision: { type: 'string' },
+          guardEnabled: { type: 'boolean' },
+          appliedTier: { type: 'string' },
+          lastScenario: { type: 'string' },
+          lastConfidence: { type: 'number' },
+          escalated: { type: 'boolean' },
+          planActive: { type: 'boolean' },
+          guardDenials: { type: 'integer' },
+          lastDenialRule: { type: 'string' },
+        },
+      },
+      render: (_args, value) => textBlock(value),
+    },
+    execute: async (_args, exec) => {
+      const agent = exec.agent as Agent | undefined
+      const state = agent === undefined ? undefined : states.for(agent)
+      const status = service.status()
+      return {
+        mode: state?.override ?? status.mode,
+        strong: `${status.tiers.strong.provider}/${status.tiers.strong.model}${status.tiers.strong.effort === undefined ? '' : `@${status.tiers.strong.effort}`}`,
+        cheap: `${status.tiers.cheap.provider}/${status.tiers.cheap.model}${status.tiers.cheap.effort === undefined ? '' : `@${status.tiers.cheap.effort}`}`,
+        vision: `${status.tiers.vision.provider}/${status.tiers.vision.model}`,
+        guardEnabled: status.guard.enabled,
+        appliedTier: state?.appliedTier ?? '',
+        lastScenario: state?.decision?.scenario ?? '',
+        lastConfidence: state?.decision?.confidence ?? 0,
+        escalated: state === undefined ? false : escalationActive(state, Date.now()),
+        planActive: state?.planActive ?? false,
+        guardDenials: state?.denials ?? 0,
+        lastDenialRule: state?.lastDenial ?? '',
+      }
+    },
+  })
+}
+
+/** Build the `tier_route` tool. */
+export function tierRouteTool({ service }: ToolServices): ToolDefinition {
+  return defineTool({
+    name: 'tier_route',
+    description:
+      'Dry-run the intent classifier on one instruction and report which tier it would use, without sending a model request. Read-only.',
+    parameters: {
+      text: { type: 'string', description: 'The instruction to classify.', required: true as const },
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          tier: { type: 'string' },
+          scenario: { type: 'string' },
+          confidence: { type: 'number' },
+          fingerprint: { type: 'string' },
+          reason: { type: 'string' },
+        },
+      },
+      render: (_args, value) => textBlock(value),
+    },
+    execute: async (args) => {
+      const config = service.config()
+      const result = classifyIntent({
+        text: args.text,
+        toolNames: [],
+        hasImage: false,
+        messageCount: 0,
+        cwd: '',
+      }, { rules: service.rules(), scenarios: config.intent.scenarios })
+      return {
+        tier: result.tier,
+        scenario: result.scenario,
+        confidence: result.confidence,
+        fingerprint: result.fingerprint,
+        reason: result.reasons.join('; '),
+      }
+    },
+  })
+}
+
+/**
+ * Register both tools on the plugin fiber.
+ * @param ctx - the plugin context (must have `tools`).
+ * @param services - the service and the state store.
+ */
+export function registerTierTools(ctx: Context, services: ToolServices): void {
+  ctx.tools.register(tierStatusTool(services))
+  ctx.tools.register(tierRouteTool(services))
+}

package/src/types.ts

@@ -0,0 +1,120 @@
+/**
+ * Shared vocabulary for dsh-autotier: the tier ids, the adapter-owned reasoning
+ * effort ids, the routing modes, and the public route/status shapes every
+ * module and the `ctx.autotier` service speak.
+ * @module dsh-autotier/types
+ */
+
+/**
+ * Service Definition (contract layer): the two cost tiers this plugin routes
+ * between. `strong` plans complex intent and reviews high-risk work; `cheap`
+ * implements it. The ids are stable wire/settings vocabulary.
+ */
+export const TIER_IDS = ['strong', 'cheap'] as const
+
+/** One of the two cost tiers. */
+export type TierId = (typeof TIER_IDS)[number]
+
+/**
+ * Reasoning-effort ids owned by the provider adapter. The DeepSeek adapter
+ * accepts exactly these four (`packages/llm/llm-deepseek/src/index.ts:133`);
+ * `medium` does not exist, and an unsupported value fails every request with
+ * `UNSUPPORTED_REASONING_EFFORT` instead of degrading.
+ */
+export const EFFORT_IDS = ['off', 'low', 'high', 'max'] as const
+
+/** One adapter-owned reasoning-effort id. */
+export type EffortId = (typeof EFFORT_IDS)[number]
+
+/**
+ * Routing modes. `auto` is the fully automatic path; the rest are explicit
+ * user overrides (`/tier strong|cheap|off`). `delegated` means the session
+ * carries an explicit model selection that autotier must not fight.
+ */
+export const ROUTING_MODES = ['auto', 'strong', 'cheap', 'delegated', 'off'] as const
+
+/** One routing mode. */
+export type RoutingMode = (typeof ROUTING_MODES)[number]
+
+/** Intent classes the rule layer and the judge distinguish. */
+export const SCENARIOS = [
+  'coding',
+  'review',
+  'planning',
+  'retrieval',
+  'batch',
+  'daily',
+  'longText',
+  'multimodal',
+] as const
+
+/** One intent class. */
+export type Scenario = (typeof SCENARIOS)[number]
+
+/** Cost/quality arbitration direction when the signals are ambiguous. */
+export const COST_MODES = ['cost-first', 'quality-first', 'balanced'] as const
+
+/** One cost/quality arbitration direction. */
+export type CostMode = (typeof COST_MODES)[number]
+
+/**
+ * One concrete tier landing: the provider/model pair plus the reasoning effort
+ * the request should carry. `effort` is omitted only when the tier inherits
+ * the session's own effort (followSession).
+ */
+export interface TierRoute {
+  readonly provider: string
+  readonly model: string
+  readonly effort?: EffortId
+}
+
+/**
+ * Why a tier was chosen. `source` is the arbitration layer that won, so an
+ * operator can tell a rule hit from a judge call from an escalation.
+ */
+export type RouteSource =
+  | 'manual'
+  | 'rule'
+  | 'judge'
+  | 'posterior'
+  | 'plan-mode'
+  | 'guard'
+  | 'escalation'
+  | 'fallback'
+  | 'default'
+
+/** One routing decision with its provenance. */
+export interface RouteDecision {
+  /** The tier the request should use. */
+  readonly tier: TierId
+  /** The concrete landing. */
+  readonly route: TierRoute
+  /** The arbitration layer that produced this decision. */
+  readonly source: RouteSource
+  /** 0..1 confidence of the intent classification (1 for explicit overrides). */
+  readonly confidence: number
+  /** Short human-readable reason, safe for logs and `/tier status`. */
+  readonly reason: string
+}
+
+/**
+ * Service Definition (contract layer): the read-only status snapshot served by
+ * `ctx.autotier.status()` and rendered by `/tier status` and the `tier_status`
+ * tool. Third-party plugins may depend on this shape.
+ */
+export interface AutotierStatus {
+  /** Current routing mode. */
+  readonly mode: RoutingMode
+  /** Configured landing per tier (effort omitted when inherited). */
+  readonly tiers: { readonly strong: TierRoute; readonly cheap: TierRoute; readonly vision: TierRoute }
+  /** Guard switches. */
+  readonly guard: { readonly enabled: boolean; readonly tiers: readonly TierId[] }
+  /** Escalation switches. */
+  readonly escalation: {
+    readonly threshold: number
+    readonly windowMs: number
+    readonly ttlMs: number
+    readonly fallbackTtlMs: number
+    readonly signature: boolean
+  }
+}