Genshin Persona

1import type { EngineInterface, Register } from "claude-code";
2
3import { atom, read, update } from "claude-code";
4
5import type { PersonaSpinner, PersonaStatus } from "../types";
6
7import { hashString } from "../src/util/hashString";
8import { CardVerbs } from "./CardVerbs";
9import { VerbDescriptionMap } from "./VerbDescriptionMap";
10
11// The persona's surfaces drawn by the engine itself, so nothing is written into the person's settings: a spinner and
12// A hint of this session's own character, its colour published for the mods, the spoken replies and one command per
13// Verb. Every read of game data, state or audio is the plugin's node scripts, run as commands, since a hooks module
14// Has no Node
15const characterAtom = atom({ key: "character", plugin: "genshin-persona" } as const, {
16  color: "",
17  displayName: "",
18  name: "",
19});
20const isCharacterRecordedAtom = atom({ key: "isCharacterRecorded", plugin: "genshin-persona" } as const, false);
21const spinnerAtom = atom({ key: "spinner", plugin: "genshin-persona" } as const, { label: "", tips: [], verbs: [] });
22const tipIndexAtom = atom({ key: "tipIndex", plugin: "genshin-persona" } as const, 0);
23// The spinner's lines cost the data package or the wiki on a first read, so its script gets the longest run allowed
24const SPINNER_TIMEOUT_MS = Temporal.Duration.from({ minutes: 10 }).total("milliseconds");
25
26const readStateDirectory = async ($: EngineInterface) => {
27  const home = (await $.env.get("HOME")) ?? (await $.env.get("USERPROFILE")) ?? "";
28  return `${home}/.claude/genshin-persona`;
29};
30
31// The session's character, from the record its start hook wrote, else the pin, else the birthday pick; the spinner
32// Is read again only when the character or the language that spells them changed
33const refresh = async ($: EngineInterface) => {
34  const sessionId = await $.session.id();
35  const status = await $.process.run(["node", `${$.plugin.root}/scripts/status.mjs`], {
36    stdin: JSON.stringify({ session_id: sessionId }),
37  });
38  if (!status.stdout.trim()) return;
39  // oxlint-disable-next-line no-restricted-properties -- The plugin's own script prints this shape, with no date in it, and a mod cannot import the shared reviver
40  const { character, isRecorded } = JSON.parse(status.stdout) as PersonaStatus;
41  await update($, isCharacterRecordedAtom, () => isRecorded);
42  const previous = await read($, characterAtom);
43  await update($, characterAtom, () => character);
44  if (previous.name === character.name && previous.displayName === character.displayName) return;
45
46  const spinner = await $.process.run(["node", `${$.plugin.root}/scripts/spinner.mjs`, character.name], {
47    timeoutMs: SPINNER_TIMEOUT_MS,
48  });
49  // oxlint-disable-next-line no-restricted-properties -- The plugin's own script prints this shape, with no date in it, and a mod cannot import the shared reviver
50  if (spinner.stdout.trim()) await update($, spinnerAtom, () => JSON.parse(spinner.stdout) as PersonaSpinner);
51};
52
53// Off the dispatch that asked, so neither the session's start nor a verb's answer waits on a node start
54const refreshLater = ($: EngineInterface) => {
55  $.clock.after(0, () => {
56    // oxlint-disable-next-line typescript/no-floating-promises -- The engine's timer slot takes no promise
57    refresh($);
58  });
59};
60
61export const register: Register = (on) => {
62  on("session.start", async ($, e, next) => {
63    await Promise.all(
64      Object.entries(VerbDescriptionMap).map(([verb, description]) =>
65        $.command.register({ argumentHint: "[name or value]", description, name: `genshin-${verb}` }),
66      ),
67    );
68    refreshLater($);
69    return next(e);
70  });
71
72  // Each verb runs the plugin's own script in this session, which the script reads off the environment, and the
73  // Character it may have switched is read again behind the answer
74  for (const verb of Object.keys(VerbDescriptionMap))
75    on("command.run", { command: `genshin-${verb}` }, async ($, e) => {
76      const sessionId = await $.session.id();
77      const { stderr, stdout } = await $.process.run(
78        ["node", `${$.plugin.root}/scripts/genshin.mjs`, verb, ...e.args.split(" ").filter(Boolean)],
79        { env: { CLAUDE_CODE_SESSION_ID: sessionId } },
80      );
81      refreshLater($);
82      const text = [stdout, stderr].filter(Boolean).join("\n").trim();
83      return CardVerbs.some((cardVerb) => cardVerb === verb)
84        ? { context: ["Answer as the card this printed from this reply on."], text }
85        : { text };
86    });
87
88  // A `/clear` or a resume carries on under another session id with no `session.start` for it, and the start hook
89  // Picks for that id, so the character is unsettled again until its record is read
90  on("session.end", async ($, e, next) => {
91    if (e.reason === "clear" || e.reason === "resume") await update($, isCharacterRecordedAtom, () => false);
92    return next(e);
93  });
94
95  // The character is read again at each turn's start until the start hook's record exists, since the pick may land
96  // After the session start's first read
97  on("turn.start", async ($, e, next) => {
98    if (!(await read($, isCharacterRecordedAtom))) refreshLater($);
99    return next(e);
100  });
101
102  on("turn.complete", async ($, e, next) => {
103    const result = await next(e);
104    if (e.agentId === undefined) await update($, tipIndexAtom, (index) => index + 1);
105    return result;
106  });
107
108  // The engine samples a word per turn; the same word always maps to the same verb of this session's character
109  on("ui.render", { component: "Spinner" }, async ($, e, next) => {
110    const { verbs } = await read($, spinnerAtom);
111    if (verbs.length === 0 || e.props.message !== null) return next(e);
112    const word = verbs[hashString(e.props.word) % verbs.length] ?? e.props.word;
113    return next({ ...e, props: { ...e.props, word } });
114  });
115
116  on("ui.render", { component: "PromptHint" }, async ($, e, next) => {
117    const { label, tips } = await read($, spinnerAtom);
118    const tip = tips[(await read($, tipIndexAtom)) % Math.max(tips.length, 1)];
119    if (!tip || e.props.isDraft) return next(e);
120    else return next({ ...e, props: { ...e.props, tail: `${label}: ${tip}` } });
121  });
122
123  // The character named among the footer's mode labels, where a standing word about the session belongs: the status
124  // Line is a settings command no plugin can set, and a label added to `modes` leaves every other plugin's in place
125  on("ui.render", { component: "SessionMode" }, async ($, e, next) => {
126    const { displayName } = await read($, characterAtom);
127    if (displayName) return next({ ...e, props: { ...e.props, modes: [...e.props.modes, displayName] } });
128    else return next(e);
129  });
130
131  // Every flushed piece of a reply, handed to the speak script as the settings hook handed it; a session with no
132  // Voice set up, or muted, pays a file check and no node start
133  on("classic.MessageDisplay", async ($, e, next) => {
134    const stateDirectory = await readStateDirectory($);
135    const isSpeaking =
136      (await $.fs.exists(`${stateDirectory}/voice-language`)) && !(await $.fs.exists(`${stateDirectory}/muted`));
137    if (isSpeaking) await $.process.run(["node", `${$.plugin.root}/scripts/speak.mjs`], { stdin: JSON.stringify(e) });
138    return next(e);
139  });
140};
141

