code-puppy-core-plugins 0.0.2__py3-none-any.whl

code_puppy_core_plugins/code_puppy_agent/SKILLS_SYSTEM.md

@@ -0,0 +1,136 @@
+# Skills System
+
+> Part of the `code-puppy-agent` skill. Read this when working with
+> skill discovery/activation, or extending how skills are presented to
+> the model. See `SKILL.md` for the overview and the full reference map.
+
+---
+
+## How skills work
+
+A skill is a directory containing a `SKILL.md` with YAML frontmatter
+(`name`, `description`, optional `version`, `author`, `tags`) and
+markdown body. The body is the instruction set loaded into context when
+the skill is activated.
+
+## Skill discovery (`plugins/agent_skills/discovery.py`)
+
+Scans these directories (first-discovered wins on name collision):
+1. `~/.code_puppy/skills/`
+2. `<CWD>/.code_puppy/skills/`
+3. `<CWD>/skills/`
+4. Plugin-registered skills (via `register_skills` callback)
+
+## Skill activation flow
+
+1. The model calls `activate_skill("skill-name")` or the user types
+   `/<skill-name>`
+2. The tool reads the full `SKILL.md` from disk
+3. Content is injected into the model's context as a tool result
+4. The model follows the instructions in its next response
+
+Skills are **opt-in** — by default the model sees a one-line summary in
+its system prompt (name + description) and must explicitly activate to
+get full instructions. At small catalog sizes (a handful to a few dozen
+skills) this flat list is fine. It stops scaling well before a few
+hundred skills — see "Skill namespaces" below.
+
+### Bundled resource files: filesystem skills vs. plugin-registered skills
+
+`activate_skill` returns a `resources: List[str]` field listing files
+bundled alongside `SKILL.md` (via `get_skill_resources()`), which the
+model can then `read_file()` on demand instead of everything being
+force-loaded on activation. This works cleanly for a **filesystem**
+skill (a real directory under one of the scanned paths above) — any
+sibling file just shows up.
+
+It does **not** work the same way for a skill registered via the
+`register_skills` callback with `skill_md_path` (like this skill,
+`code-puppy-agent`, and `namespace_skill_search` originally considered
+before dropping the idea): the discovery loader materializes only
+`SKILL.md` itself into a cache directory (plus an optional `scripts_dir`
+entry, and even that isn't surfaced through `get_skill_resources` since
+it lands as a subdirectory, not a file). **If you want a plugin-owned
+skill to reference sibling docs, put real repo paths in the SKILL.md
+prose and let the model `read_file()` them directly** — don't rely on
+the `resources` field to surface them. This document you're reading
+right now is exactly that pattern: `SKILL.md` names this file by its
+real path in the repo rather than expecting it to appear as a
+`resources` entry.
+
+## Managing skills
+
+| Command | Effect |
+|---------|--------|
+| `/skills` | Interactive TUI menu |
+| `/skills list` | Text list of all skills |
+| `/skills enable` / `disable` | Toggle skills globally |
+| `/skills frontmatter on/off` | Toggle skill summaries in system prompt |
+| `/skills install` | Browse & install from remote catalog |
+
+---
+
+## Skill namespaces (large catalogs)
+
+The **`namespace_skill_search`** builtin plugin
+(`code_puppy/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
+large catalog (tools, MCP servers, etc.).
+
+**Shape:** groups skills into **namespaces** — each skill's namespace is
+its first `tags:` entry (untagged skills fall back to a `General`
+namespace) — and replaces the flat per-skill system-prompt list with a
+compact namespace directory, plus a new `browse_skill_namespace` tool
+with three modes (no-args directory listing, `namespace=` drill-down,
+`query=` keyword search across everything). This mirrors OpenAI's
+shipped `tool_search` + namespace-grouping pattern and Anthropic's
+shipped Tool Search Tool, reimplemented in a model-agnostic way (no
+provider-specific request fields) using only Code Puppy's existing
+plugin hooks.
+
+**User-facing docs:** `docs/AGENT_SKILLS.md` → "Skill Namespaces (Large
+Catalogs)" section — what changes automatically, the tool's three
+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
+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
+this reference set for those gotchas explained in general terms, not
+tied to this one plugin).
+
+**Implementation details worth knowing if you're extending it:**
+- Namespace grouping is **case-insensitive at build time** — skills
+  tagged `finance`/`Finance`/`FINANCE` merge into one namespace, keyed
+  by first-seen casing. This isn't optional; the tool's `namespace=`
+  lookup is case-insensitive, so case-sensitive grouping would let two
+  namespaces silently fragment while looking like a single one from the
+  tool's perspective.
+- A blank/whitespace-only `query` means "no filter," not "match
+  nothing" — a naive `any(term in haystack for term in
+  query.lower().split())` degrades to `any([])` (`False`) for every
+  skill on an empty query, which is a genuinely easy trap to fall into
+  with keyword-filter code in general, not specific to this plugin.
+- Duplicate skill names across namespaces are flagged in the directory
+  output (not deduped or resolved) — `activate_skill(name)` has no way
+  to disambiguate between two skills sharing a name, and that's an
+  `agent_skills`-level gap this plugin surfaces more visibly rather than
+  causes.
+
+## When to reach for `list_or_search_skills` / `activate_skill` vs. `browse_skill_namespace`
+
+Both exist simultaneously and are not mutually exclusive:
+- `list_or_search_skills` — the original, flat, always-available tool.
+  Fine for small catalogs or when you already roughly know the skill
+  name.
+- `browse_skill_namespace` — better when the catalog is large enough
+  that `namespace_skill_search` has replaced the flat prompt block with
+  a namespace directory, and you want to browse by domain or search
+  across everything without scanning a huge flat list yourself.
+
+Either way, the terminal step is the same: `activate_skill(name)` to
+load the full instructions.

code_puppy_core_plugins/code_puppy_agent/SYSTEM_PROMPT_CONFIG_AND_I18N.md

@@ -0,0 +1,160 @@
+# System Prompt Assembly, Configuration, Messaging & i18n
+
+> Part of the `code-puppy-agent` skill. Read this when debugging what
+> ends up in the system prompt (and in what order), working with
+> `puppy.cfg`, emitting UI messages from a plugin, or wrapping
+> user-facing strings for i18n. See `SKILL.md` for the overview and the
+> full reference map.
+
+---
+
+## System Prompt Assembly
+
+Assembled in two stages: `get_full_system_prompt()` builds the base
+(`base_agent.py`), then `_assemble_instructions()` (`_builder.py`)
+appends rules and runs the per-model patcher.
+
+`get_full_system_prompt()` layers:
+
+```
+1. Authored prompt   (agent.get_system_prompt())
+2. load_prompt fragments (plugin-injected: kennel memory, permission
+   rules, namespace_skill_search's namespace directory, …)
+3. Identity ID        (agent name + UUID prefix)
+```
+
+`_assemble_instructions()` then appends:
+
+```
+4. AGENTS.md puppy_rules  (global ~/.code_puppy/AGENTS.md, then project
+   <CWD>/.code_puppy/AGENTS.md, then ./AGENTS.md fallback — concatenated,
+   not first-wins)
+5. Extended-thinking note  (only if active for the resolved model)
+6. Per-model patches       (get_model_system_prompt callbacks, via
+   prepare_prompt_for_model) — this is where the **skills block**
+   (available-skills summary) is appended, by the agent_skills plugin
+```
+
+> The skills summary is **not** a `load_prompt` fragment — it's injected
+> through `get_model_system_prompt`, so it lands *after* identity and
+> rules. **This is exactly the phase `namespace_skill_search` avoids
+> registering a second callback on** — see `PLUGINS_AND_CALLBACKS.md`
+> for why (`get_model_system_prompt` is last-write-wins across plugins,
+> not additive like `load_prompt`).
+
+Layers 2–6 are **runtime-only** — recomputed every run, never persisted
+into static agent definitions. This prevents stale timestamps, dead file
+paths, and baked-in session IDs from leaking into cloned agents.
+
+---
+
+## Configuration System (`config.py`)
+
+All settings live in `~/.code_puppy/puppy.cfg` (INI format) managed via:
+- `get_value(key)` / `set_value(key, value)`
+- `/set <key> <value>` slash command
+
+Key directories:
+- **Config root**: `~/.code_puppy/`
+- **State/sessions**: `~/.code_puppy/state/` (or platform cache dir)
+- **Cache**: `~/.code_puppy/cache/`
+- **Agents**: `~/.code_puppy/agents/`
+- **Skills**: `~/.code_puppy/skills/`
+- **Plugins**: `~/.code_puppy/plugins/`
+- **Extra models**: `~/.code_puppy/extra_models.json`
+
+AGENTS.md rules files are loaded from `~/.code_puppy/AGENTS.md` (global),
+`<CWD>/.code_puppy/AGENTS.md` (project), and `./AGENTS.md` (fallback).
+
+### Disabling a plugin
+
+`/plugins disable <name>` writes to the `disabled_plugins` config key
+(JSON list) via `code_puppy/plugins/config.py`. A disabled plugin's
+callbacks are skipped entirely — but any *persisted config change* the
+plugin already made before being disabled (e.g. `namespace_skill_search`
+turning off `frontmatter_in_system_prompt` on its first run) does **not**
+automatically revert. Disabling the plugin and undoing what it already
+did to your config are two separate actions.
+
+---
+
+## Messaging & UI
+
+### Message bus (`messaging/`)
+
+Plugins emit UI messages through the message bus rather than printing
+directly:
+
+```python
+from code_puppy.messaging import emit_info, emit_success, emit_warning, emit_error
+emit_info("Something happened")
+```
+
+These are rendered by the TUI's event handler, so they work in both
+interactive and streaming contexts.
+
+### Event streaming (`agents/event_stream_handler.py`)
+
+The agent's streaming response is handled by `event_stream_handler`,
+which processes pydantic-ai streaming events (text deltas, tool calls,
+tool returns) and emits UI messages. The `stream_event` callback lets
+plugins observe these events.
+
+---
+
+## Internationalization (i18n)
+
+User-facing CLI/TUI text is localizable via the `code_puppy/i18n/` package
+(stdlib-only; no Babel). **Full guide: `docs/I18N.md`.** Epic: PUP-473.
+This section is a quick-reference cheat sheet, not a replacement for that
+doc.
+
+### Call sites
+
+```python
+from code_puppy.i18n import t, ngettext, lazy
+emit_info(t("startup.welcome", name=owner))     # simple, interpolated
+emit_info(ngettext("files.deleted", count=n))   # plural-aware
+emit_info(lazy("startup.ready"))                 # resolved at render time
+```
+
+- Keys are dotted IDs; **interpolation uses `{name}` only** — no f-strings,
+  no `str.format` on catalog text (attribute/index access and format specs are
+  deliberately unsupported; catalogs are untrusted input).
+- A missing key echoes the key back — resolution **never raises**.
+
+### Catalogs & locales
+
+- JSON per locale: `i18n/locales/<locale>.json` (dotted-key → string, or a
+  plural dict `{"one": ..., "other": ...}`).
+- Shipped: `en-US` (source), `es` (Latin American `es-419` folded in), and
+  `fr-CA`. Regional catalogs are added only when reviewed translations exist.
+- **Fallback chain**: plain BCP-47 truncation, `es-AR → es → en-US` (see
+  `i18n.locale.fallback_chain`). `i18n.locale.PARENT_LOCALES` is a currently-
+  empty CLDR override seam for non-truncation parents. Plugins / the private
+  fork can register extra catalog dirs via `i18n.catalog.add_catalog_dir()`.
+
+### How it wires in
+
+- **Choke point**: `messaging/message_queue.py::emit_message` resolves a
+  `LazyTranslation` to a string; plain strings pass through unchanged.
+- **Locale**: `config.get_locale()` is the single source of truth (delegates
+  to the i18n translator), seeded `CODE_PUPPY_LOCALE` › `locale` config key ›
+  POSIX env › `en-US`. `/set locale <tag>` persists it.
+- **Formatting**: `i18n.format_number` / `i18n.format_datetime` (locale-aware).
+
+### Rules
+
+- **Model-facing system prompts are OUT of scope** — translating them changes
+  LLM behavior. Don't run them through the seam. (This is why
+  `namespace_skill_search`'s namespace-directory prompt fragment is plain,
+  un-wrapped English — it's model-facing content, not user-facing UI text.)
+- Extraction goes behind the coverage/pseudolocale CI gate
+  (`tests/i18n/test_i18n_coverage.py`): every translated key must exist in the
+  `en-US` source, and a pseudolocale (`en-XA`) run must emit only bracketed
+  text (catches un-externalized strings).
+- **Find what's left to extract** with the static audit:
+  `python -m code_puppy.i18n.audit --top 15` lists the worst files;
+  `--list` shows every raw `emit_*`/`console.print` site, `--json` is
+  machine-readable, and `--fail-under PCT` is a CI gate. Use it to pick the
+  next module, then the pseudolocale test above to prove it's fully migrated.

code_puppy_core_plugins/code_puppy_agent/__init__.py

@@ -0,0 +1,5 @@
+"""Builtin skill: ``code-puppy-agent``.
+
+Ships a SKILL.md that explains Code Puppy's internal architecture so the
+LLM can navigate the codebase and extend the product correctly.
+"""

code_puppy_core_plugins/code_puppy_agent/register_callbacks.py

@@ -0,0 +1,46 @@
+"""Register the built-in ``code-puppy-agent`` skill.
+
+The skill's SKILL.md lives alongside this file and is an *index* into a
+set of topic-specific reference files (``AGENTS_AND_TOOLS.md``,
+``PLUGINS_AND_CALLBACKS.md``, ``MODELS_AND_MCP.md``,
+``SESSIONS_AND_HISTORY.md``, ``SKILLS_SYSTEM.md``,
+``SYSTEM_PROMPT_CONFIG_AND_I18N.md``) in the same directory. This keeps
+any single activation cheap while still covering the full internals
+surface -- see SKILL.md's "Reference Map" for which file answers which
+question.
+
+We register it via the ``register_skills`` callback so the agent_skills
+plugin materializes it into the plugin-skill cache and it shows up in
+``/skills list``, ``activate_skill``, and the system-prompt skill block --
+just like any user-installed skill.
+
+Note: only ``skill_md_path`` is registered below, not the reference
+files. Plugin-registered skills (``skill_md_path``/``skill_md``/
+``frontmatter``+``body``) only ever materialize ``SKILL.md`` itself into
+the runtime cache -- sibling files are NOT auto-discovered as
+``resources`` the way they would be for a real filesystem skill
+directory. That's why SKILL.md references the other files by their real
+repo paths in prose (for the model to ``read_file`` on demand) rather
+than relying on the ``resources`` field ``activate_skill`` returns.
+"""
+
+from pathlib import Path
+
+from code_puppy.callbacks import register_callback
+
+_SKILL_DIR = Path(__file__).resolve().parent
+
+
+def _register_builtin_skills() -> list[dict]:
+    # This "name" MUST match the SKILL.md frontmatter ``name:``: it drives dedup +
+    # the disable-set, while frontmatter name drives display; a mismatch would
+    # silently break ``/skills enable|disable`` and the alias.
+    return [
+        {
+            "name": "code-puppy-agent",
+            "skill_md_path": str(_SKILL_DIR / "SKILL.md"),
+        }
+    ]
+
+
+register_callback("register_skills", _register_builtin_skills)

code_puppy_core_plugins/computer_use/NativeCapture.swift

@@ -0,0 +1,123 @@
+import AppKit
+import CoreGraphics
+import Foundation
+import ScreenCaptureKit
+
+enum CaptureFailure: LocalizedError {
+    case message(String)
+
+    var errorDescription: String? {
+        switch self {
+        case .message(let text): return text
+        }
+    }
+}
+@main
+struct NativeCapture {
+    static func scale(for frame: CGRect) -> CGFloat {
+        let midpoint = CGPoint(x: frame.midX, y: frame.midY)
+        for screen in NSScreen.screens {
+            guard
+                let number = screen.deviceDescription[
+                    NSDeviceDescriptionKey("NSScreenNumber")
+                ] as? NSNumber
+            else { continue }
+            let bounds = CGDisplayBounds(CGDirectDisplayID(number.uint32Value))
+            if bounds.contains(midpoint) {
+                return screen.backingScaleFactor
+            }
+        }
+        return NSScreen.main?.backingScaleFactor ?? 1
+    }
+
+    static func matchingApplication(_ query: String) throws -> NSRunningApplication {
+        let wanted = query.lowercased()
+        guard let app = NSWorkspace.shared.runningApplications.first(where: {
+            ($0.localizedName ?? "").lowercased() == wanted
+                || ($0.bundleIdentifier ?? "").lowercased() == wanted
+        }) else {
+            throw CaptureFailure.message("Running application not found: \(query)")
+        }
+        return app
+    }
+
+    static func run(appName: String, outputPath: String) async throws -> [String: Any] {
+        let app = try matchingApplication(appName)
+        let content = try await SCShareableContent.excludingDesktopWindows(
+            false,
+            onScreenWindowsOnly: false
+        )
+        let candidates = content.windows.filter {
+            guard $0.owningApplication?.processID == app.processIdentifier else {
+                return false
+            }
+            return $0.frame.width >= 200 && $0.frame.height >= 120
+        }
+        guard let window = candidates.max(by: {
+            $0.frame.width * $0.frame.height < $1.frame.width * $1.frame.height
+        }) else {
+            throw CaptureFailure.message("No capturable window found for \(appName).")
+        }
+
+        let scale = scale(for: window.frame)
+        let configuration = SCStreamConfiguration()
+        configuration.width = max(1, Int((window.frame.width * scale).rounded()))
+        configuration.height = max(1, Int((window.frame.height * scale).rounded()))
+        configuration.showsCursor = false
+        configuration.scalesToFit = false
+        let filter = SCContentFilter(desktopIndependentWindow: window)
+        let image = try await SCScreenshotManager.captureImage(
+            contentFilter: filter,
+            configuration: configuration
+        )
+        let representation = NSBitmapImageRep(cgImage: image)
+        guard let data = representation.representation(
+            using: .png,
+            properties: [:]
+        ) else {
+            throw CaptureFailure.message("Could not encode screenshot as PNG.")
+        }
+        try data.write(to: URL(fileURLWithPath: outputPath), options: .atomic)
+
+        return [
+            "application": app.localizedName ?? appName,
+            "bundle_id": app.bundleIdentifier ?? "",
+            "pid": Int(app.processIdentifier),
+            "window_id": Int(window.windowID),
+            "window_title": window.title ?? "",
+            "backing_scale": Double(scale),
+            "window_bounds_points": [
+                "x": Double(window.frame.origin.x),
+                "y": Double(window.frame.origin.y),
+                "width": Double(window.frame.width),
+                "height": Double(window.frame.height),
+            ],
+            "screenshot_size_pixels": [
+                "width": configuration.width,
+                "height": configuration.height,
+            ],
+        ]
+    }
+
+    static func main() async {
+        guard CommandLine.arguments.count == 3 else {
+            FileHandle.standardError.write(
+                Data("usage: native-capture APP OUTPUT.png\n".utf8)
+            )
+            exit(2)
+        }
+        do {
+            let payload = try await run(
+                appName: CommandLine.arguments[1],
+                outputPath: CommandLine.arguments[2]
+            )
+            let data = try JSONSerialization.data(withJSONObject: payload)
+            FileHandle.standardOutput.write(data)
+        } catch {
+            FileHandle.standardError.write(
+                Data("\(error.localizedDescription)\n".utf8)
+            )
+            exit(1)
+        }
+    }
+}

code_puppy_core_plugins/computer_use/README.md

@@ -0,0 +1,109 @@
+# macOS Computer Use
+
+This opt-in plugin lets Code Puppy inspect and operate the current macOS desktop
+through Apple's Accessibility APIs. It is macOS-only and does not use a virtual
+machine or copy any Codex implementation.
+
+## Install
+
+```bash
+pip install "code-puppy[computer-use]"
+```
+
+On first use, macOS requests permissions for the terminal or application that
+runs Code Puppy:
+
+1. **Accessibility** for inspecting and operating controls.
+2. **Screen Recording** for screenshots.
+
+Grant these under **System Settings → Privacy & Security**. Restart Code Puppy
+after changing Screen Recording access.
+
+Computer Use is off by default: its tools are not exposed to the model until
+you explicitly opt in. On macOS, Code Puppy shows a launch reminder with the
+enable command. The choice is stored in the normal Code Puppy settings directory:
+
+```text
+/computer-use enable
+/computer-use disable
+/computer-use status
+```
+
+You can change this setting at any time. Once enabled, Computer Use runs
+without per-application approval prompts or an allowlist.
+
+Use `/computer-use pause` as an emergency stop and `/computer-use resume` only
+after confirming it is safe. `/computer-use deny BUNDLE_ID` persists an
+exception, and `/computer-use allow BUNDLE_ID` removes that exception. Login,
+authorization, Keychain, and System Settings processes are always blocked.
+
+Snapshots, explicit screenshots, and successful batches display a compact
+inline preview in Ghostty, Kitty, WezTerm, and iTerm2. The same PNG is attached
+to the tool result so multimodal models can inspect it directly. App-targeted
+snapshots capture that application's largest standard window even when another
+application is in front.
+
+## Agent workflow
+
+1. Call `computer_get_app_state` with an application name.
+2. Use its screenshot, pruned focused-window accessibility tree, and
+   `state_revision` to choose an action. Prefer an element ID and one of the
+   element's advertised actions.
+3. Run one mutation, or one guarded batch of at most 20 mutations.
+4. Fetch fresh state. A completed batch does this automatically after waiting
+   for the accessibility tree to stabilize.
+
+Before every mutation, the target process is activated and verified as the
+frontmost application. This is required because ScreenCaptureKit can capture a
+background window, while Quartz sends global clicks and keystrokes to whichever
+application is actually frontmost. Use a guarded batch for click-then-type
+workflows so focus is retained and the result is verified in one control loop.
+
+Pixel clicks and drags use window-local screenshot pixels. The backend converts
+them to global Quartz points using the captured window bounds, so Retina scaling,
+negative display origins, and windows on secondary displays remain consistent.
+Scrolling accepts `up`, `down`, `left`, or `right` and a fractional page count.
+Text selection supports an exact match, optional prefix/suffix disambiguation,
+and cursor placement before or after the match.
+
+## Safety
+
+- Prefer accessibility element IDs over pixel coordinates.
+- Persisted user consent is required before tools are exposed to the model;
+  disabling the feature removes them again and blocks future captures/actions.
+- State revisions and element IDs are single-use and expire after 120 seconds.
+- Physical keyboard and pointer input do not interrupt YOLO-mode execution.
+- Every capture and mutation re-checks the application policy; the emergency
+  stop therefore also interrupts a batch at its next action boundary.
+- Password-field values are never returned in snapshots.
+- Batches stop at the first failed action, contain at most 20 steps, wait for
+  deterministic UI stability, and return updated screenshot/tree state.
+- The plugin does not pause for consequential-action confirmations in YOLO
+  mode. Use `/computer-use pause` when autonomous interaction should stop.
+
+## Native capture and privacy
+
+Application screenshots use ScreenCaptureKit through the bundled Swift helper.
+The helper is compiled locally, cached with a source hash, and returns stable
+window metadata: bundle ID, PID, window ID/title, bounds, pixel dimensions, and
+backing scale. Screenshot PNGs are temporary local files. This plugin does not
+add telemetry, persistent action history, lock-screen automation, or privileged
+system interaction.
+
+The first native capture requires Xcode Command Line Tools because the bundled
+helper is compiled on the Mac:
+
+```bash
+xcode-select --install
+```
+
+## Test
+
+```bash
+uv run ruff check code_puppy/plugins/computer_use tests/plugins
+uv run pytest tests/plugins/test_computer_use_*.py -q --no-cov
+```
+
+For a live Ghostty smoke test, launch Code Puppy from Ghostty and ask for
+`computer_get_app_state`. A compact image should appear inline; the tool result
+still carries the PNG if the terminal protocol is unavailable.

code_puppy_core_plugins/computer_use/__init__.py

@@ -0,0 +1 @@
+"""Opt-in macOS computer-use tools."""