@nebutra/agents 1.1.0 → 1.1.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @nebutra/agents@1.1.0 build /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/agents
+> @nebutra/agents@1.1.1 build /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/agents
 > tsup
 
 CLI Building entry: src/index.ts, src/tools.ts, src/providers/langchain.ts, src/providers/vercel-ai.ts, src/sdk/config.ts, src/sdk/index.ts, src/sdk/models.ts, src/sdk/provider.ts
@@ -12,22 +12,22 @@
 ESM dist/index.js               16.08 KB
 ESM dist/providers/langchain.js 536.00 B
 ESM dist/sdk/config.js          166.00 B
-ESM dist/tools.js               203.00 B
 ESM dist/chunk-UVL2UVVM.js      1.26 KB
+ESM dist/tools.js               203.00 B
 ESM dist/providers/vercel-ai.js 2.43 KB
 ESM dist/chunk-B7XWL35G.js      1.51 KB
 ESM dist/chunk-RDOFKRI6.js      4.71 KB
 ESM dist/sdk/index.js           534.00 B
-ESM dist/chunk-5LX742GP.js      7.78 KB
 ESM dist/chunk-NPQECBXL.js      2.37 KB
+ESM dist/chunk-5LX742GP.js      7.78 KB
+ESM dist/sdk/provider.js        190.00 B
 ESM dist/sdk/models.js          102.00 B
 ESM dist/chunk-RLWM437Q.js      1.63 KB
 ESM dist/chunk-NVPE5EDI.js      1.49 KB
 ESM dist/chunk-5JZJ5KMC.js      1.22 KB
-ESM dist/sdk/provider.js        190.00 B
-ESM ⚡️ Build success in 33ms
+ESM ⚡️ Build success in 48ms
 DTS Build start
-DTS ⚡️ Build success in 5153ms
+DTS ⚡️ Build success in 5575ms
 DTS dist/index.d.ts               19.71 KB
 DTS dist/tools.d.ts               724.00 B
 DTS dist/providers/langchain.d.ts 546.00 B

package/.turbo/turbo-test.log

@@ -1,18 +1,19 @@
 
-> @nebutra/agents@1.1.0 test /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/agents
+> @nebutra/agents@1.1.1 test /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/agents
 > vitest run
 
 
  RUN  v4.1.4 /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/agents
 
- ✓ src/__tests__/fallback-wiring.test.ts (9 tests) 253ms
- ✓ src/__tests__/cost-observability.test.ts (18 tests) 655ms
-     ✓ falls through retryable errors and returns the next provider's result  537ms
- ✓ src/__tests__/public-api.test.ts (16 tests) 59ms
- ✓ src/__tests__/generation.test.ts (7 tests) 43ms
+ ✓ src/__tests__/fallback-wiring.test.ts (9 tests) 235ms
+ ✓ src/__tests__/cost-observability.test.ts (18 tests) 510ms
+     ✓ falls through retryable errors and returns the next provider's result  335ms
+ ✓ src/__tests__/public-api.test.ts (16 tests) 72ms
+ ✓ src/__tests__/runtime-gateway.test.ts (3 tests) 80ms
+ ✓ src/__tests__/generation.test.ts (7 tests) 61ms
 
- Test Files  4 passed (4)
-      Tests  50 passed (50)
-   Start at  16:51:18
-   Duration  4.50s (transform 2.59s, setup 0ms, import 6.35s, tests 1.01s, environment 1ms)
+ Test Files  5 passed (5)
+      Tests  53 passed (53)
+   Start at  08:15:21
+   Duration  4.98s (transform 2.66s, setup 0ms, import 7.42s, tests 958ms, environment 1ms)
 

package/.turbo/turbo-typecheck.log

@@ -1,4 +1,4 @@
 
-> @nebutra/agents@1.1.0 typecheck /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/agents
+> @nebutra/agents@1.1.1 typecheck /home/runner/work/Nebutra-Sailor/Nebutra-Sailor/packages/ai/agents
 > tsc --noEmit
 

package/CHANGELOG.md

@@ -1,11 +1,21 @@
 # @nebutra/agents
 
