@anthusai/papyrus 2.0.0-next.1 → 2.0.0-next.100

package/lib/newsletter-model.ts

@@ -0,0 +1,202 @@
+/** Shapes and wording for the newsroom Newsletter panel. `src/papyrus_content/newsletter/` (panel.py, issues.py) produces them. */
+import { getNewsroomNavHref } from "./newsroom-nav";
+import { csvCell } from "./signup-csv";
+
+export type NewsletterCounts = Partial<Record<"queued" | "sent" | "failed" | "suppressed" | "skipped" | "delivered" | "bounced" | "complained" | "softBounced", number>>;
+
+export type NewsletterList = { id: string; name: string; kind: string; confirmed: number; pending: number; unsubscribed: number; timezone?: string };
+
+export type NewsletterEvent = { type: string; at: string; issue?: string; list?: string; detail?: string };
+
+export type NewsletterOverview = {
+  lists: NewsletterList[];
+  totals: { confirmed: number; pending: number; unsubscribed: number };
+  suppressed: number;
+  paused: { paused: boolean; reason?: string; pausedAt?: string; resumedAt?: string };
+  events: NewsletterEvent[];
+};
+
+export type NewsletterIssue = {
+  issueId: string;
+  listId: string;
+  listName?: string;
+  kind: string;
+  itemId?: string;
+  subject: string;
+  status: string;
+  sendAt?: string;
+  approvedBy?: string;
+  approvedAt?: string;
+  sentAt?: string;
+  counts: NewsletterCounts;
+  note?: string;
+  archiveUrl?: string;
+  editedSinceApproval?: boolean;
+};
+
+export type NewsletterPreview = { subject: string; html: string; text: string; bytes: number; postalAddress: boolean };
+
+export type NewsletterDelivery = { address: string; status: string; at: string; eventAt?: string; error?: string };
+
+export type NewsletterSubscriber = { email: string; status: string; lists: { id: string; status: string }[]; createdAt: string; confirmedAt?: string };
+
+export type NewsletterExportRow = {
+  email: string;
+  status: string;
+  lists: string;
+  createdAt: string;
+  consentRequestedAt: string;
+  consentConfirmedAt: string;
+  consentFormId: string;
+  consentPageUrl: string;
+  consentWording: string;
+};
+
+export type NewsletterFailure = { ok: false; error: string; message?: string };
+
+/** The newsroom words for the statuses the functions write. A status this panel does not know is shown as written, never hidden. */
+const STATUS_LABELS: Record<string, string> = {
+  draft: "Draft",
+  awaiting_approval: "Awaiting approval",
+  scheduled: "Scheduled",
+  sending: "Sending",
+  sent: "Sent",
+  stopped: "Stopped",
+  cancelled: "Cancelled",
+  blocked: "Blocked",
+};
+/** A mark beside the word, so no status relies on colour alone. */
+const STATUS_MARKS: Record<string, string> = { draft: "✎", awaiting_approval: "?", scheduled: "◷", sending: "▶", sent: "✓", stopped: "■", cancelled: "–", blocked: "!" };
+
+export function statusLabel(status: string): string {
+  if (STATUS_LABELS[status]) return STATUS_LABELS[status];
+  const words = status.replace(/_/g, " ").trim();
+  return words ? words.charAt(0).toUpperCase() + words.slice(1) : "Unknown";
+}
+
+export function statusMark(status: string): string {
+  return STATUS_MARKS[status] ?? "·";
+}
+
+export const ISSUE_STATUS_FILTERS = ["draft", "awaiting_approval", "scheduled", "sending", "sent", "blocked", "stopped", "cancelled"] as const;
+
+/** Approval accepts a draft, an alert awaiting approval, a scheduled issue (a new time) and a blocked one (cause fixed). */
+export function canApprove(status: string): boolean {
+  return status === "draft" || status === "awaiting_approval" || status === "scheduled" || status === "blocked";
+}
+export const canCancel = (status: string): boolean => status === "scheduled";
+export const canStop = (status: string): boolean => status === "sending";
+
+export function issueEditorHref(itemId: string, demo?: boolean): string {
+  return getNewsroomNavHref(`/newsroom/articles/${encodeURIComponent(itemId)}`, demo);
+}
+
+const ERROR_WORDS: Record<string, string> = {
+  forbidden: "Your role cannot do this.",
+  not_found: "That issue no longer exists.",
+  invalid_state: "The issue changed state. Refresh and try again.",
+  item_missing: "The issue's item no longer exists.",
+  render_failed: "The issue cannot be rendered. Open it in the editor and fix the body.",
+  bad_request: "The request was not understood.",
+  no_address: "Your account has no email address to send a test to.",
+  unavailable: "The newsletter service could not be reached. Try again in a minute.",
+};
+
+/** One sentence for a failed operation. A missing postal address is an operator task, so the panel says where it is set. */
+export function failureText(failure: NewsletterFailure): string {
+  if (failure.error === "postal_address_missing") {
+    return "This site has no postal address for the email footer, and mail law requires one. An operator sets it in the site's AWS configuration (an SSM parameter); it cannot be set from the newsroom.";
+  }
+  return ERROR_WORDS[failure.error] ?? failure.message ?? "The request failed.";
+}
+
+// -- times ---------------------------------------------------------------------------------------------------------------
+
+export function formatUtc(iso: string | null | undefined): string {
+  if (!iso) return "never";
+  const match = /^(\d{4}-\d{2}-\d{2})T(\d{2}:\d{2})/.exec(iso);
+  return match ? `${match[1]} ${match[2]} UTC` : iso;
+}
+
+export function validTimeZone(zone: string | null | undefined): string | null {
+  if (!zone) return null;
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: zone });
+    return zone;
+  } catch {
+    return null;
+  }
+}
+
+function wallParts(instant: Date, zone: string): { year: number; month: number; day: number; hour: number; minute: number } {
+  const parts = new Intl.DateTimeFormat("en-US", {
+    timeZone: zone, hourCycle: "h23", year: "numeric", month: "2-digit", day: "2-digit", hour: "2-digit", minute: "2-digit",
+  }).formatToParts(instant);
+  const pick = (type: string) => Number(parts.find((part) => part.type === type)?.value ?? "0");
+  return { year: pick("year"), month: pick("month"), day: pick("day"), hour: pick("hour") % 24, minute: pick("minute") };
+}
+
+/** Minutes the zone is ahead of UTC at that instant. */
+function offsetMinutes(instant: Date, zone: string): number {
+  const wall = wallParts(instant, zone);
+  const asUtc = Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute);
+  return Math.round((asUtc - Math.floor(instant.getTime() / 60000) * 60000) / 60000);
+}
+
+const pad = (value: number) => String(value).padStart(2, "0");
+
+/** Local wall time `YYYY-MM-DDTHH:mm` (a datetime-local value) as an ISO instant, for the given zone. */
+export function zonedInputToIso(local: string, zone: string): string | null {
+  const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})$/.exec(local);
+  if (!match) return null;
+  const [, year, month, day, hour, minute] = match.map(Number) as unknown as number[];
+  const wallAsUtc = Date.UTC(year, month - 1, day, hour, minute);
+  let guess = wallAsUtc - offsetMinutes(new Date(wallAsUtc), zone) * 60000;
+  guess = wallAsUtc - offsetMinutes(new Date(guess), zone) * 60000; // once more: the offset can differ across a clock change
+  const instant = new Date(guess);
+  return Number.isNaN(instant.getTime()) ? null : instant.toISOString().replace(".000Z", "Z");
+}
+
+/** The next whole hour on the zone's clock, as a datetime-local value. */
+export function nextWholeHourInput(now: Date, zone: string): string {
+  const wall = wallParts(now, zone);
+  const next = new Date(Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour + 1, 0));
+  return `${next.getUTCFullYear()}-${pad(next.getUTCMonth() + 1)}-${pad(next.getUTCDate())}T${pad(next.getUTCHours())}:00`;
+}
+
+/** An ISO instant as a datetime-local value in the zone. */
+export function isoToZonedInput(iso: string, zone: string): string {
+  const wall = wallParts(new Date(iso), zone);
+  return `${wall.year}-${pad(wall.month)}-${pad(wall.day)}T${pad(wall.hour)}:${pad(wall.minute)}`;
+}
+
+/** `2027-01-15 09:00 EST` in the zone. */
+export function formatInZone(iso: string | null | undefined, zone: string): string {
+  if (!iso) return "not set";
+  const instant = new Date(iso);
+  if (Number.isNaN(instant.getTime())) return iso;
+  const label = new Intl.DateTimeFormat("en-US", { timeZone: zone, timeZoneName: "short" }).formatToParts(instant).find((part) => part.type === "timeZoneName")?.value ?? zone;
+  return `${isoToZonedInput(iso, zone).replace("T", " ")} ${label}`;
+}
+
+// -- counts and CSV ------------------------------------------------------------------------------------------------------
+
+/** "12 sent, 2 delivered, 1 bounced"; only counters above zero, in reading order. */
+export function countsText(counts: NewsletterCounts): string {
+  const order: [keyof NewsletterCounts, string][] = [
+    ["queued", "queued"], ["sent", "sent"], ["delivered", "delivered"], ["bounced", "bounced"], ["complained", "complained"],
+    ["failed", "failed"], ["suppressed", "suppressed"], ["skipped", "skipped"], ["softBounced", "soft bounced"],
+  ];
+  const parts = order.filter(([name]) => (counts[name] ?? 0) > 0).map(([name, label]) => `${counts[name]} ${label}`);
+  return parts.length ? parts.join(", ") : "nothing sent yet";
+}
+
+export const NEWSLETTER_CSV_HEADER = [
+  "email", "status", "lists", "createdAt", "consentRequestedAt", "consentConfirmedAt", "consentFormId", "consentPageUrl", "consentWording",
+] as const;
+
+/** Every cell goes through the formula neutraliser: addresses and consent wording are text people typed. */
+export function subscribersToCsv(rows: NewsletterExportRow[]): string {
+  const lines = rows.map((row) => NEWSLETTER_CSV_HEADER.map((column) => csvCell(String(row[column] ?? ""))).join(","));
+  return `${[NEWSLETTER_CSV_HEADER.join(","), ...lines].join("\r\n")}\r\n`;
+}

