@khorsheed/dsh-local-agent-claude-code 0.1.0-rc.6

package/lib/types/model-catalog.js

@@ -0,0 +1,118 @@
+import { dirname, join } from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
+import { ModelDirectoryCache, delegationEnv, modelDirectoryContextKey } from '@khorsheed/dsh-local-agent';
+import { ClaudeControlRequests } from './control-requests.js';
+/** Initialize's native picker vocabulary, not an account entitlement claim. */
+export function claudeDirectory(result) {
+    const models = result['models'];
+    if (models === undefined)
+        return { entries: [], complete: false, customInput: true, unsupported: true, reason: 'This Claude CLI does not expose a native model directory' };
+    if (!Array.isArray(models))
+        throw new Error('Claude initialize returned an invalid model directory');
+    const entries = new Map();
+    for (const candidate of models) {
+        if (typeof candidate !== 'object' || candidate === null)
+            continue;
+        const model = candidate;
+        const value = typeof model['value'] === 'string' ? model['value'].trim() : '';
+        if (value === '' || entries.has(value))
+            continue;
+        const levels = model['supportedEffortLevels'];
+        const options = Array.isArray(levels) ? levels.flatMap(level => typeof level === 'string' && level !== '' ? [{ value: level, label: level }] : []) : undefined;
+        entries.set(value, {
+            value, label: typeof model['displayName'] === 'string' ? model['displayName'] : value, source: 'native',
+            ...typeof model['resolvedModel'] === 'string' ? { resolvedModel: model['resolvedModel'] } : {},
+            ...typeof model['description'] === 'string' ? { description: model['description'] } : {},
+            ...options === undefined ? {} : { reasoning: { options } },
+        });
+    }
+    return { entries: [...entries.values()], complete: true, customInput: true, ...entries.has('default') ? { defaultModel: 'default' } : {} };
+}
+/** Scoped native control probe. Never syncs credentials, writes settings or submits a user turn. */
+export class ClaudeModelCatalog {
+    deps;
+    cache;
+    constructor(deps) {
+        this.deps = deps;
+        this.cache = new ModelDirectoryCache({
+            load: (key, signal) => {
+                const context = JSON.parse(key);
+                return this.probe(context.homeDir, context.cwd, signal);
+            },
+            ...deps.ttlMs === undefined ? {} : { ttlMs: deps.ttlMs },
+            onError: error => deps.warn?.(`Claude model discovery failed: ${error instanceof Error ? error.message : String(error)}`),
+        });
+    }
+    key(homeDir, cwd = homeDir) {
+        const files = [join(homeDir, 'settings.json'), join(homeDir, '.credentials.json'), join(homeDir, '.claude.json')];
+        for (let directory = cwd;; directory = dirname(directory)) {
+            files.push(join(directory, '.claude', 'settings.json'), join(directory, '.claude', 'settings.local.json'));
+            if (dirname(directory) === directory)
+                break;
+        }
+        return modelDirectoryContextKey({ provider: 'claude-code', homeDir, cwd, cli: [this.deps.cli ?? 'claude'], files, ...this.deps.baseUrl === undefined ? {} : { endpoint: this.deps.baseUrl } });
+    }
+    read(homeDir, cwd) { return this.cache.read(this.key(homeDir, cwd)); }
+    refresh(homeDir, cwd) { return this.cache.refresh(this.key(homeDir, cwd)); }
+    follow(homeDir, cwd, signal) { return this.cache.follow(() => this.key(homeDir, cwd), signal); }
+    invalidate(homeDir, cwd) { this.cache.invalidate(this.key(homeDir, cwd)); }
+    dispose() { this.cache.dispose(); }
+    async probe(homeDir, cwd, signal) {
+        const child = this.deps.spawn({
+            argv: [this.deps.cli ?? 'claude', '-p', '--verbose', '--input-format', 'stream-json', '--output-format', 'stream-json',
+                '--no-session-persistence', '--settings', '{"disableAllHooks":true}', '--strict-mcp-config', '--mcp-config', '{"mcpServers":{}}', '--'],
+            cwd, stdio: { stdin: 'pipe', stdout: 'pipe', stderr: 'pipe' }, graceMs: 2_000,
+            env: delegationEnv({ CLAUDE_CONFIG_DIR: homeDir, ...this.deps.baseUrl === undefined ? {} : { ANTHROPIC_BASE_URL: this.deps.baseUrl } }),
+        });
+        const controls = new ClaudeControlRequests(frame => {
+            if (child.stdin === undefined)
+                throw new Error('Claude discovery stdin is unavailable');
+            child.stdin.write(JSON.stringify(frame) + '\n');
+        }, this.deps.timeoutMs ?? 5_000);
+        const decoder = new StringDecoder('utf8');
+        let buffer = '';
+        child.stdout?.on('data', (chunk) => {
+            buffer += decoder.write(chunk);
+            if (buffer.length > 1_048_576) {
+                controls.close();
+                child.terminate();
+                return;
+            }
+            let index;
+            while ((index = buffer.indexOf('\n')) >= 0) {
+                const line = buffer.slice(0, index);
+                buffer = buffer.slice(index + 1);
+                let event;
+                try {
+                    event = JSON.parse(line);
+                }
+                catch {
+                    continue;
+                }
+                if (controls.accept(event))
+                    continue;
+                if (event['type'] === 'control_request' && typeof event['request_id'] === 'string') {
+                    child.stdin?.write(JSON.stringify({ type: 'control_response', response: { subtype: 'error', request_id: event['request_id'], error: 'Model discovery does not execute tools' } }) + '\n');
+                }
+            }
+        });
+        child.stderr?.on('data', () => { });
+        void child.done.then(() => controls.close(), () => controls.close());
+        let cleanupTimer;
+        try {
+            return claudeDirectory(await controls.request({ subtype: 'initialize', hooks: {} }, signal));
+        }
+        finally {
+            controls.close();
+            child.stdin?.end();
+            await Promise.race([child.done.catch(() => { }), new Promise(resolve => {
+                    cleanupTimer = setTimeout(resolve, 1_000);
+                    cleanupTimer.unref();
+                })]);
+            if (cleanupTimer !== undefined)
+                clearTimeout(cleanupTimer);
+            child.terminate();
+            await child.waitForExit().catch(() => { });
+        }
+    }
+}

