@zocomputer/agent-sdk 0.5.0

package/platform/cloud-tools/image.ts

@@ -0,0 +1,225 @@
+import { randomUUID } from "node:crypto";
+
+import { generateImage } from "ai";
+import { defineTool } from "eve/tools";
+import { z } from "zod";
+
+import { ZO_TOOL_HEADER, zoGateway } from "../runtime-ai/index.ts";
+import { imageOutputPath } from "./image-path";
+import { CLOUD_TOOL_META } from "./tool-meta";
+import {
+  createRuntimeStateFilesClient,
+  DEFAULT_STATE_ASSET_DECLARATION_NAME,
+  stateAssetReference,
+  type StateAssetReference,
+  type StateFilesAssetWriter,
+} from "./state-files";
+
+export const DEFAULT_IMAGE_MODEL = "bfl/flux-2-pro";
+
+type ImageSize = `${number}x${number}`;
+type ImageAspectRatio = `${number}:${number}`;
+
+function isImageSize(value: unknown): value is ImageSize {
+  return (
+    typeof value === "string" &&
+    /^[1-9]\d{1,4}x[1-9]\d{1,4}$/u.test(value)
+  );
+}
+
+function isImageAspectRatio(value: unknown): value is ImageAspectRatio {
+  return (
+    typeof value === "string" &&
+    /^[1-9]\d{0,2}:[1-9]\d{0,2}$/u.test(value)
+  );
+}
+
+// z.templateLiteral (never z.custom): eve converts tool input schemas to JSON Schema
+// with zod's toJSONSchema, which throws on z.custom — an agent with this tool would
+// fail to boot. templateLiteral emits a string+pattern schema and keeps the
+// template-literal types; the refine keeps the stricter bounds the pattern alone
+// can't express (runtime-only, invisible to JSON Schema).
+const SizeSchema = z
+  .templateLiteral([z.number().int().positive(), "x", z.number().int().positive()])
+  .refine(isImageSize, { message: "Use WIDTHxHEIGHT, for example 1024x1024." });
+
+const AspectRatioSchema = z
+  .templateLiteral([z.number().int().positive(), ":", z.number().int().positive()])
+  .refine(isImageAspectRatio, { message: "Use WIDTH:HEIGHT, for example 1:1 or 16:9." });
+
+const ImageDimensionsSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("auto") }).strict(),
+  z.object({ kind: z.literal("size"), size: SizeSchema }).strict(),
+  z
+    .object({
+      aspectRatio: AspectRatioSchema,
+      kind: z.literal("aspectRatio"),
+    })
+    .strict(),
+]);
+
+const OutputDirSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(200)
+  .regex(
+    /^(?!\/)(?!.*\/$)(?!.*\/\/)(?!.*(?:^|\/)(?:\.|\.\.)(?:\/|$))[A-Za-z0-9._/-]+$/u,
+    "Use a relative state file path without empty, . or .. segments.",
+  );
+
+export const GenerateImageInputSchema = z
+  .object({
+    dimensions: ImageDimensionsSchema.optional(),
+    model: z.string().trim().min(1).optional(),
+    outputDir: OutputDirSchema.optional(),
+    prompt: z.string().trim().min(1).max(4000),
+    seed: z.number().int().nonnegative().optional(),
+  })
+  .strict();
+
+const StateAssetReferenceSchema = z
+  .object({
+    bytes: z.number().int().nonnegative().optional(),
+    contentType: z.string().optional(),
+    declarationName: z.string(),
+    path: z.string(),
+    type: z.literal("state_asset"),
+  })
+  .strict();
+
+export const GenerateImageOutputSchema = z
+  .object({
+    asset: StateAssetReferenceSchema,
+    bytes: z.number().int().nonnegative(),
+    mediaType: z.string(),
+    model: z.string(),
+    path: z.string(),
+    prompt: z.string(),
+    warnings: z.array(z.string()),
+  })
+  .strict();
+
+export type GenerateImageDimensions = z.infer<typeof ImageDimensionsSchema>;
+export type GenerateImageInput = z.infer<typeof GenerateImageInputSchema>;
+export type GenerateImageOutput = z.infer<typeof GenerateImageOutputSchema>;
+
+interface GeneratedImageResult {
+  readonly image: {
+    readonly mediaType: string;
+    readonly uint8Array: Uint8Array;
+  };
+  readonly warnings: readonly unknown[];
+}
+
+export interface GenerateImageToolOptions {
+  readonly assetWriter?: StateFilesAssetWriter;
+  readonly declarationName?: string;
+  readonly generate?: (options: Parameters<typeof generateImage>[0]) => Promise<GeneratedImageResult>;
+  readonly randomId?: () => string;
+}
+
+interface ImageDimensionSettings {
+  readonly aspectRatio?: ImageAspectRatio;
+  readonly size?: ImageSize;
+}
+
+function assertNever(value: never): never {
+  throw new Error(`Unhandled generate_image dimensions: ${JSON.stringify(value)}`);
+}
+
+function imageDimensionSettings(
+  dimensions: GenerateImageDimensions | undefined,
+): ImageDimensionSettings {
+  if (dimensions === undefined || dimensions.kind === "auto") {
+    return {};
+  }
+
+  switch (dimensions.kind) {
+    case "aspectRatio":
+      return { aspectRatio: dimensions.aspectRatio };
+    case "size":
+      return { size: dimensions.size };
+    default:
+      return assertNever(dimensions);
+  }
+}
+
+function warningText(warning: unknown): string {
+  if (warning instanceof Error) {
+    return warning.message;
+  }
+  if (typeof warning === "string") {
+    return warning;
+  }
+
+  // The lib overload says `JSON.stringify` returns `string`, but it really
+  // returns `undefined` for symbols/functions — widen it back.
+  const json = JSON.stringify(warning) as string | undefined;
+  return json ?? String(warning);
+}
+
+function randomImageId(): string {
+  return randomUUID().slice(0, 8);
+}
+
+export function generateImageTool(options: GenerateImageToolOptions = {}) {
+  const declarationName = options.declarationName ?? DEFAULT_STATE_ASSET_DECLARATION_NAME;
+  const assetWriter =
+    options.assetWriter ?? createRuntimeStateFilesClient({ declarationName });
+  const generate = options.generate ?? generateImage;
+  const randomId = options.randomId ?? randomImageId;
+
+  return defineTool({
+    description: CLOUD_TOOL_META.image.description,
+    inputSchema: GenerateImageInputSchema,
+    outputSchema: GenerateImageOutputSchema,
+    async execute(input): Promise<GenerateImageOutput> {
+      const model = input.model ?? DEFAULT_IMAGE_MODEL;
+      const result = await generate({
+        headers: { [ZO_TOOL_HEADER]: "generate_image" },
+        model: zoGateway().imageModel(model),
+        prompt: input.prompt,
+        ...imageDimensionSettings(input.dimensions),
+        ...(input.seed === undefined ? {} : { seed: input.seed }),
+      });
+      const image = result.image;
+      const path = imageOutputPath({
+        id: randomId(),
+        mediaType: image.mediaType,
+        outputDir: input.outputDir,
+        prompt: input.prompt,
+      });
+
+      await assetWriter.write(path, image.uint8Array, { contentType: image.mediaType });
+      const asset: StateAssetReference = stateAssetReference({
+        type: "state_asset",
+        declarationName,
+        path,
+        contentType: image.mediaType,
+        bytes: image.uint8Array.byteLength,
+      });
+
+      return {
+        asset,
+        bytes: image.uint8Array.byteLength,
+        mediaType: image.mediaType,
+        model,
+        path,
+        prompt: input.prompt,
+        warnings: result.warnings.map(warningText),
+      };
+    },
+    toModelOutput(output) {
+      return {
+        type: "text",
+        value:
+          `Generated image saved as state asset ${output.asset.declarationName}:${output.asset.path}. ` +
+          `The asset is available to the chat UI through the state_asset reference; ` +
+          `do not invent or expose a temporary URL.`,
+      };
+    },
+  });
+}
+
+export default generateImageTool();

