@vellumai/assistant 0.11.9 → 0.11.10-dev.202609091114.7b6342c

package/ARCHITECTURE.md

@@ -145,7 +145,7 @@ All guardian approval decisions, regardless of how they arrive, route through a
 
 **Text fallback path (always available):**
 
-- Every prompt includes a `requestCode` (6-char alphanumeric). Guardians can reply with `<requestCode> approve` or `<requestCode> reject` on any channel.
+- Every prompt includes a `requestCode` (6-char alphanumeric). Guardians can reply with `<requestCode> approve` or `<requestCode> reject` on any channel. The instruction saying so travels only in the card's `plainTextFallback`, which a transport appends when it sends text without buttons; composed copy and `questionText` never carry it.
 - `access_request` prompts carry the request-code verify/trust/reject/block directive in the card's `plainTextFallback`, appended by a transport only when it sends text without buttons; the `"open invite flow"` phrase for starting the Trusted Contacts invite flow stays in the text on every surface because nothing offers a button for it.
 - `pending_question` prompts (voice-originated) support `<requestCode> <your answer>` for free-text answers.
 - The `routeGuardianReply` router processes text replies through a priority-ordered pipeline: callback parsing -> request code parsing -> NL classification. All paths converge on `applyGuardianDecision`.
@@ -199,7 +199,7 @@ The guardian request system provides a channel-agnostic, unified domain for all
 
 4. **Deterministic API (prompt listing and decision endpoints):** Desktop clients and API consumers use `GET /v1/guardian-actions/pending` and `POST /v1/guardian-actions/decision` (HTTP). These endpoints surface guardian requests alongside legacy pending interactions and channel approval records, with deduplication to avoid double-rendering.
 
-5. **Buttons first, text fallback:** All request kinds (`tool_approval`, `pending_question`, `access_request`) are rendered as structured button cards when displayed in macOS guardian conversations. Each prompt also embeds deterministic text fallback instructions (request-code-based approve/reject directives, and for `access_request` the "open invite flow" phrase) so text-based channels and manual fallback always work. Code-only messages (just a request code without decision text) return clarification instead of auto-approving. Disambiguation with multiple pending requests stays fail-closed — no auto-resolve when the target is ambiguous.
+5. **Buttons first, text fallback:** All request kinds (`tool_approval`, `pending_question`, `access_request`) are rendered as structured button cards when displayed in macOS guardian conversations. Each card also carries deterministic text fallback instructions (request-code-based directives, and for `access_request` the "open invite flow" phrase) in its `plainTextFallback`, appended by a transport only when it sends text without buttons, so text-based channels and manual fallback always work without the instructions duplicating the buttons. Code-only messages (just a request code without decision text) return clarification instead of auto-approving. Disambiguation with multiple pending requests stays fail-closed: no auto-resolve when the target is ambiguous.
 
 **Resolver registry:** Kind-specific resolvers (`src/approvals/guardian-request-resolvers.ts`) handle side effects after CAS resolution. Built-in resolvers: `tool_approval` (channel/desktop approval path), `pending_question` (voice call question path), and `access_request` (trusted-contact verification session creation). New request kinds register resolvers without touching the core primitive.
 

package/Dockerfile

@@ -30,19 +30,10 @@ COPY assistant/package.json ./assistant/
 COPY assistant/src/api/package.json ./assistant/src/api/
 COPY --parents packages/*/package.json ./
 
-RUN bun install --frozen-lockfile --ignore-scripts \
+RUN --mount=type=cache,id=bun-install-cache,target=/root/.bun/install/cache \
+    bun install --frozen-lockfile --ignore-scripts \
     --filter='./assistant' --filter='./assistant/src/api'
 
-# The repo-root .dockerignore decides which skills (and files) ship.
-COPY skills ./skills
-RUN set -eu; for pkg in /app/skills/*/package.json; do \
-      [ -e "$pkg" ] || continue; \
-      dir="$(dirname "$pkg")"; \
-      echo "Installing dependencies for $dir"; \
-      (cd "$dir" && (bun install --frozen-lockfile 2>/dev/null || bun install)); \
-    done
-
-
 # Final stage
 FROM debian:trixie-slim@sha256:4ffb3a1511099754cddc70eb1b12e50ffdb67619aa0ab6c13fcd800a78ef7c7a AS runner
 
