@oxygen-agent/cli 1.638.1 → 1.662.0

package/node_modules/@oxygen/shared/dist/collab.js

@@ -0,0 +1,410 @@
+// Collaboration vocabulary (Control-layer interaction state, NOT a sixteenth
+// primitive). A comment thread or an approval request is state ABOUT a GTM
+// artifact — the artifact itself still belongs to its owning primitive, and the
+// approval gate is honored by that primitive's own route (Sequences still owns
+// whether a sequence launches). Same precedent ADR 0013 set for the Workspace
+// Copilot: durable interaction state may own a tenant store, GTM primitive
+// state may not.
+//
+// This module is the ONE vocabulary the tenant schema (`ox_collab`), the
+// `/api/cli/collab/*` routes, the CLI groups, and the MCP tools all read from:
+// which kinds can carry a thread, how a subject is addressed as a string, which
+// gates apply to which kinds, and what the statuses are. Nothing here talks to a
+// database or a transport — it is deliberately importable from every surface.
+//
+// Unlike Tags (a label that fits in a `text[]` column on the row it describes),
+// a thread is an independent entity with its own author, body, replies, and
+// lifecycle, so it is stored separately and addressed by an explicit subject
+// reference — `<kind>:<id>` — rather than by a column on the subject.
+import { OxygenError } from "./cli-result.js";
+/**
+ * Workspace objects that can carry a comment thread or an approval request.
+ *
+ * Seeded from {@link TAG_KINDS}: anything worth labelling for a campaign is
+ * worth discussing with the client who signs that campaign off. The list is
+ * RESTATED rather than aliased because it is also a stored value — the
+ * `ox_collab` CHECK constraint and existing rows pin it — so widening the tag
+ * vocabulary must be a deliberate decision here, not a silent side effect that
+ * lets the API accept a kind the database rejects. The alignment is enforced
+ * both ways: {@link EveryTagKindIsCommentable} fails the build if a taggable
+ * kind is missing, and the paired test pins today's list exactly.
+ */
+export const COLLAB_SUBJECT_KINDS = [
+    "knowledge_page",
+    "publishing_post",
+    "sequence",
+    "table",
+    "workflow",
+    "recipe",
+    "conversation",
+    "mailbox",
+    "sender",
+    "record",
+    "domain",
+    "project",
+];
+export function isCollabSubjectKind(value) {
+    return typeof value === "string" && COLLAB_SUBJECT_KINDS.includes(value);
+}
+/**
+ * How each subject kind is named in output. Total over CollabSubjectKind, so
+ * adding a kind is a compile error until it is labelled — the guarantee
+ * `TAG_KIND_LABELS` had to learn the hard way when three hand-maintained copies
+ * of the same map drifted apart.
+ *
+ * `many` keeps proper nouns intact ("CRM records") so an inline count reads
+ * correctly; headings run it through {@link collabSubjectHeading}, which only
+ * uppercases a leading lowercase letter.
+ */
+export const COLLAB_SUBJECT_LABELS = {
+    knowledge_page: { one: "knowledge page", many: "knowledge pages" },
+    publishing_post: { one: "publishing post", many: "publishing posts" },
+    sequence: { one: "sequence", many: "sequences" },
+    table: { one: "table", many: "tables" },
+    workflow: { one: "workflow", many: "workflows" },
+    recipe: { one: "recipe", many: "recipes" },
+    conversation: { one: "conversation", many: "conversations" },
+    mailbox: { one: "mailbox", many: "mailboxes" },
+    sender: { one: "sender account", many: "sender accounts" },
+    record: { one: "CRM record", many: "CRM records" },
+    domain: { one: "sending domain", many: "sending domains" },
+    project: { one: "project", many: "projects" },
+};
+/**
+ * What a thread on each kind is usually about, for `--help` and MCP tool
+ * descriptions. Total over CollabSubjectKind for the same reason the labels
+ * are: a blind-user eval (2026-07-21) found `tags --help` still advertising 7
+ * of 13 kinds because the prose was hand-written beside a hand-maintained
+ * marker map, so six taggable kinds were invisible from the one place a user
+ * looks. Here the help text cannot omit a kind — the compiler rejects the map
+ * until the kind is glossed, and {@link COLLAB_SUBJECT_KINDS_PROSE} is DERIVED
+ * from the labels rather than typed out a second time.
+ */
+export const COLLAB_SUBJECT_PROSE = {
+    knowledge_page: "a wiki page's copy before it becomes canonical",
+    publishing_post: "a post's copy before it is published",
+    sequence: "a campaign's messaging before it launches",
+    table: "a list's rows and columns, or one cell's value",
+    workflow: "an automation's graph before it runs live",
+    recipe: "an installable motion before it is installed",
+    conversation: "a reply in an inbox thread before it is sent",
+    mailbox: "a mailbox's configuration or health",
+    sender: "a sender account's caps and warmup",
+    record: "a CRM record's truth",
+    domain: "a sending domain's DNS and warmup",
+    project: "a project's scope",
+};
+/** Oxford-comma list: ["a"] -> "a"; ["a","b"] -> "a and b"; ["a","b","c"] -> "a, b, and c". */
+function formatProseList(items) {
+    if (items.length <= 1)
+        return items[0] ?? "";
+    if (items.length === 2)
+        return `${items[0]} and ${items[1]}`;
+    return `${items.slice(0, -1).join(", ")}, and ${items[items.length - 1]}`;
+}
+/**
+ * Every commentable kind in prose, for CLI `--help` and MCP tool descriptions.
+ * Derived from {@link COLLAB_SUBJECT_LABELS} on purpose: a hand-written copy is
+ * exactly what drifted in the tags help.
+ */
+export const COLLAB_SUBJECT_KINDS_PROSE = formatProseList(COLLAB_SUBJECT_KINDS.map((kind) => COLLAB_SUBJECT_LABELS[kind].many));
+/** Inline label for a count: `collabSubjectLabel("sequence", 1)` -> "sequence". */
+export function collabSubjectLabel(kind, count) {
+    const entry = isCollabSubjectKind(kind) ? COLLAB_SUBJECT_LABELS[kind] : null;
+    if (!entry)
+        return kind;
+    return count === 1 ? entry.one : entry.many;
+}
+/** Section heading for a kind: "Sequences", "CRM records". */
+export function collabSubjectHeading(kind) {
+    const entry = isCollabSubjectKind(kind) ? COLLAB_SUBJECT_LABELS[kind] : null;
+    const label = entry ? entry.many : kind;
+    return label.charAt(0).toUpperCase() + label.slice(1);
+}
+/**
+ * Render a subject as the `<kind>:<id>` string every surface accepts
+ * (`--on sequence:9f1c...`). Throws rather than emitting an unparseable ref,
+ * because a malformed ref written into a stored row is drift nobody notices
+ * until a read fails.
+ */
+export function formatSubjectRef(ref) {
+    if (!isCollabSubjectKind(ref.kind)) {
+        throw invalidSubjectRef(`Unknown subject kind "${ref.kind}".`, { kind: ref.kind });
+    }
+    const id = ref.id.trim();
+    if (!id) {
+        throw invalidSubjectRef("Subject id is required.", { kind: ref.kind });
+    }
+    return `${ref.kind}:${id}`;
+}
+/**
+ * Parse `<kind>:<id>`. Splits on the FIRST colon only, so an id that itself
+ * contains colons survives the round trip; an input with no colon at all is
+ * rejected rather than being guessed at (there is no default kind — a bare id
+ * would silently address the wrong store).
+ */
+export function tryParseSubjectRef(value) {
+    if (typeof value !== "string")
+        return null;
+    const raw = value.trim();
+    const separator = raw.indexOf(":");
+    if (separator <= 0)
+        return null;
+    const kind = raw.slice(0, separator);
+    const id = raw.slice(separator + 1).trim();
+    if (!isCollabSubjectKind(kind) || !id)
+        return null;
+    return { kind, id };
+}
+/** Throwing variant of {@link tryParseSubjectRef}, for surfaces that want the typed error. */
+export function parseSubjectRef(value) {
+    const parsed = tryParseSubjectRef(value);
+    if (parsed)
+        return parsed;
+    throw invalidSubjectRef(`Subject must be "<kind>:<id>" — for example "sequence:9f1c2b7e". Valid kinds: ${COLLAB_SUBJECT_KINDS.join(", ")}.`, { subject: typeof value === "string" ? value : null });
+}
+function invalidSubjectRef(message, details) {
+    return new OxygenError("invalid_subject_ref", message, {
+        details: { ...details, valid_kinds: [...COLLAB_SUBJECT_KINDS] },
+        exitCode: 2,
+    });
+}
+/**
+ * Sub-object addressing inside one subject, so commenting on a single cell does
+ * not need a thread table per kind: `row:<rowId>` for a whole row,
+ * `row:<rowId>#<columnKey>` for one cell, `column:<columnKey>` for a whole
+ * column. Unknown prefixes are still rejected rather than stored — an address no
+ * reader understands is worse than a refusal.
+ *
+ * `column:` was added in the second Collaboration pass because a column is what
+ * an agency and its client actually argue about ("why is Stage set this way?"),
+ * and it had no address at all: every path had to name a row first. It is a
+ * SIBLING of `row:`, not a variant of it, which is why the type below is a
+ * discriminated union — a column path has no row, and an optional `rowId` would
+ * let `{}` typecheck as a valid path.
+ */
+export const SUBJECT_PATH_ROW_PREFIX = "row:";
+export const SUBJECT_PATH_COLUMN_PREFIX = "column:";
+/** Every path form in prose, for `--help`, MCP descriptors, and error messages. */
+export const SUBJECT_PATH_FORMS_PROSE = '"row:<rowId>" for one row, "row:<rowId>#<columnKey>" for one cell, or "column:<columnKey>" for one column';
+/**
+ * Render a sub-object path: `{ kind: "row", rowId: "abc" }` -> "row:abc"; with a
+ * column -> "row:abc#email"; `{ kind: "column", columnKey: "email" }` ->
+ * "column:email".
+ */
+export function formatSubjectPath(path) {
+    if (path.kind === "column") {
+        const columnKey = path.columnKey.trim();
+        if (!columnKey || columnKey.includes("#")) {
+            throw invalidSubjectPath('Column key is required and cannot contain "#".', {
+                column_key: path.columnKey,
+            });
+        }
+        return `${SUBJECT_PATH_COLUMN_PREFIX}${columnKey}`;
+    }
+    const rowId = path.rowId.trim();
+    if (!rowId || rowId.includes("#")) {
+        throw invalidSubjectPath('Row id is required and cannot contain "#".', { row_id: path.rowId });
+    }
+    const columnKey = path.columnKey?.trim() ?? "";
+    if (path.columnKey !== undefined && !columnKey) {
+        throw invalidSubjectPath("Column key cannot be blank.", { row_id: rowId });
+    }
+    const base = `${SUBJECT_PATH_ROW_PREFIX}${rowId}`;
+    return columnKey ? `${base}#${columnKey}` : base;
+}
+export function tryParseSubjectPath(value) {
+    if (typeof value !== "string")
+        return null;
+    const raw = value.trim();
+    if (raw.startsWith(SUBJECT_PATH_COLUMN_PREFIX)) {
+        const columnKey = raw.slice(SUBJECT_PATH_COLUMN_PREFIX.length).trim();
+        // No `#` inside a column path: a column addresses no row, so a hash here
+        // means the caller meant a cell and got the prefix wrong.
+        if (!columnKey || columnKey.includes("#"))
+            return null;
+        return { kind: "column", columnKey };
+    }
+    if (!raw.startsWith(SUBJECT_PATH_ROW_PREFIX))
+        return null;
+    const remainder = raw.slice(SUBJECT_PATH_ROW_PREFIX.length);
+    const hash = remainder.indexOf("#");
+    if (hash < 0) {
+        const rowId = remainder.trim();
+        return rowId ? { kind: "row", rowId } : null;
+    }
+    const rowId = remainder.slice(0, hash).trim();
+    const columnKey = remainder.slice(hash + 1).trim();
+    if (!rowId || !columnKey || columnKey.includes("#"))
+        return null;
+    return { kind: "row", rowId, columnKey };
+}
+/** Throwing variant of {@link tryParseSubjectPath}. */
+export function parseSubjectPath(value) {
+    const parsed = tryParseSubjectPath(value);
+    if (parsed)
+        return parsed;
+    throw invalidSubjectPath(`Path must be ${SUBJECT_PATH_FORMS_PROSE} — for example "row:8f2c1a4d#email".`, { path: typeof value === "string" ? value : null });
+}
+function invalidSubjectPath(message, details) {
+    return new OxygenError("invalid_subject_path", message, { details, exitCode: 2 });
+}
+/**
+ * The gates a workspace can require. `launch` is the client's go/no-go before a
+ * campaign sends; `signoff` is their sign-off on the list that campaign sends
+ * to. Both are OPT-IN per subject (or per subject kind) — an unset gate leaves
+ * today's behavior untouched.
+ */
+export const COLLAB_GATE_KINDS = ["launch", "signoff"];
+export function isCollabGateKind(value) {
+    return typeof value === "string" && COLLAB_GATE_KINDS.includes(value);
+}
+/**
+ * Which subject kinds each gate can be required on. Total over CollabGateKind,
+ * so a new gate cannot ship without naming the primitives that must honor it —
+ * a gate nobody enforces is worse than no gate, because the workspace believes
+ * it is protected.
+ */
+export const GATE_KIND_SUBJECTS = {
+    launch: ["sequence"],
+    signoff: ["table"],
+};
+/** What each gate means, for `--help` and MCP descriptors. Total over CollabGateKind. */
+export const COLLAB_GATE_PROSE = {
+    launch: "approve before a sequence starts sending live",
+    signoff: "approve the table's rows before they are worked",
+};
+export function isGateKindValidForSubject(gateKind, subjectKind) {
+    if (!isCollabGateKind(gateKind) || !isCollabSubjectKind(subjectKind))
+        return false;
+    return GATE_KIND_SUBJECTS[gateKind].includes(subjectKind);
+}
+/** Every gate that can be required on a subject kind — drives `approvals gate list`. */
+export function gateKindsForSubject(subjectKind) {
+    if (!isCollabSubjectKind(subjectKind))
+        return [];
+    return COLLAB_GATE_KINDS.filter((gate) => GATE_KIND_SUBJECTS[gate].includes(subjectKind));
+}
+/** A thread is open until somebody resolves it; reopening flips it back. */
+export const COLLAB_THREAD_STATUSES = ["open", "resolved"];
+export function isCollabThreadStatus(value) {
+    return typeof value === "string" && COLLAB_THREAD_STATUSES.includes(value);
+}
+export const COLLAB_REQUEST_STATUSES = [
+    "pending",
+    "approved",
+    "changes_requested",
+    "rejected",
+    "cancelled",
+    "expired",
+];
+export function isCollabRequestStatus(value) {
+    return typeof value === "string" && COLLAB_REQUEST_STATUSES.includes(value);
+}
+/**
+ * The whole feature hinges on this one line: ONLY `approved` opens a gate.
+ *
+ * `changes_requested` is a decision, and it ends the requester's wait, but it is
+ * not consent — the client asked for edits. Treating it as terminal-and-done is
+ * the obvious bug (a request that is no longer pending looks "handled"), so the
+ * gate check asks this function rather than testing `status !== "pending"`.
+ */
+export function requestStatusOpensGate(status) {
+    return status === "approved";
+}
+/** Statuses that no longer await a decision. `pending` is the only live state. */
+export const COLLAB_REQUEST_TERMINAL_STATUSES = [
+    "approved",
+    "changes_requested",
+    "rejected",
+    "cancelled",
+    "expired",
+];
+export function isTerminalRequestStatus(status) {
+    return isCollabRequestStatus(status) && status !== "pending";
+}
+/**
+ * What an approver may do, as the CLI/MCP spells it — and the status each
+ * decision writes. Total over CollabDecision so the API, the CLI flags, and the
+ * MCP tool cannot each invent their own mapping (the failure mode being a
+ * `changes_requested` decision stored as `rejected`, which reads to the agency
+ * as "the client said no" rather than "the client wants edits").
+ */
+export const COLLAB_DECISIONS = ["approve", "reject", "changes_requested"];
+export function isCollabDecision(value) {
+    return typeof value === "string" && COLLAB_DECISIONS.includes(value);
+}
+export const COLLAB_DECISION_STATUSES = {
+    approve: "approved",
+    reject: "rejected",
+    changes_requested: "changes_requested",
+};
+/** Why a notification exists. Delivery itself is the notifier's problem. */
+export const COLLAB_NOTIFICATION_KINDS = ["assigned", "mentioned", "decided", "replied"];
+export function isCollabNotificationKind(value) {
+    return (typeof value === "string" && COLLAB_NOTIFICATION_KINDS.includes(value));
+}
+export const COLLAB_NOTIFICATION_STATUSES = ["pending", "sent", "failed", "skipped"];
+export function isCollabNotificationStatus(value) {
+    return (typeof value === "string" && COLLAB_NOTIFICATION_STATUSES.includes(value));
+}
+/**
+ * Body/field caps. Shared so the API, the CLI, and the tenant column widths
+ * agree — three independently chosen limits means the CLI accepts what the API
+ * truncates.
+ */
+export const MAX_COMMENT_BODY_LENGTH = 10_000;
+export const MAX_THREAD_TITLE_LENGTH = 200;
+export const MAX_DECISION_NOTE_LENGTH = 2_000;
+/** Bounds the notification fan-out one comment or request can trigger. */
+export const MAX_MENTIONS_PER_COMMENT = 25;
+export const MAX_ASSIGNEES_PER_REQUEST = 10;
+/**
+ * Normalize one comment body: trim, reject blanks, non-strings, and anything
+ * over {@link MAX_COMMENT_BODY_LENGTH}. Returns `null` so each surface can raise
+ * its own typed error (the CLI wants an exit code, the API wants a status).
+ *
+ * Deliberately does NOT strip or rewrite the body beyond trimming — a comment is
+ * the client's words, and Markdown, quoted text, and whitespace layout are part
+ * of what they wrote.
+ */
+export function normalizeCommentBody(value) {
+    if (typeof value !== "string")
+        return null;
+    const normalized = value.trim();
+    if (!normalized || normalized.length > MAX_COMMENT_BODY_LENGTH)
+        return null;
+    return normalized;
+}
+/**
+ * The Oxygen-side membership role overlay (control DB
+ * `organization_memberships.oxygen_role`). NULL means no override — today's
+ * behavior for every existing member — and `client` is the restricted role an
+ * agency hands its client: read the work, comment on it, decide the approvals
+ * assigned to them, and nothing else.
+ *
+ * Deliberately not a Clerk custom role: those need dashboard configuration, and
+ * repo doctrine requires asking a human before touching Clerk. Keep this list in
+ * step with the `organization_memberships_oxygen_role_check` constraint in
+ * control migration 0095 — the CHECK is what stops a typo from creating a role
+ * nothing enforces.
+ */
+export const COLLAB_MEMBER_ROLES = ["client"];
+export function isCollabMemberRole(value) {
+    return typeof value === "string" && COLLAB_MEMBER_ROLES.includes(value);
+}
+/**
+ * The CLERK workspace roles that carry admin authority (control DB
+ * `organization_memberships.role`). Both spellings of each: Clerk writes the
+ * `org:`-prefixed form, older rows carry the bare one.
+ *
+ * The overlay above and this list are the two halves of one question — "may this
+ * member do X" — and a Clerk admin's role OVERRIDES the overlay, which is why
+ * granting `client` to one is refused. Keeping the vocabulary here means the
+ * collaboration lib can ask without importing the billing graph, and there is
+ * one list to change if Clerk ever gains another admin-ish role.
+ */
+export const WORKSPACE_ADMIN_ROLES = ["admin", "owner", "org:admin", "org:owner"];
+export function isWorkspaceAdminRole(role) {
+    return WORKSPACE_ADMIN_ROLES.includes(role.toLowerCase());
+}

