flavor-code 1.4.2 → 1.4.3

package/README.md

@@ -40,6 +40,7 @@ Flavor Code connects to OpenAI, Anthropic, or compatible services and works with
 | 🔎 | **Code graph navigation** | A local AST code-graph index (`.flavor/astgraph/`) powers `ast_search`/`ast_callers`/`ast_impact` queries for precise symbol lookup and reachability tracing; `/explain` turns that graph plus git history into newcomer-oriented walkthroughs |
 | 🌿 | **Git-native workflows** | `/commit` drafts a Conventional-Commits message for staged changes and commits after confirmation; `/review` audits uncommitted changes; the read-only `GitHistory` tool explains when and why code changed |
 | 🎨 | **E2E requirement-to-delivery** | From a rough requirement or a design export to a delivered product: PRD, interactive prototype, visual implementation, API integration, autonomous acceptance, and scored delivery (Electron only) |
+| 🌐 | **Agent-driven built-in browser** | The Electron desktop embeds an interactive browser: the agent navigates pages and acts on elements by snapshot reference with `BrowserSnapshot`/`BrowserAct` and friends, every action is annotated in real time via a visual overlay, navigation is guarded against SSRF, and snapshots redact passwords, tokens, and other sensitive fields (Electron only) |
 | 🔁 | **Bounded self-improvement** | Repeated tool failures are captured, deduped, and proposed as suggestions; fixes ship as sandbox-verified plugins or as learned guardrail rules injected into future prompts, with run trends and rule management (`/evolve`) |
 | 🛡️ | **Clear permission boundaries** | Independent control over read, write, Shell, network, and destructive actions; Docker supported |
 
@@ -61,6 +62,8 @@ cd your-project
 flavor
 ```
 
+When you leave the session, the CLI prints the exact command for picking it back up (`flavor --resume <sessionId>`).
+
 **3. Initialize project context**
 
 Run `/init` the first time you enter a project. Flavor analyzes the language, package manager, source directories, and verification commands, then generates a `FLAVOR.md` project guide.
@@ -144,6 +147,28 @@ OpenAI-protocol providers default `thinkingEffort` to `high`. Supported values a
 
 Runtime behavior and configuration conventions for OAuth PKCE are described in the [PKCE spec](./docs/specs/pkce-runtime-config.md). The [config schema](./src/config/schema.ts) is the source of truth for all fields.
 
+### Global coding instructions
+
+Coding rules shared across projects are stored in `~/.flavor-code/GLOBAL.md`. You can edit the file manually or use explicit commands to manage single-line Markdown list items. Flavor Code never extracts or writes global rules automatically from conversation. The limit is 64 KiB. Main agents, subagents, and loop workers receive the rules. Edits or deletion are read before the next model call and appended to the current conversation without rewriting its existing prompt-cache prefix.
+
+```text
+/global                         show the path and all rules
+/global remember Keep tests focused  add one rule
+/global forget Keep tests focused    remove one matching list item
+```
+
+`forget` tries an exact text match first, then a unique partial match. It refuses ambiguous matches and preserves other hand-written Markdown.
+
+This feature is enabled by default. Disable it in global or project `flavor.json`:
+
+```json
+{
+  "globalInstructions": { "enabled": false }
+}
+```
+
+When disabled, `GLOBAL.md` is neither read nor injected, and `/global` cannot write it. The default local Shell and terminal still run with the current user's filesystem permissions; use an isolated execution environment if agent-run commands must be unable to modify this file.
+
 ## Entry Points
 
 | Entry point | Best for | How to start |
@@ -181,6 +206,9 @@ Common commands:
 | `/audit` | View tool failure audits |
 
 You can submit steering or queue follow-ups while a run is in progress; once the current model response finishes, the task picks up new instructions at safe boundaries.
+While a run is active, Enter queues the text for the next turn; `/steer <message>` changes the current turn. Type `/queue` to inspect all queued messages, use Up/Down to select one, Enter to move it back to the draft, or `d` to cancel it. Escape closes the queue; outside that view it restores the latest queued message for editing.
+
+When reading older output, a status line indicates if new output has arrived. Press End to return to the latest output, Home to jump to the top, or Ctrl+Up/Down to move between visible turns. Approval and question views keep their action keys visible while their details scroll with PageUp/PageDown or the mouse wheel.
 
 During planned work, a wide CLI shows the main task plan and sub-agent exploration side by side; if only one track exists it uses the full row, and narrow terminals stack both tracks. Long streamed responses keep a live `Writing response` activity below the latest output. LSP tools locate the nearest nested project configuration for each target file, so monorepos and sandbox/worktree projects do not need a `tsconfig.json` or `jsconfig.json` at the Flavor workspace root; JavaScript and CommonJS files are supported by the bundled TypeScript server as well.
 
@@ -214,6 +242,30 @@ Useful commands:
 
 `/co-work` first places both agents in planning and waits for both to accept the same hashed plan and declare READY. Early READY intents are retained, and only the broker's exactly-once START event opens parallel execution. Each agent works only in its own project, receives only its assigned tasks, and reports bounded completion evidence. The broker-selected integration owner verifies all assertions and emits END or FAIL through `CoWorkIntegrate`. Communication uses authenticated, bounded local IPC with no TCP listener; peer input cannot approve tools or access the other workspace. UUID/alias routing and the protocol already support a third active client; durable artifact exchange, broker-restart journaling/recovery, and large-group coordination are later hardening work. See the [CLI pals specification](./docs/specs/2026-08-14-cli-pals-cowork.md).
 
+#### Session, config, and usage management CLI
+
+Non-interactive management commands for scripts, CI, and retrospectives. Like `flavor memory` / `flavor mcp`, these are lightweight entry points that never start the agent runtime, so they cold-start quickly; reading and writing sessions and configuration reuse the same store and schema validation as the interactive mode.
+
+```bash
+# sessions: list / inspect / export / delete
+flavor sessions list                       # saved sessions for this project (newest first)
+flavor sessions show [session-id]          # summarize one session; omit id for the latest
+flavor sessions export <id> --format md --output log.md   # export a transcript (md / json)
+flavor sessions delete <id>                # delete one session
+
+# config: read the effective value, write the project config
+flavor config get context.windowTokens     # read by dot path; secrets are redacted
+flavor config set permissionMode plan      # validated against the merged config before writing; invalid values are not persisted
+flavor config unset language               # remove one key from the project config
+flavor config list --json                  # print the effective (redacted) config
+
+# usage: summarize token and cache usage for the current session
+flavor usage                               # human-readable cache-hit table
+flavor usage --json                        # machine-readable summary
+```
+
+`flavor sessions list/show`, `flavor config list/get`, and `flavor usage` all accept `--json` for scripted consumption.
+
 ### Electron Desktop
 
 ```bash
