The best way to control Claude Code, Codex and more from any computer or phone
| 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 | }) |