code-puppy-core-plugins 0.0.77__tar.gz → 0.0.79__tar.gz

{code_puppy_core_plugins-0.0.77 → code_puppy_core_plugins-0.0.79}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code-puppy-core-plugins
-Version: 0.0.77
+Version: 0.0.79
 Summary: Official plugin bundle for Code Puppy
 Project-URL: Repository, https://github.com/mpfaffenberger/code_puppy_core_plugins
 Project-URL: Homepage, https://github.com/mpfaffenberger/code_puppy_core_plugins

{code_puppy_core_plugins-0.0.77 → code_puppy_core_plugins-0.0.79}/code_puppy_core_plugins/code_puppy_agent/AGENTS_AND_TOOLS.md

@@ -134,7 +134,7 @@ register_callback("register_agent_tools", _advertise)
 ```
 
 Step 1 makes the tool *exist*; step 2 makes agents *see* it. Both are
-needed. `namespace_skill_search` (`code_puppy/plugins/namespace_skill_search/`)
+needed. `namespace_skill_search` (`code_puppy_core_plugins/namespace_skill_search/`)
 is a small, complete example of this pattern for a single tool
 (`browse_skill_namespace`) — see `SKILLS_SYSTEM.md` for what it does and
 `PLUGINS_AND_CALLBACKS.md` for the callback-safety reasoning behind how

{code_puppy_core_plugins-0.0.77 → code_puppy_core_plugins-0.0.79}/code_puppy_core_plugins/code_puppy_agent/PLUGINS_AND_CALLBACKS.md

@@ -10,12 +10,26 @@
 
 | Tier | Location | Load order |
 |------|----------|------------|
-| **Builtin** | `code_puppy/plugins/<name>/register_callbacks.py` | 1st |
+| **Builtin** | `code_puppy.plugins` entry points, shipped by the separate `code-puppy-core-plugins` distribution | 1st |
 | **User** | `~/.code_puppy/plugins/<name>/register_callbacks.py` | 2nd |
 | **Project** | `<CWD>/.code_puppy/plugins/<name>/register_callbacks.py` | 3rd (highest precedence) |
 
-Each plugin is a directory containing `register_callbacks.py`. The loader
-auto-discovers it. Project plugins shadow user plugins on name collision.
+The builtin tier is **not** a directory scan of the core package. Plugins live
+in their own repo (`code_puppy_core_plugins/<name>/register_callbacks.py`) and
+are advertised through the `code_puppy.plugins` entry-point group in that
+package's `pyproject.toml`; `_load_installed_plugins()` loads them sorted by
+name for deterministic startup. Adding a plugin there means adding an entry
+point, not just a directory.
+
+Inside core, `code_puppy/plugins/` is now only the **loader and trust
+machinery** (`__init__.py`, `trust.py`, `trust_notice.py`, `config.py`, plus the
+OAuth pasteback helpers) — not a plugin collection. A legacy directory scan of
+it still runs via `_load_builtin_plugins()` for migration, skipping any name
+already loaded from an entry point, so `builtin = installed + legacy`.
+
+User and project tiers *are* plain directory scans: each plugin is a directory
+containing `register_callbacks.py`, auto-discovered by the loader. Project
+plugins shadow user plugins on name collision.
 
 ## The callback hook system
 
@@ -82,7 +96,7 @@ That's it. The loader handles discovery, import, and registration.
 
 ## Two gotchas that will bite you, both discovered building `namespace_skill_search`
 
-`namespace_skill_search` (`code_puppy/plugins/namespace_skill_search/`)
+`namespace_skill_search` (`code_puppy_core_plugins/namespace_skill_search/`)
 groups skills into namespaces and replaces the flat per-skill list in the
 system prompt with a compact directory + a `browse_skill_namespace` tool
 (see `SKILLS_SYSTEM.md` for what it does from a user's perspective). It's
@@ -123,7 +137,7 @@ is:
   happens to get imported, with no log line tied to a specific lifecycle
   event.
 - **A pattern already solved by the `startup` callback.** See
-  `code_puppy/plugins/theme/register_callbacks.py`'s
+  `code_puppy_core_plugins/theme/register_callbacks.py`'s
   `_apply_default_theme_on_first_run`, registered via
   `register_callback("startup", _apply_default_theme_on_first_run)`.
 
@@ -157,7 +171,7 @@ my_plugin/
 
 For a plugin that also ships a builtin skill via `register_skills`
 (rather than, or in addition to, tools/prompt fragments), see
-`code_puppy/plugins/code_puppy_agent/` (this skill's own plugin) or
+`code_puppy_core_plugins/code_puppy_agent/` (this skill's own plugin) or
 `namespace_skill_search`'s README for a fuller worked example of
 justifying design decisions in-repo rather than only in a PR
 description.

{code_puppy_core_plugins-0.0.77 → code_puppy_core_plugins-0.0.79}/code_puppy_core_plugins/code_puppy_agent/SKILL.md

@@ -39,16 +39,23 @@ LLM how Code Puppy is structured under the hood so it can navigate the
 codebase, debug issues, and extend the product without guessing.
 
 > **Philosophy:** Code Puppy is plugin-first. Nearly all new functionality
-> should be a plugin under `code_puppy/plugins/` that hooks into core via
-> `code_puppy/callbacks.py`. Don't edit `code_puppy/command_line/` or core
-> agent files unless a hook genuinely doesn't exist.
+> should be a plugin in the separate `code-puppy-core-plugins` repo that hooks
+> into core via `code_puppy/callbacks.py`. Don't edit
+> `code_puppy/command_line/` or core agent files unless a hook genuinely
+> doesn't exist.
+
+> **Two repos.** Core (the `code-puppy` package) holds the runtime, agents,
+> tools, and the callback engine. Plugins (the `code-puppy-core-plugins`
+> package, this skill included) ship separately and are discovered through
+> `code_puppy.plugins` entry points. Paths below starting `code_puppy/` are in
+> core; paths starting `code_puppy_core_plugins/` are in the plugins repo.
 
 This skill is split across multiple files so activating it doesn't force
 the full ~30KB of internals into context on every use — this SKILL.md is
 the index. **Read the reference file for the topic you actually need**;
 each one is self-contained and cites real file paths so you can jump
 straight to source. All reference files are plain repo paths under
-`code_puppy/plugins/code_puppy_agent/` — read them with `read_file`.
+`code_puppy_core_plugins/code_puppy_agent/` — read them with `read_file`.
 
 ---
 
@@ -56,7 +63,7 @@ straight to source. All reference files are plain repo paths under
 
 ```
 ┌──────────────────────────────────────────────────┐
