harness-dispatch 0.4.0 → 0.5.0

package/dist/config/protocol.js

@@ -0,0 +1,300 @@
+/**
+ * Parsing for a route's `protocol:` block — how a CLI harness is actually
+ * invoked and how its output is read.
+ *
+ * Split out of config.ts. This is the largest single concern in that file and
+ * the most self-contained: it turns YAML into a CliProtocolConfig and knows
+ * nothing about routes, billing, or defaults merging.
+ *
+ * It is also the reason `harness: generic` works at all — every CLI harness,
+ * built-in or user-added, is driven by this structure rather than by
+ * TypeScript. That is why a malformed protocol block skips the whole entry
+ * with a warning instead of landing a route that would fail at dispatch time.
+ */
+import { str } from "./coercions.js";
+const SAFETY_PROFILES = ["read_only", "workspace_edit", "full_auto"];
+/** The full set of `{{name}}` tokens expandToken() in generic-cli.ts understands. */
+export const KNOWN_ARG_PLACEHOLDERS = new Set([
+    "{{prompt}}",
+    "{{model}}",
+    "{{safety}}",
+    "{{working_dir}}",
+    "{{file_dirs}}",
+    "{{native_args}}",
+]);
+export function stringArrayFrom(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    const out = raw.filter((v) => typeof v === "string");
+    return out.length > 0 ? out : undefined;
+}
+/**
+ * Parse `protocol:` for any route (see CliProtocolConfig in types.ts).
+ * Three shapes:
+ *  - A string ("cursor", "codex", ...) — looked up in presets by
+ *    name. Lets a config select a known protocol without retyping it, and
+ *    is the extension point for "others add further protocols" — a new
+ *    named entry in the shipped config.default.yaml is immediately selectable here,
+ *    no code changes.
+ *  - An object with `extends: <preset name>` — starts from that preset and
+ *    overrides only the fields present, for the common "95% the same, one
+ *    flag different" case. safety merges per-profile (overriding just
+ *    full_auto doesn't erase read_only/workspace_edit from the preset).
+ *  - A plain object — the full protocol, no preset involved (unchanged
+ *    behavior from before presets existed).
+ *
+ * Returns undefined — with a warning — for anything malformed, so a broken
+ * block degrades to "route unusable" (isAvailable() checks for a missing
+ * protocol) rather than a half-built dispatcher silently doing the wrong
+ * thing.
+ */
+export function protocolFrom(raw, routeLabel, warnings, 
+// REQUIRED, deliberately not defaulted to {}. A default made a forgotten
+// argument resolve every preset name to nothing — silently, at runtime,
+// which is the exact failure mode this file's own history is made of. As a
+// required parameter the compiler catches it instead.
+presets) {
+    if (typeof raw === "string") {
+        const preset = presets[raw];
+        if (!preset) {
+            warnings.push(`${routeLabel}: protocol "${raw}" is not a known preset (expected one of: ` +
+                `${Object.keys(presets).join(", ")}) — entry ignored.`);
+            return undefined;
+        }
+        return preset;
+    }
+    if (raw === null || typeof raw !== "object")
+        return undefined;
+    const r = raw;
+    let base;
+    if (typeof r.extends === "string") {
+        base = presets[r.extends];
+        if (!base) {
+            warnings.push(`${routeLabel}: protocol.extends "${r.extends}" is not a known preset (expected one of: ` +
+                `${Object.keys(presets).join(", ")}) — entry ignored.`);
+            return undefined;
+        }
+    }
+    return parseProtocolFields(r, routeLabel, warnings, base);
+}
+export function parseProtocolFields(r, routeLabel, warnings, base) {
+    const args = stringArrayFrom(r.args) ?? base?.args;
+    if (args === undefined) {
+        warnings.push(`${routeLabel}: protocol.args is required — entry ignored.`);
+        return undefined;
+    }
+    const outputRaw = r.output;
+    let output = base?.output;
+    if (outputRaw !== undefined) {
+        if (outputRaw === null || typeof outputRaw !== "object") {
+            warnings.push(`${routeLabel}: protocol.output must be an object — entry ignored.`);
+            return undefined;
+        }
+        const o = outputRaw;
+        if (o.mode !== "text" && o.mode !== "json_field" && o.mode !== "jsonl_stream") {
+            warnings.push(`${routeLabel}: protocol.output.mode must be one of text | json_field | jsonl_stream — entry ignored.`);
+            return undefined;
+        }
+        output = { mode: o.mode };
+        const fields = stringArrayFrom(o.fields);
+        if (fields !== undefined)
+            output.fields = fields;
+        const usageRaw = o.usage;
+        if (usageRaw !== null && typeof usageRaw === "object") {
+            const u = usageRaw;
+            const input = stringArrayFrom(u.input);
+            const outputTokens = stringArrayFrom(u.output);
+            if (input !== undefined && outputTokens !== undefined)
+                output.usage = { input, output: outputTokens };
+        }
+        const eventRulesRaw = o.event_rules;
+        if (Array.isArray(eventRulesRaw)) {
+            const eventRules = [];
+            for (const [i, ruleRaw] of eventRulesRaw.entries()) {
+                const rule = eventRuleFrom(ruleRaw, `${routeLabel}: protocol.output.event_rules[${i}]`, warnings);
+                if (rule)
+                    eventRules.push(rule);
+            }
+            if (eventRules.length > 0)
+                output.eventRules = eventRules;
+        }
+        const errorRaw = o.error;
+        if (errorRaw !== null && typeof errorRaw === "object") {
+            const e = errorRaw;
+            const field = str(e.field);
+            if (field !== undefined) {
+                const messageFields = stringArrayFrom(e.message_fields);
+                output.error = messageFields !== undefined ? { field, messageFields } : { field };
+            }
+            else {
+                warnings.push(`${routeLabel}: protocol.output.error.field is required — error detection ignored.`);
+            }
+        }
+    }
+    if (output === undefined) {
+        warnings.push(`${routeLabel}: protocol.output is required — entry ignored.`);
+        return undefined;
+    }
+    const protocol = { args, output };
+    const stdin = typeof r.stdin === "boolean" ? r.stdin : base?.stdin;
+    if (stdin !== undefined)
+        protocol.stdin = stdin;
+    const modelRaw = r.model;
+    if (modelRaw !== undefined && modelRaw !== null) {
+        const m = modelRaw;
+        if (typeof m.flag === "string" && m.flag) {
+            protocol.model = { flag: m.flag };
+        }
+        else {
+            warnings.push(`${routeLabel}: protocol.model set but missing a "flag" string — ignored.`);
+        }
+    }
+    else if (base?.model) {
+        protocol.model = base.model;
+    }
+    const workingDirRaw = r.working_dir;
+    if (workingDirRaw !== undefined && workingDirRaw !== null) {
+        const wd = workingDirRaw;
+        if (typeof wd.flag === "string" && wd.flag) {
+            protocol.workingDir = { flag: wd.flag };
+            const extraArgsWhenSet = stringArrayFrom(wd.extra_args_when_set);
+            if (extraArgsWhenSet !== undefined)
+                protocol.workingDir.extraArgsWhenSet = extraArgsWhenSet;
+            if (wd.fallback === "home")
+                protocol.workingDir.fallback = "home";
+        }
+        else {
+            warnings.push(`${routeLabel}: protocol.working_dir set but missing a "flag" string — ignored.`);
+        }
+    }
+    else if (base?.workingDir) {
+        protocol.workingDir = base.workingDir;
+    }
+    const fileDirsRaw = r.file_dirs;
+    if (fileDirsRaw !== undefined && fileDirsRaw !== null) {
+        const fd = fileDirsRaw;
+        if (typeof fd.flag === "string" && fd.flag) {
+            protocol.fileDirs = { flag: fd.flag };
+        }
+        else {
+            warnings.push(`${routeLabel}: protocol.file_dirs set but missing a "flag" string — ignored.`);
+        }
+    }
+    else if (base?.fileDirs) {
+        protocol.fileDirs = base.fileDirs;
+    }
+    const fileListHeader = str(r.file_list_header) ?? base?.fileListHeader;
+    if (fileListHeader !== undefined)
+        protocol.fileListHeader = fileListHeader;
+    const fileListBullet = (typeof r.file_list_bullet === "string" ? r.file_list_bullet : undefined) ?? base?.fileListBullet;
+    if (fileListBullet !== undefined)
+        protocol.fileListBullet = fileListBullet;
+    const apiKeyEnvVar = str(r.api_key_env_var) ?? base?.apiKeyEnvVar;
+    if (apiKeyEnvVar !== undefined)
+        protocol.apiKeyEnvVar = apiKeyEnvVar;
+    const safetyRaw = r.safety;
+    const safety = { ...base?.safety };
+    if (safetyRaw !== null && typeof safetyRaw === "object") {
+        for (const profile of SAFETY_PROFILES) {
+            const profileArgs = stringArrayFrom(safetyRaw[profile]);
+            if (profileArgs !== undefined)
+                safety[profile] = profileArgs;
+        }
+    }
+    if (Object.keys(safety).length > 0)
+        protocol.safety = safety;
+    if (typeof r.success_requires_output === "boolean") {
+        protocol.successRequiresOutput = r.success_requires_output;
+    }
+    else if (base?.successRequiresOutput !== undefined) {
+        protocol.successRequiresOutput = base.successRequiresOutput;
+    }
+    const endpointNativeArgsRaw = r.endpoint_native_args;
+    if (endpointNativeArgsRaw !== null && typeof endpointNativeArgsRaw === "object") {
+        const ena = {};
+        for (const [k, v] of Object.entries(endpointNativeArgsRaw)) {
+            const args2 = stringArrayFrom(v);
+            if (args2 !== undefined)
+                ena[k] = args2;
+        }
+        if (Object.keys(ena).length > 0)
+            protocol.endpointNativeArgs = ena;
+    }
+    else if (base?.endpointNativeArgs) {
+        protocol.endpointNativeArgs = base.endpointNativeArgs;
+    }
+    // Placeholder sanity checks on the FINAL merged args (so `extends:` results
+    // are covered too). A typo'd placeholder is the most likely user error in a
+    // hand-written protocol, and without these warnings it doesn't just fail
+    // silently — it "succeeds": the CLI receives the literal "{{promt}}" token,
+    // never receives the prompt, exits 0, and the run reports ok.
+    // Matches embedded forms too ("--flag={{prompt}}"), not just whole-token
+    // typos — expansion only ever substitutes a token that IS a placeholder,
+    // so anything merely containing one goes through literally.
+    for (const token of protocol.args) {
+        if (token.includes("{{") && !KNOWN_ARG_PLACEHOLDERS.has(token)) {
+            warnings.push(`${routeLabel}: protocol.args contains unrecognized placeholder "${token}" — it will be ` +
+                `passed to the CLI as a literal argument, not substituted. Placeholders only work as ` +
+                `a whole standalone argument. Known placeholders: ` +
+                `${[...KNOWN_ARG_PLACEHOLDERS].join(", ")}.`);
+        }
+    }
+    if (!protocol.stdin && !protocol.args.includes("{{prompt}}")) {
+        warnings.push(`${routeLabel}: protocol.args has no {{prompt}} placeholder and stdin is not true — ` +
+            `the prompt is never sent to the CLI. Add "{{prompt}}" to args, or set stdin: true.`);
+    }
+    return protocol;
+}
+export function eventRuleFrom(raw, label, warnings) {
+    if (raw === null || typeof raw !== "object") {
+        warnings.push(`${label}: must be an object — ignored.`);
+        return undefined;
+    }
+    const r = raw;
+    // "when" is optional — omitted or {} means "matches every line" (e.g. a
+    // usage rule that should fire regardless of event type, matching Codex's
+    // original unconditional `if (event.usage) {...}` check).
+    const whenRaw = r.when ?? {};
+    if (whenRaw === null || typeof whenRaw !== "object" || Array.isArray(whenRaw)) {
+        warnings.push(`${label}: "when" must be a {field: value} map — ignored.`);
+        return undefined;
+    }
+    const when = {};
+    for (const [k, v] of Object.entries(whenRaw)) {
+        if (typeof v === "string")
+            when[k] = v;
+    }
+    const emit = r.emit;
+    if (emit !== "text" &&
+        emit !== "tool_use" &&
+        emit !== "thinking" &&
+        emit !== "usage" &&
+        emit !== "error") {
+        warnings.push(`${label}: "emit" must be one of text | tool_use | thinking | usage | error — ignored.`);
+        return undefined;
+    }
+    const rule = { when, emit };
+    const textField = str(r.text_field);
+    if (textField !== undefined)
+        rule.textField = textField;
+    const nameField = str(r.name_field);
+    if (nameField !== undefined)
+        rule.nameField = nameField;
+    const inputField = str(r.input_field);
+    if (inputField !== undefined)
+        rule.inputField = inputField;
+    const chunkField = str(r.chunk_field);
+    if (chunkField !== undefined)
+        rule.chunkField = chunkField;
+    const inputTokenFields = stringArrayFrom(r.input_token_fields);
+    if (inputTokenFields !== undefined)
+        rule.inputTokenFields = inputTokenFields;
+    const outputTokenFields = stringArrayFrom(r.output_token_fields);
+    if (outputTokenFields !== undefined)
+        rule.outputTokenFields = outputTokenFields;
+    const messageField = str(r.message_field);
+    if (messageField !== undefined)
+        rule.messageField = messageField;
+    return rule;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/config/protocol.js.map

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

package/dist/config/validation.d.ts

@@ -0,0 +1,72 @@
+/**
+ * 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 declare const FAIL_OPEN_ENUMS: Record<string, readonly string[]>;
+/**
+ * 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 declare const KNOWN_TOP_LEVEL_KEYS: Set<string>;
+/**
+ * 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 declare const KNOWN_ROUTE_KEYS: Set<string>;
+export declare function warnUnknownRouteKeys(entry: Record<string, unknown>, label: string, warnings: string[]): void;
+export declare function warnUnknownTopLevelKeys(raw: Record<string, unknown>, warnings: string[]): void;
+export declare function warnUnknownSafetyEnums(node: unknown, warnings: string[], where?: string): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/config/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/config/validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAsB7D,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,aAiB/B,CAAC;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,gBAAgB,aAU3B,CAAC;AAEH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAAE,GACjB,IAAI,CAQN;AAeD,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,IAAI,CAgB9F;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,EAAE,KAAK,SAAK,GAAG,IAAI,CAqC1F"}

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",
+    "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;AAyBH,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;AAgrBF,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"}