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

package/lib/types/index.js

@@ -1,13 +1,13 @@
 /**
  * Claude Code harness instantiation of the local-agent family. Registers the
  * `claude-code` harness into the core registry: scoped home under the shared
- * homes root (`CLAUDE_CONFIG_DIR`), login as a manual handoff (claude ≥2.1
- * prints no OAuth URL off a TTY, so `/login` replies with the exact terminal
- * command and the registry watches for the credential), and project-file
- * session records. Delegation mounts through the `claude-local` provider
- * (one-shot `claude -p --output-format json` under the scoped home); the
- * bundle patch's `tool-subagent-claude-code-local` row puts the tool on the
- * profile root, so every agent preset can delegate.
+ * homes root (`CLAUDE_CONFIG_DIR`), endpoint-key authentication (the scope's
+ * `endpoint-auth.json` over the plugin config's `baseUrl`/`apiKey`/
+ * `authToken` triple — no OAuth, no browser flow, nothing to authorize inside
+ * a container), and project-file session records. Delegation mounts through
+ * the `claude-local` provider (one-shot `claude -p` under the scoped home);
+ * the bundle patch's `tool-subagent-claude-code-local` row puts the tool on
+ * the profile root, so every agent preset can delegate.
  *
  * @module @khorsheed/dsh-local-agent-claude-code
  */
@@ -15,19 +15,22 @@ import z from '@deepseek-ai/schemastery';
 import { settingsFace, vol } from '@khorsheed/dsh-local-agent';
 import { endpointHost } from '@khorsheed/dsh-local-agent/types';
 import { ClaudeCliProvider, claudeCliVersion } from './claude-cli-provider.js';
+import { checkClaudeEndpoint, clearEndpointAuth, endpointAuthFileExists, endpointAuthStamp, hasEndpointCredential, readEndpointAuthFile, resolveEndpointAuth, writeEndpointAuth, } from './endpoint-auth.js';
 import { DEFAULT_LIVE_IDLE_MS } from './live-driver.js';
 import { LiveDriverSwitch } from './live-switch.js';
 import { ClaudeModelCatalog } from './model-catalog.js';
 import { ClaudeModelBroker, ClaudeScopedModelMemory } from './model-broker.js';
