zerogravity/docs/extension-server-analysis.md

Extension Server Protocol — Deep Analysis

Source: strings analysis of /usr/share/antigravity/resources/app/extensions/antigravity/bin/language_server_linux_x64

---

Architecture Overview

graph TD
    subgraph "Antigravity App (Electron)"
        EXT["Extension (TypeScript)"]
        EXTSRV["Extension Server<br/>(ConnectRPC, HTTP/1.1)"]
    end

    subgraph "Language Server (Go binary)"
        LS["LanguageServerService<br/>(API Server, ConnectRPC)"]
        ESC["ExtensionServerClient<br/>(ConnectRPC client)"]
        STATESYNC["UnifiedStateSyncClient"]
        CAC["CodeAssistClient"]
    end

    subgraph "Google Cloud"
        GOOGLE["daily-cloudcode-pa.googleapis.com"]
    end

    EXT -->|"starts"| EXTSRV
    ESC -->|"HTTP/1.1<br/>application/connect+proto<br/>(ServerStream RPC)"| EXTSRV
    LS -->|"HTTPS<br/>application/connect+proto"| GOOGLE
    STATESYNC -->|"via ESC"| EXTSRV
    CAC -->|"GetOAuthToken()"| STATESYNC

    style EXTSRV fill:#f96,stroke:#333
    style STATESYNC fill:#69f,stroke:#333

Communication Paths

From → To	Protocol	Content-Type	Direction
Proxy → LS API Server	HTTP/1.1	application/json (JSON-RPC)	Unary
Proxy → LS API Server	HTTP/1.1	application/proto (protobuf)	Unary
LS → Extension Server	HTTP/1.1	application/connect+proto	Server-Streaming
LS → Google API	HTTPS/H2	application/connect+proto	Streaming

Important

ALL ExtensionServerService methods use Server-Streaming Connect RPC, even methods like GetSecretValue and LanguageServerStarted that are semantically unary. This means every response must use Connect streaming envelope framing.

---

Connect Streaming Protocol

The LS uses connect-go v1 (connectrpc.com/connect/v1). All extension server calls use ServerStream, which requires:

Request Format (LS → Stub)

POST /exa.extension_server_pb.ExtensionServerService/{Method} HTTP/1.1
Content-Type: application/connect+proto
Connect-Protocol-Version: 1

Body: raw protobuf (NOT envelope-framed for client→server in ServerStream)

Response Format (Stub → LS)

HTTP/1.1 200 OK
Content-Type: application/connect+proto

Body: sequence of envelope frames:

┌─────────┬──────────────────┬───────────────┐
│ Flags   │ Message Length    │ Message Data  │
│ (1 byte)│ (4 bytes, BE)    │ (N bytes)     │
├─────────┼──────────────────┼───────────────┤
│ 0x00    │ protobuf length  │ protobuf data │  ← data message (optional, 0 or more)
│ 0x02    │ trailer length   │ JSON trailer  │  ← end-of-stream (required, exactly 1)
└─────────┴──────────────────┴───────────────┘

Examples

Empty success (most methods):

\x02 \x00\x00\x00\x02 {}

= flag(0x02) + length(2) + trailer("{}")

Success with data (e.g., GetSecretValue):

\x00 \x00\x00\x00\x0e \x0a\x0c ya29.a0A...   ← data: protobuf response
\x02 \x00\x00\x00\x02 {}                       ← end-of-stream trailer

Error response (e.g., not found):

\x02 \x00\x00\x00\x22 {"error":{"code":"not_found"}}

Warning

Sending Content-Length: 0 with Content-Type: application/connect+proto causes unexpected EOF — the client expects at least the end-of-stream envelope.

---

Extension Server Service — Method Reference

All Methods Are ServerStream

From binary analysis, every method on ExtensionServerService is wrapped as:

*connect.ServerStreamForClient[...Response]

This includes ALL of these methods:

