@zihanw/pi-forge 0.5.0 → 0.5.1

package/CHANGELOG.md

@@ -6,6 +6,44 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 In 0.x development, breaking changes may occur in minor releases and will be explicitly noted.
 
+## [0.5.1] - 2026-08-23
+
+### Added
+
+- **Cross-platform release CI.** The complete verification surface, including
+  the real-browser editor suite and packed-install smoke, now runs on GitHub's
+  macOS and Windows hosted runners in addition to Linux. Generated TypeScript
+  output and repository text files are pinned to LF so tracked `dist/` checks
+  remain deterministic across operating systems.
+- **UI contribution framework (Lane 1).** Optional packages can now contribute schema-driven configuration pages to the web editor without shipping any UI code into the main package:
+  - New versioned `@zihanw/pi-forge/ui-contribution` entry point: a generic RPC contract over the Pi event bus (`UI_CONTRIBUTION_PORT_VERSION = 1`, with its own version counter separate from the `/subagent` host port) exposing exactly two operations — `listContributions` and `writeValues` — over discover/available/request/reply/unavailable channels. Wire messages carry `hostId` + `generation` binding, version negotiation (`minVersion`/`maxVersion`), bounded discovery timeouts, explicit duplicate-provider failure, and recursive JSON-compatibility validators. All payloads are plain data: no functions, components, or live contexts cross the bus. See the [UI contribution port contract](docs/reference/ui-contribution-port.md).
+  - Web server routes: `GET /api/contrib` returns discovered tab descriptors at page load, and `PUT /api/contrib/<tabId>` proxies submitted values to the contributing package over the bus. The forge side is fully generic and knows nothing about subagents; it never owns the schema, validation, or persistence of contributed tabs (the provider writes its own config files), and with no provider discovered there is no contributed tab and zero cost.
+  - Contribution discovery tolerates provider churn across sessions: providers that appear after startup surface their tabs, departed providers are cleared, and service stop cancels pending discovery.
+  - Data-driven stack-tab registry replaces the stack editor's hardcoded `"policy" | "regex" | "stack"` tab union. Built-in tabs keep their existing hosts (including the legacy imperative items workspace as an ordinary tab), while contributed configuration renders through a self-contained host on a separate top-level **Settings** surface.
+  - Generic schema-form renderer: a self-contained Vue component bridged via the vue-host mechanism, covering deliberately restricted v1 field types — boolean, number, enum, string, plus a record/table shape for keyed per-entry lists. Record identities may use live catalog-backed `keyOptions`, while validation and persistence remain provider-owned. No imperative code was added to `legacy-editor.ts`.
+- **Context diff — per-turn prompt observability (Lane 2).** Consecutive real provider requests are diffed automatically so KV-cache reuse is observable:
+  - Host-neutral pure engine (`src/context-diff.ts`): `TurnSnapshot`/`TurnDiff` shapes, block classification (`same`/`added`/`removed`/`modified`) aligned by stable content-derived keys with positional fallback, and a prefix-walk cache-boundary algorithm that walks matching block hashes and trims the char-level common prefix inside the first mismatched block — no Myers diff. Token figures are chars/4 approximations: relative deltas are accurate, and absolute boundary claims are labeled approx in the UI.
+  - Automatic per-turn capture: every provider request enters a rolling history of the last 20 turns (not just manually armed captures), and each new snapshot is auto-diffed against the previous turn. Block hashes cover role and serialized wire-relevant fields, and request-level sections (tool definitions and similar) participate as blocks so wire changes break the cache boundary faithfully.
+  - `GET /api/context-diff` serves the latest snapshot, the previous-turn diff, and summary rollups (added/removed/net tokens, prefix tokens and ratio).
+  - Preview/diff dock: the preview modal is promoted into a wider right-side panel with three focused views — **Preview** (the live compiled draft), **Draft diff** (the unsaved draft against the saved stack), and **Run diff** (the latest captured provider turn against its predecessor). Diff views hide unchanged blocks by default, show modified blocks in Before/After columns, keep run/cache metadata collapsed until requested, and offer **Focus/Split** controls to use the full editor width without permanently crowding stack editing. The panel is a self-contained Vue component riding Lane 1's data-driven registry; no imperative code was added to `legacy-editor.ts`.
+
+### Fixed
+
+- Preview/Draft/Run diffs now render git-style unified or split line views with old/new line numbers, inline changed spans, and changes-only/three-line/all-line context controls. Chars/4 figures are labeled strictly as estimates. Each captured provider request is correlated with its completed assistant message, so Run metadata shows Pi's actual input/output/cache-read/cache-write usage and a provider-reported cache-hit rate when cache reporting has been observed; otherwise it says the rate is not reported instead of presenting a synthetic zero.
+
+- Schema-driven record settings can now provide catalog-backed `keyOptions`, rendered as a duplicate-safe selector instead of a free-text identity field. UI-contribution handlers may resolve asynchronously, allowing optional packages to refresh host-owned catalogs before returning a schema or validating a write; stale replies are suppressed if that provider generation stops while the handler is pending.
+
+- Selective stack tool allow lists now select from Pi's complete registered tool catalog, so built-in inactive tools such as `grep`, `find`, and `ls` can be activated by a stack and are restored to their prior inactive state when the policy is removed. Allow lists containing `*` remain on the active baseline and do not expand to every inactive tool. The web editor now states the active-vs-registered distinction explicitly.
+- The docked Compiled preview now consumes the editor's current in-memory stack draft, refreshes from actual draft-change notifications, aborts superseded requests, and no longer silently previews the saved disk version while unsaved edits are visible.
+- Plugin configuration no longer mounts inside the stack Preview dock. Contributed pages now live on an independent top-level **Settings** surface, so switching between Stack Preview and Subagent Settings cannot unmount or constrain the settings form.
+- Preview now owns a dedicated DOM mount instead of sharing the legacy stack-tab panel, so saving or selecting another stack cannot leave an active-but-empty dock. Draft changes immediately invalidate visible compiled output, Preview and Run requests both reject superseded responses, and browser tests cover save/selection plus controlled delayed-response races.
+- Settings autosaves are serialized per contribution host and replay the newest full form snapshot after an in-flight write, preventing a slow older PUT from overwriting a newer edit while the UI reports `Saved`. Drafts and save status are retained independently per Settings page during rapid tab switches, while a forge-owned monotonic provider-session key forces clean forms to remount with fresh schema and values after fast provider churn. PUT results are bound to the provider session that received them, so a delayed old-session success retries the preserved draft instead of overwriting the new session. Duplicate contribution IDs are ignored after the first descriptor and Settings button IDs cannot collide with built-in stack tabs.
+- Compiled draft diffs align messages with stable source keys rather than positional `message-<index>` IDs, avoiding cascades of false modifications after insertions. Split Preview and top-level Settings collapse to usable single-column layouts on narrow screens without document-level horizontal overflow.
+- The stack editor now keeps the Project/Global selector attached to **New stack** instead of stretching it across a full row, leaves only primary actions in the toolbar, moves infrequent capture/import/export/delete actions into **More**, and compacts the status, metadata, tab, sidebar, and item-list chrome so editing and Preview/Diff receive substantially more viewport space.
+- The profile editor now keeps the canonical `global:<id>` selector visible in list, summary, edit heading, and save status. Profile JSON continues to store a bare schema ID and same-scope prompt-stack references relatively; their global identity is carried by storage scope and is no longer visually lost in the editor.
+- Context-diff fidelity (architecture review F1–F3/F6 and re-review R1–R4): block hashes are computed from the faithful redacted serialization rather than the lossy capture projection, preserving provider field order for request-level blocks; blocks align by stable unique keys so insertions before existing messages classify correctly; token rounding is conservative and consistent so per-block chips cannot contradict summary totals; and the empty Diff view reflects automatic per-turn capture instead of instructing manual arming.
+- UI-contribution hardening (F4/F5/F7): a partial-patch `writeValues` success no longer clobbers cached descriptor values with stale data; contribution lifecycle handles late-surfacing and departed providers and cancels pending discovery on stop; malformed or oversized `/api/contrib` request bodies return 400/413 instead of surfacing raw validator failures.
+
 ## [0.5.0] - 2026-08-21
 
 ### Planning

