AutoGPT is the vision of accessible AI for everyone, to use and to build on. Our mission is to provide the tools, so that you can focus on what matters.
import { isValidUUID } from "@/lib/utils";
import type { UIMessage } from "ai";
import { v4 as uuidv4 } from "uuid";
const EXPERT_KICKOFF_KIND = "expert_kickoff";
const KICKOFF_STORAGE_PREFIX = "expert-kickoff-status:";
const LEGACY_MARKER_PATTERN =
/^\[\[EXPERT_KICKOFF:([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\]\](?:\n\n)?/i;
const PENDING_TTL_MS = 2 * 60 * 1000;
// A hire's first turn is an intake, not a first job: the expert says hello and
// asks what the user actually wants before touching anything. Never instruct it
// to start a workflow here — one click on Hire ran a Gmail send (SECRT-2622) —
// so any redesign of this message, including this one, stays ask-first.
const KICKOFF_PROMPT =
"You were just hired. Call expert_onboarding once, and nothing else, this " +
"turn: a one-sentence greeting introducing yourself in your voice, with " +
"no dashes, then " +
"2-3 short questions the user can answer by tapping. Every question and " +
"every option must come from your own role and area of expertise and from " +
"the workflows installed on you — ask which outcome in your area to start " +
"with, and which of the services your work depends on you should be " +
"connected to, naming the real providers rather than asking in the " +
"abstract. Do not ask about work outside your role, whatever else you " +
"know about the user or their team. Do not run a workflow, create a " +
"schedule, or start any other work before the answers come back.";
export interface ExpertKickoffMetadata {
kind: typeof EXPERT_KICKOFF_KIND;
expertId: string;
attemptToken?: KickoffAttemptToken;
}
export interface ExpertKickoffSend {
text: string;
metadata: ExpertKickoffMetadata;
}
export type KickoffStatus = "idle" | "pending" | "done";
export type KickoffAttemptToken = string;
export function buildKickoffMessage(
expertId: string,
attemptToken?: KickoffAttemptToken,
): ExpertKickoffSend {
return {
text: KICKOFF_PROMPT,
metadata: {
kind: EXPERT_KICKOFF_KIND,
expertId,
...(attemptToken ? { attemptToken } : {}),
},
};
}
export function getKickoffExpertIdFromMetadata(
metadata: unknown,
): string | null {
if (!metadata || typeof metadata !== "object") return null;
const value = metadata as Record<string, unknown>;
if (value.kind !== EXPERT_KICKOFF_KIND) return null;
const expertId = value.expertId ?? value.expert_id;
return typeof expertId === "string" && isValidUUID(expertId)
? expertId
: null;
}
export function getKickoffAttemptTokenFromMetadata(
metadata: unknown,
): KickoffAttemptToken | null {
if (!metadata || typeof metadata !== "object") return null;
const value = metadata as Record<string, unknown>;
if (value.kind !== EXPERT_KICKOFF_KIND) return null;
const attemptToken = value.attemptToken;
return typeof attemptToken === "string" &&
attemptToken.length > 0 &&
attemptToken.length <= 128
? attemptToken
: null;
}
export function parseLegacyKickoffExpertId(text: string): string | null {
const match = text.match(LEGACY_MARKER_PATTERN);
return match?.[1] ?? null;
}
export function isKickoffText(text: string): boolean {
return parseLegacyKickoffExpertId(text) !== null;
}
export function stripLegacyKickoffMarker(text: string): string {
return text.replace(LEGACY_MARKER_PATTERN, "");
}
function firstTextPart(message: UIMessage): string | null {
const part = message.parts.find(
(candidate): candidate is Extract<typeof candidate, { type: "text" }> =>
candidate.type === "text",
);
return part?.text ?? null;
}
export function getKickoffExpertId(message: UIMessage): string | null {
if (message.role !== "user") return null;
const metadataExpertId = getKickoffExpertIdFromMetadata(message.metadata);
if (metadataExpertId) return metadataExpertId;
const text = firstTextPart(message);
return text ? parseLegacyKickoffExpertId(text) : null;
}
export function getKickoffAttemptToken(
message: UIMessage,
): KickoffAttemptToken | null {
if (message.role !== "user") return null;
return getKickoffAttemptTokenFromMetadata(message.metadata);
}
export function isKickoffMessage(message: UIMessage): boolean {
return getKickoffExpertId(message) !== null;
}
export function shouldClearKickoffParam(
hasExpertsSettled: boolean,
expertId: string | null,
): boolean {
return hasExpertsSettled && expertId === null;
}
// The kickoff prompt is a control turn the client sends on the user's behalf.
// It reads as an instruction, not as something the user typed, so the thread
// never shows it. The backend marks the persisted row hidden for the same
// reason.
// Returns `messages` itself when there is nothing to hide, so memoised
// consumers keyed on the array see no change.
export function hideKickoffMessages<T extends UIMessage>(messages: T[]): T[] {
if (!messages.some(isKickoffMessage)) return messages;
return messages.filter((message) => !isKickoffMessage(message));
}
export function kickoffStorageKey(userId: string, expertId: string): string {
return `${KICKOFF_STORAGE_PREFIX}${userId}:${expertId}`;
}
function readKickoffStorage(userId: string, expertId: string): string | null {
return window.localStorage.getItem(kickoffStorageKey(userId, expertId));
}
export function getKickoffStatus(
userId: string,
expertId: string,
): KickoffStatus {
if (typeof window === "undefined") return "idle";
try {
const value = readKickoffStorage(userId, expertId);
if (value === null) return "idle";
if (value === "done" || value === "1" || value.startsWith("done:")) {
return "done";
}
if (!value.startsWith("pending:")) return "idle";
const startedAt = Number(value.split(":", 2)[1]);
return Number.isFinite(startedAt) && Date.now() - startedAt < PENDING_TTL_MS
? "pending"
: "idle";
} catch {
return "idle";
}
}
export function markKickoffPending(
userId: string,
expertId: string,
): KickoffAttemptToken {
// uuidv4({}) rather than crypto.randomUUID, which is missing on plain HTTP.
const attemptToken = `${Date.now()}:${uuidv4({})}`;
if (typeof window === "undefined") return attemptToken;
try {
window.localStorage.setItem(
kickoffStorageKey(userId, expertId),
`pending:${attemptToken}`,
);
} catch {
return attemptToken;
}
return attemptToken;
}
export function markKickoffDone(
userId: string,
expertId: string,
attemptToken: KickoffAttemptToken,
): boolean {
if (typeof window === "undefined") return false;
try {
const current = readKickoffStorage(userId, expertId);
const completed = `done:${attemptToken}`;
if (current === completed) return true;
if (current !== `pending:${attemptToken}`) return false;
window.localStorage.setItem(kickoffStorageKey(userId, expertId), completed);
return true;
} catch {
return false;
}
}
export function clearKickoffPending(
userId: string,
expertId: string,
attemptToken: KickoffAttemptToken,
): void {
if (typeof window === "undefined") return;
try {
const value = readKickoffStorage(userId, expertId);
if (value === `pending:${attemptToken}`) {
window.localStorage.removeItem(kickoffStorageKey(userId, expertId));
}
} catch {
return;
}
}
export async function withKickoffLock<T>(
userId: string,
expertId: string,
action: () => Promise<T>,
): Promise<T | undefined> {
if (typeof navigator === "undefined" || !navigator.locks) return action();
return navigator.locks.request(kickoffStorageKey(userId, expertId), action);
}