@smithers-orchestrator/agents 0.24.2 → 0.25.0

package/src/http/createHttpTool.js

@@ -0,0 +1,136 @@
+import { dynamicTool } from "ai";
+import { z } from "zod";
+
+/** @typedef {import("ai").Tool} Tool */
+/** @typedef {import("./CreateHttpToolOptions.ts").CreateHttpToolOptions} CreateHttpToolOptions */
+/** @typedef {import("./HttpToolInput.ts").HttpToolInput} HttpToolInput */
+/** @typedef {import("./HttpToolOutput.ts").HttpToolOutput} HttpToolOutput */
+
+const httpToolInputSchema = z.object({
+  method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]).optional().default("GET"),
+  url: z.string().url(),
+  headers: z.record(z.string(), z.string()).optional(),
+  query: z.record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null(), z.undefined()])).optional(),
+  body: z.unknown().optional(),
+  auth: z
+    .discriminatedUnion("type", [
+      z.object({ type: z.literal("bearer"), token: z.string() }),
+      z.object({ type: z.literal("basic"), username: z.string(), password: z.string() }),
+      z.object({ type: z.literal("header"), name: z.string(), value: z.string() }),
+    ])
+    .optional(),
+  timeoutMs: z.number().int().positive().optional(),
+});
+
+/**
+ * Create an AI SDK tool that can call any REST API without an OpenAPI spec.
+ *
+ * @param {CreateHttpToolOptions} [options]
+ * @returns {Tool}
+ */
+export function createHttpTool(options = {}) {
+  return dynamicTool({
+    description:
+      options.description ??
+      "Call any REST API by providing method, url, headers, query params, body, and optional auth.",
+    inputSchema: httpToolInputSchema,
+    execute: async (input) => executeHttpRequest(/** @type {HttpToolInput} */ (input), options),
+  });
+}
+
+/**
+ * @param {HttpToolInput} input
+ * @param {CreateHttpToolOptions} options
+ * @returns {Promise<HttpToolOutput>}
+ */
+async function executeHttpRequest(input, options) {
+  const url = new URL(input.url);
+  for (const [key, value] of Object.entries(input.query ?? {})) {
+    if (value !== null && value !== undefined) {
+      url.searchParams.set(key, String(value));
+    }
+  }
+
+  const headers = new Headers(options.defaultHeaders ?? {});
+  for (const [key, value] of Object.entries(input.headers ?? {})) {
+    headers.set(key, value);
+  }
+  applyAuth(headers, input.auth);
+
+  const init = /** @type {RequestInit} */ ({
+    method: input.method ?? "GET",
+    headers,
+  });
+  if (input.body !== undefined && init.method !== "GET" && init.method !== "HEAD") {
+    init.body = serializeBody(input.body, headers);
+  }
+
+  const controller = input.timeoutMs ? new AbortController() : null;
+  const timeout = controller ? setTimeout(() => controller.abort(), input.timeoutMs) : null;
+  if (controller) {
+    init.signal = controller.signal;
+  }
+  try {
+    const response = await fetch(url, init);
+    return {
+      ok: response.ok,
+      status: response.status,
+      statusText: response.statusText,
+      headers: Object.fromEntries(response.headers.entries()),
+      body: await parseResponseBody(response),
+    };
+  } finally {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+  }
+}
+
+/**
+ * @param {Headers} headers
+ * @param {HttpToolInput["auth"]} auth
+ */
+function applyAuth(headers, auth) {
+  if (!auth) return;
+  if (auth.type === "bearer") {
+    headers.set("authorization", `Bearer ${auth.token}`);
+  } else if (auth.type === "basic") {
+    headers.set("authorization", `Basic ${btoa(`${auth.username}:${auth.password}`)}`);
+  } else {
+    headers.set(auth.name, auth.value);
+  }
+}
+
+/**
+ * @param {unknown} body
+ * @param {Headers} headers
+ * @returns {BodyInit}
+ */
+function serializeBody(body, headers) {
+  if (typeof body === "string" || body instanceof Blob || body instanceof FormData || body instanceof URLSearchParams) {
+    return body;
+  }
+  if (!headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+  return JSON.stringify(body);
+}
+
+/**
+ * @param {Response} response
+ * @returns {Promise<unknown>}
+ */
+async function parseResponseBody(response) {
+  if (response.status === 204 || response.status === 205) {
+    return null;
+  }
+  const text = await response.text();
+  if (!text) {
+    return null;
+  }
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    return JSON.parse(text);
+  }
+  return text;
+}

package/src/image-generation/ImageGenerationProvider.ts

@@ -0,0 +1,7 @@
+import type { ImageGenerationRequest } from "./ImageGenerationRequest.js";
+import type { ImageGenerationResult } from "./ImageGenerationResult.js";
+
+export type ImageGenerationProvider = {
+  name?: string;
+  generateImage(request: ImageGenerationRequest): Promise<ImageGenerationResult> | ImageGenerationResult;
+};

package/src/image-generation/ImageGenerationRequest.ts

@@ -0,0 +1,8 @@
+export type ImageGenerationRequest = {
+  prompt: string;
+  model?: string;
+  size?: string;
+  count?: number;
+  seed?: number;
+  style?: string;
+};