package/README.md

@@ -17,6 +17,7 @@ Think of it as a character sheet and workbench for your AI agent.
 - Use immutable stack `parameters` with the deterministic forge-v1 template engine.
 - Apply deterministic regex transforms to outgoing prompts or finalized assistant messages.
 - Edit stacks and profiles in a local browser UI and inspect the exact provider payload.
+- Inspect prompt changes in the Preview dock: **Preview** compiles the live draft, **Draft diff** compares unsaved edits with disk, and **Run diff** compares recent provider turns. Git-style unified/split views include old/new line numbers, inline highlights, and changes-only/three-line/all-line context. Run metadata keeps chars/4 estimates separate from Pi's provider-reported prompt/cache usage and real cache-hit rate.
 - Run an explicitly enabled profile as an experimental, approval-gated foreground subagent.
 
 ## Install
@@ -57,7 +58,7 @@ Restart Pi or run:
 /preset ui
 ```
 
-The local editor can create, fork, validate, preview, import, export, and delete prompt stacks. Its **Agent profiles** view manages one-shot model/thinking/stack presets. Writes require a trusted project. Delegation settings live in the optional `@zihanw/pi-forge-subagents` package's `subagents.json` files, not in the editor.
+The local editor can create, fork, validate, preview, import, export, and delete prompt stacks. Its **Agent profiles** view manages one-shot model/thinking/stack presets. Writes require a trusted project. When `@zihanw/pi-forge-subagents` is installed, its schema-driven editor appears on the separate top-level **Settings** surface and persists to the optional package's `subagents.json` files.
 
 ### 3. Save a profile
 

package/README.zh-CN.md

@@ -57,7 +57,7 @@ cp examples/default-prompt-stack.json .pi/forge/prompt-stacks/default.json
 /preset ui
 ```
 
