pi-midcompact 0.5.2 → 0.6.0

package/README.md

@@ -55,7 +55,7 @@ The raw session JSONL still contains:
 
 ### A reviewed draft can reclaim meaningful context
 
-The earlier browser and TUI captures below illustrate a draft with **2 ranges** covering **42 of 73 atoms**, while the other 31 atoms remain verbatim. The current UI reports Pi-provided anchor usage separately from factual content chars and image counts; it does not derive projected token savings from local character estimates. Click either image to open it at full resolution.
+The earlier browser and TUI captures below illustrate a draft with **2 ranges** covering **42 of 73 atoms**, while the other 31 atoms remain verbatim. The current UI reports Pi-provided anchor usage as the baseline and derives a **display-only** projection of post-commit usage from documented char-class assumptions (labeled `est.`, shown as a range, never used for gating); factual content chars and image counts stay alongside it. Click either image to open it at full resolution.
 
 <p align="center">
   <a href="./figures/review-webui.png">
@@ -222,6 +222,23 @@ Enter/Esc/q        close
 
 The extension shows planning status in Pi's footer only while a transaction is active. It disappears after commit or abort.
 
+## Web UI Development
+
+From a source checkout, run the browser workbench against in-memory fixtures
+without starting Pi:
+
+```bash
+npm run dev:webui
+npm run dev:webui -- --port=4180 --no-open
+```
+
+The command opens a fixture router for `review-ready`, `review-pending`,
+`selection-mixed`, `no-telemetry`, and `wide-content`. Each button opens an
+isolated workbench with its own in-memory draft. Fixture pages survive browser
+refresh and the page's Close action, reload HTML changes automatically, and
+restart for imported TypeScript changes. Stop the router with `Ctrl+C`. Use
+`dev/midcompact-debug-ui.ts` only when validating against an actual Pi session.
+
 ## Guarantees and Limits
 
 - **Original history is retained.** Compression changes what later model requests see, not the stored Pi messages.

package/README.zh-CN.md

@@ -55,7 +55,7 @@ Pi 内置的 `/compact` 可理解为**前缀压缩**（prefix compaction）：
 
 ### 实际压缩效果
 
-下面的早期浏览器和 TUI 截图展示了一份包含 **2 个区段**、覆盖 **73 个 atom 中 42 个**的草案，其余 31 个 atom 保留原文。当前 UI 会把 Pi 提供的锚点 usage 与扩展统计的 content chars、图片数量分开显示，不再根据本地字符估算推导预计 token 节省量。点击图片可查看原图。
+下面的早期浏览器和 TUI 截图展示了一份包含 **2 个区段**、覆盖 **73 个 atom 中 42 个**的草案，其余 31 个 atom 保留原文。当前 UI 以 Pi 上报的锚点 usage 为基线，并根据文档化的字符分类假设推导**仅供展示**的 commit 后占用预计（标注 `est.`、以区间呈现、绝不参与门禁）；事实性的 content chars 与图片数量仍然并列展示。点击图片可查看原图。
 
 <p align="center">
   <a href="./figures/review-webui.png">
@@ -222,6 +222,21 @@ Enter/Esc/q        关闭
 
 扩展只在事务进行期间在 Pi 页脚显示规划状态；提交或放弃后会自动清除。
 
+## Web UI 开发
+
+在源码 checkout 中，无需启动 Pi 即可用内存 fixture 运行浏览器工作台：
+
+```bash
+npm run dev:webui
+npm run dev:webui -- --port=4180 --no-open
+```
+
+命令会打开一个 fixture router，其中包含 `review-ready`、`review-pending`、
+`selection-mixed`、`no-telemetry` 和 `wide-content`。每个按钮都会打开一套独立的
+工作台和内存草案。刷新浏览器或点击 Close 不会终止 fixture；HTML 修改会自动刷新
+页面，导入的 TypeScript 修改会触发进程重启。用 `Ctrl+C` 停止 router。只有在验证
+真实 Pi 会话集成时，才需要使用 `dev/midcompact-debug-ui.ts`。
+
 ## 保证与限制
 
 - **保留原始历史。** 压缩只改变后续模型请求看到的内容，不改写存储的 Pi 消息。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-midcompact",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Branch-aware mid-context compression for the Pi coding agent",
   "author": "frostime",
   "repository": {
@@ -32,7 +32,8 @@
   ],
   "scripts": {
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "rm -rf .test-dist && tsc -p tsconfig.test.json && node test/install-mocks.mjs && node --test test/core.test.mjs test/runtime-start.test.mjs test/runtime-agent.test.mjs test/runtime-user.test.mjs test/runtime-transaction.test.mjs test/runtime-lock.test.mjs",
+    "dev:webui": "tsx watch dev/review-webui-preview.ts",
+    "test": "rm -rf .test-dist && tsc -p tsconfig.test.json && node test/install-mocks.mjs && node --test test/schema-contract.test.mjs test/core.test.mjs test/runtime-start.test.mjs test/runtime-agent.test.mjs test/runtime-user.test.mjs test/runtime-transaction.test.mjs test/runtime-lock.test.mjs && node test/review-webui-dom.test.mjs",
     "typecheck:contract": "tsc -p tsconfig.test.json --noEmit",
     "pack:check": "npm pack --dry-run"
   },
