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

package/CHANGELOG.md

@@ -2,6 +2,77 @@
 
 ## [Unreleased]
 
+## [0.88.3] - 2026-10-07
+
+### Breaking Changes
+
+- `CapabilityRuntime` gained a required member `hasLifecycleSubscribers(type, version)`: whether the registration map currently holds at least one lifecycle registration for the event key (owner activity is still rechecked at delivery). Structural implementers of this exported interface must add the member; in-repo `createCapabilityRuntime` is the only implementation and plugins only consume the interface, so external structural implementers are the affected surface.
+
+### Changed
+
+- Tool result cards now carry a per-item display budget (M2, docs/design/终端输出模式设计.md §3.2, ruling 2026-10-07): a `BoundedResultView` wraps every result renderer component (third-party plugin renderers included) plus the definition-less generic fallback, capping the rendered output at 400 visual lines — head plus the last 100 lines survive and the middle collapses to one hint line naming the omitted count (and the `fullOutputPath` reference when the tool's details carry one). The ctrl+o expanded view is capped by the same budget, so expansion is no longer an unbounded-output escape hatch; renderer contracts are untouched (`renderResult` still receives the raw `expanded` value and `lastComponent` gets the unwrapped child), and error results stay exempt (error visibility beats compactness). Small outputs render byte-for-byte unchanged. Covered by `test/tool-execution-component.test.ts` (M2 block).
+- Trace files now default to 14-day retention plus a per-directory cap of 500 files (M6 default retention, docs/design/会话轨迹与日志设计.md §6, ruling 2026-10-07): the startup sweep in main.ts runs by default and removes expired `*.trace.jsonl` files plus, per swept directory, the oldest-by-mtime survivors beyond the cap (age retention always wins a file over the cap — no double removal). `AGENT_FORGE_TRACE_MAX_AGE_DAYS` and the new `AGENT_FORGE_TRACE_MAX_FILES` override the defaults; an explicit `0` disables the respective mechanism (restoring keep-forever), an invalid value falls back to the default (previously: forever). Scope is unchanged: only the default sessions root (root + one level), never session files or custom `--session-dir`.
+- `output.put` resident artifact buffers are capped at 1 MiB (`OUTPUT_ARTIFACT_MAX_BUFFER_BYTES`, M4 double-layer limit, docs/design/终端输出模式设计.md 缓冲上限契约): buffering stops once the ceiling is exceeded while the `AsyncIterable` is still fully consumed (an early return would backpressure the producer — excess data is only dropped), and the resident view becomes head + ASCII marker (`\n[agent-forge artifact truncated: {N} bytes omitted]\n`) + the final 64 KiB of the completed stream, never exceeding the cap. `ref.sizeBytes`/`ref.truncated` are now runtime-computed (`sizeBytes` is always the original total including dropped bytes; caller-provided values are overridden), and the `onOutputArtifactCommit` observer intentionally receives the truncated resident view, so durable mirrors persist the truncated view (the bash tool collection layer keeps its own hard cap plus the `fullOutputPath` full spill, unaffected). Under-cap puts are byte-for-byte unchanged. Covered by `test/output-artifact-buffer-cap.test.ts`.
+- `model.stream` lifecycle dispatch is subscriber-gated: `dispatchModelStreamLifecycle` checks `hasLifecycleSubscribers` before the per-stream sequence increment, so with zero subscribers no per-delta envelope snapshot, clones, or dispatch happen and no sequence number is consumed — a late subscriber observes a contiguous stream starting at 1 (docs/design/插件基础能力设计.md §model.stream). With the bundled observability plugin attached (default), a subscriber is always present and the dispatch path is unchanged.
+- The four process-level diagnostic containers exposed through the inspector are now bounded, evicting oldest-first on overflow (docs/design/插件基础能力设计.md §8.3): `operations` 1024 (a `running` entry is never evicted because `reportOperationStep` rejects steps for non-running ids; when every entry is running the insert proceeds above the limit and the size stays at that high-water mark, since statuses have no terminal-state removal path), `spans` 1024 (terminal spans evicted first; when all are running it falls back to the oldest in insertion order, and a later `annotate`/`end` on an evicted span throws "not available"), `logs` 1000, `pluginRejections` 128.
+- Streaming assistant messages re-render incrementally: `AssistantMessageComponent.updateContent` diffs the rendered segment sequence and reuses unchanged prefix component instances (setText on the growing tail block), so a streaming frame no longer clears and rebuilds the whole message — per-frame cost drops from O(all blocks) to O(changed blocks) and the markdown token/line caches hit across frames instead of missing on every fresh instance. An `isStreaming` flip (turn end) still rebuilds fully, preserving the D-083 streaming/final transform split; terminal output is identical. Characterization tests pin the old streaming/thinking-collapse behavior.
+
+### Fixed
+
+- The host module supply contract now covers the root `@agent-forge/protocol` specifier: the memory plugin's inference client/protocol modules import it bare, and the jiti VIRTUAL_MODULES table only supplied the `protocol/subagent` subpath — in the install-store shape (no host node_modules) the bare import failed, the memory plugin was silently rejected on load (D-028), and zero memory tools registered. The boundary checker's host-supplied specifier list gains the same root so the three supply places stay synchronized (`test/host-module-supply.test.ts`).
+- `SessionManager` no longer copies `fileEntries` and `byId` on every append: `_appendEntry` rolls a failed storage write back in place (pop the pushed entry + conditional `byId` delete) instead of restoring an O(n) snapshot per append (O(n²) accumulation over a long session). Covered by deterministic failure-injection tests for a failed append and a failed first flush.
+
+## [0.88.2] - 2026-10-05
+
+### Breaking Changes
+
+- pi 品牌除名收口（用户裁决 2026-10-05）：环境变量只认 `AGENT_FORGE_*`，删除 `PI_TIMING` / `PI_EXPERIMENTAL` / `PI_CLEAR_ON_SHRINK` / `PI_HARDWARE_CURSOR` 的 legacy fallback 读取；package.json 包资源 manifest 键由 `pi`（`pi.skills` / `pi.prompts` / `pi.themes`）改为 `agent-forge`，旧键不再读取（`readPiManifest` → `readAgentForgeManifest`，`pi-manifest.ts` → `agent-forge-manifest.ts`）；experimental CLI 根命令 `pi` 更名 `agent-forge`（`PiCommand` → `AgentForgeCommand`，`runPi` → `runAgentForge`）。
+
+### 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).
+- Memory factory default flips off → light (user ruling 2026-10-05 "默认值按主流编程助手来、别默认关闭"): an unconfigured session now assembles the memory family (`memory_write`/`memory_recall`/`memory_list`/`memory_forget`, auto recall, bash error lessons) through the bundled memory package, matching mainstream coding assistants that ship memory enabled. Explicit `off` (settings `memory.mode`, env `AGENT_FORGE_MEMORY_MODE`, or the SDK `memoryCapability.mode` option) restores the previous privacy-first face, and invalid string values still fail closed to off with the same one-line diagnostics. Type-invalid `memoryMode`/`memorySettingsMode` config values now fail closed to off explicitly in the plugin entry instead of silently leaning on the old off default. The resolution chain (explicit > env > settings > legacy alias > default) is mirrored point by point between `resolveSdkMemoryMode` and the plugin's `resolveMemoryMode`; the golden default-session contract, the memory gating suite, and the default-value registry (`docs/design/产品默认值清单.md`) are re-pinned in the same change.
+- Memory model downloads now run as a background preheat that never blocks a prompt (2026-10-05 user ruling 「后台预热、不阻塞提问」): interactive mode kicks the one-time download right after session bind through the public `memory_enable` tool face — missing models start downloading immediately (progress in the plugin log), models already present settle in seconds, declined/absent memory is a no-op. Recall during an in-flight load returns a warming unavailable packet instead of awaiting the download (the old behavior silently blocked the first prompt's auto-recall for the whole download). Plugin-side controls ship in `plugins/memory`: `/memory` shows status, `/memory off` persists a decline (suppressing only the factory-default tier; explicit `memory.mode` re-enables and the preheat re-arms next session), `/memory retry` re-runs after a failure, and the AI-facing `memory_enable` tool shares the same closures.
+- Custom models.json models now default to `reasoning: true`, `maxTokens: 32768`, and `contextWindow: 256000` (user rulings 2026-10-05 "reasoning 默认 false 没有思考不合适" and "默认值按主流编程助手来、往大设置"): a minimal `{"id": ...}` entry gets thinking enabled at the default `medium` level instead of silently never thinking, and the window default no longer sits below mainstream 200K+ models (which triggered premature compaction). For models without thinking support, set `reasoning: false` explicitly — a wrongly-`true` model fails visibly (server rejects `reasoning_effort`) instead of the old silent capability loss; a true window below the default compacts late, caught by overflow detection. The `maxTokens` default moves 16384 → 32768 because reasoning models bill hidden thinking tokens against that budget and the docs already required ≥32768 for them. `cost` (all zero) default is unchanged; the values are registered in `docs/design/产品默认值清单.md`.
+
+## [0.88.1] - 2026-10-04
+
 ## [0.88.1] - 2026-10-04
 
 ### Breaking Changes

package/README.md

@@ -342,7 +342,7 @@ Create a plugin directory under `~/.agent-forge/agent/plugins/` or `.agent-forge
 }
 ```
 
-Capability plugin manifests are validated before loading. See [examples/extensions/](examples/extensions/) for MCP, CLI bridge, Goal/Plan and multi-Agent templates. The pre-plugin `pi` package manifest is supported only as legacy compatibility and is not the recommended extension path.
+Capability plugin manifests are validated before loading. See [examples/extensions/](examples/extensions/) for MCP, CLI bridge, Goal/Plan and multi-Agent templates. Package resource manifests are declared under the `agent-forge` key of a package.json; capability plugins via `plugin.json` are the recommended extension path.
 
 See [docs/packages.md](docs/packages.md).
 

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.3",
 	"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.3",
 	"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.3",
 	"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.3",
 	"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.3",
 	"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.3",
 	"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.3",
 	"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.3",
 	"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.3",
 	"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.3",
 	"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.3",
 	"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.3",
 	"apiVersion": "1-draft",
 	"entry": "./dist/entry.js",
 	"hostVersion": ">=0.88.0",

package/dist/artifacts/paged-read.d.ts

@@ -4,7 +4,12 @@
  *
  * `planArtifactPages` derives a deterministic page directory from the
  * artifact's stat size; `readArtifactPage` serves one page by slicing the
- * 2.6a store's read. Every unavailability (ended lifecycle, cross-session
+ * 2.6a store's read. Store contract this pager depends on: `stat().sizeBytes`
+ * MUST equal the byte length `read` serves. A store exposing a runtime-capped
+ * resident view (see OUTPUT_ARTIFACT_MAX_BUFFER_BYTES) keeps that invariant by
+ * statting with the resident length, not the original total — planning pages
+ * from a stat larger than the served bytes would produce silent empty tail
+ * pages here. Every unavailability (ended lifecycle, cross-session
  * read, unknown id, invalid page size) is a structured `unavailable`
  * result — never a crash and never a silent empty page. No new Agent
  * business API is introduced; the 2.6a store remains the only bytes source.

package/dist/artifacts/paged-read.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"paged-read.d.ts","sourceRoot":"","sources":["../../src/artifacts/paged-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,MAAM,WAAW,4BAA4B;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,kBAAkB,GAC3B;IACA,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,4BAA4B,EAAE,CAAC;CACvD,GACD;IAAE,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACnE;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D,MAAM,MAAM,kBAAkB,GAC3B;IACA,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC5B,GACD;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D,wBAAgB,iBAAiB,CAChC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,EACpC,KAAK,EAAE;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC/D,kBAAkB,CAkBpB;AAED,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC,EAC7C,KAAK,EAAE;IACN,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B,GACC,kBAAkB,CAgCpB","sourcesContent":["/**\n * Paged artifact reading (3.5c) — expands large artifacts through reference\n * pages instead of one unbounded read.\n *\n * `planArtifactPages` derives a deterministic page directory from the\n * artifact's stat size; `readArtifactPage` serves one page by slicing the\n * 2.6a store's read. Every unavailability (ended lifecycle, cross-session\n * read, unknown id, invalid page size) is a structured `unavailable`\n * result — never a crash and never a silent empty page. No new Agent\n * business API is introduced; the 2.6a store remains the only bytes source.\n */\nimport type { ArtifactStoreV1 } from \"./artifact-store.ts\";\n\nexport interface ArtifactPageDirectoryEntryV1 {\n\treadonly index: number;\n\treadonly offset: number;\n\treadonly size: number;\n}\n\nexport type ArtifactPagePlanV1 =\n\t| {\n\t\t\treadonly status: \"planned\";\n\t\t\treadonly totalBytes: number;\n\t\t\treadonly pageSize: number;\n\t\t\treadonly pages: readonly ArtifactPageDirectoryEntryV1[];\n\t  }\n\t| { readonly status: \"invalid_page_size\"; readonly pageSize: number }\n\t| { readonly status: \"unavailable\"; readonly reason: string };\n\nexport type ArtifactPageReadV1 =\n\t| {\n\t\t\treadonly status: \"ok\";\n\t\t\treadonly index: number;\n\t\t\treadonly offset: number;\n\t\t\treadonly bytes: Uint8Array;\n\t\t\treadonly hasMore: boolean;\n\t\t\treadonly nextOffset?: number;\n\t  }\n\t| { readonly status: \"unavailable\"; readonly reason: string };\n\nexport function planArtifactPages(\n\tstore: Pick<ArtifactStoreV1, \"stat\">,\n\tinput: { readonly artifactId: string; readonly pageSize: number },\n): ArtifactPagePlanV1 {\n\tif (!Number.isSafeInteger(input.pageSize) || input.pageSize < 1) {\n\t\treturn { status: \"invalid_page_size\", pageSize: input.pageSize };\n\t}\n\tconst stat = store.stat(input.artifactId);\n\tif (!stat) return { status: \"unavailable\", reason: `Artifact not found: ${input.artifactId}` };\n\tif (stat.state === \"ended\") {\n\t\treturn {\n\t\t\tstatus: \"unavailable\",\n\t\t\treason: `Artifact ${input.artifactId} lifecycle has ended: ${stat.endReason ?? \"ended\"}`,\n\t\t};\n\t}\n\tconst totalBytes = stat.sizeBytes ?? 0;\n\tconst pages: ArtifactPageDirectoryEntryV1[] = [];\n\tfor (let offset = 0; offset < totalBytes; offset += input.pageSize) {\n\t\tpages.push({ index: pages.length, offset, size: Math.min(input.pageSize, totalBytes - offset) });\n\t}\n\treturn { status: \"planned\", totalBytes, pageSize: input.pageSize, pages: Object.freeze(pages) };\n}\n\nexport function readArtifactPage(\n\tstore: Pick<ArtifactStoreV1, \"read\" | \"stat\">,\n\tinput: {\n\t\treadonly artifactId: string;\n\t\treadonly sessionId: string;\n\t\treadonly index: number;\n\t\treadonly pageSize: number;\n\t},\n): ArtifactPageReadV1 {\n\tif (!Number.isSafeInteger(input.pageSize) || input.pageSize < 1) {\n\t\treturn { status: \"unavailable\", reason: `Invalid page size: ${input.pageSize}` };\n\t}\n\tconst plan = planArtifactPages(store, { artifactId: input.artifactId, pageSize: input.pageSize });\n\tif (plan.status !== \"planned\")\n\t\treturn {\n\t\t\tstatus: \"unavailable\",\n\t\t\t// v8 ignore next -- pageSize 已在入口校验，plan 不可能返回 invalid_page_size\n\t\t\treason: plan.status === \"unavailable\" ? plan.reason : `Invalid page size: ${plan.pageSize}`,\n\t\t};\n\tconst page = plan.pages[input.index];\n\tif (!page) {\n\t\treturn { status: \"unavailable\", reason: `Page ${input.index} is outside the plan (${plan.pages.length} pages)` };\n\t}\n\tlet bytes: Uint8Array;\n\ttry {\n\t\tbytes = store.read({ artifactId: input.artifactId, sessionId: input.sessionId }).bytes;\n\t} catch (error) {\n\t\treturn { status: \"unavailable\", reason: error instanceof Error ? error.message : String(error) };\n\t}\n\tconst slice = bytes.slice(page.offset, page.offset + page.size);\n\tconst nextOffset = page.offset + page.size;\n\tconst hasMore = nextOffset < plan.totalBytes;\n\treturn {\n\t\tstatus: \"ok\",\n\t\tindex: page.index,\n\t\toffset: page.offset,\n\t\tbytes: slice,\n\t\thasMore,\n\t\t...(hasMore ? { nextOffset } : {}),\n\t};\n}\n"]}
+{"version":3,"file":"paged-read.d.ts","sourceRoot":"","sources":["../../src/artifacts/paged-read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,MAAM,WAAW,4BAA4B;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,kBAAkB,GAC3B;IACA,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,4BAA4B,EAAE,CAAC;CACvD,GACD;IAAE,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACnE;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D,MAAM,MAAM,kBAAkB,GAC3B;IACA,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC5B,GACD;IAAE,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/D,wBAAgB,iBAAiB,CAChC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,EACpC,KAAK,EAAE;IAAE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAC/D,kBAAkB,CAkBpB;AAED,wBAAgB,gBAAgB,CAC/B,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,GAAG,MAAM,CAAC,EAC7C,KAAK,EAAE;IACN,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC1B,GACC,kBAAkB,CAgCpB","sourcesContent":["/**\n * Paged artifact reading (3.5c) — expands large artifacts through reference\n * pages instead of one unbounded read.\n *\n * `planArtifactPages` derives a deterministic page directory from the\n * artifact's stat size; `readArtifactPage` serves one page by slicing the\n * 2.6a store's read. Store contract this pager depends on: `stat().sizeBytes`\n * MUST equal the byte length `read` serves. A store exposing a runtime-capped\n * resident view (see OUTPUT_ARTIFACT_MAX_BUFFER_BYTES) keeps that invariant by\n * statting with the resident length, not the original total — planning pages\n * from a stat larger than the served bytes would produce silent empty tail\n * pages here. Every unavailability (ended lifecycle, cross-session\n * read, unknown id, invalid page size) is a structured `unavailable`\n * result — never a crash and never a silent empty page. No new Agent\n * business API is introduced; the 2.6a store remains the only bytes source.\n */\nimport type { ArtifactStoreV1 } from \"./artifact-store.ts\";\n\nexport interface ArtifactPageDirectoryEntryV1 {\n\treadonly index: number;\n\treadonly offset: number;\n\treadonly size: number;\n}\n\nexport type ArtifactPagePlanV1 =\n\t| {\n\t\t\treadonly status: \"planned\";\n\t\t\treadonly totalBytes: number;\n\t\t\treadonly pageSize: number;\n\t\t\treadonly pages: readonly ArtifactPageDirectoryEntryV1[];\n\t  }\n\t| { readonly status: \"invalid_page_size\"; readonly pageSize: number }\n\t| { readonly status: \"unavailable\"; readonly reason: string };\n\nexport type ArtifactPageReadV1 =\n\t| {\n\t\t\treadonly status: \"ok\";\n\t\t\treadonly index: number;\n\t\t\treadonly offset: number;\n\t\t\treadonly bytes: Uint8Array;\n\t\t\treadonly hasMore: boolean;\n\t\t\treadonly nextOffset?: number;\n\t  }\n\t| { readonly status: \"unavailable\"; readonly reason: string };\n\nexport function planArtifactPages(\n\tstore: Pick<ArtifactStoreV1, \"stat\">,\n\tinput: { readonly artifactId: string; readonly pageSize: number },\n): ArtifactPagePlanV1 {\n\tif (!Number.isSafeInteger(input.pageSize) || input.pageSize < 1) {\n\t\treturn { status: \"invalid_page_size\", pageSize: input.pageSize };\n\t}\n\tconst stat = store.stat(input.artifactId);\n\tif (!stat) return { status: \"unavailable\", reason: `Artifact not found: ${input.artifactId}` };\n\tif (stat.state === \"ended\") {\n\t\treturn {\n\t\t\tstatus: \"unavailable\",\n\t\t\treason: `Artifact ${input.artifactId} lifecycle has ended: ${stat.endReason ?? \"ended\"}`,\n\t\t};\n\t}\n\tconst totalBytes = stat.sizeBytes ?? 0;\n\tconst pages: ArtifactPageDirectoryEntryV1[] = [];\n\tfor (let offset = 0; offset < totalBytes; offset += input.pageSize) {\n\t\tpages.push({ index: pages.length, offset, size: Math.min(input.pageSize, totalBytes - offset) });\n\t}\n\treturn { status: \"planned\", totalBytes, pageSize: input.pageSize, pages: Object.freeze(pages) };\n}\n\nexport function readArtifactPage(\n\tstore: Pick<ArtifactStoreV1, \"read\" | \"stat\">,\n\tinput: {\n\t\treadonly artifactId: string;\n\t\treadonly sessionId: string;\n\t\treadonly index: number;\n\t\treadonly pageSize: number;\n\t},\n): ArtifactPageReadV1 {\n\tif (!Number.isSafeInteger(input.pageSize) || input.pageSize < 1) {\n\t\treturn { status: \"unavailable\", reason: `Invalid page size: ${input.pageSize}` };\n\t}\n\tconst plan = planArtifactPages(store, { artifactId: input.artifactId, pageSize: input.pageSize });\n\tif (plan.status !== \"planned\")\n\t\treturn {\n\t\t\tstatus: \"unavailable\",\n\t\t\t// v8 ignore next -- pageSize 已在入口校验，plan 不可能返回 invalid_page_size\n\t\t\treason: plan.status === \"unavailable\" ? plan.reason : `Invalid page size: ${plan.pageSize}`,\n\t\t};\n\tconst page = plan.pages[input.index];\n\tif (!page) {\n\t\treturn { status: \"unavailable\", reason: `Page ${input.index} is outside the plan (${plan.pages.length} pages)` };\n\t}\n\tlet bytes: Uint8Array;\n\ttry {\n\t\tbytes = store.read({ artifactId: input.artifactId, sessionId: input.sessionId }).bytes;\n\t} catch (error) {\n\t\treturn { status: \"unavailable\", reason: error instanceof Error ? error.message : String(error) };\n\t}\n\tconst slice = bytes.slice(page.offset, page.offset + page.size);\n\tconst nextOffset = page.offset + page.size;\n\tconst hasMore = nextOffset < plan.totalBytes;\n\treturn {\n\t\tstatus: \"ok\",\n\t\tindex: page.index,\n\t\toffset: page.offset,\n\t\tbytes: slice,\n\t\thasMore,\n\t\t...(hasMore ? { nextOffset } : {}),\n\t};\n}\n"]}

package/dist/artifacts/paged-read.js.map

@@ -1 +1 @@
-{"version":3,"file":"paged-read.js","sourceRoot":"","sources":["../../src/artifacts/paged-read.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Paged artifact reading (3.5c) — expands large artifacts through reference\n * pages instead of one unbounded read.\n *\n * `planArtifactPages` derives a deterministic page directory from the\n * artifact's stat size; `readArtifactPage` serves one page by slicing the\n * 2.6a store's read. Every unavailability (ended lifecycle, cross-session\n * read, unknown id, invalid page size) is a structured `unavailable`\n * result — never a crash and never a silent empty page. No new Agent\n * business API is introduced; the 2.6a store remains the only bytes source.\n */\nimport type { ArtifactStoreV1 } from \"./artifact-store.ts\";\n\nexport interface ArtifactPageDirectoryEntryV1 {\n\treadonly index: number;\n\treadonly offset: number;\n\treadonly size: number;\n}\n\nexport type ArtifactPagePlanV1 =\n\t| {\n\t\t\treadonly status: \"planned\";\n\t\t\treadonly totalBytes: number;\n\t\t\treadonly pageSize: number;\n\t\t\treadonly pages: readonly ArtifactPageDirectoryEntryV1[];\n\t  }\n\t| { readonly status: \"invalid_page_size\"; readonly pageSize: number }\n\t| { readonly status: \"unavailable\"; readonly reason: string };\n\nexport type ArtifactPageReadV1 =\n\t| {\n\t\t\treadonly status: \"ok\";\n\t\t\treadonly index: number;\n\t\t\treadonly offset: number;\n\t\t\treadonly bytes: Uint8Array;\n\t\t\treadonly hasMore: boolean;\n\t\t\treadonly nextOffset?: number;\n\t  }\n\t| { readonly status: \"unavailable\"; readonly reason: string };\n\nexport function planArtifactPages(\n\tstore: Pick<ArtifactStoreV1, \"stat\">,\n\tinput: { readonly artifactId: string; readonly pageSize: number },\n): ArtifactPagePlanV1 {\n\tif (!Number.isSafeInteger(input.pageSize) || input.pageSize < 1) {\n\t\treturn { status: \"invalid_page_size\", pageSize: input.pageSize };\n\t}\n\tconst stat = store.stat(input.artifactId);\n\tif (!stat) return { status: \"unavailable\", reason: `Artifact not found: ${input.artifactId}` };\n\tif (stat.state === \"ended\") {\n\t\treturn {\n\t\t\tstatus: \"unavailable\",\n\t\t\treason: `Artifact ${input.artifactId} lifecycle has ended: ${stat.endReason ?? \"ended\"}`,\n\t\t};\n\t}\n\tconst totalBytes = stat.sizeBytes ?? 0;\n\tconst pages: ArtifactPageDirectoryEntryV1[] = [];\n\tfor (let offset = 0; offset < totalBytes; offset += input.pageSize) {\n\t\tpages.push({ index: pages.length, offset, size: Math.min(input.pageSize, totalBytes - offset) });\n\t}\n\treturn { status: \"planned\", totalBytes, pageSize: input.pageSize, pages: Object.freeze(pages) };\n}\n\nexport function readArtifactPage(\n\tstore: Pick<ArtifactStoreV1, \"read\" | \"stat\">,\n\tinput: {\n\t\treadonly artifactId: string;\n\t\treadonly sessionId: string;\n\t\treadonly index: number;\n\t\treadonly pageSize: number;\n\t},\n): ArtifactPageReadV1 {\n\tif (!Number.isSafeInteger(input.pageSize) || input.pageSize < 1) {\n\t\treturn { status: \"unavailable\", reason: `Invalid page size: ${input.pageSize}` };\n\t}\n\tconst plan = planArtifactPages(store, { artifactId: input.artifactId, pageSize: input.pageSize });\n\tif (plan.status !== \"planned\")\n\t\treturn {\n\t\t\tstatus: \"unavailable\",\n\t\t\t// v8 ignore next -- pageSize 已在入口校验，plan 不可能返回 invalid_page_size\n\t\t\treason: plan.status === \"unavailable\" ? plan.reason : `Invalid page size: ${plan.pageSize}`,\n\t\t};\n\tconst page = plan.pages[input.index];\n\tif (!page) {\n\t\treturn { status: \"unavailable\", reason: `Page ${input.index} is outside the plan (${plan.pages.length} pages)` };\n\t}\n\tlet bytes: Uint8Array;\n\ttry {\n\t\tbytes = store.read({ artifactId: input.artifactId, sessionId: input.sessionId }).bytes;\n\t} catch (error) {\n\t\treturn { status: \"unavailable\", reason: error instanceof Error ? error.message : String(error) };\n\t}\n\tconst slice = bytes.slice(page.offset, page.offset + page.size);\n\tconst nextOffset = page.offset + page.size;\n\tconst hasMore = nextOffset < plan.totalBytes;\n\treturn {\n\t\tstatus: \"ok\",\n\t\tindex: page.index,\n\t\toffset: page.offset,\n\t\tbytes: slice,\n\t\thasMore,\n\t\t...(hasMore ? { nextOffset } : {}),\n\t};\n}\n"]}
+{"version":3,"file":"paged-read.js","sourceRoot":"","sources":["../../src/artifacts/paged-read.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Paged artifact reading (3.5c) — expands large artifacts through reference\n * pages instead of one unbounded read.\n *\n * `planArtifactPages` derives a deterministic page directory from the\n * artifact's stat size; `readArtifactPage` serves one page by slicing the\n * 2.6a store's read. Store contract this pager depends on: `stat().sizeBytes`\n * MUST equal the byte length `read` serves. A store exposing a runtime-capped\n * resident view (see OUTPUT_ARTIFACT_MAX_BUFFER_BYTES) keeps that invariant by\n * statting with the resident length, not the original total — planning pages\n * from a stat larger than the served bytes would produce silent empty tail\n * pages here. Every unavailability (ended lifecycle, cross-session\n * read, unknown id, invalid page size) is a structured `unavailable`\n * result — never a crash and never a silent empty page. No new Agent\n * business API is introduced; the 2.6a store remains the only bytes source.\n */\nimport type { ArtifactStoreV1 } from \"./artifact-store.ts\";\n\nexport interface ArtifactPageDirectoryEntryV1 {\n\treadonly index: number;\n\treadonly offset: number;\n\treadonly size: number;\n}\n\nexport type ArtifactPagePlanV1 =\n\t| {\n\t\t\treadonly status: \"planned\";\n\t\t\treadonly totalBytes: number;\n\t\t\treadonly pageSize: number;\n\t\t\treadonly pages: readonly ArtifactPageDirectoryEntryV1[];\n\t  }\n\t| { readonly status: \"invalid_page_size\"; readonly pageSize: number }\n\t| { readonly status: \"unavailable\"; readonly reason: string };\n\nexport type ArtifactPageReadV1 =\n\t| {\n\t\t\treadonly status: \"ok\";\n\t\t\treadonly index: number;\n\t\t\treadonly offset: number;\n\t\t\treadonly bytes: Uint8Array;\n\t\t\treadonly hasMore: boolean;\n\t\t\treadonly nextOffset?: number;\n\t  }\n\t| { readonly status: \"unavailable\"; readonly reason: string };\n\nexport function planArtifactPages(\n\tstore: Pick<ArtifactStoreV1, \"stat\">,\n\tinput: { readonly artifactId: string; readonly pageSize: number },\n): ArtifactPagePlanV1 {\n\tif (!Number.isSafeInteger(input.pageSize) || input.pageSize < 1) {\n\t\treturn { status: \"invalid_page_size\", pageSize: input.pageSize };\n\t}\n\tconst stat = store.stat(input.artifactId);\n\tif (!stat) return { status: \"unavailable\", reason: `Artifact not found: ${input.artifactId}` };\n\tif (stat.state === \"ended\") {\n\t\treturn {\n\t\t\tstatus: \"unavailable\",\n\t\t\treason: `Artifact ${input.artifactId} lifecycle has ended: ${stat.endReason ?? \"ended\"}`,\n\t\t};\n\t}\n\tconst totalBytes = stat.sizeBytes ?? 0;\n\tconst pages: ArtifactPageDirectoryEntryV1[] = [];\n\tfor (let offset = 0; offset < totalBytes; offset += input.pageSize) {\n\t\tpages.push({ index: pages.length, offset, size: Math.min(input.pageSize, totalBytes - offset) });\n\t}\n\treturn { status: \"planned\", totalBytes, pageSize: input.pageSize, pages: Object.freeze(pages) };\n}\n\nexport function readArtifactPage(\n\tstore: Pick<ArtifactStoreV1, \"read\" | \"stat\">,\n\tinput: {\n\t\treadonly artifactId: string;\n\t\treadonly sessionId: string;\n\t\treadonly index: number;\n\t\treadonly pageSize: number;\n\t},\n): ArtifactPageReadV1 {\n\tif (!Number.isSafeInteger(input.pageSize) || input.pageSize < 1) {\n\t\treturn { status: \"unavailable\", reason: `Invalid page size: ${input.pageSize}` };\n\t}\n\tconst plan = planArtifactPages(store, { artifactId: input.artifactId, pageSize: input.pageSize });\n\tif (plan.status !== \"planned\")\n\t\treturn {\n\t\t\tstatus: \"unavailable\",\n\t\t\t// v8 ignore next -- pageSize 已在入口校验，plan 不可能返回 invalid_page_size\n\t\t\treason: plan.status === \"unavailable\" ? plan.reason : `Invalid page size: ${plan.pageSize}`,\n\t\t};\n\tconst page = plan.pages[input.index];\n\tif (!page) {\n\t\treturn { status: \"unavailable\", reason: `Page ${input.index} is outside the plan (${plan.pages.length} pages)` };\n\t}\n\tlet bytes: Uint8Array;\n\ttry {\n\t\tbytes = store.read({ artifactId: input.artifactId, sessionId: input.sessionId }).bytes;\n\t} catch (error) {\n\t\treturn { status: \"unavailable\", reason: error instanceof Error ? error.message : String(error) };\n\t}\n\tconst slice = bytes.slice(page.offset, page.offset + page.size);\n\tconst nextOffset = page.offset + page.size;\n\tconst hasMore = nextOffset < plan.totalBytes;\n\treturn {\n\t\tstatus: \"ok\",\n\t\tindex: page.index,\n\t\toffset: page.offset,\n\t\tbytes: slice,\n\t\thasMore,\n\t\t...(hasMore ? { nextOffset } : {}),\n\t};\n}\n"]}