pi-midcompact 0.5.1 → 0.5.3

package/README.md

@@ -29,7 +29,7 @@ That is planning guidance, not an enforced token target: semantic importance win
 
 ### A selective projection, prepared on a temporary branch
 
-`/midcompact start` freezes the current session leaf as an **anchor**. Planning happens on a disposable child branch, so the discussion used to create and edit the draft never becomes part of the committed working context.
+`/midcompact:start` freezes the current session leaf as an **anchor**. Planning happens on a disposable child branch, so the discussion used to create and edit the draft never becomes part of the committed working context.
 
 ```text
 Frozen anchor: raw session history
@@ -42,7 +42,7 @@ Planning is isolated on a temporary branch:
   ... [latest work] ──┬── [transaction] ── [draft v1] ── [draft v2]  ◀ review / edit
                       │                    (abandoned at commit)
                       └── [midcompact-state]                         ◀ committed leaf
-                            (reviewed selection metadata, not a model message; written only by /midcompact commit)
+                            (reviewed selection metadata, not a model message; written only by /midcompact:commit)
 
 Later model requests see a selective projection:
 
@@ -91,10 +91,10 @@ pi-midcompact — mid-context compression, review, then human commit
 
 | | Pi `/compact` | `pi-midcompact` |
 | --- | --- | --- |
-| Starts | Automatically near the context limit, or with `/compact` | At an explicit natural checkpoint with `/midcompact start` |
+| Starts | Automatically near the context limit, or with `/compact` | At an explicit natural checkpoint with `/midcompact:start` |
 | Selects | One older contiguous prefix; keeps a recent token-budgeted tail | One or more reviewed ranges, including non-contiguous ranges and `KEEP` holes |
 | Planning | Optional one-shot instruction to focus the generated summary | User states scope and retention depth; the Agent discusses trade-offs and drafts selective ranges and summaries |
-| Decision gate | Generates a compaction checkpoint directly | Draft → TUI or browser review → explicit human `/midcompact commit` |
+| Decision gate | Generates a compaction checkpoint directly | Draft → TUI or browser review → explicit human `/midcompact:commit` |
 | Best fit | Automatic context maintenance and overflow recovery | Deliberate cleanup of completed phases while retaining specific decisions verbatim |
 
 `pi-midcompact` does not disable or replace Pi's automatic compaction; it gives you a separate, human-reviewed way to make selective reductions. See [Pi's compaction documentation](https://github.com/earendil-works/pi-mono/blob/main/packages/coding-agent/docs/compaction.md) for the built-in mechanism.
@@ -124,13 +124,13 @@ Start a transaction at a natural breakpoint: the current work is complete enough
 Run:
 
 ```text
-/midcompact start
+/midcompact:start
 ```
 
 Pi opens a three-way chooser before creating transaction state: **Agent direct**, **User manual**, or **Drop**. Agent direct is the first and default-highlighted option, matching the previous fast path. The chooser is the standard `select` dialog, identical in interactive and RPC mode; RPC carries it as an extension UI `select` message with a bounded timeout, so an unresponsive client cancels instead of blocking. print/JSON modes have no dialog and default to **Agent direct**. Agent direct starts the existing inventory-first Agent workflow. User manual sends the same transaction guidance with a final “acknowledge only” instruction; after the Agent replies briefly, the Selection workbench opens (browser-based outside interactive mode). It does not start planning or mutate the DraftPlan until the user hands off later. Save the initial DraftPlan, close the UI, then tell the Agent to continue when you are ready. You can include an initial focus in the same command:
 
 ```text
-/midcompact start Compress the early repository exploration, but keep user requirements verbatim.
+/midcompact:start Compress the early repository exploration, but keep user requirements verbatim.
 ```
 
 ### 2. Discuss what to compress with the Agent
@@ -150,7 +150,7 @@ The Agent locates relevant parts of the frozen conversation, proposes one or mor
 Run:
 
 ```text
-/midcompact review
+/midcompact:review
 ```
 
 In interactive mode, the native TUI displays the frozen conversation as a linear timeline. Each item is marked either `KEEP` or as belonging to a proposed range. Review the range boundaries and the summary that will replace each range.
@@ -158,14 +158,14 @@ In interactive mode, the native TUI displays the frozen conversation as a linear
 For RPC, print, or other no-TUI modes, use the editable local browser interface instead:
 
 ```text
-/midcompact review-webui
+/midcompact:review-webui
 ```
 
 Use Selection to create or change ranges and KEEP holes:
 
 ```text