package/node_modules/@oxygen/shared/dist/column-types.d.ts

@@ -12,8 +12,8 @@
  */
 /** Data types an import can infer for a brand-new column. Dates-only by design. */
 export type ImportColumnDataType = "text" | "timestamptz";
-/** Data types a `text` column can be explicitly retyped into. */
-export type RetypeableDataType = "text" | "numeric" | "boolean" | "timestamptz";
+/** Data types a plain data column can be explicitly retyped into. */
+export type RetypeableDataType = "text" | "numeric" | "boolean" | "jsonb" | "timestamptz";
 export declare const RETYPEABLE_DATA_TYPES: readonly RetypeableDataType[];
 export declare const EXCEL_SERIAL_MIN = 10000;
 export declare const EXCEL_SERIAL_MAX = 80000;
@@ -41,7 +41,7 @@ export declare function parseDateValueToIso(value: unknown, options?: {
 export declare function inferImportColumnDataType(label: string, values: Iterable<unknown>): ImportColumnDataType;
 export type CoercionResult = {
     ok: true;
-    value: string | number | boolean | null;
+    value: unknown | null;
 } | {
     ok: false;
     reason: string;

package/node_modules/@oxygen/shared/dist/column-types.js

@@ -14,6 +14,7 @@ export const RETYPEABLE_DATA_TYPES = [
     "text",
     "numeric",
     "boolean",
+    "jsonb",
     "timestamptz",
 ];
 // Excel/Sheets store dates as a serial number of days since 1899-12-30.
@@ -134,7 +135,17 @@ value, dataType) {
     }
     switch (dataType) { // skipcq: JS-0047
         case "text":
-            return { ok: true, value: typeof value === "string" ? value : String(value) };
+            if (typeof value === "string")
+                return { ok: true, value };
+            if (typeof value === "object") {
+                try {
+                    return { ok: true, value: JSON.stringify(value) };
+                }
+                catch {
+                    return { ok: false, reason: "not JSON-serializable text" };
+                }
+            }
+            return { ok: true, value: String(value) };
         case "timestamptz": {
             const iso = parseDateValueToIso(value, { allowExcelSerial: true });
             return iso
@@ -157,5 +168,19 @@ value, dataType) {
             }
             return { ok: false, reason: "not a recognized boolean" };
         }
+        case "jsonb": {
+            try {
+                if (typeof value === "string") {
+                    return { ok: true, value: JSON.parse(value.trim()) };
+                }
+                const serialized = JSON.stringify(value);
+                if (serialized === undefined)
+                    return { ok: false, reason: "not valid JSON" };
+                return { ok: true, value: JSON.parse(serialized) };
+            }
+            catch {
+                return { ok: false, reason: "not valid JSON" };
+            }
+        }
     }
 }

