genshin-persona 3.9.0 → 4.1.0

package/.claude-plugin/plugin.json

@@ -8,6 +8,7 @@
   "repository": "https://github.com/Esposter/Esposter",
   "license": "Apache-2.0",
   "keywords": ["genshin", "genshin-impact", "output-style", "persona", "text-to-speech", "voice-cloning"],
+  "types": "./types/index.d.ts",
   "userConfig": {
     "typesafe_key": {
       "type": "string",

package/.mcp.json

@@ -0,0 +1 @@
+{ "mcpServers": { "genshin-persona": { "command": "node", "args": ["${CLAUDE_PLUGIN_ROOT}/scripts/channel.mjs"] } } }

package/README.md

@@ -10,7 +10,7 @@ A Claude Code plugin that gives every session a Genshin Impact character: a repl
 - **A character per session** — picked by the nearest birthday, or by lore through one typed decision when you give it a TypeSafe key; `use` and `pin` override the pick.
 - **A spoken channel, not a persona in the prose** — the character speaks in blockquote lines and nowhere else: one line opening an answer a reader will use, with everything else — the answer, the code, the commit message — a neutral assistant's, and the whole reply when the ask was the character's.
 - **Read aloud as it is written** — a hook hands each spoken line to a resident synthesizer the moment its line lands, and the line is read in the character's cloned voice while the reply is still streaming; the engine is warmed at the session start so the first reply pays no load.
-- **Localized** — the card, the spinner, the status line and every line the plugin prints in the language you set, and replies in the one you choose.
+- **Localized** — the card, the spinner, the prompt hint and every line the plugin prints in the language you set, and replies in the one you choose.
 
 ## Table of Contents
 
@@ -22,7 +22,7 @@ A Claude Code plugin that gives every session a Genshin Impact character: a repl
 
 ## <a name="getting-started">🚀 Getting Started</a>
 
-This repository is a Claude Code plugin marketplace named `esposter`, and this package is its one plugin:
+This repository is a Claude Code plugin marketplace named `esposter`:
 
 ```bash
 claude plugin marketplace add Esposter/Esposter
@@ -44,15 +44,15 @@ claude plugin disable genshin-persona@esposter
 claude --plugin-dir packages/genshin-persona
 ```
 
-Nobody switches that on: `.agents/settings.json` declares `autoUpdate` on the marketplace it declares, and Claude Code leaves it off for every marketplace but Anthropic's own. A checkout therefore re-pins its own plugin to its own current commit on startup, and `/plugin`'s **Enable auto-update** reports the value as settings' rather than offering to change it. An update still moves a pin to a commit, so work that is not committed is not loaded, whatever the toggle says. Nothing below is repeated for an update: the state directory's launchers re-aim at the running copy at every session start, and the voice's runtime and weights are kept until the copy carries a newer lockfile or engine, which `voice` with no argument reports and `voice <dub>` run again picks up, installing only what changed.
+Nobody switches that on: `.agents/settings.json` declares `autoUpdate` on the marketplace it declares, and Claude Code leaves it off for every marketplace but Anthropic's own. A checkout therefore re-pins its own plugin to its own current commit on startup, and `/plugin`'s **Enable auto-update** reports the value as settings' rather than offering to change it. An update still moves a pin to a commit, so work that is not committed is not loaded, whatever the toggle says. Nothing below is repeated for an update: the plugin writes nothing into your settings, so every surface it draws comes from the running copy, and the voice's runtime and weights are kept until the copy carries a newer lockfile or engine, which `voice` with no argument reports and `voice <dub>` run again picks up, installing only what changed.
 
 Spoken lines stay silent until the `voice` verb has set the engine up, once, with the dub the reference lines are taken from — `en`, `ja`, `ko` or `zh`:
 
 ```bash
-node "<plugin root>/scripts/genshin.ts" voice ja     # or: /genshin-persona:voice ja
+node "<plugin root>/scripts/genshin.mjs" voice ja     # or: /genshin-voice ja
 ```
 
-It installs the engine's runtime and weights — about a gigabyte, once — into the plugin's own state directory under `~/.claude/genshin-persona`, ends by speaking one sentence as the session's character, and writes the hook that reads each reply's spoken lines into your user settings, which Claude Code reads once per process, so replies are read from the next session. Each character is read in a clone of their own voice, conditioned on one line of their performance fetched from the community wiki the first time they are picked; nothing lifted from the game ships with the plugin. How the engine runs, which device it settles on and why, and what it does when it cannot speak is the [spoken replies](https://esposter.com/docs/infra/claude-interface/spoken-replies) page.
+It installs the engine's runtime and weights — about a gigabyte, once — into the plugin's own state directory under `~/.claude/genshin-persona`, and ends by speaking one sentence as the session's character; replies are read aloud from the next reply on, by the plugin's own hooks module, with nothing written into your settings. Each character is read in a clone of their own voice, conditioned on one line of their performance fetched from the community wiki the first time they are picked; nothing lifted from the game ships with the plugin. How the engine runs, which device it settles on and why, and what it does when it cannot speak is the [spoken replies](https://esposter.com/docs/infra/claude-interface/spoken-replies) page.
 
 A [TypeSafe](https://typesafe.ai) API key, given as an option, turns the pick over to lore — one typed decision over the whole roster, weighing the date, the season's festivals and your moment — instead of the nearest birthday. The key is sensitive, and the variable the SDK itself reads, `TYPESAFE_API_KEY`, is honoured when the option is empty:
 
@@ -66,31 +66,30 @@ We highly recommend you take a look at the [documentation](https://esposter.com/
 
 ### Command reference
 
-Every command is a slash command in Claude Code and the same verb of the plugin's script from any shell; the script form is what a hook, a terminal or another tool runs, and the two never differ:
+Every command is a slash command in Claude Code, `/genshin-` and the verb, which the plugin's hooks module registers at session start, and the same verb of the plugin's script from any shell; the script form is what a hook, a terminal or another tool runs, and the two never differ:
 
 ```bash
-/genshin-persona:<verb> [argument]
-node "<plugin root>/scripts/genshin.ts" <verb> [argument]
+/genshin-<verb> [argument]
+node "<plugin root>/scripts/genshin.mjs" <verb> [argument]
 ```
 
 A `<name>` is a character's, matched whole and ignoring case, in English or as the interface language spells it. A `[language]` is one the `language` verb lists, typed in English or in its own words. A verb given a name the roster has no character by, or an argument outside its set, prints why and exits 1; a verb with no argument where one is optional reports instead of changing anything.
 
-| Verb       | Argument                 | What it does                                                                                                                                                                                                                                                                    |
-| :--------- | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `today`    | —                        | Prints the card of this session's character; from a shell, of the pinned character, else of a fresh pick. A pin naming nobody in the roster is reported and ignored.                                                                                                            |
-| `roster`   | —                        | Every playable character, one line each: name, title, element, region, birthday and the patch that introduced them.                                                                                                                                                             |
-| `use`      | `<name>`                 | Speaks as one character for this session alone, from that reply on; other sessions and the next start are untouched. From a shell, where no session is running, exits 1.                                                                                                        |
-| `pin`      | `<name>`                 | Fixes one character for every session until unpinned, and for this session from that reply on.                                                                                                                                                                                  |
-| `unpin`    | —                        | Removes the pin; the pick decides again from the next session, and for this session from that reply on.                                                                                                                                                                         |
-| `voice`    | `[en \| ja \| ko \| zh]` | Sets up spoken lines in that dub — installing the engine's runtime and weights on the first run, about a gigabyte — ends by speaking one sentence, and writes the hook that reads each reply into user settings, on from the next session. With no dub, reports what is set up. |
-| `mute`     | —                        | Stops replies' spoken lines being read aloud. The pick and the card are unaffected.                                                                                                                                                                                             |
-| `unmute`   | —                        | Lets replies' spoken lines be read aloud again.                                                                                                                                                                                                                                 |
-| `volume`   | `<0–100>`                | Sets how loud replies are spoken, as a whole number, from the next reply on; `0` is silence the engine is not woken for.                                                                                                                                                        |
-| `language` | `[language]`             | Sets the interface language — every word the plugin writes — and carries the reply language with it. With none, reports what is set and lists the languages on offer.                                                                                                           |
-| `reply`    | `[language]`             | Sets the language replies are written in, on its own. With none, reports what is set and whether it was set or cascaded from the interface language.                                                                                                                            |
-| `status`   | —                        | Reports every setting at once and where each value came from. Changes nothing.                                                                                                                                                                                                  |
-| `setup`    | —                        | Writes the status line and the spinner into user settings, the spinner under this session's character.                                                                                                                                                                          |
-| `teardown` | —                        | Removes exactly what `setup` and `voice` wrote: the three settings, and the voice's runtime, weights, cached clips and dub.                                                                                                                                                     |
+| Verb       | Argument                 | What it does                                                                                                                                                                                                                         |
+| :--------- | :----------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `today`    | —                        | Prints the card of this session's character; from a shell, of the pinned character, else of a fresh pick. A pin naming nobody in the roster is reported and ignored.                                                                 |
+| `roster`   | —                        | Every playable character, one line each: name, title, element, region, birthday and the patch that introduced them.                                                                                                                  |
+| `use`      | `<name>`                 | Speaks as one character for this session alone, from that reply on; other sessions and the next start are untouched. From a shell, where no session is running, exits 1.                                                             |
+| `pin`      | `<name>`                 | Fixes one character for every session until unpinned, and for this session from that reply on.                                                                                                                                       |
+| `unpin`    | —                        | Removes the pin; the pick decides again from the next session, and for this session from that reply on.                                                                                                                              |
+| `voice`    | `[en \| ja \| ko \| zh]` | Sets up spoken lines in that dub — installing the engine's runtime and weights on the first run, about a gigabyte — and ends by speaking one sentence; replies are read from the next reply on. With no dub, reports what is set up. |
+| `mute`     | —                        | Stops replies' spoken lines being read aloud. The pick and the card are unaffected.                                                                                                                                                  |
+| `unmute`   | —                        | Lets replies' spoken lines be read aloud again.                                                                                                                                                                                      |
+| `volume`   | `<0–100>`                | Sets how loud replies are spoken, as a whole number, from the next reply on; `0` is silence the engine is not woken for.                                                                                                             |
+| `language` | `[language]`             | Sets the interface language — every word the plugin writes — and carries the reply language with it. With none, reports what is set and lists the languages on offer.                                                                |
+| `reply`    | `[language]`             | Sets the language replies are written in, on its own. With none, reports what is set and whether it was set or cascaded from the interface language.                                                                                 |
+| `status`   | —                        | Reports every setting at once and where each value came from. Changes nothing.                                                                                                                                                       |
+| `teardown` | —                        | Removes what `voice` installed: the runtime, the weights, the cached clips and the dub. The picks, the pin and the languages stay; `voice` brings spoken lines back.                                                                 |
 
 Four more are the authoring queues of one more skill, `genshin-author` — script-only and on no menu:
 
@@ -103,38 +102,38 @@ Four more are the authoring queues of one more skill, `genshin-author` — scrip
 
 ### What it ships
 
-| Component                              | Role                                                                                                                                                                                                                          |
-| :------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `hooks/hooks.json`                     | A session-start hook that picks the character, greets you with its name, what the pick weighed and who is close, and prints its card as context. The hook that reads a reply's spoken lines is a user setting `voice` writes. |
-| `output-styles/in-character.md`        | The standing rules, forced on while the plugin is enabled: a blockquote line is the character's spoken line, the ask decides how much of a reply that is, and the rest is plain.                                              |
-| `skills/<verb>/SKILL.md`               | One slash command per verb, `/genshin-persona:<verb>` — the command reference above — yours to invoke.                                                                                                                        |
-| `skills/genshin/SKILL.md`              | The model's route from a request in words to one of those verbs; hidden from the menu.                                                                                                                                        |
-| `skills/genshin-author/SKILL.md`       | How a persona card and its spinner verbs are written, the command that prints a character's own lines to write from, and the two queues.                                                                                      |
-| `src/personaCards/`                    | Authored persona cards, one typed module per character, in our words: how the character speaks for the model, their spinner verbs for you, and the reference line only where an ear chose one.                                |
-| `src/generated/PersonaReferenceMap.ts` | The measured reference line and its likeness per character, one generated map written by the repository's reference selection and never by hand.                                                                              |
-| `runtime/`                             | The manifest and lockfile of the speech engine's runtime, which the `voice` verb installs into the state directory rather than the plugin carrying it.                                                                        |
-| `src/localizations/`                   | One authored module per language for the words the data package does not carry: the base Teyvat verbs, each character's spinner gerunds, and every line the verbs print.                                                      |
-| `scripts/`                             | The hook entrypoints, the commands' script, the status-line script, the spinner rewrite and the resident synthesizer, TypeScript run directly by node.                                                                        |
+| Component                              | Role                                                                                                                                                                                                                                          |
+| :------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `hooks/hooks.json`                     | A session-start hook that picks the character, greets you with its name, what the pick weighed and who is close, and prints its card as context, and the hooks module beside it.                                                              |
+| `mod/`                                 | The hooks module: the spinner's verbs and the prompt hint's tips of this session's character, the spoken replies, and one slash command per verb.                                                                                             |
+| `types/index.d.ts`                     | The state the hooks module publishes — the session's character and its colour — which other plugins draw by.                                                                                                                                  |
+| `output-styles/in-character.md`        | The standing rules, forced on while the plugin is enabled: a blockquote line is the character's spoken line, the ask decides how much of a reply that is, and the rest is plain.                                                              |
+| `skills/genshin/SKILL.md`              | The model's route from a request in words to one of the verbs; hidden from the menu.                                                                                                                                                          |
+| `skills/genshin-author/SKILL.md`       | How a persona card and its spinner verbs are written, the command that prints a character's own lines to write from, and the two queues.                                                                                                      |
+| `src/personaCards/`                    | Authored persona cards, one typed module per character, in our words: how the character speaks for the model, their spinner verbs for you, and the reference line only where an ear chose one.                                                |
+| `src/generated/PersonaReferenceMap.ts` | The measured reference line and its likeness per character, one generated map written by the repository's reference selection and never by hand.                                                                                              |
+| `runtime/`                             | The manifest and lockfile of the speech engine's runtime, which the `voice` verb installs into the state directory rather than the plugin carrying it.                                                                                        |
+| `src/localizations/`                   | One authored module per language for the words the data package does not carry: the base Teyvat verbs, each character's spinner gerunds, and every line the verbs print.                                                                      |
+| `scripts/`                             | The session-start hook, the commands' script, the character and spinner the hooks module reads, the status line a person can name in their settings, and the resident synthesizer, each an `.mjs` that registers `tsx` before its TypeScript. |
 
-### Status line and spinner
+### Spinner and prompt hint
 
-A plugin cannot ship a status line, spinner verbs or spinner tips, so one command writes them into your user settings, and its twin removes them:
+Nothing to set up: the hooks module turns the spinner's words into the session's character's verbs and the prompt hint into one of their lines under their name, a new one each turn, names the character among the labels at the right of the prompt's footer, and publishes the character's colour, which [`genshin-mods`](https://github.com/Esposter/Esposter/tree/main/packages/genshin-mods) draws its band in. Each session draws its own character, and a switch shows at once. Why each is shaped as it is: the [persona plugin](https://esposter.com/docs/infra/claude-interface/persona-plugin) page.
 
-```bash
-node "<plugin root>/scripts/genshin.ts" setup      # or: /genshin-persona:setup
-node "<plugin root>/scripts/genshin.ts" teardown
-```
+The plugin writes nothing into your settings, so your own status line stays yours. To have it show the character's nameplate, the name in their colour on a badge of that colour's tone, point it at the script the plugin ships:
 
-The status line prints the session's character in their own colour, on a badge of its tone, from the plugin's state files alone, and the spinner shows the character's own verbs and lines under their name. Both follow a plugin update on the next session, and the spinner follows a change of character on the next session too, since Claude Code reads its keys once per process. Why each is shaped as it is: the [persona plugin](https://esposter.com/docs/infra/claude-interface/persona-plugin) page.
+```json
+{ "statusLine": { "command": "node \"<plugin root>/scripts/statusLine.mjs\"", "type": "command" } }
+```
 
 ### Languages
 
 Three settings, and they are not one axis: the **interface language** is every word the plugin writes and the master toggle, the **reply language** is what the model writes in and follows the interface language until set on its own, and the **dub** says whose voice reads a line and is neither, because it comes from a set of four and costs an install:
 
 ```bash
-node "<plugin root>/scripts/genshin.ts" language japanese   # or: /genshin-persona:language japanese
-node "<plugin root>/scripts/genshin.ts" reply english       # labels in one language, prose in another
-node "<plugin root>/scripts/genshin.ts" status              # every setting, and where each value came from
+node "<plugin root>/scripts/genshin.mjs" language japanese   # or: /genshin-language japanese
+node "<plugin root>/scripts/genshin.mjs" reply english       # labels in one language, prose in another
+node "<plugin root>/scripts/genshin.mjs" status              # every setting, and where each value came from
 ```
 
 The languages on offer are the data package's, so `language` with no argument lists them, each in its own words beside the word you type for it, and either resolves. What arrives localized for nothing and what is written by hand per language is the [persona plugin](https://esposter.com/docs/infra/claude-interface/persona-plugin) page's.
@@ -148,7 +147,7 @@ Every playable character comes from the game-data dependency — no generated ro
 `use <name>` makes this session speak as one character from that reply on; `pin <name>` fixes one for every session from the next start and this one at once; `unpin` hands both back to the pick:
 
 ```bash
-node "<plugin root>/scripts/genshin.ts" use furina      # or: /genshin-persona:use furina
+node "<plugin root>/scripts/genshin.mjs" use furina      # or: /genshin-use furina
 ```
 
 ### Spoken lines
@@ -156,10 +155,10 @@ node "<plugin root>/scripts/genshin.ts" use furina      # or: /genshin-persona:u
 A reply to an ask of the assistant opens with one blockquote line in the character's voice and may close with one; a reply to an ask of the character — a joke, a hello, an opinion, however much was pasted to form it — is such lines and nothing else, as many as the ask deserves, a list of them included. A hook hands each piece of the reply to a resident synthesizer as it lands, which reads the lines in the order they were written, in the character's cloned voice, while the reply is still being written. `mute` and `unmute` decide whether the hook asks it at all, and so does a `volume` of zero. `volume <number>` is a whole number from 0 to 100, applied as a gain, from the next reply on:
 
 ```bash
-node "<plugin root>/scripts/genshin.ts" volume 60     # or: /genshin-persona:volume 60
+node "<plugin root>/scripts/genshin.mjs" volume 60     # or: /genshin-volume 60
 ```
 
-`teardown` removes the runtime, the weights, the cached clips, the dub and the hook along with the status line and spinner settings.
+`teardown` removes the runtime, the weights, the cached clips and the dub, and spoken lines stay silent until `voice` sets them up again.
 
 ### Commands
 

package/hooks/hooks.json

@@ -1,5 +1,6 @@
 {
   "hooks": {
     "SessionStart": [{ "hooks": [{ "type": "command", "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/pick.mjs\"" }] }]
-  }
+  },
+  "modules": ["../mod/register.ts"]
 }

package/mod/CardVerbs.ts

@@ -0,0 +1,9 @@
+import { GenshinVerb } from "../src/models/GenshinVerb";
+
+// The verbs that print a card, which the model answers as from the reply that relays it
+export const CardVerbs: readonly GenshinVerb[] = [
+  GenshinVerb.Language,
+  GenshinVerb.Pin,
+  GenshinVerb.Unpin,
+  GenshinVerb.Use,
+];

package/mod/VerbDescriptionMap.ts

@@ -0,0 +1,22 @@
+import { GenshinVerb } from "../src/models/GenshinVerb";
+
+// Each verb a person runs, as `/genshin-<verb>`, and what the command menu says of it; the authoring verbs are the
+// `genshin-author` skill's and have no command
+export const VerbDescriptionMap: Partial<Record<GenshinVerb, string>> = {
+  [GenshinVerb.Language]:
+    "Sets the language every word the plugin writes is in, and the reply language with it; given nothing, reports what is set.",
+  [GenshinVerb.Mute]: "Stops replies' spoken lines being read aloud. The pick and the card are unaffected.",
+  [GenshinVerb.Pin]: "Fixes one character for every session until unpinned, this one from this reply on.",
+  [GenshinVerb.Reply]: "Sets the language replies are written in, on its own; given nothing, reports what is set.",
+  [GenshinVerb.Roster]: "Every playable character, one line each.",
+  [GenshinVerb.Status]: "Reports every setting the plugin holds and where each came from. Changes nothing.",
+  [GenshinVerb.Teardown]:
+    "Removes the voice's runtime, weights, references and dub; the picks, the pin and the languages stay.",
+  [GenshinVerb.Today]: "The card of this session's character.",
+  [GenshinVerb.Unmute]: "Lets replies' spoken lines be read aloud again.",
+  [GenshinVerb.Unpin]: "Removes the pin; the pick decides again, for this session from this reply on.",
+  [GenshinVerb.Use]: "Speaks as one character for this session alone, from this reply on.",
+  [GenshinVerb.Voice]:
+    "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.",
+  [GenshinVerb.Volume]: "Sets how loud replies are spoken, as a whole number from 0 to 100.",
+};

package/mod/register.ts

@@ -0,0 +1,140 @@
+import type { EngineInterface, Register } from "claude-code";
+
+import { atom, read, update } from "claude-code";
+
+import type { PersonaSpinner, PersonaStatus } from "../types";
+
+import { hashString } from "../src/util/hashString";
+import { CardVerbs } from "./CardVerbs";
+import { VerbDescriptionMap } from "./VerbDescriptionMap";
+
+// The persona's surfaces drawn by the engine itself, so nothing is written into the person's settings: a spinner and
+// A hint of this session's own character, its colour published for the mods, the spoken replies and one command per
+// Verb. Every read of game data, state or audio is the plugin's node scripts, run as commands, since a hooks module
+// Has no Node
+const characterAtom = atom({ key: "character", plugin: "genshin-persona" } as const, {
+  color: "",
+  displayName: "",
+  name: "",
+});
+const isCharacterRecordedAtom = atom({ key: "isCharacterRecorded", plugin: "genshin-persona" } as const, false);
+const spinnerAtom = atom({ key: "spinner", plugin: "genshin-persona" } as const, { label: "", tips: [], verbs: [] });
+const tipIndexAtom = atom({ key: "tipIndex", plugin: "genshin-persona" } as const, 0);
+// The spinner's lines cost the data package or the wiki on a first read, so its script gets the longest run allowed
+const SPINNER_TIMEOUT_MS = Temporal.Duration.from({ minutes: 10 }).total("milliseconds");
+
+const readStateDirectory = async ($: EngineInterface) => {
+  const home = (await $.env.get("HOME")) ?? (await $.env.get("USERPROFILE")) ?? "";
+  return `${home}/.claude/genshin-persona`;
+};
+
+// The session's character, from the record its start hook wrote, else the pin, else the birthday pick; the spinner
+// Is read again only when the character or the language that spells them changed
+const refresh = async ($: EngineInterface) => {
+  const sessionId = await $.session.id();
+  const status = await $.process.run(["node", `${$.plugin.root}/scripts/status.mjs`], {
+    stdin: JSON.stringify({ session_id: sessionId }),
+  });
+  if (!status.stdout.trim()) return;
+  // 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
+  const { character, isRecorded } = JSON.parse(status.stdout) as PersonaStatus;
+  await update($, isCharacterRecordedAtom, () => isRecorded);
+  const previous = await read($, characterAtom);
+  await update($, characterAtom, () => character);
+  if (previous.name === character.name && previous.displayName === character.displayName) return;
+
+  const spinner = await $.process.run(["node", `${$.plugin.root}/scripts/spinner.mjs`, character.name], {
+    timeoutMs: SPINNER_TIMEOUT_MS,
+  });
+  // 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
+  if (spinner.stdout.trim()) await update($, spinnerAtom, () => JSON.parse(spinner.stdout) as PersonaSpinner);
+};
+
+// Off the dispatch that asked, so neither the session's start nor a verb's answer waits on a node start
+const refreshLater = ($: EngineInterface) => {
+  $.clock.after(0, () => {
+    // oxlint-disable-next-line typescript/no-floating-promises -- The engine's timer slot takes no promise
+    refresh($);
+  });
+};
+
+export const register: Register = (on) => {
+  on("session.start", async ($, e, next) => {
+    await Promise.all(
+      Object.entries(VerbDescriptionMap).map(([verb, description]) =>
+        $.command.register({ argumentHint: "[name or value]", description, name: `genshin-${verb}` }),
+      ),
+    );
+    refreshLater($);
+    return next(e);
+  });
+
+  // Each verb runs the plugin's own script in this session, which the script reads off the environment, and the
+  // Character it may have switched is read again behind the answer
+  for (const verb of Object.keys(VerbDescriptionMap))
+    on("command.run", { command: `genshin-${verb}` }, async ($, e) => {
+      const sessionId = await $.session.id();
+      const { stderr, stdout } = await $.process.run(
+        ["node", `${$.plugin.root}/scripts/genshin.mjs`, verb, ...e.args.split(" ").filter(Boolean)],
+        { env: { CLAUDE_CODE_SESSION_ID: sessionId } },
+      );
+      refreshLater($);
+      const text = [stdout, stderr].filter(Boolean).join("\n").trim();
+      return CardVerbs.some((cardVerb) => cardVerb === verb)
+        ? { context: ["Answer as the card this printed from this reply on."], text }
+        : { text };
+    });
+
+  // A `/clear` or a resume carries on under another session id with no `session.start` for it, and the start hook
+  // Picks for that id, so the character is unsettled again until its record is read
+  on("session.end", async ($, e, next) => {
+    if (e.reason === "clear" || e.reason === "resume") await update($, isCharacterRecordedAtom, () => false);
+    return next(e);
+  });
+
+  // The character is read again at each turn's start until the start hook's record exists, since the pick may land
+  // After the session start's first read
+  on("turn.start", async ($, e, next) => {
+    if (!(await read($, isCharacterRecordedAtom))) refreshLater($);
+    return next(e);
+  });
+
+  on("turn.complete", async ($, e, next) => {
+    const result = await next(e);
+    if (e.agentId === undefined) await update($, tipIndexAtom, (index) => index + 1);
+    return result;
+  });
+
+  // The engine samples a word per turn; the same word always maps to the same verb of this session's character
+  on("ui.render", { component: "Spinner" }, async ($, e, next) => {
+    const { verbs } = await read($, spinnerAtom);
+    if (verbs.length === 0 || e.props.message !== null) return next(e);
+    const word = verbs[hashString(e.props.word) % verbs.length] ?? e.props.word;
+    return next({ ...e, props: { ...e.props, word } });
+  });
+
+  on("ui.render", { component: "PromptHint" }, async ($, e, next) => {
+    const { label, tips } = await read($, spinnerAtom);
+    const tip = tips[(await read($, tipIndexAtom)) % Math.max(tips.length, 1)];
+    if (!tip || e.props.isDraft) return next(e);
+    else return next({ ...e, props: { ...e.props, tail: `${label}: ${tip}` } });
+  });
+
+  // The character named among the footer's mode labels, where a standing word about the session belongs: the status
+  // Line is a settings command no plugin can set, and a label added to `modes` leaves every other plugin's in place
+  on("ui.render", { component: "SessionMode" }, async ($, e, next) => {
+    const { displayName } = await read($, characterAtom);
+    if (displayName) return next({ ...e, props: { ...e.props, modes: [...e.props.modes, displayName] } });
+    else return next(e);
+  });
+
+  // Every flushed piece of a reply, handed to the speak script as the settings hook handed it; a session with no
+  // Voice set up, or muted, pays a file check and no node start
+  on("classic.MessageDisplay", async ($, e, next) => {
+    const stateDirectory = await readStateDirectory($);
+    const isSpeaking =
+      (await $.fs.exists(`${stateDirectory}/voice-language`)) && !(await $.fs.exists(`${stateDirectory}/muted`));
+    if (isSpeaking) await $.process.run(["node", `${$.plugin.root}/scripts/speak.mjs`], { stdin: JSON.stringify(e) });
+    return next(e);
+  });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genshin-persona",
-  "version": "3.9.0",
+  "version": "4.1.0",
   "description": "A Claude Code plugin that speaks as the Genshin Impact character whose birthday is nearest: an answer opens with one spoken line in the character's voice and the rest is plain, a joke or a hello is spoken whole, and every line is read aloud in the character's own cloned voice as the reply is written.",
   "keywords": [
     "claude-code",
@@ -24,19 +24,24 @@
   },
   "files": [
     ".claude-plugin",
+    ".mcp.json",
     "hooks",
     "output-styles",
     "runtime",
     "scripts",
     "skills",
+    "mod",
     "src",
-    "!src/**/*.test.ts"
+    "types",
+    "!**/*.test.ts",
+    "!.claude-plugin/types"
   ],
   "type": "module",
   "imports": {
     "#src/*": "./src/*.ts",
     "#src/*.json": "./src/*.json",
-    "#scripts/*": "./scripts/*.ts"
+    "#scripts/*": "./scripts/*.ts",
+    "#types": "./types/index.d.ts"
   },
   "publishConfig": {
     "access": "public"
@@ -50,6 +55,7 @@
     "typecheck": "tsc"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@typesafe-ai/sdk": "^0.6.0",
     "@wasm-audio-decoders/ogg-vorbis": "^0.1.20",
     "citty": "^0.2.2",
@@ -57,7 +63,7 @@
     "tsx": "^4.23.15"
   },
   "engines": {
-    "node": ">=26.10.0"
+    "node": ">=26.11.1"
   },
-  "gitHead": "f9f6208c35e6cff4ed33910623c798cd88f09301"
+  "gitHead": "68de4c22fa7591bf6f6cc0fab2c9a906d8c4d71a"
 }

package/runtime/package-lock.json

@@ -6,7 +6,7 @@
     "": {
       "name": "genshin-persona-runtime",
       "dependencies": {
-        "@huggingface/transformers": "^4.3.0"
+        "@huggingface/transformers": "^4.3.1"
       }
     },
     "node_modules/@emnapi/runtime": {
@@ -35,9 +35,9 @@
       "license": "Apache-2.0"
     },
     "node_modules/@huggingface/transformers": {
-      "version": "4.3.0",
-      "resolved": "https://registry.npmjs.org/@huggingface/transformers/-/transformers-4.3.0.tgz",
-      "integrity": "sha512-fL1A/WUZwouPrOlYxU5dzIwD2T5J781JiB2jDR8bFe5DwCj0Gfudq+NEXCMno49kQgajHA7xQkrRLJlqG1veEA==",
+      "version": "4.3.1",
+      "resolved": "https://registry.npmjs.org/@huggingface/transformers/-/transformers-4.3.1.tgz",
+      "integrity": "sha512-5+voSeUCFK6PCKlY15dPhNOKq3/zOTxDN7oC+Wy9dFb1QZ0TSQomZRRy7URRK8YRuUoE9fGMQTTPC5d/pWBJhA==",
       "license": "Apache-2.0",
       "dependencies": {
         "@huggingface/jinja": "^0.5.10",
@@ -653,9 +653,9 @@
       "license": "BSD-3-Clause"
     },
     "node_modules/@types/node": {
-      "version": "26.6.3",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.3.tgz",
-      "integrity": "sha512-dsqMQQoeTLqu9wynDD00q573mNzso3IdQOAfHRJqLCcmCFPoGo9A1bDpUcv/9tnKpErQWv9uKeGfl37EIS02Yg==",
+      "version": "26.6.4",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-26.6.4.tgz",
+      "integrity": "sha512-ldVPDCzj7fsaGZrLB0NuHuTvJcsNasysBAqMolr/cgxrLd1xbqxIr3XJiPnHHJUCxj5sNF1vnRj9aWnrVh5Jcg==",
       "license": "MIT",
       "dependencies": {
         "undici-types": "~8.9.0"

package/runtime/package.json

@@ -3,6 +3,6 @@
   "private": true,
   "description": "The persona plugin's speech engine runtime, installed by its voice verb into the plugin's state directory rather than shipped with the plugin.",
   "dependencies": {
-    "@huggingface/transformers": "^4.3.0"
+    "@huggingface/transformers": "^4.3.1"
   }
 }

package/scripts/channel.mjs

@@ -0,0 +1,5 @@
+// Node strips types and takes no `enum`, so the entry registers tsx before it loads its TypeScript
+import { register } from "tsx/esm/api";
+
+register();
+await import("#scripts/channel");

package/scripts/channel.ts

@@ -0,0 +1,98 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+
+import { checkIsChannelRequestAllowed } from "#src/services/checkIsChannelRequestAllowed";
+import { createChannelPage } from "#src/services/createChannelPage";
+import { readChannelLine } from "#src/services/readChannelLine";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+
+// The chat window's MCP server, started with the session over stdio. It serves the page on the loopback under a token
+// Printed once to the terminal, takes typed lines into the session as channel events, and offers the reply tool that
+// Sends the plain half of an answer back to the page. The character's spoken lines need no forwarding: the message
+// Display hook already reads them to the viewer
+const token = randomBytes(16).toString("hex");
+const replyStreams = new Set<ServerResponse>();
+
+// The low-level Server keeps the raw request handlers and the channel notification, which McpServer's tool API does not expose
+// oxlint-disable-next-line typescript/no-deprecated -- see the comment above
+const mcp = new Server(
+  { name: "genshin-persona", version: "4.0.0" },
+  {
+    capabilities: { experimental: { "claude/channel": {} }, tools: {} },
+    instructions:
+      'Lines typed at the desk arrive as <channel source="genshin-persona" sender="desk">. The character\'s spoken lines already reach the viewer, so do not forward them. When a desk line asks something, also call the reply tool with the plain half of the answer; the desk reads it on the chat page.',
+  },
+);
+
+mcp.setRequestHandler(ListToolsRequestSchema, () => ({
+  tools: [
+    {
+      description: "Show the plain half of an answer to a line typed at the desk on the chat page",
+      inputSchema: { properties: { text: { type: "string" } }, required: ["text"], type: "object" },
+      name: "reply",
+    },
+  ],
+}));
+
+mcp.setRequestHandler(CallToolRequestSchema, (request) => {
+  // oxlint-disable-next-line error-handling/no-bare-error -- an unlisted tool name is the SDK's own error to report to the caller
+  if (request.params.name !== "reply") throw new Error(`Unknown tool ${request.params.name}`);
+
+  // oxlint-disable-next-line typescript/no-base-to-string -- the arguments are the caller's own JSON, and its text is the reply as sent
+  const text = String(request.params.arguments?.text ?? "");
+  for (const stream of replyStreams) stream.write(`event: reply\ndata: ${JSON.stringify({ text })}\n\n`);
+  return { content: [{ text: "sent", type: "text" }] };
+});
+
+const writeEnded = (response: ServerResponse, statusCode: number) => {
+  response.writeHead(statusCode).end();
+};
+
+const handleSay = (request: IncomingMessage, response: ServerResponse) => {
+  // Decoded as the stream arrives, so a character split across two chunks is joined rather than read as two bad bytes
+  request.setEncoding("utf8");
+  let body = "";
+  request.on("data", (chunk: string) => {
+    body += chunk;
+  });
+  request.on("end", () => {
+    const line = readChannelLine(body);
+    if (line === undefined) return writeEnded(response, 400);
+
+    mcp.notification({ method: "notifications/claude/channel", params: { content: line, meta: { sender: "desk" } } });
+    writeEnded(response, 204);
+  });
+};
+
+const handleEvents = (request: IncomingMessage, response: ServerResponse) => {
+  response.writeHead(200, { "cache-control": "no-cache", "content-type": "text/event-stream" });
+  response.write(": open\n\n");
+  replyStreams.add(response);
+  request.on("close", () => replyStreams.delete(response));
+};
+
+const http = createServer((request, response) => {
+  const url = new URL(request.url ?? "/", "http://127.0.0.1");
+  const [, presentedToken = "", route = ""] = url.pathname.split("/");
+  if (!checkIsChannelRequestAllowed(request.socket.remoteAddress, presentedToken, token))
+    return writeEnded(response, 404);
+
+  if (route === "" && request.method === "GET") {
+    response.writeHead(200, { "content-type": "text/html; charset=utf-8" }).end(createChannelPage());
+    return;
+  }
+  if (route === "events" && request.method === "GET") return handleEvents(request, response);
+  if (route === "say" && request.method === "POST") return handleSay(request, response);
+  writeEnded(response, 404);
+});
+
+http.listen(0, "127.0.0.1", () => {
+  const { port } = http.address() as AddressInfo;
+  console.error(`Chat into the session: http://127.0.0.1:${port}/${token}/`);
+});
+
+await mcp.connect(new StdioServerTransport());

package/scripts/genshin.ts

@@ -4,8 +4,8 @@ import { readInterfaceLanguage } from "#src/services/readInterfaceLanguage";
 import { readLocalization } from "#src/services/readLocalization";
 import { runMain } from "citty";
 
-// Every line the plugin prints is in the interface language, so a verb it does not know, or none, or a request for help,
-// Is answered with its own usage line, and exits before citty would add an English one of its own
+// Every line the plugin prints is in the interface language, so a verb it does not know, or none, or a request for
+// Help, is answered with its own usage line, and exits before citty would add an English one of its own
 await runMain(genshinCommand, {
   showUsage: async () => {
     const { strings } = await readLocalization(readInterfaceLanguage());