[copilot] output pull request

[pelikhan]

Goal

Implement a new pull-request output type in github.com/githubnext/gh-aw
This feature allows agent workflows to automatically create pull requests from the agent job’s output and generated git patch.

---

Requirements

Triggering

Add a create_pull_request job when the workflow frontmatter includes:

output:
  pull-request:
    title-prefix: "[agent] "  # optional
    labels: [automation]      # optional

⸻

Title & Body Extraction
• Use the same logic as the output.issue job to parse the agent’s output into a PR title and body.

⸻

Permissions

The create_pull_request job must request:

permissions:
contents: write
pull-requests: write

⸻

Job Steps
1. Download Patch
Retrieve the patch artifact (e.g., aw.patch) generated by the main agent job.
2. Checkout Repo
Prepare the repository workspace.
3. Create Branch
Use the naming convention / for uniqueness.
4. Apply Patch
Apply the downloaded patch to the new branch.
5. Commit & Push
Stage modified files, commit changes, and push the branch to the remote repository.
6. Open Pull Request
• Create a PR targeting the default branch.
• Title → extracted from agent output (prepend title-prefix if set).
• Body → extracted from agent output description.
• Labels → apply any configured labels.

⸻

Failure Handling
• If patch application, commit, push, or PR creation fails → fail the job.
• If no changes exist (empty or missing patch) → skip PR creation without error.

⸻

Options Parity

Support title-prefix and labels configuration, matching the existing output.issue behavior.

⸻

Implementation Plan

1. Compiler Updates
   • Detect output.pull-request in the frontmatter.
   • Inject a create_pull_request job into the compiled workflow.
   • Follow the same approach as buildCreateOutputIssueJob.

2. Patch Artifact Handling
   • Ensure the main agent job uploads aw.patch.
   • Use actions/download-artifact to fetch it in the PR job.

3. Branch Naming Strategy
   • Default: / for uniqueness.
   • Derive values using ${{ github.workflow }} and ${{ github.run_id }}.

4. PR Creation Logic
   • Prefer using the GitHub CLI:

gh pr create --title "$TITLE" --body "$BODY" --label "$LABELS"

•	Alternatively, use actions/github-script or the GitHub REST API.

⸻

Testing Plan

Unit Tests
• Ensure the compiler correctly generates a create_pull_request job.
• Validate job dependencies, permissions, and steps.

Integration Tests
• Simulate a workflow where the agent produces file changes.
• Confirm that a PR is successfully opened with correct title, body, and labels.

Edge Cases
• No patch produced → job skips gracefully.
• Patch apply fails → job fails cleanly.
• Conflict resolution is out of scope (fail job if conflict occurs).

⸻

Acceptance Criteria
• Workflows accept output.pull-request in frontmatter.
• Compiled workflow includes create_pull_request job.
• Job requests correct permissions (contents: write, pull-requests: write).
• PR is opened with correct title, body, and labels.
• Branch naming follows /.
• Properly handles no-change scenarios.
• Fails cleanly on patch or PR creation errors.
• Documentation updated to include usage instructions.

Do you also want me to generate the compiled workflow YAML example for the pull-request output? It would help developers understand how the compiler will emit the job. It can be part of the Padawan prompt for Copilot. Should I?