@nebutra/agents 1.0.0

package/README.md

@@ -0,0 +1,78 @@
+# @nebutra/agents — Nebutra AI Runtime
+
+> **Status: Production-ready** — The single AI runtime package for Nebutra.
+> As of v1.0.0 it consolidates the former `@nebutra/ai-sdk` (top-level
+> `generateText` / `streamText` / `embed` helpers) with the multi-agent
+> orchestration framework (`BaseAgent`, `AgentOrchestrator`, memory, tools).
+
+## What lives here
+
+```
+@nebutra/agents
+  ├── Top-level Vercel AI SDK helpers (absorbed from @nebutra/ai-sdk)
+  │     configure(), generateText(), streamText(), embed(), embedMany()
+  │     createModel(), createEmbeddingModel(), models, resolveModel()
+  │
+  ├── Multi-agent framework
+  │     BaseAgent              ← Abstract agent with tenant context + usage tracking
+  │     AgentOrchestrator      ← chat/pipeline/broadcast coordination
+  │     AgentRouter            ← route messages to the best agent
+  │     Memory                 ← Redis-backed per-tenant conversation persistence
+  │     Tools                  ← BUILT_IN_TOOLS (web_search, db_query, knowledge_base)
+  │
+  └── Provider adapters
+        providers/vercel-ai.ts ← VercelAIAgent (production, streamText + toolLoop)
+        providers/langchain.ts ← Optional LangChain stub (throws until you wire it up)
+```
+
+## Companion package
+
+| Package | Role |
+|---------|------|
+| `@nebutra/agents` | Runtime — all AI calls go through here |
+| `@nebutra/ai-providers` | Meta-only — provider registry data + scaffolding templates consumed by `@nebutra/create-sailor` |
+
+The former `@nebutra/ai-sdk` was absorbed into this package in v1.0.0.
+The former `@nebutra/langchain` stub was deleted (no callers); the LangChain
+integration hook lives here in `providers/langchain.ts` as an extension point.
+
+## Quick start — single-shot generation
+
+```ts
+import { configure, streamText } from "@nebutra/agents";
+
+configure({ provider: "openrouter", defaultModel: "anthropic/claude-sonnet-4" });
+
+const result = await streamText(
+  [{ role: "user", content: "Explain monorepos" }],
+  { model: "fast" },
+);
+return result.toUIMessageStreamResponse();
+```
+
+## Quick start — multi-agent orchestration
+
+```ts
+import { AgentOrchestrator, createAgentContext } from "@nebutra/agents";
+import { VercelAIAgent } from "@nebutra/agents/providers/vercel-ai";
+
+const orchestrator = new AgentOrchestrator({
+  agents: [
+    { id: "assistant", name: "Assistant", description: "Helpful", model: "openai/gpt-4", instructions: "..." },
+  ],
+});
+
+// Swap the BaseAgent for a real VercelAIAgent at runtime:
+orchestrator.registerAgent(
+  new VercelAIAgent({ id: "assistant", name: "Assistant", description: "Helpful", model: "openai/gpt-4", instructions: "..." }),
+);
+
+const ctx = createAgentContext("org_123", "user_456");
+const response = await orchestrator.chat("Hello", ctx);
+// → response.usage tracks tokens for billing
+```
+
+## Multi-tenant by design
+
+Every agent operation requires a `tenantId`. Usage events are emitted for
+billing and metering integration (see `@nebutra/billing/credits`).

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@nebutra/agents",
+  "version": "1.0.0",
+  "description": "Nebutra AI runtime: multi-agent orchestration + Vercel AI SDK helpers (absorbed @nebutra/ai-sdk in 1.0.0)",
+  "private": false,
+  "license": "AGPL-3.0",
+  "type": "module",
+  "nebutra": {
+    "featureId": "agents",
+    "category": "ai",
+    "summary": "Nebutra AI runtime: multi-agent orchestration + Vercel AI SDK helpers"
+  },
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./tools": "./src/tools.ts",
+    "./providers/vercel-ai": "./src/providers/vercel-ai.ts",
+    "./providers/langchain": "./src/providers/langchain.ts",
+    "./sdk": "./src/sdk/index.ts",
+    "./sdk/config": "./src/sdk/config.ts",
+    "./sdk/models": "./src/sdk/models.ts",
+    "./sdk/provider": "./src/sdk/provider.ts",
+    "./env": "./src/env.ts",
+    "./observability": "./src/observability.ts",
+    "./fallback": "./src/fallback.ts"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.76",
+    "@ai-sdk/openai": "^3.0.41",
+    "@openrouter/ai-sdk-provider": "^2.3.3",
+    "langfuse": "^3.38.20",
+    "langfuse-vercel": "^3.38.20",
+    "zod": "^4.3.6",
+    "@nebutra/billing": "0.1.0",
+    "@nebutra/cache": "0.0.1",
+    "@nebutra/logger": "0.1.0"
+  },
+  "peerDependencies": {
+    "ai": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.15",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "homepage": "https://github.com/Nebutra/Nebutra-Sailor/tree/main/packages/ai/agents#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebutra/Nebutra-Sailor.git",
+    "directory": "packages/ai/agents"
+  },
+  "bugs": {
+    "url": "https://github.com/Nebutra/Nebutra-Sailor/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}

package/src/__tests__/cost-observability.test.ts

@@ -0,0 +1,172 @@
+/**
+ * Cost & observability primitives:
+ * - Anthropic prompt cache control wiring
+ * - Multi-provider fallback chain on retryable errors
+ * - Langfuse no-op when env missing
+ */
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { _resetAgentsEnvCache } from "../env";
+import {
+  buildSystemWithCache,
+  isRetryableError,
+  runWithFallback,
+  withAnthropicCacheControl,
+} from "../fallback";
+import { _resetLangfuseCache, buildTelemetryConfig, initLangfuse } from "../observability";
+
+describe("withAnthropicCacheControl()", () => {
+  it("returns ephemeral cache control under the anthropic provider key", () => {
+    const opts = withAnthropicCacheControl();
+    expect(opts.anthropic.cacheControl.type).toBe("ephemeral");
+  });
+
+  it("wraps a system prompt with cache-control providerOptions", () => {
+    const wrapped = buildSystemWithCache("You are a helpful assistant.");
+    expect(wrapped.role).toBe("system");
+    expect(wrapped.content).toBe("You are a helpful assistant.");
+    expect(wrapped.providerOptions.anthropic.cacheControl.type).toBe("ephemeral");
+  });
+});
+
+describe("isRetryableError()", () => {
+  it.each([429, 500, 502, 503, 504, 408])("marks status %i as retryable", (statusCode) => {
+    expect(isRetryableError({ statusCode })).toBe(true);
+  });
+
+  it("marks ECONNRESET / ETIMEDOUT as retryable", () => {
+    expect(isRetryableError({ code: "ECONNRESET" })).toBe(true);
+    expect(isRetryableError({ code: "ETIMEDOUT" })).toBe(true);
+  });
+
+  it("marks 4xx auth/validation errors as non-retryable", () => {
+    expect(isRetryableError({ statusCode: 401 })).toBe(false);
+    expect(isRetryableError({ statusCode: 403 })).toBe(false);
+    expect(isRetryableError({ statusCode: 400 })).toBe(false);
+  });
+
+  it("returns false for null / undefined / non-objects", () => {
+    expect(isRetryableError(null)).toBe(false);
+    expect(isRetryableError(undefined)).toBe(false);
+    expect(isRetryableError("oops")).toBe(false);
+  });
+
+  it("respects an explicit isRetryable=true flag (AI SDK APICallError)", () => {
+    expect(isRetryableError({ isRetryable: true })).toBe(true);
+  });
+});
+
+describe("runWithFallback()", () => {
+  beforeEach(() => {
+    _resetAgentsEnvCache();
+    // Provide stub keys so buildModel() doesn't throw before invoke() runs.
+    vi.stubEnv("OPENROUTER_API_KEY", "test-or");
+    vi.stubEnv("ANTHROPIC_API_KEY", "test-an");
+    vi.stubEnv("OPENAI_API_KEY", "test-oa");
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("falls through retryable errors and returns the next provider's result", async () => {
+    let calls = 0;
+    const result = await runWithFallback(
+      async () => {
+        calls += 1;
+        if (calls === 1) {
+          // simulate primary provider 503
+          const err = Object.assign(new Error("Service Unavailable"), {
+            statusCode: 503,
+          });
+          throw err;
+        }
+        return "ok-from-fallback" as const;
+      },
+      {
+        chain: ["openrouter", "anthropic"],
+        // Stub buildModel by injecting fake creds via env
+        model: "flagship",
+      },
+    );
+
+    expect(result.result).toBe("ok-from-fallback");
+    expect(result.attempts).toBe(2);
+    expect(result.provider).toBe("anthropic");
+  });
+
+  it("rethrows non-retryable errors immediately (no fallback)", async () => {
+    let calls = 0;
+    await expect(
+      runWithFallback(
+        async () => {
+          calls += 1;
+          throw Object.assign(new Error("Unauthorized"), { statusCode: 401 });
+        },
+        { chain: ["openrouter", "anthropic"] },
+      ),
+    ).rejects.toThrow(/Unauthorized/);
+    expect(calls).toBe(1);
+  });
+
+  it("throws an aggregate error when the entire chain fails with retryables", async () => {
+    await expect(
+      runWithFallback(
+        async () => {
+          throw Object.assign(new Error("503"), { statusCode: 503 });
+        },
+        { chain: ["openrouter", "anthropic", "openai"] },
+      ),
+    ).rejects.toThrow(/All LLM providers in fallback chain/);
+  });
+});
+
+describe("Langfuse telemetry — no-op when env missing", () => {
+  beforeEach(() => {
+    _resetLangfuseCache();
+    _resetAgentsEnvCache();
+    vi.unstubAllEnvs();
+    vi.stubEnv("LANGFUSE_PUBLIC_KEY", "");
+    vi.stubEnv("LANGFUSE_SECRET_KEY", "");
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    _resetLangfuseCache();
+    _resetAgentsEnvCache();
+  });
+
+  it("initLangfuse() returns null when keys missing", async () => {
+    const client = await initLangfuse();
+    expect(client).toBeNull();
+  });
+
+  it("buildTelemetryConfig() returns isEnabled=false when keys missing", () => {
+    const cfg = buildTelemetryConfig({ functionId: "test-fn" });
+    expect(cfg.isEnabled).toBe(false);
+    expect(cfg.functionId).toBeUndefined();
+  });
+
+  it("buildTelemetryConfig() includes tenant/session metadata when configured", () => {
+    vi.stubEnv("LANGFUSE_PUBLIC_KEY", "pk-test");
+    vi.stubEnv("LANGFUSE_SECRET_KEY", "sk-test");
+    _resetAgentsEnvCache();
+
+    const cfg = buildTelemetryConfig({
+      functionId: "agent.support-bot",
+      metadata: {
+        tenantId: "org_123",
+        userId: "user_456",
+        sessionId: "conv_789",
+        agentId: "support-bot",
+      },
+    });
+
+    expect(cfg.isEnabled).toBe(true);
+    expect(cfg.functionId).toBe("agent.support-bot");
+    expect(cfg.metadata?.tenantId).toBe("org_123");
+    expect(cfg.metadata?.langfuseUserId).toBe("org_123");
+    expect(cfg.metadata?.langfuseSessionId).toBe("conv_789");
+  });
+});

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

@@ -0,0 +1,313 @@
+/**
+ * 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");
+  });
+});