@@ -114,7 +105,7 @@ RUN apt-get update && apt-get install -y \
 COPY --from=builder /root/.bun/bin/bun /usr/local/bin/bun
 RUN ln -sf /usr/local/bin/bun /usr/local/bin/bunx
 
-COPY --from=builder /app /app
+COPY --link --from=builder /app /app
 
 # Copy source after installing dependencies for better layer caching.
 COPY packages/avatar-catalog /app/packages/avatar-catalog
@@ -131,6 +122,9 @@ COPY packages/twilio-client /app/packages/twilio-client
 
 COPY assistant /app/assistant
 
+# The repo-root .dockerignore decides which skills (and files) ship.
+COPY skills /app/skills
+
 # Materialize the git-ignored offline plugin manifest from its canonical source.
 # `assistant/src/cli/lib/plugin-catalog-local.ts` statically imports this JSON
 # (loaded even when platform features are enabled), so it must exist in the image

package/docs/architecture/memory.md

@@ -13,7 +13,7 @@ An assistant runs exactly one memory tier, derived by `memoryTier()` in
 | Tier  | Selected when                                | Injection source                                 |
 | ----- | -------------------------------------------- | ------------------------------------------------ |
 | `off` | `memory.enabled === false`                   | none                                             |
-| `v3`  | `memory.v3.live === true`                    | v3 lanes + card (`v3/injector.ts`)               |
+| `v3`  | `memory.v3.live === true`                    | v3 lanes + sections (`v3/injector.ts`)           |
 | `v2`  | `memory.v2.enabled === true` and v3 not live | v2 activation/router engine (`v2/`)              |
 | `v1`  | otherwise                                    | PKB `<knowledge_base>` block (`v1/pkb/`, legacy) |
 
@@ -172,12 +172,20 @@ Ingested pages carry provenance frontmatter with distinct consumers:
 
 - **v3 (live)**: per-turn lane selection over concept pages (dense/sparse
   retrieval via `substrate/sim.ts` over the concept-page collection,
-  learned edges, entity/hot/fresh/core sets) rendered as the `<memory>`
-  card by `v3/injector.ts`. Frozen cards stay on historical user messages
-  so the provider prefix stays cacheable. Each turn's `<memory_spotlight>`
-  stays on the user message that was sent with it. A new spotlight is
-  added only on the new tail, so older messages are not rewritten. The
-  static `<info>` block
+  learned edges, entity/hot/fresh/core sets). The injection unit is the
+  SECTION: the selector pool lists a page once per matched section, and
+  `v3/injector.ts` renders each selected page's selected sections (its lead
+  when it was selected with none) into a `<memory>` block,
+  net-new sections only, deduped per `(page, section)` through
+  `memory_v3_injected_sections` and bounded by a recency prune valve with no
+  lane exemptions. Section bodies are backslash-escaped where a line would
+  read as a block header, so page text never forges a section boundary, and a
+  pruned section is dropped from any pointer that named it. Frozen section
+  blocks stay on historical user messages so
+  the provider prefix stays cacheable. Re-selected sections that are already
+  resident are listed, paths only, in a per-turn `<memory_pointer>` block
+  that stays on the user message it was sent with; a new pointer is added
+  only on the new tail, so older messages are not rewritten. The static `<info>` block
   (`substrate/static-context.ts`: essentials/threads/recent/buffer) also
   injects whenever the substrate is active.
 - **v2 (transitional)**: activation/router engine in `v2/`
@@ -192,8 +200,8 @@ Ingested pages carry provenance frontmatter with distinct consumers:
 
 The live voice front door does not await current-turn memory retrieval. Its
 prompt hook skips legacy graph retrieval, and both v3 injectors skip
-orchestration for `voiceFrontDoor`. Frozen cards from prior turns and the static
-substrate context remain available. When the answer depends on a saved personal
+orchestration for `voiceFrontDoor`. Frozen sections from prior turns and the
+static substrate context remain available. When the answer depends on a saved personal
 fact that is absent from that context, the front-door rule escalates instead of
 guessing.
 

