@oxygen-agent/cli 1.1011.288 → 1.1011.326

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

@@ -0,0 +1,597 @@
+import { type ContractIssue, type ContractObject, type Infer } from "./contracts/schema.js";
+/** OpenAI MCP Events: one event per request, and the whole request body at most 256 KiB. */
+export declare const MCP_EVENT_MAX_BODY_BYTES = 262144;
+export declare const MCP_EVENT_NAMES: readonly ["reply.classified", "enrollment.ended", "meeting.completed", "record.stage_changed", "run.settled", "approval.requested"];
+export type McpEventName = (typeof MCP_EVENT_NAMES)[number];
+/** The events a workspace event ledger row (`ox_runs.workflow_events`) projects into. */
+export type McpCatalogEventName = Extract<McpEventName, "reply.classified" | "enrollment.ended" | "meeting.completed" | "record.stage_changed">;
+/**
+ * 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 declare const MCP_REPLY_CLASSIFICATIONS: readonly ["interested", "neutral", "not_now", "not_interested", "out_of_office", "wrong_person", "bounced", "unsubscribed", "other"];
+export type McpReplyClassification = (typeof MCP_REPLY_CLASSIFICATIONS)[number];
+export declare const MCP_REPLY_CHANNELS: readonly ["email", "linkedin", "whatsapp"];
+/** How an enrollment ended: the Sequencer's own terminal statuses. */
+export declare const MCP_ENROLLMENT_OUTCOMES: readonly ["completed", "replied", "stopped", "failed", "excluded"];
+/** The run ledgers `run_outcome_analytics` reads (`SettledRunKind` in @oxygen/tenant-db). */
+export declare const MCP_RUN_KINDS: readonly ["workflow", "table_action", "table_ingestion", "agent", "copilot_turn"];
+export type McpRunKind = (typeof MCP_RUN_KINDS)[number];
+/**
+ * Every terminal status those ledgers write, with one spelling of cancel:
+ * Workflow and Table runs write `canceled`, Agent runs and Copilot turns `cancelled`.
+ */
+export declare const MCP_RUN_STATUSES: readonly ["completed", "completed_with_errors", "failed", "canceled", "budget_exhausted", "effect_unknown"];
+export type McpRunStatus = (typeof MCP_RUN_STATUSES)[number];
+export declare const MCP_APPROVAL_KINDS: readonly ["workflow", "agent"];
+export type McpApprovalKind = (typeof MCP_APPROVAL_KINDS)[number];
+declare const REPLY_CLASSIFIED_PAYLOAD: ContractObject<{
+    readonly classification: {
+        type: "string";
+        enum: readonly ("bounced" | "interested" | "neutral" | "not_interested" | "not_now" | "other" | "out_of_office" | "unsubscribed" | "wrong_person")[];
+        description?: string;
+    };
+    readonly channel: {
+        type: "string";
+        enum: readonly ("email" | "linkedin" | "whatsapp")[];
+        description?: string;
+    };
+    readonly conversation_id: {
+        oneOf: [{
+            type: "string";
+            description?: string;
+            enum?: readonly string[];
+            minLength?: number;
+            maxLength?: number;
+            pattern: string;
+        }, import("./contracts/schema.js").NullProperty];
+        description?: string;
+    };
+    readonly record_id: {
+        oneOf: [{
+            type: "string";
+            description?: string;
+            enum?: readonly string[];
+            minLength?: number;
+            maxLength?: number;
+            pattern: string;
+        }, import("./contracts/schema.js").NullProperty];
+        description?: string;
+    };
+    readonly sequence_id: {
+        oneOf: [{
+            type: "string";
+            description?: string;
+            enum?: readonly string[];
+            minLength?: number;
+            maxLength?: number;
+            pattern: string;
+        }, import("./contracts/schema.js").NullProperty];
+        description?: string;
+    };
+    readonly enrollment_id: {
+        oneOf: [{
+            type: "string";
+            description?: string;
+            enum?: readonly string[];
+            minLength?: number;
+            maxLength?: number;
+            pattern: string;
+        }, import("./contracts/schema.js").NullProperty];
+        description?: string;
+    };
+    readonly occurred_at: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        format: "date-time";
+    };
+    readonly url: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        format: "uri";
+    };
+}, "channel" | "classification" | "conversation_id" | "enrollment_id" | "occurred_at" | "record_id" | "sequence_id" | "url">;
+declare const ENROLLMENT_ENDED_PAYLOAD: ContractObject<{
+    readonly outcome: {
+        type: "string";
+        enum: readonly ("completed" | "excluded" | "failed" | "replied" | "stopped")[];
+        description?: string;
+    };
+    readonly steps_sent: {
+        oneOf: [{
+            type: "integer";
+            description?: string;
+            minimum?: number;
+            maximum?: number;
+            "x-clamp"?: true;
+        }, import("./contracts/schema.js").NullProperty];
+        description?: string;
+    };
+    readonly sequence_id: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        pattern: string;
+    };
+    readonly enrollment_id: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        pattern: string;
+    };
+    readonly occurred_at: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        format: "date-time";
+    };
+    readonly url: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        format: "uri";
+    };
+}, "enrollment_id" | "occurred_at" | "outcome" | "sequence_id" | "steps_sent" | "url">;
+declare const MEETING_COMPLETED_PAYLOAD: ContractObject<{
+    readonly session_id: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        pattern: string;
+    };
+    readonly duration_seconds: {
+        oneOf: [{
+            type: "integer";
+            description?: string;
+            minimum?: number;
+            maximum?: number;
+            "x-clamp"?: true;
+        }, import("./contracts/schema.js").NullProperty];
+        description?: string;
+    };
+    readonly record_ids: {
+        readonly type: "array";
+        readonly description?: string;
+        readonly items: {
+            type: "string";
+            description?: string;
+            enum?: readonly string[];
+            minLength?: number;
+            maxLength?: number;
+            pattern: string;
+        };
+        readonly minItems?: number;
+        readonly maxItems?: number;
+        readonly uniqueItems: true;
+    };
+    readonly activity_id: {
+        oneOf: [{
+            type: "string";
+            description?: string;
+            enum?: readonly string[];
+            minLength?: number;
+            maxLength?: number;
+            pattern: string;
+        }, import("./contracts/schema.js").NullProperty];
+        description?: string;
+    };
+    readonly occurred_at: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        format: "date-time";
+    };
+    readonly url: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        format: "uri";
+    };
+}, "activity_id" | "duration_seconds" | "occurred_at" | "record_ids" | "session_id" | "url">;
+declare const RECORD_STAGE_CHANGED_PAYLOAD: ContractObject<{
+    readonly object: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        pattern: string;
+    };
+    readonly record_id: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        pattern: string;
+    };
+    readonly pipeline_id: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        pattern: string;
+    };
+    readonly from_stage_id: {
+        oneOf: [{
+            type: "string";
+            description?: string;
+            enum?: readonly string[];
+            minLength?: number;
+            maxLength?: number;
+            pattern: string;
+        }, import("./contracts/schema.js").NullProperty];
+        description?: string;
+    };
+    readonly to_stage_id: {
+        oneOf: [{
+            type: "string";
+            description?: string;
+            enum?: readonly string[];
+            minLength?: number;
+            maxLength?: number;
+            pattern: string;
+        }, import("./contracts/schema.js").NullProperty];
+        description?: string;
+    };
+    readonly activity_id: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        pattern: string;
+    };
+    readonly occurred_at: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        format: "date-time";
+    };
+    readonly url: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        format: "uri";
+    };
+}, "activity_id" | "from_stage_id" | "object" | "occurred_at" | "pipeline_id" | "record_id" | "to_stage_id" | "url">;
+declare const RUN_SETTLED_PAYLOAD: ContractObject<{
+    readonly kind: {
+        type: "string";
+        enum: readonly ("agent" | "copilot_turn" | "table_action" | "table_ingestion" | "workflow")[];
+        description?: string;
+    };
+    readonly status: {
+        type: "string";
+        enum: readonly ("budget_exhausted" | "canceled" | "completed" | "completed_with_errors" | "effect_unknown" | "failed")[];
+        description?: string;
+    };
+    readonly run_id: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        pattern: string;
+    };
+    readonly credits_used: {
+        oneOf: [{
+            type: "number";
+            description?: string;
+            minimum?: number;
+            maximum?: number;
+            "x-clamp"?: true;
+        }, import("./contracts/schema.js").NullProperty];
+        description?: string;
+    };
+    readonly occurred_at: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        format: "date-time";
+    };
+    readonly url: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        format: "uri";
+    };
+}, "credits_used" | "kind" | "occurred_at" | "run_id" | "status" | "url">;
+declare const APPROVAL_REQUESTED_PAYLOAD: ContractObject<{
+    readonly kind: {
+        type: "string";
+        enum: readonly ("agent" | "workflow")[];
+        description?: string;
+    };
+    readonly approval_id: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        pattern: string;
+    };
+    readonly run_id: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        pattern: string;
+    };
+    readonly occurred_at: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        format: "date-time";
+    };
+    readonly url: {
+        type: "string";
+        description?: string;
+        enum?: readonly string[];
+        minLength?: number;
+        maxLength?: number;
+        format: "uri";
+    };
+}, "approval_id" | "kind" | "occurred_at" | "run_id" | "url">;
+export type McpReplyClassifiedPayload = Infer<typeof REPLY_CLASSIFIED_PAYLOAD>;
+export type McpEnrollmentEndedPayload = Infer<typeof ENROLLMENT_ENDED_PAYLOAD>;
+export type McpMeetingCompletedPayload = Infer<typeof MEETING_COMPLETED_PAYLOAD>;
+export type McpRecordStageChangedPayload = Infer<typeof RECORD_STAGE_CHANGED_PAYLOAD>;
+export type McpRunSettledPayload = Infer<typeof RUN_SETTLED_PAYLOAD>;
+export type McpApprovalRequestedPayload = Infer<typeof APPROVAL_REQUESTED_PAYLOAD>;
+/** The `data` object each event delivers. */
+export type McpEventPayloads = {
+    "reply.classified": McpReplyClassifiedPayload;
+    "enrollment.ended": McpEnrollmentEndedPayload;
+    "meeting.completed": McpMeetingCompletedPayload;
+    "record.stage_changed": McpRecordStageChangedPayload;
+    "run.settled": McpRunSettledPayload;
+    "approval.requested": McpApprovalRequestedPayload;
+};
+/** One `events/list` entry, in the shape OpenAI's MCP Events contract defines. */
+export type McpEventDefinition = {
+    readonly name: McpEventName;
+    readonly description: string;
+    readonly delivery: readonly ["webhook"];
+    /** The subscription arguments: every one an optional filter. */
+    readonly inputSchema: ContractObject;
+    /** The delivered `data` object. */
+    readonly payloadSchema: ContractObject;
+};
+/** What `events/list` answers, in this order. Plain JSON: nothing internal rides along. Read-only. */
+export declare const MCP_EVENT_DEFINITIONS: readonly McpEventDefinition[];
+export type McpEventFilterBinding = {
+    /** The payload field the argument is compared with. */
+    readonly field: string;
+    /** `equals`: the field holds the argument. `includes`: the field is a list that contains it. */
+    readonly match: "equals" | "includes";
+};
+/** How each subscription argument narrows delivery. Applied by OXYGEN before anything is sent. */
+export declare const MCP_EVENT_FILTERS: {
+    readonly [N in McpEventName]: Readonly<Record<string, McpEventFilterBinding>>;
+};
+export type McpEventContractErrorCode = "unknown_event" | "invalid_arguments" | "invalid_callback_url" | "invalid_principal" | "invalid_source_event" | "invalid_payload" | "payload_too_large";
+export type McpEventContractIssue = ContractIssue;
+export declare class McpEventContractError extends Error {
+    readonly code: McpEventContractErrorCode;
+    /** -32011 or -32602 when the caller's request is at fault; null when OXYGEN's own data is. */
+    readonly jsonRpcCode: -32011 | -32602 | null;
+    readonly issues: readonly McpEventContractIssue[];
+    constructor(code: McpEventContractErrorCode, message: string, issues?: readonly McpEventContractIssue[]);
+}
+export declare function isMcpEventName(value: unknown): value is McpEventName;
+/** The event's definition, or `unknown_event` (-32011). */
+export declare function requireMcpEventDefinition(name: unknown): McpEventDefinition;
+/** Validated filter values, keyed by argument, in sorted key order. Every v1 filter is a string. */
+export type McpEventArguments = Readonly<Record<string, string>>;
+/**
+ * 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 declare function validateMcpEventArguments(name: unknown, args: unknown): McpEventArguments;
+/**
+ * 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 declare function assertMcpEventPayload<N extends McpEventName>(name: N, payload: unknown): McpEventPayloads[N];
+/**
+ * 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 declare function mcpEventMatchesSubscription(input: {
+    name: unknown;
+    arguments: unknown;
+    payload: unknown;
+}): boolean;
+/** Who holds a subscription (ADR 0030 §2): one user's OAuth connection in one organization. */
+export type McpEventPrincipal = {
+    organizationId: string;
+    userId: string;
+    /** The OAuth client of the connection, e.g. the ChatGPT connector. */
+    oauthClientId: string;
+};
+/**
+ * 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 declare function mcpEventSubscriptionId(input: {
+    principal: McpEventPrincipal;
+    callbackUrl: string;
+    name: McpEventName;
+    arguments?: Readonly<Record<string, unknown>> | null;
+}): string;
+/**
+ * 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 declare function mcpEventDeliveryId(input: {
+    subscriptionId: string;
+    sourceEventKey: string;
+}): string;
+export type McpEventDelivery = {
+    /** The body's `eventId` and the `webhook-id` header; the same on every retry. */
+    eventId: string;
+    /** The exact bytes to sign and send, serialized once. */
+    body: string;
+    /** UTF-8 length of `body`. */
+    bytes: number;
+};
+/**
+ * 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 declare function serializeMcpEventDelivery<N extends McpEventName>(input: {
+    subscriptionId: string;
+    name: N;
+    sourceEventKey: string;
+    data: McpEventPayloads[N];
+    /** Defaults to {@link MCP_EVENT_MAX_BODY_BYTES}. */
+    maxBodyBytes?: number;
+}): McpEventDelivery;
+/**
+ * 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 declare function canonicalMcpEventJson(value: unknown): string;
+/** Where a payload's deep link points. Defaults to the deployment's public app URL. */
+export type McpEventLinkOptions = {
+    appBaseUrl?: string;
+};
+/** One `ox_runs.workflow_events` row as the MCP event reader holds it. */
+export type McpWorkspaceEventRow = {
+    source: string;
+    /** The row's `event_type`. */
+    event: string;
+    payload: unknown;
+    metadata?: unknown;
+    /** The row's `received_at`: the occurrence time when the payload carries none. */
+    receivedAt: Date | string;
+};
+/**
+ * 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 declare function mcpEventNameForWorkspaceEvent(row: Pick<McpWorkspaceEventRow, "source" | "event" | "payload" | "metadata">): McpCatalogEventName | 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 declare function projectReplyClassifiedEvent(row: McpWorkspaceEventRow, context?: McpEventLinkOptions & {
+    record?: {
+        object: string;
+        id: string;
+    } | null;
+}): McpReplyClassifiedPayload;
+/**
+ * `sequencer / enrollment_terminal` as `enrollment.ended`. The outbox row does
+ * not count sends, so the reader passes the enrollment's sent steps.
+ */
+export declare function projectEnrollmentEndedEvent(row: McpWorkspaceEventRow, context: McpEventLinkOptions & {
+    stepsSent: number | null;
+}): McpEnrollmentEndedPayload;
+/** `oxygen.notetaker / meeting.completed` as `meeting.completed`. */
+export declare function projectMeetingCompletedEvent(row: McpWorkspaceEventRow, context?: McpEventLinkOptions): McpMeetingCompletedPayload;
+/**
+ * `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 declare function projectRecordStageChangedEvent(row: McpWorkspaceEventRow, context?: McpEventLinkOptions & {
+    stageIds?: {
+        from: string | null;
+        to: string | null;
+    };
+}): McpRecordStageChangedPayload;
+type McpRunSettledCommon = {
+    runId: string;
+    /** The ledger's own terminal status. */
+    status: string;
+    /** Credits the run spent, when its ledger records a figure. */
+    creditsUsed: number | null;
+    settledAt: Date | string;
+};
+/** A settled run as the `run_outcome_analytics` reader sees it, plus the parent its deep link needs. */
+export type McpRunSettledSource = McpRunSettledCommon & ({
+    kind: "workflow";
+    workflowId: string;
+} | {
+    kind: "table_action" | "table_ingestion";
+    tableId: string;
+} | {
+    kind: "agent";
+    agentSlug: string;
+} | {
+    kind: "copilot_turn";
+    copilotSessionId: string;
+});
+/** A settled run as `run.settled`. Its producer is OXP-11.5.21. */
+export declare function projectRunSettledEvent(source: McpRunSettledSource, context?: McpEventLinkOptions): McpRunSettledPayload;
+/** A pending approval on a Workflow or Agent run. */
+export type McpApprovalRequestedSource = {
+    approvalId: string;
+    runId: string;
+    requestedAt: Date | string;
+} & ({
+    kind: "workflow";
+    workflowId: string;
+} | {
+    kind: "agent";
+    agentSlug: string;
+});
+/** A pending approval as `approval.requested`. Its producer is OXP-11.5.21. */
+export declare function projectApprovalRequestedEvent(source: McpApprovalRequestedSource, context?: McpEventLinkOptions): McpApprovalRequestedPayload;
+export {};