@@ -45,6 +46,7 @@
     "@earendil-works/pi-ai": "^0.84.1",
     "@earendil-works/pi-coding-agent": "^0.84.1",
     "typescript": "^5.9.3",
+    "tsx": "^4.23.13",
     "@earendil-works/pi-tui": "^0.84.1"
   },
   "pi": {

package/skills/midcompact/SKILL.md

@@ -12,8 +12,8 @@ This skill handles two independent tasks: planning compression and recalling com
 | Signal | Immediate duty | First action |
 |--------|----------------|--------------|
 | Runtime prompt says `FINAL STATE: USER MANUAL` | Let the user create the initial DraftPlan | Reply exactly `OK`; call no midcompact tool |
-| Runtime prompt says `FINAL STATE: AGENT DIRECT` | Start from the new empty draft | `action="inspect"` |
-| A handoff reports a persisted DraftPlan and the user asks to continue | Read the shared selection and determine what help the user wants | `action="plan", op="show"` |
+| Runtime prompt says `FINAL STATE: AGENT DIRECT` | Start from the new empty draft | `request={action:"inspect"}` |
+| A handoff reports a persisted DraftPlan and the user asks to continue | Read the shared selection and determine what help the user wants | `request={action:"plan", op:"show"}` |
 | The user or a projected summary needs detail from a committed block | Retrieve that history only | Follow **Recall workflow** |
 
 The state-specific runtime prompt is authoritative. Recall does not enter planning or mutate the DraftPlan. During the User-manual acknowledgement turn, the no-tool instruction overrides every other route.
@@ -34,7 +34,7 @@ Apply one invariant:
 
 #### 1. Read the entry state and user intent
 
-For a fresh Agent-direct transaction, begin with `action="inspect"`. For a handed-off DraftPlan, begin with `action="plan", op="show"`; inspect the anchor only if the requested work needs broader context.
+For a fresh Agent-direct transaction, begin with `request={action:"inspect"}`. For a handed-off DraftPlan, begin with `request={action:"plan", op:"show"}`; inspect the anchor only if the requested work needs broader context.
 
 Establish the user's desired scope, fidelity, and planning effort from their words, current selection, `User focus: ...`, and surrounding interaction. Treat answers collected through question, questionnaire, or similar tools as user-originated input even when represented as tool results.
 
@@ -71,7 +71,7 @@ When treatments involve a meaningful tradeoff, present concise alternatives and
 
 #### 4. Resolve boundaries and build the DraftPlan
 
-After the intended treatment is clear, use `action="locate"` for targeted content and boundary checks. An atom is the smallest selectable unit; a tool call and its matching results form one indivisible `tool_exchange` atom. Keep source text outside a range when exact wording or provenance matters and a summary cannot preserve it equivalently.
+After the intended treatment is clear, use `request={action:"locate"}` for targeted content and boundary checks. An atom is the smallest selectable unit; a tool call and its matching results form one indivisible `tool_exchange` atom. Keep source text outside a range when exact wording or provenance matters and a summary cannot preserve it equivalently.
 
 Choose boundaries from the information that must survive, not from a fixed category. A range may replace a whole semantic phase, including its initiating and concluding messages. It may instead retain a load-bearing user instruction and concluding Agent response while replacing only the execution between them. It may split around important material to leave KEEP holes. These are reasoning patterns, not rules tied to start mode, message age, or one prescribed kind of work.
 
@@ -107,7 +107,7 @@ Length follows the information that must survive, not a target ratio. Final test
 
 #### 6. Verify and hand off
 
-Call `action="plan", op="show"`. Check that the intended semantic phases are covered, KEEP holes remain outside ranges, every range has a summary, and the summaries conserve the future working state.
+Call `request={action:"plan", op:"show"}`. Check that the intended semantic phases are covered, KEEP holes remain outside ranges, every range has a summary, and the summaries conserve the future working state.
 
 Describe the completed proposal with the same recognizable landmarks used during alignment. Direct the user to `/midcompact:select` or `/midcompact:select-webui` for boundaries and KEEP holes, and to `/midcompact:review` or `/midcompact:review-webui` for summary inspection or rejection. Use browser variants when the TUI is unavailable or preferred. Ask the user to run `/midcompact:commit` when ready; never commit for them.
 
@@ -119,11 +119,11 @@ Recall works with or without an active planning transaction. It reads committed
 
 #### 1. Find the block
 
-If its id is unknown, call `action="recall", pattern="..."` to search active topics and summaries. A projected summary also states its block id and exact recall call.
+If its id is unknown, call `request={action:"recall", pattern:"..."}` to search active topics and summaries. A projected summary also states its block id and exact recall call.
 
 #### 2. Retrieve the detail
 
-Call `action="recall", ref="c0001"`. If the readable, structure-flattened result ends with a truncation marker, retry with `detail="full"`. Retrieve only what the current task needs; do not start or change a plan merely to recall history.
+Call `request={action:"recall", ref:"c0001"}`. If the readable, structure-flattened result ends with a truncation marker, retry with `detail="full"`. Retrieve only what the current task needs; do not start or change a plan merely to recall history.
 
 ## Tool conventions
 

package/skills/midcompact/references/tool-interface.md

@@ -4,11 +4,11 @@ Read this reference when exact call requirements, limits, rejection behavior, re
 
 ## Parameter grouping
 
-The tool schema is a discriminated union on `action`: selecting an action admits exactly the fields documented in that action's section, and no fields from other actions. A call that mixes actions (for example `locate` fields on `plan`) is invalid; do not repair it by dropping fields, re-issue the call with only the selected action's parameters. Shared field names (`ref`, `pattern`, `limit`, `detail`) are defined independently per action with the meaning documented in that section.
+The parameters are one object with a single `request` field; `request` is a discriminated union where each branch binds one `action` value to exactly that action's fields and is closed (`additionalProperties: false`). A call that mixes actions (for example `locate` fields on `plan`) is rejected by the schema itself; do not repair it by dropping fields, re-issue the call with only the selected action's parameters. Shared field names (`ref`, `pattern`, `limit`, `detail`) are defined independently per action with the meaning documented in that section.
 
 ## Inspect
 
-Without `spans`, `action="inspect"` inventories the frozen anchor. It returns factual structure and bounded user landmarks, not full message bodies, assistant/tool previews, summaries, or image base64.
+Without `spans`, `request.action="inspect"` inventories the frozen anchor. It returns factual structure and bounded user landmarks, not full message bodies, assistant/tool previews, summaries, or image base64.
 
 - `page_size`: default 20 groups, maximum 50.
 - `cursor`: opaque value returned by the previous page.
@@ -19,17 +19,17 @@ Stop paging after the candidate regions are covered.
 To compare explicit candidates without mutating the DraftPlan, pass one or more possibly overlapping spans:
 
 ```text
-midcompact(action="inspect", spans=[
+midcompact(request={action:"inspect", spans=[
   {"start":"a0006","end":"a0014"},
   {"start":"a0006","end":"a0020"}
-])
+]})
 ```
 
 Span inspection reports bounded endpoint landmarks, atom/message and role counts, tool exchanges and calls, factual content share, images, and protected/compressible counts. It has a 12,000-character total output budget and reports how many requested spans fit. It does not report per-span tokens: Pi supplies usage for the whole anchor, not token attribution by range. Do not combine `spans` with `page_size` or `cursor`.
 
 ## Locate
 
-`action="locate"` returns atoms from the frozen anchor. Supply either:
+`request.action="locate"` returns atoms from the frozen anchor. Supply either:
 
 - `ref`: one direct atom lookup; or
 - at least one real filter: `pattern`, `tool_name`, or `source` other than `any`.
@@ -42,7 +42,7 @@ A `g...` inventory ref is not a locate ref; use the group's `a...` start/end lan
 
 ## Plan
 
-`action="plan"` uses `op="show"` by default. Agent and user mutate the same DraftPlan.
+`request.action="plan"` uses `op="show"` by default. Agent and user mutate the same DraftPlan.
 
 | op | Required fields |
 |----|-----------------|
@@ -78,7 +78,7 @@ Committed blocks appear as protected atoms in later transaction snapshots and ca
 
 ## Recall
 
-`action="recall"` works independently of a planning transaction and reads committed blocks active on the current branch.
+`request.action="recall"` works independently of a planning transaction and reads committed blocks active on the current branch.
 
 - Without `ref`, `pattern` searches block topics and summaries; `limit` defaults to 8 and has a maximum of 20.
 - With `ref="c0001"`, the tool renders that block's stored messages.

package/src/SPEC.md

@@ -0,0 +1,116 @@
+# SPEC — midcompact extension module (`src/`)
+
+Maintenance contract for `src/`. The model-facing usage contract lives in
+`skills/midcompact/` (SKILL.md + references/tool-interface.md) and is
+authoritative for observable tool/command behavior; this spec records the
+durable invariants a future maintainer must preserve, which are not reliably
+inferable from code at a glance. Entry point: `src/index.ts` (factory in
+package.json → `pi.extensions`).
+
+## Persistence
+
+- Exactly three custom entry types are ever persisted on the session branch:
+  `midcompact-transaction`, `midcompact-draft`, `midcompact-state`
+  (`state.ts`). All are `version: 1`, shape-checked before use.
+- Restore is *latest entry wins* over the branch. A draft restores only when
+  a transaction entry precedes it with a matching `transactionId`; the two
+  form one unit. State entries are independent of transactions.
+- Commit appends a new state entry — never mutates old ones. Abort writes
+  nothing.
+- Compatibility is a standing constraint: old transactions without
+  `startMode` default to `"agent"`; old ranges lacking factual char/image
+  fields are coerced (`coerceDraftRange`). Legacy `approxTokens` fields are
+  deprecated: never authoritative for decisions or UI.
+- The planning lock is deliberately not persisted: reload clears the owner.
+
+## Transactions
+
+- Start freezes the current leaf as anchor, appends TXN + DRAFT, and routes
+  Agent-direct or User-manual. All planning happens on the child branch; the
+  discussion never enters the working context.
+- Commit and abort both navigate back to the anchor (`navigateTree`); commit
+  then appends state, abort appends nothing. Both refuse to run while the
+  Agent holds the planning lock.
+- `anchorUsage` is informational only — Pi-reported awareness, never an
+  optimization target. The web workbench may additionally render a
+  **display-level** post-commit projection derived from the documented
+  char-class assumption table in `content-metrics` (`TOKEN_ESTIMATE`): always
+  labeled `est.`, shown as a propagated band, and never feeding commit
+  gating, range validation, or any decision (same rule as `projectedTokens`
+  / `approxTokens`).
+- Atom refs are transaction-local: re-run inspect/locate in a later
+  transaction; group refs (`g...`) are never locate refs.
+
+## Projection
+
+- While blocks are active, the context hook replaces committed blocks with
+  their summary wrapper. The original history is restored only by recall;
+  recall never re-projects. Committed blocks appear as protected atoms in
+  later snapshots (no double compression).
+
+## Atoms and ranges
+
+- The atom is the smallest selectable unit; a tool call plus its matching
+  results is one indivisible `tool_exchange` atom.
+- Protected (never compressible): incomplete/orphaned tool protocol,
+  existing compressed blocks, unsupported message kinds, entries lacking
+  the persistent anchor entry.
+- Draft ranges never overlap and never contain protected atoms; boundaries
+  cannot be updated in place (remove + re-add). Empty `summary` = pending;
+  commit rejects pending, reversed, overlapping, or protected-crossing
+  ranges. `KEEP` is expressed by leaving atoms outside all ranges.
+
+## Concurrency
+
+- One runtime mutex over DraftPlan edits: owner ∈ {agent, ui}. Agent turns
+  hold it for their whole lifetime (`agent_start` → `agent_settled`); UIs
+  hold it per session via the `midcompactPlanningLock` API object (exposed
+  for UI and tests).
+- Blocked operations notify and return — there is no queue.
+
+## External contracts (reference, don't duplicate)
+
+- Tool: one `midcompact` tool whose parameters are `{ request: <union> }` —
+  a root `type: "object"` wrapping a discriminated union on `action`
+  (inspect/locate/plan/recall); each branch is closed
+  (`additionalProperties: false`), so cross-action parameters are
+  schema-rejected. The `request` wrapper exists because some providers
+  (e.g. DeepSeek) reject a root-level `anyOf` before the model sees the
+  schema.
+  Details: `skills/midcompact/references/tool-interface.md`.
+- Commands: `midcompact:start|abort|commit|review|review-webui|select|select-webui|status`;
+  no composite `/midcompact`; native naming convention `name:sub` (Pi's
+  `skill:<name>`).
+- The tool never starts a transaction and never commits; both are command-
+  or user-gated. Recall is the only action valid without a transaction.
+- Web workbench (`review-webui.html` + `review-webui.ts`): the state payload
+  carries per-atom char-class counts (`narrowChars`/`wideChars`), per-range
+  replacement char-class counts (including the actual wrapper), and the
+  assumption table (`est`), so the page renders the projection band and can
+  update estimates while a summary is edited; `GET /api/atom/:ref` serves the
+  frozen atom's full text for the original-text drawer (read-only, snapshot-local).
+  `startReviewWebUiServer` owns the Pi-independent loopback HTTP contract;
+  `showReviewWebUi` adapts it to Pi notification, browser launch, and page-bound
+  lifetime. Development may opt into a persistent server without changing the
+  production defaults.
+  User-facing copy says "can't compress" for protected atoms; "protected"
+  stays the agent/tool-side term.
+  Page invariants that broke once and must hold: the `<!--MIDCOMPACT_STATE-->`
+  script tag is the server's template injection point (renaming it breaks
+  state loading); `selectionRefs` initialization depends on helpers defined
+  later in the page script (order is load-bearing, TDZ); `gbody` visibility
+  is driven by the render-time `hidden` attribute, so collapse handlers must
+  sync that attribute, not just a class.
+
+## Change rules
+
+- Adding a tool action → new request branch + handler type + tool-interface
+  section + SKILL.md routing; adding parameters to an action → its branch
+  only (the union stays nested under `request`).
+- Changing persistence shapes → keep `version: 1` readable (coerce) or add
+  a migration; restore predicates (`state.ts`) are the compatibility gate.
+- Renaming commands → update SKILL.md/README/tests together; the stale-name
+  failure mode is a doc-arbitrated contract violation.
+- Test seams: `setOpenReviewWebBrowser` and the mocks in `test/` must stay
+  behavior-faithful to the real extension API; suites drive commands via
+  `pi.commands.get(...)` and the tool via plain param objects.