package/node_modules/@oxygen/shared/dist/index.d.ts

@@ -11,6 +11,7 @@ export * from "./cell-format.js";
 export * from "./cli-envelope.js";
 export * from "./cli-login-code.js";
 export * from "./cli-result.js";
+export * from "./collab.js";
 export * from "./crm-reply-events.js";
 export * from "./crm-activity-events.js";
 export * from "./column-types.js";
@@ -45,6 +46,7 @@ export * from "./sequences.js";
 export * from "./suppression-entries.js";
 export * from "./table-limits.js";
 export * from "./log.js";
+export * from "./axiom-field-budget.js";
 export { sanitizeLogFields } from "./redaction.js";
 export * from "./provider-request-outcomes.js";
 export * from "./schedule-label.js";

package/node_modules/@oxygen/shared/dist/index.js

@@ -11,6 +11,7 @@ export * from "./cell-format.js";
 export * from "./cli-envelope.js";
 export * from "./cli-login-code.js";
 export * from "./cli-result.js";
+export * from "./collab.js";
 export * from "./crm-reply-events.js";
 export * from "./crm-activity-events.js";
 export * from "./column-types.js";
@@ -45,6 +46,7 @@ export * from "./sequences.js";
 export * from "./suppression-entries.js";
 export * from "./table-limits.js";
 export * from "./log.js";
