@boyingliu01/xp-gate 0.31.3 → 0.32.0

package/plugins/dsh/lib/credentials.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Resolve the API key that a Delphi provider config points at, without assuming the
+ * value is in this process's environment.
+ *
+ * The credential service shipped with DSH layers environment, a provider-managed
+ * store, and `.env` files behind one `CredentialRef`. That is exactly the order the
+ * plugin needs: on the machine that prompted this work the key lived in a user-level
+ * environment variable and in `~/.dsh/.credentials.yaml`, while DSH's own process
+ * inherited neither — so `delphi-review` failed with a missing-variable error while
+ * every other gate worked.
+ *
+ * Resolution is deliberately single-layer. When `ctx.credentials` is present and
+ * reports `undefined`, this module does NOT fall back to `process.env`: the service
+ * has already consulted the environment, so a second look would resurrect a value it
+ * deliberately reported as absent and would make a DSH session resolve differently
+ * from a terminal session.
+ */
+/** A credential service, narrowed to the one method this module needs. */
+export interface CredentialService {
+    resolve(ref: unknown): Promise<{
+        value: string;
+    } | undefined>;
+}
+/** Resolve one environment-variable-style reference to its current value. */
+export type ApiKeyResolver = (ref: string) => Promise<string | undefined>;
+/**
+ * Build an `ApiKeyResolver` over the available credential service.
+ *
+ * @param credentials - `ctx.credentials`, or undefined when the host does not offer
+ *   one. Absence degrades to reading the process environment directly, which keeps
+ *   the plugin working outside DSH (CLI use, tests).
+ * @param env - environment to read in that fallback. Injected rather than read from
+ *   the global so the module stays testable offline.
+ * @param brand - converts a raw name into the service's nominal `CredentialRef`.
+ *   Injected so this module needs no import of the peer package and tests can pass
+ *   an identity function.
+ */
+export declare function createCredentialResolver(credentials: CredentialService | undefined, env: NodeJS.ProcessEnv, brand?: (value: string) => unknown): ApiKeyResolver;
+//# sourceMappingURL=credentials.d.ts.map

package/plugins/dsh/lib/credentials.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.d.ts","sourceRoot":"","sources":["../src/credentials.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAA;CAC9D;AAED,6EAA6E;AAC7E,MAAM,MAAM,cAAc,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;AAYzE;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CACtC,WAAW,EAAE,iBAAiB,GAAG,SAAS,EAC1C,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,KAAK,GAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAA0B,GACnD,cAAc,CAkBhB"}

package/plugins/dsh/lib/credentials.js

@@ -0,0 +1,57 @@
+/**
+ * Resolve the API key that a Delphi provider config points at, without assuming the
+ * value is in this process's environment.
+ *
+ * The credential service shipped with DSH layers environment, a provider-managed
+ * store, and `.env` files behind one `CredentialRef`. That is exactly the order the
+ * plugin needs: on the machine that prompted this work the key lived in a user-level
+ * environment variable and in `~/.dsh/.credentials.yaml`, while DSH's own process
+ * inherited neither — so `delphi-review` failed with a missing-variable error while
+ * every other gate worked.
+ *
+ * Resolution is deliberately single-layer. When `ctx.credentials` is present and
+ * reports `undefined`, this module does NOT fall back to `process.env`: the service
+ * has already consulted the environment, so a second look would resurrect a value it
+ * deliberately reported as absent and would make a DSH session resolve differently
+ * from a terminal session.
+ */
+/**
+ * Environment-variable names: a POSIX shell identifier. Anything else cannot name a
+ * credential, so it reads as "not set" rather than reaching the store.
+ */
+const REFERENCE_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function isReferenceName(value) {
+    return REFERENCE_NAME.test(value);
+}
+/**
+ * Build an `ApiKeyResolver` over the available credential service.
+ *
+ * @param credentials - `ctx.credentials`, or undefined when the host does not offer
+ *   one. Absence degrades to reading the process environment directly, which keeps
+ *   the plugin working outside DSH (CLI use, tests).
+ * @param env - environment to read in that fallback. Injected rather than read from
+ *   the global so the module stays testable offline.
+ * @param brand - converts a raw name into the service's nominal `CredentialRef`.
+ *   Injected so this module needs no import of the peer package and tests can pass
+ *   an identity function.
+ */
+export function createCredentialResolver(credentials, env, brand = (value) => value) {
+    return async (ref) => {
+        if (!isReferenceName(ref))
+            return undefined;
+        if (credentials !== undefined) {
+            try {
+                const resolved = await credentials.resolve(brand(ref));
+                return resolved?.value;
+            }
+            catch {
+                // A broken provider must not take the tool down; the caller turns the
+                // missing value into a DelphiSetupError that names the variable.
+                return undefined;
+            }
+        }
+        const value = env[ref];
+        return typeof value === "string" && value.length > 0 ? value : undefined;
+    };
+}
+//# sourceMappingURL=credentials.js.map

