@intentic/sandbox-contract 1.294.0 → 1.296.0

package/src/models/model-offer.test.ts

@@ -0,0 +1,88 @@
+import { expect, test } from "vitest";
+import { type ModelOffer, offerLines, parseModelPick, renewsInWords } from "./model-offer.js";
+
+/* THE OFFER the Auto judge chooses from, and the reading of what it replies. Pure both ways: no catalog, no account. */
+
+const NOW = 1_700_000_000_000;
+// Epoch SECONDS, as every reset instant on this wire; two hours past `NOW`.
+const IN_TWO_HOURS = Math.floor(NOW / 1000) + 2 * 3600;
+
+const OFFER: ModelOffer = {
+    models: [
+        { provider: "claude", model: "claude-opus-5", label: "Opus 5", efforts: ["low", "medium", "high", "max"], note: "Deep reasoning." },
+        { provider: "claude", model: "claude-haiku-4-5", label: "Haiku 4.5", efforts: ["low", "medium"] },
+        { provider: "codex", model: "gpt-5", label: "GPT-5", efforts: [] },
+    ],
+    accounts: {
+        claude: [
+            { id: "work", label: "work@studio", windows: [{ short: "5h", left: 38, resetsAt: IN_TWO_HOURS }, { short: "wk", left: 61 }] },
+            { id: "personal", windows: [] },
+        ],
+        codex: [],
+    },
+};
+
+test("a model line carries what it is, what it is for, and the efforts it takes", () => {
+    const lines = offerLines(OFFER, NOW);
+    expect(lines).toContain("- claude:claude-opus-5 — Opus 5. Deep reasoning. Effort: low, medium, high, max.");
+    // No note, so nothing is invented to fill the gap.
+    expect(lines).toContain("- claude:claude-haiku-4-5 — Haiku 4.5. Effort: low, medium.");
+    // A model that takes no effort setting says nothing about effort rather than offering an empty ladder.
+    expect(lines).toContain("- codex:gpt-5 — GPT-5.");
+});
+
+test("an account line says what is LEFT, names its pool and when it renews", () => {
+    const lines = offerLines(OFFER, NOW);
+    expect(lines).toContain("  - work (work@studio) — 5h: 38% left (renews in about 2h), wk: 61% left");
+    // Never measured is its own answer: reading it as empty would bench an account that may be entirely free.
+    expect(lines).toContain("  - personal — allowance never measured");
+});
+
+test("a provider with no named account still offers its models, and says why no account is named", () => {
+    expect(offerLines(OFFER, NOW)).toContain("- codex: no named account; this provider resolves its own.");
+});
+
+test("resets are phrased relatively, and coarsely at every scale", () => {
+    const seconds = Math.floor(NOW / 1000);
+    expect(renewsInWords(seconds + 30, NOW)).toBe("any moment");
+    expect(renewsInWords(seconds + 25 * 60, NOW)).toBe("in about 25 min");
+    expect(renewsInWords(seconds + 5 * 3600, NOW)).toBe("in about 5h");
+    expect(renewsInWords(seconds + 4 * 86_400, NOW)).toBe("in about 4 days");
+});
+
+test("the three keyed lines are read back against the offer", () => {
+    expect(parseModelPick("model: claude:claude-opus-5\neffort: high\naccount: work", OFFER).pick).toEqual({
+        provider: "claude",
+        model: "claude-opus-5",
+        effort: "high",
+        account: "work",
+    });
+});
+
+test("a reply is read through the wrappers a model reaches for anyway", () => {
+    const wrapped = "```\n- model: `claude:claude-haiku-4-5`\n- Effort: LOW\n```";
+    expect(parseModelPick(wrapped, OFFER).pick).toEqual({ provider: "claude", model: "claude-haiku-4-5", effort: "low" });
+});
+
+test("the first answer wins: a later line is commentary, not a second choice", () => {
+    const twice = "model: claude:claude-haiku-4-5\nmodel: claude:claude-opus-5";
+    expect(parseModelPick(twice, OFFER).pick?.model).toBe("claude-haiku-4-5");
+});
+
+test("a model that is not on the list yields no pick at all, carrying what it said", () => {
+    // The load-bearing choice: the caller steps to the next rung rather than running an id no provider has.
+    expect(parseModelPick("model: claude:claude-sonnet-9", OFFER)).toEqual({ pick: undefined, token: "claude:claude-sonnet-9" });
+    expect(parseModelPick("Opus, obviously", OFFER)).toEqual({ pick: undefined, token: "" });
+});
+
+test("an unrecognised effort or account is dropped, and the model it came with is kept", () => {
+    // Refinements, not the choice: the turn's own defaults answer for them, and losing a whole rung over one would
+    // spend another reading to learn nothing.
+    const offEffort = parseModelPick("model: claude:claude-haiku-4-5\neffort: max\naccount: nobody", OFFER);
+    expect(offEffort.pick).toEqual({ provider: "claude", model: "claude-haiku-4-5" });
+});
+
+test("an account of another provider is not honoured under this one", () => {
+    // `work` is a Claude account; naming it under codex would spend a credential that provider has no idea about.
+    expect(parseModelPick("model: codex:gpt-5\naccount: work", OFFER).pick).toEqual({ provider: "codex", model: "gpt-5" });
+});

