@oxygen-agent/cli 1.1011.98 → 1.1011.322

package/node_modules/@oxygen/shared/dist/mcp-event-contract.js

@@ -0,0 +1,713 @@
+import { createHash } from "node:crypto";
+import { arr, enumOf, int, nullable, num, obj, str, unwrapNullable, validateContract, } from "./contracts/schema.js";
+import { CRM_ACTIVITY_CREATED_EVENT } from "./crm-activity-events.js";
+import { CRM_EMAIL_REPLY_CLASSIFIED_EVENT, CRM_WORKFLOW_EVENT_SOURCE, } from "./crm-reply-events.js";
+import { NOTETAKER_MEETING_COMPLETED_EVENT, NOTETAKER_WORKFLOW_EVENT_SOURCE } from "./notetaker-events.js";
+import { slugifyOption } from "./select-options.js";
+import { SEQUENCE_ENROLLMENT_TERMINAL_EVENT, SEQUENCE_TERMINAL_EVENT_SOURCE, SEQUENCE_TERMINAL_STATUSES, } from "./sequence-terminal-events.js";
+import { resolveAppBaseUrl } from "./signed-token.js";
+import { isRecord, readCoercedString, readTrimmedString } from "./type-guards.js";
+// The v1 MCP Events contract (ADR 0030, ledger OXP-11.5.17): the six events
+// `events/list` advertises, what a subscription may filter on, what a delivery
+// carries, and the deterministic ids that make `events/subscribe` a refresh and
+// a redelivery recognisable. Server-only (node:crypto). The control-DB tables,
+// the `events/*` handlers and the delivery worker are OXP-11.5.18 to .20; the
+// run and approval producers are OXP-11.5.21. Signing and the SSRF-safe POST
+// are `@oxygen/shared/standard-webhooks` and `@oxygen/integrations/outbound-webhook`.
+//
+// A payload leaves OXYGEN for a third party and lands in a model's context, so
+// it holds ids, enums, counts, timestamps and one OXYGEN deep link, never
+// message text, subjects, names, email addresses, phone numbers or LinkedIn
+// URLs (ADR 0030 §7). Every projection builds its payload field by field and
+// checks it against the event's closed `payloadSchema` before returning it.
+/** OpenAI MCP Events: one event per request, and the whole request body at most 256 KiB. */
+export const MCP_EVENT_MAX_BODY_BYTES = 262_144;
+export const MCP_EVENT_NAMES = [
+    "reply.classified",
+    "enrollment.ended",
+    "meeting.completed",
+    "record.stage_changed",
+    "run.settled",
+    "approval.requested",
+];
+/**
+ * How OXYGEN classified a reply. The first six are the Inbox labels the
+ * classifier sets, and `bounced` is set when the bounce arrives. A label the
+ * workspace defined is `other`, because its key is workspace-authored text; a
+ * one-click email unsubscribe, which has no reply, is `unsubscribed`.
+ */
+export const MCP_REPLY_CLASSIFICATIONS = [
+    "interested",
+    "neutral",
+    "not_now",
+    "not_interested",
+    "out_of_office",
+    "wrong_person",
+    "bounced",
+    "unsubscribed",
+    "other",
+];
+const REPLY_LABELS_DELIVERED_AS_IS = new Set([
+    "interested",
+    "neutral",
+    "not_now",
+    "not_interested",
+    "out_of_office",
+    "wrong_person",
+    "bounced",
+]);
+export const MCP_REPLY_CHANNELS = ["email", "linkedin", "whatsapp"];
+/** How an enrollment ended: the Sequencer's own terminal statuses. */
+export const MCP_ENROLLMENT_OUTCOMES = SEQUENCE_TERMINAL_STATUSES;
+/** The run ledgers `run_outcome_analytics` reads (`SettledRunKind` in @oxygen/tenant-db). */
+export const MCP_RUN_KINDS = ["workflow", "table_action", "table_ingestion", "agent", "copilot_turn"];
+/**
+ * Every terminal status those ledgers write, with one spelling of cancel:
+ * Workflow and Table runs write `canceled`, Agent runs and Copilot turns `cancelled`.
+ */
+export const MCP_RUN_STATUSES = [
+    "completed",
+    "completed_with_errors",
+    "failed",
+    "canceled",
+    "budget_exhausted",
+    "effect_unknown",
+];
+export const MCP_APPROVAL_KINDS = ["workflow", "agent"];
+// An OXYGEN id on the wire: a uuid, a slug or a field key. Never whitespace, so
+// free text cannot pass as an id.
+const ID_PATTERN = "^[A-Za-z0-9][A-Za-z0-9_.:-]*$";
+const ID_MAX_LENGTH = 128;
+// Bounded so the largest valid meeting payload stays far below the body cap.
+const MEETING_RECORD_IDS_MAX = 1_000;
+function id(description) {
+    return { ...str({ description, minLength: 1, maxLength: ID_MAX_LENGTH }), pattern: ID_PATTERN };
+}
+function timestamp(description) {
+    return { ...str({ description }), format: "date-time" };
+}
+function deepLink(description) {
+    return { ...str({ description }), format: "uri" };
+}
+/** A closed payload whose every field is always present, null where a fact can be missing. */
+function payloadObject(properties) {
+    return obj(properties, { required: Object.keys(properties) });
+}
+const REPLY_CLASSIFIED_INPUT = obj({
+    sequence_id: id("Only replies from leads enrolled in this Sequence."),
+    classification: enumOf(MCP_REPLY_CLASSIFICATIONS, { description: "Only replies with this classification." }),
+});
+const REPLY_CLASSIFIED_PAYLOAD = payloadObject({
+    classification: enumOf(MCP_REPLY_CLASSIFICATIONS, {
+        description: "How OXYGEN classified the reply. `bounced` is a bounce, `unsubscribed` a one-click email unsubscribe, `other` a label your workspace defined.",
+    }),
+    channel: enumOf(MCP_REPLY_CHANNELS, { description: "Where the reply arrived." }),
+    conversation_id: nullable(id("The Inbox conversation; null for a one-click unsubscribe, which has none.")),
+    record_id: nullable(id("The lead's CRM person record; null when OXYGEN has not matched one.")),
+    sequence_id: nullable(id("The Sequence the lead was enrolled in; null outside Sequences.")),
+    enrollment_id: nullable(id("The lead's enrollment in that Sequence; null outside Sequences.")),
+    occurred_at: timestamp("When the reply arrived, in ISO 8601."),
+    url: deepLink("The conversation in OXYGEN, or the lead's record or Sequence when there is no conversation."),
+});
+const ENROLLMENT_ENDED_INPUT = obj({
+    sequence_id: id("Only enrollments in this Sequence."),
+    outcome: enumOf(MCP_ENROLLMENT_OUTCOMES, { description: "Only enrollments that ended this way." }),
+});
+const ENROLLMENT_ENDED_PAYLOAD = payloadObject({
+    outcome: enumOf(MCP_ENROLLMENT_OUTCOMES, {
+        description: "How the enrollment ended: `replied`; `completed`, every step sent without a reply; `stopped` or `excluded`, withdrawn by a reply-stop, an unsubscribe, a suppression rule or an operator; `failed`, sending failed.",
+    }),
+    steps_sent: nullable(int({ minimum: 0, description: "Sequence steps OXYGEN sent to the lead; null when they could not be counted." })),
+    sequence_id: id("The Sequence."),
+    enrollment_id: id("The lead's enrollment."),
+    occurred_at: timestamp("When the enrollment ended, in ISO 8601."),
+    url: deepLink("The Sequence in OXYGEN."),
+});
+const MEETING_COMPLETED_INPUT = obj({
+    record_id: id("Only meetings linked to this CRM record: a person, company or deal."),
+});
+const MEETING_COMPLETED_PAYLOAD = payloadObject({
+    session_id: id("The Meeting Notetaker session."),
+    duration_seconds: nullable(int({ minimum: 0, description: "Recorded length in whole seconds; null when its start or end was not captured." })),
+    record_ids: {
+        ...arr(id("A CRM record id."), {
+            maxItems: MEETING_RECORD_IDS_MAX,
+            description: "CRM records the meeting is linked to: people, companies and deals.",
+        }),
+        uniqueItems: true,
+    },
+    activity_id: nullable(id("The meeting on the CRM timeline; null when none was logged.")),
+    occurred_at: timestamp("When OXYGEN finished processing the meeting, in ISO 8601."),
+    url: deepLink("The meeting in OXYGEN."),
+});
+const RECORD_STAGE_CHANGED_INPUT = obj({
+    object: id("Only records of this CRM object, such as `people`, `companies` or `deals`."),
+    pipeline_id: id("Only changes to this stage field: `lead_stage` on people, `lifecycle_stage` or `deal_stage` on companies, `pipeline_stage` on deals, or a custom status field's key."),
+});
+const RECORD_STAGE_CHANGED_PAYLOAD = payloadObject({
+    object: id("The record's CRM object."),
+    record_id: id("The record."),
+    pipeline_id: id("The stage field that changed."),
+    from_stage_id: nullable(id("The stage option the record left; null when it had none.")),
+    to_stage_id: nullable(id("The stage option the record moved to; null when the stage was cleared.")),
+    activity_id: id("The stage change on the record's CRM timeline."),
+    occurred_at: timestamp("When the stage changed, in ISO 8601."),
+    url: deepLink("The record in OXYGEN."),
+});
+const RUN_SETTLED_INPUT = obj({
+    kind: enumOf(MCP_RUN_KINDS, { description: "Only runs of this kind." }),
+    status: enumOf(MCP_RUN_STATUSES, { description: "Only runs that ended with this status." }),
+});
+const RUN_SETTLED_PAYLOAD = payloadObject({
+    kind: enumOf(MCP_RUN_KINDS, {
+        description: "What ran: a Workflow run, a Table action run, a Table import (`table_ingestion`), an Agent run or a Workspace Copilot turn.",
+    }),
+    status: enumOf(MCP_RUN_STATUSES, {
+        description: "How it ended. An Agent run can also end `budget_exhausted` or `effect_unknown`.",
+    }),
+    run_id: id("The run."),
+    credits_used: nullable(num({ minimum: 0, description: "Credits the run spent; null when its ledger records no figure." })),
+    occurred_at: timestamp("When the run settled, in ISO 8601."),
+    url: deepLink("The run in OXYGEN."),
+});
+const APPROVAL_REQUESTED_INPUT = obj({
+    kind: enumOf(MCP_APPROVAL_KINDS, { description: "Only approvals requested by this kind of run." }),
+});
+const APPROVAL_REQUESTED_PAYLOAD = payloadObject({
+    kind: enumOf(MCP_APPROVAL_KINDS, { description: "What is waiting: a Workflow run or an Agent run." }),
+    approval_id: id("The pending approval."),
+    run_id: id("The waiting run."),
+    occurred_at: timestamp("When the approval was requested, in ISO 8601."),
+    url: deepLink("The waiting run in OXYGEN, where it is approved or rejected."),
+});
+function eventDefinition(name, description, inputSchema, payloadSchema) {
+    return { name, description, delivery: ["webhook"], inputSchema, payloadSchema };
+}
+/** What `events/list` answers, in this order. Plain JSON: nothing internal rides along. Read-only. */
+export const MCP_EVENT_DEFINITIONS = [
+    eventDefinition("reply.classified", "A lead replied to your outreach by email, LinkedIn or WhatsApp and OXYGEN classified the reply in its Inbox. A one-click email unsubscribe, which has no reply, arrives as `unsubscribed`. Ids only: message text and contact details stay in OXYGEN.", REPLY_CLASSIFIED_INPUT, REPLY_CLASSIFIED_PAYLOAD),
+    eventDefinition("enrollment.ended", "A lead's enrollment in an OXYGEN Sequence ended: the lead replied, every step was sent, the enrollment was stopped or excluded, or sending failed.", ENROLLMENT_ENDED_INPUT, ENROLLMENT_ENDED_PAYLOAD),
+    eventDefinition("meeting.completed", "OXYGEN's Meeting Notetaker finished processing a recorded meeting; its transcript and meeting note are ready in OXYGEN.", MEETING_COMPLETED_INPUT, MEETING_COMPLETED_PAYLOAD),
+    eventDefinition("record.stage_changed", "A CRM record's stage changed in OXYGEN, such as a person's lead stage, a company's account stage or a deal's pipeline stage.", RECORD_STAGE_CHANGED_INPUT, RECORD_STAGE_CHANGED_PAYLOAD),
+    eventDefinition("run.settled", "A run in OXYGEN reached its final status: a Workflow run, a Table action run or import, an Agent run, or a Workspace Copilot turn.", RUN_SETTLED_INPUT, RUN_SETTLED_PAYLOAD),
+    eventDefinition("approval.requested", "A Workflow run or an Agent run in OXYGEN paused and is waiting for a person to approve its next step.", APPROVAL_REQUESTED_INPUT, APPROVAL_REQUESTED_PAYLOAD),
+];
+const DEFINITIONS_BY_NAME = new Map(MCP_EVENT_DEFINITIONS.map((entry) => [entry.name, entry]));
+const equals = (field) => ({ field, match: "equals" });
+/** How each subscription argument narrows delivery. Applied by OXYGEN before anything is sent. */
+export const MCP_EVENT_FILTERS = {
+    "reply.classified": { sequence_id: equals("sequence_id"), classification: equals("classification") },
+    "enrollment.ended": { sequence_id: equals("sequence_id"), outcome: equals("outcome") },
+    "meeting.completed": { record_id: { field: "record_ids", match: "includes" } },
+    "record.stage_changed": { object: equals("object"), pipeline_id: equals("pipeline_id") },
+    "run.settled": { kind: equals("kind"), status: equals("status") },
+    "approval.requested": { kind: equals("kind") },
+};
+// The JSON-RPC error an `events/*` handler answers with: -32011 is the draft
+// extension's unknown event or subscription, -32602 invalid params. null marks a
+// fault in OXYGEN's own reader or producer, never the caller's.
+const JSON_RPC_CODES = {
+    unknown_event: -32011,
+    invalid_arguments: -32602,
+    invalid_callback_url: -32602,
+    invalid_principal: null,
+    invalid_source_event: null,
+    invalid_payload: null,
+    payload_too_large: null,
+};
+export class McpEventContractError extends Error {
+    code;
+    /** -32011 or -32602 when the caller's request is at fault; null when OXYGEN's own data is. */
+    jsonRpcCode;
+    issues;
+    constructor(code, message, issues = []) {
+        super(message);
+        this.name = "McpEventContractError";
+        this.code = code;
+        this.jsonRpcCode = JSON_RPC_CODES[code];
+        this.issues = issues;
+    }
+}
+export function isMcpEventName(value) {
+    return typeof value === "string" && DEFINITIONS_BY_NAME.has(value);
+}
+/** The event's definition, or `unknown_event` (-32011). */
+export function requireMcpEventDefinition(name) {
+    const found = typeof name === "string" ? DEFINITIONS_BY_NAME.get(name) : undefined;
+    if (!found) {
+        const named = typeof name === "string" ? `an event named ${JSON.stringify(name.slice(0, 100))}` : "that event";
+        throw new McpEventContractError("unknown_event", `OXYGEN has no ${named}.`, [
+            { path: "name", message: `name must be one of: ${MCP_EVENT_NAMES.join(", ")}.` },
+        ]);
+    }
+    return found;
+}
+/**
+ * Check `events/subscribe` and `events/unsubscribe` arguments against the
+ * event's closed `inputSchema`. Absent arguments and a `null` value both mean
+ * "no filter", as a model sends null for "any". An unknown key, a wrong type or
+ * a value outside an enum is `invalid_arguments` (-32602).
+ */
+export function validateMcpEventArguments(name, args) {
+    const definition = requireMcpEventDefinition(name);
+    if (args !== undefined && args !== null && !isRecord(args)) {
+        throw new McpEventContractError("invalid_arguments", `${definition.name} arguments must be an object.`, [
+            { path: "arguments", message: "arguments must be an object." },
+        ]);
+    }
+    const given = withoutAbsentValues(args ?? {});
+    const issues = schemaIssues(definition.inputSchema, given);
+    if (issues.length > 0) {
+        throw new McpEventContractError("invalid_arguments", `Invalid ${definition.name} arguments: ${issues.map((issue) => issue.message).join(" ")}`, issues);
+    }
+    return Object.fromEntries(Object.keys(given).sort().map((key) => [key, given[key]]));
+}
+/**
+ * The payload typed as the event's `data`, or `invalid_payload` when it breaks
+ * the closed `payloadSchema`: an unknown field, a missing one, a wrong type, a
+ * value outside an enum, or text where an id, timestamp or link belongs. The
+ * 256 KiB body cap is enforced where the body is serialized.
+ */
+export function assertMcpEventPayload(name, payload) {
+    const definition = requireMcpEventDefinition(name);
+    const issues = isRecord(payload)
+        ? schemaIssues(definition.payloadSchema, payload)
+        : [{ path: "", message: "The payload must be an object." }];
+    if (issues.length > 0) {
+        throw new McpEventContractError("invalid_payload", `${definition.name} payload breaks its schema: ${issues.map((issue) => issue.message).join(" ")}`, issues);
+    }
+    return payload;
+}
+/**
+ * Whether a subscription wants this delivery: every filter it set must match,
+ * and no filters match every event. Fails closed, as the Workflow trigger gate
+ * does (`matchesWorkflowEventFilters`): an unknown event, an argument this event
+ * does not filter on, or a non-string value never widens a subscription.
+ */
+export function mcpEventMatchesSubscription(input) {
+    const { name, arguments: args, payload } = input;
+    if (!isMcpEventName(name) || !isRecord(payload))
+        return false;
+    if (args !== undefined && args !== null && !isRecord(args))
+        return false;
+    const filters = MCP_EVENT_FILTERS[name];
+    for (const [argument, expected] of Object.entries(args ?? {})) {
+        if (expected === undefined || expected === null)
+            continue;
+        const binding = Object.hasOwn(filters, argument) ? filters[argument] : undefined;
+        if (!binding || typeof expected !== "string")
+            return false;
+        const actual = payload[binding.field];
+        const matched = binding.match === "includes"
+            ? Array.isArray(actual) && actual.includes(expected)
+            : actual === expected;
+        if (!matched)
+            return false;
+    }
+    return true;
+}
+const SUBSCRIPTION_ID_SCHEME = "oxygen.mcp_event_subscription.v1";
+const DELIVERY_ID_SCHEME = "oxygen.mcp_event_delivery.v1";
+/**
+ * The deterministic subscription id: sha256 over the principal, the callback
+ * URL, the event name and the canonical arguments, so a repeated
+ * `events/subscribe` refreshes the subscription instead of duplicating it and
+ * `events/unsubscribe` finds it from the same inputs. Pass validated arguments.
+ */
+export function mcpEventSubscriptionId(input) {
+    const definition = requireMcpEventDefinition(input.name);
+    const { organizationId, userId, oauthClientId } = input.principal;
+    if (![organizationId, userId, oauthClientId].every((part) => typeof part === "string" && part.trim() !== "")) {
+        throw new McpEventContractError("invalid_principal", "A subscription belongs to one organization, user and OAuth client; all three are required.");
+    }
+    return `sub_${sha256Hex(canonicalMcpEventJson({
+        scheme: SUBSCRIPTION_ID_SCHEME,
+        principal: { organization_id: organizationId, user_id: userId, oauth_client_id: oauthClientId },
+        callback_url: normalizedCallbackUrl(input.callbackUrl),
+        name: definition.name,
+        arguments: withoutAbsentValues(input.arguments ?? {}),
+    }))}`;
+}
+/**
+ * The `eventId` (and `webhook-id`) of one event for one subscription, derived
+ * from the subscription id and the source event's durable key, e.g. its
+ * `workflow_events` row id. A redelivered job, a reader rescan or a crash
+ * between the POST and the journal therefore reuse the id the receiver
+ * deduplicates on (ADR 0030 §4).
+ */
+export function mcpEventDeliveryId(input) {
+    if (!input.subscriptionId.trim() || !input.sourceEventKey.trim()) {
+        throw new McpEventContractError("invalid_source_event", "An event id needs the subscription id and the source event's durable key.");
+    }
+    return `evt_${sha256Hex(canonicalMcpEventJson({
+        scheme: DELIVERY_ID_SCHEME,
+        subscription_id: input.subscriptionId,
+        source_event_key: input.sourceEventKey,
+    }))}`;
+}
+/**
+ * The request body of one event delivery: `{eventId, name, timestamp, data,
+ * cursor: null}`, with `timestamp` the event's occurrence time (v1 has no
+ * replay, so `cursor` is always null). `data` must pass its schema, and a body
+ * over the cap is `payload_too_large` rather than a 413 from the receiver.
+ */
+export function serializeMcpEventDelivery(input) {
+    const data = assertMcpEventPayload(input.name, input.data);
+    const eventId = mcpEventDeliveryId(input);
+    const body = JSON.stringify({ eventId, name: input.name, timestamp: data.occurred_at, data, cursor: null });
+    const bytes = Buffer.byteLength(body, "utf8");
+    const limit = input.maxBodyBytes ?? MCP_EVENT_MAX_BODY_BYTES;
+    if (bytes > limit) {
+        throw new McpEventContractError("payload_too_large", `The ${input.name} event body is ${bytes} bytes; one delivery may carry at most ${limit}.`);
+    }
+    return { eventId, body, bytes };
+}
+/**
+ * JSON with every object's keys sorted, so equal values serialize identically
+ * however their keys were ordered: the canonical form of stored subscription
+ * arguments and of every id hashed here. `undefined` members are dropped as
+ * JSON.stringify drops them; anything JSON cannot carry is refused.
+ */
+export function canonicalMcpEventJson(value) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return JSON.stringify(value);
+    if (typeof value === "number" && Number.isFinite(value))
+        return JSON.stringify(value);
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => canonicalMcpEventJson(item === undefined ? null : item)).join(",")}]`;
+    }
+    if (isRecord(value) && [Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+        const members = Object.keys(value)
+            .filter((key) => value[key] !== undefined)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalMcpEventJson(value[key])}`);
+        return `{${members.join(",")}}`;
+    }
+    throw new McpEventContractError("invalid_arguments", "Arguments must be plain JSON: strings, finite numbers, booleans, null, lists and objects.");
+}
+const STAGE_CHANGED_ACTIVITY = "stage_changed";
+// `/api/cli/workflows/events/emit`, behind both the CLI and `oxygen_workflows_events_emit`.
+const MANUAL_EMIT_SURFACE = "cli";
+/**
+ * The v1 event a workspace event row is delivered as, or null. A manual emit
+ * is never delivered (ADR 0030 §8): it may name any source and event, so a
+ * subscriber would receive whatever a workspace member typed as if OXYGEN had
+ * observed it.
+ */
+export function mcpEventNameForWorkspaceEvent(row) {
+    if (isRecord(row.metadata) && row.metadata.surface === MANUAL_EMIT_SURFACE)
+        return null;
+    if (row.source === CRM_WORKFLOW_EVENT_SOURCE && row.event === CRM_EMAIL_REPLY_CLASSIFIED_EVENT) {
+        return "reply.classified";
+    }
+    if (row.source === SEQUENCE_TERMINAL_EVENT_SOURCE && row.event === SEQUENCE_ENROLLMENT_TERMINAL_EVENT) {
+        return "enrollment.ended";
+    }
+    if (row.source === NOTETAKER_WORKFLOW_EVENT_SOURCE && row.event === NOTETAKER_MEETING_COMPLETED_EVENT) {
+        return "meeting.completed";
+    }
+    if (row.source === CRM_WORKFLOW_EVENT_SOURCE
+        && row.event === CRM_ACTIVITY_CREATED_EVENT
+        && isRecord(row.payload)
+        && row.payload.activity_type === STAGE_CHANGED_ACTIVITY) {
+        return "record.stage_changed";
+    }
+    return null;
+}
+/**
+ * `crm / email_reply_classified` as `reply.classified`. The ledger names the
+ * lead only by contact details, so the reader passes the CRM person it matched.
+ */
+export function projectReplyClassifiedEvent(row, context = {}) {
+    const payload = catalogPayload("reply.classified", row);
+    const channel = readOneOf(payload.channel, MCP_REPLY_CHANNELS);
+    if (!channel)
+        throw sourceError("reply.classified", "names no reply channel");
+    const conversationId = readTrimmedString(payload.conversation_id);
+    const sequenceId = readTrimmedString(payload.sequence_id);
+    const record = context.record ?? null;
+    const path = conversationId
+        ? `/unibox?conversation=${encodeURIComponent(conversationId)}`
+        : record
+            ? crmRecordPath(record.object, record.id)
+            : sequenceId
+                ? sequencePath(sequenceId)
+                : "/unibox";
+    return assertMcpEventPayload("reply.classified", {
+        classification: replyClassification(payload),
+        channel,
+        conversation_id: conversationId,
+        record_id: record?.id ?? null,
+        sequence_id: sequenceId,
+        enrollment_id: readTrimmedString(payload.enrollment_id),
+        occurred_at: occurredAt("reply.classified", payload.occurred_at, row.receivedAt),
+        url: oxygenUrl(path, context),
+    });
+}
+/**
+ * `sequencer / enrollment_terminal` as `enrollment.ended`. The outbox row does
+ * not count sends, so the reader passes the enrollment's sent steps.
+ */
+export function projectEnrollmentEndedEvent(row, context) {
+    const payload = catalogPayload("enrollment.ended", row);
+    const outcome = readOneOf(payload.status, MCP_ENROLLMENT_OUTCOMES);
+    const sequenceId = readTrimmedString(payload.sequence_id);
+    const enrollmentId = readTrimmedString(payload.enrollment_id);
+    if (!outcome || !sequenceId || !enrollmentId) {
+        throw sourceError("enrollment.ended", "lacks a terminal status, Sequence or enrollment");
+    }
+    return assertMcpEventPayload("enrollment.ended", {
+        outcome,
+        steps_sent: context.stepsSent,
+        sequence_id: sequenceId,
+        enrollment_id: enrollmentId,
+        occurred_at: occurredAt("enrollment.ended", payload.occurred_at, row.receivedAt),
+        url: oxygenUrl(sequencePath(sequenceId), context),
+    });
+}
+/** `oxygen.notetaker / meeting.completed` as `meeting.completed`. */
+export function projectMeetingCompletedEvent(row, context = {}) {
+    const payload = catalogPayload("meeting.completed", row);
+    const session = isRecord(payload.session) ? payload.session : {};
+    const sessionId = readTrimmedString(session.id);
+    if (!sessionId)
+        throw sourceError("meeting.completed", "names no Notetaker session");
+    const crm = isRecord(payload.crm) ? payload.crm : {};
+    const links = Array.isArray(crm.links) ? crm.links : [];
+    const recordIds = links.flatMap((link) => {
+        const recordId = isRecord(link) ? readTrimmedString(link.row_id) : null;
+        return recordId ? [recordId] : [];
+    });
+    return assertMcpEventPayload("meeting.completed", {
+        session_id: sessionId,
+        duration_seconds: durationSeconds(session.started_at, session.ended_at),
+        record_ids: [...new Set(recordIds)],
+        activity_id: readTrimmedString(crm.activity_id),
+        occurred_at: occurredAt("meeting.completed", session.completed_at, session.ended_at, row.receivedAt),
+        url: oxygenUrl(`/crm/calls/${encodeURIComponent(sessionId)}`, context),
+    });
+}
+/**
+ * `crm / activity_created` of kind `stage_changed` as `record.stage_changed`.
+ * The activity stores the stage values; when the reader has not resolved their
+ * option ids (`stageIds`), each id is derived from its value as the option
+ * model derives an id the option did not declare (`slugifyOption`). The stock
+ * stages' ids equal their values, and a stage's name, workspace text, never
+ * leaves OXYGEN.
+ */
+export function projectRecordStageChangedEvent(row, context = {}) {
+    const payload = catalogPayload("record.stage_changed", row);
+    const activityId = readTrimmedString(payload.activity_id);
+    const metadata = isRecord(payload.metadata) ? payload.metadata : {};
+    const pipelineId = readTrimmedString(metadata.attribute);
+    const record = changedRecord(payload.links);
+    if (!activityId || !pipelineId || !record) {
+        throw sourceError("record.stage_changed", "lacks its activity id, stage field or linked record");
+    }
+    return assertMcpEventPayload("record.stage_changed", {
+        object: record.object,
+        record_id: record.id,
+        pipeline_id: pipelineId,
+        from_stage_id: context.stageIds ? context.stageIds.from : stageOptionId(metadata.from),
+        to_stage_id: context.stageIds ? context.stageIds.to : stageOptionId(metadata.to),
+        activity_id: activityId,
+        occurred_at: occurredAt("record.stage_changed", payload.occurred_at, row.receivedAt),
+        url: oxygenUrl(crmRecordPath(record.object, record.id), context),
+    });
+}
+/** A settled run as `run.settled`. Its producer is OXP-11.5.21. */
+export function projectRunSettledEvent(source, context = {}) {
+    const status = source.status === "cancelled" ? "canceled" : source.status;
+    if (!readOneOf(source.kind, MCP_RUN_KINDS) || !readOneOf(status, MCP_RUN_STATUSES)) {
+        throw sourceError("run.settled", `is a ${String(source.kind)} run with status ${String(source.status)}, not a settled run`);
+    }
+    return assertMcpEventPayload("run.settled", {
+        kind: source.kind,
+        status,
+        run_id: source.runId,
+        credits_used: source.creditsUsed,
+        occurred_at: occurredAt("run.settled", source.settledAt),
+        url: oxygenUrl(runPath(source), context),
+    });
+}
+/** A pending approval as `approval.requested`. Its producer is OXP-11.5.21. */
+export function projectApprovalRequestedEvent(source, context = {}) {
+    if (!readOneOf(source.kind, MCP_APPROVAL_KINDS)) {
+        throw sourceError("approval.requested", `comes from a ${String(source.kind)}, not a Workflow or Agent run`);
+    }
+    const path = source.kind === "workflow"
+        ? workflowRunPath(source.workflowId, source.runId)
+        : agentRunPath(source.agentSlug, source.runId);
+    return assertMcpEventPayload("approval.requested", {
+        kind: source.kind,
+        approval_id: source.approvalId,
+        run_id: source.runId,
+        occurred_at: occurredAt("approval.requested", source.requestedAt),
+        url: oxygenUrl(path, context),
+    });
+}
+// Deep links: the org-scoped top-level routes the CLI and MCP link to, mirrored
+// from apps/web/src/lib/oxygen-urls.ts, which a layer-0 package cannot import.
+// The host is always the deployment's public app URL (`resolveAppBaseUrl`).
+function oxygenUrl(path, options) {
+    return `${(options.appBaseUrl ?? resolveAppBaseUrl()).replace(/\/+$/, "")}${path}`;
+}
+function crmRecordPath(object, recordId) {
+    return `/crm/${encodeURIComponent(object)}/${encodeURIComponent(recordId)}`;
+}
+function sequencePath(sequenceId) {
+    return `/sequencer/sequences/${encodeURIComponent(sequenceId)}`;
+}
+function workflowRunPath(workflowId, runId) {
+    return `/workflows/${encodeURIComponent(workflowId)}/runs/${encodeURIComponent(runId)}`;
+}
+function agentRunPath(agentSlug, runId) {
+    return `/agents/${encodeURIComponent(agentSlug)}/runs/${encodeURIComponent(runId)}`;
+}
+function runPath(source) {
+    switch (source.kind) {
+        case "workflow":
+            return workflowRunPath(source.workflowId, source.runId);
+        case "table_action":
+            return `/tables/${encodeURIComponent(source.tableId)}/runs/${encodeURIComponent(source.runId)}`;
+        case "table_ingestion":
+            return `/tables/${encodeURIComponent(source.tableId)}/ingestions/${encodeURIComponent(source.runId)}`;
+        case "agent":
+            return agentRunPath(source.agentSlug, source.runId);
+        case "copilot_turn":
+            return `/copilot/${encodeURIComponent(source.copilotSessionId)}`;
+    }
+}
+// Every catalogue projection first proves the row is that event, so a reader
+// that skipped the router still cannot project a manual emit.
+function catalogPayload(name, row) {
+    if (mcpEventNameForWorkspaceEvent(row) !== name) {
+        const manual = isRecord(row.metadata) && row.metadata.surface === MANUAL_EMIT_SURFACE;
+        throw sourceError(name, manual ? "was emitted by hand" : `is not a ${name} source event`);
+    }
+    if (!isRecord(row.payload))
+        throw sourceError(name, "carries no payload object");
+    return row.payload;
+}
+function sourceError(name, problem) {
+    return new McpEventContractError("invalid_source_event", `Cannot deliver ${name}: the source event ${problem}.`);
+}
+function replyClassification(payload) {
+    const label = readTrimmedString(payload.status);
+    if (label)
+        return REPLY_LABELS_DELIVERED_AS_IS.has(label) ? label : "other";
+    // The one-click unsubscribe route records an opt-out with no reply to classify.
+    if (payload.opt_out === true)
+        return "unsubscribed";
+    throw sourceError("reply.classified", "carries neither a classification nor an opt-out");
+}
+// The stage writer links the changed record as the activity's actor.
+function changedRecord(value) {
+    const links = Array.isArray(value) ? value.filter(isRecord) : [];
+    const link = links.find((entry) => entry.role === "actor") ?? links[0];
+    const object = link ? readTrimmedString(link.object_slug) : null;
+    const recordId = link ? readTrimmedString(link.row_id) : null;
+    return object && recordId ? { object, id: recordId } : null;
+}
+function stageOptionId(value) {
+    const stored = readCoercedString(value);
+    return stored ? slugifyOption(stored) : null;
+}
+function readOneOf(value, values) {
+    return typeof value === "string" && values.includes(value) ? value : null;
+}
+function toIsoTimestamp(value) {
+    if (!(value instanceof Date) && !(typeof value === "string" && value.trim()))
+        return null;
+    const date = new Date(value);
+    return Number.isNaN(date.getTime()) ? null : date.toISOString();
+}
+function occurredAt(name, ...candidates) {
+    for (const candidate of candidates) {
+        const iso = toIsoTimestamp(candidate);
+        if (iso)
+            return iso;
+    }
+    throw sourceError(name, "has no occurrence time");
+}
+function durationSeconds(startedAt, endedAt) {
+    const start = toIsoTimestamp(startedAt);
+    const end = toIsoTimestamp(endedAt);
+    if (!start || !end)
+        return null;
+    const seconds = Math.round((Date.parse(end) - Date.parse(start)) / 1000);
+    return seconds >= 0 ? seconds : null;
+}
+function withoutAbsentValues(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined && entry !== null));
+}
+function sha256Hex(content) {
+    return createHash("sha256").update(content, "utf8").digest("hex");
+}
+// The contract DSL checks structure: closed keys, required fields, types, enums,
+// lengths and bounds. These schemas also carry `pattern`, `format` and
+// `uniqueItems`, which it does not read, so they are checked here.
+function schemaIssues(schema, value) {
+    const result = validateContract(schema, value, { unknown: "reject", overMax: "reject" });
+    if (!result.ok)
+        return result.issues;
+    const issues = [];
+    for (const [key, property] of Object.entries(schema.properties)) {
+        const entry = value[key];
+        if (entry !== undefined && entry !== null)
+            annotationIssues(unwrapNullable(property).property, entry, key, issues);
+    }
+    return issues;
+}
+const ISO_DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?(?:Z|[+-]\d{2}:\d{2})$/;
+const PATTERNS = new Map();
+function compiledPattern(source) {
+    let pattern = PATTERNS.get(source);
+    if (!pattern) {
+        pattern = new RegExp(source);
+        PATTERNS.set(source, pattern);
+    }
+    return pattern;
+}
+function annotationIssues(property, value, path, issues) {
+    if (!("type" in property))
+        return;
+    const annotated = property;
+    if (property.type === "array" && Array.isArray(value)) {
+        if (annotated.uniqueItems && new Set(value.map((item) => JSON.stringify(item))).size !== value.length) {
+            issues.push({ path, message: `${path} must not repeat an entry.` });
+        }
+        value.forEach((item, index) => annotationIssues(property.items, item, `${path}[${index}]`, issues));
+        return;
+    }
+    if (property.type !== "string" || typeof value !== "string")
+        return;
+    if (annotated.pattern && !compiledPattern(annotated.pattern).test(value)) {
+        issues.push({ path, message: `${path} must be an id: letters, digits, _ . : or -, starting with a letter or digit.` });
+    }
+    if (annotated.format === "date-time" && !(ISO_DATE_TIME.test(value) && Number.isFinite(Date.parse(value)))) {
+        issues.push({ path, message: `${path} must be an ISO 8601 date-time with a time zone.` });
+    }
+    if (annotated.format === "uri" && !isHttpUrl(value)) {
+        issues.push({ path, message: `${path} must be an absolute http(s) URL.` });
+    }
+}
+function isHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === "https:" || url.protocol === "http:";
+    }
+    catch {
+        return false;
+    }
+}
+function normalizedCallbackUrl(value) {
+    try {
+        return new URL(value).href;
+    }
+    catch {
+        throw new McpEventContractError("invalid_callback_url", "The callback URL is not an absolute URL.", [
+            { path: "delivery.url", message: "delivery.url must be an absolute URL." },
+        ]);
+    }
+}