pi-midcompact 0.5.1 → 0.5.2

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.2",
   "description": "Branch-aware mid-context compression for the Pi coding agent",
   "author": "frostime",
   "repository": {

package/skills/midcompact/SKILL.md

@@ -18,9 +18,11 @@ This skill handles two independent tasks: planning compression and recalling com
 
 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.
 
@@ -107,7 +109,7 @@ Length follows the information that must survive, not a target ratio. Final test
 
 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.
 
-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
 

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

@@ -2,6 +2,10 @@
 
 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 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.
+
 ## 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.

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,8 +67,20 @@ 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),
+// 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)),
@@ -78,19 +88,34 @@ const Params = Type.Object({
   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()),
-  // 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() }))),
+  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>;
 
 type RuntimeSnapshot = { atoms: Atom[]; anchorState?: CompressionState };
 
@@ -172,48 +197,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 +513,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;
@@ -538,7 +578,7 @@ export default function (pi: ExtensionAPI) {
         if (params.action === "recall") return toolResult(handleRecall(params, 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)) {
@@ -569,7 +609,7 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
-  function handleInspect(params: ParamsType, atoms: Atom[], tx: TransactionState): string {
+  function handleInspect(params: InspectParamsType, 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 +620,7 @@ export default function (pi: ExtensionAPI) {
     return formatInventory(page);
   }
 
-  function handleRecall(params: ParamsType, ctx: ExtensionContext): string {
+  function handleRecall(params: RecallParamsType, 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 +656,7 @@ export default function (pi: ExtensionAPI) {
 
 // ---- Pure handlers ----
 
-function handleLocate(params: ParamsType, atoms: Atom[]): string {
+function handleLocate(params: LocateParamsType, 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 +688,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: PlanParamsType, current: DraftPlan, atoms: Atom[]): PlanHandleResult {
   const op = params.op ?? "show";
   if (op === "show") return { op, draft: current };
   if (op === "remove") {

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;
 }