package/src/content-metrics.ts

@@ -1,6 +1,8 @@
-// Sole owner of factual message content statistics. Never converts local char or
-// image byte counts into token claims. Image base64 never contributes to text
-// char counts.
+// Sole owner of message content statistics. Factual char/image counts are the
+// authority; the only token conversion allowed is the explicitly scoped,
+// display-level estimator at the bottom of this file (web UI presentation
+// only — it never gates decisions, commits, or range validity). Image base64
+// never contributes to text char counts.
 
 import type { ContentMetrics, ImageFact, MessageLike } from "./types.js";
 
@@ -183,3 +185,73 @@ export function aggregateMetrics(parts: readonly ContentMetrics[]): ContentMetri
   }
   return { contentChars, imageCount, images };
 }
+
+// ---- Display-level token estimation (web UI presentation only) ----
+//
+// The web UI shows a projected post-commit usage band. Because the consumer
+// model is provider-dependent, tokens are estimated from char classes with a
+// documented assumption table instead of a real tokenizer: the [low, high]
+// pairs express published tokenizer spread and are propagated as a band, never
+// collapsed into a single authoritative number. The band is derived from the
+// content mix of the atoms involved (ASCII-heavy content lands near the tight
+// end, CJK-heavy near the wide end). Nothing here feeds commit gating, range
+// validation, or any decision.
+
+/** Per-char-class token-cost assumptions: [low, high] tokens per char. */
+export const TOKEN_ESTIMATE = {
+  /** ASCII/code: roughly 3.3–4.5 chars per token across common tokenizers. */
+  narrowTokPerChar: [0.22, 0.3],
+  /** Non-ASCII scripts (CJK, kana, hangul, emoji, …): the dominant spread. */
+  wideTokPerChar: [0.5, 1.0],
+  /** Images: provider- and resolution-dependent flat allowance. */
+  imageTok: [700, 1600],
+} as const;
+
+/** Char classes the estimator distinguishes. */
+export interface CharMix {
+  /** ASCII code points. */
+  narrowChars: number;
+  /** Everything non-ASCII (counted conservatively at the wide rate). */
+  wideChars: number;
+}
+
+// Classification is deliberately coarse: ASCII is estimated at the narrow
+// rate; every non-ASCII code point (CJK, kana, hangul, emoji, Cyrillic, …) is
+// counted at the wide rate, which is the conservative side for CJK-heavy
+// content and keeps the table honest without per-script modeling.
+
+/** Split a text into narrow (ASCII) and wide (everything else) code points. */
+export function charClassCounts(text: string): CharMix {
+  let narrowChars = 0;
+  let wideChars = 0;
+  for (const ch of text) {
+    const cp = ch.codePointAt(0)!;
+    if (cp <= 0x7f) {
+      narrowChars += 1;
+      continue;
+    }
+    wideChars += 1;
+  }
+  return { narrowChars, wideChars };
+}
+
+export interface TokenEstimate {
+  point: number;
+  low: number;
+  high: number;
+}
+
+/** Estimate tokens for a char mix plus images, as a propagated band. */
+export function estimateTokens(mix: CharMix, imageCount: number): TokenEstimate {
+  const [aLo, aHi] = TOKEN_ESTIMATE.narrowTokPerChar;
+  const [cLo, cHi] = TOKEN_ESTIMATE.wideTokPerChar;
+  const [iLo, iHi] = TOKEN_ESTIMATE.imageTok;
+  const mid = (lo: number, hi: number) => (lo + hi) / 2;
+  return {
+    point: Math.round(mix.narrowChars * mid(aLo, aHi)
+      + mix.wideChars * mid(cLo, cHi)
+      + imageCount * mid(iLo, iHi)),
+    low: Math.round(mix.narrowChars * aLo + mix.wideChars * cLo + imageCount * iLo),
+    high: Math.round(mix.narrowChars * aHi + mix.wideChars * cHi + imageCount * iHi),
+  };
+}

