@ai-agent-forge/agent-forge 0.88.1 → 0.88.2

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 ## [Unreleased]
 
+## [0.88.2] - 2026-10-05
+
+### Added
+
+- Plugin on-demand activation (插件按需挂载与能力手册设计): capability manifests may declare `activation: "on-demand"`, a one-line `description`, and an optional `manual` path. On-demand plugins register their tools but keep them out of the initial active surface; the system prompt carries a mountable-capabilities card per still-deferred plugin, and the new built-in `capability_mount` tool activates the full tool set (next request) and returns the plugin's AI manual, while `capability_unmount` removes only the schema (runtime state follows the plugin's own idle timeout; session teardown clears all mounts). The framework never unmounts automatically — default `activation` stays `always`, so existing and third-party plugins are unaffected (user ruling 2026-10-05 "临时/常驻分级、渐进式按需加载"). First batch on-demand (7): browser-playwright, the four desktop plugins, subagent-delegate, and image-generation — each ships an AI `MANUAL.md` and joins the package `files` whitelist. Deployment semantics: activation reads the install-store copy, so manifest changes require a `plugin install` re-run. Known defect (logged, workaround verified): local-directory installs package the tree inconsistently and may include `tsconfig.json`, whose repo-relative `extends` breaks jiti loading in the store; installing the `npm pack` tarball (files whitelist) is clean. Covered by `test/capability-mount.test.ts` and verified against a real grok-4.7 session: the model mounted the capability itself before any browser call, and a non-browser session sent zero browser tool schemas.
+
+### Fixed
+
+- desktop-windows-input: key and no-target type actions now post through the real keyboard queue (`keybd_event`): named keys and Ctrl/Alt/Shift combinations go as virtual-key events, no-target `type` is typed as VK_PACKET unicode events addressed at the current focus. Previously `key` sent WM_CHAR window messages to the target window (so `Enter` typed the letters R-E-T-U-R-N) and `WScript.SendKeys` handled the rest; neither reaches UIA-invisible surfaces. The native file-picker flow (coordinate click to open the dialog → foreground type the path → Enter) was verified end-to-end against a real Chrome dialog, which UIA cannot enumerate at all (both TreeWalker and FindAll top-level scans miss it; Win32 EnumWindows sees it).
+- Custom `--session-id` values (non-UUID short ids like `mount-test-13`) could not delegate subagents: the subagent mailbox and session-lineage addressing gate rejected any id outside the UUID/`st:` shapes, so the whole delegation failed with "mailbox owner id is not a session id" (macCRM dogfood 2026-10-05, the model itself traced the cause to `session-lineage.ts`). Addressing safety only requires a single path-safe segment; `isAgentSessionId` now also accepts `[A-Za-z0-9][A-Za-z0-9._-]*` except `.`/`..`, and the shape tests cover the custom-id family.
+- `--rebind-suite` now actually works on `--session` resume: the flag was collected in `main.ts` but dropped on the `createAgentSessionFromServices` hop, so the sdk suite-binding guard still rejected the resume (macCRM dogfood 2026-10-04, reproduced on Windows too). It is forwarded through `CreateAgentSessionFromServicesOptions` and covered by a regression test.
+- `plugin install` failures surface the installer's real message instead of the bare "The plugin installer operation failed" code (e.g. a missing `dist/entry.js` in the source directory now says so).
+- Suite `capabilities` declaring a bundled-channel plugin (e.g. `agent-forge.plugin.provider-failover`) no longer warn "has no installed active plugin": bundled plugins ship with the host and load without an install-store entry, and the warning now knows that.
+- browser-playwright: internal in-page scripts (performance collection, localStorage get/set/clear) are now passed to `page.evaluate` as function objects. Passing the equivalent `() => ...` arrow *string* is silently wrong on real Playwright — the string is evaluated as an expression, the resulting function object serializes to `undefined`, which crashed `browser_performance` with "Cannot read properties of undefined (reading 'paints')" and made the three `browser_storage` localStorage actions no-ops (macCRM dogfood 2026-10-05, verified against real Chromium). `browser_evaluate` docs now steer multi-statement logic to IIFE strings.
+- browser-playwright: `browser_setup` no longer crashes with "Cannot read properties of undefined (reading 'options')" — the capability extracted `runtime.setup` into a local before calling it, dropping `this` on the production class runtime (closure-shaped test mocks never read `this`, so 73 deterministic tests stayed green; first-install dogfood 2026-10-05). A class-shaped runtime regression test now pins the call path, and `browser_setup` was verified end-to-end on a fresh host: AI gets the structured guidance, self-installs Playwright + Chromium through `browser_setup`, and continues the page task in the same session.
+- browser-playwright: browser-binary lookup and install now share one directory. `browser_setup` installs Chromium into `<agentDir>/browser-deps/browsers` (isolated via `PLAYWRIGHT_BROWSERS_PATH`), but launch silently looked in the shared OS cache, so a fresh host with no cache failed with the install guidance even right after a successful setup. `connect()` now defaults `PLAYWRIGHT_BROWSERS_PATH` to the same isolated directory (never overriding an explicit user setting), and the manual-install guidance command pins the same path.
+- browser-playwright: `browser_drag` no longer times out on pages using `setPointerCapture` (the standard drag idiom): after `mouse.down` the tool now moves to the target by geometry (`boundingBox` + stepped `mouse.move`) instead of `locator.hover()`, whose hit-target check is defeated by pointer capture retargeting events to the source element. `browser_locator_action` `scroll` now parks the cursor over the target element before wheeling — the wheel delta used to land on whatever container the mouse happened to hover, so scrolling an explicit container silently scrolled something else. Found by a 43-assertion business-effect matrix against a purpose-built test page; both sequences are pinned in the mock tests.
+
+### Added
+
+- Visual baseline roles join the factory suite (factory contents revision 7,
+  2026-10-04 user ruling "术有专攻、角色隔离"): `design-proposer` and
+  `visual-reviewer` join the factory role seeds and the default
+  `associations.roles` of both builtin suites, so the design-proposal and
+  visual-review roles are visible out of the box (dispatch stays an explicit
+  `role` choice; role files are disk-only and seeds never overwrite user
+  edits). Workspaces provisioned at revision 6 receive the upgrade-proposal
+  diagnostic and adopt via `--suite-reset`. See
+  `docs/plans/视觉保底角色设计注记.md`.
+
+- macOS desktop plugin profiles and packages: three new builtin plugin profiles (`desktop-observe-macos`, `desktop-control-macos`, `desktop-qa-macos`) resolve the two new self-contained plugin packages `plugins/desktop-macos-observe` (`agent-forge.plugin.desktop-macos-observe`, read-only `desktop_probe`/`desktop_session_open`/`desktop_observe`/`desktop_reobserve`/`desktop_session_stop` over a JXA osascript Accessibility driver, source `macos-ax`) and `plugins/desktop-macos-input` (`agent-forge.plugin.desktop-macos-input`, bounded `desktop_execute` with click-only coordinate targets, no replay, shared `needs_user` gate). Both declare `platform.os: ["macos"]`, report fail-closed `unsupported` with probe reason `accessibility-permission-required` without an Accessibility grant, and stay separate profiles from the Windows desktop trio (a profile with an installed-but-platform-unavailable plugin is blocked wholesale by the resolver). Real darwin behavior is contract-tested with an injected fake `spawnSync`; on a real macOS host (app-mac-host, macOS 15.7.5, 2026-10-04) the deterministic suites pass, the driver's app location was fixed from by-name `Application('systemEvents')` to by-bundle-id `Application('com.apple.systemevents')` (by-name resolution fails under SSH launchd sessions), and the real-host cases now `ctx.skip(reason)` instead of silently passing when the probe reports unavailable. With `/usr/bin/osascript` granted Accessibility (TCC judges the calling binary itself, not sshd), the full real-injection suite on a TextEdit fixture passed on app-mac-host: type, key(BACKSPACE), control click, coordinate click, and focus all really injected and were re-observed.
+
+- Session metadata index (`session-index.json` in the agent dir): `SessionManager.listAll`'s default-layout branch is now served by a single-file JSON projection of session metadata (name/cwd/created/modified/message count/first message, no transcript text), written on first flush, rename, fork/branch, and selector deletion, and throttled (10s) for in-flight appends — cross-project resume listing is instant on the index-hit path instead of re-reading every session header. Index entries split relations (`file`/`dir`/`id`/`cwd`, reconciled against readdir) from content cache validated by a `file_mtime_ms` token: cache fields are trusted only while the file's stat mtime is unchanged, and refreshed by re-reading the file when it differs (write hooks are warm-up optimization, never correctness); project rows hold dir/cwd only with last-activity derived at serve time. The index is a projection, never the source of truth: missing, corrupt (JSON-level or field-level), or version-mismatched indexes rebuild from the existing full scan, so drift self-heals without user-visible errors. Accepted visible change (设计 `docs/design/会话索引.md` §5): All-scope search matches name/first message/id/cwd only — full-text search stays on the current-directory scope.
+
+- `/clean-sessions [days]` interactive command (single text-command entry point, no keybinding; 设计 `docs/design/会话索引.md` §7): deletes session files untouched for N days (default 7, positive-integer argument, usage echoed on invalid input) to keep session storage from filling the disk. Scanning stats every `*.jsonl` under all project directories of the default sessions root including `_agents/` (trace/guard sidecars excluded; the index cache is never trusted for this disk-reclaim decision), then runs a two-phase flow — preview of hit count, total size, and cutoff time, confirmation through the host dialog, then deletion of each hit with its paired `*.trace.jsonl` and `*.jsonl.guard`, index-entry removal, and emptied project directories — reporting deleted count and freed bytes. Zero hits report directly without entering confirmation.
+
+### Changed
+
+- TUI transcript silencing (D-083, 设计 `docs/design/终端输出模式设计.md` §3): interactive mode's transcript is now quiet by default — one assistant turn's tool calls merge into a single dim marker line (`⏺ bash` while running, `⏺ 3 个工具`/`⏺ 3 tools` when done; the sole tool keeps its name), with an error-colored failure count appended when any result was an error (`· 1 个失败`). Thinking blocks stay fully visible while streaming, then collapse to one dim line (`✻ 思考`/`✻ thinking`); `hideThinkingBlock` hides even that line. `Ctrl+O` (`app.tools.expand`, unchanged key) enters detail mode: per-tool full cards and full thinking text. Quiet rendering skips child tool components entirely (no kv arg lines, no result previews, no "(ctrl+o to expand)" meta hints); session records and tool results are untouched. Tool rendering contracts (`ToolExecutionComponent`, plugin `renderCall`/`renderResult`) are unchanged — only the transcript assembly (streaming and session-restore paths) groups per turn.
+- TUI quiet transcript follow-up (D-083 增补): a failing turn's marker now carries the failing result's first output line (single line, error color) under the `· N failed` count, and tool-result images (desktop/browser screenshots) render under the marker in quiet mode — both are user-visible conclusions, so neither stays hidden behind a global ctrl+o expansion. Text cards stay hidden; plugin render contracts unchanged.
+- Startup plugin bootstrap now realigns factory-listed first-party plugins automatically instead of warning (2026-10-04 install-and-use ruling, 设计 `插件独立分发与启动装配设计.md` §1 G5 例外 + §4.4): an active installation whose version misses the factory range (`^framework version`) is upgraded in place at startup — previously it only produced a `range_not_satisfied` diagnostic with a manual `plugin install`/`update --all` command, leaving every CLI upgrade one manual step away from a working tool surface. The `range_not_satisfied` diagnostic code, the `diagnosed` action status, and the `degraded` aggregate status are removed accordingly; aligned entries report `installed` with reason `range_aligned`, failures report `align_failed` with a "next startup retries automatically" diagnostic, and `AGENT_FORGE_PLUGIN_BOOTSTRAP=off` plus the offline posture gate still skip the whole run. Download failures retry 3 times with exponential backoff at the node wiring layer (the decision loop stays pure), and each install/align/failure now renders one stderr progress line (`{pluginId}: installed {version}` / install-failed with retry note, i18n'd) so a fresh install or upgrade shows live state instead of silence; fully-satisfied startups stay silent. `plugin install` of a factory plugin now prints "restart agent-forge to load it" instead of directing users to edit suite.json (factory plugins resolve through the suite's `builtin.*` capability aliases that default suites already declare).
+
+## [0.88.1] - 2026-10-04
+
 ## [0.88.1] - 2026-10-04
 
 ### Breaking Changes