@@ -302,7 +354,7 @@ Long-term memory distinguishes user preferences, behavioral feedback, project co
 
 Image prompts support PNG, JPEG, and WebP, with a 5 MiB per-image maximum and up to 5 images per prompt. The desktop app supports picking or drag-and-drop; CLI clipboard images currently work on Windows and macOS. Standard CLI paste prefers clipboard text and creates an image attachment only when no usable text flavor is available; use `/paste-image` when both flavors exist and the image is intended.
 
-CLI tool receipts are collapsed by default. Press `Ctrl+O` on Windows, Linux, or macOS to expand or collapse tool output globally. This shortcut affects tool output only; user prompts and assistant replies keep the same conversation window. On macOS, `Command+O` remains available to the terminal or host application.
+CLI tool receipts are collapsed by default, and long sessions keep only a viewport-sized window of turns and output items. Press `Ctrl+O` on Windows, Linux, or macOS to expand everything: the render budget is lifted so earlier turns, hidden output items, and full tool details all become visible, with no text truncation. Press it again to return to the compact, responsive view. On macOS, `Command+O` remains available to the terminal or host application.
 
 ## Permissions & Sandbox
 

package/README.zh-CN.md

@@ -40,6 +40,7 @@ Flavor Code 接入 OpenAI、Anthropic 或兼容服务，在受控工作区内使
 | 🔎 | **代码图导航** | 本地 AST 代码图索引（`.flavor/astgraph/`），通过 `ast_search`/`ast_callers`/`ast_impact` 等查询精确定位符号、追踪可达性；`/explain` 结合代码图与 Git 历史，向新人讲解一个符号 |
 | 🌿 | **Git 原生工作流** | `/commit` 为暂存改动生成 Conventional Commits 提交信息并确认提交；`/review` 审查未提交改动；只读 `GitHistory` 工具回答“这段代码为什么是这样” |
 | 🎨 | **E2E 需求到交付** | 从粗需求或设计稿到可交付产品：PRD、交互原型、视觉还原、接口联调、自主验收与评分交付（仅 Electron） |
