@vellumai/credential-executor 0.11.10 → 0.11.11-staging.2

package/node_modules/@vellumai/service-contracts/package.json

@@ -26,7 +26,8 @@
     "./error": "./src/error.ts",
     "./reactions": "./src/reactions.ts",
     "./guardian-requests": "./src/guardian-requests.ts",
-    "./platform-credential": "./src/platform-credential.ts"
+    "./platform-credential": "./src/platform-credential.ts",
+    "./plan-credit": "./src/plan-credit.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/service-contracts/src/__tests__/plan-credit.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  extraCreditUsd,
+  planCreditUsedFraction,
+  usageGrantRatio,
+} from "../plan-credit.js";
+
+describe("usageGrantRatio", () => {
+  test("reads the used share and clamps to 0..1", () => {
+    expect(usageGrantRatio(20, 9.1)).toBeCloseTo(0.545);
+    expect(usageGrantRatio(20, 0)).toBe(1);
+    expect(usageGrantRatio(20, 25)).toBe(0);
+  });
+
+  test("has no reading without both figures or with nothing granted", () => {
+    expect(usageGrantRatio(null, 5)).toBeNull();
+    expect(usageGrantRatio(20, null)).toBeNull();
+    expect(usageGrantRatio(0, 0)).toBeNull();
+  });
+});
+
+describe("planCreditUsedFraction", () => {
+  test("prefers the ratio whatever the plan", () => {
+    expect(planCreditUsedFraction(20, 9.1, "base")).toBeCloseTo(0.545);
+    expect(planCreditUsedFraction(20, 9.1, null)).toBeCloseTo(0.545);
+  });
+
+  test("treats a Pro plan with nothing granted as fully spent", () => {
+    expect(planCreditUsedFraction(0, 0, "pro")).toBe(1);
+    expect(planCreditUsedFraction(0, null, "pro")).toBe(1);
+  });
+
+  test("gives a base or unknown plan with nothing granted no reading", () => {
+    expect(planCreditUsedFraction(0, 0, "base")).toBeNull();
+    expect(planCreditUsedFraction(0, 0, null)).toBeNull();
+    expect(planCreditUsedFraction(null, null, "pro")).toBeNull();
+  });
+});
+
+describe("extraCreditUsd", () => {
+  test("nets unused grant credit out of the balance to the cent", () => {
+    expect(extraCreditUsd(42.17, 9.1)).toBe(33.07);
+    expect(extraCreditUsd(34.65, 9.1)).toBe(25.55);
+  });
+
+  test("never goes below zero", () => {
+    expect(extraCreditUsd(5, 9.1)).toBe(0);
+    expect(extraCreditUsd(-2.5, 0)).toBe(0);
+  });
+});

package/node_modules/@vellumai/service-contracts/src/index.ts

@@ -28,6 +28,7 @@ export * from "./rpc.js";
 export * from "./trust-rules.js";
 export * from "./ingress.js";
 export * from "./no-response.js";
+export * from "./plan-credit.js";
 export * from "./platform-credential.js";
 export * from "./remote-web-pairing.js";
 export * from "./twilio-ingress.js";

package/node_modules/@vellumai/service-contracts/src/plan-credit.ts

