Client.Start fails when CLI returns ping `timestamp` as a JSON string (PingResponse.Timestamp int64)

[lonegunmanb]

Ping/Client.Start fails when the CLI sends timestamp as a JSON string

Summary

copilot.Client.Start aborts before any RPC can be issued whenever the
connected Copilot CLI serializes the ping response's timestamp field as a
JSON string instead of a JSON number.

The Go SDK declares PingResponse.Timestamp as a hard int64:

// types.go (v0.3.0)
type PingResponse struct {
    Message         string `json:"message"`
    Timestamp       int64  `json:"timestamp"`
    ProtocolVersion *int   `json:"protocolVersion,omitempty"`
}

…and Client.Start → verifyProtocolVersion → Ping → json.Unmarshal
bubbles every unmarshal failure back to the caller verbatim, with no
compatibility shim.

In practice this means: if the CLI on a given platform returns
"timestamp":"2026-05-21T08:29:54.042Z" (ISO 8601 string), the SDK can
never start, never enumerate models, never create a session — full stop —
with this hard-to-debug error message:

json: cannot unmarshal string into Go struct field PingResponse.timestamp of type int64

I am filing a sibling issue against copilot-cli so that the wire format
gets unified across platforms (currently Windows builds emit a number,
Linux builds emit an ISO string at the same CLI version 1.0.51 — see
attached captures). However, even after the CLI is unified, the SDK should
not be one hostile string field away from refusing to start. Please add a
tolerant UnmarshalJSON on PingResponse (or change the field to a
shape-tolerant type) so that the SDK can survive both wire shapes.

Reproduction (no CLI required)

A minimal, dependency-isolated reproducer is in
tmp/sdk-repro of this gist / branch — two Go files (go.mod,
repro_test.go) totalling ~60 lines. Both payload constants below are
real captures taken via a hand-rolled JSON-RPC harness against a real
copilot --headless --stdio process; they are not synthetic.

// payloadIntTimestamp     - Windows host, copilot CLI 1.0.51-2  -> NUMBER
// payloadStringTimestamp  - Linux container, copilot CLI 1.0.51 -> STRING
const payloadStringTimestamp = `{"message":"pong","timestamp":"2026-05-21T08:29:54.042Z","protocolVersion":3}`
const payloadIntTimestamp    = `{"message":"pong","timestamp":1779352370134,"protocolVersion":3}`

func TestPingResponse_StringTimestamp_Reproduces(t *testing.T) {
    var resp copilot.PingResponse
    err := json.Unmarshal([]byte(payloadStringTimestamp), &resp)
    // err != nil; err.Error() contains:
    //   "cannot unmarshal string into Go struct field PingResponse.timestamp of type int64"
}

Inside docker.io/library/golang:latest (go1.26.3 / linux/amd64):

=== RUN   TestPingResponse_NumericTimestamp_OK
    baseline OK: {Message:pong Timestamp:1779352370134 ProtocolVersion:0x...}
--- PASS
=== RUN   TestPingResponse_StringTimestamp_Reproduces
    reproduced error: json: cannot unmarshal string into Go struct field PingResponse.timestamp of type int64
--- PASS

Note neither test requires the Copilot CLI to be installed — the bug lives
purely in the exported SDK type.

Where it bites in Client.Start

client.go (v0.3.0):

// 302: func (c *Client) Start(ctx context.Context) error
//   ...
//   329: if err := c.verifyProtocolVersion(ctx); err != nil {
//   330:     killErr := c.killProcess()
//   331:     c.state = StateError
//   332:     return errors.Join(err, killErr)
//   333: }

// 1326: func (c *Client) verifyProtocolVersion(ctx context.Context) error {
// 1328:     pingResult, err := c.Ping(ctx, "")
// 1329:     if err != nil { return err }   // <-- unmarshal error reaches here
//   ...

