DEV Community

kongkong
kongkong

Posted on

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

#ai #github #webdev #architecture

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<string, unknown>;
  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) < Date.now()) throw new Error("expired");
  if (action.actorId !== user.id) throw new Error("actor mismatch");
  if (action.operation === "propose_patch" && !user.canWrite(action.resource)) {
    throw new Error("forbidden");
  }
}
Enter fullscreen mode Exit fullscreen mode

Resolve identity from the authenticated session, not from model output. Bind the action to a base revision so a later repository state invalidates stale approval.

Persistence boundary

Store proposed and executed states separately:

proposed -> 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

  1. Submit the same action twice: one execution occurs.
  2. Change the base revision after approval: execution is rejected.
  3. Remove the user's permission: execution is rejected.
  4. Expire the action: execution is rejected.
  5. 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.

Top comments (0)