Method	Request Proto	Response Proto	Purpose
LanguageServerStarted	LanguageServerStartedRequest	LanguageServerStartedResponse	Init notification
GetSecretValue	GetSecretValueRequest{Key}	GetSecretValueResponse{Value}	Secret store read
StoreSecretValue	StoreSecretValueRequest{Key,Value}	StoreSecretValueResponse	Secret store write
SubscribeToUnifiedStateSyncTopic	SubscribeToUnifiedStateSyncTopicRequest	UnifiedStateSyncUpdate (stream)	Real-time state
PushUnifiedStateSyncUpdate	PushUnifiedStateSyncUpdateRequest	PushUnifiedStateSyncUpdateResponse	Push state updates
GetChromeDevtoolsMcpUrl	GetChromeDevtoolsMcpUrlRequest	GetChromeDevtoolsMcpUrlResponse	Chrome DevTools
FetchMCPAuthToken	FetchMCPAuthTokenRequest	FetchMCPAuthTokenResponse	MCP auth
AddAnnotation	AddAnnotationRequest	AddAnnotationResponse	IDE annotation
OpenFilePointer	OpenFilePointerRequest	OpenFilePointerResponse	Open file in IDE
ExecuteCommand	ExecuteCommandRequest	TerminalShellCommandStreamChunk	Run terminal cmd
...	...	...	53+ total methods

---

OAuth Token Flow

sequenceDiagram
    participant LS as Language Server
    participant ESC as ExtensionServerClient
    participant STUB as Stub Extension Server
    participant SYNC as UnifiedStateSyncClient

    Note over LS: Startup
    LS->>ESC: LanguageServerStarted()
    ESC->>STUB: POST .../LanguageServerStarted
    STUB-->>ESC: 200 OK (empty envelope)

    Note over LS: OAuth Token Request
    LS->>SYNC: GetOAuthTokenInfo()
    SYNC->>ESC: GetSecretValue({key: "oauth_token"})
    ESC->>STUB: POST .../GetSecretValue
    STUB-->>ESC: 200 OK (envelope with {value: "ya29.a0..."})
    ESC-->>SYNC: {value: "ya29.a0..."}
    SYNC-->>LS: OAuthTokenInfo{access_token: "ya29.a0..."}

    Note over LS: Using Token
    LS->>LS: Set auth_token on API requests
    LS->>LS: GetUserStatus, LoadCodeAssist, etc.

Key Insight: How the LS Gets OAuth Tokens

The call chain at server.go:558 (Failed to get OAuth token):

1. CodeAssistClient.GetOAuthToken() — entry point for getting OAuth
2. → UnifiedStateSyncClient.GetOAuthTokenInfo() — state sync layer
3. → ExtensionServerClient.GetSecretValue(key) — calls extension server
4. → Our stub must respond with the token value

Proto Structures

GetSecretValueRequest (from binary):

message GetSecretValueRequest {
  string key = 1;  // protobuf:"bytes,1,opt,name=key"
}

GetSecretValueResponse (from binary):

message GetSecretValueResponse {
  string value = 1;  // protobuf:"bytes,1,opt,name=value"
}

OAuthTokenInfo (from binary):

message OAuthTokenInfo {
  string access_token = ?;  // .GetAccessToken()
  string expiry = ?;        // .GetExpiry()
  string refresh_token = ?; // .GetRefreshToken()
  string token_type = ?;    // .GetTokenType()
}

SaveOAuthTokenInfoRequest contains:

message SaveOAuthTokenInfoRequest {
  OAuthTokenInfo token_info = 1;  // protobuf:"bytes,1,opt,name=token_info"
}

---

UnifiedStateSyncTopic

The state sync system is central to the LS's operation:

graph LR
    LSS["LS State Sync"] -->|"Subscribe"| EXT["Extension Server"]
    EXT -->|"Stream updates"| LSS
    LSS -->|"Push"| EXT

    LSS --> |"Reads"| OAuth["OAuth Token"]
    LSS --> |"Reads"| Settings["User Settings"]
    LSS --> |"Reads"| Models["Available Models"]
    LSS --> |"Reads"| Trajectories["Trajectory Summaries"]

What the LS reads via state sync:

From statesync.(*UnifiedStateSyncClient) methods:

