@anthusai/papyrus 5.42.1 → 5.43.0-next.10

package/infra/chat.test.ts

@@ -0,0 +1,151 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { App } from "aws-cdk-lib";
+import { AmplifyAppShellStack } from "./amplify-app-shell";
+import { PapyrusChatStack } from "./chat-stack";
+import { parseSiteConfig, resolveChatLogGroupPrefix, resolveChatStackName, resolveStackName } from "./site-config";
+
+// Executes infra/amplify-app-shell/features/per-site-private-chat.feature (run through scripts/test-infra-chat.ts).
+const examples = path.resolve(__dirname, "../examples");
+const example = (name: string, change: (config: any) => void = () => {}): any => {
+  const config = JSON.parse(fs.readFileSync(path.join(examples, `${name}.site.json`), "utf8"));
+  change(config);
+  return config;
+};
+const siteNames = fs.readdirSync(examples).filter((name) => name.endsWith(".site.json")).map((name) => name.replace(/\.site\.json$/, ""));
+const lambdaDirectory = fs.mkdtempSync(path.join(os.tmpdir(), "papyrus-chat-test-"));
+for (const file of ["run-worker.js", "probe-worker.js"]) fs.writeFileSync(path.join(lambdaDirectory, file), "exports.handler = async () => ({});\n");
+
+const resourcesOf = (template: any, type: string): any[] => Object.values<any>(template.Resources).filter((resource) => resource.Type === type);
+function shellTemplate(raw: unknown): any {
+  const config = parseSiteConfig(raw);
+  const stack = new AmplifyAppShellStack(new App(), "Shell", config, { env: { account: "712236451410", region: "us-east-1" }, stackName: resolveStackName(config) });
+  return JSON.parse(JSON.stringify((App.of(stack) as App).synth().getStackByName(stack.stackName).template));
+}
+function chatTemplate(raw: unknown): any {
+  const config = parseSiteConfig(raw);
+  const app = new App();
+  const stack = new PapyrusChatStack(app, { config, env: { account: "712236451410", region: "us-east-1" }, lambdaAssetDirectory: lambdaDirectory });
+  return JSON.parse(JSON.stringify(app.synth().getStackByName(stack.stackName).template));
+}
+const branchEnvironment = (template: any, branchName: string): Record<string, unknown> => {
+  const branch = resourcesOf(template, "AWS::Amplify::Branch").find((resource) => resource.Properties.BranchName === branchName);
+  return Object.fromEntries(branch.Properties.EnvironmentVariables.map((variable: any) => [variable.Name, variable.Value]));
+};
+const CHAT_NAMES = ["PAPYRUS_CHAT_MESSAGING_TABLE", "PAPYRUS_CHAT_CONVERSATIONS_TABLE", "PAPYRUS_CHAT_SESSION_BUCKET", "PAPYRUS_CHAT_TURN_RUNS_QUEUE_URL", "PAPYRUS_CHAT_TURN_PROBES_QUEUE_URL", "PAPYRUS_CHAT_PRIVATE_BOT_ID", "PAPYRUS_CHAT_PRIVATE_BOT_NAME"];
+
+// Scenario: a site with chat enabled gets the chat environment and a data stack
+{
+  const raw = example("anth-us");
+  assert.equal(raw.chat.modelKeyParameter, "/papyrus/shipped/openai-api-key");
+  const config = parseSiteConfig(raw);
+  assert.equal(resolveChatStackName(config), "papyrus-chat-anth-us");
+  const production = branchEnvironment(shellTemplate(raw), "main");
+  assert.equal(production.PAPYRUS_PRIVATE_CHAT_ENABLED, "true");
+  assert.deepEqual(production.PAPYRUS_CHAT_MESSAGING_TABLE, { "Fn::ImportValue": "papyrus-chat-anth-us:MessagingTableName" });
+  assert.deepEqual(production.PAPYRUS_CHAT_SESSION_BUCKET, { "Fn::ImportValue": "papyrus-chat-anth-us:SessionBucketName" });
+  assert.deepEqual(production.PAPYRUS_CHAT_TURN_RUNS_QUEUE_URL, { "Fn::ImportValue": "papyrus-chat-anth-us:TurnRunsQueueUrl" });
+  assert.equal(production.PAPYRUS_CHAT_PRIVATE_BOT_ID, "papyrus-private-assistant");
+
+  const chat = chatTemplate(raw);
+  assert.equal(resourcesOf(chat, "AWS::DynamoDB::Table").length, 2);
+  const [bucket] = resourcesOf(chat, "AWS::S3::Bucket");
+  assert.equal(bucket.Properties.VersioningConfiguration.Status, "Enabled");
+  assert.equal(bucket.Properties.PublicAccessBlockConfiguration.BlockPublicPolicy, true);
+  assert.equal(resourcesOf(chat, "AWS::SQS::Queue").length, 4);
+  assert.equal(resourcesOf(chat, "AWS::Lambda::Function").length, 2);
+  const mappings = resourcesOf(chat, "AWS::Lambda::EventSourceMapping");
+  assert.equal(mappings.length, 2);
+  assert.ok(mappings.every((mapping) => mapping.Properties.Enabled === true));
+  for (const key of ["MessagingTableName", "ConversationIndexTableName", "SessionBucketName", "TurnRunsQueueUrl", "TurnProbesQueueUrl"]) {
+    assert.equal(chat.Outputs[key].Export.Name, `papyrus-chat-anth-us:${key}`);
+  }
+  assert.deepEqual(Object.keys(chat.Parameters).filter((name) => name !== "BootstrapVersion").sort(), ["GatewayRoleArn", "PrivateAssistantBotId", "PrivateAssistantBotName"]);
+
+  // Only the run worker may read the model key parameter; the gateway policy never names it.
+  const parameterGrants = resourcesOf(chat, "AWS::IAM::Policy").filter((policy) => JSON.stringify(policy.Properties.PolicyDocument).includes("openai-api-key"));
+  assert.equal(parameterGrants.length, 1);
+  assert.ok(parameterGrants[0].Properties.Roles.some((role: any) => JSON.stringify(role).includes("RunWorkerRole")));
+  assert.equal(JSON.stringify(chat).split("/papyrus/shipped/openai-api-key").length - 1, 3, "the parameter appears in the run worker grant, the run worker environment and one output only");
+  const gateway = resourcesOf(chat, "AWS::IAM::Policy").find((policy) => policy.Properties.Roles.some((role: any) => JSON.stringify(role).includes("GatewayRoleArn")));
+  assert.ok(gateway, "the gateway policy attaches to the role named by GatewayRoleArn");
+  const gatewayActions = gateway.Properties.PolicyDocument.Statement.flatMap((statement: any) => [statement.Action].flat());
+  assert.ok(!gatewayActions.some((action: string) => action.startsWith("ssm:") || action.endsWith("*")), "the gateway has no SSM access and no wildcard action");
+}
+
+// Scenario: the staging branch never gets private chat
+{
+  const staging = branchEnvironment(shellTemplate(example("p-apyr-us")), "staging");
+  assert.equal(staging.PAPYRUS_PRIVATE_CHAT_ENABLED, "false");
+  assert.deepEqual(CHAT_NAMES.filter((name) => name in staging), []);
+}
+
+// Scenario: a site without chat gets neither
+{
+  const withoutBlock = example("anth-us", (config) => delete config.chat);
+  const disabled = example("anth-us", (config) => (config.chat.enabled = false));
+  for (const raw of [withoutBlock, disabled]) {
+    const production = branchEnvironment(shellTemplate(raw), "main");
+    assert.equal(production.PAPYRUS_PRIVATE_CHAT_ENABLED, "false");
+    assert.deepEqual(CHAT_NAMES.filter((name) => name in production), []);
+    assert.equal(resolveChatStackName(parseSiteConfig(raw)), undefined);
+    assert.throws(() => chatTemplate(raw), /does not enable chat/);
+  }
+}
+
+// Scenario: the chat block cannot be contradicted by hand-set variables
+assert.throws(() => parseSiteConfig(example("anth-us", (config) => (config.cms.environment.PAPYRUS_PRIVATE_CHAT_ENABLED = "false"))), /cms\.environment\.PAPYRUS_PRIVATE_CHAT_ENABLED/);
+assert.throws(() => parseSiteConfig(example("anth-us", (config) => (config.cms.environment.PAPYRUS_CHAT_SESSION_BUCKET = "x"))), /cms\.environment\.PAPYRUS_CHAT_SESSION_BUCKET/);
+// Without chat, the existing hand-managed flag keeps working.
+assert.equal(branchEnvironment(shellTemplate(example("anth-us", (config) => { delete config.chat; config.cms.environment.PAPYRUS_PRIVATE_CHAT_ENABLED = "true"; })), "main").PAPYRUS_PRIVATE_CHAT_ENABLED, "true");
+
+// Scenario: chat needs a CMS and a model key parameter
+assert.throws(() => parseSiteConfig(example("anth-us", (config) => delete config.chat.modelKeyParameter)), /chat\.modelKeyParameter/);
+assert.throws(() => parseSiteConfig(example("anth-us", (config) => (config.chat.modelKeyParameter = "not-a-path"))), /chat\.modelKeyParameter/);
+assert.throws(() => parseSiteConfig(example("anth-us", (config) => (config.chat.enabled = "yes"))), /chat\.enabled/);
+assert.throws(() => parseSiteConfig(example("anth-us", (config) => (config.chat.extra = 1))), /chat\.extra/);
+assert.throws(() => parseSiteConfig(example("anth-us", (config) => (config.chat.workerCodeS3Key = "abc"))), /chat\.workerCodeS3Key/);
+assert.throws(() => parseSiteConfig({ siteId: "reader-only", repository: "https://github.com/example/x", brand: "x", frontend: "markus-static", papyrusVersion: "5.42.1", hostedZoneId: "Z10285921B1G7MVRV06W9", reader: { domainName: "x.example.test", buildCommand: "npm run build", baseDirectory: "out" }, chat: { enabled: true, modelKeyParameter: "/papyrus/x/openai-api-key" } }), /chat\.enabled.*requires cms/);
+assert.throws(() => new PapyrusChatStack(new App(), { config: parseSiteConfig(example("p-apyr-us", (config) => delete config.chat.workerCodeS3Key)), env: { account: "712236451410", region: "us-east-1" } }), /bundle the chat workers first/);
+
+// Scenario: two sites in one account do not share chat storage or log groups
+{
+  const enabled = siteNames.map((name) => parseSiteConfig(example(name))).filter((config) => config.chat?.enabled);
+  assert.deepEqual(enabled.map((config) => config.siteId).sort(), ["anth-us", "dataparade", "distinctive", "p-apyr-us", "pilobol-us", "shipped", "threat-intelligence"], "every Papyrus site example enables chat");
+  const names = enabled.map((config) => resolveChatStackName(config));
+  const prefixes = enabled.map((config) => resolveChatLogGroupPrefix(config));
+  assert.equal(new Set(names).size, names.length, "stack names are unique");
+  assert.equal(new Set(prefixes).size, prefixes.length, "worker log group prefixes are unique");
+  for (const config of enabled) {
+    assert.ok(/^\/(papyrus\/[a-z0-9-]+\/openai-api-key|amplify\/shared\/[a-z0-9]+\/OPENAI_API_KEY)$/.test(config.chat!.modelKeyParameter), `${config.siteId} reuses an existing model key parameter`);
+  }
+}
+
+// Scenario: the activated p.apyr.us stack is adopted without replacing anything
+{
+  const activated = JSON.parse(fs.readFileSync(path.resolve(__dirname, "../../shared-chat-runtime/cdk/PapyrusChatDataCandidate.template.json"), "utf8"));
+  const generated = chatTemplate(example("p-apyr-us"));
+  assert.equal(resolveChatStackName(parseSiteConfig(example("p-apyr-us"))), "PapyrusChatDataCandidate");
+  const normalize = (resource: any) => {
+    const copy = JSON.parse(JSON.stringify(resource));
+    delete copy.Metadata;
+    const statements = copy.Properties?.PolicyDocument?.Statement;
+    if (statements) copy.Properties.PolicyDocument.Statement = [...statements].sort((a: any, b: any) => JSON.stringify(a).localeCompare(JSON.stringify(b)));
+    return copy;
+  };
+  assert.deepEqual(Object.keys(generated.Resources).sort(), Object.keys(activated.Resources).sort(), "no resource is added, removed or renamed (a changed logical id would replace it)");
+  for (const [logicalId, resource] of Object.entries<any>(activated.Resources)) {
+    const expected = normalize(resource);
+    // The activated template is the reviewed candidate; the queue mappings were enabled live afterwards.
+    if (resource.Type === "AWS::Lambda::EventSourceMapping") expected.Properties.Enabled = true;
+    assert.deepEqual(normalize(generated.Resources[logicalId]), expected, `${logicalId} is unchanged`);
+  }
+  for (const key of Object.keys(activated.Outputs)) {
+    assert.deepEqual({ ...generated.Outputs[key], Export: undefined }, { ...activated.Outputs[key], Export: undefined, ...(key === "FeatureDefault" ? { Value: generated.Outputs[key].Value } : {}) }, `output ${key} keeps its value`);
+  }
+  assert.deepEqual(Object.keys(generated.Outputs).sort(), Object.keys(activated.Outputs).sort());
+}
+
+console.log("per-site private chat infra tests passed");

