@sendinel/mcp-server 1.0.0

package/build/lib/action-approvals.js

@@ -0,0 +1,154 @@
+import { db, requestContext } from '../db.js';
+import { getProjectId } from '../project.js';
+import { fireWebhookEvent } from './webhook-events.js';
+/**
+ * Action approval tiers:
+ *
+ * Tier 0 (autonomous) — No approval needed. Reads, low-risk writes.
+ * Tier 1 (gated)      — Requires dashboard/Slack approval. Sends to real people, bulk ops.
+ * Tier 2 (protected)  — Requires dashboard approval + typed confirmation. Irreversible data ops.
+ */
+const GATED_ACTIONS = new Set([
+    'launch_campaign', // sends real emails
+    'create_campaign_with_content', // can activate + send in one call
+    'enroll_segment', // bulk enrollment
+    'import_subscribers', // bulk data ingestion
+    'subscribe_webhook', // outbound data channel
+    'send_transactional', // sends a real email
+]);
+const PROTECTED_ACTIONS = new Set([
+    'delete_subscriber_data', // GDPR delete — irreversible
+    'merge_subscribers', // data consolidation — irreversible
+    'delete_segment', // affects campaign targeting
+    'identify_inactive', // bulk suppression (when not dry_run)
+    'promote_ab_winner', // deletes losing variants
+]);
+export function getApprovalTier(action, params) {
+    // CRITICAL: Protected actions ALWAYS require approval, even in autonomous mode.
+    // These are irreversible (GDPR delete, merge, etc.) — no opt-out.
+    if (PROTECTED_ACTIONS.has(action)) {
+        // Exception: identify_inactive in dry_run mode is safe (read-only report)
+        if (action === 'identify_inactive' && params?.dry_run !== false)
+            return 'autonomous';
+        return 'protected';
+    }
+    // Autonomous mode: user explicitly opted out of approval gates for gated actions
+    // (request-scoped under HTTP — env is only trustworthy for single-project stdio)
+    const mode = requestContext()?.approvalMode ?? process.env.SENDINEL_APPROVAL_MODE ?? 'standard';
+    if (mode === 'autonomous')
+        return 'autonomous';
+    // Special cases: some gated actions are safe in certain modes
+    if (action === 'create_campaign_with_content' && !params?.activate)
+        return 'autonomous';
+    if (action === 'send_transactional' && params?.category === 'test')
+        return 'autonomous';
+    if (GATED_ACTIONS.has(action))
+        return 'gated';
+    return 'autonomous';
+}
+/** Build a human-readable summary of the action for the approval screen */
+export function buildApprovalSummary(action, params) {
+    const summaries = {
+        launch_campaign: (p) => `Launch campaign "${p.name || p.campaign_name || 'unknown'}" — will send emails to real contacts`,
+        create_campaign_with_content: (p) => `Create + activate campaign "${p.name}" with ${p.steps?.length ?? 0} email(s) and enroll contacts`,
+        enroll_segment: (p) => `Enroll all contacts from site into campaign ${p.campaign_id}`,
+        import_subscribers: (p) => `Import subscribers (up to ${p.contacts?.length ?? 'unknown'} records)`,
+        subscribe_webhook: (p) => `Register webhook endpoint: ${p.url} — will receive event data`,
+        send_transactional: (p) => `Send transactional email to ${p.to}`,
+        delete_subscriber_data: (p) => `GDPR delete subscriber ${p.contact_id} — permanently and irreversibly removes all data`,
+        merge_subscribers: (p) => `Merge ${p.source_ids?.length ?? 0} subscribers into ${p.target_id} — source subscribers will be deleted`,
+        delete_segment: (p) => `Delete segment ${p.segment_id} — campaigns using this segment lose their targeting`,
+        identify_inactive: (p) => `Suppress contacts inactive for ${p.days ?? 90} days — they will stop receiving emails`,
+        promote_ab_winner: (p) => `Promote A/B test winner "${p.winner}" — losing variants will be deleted`,
+    };
+    const fn = summaries[action];
+    return fn ? fn(params) : `Execute ${action} with provided parameters`;
+}
+/**
+ * Request human approval for an action. Creates a pending approval token
+ * and returns instructions for the agent to wait.
+ */
+export async function requestApproval(action, params, apiKeyId) {
+    const tier = getApprovalTier(action, params);
+    const summary = buildApprovalSummary(action, params);
+    const expiresAt = new Date(Date.now() + 30 * 60 * 1000).toISOString();
+    const { data, error } = await db()
+        .from('action_approvals')
+        .insert({
+        project_id: getProjectId(),
+        api_key_id: apiKeyId ?? null,
+        action,
+        tier,
+        params,
+        summary,
+        expires_at: expiresAt,
+    })
+        .select('id')
+        .single();
+    if (error)
+        throw new Error(`Failed to create approval request: ${error.message}`);
+    fireWebhookEvent('approval.requested', {
+        approval_id: data.id,
+        kind: action,
+        resource_id: params.resource_id ?? params.campaign_id ?? params.contact_id ?? null,
+        requested_by: apiKeyId ?? null,
+    }, getProjectId()).catch(() => { });
+    return {
+        requires_approval: true,
+        approval_id: data.id,
+        tier,
+        action,
+        summary,
+        expires_at: expiresAt,
+        approve_via: 'Dashboard → Pending Approvals, or Slack /sendinel approve',
+        message: `This action requires human approval. A notification has been sent to your dashboard. Approval ID: ${data.id}. Check status with: poll this approval_id, or wait for the webhook callback (event: approval.decided). Token expires in 30 minutes.`,
+    };
+}
+/**
+ * Check if an approval token has been approved.
+ * Returns the approval if approved, null if still pending, throws if rejected/expired.
+ */
+export async function checkApproval(approvalId, options = {}) {
+    const { data, error } = await db()
+        .from('action_approvals')
+        .select('status, decided_by, decided_via, expires_at, used_at')
+        .eq('id', approvalId)
+        .eq('project_id', getProjectId())
+        .maybeSingle();
+    if (error || !data)
+        return { approved: false, status: 'not_found' };
+    // Check expiry
+    if (data.status === 'pending' && new Date(data.expires_at) < new Date()) {
+        await db()
+            .from('action_approvals')
+            .update({ status: 'expired' })
+            .eq('id', approvalId);
+        return { approved: false, status: 'expired' };
+    }
+    if (data.status !== 'approved' || !options.consume) {
+        if (data.used_at)
+            return { approved: false, status: 'consumed' };
+        return {
+            approved: data.status === 'approved',
+            status: data.status,
+            decided_by: data.decided_by,
+        };
+    }
+    const { data: claimed, error: claimError } = await db()
+        .from('action_approvals')
+        .update({ status: 'used', used_at: new Date().toISOString() })
+        .eq('id', approvalId)
+        .eq('project_id', getProjectId())
+        .eq('status', 'approved')
+        .is('used_at', null)
+        .select('decided_by')
+        .maybeSingle();
+    if (claimError || !claimed) {
+        return { approved: false, status: 'consumed' };
+    }
+    return {
+        approved: true,
+        status: 'approved',
+        decided_by: claimed.decided_by,
+    };
+}

