@btst/stack 3.0.0-rc.1 → 3.0.0-rc.3

package/dist/packages/stack/src/plugins/ai-chat/api/operations.mjs

@@ -0,0 +1,1333 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { OperationHttpError, defineOperation, definePassthroughOperation } from '@btst/stack/plugins/api';
+import { convertToModelMessages, streamText, stepCountIs } from 'ai';
+import { z } from 'zod';
+import { aiChatPermissions } from '../../../../../../plugins/ai-chat/permissions.mjs';
+import { chatRequestSchema, updateConversationSchema, createConversationSchema } from '../schemas.mjs';
+import { getAllConversations, getConversationById } from './getters.mjs';
+import { BUILT_IN_PAGE_TOOL_SCHEMAS, BUILT_IN_PAGE_TOOL_ROUTE_ALLOWLIST } from './page-tools.mjs';
+import { serializeMessage, serializeConversation } from './serializers.mjs';
+
+const ConversationOperationInputSchema = z.object({ id: z.string() });
+const UpdateConversationOperationInputSchema = z.object({
+  id: z.string(),
+  data: updateConversationSchema
+});
+const ChatOperationInputSchema = chatRequestSchema.extend({
+  trustedUserId: z.string().optional()
+});
+const EmptyInputSchema = z.object({});
+const AI_CHAT_OPERATION_INVENTORY = Object.freeze({
+  startStream: Object.freeze({
+    http: "POST /chat",
+    request: "forRequest(request).operations.aiChat.startStream",
+    trusted: "trusted.aiChat.startStream",
+    ui: Object.freeze([
+      "composer",
+      "edit",
+      "retry",
+      "attachment",
+      "tool-result"
+    ]),
+    semantics: Object.freeze([
+      "stream.start",
+      "conversation.create",
+      "message.send",
+      "message.edit",
+      "message.retry",
+      "attachment.send",
+      "tool.activate"
+    ]),
+    publicSemantics: Object.freeze([
+      "stream.start",
+      "message.send",
+      "message.edit",
+      "message.retry",
+      "attachment.send",
+      "tool.activate"
+    ]),
+    publicWhenConfigured: true
+  }),
+  listConversations: Object.freeze({
+    http: "GET /chat/conversations",
+    request: "forRequest(request).operations.aiChat.listConversations",
+    trusted: "trusted.aiChat.listConversations",
+    ui: Object.freeze(["conversation sidebar"]),
+    semantics: Object.freeze(["conversation.read"]),
+    publicWhenConfigured: false
+  }),
+  getConversation: Object.freeze({
+    http: "GET /chat/conversations/:id",
+    request: "forRequest(request).operations.aiChat.getConversation",
+    trusted: "trusted.aiChat.getConversation",
+    ui: Object.freeze(["conversation route"]),
+    semantics: Object.freeze(["conversation.read"]),
+    publicWhenConfigured: false
+  }),
+  createConversation: Object.freeze({
+    http: "POST /chat/conversations",
+    request: "forRequest(request).operations.aiChat.createConversation",
+    trusted: "trusted.aiChat.createConversation",
+    ui: Object.freeze(["new chat"]),
+    semantics: Object.freeze(["conversation.create"]),
+    publicWhenConfigured: false
+  }),
+  updateConversation: Object.freeze({
+    http: "PUT /chat/conversations/:id",
+    request: "forRequest(request).operations.aiChat.updateConversation",
+    trusted: "trusted.aiChat.updateConversation",
+    ui: Object.freeze(["rename conversation"]),
+    semantics: Object.freeze(["conversation.update"]),
+    publicWhenConfigured: false
+  }),
+  deleteConversation: Object.freeze({
+    http: "DELETE /chat/conversations/:id",
+    request: "forRequest(request).operations.aiChat.deleteConversation",
+    trusted: "trusted.aiChat.deleteConversation",
+    ui: Object.freeze(["delete conversation"]),
+    semantics: Object.freeze(["conversation.delete"]),
+    publicWhenConfigured: false
+  })
+});
+const AI_CHAT_RAW_ESCAPE_HATCH_INVENTORY = Object.freeze([
+  "@btst/stack/plugins/ai-chat/api#getAllConversations",
+  "@btst/stack/plugins/ai-chat/api#getConversationById"
+]);
+class AiChatOperationError extends OperationHttpError {
+  constructor(statusCode, message, code) {
+    super(statusCode, message, code);
+    this.name = "AiChatOperationError";
+  }
+}
+async function runBeforeHook(hook, defaultMessage) {
+  try {
+    return await hook();
+  } catch (cause) {
+    if (cause instanceof AiChatOperationError) throw cause;
+    throw new AiChatOperationError(
+      403,
+      cause instanceof Error ? cause.message : defaultMessage,
+      "HOOK_DENIED"
+    );
+  }
+}
+function normalizeError(error, fallback) {
+  if (error instanceof Error) return error;
+  return new Error(typeof error === "string" ? error : fallback, {
+    cause: error
+  });
+}
+function requestFields(request) {
+  return request ? { request, headers: request.headers } : {};
+}
+function hookContext(context, fields = {}) {
+  return Object.freeze({
+    ...context,
+    ...requestFields(context.request),
+    ...fields
+  });
+}
+async function notifyError(hook, error, context, fields) {
+  await hook?.(
+    normalizeError(error, "AI Chat operation failed"),
+    hookContext(context, fields)
+  );
+}
+function publicConversation(conversation) {
+  return serializeConversation(conversation);
+}
+function conversationResult(conversation) {
+  return {
+    ...publicConversation(conversation),
+    messages: conversation.messages.map(serializeMessage)
+  };
+}
+function snapshotConversation(conversation) {
+  return {
+    id: conversation.id,
+    ...conversation.userId ? { userId: conversation.userId } : {},
+    title: conversation.title,
+    createdAt: conversation.createdAt.getTime(),
+    updatedAt: conversation.updatedAt.getTime(),
+    messages: (conversation.messages ?? []).map((message) => ({
+      id: message.id,
+      conversationId: message.conversationId,
+      role: message.role,
+      content: message.content,
+      createdAt: message.createdAt.getTime()
+    }))
+  };
+}
+function sameSnapshot(conversation, expected) {
+  if (!conversation || !expected)
+    return conversation === null && expected === null;
+  return JSON.stringify(snapshotConversation(conversation)) === JSON.stringify(expected);
+}
+function recordFacts(id, snapshot) {
+  return {
+    conversationId: id,
+    exists: snapshot !== null,
+    ...snapshot?.userId ? { ownerId: snapshot.userId } : {}
+  };
+}
+function textContent(message) {
+  return (message.parts ?? []).filter(
+    (part) => part.type === "text"
+  ).map((part) => part.text).join("");
+}
+function serializedParts(message) {
+  return JSON.stringify(
+    (message.parts ?? []).filter(
+      (part) => part.type === "text" || part.type === "file"
+    )
+  );
+}
+function matchesPersistedUserMessage(message, persisted) {
+  if (persisted.content === serializedParts(message)) return true;
+  const parts = message.parts ?? [];
+  return parts.length === 1 && parts[0]?.type === "text" && persisted.content === parts[0].text;
+}
+function fileParts(messages) {
+  return messages.flatMap(
+    (message) => (message.parts ?? []).filter(
+      (part) => part.type === "file"
+    )
+  );
+}
+function completedToolNames(message) {
+  if (!message) return [];
+  return [
+    ...new Set(
+      (message.parts ?? []).flatMap((part) => {
+        if (!("state" in part) || part.state !== "output-available" && part.state !== "output-error") {
+          return [];
+        }
+        if (part.type === "dynamic-tool" && "toolName" in part) {
+          return typeof part.toolName === "string" ? [part.toolName] : [];
+        }
+        return part.type.startsWith("tool-") ? [part.type.slice(5)] : [];
+      })
+    )
+  ];
+}
+function validateAttachments(messages) {
+  const files = fileParts(messages);
+  if (files.length > 10) {
+    throw new AiChatOperationError(
+      400,
+      "A chat request may include at most 10 attachments.",
+      "TOO_MANY_ATTACHMENTS"
+    );
+  }
+  for (const file of files) {
+    if (typeof file.url !== "string" || !file.url.startsWith("https://") && !file.url.startsWith("http://") && !file.url.startsWith("data:")) {
+      throw new AiChatOperationError(
+        400,
+        "Attachment URLs must use http, https, or data URLs.",
+        "INVALID_ATTACHMENT_URL"
+      );
+    }
+    if (file.url.startsWith("data:") && file.url.length > 14e6) {
+      throw new AiChatOperationError(
+        413,
+        "Inline attachments must not exceed 10 MB.",
+        "ATTACHMENT_TOO_LARGE"
+      );
+    }
+  }
+}
+function structuralToolNames(input, config) {
+  if (!config.enablePageTools || !input.availableTools?.length) return [];
+  const consumerSchemas = config.clientToolSchemas ?? {};
+  return [...new Set(input.availableTools)].filter((name) => {
+    if (name in BUILT_IN_PAGE_TOOL_SCHEMAS) {
+      const allowlist = BUILT_IN_PAGE_TOOL_ROUTE_ALLOWLIST[name];
+      return Boolean(
+        allowlist && input.routeName && allowlist.includes(input.routeName)
+      );
+    }
+    return name in consumerSchemas;
+  });
+}
+function buildTools(names, config) {
+  const pageTools = Object.fromEntries(
+    names.map((name) => [
+      name,
+      BUILT_IN_PAGE_TOOL_SCHEMAS[name] ?? config.clientToolSchemas?.[name]
+    ])
+  );
+  return Object.keys(pageTools).length > 0 ? { ...pageTools, ...config.tools } : config.tools;
+}
+function determineIntent(messages, snapshot) {
+  const last = messages[messages.length - 1];
+  if (!last) return { intent: "send" };
+  if (last.role !== "user" && last.role !== "assistant") {
+    throw new AiChatOperationError(
+      400,
+      "A chat request must end with a user or assistant message.",
+      "INVALID_MESSAGE_SEQUENCE"
+    );
+  }
+  if (!snapshot) return { intent: "send" };
+  const incomingUsers = messages.filter((message) => message.role === "user");
+  const persistedUsers = snapshot.messages.filter(
+    (message) => message.role === "user"
+  );
+  const sharedUserCount = Math.min(incomingUsers.length, persistedUsers.length);
+  for (let index = 0; index < sharedUserCount; index++) {
+    const incoming = incomingUsers[index];
+    const persisted = persistedUsers[index];
+    if (!incoming || !persisted) continue;
+    const matches = matchesPersistedUserMessage(incoming, persisted);
+    if (matches) continue;
+    if (last.role === "user" && incoming === last && index === incomingUsers.length - 1) {
+      return { intent: "edit", messageId: persisted.id };
+    }
+    throw new AiChatOperationError(
+      409,
+      "The conversation transcript changed before authorization.",
+      "STALE_MESSAGE"
+    );
+  }
+  if (incomingUsers.length > persistedUsers.length) {
+    if (incomingUsers.length === persistedUsers.length + 1 && incomingUsers[incomingUsers.length - 1] === last) {
+      return { intent: "send" };
+    }
+    throw new AiChatOperationError(
+      409,
+      "The conversation transcript changed before authorization.",
+      "STALE_MESSAGE"
+    );
+  }
+  const isToolResult = last.role === "assistant" && completedToolNames(last).length > 0;
+  if (isToolResult && incomingUsers.length !== persistedUsers.length) {
+    throw new AiChatOperationError(
+      409,
+      "The tool continuation no longer follows the latest user message.",
+      "STALE_MESSAGE"
+    );
+  }
+  const target = persistedUsers[incomingUsers.length - 1];
+  if (!target) {
+    throw new AiChatOperationError(
+      400,
+      "Retry requires a persisted message.",
+      "MESSAGE_NOT_FOUND"
+    );
+  }
+  return {
+    intent: isToolResult ? "tool-result" : "retry",
+    messageId: target.id
+  };
+}
+function nextVersion(date) {
+  return new Date(Math.max(Date.now(), date.getTime() + 1));
+}
+const AFFECTED_ROW_KEYS = [
+  "rowCount",
+  "affectedRows",
+  "rowsAffected",
+  "changes",
+  "numUpdatedRows"
+];
+function hasPositiveCount(value) {
+  if (typeof value === "number") return Number.isFinite(value) && value > 0;
+  if (typeof value === "bigint") return value > 0n;
+  return false;
+}
+function didAffectRow(result, expectedId) {
+  if (typeof result === "number" || typeof result === "bigint") {
+    return hasPositiveCount(result);
+  }
+  if (!result || typeof result !== "object") return false;
+  const record = result;
+  if ("count" in record) return hasPositiveCount(record.count);
+  if (Array.isArray(result)) {
+    return result.length > 0 && didAffectRow(result[0], expectedId);
+  }
+  for (const key of AFFECTED_ROW_KEYS) {
+    if (key in record) return hasPositiveCount(record[key]);
+  }
+  if ("meta" in record) {
+    const meta = record.meta;
+    return Boolean(
+      meta && typeof meta === "object" && "changes" in meta && hasPositiveCount(meta.changes)
+    );
+  }
+  return record.id === expectedId;
+}
+const memoryRollbackMarkers = /* @__PURE__ */ new WeakMap();
+function markMemoryRollback(adapter, error) {
+  memoryRollbackMarkers.get(adapter)?.(error);
+}
+function serializeMemoryOperations(adapter) {
+  if (adapter.id !== "memory" || memoryRollbackMarkers.has(adapter)) {
+    return adapter;
+  }
+  const source = { ...adapter };
+  const lockContext = new AsyncLocalStorage();
+  let tail = Promise.resolve();
+  let activeOwner;
+  const withLock = async (run) => {
+    const inherited = lockContext.getStore();
+    if (inherited && inherited.owner === activeOwner) {
+      return run(inherited.adapter);
+    }
+    let release = () => {
+    };
+    const previous = tail;
+    tail = new Promise((resolve) => {
+      release = resolve;
+    });
+    await previous;
+    const owner = {};
+    activeOwner = owner;
+    try {
+      return await lockContext.run(
+        { owner, adapter: source },
+        () => run(source)
+      );
+    } finally {
+      if (activeOwner === owner) activeOwner = void 0;
+      release();
+    }
+  };
+  const serialized = {
+    ...source,
+    create: ((input) => withLock((active) => active.create(input))),
+    findOne: ((input) => withLock((active) => active.findOne(input))),
+    findMany: ((input) => withLock((active) => active.findMany(input))),
+    count: (input) => withLock((active) => active.count(input)),
+    update: ((input) => withLock((active) => active.update(input))),
+    updateMany: (input) => withLock((active) => active.updateMany(input)),
+    delete: ((input) => withLock((active) => active.delete(input))),
+    deleteMany: (input) => withLock((active) => active.deleteMany(input)),
+    consumeOne: ((input) => withLock((active) => active.consumeOne(input))),
+    transaction: ((callback) => withLock((active) => {
+      const context = lockContext.getStore();
+      if (!context)
+        throw new TypeError("Missing AI Chat memory lock context.");
+      if (context.inTransaction) {
+        return callback(active).catch((error) => {
+          context.rollbackOnly = true;
+          context.rollbackError = error;
+          throw error;
+        });
+      }
+      if (!active.transaction) {
+        throw new TypeError("Missing AI Chat memory transaction adapter.");
+      }
+      return active.transaction(
+        (transaction) => lockContext.run(
+          {
+            owner: context.owner,
+            adapter: transaction,
+            inTransaction: true
+          },
+          async () => {
+            const transactionContext = lockContext.getStore();
+            const result = await callback(transaction);
+            if (transactionContext?.rollbackOnly) {
+              throw transactionContext.rollbackError;
+            }
+            return result;
+          }
+        )
+      );
+    }))
+  };
+  Object.assign(adapter, serialized);
+  memoryRollbackMarkers.set(adapter, (error) => {
+    const context = lockContext.getStore();
+    if (!context || context.owner !== activeOwner || !context.inTransaction) {
+      return;
+    }
+    context.rollbackOnly = true;
+    context.rollbackError = error;
+  });
+  return adapter;
+}
+function requireAtomicConversationTransactions(adapter) {
+  if (adapter.id !== "memory" && typeof adapter.options?.adapterConfig.transaction !== "function") {
+    throw new AiChatOperationError(
+      500,
+      "AI Chat conversation writes require an adapter with isolated transaction support.",
+      "ATOMIC_TRANSACTION_REQUIRED"
+    );
+  }
+}
+async function scopedUserId(context, input) {
+  if (context.identity) return context.identity.id;
+  const trustedUserId = input.trustedUserId;
+  if (!context.request && trustedUserId) return trustedUserId;
+  return void 0;
+}
+function assertConversationScope(snapshot, userId, message) {
+  if (userId && snapshot?.userId && snapshot.userId !== userId) {
+    throw new AiChatOperationError(403, message, "FORBIDDEN");
+  }
+}
+function createAiChatOperations(sourceAdapter, config) {
+  const adapter = serializeMemoryOperations(sourceAdapter);
+  const hooks = config.hooks;
+  const conversationSnapshots = /* @__PURE__ */ new WeakMap();
+  const streamPreparations = /* @__PURE__ */ new WeakMap();
+  const scopedUserIds = /* @__PURE__ */ new WeakMap();
+  const pendingRequestedConversationClaims = /* @__PURE__ */ new Set();
+  const pendingConversationMutationClaims = /* @__PURE__ */ new Set();
+  const claimConversationMutation = (conversationId) => {
+    requireAtomicConversationTransactions(adapter);
+    if (pendingConversationMutationClaims.has(conversationId)) {
+      throw new AiChatOperationError(
+        409,
+        "Conversation changed during authorization.",
+        "STALE_CONVERSATION"
+      );
+    }
+    pendingConversationMutationClaims.add(conversationId);
+    return () => pendingConversationMutationClaims.delete(conversationId);
+  };
+  const assertHistoryAvailable = () => {
+    if (config.access === "public") {
+      throw new AiChatOperationError(
+        404,
+        "Conversations are not available in public mode.",
+        "HISTORY_UNAVAILABLE"
+      );
+    }
+  };
+  const listConversations = defineOperation({
+    input: EmptyInputSchema,
+    permission: aiChatPermissions.conversation.read,
+    facts: () => {
+      assertHistoryAvailable();
+      return { scope: "collection" };
+    },
+    before: async (context) => {
+      const userId = await scopedUserId(context, context.input);
+      scopedUserIds.set(context.input, userId);
+      await runBeforeHook(
+        () => hooks?.onBeforeListConversations?.(
+          hookContext(context, { query: context.input })
+        ),
+        "Unauthorized: Cannot list conversations"
+      );
+    },
+    execute: async (context) => {
+      const userId = scopedUserIds.get(context.input);
+      const allConversations = await getAllConversations(adapter, userId);
+      const conversations = (context.request && !userId ? allConversations.filter((conversation) => !conversation.userId) : allConversations).map(publicConversation);
+      await hooks?.onAfterListConversations?.(
+        conversations,
+        hookContext(context, { query: context.input })
+      );
+      return conversations;
+    },
+    onError: ({ error, ...context }) => notifyError(hooks?.onErrorListConversations, error, context, {
+      query: context.input
+    })
+  });
+  const getConversation = defineOperation({
+    input: ConversationOperationInputSchema,
+    permission: aiChatPermissions.conversation.read,
+    facts: async ({ input }) => {
+      assertHistoryAvailable();
+      const conversation = await getConversationById(adapter, input.id);
+      const snapshot = conversation ? snapshotConversation(conversation) : null;
+      conversationSnapshots.set(input, snapshot);
+      return {
+        scope: "record",
+        ...recordFacts(input.id, snapshot)
+      };
+    },
+    before: async (context) => {
+      const userId = await scopedUserId(context, context.input);
+      assertConversationScope(
+        conversationSnapshots.get(context.input) ?? null,
+        context.identity ? void 0 : userId,
+        "Unauthorized: Cannot access this conversation"
+      );
+      const current = await getConversationById(adapter, context.input.id);
+      if (!sameSnapshot(
+        current,
+        conversationSnapshots.get(context.input) ?? null
+      )) {
+        throw new AiChatOperationError(
+          409,
+          "Conversation changed during authorization.",
+          "STALE_CONVERSATION"
+        );
+      }
+      await runBeforeHook(
+        () => hooks?.onBeforeGetConversation?.(
+          context.input.id,
+          hookContext(context, { params: { id: context.input.id } })
+        ),
+        "Unauthorized: Cannot get conversation"
+      );
+    },
+    execute: async (context) => {
+      const conversation = await getConversationById(adapter, context.input.id);
+      if (!conversation) {
+        throw new AiChatOperationError(
+          404,
+          "Conversation not found.",
+          "CONVERSATION_NOT_FOUND"
+        );
+      }
+      if (!sameSnapshot(
+        conversation,
+        conversationSnapshots.get(context.input) ?? null
+      )) {
+        throw new AiChatOperationError(
+          409,
+          "Conversation changed during authorization.",
+          "STALE_CONVERSATION"
+        );
+      }
+      const result = conversationResult(conversation);
+      await hooks?.onAfterGetConversation?.(
+        result,
+        hookContext(context, { params: { id: context.input.id } })
+      );
+      return result;
+    },
+    onError: ({ error, ...context }) => notifyError(hooks?.onErrorGetConversation, error, context, {
+      params: { id: context.input.id }
+    })
+  });
+  const createConversation = defineOperation({
+    input: createConversationSchema,
+    permission: aiChatPermissions.conversation.create,
+    facts: () => {
+      assertHistoryAvailable();
+      return void 0;
+    },
+    before: async (context) => {
+      const userId = await scopedUserId(context, context.input);
+      scopedUserIds.set(context.input, userId);
+      await runBeforeHook(
+        () => hooks?.onBeforeCreateConversation?.(
+          context.input,
+          hookContext(context, { body: context.input })
+        ),
+        "Unauthorized: Cannot create conversation"
+      );
+    },
+    execute: async (context) => {
+      const userId = scopedUserIds.get(context.input);
+      const now = /* @__PURE__ */ new Date();
+      const conversation = await adapter.create({
+        model: "conversation",
+        forceAllowId: Boolean(context.input.id),
+        data: {
+          ...context.input.id ? { id: context.input.id } : {},
+          ...userId ? { userId } : {},
+          title: context.input.title || "New Conversation",
+          createdAt: now,
+          updatedAt: now
+        }
+      });
+      const result = publicConversation(conversation);
+      await hooks?.onAfterCreateConversation?.(
+        result,
+        hookContext(context, { body: context.input })
+      );
+      return result;
+    },
+    onError: ({ error, ...context }) => {
+      markMemoryRollback(adapter, error);
+      return notifyError(hooks?.onErrorCreateConversation, error, context, {
+        body: context.input
+      });
+    }
+  });
+  const updateConversation = defineOperation({
+    input: UpdateConversationOperationInputSchema,
+    permission: aiChatPermissions.conversation.update,
+    facts: async ({ input }) => {
+      assertHistoryAvailable();
+      const conversation = await getConversationById(adapter, input.id);
+      const snapshot = conversation ? snapshotConversation(conversation) : null;
+      conversationSnapshots.set(input, snapshot);
+      return recordFacts(input.id, snapshot);
+    },
+    execute: async (context) => {
+      const expected = conversationSnapshots.get(context.input) ?? null;
+      if (!expected) {
+        throw new AiChatOperationError(
+          404,
+          "Conversation not found.",
+          "CONVERSATION_NOT_FOUND"
+        );
+      }
+      const userId = await scopedUserId(context, context.input);
+      assertConversationScope(
+        expected,
+        context.identity ? void 0 : userId,
+        "Unauthorized: Cannot update this conversation"
+      );
+      const releaseMutation = claimConversationMutation(expected.id);
+      try {
+        return await adapter.transaction(async (tx) => {
+          const current = await getConversationById(tx, context.input.id);
+          if (!sameSnapshot(current, expected)) {
+            throw new AiChatOperationError(
+              409,
+              "Conversation changed during authorization.",
+              "STALE_CONVERSATION"
+            );
+          }
+          await runBeforeHook(
+            () => hooks?.onBeforeUpdateConversation?.(
+              context.input.id,
+              context.input.data,
+              hookContext(context, {
+                body: context.input,
+                params: { id: context.input.id }
+              })
+            ),
+            "Unauthorized: Cannot update conversation"
+          );
+          const updatedAt = nextVersion(new Date(expected.updatedAt));
+          const matched = await tx.updateMany({
+            model: "conversation",
+            where: [
+              {
+                field: "id",
+                value: expected.id,
+                operator: "eq"
+              },
+              {
+                field: "updatedAt",
+                value: new Date(expected.updatedAt),
+                operator: "gte"
+              },
+              {
+                field: "updatedAt",
+                value: new Date(expected.updatedAt),
+                operator: "lte"
+              }
+            ],
+            update: { title: context.input.data.title, updatedAt }
+          });
+          if (!didAffectRow(matched, expected.id)) {
+            throw new AiChatOperationError(
+              409,
+              "Conversation changed during authorization.",
+              "STALE_CONVERSATION"
+            );
+          }
+          const updated = await tx.findOne({
+            model: "conversation",
+            where: [{ field: "id", value: expected.id }]
+          });
+          if (!updated) {
+            throw new AiChatOperationError(
+              404,
+              "Conversation not found.",
+              "CONVERSATION_NOT_FOUND"
+            );
+          }
+          return publicConversation(updated);
+        });
+      } finally {
+        releaseMutation();
+      }
+    },
+    after: (context) => hooks?.onAfterUpdateConversation?.(
+      context.result,
+      hookContext(context, {
+        body: context.input,
+        params: { id: context.input.id }
+      })
+    ),
+    onError: ({ error, ...context }) => {
+      markMemoryRollback(adapter, error);
+      return notifyError(hooks?.onErrorUpdateConversation, error, context, {
+        body: context.input,
+        params: { id: context.input.id }
+      });
+    }
+  });
+  const deleteConversation = defineOperation({
+    input: ConversationOperationInputSchema,
+    permission: aiChatPermissions.conversation.delete,
+    facts: async ({ input }) => {
+      assertHistoryAvailable();
+      const conversation = await getConversationById(adapter, input.id);
+      const snapshot = conversation ? snapshotConversation(conversation) : null;
+      conversationSnapshots.set(input, snapshot);
+      return recordFacts(input.id, snapshot);
+    },
+    execute: async (context) => {
+      const expected = conversationSnapshots.get(context.input) ?? null;
+      if (!expected) {
+        throw new AiChatOperationError(
+          404,
+          "Conversation not found.",
+          "CONVERSATION_NOT_FOUND"
+        );
+      }
+      const userId = await scopedUserId(context, context.input);
+      assertConversationScope(
+        expected,
+        context.identity ? void 0 : userId,
+        "Unauthorized: Cannot delete this conversation"
+      );
+      const releaseMutation = claimConversationMutation(expected.id);
+      try {
+        return await adapter.transaction(async (tx) => {
+          const current = await getConversationById(tx, context.input.id);
+          if (!sameSnapshot(current, expected)) {
+            throw new AiChatOperationError(
+              409,
+              "Conversation changed during authorization.",
+              "STALE_CONVERSATION"
+            );
+          }
+          await runBeforeHook(
+            () => hooks?.onBeforeDeleteConversation?.(
+              context.input.id,
+              hookContext(context, {
+                params: { id: context.input.id }
+              })
+            ),
+            "Unauthorized: Cannot delete conversation"
+          );
+          const deleted = await tx.deleteMany({
+            model: "conversation",
+            where: [
+              {
+                field: "id",
+                value: expected.id,
+                operator: "eq"
+              },
+              {
+                field: "updatedAt",
+                value: new Date(expected.updatedAt),
+                operator: "gte"
+              },
+              {
+                field: "updatedAt",
+                value: new Date(expected.updatedAt),
+                operator: "lte"
+              }
+            ]
+          });
+          if (!didAffectRow(deleted, expected.id)) {
+            throw new AiChatOperationError(
+              409,
+              "Conversation changed during authorization.",
+              "STALE_CONVERSATION"
+            );
+          }
+          return { success: true };
+        });
+      } finally {
+        releaseMutation();
+      }
+    },
+    after: (context) => hooks?.onAfterDeleteConversation?.(
+      context.input.id,
+      hookContext(context, { params: { id: context.input.id } })
+    ),
+    onError: ({ error, ...context }) => {
+      markMemoryRollback(adapter, error);
+      return notifyError(hooks?.onErrorDeleteConversation, error, context, {
+        params: { id: context.input.id }
+      });
+    }
+  });
+  const startStream = definePassthroughOperation({
+    input: ChatOperationInputSchema,
+    permission: aiChatPermissions.stream.start,
+    access: config.access,
+    facts: async ({ input }) => {
+      const uiMessages = input.messages;
+      if (!uiMessages[0]) {
+        throw new AiChatOperationError(
+          400,
+          "At least one message is required.",
+          "EMPTY_CHAT"
+        );
+      }
+      validateAttachments(uiMessages);
+      const conversation = config.access === "authorized" && input.conversationId ? await getConversationById(adapter, input.conversationId) : null;
+      const snapshot = conversation ? snapshotConversation(conversation) : null;
+      const intent = determineIntent(uiMessages, snapshot);
+      const mediaTypes = fileParts(uiMessages).map((file) => file.mediaType);
+      const toolNames = structuralToolNames(input, config);
+      const toolResultNames = completedToolNames(
+        uiMessages[uiMessages.length - 1]
+      );
+      const availableToolNames = /* @__PURE__ */ new Set([
+        ...toolNames,
+        ...Object.keys(config.tools ?? {})
+      ]);
+      if (toolResultNames.some((name) => !availableToolNames.has(name))) {
+        throw new AiChatOperationError(
+          400,
+          "Tool results must match a server-enabled tool.",
+          "INVALID_TOOL_RESULT"
+        );
+      }
+      streamPreparations.set(input, {
+        snapshot,
+        ...intent,
+        mediaTypes,
+        authorizationToolNames: [...availableToolNames],
+        toolNames
+      });
+      return {
+        ...input.conversationId ? { conversationId: input.conversationId } : {},
+        ...snapshot?.userId ? { ownerId: snapshot.userId } : {},
+        createsConversation: snapshot === null,
+        intent: intent.intent
+      };
+    },
+    additionalPermissions: ({ input, facts }) => {
+      const prepared = streamPreparations.get(input);
+      if (!prepared) {
+        throw new AiChatOperationError(
+          500,
+          "Stream authorization context is unavailable.",
+          "AUTHORIZATION_SNAPSHOT_MISSING"
+        );
+      }
+      const requests = [];
+      if (config.access === "authorized" && !prepared.snapshot) {
+        requests.push(aiChatPermissions.conversation.create());
+      }
+      const base = {
+        ...facts.conversationId ? { conversationId: facts.conversationId } : {},
+        ...facts.ownerId ? { ownerId: facts.ownerId } : {}
+      };
+      if (prepared.intent === "send") {
+        requests.push(
+          aiChatPermissions.message.send({
+            ...base,
+            createsConversation: !prepared.snapshot
+          })
+        );
+      } else if (prepared.intent === "edit" && facts.conversationId) {
+        if (!prepared.messageId) {
+          throw new AiChatOperationError(
+            500,
+            "Edit authorization message is unavailable.",
+            "AUTHORIZATION_SNAPSHOT_MISSING"
+          );
+        }
+        requests.push(
+          aiChatPermissions.message.edit({
+            conversationId: facts.conversationId,
+            messageId: prepared.messageId,
+            ...facts.ownerId ? { ownerId: facts.ownerId } : {}
+          })
+        );
+      } else if (prepared.intent === "retry" && facts.conversationId) {
+        if (!prepared.messageId) {
+          throw new AiChatOperationError(
+            500,
+            "Retry authorization message is unavailable.",
+            "AUTHORIZATION_SNAPSHOT_MISSING"
+          );
+        }
+        requests.push(
+          aiChatPermissions.message.retry({
+            conversationId: facts.conversationId,
+            messageId: prepared.messageId,
+            ...facts.ownerId ? { ownerId: facts.ownerId } : {}
+          })
+        );
+      } else if (prepared.intent === "tool-result") {
+        requests.push(
+          aiChatPermissions.message.send({
+            ...base,
+            createsConversation: false
+          })
+        );
+        if (!facts.conversationId || !prepared.messageId) {
+          throw new AiChatOperationError(
+            500,
+            "Tool continuation authorization message is unavailable.",
+            "AUTHORIZATION_SNAPSHOT_MISSING"
+          );
+        }
+        requests.push(
+          aiChatPermissions.message.retry({
+            conversationId: facts.conversationId,
+            messageId: prepared.messageId,
+            ...facts.ownerId ? { ownerId: facts.ownerId } : {}
+          })
+        );
+      }
+      if (prepared.mediaTypes.length > 0) {
+        requests.push(
+          aiChatPermissions.attachment.send({
+            ...base,
+            mediaTypes: [...prepared.mediaTypes]
+          })
+        );
+      }
+      if (prepared.authorizationToolNames.length > 0) {
+        requests.push(
+          aiChatPermissions.tool.activate({
+            ...base,
+            ...input.routeName ? { routeName: input.routeName } : {},
+            toolNames: [...prepared.authorizationToolNames]
+          })
+        );
+      }
+      return requests;
+    },
+    execute: async (context) => {
+      const prepared = streamPreparations.get(context.input);
+      if (!prepared) {
+        throw new AiChatOperationError(
+          500,
+          "Stream authorization context is unavailable.",
+          "AUTHORIZATION_SNAPSHOT_MISSING"
+        );
+      }
+      const uiMessages = context.input.messages;
+      const firstMessage = uiMessages[0];
+      const userId = config.access === "authorized" ? await scopedUserId(context, context.input) : void 0;
+      if (config.access === "authorized") {
+        assertConversationScope(
+          prepared.snapshot,
+          context.identity ? void 0 : userId,
+          "Unauthorized: Cannot access this conversation"
+        );
+      }
+      if (config.access === "authorized" && context.input.conversationId) {
+        const current = await getConversationById(
+          adapter,
+          context.input.conversationId
+        );
+        if (!sameSnapshot(current, prepared.snapshot)) {
+          throw new AiChatOperationError(
+            409,
+            "Conversation changed during authorization.",
+            "STALE_CONVERSATION"
+          );
+        }
+      }
+      const modelMessages = await convertToModelMessages(uiMessages);
+      const pageContext = context.input.pageContext?.trim();
+      const pageSuffix = pageContext ? `
+
+Current page context:
+${pageContext}` : "";
+      const systemContent = config.systemPrompt ? `${config.systemPrompt}${pageSuffix}` : pageSuffix || void 0;
+      const messages = systemContent ? [
+        { role: "system", content: systemContent },
+        ...modelMessages
+      ] : modelMessages;
+      const contextForHooks = hookContext(context, { body: context.input });
+      const enterChatLifecycle = async () => {
+        await runBeforeHook(
+          () => hooks?.onBeforeChat?.(
+            uiMessages.map((message) => ({
+              role: message.role,
+              content: textContent(message)
+            })),
+            contextForHooks
+          ),
+          "Unauthorized: Cannot start chat"
+        );
+        let allowedToolNames = [...prepared.toolNames];
+        if (allowedToolNames.length > 0 && hooks?.onBeforeActivateTools) {
+          const onBeforeActivateTools = hooks.onBeforeActivateTools;
+          const filtered = await runBeforeHook(
+            () => onBeforeActivateTools(
+              allowedToolNames,
+              context.input.routeName,
+              contextForHooks
+            ),
+            "Unauthorized: Tool activation denied"
+          );
+          const structurallyAllowed = new Set(allowedToolNames);
+          allowedToolNames = [
+            ...new Set(
+              filtered.filter((name) => structurallyAllowed.has(name))
+            )
+          ];
+        }
+        return buildTools(allowedToolNames, config);
+      };
+      const reportStreamError = async (error) => {
+        try {
+          await hooks?.onErrorChat?.(
+            normalizeError(error, "Chat provider stream failed"),
+            contextForHooks
+          );
+        } catch (hookError) {
+          console.error("[ai-chat] Error in onErrorChat hook:", hookError);
+        }
+      };
+      const startModelStream = (mergedTools, onFinish) => {
+        const result = streamText({
+          model: config.model,
+          messages,
+          tools: mergedTools,
+          ...mergedTools ? { stopWhen: stepCountIs(5) } : {},
+          ...onFinish ? { onFinish } : {},
+          onError: ({ error }) => reportStreamError(error)
+        });
+        return result.toUIMessageStreamResponse({
+          originalMessages: uiMessages
+        });
+      };
+      if (config.access === "public") {
+        const mergedTools = await enterChatLifecycle();
+        return startModelStream(mergedTools);
+      }
+      requireAtomicConversationTransactions(adapter);
+      const releaseExistingConversationClaim = prepared.snapshot ? claimConversationMutation(prepared.snapshot.id) : void 0;
+      const requestedMissingConversationId = !prepared.snapshot && context.input.conversationId ? context.input.conversationId : void 0;
+      if (requestedMissingConversationId && pendingRequestedConversationClaims.has(requestedMissingConversationId)) {
+        throw new AiChatOperationError(
+          409,
+          "Conversation changed during authorization.",
+          "STALE_CONVERSATION"
+        );
+      }
+      if (requestedMissingConversationId) {
+        pendingRequestedConversationClaims.add(requestedMissingConversationId);
+      }
+      try {
+        return await adapter.transaction(async (tx) => {
+          let conversationId = context.input.conversationId;
+          let streamClaimVersion;
+          const createConversation2 = () => {
+            const now = /* @__PURE__ */ new Date();
+            return tx.create({
+              model: "conversation",
+              forceAllowId: Boolean(conversationId),
+              data: {
+                ...conversationId ? { id: conversationId } : {},
+                ...userId ? { userId } : {},
+                title: textContent(firstMessage).slice(0, 50) || "New Conversation",
+                createdAt: now,
+                updatedAt: now
+              }
+            });
+          };
+          if (prepared.snapshot) {
+            const claimedAt = nextVersion(
+              new Date(prepared.snapshot.updatedAt)
+            );
+            const claimed = await tx.updateMany({
+              model: "conversation",
+              where: [
+                {
+                  field: "id",
+                  value: prepared.snapshot.id,
+                  operator: "eq"
+                },
+                {
+                  field: "updatedAt",
+                  value: new Date(prepared.snapshot.updatedAt),
+                  operator: "gte"
+                },
+                {
+                  field: "updatedAt",
+                  value: new Date(prepared.snapshot.updatedAt),
+                  operator: "lte"
+                }
+              ],
+              update: { updatedAt: claimedAt }
+            });
+            if (!didAffectRow(claimed, prepared.snapshot.id)) {
+              throw new AiChatOperationError(
+                409,
+                "Conversation changed during authorization.",
+                "STALE_CONVERSATION"
+              );
+            }
+            conversationId = prepared.snapshot.id;
+            streamClaimVersion = claimedAt;
+          } else if (conversationId) {
+            const current = await getConversationById(tx, conversationId);
+            if (current) {
+              throw new AiChatOperationError(
+                409,
+                "Conversation changed during authorization.",
+                "STALE_CONVERSATION"
+              );
+            }
+            const created = await createConversation2();
+            conversationId = created.id;
+            streamClaimVersion = created.updatedAt;
+          }
+          const mergedTools = await enterChatLifecycle();
+          if (!prepared.snapshot && !conversationId) {
+            const created = await createConversation2();
+            conversationId = created.id;
+            streamClaimVersion = created.updatedAt;
+          }
+          if (!conversationId || !streamClaimVersion) {
+            throw new AiChatOperationError(
+              500,
+              "Conversation id was not created.",
+              "CONVERSATION_CREATE_FAILED"
+            );
+          }
+          const existingMessages = await tx.findMany({
+            model: "message",
+            where: [
+              {
+                field: "conversationId",
+                value: conversationId,
+                operator: "eq"
+              }
+            ],
+            sortBy: { field: "createdAt", direction: "asc" }
+          });
+          const lastIncoming = uiMessages[uiMessages.length - 1];
+          const targetIndex = prepared.messageId ? existingMessages.findIndex(
+            (message) => message.id === prepared.messageId
+          ) : -1;
+          if ((prepared.intent === "retry" || prepared.intent === "edit") && targetIndex === -1) {
+            throw new AiChatOperationError(
+              409,
+              "The authorized message changed before persistence.",
+              "STALE_MESSAGE"
+            );
+          }
+          const deleteFrom = prepared.intent === "edit" ? targetIndex : prepared.intent === "retry" ? targetIndex + 1 : existingMessages.length;
+          for (const message of existingMessages.slice(deleteFrom)) {
+            await tx.delete({
+              model: "message",
+              where: [{ field: "id", value: message.id }]
+            });
+          }
+          if ((prepared.intent === "send" || prepared.intent === "edit") && lastIncoming?.role === "user") {
+            await tx.create({
+              model: "message",
+              data: {
+                conversationId,
+                role: "user",
+                content: serializedParts(lastIncoming),
+                createdAt: /* @__PURE__ */ new Date()
+              }
+            });
+          }
+          const completionConversationId = conversationId;
+          const completionClaimVersion = streamClaimVersion;
+          const response = startModelStream(mergedTools, async ({ text }) => {
+            try {
+              requireAtomicConversationTransactions(adapter);
+              const persisted = await adapter.transaction(
+                async (completionTx) => {
+                  const completedAt = nextVersion(completionClaimVersion);
+                  const claimed = await completionTx.updateMany({
+                    model: "conversation",
+                    where: [
+                      {
+                        field: "id",
+                        value: completionConversationId,
+                        operator: "eq"
+                      },
+                      {
+                        field: "updatedAt",
+                        value: completionClaimVersion,
+                        operator: "gte"
+                      },
+                      {
+                        field: "updatedAt",
+                        value: completionClaimVersion,
+                        operator: "lte"
+                      }
+                    ],
+                    update: { updatedAt: completedAt }
+                  });
+                  if (!didAffectRow(claimed, completionConversationId)) {
+                    throw new AiChatOperationError(
+                      409,
+                      "A newer stream owns this conversation.",
+                      "STALE_STREAM"
+                    );
+                  }
+                  await completionTx.create({
+                    model: "message",
+                    data: {
+                      conversationId: completionConversationId,
+                      role: "assistant",
+                      content: JSON.stringify(
+                        text ? [{ type: "text", text }] : []
+                      ),
+                      createdAt: /* @__PURE__ */ new Date()
+                    }
+                  });
+                  return completionTx.findMany({
+                    model: "message",
+                    where: [
+                      {
+                        field: "conversationId",
+                        value: completionConversationId,
+                        operator: "eq"
+                      }
+                    ],
+                    sortBy: { field: "createdAt", direction: "asc" }
+                  });
+                }
+              );
+              if (hooks?.onAfterChat) {
+                await hooks.onAfterChat(
+                  completionConversationId,
+                  persisted.map(serializeMessage),
+                  contextForHooks
+                );
+              }
+            } catch (error) {
+              console.error("[ai-chat] Error in stream completion:", error);
+              try {
+                await hooks?.onErrorChat?.(
+                  normalizeError(error, "Chat completion persistence failed"),
+                  contextForHooks
+                );
+              } catch (hookError) {
+                console.error(
+                  "[ai-chat] Error in onErrorChat hook:",
+                  hookError
+                );
+              }
+            }
+          });
+          const headers = new Headers(response.headers);
+          headers.set("X-Conversation-Id", completionConversationId);
+          return new Response(response.body, {
+            status: response.status,
+            statusText: response.statusText,
+            headers
+          });
+        });
+      } finally {
+        releaseExistingConversationClaim?.();
+        if (requestedMissingConversationId) {
+          pendingRequestedConversationClaims.delete(
+            requestedMissingConversationId
+          );
+        }
+      }
+    },
+    onError: ({ error, ...context }) => {
+      markMemoryRollback(adapter, error);
+      return notifyError(hooks?.onErrorChat, error, context, {
+        body: context.input
+      });
+    }
+  });
+  return {
+    startStream,
+    listConversations,
+    getConversation,
+    createConversation,
+    updateConversation,
+    deleteConversation
+  };
+}
+
+export { AI_CHAT_OPERATION_INVENTORY, AI_CHAT_RAW_ESCAPE_HATCH_INVENTORY, AiChatOperationError, ChatOperationInputSchema, ConversationOperationInputSchema, UpdateConversationOperationInputSchema, createAiChatOperations };