package/src/index.ts

@@ -67,55 +67,79 @@ const TOOL_DESCRIPTION =
 const STATUS_KEY = "midcompact";
 const START_PROMPT_PREFIX = "A mid-compaction transaction is active on a frozen anchor snapshot.";
 
-// The tool is a discriminated union: `action` selects the only parameter
-// group that applies. The schema exposes just that group's fields, so a call
-// cannot mix parameters from different actions, and cross-action misuse
-// becomes a compile-time error in the handler types rather than a runtime rule.
-const InspectParams = Type.Object({
-  action: Type.Literal("inspect"),
-  // inventory pagination or explicit candidate-span measurement
-  spans: Type.Optional(Type.Array(Type.Object({ start: Type.String(), end: Type.String() }))),
-  page_size: Type.Optional(Type.Number()),
-  cursor: Type.Optional(Type.String()),
-});
-
-const LocateParams = Type.Object({
-  action: Type.Literal("locate"),
-  ref: Type.Optional(Type.String()),
-  pattern: Type.Optional(Type.String()),
-  source: Type.Optional(StringEnum(["any", "user", "assistant", "tool_call", "tool_result"] as const)),
-  tool_name: Type.Optional(Type.String()),
-  direction: Type.Optional(StringEnum(["oldest", "newest"] as const)),
-  limit: Type.Optional(Type.Number()),
-  detail: Type.Optional(StringEnum(["brief", "full"] as const)),
-});
-
-const PlanParams = Type.Object({
-  action: Type.Literal("plan"),
-  op: Type.Optional(StringEnum(["show", "add", "update", "remove"] as const)),
-  start: Type.Optional(Type.String()),
-  end: Type.Optional(Type.String()),
-  draft_id: Type.Optional(Type.String()),
-  topic: Type.Optional(Type.String()),
-  summary: Type.Optional(Type.String()),
-  detail: Type.Optional(StringEnum(["brief", "full"] as const)),
-});
-
-const RecallParams = Type.Object({
-  action: Type.Literal("recall"),
-  ref: Type.Optional(Type.String()),
-  pattern: Type.Optional(Type.String()),
-  limit: Type.Optional(Type.Number()),
-  detail: Type.Optional(StringEnum(["brief", "full"] as const)),
-});
-
-const Params = Type.Union([InspectParams, LocateParams, PlanParams, RecallParams]);
-
-type ParamsType = Static<typeof Params>;
-type InspectParamsType = Static<typeof InspectParams>;
-type LocateParamsType = Static<typeof LocateParams>;
-type PlanParamsType = Static<typeof PlanParams>;
-type RecallParamsType = Static<typeof RecallParams>;
+// Canonical request model: one branch per action, and each branch owns exactly
+// its own fields (additionalProperties: false). The discriminant is a
+// single-value StringEnum instead of Type.Literal so it serializes as
+// string+enum, which restricted JSON-Schema subsets (e.g. DeepSeek) accept
+// more readily than const.
+//
+// The union sits under a root `request` property instead of being the
+// parameters root: some providers validate that a tool's parameters root is
+// `type: "object"` and reject a root-level anyOf before the model ever sees
+// the schema (observed on DeepSeek). Field descriptions stay in sync with
+// skills/midcompact/references/tool-interface.md.
+const InspectRequest = Type.Object(
+  {
+    action: StringEnum(["inspect"] as const, { description: "Inventory the frozen anchor, or measure explicit candidate spans." }),
+    spans: Type.Optional(Type.Array(Type.Object({ start: Type.String(), end: Type.String() }), { description: "Candidate spans to measure, as {start,end} atom refs." })),
+    page_size: Type.Optional(Type.Number({ description: "Inventory groups per page (default 20, max 50)." })),
+    cursor: Type.Optional(Type.String({ description: "Pagination cursor from the previous page." })),
+  },
+  { additionalProperties: false },
+);
+
+const LocateRequest = Type.Object(
+  {
+    action: StringEnum(["locate"] as const, { description: "Locate atoms in the frozen anchor by ref or filters." }),
+    ref: Type.Optional(Type.String({ description: "One direct atom ref; mutually exclusive with search filters." })),
+    pattern: Type.Optional(Type.String({ description: "Content filter over anchor atoms." })),
+    source: Type.Optional(StringEnum(["any", "user", "assistant", "tool_call", "tool_result"] as const, { description: "Filter by entry source." })),
+    tool_name: Type.Optional(Type.String({ description: "Filter by originating tool name." })),
+    direction: Type.Optional(StringEnum(["oldest", "newest"] as const, { description: "Match ordering, oldest (default) or newest." })),
+    limit: Type.Optional(Type.Number({ description: "1-3 results for filtered searches." })),
+    detail: Type.Optional(StringEnum(["brief", "full"] as const, { description: "brief (default) or full atom output." })),
+  },
+  { additionalProperties: false },
+);
+
+const PlanRequest = Type.Object(
+  {
+    action: StringEnum(["plan"] as const, { description: "Show or mutate the shared DraftPlan." }),
+    op: Type.Optional(StringEnum(["show", "add", "update", "remove"] as const, { description: "show (default) / add / update / remove." })),
+    start: Type.Optional(Type.String({ description: "add: range start atom ref." })),
+    end: Type.Optional(Type.String({ description: "add: range end atom ref." })),
+    draft_id: Type.Optional(Type.String({ description: "show/update/remove: target draft range id." })),
+    topic: Type.Optional(Type.String({ description: "add/update: range topic." })),
+    summary: Type.Optional(Type.String({ description: "add/update: range summary (omitted or empty = pending range)." })),
+    detail: Type.Optional(StringEnum(["brief", "full"] as const, { description: "show: brief (default) or full range output." })),
+  },
+  { additionalProperties: false },
+);
+
+const RecallRequest = Type.Object(
+  {
+    action: StringEnum(["recall"] as const, { description: "Read committed compression blocks; works without a transaction." }),
+    ref: Type.Optional(Type.String({ description: "One committed block id, e.g. c0001; renders its messages." })),
+    pattern: Type.Optional(Type.String({ description: "Filter block topics and summaries." })),
+    limit: Type.Optional(Type.Number({ description: "Blocks to list (default 8, max 20)." })),
+    detail: Type.Optional(StringEnum(["brief", "full"] as const, { description: "full raises the rendering cap on truncated blocks." })),
+  },
+  { additionalProperties: false },
+);
+
+const Params = Type.Object(
+  { request: Type.Union([InspectRequest, LocateRequest, PlanRequest, RecallRequest]) },
+  {
+    additionalProperties: false,
+    description: "`request.action` selects exactly one request shape; fields of the other actions are not valid.",
+  },
+);
+
+type ToolParams = Static<typeof Params>;
+type InspectRequestType = Static<typeof InspectRequest>;
+type LocateRequestType = Static<typeof LocateRequest>;
+type PlanRequestType = Static<typeof PlanRequest>;
+type RecallRequestType = Static<typeof RecallRequest>;
 
 type RuntimeSnapshot = { atoms: Atom[]; anchorState?: CompressionState };
 