package/build/lib/schedule.d.ts

@@ -0,0 +1,36 @@
+export declare const SCHEDULE_WINDOWS: readonly ["today", "tomorrow", "7d", "30d"];
+export type ScheduleWindow = (typeof SCHEDULE_WINDOWS)[number];
+export type ScheduleCampaign = {
+    id: string;
+    name: string;
+    type: string;
+};
+export type ScheduleEnrollmentRow = {
+    next_send_at: string | null;
+    campaigns: ScheduleCampaign | ScheduleCampaign[] | null;
+};
+export type ScheduleCampaignGroup = {
+    campaign_id: string;
+    campaign_name: string;
+    campaign_type: string;
+    total_sends_scheduled: number;
+    sends_in_window: {
+        date: string;
+        total_sends_scheduled: number;
+    }[];
+    earliest_send: string | null;
+    latest_send: string | null;
+};
+export declare function normalizeScheduleWindow(value?: string | null): ScheduleWindow;
+export declare function startOfUtcDay(date: Date): Date;
+export declare function getScheduleWindowBounds(window?: ScheduleWindow, now?: Date): {
+    window: "tomorrow";
+    start: Date;
+    end: Date;
+} | {
+    window: "today" | "7d" | "30d";
+    start: Date;
+    end: Date;
+};
+export declare function isoDate(value: string | Date): string;
+export declare function groupScheduleByCampaign(rows: ScheduleEnrollmentRow[]): ScheduleCampaignGroup[];

