@oxygen-agent/cli 1.1014.1696 → 1.1014.1870

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (112) hide show
  1. package/README.md +1 -1
  2. package/dist/admin-primary-providers-render.js +7 -2
  3. package/dist/command-families/program.js +4 -0
  4. package/dist/command-families/tables/register-relations.js +3 -2
  5. package/dist/command-manifest.js +14 -2
  6. package/dist/command-support.js +1 -1
  7. package/dist/commands/admin.js +82 -1
  8. package/dist/commands/billing.js +1 -1
  9. package/dist/commands/columns.js +2 -1
  10. package/dist/commands/copilot.js +29 -7
  11. package/dist/commands/domains.js +7 -0
  12. package/dist/commands/email-assets.d.ts +3 -0
  13. package/dist/commands/email-assets.js +78 -0
  14. package/dist/commands/email-templates.d.ts +3 -0
  15. package/dist/commands/email-templates.js +101 -0
  16. package/dist/commands/enrich-column.js +2 -1
  17. package/dist/commands/managed-inboxes.js +26 -1
  18. package/dist/commands/sequences.js +47 -12
  19. package/dist/commands/subscriptions.d.ts +2 -4
  20. package/dist/commands/subscriptions.js +297 -51
  21. package/dist/commands/table-runs.js +2 -1
  22. package/dist/sequence-start-at.d.ts +7 -0
  23. package/dist/sequence-start-at.js +21 -0
  24. package/dist/sequences-brand-kit-command.d.ts +28 -0
  25. package/dist/sequences-brand-kit-command.js +83 -0
  26. package/dist/sequences-content-commands.d.ts +28 -0
  27. package/dist/sequences-content-commands.js +176 -0
  28. package/dist/sequences-newsletter-commands.d.ts +6 -0
  29. package/dist/sequences-newsletter-commands.js +108 -0
  30. package/dist/sequences-test-send-command.d.ts +3 -0
  31. package/dist/sequences-test-send-command.js +47 -0
  32. package/node_modules/@oxygen/formula/dist/evaluate.js +2 -4
  33. package/node_modules/@oxygen/formula/dist/expression.d.ts +7 -5
  34. package/node_modules/@oxygen/formula/dist/expression.js +26 -4
  35. package/node_modules/@oxygen/formula/dist/formula-functions.d.ts +6 -0
  36. package/node_modules/@oxygen/formula/dist/formula-functions.js +55 -0
  37. package/node_modules/@oxygen/shared/dist/billing.d.ts +2 -2
  38. package/node_modules/@oxygen/shared/dist/billing.js +5 -7
  39. package/node_modules/@oxygen/shared/dist/bulk-email-pacing.d.ts +105 -0
  40. package/node_modules/@oxygen/shared/dist/bulk-email-pacing.js +125 -0
  41. package/node_modules/@oxygen/shared/dist/capability-discovery.d.ts +29 -0
  42. package/node_modules/@oxygen/shared/dist/capability-discovery.js +174 -10
  43. package/node_modules/@oxygen/shared/dist/contracts/clay-migration.d.ts +1 -0
  44. package/node_modules/@oxygen/shared/dist/contracts/clay-migration.js +28 -2
  45. package/node_modules/@oxygen/shared/dist/contracts/copilot-attachment-read.d.ts +24 -0
  46. package/node_modules/@oxygen/shared/dist/contracts/copilot-attachment-read.js +7 -0
  47. package/node_modules/@oxygen/shared/dist/contracts/teammates.js +6 -1
  48. package/node_modules/@oxygen/shared/dist/diagnostic-spool.js +90 -14
  49. package/node_modules/@oxygen/shared/dist/email-brand-kit.d.ts +108 -0
  50. package/node_modules/@oxygen/shared/dist/email-brand-kit.js +214 -0
  51. package/node_modules/@oxygen/shared/dist/email-delivery.d.ts +10 -0
  52. package/node_modules/@oxygen/shared/dist/email-delivery.js +14 -0
  53. package/node_modules/@oxygen/shared/dist/email-documents.d.ts +61 -0
  54. package/node_modules/@oxygen/shared/dist/email-documents.js +143 -0
  55. package/node_modules/@oxygen/shared/dist/email-dsn.js +52 -10
  56. package/node_modules/@oxygen/shared/dist/email-html-sanitize.d.ts +23 -0
  57. package/node_modules/@oxygen/shared/dist/email-html-sanitize.js +96 -0
  58. package/node_modules/@oxygen/shared/dist/email-subscriptions.d.ts +63 -1
  59. package/node_modules/@oxygen/shared/dist/email-subscriptions.js +149 -1
  60. package/node_modules/@oxygen/shared/dist/email-unsubscribe-token.d.ts +41 -2
  61. package/node_modules/@oxygen/shared/dist/email-unsubscribe-token.js +50 -1
  62. package/node_modules/@oxygen/shared/dist/external-write-policy.js +5 -1
  63. package/node_modules/@oxygen/shared/dist/group-commit-queue.d.ts +34 -0
  64. package/node_modules/@oxygen/shared/dist/group-commit-queue.js +103 -0
  65. package/node_modules/@oxygen/shared/dist/listed-website-platforms.d.ts +2 -0
  66. package/node_modules/@oxygen/shared/dist/listed-website-platforms.js +26 -0
  67. package/node_modules/@oxygen/shared/dist/newsletter-analytics.d.ts +90 -0
  68. package/node_modules/@oxygen/shared/dist/newsletter-analytics.js +28 -0
  69. package/node_modules/@oxygen/shared/dist/newsletter-test-send.d.ts +20 -0
  70. package/node_modules/@oxygen/shared/dist/newsletter-test-send.js +46 -0
  71. package/node_modules/@oxygen/shared/dist/object-storage.d.ts +11 -0
  72. package/node_modules/@oxygen/shared/dist/object-storage.js +12 -0
  73. package/node_modules/@oxygen/shared/dist/plan-band.d.ts +9 -0
  74. package/node_modules/@oxygen/shared/dist/plan-band.js +17 -0
  75. package/node_modules/@oxygen/shared/dist/plan-capabilities.d.ts +4 -2
  76. package/node_modules/@oxygen/shared/dist/plan-capabilities.js +12 -1
  77. package/node_modules/@oxygen/shared/dist/plan-limits-view.d.ts +2 -0
  78. package/node_modules/@oxygen/shared/dist/plan-limits-view.js +3 -0
  79. package/node_modules/@oxygen/shared/dist/pricing-snapshot.generated.d.ts +5 -0
  80. package/node_modules/@oxygen/shared/dist/pricing-snapshot.generated.js +5 -0
  81. package/node_modules/@oxygen/shared/dist/product-analytics-events.d.ts +29 -0
  82. package/node_modules/@oxygen/shared/dist/product-analytics-events.js +29 -0
  83. package/node_modules/@oxygen/shared/dist/provider-balance-signal.js +7 -0
  84. package/node_modules/@oxygen/shared/dist/sending-domain-faults.d.ts +21 -0
  85. package/node_modules/@oxygen/shared/dist/sending-domain-faults.js +53 -0
  86. package/node_modules/@oxygen/shared/dist/sending-domain-rollout.d.ts +24 -1
  87. package/node_modules/@oxygen/shared/dist/sending-domain-rollout.js +51 -4
  88. package/node_modules/@oxygen/shared/dist/sequence-failures.d.ts +10 -1
  89. package/node_modules/@oxygen/shared/dist/sequence-failures.js +68 -6
  90. package/node_modules/@oxygen/shared/dist/sequence-lifecycle.d.ts +34 -3
  91. package/node_modules/@oxygen/shared/dist/sequence-lifecycle.js +57 -4
  92. package/node_modules/@oxygen/shared/dist/sequence-template.d.ts +17 -0
  93. package/node_modules/@oxygen/shared/dist/sequence-template.js +0 -0
  94. package/node_modules/@oxygen/shared/dist/sequences.d.ts +41 -0
  95. package/node_modules/@oxygen/shared/dist/sequences.js +86 -4
  96. package/node_modules/@oxygen/shared/dist/ses-identity-policy.d.ts +19 -0
  97. package/node_modules/@oxygen/shared/dist/ses-identity-policy.js +54 -0
  98. package/node_modules/@oxygen/shared/dist/skill-play-routing.d.ts +22 -0
  99. package/node_modules/@oxygen/shared/dist/skill-play-routing.js +75 -0
  100. package/node_modules/@oxygen/shared/dist/skill-plays.generated.d.ts +5 -0
  101. package/node_modules/@oxygen/shared/dist/skill-plays.generated.js +269 -0
  102. package/node_modules/@oxygen/shared/dist/spend-safety.d.ts +7 -0
  103. package/node_modules/@oxygen/shared/dist/spend-safety.js +7 -0
  104. package/node_modules/@oxygen/shared/dist/table-limits.d.ts +6 -4
  105. package/node_modules/@oxygen/shared/dist/table-limits.js +6 -4
  106. package/node_modules/@oxygen/shared/dist/teammates.js +2 -1
  107. package/node_modules/@oxygen/shared/dist/user-capability-routing.js +15 -1
  108. package/node_modules/@oxygen/shared/dist/version.generated.d.ts +1 -1
  109. package/node_modules/@oxygen/shared/dist/version.generated.js +1 -1
  110. package/node_modules/@oxygen/shared/dist/workspace-event-catalog.js +2 -2
  111. package/node_modules/@oxygen/shared/package.json +5 -0
  112. package/package.json +2 -2