package/lib/types/provision.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Claude Code scoped-home provisioning. Unlike codex (whose credential store
+ * must be pinned to a file) and kimi (which needs a provider config),
+ * claude's `CLAUDE_CONFIG_DIR` scoped home needs nothing beyond the
+ * directory itself: login via `claude auth login` writes `.claude.json`
+ * (with the `oauthAccount` record) into it, and the real credential lands in
+ * the macOS keychain under a hashed entry or — on Linux, despite upstream
+ * bug #47661 — in the default `~/.claude/.credentials.json` while the config
+ * stays scoped. Sign-out removes the scoped config so `status` reports not
+ * authenticated; the keychain entry on macOS persists until the CLI removes
+ * it, which the framework's file-based logout cannot reach.
+ * @module @khorsheed/dsh-local-agent-claude-code/provision
+ */
+/**
+ * Provision the scoped home directory. Claude creates it lazily on first
+ * use, but creating it eagerly keeps the harness's homeDir contract uniform
+ * with the other harnesses. When `proxyUrl` is configured, the scoped
+ * `settings.json` gains an env block pointing the CLI's own traffic at it —
+ * claude reads proxy settings from this file, so the child works even when
+ * the host process environment carries no proxy (a supervisor-spawned
+ * instance's env is not the user's shell env). An existing settings file is
+ * merged, not overwritten; only the two proxy keys are managed.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @param proxyUrl - optional HTTP proxy URL for the child CLI's traffic.
+ */
+export declare function provisionClaudeHome(homeDir: string, proxyUrl?: string): Promise<void>;
+/**
+ * Read the scoped settings' configured model: the `model` key of
+ * `<homeDir>/settings.json` — the model a delegation round pins when the
+ * scoped settings name one at all. Claude's own default model is decided by
+ * the CLI and is deliberately NOT guessed here. Only the scoped file is
+ * consulted (never the host's `~/.claude`); absent or malformed content
+ * yields undefined.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @returns the configured model identifier, or undefined when none is set.
+ */
+export declare function readClaudeConfiguredModel(homeDir: string): Promise<string | undefined>;
+/** Read the scoped native effort setting without changing the settings file. */
+export declare function readClaudeConfiguredEffort(homeDir: string): Promise<string | undefined>;
+/**
+ * Write (or, with undefined, remove) the scoped settings.json `model` key,
+ * merging the rest of the file exactly as {@link provisionClaudeHome} merges
+ * its env block. Only the live driver calls this: a resident runtime needs
+ * its member's effective model IN THE FILE, because a `--resume` respawn
+ * restores the session's own stored model over the `--model` flag. The exec
+ * path never calls it — its `--model` flag always applies, and the file
+ * stays exactly as the person edited it.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @param model - the model to scratch in, or undefined to remove the key.
+ */
+export declare function writeClaudeScopedModel(homeDir: string, model: string | undefined): Promise<void>;
+/**
+ * Sign out of the scoped account: remove the scoped config file, so
+ * `/<name> status` reports not authenticated and the next login authorizes
+ * a fresh account. The macOS keychain entry (a hashed
+ * `Claude Code-credentials-<sha256(path)[:8]>` record keyed to the scoped
+ * home path) is NOT removed — the CLI's `claude auth logout` owns that, and
+ * the harness logout contract is file-based; the stale entry is harmless
+ * because a fresh login rewrites the same hashed slot.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ */
+export declare function claudeLogout(homeDir: string): Promise<void>;
+//# sourceMappingURL=provision.d.ts.map