package/build/lib/schedule.js

@@ -0,0 +1,63 @@
+export const SCHEDULE_WINDOWS = ['today', 'tomorrow', '7d', '30d'];
+export function normalizeScheduleWindow(value) {
+    return SCHEDULE_WINDOWS.includes(value) ? value : 'today';
+}
+export function startOfUtcDay(date) {
+    return new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+}
+function addUtcDays(date, days) {
+    const next = new Date(date);
+    next.setUTCDate(next.getUTCDate() + days);
+    return next;
+}
+export function getScheduleWindowBounds(window = 'today', now = new Date()) {
+    const today = startOfUtcDay(now);
+    if (window === 'tomorrow') {
+        const start = addUtcDays(today, 1);
+        return { window, start, end: addUtcDays(start, 1) };
+    }
+    const days = window === '7d' ? 7 : window === '30d' ? 30 : 1;
+    return { window, start: today, end: addUtcDays(today, days) };
+}
+export function isoDate(value) {
+    return new Date(value).toISOString().slice(0, 10);
+}
+function getCampaign(row) {
+    if (Array.isArray(row.campaigns))
+        return row.campaigns[0] ?? null;
+    return row.campaigns ?? null;
+}
+export function groupScheduleByCampaign(rows) {
+    const groups = new Map();
+    for (const row of rows) {
+        if (!row.next_send_at)
+            continue;
+        const campaign = getCampaign(row);
+        if (!campaign?.id)
+            continue;
+        const existing = groups.get(campaign.id) ?? {
+            campaign_id: campaign.id,
+            campaign_name: campaign.name,
+            campaign_type: campaign.type,
+            total_sends_scheduled: 0,
+            sends_in_window: [],
+            earliest_send: null,
+            latest_send: null,
+            dateCounts: new Map(),
+        };
+        existing.total_sends_scheduled += 1;
+        existing.earliest_send = !existing.earliest_send || row.next_send_at < existing.earliest_send ? row.next_send_at : existing.earliest_send;
+        existing.latest_send = !existing.latest_send || row.next_send_at > existing.latest_send ? row.next_send_at : existing.latest_send;
+        const date = isoDate(row.next_send_at);
+        existing.dateCounts.set(date, (existing.dateCounts.get(date) ?? 0) + 1);
+        groups.set(campaign.id, existing);
+    }
+    return [...groups.values()]
+        .map(({ dateCounts, ...group }) => ({
+        ...group,
+        sends_in_window: [...dateCounts.entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([date, total_sends_scheduled]) => ({ date, total_sends_scheduled })),
+    }))
+        .sort((a, b) => (a.earliest_send ?? '').localeCompare(b.earliest_send ?? ''));
+}

package/build/lib/social-engine/archetypes.d.ts

@@ -0,0 +1,27 @@
+import type { SocialBrief, SocialFormat, SocialPostPlatform } from "./types.js";
+export interface SocialArchetype {
+    id: string;
+    name: string;
+    /** Fill-in-the-blank hook pattern the model adapts, never copies verbatim. */
+    hook_formula: string;
+    /** Ordered roles; each maps to hard rules in the prompt builder. */
+    structure: Array<"hook" | "pain" | "proof" | "solution" | "story" | "steps" | "question" | "cta">;
+    /** The psychological mechanism this archetype rides. */
+    neurodesign_trigger: string;
+    reference_creators: string[];
+    /** Voice notes layered into the prompt for this archetype only. */
+    voice_notes: string;
+    best_for: {
+        goals: string[];
+        platforms: SocialPostPlatform[];
+        formats: SocialFormat[];
+    };
+}
+export declare const SOCIAL_ARCHETYPES: SocialArchetype[];
+export declare function getArchetype(id: string): SocialArchetype | undefined;
+/**
+ * Deterministic archetype selection: goal keywords dominate, platform and
+ * format fit break ties, declaration order breaks exact ties. An explicit
+ * brief.archetype_id always wins (the user picked).
+ */
+export declare function selectArchetype(brief: SocialBrief): SocialArchetype;