• GetOAuthTokenInfo() — OAuth access token
• GetSecureModeEnabled() — security settings
• GetBrowserToolsEnabled() — browser tool access
• GetBrowserAllowlist() — allowed browser URLs
• GetBrowserJsExecutionPolicy() — JS execution policy
• GetTerminalAutoExecutionPolicy() — terminal auto-run policy
• GetTerminalAllowedCommands() — allowed terminal commands
• GetTerminalDeniedCommands() — denied terminal commands
• GetGcpProjectID() — GCP project binding
• GetAllowAgentAccessNonWorkspaceFiles() — file access policy
• GetAllowCascadeAccessGitignoreFiles() — gitignore policy
• GetAutoContinueOnMaxGeneratorInvocations() — auto-continue
• GetDisableCascadeAutoFixLints() — lint autofix
• GetTabGitignoreAccess() — tab-level gitignore

SubscribeToUnifiedStateSyncTopic

This is a long-lived server stream. The LS subscribes at startup and expects to receive UnifiedStateSyncUpdate messages over time. If the stub closes the connection, the LS will reconnect.

For a minimal stub, we can:

1. Accept the subscription request
2. Send an end-of-stream trailer immediately (empty data)
3. Close the connection

The LS will poll/retry, but this won't break functionality — it just means settings won't be dynamically updated (which is fine for headless mode).

---

Proxy → LS Communication

The proxy communicates with the LS API server (LanguageServerService) differently:

Method	Content-Type	Protocol
call_json() (most methods)	application/json	Unary Connect
call_proto() (protobuf methods)	application/proto	Unary Connect

Both use Connect-Protocol-Version: 1 header.

Note

The LS API server accepts unary Connect calls with application/json or application/proto. This is different from the Extension Server which expects streaming application/connect+proto.

---

What the Headless Stub Must Implement

Critical (blocks all requests):

1. GetSecretValue — Must return the OAuth token when requested

   • Request body contains key (field 1, string)
   • Response must contain value (field 1, string) = the OAuth token
   • Must use Connect streaming envelope framing

2. LanguageServerStarted — Must acknowledge startup

   • Empty success response (just end-of-stream trailer)

Important (blocks some features):

3. SubscribeToUnifiedStateSyncTopic — Settings subscription

   • Can return empty end-of-stream (no data messages)
   • LS will retry but won't crash

4. PushUnifiedStateSyncUpdate — State push

   • Can return empty success

Nice-to-have (non-blocking):

5. All other methods — return empty success
   • GetChromeDevtoolsMcpUrl, ShowAnnotation, OpenFilePointer, etc.

---

Current Stub Issues (from latest debug log)

Issue 1: "key not found"

E0215 20:05:56.311541 server.go:558] Failed to get OAuth token: key not found

The GetSecretValue response doesn't match what the LS expects. The LS calls GetSecretValue with a specific key, but our stub ignores the key and always returns the token. The "key not found" error suggests the LS's state sync layer caches by key and doesn't find the expected entry.

Root cause: The LS doesn't just call GetSecretValue — it goes through the UnifiedStateSyncClient which uses GetRow(key). The state sync is a key-value store. The LS looks up a specific key in state sync, and the state sync client calls GetSecretValue on the extension server. Since our stub returns an empty protobuf for everything except GetSecretValue, the state sync's initial SubscribeToUnifiedStateSyncTopic gets no data, and subsequent GetRow() calls return "key not found".

Issue 2: "unknown model key MODEL_PLACEHOLDER_M18"

E0215 20:05:56.358443 interceptor.go:74] SendUserCascadeMessage: unknown model key MODEL_PLACEHOLDER_M18

The model configuration isn't loaded because Cache(loadCodeAssistResponse) failed. This cache depends on userInfo which depends on the OAuth token. Fix the token flow and this should resolve.

Issue 3: "mkdir permission denied"

E0215 20:05:56.311614 log.go:380] Failed to create artifacts directory...mkdir /tmp/antigravity-standalone/.gemini/antigravity-standalone/brain/.../: permission denied

The LS tries to create directories under the gemini_dir. This is non-fatal but noisy.

---

Recommended Fix Strategy

The current approach of parsing individual methods won't scale — ALL 53+ methods are ServerStream and need envelope framing.

Better approach: Instead of understanding every method, ensure:

1. Every response uses Connect streaming envelope framing (0x02 + len + {} minimum)
2. GetSecretValue returns the token in a data envelope before the end-of-stream
3. Content-Type is always application/connect+proto
4. Connection: close to avoid HTTP keep-alive issues
5. Create the gemini_dir with proper permissions before spawning the LS