pi-midcompact 0.5.2 → 0.5.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-midcompact",
-  "version": "0.5.2",
+  "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,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,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

@@ -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") {

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: {