@aragon-agent/cli 0.6.12 → 0.6.13

package/README.md

@@ -432,8 +432,8 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 
 | Key | Action |
 | --- | --- |
-| `Enter` | Submit (idle) / queue a steering message (running) — shown as `Queue: …` until the agent picks it up |
-| `Ctrl+J` / `Alt+Enter` / `Shift+Enter` | Insert a newline. `Ctrl+J` and `Alt+Enter` work everywhere; a distinct `Shift+Enter` needs a one-line terminal binding — see [`/terminal-setup`](#terminal-setup) |
+| `Enter` | 空闲时发送，运行时加入队列；收到 Core 已纳入会话的接收凭据后才移除 Queue 提示 |
+| `Ctrl+J` / `Alt+Enter` / `Shift+Enter` | 插入换行。Ctrl+J 已通过输入链路测试；另外两种组合键需要宿主发送独立序列，Alt+Enter 可能被宿主拦截。参见 [终端设置](#terminal-setup-for-shiftenter) |
 | `Shift+Tab` | Toggle **plan mode** (`BUILD` <-> `PLAN`). Equivalent: `/plan`. On Windows this needs a console flag Node < 22.17 does not set; aragon sets it at startup — see [Requirements](#requirements) |
 | `Ctrl+P` | The same toggle, over a channel no Windows console can swallow. Use it if `Shift+Tab` does nothing |
 | `Esc` | Close an overlay or popup; otherwise ask for interruption confirmation. While idle, cancel pending auto-continuation |
@@ -452,7 +452,7 @@ completes, `Up` / `Down` moves the selection, `Esc` closes it.
 | `Alt/Ctrl+←` / `→` | Word-wise cursor jump |
 | `Ctrl+W`, `Alt+Backspace` | Delete the previous word |
 | `Ctrl+U` / `Ctrl+K` | Kill to line start / end |
-| `Up` / `Down` | Move between draft lines; recall prompt history at the edges |
+| `Up` / `Down` | 按视觉行移动；空草稿或正在浏览历史时，才在边界召回历史，避免覆盖新草稿 |
 | Paste | Inserted as-is up to 6 lines / 400 chars; larger collapses to `[Pasted text #1 +15 lines]`, which deletes as one unit and expands in full when you send. `--no-paste` restores the pre-0.6.3 behaviour |
 | `?` | Open help (empty input) |
 
@@ -462,7 +462,7 @@ new output automatically; once you scroll away the status bar shows `↑N`, a sl
 scrollbar occupies the terminal's last column (including 40-column windows). Drag its thumb
 to move through history, or click the track to move one page. Messages, the team panel
 and the input area scroll together; typing or editing returns to the input without
-losing the draft. The fixed status row shows `PgDn down` while reading history.
+losing the draft. The fixed status row reports the distance from the end while reading history.
 `PgDn` moves one page down; editing or submitting returns directly to the end.
 
 **The mouse wheel is a viewport gesture and nothing else.** Wherever the pointer
@@ -498,10 +498,9 @@ Shift+Enter 与 Enter 都发送为 CR，应用无法区分；请用 `/terminal-s
 让 Shift+Enter 发送 `\u001b[13;2u`。合并到已有终端配置，不要覆盖其他快捷键；
 终端拦截某个组合键时可使用另外两种方式。参考绑定如下：
 
-- **Windows Terminal** — `settings.json`, `actions`:
-  `{ "keys": "shift+enter", "command": { "action": "sendInput", "input": "\u001b[13;2u" } }`
+- **Windows Terminal** — `settings.json` 的 `actions` 与 `keybindings` 分别定义动作和按键；完整示例见下文“输入、待处理队列与底部状态区”。
 - **VS Code integrated terminal** — `keybindings.json`:
-  `{ "key": "shift+enter", "command": "workbench.action.terminal.sendSequence", "args": { "text": "\u001b[13;2u" } }`
+  `{ "key": "shift+enter", "command": "workbench.action.terminal.sendSequence", "when": "terminalFocus", "args": { "text": "\u001b[13;2u" } }`
 - **iTerm2** — Settings > Profiles > Keys > Key Mappings, `Shift+Enter` ->
   *Send Escape Sequence* `[13;2u`
 - **kitty / WezTerm / foot** — native once keyboard-enhancement mode is on
@@ -518,9 +517,9 @@ user-side binding reaches the same result for the one key that needs it.
 
 ## Queued messages while the agent runs
 
-Agent 运行中发送的消息会进入队列。固定状态行显示最早待接收消息的首个非空行，
-多条时显示剩余数量；即使转录滚动离开底部，提示仍可见，且没有自动消失的时间限制。
-转录同时保留每条完整消息：
+Agent 运行中发送的消息会进入队列。输入框附近的独立 Queue 面板按顺序显示摘要，
+限高后显示隐藏条数；固定状态栏始终显示真实待处理总数，没有自动消失的时间限制。
+使用 `/queue` 分页查看所有消息的完整原文，未接收消息不会在普通转录中重复显示：
 
 ```
 ◷ Queue: also check the tests
@@ -528,11 +527,9 @@ Agent 运行中发送的消息会进入队列。固定状态行显示最早待
 
 仅当 Core 将消息写入对话历史并发出对应消息 ID 的接收回执，Queue 状态才移除。
 这表示引擎已接管后续处理，不表示回答完成；`turn_start`、动画和提示超时都不能代替回执。
-相同正文的两次发送仍是两条消息。中断或失败后尚未接收的消息显示 `Queue (paused)`。
-
-窄屏使用 `P>B` / `B>P` 表示待切换模式，`E2` / `E!` 表示两次 Esc 中断 / 再按 Esc 强停，
-`S+` / `T+` 表示后台服务 / TODO 存在，`Queue(p)` 表示暂停；`(+99+)` 表示至少还有
-100 条消息。完整服务和 TODO 数量分别可用 `/bg` 与 `/todo status` 查看。
+相同正文的两次发送仍是两条消息。中断或失败后尚未接收的消息保留并标记暂停。
+窄屏优先保留运行状态、待处理数量和上下文；其他字段整项隐藏，不截断关键数值。
+快捷键集中在操作提示行，并随覆盖层、补全、选区和中断确认状态变化。
 
 `/clear` 清转录和 TODO，但保留待接收队列。保存和退出会补回被清屏或保留环裁剪的
 未发送全文。恢复存档时，queued 一律成为 `Queued but never sent: ...` 警告，
@@ -2345,3 +2342,72 @@ UTF-16 编辑和 ZWJ/组合字形仍有既有限制，本次修复保证视觉
 检查流式输出不阻止闪烁；单 ESC 不停止任务，两击中断，卡住时第三击强停；菜单关闭不计入两击。
 任务结束后保留最终计划，下一条普通消息启动时旧计划消失，新有效计划出现才恢复；显式续跑保留计划。
 强停后立即提交，在等待中双 ESC 取消，旧引擎退出后不得自行执行已取消的消息。
+
+## 输入、待处理队列与底部状态区
+
+Enter 在空闲时发送，运行时加入队列；启动阶段拒绝重复提交并保留草稿。
+Ctrl+J 换行；终端能发送独立序列时，Shift+Enter 与 Alt+Enter 也可换行。
+光标按完整字素移动，支持中文、组合字符和 emoji；输入最多占终端高度四分之一且不超过六行。
+括号粘贴保留换行，不触发发送。过滤器或粘贴支持关闭时，不保证未标记多行粘贴安全。
+过滤器不可用时 Delete 保守按 Backspace 处理，避免退格误删后文。
+
+应用鼠标拖选只建立选区，Ctrl+C 才复制；复制中再次按 Ctrl+C 不会退出或停止服务。
+原生剪贴板工具完成后显示确认，OSC 52 只表示请求已发送，终端可能拒绝。
+Shift+拖动或 `/mouse off` 后的选区由宿主管理，应用无法关闭宿主的自动复制。
+
+Queue 面板逐条显示待处理消息，数量始终留在状态栏。只有 Core 已把消息纳入会话并发回接收凭据，
+该条提示才会消失。中断时未接收消息显示暂停；`/queue` 可分页查看全部原文，Esc 关闭。
+`/clear` 不丢待处理消息；`/reset`、切换会话会明确报告取消数量；恢复保存的未发送历史不会自动重发。
+
+底部依次为输入框、固定操作提示/短反馈行、全局状态栏。状态字段按显示宽度完整保留或整项隐藏。
+上下文表示当前主 Agent 的已用/上限 tokens；`~` 表示含估算，`?` 表示上限未知。
+费用是含子代理、快速模型及压缩的会话估算 USD，恢复会话沿用累计，缺价格按零计，零值不保证免费。
+本轮均速是本轮期间入账输出 token 增量除以耗时，可能包含上述辅助调用，并非瞬时生成速度。
+`/context` 提供统计范围和完整值。
+
+Windows Terminal：在设置 JSON **根级**添加 `"copyOnSelect": false`，把以下条目合并到已有数组：
+
+```json
+{
+  "actions": [{ "id": "User.AragonNewline", "command": {
+    "action": "sendInput", "input": "\u001b[13;2u"
+  } }],
+  "keybindings": [{ "keys": "shift+enter", "id": "User.AragonNewline" }]
+}
+```
+
+依据：[Windows Terminal 交互设置](https://learn.microsoft.com/en-us/windows/terminal/customize-settings/interaction)、
+[按键动作](https://learn.microsoft.com/en-us/windows/terminal/customize-settings/actions)。PowerShell 是 shell，不能在其 profile 中设置终端按键映射。
+
+VS Code 用户设置添加 `"terminal.integrated.copyOnSelection": false`，快捷键 JSON 添加：
+
+```json
+{
+  "key": "shift+enter", "command": "workbench.action.terminal.sendSequence",
+  "when": "terminalFocus", "args": { "text": "\u001b[13;2u" }
+}
+```
+
+依据：[终端基础](https://code.visualstudio.com/docs/terminal/basics)、
+[终端高级设置](https://code.visualstudio.com/docs/terminal/advanced)。应用的 `/terminal-setup` 只输出说明，不修改宿主配置。
+若宿主把 Shift+Enter 或 IME 候选确认同样编码为 CR，应用无法从相同字节推断用户意图。
+可使用经输入链路测试的 Ctrl+J、独立 CSI-u 绑定及外部编辑后括号粘贴；具体宿主组合仍需实测。
+双宿主、微软拼音及持续流式性能验收状态见 `docs/plans/tui-composer-queue-status/manual-test.md`。
+
+## 多套模型配置
+
+在 `/settings` 中使用 **Main profile** 和 **Fast profile**，可以分别为主任务与快速模型选择已保存的方案。两种角色共享配置库，但各自选择互不影响，也可以选择同一个方案。**Manage profiles** 提供新建、编辑、复制和删除；名称留空时采用模型名。同名方案通过地址主机和唯一 ID 区分。超过八条时按 `/` 搜索名称、模型或服务商。
+
+上下方向键或 Tab 移动，Enter 选择或编辑，根设置页 Ctrl+S 保存。普通文本字段的 Enter 仍保存设置。选择和子表单的修改先进入草稿；Esc 返回或确认丢弃。被主模型或快速模型引用的方案必须先解除绑定才能删除。复制包含本轮已经编辑的凭据，并产生新的 ID。
+
+方案保存服务商、模型、地址和凭据，不改变思考级别、token 上限、快速评审频率或预算。选择快速模型方案不会自动启用快速层。若本次启动时快速层未注册，首次启用会提示“已保存，待重启”；缺少模型或凭据时也需要先补齐。
+
+**Current custom** 保留旧式连接，可继续编辑原连接字段。创建方案时从磁盘上的旧式配置预填，不复制环境变量或 `--api-key` 的运行时密钥。专属密钥可保持、替换或切换为共享/环境凭据；修改服务商或地址后，必须明确选择保留原密钥，或重新输入。空地址在方案中表示服务商默认地址，快速方案不会继承主网关。
+
+启动优先级为 CLI 参数、环境变量、所选方案、旧式字段、默认值。界面显示启动覆盖；明确重新选择方案可对本次会话立即生效，重启仍遵循启动参数。专属密钥仅对对应角色和目标地址生效；主模型启动密钥不会跟随切换发往另一个网关。
+
+运行、团队任务、后台评审或压缩尚未结束时禁止保存。保存采用原子文件替换，同时检查磁盘与当前会话版本；失败保留草稿，发生冲突时选择 Reload settings。写入已成功但会话应用异常时会明确提示重启并禁用重复保存。跨进程版本检查属于乐观检查，不能消除同时写入的极小竞态。
+
+`/model`、`/fast model` 和 `config set` 修改连接会回到对应角色的自定义配置。若解除绑定会丢失专属账户或默认地址语义，命令会拒绝并引导到设置中编辑或复制。`/reload` 会一起刷新两个角色的连接和凭据，保留对话与用量。
+
+配置库仍位于 `ARAGON_HOME` 指向目录中的 `config.json`，不写入会话文件。密钥按现有机制明文保存：POSIX 创建权限为 0600，Windows 依赖用户目录 ACL，不提供加密。`config get/list` 对方案密钥使用固定掩码；损坏或未来版本的配置段整体隐藏。既有 `config edit` 备份也包含凭据。关闭通用日志脱敏、使用短密钥或分享第三方 SDK 错误日志时，仍需自行检查日志内容。

package/dist/agent/controller.d.ts

@@ -1,3 +1,5 @@
+import { type ModelSettingsSnapshot } from './model-profile-settings.js';
+import type { ModelSettingsDraft, ModelSettingsPatch, ModelSettingsSaveResult } from '../config/model-profile-store.js';
 /**
  * AgentController — builds the core `Agent`, wires the built-in toolset, and
  * exposes a small run/abort/steer surface plus the pre-flight validation that
@@ -11,6 +13,7 @@
 import type { PromptOptions, PromptOutcome } from './prompt-options.js';
 import { ModelRegistry, type AgentEvent, type AgentTool, type Message, type ModelInfo, type ModelRef, type ProviderRegistry, type ThinkingLevel } from '@aragon-agent/core';
 import type { CliConfig, CompactionConfig, FastConfig, RetryConfig, TeamConfig, ThemeName, TodoConfig } from '../config/schema.js';
+import type { ModelRole } from '../config/model-profiles.js';
 import { type ConfirmRequest } from '../tools/index.js';
 import type { ToolPermission } from '../exec/permission.js';
 import { type ToolOutputListener } from '../tools/tool-output-store.js';
@@ -180,6 +183,9 @@ export declare class AgentController {
     private readonly outputListeners;
     private readonly fast;
     private readonly compaction;
+    private settingsRevision;
+    private modelSettingsBlocked;
+    private preparedSystemPrompt;
     private readonly contextMeter;
     private readonly procs;
     /**
@@ -249,7 +255,7 @@ export declare class AgentController {
      * Read-only CLI-layer helper for the Header/Welcome key-status dot (P1-1);
      * does not touch `@aragon-agent/core`.
      */
-    hasApiKey(provider?: string): boolean;
+    hasApiKey(provider?: string, role?: ModelRole): boolean;
     /**
      * Set the color theme live. Mirrors the `setModel` / `setThinkingLevel`
      * mutator pattern — a subsequent re-render re-reads `getConfig().theme` and
@@ -524,6 +530,28 @@ export declare class AgentController {
      * the runtime nor the file.
      */
     setRetryConfig(patch: Partial<RetryConfig>): RetryConfig;
+    /** True while any request can still use a model or credential snapshot. */
+    isModelSettingsBusy(): boolean;
+    /** Monotonic revision protects an editor from all intervening settings changes. */
+    getSettingsRevision(): number;
+    /** Read-only draft creation; no startup migration or credential copying. */
+    createModelSettingsDraft(): ModelSettingsDraft;
+    /** Save an explicit draft as a single disk/live transaction. */
+    saveModelSettings(draft: ModelSettingsDraft): ModelSettingsSaveResult;
+    /** Legacy commands share the same lossless conversion and atomic save path. */
+    saveModelSettingsPatch(patch: ModelSettingsPatch): ModelSettingsSaveResult;
+    /** Refresh both role connections and credentials while retaining conversation state. */
+    reloadModelSettings(): ModelSettingsSaveResult;
+    /** Prebuild all potentially failing model/prompt work before committing the file. */
+    prepareModelSettingsSnapshot(config: CliConfig): ModelSettingsSnapshot;
+    /** Apply prepared state synchronously, without rebuilding the controller or its history. */
+    applyModelSettingsSnapshot(snapshot: ModelSettingsSnapshot): void;
+    /** Potentially failing ordinary-setting side effects are isolated from model application. */
+    applyModelSettingsEffects(): void;
+    /** A partially applied model snapshot must never reach another provider request. */
+    blockModelSettingsRequests(): void;
+    /** The UI uses this before accepting or draining queued prompts. */
+    areModelSettingsBlocked(): boolean;
     setModel(provider: string, model: string, baseUrl?: string): void;
     setThinkingLevel(level: ThinkingLevel): void;
     setMaxTokens(value: number | undefined): void;

package/dist/agent/controller.js

@@ -1,6 +1,8 @@
+import { createModelSettingsDraft, saveModelSettings, reloadModelSettings, } from './model-profile-settings.js';
 import { randomUUID } from 'node:crypto';
 import { Agent, initProviders, ModelRegistry, } from '@aragon-agent/core';
 import { clampCompactionConfig, clampFastConfig, clampRetryConfig, clampTeamConfig, clampTodoConfig, isAdapterProvider, toRetryPolicy, } from '../config/schema.js';
+import { resolveModelProfileState } from '../config/model-profile-resolution.js';
 import { makeGetApiKey } from '../config/load.js';
 import { updatePersistedConfig } from '../config/store.js';
 import { createBuiltinTools } from '../tools/index.js';
@@ -194,6 +196,9 @@ export class AgentController {
     // no timer while it has no subscribers, so the extra object is a few scalars
     // and a `Set`.
     // -----------------------------------------------------------------------
+    settingsRevision = 0;
+    modelSettingsBlocked = false;
+    preparedSystemPrompt;
     contextMeter;
     // -----------------------------------------------------------------------
     // Background services (background-service-supervision §3.3 / §3.6)
@@ -297,7 +302,7 @@ export class AgentController {
         // ONCE (C-2). `FastWiring` re-runs the same pure function in its own
         // constructor; the two agree by construction because they read the same
         // config through the same resolver.
-        const fastTier = resolveFastTier(config, (id) => this.hasApiKey(id));
+        const fastTier = resolveFastTier(config, (id, role) => this.hasApiKey(id, role));
         const fastRegistered = fastTier.ok;
         // --- Team mode ---------------------------------------------------------
         this.teamRegistered = config.team.enabled;
@@ -321,11 +326,12 @@ export class AgentController {
                             ...(this.config.baseUrl ? { baseUrl: this.config.baseUrl } : {}),
                         },
                         thinkingLevel: this.config.thinkingLevel,
+                        role: 'main',
                     },
                 providerRegistry: this.providerRegistry,
                 getCwd: () => this.cwd,
                 getMode: () => this.effectiveMode,
-                getApiKey: (id) => this.resolveKey(id),
+                getApiKey: (id, role) => this.resolveKey(id, role),
                 // `skill_find` only, and the lead's always-on bodies. See the long
                 // note in `subagent.ts` for why `skill` itself is withheld (D-16).
                 ...(this.skillsEnabled
@@ -545,8 +551,8 @@ export class AgentController {
         this.compaction = config.compaction.enabled
             ? new CompactionWiring({
                 getConfig: () => this.config,
-                hasKey: (id) => this.hasApiKey(id),
-                getApiKey: (id) => this.resolveKey(id),
+                hasKey: (id, role) => this.hasApiKey(id, role),
+                getApiKey: (id, role) => this.resolveKey(id, role),
                 getModelInfoFor: (ref) => this.getModelInfoFor(ref),
                 isPricedModel: (ref) => this.isPricedModel(ref),
                 getMessages: () => this.agent.state.messages,
@@ -623,8 +629,8 @@ export class AgentController {
         this.fast = fastRegistered
             ? new FastWiring({
                 getConfig: () => this.config,
-                hasKey: (id) => this.hasApiKey(id),
-                getApiKey: (id) => this.resolveKey(id),
+                hasKey: (id, role) => this.hasApiKey(id, role),
+                getApiKey: (id, role) => this.resolveKey(id, role),
                 isPricedModel: (ref) => this.isPricedModel(ref),
                 subscribe: (listener) => this.agent.subscribe(listener),
                 complete: (providerId, request) => this.providerRegistry.complete(providerId, request),
@@ -673,8 +679,8 @@ export class AgentController {
         if (problem)
             deps.notify?.('warn', problem);
     }
-    resolveKey(providerId) {
-        return makeGetApiKey(this.config)(providerId);
+    resolveKey(providerId, role = 'main') {
+        return makeGetApiKey(this.config, role)(providerId);
     }
     /**
      * The tool names registered right now — LAZY, and the laziness is required.
@@ -705,27 +711,30 @@ export class AgentController {
     // suddenly denies having any skills). Structure, not call ordering, is what
     // rules that out — so if you add a third caller, route it through here.
     // -----------------------------------------------------------------------
-    composeSystemPrompt() {
+    composeSystemPrompt(config = this.config) {
+        const tier = resolveFastTier(config, (id, role) => !!makeGetApiKey(config, role)(id));
+        const fastAvailable = config === this.config ? this.fast?.available() === true
+            : this.fast?.isRegistered() && config.fast.enabled && tier.ok;
         return buildSystemPrompt({
             cwd: this.cwd,
             tools: this.tools,
             skillsBlock: this.skillsEnabled ? this.skills.catalogBlock() + this.skills.alwaysBlock() : '',
             agentMode: this.effectiveMode,
             planInteractive: this.planInteractive,
-            planMaxAskRounds: this.config.planModeMaxAskRounds,
+            planMaxAskRounds: config.planModeMaxAskRounds,
             // BOTH flags, and both are required (§4.5). `teamRegistered` false means
             // there is no `task` tool to advertise; `teamEnabled` false means the user
             // turned it off for this session. Advertising in either case would
             // describe a capability the model does not have.
             teamBlock: this.teamRegistered && this.teamEnabled
                 ? buildTeamBlock({
-                    maxSubagents: this.config.team.maxSubagents,
-                    maxConcurrent: this.config.team.maxConcurrent,
+                    maxSubagents: config.team.maxSubagents,
+                    maxConcurrent: config.team.maxConcurrent,
                     // One cross-reference sentence, present only when the capability
                     // is (§3.8). `this.fast` is null during the FIRST compose (the
                     // wiring needs the Agent), which is why the constructor composes
                     // again once it exists.
-                    fastDelegation: this.fast?.delegationAvailable() === true,
+                    fastDelegation: !!fastAvailable && config.fast.delegate,
                 })
                 : '',
             // BOTH FLAGS, exactly as team mode uses both, and for the identical
@@ -735,18 +744,18 @@ export class AgentController {
             // model does not have.
             todoBlock: this.todoRegistered && this.todoEnabled
                 ? buildTodoBlock({
-                    panelVisible: this.todoPanelCapable && this.config.todo.panel,
+                    panelVisible: this.todoPanelCapable && config.todo.panel,
                 })
                 : '',
             // The SAME two flags one more time, plus the live resolution — all three
             // live inside `FastWiring.available()` (§3.3). `buildFastBlock` itself
             // returns `''` when neither capability is on, so a user who turned both
             // off pays nothing for the tier being technically live.
-            fastBlock: this.fast && this.fast.available()
+            fastBlock: fastAvailable
                 ? buildFastBlock({
-                    model: this.fast.fastRef()?.modelId ?? '',
-                    delegate: this.config.fast.delegate,
-                    review: this.config.fast.review,
+                    model: tier.ok ? tier.ref.modelId : '',
+                    delegate: config.fast.delegate,
+                    review: config.fast.review,
                 })
                 : '',
             // ONE FLAG, unlike team/todo's two: there is no live on/off switch for
@@ -762,7 +771,7 @@ export class AgentController {
         });
     }
     rebuildSystemPrompt() {
-        this.agent.setSystemPrompt(this.composeSystemPrompt());
+        this.agent.setSystemPrompt(this.preparedSystemPrompt ?? this.composeSystemPrompt());
     }
     /** Re-render the prompt from the current skill set and tell the UI. */
     refreshSkills() {
@@ -781,8 +790,10 @@ export class AgentController {
      * Read-only CLI-layer helper for the Header/Welcome key-status dot (P1-1);
      * does not touch `@aragon-agent/core`.
      */
-    hasApiKey(provider) {
-        const key = this.resolveKey(provider ?? this.config.provider);
+    hasApiKey(provider, role = 'main') {
+        const activeProvider = role === 'fast'
+            ? this.config.fast.provider || this.config.provider : this.config.provider;
+        const key = this.resolveKey(provider ?? activeProvider, role);
         return !!key && key.trim().length > 0;
     }
     /**
@@ -791,6 +802,7 @@ export class AgentController {
      * re-memoizes the palette (P1-1). Does not touch `@aragon-agent/core`.
      */
     setTheme(name) {
+        this.settingsRevision += 1;
         this.config = { ...this.config, theme: name };
     }
     /**
@@ -811,6 +823,9 @@ export class AgentController {
     // Pre-flight (R2): validate BEFORE entering the loop.
     // -----------------------------------------------------------------------
     preflight() {
+        if (this.modelSettingsBlocked)
+            return { ok: false, kind: 'config',
+                message: 'Settings were saved but not fully applied. Restart before sending requests.' };
         const provider = this.config.provider;
         if (!isAdapterProvider(provider)) {
             return {
@@ -845,6 +860,9 @@ export class AgentController {
      */
     async prompt(text, options = {}) {
         // Capture BEFORE stopping: synchronous abort listeners may cancel this request.
+        if (this.modelSettingsBlocked) {
+            return { status: 'not-started', reason: 'failed' };
+        }
         const request = ++this.startupSequence;
         try {
             if (this.agent.state.isRunning) {
@@ -1054,7 +1072,14 @@ export class AgentController {
         const id = user ? `${this.steeringPrefix}:${++this.steeringSequence}` : undefined;
         if (id !== undefined)
             this.pendingUserSteering.add(id);
-        this.agent.steer(text, id);
+        try {
+            this.agent.steer(text, id);
+        }
+        catch (error) {
+            if (id !== undefined)
+                this.pendingUserSteering.delete(id);
+            throw error;
+        }
         return id;
     }
     followUp(text) {
@@ -1192,6 +1217,7 @@ export class AgentController {
      * honestly by checking `isTeamRegistered()` first.
      */
     setTeamEnabled(enabled) {
+        this.settingsRevision += 1;
         this.teamEnabled = enabled;
         this.rebuildSystemPrompt();
     }
@@ -1205,6 +1231,7 @@ export class AgentController {
      */
     setTeamConfig(patch) {
         const team = clampTeamConfig({ ...this.config.team, ...patch });
+        this.settingsRevision += 1;
         this.config = { ...this.config, team };
         this.rebuildSystemPrompt();
         return team;
@@ -1266,6 +1293,7 @@ export class AgentController {
      * reports that honestly by checking `isTodoRegistered()` first.
      */
     setTodoEnabled(enabled) {
+        this.settingsRevision += 1;
         this.todoEnabled = enabled;
         this.rebuildSystemPrompt();
     }
@@ -1288,6 +1316,7 @@ export class AgentController {
      */
     setTodoConfig(patch) {
         const todo = clampTodoConfig({ ...this.config.todo, ...patch });
+        this.settingsRevision += 1;
         this.config = { ...this.config, todo };
         this.rebuildSystemPrompt();
         return todo;
@@ -1343,6 +1372,7 @@ export class AgentController {
      */
     setRetryConfig(patch) {
         const retry = clampRetryConfig({ ...this.config.retry, ...patch });
+        this.settingsRevision += 1;
         this.config = { ...this.config, retry };
         this.providerRegistry.setRetryPolicy(toRetryPolicy(retry));
         return retry;
@@ -1350,8 +1380,69 @@ export class AgentController {
     // -----------------------------------------------------------------------
     // Mutators
     // -----------------------------------------------------------------------
+    /** True while any request can still use a model or credential snapshot. */
+    isModelSettingsBusy() {
+        return this.isRunning() || this.isTeamBusy() || this.getCompactionSnapshot().inFlight
+            || this.getFastStatus().snapshot.inFlight;
+    }
+    /** Monotonic revision protects an editor from all intervening settings changes. */
+    getSettingsRevision() { return this.settingsRevision; }
+    /** Read-only draft creation; no startup migration or credential copying. */
+    createModelSettingsDraft() {
+        return createModelSettingsDraft(this.config, this.settingsRevision);
+    }
+    /** Save an explicit draft as a single disk/live transaction. */
+    saveModelSettings(draft) {
+        return saveModelSettings({ draft, controller: this });
+    }
+    /** Legacy commands share the same lossless conversion and atomic save path. */
+    saveModelSettingsPatch(patch) {
+        const draft = this.createModelSettingsDraft();
+        draft.profiles = undefined;
+        draft.patch = patch;
+        return this.saveModelSettings(draft);
+    }
+    /** Refresh both role connections and credentials while retaining conversation state. */
+    reloadModelSettings() { return reloadModelSettings(this); }
+    /** Prebuild all potentially failing model/prompt work before committing the file. */
+    prepareModelSettingsSnapshot(config) {
+        return { config, model: { providerId: config.provider, modelId: config.model,
+                ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}) },
+            systemPrompt: this.composeSystemPrompt(config) };
+    }
+    /** Apply prepared state synchronously, without rebuilding the controller or its history. */
+    applyModelSettingsSnapshot(snapshot) {
+        this.preparedSystemPrompt = snapshot.systemPrompt;
+        try {
+            this.config = snapshot.config;
+            this.settingsRevision += 1;
+            this.agent.setModel(snapshot.model);
+            this.agent.setThinkingLevel(snapshot.config.thinkingLevel);
+            this.agent.setMaxTokens(snapshot.config.maxTokens);
+            this.fast?.onConfigChanged(false, snapshot.config.fast.enabled);
+            this.compaction?.onConfigChanged(snapshot.config.compaction.enabled);
+            this.contextMeter.onWindowChanged();
+            this.rebuildSystemPrompt();
+        }
+        finally {
+            this.preparedSystemPrompt = undefined;
+        }
+    }
+    /** Potentially failing ordinary-setting side effects are isolated from model application. */
+    applyModelSettingsEffects() { getLogger().reconfigure(this.config.log); }
+    /** A partially applied model snapshot must never reach another provider request. */
+    blockModelSettingsRequests() {
+        this.modelSettingsBlocked = true;
+        this.config.modelSettingsRestartRequired = true;
+    }
+    /** The UI uses this before accepting or draining queued prompts. */
+    areModelSettingsBlocked() { return this.modelSettingsBlocked; }
     setModel(provider, model, baseUrl) {
+        if (this.isModelSettingsBusy())
+            throw new Error('Model settings are busy.');
+        this.settingsRevision += 1;
         this.config = { ...this.config, provider, model, baseUrl };
+        this.config.modelProfileState = resolveModelProfileState(this.config);
         this.agent.setModel({ providerId: provider, modelId: model, ...(baseUrl ? { baseUrl } : {}) });
         // NOT NEUTRAL TO THE FAST TIER even when the user never touched a `fast.*`
         // key (§3.9 / RV-3): `fast.provider: ''` and `fast.baseUrl: ''` INHERIT from
@@ -1373,16 +1464,19 @@ export class AgentController {
         this.contextMeter.onWindowChanged();
     }
     setThinkingLevel(level) {
+        this.settingsRevision += 1;
         this.config = { ...this.config, thinkingLevel: level };
         this.agent.setThinkingLevel(level);
     }
     setMaxTokens(value) {
+        this.settingsRevision += 1;
         this.config = { ...this.config, maxTokens: value };
         this.agent.setMaxTokens(value);
     }
     setApiKey(provider, key) {
         // The Agent resolves keys via `resolveKey(this.config)` at call time, so
         // updating the config here is sufficient — no Agent rebuild needed.
+        this.settingsRevision += 1;
         this.config = {
             ...this.config,
             apiKeys: { ...this.config.apiKeys, [provider]: key },
@@ -1397,6 +1491,7 @@ export class AgentController {
     }
     setCwd(cwd) {
         this.cwd = cwd;
+        this.settingsRevision += 1;
         this.config = { ...this.config, cwd };
         // The project scope moved with the cwd, so rescan BEFORE rebuilding — then
         // let the single prompt entry point emit a prompt that reflects both the new
@@ -1581,6 +1676,7 @@ export class AgentController {
      * `/fast` reports that honestly by checking `isFastRegistered()` first.
      */
     setFastEnabled(enabled) {
+        this.settingsRevision += 1;
         this.fast?.setEnabled(enabled);
     }
     getFastConfig() {
@@ -1596,6 +1692,7 @@ export class AgentController {
      */
     setFastConfig(patch) {
         const fast = clampFastConfig({ ...this.config.fast, ...patch });
+        this.settingsRevision += 1;
         this.config = { ...this.config, fast };
         // `onConfigChanged` rebuilds the prompt; when there is no wiring (the tier
         // was never registered) nothing has to be rebuilt, because no block is
@@ -1695,6 +1792,7 @@ export class AgentController {
      * on purpose (§3.2).
      */
     setCompactionEnabled(enabled) {
+        this.settingsRevision += 1;
         this.compaction?.setEnabled(enabled);
     }
     getCompactionConfig() {
@@ -1709,6 +1807,7 @@ export class AgentController {
      */
     setCompactionConfig(patch) {
         const compaction = clampCompactionConfig({ ...this.config.compaction, ...patch });
+        this.settingsRevision += 1;
         this.config = { ...this.config, compaction };
         this.compaction?.onConfigChanged();
         return compaction;
@@ -1757,6 +1856,8 @@ export class AgentController {
      * unbypassable. `replaceMessages` validates NOTHING.
      */
     async compactNow(instructions) {
+        if (this.modelSettingsBlocked)
+            return { ok: false, reason: 'settings_restart_required' };
         if (!this.compaction)
             return { ok: false, reason: 'not_registered' };
         const controller = new AbortController();

package/dist/agent/model-profile-settings.d.ts

@@ -0,0 +1,31 @@
+import type { ModelRef } from '@aragon-agent/core';
+import { type CliConfig } from '../config/schema.js';
+import { type ModelSettingsDraft, type ModelSettingsSaveResult } from '../config/model-profile-store.js';
+/** Fully prepared live state; applying it performs no input parsing or disk access. */
+export interface ModelSettingsSnapshot {
+    config: CliConfig;
+    model: ModelRef;
+    systemPrompt: string;
+}
+/** Narrow controller port keeps persistence independent from the agent implementation. */
+export interface ModelSettingsController {
+    getConfig(): CliConfig;
+    getSettingsRevision(): number;
+    isModelSettingsBusy(): boolean;
+    isFastRegistered(): boolean;
+    prepareModelSettingsSnapshot(config: CliConfig): ModelSettingsSnapshot;
+    applyModelSettingsSnapshot(snapshot: ModelSettingsSnapshot): void;
+    applyModelSettingsEffects(): void;
+    blockModelSettingsRequests(): void;
+}
+/** Capture both baselines when the editor opens, without migrating or writing anything. */
+export declare function createModelSettingsDraft(live: CliConfig, liveRevision: number): ModelSettingsDraft;
+/** Map stable failure codes to safe UI text; never include parser or SDK error messages. */
+export declare function modelSettingsResultMessage(result: ModelSettingsSaveResult): string;
+/** Validate and prepare everything before the one synchronous, atomic disk commit. */
+export declare function saveModelSettings(input: {
+    draft: ModelSettingsDraft;
+    controller: ModelSettingsController;
+}): ModelSettingsSaveResult;
+/** Reload the complete model snapshot; invalid disk content never replaces a live session. */
+export declare function reloadModelSettings(controller: ModelSettingsController): ModelSettingsSaveResult;