-│  TUI / CLI  (command_line/, tui/)                 │
+│  TUI / CLI  (command_line/, messaging/)           │
 │    user input → slash commands → agent dispatch   │
 ├──────────────────────────────────────────────────┤
 │  Agent Layer  (agents/)                           │
@@ -66,7 +73,7 @@ straight to source. All reference files are plain repo paths under
 │  Tool Layer  (tools/)                             │
 │    TOOL_REGISTRY → register_tools_for_agent()     │
 ├──────────────────────────────────────────────────┤
-│  Plugin Layer  (plugins/, callbacks.py)           │
+│  Plugin Layer  (callbacks.py + plugins/ loader)   │
 │    register_callback("hook", fn) at import time   │
 ├──────────────────────────────────────────────────┤
 │  Model Layer  (model_factory.py, config.py)       │

{code_puppy_core_plugins-0.0.77 → code_puppy_core_plugins-0.0.79}/code_puppy_core_plugins/code_puppy_agent/SKILLS_SYSTEM.md

@@ -72,7 +72,7 @@ real path in the repo rather than expecting it to appear as a
 ## Skill namespaces (large catalogs)
 
 The **`namespace_skill_search`** builtin plugin
-(`code_puppy/plugins/namespace_skill_search/`) addresses the
+(`code_puppy_core_plugins/namespace_skill_search/`) addresses the
 flat-list-doesn't-scale problem above. It's the reference
 implementation to look at if you're extending how skills are surfaced
 to the model, or building something in the same spirit for another
