@vellumai/assistant 0.11.10 → 0.11.11-staging.1

package/AGENTS.md

@@ -16,7 +16,7 @@ When you introduce a new env var that the assistant process needs to read at run
 
 **Default to including it.** If the var doesn't contain secrets (e.g. a URL, a feature flag, a path, a mode string), add it. Only omit it if it carries credential material (tokens, passwords, private keys) — those must stay isolated to CES.
 
-`CES_LOCAL_SOCKET` is intentionally included despite the socket exposing credential RPCs — assistant subprocesses are expected to reach CES. Credential protection is rules-based access control inside CES, not socket-path secrecy (see root `AGENTS.md`).
+`CES_LOCAL_SOCKET` is intentionally included despite the socket exposing credential RPCs: assistant subprocesses are expected to reach CES. Credential protection is rules-based access control inside CES, not socket-path secrecy (see root `AGENTS.md`). Do not forward `CES_SERVICE_TOKEN` or `CES_CREDENTIAL_URL`: the HTTP bearer is a vault secret and must stay in the assistant process.
 
 ## Daemon startup philosophy
 

package/node_modules/@vellumai/ces-client/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/ces-client/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/ces-client/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/ces-client/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/gateway-client/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/gateway-client/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/gateway-client/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/gateway-client/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/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;
+}