package/docs/guardian-request-flow.md

@@ -131,10 +131,13 @@ routing after a restart even though the card is absent from the model's history.
 Two instruction modes exist per request kind (`notifications/guardian-question-mode.ts`):
 **approval** ("CODE approve" / approve–reject buttons) and **answer**
 ("CODE <your answer>" / option buttons). `pending_question` is answer-mode.
-Whether a channel's copy carries the "CODE <reply>" instruction at all is one
-rule, `guardianCopyCarriesReplyMechanics`: text chats do, while the vellum
-bell and banner, the platform push, and Slack approval cards act through the
-card and have it stripped.
+The "CODE <reply>" instruction lives in exactly one place: the
+`plainTextFallback` the broadcaster builds beside the card's actions. Composed
+copy never carries it (the decision engine strips a model's echo of it on
+every channel), and a transport appends it only when it sends text without
+buttons: a rich delivery that failed, or a request with no actions to draw,
+which is how an option-less voice question stays answerable. Every surface
+with buttons, and the bell, banner, and push, show the ask alone.
 
 ## Worked example: `ask_question` on a channel
 

package/docs/runbook-trusted-contacts.md

@@ -146,9 +146,13 @@ sqlite3 "file:$GW_DB?mode=ro" \
 
 ## 3b. Contact writes
 
-All write operations on contacts are gateway-owned. Use the gateway CLI, not
+Contact writes are gateway-owned, and they reach it two ways. An operator ACL
+write (a risk ceiling) goes through the gateway CLI directly, not through
 `assistant contacts`. From the host, run the same command via