package/build/lib/social-engine/archetypes.js

@@ -0,0 +1,160 @@
+// Creator archetypes (#1360) — mirrors Synchronex's creator-archetypes layer.
+// Mirror of packages/dashboard/lib/social-engine/archetypes.ts for the MCP
+// server package (imports adapted to Node16 ".js" paths + local types).
+//
+// An archetype is what makes a post read like a specific creator instead of
+// generic marketing: a hook formula, a role structure with hard rules, a
+// neurodesign trigger, and reference creators the model can pattern-match.
+// Selection is deterministic (scored against the brief) so the same brief
+// picks the same archetype — an explicit archetype_id on the brief wins.
+export const SOCIAL_ARCHETYPES = [
+    {
+        id: "contrarian_operator",
+        name: "Contrarian Operator",
+        hook_formula: "Everyone {common_practice}. We {opposite}. Here's why.",
+        structure: ["hook", "pain", "proof", "solution", "cta"],
+        neurodesign_trigger: "pattern interrupt — violated expectation forces a second look",
+        reference_creators: ["Jason Fried", "Amanda Goetz"],
+        voice_notes: "Confident, not combative. Disagree with the practice, never with the reader.",
+        best_for: {
+            goals: ["position", "differentiat", "opinion", "philosophy", "why we"],
+            platforms: ["linkedin", "x", "twitter", "threads"],
+            formats: ["text", "single_image"],
+        },
+    },
+    {
+        id: "numbers_prover",
+        name: "Numbers Prover",
+        hook_formula: "{specific_number} {unexpected_outcome}. Here's what did it.",
+        structure: ["hook", "proof", "solution", "cta"],
+        neurodesign_trigger: "specificity = credibility — a concrete number reads as evidence, not claim",
+        reference_creators: ["Nathan Barry", "Pieter Levels"],
+        voice_notes: "Let the numbers carry it. No adjectives where a number can sit instead.",
+        best_for: {
+            goals: ["result", "milestone", "metric", "growth", "revenue", "launch result", "case study"],
+            platforms: ["x", "twitter", "linkedin", "bluesky"],
+            formats: ["text", "single_image"],
+        },
+    },
+    {
+        id: "behind_the_builder",
+        name: "Behind the Builder",
+        hook_formula: "What building {thing} actually looked like this week:",
+        structure: ["hook", "story", "solution", "cta"],
+        neurodesign_trigger: "parasocial authenticity — process beats polish for trust",
+        reference_creators: ["Arvid Kahl", "Marc Lou"],
+        voice_notes: "First person, present tense where possible. Include one unglamorous detail.",
+        best_for: {
+            goals: ["build in public", "behind", "progress", "update", "journey", "shipped"],
+            platforms: ["x", "twitter", "threads", "instagram", "tiktok"],
+            formats: ["text", "single_image", "video_script"],
+        },
+    },
+    {
+        id: "teacher_frameworker",
+        name: "Teacher Frameworker",
+        hook_formula: "The {n}-step way to {outcome} (without {common_pain}):",
+        structure: ["hook", "pain", "steps", "cta"],
+        neurodesign_trigger: "competence + saveability — frameworks get bookmarked, bookmarks compound reach",
+        reference_creators: ["Justin Welsh", "Katelyn Bourgoin"],
+        voice_notes: "Each step must be doable today. Number them. No step longer than two lines.",
+        best_for: {
+            goals: ["teach", "how to", "guide", "educat", "tips", "framework", "process"],
+            platforms: ["linkedin", "instagram", "pinterest", "youtube"],
+            formats: ["carousel", "text"],
+        },
+    },
+    {
+        id: "storyteller_arc",
+        name: "Storyteller Arc",
+        hook_formula: "{time_marker}, {low_point}. Then {turn}.",
+        structure: ["hook", "story", "solution", "cta"],
+        neurodesign_trigger: "narrative transportation — a story suspends counter-arguing",
+        reference_creators: ["Steven Bartlett", "Ali Abdaal"],
+        voice_notes: "One story, one lesson. Cut every detail that doesn't serve the turn.",
+        best_for: {
+            goals: ["story", "lesson", "mistake", "failure", "learned", "customer story"],
+            platforms: ["linkedin", "instagram", "facebook", "threads"],
+            formats: ["text", "carousel", "video_script"],
+        },
+    },
+    {
+        id: "straight_shooter",
+        name: "Straight Shooter",
+        hook_formula: "{thing} is live. It does {concrete_job}.",
+        structure: ["hook", "solution", "proof", "cta"],
+        neurodesign_trigger: "clarity premium — when everyone hypes, plain statements stand out",
+        reference_creators: ["Basecamp/37signals", "Linear"],
+        voice_notes: "Announce like you'd tell a colleague. One real use case beats three benefits.",
+        best_for: {
+            goals: ["announce", "release", "launch", "new feature", "ship", "available"],
+            platforms: ["x", "twitter", "linkedin", "facebook", "google_business", "bluesky"],
+            formats: ["text", "single_image"],
+        },
+    },
+    {
+        id: "provocateur_question",
+        name: "Provocateur",
+        hook_formula: "Hot take: {uncomfortable_claim}.",
+        structure: ["hook", "pain", "question"],
+        neurodesign_trigger: "open loop + identity stakes — people reply to defend how they work",
+        reference_creators: ["Adam Singer", "GergelyOrosz"],
+        voice_notes: "End on the question, not a CTA. The comments are the conversion.",
+        best_for: {
+            goals: ["engage", "discussion", "debate", "community", "poll", "conversation"],
+            platforms: ["x", "twitter", "threads", "linkedin", "reddit", "facebook"],
+            formats: ["text"],
+        },
+    },
+    {
+        id: "curator_listicle",
+        name: "Curator",
+        hook_formula: "{n} {things} that {outcome} (#{standout} is underrated):",
+        structure: ["hook", "steps", "cta"],
+        neurodesign_trigger: "completeness + curiosity gap — the teased item makes skipping feel costly",
+        reference_creators: ["Sahil Bloom", "Lenny Rachitsky"],
+        voice_notes: "Every item must stand alone. Lead with the strongest, close with the most surprising.",
+        best_for: {
+            goals: ["roundup", "list", "resources", "tools", "ideas", "examples"],
+            platforms: ["x", "twitter", "linkedin", "instagram", "pinterest"],
+            formats: ["carousel", "text"],
+        },
+    },
+];
+const ARCHETYPE_BY_ID = new Map(SOCIAL_ARCHETYPES.map((a) => [a.id, a]));
+export function getArchetype(id) {
+    return ARCHETYPE_BY_ID.get(id);
+}
+/**
+ * Deterministic archetype selection: goal keywords dominate, platform and
+ * format fit break ties, declaration order breaks exact ties. An explicit
+ * brief.archetype_id always wins (the user picked).
+ */
+export function selectArchetype(brief) {
+    if (brief.archetype_id) {
+        const chosen = ARCHETYPE_BY_ID.get(brief.archetype_id);
+        if (chosen)
+            return chosen;
+    }
+    const goal = `${brief.goal} ${brief.style ?? ""}`.toLowerCase();
+    let best = SOCIAL_ARCHETYPES[0];
+    let bestScore = -1;
+    for (const archetype of SOCIAL_ARCHETYPES) {
+        let score = 0;
+        for (const stem of archetype.best_for.goals) {
+            if (goal.includes(stem))
+                score += 4;
+        }
+        for (const platform of brief.platforms) {
+            if (archetype.best_for.platforms.includes(platform))
+                score += 1;
+        }
+        if (archetype.best_for.formats.includes(brief.format))
+            score += 2;
+        if (score > bestScore) {
+            best = archetype;
+            bestScore = score;
+        }
+    }
+    return best;
+}

