@fitchmultz/pi-calculator 0.0.0-stage → 4.1.1

package/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+## 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,81 @@
-# 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.
+A deterministic calculator tool for [Pi](https://github.com/earendil-works/pi) with 40-significant-digit decimal precision. Input literals and arithmetic are rounded using half-up rounding; results are decimal strings, not lossless symbolic answers.
+
+Requires Node.js 24 or later and Pi 1.0.0 or later. Release qualification selects the latest stable official Pi and the [fitchmultz/pi fork](https://github.com/fitchmultz/pi) main once per run, freezing their version and commit throughout the checks. Each host is qualified separately; a matching version string is not a compatibility result.
+
+## Install
+
+```sh
+pi install npm:@fitchmultz/pi-calculator
+```
+
+**The unscoped `pi-calculator` npm package is NOT this project.** This repository publishes only `@fitchmultz/pi-calculator`.
+
+Git remains supported as a fallback:
+
+```sh
+pi install git:github.com/fitchmultz/pi-calculator
+# Existing versioned tags remain installable:
+pi install git:github.com/fitchmultz/pi-calculator@v4.1.0
+```
+
+When switching from Git to npm, remove the exact Git source shown by `pi list` before installing the scoped package to avoid loading the calculator twice. Existing Git installs can stay on Git.
+
+The package adds one `calculator` tool with one required `expression` string. Pi supplies the schema and terminal UI libraries; the calculator uses `decimal.js` and `expr-eval-fork` for evaluation.
+
+## Expressions
+
+Use the calculator for non-trivial calculations; simple arithmetic does not need a tool call. Independent results can share one flat array:
+
+```text
+(12.5 * 1.0825) ^ 3
+sin(radians(90))
+percent(15, 200)
+mean([2,4,6,8])
+[stdev([2,4,4,4,5,5,7,9]), stdevs([2,4,4,4,5,5,7,9])]
+[0.1 + 0.2, 2^64]
+```
+
+Operators include `+`, `-`, `*`, `/`, `%`, `^` and `**`; constants are `PI` and `E`. Arrays support zero-based indexing, such as `[1,2,3][2]`.
+
+Supported functions include:
+
+- `sin`, `cos`, `tan`, their inverse/hyperbolic variants, and `atan2`. Trig uses radians. `radians(degrees)` and `degrees(radians)` convert angles.
+- `sqrt`, `cbrt`, `abs`, `pow`, `exp`, `expm1`, `ln`/`log`, `log1p`, `log2`, `log10`/`lg`. `ln` and `log` are natural logarithms. For small inputs, use `expm1(x)` for `exp(x)-1` and `log1p(x)` for `ln(1+x)` to preserve precision.
+- `ceil`, `floor`, `round`, `roundTo`, `trunc`, `sign`. `roundTo(value, places)` rounds halves away from zero; negative places round to tens, hundreds, and so on.
+- `percent(rate, amount)` gives `rate%` of `amount`: `percent(15, 200)` is `30`.
+- `sum`, `mean`, `median`, `stdev`, `stdevs` take numeric arrays. `stdev` is population standard deviation; `stdevs` is sample standard deviation and requires at least two elements.
+- `min`, `max`, `hypot`/`pyt` take either an array or individual arguments.
+- `n!` and `fac(n)` compute factorials for integers from 0 through 1000.
+
+Aggregates require finite numeric elements. Sums preserve cancellation remainders before rounding; means and even medians round after division.
+
+## Results and limits
+
+The tool returns a finite scalar or flat array of finite scalars, represented as decimal strings. A nested array, nonnumeric result, or nonfinite member fails the whole expression. Large finite values use scientific notation.
+
+Model-facing content contains only the value, such as `0.3`, or a JSON array of strings, such as `["0.3","18446744073709551616"]`. Structured details retain `{ expression, value }`, where `expression` is trimmed and `value` is a string or string array. The same stable outcome is exposed as native `structuredContent` with an `outputSchema`, so nested/codemode callers receive decimal strings without reparsing display text. Evaluation failures still throw and become native error results; schema and policy checks remain Pi-owned. Pi's tool card displays the safely escaped expression above the result.
+
+Expressions are limited to 4,096 characters and 128 nesting levels. Serialized expression/value details must fit within 50 KiB; oversized results are rejected rather than truncated. The tool requests native strict JSON-schema sampling where the provider supports it and uses Pi's normal fallback elsewhere.
+
+Each expression has a shared 1,000-step factorial budget. `sin`/`cos`/`tan` reject absolute inputs above `1e100`, hyperbolic functions reject absolute inputs above 10,000, and `%` rejects operand exponent gaps above 10,000. Expensive operations share a 10,000-unit work budget. Circular trig calls cost 100 units each, allowing at most 100 per expression.
+
+### Upgrading from v2
+
+Version 3 removes the old angle-conversion names: replace `deg(x)` with `radians(x)` and `rad(x)` with `degrees(x)`. There are no compatibility aliases. Tool content no longer includes `expression =`; consumers should read the expression from details and handle both string and string-array values.
+
+## Verification
+
+```sh
+npm ci --ignore-scripts
+npm run verify
+```
+
+Verification includes numerical and work-limit checks, schema and structured result contracts, actual extension loading, native nested validation/policy/evaluation errors, and native tool-card rendering. The exact development cohort uses TypeBox 1.3.27; no evaluator or grammar compatibility layer is needed.
+
+Update the development TypeBox pin alongside the qualified Pi host, using the version that host ships. Independent TypeBox updates are disabled in Renovate because they install duplicate host schema libraries and slow development startup. Each compatibility lane still selects its host's TypeBox version.
+
+The locked development cohort is reproducible local tooling, not a release-qualification target. CI runs the full verification against both frozen latest hosts, including fresh Git and packed npm consumers. Intentional version bumps with versioned changelog notes publish from the main-only repository pipeline when `NPM_RELEASE_ENABLED` is `true`; the release caller reuses the same frozen host inputs for qualification and publishing.
+
+Pi extensions execute with full system access. Review the source before installing.

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.1",
+  "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"
+  }
+}