@vellumai/assistant 0.7.1 → 0.7.2

package/src/runtime/routes/host-browser-routes.ts

@@ -11,7 +11,8 @@ import {
   publishCdpEvent,
 } from "../../browser-session/events.js";
 import { HostBrowserProxy } from "../../daemon/host-browser-proxy.js";
-import { BadRequestError, NotFoundError } from "./errors.js";
+import * as pendingInteractions from "../pending-interactions.js";
+import { BadRequestError, ConflictError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 /**
@@ -29,21 +30,26 @@ export type HostBrowserResultResolution =
   | { ok: true }
   | {
       ok: false;
-      code: "BAD_REQUEST" | "NOT_FOUND";
-      status: 400 | 404;
+      code: "BAD_REQUEST" | "NOT_FOUND" | "CONFLICT";
+      status: 400 | 404 | 409;
       message: string;
     };
 
 /**
- * Shared resolver used by both the HTTP route handler and the WS
- * `host_browser_result` frame handler. Looks up the pending interaction
- * by requestId, validates its kind, and forwards the response to the
- * owning conversation.
+ * Resolver for the `POST /v1/host-browser-result` HTTP route. Looks up
+ * the pending interaction by requestId, validates its kind is
+ * `host_browser`, and forwards the response to the owning conversation.
+ *
+ * NOTE: The WebSocket `host_browser_result` frame path does NOT go
+ * through this function — it is handled by `HostBrowserProxy.resolveResult`
+ * directly, which only consults `pendingInteractions` and does not
+ * currently perform a kind check. That asymmetry is pre-existing; if
+ * the WS path is ever opened to less-trusted clients, it should adopt
+ * the same kind-check guard added here.
  *
  * This function does NOT perform auth — callers are expected to have
  * already authenticated the caller (the HTTP route uses
- * `requireBoundGuardian`, the WS path relies on the JWT check performed
- * at WebSocket upgrade time).
+ * `requireBoundGuardian`).
  */
 export function resolveHostBrowserResultByRequestId(frame: {
   requestId?: unknown;
@@ -61,20 +67,30 @@ export function resolveHostBrowserResultByRequestId(frame: {
     };
   }
 
-  const proxy = HostBrowserProxy.instance;
-  if (!proxy.hasPendingRequest(requestId)) {
+  const peeked = pendingInteractions.get(requestId);
+  if (!peeked) {
     return {
       ok: false,
       code: "NOT_FOUND",
       status: 404,
-      message: "No pending interaction found for this requestId",
+      message: "No pending browser request for this requestId",
+    };
+  }
+
+  if (peeked.kind !== "host_browser") {
+    return {
+      ok: false,
+      code: "CONFLICT",
+      status: 409,
+      message: `Pending interaction is of kind "${peeked.kind}", expected "host_browser"`,
     };
   }
 
   const normalizedContent = typeof content === "string" ? content : "";
   const normalizedIsError = typeof isError === "boolean" ? isError : false;
 
-  proxy.resolve(requestId, {
+  const proxy = HostBrowserProxy.instance;
+  proxy.resolveResult(requestId, {
     content: normalizedContent,
     isError: normalizedIsError,
   });
@@ -181,6 +197,42 @@ function handleHostBrowserResult({ body }: RouteHandlerArgs) {
   if (!resolution.ok) {
     if (resolution.code === "NOT_FOUND")
       throw new NotFoundError(resolution.message);
+    if (resolution.code === "CONFLICT")
+      throw new ConflictError(resolution.message);
+    throw new BadRequestError(resolution.message);
+  }
+
+  return { accepted: true };
+}
+
+// ---------------------------------------------------------------------------
+// POST /v1/host-browser-event
+// ---------------------------------------------------------------------------
+
+function handleHostBrowserEvent({ body }: RouteHandlerArgs) {
+  if (!body || typeof body !== "object") {
+    throw new BadRequestError("Request body is required");
+  }
+
+  const resolution = resolveHostBrowserEvent(body);
+  if (!resolution.ok) {
+    throw new BadRequestError(resolution.message);
+  }
+
+  return { accepted: true };
+}
+
+// ---------------------------------------------------------------------------
+// POST /v1/host-browser-session-invalidated
+// ---------------------------------------------------------------------------
+
+function handleHostBrowserSessionInvalidated({ body }: RouteHandlerArgs) {
+  if (!body || typeof body !== "object") {
+    throw new BadRequestError("Request body is required");
+  }
+
+  const resolution = resolveHostBrowserSessionInvalidated(body);
+  if (!resolution.ok) {
     throw new BadRequestError(resolution.message);
   }
 
@@ -210,4 +262,47 @@ export const ROUTES: RouteDefinition[] = [
     }),
     handler: handleHostBrowserResult,
   },
+  {
+    operationId: "host_browser_event",
+    endpoint: "host-browser-event",
+    method: "POST",
+    requireGuardian: true,
+    summary: "Forward a CDP event from the browser extension",
+    description:
+      "Publishes a chrome.debugger.onEvent firing into the runtime-side browser-session event bus.",
+    tags: ["host"],
+    requestBody: z.object({
+      method: z.string().describe("CDP event method name"),
+      params: z.unknown().optional().describe("CDP event parameters"),
+      cdpSessionId: z
+        .string()
+        .optional()
+        .describe("CDP session ID (if target-scoped)"),
+    }),
+    responseBody: z.object({
+      accepted: z.boolean(),
+    }),
+    handler: handleHostBrowserEvent,
+  },
+  {
+    operationId: "host_browser_session_invalidated",
+    endpoint: "host-browser-session-invalidated",
+    method: "POST",
+    requireGuardian: true,
+    summary: "Notify runtime that a CDP session was invalidated",
+    description:
+      "Marks the target as invalidated in the runtime-side browser session registry.",
+    tags: ["host"],
+    requestBody: z.object({
+      targetId: z
+        .string()
+        .optional()
+        .describe("CDP target that was detached"),
+      reason: z.string().optional().describe("Detach reason"),
+    }),
+    responseBody: z.object({
+      accepted: z.boolean(),
+    }),
+    handler: handleHostBrowserSessionInvalidated,
+  },
 ];

package/src/runtime/routes/host-cu-routes.ts

@@ -8,18 +8,14 @@ import { z } from "zod";
 
 import { findConversation } from "../../daemon/conversation-store.js";
 import * as pendingInteractions from "../pending-interactions.js";
-import {
-  BadRequestError,
-  ConflictError,
-  NotFoundError,
-} from "./errors.js";
+import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 // ---------------------------------------------------------------------------
 // POST /v1/host-cu-result
 // ---------------------------------------------------------------------------
 
-function handleHostCuResult({ body }: RouteHandlerArgs) {
+function handleHostCuResult({ body, headers }: RouteHandlerArgs) {
   if (!body || typeof body !== "object") {
     throw new BadRequestError("Request body is required");
   }
@@ -58,9 +54,7 @@ function handleHostCuResult({ body }: RouteHandlerArgs) {
 
   const peeked = pendingInteractions.get(requestId);
   if (!peeked) {
-    throw new NotFoundError(
-      "No pending interaction found for this requestId",
-    );
+    throw new NotFoundError("No pending interaction found for this requestId");
   }
 
   if (peeked.kind !== "host_cu") {
@@ -69,13 +63,32 @@ function handleHostCuResult({ body }: RouteHandlerArgs) {
     );
   }
 
-  const interaction = pendingInteractions.resolve(requestId)!;
-  const conversation = findConversation(interaction.conversationId);
+  // Validate submitting client matches the targeted client (if any).
+  if (peeked.targetClientId != null) {
+    const rawClientId = (headers as Record<string, string | undefined>)?.["x-vellum-client-id"];
+    const submittingClientId = rawClientId?.trim() || undefined;
+    if (!submittingClientId) {
+      throw new BadRequestError("x-vellum-client-id header is missing for a targeted host CU request.");
+    }
+    if (submittingClientId !== peeked.targetClientId) {
+      throw new ForbiddenError(
+        `Client "${submittingClientId}" is not the target for this request (expected "${peeked.targetClientId}"). The targeted client must submit the result.`,
+      );
+    }
+  }
+
+  const conversation = findConversation(peeked.conversationId);
   if (!conversation) {
+    pendingInteractions.resolve(requestId);
     throw new NotFoundError("Conversation not found for host CU result");
   }
 
-  conversation.hostCuProxy?.resolve(requestId, {
+  if (!conversation.hostCuProxy) {
+    pendingInteractions.resolve(requestId);
+    throw new NotFoundError("No host CU proxy for conversation");
+  }
+
+  conversation.hostCuProxy.processObservation(requestId, {
     axTree,
     axDiff,
     screenshot,
@@ -103,8 +116,7 @@ export const ROUTES: RouteDefinition[] = [
     method: "POST",
     requireGuardian: true,
     summary: "Submit host CU result",
-    description:
-      "Resolve a pending host computer-use request by requestId.",
+    description: "Resolve a pending host computer-use request by requestId.",
     tags: ["host"],
     requestBody: z.object({
       requestId: z.string().describe("Pending CU request ID"),
@@ -123,6 +135,24 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({
       accepted: z.boolean(),
     }),
+    additionalResponses: {
+      "400": {
+        description:
+          "x-vellum-client-id header is missing for a targeted host CU request.",
+      },
+      "403": {
+        description:
+          "Submitting client does not match the targeted client for this request.",
+      },
+      "404": {
+        description:
+          "No pending interaction found for the given requestId, or the conversation/proxy no longer exists.",
+      },
+      "409": {
+        description:
+          "Pending interaction exists but is of a different kind (e.g. host_bash, host_file).",
+      },
+    },
     handler: handleHostCuResult,
   },
 ];

package/src/runtime/routes/host-file-routes.ts

@@ -8,18 +8,14 @@ import { z } from "zod";
 
 import { HostFileProxy } from "../../daemon/host-file-proxy.js";
 import * as pendingInteractions from "../pending-interactions.js";
-import {
-  BadRequestError,
-  ConflictError,
-  NotFoundError,
-} from "./errors.js";
+import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 // ---------------------------------------------------------------------------
 // POST /v1/host-file-result
 // ---------------------------------------------------------------------------
 
-function handleHostFileResult({ body }: RouteHandlerArgs) {
+function handleHostFileResult({ body, headers }: RouteHandlerArgs) {
   if (!body || typeof body !== "object") {
     throw new BadRequestError("Request body is required");
   }
@@ -37,9 +33,7 @@ function handleHostFileResult({ body }: RouteHandlerArgs) {
 
   const peeked = pendingInteractions.get(requestId);
   if (!peeked) {
-    throw new NotFoundError(
-      "No pending interaction found for this requestId",
-    );
+    throw new NotFoundError("No pending interaction found for this requestId");
   }
 
   if (peeked.kind !== "host_file") {
@@ -48,7 +42,19 @@ function handleHostFileResult({ body }: RouteHandlerArgs) {
     );
   }
 
-  pendingInteractions.resolve(requestId);
+  // Validate submitting client matches the targeted client (if any).
+  if (peeked.targetClientId != null) {
+    const rawClientId = (headers as Record<string, string | undefined>)?.["x-vellum-client-id"];
+    const submittingClientId = rawClientId?.trim() || undefined;
+    if (!submittingClientId) {
+      throw new BadRequestError("x-vellum-client-id header is missing for a targeted host file request.");
+    }
+    if (submittingClientId !== peeked.targetClientId) {
+      throw new ForbiddenError(
+        `Client "${submittingClientId}" is not the target for this request (expected "${peeked.targetClientId}"). The targeted client must submit the result.`,
+      );
+    }
+  }
 
   HostFileProxy.instance.resolve(requestId, {
     content: content ?? "",
@@ -90,6 +96,23 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({
       accepted: z.boolean(),
     }),
+    additionalResponses: {
+      "400": {
+        description:
+          "x-vellum-client-id header is missing for a targeted host file request.",
+      },
+      "403": {
+        description:
+          "Submitting client does not match the targeted client for this request.",
+      },
+      "404": {
+        description: "No pending interaction found for the given requestId.",
+      },
+      "409": {
+        description:
+          "Pending interaction exists but is of a different kind (e.g. host_bash, host_cu).",
+      },
+    },
     handler: handleHostFileResult,
   },
 ];

package/src/runtime/routes/host-transfer-routes.ts

@@ -9,11 +9,7 @@ import { z } from "zod";
 
 import { HostTransferProxy } from "../../daemon/host-transfer-proxy.js";
 import * as pendingInteractions from "../pending-interactions.js";
-import {
-  BadRequestError,
-  ConflictError,
-  NotFoundError,
-} from "./errors.js";
+import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 
 /**
@@ -34,6 +30,7 @@ function findProxyByTransferId(transferId: string) {
 
 function handleTransferContentGet({
   pathParams = {},
+  headers = {},
 }: RouteHandlerArgs): Uint8Array {
   const transferId = pathParams.transferId;
   if (!transferId) {
@@ -45,6 +42,13 @@ function handleTransferContentGet({
     throw new NotFoundError("Unknown or consumed transfer");
   }
 
+  const targetClientId = match.proxy.getTargetClientIdForTransfer(transferId);
+  if (targetClientId != null) {
+    const submittingClientId = (headers as Record<string, string>)["x-vellum-client-id"]?.trim() || undefined;
+    if (!submittingClientId) throw new BadRequestError("x-vellum-client-id header required for targeted transfer");
+    if (submittingClientId !== targetClientId) throw new ForbiddenError(`Client "${submittingClientId}" is not the owner of this transfer`);
+  }
+
   const content = match.proxy.getTransferContent(transferId);
   if (!content) {
     throw new NotFoundError("Unknown or consumed transfer");
@@ -55,8 +59,11 @@ function handleTransferContentGet({
 
 /**
  * Resolve Content-Length and X-Transfer-SHA256 response headers for the
- * GET transfer content endpoint. Called by the HTTP adapter before
- * sending the response.
+ * GET transfer content endpoint. Called by the HTTP adapter AFTER the handler
+ * runs (`http-adapter.ts:107-125`), so the entry has already been consumed by
+ * `getTransferContent`. We read the size/sha256 from
+ * `takeJustConsumedTransferMetadata`, which the proxy populates synchronously
+ * during the handler's `getTransferContent` call.
  */
 function resolveTransferContentGetHeaders({
   pathParams = {},
@@ -66,16 +73,14 @@ function resolveTransferContentGetHeaders({
   const transferId = pathParams?.transferId;
   if (!transferId) return { "Content-Type": "application/octet-stream" };
 
-  const match = findProxyByTransferId(transferId);
-  if (!match) return { "Content-Type": "application/octet-stream" };
-
-  const content = match.proxy.getTransferContent(transferId);
-  if (!content) return { "Content-Type": "application/octet-stream" };
+  const meta =
+    HostTransferProxy.instance.takeJustConsumedTransferMetadata(transferId);
+  if (!meta) return { "Content-Type": "application/octet-stream" };
 
   return {
     "Content-Type": "application/octet-stream",
-    "Content-Length": content.sizeBytes.toString(),
-    "X-Transfer-SHA256": content.sha256,
+    "Content-Length": meta.sizeBytes.toString(),
+    "X-Transfer-SHA256": meta.sha256,
   };
 }
 
@@ -98,6 +103,13 @@ async function handleTransferContentPut({
     throw new NotFoundError("Unknown or consumed transfer");
   }
 
+  const targetClientId = match.proxy.getTargetClientIdForTransfer(transferId);
+  if (targetClientId != null) {
+    const submittingClientId = (headers as Record<string, string>)["x-vellum-client-id"]?.trim() || undefined;
+    if (!submittingClientId) throw new BadRequestError("x-vellum-client-id header required for targeted transfer");
+    if (submittingClientId !== targetClientId) throw new ForbiddenError(`Client "${submittingClientId}" is not the owner of this transfer`);
+  }
+
   const data = rawBody ? Buffer.from(rawBody) : Buffer.alloc(0);
   const sha256 = headers["x-transfer-sha256"] ?? "";
 
@@ -107,11 +119,6 @@ async function handleTransferContentPut({
     sha256,
   );
 
-  // For to_sandbox transfers there is no separate /v1/host-transfer-result
-  // callback — the PUT handler is the terminal event. Always clean up the
-  // pending interaction so it doesn't leak.
-  pendingInteractions.resolve(match.requestId);
-
   if (!result.accepted) {
     throw new BadRequestError(result.error ?? "Transfer content rejected");
   }
@@ -123,7 +130,7 @@ async function handleTransferContentPut({
 // POST /v1/host-transfer-result
 // ---------------------------------------------------------------------------
 
-function handleTransferResult({ body }: RouteHandlerArgs) {
+function handleTransferResult({ body, headers }: RouteHandlerArgs) {
   if (!body || typeof body !== "object") {
     throw new BadRequestError("Request body is required");
   }
@@ -141,9 +148,7 @@ function handleTransferResult({ body }: RouteHandlerArgs) {
 
   const peeked = pendingInteractions.get(requestId);
   if (!peeked) {
-    throw new NotFoundError(
-      "No pending interaction found for this requestId",
-    );
+    throw new NotFoundError("No pending interaction found for this requestId");
   }
 
   if (peeked.kind !== "host_transfer") {
@@ -152,7 +157,12 @@ function handleTransferResult({ body }: RouteHandlerArgs) {
     );
   }
 
-  pendingInteractions.resolve(requestId);
+  if (peeked.targetClientId != null) {
+    const rawClientId = (headers as Record<string, string | undefined>)?.["x-vellum-client-id"];
+    const submittingClientId = rawClientId?.trim() || undefined;
+    if (!submittingClientId) throw new BadRequestError("x-vellum-client-id header is missing for a targeted host transfer request.");
+    if (submittingClientId !== peeked.targetClientId) throw new ForbiddenError(`Client "${submittingClientId}" is not the target for this request (expected "${peeked.targetClientId}").`);
+  }
 
   HostTransferProxy.instance.resolveTransferResult(requestId, {
     isError: isError ?? false,
@@ -179,6 +189,16 @@ export const ROUTES: RouteDefinition[] = [
       "Serve raw file bytes for a to_host transfer. Single-use: returns 404 after first consumption.",
     tags: ["host-transfer"],
     responseHeaders: resolveTransferContentGetHeaders,
+    additionalResponses: {
+      "400": {
+        description:
+          "x-vellum-client-id header is missing for a targeted transfer.",
+      },
+      "403": {
+        description:
+          "Submitting client does not match the targeted client for this transfer.",
+      },
+    },
     handler: handleTransferContentGet,
   },
   {
@@ -191,6 +211,16 @@ export const ROUTES: RouteDefinition[] = [
     description:
       "Receive raw file bytes for a to_sandbox transfer. Verifies SHA-256 integrity via the X-Transfer-SHA256 header.",
     tags: ["host-transfer"],
+    additionalResponses: {
+      "400": {
+        description:
+          "x-vellum-client-id header is missing for a targeted transfer.",
+      },
+      "403": {
+        description:
+          "Submitting client does not match the targeted client for this transfer.",
+      },
+    },
     handler: handleTransferContentPut,
   },
   {
@@ -211,6 +241,16 @@ export const ROUTES: RouteDefinition[] = [
     responseBody: z.object({
       accepted: z.boolean(),
     }),
+    additionalResponses: {
+      "400": {
+        description:
+          "x-vellum-client-id header is missing for a targeted host transfer request.",
+      },
+      "403": {
+        description:
+          "Submitting client does not match the targeted client for this transfer.",
+      },
+    },
     handler: handleTransferResult,
   },
 ];

package/src/runtime/routes/http-adapter.ts

@@ -163,6 +163,7 @@ export function routeDefinitionsToHTTPRoutes(
             err.code as HttpErrorCode,
             err.message,
             err.statusCode,
+            err.details,
           );
         }
         throw err;

package/src/runtime/routes/identity-intro-cache.ts

@@ -48,6 +48,36 @@ function readWorkspaceFile(name: string): string {
   }
 }
 
+function parseIdentityIntroSection(content: string): string | null {
+  let inSection = false;
+
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (/^#+\s/.test(trimmed)) {
+      inSection = trimmed.toLowerCase().includes("identity intro");
+      continue;
+    }
+    if (inSection && trimmed.length > 0) {
+      return trimmed;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Read the explicit `## Identity Intro` section from workspace prompt files.
+ *
+ * BOOTSTRAP.md instructs the assistant to write this section in IDENTITY.md.
+ * SOUL.md remains a fallback for older workspaces that stored the intro there.
+ */
+export function readWorkspaceIdentityIntro(): string | null {
+  return (
+    parseIdentityIntroSection(readWorkspaceFile("IDENTITY.md")) ??
+    parseIdentityIntroSection(readWorkspaceFile("SOUL.md"))
+  );
+}
+
 /** Compute a SHA-256 hex hash of the concatenated identity file contents. */
 export function computeIdentityContentHash(): string {
   const staticFiles = IDENTITY_FILES.map(readWorkspaceFile).join("\n---\n");

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

@@ -3,7 +3,7 @@
  */
 
 import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync, statfsSync, statSync } from "node:fs";
+import { existsSync, readFileSync, statfsSync } from "node:fs";
 import { availableParallelism, cpus, totalmem } from "node:os";
 
 import { z } from "zod";
@@ -21,6 +21,7 @@ import {
   getWorkspacePromptPath,
 } from "../../util/platform.js";
 import { APP_VERSION } from "../../version.js";
+import { resolveHatchedAtReadOnly } from "../../workspace/hatched-date.js";
 import { WORKSPACE_MIGRATIONS } from "../../workspace/migrations/registry.js";
 import { getLastWorkspaceMigrationId } from "../../workspace/migrations/runner.js";
 import { NotFoundError } from "./errors.js";
@@ -488,13 +489,7 @@ function getIdentity() {
 
   const version = APP_VERSION;
 
-  let createdAt: string | undefined;
-  try {
-    const stats = statSync(identityPath);
-    createdAt = stats.birthtime.toISOString();
-  } catch {
-    // ignore
-  }
+  const createdAt = resolveIdentityCreatedAt(identityPath);
 
   return {
     name: fields.name ?? "",
@@ -507,10 +502,18 @@ function getIdentity() {
   };
 }
 
+function resolveIdentityCreatedAt(identityPath: string): string | undefined {
+  return resolveHatchedAtReadOnly(identityPath);
+}
+
 function getIdentityIntro() {
-  const soulIntro = readSoulIdentityIntro();
-  if (soulIntro) {
-    return { text: soulIntro };
+  const identityPath = getWorkspacePromptPath("IDENTITY.md");
+  if (existsSync(identityPath)) {
+    const content = readFileSync(identityPath, "utf-8");
+    const fields = parseIdentityFields(content);
+    if (fields.name) {
+      return { text: `Hi, I'm ${fields.name}!` };
+    }
   }
 
   const cached = getCachedIntro();
@@ -520,37 +523,6 @@ function getIdentityIntro() {
   return { text: cached.text };
 }
 
-// ---------------------------------------------------------------------------
-// Identity intro cache
-// ---------------------------------------------------------------------------
-
-/**
- * Parse the `## Identity Intro` section from SOUL.md.
- * Returns the first non-empty line under that heading, or null.
- */
-function readSoulIdentityIntro(): string | null {
-  try {
-    const soulPath = getWorkspacePromptPath("SOUL.md");
-    if (!existsSync(soulPath)) return null;
-    const content = readFileSync(soulPath, "utf-8");
-
-    let inSection = false;
-    for (const line of content.split("\n")) {
-      const trimmed = line.trim();
-      if (/^#+\s/.test(trimmed)) {
-        inSection = trimmed.toLowerCase().includes("identity intro");
-        continue;
-      }
-      if (inSection && trimmed.length > 0) {
-        return trimmed;
-      }
-    }
-  } catch {
-    // Fall through to cache/fallback
-  }
-  return null;
-}
-
 // ---------------------------------------------------------------------------
 // Zod schemas for profiler health metadata
 // ---------------------------------------------------------------------------
@@ -647,7 +619,7 @@ export const ROUTES: RouteDefinition[] = [
     handler: getIdentityIntro,
     summary: "Get identity intro text",
     description:
-      "Returns the cached identity intro string, preferring SOUL.md over LLM-generated cache.",
+      "Returns a deterministic greeting derived from the assistant name in IDENTITY.md, falling back to LLM-generated cache.",
     tags: ["identity"],
     responseBody: z.object({
       text: z.string(),