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

package/CHANGELOG.md

@@ -2,8 +2,32 @@
 
 ## [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.
@@ -43,6 +67,9 @@
 - 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
 

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.2",
+	"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.2",
+	"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.2",
+	"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.2",
+	"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.2",
+	"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.2",
+	"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.2",
+	"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.2",
+	"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.2",
+	"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.2",
+	"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.2",
+	"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.2",
+	"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"]}