feat(llmo): register recurring DRS prompt-suggestion schedules at onboarding

Adds three onboarding triggers next to triggerBrandalfOnboardingJob that
register recurring DRS schedules (with an immediate first run) for the
prompt-suggestion pipelines, invoked from the V2 onboarding block after the
Brandalf trigger:

- triggerSemrushPromptJob        -> prompt_generation_semrush        (twice-monthly)
- triggerCitationAttemptJob      -> prompt_generation_agentic_traffic (twice-monthly)
- triggerSyntheticPersonasJob    -> prompt_generation_synthetic_personas (quarterly)

Each is guarded by drsClient.isConfigured() and uses a single
createSchedule({ ..., triggerImmediately: true }) call. Split error semantics:
the immediate first run is best-effort (self-heals on the next scheduled run),
but a createSchedule (schedule-registration) failure is logged at ERROR with
site_id + provider_id + status and surfaced to ops -- never silently swallowed,
since a swallowed failure means the site never gets a recurring schedule.
Onboarding still succeeds when a schedule registration fails.

Depends on a new additive createSchedule(...) method in
@adobe/spacecat-shared-drs-client (bumped to 1.14.0); must merge/release after
that shared PR.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: dzehnder

package.json

@@ -89,7 +89,7 @@
     "@adobe/spacecat-shared-cloudflare-client": "1.2.1",
     "@adobe/spacecat-shared-content-client": "1.8.24",
     "@adobe/spacecat-shared-data-access": "4.9.0",
-    "@adobe/spacecat-shared-drs-client": "1.13.0",
+    "@adobe/spacecat-shared-drs-client": "1.14.0",
     "@adobe/spacecat-shared-gpt-client": "1.6.23",
     "@adobe/spacecat-shared-http-utils": "1.34.0",
     "@adobe/spacecat-shared-ims-client": "1.12.7",

src/controllers/llmo/llmo-onboarding.js

