@dieulc/workflow 0.6.1 → 0.8.0

package/tab-editor.ts

@@ -0,0 +1,147 @@
+/**
+ * Workflow editor: gives Tab back to autocomplete while a suggestion list is
+ * visible, and lets the existing `tab` extension shortcut cycle modes when it
+ * is not.
+ *
+ * Why a custom editor is needed: Pi's `CustomEditor.handleInput()` dispatches
+ * extension shortcuts before any editor/autocomplete handling, and the
+ * workflow registers a raw `tab` shortcut. A plugin cannot make that dispatch
+ * conditional, so the workflow installs this thin subclass through the public
+ * `ctx.ui.setEditorComponent()` API. The subclass only changes the precedence
+ * for the completion branch; every other key and every other extension
+ * shortcut keeps the normal path.
+ *
+ * Public-API constraints:
+ * - `isShowingAutocomplete()` is public.
+ * - The editor's `autocompleteList`, `autocompletePrefix` and
+ *   `handleTabCompletion()` are private, so the only clean way to accept the
+ *   highlighted item is to suppress the extension bridge for one synchronous
+ *   `super.handleInput()` call.
+ * - `onExtensionShortcut` is installed by the core *after* this class is
+ *   constructed. Do not declare a same-named field: an own handler would stop
+ *   the core from installing its bridge and silently break every extension
+ *   shortcut.
+ *
+ * The history helpers keep prompt history alive across the editor swap that
+ * `setCustomEditorComponent()` performs: the core copies the editor text but not
+ * the `history` array.
+ */
+
+import {
+  CustomEditor,
+  type KeybindingsManager,
+} from "@earendil-works/pi-coding-agent";
+import type { Editor, EditorTheme, TUI } from "@earendil-works/pi-tui";
+import { decideTabAction } from "./tab-policy.ts";
+
+/** Minimal structural shape of a session entry that can carry user text. */
+export interface PromptHistoryEntry {
+  type?: string;
+  message?: {
+    role?: string;
+    content?:
+      | string
+      | ReadonlyArray<{ type?: string; text?: string }>;
+  };
+}
+
+/**
+ * User prompt texts from session entries, oldest first.
+ *
+ * Mirrors pi's `getUserMessageText()`: string content or the concatenation of
+ * text blocks. Entries without user text (assistant/tool/system, or an empty
+ * message) are skipped.
+ */
+export function promptHistoryTexts(
+  entries: readonly PromptHistoryEntry[],
+): string[] {
+  const texts: string[] = [];
+  for (const entry of entries) {
+    if (!entry || entry.type !== "message") continue;
+    const message = entry.message;
+    if (!message || message.role !== "user") continue;
+
+    const content = message.content;
+    let text = "";
+    if (typeof content === "string") {
+      text = content;
+    } else {
+      for (const block of content ?? []) {
+        if (block?.type === "text" && typeof block.text === "string") {
+          text += block.text;
+        }
+      }
+    }
+    if (text.trim()) texts.push(text);
+  }
+  return texts;
+}
+
+/**
+ * Seed a fresh editor's prompt history from session entries.
+ *
+ * `Editor.addToHistory()` unshifts, so feeding oldest→newest leaves the newest
+ * prompt at the cursor end, exactly like the host's own population path.
+ */
+export function seedPromptHistory(
+  editor: Pick<Editor, "addToHistory">,
+  entries: readonly PromptHistoryEntry[],
+): void {
+  for (const text of promptHistoryTexts(entries)) {
+    editor.addToHistory(text);
+  }
+}
+
+export class WorkflowTabEditor extends CustomEditor {
+  private readonly tabKeybindings: KeybindingsManager;
+  private hostHistoryAdded = false;
+
+  constructor(tui: TUI, theme: EditorTheme, keybindings: KeybindingsManager) {
+    super(tui, theme, keybindings);
+    this.tabKeybindings = keybindings;
+    // The default 1.4.0 editor renders the working spinner in its top border.
+    // `embedWorkingStatus` is absent from the 0.84.4 constructor options type
+    // this package compiles against, but the runtime check is field-based, so
+    // assigning it after `super` restores the default behaviour and is inert on
+    // older versions.
+    (this as any).embedWorkingStatus = true;
+  }
+
+  /** True once the host has populated this editor's prompt history. */
+  hasHostHistory(): boolean {
+    return this.hostHistoryAdded;
+  }
+
+  override addToHistory(text: string): void {
+    if (text.trim()) this.hostHistoryAdded = true;
+    super.addToHistory(text);
+  }
+
+  override handleInput(data: string): void {
+    const action = decideTabAction({
+      data,
+      keybindings: this.tabKeybindings,
+      editor: this,
+    });
+
+    if (action === "complete") {
+      // Suppress only the extension-shortcut bridge for this synchronous call.
+      // `super.handleInput()` then reaches the editor's Tab branch, which
+      // applies the highlighted item. `finally` restores the bridge so the
+      // workflow `tab` shortcut and every other extension shortcut keep
+      // working for the next key.
+      const forwarded = this.onExtensionShortcut;
+      this.onExtensionShortcut = undefined;
+      try {
+        super.handleInput(data);
+      } finally {
+        this.onExtensionShortcut = forwarded;
+      }
+      return;
+    }
+
+    // "cycle" (no visible list) and "ignore" (not Tab / disabled binding) use
+    // the normal CustomEditor path: extension shortcuts first, then the editor.
+    super.handleInput(data);
+  }
+}

