diff --git a/AGENTS.md b/AGENTS.md index 8df3cc2c466b..ad1444824a32 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -206,7 +206,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/aisdk.ts b/packages/core/src/aisdk.ts index 37aefadb4971..54ce8084117c 100644 --- a/packages/core/src/aisdk.ts +++ b/packages/core/src/aisdk.ts @@ -710,13 +710,16 @@ function metadataProviderOptions(input: ProviderMetadata | undefined): SharedV3P return Object.fromEntries(Object.entries(input).map(([key, value]) => [key, jsonObject(value)])) } -function streamLanguage(language: LanguageModelV3, options: LanguageModelV3CallOptions, http?: HttpMiddleware) { +function streamLanguage(language: LanguageModelV3, options: LanguageModelV3CallOptions, perCall?: HttpMiddleware) { const state: StreamState = { step: 0, toolNames: {}, open: {} } return Stream.concat( Stream.make(LLMEvent.stepStart({ index: state.step })), Stream.unwrap( Effect.gen(function* () { - const context = yield* Effect.context() + // The SDK sends through its own fetch, not the executor, so scoped middleware is applied here, outside the + // per-call one, and cleared for the hooks so a request a hook makes isn't wrapped again. + const http = RequestExecutor.composeMiddleware(yield* RequestExecutor.CurrentMiddleware, perCall) + const context = Context.add(yield* Effect.context(), RequestExecutor.CurrentMiddleware, undefined) return yield* Effect.tryPromise({ try: () => http ? httpMiddleware.run({ http, context }, () => language.doStream(options)) : language.doStream(options), diff --git a/packages/core/src/generate.ts b/packages/core/src/generate.ts index 2ef8d81ca79d..fa77733922db 100644 --- a/packages/core/src/generate.ts +++ b/packages/core/src/generate.ts @@ -22,6 +22,8 @@ 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 { PluginHooks } from "./plugin/hooks.js" import { ModelRetry } from "./model-retry.js" export interface TextInput { @@ -129,6 +131,7 @@ export const layer = Layer.effect( const images = yield* ImageClient.Service const decisionClient = yield* DecisionClient.Service const videos = yield* VideoClient.Service + const hooks = yield* PluginHooks.Service const runText = Effect.fn("Generate.text")(function* (input: TextInput) { const resolved = yield* resolver @@ -164,6 +167,7 @@ export const layer = Layer.effect( }), ) .pipe( + ModelHttp.scoped(hooks, { model: resolved.ref, kind: "text" }), ModelRetry.retryOneShot, Effect.mapError((error) => providerError(resolved.ref, error)), ) @@ -206,6 +210,7 @@ export const layer = Layer.effect( }) .pipe( Effect.provideService(ImageClient.Service, images), + ModelHttp.scoped(hooks, { model: input.model, kind: "image" }), ModelRetry.retryOneShot, Effect.mapError((error) => providerError(input.model, error)), ) @@ -247,6 +252,7 @@ export const layer = Layer.effect( }) .pipe( Effect.provideService(DecisionClient.Service, decisionClient), + ModelHttp.scoped(hooks, { model: input.model, kind: "decision" }), ModelRetry.retryOneShot, Effect.mapError((error) => providerError(input.model, error)), ) @@ -271,6 +277,7 @@ export const layer = Layer.effect( if (!model) return yield* missing(ref, "video") return yield* run(model).pipe( Effect.provideService(VideoClient.Service, videos), + ModelHttp.scoped(hooks, { model: ref, kind: "video" }), Effect.mapError((error) => providerError(ref, error)), ) }) @@ -374,5 +381,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..c1b49f01acf0 --- /dev/null +++ b/packages/core/src/model-http.ts @@ -0,0 +1,72 @@ +export * as ModelHttp from "./model-http.js" + +import { RequestExecutor, type HttpMiddleware } from "@opencode/ai/route" +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" + +/** + * 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 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 (!hasHooks) 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 + ? 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 = + 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 + ? 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: inner.response, + }) + return HttpClientResponse.fromWeb(sent, after.response) + }) + return http +}) + +/** Runs `effect` with the model hooks on every provider request it makes, its polls and provider downloads included. */ +export const scoped = + (hooks: PluginHooks.Interface, scope: ModelRequestScope) => + (effect: Effect.Effect) => + middleware(hooks, scope).pipe( + Effect.flatMap((http) => (http ? effect.pipe(RequestExecutor.withMiddleware(http)) : effect)), + ) 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 8e08779e6840..b6c8b762d236 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/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 75bac45b0d22..ce68c35d9ed4 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, @@ -541,7 +541,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)) @@ -563,7 +563,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 32a45a5001be..610502ea2b4a 100644 --- a/packages/core/src/plugin/provider/snowflake-cortex.ts +++ b/packages/core/src/plugin/provider/snowflake-cortex.ts @@ -203,8 +203,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. @@ -214,8 +214,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/src/session/model-request.ts b/packages/core/src/session/model-request.ts index aea3440a0273..36188aadae7c 100644 --- a/packages/core/src/session/model-request.ts +++ b/packages/core/src/session/model-request.ts @@ -30,10 +30,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" @@ -372,38 +372,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 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, { + 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/src/voice.ts b/packages/core/src/voice.ts index 4368edf5c7c3..3c21f25f8898 100644 --- a/packages/core/src/voice.ts +++ b/packages/core/src/voice.ts @@ -10,10 +10,14 @@ import { } from "@opencode/ai/experimental" import { RequestExecutor } from "@opencode/ai/route" import { makeLocationNode } from "@opencode/util/effect/app-node" +import { Model } from "@opencode/schema/model" +import { Provider } from "@opencode/schema/provider" import { Context, Effect, Layer, Redacted, Schema } from "effect" import { Credential } from "./credential.js" import { requestExecutor } from "./effect/app-node-platform.js" import { Integration } from "./integration.js" +import { ModelHttp } from "./model-http.js" +import { PluginHooks } from "./plugin/hooks.js" export interface ModelInfo { readonly model: string @@ -56,6 +60,7 @@ export const layer = Layer.effect( Effect.gen(function* () { const executor = yield* RequestExecutor.Service const integrations = yield* Integration.Service + const hooks = yield* PluginHooks.Service // Integration lists the active credential first, then newer stored credentials, then non-empty env vars. const findConnection = (provider: string, methods: readonly string[] = ["key"]) => @@ -114,6 +119,10 @@ export const layer = Layer.effect( ...access, }).pipe( Effect.provideService(RequestExecutor.Service, executor), + ModelHttp.scoped(hooks, { + model: Model.Ref.make({ providerID: Provider.ID.make(found.provider), id: Model.ID.make(input.model) }), + kind: "voice", + }), Effect.mapError( (error: AIError): Error => error.reason._tag === "InvalidRequest" || error.reason._tag === "UnsupportedOperation" @@ -130,7 +139,7 @@ export const layer = Layer.effect( export const node = makeLocationNode({ service: Service, layer, - deps: [Integration.node, requestExecutor], + deps: [Integration.node, PluginHooks.node, requestExecutor], }) /** OpenCode hosts GPT-Live on its OpenAI account, billed to the workspace whose credential starts a session. */ diff --git a/packages/core/test/aisdk.test.ts b/packages/core/test/aisdk.test.ts index 0245b7a18f65..7ba6218645f9 100644 --- a/packages/core/test/aisdk.test.ts +++ b/packages/core/test/aisdk.test.ts @@ -22,7 +22,7 @@ import { TransportError, UnknownProviderError, } from "@opencode/ai/effect" -import { LLMClient, RequestExecutor } from "@opencode/ai/route" +import { LLMClient, RequestExecutor, type HttpMiddleware } from "@opencode/ai/route" import { compileRequest } from "@opencode/ai/testing" import { expect } from "bun:test" import { Effect, Layer } from "effect" @@ -800,6 +800,35 @@ it.effect("routes AI SDK requests and responses through HTTP hook middleware", ( }), ) +it.effect("runs scoped HTTP middleware on AI SDK requests, outside per-call middleware", () => + Effect.gen(function* () { + const headers: Headers[] = [] + const resolved = yield* compatibleModel( + Object.assign( + async (_input: Parameters[0], init?: RequestInit) => { + headers.push(new Headers(init?.headers)) + return new Response(chatChunk("upstream"), { headers: { "content-type": "text/event-stream" } }) + }, + { preconnect: fetch.preconnect }, + ), + ) + const order: string[] = [] + const tag = + (name: string): HttpMiddleware => + (request, handler) => + Effect.sync(() => order.push(name)).pipe( + Effect.andThen(handler(HttpClientRequest.setHeader(request, `x-${name}`, "1"))), + ) + yield* LLMClient.generate(ai.request({ model: resolved, prompt: "Hello" }), { http: tag("call") }).pipe( + RequestExecutor.withMiddleware(tag("scoped")), + Effect.provide(client), + ) + expect(order).toEqual(["scoped", "call"]) + expect(headers[0]?.get("x-scoped")).toBe("1") + expect(headers[0]?.get("x-call")).toBe("1") + }), +) + it.effect("sends AI SDK requests directly when no HTTP hook middleware is attached", () => Effect.gen(function* () { const bodies: unknown[] = [] diff --git a/packages/core/test/generate.test.ts b/packages/core/test/generate.test.ts index adbe8a5d3889..f7feecdc6167 100644 --- a/packages/core/test/generate.test.ts +++ b/packages/core/test/generate.test.ts @@ -21,10 +21,12 @@ 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" 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" @@ -82,7 +84,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 +271,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, 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]) @@ -292,6 +297,11 @@ describe("image and decision generation", () => { type: "image", package: "@opencode/ai/providers/zai/images", }), + Info.make({ + ...Info.default(Provider.ID.make("xai"), ID.make("grok-imagine-video")), + type: "video", + package: "@opencode/ai/providers/xai/videos", + }), Info.make({ ...Info.default(Provider.ID.openai, ID.make("gpt-5")), package: "@opencode/ai/providers/openai/responses", @@ -393,6 +403,10 @@ describe("image and decision generation", () => { const text = request.body._tag === "Uint8Array" ? new TextDecoder().decode(request.body.body) : "" requests.push({ url: request.url, headers: request.headers, body: text ? JSON.parse(text) : undefined }) if (request.url === "https://images.example/fox") return HttpClientResponse.fromWeb(request, new Response(PNG)) + if (request.url === "https://api.x.ai/v1/videos/generations") + return HttpClientResponse.fromWeb(request, Response.json({ request_id: "vid_1" })) + if (request.url === "https://api.x.ai/v1/videos/vid_1") + return HttpClientResponse.fromWeb(request, Response.json({ status: "pending" })) if (request.url === "https://api.z.ai/api/paas/v4/images/generations") return HttpClientResponse.fromWeb( request, @@ -442,7 +456,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({ @@ -665,6 +679,59 @@ describe("image and decision generation", () => { }), ) + const hookedIt = testEffect( + Generate.layer.pipe( + Layer.provideMerge( + Layer.mergeAll(mediaResolver, client, mediaModels, LayerNode.compile(PluginHooks.node), executor), + ), + ), + ) + + hookedIt.effect("runs model HTTP hooks on image, decision and video provider requests, but not image downloads", () => + Effect.gen(function* () { + requests.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({ + model: ref("decide-host", "decide-default"), + input: [{ type: "text", text: "Is this a photo?" }], + questions: [{ type: "predicate", name: "photo", instructions: "Is this a photo?" }], + }) + const video = yield* generate.video.start({ model: ref("xai", "grok-imagine-video"), prompt: "A fox" }) + expect(yield* generate.video.status(ref("xai", "grok-imagine-video"), video.id)).toMatchObject({ + status: "running", + }) + expect(hooked).toEqual([ + "request:image", + "response:image", + "request:decision", + "response:decision", + "request:video", + "response:video", + "request:video", + "response:video", + ]) + 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"], + ["https://api.x.ai/v1/videos/generations", "1"], + ["https://api.x.ai/v1/videos/vid_1", "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/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/core/test/plugin/provider-azure.test.ts b/packages/core/test/plugin/provider-azure.test.ts index 53992f51ee30..140175cd97f0 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" }, }), @@ -624,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/core/test/plugin/provider-chatgpt.test.ts b/packages/core/test/plugin/provider-chatgpt.test.ts index 0f82b78697b1..8ba32c623ea8 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-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-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/core/test/plugin/provider-opencode.test.ts b/packages/core/test/plugin/provider-opencode.test.ts index 552efabe5a68..5e3f048b96d4 100644 --- a/packages/core/test/plugin/provider-opencode.test.ts +++ b/packages/core/test/plugin/provider-opencode.test.ts @@ -935,9 +935,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 94d7ec163600..a3a1cef45a1f 100644 --- a/packages/core/test/session-model-request-hooks.test.ts +++ b/packages/core/test/session-model-request-hooks.test.ts @@ -4,8 +4,10 @@ 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" import { PluginHooks } from "@opencode/core/plugin/hooks" import { Project } from "@opencode/core/project" import { AbsolutePath } from "@opencode/core/schema" @@ -274,3 +276,58 @@ 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")}`) + }), + ) + 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: ModelRequestScope) => + 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 response:text", + "model:primary:ses_hook_kind", + "session:primary:ses_hook_kind:1", + "session response:primary", + "model response:primary", + ]) + expect(sent).toEqual(["1", "1"]) + }), + ) +}) diff --git a/packages/core/test/voice.test.ts b/packages/core/test/voice.test.ts index 4f10d7fed5da..0b19d271265d 100644 --- a/packages/core/test/voice.test.ts +++ b/packages/core/test/voice.test.ts @@ -2,13 +2,16 @@ import { expect } from "bun:test" import { RequestExecutor } from "@opencode/ai/route" import { Credential } from "@opencode/core/credential" import { Integration } from "@opencode/core/integration" +import { PluginHooks } from "@opencode/core/plugin/hooks" import { Voice } from "@opencode/core/voice" +import { LayerNode } from "@opencode/util/effect/layer-node" import { Effect, Layer } from "effect" import { HttpClient, type HttpClientRequest, HttpClientResponse } from "effect/http" import { TestClock } from "effect/testing" import { testEffect } from "./lib/effect" const it = testEffect(Layer.empty) +const hooks = LayerNode.compile(PluginHooks.node) const credential = (id: string, method: "key" | "oauth") => ({ type: "credential" as const, @@ -84,7 +87,8 @@ const start = ( Effect.provide( Voice.layer.pipe( Layer.provide( - Layer.merge( + Layer.mergeAll( + hooks, mockIntegration((id) => connections[id] ?? [], resolveCredential), RequestExecutor.layer.pipe( Layer.provide( @@ -187,7 +191,8 @@ it.effect("lists voice models with availability and default without resolving cr Effect.provide( Voice.layer.pipe( Layer.provide( - Layer.merge( + Layer.mergeAll( + hooks, mockIntegration((id) => connections[id] ?? []), Layer.mock(RequestExecutor.Service, {}), ), diff --git a/packages/plugin/src/effect/model.ts b/packages/plugin/src/effect/model.ts index 6d027f0ac565..21827b126627 100644 --- a/packages/plugin/src/effect/model.ts +++ b/packages/plugin/src/effect/model.ts @@ -1,8 +1,11 @@ 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 { SessionRequestKind } from "./session.js" +import type { ModelHooks, Transform } from "./registration.js" export interface ModelEditor { /** Candidates from available providers, including models disabled by earlier transforms. */ @@ -22,7 +25,47 @@ export interface ModelEditor { } } +/** 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 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 } + | { readonly kind: "text" | "image" | "decision" | "video" | "voice"; readonly session?: undefined } +) + +/** An HTTP request to a model provider, before it is sent. Replace `request` to change it. Experimental. */ +export type ModelHttpRequest = ModelRequestScope & { + request: Request +} + +/** The provider's HTTP response to `request`. Replace `response` to change what the model client reads. Experimental. */ +export type ModelHttpResponse = ModelRequestScope & { + readonly request: Request + response: Response +} + +/** + * Hooks on every HTTP request to a model provider, whichever Session or API makes it: Session steps, compaction, + * titles and warming, `generate` text, image, decision and video calls, and voice session setup. Use these to read or + * change what is sent on the wire (URL, headers, body) or the raw response. They run on each request sent, retries and + * media polls included, after the provider's auth headers are set; a hook that fails fails the request. WebSocket + * traffic doesn't pass through them. Experimental. + */ +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/effect/session.ts b/packages/plugin/src/effect/session.ts index 6d0429b429fd..9dd42bb682af 100644 --- a/packages/plugin/src/effect/session.ts +++ b/packages/plugin/src/effect/session.ts @@ -90,6 +90,7 @@ export interface SessionModelRequest { headers: Record } +/** 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 @@ -98,6 +99,7 @@ export interface SessionHttpRequest { request: Request } +/** 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 @@ -208,7 +210,15 @@ export interface SessionHooks { readonly title: SessionTitle readonly "experimental.model.resolve": SessionModelResolve readonly "model.request": SessionModelRequest + /** + * 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, 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 readonly "experimental.ws.send": SessionWebSocketSend diff --git a/packages/plugin/src/promise/adapter.ts b/packages/plugin/src/promise/adapter.ts index ec91156ba462..2b184ab8347a 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..ac2974518edc 100644 --- a/packages/plugin/src/promise/model.ts +++ b/packages/plugin/src/promise/model.ts @@ -1,8 +1,11 @@ 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 { SessionRequestKind } from "./session.js" +import type { ModelHooks, Transform } from "./registration.js" export interface ModelEditor { /** Candidates from available providers, including models disabled by earlier transforms. */ @@ -22,7 +25,47 @@ export interface ModelEditor { } } +/** 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 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 } + | { readonly kind: "text" | "image" | "decision" | "video" | "voice"; readonly session?: undefined } +) + +/** An HTTP request to a model provider, before it is sent. Replace `request` to change it. Experimental. */ +export type ModelHttpRequest = ModelRequestScope & { + request: Request +} + +/** The provider's HTTP response to `request`. Replace `response` to change what the model client reads. Experimental. */ +export type ModelHttpResponse = ModelRequestScope & { + readonly request: Request + response: Response +} + +/** + * Hooks on every HTTP request to a model provider, whichever Session or API makes it: Session steps, compaction, + * titles and warming, `generate` text, image, decision and video calls, and voice session setup. Use these to read or + * change what is sent on the wire (URL, headers, body) or the raw response. They run on each request sent, retries and + * media polls included, after the provider's auth headers are set; a hook that fails fails the request. WebSocket + * traffic doesn't pass through them. Experimental. + */ +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/packages/plugin/src/promise/session.ts b/packages/plugin/src/promise/session.ts index 4fd80c187730..168c887da1b4 100644 --- a/packages/plugin/src/promise/session.ts +++ b/packages/plugin/src/promise/session.ts @@ -90,6 +90,7 @@ export interface SessionModelRequest { headers: Record } +/** 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 @@ -98,6 +99,7 @@ export interface SessionHttpRequest { request: Request } +/** 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 @@ -208,7 +210,15 @@ export interface SessionHooks { readonly title: SessionTitle readonly "experimental.model.resolve": SessionModelResolve readonly "model.request": SessionModelRequest + /** + * 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, 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 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 28ae763f7230..6499de68a5fa 100644 --- a/services/site/src/docs/content/build/plugins/effect.mdx +++ b/services/site/src/docs/content/build/plugins/effect.mdx @@ -1296,8 +1296,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) => @@ -1311,21 +1312,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, decision and video calls and voice session setup 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 for Session requests, inside the model hooks. ```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, @@ -1414,7 +1417,9 @@ interface SessionHooks { readonly generate: SessionGenerate readonly title: SessionTitle readonly "model.request": SessionModelRequest + /** Session calls only. Prefer ctx.model.hook("experimental.http.request") */ readonly "http.request": SessionHttpRequest + /** Session calls only. Prefer ctx.model.hook("experimental.http.response") */ readonly "http.response": SessionHttpResponse readonly "experimental.ws.handshake": SessionWebSocketHandshake readonly "experimental.ws.send": SessionWebSocketSend @@ -1436,6 +1441,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" | "video" | "voice"; 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 ea263f0d9897..10de7984e418 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`, @@ -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 aaca94624ec0..6964009dd946 100644 --- a/services/site/src/docs/content/build/plugins/server.mdx +++ b/services/site/src/docs/content/build/plugins/server.mdx @@ -1518,8 +1518,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( @@ -1533,31 +1534,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" }, - }) -}) -``` +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 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) 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. @@ -1645,7 +1629,9 @@ interface SessionHooks { title: SessionRequestHook & { result?: string } "experimental.model.resolve": SessionModelResolveHook "model.request": SessionModelRequestHook + /** Session calls only. Prefer ctx.model.hook("experimental.http.request") */ "http.request": SessionHttpRequestHook + /** Session calls only. Prefer ctx.model.hook("experimental.http.response") */ "http.response": SessionHttpResponseHook "experimental.ws.handshake": SessionWebSocketHandshakeHook "experimental.ws.send": SessionWebSocketSendHook @@ -1734,6 +1720,67 @@ interface SessionHookContext { } ``` +### 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, [Generate](#generate-experimental) text, image, decision and video calls, and +voice session setup. 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). + +- They run on each request sent: every retry, and a media job's submit, polls and result. A result downloaded from + another host, such as a CDN link, doesn't run them. +- The request already carries the provider's auth headers. Changing a request the provider signs, such as Bedrock's, + breaks the signature. +- 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`. +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 + +```ts +interface ModelHookContext { + hook( + name: Name, + callback: (event: ModelRequestHooks[Name]) => Promise | void, + options?: { providerID?: string }, + ): Promise +} + +type ModelRequestScope = { model: { providerID: string; id: string; variant?: string } } & ( + | { kind: "primary" | "compaction" | "title" | "generate"; session: { id: string; agent: string } } + | { kind: "text" | "image" | "decision" | "video" | "voice"; session?: undefined } +) + +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