-本地编辑器可以新建、fork、校验、预览、导入、导出和删除 prompt stack，并可在新建/fork/导入时明确选择写入项目或用户全局存储。切换到 **Agent profiles** 可以浏览项目与全局 profile、编辑和删除全局 profile（通过显式 `global:<id>` 路由）。写入操作要求项目已被信任。Delegation 配置由可选包 `@zihanw/pi-forge-subagents` 的 `subagents.json` 文件管理，不在编辑器中。
+本地编辑器可以新建、fork、校验、预览、导入、导出和删除 prompt stack，并可在新建/fork/导入时明确选择写入项目或用户全局存储。Preview dock 提供带旧/新行号和行内高亮的 unified/split diff，可只看变化行或保留三行/全部上下文；Run diff 会把 chars/4 估算与 Pi 返回的真实 prompt/cache usage、cache hit rate 明确分开。切换到 **Agent profiles** 可以浏览项目与全局 profile、编辑和删除全局 profile（通过显式 `global:<id>` 路由）。写入操作要求项目已被信任。Delegation 配置由可选包 `@zihanw/pi-forge-subagents` 的 `subagents.json` 文件管理，不在编辑器中。
 
 ### 3. 保存 profile
 

package/dist/context-diff-history.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Host-neutral rolling context-diff history.
+ *
+ * Keeps the last N turn snapshots captured from provider payloads and exposes
+ * the latest engine-computed diff plus compact summaries for recent turns.
+ */
+import { type TurnDiff, type TurnSnapshot } from "./context-diff.ts";
+import { type ContextDiffCapture } from "./context-diff-snapshot.ts";
+export declare const CONTEXT_DIFF_HISTORY_LIMIT = 20;
+export interface ContextDiffHistory {
+    turns: TurnSnapshot[];
+    latestDiff?: TurnDiff;
+    nextTurnNumber?: number;
+    usageByTurnId: Map<string, ContextDiffProviderUsage>;
+    cacheReportingModels: Set<string>;
+}
+export interface ContextDiffProviderUsageInput {
+    provider: string;
+    model: string;
+    stopReason: string;
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    totalTokens: number;
+}
+export interface ContextDiffProviderUsage extends ContextDiffProviderUsageInput {
+    promptTokens: number;
+    cacheHitRatio: number | null;
+    cacheStatus: "reported" | "not-reported";
+}
+export interface ContextDiffTurnSummary {
+    turnId: string;
+    capturedAt: string;
+    stackId: string;
+    approxTokens: number;
+    blockCount: number;
+    chars: number;
+    deltaTokens?: number;
+    prefixTokens?: number;
+    prefixRatio?: number;
+    changedBlocks?: number;
+    usage?: ContextDiffProviderUsage;
+}
+export interface ContextDiffView {
+    turns: ContextDiffTurnSummary[];
+    latest: {
+        turn: TurnSnapshot;
+        diff: TurnDiff;
+        usage?: ContextDiffProviderUsage;
+    } | null;
+    latestDiff: TurnDiff | null;
+}
+export declare function createContextDiffHistory(): ContextDiffHistory;
+/** Append a captured payload, evict old turns past the limit, and compute the latest diff. */
+export declare function appendContextDiffCapture(history: ContextDiffHistory, capture: ContextDiffCapture): TurnDiff | undefined;
+/** Attach the authoritative usage returned on the assistant message for one captured provider request. */
+export declare function attachContextDiffUsage(history: ContextDiffHistory, turnId: string, usage: ContextDiffProviderUsageInput): boolean;
+/** Build the response-shaped view: compact summaries for recent turns + latest full diff. */
+export declare function getContextDiffView(history: ContextDiffHistory): ContextDiffView;
+//# sourceMappingURL=context-diff-history.d.ts.map

