@thegpvc/gp-foundry 0.2.7 → 0.2.9

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
 
@@ -34,19 +39,59 @@ Rationale: the agent reads *who it is* and *what to do* before it reads the
34
39
  | `model` | yes | — | Value for `claude --model`. |
35
40
  | `allowed-tools` | yes | — | Value for `claude --allowedTools` (comma-separated). |
36
41
  | `claude-code-oauth-token` | yes | — | OAuth token; passed explicitly (composites have no `secrets`). |
42
+ | `github-token` | no | `""` | Token for the agent's own `gh`/git calls (`GH_TOKEN`/`GITHUB_TOKEN`). |
43
+ | `comms-file` | no | `.github/agents/communication.md` | Team communication guide, included verbatim if it exists. |
37
44
  | `extra-args` | no | `""` | Extra args appended verbatim to the `claude` invocation. |
45
+ | `extra-env` | no | `""` | Newline-separated `NAME=VALUE` pairs exported before the CLI runs. |
46
+ | `max-attempts` | no | `3` | Attempts when the CLI fails *transiently*. `1` disables retrying. |
47
+ | `retry-base-delay-seconds`| no | `15` | Delay before attempt 2; doubles each attempt. |
38
48
 
39
49
  ## Behaviour
40
50
 
41
51
  - 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>`.
52
+ `claude -p --model <model> --allowedTools <allowed-tools> <extra-args> < <promptfile>`.
43
53
  - `stderr` is captured to a file. If non-empty, it is emitted as a single
44
54
  `::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).
55
+ - A nonzero exit **fails the step**, preserving the CLI's own exit code. PR lanes
56
+ preserve partial output through guarded fallback steps. Failed direct-commit
57
+ scheduled lanes recover output on a separate PR labeled `needs-human`; they
58
+ never push partial output to base.
59
+ - If `role-file` is missing, or the token is empty, the step fails (these are
60
+ configuration errors, not agent outcomes).
61
+
62
+ ### Failure classes
63
+
64
+ Not every nonzero exit is the agent's fault, so a failed attempt is classified
65
+ from the tail of what the CLI printed before it died:
66
+
67
+ | Class | Example | Behaviour |
68
+ |-------------|----------------------------------------------------------------|-----------|
69
+ | `transient` | `API Error: 529 Overloaded`, a dropped or refused connection | Retried up to `max-attempts`, backing off `retry-base-delay-seconds` and doubling. |
70
+ | `quota` | `You've hit your session limit · resets 9:20am (UTC)` | **Not** retried. Fails immediately with a message naming it a capacity wall. |
71
+ | `fatal` | anything else | **Not** retried. Fails with the CLI's exit code. |
72
+
73
+ A `transient` failure clears in seconds, so retrying in-step turns a server-side
74
+ blip into a delay instead of a red run that looks exactly like a broken agent —
75
+ which on a scheduled lane otherwise strands the sweep until the next cron tick.
76
+
77
+ A `quota` wall clears at a wall-clock reset routinely tens of minutes out, far
78
+ past any step budget. Retrying would only burn the runner, so it fails fast and
79
+ says what it is; the distinct message matters because a quota wall read as an
80
+ agent bug sends people to the wrong place entirely.
81
+
82
+ Retrying assumes a role can be re-run. The harness already relies on that
83
+ everywhere else — scheduled lanes re-run on cron, `agent_refire` re-fires label
84
+ lanes, the supervisor re-drives stranded work — and roles are written to read
85
+ current state (labels, existing PRs, prior comments) before acting for exactly
86
+ that reason.
87
+
88
+ A lane whose role has an **unconditional** side effect is the exception and should
89
+ set `max-attempts: 1`. From a compiled harness that is the per-node
90
+ `agent_attempts=1` attr; the Herald is the worked example, since it posts a Slack
91
+ digest with no dedup and a retry after a partial run would post it twice. Note
92
+ `agent_attempts=` is deliberately distinct from the `pr-fix` node's
93
+ `max_attempts=`, which bounds the fix↔review **loop** rather than CLI invocations
94
+ within one run.
50
95
 
51
96
  ## Example
52
97
 
@@ -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:
@@ -73,6 +73,21 @@ inputs:
73
73
  (passthrough for flags like --max-turns, --add-dir, etc.).
74
74
  required: false
75
75
  default: ""
76
+ max-attempts:
77
+ description: >-
78
+ How many times to run the CLI when it exits non-zero for a reason that is
79
+ not the agent's fault — an overloaded or 5xx API response, a dropped
80
+ connection. A genuine agent error is never retried, and neither is a
81
+ usage/session limit, which clears on a wall-clock schedule rather than in
82
+ seconds. Set to 1 to disable retrying.
83
+ required: false
84
+ default: "3"
85
+ retry-base-delay-seconds:
86
+ description: >-
87
+ Seconds to wait before the second attempt. Each further attempt doubles
88
+ it, so the default gives 15s and then 30s.
89
+ required: false
90
+ default: "15"
76
91
  extra-env:
77
92
  description: >-
78
93
  Optional newline-separated NAME=VALUE pairs exported into the agent's
@@ -173,6 +188,8 @@ runs:
173
188
  ALLOWED_TOOLS: ${{ inputs.allowed-tools }}
174
189
  EXTRA_ARGS: ${{ inputs.extra-args }}
175
190
  EXTRA_ENV: ${{ inputs.extra-env }}
191
+ MAX_ATTEMPTS: ${{ inputs.max-attempts }}
192
+ RETRY_BASE_DELAY_SECONDS: ${{ inputs.retry-base-delay-seconds }}
176
193
  run: |