@@ -0,0 +1,66 @@
+/**
+ * Plan-credit derivations shared by the assistant runtime's `platform credits`
+ * route and the web client's usage meter, so both read the billing summary's
+ * grant figures the same way and can never quote different readings.
+ */
+
+export type BillingPlanId = "base" | "pro";
+
+function clamp01(value: number): number {
+  if (!Number.isFinite(value) || value < 0) {
+    return 0;
+  }
+  return value > 1 ? 1 : value;
+}
+
+/**
+ * How much of the usage credit an account was granted it has already used:
+ * the granted total less what is still unused, over that total. The initial
+ * $5 grant burns 0 to 100% as it is spent, and a further grant grows the total
+ * so the bar drops back. Null when nothing was ever granted, or when the
+ * platform reports neither figure, which has no honest reading rather than a
+ * full or empty bar.
+ */
+export function usageGrantRatio(
+  totalUsd: number | null,
+  availableUsd: number | null,
+): number | null {
+  if (totalUsd == null || availableUsd == null || totalUsd <= 0) {
+    return null;
+  }
+  return clamp01((totalUsd - availableUsd) / totalUsd);
+}
+
+/**
+ * The plan-credit reading with the plan's fallback applied. The grant figures
+ * count only unexpired grants, so a Pro subscription whose grants total
+ * nothing has used or expired everything it was granted (a full bar, with
+ * nothing scheduled to refill it), while a base plan in that position was
+ * never granted anything (no reading). An unknown plan gets the ratio when
+ * the figures allow one and no fallback otherwise.
+ */
+export function planCreditUsedFraction(
+  totalUsd: number | null,
+  availableUsd: number | null,
+  planId: BillingPlanId | null,
+): number | null {
+  const ratio = usageGrantRatio(totalUsd, availableUsd);
+  if (ratio != null) {
+    return ratio;
+  }
+  if (planId === "pro" && totalUsd != null && totalUsd <= 0) {
+    return 1;
+  }
+  return null;
+}
+
+/**
+ * Credit bought or earned on top of the plan-included grants: the balance less
+ * whatever is still unused on those grants, never below zero, to the cent.
+ */
+export function extraCreditUsd(
+  balanceUsd: number,
+  availableUsd: number,
+): number {
+  return Math.round(Math.max(0, balanceUsd - availableUsd) * 100) / 100;
+}

package/node_modules/@vellumai/service-contracts/src/reactions.ts

@@ -7,11 +7,13 @@
  * is spelled. Modelled on Zulip's `reaction_type`, the one surveyed system
  * that separates the namespace from the name.
  *
- * `shortcode` is a name in a channel's own namespace whose kind the channel
- * does not disclose: Slack sends `+1` for the standard emoji and `blob_wave`
- * for a workspace upload with nothing to tell them apart, and only the
- * workspace token can resolve the second. It is a distinct kind from
- * `unicode`, not a stand-in for an unknown one.
+ * `shortcode` is a name in a channel's own namespace that the channel's
+ * adapter could not place among the standard emoji. Slack sends `+1` and
+ * `blob_wave` alike, as names; its normalizer resolves the standard ones to
+ * `unicode` from Slack's own list, and what remains is a workspace upload
+ * only the workspace can render. It is a distinct kind from `unicode`, not
+ * a stand-in for an unknown one, and nothing past an adapter needs a
+ * channel's naming to read it.
  */
 import { z } from "zod";
 
@@ -39,6 +41,12 @@ export const ReactionEmojiFieldsSchema = z.object({
 });
 export type ReactionEmojiFields = z.infer<typeof ReactionEmojiFieldsSchema>;
 