package/src/models/model-offer.ts

@@ -0,0 +1,151 @@
+import { modelPinKey } from "./model-pins.js";
+import type { AgentProvider } from "../schemas/agent.js";
+import type { ModelPick } from "../schemas/model-route.js";
+
+// What the Auto judge is allowed to choose from, and how its reply is read back. Pure: the daemon gathers the facts
+// (catalogs, connected accounts, headroom readings) and this turns them into the lines the model sees and the
+// validator that reads its answer. Nothing outside the offer can be chosen, so a hallucinated model id is caught here
+// rather than at the provider.
+
+export interface OfferedWindow {
+    // Narrow token for the pool's length, e.g. "5h", "wk"; absent when nothing names how long the window runs.
+    readonly short?: string;
+    readonly label?: string;
+    // 0-100 REMAINING, the complement of the reading's utilization: the judge is asked about what is left, not spent.
+    readonly left: number;
+    // Epoch seconds, as every reset instant on this wire.
+    readonly resetsAt?: number;
+}
+
+export interface OfferedAccount {
+    readonly id: string;
+    // The owner's own name for it where there is one; the id is what must be replied with either way.
+    readonly label?: string;
+    // Empty means never measured, which is not the same as measured full and must not read as it.
+    readonly windows: readonly OfferedWindow[];
+}
+
+export interface OfferedModel {
+    readonly provider: AgentProvider;
+    readonly model: string;
+    readonly label: string;
+    // Weakest first, as the catalog row published them; empty means this model takes no effort setting.
+    readonly efforts: readonly string[];
+    // One short clause about what the model is for, where the catalog carries one.
+    readonly note?: string;
+}
+
+export interface ModelOffer {
+    // Already filtered: a model whose every account is at cap never reaches here.
+    readonly models: readonly OfferedModel[];
+    // Accounts that can pay, per provider id. A provider with none still offers its models: an unnamed account is a
+    // real state (a plain key, an endpoint), and the turn resolves one itself.
+    readonly accounts: Readonly<Record<string, readonly OfferedAccount[]>>;
+}
+
+// Relative phrasing of a reset, since an absolute instant would need the reader's timezone; deliberately coarse at
+// every scale. `reopensAt` is epoch seconds, `now` epoch ms.
+export const renewsInWords = (reopensAt: number, now: number): string => {
+    const seconds = reopensAt - Math.floor(now / 1000);
+    if (seconds <= 60) {
+        return `any moment`;
+    }
+    if (seconds < 60 * 60) {
+        return `in about ${Math.round(seconds / 60)} min`;
+    }
+    if (seconds < 36 * 60 * 60) {
+        return `in about ${Math.round(seconds / 3600)}h`;
+    }
+    return `in about ${Math.round(seconds / 86_400)} days`;
+};
+
+const windowWords = (window: OfferedWindow, now: number): string => {
+    const name = window.short ?? window.label ?? `allowance`;
+    const renews = window.resetsAt === undefined ? `` : ` (renews ${renewsInWords(window.resetsAt, now)})`;
+    return `${name}: ${Math.round(window.left)}% left${renews}`;
+};
+
+// An account with no reading says so rather than being left off: "not measured" is a fact the judge should weigh,
+// and an account silently missing from the list would read as one that cannot pay.
+const accountLine = (account: OfferedAccount, now: number): string => {
+    const name = account.label === undefined || account.label === account.id ? account.id : `${account.id} (${account.label})`;
+    const state = account.windows.length === 0 ? `allowance never measured` : account.windows.map((window) => windowWords(window, now)).join(`, `);
+    return `- ${name} — ${state}`;
+};
+
+const modelLine = (model: OfferedModel): string => {
+    const efforts = model.efforts.length === 0 ? `` : ` Effort: ${model.efforts.join(`, `)}.`;
+    const note = model.note === undefined ? `` : ` ${model.note.trim().replace(/\.$/u, ``)}.`;
+    return `- ${modelPinKey(model)} — ${model.label}.${note}${efforts}`;
+};
+
+// The two blocks the prompt shows: what may be run, and who can pay for it. Providers keep the offer's own order, so a
+// reply can be compared against the list a person would read.
+export const offerLines = (offer: ModelOffer, now: number): readonly string[] => {
+    const providers = [...new Set(offer.models.map((model) => model.provider))];
+    return [
+        `Models you may choose:`,
+        ...offer.models.map(modelLine),
+        ``,
+        `Accounts that can pay, and how much allowance each has left:`,
+        ...providers.flatMap((provider) => {
+            const accounts = offer.accounts[provider] ?? [];
+            return accounts.length === 0
+                ? [`- ${provider}: no named account; this provider resolves its own.`]
+                : [`- ${provider}:`, ...accounts.map((account) => `  ${accountLine(account, now)}`)];
+        }),
+    ];
+};
+
+// Wrapper words a model reaches for anyway: a fence, a bullet, quotes, a trailing period.
+const FENCE_LINE = /^```/u;
+const BULLET_LINE = /^[-*•]\s+/u;
+const FIELD = /^(model|effort|account)\s*:\s*(.+)$/iu;
+
+const bare = (value: string): string => value.trim().replace(/^[`'"]+/u, ``).replace(/[.`'"]+$/u, ``).trim();
+
+// The reply's `key: value` lines, lowercased keys, bullets and fences stripped. First wins: a model that answers twice
+// meant its first answer, and a later line is commentary on it.
+const fieldsOf = (reply: string): ReadonlyMap<string, string> => {
+    const fields = new Map<string, string>();
+    for (const line of reply.split(`\n`)) {
+        const trimmed = line.trim().replace(BULLET_LINE, ``);
+        const found = FENCE_LINE.test(trimmed) ? null : FIELD.exec(trimmed);
+        const key = found?.[1]?.toLowerCase();
+        if (key !== undefined && found?.[2] !== undefined && !fields.has(key)) {
+            fields.set(key, bare(found[2]));
+        }
+    }
+    return fields;
+};
+
+export interface ParsedPick {
+    readonly pick: ModelPick | undefined;
+    // The reply's literal model line, for the sentence explaining why a rung was stepped over.
+    readonly token: string;
+}
+
+// Reads the keyed reply (`model:` / `effort:` / `account:`) against the offer. The MODEL is the load-bearing choice:
+// one that names nothing offered yields no pick, and the caller steps to the next rung rather than running an id no
+// provider has. An unrecognised effort or account is dropped instead, keeping the model it came with — those are
+// refinements, and the turn's own defaults answer for them correctly.
+export const parseModelPick = (reply: string, offer: ModelOffer): ParsedPick => {
+    const fields = fieldsOf(reply);
+    const token = fields.get(`model`) ?? ``;
+    const chosen = offer.models.find((model) => modelPinKey(model).toLowerCase() === token.toLowerCase());
+    if (chosen === undefined) {
+        return { pick: undefined, token };
+    }
+    const effort = fields.get(`effort`);
+    const account = fields.get(`account`);
+    const named = (offer.accounts[chosen.provider] ?? []).find((entry) => entry.id.toLowerCase() === account?.toLowerCase());
+    return {
+        pick: {
+            provider: chosen.provider,
+            model: chosen.model,
+            ...(effort !== undefined && chosen.efforts.includes(effort.toLowerCase()) ? { effort: effort.toLowerCase() } : {}),
+            ...(named === undefined ? {} : { account: named.id }),
+        },
+        token,
+    };
+};

