narraeon 0.5.7 → 0.6.0

package/dist/node/runtime/play/TabletopResolution.js

@@ -0,0 +1,372 @@
+import { createHmac } from "node:crypto";
+import { Ajv } from "ajv";
+import { arithmeticTotal, d100Outcome, d20Outcome, isResolutionReceipt, percentileCandidate, } from "../../protocol/resolution.js";
+export const resolutionToolNames = [
+    "d20_check",
+    "percentile_check",
+    "bag_check",
+    "roll_dice",
+    "calculate",
+];
+export function isResolutionTool(name) {
+    return resolutionToolNames.some((item) => item === name);
+}
+const checkToolByScheme = {
+    d20: "d20_check",
+    d100: "percentile_check",
+    bag: "bag_check",
+};
+/** The one check tool that embodies a tabletop scheme. Auxiliary tools never decide success. */
+export function resolutionCheckToolForScheme(scheme) {
+    return checkToolByScheme[scheme];
+}
+const integer = (minimum, maximum) => ({
+    type: "integer",
+    minimum,
+    maximum,
+});
+const number = { type: "number", minimum: -1_000_000, maximum: 1_000_000 };
+const goal = { type: "string", minLength: 1, maxLength: 1000, pattern: "\\S" };
+const object = (properties, required) => ({
+    type: "object",
+    additionalProperties: false,
+    properties,
+    required,
+});
+const resolutionSchemas = {
+    d20_check: object({
+        goal,
+        modifier: integer(-1_000_000, 1_000_000),
+        difficulty: integer(-1_000_000, 1_000_000),
+        mode: { enum: ["normal", "advantage", "disadvantage"] },
+    }, ["goal", "modifier", "difficulty"]),
+    percentile_check: object({
+        goal,
+        target: integer(0, 100),
+        bonusDice: integer(0, 2),
+        penaltyDice: integer(0, 2),
+    }, ["goal", "target"]),
+    bag_check: object({
+        goal,
+        value: number,
+        difficulty: number,
+        tokens: {
+            type: "array",
+            minItems: 1,
+            maxItems: 100,
+            items: object({
+                label: { type: "string", minLength: 1, maxLength: 80 },
+                count: integer(1, 100),
+                modifier: number,
+                outcome: { enum: ["critical_success", "critical_failure"] },
+            }, ["label", "count"]),
+        },
+    }, ["goal", "value", "difficulty"]),
+    roll_dice: object({ goal, count: integer(1, 100), sides: integer(2, 1000), modifier: number }, ["goal", "count", "sides"]),
+    calculate: object({
+        goal,
+        left: number,
+        right: number,
+        operation: { enum: ["add", "subtract", "multiply", "divide"] },
+    }, ["goal", "left", "right", "operation"]),
+};
+const descriptions = {
+    d20_check: [
+        "掷 d20 判定。原始 20 大成功、1 大失败；其余取值加 modifier >= difficulty 成功。优势两骰取高，劣势取低。先确定目标和数值，结果必须兑现。",
+        "Resolve a d20 check. Selected raw 20 critically succeeds, 1 critically fails; otherwise roll + modifier >= difficulty succeeds. Advantage keeps the higher of two dice, disadvantage the lower. Declare the goal and values before rolling; honour the result.",
+    ],
+    percentile_check: [
+        "百分骰判定。共享个位，奖励/惩罚额外十位骰相消后取较低/较高的完整结果，00 与个位0表示100。最终1大成功、100大失败，其余 <= target 成功。",
+        "Resolve a percentile check. Bonus/penalty tens dice cancel, share one units die, and select the lowest/highest complete result; 00 with units 0 means 100. Selected 1 critically succeeds, 100 critically fails; otherwise <= target succeeds.",
+    ],
+    bag_check: [
+        "从当前标记清单按数量抽一枚并放回。数值 value + 标记修正 >= difficulty 成功；特殊标记覆盖成败。省略 tokens 使用默认袋（+1、0×2、-1×2、-2、大成功、大失败）。自定义袋先从世界文档读取，原样提供；每种标记必须恰好有 modifier 或 outcome。",
+        "Draw one token by quantity, with replacement. value + token modifier >= difficulty succeeds; a special outcome overrides comparison. Omit tokens for the default bag (+1, 0 x2, -1 x2, -2, critical success, critical failure). Read a custom bag from world documents and supply it exactly; every token has exactly one modifier or outcome.",
+    ],
+    roll_dice: [
+        "辅助数值掷骰：count 枚 sides 面骰求和加 modifier。用于伤害、数量等，不重新裁决已确定的行动成败。",
+        "Roll auxiliary numeric dice: sum count dice of sides faces and add modifier. Use for damage or quantities, not to reverse a resolved action.",
+    ],
+    calculate: [
+        "对两个数执行加减乘除，不产生随机数，不修改世界。",
+        "Add, subtract, multiply or divide two numbers without randomness or world changes.",
+    ],
+};
+export function resolutionToolDefinition(name, locale) {
+    return {
+        name,
+        description: descriptions[name][locale === "zh-CN" ? 0 : 1],
+        inputSchema: structuredClone(resolutionSchemas[name]),
+    };
+}
+const ajv = new Ajv({ allErrors: true, strict: true });
+const validators = Object.fromEntries(resolutionToolNames.map((name) => [
+    name,
+    ajv.compile(resolutionSchemas[name]),
+]));
+const defaultBagTokens = [
+    { label: "+1", count: 1, modifier: 1 },
+    { label: "0", count: 2, modifier: 0 },
+    { label: "-1", count: 2, modifier: -1 },
+    { label: "-2", count: 1, modifier: -2 },
+    { label: "critical_success", count: 1, outcome: "critical_success" },
+    { label: "critical_failure", count: 1, outcome: "critical_failure" },
+];
+/** Rejection sampling over a secret persisted seed; independent per tool call. */
+export function seededRandom(seed, identity) {
+    let counter = 0;
+    return (maximum) => {
+        if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > 1_000_000)
+            throw new Error("Invalid random bound");
+        const limit = Math.floor(0x1_0000_0000 / maximum) * maximum;
+        for (;;) {
+            const value = createHmac("sha256", seed)
+                .update(JSON.stringify([identity, counter++]))
+                .digest()
+                .readUInt32BE();
+            if (value < limit)
+                return value % maximum;
+        }
+    };
+}
+/** Resolve one validated tool call. Invalid arguments throw before any draw. */
+export function resolveTabletop(name, args, random) {
+    if (!validators[name](args))
+        throw new Error(`Invalid ${name} parameters: ${ajv.errorsText(validators[name].errors)}`);
+    const input = args;
+    const receipt = name === "d20_check"
+        ? resolveD20(input, random)
+        : name === "percentile_check"
+            ? resolveD100(input, random)
+            : name === "bag_check"
+                ? resolveBag(input, random)
+                : name === "roll_dice"
+                    ? resolveDice(input, random)
+                    : resolveArithmetic(input);
+    if (!isResolutionReceipt(receipt))
+        throw new Error("Calculation produced an invalid resolution receipt");
+    return receipt;
+}
+function roll(random, sides) {
+    return random(sides) + 1;
+}
+function resolveD20(input, random) {
+    const mode = input.mode ?? "normal";
+    const modifier = input.modifier;
+    const difficulty = input.difficulty;
+    const dice = [roll(random, 20)];
+    if (mode !== "normal")
+        dice.push(roll(random, 20));
+    const selected = mode === "disadvantage" ? Math.min(...dice) : Math.max(...dice);
+    const total = selected + modifier;
+    return {
+        kind: "d20",
+        goal: input.goal,
+        modifier,
+        difficulty,
+        mode,
+        dice,
+        selected,
+        total,
+        margin: total - difficulty,
+        outcome: d20Outcome(selected, total, difficulty),
+    };
+}
+function resolveD100(input, random) {
+    const bonusDice = input.bonusDice ?? 0;
+    const penaltyDice = input.penaltyDice ?? 0;
+    const target = input.target;
+    const units = random(10);
+    const net = bonusDice - penaltyDice;
+    const tens = Array.from({ length: Math.abs(net) + 1 }, () => random(10));
+    const candidates = tens.map((ten) => percentileCandidate(ten, units));
+    const selected = net < 0 ? Math.max(...candidates) : Math.min(...candidates);
+    return {
+        kind: "d100",
+        goal: input.goal,
+        target,
+        bonusDice,
+        penaltyDice,
+        units,
+        tens,
+        candidates,
+        selected,
+        margin: target - selected,
+        outcome: d100Outcome(selected, target),
+    };
+}
+function resolveBag(input, random) {
+    const defaultBag = input.tokens === undefined;
+    const tokens = structuredClone(input.tokens ?? defaultBagTokens);
+    if (new Set(tokens.map((token) => token.label)).size !== tokens.length ||
+        tokens.some((token) => (token.modifier !== undefined) === (token.outcome !== undefined)))
+        throw new Error("Bag labels must be unique, with exactly one modifier or outcome per token");
+    const weight = tokens.reduce((sum, token) => sum + token.count, 0);
+    let index = random(weight);
+    const token = tokens.find((item) => {
+        index -= item.count;
+        return index < 0;
+    });
+    const value = input.value;
+    const difficulty = input.difficulty;
+    const base = {
+        kind: "bag",
+        goal: input.goal,
+        value,
+        difficulty,
+        defaultBag,
+        tokens,
+    };
+    if (token.outcome !== undefined)
+        return {
+            ...base,
+            drawn: { label: token.label, outcome: token.outcome },
+            outcome: token.outcome,
+        };
+    const drawn = { label: token.label, modifier: token.modifier };
+    const total = value + token.modifier;
+    return {
+        ...base,
+        drawn,
+        total,
+        margin: total - difficulty,
+        outcome: total >= difficulty ? "success" : "failure",
+    };
+}
+function resolveDice(input, random) {
+    const count = input.count;
+    const sides = input.sides;
+    const modifier = input.modifier ?? 0;
+    const dice = Array.from({ length: count }, () => roll(random, sides));
+    return {
+        kind: "dice",
+        goal: input.goal,
+        count,
+        sides,
+        modifier,
+        dice,
+        total: dice.reduce((sum, die) => sum + die, modifier),
+    };
+}
+function resolveArithmetic(input) {
+    const left = input.left;
+    const right = input.right;
+    const operation = input.operation;
+    if (operation === "divide" && right === 0)
+        throw new Error("Cannot divide by zero");
+    const total = arithmeticTotal(operation, left, right);
+    if (!Number.isFinite(total))
+        throw new Error("Calculation is not finite");
+    return {
+        kind: "arithmetic",
+        goal: input.goal,
+        left,
+        right,
+        operation,
+        total,
+    };
+}
+const outcomeLabels = {
+    "zh-CN": {
+        success: "成功",
+        failure: "失败",
+        critical_success: "大成功",
+        critical_failure: "大失败",
+    },
+    en: {
+        success: "success",
+        failure: "failure",
+        critical_success: "critical success",
+        critical_failure: "critical failure",
+    },
+};
+/** Localized text the model receives as the tool result. */
+export function resolutionMarkdown(receipt, locale) {
+    const zh = locale === "zh-CN";
+    const outcome = (value) => outcomeLabels[zh ? "zh-CN" : "en"][value];
+    const signed = (value) => (value >= 0 ? `+${value}` : `${value}`);
+    const list = (values) => values.join(", ");
+    const lines = [`# ${receipt.goal}`, ""];
+    if (receipt.kind === "d20") {
+        const modes = zh
+            ? { normal: "普通", advantage: "优势", disadvantage: "劣势" }
+            : {
+                normal: "normal",
+                advantage: "advantage",
+                disadvantage: "disadvantage",
+            };
+        const compared = receipt.total >= receipt.difficulty ? ">=" : "<";
+        lines.push(zh
+            ? `判定：d20，${modes[receipt.mode]}`
+            : `Check: d20, ${modes[receipt.mode]}`, zh
+            ? `修正：${signed(receipt.modifier)}；难度：${receipt.difficulty}`
+            : `Modifier: ${signed(receipt.modifier)}; difficulty: ${receipt.difficulty}`, zh
+            ? `掷骰：${list(receipt.dice)}；取值：${receipt.selected}`
+            : `Dice: ${list(receipt.dice)}; selected: ${receipt.selected}`, zh
+            ? `计算：${receipt.selected} ${signed(receipt.modifier)} = ${receipt.total}；${receipt.total} ${compared} ${receipt.difficulty}；差值 ${signed(receipt.margin)}`
+            : `Calculation: ${receipt.selected} ${signed(receipt.modifier)} = ${receipt.total}; ${receipt.total} ${compared} ${receipt.difficulty}; margin ${signed(receipt.margin)}`);
+    }
+    else if (receipt.kind === "d100") {
+        const net = receipt.bonusDice - receipt.penaltyDice;
+        const pool = net === 0
+            ? zh
+                ? "无额外十位骰"
+                : "no extra tens die"
+            : net > 0
+                ? zh
+                    ? `奖励骰 ${receipt.bonusDice}、惩罚骰 ${receipt.penaltyDice}，相消后 ${net} 枚奖励骰，取低`
+                    : `${receipt.bonusDice} bonus and ${receipt.penaltyDice} penalty dice, net ${net} bonus die; lowest kept`
+                : zh
+                    ? `奖励骰 ${receipt.bonusDice}、惩罚骰 ${receipt.penaltyDice}，相消后 ${-net} 枚惩罚骰，取高`
+                    : `${receipt.bonusDice} bonus and ${receipt.penaltyDice} penalty dice, net ${-net} penalty die; highest kept`;
+        lines.push(zh ? `目标：${receipt.target}` : `Target: ${receipt.target}`, zh ? `判定：d100，${pool}` : `Check: d100, ${pool}`, zh
+            ? `个位：${receipt.units}；十位：${list(receipt.tens)}`
+            : `Units: ${receipt.units}; tens: ${list(receipt.tens)}`, zh
+            ? `完整结果：${list(receipt.candidates)}；取值：${receipt.selected}`
+            : `Complete results: ${list(receipt.candidates)}; selected: ${receipt.selected}`, zh
+            ? `计算：${receipt.selected} <= ${receipt.target}；差值 ${signed(receipt.margin)}`
+            : `Calculation: ${receipt.selected} <= ${receipt.target}; margin ${signed(receipt.margin)}`);
+    }
+    else if (receipt.kind === "bag") {
+        const tokens = receipt.tokens
+            .map((token) => `${token.label} ×${token.count}`)
+            .join(zh ? "、" : ", ");
+        lines.push(zh
+            ? `标记袋：${receipt.defaultBag ? "默认袋" : "自定义袋"}（${tokens}）`
+            : `Bag: ${receipt.defaultBag ? "default" : "custom"} (${tokens})`, zh
+            ? `抽取：${receipt.drawn.label}（有放回）`
+            : `Drawn: ${receipt.drawn.label} (with replacement)`);
+        if (receipt.drawn.outcome !== undefined)
+            lines.push(zh
+                ? `特殊标记直接决定结果：${outcome(receipt.drawn.outcome)}`
+                : `Special token decides the result: ${outcome(receipt.drawn.outcome)}`);
+        else {
+            const compared = receipt.total >= receipt.difficulty ? ">=" : "<";
+            lines.push(zh
+                ? `数值：${receipt.value}；标记修正：${signed(receipt.drawn.modifier)}；难度：${receipt.difficulty}`
+                : `Value: ${receipt.value}; token modifier: ${signed(receipt.drawn.modifier)}; difficulty: ${receipt.difficulty}`, zh
+                ? `计算：${receipt.value} ${signed(receipt.drawn.modifier)} = ${receipt.total}；${receipt.total} ${compared} ${receipt.difficulty}；差值 ${signed(receipt.margin)}`
+                : `Calculation: ${receipt.value} ${signed(receipt.drawn.modifier)} = ${receipt.total}; ${receipt.total} ${compared} ${receipt.difficulty}; margin ${signed(receipt.margin)}`);
+        }
+    }
+    else if (receipt.kind === "dice") {
+        lines.push(zh
+            ? `掷骰：${receipt.count}d${receipt.sides}，结果 ${list(receipt.dice)}，修正 ${signed(receipt.modifier)}`
+            : `Dice: ${receipt.count}d${receipt.sides}, results ${list(receipt.dice)}, modifier ${signed(receipt.modifier)}`, zh ? `合计：${receipt.total}` : `Total: ${receipt.total}`);
+    }
+    else {
+        lines.push(zh
+            ? `计算：${receipt.left} ${arithmeticSymbol(receipt.operation)} ${receipt.right} = ${receipt.total}`
+            : `Calculation: ${receipt.left} ${arithmeticSymbol(receipt.operation)} ${receipt.right} = ${receipt.total}`);
+    }
+    if (receipt.kind === "d20" ||
+        receipt.kind === "d100" ||
+        receipt.kind === "bag")
+        lines.push("", zh
+            ? `结果：${outcome(receipt.outcome)}`
+            : `Outcome: ${outcome(receipt.outcome)}`);
+    return lines.join("\n");
+}
+function arithmeticSymbol(operation) {
+    return { add: "+", subtract: "-", multiply: "×", divide: "÷" }[operation];
+}

