Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
import { recordLookup } from "../recordLookup";
import { Predicate, Schema } from "effect";
import type { SubscriptionProviderId } from "@akeru/contracts";
import type { BotAvatar, BotBlobShape } from "../roster/types";
import { BLOB_SHAPES, isBotAvatarColor } from "../roster/roster.logic";
import { normalizeDesktopOnboardingGoal } from "./goalPlan.logic";
export const DESKTOP_ONBOARDING_STORAGE_KEY = "akeru:desktop-onboarding:v1";
export const DESKTOP_ONBOARDING_COMPLETED_STORAGE_KEY = "akeru:desktop-onboarding-completed:v1";
export function markDesktopOnboardingCompleted(
storage: Pick<Storage, "removeItem" | "setItem">,
): void {
storage.removeItem(DESKTOP_ONBOARDING_STORAGE_KEY);
storage.setItem(DESKTOP_ONBOARDING_COMPLETED_STORAGE_KEY, "1");
}
/**
* The bot whose chat setup is handing off to. It is written with completion,
* the moment the first message goes out, so a reload mid-handoff neither
* reopens setup (and resends) nor loses the chat the user was being taken to.
*/
export const DESKTOP_ONBOARDING_HANDOFF_STORAGE_KEY = "akeru:desktop-onboarding-handoff:v2";
export const DESKTOP_ONBOARDING_LEGACY_HANDOFF_STORAGE_KEY = "akeru:desktop-onboarding-handoff:v1";
export function markDesktopOnboardingHandoffStarted(
storage: Pick<Storage, "removeItem" | "setItem">,
environmentId: string,
botId: string,
): void {
markDesktopOnboardingCompleted(storage);
storage.removeItem(DESKTOP_ONBOARDING_LEGACY_HANDOFF_STORAGE_KEY);
storage.setItem(DESKTOP_ONBOARDING_HANDOFF_STORAGE_KEY, JSON.stringify({ environmentId, botId }));
}
/** Clears the pending handoff once its chat route has opened. */
export function clearDesktopOnboardingHandoff(storage: Pick<Storage, "removeItem">): void {
storage.removeItem(DESKTOP_ONBOARDING_HANDOFF_STORAGE_KEY);
storage.removeItem(DESKTOP_ONBOARDING_LEGACY_HANDOFF_STORAGE_KEY);
}
/** Reads a pending handoff; the caller clears it after the chat opens. */
export function readDesktopOnboardingHandoff(
storage: Pick<Storage, "getItem">,
): { readonly environmentId: string; readonly botId: string } | null {
const value = storage.getItem(DESKTOP_ONBOARDING_HANDOFF_STORAGE_KEY);
if (!value) return null;
try {
const handoff: unknown = JSON.parse(value);
if (
Predicate.isObjectOrArray(handoff) &&
handoff !== null &&
"environmentId" in handoff &&
Predicate.isString(handoff.environmentId) &&
handoff.environmentId.trim() &&
"botId" in handoff &&
Predicate.isString(handoff.botId) &&
handoff.botId.trim()
) {
return { environmentId: handoff.environmentId, botId: handoff.botId };
}
} catch {
return null;
}
return null;
}
/** Migrates a v1 bot ID only after this environment's loaded roster confirms ownership. */
export function readDesktopOnboardingHandoffForEnvironment(
storage: Pick<Storage, "getItem" | "removeItem" | "setItem">,
environmentId: string,
botIds: ReadonlyArray<string>,
): { readonly environmentId: string; readonly botId: string } | null {
const current = readDesktopOnboardingHandoff(storage);
if (current) return current;
const legacyBotId = storage.getItem(DESKTOP_ONBOARDING_LEGACY_HANDOFF_STORAGE_KEY)?.trim();
if (!legacyBotId) {
storage.removeItem(DESKTOP_ONBOARDING_LEGACY_HANDOFF_STORAGE_KEY);
return null;
}
if (!botIds.includes(legacyBotId)) return null;
const handoff = { environmentId, botId: legacyBotId };
storage.setItem(DESKTOP_ONBOARDING_HANDOFF_STORAGE_KEY, JSON.stringify(handoff));
storage.removeItem(DESKTOP_ONBOARDING_LEGACY_HANDOFF_STORAGE_KEY);
return handoff;
}
export type DesktopOnboardingStep = "subscription" | "goal" | "identity" | "message";
export interface DesktopOnboardingStepDefinition {
readonly id: DesktopOnboardingStep;
/** Rail label. Short enough to sit in a four-up stepper. */
readonly label: string;
}
/** Source of truth for step order: drives the rail, the counter, and stepNumber. */
export const DESKTOP_ONBOARDING_STEPS: readonly DesktopOnboardingStepDefinition[] = [
{ id: "subscription", label: "Connect" },
{ id: "goal", label: "Goal" },
{ id: "identity", label: "Identity" },
{ id: "message", label: "First message" },
];
/**
* Generous enough for a few sentences about work we cannot anticipate, short
* enough that the answer still reads as a goal rather than a brief.
*/
export const DESKTOP_ONBOARDING_GOAL_MAX_LENGTH = 600;
export interface DesktopOnboardingDraft {
readonly step: DesktopOnboardingStep;
readonly providerId: SubscriptionProviderId;
/** What the user wants done, in their words. Empty until they answer. */
readonly goal: string;
readonly goalPhase: "ask" | "plan";
readonly name: string;
readonly avatar: Extract<BotAvatar, { kind: "blob" }>;
readonly botId: string | null;
}
export const DEFAULT_DESKTOP_ONBOARDING_DRAFT: DesktopOnboardingDraft = {
step: "subscription",
providerId: "openai-codex",
goal: "",
goalPhase: "ask",
name: "",
avatar: { kind: "blob", shape: "squircle", color: "#2E8EFF" },
botId: null,
};
function isBlobShape(value: unknown): value is BotBlobShape {
return Predicate.isString(value) && BLOB_SHAPES.some((candidate) => candidate === value);
}
function isBlobColor(value: unknown): value is string {
return isBotAvatarColor(value);
}
const providerIds: readonly SubscriptionProviderId[] = [
"openai-codex",
"anthropic",
"xai",
"kimi-for-coding",
"opencode-go",
];
/**
* Goals recovered from drafts saved while setup asked the user to pick a
* category. Phrased the way someone would answer the question that replaced
* the picker, because the answer is shown back to them and drafts their first
* message. Ids are historical: never reuse one for different work.
*/
const legacyUseCaseGoals = {
build: "Building a software feature",
fix: "Fixing a software bug",
understand: "Understanding a codebase",
automate: "Automating a task I repeat",
inbox: "Triaging my inbox and drafting replies I approve",
documents: "Processing incoming documents and filing them where they belong",
monitoring: "Watching a system and telling me when something changes",
research: "Looking up the same facts and keeping one list current",
routine: "Taking over a routine that eats my week",
} satisfies Readonly<Record<string, string>>;
function isProviderId(value: unknown): value is SubscriptionProviderId {
return Predicate.isString(value) && providerIds.some((candidate) => candidate === value);
}
function isStep(value: unknown): value is DesktopOnboardingStep {
return DESKTOP_ONBOARDING_STEPS.some((step) => step.id === value);
}
/**
* Goal of a saved draft, whichever generation of setup wrote it. A stored
* category still names work the user chose, so it outranks any custom text
* left behind by a choice they moved away from.
*/
function storedGoal(parsed: StoredDraft): string {
if (Predicate.isString(parsed.goal) && parsed.goal.trim().length > 0) return parsed.goal;
const custom = Predicate.isString(parsed.customUseCase) ? parsed.customUseCase : "";
const useCaseId = Predicate.isString(parsed.useCaseId) ? parsed.useCaseId : null;
if (useCaseId !== null && useCaseId !== "custom")
return recordLookup(legacyUseCaseGoals, useCaseId) ?? custom;
return custom;
}
const StoredDraft = Schema.Struct({
step: Schema.optionalKey(Schema.Unknown),
providerId: Schema.optionalKey(Schema.Unknown),
goal: Schema.optionalKey(Schema.Unknown),
goalPhase: Schema.optionalKey(Schema.Unknown),
customUseCase: Schema.optionalKey(Schema.Unknown),
useCaseId: Schema.optionalKey(Schema.Unknown),
name: Schema.optionalKey(Schema.Unknown),
avatar: Schema.optionalKey(
Schema.Struct({
kind: Schema.optionalKey(Schema.Unknown),
shape: Schema.optionalKey(Schema.Unknown),
color: Schema.optionalKey(Schema.Unknown),
}),
),
botId: Schema.optionalKey(Schema.Unknown),
});
type StoredDraft = typeof StoredDraft.Type;
const decodeStoredDraft = Schema.decodeUnknownSync(StoredDraft);
export function parseDesktopOnboardingDraft(value: string | null): DesktopOnboardingDraft | null {
if (value === null) return null;
try {
const parsed = decodeStoredDraft(JSON.parse(value));
const avatar = parsed.avatar;
const step = parsed.step === "use-case" ? "goal" : parsed.step;
const legacy = parsed.step === "use-case" || "useCaseId" in parsed || "customUseCase" in parsed;
const goal = legacy ? normalizeDesktopOnboardingGoal(storedGoal(parsed)) : storedGoal(parsed);
if (
!isStep(step) ||
!isProviderId(parsed.providerId) ||
goal.length > DESKTOP_ONBOARDING_GOAL_MAX_LENGTH ||
!Predicate.isString(parsed.name) ||
parsed.name.length > 80 ||
!avatar ||
avatar.kind !== "blob" ||
!isBlobShape(avatar.shape) ||
!isBlobColor(avatar.color) ||
!(parsed.botId === null || Predicate.isString(parsed.botId))
) {
return null;
}
return {
step,
providerId: parsed.providerId,
goal,
goalPhase:
parsed.goalPhase === "ask" || parsed.goalPhase === "plan"
? parsed.goalPhase
: step === "goal"
? "ask"
: "plan",
name: parsed.name,
avatar: { kind: "blob", shape: avatar.shape, color: avatar.color },
botId: parsed.botId,
};
} catch {
return null;
}
}
/** Reads the in-progress setup draft, or null when none is saved or it no longer parses. */
export function readDesktopOnboardingDraft(
storage: Pick<Storage, "getItem">,
): DesktopOnboardingDraft | null {
return parseDesktopOnboardingDraft(storage.getItem(DESKTOP_ONBOARDING_STORAGE_KEY));
}
export function writeDesktopOnboardingDraft(
storage: Pick<Storage, "setItem">,
draft: DesktopOnboardingDraft,
): void {
storage.setItem(DESKTOP_ONBOARDING_STORAGE_KEY, JSON.stringify(draft));
}