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

package/lib/types/client/index.js

@@ -1,23 +1,49 @@
 import { bindSettingsScope } from '@khorsheed/dsh-local-agent/src/client/settings-scope.ts';
+/**
+ * Local-agent-claude-code plugin, browser half: the claude-code settings card
+ * — a section of the family core's「本机 Agent 委派」family card on the
+ * Plugins page (registered through the core's
+ * `localAgentUi.registerHarnessCard` while the Host serves the
+ * `local-agent-claude-code` namespace), or this package's own `plugins.item`
+ * entry when the core predates the family card (the declare-and-degrade
+ * fallback). Every install shape serves the row's
+ * volatile Config under the row id — standalone install, family bundle, or
+ * mode pack — so the card follows the served namespace rather than any
+ * carrier bundle, and a composition without the row shows no trace of it. The
+ * card carries the family core's shared ProviderAuthBlock
+ * (login/logout/manual-handoff, backed by the core's localAgentGateway Remote
+ * and the commands channel), the default-model block (free-text write plus
+ * the gateway's model surface: the effective-model line and the suggestion
+ * vocabulary), and the resident-mode switch, whose writes ride the bound
+ * settingsScope — the host watcher hot-applies them, no reload. Every read
+ * degrades: an absent gateway renders the auth block's 'unavailable' state
+ * and drops the model surface, an unregistered namespace disables the live
+ * controls.
+ * @module @khorsheed/dsh-local-agent-claude-code/client
+ */
+import { createElement, useSyncExternalStore } from 'react';
 import { en, NS, zh } from './locales.js';
-import { ClaudeCodeBundleConfig, ClaudeCodeSettingsCard, } from './SettingsCard.js';
-export { ClaudeCodeBundleConfig, ClaudeCodeSettingsCard } from './SettingsCard.js';
+import { ClaudeCodeBundleConfig, ClaudeCodeCardSection, } from './SettingsCard.js';
+export { ClaudeCodeBundleConfig, ClaudeCodeCardSection, ClaudeCodeSettingsCard } from './SettingsCard.js';
 export { en, NS, zh };
 /**
- * This bundle's package name — the key the Plugins page dispatches
- * `plugins.bundle.config` entries on (identity triangle: cordis.patch.yml,
- * tsdown.config.ts, invariant.ts).
+ * Required services: slot registry, command Remote, and locale registry. The
+ * settings scope is NOT a static inject — its service name differs per host
+ * line (`settingsScope` on 0.1.5, `configForms` on rc.1), so a static entry
+ * would pend the whole client plugin on the other line; bindSettingsScope
+ * probes the serving one instead (the settings client package is a declared
+ * client inject, so one of them is always already up). The card track probes
+ * `configForms` through the same kind of deferred inject (see apply).
  */
