@khorsheed/dsh-local-agent-claude-code 0.2.0-rc.1 → 0.2.0-rc.3

package/lib/types/client/locales.d.ts

@@ -8,18 +8,24 @@ export declare const zh: {
     'card.expand': string;
     'card.collapse': string;
     'auth.title': string;
-    'model.title': string;
-    'model.info.aria': string;
-    'model.info': string;
-    'model.placeholder': string;
-    'model.menu': string;
-    'model.menuDefault': string;
-    'model.menuDefaultCliConfig': string;
-    'model.menuDefaultCliBuiltin': string;
-    'model.menuDefaultLastObserved': string;
-    'model.save': string;
-    'model.applied': string;
-    'model.error': string;
+    'endpoint.info.aria': string;
+    'endpoint.info': string;
+    'endpoint.baseUrl': string;
+    'endpoint.baseUrl.placeholder': string;
+    'endpoint.apiKey': string;
+    'endpoint.authToken': string;
+    'endpoint.secret.configured': string;
+    'endpoint.secret.placeholder': string;
+    'endpoint.configured': string;
+    'endpoint.save': string;
+    'endpoint.applied': string;
+    'endpoint.error': string;
+    'endpoint.check': string;
+    'endpoint.checking': string;
+    'endpoint.checkDirtyHint': string;
+    'endpoint.checkUnavailable': string;
+    'endpoint.unavailable': string;
+    'endpoint.checkFailed': string;
     'live.title': string;
     'live.info.aria': string;
     'live.info': string;
@@ -42,18 +48,24 @@ export declare const en: {
     'card.expand': string;
     'card.collapse': string;
     'auth.title': string;
-    'model.title': string;
-    'model.info.aria': string;
-    'model.info': string;
-    'model.placeholder': string;
-    'model.menu': string;
-    'model.menuDefault': string;
-    'model.menuDefaultCliConfig': string;
-    'model.menuDefaultCliBuiltin': string;
-    'model.menuDefaultLastObserved': string;
-    'model.save': string;
-    'model.applied': string;
-    'model.error': string;
+    'endpoint.info.aria': string;
+    'endpoint.info': string;
+    'endpoint.baseUrl': string;
+    'endpoint.baseUrl.placeholder': string;
+    'endpoint.apiKey': string;
+    'endpoint.authToken': string;
+    'endpoint.secret.configured': string;
+    'endpoint.secret.placeholder': string;
+    'endpoint.configured': string;
+    'endpoint.save': string;
+    'endpoint.applied': string;
+    'endpoint.error': string;
+    'endpoint.check': string;
+    'endpoint.checking': string;
+    'endpoint.checkDirtyHint': string;
+    'endpoint.checkUnavailable': string;
+    'endpoint.unavailable': string;
+    'endpoint.checkFailed': string;
     'live.title': string;
     'live.info.aria': string;
     'live.info': string;

package/lib/types/client/locales.js

@@ -3,23 +3,29 @@
 export const NS = 'local-agent-claude-code';
 /** Simplified Chinese dictionary (the key-set source of truth). */
 export const zh = {
-    'card.title': 'Local Agent · Claude Code',
-    'card.description': 'Claude Code 委派：登录授权与常驻模式（live）',
+    'card.title': '本机 Claude Code 委派',
+    'card.description': '使用本机安装的 Claude Code CLI 委派：端点凭据与常驻模式（live）',
     'card.expand': '展开',
     'card.collapse': '收起',
     'auth.title': '认证',
-    'model.title': '默认模型',
-    'model.info.aria': '默认模型说明',
-    'model.info': '留空 = 跟随默认（输入框里显示的就是当前跟随的模型）。从列表选择或手动输入一个模型名后保存，之后的每轮委派都以它起 CLI（`claude -p --model <模型>`，常驻模式同一个旗标）。成员会话里还可用作曲器按会话切换，不影响这里的默认。改动在下一轮委派生效，进行中的轮次不受影响；评测 run 的条件在建立时冻结，中途换模型会被下一轮的模型回读判为 misattributed 而拦下。',
-    'model.placeholder': '留空 = 不传模型，用 CLI 自己的默认',
-    'model.menu': '选择模型',
-    'model.menuDefault': '默认（跟随 CLI 内置默认）',
-    'model.menuDefaultCliConfig': '默认（跟随 CLI 配置：{model}）',
-    'model.menuDefaultCliBuiltin': '默认（跟随 CLI 默认：{model}）',
-    'model.menuDefaultLastObserved': '默认（跟随 CLI 内置默认（最近：{model}））',
-    'model.save': '保存',
-    'model.applied': '已保存，下一轮委派生效；进行中的轮次不受影响',
-    'model.error': '保存失败，请重试',
+    'endpoint.info.aria': '端点凭据说明',
+    'endpoint.info': '这里保存的就是默认 scope 的 endpoint-auth.json（0600，只存本机），它优先于 profile 的 YAML 配置行；宿主 shell 的环境变量从不被读取。端点留空 = Anthropic 官方端点；API Key 与 Auth Token 至少填一个（分别对应 x-api-key 与 Bearer 头，看你的中转认哪种）。密钥绝不写进 profile 文件，也不进入评测条件指纹。保存对下一轮委派生效，进行中的轮次不受影响。',
+    'endpoint.baseUrl': '端点地址（baseUrl）',
+    'endpoint.baseUrl.placeholder': '留空 = Anthropic 官方端点',
+    'endpoint.apiKey': 'API Key',
+    'endpoint.authToken': 'Auth Token',
+    'endpoint.secret.configured': '已配置 · 输入新值更换，留空保存 = 清除',
+    'endpoint.secret.placeholder': '未配置',
+    'endpoint.configured': '已配置',
+    'endpoint.save': '保存凭据',
+    'endpoint.applied': '已保存，下一轮委派生效；进行中的轮次不受影响',
+    'endpoint.error': '保存失败，请重试',
+    'endpoint.check': '验证端点并获取模型',
+    'endpoint.checking': '验证中…',
+    'endpoint.checkDirtyHint': '有未保存的修改，先保存凭据再验证',
+    'endpoint.checkUnavailable': '当前核心不支持端点验证（请升级 local-agent 核心包）',
+    'endpoint.unavailable': '当前核心不支持凭据配置（请升级 local-agent 核心包）',
+    'endpoint.checkFailed': '验证失败，请重试',
     'live.title': '常驻模式（live）',
     'live.info.aria': '常驻模式说明',
     'live.info': '常驻模式 = 成员进程常驻：输出实时流入成员会话、取消不杀进程、崩溃后自动续上原会话；关闭则每轮独立进程，跑完一次性出结果。设置为全局偏好，对所有后续委派生效。',
@@ -29,23 +35,29 @@ export const zh = {
 };
 /** English dictionary, checked complete against the zh key set. */
 export const en = {
-    'card.title': 'Local Agent · Claude Code',
-    'card.description': 'Claude Code delegation: sign-in and resident (live) mode',
+    'card.title': 'Local Claude Code Delegation',
+    'card.description': "Delegate through this machine's Claude Code CLI: endpoint credential and resident (live) mode",
     'card.expand': 'Expand',
     'card.collapse': 'Collapse',
     'auth.title': 'Authentication',
-    'model.title': 'Default model',
-    'model.info.aria': 'About the default model',
-    'model.info': "Blank = follow the default (the input shows the model it currently follows). Pick from the list or type a model name by hand and save, and every later delegation round starts the CLI with it (`claude -p --model <model>`, the same flag in resident mode). Inside a member session the composer can also switch the model per session, without touching this default. A change applies to the next round and never disturbs a round in flight; an evaluation run freezes its condition at setup, so switching mid-run is caught by the model read-back on the next round and fails the run as misattributed.",
-    'model.placeholder': "Blank = pass no model, keep the CLI's own default",
-    'model.menu': 'Pick a model',
-    'model.menuDefault': "Default (follow the CLI's built-in default)",
-    'model.menuDefaultCliConfig': 'Default (follow the CLI config: {model})',
-    'model.menuDefaultCliBuiltin': 'Default (follow the CLI default: {model})',
-    'model.menuDefaultLastObserved': "Default (follow the CLI's built-in default (last: {model}))",
-    'model.save': 'Save',
-    'model.applied': 'Saved — takes effect on the next delegation round; rounds in flight are unaffected',
-    'model.error': 'Save failed, please retry',
+    'endpoint.info.aria': 'About the endpoint credential',
+    'endpoint.info': "What you save here is the default scope's endpoint-auth.json (mode 0600, local only), which outranks the profile's YAML row; the host shell's environment is never read. A blank endpoint means Anthropic's own; fill at least one of API Key and Auth Token (x-api-key and Bearer respectively — whichever your relay accepts). Keys never enter the profile document or an evaluation's condition fingerprint. Saving applies to the next delegation round; rounds in flight are unaffected.",
+    'endpoint.baseUrl': 'Endpoint (baseUrl)',
+    'endpoint.baseUrl.placeholder': "Blank = Anthropic's own endpoint",
+    'endpoint.apiKey': 'API Key',
+    'endpoint.authToken': 'Auth Token',
+    'endpoint.secret.configured': 'Configured · type to replace, save blank to clear',
+    'endpoint.secret.placeholder': 'Not configured',
+    'endpoint.configured': 'Configured',
+    'endpoint.save': 'Save credential',
+    'endpoint.applied': 'Saved — takes effect on the next delegation round; rounds in flight are unaffected',
+    'endpoint.error': 'Save failed, please retry',
+    'endpoint.check': 'Verify endpoint & fetch models',
+    'endpoint.checking': 'Checking…',
+    'endpoint.checkDirtyHint': 'Unsaved changes — save the credential first',
+    'endpoint.checkUnavailable': 'Endpoint verification is not supported by this core (upgrade the local-agent core)',
+    'endpoint.unavailable': 'Credential configuration is not supported by this core (upgrade the local-agent core)',
+    'endpoint.checkFailed': 'Check failed, please retry',
     'live.title': 'Resident mode (live)',
     'live.info.aria': 'About resident mode',
     'live.info': 'Resident mode keeps the member process alive: output streams into the member session in real time, cancelling does not kill the process, and a crash resumes the same session. Off means every round runs as an independent one-shot process. The setting is global and applies to every later delegation.',

package/lib/types/endpoint-auth.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Endpoint-key authentication — the claude-code harness's ONLY auth mode.
+ * There is no OAuth anywhere in this package: a delegation round reaches its
+ * endpoint with `ANTHROPIC_BASE_URL` plus `ANTHROPIC_API_KEY` (x-api-key) or
+ * `ANTHROPIC_AUTH_TOKEN` (Authorization: Bearer), exactly the environment a
+ * shell would export for a proxy relay, and `claude -p` needs nothing else
+ * (verified against claude 2.1.296: a fresh scoped home with only these
+ * variables runs a round and scaffolds `.claude.json` itself — no onboarding
+ * or key-approval gate in headless mode).
+ *
+ * Two layers, merged per field, file over config:
+ *
+ * - `<scopedHome>/endpoint-auth.json` (mode 0600) — the per-scope credential.
+ *   Its name deliberately matches the eval contract hash's credential denylist
+ *   (`auth`), so the key material never enters an evaluation's condition
+ *   fingerprint; the file's mtime serves as the credential stamp, which makes
+ *   "edit the file" the recovery gesture for a `rejected` grade.
+ * - The plugin config's `baseUrl` / `apiKey` / `authToken` — the deployment
+ *   default every scope without a file shares. Read PER ROUND from the
+ *   apply-time snapshot, so a profile edit applies to the next round (and a
+ *   host restart clears the in-memory `rejected` mark).
+ *
+ * The env layer this module emits rides the family's existing plumbing:
+ * `delegationEnv` on the host, and `containerExecSpawn`'s name-only `-e`
+ * forwarding into a container (the value travels in the docker client's
+ * environment, never on an argv). A containerized round therefore
+ * authenticates with the same credential as the host — nothing is authorized
+ * inside the unit, which is the point.
+ * @module @khorsheed/dsh-local-agent-claude-code/endpoint-auth
+ */
+/**
+ * The scoped-home credential file's name. Chosen to match the eval contract
+ * hash's credential-shaped denylist (`/token|key|credential|secret|password|auth|\.env/i`),
+ * so the file is excluded from condition fingerprints by name.
+ */
+export declare const ENDPOINT_AUTH_FILE = "endpoint-auth.json";
+/**
+ * One scope's endpoint credential. `baseUrl` is optional (absent means the
+ * CLI's own default endpoint — an official console key needs no relay); at
+ * least one of `apiKey` / `authToken` must be non-empty for the scope to
+ * count as authenticated. When both are set the CLI's own precedence rules
+ * apply — the package passes both through untouched.
+ */
+export interface ClaudeEndpointAuth {
+    readonly baseUrl?: string;
+    /** Sent as `ANTHROPIC_API_KEY` (the `x-api-key` header). */
+    readonly apiKey?: string;
+    /** Sent as `ANTHROPIC_AUTH_TOKEN` (the `Authorization: Bearer` header). */
+    readonly authToken?: string;
+}
+/** Whether a resolved endpoint carries a usable credential. */
+export declare function hasEndpointCredential(auth: ClaudeEndpointAuth | undefined): auth is (ClaudeEndpointAuth & {
+    apiKey: string;
+}) | (ClaudeEndpointAuth & {
+    authToken: string;
+});
+/**
+ * Read the scope's endpoint-auth.json. Absent or unreadable yields undefined
+ * (the caller falls back to the plugin config); malformed JSON or a non-object
+ * payload also yields undefined — a torn file must not fail a status read.
+ * Non-string fields are dropped, never carried through.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @returns the file's endpoint credential, or undefined.
+ */
+export declare function readEndpointAuthFile(homeDir: string): Promise<ClaudeEndpointAuth | undefined>;
+/**
+ * Resolve one scope's effective endpoint credential: the scope's
+ * endpoint-auth.json merged FIELD BY FIELD over the plugin config's
+ * `baseUrl` / `apiKey` / `authToken` (a file that names only a key rotates
+ * the key while keeping the deployment's relay URL). The result may carry no
+ * credential at all — {@link hasEndpointCredential} is the judgment, kept
+ * separate so the caller can still route/log the resolved baseUrl.
+ * @param homeDir - the scope's scoped home.
+ * @param config - the plugin config's deployment-level endpoint triple.
+ * @returns the merged endpoint auth.
+ */
+export declare function resolveEndpointAuth(homeDir: string, config: ClaudeEndpointAuth): Promise<ClaudeEndpointAuth>;
+/**
+ * The spawn-env layer for a resolved endpoint: one entry per defined field,
+ * nothing else. Undefined yields an empty layer — the spread then adds no
+ * keys at all, byte-identical to the pre-endpoint env.
+ * @param auth - the resolved endpoint auth, or undefined.
+ * @returns the explicit env entries for the delegation spawn.
+ */
+export declare function endpointAuthEnv(auth: ClaudeEndpointAuth | undefined): NodeJS.ProcessEnv;
+/**
+ * The credential marker's modification stamp (epoch ms): the endpoint file's
+ * mtime, or undefined when the scope has no file (a config-sourced credential
+ * has no marker — rotating it pairs with the profile edit and instance
+ * restart that clear the in-memory grade marks). A fresh file write is a
+ * fresh stamp, which is how an edited-in key recovers a `rejected` grade.
+ * @param homeDir - the scope's scoped home.
+ * @returns the stamp, or undefined.
+ */
+export declare function endpointAuthStamp(homeDir: string): Promise<number | undefined>;
+/** Whether the scope carries its own endpoint file at all. */
+export declare function endpointAuthFileExists(homeDir: string): Promise<boolean>;
+/**
+ * Write the scope's endpoint-auth.json (mode 0600, mkdir -p first), the
+ * per-scope provisioning path an evaluation's `conditions provision` (or a
+ * person) uses to give one scope its own credential. Whole-file write: the
+ * payload is exactly what {@link readEndpointAuthFile} parses back.
+ * @param homeDir - the scope's scoped home.
+ * @param auth - the endpoint credential to persist.
+ */
+export declare function writeEndpointAuth(homeDir: string, auth: ClaudeEndpointAuth): Promise<void>;
+/**
+ * Clear the scope's OWN endpoint credential (the endpoint-auth.json file).
+ * A deployment-level credential from the plugin config is untouched — the
+ * core's logout reply then names the profile row as the place to edit.
+ * @param homeDir - the scope's scoped home.
+ */
+export declare function clearEndpointAuth(homeDir: string): Promise<void>;
+/** The official endpoint used when no baseUrl is configured anywhere. */
+export declare const OFFICIAL_BASE_URL = "https://api.anthropic.com";
+/** The subcommand's fetch shape (injected in tests). */
+export type EndpointCheckFetch = (url: string, init: {
+    headers: Record<string, string>;
+    signal: AbortSignal;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text(): Promise<string>;
+}>;
+/** One model the endpoint serves, from `GET <baseUrl>/v1/models`. */
+export interface EndpointServedModel {
+    readonly id: string;
+    readonly displayName?: string;
+    /** Reasoning effort levels the endpoint advertises for this model, in ascending order. */
+    readonly efforts?: readonly string[];
+}
+/**
+ * The outcome of one `GET <baseUrl>/v1/models`: the parsed model list, the
+ * HTTP status when the endpoint answered, or the transport error's message.
+ * Callers fold it their own way (the check's verdict text, the catalog's
+ * directory); no case throws.
+ */
+export type EndpointModelsResult = {
+    readonly kind: 'models';
+    readonly models: readonly EndpointServedModel[];
+} | {
+    readonly kind: 'http';
+    readonly status: number;
+    readonly body: string;
+} | {
+    readonly kind: 'unreachable';
+    readonly message: string;
+} | {
+    readonly kind: 'malformed';
+};
+/**
+ * `GET <baseUrl>/v1/models` with the resolved credential's auth header(s) —
+ * the token-free endpoint probe shared by the `/claude-code check` verdict
+ * and the model catalog. Anthropic's own API serves this route with
+ * `x-api-key`; relays (openproxy verified) proxy it and answer the same
+ * shape. Never throws: every failure mode folds into the result.
+ * @param endpoint - the resolved endpoint auth (caller checks the credential).
+ * @param fetchImpl - the HTTP fetch; default the host's global fetch.
+ * @param signal - abort for the whole probe (timeout bundled by the caller).
+ * @returns the folded result.
+ */
+export declare function fetchEndpointModels(endpoint: ClaudeEndpointAuth & {
+    readonly baseUrl: string;
+}, fetchImpl?: EndpointCheckFetch, signal?: AbortSignal): Promise<EndpointModelsResult>;
+/**
+ * Probe the resolved endpoint with a cheap, token-free round-trip: `GET
+ * <baseUrl>/v1/models` with the resolved credential's auth header(s). A 200
+ * proves both reachability and credential validity — the exact evidence a
+ * "verify" button needs — and the served model list rides the reply so the
+ * user sees what the endpoint offers (any id can be typed into the model
+ * field by hand). One transport-level retry rides along: a local proxy
+ * restart (a Surge/clash reload) stalls the first attempt into the timeout
+ * and answers the retry immediately. Never throws: every failure mode folds
+ * into the reply text, since the reply IS the diagnostic.
+ * @param endpoint - the resolved endpoint auth (scope file over settings).
+ * @param fetchImpl - the HTTP fetch; default the host's global fetch.
+ * @param timeoutMs - one attempt's deadline (two attempts at most).
+ * @returns the human-readable verdict for the `/claude-code check` reply.
+ */
+export declare function checkClaudeEndpoint(endpoint: ClaudeEndpointAuth, fetchImpl?: EndpointCheckFetch, timeoutMs?: number): Promise<string>;
+//# sourceMappingURL=endpoint-auth.d.ts.map

package/lib/types/endpoint-auth.js

@@ -0,0 +1,281 @@
+/**
+ * Endpoint-key authentication — the claude-code harness's ONLY auth mode.
+ * There is no OAuth anywhere in this package: a delegation round reaches its
+ * endpoint with `ANTHROPIC_BASE_URL` plus `ANTHROPIC_API_KEY` (x-api-key) or
+ * `ANTHROPIC_AUTH_TOKEN` (Authorization: Bearer), exactly the environment a
+ * shell would export for a proxy relay, and `claude -p` needs nothing else
+ * (verified against claude 2.1.296: a fresh scoped home with only these
+ * variables runs a round and scaffolds `.claude.json` itself — no onboarding
+ * or key-approval gate in headless mode).
+ *
+ * Two layers, merged per field, file over config:
+ *
+ * - `<scopedHome>/endpoint-auth.json` (mode 0600) — the per-scope credential.
+ *   Its name deliberately matches the eval contract hash's credential denylist
+ *   (`auth`), so the key material never enters an evaluation's condition
+ *   fingerprint; the file's mtime serves as the credential stamp, which makes
+ *   "edit the file" the recovery gesture for a `rejected` grade.
+ * - The plugin config's `baseUrl` / `apiKey` / `authToken` — the deployment
+ *   default every scope without a file shares. Read PER ROUND from the
+ *   apply-time snapshot, so a profile edit applies to the next round (and a
+ *   host restart clears the in-memory `rejected` mark).
+ *
+ * The env layer this module emits rides the family's existing plumbing:
+ * `delegationEnv` on the host, and `containerExecSpawn`'s name-only `-e`
+ * forwarding into a container (the value travels in the docker client's
+ * environment, never on an argv). A containerized round therefore
+ * authenticates with the same credential as the host — nothing is authorized
+ * inside the unit, which is the point.
+ * @module @khorsheed/dsh-local-agent-claude-code/endpoint-auth
+ */
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/**
+ * The scoped-home credential file's name. Chosen to match the eval contract
+ * hash's credential-shaped denylist (`/token|key|credential|secret|password|auth|\.env/i`),
+ * so the file is excluded from condition fingerprints by name.
+ */
+export const ENDPOINT_AUTH_FILE = 'endpoint-auth.json';
+/** Trim and normalize one credential field; blank reads as absent. */
+function field(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+/** Whether a resolved endpoint carries a usable credential. */
+export function hasEndpointCredential(auth) {
+    return auth !== undefined && (field(auth.apiKey) !== undefined || field(auth.authToken) !== undefined);
+}
+/**
+ * Read the scope's endpoint-auth.json. Absent or unreadable yields undefined
+ * (the caller falls back to the plugin config); malformed JSON or a non-object
+ * payload also yields undefined — a torn file must not fail a status read.
+ * Non-string fields are dropped, never carried through.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @returns the file's endpoint credential, or undefined.
+ */
+export async function readEndpointAuthFile(homeDir) {
+    let text;
+    try {
+        text = await readFile(join(homeDir, ENDPOINT_AUTH_FILE), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+            return undefined;
+        const baseUrl = field(parsed['baseUrl']);
+        const apiKey = field(parsed['apiKey']);
+        const authToken = field(parsed['authToken']);
+        return {
+            ...baseUrl === undefined ? {} : { baseUrl },
+            ...apiKey === undefined ? {} : { apiKey },
+            ...authToken === undefined ? {} : { authToken },
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Resolve one scope's effective endpoint credential: the scope's
+ * endpoint-auth.json merged FIELD BY FIELD over the plugin config's
+ * `baseUrl` / `apiKey` / `authToken` (a file that names only a key rotates
+ * the key while keeping the deployment's relay URL). The result may carry no
+ * credential at all — {@link hasEndpointCredential} is the judgment, kept
+ * separate so the caller can still route/log the resolved baseUrl.
+ * @param homeDir - the scope's scoped home.
+ * @param config - the plugin config's deployment-level endpoint triple.
+ * @returns the merged endpoint auth.
+ */
+export async function resolveEndpointAuth(homeDir, config) {
+    const file = await readEndpointAuthFile(homeDir);
+    const configBaseUrl = field(config.baseUrl);
+    const configApiKey = field(config.apiKey);
+    const configAuthToken = field(config.authToken);
+    return {
+        ...configBaseUrl === undefined ? {} : { baseUrl: configBaseUrl },
+        ...configApiKey === undefined ? {} : { apiKey: configApiKey },
+        ...configAuthToken === undefined ? {} : { authToken: configAuthToken },
+        ...file,
+    };
+}
+/**
+ * The spawn-env layer for a resolved endpoint: one entry per defined field,
+ * nothing else. Undefined yields an empty layer — the spread then adds no
+ * keys at all, byte-identical to the pre-endpoint env.
+ * @param auth - the resolved endpoint auth, or undefined.
+ * @returns the explicit env entries for the delegation spawn.
+ */
+export function endpointAuthEnv(auth) {
+    if (auth === undefined)
+        return {};
+    const baseUrl = field(auth.baseUrl);
+    const apiKey = field(auth.apiKey);
+    const authToken = field(auth.authToken);
+    return {
+        ...baseUrl === undefined ? {} : { ANTHROPIC_BASE_URL: baseUrl },
+        ...apiKey === undefined ? {} : { ANTHROPIC_API_KEY: apiKey },
+        ...authToken === undefined ? {} : { ANTHROPIC_AUTH_TOKEN: authToken },
+    };
+}
+/**
+ * The credential marker's modification stamp (epoch ms): the endpoint file's
+ * mtime, or undefined when the scope has no file (a config-sourced credential
+ * has no marker — rotating it pairs with the profile edit and instance
+ * restart that clear the in-memory grade marks). A fresh file write is a
+ * fresh stamp, which is how an edited-in key recovers a `rejected` grade.
+ * @param homeDir - the scope's scoped home.
+ * @returns the stamp, or undefined.
+ */
+export async function endpointAuthStamp(homeDir) {
+    try {
+        return (await stat(join(homeDir, ENDPOINT_AUTH_FILE))).mtimeMs;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Whether the scope carries its own endpoint file at all. */
+export async function endpointAuthFileExists(homeDir) {
+    return (await endpointAuthStamp(homeDir)) !== undefined;
+}
+/**
+ * Write the scope's endpoint-auth.json (mode 0600, mkdir -p first), the
+ * per-scope provisioning path an evaluation's `conditions provision` (or a
+ * person) uses to give one scope its own credential. Whole-file write: the
+ * payload is exactly what {@link readEndpointAuthFile} parses back.
+ * @param homeDir - the scope's scoped home.
+ * @param auth - the endpoint credential to persist.
+ */
+export async function writeEndpointAuth(homeDir, auth) {
+    await mkdir(homeDir, { recursive: true });
+    const baseUrl = field(auth.baseUrl);
+    const apiKey = field(auth.apiKey);
+    const authToken = field(auth.authToken);
+    const payload = {
+        ...baseUrl === undefined ? {} : { baseUrl },
+        ...apiKey === undefined ? {} : { apiKey },
+        ...authToken === undefined ? {} : { authToken },
+    };
+    await writeFile(join(homeDir, ENDPOINT_AUTH_FILE), JSON.stringify(payload, undefined, 2) + '\n', { mode: 0o600 });
+}
+/**
+ * Clear the scope's OWN endpoint credential (the endpoint-auth.json file).
+ * A deployment-level credential from the plugin config is untouched — the
+ * core's logout reply then names the profile row as the place to edit.
+ * @param homeDir - the scope's scoped home.
+ */
+export async function clearEndpointAuth(homeDir) {
+    await rm(join(homeDir, ENDPOINT_AUTH_FILE), { force: true });
+}
+/** The official endpoint used when no baseUrl is configured anywhere. */
+export const OFFICIAL_BASE_URL = 'https://api.anthropic.com';
+/** How many served model ids the check reply lists before truncating. */
+const CHECK_MODEL_LIST_LIMIT = 8;
+/** Bound on the error-body excerpt a failed check reports. */
+const CHECK_ERROR_BODY_LIMIT = 200;
+/** The effort levels one served-model entry advertises, oldest-first. */
+function servedEfforts(effort) {
+    if (typeof effort !== 'object' || effort === null)
+        return undefined;
+    const levels = ['low', 'medium', 'high', 'xhigh', 'max']
+        .filter(level => effort[level]?.supported === true);
+    return levels.length === 0 ? undefined : levels;
+}
+/**
+ * `GET <baseUrl>/v1/models` with the resolved credential's auth header(s) —
+ * the token-free endpoint probe shared by the `/claude-code check` verdict
+ * and the model catalog. Anthropic's own API serves this route with
+ * `x-api-key`; relays (openproxy verified) proxy it and answer the same
+ * shape. Never throws: every failure mode folds into the result.
+ * @param endpoint - the resolved endpoint auth (caller checks the credential).
+ * @param fetchImpl - the HTTP fetch; default the host's global fetch.
+ * @param signal - abort for the whole probe (timeout bundled by the caller).
+ * @returns the folded result.
+ */
+export async function fetchEndpointModels(endpoint, fetchImpl, signal) {
+    const headers = { 'anthropic-version': '2023-06-01' };
+    if (endpoint.apiKey !== undefined)
+        headers['x-api-key'] = endpoint.apiKey;
+    if (endpoint.authToken !== undefined)
+        headers['authorization'] = `Bearer ${endpoint.authToken}`;
+    const fetcher = fetchImpl ?? globalThis.fetch;
+    const url = `${endpoint.baseUrl.replace(/\/+$/, '')}/v1/models`;
+    let response;
+    try {
+        response = await fetcher(url, { headers, signal: signal ?? AbortSignal.timeout(8_000) });
+    }
+    catch (error) {
+        return { kind: 'unreachable', message: error instanceof Error ? error.message : String(error) };
+    }
+    if (!response.ok) {
+        return { kind: 'http', status: response.status, body: (await response.text().catch(() => '')).slice(0, CHECK_ERROR_BODY_LIMIT) };
+    }
+    let data;
+    try {
+        data = JSON.parse(await response.text()).data;
+    }
+    catch {
+        return { kind: 'malformed' };
+    }
+    if (!Array.isArray(data))
+        return { kind: 'malformed' };
+    const models = [];
+    for (const entry of data) {
+        if (typeof entry !== 'object' || entry === null)
+            continue;
+        const record = entry;
+        if (typeof record.id !== 'string' || record.id === '')
+            continue;
+        const efforts = servedEfforts(record.effort);
+        models.push({
+            id: record.id,
+            ...typeof record.display_name === 'string' && record.display_name !== '' ? { displayName: record.display_name } : {},
+            ...efforts === undefined ? {} : { efforts },
+        });
+    }
+    return { kind: 'models', models };
+}
+/**
+ * Probe the resolved endpoint with a cheap, token-free round-trip: `GET
+ * <baseUrl>/v1/models` with the resolved credential's auth header(s). A 200
+ * proves both reachability and credential validity — the exact evidence a
+ * "verify" button needs — and the served model list rides the reply so the
+ * user sees what the endpoint offers (any id can be typed into the model
+ * field by hand). One transport-level retry rides along: a local proxy
+ * restart (a Surge/clash reload) stalls the first attempt into the timeout
+ * and answers the retry immediately. Never throws: every failure mode folds
+ * into the reply text, since the reply IS the diagnostic.
+ * @param endpoint - the resolved endpoint auth (scope file over settings).
+ * @param fetchImpl - the HTTP fetch; default the host's global fetch.
+ * @param timeoutMs - one attempt's deadline (two attempts at most).
+ * @returns the human-readable verdict for the `/claude-code check` reply.
+ */
+export async function checkClaudeEndpoint(endpoint, fetchImpl, timeoutMs = 20_000) {
+    if (!hasEndpointCredential(endpoint)) {
+        return 'No endpoint credential configured — fill API Key or Auth Token on the settings card (or the profile row) first.';
+    }
+    const baseUrl = (endpoint.baseUrl ?? OFFICIAL_BASE_URL).replace(/\/+$/, '');
+    let result = await fetchEndpointModels({ ...endpoint, baseUrl }, fetchImpl, AbortSignal.timeout(timeoutMs));
+    if (result.kind === 'unreachable') {
+        result = await fetchEndpointModels({ ...endpoint, baseUrl }, fetchImpl, AbortSignal.timeout(timeoutMs));
+    }
+    if (result.kind === 'unreachable')
+        return `Endpoint unreachable (${baseUrl}): ${result.message}`;
+    if (result.kind === 'http') {
+        return `Endpoint answered HTTP ${String(result.status)} (${baseUrl})${result.body === '' ? '' : `: ${result.body}`}`;
+    }
+    if (result.kind === 'malformed') {
+        return `Endpoint reachable (${baseUrl}) but the model list did not parse — the credential worked, the reply was not /v1/models-shaped.`;
+    }
+    if (result.models.length === 0)
+        return `Endpoint reachable (${baseUrl}); it serves no models.`;
+    const ids = result.models.map(model => model.id);
+    const listed = ids.slice(0, CHECK_MODEL_LIST_LIMIT).join(', ');
+    const more = ids.length > CHECK_MODEL_LIST_LIMIT ? `, … +${String(ids.length - CHECK_MODEL_LIST_LIMIT)} more` : '';
+    return `Endpoint reachable (${baseUrl}): ${String(ids.length)} model(s) served — ${listed}${more}`;
+}