@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.
- package/AGENTS.md +4 -0
- package/README.md +6 -0
- package/actions/config-loader/dist/index.cjs +36 -36
- package/actions/merge-gate/dist/index.cjs +26 -26
- package/actions/run-agent/README.md +56 -10
- package/actions/run-agent/action.yml +141 -18
- package/dist/cli/index.cjs +116 -112
- package/package.json +2 -2
- package/schema/config.schema.json +4 -0
- package/skill/SKILL.md +4 -3
- package/skill/reference/node-types.md +7 -2
- package/skill/templates/foundry.config.yaml +1 -0
|
@@ -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`)
|
|
6
|
-
|
|
7
|
-
|
|
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` |
|
|
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
|
|
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
|
-
-
|
|
46
|
-
|
|
47
|
-
a
|
|
48
|
-
|
|
49
|
-
|
|
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
|
|
5
|
-
|
|
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
|
|
61
|
-
|
|
62
|
-
|
|
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
|
-
|
|
180
|
-
|
|
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
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
$
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
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"
|