@nebutra/agents 1.1.1 → 1.1.2

package/src/__tests__/fallback-wiring.test.ts

@@ -1,313 +0,0 @@
-/**
- * Fallback wiring — verifies that the multi-provider fallback chain is
- * actually integrated into:
- *
- *   1. `VercelAIAgent.execute()` — chat path via `streamText`
- *   2. `embed()` / `embedMany()` — embedding path
- *
- * The AI SDK + provider SDKs are mocked so no network traffic occurs.
- */
-
-import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
-
-import { _resetAgentsEnvCache } from "../env";
-import { filterAvailableProviders, runEmbedWithFallback, runWithFallback } from "../fallback";
-
-// ─── Mock the dynamically-imported provider SDKs ─────────────────────────────
-// We mock at the module level so any `await import("@ai-sdk/...")` inside
-// `buildModel()` / `buildEmbeddingModel()` returns a deterministic stub.
-
-vi.mock("@openrouter/ai-sdk-provider", () => ({
-  createOpenRouter: vi.fn(() => ({
-    chat: vi.fn((id: string) => ({ __provider: "openrouter", __id: id })),
-    textEmbeddingModel: vi.fn((id: string) => ({
-      __provider: "openrouter",
-      __id: id,
-      __kind: "embedding",
-    })),
-  })),
-}));
-
-vi.mock("@ai-sdk/anthropic", () => ({
-  createAnthropic: vi.fn(() =>
-    Object.assign((id: string) => ({ __provider: "anthropic", __id: id }), {
-      __provider: "anthropic",
-    }),
-  ),
-}));
-
-vi.mock("@ai-sdk/openai", () => ({
-  createOpenAI: vi.fn(() =>
-    Object.assign((id: string) => ({ __provider: "openai", __id: id }), {
-      __provider: "openai",
-      textEmbeddingModel: vi.fn((id: string) => ({
-        __provider: "openai",
-        __id: id,
-        __kind: "embedding",
-      })),
-    }),
-  ),
-}));
-
-// ─── filterAvailableProviders ───────────────────────────────────────────────
-
-describe("filterAvailableProviders()", () => {
-  beforeEach(() => {
-    vi.unstubAllEnvs();
-    _resetAgentsEnvCache();
-  });
-
-  afterEach(() => {
-    vi.unstubAllEnvs();
-    _resetAgentsEnvCache();
-  });
-
-  it("filters out providers whose API key is missing", () => {
-    vi.stubEnv("OPENROUTER_API_KEY", "or-key");
-    vi.stubEnv("ANTHROPIC_API_KEY", "");
-    vi.stubEnv("OPENAI_API_KEY", "");
-
-    const out = filterAvailableProviders(["openrouter", "anthropic", "openai"]);
-    expect(out).toEqual(["openrouter"]);
-  });
-
-  it("returns the original chain when NO providers have keys (avoid empty)", () => {
-    vi.stubEnv("OPENROUTER_API_KEY", "");
-    vi.stubEnv("ANTHROPIC_API_KEY", "");
-    vi.stubEnv("OPENAI_API_KEY", "");
-
-    const out = filterAvailableProviders(["openrouter", "anthropic"]);
-    expect(out).toEqual(["openrouter", "anthropic"]);
-  });
-});
-
-// ─── Single-provider config: backward compatibility ──────────────────────────
-
-describe("runWithFallback — single-provider config", () => {
-  beforeEach(() => {
-    vi.unstubAllEnvs();
-    _resetAgentsEnvCache();
-    vi.stubEnv("OPENROUTER_API_KEY", "or-key");
-    // Anthropic + OpenAI deliberately missing — chain should be filtered
-    // down to just openrouter.
-  });
-
-  afterEach(() => {
-    vi.unstubAllEnvs();
-    _resetAgentsEnvCache();
-  });
-
-  it("does not rotate when only one provider key is present", async () => {
-    let calls = 0;
-    const result = await runWithFallback(
-      async () => {
-        calls += 1;
-        return "ok" as const;
-      },
-      { chain: ["openrouter", "anthropic", "openai"] },
-    );
-
-    expect(result.result).toBe("ok");
-    expect(result.attempts).toBe(1);
-    expect(result.provider).toBe("openrouter");
-    expect(calls).toBe(1);
-  });
-});
-
-// ─── Embedding fallback rotation ─────────────────────────────────────────────
-
-describe("runEmbedWithFallback()", () => {
-  beforeEach(() => {
-    vi.unstubAllEnvs();
-    _resetAgentsEnvCache();
-    vi.stubEnv("OPENROUTER_API_KEY", "or-key");
-    vi.stubEnv("OPENAI_API_KEY", "oa-key");
-  });
-
-  afterEach(() => {
-    vi.unstubAllEnvs();
-    _resetAgentsEnvCache();
-  });
-
-  it("rotates to the next embedding provider on retryable error", async () => {
-    let calls = 0;
-    const result = await runEmbedWithFallback(
-      async () => {
-        calls += 1;
-        if (calls === 1) {
-          throw Object.assign(new Error("Rate Limited"), { statusCode: 429 });
-        }
-        return { embeddings: [[0.1, 0.2]] } as const;
-      },
-      { chain: ["openrouter", "openai"] },
-    );
-
-    expect(calls).toBe(2);
-    expect(result.attempts).toBe(2);
-    expect(result.provider).toBe("openai");
-  });
-
-  it("excludes anthropic from the embedding chain (no embedding API)", async () => {
-    vi.stubEnv("ANTHROPIC_API_KEY", "an-key");
-
-    const seenProviders: string[] = [];
-    let calls = 0;
-
-    await expect(
-      runEmbedWithFallback(
-        async () => {
-          calls += 1;
-          // Capture which provider key was used by checking the env state
-          // via the call ordering — we don't have direct access here, so we
-          // just throw retryable to force walking the chain.
-          throw Object.assign(new Error("503"), { statusCode: 503 });
-        },
-        // Even if the user includes anthropic, it's filtered out:
-        { chain: ["anthropic", "openrouter", "openai"] },
-      ),
-    ).rejects.toThrow(/All embedding providers/);
-
-    // Should only attempt openrouter + openai (anthropic filtered out)
-    expect(calls).toBe(2);
-    void seenProviders;
-  });
-
-  it("throws a clear error when no embedding-capable provider has a key", async () => {
-    vi.unstubAllEnvs();
-    _resetAgentsEnvCache();
-    vi.stubEnv("ANTHROPIC_API_KEY", "an-key");
-    // No openrouter or openai key
-
-    await expect(
-      runEmbedWithFallback(async () => ({ ok: true }), {
-        chain: ["openrouter", "openai", "anthropic"],
-      }),
-    ).rejects.toThrow(/No embedding-capable providers available/);
-  });
-
-  it("rethrows non-retryable errors immediately", async () => {
-    let calls = 0;
-    await expect(
-      runEmbedWithFallback(
-        async () => {
-          calls += 1;
-          throw Object.assign(new Error("Bad Request"), { statusCode: 400 });
-        },
-        { chain: ["openrouter", "openai"] },
-      ),
-    ).rejects.toThrow(/Bad Request/);
-    expect(calls).toBe(1);
-  });
-});
-
-// ─── VercelAIAgent.execute() rotates providers on retryable error ────────────
-
-describe("VercelAIAgent.execute() — fallback wiring", () => {
-  beforeEach(() => {
-    vi.unstubAllEnvs();
-    _resetAgentsEnvCache();
-    vi.resetModules();
-    vi.stubEnv("OPENROUTER_API_KEY", "or-key");
-    vi.stubEnv("ANTHROPIC_API_KEY", "an-key");
-  });
-
-  afterEach(() => {
-    vi.unstubAllEnvs();
-    _resetAgentsEnvCache();
-    vi.resetModules();
-  });
-
-  it("rotates to the next provider when streamText fails with a retryable error", async () => {
-    let streamCalls = 0;
-
-    // Dynamic mock of `ai` — use vi.doMock so it applies to subsequent imports.
-    vi.doMock("ai", () => ({
-      streamText: vi.fn(() => {
-        streamCalls += 1;
-        if (streamCalls === 1) {
-          // Return an object whose .text promise rejects with a retryable error
-          return {
-            text: Promise.reject(
-              Object.assign(new Error("503 Service Unavailable"), {
-                statusCode: 503,
-              }),
-            ),
-            usage: Promise.resolve({ inputTokens: 0, outputTokens: 0 }),
-          };
-        }
-        return {
-          text: Promise.resolve("hello from fallback"),
-          usage: Promise.resolve({ inputTokens: 10, outputTokens: 5 }),
-        };
-      }),
-      stepCountIs: vi.fn((n: number) => n),
-      dynamicTool: vi.fn((d: unknown) => d),
-    }));
-
-    // Avoid real billing/credit deduction
-    vi.doMock("@nebutra/billing/credits", () => ({
-      deductCredits: vi.fn(async () => {}),
-    }));
-
-    const { VercelAIAgent } = await import("../providers/vercel-ai");
-    const agent = new VercelAIAgent({
-      id: "test",
-      name: "Test",
-      description: "",
-      model: "flagship",
-      instructions: "be helpful",
-    });
-
-    const response = await agent.run([{ role: "user", content: "hi", timestamp: new Date() }], {
-      tenantId: "org_1",
-      userId: "u_1",
-      conversationId: "c_1",
-    });
-
-    expect(streamCalls).toBe(2);
-    expect(response.messages.at(-1)?.content).toBe("hello from fallback");
-    expect(response.usage.totalTokens).toBe(15);
-  });
-
-  it("does not rotate when the only configured provider succeeds (single-provider deploy)", async () => {
-    vi.unstubAllEnvs();
-    _resetAgentsEnvCache();
-    vi.resetModules();
-    vi.stubEnv("OPENROUTER_API_KEY", "or-key");
-    // Anthropic + OpenAI deliberately absent
-
-    let streamCalls = 0;
-    vi.doMock("ai", () => ({
-      streamText: vi.fn(() => {
-        streamCalls += 1;
-        return {
-          text: Promise.resolve("ok"),
-          usage: Promise.resolve({ inputTokens: 1, outputTokens: 1 }),
-        };
-      }),
-      stepCountIs: vi.fn((n: number) => n),
-      dynamicTool: vi.fn((d: unknown) => d),
-    }));
-    vi.doMock("@nebutra/billing/credits", () => ({
-      deductCredits: vi.fn(async () => {}),
-    }));
-
-    const { VercelAIAgent } = await import("../providers/vercel-ai");
-    const agent = new VercelAIAgent({
-      id: "single",
-      name: "Single",
-      description: "",
-      model: "flagship",
-      instructions: "x",
-    });
-
-    const response = await agent.run([{ role: "user", content: "ping", timestamp: new Date() }], {
-      tenantId: "t",
-      userId: "u",
-      conversationId: "c",
-    });
-
-    expect(streamCalls).toBe(1);
-    expect(response.messages.at(-1)?.content).toBe("ok");
-  });
-});