@@ -95,7 +95,7 @@ modes with examples, and how to opt back out
 (`/plugins disable namespace_skill_search` + `/skills frontmatter on`).
 
 **Design rationale + what was deliberately not built:**
-`code_puppy/plugins/namespace_skill_search/README.md` — full writeup of
+`code_puppy_core_plugins/namespace_skill_search/README.md` — full writeup of
 what was copied from OpenAI/Anthropic, why namespace-per-first-tag was
 chosen over a vector DB or a deep multi-level tree, and the two hook-
 system gotchas it was built to avoid (see `PLUGINS_AND_CALLBACKS.md` in

{code_puppy_core_plugins-0.0.77 → code_puppy_core_plugins-0.0.79}/code_puppy_core_plugins/herdr/README.md

@@ -26,6 +26,162 @@ no worker thread. If they're present it opens a background reporter that
 reports code-puppy's state **authoritatively**: herdr never has to infer
 it from the screen.
 
+## Launch and prompt another puppy
+
+From a Code Puppy running inside herdr:
+
+```text
+/herdr spawn fixer --prompt-file brief.md
+/herdr spawn reviewer --direction down --cwd ./project --prompt-file review.md -- --model MODEL
+/herdr send fixer Don't forget the tests
+/herdr send fixer --file follow-up.txt
+/herdr commands
+/herdr command fixer /model gpt-5
+```
+
+`spawn` creates a sibling split in the caller's tab, preserves the caller's
+working directory unless `--cwd` is given, and does not change focus. Wide
+panes split right; tall or approximately square panes split down (cell width
+must exceed twice the cell height to count as wide). `--direction` overrides
+that choice. Names must match `[a-z][a-z0-9_-]{0,31}` and be unique among
+live agents. Invalid names, duplicate names, unreadable prompt files, and
+invalid options are rejected before splitting.
+
+The child uses the current Python interpreter with safe-path `-P` and the
+installed `code_puppy` module,
+not a shell alias, cwd-relative console wrapper, or executable from `PATH`.
+`-P` excludes the child's cwd from Python's module search path. Caller
+interpreter flags are deliberately not inherited; only child arguments
+explicitly supplied after `--` are forwarded. Without a prompt the launcher
+waits for reported idle. With a prompt it accepts the first Code Puppy report
+in any state, names the child and returns without waiting for task completion.
+Startup timeout is 30 seconds by default (`--timeout SECONDS`, up to 300).
+A failed launch or readiness timeout reports the created pane for inspection;
+it deliberately does not close it or retry a possibly delivered prompt.
+If a split request itself times out, inspect `herdr pane list` before retrying:
+the server may have created the pane without returning its ID.
+
+`--prompt` and `--prompt-file` are mutually exclusive. Files are UTF-8.
+Spawn writes the prompt to an exclusive private temporary file (mode 0600
+on POSIX). A short, single-line Python bootstrap reads and deletes that file
+before passing the complete text as **one initial-command argument** to the
+installed module. This avoids shell canonical line-buffer limits and editor
+readiness races. Startup failure cleans up the file; a timeout can delete it
+before a slow child reads it, causing that child to fail without its prompt.
+Inspect the reported pane rather than retrying blindly. A hard caller crash
+before the child reads it can leave a private temporary file. The launcher
+never retries a possibly delivered initial command. A working child is named
+promptly; a short task may already have completed when spawn returns.
+
+**Core preprocessing limitation:** the interactive core parses attachments
+before dispatching `/herdr`, removing quotes and normalizing whitespace.
+Inline multiword `--prompt` values, quoted paths containing spaces, and quoted
+multiword child arguments therefore are not supported through this boundary.
+Use whitespace-free paths and `--prompt-file` for briefs. Inline send text
+arrives already normalized; it is not byte-preserving, and attachment-like
+paths/URLs may be consumed by the core before dispatch. This plugin cannot
+recover raw input; a raw-command dispatch seam requires an upstream change.
+
+`/herdr send` remains a **prompt-only helper**, not a way to run Code Puppy
+commands such as `/model gpt-5` or `/new`. Use the separate explicit intent
+`/herdr command fixer /model gpt-5` when intentionally requesting a command.
+Commands may mutate state or open interactive menus: recognition is not a
+safety guarantee. `/herdr commands` dynamically lists **sender candidates**
+from the existing core registry (including aliases) and `custom_command_help`
+plugin discovery, including advertised namespaced commands. Enumeration runs
+plugin help callbacks; those callbacks are not guaranteed side-effect-free.
+No handlers or `custom_command` callbacks are executed as validation probes.
+Unknown or unadvertised commands fail closed. The target may run a different
+version, configuration, or plugin set: this is not target validation.
+
+The command payload must have an exact leading `/command` token, be one line
+under 1,000 UTF-8 bytes, and contain no terminal controls. Shell `!` and bare
+exit/quit/clear passthrough are not supported. Arguments can contain slash
+paths; they are not blanket-rejected. The payload received by the launcher
+is forwarded without rewriting, but both caller and child core preprocessing
+may remove quotes, normalize spaces, or consume attachments. Inline quoted
+or escaped leading commands may already be normalized before this plugin
+sees them; do not rely on byte-preserved arguments through this boundary.
+There is no command-file mode or automatic retry.
+
+Command uses the same unique idle/terminal identity checks and `pane run`
+terminal typing as send, not a structured child command route. Verify actual
+foreground Code Puppy editor readiness before using it. A write acknowledgement
+is **not confirmed execution**, child receipt, or completion. The occupant
+check and write are not atomic; reported idle alone is not editor readiness.
+
+The `load_prompt` hook exposes these choices and `/herdr commands` discovery
+to agents inside herdr; `/herdr help` and the command menu expose them to users.
+Agents with shell tools can call the installed plugin's `launcher.execute`
+API and print the result, using the same guards rather than raw input.
+Its guards do **not** change Herdr's generic CLI transport. The existing
+`herdr pane send-text <pane-id> ...` followed by
+`herdr pane send-keys <pane-id> Enter` remains available. Verify the intended
+pane and that its Code Puppy input editor is actually ready first: a named
+agent's idle report alone does not establish editor readiness. Raw terminal
+input can execute commands in whatever process owns the foreground; it is
+not a safe arbitrary-text alternative to this helper.
+
+The launcher forwards the send tail it receives without further shell parsing.
+`--file PATH` is the explicit file form; it bypasses the caller's inline-text
+normalization, but the child still applies its usual prompt preprocessing.
+File sends remove one conventional trailing newline; other newlines are
+rejected.
+Send accepts **single-line** prompts only: multiline paste is unsafe in the
+classic editor or before bracketed paste is enabled.
+Use `spawn --prompt-file` for multiline work. Send rechecks a unique idle Code
+Puppy's terminal identity and refuses working/blocked agents. It uses herdr's
+atomic `pane.send_input` text+Enter through `pane run`. Empty prompts and
+terminal controls are rejected. Send rejects bare `exit`, `quit`, and `clear`
+(case-insensitive), and tokens beginning with `/` or `!` even inside quotes.
+This conservative token guard also rejects prose containing absolute paths;
+use prompted spawn for such briefs. It avoids reading attachments merely to
+predict whether the child would expose a command. Spawn accepts leading `/`
+as literal initial prompt text (so an initial `/model` or `/new` prompt does
+not execute that editor command), but rejects leading `!` because the core
+initial-command path supports shell passthrough. Success confirms submission,
+not completion or byte-identical model/history text.
+
+**Startup caveat:** a prompt sent immediately after a no-prompt spawn may be
+dropped. The startup idle report precedes input-editor readiness; the editor
+can flush queued terminal input when it starts. Neither `send` nor `command`
+can distinguish this gap from an input-ready idle pane. For the child's first
+task, prefer `spawn --prompt` or `spawn --prompt-file`, whose private-file
+handoff does not depend on editor readiness. A successful send acknowledges
+the pane write, not child receipt.
+
+Spawn prompts are capped at 24,000 UTF-8 bytes. Single-line sends must stay
+under 1,000 UTF-8 bytes because the classic editor's canonical line buffer can
+otherwise discard input or Enter even after startup. Use `spawn --prompt-file`
+for larger briefs. The actual typed launch command (bootstrap, path and quoted
+child arguments) must remain under 1,000 UTF-8 bytes and contain no newline;
+otherwise it fails before any split. This conservative cap avoids even an
+unready macOS shell's line buffer.
+The command blocks the caller while waiting, prints the new pane and timeout
+as progress, and may not be interruptible under the core's Ctrl+C guard.
+Use a short `--timeout` when appropriate. Only one pane-specific `agent get`
+is polled per tick. A reported child that disappears fails promptly; a child
+that exits before ever reporting still requires the bounded timeout.
+
+The preflight uniqueness check cannot reserve a name: herdr only permits
+renaming a running agent. Concurrent same-name spawns can both create panes;
+the server rejects the losing rename, and the launcher reports that pane.
+Use `herdr agent get/read/wait` to observe work.
+
+Outside herdr, `/herdr` explains that it requires `HERDR_ENV=1` and performs
+no file reads, socket requests, or subprocess launches. The CLI binary comes
+from `HERDR_BIN_PATH` when available, otherwise `herdr` in `PATH`. On Windows,
+launch commands assume herdr's default PowerShell shell.
+
+### Why not native `herdr agent prompt`?
+
+In herdr 0.9.1, custom lifecycle reports can display `codepuppy idle`, but
+native prompting requires a hard-coded known agent kind. Reporting session
+identity does not remove that gate. `agent start --kind` and `integration
+install` likewise have fixed supported-kind lists. An upstream Code Puppy
+kind/integration is a follow-up; no agent impersonation or parallel reporter
+is needed here. An agent-callable launcher tool is also deferred.
+
 ## State is authoritative
 
 State is a pure function of two facts the plugin observes directly:

code_puppy_core_plugins-0.0.79/code_puppy_core_plugins/herdr/command_intent.py

@@ -0,0 +1,109 @@
+"""Sender-side command candidates, never handler execution or target probing."""
+
+import os
+import re
+import shlex
+
+# Restrict the leading token, not arguments (which may contain slash paths).
+_TOKEN = re.compile(r"/[A-Za-z0-9_-]+(?:/[A-Za-z0-9_-]+)*")
+
+
+def command_candidates():
+    """Reuse dispatcher metadata, including aliases and custom plugin help.
+
+    Enumeration runs help callbacks, not handlers or custom_command callbacks;
+    help callbacks are not guaranteed side-effect-free. Unadvertised custom
+    commands fail closed; this is not a target manifest.
+    """
+    from code_puppy import callbacks
+
+    # Importing dispatcher registers core categories, just as actual dispatch.
+    from code_puppy.command_line import command_handler  # noqa: F401
+    from code_puppy.command_line import command_registry
+
+    registry = command_registry.get_all_commands()
+    names = {"/" + name for name in registry if _TOKEN.fullmatch("/" + name)}
+    custom = set()
+    for result in callbacks.on_custom_command_help():
+        if isinstance(result, tuple) and len(result) == 2:
+            entries = [result]
+        elif isinstance(result, list) and result and isinstance(result[0], tuple):
+            entries = result
+        elif (
+            isinstance(result, list)
+            and result
+            and isinstance(result[0], str)
+            and result[0].startswith("/")
+            and " - " in result[0]
+        ):
+            entries = [(result[0].split(" - ", 1)[0].lstrip("/").strip(), "")]
+        else:
+            continue
+        for entry in entries:
+            if (
+                isinstance(entry, tuple)
+                and len(entry) == 2
+                and isinstance(entry[0], str)
+            ):
+                token = "/" + entry[0].lstrip("/")
+                if _TOKEN.fullmatch(token):
+                    custom.add(token)
+    # The dispatcher routes multi-slash tokens through custom hooks ONLY.
+    names = {token for token in names if token.count("/") == 1}
+    return names, custom
+
+
+def validate_command(text):
+    """Validate a single exact leading token; return payload without rewriting."""
+    if not text:
+        raise ValueError("Command payload is missing.")
+    if any(
+        ord(char) < 32 or 127 <= ord(char) <= 159 or (char.isspace() and char != " ")
+        for char in text
+    ):
+        raise ValueError("Command must be one line without terminal controls.")
+    if len(text.encode("utf-8")) >= 1000:
+        raise ValueError("Command requires under 1,000 UTF-8 bytes.")
+    token = text.split(" ", 1)[0]
+    if not _TOKEN.fullmatch(token):
+        raise ValueError("Command requires an exact leading /command token.")
+    try:
+        shlex.split(text, posix=os.name != "nt")
+    except ValueError as exc:
+        raise ValueError("Command has malformed quoting.") from exc
+    builtin, custom = command_candidates()
+    recognized = token in custom or any(
+        token.lower() == name.lower() for name in builtin
+    )
+    if not recognized:
+        raise ValueError(
+            "Unknown sender command candidate. Use /herdr commands; nothing sent."
+        )
+    return text
+
+
+def candidate_help():
+    builtin, custom = command_candidates()
+    return (
+        "Sender command candidates (aliases included; target may differ).\n"
+        "Not a safety or execution guarantee; unadvertised plugins fail closed.\n"
+        + " ".join(sorted(builtin | custom))
+    )
+
+
+GUIDANCE = """## Herdr sibling input (inside herdr only)
+Use /herdr spawn NAME --prompt-file PATH for first tasks, multiline or larger briefs.
+Use /herdr send NAME ordinary prompt for prompt-only follow-up (one line, <1,000 UTF-8 bytes;
+slash/bang tokens are rejected). To intentionally request a potentially mutating or interactive
+Code Puppy command, use /herdr command NAME /model gpt-5, not send.
+Discover known sender candidates/aliases with /herdr commands (core registry + plugin help).
+Unknown/unadvertised commands fail closed. The target may have different commands/plugins;
+recognized does not mean safe. Choose command only for intentionally authorized command intent.
+Both actions type into the terminal; verify target and actual foreground editor readiness.
+Idle is not editor-ready. Acknowledgement is only a write, not confirmed execution or receipt.
+Core preprocessing removes quotes, normalizes spaces, and may consume attachments on both sides;
+arguments are not byte-preserved. No automatic retries or atomic occupant-check guarantee.
+Use /herdr help for options. From shell tools use the installed interpreter to call
+code_puppy_core_plugins.herdr.launcher.execute('/herdr ...') and print the result;
+this is the same guarded API, not raw herdr input. Never probe by executing commands.
+"""

code_puppy_core_plugins-0.0.79/code_puppy_core_plugins/herdr/launch_command.py

@@ -0,0 +1,29 @@
+"""Private prompt handoff and bounded shell bootstrap commands."""
+
+import os
+import tempfile
+from pathlib import Path
+
+# Keep terminal input short and single-line, even before the shell editor starts.
+# The child owns deletion once it reads the file, before importing the CLI.
+BOOTSTRAP = (
+    "import runpy,sys,os;"
+    "p=sys.argv[1];"
+    "t=open(p,encoding='utf-8').read();"
+    "os.unlink(p);"
+    "sys.argv=['code_puppy',*sys.argv[2:],'--',t];"
+    "runpy.run_module('code_puppy',run_name='__main__',alter_sys=True)"
+)
+
+
+def prompt_file(prompt):
+    """Create an exclusive private UTF-8 handoff; never reuse a user file."""
+    descriptor, name = tempfile.mkstemp(prefix="puppy-herdr-", suffix=".txt")
+    path = Path(name)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8", newline="") as file:
+            file.write(prompt)
+    except BaseException:
+        path.unlink(missing_ok=True)
+        raise
+    return path