[thenom]

Issue #, if available: Closes #689

Description of changes:

Problem

Nothing outside the platform can react to what happens in it without polling the API. Common asks are a chat message when a gate is waiting for a human, a notice when a discussion is resolved, or an audit record when a space is created.

Solution

An opt-in outbound event feed on Amazon EventBridge. The platform publishes, and integrations subscribe with their own rules, in this deployment or another.

Terraform (root variables, all optional):

• notification_events_enabled (default false) creates an aws_cloudwatch_event_bus in modules/api/lambda.
• notification_event_bus_name (default empty, which means <project_name>-<environment>-events).
• notification_event_source (default collaborative-ai-dlc). It's validated, and must not start with aws..
• Only the three publishing Lambdas (projects, discussions, v2-orchestrator) get NOTIFICATION_EVENT_BUS, NOTIFICATION_EVENT_SOURCE, and a separate events:PutEvents policy on that bus alone.
• New root outputs: notification_event_bus_name and notification_event_bus_arn.

Events:

Detail type	When
space.created	a space is created
gate.pending	an intent waits for a human: an agent question or checkpoint, or an engine gate (validation, walking skeleton, batch, autonomy ladder, lane failure)
discussion.message	a message is posted to an intent discussion
discussion.resolved	an intent discussion is resolved

Every detail has schemaVersion (1) and an eventId for deduplication. gate.pending also carries need (answer for an agent question, approval for checkpoints and engine gates), kind, stage, intentTitle, startedBy and prompt (an agent question's first question), so a consumer can render a useful message without calling back into the API.

docs/using-the-platform/notification-events.md, added to the nav, documents every detail field, delivery semantics (normally once, at least once) and an example rule.

Publishing (lambda/shared/notification-events.js) is best-effort:

• It never throws and gives up after two seconds. A missing bus, missing permission or EventBridge error only logs a warning, so the triggering action is never affected.
• With no bus configured it does nothing and never loads the EventBridge client.
• In the orchestrator, agent gates publish from a new durable step that only runs when a bus is configured. Engine gates publish from inside their existing gate-open step. Either way, without a bus the step sequence of existing executions is unchanged.

@aws-sdk/client-eventbridge is added to the root devDependencies at the version the other clients use (^3.1106.0). That's where lambda/shared resolves its clients. The projects and v2-orchestrator bundles include it, and discussions uses the runtime's SDK like its other clients.

Testing

• lambda/shared/test/notification-events.test.js covers no bus (no client load), the entry shape and default source, a custom source, rejected entries, send failures, client load failures, the real client loaded lazily, and the gate.pending detail: need, the prompt from a questions array, clipping, and reading the gate and META only when not given them.
• lambda/v2-orchestrator/test/engine-gate-notification.test.js covers engine gates: one publish per gate with the expected detail, nothing when the run was replaced, and an identical step sequence with and without a bus.
• npm run lint, npm run format:check, and the discussions, projects, v2-orchestrator and shared vitest projects pass, including bundle-smoke.test.js. The projects and discussions bundles also import cleanly with a bus configured.
• terraform fmt -check, terraform validate -no-tests and every terraform test suite from the Terraform workflow pass on Terraform 1.15.0, as does the SSO plan-privacy test. There's no new Terraform test: a plan of modules/api/lambda builds every Lambda package.
• The same events run in our own deployment, feeding Microsoft Teams notifications.

Impact

Disabled (the default), nothing is created and no Lambda's configuration changes. Event details include user names, email addresses and message text; the docs page says so.

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[eipasteur]

I’m requesting changes before merge for these two issues affecting project attribution and human-gate handling.

lambda/discussions/handlers.js:517

[P2] Discussion events can be attributed to an unauthorized project

authorizeScope resolves the intent’s actual project and checks membership there, but scope.projectId still comes from the URL. A member of project A can therefore post to an A discussion through /projects/B/intents/intent-A/... and emit an event labelled as project B; the resolution event has the same issue at line 943. That gives project-filtered integrations a false attribution. Using the canonical auth.projectId in both payloads, or rejecting the path mismatch, would preserve the authorization boundary.

---

lambda/shared/notification-events.js:153–156

[P2] Optional gate enrichment can outlast the notification deadline

These reads finish before the two-second EventBridge timeout starts. Engine gates supply the gate but not META, so a slow getExecution keeps the gate-open step waiting before its callback is created; agent gates similarly wait on getHumanTask. This makes optional notification work delay the gate beyond the documented bound. An overall deadline covering enrichment and publication would protect that behavior, with a slow-read case providing useful regression coverage.

[thenom]

Thanks @eipasteur, both fixed in 8e9d3ee.

Discussion event attribution (lambda/discussions/handlers.js): discussion.message and discussion.resolved now take projectId from auth.projectId (the intent's own project, the one authorizeScope checked membership on) rather than the URL. A new test in discussions.test.js posts and resolves through a path with a different project id and checks both events carry the intent's real project.

Gate enrichment deadline (lambda/shared/notification-events.js): notifyGatePending now runs the optional reads and the publish under one two-second deadline. The gate and META reads get the first second; a read that is still running then is dropped and its fields go out as null, so a slow read can't delay the gate. publishNotificationEvent's deadline now also covers loading the EventBridge client, and the caller can pass its own signal. New tests cover a slow read that is dropped while the event still publishes, a hung read with a hung publish giving up together, and the real default deadline (about two seconds overall). The docs page says the same.

[github-actions]

Automatically computed PR review signals (deterministic)

Complexity and branch coverage help focus review on functions and their tests; these signals are advisory.

Complexity and test coverage

5 changed JS/TS files analyzed · 4 flagged functions.
Coverage unavailable; test protection cannot be compared.

	File / function	Complexity	Δ	Branch coverage	Δ	Uncovered branches	Depending files
🟠	lambda/v2-orchestrator/section.js:240 — awaitEngineGate / <anonymous>	— → 24	—	—	—	—	1
🟠	lambda/discussions/handlers.js:361 — postMessage	45 → 48	+3	—	—	—	1
🟠	lambda/v2-orchestrator/index.js:880 — handler / executeStage	42 → 45	+3	—	—	—	0
🟠	lambda/discussions/handlers.js:868 — updateDiscussion	15 → 17	+2	—	—	—	1

🟢 Improving · 🟠 Needs attention · 🔴 High risk · 🟣 Highest risk

— = unavailable · n/a = not applicable · * = incomplete tests

---

Isobar repository map

This fixed repository map locates changed files and their possible reach through static links.
Red marks changed files; green marks static links, not proven runtime impact or a risk grade.

Isobar by r3al1tym.

Signals

• A: lambda/discussions/handlers.js — modified file · 1 static name-match target.
• B: lambda/v2-orchestrator/index.js — modified file · 14 static name-match targets.
• Total static reach: 2 unchanged production files; 22 unchanged test files.
• Static reach unavailable for 8 changed files.
• Revision: 8e9d3ee; updated 2026-11-04 18:00 UTC.

Legend

• ○ modified · ◇ added · × deleted. Blue markers: tests; gray markers: documentation.
• Solid green: import-linked name matches. Dotted green: broader file-level import fallback.

Full report artifacts