Enterprise agent platform for building, deploying, and operating AI teammates.
import type { TranslationKey } from "@/i18n/translations";
/** The 8 "what does your team do?" options from the reference onboarding UI
* (onboarding.html's WORK array) - `id` doubles as the value persisted to
* `users.preferences.department` via PATCH /api/auth/me/preferences. */
export type OnboardingWorkId =
| "marketing"
| "sales"
| "support"
| "ops"
| "finance"
| "people"
| "product"
| "other";
export interface OnboardingWorkOption {
id: OnboardingWorkId;
labelKey: TranslationKey;
}
export const ONBOARDING_WORK: OnboardingWorkOption[] = [
{ id: "marketing", labelKey: "onboarding.work.marketing" },
{ id: "sales", labelKey: "onboarding.work.sales" },
{ id: "support", labelKey: "onboarding.work.support" },
{ id: "ops", labelKey: "onboarding.work.ops" },
{ id: "finance", labelKey: "onboarding.work.finance" },
{ id: "people", labelKey: "onboarding.work.people" },
{ id: "product", labelKey: "onboarding.work.product" },
{ id: "other", labelKey: "onboarding.work.other" },
];
/** A goal is a sentence someone would actually say about their week, tied to
* the template that answers it - mirrors onboarding.html's GOALS array
* exactly (id/label/tpl/fn), with `tpl` translated from a display name into
* our real template id. `fn` is the work type it belongs to, used to bring
* the goals matching what the user just said they do to the front of the
* list on the Goals step. */
export interface OnboardingGoal {
id: string;
labelKey: TranslationKey;
templateId: string;
fn: OnboardingWorkId;
}
export const ONBOARDING_GOALS: OnboardingGoal[] = [
{ id: "inbox", labelKey: "onboarding.goal.inbox", templateId: "support-inbox-manager", fn: "support" },
{ id: "social", labelKey: "onboarding.goal.social", templateId: "marketing-social-media-content-manager", fn: "marketing" },
{ id: "meetings", labelKey: "onboarding.goal.meetings", templateId: "sales-meeting-agent", fn: "sales" },
{ id: "support", labelKey: "onboarding.goal.support", templateId: "support-ai-chatbot-agent", fn: "support" },
{ id: "leads", labelKey: "onboarding.goal.leads", templateId: "sales-email-lead-response-agent", fn: "sales" },
{ id: "research", labelKey: "onboarding.goal.research", templateId: "sales-research-enricher", fn: "sales" },
{ id: "docs", labelKey: "onboarding.goal.docs", templateId: "general-doc-summarizer-action-extractor", fn: "ops" },
{ id: "decks", labelKey: "onboarding.goal.decks", templateId: "marketing-collateral-agent", fn: "marketing" },
{ id: "linkedin", labelKey: "onboarding.goal.linkedin", templateId: "marketing-linkedIn-content-manager", fn: "marketing" },
{ id: "ads", labelKey: "onboarding.goal.ads", templateId: "marketing-google-ads-recommendation", fn: "marketing" },
{ id: "kb", labelKey: "onboarding.goal.kb", templateId: "support-kb-writer", fn: "support" },
{ id: "blog", labelKey: "onboarding.goal.blog", templateId: "marketing-content-agent", fn: "marketing" },
];
/** Infer the department from selected jobs instead of asking another question.
* Ties follow catalog order, so toggling the same goals in a different order
* does not change the saved department. */
export function inferWorkFromGoals(selectedGoalIds: string[]): OnboardingWorkId | "" {
const counts = new Map<OnboardingWorkId, number>();
for (const goal of ONBOARDING_GOALS) {
if (selectedGoalIds.includes(goal.id)) {
counts.set(goal.fn, (counts.get(goal.fn) ?? 0) + 1);
}
}
return [...counts].sort((a, b) => b[1] - a[1])[0]?.[0] ?? "";
}
/** Fallback recommendations when selected goals have no available persona.
* Skipping the needs step opens the catalogue directly. */
export const ONBOARDING_FALLBACK_TEMPLATE_IDS = [
"marketing-social-media-content-manager",
"support-inbox-manager",
"sales-meeting-agent",
];
/** The 5 inline voice options on the team step - ids match
* VALID_USER_VOICES/apply_user_voice on the backend (src/xagent/web/api/auth.py,
* src/xagent/web/api/agents.py) exactly; a mismatch here would let someone
* pick a voice this frontend can display but the backend would 422 on save. */
export type OnboardingVoiceId = "professional" | "friendly" | "concise" | "warm" | "playful";
export interface OnboardingVoiceOption {
id: OnboardingVoiceId;
nameKey: TranslationKey;
sayKey: TranslationKey;
}
export const ONBOARDING_VOICES: OnboardingVoiceOption[] = [
{ id: "professional", nameKey: "onboarding.voice.professional.name", sayKey: "onboarding.voice.professional.say" },
{ id: "friendly", nameKey: "onboarding.voice.friendly.name", sayKey: "onboarding.voice.friendly.say" },
{ id: "concise", nameKey: "onboarding.voice.concise.name", sayKey: "onboarding.voice.concise.say" },
{ id: "warm", nameKey: "onboarding.voice.warm.name", sayKey: "onboarding.voice.warm.say" },
{ id: "playful", nameKey: "onboarding.voice.playful.name", sayKey: "onboarding.voice.playful.say" },
];
export const ONBOARDING_DEFAULT_VOICE: OnboardingVoiceId = "professional";
/** Goals reordered so the ones matching the selected work type come first -
* the same twelve options, just resorted (mirrors onboarding.html's
* renderGoals). A stable sort: goals keep their relative order within each
* of the two buckets. */
export function reorderGoalsByWork(work: string): OnboardingGoal[] {
return [...ONBOARDING_GOALS].sort((a, b) => {
const aMatches = a.fn === work ? 0 : 1;
const bMatches = b.fn === work ? 0 : 1;
return aMatches - bMatches;
});
}
export interface RecommendedTemplate {
templateId: string;
/** The goal that recommended this template, for the card's "why" footer -
* null when nothing was picked and this came from the fallback list. */
goalId: string | null;
}
/** Which templates to show on the My team step, and why - a recommendation
* that cannot explain itself is just a default with better manners.
* Deduplicates (one card per template even if multiple goals point to it)
* and preserves ONBOARDING_GOALS' own order (not selection order).
*
* Deliberately NOT capped at 3 here - the caller (page.tsx's
* validRecommended) filters this down to templates that actually loaded
* with a persona first, THEN caps at 3. Capping here, before that filter,
* used to mean a 4th-ranked match with a real persona could never fill a
* slot vacated by a top-3 match that turned out to have none. */
// `catalog`/`fallbackTemplateIds` default to the real data but are
// overridable so a test can prove the templateId-based `seen` dedup below
// actually does something: no two goals in today's real ONBOARDING_GOALS
// share a templateId, so exercising that branch (rather than just the
// filter above collapsing a repeated SELECTED id) needs a synthetic catalog.
export function recommendedTemplates(
selectedGoalIds: string[],
catalog: OnboardingGoal[] = ONBOARDING_GOALS,
fallbackTemplateIds: string[] = ONBOARDING_FALLBACK_TEMPLATE_IDS
): RecommendedTemplate[] {
const picked = catalog.filter((goal) => selectedGoalIds.includes(goal.id));
const seen = new Set<string>();
const out: RecommendedTemplate[] = [];
for (const goal of picked) {
if (seen.has(goal.templateId)) continue;
seen.add(goal.templateId);
out.push({ templateId: goal.templateId, goalId: goal.id });
}
if (out.length === 0) {
for (const templateId of fallbackTemplateIds) {
out.push({ templateId, goalId: null });
}
}
return out;
}
/** "Gmail and Outlook", not "Gmail, Outlook" - the agent is talking, not
* printing a CSV. Matches onboarding.html's andList exactly for English
* (no Oxford comma - Intl.ListFormat's "long" style adds one, which would
* drift from the pixel/copy-matched reference). `and` and `separator` are
* caller-supplied, already-localized strings so this doesn't hardcode
* English/Western punctuation (", ") into otherwise-translated copy - e.g.
* Chinese conventionally uses "、" between list items, not a Latin comma.
* The half-width spaces around `and` itself stay hardcoded even for
* Chinese ("Gmail 和 Slack") - deliberate, not a Western-punctuation leak:
* this is the common CJK typesetting convention (often called "pangu
* spacing") of a thin space between full-width text and an adjacent
* half-width/Latin word. */
export function joinWithAnd(items: string[], and = "and", separator = ", "): string {
if (items.length === 0) return "";
if (items.length === 1) return items[0];
return `${items.slice(0, -1).join(separator)} ${and} ${items[items.length - 1]}`;
}