@vellumai/assistant 0.7.0 → 0.7.2

package/src/providers/types.ts

@@ -156,6 +156,19 @@ export interface SendMessageConfig {
    * silently fall through.
    */
   overrideProfile?: string;
+  /**
+   * Internal per-request HTTP headers for managed-proxy usage attribution.
+   * Provider clients may pass these through SDK request options only when the
+   * transport is Vellum-managed, and must never include this object in provider
+   * JSON request bodies.
+   */
+  usageAttributionHeaders?: Record<string, string>;
+  /**
+   * Controls local usage-ledger writes for attributed provider calls.
+   * Defaults to `auto`; conversation paths that aggregate usage separately
+   * set `manual` to avoid double-counting.
+   */
+  usageTracking?: "auto" | "manual";
   effort?: "none" | "low" | "medium" | "high" | "xhigh" | "max";
   speed?: "standard" | "fast";
   verbosity?: "low" | "medium" | "high";

package/src/providers/usage-tracking.ts

@@ -0,0 +1,96 @@
+import { recordUsageEvent } from "../memory/llm-usage-store.js";
+import { resolveUsageAttribution } from "../usage/attribution.js";
+import {
+  buildPricingUsageFromResponse,
+  resolveStructuredPricing,
+} from "../usage/pricing.js";
+import { getLogger } from "../util/logger.js";
+import type {
+  Message,
+  Provider,
+  ProviderResponse,
+  SendMessageOptions,
+  ToolDefinition,
+} from "./types.js";
+
+const log = getLogger("provider-usage-tracking");
+
+export class UsageTrackingProvider implements Provider {
+  public readonly name: string;
+  public readonly tokenEstimationProvider?: string;
+
+  constructor(private readonly inner: Provider) {
+    this.name = inner.name;
+    this.tokenEstimationProvider = inner.tokenEstimationProvider;
+  }
+
+  async sendMessage(
+    messages: Message[],
+    tools?: ToolDefinition[],
+    systemPrompt?: string,
+    options?: SendMessageOptions,
+  ): Promise<ProviderResponse> {
+    const response = await this.inner.sendMessage(
+      messages,
+      tools,
+      systemPrompt,
+      options,
+    );
+    this.recordUsage(response, options);
+    return response;
+  }
+
+  private recordUsage(
+    response: ProviderResponse,
+    options?: SendMessageOptions,
+  ): void {
+    const config = options?.config;
+    if (!config?.callSite) return;
+    if (config.usageTracking === "manual") return;
+    if (response.usage.inputTokens <= 0 && response.usage.outputTokens <= 0) {
+      return;
+    }
+
+    try {
+      const attribution = resolveUsageAttribution({
+        callSite: config.callSite,
+        overrideProfile: config.overrideProfile,
+      });
+      const providerName = response.actualProvider ?? this.inner.name;
+      const pricingUsage = buildPricingUsageFromResponse(
+        providerName,
+        response,
+      );
+      const pricing = resolveStructuredPricing(
+        providerName,
+        response.model,
+        pricingUsage,
+      );
+
+      recordUsageEvent(
+        {
+          actor: "llm_call_site",
+          provider: providerName,
+          model: response.model,
+          inputTokens: pricingUsage.directInputTokens,
+          outputTokens: pricingUsage.outputTokens,
+          cacheCreationInputTokens: pricingUsage.cacheCreationInputTokens,
+          cacheReadInputTokens: pricingUsage.cacheReadInputTokens,
+          conversationId: null,
+          runId: null,
+          requestId: null,
+          callSite: attribution.callSite,
+          inferenceProfile: attribution.appliedProfile,
+          inferenceProfileSource: attribution.profileSource,
+          llmCallCount: 1,
+        },
+        pricing,
+      );
+    } catch (err) {
+      log.warn(
+        { err, callSite: config.callSite },
+        "Failed to auto-record provider usage event (non-fatal)",
+      );
+    }
+  }
+}

package/src/runtime/AGENTS.md

@@ -12,6 +12,10 @@ The single HTTP send endpoint is `POST /v1/messages`. Key behaviors:
 
 Do NOT add new send endpoints. All message ingress should go through `POST /v1/messages` (HTTP).
 
+### GET handler idempotency
+
+GET handlers must be safe and side-effect-free — they must not enqueue background jobs, mutate database state, or trigger writes. If a feature needs server-initiated work in response to a client request, use an explicit POST endpoint or a push-based flow (SSE event → client refetch). See [RFC 9110 §9.2.1 — Safe Methods](https://httpwg.org/specs/rfc9110.html#safe.methods).
+
 ### Approvals (confirmations, secrets, trust rules)
 
 Approvals are **orthogonal to message sending**. The assistant asks for approval whenever it needs one — this is a separate concern from how a message enters the system.
@@ -65,11 +69,11 @@ Host browser allows the assistant to proxy CDP (Chrome DevTools Protocol) JSON-R
 
 The `chrome-extension` interface in `INTERFACE_IDS` is a non-interactive transport that supports only the `host_browser` capability — it does NOT support `host_bash`, `host_file`, or `host_cu`. This is encoded in `supportsHostProxy(id, capability)`: passing a capability argument returns `true` for `chrome-extension` only when the capability is `host_browser`; the no-arg form returns `false` for `chrome-extension` (so legacy desktop-only call sites that assume full-desktop proxy availability continue to gate correctly).
 
-For **self-hosted** deployments, `host_browser_request` frames are routed through the `ChromeExtensionRegistry` singleton (`runtime/chrome-extension-registry.ts`), which tracks active chrome-extension WebSocket connections keyed by `(guardianId, clientInstanceId)`. The registry is populated on WebSocket `open` and drained on `close` inside `http-server.ts`'s `/v1/browser-relay` handlers — see the `wsType === "browser-relay"` branches. For **cloud/platform-hosted** deployments, the chrome extension connects via SSE (`GET /v1/events` with `X-Vellum-Interface-Id: chrome-extension`) and `host_browser_request` frames travel through `assistantEventHub` to the SSE stream. The extension POSTs results back to `POST /v1/host-browser-result`. Transport selection is handled by `resolveHostBrowserSender()` which checks the `ChromeExtensionRegistry` first (WS), then the `ClientRegistry` for an SSE-connected chrome-extension client. For macOS, `host_browser_request` frames travel through `assistantEventHub` (SSE) by default; when the guardian also has an active extension connection, the registry-routed WebSocket sender takes precedence.
+For **self-hosted** deployments, `host_browser_request` frames are routed through the `ChromeExtensionRegistry` singleton (`runtime/chrome-extension-registry.ts`), which tracks active chrome-extension WebSocket connections keyed by `(guardianId, clientInstanceId)`. The registry is populated on WebSocket `open` and drained on `close` inside `http-server.ts`'s `/v1/browser-relay` handlers — see the `wsType === "browser-relay"` branches. For **cloud/platform-hosted** deployments, the chrome extension connects via SSE (`GET /v1/events` with `X-Vellum-Interface-Id: chrome-extension`) and `host_browser_request` frames travel through `assistantEventHub` to the SSE stream. The extension POSTs results back to `POST /v1/host-browser-result`. Transport selection is handled by `HostBrowserProxy`, which publishes events to the `assistantEventHub` with `targetCapability: "host_browser"` — the hub delivers to whichever subscriber (chrome-extension or macOS client) has the `host_browser` capability. For macOS, `host_browser_request` frames travel through `assistantEventHub` (SSE) by default; when the guardian also has an active extension connection, the registry-routed WebSocket sender takes precedence.
 
 A single guardian may have multiple parallel extension installs connected at once (two Chrome profiles, two desktops sharing a sync identity). Each install generates a stable `clientInstanceId` on first run, persists it in `chrome.storage.local`, and sends it on every WebSocket handshake as a query param (`clientInstanceId=...`) or header (`x-client-instance-id`). The registry keys inner entries by that id so sibling installs don't evict each other on register/unregister. The default `send(guardianId, msg)` path routes to whichever instance has the most recent activity (`lastActiveAt`); `sendToInstance(guardianId, clientInstanceId, msg)` pins a specific install. Older extension builds that omit the id get a connection-scoped `legacy:<connectionId>` fallback key so they degrade gracefully to single-instance semantics.
 
-`Conversation.hostBrowserSenderOverride` is the integration point between the turn layer and the registry. When any turn enters the routes layer and the guardian has an active extension connection in the `ChromeExtensionRegistry`, `conversation-routes.ts` resolves the registry entry and sets the override to a sender that writes to that WebSocket. This applies to chrome-extension turns (where the registry is the only transport) and macOS turns (where the extension connection lets browser tools route through the user's real Chrome session instead of cdp-inspect/local). `Conversation.restoreBrowserProxyAvailability()` re-threads the override on queue drain — without this, the drain path would clobber the registry-routed sender with the default `sendToClient` (pointed at the SSE hub) and `host_browser_request` frames would stop reaching the extension mid-queue.
+`Conversation.hostBrowserSenderOverride` is the integration point between the turn layer and the proxy. When any turn enters the routes layer and the guardian has an active extension connection in the `ChromeExtensionRegistry`, `conversation-routes.ts` resolves the registry entry and sets the override to a sender that writes to that WebSocket. This applies to chrome-extension turns (where the registry is the only transport) and macOS turns (where the extension connection lets browser tools route through the user's real Chrome session instead of cdp-inspect/local). `Conversation.restoreBrowserProxyAvailability()` re-threads the override on queue drain — without this, the drain path would clobber the registry-routed sender with the default `sendToClient` (pointed at the SSE hub) and `host_browser_request` frames would stop reaching the extension mid-queue.
 
 Capability token bootstrap for self-hosted deployments is handled by the gateway (`gateway/src/http/routes/browser-extension-pair.ts`) which mints a guardian-bound HMAC capability token. The daemon delegates token verification to the gateway via IPC (`verify_capability_token`) — it must never read secrets from `GATEWAY_SECURITY_DIR` or any other gateway-owned directory. Cloud deployments issue guardian-bound JWTs via the gateway's WorkOS-backed flow.
 
@@ -81,7 +85,7 @@ On macOS-originated turns, the CDP factory (`tools/browser/cdp-client/factory.ts
 
 | Priority | Backend                    | Condition                                                                                                                                                                                                | Transport                                                                                              |
 | -------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| 1        | **Extension / host proxy** | `hostBrowserProxy` present AND `isAvailable()` returns `true`. On macOS, the proxy is always provisioned. On other interfaces, requires an active transport (WS registry or SSE chrome-extension client) | WS via `ChromeExtensionRegistry` (self-hosted), SSE via `assistantEventHub` (cloud extension or macOS) |
+| 1        | **Extension / host proxy** | `hostBrowserProxy` present AND `isAvailable()` returns `true`. On macOS, the proxy is always provisioned. On other interfaces, requires an active hub subscriber with `host_browser` capability | WS via `ChromeExtensionRegistry` (self-hosted), SSE via `assistantEventHub` with `targetCapability: "host_browser"` (cloud extension or macOS) |
 | 2        | **cdp-inspect**            | (a) `hostBrowser.cdpInspect.enabled` is `true` in config, OR (b) `transportInterface === "macos"` AND `desktopAuto.enabled` is `true` (default) AND the cooldown from a prior failure is not active      | Direct CDP WebSocket to `localhost:9222`                                                               |
 | 3        | **Local**                  | Always present as the final fallback                                                                                                                                                                     | In-process Playwright CDP via `browserManager`                                                         |
 
@@ -89,9 +93,9 @@ On macOS-originated turns, the CDP factory (`tools/browser/cdp-client/factory.ts
 
 The "extension" backend label is a misnomer inherited from the original Phase 2 design where only the Chrome Extension provided host-browser access. In the current architecture, two transports can power this backend:
 
-- **Extension WebSocket** (self-hosted): When the `ChromeExtensionRegistry` has an active entry for the guardian, `resolveHostBrowserSender()` returns a registry-routed sender. `host_browser_request` frames travel over the `/v1/browser-relay` WebSocket to the Chrome extension, which executes CDP commands via `chrome.debugger`.
-- **Extension SSE** (cloud/platform): When no WebSocket entry exists but a `chrome-extension` client is registered in the `ClientRegistry` (connected via `GET /v1/events`), `resolveHostBrowserSender()` returns the `onEvent` SSE hub sender and sets `hasSseExtension = true`. `host_browser_request` frames travel through `assistantEventHub` to the extension's SSE stream. The extension POSTs results back to `/v1/host-browser-result`. This path is used for any `canServiceSseBrowser()` interface (`web`, `chrome-extension`, `macos`).
-- **macOS SSE bridge**: When the macOS desktop client is connected but no extension is present, `resolveHostBrowserSender()` returns the `onEvent` SSE hub sender. `host_browser_request` frames travel through `assistantEventHub` to the desktop client's SSE connection. The desktop client executes CDP commands against the local Chrome and POSTs results back to `/v1/host-browser-result`.
+- **Extension WebSocket** (self-hosted): When the `ChromeExtensionRegistry` has an active entry for the guardian, the registry-routed sender delivers frames over the `/v1/browser-relay` WebSocket to the Chrome extension, which executes CDP commands via `chrome.debugger`.
+- **Extension SSE** (cloud/platform): When no WebSocket entry exists, `HostBrowserProxy.send()` publishes to `assistantEventHub` with `targetCapability: "host_browser"`. The hub delivers the event to the chrome-extension subscriber (which registered with that capability via SSE). The extension POSTs results back to `/v1/host-browser-result`. This path is used for any `canServiceSseBrowser()` interface (`web`, `chrome-extension`, `macos`).
+- **macOS SSE bridge**: When the macOS desktop client is connected but no extension is present, the same hub publish with `targetCapability: "host_browser"` delivers to the macOS subscriber (which has all host-proxy capabilities). The desktop client executes CDP commands against the local Chrome and POSTs results back to `/v1/host-browser-result`.
 
 All three transports use the same `HostBrowserProxy` → `ExtensionCdpClient` pipeline. The `browser_status` output distinguishes the transport via the `details.transport` field: `"extension-ws"` or `"macos-sse"`.
 

package/src/runtime/__tests__/agent-wake.test.ts

@@ -402,6 +402,95 @@ describe("wakeAgentForOpportunity", () => {
     expect(processing).toBe(false);
   });
 
+  test("applies caller-supplied trustContext to the target before the agent loop runs", async () => {
+    // Background system jobs (memory consolidation, update-bulletin) need
+    // guardian trust to clear the side-effect approval gate. The wake must
+    // call setTrustContext BEFORE agentLoop.run so the per-turn snapshot
+    // captures the elevated trust.
+    const trustCalls: Array<{ ctx: unknown; before: number }> = [];
+    const runCalls: number[] = [];
+    let callOrder = 0;
+
+    const history: Message[] = [];
+    let processing = false;
+    const target: WakeTarget = {
+      conversationId: "conv-trust",
+      agentLoop: {
+        run: async (input) => {
+          runCalls.push(callOrder++);
+          return [...input];
+        },
+      },
+      getMessages: () => history,
+      pushMessage: () => {},
+      emitAgentEvent: () => {},
+      isProcessing: () => processing,
+      markProcessing: (on) => {
+        processing = on;
+      },
+      persistTailMessage: async () => {},
+      setTrustContext: (ctx) => {
+        trustCalls.push({ ctx, before: callOrder++ });
+      },
+    };
+
+    await wakeAgentForOpportunity(
+      {
+        conversationId: "conv-trust",
+        hint: "consolidate memory",
+        source: "memory_v2_consolidation",
+        trustContext: { sourceChannel: "vellum", trustClass: "guardian" },
+      },
+      { resolveTarget: async () => target },
+    );
+
+    expect(trustCalls).toHaveLength(1);
+    expect(trustCalls[0]!.ctx).toEqual({
+      sourceChannel: "vellum",
+      trustClass: "guardian",
+    });
+    // setTrustContext fired strictly before agentLoop.run.
+    expect(runCalls).toHaveLength(1);
+    expect(trustCalls[0]!.before).toBeLessThan(runCalls[0]!);
+  });
+
+  test("does not call setTrustContext when no trustContext is supplied", async () => {
+    const trustCalls: unknown[] = [];
+    const history: Message[] = [];
+    let processing = false;
+    const target: WakeTarget = {
+      conversationId: "conv-no-trust",
+      agentLoop: {
+        run: async (input) => [...input],
+      },
+      getMessages: () => history,
+      pushMessage: () => {},
+      emitAgentEvent: () => {},
+      isProcessing: () => processing,
+      markProcessing: (on) => {
+        processing = on;
+      },
+      persistTailMessage: async () => {},
+      setTrustContext: (ctx) => {
+        trustCalls.push(ctx);
+      },
+    };
+
+    await wakeAgentForOpportunity(
+      {
+        conversationId: "conv-no-trust",
+        hint: "x",
+        source: "t",
+      },
+      { resolveTarget: async () => target },
+    );
+
+    // Inbound-message conversations populate trust via processMessage().
+    // Without an explicit opt-in from the caller, the wake must not
+    // overwrite whatever the conversation already holds.
+    expect(trustCalls).toHaveLength(0);
+  });
+
   test("two concurrent wakes on the same conversation are serialized", async () => {
     // Build a target whose agentLoop.run resolves only when we signal.
     const gate1 = Promise.withResolvers<void>();

package/src/runtime/agent-wake.ts

@@ -41,6 +41,9 @@
  */
 
 import type { AgentEvent, AgentLoop } from "../agent/loop.js";
+import { resolveEffectiveContextWindow } from "../config/llm-context-resolution.js";
+import { getConfig } from "../config/loader.js";
+import type { TrustContext } from "../daemon/trust-context.js";
 import { getConversationOverrideProfile } from "../memory/conversation-crud.js";
 import type { Message } from "../providers/types.js";
 import { getLogger } from "../util/logger.js";
@@ -137,12 +140,30 @@ export interface WakeTarget {
    * typically omit it.
    */
   onWakeProducedOutput?(source: string, hint: string, surfaceId: string): void;
+  /**
+   * Apply a trust context to the underlying conversation before the agent
+   * loop runs. Internal background jobs (memory consolidation, update
+   * bulletin) use this to declare guardian trust so side-effect tools
+   * (file_edit, file_write, bash) clear the approval gate. Inbound message
+   * conversations populate trust via `processMessage()` and don't pass
+   * `trustContext` through the wake.
+   */
+  setTrustContext?(ctx: TrustContext): void;
 }
 
 export interface WakeOptions {
   conversationId: string;
   hint: string;
   source: string;
+  /**
+   * Optional trust context to apply to the conversation before the agent
+   * loop runs. Required for internal background jobs that need elevated
+   * trust to invoke side-effect tools — without it the loop falls back to
+   * `trustClass: "unknown"` and side-effect tools are blocked. Caller
+   * should pass `{ sourceChannel: "vellum", trustClass: "guardian" }` for
+   * assistant-self-maintenance jobs.
+   */
+  trustContext?: TrustContext;
 }
 
 /**
@@ -370,6 +391,13 @@ export async function wakeAgentForOpportunity(
       return { invoked: false, producedToolCalls: false, reason: "timeout" };
     }
 
+    // Apply caller-supplied trust before the agent loop reads its per-turn
+    // snapshot. Background jobs without an inbound message use this to
+    // declare guardian trust so side-effect tools clear the approval gate.
+    if (opts.trustContext && target.setTrustContext) {
+      target.setTrustContext(opts.trustContext);
+    }
+
     const baseline = target.getMessages();
     const hintContent = `[opportunity:${source}] ${hint}`;
     // Sandwich the hint as an assistant message between two hardcoded
@@ -409,10 +437,18 @@ export async function wakeAgentForOpportunity(
     // Honor the conversation's pinned inference-profile override (if any).
     // Without this, scheduled-task wakes and other opportunity wakes bypass
     // `runAgentLoopImpl` entirely and execute under workspace defaults,
-    // silently violating the user's pinned preference. Read before
-    // `markProcessing(true)` so a thrown DB read can't strand the
+    // silently violating the user's pinned preference. Resolve the effective
+    // context budget here as well because wakes bypass the normal user-turn
+    // path that computes it for tool-result truncation. Read before
+    // `markProcessing(true)` so a thrown DB/config read can't strand the
     // processing flag.
     const overrideProfile = getConversationOverrideProfile(conversationId);
+    const config = getConfig();
+    const effectiveContextWindow = resolveEffectiveContextWindow({
+      llm: config.llm,
+      callSite: "mainAgent",
+      overrideProfile,
+    });
 
     // Mark processing for the duration of the run so a concurrent user
     // send is queued by `enqueueMessage()` rather than spawning a second
@@ -442,6 +478,7 @@ export async function wakeAgentForOpportunity(
           "mainAgent",
           undefined, // turnContext
           overrideProfile,
+          effectiveContextWindow.maxInputTokens,
         );
       } catch (err) {
         // Capture the error for post-finally logging, then short-circuit