-/midcompact select
-/midcompact select-webui
+/midcompact:select
+/midcompact:select-webui
 ```
 
 Use the TUI or local browser Review surface to edit summaries/topics and reject ranges. Review deliberately does not create or resize ranges; reopen Selection for boundary changes. To continue with Agent after a user-created plan, send a normal message asking it to continue the current midcompact draft; the Agent is prompted to read the existing plan first.
@@ -175,7 +175,7 @@ Use the TUI or local browser Review surface to edit summaries/topics and reject
 When the plan is correct, run:
 
 ```text
-/midcompact commit
+/midcompact:commit
 ```
 
 This is deliberately a human command. The Agent cannot commit compression itself.
@@ -187,14 +187,14 @@ Pi returns to the anchor, discards the temporary planning branch, stores the rev
 Keep working normally after committing. If you decide not to compress, run:
 
 ```text
-/midcompact abort
+/midcompact:abort
 ```
 
 This returns to the anchor and discards the transaction without changing the active context.
 
 ## Native TUI Controls
 
-Inside `/midcompact review`:
+Inside `/midcompact:review`:
 
 ```text
 n/p or Left/Right  select a proposed range
@@ -211,14 +211,14 @@ Enter/Esc/q        close
 
 | Command | Result |
 | --- | --- |
-| `/midcompact start [instructions]` | Opens Agent direct / User manual / Drop, then starts a transaction at the current session-tree leaf. |
-| `/midcompact select` | Opens the native TUI Selection workbench for range and KEEP editing. |
-| `/midcompact select-webui` | Opens the local browser Selection workbench. |
-| `/midcompact review` | Opens summary/topic review in the native TUI. |
-| `/midcompact review-webui` | Opens summary/topic review in a local browser. |
-| `/midcompact commit` | Commits the reviewed draft. Human only. |
-| `/midcompact abort` | Abandons the transaction and returns to the anchor. |
-| `/midcompact status` | Displays the current draft, or the committed compression state on this branch. |
+| `/midcompact:start [instructions]` | Opens Agent direct / User manual / Drop, then starts a transaction at the current session-tree leaf. |
+| `/midcompact:select` | Opens the native TUI Selection workbench for range and KEEP editing. |
+| `/midcompact:select-webui` | Opens the local browser Selection workbench. |
+| `/midcompact:review` | Opens summary/topic review in the native TUI. |
+| `/midcompact:review-webui` | Opens summary/topic review in a local browser. |
+| `/midcompact:commit` | Commits the reviewed draft. Human only. |
+| `/midcompact:abort` | Abandons the transaction and returns to the anchor. |
+| `/midcompact:status` | Displays the current draft, or the committed compression state on this branch. |
 
 The extension shows planning status in Pi's footer only while a transaction is active. It disappears after commit or abort.
 
@@ -227,7 +227,7 @@ The extension shows planning status in Pi's footer only while a transaction is a
 - **Original history is retained.** Compression changes what later model requests see, not the stored Pi messages.
 - **Fail-open projection.** If an exact reviewed sequence no longer resolves, the extension sends the raw history unchanged rather than removing uncertain content.
 - **State is branch-local.** Navigating with `/tree` to a point before a committed state restores raw history; returning to its descendant restores the projection.
-- **Human review is required.** The Agent can propose a plan but cannot execute `/midcompact commit`.
+- **Human review is required.** The Agent can propose a plan but cannot execute `/midcompact:commit`.
 - **Tool protocol is protected.** Unknown, incomplete, or orphaned tool exchanges are not compressible.
 - **Repeated transactions work.** Later transactions can compress newly accumulated raw context; existing summaries remain protected.
 - **Native Pi `/compact` interaction needs more real-session validation.** Avoid relying on mixed automatic/native compaction behavior for critical work until it has been exercised in your environment.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-midcompact",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Branch-aware mid-context compression for the Pi coding agent",
   "author": "frostime",
   "repository": {
@@ -32,7 +32,7 @@
   ],
   "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",
+    "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",
     "typecheck:contract": "tsc -p tsconfig.test.json --noEmit",
     "pack:check": "npm pack --dry-run"
   },

package/skills/midcompact/SKILL.md

@@ -12,15 +12,17 @@ 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.
 
+The tool groups parameters by `action`: each action accepts only its own fields, and fields from other actions are rejected. Read `references/tool-interface.md` before adding workload-specific parameters, and treat the action-specific field lists there as exhaustive.
+
 ## Plan compression
 