package/plugins/dsh/lib/delphi-config.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Delphi configuration loading for the DSH plugin.
+ *
+ * Reads the same `.delphi-config.json` the xp-gate skill already uses, so a
+ * project configures its reviewers once and both the skill and the DSH tool
+ * agree on who they are.
+ *
+ * @test REQ-DSH-016
+ * @intent 复用项目既有的 .delphi-config.json，把 provider/api_key/专家席位解析成
+ *         DSH 工具可用的结构，并对 ${ENV} 占位符与缺失密钥给出可操作的报错。
+ * @covers AC-DSH-016-02
+ */
+import type { ExpertSeat, DelphiOptions } from "./delphi.js";
+/** Shape of one expert entry in .delphi-config.json. */
+interface RawExpert {
+    id?: string;
+    role?: string;
+    name?: string;
+    model?: string;
+    requested_model?: string;
+    max_tokens?: number;
+    maxTokens?: number;
+    /** Per-expert provider override; falls back to the profile default. */
+    provider?: string;
+}
+interface RawProfile {
+    provider?: string;
+    providers?: Record<string, {
+        base_url?: string;
+        baseUrl?: string;
+        api_key?: string;
+        apiKey?: string;
+    }>;
+    /**
+     * Experts appear in two shapes in the wild: an object keyed by role (what
+     * xp-gate actually writes) and an array. Both are accepted.
+     */
+    experts?: RawExpert[] | Record<string, RawExpert>;
+    consensus?: {
+        threshold_percent?: number;
+        max_review_rounds?: number;
+    };
+}
+export interface RawDelphiConfig extends RawProfile {
+    active_profile?: string;
+    profiles?: Record<string, RawProfile>;
+}
+export interface ResolvedDelphiConfig {
+    readonly seats: ExpertSeat[];
+    readonly baseUrl: string;
+    readonly apiKey: string;
+    readonly thresholdPercent: number;
+    readonly maxRounds: number;
+    readonly provider: string;
+}
+/** Raised when config on disk cannot be turned into a usable review setup. */
+export declare class DelphiSetupError extends Error {
+}
+/**
+ * The result of expanding a config value: the expanded text plus what could not
+ * be resolved, kept apart by REASON.
+ *
+ * `missing` and `empty` are different problems with different remedies, so they
+ * are separate lists rather than one "did not expand" bucket (#576):
+ *   missing — nobody set it: fix the environment (and, on a long-lived host,
+ *             restart the process that needs to inherit it)
+ *   empty   — someone set it to "": fix the configuration
+ */
+export interface ExpandedEnv {
+    readonly value: string;
+    readonly missing: readonly string[];
+    readonly empty: readonly string[];
+}
+/**
+ * Expand `${VAR}` / `{env:VAR}` without collapsing "unset" into "empty".
+ * Supports the two spellings already present in xp-gate config files.
+ */
+export declare function expandEnvDetailed(value: string, env?: NodeJS.ProcessEnv): ExpandedEnv;
+/**
+ * Expand `${VAR}` and `{env:VAR}` placeholders from the environment.
+ * Supports the two spellings already present in xp-gate config files.
+ *
+ * Kept for callers that only need the text; use {@link expandEnvDetailed} when
+ * the difference between "unset" and "set to empty" matters.
+ */
+export declare function expandEnv(value: string, env?: NodeJS.ProcessEnv): string;
+/**
+ * Turn raw config into a ready-to-run review setup.
+ * Fails loudly and specifically: a missing key or an unexpanded placeholder is
+ * the most common way a Delphi run silently degrades.
+ */
+export declare function resolveConfig(cfg: RawDelphiConfig, env?: NodeJS.ProcessEnv, apiKeyOverrides?: ApiKeyOverrides): ResolvedDelphiConfig;
+/**
+ * Default global config location; XDG_CONFIG_HOME is an accepted override.
+ *
+ * Exported so the Gate MW validator's parity test can import THIS definition
+ * rather than restating it (2026-10-27 review, technical seat CRITICAL): the
+ * gate (`githooks/lib/validate-code-walkthrough.cjs`) needs the same path, and
+ * a second hand-written copy can drift silently. Drift here is not cosmetic —
+ * the gate would validate seats from one file while the reviewer used another,
+ * which is exactly the class of bug #574 exists to catch.
+ */
+export declare function defaultGlobalConfigPath(env: NodeJS.ProcessEnv): string;
+/**
+ * Pre-resolved credential values, keyed by the environment-variable name a config
+ * referenced.
+ *
+ * The loader is synchronous and the DSH credential service is asynchronous, so a
+ * caller that resolved a key from the store hands the result in here. The override
+ * is intentionally keyed by name: a config whose `api_key` is a literal, or which
+ * names a different variable, is left untouched.
+ */
+type ApiKeyOverrides = Readonly<Record<string, string>>;
+/**
+ * List the environment-variable names the config's provider api_keys reference,
+ * WITHOUT resolving any of them.
+ *
+ * `loadDelphiConfig` is synchronous while DSH's credential service is asynchronous,
+ * so the caller has to learn what to resolve before it can build the config. Reading
+ * the names is deliberately tolerant: an unset variable is exactly the case this
+ * exists for, so a name is reported whether or not it currently has a value, and a
+ * missing config yields an empty list instead of an error.
+ */
+export declare function listCredentialReferences(cwd: string, globalPath?: string): string[];
+export declare function loadDelphiConfig(cwd: string, env?: NodeJS.ProcessEnv, globalPath?: string, apiKeyOverrides?: ApiKeyOverrides): ResolvedDelphiConfig;
+/** Build the transport options a round needs from a resolved config. */
+export declare function toDelphiOptions(cfg: ResolvedDelphiConfig): DelphiOptions;
+export {};
+//# sourceMappingURL=delphi-config.d.ts.map