+## 1.1.1
+
+### Patch Changes
+
+- Publish registry package metadata under the MIT license.
+
+- Updated dependencies []:
+  - @nebutra/billing@0.1.2
+  - @nebutra/cache@0.0.2
+  - @nebutra/logger@0.1.1
+
 ## 1.1.0
 
 ### Minor Changes
 
 - [`092a1ce`](https://github.com/Nebutra/Nebutra-Sailor/commit/092a1ce810965e2d81767642e4bad05b80df81f4) Thanks [@TsekaLuk](https://github.com/TsekaLuk)! - Add the Atelier agentic creative-canvas capability.
-
   - `@nebutra/agents`: new image/video **generation modality**
     (`@nebutra/agents/generation`) on the same env-key-gated provider layer as
     the LLM fallback chain, with a deterministic always-available mock provider.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nebutra/agents",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Nebutra AI runtime: multi-agent orchestration + Vercel AI SDK helpers (absorbed @nebutra/ai-sdk in 1.0.0)",
   "private": false,
   "license": "MIT",
@@ -8,6 +8,7 @@
   "nebutra": {
     "featureId": "agents",
     "category": "ai",
+    "surface": "model-runtime",
     "summary": "Nebutra AI runtime: multi-agent orchestration + Vercel AI SDK helpers"
   },
   "main": "./src/index.ts",
@@ -30,20 +31,13 @@
     "@ai-sdk/anthropic": "^3.0.76",
     "@ai-sdk/openai": "^3.0.41",
     "@openrouter/ai-sdk-provider": "^2.3.3",
+    "ai": "^6.0.0",
     "langfuse": "^3.38.20",
     "langfuse-vercel": "^3.38.20",
     "zod": "^4.3.6",
-    "@nebutra/billing": "0.1.1",
-    "@nebutra/cache": "0.0.1",
-    "@nebutra/logger": "0.1.0"
-  },
-  "peerDependencies": {
-    "ai": "^6.0.0"
-  },
-  "peerDependenciesMeta": {
-    "ai": {
-      "optional": true
-    }
+    "@nebutra/billing": "0.1.2",
+    "@nebutra/cache": "0.0.2",
+    "@nebutra/logger": "0.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.19.15",

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

@@ -31,7 +31,7 @@ describe("withAnthropicCacheControl()", () => {
 });
 
 describe("isRetryableError()", () => {
-  it.each([429, 500, 502, 503, 504, 408])("marks status %i as retryable", (statusCode) => {
+  it.each([429, 500, 502, 503, 504, 408])("marks status %i as retryable", (statusCode: number) => {
     expect(isRetryableError({ statusCode })).toBe(true);
   });
 

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

@@ -0,0 +1,108 @@
+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 });
+  });
+});

package/src/gateway.ts