package/src/__tests__/generation.test.ts

@@ -1,111 +0,0 @@
-/**
- * Image / video generation modality.
- *
- * Verifies the env-key-gated provider chain mirrors the LLM fallback design:
- * deterministic mock terminal, additive real-provider priority, retryable
- * rotation, and tenant-scoped attribution.
- */
-
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-import {
-  _resetGenerationRegistry,
-  type GenerationContext,
-  type GenerationProvider,
-  generateImage,
-  generateVideo,
-  listGenerationProviders,
-  registerGenerationProvider,
-} from "../generation/index";
-
-const ctx: GenerationContext = {
-  tenantId: "org_test",
-  userId: "user_test",
-  conversationId: "canvas_1",
-};
-
-beforeEach(() => {
-  _resetGenerationRegistry();
-  delete process.env.GENERATION_FALLBACK_CHAIN;
-});
-afterEach(() => {
-  _resetGenerationRegistry();
-});
-
-describe("mock provider (terminal)", () => {
-  it("is always available with no secret", () => {
-    expect(listGenerationProviders("image")).toEqual(["mock"]);
-    expect(listGenerationProviders("video")).toEqual(["mock"]);
-  });
-
-  it("produces a deterministic data URI for identical input", async () => {
-    const a = await generateImage({ prompt: "a blue fox", width: 512, height: 512 }, ctx);
-    const b = await generateImage({ prompt: "a blue fox", width: 512, height: 512 }, ctx);
-    expect(a.url).toBe(b.url);
-    expect(a.url.startsWith("data:image/svg+xml;base64,")).toBe(true);
-    expect(a.width).toBe(512);
-    expect(a.providerName).toBe("mock");
-    expect(a.usage.units).toBe(1);
-  });
-
-  it("varies output by prompt", async () => {
-    const a = await generateImage({ prompt: "sunset" }, ctx);
-    const b = await generateImage({ prompt: "moonrise" }, ctx);
-    expect(a.url).not.toBe(b.url);
-  });
-
-  it("returns a poster frame + second-based units for video", async () => {
-    const v = await generateVideo({ prompt: "waves", durationSeconds: 8 }, ctx);
-    expect(v.modality).toBe("video");
-    expect(v.usage.units).toBe(8);
-  });
-});
-
-describe("env-key gating + priority", () => {
-  const realProvider: GenerationProvider = {
-    name: "fake-real",
-    envKey: "FAKE_REAL_API_KEY",
-    capabilities: ["image"],
-    async generateImage(req) {
-      return {
-        modality: "image",
-        mimeType: "image/png",
-        url: "https://example.test/real.png",
-        width: req.width ?? 1024,
-        height: req.height ?? 1024,
-        providerName: "fake-real",
-        model: "fake-real-1",
-        usage: { units: 1 },
-      };
-    },
-  };
-
-  it("hides a provider whose env key is absent", () => {
-    registerGenerationProvider(realProvider);
-    delete process.env.FAKE_REAL_API_KEY;
-    expect(listGenerationProviders("image")).toEqual(["mock"]);
-  });
-
-  it("prefers the real provider when its key is present", async () => {
-    registerGenerationProvider(realProvider);
-    process.env.FAKE_REAL_API_KEY = "x";
-    expect(listGenerationProviders("image")).toEqual(["fake-real", "mock"]);
-    const r = await generateImage({ prompt: "hi" }, ctx);
-    expect(r.providerName).toBe("fake-real");
-    delete process.env.FAKE_REAL_API_KEY;
-  });
-});
-
-describe("retryable rotation", () => {
-  it("rotates to mock when a real provider throws a retryable error", async () => {
-    registerGenerationProvider({
-      name: "flaky",
-      envKey: null,
-      capabilities: ["image"],
-      async generateImage() {
-        throw new Error("429 Too Many Requests");
-      },
-    });
-    const r = await generateImage({ prompt: "resilient" }, ctx);
-    expect(r.providerName).toBe("mock");
-  });
-});

