@jskit-ai/assistant-runtime 0.1.193 → 0.1.194

package/src/server/registerRoutes.js

@@ -1,14 +1,10 @@
 import { AppError } from "@jskit-ai/kernel/server/runtime";
 import { composeSchemaDefinitions } from "@jskit-ai/kernel/shared/validators";
-import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
 import { createJsonApiResourceRouteContract } from "@jskit-ai/http-runtime/shared/validators/jsonApiRouteTransport";
 import {
   ASSISTANT_CONVERSATIONS_TRANSPORT,
   ASSISTANT_CONVERSATION_MESSAGES_TRANSPORT,
-  ASSISTANT_SETTINGS_UPDATE_TRANSPORT,
-  ASSISTANT_SETTINGS_TRANSPORT,
   assistantConversationOutputValidator,
-  assistantConfigResource,
   assistantResource,
   resolveAssistantApiBasePath
 } from "@jskit-ai/assistant-core/shared";
@@ -18,56 +14,20 @@ import {
   setNdjsonHeaders,
   writeNdjson
 } from "@jskit-ai/assistant-core/server";
-import { resolveAssistantSurfaceConfig } from "../shared/assistantSurfaces.js";
 import { actionIds } from "./actionIds.js";
-import { assistantSurfaceRouteParamsValidator } from "./inputSchemas.js";
-
-function requireWorkspaceAssistantRouteParams(workspaceScopeSupport = null) {
-  if (!workspaceScopeSupport) {
-    throw new Error("Assistant workspace routes require workspace server scope support.");
-  }
-
-  return composeSchemaDefinitions(
-    [workspaceScopeSupport.params, assistantSurfaceRouteParamsValidator],
-    {
-      mode: "patch",
-      context: "assistant-runtime workspace surface route params"
-    }
-  );
-}
-
-function readWorkspaceInput(request, requiresWorkspace, workspaceScopeSupport = null) {
-  if (requiresWorkspace !== true) {
-    return {};
-  }
-
-  if (!workspaceScopeSupport) {
-    throw new Error("Assistant workspace routes require workspace server scope support.");
-  }
-
-  return workspaceScopeSupport.buildInputFromRouteParams(request?.input?.params);
-}
-
-function requireAssistantSurface(appConfig = {}, targetSurfaceId = "") {
-  const assistantSurface = resolveAssistantSurfaceConfig(appConfig, targetSurfaceId);
-  if (assistantSurface) {
-    return assistantSurface;
-  }
-
-  throw new AppError(404, "Assistant not found.");
-}
-
-function requireHostSurfaceId(request) {
-  const headerValue = Array.isArray(request?.headers?.["x-jskit-surface"])
-    ? request.headers["x-jskit-surface"][0]
-    : request?.headers?.["x-jskit-surface"];
-  const hostSurfaceId = normalizeSurfaceId(headerValue);
-  if (hostSurfaceId) {
-    return hostSurfaceId;
-  }
-
-  throw new AppError(400, "Assistant surface header x-jskit-surface is required.");
-}
+import {
+  assistantConversationIdInputValidator,
+  assistantConversationGoalBodyValidator,
+  assistantConversationMessageIdInputValidator,
+  assistantConversationReadQueryValidator,
+  conversationConfigureBodyValidator,
+  conversationSelectBodyValidator,
+  conversationReplaceBodyValidator,
+  conversationSendBodyValidator,
+  assistantSurfaceRouteParamsValidator
+} from "./inputSchemas.js";
+import { registerSettingsRoutes } from "./registerSettingsRoutes.js";
+import { requireWorkspaceAssistantRouteParams, resolveRouteRequestState } from "./support/assistantRouteContext.js";
 
 function shouldExposeAppErrorDetails(errorCode = "") {
   return String(errorCode || "").trim() !== "ACTION_PERMISSION_DENIED";
@@ -106,43 +66,6 @@ function sendPreStreamErrorResponse(reply, error) {
   });
 }
 
