paseo/docs/ATTACHMENT_BASED_REVIEW_CONTEXT_PLAN.md

Attachment-Based Review Context Plan

Goal

Use structured attachments as the source of truth for review context during agent creation.

This covers two related behaviors:

1. Provider-facing context for the agent prompt
2. Worktree checkout behavior when creating a worktree from a review item

The design should stay compatible with future forge support such as GitLab.

Core Direction

• Do not parse the prompt to discover issue/PR intent.
• Do not introduce deeply nested transport objects for this flow.
• Make the attachment itself the discriminated union.
• Keep forge-specific checkout logic below the attachment layer.
• Let each agent provider translate attachments into its own prompt/input format.

Initial Attachment Types

Two initial structured attachment types:

• github_pr
• github_issue

With separate MIME types:

• application/github-pr
• application/github-issue

Proposed wire shape:

type AgentAttachment =
  | {
      type: "github_pr";
      mimeType: "application/github-pr";
      number: number;
      title: string;
      url: string;
      body?: string | null;
      baseRefName?: string | null;
      headRefName?: string | null;
    }
  | {
      type: "github_issue";
      mimeType: "application/github-issue";
      number: number;
      title: string;
      url: string;
      body?: string | null;
    };

Backward Compatibility

• Add new optional attachments fields; keep existing images fields.
• Unknown attachment discriminators must be dropped during schema normalization instead of failing the full request.
• Malformed attachment entries should also be ignored safely.
• Old clients continue working because attachments is optional.
• New clients can send attachments without breaking older flows that still rely on images.

Request-Level Changes

Add optional attachments to:

• create_agent_request
• send_agent_message_request

Existing initialPrompt remains plain user text.

The selected GitHub PR/issue becomes a structured attachment instead of being injected into prompt text as the primary source of truth.

App Responsibilities

When the user selects a GitHub item:

• If it is a PR, create a github_pr attachment
• If it is an issue, create a github_issue attachment
• Include the attachment in the create-agent request

The UI can still render friendly labels and previews from the same data.

The app should stop treating PR/issue context as prompt-only metadata.

Worktree Creation Behavior

During agent creation, if worktree creation is requested:

• Inspect normalized attachments
• If a github_pr attachment is present, use it to drive checkout for the worktree

The important rule:

• attachment type identifies the review object
• server-side git logic decides how to check it out

This keeps the attachment contract simple while allowing fork-safe implementation details.

Checkout Resolution

The attachment itself should not encode the full checkout strategy.

Instead, the server should resolve checkout from the github_pr attachment using forge-aware logic.

Examples of possible implementation strategies:

• gh pr checkout
• git fetch origin refs/pull/<number>/head:<local-branch>
• another GitHub-aware resolver if needed later

This is intentionally a server implementation detail, not part of the attachment schema.

Provider Responsibilities

Each provider adapter should receive normalized attachments and decide how to represent them for the model.

Examples:

• Claude: render attachment into text blocks
• Codex: inject as blocks or text
• OpenCode: send as file/resource-like input where appropriate
• ACP: convert to resource/text forms as supported

The session layer should not hardcode one translation strategy for all providers.

Suggested Implementation Order

1. Add tolerant attachment schema and normalization in shared/server message handling.
2. Thread attachments through app -> daemon client -> session layer.
3. Update create-agent UI flows to emit github_pr / github_issue attachments from GitHub selection.
4. Teach worktree creation to inspect attachments and special-case github_pr.
5. Update provider adapters to translate attachments into provider-specific prompt/input forms.
6. Optionally migrate image transport into the same attachment mechanism later.

Files Likely Involved

• packages/server/src/shared/messages.ts
• packages/server/src/client/daemon-client.ts
• packages/server/src/server/session.ts
• packages/server/src/server/worktree-session.ts
• packages/server/src/server/agent/agent-sdk-types.ts
• packages/server/src/server/agent/providers/claude-agent.ts
• packages/server/src/server/agent/providers/codex-app-server-agent.ts
• packages/server/src/server/agent/providers/opencode-agent.ts
• packages/server/src/server/agent/providers/acp-agent.ts
• packages/app/src/screens/new-workspace-screen.tsx
• packages/app/src/screens/agent/draft-agent-screen.tsx
• packages/app/src/contexts/session-context.tsx

Notes

• The current image path can remain in place initially.
• The plan intentionally keeps checkout concerns separate from provider prompt translation.
• Future forge support should add new attachment discriminators rather than expanding GitHub-only nested fields.