-`vellum exec --service gateway --`.
+`vellum exec --service gateway --`. A write that changes the contact graph
+itself (the record, or a channel binding) goes through `assistant contacts`,
+which opens a form in the guardian's app and writes nothing until they submit
+it; the gateway still performs the write.
 
 ```bash
 gateway contacts set-risk-threshold <contactId> --threshold high
@@ -156,6 +160,13 @@ gateway contacts set-risk-threshold <contactId> --threshold high
 
 `inherit` clears the risk ceiling so the contact follows room and trust-class settings. Stored vocabulary is `none`, `low`, `medium`, or `high`.
 
+Binding an address to a contact goes through the guardian instead of the operator. The command below opens a form in the guardian's app naming that contact, and the gateway writes the channel only when they submit it. An address already held by a different contact is refused, naming that contact.
+
+```bash
+assistant contacts channels add <contactId> --channel <type> --address <addr>
+assistant contacts channels add <contactId> --channel email --address alice@example.com
+```
+
 ## 4. Force-Revoke a Trusted Contact
 
 ### Via CLI (preferred)

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

@@ -10,6 +10,7 @@
     "./conversation-handle": "./src/conversation-handle.ts",
     "./client-metadata": "./src/client-metadata.ts",
     "./credential-rpc": "./src/credential-rpc.ts",
+    "./desktop-presence": "./src/desktop-presence.ts",
     "./ingress": "./src/ingress.ts",
     "./no-response": "./src/no-response.ts",
     "./remote-web-pairing": "./src/remote-web-pairing.ts",
@@ -25,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/__tests__/secret-detection.test.ts

@@ -38,6 +38,8 @@ const FIXTURES: Record<string, string> = {
   "GitLab Token": `glpat-${filler(20)}`,
   "Stripe Secret Key": `sk_live_${filler(24)}`,
   "Stripe Restricted Key": `rk_live_${filler(24)}`,
+  "Link Access Token": `liwltoken_${filler(24)}`,
+  "Link Refresh Token": `liwlrefresh_${filler(24)}`,
   "Slack Bot Token": `xoxb-1234567890-1234567890-${filler(24)}`,
   "Slack User Token": `xoxp-1234567890-1234567890-1234567890-${"0123456789abcdef".repeat(2)}`,
   "Slack App Token": "xapp-1-abc123-4567-defghij890",

package/node_modules/@vellumai/ces-client/node_modules/@vellumai/service-contracts/src/desktop-presence.ts

@@ -0,0 +1,11 @@
+/**
+ * The presence states a desktop client may report. Single runtime source for
+ * the daemon's stored type, the client route's wire enum, and the Electron
+ * presence monitor.
+ *
+ * Member order is load-bearing: the route feeds this tuple to `z.enum`, so
+ * reordering rewrites the generated `assistant/openapi.yaml`.
+ */
+export const DESKTOP_PRESENCE_STATES = ["active", "idle", "away"] as const;
+
+export type DesktopPresenceState = (typeof DESKTOP_PRESENCE_STATES)[number];

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/ces-client/node_modules/@vellumai/service-contracts/src/secret-detection.ts

@@ -143,6 +143,13 @@ export const PREFIX_PATTERNS: SecretPrefixPattern[] = [
   // -- Stripe --
   { label: "Stripe Secret Key", regex: /sk_live_[A-Za-z0-9]{24,}/ },
   { label: "Stripe Restricted Key", regex: /rk_live_[A-Za-z0-9]{24,}/ },
+  // Link (Stripe's wallet) issues prefixed OAuth tokens rather than opaque
+  // ones, and its own docs tell users to export the access token as
+  // LINK_ACCESS_TOKEN to drive link-cli, so these do get pasted by hand. A
+  // leaked one can spend from the wallet. The `lwlpk_` client id is public
+  // (it ships in the CLI bundle) and is deliberately not matched here.
+  { label: "Link Access Token", regex: /liwltoken_[A-Za-z0-9]{16,}/ },
+  { label: "Link Refresh Token", regex: /liwlrefresh_[A-Za-z0-9]{16,}/ },
 
   // -- Slack --
   {

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

@@ -10,6 +10,7 @@
     "./conversation-handle": "./src/conversation-handle.ts",
     "./client-metadata": "./src/client-metadata.ts",
     "./credential-rpc": "./src/credential-rpc.ts",
+    "./desktop-presence": "./src/desktop-presence.ts",
     "./ingress": "./src/ingress.ts",
     "./no-response": "./src/no-response.ts",
     "./remote-web-pairing": "./src/remote-web-pairing.ts",
@@ -25,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/__tests__/secret-detection.test.ts

@@ -38,6 +38,8 @@ const FIXTURES: Record<string, string> = {
   "GitLab Token": `glpat-${filler(20)}`,
   "Stripe Secret Key": `sk_live_${filler(24)}`,
   "Stripe Restricted Key": `rk_live_${filler(24)}`,
+  "Link Access Token": `liwltoken_${filler(24)}`,
+  "Link Refresh Token": `liwlrefresh_${filler(24)}`,
   "Slack Bot Token": `xoxb-1234567890-1234567890-${filler(24)}`,
   "Slack User Token": `xoxp-1234567890-1234567890-1234567890-${"0123456789abcdef".repeat(2)}`,
   "Slack App Token": "xapp-1-abc123-4567-defghij890",

package/node_modules/@vellumai/gateway-client/node_modules/@vellumai/service-contracts/src/desktop-presence.ts

@@ -0,0 +1,11 @@
+/**
+ * The presence states a desktop client may report. Single runtime source for
+ * the daemon's stored type, the client route's wire enum, and the Electron
+ * presence monitor.
+ *
+ * Member order is load-bearing: the route feeds this tuple to `z.enum`, so
+ * reordering rewrites the generated `assistant/openapi.yaml`.
+ */
+export const DESKTOP_PRESENCE_STATES = ["active", "idle", "away"] as const;
+
+export type DesktopPresenceState = (typeof DESKTOP_PRESENCE_STATES)[number];

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/gateway-client/node_modules/@vellumai/service-contracts/src/secret-detection.ts

@@ -143,6 +143,13 @@ export const PREFIX_PATTERNS: SecretPrefixPattern[] = [
   // -- Stripe --
   { label: "Stripe Secret Key", regex: /sk_live_[A-Za-z0-9]{24,}/ },
   { label: "Stripe Restricted Key", regex: /rk_live_[A-Za-z0-9]{24,}/ },
+  // Link (Stripe's wallet) issues prefixed OAuth tokens rather than opaque
+  // ones, and its own docs tell users to export the access token as
+  // LINK_ACCESS_TOKEN to drive link-cli, so these do get pasted by hand. A
+  // leaked one can spend from the wallet. The `lwlpk_` client id is public
+  // (it ships in the CLI bundle) and is deliberately not matched here.
+  { label: "Link Access Token", regex: /liwltoken_[A-Za-z0-9]{16,}/ },
+  { label: "Link Refresh Token", regex: /liwlrefresh_[A-Za-z0-9]{16,}/ },
 
   // -- Slack --
   {

package/node_modules/@vellumai/gateway-client/src/gateway-ipc-contracts.ts

@@ -401,6 +401,78 @@ export type ContactsIdentitySnapshotIpcResponse = z.infer<
   typeof ContactsIdentitySnapshotIpcResponseSchema
 >;
 
+// ── webhook ingress routes ───────────────────────────────────────────────────
+// The gateway owns the registry of subpaths this assistant answers from
+// outside; the daemon claims, drops, and inspects them over IPC. Both sides
+// read these schemas so a change to the stored row has to travel through the
+// contract.
+
+/**
+ * Feature flag gating the whole webhook ingress registry. The gateway reads it
+ * to decide whether to accept a claim and how to advertise its allowed paths,
+ * and the daemon reads it to decide whether to claim at all, so both sides have
+ * to name the same key.
+ */
+export const WebhookIngressRouteSchema = z.object({
+  path: z.string(),
+  type: z.string(),
+  source: z.string().nullable(),
+  match: z.literal("exact"),
+  createdAt: z.number(),
+  lastRegisteredAt: z.number(),
+});
+
+export type WebhookIngressRoute = z.infer<typeof WebhookIngressRouteSchema>;
+
+export const RegisterWebhookRouteIpcParamsSchema = z.object({
+  /** Exact subpath, leading slash included, under `/webhooks/`. */
+  path: z.string().min(1),
+  type: z.string().min(1),
+  source: z.string().nullish(),
+});
+
+export type RegisterWebhookRouteIpcParams = z.infer<
+  typeof RegisterWebhookRouteIpcParamsSchema
+>;
+
+/**
+ * A refusal is a normal result rather than an error: the daemon reads
+ * `disabled` as "this assistant is not serving its own webhooks" and falls
+ * back to the platform's callback routes.
+ */
+export const RegisterWebhookRouteIpcResponseSchema = z.union([
+  z.object({ disabled: z.literal(true) }),
+  z.object({ disabled: z.literal(false), route: WebhookIngressRouteSchema }),
+]);
+
+export type RegisterWebhookRouteIpcResponse = z.infer<
+  typeof RegisterWebhookRouteIpcResponseSchema
+>;
+
+export const UnregisterWebhookRouteIpcParamsSchema = z.object({
+  path: z.string().min(1),
+});
+
+export type UnregisterWebhookRouteIpcParams = z.infer<
+  typeof UnregisterWebhookRouteIpcParamsSchema
+>;
+
+export const UnregisterWebhookRouteIpcResponseSchema = z.object({
+  removed: z.boolean(),
+});
+
+export type UnregisterWebhookRouteIpcResponse = z.infer<
+  typeof UnregisterWebhookRouteIpcResponseSchema
+>;
+
+export const ListWebhookRoutesIpcResponseSchema = z.object({
+  routes: z.array(WebhookIngressRouteSchema),
+});
+
+export type ListWebhookRoutesIpcResponse = z.infer<
+  typeof ListWebhookRoutesIpcResponseSchema
+>;
+
 // ── classify_risk ────────────────────────────────────────────────────────────
 // Risk classification is gateway-owned; the assistant sends one request per
 // tool invocation and reads the whole answer back. The gateway validates the

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

@@ -10,6 +10,7 @@
     "./conversation-handle": "./src/conversation-handle.ts",
     "./client-metadata": "./src/client-metadata.ts",
     "./credential-rpc": "./src/credential-rpc.ts",
+    "./desktop-presence": "./src/desktop-presence.ts",
     "./ingress": "./src/ingress.ts",
     "./no-response": "./src/no-response.ts",
     "./remote-web-pairing": "./src/remote-web-pairing.ts",
@@ -25,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",