Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.
Rust ai-agentsai-gatewayclaude-codecodexcoding-agentcost-optimizationdeepseekllm-gatewayllm-routerlocal-firstmodel-routingrusttask-routingtauri
Explain Codex session visibility and supported recovery (#199)
澄潭70e8815610d4
diff --git a/apps/desktop/src/features/agents/CodexAccessPanel.tsx b/apps/desktop/src/features/agents/CodexAccessPanel.tsxindex 686021c9..3e962a9b 100644--- a/apps/desktop/src/features/agents/CodexAccessPanel.tsx+++ b/apps/desktop/src/features/agents/CodexAccessPanel.tsx@@ -5,6 +5,25 @@ import { preferredCodexShell } from './codex-launch';export type { CodexAccess } from './types';import type { CodexAccess } from './types';+export function CodexHistoryNotice({ language, mode }: { language: 'zh' | 'en'; mode: 'profile' | 'root' }) {+ const text = (zh: string, en: string) => language === 'zh' ? zh : en;+ const root = mode === 'root';+ return <div className={`callout${root ? ' warn' : ''}`} role="note" data-codex-history-guidance data-codex-history-mode={mode}>+ <UiIcon name={root ? 'warning' : 'info'} /><div>+ <strong>{root+ ? text('切换后如何找回原有会话', 'Finding earlier sessions after switching')+ : text('原有会话仍可从原入口继续', 'Continue earlier sessions from the original entry')}</strong>+ <p>{root+ ? text('设为默认后,Codex 按模型服务商筛选 /resume。原有会话可能不再显示,即使选择全部目录;会话文件仍然保留。', 'After using HiRoute by default, Codex filters /resume by model provider. Earlier sessions may disappear, even with all directories selected; their files remain.')+ : text('按需使用只影响 HiRoute profile,普通 Codex 的配置和会话历史不变。HiRoute profile 内的 /resume 可能不显示原服务商的会话。', 'On-demand access only affects the HiRoute profile. Ordinary Codex configuration and session history stay unchanged. Inside the HiRoute profile, /resume may hide sessions from the original provider.')}</p>+ <p>{root+ ? text('找回步骤:在 HiRoute 的“模型路由”点击“停用”,等待原配置恢复完成,再使用原 CODEX_HOME 和原 profile 运行 ', 'To recover: turn off Model routing in HiRoute and wait for configuration restoration to finish. Then use your original CODEX_HOME and profile to run ')+ : text('无需停用 HiRoute。退出 HiRoute profile,用原 CODEX_HOME 和原 profile 运行 ', 'No need to disable HiRoute. Exit the HiRoute profile and use your original CODEX_HOME and profile to run ')}<code>codex resume --all</code>{text(',选择原有会话。', ' and select the earlier session.')}</p>+ <p>{text('原入口使用原服务商,绕过 HiRoute,需要原账号或 API 凭据。', 'The original entry uses the original provider, bypasses HiRoute, and needs its original account or API credentials.')}</p>+ </div>+ </div>;+}+export function CodexAccessSettings({ access, mode, language, disabled, onMode }: {access: CodexAccess; mode: 'profile' | 'root'; language: 'zh' | 'en'; disabled: boolean;onMode: (mode: 'profile' | 'root') => void;@@ -22,7 +41,7 @@ export function CodexAccessSettings({ access, mode, language, disabled, onMode }<dl><div><dt>CODEX_HOME</dt><dd><code className="configuration-path">{access.codex_home}</code></dd></div>{access.slot_occupied && <div><dt>{text('目标文件', 'Target file')}</dt><dd><code className="configuration-path">{access.target_file}</code></dd></div>}</dl>- <p className="field-help">{text('不同入口的会话历史可能不同;不提供跨 provider 历史恢复。独立 profile 不支持启动 Desktop。', 'History may differ between entry points; cross-provider recovery is not provided. The separate profile cannot launch Desktop.')}</p>+ <p className="field-help">{text('使用原有会话时需选择相同的 CODEX_HOME 和原 profile。独立 profile 不支持启动 Desktop。', 'Use the same CODEX_HOME and original profile for earlier sessions. The separate profile cannot launch Desktop.')}</p></Disclosure></div>;}@@ -40,6 +59,7 @@ export function CodexAccessPanel({ access, language, retryDisabled, onRetry }: {<p className="field-help">{mode === 'profile'? text('按需使用 · Codex CLI:复制命令到终端启动。普通 Codex 与 Desktop 保持原配置。', 'On demand · Codex CLI: copy the command to start in a terminal. Ordinary Codex and Desktop keep their settings.'): text('默认接入 · Codex CLI 和 Desktop:共享此配置目录的入口使用 HiRoute。', 'Default connection · Codex CLI and Desktop: entry points sharing this directory use HiRoute.')}</p>+ <CodexHistoryNotice language={language} mode={mode} />{mode === 'profile' && access.slot_occupied && !access.pending_operation && !access.access_revoked && <div><div className="detail-section-head"><strong>{text('启动 Codex', 'Start Codex')}</strong><label className="field-label agent-launch-shell">Shell <select className="select" value={shell} onChange={e => { setShell(e.target.value); setCopyState(''); }}>{Object.keys(access.commands).map(name => <option key={name}>{name}</option>)}</select></label></div><pre className="agent-launch-command"><code>{command}</code></pre>diff --git a/apps/desktop/src/features/agents/CodexModelEditor.tsx b/apps/desktop/src/features/agents/CodexModelEditor.tsxindex a38928b3..29803fd5 100644--- a/apps/desktop/src/features/agents/CodexModelEditor.tsx+++ b/apps/desktop/src/features/agents/CodexModelEditor.tsx@@ -2,7 +2,7 @@ import { agentModelStatus } from './status';import React from 'react';import { Disclosure, UiIcon } from '../../ui';import type { AgentModelEditorProps } from './AgentModelEditor';-import { CodexAccessSettings } from './CodexAccessPanel';+import { CodexAccessSettings, CodexHistoryNotice } from './CodexAccessPanel';import { codexSurfaceFacts } from './codex-surfaces';import { surfaceName } from './ecosystems';import { codexDefaultChoiceValid } from './editor-state';@@ -165,6 +165,7 @@ export function CodexModelEditor({<p className="field-help" data-codex-shared-scope>{activeCodexMode === 'profile'? text('按需使用 · 仅 Codex CLI。启用后将启动命令粘贴到终端,开启新会话。普通 Codex 和 Desktop 保持原配置。', 'On demand · Codex CLI only. After enabling, paste the launch command into a terminal to start a new session. Ordinary Codex and Desktop keep their settings.'): text('设为默认 · 修改同一配置目录下 Codex CLI 和 Desktop 的模型接入。保存后重新启动对应客户端即可生效。', 'Use by default · changes model access for Codex CLI and Desktop sharing this directory. Restart the client after saving to apply the settings.')}</p>+ <CodexHistoryNotice language={language} mode={activeCodexMode} /><fieldset><legend className="field-label">{text('允许的智能路由', 'Allowed smart routes')}</legend>{enabledPlans.length === 1 && creatingModelConnection && <p className="field-help">{text('唯一可用路由已选为默认,可直接启用。', 'The only available route is selected as the default. Enable to continue.')}</p>}{enabledPlans.map(plan => <label className="check-row agent-route-choice" data-agent-plan-id={plan.agent_plan_id} key={plan.agent_plan_id}><input type="checkbox" checked={editorValues.allowedPlanIds.includes(plan.agent_plan_id)} onChange={() => toggleAllowedPlan(plan.agent_plan_id)} /><div><strong>{plan.desired.display_name}</strong></div></label>)}@@ -199,7 +200,7 @@ export function CodexModelEditor({: text('保存一次即作用于共享此配置作用域与 CODEX_HOME 的 Codex CLI 和 Desktop。', 'One save applies to Codex CLI and Desktop when they share this configuration scope and CODEX_HOME.')}</p>{codexSurfaces.map(({surface, detected, applicable}) => {return <span className="field-help" key={surface} data-agent-surface-fact={surface} data-agent-surface-detected={detected ? 'true' : 'false'} data-agent-surface-applicable={applicable ? 'true' : 'false'}>{surfaceName(surface)} · {detected ? text('当前已发现可执行入口', 'currently detected as runnable') : text('当前未发现可执行入口', 'not currently detected as runnable')} · {applicable ? text('适用当前模式', 'applies to this mode') : text('不适用当前模式', 'does not apply to this mode')}</span>;})}</div></div>- <p className="field-help" data-agent-plan-compatibility>{text('保存时会核对路由的 Codex Responses 能力。不同入口的会话历史可能不同。', 'Saving checks the routes’ Codex Responses capabilities. History may differ between entry points.')}</p>+ <p className="field-help" data-agent-plan-compatibility>{text('保存时会核对路由的 Codex Responses 能力。', 'Saving checks the routes’ Codex Responses capabilities.')}</p></Disclosure>{modelFormInvalid && <span className="oc-inline-error">{text('请选择可用路由或固定模型,并修正不可用项。', 'Choose an available route or fixed model and resolve unavailable selections.')}</span>}</div>;diff --git a/apps/desktop/src/features/agents/README.md b/apps/desktop/src/features/agents/README.mdindex 9bffd806..6cc09772 100644--- a/apps/desktop/src/features/agents/README.md+++ b/apps/desktop/src/features/agents/README.md@@ -20,7 +20,7 @@ to their production owners and executable contracts.| [AgentSettingsFeedback.tsx](AgentSettingsFeedback.tsx) | Presentation of authoritative Preview blockers. || [HermesModelEditor.tsx](HermesModelEditor.tsx), [HermesRootFields.tsx](HermesRootFields.tsx) | One Plan/protocol and explicit effective profile; root fields are shared with source scan. Automatic adapter preparation and unobserved native loading stay distinct. || [collaboration-check-feedback.ts](collaboration-check-feedback.ts) | Versioned collaboration-check failures become safe login, Skill recovery and retry guidance; native output is never display text. |-| [CodexAccessPanel.tsx](CodexAccessPanel.tsx) | Profile/root facts, mode controls, launch commands, ordinary file-conflict diagnosis and an existing pending Operation's recovery entry. |+| [CodexAccessPanel.tsx](CodexAccessPanel.tsx) | Profile/root facts, mode controls, launch commands, visible mode-specific session-history and original-entry guidance, ordinary file-conflict diagnosis and an existing pending Operation's recovery entry. || [codex-launch.ts](codex-launch.ts), [codex-surfaces.ts](codex-surfaces.ts) | Confirmed command-copy eligibility and the distinction between detected executables and mode applicability. || [mutation-feedback.ts](mutation-feedback.ts) | Submitted, pre-apply cancelled and uncertain outcomes; truthful disable/recovery messages. || [Agents page](../../agents.tsx) | Snapshot refresh, selected Agent/tab, in-memory draft and mode, discard guard, native calls, Operation handoff, confirmation-dependent copy effect and task-history composition. |diff --git a/apps/desktop/src/occami/styles.css b/apps/desktop/src/occami/styles.cssindex 63fd6073..7c4fc63a 100644--- a/apps/desktop/src/occami/styles.css+++ b/apps/desktop/src/occami/styles.css@@ -65,6 +65,7 @@.agent-form .agent-route-choice {padding:12px 14px;border:1px solid var(--border);border-radius:10px;background:var(--bg-soft);}.agent-form .agent-route-choice:has(input:checked) {border-color:var(--accent);background:var(--accent-soft);}.configuration-path {white-space:pre-wrap;overflow-wrap:anywhere;}+[data-codex-history-guidance] code {white-space:nowrap;}.agent-launch-command {white-space:pre-wrap;overflow-wrap:anywhere;padding:14px;border:1px solid var(--border);border-radius:10px;background:var(--bg-soft);font-size:calc(12px * var(--hr-text-scale));}.agent-launch-shell {display:flex;align-items:center;gap:8px;}.agent-launch-shell .select {width:auto;max-width:160px;}diff --git a/apps/desktop/tests/v3/browser/agent-trust-scenarios.mjs b/apps/desktop/tests/v3/browser/agent-trust-scenarios.mjsindex beeecebf..adf1313c 100644--- a/apps/desktop/tests/v3/browser/agent-trust-scenarios.mjs+++ b/apps/desktop/tests/v3/browser/agent-trust-scenarios.mjs@@ -318,12 +318,53 @@ const scenarios = [const route = dialog().querySelector('[data-agent-plan-id] input');assert(route?.checked && !submit().disabled, 'Sole route is not ready to submit');assert(!dialog().querySelector('details').open, 'Advanced settings are open on first enable');+ const history = dialog().querySelector('[data-codex-history-guidance]');+ assert(visible(history) && !history.closest('details'), 'Session-history guidance is hidden before enabling');+ assert(history.dataset.codexHistoryMode === 'profile' && !history.classList.contains('warn'), 'Default profile is presented as a root takeover warning');+ assert(history.textContent.includes('普通 Codex 的配置和会话历史不变')+ && history.textContent.includes('HiRoute profile 内的 /resume'), 'Default guidance does not limit provider filtering to the HiRoute profile');+ assert(history.textContent.includes('无需停用 HiRoute') && !history.textContent.includes('恢复完成')+ && history.textContent.includes('原 CODEX_HOME') && history.textContent.includes('原 profile')+ && history.textContent.includes('codex resume --all') && history.textContent.includes('绕过 HiRoute')+ && history.textContent.includes('凭据'), 'Default guidance requires disabling or omits the original entry and bypass semantics');assert(!dialog().querySelector('[data-agent-capability-preview]') && calls('plan_editor_options').length === 0, 'Enable still loads a read-only capacity preview');assert(dialog().textContent.includes('开启新会话'), 'Profile activation step is missing');const cancel = [...dialog().querySelectorAll('button')].find(button => button.textContent.trim() === '取消');cancel.click(); await tick();assert(!dialog() && calls('preview_agent_settings').length === 0 && c().operations.length === 0, 'Cancel applied a draft');}),+ scenario('codex.history.root-and-configured-guidance', ['agent-model-routing'], 'Codex distinguishes original-entry return from root restoration in setup and saved settings', async () => {+ await freshCodex('splitCodexStatus');+ const saved = document.querySelector('[data-codex-history-guidance]');+ assert(visible(saved) && saved.dataset.codexHistoryMode === 'root'+ && saved.textContent.includes('停用') && saved.textContent.includes('恢复完成')+ && saved.textContent.includes('codex resume --all')+ && saved.textContent.includes('绕过 HiRoute'), 'Configured connection has no supported original-provider entry');+ await openEditor('model', false);+ const history = dialog().querySelector('[data-codex-history-guidance]');+ assert(visible(history) && !history.closest('details'), 'Root takeover hides session-history warning in advanced settings');+ assert(history.classList.contains('warn') && history.textContent.includes('全部目录')+ && history.textContent.includes('会话文件仍然保留') && history.textContent.includes('恢复完成'), 'Root takeover omits provider filtering, preserved history or restoration');+ assert(dialog().querySelector('[data-codex-shared-scope]').textContent.includes('设为默认'), 'The root configuration was not exercised');+ assert(calls('preview_agent_settings').length === 0 && c().operations.length === 0, 'Reading history guidance changed configuration');+ [...dialog().querySelectorAll('button')].find(button => button.textContent.trim() === '取消').click();+ await tick();+ assert(!dialog() && visible(saved), 'Cancelling lost the saved recovery instructions');+ const access = c().agents.agents.find(agent => agent.agent_id === 'agent_codex_default').codex_access;+ access.selected_mode = 'profile'; c().refresh(); await tick();+ const profileSaved = document.querySelector('[data-codex-history-guidance]');+ assert(profileSaved.dataset.codexHistoryMode === 'profile' && profileSaved.textContent.includes('无需停用 HiRoute')+ && !profileSaved.classList.contains('warn'), 'Saved profile incorrectly requires restoration to use the ordinary entry');+ access.slot_occupied = false; c().refresh(); await tick();+ await openEditor('model');+ const mode = dialog().querySelector('[data-codex-access-mode] select');+ changeSelect(mode, 'root'); await tick();+ assert(dialog().querySelector('[data-codex-history-guidance]').textContent.includes('恢复完成'), 'Switching to root keeps the profile return path');+ changeSelect(mode, 'profile'); await tick();+ assert(dialog().querySelector('[data-codex-history-guidance]').textContent.includes('无需停用 HiRoute'), 'Switching back to profile keeps root restoration instructions');+ [...dialog().querySelectorAll('button')].find(button => button.textContent.trim() === '取消').click(); await tick();+ assert(!dialog() && calls('preview_agent_settings').length === 0 && c().operations.length === 0, 'Reading or changing draft guidance applied settings');+ }),scenario('claude.enable.shared-presets', ['agent-model-routing'], 'Claude first enable shares one route while retaining independent advanced presets', async () => {await fresh('notRunnable', true);await openEditor('model', false);diff --git a/apps/desktop/tests/v3/browser/scenario-requirements.mjs b/apps/desktop/tests/v3/browser/scenario-requirements.mjsindex 19451e48..ffbb8a25 100644--- a/apps/desktop/tests/v3/browser/scenario-requirements.mjs+++ b/apps/desktop/tests/v3/browser/scenario-requirements.mjs@@ -12,6 +12,7 @@ export const agentTrustRequired = ['codex.restore.conflict-active','hermes.routing.unavailable-and-exact-recovery','claude.routing.blocker-guidance','codex.enable.draft-cancel',+ 'codex.history.root-and-configured-guidance','claude.enable.shared-presets','codex.enable.confirmed-command','codex.routing.fixed-binding',diff --git a/docs/code-map/worker-context.md b/docs/code-map/worker-context.mdindex 8b13f923..dcdc4bc2 100644--- a/docs/code-map/worker-context.md+++ b/docs/code-map/worker-context.md@@ -24,6 +24,12 @@ report the actual installed consumers; [safe conflict facts](../../crates/domainretain rejection identity through compensation and client observation.Native defaults and collaboration stay independent;restoration must verify ownership rather than infer it from a provider name.++Codex's [connection guidance](../../apps/desktop/src/features/agents/CodexAccessPanel.tsx)+explains native provider-scoped session discovery before enabling routing. Default+on-demand access preserves the ordinary entry for earlier sessions; advanced default+takeover first requires configuration restoration. See [session recovery](../local-user-configuration.md#find-earlier-codex-sessions). Worker Continue below+has its own exact-history binding and does not replace the native `/resume` picker.OpenCode's [startup target binding](../../crates/daemon/src/control/runtime.rs) keepsthe physical JSON/JSONC file verified by existing recovery markers;[effective model facts](../../crates/integrations/src/agents/opencode_scanner.rs)diff --git a/docs/local-user-configuration.md b/docs/local-user-configuration.mdindex e41bf686..53cf4d89 100644--- a/docs/local-user-configuration.md+++ b/docs/local-user-configuration.md@@ -61,10 +61,10 @@ not adopt files by name or remove their authentication fields. Preserve your ownresolve the conflicting entry manually before a fresh preview.Profile mode uses native `codex --profile hiroute`; it does not provide a Desktop profile-launcher. History can differ between entry points. Cross-provider history restoration and-session database changes are outside this feature. Gateway credentials authorize the selected-models independently of the Codex client's OpenAI login; retaining original models still-requires a usable upstream source configured in HiRoute.+launcher. Session histories remain scoped to their native provider; HiRoute does not merge+histories or modify the session database. Gateway credentials authorize the selected models+independently of the Codex client's OpenAI login; retaining original models still requires a+usable upstream source configured in HiRoute.A pending operation reserves the home even if Gateway access is already revoked. The Agentpage shows the target and conflicting fields, and can recheck and resume the original Operation.@@ -82,6 +82,50 @@ Local CLI callers can resume that same operation through `agents connect apply`This retry accepts no new settings or grants. The daemon checks the stored operation and itscontext before continuing. First-time creation and edits still require normal Preview/Apply.+### Find earlier Codex sessions++Default **On demand** mode preserves ordinary Codex configuration and session+history. Use the ordinary Codex entry to find earlier sessions; the HiRoute profile+can remain enabled.++Inside the HiRoute profile, Codex filters its native `/resume` picker by HiRoute's+model provider. Sessions created with another provider can disappear from that+picker while their files remain in the same `CODEX_HOME`. Advanced **Use by default**+mode applies this provider change to ordinary Codex and Desktop as well. Selecting+all directories, or running `codex resume --all`, removes the directory filter;+it does not remove the provider filter. The model-routing form and configured+connection explain the selected mode's scope and return path.++### Return to the original provider++1. For default **On demand** mode, return to the ordinary Codex entry without+ the HiRoute profile. **No disable or configuration restoration is needed.**+ For advanced **Use by default** mode, open **Agents → Codex** in HiRoute and+ turn off **Model routing** first. Wait for configuration restoration to complete;+ resolve any reported file conflict or incomplete operation before continuing.+2. Exit the Codex instance using HiRoute. Open a terminal using the original+ `CODEX_HOME` shown in the connection's configuration details. Use the same+ original profile and working environment as before enabling HiRoute.+3. Run `codex resume --all` and select the earlier session. If the original entry+ used an explicit profile, retain it: `codex --profile <original-profile> resume --all`.+ The `hiroute` profile is the managed route, not the original entry.+4. Continuing the session uses the original provider and its account or API+ credentials. Those requests **bypass HiRoute**. The on-demand HiRoute profile+ remains available for separate sessions. Advanced default takeover changes the+ ordinary entry's provider again when re-enabled.++Advanced-mode restoration uses the existing conditional transaction for+HiRoute-owned configuration fields. Neither return path edits Codex's session files,+provider labels or private session database. Keep a backup of important history;+changing provider IDs or rewriting the database is not a supported migration.++For sessions created under several different original providers, use each+provider's original configuration and credentials. HiRoute cannot reconstruct a+configuration or account that was already missing before it was enabled.++The native commands are documented in the [official Codex CLI reference](https://developers.openai.com/codex/cli/reference/).+The configuration contract belongs to [Agent connections](../issue-spec/specs/agent-connections/spec.md).+## OpenCodeIn Agents, enable OpenCode model routing and select the published routes and eachdiff --git a/issue-spec/specs/agent-connections/spec.md b/issue-spec/specs/agent-connections/spec.mdindex 0082477f..075f60d1 100644--- a/issue-spec/specs/agent-connections/spec.md+++ b/issue-spec/specs/agent-connections/spec.md@@ -247,8 +247,26 @@ DTO may expose only the exact codex_home/target_file/commands needed for this acother paths remain masked and no credential is included. This exception does notapply to diagnostics or remote telemetry. Gateway validates token/model scope,not directory hiding or launch argument filtering. Pure HiRoute needs no Codex-OpenAI login and promises neither Desktop profile launch nor cross-provider history-recovery. Native history labels/databases are not rewritten.+OpenAI login and does not promise Desktop profile launch or migration of sessions+between providers. Native history labels/databases are not rewritten.++Before enabling model routing, the ordinary Codex form visibly explains session+discovery for the selected mode; the configured connection retains this guidance.+Default on-demand mode preserves ordinary Codex configuration and session history.+Earlier-provider sessions can be hidden from `/resume` inside the HiRoute profile;+returning to the original entry does not require disabling HiRoute. Advanced+default takeover warns that the provider filter can hide earlier sessions even+in the all-directories view, while retaining their files. Only this mode requires+turning off model routing and completing native configuration restoration before+returning to the original default entry. An incomplete or conflicting restore+does not authorize claiming that entry is restored.++Both modes direct users to their original CODEX_HOME and original profile with+`codex resume --all` to select an earlier session. This original entry uses the+original provider, bypasses HiRoute and needs that provider's credentials. Native+acceptance proves earlier-session discovery and resume through the ordinary entry+while the on-demand HiRoute profile remains configured; profile isolation alone+does not establish resume success.Restore preserves unrelated user fields and new content in a created profile.Originally missing profile fields resume inheriting current root rather than writing