@vellumai/assistant 0.11.1 → 0.11.2-staging.2

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

@@ -29,11 +29,7 @@ import {
   discardLastAssistantDisplayTurn,
   extractUserPromptText,
 } from "../../daemon/conversation-history.js";
-import {
-  formatSummarizeUpToResult,
-  isBackgroundEventMetadata,
-  isEchoSuppressedUserMessage,
-} from "../../daemon/conversation-process.js";
+import { formatSummarizeUpToResult } from "../../daemon/conversation-process.js";
 import { findConversation } from "../../daemon/conversation-registry.js";
 import {
   destroyActiveConversation,
@@ -55,6 +51,8 @@ import {
   deleteConversation,
   forkConversation as forkConversationInStore,
   getConversation,
+  isBackgroundEventMetadata,
+  isEchoSuppressedUserMessage,
   setConversationEnabledPlugins,
   setConversationSurfaced,
   unarchiveConversation,
@@ -280,7 +278,14 @@ async function handleSummarizeConversation({ body = {} }: RouteHandlerArgs) {
       conversation.emitActivityState("thinking", "context_compacting", {
         statusText: "Summarizing conversation",
       });
-      const result = await conversation.summarizeUpToMessage(beforeMessageId);
+      // The context-window usage push goes out on the same broadcast path as
+      // the result card below: this route resolves its conversation outside
+      // the send path, so the instance may still hold the store's no-op
+      // sender and a `sendToClient` emit would reach nobody.
+      const result = await conversation.summarizeUpToMessage(
+        beforeMessageId,
+        broadcastMessage,
+      );
       // Stop aborted the in-flight summary: the compactor reports the aborted
       // provider call as a non-compacted result (it swallows the abort rather
       // than throwing), so detect cancellation via the signal. A cancelled
@@ -745,6 +750,13 @@ async function handleRetryLastAssistantTurn({
         onEvent: broadcastMessage,
         isUserMessage: true,
         isInteractive,
+        // The re-run carries none of the anchor's original delivery
+        // orchestration: a channel anchor's reply is not posted back to
+        // Slack/Telegram (that is owned by the inbound event's
+        // `finalizeEventDelivery`) and a voice anchor's is not spoken over a
+        // session. The regenerated reply reaches SSE subscribers only, so the
+        // push is the user's only copy once they leave.
+        replyDeliveredInAppOnly: true,
         ...(isHiddenPrompt ? { isHiddenPrompt: true } : {}),
       });
     } catch (err) {

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

@@ -87,12 +87,15 @@ import {
   getMessageById,
 } from "../../persistence/conversation-crud.js";
 import { getConversationByKey } from "../../persistence/conversation-key-store.js";
+import {
+  type ConversationKind,
+  resolveConversationKind,
+} from "../../persistence/conversation-types.js";
 import { getDb } from "../../persistence/db-connection.js";
 import { clearEmbeddingBackendCache } from "../../persistence/embeddings/embedding-backend.js";
 import { getLlmRequestLogSource } from "../../persistence/llm-request-log-source.js";
 import { type LogRow } from "../../persistence/llm-request-log-store.js";
 import { getMemoryRecallLogByMessageIds } from "../../plugins/defaults/memory/memory-recall-log-store.js";
-import { MEMORY_V2_CONSOLIDATION_SOURCE } from "../../plugins/defaults/memory/substrate/constants.js";
 import { getMemoryV2ActivationLogByMessageIds } from "../../plugins/defaults/memory/v2/activation-log-store.js";
 import { getMemoryV3SelectionForInspectorByMessageIds } from "../../plugins/defaults/memory/v3/selection-log-store.js";
 import { ROUTING_IDENTITY_PROVIDERS } from "../../providers/inference/auth.js";
@@ -146,6 +149,7 @@ type LlmContextRouteResult = Omit<LlmContextNormalizationResult, "summary"> & {
 };
 
 import {
+  CODE_OWNED_PROFILE_NAMES,
   getEffectiveProfilesForProvider,
   INVARIANT_PROFILE_NAMES,
   MANAGED_PROFILE_NAMES,
@@ -1743,6 +1747,15 @@ async function handleReplaceInferenceProfile({
       `Profile "${name}" is not currently available and cannot be edited.`,
     );
   }
+  if (CODE_OWNED_PROFILE_NAMES.has(name)) {
+    // A code-owned profile resolves from the catalog whatever the workspace
+    // holds, so even a status re-enable would persist a stub that never
+    // governs anything. Reject the write rather than accept a silent no-op.
+    throw new BadRequestError(
+      `Profile "${name}" is code-owned and cannot be edited. ` +
+        `Duplicate it to a custom profile to customize.`,
+    );
+  }
   if (isManaged) {
     // Managed profiles are daemon-seeded and read-only — the commit guard
     // (`assertInvariantProfilesPreserved`) rejects every write to them
@@ -1966,28 +1979,6 @@ function handleGetMessageContent({
   return result;
 }
 
-type ConversationKind =
-  | "user"
-  | "background"
-  | "background_memory_consolidation"
-  | "scheduled";
-
-function resolveConversationKind(
-  source: string,
-  conversationType: string,
-): ConversationKind {
-  if (source === MEMORY_V2_CONSOLIDATION_SOURCE) {
-    return "background_memory_consolidation";
-  }
-  if (conversationType === "background") {
-    return "background";
-  }
-  if (conversationType === "scheduled") {
-    return "scheduled";
-  }
-  return "user";
-}
-
 async function handleGetLlmContext({
   pathParams = {},
   queryParams = {},

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

@@ -53,7 +53,6 @@ import {
   buildModelInfoEvent,
   formatCleanResult,
   formatCompactResult,
-  isBackgroundEventMetadata,
   isModelSlashCommand,
 } from "../../daemon/conversation-process.js";
 import { findConversation } from "../../daemon/conversation-registry.js";
@@ -113,8 +112,10 @@ import {
   getMessages,
   getMessagesPaginated,
   hasMessages,
+  isBackgroundEventMetadata,
   isConversationProcessing,
   isHiddenMessageMetadata,
+  isProviderErrorMetadata,
   isSystemCardMetadata,
   type MessageRow,
   recordConversationPersistedSeq,
@@ -212,6 +213,21 @@ interface AlignedAttachments {
   rewriteContentOrder: ContentOrderRewrite;
 }
 
+/**
+ * Metadata-only projection of an attachment for inline `contentBlocks`
+ * placement. The flat `attachments` array is the payload carrier: it keeps
+ * `data`/`thumbnailData`, and `/v1/assistants/:id/attachments/:id/content`
+ * serves stored bytes on demand. Attachment blocks are positional references
+ * the renderer resolves against that array by id, so inlining the base64 here
+ * would ship every image twice in the same response.
+ */
+function toAttachmentBlockRef(
+  a: RuntimeAttachmentMetadata,
+): RuntimeAttachmentMetadata {
+  const { data: _data, thumbnailData: _thumbnailData, ...meta } = a;
+  return meta;
+}
+
 /**
  * Align DB-hydrated attachment rows with the file-block refs `renderHistoryContent`
  * captured. When a file block carries an attachment id (user-message uploads —
@@ -339,6 +355,33 @@ function isValidRiskThreshold(value: unknown): value is RiskThreshold {
   );
 }
 
+/**
+ * Upper bound on the reported visible-app id. Sized so it can never clip an id
+ * the viewer can actually open: a plugin app id is `plugins~<plugin>~<app>`,
+ * and each of those two segments is a filesystem directory name bounded at 255
+ * bytes, so the longest openable id runs to ~519 characters. The cap exists
+ * only to bound what an arbitrary client can park on the conversation, not to
+ * validate the id — `resolveAppSource` decides what resolves.
+ */
+const VISIBLE_APP_ID_MAX_LENGTH = 640;
+
+/**
+ * True when the client-reported visible-app id is safe to carry as view state:
+ * non-empty, trimmed, bounded, and free of path separators or traversal.
+ * Mirrors the app store's own id validation so a malformed id is dropped at
+ * ingress instead of reaching a filesystem lookup.
+ */
+function isSafeVisibleAppId(value: string): boolean {
+  return (
+    value.length > 0 &&
+    value.length <= VISIBLE_APP_ID_MAX_LENGTH &&
+    value === value.trim() &&
+    !value.includes("/") &&
+    !value.includes("\\") &&
+    !value.includes("..")
+  );
+}
+
 /**
  * True when a message's persisted metadata explicitly flags it as hidden.
  * Used to suppress internal scaffolding messages from UI history while
@@ -890,6 +933,7 @@ export function handleListMessages({
     let backgroundEventNotification: boolean | undefined;
     let backgroundToolCompletion: ConversationMessage["backgroundToolCompletion"];
     let systemCard: boolean | undefined;
+    let providerError: ConversationMessage["providerError"];
     if (msg.metadata) {
       try {
         const meta = JSON.parse(msg.metadata);
@@ -901,6 +945,19 @@ export function handleListMessages({
         if (isSystemCardMetadata(meta)) {
           systemCard = true;
         }
+        // Daemon-persisted provider-failure notices carry the classified
+        // error code/category so clients can render a themed card instead
+        // of a persona bubble.
+        if (isProviderErrorMetadata(meta)) {
+          providerError = {
+            ...(typeof meta.providerErrorCode === "string"
+              ? { code: meta.providerErrorCode }
+              : {}),
+            ...(typeof meta.providerErrorCategory === "string"
+              ? { category: meta.providerErrorCategory }
+              : {}),
+          };
+        }
         // Every wake persists a `<background_event source="...">` trigger row
         // (see `persistWakeTriggerMessage`) that the LLM reads. Flag any such
         // row so clients hide it from the transcript like a subagent/ACP
@@ -973,6 +1030,7 @@ export function handleListMessages({
       backgroundEventNotification,
       backgroundToolCompletion,
       systemCard,
+      providerError,
       slackMessage,
       clientMessageId: msg.clientMessageId ?? undefined,
     };
@@ -1050,9 +1108,10 @@ export function handleListMessages({
     const attachmentRefs = collectAttachmentRefs(m.content);
     const aligned = alignAttachments(attachmentRefs, msgAttachments);
     msgAttachments = aligned.attachments;
-    const attachmentBlocks = attachmentRefs.map(
-      (_ref, refIdx) => aligned.refIndexToAttachment.get(refIdx) ?? null,
-    );
+    const attachmentBlocks = attachmentRefs.map((_ref, refIdx) => {
+      const att = aligned.refIndexToAttachment.get(refIdx);
+      return att ? toAttachmentBlockRef(att) : null;
+    });
     const rendered = renderHistoryContent(
       m.content,
       attachmentBlocks,
@@ -1129,7 +1188,10 @@ export function handleListMessages({
     );
     for (const att of msgAttachments) {
       if (!existingAttachmentIds.has(att.id)) {
-        contentBlocks.push({ type: "attachment", attachment: att });
+        contentBlocks.push({
+          type: "attachment",
+          attachment: toAttachmentBlockRef(att),
+        });
       }
     }
 
@@ -1169,6 +1231,8 @@ export function handleListMessages({
       ...(m.backgroundToolCompletion
         ? { backgroundToolCompletion: m.backgroundToolCompletion }
         : {}),
+      ...(m.systemCard ? { systemCard: true } : {}),
+      ...(m.providerError ? { providerError: m.providerError } : {}),
       ...(m.slackMessage ? { slackMessage: m.slackMessage } : {}),
     };
   });
@@ -1387,11 +1451,16 @@ export async function handleSendMessage(
     // handoff to prime a proactive assistant greeting without showing the
     // triggering user message. Honored on the standard send path only.
     hidden?: boolean;
+    // True when the turn was auto-sent on the user's behalf rather than typed.
+    // Independent of `hidden`: the research prompt is visible AND scripted,
+    // the kickoff greeting is hidden AND scripted. Absent means UNKNOWN.
+    scripted?: boolean;
     bypassSecretCheck?: boolean;
     hostHomeDir?: string;
     hostUsername?: string;
     clientTimezone?: unknown;
     clientOs?: unknown;
+    visibleAppId?: unknown;
     clientId?: string;
     clientMessageId?: string;
     inferenceProfile?: string | null;
@@ -1519,6 +1588,16 @@ export async function handleSendMessage(
     typeof body.clientOs === "string"
       ? (parseClientOs(body.clientOs) ?? undefined)
       : undefined;
+  // App the client has open on screen. Purely view state: it drives the
+  // per-turn `visible_app:` context line and nothing else, so an id that no
+  // longer resolves (deleted app) is dropped silently during assembly rather
+  // than failing the send. Traversal-shaped ids are rejected here so nothing
+  // downstream has to treat the value as a path segment.
+  const visibleAppId =
+    typeof body.visibleAppId === "string" &&
+    isSafeVisibleAppId(body.visibleAppId)
+      ? body.visibleAppId
+      : undefined;
 
   // Reject non-string content values (numbers, objects, etc.)
   if (content != null && typeof content !== "string") {
@@ -1679,12 +1758,14 @@ export async function handleSendMessage(
         hostUsername: body.hostUsername,
         ...(clientTimezone ? { clientTimezone } : {}),
         ...(clientOs ? { clientOs } : {}),
+        ...(visibleAppId ? { visibleAppId } : {}),
       } satisfies HostProxyTransportMetadata)
     : ({
         channelId: sourceChannel,
         interfaceId: sourceInterface,
         ...(clientTimezone ? { clientTimezone } : {}),
         ...(clientOs ? { clientOs } : {}),
+        ...(visibleAppId ? { visibleAppId } : {}),
       } satisfies NonHostProxyTransportMetadata);
 
   const conversation = await smDeps.getOrCreateConversation(
@@ -1878,8 +1959,7 @@ export async function handleSendMessage(
   // real first response. Gated behind the `self-intro-greeting` flag (default
   // off); `undefined` (flag off or no names) falls back to the canned path.
   const selfIntroGreetingEnabled =
-    isWakeUp &&
-    isAssistantFeatureFlagEnabled(SELF_INTRO_GREETING_FLAG, getConfig());
+    isWakeUp && isAssistantFeatureFlagEnabled(SELF_INTRO_GREETING_FLAG);
   const selfIntro = selfIntroGreetingEnabled
     ? buildSelfIntroMessage(body.onboarding ?? undefined)
     : undefined;
@@ -2090,6 +2170,13 @@ export async function handleSendMessage(
           // hidden send that lands mid-turn stays hidden when drained —
           // the drain path persists this metadata and skips the echo.
           ...(body.hidden === true ? { hidden: true } : {}),
+          // Same reason: the queue round-trips metadata, not persist options,
+          // so a scripted send that lands mid-turn can only keep its marker
+          // this way. Both booleans forwarded, since false is a real assertion
+          // ("the user typed this"), not an absence.
+          ...(typeof body.scripted === "boolean"
+            ? { scripted: body.scripted }
+            : {}),
         },
         clientMetadata,
       ),
@@ -2232,6 +2319,9 @@ export async function handleSendMessage(
         userMessageInterface: sourceInterface,
         assistantMessageInterface: sourceInterface,
         ...(body.automated === true ? { automated: true } : {}),
+        ...(typeof body.scripted === "boolean"
+          ? { scripted: body.scripted }
+          : {}),
       };
       const persisted = await persistQueuedMessageBody(conversation, {
         content: rawContent,
@@ -2376,7 +2466,9 @@ export async function handleSendMessage(
         });
         publishConversationMessagesChanged(conversationId, originClientId);
         conversation.emitActivityState("thinking", "context_compacting");
-        const result = await conversation.forceCompact();
+        // Same sink the result card below goes out on, so the indicator and
+        // the card can never be delivered to different places.
+        const result = await conversation.forceCompact(broadcastMessage);
         const cardId = await persistCannedAssistantCard({
           conversation,
           conversationId,
@@ -2497,6 +2589,7 @@ export async function handleSendMessage(
         : undefined,
       clientMetadata,
     ),
+    scripted: body.scripted,
     clientMessageId,
   });
 
@@ -3004,6 +3097,12 @@ export const ROUTES: RouteDefinition[] = [
         .describe(
           'Client OS surface ("web" | "ios" | "macos" | "android"), reported separately from `interface`. Drives the per-turn `client_os` context only; does not affect transport/host-proxy capabilities.',
         ),
+      visibleAppId: z
+        .string()
+        .optional()
+        .describe(
+          'Id of the app the client currently has open on screen (app viewer or the app-editing split). Drives the per-turn `visible_app:` context line so the assistant can resolve "the app" to what the user is looking at. View state only: it never affects transport, routing, or tool gating, and is omitted whenever no app is in view.',
+        ),
       clientMessageId: z
         .string()
         .describe(
@@ -3031,6 +3130,12 @@ export const ROUTES: RouteDefinition[] = [
         .describe(
           "When true, persist the user message but suppress it from the UI transcript (it stays in LLM-side history and still drives the turn). Used for machine signals the user never typed (proactive-greeting priming, channel-setup wizard close). Suppression covers the queued path too: a hidden send that lands mid-turn returns { queued: true, requestId } but never appears in list-messages queued snapshots, emits no echo, and does not supersede pending interactions. Honored on the standard send path only — slash-command content bypasses it.",
         ),
+      scripted: z
+        .boolean()
+        .optional()
+        .describe(
+          "When true, this turn was auto-sent on the user's behalf rather than typed by them: onboarding research prompts, the personality rewrite message, research corrections, hidden kickoff greetings, the legacy pre-chat bootstrap. Stamped onto the persisted message and forwarded to turn telemetry, where activation metrics exclude it. Send false for a genuine typed message; OMIT the field only if the client genuinely cannot tell, since absent means UNKNOWN and a wrong false is trusted downstream. Independent of `hidden`: a turn can be visible and scripted (the research prompt) or hidden and scripted (the kickoff greeting).",
+        ),
       onboarding: z
         .object({
           tools: z.array(z.string()),

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

@@ -22,7 +22,6 @@ import {
   assertAcpCredentialFormat,
 } from "../../acp/acp-credentials.js";
 import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
-import { getConfig } from "../../config/loader.js";
 import {
   fetchManagedCatalog,
   type ManagedCredentialDescriptor,
@@ -319,10 +318,7 @@ async function handleCredentialsReveal({ body, headers }: RouteHandlerArgs) {
   }
 
   const forChat = (body as { forChat?: unknown }).forChat === true;
-  if (
-    forChat &&
-    !isAssistantFeatureFlagEnabled("chat-credential-reveal", getConfig())
-  ) {
+  if (forChat && !isAssistantFeatureFlagEnabled("chat-credential-reveal")) {
     throw new BadRequestError(
       "--for-chat requires the chat-credential-reveal feature flag",
     );

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

@@ -4,21 +4,37 @@
  * Exposes document CRUD over HTTP, sharing business logic with the
  * handlers in `daemon/handlers/documents.ts`.
  */
+import { randomUUID } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import { basename, extname } from "node:path";
+
 import { z } from "zod";
 
 import {
   addDocumentConversation,
+  createFileBackedDocument,
   getDocumentById,
+  getDocumentByWorkspacePath,
   getDocumentsForConversation,
+  refreshDocumentContentFromFile,
   saveDocument,
 } from "../../documents/document-store.js";
 import { rawAll } from "../../persistence/raw-query.js";
 import { getLogger } from "../../util/logger.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
 import { renderMarkdownToPDF } from "./document-pdf-renderer.js";
-import { BadRequestError, InternalError, NotFoundError } from "./errors.js";
-import type { RouteDefinition } from "./types.js";
+import {
+  BadRequestError,
+  InternalError,
+  NotFoundError,
+  UnprocessableEntityError,
+} from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
 import { RouteResponse } from "./types.js";
+import {
+  resolveWorkspacePath,
+  toWorkspaceRelativePath,
+} from "./workspace-utils.js";
 
 const log = getLogger("documents-routes");
 
@@ -64,6 +80,164 @@ function listAllDocuments(): Array<{
   }
 }
 
+// ---------------------------------------------------------------------------
+// File-backed documents
+// ---------------------------------------------------------------------------
+
+/** Extensions the document editor round-trips faithfully as markdown. */
+const MARKDOWN_EXTENSIONS = new Set([".md", ".markdown"]);
+
+/** The document payload shape shared by `GET documents/{id}` and its siblings. */
+const documentPayloadSchema = z.object({
+  success: z.boolean(),
+  surfaceId: z.string(),
+  conversationId: z.string(),
+  title: z.string(),
+  content: z.string(),
+  wordCount: z.number(),
+  createdAt: z.number(),
+  updatedAt: z.number(),
+  workspacePath: z
+    .string()
+    .nullable()
+    .describe("Workspace-relative file this document is bound to, or null"),
+});
+
+/**
+ * Resolve a client-supplied workspace path to the markdown file it names.
+ *
+ * Uses the same resolution as the workspace file routes, so a path that
+ * escapes the workspace (traversal, absolute, symlinked out, dot-segment) is
+ * rejected here exactly as it would be there.
+ */
+function resolveWorkspaceMarkdownFile(path: string): {
+  absolutePath: string;
+  relativePath: string;
+} {
+  const resolved = resolveWorkspacePath(path);
+  if (resolved === undefined) {
+    throw new BadRequestError("Invalid path");
+  }
+
+  if (!MARKDOWN_EXTENSIONS.has(extname(resolved).toLowerCase())) {
+    throw new UnprocessableEntityError(
+      "Only markdown files (.md, .markdown) can back a document",
+    );
+  }
+
+  return {
+    absolutePath: resolved,
+    relativePath: toWorkspaceRelativePath(resolved),
+  };
+}
+
+/** Current text of a workspace file, or `null` when it is gone or not a file. */
+function readWorkspaceFileText(absolutePath: string): string | null {
+  try {
+    if (!statSync(absolutePath).isFile()) {
+      return null;
+    }
+    return readFileSync(absolutePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/** Load a document by surface ID for a response, or fail loudly if it vanished. */
+function loadDocumentPayload(surfaceId: string): Record<string, unknown> {
+  const doc = getDocumentById(surfaceId);
+  if (!doc) {
+    throw new InternalError("Document could not be loaded after persisting");
+  }
+  return { success: true, ...doc };
+}
+
+/**
+ * Find or create the document bound to a workspace markdown file.
+ *
+ * The file is the source of truth at open time: when a bound document's stored
+ * content has drifted from the bytes on disk (the file was edited outside the
+ * editor), the row is refreshed from the file before it is returned. Writes go
+ * the other way — the document store writes through to the file.
+ */
+function handleDocumentForWorkspaceFile({
+  body,
+}: RouteHandlerArgs): Record<string, unknown> {
+  const { path, conversationId } = (body ?? {}) as {
+    path?: string;
+    conversationId?: string;
+  };
+
+  if (!path || typeof path !== "string") {
+    throw new BadRequestError("path is required");
+  }
+  if (!conversationId || typeof conversationId !== "string") {
+    throw new BadRequestError("conversationId is required");
+  }
+
+  const { absolutePath, relativePath } = resolveWorkspaceMarkdownFile(path);
+  const existing = getDocumentByWorkspacePath(relativePath);
+  const fileText = readWorkspaceFileText(absolutePath);
+
+  if (fileText === null) {
+    // A bound document whose file is gone is reported distinctly: the client
+    // needs to tell "this file was deleted" apart from "no such file", and the
+    // document must never be used to resurrect the file.
+    if (existing) {
+      throw new NotFoundError(
+        `The file backing this document no longer exists: ${relativePath}`,
+      );
+    }
+    throw new NotFoundError("File not found");
+  }
+
+  if (existing) {
+    // Opening the file from another conversation grants that conversation
+    // access, the same association the link route writes.
+    addDocumentConversation(existing.surfaceId, conversationId);
+
+    if (existing.content !== fileText) {
+      const refresh = refreshDocumentContentFromFile(
+        existing.surfaceId,
+        fileText,
+      );
+      if (!refresh.success) {
+        throw new InternalError(refresh.error);
+      }
+      log.info(
+        { surfaceId: existing.surfaceId, workspacePath: relativePath },
+        "Refreshed file-backed document from disk",
+      );
+    }
+    return loadDocumentPayload(existing.surfaceId);
+  }
+
+  const surfaceId = `doc-${randomUUID()}`;
+  const created = createFileBackedDocument({
+    surfaceId,
+    conversationId,
+    title: basename(relativePath),
+    content: fileText,
+    workspacePath: relativePath,
+  });
+
+  if (!created.success) {
+    // A concurrent request may have won the unique index on workspace_path.
+    const raced = getDocumentByWorkspacePath(relativePath);
+    if (!raced) {
+      throw new InternalError(created.error);
+    }
+    addDocumentConversation(raced.surfaceId, conversationId);
+    return loadDocumentPayload(raced.surfaceId);
+  }
+
+  log.info(
+    { surfaceId, workspacePath: relativePath, conversationId },
+    "Bound workspace file to a new document",
+  );
+  return loadDocumentPayload(surfaceId);
+}
+
 // ---------------------------------------------------------------------------
 // Route definitions
 // ---------------------------------------------------------------------------
@@ -119,16 +293,7 @@ export const ROUTES: RouteDefinition[] = [
     summary: "Get a document",
     description: "Return a single document by surface ID.",
     tags: ["documents"],
-    responseBody: z.object({
-      success: z.boolean(),
-      surfaceId: z.string(),
-      conversationId: z.string(),
-      title: z.string(),
-      content: z.string(),
-      wordCount: z.number(),
-      createdAt: z.number(),
-      updatedAt: z.number(),
-    }),
+    responseBody: documentPayloadSchema,
     handler: ({ pathParams }) => {
       const doc = getDocumentById(pathParams!.id);
       if (!doc) {
@@ -201,6 +366,36 @@ export const ROUTES: RouteDefinition[] = [
     },
   },
 
+  {
+    operationId: "documentForWorkspaceFile",
+    endpoint: "documents/for-workspace-file",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Get or create the document for a workspace markdown file",
+    description:
+      "Return the document bound to a workspace markdown file, creating it on " +
+      "first open. The file is the source of truth at open time: stored " +
+      "content that has drifted from the file is refreshed from disk before " +
+      "the document is returned.",
+    tags: ["documents"],
+    requestBody: z.object({
+      path: z
+        .string()
+        .describe("Workspace-relative path to a .md/.markdown file"),
+      conversationId: z
+        .string()
+        .describe("Conversation the document is opened from"),
+    }),
+    responseBody: documentPayloadSchema,
+    additionalResponses: {
+      "422": { description: "Path is not a markdown file" },
+    },
+    handler: handleDocumentForWorkspaceFile,
+  },
+
   {
     operationId: "linkDocumentConversation",
     endpoint: "documents/:id/conversations",