+export * from "./axiom-field-budget.js";
 // Narrow, deliberate export (ADR 0014): lets telemetry emitters regression-test
 // their field names against the REAL log sanitizer — the unanchored
 // SECRET_KEY_PATTERN redacts any name containing "token", which mocked loggers

package/node_modules/@oxygen/shared/dist/pricing-sheet.d.ts

@@ -90,6 +90,36 @@ export declare const VOICE_CREDITS_PER_AMD_CALL = 38;
 /** Managed domains: registrar at-cost × 1.25 (≈ a $10.44 .com → ~13,050 credits/yr). */
 export declare const MANAGED_DOMAIN_MARKUP = 1.25;
 export declare const MANAGED_DOMAIN_CREDITS_PER_YEAR_TYPICAL = 13050;
+/**
+ * Inbox deliverability (EmailGuard placement seat). A flat monthly price per
+ * SUBSCRIBED inbox covering continuous deliverability monitoring (blacklist,
+ * SPF/DKIM/DMARC, domain reputation) plus an included allowance of
+ * inbox-placement (spam) tests; tests beyond the allowance bill the per-test
+ * price.
+ *
+ * All three are DISPLAY mirrors, per this file's contract. The canonical values
+ * live where they are enforced, and seed-parity.test.ts binds them so a mirror
+ * can never quietly drift from the number actually billed:
+ *   seat      DELIVERABILITY_UNIT_MONTHLY_CREDITS       (@oxygen/control-db,
+ *             also PRICING_SEED commitment.deliverability_unit) — 1,000 credits
+ *             ($1.00), restored by the founder on 2026-07-30 after reviewing the
+ *             Agency-plan unit economics, superseding the 2026-07-26 signature
+ *             of 2,000.
+ *   allowance DELIVERABILITY_INCLUDED_TESTS_PER_INBOX  (@oxygen/control-db)
+ *   overage   EMAILGUARD_MANAGED_PLACEMENT_CREDITS     (@oxygen/providers,
+ *             derived from the Agency plan rather than typed in)
+ *
+ * THE ALLOWANCE IS LOAD-BEARING, not a perk. Placement COGS is per TEST
+ * ($0.1327 on EmailGuard's Agency plan), not per inbox, so an unbounded seat
+ * inverts its own margin: at $1.00/inbox-month the EIGHTH test in a cycle is
+ * already sold at a loss. Two included tests cost $0.265 against $1.00 of
+ * revenue — a ~73% margin — and everything past them bills
+ * PLACEMENT_TEST_OVERAGE_CREDITS. Orgs on their own EmailGuard key (BYOK) pay 0.
+ */
+export declare const DELIVERABILITY_SEAT_CREDITS_PER_MONTH = 1000;
+export declare const DELIVERABILITY_INCLUDED_TESTS_PER_INBOX = 2;
+/** Overage placement test: $0.1327 EmailGuard COGS × 1.25, rounded up. */
+export declare const PLACEMENT_TEST_OVERAGE_CREDITS = 166;
 /**
  * LinkedIn accounts: founder decision (2026-07-25) — a PURE seat model. The
  * flat monthly connection fee per connected account is now the WHOLE LinkedIn

package/node_modules/@oxygen/shared/dist/pricing-sheet.js

@@ -82,6 +82,36 @@ export const VOICE_CREDITS_PER_AMD_CALL = 38;
 /** Managed domains: registrar at-cost × 1.25 (≈ a $10.44 .com → ~13,050 credits/yr). */
 export const MANAGED_DOMAIN_MARKUP = 1.25;
 export const MANAGED_DOMAIN_CREDITS_PER_YEAR_TYPICAL = 13_050;
