multi-agent-prompt 0.1.0__py3-none-any.whl

multi_agent_prompt/__init__.py

@@ -0,0 +1,3 @@
+"""multi-agent-prompt: a crash-proof, autosaving prompt editor for AI coding agent CLIs."""
+
+__version__ = "0.1.0"

multi_agent_prompt/archive.py

@@ -0,0 +1,91 @@
+"""Archive-on-clear: never actually lose a draft, just retire it.
+
+Clearing the scratch file — via ``map clear`` or the in-editor keymap — first
+copies the current content into a rolling, per-project archive, then prunes
+that archive down to the most recent ``keep`` entries (by count, not age:
+"keep the last N drafts" is simpler to reason about and configure than a
+retention window, and doesn't depend on the clock).
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+
+from multi_agent_prompt.paths import ARCHIVE_DIRNAME
+
+DEFAULT_ARCHIVE_KEEP = 10
+KEEP_ENV_VAR = "MAP_ARCHIVE_KEEP"
+
+
+def resolve_archive_keep(override: int | None = None) -> int:
+    """CLI flag > MAP_ARCHIVE_KEEP env var > default (10)."""
+    if override is not None:
+        return override
+    raw = os.environ.get(KEEP_ENV_VAR)
+    if raw:
+        try:
+            return int(raw)
+        except ValueError:
+            pass
+    return DEFAULT_ARCHIVE_KEEP
+
+
+def _next_archive_path(directory: Path) -> Path:
+    """A path in ``directory``, guaranteed to sort after every existing entry.
+
+    The human-readable timestamp prefix is cosmetic; the nanosecond epoch
+    suffix is what actually guarantees both uniqueness and correct
+    chronological ordering. It must not be a "does this filename already
+    exist" counter starting from 0/1/2... — pruning deletes old, *low*
+    sequence numbers, so a fresh counter starting from 0 would reuse a freed
+    slot for a brand-new file, making a just-created draft sort as the
+    *oldest* entry and get immediately pruned by mistake. `time.time_ns()`
+    is (for this purpose) always increasing, so a collision is only ever
+    possible when the clock genuinely hasn't ticked between two calls —
+    handled by incrementing, never by restarting from a fresh, reusable base.
+    """
+    stamp = time.strftime("%Y%m%dT%H%M%S")
+    ns = time.time_ns()
+    candidate = directory / f"{stamp}-{ns}.md"
+    while candidate.exists():
+        ns += 1
+        candidate = directory / f"{stamp}-{ns}.md"
+    return candidate
+
+
+def prune_archive(directory: Path, keep: int) -> list[Path]:
+    """Delete all but the ``keep`` most recent archived drafts. Returns what was removed."""
+    if not directory.is_dir() or keep < 0:
+        return []
+    files = sorted(directory.glob("*.md"))
+    excess = files if keep == 0 else files[:-keep]
+    for f in excess:
+        f.unlink()
+    return excess
+
+
+def archive_and_clear(
+    file: Path,
+    keep: int = DEFAULT_ARCHIVE_KEEP,
+    archive: bool = True,
+) -> Path | None:
+    """Archive ``file``'s current content (unless empty or ``archive=False``), then truncate it.
+
+    Returns the path it archived to, or None if there was nothing to archive
+    (empty/missing file, or ``archive=False``).
+    """
+    content = file.read_text(encoding="utf-8") if file.exists() else ""
+    archived_to = None
+
+    if archive and content.strip():
+        adir = file.parent / ARCHIVE_DIRNAME
+        adir.mkdir(parents=True, exist_ok=True)
+        archived_to = _next_archive_path(adir)
+        archived_to.write_text(content, encoding="utf-8")
+        prune_archive(adir, keep)
+
+    file.parent.mkdir(parents=True, exist_ok=True)
+    file.write_text("", encoding="utf-8")
+    return archived_to

multi_agent_prompt/cli.py

@@ -0,0 +1,338 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+import verkit
+from rich.console import Console
+
+from multi_agent_prompt import archive, paths
+from multi_agent_prompt.editor import (
+    DEFAULT_CLEAR_KEY,
+    DEFAULT_DEBOUNCE_MS,
+    DEFAULT_FOLD_THRESHOLD,
+    DEFAULT_HELP_KEY,
+    DEFAULT_HISTORY_KEY,
+    nvim_available,
+    open_editor,
+)
+
+PACKAGE_NAME = "multi-agent-prompt"
+
+
+def cmd_edit(args: argparse.Namespace) -> int:
+    file = paths.prompt_file()
+    if not nvim_available(args.nvim_bin):
+        print(
+            f"error: '{args.nvim_bin}' not found on PATH. "
+            "multi-agent-prompt's autosave relies on Neovim's Lua API "
+            "(https://neovim.io/) — plain Vim isn't supported.",
+            file=sys.stderr,
+        )
+        return 1
+
+    if paths.ensure_gitignored():
+        print(f"Added {paths.GITIGNORE_PATTERN} to .gitignore", file=sys.stderr)
+
+    return open_editor(
+        file,
+        debounce_ms=args.debounce,
+        nvim_bin=args.nvim_bin,
+        clean=args.clean,
+        clear_key=None if args.no_clear_key else args.clear_key,
+        history_key=None if args.no_history_key else args.history_key,
+        help_key=None if args.no_help_key else args.help_key,
+        fold_threshold=None if args.no_fold_paste else args.fold_threshold,
+        insert=not args.no_insert,
+    )
+
+
+def cmd_where(args: argparse.Namespace) -> int:
+    print(paths.prompt_file())
+    return 0
+
+
+def cmd_show(args: argparse.Namespace) -> int:
+    file = paths.prompt_file()
+    if not file.exists():
+        return 0
+    sys.stdout.write(file.read_text(encoding="utf-8"))
+    return 0
+
+
+def cmd_clear(args: argparse.Namespace) -> int:
+    file = paths.prompt_file()
+    keep = archive.resolve_archive_keep(args.keep)
+    archived_to = archive.archive_and_clear(file, keep=keep, archive=not args.no_archive)
+
+    if archived_to is not None:
+        print(f"Archived previous draft to {archived_to}", file=sys.stderr)
+    print(f"Cleared {file}", file=sys.stderr)
+    return 0
+
+
+def cmd_pop(args: argparse.Namespace) -> int:
+    """Read the draft, archive it, clear the file, and print what was read — one operation.
+
+    This is what `/prompt` uses: hand the draft off and reset for the next
+    one in a single step, so there's no separate "now go clear it" the user
+    has to remember to do.
+    """
+    file = paths.prompt_file()
+    content = file.read_text(encoding="utf-8") if file.exists() else ""
+    keep = archive.resolve_archive_keep(args.keep)
+    archive.archive_and_clear(file, keep=keep, archive=not args.no_archive)
+    sys.stdout.write(content)
+    return 0
+
+
+def cmd_version(args: argparse.Namespace) -> int:
+    """Show version, promote it, tag it, or run a full release — via verkit.
+
+    Mirrors task-agent's `ta version` surface (verkit is the shared
+    version-management library across this developer's projects): bare
+    `map version` shows installed vs. latest-on-PyPI; `promote` bumps
+    semver and commits; `tag` tags HEAD from the committed version and
+    pushes; `release` does both atomically.
+    """
+    console = Console()
+    verkit.display_version_info(console, PACKAGE_NAME)
+
+    try:
+        if args.version_command == "release":
+            new_v = verkit.promote_version(args.part, console=console)
+            console.print(f"[blue]Release {new_v}: tagging and pushing...[/blue]")
+            verkit.tag_version(console=console, push=args.push, push_branch=args.push_branch)
+            console.print(f"[bold green]Release v{new_v} complete.[/bold green]")
+        elif args.version_command == "promote":
+            new_v = verkit.promote_version(args.part, console=console)
+            console.print(
+                "[dim]Next: map version tag[/dim]  "
+                "[dim](or use map version release for one-shot)[/dim]"
+            )
+            console.print(f"[dim]HEAD is now v{new_v}; tag when ready to publish.[/dim]")
+        elif args.version_command == "tag":
+            verkit.tag_version(console=console, push=args.push, push_branch=args.push_branch)
+    except SystemExit:
+        raise
+    except Exception as e:  # noqa: BLE001 - deliberate top-level boundary for verkit's git/subprocess errors
+        console.print(f"[red]Error during version operation: {e}[/red]")
+        return 1
+
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="map",
+        description=(
+            "A crash-proof, autosaving prompt editor for AI coding agent CLIs. "
+            "Compose in your real Neovim in a split pane; hand off to the chat "
+            "with /prompt or @prompt.md."
+        ),
+    )
+    parser.add_argument(
+        "-V", "--version", action="store_true", help="Show version and exit"
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    edit_parser = subparsers.add_parser(
+        "edit", help="Open the project's scratch prompt file (default command)"
+    )
+    edit_parser.add_argument(
+        "--debounce",
+        type=int,
+        default=DEFAULT_DEBOUNCE_MS,
+        help=f"Autosave debounce in milliseconds (default: {DEFAULT_DEBOUNCE_MS})",
+    )
+    edit_parser.add_argument(
+        "--nvim-bin",
+        default="nvim",
+        help="Neovim binary to launch (default: nvim)",
+    )
+    edit_parser.add_argument(
+        "--clean",
+        action="store_true",
+        help="Skip the user's init.lua entirely (-u NONE) for faster startup",
+    )
+    edit_parser.add_argument(
+        "--clear-key",
+        default=DEFAULT_CLEAR_KEY,
+        help=f"Buffer-local normal-mode keymap that archives and clears (default: {DEFAULT_CLEAR_KEY})",
+    )
+    edit_parser.add_argument(
+        "--no-clear-key",
+        action="store_true",
+        help="Don't register the in-editor clear keymap at all",
+    )
+    edit_parser.add_argument(
+        "--history-key",
+        default=DEFAULT_HISTORY_KEY,
+        help=(
+            "Buffer-local normal-mode keymap that opens the archive directory "
+            f"(read-only) in a split (default: {DEFAULT_HISTORY_KEY})"
+        ),
+    )
+    edit_parser.add_argument(
+        "--no-history-key",
+        action="store_true",
+        help="Don't register the in-editor archive-browsing keymap at all",
+    )
+    edit_parser.add_argument(
+        "--help-key",
+        default=DEFAULT_HELP_KEY,
+        help=(
+            "Buffer-local normal-mode keymap that shows a cheatsheet of "
+            f"whichever keymaps are active (default: {DEFAULT_HELP_KEY})"
+        ),
+    )
+    edit_parser.add_argument(
+        "--no-help-key",
+        action="store_true",
+        help="Don't register the in-editor help keymap at all",
+    )
+    edit_parser.add_argument(
+        "--fold-threshold",
+        type=int,
+        default=DEFAULT_FOLD_THRESHOLD,
+        help=(
+            "Auto-fold a paste of this many lines or more, closed by default "
+            f"(za/zo/zc to toggle) (default: {DEFAULT_FOLD_THRESHOLD})"
+        ),
+    )
+    edit_parser.add_argument(
+        "--no-fold-paste",
+        action="store_true",
+        help="Don't auto-fold large pastes at all",
+    )
+    edit_parser.add_argument(
+        "--no-insert",
+        action="store_true",
+        help="Open in normal mode instead of dropping straight into insert mode",
+    )
+    edit_parser.set_defaults(func=cmd_edit)
+
+    where_parser = subparsers.add_parser(
+        "where", help="Print the resolved scratch prompt file path"
+    )
+    where_parser.set_defaults(func=cmd_where)
+
+    show_parser = subparsers.add_parser(
+        "show", help="Print the scratch prompt file's current content"
+    )
+    show_parser.set_defaults(func=cmd_show)
+
+    pop_parser = subparsers.add_parser(
+        "pop",
+        help="Print the current draft, archive it, and clear the file — one operation",
+    )
+    pop_parser.add_argument(
+        "--keep",
+        type=int,
+        default=None,
+        help=(
+            f"How many archived drafts to retain (default: {archive.DEFAULT_ARCHIVE_KEEP}, "
+            f"or ${archive.KEEP_ENV_VAR})"
+        ),
+    )
+    pop_parser.add_argument(
+        "--no-archive",
+        action="store_true",
+        help="Discard the draft instead of archiving it (e.g. it contained a secret)",
+    )
+    pop_parser.set_defaults(func=cmd_pop)
+
+    clear_parser = subparsers.add_parser(
+        "clear", help="Archive the current draft, then empty the scratch prompt file"
+    )
+    clear_parser.add_argument(
+        "--keep",
+        type=int,
+        default=None,
+        help=(
+            f"How many archived drafts to retain (default: {archive.DEFAULT_ARCHIVE_KEEP}, "
+            f"or ${archive.KEEP_ENV_VAR})"
+        ),
+    )
+    clear_parser.add_argument(
+        "--no-archive",
+        action="store_true",
+        help="Discard the current draft instead of archiving it first (e.g. it contained a secret)",
+    )
+    clear_parser.set_defaults(func=cmd_clear)
+
+    version_parser = subparsers.add_parser(
+        "version", help="Show version, promote, tag, or run a full release"
+    )
+    v_sub = version_parser.add_subparsers(dest="version_command")
+    promote_parser = v_sub.add_parser(
+        "promote",
+        help=(
+            "Bump semver and commit it (amends only if HEAD is unpushed/untagged; "
+            "otherwise creates chore(release): vX.Y.Z)"
+        ),
+    )
+    promote_parser.add_argument("part", choices=["major", "minor", "patch"])
+    version_tag_parser = v_sub.add_parser(
+        "tag",
+        help="Tag HEAD as vX.Y.Z from committed version; push branch then tag",
+    )
+    version_tag_parser.add_argument(
+        "--no-push",
+        dest="push",
+        action="store_false",
+        help="Create the local tag only (do not push branch or tag)",
+    )
+    version_tag_parser.add_argument(
+        "--no-push-branch",
+        dest="push_branch",
+        action="store_false",
+        help="When pushing, push only the tag (not the branch)",
+    )
+    version_tag_parser.set_defaults(push=True, push_branch=True)
+    version_release_parser = v_sub.add_parser(
+        "release", help="Atomic promote + tag + push branch + push tag"
+    )
+    version_release_parser.add_argument("part", choices=["major", "minor", "patch"])
+    version_release_parser.add_argument(
+        "--no-push",
+        dest="push",
+        action="store_false",
+        help="Promote and tag locally only",
+    )
+    version_release_parser.set_defaults(push=True, push_branch=True)
+    version_parser.set_defaults(func=cmd_version)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.version:
+        verkit.display_version_info(Console(), PACKAGE_NAME)
+        sys.exit(0)
+
+    if args.command is None:
+        # Bare `map` == `map edit` with defaults.
+        args.command = "edit"
+        args.debounce = DEFAULT_DEBOUNCE_MS
+        args.nvim_bin = "nvim"
+        args.clean = False
+        args.clear_key = DEFAULT_CLEAR_KEY
+        args.no_clear_key = False
+        args.history_key = DEFAULT_HISTORY_KEY
+        args.no_history_key = False
+        args.help_key = DEFAULT_HELP_KEY
+        args.no_help_key = False
+        args.fold_threshold = DEFAULT_FOLD_THRESHOLD
+        args.no_fold_paste = False
+        args.no_insert = False
+        args.func = cmd_edit
+
+    sys.exit(args.func(args))
+
+
+if __name__ == "__main__":
+    main()

multi_agent_prompt/editor.py

@@ -0,0 +1,315 @@
+"""Launch the user's real Neovim on the scratch prompt file, with autosave bolted on.
+
+This deliberately does not touch the user's ``init.lua`` or try to
+reimplement Vim: it loads their actual config as-is (so keymaps, colorscheme,
+and plugins "just work" without any import step) and layers small additions
+on top via ``-c``. Each ``map`` invocation is its own throwaway nvim
+process, so none of this can ever reach the user's other, real nvim
+sessions — but not everything below is *buffer*-local within this one
+session; see fold-on-paste.
+
+  * Autosave, debounced (``debounce_ms`` after the last edit) — the everyday
+    case — and immediately on ``FocusLost``/``BufLeave``, so switching to the
+    chat pane to hand the prompt off never races the debounce timer.
+  * Auto-reload on ``FocusGained``/``BufEnter``: the counterpart to the
+    above. Handing a draft off (e.g. via `/prompt`, which runs `map pop`
+    from the *agent's* process, not this nvim) clears the file from outside
+    this editor session — without this, the buffer you're still looking at
+    would keep showing the old, already-submitted text until you touched it.
+  * A ``clear_key`` mapping that archives the current draft (via ``map
+    clear``, so the CLI and the in-editor keymap share one implementation)
+    and reloads the now-empty buffer.
+  * A ``history_key`` mapping that lists archived drafts (newest first) in a
+    scratch split — ``<CR>`` opens one, read-only. Deliberately not
+    `:vsplit <archive_dir>` / netrw: netrw's directory browsing isn't
+    available at all under ``-u NONE`` (confirmed directly — even
+    `:Explore` is "not an editor command" there), and under a full config
+    it may be intercepted by whatever directory-handling plugin (neo-tree,
+    oil.nvim, ...) the user has, which is inconsistent with ``--clean``.
+    This tiny listing works identically either way.
+  * Fold-on-paste: pasting ``fold_threshold`` lines or more (bracketed
+    paste, `"+p`, `"*p`, ...) automatically folds (and closes) just those
+    lines, via Neovim's ``vim.paste()`` override — so dropping a long CLI
+    transcript or diff into the buffer doesn't bury the rest of what you're
+    writing. Standard Vim fold commands (``za``/``zo``/``zc``) toggle it;
+    nothing new to bind for that part. ``vim.paste`` is a *global* hook, not
+    a buffer-local option — this does apply to any other buffer opened
+    within this same throwaway session (e.g. one opened via the history
+    keymap), which is fine here since every buffer in this session is
+    another scratch markdown file.
+
+The launched nvim gets ``MAP_SESSION=1`` in its environment — nothing in
+this package reads it, but it's there for a user who wants to guard an
+expensive line in their own init.lua (e.g. a `clipboard=unnamedplus` setting
+that's slow specifically under WSL) behind ``if not vim.env.MAP_SESSION``,
+without multi-agent-prompt ever touching that file itself.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from multi_agent_prompt.paths import ARCHIVE_DIRNAME
+
+DEFAULT_DEBOUNCE_MS = 2000
+DEFAULT_NVIM_BIN = "nvim"
+DEFAULT_CLEAR_KEY = "<leader>pc"
+DEFAULT_HISTORY_KEY = "<leader>ph"
+DEFAULT_HELP_KEY = "g?"
+DEFAULT_FOLD_THRESHOLD = 6
+
+
+def build_autosave_lua(
+    debounce_ms: int = DEFAULT_DEBOUNCE_MS,
+    clear_key: str | None = DEFAULT_CLEAR_KEY,
+    history_dir: Path | None = None,
+    history_key: str | None = DEFAULT_HISTORY_KEY,
+    help_key: str | None = DEFAULT_HELP_KEY,
+    fold_threshold: int | None = DEFAULT_FOLD_THRESHOLD,
+) -> str:
+    """Lua snippet, scoped to the current buffer only.
+
+    Always: autosave (debounced + on focus-lost) and auto-reload on
+    focus-gained. Optionally: the clear keymap, the archive-browsing keymap
+    (when ``history_dir`` is given), fold-on-paste (when ``fold_threshold``
+    is a positive int), and a ``g?`` cheatsheet listing whichever of those
+    are actually active — reflecting real overrides, not just the defaults,
+    since it's built from the same values passed in here.
+    """
+    lua = f"""
+local uv = vim.uv or vim.loop
+local timer = uv.new_timer()
+local function save_now()
+  if vim.bo.modified then
+    vim.cmd("silent! write")
+  end
+end
+vim.api.nvim_create_autocmd({{"TextChanged", "TextChangedI"}}, {{
+  buffer = 0,
+  callback = function()
+    timer:stop()
+    timer:start({debounce_ms}, 0, vim.schedule_wrap(save_now))
+  end,
+}})
+vim.api.nvim_create_autocmd({{"FocusLost", "BufLeave"}}, {{
+  buffer = 0,
+  callback = function()
+    timer:stop()
+    save_now()
+  end,
+}})
+vim.opt.autoread = true
+vim.api.nvim_create_autocmd({{"FocusGained", "BufEnter"}}, {{
+  buffer = 0,
+  callback = function()
+    -- Reloads from disk only if this buffer has no unsaved changes of its
+    -- own, so a draft in progress here is never silently discarded.
+    vim.cmd("silent! checktime")
+  end,
+}})
+""".strip()
+
+    if clear_key:
+        lua += f"""
+vim.keymap.set("n", "{clear_key}", function()
+  timer:stop()
+  -- Deliberately not `silent!`: if the write fails, let the error abort
+  -- here rather than silently archiving/truncating stale disk content.
+  vim.cmd("silent write")
+  vim.fn.system("map clear")
+  vim.cmd("edit!")
+end, {{ buffer = 0, desc = "multi-agent-prompt: archive and clear" }})
+""".rstrip()
+
+    if history_dir and history_key:
+        hdir = str(history_dir)
+        # A self-contained scratch-buffer listing, not `:vsplit <dir>` / netrw:
+        # netrw's directory browsing isn't available under -u NONE at all
+        # (confirmed directly — even `:Explore` is "not an editor command"
+        # there), and under a full config it may be intercepted by whatever
+        # directory-handling plugin (neo-tree, oil.nvim, ...) the user has —
+        # fine on its own, but inconsistent with --clean. This works
+        # identically either way.
+        lua += f"""
+vim.api.nvim_create_autocmd("BufReadPost", {{
+  pattern = "{hdir}/*",
+  callback = function()
+    vim.bo.readonly = true
+    vim.bo.modifiable = false
+  end,
+  desc = "multi-agent-prompt: archived drafts are read-only",
+}})
+vim.keymap.set("n", "{history_key}", function()
+  local dir = "{hdir}"
+  local ok, files = pcall(vim.fn.readdir, dir)
+  files = (ok and files) or {{}}
+  table.sort(files, function(a, b) return a > b end)  -- filenames sort newest-first
+  if #files == 0 then
+    vim.notify("multi-agent-prompt: no archived drafts yet", vim.log.levels.INFO)
+    return
+  end
+  vim.cmd("vsplit")
+  local buf = vim.api.nvim_create_buf(false, true)
+  vim.api.nvim_win_set_buf(0, buf)
+  vim.bo[buf].buftype = "nofile"
+  vim.bo[buf].bufhidden = "wipe"
+  vim.bo[buf].filetype = "map-history"
+  vim.api.nvim_buf_set_lines(buf, 0, -1, false, files)
+  vim.bo[buf].modifiable = false
+  vim.keymap.set("n", "<CR>", function()
+    local line = vim.api.nvim_get_current_line()
+    if line ~= "" then
+      vim.cmd("edit " .. vim.fn.fnameescape(dir .. "/" .. line))
+    end
+  end, {{ buffer = buf, desc = "multi-agent-prompt: open archived draft" }})
+end, {{ buffer = 0, desc = "multi-agent-prompt: browse archived prompts" }})
+""".rstrip()
+
+    if fold_threshold and fold_threshold > 0:
+        # vim.paste() is Neovim's single hook for every paste source
+        # (bracketed/terminal paste, "+p, "*p, ...), called with the
+        # complete line list for a small paste (phase -1) or streamed in
+        # chunks for a large one (phase 1/2/3). Track cursor position across
+        # the call rather than trust `#lines` alone, since a chunked paste's
+        # individual calls don't each carry the full line count.
+        lua += f"""
+local map_orig_paste = vim.paste
+local map_paste_start = nil
+vim.paste = function(lines, phase)
+  if phase == 1 or phase == -1 then
+    map_paste_start = vim.api.nvim_win_get_cursor(0)[1]
+  end
+  local ok = map_orig_paste(lines, phase)
+  if (phase == -1 or phase == 3) and map_paste_start then
+    local paste_end = vim.api.nvim_win_get_cursor(0)[1]
+    if paste_end - map_paste_start >= {fold_threshold} then
+      vim.cmd(string.format("%d,%dfold", map_paste_start, paste_end))
+    end
+    map_paste_start = nil
+  end
+  return ok
+end
+""".rstrip()
+
+    if help_key:
+        entries = []
+        if clear_key:
+            entries.append((clear_key, "archive current draft & clear"))
+        if history_dir and history_key:
+            entries.append((history_key, "browse archived drafts"))
+        if fold_threshold and fold_threshold > 0:
+            entries.append(("za/zo/zc", f"toggle fold ({fold_threshold}+ line pastes auto-fold)"))
+        entries.append((help_key, "show this help"))
+        width = max(len(k) for k, _ in entries)
+        help_lines = ", ".join(
+            f'"  {k.ljust(width)}  {desc}"' for k, desc in entries
+        )
+        lua += f"""
+vim.keymap.set("n", "{help_key}", function()
+  local lines = {{ " multi-agent-prompt ", "", {help_lines} }}
+  local width = 0
+  for _, l in ipairs(lines) do
+    width = math.max(width, vim.fn.strdisplaywidth(l))
+  end
+  local buf = vim.api.nvim_create_buf(false, true)
+  vim.api.nvim_buf_set_lines(buf, 0, -1, false, lines)
+  vim.bo[buf].modifiable = false
+  vim.bo[buf].bufhidden = "wipe"
+  local win = vim.api.nvim_open_win(buf, true, {{
+    relative = "cursor",
+    row = 1,
+    col = 0,
+    width = width + 2,
+    height = #lines,
+    style = "minimal",
+    border = "rounded",
+  }})
+  local close = function()
+    pcall(vim.api.nvim_win_close, win, true)
+  end
+  vim.keymap.set("n", "q", close, {{ buffer = buf, nowait = true }})
+  vim.keymap.set("n", "<Esc>", close, {{ buffer = buf, nowait = true }})
+end, {{ buffer = 0, desc = "multi-agent-prompt: show keymap help" }})
+""".rstrip()
+
+    return lua
+
+
+def build_nvim_command(
+    file: Path,
+    debounce_ms: int = DEFAULT_DEBOUNCE_MS,
+    nvim_bin: str = DEFAULT_NVIM_BIN,
+    clean: bool = False,
+    clear_key: str | None = DEFAULT_CLEAR_KEY,
+    history_key: str | None = DEFAULT_HISTORY_KEY,
+    help_key: str | None = DEFAULT_HELP_KEY,
+    fold_threshold: int | None = DEFAULT_FOLD_THRESHOLD,
+    insert: bool = True,
+) -> list[str]:
+    """The argv to launch nvim on ``file`` with autosave (and the clear/history/help/fold keymaps) enabled.
+
+    ``clean=True`` passes ``-u NONE``, skipping the user's init.lua (and every
+    plugin it loads) entirely — a fast, minimal mode for when startup latency
+    from a large distro (LSP servers, treesitter, etc.) matters more than
+    having every keymap and plugin available for a quick one-file edit.
+
+    ``insert=True`` (default) drops straight into append-mode insert at the
+    end of the buffer — a scratch prompt file is written far more than it's
+    navigated, so requiring an `i`/`a`/`o` before typing is pure friction.
+    """
+    history_dir = file.parent / ARCHIVE_DIRNAME
+    lua = build_autosave_lua(
+        debounce_ms,
+        clear_key=clear_key,
+        history_dir=history_dir,
+        history_key=history_key,
+        help_key=help_key,
+        fold_threshold=fold_threshold,
+    )
+    argv = [nvim_bin]
+    if clean:
+        argv.append("-u")
+        argv.append("NONE")
+    argv += ["-c", f"lua {lua}"]
+    if insert:
+        argv += ["-c", "normal! G", "-c", "startinsert!"]
+    argv += [str(file)]
+    return argv
+
+
+def nvim_available(nvim_bin: str = DEFAULT_NVIM_BIN) -> bool:
+    return shutil.which(nvim_bin) is not None
+
+
+def open_editor(
+    file: Path,
+    debounce_ms: int = DEFAULT_DEBOUNCE_MS,
+    nvim_bin: str = DEFAULT_NVIM_BIN,
+    clean: bool = False,
+    clear_key: str | None = DEFAULT_CLEAR_KEY,
+    history_key: str | None = DEFAULT_HISTORY_KEY,
+    help_key: str | None = DEFAULT_HELP_KEY,
+    fold_threshold: int | None = DEFAULT_FOLD_THRESHOLD,
+    insert: bool = True,
+) -> int:
+    """Open ``file`` in nvim (inheriting the terminal) with autosave. Returns nvim's exit code."""
+    file.parent.mkdir(parents=True, exist_ok=True)
+    if not file.exists():
+        file.touch()
+    argv = build_nvim_command(
+        file,
+        debounce_ms=debounce_ms,
+        nvim_bin=nvim_bin,
+        clean=clean,
+        clear_key=clear_key,
+        history_key=history_key,
+        help_key=help_key,
+        fold_threshold=fold_threshold,
+        insert=insert,
+    )
+    env = {**os.environ, "MAP_SESSION": "1"}
+    result = subprocess.run(argv, check=False, env=env)
+    return result.returncode

multi_agent_prompt/paths.py

@@ -0,0 +1,99 @@
+"""Resolve where a project's scratch prompt file (and its archive) live.
+
+State lives under ``.ma/prompt/`` — ``.ma`` is the shared root directory for
+the whole multi-agent-* product line (``map``'s CLI alias is itself the
+shared ``ma`` prefix of ``map``/``mar``/``maa``), with each product getting
+its own subdirectory so a project never accumulates a `.map/`, `.mar/`,
+`.maa/`... pile of top-level dotfolders. Only this tool's own subdirectory
+(``.ma/prompt/``) is touched here; task-agent's separate, already-shipped
+``.task-agent/`` convention is out of scope for this rename.
+
+Resolution walks up from the start directory to the nearest ``.git`` root
+(matching how most agent CLIs and task-agent itself scope their own config),
+falling back to the start directory itself when no repo is found.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+MA_DIRNAME = ".ma"
+PRODUCT_DIRNAME = "prompt"
+PROMPT_FILENAME = "current.md"
+ARCHIVE_DIRNAME = "archive"
+
+# Anything that already covers `.ma/prompt/` — including a broader existing
+# `.ma/` entry a future sibling product's setup might have added — counts as
+# "already ignored".
+_COVERING_GITIGNORE_LINES = frozenset(
+    {
+        f"{MA_DIRNAME}/{PRODUCT_DIRNAME}/",
+        f"{MA_DIRNAME}/{PRODUCT_DIRNAME}",
+        f"/{MA_DIRNAME}/{PRODUCT_DIRNAME}/",
+        f"/{MA_DIRNAME}/{PRODUCT_DIRNAME}",
+        f"{MA_DIRNAME}/",
+        MA_DIRNAME,
+        f"/{MA_DIRNAME}/",
+        f"/{MA_DIRNAME}",
+    }
+)
+GITIGNORE_PATTERN = f"{MA_DIRNAME}/{PRODUCT_DIRNAME}/"
+
+
+def find_repo_root(start: Path) -> Path:
+    """Walk up from ``start`` to the nearest directory containing ``.git``.
+
+    Returns ``start`` (resolved) if no ``.git`` is found before the
+    filesystem root.
+    """
+    current = start.resolve()
+    while True:
+        if (current / ".git").exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            return start.resolve()
+        current = parent
+
+
+def prompt_dir(start: Path | None = None) -> Path:
+    """The ``.ma/prompt`` directory for the project containing ``start`` (default cwd)."""
+    root = find_repo_root(start or Path.cwd())
+    return root / MA_DIRNAME / PRODUCT_DIRNAME
+
+
+def prompt_file(start: Path | None = None) -> Path:
+    """The scratch prompt file path for the project containing ``start``."""
+    return prompt_dir(start) / PROMPT_FILENAME
+
+
+def archive_dir(start: Path | None = None) -> Path:
+    """Where previously-cleared drafts for this project are kept."""
+    return prompt_dir(start) / ARCHIVE_DIRNAME
+
+
+def ensure_gitignored(start: Path | None = None) -> bool:
+    """Append ``.ma/prompt/`` to the project's ``.gitignore`` if not already covered.
+
+    No-ops (returns False) when the project has no ``.git`` directory at all
+    (nothing to ignore against), or an existing line already covers it —
+    either the exact pattern or a broader ``.ma/`` entry. Returns True when
+    it actually modified (or created) ``.gitignore``.
+    """
+    root = find_repo_root(start or Path.cwd())
+    if not (root / ".git").exists():
+        return False
+
+    gitignore = root / ".gitignore"
+    existing = gitignore.read_text(encoding="utf-8") if gitignore.exists() else ""
+    lines = existing.splitlines()
+
+    for line in lines:
+        if line.strip() in _COVERING_GITIGNORE_LINES:
+            return False
+
+    with gitignore.open("a", encoding="utf-8") as f:
+        if existing and not existing.endswith("\n"):
+            f.write("\n")
+        f.write(f"{GITIGNORE_PATTERN}\n")
+    return True

multi_agent_prompt-0.1.0.dist-info/METADATA

@@ -0,0 +1,231 @@
+Metadata-Version: 2.5
+Name: multi-agent-prompt
+Version: 0.1.0
+Summary: A crash-proof, autosaving prompt editor for AI coding agent CLIs — compose in your real editor, hand off with a slash command
+Author-email: Mark Stouffer <1802850+InTEGr8or@users.noreply.github.com>
+License: MIT
+Requires-Python: >=3.12
+Requires-Dist: rich>=13.9.4
+Requires-Dist: verkit>=0.1.4
+Description-Content-Type: text/markdown
+
+# Multi-Agent Prompt ✍️
+
+A crash-proof, autosaving prompt editor for AI coding agent CLIs.
+
+Chat text boxes lose long, carefully-composed prompts to a single wrong
+keystroke, and give you almost no editing power while you write. `multi-agent-prompt`
+moves composition out of the chat box entirely: write in a real Neovim, in a
+split pane next to your agent session, autosaved to disk every couple of
+seconds so a crash or a fat-fingered shortcut can never cost you more than a
+moment of typing. When you're ready, hand it to the agent with `/prompt` —
+which reads it, archives it, and clears the file in one step, so there's no
+separate "now go clear it" to remember.
+
+---
+
+## Install
+
+```bash
+pip install multi-agent-prompt
+# or
+uv tool install multi-agent-prompt
+```
+
+Requires [Neovim](https://neovim.io/) — the autosave hook is Lua, so plain
+Vim isn't supported.
+
+## Usage
+
+Open a split pane next to your agent CLI (Windows Terminal: `Alt+Shift+-`;
+tmux: `<prefix> "`) in the **same working directory**, then run:
+
+```bash
+map
+```
+
+This opens `.ma/prompt/current.md` — resolved to the current project's git
+root, so every pane in the same repo shares one scratch file — in your actual
+`nvim`, your actual `init.lua`, your actual keymaps and plugins. No config
+import step, no reimplemented Vim subset: it's just Neovim. You land in
+**insert mode already**, cursor at the end of the buffer, so there's no `i`
+to press before you start typing (`--no-insert` if you'd rather open in
+normal mode). A buffer-local autocmd (scoped only to this one buffer — it
+never touches how you edit anything else) autosaves ~2 seconds after you stop
+typing, and immediately when you switch away from the pane
+(`FocusLost`/`BufLeave`), so the save always beats you to the chat window.
+
+When you're done, switch back to the agent pane and either:
+
+- Type `/prompt` (if the agent's install includes the skill — see below) —
+  reads the draft, archives it, and clears the file, all in one step, or
+- Reference `@prompt.md` / `@.ma/prompt/current.md` directly, if your agent
+  supports file mentions and can see gitignored files — this is a plain
+  read, so unlike `/prompt` it doesn't archive or clear anything.
+
+Pasting a long CLI transcript or diff in? Anything **6 lines or more**
+(bracketed paste, `"+p`, `"*p` — any paste source) auto-folds, closed, so it
+doesn't bury the rest of what you're writing — `za`/`zo`/`zc` (standard Vim)
+toggle it open.
+
+Also want to browse past drafts without leaving the editor? A buffer-local
+keymap — `<leader>ph` by default — lists archived drafts (newest first) in a
+split; `<CR>` opens one, read-only. Forgot what any of this is bound to?
+Press `g?` — it shows exactly the keymaps active for *this* session
+(respecting any `--clear-key`/`--history-key` overrides, and omitting
+whichever ones you disabled):
+
+```
+map            # open the scratch file (same as `map edit`)
+map where      # print the resolved file path
+map show       # print its current content to stdout (does not clear it)
+map pop        # print it, archive it, and clear it — what /prompt uses
+map clear      # archive the current draft, then empty it, without printing it
+map --clean    # skip your init.lua entirely (-u NONE) for faster startup
+```
+
+```
+map edit --clear-key '<F5>'      # rebind the in-editor clear keymap
+map edit --no-clear-key          # don't register it at all
+map edit --history-key '<F6>'    # rebind the in-editor history-browse keymap
+map edit --no-history-key        # don't register it at all
+map edit --help-key '<F1>'       # rebind the in-editor g? cheatsheet keymap
+map edit --no-help-key           # don't register it at all
+map edit --fold-threshold 3      # auto-fold pastes of 3+ lines instead of 6
+map edit --no-fold-paste         # don't auto-fold pastes at all
+map edit --no-insert             # open in normal mode instead of insert mode
+map clear --keep 20              # override how many archived drafts to retain
+map clear --no-archive           # discard instead of archiving (e.g. it had a secret in it)
+```
+
+`map pop` accepts the same `--keep`/`--no-archive` as `map clear`.
+
+### The archive
+
+`map pop`/`map clear` — from the CLI or the in-editor keymap, which shells
+out to `map clear` — never actually discard a non-empty draft; they move it
+to `.ma/prompt/archive/<timestamp>-<seq>.md` first, then prune that archive
+down to the most recent entries. Pruning is by **count**, not age (`--keep` /
+`MAP_ARCHIVE_KEEP` env var, default **10**) — simpler to reason about than a
+retention window, and it doesn't depend on the clock. Use `--no-archive` for
+the one case that shouldn't be kept anywhere: you pasted a secret and want it
+actually gone.
+
+## Performance
+
+A `map` session opens your *entire* Neovim config, which is exactly the
+point — but if that config is large, startup isn't free. Two things worth
+knowing, from actually measuring it (not guessing):
+
+- **It's not a one-time thing.** Whatever makes your first `map` slow will
+  make every subsequent one about equally slow, unless something changes
+  (lazy.nvim itself finishes installing/compiling once; LSP servers and
+  large plugin trees generally don't get meaningfully faster after that).
+- **On WSL specifically, check for `vim.opt.clipboard = 'unnamedplus'` (or
+  similar) in your own init.lua.** Setting that option makes Neovim probe for
+  a clipboard provider immediately, and on WSL that probe walks every `PATH`
+  entry checking `executable()` — including everything under `/mnt/c/...`,
+  which is slow cross-filesystem interop. Measured on this project's own dev
+  machine: ~900ms startup with that line in play, ~160ms with the Windows
+  `PATH` entries stripped, ~4ms with `-u NONE`. That's not multi-agent-prompt
+  overhead; it's one line in a personal init.lua interacting badly with WSL,
+  and fixing it (or guarding it — see `MAP_SESSION` below) speeds up *every*
+  Neovim session, not just `map`.
+- **`map --clean` (`-u NONE`)** sidesteps all of it by skipping your config
+  entirely — the built-in fast path when you don't need your plugins for a
+  quick edit.
+- **`MAP_SESSION=1`** is set in the environment of every nvim `map` launches.
+  Nothing in this package reads it — it's there so you can guard an
+  expensive line in your *own* init.lua behind
+  `if not vim.env.MAP_SESSION then ... end`, if you want full-config speed
+  back without giving up faster `map` startup. That's your config to edit,
+  not something this tool does for you. This isn't just for the clipboard
+  line above — a scratch prompt buffer has no use for a file-tree sidebar or
+  git tooling either, and with [lazy.nvim](https://github.com/folke/lazy.nvim)
+  you can skip those specific plugins the same way, with `cond` on the spec:
+
+  ```lua
+  return {
+    'nvim-neo-tree/neo-tree.nvim',
+    cond = not vim.env.MAP_SESSION,
+    -- ...
+  }
+  ```
+
+  Confirmed on this project's own dev config: with `neo-tree.nvim` and
+  `gitsigns.nvim` guarded this way, `<leader>e` (NeoTree's toggle) becomes a
+  no-op in a `map` session, and their entire module trees (dozens of
+  individual `require()` calls each) simply don't load — real startup
+  savings, not just fewer keymaps to trip over. `cond` is evaluated on every
+  start, so this takes effect immediately; no `:Lazy sync`/restart needed.
+- **It's specifically a startup cost, not a per-save one.** The clipboard
+  probe runs once, while your init.lua is sourced, not again on autosave, on
+  `FocusLost`, or when you switch panes and type `/prompt` — that last step
+  never touches nvim at all (`map pop`/reading the file is a separate,
+  plain filesystem read and write). If a session still feels slow at the
+  hand-off moment specifically, that's terminal pane-switching or the
+  agent's own slash-command overhead, not this tool or Neovim.
+- **`/prompt`'s own overhead is small, and it isn't Neovim's.** Measured on
+  this project's own dev machine: `map pop` runs in ~60-85ms end to end —
+  bare `python3 -c pass` alone is ~30ms of that, this package's own imports
+  add maybe another ~20ms, and the rest is the file read/archive/write. If
+  `/prompt` still feels slow, that latency lives in the *agent host's* own
+  tool-call round trip (spawning/sandboxing the shell command), not in
+  anything this package does — there's no nvim process in this path at all.
+  The one thing the `prompt` skill itself controls: it runs `map pop`
+  directly rather than checking `which map` first, since that check is a
+  second subprocess spawn that's a wasted round trip almost every time.
+
+## Agent integration
+
+`skills/prompt/` is a portable [Agent Skill](https://code.claude.com/docs/en/skills)
+that teaches a host to read `.ma/prompt/current.md` and treat its content as
+the user's message when they type `/prompt`. See
+[`skills/README.md`](./skills/README.md) for install paths.
+
+## Why not tmux `send-keys` / auto-injection?
+
+That's the obvious next step — save, close the pane, and have the tool type
+`/prompt` into the neighboring agent pane for you — but it needs a reliable
+way to identify *which* pane is running the agent, which varies by terminal
+(tmux panes, Windows Terminal panes, and OS-level input injection like
+`xdotool`/`wtype` all solve a different half of that problem). The manual
+handoff above works everywhere today; auto-injection is being explored as a
+follow-up, potentially building on [`multi-agent-registry`](https://github.com/InTEGr8or/multi-agent-registry)'s
+chat discovery to identify a live agent session (not just a recent one) in
+the same directory.
+
+If/when that lands: prefer sending a widely-supported "submit" keystroke —
+`Ctrl+Enter` is the closest thing to a universal convention across chat
+input boxes — into the target pane after typing `/prompt`, over anything
+input-method-specific, so the same injection code has a chance of working
+across agents rather than being re-tuned per host.
+
+## Design notes
+
+- **The prompt file is per-project, not global.** `.ma/prompt/current.md`
+  resolves against the nearest `.git` root, so working on two projects in two
+  terminal tabs never mixes up their scratch files.
+- **`.ma/` is a shared root, not this tool's alone.** It's the umbrella
+  directory for the whole multi-agent-* line (`map`'s CLI alias is the shared
+  `ma` prefix of `map`/`mar`/`maa`) — one dotfolder instead of one per
+  product. Only `.ma/prompt/` is this tool's; a sibling product could use
+  `.ma/registry/`, etc., without colliding. Note that `task-agent`'s existing
+  `.task-agent/` convention predates this and stays as-is — migrating an
+  already-shipped tool's config layout is a separate, larger decision.
+- **`.gitignore` is managed for you.** The first time `map edit` runs in a
+  git repo, it appends `.ma/prompt/` to `.gitignore` if it isn't already
+  covered — including by a broader pre-existing `.ma/` entry.
+- **Reading is non-destructive; handing off isn't, but it never discards
+  either.** `map show` and `@prompt.md` (file mention) just print/read — the
+  file is untouched either way. `/prompt` (`map pop`) clears it, because the
+  whole point is not needing a separate "now go clear it" step — but it
+  archives first, so "cleared" never means "gone". `--no-archive` is the
+  explicit opt-out for content that shouldn't be kept anywhere at all.
+- **The editor notices when the file changes out from under it.** `/prompt`
+  runs `map pop` from the *agent's* process, not from inside the running
+  nvim session — so if you're still looking at that buffer when you hand a
+  draft off, it auto-reloads (`autoread` + `checktime` on
+  `FocusGained`/`BufEnter`) the next time you focus it, rather than keep
+  showing the text you already submitted. It won't discard anything you've
+  since typed there unsaved.

multi_agent_prompt-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+multi_agent_prompt/__init__.py,sha256=o0H7CBkPPY2AYgAK5VUYlDy7eFXaghzFSJrSikN93hk,115
+multi_agent_prompt/archive.py,sha256=jmuYRKoJPTj6fn-V81oT5x6CLkyCkXqQFJMQM0isMJ4,3284
+multi_agent_prompt/cli.py,sha256=4HYgnygXM9czpIeJ5xLOYfeAddV9NMBdajXkm_Wk7oM,11397
+multi_agent_prompt/editor.py,sha256=bIVxqnph7qo3sXS-ceUBUbH_XmGDs2uxe5t6VjTFOS8,12349
+multi_agent_prompt/paths.py,sha256=dsQ1p5FEVOvNEq9XOGF2yarGCM2fYYlzzj5FrC1W7Tg,3563
+multi_agent_prompt-0.1.0.dist-info/METADATA,sha256=C1sqT-hdf1OURq2cPlVcJL-A8_6lGoy3jRfjrrp1Ytc,12208
+multi_agent_prompt-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+multi_agent_prompt-0.1.0.dist-info/entry_points.txt,sha256=0GLTX8zgbyWGj0twq7A3vfBBe8wYIB9C8vV4ppKfiB0,101
+multi_agent_prompt-0.1.0.dist-info/RECORD,,

multi_agent_prompt-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

multi_agent_prompt-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+map = multi_agent_prompt.cli:main
+multi-agent-prompt = multi_agent_prompt.cli:main