-function resolveRouteRequestState(
-  request,
-  {
-    resolveCurrentAppConfig = () => ({}),
-    kind = "runtime",
-    requiresWorkspace = false,
-    workspaceScopeSupport = null
-  } = {}
-) {
-  const appConfig = resolveCurrentAppConfig();
-  const targetSurfaceId = normalizeSurfaceId(request?.input?.params?.surfaceId);
-  const assistantSurface = requireAssistantSurface(appConfig, targetSurfaceId);
-  const hostSurfaceId = requireHostSurfaceId(request);
-  const expectsWorkspace = kind === "settings"
-    ? assistantSurface.settingsSurfaceRequiresWorkspace
-    : assistantSurface.runtimeSurfaceRequiresWorkspace;
-  const expectedHostSurfaceId = kind === "settings"
-    ? assistantSurface.settingsSurfaceId
-    : assistantSurface.targetSurfaceId;
-
-  if (expectsWorkspace !== (requiresWorkspace === true)) {
-    throw new AppError(404, "Assistant route not found.");
-  }
-  if (hostSurfaceId !== expectedHostSurfaceId) {
-    throw new AppError(403, "Assistant route is not available on this surface.");
-  }
-
-  return Object.freeze({
-    assistantSurface,
-    hostSurfaceId,
-    actionInput: Object.freeze({
-      targetSurfaceId: assistantSurface.targetSurfaceId,
-      ...readWorkspaceInput(request, requiresWorkspace, workspaceScopeSupport)
-    })
-  });
-}
-
 function buildChatStreamActionInput(routeInput = {}, requestBody = {}) {
   const actionInput = {
     ...routeInput,
@@ -159,15 +82,6 @@ function buildChatStreamActionInput(routeInput = {}, requestBody = {}) {
   return actionInput;
 }
 
-function resolveAssistantSettingsRecordId(record = {}) {
-  const scopeKey = String(record?.scopeKey || "").trim();
-  if (!scopeKey) {
-    throw new Error("Assistant settings JSON:API response requires scopeKey.");
-  }
-
-  return scopeKey;
-}
-
 function resolveAssistantConversationMessagesRecordId(record = {}) {
   const conversationId = String(record?.conversation?.id || "").trim();
   if (!conversationId) {
@@ -177,98 +91,6 @@ function resolveAssistantConversationMessagesRecordId(record = {}) {
   return conversationId;
 }
 
-function registerSettingsRoutes(
-  router,
-  resolveCurrentAppConfig,
-  { requiresWorkspace = false, workspaceScopeSupport = null } = {}
-) {
-  const routeBase = resolveAssistantApiBasePath({
-    requiresWorkspace
-  });
-  const visibility = requiresWorkspace ? "workspace" : "public";
-  const routePath = `${routeBase}/:surfaceId/settings`;
-  const params = requiresWorkspace === true
-    ? requireWorkspaceAssistantRouteParams(workspaceScopeSupport)
-    : assistantSurfaceRouteParamsValidator;
-
-  router.register(
-    "GET",
-    routePath,
-    {
-      auth: "required",
-      visibility,
-      params,
-      meta: {
-        tags: ["assistant", "settings"],
-        summary: "Get assistant settings."
-      },
-      ...createJsonApiResourceRouteContract({
-        ...ASSISTANT_SETTINGS_TRANSPORT,
-        output: assistantConfigResource.operations.view.output,
-        outputKind: "record",
-        getRecordId: resolveAssistantSettingsRecordId
-      })
-    },
-    async function assistantSettingsReadRoute(request, reply) {
-      const routeState = resolveRouteRequestState(request, {
-        resolveCurrentAppConfig,
-        kind: "settings",
-        requiresWorkspace,
-        workspaceScopeSupport
-      });
-
-      const response = await request.executeAction({
-        actionId: actionIds.settingsRead,
-        surface: routeState.hostSurfaceId,
-        input: routeState.actionInput
-      });
-
-      reply.code(200).send(response);
-    }
-  );
-
-  router.register(
-    "PATCH",
-    routePath,
-    {
-      auth: "required",
-      visibility,
-      params,
-      meta: {
-        tags: ["assistant", "settings"],
-        summary: "Update assistant settings."
-      },
-      ...createJsonApiResourceRouteContract({
-        ...ASSISTANT_SETTINGS_UPDATE_TRANSPORT,
-        body: assistantConfigResource.operations.patch.body,
-        output: assistantConfigResource.operations.patch.output,
-        outputKind: "record",
-        getRecordId: resolveAssistantSettingsRecordId,
-        includeValidation400: true
-      })
-    },
-    async function assistantSettingsPatchRoute(request, reply) {
-      const routeState = resolveRouteRequestState(request, {
-        resolveCurrentAppConfig,
-        kind: "settings",
-        requiresWorkspace,
-        workspaceScopeSupport
-      });
-
-      const response = await request.executeAction({
-        actionId: actionIds.settingsUpdate,
-        surface: routeState.hostSurfaceId,
-        input: {
-          ...routeState.actionInput,
-          patch: request.input.body
-        }
-      });
-
-      reply.code(200).send(response);
-    }
-  );
-}
-
 function registerRuntimeRoutes(
   router,
   resolveCurrentAppConfig,
@@ -487,27 +309,227 @@ function registerRuntimeRoutes(
   );
 }
 
-function registerRoutes(router, { config = {}, workspaceScopeSupport = null } = {}) {
+function registerConversationRoutes(
+  router,
+  resolveCurrentAppConfig,
+  { requiresWorkspace = false, workspaceScopeSupport = null, conversationDataSchema = null,
+    conversationConfigurationSchema = null, conversationSelectionSchema = null, conversationReplacementSchema = null } = {}
+) {
+  const routeBase = `${resolveAssistantApiBasePath({ requiresWorkspace })}/:surfaceId/conversations/:conversationId`;
+  const visibility = requiresWorkspace ? "workspace" : "public";
+  const surfaceParams = requiresWorkspace
+    ? requireWorkspaceAssistantRouteParams(workspaceScopeSupport)
+    : assistantSurfaceRouteParamsValidator;
+  const params = composeSchemaDefinitions([surfaceParams, assistantConversationIdInputValidator], {
+    mode: "patch",
+    context: "assistant-runtime conversation route params"
+  });
+
+  router.register("GET", routeBase, {
+    auth: "required", visibility, params,
+    query: assistantConversationReadQueryValidator,
+    meta: { tags: ["assistant"], summary: "Read assistant conversation state." }
+  }, async function assistantConversationReadRoute(request, reply) {
+    const routeState = resolveRouteRequestState(request, {
+      resolveCurrentAppConfig, requiresWorkspace, workspaceScopeSupport
+    });
+    const input = { ...routeState.actionInput, conversationId: request.input.params.conversationId };
+    for (const key of ["beforeTurnId", "limit"]) {
+      if (Object.hasOwn(request.input.query || {}, key)) input[key] = request.input.query[key];
+    }
+    const response = await request.executeAction({
+      actionId: actionIds.conversationRead,
+      surface: routeState.hostSurfaceId,
+      input
+    });
+    reply.code(200).send(response);
+  });
+
+  router.register("POST", `${routeBase}/messages`, {
+    auth: "required", visibility, params,
+    body: conversationSendBodyValidator(conversationDataSchema),
+    meta: { tags: ["assistant"], summary: "Send an assistant conversation message." }
+  }, async function assistantConversationSendRoute(request, reply) {
+    const routeState = resolveRouteRequestState(request, {
+      resolveCurrentAppConfig, requiresWorkspace, workspaceScopeSupport
+    });
+    const body = request.input.body;
+    const response = await request.executeAction({
+      actionId: actionIds.conversationSend,
+      surface: routeState.hostSurfaceId,
+      input: {
+        ...routeState.actionInput,
+        conversationId: request.input.params.conversationId,
+        messageId: body.messageId,
+        text: body.text,
+        ...(conversationDataSchema && Object.hasOwn(body, "data") ? { data: body.data } : {}),
+        ...(Object.hasOwn(body, "attachmentIds") ? { attachmentIds: body.attachmentIds } : {}),
+        ...(Object.hasOwn(body, "steer") ? { steer: body.steer } : {})
+      }
+    });
+    reply.code(202).send(response);
+  });
+
+  router.register("POST", `${routeBase}/cancel`, {
+    auth: "required", visibility, params,
+    meta: { tags: ["assistant"], summary: "Cancel the active assistant conversation turn." }
+  }, async function assistantConversationCancelRoute(request, reply) {
+    const routeState = resolveRouteRequestState(request, {
+      resolveCurrentAppConfig, requiresWorkspace, workspaceScopeSupport
+    });
+    const response = await request.executeAction({
+      actionId: actionIds.conversationCancel,
+      surface: routeState.hostSurfaceId,
+      input: { ...routeState.actionInput, conversationId: request.input.params.conversationId }
+    });
+    reply.code(200).send(response);
+  });
+
+  router.register("POST", `${routeBase}/deliveries/:messageId/inspect`, {
+    auth: "required", visibility,
+    params: composeSchemaDefinitions([params, assistantConversationMessageIdInputValidator], {
+      mode: "patch", context: "assistant-runtime conversation delivery inspection route params"
+    }),
+    meta: { tags: ["assistant"], summary: "Inspect assistant message delivery without resubmitting it." }
+  }, async function assistantConversationInspectDeliveryRoute(request, reply) {
+    const routeState = resolveRouteRequestState(request, {
+      resolveCurrentAppConfig, requiresWorkspace, workspaceScopeSupport
+    });
+    const response = await request.executeAction({
+      actionId: actionIds.conversationInspectDelivery,
+      surface: routeState.hostSurfaceId,
+      input: { ...routeState.actionInput, conversationId: request.input.params.conversationId,
+        messageId: request.input.params.messageId }
+    });
+    reply.code(200).send(response);
+  });
+
+  for (const method of ["GET", "POST"]) {
+    router.register(method, `${routeBase}/goal`, {
+      auth: "required", visibility, params,
+      ...(method === "POST" ? { body: assistantConversationGoalBodyValidator } : {}),
+      meta: { tags: ["assistant"], summary: method === "GET" ? "Read the current conversation goal." : "Update the conversation goal." }
+    }, async function assistantConversationGoalRoute(request, reply) {
+      const routeState = resolveRouteRequestState(request, {
+        resolveCurrentAppConfig, requiresWorkspace, workspaceScopeSupport
+      });
+      const input = { ...routeState.actionInput, conversationId: request.input.params.conversationId };
+      if (method === "POST") {
+        for (const key of ["action", "expectedSegmentId", "expectedGoalId", "messageId", "objective", "tokenBudget", "attachmentIds"]) {
+          if (Object.hasOwn(request.input.body, key)) input[key] = request.input.body[key];
+        }
+      }
+      const response = await request.executeAction({
+        actionId: method === "GET" ? actionIds.conversationGoalRead : actionIds.conversationGoalUpdate,
+        surface: routeState.hostSurfaceId, input
+      });
+      reply.code(response === null ? 204 : 200).send(response);
+    });
+  }
+
+  if (conversationConfigurationSchema) {
+    router.register("PATCH", `${routeBase}/configuration`, {
+      auth: "required", visibility, params,
+      body: conversationConfigureBodyValidator(conversationConfigurationSchema),
+      meta: { tags: ["assistant"], summary: "Apply the application's declared conversation settings." }
+    }, async function assistantConversationConfigureRoute(request, reply) {
+      const routeState = resolveRouteRequestState(request, {
+        resolveCurrentAppConfig, requiresWorkspace, workspaceScopeSupport
+      });
+      const response = await request.executeAction({
+        actionId: actionIds.conversationConfigure,
+        surface: routeState.hostSurfaceId,
+        input: { ...routeState.actionInput, conversationId: request.input.params.conversationId,
+          configuration: request.input.body.configuration }
+      });
+      reply.code(200).send(response);
+    });
+  }
+
+  if (conversationSelectionSchema) {
+    router.register("POST", `${routeBase}/selection`, {
+      auth: "required", visibility, params,
+      body: conversationSelectBodyValidator(conversationSelectionSchema),
+      meta: { tags: ["assistant"], summary: "Apply an authorized application conversation selection." }
+    }, async function assistantConversationSelectRoute(request, reply) {
+      const routeState = resolveRouteRequestState(request, {
+        resolveCurrentAppConfig, requiresWorkspace, workspaceScopeSupport
+      });
+      const response = await request.executeAction({
+        actionId: actionIds.conversationSelect,
+        surface: routeState.hostSurfaceId,
+        input: { ...routeState.actionInput, conversationId: request.input.params.conversationId,
+          selection: request.input.body.selection }
+      });
+      reply.code(200).send(response);
+    });
+  }
+
+  if (conversationReplacementSchema) {
+    router.register("POST", `${routeBase}/replacement`, {
+      auth: "required", visibility, params,
+      body: conversationReplaceBodyValidator(conversationReplacementSchema),
+      meta: { tags: ["assistant"], summary: "Apply an authorized application conversation replacement." }
+    }, async function assistantConversationReplaceRoute(request, reply) {
+      const routeState = resolveRouteRequestState(request, {
+        resolveCurrentAppConfig, requiresWorkspace, workspaceScopeSupport
+      });
+      const response = await request.executeAction({
+        actionId: actionIds.conversationReplace,
+        surface: routeState.hostSurfaceId,
+        input: { ...routeState.actionInput, conversationId: request.input.params.conversationId,
+          replacement: request.input.body.replacement }
+      });
+      reply.code(200).send(response);
+    });
+  }
+}
+
+function registerRoutes(router, {
+  config = {},
+  workspaceScopeSupport = null,
+  conversationRuntime = null,
+  conversationAccess = null,
+  conversationDataSchema = null,
+  conversationConfigurationSchema = null,
+  conversationSelectionSchema = null,
+  conversationReplacementSchema = null,
+  assistantConfigService = null
+} = {}) {
   if (!router || typeof router.register !== "function") {
     throw new Error("registerRoutes requires an HTTP router.");
   }
+  if (conversationRuntime && typeof conversationRuntime.open !== "function") {
+    throw new TypeError("Assistant conversation routes require conversationRuntime.open().");
+  }
   const resolveCurrentAppConfig = () => config;
+  const registerAssistantRuntimeRoutes = conversationRuntime ? registerConversationRoutes : registerRuntimeRoutes;
+  const runtimeRouter = conversationRuntime && conversationAccess ? conversationAccess.router : router;
+  const includeSettings = !conversationRuntime || Boolean(assistantConfigService);
 
-  registerSettingsRoutes(router, resolveCurrentAppConfig, {
+  if (includeSettings) registerSettingsRoutes(router, resolveCurrentAppConfig, {
     requiresWorkspace: false
   });
-  registerRuntimeRoutes(router, resolveCurrentAppConfig, {
-    requiresWorkspace: false
+  registerAssistantRuntimeRoutes(runtimeRouter, resolveCurrentAppConfig, {
+    requiresWorkspace: false,
+    conversationDataSchema,
+    conversationConfigurationSchema,
+    conversationSelectionSchema,
+    conversationReplacementSchema
   });
 
   if (workspaceScopeSupport) {
-    registerSettingsRoutes(router, resolveCurrentAppConfig, {
+    if (includeSettings) registerSettingsRoutes(router, resolveCurrentAppConfig, {
       requiresWorkspace: true,
       workspaceScopeSupport
     });
-    registerRuntimeRoutes(router, resolveCurrentAppConfig, {
+    registerAssistantRuntimeRoutes(runtimeRouter, resolveCurrentAppConfig, {
       requiresWorkspace: true,
-      workspaceScopeSupport
+      workspaceScopeSupport,
+      conversationDataSchema,
+      conversationConfigurationSchema,
+      conversationSelectionSchema,
+      conversationReplacementSchema
     });
   }
 }

package/src/server/registerSettingsRoutes.js

@@ -0,0 +1,113 @@
+import { createJsonApiResourceRouteContract } from "@jskit-ai/http-runtime/shared/validators/jsonApiRouteTransport";
+import {
+  ASSISTANT_SETTINGS_UPDATE_TRANSPORT,
+  ASSISTANT_SETTINGS_TRANSPORT,
+  assistantConfigResource,
+  resolveAssistantApiBasePath
+} from "@jskit-ai/assistant-core/shared";
+import { actionIds } from "./actionIds.js";
+import { assistantSurfaceRouteParamsValidator } from "./inputSchemas.js";
+import { requireWorkspaceAssistantRouteParams, resolveRouteRequestState } from "./support/assistantRouteContext.js";
+
+function resolveAssistantSettingsRecordId(record = {}) {
+  const scopeKey = String(record?.scopeKey || "").trim();
+  if (!scopeKey) {
+    throw new Error("Assistant settings JSON:API response requires scopeKey.");
+  }
+
+  return scopeKey;
+}
+
+function registerSettingsRoutes(
+  router,
+  resolveCurrentAppConfig,
+  { requiresWorkspace = false, workspaceScopeSupport = null } = {}
+) {
+  const routeBase = resolveAssistantApiBasePath({
+    requiresWorkspace
+  });
+  const visibility = requiresWorkspace ? "workspace" : "public";
+  const routePath = `${routeBase}/:surfaceId/settings`;
+  const params = requiresWorkspace === true
+    ? requireWorkspaceAssistantRouteParams(workspaceScopeSupport)
+    : assistantSurfaceRouteParamsValidator;
+
+  router.register(
+    "GET",
+    routePath,
+    {
+      auth: "required",
+      visibility,
+      params,
+      meta: {
+        tags: ["assistant", "settings"],
+        summary: "Get assistant settings."
+      },
+      ...createJsonApiResourceRouteContract({
+        ...ASSISTANT_SETTINGS_TRANSPORT,
+        output: assistantConfigResource.operations.view.output,
+        outputKind: "record",
+        getRecordId: resolveAssistantSettingsRecordId
+      })
+    },
+    async function assistantSettingsReadRoute(request, reply) {
+      const routeState = resolveRouteRequestState(request, {
+        resolveCurrentAppConfig,
+        kind: "settings",
+        requiresWorkspace,
+        workspaceScopeSupport
+      });
+
+      const response = await request.executeAction({
+        actionId: actionIds.settingsRead,
+        surface: routeState.hostSurfaceId,
+        input: routeState.actionInput
+      });
+
+      reply.code(200).send(response);
+    }
+  );
+
+  router.register(
+    "PATCH",
+    routePath,
+    {
+      auth: "required",
+      visibility,
+      params,
+      meta: {
+        tags: ["assistant", "settings"],
+        summary: "Update assistant settings."
+      },
+      ...createJsonApiResourceRouteContract({
+        ...ASSISTANT_SETTINGS_UPDATE_TRANSPORT,
+        body: assistantConfigResource.operations.patch.body,
+        output: assistantConfigResource.operations.patch.output,
+        outputKind: "record",
+        getRecordId: resolveAssistantSettingsRecordId,
+        includeValidation400: true
+      })
+    },
+    async function assistantSettingsPatchRoute(request, reply) {
+      const routeState = resolveRouteRequestState(request, {
+        resolveCurrentAppConfig,
+        kind: "settings",
+        requiresWorkspace,
+        workspaceScopeSupport
+      });
+
+      const response = await request.executeAction({
+        actionId: actionIds.settingsUpdate,
+        surface: routeState.hostSurfaceId,
+        input: {
+          ...routeState.actionInput,
+          patch: request.input.body
+        }
+      });
+
+      reply.code(200).send(response);
+    }
+  );
+}
+
+export { registerSettingsRoutes };

package/src/server/repositories/conversationsRepository.js

@@ -1,4 +1,4 @@
-import { createWithTransaction, normalizeDbRecordId, runInTransaction } from "@jskit-ai/database-runtime/shared/repositoryOptions";
+import { applyForUpdate, createWithTransaction, normalizeDbRecordId, runInTransaction } from "@jskit-ai/database-runtime/shared/repositoryOptions";
 import { normalizeSurfaceId } from "@jskit-ai/kernel/shared/surface/registry";
 import { normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import {
@@ -88,9 +88,15 @@ function createRepository(knex) {
     }
 
     const client = options?.trx || knex;
-    const row = await createConversationBaseQuery(client)
-      .where("c.id", normalizedConversationId)
-      .first();
+    if (options.forUpdate === true) {
+      if (!options.trx) throw new TypeError("Locking a conversation requires its database transaction.");
+      // Acquire the write reservation before reading, including SQLite where
+      // SELECT FOR UPDATE is not supported. This does not change row contents.
+      await client(assistantRuntimeConfig.conversationsTable).where({ id: normalizedConversationId })
+        .update({ id: normalizedConversationId });
+    }
+    const query = createConversationBaseQuery(client).where("c.id", normalizedConversationId);
+    const row = await applyForUpdate(query, options).first();
 
     return row ? mapConversationRow(row) : null;
   }
@@ -108,12 +114,13 @@ function createRepository(knex) {
     }
 
     const client = options?.trx || knex;
+    if (options.forUpdate === true) await findById(normalizedConversationId, options);
     const query = createConversationBaseQuery(client)
       .where("c.id", normalizedConversationId)
       .where("c.created_by_user_id", normalizedActorUserId)
       .where("c.surface_id", normalizedSurfaceId);
     applyWorkspaceScope(query, "c.workspace_id", workspaceId);
-    const row = await query.first();
+    const row = await applyForUpdate(query, options).first();
 
     return row ? mapConversationRow(row) : null;
   }

package/src/server/repositories/messagesRepository.js

@@ -140,6 +140,17 @@ function createRepository(knex) {
     return Number.isFinite(total) && total > 0 ? total : 0;
   }
 
+  async function updateById(messageId, patch = {}, options = {}) {
+    const id = normalizeInputRecordId(messageId);
+    if (!id) return null;
+    const client = options?.trx || knex;
+    const update = {};
+    if (Object.hasOwn(patch, "contentText")) update.content_text = patch.contentText == null ? null : String(patch.contentText);
+    if (Object.hasOwn(patch, "metadata")) update.metadata_json = stringifyJsonObject(patch.metadata);
+    if (Object.keys(update).length) await client(assistantRuntimeConfig.messagesTable).where({ id }).update(update);
+    return findById(id, { trx: client });
+  }
+
   async function listByConversationScope(conversationId, { workspaceId = null } = {}, pagination = {}, options = {}) {
     const normalizedConversationId = normalizeInputRecordId(conversationId);
     if (!normalizedConversationId) {
@@ -171,6 +182,7 @@ function createRepository(knex) {
     withTransaction,
     findById,
     create,
+    updateById,
     countByConversationScope,
     listByConversationScope,
     transaction