go — Go SDK

🎯 Why This Module Exists

Go dominates cloud-native tooling: Kubernetes operators, Terraform providers, CI systems, observability agents. A Go SDK unlocks embedding Copilot's agent loop into these systems without shelling out — preserving the event stream, permission flow, and tool callback ergonomics. Because Go compiles to a single static binary, a Copilot-powered operator can be deployed with kubectl apply and a pulled image, no runtime install required.

The Go SDK also showcases something the other SDKs don't: an embedded CLI pattern. Go can't trivially depend on npm packages, so internal/embeddedcli ships the CLI binary inside the SDK and extracts it on first use to a content-addressable cache directory. Concurrent processes race to extract — handled by platform-specific flock advisory locks.

🏗️ Design Decisions

Architecture

flowchart LR
  subgraph pub["public (package copilot)"]
    CL[Client
client.go]
    SE[Session
session.go]
    T[DefineTool[T,U]
definetool.go]
    PH[PermissionHandler
permissions.go]
    TY[Types
types.go]
    SF[SessionFsProvider
session_fs_provider.go]
  end
  subgraph int["internal (unexported)"]
    JR[jsonrpc2
custom transport]
    EC[embeddedcli
extraction]
    FL[flock
cross-platform]
  end
  subgraph gen["rpc (generated + hand-written)"]
    GR[generated_rpc.go
codegen]
    RU[result_union.go
hand-written]
  end
  CLIPROC[copilot subprocess]

  CL --> JR
  CL --> EC
  EC --> FL
  SE --> JR
  CL --> GR
  SE --> GR
  CL --> TY
  SE --> TY
  SE --> T
  SE --> PH
  SE --> SF
  GR --> RU
  JR -->|stdio / TCP| CLIPROC

🚶 Narrated Walkthrough

Key Components

⚡ Algorithm Spotlight

DefineTool — generic tool wrapper

Problem. Users want to write func(args GetWeatherArgs, inv ToolInvocation) (string, error) and have the SDK generate the JSON Schema, unmarshal JSON into T, and marshal U back — without manually writing schema strings.

func DefineTool[T any, U any](name, description string, handler func(T, ToolInvocation) (U, error)) Tool {
    var zero T
    schema := generateSchemaForType(reflect.TypeOf(zero))
    return Tool{
        Name:        name,
        Description: description,
        Parameters:  schema,
        Handler:     createTypedHandler(handler),
    }
}

The clever bit is that T is used twice — once by reflect.TypeOf(zero) to synthesise the schema, and once in the compiled closure createTypedHandler to unmarshal incoming JSON. The generic parameter keeps both in lockstep with compile-time checks.

flock-guarded CLI extraction

Content-addressed cache; double-checked locking; atomic rename. See installer.go. The POSIX advisory lock is automatically released on process exit — no stale-lock cleanup needed.

// Pseudocode from installer.go
target := filepath.Join(cacheDir, "cli-"+contentHash, "copilot")
if fileExists(target) { return target, nil }

lockFile, _ := os.OpenFile(target+".lock", os.O_CREATE|os.O_RDWR, 0644)
defer lockFile.Close()
flock.Lock(lockFile.Fd())
defer flock.Unlock(lockFile.Fd())

if fileExists(target) { return target, nil } // re-check under lock
// extract zip to .tmp, chmod, os.Rename to target

Start/Stop under RWMutex

startStopMux.Lock() for Start/Stop (writer), RLock() for all methods that need a live process. Many CreateSession calls can proceed concurrently; a Stop waits for them to finish before tearing down.

⚠ What Could Go Wrong

📊 Performance Profile

Zero-alloc hot path: JSON decoder reuses bufio.Reader; event dispatch iterates slice. Reflection cost: paid once per tool at DefineTool time; runtime invocations use captured closures. Goroutines: one reader per client + short-lived per-RPC; not thousands. Bundled CLI overhead: first extraction ~20-100ms (disk-bound); subsequent starts skip extraction in O(1).

Deep-Dive Highlights

Configuration Reference

Code Examples

Minimal client/session

package main

import (
    "context"
    "fmt"
    "log"
    copilot "github.com/github/copilot-sdk/go"
)

func main() {
    client := copilot.NewClient(nil)
    if err := client.Start(); err != nil { log.Fatal(err) }
    defer client.Stop()

    session, err := client.CreateSession(context.Background(), &copilot.SessionConfig{
        OnPermissionRequest: copilot.PermissionHandler.ApproveAll,
    })
    if err != nil { log.Fatal(err) }

    session.On(func(evt copilot.SessionEvent) {
        if d, ok := evt.Data.(*copilot.AssistantMessageData); ok {
            fmt.Println(d.Content)
        }
    })

    session.Send(copilot.MessageOptions{Prompt: "Hello!"})
}

Generic DefineTool

type GetWeatherParams struct {
    City string `json:"city" jsonschema:"city name"`
    Unit string `json:"unit" jsonschema:"temperature unit (celsius or fahrenheit)"`
}

tool := copilot.DefineTool("get_weather", "Get weather for a city",
    func(params GetWeatherParams, inv copilot.ToolInvocation) (string, error) {
        return fmt.Sprintf("Weather in %s: 22°%s", params.City, params.Unit), nil
    })

jsonrpc2 Request/Response types

type Request struct {
    JSONRPC string          `json:"jsonrpc"`
    ID      json.RawMessage `json:"id"`      // nil for notifications
    Method  string          `json:"method"`
    Params  json.RawMessage `json:"params"`
}

type Response struct {
    JSONRPC string          `json:"jsonrpc"`
    ID      json.RawMessage `json:"id,omitempty"`
    Result  json.RawMessage `json:"result,omitempty"`
    Error   *Error          `json:"error,omitempty"`
}

Directory Map

go/
├── client.go                    ← Client + Start/Stop/CreateSession
├── session.go                   ← Session + event pump + tool dispatch
├── types.go                     ← All public types
├── definetool.go                ← Generic DefineTool[T,U]
├── permissions.go               ← Pre-built permission handlers (13 lines)
├── session_fs_provider.go       ← FS interface + adapter
├── telemetry.go                 ← W3C Trace Context
├── sdk_protocol_version.go      ← Embedded constant
├── process_windows.go           ← Windows CTRL_BREAK signal
├── process_other.go             ← Unix SIGTERM
├── internal/
│   ├── jsonrpc2/
│   │   ├── jsonrpc2.go          ← Client, handlers
│   │   └── frame.go             ← Content-Length framing
│   ├── embeddedcli/
│   │   └── embeddedcli.go       ← Content-addressed extraction
│   ├── flock/
│   │   ├── flock.go             ← Lock interface
│   │   ├── flock_unix.go        ← POSIX advisory
│   │   ├── flock_windows.go     ← LockFileEx
│   │   └── flock_other.go       ← No-op fallback
│   └── e2e/                     ← Conformance tests
├── embeddedcli/
│   └── installer.go             ← Public installer helper
├── rpc/
│   ├── generated_rpc.go         ← Codegen'd ServerRpc
│   └── result_union.go          ← Hand-written event data union
├── cmd/bundler/main.go          ← Release-time packaging
├── samples/chat.go              ← Demo
└── go.mod