The best way to control Claude Code, Codex and more from any computer or phone

main
ts 145 lines 4.9 KB
Raw
1 /// <reference types="@cloudflare/workers-types" />
2
3 import * as Binding from "alchemy/Binding";
4 import type { RuntimeContext } from "alchemy/RuntimeContext";
5 import type { LanguageModel } from "effect/ai/LanguageModel";
6 import * as Data from "effect/Data";
7 import * as Effect from "effect/Effect";
8 import * as Layer from "effect/Layer";
9 import type { Gateway as GatewayResource } from "./Gateway.ts";
10 import { type LanguageModelOptions } from "./LanguageModel.ts";
11
12 /**
13 * Binding service that turns a {@link Gateway} resource
14 * into a typed {@link QueryGatewayClient} for Worker runtime code. Wraps
15 * the Cloudflare.AI. Gateway runtime binding so each operation returns
16 * an Effect tagged with {@link GatewayError}, exposes the raw
17 * Workers AI handle for `ai.run(...)`, and provides a `model(options)`
18 * factory that produces an `effect/ai` `LanguageModel`
19 * `Layer`.
20 *
21 * Bind a {@link Gateway} to a Worker and obtain the
22 * Effect-native AI Gateway client (`run`, `getUrl`, `model`, …).
23 *
24 * `QueryGateway` is a single identifier that is simultaneously the binding's
25 * Context tag, its type, and the callable —
26 * `yield* Cloudflare.AI.QueryGateway(gateway)`.
27 *
28 *
29 * ### Calling AI Gateway
30 * **Example:** Run through a gateway
31 * Bind the gateway during the Worker's init phase, then use `run` or
32 * `getUrl` from request handlers.
33 * ```typescript
34 * const aiGateway = yield* Cloudflare.AI.QueryGateway(gateway);
35 *
36 * return {
37 * fetch: Effect.gen(function* () {
38 * return yield* aiGateway.run({
39 * provider: "workers-ai",
40 * endpoint: "@cf/meta/llama-3.1-8b-instruct",
41 * headers: { "content-type": "application/json" },
42 * query: { prompt: "Write a concise status update" },
43 * });
44 * }),
45 * };
46 * ```
47 *
48 * ### Driving Effect AI through the gateway
49 * **Example:** `aiGateway.model(...)` -> Effect AI `LanguageModel`
50 * `model(options)` produces a `Layer<LanguageModel, never,
51 * RuntimeContext>` that translates `LanguageModel.generateText` /
52 * `streamText` calls (including tool calls and structured outputs)
53 * into `ai.run(...)` against the bound Workers AI model, routed
54 * through the gateway.
55 * ```typescript
56 * const aiGateway = yield* Cloudflare.AI.QueryGateway(gateway);
57 *
58 * const languageModel = aiGateway.model({
59 * model: "@cf/meta/llama-3.1-8b-instruct",
60 * parameters: { temperature: 0.7, maxTokens: 1024 },
61 * });
62 *
63 * const response = yield* LanguageModel.generateText({ prompt }).pipe(
64 * Effect.provide(languageModel),
65 * );
66 * ```
67 *
68 * Provide {@link QueryGatewayBinding} in the worker's runtime layer
69 * to resolve the underlying Cloudflare.AI. binding at request time.
70 *
71 * @binding
72 * @product AI Gateway
73 * @category AI
74 */
75 export interface QueryGateway extends Binding.Service<
76 QueryGateway,
77 "Cloudflare.AI.QueryGateway",
78 (gateway: GatewayResource) => Effect.Effect<QueryGatewayClient>
79 > {}
80
81 export const QueryGateway = Binding.Service<QueryGateway>("Cloudflare.AI.QueryGateway");
82
83 // Error raised by AI Gateway runtime operations.
84 export class GatewayError extends Data.TaggedError("AiGatewayError")<{
85 /**
86 * Human-readable runtime error message.
87 */
88 message: string;
89 /**
90 * Original error thrown by the Cloudflare runtime binding.
91 */
92 cause: unknown;
93 }> {}
94
95 /**
96 * Effect-native client for a Cloudflare.AI. Gateway Worker binding.
97 *
98 * Wraps the runtime {@link Gateway} binding so each operation returns an
99 * Effect tagged with {@link GatewayError}. Use
100 * `Cloudflare.AI.QueryGateway(gateway)` inside a Worker's init phase.
101 */
102 export interface QueryGatewayClient {
103 /**
104 * Effect resolving to the raw Workers AI binding.
105 */
106 raw: Effect.Effect<Ai, never, RuntimeContext>;
107 /**
108 * Effect resolving to the raw AI Gateway runtime binding.
109 */
110 gateway: Effect.Effect<AiGateway, never, RuntimeContext>;
111 /**
112 * Effect resolving to the gateway id (the resource attribute, captured at
113 * bind time). Useful when calling `ai.run(model, inputs, { gateway: { id } })`
114 * — the in-account path for first-party services like Workers AI.
115 */
116 id: Effect.Effect<string, never, RuntimeContext>;
117 /**
118 * Update metadata on an existing AI Gateway log entry.
119 */
120 patchLog(
121 logId: string,
122 data: Parameters<AiGateway["patchLog"]>[1],
123 ): Effect.Effect<void, GatewayError, RuntimeContext>;
124 /**
125 * Read an AI Gateway log entry by ID.
126 */
127 getLog(logId: string): Effect.Effect<AiGatewayLog, GatewayError, RuntimeContext>;
128 /**
129 * Build a provider URL routed through this gateway.
130 */
131 getUrl(
132 provider?: Parameters<AiGateway["getUrl"]>[0],
133 ): Effect.Effect<string, GatewayError, RuntimeContext>;
134 /**
135 * Run an AI Gateway request through the Cloudflare runtime binding.
136 */
137 run(
138 data: Parameters<AiGateway["run"]>[0],
139 options?: Parameters<AiGateway["run"]>[1],
140 ): Effect.Effect<Response, GatewayError, RuntimeContext>;
141
142 model(
143 options: Omit<LanguageModelOptions, "client">,
144 ): Layer.Layer<LanguageModel, never, RuntimeContext>;
145 }