package/src/__tests__/public-api.test.ts

@@ -1,114 +0,0 @@
-/**
- * Public API contract for @nebutra/agents.
- *
- * Guards the surface area that was consolidated from `@nebutra/ai-sdk`
- * (generateText / streamText / embed / embedMany / configure / models / createModel)
- * plus the pre-existing agent orchestration primitives. Any deletion or
- * rename to these exports is a breaking change.
- */
-
-import { describe, expect, it } from "vitest";
-import * as agents from "../index";
-
-describe("@nebutra/agents public API contract", () => {
-  // ─── Agent orchestration primitives ──────────────────────────────────────
-  it("exports BaseAgent class", () => {
-    expect(agents.BaseAgent).toBeDefined();
-    expect(typeof agents.BaseAgent).toBe("function");
-  });
-
-  it("exports AgentOrchestrator class", () => {
-    expect(agents.AgentOrchestrator).toBeDefined();
-    expect(typeof agents.AgentOrchestrator).toBe("function");
-  });
-
-  it("exports AgentRouter class", () => {
-    expect(agents.AgentRouter).toBeDefined();
-    expect(typeof agents.AgentRouter).toBe("function");
-  });
-
-  // ─── Memory functions ────────────────────────────────────────────────────
-  it("exports memory functions", () => {
-    expect(typeof agents.clearMemory).toBe("function");
-    expect(typeof agents.getMemory).toBe("function");
-    expect(typeof agents.saveMemory).toBe("function");
-  });
-
-  // ─── Tenant / context ────────────────────────────────────────────────────
-  it("exports tenant utilities", () => {
-    expect(typeof agents.checkAgentQuota).toBe("function");
-    expect(typeof agents.createAgentContext).toBe("function");
-  });
-
-  // ─── Tools ───────────────────────────────────────────────────────────────
-  it("exports built-in tools", () => {
-    expect(agents.BUILT_IN_TOOLS).toBeDefined();
-    expect(agents.databaseQueryTool).toBeDefined();
-    expect(agents.knowledgeBaseTool).toBeDefined();
-    expect(agents.webSearchTool).toBeDefined();
-  });
-
-  // ─── Vercel AI SDK helpers (absorbed from @nebutra/ai-sdk) ───────────────
-  it("exports configure() and getConfig()", () => {
-    expect(typeof agents.configure).toBe("function");
-    expect(typeof agents.getConfig).toBe("function");
-  });
-
-  it("exports generateText() and streamText()", () => {
-    expect(typeof agents.generateText).toBe("function");
-    expect(typeof agents.streamText).toBe("function");
-  });
-
-  it("exports embed() and embedMany()", () => {
-    expect(typeof agents.embed).toBe("function");
-    expect(typeof agents.embedMany).toBe("function");
-  });
-
-  it("exports createModel() and createEmbeddingModel()", () => {
-    expect(typeof agents.createModel).toBe("function");
-    expect(typeof agents.createEmbeddingModel).toBe("function");
-  });
-
-  it("exports models preset map with expected keys", () => {
-    expect(agents.models).toBeDefined();
-    expect(agents.models.flagship).toBeTypeOf("string");
-    expect(agents.models.fast).toBeTypeOf("string");
-    expect(agents.models.embedding).toBeTypeOf("string");
-  });
-
-  it("exports resolveModel() and returns presets correctly", () => {
-    expect(typeof agents.resolveModel).toBe("function");
-    expect(agents.resolveModel("flagship")).toBe(agents.models.flagship);
-    expect(agents.resolveModel("custom/passthrough")).toBe("custom/passthrough");
-  });
-
-  it("configure() accepts a provider selection and getConfig() reflects it", () => {
-    agents.configure({ provider: "openai", defaultModel: "gpt-4o" });
-    const cfg = agents.getConfig();
-    expect(cfg.provider).toBe("openai");
-    expect(cfg.defaultModel).toBe("gpt-4o");
-  });
-
-  it("NebutraAIConfigSchema validates input config", () => {
-    expect(agents.NebutraAIConfigSchema).toBeDefined();
-    const parsed = agents.NebutraAIConfigSchema.parse({});
-    expect(parsed.provider).toBe("openrouter"); // default
-    expect(parsed.defaultModel).toBeTypeOf("string");
-  });
-
-  it("AgentOrchestrator can be instantiated with empty agents", () => {
-    const orch = new agents.AgentOrchestrator({ agents: [] });
-    expect(orch).toBeInstanceOf(agents.AgentOrchestrator);
-  });
-
-  it("BaseAgent can be instantiated with an AgentConfig", () => {
-    const agent = new agents.BaseAgent({
-      id: "test",
-      name: "Test Agent",
-      description: "Contract test",
-      model: "openai/gpt-4",
-      instructions: "You are a test agent.",
-    });
-    expect(agent.config.id).toBe("test");
-  });
-});