@@ -171,7 +195,7 @@ export default function (pi: ExtensionAPI) {
         content: [
           "An active midcompact transaction exists with a persisted DraftPlan.",
           `Draft revision ${currentDraft.revision}; ${currentDraft.ranges.length} existing range(s), which may have been created by the user.`,
-          "If the current user request asks to continue midcompact, read the `midcompact` skill first, then call midcompact(action=\"plan\", op=\"show\") before any other midcompact action. Treat the existing plan as the current shared draft. Infer from the user's request whether to preserve, refine, or extend it; ask only if materially ambiguous.",
+          "If the current user request asks to continue midcompact, read the `midcompact` skill first, then call midcompact(request={action:\"plan\", op:\"show\"}) before any other midcompact action. Treat the existing plan as the current shared draft. Infer from the user's request whether to preserve, refine, or extend it; ask only if materially ambiguous.",
         ].join("\n"),
         display: false,
       },
@@ -573,9 +597,10 @@ export default function (pi: ExtensionAPI) {
     label: "Midcompact",
     description: TOOL_DESCRIPTION,
     parameters: Params,
-    async execute(_id: string, params: ParamsType, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: ExtensionContext) {
+    async execute(_id: string, params: ToolParams, _signal: AbortSignal | undefined, _onUpdate: unknown, ctx: ExtensionContext) {
       try {
-        if (params.action === "recall") return toolResult(handleRecall(params, ctx));
+        const request = params.request;
+        if (request.action === "recall") return toolResult(handleRecall(request, ctx));
         const restored = restoreTransaction(ctx.sessionManager.getBranch() as SessionEntry[]);
         const currentTx = withCompatDefaults(restored.transaction ?? transaction);
         if (!currentTx) return toolResult("No active midcompact transaction. Ask the user to run `/midcompact:start` first.");
@@ -586,14 +611,14 @@ export default function (pi: ExtensionAPI) {
         }
         const snapshot = buildAnchorSnapshot(ctx.sessionManager, currentTx);
 
-        if (params.action === "inspect") return toolResult(handleInspect(params, snapshot.atoms, currentTx));
-        if (params.action === "locate") return toolResult(handleLocate(params, snapshot.atoms));
-        if (params.action === "plan") {
-          const result = handlePlan(params, draft!, snapshot.atoms);
+        if (request.action === "inspect") return toolResult(handleInspect(request, snapshot.atoms, currentTx));
+        if (request.action === "locate") return toolResult(handleLocate(request, snapshot.atoms));
+        if (request.action === "plan") {
+          const result = handlePlan(request, draft!, snapshot.atoms);
           if (result.op === "show") {
             return toolResult(formatDraft(draft!, draftTelemetry(transaction, draft), {
-              detail: params.detail,
-              draftId: params.draft_id,
+              detail: request.detail,
+              draftId: request.draft_id,
               atoms: snapshot.atoms,
             }));
           }
@@ -609,7 +634,7 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
-  function handleInspect(params: InspectParamsType, atoms: Atom[], tx: TransactionState): string {
+  function handleInspect(params: InspectRequestType, atoms: Atom[], tx: TransactionState): string {
     if (params.spans) {
       if (params.page_size !== undefined || params.cursor !== undefined) {
         throw new Error("inspect spans cannot be combined with inventory pagination.");
@@ -620,7 +645,7 @@ export default function (pi: ExtensionAPI) {
     return formatInventory(page);
   }
 
-  function handleRecall(params: RecallParamsType, ctx: ExtensionContext): string {
+  function handleRecall(params: RecallRequestType, ctx: ExtensionContext): string {
     const sm = ctx.sessionManager;
     const branchState = restoreCompressionState(sm.getBranch() as SessionEntry[]) ?? activeState;
     if (!branchState?.blocks.length) return "No compressed blocks are active on this branch.";
@@ -656,7 +681,7 @@ export default function (pi: ExtensionAPI) {
 
 // ---- Pure handlers ----
 
-function handleLocate(params: LocateParamsType, atoms: Atom[]): string {
+function handleLocate(params: LocateRequestType, atoms: Atom[]): string {
   const hasFilter = Boolean(params.pattern || params.tool_name || (params.source && params.source !== "any"));
   if (params.ref && hasFilter) {
     throw new Error("locate accepts either one direct ref or search filters, not both.");
@@ -688,7 +713,7 @@ type PlanHandleResult =
   | { op: "show"; draft: DraftPlan }
   | { op: "add" | "update" | "remove"; draft: DraftPlan; changedId: string };
 
-function handlePlan(params: PlanParamsType, current: DraftPlan, atoms: Atom[]): PlanHandleResult {
+function handlePlan(params: PlanRequestType, current: DraftPlan, atoms: Atom[]): PlanHandleResult {
   const op = params.op ?? "show";
   if (op === "show") return { op, draft: current };
   if (op === "remove") {