package/tab-policy.ts

@@ -0,0 +1,42 @@
+/**
+ * Tab precedence between Pi's autocomplete and the workflow mode cycle.
+ *
+ * Pi's `CustomEditor.handleInput()` checks extension shortcuts *before* the
+ * editor, so the workflow's registered `tab` shortcut would otherwise swallow
+ * every Tab — including the one that accepts the highlighted command, file or
+ * document suggestion. The workflow editor asks this policy first:
+ *
+ *   suggestion list visible  -> complete (apply the highlighted item)
+ *   no suggestion list       -> cycle    (Plan → Build → Default)
+ *   another key              -> ignore   (let CustomEditor/Editor handle it)
+ *   Tab binding disabled     -> ignore   (never turn a disabled Tab into accept)
+ *
+ * The rule is deliberately based on menu visibility only, matching Pi Desktop's
+ * `Composer.tsx` `menuKey` logic. A `/command` line whose list has not rendered
+ * yet is allowed to cycle; the list wins only while it is actually visible.
+ *
+ * Pure module (type-only imports) so the precedence is unit-testable without a
+ * TUI.
+ */
+
+import type { Keybinding } from "@earendil-works/pi-tui";
+
+export type TabAction = "ignore" | "complete" | "cycle";
+
+export interface TabEditorView {
+  /** True while a non-empty autocomplete list is visible. */
+  isShowingAutocomplete(): boolean;
+}
+
+export interface TabKeyMatcher {
+  matches(data: string, keybinding: Keybinding): boolean;
+}
+
+export function decideTabAction(args: {
+  data: string;
+  keybindings: TabKeyMatcher;
+  editor: TabEditorView;
+}): TabAction {
+  if (!args.keybindings.matches(args.data, "tui.input.tab")) return "ignore";
+  return args.editor.isShowingAutocomplete() ? "complete" : "cycle";
+}

package/utils.ts

@@ -931,6 +931,53 @@ export function isPlanWritePath(p: string, cwd: string): boolean {
   return norm.includes(".pi/plans/") || norm.startsWith(cwdNorm + "/.pi/plans");
 }
 