package/build/lib/social-engine/index.d.ts

@@ -0,0 +1,5 @@
+export { SOCIAL_ARCHETYPES, getArchetype, selectArchetype, type SocialArchetype } from "./archetypes.js";
+export { PLATFORM_CONSTRAINTS, assembleCaption, buildPlatformRuleBlock, getPlatformConstraints, type PlatformConstraints } from "./platform-constraints.js";
+export { buildSocialSystemPrompt, buildSocialUserPrompt, type SocialPromptInput } from "./prompt-builder.js";
+export { parseSocialResponse } from "./parse.js";
+export { SOCIAL_POST_PLATFORMS, type CarouselFrame, type MediaPlan, type SocialBrief, type SocialFormat, type SocialGenerationRecord, type SocialPostIR, type SocialPostPlatform, type SocialVariant, type VariantLabel, } from "./types.js";

package/build/lib/social-engine/index.js

@@ -0,0 +1,6 @@
+// Mirror of packages/dashboard/lib/social-engine/index.ts for the MCP server.
+export { SOCIAL_ARCHETYPES, getArchetype, selectArchetype } from "./archetypes.js";
+export { PLATFORM_CONSTRAINTS, assembleCaption, buildPlatformRuleBlock, getPlatformConstraints } from "./platform-constraints.js";
+export { buildSocialSystemPrompt, buildSocialUserPrompt } from "./prompt-builder.js";
+export { parseSocialResponse } from "./parse.js";
+export { SOCIAL_POST_PLATFORMS, } from "./types.js";

