@dsh-jev/router 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @dsh-jev/router
+
+dsh (DeepSeek Harness) cordis plugin: per-turn model routing decided by
+[jev System One](https://typesafe.ai) via `@dsh-jev/core`.
+
+Before each turn's first model request, the plugin asks jev to classify the
+turn's complexity:
+
+- **heavy** (multi-step coding, debugging, architecture) → `deepseek-official`
+- **light** (simple Q&A, formatting) → `zai-coding-cn` / `glm-5.3-flash`
+
+## Safety design
+
+- **Never registers or modifies LLM routes.** Route registration belongs to
+  `dsh-llm-deepseek` / `dsh-llm-pi-ai` / `dsh-auth`; cross-plugin registration
+  conflicts are a known dsh footgun. This plugin only *selects* between routes
+  already present in `ctx.llm`, via the `agent/request` waterfall — and only
+  after double-checking the target provider is actually registered
+  (`ctx.llm.listProviders()`). An unregistered target keeps the default route.
+- **Shadow-run by default.** Decisions are logged to stdout
+  (`[dsh-jev-router] turn=… picked=… target=… shadow`) and nothing changes.
+  Set `mode: enforce` in the plugin config to actually switch.
+- **Degrades, never breaks.** jev unreachable / timeout / non-2xx → the
+  resolved config is returned untouched (default route is kept) and the
+  degrade reason is logged. The listener itself never throws.
+
+## Install into a dsh profile
+
+```yaml
+# <profile>/cordis.patch.yml
+- insert:
+    - id: dsh-jev-router
+      # local files go under `name:` (dsh converts fs paths to file:// URLs);
+      # a `path:` field is silently ignored and the import crashes
+      name: /Users/you/workspace/opensource/dsh-jev/packages/router/dist/index.js
+      config:
+        mode: shadow # shadow | enforce
+        heavy: { provider: deepseek-official, model: deepseek-flash }
+        light: { provider: zai-coding-cn, model: glm-5.3-flash }
+```
+
+All config keys are optional; `JEV_API_KEY` / `JEV_ENDPOINT` env vars are
+honored via `@dsh-jev/core`.
+
+## Development
+
+```sh
+pnpm --filter @dsh-jev/router build
+pnpm --filter @dsh-jev/router test   # 13 tests: routing, fallback, shadow vs enforce
+```

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+/**
+ * @dsh-jev/router — per-turn jev routing for DeepSeek Harness (dsh).
+ *
+ * RED LINE (do not cross): this plugin NEVER registers, patches, or removes
+ * LLM routes. Route registration is owned by dsh-llm-deepseek / dsh-llm-pi-ai
+ * / dsh-auth, and cross-plugin registration conflicts are a known footgun
+ * (see ~/.config/dsh/AGENTS.md). We only *choose* between routes that are
+ * already registered in `ctx.llm` — via the `agent/request` waterfall — and
+ * only when `mode: enforce` is explicitly configured. The default is
+ * `shadow`: decisions are logged to stdout and the request is untouched.
+ *
+ * Failure semantics: any jev failure (network, timeout, non-2xx, malformed)
+ * degrades to "no opinion" — the resolved config is returned unchanged, so
+ * the agent keeps whatever default route it would have used.
+ */
+import { JevOutcome, ChoiceAnswer } from '@dsh-jev/core';
+export interface RouteSelection {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+}
+export interface RouterConfig {
+    /** `shadow` (default) logs decisions without switching; `enforce` actually switches. */
+    mode?: 'shadow' | 'enforce';
+    /** Route for complex turns. */
+    heavy?: RouteSelection;
+    /** Route for simple turns. */
+    light?: RouteSelection;
+    endpoint?: string;
+    apiKey?: string;
+    timeoutMs?: number;
+    /** Injectable fetch for tests. */
+    fetchImpl?: typeof fetch;
+    /** Injectable logger for tests. */
+    log?: (line: string) => void;
+}
+export declare const DEFAULT_HEAVY: RouteSelection;
+export declare const DEFAULT_LIGHT: RouteSelection;
+interface TextBlock {
+    type: 'text';
+    text: string;
+}
+interface UserMessage {
+    content?: Array<TextBlock | {
+        type: string;
+        [k: string]: unknown;
+    }>;
+}
+/** The `agent/pre-step` payload slice we consume. */
+interface PreStepPayload {
+    agent: unknown;
+    messages: UserMessage[];
+    turn: number;
+    step: number;
+    signal: AbortSignal;
+}
+/** The `agent/request` payload slice we consume. */
+interface RequestPayload {
+    agent: unknown;
+    turn: number;
+    step: number;
+    signal: AbortSignal;
+}
+/** Frozen LlmCallConfig slice returned by the `agent/request` waterfall. */
+interface CallConfig {
+    provider: string;
+    model: string;
+    reasoningEffort?: string;
+    maxTokens?: number;
+    [k: string]: unknown;
+}
+/** Minimal `ctx.llm` surface (read-only; we never mutate registrations). */
+interface LlmRegistry {
+    listProviders(): Array<{
+        id: string;
+        name?: string;
+    }>;
+}
+interface PluginContext {
+    on(event: 'agent/pre-step', listener: (payload: PreStepPayload, next: () => Promise<unknown>) => Promise<unknown>): unknown;
+    on(event: 'agent/request', listener: (payload: RequestPayload, next: () => Promise<CallConfig>) => Promise<CallConfig>): unknown;
+    llm?: LlmRegistry;
+}
+export declare const name = "dsh-jev-router";
+export declare const inject: string[];
+/** Concatenate the text blocks of the newest user message for jev context. */
+export declare function extractUserText(messages: UserMessage[]): string;
+export declare function sameRoute(a: {
+    provider: string;
+    model: string;
+}, b: {
+    provider: string;
+    model: string;
+}): boolean;
+export declare function isProviderRegistered(llm: LlmRegistry | undefined, provider: string): boolean;
+/** Map a jev choice outcome to the target route, or undefined to keep default. */
+export declare function selectRoute(outcome: JevOutcome<ChoiceAnswer>, resolved: CallConfig, config: RouterConfig, llm: LlmRegistry | undefined): {
+    route: RouteSelection;
+    keepDefault: boolean;
+    reason: string;
+};
+export declare function apply(ctx: PluginContext, config?: RouterConfig): void;
+export {};

package/dist/index.js

@@ -0,0 +1,137 @@
+/**
+ * @dsh-jev/router — per-turn jev routing for DeepSeek Harness (dsh).
+ *
+ * RED LINE (do not cross): this plugin NEVER registers, patches, or removes
+ * LLM routes. Route registration is owned by dsh-llm-deepseek / dsh-llm-pi-ai
+ * / dsh-auth, and cross-plugin registration conflicts are a known footgun
+ * (see ~/.config/dsh/AGENTS.md). We only *choose* between routes that are
+ * already registered in `ctx.llm` — via the `agent/request` waterfall — and
+ * only when `mode: enforce` is explicitly configured. The default is
+ * `shadow`: decisions are logged to stdout and the request is untouched.
+ *
+ * Failure semantics: any jev failure (network, timeout, non-2xx, malformed)
+ * degrades to "no opinion" — the resolved config is returned unchanged, so
+ * the agent keeps whatever default route it would have used.
+ */
+import { createJevClient } from '@dsh-jev/core';
+export const DEFAULT_HEAVY = {
+    provider: 'deepseek-official',
+    model: 'deepseek-flash',
+};
+export const DEFAULT_LIGHT = {
+    provider: 'zai-coding-cn',
+    model: 'glm-5.3-flash',
+};
+export const name = 'dsh-jev-router';
+export const inject = ['llm'];
+// ---------------------------------------------------------------------------
+// Pure helpers (unit-tested directly).
+// ---------------------------------------------------------------------------
+/** Concatenate the text blocks of the newest user message for jev context. */
+export function extractUserText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const blocks = messages[i]?.content;
+        if (!Array.isArray(blocks) || blocks.length === 0)
+            continue;
+        const text = blocks
+            .filter((b) => b?.type === 'text' && typeof b.text === 'string')
+            .map((b) => b.text)
+            .join('\n')
+            .trim();
+        if (text)
+            return text.slice(0, 4000);
+    }
+    return '';
+}
+export function sameRoute(a, b) {
+    return a.provider === b.provider && a.model === b.model;
+}
+export function isProviderRegistered(llm, provider) {
+    try {
+        const providers = llm?.listProviders();
+        if (!Array.isArray(providers))
+            return false;
+        return providers.some((p) => p?.id === provider);
+    }
+    catch {
+        return false;
+    }
+}
+/** Map a jev choice outcome to the target route, or undefined to keep default. */
+export function selectRoute(outcome, resolved, config, llm) {
+    const heavy = { ...DEFAULT_HEAVY, ...config.heavy };
+    const light = { ...DEFAULT_LIGHT, ...config.light };
+    if (!outcome.ok) {
+        return { route: heavy, keepDefault: true, reason: `jev degraded (${outcome.error ?? 'unknown'}) — keeping default route` };
+    }
+    const picked = outcome.value.picked;
+    const route = picked === 'light' ? light : picked === 'heavy' ? heavy : heavy;
+    if (sameRoute(route, resolved)) {
+        return { route, keepDefault: true, reason: `already on ${route.provider}/${route.model}` };
+    }
+    if (!isProviderRegistered(llm, route.provider)) {
+        return { route, keepDefault: true, reason: `target route ${route.provider} not registered — keeping default (registration is not this plugin's job)` };
+    }
+    return { route, keepDefault: false, reason: 'ok' };
+}
+// ---------------------------------------------------------------------------
+// Plugin entry.
+// ---------------------------------------------------------------------------
+export function apply(ctx, config = {}) {
+    const mode = config.mode ?? 'shadow';
+    const log = config.log ?? ((line) => process.stdout.write(line + '\n'));
+    const jev = createJevClient({
+        ...(config.endpoint !== undefined ? { endpoint: config.endpoint } : {}),
+        ...(config.apiKey !== undefined ? { apiKey: config.apiKey } : {}),
+        ...(config.timeoutMs !== undefined ? { timeoutMs: config.timeoutMs } : {}),
+        ...(config.fetchImpl !== undefined ? { fetchImpl: config.fetchImpl } : {}),
+    });
+    /** Latest user text per agent per turn, captured at pre-step. */
+    const turnText = new WeakMap();
+    const evaluate = async (agent, turn) => {
+        const text = turnText.get(agent)?.get(turn) ?? '';
+        const question = 'Classify the complexity of this assistant turn for model routing. ' +
+            'Choose "heavy" when it needs strong reasoning (multi-step coding, debugging, architecture, long-context analysis). ' +
+            'Choose "light" when a fast, cheap model suffices (simple Q&A, formatting, small lookups, chit-chat).';
+        return await jev.choice({ question, options: ['heavy', 'light'], context: text ? { userTurn: text } : {} }, { pickedIndex: 0, picked: 'heavy' } // structural fallback; degraded outcomes keep the default route anyway
+        );
+    };
+    ctx.on('agent/pre-step', async (payload, next) => {
+        const decision = await next();
+        const perTurn = turnText.get(payload.agent) ?? new Map();
+        perTurn.set(payload.turn, extractUserText(payload.messages));
+        turnText.set(payload.agent, perTurn);
+        return decision;
+    });
+    ctx.on('agent/request', async (payload, next) => {
+        const resolved = await next();
+        let outcome;
+        try {
+            outcome = await evaluate(payload.agent, payload.turn);
+        }
+        catch {
+            // JevClient contractually never throws, but stay defensive: keep default.
+            return resolved;
+        }
+        const { route, keepDefault, reason } = selectRoute(outcome, resolved, config, ctx.llm);
+        const label = `turn=${payload.turn} step=${payload.step} picked=${outcome.value.picked}` +
+            (outcome.ok ? '' : ` (degraded)`) +
+            ` target=${route.provider}/${route.model}` +
+            ` from=${resolved.provider}/${resolved.model}`;
+        if (keepDefault) {
+            log(`[dsh-jev-router] ${label} keep-default — ${reason}`);
+            return resolved;
+        }
+        if (mode !== 'enforce') {
+            log(`[dsh-jev-router] ${label} shadow (set mode: enforce to switch)`);
+            return resolved;
+        }
+        log(`[dsh-jev-router] ${label} enforcing switch`);
+        return {
+            ...resolved,
+            provider: route.provider,
+            model: route.model,
+            ...(route.reasoningEffort !== undefined ? { reasoningEffort: route.reasoningEffort } : {}),
+        };
+    });
+}