+/** Inputs for deciding whether this run may hand a plan off. */
+export interface PlanHandoffEligibility {
+  mode: "plan" | "build" | null;
+  /** The run started in Plan mode (not a Build turn that flipped to Plan). */
+  runStartedInPlan: boolean;
+  /** This run wrote/edited a file under `.pi/plans/`. */
+  planWrittenThisRun: boolean;
+}
+
+/**
+ * A handoff requires all three: the workflow is in Plan mode NOW, the run
+ * started in Plan mode, and the run actually wrote a plan. Session-lifetime
+ * plan files and old todos never authorize a handoff.
+ */
+export function shouldHandoffPlan(input: PlanHandoffEligibility): boolean {
+  return (
+    input.mode === "plan" &&
+    input.runStartedInPlan === true &&
+    input.planWrittenThisRun === true
+  );
+}
+
+/**
+ * Last `write`/`edit` tool call in THIS RUN whose path is under `.pi/plans/`.
+ * `messages` must be the `agent_end` run messages (the run's `newMessages`),
+ * never the session history — scanning history would resurrect old plans.
+ * Returns the path as supplied by the tool call; the caller resolves it.
+ */
+export function findPlanWritePathInMessages(
+  messages: readonly unknown[],
+  cwd: string,
+): string | undefined {
+  if (!Array.isArray(messages) || messages.length === 0) return undefined;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i] as any;
+    if (m?.role !== "assistant" || !Array.isArray(m.content)) continue;
+    for (let j = m.content.length - 1; j >= 0; j--) {
+      const b = m.content[j];
+      if (b?.type !== "toolCall") continue;
+      if (b.name !== "write" && b.name !== "edit") continue;
+      const p = b.arguments?.path ?? b.arguments?.file_path;
+      if (typeof p === "string" && p && isPlanWritePath(p, cwd)) return p;
+    }
+  }
+  return undefined;
+}
+
 // ── Plan date helpers (UTC) ──────────────────────────────────────
 
 /** Return YYYY-MM-DD in UTC for the given date (default: now). Uses toISOString slice, deterministic across locales. */