package/src/image-generation/ImageGenerationResult.ts

@@ -0,0 +1,10 @@
+export type ImageGenerationResult = {
+  provider?: string;
+  model?: string;
+  images: Array<{
+    url?: string;
+    base64?: string;
+    mimeType?: string;
+    revisedPrompt?: string;
+  }>;
+};

package/src/image-generation/ImageGenerationToolOptions.ts

@@ -0,0 +1,10 @@
+export type ImageGenerationToolOptions = {
+  /** Tool name used when returning a toolset. */
+  name?: string;
+  /** Description shown to the model. */
+  description?: string;
+  /** Provider model to use when the agent does not specify one. */
+  model?: string;
+  /** Return `{ [name]: tool }` for direct mounting on an agent. */
+  asToolset?: boolean;
+};

package/src/image-generation/createImageGenerationTool.d.ts

@@ -0,0 +1,18 @@
+import type { Tool } from "ai";
+import type { ImageGenerationProvider } from "./ImageGenerationProvider.js";
+import type { ImageGenerationToolOptions } from "./ImageGenerationToolOptions.js";
+
+export type { ImageGenerationProvider } from "./ImageGenerationProvider.js";
+export type { ImageGenerationRequest } from "./ImageGenerationRequest.js";
+export type { ImageGenerationResult } from "./ImageGenerationResult.js";
+export type { ImageGenerationToolOptions } from "./ImageGenerationToolOptions.js";
+
+export declare function createImageGenerationTool(
+  provider: ImageGenerationProvider,
+  options: ImageGenerationToolOptions & { asToolset: true },
+): Record<string, Tool>;
+
+export declare function createImageGenerationTool(
+  provider: ImageGenerationProvider,
+  options?: ImageGenerationToolOptions,
+): Tool;

package/src/image-generation/createImageGenerationTool.js

@@ -0,0 +1,92 @@
+import { dynamicTool, jsonSchema } from "ai";
+
+/** @typedef {import("ai").Tool} Tool */
+/** @typedef {import("./ImageGenerationProvider.ts").ImageGenerationProvider} ImageGenerationProvider */
+/** @typedef {import("./ImageGenerationToolOptions.ts").ImageGenerationToolOptions} ImageGenerationToolOptions */
+/** @typedef {import("./ImageGenerationRequest.ts").ImageGenerationRequest} ImageGenerationRequest */
+
+const DEFAULT_TOOL_NAME = "generate_image";
+
+const imageGenerationInputSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["prompt"],
+  properties: {
+    prompt: {
+      type: "string",
+      description: "A detailed description of the image to generate.",
+      minLength: 1,
+    },
+    model: {
+      type: "string",
+      description: "Optional provider model override.",
+    },
+    size: {
+      type: "string",
+      description: "Requested output size, such as 1024x1024.",
+    },
+    count: {
+      type: "integer",
+      description: "Number of images to generate.",
+      minimum: 1,
+      maximum: 10,
+    },
+    seed: {
+      type: "integer",
+      description: "Optional deterministic seed when supported by the provider.",
+    },
+    style: {
+      type: "string",
+      description: "Optional provider-specific style hint.",
+    },
+  },
+};
+
+/**
+ * Create an agent-callable image generation primitive backed by a provider.
+ *
+ * The provider boundary keeps Smithers independent of any single image model
+ * vendor while still exposing a stable tool surface to AI SDK agents.
+ *
+ * @param {ImageGenerationProvider} provider
+ * @param {ImageGenerationToolOptions} [options]
+ * @returns {Tool | Record<string, Tool>}
+ */
+export function createImageGenerationTool(provider, options = {}) {
+  if (!provider || typeof provider.generateImage !== "function") {
+    throw new TypeError("createImageGenerationTool requires a provider with generateImage(request)");
+  }
+
+  const tool = dynamicTool({
+    description:
+      options.description ??
+      "Generate images from a prompt. Returns image URLs or base64 image payloads from the configured provider.",
+    inputSchema: jsonSchema(imageGenerationInputSchema),
+    execute: async (input) => provider.generateImage(normalizeImageGenerationInput(input, options)),
+  });
+
+  if (options.asToolset) {
+    return { [options.name ?? DEFAULT_TOOL_NAME]: tool };
+  }
+  return tool;
+}
+
+/**
+ * @param {unknown} input
+ * @param {ImageGenerationToolOptions} options
+ * @returns {ImageGenerationRequest}
+ */
+function normalizeImageGenerationInput(input, options) {
+  const value = /** @type {Partial<ImageGenerationRequest>} */ (input ?? {});
+  if (typeof value.prompt !== "string" || value.prompt.trim() === "") {
+    throw new TypeError("generate_image requires a non-empty prompt");
+  }
+  return {
+    prompt: value.prompt,
+    ...(typeof value.size === "string" ? { size: value.size } : {}),
+    ...(typeof value.count === "number" ? { count: value.count } : {}),
+    ...(typeof value.seed === "number" ? { seed: value.seed } : {}),
+    ...(typeof value.style === "string" ? { style: value.style } : {}),
+    ...(typeof value.model === "string" ? { model: value.model } : options.model ? { model: options.model } : {}),
+  };
+}