Support bounded queries in workflow frontmatter and generated AWF configuration

[lpcox]

Problem

AWF supports bounded queries through the boundedQueries section of its JSON configuration, but gh-aw does not currently expose this configuration in workflow frontmatter.

As a result, an agentic workflow cannot declaratively query approved private repositories without replacing the generated workflow or manually constructing the AWF configuration.

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

Proposed frontmatter

Add bounded-query configuration under the AWF agent sandbox:

sandbox:
  agent:
    id: awf
    bounded-queries:
      private-repos:
        - repo: my-org/public-docs
          sensitivity: public
        - repo: my-org/internal-service
          sensitivity: internal
        - repo: my-org/confidential-service
          sensitivity: confidential
        - repo: my-org/sealed-service
          sensitivity: sealed
      runtime: docker
      timeout: 30
      memory-limit: 512m
      interpreter: python3
      max-invocations: 32

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

Generated AWF configuration

The compiler should translate the frontmatter into:

{
  "boundedQueries": {
    "enabled": true,
    "privateRepos": [
      {
        "repo": "my-org/public-docs",
        "sensitivity": "public"
      },
      {
        "repo": "my-org/internal-service",
        "sensitivity": "internal"
      },
      {
        "repo": "my-org/confidential-service",
        "sensitivity": "confidential"
      },
      {
        "repo": "my-org/sealed-service",
        "sensitivity": "sealed"
      }
    ],
    "runtime": "docker",
    "timeout": 30,
    "memoryLimit": "512m",
    "interpreter": "python3",
    "maxInvocations": 32
  }
}

Authoring-agent guidance

The gh-aw workflow authoring and design agents should understand bounded queries as a first-class capability. When a requested workflow needs information from a private repository other than the repository running the workflow, bounded queries should be the preferred design.

Authoring guidance should:

• Recommend bounded queries for finite, answerable questions about private repositories in cross-repository workflows.
• Prefer bounded queries over checking out a private repository into the primary agent workspace, granting the agent a cross-repository token, or reading repository contents through an unrestricted API tool.
• Help the author select the narrowest finite result schema and an appropriate repository sensitivity.
• Explain when bounded queries are not suitable, such as source-code extraction or questions whose possible answers cannot be bounded in advance.
• Include the required sandbox.agent.bounded-queries frontmatter when generating such a workflow.

The runtime agent should also be told that the configured repositories are available through the generated bounded-query skill and that this is the expected interface for private-repository questions.

Validation

Compilation should reject:

• An empty private-repos list
• Invalid or duplicate owner/repo slugs
• Sensitivity values other than public, internal, confidential, or sealed
• Unsupported runtimes or interpreters
• Invalid timeout, memory, or invocation limits
• GitHub Actions expressions or other dynamic values in repository slugs or sensitivity classifications
• Bounded queries used with a non-AWF sandbox

Authentication requirements for staging private repositories should be documented. The staging credential must remain host-side, must not be written to the compiled workflow configuration, and must not reach the agent environment.

Acceptance criteria

• The frontmatter schema and editor completions include sandbox.agent.bounded-queries
• All four confidentiality levels are accepted
• Frontmatter compiles to AWF's boundedQueries configuration
• Omitting bounded-queries preserves existing behavior
• Optional values use AWF defaults rather than duplicating defaults in gh-aw
• Invalid repository and sensitivity configurations fail during compilation
• Compilation tests cover parsing, validation, and generated AWF JSON
• Documentation includes configuration, authentication, and a basic query example
• Workflow authoring guidance treats bounded queries as the preferred private-repository access pattern for cross-repository workflows
• Generated runtime instructions make the agent aware of the bounded-query capability
• No staging credential or private repository content is exposed in the generated lock file or agent environment