oh-my-pi/docs/tools/calc.md

calc

Evaluates one or more arithmetic expressions and returns formatted numeric results.

Source

• Entry: packages/coding-agent/src/tools/calculator.ts
• Model-facing prompt: packages/coding-agent/src/prompts/tools/calculator.md
• Key collaborators:
  • packages/coding-agent/src/tui.ts — status lines and tree-list rendering
  • packages/coding-agent/src/tools/render-utils.ts — preview limits and formatting helpers

Inputs

Field	Type	Required	Description
calculations	Calculation[]	Yes	Batch of expressions to evaluate in order.

Calculation

Field	Type	Required	Description
expression	string	Yes	Arithmetic expression string.
prefix	string	Yes	Prepended verbatim to the rendered numeric result.
suffix	string	Yes	Appended verbatim to the rendered numeric result.

Outputs

• Single-shot result.
• content[0].text is the newline-joined prefix + value + suffix string for each calculation.
• details.results is an array of { expression, value, output }.
• On renderer fallback, if details is missing but content[0].text exists, the TUI tries to pair each output line with the original expressions from call args.

Flow

1. execute() wraps evaluation in untilAborted(...).
2. For each entry, evaluateExpression(...) tokenizes the expression, parses it with a recursive-descent parser, rejects non-finite outputs, and normalizes -0 to 0.
3. tokenizeExpression(...) accepts whitespace, parentheses, operators, and number literals; any other character throws immediately.
4. ExpressionParser applies precedence in this order: + -, * / %, unary + -, exponentiation **, parentheses/literals.
5. Exponentiation is right-associative (2 ** 3 ** 2 parses as 2 ** (3 ** 2)).
6. Each numeric result is formatted with String(value) and wrapped with the provided prefix and suffix.
7. The tool returns text output plus structured details.

Side Effects

• Background work / cancellation
  • Supports abort via untilAborted(...).
• Session state
  • None.
• Filesystem / Network / Subprocesses
  • None.

Limits & Caps

• Supported operators: +, -, *, /, %, ** (packages/coding-agent/src/tools/calculator.ts).
• Supported numeric literals:
  • decimal integers/floats, including leading-dot forms like .5
  • scientific notation like 1e10, 2.5E-3
  • hexadecimal 0x...
  • binary 0b...
  • octal 0o...
• Results must be finite; Infinity and NaN are rejected.
• The renderer collapses long result lists using PREVIEW_LIMITS.COLLAPSED_ITEMS from packages/coding-agent/src/tools/render-utils.ts.

Errors

• Invalid characters: e.g. Invalid character "x" in expression.
• Malformed numbers: invalid prefixed literal, invalid exponent, invalid number.
• Syntax errors: Unexpected token in expression, Unexpected end of expression, Missing closing parenthesis, Expression is empty.
• Non-finite arithmetic: Expression result is not a finite number.
• Any evaluation error aborts the whole batch; the tool does not return partial successes.

Notes

• Despite the schema example showing sqrt(16), the parser does not support functions, identifiers, units, or constants; only numeric literals, operators, and parentheses are accepted.
• Precision is plain JavaScript number semantics throughout, including floating-point rounding behavior.
• / and % use JavaScript numeric operators directly; there is no integer-only mode or unit handling.
• Unary operators bind tighter than *///% but looser than exponentiation because unary parsing delegates to #parsePower().