Wrap the GitHub Copilot SDK in an Action Envelope Before It Reaches Your Application

GitHub has published github/copilot-sdk, an MIT-licensed multi-platform SDK for integrating the Copilot Agent into applications and services. Embedding an agent is not the hard part. Connecting its proposed actions to your application's permissions, persistence, and UI is. A safe full-stack path starts with an action envelope that every layer understands. The envelope type AgentAction = { actionId: string; actorId: string; operation: "read_file" | "propose_patch"; resource: string; baseRevision: string; arguments: Record; expiresAt: string; }; Enter fullscreen mode Exit fullscreen mode The model may propose this object. It does not authorize it. API boundary Validate the envelope at the server: function authorize(action: AgentAction, user: User) { if (Date.parse(action.expiresAt) validated -> approved -> executing -> succeeded \-> failed Enter fullscreen mode Exit fullscreen mode Use actionId as an idempotency key. A network retry must return the existing result instead of applying a patch twice. UI boundary Before approval, show: exact operation; resource and base revision; summarized arguments; expected side effect; expiration time. If the plan changes, create a new action ID and require new approval. Do not silently update an approved card. End-to-end failure tests Submit the same action twice: one execution occurs. Change the base revision after approval: execution is rejected. Remove the user's permission: execution is rejected. Expire the action: execution is rejected. Disconnect the browser during execution: reconnect shows authoritative state. Why an SDK seam matters Keep Copilot-specific request and response types inside one adapter. The rest of the application should depend on your AgentAction contract. That gives you a stable authorization and persistence model if the SDK, model, or provider changes. Limitations This is an integration pattern, not a claim about the SDK's internal authorization, session, or persistence behavior. I have not built a production application with the current SDK release. Check the repository's supported languages and current API before implementing the adapter. An agent SDK supplies capability. Your application still owns authority.