package/build/lib/social-engine/parse.d.ts

@@ -0,0 +1,7 @@
+import type { SocialPostIR, SocialPostPlatform } from "./types.js";
+/**
+ * Parse one platform segment's model output into a validated IR.
+ * Throws on unusable output (no parseable variants) — the caller decides
+ * whether to retry or surface the failure.
+ */
+export declare function parseSocialResponse(raw: string, platform: SocialPostPlatform, archetypeId: string): SocialPostIR;

package/build/lib/social-engine/parse.js

@@ -0,0 +1,83 @@
+// Response parsing + gen-time enforcement (#1360). Takes the raw model text
+// for ONE platform segment and returns a validated SocialPostIR: variants
+// normalized to A/B/C, captions assembled under platform budgets (hashtag
+// trim, then flagged sentence-boundary truncation), media plan sanitized.
+// Mirror of packages/dashboard/lib/social-engine/parse.ts.
+import { assembleCaption } from "./platform-constraints.js";
+const VARIANT_LABELS = ["A", "B", "C"];
+function cleanString(value, max) {
+    return typeof value === "string" ? value.trim().slice(0, max) : "";
+}
+function sanitizeMediaPlan(raw) {
+    if (!raw || typeof raw !== "object")
+        return undefined;
+    const plan = raw;
+    const kind = plan.kind;
+    if (kind !== "single_image" && kind !== "carousel" && kind !== "video_script")
+        return undefined;
+    const result = { kind };
+    const direction = cleanString(plan.image_direction, 500);
+    if (direction)
+        result.image_direction = direction;
+    if (Array.isArray(plan.frames)) {
+        const frames = plan.frames
+            .filter((frame) => Boolean(frame) && typeof frame === "object")
+            .slice(0, 10)
+            .map((frame, index) => ({
+            order: typeof frame.order === "number" ? frame.order : index + 1,
+            headline: cleanString(frame.headline, 120),
+            support_text: cleanString(frame.support_text, 300),
+            visual_direction: cleanString(frame.visual_direction, 300),
+        }))
+            .filter((frame) => frame.headline);
+        if (frames.length)
+            result.frames = frames;
+    }
+    return result.image_direction || result.frames ? result : undefined;
+}
+/**
+ * Parse one platform segment's model output into a validated IR.
+ * Throws on unusable output (no parseable variants) — the caller decides
+ * whether to retry or surface the failure.
+ */
+export function parseSocialResponse(raw, platform, archetypeId) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.replace(/```json?\n?|```/g, "").trim());
+    }
+    catch {
+        throw new Error(`Unparseable model output for ${platform}`);
+    }
+    const rawVariants = Array.isArray(parsed.variants) ? parsed.variants : [];
+    const warnings = [];
+    const variants = rawVariants
+        .filter((v) => Boolean(v) && typeof v === "object")
+        .slice(0, 3)
+        .map((v, index) => {
+        const parts = {
+            hook: cleanString(v.hook, 400),
+            body: cleanString(v.body, 4000),
+            cta: cleanString(v.cta, 300),
+            hashtags: Array.isArray(v.hashtags) ? v.hashtags.filter((t) => typeof t === "string").slice(0, 15) : [],
+        };
+        const { caption, warnings: captionWarnings } = assembleCaption(parts, platform);
+        warnings.push(...captionWarnings.map((w) => `variant ${VARIANT_LABELS[index]}: ${w}`));
+        return {
+            label: VARIANT_LABELS[index],
+            angle: cleanString(v.angle, 200),
+            ...parts,
+            caption,
+        };
+    })
+        .filter((v) => v.caption.length > 0);
+    if (!variants.length) {
+        throw new Error(`Model returned no usable variants for ${platform}`);
+    }
+    return {
+        platform,
+        archetype_id: archetypeId,
+        variants,
+        media_plan: sanitizeMediaPlan(parsed.media_plan),
+        warnings,
+    };
+}

