@smithers-orchestrator/agents 0.24.0 → 0.25.0

package/src/createElevenLabsTextToSpeechTool.js

@@ -0,0 +1,128 @@
+import { dynamicTool, jsonSchema } from "ai";
+
+const DEFAULT_BASE_URL = "https://api.elevenlabs.io";
+const DEFAULT_MODEL_ID = "eleven_turbo_v2_5";
+const DEFAULT_VOICE_ID = "21m00Tcm4TlvDq8ikWAM";
+const TOOL_NAME = "elevenlabs_text_to_speech";
+
+const inputSchema = {
+  type: "object",
+  properties: {
+    text: {
+      type: "string",
+      minLength: 1,
+      description: "Text to synthesize into speech.",
+    },
+    voiceId: {
+      type: "string",
+      minLength: 1,
+      description: "Optional ElevenLabs voice id. Defaults to the configured voice.",
+    },
+    modelId: {
+      type: "string",
+      minLength: 1,
+      description: "Optional ElevenLabs model id. Defaults to the configured model.",
+    },
+    voiceSettings: {
+      type: "object",
+      additionalProperties: true,
+      description: "Optional ElevenLabs voice_settings payload.",
+    },
+  },
+  required: ["text"],
+  additionalProperties: false,
+};
+
+/**
+ * Create an agent-callable ElevenLabs text-to-speech tool.
+ *
+ * @param {import("./createElevenLabsTextToSpeechTool.ts").ElevenLabsTextToSpeechToolOptions} options
+ * @returns {import("./createElevenLabsTextToSpeechTool.ts").ElevenLabsTextToSpeechToolset}
+ */
+export function createElevenLabsTextToSpeechTool(options) {
+  if (!options?.apiKey) {
+    throw new Error("createElevenLabsTextToSpeechTool requires an ElevenLabs apiKey");
+  }
+
+  const fetchImpl = options.fetch ?? globalThis.fetch;
+  if (typeof fetchImpl !== "function") {
+    throw new Error("createElevenLabsTextToSpeechTool requires fetch");
+  }
+
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const defaultVoiceId = options.defaultVoiceId ?? DEFAULT_VOICE_ID;
+  const defaultModelId = options.defaultModelId ?? DEFAULT_MODEL_ID;
+
+  return {
+    tools: {
+      [TOOL_NAME]: dynamicTool({
+        description: "Synthesize speech audio from text using ElevenLabs.",
+        inputSchema: jsonSchema(inputSchema),
+        execute: async (input) =>
+          synthesizeSpeech({
+            apiKey: options.apiKey,
+            baseUrl,
+            defaultVoiceId,
+            defaultModelId,
+            fetchImpl,
+            input,
+          }),
+      }),
+    },
+    toolNames: [TOOL_NAME],
+  };
+}
+
+/**
+ * @param {{
+ *   apiKey: string;
+ *   baseUrl: string;
+ *   defaultVoiceId: string;
+ *   defaultModelId: string;
+ *   fetchImpl: typeof fetch;
+ *   input: unknown;
+ * }} params
+ */
+async function synthesizeSpeech({ apiKey, baseUrl, defaultVoiceId, defaultModelId, fetchImpl, input }) {
+  const args = /** @type {import("./createElevenLabsTextToSpeechTool.ts").ElevenLabsTextToSpeechInput} */ (
+    input ?? {}
+  );
+  if (typeof args.text !== "string" || args.text.trim() === "") {
+    throw new Error("elevenlabs_text_to_speech requires non-empty text");
+  }
+
+  const voiceId = args.voiceId ?? defaultVoiceId;
+  const modelId = args.modelId ?? defaultModelId;
+  const body = {
+    text: args.text,
+    model_id: modelId,
+    ...(args.voiceSettings ? { voice_settings: args.voiceSettings } : {}),
+  };
+
+  const response = await fetchImpl(`${baseUrl}/v1/text-to-speech/${encodeURIComponent(voiceId)}`, {
+    method: "POST",
+    headers: {
+      Accept: "audio/mpeg",
+      "Content-Type": "application/json",
+      "xi-api-key": apiKey,
+    },
+    body: JSON.stringify(body),
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text().catch(() => "");
+    throw new Error(
+      `ElevenLabs text-to-speech failed with ${response.status}${errorText ? `: ${errorText}` : ""}`,
+    );
+  }
+
+  const contentType = response.headers.get("content-type") ?? "audio/mpeg";
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  return {
+    audioBase64: Buffer.from(bytes).toString("base64"),
+    contentType,
+    voiceId,
+    modelId,
+    byteLength: bytes.byteLength,
+  };
+}

package/src/createElevenLabsTextToSpeechTool.ts

@@ -0,0 +1,33 @@
+import type { Tool } from "ai";
+
+export type ElevenLabsTextToSpeechInput = {
+  text: string;
+  voiceId?: string;
+  modelId?: string;
+  voiceSettings?: Record<string, unknown>;
+};
+
+export type ElevenLabsTextToSpeechResult = {
+  audioBase64: string;
+  contentType: string;
+  voiceId: string;
+  modelId: string;
+  byteLength: number;
+};
+
+export type ElevenLabsTextToSpeechToolOptions = {
+  apiKey: string;
+  defaultVoiceId?: string;
+  defaultModelId?: string;
+  baseUrl?: string;
+  fetch?: typeof fetch;
+};
+
+export type ElevenLabsTextToSpeechToolset = {
+  tools: Record<"elevenlabs_text_to_speech", Tool>;
+  toolNames: ["elevenlabs_text_to_speech"];
+};
+
+export declare function createElevenLabsTextToSpeechTool(
+  options: ElevenLabsTextToSpeechToolOptions,
+): ElevenLabsTextToSpeechToolset;

package/src/diagnostics/getDiagnosticStrategy.js

@@ -9,6 +9,9 @@ import { spawnSync } from "node:child_process";
 /**
  * @typedef {{ id: DiagnosticCheckId; run: (ctx: DiagnosticContext) => Promise<DiagnosticCheck>; }} DiagnosticCheckDef
  */
+/**
+ * @typedef {{ provider?: string; model?: string; apiKey?: string }} DiagnosticHints
+ */
 
 // ---------------------------------------------------------------------------
 // Shared check helpers
@@ -187,6 +190,17 @@ const claudeStrategy = {
 // ---------------------------------------------------------------------------
 // Codex strategy
 // ---------------------------------------------------------------------------
+/**
+ * Resolve the OpenAI models endpoint, honoring OPENAI_BASE_URL (Azure, proxies,
+ * OpenAI-compatible gateways, and hermetic test fixtures) the same way the
+ * OpenAI SDK and codex do. Defaults to the public API, so existing behavior is
+ * unchanged when the variable is unset.
+ * @param {Record<string, string | undefined>} env
+ */
+function openaiModelsUrl(env) {
+    const base = (env.OPENAI_BASE_URL ?? "https://api.openai.com/v1").replace(/\/+$/, "");
+    return `${base}/models`;
+}
 // Combined API key validation + rate limit check via GET /v1/models (free, no tokens)
 const codexApiKeyAndRateLimitCheck = [
     {
@@ -203,7 +217,7 @@ const codexApiKeyAndRateLimitCheck = [
                 };
             }
             try {
-                const res = await fetch("https://api.openai.com/v1/models", {
+                const res = await fetch(openaiModelsUrl(ctx.env), {
                     headers: { Authorization: `Bearer ${apiKey}` },
                     signal: AbortSignal.timeout(4_000),
                 });
@@ -255,7 +269,7 @@ const codexApiKeyAndRateLimitCheck = [
                 };
             }
             try {
-                const res = await fetch("https://api.openai.com/v1/models", {
+                const res = await fetch(openaiModelsUrl(ctx.env), {
                     headers: { Authorization: `Bearer ${apiKey}` },
                     signal: AbortSignal.timeout(4_000),
                 });
@@ -429,15 +443,6 @@ const googleRateLimitCheck = {
         }
     },
 };
-const geminiStrategy = {
-    agentId: "gemini",
-    command: "gemini",
-    checks: [
-        checkCliInstalled("gemini", "Gemini CLI"),
-        googleAuthCheck,
-        googleRateLimitCheck,
-    ],
-};
 const antigravityAuthSkip = {
     id: "api_key_valid",
     run: async () => {
@@ -472,15 +477,75 @@ const antigravityStrategy = {
 // ---------------------------------------------------------------------------
 // Pi strategy
 // ---------------------------------------------------------------------------
-const piStrategy = {
-    agentId: "pi",
-    command: "pi",
-    checks: [
-        checkCliInstalled("pi", "Pi"),
-        googleAuthCheck,
-        googleRateLimitCheck,
-    ],
-};
+/**
+ * Resolve the effective pi provider family from an explicit `--provider`, a
+ * `provider/model` prefix, or a bare model id's well-known prefix. Returns ""
+ * when undeterminable so callers fall back to pi's default (google) (#284).
+ * @param {DiagnosticHints | undefined} hints
+ * @returns {string}
+ */
+function resolvePiProvider(hints) {
+    const explicit = (hints?.provider || "").trim().toLowerCase();
+    if (explicit) {
+        return explicit;
+    }
+    const model = typeof hints?.model === "string" ? hints.model.trim().toLowerCase() : "";
+    if (!model) {
+        return "";
+    }
+    if (model.includes("/")) {
+        return model.split("/")[0];
+    }
+    // Bare model id (no provider prefix) — infer the provider family from
+    // common id prefixes so diagnostics probe the right backend.
+    if (model.startsWith("gpt-") || model.startsWith("o1-") || model.startsWith("o3-") || model.startsWith("o4-") || model.startsWith("chatgpt")) {
+        return "openai";
+    }
+    if (model.startsWith("claude")) {
+        return "anthropic";
+    }
+    if (model.startsWith("gemini")) {
+        return "google";
+    }
+    return "";
+}
+/**
+ * @param {DiagnosticHints | undefined} hints
+ * @returns {DiagnosticCheckDef[]}
+ */
+function piProviderChecks(hints) {
+    const raw = resolvePiProvider(hints);
+    if (raw === "openai" || raw === "openai-codex" || raw === "azure" || raw === "azure-openai") {
+        return [...codexApiKeyAndRateLimitCheck];
+    }
+    if (raw === "anthropic" || raw === "claude") {
+        return [claudeApiKeyCheck, claudeRateLimitCheck];
+    }
+    return [googleAuthCheck, googleRateLimitCheck];
+}
+/**
+ * pi accepts credentials via the `--api-key` option instead of an environment
+ * variable. Diagnostics only see the process env, so map an explicit apiKey to
+ * the env var the selected provider's checks read — otherwise an apiKey-only pi
+ * run is misreported as "key missing" (#284). Returns undefined when there is
+ * nothing to inject.
+ * @param {string} command
+ * @param {DiagnosticHints | undefined} hints
+ * @returns {Record<string, string> | undefined}
+ */
+export function diagnosticApiKeyEnv(command, hints) {
+    if (command !== "pi" || !hints?.apiKey) {
+        return undefined;
+    }
+    const raw = resolvePiProvider(hints);
+    if (raw === "openai" || raw === "openai-codex" || raw === "azure" || raw === "azure-openai") {
+        return { OPENAI_API_KEY: hints.apiKey };
+    }
+    if (raw === "anthropic" || raw === "claude") {
+        return { ANTHROPIC_API_KEY: hints.apiKey };
+    }
+    return { GOOGLE_API_KEY: hints.apiKey };
+}
 // ---------------------------------------------------------------------------
 // Amp strategy
 // ---------------------------------------------------------------------------
@@ -523,14 +588,20 @@ const strategies = {
     codex: codexStrategy,
     antigravity: antigravityStrategy,
     agy: antigravityStrategy,
-    gemini: geminiStrategy,
-    pi: piStrategy,
     amp: ampStrategy,
 };
 /**
  * @param {string} command
+ * @param {DiagnosticHints} [hints]
  * @returns {AgentDiagnosticStrategy | null}
  */
-export function getDiagnosticStrategy(command) {
+export function getDiagnosticStrategy(command, hints) {
+    if (command === "pi") {
+        return {
+            agentId: "pi",
+            command: "pi",
+            checks: [checkCliInstalled("pi", "Pi"), ...piProviderChecks(hints)],
+        };
+    }
     return strategies[command] ?? null;
 }

package/src/diagnostics/launchDiagnostics.js

@@ -1,4 +1,4 @@
-import { getDiagnosticStrategy } from "./getDiagnosticStrategy.js";
+import { diagnosticApiKeyEnv, getDiagnosticStrategy } from "./getDiagnosticStrategy.js";
 import { runDiagnostics } from "./runDiagnostics.js";
 /** @typedef {import("./DiagnosticReport.ts").DiagnosticReport} DiagnosticReport */
 
@@ -6,11 +6,14 @@ import { runDiagnostics } from "./runDiagnostics.js";
  * @param {string} command
  * @param {Record<string, string>} env
  * @param {string} cwd
+ * @param {{ provider?: string; model?: string; apiKey?: string }} [hints]
  * @returns {Promise<DiagnosticReport> | null}
  */
-export function launchDiagnostics(command, env, cwd) {
-    const strategy = getDiagnosticStrategy(command);
+export function launchDiagnostics(command, env, cwd, hints) {
+    const strategy = getDiagnosticStrategy(command, hints);
     if (!strategy)
         return null;
-    return runDiagnostics(strategy, { env, cwd }).catch(() => null);
+    const apiKeyEnv = diagnosticApiKeyEnv(command, hints);
+    const effectiveEnv = apiKeyEnv ? { ...env, ...apiKeyEnv } : env;
+    return runDiagnostics(strategy, { env: effectiveEnv, cwd }).catch(() => null);
 }

package/src/document-parsing/DocumentParsingProvider.ts

@@ -0,0 +1,13 @@
+import type { DocumentParsingResult } from "./DocumentParsingResult.ts";
+
+export type DocumentParsingProvider = {
+  name: "firecrawl" | "mistral-ocr" | "llamaparse" | string;
+  parseDocument: (input: {
+    source:
+      | { type: "url"; url: string }
+      | { type: "base64"; data: string; mimeType?: string; filename?: string }
+      | { type: "text"; text: string; filename?: string };
+    outputFormat?: "text" | "markdown" | "json";
+    instructions?: string;
+  }) => Promise<DocumentParsingResult>;
+};

package/src/document-parsing/DocumentParsingResult.ts

@@ -0,0 +1,13 @@
+export type DocumentParsingResult = {
+  provider: "firecrawl" | "mistral-ocr" | "llamaparse" | string;
+  text: string;
+  markdown?: string;
+  pages?: Array<{
+    index: number;
+    text?: string;
+    markdown?: string;
+    images?: unknown[];
+  }>;
+  metadata?: Record<string, unknown>;
+  raw?: unknown;
+};

package/src/document-parsing/DocumentParsingToolset.ts

@@ -0,0 +1,4 @@
+export type DocumentParsingToolset = {
+  tools: Record<string, import("ai").Tool>;
+  toolNames: string[];
+};

package/src/document-parsing/DocumentParsingToolsetOptions.ts

@@ -0,0 +1,9 @@
+import type { DocumentParsingProvider } from "./DocumentParsingProvider.ts";
+
+export type DocumentParsingToolsetOptions = {
+  provider?: "firecrawl" | "mistral-ocr" | "llamaparse" | DocumentParsingProvider;
+  apiKey?: string;
+  baseUrl?: string;
+  toolName?: string;
+  fetch?: typeof fetch;
+};

package/src/document-parsing/createDocumentParsingToolset.d.ts

@@ -0,0 +1,9 @@
+import type { DocumentParsingToolset } from "./DocumentParsingToolset.js";
+import type { DocumentParsingToolsetOptions } from "./DocumentParsingToolsetOptions.js";
+
+export type { DocumentParsingProvider } from "./DocumentParsingProvider.js";
+export type { DocumentParsingResult } from "./DocumentParsingResult.js";
+export type { DocumentParsingToolset } from "./DocumentParsingToolset.js";
+export type { DocumentParsingToolsetOptions } from "./DocumentParsingToolsetOptions.js";
+
+export declare function createDocumentParsingToolset(options?: DocumentParsingToolsetOptions): DocumentParsingToolset;