Add tests and documentation for custom binary mounts in AWF sandbox

[Copilot]

The sandbox.agent.mounts field was already implemented and working across all AWF engines (Copilot, Claude, Codex), but lacked comprehensive tests and documentation.

Changes

Tests (pkg/workflow/custom_mounts_test.go)

• Engine-specific tests (Claude, Codex)
• Cross-engine consistency validation
• Common tool scenarios (database clients, cloud CLIs, build tools, shared libraries)

Documentation (docs/src/content/docs/reference/sandbox.md)

• Practical examples for common use cases
• Security considerations (read-only vs read-write)
• Mount syntax reference

Demo (.github/workflows/demo-custom-mounts.md)

• Working example with multiple tool types

Usage

Mount custom binaries and libraries into the AWF container:

sandbox:
  agent:
    id: awf
    mounts:
      # Database clients
      - "/usr/bin/psql:/usr/bin/psql:ro"
      - "/usr/lib/x86_64-linux-gnu/libpq.so.5:/usr/lib/x86_64-linux-gnu/libpq.so.5:ro"
      
      # Cloud CLIs
      - "/usr/local/bin/aws:/usr/local/bin/aws:ro"
      
      # Build tools
      - "/usr/bin/make:/usr/bin/make:ro"

Format: source:destination:mode where mode is ro (read-only) or rw (read-write).

Custom mounts are validated for syntax and applied to all AWF-wrapped engines. Mounts are sorted alphabetically in compiled workflows for consistency.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[plan] Add configuration option for custom binary and library mounts</issue_title>
<issue_description>## Objective

Allow workflow authors to specify additional binaries and libraries to mount into the agent container via frontmatter configuration.

Context

While default mounts (date, gh, yq) work for many workflows, some workflows need specialized tools:

• Database clients (psql, mysql, redis-cli)
• Cloud CLIs (aws, gcloud, azure)
• Build tools (make, cmake, gcc)
• Container tools (docker, kubectl, helm)

Workflow authors should be able to declare these dependencies explicitly.

Approach

1. Add new frontmatter field sandbox.mounts with structure:

   sandbox:
     mounts:
       binaries:
         - /usr/bin/docker
         - /usr/bin/kubectl
       libraries:
         - /usr/lib/x86_64-linux-gnu/libssl.so.3
       directories:
         - /usr/share/ca-certificates

2. Parse configuration in pkg/workflow/frontmatter_types.go
3. Validate that requested paths exist on host
4. Generate Docker mount arguments during engine execution
5. Document configuration in workflow reference docs

Files to Create/Modify

• Modify: pkg/workflow/frontmatter_types.go (add SandboxConfig.Mounts)
• Modify: pkg/parser/schemas/frontmatter_schema.json (add schema)
• Modify: pkg/workflow/copilot_engine_execution.go (apply custom mounts)
• Modify: pkg/workflow/claude_engine.go (apply custom mounts)
• Modify: pkg/workflow/codex_engine.go (apply custom mounts)
• Create: pkg/workflow/custom_mounts_test.go (test custom mounts)
• Update: docs/src/content/docs/reference/sandbox.md (document feature)

Acceptance Criteria

• Frontmatter schema supports declaring custom mounts
• Parser validates mount paths exist before workflow execution
• Custom mounts applied correctly across all engines
• Tests verify binary/library/directory mounting
• Documentation includes examples for common use cases
• Error messages helpful when requested paths don't exist

Related

Extends mounting capabilities beyond defaults defined in #11971 and #11972
Related to #11970

AI generated by Plan Command for #11970

Comments on the Issue (you are @copilot in this section)

• Fixes [plan] Add configuration option for custom binary and library mounts #12378

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[github-actions]

🔍 PR Triage Results

Category: docs | Risk: low | Priority: 37/100

Scores Breakdown

• Impact: 15/50 - Documentation/test improvement
• Urgency: 15/30 - 0 days old, 0 comments
• Quality: 7/20 - Description: good, CI: unstable

📋 Recommended Action: defer

Low impact or work in progress

Note: CI status is unstable. Please resolve CI issues before final review.

---

Triaged by PR Triage Agent on 2026-01-29

AI generated by PR Triage Agent

[github-actions]

🔍 PR Triage Results

Category: feature | Risk: high | Priority: 50/100

Scores Breakdown

• Impact: 30/50 - Tests and docs for binary mounts
• Urgency: 10/30 - 2 days old
• Quality: 10/20 - Draft status, CI pending

📋 Recommended Action: batch_review

Part of Batch #2: Feature Additions (batch-feature-001). Related to PRs #12460, #12444 for container mount functionality.

---

Triaged by PR Triage Agent on 2026-01-31 | Run #21540069309

AI generated by PR Triage Agent

[github-actions]

🔍 PR Triage Results

Category: feature | Risk: high | Priority: 60/100

Scores Breakdown

• Impact: 35/50 - Feature with high risk level
• Urgency: 10/30 - Recent PR (2 days), CI pending
• Quality: 15/20 - CI pending, Draft status

📋 Recommended Action: Batch Review

This PR is recommended for batch review with similar PRs.

📦 Batch Processing

This PR is part of batch-feature-001 with 3 other PR(s): #12130, #12460, #12698

Consider reviewing these PRs together for consistency and efficiency.

---

Triaged by PR Triage Agent on 2026-01-31 12:17 UTC
See full report: PR Triage Discussion

AI generated by PR Triage Agent