@khorsheed/dsh-local-agent-codex 0.1.0-rc.6

package/lib/types/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Codex harness instantiation of the local-agent family. Registers the
+ * `codex` harness into the core registry: scoped home under the shared homes
+ * root (`CODEX_HOME`), device-code login through `codex login --device-auth`
+ * (prompt captured from stdout), and rollout-file session records.
+ * Delegation mounts through the `codex-local` provider (one-shot
+ * `codex exec` under the scoped home); the bundle patch's
+ * `tool-subagent-codex-local` row puts the tool on the profile root, so
+ * every agent preset can delegate.
+ *
+ * @module @khorsheed/dsh-local-agent-codex
+ */
+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-codex";
+/**
+ * Boot delay before the model catalog's eager warmup probe fires. The probe
+ * spawns a `codex app-server` — cheap, but not free — so it waits out the
+ * boot storm instead of competing with it, and the FIRST settings-card open
+ * usually hits a warm cache. A card opened before the timer fires simply
+ * triggers the probe itself (the read path's lazy kick), so the delay never
+ * costs correctness. Kept short: a setting visible within seconds of boot.
+ */
+export declare const CATALOG_WARMUP_DELAY_MS = 1500;
+/** Services required before the harness can register. */
+export declare const inject: string[];
+/** Plugin config: the sandbox mode fresh delegations default to, plus the live driver. */
+export interface Config {
+    /** Codex sandbox policy for `codex exec` / app-server threads; defaults to workspace-write. */
+    sandbox?: 'read-only' | 'workspace-write' | 'danger-full-access';
+    /**
+     * The model every delegation round starts the CLI with (`codex exec -m
+     * <model>`, and `-c model=…` for the resident app-server). Absent — the
+     * default — passes NO model flag at all: the scoped `config.toml`'s own
+     * `model`, or codex'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;
+    /**
+     * Live driver: keep one resident `codex app-server` process per member and
+     * drive turns over the app-server wire (runtime-level interrupt, push-mode
+     * mirroring) instead of one `codex exec` 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 sandbox policy a fresh delegation defaults to. */
+export declare const DEFAULT_SANDBOX: NonNullable<Config['sandbox']>;
+/**
+ * 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 CODEX_SETTINGS_NAMESPACE = "local-agent-codex";
+/**
+ * Register the Codex harness into the local-agent registry.
+ * @param ctx - plugin context carrying the registry.
+ * @param config - plugin config; `sandbox` selects the `codex exec` policy.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,272 @@
+/**
+ * Codex harness instantiation of the local-agent family. Registers the
+ * `codex` harness into the core registry: scoped home under the shared homes
+ * root (`CODEX_HOME`), device-code login through `codex login --device-auth`
+ * (prompt captured from stdout), and rollout-file session records.
+ * Delegation mounts through the `codex-local` provider (one-shot
+ * `codex exec` under the scoped home); the bundle patch's
+ * `tool-subagent-codex-local` row puts the tool on the profile root, so
+ * every agent preset can delegate.
+ *
+ * @module @khorsheed/dsh-local-agent-codex
+ */
+import z from '@deepseek-ai/schemastery';
+import { settingsFace, vol } from '@khorsheed/dsh-local-agent';
+import { endpointHost } from '@khorsheed/dsh-local-agent/types';
+import { CodexCliProvider, codexCliVersion } from './codex-cli-provider.js';
+import { DEFAULT_LIVE_IDLE_MS } from './live-driver.js';
+import { LiveDriverSwitch } from './live-switch.js';
+import { CodexModelBroker } from './model-broker.js';
+import { CodexModelCatalog } from './model-catalog.js';
+import { codexAuthenticated, listCodexSessions } from './records.js';
+import { codexCredentialStamp, codexLogout, provisionCodexConfig, readCodexBaseUrl, readCodexModel, readCodexReasoningEffort } from './provision.js';
+/** Stable Cordis plugin name; the bundle patch row id. */
+export const name = 'local-agent-codex';
+/**
+ * Boot delay before the model catalog's eager warmup probe fires. The probe
+ * spawns a `codex app-server` — cheap, but not free — so it waits out the
+ * boot storm instead of competing with it, and the FIRST settings-card open
+ * usually hits a warm cache. A card opened before the timer fires simply
+ * triggers the probe itself (the read path's lazy kick), so the delay never
+ * costs correctness. Kept short: a setting visible within seconds of boot.
+ */
+export const CATALOG_WARMUP_DELAY_MS = 1_500;
+/** 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({
+    sandbox: z.union([
+        z.const('read-only'),
+        z.const('workspace-write'),
+        z.const('danger-full-access'),
+    ]),
+    model: volatilize(SETTINGS_FIELDS.model),
+    live: volatilize(SETTINGS_FIELDS.live),
+    liveIdleMs: z.number().default(DEFAULT_LIVE_IDLE_MS),
+    liveMirrorGranularity: volatilize(SETTINGS_FIELDS.liveMirrorGranularity),
+    recentModels: volatilize(SETTINGS_FIELDS.recentModels),
+});
+/** The sandbox policy a fresh delegation defaults to. */
+export const DEFAULT_SANDBOX = 'workspace-write';
+/**
+ * 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 CODEX_SETTINGS_NAMESPACE = 'local-agent-codex';
+/**
+ * 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 CODEX_SETTINGS_SCHEMA = z.object(SETTINGS_FIELDS);
+/**
+ * Register the Codex harness into the local-agent registry.
+ * @param ctx - plugin context carrying the registry.
+ * @param config - plugin config; `sandbox` selects the `codex exec` policy.
+ */
+export function apply(ctx, config) {
+    ctx.effect(() => {
+        const sandbox = config.sandbox ?? DEFAULT_SANDBOX;
+        const homeDir = ctx.localAgent.homeDir('codex');
+        // Codex's default credential store on macOS is the keychain; pin
+        // file-based storage so login lands in the scoped home's auth.json.
+        void provisionCodexConfig(homeDir).catch((error) => {
+            ctx.logger.warn(`local-agent-codex: config.toml 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: CODEX_SETTINGS_NAMESPACE,
+            legacySchema: CODEX_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-level model surface: the composer picker's session-level
+        // overrides (in-memory, deliberately lost on a host restart), shared by
+        // reference with the broker (which writes them), the exec provider (which
+        // consults them per round), and the live driver (which binds them at
+        // runtime spawn). A switch on a member with a live runtime bound to a
+        // different model retires that runtime — the next round respawns onto the
+        // new model while the codex thread itself resumes.
+        const memberModelOverrides = new Map();
+        const modelCatalog = new CodexModelCatalog({
+            spawn: spec => ctx.subprocess.spawn(spec),
+            warn: message => ctx.logger.warn(message),
+        });
+        // Eager warmup: kick one background probe of the DEFAULT scoped home
+        // shortly after apply completes (never blocking it — read() is the
+        // synchronous cache read whose only side effect is the background
+        // re-probe), so the first settings-card open usually serves the warm
+        // cache instead of reading an empty one and waiting a TTL window. Named
+        // scopes keep the lazy path: their first modelInfo read probes on demand.
+        // The timer is unref'd (it must not hold the host process open) and
+        // cleared on dispose (an unloaded plugin spawns nothing).
+        const warmup = setTimeout(() => {
+            void modelCatalog.read(homeDir);
+        }, CATALOG_WARMUP_DELAY_MS);
+        warmup.unref();
+        const liveSwitch = new LiveDriverSwitch(ctx, face, {
+            sandbox,
+            model: childSessionId => memberModelOverrides.get(childSessionId) ?? resolveModel(),
+            ...config.liveIdleMs === undefined ? {} : { liveIdleMs: config.liveIdleMs },
+        });
+        const modelBroker = new CodexModelBroker({
+            ctx,
+            settingsModel: resolveModel,
+            recentModels: () => face.get().recentModels ?? [],
+            homeDir: childSessionId => ctx.localAgent.homeDir('codex', childSessionId === undefined ? undefined : (ctx.localAgent.memberBinding?.(childSessionId) ?? ctx.localAgent.getDelegation(childSessionId))?.scope),
+            cwd: childSessionId => childSessionId === undefined ? undefined : (ctx.localAgent.memberBinding?.(childSessionId) ?? ctx.localAgent.getDelegation(childSessionId))?.cwd,
+            directory: (home, cwd) => modelCatalog.directory(home, cwd),
+            refreshDirectory: (home, cwd) => modelCatalog.refresh(home, cwd),
+            followDirectory: (home, cwd, signal) => modelCatalog.follow(home, signal, cwd),
+            live: () => face.get().live,
+            overrides: memberModelOverrides,
+            liveBoundModel: childSessionId => liveSwitch.boundModel(childSessionId),
+            retireRuntime: childSessionId => liveSwitch.retireRuntime(childSessionId),
+            // The account catalog probe is LAZY per read: read() serves the cache
+            // and kicks a background probe when stale; the apply above warms the
+            // default scope's cache so the first card open usually hits it.
+            catalog: (scopedHome, cwd) => modelCatalog.read(scopedHome, cwd),
+            // The account's built-in default slug (the probe's isDefault entry) —
+            // the layer that names the CLI's compiled default, read off the same
+            // cache.
+            catalogDefault: (scopedHome, cwd) => modelCatalog.readDefault(scopedHome, cwd),
+        });
+        const disposeProvider = ctx.subagents.registerProvider(new CodexCliProvider(ctx, sandbox, liveSwitch.resolve, resolveModel, childSessionId => memberModelOverrides.get(childSessionId)));
+        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('codex', binding.scope), childSession,
+                    parentSessionId: binding.parentSessionId, configuration: configuration.resolved, }, signal);
+            },
+            name: 'codex',
+            displayName: 'Codex',
+            homeEnvVar: 'CODEX_HOME',
+            delegationProvider: 'codex-local',
+            modelBroker,
+            // A PTY run of plain `codex login` starts a localhost callback server
+            // (no device code, no paste) and opens the browser itself — the
+            // first-class flow. `--device-auth` remains the documented headless
+            // fallback for remote terminals.
+            login: { pty: { command: 'codex', args: ['login'] } },
+            records: { listSessions: homeDir => listCodexSessions(homeDir) },
+            // A NAMED scope's directory is provisioned through this hook when the
+            // registry materializes it — the same `config.toml` storage pin the
+            // default scope gets from the apply above, so a scope's first login
+            // lands in its own `auth.json` instead of the macOS keychain.
+            provision: scopedHome => provisionCodexConfig(scopedHome).then(() => { }),
+            isAuthenticated: codexAuthenticated,
+            credentialStamp: codexCredentialStamp,
+            logout: codexLogout,
+            // The eval snapshot: the sandbox policy comes from the plugin config
+            // (it rides every spawn argv); effort and endpoint are read live from
+            // the scoped config, which codex itself reads — a person-edited value
+            // is exactly what the rounds run with. The model follows the family's
+            // fixed order: the plugin config key (it overrides the file on every
+            // argv) before the scoped config's own `model`, absent when neither
+            // names one.
+            // The directory is a PARAMETER, not the apply-time capture: a status
+            // read (or an evaluation snapshot) of a named scope must report the
+            // config that scope's rounds would run with, which is the config in
+            // that scope's own directory.
+            effectiveSettings: async (scopedHome) => {
+                const [reasoningEffort, baseUrl, scopedModel, cliVersion] = await Promise.all([
+                    readCodexReasoningEffort(scopedHome).catch(() => undefined),
+                    readCodexBaseUrl(scopedHome).catch(() => undefined),
+                    readCodexModel(scopedHome).catch(() => undefined),
+                    codexCliVersion(ctx, scopedHome).catch(() => undefined),
+                ]);
+                const model = resolveModel() ?? scopedModel;
+                const baseUrlHost = baseUrl !== undefined ? endpointHost(baseUrl) : undefined;
+                return {
+                    drive: face.get().live ? 'live' : 'exec',
+                    sandbox,
+                    ...reasoningEffort !== undefined ? { reasoningEffort } : {},
+                    baseUrlSet: baseUrl !== undefined,
+                    ...baseUrlHost !== undefined ? { baseUrlHost } : {},
+                    ...model !== undefined ? { model } : {},
+                    ...cliVersion !== undefined ? { cliVersion } : {},
+                };
+            },
+            subcommand: (input, invocation) => {
+                const [verb] = input.split(/\s+/);
+                if (verb === 'sessions') {
+                    return listCodexSessions(invocation.agent.ctx.localAgent.homeDir('codex'))
+                        .then(records => ({
+                        kind: 'success',
+                        text: records.length === 0
+                            ? 'No codex sessions in the scoped home yet.'
+                            : records.map(r => `${r.id} ${r.workDir}`).join('\n'),
+                    }));
+                }
+                return undefined;
+            },
+        });
+        return () => {
+            clearTimeout(warmup);
+            modelCatalog.dispose();
+            disposeProvider();
+            disposeHarness();
+            liveSwitch.dispose();
+        };
+    }, 'local-agent-codex: harness');
+}

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@khorsheed/dsh-local-agent-codex`.
+ * @module @khorsheed/dsh-local-agent-codex/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "local-agent-codex-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-codex`.
+ * @module @khorsheed/dsh-local-agent-codex/invariant
+ */
+const PACKAGE_NAME = '@khorsheed/dsh-local-agent-codex';
+/** Cordis companion plugin name. */
+export const name = 'local-agent-codex-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * The codex harness definition is this bundle's contract with the core
+ * registry: whenever a `codex` 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 !== 'codex')
+            return;
+        if (harness.homeEnvVar !== 'CODEX_HOME') {
+            fail('codex harness registered with a home env other than the local-agent-codex 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,229 @@
+/**
+ * The codex provider's live driver: one resident `codex app-server --stdio`
+ * process per member (child session), driven over the vendor's experimental
+ * JSON-RPC app-server wire (protocol-probed against codex-cli 0.144.0's
+ * `app-server generate-json-schema`; the harness `subagent-codex` package is
+ * the reference implementation). A delegation round is a `turn/start` on the
+ * member's resident thread instead of a fresh `codex exec` process, which buys
+ * what the process boundary could not: runtime-level graceful interrupt
+ * (`turn/interrupt`; the process survives and the thread stays continuable)
+ * and push-mode mirroring (`item/completed` + delta notifications instead of
+ * folding a polled stdout stream).
+ *
+ * Lifecycle mirrors the dsh live driver's discipline (M1): lazy spawn with an
+ * initialize handshake, one in-flight spawn per member, idle-timeout reclaim
+ * (stdin EOF → grace → SIGTERM ladder — the app-server wire has no shutdown
+ * method), crash re-spawn with `thread/resume` of the recorded thread id, a
+ * channel breaker with cooldown, and `disposeAll` on plugin unload. The wire
+ * adapter is self-contained (no new dependency): line framing with a
+ * StringDecoder for split UTF-8 tails, request correlation, and unattended
+ * auto-answers for the server→client approval requests (the proposal's
+ * default permission policy: answer exactly as the unattended exec mode does).
+ * @module @khorsheed/dsh-local-agent-codex/live-driver
+ */
+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 { LocalAgentResolvedConfiguration } from '@khorsheed/dsh-local-agent/types';
+import { type CodexTranscriptLine } from './codex-cli-provider.ts';
+/** Default idle lifetime of an unused resident runtime before reclaim. */
+export declare const DEFAULT_LIVE_IDLE_MS: number;
+/** Default timeout for a wire request acknowledgement. */
+export declare const DEFAULT_LIVE_REQUEST_TIMEOUT_MS = 30000;
+/** Default timeout for the app-server handshake (a cold boot can be slow). */
+export declare const DEFAULT_LIVE_INITIALIZE_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 item's snapshot messages. */
+export declare const DEFAULT_SNAPSHOT_MIN_INTERVAL_MS = 50;
+/** Default minimum text growth between one streaming item's snapshot messages. */
+export declare const DEFAULT_SNAPSHOT_MIN_CHARS = 0;
+/**
+ * The app-server channel could not come up (spawn failure or handshake
+ * timeout/mismatch). 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 CodexLiveDriverTimeouts {
+    readonly initializeMs: number;
+    readonly requestMs: number;
+    readonly convergeMs: number;
+    readonly channelRetryMs: number;
+}
+/** How much of the live event stream crosses into the child session. */
+export type CodexLiveMirrorGranularity = 'event' | 'token';
+/** Fully resolved inputs for one live round. */
+export interface CodexLiveRoundSpec {
+    /** Parent Session workspace; also the runtime process cwd. */
+    readonly cwd: string;
+    /** The codex harness's scoped home, injected as the runtime's `CODEX_HOME`. */
+    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 thread recorded as `cliSessionId`, appending
+     * under this turn number. Also the reattach path after a runtime crash.
+     */
+    readonly resume?: {
+        readonly cliSessionId: string;
+        readonly turn: number;
+    } | undefined;
+    /** Fresh round: called with the server-assigned thread id (delegation record). */
+    readonly onThreadId?: ((threadId: string) => void) | undefined;
+    /**
+     * The member's START model — the delegation's own requested model, or the
+     * composer's session-level override, as resolved by the provider. When it
+     * names one, a resident runtime bound to a DIFFERENT model is retired
+     * before the spawn so the round respawns onto it (the same CLI session
+     * resumes — the rollout carries over). Absent means the spawn resolver
+     * decides (override → recorded → settings).
+     */
+    readonly startModel?: string | undefined;
+    readonly configuration?: LocalAgentResolvedConfiguration;
+}
+type JsonObject = Record<string, unknown>;
+/**
+ * Auth-shaped failure signatures in codex's error output: the endpoint
+ * rejected the credential. Mirrors the exec path's detector
+ * (CODEX_AUTH_FAILURE in codex-cli-provider.ts); the live path matches
+ * against turn-failure messages, which is where a mid-run 401 surfaces when
+ * the process does not exit.
+ */
+export declare const CODEX_LIVE_AUTH_FAILURE: RegExp;
+/**
+ * Map one app-server `item/completed` ThreadItem onto the shared transcript
+ * line shape — the live transport's entry into the SAME fold the exec NDJSON
+ * parser owns (`foldCodexStreamLine`); both produce `CodexTranscriptLine`s
+ * and append through `appendCodexTranscriptLine`, so the two drivers' final
+ * child transcripts cannot drift.
+ */
+export declare function codexAppServerItemToLine(item: JsonObject): CodexTranscriptLine | undefined;
+/**
+ * The codex live driver owns every resident app-server runtime of this
+ * provider generation. Created only when `live: true`; disposed with the
+ * plugin.
+ */
+export declare class CodexLiveDriver {
+    private readonly ctx;
+    private readonly config;
+    private readonly timeouts;
+    private readonly runtimes;
+    /** In-flight spawns by member: concurrent rounds share one, disposeAll waits them out. */
+    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, 'sandbox'> & {
+        liveIdleMs?: number;
+        liveMirrorGranularity?: CodexLiveMirrorGranularity;
+        /** Maximum batching wait for incremental streaming messages. */
+        snapshotMinIntervalMs?: number;
+        /** @deprecated Character growth no longer gates live publication. */
+        snapshotMinChars?: number;
+        /**
+         * Resolver for the member's configured model, read at each RUNTIME SPAWN
+         * (the app-server is where a live round's CLI starts). Receives the
+         * member's child session id so the session-level override can outrank
+         * the settings value; absent, or resolving to nothing, leaves the spawn
+         * argv unchanged.
+         */
+        model?: (childSessionId: string) => string | undefined;
+    }, timeouts?: CodexLiveDriverTimeouts);
+    /** 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;
+    private clearIdleTimer;
+    private armIdleTimer;
+    private reclaim;
+    /** Reclaim every runtime (plugin unload); no process survives the profile. */
+    disposeAll(): Promise<void>;
+    /**
+     * 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) codex thread.
+     */
+    hasRuntime(key: string): boolean;
+    /** @deprecated Compatibility no-op: live output is always incremental. */
+    setLiveMirrorGranularity(_granularity: CodexLiveMirrorGranularity): 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>;
+    /**
+     * The model the member's live runtime bound at spawn: the identifier, or
+     * undefined when the runtime spawned with no model flag. Null when the
+     * member has no live runtime in this generation — the broker's switch check
+     * distinguishes "no runtime to retire" from "runtime bound to no model".
+     */
+    boundModelOf(key: string): string | undefined | null;
+    /**
+     * Retire the member's resident runtime so the NEXT round respawns (the CLI
+     * session itself carries over via thread/resume). The composer's model
+     * switch calls this after storing the new override; the caller guarantees
+     * no round is in flight for the member.
+     */
+    retireRuntime(key: string): Promise<void>;
+    /** The member's runtime, spawning it (once per member at a time) when absent or dead. */
+    private ensureRuntime;
+    /**
+     * Spawn the member's resident app-server and prove the wire with a
+     * handshake. Failure trips the channel breaker; a cancellation mid-spawn
+     * reclaims the half-started process without touching the breaker.
+     */
+    private spawnRuntime;
+    private markChannelBroken;
+    /**
+     * Report an auth-shaped round failure to the family registry's auth-failure
+     * mark (the exec path's post-exit 401 detection ported to a process that
+     * never exits: the match runs against the settled error instead). Degrades
+     * silently on a core predating reportAuthFailure.
+     */
+    private reportAuthIfShaped;
+    /**
+     * Auto-answer the app-server's approval/elicitation requests, matching the
+     * unattended exec behavior (and the harness reference implementation's
+     * tables): the live driver never grants interactive approval. This is the
+     * proposal's default permission policy; the relay hook for a human
+     * approval UI is a later increment.
+     */
+    private answerServerRequest;
+    /**
+     * Drive one delegation round on the member's resident app-server. Mirrors
+     * the exec run's settlement contract exactly so the facade, the tool, and
+     * the projections cannot tell the difference — except `cancel` is a runtime
+     * interrupt and the process survives. Cancellation is honored in every
+     * window (the M1 acceptance lesson): the abort listener registers before
+     * any await, the spawn/handshake races it, and a pre-accept cancel reclaims
+     * the fresh runtime instead of letting the turn run unwatched.
+     */
+    /** Create/resume the native thread without starting a model turn. */
+    prepare(spec: CodexLiveRoundSpec, signal: AbortSignal): Promise<void>;
+    private ensureThread;
+    startRound(request: SubagentStartRequest, spec: CodexLiveRoundSpec): Promise<SubagentRun>;
+    /** The serialized round body. */
+    private startRoundLocked;
+}
+export {};
+//# sourceMappingURL=live-driver.d.ts.map