cagent-action: Instructions file for Codex

AGENTS.md

Guide for AI agents and LLMs working in this repository. Read this before exploring the codebase or proposing changes.

What this repo is

docker/cagent-action — a GitHub Action (and a family of sub-actions) that runs Docker Agent AI agents inside GitHub Actions workflows. It is published to the GitHub Marketplace and consumed by other repos as uses: docker/[email protected].

The repo ships three things:

1. Root composite action (action.yml) — downloads the docker-agent binary, optionally installs mcp-gateway, validates inputs, runs the agent securely (auth checks, prompt injection detection, secret-leak scanning), and exposes outputs.
2. review-pr/ — a higher-level composite action and reusable workflow (.github/workflows/review-pr.yml) that orchestrates a multi-agent PR review pipeline (drafter → verifier → poster) with a learning loop driven by reviewer feedback.
3. TypeScript helpers in src/ — bundled to dist/*.js and invoked by internal sub-actions (e.g., setup-credentials, security primitives, signed commits via the GitHub API).

Anything else here (workflows under .github/workflows/, scripts, tests) exists to develop, test, release, or self-test these three artifacts.

Repo layout

.
├── action.yml                       # ← Root action ("cagent Runner"). Composite. Source of truth for inputs/outputs.
├── DOCKER_AGENT_VERSION             # Pinned docker-agent version (currently v1.54.0). Read at runtime by action.yml.
├── package.json                     # pnpm workspace root. Scripts: build, test, lint, format, actionlint.
├── tsup.config.ts                   # Bundles src/<name>/index.ts → dist/<name>.js (ESM, Node 24, fully bundled).
├── tsconfig.json                    # TS config. rootDir=src, target ES2024, strict.
├── vitest.config.ts                 # Two projects: "unit" and "integration".
├── biome.json                       # Formatter + linter (Biome). 100 char width, 2 spaces, single quotes, semicolons.
│
├── src/
│   ├── add-reaction/                # Adds emoji reactions to issue/PR comments.
│   │   ├── index.ts                 # Entry → bundled to dist/add-reaction.js
│   │   └── __tests__/
│   ├── check-org-membership/        # Verifies a user belongs to a GitHub org; also resolves PR author via pulls.get.
│   │   ├── index.ts                 # Entry → bundled to dist/check-org-membership.js (standalone CLI + library).
│   │   └── __tests__/
│   ├── credentials/                 # Fetches AWS secrets via OIDC, exports PAT and AI keys.
│   │   ├── index.ts                 # Entry → bundled to dist/credentials.js
│   │   ├── ai-keys.ts
│   │   ├── aws-credentials.ts
│   │   ├── github-app.ts            # Reads docker-agent-action/github-app from Secrets Manager; exports GITHUB_APP_TOKEN (a PAT) + ORG_MEMBERSHIP_TOKEN.
│   │   └── __tests__/
│   ├── filter-diff/                 # Strips excluded-path sections from a unified diff.
│   │   ├── index.ts                 # CLI entry → bundled to dist/filter-diff.js
│   │   ├── filter-diff.ts           # Core filterDiff() pure function + applyFilter() I/O wrapper.
│   │   └── __tests__/
│   ├── score-risk/                  # Per-file risk scoring for the PR review pipeline.
│   │   ├── index.ts                 # CLI entry → bundled to dist/score-risk.js
│   │   ├── score-risk.ts            # Core scoreFiles() pure function.
│   │   └── __tests__/
│   ├── get-pr-meta/                 # Fetches PR metadata (title, body, author, base branch) used by review-pr.
│   │   ├── index.ts                 # Entry → bundled to dist/get-pr-meta.js
│   │   └── __tests__/
│   ├── mention-reply/               # Handles @docker-agent mention events: parses context, verifies org membership, builds prompt.
│   │   ├── index.ts                 # Entry → bundled to dist/mention-reply.js
│   │   └── __tests__/
│   ├── post-comment/                # Posts comments to PRs/issues.
│   │   ├── index.ts                 # Entry → bundled to dist/post-comment.js
│   │   └── __tests__/
│   ├── security/                    # Security primitives consumed by action.yml.
│   │   ├── index.ts                 # CLI dispatcher → bundled to dist/security.js.
│   │   │                            #   Subcommands: check-auth <association> <allowed-roles-json>
│   │   │                            #                sanitize-input <inputPath> <outputPath>
│   │   │                            #                sanitize-output <filePath>
│   │   ├── check-auth.ts            # author_association-based authorization.
│   │   ├── sanitize-input.ts        # Detects prompt injection patterns. Sets risk-level output.
│   │   ├── sanitize-output.ts       # Scans agent output for leaked API keys / tokens.
│   │   ├── patterns.ts              # Single source of truth for SECRET_PATTERNS, SECRET_PREFIXES, CRITICAL_PATTERNS.
│   │   └── __tests__/security.test.ts  # Vitest unit tests (replaces former test-security.sh / test-exploits.sh).
│   └── signed-commit/               # CLI tool that creates verified commits via GitHub's GraphQL API.
│       ├── index.ts                 # Entry → bundled to dist/signed-commit.js
│       ├── signed-commit.ts
│       └── __tests__/
│
├── review-pr/                       # PR-review action + agents.
│   ├── action.yml                   # Composite: orchestrates diff fetching, chunking, risk scoring, review, learning.
│   ├── README.md                    # User-facing docs for the PR review feature.
│   ├── reply/action.yml             # Sub-action: replies to feedback on review comments.
│   └── agents/
│       ├── pr-review.yaml           # Root reviewer agent (cagent YAML).
│       ├── pr-review-feedback.yaml  # Processes captured feedback into memory.
│       ├── pr-review-mention-reply.yaml  # Handles @docker-agent mention-reply responses.
│       ├── pr-review-reply.yaml     # Replies in-thread to reviewer comments.
│       ├── refs/                    # Reference docs passed to agents (posting format, code-review style).
│       └── evals/                   # cagent eval JSON files (success-*, security-*, marlin-*, etc.).
│
├── setup-credentials/               # Composite action: fetches AWS creds via OIDC, exports GITHUB_APP_TOKEN +
│   └── action.yml                   #   ORG_MEMBERSHIP_TOKEN. At root so consumers can use
│                                    #   docker/cagent-action/setup-credentials@VERSION directly.
│                                    #   Also exports CAGENT_ACTION_ROOT (repo root of the downloaded action copy)
│                                    #   for subsequent run: steps that need to invoke dist/ bundles.
│
├── .github/
│   ├── actions/
│   │   └── mention-reply/           # Internal-only JS action (node24). main = dist/mention-reply.js.
│   │       └── action.yml           #   Only used by review-pr.yml; not intended for external consumers.
│   ├── workflows/                   # CI + self-test + release workflows (see "Workflows" below).
│   └── CODEOWNERS
│
├── scripts/
│   ├── act-local.sh                 # Helper for running workflows locally with `act`.
│   └── debug-permissions.ts
│
└── tests/                           # Shell-based integration tests for action.yml bash logic.
    ├── test-job-summary.sh
    ├── test-output-extraction.sh
    ├── out.diff                      # Fixture used by test-output-extraction.sh
    └── test.diff                    # Fixture used by test-output-extraction.sh