pm-agent
e8e9de8611
From Gitea issue #116. Authored by the PM agent's worker; the merge gate is the approver. Refs #116. Agent: pm-agent (issue #116, mode revise)
194 lines
12 KiB
YAML
194 lines
12 KiB
YAML
---
|
|
# =============================================================================
|
|
# The dispatcher's configuration. Everything here is NON-SECRET and reviewable in a diff;
|
|
# the two credentials live in pm-agent-credentials.sops.yaml and are referenced by name only
|
|
# (R-IDP-04).
|
|
#
|
|
# WHAT IS *NOT* HERE, on purpose:
|
|
# * the PM persona — baked into the image at /etc/pm-agent/pm-persona.md. It is the
|
|
# agent's standing instruction set, and a ConfigMap is `kubectl edit`-able by anyone with
|
|
# namespace write. Changing how the PM behaves should be a reviewed commit and an image
|
|
# rebuild, not a live edit. (PM_PERSONA_FILE below can point elsewhere, which is the
|
|
# escape hatch for someone deliberately experimenting.)
|
|
# * the worker Job template — likewise baked in, and for a stronger reason: the template IS
|
|
# the shape the admission policy and the dispatcher's RBAC jointly bound. See the header
|
|
# of infra/agent/worker-job-template.yaml.
|
|
#
|
|
# NO SHELL-STYLE EXPANSIONS BELOW — AND THAT RULE APPLIES TO THESE COMMENTS TOO.
|
|
# This namespace's Flux Kustomization substitutes from cluster-vars, and envsubst runs over
|
|
# the WHOLE rendered manifest, comment lines included. So an unescaped dollar-brace token
|
|
# anywhere in this file — even in prose explaining the rule — is either replaced with the
|
|
# empty string or, if it is not a valid name, fails the ENTIRE Kustomization. This paragraph
|
|
# used to contain two such tokens as examples and the gate refused the change for it
|
|
# (ci/l0.sh, flux-postbuild-substitution: 1 UNDEFINED + 1 FATAL-PARSE), which is the check
|
|
# working exactly as intended. Every value below is a literal, including the Gitea URL — see
|
|
# the comment on it. The escaping contract itself: catalog/README.md.
|
|
# =============================================================================
|
|
apiVersion: v1
|
|
kind: ConfigMap
|
|
metadata:
|
|
name: pm-agent-config
|
|
namespace: pm-agent
|
|
labels:
|
|
app.kubernetes.io/name: pm-agent
|
|
app.kubernetes.io/part-of: pm-agent
|
|
data:
|
|
# --- where the work comes from ---------------------------------------------
|
|
# THE IN-CLUSTER SERVICE ADDRESS, NOT THE PUBLIC HOSTNAME, and for the same reason prod's
|
|
# own Flux source uses it (clusters/prod/kustomization.yaml): this path depends on neither
|
|
# public DNS, nor Cloudflare, nor the shared Gateway, nor the BASE_DOMAIN knob. A change of
|
|
# domain, a certificate problem or a Gateway outage cannot sever the agent from the
|
|
# repository it works on. It is also why the egress policy can be a pod-identity rule rather than a
|
|
# `world` allow, and why pm-worker's baked-in host allowlist can be two entries long.
|
|
PM_GITEA_URL: "http://gitea.gitea.svc.cluster.local:3000"
|
|
PM_GITEA_OWNER: "Home-Network"
|
|
PM_GITEA_REPO: "home-network-k3s-impl"
|
|
PM_BASE_BRANCH: "main"
|
|
PM_NAMESPACE: "pm-agent"
|
|
|
|
# --- what runs the work ----------------------------------------------------
|
|
# THE WORKER IMAGE, DIGEST-PINNED. This must be the SAME digest the Deployment runs, since
|
|
# the dispatcher and its workers share the committed Job template and the env-name
|
|
# contract. A tag here is refused at startup (and would be DENIED by admission anyway).
|
|
#
|
|
# THE FIRST PUBLISHED DIGEST. CI builds, verifies and — on main — publishes agent-runner
|
|
# (.gitea/workflows/images.yaml). This value is images run 340's publish (tag
|
|
# sha-523cd9118f95, which `main` pointed at), read from the registry on 2026-10-30. From here
|
|
# on Renovate replaces it with the digest the REGISTRY returns for the `main` tag, in a pull
|
|
# request that also moves the Deployment's image (same marker, same branch). Nobody pushes
|
|
# this image from a workstation.
|
|
#
|
|
# The run-340 digest predated the worker template's `imagePullSecrets` entry (PR #61), which
|
|
# admission REQUIRES, so its worker Jobs were DENIED. The digest below (df36d9b, run 383,
|
|
# agent-runner:sha-ddd04d460ef6, pinned in PR #96) bakes a template that carries
|
|
# `imagePullSecrets: pm-agent-registry`, which is what made turning PM_DRY_RUN off possible
|
|
# (decisions/2026-10-31-pm-agent-runner-digest.md). A digest older than that would be DENIED.
|
|
# The digest below (14a42ba, images run 394, agent-runner:sha-466f63ec3c3d = PR #99's merge)
|
|
# adds the CLI failure envelope to triage errors and the PM_DECISION_MAX_TURNS knob
|
|
# (decisions/2026-10-31-pm-agent-digest-99.md).
|
|
# renovate-digest: image=gitea.home.keithjackson.dev/home-network/agent-runner tag=main
|
|
PM_WORKER_IMAGE: "gitea.home.keithjackson.dev/home-network/agent-runner@sha256:14a42ba8281ecd98005f5d99ecda4fb729104c783b01584097c32e104ced1bb2"
|
|
|
|
# --- the model -------------------------------------------------------------
|
|
# The PM only reads a thread and answers with one JSON object, so it holds no tools and
|
|
# takes one turn. The worker does real repository work against a gate. Both run on the
|
|
# most capable general model on purpose: the failure mode that matters here is a plausible
|
|
# change that is subtly wrong, which is exactly what a cheaper tier buys more of.
|
|
PM_MODEL: "claude-opus-5"
|
|
PM_WORKER_MODEL: "claude-opus-5"
|
|
|
|
# --- pace and blast radius -------------------------------------------------
|
|
# These five numbers are the throttle. They exist because the first minute after the
|
|
# credentials are filled in is the dangerous one: every open issue is new to the agent at
|
|
# once.
|
|
#
|
|
# PM_POLL_INTERVAL_SECONDS how long an issue may wait before the PM looks at it.
|
|
# PM_MAX_ACTIVE_WORKERS concurrent worker Jobs. RAM is the binding constraint on this
|
|
# 3-node cluster and each worker's limit is 2Gi, so 2 is 4Gi
|
|
# worst case. It is also a subscription-rate-limit throttle:
|
|
# several Claude Code sessions on one subscription seat contend
|
|
# for the same account limits.
|
|
# PM_MAX_NEW_WORKERS_PER_CYCLE at most one NEW assignment per poll, so a backlog is
|
|
# drained one issue at a time rather than in one stampede.
|
|
# PM_ISSUE_COOLDOWN_SECONDS how often one issue may cost a decision. The dispatcher stamps
|
|
# this BEFORE it asks the model, so a decision that then fails
|
|
# cannot be retried on every poll.
|
|
# PM_WORKER_MAX_BUDGET_USD per-assignment spend ceiling the CLI enforces itself. It is
|
|
# Claude Code's own client-side estimate rather than a bill, so
|
|
# treat it as a runaway-loop stop, not as accounting.
|
|
PM_POLL_INTERVAL_SECONDS: "60"
|
|
PM_MAX_ACTIVE_WORKERS: "2"
|
|
PM_MAX_NEW_WORKERS_PER_CYCLE: "1"
|
|
PM_ISSUE_COOLDOWN_SECONDS: "900"
|
|
PM_WORKER_MAX_TURNS: "80"
|
|
PM_WORKER_MAX_BUDGET_USD: "10"
|
|
|
|
# --- scope -----------------------------------------------------------------
|
|
# EMPTY MEANS EVERY OPEN ISSUE, which is the behaviour this service was asked for: it
|
|
# reacts to issue creation and to comments, on all of them.
|
|
#
|
|
# RECOMMENDED FOR THE FIRST WEEKS, and a one-word change: set this to `agent`, and the
|
|
# dispatcher considers only issues a human has labelled `agent`. That bounds the agent to
|
|
# work somebody deliberately handed it while trust is being established, with no code
|
|
# change and no redeploy of anything but this ConfigMap. The operator's call; the default
|
|
# here honours the request as made.
|
|
#
|
|
# SET TO `agent` FOR THE FIRST RUN (2026-10-30, docs/plans/pm-agent-issue-to-pr.md
|
|
# follow-up 3). The label does not exist in the repository yet: create it in Gitea
|
|
# (Issues -> Labels -> New Label, name `agent`) before labelling a test issue.
|
|
PM_REQUIRE_LABEL: "agent"
|
|
|
|
# Dry run: the PM still reads threads, still asks the model and still posts its decision as
|
|
# an issue comment — so the operator can read exactly what it WOULD have done — but creates
|
|
# no worker Job and so changes no code. The honest way to watch this service for a day
|
|
# before letting it write anything.
|
|
#
|
|
# "true" for the first run (2026-10-30 .. 2026-10-31); dry-run triage of issue #97 was read
|
|
# and the operator approved going live. "false" since decisions/2026-10-31-pm-agent-go-live.md.
|
|
# Setting it back to "true" (plus a config-generation bump) is the gentlest stop — see
|
|
# runbooks/pm-agent.md.
|
|
PM_DRY_RUN: "false"
|
|
|
|
# --- mentions on a pull request (issue #116) --------------------------------
|
|
# OFF. Turning it on makes the dispatcher also look at PULL REQUESTS: a mention of the bot
|
|
# account in a pull request's conversation, in a review's body, or on a line inside an
|
|
# inline review thread, makes the PM read that pull request and reply where it was
|
|
# mentioned. It can ONLY reply — a mention cannot start, revise or push a branch; that is
|
|
# the second half of issue #116 and has its own issue.
|
|
#
|
|
# AN EXPLICIT MENTION IS THE ONLY TRIGGER, and a mention is self-limiting: one `@` gets one
|
|
# reply, and no other comment on the pull request is picked up. A comment that does not
|
|
# name the bot costs nothing — no reply and no model call — however recently the bot was
|
|
# mentioned or replied nearby. So the spend on this path is bounded by how often somebody
|
|
# types the handle, not by how busy the pull request is.
|
|
#
|
|
# WHY IT SHIPS OFF. Not one call on this path has been made against the live Gitea — the
|
|
# branch that wrote it held no Gitea credential and no cluster — and the cheap mention
|
|
# query it prefers needs a token scope the bot does not have today (see
|
|
# PM_PR_MENTION_DISCOVERY). The intended order is: set PM_PLAN once and read what it would
|
|
# have replied to, then set this to "true". Both are ConfigMap edits plus a
|
|
# config-generation bump.
|
|
PM_PR_MENTIONS: "false"
|
|
|
|
# How candidate pull requests are found. `auto` tries Gitea's notification list for the bot
|
|
# account first — one bounded call, which is the "way to check for '@'s for the bot account
|
|
# instead of scouring the entire pull request list" the operator asked for — and falls back
|
|
# to listing open pull requests if that is refused. `notifications` uses only the cheap
|
|
# query and does nothing if it is unavailable (it will not silently widen into the scan the
|
|
# operator rejected). `pulls` never calls the notification endpoint.
|
|
#
|
|
# EXPECT THE FALLBACK AT FIRST. Gitea puts /api/v1/notifications behind its own
|
|
# `notification` token scope, and the bot's token is minted
|
|
# `read:user, write:repository, write:issue, read:package` — so until the operator re-mints
|
|
# it with `read:notification`, the cheap query is refused and the dispatcher logs exactly
|
|
# that, naming the scope. Which query answered is logged every cycle either way.
|
|
PM_PR_MENTION_DISCOVERY: "auto"
|
|
|
|
# How far back the notification query looks. Longer costs nothing but a bigger response;
|
|
# shorter risks missing a mention the dispatcher was down for. A day is well inside the
|
|
# idempotency marker's reach, which does not expire at all.
|
|
PM_PR_NOTIFICATION_LOOKBACK_SECONDS: "86400"
|
|
|
|
# The same throttle shape as the issue path: one decision per pull request per cooldown
|
|
# window, and at most this many replies per poll.
|
|
PM_PR_COOLDOWN_SECONDS: "900"
|
|
PM_PR_MAX_REPLIES_PER_CYCLE: "1"
|
|
|
|
# How much of the change the PM is shown. The changed-file summary is always included; this
|
|
# caps the diff quoted beneath it. Set to "0" to send the file list alone — the right
|
|
# setting if the diffs here turn out to dominate the decision's token cost.
|
|
PM_PR_DIFF_MAX_CHARS: "20000"
|
|
PM_PR_MAX_CHANGED_FILES: "200"
|
|
|
|
# Plan mode for the pull-request path: discover, assemble the payload, PRINT it to the
|
|
# dispatcher's stdout, ask no model and post nothing. Setting it also enables the path, so
|
|
# it is one knob to look before leaping. PM_DRY_RUN above implies it, because on this path
|
|
# the posted reply IS the action under test, and it also carries the idempotency marker —
|
|
# posting it would make a dry run not dry.
|
|
PM_PLAN: "false"
|
|
|
|
# If the gate refuses a worker's change, the branch is NOT pushed by default and the issue
|
|
# gets the gate log instead. Set to "true" to push anyway and open a red pull request —
|
|
# useful when a human wants to see the work, noisy as a standing setting.
|
|
PM_PUSH_ON_RED_GATE: "false"
|