The best way to control Claude Code, Codex and more from any computer or phone
| 1 | import type * as runtime from "@cloudflare/workers-types"; |
| 2 | import * as aisearch from "@distilled.cloud/cloudflare/aisearch"; |
| 3 | import type { RuntimeContext } from "alchemy/RuntimeContext"; |
| 4 | import * as Effect from "effect/Effect"; |
| 5 | import type * as HttpClient from "effect/http/HttpClient"; |
| 6 | import * as Stream from "effect/Stream"; |
| 7 | import type { Credentials } from "../Credentials.ts"; |
| 8 | import { SearchError, type QuerySearchClient } from "./QuerySearch.ts"; |
| 9 | import type { QuerySearchNamespaceClient } from "./QuerySearchNamespace.ts"; |
| 10 | |
| 11 | // Shared HTTP scaffolding for the AI Search `*Local` binding layers. NOT |
| 12 | // re-exported from `index.ts` — only the per-level `*Local` layers are public. |
| 13 | // |
| 14 | // The `ai_search` / `ai_search_namespace` Worker bindings proxy the same AI |
| 15 | // Search REST API that distilled wraps, so the whole data plane |
| 16 | // (`search` / `chatCompletions` / `info` / `stats` / `list`) is reachable over |
| 17 | // HTTP with the current credentials — no Worker host, no native binding. |
| 18 | // |
| 19 | // The one wrinkle: distilled decodes responses to **camelCase**, while the |
| 20 | // binding client contract types come from `@cloudflare/workers-types` and are |
| 21 | // the **snake_case** wire shape. These adapters translate both directions |
| 22 | // (mirroring the D1 `*Local` shim), passing user-controlled maps |
| 23 | // (`item.metadata`, retrieval `filters`) through untouched. |
| 24 | |
| 25 | /** |
| 26 | * Injectable auth shared by a future Http (scoped-token) impl and the Local |
| 27 | * (current-credentials) impl. `authorize` discharges the |
| 28 | * `Credentials | HttpClient` requirement of a distilled op; `accountId` is the |
| 29 | * Cloudflare account the ops run against. |
| 30 | */ |
| 31 | export interface SearchAuth { |
| 32 | authorize: <A, E>( |
| 33 | eff: Effect.Effect<A, E, Credentials | HttpClient.HttpClient>, |
| 34 | ) => Effect.Effect<A, E>; |
| 35 | accountId: string; |
| 36 | } |
| 37 | |
| 38 | const u = <T>(v: T | null | undefined): T | undefined => (v == null ? undefined : v); |
| 39 | |
| 40 | const run = <A, E>( |
| 41 | auth: SearchAuth, |
| 42 | eff: Effect.Effect<A, E, Credentials | HttpClient.HttpClient>, |
| 43 | ): Effect.Effect<A, SearchError, RuntimeContext> => |
| 44 | auth.authorize(eff).pipe( |
| 45 | Effect.mapError((cause) => { |
| 46 | const message = |
| 47 | cause instanceof Error |
| 48 | ? cause.message |
| 49 | : typeof (cause as { message?: unknown } | undefined)?.message === "string" |
| 50 | ? (cause as { message: string }).message |
| 51 | : "AI Search HTTP error"; |
| 52 | return new SearchError({ message, cause }); |
| 53 | }), |
| 54 | ); |
| 55 | |
| 56 | // ── response mappers (distilled camelCase -> runtime snake_case) ───────────── |
| 57 | |
| 58 | type ChunkIn = aisearch.SearchNamespaceInstanceResponse["chunks"][number]; |
| 59 | |
| 60 | const mapChunk = (c: ChunkIn): runtime.AiSearchSearchResponse["chunks"][number] => ({ |
| 61 | id: c.id, |
| 62 | type: c.type, |
| 63 | score: c.score, |
| 64 | text: c.text, |
| 65 | item: { |
| 66 | key: c.item?.key ?? "", |
| 67 | timestamp: u(c.item?.timestamp), |
| 68 | metadata: u(c.item?.metadata) as Record<string, unknown> | undefined, |
| 69 | }, |
| 70 | scoring_details: c.scoringDetails |
| 71 | ? { |
| 72 | keyword_score: u(c.scoringDetails.keywordScore), |
| 73 | vector_score: u(c.scoringDetails.vectorScore), |
| 74 | keyword_rank: u(c.scoringDetails.keywordRank), |
| 75 | vector_rank: u(c.scoringDetails.vectorRank), |
| 76 | reranking_score: u(c.scoringDetails.rerankingScore), |
| 77 | fusion_method: u(c.scoringDetails.fusionMethod) as "rrf" | "max" | undefined, |
| 78 | } |
| 79 | : undefined, |
| 80 | }); |
| 81 | |
| 82 | const mapSearch = ( |
| 83 | r: aisearch.SearchNamespaceInstanceResponse, |
| 84 | ): runtime.AiSearchSearchResponse => ({ |
| 85 | search_query: r.searchQuery ?? "", |
| 86 | chunks: r.chunks.map(mapChunk), |
| 87 | }); |
| 88 | |
| 89 | const mapChat = ( |
| 90 | r: aisearch.ChatCompletionsNamespaceInstanceResponse, |
| 91 | ): runtime.AiSearchChatCompletionsResponse => ({ |
| 92 | id: u(r.id), |
| 93 | object: u(r.object), |
| 94 | model: u(r.model), |
| 95 | choices: r.choices.map((choice) => ({ |
| 96 | index: u(choice.index), |
| 97 | message: { |
| 98 | role: choice.message.role as "system" | "developer" | "user" | "assistant" | "tool", |
| 99 | content: |
| 100 | typeof choice.message.content === "string" |
| 101 | ? choice.message.content |
| 102 | : choice.message.content == null |
| 103 | ? null |
| 104 | : JSON.stringify(choice.message.content), |
| 105 | }, |
| 106 | })), |
| 107 | chunks: r.chunks.map(mapChunk), |
| 108 | }); |
| 109 | |
| 110 | const mapStats = (r: aisearch.StatsNamespaceInstanceResponse): runtime.AiSearchStatsResponse => ({ |
| 111 | queued: u(r.queued), |
| 112 | running: u(r.running), |
| 113 | completed: u(r.completed), |
| 114 | error: u(r.error), |
| 115 | skipped: u(r.skipped), |
| 116 | outdated: u(r.outdated), |
| 117 | last_activity: u(r.lastActivity), |
| 118 | engine: r.engine |
| 119 | ? { |
| 120 | vectorize: r.engine.vectorize |
| 121 | ? { |
| 122 | vectorsCount: r.engine.vectorize.vectorsCount, |
| 123 | dimensions: r.engine.vectorize.dimensions, |
| 124 | } |
| 125 | : undefined, |
| 126 | r2: r.engine.r2 |
| 127 | ? { |
| 128 | payloadSizeBytes: r.engine.r2.payloadSizeBytes, |
| 129 | metadataSizeBytes: r.engine.r2.metadataSizeBytes, |
| 130 | objectCount: r.engine.r2.objectCount, |
| 131 | } |
| 132 | : undefined, |
| 133 | } |
| 134 | : undefined, |
| 135 | }); |
| 136 | |
| 137 | const mapInfo = (r: aisearch.ReadNamespaceInstanceResponse): runtime.AiSearchInstanceInfo => ({ |
| 138 | id: r.id, |
| 139 | type: u(r.type) as runtime.AiSearchInstanceInfo["type"], |
| 140 | source: u(r.source), |
| 141 | source_params: u(r.sourceParams), |
| 142 | paused: u(r.paused), |
| 143 | status: u(r.status), |
| 144 | namespace: u(r.namespace), |
| 145 | created_at: u(r.createdAt), |
| 146 | modified_at: u(r.modifiedAt), |
| 147 | token_id: u(r.tokenId), |
| 148 | ai_gateway_id: u(r.aiGatewayId), |
| 149 | rewrite_query: u(r.rewriteQuery), |
| 150 | reranking: u(r.reranking), |
| 151 | embedding_model: u(r.embeddingModel), |
| 152 | ai_search_model: u(r.aiSearchModel), |
| 153 | rewrite_model: u(r.rewriteModel), |
| 154 | reranking_model: u(r.rerankingModel), |
| 155 | hybrid_search_enabled: u(r.hybridSearchEnabled), |
| 156 | index_method: r.indexMethod |
| 157 | ? { vector: r.indexMethod.vector, keyword: r.indexMethod.keyword } |
| 158 | : undefined, |
| 159 | fusion_method: u(r.fusionMethod) as "max" | "rrf" | undefined, |
| 160 | indexing_options: r.indexingOptions |
| 161 | ? { |
| 162 | keyword_tokenizer: u(r.indexingOptions.keywordTokenizer) as |
| 163 | | "porter" |
| 164 | | "trigram" |
| 165 | | undefined, |
| 166 | } |
| 167 | : undefined, |
| 168 | retrieval_options: r.retrievalOptions |
| 169 | ? { |
| 170 | keyword_match_mode: u(r.retrievalOptions.keywordMatchMode) as "and" | "or" | undefined, |
| 171 | boost_by: u(r.retrievalOptions.boostBy)?.map((b) => ({ |
| 172 | field: b.field, |
| 173 | direction: u(b.direction) as "asc" | "desc" | "exists" | "not_exists" | undefined, |
| 174 | })), |
| 175 | } |
| 176 | : undefined, |
| 177 | chunk_size: u(r.chunkSize), |
| 178 | chunk_overlap: u(r.chunkOverlap), |
| 179 | score_threshold: u(r.scoreThreshold), |
| 180 | max_num_results: u(r.maxNumResults), |
| 181 | cache: u(r.cache), |
| 182 | cache_threshold: u(r.cacheThreshold) as runtime.AiSearchInstanceInfo["cache_threshold"], |
| 183 | custom_metadata: u(r.customMetadata)?.map((m) => ({ |
| 184 | field_name: m.fieldName, |
| 185 | data_type: m.dataType as "text" | "number" | "boolean" | "datetime", |
| 186 | })), |
| 187 | sync_interval: u(r.syncInterval) as runtime.AiSearchInstanceInfo["sync_interval"], |
| 188 | metadata: u(r.metadata) as Record<string, unknown> | undefined, |
| 189 | }); |
| 190 | |
| 191 | const mapList = ( |
| 192 | result: aisearch.ReadNamespaceInstanceResponse[], |
| 193 | ): runtime.AiSearchListResponse => ({ |
| 194 | result: result.map(mapInfo), |
| 195 | }); |
| 196 | |
| 197 | const mapMulti = (r: aisearch.SearchNamespaceResponse): runtime.AiSearchMultiSearchResponse => ({ |
| 198 | search_query: r.searchQuery ?? "", |
| 199 | chunks: r.chunks.map((c) => ({ ...mapChunk(c), instance_id: c.instanceId })), |
| 200 | errors: u(r.errors)?.map((e) => ({ |
| 201 | instance_id: e.instanceId, |
| 202 | message: e.message, |
| 203 | })), |
| 204 | }); |
| 205 | |
| 206 | // ── request mappers (runtime snake_case -> distilled camelCase) ────────────── |
| 207 | |
| 208 | const mapMessages = (messages: runtime.AiSearchMessage[]) => |
| 209 | messages.map((m) => ({ |
| 210 | role: m.role as "system" | "developer" | "user" | "assistant" | "tool", |
| 211 | content: |
| 212 | typeof m.content === "string" || m.content == null |
| 213 | ? m.content |
| 214 | : (m.content as unknown[]).map((part) => { |
| 215 | const p = part as Record<string, unknown>; |
| 216 | if ("image_url" in p || "imageUrl" in p) { |
| 217 | const img = (p.image_url ?? p.imageUrl) as { url: string }; |
| 218 | return { type: "image_url" as const, imageUrl: { url: img.url } }; |
| 219 | } |
| 220 | return { type: "text" as const, text: p.text as string }; |
| 221 | }), |
| 222 | })); |
| 223 | |
| 224 | const mapOptions = (o: runtime.AiSearchOptions | undefined) => { |
| 225 | if (!o) return undefined; |
| 226 | return { |
| 227 | cache: o.cache |
| 228 | ? { enabled: o.cache.enabled, cacheThreshold: o.cache.cache_threshold } |
| 229 | : undefined, |
| 230 | queryRewrite: o.query_rewrite |
| 231 | ? { |
| 232 | enabled: o.query_rewrite.enabled, |
| 233 | model: o.query_rewrite.model, |
| 234 | rewritePrompt: o.query_rewrite.rewrite_prompt, |
| 235 | } |
| 236 | : undefined, |
| 237 | reranking: o.reranking |
| 238 | ? { |
| 239 | enabled: o.reranking.enabled, |
| 240 | model: o.reranking.model, |
| 241 | matchThreshold: o.reranking.match_threshold, |
| 242 | } |
| 243 | : undefined, |
| 244 | retrieval: o.retrieval |
| 245 | ? { |
| 246 | retrievalType: o.retrieval.retrieval_type, |
| 247 | fusionMethod: o.retrieval.fusion_method, |
| 248 | keywordMatchMode: o.retrieval.keyword_match_mode, |
| 249 | matchThreshold: o.retrieval.match_threshold, |
| 250 | maxNumResults: o.retrieval.max_num_results, |
| 251 | contextExpansion: o.retrieval.context_expansion, |
| 252 | returnOnFailure: o.retrieval.return_on_failure, |
| 253 | // `filters` is a Vectorize metadata filter over user-defined fields — |
| 254 | // pass through untouched. |
| 255 | filters: o.retrieval.filters as Record<string, unknown> | undefined, |
| 256 | boostBy: o.retrieval.boost_by, |
| 257 | } |
| 258 | : undefined, |
| 259 | }; |
| 260 | }; |
| 261 | |
| 262 | // ── client builders ────────────────────────────────────────────────────────── |
| 263 | |
| 264 | /** Effect resolving `{ name (namespace), id (instanceId) }` at apply time. */ |
| 265 | export type InstanceRef = Effect.Effect<{ name: string; id: string }>; |
| 266 | |
| 267 | /** Effect resolving the namespace `name` at apply time. */ |
| 268 | export type NamespaceRef = Effect.Effect<string>; |
| 269 | |
| 270 | const dieRaw = (kind: string): Effect.Effect<never> => |
| 271 | Effect.die( |
| 272 | new Error( |
| 273 | `The AI Search ${kind} *Local binding runs over the HTTP API; the raw native runtime binding is only available inside a deployed Worker.`, |
| 274 | ), |
| 275 | ); |
| 276 | |
| 277 | /** |
| 278 | * Build a single-instance {@link QuerySearchClient} over the HTTP API. `ref` |
| 279 | * resolves the `{ namespace, instanceId }` at apply time. |
| 280 | */ |
| 281 | export const makeLocalSearchClient = (auth: SearchAuth, ref: InstanceRef): QuerySearchClient => { |
| 282 | const withRef = <A, E>( |
| 283 | fn: (r: { |
| 284 | name: string; |
| 285 | id: string; |
| 286 | }) => Effect.Effect<A, E, Credentials | HttpClient.HttpClient>, |
| 287 | ) => Effect.flatMap(ref, (r) => run(auth, fn(r))); |
| 288 | |
| 289 | return { |
| 290 | raw: dieRaw("instance"), |
| 291 | search: (params) => |
| 292 | withRef((r) => |
| 293 | aisearch.searchNamespaceInstance({ |
| 294 | accountId: auth.accountId, |
| 295 | namespace: r.name, |
| 296 | id: r.id, |
| 297 | ...("query" in params && params.query !== undefined |
| 298 | ? { query: params.query } |
| 299 | : { messages: mapMessages(params.messages ?? []) }), |
| 300 | aiSearchOptions: mapOptions(params.ai_search_options), |
| 301 | } as aisearch.SearchNamespaceInstanceRequest), |
| 302 | ).pipe(Effect.map(mapSearch)), |
| 303 | chatCompletions: (params) => |
| 304 | withRef((r) => |
| 305 | aisearch.chatCompletionsNamespaceInstance({ |
| 306 | accountId: auth.accountId, |
| 307 | namespace: r.name, |
| 308 | id: r.id, |
| 309 | messages: mapMessages(params.messages), |
| 310 | aiSearchOptions: mapOptions(params.ai_search_options), |
| 311 | } as aisearch.ChatCompletionsNamespaceInstanceRequest), |
| 312 | ).pipe(Effect.map(mapChat)), |
| 313 | info: () => |
| 314 | withRef((r) => |
| 315 | aisearch.readNamespaceInstance({ |
| 316 | accountId: auth.accountId, |
| 317 | namespace: r.name, |
| 318 | id: r.id, |
| 319 | }), |
| 320 | ).pipe(Effect.map(mapInfo)), |
| 321 | stats: () => |
| 322 | withRef((r) => |
| 323 | aisearch.statsNamespaceInstance({ |
| 324 | accountId: auth.accountId, |
| 325 | namespace: r.name, |
| 326 | id: r.id, |
| 327 | }), |
| 328 | ).pipe(Effect.map(mapStats)), |
| 329 | } satisfies QuerySearchClient; |
| 330 | }; |
| 331 | |
| 332 | /** |
| 333 | * Build a namespace {@link QuerySearchNamespaceClient} over the HTTP API. |
| 334 | * `.get(instanceName)` scopes a single-instance client to `(namespace, |
| 335 | * instanceName)`. |
| 336 | */ |
| 337 | export const makeLocalSearchNamespaceClient = ( |
| 338 | auth: SearchAuth, |
| 339 | ref: NamespaceRef, |
| 340 | ): QuerySearchNamespaceClient => ({ |
| 341 | raw: dieRaw("namespace"), |
| 342 | get: (instanceName) => |
| 343 | makeLocalSearchClient( |
| 344 | auth, |
| 345 | Effect.map(ref, (name) => ({ name, id: instanceName })), |
| 346 | ), |
| 347 | list: (params) => |
| 348 | Effect.flatMap(ref, (name) => |
| 349 | run( |
| 350 | auth, |
| 351 | Stream.runCollect( |
| 352 | aisearch.listNamespaceInstances.pages({ |
| 353 | accountId: auth.accountId, |
| 354 | namespace: name, |
| 355 | perPage: params?.per_page, |
| 356 | orderBy: params?.order_by, |
| 357 | orderByDirection: params?.order_by_direction, |
| 358 | search: params?.search, |
| 359 | }), |
| 360 | ), |
| 361 | ), |
| 362 | ).pipe( |
| 363 | Effect.map((chunk) => |
| 364 | mapList( |
| 365 | Array.from(chunk).flatMap( |
| 366 | (page) => (page.result ?? []) as unknown as aisearch.ReadNamespaceInstanceResponse[], |
| 367 | ), |
| 368 | ), |
| 369 | ), |
| 370 | ), |
| 371 | search: (params) => |
| 372 | Effect.flatMap(ref, (name) => |
| 373 | run( |
| 374 | auth, |
| 375 | aisearch.searchNamespace({ |
| 376 | accountId: auth.accountId, |
| 377 | name, |
| 378 | aiSearchOptions: { |
| 379 | instanceIds: params.ai_search_options.instance_ids, |
| 380 | ...mapOptions(params.ai_search_options), |
| 381 | }, |
| 382 | ...("query" in params && params.query !== undefined |
| 383 | ? { query: params.query } |
| 384 | : { messages: mapMessages(params.messages ?? []) }), |
| 385 | } as aisearch.SearchNamespaceRequest), |
| 386 | ), |
| 387 | ).pipe(Effect.map(mapMulti)), |
| 388 | }); |