package/dist/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.test.js

@@ -0,0 +1,152 @@
+import { describe, expect, it } from 'vitest';
+import { apply, extractUserText, selectRoute } from './index.js';
+function mockJevFetch(picked) {
+    const calls = [];
+    const fetchImpl = (async (url, init) => {
+        calls.push({ url: String(url), body: JSON.parse(init.body) });
+        if (picked === 'DEGRADE') {
+            return new Response('nope', { status: 403 });
+        }
+        return Response.json({ answer: { pickedIndex: picked === 'light' ? 1 : 0, picked, rationale: 'test' } });
+    });
+    return { fetchImpl, calls };
+}
+function makeHarness(llm = { listProviders: () => [{ id: 'deepseek-official' }, { id: 'zai-coding-cn' }] }) {
+    const listeners = new Map();
+    const ctx = {
+        llm,
+        on: (event, listener) => listeners.set(event, listener),
+    };
+    return { listeners, ctx };
+}
+const resolvedConfig = { provider: 'deepseek-official', model: 'deepseek-flash' };
+async function runRequest(h, turn = 1, next = async () => ({ ...resolvedConfig })) {
+    const listener = h.listeners.get('agent/request');
+    const agent = {};
+    await h.listeners.get('agent/pre-step')({ agent, turn, step: 1, messages: [], signal: new AbortController().signal }, async () => ({ kind: 'enter', messages: [] }));
+    return listener({ agent, turn, step: 1, signal: new AbortController().signal }, next);
+}
+// ---------------------------------------------------------------------------
+// extractUserText
+// ---------------------------------------------------------------------------
+describe('extractUserText', () => {
+    it('returns the newest user message text', () => {
+        const messages = [
+            { content: [{ type: 'text', text: 'old question' }] },
+            { content: [{ type: 'text', text: 'new question' }] },
+        ];
+        expect(extractUserText(messages)).toBe('new question');
+    });
+    it('skips messages without text blocks and truncates long input', () => {
+        expect(extractUserText([{ content: [{ type: 'image', url: 'x' }] }, { content: [] }])).toBe('');
+        const long = { content: [{ type: 'text', text: 'x'.repeat(9000) }] };
+        expect(extractUserText([long]).length).toBe(4000);
+    });
+});
+// ---------------------------------------------------------------------------
+// selectRoute
+// ---------------------------------------------------------------------------
+const okOutcome = (picked) => ({
+    ok: true,
+    value: { pickedIndex: picked === 'light' ? 1 : 0, picked },
+    durationMs: 5,
+});
+const degraded = {
+    ok: false,
+    value: { pickedIndex: 0, picked: 'heavy' },
+    error: 'HTTP 403',
+    durationMs: 3,
+};
+describe('selectRoute', () => {
+    const llm = { listProviders: () => [{ id: 'deepseek-official' }, { id: 'zai-coding-cn' }] };
+    it('light pick maps to the light route', () => {
+        const r = selectRoute(okOutcome('light'), resolvedConfig, {}, llm);
+        expect(r.keepDefault).toBe(false);
+        expect(r.route).toEqual({ provider: 'zai-coding-cn', model: 'glm-5.3-flash' });
+    });
+    it('heavy pick keeps the heavy route when already there', () => {
+        const r = selectRoute(okOutcome('heavy'), resolvedConfig, {}, llm);
+        expect(r.keepDefault).toBe(true); // already on heavy
+    });
+    it('degraded outcome keeps the default route', () => {
+        const r = selectRoute(degraded, resolvedConfig, {}, llm);
+        expect(r.keepDefault).toBe(true);
+        expect(r.reason).toContain('degraded');
+    });
+    it('unregistered target provider keeps the default route', () => {
+        const emptyLlm = { listProviders: () => [{ id: 'deepseek-official' }] };
+        const r = selectRoute(okOutcome('light'), resolvedConfig, {}, emptyLlm);
+        expect(r.keepDefault).toBe(true);
+        expect(r.reason).toContain('not registered');
+    });
+    it('throwing listProviders is treated as unregistered', () => {
+        const badLlm = { listProviders: () => { throw new Error('boom'); } };
+        expect(selectRoute(okOutcome('light'), resolvedConfig, {}, badLlm).keepDefault).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// plugin wiring
+// ---------------------------------------------------------------------------
+describe('apply', () => {
+    it('shadow mode (default): logs but never changes config', async () => {
+        const { fetchImpl } = mockJevFetch('light');
+        const lines = [];
+        const h = makeHarness();
+        apply(h.ctx, { fetchImpl, log: (l) => lines.push(l) });
+        const out = await runRequest(h);
+        expect(out).toEqual(resolvedConfig);
+        expect(lines).toHaveLength(1);
+        expect(lines[0]).toContain('shadow');
+        expect(lines[0]).toContain('zai-coding-cn/glm-5.3-flash');
+    });
+    it('enforce mode: switches to the light route on a light pick', async () => {
+        const { fetchImpl, calls } = mockJevFetch('light');
+        const lines = [];
+        const h = makeHarness();
+        apply(h.ctx, { fetchImpl, log: (l) => lines.push(l), mode: 'enforce' });
+        const out = await runRequest(h);
+        expect(out).toEqual({ provider: 'zai-coding-cn', model: 'glm-5.3-flash' });
+        expect(lines[0]).toContain('enforcing switch');
+        // the captured user turn reached jev as context
+        expect(calls[0].body.context.userTurn ?? '').toBe('');
+    });
+    it('enforce mode: heavy pick from a light default switches up', async () => {
+        const { fetchImpl } = mockJevFetch('heavy');
+        const h = makeHarness();
+        apply(h.ctx, { fetchImpl, log: () => { }, mode: 'enforce' });
+        const out = await runRequest(h, 1, async () => ({ provider: 'zai-coding-cn', model: 'glm-5.3-flash' }));
+        expect(out).toEqual({ provider: 'deepseek-official', model: 'deepseek-flash' });
+    });
+    it('jev unreachable: keeps default and logs the degrade', async () => {
+        const { fetchImpl } = mockJevFetch('DEGRADE');
+        const lines = [];
+        const h = makeHarness();
+        apply(h.ctx, { fetchImpl, log: (l) => lines.push(l), mode: 'enforce' });
+        const out = await runRequest(h);
+        expect(out).toEqual(resolvedConfig);
+        expect(lines[0]).toContain('degraded');
+    });
+    it('pre-step captured user text is sent to jev', async () => {
+        const { fetchImpl, calls } = mockJevFetch('heavy');
+        const h = makeHarness();
+        apply(h.ctx, { fetchImpl, log: () => { } });
+        const agent = {};
+        await h.listeners.get('agent/pre-step')({ agent, turn: 3, step: 1, messages: [{ content: [{ type: 'text', text: 'refactor the parser' }] }], signal: new AbortController().signal }, async () => ({ kind: 'enter', messages: [] }));
+        await h.listeners.get('agent/request')({ agent, turn: 3, step: 1, signal: new AbortController().signal }, async () => ({ ...resolvedConfig }));
+        expect(calls[0].body.context.userTurn).toBe('refactor the parser');
+        expect(calls[0].body.options).toEqual(['heavy', 'light']);
+    });
+    it('custom routes are honored', async () => {
+        const { fetchImpl } = mockJevFetch('light');
+        const h = makeHarness();
+        const config = {
+            fetchImpl,
+            log: () => { },
+            mode: 'enforce',
+            light: { provider: 'zai-coding-cn', model: 'glm-5.3' },
+        };
+        apply(h.ctx, config);
+        const out = await runRequest(h);
+        expect(out).toEqual({ provider: 'zai-coding-cn', model: 'glm-5.3' });
+    });
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@dsh-jev/router",
+  "version": "0.1.0",
+  "description": "dsh cordis plugin: per-turn jev System One complexity routing between already-registered LLM routes (shadow-run by default)",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@dsh-jev/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "license": "MIT"
+}