package/plugins/dsh/lib/delphi-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delphi-config.d.ts","sourceRoot":"","sources":["../src/delphi-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAG5D,wDAAwD;AACxD,UAAU,SAAS;IACjB,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,UAAU,UAAU;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACtG;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IACjD,SAAS,CAAC,EAAE;QAAE,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CACvE;AAED,MAAM,WAAW,eAAgB,SAAQ,UAAU;IACjD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;CACtC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,UAAU,EAAE,CAAA;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAC1B;AAED,8EAA8E;AAC9E,qBAAa,gBAAiB,SAAQ,KAAK;CAAG;AAoB9C;;;;;;;;;GASG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAClC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,WAAW,CAmBb;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAErF;AAmLD;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,eAAe,EACpB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,eAAe,GAAE,eAAoB,GACpC,oBAAoB,CAuBtB;AAwCD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAItE;AAED;;;;;;;;GAQG;AACH,KAAK,eAAe,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AAoCvD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EACX,UAAU,GAAE,MAA6C,GACxD,MAAM,EAAE,CAoBV;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,UAAU,GAAE,MAAqC,EACjD,eAAe,GAAE,eAAoB,GACpC,oBAAoB,CAetB;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,GAAG,EAAE,oBAAoB,GAAG,aAAa,CAQxE"}

package/plugins/dsh/lib/delphi-config.js