@@ -385,6 +385,14 @@ export type SequenceEmailSendStep = {
385
385
  body_template: string;
386
386
  /** Optional HTML body (B-W2): renders the send as multipart/alternative. Supports {{column}}. */
387
387
  body_html_template?: string;
388
+ /**
389
+ * A designed body stored as an email document (sending-domain Sequences):
390
+ * its revision supplies the HTML and text parts, rendered per recipient at
391
+ * delivery with HTML-escaped merge values. Without `revision` the step follows
392
+ * the document's current revision until the Sequence goes live, which pins it.
393
+ * Not combined with body_html_template; body_template may then stay empty.
394
+ */
395
+ body_document?: SequenceEmailBodyDocument;
388
396
  /** Static Cc / Bcc recipients (fixed addresses, not templated). */
389
397
  cc?: string[];
390
398
  bcc?: string[];
@@ -748,6 +756,39 @@ export type SequenceStep = SequenceLinkedInVisitProfileStep | SequenceLinkedInIn
748
756
  export type SequenceDefinition = {
749
757
  steps: SequenceStep[];
750
758
  };
759
+ /** `body_document` on an email_send step: an email document id and, once pinned, its revision. */
760
+ export type SequenceEmailBodyDocument = {
761
+ id: string;
762
+ revision?: number;
763
+ };
764
+ /** The email_send steps whose body is an email document, in flat step order. */
765
+ export declare function sequenceBodyDocumentSteps(definition: {
766
+ steps?: readonly unknown[];
767
+ } | null | undefined): Array<{
768
+ index: number;
769
+ stepId: string;
770
+ ref: SequenceEmailBodyDocument;
771
+ }>;
772
+ /**
773
+ * Where a step's content lives, for `sequences content get|set` on every surface:
774
+ * the email_send step by id, its document reference, and its plain bodies.
775
+ * Throws a fixed-copy OxygenError naming the step when it is not an email_send.
776
+ */
777
+ export declare function sequenceContentStep(definition: {
778
+ steps?: readonly unknown[];
779
+ } | null | undefined, stepId: string): {
780
+ index: number;
781
+ step: Record<string, unknown>;
782
+ bodyDocument: SequenceEmailBodyDocument | null;
783
+ };
784
+ /**
785
+ * The definition with one email_send step bodied by `documentId` (following its
786
+ * current revision), or null when the step already references exactly that.
787
+ * A document replaces the step's body_html_template.
788
+ */
789
+ export declare function withSequenceStepBodyDocument<T extends {
790
+ steps: readonly unknown[];
791
+ }>(definition: T, stepId: string, documentId: string): T | null;
751
792
  /** Which channel a step executes on, or null for channel-agnostic control steps. */
752
793
  export declare function sequenceStepChannel(step: SequenceStep): SequenceChannel | null;
753
794
  /** Distinct channels a sequence touches (drives the sequence's channels[] tag). */
@@ -472,6 +472,77 @@ export function sequenceLeadContacts(input) {
472
472
  phone: callPhoneFromRow(input.rowValues, phoneKey) !== null || whatsAppAttendeeIdFromRow(input.rowValues, phoneKey) !== null,
473
473
  };
474
474
  }