package/src/models/model-roles.ts

@@ -65,6 +65,15 @@ export const MODEL_ROLES = [
         kind: "helper",
         icon: "users",
     },
+    {
+        // Picks one offered `provider:model` line, an effort and an account from a fixed list; a classification, not
+        // free text. Prompt carries live account headroom, so it must not be a model whose own allowance it is reading.
+        id: "model-router",
+        label: "Auto model choice",
+        blurb: "Which model reads a new chat's first message and picks the model, effort and account it runs on.",
+        kind: "helper",
+        icon: "sparkles",
+    },
     {
         id: "pipeline-fix",
         label: "Pipeline fixes",

package/src/schemas/agent.ts

@@ -262,6 +262,13 @@ export const AgentTurnSchema = z
             ),
         // Vetoes automatic tier selection for this turn; the judge still runs and records its verdict, but nothing is
         // substituted.
+        // Set by the composer on the one turn whose model the Auto judge chose; the daemon only records it.
+        autoPicked: z
+            .boolean()
+            .optional()
+            .describe(
+                "Whether this turn's model was chosen for you by reading the conversation's opening message, rather than picked by hand. Recorded so the choice can be judged later against what you did next.",
+            ),
         tierHold: z
             .boolean()
             .optional()

package/src/schemas/agents.ts

