pi-mipmux 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Warren Winter
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,119 @@
-# Temporary Holding Version
+# pi-mipmux
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+pi-mipmux is a [Pi](https://pi.dev) extension for mipmux. Its `/mipmux` command opens a panel where you choose the folders that the agent's context packets come from, and set build preferences such as the budget and the discovery model. The extension applies these choices to the agent's `context_builder` and `context_prepare` calls before Pi sends them to mipmux.
+
+## Install
+
+pi-mipmux needs mipmux connected to Pi as an MCP server named `mipmux`, and the `mipmux` command on your PATH; the [mipmux quickstart](https://github.com/w-winter/mipmux#quickstart) covers building and configuring it. With Pi's built-in MCP support:
+
+```sh
+pi mcp add mipmux -- mipmux mcp
+pi install npm:pi-mipmux
+```
+
+## Use the panel
+
+Run `/mipmux`. The panel lists every setting with the value a build would use now. Highlight a row and press a key:
+
+| Key | Action |
+|---|---|
+| ↑ ↓ | Move between rows |
+| Enter | Edit the highlighted value, or open its list |
+| `p` | Pin or unpin the value; a pinned value replaces the value the agent sends |
+| Delete or Backspace | Clear the value, or remove the highlighted item in a list |
+| Ctrl+S | Save every change |
+| Esc or Ctrl+C | Go back one screen; on the main screen, close the panel |
+
+Nothing changes until you press Ctrl+S. The footer shows `(unsaved)` while changes are waiting, and closing the panel discards them. Saved changes apply from the agent's next mipmux call, with no restart or reconnect.
+
+`/mipmux <name>` selects a saved workspace without opening the panel and completes saved names. In RPC mode, `/mipmux` sends the current settings to the client as a notification instead of opening the panel. Print mode (`pi -p`) and JSON mode have no UI, so `/mipmux` shows nothing there.
+
+## Choose a workspace
+
+Every build and prepare call names a workspace: the source folders mipmux indexes (its roots) and the output folder where mipmux saves packets. The panel saves workspaces under names so you can select one per session.
+
+To create a workspace, press Enter on **Roots** and choose a folder. The workspace is named after that folder, or `name (1)` if the name is taken, and its output folder is `prompt-exports` inside it. Saving creates the output folder if it does not exist. Press Enter on **Roots** again to add or remove folders; a workspace keeps at least one. The other rows change the output folder and edit the ignore rules. **Rename workspace** changes the name; you never have to.
+
+Enter on **Selected workspace** opens the list of saved workspaces. Select one for this session, delete one with Delete, start a new one from a folder, save the workspace the agent last declared in this session, or choose none.
+
+While a workspace is selected, the agent receives its exact declaration in the system prompt, and the extension blocks a build or prepare call that names any other workspace, repeating the declaration in the error. With nothing selected, the agent chooses its own workspace and only your preferences apply. The extension never selects a workspace for you from Pi's current directory or from what the agent sends.
+
+If the selected workspace is renamed or deleted, for example from another session, or `mipmux.json` cannot be read, the extension blocks build and prepare calls until you select a workspace again, and the footer adds `(missing)` or `(file error)` after the name.
+
+## Type paths
+
+Root, output folder and ignore rule rows open a path field with completion. Type a path as in a shell: `~` is your home folder, and a relative path starts at Pi's current directory, or at the root for an ignore rule. Root and output fields open with a suggested folder; Ctrl+U clears it.
+
+Below the field, the first row is the path you typed, when it names something you can choose. The rows after it are the entries of the folder you are typing in that match the name typed so far, best match first. Matching ignores case, so `~/proj` finds `~/Projects`. Hidden entries appear once the name you type starts with a dot.
+
+| Key | Action |
+|---|---|
+| Tab | Complete the typed name to the highlighted entry, as the disk spells it |
+| Shift+Tab | Go up one folder |
+| ↑ ↓ | Highlight another row |
+| Enter | Choose the highlighted row |
+
+While a name is partly typed, the best match is highlighted, so typing a few letters and pressing Enter chooses it.
+
+## Leave paths out or bring them back
+
+**Ignore rules** edits the `.mipmux_ignore` file at each root of the selected workspace. The file uses gitignore syntax, and mipmux reads it in every folder, so you can also edit it by hand or add one in a subfolder. A plain line leaves paths out. A line starting with `!` brings back a path that another ignore file hides, such as `.repo_ignore`, `.cursorignore`, mipmux's built-in patterns or Git's exclude files. Nothing brings back a path that `.gitignore` hides. As in Git, an ignore file in a deeper folder takes precedence over one in a folder above it, so to bring back a path that a subfolder's ignore file hides, add the `!` line to a `.mipmux_ignore` in that subfolder.
+
+In the rule field, type a path inside the root, relative to it, or a pattern such as `*.log`, and put `!` in front to bring the path back. Tab completes the path after the `!`. A chosen path becomes a rule anchored to the root, such as `/node_modules/` or `!docs/investigations/`. Delete removes a highlighted rule. Ctrl+S writes the files you changed, keeping their comments, and refuses to overwrite a file that someone edited while the panel was open.
+
+The rules belong to the folder, not to the saved workspace: every workspace and every client that uses the folder applies them, and RepoPrompt CE does not read them. Commit the file to share the rules, or add `.mipmux_ignore` to your global gitignore to keep it out of Git.
+
+## Set preferences
+
+| Setting | Applies to | Saved with |
+|---|---|---|
+| Budget, in mipmux's estimated units, such as `210000` or `210k` | builds; preparations only when pinned | the session |
+| Enhancement mode: `augment`, `fullRewrite` or `preserve` | builds | the session |
+| Clarification questions from discovery, with an optional timeout | builds in sessions with a UI | the session |
+| Discovery model, from the models mipmux allows | builds | the session or the selected workspace |
+| Thinking level for the discovery model | builds | the session or the selected workspace |
+
+A value you set fills in a setting the agent leaves out. A pinned value replaces the agent's value too. From highest precedence to lowest, a build uses a pinned session value, a pinned workspace value, the agent's value, a session value, a workspace value, and finally the server default.
+
+Session choices are recorded in the session itself: resuming or forking a session restores them, and a new session starts with nothing selected. They do not change mipmux's configuration file or other sessions. Changing a preference changes the request, so repeating an earlier build start under the same output name fails with `outputNameConflict`; the extension adds a note saying so, and a new output name solves it.
+
+## Server defaults
+
+The **Server defaults (all clients)** section edits mipmux's configuration file, whose path the panel names: the budget and enhancement mode of builds that name none, the discovery model and thinking level, and the allowed models. These apply to every client that uses mipmux, not only Pi. A running mipmux rereads them before each build, so a save takes effect at the next build without a reconnect. If `mipmux config` fails, the section is missing and the panel's header says why; if the file sets up no discovery, only the budget and enhancement mode rows appear.
+
+The discovery model and **Allowed models** lists show the models mipmux has credentials for, from `mipmux models`; type to filter them. In **Allowed models**, Enter allows or disallows the highlighted model, and a model that is allowed but has no credentials is marked `no credentials`. Session and workspace model rows offer the discovery model and the allowed models, and mipmux refuses any other.
+
+A save changes only the values you changed and keeps the file's other settings, their order and its indentation. It replaces the file only after `mipmux config` accepts the result, and refuses to overwrite a file that someone edited while the panel was open. Other settings in the file, such as the cache path or discovery credentials, apply when mipmux starts again; reconnect it from `/mcp` after editing them by hand.
+
+## Waiting for a build
+
+A build can take minutes, and Pi delivers a steering message only after the tool call in progress returns. The extension adds a `mipmux_wait` tool, which waits for a job as `context_job` does with `op: "wait"`, takes the same `jobId` and `durationMs`, and returns mipmux's reply. When you send a steering message during the wait, the wait ends at once with a result telling the agent that the job is still running, so the agent reads your message straight away and waits again afterwards. The job itself never stops, and the interrupted wait leaves no row in Pi's terminal interface; your message appears in its place.
+
+The extension blocks `context_job` waits, including those in codemode scripts, with a message that tells the agent to use `mipmux_wait`; status, answers, cancellation and disposal still go through `context_job`. A steering message counts when you send it from Pi's terminal or an RPC client, or when the [pi-queue-steer](https://github.com/tmustier/pi-queue-steer) extension accepts it into its queue. Codemode scripts cannot call `mipmux_wait`, so the agent waits with a direct call.
+
+## Footer
+
+While the extension is loaded, Pi's footer shows `mipmux:` and the selected workspace, or `mipmux: no workspace`. The panel's last row, **Show in footer** under **Display**, turns this item on or off for all your sessions. The session where you save applies it at once; other open sessions apply it before their next prompt.
+
+## Storage
+
+Saved workspaces and the footer setting are stored in `mipmux.json` in Pi's agent directory (`~/.pi/agent`, or `$PI_CODING_AGENT_DIR`) and shared by all your sessions. The footer setting is its `showInFooter` field; a file without it shows the footer item. A session keeps only the name it selected, so an edit reaches every session on its next call. Saving applies only the workspaces you added, changed or deleted, so changes another session saved while the panel was open remain. Two saved workspaces with the same root folders and output folder, in any order and under any names, are duplicates: saving keeps the earlier one, with its name, discovery model and thinking level, and the panel says which it removed.
+
+## Limits
+
+- The extension sees calls that pass through Pi's tool pipeline, including calls from codemode scripts, under the tool names that Pi's built-in MCP support gives a server named `mipmux`: `mcp__mipmux__context_builder` and `mcp__mipmux__context_prepare`. Calls another extension makes outside Pi's tool pipeline bypass it.
+- The panel reads and edits the configuration file that `mipmux config` reports when run from your PATH, and names it at the top. By default that is `~/.config/mipmux/config.json`, or `$XDG_CONFIG_HOME/mipmux/config.json`. If Pi starts mipmux with `--config` or a different `XDG_CONFIG_HOME`, the server uses another file, and the panel's server defaults and model lists do not describe that server.
+- Without a UI, the clarification preference is not applied.
+
+## Development
+
+```sh
+npm test
+npm run typecheck
+```
+
+Both run from this directory and use the TypeScript, TypeBox and Pi packages installed in the mipmux checkout. Two tests run Pi in RPC mode with a scripted model and a stand-in mipmux server.
+
+The oh-my-pi extension in [`integrations/omp`](https://github.com/w-winter/mipmux/tree/main/integrations/omp#readme) copies every module in `src` except `extension.ts`, `routes.ts` and `wait.ts`, so after changing one, run that package's checks too.
+
+To run the extension from a checkout instead of npm, install it by path: `pi install /absolute/path/to/mipmux/integrations/pi`.

package/package.json

@@ -1,6 +1,22 @@
 {
   "name": "pi-mipmux",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Pi extension that selects a saved mipmux workspace and applies build preferences to mipmux calls",
+  "license": "Apache-2.0",
+  "repository": { "type": "git", "url": "git+https://github.com/w-winter/mipmux.git", "directory": "integrations/pi" },
+  "homepage": "https://github.com/w-winter/mipmux/tree/main/integrations/pi#readme",
+  "bugs": "https://github.com/w-winter/mipmux/issues",
+  "type": "module",
+  "keywords": ["pi-package"],
+  "files": ["src"],
+  "pi": { "extensions": ["./src/extension.ts"] },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "typecheck": "tsc -p tsconfig.json"
+  }
+}

package/src/config.ts

@@ -0,0 +1,47 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import Type, { type Static } from 'typebox';
+import { Compile } from 'typebox/compile';
+import { EnhancementMode, ModelReference, ThinkingLevel } from './state.ts';
+
+/** The global defaults `mipmux config` prints: what a build uses for every setting no request or preference names. */
+const MipmuxConfig = Type.Object({ kind: Type.Literal('config'), path: Type.String(), contextBudgetUnits: Type.Integer({ minimum: 1 }),
+  defaultEnhancementMode: EnhancementMode, tools: Type.Enum(['core', 'full']),
+  discovery: Type.Union([Type.Null(), Type.Object({ model: ModelReference, thinking: ThinkingLevel, allowedModels: Type.Array(ModelReference) },
+    { additionalProperties: false })]) }, { additionalProperties: false });
+export type MipmuxConfig = Static<typeof MipmuxConfig>;
+/** The mipmux commands the extension runs: `config` reports the file at `path`, or the default file, and fails when mipmux rejects it. */
+export interface MipmuxCommands {
+  config(path?: string): Promise<MipmuxConfig>;
+  models(path: string): Promise<string[]>;
+}
+const configValidator = Compile(MipmuxConfig);
+
+/**
+ * Runs `mipmux config` from PATH, as an MCP client configured with `mipmux mcp` starts the server, so the defaults shown
+ * are the ones a newly started server reads. Fails with mipmux's error code, or with the reason the command could not run.
+ */
+export async function readMipmuxConfig(path?: string): Promise<MipmuxConfig> {
+  const value: unknown = JSON.parse(await mipmux(['config', ...(path === undefined ? [] : ['--config', path])]));
+  if (!configValidator.Check(value)) throw new Error('mipmux config printed an unexpected result; update mipmux or the mipmux extension');
+  return value;
+}
+
+/** Runs mipmux from PATH and returns its output; fails with mipmux's error report, or with the reason the command could not run. */
+async function mipmux(args: readonly string[]): Promise<string> {
+  try { return (await promisify(execFile)('mipmux', [...args])).stdout; }
+  catch (error) {
+    // mipmux reports its failures as JSON on stdout; a command that never ran reports through the error message.
+    const stdout = error instanceof Error && 'stdout' in error ? String(error.stdout).trim() : '';
+    throw new Error(`mipmux ${args[0]} failed: ${stdout || (error instanceof Error ? error.message : 'unknown error')}`, { cause: error });
+  }
+}
+
+const ModelList = Compile(Type.Object({ kind: Type.Literal('models'), models: Type.Array(ModelReference) }, { additionalProperties: false }));
+
+/** The discovery models mipmux can use with its configured credentials, from `mipmux models`. */
+export async function readMipmuxModels(path: string): Promise<string[]> {
+  const value: unknown = JSON.parse(await mipmux(['models', '--config', path]));
+  if (!ModelList.Check(value)) throw new Error('mipmux models printed an unexpected result; update mipmux or the mipmux extension');
+  return value.models;
+}

package/src/draft.ts

@@ -0,0 +1,101 @@
+import { basename } from 'node:path';
+import type { ServerDefaults } from './server-config.ts';
+import type { Store } from './store.ts';
+import { type Preferences, type SavedWorkspace, type SessionState, type Workspace } from './state.ts';
+
+/*
+ * The panel's unsaved changes. The panel edits a draft and writes it only on ctrl+s; closing discards it. A save applies
+ * only the saved workspaces the panel added, changed or deleted, so changes another session saved meanwhile survive, and
+ * writes only the `.mipmux_ignore` files the panel changed.
+ */
+/** A saved workspace in the draft; `origin` is its name in the file when the panel read it, or null for a new one. */
+export interface DraftEntry { readonly origin: string | null; readonly workspace: SavedWorkspace }
+/** The complete new lines of one root's `.mipmux_ignore`. */
+export interface IgnoreEdit { readonly root: string; readonly lines: readonly string[] }
+export interface Draft {
+  readonly entries: readonly DraftEntry[];
+  readonly selected: string | null;
+  readonly preferences: Preferences;
+  readonly ignoreEdits: readonly IgnoreEdit[];
+  /** mipmux's request defaults, or null when `mipmux config` could not report them. */
+  readonly server: ServerDefaults | null;
+  /** Whether every session shows the footer item. */
+  readonly showInFooter: boolean;
+}
+const rootNamePattern = /^[A-Za-z][A-Za-z0-9_-]*$/;
+
+export function openDraft(store: Store, state: SessionState, server: ServerDefaults | null): Draft {
+  return { entries: store.workspaces.map(workspace => ({ origin: workspace.name, workspace })), selected: state.selected,
+    preferences: state.preferences, ignoreEdits: [], server, showInFooter: store.showInFooter };
+}
+
+export function selectedWorkspace(draft: Draft): SavedWorkspace | null {
+  return draft.entries.find(entry => entry.workspace.name === draft.selected)?.workspace ?? null;
+}
+
+/** `base`, or `base (1)`, `base (2)` and so on, whichever is free first, as RepoPrompt CE names workspaces. */
+export function uniqueName(base: string, taken: readonly string[]): string {
+  let name = base;
+  for (let counter = 1; taken.includes(name); counter++) name = `${base} (${counter})`;
+  return name;
+}
+
+/** A root name from the folder's name, in the form mipmux accepts, distinct from the workspace's other roots. */
+function rootName(path: string, roots: Workspace['roots']): string {
+  const cleaned = basename(path).replace(/[^A-Za-z0-9_-]/g, '-');
+  const base = rootNamePattern.test(cleaned) ? cleaned : `root-${cleaned}`;
+  let name = base;
+  for (let counter = 2; roots.some(root => root.name === name); counter++) name = `${base}-${counter}`;
+  return name;
+}
+
+/** Adds the roots and output folder of `workspace`, such as one the agent declared, under a name taken from its first root, and selects it. */
+export function addWorkspace(draft: Draft, workspace: Pick<Workspace, 'roots' | 'outputRoot'>): Draft {
+  const first = workspace.roots[0]?.absolutePath ?? 'workspace';
+  const name = uniqueName(basename(first), draft.entries.map(entry => entry.workspace.name));
+  const added: SavedWorkspace = { name, roots: workspace.roots, outputRoot: workspace.outputRoot };
+  return { ...draft, entries: [...draft.entries, { origin: null, workspace: added }], selected: name };
+}
+
+/** A new saved workspace with one root, `<root>/prompt-exports` as its output folder, named after the root and selected. */
+export function createFromFolder(draft: Draft, folder: string): Draft {
+  return addWorkspace(draft, { roots: [{ name: rootName(folder, []), absolutePath: folder }], outputRoot: `${folder}/prompt-exports` });
+}
+
+/** Replaces the selected saved workspace with `change(workspace)`. */
+export function editSelected(draft: Draft, change: (workspace: SavedWorkspace) => SavedWorkspace): Draft {
+  return { ...draft, entries: draft.entries.map(entry => entry.workspace.name === draft.selected ? { ...entry, workspace: change(entry.workspace) } : entry) };
+}
+
+export function addRoot(workspace: SavedWorkspace, folder: string): SavedWorkspace {
+  return { ...workspace, roots: [...workspace.roots, { name: rootName(folder, workspace.roots), absolutePath: folder }] };
+}
+
+export function removeRoot(workspace: SavedWorkspace, name: string): SavedWorkspace {
+  return { ...workspace, roots: workspace.roots.filter(root => root.name !== name) };
+}
+
+/** Renames the selected saved workspace; fails with a reason when the name is empty or taken. */
+export function renameSelected(draft: Draft, name: string): Draft | { readonly problem: string } {
+  if (!name) return { problem: 'A name needs at least one character.' };
+  if (name !== draft.selected && draft.entries.some(entry => entry.workspace.name === name)) return { problem: `"${name}" is already saved.` };
+  return { ...editSelected(draft, workspace => ({ ...workspace, name })), selected: name };
+}
+
+export function deleteWorkspace(draft: Draft, name: string): Draft {
+  return { ...draft, entries: draft.entries.filter(entry => entry.workspace.name !== name), selected: draft.selected === name ? null : draft.selected };
+}
+
+/**
+ * The draft's additions, edits and deletions applied to the saved workspaces as the file holds them now: an edit keeps its
+ * entry's place, and a new workspace, or one another session deleted meanwhile, is added at the end.
+ */
+export function applyDraft(stored: readonly SavedWorkspace[], draft: Draft, snapshot: readonly SavedWorkspace[]): SavedWorkspace[] {
+  const unchanged = (entry: DraftEntry) => snapshot.some(saved => saved.name === entry.origin && JSON.stringify(saved) === JSON.stringify(entry.workspace));
+  const changed = draft.entries.filter(entry => !unchanged(entry));
+  const deleted = snapshot.filter(saved => !draft.entries.some(entry => entry.origin === saved.name)).map(saved => saved.name);
+  const kept = stored.filter(saved => !deleted.includes(saved.name))
+    .map(saved => changed.find(entry => entry.origin === saved.name)?.workspace ?? saved);
+  const added = changed.filter(entry => entry.origin === null || !stored.some(saved => saved.name === entry.origin));
+  return [...kept, ...added.map(entry => entry.workspace)];
+}

package/src/extension.ts

@@ -0,0 +1,31 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { getAgentDir, type ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { readMipmuxConfig, readMipmuxModels } from './config.ts';
+import { createMipmux, entryType, workspaceSection } from './register.ts';
+import { registerSteerableWait } from './wait.ts';
+
+/** Registers the /mipmux command and the handlers that apply this session's mipmux choices to the agent's calls. */
+export default function mipmux(pi: ExtensionAPI): void {
+  const extension = createMipmux({ storePath: join(getAgentDir(), 'mipmux.json'), home: homedir(), mipmux: { config: readMipmuxConfig, models: readMipmuxModels },
+    appendEntry: state => { pi.appendEntry(entryType, state); } });
+  pi.on('session_start', (_event, ctx) => extension.restore(ctx));
+  pi.on('session_tree', (_event, ctx) => extension.restore(ctx));
+  pi.on('before_agent_start', async (event, ctx) => {
+    const workspace = await extension.beforeAgentStart(ctx);
+    if (workspace !== null) event.systemPromptOptions.sections[workspaceSection] = workspace;
+  });
+  // Pi runs a call with the arguments as handlers left them, so the edits made in place need no result.
+  pi.on('tool_call', async (event, ctx) => {
+    const decision = await extension.toolCall(event, ctx);
+    return decision.kind === 'blocked' ? { block: true, reason: decision.reason } : undefined;
+  });
+  pi.on('tool_result', event => {
+    const content = extension.toolResult(event);
+    if (content === undefined) return undefined;
+    return event.structuredContent === undefined ? { content } : { content, structuredContent: event.structuredContent };
+  });
+  registerSteerableWait(pi);
+  pi.registerCommand('mipmux', { description: 'Select a saved mipmux workspace and set build preferences',
+    getArgumentCompletions: prefix => extension.completions(prefix), handler: (args, ctx) => extension.command(args, ctx) });
+}

package/src/ignore-file.ts

@@ -0,0 +1,82 @@
+import { randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { readFile, rename, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, relative } from 'node:path';
+import { expand, resolveExisting, type PathBase, type PathEntry } from './paths.ts';
+
+/*
+ * A root's `.mipmux_ignore`, in gitignore syntax. mipmux reads one in every folder; the panel edits the one at each root.
+ * Its rules belong to the folder, so they apply to every workspace and client that uses it.
+ */
+export const ignoreFileName = '.mipmux_ignore';
+const globCharacters = /[*?[\]]/;
+/** The lines of a root's `.mipmux_ignore` as the panel read them, or why it could not read them. */
+export type IgnoreFile = { readonly kind: 'read'; readonly lines: readonly string[] } | { readonly kind: 'unreadable'; readonly problem: string };
+/** A line the picker would add, or why it refuses the typed text. */
+export type RuleChoice = { readonly kind: 'rule'; readonly line: string } | { readonly kind: 'refused'; readonly reason: string };
+
+export const ignoreFilePath = (root: string) => join(root, ignoreFileName);
+/** A line that is a rule rather than a blank line or a comment. */
+export const isRule = (line: string) => line.trim() !== '' && !line.startsWith('#');
+
+function lines(text: string): string[] {
+  const split = text.split('\n');
+  return split.at(-1) === '' ? split.slice(0, -1) : split;
+}
+
+/** Reads a root's file; a missing file has no lines. */
+export function readIgnoreFile(root: string): IgnoreFile {
+  try { return { kind: 'read', lines: lines(readFileSync(ignoreFilePath(root), 'utf8')) }; }
+  catch (error) {
+    if (error instanceof Error && 'code' in error && error.code === 'ENOENT') return { kind: 'read', lines: [] };
+    return { kind: 'unreadable', problem: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+/**
+ * Replaces a root's file with `next`. Fails, writing nothing, when the file no longer holds `read`, so a hand edit made
+ * while the panel was open is never overwritten.
+ */
+export async function writeIgnoreFile(root: string, read: readonly string[], next: readonly string[]): Promise<void> {
+  const path = ignoreFilePath(root);
+  const current = await readFile(path, 'utf8').then(lines, (error: Error & { code?: string }) => {
+    if (error.code === 'ENOENT') return [];
+    throw error;
+  });
+  if (JSON.stringify(current) !== JSON.stringify(read)) throw new Error(`${path} changed while the panel was open; close the panel and open it again.`);
+  const temporary = join(root, `.mipmux_ignore.${randomUUID()}`);
+  await writeFile(temporary, next.map(line => `${line}\n`).join(''));
+  await rename(temporary, path);
+}
+
+/** The rule for a path inside `root`: relative to it, anchored to it, and ending in `/` for a folder. */
+function pathRule(root: string, path: string, folder: boolean): string | null {
+  const under = relative(root, path);
+  if (!under || under.startsWith('..') || isAbsolute(under)) return null;
+  return (under.includes('/') ? under : `/${under}`) + (folder ? '/' : '');
+}
+
+/** The rule for a completion the user chose; `negated` brings the path back instead of leaving it out. */
+export function entryRule(root: string, entry: PathEntry, negated: boolean): string {
+  const found = resolveExisting(entry.path);
+  return (negated ? '!' : '') + (pathRule(root, found.path, found.kind === 'folder') ?? entry.name);
+}
+
+/**
+ * The rule for typed text. A leading `!` brings paths back. A path that exists inside the root becomes a rule anchored to
+ * the root; `~` or an absolute path must lie inside it. Anything else, such as `*.log` or a path that does not exist yet,
+ * is kept as a gitignore pattern as typed.
+ */
+export function typedRule(text: string, base: PathBase): RuleChoice {
+  if (text.startsWith('#')) return { kind: 'refused', reason: 'A line starting with # is a comment, not a rule.' };
+  const negated = text.startsWith('!'), body = negated ? text.slice(1) : text, marker = negated ? '!' : '';
+  if (!body) return { kind: 'refused', reason: 'Type a path or a pattern.' };
+  if (globCharacters.test(body)) return { kind: 'rule', line: marker + body };
+  const found = resolveExisting(expand(body, base));
+  const rule = found.kind === 'missing' ? null : pathRule(base.base, found.path, found.kind === 'folder');
+  if (rule) return { kind: 'rule', line: marker + rule };
+  if (body.startsWith('~') || (isAbsolute(body) && found.kind !== 'missing')) {
+    return { kind: 'refused', reason: `That path is outside ${base.base}.` };
+  }
+  return { kind: 'rule', line: marker + body };
+}