@dsh-agentic-roleplay/state 0.3.1 → 0.3.2

package/lib/index.js

@@ -3,7 +3,7 @@ import { DatabaseSync } from "node:sqlite";
 import { dirname, join, resolve } from "node:path";
 import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
-import { randomUUID } from "node:crypto";
+import { randomInt, randomUUID } from "node:crypto";
 import { copyFileSync, existsSync, mkdirSync, readdirSync, renameSync, rmSync } from "node:fs";
 import { defineTool } from "@deepseek-ai/dsh-tools";
 //#region ../dsh-roleplay-model/src/character.ts
@@ -367,6 +367,31 @@ const TRIGGER_NOTE_KINDS = ["beat", "cue"];
 /** At most this many triggers in a story. */
 const MAX_TRIGGERS = 200;
 //#endregion
+//#region ../dsh-roleplay-model/src/dice.ts
+/** What a band of a check makes of an attempt; the same three results a round's outcome has. */
+const DICE_RESULTS = [
+	"succeeded",
+	"partial",
+	"failed"
+];
+/** How a roll is read: by its total, or by how many of the dice came up high enough. */
+const DICE_READINGS = ["total", "successes"];
+/**
+* What the value is compared with: `absolute` reads the value itself, `over` the amount by which it beats the target
+* (a difficulty to meet or exceed), `under` the amount by which it stays below the target (a skill to roll under).
+*/
+const DICE_COMPARISONS = [
+	"absolute",
+	"over",
+	"under"
+];
+/** Rolls and checks are limited so that a story cannot grow without bound. */
+const MAX_DICE_CHECKS = 40;
+const MAX_DICE_BANDS = 20;
+const MAX_DICE_PER_ROLL = 100;
+const MAX_DICE_SIDES = 1e3;
+const MAX_DICE_TERMS = 8;
+//#endregion
 //#region ../dsh-roleplay-model/src/visual.ts
 const VISUAL_SUBJECT_KINDS = [
 	"character",
@@ -445,6 +470,16 @@ const ZH = {
 	"age: {value}": "年龄：{value}",
 	"gender: {value}": "性别：{value}",
 	"pronouns: {value}": "代词：{value}",
+	"- {key} ({name}): {use}": "- {key}（{name}）：{use}",
+	"Rolls {dice}.": "掷 {dice}。",
+	"Give a target: the difficulty, the number to meet or beat; set it by how hard the attempt is.": "需给出 target：难度，即要达到或超过的数字；按这次尝试的难易来定。",
+	"Give a target: the number to stay under; set it by how hard the attempt is.": "需给出 target：要低于的数字；按这次尝试的难易来定。",
+	"It adds the character's {variable}.": "它会加上该角色的 {variable}。",
+	"Counts the dice that show {hit} or more.": "统计显示 {hit} 或更高的骰子数。",
+	"the player's roll": "玩家的掷骰",
+	"The player rolled {dice} ({reason}) and got {total}: dice {faces}. This is a fact, decided by the dice: take it into account when you judge the attempt and decide what happens.": "玩家掷了 {dice}（{reason}），得到 {total}：骰面 {faces}。这是由骰子决定的事实：在你判断这次尝试、决定发生什么时把它考虑进去。",
+	"The checks of this story:": "本故事的检定：",
+	"No checks are defined: use roll_dice only.": "没有定义检定：只用 roll_dice。",
 	"Situation:": "当前情形：",
 	"Now: {time}.": "现在是：{time}。",
 	"Where you are:": "你所在之处：",
@@ -542,7 +577,9 @@ const ZH = {
 	"{where}: say what it took in since that bears on it": "{where}：请写出此后与之相关的经历",
 	"{where}: thing {id} came before the belief was formed; cite what came after": "{where}：经历 {id} 发生在看法形成之前；请引用之后发生的事",
 	"{where}: say what changes": "{where}：请写出有何改变",
-	"{where}: the text must be there and at most {max} characters": "{where}：必须有文字，且最多 {max} 个字符",
+	"{where}: the text must be there and at most {max} characters; leave it out to keep the belief as it is": "{where}：文字不能为空，且最多 {max} 个字符；想保持信念原样就不要写这一项",
+	"{where}: the confidence, the importance and the numbers are fields of their own, not part of the text": "{where}：把握程度、重要性和编号是各自独立的字段，不属于文字",
+	"{where}: name what speaks against the belief in contradicted_by": "{where}：在 contradicted_by 里写出与该信念相悖的内容的编号",
 	"{where}: a belief that something contradicts must be doubted: lower its confidence": "{where}：被事实相悖的看法必须存疑：请降低其 confidence",
 	"{where}: to doubt a belief, name what contradicts it in contradicted_by": "{where}：要对看法存疑，请在 contradicted_by 中写明与之相悖的经历",
 	"{where}: merge into a belief that stays": "{where}：请合并到保留的看法中",
@@ -595,7 +632,9 @@ const ZH = {
 	"The time you had for \"{goal}\" has passed ({when}; it is {now} now)": "你为“{goal}”预留的时间已过（{when}；现在是{now}）",
 	"You are not with the player's character and nothing of this happens in front of anyone: decide what you do about it.": "你不和玩家的角色在一起，这件事也不会发生在任何人面前：决定你要怎么处理。",
 	"{names} noticed: {text}": "{names}注意到：{text}",
-	"{name} went to {place}.": "{name}去了{place}。"
+	"{name} went to {place}.": "{name}去了{place}。",
+	"## MCP resource servers\n\nUse {tools} with the server argument naming an MCP server.": "## MCP 资源服务器\n\n使用 {tools}，server 参数填 MCP 服务器的名称。",
+	"## MCP resource servers\n\nUse {tools} with one of these names as the server argument: {servers}.": "## MCP 资源服务器\n\n使用 {tools}，server 参数填下列名称之一：{servers}。"
 };
 //#endregion
 //#region ../dsh-roleplay-model/src/messages.ts
@@ -1084,7 +1123,7 @@ function seasonOf(day, hemisphere = "north") {
 	return north === "winter" ? "summer" : north === "summer" ? "winter" : north === "spring" ? "autumn" : "spring";
 }
 const key = (month, day) => month * 100 + day;
-function within(day, from, to) {
+function within$1(day, from, to) {
 	if (from.year !== void 0 && to.year !== void 0) {
 		const at = day.year * 1e4 + key(day.month, day.day);
 		return at >= from.year * 1e4 + key(from.month, from.day) && at <= to.year * 1e4 + key(to.month, to.day);
@@ -1099,7 +1138,7 @@ function matches(token, day, calendar) {
 		case "weekday": return day.weekday === token.weekday;
 		case "month": return day.month === token.month;
 		case "date": return day.month === token.month && day.day === token.day && (token.year === void 0 || day.year === token.year);
-		case "span": return within(day, token.from, token.to);
+		case "span": return within$1(day, token.from, token.to);
 		case "dom": return token.day === "last" ? day.day === daysIn(day.year, day.month) : day.day === token.day;
 		case "nth": return day.weekday === token.weekday && (token.n === "last" ? day.day + 7 > daysIn(day.year, day.month) : Math.ceil(day.day / 7) === token.n);
 		case "season": return seasonOf(day, calendar.hemisphere) === token.season;
@@ -7538,6 +7577,108 @@ var SqliteTriggerRepository = class {
 	}
 };
 //#endregion
+//#region src/sqlite/dice-repository.ts
+const MAX_ROLLS_LISTED = 200;
+function parseDefinition(text) {
+	try {
+		return JSON.parse(text);
+	} catch (error) {
+		throw new CorruptDataError("a dice check's definition is not valid JSON", { cause: error });
+	}
+}
+var SqliteDiceRepository = class {
+	db;
+	clock;
+	constructor(db, clock) {
+		this.db = db;
+		this.clock = clock;
+	}
+	define(definition) {
+		if ((this.db.get("SELECT count(*) AS count FROM dice_checks")?.count ?? 0) >= 40) throw new InvalidValueError(`a story has at most 40 dice checks`);
+		const { key, name, use, ...rest } = definition;
+		return guard(() => {
+			const { lastInsertRowid } = this.db.run("INSERT INTO dice_checks (key, name, use_text, definition) VALUES (?, ?, ?, ?)", [
+				key,
+				name,
+				use,
+				toJson(rest)
+			]);
+			return this.require(Number(lastInsertRowid));
+		});
+	}
+	checks() {
+		return this.db.all("SELECT * FROM dice_checks ORDER BY id").map((row) => this.toCheck(row));
+	}
+	check(key) {
+		const row = this.db.get("SELECT * FROM dice_checks WHERE key = ?", [key]);
+		return row === void 0 ? void 0 : this.toCheck(row);
+	}
+	removeCheck(key) {
+		if (this.db.run("DELETE FROM dice_checks WHERE key = ?", [key]).changes === 0) throw new NotFoundError(`there is no dice check "${key}"`);
+	}
+	record(roll) {
+		const at = this.clock().toISOString();
+		const { lastInsertRowid } = this.db.run("INSERT INTO dice_rolls (turn, check_key, expression, faces, kept, modifier, target, total, value, readout, reason, character, by, at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", [
+			roll.turn,
+			roll.check ?? null,
+			roll.expression,
+			toJson(roll.faces),
+			toJson(roll.kept),
+			roll.modifier,
+			roll.target ?? null,
+			roll.total,
+			roll.value,
+			roll.readout === void 0 ? null : toJson(roll.readout),
+			roll.reason,
+			roll.character ?? null,
+			roll.by,
+			at
+		]);
+		return {
+			...roll,
+			id: Number(lastInsertRowid),
+			at
+		};
+	}
+	rolls(filter = {}) {
+		const limit = Math.min(filter.limit ?? MAX_ROLLS_LISTED, MAX_ROLLS_LISTED);
+		return (filter.turn === void 0 ? this.db.all("SELECT * FROM (SELECT * FROM dice_rolls ORDER BY id DESC LIMIT ?) ORDER BY id", [limit]) : this.db.all("SELECT * FROM dice_rolls WHERE turn = ? ORDER BY id LIMIT ?", [filter.turn, limit])).map((row) => this.toRoll(row));
+	}
+	require(id) {
+		const row = this.db.get("SELECT * FROM dice_checks WHERE id = ?", [id]);
+		if (row === void 0) throw new NotFoundError(`there is no dice check ${id}`);
+		return this.toCheck(row);
+	}
+	toCheck(row) {
+		return {
+			id: row.id,
+			key: row.key,
+			name: row.name,
+			use: row.use_text,
+			...parseDefinition(row.definition)
+		};
+	}
+	toRoll(row) {
+		return {
+			id: row.id,
+			turn: row.turn,
+			expression: row.expression,
+			faces: parseNumberList(row.faces, "dice_rolls.faces"),
+			kept: parseNumberList(row.kept, "dice_rolls.kept"),
+			modifier: row.modifier,
+			total: row.total,
+			value: row.value,
+			reason: row.reason,
+			by: row.by,
+			at: row.at,
+			...row.check_key === null ? {} : { check: row.check_key },
+			...row.target === null ? {} : { target: row.target },
+			...row.readout === null ? {} : { readout: JSON.parse(row.readout) },
+			...row.character === null ? {} : { character: row.character }
+		};
+	}
+};
+//#endregion
 //#region src/sqlite/clock-repository.ts
 const toChange = (row) => ({
 	id: row.id,
@@ -8681,7 +8822,7 @@ var SqliteMetadataRepository = class {
 //#region src/sqlite/schema.ts
 /**
 * Migrations are applied in order and never edited once released (0.1.0 released
-* versions 1 to 6; tests/sqlite/migrate.spec.ts pins them): a change to the schema
+* versions 1 to 6; tests/sqlite/migrate.spec.ts pins the released ones): a change to the schema
 * is a new entry. Enumerations are spelled out so that a later change to the model
 * cannot alter what an old migration did.
 */
@@ -9260,6 +9401,36 @@ const MIGRATIONS = [
       ) STRICT;
       CREATE INDEX memory_evidence_perception ON memory_evidence (perception_id);
       ALTER TABLE routine_windows ADD COLUMN filters TEXT NOT NULL DEFAULT '[]';
+    `
+	},
+	{
+		version: 8,
+		sql: `
+      CREATE TABLE dice_checks (
+        id INTEGER PRIMARY KEY,
+        key TEXT NOT NULL UNIQUE,
+        name TEXT NOT NULL,
+        use_text TEXT NOT NULL,
+        definition TEXT NOT NULL
+      ) STRICT;
+      CREATE TABLE dice_rolls (
+        id INTEGER PRIMARY KEY,
+        turn INTEGER NOT NULL,
+        check_key TEXT,
+        expression TEXT NOT NULL,
+        faces TEXT NOT NULL,
+        kept TEXT NOT NULL,
+        modifier INTEGER NOT NULL,
+        target INTEGER,
+        total INTEGER NOT NULL,
+        value INTEGER NOT NULL,
+        readout TEXT,
+        reason TEXT NOT NULL,
+        character TEXT,
+        by TEXT NOT NULL CHECK (by IN ('agent', 'player')),
+        at TEXT NOT NULL
+      ) STRICT;
+      CREATE INDEX dice_rolls_turn ON dice_rolls (turn, id);
     `
 	}
 ];
@@ -10008,6 +10179,7 @@ var SqliteSessionStore = class {
 	routines;
 	engagements;
 	triggers;
+	dice;
 	recallIndex;
 	eventRepository;
 	constructor(db, clock, vectors) {
@@ -10038,6 +10210,7 @@ var SqliteSessionStore = class {
 		this.routines = new SqliteRoutineRepository(db);
 		this.engagements = new SqliteEngagementRepository(db);
 		this.triggers = new SqliteTriggerRepository(db);
+		this.dice = new SqliteDiceRepository(db, clock);
 		this.eventRepository = new SqliteEventRepository(db, clock, this.recallIndex, (id) => this.locations.get(id)?.name, (id) => this.items.get(id)?.name);
 		this.events = this.eventRepository;
 		this.memories = new SqliteMemoryRepository(db, clock, this.recallIndex);
@@ -10444,6 +10617,375 @@ function identityOf(database, storeOptions) {
 	}
 }
 //#endregion
+//#region src/records/dice.ts
+const systemRoller = (sides) => randomInt(1, sides + 1);
+const TERM = /^(?:(\d*)d(\d+|%)(?:(kh|kl|dh|dl)(\d*))?|(\d+))$/;
+/** Reads dice notation: `2d6+1`, `d20`, `4d6kh3`, `d%`, `1d8+1d4-1`. @throws {InvalidValueError} with what is wrong. */
+function parseNotation(input) {
+	const source = input.toLowerCase().replace(/\s+/g, "");
+	if (source === "") throw new InvalidValueError("dice notation is empty: write it like 2d6+1");
+	const parts = source.split(/(?=[+-])/);
+	if (parts.length > 8) throw new InvalidValueError(`dice notation has more than 8 terms`);
+	const terms = parts.map((part, index) => {
+		const sign = part.startsWith("-") ? -1 : 1;
+		const body = part.replace(/^[+-]/, "");
+		if (index > 0 && !/^[+-]/.test(part)) throw new InvalidValueError(`"${input}" is not dice notation: write it like 2d6+1`);
+		const match = TERM.exec(body);
+		if (match === null) throw new InvalidValueError(`"${part}" is not dice notation: write it like 2d6+1, 4d6kh3 or d100`);
+		if (match[5] !== void 0) return {
+			sign,
+			constant: Number(match[5])
+		};
+		const count = match[1] === "" || match[1] === void 0 ? 1 : Number(match[1]);
+		const sides = match[2] === "%" ? 100 : Number(match[2]);
+		if (count < 1 || count > 100) throw new InvalidValueError(`"${part}": roll from 1 to 100 dice at a time`);
+		if (sides < 2 || sides > 1e3) throw new InvalidValueError(`"${part}": a die has from 2 to ${MAX_DICE_SIDES} sides`);
+		const mode = match[3];
+		if (mode === void 0) return {
+			sign,
+			count,
+			sides
+		};
+		const n = match[4] === "" || match[4] === void 0 ? 1 : Number(match[4]);
+		if (n < 1 || n >= count) throw new InvalidValueError(`"${part}": ${mode.startsWith("k") ? "keep" : "drop"} at least 1 and fewer than the ${count} dice`);
+		return {
+			sign,
+			count,
+			sides,
+			keep: {
+				mode,
+				n
+			}
+		};
+	});
+	if (!terms.some((term) => "sides" in term)) throw new InvalidValueError(`"${input}" has no dice: write it like 2d6+1`);
+	return {
+		text: source,
+		terms
+	};
+}
+/** The lowest and highest total the dice and constants can give. */
+function notationRange(notation) {
+	let min = 0;
+	let max = 0;
+	for (const term of notation.terms) {
+		if ("constant" in term) {
+			min += term.sign * term.constant;
+			max += term.sign * term.constant;
+			continue;
+		}
+		const kept = term.keep === void 0 ? term.count : term.keep.mode.startsWith("k") ? term.keep.n : term.count - term.keep.n;
+		const low = kept;
+		const high = kept * term.sides;
+		min += term.sign === 1 ? low : -high;
+		max += term.sign === 1 ? high : -low;
+	}
+	return {
+		min,
+		max
+	};
+}
+function keepOf(faces, keep) {
+	const ordered = faces.map((face, index) => ({
+		face,
+		index
+	})).sort((a, b) => a.face - b.face || a.index - b.index);
+	const count = keep.mode.startsWith("k") ? keep.n : faces.length - keep.n;
+	return (keep.mode === "kh" || keep.mode === "dl" ? ordered.slice(ordered.length - count) : ordered.slice(0, count)).sort((a, b) => a.index - b.index).map((entry) => entry.face);
+}
+function rollNotation(notation, roll = systemRoller) {
+	const faces = [];
+	const kept = [];
+	let constant = 0;
+	let total = 0;
+	for (const term of notation.terms) {
+		if ("constant" in term) {
+			constant += term.sign * term.constant;
+			total += term.sign * term.constant;
+			continue;
+		}
+		const thrown = Array.from({ length: term.count }, () => roll(term.sides));
+		const counted = term.keep === void 0 ? thrown : keepOf(thrown, term.keep);
+		faces.push(...thrown);
+		kept.push(...counted);
+		total += term.sign * counted.reduce((sum, face) => sum + face, 0);
+	}
+	return {
+		faces,
+		kept,
+		constant,
+		total
+	};
+}
+const within = (band, value) => (band.min === void 0 || value >= band.min) && (band.max === void 0 || value <= band.max);
+/** What the bands of a check make of a value. @throws {InvalidValueError} when no band holds it. */
+function readBands(bands, value) {
+	const band = bands.find((candidate) => within(candidate, value));
+	if (band === void 0) throw new InvalidValueError(`no band of this check holds ${value}: the check's bands leave a gap`);
+	return {
+		label: band.label,
+		result: band.result,
+		critical: band.critical === true
+	};
+}
+/**
+* Rolls a check: the dice, the character's modifier and any bonus added, then the value read against the bands. With the reading
+* `successes` the total is the number of dice that hit. A check read against a target needs one.
+* @throws {InvalidValueError} for a target a check needs and is not given, or bands that leave the value unread.
+*/
+function rollCheck(check, input, roll = systemRoller) {
+	const rolled = rollNotation(parseNotation(check.dice), roll);
+	const comparison = check.compare ?? "absolute";
+	if (comparison !== "absolute" && input.target === void 0) throw new InvalidValueError(`the check "${check.key}" is read against a target (${comparison === "over" ? "the number to meet or beat" : "the number to stay under"}): give one`);
+	const added = (input.modifier ?? 0) + (input.bonus ?? 0);
+	const total = check.reading === "successes" ? rolled.kept.filter((face) => face >= (check.hit ?? 0)).length + (input.bonus ?? 0) : rolled.total + added;
+	const value = comparison === "over" ? total - (input.target ?? 0) : comparison === "under" ? (input.target ?? 0) - total : total;
+	return {
+		faces: rolled.faces,
+		kept: rolled.kept,
+		modifier: check.reading === "successes" ? input.bonus ?? 0 : rolled.constant + added,
+		...input.target === void 0 ? {} : { target: input.target },
+		total,
+		value,
+		readout: readBands(check.bands, value)
+	};
+}
+/** What is wrong with a check as a world defines it; nothing when it is sound. */
+function checkProblems(check) {
+	const problems = [];
+	if (!/^[a-z][a-z0-9_-]{0,39}$/.test(check.key)) problems.push(`the key "${check.key}" must be lower-case letters, digits, - or _, starting with a letter`);
+	if (check.name.trim() === "") problems.push("it needs a name");
+	if (check.use.trim() === "") problems.push("it needs a \"use\": when the game master rolls it");
+	if (check.compare !== void 0 && !DICE_COMPARISONS.includes(check.compare)) problems.push(`"compare" must be one of: ${DICE_COMPARISONS.join(", ")}`);
+	if (check.reading !== void 0 && !DICE_READINGS.includes(check.reading)) problems.push(`"reading" must be one of: ${DICE_READINGS.join(", ")}`);
+	let notation;
+	try {
+		notation = parseNotation(check.dice);
+	} catch (error) {
+		problems.push(`"dice": ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (check.bands.length === 0) problems.push("it needs at least one band");
+	if (check.bands.length > 20) problems.push(`it has more than 20 bands`);
+	check.bands.forEach((band, index) => {
+		if (band.label.trim() === "") problems.push(`band ${index + 1} needs a label`);
+		if (!DICE_RESULTS.includes(band.result)) problems.push(`band ${index + 1}: "result" must be one of: ${DICE_RESULTS.join(", ")}`);
+		if (band.min !== void 0 && band.max !== void 0 && band.min > band.max) problems.push(`band ${index + 1}: min is above max`);
+	});
+	if (check.reading === "successes") {
+		const sides = notation?.terms.flatMap((term) => "sides" in term ? [term.sides] : []) ?? [];
+		if (check.hit === void 0 || !Number.isInteger(check.hit) || check.hit < 1 || sides.length > 0 && check.hit > Math.max(...sides)) problems.push("the reading \"successes\" needs \"hit\": the lowest face that counts");
+	}
+	if (notation !== void 0 && problems.length === 0 && (check.compare ?? "absolute") === "absolute" && check.modifier === void 0) {
+		const { min, max } = check.reading === "successes" ? {
+			min: 0,
+			max: notation.terms.reduce((sum, term) => sum + ("count" in term ? term.count : 0), 0)
+		} : notationRange(notation);
+		for (let value = min; value <= max; value += 1) if (!check.bands.some((band) => within(band, value))) {
+			problems.push(`no band holds ${value}, which the dice can give`);
+			break;
+		}
+	}
+	return problems;
+}
+function rollPlain(expression, roll = systemRoller) {
+	const notation = parseNotation(expression);
+	const rolled = rollNotation(notation, roll);
+	return {
+		expression: notation.text,
+		faces: rolled.faces,
+		kept: rolled.kept,
+		modifier: rolled.constant,
+		total: rolled.total
+	};
+}
+//#endregion
+//#region src/tools/dice.ts
+const ROLL_DICE_TOOL = "roll_dice";
+const ROLL_CHECK_TOOL = "roll_check";
+const LIST_CHECKS_TOOL = "list_checks";
+const sign = (value) => value >= 0 ? `+${value}` : String(value);
+/** How a roll reads to the agent that asked for it: what fell, what it adds up to, and what the world's check makes of it. */
+function describeRoll(roll, check) {
+	const dice = `[${roll.faces.join(", ")}]${roll.kept.length < roll.faces.length ? ` keeping [${roll.kept.join(", ")}]` : ""}`;
+	const lines = [`Roll ${roll.id}: ${roll.expression}${check === void 0 ? "" : ` for the check "${check.name}"`}${roll.character === void 0 ? "" : ` (${roll.character})`} - ${dice}${roll.modifier === 0 ? "" : ` ${sign(roll.modifier)}`} = ${roll.total}${check?.reading === "successes" ? " successes" : ""}.`];
+	if (roll.target !== void 0) lines.push(`Against ${roll.target}: ${roll.value >= 0 ? "+" : ""}${roll.value}.`);
+	if (roll.readout !== void 0) lines.push(`That is: ${roll.readout.label}${roll.readout.critical ? " (critical)" : ""}; the result is ${roll.readout.result}. This is decided by the dice: do not change it, narrate it.${check === void 0 || roll.character === void 0 ? "" : ` In resolve_round give ${roll.character}'s outcome this result and cite the roll: roll ${roll.id}.`}`);
+	return lines.join(" ");
+}
+const rolled = (_args, value) => [{
+	type: "text",
+	text: value.text
+}];
+/**
+* Tools that roll dice for an agent, so that numbers are not made up. `roll_check` rolls a check the story defines and reads
+* the result with the check's own bands; `roll_dice` rolls plain notation for what has no check. The roller is the system's
+* source of randomness unless one is given.
+*/
+function createDiceTools(resolve, options = {}) {
+	const roller = options.roller ?? systemRoller;
+	const linkOf = (agent) => {
+		const found = agent === void 0 ? void 0 : resolve(agent.session.id);
+		if (found === void 0) throw new NotFoundError("this agent is not working in a roleplay session, so there are no dice to roll");
+		return found;
+	};
+	return [
+		defineTool({
+			name: LIST_CHECKS_TOOL,
+			description: "List the checks this story defines for settling uncertain attempts: when each is used, the dice it rolls and how its result is read.",
+			parameters: {},
+			output: {
+				schema: { type: "json" },
+				render: (_args, value) => [{
+					type: "text",
+					text: JSON.stringify(value, null, 2)
+				}]
+			},
+			isConcurrencySafe: () => true,
+			execute(_args, exec) {
+				const { session } = linkOf(exec.agent);
+				return Promise.resolve(session.dice.checks().map((check) => ({
+					key: check.key,
+					name: check.name,
+					use: check.use,
+					dice: check.dice,
+					compare: check.compare ?? "absolute",
+					...check.modifier === void 0 ? {} : { modifier: `the character's ${check.modifier}` },
+					bands: check.bands.map((band) => ({
+						...band.min === void 0 ? {} : { from: band.min },
+						...band.max === void 0 ? {} : { to: band.max },
+						label: band.label,
+						result: band.result
+					}))
+				})));
+			}
+		}),
+		defineTool({
+			name: ROLL_CHECK_TOOL,
+			description: "Roll one of the story's checks for an attempt whose outcome is uncertain and matters: the dice are rolled for you and the result is read with the check's own bands, so you never choose or make up a number. Use the check whose \"use\" fits (list_checks shows them). Roll once per attempt, before you decide what happens, and let the result stand: a failed roll is a failure, whatever the story would like.",
+			parameters: {
+				check: {
+					type: "string",
+					required: true,
+					description: "The key of the check, as list_checks gives it."
+				},
+				reason: {
+					type: "string",
+					required: true,
+					description: "What is attempted, by whom, in a sentence."
+				},
+				character: {
+					type: "string",
+					required: true,
+					description: "The key of the character the attempt is for (the player's character included): the roll is theirs, and their outcome in resolve_round takes its result from it."
+				},
+				target: {
+					type: "integer",
+					description: "When the check is read against a target (list_checks says compare over or under): the difficulty, the number the total must meet or beat (or stay under). Set it by how hard the attempt is, using what the check's \"use\" says about difficulty; never 0 to make it easy."
+				},
+				bonus: {
+					type: "integer",
+					description: "What the circumstances add to or take from the roll, from -10 to 10; leave out for none."
+				}
+			},
+			output: {
+				schema: { type: "json" },
+				render: rolled
+			},
+			isConcurrencySafe: () => false,
+			execute(args, exec) {
+				const { session, turn } = linkOf(exec.agent);
+				const check = session.dice.check(args.check);
+				if (check === void 0) throw new NotFoundError(`there is no check "${args.check}"; list_checks shows the story's checks`);
+				if (session.characters.list().every((entry) => characterKey(entry) !== args.character)) throw new NotFoundError(`there is no character "${args.character}"; list_characters shows the keys`);
+				let modifier;
+				if (check.modifier !== void 0) {
+					const who = session.characters.list().find((entry) => characterKey(entry) === args.character);
+					if (who === void 0) throw new NotFoundError(`there is no character "${args.character}"; list_characters shows the keys`);
+					const value = session.variables.value(check.modifier, "character", who.id);
+					if (typeof value !== "number") throw new NotFoundError(`the character's ${check.modifier} is not a number, so the check cannot add it`);
+					modifier = value;
+				}
+				const bonus = Math.max(-10, Math.min(10, args.bonus ?? 0));
+				const made = rollCheck(check, {
+					...modifier === void 0 ? {} : { modifier },
+					bonus,
+					...args.target === void 0 ? {} : { target: args.target }
+				}, roller);
+				const roll = session.dice.record({
+					turn,
+					check: check.key,
+					expression: check.dice,
+					faces: made.faces,
+					kept: made.kept,
+					modifier: made.modifier,
+					...made.target === void 0 ? {} : { target: made.target },
+					total: made.total,
+					value: made.value,
+					readout: made.readout,
+					reason: args.reason,
+					character: args.character,
+					by: options.by ?? "agent"
+				});
+				return Promise.resolve({
+					roll: roll.id,
+					check: check.key,
+					total: roll.total,
+					result: made.readout.result,
+					label: made.readout.label,
+					critical: made.readout.critical,
+					text: describeRoll(roll, check)
+				});
+			}
+		}),
+		defineTool({
+			name: ROLL_DICE_TOOL,
+			description: "Roll dice for something the story has no check for (damage, a random pick, who goes first, a rumour table): the dice are rolled for you, so you never make up a number. Write the notation like 1d6, 2d4+1, 4d6kh3 (keep the highest 3) or d100. What the number means is for you to decide from the rules you were given; when a check fits the attempt, use roll_check instead.",
+			parameters: {
+				expression: {
+					type: "string",
+					required: true,
+					description: "Dice notation, for example 2d6+1."
+				},
+				reason: {
+					type: "string",
+					required: true,
+					description: "What the roll is for, in a sentence."
+				},
+				character: {
+					type: "string",
+					description: "The key of the character it is for, when it is for one."
+				}
+			},
+			output: {
+				schema: { type: "json" },
+				render: rolled
+			},
+			isConcurrencySafe: () => false,
+			execute(args, exec) {
+				const { session, turn } = linkOf(exec.agent);
+				const made = rollPlain(args.expression, roller);
+				const roll = session.dice.record({
+					turn,
+					expression: made.expression,
+					faces: made.faces,
+					kept: made.kept,
+					modifier: made.modifier,
+					total: made.total,
+					value: made.total,
+					reason: args.reason,
+					...args.character === void 0 ? {} : { character: args.character },
+					by: options.by ?? "agent"
+				});
+				return Promise.resolve({
+					roll: roll.id,
+					total: roll.total,
+					text: describeRoll(roll)
+				});
+			}
+		})
+	];
+}
+//#endregion
 //#region src/records/lint.ts
 /**
 * What is inconsistent or unfinished in the world's graph of places and characters. Things made up in
@@ -12031,7 +12573,8 @@ function createTools(resolve, options) {
 //#region src/plugin.ts
 const Config = z.object({
 	journalMode: z.union(["delete", "wal"]).default("delete"),
-	writeTools: z.boolean().default(false)
+	writeTools: z.boolean().default(false),
+	diceTools: z.boolean().default(false)
 });
 /**
 * Roleplay session state for other plugins. It creates and opens sessions
@@ -12057,6 +12600,7 @@ var RoleplayState = class extends Service {
 		};
 		ctx.inject(["tools"], (scope) => {
 			for (const tool of createTools(resolve, { write: config.writeTools ?? false })) scope.tools.register(tool);
+			if (config.diceTools === true) for (const tool of createDiceTools(resolve)) scope.tools.register(tool);
 		});
 	}
 	/**
@@ -12192,6 +12736,7 @@ var RoleplayState = class extends Service {
 			routines: store.routines,
 			engagements: store.engagements,
 			triggers: store.triggers,
+			dice: store.dice,
 			planMove: (characterId, move) => store.planMove(characterId, move),
 			planKnownMove: (characterId, move) => store.planKnownMove(characterId, move),
 			move: (characterId, move) => store.move(characterId, move),
@@ -12461,6 +13006,6 @@ function createCharacterTools(link, characterId) {
 	];
 }
 //#endregion
-export { ACCURACIES, CHARACTER_CONTROLS, CHARACTER_KINDS, CHARACTER_ROLES, CHARACTER_TIERS, CLOCK_MODES, COMPARISONS, CONSOLIDATION_KINDS, CONTAINER_STATES, Config, ConflictError, CorruptDataError, DAY, DAY_PARTS, DEFAULT_CONFIDENCE, DEFAULT_MEMORY_POLICY, DEFAULT_SLOTS, EMOTION_VARIABLES, ENGAGEMENT_GRACE, ENGAGEMENT_STATUSES, EVIDENCE_RELATIONS, EXIT_STATES, HOUR, IMPORTANCE_MAX, IMPORTANCE_MIN, INTENT_HORIZONS, INTENT_STATUSES, INTENT_TYPES, ITEM_ACTIONS, InvalidEditError, InvalidMoveError, InvalidValueError, KNOWLEDGE_KINDS, LANGUAGES, LORE_KINDS, LORE_SUBJECT_KINDS, MAX_LOCATION_FEATURES, MAX_ROUTINE_WINDOWS, MAX_SHOWN, MAX_TRIGGERS, MAX_VARIABLES, MEMBERSHIP_STATUSES, MEMORY_CONFIDENCES, MEMORY_KINDS, MIGRATION_BACKUP_FOLDER, MINUTE, MONTH_NAMES, NO_CALENDAR, NotFoundError, PERCEPTION_MODES, PLACEABLE_KINDS, PLOT_NUDGE_MODES, PLOT_STATUSES, RECALL_ITEM_KINDS, RoleplayState, LATEST_VERSION as SCHEMA_VERSION, SEASONS, SECOND, SELF, SESSION_DATABASE_FILE, SLOT_ID, SUMMARY_LEVELS, SchemaError, StateError, TEMPLATE_KINDS, THREAD_STATUSES, TIME_CHANGE_KINDS, TRIGGER_NOTE_KINDS, TRIGGER_STATUSES, UnwritableError, VARIABLE_KEY, VARIABLE_KINDS, VARIABLE_SUBJECTS, VARIABLE_VISIBILITIES, VISUAL_SUBJECT_KINDS, WEEKDAY_NAMES, addLocalDays, agendaAt, announcements, apply, applyItemPlan, applyRecordsEdit, audienceIds, catchUpPlan, changeItem, changeVariable, characterKey, clarityAt, clockTime, conditionHolds, createCharacterTools, createSession, createSessionStore, createTools, dayMatches, dayPart, dayTokenProblems, deleteSession, deliverNotes, denseScore, describeDuration, describeHolder, describeInstant, describeValue, finishRecall, fuseScores, holidaysOn, inAudience, inWindow, isSessionId, isTimeZone, itemKey, jitter, judgedStatements, languageOf, lapseNotes, lintWorld, listSessions, localIso, localTime, locationKey, mentioned, migrationBackupPath, moveCharacter, name, nextOccurrence, nextTimeOfDay, nodeSqliteDriver, occurrenceAt, openSession, openSessionStore, overlap, parseDayToken, parseInstant, parseRecordsEdit, parseTimeOfDay, parseTriggerDefinition, placeholdersOf, planItemChange, planKnownMove, planMove, planVariableChange, poolCandidates, rankGoals, readCalendar, readRecords, readTriggerDefinition, recall, recallCandidates, recallPool, recordsEditSchema, renderWords, retention, runTriggers, seasonOf, seededRoll, sessionDatabase, sessionFolder, shownVariables, subjectOf, systemClock, systemTimeZone, tokens, translated, translation, translator, triggerReferenceProblems, valueIssue, writeCalendar, zonedInstant };
+export { ACCURACIES, CHARACTER_CONTROLS, CHARACTER_KINDS, CHARACTER_ROLES, CHARACTER_TIERS, CLOCK_MODES, COMPARISONS, CONSOLIDATION_KINDS, CONTAINER_STATES, Config, ConflictError, CorruptDataError, DAY, DAY_PARTS, DEFAULT_CONFIDENCE, DEFAULT_MEMORY_POLICY, DEFAULT_SLOTS, DICE_COMPARISONS, DICE_READINGS, DICE_RESULTS, EMOTION_VARIABLES, ENGAGEMENT_GRACE, ENGAGEMENT_STATUSES, EVIDENCE_RELATIONS, EXIT_STATES, HOUR, IMPORTANCE_MAX, IMPORTANCE_MIN, INTENT_HORIZONS, INTENT_STATUSES, INTENT_TYPES, ITEM_ACTIONS, InvalidEditError, InvalidMoveError, InvalidValueError, KNOWLEDGE_KINDS, LANGUAGES, LIST_CHECKS_TOOL, LORE_KINDS, LORE_SUBJECT_KINDS, MAX_DICE_BANDS, MAX_DICE_CHECKS, MAX_DICE_PER_ROLL, MAX_DICE_SIDES, MAX_DICE_TERMS, MAX_LOCATION_FEATURES, MAX_ROUTINE_WINDOWS, MAX_SHOWN, MAX_TRIGGERS, MAX_VARIABLES, MEMBERSHIP_STATUSES, MEMORY_CONFIDENCES, MEMORY_KINDS, MIGRATION_BACKUP_FOLDER, MINUTE, MONTH_NAMES, NO_CALENDAR, NotFoundError, PERCEPTION_MODES, PLACEABLE_KINDS, PLOT_NUDGE_MODES, PLOT_STATUSES, RECALL_ITEM_KINDS, ROLL_CHECK_TOOL, ROLL_DICE_TOOL, RoleplayState, LATEST_VERSION as SCHEMA_VERSION, SEASONS, SECOND, SELF, SESSION_DATABASE_FILE, SLOT_ID, SUMMARY_LEVELS, SchemaError, StateError, TEMPLATE_KINDS, THREAD_STATUSES, TIME_CHANGE_KINDS, TRIGGER_NOTE_KINDS, TRIGGER_STATUSES, UnwritableError, VARIABLE_KEY, VARIABLE_KINDS, VARIABLE_SUBJECTS, VARIABLE_VISIBILITIES, VISUAL_SUBJECT_KINDS, WEEKDAY_NAMES, addLocalDays, agendaAt, announcements, apply, applyItemPlan, applyRecordsEdit, audienceIds, catchUpPlan, changeItem, changeVariable, characterKey, checkProblems, clarityAt, clockTime, conditionHolds, createCharacterTools, createDiceTools, createSession, createSessionStore, createTools, dayMatches, dayPart, dayTokenProblems, deleteSession, deliverNotes, denseScore, describeDuration, describeHolder, describeInstant, describeRoll, describeValue, finishRecall, fuseScores, holidaysOn, inAudience, inWindow, isSessionId, isTimeZone, itemKey, jitter, judgedStatements, languageOf, lapseNotes, lintWorld, listSessions, localIso, localTime, locationKey, mentioned, migrationBackupPath, moveCharacter, name, nextOccurrence, nextTimeOfDay, nodeSqliteDriver, notationRange, occurrenceAt, openSession, openSessionStore, overlap, parseDayToken, parseInstant, parseNotation, parseRecordsEdit, parseTimeOfDay, parseTriggerDefinition, placeholdersOf, planItemChange, planKnownMove, planMove, planVariableChange, poolCandidates, rankGoals, readBands, readCalendar, readRecords, readTriggerDefinition, recall, recallCandidates, recallPool, recordsEditSchema, renderWords, retention, rollCheck, rollNotation, rollPlain, runTriggers, seasonOf, seededRoll, sessionDatabase, sessionFolder, shownVariables, subjectOf, systemClock, systemRoller, systemTimeZone, tokens, translated, translation, translator, triggerReferenceProblems, valueIssue, writeCalendar, zonedInstant };
 
 //# sourceMappingURL=index.js.map