forge-agent

Runtime executor for brasalabs6/forge-actions reusable workflows.

forge-agent is the runner-side package that does the heavy work that should not live inside installable workflow stubs:

• collect GitHub event context;
• resolve agent and mode;
• render prompts;
• prepare a provider runtime;
• run Codex initially;
• validate JSON output against schemas;
• apply or plan GitHub side effects;
• report artifacts, metrics and final status to the control plane.

For live code-command jobs, forge-agent creates a branch, commits detected repository changes, pushes the branch, opens a pull request, and comments back with the resulting PR and commit.

The package is intentionally based on the original codex-runner github ... CLI pipeline. codex-runner remains the control plane and API. forge-actions owns workflows/templates. forge-agent owns execution on the GitHub Actions runner.

Canonical Documentation

• FORGE-AGENT is the detailed current compendium for the npm runtime, provider execution, GitHub modes, callback credentials, artifacts, release gates and cross-repo contracts with forge-api and forge-actions.

Usage

forge-agent run \
  --job-id "$JOB_ID" \
  --dispatch-id "$DISPATCH_ID" \
  --mode "$MODE" \
  --agent-id "$AGENT_ID" \
  --target-repository "$GITHUB_REPOSITORY" \
  --target-path "$GITHUB_WORKSPACE/target" \
  --output "$GITHUB_WORKSPACE/agent-output.json"

The smaller commands from the old CLI are still available:

forge-agent collect-context --mode issue-command --output context.json
forge-agent render-prompt --agent github-issue-command-codex --context context.json --output prompt.md
forge-agent run-agent --agent github-issue-command-codex --prompt prompt.md --output output.json --dry-run
forge-agent validate-output --output output.json --schema schemas/agent-outputs/issue-command.schema.json
forge-agent apply-output --mode issue-command --context context.json --output output.json --dry-run

Runtime Boundary

forge-agent can fetch dynamic agent config from CODEX_RUNNER_API_URL using a bearer token from FORGE_AGENT_SESSION_TOKEN, RUNTIME_CALLBACK_TOKEN or the legacy CODEX_RUNNER_API_TOKEN, in that order. Local --agents-config files are supported for development and dry-runs. Live execution should use the API-managed session token minted for one job.

For comment-driven modes (issue-command, code-command, qa-command), the runtime enforces the parsed GitHub command authorization itself. Workflows should still filter events early, but forge-agent treats untrusted comments as blocked even if a workflow calls it by mistake.

Secrets are read from the runner environment and redacted from artifacts/log payloads. The package does not install workflows or open installation PRs.

ACP is reserved in the provider interface, but not implemented yet; selecting it returns a controlled blocked result.

Validation

Use the local validation gates before release or cross-repo changes:

npm run validate
npm run validate:cross-repo
npm run validate:full

• validate: unit/contract tests plus local validate-pipeline.
• validate:cross-repo: checks runtime contract alignment with sibling forge-api and forge-actions repos.
• validate:full: runs both gates in sequence.