-import { claudeAuthenticated, claudeCredentialStamp, listClaudeSessions, readClaudeTranscriptModel, syncClaudeCredentialFile } from './records.js';
-import { claudeLogout, provisionClaudeHome, readClaudeConfiguredModel } from './provision.js';
+import { firstModelOf, readModelList, readModelListSync, writeModelList } from '@khorsheed/dsh-local-agent';
+import { listClaudeSessions, readClaudeTranscriptModel } from './records.js';
+import { provisionClaudeHome, readClaudeConfiguredModel } from './provision.js';
 /** Stable Cordis plugin name; the bundle patch row id. */
 export const name = 'local-agent-claude-code';
 /** Services required before the harness can register. */
 export const inject = ['localAgent', 'subagents', 'subprocess', 'settings'];
 /**
  * The settings fields (`live`, `liveMirrorGranularity`, `model`,
- * `recentModels`) ride the plugin Config, marked `.volatile()` where the
+ * `recentModels`, and the endpoint credential `baseUrl`/`apiKey`/`authToken`)
+ * ride the plugin Config, marked `.volatile()` where the
  * host's schemastery has it (3.18.4+, the rc.1 line — probed, never sniffed):
  * there the SettingsForms writes hot-track the running fiber's Volatile
  * references without a remount, and the official one-shot import moves an old
@@ -58,6 +61,8 @@ export const Config = z.object({
     ]),
     model: volatilize(SETTINGS_FIELDS.model),
     baseUrl: z.string(),
+    apiKey: z.string(),
+    authToken: z.string(),
     proxyUrl: z.string(),
     live: volatilize(SETTINGS_FIELDS.live),
     liveIdleMs: z.number().default(DEFAULT_LIVE_IDLE_MS),
@@ -85,7 +90,6 @@ const CLAUDE_SETTINGS_SCHEMA = z.object(SETTINGS_FIELDS);
 export function apply(ctx, config) {
     ctx.effect(() => {
         const permissionMode = config.permissionMode ?? DEFAULT_PERMISSION_MODE;
-        const baseUrl = config.baseUrl;
         const homeDir = ctx.localAgent.homeDir('claude-code');
         // Claude creates the scoped home lazily; create it eagerly so the
         // harness's homeDir contract is uniform with the other harnesses.
@@ -123,15 +127,28 @@ export function apply(ctx, config) {
             legacyBase,
             read: readSettings,
         });
-        // The model is read PER ROUND, not captured at apply: the settings card
-        // writes the same namespace field, so a change has to reach the next
-        // delegation without a plugin reload — exactly like the live toggle.
-        // Blank is not a model: a whitespace-only value means "unset", which is
-        // the pre-key argv.
-        const resolveModel = () => {
+        // The endpoint credential's deployment level: the plugin config triple,
+        // merged per field UNDER the scope's own endpoint-auth.json at resolve
+        // time. Resolved PER READ against the scope's home — a card write (which
+        // lands in the file through the endpointAuth face) takes effect on the
+        // next round with no reload.
+        const endpointConfig = {
+            ...config.baseUrl === undefined ? {} : { baseUrl: config.baseUrl },
+            ...config.apiKey === undefined ? {} : { apiKey: config.apiKey },
+            ...config.authToken === undefined ? {} : { authToken: config.authToken },
+        };
+        const resolveEndpoint = (scopeHome) => resolveEndpointAuth(scopeHome, endpointConfig);
+        // The memberless model key: the plugin-config/settings `model`, blank = unset.
+        const settingsModelKey = () => {
             const model = face.get().model?.trim();
             return model === undefined || model === '' ? undefined : model;
         };
+        // The harness's default model for a scope: the curated model list's
+        // FIRST entry (models.json, edited on the card), ahead of the settings
+        // key; an empty list leaves the pre-existing chain untouched. Read sync
+        // per call — one small file, and a card write always reaches the next
+        // round.
+        const resolveModel = (scope) => firstModelOf(readModelListSync(ctx.localAgent.homeDir('claude-code', scope))) ?? settingsModelKey();
         // The member model layers above the settings key: the session-level
         // override map (the composer's picker writes it through the broker; both
         // round paths and the live spawn read it) and the scoped-settings.json
@@ -152,18 +169,24 @@ export function apply(ctx, config) {
             const named = delegationModel?.trim();
             if (named !== undefined && named !== '')
                 return named;
-            return resolveModel();
+            // The member's scope decides whose list answers: a named scope's rounds
+            // read that scope's models.json, exactly like its endpoint credential.
+            const record = ctx.localAgent.memberBinding?.(childSessionId) ?? ctx.localAgent.getDelegation(childSessionId);
+            return resolveModel(record?.scope);
         };
         const liveSwitch = new LiveDriverSwitch(ctx, face, {
             ...config.permissionMode === undefined ? {} : { permissionMode: config.permissionMode },
-            ...config.baseUrl === undefined ? {} : { baseUrl: config.baseUrl },
+            endpoint: resolveEndpoint,
             ...config.liveIdleMs === undefined ? {} : { liveIdleMs: config.liveIdleMs },
             model: effectiveModel,
             provisionModel: (home, model) => scopedModelMemory.provision(home, model),
         });
         const modelCatalog = new ClaudeModelCatalog({
-            spawn: spec => ctx.subprocess.spawn(spec),
-            ...config.baseUrl === undefined ? {} : { baseUrl: config.baseUrl },
+            endpoint: resolveEndpoint,
+            // Re-key on the config baseUrl; the scope file's own edits (the card's
+            // credential writes land there) are covered by its fingerprint in the
+            // key's file list.
+            endpointLabel: () => config.baseUrl,
             warn: message => ctx.logger.warn(message),
         });
         const modelContext = (childSessionId) => {
@@ -177,6 +200,7 @@ export function apply(ctx, config) {
                 return { home, directory: refresh => refresh ? modelCatalog.refresh(home, binding.cwd) : modelCatalog.read(home, binding.cwd) };
             },
             settingsModel: resolveModel,
+            modelList: scope => readModelListSync(ctx.localAgent.homeDir('claude-code', scope)),
             cliDefault: childSessionId => {
                 const context = modelContext(childSessionId);
                 return context.home === homeDir ? scopedModelMemory.cliDefault(homeDir) : readClaudeConfiguredModel(context.home);
@@ -198,7 +222,7 @@ export function apply(ctx, config) {
             // live-settle report.
             transcriptModel: (cliSessionId, childSessionId) => readClaudeTranscriptModel(modelContext(childSessionId).home, cliSessionId),
         });
-        const disposeProvider = ctx.subagents.registerProvider(new ClaudeCliProvider(ctx, permissionMode, baseUrl, liveSwitch.resolve, effectiveModel));
+        const disposeProvider = ctx.subagents.registerProvider(new ClaudeCliProvider(ctx, permissionMode, resolveEndpoint, liveSwitch.resolve, effectiveModel));
         const disposeHarness = ctx.localAgent.register({
             prepareMember: async ({ binding, childSession, configuration, signal }) => {
                 const driver = liveSwitch.resolve(binding.childSessionId);
@@ -211,57 +235,90 @@ export function apply(ctx, config) {
             displayName: 'Claude Code',
             homeEnvVar: 'CLAUDE_CONFIG_DIR',
             delegationProvider: 'claude-local',
-            login: {
-                // claude ≥2.1 (verified 2.1.235+) runs its auth only on a TTY: under
-                // the pty wrapper it auto-opens the user's browser and prints the
-                // OAuth URL as fallback; the page hands back a code the user pastes
-                // via /claude-code code <value>. The relay env is scrubbed and the
-                // scoped home pinned so the credential lands where delegations read
-                // it (the wrapper passes the harness env through).
-                // The argv pins the config directory itself (an `env NAME=VALUE`
-                // assignment outranks the spawn env), so it is built from the
-                // directory being logged in: `/claude-code login --scope <name>`
-                // authorizes THAT scope, not the default one.
-                pty: {
-                    command: 'env',
-                    args: (scopedHome) => ['-u', 'ANTHROPIC_API_KEY', '-u', 'ANTHROPIC_BASE_URL', `CLAUDE_CONFIG_DIR=${scopedHome}`, 'claude', 'auth', 'login'],
-                },
-                // The watch syncs the keychain credential into the runtime-readable
-                // file first (claude 2.1.236 writes keychain but reads the file),
-                // then probes.
-                watch: async (home) => {
-                    await syncClaudeCredentialFile(home, message => { ctx.logger.warn(message); });
-                    return claudeAuthenticated(home, message => { ctx.logger.warn(message); });
-                },
-            },
+            // No `login` declaration: the harness authenticates by endpoint key
+            // (endpoint-auth.ts), so the core reports the harness as not loginable
+            // and `/claude-code login` answers that there is no login flow — no
+            // browser, no OAuth, nothing to authorize inside a container.
             records: { listSessions: homeDir => listClaudeSessions(homeDir) },
             // A NAMED scope's directory is provisioned through this hook when the
             // registry materializes it — the same eager creation and settings the
             // default scope gets from the apply above.
             provision: scopedHome => provisionClaudeHome(scopedHome, config.proxyUrl).then(() => { }),
-            // The logger is wired here because this probe is the clobber site the
-            // spawn sites do not cover: every status read and every readiness check
-            // reconciles the two credential stores through it.
-            isAuthenticated: home => claudeAuthenticated(home, message => { ctx.logger.warn(message); }),
-            credentialStamp: claudeCredentialStamp,
-            logout: claudeLogout,
+            // Endpoint-key presence: the scope's endpoint-auth.json merged over the
+            // plugin config must carry a non-empty key. The verdict rides the
+            // family's credential grades untouched: presence grades
+            // `present-unverified`, a completed round grades `verified`, a round's
+            // 401 grades `rejected` until the endpoint file's mtime moves past the
+            // mark (editing the file IS the re-login gesture).
+            isAuthenticated: home => resolveEndpoint(home).then(endpoint => hasEndpointCredential(endpoint)),
+            // The settings card's verify button: a cheap token-free probe of the
+            // SAVED endpoint (the reply tells the user to save first when a
+            // credential is missing). Session-less via the gateway Remote.
+            checkEndpoint: home => resolveEndpoint(home).then(endpoint => checkClaudeEndpoint(endpoint)),
+            // The settings card's credential form: read the resolved per-field
+            // state (secrets as booleans), write edits into the scope's own
+            // endpoint-auth.json — the harness's 0600 store, never the profile
+            // patch document. A cleared field falls back to the config triple.
+            endpointAuth: {
+                read: async (home) => {
+                    const endpoint = await resolveEndpoint(home);
+                    return {
+                        ...endpoint.baseUrl === undefined ? {} : { baseUrl: endpoint.baseUrl },
+                        apiKeySet: endpoint.apiKey !== undefined,
+                        authTokenSet: endpoint.authToken !== undefined,
+                    };
+                },
+                write: async (home, fields) => {
+                    const current = await readEndpointAuthFile(home) ?? {};
+                    const next = { ...current };
+                    for (const [field, value] of Object.entries(fields)) {
+                        if (value === undefined)
+                            continue;
+                        const trimmed = typeof value === 'string' ? value.trim() : '';
+                        if (value === null || trimmed === '')
+                            delete next[field];
+                        else
+                            next[field] = trimmed;
+                    }
+                    if (Object.keys(next).length === 0)
+                        await clearEndpointAuth(home);
+                    else
+                        await writeEndpointAuth(home, next);
+                },
+            },
+            credentialStamp: endpointAuthStamp,
+            // Logout clears the scope's OWN endpoint file. A config-sourced
+            // credential outlives it — said out loud, or the status would flip
+            // right back and read as a failed logout.
+            logout: async (home) => {
+                if (await endpointAuthFileExists(home)) {
+                    await clearEndpointAuth(home);
+                    return;
+                }
+                throw new Error('claude-code has no scoped endpoint-auth.json to clear — the credential comes from the settings card or the profile row (baseUrl/apiKey/authToken); clear it there instead');
+            },
             // The model surface: the settings card reads the memberless info ("what
             // would a round run with"), the member composer reads and switches a
             // member's session-level override through the same broker.
             modelBroker,
+            // The settings card's curated model list (the default scope's
+            // models.json; named scopes carry their own, read per round).
+            modelList: {
+                read: home => readModelList(home),
+                write: (home, models) => writeModelList(home, models),
+            },
             // The eval snapshot: the permission mode is the plugin config resolved
             // at apply (it selects the spawn flags); the endpoint mirrors the
-            // provider's own resolution order — the config item wins over the host
-            // process environment's ANTHROPIC_BASE_URL. The model follows the
-            // family's fixed order: the plugin config key (it rides every argv)
-            // before the scoped settings.json's own `model`. The CLI's own default
-            // model is never guessed, so neither one configured means no field.
-            // The directory is a PARAMETER, not the apply-time capture: a status
-            // read (or an evaluation snapshot) of a named scope must report the
-            // settings that scope's rounds would run with.
+            // provider's own resolution — the scope's file over the config triple.
+            // The model follows the family's fixed order: the plugin config key (it
+            // rides every argv) before the scoped settings.json's own `model`. The
+            // CLI's own default model is never guessed, so neither one configured
+            // means no field. The directory is a PARAMETER, not the apply-time
+            // capture: a status read (or an evaluation snapshot) of a named scope
+            // must report the settings that scope's rounds would run with.
             effectiveSettings: async (scopedHome) => {
-                const effectiveBaseUrl = baseUrl ?? process.env.ANTHROPIC_BASE_URL;
-                const baseUrlHost = effectiveBaseUrl !== undefined ? endpointHost(effectiveBaseUrl) : undefined;
+                const endpoint = await resolveEndpoint(scopedHome);
+                const baseUrlHost = endpoint.baseUrl !== undefined ? endpointHost(endpoint.baseUrl) : undefined;
                 const [scopedModel, cliVersion] = await Promise.all([
                     readClaudeConfiguredModel(scopedHome).catch(() => undefined),
                     claudeCliVersion(ctx, scopedHome).catch(() => undefined),
@@ -270,7 +327,7 @@ export function apply(ctx, config) {
                 return {
                     drive: face.get().live ? 'live' : 'exec',
                     permissionMode,
-                    baseUrlSet: effectiveBaseUrl !== undefined,
+                    baseUrlSet: endpoint.baseUrl !== undefined,
                     ...baseUrlHost !== undefined ? { baseUrlHost } : {},
                     ...model !== undefined ? { model } : {},
                     ...cliVersion !== undefined ? { cliVersion } : {},
@@ -287,6 +344,15 @@ export function apply(ctx, config) {
                             : records.map(r => `${r.id} ${r.workDir}`).join('\n'),
                     }));
                 }
+                // `/claude-code check`: the settings card's verify button — a cheap
+                // token-free probe of the SAVED endpoint (the reply tells the user to
+                // save first when a credential is missing).
+                if (verb === 'check') {
+                    const scopeHome = invocation.agent.ctx.localAgent.homeDir('claude-code');
+                    return resolveEndpoint(scopeHome)
+                        .then(endpoint => checkClaudeEndpoint(endpoint))
+                        .then(text => ({ kind: 'success', text }));
+                }
                 return undefined;
             },
         });

package/lib/types/live-driver.d.ts

@@ -3,6 +3,7 @@ import type { Context } from '@deepseek-ai/cordis';
 import type { Session } from '@deepseek-ai/dsh-session';
 import { type SubagentRun, type SubagentStartRequest } from '@deepseek-ai/dsh-subagent';
 import type { Config } from './index.ts';
+import type { ClaudeEndpointAuth } from './endpoint-auth.ts';
 /** Default idle lifetime of an unused resident runtime before reclaim. */
 export declare const DEFAULT_LIVE_IDLE_MS: number;
 /** Default timeout for the turn's system/init ack (a cold boot can be slow). */
