@anthusai/papyrus 5.135.0 → 5.136.0-next.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -9,7 +9,7 @@ import { FEED_STREAM_VIEW, FEED_TABLES, tableStream } from "./stream-readers.js"
9
9
  import { setModelKeyParameter } from "./model-key.js";
10
10
  import { allowWakeSending } from "./wake-queue.js";
11
11
  /**
12
- * The change feeds for Reference, ReviewRequest, Message, LocalizationRequest and Delivery (docs/design/always-on-agents-architecture.md, slice B3, PPY-9b9e64):
12
+ * The change feeds for Reference, ReviewRequest, Message, LocalizationRequest, Delivery and Assignment (docs/design/always-on-agents-architecture.md, slice B3, PPY-9b9e64):
13
13
  * one function that turns each change to a row of those tables into one wake per listening agent on the site's wake queue. All the logic is
14
14
  * src/papyrus_content/change_feeds.py (the normalized change and the wake are the Item feed's, src/papyrus_content/item_change_feed.py); the handler is
15
15
  * amplify/functions/change-feed/handler.py. One function, not one per table: the feeds share every line of code and all they differ in is the table of the stream
@@ -48,8 +48,10 @@ export const CHANGE_FEED_FILTERS = {
48
48
  Message: { eventName: ["INSERT"], dynamodb: { NewImage: { messageKind: { S: ["comment"] } } } },
49
49
  LocalizationRequest: { eventName: ["INSERT", "MODIFY"], dynamodb: { NewImage: { state: { S: ["wanted"] } } } },
50
50
  Delivery: { eventName: ["INSERT", "MODIFY"] },
51
+ // Only the Assignments that are requests between responsibilities (type `responsibility.<agent>`, src/papyrus_content/handoff_records.py); the other kinds run by their own executors.
52
+ Assignment: { eventName: ["INSERT", "MODIFY"], dynamodb: { NewImage: { assignmentTypeKey: { S: [{ prefix: "responsibility." }] } } } },
51
53
  };
52
- /** The streams of every feed table the schema has. The Reference, Message and LocalizationRequest streams are the readers' own where they exist; ReviewRequest and Delivery had none. */
54
+ /** The streams of every feed table the schema has. The Reference, Message and LocalizationRequest streams are the readers' own where they exist; ReviewRequest, Delivery and Assignment had none. */
53
55
  export function enableFeedStreams(backend) {
54
56
  const streams = {};
55
57
  for (const table of FEED_TABLES) {
@@ -12,7 +12,7 @@ import { allowWakeSending } from "./wake-queue";
12
12
  import type { AgentPiece } from "./stack";
13
13
 
14
14
  /**
15
- * The change feeds for Reference, ReviewRequest, Message, LocalizationRequest and Delivery (docs/design/always-on-agents-architecture.md, slice B3, PPY-9b9e64):
15
+ * The change feeds for Reference, ReviewRequest, Message, LocalizationRequest, Delivery and Assignment (docs/design/always-on-agents-architecture.md, slice B3, PPY-9b9e64):
16
16
  * one function that turns each change to a row of those tables into one wake per listening agent on the site's wake queue. All the logic is
17
17
  * src/papyrus_content/change_feeds.py (the normalized change and the wake are the Item feed's, src/papyrus_content/item_change_feed.py); the handler is
18
18
  * amplify/functions/change-feed/handler.py. One function, not one per table: the feeds share every line of code and all they differ in is the table of the stream
@@ -53,6 +53,8 @@ export const CHANGE_FEED_FILTERS: Record<FeedTable, Record<string, unknown>> = {
53
53
  Message: { eventName: ["INSERT"], dynamodb: { NewImage: { messageKind: { S: ["comment"] } } } },
54
54
  LocalizationRequest: { eventName: ["INSERT", "MODIFY"], dynamodb: { NewImage: { state: { S: ["wanted"] } } } },
55
55
  Delivery: { eventName: ["INSERT", "MODIFY"] },
56
+ // Only the Assignments that are requests between responsibilities (type `responsibility.<agent>`, src/papyrus_content/handoff_records.py); the other kinds run by their own executors.
57
+ Assignment: { eventName: ["INSERT", "MODIFY"], dynamodb: { NewImage: { assignmentTypeKey: { S: [{ prefix: "responsibility." }] } } } },
56
58
  };
57
59
 
58
60
  /** The streams the stack switched on or found: a table's stream ARN, only for a table the site's schema has. */
@@ -70,7 +72,7 @@ export type ChangeFeedsSource = {
70
72
  openAiKeyParameter?: string;
71
73
  };
72
74
 
73
- /** The streams of every feed table the schema has. The Reference, Message and LocalizationRequest streams are the readers' own where they exist; ReviewRequest and Delivery had none. */
75
+ /** The streams of every feed table the schema has. The Reference, Message and LocalizationRequest streams are the readers' own where they exist; ReviewRequest, Delivery and Assignment had none. */
74
76
  export function enableFeedStreams(backend: any): FeedStreams {
75
77
  const streams: FeedStreams = {};
76
78
  for (const table of FEED_TABLES) {
@@ -6,6 +6,7 @@ import { pythonLambdaCode } from "../functions/shared/python-bundle.js";
6
6
  import { connectToSiteApi } from "../site-api-access.js";
7
7
  import { tableStream } from "./stream-readers.js";
8
8
  import { setModelKeyParameter } from "./model-key.js";
9
+ import { allowFollowUpTimers } from "./schedule-group.js";
9
10
  import { allowWakeSending } from "./wake-queue.js";
10
11
  /**
11
12
  * The Item change feed (docs/design/always-on-agents-architecture.md, slice B2, PPY-8a374e): a DynamoDB stream consumer on the Item table that turns each
@@ -17,12 +18,23 @@ import { allowWakeSending } from "./wake-queue.js";
17
18
  * `enableItemStream` (the Item table had no stream and no reader before this; it holds one reader now, the feed).
18
19
  *
19
20
  * What the function may do, and nothing else: read the Item stream; read the site's `SiteDocument` rows through its own site's API (`getSiteDocument`: the live
20
- * version of the listener index) and that one document's objects in the site's bucket (`tenants/<tenant>/site/listeners/`); look up and send to its own
21
- * site's wake queue. It reads no table, receives and deletes no wake, and calls no model.
21
+ * version of the listener index and of the agent policy) and those two documents' objects in the site's bucket (`tenants/<tenant>/site/listeners/` and
22
+ * `.../agents/`); look up and send to its own site's wake queue; set and clear follow-up timers for paid steps that wait for quiet (`follow-up-*` entries in its
23
+ * site's schedule group, slice B5); and, for the loop guard (slice B7), read a Story's versions, write the loop count on its current version and raise the one hard-gate
24
+ * review request, all through its own site's API. It reads no table, receives and deletes no wake, and calls no model.
22
25
  */
23
26
  export const ITEM_STREAM_VIEW = dynamodb.StreamViewType.NEW_AND_OLD_IMAGES;
24
- export const ITEM_FEED_API_FIELDS = ["Query/fields/getSiteDocument"];
27
+ /** `getSiteDocument`: the listener index and the agent policy. The gate (PPY-67e3cd, PPY-4e7e8b) reads a Story's versions and keeps its loop count on the current one, and raises the hard gate once. */
28
+ export const ITEM_FEED_API_FIELDS = [
29
+ "Query/fields/getSiteDocument",
30
+ "Query/fields/listItemsByLineageAndVersion",
31
+ "Query/fields/getItem",
32
+ "Mutation/fields/updateItem",
33
+ "Query/fields/getReviewRequest",
34
+ "Mutation/fields/createReviewRequest",
35
+ ];
25
36
  export const LISTENER_INDEX_KIND = "listeners";
37
+ export const AGENT_POLICY_KIND = "agents";
26
38
  const STREAM_READ_ACTIONS = ["dynamodb:DescribeStream", "dynamodb:GetRecords", "dynamodb:GetShardIterator", "dynamodb:ListStreams"];
27
39
  /**
28
40
  * Switches on the Item table's stream, with both images (the feed compares them to tell a board move from any other update), and returns its ARN.
@@ -67,9 +79,12 @@ export function itemChangeFeedPiece(brandId, source) {
67
79
  feed.addToRolePolicy(new PolicyStatement({
68
80
  effect: Effect.ALLOW,
69
81
  actions: ["s3:GetObject"],
70
- resources: [`${source.bucketArn}/tenants/${source.tenantId}/site/${LISTENER_INDEX_KIND}/*`],
82
+ resources: [LISTENER_INDEX_KIND, AGENT_POLICY_KIND].map((kind) => `${source.bucketArn}/tenants/${source.tenantId}/site/${kind}/*`),
71
83
  }));
72
84
  allowWakeSending(feed, brandId);
85
+ allowFollowUpTimers(feed, brandId);
86
+ feed.addEnvironment("PAPYRUS_AWS_ACCOUNT_ID", stack.account);
87
+ feed.addEnvironment("PAPYRUS_AWS_PARTITION", stack.partition);
73
88
  feed.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: STREAM_READ_ACTIONS, resources: [source.streamArn] }));
74
89
  new CfnEventSourceMapping(scope, "ItemStreamMapping", {
75
90
  eventSourceArn: source.streamArn,
@@ -7,6 +7,7 @@ import { pythonLambdaCode } from "../functions/shared/python-bundle";
7
7
  import { connectToSiteApi } from "../site-api-access";
8
8
  import { tableStream } from "./stream-readers";
9
9
  import { setModelKeyParameter } from "./model-key";
10
+ import { allowFollowUpTimers } from "./schedule-group";
10
11
  import { allowWakeSending } from "./wake-queue";
11
12
  import type { AgentPiece } from "./stack";
12
13
 
@@ -20,13 +21,24 @@ import type { AgentPiece } from "./stack";
20
21
  * `enableItemStream` (the Item table had no stream and no reader before this; it holds one reader now, the feed).
21
22
  *
22
23
  * What the function may do, and nothing else: read the Item stream; read the site's `SiteDocument` rows through its own site's API (`getSiteDocument`: the live
23
- * version of the listener index) and that one document's objects in the site's bucket (`tenants/<tenant>/site/listeners/`); look up and send to its own
24
- * site's wake queue. It reads no table, receives and deletes no wake, and calls no model.
24
+ * version of the listener index and of the agent policy) and those two documents' objects in the site's bucket (`tenants/<tenant>/site/listeners/` and
25
+ * `.../agents/`); look up and send to its own site's wake queue; set and clear follow-up timers for paid steps that wait for quiet (`follow-up-*` entries in its
26
+ * site's schedule group, slice B5); and, for the loop guard (slice B7), read a Story's versions, write the loop count on its current version and raise the one hard-gate
27
+ * review request, all through its own site's API. It reads no table, receives and deletes no wake, and calls no model.
25
28
  */
26
29
 
27
30
  export const ITEM_STREAM_VIEW = dynamodb.StreamViewType.NEW_AND_OLD_IMAGES;
28
- export const ITEM_FEED_API_FIELDS = ["Query/fields/getSiteDocument"];
31
+ /** `getSiteDocument`: the listener index and the agent policy. The gate (PPY-67e3cd, PPY-4e7e8b) reads a Story's versions and keeps its loop count on the current one, and raises the hard gate once. */
32
+ export const ITEM_FEED_API_FIELDS = [
33
+ "Query/fields/getSiteDocument",
34
+ "Query/fields/listItemsByLineageAndVersion",
35
+ "Query/fields/getItem",
36
+ "Mutation/fields/updateItem",
37
+ "Query/fields/getReviewRequest",
38
+ "Mutation/fields/createReviewRequest",
39
+ ];
29
40
  export const LISTENER_INDEX_KIND = "listeners";
41
+ export const AGENT_POLICY_KIND = "agents";
30
42
  const STREAM_READ_ACTIONS = ["dynamodb:DescribeStream", "dynamodb:GetRecords", "dynamodb:GetShardIterator", "dynamodb:ListStreams"];
31
43
 
32
44
  /** What the feed needs from the rest of the site's backend. Absent for a backend that cannot run it (a shared stack, which acts for no one tenant). */
@@ -92,10 +104,13 @@ export function itemChangeFeedPiece(brandId: string, source: ItemChangeFeedSourc
92
104
  new PolicyStatement({
93
105
  effect: Effect.ALLOW,
94
106
  actions: ["s3:GetObject"],
95
- resources: [`${source.bucketArn}/tenants/${source.tenantId}/site/${LISTENER_INDEX_KIND}/*`],
107
+ resources: [LISTENER_INDEX_KIND, AGENT_POLICY_KIND].map((kind) => `${source.bucketArn}/tenants/${source.tenantId}/site/${kind}/*`),
96
108
  }),
97
109
  );
98
110
  allowWakeSending(feed, brandId);
111
+ allowFollowUpTimers(feed, brandId);
112
+ feed.addEnvironment("PAPYRUS_AWS_ACCOUNT_ID", stack.account);
113
+ feed.addEnvironment("PAPYRUS_AWS_PARTITION", stack.partition);
99
114
  feed.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: STREAM_READ_ACTIONS, resources: [source.streamArn] }));
100
115
  new CfnEventSourceMapping(scope, "ItemStreamMapping", {
101
116
  eventSourceArn: source.streamArn,
@@ -14,7 +14,7 @@ import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
14
14
  * This is a finding about readers that exist today, not something this fixes for them: the readers are named here only so the rule and the test can count them.
15
15
  */
16
16
  /** The tables the change feeds of slice B3 cover (the Item table's feed is its own function, amplify/agents/item-change-feed.ts). */
17
- export const FEED_TABLES = ["Reference", "ReviewRequest", "Message", "LocalizationRequest", "Delivery"];
17
+ export const FEED_TABLES = ["Reference", "ReviewRequest", "Message", "LocalizationRequest", "Delivery", "Assignment"];
18
18
  export const MAX_STREAM_READERS = 2;
19
19
  /** Every stream reader that is not a change feed: the table it reads. */
20
20
  export const STREAM_READER_TABLES = {
@@ -16,7 +16,7 @@ import * as dynamodb from "aws-cdk-lib/aws-dynamodb";
16
16
  */
17
17
 
18
18
  /** The tables the change feeds of slice B3 cover (the Item table's feed is its own function, amplify/agents/item-change-feed.ts). */
19
- export const FEED_TABLES = ["Reference", "ReviewRequest", "Message", "LocalizationRequest", "Delivery"] as const;
19
+ export const FEED_TABLES = ["Reference", "ReviewRequest", "Message", "LocalizationRequest", "Delivery", "Assignment"] as const;
20
20
  export type FeedTable = (typeof FEED_TABLES)[number];
21
21
 
22
22
  export const MAX_STREAM_READERS = 2;
@@ -2,7 +2,7 @@
2
2
 
3
3
  All the logic is ``papyrus_content.item_change_feed``. This file decodes nothing itself: it builds the collaborators with the function's own role: the
4
4
  site's listener index (``agent_listeners.ListenerIndex`` over the site store: one point read of the live version, the body from S3 only when the version
5
- moved) and the site's wake queue (``agent_wakes.wake_sender``). Nothing here lists a table.
5
+ moved) and the site's wake queue (``agent_wakes.wake_sender``). Nothing here lists a table. Between the changes and the queue stands the wake gate (``wake_gate.py``): a paid step waits for quiet on a follow-up timer, a person's change clears the loop count, and an agent that reaches the limit raises one hard gate.
6
6
 
7
7
  A batch is processed in order. A record whose wakes cannot all be put on the queue is reported as failed, and Lambda retries from it; every wake key is the same on
8
8
  the retry, so what was already sent starts nothing twice. Records that are no change (a version marked superseded, a card's counts refreshed) cost nothing.
@@ -34,13 +34,46 @@ def listener_index(site) -> Any:
34
34
  return _INDEX
35
35
 
36
36
 
37
- def handler(event: dict[str, Any], context: Any = None, *, index=None, send=None, environment=None) -> dict[str, Any]:
37
+ _CLIENT: Any = None
38
+
39
+
40
+ def site_client(site) -> Any:
41
+ global _CLIENT
42
+ if _CLIENT is None:
43
+ from papyrus_content.graphql_authoring import PapyrusGraphQLAuthoringClient
44
+
45
+ os.environ.setdefault("PAPYRUS_GRAPHQL_AUTH", "iam") # the function's own role signs the calls
46
+ _CLIENT = PapyrusGraphQLAuthoringClient(endpoint=site.appsync_endpoint)
47
+ return _CLIENT
48
+
49
+
50
+ def wake_gate(site, environment) -> Any:
51
+ """The gate between the feed and the queue (PPY-67e3cd, PPY-4e7e8b): the agent policy's window and loop limit, the site's follow-up timers, the Story's counter and the hard gate."""
52
+ import boto3
53
+
54
+ from papyrus_content import wake_gate as gate
55
+ from papyrus_content.agent_policy import AgentPolicyStore
56
+ from papyrus_content.agent_policy.run_gate import SiteCatalogue
57
+ from papyrus_content.follow_up_timers import FollowUpTimers
58
+ from papyrus_content.site_store import SiteStore
59
+
60
+ client = site_client(site)
61
+ store = AgentPolicyStore(SiteStore(boto3.client("s3"), site.site_bucket, SiteCatalogue(client)))
62
+ timers = FollowUpTimers.for_site(site.publication_id, account=environment["PAPYRUS_AWS_ACCOUNT_ID"], region=environment["AWS_REGION"],
63
+ partition=environment.get("PAPYRUS_AWS_PARTITION") or "aws")
64
+ return gate.WakeGate(policy=lambda: store.read(site.tenant_id).document, timers=timers, chain=gate.StoryChain(client),
65
+ review=lambda **found: gate.raise_loop_review(client, **found))
66
+
67
+
68
+ def handler(event: dict[str, Any], context: Any = None, *, index=None, send=None, environment=None, gate=None) -> dict[str, Any]:
38
69
  from papyrus_content import item_change_feed
39
70
  from papyrus_content.agent_wakes import wake_sender
40
71
  from papyrus_content.localize.dispatch import decode_image
41
72
 
42
- site = item_change_feed.Site.from_environment(environment if environment is not None else os.environ)
73
+ environment = os.environ if environment is None else environment
74
+ site = item_change_feed.Site.from_environment(environment)
43
75
  result = item_change_feed.handle(event.get("Records", []), decode=decode_image, listeners=lambda: (index or listener_index(site)).document(),
44
- send=send or wake_sender(), site=site)
76
+ send=send or wake_sender(), site=site,
77
+ gate=gate or (wake_gate(site, environment) if event.get("Records") else None))
45
78
  print(json.dumps({"event": "papyrus_item_change_feed", "records": len(event.get("Records", [])), "wakesSent": result["wakesSent"], "failed": len(result["batchItemFailures"])}))
46
79
  return {"batchItemFailures": result["batchItemFailures"]}
@@ -21,7 +21,7 @@ const THEME_KEYS = [
21
21
  "footerWordmarkWidth",
22
22
  ];
23
23
  const KNOWN_KEYS = new Set([
24
- "name", "siteId", "siteOrigin", "basePath", "computeRoleArn", "sendingDomain", "fromAddress", "fromName", "instantAlerts", "theme", "lists",
24
+ "name", "siteId", "siteOrigin", "basePath", "computeRoleArn", "sendingDomain", "fromAddress", "fromName", "theme", "lists",
25
25
  "configurationSet", "eventTopicName", "itemUrlStyle",
26
26
  ]);
27
27
  const LIST_KEYS = {
@@ -169,7 +169,7 @@ export function resolveRule(raw, label) {
169
169
  ...(rule.types === undefined ? {} : { types: stringList(rule.types, `${label}.types`) }),
170
170
  };
171
171
  }
172
- function resolveList(raw, index, instantAlerts) {
172
+ function resolveList(raw, index) {
173
173
  const label = `lists[${index}]`;
174
174
  if (typeof raw !== "object" || raw === null || Array.isArray(raw))
175
175
  fail(`${label} must be an object`);
@@ -198,9 +198,6 @@ function resolveList(raw, index, instantAlerts) {
198
198
  const approval = list.approval === undefined ? "admin" : list.approval;
199
199
  if (approval !== "admin" && approval !== "none")
200
200
  fail(`${label}.approval must be "admin" or "none"`);
201
- if (approval === "none" && !instantAlerts) {
202
- fail(`${label}.approval "none" sends alerts without an admin approving them: set instantAlerts: true on the plugin first`);
203
- }
204
201
  return { ...base, kind, rule: resolveRule(list.rule, `${label}.rule`), approval };
205
202
  }
206
203
  export function resolveNewsletterConfig(request) {
@@ -216,12 +213,9 @@ export function resolveNewsletterConfig(request) {
216
213
  if (extra.length > 0 || !local || local.length > 64 || !LOCAL_PART.test(local) || domain !== sendingDomain) {
217
214
  fail(`fromAddress must be an address on ${sendingDomain} (lowercase, such as newsletter@${sendingDomain})`);
218
215
  }
219
- if (raw.instantAlerts !== undefined && typeof raw.instantAlerts !== "boolean")
220
- fail("instantAlerts must be a boolean");
221
- const instantAlerts = raw.instantAlerts === true;
222
216
  if (!Array.isArray(raw.lists) || raw.lists.length === 0 || raw.lists.length > 20)
223
217
  fail("lists must be a list of 1 to 20 lists");
224
- const lists = raw.lists.map((entry, index) => resolveList(entry, index, instantAlerts));
218
+ const lists = raw.lists.map((entry, index) => resolveList(entry, index));
225
219
  const duplicates = lists.map((list) => list.id).filter((id, index, ids) => ids.indexOf(id) !== index);
226
220
  if (duplicates.length > 0)
227
221
  fail(`lists has duplicate ids: ${[...new Set(duplicates)].join(", ")}`);
@@ -236,7 +230,6 @@ export function resolveNewsletterConfig(request) {
236
230
  sendingDomain,
237
231
  fromAddress,
238
232
  fromName: text(raw.fromName, "fromName", 80),
239
- instantAlerts,
240
233
  theme: resolveTheme(raw.theme),
241
234
  lists,
242
235
  itemUrlStyle: itemUrlStyle(raw.itemUrlStyle),
@@ -85,7 +85,6 @@ export type NewsletterConfig = {
85
85
  fromAddress: string;
86
86
  fromName: string;
87
87
  /** A site must set this to true before any list may send without approval. */
88
- instantAlerts: boolean;
89
88
  theme: NewsletterTheme;
90
89
  lists: NewsletterList[];
91
90
  /** How the site addresses its item pages (`urls.style` in projection.json): roundup drafts link to published items with it. */
@@ -97,7 +96,7 @@ export type NewsletterConfig = {
97
96
  };
98
97
 
99
98
  const KNOWN_KEYS = new Set([
100
- "name", "siteId", "siteOrigin", "basePath", "computeRoleArn", "sendingDomain", "fromAddress", "fromName", "instantAlerts", "theme", "lists",
99
+ "name", "siteId", "siteOrigin", "basePath", "computeRoleArn", "sendingDomain", "fromAddress", "fromName", "theme", "lists",
101
100
  "configurationSet", "eventTopicName", "itemUrlStyle",
102
101
  ]);
103
102
  const LIST_KEYS = {
@@ -235,7 +234,7 @@ export function resolveRule(raw: unknown, label: string): NewsletterRule {
235
234
  };
236
235
  }
237
236
 
238
- function resolveList(raw: unknown, index: number, instantAlerts: boolean): NewsletterList {
237
+ function resolveList(raw: unknown, index: number): NewsletterList {
239
238
  const label = `lists[${index}]`;
240
239
  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) fail(`${label} must be an object`);
241
240
  const kind = (raw as Record<string, unknown>).kind;
@@ -261,9 +260,6 @@ function resolveList(raw: unknown, index: number, instantAlerts: boolean): Newsl
261
260
  }
262
261
  const approval = list.approval === undefined ? "admin" : list.approval;
263
262
  if (approval !== "admin" && approval !== "none") fail(`${label}.approval must be "admin" or "none"`);
264
- if (approval === "none" && !instantAlerts) {
265
- fail(`${label}.approval "none" sends alerts without an admin approving them: set instantAlerts: true on the plugin first`);
266
- }
267
263
  return { ...base, kind, rule: resolveRule(list.rule, `${label}.rule`), approval };
268
264
  }
269
265
 
@@ -280,10 +276,8 @@ export function resolveNewsletterConfig(request: PluginRequest): NewsletterConfi
280
276
  if (extra.length > 0 || !local || local.length > 64 || !LOCAL_PART.test(local) || domain !== sendingDomain) {
281
277
  fail(`fromAddress must be an address on ${sendingDomain} (lowercase, such as newsletter@${sendingDomain})`);
282
278
  }
283
- if (raw.instantAlerts !== undefined && typeof raw.instantAlerts !== "boolean") fail("instantAlerts must be a boolean");
284
- const instantAlerts = raw.instantAlerts === true;
285
279
  if (!Array.isArray(raw.lists) || raw.lists.length === 0 || raw.lists.length > 20) fail("lists must be a list of 1 to 20 lists");
286
- const lists = raw.lists.map((entry, index) => resolveList(entry, index, instantAlerts));
280
+ const lists = raw.lists.map((entry, index) => resolveList(entry, index));
287
281
  const duplicates = lists.map((list) => list.id).filter((id, index, ids) => ids.indexOf(id) !== index);
288
282
  if (duplicates.length > 0) fail(`lists has duplicate ids: ${[...new Set(duplicates)].join(", ")}`);
289
283
  const roundups = lists.filter((list) => list.kind === "roundup");
@@ -296,7 +290,6 @@ export function resolveNewsletterConfig(request: PluginRequest): NewsletterConfi
296
290
  sendingDomain,
297
291
  fromAddress,
298
292
  fromName: text(raw.fromName, "fromName", 80),
299
- instantAlerts,
300
293
  theme: resolveTheme(raw.theme),
301
294
  lists,
302
295
  itemUrlStyle: itemUrlStyle(raw.itemUrlStyle),
@@ -71,7 +71,6 @@ export function newsletterEnvironment(config, tableName, keyParameter) {
71
71
  FROM_NAME: config.fromName,
72
72
  CONFIGURATION_SET: config.configurationSet,
73
73
  ITEM_URL_STYLE: config.itemUrlStyle,
74
- INSTANT_ALERTS: config.instantAlerts ? "true" : "false",
75
74
  LISTS_JSON: JSON.stringify(config.lists.map((list) => ({
76
75
  id: list.id,
77
76
  name: list.name,
@@ -84,7 +84,6 @@ export function newsletterEnvironment(config: NewsletterConfig, tableName: strin
84
84
  FROM_NAME: config.fromName,
85
85
  CONFIGURATION_SET: config.configurationSet,
86
86
  ITEM_URL_STYLE: config.itemUrlStyle,
87
- INSTANT_ALERTS: config.instantAlerts ? "true" : "false",
88
87
  LISTS_JSON: JSON.stringify(
89
88
  config.lists.map((list) => ({
90
89
  id: list.id,
@@ -1,7 +1,7 @@
1
1
  """Bundle entry kept for the shared Python bundler, which copies ``handler.py`` to the asset root.
2
2
 
3
- The Lambdas' handlers are ``papyrus_content.notifications.handler.{router,email,flush,ses_events}``
3
+ The Lambdas' handlers are ``papyrus_content.notifications.handler.{router,email,x,flush,ses_events}``
4
4
  (src/papyrus_content/notifications/handler.py).
5
5
  """
6
6
 
7
- from papyrus_content.notifications.handler import email, flush, router, ses_events # noqa: F401
7
+ from papyrus_content.notifications.handler import email, flush, router, ses_events, x # noqa: F401
@@ -17,11 +17,14 @@ import { ALARM_MINIMUM_SENDS, BOUNCE_RATE_THRESHOLD, COMPLAINT_RATE_THRESHOLD }
17
17
  import { postalAddressParameterArns } from "../newsletter/sending.js";
18
18
  import { resolveNotificationsConfig } from "./config.js";
19
19
  import { siteApiEnvironment } from "../../site-api-access.js";
20
+ import { X_ENDPOINTS, announcementsParameterPrefix } from "../../functions/announcements/wire.js";
21
+ import { ANNOUNCEMENTS_TIMEOUT_SECONDS } from "../../functions/announcements/resource.js";
20
22
  export { resolveNotificationsConfig };
21
23
  export const NOTIFICATIONS_OUTPUT_KEY = "notifications";
22
24
  export const HANDLERS = {
23
25
  router: "papyrus_content.notifications.handler.router",
24
26
  email: "papyrus_content.notifications.handler.email",
27
+ x: "papyrus_content.notifications.handler.x",
25
28
  flush: "papyrus_content.notifications.handler.flush",
26
29
  sesEvents: "papyrus_content.notifications.handler.ses_events",
27
30
  pause: "papyrus_content.notifications.handler.pause",
@@ -33,6 +36,9 @@ export const NOTIFICATIONS_REQUIREMENTS = [CADUCUS_REQUIREMENT, "PyYAML>=6.0.2,<
33
36
  const FUNCTION_DIRECTORY = "../plugins/notifications/function";
34
37
  export const EMAIL_TIMEOUT_SECONDS = 120;
35
38
  export const EMAIL_MAX_RECEIVE_COUNT = 3;
39
+ /** One post can wait out X's rate limit inside the consumer (Caducus sleeps until `x-rate-limit-reset`), and X's windows are fifteen minutes: the Lambda maximum. */
40
+ export const X_TIMEOUT_SECONDS = 900;
41
+ export const X_MAX_RECEIVE_COUNT = 3;
36
42
  export const notificationsManifest = {
37
43
  name: "notifications",
38
44
  contract: 1,
@@ -50,6 +56,7 @@ export function overrideNotificationsCodeForTests(code) {
50
56
  }
51
57
  export const notificationsFunctionName = (siteId) => `papyrus-notifications-${siteId}`;
52
58
  export const notificationsEmailName = (siteId) => `papyrus-notifications-email-${siteId}`;
59
+ export const notificationsXName = (siteId) => `papyrus-notifications-x-${siteId}`;
53
60
  export const notificationsFlushName = (siteId) => `papyrus-notifications-flush-${siteId}`;
54
61
  export const notificationsSesEventsName = (siteId) => `papyrus-notifications-ses-${siteId}`;
55
62
  export const notificationsPauseName = (siteId) => `papyrus-notifications-pause-${siteId}`;
@@ -62,6 +69,7 @@ export const notificationsKeyParameterName = (siteId) => `/papyrus/${siteId}/not
62
69
  export const legacyNewsletterKeyParameterName = (siteId) => `/papyrus/${siteId}/newsletter-key`;
63
70
  export const notificationsAlarmNames = (siteId) => ({
64
71
  emailDeadLetters: `papyrus-notifications-${siteId}-email-dlq`,
72
+ xDeadLetters: `papyrus-notifications-${siteId}-x-dlq`,
65
73
  routerDeadLetters: `papyrus-notifications-${siteId}-router-dlq`,
66
74
  });
67
75
  /** The pause alarms, created only where the newsletter plugin is absent (python: `pause.alarm_names`). */
@@ -182,6 +190,22 @@ export const notificationsPlugin = {
182
190
  enforceSSL: true,
183
191
  deadLetterQueue: { queue: emailDeadLetters, maxReceiveCount: EMAIL_MAX_RECEIVE_COUNT },
184
192
  });
193
+ // X: its own queue, so one consumer at a time posts for the site's one account (the budget is charged one post after another), and its dead letter queue.
194
+ const xDeadLetters = new Queue(stack, "XDeadLetterQueue", {
195
+ queueName: `papyrus-notifications-${config.siteId}-x-dlq`,
196
+ retentionPeriod: Duration.days(14),
197
+ encryption: QueueEncryption.SQS_MANAGED,
198
+ enforceSSL: true,
199
+ });
200
+ const xQueue = new Queue(stack, "XQueue", {
201
+ queueName: `papyrus-notifications-${config.siteId}-x`,
202
+ visibilityTimeout: Duration.seconds(X_TIMEOUT_SECONDS * 6),
203
+ encryption: QueueEncryption.SQS_MANAGED,
204
+ enforceSSL: true,
205
+ deadLetterQueue: { queue: xDeadLetters, maxReceiveCount: X_MAX_RECEIVE_COUNT },
206
+ });
207
+ // The announcements function's model tables: the settings (pause, budget, prices), the account connection and the spend counter. The consumer has no signed-in person, so it reads and writes them with its own role.
208
+ const announcementTables = backend.data.resources.tables;
185
209
  const routerDeadLetters = new Queue(stack, "RouterDeadLetterQueue", {
186
210
  queueName: `papyrus-notifications-${config.siteId}-router-dlq`,
187
211
  retentionPeriod: Duration.days(14),
@@ -191,6 +215,12 @@ export const notificationsPlugin = {
191
215
  const environment = {
192
216
  ...notificationsEnvironment(config, { table: table.tableName, operators: operatorsParameter, key: keyParameter.parameterName }),
193
217
  EMAIL_QUEUE_URL: emailQueue.queueUrl,
218
+ X_QUEUE_URL: xQueue.queueUrl,
219
+ ...X_ENDPOINTS,
220
+ ANNOUNCEMENT_SETTINGS_TABLE: announcementTables.AnnouncementSettings.tableName,
221
+ X_CONNECTION_TABLE: announcementTables.XConnection.tableName,
222
+ ANNOUNCEMENT_SPEND_TABLE: announcementTables.AnnouncementSpend.tableName,
223
+ X_REFRESH_LEASE_SECONDS: String(ANNOUNCEMENTS_TIMEOUT_SECONDS),
194
224
  ...siteApiEnvironment(context.graphqlEndpoint),
195
225
  };
196
226
  const common = { runtime: Runtime.PYTHON_3_12, architecture: Architecture.ARM_64, code, environment };
@@ -215,6 +245,17 @@ export const notificationsPlugin = {
215
245
  description: `Mails queued notifications for ${config.siteId}, paced under the SES send rate`,
216
246
  });
217
247
  email.addEventSource(new SqsEventSource(emailQueue, { batchSize: 10, reportBatchItemFailures: true }));
248
+ const x = new LambdaFunction(stack, "XFunction", {
249
+ ...common,
250
+ functionName: notificationsXName(config.siteId),
251
+ handler: HANDLERS.x,
252
+ timeout: Duration.seconds(X_TIMEOUT_SECONDS),
253
+ memorySize: 512,
254
+ // One post at a time: the budget is charged one post after another, and a post whose outcome is unknown is checked before it is repeated.
255
+ reservedConcurrentExecutions: 1,
256
+ description: `Posts queued announcements for ${config.siteId} to its connected X account`,
257
+ });
258
+ x.addEventSource(new SqsEventSource(xQueue, { batchSize: 1, reportBatchItemFailures: true }));
218
259
  const flush = new LambdaFunction(stack, "FlushFunction", {
219
260
  ...common,
220
261
  functionName: notificationsFlushName(config.siteId),
@@ -255,13 +296,24 @@ export const notificationsPlugin = {
255
296
  parameterArns.push(`arn:${stack.partition}:ssm:${stack.region}:${stack.account}:parameter${legacyNewsletterKeyParameterName(config.siteId)}`);
256
297
  }
257
298
  // Every function builds the same runtime (the audience needs the recipient key), and the SES events suppress readers.
258
- for (const fn of [router, email, flush, sesEvents]) {
299
+ for (const fn of [router, email, x, flush, sesEvents]) {
259
300
  table.grantReadWriteData(fn); // includes the table key's encrypt and decrypt
260
301
  fn.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: ["ssm:GetParameter"], resources: parameterArns }));
261
302
  }
262
303
  // A reader who lifts a bounce or complaint by opting in again is cleared from the SES account suppression list too.
263
304
  // The action has no resource-level form (as for the newsletter function).
264
305
  router.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: ["ses:DeleteSuppressedDestination"], resources: ["*"] }));
306
+ // The X consumer reads the account's connection, its token parameters (a refresh saves the next one), the settings and the spend counter, and nothing else of the site's.
307
+ announcementTables.AnnouncementSettings.grantReadData(x);
308
+ announcementTables.XConnection.grantReadWriteData(x); // a refresh takes the connection's lease and records its result
309
+ announcementTables.AnnouncementSettings.grantReadWriteData(x); // a refresh X refuses pauses announcements
310
+ announcementTables.AnnouncementSpend.grantReadWriteData(x);
311
+ x.addToRolePolicy(new PolicyStatement({
312
+ effect: Effect.ALLOW,
313
+ actions: ["ssm:GetParameter", "ssm:PutParameter"],
314
+ resources: [`arn:${stack.partition}:ssm:${stack.region}:${stack.account}:parameter${announcementsParameterPrefix(config.siteId)}/*`],
315
+ }));
316
+ xQueue.grantSendMessages(router);
265
317
  emailQueue.grantSendMessages(router);
266
318
  emailQueue.grantSendMessages(flush);
267
319
  emailQueue.grantSendMessages(email); // a fan-out page queues its deliveries and the next page
@@ -339,6 +391,7 @@ export const notificationsPlugin = {
339
391
  const alarmNames = notificationsAlarmNames(config.siteId);
340
392
  for (const [id, alarmName, queue] of [
341
393
  ["EmailDeadLetterAlarm", alarmNames.emailDeadLetters, emailDeadLetters],
394
+ ["XDeadLetterAlarm", alarmNames.xDeadLetters, xDeadLetters],
342
395
  ["RouterDeadLetterAlarm", alarmNames.routerDeadLetters, routerDeadLetters],
343
396
  ]) {
344
397
  new Alarm(stack, id, {
@@ -359,7 +412,7 @@ export const notificationsPlugin = {
359
412
  }
360
413
  // The CMS routes are the only caller: a publish tells this function nothing (the announce agent is woken by the Item change feed).
361
414
  router.addPermission("InvokeFromCmsCompute", { principal: new ArnPrincipal(config.computeRoleArn), action: "lambda:InvokeFunction" });
362
- backend.addOutput({ custom: { [NOTIFICATIONS_OUTPUT_KEY]: { actionsFunction: router.functionName } } });
415
+ backend.addOutput({ custom: { [NOTIFICATIONS_OUTPUT_KEY]: { actionsFunction: router.functionName, xQueueUrl: xQueue.queueUrl } } });
363
416
  },
364
417
  };
365
418
  function installRequirements(requirementsPath, outputDir) {
@@ -7,6 +7,7 @@ import { ArnPrincipal, Effect, PolicyStatement } from "aws-cdk-lib/aws-iam";
7
7
  import { Key } from "aws-cdk-lib/aws-kms";
8
8
  import { Architecture, type Code, Function as LambdaFunction, Runtime } from "aws-cdk-lib/aws-lambda";
9
9
  import { SqsEventSource } from "aws-cdk-lib/aws-lambda-event-sources";
10
+ import type { ITable } from "aws-cdk-lib/aws-dynamodb";
10
11
  import { Queue, QueueEncryption } from "aws-cdk-lib/aws-sqs";
11
12
  import { execFileSync } from "node:child_process";
12
13
  import path from "node:path";
@@ -18,6 +19,8 @@ import { postalAddressParameterArns } from "../newsletter/sending";
18
19
  import type { PapyrusPlugin, PluginManifest, PluginWiringContext } from "../types";
19
20
  import { resolveNotificationsConfig, type NotificationsConfig } from "./config";
20
21
  import { siteApiEnvironment } from "../../site-api-access";
22
+ import { X_ENDPOINTS, announcementsParameterPrefix } from "../../functions/announcements/wire";
23
+ import { ANNOUNCEMENTS_TIMEOUT_SECONDS } from "../../functions/announcements/resource";
21
24
 
22
25
  export { resolveNotificationsConfig };
23
26
  export type { NotificationsConfig };
@@ -26,6 +29,7 @@ export const NOTIFICATIONS_OUTPUT_KEY = "notifications";
26
29
  export const HANDLERS = {
27
30
  router: "papyrus_content.notifications.handler.router",
28
31
  email: "papyrus_content.notifications.handler.email",
32
+ x: "papyrus_content.notifications.handler.x",
29
33
  flush: "papyrus_content.notifications.handler.flush",
30
34
  sesEvents: "papyrus_content.notifications.handler.ses_events",
31
35
  pause: "papyrus_content.notifications.handler.pause",
@@ -37,6 +41,9 @@ export const NOTIFICATIONS_REQUIREMENTS = [CADUCUS_REQUIREMENT, "PyYAML>=6.0.2,<
37
41
  const FUNCTION_DIRECTORY = "../plugins/notifications/function";
38
42
  export const EMAIL_TIMEOUT_SECONDS = 120;
39
43
  export const EMAIL_MAX_RECEIVE_COUNT = 3;
44
+ /** One post can wait out X's rate limit inside the consumer (Caducus sleeps until `x-rate-limit-reset`), and X's windows are fifteen minutes: the Lambda maximum. */
45
+ export const X_TIMEOUT_SECONDS = 900;
46
+ export const X_MAX_RECEIVE_COUNT = 3;
40
47
 
41
48
  export const notificationsManifest: PluginManifest = {
42
49
  name: "notifications",
@@ -58,6 +65,7 @@ export function overrideNotificationsCodeForTests(code?: Code): void {
58
65
 
59
66
  export const notificationsFunctionName = (siteId: string) => `papyrus-notifications-${siteId}`;
60
67
  export const notificationsEmailName = (siteId: string) => `papyrus-notifications-email-${siteId}`;
68
+ export const notificationsXName = (siteId: string) => `papyrus-notifications-x-${siteId}`;
61
69
  export const notificationsFlushName = (siteId: string) => `papyrus-notifications-flush-${siteId}`;
62
70
  export const notificationsSesEventsName = (siteId: string) => `papyrus-notifications-ses-${siteId}`;
63
71
  export const notificationsPauseName = (siteId: string) => `papyrus-notifications-pause-${siteId}`;
@@ -70,6 +78,7 @@ export const notificationsKeyParameterName = (siteId: string) => `/papyrus/${sit
70
78
  export const legacyNewsletterKeyParameterName = (siteId: string) => `/papyrus/${siteId}/newsletter-key`;
71
79
  export const notificationsAlarmNames = (siteId: string) => ({
72
80
  emailDeadLetters: `papyrus-notifications-${siteId}-email-dlq`,
81
+ xDeadLetters: `papyrus-notifications-${siteId}-x-dlq`,
73
82
  routerDeadLetters: `papyrus-notifications-${siteId}-router-dlq`,
74
83
  });
75
84
 
@@ -201,6 +210,22 @@ export const notificationsPlugin: PapyrusPlugin<NotificationsConfig, Record<stri
201
210
  enforceSSL: true,
202
211
  deadLetterQueue: { queue: emailDeadLetters, maxReceiveCount: EMAIL_MAX_RECEIVE_COUNT },
203
212
  });
213
+ // X: its own queue, so one consumer at a time posts for the site's one account (the budget is charged one post after another), and its dead letter queue.
214
+ const xDeadLetters = new Queue(stack, "XDeadLetterQueue", {
215
+ queueName: `papyrus-notifications-${config.siteId}-x-dlq`,
216
+ retentionPeriod: Duration.days(14),
217
+ encryption: QueueEncryption.SQS_MANAGED,
218
+ enforceSSL: true,
219
+ });
220
+ const xQueue = new Queue(stack, "XQueue", {
221
+ queueName: `papyrus-notifications-${config.siteId}-x`,
222
+ visibilityTimeout: Duration.seconds(X_TIMEOUT_SECONDS * 6),
223
+ encryption: QueueEncryption.SQS_MANAGED,
224
+ enforceSSL: true,
225
+ deadLetterQueue: { queue: xDeadLetters, maxReceiveCount: X_MAX_RECEIVE_COUNT },
226
+ });
227
+ // The announcements function's model tables: the settings (pause, budget, prices), the account connection and the spend counter. The consumer has no signed-in person, so it reads and writes them with its own role.
228
+ const announcementTables = backend.data.resources.tables as Record<string, ITable>;
204
229
  const routerDeadLetters = new Queue(stack, "RouterDeadLetterQueue", {
205
230
  queueName: `papyrus-notifications-${config.siteId}-router-dlq`,
206
231
  retentionPeriod: Duration.days(14),
@@ -211,6 +236,12 @@ export const notificationsPlugin: PapyrusPlugin<NotificationsConfig, Record<stri
211
236
  const environment = {
212
237
  ...notificationsEnvironment(config, { table: table.tableName, operators: operatorsParameter, key: keyParameter.parameterName }),
213
238
  EMAIL_QUEUE_URL: emailQueue.queueUrl,
239
+ X_QUEUE_URL: xQueue.queueUrl,
240
+ ...X_ENDPOINTS,
241
+ ANNOUNCEMENT_SETTINGS_TABLE: announcementTables.AnnouncementSettings.tableName,
242
+ X_CONNECTION_TABLE: announcementTables.XConnection.tableName,
243
+ ANNOUNCEMENT_SPEND_TABLE: announcementTables.AnnouncementSpend.tableName,
244
+ X_REFRESH_LEASE_SECONDS: String(ANNOUNCEMENTS_TIMEOUT_SECONDS),
214
245
  ...siteApiEnvironment(context.graphqlEndpoint),
215
246
  };
216
247
  const common = { runtime: Runtime.PYTHON_3_12, architecture: Architecture.ARM_64, code, environment };
@@ -235,6 +266,17 @@ export const notificationsPlugin: PapyrusPlugin<NotificationsConfig, Record<stri
235
266
  description: `Mails queued notifications for ${config.siteId}, paced under the SES send rate`,
236
267
  });
237
268
  email.addEventSource(new SqsEventSource(emailQueue, { batchSize: 10, reportBatchItemFailures: true }));
269
+ const x = new LambdaFunction(stack, "XFunction", {
270
+ ...common,
271
+ functionName: notificationsXName(config.siteId),
272
+ handler: HANDLERS.x,
273
+ timeout: Duration.seconds(X_TIMEOUT_SECONDS),
274
+ memorySize: 512,
275
+ // One post at a time: the budget is charged one post after another, and a post whose outcome is unknown is checked before it is repeated.
276
+ reservedConcurrentExecutions: 1,
277
+ description: `Posts queued announcements for ${config.siteId} to its connected X account`,
278
+ });
279
+ x.addEventSource(new SqsEventSource(xQueue, { batchSize: 1, reportBatchItemFailures: true }));
238
280
  const flush = new LambdaFunction(stack, "FlushFunction", {
239
281
  ...common,
240
282
  functionName: notificationsFlushName(config.siteId),
@@ -276,13 +318,26 @@ export const notificationsPlugin: PapyrusPlugin<NotificationsConfig, Record<stri
276
318
  parameterArns.push(`arn:${stack.partition}:ssm:${stack.region}:${stack.account}:parameter${legacyNewsletterKeyParameterName(config.siteId)}`);
277
319
  }
278
320
  // Every function builds the same runtime (the audience needs the recipient key), and the SES events suppress readers.
279
- for (const fn of [router, email, flush, sesEvents]) {
321
+ for (const fn of [router, email, x, flush, sesEvents]) {
280
322
  table.grantReadWriteData(fn); // includes the table key's encrypt and decrypt
281
323
  fn.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: ["ssm:GetParameter"], resources: parameterArns }));
282
324
  }
283
325
  // A reader who lifts a bounce or complaint by opting in again is cleared from the SES account suppression list too.
284
326
  // The action has no resource-level form (as for the newsletter function).
285
327
  router.addToRolePolicy(new PolicyStatement({ effect: Effect.ALLOW, actions: ["ses:DeleteSuppressedDestination"], resources: ["*"] }));
328
+ // The X consumer reads the account's connection, its token parameters (a refresh saves the next one), the settings and the spend counter, and nothing else of the site's.
329
+ announcementTables.AnnouncementSettings.grantReadData(x);
330
+ announcementTables.XConnection.grantReadWriteData(x); // a refresh takes the connection's lease and records its result
331
+ announcementTables.AnnouncementSettings.grantReadWriteData(x); // a refresh X refuses pauses announcements
332
+ announcementTables.AnnouncementSpend.grantReadWriteData(x);
333
+ x.addToRolePolicy(
334
+ new PolicyStatement({
335
+ effect: Effect.ALLOW,
336
+ actions: ["ssm:GetParameter", "ssm:PutParameter"],
337
+ resources: [`arn:${stack.partition}:ssm:${stack.region}:${stack.account}:parameter${announcementsParameterPrefix(config.siteId)}/*`],
338
+ }),
339
+ );
340
+ xQueue.grantSendMessages(router);
286
341
  emailQueue.grantSendMessages(router);
287
342
  emailQueue.grantSendMessages(flush);
288
343
  emailQueue.grantSendMessages(email); // a fan-out page queues its deliveries and the next page
@@ -369,6 +424,7 @@ export const notificationsPlugin: PapyrusPlugin<NotificationsConfig, Record<stri
369
424
  const alarmNames = notificationsAlarmNames(config.siteId);
370
425
  for (const [id, alarmName, queue] of [
371
426
  ["EmailDeadLetterAlarm", alarmNames.emailDeadLetters, emailDeadLetters],
427
+ ["XDeadLetterAlarm", alarmNames.xDeadLetters, xDeadLetters],
372
428
  ["RouterDeadLetterAlarm", alarmNames.routerDeadLetters, routerDeadLetters],
373
429
  ] as const) {
374
430
  new Alarm(stack, id, {
@@ -391,7 +447,7 @@ export const notificationsPlugin: PapyrusPlugin<NotificationsConfig, Record<stri
391
447
  // The CMS routes are the only caller: a publish tells this function nothing (the announce agent is woken by the Item change feed).
392
448
  router.addPermission("InvokeFromCmsCompute", { principal: new ArnPrincipal(config.computeRoleArn), action: "lambda:InvokeFunction" });
393
449
 
394
- backend.addOutput({ custom: { [NOTIFICATIONS_OUTPUT_KEY]: { actionsFunction: router.functionName } } });
450
+ backend.addOutput({ custom: { [NOTIFICATIONS_OUTPUT_KEY]: { actionsFunction: router.functionName, xQueueUrl: xQueue.queueUrl } } });
395
451
  },
396
452
  };
397
453
 
@@ -55,6 +55,7 @@ export type ImageOperationName =
55
55
  | "announcements_recent"
56
56
  | "announcements_explain"
57
57
  | "ratings_set"
58
+ | "handoffs_request"
58
59
  ;
59
60
 
60
61
  export type ImageErrorCode =
@@ -1589,6 +1590,26 @@ export type RatingsSetResult = {
1589
1590
  ratedBy?: string;
1590
1591
  };
1591
1592
 
1593
+ /** Ask another responsibility for one piece of work on a Story. It appears on the Story as an Assignment that says who asked and why, and wakes the responsible agent once. */
1594
+ export type HandoffsRequestInput = {
1595
+ /** The lineage id of the Story. */
1596
+ story: string;
1597
+ /** The responsibility asked, as the agent catalogue names it, such as research. */
1598
+ responsibility: string;
1599
+ /** What is needed and why, in plain words. It is the Assignment's brief and what the responsible agent reads. */
1600
+ why: string;
1601
+ };
1602
+
1603
+ export type HandoffsRequestResult = {
1604
+ assignmentId: string;
1605
+ responsibility: string;
1606
+ story: string;
1607
+ status: string;
1608
+ askedBy: string;
1609
+ /** False when the same ask was already made: nothing new was written and nobody is woken again. */
1610
+ created: boolean;
1611
+ };
1612
+
1592
1613
  export interface ImageOperations {
1593
1614
  image_profile_get: { input: ImageProfileGetInput; result: ImageProfileGetResult };
1594
1615
  image_profile_resolve: { input: ImageProfileResolveInput; result: ImageProfileResolveResult };
@@ -1642,6 +1663,7 @@ export interface ImageOperations {
1642
1663
  announcements_recent: { input: AnnouncementsRecentInput; result: AnnouncementsRecentResult };
1643
1664
  announcements_explain: { input: AnnouncementsExplainInput; result: AnnouncementsExplainResult };
1644
1665
  ratings_set: { input: RatingsSetInput; result: RatingsSetResult };
1666
+ handoffs_request: { input: HandoffsRequestInput; result: HandoffsRequestResult };
1645
1667
  }
1646
1668
 
1647
1669
  /** What each operation is, for the transport: read operations are queries, write and spend operations are mutations. */
@@ -1698,14 +1720,15 @@ export const IMAGE_OPERATIONS = {
1698
1720
  announcements_recent: { effect: "read", agentAllowed: true, agentRung: "observe", agentRefusal: "human_required", group: "announcements", command: "papyrus announcements recent" },
1699
1721
  announcements_explain: { effect: "read", agentAllowed: true, agentRung: "observe", agentRefusal: "human_required", group: "announcements", command: "papyrus announcements explain" },
1700
1722
  ratings_set: { effect: "write", agentAllowed: true, agentRung: "draft", agentRefusal: "human_required", group: "ratings", command: "papyrus ratings set" },
1723
+ handoffs_request: { effect: "write", agentAllowed: true, agentRung: "propose", agentRefusal: "human_required", group: "handoffs", command: "papyrus handoffs request" },
1701
1724
  } as const;
1702
1725
 
1703
- /** `group` says which door: images go through imageRead and imageWrite, guidelines through guidelinesRead and guidelinesWrite; announcements and ratings have no door yet (the console reads and writes their models directly). */
1726
+ /** `group` says which door: images go through imageRead and imageWrite, guidelines through guidelinesRead and guidelinesWrite; announcements, ratings and handoffs have no door yet (the console reads and writes their models directly). */
1704
1727
  export type ImageTransport = (request: {
1705
1728
  op: ImageOperationName;
1706
1729
  input: unknown;
1707
1730
  effect: "read" | "write" | "spend";
1708
- group: "images" | "guidelines" | "announcements" | "ratings";
1731
+ group: "images" | "guidelines" | "announcements" | "ratings" | "handoffs";
1709
1732
  }) => Promise<unknown>;
1710
1733
 
1711
1734
  export async function callImageOperation<Name extends ImageOperationName>(
package/package.json CHANGED
@@ -650,7 +650,7 @@
650
650
  "optional": true
651
651
  }
652
652
  },
653
- "version": "5.135.0",
653
+ "version": "5.136.0-next.2",
654
654
  "dependencies": {
655
655
  "@aws-amplify/adapter-nextjs": "^1.7.3",
656
656
  "@aws-crypto/sha256-js": "5.2.0",
@@ -1,5 +1,5 @@
1
1
  {
2
- "version": "5.135.0",
2
+ "version": "5.136.0-next.2",
3
3
  "routes": [
4
4
  {
5
5
  "file": "app/%5F_preview/[[...path]]/route.ts",