|
| 1 | +# debug |
| 2 | + |
| 3 | +Run sandbox environment diagnostics to verify the agent runtime is healthy. |
| 4 | + |
| 5 | +The debug agent is a **custom fullsend agent** — the first one built outside the built-in dispatch chain. It reuses the code agent's sandbox identity (same image, policy, host_files, coder token) but only performs diagnostics. Results are posted as a comment on the triggering issue. |
| 6 | + |
| 7 | +## Usage |
| 8 | + |
| 9 | +``` |
| 10 | +/fullsend debug <#issue> [--repo owner/name] |
| 11 | +``` |
| 12 | + |
| 13 | +This is a shortcut for `/fullsend trigger debug <#issue>`. See `trigger.md` for the full procedure. |
| 14 | + |
| 15 | +### Direct dispatch (fallback) |
| 16 | + |
| 17 | +If the `/fs-debug` slash-command dispatch fails (GITHUB_TOKEN permission issues), trigger directly: |
| 18 | + |
| 19 | +```bash |
| 20 | +gh workflow run fullsend-debug.yml --repo <owner/name> --ref main \ |
| 21 | + -f issue_key="<N>" -f issue_source="github" |
| 22 | +``` |
| 23 | + |
| 24 | +## What it checks |
| 25 | + |
| 26 | +| Group | Checks | Why it matters | |
| 27 | +|-------|--------|---------------| |
| 28 | +| Env vars | COREPACK, YARN, PROXY, NODE, GCP vars | Confirms .env.d files were sourced | |
| 29 | +| Yarn & corepack | which, version, readlink | Confirms toolchain is on PATH | |
| 30 | +| COREPACK_HOME | Set? Writable? | Must be `/tmp/corepack` (not /usr) | |
| 31 | +| Network / proxy | node fetch to npm, yarn config, gh api, curl (expect blocked) | Confirms policy + proxy work | |
| 32 | +| Node & tools | node, openspec, gh versions | Confirms image has expected tools | |
| 33 | +| Filesystem | /tmp writable, /usr not writable, whoami, disk space | Confirms sandbox isolation | |
| 34 | +| .env.d files | List files in /sandbox/workspace/.env.d/ | Confirms host_files delivery | |
| 35 | +| GCP credentials | Credential JSON + OIDC token present | Confirms auth will work | |
| 36 | + |
| 37 | +## Output |
| 38 | + |
| 39 | +The agent posts a structured summary as a comment on the triggering issue (via `post-debug.sh`). The comment is tagged with `<!-- fullsend:debug-agent -->` for identification. |
| 40 | + |
| 41 | +The full transcript is also available in the `fullsend-debug` artifact. |
| 42 | + |
| 43 | +## Architecture (template for custom agents) |
| 44 | + |
| 45 | +``` |
| 46 | +.github/workflows/ |
| 47 | + fullsend-debug-dispatch.yml ← slash-command listener (/fs-debug) |
| 48 | + fullsend-debug.yml ← standalone agent workflow |
| 49 | +
|
| 50 | +.fullsend/customized/ |
| 51 | + agents/debug.md ← agent prompt (diagnostic checks) |
| 52 | + harness/debug.yaml ← sandbox config (reuses code policy) |
| 53 | + scripts/post-debug.sh ← posts results to issue (untrusted output!) |
| 54 | +``` |
| 55 | + |
| 56 | +### Workflow steps (fullsend-debug.yml) |
| 57 | + |
| 58 | +1. Checkout repo + target-repo + upstream defaults (scaffold) |
| 59 | +2. Prepare workspace (layer scaffold defaults → customized overrides) |
| 60 | +3. Validate enrollment |
| 61 | +4. Mint coder token (same GitHub App identity as code agent) |
| 62 | +5. Setup GCP via WIF + prepare sandbox credentials |
| 63 | +6. Setup agent env (DEBUG_ prefix) |
| 64 | +7. Install fullsend CLI |
| 65 | +8. `fullsend run debug` |
| 66 | +9. Upload artifact (always) |
| 67 | + |
| 68 | +### Security: post-script and untrusted output |
| 69 | + |
| 70 | +The agent runs inside an untrusted sandbox. `post-debug.sh` treats all agent output as untrusted: |
| 71 | + |
| 72 | +- Text extracted via `jq` (no shell eval of agent strings) |
| 73 | +- Truncated to 60k chars (GitHub comment limit is 65536) |
| 74 | +- Posted via `--body-file -` (piped stdin, no shell interpolation) |
| 75 | +- `ISSUE_NUMBER` validated as numeric, `REPO_FULL_NAME` validated as `owner/repo` |
| 76 | + |
| 77 | +### Known issues |
| 78 | + |
| 79 | +- **Dispatch 401**: The `fullsend-debug-dispatch.yml` uses `GITHUB_TOKEN` for `gh workflow run`, which calls GraphQL to resolve the default branch. Some repos restrict `GITHUB_TOKEN` GraphQL access. Workaround: pass `--ref main` explicitly, or use direct `gh workflow run` from the CLI. |
| 80 | + |
| 81 | +- **Only in rhdh-agentic**: The debug agent is currently only set up in rhdh-agentic. To use in rhdh-plugins, port the four files listed above. |
| 82 | + |
| 83 | +## Building more custom agents |
| 84 | + |
| 85 | +The debug agent follows the pattern from [fullsend PR #1179](https://github.com/fullsend-ai/fullsend/pull/1179) (building-custom-agents guide). To create a new custom agent: |
| 86 | + |
| 87 | +1. **Agent prompt** (`agents/<name>.md`) — YAML frontmatter + markdown instructions |
| 88 | +2. **Harness** (`harness/<name>.yaml`) — image, policy, host_files, timeout, post_script |
| 89 | +3. **Workflow** (`.github/workflows/fullsend-<name>.yml`) — standalone, replicates workspace layering + auth |
| 90 | +4. **Dispatch** (`.github/workflows/fullsend-<name>-dispatch.yml`) — slash-command listener |
| 91 | +5. **Post-script** (optional, `scripts/post-<name>.sh`) — acts on output, treats it as untrusted |
| 92 | + |
| 93 | +No changes to `config.yaml` needed — `fullsend run` does not validate config.yaml roles for standalone workflows. |
0 commit comments