// 1216: func (c *Client) Ping(ctx context.Context, message string) (*PingResponse, error) {
//   ...
// 1226: var response PingResponse
// 1227: if err := json.Unmarshal(result, &response); err != nil {
// 1228:     return nil, err              // <-- error originates here
// 1229: }

There is no ClientOptions knob (e.g. SkipPingVerification,
PingResponseHook) that lets a downstream consumer bypass this code path.

Proposed fix

Any one of the following resolves the immediate breakage; the first is
preferred because it preserves the typed-int64 ergonomics for existing
callers:

Option A — tolerant UnmarshalJSON on PingResponse (recommended)

func (p *PingResponse) UnmarshalJSON(b []byte) error {
    type alias struct {
        Message         string          `json:"message"`
        Timestamp       json.RawMessage `json:"timestamp"`
        ProtocolVersion *int            `json:"protocolVersion,omitempty"`
    }
    var a alias
    if err := json.Unmarshal(b, &a); err != nil {
        return err
    }
    p.Message = a.Message
    p.ProtocolVersion = a.ProtocolVersion

    raw := bytes.TrimSpace(a.Timestamp)
    switch {
    case len(raw) == 0 || string(raw) == "null":
        // leave zero
    case raw[0] == '"':
        // String form. Support both ISO-8601 and stringified epoch ms.
        var s string
        if err := json.Unmarshal(raw, &s); err != nil {
            return err
        }
        if n, err := strconv.ParseInt(s, 10, 64); err == nil {
            p.Timestamp = n
        } else if t, err := time.Parse(time.RFC3339Nano, s); err == nil {
            p.Timestamp = t.UnixMilli()
        } else {
            return fmt.Errorf("PingResponse.timestamp: unrecognised string %q", s)
        }
    default:
        if err := json.Unmarshal(raw, &p.Timestamp); err != nil {
            return err
        }
    }
    return nil
}

Option B — change Timestamp to json.Number and add Time() /
Int64() helpers. Less invasive but pushes the parse responsibility onto
every caller and silently accepts garbage strings.

Option C — ClientOptions.SkipProtocolVerification bool as an escape
hatch for consumers stuck on broken CLI builds. Only useful in combination
with (A) or (B); on its own it defers the same crash to the first real RPC
that hits a similarly-typed field.

I'm happy to send the PR for Option A if it's the direction you want.

Environment

• SDK: github.com/github/copilot-sdk/go v0.3.0
• (Also verified still affected on v1.0.0-beta.4.)
• Reproducer: go1.26.3 linux/amd64 inside docker.io/library/golang:latest
• Observed wire payloads: see captures attached in sibling
  github/copilot-cli issue.

[lonegunmanb]

Sibling issue against the CLI side (cross-platform wire-shape divergence): github/copilot-cli#3444

[lonegunmanb]

Full reproducer source (live captures)

Both pieces below are self-contained — no need to clone anything. Drop
them into a fresh directory and run go run ./cmd/captureping on each
platform you care about.

go.mod

module sdk-repro

go 1.25

require github.com/github/copilot-sdk/go v0.3.0

(Run go mod tidy once to fill in indirect deps — google/uuid,
go.opentelemetry.io/otel, etc.)

cmd/captureping/main.go — live CLI capture, no SDK dep

This is the program that produced both wire-format samples. It does
not import the SDK; it spawns copilot --headless --stdio and writes
a hand-rolled JSON-RPC 2.0 ping frame, then dumps the raw bytes and
classifies every top-level result field as NUMBER / STRING / etc.
so Linux and Windows runs are trivially diffable.

// capture_ping.go — minimal harness that spawns `copilot --headless` (stdio
// JSON-RPC transport) and sends a hand-rolled `ping` request, then prints the
// raw response bytes verbatim so we can confirm exactly how the CLI serializes
// `timestamp`.
//
// Usage (inside the same container that exhibits the JJC error):
//   go run ./cmd/captureping [path-to-copilot]
//
// If no argument is given it falls back to `copilot` on PATH.
package main