package/build/lib/social-engine/platform-constraints.d.ts

@@ -0,0 +1,27 @@
+import type { SocialPostPlatform, SocialVariant } from "./types.js";
+export interface PlatformConstraints {
+    /** Hard caption ceiling (publish fails or truncates beyond it). */
+    maxChars: number;
+    /** Soft target the prompt aims for — leaves headroom under maxChars. */
+    targetChars: number;
+    hashtags: {
+        min: number;
+        max: number;
+    };
+    emojiOk: boolean;
+    lineBreaks: boolean;
+    toneNote: string;
+}
+export declare const PLATFORM_CONSTRAINTS: Record<SocialPostPlatform, PlatformConstraints>;
+export declare function getPlatformConstraints(platform: SocialPostPlatform): PlatformConstraints;
+/** Prose rule block for the prompt — derived from the structured constraints. */
+export declare function buildPlatformRuleBlock(platform: SocialPostPlatform): string;
+/**
+ * Gen-time enforcement: assemble the publishable caption from variant parts,
+ * repairing deterministically when over budget — hashtags trimmed first, then
+ * sentence-boundary truncation as a last resort (flagged, never silent).
+ */
+export declare function assembleCaption(variant: Pick<SocialVariant, "hook" | "body" | "cta" | "hashtags">, platform: SocialPostPlatform): {
+    caption: string;
+    warnings: string[];
+};

package/build/lib/social-engine/platform-constraints.js

