harness-dispatch 0.4.0 → 0.6.0

package/dist/config/validation.js

@@ -0,0 +1,189 @@
+/**
+ * What a config file is ALLOWED to say, and what to warn about when it says
+ * something else.
+ *
+ * Split out of config.ts. This module exists because of a specific, repeated
+ * failure: the parser reads what it recognises and cannot distinguish a key it
+ * does not know from a key that is absent. Four silent-drop defects came from
+ * that — a misspelled `workspace_policy` or `safety_profile` left the route
+ * running under the LESS restrictive default, silently.
+ *
+ * So the legal surface is enumerated here rather than implied by whatever the
+ * builders happen to read. Keeping it in one file is the point: a per-shape
+ * copy is what drifted last time.
+ */
+/**
+ * Warn on any unrecognised value for an enum that FAILS OPEN.
+ *
+ * Every *From() validator returns undefined on a mismatch and the caller
+ * falls back to a default — silently. For most fields that is merely
+ * annoying, but for these three the default is LESS restrictive than what the
+ * operator asked for:
+ *
+ *   safety_profile: read_onlyy  -> undefined -> DEFAULT_SAFETY_PROFILE
+ *                                            -> workspace_edit (write access)
+ *   workspace_policy: coppy     -> undefined -> shared_locked
+ *                                            -> a SHARED workspace, not an
+ *                                               isolated copy
+ *
+ * A typo therefore quietly grants more than intended, which is the wrong
+ * direction for a safety control. The same parser already warns loudly for a
+ * malformed `protocol` block, so this is consistency as much as safety.
+ *
+ * Walks the raw tree rather than hooking each builder: the same keys appear
+ * under services:, clis:, endpoints: and overrides:, and a single walk cannot
+ * miss a format the way four separate call sites can.
+ */
+export const FAIL_OPEN_ENUMS = {
+    // Billing enums, added after a review found `billing_kind: metered-api`
+    // (hyphen, not underscore) silently resolving to the harness default of
+    // `included_plan_then_flexible_credits` with paidUsagePossible false and no
+    // warning. This block existed precisely for enums whose fallback is LESS
+    // restrictive than the value attempted, and billing is the other hard
+    // constraint the product states — a typo here silently marks a metered route
+    // as free.
+    billing_kind: [
+        "local_compute",
+        "included_plan_usage",
+        "included_plan_then_flexible_credits",
+        "included_credit_then_optional_overage",
+        "included_usage_then_on_demand",
+        "metered_api",
+        "free_quota",
+        "unknown",
+    ],
+    billing_confidence: ["documented", "inferred", "unknown", "unsupported"],
+    safety_profile: ["read_only", "workspace_edit", "full_auto"],
+    effective_safety: ["read_only", "workspace_edit", "full_auto"],
+    workspace_policy: ["shared", "shared_locked", "git_worktree", "copy"],
+};
+/**
+ * Every key this parser understands at the top level of config.yaml.
+ *
+ * `doctor` reported "no unrecognized config entries" while a typo'd or
+ * invented top-level key produced no warning at all — the check's own name
+ * promised something it never did. A misspelled `max_concurrent_runs` is
+ * indistinguishable from not setting it, which is exactly the silent-default
+ * class that has bitten this file twice already.
+ */
+export const KNOWN_TOP_LEVEL_KEYS = new Set([
+    "version",
+    "clis",
+    "endpoints",
+    "services",
+    "disabled",
+    "overrides",
+    "api_keys",
+    "protocols",
+    "policy",
+    "telemetry",
+    "retention",
+    "leaderboard",
+    "max_concurrent_runs",
+    "default_safety_profile",
+    "workspace_policy",
+    "protocol",
+]);
+/**
+ * Every key a `clis:` or `endpoints:` entry may carry.
+ *
+ * ROOT-CAUSE FIX, not a fourth instance. Three separate silent-drop defects
+ * were found in this file in one day — workspace_policy ignored for `clis:`,
+ * api_keys ignored for `endpoints:`, unknown top-level keys unwarned — and
+ * each was patched individually. Measured afterwards: a route carrying
+ * `workspace_polcy`, `safety_profil` and `tierr` still produced ZERO warnings
+ * and silently got none of the three.
+ *
+ * The mechanism is that this parser reads what it recognises and cannot
+ * distinguish a key it does not know from a key that is absent. Nothing
+ * enumerated the legal surface, so every future misspelling was guaranteed to
+ * fail the same silent way — and these are safety and isolation controls, so
+ * "silently absent" means "silently less restrictive".
+ *
+ * Kept as one list for both entry shapes on purpose. Splitting it per shape
+ * would recreate the original defect, where two parallel field lists drifted
+ * and each was missing something the other had.
+ */
+export const KNOWN_ROUTE_KEYS = new Set([
+    "name", "harness", "type", "command", "enabled", "model", "models", "model_hint",
+    "tier", "weight", "cli_capability", "capabilities", "timeout_ms",
+    "max_input_tokens", "max_output_tokens", "thinking_level",
+    "leaderboard_model", "escalate_model", "escalate_on", "resource_weight",
+    "api_key", "base_url", "protocol", "filter",
+    "provider", "surface", "auth_source", "billing_kind", "billing_confidence",
+    "billing_notes", "paid_usage_possible", "allow_paid_usage",
+    "safety_profile", "effective_safety", "workspace_policy",
+    "endpoint_mode", "endpoint_provider", "wire_protocol",
+]);
+export function warnUnknownRouteKeys(entry, label, warnings) {
+    for (const key of Object.keys(entry)) {
+        if (KNOWN_ROUTE_KEYS.has(key))
+            continue;
+        warnings.push(`${label}: unknown key "${key}" — IGNORED. If this was meant to be a ` +
+            `safety or workspace setting, it is NOT in effect; check the spelling.`);
+    }
+}
+/**
+ * Keys the parser ACCEPTS and nothing reads.
+ *
+ * Silently allowing them is worse than rejecting them: `default_safety_profile`
+ * is a safety-control name that does nothing at all, which is the exact
+ * failure this module exists to prevent. They stay allow-listed (so they are
+ * not reported as typos) but say plainly that setting them has no effect.
+ *
+ * Verified read-nowhere in src/ at the time of writing; if one is implemented
+ * later, delete it from here and the warning goes away.
+ */
+const ACCEPTED_BUT_UNIMPLEMENTED = new Set(["protocols", "default_safety_profile"]);
+export function warnUnknownTopLevelKeys(raw, warnings) {
+    for (const key of Object.keys(raw)) {
+        if (ACCEPTED_BUT_UNIMPLEMENTED.has(key)) {
+            warnings.push(`${key}: recognised but NOT IMPLEMENTED — setting it has no effect. ` +
+                `Remove it, or track the gap; it is not a typo.`);
+            continue;
+        }
+        if (KNOWN_TOP_LEVEL_KEYS.has(key))
+            continue;
+        if (key.endsWith("_api_key"))
+            continue; // documented per-route shorthand
+        warnings.push(`unknown top-level config key: ${key} — IGNORED. Check the spelling against ` +
+            `the documented keys (${[...KNOWN_TOP_LEVEL_KEYS].slice(0, 6).join(", ")}, ...).`);
+    }
+}
+export function warnUnknownSafetyEnums(node, warnings, where = "") {
+    if (Array.isArray(node)) {
+        for (const [i, v] of node.entries())
+            warnUnknownSafetyEnums(v, warnings, `${where}[${i}]`);
+        return;
+    }
+    if (node === null || typeof node !== "object")
+        return;
+    const obj = node;
+    const label = typeof obj.name === "string" && obj.name !== "" ? String(obj.name) : where || "config";
+    for (const [key, allowed] of Object.entries(FAIL_OPEN_ENUMS)) {
+        const value = obj[key];
+        if (value === undefined)
+            continue;
+        if (typeof value === "string" && allowed.includes(value))
+            continue;
+        // effective_safety may also be a per-request map; validate it entry by
+        // entry so a typo in one key still warns without condemning the whole
+        // block. See effectiveSafetyFrom().
+        if (key === "effective_safety" && value !== null && typeof value === "object" && !Array.isArray(value)) {
+            const entries = Object.entries(value);
+            const bad = entries.filter(([k, v]) => !allowed.includes(k) || typeof v !== "string" || !allowed.includes(v));
+            if (bad.length === 0)
+                continue;
+            warnings.push(`${label}: effective_safety: ${bad.map(([k, v]) => `${k}: ${JSON.stringify(v)}`).join(", ")} ` +
+                `is not a ${allowed.join("/")} pair — IGNORED for those requests.`);
+            continue;
+        }
+        warnings.push(`${label}: ${key}: ${JSON.stringify(value)} is not one of ${allowed.join(", ")} — ` +
+            `IGNORED, and the default applies instead, which is less restrictive than what ` +
+            `this looks like it was meant to set. Fix the value.`);
+    }
+    for (const [k, v] of Object.entries(obj)) {
+        warnUnknownSafetyEnums(v, warnings, where ? `${where}.${k}` : k);
+    }
+}
+//# sourceMappingURL=validation.js.map

