@vellumai/assistant 0.12.1 → 0.12.2-staging.1

package/src/runtime/routes/acp-routes.ts

@@ -24,8 +24,11 @@ import {
   AcpResumeError,
   AcpSessionNotFoundError,
 } from "../../acp/session-manager.js";
-import type { AcpSessionState } from "../../acp/types.js";
-import type { AssistantEvent } from "../../api/index.js";
+import { type AcpSessionState, isLiveAcpStatus } from "../../acp/types.js";
+import {
+  AcpSessionModelUpdateEventSchema,
+  type AssistantEvent,
+} from "../../api/index.js";
 import { getConfig } from "../../config/loader.js";
 import { createGuardianRequestForConfirmation } from "../../permissions/confirmation-guardian-request.js";
 import type { UserDecision } from "../../permissions/types.js";
@@ -53,6 +56,10 @@ const log = getLogger("acp-routes");
 const DEFAULT_SESSION_LIMIT = 50;
 const MAX_SESSION_LIMIT = 500;
 
+/** The option shape the `acp_session_model_update` event already publishes. */
+const acpModelOptionsSchema =
+  AcpSessionModelUpdateEventSchema.shape.availableModels;
+
 const sessionEntrySchema = z.object({
   id: z.string(),
   agentId: z.string(),
@@ -68,6 +75,15 @@ const sessionEntrySchema = z.object({
   /** Credential failure that ended the run, when one did. Drives the inline
    *  Connect card on reopen; cleared when a replacement token is stored. */
   authErrorCode: z.string().optional(),
+  /** Model a live session is running on. Absent for history rows, which have
+   *  no live process to ask. */
+  model: z.string().optional(),
+  /** Models a live session could run on. Absent for history rows. */
+  availableModels: acpModelOptionsSchema.optional(),
+  /** Scopes live model revisions to one assistant process. */
+  modelRevisionEpoch: z.string().uuid().optional(),
+  /** Orders live model state within `modelRevisionEpoch`. */
+  modelRevision: z.number().int().nonnegative().optional(),
   usedTokens: z.number().optional(),
   contextSize: z.number().optional(),
   costAmount: z.number().optional(),
@@ -214,17 +230,26 @@ async function spawnSession({ body, abortSignal }: RouteHandlerArgs) {
   const task = body?.task as string | undefined;
   const conversationId = body?.conversationId as string | undefined;
   const cwd = (body?.cwd as string | undefined) ?? process.cwd();
+  const model = body?.model ?? undefined;
 
   if (!agent || !task || !conversationId) {
     throw new BadRequestError("agent, task, and conversationId are required");
   }
+  if (model !== undefined && typeof model !== "string") {
+    throw new BadRequestError("model must be a string when provided");
+  }
 
   // High-risk approval gate. Block BEFORE any side effects — resolution can
   // trigger a `bun` global install (auto-install.ts) and `manager.spawn`
   // launches the host subprocess — so an unapproved request mutates nothing.
   const decision = await awaitRouteApproval({
     toolName: "acp_spawn",
-    input: { agent, task, cwd },
+    input: {
+      agent,
+      task,
+      cwd,
+      ...(model !== undefined ? { model } : {}),
+    },
     conversationId,
     signal: abortSignal,
   });
@@ -262,17 +287,33 @@ async function spawnSession({ body, abortSignal }: RouteHandlerArgs) {
   );
 
   const manager = getAcpSessionManager();
-  const { acpSessionId, protocolSessionId } = await manager.spawn(
+  const {
+    acpSessionId,
+    protocolSessionId,
+    requestedModel,
+    effectiveModel,
+    modelWarning,
+  } = await manager.spawn(
     agent,
     agentConfig,
     task,
     cwd,
     conversationId,
     broadcastMessage,
+    { model },
   );
 
   log.info({ acpSessionId, protocolSessionId, agent }, "ACP spawn succeeded");
-  return { acpSessionId, protocolSessionId, agent };
+  // A refused model is a warning, not a failed spawn: the session is live on
+  // the agent's own model.
+  return {
+    acpSessionId,
+    protocolSessionId,
+    agent,
+    requestedModel: requestedModel ?? null,
+    effectiveModel: effectiveModel ?? null,
+    ...(modelWarning ? { modelWarning } : {}),
+  };
 }
 
 async function steerSession({ pathParams, body }: RouteHandlerArgs) {
@@ -588,10 +629,7 @@ function deleteSession({ pathParams }: RouteHandlerArgs) {
 
   try {
     const state = manager.getStatus(id);
-    if (
-      !Array.isArray(state) &&
-      (state.status === "running" || state.status === "initializing")
-    ) {
+    if (!Array.isArray(state) && isLiveAcpStatus(state.status)) {
       throw new ConflictError(
         `ACP session "${id}" is still ${state.status}. Cancel or close it before deleting.`,
       );
@@ -640,11 +678,32 @@ export const ROUTES: RouteDefinition[] = [
       task: z.string().describe("Task description"),
       conversationId: z.string(),
       cwd: z.string().describe("Working directory").optional(),
+      model: z
+        .string()
+        .optional()
+        .describe("Optional model id or alias to request for the session."),
     }),
     responseBody: z.object({
       acpSessionId: z.string(),
       protocolSessionId: z.string(),
       agent: z.string(),
+      requestedModel: z
+        .string()
+        .nullable()
+        .describe("The model explicitly requested for this spawn, if any."),
+      effectiveModel: z
+        .string()
+        .nullable()
+        .describe(
+          "The top-level session model reported by the ACP adapter, if any.",
+        ),
+      modelWarning: z
+        .string()
+        .optional()
+        .describe(
+          "Why the requested model was not applied. The session is running " +
+            "on the agent's own model.",
+        ),
     }),
   },
   {
@@ -852,6 +911,10 @@ function listMergedSessions(opts: { limit: number; conversationId?: string }): {
       parentToolUseId: s.parentToolUseId,
       authErrorCode: s.authErrorCode,
       authErrorCredential: s.authErrorCredential,
+      model: s.model,
+      availableModels: s.availableModels,
+      modelRevisionEpoch: s.modelRevisionEpoch,
+      modelRevision: s.modelRevision,
       usedTokens: s.latestUsage?.usedTokens,
       contextSize: s.latestUsage?.contextSize,
       costAmount: s.latestUsage?.costAmount,

package/src/runtime/routes/app-management-routes.ts

@@ -51,6 +51,7 @@ import { compileApp, runCompile } from "../../bundler/app-compiler.js";
 import { scanBundle } from "../../bundler/bundle-scanner.js";
 import type { SignatureJson } from "../../bundler/bundle-signer.js";
 import { verifyBundleSignature } from "../../bundler/signature-verifier.js";
+import { notifyAppSurfacesChanged } from "../../daemon/app-change-notify.js";
 import { compareSemver } from "../../daemon/handlers/shared.js";
 import { computeContentId } from "../../util/content-id.js";
 import { getLogger } from "../../util/logger.js";
@@ -128,6 +129,17 @@ const appListItemSchema = z.object({
 
 type AppListItem = z.infer<typeof appListItemSchema>;
 
+const compileDiagnosticSchema = z.object({
+  text: z.string(),
+  location: z
+    .object({
+      file: z.string(),
+      line: z.number(),
+      column: z.number(),
+    })
+    .optional(),
+});
+
 /**
  * The pin route's body. `RouteDefinition.requestBody` is a codegen signal and
  * does not validate, so the handler parses against this too; declaring it once
@@ -896,6 +908,44 @@ async function handleOpenApp({ pathParams }: RouteHandlerArgs) {
   return { ...result, html };
 }
 
+/**
+ * Compile an app's source into dist/ and refresh open surfaces.
+ * Runs in the assistant process so open surfaces, client broadcasts, and
+ * published-app redeploy see the new build. Workspace and plugin apps both
+ * compile in place so local plugin edits can be rebuilt without waiting for
+ * the plugin source watcher.
+ */
+async function handleRefreshApp({ pathParams }: RouteHandlerArgs) {
+  const appId = pathParams?.id;
+  if (!appId) {
+    throw new BadRequestError("App id is required.");
+  }
+
+  const source = resolveAppSource(appId);
+  if (!source) {
+    throw new NotFoundError(
+      `App "${appId}" not found. Run 'assistant apps list' to see available apps.`,
+    );
+  }
+
+  const compileResult = await compileApp(source.sourceDir);
+  notifyAppSurfacesChanged(source.id, { fileChange: true });
+
+  return {
+    ok: true as const,
+    appId: source.id,
+    name: source.name,
+    compiled: compileResult.ok,
+    compile_duration_ms: compileResult.durationMs,
+    ...(compileResult.ok
+      ? {}
+      : {
+          compile_errors: compileResult.errors,
+          compile_warnings: compileResult.warnings,
+        }),
+  };
+}
+
 /**
  * Reject a mutation targeting a plugin-bundled app. Plugin apps are owned by
  * their plugin and are read-only over this surface — their source is not
@@ -1253,6 +1303,29 @@ export const ROUTES: RouteDefinition[] = [
       origin: z.string(),
     }),
   },
+  {
+    operationId: "apps_refresh",
+    endpoint: "apps/:id/refresh",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    handler: handleRefreshApp,
+    summary: "Compile an app",
+    description:
+      "Compile workspace or plugin app source into dist/ and refresh open surfaces.",
+    tags: ["apps"],
+    responseBody: z.object({
+      ok: z.literal(true),
+      appId: z.string(),
+      name: z.string(),
+      compiled: z.boolean(),
+      compile_duration_ms: z.number(),
+      compile_errors: z.array(compileDiagnosticSchema).optional(),
+      compile_warnings: z.array(compileDiagnosticSchema).optional(),
+    }),
+  },
   {
     operationId: "apps_delete",
     endpoint: "apps/:id/delete",

package/src/runtime/routes/app-routes.ts

@@ -92,7 +92,7 @@ function serveCompiledApp(
     );
     const body = isLegacySingleFileDir(appDir)
       ? UNSUPPORTED_LEGACY_APP_HTML
-      : `<p>App has not been compiled yet. Edit a source file to trigger a build.</p>`;
+      : `<p>App has not been compiled yet. Run <code>assistant apps refresh</code> to build.</p>`;
     return (
       `<!DOCTYPE html><html><head><title>${escapedName}</title></head>` +
       `<body>${body}</body></html>`

package/src/runtime/routes/channel-send-routes.ts

@@ -0,0 +1,85 @@
+/**
+ * Route handler for a model-directed text send to a channel chat.
+ *
+ * POST /v1/channels/send: deliver text to a chat on a channel through the
+ * channel's transport, recorded after acknowledgement. The
+ * messaging tool's channel branch runs the same function in-process; this
+ * route is the door for the CLI and scripts, so the two doors share one
+ * seam and one record.
+ */
+
+import { z } from "zod";
+
+import { CHANNEL_IDS } from "../../channels/types.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import {
+  ChannelNotAddressableError,
+  ChannelSendFailedError,
+  sendChannelText,
+} from "../channel-send.js";
+import { BadGatewayError, BadRequestError } from "./errors.js";
+import { parseBody } from "./parse-body.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+
+const ProactiveTargetSchema = z.object({
+  kind: z.literal("chat"),
+  chatId: z.string().min(1).describe("Chat id in the channel's own id space"),
+  threadId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Thread within the chat, in the channel's own id space"),
+});
+
+const ChannelSendRequestSchema = z.object({
+  channel: z.enum(CHANNEL_IDS).describe("Channel to send on"),
+  target: ProactiveTargetSchema,
+  text: z.string().min(1).describe("Text to send"),
+  renderRichly: z
+    .boolean()
+    .optional()
+    .describe("Ask the channel for its rich rendering, where it has one"),
+});
+
+const ChannelSendResponseSchema = z.object({
+  channel: z.enum(CHANNEL_IDS),
+  chatId: z.string(),
+  threadId: z.string().optional(),
+  messageIds: z.array(z.string()),
+  lastMessageId: z.string(),
+  recordedIn: z.string().optional(),
+});
+
+async function handleChannelSend({ body }: RouteHandlerArgs) {
+  const request = parseBody(ChannelSendRequestSchema, body);
+  try {
+    return await sendChannelText(request);
+  } catch (e) {
+    if (e instanceof ChannelNotAddressableError) {
+      throw new BadRequestError(e.message);
+    }
+    if (e instanceof ChannelSendFailedError) {
+      throw new BadGatewayError(e.message);
+    }
+    throw e;
+  }
+}
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "channels_send_post",
+    endpoint: "channels/send",
+    method: "POST",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Send text to a channel chat",
+    description:
+      "Deliver text to a chat on a channel through the channel's transport, recorded after the channel acknowledges it.",
+    tags: ["channels"],
+    handler: handleChannelSend,
+    requestBody: ChannelSendRequestSchema,
+    responseBody: ChannelSendResponseSchema,
+  },
+];

package/src/runtime/routes/conversation-list-routes.ts

@@ -14,6 +14,7 @@ import { z } from "zod";
 
 import { CHANNEL_IDS } from "../../channels/types.js";
 import { isAssistantInitiatedThreadsEnabled } from "../../config/assistant-initiated-threads-gate.js";
+import { localeFromAcceptLanguage } from "../../i18n/index.js";
 import { channelBindingSchema } from "../../messaging/channel-binding-schema.js";
 import {
   type Confidence,
@@ -244,7 +245,10 @@ function parseEnumQueryParam<const T extends readonly string[]>(
   );
 }
 
-function handleListConversations({ queryParams = {} }: RouteHandlerArgs) {
+function handleListConversations({
+  queryParams = {},
+  headers,
+}: RouteHandlerArgs) {
   const limit = Number(queryParams.limit ?? 50);
   const offset = Number(queryParams.offset ?? 0);
   // "background" is the back-compat umbrella (background + scheduled); newer
@@ -365,6 +369,7 @@ function handleListConversations({ queryParams = {} }: RouteHandlerArgs) {
         // Checks in-memory flag first (hot path), falls back to the
         // persisted `processing_started_at` column for cold conversations.
         isProcessing: isConversationProcessing(conversation.id),
+        locale: localeFromAcceptLanguage(headers?.["accept-language"]),
       }),
     ),
     nextOffset,
@@ -579,8 +584,14 @@ function handleMarkUnread({ body = {}, headers }: RouteHandlerArgs) {
   }
 }
 
-function handleGetConversation({ pathParams = {} }: RouteHandlerArgs) {
-  const detail = buildConversationDetailResponse(pathParams.id!);
+function handleGetConversation({
+  pathParams = {},
+  headers,
+}: RouteHandlerArgs) {
+  const detail = buildConversationDetailResponse(
+    pathParams.id!,
+    localeFromAcceptLanguage(headers?.["accept-language"]),
+  );
   if (!detail) {
     throw new NotFoundError(`Conversation ${pathParams.id} not found`);
   }

package/src/runtime/routes/conversation-query-routes.ts

@@ -29,6 +29,7 @@ import {
   LatencyBreakdownSchema,
   LLMRequestLogEntrySchema,
 } from "../../api/responses/llm-request-log-entry.js";
+import { scrubNulledAcpAgentLeaves } from "../../config/acp-agent-write.js";
 import {
   catalogEntryFor,
   type InputModalities,
@@ -92,6 +93,7 @@ import {
   log,
 } from "../../daemon/handlers/shared.js";
 import { rescheduleHeartbeatIfTimezoneChanged } from "../../heartbeat/heartbeat-service.js";
+import { overlayWorkspaceMcpForConfigRead } from "../../mcp/workspace-mcp-config.js";
 import {
   getAssistantMessageIdsInTurn,
   getConversation,
@@ -687,6 +689,38 @@ function rejectMcpTransportHeaderWrite(patch: unknown): void {
   );
 }
 
+const MCP_CONFIG_WRITE_MESSAGE =
+  "MCP servers are stored in mcp.json. Use assistant mcp add or assistant mcp remove.";
+
+function stripMcpFromConfigWrite(patch: Record<string, unknown>): void {
+  if (Object.hasOwn(patch, "mcp")) {
+    delete patch.mcp;
+  }
+}
+
+function rejectMcpConfigSetPath(path: string, value: unknown): void {
+  if (path !== "mcp" && !path.startsWith("mcp.")) {
+    return;
+  }
+  const relative =
+    path === "mcp" ? value : nestPath(path.slice("mcp.".length), value);
+  if (patchContainsMcpTransportHeaders({ mcp: relative })) {
+    throw new BadRequestError(
+      "MCP authentication headers must be managed through MCP server add/update APIs, not generic config writes.",
+    );
+  }
+  throw new BadRequestError(MCP_CONFIG_WRITE_MESSAGE);
+}
+
+function nestPath(path: string, value: unknown): unknown {
+  const segments = path.split(".");
+  let current: unknown = value;
+  for (let i = segments.length - 1; i >= 0; i--) {
+    current = { [segments[i]!]: current };
+  }
+  return current;
+}
+
 const WireProfileEntry = ProfileEntry.extend({
   supportsVision: z.boolean().optional(),
   invariant: z.boolean().optional(),
@@ -893,6 +927,7 @@ const ConfigPatchRequestSchema = z
 function handleGetConfig() {
   try {
     const config = applyContextDefaultsToRawConfig(loadRawConfig());
+    overlayWorkspaceMcpForConfigRead(config);
     sanitizeMcpTransportHeadersForSettingsRead(config);
     overlayEffectiveProfilesForWire(config);
     enrichProfilesForWire(config);
@@ -1594,6 +1629,7 @@ async function handlePatchConfig({ body }: RouteHandlerArgs) {
   normalizeManagedProfileWrites(body);
   rejectManagedProfileDeletion(body as Record<string, unknown>);
   rejectMcpTransportHeaderWrite(body);
+  stripMcpFromConfigWrite(body as Record<string, unknown>);
 
   const raw = loadRawConfig();
   const patch = body as Record<string, unknown>;
@@ -1603,11 +1639,13 @@ async function handlePatchConfig({ body }: RouteHandlerArgs) {
   }
   deepMergeOverwrite(raw, patch);
   scrubRemovedServiceModes(raw);
+  scrubNulledAcpAgentLeaves(raw);
   seedSttProviderForSparseBlock(raw);
 
   await commitConfigWrite(raw, "patch");
 
   const merged = applyContextDefaultsToRawConfig(loadRawConfig());
+  overlayWorkspaceMcpForConfigRead(merged);
   sanitizeMcpTransportHeadersForSettingsRead(merged);
   overlayEffectiveProfilesForWire(merged);
   enrichProfilesForWire(merged);
@@ -1670,6 +1708,7 @@ async function handleSetConfig({ body }: RouteHandlerArgs) {
   stripWireOnlyProfileKeys(patchShape);
   normalizeManagedProfileWrites(patchShape);
   rejectManagedProfileDeletion(patchShape);
+  rejectMcpConfigSetPath(path, value);
   rejectMcpTransportHeaderWrite(patchShape);
 
   const raw = loadRawConfig();
@@ -1708,6 +1747,7 @@ async function handleSetConfig({ body }: RouteHandlerArgs) {
       written.source = "managed";
     }
   }
+  scrubNulledAcpAgentLeaves(raw);
   // A SET can create `services.stt` with a leaf like `language` and no
   // `provider`, which SttServiceSchema requires whenever the block exists;
   // the same seeding that guards PATCH keeps this write's persisted block

package/src/runtime/routes/conversation-routes.ts

@@ -140,7 +140,10 @@ import {
   getOrCreateConversation,
 } from "../../persistence/conversation-key-store.js";
 import { searchConversations } from "../../persistence/conversation-queries.js";
-import { isNoResponseMetadata } from "../../persistence/conversation-types.js";
+import {
+  isNoResponseMetadata,
+  messageMetadataIsAmbientSightKeep,
+} from "../../persistence/conversation-types.js";
 import { linkRequestLogsToMessage } from "../../persistence/llm-request-log-store.js";
 import { assistantTextVisibilityOf } from "../../persistence/user-facing-content.js";
 import { MEMORY_RETROSPECTIVE_FORK_SOURCE } from "../../plugins/defaults/memory/memory-retrospective-constants.js";
@@ -159,6 +162,7 @@ import {
   getWorkspaceDir,
   getWorkspacePromptPath,
 } from "../../util/platform.js";
+import { safeStringSlice } from "../../util/unicode.js";
 import { assistantEventHub, broadcastMessage } from "../assistant-event-hub.js";
 import { getCurrentSeq } from "../assistant-stream-state.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
@@ -1037,6 +1041,9 @@ export async function handleListMessages({
     let backgroundToolCompletion: ConversationMessage["backgroundToolCompletion"];
     let systemCard: boolean | undefined;
     let noResponse: boolean | undefined;
+    const cameraFrame = messageMetadataIsAmbientSightKeep(msg.metadata)
+      ? true
+      : undefined;
     let reaction: ConversationMessage["reaction"];
     let providerError: ConversationMessage["providerError"];
     let deletedAt: number | undefined;
@@ -1136,6 +1143,7 @@ export async function handleListMessages({
       backgroundToolCompletion,
       systemCard,
       noResponse,
+      cameraFrame,
       reaction,
       providerError,
       slackMessage,
@@ -1353,6 +1361,7 @@ export async function handleListMessages({
           : {}),
         ...(m.systemCard ? { systemCard: true } : {}),
         ...(m.noResponse ? { noResponse: true } : {}),
+        ...(m.cameraFrame ? { cameraFrame: true as const } : {}),
         // The row's own marker, so a client gates per-row presentation on what
         // this row was written with rather than on the live flag.
         ...(m.assistantTextVisibility
@@ -3289,11 +3298,15 @@ async function generateLlmSuggestion(
 ): Promise<string | null> {
   const log = (await import("../../util/logger.js")).getLogger("runtime-http");
   const truncatedAssistant = escapeXmlContent(
-    assistantText.length > 2000 ? assistantText.slice(-2000) : assistantText,
+    assistantText.length > 2000
+      ? safeStringSlice(assistantText, assistantText.length - 2000)
+      : assistantText,
   );
   const truncatedUser =
     priorUserText && priorUserText.length > 500
-      ? escapeXmlContent(priorUserText.slice(-500))
+      ? escapeXmlContent(
+          safeStringSlice(priorUserText, priorUserText.length - 500),
+        )
       : priorUserText
         ? escapeXmlContent(priorUserText)
         : priorUserText;

package/src/runtime/routes/credential-routes.ts

@@ -43,7 +43,7 @@ import {
   deleteCredentialMetadata,
   getCredentialMetadata,
   getCredentialMetadataById,
-  listCredentialMetadata,
+  listCredentialRecordsLive,
 } from "../../tools/credentials/metadata-store.js";
 import type { CredentialInjectionTemplate } from "../../tools/credentials/policy-types.js";
 import {
@@ -228,6 +228,9 @@ function assertNotPlatformManaged(
   }
 }
 
+const CREDENTIAL_STORE_UNREACHABLE =
+  "Credential store is unreachable. Retry in a moment, or check that the credential vault is running.";
+
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
@@ -235,9 +238,14 @@ function assertNotPlatformManaged(
 async function handleCredentialsList({ body }: RouteHandlerArgs) {
   const search = (body as { search?: string } | undefined)?.search;
 
+  const live = await listCredentialRecordsLive();
+  if (live.unreachable) {
+    throw new InternalError(CREDENTIAL_STORE_UNREACHABLE);
+  }
+
   // Platform-provisioned credentials are not the user's to act on, so they
   // never become a Settings row (and never a click-to-reveal).
-  let allMetadata = listCredentialMetadata().filter(
+  let allMetadata = live.records.filter(
     (m) => !isPlatformManagedCredential(m.service, m.field),
   );
 
@@ -272,7 +280,12 @@ async function handleCredentialsList({ body }: RouteHandlerArgs) {
 
   const credentials = await Promise.all(
     allMetadata.map(async (m) => {
-      const secret = await getSecureKeyAsync(credentialKey(m.service, m.field));
+      const { value: secret, unreachable } = await getSecureKeyResultAsync(
+        credentialKey(m.service, m.field),
+      );
+      if (unreachable) {
+        throw new InternalError(CREDENTIAL_STORE_UNREACHABLE);
+      }
       const connection = connectionsByProvider.get(m.service);
       return buildCredentialOutput(m, secret, connection);
     }),
@@ -310,9 +323,7 @@ async function handleCredentialsInspect({ body }: RouteHandlerArgs) {
 
   if (!lookup.metadata && (secret == null || secret.length === 0)) {
     if (unreachable) {
-      throw new InternalError(
-        "Credential store is unreachable — ensure the assistant is running",
-      );
+      throw new InternalError(CREDENTIAL_STORE_UNREACHABLE);
     }
     throw new BadRequestError("Credential not found");
   }
@@ -374,9 +385,7 @@ async function handleCredentialsReveal({ body, headers }: RouteHandlerArgs) {
 
   if (secret == null || secret.length === 0) {
     if (unreachable) {
-      throw new InternalError(
-        "Credential store is unreachable — ensure the assistant is running",
-      );
+      throw new InternalError(CREDENTIAL_STORE_UNREACHABLE);
     }
     throw new BadRequestError("Credential not found");
   }
@@ -620,7 +629,7 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "List all credentials with metadata",
     description:
-      "Return all stored credentials with metadata, OAuth connection info, and platform-managed credentials.",
+      "Return credentials from the live credential vault, with OAuth connection info and platform-managed credentials. Fails if the vault is unreachable.",
     tags: ["credentials"],
     requestBody: z.object({
       search: z.string().optional().describe("Filter by substring match"),