@@ -15,11 +16,6 @@ export declare const DEFAULT_LIVE_CHANNEL_RETRY_MS: number;
 export declare const DEFAULT_SNAPSHOT_MIN_INTERVAL_MS = 50;
 /** Default minimum text growth between one streaming kind's snapshot messages. */
 export declare const DEFAULT_SNAPSHOT_MIN_CHARS = 0;
-/**
- * The stream-json channel could not come up (spawn failure or the first
- * turn's init never arrived). The provider catches exactly this and falls
- * back to the exec one-shot; any other error is a real round failure.
- */
 export declare class LiveChannelUnavailableError extends Error {
     constructor(message: string);
 }
@@ -85,7 +81,14 @@ export declare class ClaudeLiveDriver {
      */
     private draining;
     private readonly disposeController;
-    constructor(ctx: Context, config: Pick<Config, 'permissionMode' | 'baseUrl'> & {
+    constructor(ctx: Context, config: Pick<Config, 'permissionMode'> & {
+        /**
+         * Resolver for the spawn's endpoint credential (endpoint-auth.ts: the
+         * member's scoped endpoint-auth.json over the plugin config triple),
+         * read per RUNTIME SPAWN — a key rotation reaches the resident process
+         * at its next respawn. Absent, no `ANTHROPIC_*` variables are set.
+         */
+        endpoint?: (homeDir: string) => Promise<ClaudeEndpointAuth>;
         liveIdleMs?: number;
         liveMirrorGranularity?: ClaudeLiveMirrorGranularity;
         /** Maximum batching wait for incremental streaming messages. */