Attachment spec diverges from upstream sendMessage union (:github-reference, :line-range)

[krukow]

_{Generated via Copilot on behalf of @krukow}

Attachment spec diverges from the upstream sendMessage union

Found during the GA upstream parity audit (Phase 1).

The Node.js SDK's outbound MessageOptions.attachments union
(nodejs/src/types.ts:2160-2187, tag v1.0.0-beta.12) admits exactly four shapes:

• file (path, displayName?)
• directory (path, displayName?)
• selection (filePath, displayName, selection?{start,end}, text?)
• blob (data, mimeType, displayName?)

This SDK's ::attachment spec (src/github/copilot_sdk/specs.clj:895) admits two
extras the upstream outbound union does not:

1. :github-reference — exists in the wire protocol (nodejs/src/generated/rpc.ts:6587
type: "github_reference") and in session events (session-events.ts:2298), i.e. it is
   an inbound attachment received in user.message events, not a shape you send via
   send!. The Clojure ::attachment (outbound) and ::inbound-attachment specs are
   currently identical, conflating the two directions.
2. :line-range on :file/:directory attachments — not present in the upstream
   file/directory shapes at all.

Why it matters for GA

::attachment is the outbound contract for send!. Accepting shapes the official
SDK never sends outbound risks (a) misleading users about parity and (b) emitting wire
payloads the runtime ignores. The spec is part of the public surface that freezes at GA,
so narrowing it later is a breaking change.

Proposed resolution

• Split the directions cleanly: keep :github-reference only on ::inbound-attachment
  (events), drop it from the outbound ::attachment union.
• Confirm whether :line-range on file/directory is a real CLI-supported outbound field
  (find a runtime/CLI reference) or remove it.
• Document any deliberately-retained Clojure-only extras as experimental.

Needs a CLI/runtime reference check before changing the outbound spec.

Severity: ga-nice-to-have (public spec freezes at GA; narrowing later is breaking).