package/lib/newsroom-board.ts

@@ -21,6 +21,31 @@ export interface NativeBoardIssue extends KanbanIssue {
   href: string;
   /** A few lines to show under the headline: the blurb, else the subtitle. */
   excerpt?: string;
+  /** The quiet path shown where a board would print the ID, e.g. `articles/my-slug` or `assignments/write-it`. */
+  displayId: string;
+}
+
+function slugify(text: string): string {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
+/** Section and slug for a content item, falling back to the publication's board path segment. */
+export function contentItemDisplayId(version: { section?: string | null; slug?: string | null; lineageId: string }): string {
+  const section = slugify(version.section ?? "") || contentItemBoardPathSegment();
+  return `${section}/${slugify(version.slug ?? "") || version.lineageId.slice(0, 8)}`;
+}
+
+/** Assignments have no slug: use the title as one, else a short id. */
+export function assignmentDisplayId(assignment: { id: string; title?: string | null }): string {
+  const titleSlug = slugify(assignment.title ?? "").slice(0, 48).replace(/-+$/g, "");
+  return `assignments/${titleSlug || assignment.id.slice(0, 8)}`;
+}
+
+/** `formatIssueId` for the Kanbus UI: the host-provided path, never the raw `kind:id` prefix. */
+export function formatNativeIssueId(issue: KanbanIssue): string {
+  const displayId = (issue as Partial<NativeBoardIssue>).displayId;
+  if (displayId) return displayId;
+  return issue.id.replace(/^[A-Za-z]+:/, "").slice(0, 12);
 }
 
 export function contentItemBoardPathSegment(): string {
@@ -60,7 +85,7 @@ export function projectContentItemBoard(records: {
       title: version.headline || version.title || version.slug, nativeStatus: stage, status: `${contentItemType}/${stage}`,
       priority: 2, description: workCount ? `${workCount} assignment${workCount === 1 ? "" : "s"} on this ${contentItemType}.` : undefined,
       updated_at: version.updatedAt ?? undefined, href: `/newsroom/articles/${encodeURIComponent(version.id)}`,
-      excerpt: contentItemExcerpt(version),
+      excerpt: contentItemExcerpt(version), displayId: contentItemDisplayId(version),
     };
   });
 }