package/dist/node/runtime/play/TabletopRules.js

@@ -0,0 +1,141 @@
+import { gameplayLabel } from "../../protocol/gameplay.js";
+import { resolutionCheckToolForScheme, resolutionToolDefinition, } from "./TabletopResolution.js";
+/**
+ * The scheme's fixed rules, taken from the same description the check tool
+ * sends to the model, so the prompt and the tool cannot drift apart.
+ */
+export function tabletopSchemeRules(gameplay, locale) {
+    return resolutionToolDefinition(resolutionCheckToolForScheme(gameplay.scheme), locale).description;
+}
+/**
+ * Runtime-owned rules at the world placeholder of a tabletop world. The block
+ * is world-derived and carries no preset state, so a scheme never requires a
+ * preset change.
+ */
+export function tabletopWorldRulesBlock(gameplay, locale) {
+    const label = gameplayLabel(gameplay, locale);
+    const rules = tabletopSchemeRules(gameplay, locale);
+    // Only the bag scheme has a world-defined token list; other schemes never mention one.
+    const bagLine = gameplay.scheme !== "bag"
+        ? ""
+        : locale === "zh-CN"
+            ? "- 世界文档中定义的混乱袋必须读取，并原样提供其当前标记清单；袋的变化由你在世界文档中维护。\n"
+            : "- A chaos bag defined in the world documents must be read and supplied exactly as its current token list. You maintain the bag's changes in the world documents.\n";
+    const markdown = locale === "zh-CN"
+        ? `# 跑团判定规则
+
+本世界是跑团世界，判定方案为 ${label}。以下规则由 Runtime 固定，随本世界的玩法身份生效。
+
+## 判定工具
+
+${rules}
+
+## 辅助工具
+
+- roll_dice：辅助数值掷骰，用于伤害、数量等，不重新裁决已确定的行动成败。
+- calculate：对两个数执行加减乘除，不产生随机数，不修改世界。
+
+## 绑定契约
+
+- 调用判定工具前，先声明行动目标、所用数值与难度；只有有成败不确定性或对抗的行动才需要判定。
+- 必须先调用判定工具并取得回执，再叙述结果。
+- 判定成功必须实现已声明的目标，失败则不实现，不论情节是否看似合理。
+- 大成功与大失败按工具的固定规则兑现，不能由叙述改写。
+- 掷骰之后不得更改该行动的目标或难度，也不得为同一行动重掷。
+- 辅助掷骰与算术只决定伤害、数量等数值，不能推翻已经结算的判定。
+${bagLine}- 参数不合法属于工具错误，不等于行动失败；修正参数后重新调用即可。`
+        : `# Tabletop resolution rules
+
+This world is tabletop, with resolution scheme ${label}. The Runtime-fixed rules below apply because of this world's gameplay identity.
+
+## Check tool
+
+${rules}
+
+## Auxiliary tools
+
+- roll_dice: auxiliary numeric dice for damage, quantities and similar values. It never re-decides a resolved action.
+- calculate: add, subtract, multiply or divide two numbers. It draws no randomness and changes no world state.
+
+## Binding contract
+
+- Before calling the check tool, declare the action's goal, the inputs and the difficulty. Only actions with uncertain success or opposition need a check.
+- Call the check tool and receive its receipt before narrating the outcome.
+- A success must fulfil the declared goal and a failure must not, regardless of whether the story seems plausible.
+- Critical outcomes follow the tool's fixed rules and cannot be rewritten by narration.
+- After a draw, never change that action's goal or difficulty, and never reroll the same action.
+- Auxiliary dice and arithmetic decide numeric values such as damage or quantities; they never reverse a resolved check.
+${bagLine}- Invalid arguments are tool errors, not failed actions; correct the arguments and call the tool again.`;
+    return { source: "runtime:world-placeholder/gameplay", markdown };
+}
+/**
+ * Author-side statement of a tabletop package or world revision: the mode and
+ * scheme, what a write may change, and the scheme's rules.
+ */
+export function tabletopAuthoringRulesBlock(gameplay, target, locale) {
+    const label = gameplayLabel(gameplay, locale);
+    const rules = tabletopSchemeRules(gameplay, locale);
+    const source = target === "setting"
+        ? "runtime:content-package/gameplay"
+        : "runtime:world-revision/gameplay";
+    const markdown = target === "setting"
+        ? locale === "zh-CN"
+            ? `# 玩法模式与判定方案
+
+当前内容包是跑团内容包，当前判定方案为 ${label}。玩法模式固定为跑团，不能改为互动式小说。判定方案可通过写入 control/gameplay.json 改为 d20、d100 或 bag；这只影响之后创建的世界，已有世界不随源内容包变化。改变方案时，应同步调整人物数值、难度与规则，使其符合新方案的数值尺度。
+
+当前方案的判定工具规则：
+
+${rules}`
+            : `# Gameplay mode and resolution scheme
+
+This content package is tabletop, with current resolution scheme ${label}. The gameplay mode is fixed as tabletop and cannot become interactive fiction. The scheme may be changed by writing control/gameplay.json to d20, d100 or bag. The change affects only worlds created later; existing worlds never follow the source package. When changing the scheme, adjust character values, difficulty and rules so they match the new scheme's numeric scale.
+
+Check-tool rules for the current scheme:
+
+${rules}`
+        : locale === "zh-CN"
+            ? `# 玩法模式与判定方案（固定）
+
+当前修订的世界是跑团世界，判定方案为 ${label}。玩法模式与判定方案在世界创建后固定，修订不能修改 control/gameplay.json。数值与难度须遵循该方案。
+
+当前方案的判定工具规则：
+
+${rules}`
+            : `# Gameplay mode and resolution scheme (fixed)
+
+The world under revision is tabletop, with resolution scheme ${label}. Its gameplay mode and scheme were fixed at creation; a revision cannot change control/gameplay.json. Numeric values and difficulty must follow this scheme.
+
+Check-tool rules for the current scheme:
+
+${rules}`;
+    const bag = gameplay.scheme === "bag" ? `\n\n${bagAuthoringGuidance(locale)}` : "";
+    return { source, markdown: `${markdown}${bag}` };
+}
+/**
+ * Authoring guidance for a chaos-bag scheme: the default bag, or a bag the world
+ * documents, and who maintains its contents. Only the bag scheme carries it.
+ */
+export function bagAuthoringGuidance(locale) {
+    return locale === "zh-CN"
+        ? `## 混乱袋内容
+
+- 默认袋：世界文档未定义标记时，判定使用默认袋：+1、0×2、-1×2、-2、大成功、大失败。
+- 世界自定义袋：在世界文档中写明每种标记的名称与数量，并且每种标记恰好写明修正值或大成功／大失败之一。判定时必须读取该清单，并原样提供。
+- 袋内容的变化由你在世界文档中维护。每次抽取后标记放回，抽取本身不改变袋。`
+        : `## Chaos-bag contents
+
+- Default bag: when the world documents define no tokens, the check uses the default bag: +1, 0 ×2, -1 ×2, -2, critical success, critical failure.
+- World-documented bag: write each token's label and count in the world documents, and give each token exactly one of a modifier or a critical outcome. Read that list and supply it exactly when checking.
+- You maintain any change to the bag's contents in the world documents. Each drawn token returns to the bag, so drawing never changes the bag itself.`;
+}
+/** The receipt sent after a successful gameplay write; it teaches the new scheme's rules mid-conversation. */
+export function tabletopSchemeReceipt(gameplay, locale) {
+    const rules = tabletopSchemeRules(gameplay, locale);
+    const receipt = locale === "zh-CN"
+        ? `新判定方案规则（之后请按此调整数值与难度）：\n\n${rules}`
+        : `New resolution-scheme rules (adjust numbers and difficulty to match from now on):\n\n${rules}`;
+    return gameplay.scheme === "bag"
+        ? `${receipt}\n\n${bagAuthoringGuidance(locale)}`
+        : receipt;
+}