1// FNV-1a over UTF-16 code units: a few lines, stable across runtimes, and the same seed always lands on the same
2// Candidate, which is all a day's tie-break needs
3const FNV_OFFSET_BASIS = 0x81_1c_9d_c5;
4const FNV_PRIME = 0x01_00_01_93;
5
6export const hashString = (value: string): number => {
7  let hash = FNV_OFFSET_BASIS;
8  for (const character of value) {
9    hash ^= character.codePointAt(0) ?? 0;
10    hash = Math.imul(hash, FNV_PRIME) >>> 0;
11  }
12
13  return hash;
14};
15

1import { GenshinVerb } from "../src/models/GenshinVerb";
2
3// The verbs that print a card, which the model answers as from the reply that relays it
4export const CardVerbs: readonly GenshinVerb[] = [
5  GenshinVerb.Language,
6  GenshinVerb.Pin,
7  GenshinVerb.Unpin,
8  GenshinVerb.Use,
9];
10

1import { GenshinVerb } from "../src/models/GenshinVerb";
2
3// Each verb a person runs, as `/genshin-<verb>`, and what the command menu says of it; the authoring verbs are the
4// `genshin-author` skill's and have no command
5export const VerbDescriptionMap: Partial<Record<GenshinVerb, string>> = {
6  [GenshinVerb.Language]:
7    "Sets the language every word the plugin writes is in, and the reply language with it; given nothing, reports what is set.",
8  [GenshinVerb.Mute]: "Stops replies' spoken lines being read aloud. The pick and the card are unaffected.",
9  [GenshinVerb.Pin]: "Fixes one character for every session until unpinned, this one from this reply on.",
10  [GenshinVerb.Reply]: "Sets the language replies are written in, on its own; given nothing, reports what is set.",
11  [GenshinVerb.Roster]: "Every playable character, one line each.",
12  [GenshinVerb.Status]: "Reports every setting the plugin holds and where each came from. Changes nothing.",
13  [GenshinVerb.Teardown]:
14    "Removes the voice's runtime, weights, references and dub; the picks, the pin and the languages stay.",
15  [GenshinVerb.Today]: "The card of this session's character.",
16  [GenshinVerb.Unmute]: "Lets replies' spoken lines be read aloud again.",
17  [GenshinVerb.Unpin]: "Removes the pin; the pick decides again, for this session from this reply on.",
18  [GenshinVerb.Use]: "Speaks as one character for this session alone, from this reply on.",
19  [GenshinVerb.Voice]:
20    "Sets up spoken replies in the character's own cloned voice, or switches the dub (en, ja, ko or zh); given nothing, reports what is installed.",
21  [GenshinVerb.Volume]: "Sets how loud replies are spoken, as a whole number from 0 to 100.",
22};
23