package/lib/types/provision.js

@@ -0,0 +1,132 @@
+/**
+ * Claude Code scoped-home provisioning. Unlike codex (whose credential store
+ * must be pinned to a file) and kimi (which needs a provider config),
+ * claude's `CLAUDE_CONFIG_DIR` scoped home needs nothing beyond the
+ * directory itself: login via `claude auth login` writes `.claude.json`
+ * (with the `oauthAccount` record) into it, and the real credential lands in
+ * the macOS keychain under a hashed entry or — on Linux, despite upstream
+ * bug #47661 — in the default `~/.claude/.credentials.json` while the config
+ * stays scoped. Sign-out removes the scoped config so `status` reports not
+ * authenticated; the keychain entry on macOS persists until the CLI removes
+ * it, which the framework's file-based logout cannot reach.
+ * @module @khorsheed/dsh-local-agent-claude-code/provision
+ */
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** The scoped config file holding the oauthAccount auth marker. */
+const SCOPED_CONFIG = '.claude.json';
+/** The scoped settings file carrying the CLI's env block. */
+const SCOPED_SETTINGS = 'settings.json';
+/**
+ * Provision the scoped home directory. Claude creates it lazily on first
+ * use, but creating it eagerly keeps the harness's homeDir contract uniform
+ * with the other harnesses. When `proxyUrl` is configured, the scoped
+ * `settings.json` gains an env block pointing the CLI's own traffic at it —
+ * claude reads proxy settings from this file, so the child works even when
+ * the host process environment carries no proxy (a supervisor-spawned
+ * instance's env is not the user's shell env). An existing settings file is
+ * merged, not overwritten; only the two proxy keys are managed.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @param proxyUrl - optional HTTP proxy URL for the child CLI's traffic.
+ */
+export async function provisionClaudeHome(homeDir, proxyUrl) {
+    await mkdir(homeDir, { recursive: true });
+    if (proxyUrl === undefined)
+        return;
+    const path = join(homeDir, SCOPED_SETTINGS);
+    let settings = {};
+    try {
+        settings = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        // Absent or malformed: start fresh (a malformed file is replaced, not merged).
+    }
+    const env = (settings.env ?? {});
+    if (env.https_proxy === proxyUrl && env.http_proxy === proxyUrl)
+        return;
+    env.https_proxy = proxyUrl;
+    env.http_proxy = proxyUrl;
+    settings.env = env;
+    await writeFile(path, JSON.stringify(settings, undefined, 2) + '\n');
+}
+/**
+ * Read the scoped settings' configured model: the `model` key of
+ * `<homeDir>/settings.json` — the model a delegation round pins when the
+ * scoped settings name one at all. Claude's own default model is decided by
+ * the CLI and is deliberately NOT guessed here. Only the scoped file is
+ * consulted (never the host's `~/.claude`); absent or malformed content
+ * yields undefined.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @returns the configured model identifier, or undefined when none is set.
+ */
+export async function readClaudeConfiguredModel(homeDir) {
+    let text;
+    try {
+        text = await readFile(join(homeDir, SCOPED_SETTINGS), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        const settings = JSON.parse(text);
+        return typeof settings.model === 'string' && settings.model !== '' ? settings.model : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Read the scoped native effort setting without changing the settings file. */
+export async function readClaudeConfiguredEffort(homeDir) {
+    try {
+        const settings = JSON.parse(await readFile(join(homeDir, SCOPED_SETTINGS), 'utf8'));
+        return typeof settings.effortLevel === 'string' && settings.effortLevel.trim() !== '' ? settings.effortLevel.trim() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Write (or, with undefined, remove) the scoped settings.json `model` key,
+ * merging the rest of the file exactly as {@link provisionClaudeHome} merges
+ * its env block. Only the live driver calls this: a resident runtime needs
+ * its member's effective model IN THE FILE, because a `--resume` respawn
+ * restores the session's own stored model over the `--model` flag. The exec
+ * path never calls it — its `--model` flag always applies, and the file
+ * stays exactly as the person edited it.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @param model - the model to scratch in, or undefined to remove the key.
+ */
+export async function writeClaudeScopedModel(homeDir, model) {
+    const path = join(homeDir, SCOPED_SETTINGS);
+    let settings = {};
+    try {
+        settings = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        // Absent or malformed: start fresh (a malformed file is replaced, not merged).
+    }
+    if (model === undefined) {
+        if (!('model' in settings))
+            return;
+        delete settings['model'];
+    }
+    else {
+        if (settings['model'] === model)
+            return;
+        settings['model'] = model;
+    }
+    await writeFile(path, JSON.stringify(settings, undefined, 2) + '\n');
+}
+/**
+ * Sign out of the scoped account: remove the scoped config file, so
+ * `/<name> status` reports not authenticated and the next login authorizes
+ * a fresh account. The macOS keychain entry (a hashed
+ * `Claude Code-credentials-<sha256(path)[:8]>` record keyed to the scoped
+ * home path) is NOT removed — the CLI's `claude auth logout` owns that, and
+ * the harness logout contract is file-based; the stale entry is harmless
+ * because a fresh login rewrites the same hashed slot.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ */
+export async function claudeLogout(homeDir) {
+    await rm(join(homeDir, SCOPED_CONFIG), { force: true });
+}

package/lib/types/records.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Claude Code session records adapter: scans the scoped home's `projects/`
+ * session files (one JSONL per session under `projects/<cwd-slug>/`, the
+ * slug being the workspace path with separators replaced by dashes), plus
+ * the transcript model read-back ({@link readClaudeTranscriptModel}) the
+ * model broker's `lastObserved` backstop runs on. The
+ * slug is a LOSSY encoding of the cwd — different paths can collide on the
+ * same slug — so the listed cwd always comes from the file CONTENT (the
+ * first `user` event's `cwd` field), never from the directory name. Only the
+ * head of each file is read — the first user event carries the id, cwd, and
+ * timestamp the listing needs; the rest of the file (conversation) is not
+ * parsed. Files are append-only with torn-tail tolerance, and contents are
+ * always untrusted input.
+ * @module @khorsheed/dsh-local-agent-claude-code/records
+ */
+import { execFile } from 'node:child_process';
+import type { LocalAgentSessionRecord } from '@khorsheed/dsh-local-agent';
+/** Test-swappable process exec (the keychain read goes through `security`). */
+export declare const internals: {
+    exec: typeof execFile.__promisify__;
+};
+/**
+ * The scoped `.claude.json`'s modification stamp (epoch ms), undefined when
+ * absent. A completed login rewrites this file, so the stamp distinguishes a
+ * fresh login from a leftover marker (a revoked token's record lingers).
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @returns the marker's mtime, or undefined when no scoped config exists.
+ */
+export declare function claudeCredentialStamp(homeDir: string): Promise<number | undefined>;
+/**
+ * Reconcile the keychain credential with `<homeDir>/.credentials.json`,
+ * NEWER WINS. Claude 2.1.236 on macOS WRITES the scoped login to the hashed
+ * keychain entry but READS the credentials file at runtime (the same
+ * write/read split as the Linux #47661 bug) — a login that lands only in the
+ * keychain still answers "Not logged in", so the file has to be kept current.
+ *
+ * The file is not this process's private mirror, though: a containerized
+ * round bind-mounts this very directory read-write (the unit has no keychain,
+ * so the CLI inside it reads and writes the file), and the pre-spawn sync runs
+ * against the HOST path moments before the unit reads it through the mount.
+ * An unconditional mirror therefore makes this function the one participant
+ * that can move the credential chain BACKWARD: it hands the next run a refresh
+ * token the other writer already spent, the endpoint rejects it, and the CLI
+ * answers by CLEARING the file — which logs the instance out, because that
+ * file is the instance's credential. So the keychain blob is written only when
+ * it is not older than the file's. Undefined expiry on either side keeps the
+ * pre-newer-wins behavior (the keychain writes), and a file that is not USABLE
+ * never wins.
+ *
+ * Only a USABLE blob (non-empty token, see `readKeychainCredential`) is
+ * mirrored; with none in the keychain, a file holding an empty-token shell —
+ * debris from an earlier first-match read, or a cleared credential — is
+ * REMOVED, so the runtime says "Not logged in" instead of the misleading
+ * "OAuth session expired". Idempotent and content-compare before write.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @param log - warn channel for the two decisions that used to be silent.
+ * @returns true when a usable credential is in the file after the call.
+ */
+export declare function syncClaudeCredentialFile(homeDir: string, log?: (message: string) => void): Promise<boolean>;
+/**
+ * Whether the scoped home holds usable Claude Code credentials: the scoped
+ * `.claude.json` carries an `oauthAccount` record once a device-code login
+ * has completed, AND the keychain credential is not past its stored expiry
+ * (when the expiry is readable — a server-side REVOCATION is not visible
+ * locally; providers report those through `localAgent.reportAuthFailure`).
+ * The real credential lives in the macOS keychain under a hashed entry
+ * (`Claude Code-credentials-<sha256(path)[:8]>`, hashed from the config-dir
+ * path) or in the default `~/.claude/.credentials.json` on Linux (upstream
+ * bug #47661: `CLAUDE_CONFIG_DIR` does not isolate the credentials file
+ * there — it writes the scoped dir but READS the default home, so Linux
+ * credentials may exist even when the scoped home has none). Spawning the
+ * CLI to probe auth is avoided; the platform differences are documented in
+ * the README.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @param log - warn channel handed to the credential reconcile below.
+ * @returns true when a completed login is recorded and not locally expired.
+ */
+export declare function claudeAuthenticated(homeDir: string, log?: (message: string) => void): Promise<boolean>;
+/**
+ * Parse the head of a session file for the listing fields. The first `user`
+ * event carries `sessionId`, `cwd`, and `timestamp`; its `cwd` is the only
+ * trustworthy workspace source (the directory slug is lossy). Unknown or
+ * malformed values yield an undefined record rather than failing the list.
+ * @param text - the raw session file head (only the head is read).
+ * @returns the record, or undefined when no user event is found.
+ */
+export declare function projectRecord(text: string): LocalAgentSessionRecord | undefined;
+/**
+ * Read the scoped home's session files. The listing walks the projects
+ * directory and reads each jsonl head; a torn or malformed file is skipped
+ * rather than failing the whole list.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @returns the parsed records, empty when no sessions exist yet.
+ */
+export declare function listClaudeSessions(homeDir: string): Promise<readonly LocalAgentSessionRecord[]>;
+/**
+ * The model a member's OWN CLI transcript names — the history backstop for
+ * the broker's `lastObserved` when no delegation record observed one (every
+ * member whose rounds predate the live-settle report). The live-settle
+ * channel remains primary (the record's `observedModel` wins when present);
+ * this reader only answers "what did this session last run" from the CLI's
+ * own files, read-only — nothing is backfilled into `delegations.jsonl`.
+ *
+ * Location rule: with `cliSessionId`, the main transcript
+ * `projects/<cwd-slug>/<cliSessionId>.jsonl` (found by NAME across the
+ * project dirs — the slug is lossy, so it is never computed); when it is
+ * absent, a sidechain `agent-*.jsonl` whose head names the session id
+ * (bounded candidate count) answers instead. Without `cliSessionId` (the
+ * settings card's memberless read), the NEWEST transcript across the
+ * projects tree (mtime, bounded dir/file scan) answers; a newest file that
+ * names no model yields to the next, up to a few tries. Every failure —
+ * missing tree, unreadable file, no model in the read window — is
+ * `undefined`, never a throw.
+ * @param homeDir - the `claude-code` harness's scoped home.
+ * @param cliSessionId - the delegation record's CLI session id, when the
+ *   member's own transcript is wanted.
+ * @returns the model identifier, or undefined.
+ */
+export declare function readClaudeTranscriptModel(homeDir: string, cliSessionId?: string): Promise<string | undefined>;
+//# sourceMappingURL=records.d.ts.map