package/dist/context-diff-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-diff-history.d.ts","sourceRoot":"","sources":["../src/context-diff-history.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAA+B,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAClG,OAAO,EAAuB,KAAK,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAE1F,eAAO,MAAM,0BAA0B,KAAK,CAAC;AAE7C,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,UAAU,CAAC,EAAE,QAAQ,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,wBAAwB,CAAC,CAAC;IACrD,oBAAoB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,6BAA6B;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,wBAAyB,SAAQ,6BAA6B;IAC9E,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,WAAW,EAAE,UAAU,GAAG,cAAc,CAAC;CACzC;AAED,MAAM,WAAW,sBAAsB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,KAAK,CAAC,EAAE,wBAAwB,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC/B,KAAK,EAAE,sBAAsB,EAAE,CAAC;IAChC,MAAM,EAAE;QAAE,IAAI,EAAE,YAAY,CAAC;QAAC,IAAI,EAAE,QAAQ,CAAC;QAAC,KAAK,CAAC,EAAE,wBAAwB,CAAA;KAAE,GAAG,IAAI,CAAC;IACxF,UAAU,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC5B;AAED,wBAAgB,wBAAwB,IAAI,kBAAkB,CAO7D;AAED,8FAA8F;AAC9F,wBAAgB,wBAAwB,CACvC,OAAO,EAAE,kBAAkB,EAC3B,OAAO,EAAE,kBAAkB,GACzB,QAAQ,GAAG,SAAS,CAiBtB;AAED,0GAA0G;AAC1G,wBAAgB,sBAAsB,CACrC,OAAO,EAAE,kBAAkB,EAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,6BAA6B,GAClC,OAAO,CAcT;AAED,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,GAAG,eAAe,CA0B/E"}

package/dist/context-diff-history.js