+/** The typed fields with the kind and name known. */
+export type ReactionEmojiIdentity = ReactionEmojiFields & {
+  emojiKind: ReactionEmojiKind;
+  emojiName: string;
+};
+
 /**
  * The typed emoji fields a source actually carries, with undefined ones
  * omitted: an absent key and a present-but-undefined one serialize alike, but the
@@ -58,3 +66,75 @@ export function pickReactionEmojiFields(
       : {}),
   };
 }
+
+/**
+ * Parse Discord's custom-emoji mention form. The form travels the wire as a
+ * reaction's spelling, so more than one package reads it: the daemon rebuilds
+ * a REST path from it when the assistant reacts, and a row carrying only the
+ * spelling recovers its kind from it. One parser, so the two cannot disagree
+ * about what counts as one.
+ *
+ * `animated` reports whether the spelling carries the `a` marker. Discord's
+ * normalizer never writes that marker, so it is read only from spellings that
+ * arrive from elsewhere: a row written by another producer, or a value the
+ * model hands back as it received it.
+ */
+export function parseDiscordEmojiMention(
+  emoji: string,
+): { name: string; id: string; animated: boolean } | null {
+  const match = /^<(a?):([^:>]+):(\d+)>$/.exec(emoji);
+  return match
+    ? { name: match[2]!, id: match[3]!, animated: match[1] === "a" }
+    : null;
+}
+
+/**
+ * Recover an emoji's kind from its spelling alone. This is the one inference
+ * the design permits, reserved for a value that carries the string and no
+ * typed fields: a persisted row or a replayed retry payload. A value that
+ * declares its kind never reaches this; `reactionEmojiIdentity` makes that
+ * choice for every reader.
+ *
+ * A mention form is unambiguous. Past that the two remaining kinds are told
+ * apart by whether the string is a name at all: a channel's shortcode is
+ * ASCII word characters, optionally carrying Slack's `::skin-tone-N`
+ * suffix, and anything else is the character itself.
+ */
+export function classifyReactionEmojiSpelling(
+  emoji: string,
+): ReactionEmojiIdentity {
+  const custom = parseDiscordEmojiMention(emoji);
+  if (custom) {
+    // The plain `<:name:id>` form says nothing about animation: the
+    // normalizer spells every custom emoji that way and reports animation
+    // in the typed field instead, so a spelling without the `a` marker is
+    // "unrecorded", not "not animated". Only the `<a:` form asserts it.
+    return {
+      emojiKind: "custom",
+      emojiName: custom.name,
+      emojiId: custom.id,
+      ...(custom.animated ? { emojiAnimated: true } : {}),
+    };
+  }
+  return /^[\w+-]+(::skin-tone-[2-6])?$/.test(emoji)
+    ? { emojiKind: "shortcode", emojiName: emoji }
+    : { emojiKind: "unicode", emojiName: emoji };
+}
+
+/**
+ * The typed identity of a reaction's emoji: the fields it declares when it
+ * declares a kind, otherwise the kind recovered from its spelling. Every
+ * reader that must know what an emoji is goes through this, so the wire
+ * contract and the web agree on when the spelling is consulted.
+ */
+export function reactionEmojiIdentity(
+  reaction: { emoji: string } & ReactionEmojiFields,
+): ReactionEmojiIdentity {
+  return reaction.emojiKind !== undefined && reaction.emojiName !== undefined
+    ? {
+        ...pickReactionEmojiFields(reaction),
+        emojiKind: reaction.emojiKind,
+        emojiName: reaction.emojiName,
+      }
+    : classifyReactionEmojiSpelling(reaction.emoji);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/credential-executor",
-  "version": "0.11.10",
+  "version": "0.11.11-staging.2",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/transport.test.ts

@@ -163,6 +163,10 @@ describe("health probes", () => {
     expect(src).toMatch(/\/readyz/);
     // Health server uses Bun.serve on a dedicated port, not the socket
     expect(src).toMatch(/startHealthServer\(\s*healthPort/);
+    // Kubelet httpGet targets the pod IP, so the probe listener must not
+    // bind loopback-only. Credential routes are gated with isLoopbackAddress.
+    expect(src).not.toMatch(/hostname:\s*"127\.0\.0\.1"/);
+    expect(src).toMatch(/isLoopbackAddress\(/);
   });
 
   test("getHealthPort defaults to 8090", () => {

package/src/http/loopback-address.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  isCesHttpProbePath,
+  isLoopbackAddress,
+} from "./loopback-address.js";
+
+describe("isLoopbackAddress", () => {
+  test("accepts IPv4 loopback", () => {
+    expect(isLoopbackAddress("127.0.0.1")).toBe(true);
+    expect(isLoopbackAddress("127.0.0.2")).toBe(true);
+  });
+
+  test("accepts IPv6 loopback and IPv4-mapped loopback", () => {
+    expect(isLoopbackAddress("::1")).toBe(true);
+    expect(isLoopbackAddress("::ffff:127.0.0.1")).toBe(true);
+  });
+
+  test("rejects non-loopback addresses", () => {
+    expect(isLoopbackAddress("10.0.0.1")).toBe(false);
+    expect(isLoopbackAddress("192.168.1.10")).toBe(false);
+    expect(isLoopbackAddress("8.8.8.8")).toBe(false);
+    expect(isLoopbackAddress("::ffff:10.0.0.1")).toBe(false);
+    expect(isLoopbackAddress("2001:db8::1")).toBe(false);
+  });
+});
+
+describe("isCesHttpProbePath", () => {
+  test("matches kubelet probe paths only", () => {
+    expect(isCesHttpProbePath("/healthz")).toBe(true);
+    expect(isCesHttpProbePath("/readyz")).toBe(true);
+    expect(isCesHttpProbePath("/v1/credentials")).toBe(false);
+    expect(isCesHttpProbePath("/v1/logs/export")).toBe(false);
+  });
+});

package/src/http/loopback-address.ts

@@ -0,0 +1,25 @@
+/**
+ * Strict loopback check for CES HTTP peers: 127.0.0.0/8 and ::1.
+ * IPv4-mapped IPv6 (`::ffff:127.0.0.1`) is treated as IPv4.
+ */
+export function isLoopbackAddress(addr: string): boolean {
+  const v4Mapped = addr.match(/^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/i);
+  const normalized = v4Mapped ? v4Mapped[1] : addr;
+
+  if (normalized.includes(".")) {
+    const parts = normalized.split(".").map(Number);
+    if (
+      parts.length !== 4 ||
+      parts.some((p) => Number.isNaN(p) || p < 0 || p > 255)
+    ) {
+      return false;
+    }
+    return parts[0] === 127;
+  }
+
+  return normalized.toLowerCase() === "::1";
+}
+
+export function isCesHttpProbePath(pathname: string): boolean {
+  return pathname === "/healthz" || pathname === "/readyz";
+}

package/src/main.ts

@@ -51,6 +51,7 @@ import {
   type CredentialRouteDeps,
 } from "./http/credential-routes.js";
 import { handleLogExportRoute } from "./http/log-export-routes.js";
+import { isLoopbackAddress } from "./http/loopback-address.js";
 import { handleMetadataRoute } from "./http/metadata-routes.js";
 import { CES_MIGRATIONS } from "./migrations/registry.js";
 import { runCesMigrations } from "./migrations/runner.js";
@@ -246,9 +247,12 @@ function startHealthServer(
   signal: AbortSignal,
   credentialDeps: CredentialRouteDeps | null,
 ): ReturnType<typeof Bun.serve> {
+  // Listen on every interface so kubelet httpGet probes can hit the pod IP.
+  // Credential CRUD, metadata, and log export stay loopback-only: assistant
+  // and gateway in this pod call http://localhost:<CES_HEALTH_PORT>.
   const server = Bun.serve({
     port,
-    async fetch(req) {
+    async fetch(req, httpServer) {
       const url = new URL(req.url);
       if (url.pathname === "/healthz") {
         return new Response(JSON.stringify({ status: "ok" }), {
@@ -256,7 +260,7 @@ function startHealthServer(
         });
       }
       if (url.pathname === "/readyz") {
-        // Always return 200 — pod readiness must not depend on whether the
+        // Always return 200: pod readiness must not depend on whether the
         // assistant has connected.  When the CES feature flag is off the
         // assistant never connects, and a 503 here would block pod
         // scheduling during dark-launch.  The sidecar can't do useful work
@@ -275,6 +279,11 @@ function startHealthServer(
         );
       }
 
+      const peer = httpServer.requestIP(req)?.address;
+      if (!peer || !isLoopbackAddress(peer)) {
+        return new Response("Not Found", { status: 404 });
+      }
+
       // Credential CRUD routes (only if service token is configured)
       if (credentialDeps) {
         const metadataResponse = await handleMetadataRoute(req);