package/infra/index.js

@@ -10,6 +10,7 @@ try {
   );
 }
 export const { AmplifyAppShellStack } = await import("./amplify-app-shell.js");
+export const { PapyrusChatStack } = await import("./chat-stack.js");
 export const { SecureStringParameter } = await import("./secure-string-parameter.js");
 export const { GithubOidcProviderStack } = await import("./github-oidc-provider.js");
 export { parseSiteConfig } from "./site-config.js";

package/infra/site-config.js

@@ -28,6 +28,9 @@ const HOST_NAME_PATTERN = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
 const SITE_ORIGIN_PATTERN = /^https:\/\/([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}(:\d{1,5})?$/;
 const DOMAIN_PREFIX_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 const APP_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 _.-]*$/;
+const CHAT_MODEL_KEY_PARAMETER_PATTERN = /^\/[A-Za-z0-9_.-]+(\/[A-Za-z0-9_.-]+)+$/;
+const CHAT_LOG_GROUP_PREFIX_PATTERN = /^\/aws\/lambda\/[A-Za-z0-9_.-]{1,100}$/;
+const CHAT_WORKER_CODE_KEY_PATTERN = /^[0-9a-f]{64}\.zip$/;
 const STACK_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9-]{0,127}$/;
 const BRANCH_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9/_.-]*$/;
 const PAPYRUS_VERSION_PATTERN = /^\d+\.\d+\.\d+(-[0-9A-Za-z-]+\.\d+)?$/;