+/**
+ * Inbox deliverability (EmailGuard placement seat). A flat monthly price per
+ * SUBSCRIBED inbox covering continuous deliverability monitoring (blacklist,
+ * SPF/DKIM/DMARC, domain reputation) plus an included allowance of
+ * inbox-placement (spam) tests; tests beyond the allowance bill the per-test
+ * price.
+ *
+ * All three are DISPLAY mirrors, per this file's contract. The canonical values
+ * live where they are enforced, and seed-parity.test.ts binds them so a mirror
+ * can never quietly drift from the number actually billed:
+ *   seat      DELIVERABILITY_UNIT_MONTHLY_CREDITS       (@oxygen/control-db,
+ *             also PRICING_SEED commitment.deliverability_unit) — 1,000 credits
+ *             ($1.00), restored by the founder on 2026-07-30 after reviewing the
+ *             Agency-plan unit economics, superseding the 2026-07-26 signature
+ *             of 2,000.
+ *   allowance DELIVERABILITY_INCLUDED_TESTS_PER_INBOX  (@oxygen/control-db)
+ *   overage   EMAILGUARD_MANAGED_PLACEMENT_CREDITS     (@oxygen/providers,
+ *             derived from the Agency plan rather than typed in)
+ *
+ * THE ALLOWANCE IS LOAD-BEARING, not a perk. Placement COGS is per TEST
+ * ($0.1327 on EmailGuard's Agency plan), not per inbox, so an unbounded seat
+ * inverts its own margin: at $1.00/inbox-month the EIGHTH test in a cycle is
+ * already sold at a loss. Two included tests cost $0.265 against $1.00 of
+ * revenue — a ~73% margin — and everything past them bills
+ * PLACEMENT_TEST_OVERAGE_CREDITS. Orgs on their own EmailGuard key (BYOK) pay 0.
+ */
+export const DELIVERABILITY_SEAT_CREDITS_PER_MONTH = 1_000;
+export const DELIVERABILITY_INCLUDED_TESTS_PER_INBOX = 2;
+/** Overage placement test: $0.1327 EmailGuard COGS × 1.25, rounded up. */
+export const PLACEMENT_TEST_OVERAGE_CREDITS = 166;
 /**
  * LinkedIn accounts: founder decision (2026-07-25) — a PURE seat model. The
  * flat monthly connection fee per connected account is now the WHOLE LinkedIn

package/node_modules/@oxygen/shared/dist/social-capabilities.d.ts

@@ -2,13 +2,12 @@
  * Social channel capability registry.
  *
  * Channel, provider rail, and operation support are deliberately independent.
- * LinkedIn is the only registered channel today, but callers resolve capabilities
- * through this contract instead of branching on `channel === "linkedin"`. Adding a
- * channel later means registering a real adapter profile, not adding placeholder UI.
+ * Callers resolve capabilities through this contract instead of branching on a
+ * channel name. A channel is registered only when a real adapter exists.
  */