package/platform/cloud-tools/index.ts

@@ -0,0 +1,22 @@
+export {
+  DEFAULT_IMAGE_MODEL,
+  GenerateImageInputSchema,
+  GenerateImageOutputSchema,
+  default as generateImage,
+  generateImageTool,
+} from "./image";
+export type {
+  GenerateImageDimensions,
+  GenerateImageInput,
+  GenerateImageOutput,
+  GenerateImageToolOptions,
+} from "./image";
+export {
+  createRuntimeStateFilesClient,
+  DEFAULT_STATE_ASSET_DECLARATION_NAME,
+  stateAssetReference,
+} from "./state-files";
+export type { StateAssetReference, StateFilesAssetWriter } from "./state-files";
+
+export { webSearch } from "./web-search";
+export type { WebSearchConfig } from "./web-search";

package/platform/cloud-tools/state-files.ts

@@ -0,0 +1,368 @@
+import { ambientEveSessionId } from "../runtime-ai/session-fetch.ts";
+
+export const DEFAULT_STATE_ASSET_DECLARATION_NAME = "files";
+export const STATE_FILES_HANDLE_PATH = "/state/handles";
+export const ZO_AGENT_TOKEN_HEADER = "x-zo-agent-token";
+export const ZO_EVE_SESSION_HEADER = "x-zo-eve-session";
+
+const DEFAULT_STATE_FILES_SUGGESTED_DEFAULTS: RuntimeStateFilesSuggestedDefaults = Object.freeze({
+  engine: "zo-blob-r2",
+  partition: "session",
+});
+
+export interface StateAssetReference {
+  readonly type: "state_asset";
+  readonly declarationName: string;
+  readonly path: string;
+  readonly contentType?: string;
+  readonly bytes?: number;
+}
+
+interface StateFilesCredentials {
+  readonly accessKeyId: string;
+  readonly secretAccessKey: string;
+  readonly sessionToken: string;
+  readonly expiresAt: string;
+}
+
+interface StateFilesHandle {
+  readonly handleId: string;
+  readonly declarationName: string;
+  readonly interface: "files";
+  readonly access: "r" | "rw";
+  readonly engine: "zo-blob-r2";
+  readonly bucketName: string;
+  readonly endpoint: string;
+  readonly credentials: StateFilesCredentials;
+}
+
+export interface StateFilesWriteOptions {
+  readonly contentType?: string;
+}
+
+export interface StateFilesAssetWriter {
+  write(path: string, body: Uint8Array, options?: StateFilesWriteOptions): Promise<void>;
+}
+
+export interface RuntimeStateFilesClientOptions {
+  readonly apiBaseUrl?: string | URL | null;
+  readonly agentToken?: string | null;
+  readonly declarationName?: string;
+  readonly fetch?: typeof globalThis.fetch;
+  readonly getSessionId?: () => string | undefined;
+  readonly now?: () => Date;
+  readonly suggestedDefaults?: RuntimeStateFilesSuggestedDefaults;
+}
+
+export interface RuntimeStateFilesSuggestedDefaults {
+  readonly engine?: "zo-blob-r2";
+  readonly partition?: "none" | "team" | "user" | "session";
+}
+
+class StateFilesRuntimeError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StateFilesRuntimeError";
+  }
+}
+
+export function createRuntimeStateFilesClient(
+  options: RuntimeStateFilesClientOptions = {},
+): StateFilesAssetWriter {
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  const declarationName = options.declarationName ?? DEFAULT_STATE_ASSET_DECLARATION_NAME;
+  const getSessionId = options.getSessionId ?? ambientEveSessionId;
+  const now = options.now ?? (() => new Date());
+
+  return {
+    async write(path, body, writeOptions) {
+      const key = normalizeStateFilePath(path);
+      const eveSessionKey = getSessionId();
+      const handle = await requestRuntimeStateFilesHandle({
+        apiBaseUrl: resolveApiBaseUrl(options.apiBaseUrl),
+        agentToken: resolveAgentToken(options.agentToken),
+        declarationName,
+        fetch: fetchImpl,
+        suggestedDefaults: options.suggestedDefaults ?? DEFAULT_STATE_FILES_SUGGESTED_DEFAULTS,
+        ...(eveSessionKey === undefined ? {} : { eveSessionKey }),
+      });
+      if (handle.access !== "rw") {
+        throw new StateFilesRuntimeError(`state files handle "${handle.handleId}" is read-only`);
+      }
+      await putStateFileObject({
+        body,
+        bucketName: handle.bucketName,
+        credentials: handle.credentials,
+        endpoint: handle.endpoint,
+        fetch: fetchImpl,
+        key,
+        now,
+        ...(writeOptions?.contentType === undefined ? {} : { contentType: writeOptions.contentType }),
+      });
+    },
+  };
+}
+
+export function stateAssetReference(input: StateAssetReference): StateAssetReference {
+  return Object.freeze({
+    type: "state_asset",
+    declarationName: input.declarationName,
+    path: normalizeStateFilePath(input.path),
+    ...(input.contentType === undefined ? {} : { contentType: input.contentType }),
+    ...(input.bytes === undefined ? {} : { bytes: input.bytes }),
+  });
+}
+
+export function normalizeStateFilePath(path: string): string {
+  if (path.length === 0) throw new Error("state file path must not be empty");
+  if (path.startsWith("/")) throw new Error(`state file path "${path}" must be relative`);
+  const segments = path.split("/");
+  if (segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
+    throw new Error(`state file path "${path}" must not contain empty, . or .. segments`);
+  }
+  return path;
+}
+
+interface RequestRuntimeStateFilesHandleOptions {
+  readonly apiBaseUrl: string;
+  readonly agentToken: string;
+  readonly declarationName: string;
+  readonly eveSessionKey?: string;
+  readonly fetch: typeof globalThis.fetch;
+  readonly suggestedDefaults: RuntimeStateFilesSuggestedDefaults;
+}
+
+async function requestRuntimeStateFilesHandle(
+  options: RequestRuntimeStateFilesHandleOptions,
+): Promise<StateFilesHandle> {
+  const headers = new Headers({ "content-type": "application/json" });
+  headers.set(ZO_AGENT_TOKEN_HEADER, options.agentToken);
+  if (options.eveSessionKey !== undefined && options.eveSessionKey.trim().length > 0) {
+    headers.set(ZO_EVE_SESSION_HEADER, options.eveSessionKey.trim());
+  }
+
+  const response = await options.fetch(buildStateFilesHandleUrl(options.apiBaseUrl), {
+    method: "POST",
+    headers,
+    body: JSON.stringify({
+      declarationName: options.declarationName,
+      interface: "files",
+      access: "rw",
+      suggestedDefaults: options.suggestedDefaults,
+    }),
+  });
+  const json: unknown = await response.json().catch(() => null);
+  if (!response.ok) {
+    throw new StateFilesRuntimeError(readBrokerErrorMessage(json));
+  }
+  const handle = parseStateFilesHandle(json);
+  if (handle === null) {
+    throw new StateFilesRuntimeError("state files broker returned a malformed handle");
+  }
+  return handle;
+}
+
+function resolveApiBaseUrl(apiBaseUrl: string | URL | null | undefined): string {
+  const value = String(apiBaseUrl ?? process.env.ZO_API_URL ?? "").trim();
+  if (value.length === 0) {
+    throw new StateFilesRuntimeError("ZO_API_URL is required to write generated state assets");
+  }
+  return value;
+}
+
+function resolveAgentToken(agentToken: string | null | undefined): string {
+  const value = (agentToken ?? process.env.ZO_AGENT_TOKEN ?? "").trim();
+  if (value.length === 0) {
+    throw new StateFilesRuntimeError("ZO_AGENT_TOKEN is required to write generated state assets");
+  }
+  return value;
+}
+
+function buildStateFilesHandleUrl(apiBaseUrl: string): string {
+  const url = new URL(apiBaseUrl);
+  url.pathname = `${url.pathname.replace(/\/+$/u, "")}/${STATE_FILES_HANDLE_PATH.replace(/^\/+/, "")}`;
+  url.search = "";
+  url.hash = "";
+  return url.toString();
+}
+
+function parseStateFilesHandle(value: unknown): StateFilesHandle | null {
+  if (!isRecord(value)) return null;
+  if (value.interface !== "files" || value.engine !== "zo-blob-r2") return null;
+  const access = value.access === "r" || value.access === "rw" ? value.access : null;
+  const handleId = readString(value, "handleId");
+  const declarationName = readString(value, "declarationName");
+  const bucketName = readString(value, "bucketName");
+  const endpoint = readString(value, "endpoint");
+  const credentials = parseStateFilesCredentials(value.credentials);
+  if (
+    access === null ||
+    handleId === null ||
+    declarationName === null ||
+    bucketName === null ||
+    endpoint === null ||
+    credentials === null
+  ) {
+    return null;
+  }
+  return { handleId, declarationName, interface: "files", access, engine: "zo-blob-r2", bucketName, endpoint, credentials };
+}
+
+function parseStateFilesCredentials(value: unknown): StateFilesCredentials | null {
+  if (!isRecord(value)) return null;
+  const accessKeyId = readString(value, "accessKeyId");
+  const secretAccessKey = readString(value, "secretAccessKey");
+  const sessionToken = readString(value, "sessionToken");
+  const expiresAt = readString(value, "expiresAt");
+  if (
+    accessKeyId === null ||
+    secretAccessKey === null ||
+    sessionToken === null ||
+    expiresAt === null ||
+    !Number.isFinite(Date.parse(expiresAt))
+  ) {
+    return null;
+  }
+  return { accessKeyId, secretAccessKey, sessionToken, expiresAt };
+}
+
+function readBrokerErrorMessage(value: unknown): string {
+  if (!isRecord(value)) return "state files broker request failed";
+  const error = isRecord(value.error) ? value.error : value;
+  return readString(error, "message") ?? "state files broker request failed";
+}
+
+interface PutStateFileObjectOptions {
+  readonly endpoint: string;
+  readonly bucketName: string;
+  readonly credentials: StateFilesCredentials;
+  readonly key: string;
+  readonly body: Uint8Array;
+  readonly contentType?: string;
+  readonly fetch: typeof globalThis.fetch;
+  readonly now: () => Date;
+}
+
+async function putStateFileObject(options: PutStateFileObjectOptions): Promise<void> {
+  const url = stateFileObjectUrl(options.endpoint, options.bucketName, options.key);
+  const payloadHash = await sha256Hex(options.body);
+  const headers = await signedS3Headers({
+    credentials: options.credentials,
+    date: options.now(),
+    host: url.host,
+    method: "PUT",
+    path: url.pathname,
+    payloadHash,
+    ...(options.contentType === undefined ? {} : { contentType: options.contentType }),
+  });
+  const response = await options.fetch(url, {
+    method: "PUT",
+    headers,
+    body: options.body,
+  });
+  if (!response.ok) {
+    throw new StateFilesRuntimeError(`state asset write failed with ${response.status}`);
+  }
+}
+
+function stateFileObjectUrl(endpoint: string, bucketName: string, key: string): URL {
+  const base = endpoint.replace(/\/+$/u, "");
+  return new URL(`${base}/${encodeS3PathSegment(bucketName)}/${encodeS3Key(key)}`);
+}
+
+interface SignedS3HeadersInput {
+  readonly method: "PUT";
+  readonly path: string;
+  readonly host: string;
+  readonly payloadHash: string;
+  readonly credentials: StateFilesCredentials;
+  readonly date: Date;
+  readonly contentType?: string;
+}
+
+async function signedS3Headers(input: SignedS3HeadersInput): Promise<Headers> {
+  const amzDate = awsAmzDate(input.date);
+  const dateStamp = amzDate.slice(0, 8);
+  const headerEntries: [string, string][] = [
+    ["host", input.host],
+    ["x-amz-content-sha256", input.payloadHash],
+    ["x-amz-date", amzDate],
+    ["x-amz-security-token", input.credentials.sessionToken],
+  ];
+  if (input.contentType !== undefined) {
+    headerEntries.push(["content-type", input.contentType]);
+  }
+  headerEntries.sort(([left], [right]) => left.localeCompare(right));
+  const canonicalHeaders = headerEntries.map(([name, value]) => `${name}:${value.trim()}\n`).join("");
+  const signedHeaders = headerEntries.map(([name]) => name).join(";");
+  const canonicalRequest = [
+    input.method,
+    input.path,
+    "",
+    canonicalHeaders,
+    signedHeaders,
+    input.payloadHash,
+  ].join("\n");
+  const scope = `${dateStamp}/auto/s3/aws4_request`;
+  const stringToSign = [
+    "AWS4-HMAC-SHA256",
+    amzDate,
+    scope,
+    await sha256Hex(new TextEncoder().encode(canonicalRequest)),
+  ].join("\n");
+  const signingKey = await awsSigningKey(input.credentials.secretAccessKey, dateStamp);
+  const signature = await hmacHex(signingKey, stringToSign);
+  const headers = new Headers();
+  for (const [name, value] of headerEntries) headers.set(name, value);
+  headers.set(
+    "authorization",
+    `AWS4-HMAC-SHA256 Credential=${input.credentials.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`,
+  );
+  return headers;
+}
+
+async function awsSigningKey(secretAccessKey: string, dateStamp: string): Promise<Uint8Array> {
+  const dateKey = await hmacBytes(new TextEncoder().encode(`AWS4${secretAccessKey}`), dateStamp);
+  const regionKey = await hmacBytes(dateKey, "auto");
+  const serviceKey = await hmacBytes(regionKey, "s3");
+  return hmacBytes(serviceKey, "aws4_request");
+}
+
+async function hmacBytes(key: Uint8Array, data: string): Promise<Uint8Array> {
+  const cryptoKey = await crypto.subtle.importKey("raw", key, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  return new Uint8Array(await crypto.subtle.sign("HMAC", cryptoKey, new TextEncoder().encode(data)));
+}
+
+async function hmacHex(key: Uint8Array, data: string): Promise<string> {
+  return bytesToHex(await hmacBytes(key, data));
+}
+
+async function sha256Hex(bytes: Uint8Array): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return bytesToHex(new Uint8Array(digest));
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function awsAmzDate(date: Date): string {
+  return date.toISOString().replace(/[:-]|\.\d{3}/gu, "");
+}
+
+function encodeS3Key(key: string): string {
+  return key.split("/").map(encodeS3PathSegment).join("/");
+}
+
+function encodeS3PathSegment(segment: string): string {
+  return encodeURIComponent(segment).replace(/[!'()*]/gu, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readString(record: Record<string, unknown>, key: string): string | null {
+  const value = record[key];
+  return typeof value === "string" && value.length > 0 ? value : null;
+}

package/platform/cloud-tools/tool-meta.ts

@@ -0,0 +1,32 @@
+// The single source of truth for each built-in Zo cloud tool's user-facing
+// metadata — today just its description. Consumed on BOTH sides of a gap the
+// tool object can't bridge:
+//   - the tool definition itself (`image.ts` reads its `description` from here), and
+//   - `apps/api`'s definition parser, which shows a stored agent's tools in the
+//     /build Settings tab. That parser reads tenant tool files as TEXT (it never
+//     imports/executes them), and a built-in is seeded as a one-line re-export —
+//     `export { default } from "./image.ts"` — that carries no
+//     `description:` string of its own. It looks the built-in up here instead.
+//
+// Keyed by the tool's `@zocomputer/cloud-tools/<key>` subpath segment (the seed's
+// re-export target), NOT the wire name the model sees (the tool file's name, e.g.
+// `generate_image`). Keep this module import-light — no `ai`/`eve`/`zod`/runtime —
+// so `apps/api` can import it without pulling the agent-runtime deps into its bundle.
+export const CLOUD_TOOL_META = {
+  image: {
+    description: "Generate an image from a text prompt and save it as an external state asset.",
+  },
+} as const;
+
+export type CloudToolName = keyof typeof CLOUD_TOOL_META;
+export type CloudToolMeta = (typeof CLOUD_TOOL_META)[CloudToolName];
+
+/**
+ * Metadata for a built-in cloud tool by its `@zocomputer/cloud-tools/<key>`
+ * subpath segment, or `null` for an unknown key — the checked lookup callers
+ * use to resolve an arbitrary (untrusted) string against the map. The `as
+ * CloudToolName` is proven safe by the preceding `in` guard and isolated here.
+ */
+export function cloudToolMeta(key: string): CloudToolMeta | null {
+  return key in CLOUD_TOOL_META ? CLOUD_TOOL_META[key as CloudToolName] : null;
+}

package/platform/cloud-tools/web-search.ts

@@ -0,0 +1,15 @@
+import { zoGateway } from "../runtime-ai/index.ts";
+
+type Gateway = ReturnType<typeof zoGateway>;
+type ExaSearchFactory = Gateway["tools"]["exaSearch"];
+
+export type WebSearchConfig = Parameters<ExaSearchFactory>[0];
+
+export function webSearch(config?: WebSearchConfig): ReturnType<ExaSearchFactory> {
+  const gateway = zoGateway();
+  return config === undefined
+    ? gateway.tools.exaSearch()
+    : gateway.tools.exaSearch(config);
+}
+
+export default webSearch;