177
194
  set -uo pipefail
178
195
 
@@ -215,24 +232,110 @@ runs:
215
232
  fi
216
233
 
217
234
  STDERR_LOG="$(mktemp)"
235
+ STDOUT_LOG="$(mktemp)"
236
+ EXIT_FILE="$(mktemp)"
237
+
238
+ # classify_failure names why an attempt died, read from the tail of what
239
+ # the CLI produced. The CLI prints its terminal error last, so a bounded
240
+ # window keeps an agent that merely *mentioned* rate limiting mid-run
241
+ # from being mistaken for one that hit it.
242
+ classify_failure() {
243
+ combined="$(tail -n 20 "$1" 2>/dev/null; tail -n 20 "$2" 2>/dev/null)"
244
+
245
+ # A usage wall clears at a wall-clock reset that is routinely tens of
246
+ # minutes out — far past any step budget — so retrying here only burns
247
+ # the runner. Terminal, but it gets its own message: this is a capacity
248
+ # problem, and reading it as a broken agent sends people to the wrong
249
+ # place. Observed shape: "You've hit your session limit · resets 9:20am (UTC)".
250
+ if printf '%s' "$combined" | grep -qiE "hit your (session|usage) limit|usage limit reached|quota exceeded"; then
251
+ printf 'quota'
252
+ return
253
+ fi
254
+
255
+ # Server-side and connection failures clear in seconds. Observed shape:
256
+ # "API Error: 529 Overloaded. This is a server-side issue, usually temporary".
257
+ 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
258
+ printf 'transient'
259
+ return
260
+ fi
261
+
262
+ printf 'fatal'
263
+ }
218
264
 
219
265
  # Capture the agent's exit code instead of swallowing it: a dead agent must
220
266
  # be RED, not a green no-op — that's what lets a human (or the supervisor
221
267
  # sweep) notice and re-drive the work. Fallback steps in the generated
222
268
  # workflow run `if: !cancelled()`, so partial work is still salvaged.
223
269
  # stderr goes to a file (not streamed) so it surfaces as one grouped warning.
270
+ #
271
+ # Retrying assumes a role can be re-run, which the harness already relies
272
+ # on everywhere else: the scheduled lanes re-run on their cron, agent_refire
273
+ # re-fires label lanes, and the supervisor re-drives stranded work. Roles
274
+ # are written to read current state (labels, existing PRs, prior comments)
275
+ # before acting for exactly that reason. A consumer that has a lane where
276
+ # that does not hold can set max-attempts: 1.
224
277
  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
278
+ ATTEMPT=1
279
+ DELAY="${RETRY_BASE_DELAY_SECONDS:-15}"
280
+
281
+ while : ; do
282
+ : > "$STDERR_LOG"
283
+ : > "$STDOUT_LOG"
284
+
285
+ if [ "$ATTEMPT" -gt 1 ]; then
286
+ echo "::notice::run-agent: attempt ${ATTEMPT}/${MAX_ATTEMPTS}"
287
+ fi
288
+
289
+ # stdout is teed rather than redirected so a long run stays watchable
290
+ # in the live log; the exit code travels out of the subshell in a file
291
+ # because the pipeline would otherwise report tee's. `set +e` inside
292
+ # the subshell is load-bearing: the step runs under `bash -e`, which
293
+ # would otherwise abort the subshell at the failing CLI and never
294
+ # reach the echo that records the code.
295
+ # shellcheck disable=SC2086
296
+ # The prompt goes in on stdin, not argv: Linux limits each argument to
297
+ # 128 KiB and a large PR diff exceeds it.
298
+ ( set +e
299
+ claude -p \
300
+ --model "$MODEL" \
301
+ --allowedTools "$ALLOWED_TOOLS" \
302
+ $EXTRA_ARGS \
303
+ < "$PROMPT_FILE" 2> "$STDERR_LOG"
304
+ echo $? > "$EXIT_FILE" ) | tee "$STDOUT_LOG"
305
+ AGENT_EXIT="$(cat "$EXIT_FILE" 2>/dev/null || echo 1)"
306
+ [ -n "$AGENT_EXIT" ] || AGENT_EXIT=1
307
+
308
+ if [ -s "$STDERR_LOG" ]; then
309
+ echo "::warning::Claude produced stderr output:"
310
+ cat "$STDERR_LOG"
311
+ fi
312
+
313
+ if [ "$AGENT_EXIT" -eq 0 ]; then
314
+ break
315
+ fi
316
+
317
+ FAILURE_CLASS="$(classify_failure "$STDOUT_LOG" "$STDERR_LOG")"
318
+
319
+ if [ "$FAILURE_CLASS" = "quota" ]; then
320
+ 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."
321
+ break
322
+ fi
323
+
324
+ if [ "$FAILURE_CLASS" != "transient" ]; then
325
+ break
326
+ fi
327
+
328
+ if [ "$ATTEMPT" -ge "$MAX_ATTEMPTS" ]; then
329
+ echo "::error::agent hit a transient API failure on all ${MAX_ATTEMPTS} attempts — giving up"
330
+ break
331
+ fi
332
+
333
+ echo "::warning::run-agent: transient API failure (exit ${AGENT_EXIT}); retrying in ${DELAY}s"
334
+ sleep "$DELAY"
335
+ ATTEMPT=$((ATTEMPT + 1))
336
+ DELAY=$((DELAY * 2))
337
+ done
338
+
236
339
  if [ "$AGENT_EXIT" -ne 0 ]; then
237
340
  echo "::error::agent exited with code $AGENT_EXIT — failing the step so the run is visibly red"
238
341
  exit "$AGENT_EXIT"