feat(plugin): add experimental WebSocket handshake hook (#49131)

This commit is contained in:
Aiden Cline
2026-09-15 01:41:00 -05:00
committed by GitHub
Unverified
parent 27aaa9ce0e
commit d0a902815d
12 changed files with 296 additions and 46 deletions
@@ -1257,6 +1257,26 @@ effect: (ctx) =>
}),
```
Providers that stream over a WebSocket reuse one connection per session, so the HTTP hooks never see that traffic. The
experimental `experimental.ws.handshake` hook runs once per model call before the connection is selected and exposes the
connection `url` and `headers`; changing either reopens the socket. HTTP hooks still run for any request a WebSocket
route falls back to.
```ts
effect: (ctx) =>
Effect.gen(function* () {
yield* ctx.session.hook(
"experimental.ws.handshake",
(event) =>
Effect.gen(function* () {
event.headers.authorization = `Bearer ${yield* mintToken(event.url)}`
delete event.headers["api-key"]
}),
{ providerID: "azure" },
)
}),
```
Override the retry decision for a provider failure or replace its delay in milliseconds. The hook runs after OpenCode
classifies the failure and proposes its policy, but before any retry is scheduled. It does not expose how OpenCode
internally performs the next attempt.
@@ -1389,6 +1389,29 @@ await ctx.session.hook("http.response", (event) => {
})
```
#### Native WebSocket (experimental)
Providers that stream over a WebSocket open one connection per session and reuse it across requests, so
`http.request` and `http.response` never see that traffic. The `experimental.ws.handshake` hook runs once per model
call before the connection is selected. It carries the same `sessionID`, `agent`, `model`, and `kind` as the HTTP
hooks, plus the connection `url` and `headers`. Changing `url` or `headers` changes which socket the request uses, so a
rotated bearer token reopens the connection.
HTTP hooks still run for every HTTP request, including the request a WebSocket route falls back to.
```ts
await ctx.session.hook(
"experimental.ws.handshake",
async (event) => {
event.headers.authorization = `Bearer ${await mintToken(event.url)}`
delete event.headers["api-key"]
},
{ providerID: "azure" },
)
```
This hook is experimental and its name or shape may change.
#### Retry policy
Override the retry decision for a provider failure or replace its delay in milliseconds. The hook runs after OpenCode
@@ -1434,9 +1457,19 @@ interface SessionHooks {
"model.request": SessionModelRequestHook
"http.request": SessionHttpRequestHook
"http.response": SessionHttpResponseHook
"experimental.ws.handshake": SessionWebSocketHandshakeHook
retry: SessionRetryHook
}
interface SessionWebSocketHandshakeHook {
readonly sessionID: string
readonly agent: string
readonly model: { providerID: string; id: string; variant?: string }
readonly kind: "primary" | "compaction" | "title" | "generate"
url: string
headers: Record<string, string>
}
type RetryDecision = { retry: false } | { retry: true; delay: number }
interface SessionRetryHook {