@@ -0,0 +1,369 @@
+/**
+ * Delphi configuration loading for the DSH plugin.
+ *
+ * Reads the same `.delphi-config.json` the xp-gate skill already uses, so a
+ * project configures its reviewers once and both the skill and the DSH tool
+ * agree on who they are.
+ *
+ * @test REQ-DSH-016
+ * @intent 复用项目既有的 .delphi-config.json，把 provider/api_key/专家席位解析成
+ *         DSH 工具可用的结构，并对 ${ENV} 占位符与缺失密钥给出可操作的报错。
+ * @covers AC-DSH-016-02
+ */
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { validateSeats } from "./delphi.js";
+/** Raised when config on disk cannot be turned into a usable review setup. */
+export class DelphiSetupError extends Error {
+}
+/**
+ * Delphi's documented defaults, applied when the config omits a consensus setting.
+ * Held as object properties so the values read as policy fields rather than stray
+ * literals.
+ */
+const CONSENSUS_DEFAULTS = {
+    threshold_percent: "90",
+    max_review_rounds: "5",
+};
+/** Placeholder spellings xp-gate configs already use. Named so the error text can
+ *  quote the exact form the user wrote — a typo in the spelling is
+ *  indistinguishable from an unset variable otherwise (#576). */
+const PLACEHOLDER_PATTERNS = [
+    { form: "shell", re: /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g },
+    { form: "env", re: /\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g },
+];
+/**
+ * Expand `${VAR}` / `{env:VAR}` without collapsing "unset" into "empty".
+ * Supports the two spellings already present in xp-gate config files.
+ */
+export function expandEnvDetailed(value, env = process.env) {
+    const missing = [];
+    const empty = [];
+    let out = value;
+    for (const { re } of PLACEHOLDER_PATTERNS) {
+        out = out.replace(re, (_m, name) => {
+            const found = env[name];
+            if (found === undefined) {
+                if (!missing.includes(name))
+                    missing.push(name);
+                return "";
+            }
+            if (found === "") {
+                if (!empty.includes(name))
+                    empty.push(name);
+                return "";
+            }
+            return found;
+        });
+    }
+    return { value: out, missing, empty };
+}
+/**
+ * Expand `${VAR}` and `{env:VAR}` placeholders from the environment.
+ * Supports the two spellings already present in xp-gate config files.
+ *
+ * Kept for callers that only need the text; use {@link expandEnvDetailed} when
+ * the difference between "unset" and "set to empty" matters.
+ */
+export function expandEnv(value, env = process.env) {
+    return expandEnvDetailed(value, env).value;
+}
+/** Pick the active profile, falling back to the top level. */
+function selectProfile(cfg) {
+    const active = cfg.active_profile;
+    if (active && cfg.profiles?.[active])
+        return cfg.profiles[active];
+    if (cfg.profiles && Object.keys(cfg.profiles).length > 0) {
+        throw new DelphiSetupError(`No active_profile set. Available: ${Object.keys(cfg.profiles).join(", ")}`);
+    }
+    return cfg;
+}
+function seatFromRaw(raw, index, fallbackRole) {
+    const model = raw.model ?? raw.requested_model ?? "";
+    return {
+        id: raw.id ?? raw.name ?? `Expert ${String.fromCharCode(65 + index)}`,
+        role: raw.role ?? fallbackRole,
+        model,
+        maxTokens: raw.max_tokens ?? raw.maxTokens,
+    };
+}
+/** Normalize either experts shape into an ordered list with roles attached. */
+function normalizeExperts(experts) {
+    if (!experts)
+        return [];
+    if (Array.isArray(experts)) {
+        return experts.map((raw, i) => ({ raw, role: raw.role ?? `expert${i}` }));
+    }
+    // Object form: the KEY is the role, which is how xp-gate writes it.
+    return Object.entries(experts).map(([role, raw]) => ({ raw, role }));
+}
+/** Resolve one provider's base_url + api_key, failing loudly. */
+function resolveOneProvider(name, entry, env, apiKeyOverrides) {
+    const baseUrl = entry.base_url ?? entry.baseUrl ?? "";
+    if (!baseUrl)
+        throw new DelphiSetupError(`Provider "${name}" has no base_url.`);
+    const rawKey = entry.api_key ?? entry.apiKey ?? "";
+    // Find the placeholder BEFORE touching `env`: the spelling lives in the
+    // config, not the environment, so a broken `env` must not hide it.
+    const placeholder = findPlaceholder(rawKey);
+    // A caller that already resolved this variable from the authoritative store
+    // (DSH's credential service) wins over the process environment: the store is
+    // layered over env itself, so its answer is the more informed one. A literal
+    // api_key names no variable and is therefore untouched.
+    const overrideValue = placeholder ? apiKeyOverrides[placeholder.name] : undefined;
+    // Every read of `env` may fail — a caller can pass a proxy, a frozen object,
+    // or an environment that throws on access. Diagnostics must never become the
+    // reason the run dies: on any error fall back to the plainest possible
+    // message, which is still a DelphiSetupError (#576).
+    let expanded;
+    try {
+        expanded = expandEnvDetailed(rawKey, env);
+    }
+    catch {
+        expanded = { value: "", missing: placeholder ? [placeholder.name] : [], empty: [] };
+    }
+    const apiKey = overrideValue ?? expanded.value;
+    if (!apiKey) {
+        // Name the variable rather than echoing config, which may hold a literal key.
+        throw new DelphiSetupError(placeholder
+            ? describeUnusableKey(name, rawKey, placeholder, expanded, env)
+            : `Provider "${name}" has no api_key.`);
+    }
+    return { baseUrl, apiKey };
+}
+/** Resolve every referenced provider's base_url + api_key, failing loudly. */
+function resolveProviders(profile, needed, env, apiKeyOverrides) {
+    if (needed.size === 0) {
+        throw new DelphiSetupError('No provider configured. Set "provider" on the profile or on each expert.');
+    }
+    const providerTable = profile.providers ?? {};
+    const resolved = new Map();
+    for (const name of needed) {
+        const entry = providerTable[name];
+        if (!entry) {
+            throw new DelphiSetupError(`Provider "${name}" is not defined under "providers". ` +
+                `Known: ${Object.keys(providerTable).join(", ") || "(none)"}`);
+        }
+        resolved.set(name, resolveOneProvider(name, entry, env, apiKeyOverrides));
+    }
+    return resolved;
+}
+/** Locate the first placeholder in a config value, keeping both name and spelling. */
+function findPlaceholder(rawKey) {
+    for (const { re } of PLACEHOLDER_PATTERNS) {
+        // Fresh lastIndex each call: the shared regexes are global.
+        re.lastIndex = 0;
+        const match = re.exec(rawKey);
+        if (match)
+            return { name: match[1], spelling: match[0] };
+    }
+    return null;
+}
+/** Env keys whose name matches case-insensitively. Never throws: a hostile or
+ *  partially-broken `env` must not turn diagnostics into the failure (#576). */
+function caseVariantsOf(name, env) {
+    try {
+        const lower = name.toLowerCase();
+        return Object.keys(env).filter((k) => k !== name && k.toLowerCase() === lower);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Build the message for a provider whose api_key did not expand to anything.
+ *
+ * The old text asserted "is not set in the environment" for every failure. That
+ * is a factual claim the caller cannot make from an expanded string alone: an
+ * empty result also happens when the variable IS set — to "", or set in a
+ * place this process never inherited (a long-lived host whose parent started
+ * before the variable was written; a shell that never reloaded; a systemd unit
+ * without restart; a container created without `-e`). The reader was sent to
+ * check the key, the config, and the gateway — everything except the parent
+ * process environment (#576).
+ */
+function describeUnusableKey(providerName, rawKey, placeholder, expanded, env) {
+    const { name, spelling } = placeholder;
+    const lines = [];
+    if (expanded.empty.includes(name)) {
+        lines.push(`API key variable ${name} is empty in the environment.`, `Provider "${providerName}" uses ${spelling} in its api_key.`, "The variable is defined but has no value — this is usually a configuration error.", `Set ${name} to a non-empty value.`);
+    }
+    else {
+        lines.push(`API key variable ${name} is not set in the environment.`, `Provider "${providerName}" uses ${spelling} in its api_key.`);
+        const variants = caseVariantsOf(name, env);
+        if (variants.length > 0) {
+            lines.push(`Note: the environment has a variable whose name differs only in case: ` +
+                `${variants.join(", ")}. Environment variable names are case-sensitive on ` +
+                "POSIX systems, so ${name} does not match it.");
+        }
+        lines.push(`Set ${name} and restart the process that reads it. If you already set it, ` +
+            "a long-running parent may still be holding the environment it started " +
+            "with — the variable is inherited once at process start and not refreshed.");
+    }
+    if (!rawKey.includes("${") && !rawKey.includes("{env:")) {
+        // Reached only when the value expanded to "" from a literal; say so instead
+        // of naming a variable that is not referenced.
+        lines.push(`The configured api_key is a literal value and expands to an empty string.`);
+    }
+    return lines.join(" ");
+}
+/**
+ * Turn raw config into a ready-to-run review setup.
+ * Fails loudly and specifically: a missing key or an unexpanded placeholder is
+ * the most common way a Delphi run silently degrades.
+ */
+export function resolveConfig(cfg, env = process.env, apiKeyOverrides = {}) {
+    const profile = selectProfile(cfg);
+    const normalized = normalizeExperts(profile.experts);
+    // An expert may name its own provider; otherwise there must be a profile-wide
+    // default. Resolve base_url/api_key per provider so mixed setups work.
+    const providerNames = new Set(normalized.map((e) => e.raw.provider ?? profile.provider).filter((p) => !!p));
+    const resolvedProviders = resolveProviders(profile, providerNames, env, apiKeyOverrides);
+    const seats = normalized.map((e, i) => seatFromRaw(e.raw, i, e.role));
+    // Surface an unexpanded placeholder as a config error, not a provider 404.
+    for (const s of seats) {
+        if (s.model.includes("${") || s.model.includes("{env:")) {
+            throw new DelphiSetupError(`Expert "${s.id}" model "${s.model}" is an unexpanded placeholder.`);
+        }
+    }
+    validateSeats(seats);
+    return buildResult(profile, normalized, resolvedProviders, seats, cfg);
+}
+/** Assemble the final result after seats and providers validated. */
+function buildResult(profile, normalized, resolvedProviders, seats, cfg) {
+    // All seats share one gateway in the supported setup; require agreement so a
+    // mixed list cannot silently send one seat's key to another host.
+    // Every seat resolves to the same gateway, so the first one speaks for all.
+    const [firstSeat] = normalized;
+    const chosen = resolvedProviders.get(firstSeat?.raw.provider ?? profile.provider ?? "");
+    if (!chosen)
+        throw new DelphiSetupError("Unable to resolve a provider for the first expert.");
+    for (const e of normalized) {
+        const name = e.raw.provider ?? profile.provider ?? "";
+        const other = resolvedProviders.get(name);
+        if (!other || other.baseUrl !== chosen.baseUrl) {
+            throw new DelphiSetupError(`All experts must share one gateway base_url; "${name}" differs. ` +
+                `Split the review or align the providers.`);
+        }
+    }
+    // consensus may sit on the profile or at the document root; both occur.
+    const consensus = profile.consensus ?? cfg.consensus;
+    return {
+        seats,
+        baseUrl: chosen.baseUrl,
+        apiKey: chosen.apiKey,
+        thresholdPercent: consensus?.threshold_percent ?? Number(CONSENSUS_DEFAULTS.threshold_percent),
+        maxRounds: consensus?.max_review_rounds ?? Number(CONSENSUS_DEFAULTS.max_review_rounds),
+        provider: normalized[0].raw.provider ?? profile.provider ?? "",
+    };
+}
+/**
+ * Default global config location; XDG_CONFIG_HOME is an accepted override.
+ *
+ * Exported so the Gate MW validator's parity test can import THIS definition
+ * rather than restating it (2026-10-27 review, technical seat CRITICAL): the
+ * gate (`githooks/lib/validate-code-walkthrough.cjs`) needs the same path, and
+ * a second hand-written copy can drift silently. Drift here is not cosmetic —
+ * the gate would validate seats from one file while the reviewer used another,
+ * which is exactly the class of bug #574 exists to catch.
+ */
+export function defaultGlobalConfigPath(env) {
+    // r16 MA-01 disposition: the CLI lib pins ~/.config/xp-gate, and on Linux
+    // $HOME/.config IS the XDG default — opt-in escape hatch only.
+    return join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "xp-gate", ".delphi-config.json");
+}
+/** Read and resolve `.delphi-config.json` from a project root. */
+/** Read the raw config text from the project path, falling back to the global one. */
+function readConfigText(cwd, globalPath) {
+    // Global fallback (AC-DSH-016-03): the machine-wide config at
+    // ~/.config/xp-gate/.delphi-config.json is the single source of truth for
+    // every project. Without it, each repo needed its own copy — and reading a
+    // stale or differently-priced config from another project's directory caused
+    // real money loss (2026-10-03: an expensive overseas model burned the daily
+    // quota). A project-local config still wins, so per-project overrides work.
+    const path = resolve(cwd, ".delphi-config.json");
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (projectError) {
+        // Fall back ONLY when the project file is genuinely absent (ENOENT); any
+        // other read error must surface rather than silently route this run to
+        // another config. Same semantics as delphi-external-review.cjs, which
+        // gates the fallback on existsSync (walkthrough R8 MA-01).
+        if (projectError?.code !== "ENOENT") {
+            throw new DelphiSetupError(`Cannot read ${path}: ${projectError.message}`);
+        }
+    }
+    try {
+        return readFileSync(globalPath, "utf8");
+    }
+    catch (globalError) {
+        // r16 CI-01: mirror the project-read semantics — a global file that is
+        // absent means "no config anywhere"; any OTHER error (EACCES/EISDIR)
+        // must surface as-is rather than masquerade as a missing file.
+        if (globalError?.code !== "ENOENT") {
+            throw new DelphiSetupError(`Cannot read ${globalPath}: ${globalError.message}`);
+        }
+        return null;
+    }
+}
+/**
+ * List the environment-variable names the config's provider api_keys reference,
+ * WITHOUT resolving any of them.
+ *
+ * `loadDelphiConfig` is synchronous while DSH's credential service is asynchronous,
+ * so the caller has to learn what to resolve before it can build the config. Reading
+ * the names is deliberately tolerant: an unset variable is exactly the case this
+ * exists for, so a name is reported whether or not it currently has a value, and a
+ * missing config yields an empty list instead of an error.
+ */
+export function listCredentialReferences(cwd, globalPath = defaultGlobalConfigPath(process.env)) {
+    const raw = readConfigText(cwd, globalPath);
+    if (raw === null)
+        return [];
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        // A malformed config is reported by loadDelphiConfig with an actionable
+        // message; there is simply nothing to resolve here.
+        return [];
+    }
+    const names = new Set();
+    for (const profile of Object.values(parsed.profiles ?? {})) {
+        for (const provider of Object.values(profile.providers ?? {})) {
+            const placeholder = findPlaceholder(provider.api_key ?? provider.apiKey ?? "");
+            if (placeholder)
+                names.add(placeholder.name);
+        }
+    }
+    return [...names].sort();
+}
+export function loadDelphiConfig(cwd, env = process.env, globalPath = defaultGlobalConfigPath(env), apiKeyOverrides = {}) {
+    const raw = readConfigText(cwd, globalPath);
+    if (raw === null) {
+        const path = resolve(cwd, ".delphi-config.json");
+        throw new DelphiSetupError(`No .delphi-config.json found at ${path} or the global location ${globalPath}.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new DelphiSetupError(`.delphi-config.json is not valid JSON: ${e.message}`);
+    }
+    return resolveConfig(parsed, env, apiKeyOverrides);
+}
+/** Build the transport options a round needs from a resolved config. */
+export function toDelphiOptions(cfg) {
+    return {
+        baseUrl: cfg.baseUrl,
+        apiKey: cfg.apiKey,
+        seats: cfg.seats,
+        thresholdPercent: cfg.thresholdPercent,
+        maxRounds: cfg.maxRounds,
+    };
+}
+//# sourceMappingURL=delphi-config.js.map

package/plugins/dsh/lib/delphi-run.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Delphi review orchestration: iterate rounds until consensus or the cap.
+ *
+ * @test REQ-DSH-016
+ * @intent 编排多轮交叉评审：首轮匿名独立评审，后续轮次反馈上一轮汇总，
+ *         直到达到共识阈值（默认 90%）或触及轮次上限（默认 5），
+ *         并把结果整理成可写成 .code-walkthrough-result.json 的证据。
+ * @covers AC-DSH-016-03
+ */
+import type { DelphiOptions, RoundResult } from "./delphi.js";
+export interface ReviewOutcome {
+    readonly rounds: readonly RoundResult[];
+    readonly consensus: boolean;
+    readonly finalRatio: number;
+    readonly totalRounds: number;
+}
+/**
+ * Run a full review. Round 1 is anonymous; each later round sees the aggregate
+ * plus whatever the caller says was addressed, then re-votes.
+ */
+export declare function runReview(opts: DelphiOptions, subject: string, addressed?: string, signal?: AbortSignal): Promise<ReviewOutcome>;
+/** Human-readable transcript for the tool result. */
+export declare function formatOutcome(outcome: ReviewOutcome): string;
+//# sourceMappingURL=delphi-run.d.ts.map

package/plugins/dsh/lib/delphi-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delphi-run.d.ts","sourceRoot":"","sources":["../src/delphi-run.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,aAAa,EAAc,WAAW,EAAE,MAAM,aAAa,CAAA;AAoBzE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAA;IACvC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B;AA0CD;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,MAAM,EACf,SAAS,SAAK,EACd,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,aAAa,CAAC,CA0CxB;AAED,qDAAqD;AACrD,wBAAgB,aAAa,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAiB5D"}