@@ -0,0 +1,234 @@
+import { isRetryableError } from "./fallback";
+
+export type AgentRuntimeGatewayMessageRole = "system" | "user" | "assistant" | "tool";
+
+export interface AgentRuntimeGatewayMessage {
+  readonly role: AgentRuntimeGatewayMessageRole;
+  readonly content: string;
+}
+
+export interface AgentRuntimeGatewayUsage {
+  readonly inputTokens?: number;
+  readonly outputTokens?: number;
+  readonly totalTokens?: number;
+}
+
+export interface AgentRuntimeGatewayCompletion {
+  readonly id: string;
+  readonly provider: string;
+  readonly model: string;
+  readonly text: string;
+  readonly usage?: AgentRuntimeGatewayUsage;
+  readonly raw?: unknown;
+}
+
+export interface AgentRuntimeGatewayProvider {
+  readonly id: string;
+  readonly model: string;
+  readonly capabilities: ReadonlySet<string>;
+  complete(
+    messages: readonly AgentRuntimeGatewayMessage[],
+    options?: AgentRuntimeGatewayCompleteOptions,
+  ): Promise<AgentRuntimeGatewayCompletion>;
+}
+
+export interface AgentRuntimeGatewayCompleteOptions {
+  readonly temperature?: number;
+  readonly maxTokens?: number;
+  readonly signal?: AbortSignal;
+}
+
+export interface AgentRuntimeGatewayRequest extends AgentRuntimeGatewayCompleteOptions {
+  readonly capability: string;
+  readonly messages: readonly AgentRuntimeGatewayMessage[];
+  readonly tenantId?: string;
+  readonly userId?: string;
+  readonly requestId?: string;
+  readonly cacheKey?: string;
+  readonly maxFallbacks?: number;
+}
+
+export interface AgentRuntimeGatewayDecision {
+  readonly provider: string;
+  readonly reason: string;
+  readonly fallbackIndex: number;
+}
+
+export interface AgentRuntimeGatewayDebugEntry {
+  readonly requestId: string;
+  readonly tenantId?: string;
+  readonly userId?: string;
+  readonly decision: AgentRuntimeGatewayDecision;
+  readonly ok: boolean;
+  readonly error?: string;
+}
+
+export interface AgentRuntimeGatewayUsageReport {
+  readonly calls: number;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly totalTokens: number;
+  readonly estimatedUsd: number;
+}
+
+export interface AgentRuntimeGatewayOptions {
+  readonly providers: readonly AgentRuntimeGatewayProvider[];
+  readonly estimateUsd?: (usage: Required<AgentRuntimeGatewayUsage>) => number;
+  readonly requestId?: () => string;
+}
+
+interface CacheEntry {
+  readonly response: AgentRuntimeGatewayCompletion;
+}
+
+function capabilityParts(capability: string): string[] {
+  return capability
+    .split(/[+,\s]+/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function cacheKey(request: AgentRuntimeGatewayRequest): string {
+  return (
+    request.cacheKey ??
+    JSON.stringify({
+      capability: request.capability,
+      prefix: request.messages.slice(0, Math.max(1, request.messages.length - 1)),
+      last: request.messages.at(-1),
+    })
+  );
+}
+
+function normalizeUsage(
+  usage: AgentRuntimeGatewayUsage | undefined,
+): Required<AgentRuntimeGatewayUsage> {
+  const inputTokens = usage?.inputTokens ?? 0;
+  const outputTokens = usage?.outputTokens ?? 0;
+  return {
+    inputTokens,
+    outputTokens,
+    totalTokens: usage?.totalTokens ?? inputTokens + outputTokens,
+  };
+}
+
+function defaultRequestId(): string {
+  return `agents-gw-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+
+function defaultCostEstimate(usage: Required<AgentRuntimeGatewayUsage>): number {
+  return usage.totalTokens * 0.000_001;
+}
+
+export class AgentRuntimeGateway {
+  readonly #providers: readonly AgentRuntimeGatewayProvider[];
+  readonly #cache = new Map<string, CacheEntry>();
+  readonly #debug: AgentRuntimeGatewayDebugEntry[] = [];
+  readonly #estimateUsd: (usage: Required<AgentRuntimeGatewayUsage>) => number;
+  readonly #requestId: () => string;
+  #hits = 0;
+  #misses = 0;
+  #usage: AgentRuntimeGatewayUsageReport = {
+    calls: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    totalTokens: 0,
+    estimatedUsd: 0,
+  };
+
+  constructor(options: AgentRuntimeGatewayOptions) {
+    this.#providers = options.providers;
+    this.#estimateUsd = options.estimateUsd ?? defaultCostEstimate;
+    this.#requestId = options.requestId ?? defaultRequestId;
+  }
+
+  async complete(request: AgentRuntimeGatewayRequest): Promise<AgentRuntimeGatewayCompletion> {
+    const resolvedRequestId = request.requestId ?? this.#requestId();
+    const resolvedCacheKey = cacheKey(request);
+    const cached = this.#cache.get(resolvedCacheKey);
+    if (cached) {
+      this.#hits += 1;
+      return cached.response;
+    }
+    this.#misses += 1;
+
+    const providers = this.route(request);
+    let lastError: unknown;
+    const max = Math.min(request.maxFallbacks ?? providers.length, providers.length);
+
+    for (let index = 0; index < max; index += 1) {
+      const provider = providers[index];
+      if (!provider) continue;
+
+      const decision: AgentRuntimeGatewayDecision = {
+        provider: provider.id,
+        fallbackIndex: index,
+        reason: `matched capability "${request.capability}"`,
+      };
+
+      try {
+        const response = await provider.complete(request.messages, {
+          ...(request.temperature !== undefined && { temperature: request.temperature }),
+          ...(request.maxTokens !== undefined && { maxTokens: request.maxTokens }),
+          ...(request.signal !== undefined && { signal: request.signal }),
+        });
+        this.#recordUsage(response);
+        this.#cache.set(resolvedCacheKey, { response });
+        this.#debug.push({
+          requestId: resolvedRequestId,
+          ...(request.tenantId !== undefined && { tenantId: request.tenantId }),
+          ...(request.userId !== undefined && { userId: request.userId }),
+          decision,
+          ok: true,
+        });
+        return response;
+      } catch (error) {
+        lastError = error;
+        this.#debug.push({
+          requestId: resolvedRequestId,
+          ...(request.tenantId !== undefined && { tenantId: request.tenantId }),
+          ...(request.userId !== undefined && { userId: request.userId }),
+          decision,
+          ok: false,
+          error: error instanceof Error ? error.message : String(error),
+        });
+
+        if (!isRetryableError(error)) throw error;
+      }
+    }
+
+    throw new Error(
+      `All AgentRuntimeGateway providers failed for capability "${request.capability}". Last error: ${String(lastError)}`,
+    );
+  }
+
+  route(request: Pick<AgentRuntimeGatewayRequest, "capability">): AgentRuntimeGatewayProvider[] {
+    const parts = capabilityParts(request.capability);
+    const matched = this.#providers.filter((provider) =>
+      parts.every((part) => provider.capabilities.has(part)),
+    );
+    return matched.length > 0 ? matched : [...this.#providers];
+  }
+
+  cacheStats(): { hits: number; misses: number; size: number } {
+    return { hits: this.#hits, misses: this.#misses, size: this.#cache.size };
+  }
+
+  usageReport(): AgentRuntimeGatewayUsageReport {
+    return { ...this.#usage };
+  }
+
+  debugLog(): readonly AgentRuntimeGatewayDebugEntry[] {
+    return [...this.#debug];
+  }
+
+  #recordUsage(response: AgentRuntimeGatewayCompletion): void {
+    const usage = normalizeUsage(response.usage);
+    this.#usage = {
+      calls: this.#usage.calls + 1,
+      inputTokens: this.#usage.inputTokens + usage.inputTokens,
+      outputTokens: this.#usage.outputTokens + usage.outputTokens,
+      totalTokens: this.#usage.totalTokens + usage.totalTokens,
+      estimatedUsd: Number((this.#usage.estimatedUsd + this.#estimateUsd(usage)).toFixed(6)),
+    };
+  }
+}