@@ -0,0 +1,84 @@
+/**
+ * Host-neutral rolling context-diff history.
+ *
+ * Keeps the last N turn snapshots captured from provider payloads and exposes
+ * the latest engine-computed diff plus compact summaries for recent turns.
+ */
+import { diffTurns, turnApproxTokens } from "./context-diff.js";
+import { extractTurnSnapshot } from "./context-diff-snapshot.js";
+export const CONTEXT_DIFF_HISTORY_LIMIT = 20;
+export function createContextDiffHistory() {
+    return {
+        turns: [],
+        nextTurnNumber: 1,
+        usageByTurnId: new Map(),
+        cacheReportingModels: new Set(),
+    };
+}
+/** Append a captured payload, evict old turns past the limit, and compute the latest diff. */
+export function appendContextDiffCapture(history, capture) {
+    const nextTurnNumber = history.nextTurnNumber ?? 1;
+    const turnId = capture.turnId ?? `turn-${nextTurnNumber}`;
+    history.nextTurnNumber = nextTurnNumber + 1;
+    const snapshot = extractTurnSnapshot({
+        ...capture,
+        turnId,
+    });
+    const previous = history.turns.at(-1);
+    history.turns.push(snapshot);
+    if (history.turns.length > CONTEXT_DIFF_HISTORY_LIMIT) {
+        const evicted = history.turns.shift();
+        if (evicted)
+            history.usageByTurnId.delete(evicted.turnId);
+    }
+    const diff = diffTurns(previous, snapshot);
+    history.latestDiff = diff;
+    return diff;
+}
+/** Attach the authoritative usage returned on the assistant message for one captured provider request. */
+export function attachContextDiffUsage(history, turnId, usage) {
+    if (!history.turns.some((turn) => turn.turnId === turnId))
+        return false;
+    const modelKey = `${usage.provider}/${usage.model}`;
+    const currentReportsCache = usage.cacheRead > 0 || usage.cacheWrite > 0;
+    const cacheReported = currentReportsCache || history.cacheReportingModels.has(modelKey);
+    if (currentReportsCache)
+        history.cacheReportingModels.add(modelKey);
+    const promptTokens = usage.input + usage.cacheRead + usage.cacheWrite;
+    history.usageByTurnId.set(turnId, {
+        ...usage,
+        promptTokens,
+        cacheHitRatio: cacheReported && promptTokens > 0 ? usage.cacheRead / promptTokens : null,
+        cacheStatus: cacheReported ? "reported" : "not-reported",
+    });
+    return true;
+}
+/** Build the response-shaped view: compact summaries for recent turns + latest full diff. */
+export function getContextDiffView(history) {
+    const turns = history.turns.map((turn, index) => {
+        const previous = index > 0 ? history.turns[index - 1] : undefined;
+        const diff = diffTurns(previous, turn);
+        return {
+            turnId: turn.turnId,
+            capturedAt: turn.capturedAt,
+            stackId: turn.stackId,
+            approxTokens: turnApproxTokens(turn),
+            blockCount: turn.blocks.length,
+            chars: turn.blocks.reduce((sum, block) => sum + block.chars, 0),
+            deltaTokens: diff.deltaTokens,
+            prefixTokens: diff.prefixTokens,
+            prefixRatio: diff.prefixRatio,
+            changedBlocks: diff.summary.changedBlocks,
+            usage: history.usageByTurnId.get(turn.turnId),
+        };
+    });
+    const latest = history.turns.length > 0 && history.latestDiff
+        ? {
+            turn: history.turns[history.turns.length - 1],
+            diff: history.latestDiff,
+            usage: history.usageByTurnId.get(history.turns[history.turns.length - 1].turnId),
+        }
+        : null;
+    return { turns, latest, latestDiff: history.latestDiff ?? null };
+}
+//# sourceMappingURL=context-diff-history.js.map

package/dist/context-diff-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-diff-history.js","sourceRoot":"","sources":["../src/context-diff-history.ts"],"names":[],"mappings":"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"}

package/dist/context-diff-snapshot.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Host-neutral snapshot extraction from captured provider payloads.
+ *
+ * This module stays free of Node/DOM/Vue APIs so the same extraction logic can
+ * be reused by the web host and future non-web surfaces.
+ */
+import { type TurnSnapshot } from "./context-diff.ts";
+export interface ContextDiffCapture {
+    turnId?: string;
+    capturedAt: string;
+    stackId?: string;
+    payload?: unknown;
+    /** Secret-redacted, complete provider-request JSON used for diff identity. */
+    serializedPayload?: string;
+    text: string;
+}
+/** Convert a captured provider payload into an ordered TurnSnapshot of Blocks. */
+export declare function extractTurnSnapshot(capture: ContextDiffCapture): TurnSnapshot;
+//# sourceMappingURL=context-diff-snapshot.d.ts.map

package/dist/context-diff-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-diff-snapshot.d.ts","sourceRoot":"","sources":["../src/context-diff-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAyD,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAE7G,MAAM,WAAW,kBAAkB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8EAA8E;IAC9E,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,IAAI,EAAE,MAAM,CAAC;CACb;AAED,kFAAkF;AAClF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,kBAAkB,GAAG,YAAY,CAO7E"}

package/dist/context-diff-snapshot.js

