dsh-autotier 0.1.0

package/cordis.patch.yml

@@ -0,0 +1,125 @@
+# dsh-autotier: automatic model-tier routing for DeepSeek Harness.
+#
+# One user instruction enters, one tier decision comes out. Complex intent is
+# planned on the strong tier and implemented on the cheap tier; simple intent is
+# designed and implemented on the cheap tier directly. High-risk tool calls are
+# denied while the cheap tier executes, and repeated failures escalate to the
+# strong tier with a TTL fallback. Everything below is a Schemastery-validated
+# config field; an invalid value fails loudly at load time.
+- insert:
+    - id: autotier
+      name: dsh-autotier
+      # `sessions` is plural: the host service is `ctx.sessions`, and a
+      # non-existent name here would leave this plugin PENDING forever.
+      inject: [settings, llm, tools, commands, sessions]
+      config:
+        # ---- tiers ----------------------------------------------------------
+        tiers:
+          # The planning/review tier. `effort` is the adapter-owned vocabulary
+          # off | low | high | max; `medium` does not exist and would fail every
+          # request with UNSUPPORTED_REASONING_EFFORT.
+          strong:
+            provider: deepseek-official
+            model: deepseek-v4-pro
+            effort: high
+            # false = this tier's effort overrides the session's own.
+            followSession: false
+            # Ordered fallback landings (provider/model) used when the tier is
+            # unavailable. The chain is deduplicated and must not name the tier
+            # itself; validation refuses a self-referential chain at load time.
+            fallback: []
+          # The implementation tier.
+          cheap:
+            provider: deepseek-official
+            model: deepseek-v4-flash
+            effort: low
+            # true = inherit the session's effort, so an explicit user choice
+            # still wins inside the cheap tier.
+            followSession: true
+            fallback: []
+          # Image-capable landing: a turn carrying images is routed here,
+          # because a text-only model silently substitutes image placeholders.
+          vision:
+            provider: deepseek-official
+            model: deepseek-v4-flash-vision-exp
+        # ---- intent classification -----------------------------------------
+        intent:
+          # Confidence at or above which the deterministic rule layer decides
+          # without calling the judge model.
+          ruleThreshold: 0.7
+          # Attempt-first middle band: scores in [tauLow, ruleThreshold) start on
+          # the cheap tier and escalate on a signal. Disabled until the
+          # calibration corpus lands.
+          attemptBand:
+            enabled: false
+            tauLow: 0.45
+          # Application-side double threshold that stops tier flapping between
+          # turns; the decision threshold above is unchanged.
+          hysteresis:
+            toStrong: 0.8
+            toCheap: 0.6
+          # Declarative rule table. Rules are evaluated by descending priority;
+          # the first match wins, and a guard denial always outranks a rule.
+          # `when.patterns` are regular expressions matched against the user
+          # text, `when.tools` against the tool name, `when.cwd` against the
+          # workspace path (empty = no constraint). `tier` is cheap | strong.
+          # Example entry:
+          #   - id: plan-first
+          #     when:
+          #       patterns: ['^plan\\b', 'architecture']
+          #       tools: []
+          #       cwd: ''
+          #     tier: strong
+          #     priority: 10
+          rules: []
+          # The low-confidence judge: a cheap model classifies intent only.
+          judge:
+            enabled: true
+            # Empty = pick the first catalog model whose id contains "flash".
+            model: ''
+            temperature: 0
+            maxTokens: 16
+            cooldownMs: 30000
+            timeoutMs: 2000
+            # Consecutive judge failures after which the current turn skips the
+            # judge instead of paying its timeout on every request.
+            unavailableSkip: 2
+          # Per-scenario switches: coding, review, planning, retrieval, batch,
+          # daily, longText, multimodal.
+          scenarios:
+            coding: true
+            review: true
+            planning: true
+            retrieval: true
+            batch: true
+            daily: true
+            longText: true
+            multimodal: true
+          # Ambiguity arbitration: cost-first | quality-first | balanced.
+          costMode: balanced
+        # ---- high-risk guard ------------------------------------------------
+        guard:
+          enabled: true
+          # Tiers whose execution the guard protects (cheap only).
+          tiers: [cheap]
+          # Commands, tools or path prefixes that never trip the guard.
+          whitelist: []
+          # Self-modification surfaces that force strong-tier review.
+          protectedPaths: ['.dsh', 'AGENTS.md', 'package.json', '.github/workflows']
+          # Relationship with dsh-defend: auto audits coexistence, none stays
+          # silent. The guard never weakens dsh-defend.
+          interopDefend: auto
+        # ---- failure escalation ---------------------------------------------
+        escalation:
+          # Failures within windowMs that reach this count escalate the tier.
+          threshold: 2
+          windowMs: 60000
+          # How long an escalation stays in effect before falling back.
+          ttlMs: 180000
+          # TTL used after a fallback landing was taken.
+          fallbackTtlMs: 300000
+          # Count same-signature recurrences instead of every failure.
+          signature: true
+        # auto | strong | cheap | delegated | off. `delegated` means the session
+        # carries an explicit model selection that autotier must not fight.
+        routingMode: auto