package/bundled-plugins/agent-loop-policy/agent-forge.json

@@ -1,7 +1,7 @@
 {
 	"packageFormatVersion": 1,
 	"id": "agent-forge.plugin.agent-loop-policy",
-	"pluginVersion": "0.88.1",
+	"pluginVersion": "0.88.2",
 	"apiVersion": "1",
 	"minHostVersion": "0.88.0",
 	"platform": {

package/bundled-plugins/agent-loop-policy/plugin.json

@@ -1,6 +1,6 @@
 {
 	"id": "agent-forge.plugin.agent-loop-policy",
-	"version": "0.88.1",
+	"version": "0.88.2",
 	"apiVersion": "1-draft",
 	"entry": "./dist/entry.js",
 	"hostVersion": ">=0.88.0"

package/bundled-plugins/coding-tools/agent-forge.json

@@ -1,7 +1,7 @@
 {
 	"packageFormatVersion": 1,
 	"id": "agent-forge.plugin.coding-tools",
-	"pluginVersion": "0.88.1",
+	"pluginVersion": "0.88.2",
 	"apiVersion": "1",
 	"minHostVersion": "0.88.0",
 	"platform": {

package/bundled-plugins/coding-tools/plugin.json

@@ -1,6 +1,6 @@
 {
 	"id": "agent-forge.plugin.coding-tools",
-	"version": "0.88.1",
+	"version": "0.88.2",
 	"apiVersion": "1-draft",
 	"entry": "./dist/entry.js",
 	"hostVersion": ">=0.88.0",

package/bundled-plugins/compaction-policy/agent-forge.json

@@ -1,7 +1,7 @@
 {
 	"packageFormatVersion": 1,
 	"id": "agent-forge.plugin.compaction-policy",
-	"pluginVersion": "0.88.1",
+	"pluginVersion": "0.88.2",
 	"apiVersion": "1",
 	"minHostVersion": "0.88.0",
 	"platform": {

package/bundled-plugins/compaction-policy/plugin.json

@@ -1,6 +1,6 @@
 {
 	"id": "agent-forge.plugin.compaction-policy",
-	"version": "0.88.1",
+	"version": "0.88.2",
 	"apiVersion": "1-draft",
 	"entry": "./dist/entry.js",
 	"hostVersion": ">=0.88.0",

package/bundled-plugins/overflow-policy/agent-forge.json

@@ -1,7 +1,7 @@
 {
 	"packageFormatVersion": 1,
 	"id": "agent-forge.plugin.overflow-policy",
-	"pluginVersion": "0.88.1",
+	"pluginVersion": "0.88.2",
 	"apiVersion": "1",
 	"minHostVersion": "0.88.0",
 	"platform": {

package/bundled-plugins/overflow-policy/plugin.json

@@ -1,6 +1,6 @@
 {
 	"id": "agent-forge.plugin.overflow-policy",
-	"version": "0.88.1",
+	"version": "0.88.2",
 	"apiVersion": "1-draft",
 	"entry": "./dist/entry.js",
 	"hostVersion": ">=0.88.0",

package/bundled-plugins/provider-failover/agent-forge.json

@@ -1,7 +1,7 @@
 {
 	"packageFormatVersion": 1,
 	"id": "agent-forge.plugin.provider-failover",
-	"pluginVersion": "0.88.1",
+	"pluginVersion": "0.88.2",
 	"apiVersion": "1",
 	"minHostVersion": "0.88.0",
 	"platform": {

package/bundled-plugins/provider-failover/plugin.json

@@ -1,6 +1,6 @@
 {
 	"id": "agent-forge.plugin.provider-failover",
-	"version": "0.88.1",
+	"version": "0.88.2",
 	"apiVersion": "1-draft",
 	"entry": "./dist/entry.js",
 	"hostVersion": ">=0.88.0"

package/bundled-plugins/retry-policy/agent-forge.json

@@ -1,7 +1,7 @@
 {
 	"packageFormatVersion": 1,
 	"id": "agent-forge.plugin.retry-policy",
-	"pluginVersion": "0.88.1",
+	"pluginVersion": "0.88.2",
 	"apiVersion": "1",
 	"minHostVersion": "0.88.0",
 	"platform": {

package/bundled-plugins/retry-policy/plugin.json

@@ -1,6 +1,6 @@
 {
 	"id": "agent-forge.plugin.retry-policy",
-	"version": "0.88.1",
+	"version": "0.88.2",
 	"apiVersion": "1-draft",
 	"entry": "./dist/entry.js",
 	"hostVersion": ">=0.88.0",