import (
	"bufio"
	"context"
	"encoding/json"
	"fmt"
	"io"
	"os"
	"os/exec"
	"runtime"
	"strconv"
	"strings"
	"time"
)

func main() {
	cliPath := "copilot"
	if len(os.Args) > 1 {
		cliPath = os.Args[1]
	}

	// Banner: identify the host so Linux/Windows runs are trivially diffable.
	fmt.Println("=== HOST ===")
	fmt.Printf("go_os=%s go_arch=%s go_version=%s\n", runtime.GOOS, runtime.GOARCH, runtime.Version())
	if resolved, err := exec.LookPath(cliPath); err == nil {
		fmt.Printf("copilot_path=%s\n", resolved)
	} else {
		fmt.Printf("copilot_path=<not found on PATH: %s> err=%v\n", cliPath, err)
	}
	versionOut, _ := exec.Command(cliPath, "--version").CombinedOutput()
	fmt.Printf("copilot_version=%s\n", strings.TrimSpace(string(versionOut)))
	fmt.Println()

	// Same flags the Go SDK passes when running the CLI in stdio transport
	// mode (see copilot-sdk/go client.go:startCLIServer). The `--stdio` flag
	// is critical: without it the CLI defaults to TCP transport and never
	// reads from stdin, so the script appears to hang.
	cliArgs := []string{
		"--headless",
		"--no-auto-update",
		"--log-level", "debug",
		"--stdio",
	}
	fmt.Fprintf(os.Stderr, "spawning: %s %v\n", cliPath, cliArgs)
	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
	defer cancel()
	cmd := exec.CommandContext(ctx, cliPath, cliArgs...)
	stdin, err := cmd.StdinPipe()
	if err != nil {
		die("stdin pipe: %v", err)
	}
	stdout, err := cmd.StdoutPipe()
	if err != nil {
		die("stdout pipe: %v", err)
	}
	stderr, err := cmd.StderrPipe()
	if err != nil {
		die("stderr pipe: %v", err)
	}
	if err := cmd.Start(); err != nil {
		die("start %s: %v", cliPath, err)
	}
	defer cmd.Process.Kill()

	// Mirror stderr to our stderr so the operator can see CLI-side warnings
	// (package extraction, login state, debug log lines, etc.).
	go func() { _, _ = io.Copy(os.Stderr, stderr) }()

	// Give the CLI a moment to finish its self-extraction / startup banner
	// before we try the handshake. Pure cosmetic — doesn't change correctness.
	time.Sleep(500 * time.Millisecond)

	// JSON-RPC 2.0 ping request, framed with the LSP-style Content-Length header
	// that the Copilot CLI stdio transport expects (see SDK
	// internal/jsonrpc2/frame.go).
	req := map[string]any{
		"jsonrpc": "2.0",
		"id":      1,
		"method":  "ping",
		"params":  map[string]any{"message": ""},
	}
	payload, _ := json.Marshal(req)
	header := "Content-Length: " + strconv.Itoa(len(payload)) + "\r\n\r\n"
	fmt.Fprintf(os.Stderr, "writing request: %s\n", string(payload))
	if _, err := stdin.Write([]byte(header)); err != nil {
		die("write header: %v", err)
	}
	if _, err := stdin.Write(payload); err != nil {
		die("write body: %v", err)
	}

	// Read a single LSP-framed reply.
	r := bufio.NewReader(stdout)
	var contentLength int
	for {
		line, err := r.ReadString('\n')
		if err != nil {
			die("read header: %v", err)
		}
		line = trimCRLF(line)
		if line == "" {
			break
		}
		if v, ok := stripPrefix(line, "Content-Length: "); ok {
			n, perr := strconv.Atoi(v)
			if perr != nil {
				die("bad Content-Length %q: %v", v, perr)
			}
			contentLength = n
		}
	}
	if contentLength == 0 {
		die("no Content-Length header in reply")
	}
	body := make([]byte, contentLength)
	if _, err := io.ReadFull(r, body); err != nil {
		die("read body: %v", err)
	}

	fmt.Println("=== RAW RESPONSE BYTES ===")
	fmt.Println(string(body))

	// Pretty-print so the timestamp field type is obvious.
	var pretty any
	if err := json.Unmarshal(body, &pretty); err == nil {
		out, _ := json.MarshalIndent(pretty, "", "  ")
		fmt.Println("=== PARSED (generic) ===")
		fmt.Println(string(out))
	}

	// Inspect each top-level result field's JSON kind explicitly so we can
	// compare Linux vs Windows wire formats without eyeballing JSON.
	var probe struct {
		Result map[string]json.RawMessage `json:"result"`
	}
	if err := json.Unmarshal(body, &probe); err == nil {
		fmt.Println("=== RESULT FIELD KINDS ===")
		for _, k := range sortedKeys(probe.Result) {
			raw := string(probe.Result[k])
			fmt.Printf("  %-16s raw=%s kind=%s\n", k, raw, jsonKind(raw))
		}
	}

	fmt.Println("=== END ===")
}