package/docs/preset-row.md

@@ -0,0 +1,61 @@
+# Optional preset prompt section
+
+`dsh-autotier` is a **host-plane** plugin: the profile row applies to every
+session and routing works with no preset change. This page is for users who want
+the model to *know* which tier it is running on.
+
+## Why this is optional
+
+The host row is registered on the root scope, so it covers every agent,
+including subagents, without touching any preset. A preset section only adds
+model-facing text — it never changes routing, and the plugin works correctly
+when the section is absent (`/tier status` reports `prompt-section: absent`).
+
+This is deliberate: shipping a preset with the package would freeze a snapshot
+of the host's `standard` preset and drift on every harness release.
+
+## The row
+
+Add one row to **your own** agent preset's `cordis.patch.yml` (the file that
+declares the preset's plugin rows):
+
+```yaml
+- insert:
+    - id: autotier-prompt
+      name: '@deepseek-ai/dsh-system-prompt'
+      config:
+        sections:
+          - name: autotier
+            text: |-
+              You are running under dsh-autotier routing. The active tier is
+              chosen per turn: complex work is planned on the strong tier and
+              implemented on the cheap tier; simple work runs on the cheap tier
+              throughout. If a tool call is denied by the high-risk guard, do not
+              retry it — report what you were about to do and let the tier
+              escalate.
+```
+
+The exact `sections` shape is owned by the host `system-prompt` package; if your
+harness version expects a different key, follow the error the Loader prints —
+the plugin itself does not depend on this row.
+
+## Verifying it took effect
+
+`/tier status` prints the live routing state; the optional section itself is
+visible in the assembled system prompt, not in `/tier` output. If you rename the
+section, keep the name `autotier` so you can find it in the prompt.
+
+## Per-preset isolation
+
+If you want a preset to opt out of routing entirely, compose the plugin inside
+an `isolate` realm instead of the root scope:
+
+```yaml
+- isolate:
+    autotier: true
+  insert:
+    - id: autotier
+      name: dsh-autotier
+```
+
+A realm-isolated row only affects the sessions of that preset.

package/docs/supporting-lanes.md

@@ -0,0 +1,45 @@
+# Supporting lanes: compaction and title generation
+
+`dsh-autotier` routes **conversation requests** — the ones the agent loop
+assembles for a turn. Two other host seams make their own model calls and are
+deliberately left alone:
+
+| Lane | Host seam | Owner package |
+|---|---|---|
+| Context compaction | its own model settings | `@deepseek-ai/dsh-compaction` |
+| Session titles | its own model settings | `@deepseek-ai/dsh-session-title-llm` |
+
+Routing them from here would be wrong twice over: they are not turn-scoped, so a
+per-turn tier decision does not apply, and rewriting their calls would surprise a
+user who configured them explicitly.
+
+## Aligning their cost profile
+
+If you want the whole harness to sit on the cheap model, point each lane's own
+configuration at the same landing as `tiers.cheap`:
+
+```yaml
+- insert:
+    - id: compaction
+      name: '@deepseek-ai/dsh-compaction'
+      config:
+        provider: deepseek-official
+        model: deepseek-v4-flash
+        reasoningEffort: low
+
+    - id: session-title-llm
+      name: '@deepseek-ai/dsh-session-title-first-prompt-llm'
+      config:
+        provider: deepseek-official
+        model: deepseek-v4-flash
+```
+
+The key names above are the host packages' own; check the installed version's
+schema if a row is rejected. `dsh-autotier` never writes these rows.
+
+## Judge calls
+
+The low-confidence judge uses `intent.judge.model` (or the first catalog model
+whose id contains `flash`) through the ordinary `ctx.llm` path. It is a separate,
+short request with its own `maxTokens` and `timeoutMs`, so it never inherits a
+tier's landing — pin it to a cheap model on purpose.