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

package/lib/types/client/index.js

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

package/lib/types/client/locales.d.ts

@@ -8,18 +8,23 @@ export declare const zh: {
     'card.expand': string;
     'card.collapse': string;
     'auth.title': string;
-    'model.title': string;
-    'model.info.aria': string;
-    'model.info': string;
-    'model.placeholder': string;
-    'model.menu': string;
-    'model.menuDefault': string;
-    'model.menuDefault.cli-config': string;
-    'model.menuDefault.cli-builtin': string;
-    'model.menuDefault.last-observed': string;
-    'model.save': string;
-    'model.applied': string;
-    'model.error': string;
+    'endpoint.info.aria': string;
+    'endpoint.info': string;
+    'endpoint.baseUrl': string;
+    'endpoint.baseUrl.placeholder': string;
+    'endpoint.apiKey': string;
+    'endpoint.secret.configured': string;
+    'endpoint.secret.placeholder': string;
+    'endpoint.configured': string;
+    'endpoint.save': string;
+    'endpoint.applied': string;
+    'endpoint.error': string;
+    'endpoint.check': string;
+    'endpoint.checking': string;
+    'endpoint.checkDirtyHint': string;
+    'endpoint.checkUnavailable': string;
+    'endpoint.unavailable': string;
+    'endpoint.checkFailed': string;
     'live.title': string;
     'live.info.aria': string;
     'live.info': string;
@@ -42,18 +47,23 @@ export declare const en: {
     'card.expand': string;
     'card.collapse': string;
     'auth.title': string;
-    'model.title': string;
-    'model.info.aria': string;
-    'model.info': string;
-    'model.placeholder': string;
-    'model.menu': string;
-    'model.menuDefault': string;
-    'model.menuDefault.cli-config': string;
-    'model.menuDefault.cli-builtin': string;
-    'model.menuDefault.last-observed': string;
-    'model.save': string;
-    'model.applied': string;
-    'model.error': string;
+    'endpoint.info.aria': string;
+    'endpoint.info': string;
+    'endpoint.baseUrl': string;
+    'endpoint.baseUrl.placeholder': string;
+    'endpoint.apiKey': string;
+    'endpoint.secret.configured': string;
+    'endpoint.secret.placeholder': string;
+    'endpoint.configured': string;
+    'endpoint.save': string;
+    'endpoint.applied': string;
+    'endpoint.error': string;
+    'endpoint.check': string;
+    'endpoint.checking': string;
+    'endpoint.checkDirtyHint': string;
+    'endpoint.checkUnavailable': string;
+    'endpoint.unavailable': string;
+    'endpoint.checkFailed': string;
     'live.title': string;
     'live.info.aria': string;
     'live.info': string;

package/lib/types/client/locales.js

@@ -3,23 +3,28 @@
 export const NS = 'local-agent-codex';
 /** Simplified Chinese dictionary (the key-set source of truth). */
 export const zh = {
-    'card.title': 'Local Agent · Codex',
-    'card.description': 'Codex 委派：登录授权与常驻模式（live）',
+    'card.title': '本机 Codex 委派',
+    'card.description': 'Codex 委派：端点凭据与常驻模式（live）',
     'card.expand': '展开',
     'card.collapse': '收起',
     'auth.title': '认证',
-    'model.title': '默认模型',
-    'model.info.aria': '默认模型说明',
-    'model.info': '留空 = 跟随默认（输入框里显示的就是当前跟随的模型）。从列表选择或手动输入一个模型名后保存，之后的每轮委派都以它起 CLI（一次性轮次走 `codex exec -m <模型>`，常驻模式走 app-server 的 `-c model=…`）。成员会话里还可用作曲器按会话切换，不影响这里的默认。改动在下一轮委派生效，进行中的轮次不受影响；评测 run 的条件在建立时冻结，中途换模型会被下一轮的模型回读判为 misattributed 而拦下。',
-    'model.placeholder': '留空 = 不传模型，用 CLI 自己的默认',
-    'model.menu': '选择模型',
-    'model.menuDefault': '默认（跟随 CLI 内置默认）',
-    'model.menuDefault.cli-config': '默认（跟随 CLI 配置：{model}）',
-    'model.menuDefault.cli-builtin': '默认（跟随 CLI 默认：{model}）',
-    'model.menuDefault.last-observed': '默认（跟随 CLI 内置默认（最近：{model}））',
-    'model.save': '保存',
-    'model.applied': '已保存，下一轮委派生效；进行中的轮次不受影响',
-    'model.error': '保存失败，请重试',
+    'endpoint.info.aria': '端点凭据说明',
+    'endpoint.info': '这里保存的就是默认 scope 的 endpoint-auth.json（0600，只存本机），它优先于 profile 的 YAML 配置行；宿主 shell 的环境变量从不被读取。配置 API Key 后每轮委派以自定义 provider（wire_api=responses）路由到端点；端点地址留空 = OpenAI 官方端点。密钥绝不写进 profile 文件，也不进入评测条件指纹。没有网页登录：容器轮与宿主轮用同一套凭据，容器里不需要再授权一次。保存对下一轮委派生效，进行中的轮次不受影响。',
+    'endpoint.baseUrl': '端点地址（baseUrl）',
+    'endpoint.baseUrl.placeholder': '留空 = OpenAI 官方端点',
+    'endpoint.apiKey': 'API Key',
+    'endpoint.secret.configured': '已配置 · 输入新值更换，留空保存 = 清除',
+    'endpoint.secret.placeholder': '未配置',
+    'endpoint.configured': '已配置',
+    'endpoint.save': '保存凭据',
+    'endpoint.applied': '已保存，下一轮委派生效；进行中的轮次不受影响',
+    'endpoint.error': '保存失败，请重试',
+    'endpoint.check': '验证端点并获取模型',
+    'endpoint.checking': '验证中…',
+    'endpoint.checkDirtyHint': '有未保存的修改，先保存凭据再验证',
+    'endpoint.checkUnavailable': '当前核心不支持端点验证（请升级 local-agent 核心包）',
+    'endpoint.unavailable': '当前核心不支持凭据配置（请升级 local-agent 核心包）',
+    'endpoint.checkFailed': '验证失败，请重试',
     'live.title': '常驻模式（live）',
     'live.info.aria': '常驻模式说明',
     'live.info': '常驻模式 = 成员进程常驻：输出实时流入成员会话、取消不杀进程、崩溃后自动续上原会话；关闭则每轮独立进程，跑完一次性出结果。设置为全局偏好，对所有后续委派生效。',
@@ -29,23 +34,28 @@ export const zh = {
 };
 /** English dictionary, checked complete against the zh key set. */
 export const en = {
-    'card.title': 'Local Agent · Codex',
-    'card.description': 'Codex delegation: sign-in and resident (live) mode',
+    'card.title': 'Local Codex Delegation',
+    'card.description': 'Codex delegation: endpoint credential and resident (live) mode',
     'card.expand': 'Expand',
     'card.collapse': 'Collapse',
     'auth.title': 'Authentication',
-    'model.title': 'Default model',
-    'model.info.aria': 'About the default model',
-    'model.info': "Blank = follow the default (the input shows the model it currently follows). Pick from the list or type a model name by hand and save, and every later delegation round starts the CLI with it (`codex exec -m <model>` for one-shot rounds, `-c model=…` on the resident app-server). Inside a member session the composer can also switch the model per session, without touching this default. A change applies to the next round and never disturbs a round in flight; an evaluation run freezes its condition at setup, so switching mid-run is caught by the model read-back on the next round and fails the run as misattributed.",
-    'model.placeholder': "Blank = pass no model, keep the CLI's own default",
-    'model.menu': 'Pick a model',
-    'model.menuDefault': "Default (follow the CLI's built-in default)",
-    'model.menuDefault.cli-config': 'Default (follow the CLI config: {model})',
-    'model.menuDefault.cli-builtin': 'Default (follow the CLI default: {model})',
-    'model.menuDefault.last-observed': "Default (follow the CLI's built-in default (last: {model}))",
-    'model.save': 'Save',
-    'model.applied': 'Saved — takes effect on the next delegation round; rounds in flight are unaffected',
-    'model.error': 'Save failed, please retry',
+    'endpoint.info.aria': 'About the endpoint credential',
+    'endpoint.info': "What you save here is the default scope's endpoint-auth.json (mode 0600, local only), which outranks the profile's YAML row; the host shell's environment is never read. With an API Key configured, every delegation round routes at the endpoint through a custom provider (wire_api=responses); a blank endpoint means OpenAI's own. Keys never enter the profile document or an evaluation's condition fingerprint. There is no web login: container rounds share the host's credential and nothing is authorized inside a container. Saving applies to the next delegation round; rounds in flight are unaffected.",
+    'endpoint.baseUrl': 'Endpoint (baseUrl)',
+    'endpoint.baseUrl.placeholder': "Blank = OpenAI's own endpoint",
+    'endpoint.apiKey': 'API Key',
+    'endpoint.secret.configured': 'Configured · type to replace, save blank to clear',
+    'endpoint.secret.placeholder': 'Not configured',
+    'endpoint.configured': 'Configured',
+    'endpoint.save': 'Save credential',
+    'endpoint.applied': 'Saved — takes effect on the next delegation round; rounds in flight are unaffected',
+    'endpoint.error': 'Save failed, please retry',
+    'endpoint.check': 'Verify endpoint & list models',
+    'endpoint.checking': 'Verifying…',
+    'endpoint.checkDirtyHint': 'Unsaved changes — save the credential before verifying',
+    'endpoint.checkUnavailable': 'This core cannot verify endpoints (upgrade the local-agent core package)',
+    'endpoint.unavailable': 'This core cannot configure credentials (upgrade the local-agent core package)',
+    'endpoint.checkFailed': 'Verification failed, please retry',
     'live.title': 'Resident mode (live)',
     'live.info.aria': 'About resident mode',
     'live.info': 'Resident mode keeps the member process alive: output streams into the member session in real time, cancelling does not kill the process, and a crash resumes the same session. Off means every round runs as an independent one-shot process. The setting is global and applies to every later delegation.',

package/lib/types/codex-cli-provider.d.ts

@@ -13,13 +13,22 @@
  * it too (a deliberate user re-enable conflicts loud, by design).
  * @module @khorsheed/dsh-local-agent-codex/codex-cli-provider
  */
-import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm';
+import type { ContentBlock, ReasoningEffortId, TokenUsage } from '@deepseek-ai/dsh-llm';
 import { type ResolvedSubagentStartRequest, type SubagentCapabilities, type SubagentProvider, type SubagentRun, type SubagentStartRequest, type SubagentStopReason } from '@deepseek-ai/dsh-subagent';
 import type { Context } from '@deepseek-ai/cordis';
 import type { Session } from '@deepseek-ai/dsh-session';
 import type { SubprocessHandle, SubprocessSpawnSpec } from '@deepseek-ai/dsh-subprocess';
 import type { DelegationExecTarget, LocalAgentToolCalls } from '@khorsheed/dsh-local-agent/types';
 import type { CodexLiveDriver } from './live-driver.ts';
+import { type CodexEndpointAuth } from './endpoint-auth.ts';
+/**
+ * The synthesized result for a call whose result the stream never recorded
+ * (a killed run, or a result-less item type like web_search_call). The
+ * released-log contract resolves every advertised call before its step
+ * closes, so an interrupted call folds with this error result. Same text as
+ * the kimi provider's placeholder, for family consistency.
+ */
+export declare const CODEX_INTERRUPTED_TOOL_RESULT = "\uFF08\u5DE5\u5177\u8C03\u7528\u88AB\u4E2D\u65AD\uFF0C\u672A\u80FD\u8BB0\u5F55\u8FD4\u56DE\u7ED3\u679C\uFF09";
 /** Default POSIX grace between subprocess termination tiers. */
 export declare const DEFAULT_DISPOSE_GRACE_MS = 3000;
 /**
@@ -71,6 +80,7 @@ export declare class CodexCliProvider implements SubagentProvider {
     private readonly live?;
     private readonly model?;
     private readonly overrides?;
+    private readonly endpoint?;
     readonly name = "codex-local";
     readonly capabilities: SubagentCapabilities;
     readonly inheritsParentContext = false;
@@ -81,17 +91,25 @@ export declare class CodexCliProvider implements SubagentProvider {
      *   while a retiring generation still hosts it).
      * @param model - resolver for the configured model, read PER ROUND so a
      *   settings-card write takes effect on the next delegation without a
-     *   reload. Undefined (the resolver absent, or returning undefined) leaves
-     *   the argv exactly as it was before the key existed — the scoped
-     *   config.toml's own `model` then decides, as it always did.
+     *   reload; it receives the round's scope (a named scope's curated list
+     *   answers first). Undefined (the resolver absent, or returning
+     *   undefined) leaves the argv exactly as it was before the key existed —
+     *   the scoped config.toml's own `model` then decides, as it always did.
      * @param overrides - resolver for the member's session-level model override
      *   (the composer picker, owned by the model broker). It outranks BOTH the
      *   delegation's recorded model and the configured one: on the exec path it
      *   re-points the next round's `-m`, and on the live path it is the member's
      *   start model — a resident runtime bound to a different model is retired
      *   so the round respawns onto the override.
+     * @param endpoint - resolver for the scope's endpoint credential, read PER
+     *   ROUND so a settings-card write takes effect on the next delegation
+     *   without a reload. A resolution carrying a key routes the round at the
+     *   relay (a custom `model_providers` entry on the argv, the key in the
+     *   env); with no key the spawn carries no credential at all.
      */
-    constructor(ctx: Context, sandbox?: CodexSandbox, live?: CodexLiveDriver | ((childSessionId: string) => CodexLiveDriver | undefined) | undefined, model?: (() => string | undefined) | undefined, overrides?: ((childSessionId: string) => string | undefined) | undefined);
+    constructor(ctx: Context, sandbox?: CodexSandbox, live?: CodexLiveDriver | ((childSessionId: string) => CodexLiveDriver | undefined) | undefined, model?: ((scope?: string) => string | undefined) | undefined, overrides?: ((childSessionId: string) => string | undefined) | undefined, endpoint?: ((scopeHome: string) => Promise<CodexEndpointAuth>) | undefined);
+    /** The scope's endpoint credential for this round; absent resolver = never. */
+    private resolveEndpoint;
     /** Resolve the live driver for one round's member, if live is on for it. */
     private liveDriver;
     /** Per-round member-channel registration for the exec path (see {@link registerCodexMemberRun}). */
@@ -116,6 +134,13 @@ export interface CodexCliRunSpec {
     readonly exec?: DelegationExecTarget | undefined;
     /** Resolved endpoint label for diagnostics; absent means the CLI default. */
     readonly endpointLabel?: string | undefined;
+    /**
+     * The endpoint credential's `-c` config overrides (a custom
+     * `model_providers` entry plus the provider selection), spliced next to
+     * the member override. Empty when the round carries no endpoint
+     * credential — the argv is then byte-identical to the pre-endpoint shape.
+     */
+    readonly endpointArgv?: readonly string[] | undefined;
     /** Sandbox policy passed to `codex exec --sandbox`. */
     readonly sandbox: CodexSandbox;
     /**
@@ -291,7 +316,8 @@ export declare class CodexStreamParser implements CodexStreamFoldState {
  * not put one on the wire; the settle path then reads the rollout's
  * turn_context). Item types covered: `reasoning` (thinking), `agent_message`
  * (reply text), `command_execution` (shell command with aggregated output),
- * `web_search_call`, and `function_call_output`. The last `agent_message`
+ * `web_search_call`, `custom_tool_call`/`custom_tool_call_output` (deferred
+ * and dynamic tools), and `function_call_output`. The last `agent_message`
  * wins as the run output (the final answer), and `turn.completed` carries the
  * turn's usage. Malformed lines are skipped.
  * @param stream - the collected stdout NDJSON text.
@@ -319,6 +345,17 @@ export declare function parseCodexJsonStream(stream: string): {
  * @returns the published run after the child starts.
  */
 export declare function startCodexCliRun(request: SubagentStartRequest, spec: CodexCliRunSpec): Promise<SubagentRun>;
+/**
+ * Write the round's request/header when the config differs from the child
+ * log's last one (the host logs changed snapshots, not per-call duplicates):
+ * the first write is `initial`, a differing one `change`, an identical one
+ * skipped. Context Lens reads the child log's config from these headers.
+ */
+export declare function appendCodexRequestHeader(childSession: Session, config: {
+    provider: string;
+    model: string;
+    reasoningEffort?: ReasoningEffortId;
+}): void;
 /** One assistant-role message event, attributed to the codex route. */
 export declare function codexAssistantEvent(blocks: readonly ContentBlock[]): import("@deepseek-ai/dsh-llm").AssistantMessage;
 /**
@@ -327,8 +364,17 @@ export declare function codexAssistantEvent(blocks: readonly ContentBlock[]): im
  * assembler requires: without a boundary the step never enters the location
  * index, the line's assistant message resolves to a turn-level location, and
  * the real-time view renders nothing (only a full rebuild, which mints step
- * drafts from the explicit coordinates, recovers it). Tool cards escape that
- * fate only because their definition does not consult the step location.
+ * drafts from the explicit coordinates, recovers it).
+ *
+ * A tool line folds the NATIVE lifecycle inside its one step: an assistant
+ * message advertising the tool-call block, the `tool/call`, then its
+ * `tool/result` — the released-log reader pairs call and result against the
+ * advertisement and resolves every advertised call before the step closes.
+ * Every fold sees a COMPLETED item (the exec live mirror holds the volatile
+ * last line; the live driver folds at item/completed), so a result the
+ * stream has not recorded by fold time will never arrive — the call folds
+ * with the synthesized interrupted result instead of leaving the step
+ * unresolvable.
  * @returns whether the line folded (false when the options skipped it).
  */
 export declare function appendCodexTranscriptLine(childSession: Session, turn: number, step: number, line: CodexTranscriptLine, usage: TokenUsage | undefined): boolean;