@try-works/dsh-recursive-mode 0.3.0 → 0.4.0

package/src/router.ts

@@ -11,6 +11,42 @@
  */
 import { readFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
+// T9: the per-role model lookup, so there is ONE definition of "which model does this role use".
+// `role-route.ts` imports only the `RouterPolicy` TYPE from here, which erases at runtime — so
+// this is a one-way runtime dependency, not the cycle that bit `policy-globs` earlier.
+import { modelForRole } from './role-route.ts'
+
+/**
+ * ⚠ FU-19 — WHAT A CHILD RUNS ON, WHEN THE USER SAYS SO AND NOTHING MORE SPECIFIC DOES.
+ *
+ * Optional on purpose, and the reason is the same one the override layer gives below: an absent field must mean
+ * "defer to the next level in the precedence", never "reset to nothing". A default here would make every field
+ * present and silently shadow the role routes and phase routes forever.
+ */
+export interface SubagentDefault {
+  /** The SUBAGENT provider — who creates the child (`spawn`, `fork`). NOT the LLM provider; see below. */
+  provider?: string | null
+  /** The model id to ask for. */
+  model?: string | null
+  /**
+   * ⚠ THE LLM PROVIDER — WHO SERVES THE MODEL (`deepseek-official`), which is a DIFFERENT thing from the
+   * `provider` field above. Conflating the two was a real defect in this feature's first schema: a plain
+   * `provider` could mean either, and a user setting it had no way to know which.
+   *
+   * Optional: when only a model is named, the plugin looks its provider up from the inventory DSH exposes.
+   */
+  modelProvider?: string | null
+}
+
+/** Per-phase overrides — the narrowest level, and the one that answers "this phase needs a stronger model". */
+export interface PhaseRoute {
+  role?: string
+  /** The subagent provider, as above. */
+  provider?: string | null
+  model?: string | null
+  /** The LLM provider serving `model`, as above. */
+  modelProvider?: string | null
+}
 
 export interface RouterDefaults {
   when_role_unconfigured: string
@@ -19,6 +55,8 @@ export interface RouterDefaults {
   allow_auto_assign_if_single_cli: boolean
   probe_timeout_ms: number
   invoke_timeout_ms: number
+  /** FU-19: the general provider/model for delegated subagents, absent when the user has not chosen one. */
+  subagent?: SubagentDefault
 }
 
 export interface RoleRoute {
@@ -26,6 +64,16 @@ export interface RoleRoute {
   mode: string
   cli: string | null
   model: string | null
+  /**
+   * FU-19: the provider this role should be served by, when the user has chosen one. Absent means "let the tier
+   * ladder decide", which is what every policy scaffolded before this field did.
+   *
+   * This is the SUBAGENT provider — who creates the child. The LLM provider that serves the model is its own
+   * field below, because one name for two ideas is how a configuration becomes a guess.
+   */
+  provider?: string | null
+  /** FU-19: the LLM provider serving this role's `model`. Optional; looked up from the inventory when omitted. */
+  modelProvider?: string | null
   fallback: string
 }
 
@@ -33,6 +81,8 @@ export interface RouterPolicy {
   version: number
   defaults: RouterDefaults
   role_routes: Record<string, RoleRoute>
+  /** FU-19: phase-keyed overrides, e.g. `{ '08': { role: 'memory-auditor' } }`. Absent means none. */
+  phase_routes?: Record<string, PhaseRoute>
   cli_overrides: Record<string, unknown>
   custom_clis: unknown[]
 }
@@ -43,6 +93,22 @@ export interface RouteDecision {
   tier: RouteTier
   provider?: string
   reason: string
+  /**
+   * T9: the model the policy names for this role, or null when it names none.
+   *
+   * Present on EVERY decision because it is attached by the wrapper, never per-return-site.
+   *
+   * ⚠ THIS COMMENT USED TO SAY THE PLUGIN DOES NOT APPLY IT. That was true when it was written and is false now:
+   * `delegateReview` sets `request.agentOptions = { model }` when the provider declares the `agentOptions`
+   * capability, and reports a routing note when it does not. So this is still a value a caller can HONOUR, but
+   * the plugin now does the honouring — and says so when it cannot.
+   */
+  model?: string | null
+  /**
+   * FU-19: where the provider and model came from, one short label per value, so "why did this child run on
+   * that model" is answerable without reading the resolution code.
+   */
+  chosen?: { provider?: string; model?: string }
 }
 
 export interface SubagentProviderLike {
@@ -52,6 +118,12 @@ export interface SubagentProviderLike {
     depthLimit?: boolean
     toolFilter?: boolean
     persona?: boolean
+    /**
+     * T9: whether this provider accepts `agentOptions` (provider/model/reasoning-effort
+     * overrides). The harness REJECTS a start that sends them to a provider without this
+     * capability, so the caller must ASK rather than assume — see `delegateReview`.
+     */
+    agentOptions?: boolean
   }
 }
 
@@ -82,15 +154,51 @@ const DEFAULT_POLICY: RouterPolicy = {
   custom_clis: [],
 }
 
+/**
+ * T7 — the settings OVERRIDE layer over the declarative file.
+ *
+ * ONE PATH, NOT TWO (the item's own interaction note): `recursive-router.json` remains the
+ * declarative source, and the settings namespace can OVERRIDE individual fields without
+ * restating the file. That is why every field here is optional and why the schema declares
+ * NO defaults for them: an absent field means "defer to the file", and a default would make
+ * every field present and silently shadow the file forever.
+ */
+export interface RouterPolicyOverrides {
+  defaults?: Partial<RouterPolicy['defaults']>
+}
+
+/** Drop keys explicitly set to `undefined`, so "unset" cannot erase a file's value. */
+function compact<T extends object>(value: T | undefined): Partial<T> {
+  if (value === undefined) return {}
+  const out: Record<string, unknown> = {}
+  for (const [key, entry] of Object.entries(value)) {
+    if (entry !== undefined) out[key] = entry
+  }
+  return out as Partial<T>
+}
+
 /** Parse recursive-router.json. A missing/invalid file yields a default self-audit policy (never throws). */
-export function loadRouterPolicy(path?: string): RouterPolicy {
+export function loadRouterPolicy(path?: string, overrides?: RouterPolicyOverrides): RouterPolicy {
+  const base = readRouterPolicy(path)
+  const applied = compact(overrides?.defaults)
+  if (Object.keys(applied).length === 0) return base
+  return { ...base, defaults: { ...base.defaults, ...applied } }
+}
+
+/** The file (or the built-in default) — the declarative source the overrides sit on top of. */
+function readRouterPolicy(path?: string): RouterPolicy {
   if (!path || !existsSync(path)) return DEFAULT_POLICY
   try {
     const raw = JSON.parse(readFileSync(path, 'utf8')) as Partial<RouterPolicy>
     return {
       version: typeof raw.version === 'number' ? raw.version : 1,
+      // The spread carries `subagent` through when the file declares it and leaves it absent when it does not —
+      // which is exactly the tolerance FU-19 needs, with no extra code.
       defaults: { ...DEFAULT_POLICY.defaults, ...(raw.defaults ?? {}) },
       role_routes: raw.role_routes ?? {},
+      // Phase overrides are carried only when the file has them: an empty object would claim the user configured
+      // something, and absence is a fact worth keeping distinct from emptiness.
+      ...(raw.phase_routes === undefined ? {} : { phase_routes: raw.phase_routes }),
       cli_overrides: raw.cli_overrides ?? {},
       custom_clis: raw.custom_clis ?? [],
     }
@@ -104,13 +212,31 @@ export function routerPolicyPath(root: string): string {
   return join(root, '.recursive', 'config', 'recursive-router.json')
 }
 
+/**
+ * T9 — attach the role's model to the decision.
+ *
+ * ⚠ WHY A WRAPPER AND NOT SIX EDITS. `resolveRoleInner` has six return sites, and adding the
+ * model to each would leave a decision shape that carries it on some paths and not others — a
+ * trap for the next reader, and exactly the kind of quiet inconsistency this plan keeps
+ * refusing to ship. Attaching it ONCE, at the seam where the decision leaves, makes the field
+ * present on EVERY path by construction. The policy lookup itself lives in `role-route.ts`
+ * (`routeForRole`), so there is one definition of "which model does this role use", not two.
+ */
+export function resolveRole(
+  role: string,
+  policy: RouterPolicy,
+  providers: Record<string, SubagentProviderLike>,
+): RouteDecision {
+  return { ...resolveRoleInner(role, policy, providers), model: modelForRole(role, policy) }
+}
+
 /**
  * Resolve a role to a tier, preferring a native provider whose name maps to
  * the role (e.g. role 'code-reviewer' -> provider 'code-reviewer' or the
  * generic spawn/fork provider). External CLIs ride their provider rows; else
  * the policy fallback.
  */
-export function resolveRole(
+function resolveRoleInner(
   role: string,
   policy: RouterPolicy,
   providers: Record<string, SubagentProviderLike>,