package/dist/config/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/config/validation.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -12,14 +12,31 @@
  * All string values are scanned for ${ENV_VAR} references and replaced with
  * the corresponding environment variable.
  */
+/** Injection seam for tests. Set via loadConfig({ whichFn }) if needed. */
+export type WhichFn = (cmd: string) => Promise<string | null>;
 import type { CliProtocolConfig, RouterConfig } from "./types.js";
 /** Named, selectable protocols — every harness in CLI_DEFAULTS that defines one, keyed by its harness name (see protocolFrom()'s string/`extends:` handling). */
 export declare const PROTOCOL_PRESETS: Record<string, CliProtocolConfig>;
-/** Injection seam for tests. Set via loadConfig({ whichFn }) if needed. */
-export type WhichFn = (cmd: string) => Promise<string | null>;
+/**
+ * Commands auto-detect probes on PATH, exported so `doctor` can name them.
+ *
+ * A zero-route install used to report "0 ready route(s)" and stop, which tells
+ * a new user nothing about what was looked for or what to install. Keyed the
+ * same way as AUTO_DETECT_NAME so the two cannot drift.
+ */
+export declare const AUTO_DETECT_COMMANDS: Record<string, string>;
 export interface LoadConfigOptions {
     /** Override `which` for tests — return null when a CLI is "not found". */
     whichFn?: WhichFn;
+    /**
+     * Treat a missing explicit path as auto-detect rather than an error.
+     *
+     * Only `configure` sets this: the path it is given is its OUTPUT, which
+     * legitimately does not exist yet. For every other command an explicit
+     * --config that is not there is a typo, and silently auto-detecting printed
+     * a confident route table for a config that was never loaded.
+     */
+    allowMissing?: boolean;
 }
 /**
  * Load a RouterConfig.

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAWH,OAAO,KAAK,EAOV,iBAAiB,EAGjB,YAAY,EAOb,MAAM,YAAY,CAAC;AA+EpB,iKAAiK;AACjK,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAI9D,CAAC;AA4DF,2EAA2E;AAC3E,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AA09B9D,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC9B,IAAI,CAAC,EAAE,MAAM,EACb,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAwEvB;AAMD,MAAM,WAAW,aAAa;IAC5B,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,EACnC,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GACpD,aAAa,CAkCf"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA6BH,2EAA2E;AAC3E,MAAM,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;AA+B9D,OAAO,KAAK,EAOV,iBAAiB,EAGjB,YAAY,EAOb,MAAM,YAAY,CAAC;AAsEpB,iKAAiK;AACjK,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAI9D,CAAC;AAQF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAKvD,CAAC;AA6iBF,MAAM,WAAW,iBAAiB;IAChC,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,UAAU,CAC9B,IAAI,CAAC,EAAE,MAAM,EACb,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAwGvB;AAMD,MAAM,WAAW,aAAa;IAC5B,IAAI,IAAI,IAAI,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,EACnC,IAAI,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAO,GACpD,aAAa,CAkCf"}