@@ -211,6 +214,58 @@ export function resolveStagingDomainName(config) {
 export function resolveStackName(config) {
     return config.stackName ?? `amplify-app-shell-${config.siteId}`;
 }
+/** The chat data stack of a site; its construct id and CloudFormation name. Nothing when chat is not enabled. */
+export function resolveChatStackName(config) {
+    if (!config.chat?.enabled)
+        return undefined;
+    return config.chat.stackName ?? `papyrus-chat-${config.siteId}`;
+}
+export function resolveChatLogGroupPrefix(config) {
+    return config.chat?.logGroupPrefix ?? `/aws/lambda/papyrus-chat-${config.siteId}`;
+}
+/** CloudFormation export names the chat stack publishes and the app shell imports (no stack ever references the other directly). */
+export const CHAT_EXPORTED_RESOURCES = ["MessagingTableName", "ConversationIndexTableName", "SessionBucketName", "TurnRunsQueueUrl", "TurnProbesQueueUrl"];
+export const CHAT_ENVIRONMENT_NAMES = {
+    MessagingTableName: "PAPYRUS_CHAT_MESSAGING_TABLE",
+    ConversationIndexTableName: "PAPYRUS_CHAT_CONVERSATIONS_TABLE",
+    SessionBucketName: "PAPYRUS_CHAT_SESSION_BUCKET",
+    TurnRunsQueueUrl: "PAPYRUS_CHAT_TURN_RUNS_QUEUE_URL",
+    TurnProbesQueueUrl: "PAPYRUS_CHAT_TURN_PROBES_QUEUE_URL",
+};
+export const CHAT_PRIVATE_ASSISTANT_ID = "papyrus-private-assistant";
+export const CHAT_PRIVATE_ASSISTANT_NAME = "Papyrus Assistant";
+export function chatExportName(stackName, resource) {
+    return `${stackName}:${resource}`;
+}
+function parseChat(value, cms) {
+    if (value === undefined)
+        return undefined;
+    const record = requireObject(value, "chat");
+    rejectUnknownKeys(record, ["enabled", "modelKeyParameter", "stackName", "logGroupPrefix", "workerCodeS3Key"], "chat");
+    if (typeof record.enabled !== "boolean")
+        fail("chat.enabled", "must be a boolean");
+    const chat = {
+        enabled: record.enabled,
+        modelKeyParameter: requireString(record.modelKeyParameter, "chat.modelKeyParameter", CHAT_MODEL_KEY_PARAMETER_PATTERN, "SSM parameter name such as /papyrus/<site>/openai-api-key"),
+        stackName: optionalString(record.stackName, "chat.stackName", STACK_NAME_PATTERN, "CloudFormation stack name"),
+        logGroupPrefix: optionalString(record.logGroupPrefix, "chat.logGroupPrefix", CHAT_LOG_GROUP_PREFIX_PATTERN, "/aws/lambda/<name>"),
+        workerCodeS3Key: optionalString(record.workerCodeS3Key, "chat.workerCodeS3Key", CHAT_WORKER_CODE_KEY_PATTERN, "<64 hex>.zip CDK asset key"),
+    };
+    for (const key of ["stackName", "logGroupPrefix", "workerCodeS3Key"]) {
+        if (chat[key] === undefined)
+            delete chat[key];
+    }
+    if (chat.enabled && cms === undefined)
+        fail("chat.enabled", "requires cms (the chat gateway runs in the CMS compute role)");
+    if (chat.enabled && cms) {
+        for (const key of Object.keys(cms.environment)) {
+            if (key === "PAPYRUS_PRIVATE_CHAT_ENABLED" || key.startsWith("PAPYRUS_CHAT_")) {
+                fail(`cms.environment.${key}`, "is managed by the chat block when chat is enabled: remove it and use chat.enabled");
+            }
+        }
+    }
+    return chat;
+}
 export function resolveStoragePreviewPrefix(config) {
     return config.storagePreviewPrefix ?? "preview/";
 }
@@ -355,7 +410,7 @@ function parseAws(value) {
 }
 export function parseSiteConfig(raw) {
     const record = requireObject(raw, "site");
-    rejectUnknownKeys(record, ["siteId", "repository", "repositoryAccessTokenSecretArn", "brand", "frontend", "hostedZoneId", "stackName", "aws", "cms", "email", "reader", "papyrusVersion", "storagePreviewPrefix", "knowledgeRun", "autoDeploy", "github"], "site");
+    rejectUnknownKeys(record, ["siteId", "repository", "repositoryAccessTokenSecretArn", "brand", "frontend", "hostedZoneId", "stackName", "aws", "cms", "email", "reader", "papyrusVersion", "storagePreviewPrefix", "chat", "knowledgeRun", "autoDeploy", "github"], "site");
     const siteId = requireString(record.siteId, "siteId", SITE_ID_PATTERN, "kebab-case");
     const repository = requireString(record.repository, "repository", REPOSITORY_PATTERN, "https://github.com/<org>/<repo>");
     const repositoryAccessTokenSecretArn = record.repositoryAccessTokenSecretArn === undefined
@@ -448,6 +503,7 @@ export function parseSiteConfig(raw) {
             fail("github", "ownerId and repoId must be set together");
         github = { owner, repo, branches, ciCanDeployInfra: ciCanDeployInfra, ...(ownerId !== undefined ? { ownerId, repoId } : {}) };
     }
+    const chat = parseChat(record.chat, cms);
     const hasDomain = cms?.domainName !== undefined || reader?.domainName !== undefined;
     if (hasDomain && hostedZoneId === undefined) {
         fail("hostedZoneId", "is required when cms.domainName or reader.domainName is set");
@@ -469,6 +525,7 @@ export function parseSiteConfig(raw) {
         reader,
         papyrusVersion,
         storagePreviewPrefix,
+        ...(chat ? { chat } : {}),
         autoDeploy: autoDeploy,
         github,
         ...(record.knowledgeRun !== undefined ? { knowledgeRun: record.knowledgeRun } : {}),

package/infra/site-config.ts

@@ -55,6 +55,21 @@ export type CmsConfig = {
   deployStackInBuild?: boolean;
 };
 
+export type ChatConfig = {
+  enabled: boolean;
+  /** SSM SecureString parameter holding the site's OpenAI key; only the chat run worker may read it. */
+  modelKeyParameter: string;
+  /** Chat data stack name (also its CDK construct id). Default `papyrus-chat-<siteId>`. */
+  stackName?: string;
+  /** CloudWatch log group prefix of the two workers (`<prefix>-run-worker`, `<prefix>-probe-worker`). Default `/aws/lambda/papyrus-chat-<siteId>`. */
+  logGroupPrefix?: string;
+  /**
+   * Pins the worker code to an already uploaded CDK asset object (key in the CDK assets bucket) instead of
+   * bundling and uploading new bytes. Only for adopting a stack whose workers are already verified live.
+   */
+  workerCodeS3Key?: string;
+};
+
 export type AmplifyAppShellSiteConfig = {
   siteId: string;
   repository: string;
@@ -82,6 +97,11 @@ export type AmplifyAppShellSiteConfig = {
   };
   papyrusVersion: string;
   storagePreviewPrefix?: string;
+  /**
+   * Private newsroom chat for this publication (docs/private-newsroom-chat-per-site.md). Absent or
+   * `enabled: false` means the site gets neither the chat data stack nor the chat environment on its CMS.
+   */
+  chat?: ChatConfig;
   /**
    * The scheduled cloud knowledge run for this publication. The app-shell stack ignores it; it is validated by
    * infra/scheduled-jobs/lib/knowledge-run-config.ts, which owns the schema.
@@ -153,6 +173,9 @@ const HOST_NAME_PATTERN = /^([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}$/;
 const SITE_ORIGIN_PATTERN = /^https:\/\/([a-z0-9]([a-z0-9-]*[a-z0-9])?\.)+[a-z]{2,}(:\d{1,5})?$/;
 const DOMAIN_PREFIX_PATTERN = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
 const APP_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9 _.-]*$/;
+const CHAT_MODEL_KEY_PARAMETER_PATTERN = /^\/[A-Za-z0-9_.-]+(\/[A-Za-z0-9_.-]+)+$/;
+const CHAT_LOG_GROUP_PREFIX_PATTERN = /^\/aws\/lambda\/[A-Za-z0-9_.-]{1,100}$/;
+const CHAT_WORKER_CODE_KEY_PATTERN = /^[0-9a-f]{64}\.zip$/;
 const STACK_NAME_PATTERN = /^[A-Za-z][A-Za-z0-9-]{0,127}$/;
 const BRANCH_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9/_.-]*$/;
 const PAPYRUS_VERSION_PATTERN = /^\d+\.\d+\.\d+(-[0-9A-Za-z-]+\.\d+)?$/;
@@ -339,6 +362,57 @@ export function resolveStackName(config: Pick<AmplifyAppShellSiteConfig, "siteId
   return config.stackName ?? `amplify-app-shell-${config.siteId}`;
 }
 
+/** The chat data stack of a site; its construct id and CloudFormation name. Nothing when chat is not enabled. */
+export function resolveChatStackName(config: Pick<AmplifyAppShellSiteConfig, "siteId" | "chat">): string | undefined {
+  if (!config.chat?.enabled) return undefined;
+  return config.chat.stackName ?? `papyrus-chat-${config.siteId}`;
+}
+
+export function resolveChatLogGroupPrefix(config: Pick<AmplifyAppShellSiteConfig, "siteId" | "chat">): string {
+  return config.chat?.logGroupPrefix ?? `/aws/lambda/papyrus-chat-${config.siteId}`;
+}
+
+/** CloudFormation export names the chat stack publishes and the app shell imports (no stack ever references the other directly). */
+export const CHAT_EXPORTED_RESOURCES = ["MessagingTableName", "ConversationIndexTableName", "SessionBucketName", "TurnRunsQueueUrl", "TurnProbesQueueUrl"] as const;
+export const CHAT_ENVIRONMENT_NAMES: Record<(typeof CHAT_EXPORTED_RESOURCES)[number], string> = {
+  MessagingTableName: "PAPYRUS_CHAT_MESSAGING_TABLE",
+  ConversationIndexTableName: "PAPYRUS_CHAT_CONVERSATIONS_TABLE",
+  SessionBucketName: "PAPYRUS_CHAT_SESSION_BUCKET",
+  TurnRunsQueueUrl: "PAPYRUS_CHAT_TURN_RUNS_QUEUE_URL",
+  TurnProbesQueueUrl: "PAPYRUS_CHAT_TURN_PROBES_QUEUE_URL",
+};
+export const CHAT_PRIVATE_ASSISTANT_ID = "papyrus-private-assistant";
+export const CHAT_PRIVATE_ASSISTANT_NAME = "Papyrus Assistant";
+export function chatExportName(stackName: string, resource: (typeof CHAT_EXPORTED_RESOURCES)[number]): string {
+  return `${stackName}:${resource}`;
+}
+
+function parseChat(value: unknown, cms: CmsConfig | undefined): ChatConfig | undefined {
+  if (value === undefined) return undefined;
+  const record = requireObject(value, "chat");
+  rejectUnknownKeys(record, ["enabled", "modelKeyParameter", "stackName", "logGroupPrefix", "workerCodeS3Key"], "chat");
+  if (typeof record.enabled !== "boolean") fail("chat.enabled", "must be a boolean");
+  const chat: ChatConfig = {
+    enabled: record.enabled,
+    modelKeyParameter: requireString(record.modelKeyParameter, "chat.modelKeyParameter", CHAT_MODEL_KEY_PARAMETER_PATTERN, "SSM parameter name such as /papyrus/<site>/openai-api-key"),
+    stackName: optionalString(record.stackName, "chat.stackName", STACK_NAME_PATTERN, "CloudFormation stack name"),
+    logGroupPrefix: optionalString(record.logGroupPrefix, "chat.logGroupPrefix", CHAT_LOG_GROUP_PREFIX_PATTERN, "/aws/lambda/<name>"),
+    workerCodeS3Key: optionalString(record.workerCodeS3Key, "chat.workerCodeS3Key", CHAT_WORKER_CODE_KEY_PATTERN, "<64 hex>.zip CDK asset key"),
+  };
+  for (const key of ["stackName", "logGroupPrefix", "workerCodeS3Key"] as const) {
+    if (chat[key] === undefined) delete chat[key];
+  }
+  if (chat.enabled && cms === undefined) fail("chat.enabled", "requires cms (the chat gateway runs in the CMS compute role)");
+  if (chat.enabled && cms) {
+    for (const key of Object.keys(cms.environment)) {
+      if (key === "PAPYRUS_PRIVATE_CHAT_ENABLED" || key.startsWith("PAPYRUS_CHAT_")) {
+        fail(`cms.environment.${key}`, "is managed by the chat block when chat is enabled: remove it and use chat.enabled");
+      }
+    }
+  }
+  return chat;
+}
+
 export function resolveStoragePreviewPrefix(config: Pick<AmplifyAppShellSiteConfig, "storagePreviewPrefix">): string {
   return config.storagePreviewPrefix ?? "preview/";
 }
@@ -498,7 +572,7 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
   const record = requireObject(raw, "site");
   rejectUnknownKeys(
     record,
-    ["siteId", "repository", "repositoryAccessTokenSecretArn", "brand", "frontend", "hostedZoneId", "stackName", "aws", "cms", "email", "reader", "papyrusVersion", "storagePreviewPrefix", "knowledgeRun", "autoDeploy", "github"],
+    ["siteId", "repository", "repositoryAccessTokenSecretArn", "brand", "frontend", "hostedZoneId", "stackName", "aws", "cms", "email", "reader", "papyrusVersion", "storagePreviewPrefix", "chat", "knowledgeRun", "autoDeploy", "github"],
     "site",
   );
 
@@ -590,6 +664,8 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
     github = { owner, repo, branches, ciCanDeployInfra: ciCanDeployInfra as boolean, ...(ownerId !== undefined ? { ownerId, repoId } : {}) };
   }
 
+  const chat = parseChat(record.chat, cms);
+
   const hasDomain = cms?.domainName !== undefined || reader?.domainName !== undefined;
   if (hasDomain && hostedZoneId === undefined) {
     fail("hostedZoneId", "is required when cms.domainName or reader.domainName is set");
@@ -612,6 +688,7 @@ export function parseSiteConfig(raw: unknown): AmplifyAppShellSiteConfig {
     reader,
     papyrusVersion,
     storagePreviewPrefix,
+    ...(chat ? { chat } : {}),
     autoDeploy: autoDeploy as boolean,
     github,
     ...(record.knowledgeRun !== undefined ? { knowledgeRun: record.knowledgeRun } : {}),

package/lib/cli-login-discovery.ts

@@ -0,0 +1,78 @@
+import { NextResponse, type NextRequest } from "next/server";
+import { readAmplifyOutputsFile } from "./amplify-outputs-path";
+import { SiteOriginNotConfiguredError, publicSiteOrigin, siteOriginNotConfiguredResponse } from "./site-origin";
+
+/**
+ * The public values `papyrus login <site>` needs, served at `/.well-known/papyrus-cli.json`.
+ * Every value is public (Cognito pool/client ids, hosted-UI domain, API URL). Nothing here is a
+ * secret, and the file only exists for a site whose web client registers the CLI callback.
+ */
+export const CLI_LOGIN_PATH = "/.well-known/papyrus-cli.json";
+
+export interface CliLoginDocument {
+  publication: string;
+  issuer: string;
+  client_id: string;
+  oauth_domain: string;
+  graphql_endpoint: string;
+  callback_uri: string;
+}
+
+export interface AmplifyOutputsForCliLogin {
+  auth?: {
+    user_pool_id?: string;
+    user_pool_client_id?: string;
+    aws_region?: string;
+    oauth?: { domain?: string; redirect_sign_in_uri?: string[] };
+  };
+  data?: { url?: string };
+}
+
+/**
+ * The CLI signs in through the site's existing public web app client, which every app-shell site
+ * registers with this callback (infra/amplify-app-shell/lib/site-config.ts). No separate client exists.
+ */
+export const CLI_CALLBACK_URI = "http://localhost:3001/";
+
+export function cliLoginDocumentFromOutputs(outputs: AmplifyOutputsForCliLogin | null, siteOrigin: string): CliLoginDocument | null {
+  const userPoolId = outputs?.auth?.user_pool_id;
+  const clientId = outputs?.auth?.user_pool_client_id;
+  const domain = outputs?.auth?.oauth?.domain;
+  const endpoint = outputs?.data?.url;
+  if (!userPoolId || !clientId || !domain || !endpoint || !endpoint.startsWith("https://")) return null;
+  // Only when the client really registers the callback; otherwise the sign-in could never complete.
+  if (!outputs?.auth?.oauth?.redirect_sign_in_uri?.includes(CLI_CALLBACK_URI)) return null;
+  const region = outputs?.auth?.aws_region ?? userPoolId.split("_")[0];
+  return {
+    publication: siteOrigin,
+    issuer: `https://cognito-idp.${region}.amazonaws.com/${userPoolId}`,
+    client_id: clientId,
+    oauth_domain: `https://${domain}`,
+    graphql_endpoint: endpoint,
+    callback_uri: CLI_CALLBACK_URI,
+  };
+}
+
+export interface CliLoginDiscoveryOptions {
+  readOutputs?: () => AmplifyOutputsForCliLogin | null;
+  environment?: Record<string, string | undefined>;
+}
+
+export function handleCliLoginDiscovery(request: Pick<NextRequest, "nextUrl">, options: CliLoginDiscoveryOptions = {}): NextResponse {
+  let origin: string;
+  try {
+    origin = publicSiteOrigin(request, options.environment ?? process.env);
+  } catch (error) {
+    if (error instanceof SiteOriginNotConfiguredError) return siteOriginNotConfiguredResponse(error);
+    throw error;
+  }
+  const outputs = (options.readOutputs ?? (() => readAmplifyOutputsFile() as AmplifyOutputsForCliLogin | null))();
+  const document = cliLoginDocumentFromOutputs(outputs, origin);
+  if (!document) {
+    return NextResponse.json(
+      { error: "cli_login_not_configured", message: "This site does not register the CLI sign-in callback." },
+      { status: 404, headers: { "cache-control": "public, max-age=60" } },
+    );
+  }
+  return NextResponse.json(document, { headers: { "cache-control": "public, max-age=300" } });
+}

package/lib/monitoring-client.ts

@@ -3,6 +3,9 @@
 import { generateClient } from "aws-amplify/data";
 import { emailReferenceBatches } from "./monitoring-overview";
 import type {
+  EmailDecisionResult,
+  MonitoringListName,
+  MonitoringPage,
   EmailReferenceImportItem,
   EmailReferenceImportOutcome,
   MonitoringEmailArticleResolution,
@@ -10,10 +13,10 @@ import type {
   MonitoringResult,
 } from "./monitoring-overview";
 
-type QueryField = "monitoringOverview" | "monitoringEmailSubmission" | "monitoringResolveEmailArticleLink" | "intakeEmailSubmissionReferences";
+type QueryField = "monitoringOverview" | "monitoringPage" | "monitoringEmailSubmission" | "monitoringDecideEmailSubmission" | "monitoringResolveEmailArticleLink" | "intakeEmailSubmissionReferences" | "monitoringQueueEmailReference";
 type GraphQLResult = { data?: Partial<Record<QueryField, unknown>>; errors?: { message?: string; errorType?: string }[] };
 
-async function query<T>(field: QueryField, queryText: string, variables: Record<string, string | number>): Promise<T | { error: "forbidden" } | { state: "unavailable" }> {
+async function query<T>(field: QueryField, queryText: string, variables: Record<string, string | number | null>): Promise<T | { error: "forbidden" } | { state: "unavailable" }> {
   const client = generateClient({ authMode: "userPool" });
   let result: GraphQLResult;
   try {
@@ -34,12 +37,36 @@ export async function loadMonitoringOverview(scope: "publication" | "all"): Prom
     `query MonitoringOverview($scope: String) { monitoringOverview(scope: $scope) }`, { scope });
 }
 
+/**
+ * One more page of one list after `cursor` (null starts the list from its newest row). `heldOnly` lists only held
+ * email submissions, so a held message is findable however old it is.
+ */
+export async function loadMonitoringPage(
+  list: MonitoringListName, cursor: string | null, scope: "publication" | "all", heldOnly = false,
+): Promise<MonitoringPage> {
+  return query<MonitoringPage>("monitoringPage",
+    `query MonitoringPage($list: String!, $cursor: String, $filter: String, $scope: String) { monitoringPage(list: $list, cursor: $cursor, filter: $filter, scope: $scope) }`,
+    { list, cursor, filter: heldOnly ? "held" : null, 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 });
 }
 
+/**
+ * Accept or Reject one held email submission. "Accept" releases it into the normal intake and
+ * "Reject" discards it; the editor and the optional reason are recorded server-side.
+ */
+export async function decideMonitoringEmailSubmission(
+  receiptId: string, decision: "accept" | "reject", reason: string,
+): Promise<EmailDecisionResult> {
+  return query<EmailDecisionResult>("monitoringDecideEmailSubmission",
+    `mutation MonitoringDecideEmailSubmission($receiptId: String!, $decision: String!, $reason: String) { monitoringDecideEmailSubmission(receiptId: $receiptId, decision: $decision, reason: $reason) }`,
+    { receiptId, decision: decision === "accept" ? "release" : "discard", reason });
+}
+
 /** 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",
@@ -74,10 +101,19 @@ export async function importMonitoringEmailCandidates(
     } 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)) {
+    if (!response?.ok || !Array.isArray(response.references) || response.references.length !== batch.length) {
       return { imported: references.length, references, error: "The import was not accepted. Check your editor access and retry." };
     }
     references.push(...response.references);
+    for (const [index, reference] of response.references.entries()) {
+      const queued = await query<{ queued: boolean }>("monitoringQueueEmailReference",
+        `mutation MonitoringQueueEmailReference($input: AWSJSON!) { monitoringQueueEmailReference(input: $input) }`,
+        { input: JSON.stringify({ receiptId, ...batch[index], referenceId: reference.id }) });
+      if (!("queued" in queued) || !queued.queued) {
+        return { imported: references.length, references,
+          error: "References were registered, but predictions could not be queued. Retry these selected links safely." };
+      }
+    }
   }
   return { imported: references.length, references };
 }

package/lib/monitoring-overview-fixture.ts

@@ -5,7 +5,7 @@ export const FIXTURE_MONITORING_OVERVIEW: MonitoringOverview = {
   state: "ready",
   asOf: "2026-10-21T02:40:00Z",
   scope: { mode: "publication", publicationId: "desk-a", site: "a.example.test", canViewAll: true },
-  feeds: [{ id: "hn", sourceUrl: "https://news.ycombinator.com/rss", intervalSeconds: 900, limit: 30, enabled: true,
+  feeds: [{ id: "hn", sourceUrl: "https://news.ycombinator.com/rss", intervalSeconds: 900, enabled: true,
     lastStatus: "complete", lastFinishedAt: "2026-10-21T02:33:00Z", nextDueAt: "2026-10-21T02:50:00Z" }],
   runs: [
     { runId: "r3", startedAt: "2026-10-21T02:33:00.000000Z", status: "complete", new: 2, revised: 1, unchanged: 27, itemCount: 30, errorCount: 0, errors: [] },
@@ -14,7 +14,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 },
+  router: { mode: "live", feedback: true, enabled: true },
   usage: { day: "2026-10-21", decisionsToday: 2, decisionsTotal: 3, historyComplete: true },
   hiddenNotRelevant: 1,
   items: [