chore: release v2.2.0

CHANGELOG.md

@@ -4,6 +4,43 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-07-30
+
+### Added
+
+- **desktop**: New Electron desktop client — typed IPC contract with execution reducer, Task Console and Settings renderer (React + Vite), main-process runtime bridge with settings store, IPC failure degraded states, accessibility semantics (ARIA live regions, focus-visible, reduced-motion), and electron-builder packaging that publishes multi-platform zip archives to GitHub Releases.
+- **cli/headless**: Non-interactive headless mode with a JSON output contract — validated `--output`, artifacts and security denials exposed in the payload, stdout writes intercepted during JSON runs, and top-level error classification.
+- **core/session**: Session resume — full step schema, order-independent resume unlock, cross-step file context hydration, and session records validated against a schema on load.
+- **runtime/hooks**: Lifecycle hooks — project hooks gated behind explicit opt-in, hardened hook plumbing, per-tool outcome observation in postToolUse, and log-callback failures isolated from hook policy decisions.
+- **security/permissions**: Declarative permission rules with in-session derived allow rules (literal wildcards escaped; bare tool rules never derived from always-allow approvals).
+- **core/context**: Context zone budgets — final serialized prompt budgeted including the fallback path, with guaranteed budget postconditions and a single compaction summary.
+- **core/instructions**: AGENTS.md project instruction loading with byte-capped instruction file reads.
+- **mcp-web-fetch**: New `@frontagent/mcp-web-fetch` adapter package, wired into the agent registry and planner.
+- **prompts**: Codegen and planner prompt disciplines — external knowledge injection, security-engineering and code-minimalism disciplines, and a security review dimension in the code-quality sub-agent.
+- **benchmarks/eval**: Reproducible SDD ablation evaluation — frozen 30-task set with a typecheck-clean fixture project, two-arm orchestrator with resume support, machine-checkable acceptance, and a published results report with reproduction guide.
+- **docs**: Verifiable npm downloads counter in the README with daily refresh; desktop client documentation.
+
+### Fixed
+
+- **cli**: Global bin invocations (`fa` via npm/pnpm/homebrew symlinks) no longer exit silently — the direct-entry guard resolves the symlinked argv path before comparing module URLs. (#396)
+- **guard**: `hallucinationGuard.checks` is honored on the executor validation path (`validateFilePath` / `validateCode`), while project-root containment stays enforced even when `fileExistence` is disabled. (#386)
+- **core/llm**: Migrated to the AI SDK v5 line (clears GHSA-rwvc-j5jr-mgvh) and pinned the OpenAI provider to Chat Completions for OpenAI-compatible base URLs.
+- **planner**: `web_fetch` actions are preserved in generated plans.
+- **agent**: Dependency recovery uses the project's package manager.
+- **desktop**: Default-workspace setting takes effect, telemetry log only auto-scrolls at the bottom, demo content removed from TaskComposer initial values, successful settings saves announced to assistive tech.
+- **runtime-node**: Session ids constrained to the sessions directory with atomic writes; real taskId carried on failed taskComplete hooks; win32 process-tree kill.
+- **workflow**: Workflow-rules gate accepts the vars-based self-hosted Repo Guard runner, keeping pre-commit/pre-push hooks green on clean checkouts. (#397)
+
+### Changed
+
+- **ci**: Repo Guard runs on a self-hosted Claude Code engine with allowlisted fork PR actors via `pull_request_target`; catch-all CODEOWNERS rule requires owner review on every PR; OpenRouter provider order passed through to Repo Guard.
+- **deps**: ts-morph upgraded to ^28; AI SDK moved to the v5 line.
+
+### Tests
+
+- CLI entry-guard symlink coverage; guard switch-independence and containment-under-disabled coverage; discriminating executor read_file coverage.
+- Runtime run orchestration and shutdown ordering; two-phase plan generation; step callback contracts; executor skills; semantic boundary detection across languages.
+
 ## [2.1.1] - 2026-06-09
 
 ### Changed

README.md

@@ -52,12 +52,12 @@ Use FrontAgent when you need a frontend AI agent that can:
 
 ## Current Release Snapshot
 
-The repository is currently aligned on `frontagent@2.1.1` for both the npm CLI package and the VS Code extension.
+The repository is currently aligned on `frontagent@2.2.0` for both the npm CLI package and the VS Code extension.
 
 - Runtime requirements: Node.js `>=20.0.0`; VS Code extension engine `^1.120.0`.
-- Build output: `pnpm build` builds the monorepo, bundles the CLI, syncs the VS Code version, and packages `apps/vscode/frontagent-2.1.1.vsix`.
+- Build output: `pnpm build` builds the monorepo, bundles the CLI, syncs the VS Code version, and packages `apps/vscode/frontagent-2.2.0.vsix`.
 - Quality gates: `pnpm quality:predev`, `pnpm quality:precommit`, `pnpm quality:ci`, and `pnpm quality:local` combine contract checks, linting, typechecking, tests, workflow tests, and build verification.
-- v2.1.1 focus: smaller agent/executor/context/Filesense/memory/runtime/webview modules, hardened VS Code webview nonce generation, restored GitNexus contract checks, and expanded focused tests.
+- v2.2.0 focus: the Electron desktop client, headless non-interactive CLI mode, session resume, lifecycle hooks, declarative permission rules, context zone budgets, the mcp-web-fetch adapter, and CLI/guard correctness fixes.
 
 ## Three Ways to Use FrontAgent
 

apps/desktop/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontagent/desktop",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "FrontAgent desktop app (Electron) — standalone GUI entry point reusing the Node runtime spine",
   "private": true,
   "author": "FrontAgent",

apps/vscode/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2.2.0
+
+- Aligned the extension package with the FrontAgent `2.2.0` release.
+- Bundled runtime migrated to the AI SDK v5 line; the OpenAI provider now explicitly targets the Chat Completions endpoint for OpenAI-compatible base URLs.
+- Inherited the guard, planner, session-resume, and lifecycle-hook fixes from the 2.2.0 core packages.
+- Kept the minimum VS Code engine requirement at `^1.120.0`.
+- Build output now packages the `frontagent-2.2.0.vsix` artifact through the root `pnpm build` script.
+
 ## 2.1.1
 
 - Aligned the extension package with the FrontAgent `2.1.1` release.

apps/vscode/package.json

@@ -2,7 +2,7 @@
   "name": "frontagent",
   "displayName": "FrontAgent",
   "description": "Chat with FrontAgent from a VS Code sidebar.",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "publisher": "ceilf6",
   "icon": "media/icon.png",
   "license": "MIT",

docs/CHANGELOG-CN.md

@@ -4,6 +4,40 @@
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-07-30
+
+### 新增
+- **desktop**：全新 Electron 桌面客户端——类型化 IPC 契约与执行 reducer、Task Console 与设置面板（React + Vite）、主进程 runtime bridge 与设置存储、IPC 故障降级态、无障碍语义（ARIA live region、focus-visible、reduced-motion），并通过 electron-builder 打包多平台 zip 附到 GitHub Releases。
+- **cli/headless**：非交互 headless 模式与 JSON 输出契约——校验 `--output`、payload 暴露 artifacts 与安全拒绝记录、JSON 运行期间拦截 stdout 直写、顶层错误分类。
+- **core/session**：会话恢复——完整 step schema、顺序无关的恢复解锁、跨步骤文件上下文水合、加载时按 schema 校验会话记录。
+- **runtime/hooks**：生命周期 hooks——项目 hooks 显式 opt-in、加固 hook 管线、postToolUse 观测每个工具结果、日志回调故障与 hook 策略决策隔离。
+- **security/permissions**：声明式权限规则与会话内派生 allow 规则（转义字面通配符；always-allow 审批不再派生裸工具规则）。
+- **core/context**：上下文分区预算——最终序列化 prompt 全路径预算化（含 fallback），保证预算后置条件与单次压缩摘要。
+- **core/instructions**：AGENTS.md 项目指令加载，指令文件读取受字节上限约束。
+- **mcp-web-fetch**：新增 `@frontagent/mcp-web-fetch` 适配包并接入 agent registry 与 planner。
+- **prompts**：codegen 与 planner 注入外部知识、安全工程与代码极简纪律；code-quality 子代理新增安全评审维度。
+- **benchmarks/eval**：可复现的 SDD 消融评测——冻结 30 任务集、typecheck-clean fixture 工程、双臂编排器（支持断点续跑）、机器可校验验收，附结果报告与复现指南。
+- **docs**：README 可验证 npm 下载量计数（每日刷新）；桌面客户端文档。
+
+### 修复
+- **cli**：全局安装的 `fa`（npm/pnpm/homebrew symlink bin）不再静默退出——入口守卫比较前先解析 argv 的 symlink 真实路径。（#396）
+- **guard**：executor 校验路径（`validateFilePath` / `validateCode`）现在尊重 `hallucinationGuard.checks` 配置；禁用 `fileExistence` 时项目根目录包含性安全边界仍然生效。（#386）
+- **core/llm**：迁移至 AI SDK v5（清除 GHSA-rwvc-j5jr-mgvh），OpenAI provider 对 OpenAI 兼容 baseURL 显式固定 Chat Completions 端点。
+- **planner**：生成计划时保留 `web_fetch` 动作。
+- **agent**：依赖恢复使用项目自身的包管理器。
+- **desktop**：默认工作区设置生效、telemetry 日志仅在底部时自动滚动、移除 TaskComposer 演示内容、设置保存成功向辅助技术播报。
+- **runtime-node**：会话 id 约束在 sessions 目录内并原子写入；失败的 taskComplete hooks 携带真实 taskId；win32 进程树终止。
+- **workflow**：workflow-rules 门禁兼容 vars 形式的自托管 Repo Guard runner，干净检出下 pre-commit/pre-push 钩子恢复绿色。（#397）
+
+### 变更
+- **ci**：Repo Guard 迁移至自托管 Claude Code 引擎，`pull_request_target` + fork PR 触发者白名单；catch-all CODEOWNERS 规则要求所有 PR 经 owner 评审；OpenRouter provider 顺序透传至 Repo Guard。
+- **deps**：ts-morph 升级至 ^28；AI SDK 迁移至 v5 线。
+
+### 测试
+- CLI 入口守卫 symlink 覆盖；guard 开关独立性与禁用态包含性覆盖；executor read_file 判别性用例。
+- runtime 编排与关停顺序、两阶段计划生成、step 回调契约、executor skills、跨语言语义边界检测。
+
+
 ## [2.1.1] - 2026-06-09
 
 ### 变更

docs/README-CN.md

@@ -51,12 +51,12 @@ FrontAgent 是一个开源前端 AI 编程 Agent，面向真实前端工程场
 
 ## 当前发布快照
 
-当前仓库的 npm CLI 包与 VS Code 插件均对齐到 `frontagent@2.1.1`。
+当前仓库的 npm CLI 包与 VS Code 插件均对齐到 `frontagent@2.2.0`。
 
 - 运行时要求：Node.js `>=20.0.0`；VS Code 插件 engine 为 `^1.120.0`。
-- 构建产物：`pnpm build` 会构建 monorepo、打包 CLI、同步 VS Code 版本，并生成 `apps/vscode/frontagent-2.1.1.vsix`。
+- 构建产物：`pnpm build` 会构建 monorepo、打包 CLI、同步 VS Code 版本，并生成 `apps/vscode/frontagent-2.2.0.vsix`。
 - 质量门禁：`pnpm quality:predev`、`pnpm quality:precommit`、`pnpm quality:ci` 和 `pnpm quality:local` 会组合执行 contract 检查、lint、typecheck、测试、workflow 测试与构建验证。
-- v2.1.1 重点：拆小 agent/executor/context/Filesense/memory/runtime/webview 模块，加固 VS Code webview nonce 生成，恢复 GitNexus contract checks，并扩展 focused tests。
+- v2.2.0 重点：Electron 桌面客户端、headless 非交互 CLI、会话恢复、生命周期 hooks、声明式权限规则、上下文分区预算、mcp-web-fetch 适配包，以及 CLI/guard 正确性修复。
 
 ## 三种使用方式
 

docs/releases/v2.2.0.md

@@ -0,0 +1,58 @@
+# FrontAgent v2.2.0
+
+FrontAgent v2.2.0 is a minor release after v2.1.1. It ships the new Electron desktop client, headless non-interactive CLI mode, session resume, lifecycle hooks, declarative permission rules, context zone budgets, the `@frontagent/mcp-web-fetch` adapter, a reproducible SDD ablation evaluation framework, and a set of correctness and security fixes across the CLI entry path, the hallucination guard, and the LLM provider layer.
+
+## Highlights
+
+- New Electron desktop client with a typed IPC contract, Task Console + Settings UI, accessibility semantics, and multi-platform zip archives attached to GitHub Releases.
+- Headless non-interactive CLI mode with a validated JSON output contract exposing artifacts and security denials.
+- Session resume with schema-validated session records and cross-step file context hydration.
+- Lifecycle hooks with explicit project-hook opt-in and hardened hook plumbing.
+- Declarative permission rules and context zone budgets on the core execution path.
+- Reproducible SDD ablation benchmark: frozen 30-task set, two-arm orchestrator, machine-checkable acceptance, published negative findings with reproduction guide.
+- Global `fa` bin invocations work again (symlinked entry-path fix), and `hallucinationGuard.checks` is genuinely honored on the executor path without weakening the project-root security boundary.
+
+## Added
+
+- **Desktop client**: typed IPC contract + execution reducer, Task Console and Settings renderer (React + Vite), main-process runtime bridge + settings store, IPC-failure degraded states, ARIA live regions and navigation semantics, electron-builder packaging publishing multi-platform zips to GitHub Releases, and desktop documentation.
+- **Headless CLI**: `--output` validation, artifacts and security denials in the JSON payload, stdout interception during JSON runs, top-level error classification.
+- **Session resume**: full step schema, order-independent resume unlock, cross-step file context hydration, session records validated on load.
+- **Lifecycle hooks**: explicit opt-in for project hooks, per-tool outcome observation in postToolUse, log-callback failure isolation.
+- **Permissions**: declarative permission rules; in-session derived allow rules with literal-wildcard escaping; bare tool rules never derived from always-allow approvals.
+- **Context**: zone budgets with guaranteed postconditions and a single compaction summary; AGENTS.md project instructions with byte-capped reads.
+- **MCP**: `@frontagent/mcp-web-fetch` adapter package wired into the agent registry and planner.
+- **Prompts**: external-knowledge, security-engineering, and code-minimalism disciplines in codegen/planner; security review dimension in the code-quality sub-agent.
+- **Evaluation**: frozen 30-task ablation set, typecheck-clean fixture project, two-arm orchestrator with resume, acceptance check runner, results report and reproduction guide.
+- **Docs**: verifiable npm downloads counter with daily refresh.
+
+## Fixed
+
+- **CLI entry**: global bin symlinks (`fa` via npm/pnpm/homebrew) no longer exit silently; the direct-entry guard resolves the symlinked argv path. (#396)
+- **Hallucination guard**: `hallucinationGuard.checks` is honored by `validateFilePath` / `validateCode` on the executor path; project-root containment remains enforced when `fileExistence` is disabled. (#386)
+- **LLM provider**: AI SDK migrated to the v5 line (clears GHSA-rwvc-j5jr-mgvh); OpenAI provider pinned to Chat Completions for OpenAI-compatible base URLs.
+- **Planner**: `web_fetch` actions preserved in generated plans.
+- **Agent**: dependency recovery uses the project package manager.
+- **Desktop**: default-workspace setting takes effect; telemetry auto-scroll only at bottom; no demo content in TaskComposer; settings saves announced to assistive tech.
+- **Runtime**: session ids constrained to the sessions dir with atomic writes; real taskId on failed taskComplete hooks; win32 process-tree kill.
+- **Workflow gates**: workflow-rules test accepts the vars-based self-hosted Repo Guard runner. (#397)
+
+## Changed
+
+- **CI**: Repo Guard on a self-hosted Claude Code engine with allowlisted fork actors under `pull_request_target`; catch-all CODEOWNERS; OpenRouter provider order passthrough.
+- **Dependencies**: ts-morph ^28; AI SDK v5 line.
+
+## Known Issues
+
+- `hallucinationGuard.enabled` is still dead config on the agent path; only `checks` is consulted. Tracked in #400.
+
+## Verification
+
+- `pnpm quality:precommit` (lint, typecheck, workspace tests, workflow rules) green at release.
+- CLI symlink invocation verified against the packaged bundle (`fa --version` via a bin symlink).
+
+## Compatibility
+
+- CLI package version: `frontagent@2.2.0`.
+- VS Code extension version: `frontagent@2.2.0`.
+- Node.js requirement: `>=20.0.0`.
+- VS Code requirement: `^1.120.0`.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "frontagent",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "FrontAgent CLI and VS Code extension for frontend AI engineering with SDD constraints, MCP-controlled execution, and RAG planning",
   "type": "module",
   "bin": {

packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontagent/core",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "FrontAgent 核心 - Agent 编排、规划、执行",
   "type": "module",
   "main": "./dist/index.js",

packages/hallucination-guard/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontagent/hallucination-guard",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "幻觉防控模块 - Agent 输出校验与事实核查",
   "type": "module",
   "main": "./dist/index.js",

packages/mcp-file/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontagent/mcp-file",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "MCP File Adapter - 文件操作 MCP Server",
   "type": "module",
   "main": "./dist/index.js",

packages/mcp-filesense/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontagent/mcp-filesense",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "MCP Filesense Adapter - Agent-friendly directory indexing for FrontAgent",
   "type": "module",
   "main": "./dist/index.js",

packages/mcp-memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontagent/mcp-memory",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "MCP Memory Adapter - remote knowledge sync and RAG query",
   "type": "module",
   "main": "./dist/index.js",

packages/mcp-shell/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontagent/mcp-shell",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

packages/mcp-web-fetch/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontagent/mcp-web-fetch",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "MCP Web-Fetch Adapter - Agent-friendly URL fetching (HTML→text) with SSRF guards for FrontAgent",
   "type": "module",
   "main": "./dist/index.js",

packages/mcp-web-fetch/src/engine.ts

@@ -38,7 +38,7 @@ export const HARD_MAX_TIMEOUT_MS = 60_000;
 export const HARD_MAX_BYTES = 5_000_000;
 const DEFAULT_MAX_REDIRECTS = 5;
 const HARD_MAX_REDIRECTS = 10;
-const DEFAULT_USER_AGENT = 'frontagent-mcp-web-fetch/2.1.1 (+https://github.com/frontagent)';
+const DEFAULT_USER_AGENT = 'frontagent-mcp-web-fetch/2.2.0 (+https://github.com/frontagent)';
 
 /**
  * Clamps a caller-supplied numeric limit to a safe, bounded integer.

packages/mcp-web-fetch/src/types.ts

@@ -2,7 +2,7 @@ import type { FetchResult } from './engine.js';
 
 export type { FetchOptions, FetchResult } from './engine.js';
 
-export const VERSION = '2.1.1';
+export const VERSION = '2.2.0';
 
 export interface WebFetchToolResult {
   success: boolean;

packages/mcp-web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontagent/mcp-web",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "MCP Web Adapter - 浏览器感知与交互 MCP Server",
   "type": "module",
   "main": "./dist/index.js",

packages/runtime-node/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontagent/runtime-node",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "Node runtime adapter for FrontAgent CLI and VSCode extension",
   "type": "module",
   "main": "./dist/index.js",

packages/sdd/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontagent/sdd",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "description": "SDD (Specification Driven Development) 控制层 - Agent 行为约束引擎",
   "type": "module",
   "main": "./dist/index.js",

packages/shared/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontagent/shared",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",