1export enum GenshinVerb {
2  Language = "language",
3  Lines = "lines",
4  Mute = "mute",
5  Pin = "pin",
6  Reply = "reply",
7  Roster = "roster",
8  Status = "status",
9  Teardown = "teardown",
10  Today = "today",
11  Uncarded = "uncarded",
12  Unmute = "unmute",
13  Unpin = "unpin",
14  Untranslated = "untranslated",
15  Unverbed = "unverbed",
16  Use = "use",
17  Voice = "voice",
18  Volume = "volume",
19}
20
21export const GenshinVerbs: readonly GenshinVerb[] = Object.values(GenshinVerb);
22

1// The plugin's state contract, the one self-contained file the engine validates the hooks module's `$.state` keys
2// Against; the plugin's own scripts print these shapes and import them from here, so each is written once
3// What the hooks module reads of the session's character: the colour the mods draw their accent in, already readable
4// On a dark terminal, and the names a switch compares — the English one the identity, the display one the language's
5export interface PersonaCharacter {
6  // A colour readable on a dark terminal, "" for a character with neither a colour nor an element of their own
7  color: string;
8  displayName: string;
9  name: string;
10}
11
12// Everything the spinner and the prompt hint show for one character. The verbs carry both layers, the base Teyvat
13// Content with the character's own behind it; the tips are the character's lines, shown under their name
14export interface PersonaSpinner {
15  // The character's name as the interface language spells it, in front of every tip
16  label: string;
17  tips: string[];
18  verbs: string[];
19}
20
21// What the status script prints: the character, and whether it is this session's own record rather than the pin or
22// The birthday pick standing in while the start hook is still recording
23export interface PersonaStatus {
24  character: PersonaCharacter;
25  isRecorded: boolean;
26}
27
28declare module "claude-code" {
29  interface PluginState {
30    "genshin-persona": {
31      character: PersonaCharacter;
32      isCharacterRecorded: boolean;
33      spinner: PersonaSpinner;
34      tipIndex: number;
35    };
36  }
37}
38