475
+ /** The email_send steps whose body is an email document, in flat step order. */
476
+ export function sequenceBodyDocumentSteps(definition) {
477
+ const out = [];
478
+ (definition?.steps ?? []).forEach((step, index) => {
479
+ if (!isRecord(step) || step.kind !== "email_send" || !isRecord(step.body_document))
480
+ return;
481
+ const id = step.body_document.id;
482
+ const revision = step.body_document.revision;
483
+ if (typeof id !== "string")
484
+ return;
485
+ out.push({ index, stepId: typeof step.id === "string" ? step.id : "", ref: { id, ...(typeof revision === "number" ? { revision } : {}) } });
486
+ });
487
+ return out;
488
+ }
489
+ /**
490
+ * Where a step's content lives, for `sequences content get|set` on every surface:
491
+ * the email_send step by id, its document reference, and its plain bodies.
492
+ * Throws a fixed-copy OxygenError naming the step when it is not an email_send.
493
+ */
494
+ export function sequenceContentStep(definition, stepId) {
495
+ const steps = definition?.steps ?? [];
496
+ const index = steps.findIndex((step) => isRecord(step) && step.id === stepId);
497
+ const step = index === -1 ? null : steps[index];
498
+ if (!isRecord(step)) {
499
+ throw new OxygenError("sequence_step_not_found", "No step with that id in this sequence.", {
500
+ details: { step_id: stepId, step_ids: steps.filter(isRecord).map((entry) => entry.id) }, exitCode: 2,
501
+ });
502
+ }
503
+ if (step.kind !== "email_send") {
504
+ throw new OxygenError("sequence_step_not_email", "Content applies to an email_send step.", { details: { step_id: stepId, kind: step.kind }, exitCode: 2 });
505
+ }
506
+ const ref = sequenceBodyDocumentSteps({ steps: [step] })[0]?.ref ?? null;
507
+ return { index, step, bodyDocument: ref };
508
+ }
509
+ /**
510
+ * The definition with one email_send step bodied by `documentId` (following its
511
+ * current revision), or null when the step already references exactly that.
512
+ * A document replaces the step's body_html_template.
513
+ */
514
+ export function withSequenceStepBodyDocument(definition, stepId, documentId) {
515
+ const { index, step, bodyDocument } = sequenceContentStep(definition, stepId);
516
+ if (bodyDocument && bodyDocument.id === documentId && bodyDocument.revision === undefined && step.body_html_template === undefined)
517
+ return null;
518
+ const { body_html_template: _html, ...rest } = step;
519
+ const steps = [...definition.steps];
520
+ steps[index] = { ...rest, body_document: { id: documentId } };
521
+ return { ...definition, steps };
522
+ }
523
+ const BODY_DOCUMENT_UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
524
+ function normalizeBodyDocument(raw, path, issues) {
525
+ if (raw === undefined || raw === null)
526
+ return undefined;
527
+ if (!isRecord(raw)) {
528
+ issues.push({ path, message: "must be an object { id, revision? }." });
529
+ return undefined;
530
+ }
531
+ const unknownKeys = Object.keys(raw).filter((key) => key !== "id" && key !== "revision");
532
+ if (unknownKeys.length > 0)
533
+ issues.push({ path, message: `unknown field(s): ${unknownKeys.join(", ")}; only id and revision.` });
534
+ if (typeof raw.id !== "string" || !BODY_DOCUMENT_UUID_RE.test(raw.id)) {
535
+ issues.push({ path: `${path}.id`, message: "must be an email document id." });
536
+ return undefined;
537
+ }
538
+ if (raw.revision === undefined || raw.revision === null)
539
+ return { id: raw.id.toLowerCase() };
540
+ if (typeof raw.revision !== "number" || !Number.isInteger(raw.revision) || raw.revision < 1) {
541
+ issues.push({ path: `${path}.revision`, message: "must be a positive integer." });
542
+ return undefined;
543
+ }
544
+ return { id: raw.id.toLowerCase(), revision: raw.revision };
545
+ }
475
546
  const MAX_SEQUENCE_STEPS = 50;
