@vellumai/assistant 0.11.9-dev.202609081913.93e93af → 0.11.9-dev.202609082126.a4f0fef

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;
+}

package/openapi.yaml

@@ -5102,7 +5102,7 @@ paths:
     put:
       operationId: config_embeddings_put
       summary: Set embedding config
-      description: Change the embedding provider and optionally model.
+      description: Change the embedding provider, model, and optional custom endpoint.
       tags:
         - config
       requestBody:
@@ -5116,6 +5116,14 @@ paths:
                   type: string
                 model:
                   type: string
+                baseUrl:
+                  type: string
+                dimensions:
+                  anyOf:
+                    - type: integer
+                      exclusiveMinimum: 0
+                      maximum: 9007199254740991
+                    - type: "null"
               required:
                 - provider
       responses:
@@ -13745,6 +13753,13 @@ paths:
                     anyOf:
                       - type: string
                       - type: "null"
+                  effectiveTimezone:
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                    description:
+                      Timezone used for cron and active-hours evaluation after resolving heartbeat.timezone, then the user's
+                      configured or detected zone
                   nextRunAt:
                     anyOf:
                       - type: number
@@ -13762,6 +13777,7 @@ paths:
                   - activeHoursEnd
                   - cronExpression
                   - timezone
+                  - effectiveTimezone
                   - nextRunAt
                   - lastRunAt
                   - success
@@ -13801,7 +13817,7 @@ paths:
                     - type: string
                     - type: "null"
                 timezone:
-                  description: Timezone for cron evaluation
+                  description: Timezone for cron and active-hours evaluation
                   anyOf:
                     - type: string
                     - type: "null"
@@ -13833,6 +13849,13 @@ paths:
                     anyOf:
                       - type: string
                       - type: "null"
+                  effectiveTimezone:
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                    description:
+                      Timezone used for cron and active-hours evaluation after resolving heartbeat.timezone, then the user's
+                      configured or detected zone
                   nextRunAt:
                     anyOf:
                       - type: number
@@ -13850,6 +13873,7 @@ paths:
                   - activeHoursEnd
                   - cronExpression
                   - timezone
+                  - effectiveTimezone
                   - nextRunAt
                   - lastRunAt
                   - success
@@ -20044,6 +20068,7 @@ paths:
                               - openai
                               - gemini
                               - ollama
+                              - custom
                           - type: "null"
                       model:
                         anyOf:
@@ -24668,12 +24693,13 @@ paths:
   /v1/platform/credits:
     get:
       operationId: platform_credits_get
-      summary: Get the organization's remaining credit balance and daily-limit state
+      summary: Get the organization's credit balance, plan-credit usage, and daily-limit state
       description:
         "Fetches the org's settled, pending, and effective (remaining) credit balance in USD from the platform
-        billing summary, plus the daily-limit state: today's spend counted against the daily credit limit (which
-        excludes spend covered by plan-included credits, so it is not total spend), the limit itself, and the
-        low-balance warning state."
+        billing summary, plus plan-included credit usage (remaining, total, and the used fraction shown by the in-app
+        usage meter), extra credit bought or earned on top, credit expiring within 30 days, and the daily-limit state:
+        today's spend counted against the daily credit limit (which excludes spend covered by plan-included credits, so
+        it is not total spend), the limit itself, and the low-balance warning state."
       tags:
         - platform
       responses:
@@ -24724,6 +24750,56 @@ paths:
                   low_balance_warning:
                     type: boolean
                     description: True when the balance is above zero but below the low-balance threshold and auto top-up is not enabled.
+                  plan_credit_remaining:
+                    anyOf:
+                      - type: number
+                      - type: "null"
+                    description:
+                      Unused credit (USD) remaining on the unexpired plan-included grants (initial credit, Pro credit bundle).
+                      Null when the platform did not report grant figures.
+                  plan_credit_total:
+                    anyOf:
+                      - type: number
+                      - type: "null"
+                    description:
+                      Total credit (USD) those plan-included grants were worth, net of refunds. Null when the platform did not
+                      report grant figures.
+                  plan_credit_used_fraction:
+                    anyOf:
+                      - type: number
+                      - type: "null"
+                    description:
+                      "Share of the plan-included credit already used, from 0 to 1: the same reading as the in-app usage meter. A
+                      Pro subscription whose unexpired grants total nothing reads as 1 (everything granted is used or
+                      expired). Null when there is no usable reading: grant figures missing, or a zero total on a base
+                      or unknown plan."
+                  plan_credits_spent:
+                    anyOf:
+                      - type: boolean
+                      - type: "null"
+                    description:
+                      True when the plan-included credit is used up or expired. Whether further managed usage is funded is
+                      extra_credit_remaining (zero means the organization is out of credit). Null when there is no
+                      plan-credit reading.
+                  extra_credit_remaining:
+                    anyOf:
+                      - type: number
+                      - type: "null"
+                    description:
+                      "Credit (USD) bought or earned on top of the plan-included grants: remaining minus plan_credit_remaining,
+                      floored at zero. Null when grant figures are missing."
+                  credits_expiring_soon:
+                    anyOf:
+                      - type: number
+                      - type: "null"
+                    description:
+                      Unexpired credit (USD) on grants that expire within the next 30 days. Null when the platform did not report
+                      it.
+                  next_credit_expiry_at:
+                    anyOf:
+                      - type: string
+                      - type: "null"
+                    description: Earliest upcoming expiry (ISO 8601) across grants that still hold credit, or null when none is scheduled.
                 required:
                   - remaining
                   - settled
@@ -24737,6 +24813,13 @@ paths:
                   - daily_limit_snoozed
                   - low_balance_threshold
                   - low_balance_warning
+                  - plan_credit_remaining
+                  - plan_credit_total
+                  - plan_credit_used_fraction
+                  - plan_credits_spent
+                  - extra_credit_remaining
+                  - credits_expiring_soon
+                  - next_credit_expiry_at
                 additionalProperties: false
   /v1/platform/disconnect:
     post:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.11.9-dev.202609081913.93e93af",
+  "version": "0.11.9-dev.202609082126.a4f0fef",
   "license": "MIT",
   "type": "module",
   "exports": {