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

main
ts 378 lines 14.1 KB
Raw
1 import * as Config from "@effect/ai-codegen/Config"
2 import * as Generator from "@effect/ai-codegen/Generator"
3 import * as SpecFetcher from "@effect/ai-codegen/SpecFetcher"
4 import * as NodeServices from "@effect/platform-node/NodeServices"
5 import { assert, describe, it } from "@effect/vitest"
6 import * as Effect from "effect/Effect"
7 import * as Yaml from "effect/encoding/Yaml"
8 import * as Exit from "effect/Exit"
9 import * as FileSystem from "effect/FileSystem"
10 import * as HttpClient from "effect/http/HttpClient"
11 import * as HttpClientResponse from "effect/http/HttpClientResponse"
12 import * as Layer from "effect/Layer"
13 import * as Path from "effect/Path"
14 import * as Schema from "effect/Schema"
15 import { gzipSync } from "node:zlib"
16
17 const ref = (name: string) => ({ $ref: `#/components/schemas/${name}` })
18 const object = (properties: Record<string, unknown>, required: ReadonlyArray<string> = []) => ({
19 type: "object",
20 properties,
21 required
22 })
23 const string = { type: "string" }
24 const tag = (value: string) => ({ type: "string", enum: [value] })
25
26 interface Case {
27 readonly name: string
28 readonly schemas: Record<string, unknown>
29 readonly valid: ReadonlyArray<unknown>
30 readonly invalid: ReadonlyArray<unknown>
31 }
32
33 // Each case mirrors a shape from the canonical OpenAI spec (openai/openai-openapi). The
34 // last schema is the request body of the only operation, so it is the one decoded.
35 const cases: ReadonlyArray<Case> = [
36 {
37 name: "OpenAPI 3.1 keywords such as examples",
38 schemas: { Root: object({ name: { type: ["string", "null"], examples: ["a"] } }, ["name"]) },
39 valid: [{ name: "a" }, { name: null }],
40 invalid: [{ name: 1 }]
41 },
42 {
43 // CreateChatCompletionRequest, Response, *Resource
44 name: "allOf of object schemas",
45 schemas: {
46 Base: object({ temperature: { type: ["number", "null"] } }),
47 Root: {
48 allOf: [
49 ref("Base"),
50 object({ model: string, messages: { type: "array", items: string } }, ["model", "messages"])
51 ]
52 }
53 },
54 valid: [{ model: "gpt", messages: ["hi"], temperature: 1 }],
55 invalid: [{ model: "gpt" }]
56 },
57 {
58 // WebSearchToolCall.action
59 name: "object wrapper around oneOf alternatives",
60 schemas: {
61 Search: object({ type: tag("search"), query: string }, ["type"]),
62 OpenPage: object({ type: tag("open_page"), url: string }, ["type"]),
63 Root: object({
64 action: { type: "object", oneOf: [ref("Search"), ref("OpenPage")], discriminator: { propertyName: "type" } }
65 }, ["action"])
66 },
67 valid: [{ action: { type: "search", query: "q" } }, { action: { type: "open_page", url: "u" } }],
68 invalid: [{ action: { type: "find" } }]
69 },
70 {
71 // CreateAssistantRequest.tool_resources.file_search, CreateVectorStoreFileBatchRequest
72 name: "properties with required-only oneOf alternatives",
73 schemas: {
74 Root: {
75 type: "object",
76 properties: {
77 ids: { type: "array", items: string },
78 stores: { type: "array", items: object({ metadata: { anyOf: [{ type: "object" }, { type: "null" }] } }) }
79 },
80 oneOf: [{ required: ["ids"] }, { required: ["stores"] }]
81 }
82 },
83 valid: [{ ids: ["a"] }, { stores: [{ metadata: null }] }],
84 invalid: [{}]
85 },
86 {
87 // ComputerUseApprovalResponseParamBrowserAuthentication
88 name: "properties with oneOf alternatives by reference",
89 schemas: {
90 Submit: object({ action: tag("submit"), username: string }, ["action", "username"]),
91 Cancel: object({ action: tag("cancel") }, ["action"]),
92 Root: {
93 properties: { type: tag("browser_authentication") },
94 required: ["type"],
95 oneOf: [ref("Submit"), ref("Cancel")],
96 discriminator: { propertyName: "action" }
97 }
98 },
99 valid: [{ type: "browser_authentication", action: "submit", username: "u" }, {
100 type: "browser_authentication",
101 action: "cancel"
102 }],
103 invalid: [{ type: "browser_authentication", action: "submit" }]
104 },
105 {
106 // FineTuningJob
107 name: "if/then/else",
108 schemas: {
109 Root: {
110 ...object({ method: object({ type: { enum: ["supervised", "dpo"] } }), hyperparameters: { type: "object" } }),
111 if: {
112 properties: { method: { properties: { type: { enum: ["dpo"] } }, required: ["type"] } },
113 required: ["method"]
114 },
115 else: { required: ["hyperparameters"] }
116 }
117 },
118 valid: [{ method: { type: "dpo" } }, { method: { type: "supervised" }, hyperparameters: {} }],
119 invalid: [{ method: 1 }]
120 },
121 {
122 // RealtimeSessionCreateRequestGA noise_reduction
123 name: "not",
124 schemas: {
125 Root: object({ noise_reduction: { not: { type: ["array", "string", "number", "boolean"] } } })
126 },
127 valid: [{ noise_reduction: null }, { noise_reduction: { type: "near_field" } }],
128 invalid: [{ noise_reduction: "on" }]
129 },
130 {
131 // FineTuningJob.method: a nullable reference narrowed by the `if` condition
132 name: "nullable alternatives merged with an object constraint",
133 schemas: {
134 Method: object({
135 type: { type: "string", enum: ["supervised", "dpo"] },
136 dpo: object({ beta: { type: "number" } })
137 }),
138 Root: {
139 ...object({ method: { anyOf: [ref("Method"), { type: "null" }] }, hyperparameters: { type: "object" } }),
140 if: {
141 properties: { method: { type: "object", properties: { type: { enum: ["dpo"] } }, required: ["type"] } },
142 required: ["method"]
143 },
144 else: { required: ["hyperparameters"] }
145 }
146 },
147 valid: [{ method: { type: "dpo", dpo: { beta: 1 } } }, { method: null, hyperparameters: {} }],
148 invalid: [{ method: { type: "supervised" } }, { method: { type: "dpo", dpo: { beta: "high" } } }]
149 },
150 {
151 // CreateRunRequest.truncation_strategy and response_format
152 name: "OpenAPI 3.0 nullable markers left in a 3.1 spec",
153 schemas: {
154 Truncation: object({ type: tag("auto") }, ["type"]),
155 Root: object({
156 truncation: { allOf: [ref("Truncation"), { nullable: true }] },
157 format: { ...ref("Truncation"), nullable: true }
158 })
159 },
160 valid: [{ truncation: null, format: null }, { truncation: { type: "auto" }, format: { type: "auto" } }],
161 invalid: [{ truncation: { type: "last_messages" } }, { format: "auto" }]
162 },
163 {
164 // ImageRefParam
165 name: "exactly one of two keys",
166 schemas: {
167 Root: {
168 ...object({ image_url: string, file_id: string }),
169 anyOf: [{ required: ["image_url"] }, { required: ["file_id"] }],
170 not: { required: ["image_url", "file_id"] },
171 additionalProperties: false
172 }
173 },
174 valid: [{ image_url: "https://example.com/a.png" }, { file_id: "file_1" }],
175 invalid: [{}, { image_url: "https://example.com/a.png", file_id: "file_1" }]
176 },
177 {
178 // EnvironmentParamOpenaiHosted
179 name: "keys that cannot be combined",
180 schemas: {
181 Root: {
182 ...object({
183 type: tag("hosted"),
184 environment_id: string,
185 packages: { type: "array", items: string },
186 network: string
187 }, [
188 "type"
189 ]),
190 additionalProperties: false,
191 not: { required: ["environment_id"], anyOf: [{ required: ["packages"] }, { required: ["network"] }] }
192 }
193 },
194 valid: [{ type: "hosted" }, { type: "hosted", environment_id: "env_1" }, {
195 type: "hosted",
196 packages: ["numpy"],
197 network: "none"
198 }],
199 invalid: [{ type: "hosted", environment_id: "env_1", packages: [] }, {
200 type: "hosted",
201 environment_id: "env_1",
202 network: "none"
203 }]
204 },
205 {
206 // Metadata, FunctionParameters and free-form objects
207 name: "maps and free-form objects",
208 schemas: {
209 Root: object({
210 metadata: { anyOf: [{ type: "object", additionalProperties: string }, { type: "null" }] },
211 parameters: { type: "object", additionalProperties: true },
212 options: { type: "object" }
213 })
214 },
215 valid: [{ metadata: { user: "u_1" }, parameters: { type: "object", properties: {} }, options: { seed: 1 } }],
216 invalid: [{ metadata: { user: 1 } }, { options: "seed" }]
217 },
218 {
219 // LocalShellToolCallOutput requires `call_id` without declaring it
220 name: "required keys missing from properties",
221 schemas: { Root: object({ type: tag("local_shell_call_output"), output: string }, ["type", "call_id", "output"]) },
222 valid: [{ type: "local_shell_call_output", call_id: "call_1", output: "ok" }],
223 invalid: [{ type: "local_shell_call_output", output: "ok" }]
224 },
225 {
226 // A member closed by the spec forbids keys that only other members declare
227 name: "explicitly closed composition members",
228 schemas: {
229 Root: object({
230 merged: { allOf: [{ ...object({ a: string }), additionalProperties: false }, object({ b: string })] },
231 distributed: {
232 ...object({ a: string }),
233 additionalProperties: false,
234 anyOf: [object({ b: string }, ["b"]), { required: ["a"] }]
235 }
236 })
237 },
238 valid: [{ merged: { a: "a" }, distributed: { a: "a" } }],
239 invalid: [{ merged: { a: "a", b: "b" } }, { distributed: { b: "b" } }]
240 },
241 {
242 // Both alternatives keywords on one schema must hold together, whether or not the `allOf`
243 // fragment declares properties of its own
244 name: "anyOf and oneOf on the same object",
245 schemas: {
246 Root: object({
247 requiredOnly: {
248 ...object({ a: string, b: string, c: string }),
249 allOf: [{ required: ["a"] }],
250 anyOf: [{ required: ["b"] }],
251 oneOf: [{ required: ["c"] }]
252 },
253 declaring: {
254 ...object({ a: string, b: string, c: string }),
255 allOf: [{ ...object({ d: string }), required: ["a"] }],
256 anyOf: [{ required: ["b"] }],
257 oneOf: [{ required: ["c"] }]
258 }
259 })
260 },
261 valid: [
262 { requiredOnly: { a: "a", b: "b", c: "c" } },
263 { declaring: { a: "a", b: "b", c: "c" } },
264 { declaring: { a: "a", b: "b", c: "c", d: "d" } }
265 ],
266 invalid: [
267 { requiredOnly: { a: "a" } },
268 { requiredOnly: { a: "a", b: "b" } },
269 { requiredOnly: { a: "a", c: "c" } },
270 { declaring: { b: "b", c: "c" } },
271 { declaring: { a: "a", b: "b" } },
272 { declaring: { a: "a", c: "c" } },
273 { declaring: { a: "a", b: "b", c: "c", d: 1 } }
274 ]
275 }
276 ]
277
278 const openAiConfig = Effect.gen(function*() {
279 const fs = yield* FileSystem.FileSystem
280 const config = Schema.decodeUnknownSync(Config.CodegenConfig)(Yaml.parse(
281 yield* fs.readFileString(new URL("../../../ai/openai/codegen.yaml", import.meta.url).pathname)
282 ))
283 // Patches addressing individual OpenAI components cannot apply to these fixtures,
284 // but document-level patches (such as the OpenAPI version) still shape generation.
285 const patches = config.patchList.filter((patch) => !patch.includes("\"/components/"))
286 return new Config.CodegenConfig({ ...config, patches })
287 })
288
289 const generateAndImport = Effect.fn(function*(schemas: Record<string, unknown>) {
290 const fs = yield* FileSystem.FileSystem
291 const path = yield* Path.Path
292 const generator = yield* Generator.CodeGenerator
293 const config = yield* openAiConfig
294 const root = Object.keys(schemas).at(-1)!
295 const code = yield* generator.generate({
296 name: "openai",
297 packagePath: ".",
298 outputPath: "Generated.ts",
299 specSource: Config.SpecSource.File("fixture.json"),
300 config
301 }, {
302 openapi: "3.1.0",
303 info: { title: "OpenAI", version: "1.0.0" },
304 paths: {
305 "/root": {
306 post: {
307 operationId: "createRoot",
308 requestBody: { required: true, content: { "application/json": { schema: ref(root) } } },
309 responses: { "204": { description: "No content" } }
310 }
311 }
312 },
313 components: { schemas }
314 })
315 // Generated modules import `effect`, so they must live inside this package to resolve it.
316 const directory = yield* fs.makeTempDirectoryScoped({ directory: import.meta.dirname })
317 const file = path.join(directory, "Generated.ts")
318 yield* fs.writeFileString(file, code)
319 const module = yield* Effect.promise(() => import(file))
320 return module[root] as Schema.Codec<unknown, unknown>
321 })
322
323 describe("OpenAI generation", () => {
324 it.effect.each(cases)("preserves $name", ({ invalid, schemas, valid }) =>
325 Effect.gen(function*() {
326 const schema = yield* generateAndImport(schemas)
327 const decode = Schema.decodeUnknownExit(schema)
328 for (const value of valid) {
329 const exit = decode(value)
330 assert.isTrue(Exit.isSuccess(exit), `expected to accept ${JSON.stringify(value)}`)
331 // Accepted values must decode without losing keys
332 if (Exit.isSuccess(exit)) assert.deepStrictEqual(exit.value, value)
333 }
334 for (const value of invalid) {
335 assert.isTrue(Exit.isFailure(decode(value)), `expected to reject ${JSON.stringify(value)}`)
336 }
337 }).pipe(
338 Effect.scoped,
339 Effect.provide(Generator.layerSchema.pipe(Layer.provideMerge(NodeServices.layer)))
340 ))
341 })
342
343 describe("SpecFetcher", () => {
344 it.effect("fails when a spec URL responds with an error status", () =>
345 Effect.gen(function*() {
346 const fetcher = yield* SpecFetcher.SpecFetcher
347 const exit = yield* Effect.exit(
348 fetcher.fetch(Config.SpecSource.Url("https://example.com/openapi.yml"), "openai")
349 )
350 assert.isTrue(Exit.isFailure(exit))
351 }).pipe(Effect.provide(SpecFetcher.layer.pipe(
352 Layer.provide(Layer.succeed(
353 HttpClient.HttpClient,
354 HttpClient.make((request) =>
355 Effect.succeed(HttpClientResponse.fromWeb(request, new Response("Not Found", { status: 404 })))
356 )
357 )),
358 Layer.provide(NodeServices.layer)
359 ))))
360
361 it.effect("decompresses a gzipped spec URL", () =>
362 Effect.gen(function*() {
363 const fetcher = yield* SpecFetcher.SpecFetcher
364 const spec = yield* fetcher.fetch(Config.SpecSource.Url("https://example.com/openapi.json.gz"), "anthropic")
365 assert.deepStrictEqual(spec, { openapi: "3.1.0", paths: {} })
366 }).pipe(Effect.provide(SpecFetcher.layer.pipe(
367 Layer.provide(Layer.succeed(
368 HttpClient.HttpClient,
369 HttpClient.make((request) =>
370 Effect.succeed(HttpClientResponse.fromWeb(
371 request,
372 new Response(gzipSync(JSON.stringify({ openapi: "3.1.0", paths: {} })))
373 ))
374 )
375 )),
376 Layer.provide(NodeServices.layer)
377 ))))
378 })