476
547
  const MAX_TEMPLATE_LENGTH = 8_000;
477
548
  // The Premium ceiling, and only an authoring hint: the limit that actually
@@ -670,7 +741,9 @@ export function sequenceStepsMissingCopy(steps) {
670
741
  if (sequenceInheritedEmailSubject(steps, index) === null) {
671
742
  check(step, "subject_template", step.subject_template);
672
743
  }
673
- check(step, "body_template", step.body_template);
744
+ // A document-bodied step's copy is the document.
745
+ if (!step.body_document)
746
+ check(step, "body_template", step.body_template);
674
747
  break;
675
748
  case "email_reply":
676
749
  check(step, "body_template", step.body_template);
@@ -1020,12 +1093,20 @@ raw, index, options, issues) {
1020
1093
  // instead of relying on an empty string being read the right way downstream.
1021
1094
  const subject = optionalTemplate(raw.subject_template, `${path}.subject_template`, MAX_TEMPLATE_LENGTH, issues);
1022
1095
  const threaded = !(subject ?? "").trim();
1023
- const body = requiredTemplate(raw.body_template, `${path}.body_template`, issues, options.draft === true);
1096
+ const bodyDocument = normalizeBodyDocument(raw.body_document, `${path}.body_document`, issues);
1097
+ // A document carries its own plain-text part, so body_template may stay
1098
+ // empty (it remains the text fallback when set).
1099
+ const body = requiredTemplate(raw.body_template ?? (bodyDocument ? "" : undefined), `${path}.body_template`, issues, options.draft === true || bodyDocument !== undefined);
1024
1100
  const bodyHtml = optionalTemplate(raw.body_html_template, `${path}.body_html_template`, MAX_TEMPLATE_LENGTH, issues);
1101
+ if (bodyDocument && bodyHtml !== undefined && bodyHtml.trim()) {
1102
+ issues.push({ path: `${path}.body_html_template`, message: "set body_document or body_html_template, not both." });
1103
+ }
1025
1104
  // A threaded step has no subject to override, so its variants may only vary
1026
1105
  // the body — a subject-only variant then fails normalizeVariants' own
1027
1106
  // "must override at least one of" check rather than silently doing nothing.
1028
- const variants = normalizeVariants(raw.variants, `${path}.variants`, threaded ? ["body_template", "body_html_template"] : ["subject_template", "body_template", "body_html_template"], issues, options.draft === true);
1107
+ // A document-bodied step's HTML is the document, so variants vary subject/text only.
1108
+ const variantBodyFields = bodyDocument ? ["body_template"] : ["body_template", "body_html_template"];
1109
+ const variants = normalizeVariants(raw.variants, `${path}.variants`, threaded ? variantBodyFields : ["subject_template", ...variantBodyFields], issues, options.draft === true);
1029
1110
  const autoOptimize = normalizeAutoOptimize(raw.auto_optimize, `${path}.auto_optimize`, variants, options, issues);
1030
1111
  const cc = optionalEmailList(raw.cc, `${path}.cc`, issues);
1031
1112
  const bcc = optionalEmailList(raw.bcc, `${path}.bcc`, issues);
@@ -1047,6 +1128,7 @@ raw, index, options, issues) {
1047
1128
  ...(threaded ? {} : { subject_template: subject }),
1048
1129
  body_template: body ?? "",
1049
1130
  ...(bodyHtml !== undefined ? { body_html_template: bodyHtml } : {}),
1131
+ ...(bodyDocument ? { body_document: bodyDocument } : {}),
1050
1132
  ...(cc ? { cc } : {}),
1051
1133
  ...(bcc ? { bcc } : {}),
1052
1134
  ...(variants ? { variants: variants } : {}),
@@ -1289,7 +1371,7 @@ const STEP_KIND_FIELDS = {
1289
1371
  like_post: ["reaction", "post_recency_days", "on_no_post"],
1290
1372
  comment_post: ["text_template", "ai_prompt", "post_recency_days", "on_no_post"],
1291
1373
  withdraw_invite: [],
1292
- email_send: ["subject_template", "body_template", "body_html_template", "cc", "bcc", "send_window", "variants", "auto_optimize"],
1374
+ email_send: ["subject_template", "body_template", "body_html_template", "body_document", "cc", "bcc", "send_window", "variants", "auto_optimize"],
1293
1375
  email_reply: ["body_template", "body_html_template", "cc", "bcc", "send_window", "variants", "auto_optimize"],
1294
1376
  email_enroll: ["subsequence_id"],
1295
1377
  email_move: ["subsequence_id"],
@@ -0,0 +1,19 @@
1
+ /** OXYGEN's own sending and product domains: never claimable by a workspace. */
2
+ export declare const RESERVED_SES_IDENTITY_SUFFIXES: readonly ["oxygen-agent.com"];
3
+ /** An unverified claim lapses after this long, so a typo cannot hold a domain forever. */
4
+ export declare const SES_IDENTITY_CLAIM_TTL_MS: number;
5
+ /** Lower-cased hostname with at least two labels, or null when it is not one. */
6
+ export declare function normalizeSesIdentity(value: unknown): string | null;
7
+ /** True when `identity` is `parent` or one of its subdomains. */
8
+ export declare function isSesIdentityWithin(identity: string, parent: string): boolean;
9
+ /** True when either identity covers the other: the same name, or one is a subdomain of the other. */
10
+ export declare function sesIdentitiesOverlap(a: string, b: string): boolean;
11
+ export declare function isReservedSesIdentity(identity: string): boolean;
12
+ /**
13
+ * The identity's parents down to two labels, nearest first: `a.news.example.com`
14
+ * gives `news.example.com`, `example.com`. With the identity itself these are
15
+ * the registry rows a claim must not collide with on the way up.
16
+ */
17
+ export declare function sesIdentityParents(identity: string): string[];
18
+ /** The SES tenant name for a workspace: `oxy_` plus its UUID without dashes (36 of SES's 64 characters). */
19
+ export declare function sesTenantName(organizationId: string): string;
@@ -0,0 +1,54 @@
1
+ // Who may own an SES identity on OXYGEN's one shared SES account. SES knows an
2
+ // identity once per account and lets a verified domain send for its subdomains,
3
+ // so ownership is decided here and in the control-db registry before any SES
4
+ // call: one workspace per identity, never one under or over another workspace's
5
+ // identity, and never OXYGEN's own domains.
6
+ /** OXYGEN's own sending and product domains: never claimable by a workspace. */
7
+ export const RESERVED_SES_IDENTITY_SUFFIXES = ["oxygen-agent.com"];
8
+ /** An unverified claim lapses after this long, so a typo cannot hold a domain forever. */
9
+ export const SES_IDENTITY_CLAIM_TTL_MS = 72 * 60 * 60 * 1000;
10
+ const LABEL_RE = /^(?!-)[a-z0-9-]{1,63}(?<!-)$/;
11
+ const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
12
+ /** Lower-cased hostname with at least two labels, or null when it is not one. */
13
+ export function normalizeSesIdentity(value) {
14
+ if (typeof value !== "string")
15
+ return null;
16
+ const identity = value.trim().toLowerCase().replace(/\.$/, "");
17
+ if (identity.length === 0 || identity.length > 253)
18
+ return null;
19
+ const labels = identity.split(".");
20
+ if (labels.length < 2 || !labels.every((label) => LABEL_RE.test(label)))
21
+ return null;
22
+ if (/^[0-9]+$/.test(labels[labels.length - 1]))
23
+ return null;
24
+ return identity;
25
+ }
26
+ /** True when `identity` is `parent` or one of its subdomains. */
27
+ export function isSesIdentityWithin(identity, parent) {
28
+ return identity === parent || identity.endsWith(`.${parent}`);
29
+ }
30
+ /** True when either identity covers the other: the same name, or one is a subdomain of the other. */
31
+ export function sesIdentitiesOverlap(a, b) {
32
+ return isSesIdentityWithin(a, b) || isSesIdentityWithin(b, a);
33
+ }
34
+ export function isReservedSesIdentity(identity) {
35
+ return RESERVED_SES_IDENTITY_SUFFIXES.some((suffix) => sesIdentitiesOverlap(identity, suffix));
36
+ }
37
+ /**
38
+ * The identity's parents down to two labels, nearest first: `a.news.example.com`
39
+ * gives `news.example.com`, `example.com`. With the identity itself these are
40
+ * the registry rows a claim must not collide with on the way up.
41
+ */
42
+ export function sesIdentityParents(identity) {
43
+ const labels = identity.split(".");
44
+ const parents = [];
45
+ for (let index = 1; index <= labels.length - 2; index += 1)
46
+ parents.push(labels.slice(index).join("."));
47
+ return parents;
48
+ }
49
+ /** The SES tenant name for a workspace: `oxy_` plus its UUID without dashes (36 of SES's 64 characters). */
50
+ export function sesTenantName(organizationId) {
51
+ if (!UUID_RE.test(organizationId))
52
+ throw new Error("sesTenantName needs an organization UUID");
53
+ return `oxy_${organizationId.toLowerCase().replaceAll("-", "")}`;
54
+ }
@@ -0,0 +1,22 @@
1
+ /**
2
+ * Which feature-skill play a GTM ask matches, from each play's own title and
3
+ * trigger phrases (generated from the play catalog, never a second list).
4
+ *
5
+ * A capability route names the skill that owns an ask; without the play file the
6
+ * agent planned from general knowledge and skipped OXYGEN's defaults (Oxygent
7
+ * suite, 2026-10-21: oxygen_skills_get called 0 times in 8 runs). The match is
8
+ * deliberately strict: the ask must hold three quarters (and at least three) of
9
+ * one trigger phrase's content words, an adjacent pair of them included, and a
10
+ * tie between plays names none.
11
+ */
12
+ export type SkillPlayMatch = {
13
+ skill: string;
14
+ slug: string;
15
+ file: string;
16
+ };
17
+ export declare const SKILL_PLAY_TRIGGERS: readonly {
18
+ skill: string;
19
+ slug: string;
20
+ phrases: readonly string[];
21
+ }[];
22
+ export declare function matchSkillPlay(query: string): SkillPlayMatch | null;
@@ -0,0 +1,75 @@
1
+ import { SKILL_PLAY_TRIGGERS_GENERATED } from "./skill-plays.generated.js";
2
+ export const SKILL_PLAY_TRIGGERS = SKILL_PLAY_TRIGGERS_GENERATED;
3
+ const STOPWORDS = new Set([
4
+ "a", "about", "across", "all", "an", "and", "any", "are", "as", "at", "be", "before", "by", "can", "d", "do", "does",
5
+ "every", "for", "from", "get", "give", "going", "how", "i", "i'm", "in", "into", "is", "it", "it's", "its", "just",
6
+ "let", "ll", "me", "my", "of", "on", "one", "or", "our", "s", "should", "so", "some", "that", "the", "their", "them",
7
+ "then", "these", "they", "this", "those", "to", "up", "us", "want", "we", "what", "when", "which", "who", "why",
8
+ "will", "with", "would", "you", "your",
9
+ ]);
10
+ function stem(word) {
11
+ if (word.length > 4 && word.endsWith("ies"))
12
+ return `${word.slice(0, -3)}y`;
13
+ if (word.length > 3 && word.endsWith("s") && !word.endsWith("ss"))
14
+ return word.slice(0, -1);
15
+ return word;
16
+ }
17
+ function contentWords(text) {
18
+ return text
19
+ .toLowerCase()
20
+ .replace(/[’]/g, "'")
21
+ .split(/[^a-z0-9/']+/)
22
+ .map((word) => word.replace(/^[/']+|[/']+$/g, ""))
23
+ .filter((word) => word.length > 0 && !STOPWORDS.has(word))
24
+ .map(stem);
25
+ }
26
+ function wordPairs(words) {
27
+ const pairs = new Set();
28
+ for (let i = 1; i < words.length; i += 1)
29
+ pairs.add(`${words[i - 1]} ${words[i]}`);
30
+ return pairs;
31
+ }
32
+ const PLAY_PHRASES = SKILL_PLAY_TRIGGERS.map((play) => ({
33
+ play,
34
+ phrases: play.phrases.map((phrase) => {
35
+ const words = contentWords(phrase);
36
+ return { words: new Set(words), pairs: wordPairs(words) };
37
+ }),
38
+ }));
39
+ /** An ask must hold at least this many of one phrase's words... */
40
+ const MIN_SHARED_WORDS = 3;
41
+ /** ...and this share of them, one adjacent pair included. */
42
+ const MIN_PHRASE_COVERAGE = 0.75;
43
+ export function matchSkillPlay(query) {
44
+ const askedWords = contentWords(query);
45
+ const asked = new Set(askedWords);
46
+ const askedPairs = wordPairs(askedWords);
47
+ if (askedPairs.size === 0)
48
+ return null;
49
+ let best = null;
50
+ let tied = false;
51
+ for (const { play, phrases } of PLAY_PHRASES) {
52
+ let score = 0;
53
+ for (const { words, pairs } of phrases) {
54
+ let shared = 0;
55
+ for (const word of words)
56
+ if (asked.has(word))
57
+ shared += 1;
58
+ if (shared < MIN_SHARED_WORDS || shared / words.size < MIN_PHRASE_COVERAGE)
59
+ continue;
60
+ if (![...pairs].some((pair) => askedPairs.has(pair)))
61
+ continue;
62
+ score = Math.max(score, shared / words.size + shared / 100);
63
+ }
64
+ if (score === 0)
65
+ continue;
66
+ if (!best || score > best.score) {
67
+ best = { skill: play.skill, slug: play.slug, score };
68
+ tied = false;
69
+ }
70
+ else if (score === best.score) {
71
+ tied = true;
72
+ }
73
+ }
74
+ return best && !tied ? { skill: best.skill, slug: best.slug, file: `plays/${best.slug}.md` } : null;
75
+ }
@@ -0,0 +1,5 @@
1
+ export declare const SKILL_PLAY_TRIGGERS_GENERATED: readonly {
2
+ skill: string;
3
+ slug: string;
4
+ phrases: readonly string[];
5
+ }[];
@@ -0,0 +1,269 @@
1
+ // GENERATED by apps/web/scripts/generate-copilot-playbooks.ts from the play
2
+ // catalog (`skill`, `title`, `trigger_phrases` in apps/web/src/lib/agent-skill-plays.ts).
3
+ // Do not edit by hand — run `npm run skills:metadata -w @oxygen/web`.
4
+ export const SKILL_PLAY_TRIGGERS_GENERATED = [
5
+ {
6
+ skill: "oxygen-clay-migration",
7
+ slug: "migrate-from-clay",
8
+ phrases: [
9
+ "Migrate from Clay",
10
+ "Move my whole Clay workspace into Oxygen",
11
+ "Clay is too expensive — what's the switch cost?",
12
+ "Rebuild my Clay waterfalls here",
13
+ "Import a Clay CSV and re-enrich it",
14
+ "How do I replace Claygent with Oxygen?",
15
+ "Bring my Clay company list over and score it",
16
+ ],
17
+ },
18
+ {
19
+ skill: "oxygen-crm",
20
+ slug: "website-visitor-outreach",
21
+ phrases: [
22
+ "Turn de-anonymized website visitors into warm pipeline",
23
+ "People visit our website but never convert",
24
+ "Who is on my site right now — and can we contact them?",
25
+ "Which companies visited our website this week?",
26
+ "Turn website traffic into leads",
27
+ "Set up visitor de-anonymization",
28
+ "Connect RB2B to OXYGEN",
29
+ ],
30
+ },
31
+ {
32
+ skill: "oxygen-diagnostics",
33
+ slug: "day-30-review",
34
+ phrases: [
35
+ "Day 30: review, scale, or kill",
36
+ "What worked this month and what did it cost?",
37
+ "Review my GTM runs and decide what to scale",
38
+ "Monthly review of sequences and spend",
39
+ "Should I kill or scale this play?",
40
+ "Where did my credits go this month?",
41
+ ],
42
+ },
43
+ {
44
+ skill: "oxygen-email-infra",
45
+ slug: "email-infra-setup",
46
+ phrases: [
47
+ "Set up cold email infrastructure",
48
+ "Set up cold email infrastructure",
49
+ "I need sending domains and mailboxes for outbound",
50
+ "How do I send cold email without burning my domain?",
51
+ "Buy me some inboxes for a cold email campaign",
52
+ "Stand up a warmed mailbox pool for outreach",
53
+ "What do sending inboxes cost per month?",
54
+ ],
55
+ },
56
+ {
57
+ skill: "oxygen-knowledge",
58
+ slug: "client-workspace-launch",
59
+ phrases: [
60
+ "Stand up a new client workspace",
61
+ "Onboard a new client into Oxygen",
62
+ "Set up a workspace for a new client",
63
+ "How do I run Oxygen for multiple clients?",
64
+ "Stand up a client account from scratch",
65
+ "Repeatable client onboarding for my agency",
66
+ ],
67
+ },
68
+ {
69
+ skill: "oxygen-onboarding",
70
+ slug: "day-1-first-win",
71
+ phrases: [
72
+ "Day 1: from your offer to your warmest leads",
73
+ "I just signed up — what do I actually do with this?",
74
+ "Where do I start with Oxygen?",
75
+ "Who should I contact first?",
76
+ "Find my warmest leads",
77
+ "What should I do in my first session?",
78
+ ],
79
+ },
80
+ {
81
+ skill: "oxygen-publishing",
82
+ slug: "founder-posting-system",
83
+ phrases: [
84
+ "A founder posting system grounded in your knowledge base",
85
+ "I should be posting on LinkedIn but never do",
86
+ "Draft LinkedIn posts in my voice",
87
+ "Plan my LinkedIn content for the week",
88
+ "Set up a content calendar",
89
+ "I can't post consistently — schedule my posts for me",
90
+ "Turn my company knowledge into LinkedIn posts",
91
+ ],
92
+ },
93
+ {
94
+ skill: "oxygen-sequencer",
95
+ slug: "inbound-led-outbound",
96
+ phrases: [
97
+ "Inbound-led outbound: post engagers into a capped warm sequence",
98
+ "Turn the people who engage with my LinkedIn posts into pipeline",
99
+ "Who is engaging with my competitors' or my niche creators' posts?",
100
+ "Reach the people engaging with LinkedIn posts about my topic",
101
+ "Turn my LinkedIn connections and followers into pipeline",
102
+ "Turn my LinkedIn profile viewers into leads",
103
+ "I have no lead list. Where do I start on LinkedIn?",
104
+ ],
105
+ },
106
+ {
107
+ skill: "oxygen-sequencer",
108
+ slug: "multichannel-top-tier",
109
+ phrases: [
110
+ "Email + LinkedIn for top-tier leads",
111
+ "Combine email and LinkedIn for our best accounts",
112
+ "Run a multichannel sequence for top-tier leads",
113
+ "Email plus a LinkedIn invite for high-fit accounts",
114
+ "LinkedIn first for warm leads, email as the fallback",
115
+ ],
116
+ },
117
+ {
118
+ skill: "oxygen-sequencer",
119
+ slug: "outbound-pilot-50",
120
+ phrases: [
121
+ "Launch a 50-lead outbound pilot",
122
+ "I need outbound running this week",
123
+ "Build me a cold outreach pilot",
124
+ "Find 50 leads and draft first emails for me to review",
125
+ "I have no pipeline — start outbound",
126
+ ],
127
+ },
128
+ {
129
+ skill: "oxygen-sequencer",
130
+ slug: "signal-outbound",
131
+ phrases: [
132
+ "Signal-based email outbound",
133
+ "Email companies that are hiring for this role",
134
+ "Reach people who just showed buying intent",
135
+ "Turn hiring signals into cold email",
136
+ "Email our website visitors and signups who fit",
137
+ ],
138
+ },
139
+ {
140
+ skill: "oxygen-sequencer",
141
+ slug: "whole-tam-email",
142
+ phrases: [
143
+ "Whole-market cold email",
144
+ "Run cold email across our whole market",
145
+ "Set up evergreen cold email at full capacity",
146
+ "A/B test our cold email CTAs and subject lines",
147
+ "Re-contact the people who never replied",
148
+ "The pilot worked — how do I scale cold email?",
149
+ "Build a repeatable cold email system",
150
+ ],
151
+ },
152
+ {
153
+ skill: "oxygen-signals",
154
+ slug: "daily-warm-lead-queue",
155
+ phrases: [
156
+ "A daily ranked queue of your warmest leads",
157
+ "Who should I reach out to today?",
158
+ "Give me one ranked list of my warmest leads every morning",
159
+ "Turn all my intent signals into a daily to-do list",
160
+ "Make Oxygen do something while I'm not looking",
161
+ "What should I set up in my first week?",
162
+ "Set up a weekly CRM cleanup routine",
163
+ ],
164
+ },
165
+ {
166
+ skill: "oxygen-signals",
167
+ slug: "existing-network",
168
+ phrases: [
169
+ "Hand-written first messages to buyers already in your network",
170
+ "Work my network",
171
+ "Reactivate my connections",
172
+ "Message the buyers I'm already connected to",
173
+ "Write personal messages to my LinkedIn connections",
174
+ ],
175
+ },
176
+ {
177
+ skill: "oxygen-signals",
178
+ slug: "new-connections",
179
+ phrases: [
180
+ "Message the buyers among your new connections",
181
+ "Follow up with my new LinkedIn connections",
182
+ "Message the people who just connected with me",
183
+ "Which of my new connections are buyers?",
184
+ "Start conversations with my recent connections",
185
+ ],
186
+ },
187
+ {
188
+ skill: "oxygen-signals",
189
+ slug: "post-engagers",
190
+ phrases: [
191
+ "Start conversations with the buyers who engage with your posts",
192
+ "Reach the people who engage with my LinkedIn posts",
193
+ "Message the people who commented on my post",
194
+ "Who reacted to my post, and are they buyers?",
195
+ "Turn my post engagers into conversations",
196
+ ],
197
+ },
198
+ {
199
+ skill: "oxygen-signals",
200
+ slug: "profile-viewers-and-followers",
201
+ phrases: [
202
+ "Invite the buyers who view your profile or follow you",
203
+ "Reach out to the people who viewed my LinkedIn profile",
204
+ "Turn my LinkedIn followers into conversations",
205
+ "Invite my followers who aren't connected yet",
206
+ "Who viewed my profile, and should I contact them?",
207
+ ],
208
+ },
209
+ {
210
+ skill: "oxygen-sourcing",
211
+ slug: "icp-to-account-map",
212
+ phrases: [
213
+ "Turn your ICP into a scored account map",
214
+ "Turn my ICP into a list of target accounts",
215
+ "Find B2B SaaS accounts that match our ideal customer profile",
216
+ "Who should we actually be selling to?",
217
+ "Map my market and score the companies by fit",
218
+ "Pull the companies off this VC portfolio, partner directory or event page",
219
+ "I have a list of companies, which ones fit us best?",
220
+ ],
221
+ },
222
+ {
223
+ skill: "oxygen-sourcing",
224
+ slug: "local-business-maps",
225
+ phrases: [
226
+ "Local businesses from Google Maps",
227
+ "Find local businesses in my cities",
228
+ "Get a list of clinics or restaurants by city",
229
+ "Pull businesses from Google Maps",
230
+ "Our buyers are local businesses with a physical location",
231
+ ],
232
+ },
233
+ {
234
+ skill: "oxygen-sourcing",
235
+ slug: "lookalike-tam",
236
+ phrases: [
237
+ "Lookalike TAM",
238
+ "Find more companies like our best customers",
239
+ "Build a lookalike list from our customers",
240
+ "Who else looks like the customers we already have?",
241
+ "Use our customers as seeds to map our market",
242
+ ],
243
+ },
244
+ {
245
+ skill: "oxygen-tables",
246
+ slug: "speed-to-lead",
247
+ phrases: [
248
+ "Answer inbound leads in minutes",
249
+ "New signups sit for days before anyone reaches out",
250
+ "Route my inbound leads into the CRM automatically",
251
+ "Answer trial signups the same day they arrive",
252
+ "Set up speed-to-lead for my demo requests",
253
+ "Enrich and follow up on form fills without me watching",
254
+ ],
255
+ },
256
+ {
257
+ skill: "oxygen-unibox",
258
+ slug: "reply-to-meeting",
259
+ phrases: [
260
+ "Turn replies into booked meetings",
261
+ "I get replies but they never turn into meetings",
262
+ "Help me handle my inbound replies faster",
263
+ "Book more meetings from the replies I already have",
264
+ "Log booked calls in my CRM automatically",
265
+ "What do I do with 'circle back next quarter' replies?",
266
+ "Bring deferred leads back when they're ready",
267
+ ],
268
+ },
269
+ ];
@@ -158,6 +158,13 @@ export type CopilotApprovalFreeAllowance = {
158
158
  * largest session allowance stays below the attended turn backstop above.
159
159
  */
160
160
  export declare const COPILOT_APPROVAL_FREE_ALLOWANCE_BY_PLAN_BAND: Readonly<Record<PlanBand, CopilotApprovalFreeAllowance>>;
161
+ /**
162
+ * On every plan, an Oxygent call whose declared ceiling (`max_credits`, the
163
+ * maximum quote, never the estimate) is strictly BELOW this runs without an
164
+ * approval card (Philipp, 2026-10-21). It only adds to the per-call allowance
165
+ * above, never lowers one, and the per-session allowance still applies.
166
+ */
167
+ export declare const OXYGENT_APPROVAL_FREE_BELOW_CREDITS = 100;
161
168
  /** A plan size's approval-free Copilot allowance. */
162
169
  export declare function copilotApprovalFreeAllowanceForBand(band: PlanBand): CopilotApprovalFreeAllowance;
163
170
  export declare function resolveDefaultByokColumnRunMaxRows(tier: SpendSafetyPlanTier): number | null;
@@ -191,6 +191,13 @@ export const COPILOT_APPROVAL_FREE_ALLOWANCE_BY_PLAN_BAND = Object.freeze({
191
191
  "999": Object.freeze({ perCallCredits: 300, perSessionCredits: 1_500 }),
192
192
  "1999": Object.freeze({ perCallCredits: 500, perSessionCredits: 2_500 }),
193
193
  });
194
+ /**
195
+ * On every plan, an Oxygent call whose declared ceiling (`max_credits`, the
196
+ * maximum quote, never the estimate) is strictly BELOW this runs without an
197
+ * approval card (Philipp, 2026-10-21). It only adds to the per-call allowance
198
+ * above, never lowers one, and the per-session allowance still applies.
199
+ */
200
+ export const OXYGENT_APPROVAL_FREE_BELOW_CREDITS = 100;
194
201
  /** A plan size's approval-free Copilot allowance. */
195
202
  export function copilotApprovalFreeAllowanceForBand(band) {
196
203
  return COPILOT_APPROVAL_FREE_ALLOWANCE_BY_PLAN_BAND[band];