@anthusai/papyrus 5.39.0 → 5.41.0

package/components/papyrus-private-chat-panel.tsx

@@ -0,0 +1,134 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { PapyrusConsoleConversation, type ConsoleConversationMessage } from "./papyrus-console-conversation";
+import {
+  listPapyrusPrivateChatMessages,
+  openPapyrusPrivateChat,
+  sendPapyrusPrivateChatMessage,
+  type PapyrusPrivateChatChannel,
+  type PapyrusPrivateChatMessage,
+} from "../lib/papyrus-private-chat-client";
+
+const REFRESH_MS = 2_000;
+
+function toConsoleMessages(messages: readonly PapyrusPrivateChatMessage[]): ConsoleConversationMessage[] {
+  return messages.map((message) => ({
+    id: message.message_id,
+    role: message.author_kind === "human" ? "USER" : "ASSISTANT",
+    text: message.body,
+    createdAt: message.created_at,
+  }));
+}
+
+function failureMessage(error: unknown): string {
+  return error instanceof Error && error.message.trim() ? error.message : "Private chat is unavailable.";
+}
+
+export function PapyrusPrivateChatPanel({ onClose }: { onClose: () => void }) {
+  const [channel, setChannel] = useState<PapyrusPrivateChatChannel | null>(null);
+  const [messages, setMessages] = useState<PapyrusPrivateChatMessage[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [sending, setSending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const retryAttempt = useRef<{ text: string; key: string } | null>(null);
+  const isWaitingForReply = messages.length > 0 && messages[messages.length - 1].author_kind === "human" &&
+    messages[messages.length - 1].addressed_to_bot_id !== null;
+  const conversationMessages = useMemo(() => {
+    const current = toConsoleMessages(messages);
+    if (!isWaitingForReply) return current;
+    const last = messages[messages.length - 1];
+    return [...current, {
+      id: `pending-reply:${last.message_id}`,
+      role: "ASSISTANT",
+      text: "",
+      pending: true,
+    }];
+  }, [isWaitingForReply, messages]);
+
+  const refreshMessages = useCallback(async (channelId: string) => {
+    const next = await listPapyrusPrivateChatMessages(channelId);
+    setMessages(next);
+  }, []);
+
+  const openConversation = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const nextChannel = await openPapyrusPrivateChat();
+      setChannel(nextChannel);
+      await refreshMessages(nextChannel.channel_id);
+    } catch (nextError) {
+      setError(failureMessage(nextError));
+    } finally {
+      setLoading(false);
+    }
+  }, [refreshMessages]);
+
+  useEffect(() => {
+    void openConversation();
+  }, [openConversation]);
+
+  useEffect(() => {
+    if (!channel || !isWaitingForReply) return;
+    let active = true;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const poll = async () => {
+      try {
+        await refreshMessages(channel.channel_id);
+      } catch (nextError) {
+        if (active) setError(failureMessage(nextError));
+        return;
+      }
+      if (active) timer = setTimeout(poll, REFRESH_MS);
+    };
+    timer = setTimeout(poll, REFRESH_MS);
+    return () => {
+      active = false;
+      if (timer) clearTimeout(timer);
+    };
+  }, [channel, isWaitingForReply, refreshMessages]);
+
+  const sendMessage = useCallback(async (text: string) => {
+    if (!channel || !text.trim() || sending) return;
+    const attempt = retryAttempt.current?.text === text
+      ? retryAttempt.current
+      : { text, key: globalThis.crypto.randomUUID() };
+    retryAttempt.current = attempt;
+    setSending(true);
+    setError(null);
+    try {
+      const result = await sendPapyrusPrivateChatMessage(channel.channel_id, text, attempt.key);
+      setMessages((current) => current.some((message) => message.message_id === result.message.message_id)
+        ? current
+        : [...current, result.message]);
+      retryAttempt.current = null;
+    } catch (nextError) {
+      setError(failureMessage(nextError));
+    } finally {
+      setSending(false);
+    }
+  }, [channel, sending]);
+
+  return <div className="papyrus-console__panel">
+    <header className="papyrus-console__header">
+      <p className="papyrus-console__header-label">Private chat</p>
+      <button className="papyrus-console__close" onClick={onClose} type="button" aria-label="Close console">×</button>
+    </header>
+    {channel ? <p className="papyrus-console__empty" role="status">Private conversation for your selected Account.</p> : null}
+    {!channel && !loading ? <div className="papyrus-console__empty" role="alert">
+      <strong>Private chat could not be opened.</strong>
+      <span>{error}</span>
+      <button className="papyrus-console__new-session" onClick={() => void openConversation()} type="button">Retry</button>
+    </div> : <PapyrusConsoleConversation
+      messages={conversationMessages}
+      isSending={sending || loading || !channel}
+      isRunning={isWaitingForReply}
+      onSendMessage={sendMessage}
+      error={error}
+      emptyState={loading ? <p className="papyrus-console__empty">Opening private conversation…</p> : (
+        <p className="papyrus-console__empty">This conversation is private to your selected Account and editor session.</p>
+      )}
+    />}
+  </div>;
+}