@@ -175,6 +175,115 @@ export async function triggerBrandalfOnboardingJob({
   return drsJob;
 }
 
+// Cadence labels accepted by DRS `createSchedule` for the recurring
+// "prompt suggestion" pipelines. DRS derives the concrete cron expression
+// server-side from the label (frequency:'cron') — we never send raw cron, so a
+// misconfigured/leaked caller cannot schedule a fleet-wide Fargate storm.
+//   'twice-monthly' → 1st & 15th (honest label; not a true 14-day interval)
+//   'quarterly'     → 1st of Jan/Apr/Jul/Oct
+// See local/drs-prompt-suggestions-schedules-onboarding-plan.md ("Cadence expression").
+const DRS_CADENCE_TWICE_MONTHLY = 'twice-monthly';
+const DRS_CADENCE_QUARTERLY = 'quarterly';
+
+/**
+ * Registers a recurring DRS schedule for one prompt-suggestion provider, with an
+ * immediate first run. Shared body for the three onboarding triggers below.
+ *
+ * Split error semantics (see the V2 caller): the immediate first run is
+ * best-effort — if it produces nothing (e.g. brand/base-prompt data not present
+ * yet) the next scheduled run self-heals. A `createSchedule` (schedule
+ * REGISTRATION) failure is NOT best-effort: the site would never get a recurring
+ * schedule and nothing self-heals, so it propagates to the caller which logs it
+ * at ERROR. This helper therefore does not swallow the failure itself.
+ *
+ * @param {object} params
+ * @param {object} params.drsClient - Configured DRS client.
+ * @param {string} params.providerId - DRS provider id to schedule.
+ * @param {string} params.cadence - One of DRS_CADENCE_* labels.
+ * @param {string} params.siteId - SpaceCat site UUID.
+ * @param {string} params.orgId - SpaceCat organization UUID.
+ * @param {string} params.imsOrgId - IMS org id (isolation key; DRS re-derives server-side).
+ * @param {object} params.log - Logger.
+ * @param {Function} [params.say] - Optional Slack say callback.
+ * @returns {Promise<object|null>} The createSchedule result, or null when DRS is not configured.
+ */
+async function registerPromptSuggestionSchedule({
+  drsClient, providerId, cadence, siteId, orgId, imsOrgId, log, say = () => {},
+}) {
+  if (!drsClient.isConfigured()) {
+    log.debug(`DRS client not configured, skipping ${providerId} schedule for site ${siteId}`);
+    return null;
+  }
+
+  // Default enable_brand_presence off (plan Phase 0.4): these prompt-suggestion
+  // pipelines must not push unexpected load into the brand-presence pipeline / SNS
+  // allowlist unless a site is explicitly BP-enabled.
+  const result = await drsClient.createSchedule({
+    siteId,
+    providerId,
+    cadence,
+    orgId,
+    imsOrgId,
+    enableBrandPresence: false,
+    triggerImmediately: true,
+  });
+
+  log.info(`Registered DRS ${providerId} schedule ${result?.scheduleId ?? 'unknown'} `
+    + `(cadence=${cadence}) for site ${siteId}${result?.alreadyExisted ? ' (already existed)' : ''}`);
+  say(`:calendar_spiral: Registered DRS ${providerId} schedule for site ${siteId}`);
+  return result;
+}
+
+/**
+ * Registers the recurring SEMrush prompt-generation schedule (twice-monthly) for
+ * a newly onboarded site, triggering an immediate first run.
+ * @param {object} params - See {@link registerPromptSuggestionSchedule}.
+ * @returns {Promise<object|null>}
+ */
+export async function triggerSemrushPromptJob(params) {
+  return registerPromptSuggestionSchedule({
+    ...params,
+    providerId: 'prompt_generation_semrush',
+    cadence: DRS_CADENCE_TWICE_MONTHLY,
+  });
+}
+
+/**
+ * Registers the recurring "citation attempts" schedule (twice-monthly) for a
+ * newly onboarded site, triggering an immediate first run.
+ *
+ * NOTE: "Citation Attempt" is the renamed *output* of the agentic-traffic
+ * pipeline — there is no standalone citation-attempt provider — so the provider
+ * id below (`prompt_generation_agentic_traffic`) will NOT grep from the word
+ * "citation". DRS's per-provider Fargate whitelist (`AT_FARGATE_WHITELIST`) is
+ * the real enablement gate; leave agentic-traffic un-whitelisted in an env until
+ * its Postgres-format migration is confirmed healthy (plan Phase 0.2) so the
+ * best-effort first run cannot automate a known-failing pipeline.
+ * @param {object} params - See {@link registerPromptSuggestionSchedule}.
+ * @returns {Promise<object|null>}
+ */
+export async function triggerCitationAttemptJob(params) {
+  return registerPromptSuggestionSchedule({
+    ...params,
+    providerId: 'prompt_generation_agentic_traffic',
+    cadence: DRS_CADENCE_TWICE_MONTHLY,
+  });
+}
+
+/**
+ * Registers the recurring synthetic-personas schedule (quarterly) for a newly
+ * onboarded site, triggering an immediate first run.
+ * @param {object} params - See {@link registerPromptSuggestionSchedule}.
+ * @returns {Promise<object|null>}
+ */
+export async function triggerSyntheticPersonasJob(params) {
+  return registerPromptSuggestionSchedule({
+    ...params,
+    providerId: 'prompt_generation_synthetic_personas',
+    cadence: DRS_CADENCE_QUARTERLY,
+  });
+}
+
 // submitOnboardingPromptGenerationJob removed — prompt generation is now
 // triggered by DRS after Brandalf completes (LLMO-4258, option b).
 
@@ -1422,6 +1531,45 @@ export async function activateBrandAndGeneratePrompts({
       log.error(`Failed to start DRS Brandalf flow: ${drsError.message}`);
       say(':warning: Failed to start DRS Brandalf flow (will need manual trigger)');
     }
+
+    // Register the recurring "prompt suggestion" schedules (SEMrush, citation
+    // attempts, synthetic personas), each with an immediate first run. Done AFTER
+    // the Brandalf trigger above (which chains base prompt generation on
+    // completion, LLMO-4258) — not fired in parallel before brand data exists, so
+    // the first run has base prompts to work from (plan Phase 0.3). The immediate
+    // run is best-effort; the durable outcome is the recurring schedule row.
+    const promptSuggestionSchedules = [
+      { name: 'SEMrush prompts', providerId: 'prompt_generation_semrush', trigger: triggerSemrushPromptJob },
+      { name: 'citation attempts', providerId: 'prompt_generation_agentic_traffic', trigger: triggerCitationAttemptJob },
+      { name: 'synthetic personas', providerId: 'prompt_generation_synthetic_personas', trigger: triggerSyntheticPersonasJob },
+    ];
+    const scheduleDrsClient = DrsClient.createFrom(context);
+    await Promise.allSettled(
+      promptSuggestionSchedules.map(async ({ name, providerId, trigger }) => {
+        try {
+          await trigger({
+            drsClient: scheduleDrsClient,
+            siteId: site.getId(),
+            orgId: organization.getId(),
+            imsOrgId,
+            log,
+            say,
+          });
+        } catch (scheduleError) {
+          // Schedule-REGISTRATION failure (distinct from the best-effort immediate
+          // run): the site would never get a recurring schedule and nothing
+          // self-heals, so surface it loudly with full context — never swallow it.
+          // Onboarding still succeeds, mirroring the brand-activation side-effect
+          // handling in brands.js (activateBrand). `status` is the upstream HTTP
+          // status when the DRS client attaches one.
+          const status = scheduleError.status ?? 'unknown';
+          log.error(`Failed to register DRS ${name} schedule provider_id=${providerId} `
+            + `site_id=${site.getId()} status=${status}: ${scheduleError.message}`);
+          say(`:warning: Failed to register DRS ${name} schedule for site ${site.getId()} `
+            + '(will need manual trigger)');
+        }
+      }),
+    );
   } else {
     // V1 has no Brandalf trigger, so DRS will not submit prompt generation
     // automatically. Submit it directly here so v1 onboardings still get

test/controllers/llmo/llmo-onboarding.test.js

@@ -198,12 +198,14 @@ describe('LLMO Onboarding Functions', () => {
       isConfigured = true,
       submitJob = sandbox.stub().resolves({ job_id: 'test-brandalf-job-123' }),
       submitPromptGenerationJob = sandbox.stub().resolves({ job_id: 'test-drs-job-123' }),
+      createSchedule = sandbox.stub().resolves({ scheduleId: 'test-schedule-123', alreadyExisted: false }),
     } = options;
 
     const instance = {
       isConfigured: sandbox.stub().returns(isConfigured),
       submitJob,
       submitPromptGenerationJob,
+      createSchedule,
     };
 
     return {
@@ -5756,4 +5758,175 @@ describe('LLMO Onboarding Functions', () => {
       expect(() => validateConfiguration(config)).to.throw(/detectedCdn/);
     });
   });
+
+  describe('prompt-suggestion schedule triggers (Phase 3)', () => {
+    let onboardingModule;
+    let sandbox;
+
+    before(async () => {
+      onboardingModule = await esmock('../../../src/controllers/llmo/llmo-onboarding.js', {});
+    });
+
+    beforeEach(() => {
+      sandbox = sinon.createSandbox();
+    });
+
+    afterEach(() => {
+      sandbox.restore();
+    });
+
+    const buildDrsClient = (createScheduleImpl) => ({
+      isConfigured: sandbox.stub().returns(true),
+      createSchedule: createScheduleImpl
+        || sandbox.stub().resolves({ scheduleId: 'sched-1', alreadyExisted: false }),
+    });
+
+    const buildParams = (drsClient) => ({
+      drsClient,
+      siteId: 'site-123',
+      orgId: 'org-123',
+      imsOrgId: 'ABC123@AdobeOrg',
+      log: {
+        info: sandbox.stub(), debug: sandbox.stub(), warn: sandbox.stub(), error: sandbox.stub(),
+      },
+      say: sandbox.stub(),
+    });
+
+    const HELPERS = [
+      ['triggerSemrushPromptJob', 'prompt_generation_semrush', 'twice-monthly'],
+      ['triggerCitationAttemptJob', 'prompt_generation_agentic_traffic', 'twice-monthly'],
+      ['triggerSyntheticPersonasJob', 'prompt_generation_synthetic_personas', 'quarterly'],
+    ];
+
+    HELPERS.forEach(([fnName, providerId, cadence]) => {
+      it(`${fnName} registers a ${cadence} schedule for ${providerId} with an immediate first run`, async () => {
+        const drsClient = buildDrsClient();
+        const result = await onboardingModule[fnName](buildParams(drsClient));
+
+        expect(drsClient.createSchedule).to.have.been.calledOnce;
+        expect(drsClient.createSchedule.firstCall.args[0]).to.deep.include({
+          siteId: 'site-123',
+          orgId: 'org-123',
+          imsOrgId: 'ABC123@AdobeOrg',
+          providerId,
+          cadence,
+          enableBrandPresence: false,
+          triggerImmediately: true,
+        });
+        expect(result).to.deep.equal({ scheduleId: 'sched-1', alreadyExisted: false });
+      });
+
+      it(`${fnName} skips (no createSchedule) when the DRS client is not configured`, async () => {
+        const drsClient = buildDrsClient();
+        drsClient.isConfigured.returns(false);
+        const params = buildParams(drsClient);
+
+        const result = await onboardingModule[fnName](params);
+
+        expect(drsClient.createSchedule).to.not.have.been.called;
+        expect(result).to.equal(null);
+        expect(params.log.debug).to.have.been.calledWithMatch(providerId);
+      });
+
+      it(`${fnName} propagates a schedule-registration failure to the caller (not swallowed)`, async () => {
+        const err = new Error('DRS POST /schedules failed: 500');
+        const drsClient = buildDrsClient(sandbox.stub().rejects(err));
+
+        await expect(onboardingModule[fnName](buildParams(drsClient)))
+          .to.be.rejectedWith('DRS POST /schedules failed: 500');
+      });
+    });
+  });
+
+  describe('activateBrandAndGeneratePrompts — V2 prompt-suggestion schedules', () => {
+    let sandbox;
+
+    beforeEach(() => {
+      sandbox = sinon.createSandbox();
+    });
+
+    afterEach(() => {
+      sandbox.restore();
+    });
+
+    const buildV2Context = () => {
+      const brandsMaybeSingle = sandbox.stub().resolves({ data: null, error: null });
+      const eqName = sandbox.stub().returns({ maybeSingle: brandsMaybeSingle });
+      const eqOrg = sandbox.stub().returns({ eq: eqName });
+      const select = sandbox.stub().returns({ eq: eqOrg });
+      const postgrestClient = { from: sandbox.stub().returns({ select }) };
+      const log = {
+        info: sandbox.stub(), debug: sandbox.stub(), warn: sandbox.stub(), error: sandbox.stub(),
+      };
+      return {
+        log,
+        dataAccess: { services: { postgrestClient } },
+      };
+    };
+
+    const buildV2Params = (context) => ({
+      onboardingMode: 'v2',
+      organization: { getId: sandbox.stub().returns('org-123') },
+      site: { getId: sandbox.stub().returns('site-123') },
+      siteConfig: { getFetchConfig: sandbox.stub().returns({}) },
+      brandName: 'Test Brand',
+      imsOrgId: 'ABC123@AdobeOrg',
+      baseURL: 'https://example.com',
+      context,
+      say: sandbox.stub(),
+    });
+
+    it('registers all three prompt-suggestion schedules after the Brandalf trigger', async () => {
+      const mockDrsClient = createMockDrsClient(sandbox);
+      const { activateBrandAndGeneratePrompts } = await esmock(
+        '../../../src/controllers/llmo/llmo-onboarding.js',
+        createCommonEsmockDependencies({
+          mockDrsClient,
+          mockUpsertBrand: sandbox.stub().resolves({ id: 'brand-123', name: 'Test Brand' }),
+        }),
+      );
+
+      const context = buildV2Context();
+      await activateBrandAndGeneratePrompts(buildV2Params(context));
+
+      const instance = mockDrsClient.createFrom();
+      expect(instance.submitJob).to.have.been.calledOnce; // Brandalf fired first
+      expect(instance.createSchedule).to.have.been.calledThrice;
+      const providerIds = instance.createSchedule.getCalls().map((c) => c.args[0].providerId);
+      expect(providerIds).to.have.members([
+        'prompt_generation_semrush',
+        'prompt_generation_agentic_traffic',
+        'prompt_generation_synthetic_personas',
+      ]);
+    });
+
+    it('logs a schedule-registration failure at ERROR with context but still completes onboarding', async () => {
+      const err = new Error('DRS POST /schedules failed');
+      err.status = 500;
+      const mockDrsClient = createMockDrsClient(sandbox, {
+        createSchedule: sandbox.stub().rejects(err),
+      });
+      const { activateBrandAndGeneratePrompts } = await esmock(
+        '../../../src/controllers/llmo/llmo-onboarding.js',
+        createCommonEsmockDependencies({
+          mockDrsClient,
+          mockUpsertBrand: sandbox.stub().resolves({ id: 'brand-123', name: 'Test Brand' }),
+        }),
+      );
+
+      const context = buildV2Context();
+      // Must resolve (onboarding succeeds) despite every schedule registration failing.
+      await activateBrandAndGeneratePrompts(buildV2Params(context));
+
+      const errorLogs = context.log.error.getCalls().map((c) => c.args[0]);
+      const semrushLog = errorLogs.find((m) => m.includes('prompt_generation_semrush'));
+      expect(semrushLog, 'expected an ERROR log for the failed semrush schedule').to.be.a('string');
+      expect(semrushLog).to.include('site_id=site-123');
+      expect(semrushLog).to.include('status=500');
+      // All three providers are surfaced, none swallowed.
+      expect(context.log.error).to.have.been.calledThrice;
+      // Brandalf still fired — the schedule failures did not abort onboarding.
+      expect(mockDrsClient.createFrom().submitJob).to.have.been.calledOnce;
+    });
+  });
 });