@@ -1174,11 +1221,21 @@ export function reviewFindingTier(f: {
   return "Info";
 }
 
-/** True when a severity tier is high enough to warrant the verify pass. */
+/**
+ * True when a severity tier is high enough to warrant the verify pass.
+ *
+ * Step 9: only accepted findings at severity >= 7 (with confidence >= 60)
+ * trigger self-verification. Lower findings are not worth a second full LLM
+ * turn; empty, low-severity, or rejected-only findings resubmit pass 1's
+ * plan directly.
+ */
 export function reviewNeedsVerification(findings: ReviewFinding[]): boolean {
   if (!Array.isArray(findings)) return false;
   return findings.some(
-    (f) => Number(f?.severity) >= 5 && Number(f?.confidence) >= 60,
+    (f) =>
+      Number(f?.severity) >= 7 &&
+      Number(f?.confidence) >= 60 &&
+      f?.disposition === "accepted",
   );
 }
 
@@ -1285,6 +1342,79 @@ export function renderReviewChangelog(
   return lines.join("\n").trimEnd();
 }
 
+/**
+ * Minimal unified diff between two plan texts (step 9).
+ *
+ * Pass 2 only checks "did the rewrite drop a requirement", so it gets a
+ * diff — not two full plans. Prefix/suffix trim with a few context lines
+ * keeps typical localized rewrites at ~1/10th the tokens; a total rewrite
+ * degrades to one hunk (no worse than today). Capped and never throws.
+ */
+export function buildPlanDiff(
+  original: string,
+  revised: string,
+  context = 3,
+): string {
+  const a = String(original ?? "").split("\n");
+  const b = String(revised ?? "").split("\n");
+  if (a.join("\n") === b.join("\n")) return "(no differences)";
+  const ctx = Number.isFinite(context)
+    ? Math.max(0, Math.min(10, Math.trunc(Number(context))))
+    : 3;
+  let start = 0;
+  while (start < a.length && start < b.length && a[start] === b[start])
+    start++;
+  let endA = a.length - 1;
+  let endB = b.length - 1;
+  while (endA >= start && endB >= start && a[endA] === b[endB]) {
+    endA--;
+    endB--;
+  }
+  const fromA = Math.max(0, start - ctx);
+  const toA = Math.min(a.length - 1, endA + ctx);
+  const fromB = Math.max(0, start - ctx);
+  const toB = Math.min(b.length - 1, endB + ctx);
+  const out = [
+    "--- original (author)",
+    "+++ rewritten (reviewer)",
+    `@@ -${fromA + 1},${toA - fromA + 1} +${fromB + 1},${toB - fromB + 1} @@`,
+  ];
+  for (let i = fromA; i < start; i++) out.push(`  ${a[i]}`);
+  for (let i = start; i <= endA; i++) out.push(`- ${a[i]}`);
+  for (let i = start; i <= endB; i++) out.push(`+ ${b[i]}`);
+  const tailFrom = Math.max(endA + 1, endB + 1, start);
+  const tailTo = Math.max(toA, toB);
+  const tailSrc = toA - fromA >= toB - fromB ? a : b;
+  for (let i = tailFrom; i <= Math.min(tailTo, tailSrc.length - 1); i++)
+    out.push(`  ${tailSrc[i]}`);
+  const text = out.join("\n");
+  const MAX_DIFF_CHARS = 12_000;
+    return text.length > MAX_DIFF_CHARS
+      ? `${text.slice(0, MAX_DIFF_CHARS)}\n… [diff truncated — the rewrite is large; re-read the plan file]`
+      : text;
+}
+
+/** Outcome of landing a detached background review (steps 5/11). */
+export type ReviewLanding = "updated" | "unchanged" | "stale";
+
+/**
+ * Decide what a landed background review may announce (step 11 contract).
+ * Pure: `diskHash` is the plan file on disk, `inputHash` the reviewed
+ * revision, `finalHash` the reviewer's rewrite. Only `updated` (the disk
+ * holds the rewrite) announces a change; every other outcome keeps the
+ * author's/user's text and stays quiet or defers to a re-run.
+ */
+export function classifyReviewLanding(input: {
+  diskHash?: string;
+  inputHash: string;
+  finalHash: string;
+}): ReviewLanding {
+  if (input.diskHash === undefined) return "unchanged";
+  if (input.diskHash === input.finalHash) return "updated";
+  if (input.diskHash === input.inputHash) return "unchanged";
+  return "stale";
+}
+
 /**
  * Strip any previously appended Review Mode appendix from a plan.
  * Returns the plan body exactly as the author wrote it.
@@ -1436,11 +1566,11 @@ export function pruneContextEntriesForReview(
   opts: PruneReviewContextOptions = {},
 ): any[] {
   const maxChars = Number.isFinite(opts.maxToolResultChars)
-    ? Math.max(200, Number(opts.maxToolResultChars))
-    : 4000;
+    ? Math.min(4000, Math.max(200, Number(opts.maxToolResultChars)))
+    : 1000;
   const maxEntries = Number.isFinite(opts.maxEntries)
-    ? Math.max(1, Number(opts.maxEntries))
-    : 120;
+    ? Math.min(120, Math.max(1, Number(opts.maxEntries)))
+    : 30;
   if (!Array.isArray(entries)) return [];
   const kept: any[] = [];
   try {
@@ -1554,8 +1684,8 @@ export function renderReviewContextBlock(
   opts: { maxChars?: number } = {},
 ): string {
   const maxChars = Number.isFinite(opts.maxChars)
-    ? Math.max(1000, Number(opts.maxChars))
-    : 60_000;
+    ? Math.min(60_000, Math.max(1000, Number(opts.maxChars)))
+    : 15_000;
   if (!Array.isArray(entries) || entries.length === 0) return "";
   const lines: string[] = [];
   try {
@@ -1579,67 +1709,240 @@ export function renderReviewContextBlock(
   }
   let out = lines.join("\n\n");
   if (out.length > maxChars) {
-    out = `${out.slice(0, maxChars)}\n\n… [context truncated at ${maxChars} chars]`;
+    out = `${out.slice(0, maxChars)}\n\n… [context truncated at ${maxChars} chars — re-read anything you rely on with read/grep]`;
   }
   return out;
 }
-
-// ── Slash-command argument completions (pi-tui contract) ─────────────
-//
-// `CombinedAutocompleteProvider.getSuggestions` (pi-tui dist/autocomplete.js)
-// passes `getArgumentCompletions(argumentText)` the ENTIRE typed argument
-// text after the command name and, on accept, `applyCompletion` replaces
-// that whole argument text with `item.value` (the slash-argument branch:
-// `newLine = beforePrefix + item.value`). So an argument-position item's
-// `value` must be the complete replacement — e.g. `"use <name>"`, never the
-// bare token. Pi's own /mcp extension follows this contract
-// (`value: `${action} ${name}``). `joinArgumentValue` is the single helper
-// that enforces it: it keeps every committed token and appends (or replaces
-// the last partial token with) `token`.
-
-/** One slash-command argument completion item (pi-tui `AutocompleteItem` shape). */
-export interface ArgumentCompletion {
-  value: string;
-  label: string;
-  description?: string;
-}
-
-/**
- * Build the full-argument replacement `value` for a completion token.
- *
- * `prefix` is the typed argument text so far. Tokens separated by whitespace
- * are "committed"; if `prefix` ends with whitespace the user is starting a
- * fresh token, so `token` is appended — otherwise it replaces the trailing
- * partial token. Pure; never throws.
- *
- *   joinArgumentValue("use Syn-De", "Syn-Deepseek-v4.1-Flash-Planner")
- *     → "use Syn-Deepseek-v4.1-Flash-Planner"
- *   joinArgumentValue("use ", "none") → "use none"
- *   joinArgumentValue("", "list")     → "list"
- */
-export function joinArgumentValue(prefix: string, token: string): string {
-  const raw = String(prefix ?? "");
-  const endsWithWs = /\s$/.test(raw);
-  const parts = raw.trim().split(/\s+/).filter(Boolean);
-  const committed = endsWithWs ? parts : parts.slice(0, -1);
-  return [...committed, token].join(" ");
-}
-
-/**
- * Exact-match suppression for slash-command argument completions: when the
- * token being typed (`partial`, "" while the prefix ends with whitespace)
- * already equals the ONLY remaining candidate, return true so the completer
- * yields null — pi's editor then closes the dropdown and the FIRST Enter
- * submits instead of being consumed by the completion-accept handler
- * (editor.js `tui.select.confirm`). Pure.
- */
-export function suppressExactArgumentMatch(
-  candidates: readonly string[],
-  partial: string,
-): boolean {
-  if (!partial) return false;
-  return (
-    candidates.length === 1 &&
-    candidates[0].toLowerCase() === partial.toLowerCase()
-  );
-}
+
+// ── Planner-context manifest for the reviewer (step 8) ─────────────
+
+/** What `buildPlannerContextManifest` found in the parent branch. */
+export interface PlannerContextManifest {
+  /** Markdown section for the pass-1 prompt ("" when there is nothing). */
+  markdown: string;
+  /** Distinct file paths inventoried. */
+  files: number;
+  /** Explore recon summaries included. */
+  reconResults: number;
+}
+
+export interface BuildPlannerManifestOptions {
+  /** Max files listed in the inventory. */
+  maxFiles?: number;
+  /** Max explore results summarized. */
+  maxReconResults?: number;
+  /** Max chars taken from the tail of each explore result. */
+  maxReconChars?: number;
+  /**
+   * Describe a referenced path (size/mtime/hash token). Return undefined
+   * for paths that cannot be described — the path is still listed.
+   */
+  describeFile?: (path: string) => string | undefined;
+}
+
+const PLANNER_MANIFEST_MAX_FILES = 200;
+const PLANNER_MANIFEST_MAX_RECON = 3;
+const PLANNER_MANIFEST_RECON_CHARS = 700;
+
+/**
+ * Ordered unique `path`/`file_path` arguments from tool calls in the branch.
+ * These are the files Plan Mode touched — the reviewer can trust them
+ * unless a finding cites them (then it re-reads). Never throws.
+ */
+function manifestToolPaths(entries: unknown, maxFiles: number): string[] {
+  const paths: string[] = [];
+  const seen = new Set<string>();
+  const take = (raw: unknown): void => {
+    if (paths.length >= maxFiles) return;
+    if (typeof raw !== "string") return;
+    const p = raw.trim();
+    if (!p || p.length > 500 || seen.has(p)) return;
+    seen.add(p);
+    paths.push(p);
+  };
+  try {
+    if (!Array.isArray(entries)) return paths;
+    for (const e of entries) {
+      if (paths.length >= maxFiles) break;
+      if (!e || typeof e !== "object") continue;
+      const blocks = (e as { message?: { content?: unknown } }).message
+        ?.content;
+      if (!Array.isArray(blocks)) continue;
+      for (const b of blocks) {
+        if (!b || typeof b !== "object") continue;
+        const t = (b as { type?: unknown }).type;
+        if (t !== "toolCall" && t !== "tool_use") continue;
+        const args = (b as { arguments?: unknown; input?: unknown })
+          .arguments ?? (b as { input?: unknown }).input;
+        if (args && typeof args === "object") {
+          take((args as Record<string, unknown>).path);
+          take((args as Record<string, unknown>).file_path);
+        }
+      }
+    }
+  } catch {
+    /* keep what was collected */
+  }
+  return paths;
+}
+
+/**
+ * Tails of the most recent `explore` tool results (Plan Mode recon), newest
+ * first. Conclusions tend to live at the end, so the tail is kept. Never throws.
+ */
+function manifestReconTails(
+  entries: unknown,
+  maxResults: number,
+  maxChars: number,
+): string[] {
+  const tails: string[] = [];
+  try {
+    if (!Array.isArray(entries)) return tails;
+    for (
+      let i = entries.length - 1;
+      i >= 0 && tails.length < maxResults;
+      i--
+    ) {
+      const msg = (entries[i] as { message?: unknown })?.message as
+        | { role?: unknown; toolName?: unknown; content?: unknown }
+        | undefined;
+      if (!msg || msg.role !== "toolResult" || msg.toolName !== "explore")
+        continue;
+      const text = contentBlocksToText(msg.content).trim();
+      if (!text) continue;
+      tails.push(
+        text.length > maxChars ? `…${text.slice(text.length - maxChars)}` : text,
+      );
+    }
+  } catch {
+    /* keep what was collected */
+  }
+  return tails;
+}
+
+/**
+ * Build the Planner-context manifest: a file inventory with change tokens
+ * plus recent explore recon, so the reviewer verifies instead of re-exploring
+ * (plan 2026-10-23, step 8). Takes the RAW branch — pruned entries elide the
+ * explore tails this needs. Pure except for the optional `describeFile`.
+ * Never throws; empty input yields an empty markdown section.
+ */
+export function buildPlannerContextManifest(
+  entries: unknown,
+  opts: BuildPlannerManifestOptions = {},
+): PlannerContextManifest {
+  const empty: PlannerContextManifest = {
+    markdown: "",
+    files: 0,
+    reconResults: 0,
+  };
+  try {
+    const maxFiles = Number.isFinite(opts.maxFiles)
+      ? Math.max(1, Math.min(500, Number(opts.maxFiles)))
+      : PLANNER_MANIFEST_MAX_FILES;
+    const maxRecon = Number.isFinite(opts.maxReconResults)
+      ? Math.max(0, Math.min(10, Number(opts.maxReconResults)))
+      : PLANNER_MANIFEST_MAX_RECON;
+    const maxReconChars = Number.isFinite(opts.maxReconChars)
+      ? Math.max(100, Math.min(8000, Number(opts.maxReconChars)))
+      : PLANNER_MANIFEST_RECON_CHARS;
+    const paths = manifestToolPaths(entries, maxFiles);
+    const recon = manifestReconTails(entries, maxRecon, maxReconChars);
+    if (paths.length === 0 && recon.length === 0) return empty;
+    const lines = [
+      "## Shared context (Planner — trusted unless a finding cites it)",
+      "",
+      "Plan Mode already explored this repository. Trust this inventory and",
+      "these recon summaries for everything they cover; re-read only files a",
+      "finding anchors, plus one or two spot checks.",
+      "",
+    ];
+    if (paths.length > 0) {
+      lines.push(`Files Plan Mode touched (${paths.length}):`, "");
+      for (const p of paths) {
+        let detail = "";
+        try {
+          const d = opts.describeFile?.(p);
+          if (d) detail = ` — ${d}`;
+        } catch {
+          /* a path is still listed without its token */
+        }
+        lines.push(`- \`${p}\`${detail}`);
+      }
+      lines.push("");
+    }
+    if (recon.length > 0) {
+      lines.push(`Planner recon (newest first, ${recon.length}):`, "");
+      recon.forEach((tail, i) => {
+        lines.push(`### Recon ${i + 1}`, "", tail, "");
+      });
+    }
+    return {
+      markdown: lines.join("\n").trimEnd(),
+      files: paths.length,
+      reconResults: recon.length,
+    };
+  } catch {
+    return empty;
+  }
+}
+
+// ── Slash-command argument completions (pi-tui contract) ─────────────
+//
+// `CombinedAutocompleteProvider.getSuggestions` (pi-tui dist/autocomplete.js)
+// passes `getArgumentCompletions(argumentText)` the ENTIRE typed argument
+// text after the command name and, on accept, `applyCompletion` replaces
+// that whole argument text with `item.value` (the slash-argument branch:
+// `newLine = beforePrefix + item.value`). So an argument-position item's
+// `value` must be the complete replacement — e.g. `"use <name>"`, never the
+// bare token. Pi's own /mcp extension follows this contract
+// (`value: `${action} ${name}``). `joinArgumentValue` is the single helper
+// that enforces it: it keeps every committed token and appends (or replaces
+// the last partial token with) `token`.
+
+/** One slash-command argument completion item (pi-tui `AutocompleteItem` shape). */
+export interface ArgumentCompletion {
+  value: string;
+  label: string;
+  description?: string;
+}
+
+/**
+ * Build the full-argument replacement `value` for a completion token.
+ *
+ * `prefix` is the typed argument text so far. Tokens separated by whitespace
+ * are "committed"; if `prefix` ends with whitespace the user is starting a
+ * fresh token, so `token` is appended — otherwise it replaces the trailing
+ * partial token. Pure; never throws.
+ *
+ *   joinArgumentValue("use Syn-De", "Syn-Deepseek-v4.1-Flash-Planner")
+ *     → "use Syn-Deepseek-v4.1-Flash-Planner"
+ *   joinArgumentValue("use ", "none") → "use none"
+ *   joinArgumentValue("", "list")     → "list"
+ */
+export function joinArgumentValue(prefix: string, token: string): string {
+  const raw = String(prefix ?? "");
+  const endsWithWs = /\s$/.test(raw);
+  const parts = raw.trim().split(/\s+/).filter(Boolean);
+  const committed = endsWithWs ? parts : parts.slice(0, -1);
+  return [...committed, token].join(" ");
+}
+
+/**
+ * Exact-match suppression for slash-command argument completions: when the
+ * token being typed (`partial`, "" while the prefix ends with whitespace)
+ * already equals the ONLY remaining candidate, return true so the completer
+ * yields null — pi's editor then closes the dropdown and the FIRST Enter
+ * submits instead of being consumed by the completion-accept handler
+ * (editor.js `tui.select.confirm`). Pure.
+ */
+export function suppressExactArgumentMatch(
+  candidates: readonly string[],
+  partial: string,
+): boolean {
+  if (!partial) return false;
+  return (
+    candidates.length === 1 &&
+    candidates[0].toLowerCase() === partial.toLowerCase()
+  );
+}