@@ -73,7 +98,7 @@ export function projectAssignmentBoard(assignments: readonly AssignmentRecord[])
     priority: row.priority ?? 2, assignee: row.assigneeId || undefined,
     description: row.summary || row.brief || undefined,
     created_at: row.createdAt, updated_at: row.updatedAt,
-    href: `/newsroom/assignments/${encodeURIComponent(row.id)}`,
+    href: `/newsroom/assignments/${encodeURIComponent(row.id)}`, displayId: assignmentDisplayId(row),
   }));
 }
 

package/lib/newsroom-demo-dashboard.ts

@@ -237,7 +237,7 @@ export function applyPilobolusDemoDashboardContent(
         ...record,
         title: "Pilobolus Editorial Policy",
         body: [
-          "Publication doctrine is the global inclusion standard for Pilobol.us; desk doctrine sets local intake priorities for field notes and source intake.",
+          "Publication doctrine is the global inclusion standard for Pilobol.us; section doctrine sets local intake priorities for field notes and source intake.",
           "Field-notes reporting should prioritize accepted Pilobolus references and annotated intake artifacts—not the Papyrus platform knowledge base.",
           "High-risk claims about host takeover or network control require explicit uncertainty handling and accepted source linkage.",
         ],

package/lib/newsroom-nav.ts

@@ -21,7 +21,7 @@ export type NewsroomNavItem = {
 };
 
 export const NEWSROOM_OPS_NAV: NewsroomNavItem[] = [
-  { id: "overview", label: "Overview", detail: "Desk home", href: newsroomHref() },
+  { id: "overview", label: "Overview", detail: "Newsroom home", href: newsroomHref() },
   { id: "articles", label: getContentItemName().plural, detail: "Drafts & published", href: newsroomHref("articles") },
   { id: "assignments", label: "Assignments", detail: "Work queue", href: newsroomHref("assignments") },
   { id: "references", label: "References", detail: "Knowledge base", href: newsroomHref("references") },

package/lib/newsroom-organizer-nav.ts

@@ -8,6 +8,7 @@ export type OrganizerDestination = {
 };
 export const ORGANIZER_NAV_GROUPS: readonly { title: string; items: readonly OrganizerDestination[] }[] = [
   { title: "Editorial work", items: [
+    { key: "overview", label: "Overview", description: "See notifications and work needing attention.", path: "/newsroom", primary: true },
     { key: "articles", label: getContentItemName().plural, description: `Follow ${contentItemPluralLowercase} across their stages and open one to write or revise it.`, path: `/newsroom/${contentItemBoardPathSegment()}`, alsoActiveOnPaths: ["/newsroom/articles"], primary: true },
     { key: "assignments", label: "Assignments", description: "Follow research and reporting work across its statuses and claim it.", path: "/newsroom/assignments" },
     { key: "messages", label: "Messages", description: "Read and reply to newsroom conversations.", path: "/newsroom/messages", primary: true },
@@ -23,7 +24,7 @@ export const ORGANIZER_NAV_GROUPS: readonly { title: string; items: readonly Org
   ] },
 ];
 const all = ORGANIZER_NAV_GROUPS.flatMap(group => group.items);
-export const ORGANIZER_PRIMARY_NAV = ["articles", "references", "messages"].map(key => all.find(item => item.key === key)!);
+export const ORGANIZER_PRIMARY_NAV = ["overview", "articles", "references", "messages"].map(key => all.find(item => item.key === key)!);
 
 export const ORGANIZER_SETTINGS_DESTINATION = {
   label: "Settings", path: "/newsroom/settings", description: "Theme, motion and interface preferences.",

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);
+}

package/lib/papyrus-private-chat-client.ts

@@ -0,0 +1,81 @@
+export type PapyrusPrivateChatChannel = {
+  channel_id: string;
+  participants: Array<{ kind: string; actor_id: string }>;
+};
+
+export type PapyrusPrivateChatMessage = {
+  message_id: string;
+  channel_id: string;
+  seq: number;
+  author_kind: "human" | "bot";
+  body: string;
+  addressed_to_bot_id: string | null;
+  created_at: string;
+};
+
+export type PapyrusPrivateChatSendResult = {
+  message: PapyrusPrivateChatMessage;
+  turn_id: string | null;
+};
+
+export type PapyrusPrivateChatFetch = typeof globalThis.fetch;
+
+const CHAT_API = "/api/newsroom/chat";
+
+async function requestJson<T>(path: string, init: RequestInit, fetcher: PapyrusPrivateChatFetch): Promise<T> {
+  const response = await fetcher(`${CHAT_API}/${path}`, {
+    ...init,
+    credentials: "same-origin",
+    cache: "no-store",
+  });
+  const payload = await response.json().catch(() => null) as Record<string, unknown> | null;
+  if (!response.ok) {
+    const error = typeof payload?.error === "string" ? payload.error
+      : typeof payload?.detail === "string" ? payload.detail
+        : `Private chat request failed (${response.status}).`;
+    throw new Error(error);
+  }
+  if (!payload || typeof payload !== "object") throw new Error("Private chat returned an invalid response.");
+  return payload as T;
+}
+
+/** Open the current editor's server-derived private channel using the signed same-origin session cookie. */
+export async function openPapyrusPrivateChat(fetcher: PapyrusPrivateChatFetch = globalThis.fetch): Promise<PapyrusPrivateChatChannel> {
+  const result = await requestJson<PapyrusPrivateChatChannel>("private-channel", { method: "POST" }, fetcher);
+  if (!result.channel_id?.trim() || !Array.isArray(result.participants)) {
+    throw new Error("Private chat returned an invalid channel.");
+  }
+  return result;
+}
+
+/** Read only the private channel returned by the host's authenticated open request. */
+export async function listPapyrusPrivateChatMessages(
+  channelId: string,
+  fetcher: PapyrusPrivateChatFetch = globalThis.fetch,
+): Promise<PapyrusPrivateChatMessage[]> {
+  if (!channelId.trim()) throw new Error("A private chat channel is required.");
+  const result = await requestJson<{ messages?: unknown }>(`channels/${encodeURIComponent(channelId)}/messages`, { method: "GET" }, fetcher);
+  if (!Array.isArray(result.messages)) throw new Error("Private chat returned an invalid message list.");
+  return result.messages as PapyrusPrivateChatMessage[];
+}
+
+/** One explicit send. The browser sends neither its tenant nor author or bot identity. */
+export async function sendPapyrusPrivateChatMessage(
+  channelId: string,
+  body: string,
+  idempotencyKey: string,
+  fetcher: PapyrusPrivateChatFetch = globalThis.fetch,
+): Promise<PapyrusPrivateChatSendResult> {
+  if (!channelId.trim() || !body.trim() || !idempotencyKey.trim()) {
+    throw new Error("A channel, message and idempotency key are required.");
+  }
+  const result = await requestJson<PapyrusPrivateChatSendResult>(`channels/${encodeURIComponent(channelId)}/messages`, {
+    method: "POST",
+    headers: { "content-type": "application/json", "idempotency-key": idempotencyKey },
+    body: JSON.stringify({ body }),
+  }, fetcher);
+  if (!result.message?.message_id || result.message.channel_id !== channelId) {
+    throw new Error("Private chat returned an invalid sent message.");
+  }
+  return result;
+}