+| 🌐 | **Agent 内置浏览器** | Electron 桌面端内置可交互浏览器：Agent 通过 `BrowserSnapshot`/`BrowserAct` 等工具导航页面、按元素引用点击与输入，操作以可视化覆盖层实时标注；导航受 SSRF 防护约束，快照自动脱敏密码、token 等敏感字段（仅 Electron） |
 | 🔁 | **有界自进化** | 重复的工具失败被捕获、去重并形成建议；修复以沙箱验证过的插件形式落地，或沉淀为注入后续提示词的 guardrail 规则，并支持运行趋势与规则管理（`/evolve`） |
 | 🛡️ | **明确的权限边界** | 分别控制读、写、Shell、网络和破坏性操作，也可使用 Docker |
 
@@ -61,6 +62,8 @@ cd your-project
 flavor
 ```
 
+退出会话时，CLI 会打印接着上次的恢复命令（`flavor --resume <sessionId>`）。
+
 **3. 初始化项目上下文**
 
 首次进入项目后运行 `/init`。Flavor 会分析语言、包管理器、源码目录和验证命令，并生成 `FLAVOR.md` 项目指南。
@@ -144,6 +147,28 @@ OpenAI 协议 Provider 的 `thinkingEffort` 默认值为 `high`，支持 `minima
 
 OAuth PKCE 的运行时行为与配置约定见 [PKCE 规范](./docs/specs/pkce-runtime-config.md)。完整配置字段以 [配置 Schema](./src/config/schema.ts) 为准。
 
+### 全局编程规范
+
+跨项目编程规范存放在 `~/.flavor-code/GLOBAL.md`。可以手动编辑文件，也可以使用明确的命令管理单行 Markdown 列表项；Flavor Code 不会从对话自动提取或写入全局规范。文件大小上限为 64 KiB。主 Agent、子 Agent 和 loop worker 都会收到这些规范。编辑或删除文件后，下一次模型调用会读取新内容，并把变更追加到当前会话，不改写已有的 prompt cache 前缀。
+
+```text
+/global                         显示文件路径和全部规范
+/global remember 保持测试聚焦    添加一条规范
+/global forget 保持测试聚焦      删除唯一匹配的列表项
+```
+
+`forget` 优先按完整文本匹配，其次按唯一的部分文本匹配；匹配到多条时不会删除。文件中的其他手写 Markdown 会保留。
+
+默认启用。可在全局或项目 `flavor.json` 中关闭：
+
+```json
+{
+  "globalInstructions": { "enabled": false }
+}
+```
+
+关闭时不会读取或注入 `GLOBAL.md`，`/global` 修改命令也不会写入。默认本地 Shell 和终端仍以当前用户权限运行；若需要阻止 Agent 执行的命令修改该文件，需另行使用隔离执行环境。
+
 ## 使用入口
 
 | 入口 | 适合场景 | 启动方式 |