package/src/__tests__/runtime-gateway.test.ts

@@ -1,108 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { AgentRuntimeGateway, type AgentRuntimeGatewayProvider } from "../gateway";
-
-function provider(
-  id: string,
-  text: string,
-  options: {
-    capabilities?: readonly string[];
-    fail?: "retryable" | "fatal";
-    calls?: { count: number };
-  } = {},
-): AgentRuntimeGatewayProvider {
-  return {
-    id,
-    model: `${id}-model`,
-    capabilities: new Set(options.capabilities ?? ["reasoning", "tools"]),
-    async complete() {
-      if (options.calls) options.calls.count += 1;
-      if (options.fail === "retryable") {
-        throw Object.assign(new Error("rate limited"), { statusCode: 429 });
-      }
-      if (options.fail === "fatal") {
-        throw Object.assign(new Error("unauthorized"), { statusCode: 401 });
-      }
-      return {
-        id: `${id}-call`,
-        model: `${id}-model`,
-        provider: id,
-        text,
-        usage: { inputTokens: 2, outputTokens: 3, totalTokens: 5 },
-      };
-    },
-  };
-}
-
-describe("AgentRuntimeGateway", () => {
-  it("routes by capability and records tenant-aware usage decisions", async () => {
-    const gateway = new AgentRuntimeGateway({
-      providers: [
-        provider("vision-only", "no", { capabilities: ["vision"] }),
-        provider("reasoning-tools", "hello", { capabilities: ["reasoning", "tools"] }),
-      ],
-    });
-
-    const response = await gateway.complete({
-      capability: "reasoning+tools",
-      tenantId: "org_1",
-      userId: "user_1",
-      requestId: "req_1",
-      messages: [{ role: "user", content: "hi" }],
-    });
-
-    expect(response.text).toBe("hello");
-    expect(gateway.usageReport()).toMatchObject({ calls: 1, totalTokens: 5 });
-    expect(gateway.debugLog()[0]).toMatchObject({
-      requestId: "req_1",
-      tenantId: "org_1",
-      userId: "user_1",
-      decision: {
-        provider: "reasoning-tools",
-        fallbackIndex: 0,
-      },
-      ok: true,
-    });
-  });
-
-  it("falls back only for retryable provider errors", async () => {
-    const retryable = new AgentRuntimeGateway({
-      providers: [provider("primary", "no", { fail: "retryable" }), provider("fallback", "yes")],
-    });
-
-    await expect(
-      retryable.complete({
-        capability: "reasoning",
-        messages: [{ role: "user", content: "hi" }],
-      }),
-    ).resolves.toMatchObject({ provider: "fallback", text: "yes" });
-
-    const fatal = new AgentRuntimeGateway({
-      providers: [provider("primary", "no", { fail: "fatal" }), provider("fallback", "yes")],
-    });
-
-    await expect(
-      fatal.complete({
-        capability: "reasoning",
-        messages: [{ role: "user", content: "hi" }],
-      }),
-    ).rejects.toThrow(/unauthorized/);
-    expect(fatal.debugLog()).toHaveLength(1);
-  });
-
-  it("uses a stable prompt cache without invoking the provider twice", async () => {
-    const calls = { count: 0 };
-    const gateway = new AgentRuntimeGateway({
-      providers: [provider("primary", "cached", { calls })],
-    });
-    const request = {
-      capability: "reasoning",
-      messages: [{ role: "user" as const, content: "same prompt" }],
-    };
-
-    await gateway.complete(request);
-    await gateway.complete(request);
-
-    expect(calls.count).toBe(1);
-    expect(gateway.cacheStats()).toMatchObject({ hits: 1, misses: 1, size: 1 });
-  });
-});