@@ -0,0 +1,70 @@
+// Platform constraints (#1360) — structured per-platform rules, enforced at
+// generation time: they shape the prompt AND validate/repair the parsed
+// output. Single source of truth for the prose rules the prompt uses.
+// Mirror of packages/dashboard/lib/social-engine/platform-constraints.ts.
+export const PLATFORM_CONSTRAINTS = {
+    x: { maxChars: 280, targetChars: 240, hashtags: { min: 0, max: 2 }, emojiOk: false, lineBreaks: true, toneNote: "Lead with the hook. No fluff. Conversational and direct." },
+    twitter: { maxChars: 280, targetChars: 240, hashtags: { min: 0, max: 2 }, emojiOk: false, lineBreaks: true, toneNote: "Lead with the hook. No fluff. Conversational and direct." },
+    linkedin: { maxChars: 1300, targetChars: 1000, hashtags: { min: 3, max: 5 }, emojiOk: false, lineBreaks: true, toneNote: "Professional but human. Bold first line, no greeting. Line breaks for readability. Thought-leadership framing." },
+    instagram: { maxChars: 2200, targetChars: 1500, hashtags: { min: 5, max: 10 }, emojiOk: true, lineBreaks: true, toneNote: "Conversational and warm. Hook on line 1 — the reader sees it before 'more'. Soft CTA at the end." },
+    facebook: { maxChars: 500, targetChars: 400, hashtags: { min: 0, max: 2 }, emojiOk: true, lineBreaks: true, toneNote: "Community-focused. Pose a question or invite discussion. Link in post is fine." },
+    tiktok: { maxChars: 150, targetChars: 120, hashtags: { min: 2, max: 3 }, emojiOk: true, lineBreaks: false, toneNote: "Casual, energetic hook. Trending language is acceptable. No hashtag stuffing." },
+    threads: { maxChars: 500, targetChars: 400, hashtags: { min: 0, max: 2 }, emojiOk: true, lineBreaks: true, toneNote: "Casual and conversational — a hot take or behind-the-scenes note." },
+    reddit: { maxChars: 4000, targetChars: 1200, hashtags: { min: 0, max: 0 }, emojiOk: false, lineBreaks: true, toneNote: "No sales tone. Community-first. Be genuinely useful; write like a member, not a brand." },
+    bluesky: { maxChars: 300, targetChars: 260, hashtags: { min: 0, max: 1 }, emojiOk: false, lineBreaks: true, toneNote: "Link-forward culture. Share the insight, let the link do the rest." },
+    youtube: { maxChars: 5000, targetChars: 1500, hashtags: { min: 0, max: 3 }, emojiOk: false, lineBreaks: true, toneNote: "Description format: hook sentence, 2–3 paragraph summary, keywords embedded naturally, subscribe CTA at the end." },
+    pinterest: { maxChars: 500, targetChars: 400, hashtags: { min: 0, max: 4 }, emojiOk: false, lineBreaks: false, toneNote: "Inspirational and keyword-rich for SEO. Describe what the reader will learn or make." },
+    google_business: { maxChars: 1500, targetChars: 1000, hashtags: { min: 0, max: 0 }, emojiOk: false, lineBreaks: true, toneNote: "Professional and factual. Local-business tone. Highlight value, include a CTA." },
+};
+export function getPlatformConstraints(platform) {
+    return PLATFORM_CONSTRAINTS[platform];
+}
+/** Prose rule block for the prompt — derived from the structured constraints. */
+export function buildPlatformRuleBlock(platform) {
+    const c = PLATFORM_CONSTRAINTS[platform];
+    const hashtagRule = c.hashtags.max === 0
+        ? "No hashtags."
+        : `${c.hashtags.min}–${c.hashtags.max} hashtags${c.hashtags.min === 0 ? " at most" : ""}.`;
+    return [
+        `Platform: ${platform}.`,
+        `Hard limit ${c.maxChars} characters for the FULL caption (hook + body + cta + hashtags); aim for ~${c.targetChars}.`,
+        hashtagRule,
+        c.emojiOk ? "Emojis allowed where natural." : "No emojis.",
+        c.lineBreaks ? "Use line breaks for rhythm." : "Single block of text, no line breaks.",
+        c.toneNote,
+    ].join(" ");
+}
+/**
+ * Gen-time enforcement: assemble the publishable caption from variant parts,
+ * repairing deterministically when over budget — hashtags trimmed first, then
+ * sentence-boundary truncation as a last resort (flagged, never silent).
+ */
+export function assembleCaption(variant, platform) {
+    const c = PLATFORM_CONSTRAINTS[platform];
+    const warnings = [];
+    const joiner = c.lineBreaks ? "\n\n" : " ";
+    let hashtags = (variant.hashtags ?? [])
+        .map((tag) => tag.trim())
+        .filter(Boolean)
+        .map((tag) => (tag.startsWith("#") ? tag : `#${tag}`))
+        .slice(0, c.hashtags.max);
+    const assemble = (tags) => {
+        const parts = [variant.hook, variant.body, variant.cta].map((part) => (part ?? "").trim()).filter(Boolean);
+        const text = parts.join(joiner);
+        return tags.length ? `${text}${joiner}${tags.join(" ")}` : text;
+    };
+    let caption = assemble(hashtags);
+    while (caption.length > c.maxChars && hashtags.length > c.hashtags.min) {
+        hashtags = hashtags.slice(0, -1);
+        caption = assemble(hashtags);
+        if (!warnings.length)
+            warnings.push(`${platform}: trimmed hashtags to fit ${c.maxChars} chars`);
+    }
+    if (caption.length > c.maxChars) {
+        const slice = caption.slice(0, c.maxChars);
+        const lastStop = Math.max(slice.lastIndexOf(". "), slice.lastIndexOf("! "), slice.lastIndexOf("? "), slice.lastIndexOf("\n"));
+        caption = lastStop > c.maxChars * 0.5 ? slice.slice(0, lastStop + 1).trimEnd() : slice.trimEnd();
+        warnings.push(`${platform}: caption exceeded ${c.maxChars} chars and was truncated — review before publishing`);
+    }
+    return { caption, warnings };
+}