@@ -181,6 +206,9 @@ OAuth PKCE 的运行时行为与配置约定见 [PKCE 规范](./docs/specs/pkce-
 | `/audit` | 查看工具失败审计 |
 
 运行中可以提交 steering 或排队 follow-up；当前模型响应结束后，任务会在安全边界处接收新指令。
+运行中按 Enter 会把输入排到下一轮；输入 `/steer <内容>` 会影响当前回合。输入 `/queue` 可查看全部待发送消息，用上下键选中，按 Enter 移回输入框编辑，或按 `d` 取消。Esc 关闭队列视图；在普通输入界面则会取回最后一条待发送消息供编辑。
+
+查看较早输出时，状态栏会提示是否有新内容。按 End 回到最新输出，Home 跳到顶部，Ctrl+上下键在当前可见的回合间跳转。审批和提问界面的操作键固定显示，详情可用 PageUp/PageDown 或鼠标滚轮翻阅。
 
 有任务规划时，宽终端会把主任务计划与子 Agent 探索左右并排展示；只有一类工作时占满整行，窄终端则自动纵向排列。长内容流式输出期间，最新内容下方会持续显示 `Writing response` 动作。LSP 工具会从目标文件向上寻找最近的嵌套项目配置，因此 monorepo、sandbox 或 worktree 项目无需在 Flavor 工作区根部额外放置 `tsconfig.json` / `jsconfig.json`；内置 TypeScript 服务也支持 JavaScript 与 CommonJS 文件。
 
@@ -214,6 +242,30 @@ flavor --pal-name B
 
 `/co-work` 会先让双方进入规划，等待双方接受同一个哈希计划并声明 READY；较早的 READY 意图会被保留，只有 broker 恰好一次的 START 事件才会放行并行执行。每个 Agent 只在自己的项目内工作，只接收分配给自己的任务，并提交有界的完成证据。broker 指定的集成负责人会检查所有断言，再通过 `CoWorkIntegrate` 广播 END 或 FAIL。通信使用经过认证、有大小上限的本机 IPC，不开放 TCP 监听；peer 输入不能代替本机工具审批，也不能访问另一工作区。UUID/别名路由和协议已能支持第三个活动实例；持久化成果物交换、broker 重启日志与恢复、大规模多方协调属于后续强化。详见 [CLI Pals 规范](./docs/specs/2026-08-14-cli-pals-cowork.md)。
 
+#### 会话、配置与用量管理 CLI
+
+面向脚本、CI 和复盘的非交互管理命令，与 `flavor memory` / `flavor mcp` 同属轻量入口，不会启动 Agent 运行时，因此冷启动很快；读写会话与配置复用交互模式相同的存储与 Schema 校验：
+
+```bash
+# 会话：列出 / 查看 / 导出 / 删除
+flavor sessions list                       # 列出当前项目的历史会话（最新在前）
+flavor sessions show [session-id]          # 查看一次会话摘要，省略 id 取最新
+flavor sessions export <id> --format md --output log.md   # 导出会话记录（md / json）
+flavor sessions delete <id>                # 删除一条会话
+
+# 配置：读取生效值、写入项目配置
+flavor config get context.windowTokens     # 按点路径读取，密钥自动脱敏
+flavor config set permissionMode plan      # 写入前先按合并结果校验，非法值不落盘
+flavor config unset language               # 从项目配置移除某一项
+flavor config list --json                  # 打印合并后的生效配置（脱敏）
+
+# 用量：汇总当前会话的 token 与缓存命中
+flavor usage                               # 人类可读的缓存命中表
+flavor usage --json                        # 机器可读的用量摘要
+```
+
+`flavor sessions list/show`、`flavor config list/get`、`flavor usage` 均支持 `--json` 以便脚本消费。
+
 ### Electron 桌面端
 
 ```bash
@@ -302,7 +354,7 @@ Skill 是带有 YAML 头信息的 `SKILL.md`，放在 `.flavor/skills/<name>/`
 
 图片提示支持 PNG、JPEG 和 WebP，单图最大 5 MiB、每次最多 5 张。桌面端支持选择或拖放；CLI 剪贴板图片目前支持 Windows 和 macOS。CLI 标准粘贴会优先使用剪贴板文字，只有没有可用文字时才把剪贴板图像添加为附件；剪贴板同时含有文字和图片但需要图片时，使用 `/paste-image`。
 
-CLI 工具回执默认折叠。在 Windows、Linux 和 macOS 上均使用 `Ctrl+O` 全局展开或收起工具输出；该快捷键只影响工具输出，用户输入和助手回复的对话窗口不会随之变化。macOS 的 `Command+O` 继续保留给终端或宿主应用。
+CLI 工具回执默认折叠，长会话只保留与终端视口成比例的回合与输出项窗口。在 Windows、Linux 和 macOS 上均使用 `Ctrl+O` 展开：渲染上限随之解除，更早的回合、被隐藏的输出项与完整工具明细都会显示，文本也不再截断；再按一次回到紧凑的响应式视图。macOS 的 `Command+O` 继续保留给终端或宿主应用。
 
 ## 权限与沙箱
 

package/dist/agent/loop.d.ts

@@ -29,6 +29,7 @@ export interface AgentLoopOptions {
     extendIterations?: number;
     maxExtensions?: number;
     hasActiveProgress?(): boolean;
+    beforeModelCall?(signal?: AbortSignal): Promise<void>;
     agent?: "main" | "subagent";
     ownerId?: string;
     hallucinationGuard?: HallucinationGuard;