@nettee/beacon 0.2.9 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Beacon
 
-Beacon is a single-host service that turns Feishu messages and configured schedules into isolated Pi agent runs. Each accepted Trigger is durably claimed, produces an explicit Final Outcome, and may `reply_text` / `reply_card` to a person, `notify_card` a group, or stay silent on the admin channel.
+Beacon is a single-host service that turns Feishu messages, configured schedules, and subscribed CloudEvents into isolated Pi agent runs. Each accepted Trigger is durably claimed, produces an explicit Final Outcome, and may `reply_text` / `reply_card` to a person, `notify_card` a group, or stay silent on the admin channel.
 
 This repository currently implements the Feishu + Pi MVP described by the
 [Zest Dev Spec](https://github.com/nettee/beacon/blob/main/specs/change/20260913-beacon-feishu-pi-mvp/spec.md).
@@ -67,7 +67,7 @@ back to `prompt.md`. If neither place has a complete pair, Profile load fails
 and lists the missing paths. Both pairs may exist; the workspace pair wins.
 
 Beacon prepends an English platform template for this Run: workspace limit,
-inbound vs Schedule vs manual capabilities, the `reply_text` / `reply_card` /
+inbound vs Schedule vs event vs manual capabilities, the `reply_text` / `reply_card` /
 `no_reply` / `notify_card` contract, and an optional `submit_feedback` tool.
 
 Protect the home and secret file before running Beacon:
@@ -120,6 +120,166 @@ the current time.
 After sleep or restart, overdue occurrences are reconciled and coalesced to the
 most recent one.
 
+## Event triggers
+
+Beacon accepts CloudEvents on a dedicated, opt-in HTTP server. A Profile's
+optional `listener` selects the events it receives; Profiles without a listener
+never receive external events. Direct Feishu/manual inputs and Schedules keep
+using their existing paths:
+
+```text
+CloudEvent → authenticate → match + persist recipients ─────┐
+Time       → Schedule due ──────────────────────────────────┼→ Trigger → Run
+Input      → directly addressed Profile ────────────────────┘
+```
+
+Enable the server in `config.yaml` (all values below except `enabled` and
+`credentials_file` show defaults):
+
+```yaml
+events:
+  enabled: true
+  listen: 127.0.0.1
+  port: 46184
+  max_body_bytes: 262144
+  max_pending: 1000
+  credentials_file: event-credentials.json
+```
+
+`credentials_file` resolves relative to the directory containing `config.yaml`;
+absolute paths also work. Copy
+[`examples/event-credentials.json.example`](examples/event-credentials.json.example)
+to that location and replace its token with a unique, random Bearer token of at
+least 32 characters (for example, generate one with `openssl rand -hex 32`).
+Each producer has a stable ID and an explicit list of allowed event sources:
+
+```json
+{
+  "version": 1,
+  "producers": [
+    {
+      "id": "deployment-system",
+      "token": "REPLACE_WITH_A_UNIQUE_RANDOM_TOKEN_AT_LEAST_32_CHARACTERS",
+      "sources": ["https://deploy.example.com/production"]
+    }
+  ]
+}
+```
+
+The credentials file must be a regular, non-symlink file owned by the Beacon
+user with mode `0600`. Its parent directory must belong to that user and grant
+no group/world access. Producer IDs and tokens must be unique, and source lists
+must be nonempty. Tokens use Bearer-compatible characters. Credentials are not
+passed to Pi, included in event records, or loaded from `runtime.env`.
+
+```sh
+chmod 700 "$HOME/.beacon"
+chmod 600 "$HOME/.beacon/event-credentials.json"
+```
+
+Subscribe in the desired `profile.yaml`:
+
+```yaml
+admin:
+  chat_id: REPLACE_WITH_ADMIN_DIRECT_CHAT_ID
+listener:
+  sources:
+    - https://deploy.example.com/production
+  types:
+    - com.example.deployment.completed.v1
+  notify:
+    chat_id: REPLACE_WITH_GROUP_CHAT_ID
+```
+
+Both lists are required and nonempty. Values match exactly: **OR within each
+list, AND between `sources` and `types`**. There are no wildcards, regular
+expressions, or filters inside `data`. A listener requires `admin.chat_id`;
+`listener.notify` is optional. Matching Profiles each receive one Trigger with
+the complete event as input. Their `persona.md` and `task.md` define what to do.
+`reply_text` and `reply_card` go to the configured admin; `no_reply` is allowed;
+`notify_card` is available only when the listener has a notify target. The event
+cannot choose a Profile, command, or delivery destination. All event fields
+remain untrusted external data, even after producer authentication.
+
+Restart Beacon after changing configuration or credentials. This example sends
+one CloudEvents 1.0 structured JSON event. Set the token in your **sender's**
+environment to the value in its producer credentials; do not put it in Beacon's
+`runtime.env`:
+
+```sh
+export BEACON_EVENT_TOKEN='YOUR_CONFIGURED_PRODUCER_TOKEN'
+curl --fail-with-body --include \
+  -X POST http://127.0.0.1:46184/v1/events \
+  -H "Authorization: Bearer ${BEACON_EVENT_TOKEN}" \
+  -H 'Content-Type: application/cloudevents+json' \
+  --data-binary '{
+    "specversion": "1.0",
+    "id": "deployment-20260929-001",
+    "source": "https://deploy.example.com/production",
+    "type": "com.example.deployment.completed.v1",
+    "subject": "services/payment",
+    "time": "2026-09-29T09:00:00Z",
+    "datacontenttype": "application/json",
+    "data": {"service": "payment", "version": "v2.3.0"}
+  }'
+```
+
+Use a new event `id` for each new fact. When retrying delivery of the same fact,
+keep the same event body and ID. Acceptance returns a `receipt_id`, `status`,
+`accepted_at`, `recipients`, and `duplicate`, with a `Location` header pointing
+to the receipt. Query it using the same producer's credentials:
+
+```sh
+export BEACON_EVENT_RECEIPT_ID='evt_REPLACE_WITH_RECEIPT_ID_FROM_RESPONSE'
+curl --fail-with-body \
+  -H "Authorization: Bearer ${BEACON_EVENT_TOKEN}" \
+  "http://127.0.0.1:46184/v1/events/${BEACON_EVENT_RECEIPT_ID}"
+```
+
+| HTTP result | Meaning |
+| --- | --- |
+| `202` | New event durably accepted, independently of Run execution |
+| `200` on POST | Identical event from the same producer already accepted; no new Trigger |
+| `400` / `415` | Invalid event or unsupported representation; fix the request |
+| `401` / `403` | Invalid credentials / producer not authorized for this `source` |
+| `409` | Same `source + id` already belongs to different event content or another producer |
+| `413` | Request exceeds `max_body_bytes` (256 KiB by default) |
+| `503` | Intake unavailable or pending inbox full; retry with backoff, honoring `Retry-After` |
+| `500` | Required intake work failed; acceptance was not confirmed; retry the same event after recovery |
+
+Receipt queries return `200` only to the originating producer while its source
+remains authorized; missing or inaccessible receipts return `404`. Receipt
+status is `unmatched` when no Profile matched, `pending` while recipients await
+dispatch, or `dispatched` when dispatch has settled for all recipients. Each
+recipient includes `profile_id` and, once dispatch settles, `trigger_id`.
+**`dispatched` does not mean the Runs succeeded.** Inspect their Trigger/Run
+records or Dashboard for execution and delivery outcomes.
+
+This first version accepts a single structured JSON CloudEvent per POST.
+`specversion`, `id`, `source`, and `type` are required. Sources may be valid
+relative URI references or absolute URIs. Data is optional and must be JSON;
+`datacontenttype`, when supplied, must be `application/json` or an
+`application/*+json` type, with an optional UTF-8 charset. Extension names use
+lowercase letters/digits and values are strings, booleans, or 32-bit integers.
+There are no provider adapters, batch envelopes, binary-mode CloudEvents,
+`data_base64`, or compressed requests.
+
+The durable inbox lives at `<Beacon home>/state/events/`. At acceptance Beacon
+snapshots matching Profiles and their admin/notify destinations. Restart resumes
+pending dispatch without rematching historical events, and each recipient
+Profile is claimed once. Changing a listener affects only new events. Keep
+Profiles referenced by pending receipts configured until dispatch settles;
+removing one causes a visible fatal dispatch failure. Dispatch is serial and
+waits for the shared Run queue, while HTTP acceptance remains independent.
+Active Runs interrupted by restart fail rather than execute twice; failed Runs
+are not retried automatically or retriggered by duplicate event delivery. Event
+records, like existing state records, have no automatic retention cleanup;
+manually deleting them removes deduplication history.
+
+For remote senders, put HTTPS authentication-preserving reverse proxying in front
+of the event port. Keep its default loopback binding when the proxy is on the
+same host. Expose only the event endpoint, not Beacon's unauthenticated Dashboard.
+
 ## Commands
 
 ```text
@@ -162,14 +322,14 @@ An Agent closes the conversational channel with `reply_text`, `reply_card`, or
 `no_reply`, and may also call `notify_card` when the Run has a notify target:
 
 - `reply_text` sends plain text. Inbound Feishu messages quote-reply the user.
-  Schedules message the Profile admin.
+  Schedules and event Runs message the Profile admin.
 - `reply_card` sends an interactive card on the same conversational channel
-  (inbound quote-reply, or Schedule admin chat). It closes that channel by
+  (inbound quote-reply, or Schedule/event admin chat). It closes that channel by
   itself.
 - `no_reply` finishes without messaging the conversational channel. Its
   `reason` is stored for audit and is never sent. Do not use it on inbound
   messages.
-- `notify_card` posts an interactive card to the Schedule's configured group.
+- `notify_card` posts an interactive card to the Schedule or listener's configured group.
   Only valid when the Run has a notify target.
 
 Which of `reply_text` / `reply_card` / `notify_card` / `no_reply` to use for a
@@ -202,7 +362,7 @@ these argument shapes:
 
 Beacon binds destinations; the Agent never supplies a `chat_id`. Text remains
 text. Cards are sent with Feishu's `interactive` message type and include the
-card generation time. A schedule `no_reply` without `notify_card` records a
+card generation time. A Schedule or event `no_reply` without `notify_card` records a
 successful Run with no Delivery. Failures `reply_text` a short error and never
 notify a group. Manual local triggers print reply text/card and any notify card
 as Markdown on stdout.
@@ -235,7 +395,7 @@ pi --export /ABSOLUTE/SESSION/PATH/TIMESTAMP_run_REPORTED_ID.jsonl run.html
 `beacon doctor` keeps using `--no-session`, so its Pi smoke tests do not create
 diagnostic session files.
 
-Duplicate Feishu events and duplicate Schedule occurrences do not start a second Run. Active Runs interrupted by restart fail rather than rerun. Pending Delivery can resume, while a Delivery interrupted after its external call began fails without resending. Run and Delivery success are recorded independently. Beacon does not automatically retry either one.
+Duplicate Feishu events, CloudEvents, and Schedule occurrences do not start a second Run. Active Runs interrupted by restart fail rather than rerun. Pending Delivery can resume, while a Delivery interrupted after its external call began fails without resending. Run and Delivery success are recorded independently. Beacon does not automatically retry either one.
 
 Secrets and ephemeral Run Capability tokens are excluded from persisted records and from the Pi environment except for the one Run-scoped Outcome capability.
 

package/dist/config/event-credentials.js

@@ -0,0 +1,67 @@
+import { constants } from "node:fs";
+import { lstat, open, realpath, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+import { z } from "zod";
+import { eventSourceSchema } from "../events/cloudevent.js";
+const credentialsSchema = z
+    .object({
+    version: z.literal(1),
+    producers: z
+        .array(z
+        .object({
+        id: z.string().regex(/^[a-z0-9][a-z0-9_-]{0,62}$/),
+        token: z
+            .string()
+            .min(32)
+            .regex(/^[A-Za-z0-9._~+/-]+=*$/),
+        sources: z.array(eventSourceSchema).min(1),
+    })
+        .strict())
+        .min(1),
+})
+    .strict();
+export async function loadEventCredentials(path) {
+    const canonicalParent = await realpath(dirname(path));
+    const parent = await stat(canonicalParent);
+    if ((parent.mode & 0o077) !== 0 ||
+        (typeof process.getuid === "function" && parent.uid !== process.getuid())) {
+        throw new Error("Event credentials parent must be owned by the current user and grant no group/world access");
+    }
+    if ((await lstat(path)).isSymbolicLink()) {
+        throw new Error("Event credentials must not be a symbolic link");
+    }
+    const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const metadata = await file.stat();
+        if (!metadata.isFile() ||
+            (metadata.mode & 0o777) !== 0o600 ||
+            (typeof process.getuid === "function" &&
+                metadata.uid !== process.getuid())) {
+            throw new Error("Event credentials must be a regular file owned by the current user with mode 0600");
+        }
+        // Deliberately omit parser causes: malformed JSON can quote credential bytes.
+        let parsed;
+        try {
+            parsed = JSON.parse(await file.readFile("utf8"));
+        }
+        catch {
+            throw new Error("Cannot read valid JSON event credentials");
+        }
+        const result = credentialsSchema.safeParse(parsed);
+        if (!result.success)
+            throw new Error("Invalid event credentials configuration");
+        const ids = new Set();
+        const tokens = new Set();
+        for (const producer of result.data.producers) {
+            if (ids.has(producer.id) || tokens.has(producer.token)) {
+                throw new Error("Event producer IDs and tokens must be unique");
+            }
+            ids.add(producer.id);
+            tokens.add(producer.token);
+        }
+        return result.data.producers;
+    }
+    finally {
+        await file.close();
+    }
+}

package/dist/config/global.js

@@ -26,6 +26,18 @@ const globalDocumentSchema = z
     scheduler: z
         .object({ max_occurrences_per_reconciliation: positiveInteger })
         .strict(),
+    events: z
+        .object({
+        enabled: z.boolean().default(false),
+        listen: z.string().min(1).default("127.0.0.1"),
+        port: z.number().int().min(1).max(65535).default(46184),
+        max_body_bytes: positiveInteger.default(262144),
+        max_pending: positiveInteger.default(1000),
+        credentials_file: z.string().min(1).optional(),
+    })
+        .strict()
+        .refine((value) => !value.enabled || value.credentials_file !== undefined, "events.credentials_file is required when events are enabled")
+        .optional(),
     dashboard: z
         .object({
         enabled: z.boolean().optional(),
@@ -105,6 +117,17 @@ export async function loadGlobalConfig(path) {
         scheduler: {
             maxOccurrencesPerReconciliation: document.scheduler.max_occurrences_per_reconciliation,
         },
+        ...(document.events?.enabled
+            ? {
+                events: {
+                    listen: document.events.listen,
+                    port: document.events.port,
+                    maxBodyBytes: document.events.max_body_bytes,
+                    maxPending: document.events.max_pending,
+                    credentialsPath: resolveFromHome(document.events.credentials_file),
+                },
+            }
+            : {}),
         dashboard: {
             enabled: document.dashboard?.enabled ?? defaultDashboard.enabled,
             listen: document.dashboard?.listen ?? defaultDashboard.listen,

package/dist/config/profile.js

@@ -2,6 +2,7 @@ import { readFile, realpath, stat } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { z } from "zod";
+import { eventSourceSchema } from "../events/cloudevent.js";
 import { nextOccurrence } from "../schedule/cron.js";
 import { parseStrictYaml } from "./yaml.js";
 const profileIdPattern = /^[a-z0-9](?:[a-z0-9_-]{0,62})$/;
@@ -51,6 +52,17 @@ const profileDocumentSchema = z
         .strict()
         .optional(),
     schedules: z.array(scheduleSchema).default([]),
+    listener: z
+        .object({
+        sources: z.array(eventSourceSchema).min(1),
+        types: z.array(z.string().min(1)).min(1),
+        notify: z
+            .object({ chat_id: z.string().trim().min(1) })
+            .strict()
+            .optional(),
+    })
+        .strict()
+        .optional(),
 })
     .strict();
 function assertProfileId(profileId) {
@@ -167,6 +179,9 @@ export async function loadProfile(profileId, profilesDirectory = join(homedir(),
     if (config.schedules.length > 0 && !config.admin) {
         throw new Error(`Profile ${profileId} with schedules must declare admin.chat_id`);
     }
+    if (config.listener && !config.admin) {
+        throw new Error(`Profile ${profileId} with listener must declare admin.chat_id`);
+    }
     const canonicalProfileDirectory = await realpath(profileDirectory);
     const workspace = isAbsolute(config.workspace)
         ? config.workspace
@@ -193,6 +208,17 @@ export async function loadProfile(profileId, profilesDirectory = join(homedir(),
         runtime: config.runtime,
         model: config.model,
         ...(config.admin ? { admin: { chatId: config.admin.chat_id } } : {}),
+        ...(config.listener
+            ? {
+                listener: {
+                    sources: config.listener.sources,
+                    types: config.listener.types,
+                    ...(config.listener.notify
+                        ? { notify: { chatId: config.listener.notify.chat_id } }
+                        : {}),
+                },
+            }
+            : {}),
         schedules: config.schedules.map((schedule) => ({
             id: schedule.id,
             cron: schedule.cron,

package/dist/dashboard/records.js

@@ -46,6 +46,12 @@ function summarize(value, hasSessionFile) {
         acceptedAt,
         kind: asString(input?.kind) ?? "unknown",
         scheduleId: asString(input?.scheduleId),
+        ...(input?.kind === "event"
+            ? {
+                eventSource: asString(asRecord(input.event)?.source),
+                eventType: asString(asRecord(input.event)?.type),
+            }
+            : {}),
         hasNotifyTarget: asRecord(record.notifyTarget) !== undefined,
         runId: asString(run?.runId),
         state: asString(run?.state),
@@ -81,7 +87,7 @@ export async function listRunSummaries(profilesDirectory) {
         if (!entries)
             continue;
         for (const entry of entries) {
-            if (!entry.isDirectory())
+            if (!entry.isDirectory() || /^\.claim-[0-9a-f-]{36}$/.test(entry.name))
                 continue;
             const summary = await loadSummary(join(root, entry.name, "record.json"));
             if (summary)
@@ -97,6 +103,9 @@ export function kindLabel(row) {
     if (row.kind === "schedule" && row.scheduleId) {
         return `schedule:${row.scheduleId}`;
     }
+    if (row.kind === "event" && row.eventType) {
+        return `event:${row.eventType}${row.eventSource ? ` (${row.eventSource})` : ""}`;
+    }
     return row.kind;
 }
 export function toRunListItem(row) {

package/dist/dashboard/server.js

@@ -28,6 +28,9 @@ function triggerFromRunSummary(summary) {
             notify: summary.hasNotifyTarget,
         };
     }
+    if (summary.kind === "event") {
+        return { kind: "event", notify: summary.hasNotifyTarget };
+    }
     if (summary.kind === "feishu_message") {
         return { kind: "feishu_message", notify: false };
     }

package/dist/doctor.js

@@ -1,3 +1,4 @@
+import { loadEventCredentials } from "./config/event-credentials.js";
 import { loadGlobalConfig } from "./config/global.js";
 import { loadProfileRegistry } from "./config/registry.js";
 import { loadRuntimeEnvironment } from "./config/runtime-environment.js";
@@ -8,6 +9,8 @@ export async function runDoctor(configPath) {
     const global = await loadGlobalConfig(configPath);
     const runtimeEnvironment = await loadRuntimeEnvironment(global.runtimeEnvironmentPath);
     const profiles = await loadProfileRegistry(global.profilesDirectory);
+    if (global.events)
+        await loadEventCredentials(global.events.credentialsPath);
     for (const profile of profiles) {
         const credentials = await loadFeishuCredentials(profile.id, global.secretsPath);
         await createFeishuGateway(credentials).checkReady();

package/dist/events/cloudevent.js

@@ -0,0 +1,93 @@
+import { z } from "zod";
+// RFC 3986 URI references, including relative paths. Do not normalize: source
+// identity and listener matching use the exact value provided by the producer.
+const uriReference = /^(?:([A-Za-z][A-Za-z0-9+.-]*):)?(?:\/\/([^/?#]*))?([^?#]*)(?:\?([^#]*))?(?:#(.*))?$/;
+const pathCharacters = /^(?:[A-Za-z0-9\-._~:@!$&'()*+,;=/]|%[0-9A-Fa-f]{2})*$/;
+const queryCharacters = /^(?:[A-Za-z0-9\-._~:@!$&'()*+,;=/?]|%[0-9A-Fa-f]{2})*$/;
+const authorityCharacters = /^(?:[A-Za-z0-9\-._~:@!$&'()*+,;=[\]]|%[0-9A-Fa-f]{2})*$/;
+export const eventSourceSchema = z
+    .string()
+    .min(1)
+    .refine((value) => {
+    const parts = uriReference.exec(value);
+    if (!parts)
+        return false;
+    const [, scheme, authority, path = "", query = "", fragment = ""] = parts;
+    if (!pathCharacters.test(path) ||
+        !queryCharacters.test(query) ||
+        !queryCharacters.test(fragment))
+        return false;
+    if (!scheme &&
+        authority === undefined &&
+        !path.startsWith("/") &&
+        (path.split("/")[0] ?? "").includes(":"))
+        return false;
+    if (authority !== undefined) {
+        if (!authorityCharacters.test(authority))
+            return false;
+        // Use HTTP's authority parser for host/IP/port syntax only. The original
+        // scheme, path and identity remain untouched, including relative sources.
+        try {
+            new URL(`http://${authority || "cloudevents.invalid"}/`);
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}, "Must be a valid nonempty URI reference");
+const knownAttributes = new Set([
+    "specversion",
+    "id",
+    "source",
+    "type",
+    "subject",
+    "time",
+    "dataschema",
+    "datacontenttype",
+    "data",
+]);
+export const cloudEventSchema = z
+    .object({
+    specversion: z.literal("1.0"),
+    id: z.string().min(1),
+    source: eventSourceSchema,
+    type: z.string().min(1),
+    subject: z.string().min(1).optional(),
+    time: z.iso.datetime({ offset: true }).optional(),
+    dataschema: eventSourceSchema
+        .refine((value) => /^[A-Za-z][A-Za-z0-9+.-]*:/.test(value), "dataschema must be an absolute URI")
+        .optional(),
+    datacontenttype: z
+        .string()
+        .refine((value) => /^application\/(?:json|[a-z0-9!#$&^_.+-]+\+json)(?:\s*;\s*charset\s*=\s*(?:utf-8|"utf-8"))?$/i.test(value), "Only JSON event data is supported")
+        .optional(),
+    data: z.json().optional(),
+})
+    .catchall(z.union([
+    z.string(),
+    z.boolean(),
+    z.number().int().min(-2147483648).max(2147483647),
+]))
+    .superRefine((event, context) => {
+    for (const key of Object.keys(event)) {
+        if (knownAttributes.has(key))
+            continue;
+        if (key === "data_base64" || !/^[a-z0-9]+$/.test(key)) {
+            context.addIssue({
+                code: "custom",
+                path: [key],
+                message: key === "data_base64"
+                    ? "data_base64 is unsupported; send JSON data"
+                    : "Extension names must contain only lowercase letters and digits",
+            });
+        }
+    }
+});
+export function parseCloudEvent(input) {
+    return cloudEventSchema.parse(input);
+}
+export function matchesListener(event, listener) {
+    return (listener.sources.includes(event.source) &&
+        listener.types.includes(event.type));
+}

package/dist/events/pipeline.js

@@ -0,0 +1,99 @@
+import { matchesListener } from "./cloudevent.js";
+import { EventIntakeError, } from "./store.js";
+export class EventPipeline {
+    options;
+    work;
+    requested = false;
+    stopped = false;
+    failure;
+    constructor(options) {
+        this.options = options;
+    }
+    async accept(event, producer) {
+        if (this.stopped || this.failure)
+            throw new EventIntakeError(503, "Event intake unavailable");
+        if (!producer.sources.includes(event.source))
+            throw new EventIntakeError(403, "Event source is not authorized");
+        const recipients = this.options.contexts
+            .filter(({ profile }) => profile.listener && matchesListener(event, profile.listener))
+            .map(({ profile }) => {
+            if (!profile.admin)
+                throw new Error(`Listener Profile ${profile.id} has no admin destination`);
+            return {
+                profileId: profile.id,
+                chatId: profile.admin.chatId,
+                ...(profile.listener?.notify
+                    ? { notifyChatId: profile.listener.notify.chatId }
+                    : {}),
+            };
+        });
+        const result = await this.options.store.accept(event, producer.id, recipients, this.options.maxPending);
+        this.wake();
+        return result;
+    }
+    /** Call after Profile orchestrator recovery and after the HTTP listener binds. */
+    wake() {
+        if (this.stopped || this.failure)
+            return;
+        this.requested = true;
+        if (this.work)
+            return;
+        this.work = this.pump()
+            .catch((error) => {
+            this.failure = new Error(`Event dispatch failed: ${error instanceof Error ? error.message : "unknown error"}`, { cause: error });
+            this.options.onFatal(this.failure);
+        })
+            .finally(() => {
+            this.work = undefined;
+            if (this.requested && !this.stopped && !this.failure)
+                this.wake();
+        });
+    }
+    async pump() {
+        while (this.requested && !this.stopped) {
+            this.requested = false;
+            for (const record of await this.options.store.pending()) {
+                for (const recipient of record.recipients) {
+                    if (this.stopped)
+                        return;
+                    if (recipient.triggerId)
+                        continue;
+                    const context = this.options.contexts.find(({ profile }) => profile.id === recipient.profileId);
+                    if (!context)
+                        throw new Error(`Pending Event ${record.receiptId} requires missing Profile ${recipient.profileId}`);
+                    const input = { kind: "event", event: record.event };
+                    const claimed = await context.store.claim({
+                        sourceKey: ["event", record.event.source, record.event.id],
+                        acceptedAt: new Date(record.acceptedAt),
+                        target: { kind: "chat", chatId: recipient.chatId },
+                        ...(recipient.notifyChatId
+                            ? {
+                                notifyTarget: {
+                                    kind: "chat",
+                                    chatId: recipient.notifyChatId,
+                                },
+                            }
+                            : {}),
+                        input,
+                    });
+                    // Existing claims were recovered by the orchestrator before intake starts.
+                    if (claimed.created)
+                        await context.orchestrator.process(claimed.record.triggerKey, async () => input);
+                    await this.options.store.markDispatched(record.receiptId, recipient.profileId, claimed.record.triggerId);
+                }
+            }
+        }
+    }
+    async close() {
+        this.stopped = true;
+        await this.work;
+        if (this.failure)
+            throw this.failure;
+    }
+    async drain() {
+        while (this.work)
+            await this.work;
+        if (this.failure)
+            throw this.failure;
+    }
+}