func jsonKind(raw string) string {
	if len(raw) == 0 {
		return "EMPTY"
	}
	switch raw[0] {
	case '"':
		return "STRING"
	case '{':
		return "OBJECT"
	case '[':
		return "ARRAY"
	case 't', 'f':
		return "BOOL"
	case 'n':
		return "NULL"
	case '-', '0', '1', '2', '3', '4', '5', '6', '7', '8', '9':
		return "NUMBER"
	default:
		return "OTHER"
	}
}

func sortedKeys(m map[string]json.RawMessage) []string {
	keys := make([]string, 0, len(m))
	for k := range m {
		keys = append(keys, k)
	}
	// Lightweight insertion sort to avoid pulling in sort just for this.
	for i := 1; i < len(keys); i++ {
		for j := i; j > 0 && keys[j-1] > keys[j]; j-- {
			keys[j-1], keys[j] = keys[j], keys[j-1]
		}
	}
	return keys
}

func trimCRLF(s string) string {
	for len(s) > 0 && (s[len(s)-1] == '\n' || s[len(s)-1] == '\r') {
		s = s[:len(s)-1]
	}
	return s
}

func stripPrefix(s, prefix string) (string, bool) {
	if len(s) < len(prefix) {
		return "", false
	}
	if s[:len(prefix)] != prefix {
		return "", false
	}
	return s[len(prefix):], true
}

func die(format string, a ...any) {
	fmt.Fprintf(os.Stderr, "FATAL: "+format+"\n", a...)
	os.Exit(1)
}

repro_test.go — pure SDK-side reproducer (no CLI needed)

Drops both real captures into json.Unmarshal against the exported
copilot.PingResponse. The string-form test fails today and is the
canonical assertion for "the SDK can't accept this wire shape".

// Package repro is a minimal, dependency-isolated reproducer for the
// PingResponse.timestamp unmarshal failure observed when the Copilot Go SDK
// (github.com/github/copilot-sdk/go v0.3.0) talks to a Copilot CLI that
// emits the JSON-RPC `ping` response with `timestamp` serialized as a JSON
// string (ISO 8601) instead of a JSON number (epoch milliseconds).
//
// Both payloads below are REAL captures taken via
// cmd/captureping using the same flags the SDK uses to start
// the CLI (`--headless --no-auto-update --log-level debug --stdio`):
//
//   - payloadIntTimestamp     — Windows host, copilot CLI 1.0.51-2  → NUMBER
//   - payloadStringTimestamp  — Linux container, copilot CLI 1.0.51 → STRING
//
// Same CLI version, different platforms, different wire shapes.
package repro