-Selected ranges become summaries in future model context; content outside them stays verbatim. Originals remain stored, but recall is a recovery path, not a substitute for a sufficient summary. Agent and user edit one DraftPlan; the user retains final control through review and `/midcompact commit`.
+Selected ranges become summaries in future model context; content outside them stays verbatim. Originals remain stored, but recall is a recovery path, not a substitute for a sufficient summary. Agent and user edit one DraftPlan; the user retains final control through review and `/midcompact:commit`.
 
 The start mode controls how the first draft is created. It does not determine whether a user selection is final, how much initiative the Agent should take, or how deeply the history should be investigated.
 
@@ -32,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.
 
@@ -69,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.
 
@@ -105,9 +107,9 @@ 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.
+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.
 
 ## Recall compressed content
 
@@ -117,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

@@ -2,9 +2,13 @@
 
 Read this reference when exact call requirements, limits, rejection behavior, repeated compression, or recall truncation matters. The main workflow remains in `../SKILL.md`.
 
+## Parameter grouping
+
+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.
@@ -15,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`.
@@ -38,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 |
 |----|-----------------|
@@ -74,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,93 @@
+# 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 (same rule as `projectedTokens` / estimates).
+- 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.
+
+## 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/index.ts

@@ -6,8 +6,6 @@ import {
   type ExtensionContext,
   type SessionEntry,
 } from "@earendil-works/pi-coding-agent";
-import type { AutocompleteItem } from "@earendil-works/pi-tui";
-
 import { buildAtoms, formatLocatedAtom, isProtectedAtom, locateAtomMatches } from "./atoms.js";
 import { buildInventory, formatInventory, formatSpanInspection } from "./inventory.js";
 import { messageText } from "./messages.js";
@@ -69,28 +67,79 @@ const TOOL_DESCRIPTION =
 const STATUS_KEY = "midcompact";
 const START_PROMPT_PREFIX = "A mid-compaction transaction is active on a frozen anchor snapshot.";
 
-const Params = Type.Object({
-  action: StringEnum(["inspect", "locate", "plan", "recall"] as const),
-  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)),
-  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()),
-  // inspect inventory pagination or explicit candidate-span measurement
-  page_size: Type.Optional(Type.Number()),
-  cursor: Type.Optional(Type.String()),
-  spans: Type.Optional(Type.Array(Type.Object({ start: Type.String(), end: Type.String() }))),
-});
-
-type ParamsType = Static<typeof Params>;
+// 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 };
 
@@ -146,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,
       },
@@ -172,48 +221,63 @@ export default function (pi: ExtensionAPI) {
     return { messages: projectMessages(event.messages as MessageLike[], activeState) as typeof event.messages };
   });
 
-  pi.registerCommand("midcompact", {
-    description: "Start, select, review, commit, inspect, or abort a branch-isolated mid-context compression transaction",
-    getArgumentCompletions(prefix: string): AutocompleteItem[] | null {
-      const query = prefix.trimStart().toLowerCase();
-      if (/\s/.test(query)) return null;
-      const items: AutocompleteItem[] = [
-        { value: "start", label: "start — Start a new midcompact transaction at the current anchor" },
-        { value: "abort", label: "abort — Abort the active transaction and return to anchor" },
-        { value: "commit", label: "commit — Commit the current draft to the branch state" },
-        { value: "review", label: "review — Open interactive TUI to inspect and edit the draft" },
-        { value: "review-webui", label: "review-webui — Open a local web page to inspect and edit the draft (works without TUI)" },
-        { value: "select", label: "select — Open the TUI Selection surface to edit range boundaries" },
-        { value: "select-webui", label: "select-webui — Open Selection in a local browser" },
-        { value: "status", label: "status — Show current transaction and draft status" },
-      ];
-      const filtered = items.filter((item) => item.value.startsWith(query));
-      return filtered.length > 0 ? filtered : null;
-    },
+  // One command per operation; the `midcompact:` prefix follows the same
+  // naming convention as Pi's own `skill:<name>` commands. The former
+  // composite `/midcompact <subcommand>` command is gone.
+  pi.registerCommand("midcompact:start", {
+    description: "Start a new midcompact transaction at the current anchor. Optional trailing text becomes the initial focus.",
     handler: async (args: string, ctx: ExtensionCommandContext) => {
       await ctx.waitForIdle();
-      const rawArgs = args.trim();
-      const lower = rawArgs.toLowerCase();
-
-      if (lower === "abort") return abortTransaction(ctx);
-      if (lower === "commit") return commitTransaction(ctx);
-      if (lower === "review") return reviewTransaction(ctx, "tui");
-      if (lower === "review-webui") return reviewTransaction(ctx, "web");
-      if (lower === "select") return openSelectionUi(ctx, "auto");
-      if (lower === "select-webui") return openSelectionUi(ctx, "web");
-      if (lower === "status") return showStatus(ctx);
-
-      // start [instructions...]
-      const startMatch = rawArgs.match(/^start\b\s*(.*)$/i);
-      if (startMatch) {
-        const instructions = (startMatch[1] ?? "").trim();
-        return startTransaction(ctx, instructions || undefined);
-      }
-
-      ctx.ui.notify(
-        "Usage: /midcompact start [instructions] | /midcompact select[-webui] | /midcompact review[-webui] | /midcompact commit | /midcompact status | /midcompact abort",
-        "warning",
-      );
+      return startTransaction(ctx, args.trim() || undefined);
+    },
+  });
+  pi.registerCommand("midcompact:abort", {
+    description: "Abort the active transaction and return to the anchor",
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
+      await ctx.waitForIdle();
+      return abortTransaction(ctx);
+    },
+  });
+  pi.registerCommand("midcompact:commit", {
+    description: "Commit the current draft to the branch state",
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
+      await ctx.waitForIdle();
+      return commitTransaction(ctx);
+    },
+  });
+  pi.registerCommand("midcompact:review", {
+    description: "Open the interactive TUI review to inspect and edit the draft",
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
+      await ctx.waitForIdle();
+      return reviewTransaction(ctx, "tui");
+    },
+  });
+  pi.registerCommand("midcompact:review-webui", {
+    description: "Open a local web page to inspect and edit the draft (works without TUI)",
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
+      await ctx.waitForIdle();
+      return reviewTransaction(ctx, "web");
+    },
+  });
+  pi.registerCommand("midcompact:select", {
+    description: "Open the TUI Selection surface to edit range boundaries",
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
+      await ctx.waitForIdle();
+      return openSelectionUi(ctx, "auto");
+    },
+  });
+  pi.registerCommand("midcompact:select-webui", {
+    description: "Open Selection in a local browser",
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
+      await ctx.waitForIdle();
+      return openSelectionUi(ctx, "web");
+    },
+  });
+  pi.registerCommand("midcompact:status", {
+    description: "Show current transaction and draft status",
+    handler: async (_args: string, ctx: ExtensionCommandContext) => {
+      await ctx.waitForIdle();
+      return showStatus(ctx);
     },
   });
 
@@ -473,7 +537,7 @@ export default function (pi: ExtensionAPI) {
 
     if (ctx.mode !== "tui") {
       ctx.ui.notify(
-        "Interactive TUI review is only available in interactive (tui) mode. Use /midcompact review-webui to open a local web page instead.",
+        "Interactive TUI review is only available in interactive (tui) mode. Use /midcompact:review-webui to open a local web page instead.",
         "warning",
       );
       return;
@@ -533,12 +597,13 @@ 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.");
+        if (!currentTx) return toolResult("No active midcompact transaction. Ask the user to run `/midcompact:start` first.");
         transaction = currentTx;
         draft = restored.draft ? { ...restored.draft, ranges: restored.draft.ranges.map(coerceDraftRange) } : (draft ?? emptyDraft(currentTx.id));
         if (!requireAgentAccess(ctx)) {
@@ -546,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,
             }));
           }
@@ -569,7 +634,7 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
-  function handleInspect(params: ParamsType, 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.");
@@ -580,7 +645,7 @@ export default function (pi: ExtensionAPI) {
     return formatInventory(page);
   }
 
-  function handleRecall(params: ParamsType, 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.";
@@ -616,7 +681,7 @@ export default function (pi: ExtensionAPI) {
 
 // ---- Pure handlers ----
 
-function handleLocate(params: ParamsType, 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.");
@@ -648,7 +713,7 @@ type PlanHandleResult =
   | { op: "show"; draft: DraftPlan }
   | { op: "add" | "update" | "remove"; draft: DraftPlan; changedId: string };
 
-function handlePlan(params: ParamsType, 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") {

package/src/projection.ts

@@ -17,7 +17,7 @@ export function summaryMessage(block: CompressionBlock, timestamp = Date.now()):
       block.summary,
       "",
       `Original block: ${block.id}`,
-      `Use midcompact(action=\"recall\", ref=\"${block.id}\") if exact details are needed.`,
+      `Use midcompact(request={action:\"recall\", ref:\"${block.id}\"}) if exact details are needed.`,
     ].join("\n"),
     display: true,
     details: {

package/src/types.ts

@@ -178,7 +178,7 @@ export interface TransactionState {
   startedAt: string;
   /** Initial routing chosen at start: Agent-first prompt or User-first UI. */
   startMode?: StartMode;
-  /** Frozen awareness captured when /midcompact starts; informational, never a target. */
+  /** Frozen awareness captured when /midcompact:start runs; informational, never a target. */
   anchorUsage?: ContextUsageSnapshot;
 }