Wire your agent into Gluecron.

═══════════════════════════════════════════════════════════════════════════════
HOLDEN MERCER × GLUECRON INTEGRATION SPEC
What HM needs to change on its side to support Gluecron-hosted repos
Gluecron API v1.1 — all endpoints below are LIVE (rolled out 2026-05-20)
═══════════════════════════════════════════════════════════════════════════════

TL;DR
─────────────────────────────────────────────────────────────────────────────
Your earlier read of Gluecron's API was based on v1, which lacked
/contents, /git/*, and /actions/workflows/:filename/dispatches. Those
gaps are now closed. Shapes match GitHub REST v3 exactly — a base-URL
swap reuses most of your existing GitHub integration. The "clone +
push" workaround you architected still works (path A below); the
native dispatch flow (path B) is now also available if you want it.

Required changes on HM's side
─────────────────────────────────────────────────────────────────────────────

1. ADD GLUECRON AS A DESTINATION
   Surface Gluecron alongside GitHub in your repo picker. Detect with:

     hostname === "gluecron.com"
       || process.env.GLUECRON_HOST    // self-hosted instances

2. SWAP THE BASE URL
   GitHub:    https://api.github.com
   Gluecron:  https://gluecron.com/api/v2
              (or https://<GLUECRON_HOST>/api/v2 for self-hosted)

3. SWAP THE AUTH TOKEN PREFIX — header name stays
   GitHub:    Authorization: Bearer ghp_…
   Gluecron:  Authorization: Bearer glc_…        (PAT, scope=repo)
              Or OAuth:      Bearer glct_…       (admin scope NOT issuable)
              Or App install:Bearer ghi_…

4. CHANGE NOTHING ELSE IN YOUR REQUEST/RESPONSE PARSING
   - Same field names (snake_case)
   - Same status codes
   - Same base64 content encoding
   - Same git-objects API surface

Endpoints HM will call
─────────────────────────────────────────────────────────────────────────────

READ FILES
  GET    /api/v2/repos/:owner/:repo/contents/:path?ref=<branch_or_sha>
         → { type, name, path, size, sha, encoding:"base64", content,
             html_url, download_url }

ATOMIC MULTI-FILE WRITE (preferred for agent turns)
  POST   /api/v2/repos/:owner/:repo/git/blobs
         body: { content, encoding: "utf-8" | "base64" }
         → { sha, url, size }

  POST   /api/v2/repos/:owner/:repo/git/trees
         body: { base_tree?, tree: [{ path, mode:"100644",
                                       type:"blob", sha|null }] }
         → { sha, url, tree[] }
         (sha:null in a tree entry = delete that path from base_tree)

  POST   /api/v2/repos/:owner/:repo/git/commits
         body: { message, tree, parents: [<head_sha>] }
         → { sha, tree, message, parents, author, html_url }

  GET    /api/v2/repos/:owner/:repo/git/refs/heads/:branch
         → { ref, object: { sha, type:"commit" } }

  PATCH  /api/v2/repos/:owner/:repo/git/refs/heads/:branch
         body: { sha: <new_commit>, force?: false }
         → { ref, object }   (422 if not fast-forward and force=false)

OPEN A PULL REQUEST
  POST   /api/v2/repos/:owner/:repo/pulls
         body: { title, body, base, head }
         → { id, number, title, state, html_url, ... }

DISPATCH A NATIVE BUILD ON GLUECRON ACTIONS  (optional — path B)
  POST   /api/v2/repos/:owner/:repo/actions/workflows/:filename/dispatches
         body: { ref:"main", inputs?: { prompt, model, … } }
         → 204 No Content

  GET    /api/v2/repos/:owner/:repo/actions/workflows/:filename/runs
         ?branch=&head_sha=&per_page=30&page=1
         → { total_count, workflow_runs:[...] }

  GET    /api/v2/repos/:owner/:repo/actions/runs/:run_id
         → { id, name, head_branch, head_sha, status, conclusion,
             event, created_at, updated_at, run_started_at, html_url }

  GET    /api/v2/repos/:owner/:repo/actions/runs/:run_id/logs
         → application/zip (one .log file per job)

  POST   /api/v2/repos/:owner/:repo/actions/runs/:run_id/cancel
         → 202 Accepted   (409 if already terminal)

User-side workflow file  (one-time setup per repo, for path B)
─────────────────────────────────────────────────────────────────────────────

If HM dispatches via path B, the user's repo needs a YAML committed to
.gluecron/workflows/holden-mercer.yml. Recommend this template:

  name: Holden Mercer build agent
  on:
    workflow_dispatch:
      inputs:
        prompt:
          description: What the agent should build / fix
          required: true
          type: string
        model:
          description: Anthropic model to use
          required: false
          default: claude-haiku-4-5
          type: string
  jobs:
    agent:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - name: Run HM agent
          env:
            ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
            HM_PROMPT:         ${{ inputs.prompt }}
            HM_MODEL:          ${{ inputs.model }}
          run: npx @holden-mercer/agent run

Two integration paths — pick one (or offer both in HM's UI)
─────────────────────────────────────────────────────────────────────────────

PATH A — Your-backend mode  (matches your original v1 workaround)
   1. Clone the repo using a credential helper (NOT URL-embedded token):
      git -c credential.helper=… clone https://gluecron.com/:owner/:repo.git
   2. Run the tool-use loop on HM's backend against local files
   3. Push the result via the git-objects API (one atomic commit):
      POST /git/blobs → /git/trees → /git/commits → PATCH /git/refs/heads
   4. POST /pulls to open the PR
   Pros: full control, you own compute. Cons: you bear all build minutes.

PATH B — Gluecron-native mode  (uses our runner)
   1. POST /actions/workflows/holden-mercer.yml/dispatches with inputs
   2. Your agent code runs inside Gluecron Actions on the user's repo
   3. The runner pushes commits + opens the PR itself
   Pros: zero infra on your side, lower egress. Cons: Gluecron concurrency
   + timeout limits apply per tier.

Both paths supported. Most vendors ship A first, add B later as an opt-in.

Webhook callback  (optional but recommended)
─────────────────────────────────────────────────────────────────────────────
Subscribe to pull_request + workflow_run events at
  /:owner/:repo/settings/webhooks
HMAC signature header:  X-Gluecron-Signature: sha256=<hex>
Delivery:               at-least-once with exponential backoff
                        (30s, 2m, 10m, 1h, 6h — max 6 attempts then
                        dead-letter)
Dedupe with:            X-Gluecron-Delivery: <uuid>

Compatibility checklist  (matches GitHub REST v3 by design)
─────────────────────────────────────────────────────────────────────────────
[x] Same endpoint shapes
[x] Same field names (snake_case)
[x] Same base64 content encoding
[x] Same status codes
[x] Same git plumbing API (blobs / trees / commits / refs)
[x] Same workflow_dispatch shape
[x] HMAC-SHA256 webhook signatures
[x] PKCE OAuth (RFC 7636)
[x] Pagination via ?limit, ?offset (default 30, max 100)

Differences to flag in HM's client code
─────────────────────────────────────────────────────────────────────────────
- Token prefix:    glc_ (PAT) / glct_ (OAuth) / ghi_ (app install)
- Pagination:      ?limit not ?per_page  (recommend limit)
- OAuth scopes:    namespaced — read:repo / write:repo  (admin NOT issuable)
- Webhook header:  X-Gluecron-Signature  not  X-Hub-Signature-256

Estimated work on HM's side
─────────────────────────────────────────────────────────────────────────────
- UI change (add Gluecron destination)          ~2-4 hrs
- API client base-URL/token swap                ~2-3 hrs
- Webhook handler for X-Gluecron-Signature      ~1 hr
- Path B dispatch integration  (optional)       ~4-6 hrs
TOTAL minimum (paths A only):  ~5-8 hrs
TOTAL with path B as well:     ~10-15 hrs

Support
─────────────────────────────────────────────────────────────────────────────
Live spec:   https://gluecron.com/docs/build-agent-integration  (this page)
Status:      https://gluecron.com/admin/health
Issues:      https://gluecron.com/ccantynz/Gluecron.com/issues
Contact:     ccantynz on gluecron.com
═══════════════════════════════════════════════════════════════════════════════

═══════════════════════════════════════════════════════════════════════════════
GLUECRON MCP TOOL SURFACE  (50+ tools, model-context-protocol/2025-06-18)
═══════════════════════════════════════════════════════════════════════════════

Transport:  POST /mcp           — JSON-RPC 2.0 (single or batch)
            GET  /mcp           — discovery handshake
Auth:       same as REST v2     — Bearer glc_… (PAT) or session cookie
            agent tokens (agt_…) routed via agent-multiplayer

Call shape:
  {
    "jsonrpc": "2.0", "id": 1,
    "method": "tools/call",
    "params": { "name": "<tool_name>", "arguments": { … } }
  }

─── READ TOOLS (public, no auth) ────────────────────────────────────────────
gluecron_repo_search                Search public repos by keyword
gluecron_repo_read_file             Read a file at a ref
gluecron_repo_list_issues           List open issues on a repo
gluecron_repo_explain_codebase      Cached AI 'explain this codebase' markdown
gluecron_repo_health                Health score + breakdown for a repo

─── REPOS (write — requires 'repo' or 'admin') ──────────────────────────────
gluecron_fork_repo                  Fork a repo to the caller's namespace
gluecron_delete_repo                Permanently delete a repo (admin)
gluecron_update_repo                Description / visibility / default branch
gluecron_search_repos               Full search (sort, limit, filters)
gluecron_clone_url                  Authed HTTPS clone URL + helper hint

─── ISSUES (write — requires 'repo') ────────────────────────────────────────
gluecron_create_issue               Open a new issue
gluecron_comment_issue              Add a comment
gluecron_close_issue                Close an open issue (idempotent)
gluecron_reopen_issue               Reopen a closed issue
gluecron_label_issue                Attach labels (auto-creates missing)
gluecron_unlabel_issue              Detach a single label
gluecron_assign_issue               Assign to a user (via assignee:* label)
gluecron_search_issues              Title/body keyword search per repo

─── PULL REQUESTS (write — requires 'repo') ─────────────────────────────────
gluecron_create_pr                  Open a PR
gluecron_open_draft_pr              Open a draft PR
gluecron_get_pr                     Fetch full PR record
gluecron_list_prs                   List PRs by state
gluecron_search_prs                 Keyword search on title/body
gluecron_comment_pr                 Add a PR comment
gluecron_request_changes            Post an AI-review 'changes requested' comment
gluecron_merge_pr                   Merge a PR (enforces every gate + risk score)
gluecron_close_pr                   Close without merging (idempotent)
gluecron_generate_pr_description    AI commit-message-style description

─── FILES & GIT PLUMBING (write — requires 'repo') ──────────────────────────
gluecron_read_file                  GET /contents wrapper
gluecron_write_file                 PUT /contents wrapper (utf8 or base64)
gluecron_delete_file                DELETE /contents wrapper
gluecron_list_tree                  GET /tree wrapper (recursive supported)
gluecron_get_commit                 GET /commits/:sha wrapper
gluecron_create_branch              Create a new branch ref at a sha
gluecron_atomic_multi_file_commit   blob/tree/commit/ref-update in one call
                                    — the killer agent tool

─── AI WORKFLOWS (Gluecron-native — requires 'repo') ────────────────────────
gluecron_ship_spec                  Drop .gluecron/specs/*.md status:ready
gluecron_voice_to_pr                Transcript → spec or issue (auto-classified)
gluecron_refactor_across_repos      Plan + execute a multi-repo refactor
gluecron_explain_repo               Cached 'explain this repo' markdown
gluecron_chat_with_repo             Start a chat + send the first message
gluecron_chat_continue              Send another message in a chat
gluecron_generate_tests             AI tests for a PR (follow-up-pr / append)
gluecron_generate_commit_message    Conventional / plain commit message for a diff
gluecron_generate_release_notes     Section-bucketed notes between two tags
gluecron_propose_migration          Dep-upgrade PR via migration-assistant
gluecron_propose_doc_update         Doc-drift scan + PR opens

─── CI / DEPLOYS (write — requires 'repo') ──────────────────────────────────
gluecron_trigger_workflow           workflow_dispatch
gluecron_get_workflow_run           Run status + metadata
gluecron_get_workflow_logs          Per-job log payload (JSON; ZIP via REST)
gluecron_cancel_workflow_run        Cancel queued/running run
gluecron_get_preview_url            Branch-preview URL + status
gluecron_provision_pr_sandbox       Re-provision a PR sandbox

─── AGENTS (multiplayer surface — admin to mint, repo to lease) ─────────────
gluecron_create_agent_session       Mint agent token (returned ONCE) (admin)
gluecron_acquire_lease              Grab an exclusive target lease
gluecron_release_lease              Release a held lease
gluecron_get_agent_budget           spent / cap / remaining cents

─── SEMANTIC ────────────────────────────────────────────────────────────────
gluecron_semantic_search            Vector-index query (Voyage or hash)
gluecron_find_symbol                findDefinitions wrapper

─── INSIGHTS ────────────────────────────────────────────────────────────────
gluecron_pr_status_summary          State + risk + trio verdict for a PR
gluecron_repo_health                (also under READ; included here for parity)
gluecron_ai_cost_summary            Spend rollup (user / repo / agent)

═══════════════════════════════════════════════════════════════════════════════