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

package/lib/types/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * 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.
+ *
+ * @module @khorsheed/dsh-local-agent-claude-code
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Stable Cordis plugin name; the bundle patch row id. */
+export declare const name = "local-agent-claude-code";
+/** Services required before the harness can register. */
+export declare const inject: string[];
+/** Plugin config: the permission mode fresh delegations default to, plus the live driver. */
+export interface Config {
+    /**
+     * `claude -p` permission handling; `skip` passes
+     * `--dangerously-skip-permissions` so the child can write files without an
+     * interactive approval prompt. Defaults to `skip` because a one-shot CLI
+     * subagent has no approval surface.
+     */
+    permissionMode?: 'skip' | 'normal';
+    /**
+     * The model every delegation round starts the CLI with (`claude -p --model
+     * <model>`, the same flag in resident mode). Absent — the default — passes
+     * NO model flag at all: the scoped `settings.json`'s own `model`, or the
+     * CLI's built-in default with none, decides exactly as it did before this
+     * key existed. The settings card writes the same key, so a change applies
+     * to the next round without a reload.
+     */
+    model?: string;
+    /**
+     * `ANTHROPIC_BASE_URL` for the child CLI; absent inherits the host
+     * process environment (a user-level proxy like `https://proxy.example.com/anthropic`
+     * is typically exported there). Set when delegations must route through a
+     * different endpoint than the login flow used.
+     */
+    baseUrl?: string;
+    /**
+     * HTTP proxy for the child CLI's own traffic (model calls AND OAuth
+     * refresh), provisioned into the scoped `settings.json` env block. Needed
+     * when the host process environment carries no proxy (a supervisor-spawned
+     * instance does not inherit the user's shell exports).
+     */
+    proxyUrl?: string;
+    /**
+     * Live driver: keep one resident stream-json process per member and drive
+     * turns over stdin messages (runtime-level graceful interrupt, same-shape
+     * push stream) instead of one `claude -p` process per round. Default off;
+     * the exec one-shot stays the fallback whenever the channel cannot come up.
+     */
+    live?: boolean;
+    /** Idle lifetime of an unused resident runtime before reclaim. */
+    liveIdleMs?: number;
+    /** @deprecated Accepted for old profiles; live output is always incremental. */
+    liveMirrorGranularity?: 'event' | 'token';
+    /** Model identifiers the settings card saved before (settings field). */
+    recentModels?: readonly string[];
+}
+export declare const Config: z;
+/** The permission mode a fresh delegation defaults to. */
+export declare const DEFAULT_PERMISSION_MODE: NonNullable<Config['permissionMode']>;
+/**
+ * Settings namespace for the settings-page card. The Cordis config feeds the
+ * composition `base` layer, so a field absent from the user layer inherits the
+ * YAML value — the card only ever stores deliberate overrides.
+ */
+export declare const CLAUDE_SETTINGS_NAMESPACE = "local-agent-claude-code";
+/**
+ * Register the Claude Code harness into the local-agent registry.
+ * @param ctx - plugin context carrying the registry.
+ * @param config - plugin config; `permissionMode` selects the `claude -p` policy.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,300 @@
+/**
+ * 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.
+ *
+ * @module @khorsheed/dsh-local-agent-claude-code
+ */
+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 { 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';
+/** 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
+ * 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
+ * settings.yaml section into this row's config. On 0.1.5 the call is absent,
+ * the fields stay plain config keys (a semantic superset — the profile row
+ * can now preset them too), and the legacy settings namespace below carries
+ * the user layer exactly as before. `model` deliberately carries NO default:
+ * an unset key must resolve to undefined, which is what keeps the pre-key
+ * behavior byte-identical.
+ */
+const SETTINGS_FIELDS = {
+    live: z.boolean().default(false),
+    liveMirrorGranularity: z.union([z.const('event'), z.const('token')]).default('token'),
+    model: z.string(),
+    recentModels: z.array(z.string()).default([]),
+};
+/** Mark one schema field volatile when the host's schemastery has the method (rc.1), pass it through plain when not (0.1.5). */
+function volatilize(field) {
+    return typeof field.volatile === 'function' ? field.volatile() : field;
+}
+// Bare `z` annotation: `z<Config>` fails schemastery 3.18.4's variance under
+// exactOptionalPropertyTypes (TS2375) and dropping the annotation trips
+// TS2742; the interface stays the apply signature's contract.
+export const Config = z.object({
+    permissionMode: z.union([
+        z.const('skip'),
+        z.const('normal'),
+    ]),
+    model: volatilize(SETTINGS_FIELDS.model),
+    baseUrl: z.string(),
+    proxyUrl: z.string(),
+    live: volatilize(SETTINGS_FIELDS.live),
+    liveIdleMs: z.number().default(DEFAULT_LIVE_IDLE_MS),
+    liveMirrorGranularity: volatilize(SETTINGS_FIELDS.liveMirrorGranularity),
+    recentModels: volatilize(SETTINGS_FIELDS.recentModels),
+});
+/** The permission mode a fresh delegation defaults to. */
+export const DEFAULT_PERMISSION_MODE = 'skip';
+/**
+ * Settings namespace for the settings-page card. The Cordis config feeds the
+ * composition `base` layer, so a field absent from the user layer inherits the
+ * YAML value — the card only ever stores deliberate overrides.
+ */
+export const CLAUDE_SETTINGS_NAMESPACE = 'local-agent-claude-code';
+/**
+ * The card's 0.1.5 schema; field defaults are the innermost layer below
+ * `base`. Shared with the Config schema's settings fields above.
+ */
+const CLAUDE_SETTINGS_SCHEMA = z.object(SETTINGS_FIELDS);
+/**
+ * Register the Claude Code harness into the local-agent registry.
+ * @param ctx - plugin context carrying the registry.
+ * @param config - plugin config; `permissionMode` selects the `claude -p` policy.
+ */
+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.
+        void provisionClaudeHome(homeDir, config.proxyUrl).catch((error) => {
+            ctx.logger.warn(`local-agent-claude-code: scoped home provisioning failed: ${error instanceof Error ? error.message : String(error)}`);
+        });
+        // The live driver is settings-driven: the settings card's toggle (user
+        // layer over the YAML composition base) swaps driver generations without
+        // a reload. Toggling OFF drains the retiring generation — new rounds fall
+        // back to exec, in-flight rounds finish on their runtime, idle runtimes
+        // are reclaimed at once. Legacy granularity settings are accepted but ignored.
+        // The settings face hides the two host lines: 0.1.5 serves the legacy
+        // namespace scope (register + base); rc.1 reads the row config's volatile
+        // fields and re-reads on `settings/document-updated`. Both hot-apply the
+        // card's writes without a reload.
+        const readSettings = () => {
+            const model = vol(config.model);
+            const recentModels = vol(config.recentModels);
+            return {
+                live: vol(config.live) ?? false,
+                liveMirrorGranularity: vol(config.liveMirrorGranularity) ?? 'token',
+                ...model === undefined ? {} : { model },
+                ...recentModels === undefined ? {} : { recentModels },
+            };
+        };
+        const legacyBase = {};
+        for (const field of ['live', 'liveMirrorGranularity', 'model']) {
+            const value = vol(config[field]);
+            if (value !== undefined)
+                legacyBase[field] = value;
+        }
+        const face = settingsFace(ctx, {
+            namespace: CLAUDE_SETTINGS_NAMESPACE,
+            legacySchema: CLAUDE_SETTINGS_SCHEMA,
+            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 = () => {
+            const model = face.get().model?.trim();
+            return model === undefined || model === '' ? undefined : model;
+        };
+        // 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
+        // scratch memory (a live spawn writes the member's effective model into
+        // the file because a --resume respawn honors it over the --model flag;
+        // the memory keeps the person's own configured value straight across
+        // those writes).
+        const overrides = new Map();
+        const scopedModelMemory = new ClaudeScopedModelMemory();
+        // The member's effective model in the family's fixed order: override,
+        // then the round's delegation model, then the settings key. The scoped
+        // file and the CLI's built-in default decide below that, as they always
+        // did — they need no argv representation.
+        const effectiveModel = (childSessionId, delegationModel) => {
+            const own = overrides.get(childSessionId)?.trim();
+            if (own !== undefined && own !== '')
+                return own;
+            const named = delegationModel?.trim();
+            if (named !== undefined && named !== '')
+                return named;
+            return resolveModel();
+        };
+        const liveSwitch = new LiveDriverSwitch(ctx, face, {
+            ...config.permissionMode === undefined ? {} : { permissionMode: config.permissionMode },
+            ...config.baseUrl === undefined ? {} : { baseUrl: config.baseUrl },
+            ...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 },
+            warn: message => ctx.logger.warn(message),
+        });
+        const modelContext = (childSessionId) => {
+            const record = childSessionId === undefined ? undefined : ctx.localAgent.memberBinding?.(childSessionId) ?? ctx.localAgent.getDelegation(childSessionId);
+            return { home: ctx.localAgent.homeDir('claude-code', record?.scope), cwd: record?.cwd };
+        };
+        const modelBroker = new ClaudeModelBroker({
+            localAgent: ctx.localAgent,
+            configurationContext: binding => {
+                const home = ctx.localAgent.homeDir('claude-code', binding.scope);
+                return { home, directory: refresh => refresh ? modelCatalog.refresh(home, binding.cwd) : modelCatalog.read(home, binding.cwd) };
+            },
+            settingsModel: resolveModel,
+            cliDefault: childSessionId => {
+                const context = modelContext(childSessionId);
+                return context.home === homeDir ? scopedModelMemory.cliDefault(homeDir) : readClaudeConfiguredModel(context.home);
+            },
+            directory: (childSessionId, refresh) => {
+                const context = modelContext(childSessionId);
+                return refresh ? modelCatalog.refresh(context.home, context.cwd) : modelCatalog.read(context.home, context.cwd);
+            },
+            followDirectory: (childSessionId, signal) => {
+                const context = modelContext(childSessionId);
+                return modelCatalog.follow(context.home, context.cwd, signal);
+            },
+            recentModels: () => face.get().recentModels ?? [],
+            live: () => face.get().live,
+            overrides,
+            liveSwitch,
+            // The lastObserved backstop: the member's own transcript (or the
+            // tree's newest) answers for every round that predates the
+            // 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 disposeHarness = ctx.localAgent.register({
+            prepareMember: async ({ binding, childSession, configuration, signal }) => {
+                const driver = liveSwitch.resolve(binding.childSessionId);
+                if (driver === undefined || driver.disabled)
+                    throw new Error('Enable the native live harness before preparing a coordinator');
+                await driver.prepare({ cwd: binding.cwd, homeDir: ctx.localAgent.homeDir('claude-code', binding.scope), childSession,
+                    parentSessionId: binding.parentSessionId, configuration: configuration.resolved, }, signal);
+            },
+            name: 'claude-code',
+            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); });
+                },
+            },
+            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,
+            // 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 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.
+            effectiveSettings: async (scopedHome) => {
+                const effectiveBaseUrl = baseUrl ?? process.env.ANTHROPIC_BASE_URL;
+                const baseUrlHost = effectiveBaseUrl !== undefined ? endpointHost(effectiveBaseUrl) : undefined;
+                const [scopedModel, cliVersion] = await Promise.all([
+                    readClaudeConfiguredModel(scopedHome).catch(() => undefined),
+                    claudeCliVersion(ctx, scopedHome).catch(() => undefined),
+                ]);
+                const model = resolveModel() ?? scopedModel;
+                return {
+                    drive: face.get().live ? 'live' : 'exec',
+                    permissionMode,
+                    baseUrlSet: effectiveBaseUrl !== undefined,
+                    ...baseUrlHost !== undefined ? { baseUrlHost } : {},
+                    ...model !== undefined ? { model } : {},
+                    ...cliVersion !== undefined ? { cliVersion } : {},
+                };
+            },
+            subcommand: (input, invocation) => {
+                const [verb] = input.split(/\s+/);
+                if (verb === 'sessions') {
+                    return listClaudeSessions(invocation.agent.ctx.localAgent.homeDir('claude-code'))
+                        .then(records => ({
+                        kind: 'success',
+                        text: records.length === 0
+                            ? 'No claude sessions in the scoped home yet.'
+                            : records.map(r => `${r.id} ${r.workDir}`).join('\n'),
+                    }));
+                }
+                return undefined;
+            },
+        });
+        return () => {
+            modelCatalog.dispose();
+            disposeProvider();
+            disposeHarness();
+            liveSwitch.dispose();
+        };
+    }, 'local-agent-claude-code: harness');
+}

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-local-agent-claude-code`.
+ * @module @khorsheed/dsh-local-agent-claude-code/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "local-agent-claude-code-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - plugin context carrying the invariant registry.
+ * @returns the installed registration's disposer.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,33 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-local-agent-claude-code`.
+ * @module @khorsheed/dsh-local-agent-claude-code/invariant
+ */
+const PACKAGE_NAME = '@khorsheed/dsh-local-agent-claude-code';
+/** Cordis companion plugin name. */
+export const name = 'local-agent-claude-code-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * The claude-code harness definition is this bundle's contract with the core
+ * registry: whenever a `claude-code` harness registers, its scoped-home
+ * variable must be the one this bundle pins.
+ */
+const install = (ctx, fail) => {
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName !== 'localAgent/harness-added')
+            return;
+        const harness = args[0];
+        if (harness.name !== 'claude-code')
+            return;
+        if (harness.homeEnvVar !== 'CLAUDE_CONFIG_DIR') {
+            fail('claude-code harness registered with a home env other than the local-agent-claude-code contract');
+        }
+    }, { global: true });
+};
+/**
+ * Register this package's invariant companion.
+ * @param ctx - plugin context carrying the invariant registry.
+ * @returns the installed registration's disposer.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */

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

