@fitchmultz/pi-calculator 0.0.0-stage → 4.1.2

package/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+## 4.1.2 - 2026-10-31
+
+- Refresh installation and reference documentation while preserving unpinned npm and Git sources and migration guidance.
+- Refresh the development lockfile and compatibility workflow references.
+
+## 4.1.1 - 2026-10-04
+
+- Publish the existing calculator as the public scoped package `@fitchmultz/pi-calculator`, continuing the 4.1.x version line. The unrelated unscoped npm package is not this project.
+- Lead installation guidance with the scoped npm source while preserving Git installation, existing tags, and the calculator's numerical, schema, structured-result, rendering, and native-composition contracts.
+- Qualify the latest stable official Pi and maintained fork main with once-frozen host identities, and add a main-only gated repository release pipeline.
+
+## 4.1.0 - 2026-10-01
+
+- Require Pi 1.0.0 and qualify its exact published cohort with host TypeBox 1.3.27.
+- Expose the existing expression/value outcome through native structured output for nested callers, preserving decimal strings, scalar/array behavior, grammar, work limits, errors, and rendering.
+- Exercise native nested scalar/array receipts and distinct validation, policy, and evaluation failures without provider calls. Keep Git/GitHub-only distribution.
+
+## 4.0.0 - 2026-09-26
+
+### Breaking changes
+
+- Require Node.js 24 or later.
+
+### Changed
+
+- Qualify development against Pi 0.87.1 and the TypeBox version Pi ships (1.3.27), on Node 24 for both official Pi and the maintained fork.
+- Type-check with Node 24 types and explicit Node module resolution under TypeScript 7.
+
+## 3.0.0 - 2026-09-21
+
+### Breaking changes
+
+- Replace `deg(x)` with `radians(x)` for degrees-to-radians conversion, and `rad(x)` with `degrees(x)` for radians-to-degrees conversion. The old names are removed without aliases.
+- Return value-only model content instead of `expression = value`. Details retain the trimmed expression and a value that can now be a decimal string or an array of decimal strings.
+
+### Added
+
+- Evaluate independent calculations in one flat array. Reject nested, nonnumeric, or nonfinite results as a whole, and reject serialized expression/value details larger than 50 KiB.
+- Show safely escaped expressions in native Pi tool cards while keeping model output concise.
+- Request native strict-prefer JSON-schema sampling with provider-controlled fallback.
+
+### Changed
+
+- Pass Decimal values directly through the parser while preserving decimal-literal precision, numerical algorithms, private contexts, and work limits.
+- Clarify percentage argument order, population/sample standard deviation, logarithm bases, small-argument `expm1`/`log1p`, and when to combine calculations or skip a trivial tool call.
+- Qualify development against Pi 0.87.0 and TypeBox 1.3.34; declare host-provided Pi TUI as an optional peer. The package remains private and Git-distributed.
+
+### Fixed
+
+- Require finite inputs consistently for aggregates, including `min`, `max`, and `hypot`/`pyt`.
+
+## 2.0.2 - 2026-09-18
+
+### Fixed
+
+- Preserve tangent accuracy near poles by dividing guarded sine and cosine values.
+- Preserve cancellation remainders in sums without allocating across large exponent gaps, and round means and even medians only after division.
+- Center standard-deviation calculations before averaging so identical measurements have zero spread and large common offsets do not distort the result.
+- Reject non-finite measurements in statistics, including medians that previously hid invalid square roots or division by zero.
+
+### Added
+
+- Regression checks for numeric correctness and GitHub CI verification on the minimum supported Node version and Node 24.
+
+## 2.0.1 - 2026-08-08
+
+### Fixed
+
+- Restrict evaluation to null-prototype deterministic allowlists instead of inheriting broken parser functions, operators, or object properties.
+- Evaluate supported scientific helpers in a private Decimal context, including cancellation-safe `expm1`/`log1p`, hyperbolic functions, `pow`, `atan2`, `sum`, `sign`, and `trunc`.
+- Return the requested element for array indexes instead of always coercing wrapped indexes to zero.
+- Preserve single-quoted numeric strings and quoted `**` text during literal rewriting, and reject unsupported comments.
+- Accept negative zero factorials, correctly round factorials once from an exact BigInt result, and reject extra function arguments.
+- Restore the full 40-digit `E` constant, round input literals to the documented precision, reset Decimal state after every evaluation, cap nesting deterministically, and replace raw dependency errors with stable calculator errors.
+- Disable member access and unadvertised conditional, comparison, logical, higher-order, random, string-escape, comment, and multi-expression operations.
+- Bound circular and hyperbolic trig operands plus modulo exponent gaps with a shared work budget to prevent synchronous CPU amplification.
+
+### Changed
+
+- Keep only stable expression and value fields in tool details and trim always-on prompt guidance.
+- Limit npm package contents to runtime source and documentation.
+
+## 2.0.0 - 2026-08-06
+
+### Changed
+
+- Require Pi 0.84.0 or later.
+- Import the host-provided TypeBox package directly, following the Pi 0.84 extension contract.
+- Format very large integers in scientific notation so calculator output stays below Pi's 50KB tool-output limit.
+- Keep evaluation details JSON-safe by removing the lossy JavaScript number conversion.
+- Escape line breaks in displayed expressions so tool results stay within Pi's 2,000-line output limit.
+
+### Added
+
+- Type checking and an actual Pi 0.84 extension-load check to the release verification command.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mitchell Fultz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,67 @@
-# Temporary Holding Version
+# pi-calculator
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+pi-calculator adds a calculator tool to [Pi](https://github.com/earendil-works/pi), with 40 significant digits of decimal precision. Use it to check totals or evaluate scientific expressions.
+
+![Pi sends an expression to the calculator, which returns a decimal result or rejects an invalid expression.](.github/readme/calculator-flow.png)
+
+## Install and try it
+
+Use Node.js and a supported Pi release. See the [compatibility requirements](https://github.com/fitchmultz/pi-calculator/blob/main/docs/reference.md#installation-options).
+
+```sh
+pi install npm:@fitchmultz/pi-calculator
+pi
+```
+
+Enter this prompt in the new Pi session:
+
+```text
+Use the calculator to evaluate [0.1 + 0.2, 2^64].
+```
+
+The calculator tool returns `["0.3","18446744073709551616"]`.
+
+See [installation options](docs/reference.md#installation-options) for Git installs or a change from Git to npm.
+
+Pi extensions run with full system access. Review the source before you install the package.
+
+## Expressions
+
+Try these expressions:
+
+```text
+percent(15, 200)                 → 30
+roundTo(-1.25, 1)                → -1.3
+mean([2,4,6,8])                  → 5
+sin(radians(90))                 → 1
+sum([1e40,1,-1e40])              → 1
+(12.5 * 1.0825) ^ 3              → 2477.500518798828125
+```
+
+Arithmetic supports `+`, `-`, `*`, `/`, `%`, `^` and `**`, with `PI` and `E` as constants. Put independent calculations in one flat array, as in the first example.
+
+Trig uses radians. Use `radians()` to convert degrees to radians. Use `degrees()` to convert radians to degrees.
+
+`roundTo(value, places)` rounds half values away from zero. Use negative places to round to tens, hundreds or larger units.
+
+See the [expression reference](docs/reference.md#expressions) for all functions and array indexing.
+
+## Results and limits
+
+Results are decimal strings, or a flat array of decimal strings. Input numbers and arithmetic use half-up rounding. Large finite results use scientific notation.
+
+The calculator tool rejects invalid expressions, nonfinite results and nested result arrays. If one result in an array is invalid, the calculator tool rejects the whole expression.
+
+Keep expressions within 4,096 characters. See [limits](docs/reference.md#limits) for nesting, output size and work budgets.
+
+See [result format](docs/reference.md#result-format) to use the calculator tool from another extension.
+
+Read the [migration notes](https://github.com/fitchmultz/pi-calculator/blob/main/docs/reference.md#migration) before upgrading.
+
+## Verification
+
+See the [development guide](docs/development.md) for local checks and Pi compatibility tests. See the [changelog](CHANGELOG.md) for release history.
+
+## License
+
+[MIT](LICENSE) © Mitchell Fultz.

package/decimal.ts

@@ -0,0 +1,91 @@
+import { Decimal as DecimalBase } from "decimal.js";
+
+export const DECIMAL_PRECISION = 40;
+export const MAX_EXPRESSION_DEPTH = 128;
+const DECIMAL_CONFIG = {
+	defaults: true,
+	precision: DECIMAL_PRECISION,
+	rounding: DecimalBase.ROUND_HALF_UP,
+} as const;
+export const Decimal = DecimalBase.clone(DECIMAL_CONFIG);
+export type DecimalValue = DecimalBase;
+
+export function resetDecimal(): void {
+	Decimal.set(DECIMAL_CONFIG);
+}
+
+const DECIMAL_LITERAL = /^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/i;
+
+function decimalFromString(value: string): DecimalValue {
+	if (!DECIMAL_LITERAL.test(value)) throw new Error("invalid decimal literal");
+	const decimal = new Decimal(value);
+	if (!decimal.isFinite()) throw new Error("decimal literal overflow");
+	if (decimal.isZero() && /[1-9]/.test(value.replace(/[eE].*$/, ""))) {
+		throw new Error("decimal literal underflow");
+	}
+	const rounded = decimal.toSignificantDigits(DECIMAL_PRECISION);
+	if (!rounded.isFinite()) throw new Error("decimal literal overflow");
+	if (rounded.isZero() && !decimal.isZero()) throw new Error("decimal literal underflow");
+	return rounded;
+}
+
+export function toDec(value: unknown): DecimalValue {
+	if (value instanceof Decimal) return value;
+	if (typeof value === "string") return decimalFromString(value);
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new Error("non-finite number");
+		return new Decimal(String(value));
+	}
+	throw new Error(`expected number, got ${typeof value}`);
+}
+
+/** Preserve numeric literal precision and normalize ** outside quoted strings. */
+export function decimalizeExpression(expression: string): string {
+	if (expression.includes("\\")) throw new Error("escape sequences are not supported");
+
+	let result = "";
+	let i = 0;
+	let nestingDepth = 0;
+
+	while (i < expression.length) {
+		const ch = expression[i]!;
+
+		if (ch === '"' || ch === "'") {
+			const end = expression.indexOf(ch, i + 1);
+			if (end < 0) throw new Error("unclosed string in expression");
+			result += expression.slice(i, end + 1);
+			i = end + 1;
+			continue;
+		}
+
+		if (ch === "/" && expression[i + 1] === "*") throw new Error("comments are not supported");
+		if (ch === ";") throw new Error("multiple expressions are not supported");
+
+		if (ch === "(" || ch === "[") {
+			nestingDepth++;
+			if (nestingDepth > MAX_EXPRESSION_DEPTH) {
+				throw new Error(`expression is too deeply nested (max ${MAX_EXPRESSION_DEPTH})`);
+			}
+		} else if ((ch === ")" || ch === "]") && nestingDepth > 0) {
+			nestingDepth--;
+		}
+
+		if (ch === "*" && expression[i + 1] === "*") {
+			result += "^";
+			i += 2;
+			continue;
+		}
+
+		const match = expression.slice(i).match(/^(?:\d+\.\d+|\d+\.|\.\d+|\d+)(?:[eE][+-]?\d+)?/);
+		if (match && (i === 0 || !/[\w.]/.test(expression[i - 1]!))) {
+			result += `d("${match[0]}")`;
+			i += match[0].length;
+			continue;
+		}
+
+		result += ch;
+		i++;
+	}
+
+	return result;
+}

package/eval.ts

@@ -0,0 +1,452 @@
+import { Parser } from "expr-eval-fork";
+import { DECIMAL_PRECISION, Decimal, decimalizeExpression, resetDecimal, toDec, type DecimalValue } from "./decimal.ts";
+
+export const MAX_EXPRESSION_LENGTH = 4096;
+const MAX_FACTORIAL_OPERAND = 1000;
+const MAX_FACTORIAL_WORK = MAX_FACTORIAL_OPERAND;
+const MAX_ROUND_DIGITS = 1_000_000_000;
+const MAX_HYPERBOLIC_ABS = 10_000;
+const MAX_MODULO_EXPONENT_GAP = 10_000;
+const MAX_EXPENSIVE_WORK = 10_000;
+const TRIG_WORK = 100;
+const PI = new Decimal("3.141592653589793238462643383279502884197");
+const E = new Decimal("2.718281828459045235360287471352662497757");
+const MAX_TRIG_ABS = new Decimal("1e100");
+const SMALL_ATAN_ABS = new Decimal("1e-100");
+const LARGE_ATAN_ABS = new Decimal("1e100");
+const GUARD_DECIMAL_CONFIG = {
+	defaults: true,
+	precision: DECIMAL_PRECISION + 10,
+	rounding: Decimal.ROUND_HALF_UP,
+} as const;
+const GuardDecimal = Decimal.clone(GUARD_DECIMAL_CONFIG);
+
+let factorialWorkLeft = 0;
+let expensiveWorkLeft = 0;
+const EMPTY_VARIABLES: Record<string, never> = Object.create(null);
+
+const parser = new Parser({
+	allowMemberAccess: false,
+	operators: {
+		assignment: false,
+		comparison: false,
+		concatenate: false,
+		conditional: false,
+		fndef: false,
+		in: false,
+		logical: false,
+	},
+});
+
+function nullMap<T extends object>(values: T): T {
+	return Object.assign(Object.create(null), values);
+}
+
+function requireArity(name: string, args: unknown[], count: number): void {
+	if (args.length !== count) {
+		throw new Error(`${name}() needs exactly ${count} argument${count === 1 ? "" : "s"}`);
+	}
+}
+
+function factorial(value: unknown) {
+	const n = toDec(value);
+	if (!n.isInteger() || n.lt(0)) throw new Error("factorial needs a non-negative integer");
+	if (n.gt(MAX_FACTORIAL_OPERAND)) throw new Error(`factorial operand too large (max ${MAX_FACTORIAL_OPERAND})`);
+
+	const count = n.toNumber();
+	const cost = Math.max(count, 1);
+	if (cost > factorialWorkLeft) throw new Error("factorial work budget exceeded");
+	factorialWorkLeft -= cost;
+
+	let result = 1n;
+	for (let i = 2; i <= count; i++) result *= BigInt(i);
+	return new Decimal(result.toString()).toSignificantDigits(DECIMAL_PRECISION);
+}
+
+function decimals(values: unknown, name: string, minLength = 1): DecimalValue[] {
+	if (!Array.isArray(values) || values.length < minLength) {
+		const need = minLength === 1 ? "a non-empty number array" : `at least ${minLength} numbers`;
+		throw new Error(`${name}() needs ${need}`);
+	}
+	return values.map((value, index) => {
+		try {
+			const number = toDec(value);
+			if (!number.isFinite()) throw new Error("expected a finite number");
+			return number;
+		} catch {
+			throw new Error(`${name}(): invalid number at index ${index}`);
+		}
+	});
+}
+
+function decimalArguments(args: unknown[], name: string): DecimalValue[] {
+	const values = args.length === 1 && Array.isArray(args[0]) ? args[0] : args;
+	if (values.length === 0) throw new Error(`${name}() needs at least one number`);
+	return decimals(values, name);
+}
+
+function sum(xs: DecimalValue[], Ctor = Decimal, divisor = 1): DecimalValue {
+	if (xs.some((x) => !x.isFinite())) return Ctor.sum(...xs).div(divisor);
+
+	// Decimal.sum also truncates across large exponent gaps. Signed BigInt chunks
+	// keep the exact sum sparse, including intermediate values outside Decimal's range.
+	const width = BigInt(Ctor.precision);
+	const base = 10n ** width;
+	const bins = new Map<bigint, bigint>();
+	const add = (key: bigint, value: bigint) => bins.set(key, (bins.get(key) ?? 0n) + value);
+	for (const x of xs) {
+		if (x.isZero()) continue;
+		const digits = x.toExponential().split("e")[0]!.replace(".", "");
+		const exponent = BigInt(x.e) - BigInt(x.sd() - 1);
+		const key = exponent >= 0n ? exponent / width : (exponent - width + 1n) / width;
+		add(key, BigInt(digits) * 10n ** (exponent - key * width));
+	}
+	for (let key of [...bins.keys()].sort((a, b) => Number(a - b))) {
+		for (;;) {
+			const value = bins.get(key)!;
+			const carry = value / base;
+			bins.set(key, value % base);
+			if (!carry) break;
+			add(++key, carry);
+		}
+	}
+
+	const keys = [...bins.keys()].filter((key) => bins.get(key) !== 0n).sort((a, b) => Number(b - a));
+	if (keys.length === 0) return new Ctor(0);
+	let key = keys[0]!;
+	let coefficient = bins.get(key)!;
+	let i = 1;
+	const digitCount = (n: bigint) => n.toString().replace("-", "").length;
+	const retained = Ctor.precision + Math.ceil(Math.log10(divisor)) + 2;
+	for (; i < keys.length; i++) {
+		const next = keys[i]!;
+		if (digitCount(coefficient) >= retained || key - next > 2n) break;
+		coefficient = coefficient * base ** (key - next) + bins.get(next)!;
+		key = next;
+	}
+
+	// Normalized chunks have magnitude < base, so the leading remaining chunk
+	// determines the tail's sign. A sticky digit preserves which side of a tie it lies on.
+	let shift = 0n;
+	if (i < keys.length) {
+		shift = BigInt(Math.max(2, retained - digitCount(coefficient)));
+		coefficient = coefficient * 10n ** shift + (bins.get(keys[i]!)! > 0n ? 1n : -1n);
+	}
+	// Divide and round before restoring the exponent to avoid intermediate overflow/underflow.
+	const [mantissa, exponent] = new Ctor(coefficient.toString()).div(divisor).toExponential().split("e");
+	return new Ctor(`${mantissa}e${BigInt(exponent!) + key * width - shift}`);
+}
+
+function mean(xs: DecimalValue[]): DecimalValue {
+	return sum(xs, Decimal, xs.length);
+}
+
+function standardDeviation(xs: DecimalValue[], sample: boolean): DecimalValue {
+	// Scale before subtraction; a power of ten preserves small spreads around a large offset.
+	const scale = new GuardDecimal(`1e${GuardDecimal.max(...xs.map((x) => x.abs())).e}`);
+	const scaled = xs.map((x) => new GuardDecimal(x).div(scale));
+	// Center on an input first so a large common offset cannot round away the spread.
+	const shifted = scaled.map((x) => x.minus(scaled[0]!));
+	const center = sum(shifted, GuardDecimal, xs.length);
+	const squared = shifted.map((x) => x.minus(center).pow(2));
+	return new Decimal(sum(squared, GuardDecimal, sample ? xs.length - 1 : xs.length)
+		.sqrt().times(scale).toSignificantDigits(DECIMAL_PRECISION));
+}
+
+function tangent(value: DecimalValue): DecimalValue {
+	// Avoid Decimal.tan's cancellation in sqrt(1 - sin(x)^2) near a pole.
+	const x = new GuardDecimal(value);
+	return new Decimal(x.sin().div(x.cos()).toSignificantDigits(DECIMAL_PRECISION));
+}
+
+function arctangent(value: DecimalValue): DecimalValue {
+	// Decimal.atan can loop when argument reduction overflows or underflows.
+	const abs = value.abs();
+	if (abs.lt(SMALL_ATAN_ABS)) return value;
+	if (abs.gt(LARGE_ATAN_ABS)) return PI.div(value.isNegative() ? -2 : 2);
+	return Decimal.atan(value);
+}
+
+function arctangent2(y: DecimalValue, x: DecimalValue): DecimalValue {
+	if (x.isZero() || y.isZero() || !x.isFinite() || !y.isFinite()) return Decimal.atan2(y, x);
+	const ratio = y.div(x);
+	if (ratio.abs().lt(SMALL_ATAN_ABS)) return x.isNegative() ? (y.isNegative() ? PI.negated() : PI) : ratio;
+	if (ratio.abs().gt(LARGE_ATAN_ABS)) return PI.div(y.isNegative() ? -2 : 2);
+	return Decimal.atan2(y, x);
+}
+
+function expm1(value: DecimalValue): DecimalValue {
+	const x = new GuardDecimal(value.toString());
+	if (x.abs().gte(0.1)) {
+		return new Decimal(GuardDecimal.exp(x).minus(1).toSignificantDigits(DECIMAL_PRECISION).toString());
+	}
+	let term = x;
+	let total = x;
+	for (let n = 2; n <= DECIMAL_PRECISION + 10; n++) {
+		term = term.times(x).div(n);
+		const next = total.plus(term);
+		if (next.eq(total)) break;
+		total = next;
+	}
+	return new Decimal(total.toSignificantDigits(DECIMAL_PRECISION).toString());
+}
+
+function log1p(value: DecimalValue): DecimalValue {
+	const x = new GuardDecimal(value.toString());
+	if (x.abs().gte(0.1)) {
+		return new Decimal(GuardDecimal.ln(x.plus(1)).toSignificantDigits(DECIMAL_PRECISION).toString());
+	}
+	let power = x;
+	let total = x;
+	for (let n = 2; n <= DECIMAL_PRECISION + 10; n++) {
+		power = power.times(x);
+		const next = n % 2 === 0 ? total.minus(power.div(n)) : total.plus(power.div(n));
+		if (next.eq(total)) break;
+		total = next;
+	}
+	return new Decimal(total.toSignificantDigits(DECIMAL_PRECISION).toString());
+}
+
+function spendExpensiveWork(cost: number): void {
+	if (cost > expensiveWorkLeft) throw new Error("expression work budget exceeded");
+	expensiveWorkLeft -= cost;
+}
+
+function trigonometric(
+	name: string,
+	fn: (x: DecimalValue) => DecimalValue,
+	maxAbs?: DecimalValue,
+): (x: DecimalValue) => DecimalValue {
+	return (x) => {
+		if (maxAbs && x.abs().gt(maxAbs)) {
+			throw new Error(`${name}() argument too large (max absolute value ${maxAbs.toString()})`);
+		}
+		spendExpensiveWork(TRIG_WORK);
+		return fn(x);
+	};
+}
+
+function hyperbolic(name: string, fn: (x: DecimalValue) => DecimalValue): (x: DecimalValue) => DecimalValue {
+	return (x) => {
+		if (x.abs().gt(MAX_HYPERBOLIC_ABS)) {
+			throw new Error(`${name}() argument too large (max absolute value ${MAX_HYPERBOLIC_ABS})`);
+		}
+		spendExpensiveWork(x.isFinite() ? Math.max(1, Math.ceil(x.abs().toNumber())) : 1);
+		return fn(x);
+	};
+}
+
+function modulo(a: unknown, b: unknown) {
+	const left = toDec(a);
+	const right = toDec(b);
+	if (right.isZero()) throw new Error("modulo by zero");
+	const exponentGap = left.isFinite() && right.isFinite() ? Math.abs(left.e - right.e) : 0;
+	if (exponentGap > MAX_MODULO_EXPONENT_GAP) {
+		throw new Error(`modulo exponent gap too large (max ${MAX_MODULO_EXPONENT_GAP})`);
+	}
+	spendExpensiveWork(Math.max(1, exponentGap));
+	return left.mod(right);
+}
+
+function roundTo(...args: unknown[]) {
+	requireArity("roundTo", args, 2);
+	const digits = toDec(args[1]);
+	if (!digits.isInteger() || digits.abs().gt(MAX_ROUND_DIGITS)) {
+		throw new Error(`roundTo() digits must be an integer from -${MAX_ROUND_DIGITS} to ${MAX_ROUND_DIGITS}`);
+	}
+	const places = digits.toNumber();
+	const value = toDec(args[0]);
+	if (places >= 0) return value.toDecimalPlaces(places);
+	const scale = new Decimal(10).pow(-places);
+	return value.div(scale).toDecimalPlaces(0).times(scale);
+}
+
+function arrayIndex(values: unknown, index: unknown): unknown {
+	if (!Array.isArray(values)) throw new Error("indexing needs an array");
+	let n: DecimalValue;
+	try {
+		n = toDec(index);
+	} catch {
+		throw new Error("array index needs an integer");
+	}
+	if (!n.isInteger()) throw new Error("array index needs an integer");
+	if (n.lt(0) || n.gte(values.length)) throw new Error("array index out of range");
+	return values[n.toNumber()];
+}
+
+const decimalUnary: Record<string, (x: DecimalValue) => DecimalValue> = {
+	sin: trigonometric("sin", (x) => Decimal.sin(x), MAX_TRIG_ABS),
+	cos: trigonometric("cos", (x) => Decimal.cos(x), MAX_TRIG_ABS),
+	tan: trigonometric("tan", tangent, MAX_TRIG_ABS),
+	asin: trigonometric("asin", (x) => Decimal.asin(x)),
+	acos: trigonometric("acos", (x) => Decimal.acos(x)),
+	atan: trigonometric("atan", arctangent),
+	sinh: hyperbolic("sinh", (x) => Decimal.sinh(x)),
+	cosh: hyperbolic("cosh", (x) => Decimal.cosh(x)),
+	tanh: hyperbolic("tanh", (x) => Decimal.tanh(x)),
+	asinh: hyperbolic("asinh", (x) => Decimal.asinh(x)),
+	acosh: hyperbolic("acosh", (x) => Decimal.acosh(x)),
+	atanh: hyperbolic("atanh", (x) => Decimal.atanh(x)),
+	sqrt: (x) => Decimal.sqrt(x),
+	cbrt: (x) => Decimal.cbrt(x),
+	abs: (x) => Decimal.abs(x),
+	ln: (x) => Decimal.ln(x),
+	log: (x) => Decimal.ln(x),
+	lg: (x) => Decimal.log10(x),
+	log10: (x) => Decimal.log10(x),
+	log2: (x) => Decimal.log2(x),
+	exp: (x) => Decimal.exp(x),
+	expm1,
+	log1p,
+	ceil: (x) => Decimal.ceil(x),
+	floor: (x) => Decimal.floor(x),
+	round: (x) => Decimal.round(x),
+	trunc: (x) => Decimal.trunc(x),
+	sign: (x) => new Decimal(Decimal.sign(x)),
+};
+
+parser.unaryOps = nullMap({
+	...Object.fromEntries(Object.entries(decimalUnary).map(([name, fn]) => [name, (value: unknown) => fn(toDec(value))])),
+	"+": toDec,
+	"-": (value: unknown) => toDec(value).negated(),
+	"!": factorial,
+});
+
+parser.binaryOps = nullMap({
+	"+": (a, b) => toDec(a).plus(toDec(b)),
+	"-": (a, b) => toDec(a).minus(toDec(b)),
+	"*": (a, b) => toDec(a).times(toDec(b)),
+	"/": (a, b) => {
+		const numerator = toDec(a);
+		const denominator = toDec(b);
+		if (denominator.isZero()) throw new Error("division by zero");
+		return numerator.div(denominator);
+	},
+	"%": modulo,
+	"^": (a, b) => toDec(a).pow(toDec(b)),
+	"[": arrayIndex,
+});
+parser.ternaryOps = nullMap({});
+
+const hypot = (...args: unknown[]) => Decimal.hypot(...decimalArguments(args, "hypot"));
+
+parser.functions = nullMap({
+	d: (...args: unknown[]) => {
+		requireArity("d", args, 1);
+		if (typeof args[0] !== "string") throw new Error("invalid decimal literal");
+		return toDec(args[0]);
+	},
+	fac: (...args: unknown[]) => {
+		requireArity("fac", args, 1);
+		return factorial(args[0]);
+	},
+	pow: (...args: unknown[]) => {
+		requireArity("pow", args, 2);
+		return toDec(args[0]).pow(toDec(args[1]));
+	},
+	atan2: (...args: unknown[]) => {
+		requireArity("atan2", args, 2);
+		const values = args.map(toDec);
+		spendExpensiveWork(TRIG_WORK);
+		return arctangent2(values[0]!, values[1]!);
+	},
+	min: (...args: unknown[]) => Decimal.min(...decimalArguments(args, "min")),
+	max: (...args: unknown[]) => Decimal.max(...decimalArguments(args, "max")),
+	sum: (...args: unknown[]) => {
+		requireArity("sum", args, 1);
+		return sum(decimals(args[0], "sum"));
+	},
+	hypot,
+	pyt: hypot,
+	roundTo,
+	percent: (...args: unknown[]) => {
+		requireArity("percent", args, 2);
+		const rate = toDec(args[0]);
+		const amount = toDec(args[1]);
+		// Scale the larger factor first so intermediate arithmetic stays in range.
+		return amount.abs().gte(rate.abs())
+			? amount.div(100).times(rate)
+			: rate.div(100).times(amount);
+	},
+	radians: (...args: unknown[]) => {
+		requireArity("radians", args, 1);
+		return toDec(args[0]).times(PI).div(180);
+	},
+	degrees: (...args: unknown[]) => {
+		requireArity("degrees", args, 1);
+		return toDec(args[0]).times(180).div(PI);
+	},
+	mean: (...args: unknown[]) => {
+		requireArity("mean", args, 1);
+		return mean(decimals(args[0], "mean"));
+	},
+	median: (...args: unknown[]) => {
+		requireArity("median", args, 1);
+		const xs = decimals(args[0], "median").sort((a, b) => a.comparedTo(b));
+		const mid = Math.floor(xs.length / 2);
+		return xs.length % 2 === 0 ? mean([xs[mid - 1]!, xs[mid]!]) : xs[mid]!;
+	},
+	stdev: (...args: unknown[]) => {
+		requireArity("stdev", args, 1);
+		return standardDeviation(decimals(args[0], "stdev"), false);
+	},
+	stdevs: (...args: unknown[]) => {
+		requireArity("stdevs", args, 1);
+		return standardDeviation(decimals(args[0], "stdevs", 2), true);
+	},
+});
+
+parser.consts = nullMap({ PI, E });
+
+function normalizeExpression(expression: string): string {
+	const trimmed = expression.trim();
+	if (!trimmed) throw new Error("Expression is empty");
+	if (trimmed.length > MAX_EXPRESSION_LENGTH) {
+		throw new Error(`Expression too long (max ${MAX_EXPRESSION_LENGTH} chars)`);
+	}
+	return trimmed;
+}
+
+function resultString(result: unknown): string {
+	if (typeof result === "number") result = new Decimal(String(result));
+	if (!(result instanceof Decimal)) {
+		const type = Array.isArray(result) ? "array" : typeof result;
+		throw new Error(`Expression did not evaluate to a number (got ${type})`);
+	}
+	if (!result.isFinite()) {
+		if (result.isNaN()) throw new Error("Result is NaN");
+		throw new Error(result.isPositive() ? "Result is Infinity" : "Result is -Infinity");
+	}
+	return result.toString();
+}
+
+export function evaluateExpression(expression: string): { expression: string; value: string | string[] } {
+	const normalized = normalizeExpression(expression);
+	let result: unknown;
+	factorialWorkLeft = MAX_FACTORIAL_WORK;
+	expensiveWorkLeft = MAX_EXPENSIVE_WORK;
+	try {
+		result = parser.evaluate(decimalizeExpression(normalized), EMPTY_VARIABLES);
+	} catch (error) {
+		let message = error instanceof Error ? error.message : String(error);
+		message = message
+			.replace(/^\[DecimalError\]\s*/, "")
+			.replace(/^parse error \[\d+:\d+\]:\s*/, "")
+			.replace(/\bT[A-Z]+:\s*/g, "");
+		if (/precision limit exceeded/i.test(message)) message = "numeric argument exceeds precision limit";
+		if (error instanceof RangeError && /call stack/i.test(message)) message = "expression is too deeply nested";
+		throw new Error(`Invalid expression: ${message}`);
+	} finally {
+		factorialWorkLeft = 0;
+		expensiveWorkLeft = 0;
+		resetDecimal();
+		GuardDecimal.set(GUARD_DECIMAL_CONFIG);
+	}
+
+	const value = Array.isArray(result) ? result.map(resultString) : resultString(result);
+	const evaluated = { expression: normalized, value };
+	if (Buffer.byteLength(JSON.stringify(evaluated)) > 50 * 1024) {
+		throw new Error("Result exceeds 50 KiB output limit");
+	}
+	return evaluated;
+}

package/expr-eval-fork.d.ts

@@ -0,0 +1,8 @@
+import "expr-eval-fork";
+
+declare module "expr-eval-fork" {
+	interface Parser {
+		binaryOps: Record<string, (left: unknown, right: unknown) => unknown>;
+		ternaryOps: Record<string, (condition: unknown, consequent: unknown, alternate: unknown) => unknown>;
+	}
+}

package/index.ts

@@ -0,0 +1,46 @@
+import { Type } from "typebox";
+import { Text } from "@earendil-works/pi-tui";
+import { defineTool, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { DECIMAL_PRECISION } from "./decimal.ts";
+import { evaluateExpression, MAX_EXPRESSION_LENGTH } from "./eval.ts";
+
+const calculatorTool = defineTool({
+	name: "calculator",
+	label: "Calculator",
+	description: `Calculate arithmetic, scientific functions and statistics with ${DECIMAL_PRECISION}-significant-digit decimal precision. Returns one number or a flat array of numbers.`,
+	promptSnippet: "Calculate numeric answers and verify arithmetic",
+	promptGuidelines: [
+		"Use calculator for non-trivial calculations; simple arithmetic does not need a tool call. Results are rounded decimal strings. In calculator expressions, use sum([...]) for totals and roundTo(value, places) for requested rounding. Put independent results in a flat array.",
+	],
+	constrainedSampling: { type: "json_schema", strict: "prefer" },
+	parameters: Type.Object(
+		{
+			expression: Type.String({
+				minLength: 1,
+				maxLength: MAX_EXPRESSION_LENGTH,
+				description: "Numeric expression: + - * / % ^ **, PI, E, roots, trig, n! (0–1000), sum/mean/median. log/ln are natural; log2/log10 choose a base. Use expm1(x) for exp(x)-1 and log1p(x) for ln(1+x) when x is small. Trig uses radians; radians(degrees) and degrees(radians) convert angles. percent(rate, amount) gives rate% of amount. stdev(array) is population; stdevs(array) is sample. roundTo(value, places) rounds halves away from zero.",
+			}),
+		},
+		{ additionalProperties: false },
+	),
+	outputSchema: Type.Object({
+		expression: Type.String(),
+		value: Type.Union([Type.String(), Type.Array(Type.String())]),
+	}, { additionalProperties: false }),
+	renderCall(args, theme) {
+		return new Text(theme.fg("toolTitle", theme.bold("calculator ")) + theme.fg("dim", JSON.stringify(args.expression ?? "")), 0, 0);
+	},
+	async execute(_toolCallId, params) {
+		const evaluated = evaluateExpression(params.expression);
+		const text = Array.isArray(evaluated.value) ? JSON.stringify(evaluated.value) : evaluated.value;
+		return {
+			content: [{ type: "text", text }],
+			details: evaluated,
+			structuredContent: evaluated,
+		};
+	},
+});
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool(calculatorTool);
+}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@fitchmultz/pi-calculator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.1.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "description": "Deterministic high-precision calculator tool for Pi",
+  "type": "module",
+  "files": [
+    "index.ts",
+    "eval.ts",
+    "decimal.ts",
+    "expr-eval-fork.d.ts",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "pi-package",
+    "pi",
+    "calculator",
+    "decimal"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fitchmultz/pi-calculator.git"
+  },
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "scripts": {
+    "check": "node check.ts",
+    "check:load": "node check-extension.ts",
+    "typecheck": "tsc",
+    "verify": "npm run typecheck && npm run check && npm run check:load",
+    "check:compat": "npm run verify"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "dependencies": {
+    "decimal.js": "10.6.0",
+    "expr-eval-fork": "3.0.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@earendil-works/pi-tui": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-tui": "1.0.0",
+    "@types/node": "24.19.1",
+    "typebox": "1.3.27",
+    "typescript": "7.0.2"
+  }
+}