From f77940167ccb8d576ff2685a5757acccd4783b4e Mon Sep 17 00:00:00 2001 From: Aiden Cline Date: Sun, 8 Nov 2026 22:28:44 -0600 Subject: [PATCH 1/7] feat(plugin): add experimental model HTTP hooks --- packages/core/src/generate.ts | 28 +++++--- packages/core/src/model-http.ts | 68 +++++++++++++++++++ packages/core/src/plugin/hooks.ts | 3 + packages/core/src/plugin/host.ts | 1 + packages/core/src/session/model-request.ts | 37 +--------- packages/core/test/generate.test.ts | 8 ++- packages/core/test/plugin/host.ts | 2 + packages/plugin/src/effect/model.ts | 39 ++++++++++- packages/plugin/src/promise/adapter.ts | 4 ++ packages/plugin/src/promise/model.ts | 39 ++++++++++- .../src/docs/content/build/plugins/server.mdx | 45 ++++++++++++ 11 files changed, 227 insertions(+), 47 deletions(-) create mode 100644 packages/core/src/model-http.ts diff --git a/packages/core/src/generate.ts b/packages/core/src/generate.ts index a28ab6b32646..7b388ed88d32 100644 --- a/packages/core/src/generate.ts +++ b/packages/core/src/generate.ts @@ -5,13 +5,15 @@ import type { DecisionRequest, DecisionResult, ImageRequest, ImageResult } from import { Money } from "@opencode/schema/money" import { SessionID } from "@opencode/schema/session-id" import { Context, Effect, Layer, Schema } from "effect" -import { RequestExecutor } from "@opencode/ai/route" +import { RequestExecutor, type HttpMiddleware } from "@opencode/ai/route" import { makeLocationNode } from "@opencode/util/effect/app-node" import { llmClient, requestExecutor } from "./effect/app-node-platform.js" import { Integration } from "./integration.js" import { ModelResolver } from "./model-resolver.js" import { Model } from "./model.js" +import { ModelHttp } from "./model-http.js" import { ModelRetry } from "./model-retry.js" +import { PluginHooks } from "./plugin/hooks.js" export interface TextInput { readonly prompt: string @@ -78,7 +80,6 @@ export interface Interface { export class Service extends Context.Service()("@opencode/Generate") {} -// Image and decision clients are built here, on the shared request executor, so only Generate depends on them. export const layer = Layer.effect( Service, Effect.gen(function* () { @@ -86,8 +87,15 @@ export const layer = Layer.effect( const resolver = yield* ModelResolver.Service const models = yield* Model.Service const executor = yield* RequestExecutor.Service - const images = yield* ImageClient.Service - const decisionClient = yield* DecisionClient.Service + const hooks = yield* PluginHooks.Service + // Image and decision clients are built per call so the model HTTP hooks wrap every provider request they make. + const clients = (http: HttpMiddleware | undefined) => + Layer.provide( + Layer.merge(ImageClient.layer, DecisionClient.layer), + http === undefined + ? Layer.succeed(RequestExecutor.Service, executor) + : RequestExecutor.middleware(http, Layer.succeed(RequestExecutor.Service, executor)), + ) const runText = Effect.fn("Generate.text")(function* (input: TextInput) { const resolved = yield* resolver.resolve(input.model).pipe( @@ -111,6 +119,7 @@ export const layer = Layer.effect( if (!resolved && input.model) return yield* missing(input.model, "chat") if (!resolved) return yield* new UnavailableError({ message: "No model specified and no supported model is available" }) + const http = yield* ModelHttp.middleware(hooks, { model: resolved.ref, kind: "text" }) const response = yield* llm .generate( ai.request({ @@ -119,6 +128,7 @@ export const layer = Layer.effect( // Gateways require session attribution even for a stateless call; no Session is stored. headers: { "x-opencode-session": SessionID.create() }, }), + http === undefined ? undefined : { http }, ) .pipe( ModelRetry.retryOneShot, @@ -151,6 +161,7 @@ export const layer = Layer.effect( .resolveImage(input.model) .pipe(Effect.mapError((error) => resolutionError(input.model, "image", error))) if (!model) return yield* missing(input.model, "image") + const http = yield* ModelHttp.middleware(hooks, { model: input.model, kind: "image" }) // `ai.image.generate` turns an invalid request into a typed error; building it with `ai.image.request` would throw. const response = yield* ai.image.generate({ model, @@ -160,7 +171,7 @@ export const layer = Layer.effect( aspect: input.aspect, resolution: input.resolution, }).pipe( - Effect.provideService(ImageClient.Service, images), + Effect.provide(clients(http)), ModelRetry.retryOneShot, Effect.mapError((error) => providerError(input.model, error)), ) @@ -190,6 +201,7 @@ export const layer = Layer.effect( .resolveDecision(input.model) .pipe(Effect.mapError((error) => resolutionError(input.model, "decision", error))) if (!model) return yield* missing(input.model, "decision") + const http = yield* ModelHttp.middleware(hooks, { model: input.model, kind: "decision" }) const response = yield* ai.decision.generate({ model, input: input.input.map((part) => @@ -199,7 +211,7 @@ export const layer = Layer.effect( ), questions: input.questions, }).pipe( - Effect.provideService(DecisionClient.Service, decisionClient), + Effect.provide(clients(http)), ModelRetry.retryOneShot, Effect.mapError((error) => providerError(input.model, error)), ) @@ -228,7 +240,7 @@ export const layer = Layer.effect( decisions: (input) => credentials(decisions(input)), }) }), -).pipe(Layer.provide([ImageClient.layer, DecisionClient.layer])) +) // Provider metadata may hold undefined fields, which the JSON response schema rejects. function plainJson(value: Record): Record { @@ -277,5 +289,5 @@ function failureReason(tag: AIError["reason"]["_tag"], status: number | undefine export const node = makeLocationNode({ service: Service, layer, - deps: [ModelResolver.node, Model.node, llmClient, requestExecutor], + deps: [ModelResolver.node, Model.node, PluginHooks.node, llmClient, requestExecutor], }) diff --git a/packages/core/src/model-http.ts b/packages/core/src/model-http.ts new file mode 100644 index 000000000000..c073701b9b90 --- /dev/null +++ b/packages/core/src/model-http.ts @@ -0,0 +1,68 @@ +export * as ModelHttp from "./model-http.js" + +import type { HttpMiddleware } from "@opencode/ai/route" +import type { SessionRequestKind } from "@opencode/plugin/effect/session" +import type { Agent } from "@opencode/schema/agent" +import type { Model } from "@opencode/schema/model" +import type { Session } from "@opencode/schema/session" +import { Effect, Stream } from "effect" +import { HttpClientRequest, HttpClientResponse } from "effect/http" +import type { PluginHooks } from "./plugin/hooks.js" + +export type Scope = { readonly model: Model.Ref } & ( + | { readonly kind: SessionRequestKind; readonly sessionID: Session.ID; readonly agent: Agent.ID } + | { readonly kind: "text" | "image" | "decision" } +) + +/** + * Per-call middleware that runs the model `experimental.http.*` hooks, and the session `http.*` hooks when a Session + * makes the request. Model hooks wrap session hooks. Undefined when no hook applies. + */ +export const middleware = Effect.fnUntraced(function* (hooks: PluginHooks.Interface, scope: Scope) { + const providerID = scope.model.providerID + const session = "sessionID" in scope ? scope : undefined + const any = [ + yield* hooks.has("model", "experimental.http.request", providerID), + yield* hooks.has("model", "experimental.http.response", providerID), + session !== undefined && (yield* hooks.has("session", "http.request", providerID)), + session !== undefined && (yield* hooks.has("session", "http.response", providerID)), + ].some(Boolean) + if (!any) return undefined + const http: HttpMiddleware = (req, handler) => + Effect.gen(function* () { + const request = yield* HttpClientRequest.toWeb(req) + const outer = yield* hooks.trigger("model", "experimental.http.request", { ...scope, request }) + const before = + session === undefined + ? outer + : yield* hooks.trigger("session", "http.request", { ...session, request: outer.request }) + // A hook that kept the request object cannot have replaced its body, so the original body is sent as is. + // Reading it back would hold a second full copy of the request, screenshots included, for the whole call. + const sent = + before.request === request + ? HttpClientRequest.setBody(HttpClientRequest.fromWeb(request), req.body) + : before.request.body + ? HttpClientRequest.bodyUint8Array( + HttpClientRequest.fromWeb(before.request), + new Uint8Array(yield* Effect.promise(() => before.request.clone().arrayBuffer())), + before.request.headers.get("content-type") ?? undefined, + ) + : HttpClientRequest.fromWeb(before.request) + const res = yield* handler(sent) + const response = new Response( + [204, 205, 304].includes(res.status) ? null : yield* Stream.toReadableStreamEffect(res.stream), + { status: res.status, headers: res.headers }, + ) + const inner = + session === undefined + ? { response } + : yield* hooks.trigger("session", "http.response", { ...session, request: before.request, response }) + const after = yield* hooks.trigger("model", "experimental.http.response", { + ...scope, + request: before.request, + response: inner.response, + }) + return HttpClientResponse.fromWeb(sent, after.response) + }) + return http +}) diff --git a/packages/core/src/plugin/hooks.ts b/packages/core/src/plugin/hooks.ts index 1325837f9d58..783aefdadb3f 100644 --- a/packages/core/src/plugin/hooks.ts +++ b/packages/core/src/plugin/hooks.ts @@ -1,6 +1,7 @@ export * as PluginHooks from "./hooks.js" import type { AISDKHooks } from "@opencode/plugin/effect/aisdk" +import type { ModelRequestHooks } from "@opencode/plugin/effect/model" import type { SessionHooks } from "@opencode/plugin/effect/session" import type { ShellHooks } from "@opencode/plugin/effect/shell" import type { ToolFailures, ToolHooks } from "@opencode/plugin/effect/tool" @@ -12,6 +13,7 @@ import { State } from "../state.js" export interface Domains { readonly aisdk: AISDKHooks + readonly model: ModelRequestHooks readonly session: SessionHooks readonly permission: PermissionHooks readonly shell: ShellHooks @@ -23,6 +25,7 @@ type NoFailures = { readonly [Name in keyof Spec]: never } // Failure channel for each hook event. Only tool execute.before may fail: a Tool.Error rejects the call before it runs. interface Failures extends Record { readonly aisdk: NoFailures + readonly model: NoFailures readonly session: NoFailures readonly permission: NoFailures readonly shell: NoFailures diff --git a/packages/core/src/plugin/host.ts b/packages/core/src/plugin/host.ts index 19a163d9aee0..d34b5b698c2b 100644 --- a/packages/core/src/plugin/host.ts +++ b/packages/core/src/plugin/host.ts @@ -235,6 +235,7 @@ export const make = Effect.fn("PluginHost.make")(function* (plugin: Pick hooks.register("model", name, callback, options), list: (input) => response(models.available(input?.types)), default: () => response(models.default()), reload: models.reload, diff --git a/packages/core/src/session/model-request.ts b/packages/core/src/session/model-request.ts index 012888179324..d4e03f9a82a1 100644 --- a/packages/core/src/session/model-request.ts +++ b/packages/core/src/session/model-request.ts @@ -29,10 +29,10 @@ import type { import type { Agent } from "@opencode/schema/agent" import type { Model } from "@opencode/schema/model" import type { Content } from "@opencode/schema/tool" -import { Cause, Context, Effect, Layer, Result, Stream } from "effect" -import { HttpClientRequest, HttpClientResponse } from "effect/http" +import { Cause, Context, Effect, Layer, Result } from "effect" import { makeLocationNode } from "@opencode/util/effect/app-node" import { App } from "../app.js" +import { ModelHttp } from "../model-http.js" import { Instructions } from "../instructions/index.js" import { Permission } from "../permission.js" import { PluginHooks } from "../plugin/hooks.js" @@ -349,38 +349,7 @@ export const layer = Layer.effect( model: route === base.model.route ? base.model : LanguageModel.update(base.model, { route }), headers: Object.keys(modelHook.headers).length === 0 ? undefined : modelHook.headers, } - const hasHttpHooks = - (yield* hooks.has("session", "http.request", model.ref.providerID)) || - (yield* hooks.has("session", "http.response", model.ref.providerID)) - const http: StreamOptions["http"] = hasHttpHooks - ? (req, handler) => - Effect.gen(function* () { - const request = yield* HttpClientRequest.toWeb(req) - const before = yield* hooks.trigger("session", "http.request", { ...scope, request }) - // A hook that kept the request object cannot have replaced its body, so the original body is sent as is. - // Reading it back would hold a second full copy of the request, screenshots included, for the whole call. - const sent = - before.request === request - ? HttpClientRequest.setBody(HttpClientRequest.fromWeb(request), req.body) - : before.request.body - ? HttpClientRequest.bodyUint8Array( - HttpClientRequest.fromWeb(before.request), - new Uint8Array(yield* Effect.promise(() => before.request.clone().arrayBuffer())), - before.request.headers.get("content-type") ?? undefined, - ) - : HttpClientRequest.fromWeb(before.request) - const res = yield* handler(sent) - const after = yield* hooks.trigger("session", "http.response", { - ...scope, - request: before.request, - response: new Response( - [204, 205, 304].includes(res.status) ? null : yield* Stream.toReadableStreamEffect(res.stream), - { status: res.status, headers: res.headers }, - ), - }) - return HttpClientResponse.fromWeb(sent, after.response) - }) - : undefined + const http = yield* ModelHttp.middleware(hooks, scope) // HTTP hooks wrap every HTTP request, including the WebSocket fallback path. The route decides // which transport actually carries the request, so both hook families are always offered. const webSocket = diff --git a/packages/core/test/generate.test.ts b/packages/core/test/generate.test.ts index 005240b4c66a..73e8ff5e27c4 100644 --- a/packages/core/test/generate.test.ts +++ b/packages/core/test/generate.test.ts @@ -21,6 +21,7 @@ import { Integration } from "@opencode/core/integration" import { IntegrationConnection } from "@opencode/core/integration/connection" import { ModelResolver } from "@opencode/core/model-resolver" import { ModelsDev } from "@opencode/core/models-dev" +import { PluginHooks } from "@opencode/core/plugin/hooks" import { ID, Info, Model, Ref, VariantID } from "@opencode/core/model" import { Provider } from "@opencode/core/provider" import { Variant } from "@opencode/core/variant" @@ -82,7 +83,8 @@ const aisdk = Layer.mock(AISDK.Service, { const client = TestLLM.testLayer({ fallback: TestLLM.text("OK", "generate") }) const resolver = ModelResolver.layer.pipe(Layer.provide(Layer.mergeAll(providers, models, integrations, npm, aisdk))) -const generateDeps = Layer.mergeAll(models, RequestExecutor.fetchLayer) +const hooks = Layer.mock(PluginHooks.Service, { has: () => Effect.succeed(false) }) +const generateDeps = Layer.mergeAll(models, hooks, RequestExecutor.fetchLayer) const it = testEffect(Generate.layer.pipe(Layer.provide(Layer.mergeAll(resolver, client, generateDeps)))) const resolverIt = testEffect(resolver) const retryIt = testEffect( @@ -268,7 +270,7 @@ testEffect(Layer.empty).effect("attributes each stateless completion without cre }), ).toBe("OK") } - }).pipe(Effect.provide(Generate.layer.pipe(Layer.provide(Layer.mergeAll(resolver, native, models, executor))))) + }).pipe(Effect.provide(Generate.layer.pipe(Layer.provide(Layer.mergeAll(resolver, native, models, hooks, executor))))) expect(sessions).toHaveLength(2) expect(sessions[0]).toStartWith("ses_") expect(sessions[1]).not.toBe(sessions[0]) @@ -420,7 +422,7 @@ describe("image and decision generation", () => { Layer.provide(Layer.mergeAll(mediaProviders, mediaModels, mediaIntegrations, npm, aisdk)), ) const mediaIt = testEffect( - Generate.layer.pipe(Layer.provide(Layer.mergeAll(mediaResolver, client, mediaModels, executor))), + Generate.layer.pipe(Layer.provide(Layer.mergeAll(mediaResolver, client, mediaModels, hooks, executor))), ) const ref = (providerID: string, id: string, variant?: string) => Ref.make({ diff --git a/packages/core/test/plugin/host.ts b/packages/core/test/plugin/host.ts index bc436ab7d249..3ddc8947a9c1 100644 --- a/packages/core/test/plugin/host.ts +++ b/packages/core/test/plugin/host.ts @@ -54,6 +54,7 @@ export function host(overrides: Overrides = {}): Plugin.Context { reload: () => Effect.die("unused provider.reload"), }, model: overrides.model ?? { + hook: () => Effect.die("unused model.hook"), list: () => Effect.die("unused model.list"), default: () => Effect.die("unused model.default"), transform: () => Effect.die("unused model.transform"), @@ -291,6 +292,7 @@ export const noProviders: Plugin.Context["provider"] = { export function modelHost(models: Model.Interface): Plugin.Context["model"] { return { + hook: () => Effect.die("unused model.hook"), list: () => models.available().pipe(Effect.map(located)), default: () => models.default().pipe(Effect.map(located)), reload: models.reload, diff --git a/packages/plugin/src/effect/model.ts b/packages/plugin/src/effect/model.ts index 6d027f0ac565..65acda755bd9 100644 --- a/packages/plugin/src/effect/model.ts +++ b/packages/plugin/src/effect/model.ts @@ -1,8 +1,10 @@ import type { ModelApi } from "@opencode/client/effect/api" +import type { Agent } from "@opencode/schema/agent" import type { Model } from "@opencode/schema/model" +import type { Session } from "@opencode/schema/session" import type { Effect, Types } from "effect" import type { ProviderRecord } from "./provider.js" -import type { Transform } from "./registration.js" +import type { ModelHooks, Transform } from "./registration.js" export interface ModelEditor { /** Candidates from available providers, including models disabled by earlier transforms. */ @@ -22,7 +24,42 @@ export interface ModelEditor { } } +/** + * Why a model request is being made. Session requests use `primary`, `compaction`, `title` and `generate`; the + * stateless generate API uses `text`, `image` and `decision`. Experimental. + */ +export type ModelRequestKind = "primary" | "compaction" | "title" | "generate" | "text" | "image" | "decision" + +/** Who is making a model request. `sessionID` and `agent` are set only when a Session makes it. Experimental. */ +export interface ModelRequestScope { + readonly model: Model.Ref + readonly kind: ModelRequestKind + readonly sessionID?: Session.ID + readonly agent?: Agent.ID +} + +/** An HTTP request to a model provider, before it is sent. Replace `request` to change it. Experimental. */ +export interface ModelHttpRequest extends ModelRequestScope { + request: Request +} + +/** The provider's HTTP response to `request`. Replace `response` to change what the model client reads. Experimental. */ +export interface ModelHttpResponse extends ModelRequestScope { + readonly request: Request + response: Response +} + +/** + * Hooks on every model request, whichever Session or API makes it: Session steps, compaction and titles, and + * `generate` text, image and decision calls. + */ +export interface ModelRequestHooks { + readonly "experimental.http.request": ModelHttpRequest + readonly "experimental.http.response": ModelHttpResponse +} + export interface ModelDomain extends ModelApi { + readonly hook: ModelHooks readonly transform: Transform readonly reload: () => Effect.Effect } diff --git a/packages/plugin/src/promise/adapter.ts b/packages/plugin/src/promise/adapter.ts index 62387459a660..e9c7ea2cb21f 100644 --- a/packages/plugin/src/promise/adapter.ts +++ b/packages/plugin/src/promise/adapter.ts @@ -377,6 +377,10 @@ export function fromPromise(plugin: Plugin) { text: adaptApiMethod(GenerateEndpoints["generate.text"], host.generate.text), }, model: { + hook: (name, callback, options) => + register( + host.model.hook(name, (event) => Effect.promise(() => Promise.resolve(callback(event))), options), + ), list: adaptApiMethod(ModelEndpoints["model.list"], host.model.list), default: adaptApiMethod(ModelEndpoints["model.default"], host.model.default), transform: transform(host.model), diff --git a/packages/plugin/src/promise/model.ts b/packages/plugin/src/promise/model.ts index f566277cbfd7..8d4715c4608e 100644 --- a/packages/plugin/src/promise/model.ts +++ b/packages/plugin/src/promise/model.ts @@ -1,8 +1,10 @@ import type { ModelApi } from "@opencode/client/promise/api" +import type { Agent } from "@opencode/schema/agent" import type { Model } from "@opencode/schema/model" +import type { Session } from "@opencode/schema/session" import type { Types } from "effect" import type { ProviderRecord } from "./provider.js" -import type { Transform } from "./registration.js" +import type { ModelHooks, Transform } from "./registration.js" export interface ModelEditor { /** Candidates from available providers, including models disabled by earlier transforms. */ @@ -22,7 +24,42 @@ export interface ModelEditor { } } +/** + * Why a model request is being made. Session requests use `primary`, `compaction`, `title` and `generate`; the + * stateless generate API uses `text`, `image` and `decision`. Experimental. + */ +export type ModelRequestKind = "primary" | "compaction" | "title" | "generate" | "text" | "image" | "decision" + +/** Who is making a model request. `sessionID` and `agent` are set only when a Session makes it. Experimental. */ +export interface ModelRequestScope { + readonly model: Model.Ref + readonly kind: ModelRequestKind + readonly sessionID?: Session.ID + readonly agent?: Agent.ID +} + +/** An HTTP request to a model provider, before it is sent. Replace `request` to change it. Experimental. */ +export interface ModelHttpRequest extends ModelRequestScope { + request: Request +} + +/** The provider's HTTP response to `request`. Replace `response` to change what the model client reads. Experimental. */ +export interface ModelHttpResponse extends ModelRequestScope { + readonly request: Request + response: Response +} + +/** + * Hooks on every model request, whichever Session or API makes it: Session steps, compaction and titles, and + * `generate` text, image and decision calls. + */ +export interface ModelRequestHooks { + readonly "experimental.http.request": ModelHttpRequest + readonly "experimental.http.response": ModelHttpResponse +} + export interface ModelDomain extends ModelApi { + readonly hook: ModelHooks readonly transform: Transform readonly reload: () => Promise } diff --git a/services/site/src/docs/content/build/plugins/server.mdx b/services/site/src/docs/content/build/plugins/server.mdx index 29d747ba2f46..c41fb0bc4368 100644 --- a/services/site/src/docs/content/build/plugins/server.mdx +++ b/services/site/src/docs/content/build/plugins/server.mdx @@ -1704,6 +1704,51 @@ interface SessionHookContext { } ``` +### Models (experimental) + +Model HTTP hooks see every HTTP request to a model provider, whichever Session or API makes it: Session steps, +compaction and titles, and [Generate](#generate-experimental) text, image and decision calls. They work like the +session [Native HTTP](#native-http) hooks and wrap them: a model request hook runs before the session one, and a model +response hook runs after it. + +`event.kind` is `"primary"`, `"compaction"`, `"title"` or `"generate"` for Session requests, and `"text"`, `"image"` +or `"decision"` for Generate. `sessionID` and `agent` are set only for Session requests. Generate calls made through +the HTTP API run in the global config location, so only globally configured plugins see them. + +```ts +await ctx.model.hook( + "experimental.http.request", + (event) => { + event.request.headers.set("x-request-kind", event.kind) + }, + { providerID: "openai" }, +) +``` + +#### Reference + +```ts +interface ModelHookContext { + hook( + name: Name, + callback: (event: ModelRequestHooks[Name]) => Promise | void, + options?: { providerID?: string }, + ): Promise +} + +interface ModelRequestScope { + model: { providerID: string; id: string } + kind: "primary" | "compaction" | "title" | "generate" | "text" | "image" | "decision" + sessionID?: string + agent?: string +} + +interface ModelRequestHooks { + "experimental.http.request": ModelRequestScope & { request: Request } + "experimental.http.response": ModelRequestScope & { request: Request; response: Response } +} +``` + ### Permissions Review permission decisions after configured rules are evaluated and before an From 704df147081fc2e292635f42edcffa1931fae195 Mon Sep 17 00:00:00 2001 From: Aiden Cline Date: Tue, 10 Nov 2026 14:37:38 -0600 Subject: [PATCH 2/7] feat(plugin): route session HTTP hooks through model HTTP hooks --- packages/core/src/model-http.ts | 38 +++--------- packages/core/src/plugin/hooks.ts | 49 +++++++++++++-- packages/core/src/session/model-request.ts | 2 +- .../core/test/plugin/provider-azure.test.ts | 14 +++-- .../plugin/provider-github-copilot.test.ts | 10 ++- .../test/plugin/provider-opencode.test.ts | 5 +- packages/core/test/plugin/warming.test.ts | 1 + .../test/session-model-request-hooks.test.ts | 43 +++++++++++++ packages/plugin/src/effect/model.ts | 31 ++++++---- packages/plugin/src/effect/session.ts | 12 ++++ packages/plugin/src/promise/model.ts | 31 ++++++---- packages/plugin/src/promise/session.ts | 12 ++++ .../src/docs/content/build/plugins/effect.mdx | 18 +++--- .../docs/content/build/plugins/migrate-v1.mdx | 40 ++++++------ .../src/docs/content/build/plugins/server.mdx | 61 ++++++++----------- 15 files changed, 235 insertions(+), 132 deletions(-) diff --git a/packages/core/src/model-http.ts b/packages/core/src/model-http.ts index c073701b9b90..3d55cc666ce7 100644 --- a/packages/core/src/model-http.ts +++ b/packages/core/src/model-http.ts @@ -1,41 +1,25 @@ export * as ModelHttp from "./model-http.js" import type { HttpMiddleware } from "@opencode/ai/route" -import type { SessionRequestKind } from "@opencode/plugin/effect/session" -import type { Agent } from "@opencode/schema/agent" -import type { Model } from "@opencode/schema/model" -import type { Session } from "@opencode/schema/session" +import type { ModelRequestScope } from "@opencode/plugin/effect/model" import { Effect, Stream } from "effect" import { HttpClientRequest, HttpClientResponse } from "effect/http" import type { PluginHooks } from "./plugin/hooks.js" -export type Scope = { readonly model: Model.Ref } & ( - | { readonly kind: SessionRequestKind; readonly sessionID: Session.ID; readonly agent: Agent.ID } - | { readonly kind: "text" | "image" | "decision" } -) - /** - * Per-call middleware that runs the model `experimental.http.*` hooks, and the session `http.*` hooks when a Session - * makes the request. Model hooks wrap session hooks. Undefined when no hook applies. + * Per-call middleware that runs the model `experimental.http.*` hooks, which include the session `http.*` hooks. + * Undefined when no hook applies. */ -export const middleware = Effect.fnUntraced(function* (hooks: PluginHooks.Interface, scope: Scope) { +export const middleware = Effect.fnUntraced(function* (hooks: PluginHooks.Interface, scope: ModelRequestScope) { const providerID = scope.model.providerID - const session = "sessionID" in scope ? scope : undefined - const any = [ - yield* hooks.has("model", "experimental.http.request", providerID), - yield* hooks.has("model", "experimental.http.response", providerID), - session !== undefined && (yield* hooks.has("session", "http.request", providerID)), - session !== undefined && (yield* hooks.has("session", "http.response", providerID)), - ].some(Boolean) + const any = + (yield* hooks.has("model", "experimental.http.request", providerID)) || + (yield* hooks.has("model", "experimental.http.response", providerID)) if (!any) return undefined const http: HttpMiddleware = (req, handler) => Effect.gen(function* () { const request = yield* HttpClientRequest.toWeb(req) - const outer = yield* hooks.trigger("model", "experimental.http.request", { ...scope, request }) - const before = - session === undefined - ? outer - : yield* hooks.trigger("session", "http.request", { ...session, request: outer.request }) + const before = yield* hooks.trigger("model", "experimental.http.request", { ...scope, request }) // A hook that kept the request object cannot have replaced its body, so the original body is sent as is. // Reading it back would hold a second full copy of the request, screenshots included, for the whole call. const sent = @@ -53,14 +37,10 @@ export const middleware = Effect.fnUntraced(function* (hooks: PluginHooks.Interf [204, 205, 304].includes(res.status) ? null : yield* Stream.toReadableStreamEffect(res.stream), { status: res.status, headers: res.headers }, ) - const inner = - session === undefined - ? { response } - : yield* hooks.trigger("session", "http.response", { ...session, request: before.request, response }) const after = yield* hooks.trigger("model", "experimental.http.response", { ...scope, request: before.request, - response: inner.response, + response, }) return HttpClientResponse.fromWeb(sent, after.response) }) diff --git a/packages/core/src/plugin/hooks.ts b/packages/core/src/plugin/hooks.ts index 783aefdadb3f..08cecc4da4c1 100644 --- a/packages/core/src/plugin/hooks.ts +++ b/packages/core/src/plugin/hooks.ts @@ -1,8 +1,8 @@ export * as PluginHooks from "./hooks.js" import type { AISDKHooks } from "@opencode/plugin/effect/aisdk" -import type { ModelRequestHooks } from "@opencode/plugin/effect/model" -import type { SessionHooks } from "@opencode/plugin/effect/session" +import type { ModelHttpRequest, ModelHttpResponse, ModelRequestHooks } from "@opencode/plugin/effect/model" +import type { SessionHooks, SessionHttpRequest, SessionHttpResponse } from "@opencode/plugin/effect/session" import type { ShellHooks } from "@opencode/plugin/effect/shell" import type { ToolFailures, ToolHooks } from "@opencode/plugin/effect/tool" import type { ModelHookOptions } from "@opencode/plugin/effect/registration" @@ -67,14 +67,22 @@ const layer = Layer.effect( Service, Effect.gen(function* () { const callbacks = new Map() - const key = (domain: keyof Domains, name: PropertyKey) => `${domain}.${String(name)}` + // The session HTTP hooks are model HTTP hooks that skip calls made outside a Session. + const key = (domain: keyof Domains, name: PropertyKey) => + domain === "session" && (name === "http.request" || name === "http.response") + ? `model.experimental.${name}` + : `${domain}.${String(name)}` const register: Interface["register"] = Effect.fn("PluginHooks.register")( function* (domain, name, callback, options) { const scope = yield* Scope.Scope const id = key(domain, name) let active = true - const entry = { callback, options } + const entry = { + callback: + domain !== "session" ? callback : name === "http.request" ? sessionRequest(callback) : name === "http.response" ? sessionResponse(callback) : callback, + options, + } callbacks.set(id, [...(callbacks.get(id) ?? []), entry]) const dispose = Effect.sync(() => { if (!active) return @@ -108,4 +116,37 @@ const layer = Layer.effect( }), ) +function sessionRequest(callback: Function) { + return (event: ModelHttpRequest): Effect.Effect => { + if (event.session === undefined) return Effect.void + const legacy: SessionHttpRequest = { + sessionID: event.session.id, + agent: event.session.agent, + model: event.model, + kind: event.kind, + request: event.request, + } + return Effect.map(callback(legacy), () => { + event.request = legacy.request + }) + } +} + +function sessionResponse(callback: Function) { + return (event: ModelHttpResponse): Effect.Effect => { + if (event.session === undefined) return Effect.void + const legacy: SessionHttpResponse = { + sessionID: event.session.id, + agent: event.session.agent, + model: event.model, + kind: event.kind, + request: event.request, + response: event.response, + } + return Effect.map(callback(legacy), () => { + event.response = legacy.response + }) + } +} + export const node = makeLocationNode({ service: Service, layer, deps: [] }) diff --git a/packages/core/src/session/model-request.ts b/packages/core/src/session/model-request.ts index d4e03f9a82a1..cb24c347c948 100644 --- a/packages/core/src/session/model-request.ts +++ b/packages/core/src/session/model-request.ts @@ -349,7 +349,7 @@ export const layer = Layer.effect( model: route === base.model.route ? base.model : LanguageModel.update(base.model, { route }), headers: Object.keys(modelHook.headers).length === 0 ? undefined : modelHook.headers, } - const http = yield* ModelHttp.middleware(hooks, scope) + const http = yield* ModelHttp.middleware(hooks, { model: model.ref, kind, session: { id: session.id, agent: input.agent } }) // HTTP hooks wrap every HTTP request, including the WebSocket fallback path. The route decides // which transport actually carries the request, so both hook families are always offered. const webSocket = diff --git a/packages/core/test/plugin/provider-azure.test.ts b/packages/core/test/plugin/provider-azure.test.ts index 53992f51ee30..c87422c0babf 100644 --- a/packages/core/test/plugin/provider-azure.test.ts +++ b/packages/core/test/plugin/provider-azure.test.ts @@ -601,9 +601,10 @@ describe("AzurePlugin requests", () => { kind: "primary" as const, } - const azure = yield* hooks.trigger("session", "http.request", { - ...context, - sessionID: Session.ID.make("ses_azure"), + const azure = yield* hooks.trigger("model", "experimental.http.request", { + model: context.model, + kind: context.kind, + session: { id: Session.ID.make("ses_azure"), agent: context.agent }, request: new Request("https://test-resource.openai.azure.com/openai/v1/responses", { headers: { "api-key": "stored-token", "x-keep": "yes" }, }), @@ -614,9 +615,10 @@ describe("AzurePlugin requests", () => { expect(azure.request.headers.has("api-key")).toBe(false) expect(azure.request.headers.get("x-keep")).toBe("yes") - const foundry = yield* hooks.trigger("session", "http.request", { - ...context, - sessionID: Session.ID.make("ses_foundry"), + const foundry = yield* hooks.trigger("model", "experimental.http.request", { + model: context.model, + kind: context.kind, + session: { id: Session.ID.make("ses_foundry"), agent: context.agent }, request: new Request("https://test-resource.services.ai.azure.com/anthropic/v1/messages", { headers: { "x-api-key": "stored-token" }, }), diff --git a/packages/core/test/plugin/provider-github-copilot.test.ts b/packages/core/test/plugin/provider-github-copilot.test.ts index 841b03d38610..c9e2881dab9c 100644 --- a/packages/core/test/plugin/provider-github-copilot.test.ts +++ b/packages/core/test/plugin/provider-github-copilot.test.ts @@ -41,9 +41,8 @@ function required(value: T | undefined): T { const httpRequest = Effect.fn(function* (request: Request) { const hooks = yield* PluginHooks.Service - return yield* hooks.trigger("session", "http.request", { - sessionID: Session.ID.make("ses_test"), - agent: Agent.ID.make("build"), + return yield* hooks.trigger("model", "experimental.http.request", { + session: { id: Session.ID.make("ses_test"), agent: Agent.ID.make("build") }, model: Model.Ref.make({ providerID: Provider.ID.githubCopilot, id: Model.ID.make("gpt-5.4") }), kind: "primary", request, @@ -302,9 +301,8 @@ describe("GithubCopilotPlugin", () => { Effect.gen(function* () { yield* addPlugin() const hooks = yield* PluginHooks.Service - const event = yield* hooks.trigger("session", "http.request", { - sessionID: Session.ID.make("ses_test"), - agent: Agent.ID.make("build"), + const event = yield* hooks.trigger("model", "experimental.http.request", { + session: { id: Session.ID.make("ses_test"), agent: Agent.ID.make("build") }, model: Model.Ref.make({ providerID: Provider.ID.githubCopilot, id: Model.ID.make("claude-sonnet-4.5") }), kind: "primary", request: new Request("https://api.githubcopilot.com/v1/messages", { diff --git a/packages/core/test/plugin/provider-opencode.test.ts b/packages/core/test/plugin/provider-opencode.test.ts index f504a1713513..14f48d668ac6 100644 --- a/packages/core/test/plugin/provider-opencode.test.ts +++ b/packages/core/test/plugin/provider-opencode.test.ts @@ -932,9 +932,8 @@ describe("OpencodePlugin", () => { yield* drain const rejected = (providerID: Provider.ID) => hooks - .trigger("session", "http.response", { - sessionID: Session.ID.make("ses_console"), - agent: Agent.ID.make("build"), + .trigger("model", "experimental.http.response", { + session: { id: Session.ID.make("ses_console"), agent: Agent.ID.make("build") }, model: Model.Ref.make({ providerID, id: Model.ID.make("model") }), kind: "primary", request: new Request("https://inference.example/v1/responses"), diff --git a/packages/core/test/plugin/warming.test.ts b/packages/core/test/plugin/warming.test.ts index d1fa5c967100..33d1fab61578 100644 --- a/packages/core/test/plugin/warming.test.ts +++ b/packages/core/test/plugin/warming.test.ts @@ -63,6 +63,7 @@ const run = Effect.fnUntraced(function* ( yield* WarmingPlugin.Plugin.effect( host({ model: { + hook: () => Effect.die("unused model.hook"), list: () => Effect.succeed({ location: { directory }, data: [{ ...model, settings: { cache } }] }), default: () => Effect.die("unused model.default"), transform: () => Effect.die("unused model.transform"), diff --git a/packages/core/test/session-model-request-hooks.test.ts b/packages/core/test/session-model-request-hooks.test.ts index 32b6eab685cd..3ce116e4a929 100644 --- a/packages/core/test/session-model-request-hooks.test.ts +++ b/packages/core/test/session-model-request-hooks.test.ts @@ -6,6 +6,7 @@ import { Money } from "@opencode/schema/money" import { Session } from "@opencode/schema/session" import type { SessionRequestKind } from "@opencode/plugin/effect/session" import { Location } from "@opencode/core/location" +import { ModelHttp } from "@opencode/core/model-http" import { PluginHooks } from "@opencode/core/plugin/hooks" import { Project } from "@opencode/core/project" import { AbsolutePath } from "@opencode/core/schema" @@ -238,3 +239,45 @@ describe("SessionModelRequest HTTP hooks", () => { }), ) }) + +describe("model HTTP hooks", () => { + it.effect("run for every call, and session http hooks only for calls with a Session", () => + Effect.gen(function* () { + const hooks = yield* PluginHooks.Service + const seen: string[] = [] + yield* hooks.register("model", "experimental.http.request", (event) => + Effect.sync(() => { + seen.push(`model:${event.kind}:${event.session?.id ?? "-"}`) + event.request = new Request(event.request, { headers: { "x-model-hook": "1" } }) + }), + ) + yield* hooks.register("session", "http.request", (event) => + Effect.sync(() => { + seen.push(`session:${event.kind}:${event.sessionID}:${event.request.headers.get("x-model-hook")}`) + }), + ) + const sent: string[] = [] + const send = (scope: Parameters[1]) => + Effect.gen(function* () { + const http = yield* ModelHttp.middleware(hooks, scope) + if (!http) throw new Error("Expected HTTP middleware") + yield* http(HttpClientRequest.post("https://example.test/v1/responses"), (request) => + Effect.sync(() => { + sent.push(request.headers["x-model-hook"] ?? "") + return HttpClientResponse.fromWeb(request, new Response("{}", { status: 200 })) + }), + ) + }) + + yield* send({ model: model.ref, kind: "text" }) + yield* send({ + model: model.ref, + kind: "primary", + session: { id: session.id, agent: Agent.ID.make("build") }, + }) + + expect(seen).toEqual(["model:text:-", "model:primary:ses_hook_kind", "session:primary:ses_hook_kind:1"]) + expect(sent).toEqual(["1", "1"]) + }), + ) +}) diff --git a/packages/plugin/src/effect/model.ts b/packages/plugin/src/effect/model.ts index 65acda755bd9..837c9bfe59d7 100644 --- a/packages/plugin/src/effect/model.ts +++ b/packages/plugin/src/effect/model.ts @@ -4,6 +4,7 @@ import type { Model } from "@opencode/schema/model" import type { Session } from "@opencode/schema/session" import type { Effect, Types } from "effect" import type { ProviderRecord } from "./provider.js" +import type { SessionRequestKind } from "./session.js" import type { ModelHooks, Transform } from "./registration.js" export interface ModelEditor { @@ -28,30 +29,38 @@ export interface ModelEditor { * Why a model request is being made. Session requests use `primary`, `compaction`, `title` and `generate`; the * stateless generate API uses `text`, `image` and `decision`. Experimental. */ -export type ModelRequestKind = "primary" | "compaction" | "title" | "generate" | "text" | "image" | "decision" +export type ModelRequestKind = SessionRequestKind | "text" | "image" | "decision" -/** Who is making a model request. `sessionID` and `agent` are set only when a Session makes it. Experimental. */ -export interface ModelRequestScope { - readonly model: Model.Ref - readonly kind: ModelRequestKind - readonly sessionID?: Session.ID - readonly agent?: Agent.ID +/** The Session that made a model request. Experimental. */ +export interface ModelRequestSession { + readonly id: Session.ID + readonly agent: Agent.ID } +/** + * Which model is called and why. `session` is set exactly when a Session makes the request, so checking it narrows + * `kind` to the Session kinds. Experimental. + */ +export type ModelRequestScope = { readonly model: Model.Ref } & ( + | { readonly kind: SessionRequestKind; readonly session: ModelRequestSession } + | { readonly kind: "text" | "image" | "decision"; readonly session?: undefined } +) + /** An HTTP request to a model provider, before it is sent. Replace `request` to change it. Experimental. */ -export interface ModelHttpRequest extends ModelRequestScope { +export type ModelHttpRequest = ModelRequestScope & { request: Request } /** The provider's HTTP response to `request`. Replace `response` to change what the model client reads. Experimental. */ -export interface ModelHttpResponse extends ModelRequestScope { +export type ModelHttpResponse = ModelRequestScope & { readonly request: Request response: Response } /** - * Hooks on every model request, whichever Session or API makes it: Session steps, compaction and titles, and - * `generate` text, image and decision calls. + * Hooks on every HTTP request to a model provider, whichever Session or API makes it: Session steps, compaction, + * titles and warming, and `generate` text, image and decision calls. Use these to read or change what is sent on the + * wire (URL, headers, body) or the raw response. WebSocket traffic doesn't pass through them. Experimental. */ export interface ModelRequestHooks { readonly "experimental.http.request": ModelHttpRequest diff --git a/packages/plugin/src/effect/session.ts b/packages/plugin/src/effect/session.ts index cfa84d44ca54..28e935c5245d 100644 --- a/packages/plugin/src/effect/session.ts +++ b/packages/plugin/src/effect/session.ts @@ -87,6 +87,7 @@ export interface SessionModelRequest { headers: Record } +/** @deprecated Use `ctx.model.hook("experimental.http.request")`, which also runs for calls made outside a Session. */ export interface SessionHttpRequest { readonly sessionID: Session.ID readonly agent: Agent.ID @@ -95,6 +96,7 @@ export interface SessionHttpRequest { request: Request } +/** @deprecated Use `ctx.model.hook("experimental.http.response")`, which also runs for calls made outside a Session. */ export interface SessionHttpResponse { readonly sessionID: Session.ID readonly agent: Agent.ID @@ -203,7 +205,17 @@ export interface SessionHooks { readonly title: SessionTitle readonly "experimental.model.resolve": SessionModelResolve readonly "model.request": SessionModelRequest + /** + * Runs for HTTP requests a Session makes. Registered as a `ctx.model.hook("experimental.http.request")` that skips + * calls without a Session. + * @deprecated Use `ctx.model.hook("experimental.http.request")` and read `event.session`. + */ readonly "http.request": SessionHttpRequest + /** + * Runs for HTTP responses to a Session's requests. Registered as a `ctx.model.hook("experimental.http.response")` + * that skips calls without a Session. + * @deprecated Use `ctx.model.hook("experimental.http.response")` and read `event.session`. + */ readonly "http.response": SessionHttpResponse readonly "experimental.ws.handshake": SessionWebSocketHandshake readonly "experimental.ws.send": SessionWebSocketSend diff --git a/packages/plugin/src/promise/model.ts b/packages/plugin/src/promise/model.ts index 8d4715c4608e..4828e92d9c63 100644 --- a/packages/plugin/src/promise/model.ts +++ b/packages/plugin/src/promise/model.ts @@ -4,6 +4,7 @@ import type { Model } from "@opencode/schema/model" import type { Session } from "@opencode/schema/session" import type { Types } from "effect" import type { ProviderRecord } from "./provider.js" +import type { SessionRequestKind } from "./session.js" import type { ModelHooks, Transform } from "./registration.js" export interface ModelEditor { @@ -28,30 +29,38 @@ export interface ModelEditor { * Why a model request is being made. Session requests use `primary`, `compaction`, `title` and `generate`; the * stateless generate API uses `text`, `image` and `decision`. Experimental. */ -export type ModelRequestKind = "primary" | "compaction" | "title" | "generate" | "text" | "image" | "decision" +export type ModelRequestKind = SessionRequestKind | "text" | "image" | "decision" -/** Who is making a model request. `sessionID` and `agent` are set only when a Session makes it. Experimental. */ -export interface ModelRequestScope { - readonly model: Model.Ref - readonly kind: ModelRequestKind - readonly sessionID?: Session.ID - readonly agent?: Agent.ID +/** The Session that made a model request. Experimental. */ +export interface ModelRequestSession { + readonly id: Session.ID + readonly agent: Agent.ID } +/** + * Which model is called and why. `session` is set exactly when a Session makes the request, so checking it narrows + * `kind` to the Session kinds. Experimental. + */ +export type ModelRequestScope = { readonly model: Model.Ref } & ( + | { readonly kind: SessionRequestKind; readonly session: ModelRequestSession } + | { readonly kind: "text" | "image" | "decision"; readonly session?: undefined } +) + /** An HTTP request to a model provider, before it is sent. Replace `request` to change it. Experimental. */ -export interface ModelHttpRequest extends ModelRequestScope { +export type ModelHttpRequest = ModelRequestScope & { request: Request } /** The provider's HTTP response to `request`. Replace `response` to change what the model client reads. Experimental. */ -export interface ModelHttpResponse extends ModelRequestScope { +export type ModelHttpResponse = ModelRequestScope & { readonly request: Request response: Response } /** - * Hooks on every model request, whichever Session or API makes it: Session steps, compaction and titles, and - * `generate` text, image and decision calls. + * Hooks on every HTTP request to a model provider, whichever Session or API makes it: Session steps, compaction, + * titles and warming, and `generate` text, image and decision calls. Use these to read or change what is sent on the + * wire (URL, headers, body) or the raw response. WebSocket traffic doesn't pass through them. Experimental. */ export interface ModelRequestHooks { readonly "experimental.http.request": ModelHttpRequest diff --git a/packages/plugin/src/promise/session.ts b/packages/plugin/src/promise/session.ts index 5067ee006b16..2196ccd049a5 100644 --- a/packages/plugin/src/promise/session.ts +++ b/packages/plugin/src/promise/session.ts @@ -87,6 +87,7 @@ export interface SessionModelRequest { headers: Record } +/** @deprecated Use `ctx.model.hook("experimental.http.request")`, which also runs for calls made outside a Session. */ export interface SessionHttpRequest { readonly sessionID: Session.ID readonly agent: Agent.ID @@ -95,6 +96,7 @@ export interface SessionHttpRequest { request: Request } +/** @deprecated Use `ctx.model.hook("experimental.http.response")`, which also runs for calls made outside a Session. */ export interface SessionHttpResponse { readonly sessionID: Session.ID readonly agent: Agent.ID @@ -203,7 +205,17 @@ export interface SessionHooks { readonly title: SessionTitle readonly "experimental.model.resolve": SessionModelResolve readonly "model.request": SessionModelRequest + /** + * Runs for HTTP requests a Session makes. Registered as a `ctx.model.hook("experimental.http.request")` that skips + * calls without a Session. + * @deprecated Use `ctx.model.hook("experimental.http.request")` and read `event.session`. + */ readonly "http.request": SessionHttpRequest + /** + * Runs for HTTP responses to a Session's requests. Registered as a `ctx.model.hook("experimental.http.response")` + * that skips calls without a Session. + * @deprecated Use `ctx.model.hook("experimental.http.response")` and read `event.session`. + */ readonly "http.response": SessionHttpResponse readonly "experimental.ws.handshake": SessionWebSocketHandshake readonly "experimental.ws.send": SessionWebSocketSend diff --git a/services/site/src/docs/content/build/plugins/effect.mdx b/services/site/src/docs/content/build/plugins/effect.mdx index da5b1652579f..0cad39d381e8 100644 --- a/services/site/src/docs/content/build/plugins/effect.mdx +++ b/services/site/src/docs/content/build/plugins/effect.mdx @@ -1306,21 +1306,23 @@ effect: (ctx) => }), ``` -Modify native provider requests or responses. Their bodies are one-shot streams; clone or replace a body before reading -it. Both hooks run for every request a session issues; `event.kind` is `"primary"`, `"compaction"`, `"title"`, or -`"generate"` depending on which flow issued it. +Modify native provider requests or responses with the experimental model HTTP hooks. They run for every HTTP request +to a model provider, including Generate text, image and decision calls made outside a Session. Bodies are one-shot +streams; clone or replace a body before reading it. `event.kind` says why the call was made, and `event.session` is set +exactly when a Session made it. The session `http.request` and `http.response` hooks are deprecated; they still run, as +model hooks that skip calls without a Session. ```ts effect: (ctx) => Effect.gen(function* () { - const session = ctx.session - yield* session.hook("http.request", (event) => + const model = ctx.model + yield* model.hook("experimental.http.request", (event) => Effect.sync(() => { - event.request.headers.set("x-session-id", event.sessionID) + if (event.session) event.request.headers.set("x-session-id", event.session.id) if (event.kind === "title") event.request.headers.set("x-priority", "background") }), ) - yield* session.hook("http.response", (event) => + yield* model.hook("experimental.http.response", (event) => Effect.sync(() => { event.response = new Response(event.response.body, { status: event.response.status, @@ -1409,7 +1411,9 @@ interface SessionHooks { readonly generate: SessionGenerate readonly title: SessionTitle readonly "model.request": SessionModelRequest + /** @deprecated Use ctx.model.hook("experimental.http.request") */ readonly "http.request": SessionHttpRequest + /** @deprecated Use ctx.model.hook("experimental.http.response") */ readonly "http.response": SessionHttpResponse readonly "experimental.ws.handshake": SessionWebSocketHandshake readonly "experimental.ws.send": SessionWebSocketSend diff --git a/services/site/src/docs/content/build/plugins/migrate-v1.mdx b/services/site/src/docs/content/build/plugins/migrate-v1.mdx index ea263f0d9897..c70a5b20fa20 100644 --- a/services/site/src/docs/content/build/plugins/migrate-v1.mdx +++ b/services/site/src/docs/content/build/plugins/migrate-v1.mdx @@ -144,26 +144,26 @@ only when the plugin needs to remove that particular hook or transform earlier w Use this table to find the closest V2 API for each V1 hook: -| V1 hook | V2 API | -| -------------------------------------- | ------------------------------------------------------------ | -| `event` | `ctx.event.subscribe()` | -| `dispose` | cleanup function returned by `setup` | -| `config` | transforms on the affected domains | -| `tool` map | `ctx.tool.transform(...)` | -| `auth` | `ctx.integration.transform(...)` and integration APIs | -| `provider` | `ctx.provider.transform(...)` and `ctx.model.transform(...)` | -| `chat.message` | `ctx.session.hook("prompt", ...)` | -| `chat.params` | `ctx.session.hook("context", ...)` | -| `chat.headers` | `ctx.session.hook("model.request", ...)` or `"http.request"` | -| `permission.ask` | `ctx.permission.hook("evaluate", ...)` | -| `command.execute.before` | command transforms or the prompt hook, depending on intent | -| `tool.execute.before` | `ctx.tool.hook("execute.before", ...)` | -| `tool.execute.after` | `ctx.tool.hook("execute.after", ...)` | -| `shell.env` | `ctx.shell.hook("create.before", ...)` | -| `tool.definition` | `ctx.tool.transform(...)` | -| `experimental.chat.system.transform` | `ctx.session.hook("context", ...)` and edit `event.system` | -| `experimental.chat.messages.transform` | `ctx.session.hook("context", ...)` and edit `event.messages` | -| `experimental.session.compacting` | `ctx.session.hook("compaction", ...)` | +| V1 hook | V2 API | +| -------------------------------------- | ---------------------------------------------------------------------------------------------- | +| `event` | `ctx.event.subscribe()` | +| `dispose` | cleanup function returned by `setup` | +| `config` | transforms on the affected domains | +| `tool` map | `ctx.tool.transform(...)` | +| `auth` | `ctx.integration.transform(...)` and integration APIs | +| `provider` | `ctx.provider.transform(...)` and `ctx.model.transform(...)` | +| `chat.message` | `ctx.session.hook("prompt", ...)` | +| `chat.params` | `ctx.session.hook("context", ...)` | +| `chat.headers` | `ctx.session.hook("model.request", ...)` or `ctx.model.hook("experimental.http.request", ...)` | +| `permission.ask` | `ctx.permission.hook("evaluate", ...)` | +| `command.execute.before` | command transforms or the prompt hook, depending on intent | +| `tool.execute.before` | `ctx.tool.hook("execute.before", ...)` | +| `tool.execute.after` | `ctx.tool.hook("execute.after", ...)` | +| `shell.env` | `ctx.shell.hook("create.before", ...)` | +| `tool.definition` | `ctx.tool.transform(...)` | +| `experimental.chat.system.transform` | `ctx.session.hook("context", ...)` and edit `event.system` | +| `experimental.chat.messages.transform` | `ctx.session.hook("context", ...)` and edit `event.messages` | +| `experimental.session.compacting` | `ctx.session.hook("compaction", ...)` | These are migration destinations, not always exact renames. In particular, the V2 `prompt` hook runs before durable prompt admission, while `context` runs immediately before an agent model request. Register `context`, `compaction`, diff --git a/services/site/src/docs/content/build/plugins/server.mdx b/services/site/src/docs/content/build/plugins/server.mdx index c41fb0bc4368..1a1307c1e7c8 100644 --- a/services/site/src/docs/content/build/plugins/server.mdx +++ b/services/site/src/docs/content/build/plugins/server.mdx @@ -1503,31 +1503,14 @@ await ctx.session.hook( #### Native HTTP -Modify native provider requests or responses. Their bodies are one-shot streams; clone or replace a body before reading -it. - -Both hooks run for every request a session issues. `event.kind` says which flow issued it: `"primary"` for the agent -loop, `"compaction"` for checkpoint summaries, `"title"` for title generation, and `"generate"` for transient -`ctx.session.generate` calls. Use it instead of the agent ID to tell auxiliary requests apart. - -```ts -await ctx.session.hook("http.request", (event) => { - event.request.headers.set("x-session-id", event.sessionID) - if (event.kind === "title") event.request.headers.set("x-priority", "background") -}) - -await ctx.session.hook("http.response", (event) => { - event.response = new Response(event.response.body, { - status: event.response.status, - headers: { ...Object.fromEntries(event.response.headers), "x-plugin": "review" }, - }) -}) -``` +`http.request` and `http.response` are deprecated. Use the [model HTTP hooks](#models-experimental), which run for +the same requests and for calls made outside a Session. The session hooks still work: each one is registered as a +model hook that skips calls without a Session, so both kinds run in plugin order. #### 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 +the HTTP hooks 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. @@ -1615,7 +1598,9 @@ interface SessionHooks { title: SessionRequestHook & { result?: string } "experimental.model.resolve": SessionModelResolveHook "model.request": SessionModelRequestHook + /** @deprecated Use ctx.model.hook("experimental.http.request") */ "http.request": SessionHttpRequestHook + /** @deprecated Use ctx.model.hook("experimental.http.response") */ "http.response": SessionHttpResponseHook "experimental.ws.handshake": SessionWebSocketHandshakeHook "experimental.ws.send": SessionWebSocketSendHook @@ -1706,23 +1691,33 @@ interface SessionHookContext { ### Models (experimental) -Model HTTP hooks see every HTTP request to a model provider, whichever Session or API makes it: Session steps, -compaction and titles, and [Generate](#generate-experimental) text, image and decision calls. They work like the -session [Native HTTP](#native-http) hooks and wrap them: a model request hook runs before the session one, and a model -response hook runs after it. +Model HTTP hooks run for every HTTP request to a model provider, whichever Session or API makes it: Session steps, +compaction, titles and cache warming, and [Generate](#generate-experimental) text, image and decision calls. Use them to +read or change what goes on the wire (URL, headers, body) or the raw response. Request and response bodies are one-shot +streams; clone or replace a body before reading it. WebSocket traffic doesn't pass through them; see +[Native WebSocket](#native-websocket-experimental). -`event.kind` is `"primary"`, `"compaction"`, `"title"` or `"generate"` for Session requests, and `"text"`, `"image"` -or `"decision"` for Generate. `sessionID` and `agent` are set only for Session requests. Generate calls made through -the HTTP API run in the global config location, so only globally configured plugins see them. +`event.kind` says why the call was made: `"primary"`, `"compaction"`, `"title"` or `"generate"` for Session requests, +and `"text"`, `"image"` or `"decision"` for Generate. `event.session` is set exactly when a Session made the call. +Generate calls made through the HTTP API run in the global config location, so only globally configured plugins see +them. ```ts await ctx.model.hook( "experimental.http.request", (event) => { event.request.headers.set("x-request-kind", event.kind) + if (event.session) event.request.headers.set("x-session-id", event.session.id) }, { providerID: "openai" }, ) + +await ctx.model.hook("experimental.http.response", (event) => { + event.response = new Response(event.response.body, { + status: event.response.status, + headers: { ...Object.fromEntries(event.response.headers), "x-plugin": "review" }, + }) +}) ``` #### Reference @@ -1736,12 +1731,10 @@ interface ModelHookContext { ): Promise } -interface ModelRequestScope { - model: { providerID: string; id: string } - kind: "primary" | "compaction" | "title" | "generate" | "text" | "image" | "decision" - sessionID?: string - agent?: string -} +type ModelRequestScope = { model: { providerID: string; id: string } } & ( + | { kind: "primary" | "compaction" | "title" | "generate"; session: { id: string; agent: string } } + | { kind: "text" | "image" | "decision"; session?: undefined } +) interface ModelRequestHooks { "experimental.http.request": ModelRequestScope & { request: Request } From 28607054965a138f0f1b3c3853c76042e557726d Mon Sep 17 00:00:00 2001 From: Aiden Cline Date: Tue, 10 Nov 2026 19:03:15 -0600 Subject: [PATCH 3/7] fix(core): address review of model HTTP hooks --- AGENTS.md | 2 +- packages/core/src/generate.ts | 24 ++++----- packages/core/src/plugin/hooks.ts | 43 ++++++++++------ packages/core/src/session/model-request.ts | 6 ++- packages/core/test/generate.test.ts | 49 ++++++++++++++++++- .../core/test/plugin/provider-chatgpt.test.ts | 4 +- .../core/test/plugin/provider-openai.test.ts | 4 +- packages/plugin/src/effect/model.ts | 11 ++--- packages/plugin/src/promise/model.ts | 11 ++--- .../src/docs/content/build/plugins/effect.mdx | 21 ++++++-- .../docs/content/build/plugins/migrate-v1.mdx | 5 +- .../src/docs/content/build/plugins/server.mdx | 14 +++--- 12 files changed, 133 insertions(+), 61 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ebfc4fd6d9ae..3ff908b2ae2a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -208,7 +208,7 @@ const table = sqliteTable("session", { - Temporary exception: endpoints that list or use providers managed policy can deny (`model.list`, `model.default`, `provider.list`, `generate.*`, `voice.*` and `websearch.query`) wait through `awaitPlugins` in `packages/server/src/location.ts`, because policy is applied by the last plugin to activate and is missing until then. Don't add new waits; this goes away once a plugin batch becomes visible only when it ends. - The server answers with what is loaded now: lists may be empty or partial on a cold Location, and an action whose model, provider or RPC hasn't loaded yet fails with not-found. That is expected, not a bug to fix on the server. - Clients are responsible for making sure what they need is loaded before they call. Long-lived clients refresh on the matching `*.updated` event (`model.updated`, `agent.updated`, `skill.updated`, `integration.updated`, `plugin.updated`, ...). One-shot clients (CLI commands, ACP, SDK callers) wait on their side, for example by polling `plugin.list` or the entry they need. See `packages/cli/src/services/plugin-startup.ts`. -- Running the hooks that are registered and waiting for their result is fine (for example `hooks.trigger("session", "http.request", ...)`). What is not allowed is waiting for plugins to load first: if the plugin that adds a hook hasn't loaded yet, the call runs without that hook. +- Running the hooks that are registered and waiting for their result is fine (for example `hooks.trigger("model", "experimental.http.request", ...)`). What is not allowed is waiting for plugins to load first: if the plugin that adds a hook hasn't loaded yet, the call runs without that hook. ## Session Core diff --git a/packages/core/src/generate.ts b/packages/core/src/generate.ts index 7b388ed88d32..c4810864cbb6 100644 --- a/packages/core/src/generate.ts +++ b/packages/core/src/generate.ts @@ -80,6 +80,7 @@ export interface Interface { export class Service extends Context.Service()("@opencode/Generate") {} +// Image and decision clients are built here, on the shared request executor, so only Generate depends on them. export const layer = Layer.effect( Service, Effect.gen(function* () { @@ -88,14 +89,11 @@ export const layer = Layer.effect( const models = yield* Model.Service const executor = yield* RequestExecutor.Service const hooks = yield* PluginHooks.Service - // Image and decision clients are built per call so the model HTTP hooks wrap every provider request they make. - const clients = (http: HttpMiddleware | undefined) => - Layer.provide( - Layer.merge(ImageClient.layer, DecisionClient.layer), - http === undefined - ? Layer.succeed(RequestExecutor.Service, executor) - : RequestExecutor.middleware(http, Layer.succeed(RequestExecutor.Service, executor)), - ) + const images = yield* ImageClient.Service + const decisionClient = yield* DecisionClient.Service + // With model HTTP hooks, the call gets a fresh client (not the memoized one) on an executor that runs them. + const hooked = (http: HttpMiddleware) => + RequestExecutor.middleware(http, Layer.succeed(RequestExecutor.Service, executor)) const runText = Effect.fn("Generate.text")(function* (input: TextInput) { const resolved = yield* resolver.resolve(input.model).pipe( @@ -171,7 +169,9 @@ export const layer = Layer.effect( aspect: input.aspect, resolution: input.resolution, }).pipe( - Effect.provide(clients(http)), + http === undefined + ? Effect.provideService(ImageClient.Service, images) + : Effect.provide(Layer.fresh(ImageClient.layer).pipe(Layer.provide(hooked(http)))), ModelRetry.retryOneShot, Effect.mapError((error) => providerError(input.model, error)), ) @@ -211,7 +211,9 @@ export const layer = Layer.effect( ), questions: input.questions, }).pipe( - Effect.provide(clients(http)), + http === undefined + ? Effect.provideService(DecisionClient.Service, decisionClient) + : Effect.provide(Layer.fresh(DecisionClient.layer).pipe(Layer.provide(hooked(http)))), ModelRetry.retryOneShot, Effect.mapError((error) => providerError(input.model, error)), ) @@ -240,7 +242,7 @@ export const layer = Layer.effect( decisions: (input) => credentials(decisions(input)), }) }), -) +).pipe(Layer.provide([ImageClient.layer, DecisionClient.layer])) // Provider metadata may hold undefined fields, which the JSON response schema rejects. function plainJson(value: Record): Record { diff --git a/packages/core/src/plugin/hooks.ts b/packages/core/src/plugin/hooks.ts index 08cecc4da4c1..f67f03ea8e8f 100644 --- a/packages/core/src/plugin/hooks.ts +++ b/packages/core/src/plugin/hooks.ts @@ -42,10 +42,17 @@ const eventProviderID = (event: unknown) => { return typeof model.providerID === "string" ? model.providerID : undefined } +type Name = keyof Domains[Domain] & keyof Failures[Domain] +// The deprecated session HTTP hooks register into the model HTTP hooks, so only the model names are triggered. +type Triggered = Exclude< + Name, + Domain extends "session" ? "http.request" | "http.response" : never +> + export interface Interface { readonly has: ( domain: Domain, - name: keyof Domains[Domain] & keyof Failures[Domain], + name: Triggered, providerID?: string, ) => Effect.Effect readonly register: ( @@ -54,11 +61,11 @@ export interface Interface { callback: Callback, options?: ModelHookOptions, ) => Effect.Effect - readonly trigger: ( + readonly trigger: >( domain: Domain, - name: Name, - event: Domains[Domain][Name], - ) => Effect.Effect + name: Hook, + event: Domains[Domain][Hook], + ) => Effect.Effect } export class Service extends Context.Service()("@opencode/PluginHooks") {} @@ -67,22 +74,21 @@ const layer = Layer.effect( Service, Effect.gen(function* () { const callbacks = new Map() - // The session HTTP hooks are model HTTP hooks that skip calls made outside a Session. - const key = (domain: keyof Domains, name: PropertyKey) => - domain === "session" && (name === "http.request" || name === "http.response") - ? `model.experimental.${name}` - : `${domain}.${String(name)}` + const key = (domain: keyof Domains, name: PropertyKey) => `${domain}.${String(name)}` const register: Interface["register"] = Effect.fn("PluginHooks.register")( function* (domain, name, callback, options) { const scope = yield* Scope.Scope - const id = key(domain, name) + // The session HTTP hooks are model HTTP hooks that skip calls made outside a Session. + const legacy = + domain === "session" && name === "http.request" + ? sessionHttp.request + : domain === "session" && name === "http.response" + ? sessionHttp.response + : undefined + const id = legacy ? legacy.id : key(domain, name) let active = true - const entry = { - callback: - domain !== "session" ? callback : name === "http.request" ? sessionRequest(callback) : name === "http.response" ? sessionResponse(callback) : callback, - options, - } + const entry = { callback: legacy ? legacy.adapt(callback) : callback, options } callbacks.set(id, [...(callbacks.get(id) ?? []), entry]) const dispose = Effect.sync(() => { if (!active) return @@ -116,6 +122,11 @@ const layer = Layer.effect( }), ) +const sessionHttp = { + request: { id: "model.experimental.http.request", adapt: sessionRequest }, + response: { id: "model.experimental.http.response", adapt: sessionResponse }, +} + function sessionRequest(callback: Function) { return (event: ModelHttpRequest): Effect.Effect => { if (event.session === undefined) return Effect.void diff --git a/packages/core/src/session/model-request.ts b/packages/core/src/session/model-request.ts index cb24c347c948..97e3f625a05d 100644 --- a/packages/core/src/session/model-request.ts +++ b/packages/core/src/session/model-request.ts @@ -349,7 +349,11 @@ export const layer = Layer.effect( model: route === base.model.route ? base.model : LanguageModel.update(base.model, { route }), headers: Object.keys(modelHook.headers).length === 0 ? undefined : modelHook.headers, } - const http = yield* ModelHttp.middleware(hooks, { model: model.ref, kind, session: { id: session.id, agent: input.agent } }) + const http = yield* ModelHttp.middleware(hooks, { + model: model.ref, + kind, + session: { id: session.id, agent: input.agent }, + }) // HTTP hooks wrap every HTTP request, including the WebSocket fallback path. The route decides // which transport actually carries the request, so both hook families are always offered. const webSocket = diff --git a/packages/core/test/generate.test.ts b/packages/core/test/generate.test.ts index 73e8ff5e27c4..38b28d0d6f17 100644 --- a/packages/core/test/generate.test.ts +++ b/packages/core/test/generate.test.ts @@ -270,7 +270,9 @@ testEffect(Layer.empty).effect("attributes each stateless completion without cre }), ).toBe("OK") } - }).pipe(Effect.provide(Generate.layer.pipe(Layer.provide(Layer.mergeAll(resolver, native, models, hooks, executor))))) + }).pipe( + Effect.provide(Generate.layer.pipe(Layer.provide(Layer.mergeAll(resolver, native, models, hooks, executor)))), + ) expect(sessions).toHaveLength(2) expect(sessions[0]).toStartWith("ses_") expect(sessions[1]).not.toBe(sessions[0]) @@ -593,6 +595,51 @@ describe("image and decision generation", () => { }), ) + // Records each model HTTP hook call and tags the request, so the provider sees which calls were hooked. + const hooked: string[] = [] + const recording = Layer.mock(PluginHooks.Service, { + has: () => Effect.succeed(true), + trigger: (_domain, name, event) => + Effect.sync(() => { + record(String(name), event) + return event + }), + }) + const record = (name: string, event: unknown) => { + if (!(event instanceof Object) || !("kind" in event)) return + hooked.push(`${name}:${String(event.kind)}`) + if (name === "experimental.http.request" && "request" in event && event.request instanceof Request) + event.request.headers.set("x-hook", "1") + } + const hookedIt = testEffect( + Generate.layer.pipe(Layer.provide(Layer.mergeAll(mediaResolver, client, mediaModels, recording, executor))), + ) + + hookedIt.effect("runs model HTTP hooks on image and decision provider requests, but not image downloads", () => + Effect.gen(function* () { + requests.length = 0 + hooked.length = 0 + const generate = yield* Generate.Service + yield* generate.image({ model: ref("zai", "glm-image"), prompt: "A fox" }) + yield* generate.decisions({ + model: ref("decide-host", "decide-default"), + input: [{ type: "text", text: "Is this a photo?" }], + questions: [{ type: "predicate", name: "photo", instructions: "Is this a photo?" }], + }) + expect(hooked).toEqual([ + "experimental.http.request:image", + "experimental.http.response:image", + "experimental.http.request:decision", + "experimental.http.response:decision", + ]) + expect(requests.map((request) => [request.url, request.headers["x-hook"] ?? "-"])).toEqual([ + ["https://api.z.ai/api/paas/v4/images/generations", "1"], + ["https://images.example/fox", "-"], + ["https://api.typesafe.ai/v1/systemone", "1"], + ]) + }), + ) + mediaIt.effect("rejects models of another type and unknown models", () => Effect.gen(function* () { const generate = yield* Generate.Service diff --git a/packages/core/test/plugin/provider-chatgpt.test.ts b/packages/core/test/plugin/provider-chatgpt.test.ts index ae9391c7813a..dfb4a8d210be 100644 --- a/packages/core/test/plugin/provider-chatgpt.test.ts +++ b/packages/core/test/plugin/provider-chatgpt.test.ts @@ -92,8 +92,8 @@ const request = Effect.fn(function* ( baseURL: event.baseURL, headers: event.headers, hasHttpHooks: - (yield* hooks.has("session", "http.request", providerID)) || - (yield* hooks.has("session", "http.response", providerID)), + (yield* hooks.has("model", "experimental.http.request", providerID)) || + (yield* hooks.has("model", "experimental.http.response", providerID)), } }) diff --git a/packages/core/test/plugin/provider-openai.test.ts b/packages/core/test/plugin/provider-openai.test.ts index a31871d0a131..6d5b7d8a3409 100644 --- a/packages/core/test/plugin/provider-openai.test.ts +++ b/packages/core/test/plugin/provider-openai.test.ts @@ -60,8 +60,8 @@ const request = Effect.fn(function* ( baseURL: event.baseURL, headers: event.headers, hasHttpHooks: - (yield* hooks.has("session", "http.request", providerID)) || - (yield* hooks.has("session", "http.response", providerID)), + (yield* hooks.has("model", "experimental.http.request", providerID)) || + (yield* hooks.has("model", "experimental.http.response", providerID)), } }) diff --git a/packages/plugin/src/effect/model.ts b/packages/plugin/src/effect/model.ts index 837c9bfe59d7..75c799935320 100644 --- a/packages/plugin/src/effect/model.ts +++ b/packages/plugin/src/effect/model.ts @@ -25,12 +25,6 @@ export interface ModelEditor { } } -/** - * Why a model request is being made. Session requests use `primary`, `compaction`, `title` and `generate`; the - * stateless generate API uses `text`, `image` and `decision`. Experimental. - */ -export type ModelRequestKind = SessionRequestKind | "text" | "image" | "decision" - /** The Session that made a model request. Experimental. */ export interface ModelRequestSession { readonly id: Session.ID @@ -38,8 +32,9 @@ export interface ModelRequestSession { } /** - * Which model is called and why. `session` is set exactly when a Session makes the request, so checking it narrows - * `kind` to the Session kinds. Experimental. + * Which model is called and why. `session` is set for a Session's own model requests, so checking it narrows `kind` + * to the Session kinds. A tool that calls Generate from inside a Session makes a Generate call with no `session`. + * Experimental. */ export type ModelRequestScope = { readonly model: Model.Ref } & ( | { readonly kind: SessionRequestKind; readonly session: ModelRequestSession } diff --git a/packages/plugin/src/promise/model.ts b/packages/plugin/src/promise/model.ts index 4828e92d9c63..8f2d3b4e7a27 100644 --- a/packages/plugin/src/promise/model.ts +++ b/packages/plugin/src/promise/model.ts @@ -25,12 +25,6 @@ export interface ModelEditor { } } -/** - * Why a model request is being made. Session requests use `primary`, `compaction`, `title` and `generate`; the - * stateless generate API uses `text`, `image` and `decision`. Experimental. - */ -export type ModelRequestKind = SessionRequestKind | "text" | "image" | "decision" - /** The Session that made a model request. Experimental. */ export interface ModelRequestSession { readonly id: Session.ID @@ -38,8 +32,9 @@ export interface ModelRequestSession { } /** - * Which model is called and why. `session` is set exactly when a Session makes the request, so checking it narrows - * `kind` to the Session kinds. Experimental. + * Which model is called and why. `session` is set for a Session's own model requests, so checking it narrows `kind` + * to the Session kinds. A tool that calls Generate from inside a Session makes a Generate call with no `session`. + * Experimental. */ export type ModelRequestScope = { readonly model: Model.Ref } & ( | { readonly kind: SessionRequestKind; readonly session: ModelRequestSession } diff --git a/services/site/src/docs/content/build/plugins/effect.mdx b/services/site/src/docs/content/build/plugins/effect.mdx index 0cad39d381e8..f5f6fd988f6b 100644 --- a/services/site/src/docs/content/build/plugins/effect.mdx +++ b/services/site/src/docs/content/build/plugins/effect.mdx @@ -1291,8 +1291,9 @@ The `system` part that holds OpenCode's instructions also lists each source in ` `{ key, text }`, such as `core/date` or `core/environment`, so a hook can tell the sources apart. The list is a copy: editing the part's `text` does not update it. This is experimental and may change. -Modify model request settings and optionally scope the hook to one provider. The event carries the same `kind` as -the HTTP hooks below. +Modify model request settings and optionally scope the hook to one provider. Its `kind` is `"primary"`, +`"compaction"`, `"title"` or `"generate"`. It only runs for Session requests; to change the URL or headers of any model +call, use the model HTTP hooks below. ```ts effect: (ctx) => @@ -1309,7 +1310,7 @@ effect: (ctx) => Modify native provider requests or responses with the experimental model HTTP hooks. They run for every HTTP request to a model provider, including Generate text, image and decision calls made outside a Session. Bodies are one-shot streams; clone or replace a body before reading it. `event.kind` says why the call was made, and `event.session` is set -exactly when a Session made it. The session `http.request` and `http.response` hooks are deprecated; they still run, as +for a Session's own model requests. The session `http.request` and `http.response` hooks are deprecated; they still run, as model hooks that skip calls without a Session. ```ts @@ -1435,6 +1436,20 @@ interface SessionRetry { interface SessionHookDomain { readonly hook: ModelHooks } + +type ModelRequestScope = { readonly model: { providerID: string; id: string; variant?: string } } & ( + | { readonly kind: "primary" | "compaction" | "title" | "generate"; readonly session: { id: string; agent: string } } + | { readonly kind: "text" | "image" | "decision"; readonly session?: undefined } +) + +interface ModelRequestHooks { + readonly "experimental.http.request": ModelRequestScope & { request: Request } + readonly "experimental.http.response": ModelRequestScope & { readonly request: Request; response: Response } +} + +interface ModelHookDomain { + readonly hook: ModelHooks +} ``` ### Shell diff --git a/services/site/src/docs/content/build/plugins/migrate-v1.mdx b/services/site/src/docs/content/build/plugins/migrate-v1.mdx index c70a5b20fa20..10de7984e418 100644 --- a/services/site/src/docs/content/build/plugins/migrate-v1.mdx +++ b/services/site/src/docs/content/build/plugins/migrate-v1.mdx @@ -219,8 +219,9 @@ export default Plugin.define({ ``` Use semantic provider options in `event.options`. Use `model.request` for model request headers and raw request settings, -and use `http.request` or `http.response` only when the plugin needs the native provider HTTP exchange. Provider-specific -hooks can pass `{ providerID: "..." }` as the third argument to `ctx.session.hook`. +and use `ctx.model.hook("experimental.http.request")` or `"experimental.http.response"` only when the plugin needs the +native provider HTTP exchange. Provider-specific hooks can pass `{ providerID: "..." }` as the third argument to +`ctx.session.hook` and `ctx.model.hook`. ## Migrate custom tools diff --git a/services/site/src/docs/content/build/plugins/server.mdx b/services/site/src/docs/content/build/plugins/server.mdx index 1a1307c1e7c8..2455e5580bdf 100644 --- a/services/site/src/docs/content/build/plugins/server.mdx +++ b/services/site/src/docs/content/build/plugins/server.mdx @@ -1488,8 +1488,9 @@ await ctx.session.hook( #### Model request -Modify model request settings and optionally scope the hook to one provider. The event carries the same `kind` -as the HTTP hooks below. +Modify model request settings and optionally scope the hook to one provider. Its `kind` is `"primary"`, +`"compaction"`, `"title"` or `"generate"`. It only runs for Session requests; to change the URL or headers of any model +call, use the [model HTTP hooks](#model-http-experimental). ```ts await ctx.session.hook( @@ -1503,7 +1504,7 @@ await ctx.session.hook( #### Native HTTP -`http.request` and `http.response` are deprecated. Use the [model HTTP hooks](#models-experimental), which run for +`http.request` and `http.response` are deprecated. Use the [model HTTP hooks](#model-http-experimental), which run for the same requests and for calls made outside a Session. The session hooks still work: each one is registered as a model hook that skips calls without a Session, so both kinds run in plugin order. @@ -1689,7 +1690,7 @@ interface SessionHookContext { } ``` -### Models (experimental) +### Model HTTP (experimental) Model HTTP hooks run for every HTTP request to a model provider, whichever Session or API makes it: Session steps, compaction, titles and cache warming, and [Generate](#generate-experimental) text, image and decision calls. Use them to @@ -1698,7 +1699,8 @@ streams; clone or replace a body before reading it. WebSocket traffic doesn't pa [Native WebSocket](#native-websocket-experimental). `event.kind` says why the call was made: `"primary"`, `"compaction"`, `"title"` or `"generate"` for Session requests, -and `"text"`, `"image"` or `"decision"` for Generate. `event.session` is set exactly when a Session made the call. +and `"text"`, `"image"` or `"decision"` for Generate. `event.session` is set for a Session's own model requests. A +tool that calls Generate from inside a Session, like the built-in image tool, makes a Generate call with no `session`. Generate calls made through the HTTP API run in the global config location, so only globally configured plugins see them. @@ -1731,7 +1733,7 @@ interface ModelHookContext { ): Promise } -type ModelRequestScope = { model: { providerID: string; id: string } } & ( +type ModelRequestScope = { model: { providerID: string; id: string; variant?: string } } & ( | { kind: "primary" | "compaction" | "title" | "generate"; session: { id: string; agent: string } } | { kind: "text" | "image" | "decision"; session?: undefined } ) From 71a220e0c6556b38086f80674699b6ee64a27ae5 Mon Sep 17 00:00:00 2001 From: Aiden Cline Date: Tue, 10 Nov 2026 19:30:49 -0600 Subject: [PATCH 4/7] refactor(core): move built-in provider plugins to model HTTP hooks --- packages/core/src/plugin/provider/azure.ts | 4 ++-- packages/core/src/plugin/provider/github-copilot.ts | 4 ++-- packages/core/src/plugin/provider/opencode.ts | 6 +++--- packages/core/src/plugin/provider/snowflake-cortex.ts | 8 ++++---- packages/core/test/plugin/provider-azure.test.ts | 10 ++++++++++ packages/plugin/src/effect/session.ts | 11 +++++------ packages/plugin/src/promise/session.ts | 11 +++++------ .../site/src/docs/content/build/plugins/effect.mdx | 8 ++++---- .../site/src/docs/content/build/plugins/server.mdx | 10 +++++----- 9 files changed, 40 insertions(+), 32 deletions(-) diff --git a/packages/core/src/plugin/provider/azure.ts b/packages/core/src/plugin/provider/azure.ts index cab1745a2cb7..cf3de9658aa3 100644 --- a/packages/core/src/plugin/provider/azure.ts +++ b/packages/core/src/plugin/provider/azure.ts @@ -444,8 +444,8 @@ export function make( const current = yield* token(scope).pipe(Effect.orDie) return `Bearer ${current.access}` }) - yield* ctx.session.hook( - "http.request", + yield* ctx.model.hook( + "experimental.http.request", (evt) => Effect.gen(function* () { const authorization = yield* bearer(evt.request.url) diff --git a/packages/core/src/plugin/provider/github-copilot.ts b/packages/core/src/plugin/provider/github-copilot.ts index 2cbe319c7ef3..8b6258bf3944 100644 --- a/packages/core/src/plugin/provider/github-copilot.ts +++ b/packages/core/src/plugin/provider/github-copilot.ts @@ -415,8 +415,8 @@ export const GithubCopilotPlugin = define({ }), { providerID: Provider.ID.githubCopilot }, ) - yield* ctx.session.hook( - "http.request", + yield* ctx.model.hook( + "experimental.http.request", (evt) => Effect.gen(function* () { // The Messages route sends the token as `x-api-key`, the OpenAI routes as a bearer token. diff --git a/packages/core/src/plugin/provider/opencode.ts b/packages/core/src/plugin/provider/opencode.ts index 159ece15cd7e..2a71e0e11fa9 100644 --- a/packages/core/src/plugin/provider/opencode.ts +++ b/packages/core/src/plugin/provider/opencode.ts @@ -2,7 +2,7 @@ import { isDeepStrictEqual } from "node:util" import { Duration, Effect, Equal, FiberHandle, Option, Schema, Scope, Semaphore, Stream } from "effect" import type { IntegrationOAuthMethodRegistration } from "@opencode/plugin/effect/integration" import { define } from "@opencode/plugin/effect/plugin" -import type { SessionHttpResponse } from "@opencode/plugin/effect/session" +import type { ModelHttpResponse } from "@opencode/plugin/effect/model" import { FetchHttpClient, HttpBody, @@ -536,7 +536,7 @@ export const OpencodePlugin = define< // Console inference rejects a missing SSO sign-in with a generic 401/403. Re-check the Console config, which // reports the reason, and replace the response with instructions when the connection needs the user. // A client retrying rejected inference would otherwise send one config request per failed response. - const explain = (event: SessionHttpResponse) => + const explain = (event: ModelHttpResponse) => Effect.gen(function* () { if (event.response.status !== 401 && event.response.status !== 403) return yield* check(Duration.seconds(30)) @@ -558,7 +558,7 @@ export const OpencodePlugin = define< yield* Effect.forEach(explainers, (registration) => registration.dispose, { discard: true }) explainers = yield* Effect.forEach( next.connection ? new Set([Provider.ID.opencode, ...Object.keys(next.remote?.providers ?? {})]) : [], - (providerID) => ctx.session.hook("http.response", explain, { providerID }).pipe(Scope.provide(scope)), + (providerID) => ctx.model.hook("experimental.http.response", explain, { providerID }).pipe(Scope.provide(scope)), ) }) yield* guard(snapshot) diff --git a/packages/core/src/plugin/provider/snowflake-cortex.ts b/packages/core/src/plugin/provider/snowflake-cortex.ts index 1745b87df122..b38658429754 100644 --- a/packages/core/src/plugin/provider/snowflake-cortex.ts +++ b/packages/core/src/plugin/provider/snowflake-cortex.ts @@ -201,8 +201,8 @@ export const SnowflakeCortexPlugin = define({ } }) yield* ProviderRefresh.onSwitch(integrationID, ProviderRefresh.reloadIfChanged(load, ctx.provider.reload())) - yield* ctx.session.hook( - "http.request", + yield* ctx.model.hook( + "experimental.http.request", (event) => Effect.sync(() => { // Model resolution already supplies and refreshes stored credentials on each attempt. @@ -212,8 +212,8 @@ export const SnowflakeCortexPlugin = define({ }), { providerID }, ) - yield* ctx.session.hook( - "http.response", + yield* ctx.model.hook( + "experimental.http.response", Effect.fn(function* (event) { if (event.response.status !== 400) return const error = Option.getOrUndefined(decodeError(yield* Effect.promise(() => event.response.clone().text()))) diff --git a/packages/core/test/plugin/provider-azure.test.ts b/packages/core/test/plugin/provider-azure.test.ts index c87422c0babf..140175cd97f0 100644 --- a/packages/core/test/plugin/provider-azure.test.ts +++ b/packages/core/test/plugin/provider-azure.test.ts @@ -626,6 +626,16 @@ describe("AzurePlugin requests", () => { expect(foundry.request.headers.get("authorization")).toBe("Bearer https://ai.azure.com/.default-token") expect(foundry.request.headers.has("x-api-key")).toBe(false) + // Generate calls have no Session and get the same token. + const generated = yield* hooks.trigger("model", "experimental.http.request", { + model: context.model, + kind: "text", + request: new Request("https://test-resource.openai.azure.com/openai/v1/responses"), + }) + expect(generated.request.headers.get("authorization")).toBe( + "Bearer https://cognitiveservices.azure.com/.default-token", + ) + const handshake = yield* hooks.trigger("session", "experimental.ws.handshake", { ...context, sessionID: Session.ID.make("ses_azure_ws"), diff --git a/packages/plugin/src/effect/session.ts b/packages/plugin/src/effect/session.ts index 28e935c5245d..ce6ebb8d3eb2 100644 --- a/packages/plugin/src/effect/session.ts +++ b/packages/plugin/src/effect/session.ts @@ -87,7 +87,7 @@ export interface SessionModelRequest { headers: Record } -/** @deprecated Use `ctx.model.hook("experimental.http.request")`, which also runs for calls made outside a Session. */ +/** Prefer `ctx.model.hook("experimental.http.request")`, which also runs for calls made outside a Session. */ export interface SessionHttpRequest { readonly sessionID: Session.ID readonly agent: Agent.ID @@ -96,7 +96,7 @@ export interface SessionHttpRequest { request: Request } -/** @deprecated Use `ctx.model.hook("experimental.http.response")`, which also runs for calls made outside a Session. */ +/** Prefer `ctx.model.hook("experimental.http.response")`, which also runs for calls made outside a Session. */ export interface SessionHttpResponse { readonly sessionID: Session.ID readonly agent: Agent.ID @@ -207,14 +207,13 @@ export interface SessionHooks { readonly "model.request": SessionModelRequest /** * Runs for HTTP requests a Session makes. Registered as a `ctx.model.hook("experimental.http.request")` that skips - * calls without a Session. - * @deprecated Use `ctx.model.hook("experimental.http.request")` and read `event.session`. + * calls without a Session. Prefer the model hook, which also sees Generate calls; `event.session` holds the Session. */ readonly "http.request": SessionHttpRequest /** * Runs for HTTP responses to a Session's requests. Registered as a `ctx.model.hook("experimental.http.response")` - * that skips calls without a Session. - * @deprecated Use `ctx.model.hook("experimental.http.response")` and read `event.session`. + * that skips calls without a Session. Prefer the model hook, which also sees Generate calls; `event.session` holds the + * Session. */ readonly "http.response": SessionHttpResponse readonly "experimental.ws.handshake": SessionWebSocketHandshake diff --git a/packages/plugin/src/promise/session.ts b/packages/plugin/src/promise/session.ts index 2196ccd049a5..9c53dd3b9aea 100644 --- a/packages/plugin/src/promise/session.ts +++ b/packages/plugin/src/promise/session.ts @@ -87,7 +87,7 @@ export interface SessionModelRequest { headers: Record } -/** @deprecated Use `ctx.model.hook("experimental.http.request")`, which also runs for calls made outside a Session. */ +/** Prefer `ctx.model.hook("experimental.http.request")`, which also runs for calls made outside a Session. */ export interface SessionHttpRequest { readonly sessionID: Session.ID readonly agent: Agent.ID @@ -96,7 +96,7 @@ export interface SessionHttpRequest { request: Request } -/** @deprecated Use `ctx.model.hook("experimental.http.response")`, which also runs for calls made outside a Session. */ +/** Prefer `ctx.model.hook("experimental.http.response")`, which also runs for calls made outside a Session. */ export interface SessionHttpResponse { readonly sessionID: Session.ID readonly agent: Agent.ID @@ -207,14 +207,13 @@ export interface SessionHooks { readonly "model.request": SessionModelRequest /** * Runs for HTTP requests a Session makes. Registered as a `ctx.model.hook("experimental.http.request")` that skips - * calls without a Session. - * @deprecated Use `ctx.model.hook("experimental.http.request")` and read `event.session`. + * calls without a Session. Prefer the model hook, which also sees Generate calls; `event.session` holds the Session. */ readonly "http.request": SessionHttpRequest /** * Runs for HTTP responses to a Session's requests. Registered as a `ctx.model.hook("experimental.http.response")` - * that skips calls without a Session. - * @deprecated Use `ctx.model.hook("experimental.http.response")` and read `event.session`. + * that skips calls without a Session. Prefer the model hook, which also sees Generate calls; `event.session` holds the + * Session. */ readonly "http.response": SessionHttpResponse readonly "experimental.ws.handshake": SessionWebSocketHandshake diff --git a/services/site/src/docs/content/build/plugins/effect.mdx b/services/site/src/docs/content/build/plugins/effect.mdx index f5f6fd988f6b..0ead3c9b0313 100644 --- a/services/site/src/docs/content/build/plugins/effect.mdx +++ b/services/site/src/docs/content/build/plugins/effect.mdx @@ -1310,8 +1310,8 @@ effect: (ctx) => Modify native provider requests or responses with the experimental model HTTP hooks. They run for every HTTP request to a model provider, including Generate text, image and decision calls made outside a Session. Bodies are one-shot streams; clone or replace a body before reading it. `event.kind` says why the call was made, and `event.session` is set -for a Session's own model requests. The session `http.request` and `http.response` hooks are deprecated; they still run, as -model hooks that skip calls without a Session. +for a Session's own model requests. The session `http.request` and `http.response` hooks still +work, as model hooks that skip calls without a Session. ```ts effect: (ctx) => @@ -1412,9 +1412,9 @@ interface SessionHooks { readonly generate: SessionGenerate readonly title: SessionTitle readonly "model.request": SessionModelRequest - /** @deprecated Use ctx.model.hook("experimental.http.request") */ + /** Session calls only. Prefer ctx.model.hook("experimental.http.request") */ readonly "http.request": SessionHttpRequest - /** @deprecated Use ctx.model.hook("experimental.http.response") */ + /** Session calls only. Prefer ctx.model.hook("experimental.http.response") */ readonly "http.response": SessionHttpResponse readonly "experimental.ws.handshake": SessionWebSocketHandshake readonly "experimental.ws.send": SessionWebSocketSend diff --git a/services/site/src/docs/content/build/plugins/server.mdx b/services/site/src/docs/content/build/plugins/server.mdx index 2455e5580bdf..819ac121b8bd 100644 --- a/services/site/src/docs/content/build/plugins/server.mdx +++ b/services/site/src/docs/content/build/plugins/server.mdx @@ -1504,9 +1504,9 @@ await ctx.session.hook( #### Native HTTP -`http.request` and `http.response` are deprecated. Use the [model HTTP hooks](#model-http-experimental), which run for -the same requests and for calls made outside a Session. The session hooks still work: each one is registered as a -model hook that skips calls without a Session, so both kinds run in plugin order. +Prefer the [model HTTP hooks](#model-http-experimental), which run for the same requests and for calls made outside a +Session. `ctx.session.hook("http.request")` and `"http.response"` still work: each one is registered as a model hook +that skips calls without a Session, so both kinds run in plugin order. #### Native WebSocket (experimental) @@ -1599,9 +1599,9 @@ interface SessionHooks { title: SessionRequestHook & { result?: string } "experimental.model.resolve": SessionModelResolveHook "model.request": SessionModelRequestHook - /** @deprecated Use ctx.model.hook("experimental.http.request") */ + /** Session calls only. Prefer ctx.model.hook("experimental.http.request") */ "http.request": SessionHttpRequestHook - /** @deprecated Use ctx.model.hook("experimental.http.response") */ + /** Session calls only. Prefer ctx.model.hook("experimental.http.response") */ "http.response": SessionHttpResponseHook "experimental.ws.handshake": SessionWebSocketHandshakeHook "experimental.ws.send": SessionWebSocketSendHook From 24bd1663a7a6509c0f737c7e7b34487a5a17b568 Mon Sep 17 00:00:00 2001 From: Aiden Cline Date: Wed, 11 Nov 2026 15:19:57 -0600 Subject: [PATCH 5/7] refactor(core): run session HTTP hooks inside model HTTP hooks --- packages/core/src/model-http.ts | 26 +++++-- packages/core/src/plugin/hooks.ts | 70 +++---------------- packages/plugin/src/effect/session.ts | 9 ++- packages/plugin/src/promise/session.ts | 9 ++- .../src/docs/content/build/plugins/effect.mdx | 2 +- .../src/docs/content/build/plugins/server.mdx | 4 +- 6 files changed, 41 insertions(+), 79 deletions(-) diff --git a/packages/core/src/model-http.ts b/packages/core/src/model-http.ts index 3d55cc666ce7..248e6eaa7b54 100644 --- a/packages/core/src/model-http.ts +++ b/packages/core/src/model-http.ts @@ -7,19 +7,32 @@ import { HttpClientRequest, HttpClientResponse } from "effect/http" import type { PluginHooks } from "./plugin/hooks.js" /** - * Per-call middleware that runs the model `experimental.http.*` hooks, which include the session `http.*` hooks. - * Undefined when no hook applies. + * Per-call middleware that runs the model `experimental.http.*` hooks, and the session `http.*` hooks when a Session + * makes the request. Model hooks wrap session hooks. Undefined when no hook applies. */ export const middleware = Effect.fnUntraced(function* (hooks: PluginHooks.Interface, scope: ModelRequestScope) { const providerID = scope.model.providerID + // The session hooks' own event shape, for requests a Session makes. + const session = scope.session && { + sessionID: scope.session.id, + agent: scope.session.agent, + model: scope.model, + kind: scope.kind, + } const any = (yield* hooks.has("model", "experimental.http.request", providerID)) || - (yield* hooks.has("model", "experimental.http.response", providerID)) + (yield* hooks.has("model", "experimental.http.response", providerID)) || + (session !== undefined && + ((yield* hooks.has("session", "http.request", providerID)) || + (yield* hooks.has("session", "http.response", providerID)))) if (!any) return undefined const http: HttpMiddleware = (req, handler) => Effect.gen(function* () { const request = yield* HttpClientRequest.toWeb(req) - const before = yield* hooks.trigger("model", "experimental.http.request", { ...scope, request }) + const outer = yield* hooks.trigger("model", "experimental.http.request", { ...scope, request }) + const before = session + ? yield* hooks.trigger("session", "http.request", { ...session, request: outer.request }) + : outer // A hook that kept the request object cannot have replaced its body, so the original body is sent as is. // Reading it back would hold a second full copy of the request, screenshots included, for the whole call. const sent = @@ -37,10 +50,13 @@ export const middleware = Effect.fnUntraced(function* (hooks: PluginHooks.Interf [204, 205, 304].includes(res.status) ? null : yield* Stream.toReadableStreamEffect(res.stream), { status: res.status, headers: res.headers }, ) + const inner = session + ? yield* hooks.trigger("session", "http.response", { ...session, request: before.request, response }) + : { response } const after = yield* hooks.trigger("model", "experimental.http.response", { ...scope, request: before.request, - response, + response: inner.response, }) return HttpClientResponse.fromWeb(sent, after.response) }) diff --git a/packages/core/src/plugin/hooks.ts b/packages/core/src/plugin/hooks.ts index f67f03ea8e8f..783aefdadb3f 100644 --- a/packages/core/src/plugin/hooks.ts +++ b/packages/core/src/plugin/hooks.ts @@ -1,8 +1,8 @@ export * as PluginHooks from "./hooks.js" import type { AISDKHooks } from "@opencode/plugin/effect/aisdk" -import type { ModelHttpRequest, ModelHttpResponse, ModelRequestHooks } from "@opencode/plugin/effect/model" -import type { SessionHooks, SessionHttpRequest, SessionHttpResponse } from "@opencode/plugin/effect/session" +import type { ModelRequestHooks } from "@opencode/plugin/effect/model" +import type { SessionHooks } from "@opencode/plugin/effect/session" import type { ShellHooks } from "@opencode/plugin/effect/shell" import type { ToolFailures, ToolHooks } from "@opencode/plugin/effect/tool" import type { ModelHookOptions } from "@opencode/plugin/effect/registration" @@ -42,17 +42,10 @@ const eventProviderID = (event: unknown) => { return typeof model.providerID === "string" ? model.providerID : undefined } -type Name = keyof Domains[Domain] & keyof Failures[Domain] -// The deprecated session HTTP hooks register into the model HTTP hooks, so only the model names are triggered. -type Triggered = Exclude< - Name, - Domain extends "session" ? "http.request" | "http.response" : never -> - export interface Interface { readonly has: ( domain: Domain, - name: Triggered, + name: keyof Domains[Domain] & keyof Failures[Domain], providerID?: string, ) => Effect.Effect readonly register: ( @@ -61,11 +54,11 @@ export interface Interface { callback: Callback, options?: ModelHookOptions, ) => Effect.Effect - readonly trigger: >( + readonly trigger: ( domain: Domain, - name: Hook, - event: Domains[Domain][Hook], - ) => Effect.Effect + name: Name, + event: Domains[Domain][Name], + ) => Effect.Effect } export class Service extends Context.Service()("@opencode/PluginHooks") {} @@ -79,16 +72,9 @@ const layer = Layer.effect( const register: Interface["register"] = Effect.fn("PluginHooks.register")( function* (domain, name, callback, options) { const scope = yield* Scope.Scope - // The session HTTP hooks are model HTTP hooks that skip calls made outside a Session. - const legacy = - domain === "session" && name === "http.request" - ? sessionHttp.request - : domain === "session" && name === "http.response" - ? sessionHttp.response - : undefined - const id = legacy ? legacy.id : key(domain, name) + const id = key(domain, name) let active = true - const entry = { callback: legacy ? legacy.adapt(callback) : callback, options } + const entry = { callback, options } callbacks.set(id, [...(callbacks.get(id) ?? []), entry]) const dispose = Effect.sync(() => { if (!active) return @@ -122,42 +108,4 @@ const layer = Layer.effect( }), ) -const sessionHttp = { - request: { id: "model.experimental.http.request", adapt: sessionRequest }, - response: { id: "model.experimental.http.response", adapt: sessionResponse }, -} - -function sessionRequest(callback: Function) { - return (event: ModelHttpRequest): Effect.Effect => { - if (event.session === undefined) return Effect.void - const legacy: SessionHttpRequest = { - sessionID: event.session.id, - agent: event.session.agent, - model: event.model, - kind: event.kind, - request: event.request, - } - return Effect.map(callback(legacy), () => { - event.request = legacy.request - }) - } -} - -function sessionResponse(callback: Function) { - return (event: ModelHttpResponse): Effect.Effect => { - if (event.session === undefined) return Effect.void - const legacy: SessionHttpResponse = { - sessionID: event.session.id, - agent: event.session.agent, - model: event.model, - kind: event.kind, - request: event.request, - response: event.response, - } - return Effect.map(callback(legacy), () => { - event.response = legacy.response - }) - } -} - export const node = makeLocationNode({ service: Service, layer, deps: [] }) diff --git a/packages/plugin/src/effect/session.ts b/packages/plugin/src/effect/session.ts index ce6ebb8d3eb2..c3db2731901d 100644 --- a/packages/plugin/src/effect/session.ts +++ b/packages/plugin/src/effect/session.ts @@ -206,14 +206,13 @@ export interface SessionHooks { readonly "experimental.model.resolve": SessionModelResolve readonly "model.request": SessionModelRequest /** - * Runs for HTTP requests a Session makes. Registered as a `ctx.model.hook("experimental.http.request")` that skips - * calls without a Session. Prefer the model hook, which also sees Generate calls; `event.session` holds the Session. + * Runs for HTTP requests a Session makes, inside `ctx.model.hook("experimental.http.request")`. Prefer the model hook, + * which also sees Generate calls; `event.session` holds the Session. */ readonly "http.request": SessionHttpRequest /** - * Runs for HTTP responses to a Session's requests. Registered as a `ctx.model.hook("experimental.http.response")` - * that skips calls without a Session. Prefer the model hook, which also sees Generate calls; `event.session` holds the - * Session. + * Runs for HTTP responses to a Session's requests, before `ctx.model.hook("experimental.http.response")`. Prefer the + * model hook, which also sees Generate calls; `event.session` holds the Session. */ readonly "http.response": SessionHttpResponse readonly "experimental.ws.handshake": SessionWebSocketHandshake diff --git a/packages/plugin/src/promise/session.ts b/packages/plugin/src/promise/session.ts index 9c53dd3b9aea..f460bf5021fd 100644 --- a/packages/plugin/src/promise/session.ts +++ b/packages/plugin/src/promise/session.ts @@ -206,14 +206,13 @@ export interface SessionHooks { readonly "experimental.model.resolve": SessionModelResolve readonly "model.request": SessionModelRequest /** - * Runs for HTTP requests a Session makes. Registered as a `ctx.model.hook("experimental.http.request")` that skips - * calls without a Session. Prefer the model hook, which also sees Generate calls; `event.session` holds the Session. + * Runs for HTTP requests a Session makes, inside `ctx.model.hook("experimental.http.request")`. Prefer the model hook, + * which also sees Generate calls; `event.session` holds the Session. */ readonly "http.request": SessionHttpRequest /** - * Runs for HTTP responses to a Session's requests. Registered as a `ctx.model.hook("experimental.http.response")` - * that skips calls without a Session. Prefer the model hook, which also sees Generate calls; `event.session` holds the - * Session. + * Runs for HTTP responses to a Session's requests, before `ctx.model.hook("experimental.http.response")`. Prefer the + * model hook, which also sees Generate calls; `event.session` holds the Session. */ readonly "http.response": SessionHttpResponse readonly "experimental.ws.handshake": SessionWebSocketHandshake diff --git a/services/site/src/docs/content/build/plugins/effect.mdx b/services/site/src/docs/content/build/plugins/effect.mdx index 0ead3c9b0313..bc998e589ff4 100644 --- a/services/site/src/docs/content/build/plugins/effect.mdx +++ b/services/site/src/docs/content/build/plugins/effect.mdx @@ -1311,7 +1311,7 @@ Modify native provider requests or responses with the experimental model HTTP ho to a model provider, including Generate text, image and decision calls made outside a Session. Bodies are one-shot streams; clone or replace a body before reading it. `event.kind` says why the call was made, and `event.session` is set for a Session's own model requests. The session `http.request` and `http.response` hooks still -work, as model hooks that skip calls without a Session. +work for Session requests, inside the model hooks. ```ts effect: (ctx) => diff --git a/services/site/src/docs/content/build/plugins/server.mdx b/services/site/src/docs/content/build/plugins/server.mdx index 819ac121b8bd..8e5338ebfcae 100644 --- a/services/site/src/docs/content/build/plugins/server.mdx +++ b/services/site/src/docs/content/build/plugins/server.mdx @@ -1505,8 +1505,8 @@ await ctx.session.hook( #### Native HTTP Prefer the [model HTTP hooks](#model-http-experimental), which run for the same requests and for calls made outside a -Session. `ctx.session.hook("http.request")` and `"http.response"` still work: each one is registered as a model hook -that skips calls without a Session, so both kinds run in plugin order. +Session. `ctx.session.hook("http.request")` and `"http.response"` still work for Session requests. The model hooks wrap +them: a model request hook runs before the session one, and a model response hook runs after it. #### Native WebSocket (experimental) From 428c244523a41e55ec423df538e5f4e7eed22649 Mon Sep 17 00:00:00 2001 From: Aiden Cline Date: Thu, 12 Nov 2026 22:39:05 -0600 Subject: [PATCH 6/7] refactor: pass model HTTP hooks to image and decision clients per call --- packages/ai/src/decision-client.ts | 13 +++-- packages/ai/src/media-client.ts | 49 ++++++++++++------- packages/ai/src/route/executor.ts | 18 ++++--- packages/core/src/generate.ts | 20 ++++---- packages/core/src/model-http.ts | 4 +- packages/core/test/generate.test.ts | 42 +++++++--------- .../test/session-model-request-hooks.test.ts | 18 ++++++- 7 files changed, 97 insertions(+), 67 deletions(-) diff --git a/packages/ai/src/decision-client.ts b/packages/ai/src/decision-client.ts index 188038f5f833..2b83ea3f4ba2 100644 --- a/packages/ai/src/decision-client.ts +++ b/packages/ai/src/decision-client.ts @@ -13,9 +13,15 @@ import { AIError, InvalidProviderOutputError } from "./schema/index.js" export type Execute = RequestExecutor.Interface["execute"] +/** Per-call options. `http` wraps every HTTP request of the call. */ +export interface CallOptions { + readonly http?: RequestExecutor.HttpMiddleware +} + export interface Interface { readonly generate: ( request: DecisionRequest, Questions>, + options?: CallOptions, ) => Effect.Effect, AIError> } @@ -23,17 +29,18 @@ export class Service extends Context.Service()("@opencode/AI export const generate = ( request: DecisionRequest, Questions>, + options?: CallOptions, ): Effect.Effect, AIError, Service> => - Effect.flatMap(Service, (client) => client.generate(request)) + Effect.flatMap(Service, (client) => client.generate(request, options)) export const layer: Layer.Layer = Layer.effect( Service, Effect.gen(function* () { const executor = yield* RequestExecutor.Service return Service.of({ - generate: Effect.fnUntraced(function* (request) { + generate: Effect.fnUntraced(function* (request, options) { const route = request.model.route - const response = yield* route.generate(request, executor.execute) + const response = yield* route.generate(request, RequestExecutor.withHttp(executor, options?.http)) if (answersMatch(request.questions, response.answers)) return response as DecisionResponseFor return yield* new AIError({ diff --git a/packages/ai/src/media-client.ts b/packages/ai/src/media-client.ts index 622bfa7fdbad..49414300fe0d 100644 --- a/packages/ai/src/media-client.ts +++ b/packages/ai/src/media-client.ts @@ -1,6 +1,6 @@ import { type Context, Effect, Layer, Stream } from "effect" import { resultEvents, type AwaitOptions, type Generation, type Observation } from "./generation.js" -import { RequestExecutor } from "./route/executor.js" +import { RequestExecutor, type HttpMiddleware } from "./route/executor.js" import type { MediaRoute } from "./route/media.js" import { AIError, UnsupportedOperationError } from "./schema/index.js" @@ -9,12 +9,21 @@ export interface RoutedRequest } } +/** Per-call options. `http` wraps every HTTP request of the call, polling included. */ +export interface CallOptions extends AwaitOptions { + readonly http?: HttpMiddleware +} + /** `start` and `resume` fail with `UnsupportedOperation` on inline and stream routes. */ export interface Interface, Event, Response> { - readonly generate: (request: Req, options?: AwaitOptions) => Effect.Effect - readonly stream: (request: Req, options?: AwaitOptions) => Stream.Stream - readonly start: (request: Req) => Effect.Effect, AIError> - readonly resume: (model: Req["model"], token: unknown) => Effect.Effect, AIError> + readonly generate: (request: Req, options?: CallOptions) => Effect.Effect + readonly stream: (request: Req, options?: CallOptions) => Stream.Stream + readonly start: (request: Req, options?: Pick) => Effect.Effect, AIError> + readonly resume: ( + model: Req["model"], + token: unknown, + options?: Pick, + ) => Effect.Effect, AIError> } /** One modality's layer and service accessors, dispatching each request on its route's `kind`. */ @@ -31,6 +40,7 @@ export const make = , Even service, Effect.gen(function* () { const executor = yield* RequestExecutor.Service + const execute = (options: Pick | undefined) => RequestExecutor.withHttp(executor, options?.http) const notQueued = (route: MediaRoute.AnyRoute, operation: string) => new AIError({ reason: new UnsupportedOperationError({ @@ -40,39 +50,42 @@ export const make = , Even message: `${route.provider}/${route.id} is not a queued route; use generate or stream`, }), }) - const start = (request: Req) => { + const start = (request: Req, options?: Pick) => { const route = request.model.route if (route.kind !== "queued") return Effect.fail(notQueued(route, "start")) - return route.start(request, executor.execute) + return route.start(request, execute(options)) } return service.of({ start, - resume: (model, token) => { + resume: (model, token, options) => { if (model.route.kind !== "queued") return Effect.fail(notQueued(model.route, "resume")) - return model.route.resume(model, token, executor.execute) + return model.route.resume(model, token, execute(options)) }, generate: (request, options) => { const route = request.model.route - if (route.kind !== "queued") return route.generate(request, executor.execute) - return start(request).pipe(Effect.flatMap((generation) => generation.await(options))) + if (route.kind !== "queued") return route.generate(request, execute(options)) + return start(request, options).pipe(Effect.flatMap((generation) => generation.await(options))) }, stream: (request, options) => { const route = request.model.route - if (route.kind === "stream") return route.stream(request, executor.execute) + if (route.kind === "stream") return route.stream(request, execute(options)) if (route.kind === "queued") return Stream.unwrap( - start(request).pipe(Effect.map((generation) => resultEvents(generation, input.responseEvents, options))), + start(request, options).pipe( + Effect.map((generation) => resultEvents(generation, input.responseEvents, options)), + ), ) - return Stream.fromIterableEffect(Effect.map(route.generate(request, executor.execute), input.responseEvents)) + return Stream.fromIterableEffect(Effect.map(route.generate(request, execute(options)), input.responseEvents)) }, }) }), ), - generate: (request: Req, options?: AwaitOptions) => service.use((client) => client.generate(request, options)), - stream: (request: Req, options?: AwaitOptions) => + generate: (request: Req, options?: CallOptions) => service.use((client) => client.generate(request, options)), + stream: (request: Req, options?: CallOptions) => Stream.unwrap(service.useSync((client) => client.stream(request, options))), - start: (request: Req) => service.use((client) => client.start(request)), - resume: (model: Req["model"], token: unknown) => service.use((client) => client.resume(model, token)), + start: (request: Req, options?: Pick) => service.use((client) => client.start(request, options)), + resume: (model: Req["model"], token: unknown, options?: Pick) => + service.use((client) => client.resume(model, token, options)), }) export * as MediaClient from "./media-client.js" diff --git a/packages/ai/src/route/executor.ts b/packages/ai/src/route/executor.ts index 11082ef4e815..84e651493e86 100644 --- a/packages/ai/src/route/executor.ts +++ b/packages/ai/src/route/executor.ts @@ -270,19 +270,23 @@ export const withFetch = ( return middleware === undefined ? send : (request) => middleware(request, send) } +/** `executor.execute` with `fn` run on every request, outside the middleware each request passes. */ +export const withHttp = (executor: Interface, fn: HttpMiddleware | undefined): Interface["execute"] => + fn === undefined + ? executor.execute + : (request, next) => + executor.execute( + request, + next === undefined ? fn : (input, handler) => fn(input, (forwarded) => next(forwarded, handler)), + ) + /** Run `fn` on every request: it sees the raw response before status classification, inside middleware already on `executor`, and outside per-call middleware. */ export const middleware = (fn: HttpMiddleware, executor: Layer.Layer = fetchLayer): Layer.Layer => Layer.effect( Service, Effect.gen(function* () { const inner = yield* Service - return Service.of({ - execute: (request, next) => - inner.execute( - request, - next === undefined ? fn : (input, handler) => fn(input, (forwarded) => next(forwarded, handler)), - ), - }) + return Service.of({ execute: withHttp(inner, fn) }) }), ).pipe(Layer.provide(executor)) diff --git a/packages/core/src/generate.ts b/packages/core/src/generate.ts index c4810864cbb6..9fad85c2652a 100644 --- a/packages/core/src/generate.ts +++ b/packages/core/src/generate.ts @@ -5,7 +5,7 @@ import type { DecisionRequest, DecisionResult, ImageRequest, ImageResult } from import { Money } from "@opencode/schema/money" import { SessionID } from "@opencode/schema/session-id" import { Context, Effect, Layer, Schema } from "effect" -import { RequestExecutor, type HttpMiddleware } from "@opencode/ai/route" +import { RequestExecutor } from "@opencode/ai/route" import { makeLocationNode } from "@opencode/util/effect/app-node" import { llmClient, requestExecutor } from "./effect/app-node-platform.js" import { Integration } from "./integration.js" @@ -91,9 +91,6 @@ export const layer = Layer.effect( const hooks = yield* PluginHooks.Service const images = yield* ImageClient.Service const decisionClient = yield* DecisionClient.Service - // With model HTTP hooks, the call gets a fresh client (not the memoized one) on an executor that runs them. - const hooked = (http: HttpMiddleware) => - RequestExecutor.middleware(http, Layer.succeed(RequestExecutor.Service, executor)) const runText = Effect.fn("Generate.text")(function* (input: TextInput) { const resolved = yield* resolver.resolve(input.model).pipe( @@ -126,7 +123,7 @@ export const layer = Layer.effect( // Gateways require session attribution even for a stateless call; no Session is stored. headers: { "x-opencode-session": SessionID.create() }, }), - http === undefined ? undefined : { http }, + { http }, ) .pipe( ModelRetry.retryOneShot, @@ -169,9 +166,10 @@ export const layer = Layer.effect( aspect: input.aspect, resolution: input.resolution, }).pipe( - http === undefined - ? Effect.provideService(ImageClient.Service, images) - : Effect.provide(Layer.fresh(ImageClient.layer).pipe(Layer.provide(hooked(http)))), + Effect.provideService(ImageClient.Service, { + ...images, + generate: (request, options) => images.generate(request, { ...options, http }), + }), ModelRetry.retryOneShot, Effect.mapError((error) => providerError(input.model, error)), ) @@ -211,9 +209,9 @@ export const layer = Layer.effect( ), questions: input.questions, }).pipe( - http === undefined - ? Effect.provideService(DecisionClient.Service, decisionClient) - : Effect.provide(Layer.fresh(DecisionClient.layer).pipe(Layer.provide(hooked(http)))), + Effect.provideService(DecisionClient.Service, { + generate: (request) => decisionClient.generate(request, { http }), + }), ModelRetry.retryOneShot, Effect.mapError((error) => providerError(input.model, error)), ) diff --git a/packages/core/src/model-http.ts b/packages/core/src/model-http.ts index 248e6eaa7b54..44f65c7e9ab1 100644 --- a/packages/core/src/model-http.ts +++ b/packages/core/src/model-http.ts @@ -19,13 +19,13 @@ export const middleware = Effect.fnUntraced(function* (hooks: PluginHooks.Interf model: scope.model, kind: scope.kind, } - const any = + const hasHooks = (yield* hooks.has("model", "experimental.http.request", providerID)) || (yield* hooks.has("model", "experimental.http.response", providerID)) || (session !== undefined && ((yield* hooks.has("session", "http.request", providerID)) || (yield* hooks.has("session", "http.response", providerID)))) - if (!any) return undefined + if (!hasHooks) return undefined const http: HttpMiddleware = (req, handler) => Effect.gen(function* () { const request = yield* HttpClientRequest.toWeb(req) diff --git a/packages/core/test/generate.test.ts b/packages/core/test/generate.test.ts index 38b28d0d6f17..30f8b4b572bc 100644 --- a/packages/core/test/generate.test.ts +++ b/packages/core/test/generate.test.ts @@ -26,6 +26,7 @@ import { ID, Info, Model, Ref, VariantID } from "@opencode/core/model" import { Provider } from "@opencode/core/provider" import { Variant } from "@opencode/core/variant" import { Money } from "@opencode/schema/money" +import { LayerNode } from "@opencode/util/effect/layer-node" import { Npm } from "@opencode/util/npm" import { Effect, Exit, Fiber, Layer } from "effect" import { TestClock } from "effect/testing" @@ -595,30 +596,28 @@ describe("image and decision generation", () => { }), ) - // Records each model HTTP hook call and tags the request, so the provider sees which calls were hooked. - const hooked: string[] = [] - const recording = Layer.mock(PluginHooks.Service, { - has: () => Effect.succeed(true), - trigger: (_domain, name, event) => - Effect.sync(() => { - record(String(name), event) - return event - }), - }) - const record = (name: string, event: unknown) => { - if (!(event instanceof Object) || !("kind" in event)) return - hooked.push(`${name}:${String(event.kind)}`) - if (name === "experimental.http.request" && "request" in event && event.request instanceof Request) - event.request.headers.set("x-hook", "1") - } const hookedIt = testEffect( - Generate.layer.pipe(Layer.provide(Layer.mergeAll(mediaResolver, client, mediaModels, recording, executor))), + Generate.layer.pipe( + Layer.provideMerge( + Layer.mergeAll(mediaResolver, client, mediaModels, LayerNode.compile(PluginHooks.node), executor), + ), + ), ) hookedIt.effect("runs model HTTP hooks on image and decision provider requests, but not image downloads", () => Effect.gen(function* () { requests.length = 0 - hooked.length = 0 + const hooked: string[] = [] + const hooks = yield* PluginHooks.Service + yield* hooks.register("model", "experimental.http.request", (event) => + Effect.sync(() => { + hooked.push(`request:${event.kind}`) + event.request.headers.set("x-hook", "1") + }), + ) + yield* hooks.register("model", "experimental.http.response", (event) => + Effect.sync(() => void hooked.push(`response:${event.kind}`)), + ) const generate = yield* Generate.Service yield* generate.image({ model: ref("zai", "glm-image"), prompt: "A fox" }) yield* generate.decisions({ @@ -626,12 +625,7 @@ describe("image and decision generation", () => { input: [{ type: "text", text: "Is this a photo?" }], questions: [{ type: "predicate", name: "photo", instructions: "Is this a photo?" }], }) - expect(hooked).toEqual([ - "experimental.http.request:image", - "experimental.http.response:image", - "experimental.http.request:decision", - "experimental.http.response:decision", - ]) + expect(hooked).toEqual(["request:image", "response:image", "request:decision", "response:decision"]) expect(requests.map((request) => [request.url, request.headers["x-hook"] ?? "-"])).toEqual([ ["https://api.z.ai/api/paas/v4/images/generations", "1"], ["https://images.example/fox", "-"], diff --git a/packages/core/test/session-model-request-hooks.test.ts b/packages/core/test/session-model-request-hooks.test.ts index 3ce116e4a929..7c59e971b74a 100644 --- a/packages/core/test/session-model-request-hooks.test.ts +++ b/packages/core/test/session-model-request-hooks.test.ts @@ -4,6 +4,7 @@ import { OpenAIChat } from "@opencode/ai/protocols" import { Agent } from "@opencode/schema/agent" import { Money } from "@opencode/schema/money" import { Session } from "@opencode/schema/session" +import type { ModelRequestScope } from "@opencode/plugin/effect/model" import type { SessionRequestKind } from "@opencode/plugin/effect/session" import { Location } from "@opencode/core/location" import { ModelHttp } from "@opencode/core/model-http" @@ -256,8 +257,14 @@ describe("model HTTP hooks", () => { seen.push(`session:${event.kind}:${event.sessionID}:${event.request.headers.get("x-model-hook")}`) }), ) + yield* hooks.register("session", "http.response", (event) => + Effect.sync(() => void seen.push(`session response:${event.kind}`)), + ) + yield* hooks.register("model", "experimental.http.response", (event) => + Effect.sync(() => void seen.push(`model response:${event.kind}`)), + ) const sent: string[] = [] - const send = (scope: Parameters[1]) => + const send = (scope: ModelRequestScope) => Effect.gen(function* () { const http = yield* ModelHttp.middleware(hooks, scope) if (!http) throw new Error("Expected HTTP middleware") @@ -276,7 +283,14 @@ describe("model HTTP hooks", () => { session: { id: session.id, agent: Agent.ID.make("build") }, }) - expect(seen).toEqual(["model:text:-", "model:primary:ses_hook_kind", "session:primary:ses_hook_kind:1"]) + expect(seen).toEqual([ + "model:text:-", + "model response:text", + "model:primary:ses_hook_kind", + "session:primary:ses_hook_kind:1", + "session response:primary", + "model response:primary", + ]) expect(sent).toEqual(["1", "1"]) }), ) From 45e2af3d9ed39a2638f4311af06d2c795907fdb5 Mon Sep 17 00:00:00 2001 From: Aiden Cline Date: Tue, 17 Nov 2026 14:35:12 -0600 Subject: [PATCH 7/7] docs: wrap model HTTP hook kinds --- services/site/src/docs/content/build/plugins/server.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/services/site/src/docs/content/build/plugins/server.mdx b/services/site/src/docs/content/build/plugins/server.mdx index b4567edb1ddf..6964009dd946 100644 --- a/services/site/src/docs/content/build/plugins/server.mdx +++ b/services/site/src/docs/content/build/plugins/server.mdx @@ -1735,8 +1735,9 @@ through them; see [Native WebSocket](#native-websocket-experimental). - A hook that fails fails the request. `event.kind` says why the call was made: `"primary"`, `"compaction"`, `"title"` or `"generate"` for Session requests, -`"text"`, `"image"`, `"decision"` or `"video"` for Generate, and `"voice"` for voice sessions. `event.session` is set for a Session's own model requests. A -tool that calls Generate from inside a Session, like the built-in image tool, makes a Generate call with no `session`. +`"text"`, `"image"`, `"decision"` or `"video"` for Generate, and `"voice"` for voice sessions. `event.session` is set +for a Session's own model requests. A tool that calls Generate from inside a Session, like the built-in image tool, +makes a Generate call with no `session`. Generate calls made through the HTTP API run in the global config location, so only globally configured plugins see them.