protoagent.plugin.yaml

# protoagent.plugin.yaml — DATA ONLY (the host reads this without importing code).
# Keep `version` in lockstep with pyproject.toml (tests/test_version.py asserts it).
id: github
name: GitHub (read/write tools)
version: 0.2.0
description: >-
  Read AND write GitHub tools over the `gh` CLI, with PER-AGENT write gating. The
  read tools (PRs, issues, diffs, CI, repo files/contents) are always on; the write
  tools (create/edit/merge/close issues & PRs, comment, labels, assignees) load ONLY
  when `github.write: true` — so a research/Lead agent stays read-only while a
  coding/PM agent gets write, purely by its own per-instance config (ADR 0019).
  Merging is `confirm`-guarded. Supersedes the read-only in-tree `github` plugin.
  Tools degrade to a readable error if `gh` isn't installed/authenticated.
enabled: false                 # SHIP DISABLED — enabling is the operator's trust decision
repository: https://github.com/protoLabsAI/github-plugin
min_protoagent_version: "0.27.0"

# Config (ADR 0019): defaults are the source of truth; langgraph-config.yaml overlays.
# `write` is the per-agent gate — each agent's config decides read-only vs read+write.
# `default_repo`/`repos` route the user-only `/issue` command (and the console views):
# explicit `--repo` > default_repo > first of repos > GITHUB_DEFAULT_REPO/GH_REPO env.
config_section: github
config:
  write: false                 # false = read tools only; true = read + write tools
  default_repo: ""             # preselected repo for /issue (owner/name); "" = none
  repos: []                    # repo picker list (each owner/name) for /issue + views

# Settings (ADR 0019) — surfaced as editable fields in the console.
settings:
  - {key: write, label: "Allow write tools (this agent)", type: bool}
  - {key: default_repo, label: "Default repo (owner/name)", type: string}
  - {key: repos, label: "Repo picker list", type: string_list}

# Console views (ADR 0026/0057) — sandboxed iframes the plugin serves itself (api.py).
#  - the READ-ONLY board (Issues/PRs tabs over the repo picker): right dock + a ⌘K morph
#    (`palette: inline` opens the board in the palette body). `placement: right` is just a
#    default — views are drag-sortable in the console.
#  - FILE AN ISSUE (the compact form): a util-bar widget pill (`utility`, opens its dialog)
#    AND a distinct ⌘K palette page (`palette: { path }`). Filing lives here + the palette,
#    NOT in the board — the board is a viewer.
views:
  - { id: github, label: GitHub, icon: Github, path: /plugins/github/view, placement: right, palette: inline }
  - { id: github-new-issue, label: New issue, icon: Bug, path: /plugins/github/new-issue, utility: { info: "File a GitHub issue" }, palette: { path: /plugins/github/new-issue } }

# Auth-exempt view PAGES — a browser iframe page-load can't carry a bearer, so under
# a token-gated deployment these would 401-blank without this. Needs a host with the
# plugin public_paths feature; older hosts ignore it (the pages stay open-mode only).
# The page is chrome; the DATA it fetches stays gated under /api/plugins/github/*.
public_paths:
  - /plugins/github/view
  - /plugins/github/new-issue

# Auth: `gh` uses its own ambient auth (`gh auth login`), or GITHUB_TOKEN / GH_TOKEN
# from the env if set. No plugin secret needed for public-repo reads.

# Declarative transparency (shown in the console; not yet enforced).
capabilities:
  network: ["api.github.com"]  # shells out to `gh`, which talks to api.github.com
  filesystem: none