-export declare const SOCIAL_CHANNELS: readonly ["linkedin"];
+export declare const SOCIAL_CHANNELS: readonly ["linkedin", "x"];
 export type SocialChannel = (typeof SOCIAL_CHANNELS)[number];
-export declare const SOCIAL_PROVIDER_RAILS: readonly ["unipile"];
+export declare const SOCIAL_PROVIDER_RAILS: readonly ["unipile", "composio"];
 export type SocialProviderRail = (typeof SOCIAL_PROVIDER_RAILS)[number];
 export declare const SOCIAL_OPERATIONS: readonly ["list_owned_posts", "read_post_metrics", "list_comments", "reply_to_comment"];
 export type SocialOperation = (typeof SOCIAL_OPERATIONS)[number];
@@ -24,7 +23,7 @@ export type SocialOperationCapability = {
     limitation: string | null;
 };
 export type SocialMetricCapability = {
-    status: "available" | "unavailable";
+    status: SocialCapabilityStatus;
     provider_field: string | null;
     reason: string | null;
 };
@@ -41,3 +40,5 @@ export type SocialCapabilityProfile = {
 };
 export declare function listSocialCapabilityProfiles(): readonly SocialCapabilityProfile[];
 export declare function getSocialCapabilityProfile(channel: string, providerRail: string): SocialCapabilityProfile | null;
+/** Resolve the first configured rail that can perform an operation for a channel. */
+export declare function getSocialCapabilityProfileForOperation(channel: string, operation: SocialOperation): SocialCapabilityProfile | null;