@@ -0,0 +1,172 @@
+import type { LocalAgentResolvedConfiguration } from '@khorsheed/dsh-local-agent/types';
+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';
+/** 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). */
+export declare const DEFAULT_LIVE_INIT_TIMEOUT_MS = 60000;
+/** Bounded wait for an interrupted turn to converge while a run disposes. */
+export declare const DEFAULT_LIVE_DISPOSE_CONVERGE_MS = 5000;
+/** How long a tripped channel breaker stays on the exec fallback. */
+export declare const DEFAULT_LIVE_CHANNEL_RETRY_MS: number;
+/** Default minimum interval between one streaming kind's snapshot messages. */
+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);
+}
+/** Internal timeouts; tests inject small values. */
+export interface ClaudeLiveDriverTimeouts {
+    readonly initMs: number;
+    readonly convergeMs: number;
+    readonly channelRetryMs: number;
+}
+/** How much of the live event stream crosses into the child session. */
+export type ClaudeLiveMirrorGranularity = 'event' | 'token';
+/** Fully resolved inputs for one live round. */
+export interface ClaudeLiveRoundSpec {
+    /** Parent Session workspace; also the runtime process cwd. */
+    readonly cwd: string;
+    /** The `claude-code` harness's scoped home, injected as `CLAUDE_CONFIG_DIR`. */
+    readonly homeDir: string;
+    /** dsh subagent session recording this delegation (always live on this path). */
+    readonly childSession: Session;
+    /** The delegating session (member-channel registration). */
+    readonly parentSessionId: string;
+    /**
+     * Resume round: continue the session recorded as `cliSessionId` (also the
+     * reattach path after a runtime crash — the respawn passes `--resume`).
+     */
+    readonly resume?: {
+        readonly cliSessionId: string;
+        readonly turn: number;
+    } | undefined;
+    /**
+     * The delegation layer's model: the model this DELEGATION requested on its
+     * first round, re-requested by every resume round from the record. The
+     * spawn binds it when no session-level override outranks it — a delegation
+     * naming a model is no longer exec-only; its model binds at spawn like any
+     * other layer.
+     */
+    readonly model?: string | undefined;
+    readonly configuration?: LocalAgentResolvedConfiguration;
+    /** Fresh round: called with the session id from the turn's system/init. */
+    readonly onSessionId?: ((sessionId: string) => void) | undefined;
+}
+/**
+ * The claude live driver owns every resident stream-json runtime of this
+ * provider generation. Created only when `live: true`; disposed with the
+ * plugin.
+ */
+export declare class ClaudeLiveDriver {
+    private readonly ctx;
+    private readonly config;
+    private readonly timeouts;
+    private readonly runtimes;
+    private readonly ensuring;
+    private readonly idleTimers;
+    /** Per-member round serialization (the resume lock covers resume-vs-resume only). */
+    private readonly roundChains;
+    private channelBrokenAt;
+    private disposed;
+    /**
+     * Set by drain() (a settings-driven generation handoff): new rounds are
+     * refused so the provider falls back to exec, while in-flight rounds finish
+     * on their runtime undisturbed. Unlike `disposed`, the driver still serves
+     * what it already accepted.
+     */
+    private draining;
+    private readonly disposeController;
+    constructor(ctx: Context, config: Pick<Config, 'permissionMode' | 'baseUrl'> & {
+        liveIdleMs?: number;
+        liveMirrorGranularity?: ClaudeLiveMirrorGranularity;
+        /** Maximum batching wait for incremental streaming messages. */
+        snapshotMinIntervalMs?: number;
+        /** @deprecated Character growth no longer gates live publication. */
+        snapshotMinChars?: number;
+        /**
+         * Resolver for the member's effective model, read at each RUNTIME SPAWN
+         * (the resident process is where a live round's CLI starts). Receives
+         * the member and the round's delegation-layer model (the delegation's
+         * own request, re-requested on resume from the record) and answers in
+         * the family's order — session-level override, delegation, settings.
+         * Absent, or resolving to nothing, leaves the spawn argv unchanged.
+         */
+        model?: (childSessionId: string, delegationModel?: string) => string | undefined;
+        /**
+         * Scratch the spawn's effective model into the scoped settings.json
+         * before the process starts (a `--resume` respawn restores the
+         * session's stored model over the `--model` flag). index.ts wires the
+         * shared {@link ClaudeScopedModelMemory}; absent, the file is untouched.
+         */
+        provisionModel?: (homeDir: string, model: string | undefined) => Promise<void>;
+    }, timeouts?: ClaudeLiveDriverTimeouts);
+    /** Whether the channel is in its post-failure cooldown (rounds fall back to exec). */
+    get disabled(): boolean;
+    /** Count of resident runtimes currently registered (zombie accounting in tests). */
+    get liveCount(): number;
+    /**
+     * True while the member's runtime exists or is being spawned. The settings
+     * controller gates a new generation on this: a fresh driver must not serve
+     * a member whose retiring generation still hosts the (same) claude session.
+     */
+    hasRuntime(key: string): boolean;
+    /** @deprecated Compatibility no-op: live output is always incremental. */
+    setLiveMirrorGranularity(_granularity: ClaudeLiveMirrorGranularity): void;
+    /**
+     * Drain for a settings-driven generation handoff: refuse new rounds (the
+     * provider's catch falls back to exec), let every in-flight round finish on
+     * its runtime, then reclaim. Resolves when no runtime or spawn remains.
+     * Unlike disposeAll, in-flight work is never interrupted.
+     */
+    drain(): Promise<void>;
+    private clearIdleTimer;
+    private armIdleTimer;
+    private reclaim;
+    /** Reclaim every runtime (plugin unload); no process survives the profile. */
+    disposeAll(): Promise<void>;
+    private ensureRuntime;
+    /** The model a spawn for this round would bind (the argv `--model` value). */
+    private spawnModel;
+    /**
+     * The model the member's resident runtime was spawned with, or undefined
+     * when the member has no live runtime (or it binds none). The model broker
+     * compares this against a switch's new effective model.
+     */
+    runtimeModel(childSessionId: string): string | undefined;
+    /**
+     * Retire the member's resident runtime so the next round respawns with its
+     * new effective model (the model broker's switch path). The caller refuses
+     * switches while a round is in flight, so the reclaim never kills a run;
+     * the CLI session survives on disk and the respawn resumes it.
+     */
+    retireRuntime(childSessionId: string): Promise<void>;
+    /**
+     * Spawn the member's resident stream-json process. There is no handshake
+     * message — the channel proves itself with the first turn's system/init —
+     * so spawn failure is the only breaker trip here; the init wait lives in
+     * the round's accept window.
+     */
+    private spawnRuntime;
+    private markChannelBroken;
+    /**
+     * Drive one delegation round on the member's resident stream-json process.
+     * Mirrors the exec run's settlement contract exactly (settleRunResult +
+     * turn/end bookkeeping); cancel is the interrupt control request and the
+     * process survives.
+     */
+    /** Initialize native controls without sending a user prompt. Native history starts on its first real turn. */
+    prepare(spec: ClaudeLiveRoundSpec, signal: AbortSignal): Promise<void>;
+    startRound(request: SubagentStartRequest, spec: ClaudeLiveRoundSpec): Promise<SubagentRun>;
+    /** The serialized round body. */
+    private startRoundLocked;
+}
+//# sourceMappingURL=live-driver.d.ts.map