@thegpvc/gp-foundry 0.2.8 → 0.2.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,9 +2,14 @@
2
2
 
3
3
  The keystone action of a gp-foundry harness. It assembles a single prompt file
4
4
  from ordered fragments, then runs the [Claude Code](https://github.com/anthropics/claude-code)
5
- CLI headlessly (`claude -p`). It is deliberately **fire-and-forget**: it never
6
- fails the step, so the agent's side effects (file edits, commits, comments) are
7
- what downstream steps act on — not the CLI exit code.
5
+ CLI headlessly (`claude -p`) with the prompt on stdin, avoiding operating-system
6
+ argument-size limits.
7
+
8
+ A dead agent is **red**, not a green no-op: the CLI's exit code is propagated so
9
+ a human — or the supervisor's stranded-work sweep — notices and re-drives it.
10
+ The agent's side effects are still the product, and the generated workflows run
11
+ their fallback steps under `if: !cancelled()`, so partial work is salvaged
12
+ regardless. A transient API failure is retried in-step first (see *Failure classes*).
8
13
 
9
14
  ## Prompt assembly order
10
15
 
@@ -33,20 +38,61 @@ Rationale: the agent reads *who it is* and *what to do* before it reads the
33
38
  | `scope-path` | no | `.github/agents/scope.yaml` | Scope config file, included verbatim if it exists. |
34
39
  | `model` | yes | — | Value for `claude --model`. |
35
40
  | `allowed-tools` | yes | — | Value for `claude --allowedTools` (comma-separated). |
36
- | `claude-code-oauth-token` | yes | — | OAuth token; passed explicitly (composites have no `secrets`). |
41
+ | `claude-code-oauth-token` | one of | `""` | OAuth token (one subscription seat); passed explicitly (composites have no `secrets`). |
42
+ | `anthropic-api-key` | one of | `""` | Anthropic API key (usage-billed, no seat). Pass exactly one of the two credentials; both or neither fails the step. |
43
+ | `github-token` | no | `""` | Token for the agent's own `gh`/git calls (`GH_TOKEN`/`GITHUB_TOKEN`). |
44
+ | `comms-file` | no | `.github/agents/communication.md` | Team communication guide, included verbatim if it exists. |
37
45
  | `extra-args` | no | `""` | Extra args appended verbatim to the `claude` invocation. |
46
+ | `extra-env` | no | `""` | Newline-separated `NAME=VALUE` pairs exported before the CLI runs. |
47
+ | `max-attempts` | no | `3` | Attempts when the CLI fails *transiently*. `1` disables retrying. |
48
+ | `retry-base-delay-seconds`| no | `15` | Delay before attempt 2; doubles each attempt. |
38
49
 
39
50
  ## Behaviour
40
51
 
41
52
  - The assembled prompt is written to a temp file; the run step invokes
42
- `claude -p "$(cat <promptfile>)" --model <model> --allowedTools <allowed-tools> <extra-args>`.
53
+ `claude -p --model <model> --allowedTools <allowed-tools> <extra-args> < <promptfile>`.
43
54
  - `stderr` is captured to a file. If non-empty, it is emitted as a single
44
55
  `::warning::` group. `stdout` streams to the job log normally.
45
- - The `claude` invocation is suffixed with `|| true`, so a nonzero exit code
46
- **does not fail the step**. Detecting "no changes" and reacting is the job of
47
- a downstream fallback step, not this action.
48
- - If `role-file` is missing, or the token is empty, the step **does** fail
49
- (these are configuration errors, not agent outcomes).
56
+ - A nonzero exit **fails the step**, preserving the CLI's own exit code. PR lanes
57
+ preserve partial output through guarded fallback steps. Failed direct-commit
58
+ scheduled lanes recover output on a separate PR labeled `needs-human`; they
59
+ never push partial output to base.
60
+ - If `role-file` is missing, or the token is empty, the step fails (these are
61
+ configuration errors, not agent outcomes).
62
+
63
+ ### Failure classes
64
+
65
+ Not every nonzero exit is the agent's fault, so a failed attempt is classified
66
+ from the tail of what the CLI printed before it died:
67
+
68
+ | Class | Example | Behaviour |
69
+ |-------------|----------------------------------------------------------------|-----------|
70
+ | `transient` | `API Error: 529 Overloaded`, a dropped or refused connection | Retried up to `max-attempts`, backing off `retry-base-delay-seconds` and doubling. |
71
+ | `quota` | `You've hit your session limit · resets 9:20am (UTC)` | **Not** retried. Fails immediately with a message naming it a capacity wall. |
72
+ | `fatal` | anything else | **Not** retried. Fails with the CLI's exit code. |
73
+
74
+ A `transient` failure clears in seconds, so retrying in-step turns a server-side
75
+ blip into a delay instead of a red run that looks exactly like a broken agent —
76
+ which on a scheduled lane otherwise strands the sweep until the next cron tick.
77
+
78
+ A `quota` wall clears at a wall-clock reset routinely tens of minutes out, far
79
+ past any step budget. Retrying would only burn the runner, so it fails fast and
80
+ says what it is; the distinct message matters because a quota wall read as an
81
+ agent bug sends people to the wrong place entirely.
82
+
83
+ Retrying assumes a role can be re-run. The harness already relies on that
84
+ everywhere else — scheduled lanes re-run on cron, `agent_refire` re-fires label
85
+ lanes, the supervisor re-drives stranded work — and roles are written to read
86
+ current state (labels, existing PRs, prior comments) before acting for exactly
87
+ that reason.
88
+
89
+ A lane whose role has an **unconditional** side effect is the exception and should
90
+ set `max-attempts: 1`. From a compiled harness that is the per-node
91
+ `agent_attempts=1` attr; the Herald is the worked example, since it posts a Slack
92
+ digest with no dedup and a retry after a partial run would post it twice. Note
93
+ `agent_attempts=` is deliberately distinct from the `pr-fix` node's
94
+ `max_attempts=`, which bounds the fix↔review **loop** rather than CLI invocations
95
+ within one run.
50
96
 
51
97
  ## Example
52
98
 
@@ -1,8 +1,8 @@
1
1
  name: Run Agent
2
2
  description: >-
3
3
  Assemble a prompt file in a documented order and run the Claude Code CLI
4
- headlessly. Captures stderr, warns on any stderr output, and never fails the
5
- step (the agent's side effects are the product, not its exit code).
4
+ headlessly through stdin. Captures stderr and propagates agent failures so
5
+ workflows can recover partial work without reporting a false success.
6
6
 
7
7
  inputs:
8
8
  role-file:
@@ -57,9 +57,17 @@ inputs:
57
57
  default: ""
58
58
  claude-code-oauth-token:
59
59
  description: >-
60
- Claude Code OAuth token. Composites have no secrets context, so this must
61
- be passed in explicitly by the caller.
62
- required: true
60
+ Claude Code OAuth token — authenticates as one subscription seat. Pass
61
+ this OR `anthropic-api-key`, never both. Composites have no secrets
62
+ context, so the credential must be passed in explicitly by the caller.
63
+ required: false
64
+ default: ""
65
+ anthropic-api-key:
66
+ description: >-
67
+ Anthropic API key — usage-billed and not tied to a person's seat, the
68
+ alternative to `claude-code-oauth-token`. Pass exactly one of the two.
69
+ required: false
70
+ default: ""
63
71
  github-token:
64
72
  description: >-
65
73
  Token for the agent's own `gh`/git operations (labels, comments, PRs).
@@ -73,6 +81,21 @@ inputs:
73
81
  (passthrough for flags like --max-turns, --add-dir, etc.).
74
82
  required: false
75
83
  default: ""
84
+ max-attempts:
85
+ description: >-
86
+ How many times to run the CLI when it exits non-zero for a reason that is
87
+ not the agent's fault — an overloaded or 5xx API response, a dropped
88
+ connection. A genuine agent error is never retried, and neither is a
89
+ usage/session limit, which clears on a wall-clock schedule rather than in
90
+ seconds. Set to 1 to disable retrying.
91
+ required: false
92
+ default: "3"
93
+ retry-base-delay-seconds:
94
+ description: >-
95
+ Seconds to wait before the second attempt. Each further attempt doubles
96
+ it, so the default gives 15s and then 30s.
97
+ required: false
98
+ default: "15"
76
99
  extra-env:
77
100
  description: >-
78
101
  Optional newline-separated NAME=VALUE pairs exported into the agent's
@@ -165,6 +188,7 @@ runs:
165
188
  shell: bash
166
189
  env:
167
190
  CLAUDE_CODE_OAUTH_TOKEN: ${{ inputs.claude-code-oauth-token }}
191
+ ANTHROPIC_API_KEY: ${{ inputs.anthropic-api-key }}
168
192
  GH_TOKEN: ${{ inputs.github-token }}
169
193
  GITHUB_TOKEN: ${{ inputs.github-token }}
170
194
  PROMPT_FILE: ${{ steps.assemble.outputs.prompt-file }}
@@ -173,11 +197,24 @@ runs:
173
197
  ALLOWED_TOOLS: ${{ inputs.allowed-tools }}
174
198
  EXTRA_ARGS: ${{ inputs.extra-args }}
175
199
  EXTRA_ENV: ${{ inputs.extra-env }}
200
+ MAX_ATTEMPTS: ${{ inputs.max-attempts }}
201
+ RETRY_BASE_DELAY_SECONDS: ${{ inputs.retry-base-delay-seconds }}
176
202
  run: |
177
203
  set -uo pipefail
178
204
 
179
- if [ -z "${CLAUDE_CODE_OAUTH_TOKEN}" ]; then
180
- echo "::error::claude-code-oauth-token is empty"
205
+ # Exactly one credential. Which one the CLI prefers when it sees both is
206
+ # its business, not something a billing decision should rest on — so two
207
+ # is an error, and the unused variable is removed rather than left empty
208
+ # in the agent's environment.
209
+ if [ -n "${ANTHROPIC_API_KEY:-}" ] && [ -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ]; then
210
+ echo "::error::both anthropic-api-key and claude-code-oauth-token are set — pass exactly one"
211
+ exit 1
212
+ elif [ -n "${ANTHROPIC_API_KEY:-}" ]; then
213
+ unset CLAUDE_CODE_OAUTH_TOKEN
214
+ elif [ -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ]; then
215
+ unset ANTHROPIC_API_KEY
216
+ else
217
+ echo "::error::no agent credential: both claude-code-oauth-token and anthropic-api-key are empty"
181
218
  exit 1
182
219
  fi
183
220
 
@@ -215,24 +252,110 @@ runs:
215
252
  fi
216
253
 
217
254
  STDERR_LOG="$(mktemp)"
255
+ STDOUT_LOG="$(mktemp)"
256
+ EXIT_FILE="$(mktemp)"
257
+
258
+ # classify_failure names why an attempt died, read from the tail of what
259
+ # the CLI produced. The CLI prints its terminal error last, so a bounded
260
+ # window keeps an agent that merely *mentioned* rate limiting mid-run
261
+ # from being mistaken for one that hit it.
262
+ classify_failure() {
263
+ combined="$(tail -n 20 "$1" 2>/dev/null; tail -n 20 "$2" 2>/dev/null)"
264
+
265
+ # A usage wall clears at a wall-clock reset that is routinely tens of
266
+ # minutes out — far past any step budget — so retrying here only burns
267
+ # the runner. Terminal, but it gets its own message: this is a capacity
268
+ # problem, and reading it as a broken agent sends people to the wrong
269
+ # place. Observed shape: "You've hit your session limit · resets 9:20am (UTC)".
270
+ if printf '%s' "$combined" | grep -qiE "hit your (session|usage) limit|usage limit reached|quota exceeded"; then
271
+ printf 'quota'
272
+ return
273
+ fi
274
+
275
+ # Server-side and connection failures clear in seconds. Observed shape:
276
+ # "API Error: 529 Overloaded. This is a server-side issue, usually temporary".
277
+ if printf '%s' "$combined" | grep -qiE "api error: 5[0-9]{2}|overloaded|internal server error|bad gateway|service unavailable|gateway timeout|connection (reset|refused|closed)|econnreset|etimedout|socket hang up|network error"; then
278
+ printf 'transient'
279
+ return
280
+ fi
281
+
282
+ printf 'fatal'
283
+ }
218
284
 
219
285
  # Capture the agent's exit code instead of swallowing it: a dead agent must
220
286
  # be RED, not a green no-op — that's what lets a human (or the supervisor
221
287
  # sweep) notice and re-drive the work. Fallback steps in the generated
222
288
  # workflow run `if: !cancelled()`, so partial work is still salvaged.
223
289
  # stderr goes to a file (not streamed) so it surfaces as one grouped warning.
290
+ #
291
+ # Retrying assumes a role can be re-run, which the harness already relies
292
+ # on everywhere else: the scheduled lanes re-run on their cron, agent_refire
293
+ # re-fires label lanes, and the supervisor re-drives stranded work. Roles
294
+ # are written to read current state (labels, existing PRs, prior comments)
295
+ # before acting for exactly that reason. A consumer that has a lane where
296
+ # that does not hold can set max-attempts: 1.
224
297
  AGENT_EXIT=0
225
- # shellcheck disable=SC2086
226
- claude -p "$(cat "$PROMPT_FILE")" \
227
- --model "$MODEL" \
228
- --allowedTools "$ALLOWED_TOOLS" \
229
- $EXTRA_ARGS \
230
- 2> "$STDERR_LOG" || AGENT_EXIT=$?
231
-
232
- if [ -s "$STDERR_LOG" ]; then
233
- echo "::warning::Claude produced stderr output:"
234
- cat "$STDERR_LOG"
235
- fi
298
+ ATTEMPT=1
299
+ DELAY="${RETRY_BASE_DELAY_SECONDS:-15}"
300
+
301
+ while : ; do
302
+ : > "$STDERR_LOG"
303
+ : > "$STDOUT_LOG"
304
+
305
+ if [ "$ATTEMPT" -gt 1 ]; then
306
+ echo "::notice::run-agent: attempt ${ATTEMPT}/${MAX_ATTEMPTS}"
307
+ fi
308
+
309
+ # stdout is teed rather than redirected so a long run stays watchable
310
+ # in the live log; the exit code travels out of the subshell in a file
311
+ # because the pipeline would otherwise report tee's. `set +e` inside
312
+ # the subshell is load-bearing: the step runs under `bash -e`, which
313
+ # would otherwise abort the subshell at the failing CLI and never
314
+ # reach the echo that records the code.
315
+ # shellcheck disable=SC2086
316
+ # The prompt goes in on stdin, not argv: Linux limits each argument to
317
+ # 128 KiB and a large PR diff exceeds it.
318
+ ( set +e
319
+ claude -p \
320
+ --model "$MODEL" \
321
+ --allowedTools "$ALLOWED_TOOLS" \
322
+ $EXTRA_ARGS \
323
+ < "$PROMPT_FILE" 2> "$STDERR_LOG"
324
+ echo $? > "$EXIT_FILE" ) | tee "$STDOUT_LOG"
325
+ AGENT_EXIT="$(cat "$EXIT_FILE" 2>/dev/null || echo 1)"
326
+ [ -n "$AGENT_EXIT" ] || AGENT_EXIT=1
327
+
328
+ if [ -s "$STDERR_LOG" ]; then
329
+ echo "::warning::Claude produced stderr output:"
330
+ cat "$STDERR_LOG"
331
+ fi
332
+
333
+ if [ "$AGENT_EXIT" -eq 0 ]; then
334
+ break
335
+ fi
336
+
337
+ FAILURE_CLASS="$(classify_failure "$STDOUT_LOG" "$STDERR_LOG")"
338
+
339
+ if [ "$FAILURE_CLASS" = "quota" ]; then
340
+ echo "::error::agent hit a usage or session limit — a capacity wall, not a code failure. It clears on a wall-clock reset well past this step's budget, so the attempt is not retried; re-drive the lane after the reset."
341
+ break
342
+ fi
343
+
344
+ if [ "$FAILURE_CLASS" != "transient" ]; then
345
+ break
346
+ fi
347
+
348
+ if [ "$ATTEMPT" -ge "$MAX_ATTEMPTS" ]; then
349
+ echo "::error::agent hit a transient API failure on all ${MAX_ATTEMPTS} attempts — giving up"
350
+ break
351
+ fi
352
+
353
+ echo "::warning::run-agent: transient API failure (exit ${AGENT_EXIT}); retrying in ${DELAY}s"
354
+ sleep "$DELAY"
355
+ ATTEMPT=$((ATTEMPT + 1))
356
+ DELAY=$((DELAY * 2))
357
+ done
358
+
236
359
  if [ "$AGENT_EXIT" -ne 0 ]; then
237
360
  echo "::error::agent exited with code $AGENT_EXIT — failing the step so the run is visibly red"
238
361
  exit "$AGENT_EXIT"