@@ -2,6 +2,7 @@
 import { z } from "zod";
 import { AgentHarnessSchema, AgentOriginSchema, AgentProviderSchema, ForkedFromSchema } from "./agent.js";
 import { LoopStateSchema } from "./loops.js";
+import { EMOJI_MAX_LENGTH, isSingleEmoji } from "../text/emoji.js";
 // A fleet agent is any conversation with a registry entry, keyed by conversationId. Isolated ones own a git worktree
 // (branch agent/<id>); workspace conversations have none, but both share one status/activity/cost lifecycle.
 
@@ -153,6 +154,26 @@ export type LandedMessageDraft = z.infer<typeof LandedMessageDraftSchema>;
 // offer the press that clears a refusal without knowing whose refusal it is.
 export const LandConflictReasonSchema = z.enum(["workspace", "diverged", "binary"]);
 export type LandConflictReason = z.infer<typeof LandConflictReasonSchema>;
+// One person behind one mark. The instant rides along so the group can be ordered by who was first, which is also the
+// order the names read in.
+export const ReactorSchema = z.object({
+    email: z.string().describe("Who it was, as the sandbox verified them."),
+    name: z.string().optional().describe("What to call them, when their sign-in carried a name. Absent leaves the address to stand for them."),
+    at: z.number().describe("When they marked it, in milliseconds."),
+});
+export type Reactor = z.infer<typeof ReactorSchema>;
+// Grouped by emoji on the wire, not as a flat list of presses: every surface draws one chip per emoji, and grouping
+// here is what stops three of them each grouping it differently.
+export const AgentReactionSchema = z.object({
+    emoji: z.string().describe("The mark itself, one emoji, carried as the character rather than as a name that would need a table on both sides."),
+    by: z
+        .array(ReactorSchema)
+        .min(1)
+        .describe(
+            "Everyone wearing this mark, oldest first, each by name. Carried whole rather than as a count, because a chip reading 3 that cannot say whose is a number nobody can answer. Never empty: the last person taking theirs back takes the whole chip with it.",
+        ),
+});
+export type AgentReaction = z.infer<typeof AgentReactionSchema>;
 export const AgentSummarySchema = z.object({
     id: z.string().describe("The conversation id, which is how every other call addresses it."),
     sessionId: z.string().optional().describe("The provider session behind the last turn. It is retired whenever the model or account changes."),
@@ -252,6 +273,15 @@ export const AgentSummarySchema = z.object({
         .describe(
             "A collaborator has asked a maintainer to merge this work. Cleared by whichever merge or discard answers it. Absent means nobody is waiting.",
         ),
+    // Beside `landRequested` because both are marks people left on the card rather than anything the agent did. Ordered
+    // by when each emoji was first used, so a chip never jumps out from under the cursor when a second person presses
+    // the same one.
+    reactions: z
+        .array(AgentReactionSchema)
+        .optional()
+        .describe(
+            "What people have marked this conversation with, one entry per emoji, in the order the emoji were first used. Absent means nobody has marked it, which is most conversations.",
+        ),
     // The card's provenance line when an outside message opened the conversation; absent means a person started it.
     origin: AgentOriginSchema.optional().describe(
         "Where the conversation came from when nobody typed it: a chat mention, a visitor's message, a webhook. Absent means a person started it.",
@@ -534,6 +564,18 @@ export const AgentRenameSchema = z.object({
     id: z.string().min(1).describe("Which conversation."),
     title: z.string().trim().min(1).max(80).describe("What to call it from now on."),
 });
+// `on` states the intent rather than flipping whatever is stored: a double press, a retried request and two windows
+// racing must all settle the same way, which a toggle cannot promise.
+export const AgentReactSchema = z.object({
+    id: z.string().min(1).describe("Which conversation."),
+    emoji: z
+        .string()
+        .trim()
+        .max(EMOJI_MAX_LENGTH)
+        .refine(isSingleEmoji, { message: "not a single emoji" })
+        .describe("The mark to leave, as the emoji character itself. Exactly one: a chip has room for one mark, and a press is one press."),
+    on: z.boolean().describe("Whether to add your mark or take it back. Saying what you want rather than flipping what is there, so pressing twice lands where pressing once did."),
+});
 // Bounded just above the handoff's per-message render cap, so a line too long to carry whole doesn't reach the agent
 // truncated.
 export const AgentPlaceSchema = z.object({

package/src/schemas/model-route.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { AgentProviderSchema } from "./agent.js";
+
+// Asked once per chat, on the message it opens with; answers with the model, effort and account that whole
+// conversation runs on. Distinct from prompt-complexity.ts, which judges a turn at a time and may only ever name a
+// cheaper rung of the provider already picked: this one chooses freely, and only before anything has run.
+
+export const ModelRouteAskSchema = z.object({
+    prompt: z.string().min(1).max(20000).describe("The message a new chat is about to open with."),
+    paths: z
+        .array(z.string().min(1).max(500))
+        .max(50)
+        .default([])
+        .describe("Workspace paths the message names: uploads, @-mentions, the editor's own file. How much real code the work touches."),
+    editorContext: z.boolean().optional().describe("Whether the message carries a file and selection the user pointed at, so it is about real code."),
+    planMode: z.boolean().optional().describe("Whether the chat opens in plan mode, which is a request to think before acting."),
+});
+export type ModelRouteAsk = z.infer<typeof ModelRouteAskSchema>;
+
+export const ModelPickSchema = z.object({
+    provider: AgentProviderSchema.describe("Which provider serves the conversation."),
+    model: z.string().min(1).describe("Which of its models."),
+    effort: z.string().optional().describe("How hard it should think, where the model offers a choice. Absent takes the model's own default."),
+    account: z
+        .string()
+        .optional()
+        .describe("Which connected account pays, by its daemon-minted id. Absent leaves it to whichever account has the most headroom."),
+});
+export type ModelPick = z.infer<typeof ModelPickSchema>;
+
+export const ModelRouteSchema = z.object({
+    // Absent is a real, safe answer: the chat runs on whatever the picker remembered, and says why nothing moved.
+    pick: ModelPickSchema.optional().describe("What the conversation should run on, or absent when nothing could be chosen and the usual pick stands."),
+    reason: z.string().describe("Why, in the one line a chat can show. Present whether or not a model was named."),
+    // Absent means nothing was spent: the role was unset, every rung refused, or the deadline passed first.
+    judge: z
+        .string()
+        .optional()
+        .describe(
+            "Which model answered, as `provider:model`, so the chat can name what the reading cost. Absent when no model was reached at all.",
+        ),
+});
+export type ModelRoute = z.infer<typeof ModelRouteSchema>;

package/src/schemas/providers/usage.ts

@@ -102,6 +102,10 @@ export const UsageTurnSchema = z.object({
     tierCeiling: z.number().optional(),
     // The turn carried AgentTurn.tierHold: the user vetoed a fast verdict. Absent means no veto.
     tierDenied: z.boolean().optional(),
+    // This turn's model was chosen by the Auto judge reading the conversation's opening message, not picked by hand.
+    // Marked on that one turn only; a later row of the same conversation naming a different model is the user
+    // overruling it, which is the escalation rate this feature has to be able to answer for.
+    autoPicked: z.boolean().optional(),
 });
 export type UsageTurn = z.infer<typeof UsageTurnSchema>;
 // Ledger grouped by day, provider, account, model, harness and conversation, one panel's worth of rows per active day.

package/src/schemas/settings.ts

@@ -317,11 +317,15 @@ export const SandboxSettingsSchema = z.object({
     // off: the judge never runs.
     // shadow (default): the judge scores every turn to the ledger; nothing is routed.
     // on: a turn judged fast runs on the cheap rung, where the provider publishes one.
+    // judge: the deterministic scorer keeps writing shadow rows but routes nothing; the Auto picker row is offered
+    // instead, and a model reads a new chat's opening message once to choose what the whole conversation runs on.
+    // Exclusive with `on` because the two answer the same question at different moments, and a per-turn downgrade
+    // underneath a picked-by-model conversation would be overruling a choice already made about this chat.
     autoTier: z
-        .enum(["off", "shadow", "on"])
+        .enum(["off", "shadow", "on", "judge"])
         .default("shadow")
         .describe(
-            "Whether an easy-looking turn may run on a cheaper model from the same provider. Three states rather than a switch, because the middle one is the only honest road to the third: it scores every turn and routes nothing, so the guess can become a measurement before it changes anything. It can only ever route down, so the worst case is one turn's quality rather than a bill nobody asked for.",
+            "Whether an easy-looking turn may run on a cheaper model from the same provider. Three states rather than a switch, because the middle one is the only honest road to the third: it scores every turn and routes nothing, so the guess can become a measurement before it changes anything. It can only ever route down, so the worst case is one turn's quality rather than a bill nobody asked for. The fourth, Auto, answers a different question: rather than downgrading turns one by one, it offers an Auto row in the model picker and has a model read a new chat's first message to choose what that whole conversation runs on.",
         ),
     // `balanced` is what every verdict recorded before this setting existed was judged against, so shadow history stays
     // comparable.

package/src/text/emoji.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { isSingleEmoji } from "./emoji.js";
+
+describe("isSingleEmoji", () => {
+    it("takes one emoji however many code points it is made of", () => {
+        expect(isSingleEmoji(`👍`)).toBe(true);
+        // A skin tone, a ZWJ family and a flag are 2, 7 and 2 code points that each draw as one mark.
+        expect(isSingleEmoji(`👍🏽`)).toBe(true);
+        expect(isSingleEmoji(`👨‍👩‍👧‍👦`)).toBe(true);
+        expect(isSingleEmoji(`🇵🇱`)).toBe(true);
+        expect(isSingleEmoji(`🏴󠁧󠁢󠁳󠁣󠁴󠁿`)).toBe(true);
+        // A keycap leads with an ASCII digit, which is why the pictographic property alone would refuse it.
+        expect(isSingleEmoji(`1️⃣`)).toBe(true);
+    });
+
+    it("refuses everything that is not exactly one mark", () => {
+        expect(isSingleEmoji(``)).toBe(false);
+        expect(isSingleEmoji(`👍👎`)).toBe(false);
+        expect(isSingleEmoji(`a`)).toBe(false);
+        expect(isSingleEmoji(`lgtm`)).toBe(false);
+        // The one a length check alone would let through: an emoji with a word stuck to it.
+        expect(isSingleEmoji(`👍!`)).toBe(false);
+        expect(isSingleEmoji(` `)).toBe(false);
+    });
+
+    it("refuses a string too long to be one grapheme without segmenting it", () => {
+        expect(isSingleEmoji(`👍`.repeat(40))).toBe(false);
+    });
+});

package/src/text/emoji.ts

@@ -0,0 +1,24 @@
+// What counts as one emoji, for anywhere a person picks one rather than types a sentence (a conversation's reactions).
+// Shared so the field that accepts the press and the route that stores it cannot disagree about what was pressed.
+
+// The unit is the grapheme, not the code point: a flag, a skin-toned wave and a seven-code-point family all render as
+// one mark, and one mark is what a chip draws and a person presses.
+const graphemes = new Intl.Segmenter(undefined, { granularity: `grapheme` });
+
+// Two escapes ride alongside the pictographic property rather than under it, because neither is one: a keycap (1️⃣) is a
+// plain ASCII digit plus U+20E3, and a country flag (🇵🇱) is a pair of regional indicators.
+const PICTOGRAPHIC = /[\p{Extended_Pictographic}\p{Regional_Indicator}\u{20E3}]/u;
+
+// A single grapheme is long enough to matter — a subdivision flag is 28 UTF-16 units — so this bounds the string before
+// segmenting it, and never stands in for the grapheme count itself.
+export const EMOJI_MAX_LENGTH = 64;
+
+// True for exactly one emoji grapheme. False for two of them, for a letter, and for an empty string: a reaction is one
+// press, and a chip has room for one mark.
+export const isSingleEmoji = (text: string): boolean => {
+    if (text.length === 0 || text.length > EMOJI_MAX_LENGTH || !PICTOGRAPHIC.test(text)) {
+        return false;
+    }
+    const segments = graphemes.segment(text)[Symbol.iterator]();
+    return segments.next().done !== true && segments.next().done === true;
+};