import (
	"encoding/json"
	"strings"
	"testing"

	copilot "github.com/github/copilot-sdk/go"
)

const payloadStringTimestamp = `{"message":"pong","timestamp":"2026-05-21T08:29:54.042Z","protocolVersion":3}`
const payloadIntTimestamp    = `{"message":"pong","timestamp":1779352370134,"protocolVersion":3}`

func TestPingResponse_NumericTimestamp_OK(t *testing.T) {
	var resp copilot.PingResponse
	if err := json.Unmarshal([]byte(payloadIntTimestamp), &resp); err != nil {
		t.Fatalf("baseline numeric-timestamp unmarshal should succeed, got: %v", err)
	}
	if resp.Timestamp != 1779352370134 {
		t.Fatalf("Timestamp mismatch: got %d", resp.Timestamp)
	}
	t.Logf("baseline OK: %+v", resp)
}

func TestPingResponse_StringTimestamp_Reproduces(t *testing.T) {
	var resp copilot.PingResponse
	err := json.Unmarshal([]byte(payloadStringTimestamp), &resp)
	if err == nil {
		t.Fatalf("expected unmarshal to fail with the SDK's int64 Timestamp field, got nil; resp=%+v", resp)
	}
	t.Logf("reproduced error: %v", err)

	const want = "cannot unmarshal string into Go struct field PingResponse.timestamp of type int64"
	if !strings.Contains(err.Error(), want) {
		t.Fatalf("error message mismatch:\n got: %v\nwant substring: %s", err, want)
	}
}

How to run

# Pure SDK-side repro (no CLI needed; works inside golang:latest):
go test -v ./...

# Live CLI capture (run on both Windows and Linux to compare):
go run ./cmd/captureping
# or with an explicit binary:
go run ./cmd/captureping /usr/local/bin/copilot

[github-actions]

Investigation findings

Thanks for the detailed report! I investigated this and confirmed a real bug in the Go SDK, though the specifics are the inverse of what's described.

What the code actually looks like

In go/types.go, PingResponse.Timestamp is declared as time.Time, not int64:

type PingResponse struct {
    Message         string    `json:"message"`
    Timestamp       time.Time `json:"timestamp"`
    ProtocolVersion *int      `json:"protocolVersion,omitempty"`
}
```

### The actual failing scenario

Because `time.Time` uses Go's standard JSON unmarshaler (which expects an RFC 3339 string):

| CLI platform | Wire format | Unmarshal result |
|---|---|---|
| Linux CLI (`1.0.51`) | `"timestamp":"2026-05-21T08:29:54.042Z"` (ISO 8601 string) | ✅ succeeds |
| Windows CLI (`1.0.51-2`) | `"timestamp":1779352370134` (numeric epoch ms) | ❌ **fails** — `Time.UnmarshalJSON: input is not a JSON string` |

So the platforms are swapped from the issue description: the **Windows** CLI's numeric timestamp is what breaks the current SDK, while the Linux ISO 8601 string already works fine.

I verified this with a small reproducer:

```
String timestamp: err=<nil>, ts=2026-05-21 08:29:54.042 +0000 UTC
Int timestamp: err=Time.UnmarshalJSON: input is not a JSON string, ts=0001-01-01 00:00:00 +0000 UTC

Code path

The failure propagates through: Client.Start → verifyProtocolVersion (line 1428) → c.Ping (line 1446, legacy fallback) → json.Unmarshal (line 1328) → unmarshal error bubbles up, killing the client.

Conclusion

The underlying concern is valid and this is a bug: the Go SDK's PingResponse cannot handle numeric epoch-ms timestamps from the Windows CLI, causing Client.Start to abort. The proposed fix (a tolerant UnmarshalJSON on PingResponse that accepts both RFC 3339 strings and numeric epoch ms) remains the right approach. A PR for Option A from the issue would be welcome.

Generated by Bug Handler for issue #1356 · ● 414.5K · ◷