package/infra/amplify-app-shell.js

@@ -199,6 +199,7 @@ export class AmplifyAppShellStack extends Stack {
             environmentVariables: environmentVariables({
                 ...config.cms.environment,
                 ...emailEnvironment,
+                PAPYRUS_PRIVATE_CHAT_ENABLED: config.cms.environment.PAPYRUS_PRIVATE_CHAT_ENABLED ?? "false",
                 PAPYRUS_COGNITO_DOMAIN_PREFIX: config.cms.cognitoDomainPrefix,
                 ...(config.cms.applyCognitoDomainPrefix ? { PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX: "true" } : {}),
                 PAPYRUS_OAUTH_REDIRECT_URLS: oauthRedirectUrls,
@@ -221,6 +222,7 @@ export class AmplifyAppShellStack extends Stack {
                 buildSpec: cmsStagingBuildSpec(config),
                 environmentVariables: environmentVariables({
                     ...config.cms.environment,
+                    PAPYRUS_PRIVATE_CHAT_ENABLED: "false",
                     PAPYRUS_COGNITO_DOMAIN_PREFIX: config.cms.cognitoDomainPrefix,
                     ...(config.cms.applyCognitoDomainPrefix ? { PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX: "true" } : {}),
                     PAPYRUS_OAUTH_REDIRECT_URLS: oauthRedirectUrls,

package/infra/amplify-app-shell.ts

@@ -221,6 +221,7 @@ export class AmplifyAppShellStack extends Stack {
       environmentVariables: environmentVariables({
         ...config.cms.environment,
         ...emailEnvironment,
+        PAPYRUS_PRIVATE_CHAT_ENABLED: config.cms.environment.PAPYRUS_PRIVATE_CHAT_ENABLED ?? "false",
         PAPYRUS_COGNITO_DOMAIN_PREFIX: config.cms.cognitoDomainPrefix,
         ...(config.cms.applyCognitoDomainPrefix ? { PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX: "true" } : {}),
         PAPYRUS_OAUTH_REDIRECT_URLS: oauthRedirectUrls,
@@ -244,6 +245,7 @@ export class AmplifyAppShellStack extends Stack {
         buildSpec: cmsStagingBuildSpec(config),
         environmentVariables: environmentVariables({
           ...config.cms.environment,
+          PAPYRUS_PRIVATE_CHAT_ENABLED: "false",
           PAPYRUS_COGNITO_DOMAIN_PREFIX: config.cms.cognitoDomainPrefix,
           ...(config.cms.applyCognitoDomainPrefix ? { PAPYRUS_APPLY_COGNITO_DOMAIN_PREFIX: "true" } : {}),
           PAPYRUS_OAUTH_REDIRECT_URLS: oauthRedirectUrls,

package/infra/site-config.js

@@ -273,6 +273,10 @@ function parseCms(value) {
             fail(`cms.environment.${key}`, "is managed by the template: Google sign-in is always on, the Cognito domain comes from cms.cognitoDomainPrefix, the revalidation secret parameter is derived from siteId and the Prospectus endpoint comes from cms.prospectusAccountsApiStageArn and the public site origin comes from the site host");
         }
     }
+    const privateChatEnabled = cms.environment.PAPYRUS_PRIVATE_CHAT_ENABLED;
+    if (privateChatEnabled !== undefined && privateChatEnabled !== "true" && privateChatEnabled !== "false") {
+        fail("cms.environment.PAPYRUS_PRIVATE_CHAT_ENABLED", "must be the string \"true\" or \"false\"");
+    }
     if (cms.siteOrigin && cms.domainName) {
         fail("cms.siteOrigin", "is for sites whose host is served by their own edge; remove it when cms.domainName is set");
     }

package/infra/site-config.ts

@@ -413,6 +413,10 @@ function parseCms(value: unknown): CmsConfig {
       fail(`cms.environment.${key}`, "is managed by the template: Google sign-in is always on, the Cognito domain comes from cms.cognitoDomainPrefix, the revalidation secret parameter is derived from siteId and the Prospectus endpoint comes from cms.prospectusAccountsApiStageArn and the public site origin comes from the site host");
     }
   }
+  const privateChatEnabled = cms.environment.PAPYRUS_PRIVATE_CHAT_ENABLED;
+  if (privateChatEnabled !== undefined && privateChatEnabled !== "true" && privateChatEnabled !== "false") {
+    fail("cms.environment.PAPYRUS_PRIVATE_CHAT_ENABLED", "must be the string \"true\" or \"false\"");
+  }
 
   if (cms.siteOrigin && cms.domainName) {
     fail("cms.siteOrigin", "is for sites whose host is served by their own edge; remove it when cms.domainName is set");

package/lib/monitoring-client.ts

@@ -1,29 +1,83 @@
 "use client";
 
 import { generateClient } from "aws-amplify/data";
-import type { MonitoringResult } from "./monitoring-overview";
+import { emailReferenceBatches } from "./monitoring-overview";
+import type {
+  EmailReferenceImportItem,
+  EmailReferenceImportOutcome,
+  MonitoringEmailArticleResolution,
+  MonitoringEmailDetails,
+  MonitoringResult,
+} from "./monitoring-overview";
 
-type GraphQLResult = { data?: { monitoringOverview?: unknown }; errors?: { message?: string; errorType?: string }[] };
+type QueryField = "monitoringOverview" | "monitoringEmailSubmission" | "monitoringResolveEmailArticleLink" | "intakeEmailSubmissionReferences";
+type GraphQLResult = { data?: Partial<Record<QueryField, unknown>>; errors?: { message?: string; errorType?: string }[] };
 
-/**
- * Reads the monitoring overview through the site's own authenticated API (user pool, editor or admin).
- * The browser holds no table name, key or secret: the function behind the query does the read.
- */
-export async function loadMonitoringOverview(scope: "publication" | "all"): Promise<MonitoringResult> {
+async function query<T>(field: QueryField, queryText: string, variables: Record<string, string | number>): Promise<T | { error: "forbidden" } | { state: "unavailable" }> {
   const client = generateClient({ authMode: "userPool" });
   let result: GraphQLResult;
   try {
-    result = (await client.graphql({
-      query: `query MonitoringOverview($scope: String) { monitoringOverview(scope: $scope) }`,
-      variables: { scope },
-    })) as GraphQLResult;
+    result = (await client.graphql({ query: queryText, variables })) as GraphQLResult;
   } catch (error) {
-    // Amplify throws the response when AppSync returns errors.
     result = (error && typeof error === "object" && "errors" in error ? error : { errors: [{ message: "failed" }] }) as GraphQLResult;
   }
   const refused = result.errors?.some((entry) => /unauthorized|not authorized|forbidden/i.test(`${entry.errorType ?? ""} ${entry.message ?? ""}`));
   if (refused) return { error: "forbidden" };
-  if (result.errors?.length || result.data?.monitoringOverview === undefined || result.data.monitoringOverview === null) return { state: "unavailable" };
-  const raw = result.data.monitoringOverview;
-  return (typeof raw === "string" ? JSON.parse(raw) : raw) as MonitoringResult;
+  const raw = result.data?.[field];
+  if (result.errors?.length || raw === undefined || raw === null) return { state: "unavailable" };
+  return (typeof raw === "string" ? JSON.parse(raw) : raw) as T;
+}
+
+/** Reads monitoring data only through the site's authenticated editor/admin API. */
+export async function loadMonitoringOverview(scope: "publication" | "all"): Promise<MonitoringResult> {
+  return query<MonitoringResult>("monitoringOverview",
+    `query MonitoringOverview($scope: String) { monitoringOverview(scope: $scope) }`, { scope });
+}
+
+/** Loads one receipt's safe plain-text rendering and its already extracted candidate links. */
+export async function loadMonitoringEmailSubmission(receiptId: string): Promise<MonitoringEmailDetails> {
+  return query<MonitoringEmailDetails>("monitoringEmailSubmission",
+    `query MonitoringEmailSubmission($receiptId: String!) { monitoringEmailSubmission(receiptId: $receiptId) }`, { receiptId });
+}
+
+/** Resolve one explicitly selected Beehiiv article redirect; this may register a click with the sender. */
+export async function resolveMonitoringEmailArticleLink(receiptId: string, candidateIndex: number): Promise<MonitoringEmailArticleResolution> {
+  return query<MonitoringEmailArticleResolution>("monitoringResolveEmailArticleLink",
+    `mutation MonitoringResolveEmailArticleLink($receiptId: String!, $candidateIndex: Int!) { monitoringResolveEmailArticleLink(receiptId: $receiptId, candidateIndex: $candidateIndex) }`,
+    { receiptId, candidateIndex });
+}
+
+/** Use the existing editor-authorized Reference intake; 20 is its request batch size, not a total limit. */
+export async function importMonitoringEmailCandidates(
+  receiptId: string,
+  items: EmailReferenceImportItem[],
+): Promise<EmailReferenceImportOutcome> {
+  const client = generateClient({ authMode: "userPool" });
+  const references: EmailReferenceImportOutcome["references"] = [];
+  for (const batch of emailReferenceBatches(items)) {
+    let result: GraphQLResult;
+    try {
+      result = (await client.graphql({
+        query: `mutation IntakeEmailSubmissionReferences($input: AWSJSON!) { intakeEmailSubmissionReferences(input: $input) }`,
+        variables: { input: JSON.stringify({ receiptId, items: batch }) },
+      })) as GraphQLResult;
+    } catch {
+      return { imported: references.length, references, error: "The import stopped. Completed links are safe to retry." };
+    }
+    if (result.errors?.length) {
+      return { imported: references.length, references, error: "The import stopped. Completed links are safe to retry." };
+    }
+    const raw = result.data?.intakeEmailSubmissionReferences;
+    let response: { ok?: boolean; references?: EmailReferenceImportOutcome["references"] } | null | undefined;
+    try {
+      response = (typeof raw === "string" ? JSON.parse(raw) : raw) as typeof response;
+    } catch {
+      return { imported: references.length, references, error: "The import response could not be read. Completed links are safe to retry." };
+    }
+    if (!response?.ok || !Array.isArray(response.references)) {
+      return { imported: references.length, references, error: "The import was not accepted. Check your editor access and retry." };
+    }
+    references.push(...response.references);
+  }
+  return { imported: references.length, references };
 }

package/lib/monitoring-overview-fixture.ts

@@ -15,7 +15,7 @@ export const FIXTURE_MONITORING_OVERVIEW: MonitoringOverview = {
   routerRuns: [{ runId: "q2", startedAt: "2026-10-21T02:37:00.000000Z", mode: "live", status: "stopped", stoppedBy: "request_ceiling_reached",
     counts: { examined: 3, decided: 1, delivered: 1, deliveryFailed: 1, routed: 1 }, errorCount: 0 }],
   router: { mode: "live", feedback: true, enabled: true, maxItemsPerRun: 5 },
-  usage: { day: "2026-10-21", decisionsToday: 2, decisionsTotal: 3, ceilings: { decisionsTotal: 300, decisionsPerDay: 100, items: 300 } },
+  usage: { day: "2026-10-21", decisionsToday: 2, decisionsTotal: 3, historyComplete: true },
   hiddenNotRelevant: 1,
   items: [
     { sourceId: "104", revision: 1, title: "Fresh Show HN", url: "https://example.org/104", discussionUrl: "https://news.ycombinator.com/item?id=104",

package/lib/monitoring-overview.ts

@@ -32,6 +32,52 @@ export type MonitoringItem = {
   relevance: MonitoringRelevance[];
 };
 
+export type MonitoringEmailSummary = {
+  receiptId: string; observedAt: string | null; status: string; subject: string | null;
+  envelopeSender: string | null; headerFrom: string | null; warnings: string[];
+  verdicts: Record<string, string>; linkCount: number; processedCount: number; unresolvedLinkCount: number;
+  reviewRequired: boolean; errorCode: string | null;
+};
+
+export type MonitoringEmailDetails = {
+  submission: MonitoringEmailSummary & { corpusId: string | null }; safeBodyText: string;
+  candidateLinks: { url: string; title: string; resolutionStatus?: "unresolved" }[]; sourceMaterialIsUntrusted: true;
+} | { error: "forbidden" | "bad_request" } | { state: "unavailable" | "not_configured" };
+
+export type MonitoringEmailArticleResolution = {
+  url: string; title: string; resolved: true;
+} | { error: "forbidden" | "bad_request" | "not_resolvable" | "resolution_failed"; reason?: string } | { state: "unavailable" };
+
+export type EmailReferenceImportItem = { candidateIndex: number; source_uri: string };
+export type EmailReferenceImportOutcome = {
+  imported: number; references: { id: string; lineageId: string; curationStatus: string }[]; error?: string;
+};
+
+/** Split a complete editor selection into API work batches; the batch size is not a total link limit. */
+export function emailReferenceBatches<T>(items: T[], batchSize = 20): T[][] {
+  if (!Number.isSafeInteger(batchSize) || batchSize < 1) throw new Error("batchSize must be a positive integer");
+  const batches: T[][] = [];
+  for (let offset = 0; offset < items.length; offset += batchSize) {
+    batches.push(items.slice(offset, offset + batchSize));
+  }
+  return batches;
+}
+
+/** Async email actions may only update the receipt that is still open. */
+export function isCurrentEmailSubmissionAction(activeReceiptId: string | null, actionReceiptId: string): boolean {
+  return activeReceiptId === actionReceiptId;
+}
+
+export function beginEmailSubmissionAction(inFlight: Set<string>, actionKey: string): boolean {
+  if (inFlight.has(actionKey)) return false;
+  inFlight.add(actionKey);
+  return true;
+}
+
+export function endEmailSubmissionAction(inFlight: Set<string>, actionKey: string): void {
+  inFlight.delete(actionKey);
+}
+
 export type MonitoringRun = {
   runId: string;
   startedAt: string;
@@ -79,9 +125,10 @@ export type MonitoringOverview = {
     day: string;
     decisionsToday: number;
     decisionsTotal: number;
-    ceilings: { decisionsTotal?: number; decisionsPerDay?: number; items?: number } | null;
+    historyComplete: boolean;
   } | null;
   items: MonitoringItem[];
+  emailSubmissions?: MonitoringEmailSummary[];
   hiddenNotRelevant: number;
 };
 
@@ -116,10 +163,6 @@ export function confidenceText(confidence: number | null): string {
   return confidence === null ? "confidence not reported" : `${Math.round(confidence * 100)}% confidence`;
 }
 
-export function usageText(used: number, ceiling: number | undefined): string {
-  return ceiling === undefined ? `${used} used, no ceiling set` : `${used} of ${ceiling}`;
-}
-
 export function everyText(seconds: number | null): string {
   if (!seconds) return "on a schedule";
   return seconds % 3600 === 0 ? `every ${seconds / 3600} h` : seconds % 60 === 0 ? `every ${seconds / 60} min` : `every ${seconds} s`;

package/lib/papyrus-chat-admission.ts

@@ -0,0 +1,65 @@
+import { postChatMessage, type ChatHttpTransport, type ChatMessageSubmission, type PostMessageResponse } from "chatticus/chat-client";
+
+/** Stable author mapping supplied by the Papyrus host; never infer it from a display label or email. */
+export interface PapyrusChatAuthor {
+  hostMappedAuthorId: string;
+  addressedToBotId: string | null;
+}
+
+/** One logical send. Reuse this exact value only for an explicit retry of the same message. */
+export interface PapyrusChatAdmissionAttempt {
+  readonly submission: Readonly<ChatMessageSubmission>;
+  readonly idempotencyKey: string;
+}
+
+export interface PapyrusChatAdmissionSenderOptions {
+  /** Host-owned chat URL; no endpoint is configured or exposed by this module. */
+  url: string;
+  /** Must obtain current Papyrus auth headers on every call; token type stays a host decision. */
+  freshAuthorizationHeaders: () => Promise<Record<string, string>>;
+  fetch?: typeof globalThis.fetch;
+  /** Override only in hermetic tests. Production defaults to the platform CSPRNG. */
+  createIdempotencyKey?: () => string;
+}
+
+export interface PapyrusChatAdmissionSender {
+  createAttempt(text: string, author: PapyrusChatAuthor): PapyrusChatAdmissionAttempt;
+  send(attempt: PapyrusChatAdmissionAttempt): Promise<PostMessageResponse>;
+}
+
+/**
+ * Bind Papyrus's host-owned auth and URL to Chatticus's reusable admission
+ * transport. Each send makes one POST; there is no automatic retry or auth
+ * fallback. An explicit retry sends the same attempt and refreshes headers.
+ */
+export function createPapyrusChatAdmissionSender(options: PapyrusChatAdmissionSenderOptions): PapyrusChatAdmissionSender {
+  const transport: ChatHttpTransport = {
+    url: options.url,
+    headers: async () => {
+      const headers = await options.freshAuthorizationHeaders();
+      const authorization = Object.entries(headers).find(([name]) => name.toLowerCase() === "authorization")?.[1];
+      if (!authorization?.trim()) throw new Error("Papyrus authorization headers are required");
+      return headers;
+    },
+    ...(options.fetch ? { fetch: options.fetch } : {}),
+  };
+  const createKey = options.createIdempotencyKey ?? (() => globalThis.crypto.randomUUID());
+
+  return {
+    createAttempt(text, author) {
+      if (!text.trim() || !author.hostMappedAuthorId.trim()) throw new Error("A message and host-mapped author are required");
+      const submission: ChatMessageSubmission = {
+        author_kind: "human",
+        author_id: author.hostMappedAuthorId,
+        body: text,
+        addressed_to_bot_id: author.addressedToBotId,
+      };
+      const idempotencyKey = createKey();
+      if (!idempotencyKey.trim()) throw new Error("A stable message admission key is required");
+      return Object.freeze({ submission: Object.freeze(submission), idempotencyKey });
+    },
+    send(attempt) {
+      return postChatMessage(transport, attempt.submission, attempt.idempotencyKey);
+    },
+  };
+}

package/lib/papyrus-hosted-chat.ts

@@ -0,0 +1,217 @@
+import { createHash } from "node:crypto";
+import type { EmbeddedChatAppDependencies } from "chatticus/chat-server";
+import type { NextRequest } from "next/server";
+import {
+  ProspectusAccountsError,
+  authorizeSignedInPersonForAccount,
+} from "./prospectus-site-identity";
+import {
+  resolveProspectusSignInRuntime,
+  signedInProspectusSession,
+  type ProspectusSignInRuntime,
+} from "./prospectus-session";
+import { prospectusSiteProduct, publishingAccountsForSite } from "./prospectus-publication-access";
+import { publicSiteOrigin } from "./site-origin-value";
+
+const NO_STORE_HEADERS = { "cache-control": "no-store" };
+
+export interface PapyrusChatScope {
+  siteProduct: string;
+  accountId: string;
+  personId: string;
+  tenantId: string;
+  editorId: string;
+}
+
+export interface PapyrusHostedChatOptions {
+  resolveRuntime?: (siteOrigin: string) => Promise<ProspectusSignInRuntime | null>;
+  resolvePrivateDependencies?: () => Promise<EmbeddedChatAppDependencies | null>;
+  privateChatEnabled?: boolean;
+  siteProduct?: string | null;
+  environment?: Record<string, string | undefined>;
+  nowInSeconds?: () => number;
+}
+
+function siteAndAccountKey(siteProduct: string, accountId: string): string {
+  return createHash("sha256").update(JSON.stringify([siteProduct, accountId])).digest("hex");
+}
+
+export function derivePapyrusChatScope(siteProduct: string, accountId: string, personId: string): PapyrusChatScope {
+  const tenantHash = siteAndAccountKey(siteProduct, accountId);
+  const editorHash = createHash("sha256").update(JSON.stringify([siteProduct, accountId, personId])).digest("hex");
+  return {
+    siteProduct,
+    personId,
+    accountId,
+    tenantId: `papyrus-${tenantHash.slice(0, 40)}`,
+    editorId: `papyrus-editor-${editorHash.slice(0, 40)}`,
+  };
+}
+
+type ResolvedPapyrusPrincipal = {
+  kind: "user";
+  tenantId: string;
+  userId: string;
+  workerId: null;
+  organizationStatus: "enabled";
+  role: "member";
+};
+
+async function principalForRequest(
+  request: NextRequest,
+  operation: "console:read" | "console:write",
+  options: PapyrusHostedChatOptions,
+): Promise<{ principal: ResolvedPapyrusPrincipal | null; status: number }> {
+  const environment = options.environment ?? process.env;
+  const siteProduct = options.siteProduct !== undefined ? options.siteProduct : prospectusSiteProduct(environment);
+  if (!siteProduct) return { principal: null, status: 503 };
+
+  let runtime: ProspectusSignInRuntime | null;
+  try {
+    runtime = await (options.resolveRuntime ?? resolveProspectusSignInRuntime)(publicSiteOrigin(request, environment));
+  } catch {
+    return { principal: null, status: 503 };
+  }
+  if (!runtime) return { principal: null, status: 503 };
+
+  const nowInSeconds = options.nowInSeconds?.() ?? Math.floor(Date.now() / 1000);
+  const session = signedInProspectusSession(request, runtime.sealingSecret, nowInSeconds);
+  if (!session || !session.selectedAccountId || !Number.isFinite(session.accessTokenExpiresAt) || session.accessTokenExpiresAt <= nowInSeconds) {
+    return { principal: null, status: 401 };
+  }
+
+  try {
+    const directory = await runtime.accounts.accountDirectory(session.accessToken);
+    if (directory.person?.id !== session.personId) return { principal: null, status: 401 };
+    if (!publishingAccountsForSite(directory.accounts, siteProduct).some((account) => account.accountId === session.selectedAccountId)) {
+      return { principal: null, status: 403 };
+    }
+    const authorization = await authorizeSignedInPersonForAccount(
+      runtime.accounts,
+      session.accessToken,
+      session.selectedAccountId,
+      operation,
+    );
+    if (authorization.personId !== session.personId || authorization.accountId !== session.selectedAccountId || authorization.operation !== operation) {
+      return { principal: null, status: 403 };
+    }
+    const scope = derivePapyrusChatScope(siteProduct, session.selectedAccountId, session.personId);
+    return {
+      principal: {
+        kind: "user",
+        tenantId: scope.tenantId,
+        userId: scope.editorId,
+        workerId: null,
+        organizationStatus: "enabled",
+        role: "member",
+      },
+      status: 200,
+    };
+  } catch (error) {
+    if (error instanceof ProspectusAccountsError && (error.status === 401 || error.status === 403)) {
+      return { principal: null, status: error.status };
+    }
+    return { principal: null, status: 503 };
+  }
+}
+
+function jsonFailure(status: number, error: string): Response {
+  return new Response(JSON.stringify({ error }), {
+    status,
+    headers: { ...NO_STORE_HEADERS, "content-type": "application/json" },
+  });
+}
+
+function supportedPath(path: readonly string[]): boolean {
+  return (path.length === 1 && path[0] === "private-channel") ||
+    (path.length === 3 && path[0] === "channels" && path[2] === "messages") ||
+    (path.length === 3 && path[0] === "turns" && (path[2] === "events" || path[2] === "stream"));
+}
+
+function chatRequestPath(path: readonly string[]): string {
+  return `/${path.map((part) => encodeURIComponent(part)).join("/")}`;
+}
+
+export async function handlePapyrusHostedChatRequest(
+  request: NextRequest,
+  path: readonly string[],
+  options: PapyrusHostedChatOptions = {},
+): Promise<Response> {
+  if (!supportedPath(path) || path.some((part) => !part || part === "." || part === ".." || part.includes("/"))) {
+    return jsonFailure(404, "chat_route_not_found");
+  }
+  if (request.method !== "GET" && request.method !== "POST") return jsonFailure(405, "method_not_allowed");
+  const isMessageRoute = path[0] === "channels";
+  const isPrivateChannelRoute = path[0] === "private-channel";
+  if (isPrivateChannelRoute && request.method !== "POST") return jsonFailure(405, "method_not_allowed");
+  if ((isMessageRoute && path[2] === "messages" && request.method === "POST") || (!isMessageRoute && !isPrivateChannelRoute && request.method !== "GET")) {
+    if (!isMessageRoute && !isPrivateChannelRoute) return jsonFailure(405, "method_not_allowed");
+  }
+  if (isMessageRoute && request.method === "GET" && path[2] !== "messages") return jsonFailure(405, "method_not_allowed");
+  if ((isMessageRoute || isPrivateChannelRoute) && request.method === "POST") {
+    let origin: string;
+    try {
+      origin = publicSiteOrigin(request, options.environment ?? process.env);
+    } catch {
+      return jsonFailure(503, "chat_site_origin_unavailable");
+    }
+    if (request.headers.get("origin") !== origin) return jsonFailure(403, "same_origin_required");
+  }
+
+  const environment = options.environment ?? process.env;
+  const privateChatEnabled = options.privateChatEnabled ?? environment.PAPYRUS_PRIVATE_CHAT_ENABLED === "true";
+  if (!privateChatEnabled) return jsonFailure(404, "private_chat_disabled");
+
+  let dependencies: EmbeddedChatAppDependencies | null;
+  try {
+    if (options.resolvePrivateDependencies) {
+      dependencies = await options.resolvePrivateDependencies();
+    } else {
+      const chatRuntime = await import("chatticus/chat-runtime");
+      dependencies = chatRuntime.createSiteHostedChatDependencies(
+        chatRuntime.siteHostedChatResourcesFromEnvironment(environment),
+        chatRuntime.siteHostedChatClients(),
+      ) as EmbeddedChatAppDependencies;
+    }
+  } catch {
+    dependencies = null;
+  }
+  if (!dependencies) return jsonFailure(503, "private_chat_storage_unavailable");
+
+  const authorization = await principalForRequest(request, request.method === "POST" ? "console:write" : "console:read", options);
+  if (!authorization.principal) return jsonFailure(authorization.status, authorization.status === 401 ? "sign_in_required" : authorization.status === 403 ? "chat_account_access_denied" : "chat_runtime_unavailable");
+
+  const headers = new Headers({ accept: request.headers.get("accept") ?? "application/json" });
+  let body: string | undefined;
+  if (request.method === "POST" && isMessageRoute) {
+    const idempotencyKey = request.headers.get("idempotency-key")?.trim();
+    const input = await request.json().catch(() => null) as Record<string, unknown> | null;
+    const privateBotId = environment.PAPYRUS_CHAT_PRIVATE_BOT_ID?.trim();
+    if (!idempotencyKey || typeof input?.body !== "string" || !input.body.trim()) {
+      return jsonFailure(422, "message_body_and_idempotency_key_required");
+    }
+    if (!privateBotId) return jsonFailure(503, "private_chat_storage_unavailable");
+    headers.set("content-type", "application/json");
+    headers.set("idempotency-key", idempotencyKey);
+    body = JSON.stringify({
+      author_kind: "human",
+      author_id: authorization.principal.userId,
+      body: input.body,
+      addressed_to_bot_id: privateBotId,
+    });
+  }
+
+  const target = new URL(chatRequestPath(path) + new URL(request.url).search, request.url);
+  const forwarded = new Request(target, { method: request.method, headers, ...(body === undefined ? {} : { body }) });
+  let chatServer: typeof import("chatticus/chat-server");
+  try {
+    chatServer = await import("chatticus/chat-server");
+  } catch {
+    return jsonFailure(503, "private_chat_storage_unavailable");
+  }
+  const app = chatServer.createEmbeddedChatApp({
+    ...dependencies,
+    resolvePrincipal: async () => authorization.principal,
+  });
+  return app.fetch(forwarded);
+}