dsh-autotier 0.1.0

package/lib/types/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAElD,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAGxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,+BAA+B;AAC/B,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAA;IACjC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAA;CACjC;AAOD,oCAAoC;AACpC,wBAAgB,cAAc,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,YAAY,GAAG,cAAc,CA+ChF;AAED,mCAAmC;AACnC,wBAAgB,aAAa,CAAC,EAAE,OAAO,EAAE,EAAE,YAAY,GAAG,cAAc,CAwCvE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,GAAG,IAAI,CAG5E"}

package/lib/types/types.d.ts

@@ -0,0 +1,96 @@
+/**
+ * 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 declare const TIER_IDS: readonly ["strong", "cheap"];
+/** 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 declare const EFFORT_IDS: readonly ["off", "low", "high", "max"];
+/** 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 declare const ROUTING_MODES: readonly ["auto", "strong", "cheap", "delegated", "off"];
+/** One routing mode. */
+export type RoutingMode = (typeof ROUTING_MODES)[number];
+/** Intent classes the rule layer and the judge distinguish. */
+export declare const SCENARIOS: readonly ["coding", "review", "planning", "retrieval", "batch", "daily", "longText", "multimodal"];
+/** One intent class. */
+export type Scenario = (typeof SCENARIOS)[number];
+/** Cost/quality arbitration direction when the signals are ambiguous. */
+export declare const COST_MODES: readonly ["cost-first", "quality-first", "balanced"];
+/** 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;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;;;GAIG;AACH,eAAO,MAAM,QAAQ,8BAA+B,CAAA;AAEpD,iCAAiC;AACjC,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAA;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,UAAU,wCAAyC,CAAA;AAEhE,6CAA6C;AAC7C,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAA;AAElD;;;;GAIG;AACH,eAAO,MAAM,aAAa,0DAA2D,CAAA;AAErF,wBAAwB;AACxB,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;AAExD,+DAA+D;AAC/D,eAAO,MAAM,SAAS,oGASZ,CAAA;AAEV,wBAAwB;AACxB,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,SAAS,CAAC,CAAC,MAAM,CAAC,CAAA;AAEjD,yEAAyE;AACzE,eAAO,MAAM,UAAU,sDAAuD,CAAA;AAE9E,8CAA8C;AAC9C,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAA;AAElD;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAA;CAC3B;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,MAAM,GACN,OAAO,GACP,WAAW,GACX,WAAW,GACX,OAAO,GACP,YAAY,GACZ,UAAU,GACV,SAAS,CAAA;AAEb,gDAAgD;AAChD,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,4BAA4B;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAA;IACzB,yDAAyD;IACzD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,4BAA4B;IAC5B,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;IAC1B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;KAAE,CAAA;IACrG,sBAAsB;IACtB,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAA;IAChF,2BAA2B;IAC3B,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;QAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;QACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;QACtB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;QAC9B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;KAC5B,CAAA;CACF"}

package/package.json

@@ -0,0 +1,179 @@
+{
+  "name": "dsh-autotier",
+  "version": "0.1.0",
+  "description": "Automatic strong/cheap model-tier routing for DeepSeek Harness: intent-gated tier landing on the agent/request waterfall, plan-mode handoff (strong plans, cheap implements), deterministic high-risk guards on tools/pre-execute, failure escalation with TTL fallback, a /tier command, and tier status tools",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PerryLink/dsh-autotier.git"
+  },
+  "homepage": "https://github.com/PerryLink/dsh-autotier#readme",
+  "bugs": {
+    "url": "https://github.com/PerryLink/dsh-autotier/issues"
+  },
+  "author": "PerryLink",
+  "private": false,
+  "type": "module",
+  "main": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "CHANGELOG.md",
+    "THIRD_PARTY_NOTICES.md",
+    "SECURITY.md",
+    "AGENTS.md",
+    "README.md",
+    "README.zh.md",
+    "README.es.md",
+    "README.pt.md",
+    "README.hi.md",
+    "LICENSE",
+    "docs"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "compatibility": {
+      "dshReleases": {
+        "0.1.2-rc.1": "compatible"
+      }
+    }
+  },
+  "dshWorkshop": {
+    "schema": "omdsh-workshop-package/v1",
+    "type": "plugin",
+    "integration": {
+      "protocol": "harness-profile",
+      "artifact": "cordis.patch.yml"
+    },
+    "install": {
+      "mode": "transactional",
+      "adapter": "profile-bundle",
+      "failurePolicy": "generation-rollback",
+      "touchesCurrentBeforeActivation": false
+    },
+    "lifecycle": {
+      "activation": "restart-profile",
+      "dispose": "supported"
+    },
+    "permissions": [
+      "network:outbound",
+      "session:append"
+    ],
+    "compatibility": {
+      "dshVersions": [
+        "0.1.2-rc.1"
+      ]
+    },
+    "capability": {
+      "id": "autotier",
+      "kind": "command",
+      "invocation": "/tier, agent/request, tools/pre-execute",
+      "expected": "routes each turn to a strong or cheap model tier, blocks high-risk tool calls while the cheap tier is executing, and escalates to the strong tier after repeated failures"
+    },
+    "evidence": {
+      "install": null,
+      "failureIsolation": null,
+      "hotReload": null,
+      "remove": null
+    }
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "deepseek",
+    "cordis",
+    "router",
+    "model-tier",
+    "cost",
+    "auto"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "packageManager": "pnpm@11.7.0",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": ">=0.1.2-rc.1 <0.2.0",
+    "@deepseek-ai/dsh-commands": ">=0.1.2-rc.1 <0.2.0",
+    "@deepseek-ai/dsh-llm": ">=0.1.2-rc.1 <0.2.0",
+    "@deepseek-ai/dsh-plan-mode": ">=0.1.2-rc.1 <0.2.0",
+    "@deepseek-ai/dsh-session": ">=0.1.2-rc.1 <0.2.0",
+    "@deepseek-ai/dsh-session-projection": ">=0.1.2-rc.1 <0.2.0",
+    "@deepseek-ai/dsh-settings": ">=0.1.2-rc.1 <0.2.0",
+    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.2.0",
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-plan-mode": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-session-projection": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.7",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@deepseek-ai/dsh-agent": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-agent-default-model": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-agent-loop": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-agent-loop-testkit": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-atomic-write": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-commands": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-home-paths": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-llm": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-plan-mode": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-sandbox-policy": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-session": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-session-persistence": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-session-projection": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-settings": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-settings-file": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-tools": "0.1.2-rc.1",
+    "@deepseek-ai/dsh-util-values": "0.1.2-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.2",
+    "@types/node": "^22.19.0",
+    "@types/react": "18.3.31",
+    "@vitest/coverage-v8": "3.2.7",
+    "oxlint": "0.18.1",
+    "react": "18.3.1",
+    "react-dom": "18.3.1",
+    "vitest": "^3.2.0"
+  },
+  "scripts": {
+    "build": "node scripts/prepare.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.test.json --noEmit",
+    "typecheck:ci": "tsc -p tsconfig.ci.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "oxlint",
+    "check:readmes": "node scripts/check-readme-sync.mjs",
+    "prepare": "node scripts/prepare.mjs",
+    "verify:self-contained": "node scripts/verify-self-contained.mjs",
+    "verify:artifacts": "node scripts/verify-artifacts.mjs",
+    "prepublishOnly": "pnpm run typecheck && pnpm run typecheck:ci && pnpm test && pnpm run build && pnpm run verify:self-contained && pnpm run verify:artifacts"
+  },
+  "license": "Apache-2.0",
+  "funding": {
+    "type": "individual",
+    "url": "https://github.com/sponsors/PerryLink"
+  }
+}

package/src/command.ts

@@ -0,0 +1,73 @@
+/**
+ * The `/tier` command: a session-scoped escape hatch over the automatic
+ * routing. `auto` returns the session to routing, `strong`/`cheap` pin it,
+ * `off` disables routing entirely, and `status` prints the live decision state.
+ * @module dsh-autotier/command
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-commands'
+import type { CommandResult } from '@deepseek-ai/dsh-commands'
+import { escalationActive } from './policy.ts'
+import type { AutotierService } from './service.ts'
+import type { AgentStateStore } from './state.ts'
+import { ROUTING_MODES, type RoutingMode } from './types.ts'
+
+/** Format the tier table for `/tier status`. */
+function statusText(service: AutotierService, state: ReturnType<AgentStateStore['for']>): string {
+  const status = service.status()
+  const strong = status.tiers.strong
+  const cheap = status.tiers.cheap
+  const lines = [
+    `dsh-autotier — mode: ${state.override ?? status.mode}`,
+    `strong: ${strong.provider}/${strong.model}${strong.effort === undefined ? ' (follows session effort)' : ` @${strong.effort}`}`,
+    `cheap:  ${cheap.provider}/${cheap.model}${cheap.effort === undefined ? ' (follows session effort)' : ` @${cheap.effort}`}`,
+    `vision: ${status.tiers.vision.provider}/${status.tiers.vision.model}`,
+    `guard:  ${status.guard.enabled ? 'on' : 'off'} (${status.guard.tiers.join(', ')})`,
+  ]
+  const decision = state.decision
+  if (decision !== undefined) {
+    lines.push(`last intent: ${decision.scenario} (confidence ${decision.confidence.toFixed(2)}, fingerprint ${decision.fingerprint})`)
+    if (decision.reasons.length > 0) lines.push(`  because: ${decision.reasons.join('; ')}`)
+  }
+  if (state.appliedTier !== undefined) lines.push(`applied tier: ${state.appliedTier}`)
+  if (escalationActive(state, Date.now())) {
+    lines.push(`escalation: active for ${String(Math.ceil(((state.escalation?.until ?? 0) - Date.now()) / 1000))}s`)
+  }
+  if (state.fallback !== undefined) lines.push(`fallback: chain entry ${String(state.fallback.index + 1)}`)
+  if (state.planActive) lines.push('plan mode: active (strong tier)')
+  if (state.denials > 0) lines.push(`guard denials: ${String(state.denials)} (last rule ${state.lastDenial})`)
+  return lines.join('\n')
+}
+
+/**
+ * Register the `/tier` command on the plugin fiber.
+ * @param ctx - the plugin context (must have `commands`).
+ * @param service - the live service.
+ * @param states - the per-agent state store.
+ */
+export function registerTierCommand(ctx: Context, service: AutotierService, states: AgentStateStore): void {
+  ctx.commands.register({
+    name: 'tier',
+    description: 'Show or set this session\'s model tier (auto | strong | cheap | delegated | off | status).',
+    input: { hint: 'auto | strong | cheap | delegated | off | status' },
+    handler: ({ agent, rawInput }): CommandResult => {
+      const argument = rawInput.trim().toLowerCase()
+      const state = states.for(agent)
+      if (argument === '' || argument === 'status') {
+        return { kind: 'success', text: statusText(service, state) }
+      }
+      const mode = ROUTING_MODES.find(candidate => candidate === argument)
+      if (mode === undefined) {
+        return { kind: 'error', text: `unknown tier mode ${JSON.stringify(argument)}; use auto | strong | cheap | off | status` }
+      }
+      state.override = mode === 'auto' ? undefined : (mode as RoutingMode)
+      const status = service.status()
+      const effective = state.override ?? status.mode
+      return {
+        kind: 'success',
+        text: `dsh-autotier: session mode set to ${effective}\n${statusText(service, state)}`,
+      }
+    },
+  })
+}