@vellumai/assistant 0.5.3 → 0.5.5

package/src/security/ces-credential-client.ts

@@ -0,0 +1,173 @@
+/**
+ * HTTP client for CES credential CRUD endpoints.
+ *
+ * In containerized mode the assistant cannot access `keys.enc` directly.
+ * Instead, the CES sidecar exposes credential management over HTTP and the
+ * assistant talks to it via this client.
+ *
+ * Endpoints (served by `credential-executor/src/http/credential-routes.ts`):
+ * - GET  /v1/credentials           → { accounts: string[] }
+ * - GET  /v1/credentials/:account  → { account, value } | 404
+ * - POST /v1/credentials/:account  → { ok: true, account }
+ * - DELETE /v1/credentials/:account → { ok: true, account } | 404 | 500
+ *
+ * Auth: Bearer token from `CES_SERVICE_TOKEN` env var.
+ * Base URL: `CES_CREDENTIAL_URL` env var (e.g. `http://ces-container:8090`).
+ */
+
+import { getLogger } from "../util/logger.js";
+import type { CredentialBackend, DeleteResult } from "./credential-backend.js";
+
+const log = getLogger("ces-credential-client");
+
+const REQUEST_TIMEOUT_MS = 10_000;
+
+// ---------------------------------------------------------------------------
+// Env helpers
+// ---------------------------------------------------------------------------
+
+function getBaseUrl(): string | undefined {
+  return process.env.CES_CREDENTIAL_URL;
+}
+
+function getServiceToken(): string | undefined {
+  return process.env.CES_SERVICE_TOKEN;
+}
+
+// ---------------------------------------------------------------------------
+// Internal fetch wrapper
+// ---------------------------------------------------------------------------
+
+async function cesRequest(
+  method: string,
+  path: string,
+  body?: unknown,
+): Promise<Response | null> {
+  const baseUrl = getBaseUrl();
+  const token = getServiceToken();
+  if (!baseUrl || !token) return null;
+
+  const url = `${baseUrl.replace(/\/+$/, "")}${path}`;
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${token}`,
+    "Content-Type": "application/json",
+  };
+
+  try {
+    return await fetch(url, {
+      method,
+      headers,
+      ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+      signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+  } catch (err) {
+    log.warn({ err, method, path }, "CES credential request failed");
+    return null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// CesCredentialBackend
+// ---------------------------------------------------------------------------
+
+export class CesCredentialBackend implements CredentialBackend {
+  readonly name = "ces-http";
+
+  isAvailable(): boolean {
+    return !!getBaseUrl() && !!getServiceToken();
+  }
+
+  async get(account: string): Promise<string | undefined> {
+    try {
+      const res = await cesRequest(
+        "GET",
+        `/v1/credentials/${encodeURIComponent(account)}`,
+      );
+      if (!res) return undefined;
+      if (res.status === 404) return undefined;
+      if (!res.ok) {
+        log.warn(
+          { account, status: res.status },
+          "CES credential get returned non-OK status",
+        );
+        return undefined;
+      }
+      const data = (await res.json()) as { value?: string };
+      return data.value;
+    } catch (err) {
+      log.warn({ err, account }, "CES credential get threw unexpectedly");
+      return undefined;
+    }
+  }
+
+  async set(account: string, value: string): Promise<boolean> {
+    try {
+      const res = await cesRequest(
+        "POST",
+        `/v1/credentials/${encodeURIComponent(account)}`,
+        { value },
+      );
+      if (!res) return false;
+      if (!res.ok) {
+        log.warn(
+          { account, status: res.status },
+          "CES credential set returned non-OK status",
+        );
+        return false;
+      }
+      return true;
+    } catch (err) {
+      log.warn({ err, account }, "CES credential set threw unexpectedly");
+      return false;
+    }
+  }
+
+  async delete(account: string): Promise<DeleteResult> {
+    try {
+      const res = await cesRequest(
+        "DELETE",
+        `/v1/credentials/${encodeURIComponent(account)}`,
+      );
+      if (!res) return "error";
+      if (res.status === 404) return "not-found";
+      if (!res.ok) {
+        log.warn(
+          { account, status: res.status },
+          "CES credential delete returned non-OK status",
+        );
+        return "error";
+      }
+      return "deleted";
+    } catch (err) {
+      log.warn({ err, account }, "CES credential delete threw unexpectedly");
+      return "error";
+    }
+  }
+
+  async list(): Promise<string[]> {
+    try {
+      const res = await cesRequest("GET", "/v1/credentials");
+      if (!res) return [];
+      if (!res.ok) {
+        log.warn(
+          { status: res.status },
+          "CES credential list returned non-OK status",
+        );
+        return [];
+      }
+      const data = (await res.json()) as { accounts?: string[] };
+      return data.accounts ?? [];
+    } catch (err) {
+      log.warn({ err }, "CES credential list threw unexpectedly");
+      return [];
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+export function createCesCredentialBackend(): CesCredentialBackend {
+  return new CesCredentialBackend();
+}

package/src/security/secure-keys.ts

@@ -3,6 +3,7 @@
  * adapters.
  *
  * Backend selection (`resolveBackend`) is the single decision point:
+ *   - Containerized (IS_CONTAINERIZED + CES_CREDENTIAL_URL set): CES HTTP client.
  *   - Production (VELLUM_DEV unset or "0"): keychain backend when available.
  *   - Dev mode (VELLUM_DEV=1): encrypted file store always.
  *
@@ -16,7 +17,10 @@ import type {
   SecureKeyDeleteResult,
 } from "@vellumai/credential-storage";
 
+import providerEnvVarsRegistry from "../../../meta/provider-env-vars.json" with { type: "json" };
+import { getIsContainerized } from "../config/env-registry.js";
 import { getLogger } from "../util/logger.js";
+import { createCesCredentialBackend } from "./ces-credential-client.js";
 import type { CredentialBackend, DeleteResult } from "./credential-backend.js";
 import {
   createEncryptedStoreBackend,
@@ -50,18 +54,39 @@ function getEncryptedStoreBackend(): CredentialBackend {
 
 /**
  * Resolve the primary credential backend for this process.
- * Production (VELLUM_DEV unset or "0") uses keychain when available.
- * Dev mode (VELLUM_DEV=1) always uses the encrypted file store.
+ *
+ * Priority:
+ *   1. Containerized + CES_CREDENTIAL_URL → CES HTTP client (skip keychain
+ *      and encrypted store entirely — the sidecar owns credential storage).
+ *   2. Production (VELLUM_DEV unset or "0") → keychain when available.
+ *   3. Dev mode (VELLUM_DEV=1) → encrypted file store always.
  *
  * Once resolved, the backend does not change during the process lifetime.
  * Call `_resetBackend()` in tests to clear the cached resolution.
  */
 function resolveBackend(): CredentialBackend {
   if (!_resolvedBackend) {
-    if (process.env.VELLUM_DEV !== "1" && getKeychainBackend().isAvailable()) {
-      _resolvedBackend = getKeychainBackend();
-    } else {
-      _resolvedBackend = getEncryptedStoreBackend();
+    if (getIsContainerized() && process.env.CES_CREDENTIAL_URL) {
+      const ces = createCesCredentialBackend();
+      if (ces.isAvailable()) {
+        _resolvedBackend = ces;
+      } else {
+        log.warn(
+          "CES_CREDENTIAL_URL is set but CES backend is not available — " +
+            "falling back to local credential store",
+        );
+      }
+    }
+
+    if (!_resolvedBackend) {
+      if (
+        process.env.VELLUM_DEV !== "1" &&
+        getKeychainBackend().isAvailable()
+      ) {
+        _resolvedBackend = getKeychainBackend();
+      } else {
+        _resolvedBackend = getEncryptedStoreBackend();
+      }
     }
   }
   return _resolvedBackend;
@@ -70,6 +95,8 @@ function resolveBackend(): CredentialBackend {
 /**
  * List all account names across both backends (async).
  *
+ * In CES mode, only the CES backend is queried — there are no local stores.
+ *
  * When the primary backend is the keychain, this merges keys from the keychain
  * and the encrypted store (for legacy keys that haven't been migrated). The
  * result is deduplicated. When the primary backend is already the encrypted
@@ -79,6 +106,9 @@ export async function listSecureKeysAsync(): Promise<string[]> {
   const backend = resolveBackend();
   const primaryKeys = await backend.list();
 
+  // CES mode — the sidecar is the single source of truth, no local merge.
+  if (backend.name === "ces-http") return primaryKeys;
+
   // If primary backend is NOT the encrypted store, also check
   // the encrypted store for legacy keys that haven't been migrated.
   if (backend !== getEncryptedStoreBackend()) {
@@ -96,8 +126,10 @@ export async function listSecureKeysAsync(): Promise<string[]> {
 
 /**
  * Retrieve a secret from secure storage. Reads from the primary backend
- * first. If the primary backend is the keychain, falls back to the encrypted
- * store for legacy keys that haven't been migrated.
+ * first. In CES mode, the sidecar is the single source of truth — no
+ * local fallback. In local mode, if the primary backend is the keychain,
+ * falls back to the encrypted store for legacy keys that haven't been
+ * migrated.
  */
 export async function getSecureKeyAsync(
   account: string,
@@ -106,6 +138,9 @@ export async function getSecureKeyAsync(
   const result = await backend.get(account);
   if (result != null) return result;
 
+  // CES mode — no local fallback.
+  if (backend.name === "ces-http") return undefined;
+
   // Legacy fallback: if primary backend is NOT the encrypted store,
   // check the encrypted store for keys that haven't been migrated.
   if (backend !== getEncryptedStoreBackend()) {
@@ -135,13 +170,25 @@ export async function setSecureKeyAsync(
 }
 
 /**
- * Delete a secret from secure storage. Always attempts deletion on both
- * the keychain backend (if available) and the encrypted store backend,
- * regardless of routing mode. This cleans up legacy data from both stores.
+ * Delete a secret from secure storage.
+ *
+ * In containerized mode with CES, deletion is routed exclusively through the
+ * CES backend — there are no local stores to clean up.
+ *
+ * In local mode, always attempts deletion on both the keychain backend (if
+ * available) and the encrypted store backend, regardless of routing mode.
+ * This cleans up legacy data from both stores.
  */
 export async function deleteSecureKeyAsync(
   account: string,
 ): Promise<DeleteResult> {
+  const backend = resolveBackend();
+
+  // In CES mode, the sidecar is the only store — no local cleanup needed.
+  if (backend.name === "ces-http") {
+    return backend.delete(account);
+  }
+
   const keychain = getKeychainBackend();
   const enc = getEncryptedStoreBackend();
 
@@ -164,18 +211,14 @@ export async function deleteSecureKeyAsync(
 // ---------------------------------------------------------------------------
 
 /**
- * Env var names keyed by provider. The convention is `<PROVIDER>_API_KEY`.
- * Ollama is intentionally omitted — it doesn't require an API key.
+ * Env var names keyed by provider. Loaded from the shared registry at
+ * `meta/provider-env-vars.json` — the single source of truth also consumed
+ * by the CLI and the macOS client.
+ * Ollama is intentionally omitted from the registry — it doesn't require
+ * an API key.
  */
-const PROVIDER_ENV_VARS: Record<string, string> = {
-  anthropic: "ANTHROPIC_API_KEY",
-  openai: "OPENAI_API_KEY",
-  gemini: "GEMINI_API_KEY",
-  fireworks: "FIREWORKS_API_KEY",
-  openrouter: "OPENROUTER_API_KEY",
-  brave: "BRAVE_API_KEY",
-  perplexity: "PERPLEXITY_API_KEY",
-};
+const PROVIDER_ENV_VARS: Record<string, string> =
+  providerEnvVarsRegistry.providers;
 
 /**
  * Retrieve a provider API key, checking secure storage first and falling

package/src/signals/bash.ts

@@ -20,6 +20,7 @@ import { spawn } from "node:child_process";
 import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { getIsContainerized } from "../config/env-registry.js";
 import { getLogger } from "../util/logger.js";
 import { getSignalsDir, getWorkspaceDir } from "../util/platform.js";
 
@@ -65,6 +66,8 @@ function writeResult(requestId: string, result: BashSignalResult): void {
  * when a matching signal file is created or modified.
  */
 export function handleBashSignal(filename: string): void {
+  if (getIsContainerized()) return;
+
   if (!isDebugMode()) {
     log.warn(
       { filename },

package/src/signals/cancel.ts

@@ -13,6 +13,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { getIsContainerized } from "../config/env-registry.js";
 import { getLogger } from "../util/logger.js";
 import { getSignalsDir } from "../util/platform.js";
 
@@ -39,6 +40,8 @@ export function registerCancelCallback(cb: CancelCallback): void {
  * Called by ConfigWatcher when the signal file is written or modified.
  */
 export function handleCancelSignal(): void {
+  if (getIsContainerized()) return;
+
   try {
     const content = readFileSync(join(getSignalsDir(), "cancel"), "utf-8");
     const parsed = JSON.parse(content) as { conversationId?: string };

package/src/signals/confirm.ts

@@ -10,6 +10,7 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { getIsContainerized } from "../config/env-registry.js";
 import type { UserDecision } from "../permissions/types.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
 import { getLogger } from "../util/logger.js";
@@ -37,6 +38,8 @@ function isUserDecision(value: string): value is UserDecision {
  * Called by ConfigWatcher when the signal file is written or modified.
  */
 export function handleConfirmationSignal(): void {
+  if (getIsContainerized()) return;
+
   try {
     const content = readFileSync(join(getSignalsDir(), "confirm"), "utf-8");
     const parsed = JSON.parse(content) as {

package/src/signals/conversation-undo.ts

@@ -16,6 +16,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { getIsContainerized } from "../config/env-registry.js";
 import { getLogger } from "../util/logger.js";
 import { getSignalsDir } from "../util/platform.js";
 
@@ -46,6 +47,8 @@ export function registerConversationUndoCallback(cb: UndoCallback): void {
  * file is written.
  */
 export async function handleConversationUndoSignal(): Promise<void> {
+  if (getIsContainerized()) return;
+
   const resultPath = join(getSignalsDir(), "conversation-undo.result");
 
   const writeResult = (

package/src/signals/event-stream.ts

@@ -24,6 +24,7 @@ import {
 } from "node:fs";
 import { join } from "node:path";
 
+import { getIsContainerized } from "../config/env-registry.js";
 import type { AssistantEvent } from "../runtime/assistant-event.js";
 import { getSignalsDir } from "../util/platform.js";
 
@@ -86,6 +87,8 @@ export function appendEventToStream(
   conversationId: string,
   event: AssistantEvent,
 ): void {
+  if (getIsContainerized()) return;
+
   const dirs = getSubscriberDirs(conversationId);
   if (dirs.length === 0) return;
 
@@ -130,6 +133,10 @@ export function watchEventStream(
   conversationId: string,
   callback: (event: AssistantEvent) => void,
 ): EventStreamWatcher {
+  if (getIsContainerized()) {
+    return { dispose() {} };
+  }
+
   const parentDir = eventsDir();
   mkdirSync(parentDir, { recursive: true });
   const subDir = join(parentDir, `${conversationId}.${process.pid}`);

package/src/signals/shotgun.ts

@@ -15,6 +15,7 @@ import crypto from "node:crypto";
 import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { getIsContainerized } from "../config/env-registry.js";
 import {
   fireWatchCompletionNotifier,
   fireWatchStartNotifier,
@@ -54,6 +55,8 @@ function writeResult(requestId: string, result: ShotgunResult): void {
  * when a matching signal file is created or modified.
  */
 export function handleShotgunSignal(filename: string): void {
+  if (getIsContainerized()) return;
+
   const signalPath = join(getSignalsDir(), filename);
   let raw: string;
   try {

package/src/signals/trust-rule.ts

@@ -12,6 +12,7 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 
+import { getIsContainerized } from "../config/env-registry.js";
 import { addRule } from "../permissions/trust-store.js";
 import * as pendingInteractions from "../runtime/pending-interactions.js";
 import { getTool } from "../tools/registry.js";
@@ -27,6 +28,8 @@ const VALID_TRUST_DECISIONS: ReadonlySet<string> = new Set(["allow", "deny"]);
  * Called by ConfigWatcher when the signal file is written or modified.
  */
 export function handleTrustRuleSignal(): void {
+  if (getIsContainerized()) return;
+
   const resultPath = join(getSignalsDir(), "trust-rule.result");
 
   const writeError = (requestId: string | undefined, error: string): void => {

package/src/telemetry/usage-telemetry-reporter.test.ts

@@ -41,14 +41,12 @@ mock.module("../memory/turn-events-store.js", () => ({
   queryUnreportedTurnEvents: mockQueryUnreportedTurnEvents,
 }));
 
-const mockResolveManagedProxyContext = mock(async () => ({
-  enabled: false,
-  platformBaseUrl: "",
-  assistantApiKey: "",
-}));
+let mockPlatformClient: Record<string, unknown> | null = null;
 
-mock.module("../providers/managed-proxy/context.js", () => ({
-  resolveManagedProxyContext: mockResolveManagedProxyContext,
+mock.module("../platform/client.js", () => ({
+  VellumPlatformClient: {
+    create: async () => mockPlatformClient,
+  },
 }));
 
 const mockGetTelemetryPlatformUrl = mock(() => "https://platform.vellum.ai");
@@ -142,7 +140,7 @@ beforeEach(() => {
   mockQueryUnreportedUsageEvents.mockReset();
   mockQueryUnreportedTurnEvents.mockReset();
   mockQueryUnreportedTurnEvents.mockReturnValue([]);
-  mockResolveManagedProxyContext.mockReset();
+  mockPlatformClient = null;
   mockGetTelemetryPlatformUrl.mockReset();
   mockGetTelemetryAppToken.mockReset();
   mockGetDeviceId.mockReset();
@@ -156,11 +154,6 @@ beforeEach(() => {
 
   // Defaults
   mockGetMemoryCheckpoint.mockReturnValue(null);
-  mockResolveManagedProxyContext.mockResolvedValue({
-    enabled: false,
-    platformBaseUrl: "",
-    assistantApiKey: "",
-  });
   mockGetTelemetryPlatformUrl.mockReturnValue("https://platform.vellum.ai");
   mockGetTelemetryAppToken.mockReturnValue("default-test-token");
 
@@ -179,37 +172,31 @@ afterEach(() => {
 // ---------------------------------------------------------------------------
 
 describe("UsageTelemetryReporter", () => {
-  test("authenticated flush uses Api-Key header and proxy URL", async () => {
-    mockResolveManagedProxyContext.mockResolvedValue({
-      enabled: true,
-      platformBaseUrl: "https://test.vellum.ai",
-      assistantApiKey: "test-key",
+  test("authenticated flush uses client.fetch with platform path", async () => {
+    const clientFetchMock = mock(async (_path: string, _init?: RequestInit) => {
+      return new Response('{"accepted":2}', { status: 200 });
     });
+    mockPlatformClient = {
+      baseUrl: "https://test.vellum.ai",
+      assistantApiKey: "test-key",
+      platformAssistantId: "asst-123",
+      fetch: clientFetchMock,
+    };
     const events = [makeUsageEvent(), makeUsageEvent()];
     mockQueryUnreportedUsageEvents.mockReturnValue(events);
-    mockFetch.mockImplementation(() =>
-      Promise.resolve(
-        new Response(`{"accepted":${events.length}}`, { status: 200 }),
-      ),
-    );
 
     const reporter = new UsageTelemetryReporter();
     await reporter.flush();
 
-    expect(mockFetch).toHaveBeenCalledTimes(1);
-    const [url, opts] = mockFetch.mock.calls[0] as [string, RequestInit];
-    expect(url).toBe("https://test.vellum.ai/v1/telemetry/ingest/");
-    expect((opts.headers as Record<string, string>)["Authorization"]).toBe(
-      "Api-Key test-key",
-    );
+    expect(clientFetchMock).toHaveBeenCalledTimes(1);
+    const [path] = clientFetchMock.mock.calls[0] as [string, RequestInit];
+    expect(path).toBe("/v1/telemetry/ingest/");
+    // globalThis.fetch should NOT have been called directly
+    expect(mockFetch).not.toHaveBeenCalled();
   });
 
   test("anonymous flush uses X-Telemetry-Token and default URL", async () => {
-    mockResolveManagedProxyContext.mockResolvedValue({
-      enabled: false,
-      platformBaseUrl: "",
-      assistantApiKey: "",
-    });
+    mockPlatformClient = null;
     mockGetTelemetryPlatformUrl.mockReturnValue("https://platform.test.ai");
     mockGetTelemetryAppToken.mockReturnValue("anon-token");
 
@@ -375,9 +362,9 @@ describe("UsageTelemetryReporter", () => {
       (mockFetch.mock.calls[0] as [string, RequestInit])[1].body as string,
     );
 
-    // Top-level: installation_id, app_version, and events array (no turn_events key)
+    // Top-level: installation_id, assistant_version, and events array (no turn_events key)
     expect(body.installation_id).toBe("test-device-id");
-    expect(body.app_version).toBe("1.2.3-test");
+    expect(body.assistant_version).toBe("1.2.3-test");
     expect(Array.isArray(body.events)).toBe(true);
     expect(body.events.length).toBe(1);
     expect(body.turn_events).toBeUndefined();

package/src/telemetry/usage-telemetry-reporter.ts

@@ -22,7 +22,7 @@ import {
 import { queryUnreportedLifecycleEvents } from "../memory/lifecycle-events-store.js";
 import { queryUnreportedUsageEvents } from "../memory/llm-usage-store.js";
 import { queryUnreportedTurnEvents } from "../memory/turn-events-store.js";
-import { resolveManagedProxyContext } from "../providers/managed-proxy/context.js";
+import { VellumPlatformClient } from "../platform/client.js";
 import { DAEMON_INTERNAL_ASSISTANT_ID } from "../runtime/assistant-scope.js";
 import { getExternalAssistantId } from "../runtime/auth/external-assistant-id.js";
 import { getDeviceId } from "../util/device-id.js";
@@ -139,22 +139,11 @@ export class UsageTelemetryReporter {
         return;
 
       // Resolve auth context — skip flush when neither auth mode is viable
-      const proxyCtx = await resolveManagedProxyContext();
-      if (!proxyCtx.enabled && !getTelemetryAppToken()) {
+      const client = await VellumPlatformClient.create();
+      if (!client && !getTelemetryAppToken()) {
         return;
       }
 
-      let url: string;
-      let authHeaders: Record<string, string>;
-
-      if (proxyCtx.enabled) {
-        url = `${proxyCtx.platformBaseUrl}${TELEMETRY_PATH}`;
-        authHeaders = { Authorization: `Api-Key ${proxyCtx.assistantApiKey}` };
-      } else {
-        url = `${getTelemetryPlatformUrl()}${TELEMETRY_PATH}`;
-        authHeaders = { "X-Telemetry-Token": getTelemetryAppToken() };
-      }
-
       // Build payload
       const typedEvents: TelemetryEvent[] = [
         ...events.map(
@@ -193,28 +182,41 @@ export class UsageTelemetryReporter {
       const organizationId = getPlatformOrganizationId() || undefined;
       const userId = getPlatformUserId() || undefined;
       const payload = {
-        installation_id: getDeviceId(),
+        device_id: getDeviceId(),
         assistant_id: assistantId,
-        app_version: APP_VERSION,
+        assistant_version: APP_VERSION,
         ...(organizationId ? { organization_id: organizationId } : {}),
         ...(userId ? { user_id: userId } : {}),
         events: typedEvents,
       };
 
       // Send
-      const resp = await fetch(url, {
+      const fetchInit: RequestInit = {
         method: "POST",
         headers: {
           "Content-Type": "application/json",
-          ...authHeaders,
         },
         body: JSON.stringify(payload),
-      });
+      };
+
+      let resp: Response;
+      if (client) {
+        resp = await client.fetch(TELEMETRY_PATH, fetchInit);
+      } else {
+        const url = `${getTelemetryPlatformUrl()}${TELEMETRY_PATH}`;
+        resp = await fetch(url, {
+          ...fetchInit,
+          headers: {
+            "Content-Type": "application/json",
+            "X-Telemetry-Token": getTelemetryAppToken(),
+          },
+        });
+      }
 
       if (!resp.ok) {
         await resp.text(); // consume body to release connection
         log.warn(
-          { status: resp.status, url },
+          { status: resp.status },
           "Usage telemetry POST failed — will retry next cycle",
         );
         return;

package/src/tools/filesystem/edit.ts

@@ -38,8 +38,13 @@ class FileEditTool implements Tool {
             description:
               "Replace all occurrences of old_string instead of requiring a unique match (default: false)",
           },
+          activity: {
+            type: "string",
+            description:
+              "Brief non-technical explanation of what you are doing and why, shown to the user as a status update.",
+          },
         },
-        required: ["path", "old_string", "new_string"],
+        required: ["path", "old_string", "new_string", "activity"],
       },
     };
   }