Support bounded agents in workflow frontmatter and generated AWF configuration #50486

Problem

AWF is adding bounded agents in github/gh-aw-firewall#6908. A bounded agent runs a pinned native coding-agent engine in a single-use enclave over one immutable private-repository seed, then returns exactly one value conforming to a finite schema. The calling agent receives no repository contents, credentials, transcript, or unrestricted model output.

AWF exposes this capability only through the root boundedAgents configuration object. gh-aw cannot currently express that object in workflow frontmatter, so workflow authors must mutate awf-config.json in generated workflow steps. That workaround is appropriate for smoke tests but not a supported authoring or security boundary.

This should follow the existing tools.github.bounded-queries compiler integration introduced by #49146.

AWF documentation: https://github.com/github/gh-aw-firewall/blob/main/docs/bounded-agents.md

Proposed frontmatter

Add tools.github.bounded-agents for workflows using the AWF sandbox:

sandbox:
  agent:
    id: awf

tools:
  github:
    bounded-agents:
      private-repos:
        - repo: my-org/internal-service
          sensitivity: internal
        - repo: my-org/confidential-service
          sensitivity: confidential
      runtime: gvisor
      engine: copilot
      model: gpt-4o-mini
      timeout: 120
      memory-limit: 512m
      cpu-limit: "1"
      pids-limit: 128
      tmpfs-limit: 64m
      max-output-bytes: 8192
      max-task-bytes: 4096
      max-invocations: 8

The presence of bounded-agents should enable the subsystem. Optional fields should be omitted from generated configuration when unspecified so AWF remains the source of truth for defaults.

Initially supported author-facing values should reflect implemented AWF capabilities:

• runtime: docker or gvisor. Do not expose sbx until AWF can prove its required capabilities instead of failing closed.
• engine: copilot. AWF recognizes claude, codex, and gemini, but they intentionally fail closed until dedicated enclave images and adapters exist.
• model: required, fixed for every enclave request, and not caller-overridable.
• repository sensitivity: public, internal, confidential, or sealed.

Do not expose AWF's legacy profile, maxModelRequests, or maxModelTokens fields in the initial frontmatter. Native engines choose their API-proxy route from engine, and native Copilot does not expose enforceable request-count or per-call token controls. Presenting those fields as workflow guardrails would be misleading.

Generated AWF configuration

The example above should compile to the equivalent of:

{
  "boundedAgents": {
    "enabled": true,
    "privateRepos": [
      {
        "repo": "my-org/internal-service",
        "sensitivity": "internal"
      },
      {
        "repo": "my-org/confidential-service",
        "sensitivity": "confidential"
      }
    ],
    "runtime": "gvisor",
    "engine": "copilot",
    "model": "gpt-4o-mini",
    "timeout": 120,
    "memoryLimit": "512m",
    "cpuLimit": "1",
    "pidsLimit": 128,
    "tmpfsLimit": "64m",
    "maxOutputBytes": 8192,
    "maxTaskBytes": 4096,
    "maxInvocations": 8
  }
}

The compiler must generate this trusted configuration directly. It must not expose configuration hooks for enclave images, API endpoints, credentials, Docker sockets, mounts, network topology, API-proxy addresses, broker paths, or host staging roots.

API-proxy and authentication integration

Bounded agents require the AWF API proxy, and the enclave's only network peer is a dedicated API-proxy instance. gh-aw should:

• Ensure the selected bounded-agent engine has a supported API-proxy target and fail compilation with an actionable error when it cannot provide one.
• Reuse existing gh-aw authentication/provider configuration rather than adding credential fields under bounded-agents.
• Keep real model credentials in the API proxy; the enclave receives only fixed local endpoints and non-secret placeholders.
• Keep the private-repository staging credential host-side. It must not appear in generated AWF JSON, the primary agent environment, the enclave environment, command arguments, URLs, or logs.
• Preserve the invariant that Docker-in-Docker access is incompatible with bounded agents because primary-agent access to the enclave Docker daemon bypasses the disclosure boundary.

A workflow's primary engine and bounded-agent engine may differ. The implementation therefore needs to validate and configure the bounded-agent route independently rather than assuming the primary engine's route is sufficient.

Agent guidance

The workflow authoring/designer agents should treat bounded agents as the preferred option when a cross-repository private question requires judgment or multi-step repository inspection but still has a finite answer schema.

Guidance should distinguish:

• bounded-queries: deterministic, author-supplied Python over an immutable seed.
• bounded-agents: fixed native coding-agent loop over an immutable seed, for multi-step reading and judgment.
• unrestricted checkout/API access: required only when the desired disclosure is not finite or when source content itself must be returned.

Generated runtime instructions should tell the primary agent that configured repositories are available through the generated bounded-agent skill and that each invocation must select a configured repository and finite response schema. The caller must never select the engine, model, runtime, route, or credentials.

Validation

Compilation should reject:

• An empty private-repos list.
• Invalid or case-insensitively duplicate owner/repo slugs.
• GitHub Actions expressions or dynamic values in repository slugs or sensitivity classifications.
• Sensitivity values outside public, internal, confidential, and sealed.
• Unsupported or not-yet-implemented runtimes and engines.
• A missing or invalid model identifier.
• Invalid timeout, resource, task, output, or invocation limits.
• Bounded agents used with a non-AWF sandbox or an AWF version that does not support them.
• Configurations that enable DinD or cannot produce the required API-proxy route.

Acceptance criteria

• Frontmatter parsing, schema, editor completions, merge/import semantics, and documentation include tools.github.bounded-agents.
• Frontmatter compiles to AWF's root boundedAgents object with enabled: true.
• Optional values are omitted so AWF owns defaults.
• Only implemented runtimes and engines are authorable.
• The selected engine/model receives an independently validated API-proxy route.
• Compilation tests cover parsing, validation, shared-workflow merges, and generated AWF JSON.
• Runtime tests verify the generated bounded-agent skill is available to the primary agent.
• Authoring/designer guidance distinguishes bounded agents from bounded queries and unrestricted private-repository access.
• No staging credential, model credential, private repository content, enclave transcript, endpoint, image, mount, socket, or network detail is exposed in the generated lock file or agent environment.
• Omitting bounded-agents preserves existing behavior.

Dependency

This depends on the bounded-agent AWF implementation in github/gh-aw-firewall#6908 and should require the AWF release that contains it.