@@ -0,0 +1,146 @@
+/**
+ * Host-neutral snapshot extraction from captured provider payloads.
+ *
+ * This module stays free of Node/DOM/Vue APIs so the same extraction logic can
+ * be reused by the web host and future non-web surfaces.
+ */
+import { createBlock, createTurnSnapshot, hashText } from "./context-diff.js";
+/** Convert a captured provider payload into an ordered TurnSnapshot of Blocks. */
+export function extractTurnSnapshot(capture) {
+    return createTurnSnapshot({
+        turnId: capture.turnId ?? capture.capturedAt,
+        capturedAt: capture.capturedAt,
+        stackId: capture.stackId ?? "",
+        blocks: extractBlocks(capture),
+    });
+}
+function extractBlocks(capture) {
+    const serializedPayload = parseSerializedPayload(capture.serializedPayload);
+    const payload = serializedPayload === undefined ? capture.payload : serializedPayload;
+    if (!isPlainObject(payload)) {
+        return [createBlock("payload-text", "payload", capture.text, capture.serializedPayload === undefined ? undefined : {
+                section: "payload",
+                serializedPayload: capture.serializedPayload,
+            })];
+    }
+    const blocks = [];
+    const messageKeyCounts = new Map();
+    for (const [key, value] of Object.entries(payload)) {
+        if (key === "system") {
+            blocks.push(createSystemBlock(value));
+            continue;
+        }
+        if (key === "messages" && Array.isArray(value) && value.length > 0) {
+            for (const message of value) {
+                const text = messageToText(message);
+                const role = messageRole(message);
+                const baseKey = `message-${keyPart(role)}-${hashText(`${role}\u0000${text}`).slice(0, 8)}`;
+                const occurrence = messageKeyCounts.get(baseKey) ?? 0;
+                messageKeyCounts.set(baseKey, occurrence + 1);
+                const messageKey = occurrence === 0 ? baseKey : `${baseKey}-${occurrence + 1}`;
+                blocks.push(createBlock(messageKey, role, text, {
+                    section: "messages",
+                    value: message,
+                }));
+            }
+            continue;
+        }
+        blocks.push(createRequestFieldBlock(key, value));
+    }
+    if (blocks.length > 0)
+        return blocks;
+    return [createBlock("payload", "payload", stringify(payload), {
+            section: "payload",
+            value: payload,
+        })];
+}
+function createRequestFieldBlock(key, value) {
+    return createBlock(`request-${key}`, "request", stringify({ [key]: value }, 2), {
+        section: "request",
+        field: key,
+        value,
+    });
+}
+function createSystemBlock(value) {
+    if (typeof value === "string") {
+        return createBlock("system", "system", value, {
+            section: "system",
+            value,
+        });
+    }
+    if (Array.isArray(value)) {
+        const systemText = contentBlocksToText(value);
+        return createBlock("system", "system", systemText || stringify(value), {
+            section: "system",
+            value,
+        });
+    }
+    return createBlock("system", "system", stringify(value), {
+        section: "system",
+        value,
+    });
+}
+function messageRole(message) {
+    return isPlainObject(message) && typeof message.role === "string" && message.role.length > 0
+        ? message.role
+        : "message";
+}
+function keyPart(value) {
+    const part = value.replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "");
+    return part || "message";
+}
+function parseSerializedPayload(serializedPayload) {
+    if (serializedPayload === undefined)
+        return undefined;
+    try {
+        return JSON.parse(serializedPayload);
+    }
+    catch {
+        return undefined;
+    }
+}
+function stringify(value, space = 0) {
+    try {
+        const result = JSON.stringify(value, null, space);
+        return result === undefined ? String(value) : result;
+    }
+    catch {
+        return String(value);
+    }
+}
+function messageToText(message) {
+    if (typeof message === "string")
+        return message;
+    if (!isPlainObject(message))
+        return stringify(message);
+    const content = message.content;
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content))
+        return contentBlocksToText(content);
+    return stringify(message);
+}
+function contentBlocksToText(content) {
+    if (!Array.isArray(content))
+        return typeof content === "string" ? content : "";
+    const parts = [];
+    for (const part of content) {
+        if (isPlainObject(part) && typeof part.text === "string") {
+            parts.push(part.text);
+        }
+        else if (isPlainObject(part) && part.type === "image") {
+            parts.push("[image content]");
+        }
+        else if (typeof part === "string") {
+            parts.push(part);
+        }
+        else if (part !== undefined && part !== null) {
+            parts.push(stringify(part));
+        }
+    }
+    return parts.join("\n").trim();
+}
+function isPlainObject(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+//# sourceMappingURL=context-diff-snapshot.js.map

package/dist/context-diff-snapshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-diff-snapshot.js","sourceRoot":"","sources":["../src/context-diff-snapshot.ts"],"names":[],"mappings":"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"}

package/dist/context-diff.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Host-neutral context diff engine.
+ *
+ * Pure functions only: no DOM, no Vue, no Node APIs. Consecutive turn
+ * snapshots are compared with a simple prefix-walk that models KV-cache
+ * reuse without attempting a full Myers diff.
+ */
+export interface Block {
+    key: string;
+    role: string;
+    text: string;
+    chars: number;
+    approxTokens: number;
+    hash: string;
+}
+export interface TurnSnapshot {
+    turnId: string;
+    capturedAt: string;
+    stackId: string;
+    blocks: Block[];
+}
+export type DiffBlockStatus = "same" | "added" | "removed" | "modified";
+export interface DiffBlock {
+    status: DiffBlockStatus;
+    before?: Block;
+    after?: Block;
+    tokenDelta: number;
+}
+export interface TurnDiffSummary {
+    sameBlocks: number;
+    addedBlocks: number;
+    removedBlocks: number;
+    modifiedBlocks: number;
+    changedBlocks: number;
+    /** Net tokens introduced by added or lengthened modified blocks. */
+    addedTokens: number;
+    /** Net tokens removed by removed or shortened modified blocks. */
+    removedTokens: number;
+    /** Net total token change (`addedTokens - removedTokens`). */
+    netTokens: number;
+}
+export interface TurnDiff {
+    blocks: DiffBlock[];
+    prefixTokens: number;
+    prefixRatio: number;
+    deltaTokens: number;
+    summary: TurnDiffSummary;
+}
+/** Estimate tokens from characters using the same chars/4 approximation as payload capture. */
+export declare function estimateApproxTokens(text: string): number;
+/** Pure string hash used as the block identity shortcut. */
+export declare function hashText(text: string): string;
+export declare function createBlock(key: string, role: string, text: string, serialized?: unknown): Block;
+export declare function createTurnSnapshot(input: {
+    turnId: string;
+    capturedAt?: string;
+    stackId?: string;
+    blocks?: Block[];
+}): TurnSnapshot;
+export declare function turnApproxTokens(turn: TurnSnapshot): number;
+/**
+ * Diff two consecutive turn snapshots.
+ *
+ * The cache-boundary walk compares block arrays positionally while hashes
+ * match. This preserves the serialized-prefix meaning even when a later
+ * block is moved. Classification uses stable block keys after the boundary so
+ * a middle insertion does not make every following block look modified.
+ */
+export declare function diffTurns(previous: TurnSnapshot | null | undefined, current: TurnSnapshot): TurnDiff;
+//# sourceMappingURL=context-diff.d.ts.map

package/dist/context-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-diff.d.ts","sourceRoot":"","sources":["../src/context-diff.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,KAAK;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,YAAY;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,KAAK,EAAE,CAAC;CAChB;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,CAAC;AAExE,MAAM,WAAW,SAAS;IACzB,MAAM,EAAE,eAAe,CAAC;IACxB,MAAM,CAAC,EAAE,KAAK,CAAC;IACf,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC/B,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,oEAAoE;IACpE,WAAW,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,aAAa,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,QAAQ;IACxB,MAAM,EAAE,SAAS,EAAE,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,eAAe,CAAC;CACzB;AAED,+FAA+F;AAC/F,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED,4DAA4D;AAC5D,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAO7C;AAED,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,OAAO,GAAG,KAAK,CAahG;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;CACjB,GAAG,YAAY,CAOf;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAG3D;AA+KD;;;;;;;GAOG;AACH,wBAAgB,SAAS,CACxB,QAAQ,EAAE,YAAY,GAAG,IAAI,GAAG,SAAS,EACzC,OAAO,EAAE,YAAY,GACnB,QAAQ,CAwCV"}