-const PACKAGE_NAME = '@khorsheed/dsh-local-agent-claude-code';
-/** Required services: slot registry, settings scope, command Remote, and locale registry. */
 export const inject = ['slots', 'remote', 'remote.commands', 'locale'];
 /**
  * Client plugin body: register the dictionaries and the claude-code settings
- * surfaces bound to the local-agent-claude-code namespace.
+ * card bound to the local-agent-claude-code namespace.
  * @param ctx - client root context.
  */
 export function apply(ctx) {
     ctx.effect(() => ctx.locale.register(NS, { zh, en }), 'local-agent-claude-code: dictionaries');
+    const t = ctx.locale.bind(NS);
     const scope = bindSettingsScope(ctx, 'local-agent-claude-code');
     // The auth block's copy lives in the family core's dictionary; binding is
     // stable per namespace and late dictionary registration still resolves.
@@ -27,21 +53,58 @@ export function apply(ctx) {
     // never matters, and degrade to the auth block's 'unavailable' state when
     // the core client is absent.
     const gateway = () => ctx.get('remote.localAgentGateway');
-    // Both settings surfaces inject the same face.
-    const cardInject = () => ({
+    // The card's inject face minus the hooks compartment — the family-card
+    // section consumes this verbatim; the standalone card's slot registration
+    // adds the hooks compartment back below.
+    const cardFace = () => ({
         scope,
-        hooks: { settings: scope },
         authT,
-        renderModelPicker: props => ctx.get('localAgentUi')?.renderHarnessModelPicker('claude-code', props),
-        // The model surface read behind the default-model block's effective
-        // line and suggestions. 'claude-code' is the harness name the host
-        // half registers; a core predating the model broker (or an absent
-        // gateway) degrades to the bare free-text input.
-        modelInfo: () => {
+        // The curated model list's read/write faces, over the same Remotes.
+        modelList: {
+            read: () => {
+                const gw = gateway();
+                if (gw === undefined || typeof gw.modelList !== 'function')
+                    return Promise.resolve(undefined);
+                return gw.modelList('claude-code').then(result => (result.ok ? result.value : undefined));
+            },
+            write: (models) => {
+                const gw = gateway();
+                if (gw === undefined || typeof gw.configureModelList !== 'function')
+                    return Promise.resolve(undefined);
+                return gw.configureModelList('claude-code', models).then(result => (result.ok ? result.value : undefined));
+            },
+        },
+        // The endpoint's served catalog for the add dialog. A core predating
+        // modelDirectory leaves the dialog with its reason.
+        modelDirectory: (refresh) => {
+            const gw = gateway();
+            if (gw === undefined || typeof gw.modelDirectory !== 'function')
+                return Promise.resolve(undefined);
+            return gw.modelDirectory('claude-code', undefined, refresh ?? false).then(result => (result.ok ? result.value : undefined));
+        },
+        // The verify button's probe, over the session-less gateway Remote. A core
+        // predating `checkEndpoint` hides the button (declare-and-degrade).
+        checkEndpoint: () => {
             const gw = gateway();
-            if (gw === undefined || typeof gw.harnessModel !== 'function')
+            if (gw === undefined || typeof gw.checkEndpoint !== 'function')
                 return Promise.resolve(undefined);
-            return gw.harnessModel('claude-code').then(result => (result.ok ? result.value : undefined));
+            return gw.checkEndpoint('claude-code').then(result => (result.ok ? result.value : undefined));
+        },
+        // The credential form's read/write face, over the same session-less
+        // Remotes. Absent on a core that predates them — the card hides the form.
+        endpointAuth: {
+            read: () => {
+                const gw = gateway();
+                if (gw === undefined || typeof gw.endpointAuth !== 'function')
+                    return Promise.resolve(undefined);
+                return gw.endpointAuth('claude-code').then(result => (result.ok ? result.value : undefined));
+            },
+            write: (fields) => {
+                const gw = gateway();
+                if (gw === undefined || typeof gw.configureEndpoint !== 'function')
+                    return Promise.resolve(undefined);
+                return gw.configureEndpoint('claude-code', fields).then(result => (result.ok ? result.value : undefined));
+            },
         },
         auth: {
             status: name => 
@@ -53,35 +116,57 @@ export function apply(ctx) {
                 .then(result => (result.ok ? result.value?.result.text : undefined)),
         },
     });
-    // The settings surface follows the host line AND the install shape — three
-    // tracks, all riding slots.inject so each fires only where its declaration
-    // exists. Standalone install: the package's own Plugins-page detail view
-    // (`plugins.bundle.config`, keyed by package name). Installed as a family
-    // member: the member is no longer the profile's direct dependency, so only
-    // the bundle gets a detail view — the card rides the row-level slot
-    // (`plugins.row.config`, keyed `<bundle package>#<row id>` with the row id
-    // the bundle's patch declares) and the bundle's page gains a configure
-    // entry opening it. 0.1.5: the legacy configurable-plugins tab card
-    // (`settings.plugin.item`, keyed by the settings namespace) through a
-    // string-keyed duck narrow of the same service (the slot name is gone from
-    // the alpha.2 SlotMap).
-    ctx.slots.inject('plugins.bundle.config', () => ctx.slots.register({
-        name: 'plugins.bundle.config',
-        key: PACKAGE_NAME,
-        locale: NS,
-        inject: cardInject,
-    }, ClaudeCodeBundleConfig));
-    ctx.slots.inject('plugins.row.config', () => ctx.slots.register({
-        name: 'plugins.row.config',
-        key: '@khorsheed/dsh-bundle-local-agent#local-agent-claude-code',
-        locale: NS,
-        inject: cardInject,
-    }, ClaudeCodeBundleConfig));
-    const legacy = ctx.slots;
-    legacy.inject('settings.plugin.item', () => legacy.register({
-        name: 'settings.plugin.item',
-        key: 'local-agent-claude-code',
-        locale: NS,
-        inject: cardInject,
-    }, ClaudeCodeSettingsCard));
+    // The settings card injects this face.
+    const cardInject = () => ({ ...cardFace(), hooks: { settings: scope } });
+    // The family-card section render bypasses the slot renderer's inject.hooks
+    // materialization, so bind the scope's selector hook here with the same
+    // semantics (a uSES subscription over the scope's own subscribe/getSnapshot).
+    const subscribeScope = (listener) => scope.subscribe(listener);
+    const readScope = () => scope.getSnapshot();
+    const useSettings = (select) => select(useSyncExternalStore(subscribeScope, readScope));
+    // One Plugins-page seat gated on the SERVED NAMESPACE, never on the install
+    // shape: whichever composition carries the `local-agent-claude-code` row —
+    // standalone install, family bundle, or mode pack — serves the row's
+    // volatile Config under the row id, and `whileServed` keeps the
+    // registration alive for exactly that span (the official companion
+    // convention), so a composition without the row shows no trace of the card.
+    // This replaces the retired per-shape seats: `plugins.row.config` hardcoded
+    // one carrier bundle into its key, and the host deleted
+    // `settings.plugin.item`. The probe rides a deferred inject because
+    // configForms exists only on the alpha.2+ host line; a 0.1.5 host never
+    // fires it, and a configForms predating whileServed (0.1.6-alpha.2) skips
+    // the card.
+    ctx.inject(['configForms'], (formsCtx) => {
+        const forms = formsCtx.configForms;
+        if (typeof forms.whileServed !== 'function')
+            return;
+        return forms.whileServed(['local-agent-claude-code'], () => {
+            // The family card owns the Plugins-page seat when the core's client
+            // provides it: a core new enough answers registerHarnessCard, and this
+            // package renders as a section of the「本机 Agent 委派」card instead of
+            // its own entry. The probe runs at serve time — a host round-trip past
+            // client plugin boot — so a composed core has already provided the
+            // service; an old or absent core keeps the standalone card below.
+            const ui = ctx.get('localAgentUi');
+            if (typeof ui?.registerHarnessCard === 'function') {
+                return ui.registerHarnessCard({
+                    name: 'claude-code',
+                    // The retired standalone card's order, kept as the section order.
+                    order: 130,
+                    locale: NS,
+                    label: () => t('card.title'),
+                    render: ({ active, useSessions }) => createElement(ClaudeCodeCardSection, { active, useSessions, ...cardFace(), useSettings, t }),
+                });
+            }
+            return ctx.slots.inject('plugins.item', () => ctx.slots.register({
+                name: 'plugins.item',
+                id: 'local-agent-claude-code',
+                // Community cards sort after the official settings pages (orders 10-40).
+                order: 130,
+                label: () => t('card.title'),
+                locale: NS,
+                inject: cardInject,
+            }, ClaudeCodeBundleConfig));
+        });
+    });
 }

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