codecalc

Execute `code` in `language` in a sandbox. Use this, not execute_code_stream/run_submit/session_run, for one program whose result you can wait for within a 120s cap. Returns stdout, stderr, exit_code, duration_ms, cpu_ms, peak_memory_kb, verdict (OK/TLE/MLE/OLE/RTE). - `session_id`: run inside a session workspace (see session_start); with a stateful session (python3/node) interpreter state persists across calls. Also reports `artifacts_created` (files just created/modified) since that workspace outlives the call; a sessionless run has none. See `session_run` for the same field plus i…

Execute code and STREAM progress + partial output as it runs. Use this, not execute_code/run_submit/session_run, for the same run when you want output while it runs, up to a 300s cap. Reports progress notifications to the client while the program runs, so agents can see output before the process finishes. Returns the same result shape and applies the SAME ceilings as execute_code: max_memory_mb, max_output_kb and max_cpu are forwarded to the executor exactly as execute_code forwards them, including the same 240 KiB per-stream clamp. `dependencies`: same as execute_code's (PEP 723 merge, `no_…

Extract a named function (with its imports + referenced helpers) into a standalone program and run it in the sandbox. python3 gets exact ast extraction; other languages best-effort block extraction (pass `call` to execute non-python). Returns the extracted program and per-input runs.

What binary64 actually stores for X: exact value, raw bits, ULP, both neighbours, and whether the literal is representable. `float_repr(0.1)` shows 0.1000000000000000055511151231257827...; `float_repr(0.25)` says EXACT. Above 2^53 warns consecutive integers are indistinguishable.

Convert a SPAN of elapsed seconds into a humanised duration (e.g. '2d 3h 4m 5s') plus per-day and per-30d rates. For an epoch timestamp to a calendar date, use epoch_time instead. For byte counts, not seconds, use data_sizes. Returns `human`, `per_day`, `per_30d`, and the echoed `seconds`.

Install a package for a language (uv pip / npm / gem / go get / cargo add...). Asks the caller to confirm before installing (a protocol-level gate, not just the `anthropic/requiresUserInteraction` `_meta` hint — see codecalc/confirmation.py); a declined or malformed confirmation refuses with no install attempted. With session_id, executed code in that session can import the result. NETWORK: yes, always. The package manager fetches from its registry (PyPI, npm, rubygems, crates.io). codecalc opens no socket itself; the child process does. NOT SANDBOXED: the installer runs as a direct subpro…

List execution providers (execution BACKENDS — local subprocess, gVisor-strict, remote) and their machine-readable capabilities. This is about which BACKEND runs your code, not which LANGUAGE it runs — a provider's `ready`/`strict` fields are resolution facts about the backend itself. Per-language reliability (how much codecalc's CI has actually verified a given language's toolchain, vs merely resolved it) is a separate axis reported by `list_languages`/`runtimes_status`/`codecalc doctor` as `tier`; a `ready` provider says nothing about whether a specific language running through it has ever …

List every language codecalc can execute, with extension, compile flag, and what this machine resolved. `status` is `installed` (its command was found on the sandbox PATH) or `supported` (nothing for it here); `status_basis` is `resolved`, meaning nothing was executed to check. Run `codecalc doctor --deep` to promote a runtime to `available` by actually running it. `tier` is a DIFFERENT axis from `status`: `status` says whether THIS machine resolved the command (resolution); `tier` says whether codecalc's own CI has actually executed this language and asserted on its output (reliability) — `t…

List every supported unit alias — all aliases and spellings — for convert_units.

Structured matrix operations: det, inverse, eigenvalues, transpose, rank, trace. `evaluate_expression` refuses `Matrix([[1,2],[3,4]])` on purpose — `[`/`]` are denied there to block subscript-based RCE escapes, and a matrix literal is collateral from that (correctly aimed) screen. This tool is the structured replacement: `rows` is a JSON array of arrays (row-major), never a string to parse. Each entry is either a JSON number, used directly, or a scalar expression string ('1/2', 'sqrt(2)', 'x+1'), screened per-entry the same way evaluate_expression screens its input before anything reaches Sym…

Exact percent change from FROM_VALUE to TO_VALUE. Use percentage, not this, for PART / TOTAL rather than a before/after change. `(to_value - from_value) / abs(from_value) * 100` — the conventional finance definition, relative to the MAGNITUDE of the base so a negative from_value does not flip the sign (see `note` when it applies). Refuses from_value=0 (undefined) rather than returning infinity — report the absolute change instead. Returns `percent_exact` (exact rational), `percent_decimal` (rounded), `absolute_change`, `direction` ("increase"/"decrease"/"unchanged"), and `multiplier` (to_valu…

Exact share and percentage of PART / TOTAL. Use calc_exact for a single arithmetic expression, or compare_threshold to check the result against a threshold rather than just compute it.

p50/p90/p95/p99 (the 50th/90th/95th/99th percentile cutoffs) by nearest-rank AND linear interpolation. Pairs with calc_stats, which gives mean/median/stdev/CV on the same sample instead of these distribution points. Warns when n < 100 that p99 is just the maximum wearing a label.

Look up a physical constant (speed_of_light, planck, avogadro, gravity, electron_mass, gas_constant, ...) or list all 22 with values.

Convert a value between ANY bases 2..36, fractions included; bases that cannot represent the fraction (e.g. 0.1 in base 2) are flagged non-terminating. `radix_convert('zz', 36, 7)` is one call.

Cancel a background run started with run_submit. Idempotent: calling this on a run that is already finished/cleaned reports `cancelled: false, state: <its actual terminal state>` rather than erroring — matching execute_code's own "no partial result" rule, there is nothing partial to hand back either way. Propagation depends on the SELECTED PROVIDER (see list_execution_providers' `cancel` capability). The built-in `local` provider does not support stopping a run once it has started; that is reported honestly here rather than silently pretended to have worked — the computation keeps running to…

Poll a background run started with run_submit. While running: {"ok": True, "state": "running"|"cancelling", "run_id", "provider_id", "started_at", "deadline"}. Once terminal (`state` "finished"/"cleaned"/"recovered"), this returns the SAME result shape execute_code returns — stdout/stderr/exit_code/ verdict/unenforced/provider (the interface_version/provider_id/limits receipt)/... — merged with a small set of run_* extras (run_id, provider_id, started_at, deadline, state, cleaned; see server.py's _RUN_EXTRA_KEYS). This terminal reply carries the same `anthropic/maxResultSizeChars` `_meta` ex…

Submit code for BACKGROUND execution; returns a run_id immediately. Use this, not execute_code/execute_code_stream/session_run, when you do not want to hold the call open — poll run_inspect(run_id), and run_cancel(run_id) to stop it early. Same request shape as execute_code minus `session_id` (a run is a standalone process, not a session workspace). `timeout` bounds the WORK itself, not how long you wait to collect it. This call's own reply carries no output — a small run_id handle — so the `anthropic/maxResultSizeChars` hint lives on `run_inspect` instead, which returns the full envelope, s…

Check every language runtime for available updates (NON-MUTATING). Reports current vs latest version per language, which package manager owns it (mise/rustup/swiftly/apt/npm/uv), and the exact command that would run. Each entry also carries `tier` (registry.RELIABILITY_TIERS) — see list_languages for what `tested`/`best_effort`/`plan_only` mean. A current, up-to-date toolchain can still be `best_effort`: `tier` is orthogonal to whether the update check below found a newer version. NETWORK: yes. Non-mutating refers to this machine's runtimes, not to traffic — each package manager is asked wh…

List files created by executed code in a session (excluding runner internals like main.py/run.out).

Delete one file (or symlink entry — never the directory or symlink's target) from a session workspace. This is the recovery path when a session is refused for being over CODECALC_MAX_ARTIFACT_COUNT: neither session_write_file (creates/overwrites, never removes) nor session_run/ execute_code (refused by the same cap) can shrink the count, so this is the only in-session way to get back under it short of session_stop discarding the whole workspace. Refuses runner-internal paths (the same ones session_artifacts excludes) and directories.

List workspace files, optionally using a bounded cursor page. Use session_artifacts, not this, for only the files executed code produced; use session_read_file for one file's contents.

List active sessions and their languages/state.

Read a file from a session workspace. Text files return content. With as_image=True (or for image files), the file is returned as an inline image the model can see. Use session_files to discover paths; session_artifacts lists what executed code produced.

Run a multi-file program already written into a session workspace (via session_write_file). Use this, not execute_code/execute_code_stream/run_submit, when `entry_file` may import other files already in that workspace (helper.py, data/...). Runs as a fresh process in the session workdir (not the REPL worker), so relative imports and data files resolve. Returns stdout/stderr/verdict plus the entry file's path. Oversized output spills into the session workspace the same way execute_code's does — see its docstring for `stdout_spill`/`stderr_spill`. Reports `artifacts_created` and inlines small …

Archive or restore a session's workspace files. `action`: - "save": tar.gz the session's current files (same rules as session_artifacts: .codecalc-run/ excluded, symlinks/hardlinks refused) into a snapshot stored OUTSIDE the workspace, so sandboxed code can never read or tamper with it. Returns snapshot_id. - "restore": extract snapshot_id's files into a brand-new session (default) or, with replace=True, wipe and recreate session_id's OWN workspace first. Only files are restored — a python3/node session's REPL variables/imports are never part of a snapshot. - "list": snapshots sav…

Start a persistent session. python3/node get a stateful REPL worker (variables/imports persist across execute_code calls); other languages get a persistent workspace directory. Returns session_id.

Stop a session: kill its REPL worker (if any) and delete its workspace. Also deletes every session_snapshot saved for it, unless keep_snapshots=True.

Write a file into a session workspace (relative path, no escapes). Use this to seed input data for executed code.

Symbolic algebra, selected by `op` — replaces the four former standalone tools solve_expression, solve_linear, simplify_expression and limit_expression, retired in 0.12.0 (CHANGELOG.md). Every op returns exactly its former tool's own result, plus `op` (additive). op="solve" (was solve_expression) — the roots of one equation: 'x**2 - 4 = 0', '2*x + 1 = 7'. For a system of several equations, use op="solve_linear". For general constraint satisfiability (inequalities, boolean constraints, multiple solvers), use z3_check. Returns `solutions` as a list of strings alongside the parsed `equation` and…

Debug WHY, line by line, for the ONE input you actually ran it on: which statements fired, in what order, with what variable values at each step, and which if/elif/while/for/try branch was taken versus never taken. Want just the printed output instead? Use execute_code. Returns `events`: ordered `{step, line, event, func, locals}`, one entry per traced line/call/return/exception in YOUR code only (library internals excluded). `locals` on each entry is only the names that changed since the previous step in that same call — not a full dump every line. A `return` entry also carries `return_value…

Build the truth table for a boolean expression over and/or/not/xor/ implies/iff (plus true/false constants and variables): 'a and b or not c', 'p xor q', 'a implies b'. Use z3_check, not this, for satisfiability over inequalities or non-boolean variables; use evaluate_expression for symbolic (non-boolean) math. Returns `variables` (sorted names) and `rows` (one dict per assignment, each variable name -> bool plus `result`), plus `row_count`, `satisfiable` (any row true), and `tautology` (every row true).

Update language runtimes. SAFE BY DEFAULT: with apply=False this is a dry run — it returns the update commands that WOULD run without changing anything. Pass apply=True to actually execute them (mise up, rustup update, swiftly update, apt-get upgrade of language packages, npm -g update, uv tool upgrade). apply=True asks the caller to confirm first (a protocol-level gate, not just the `anthropic/requiresUserInteraction` `_meta` hint — see codecalc/confirmation.py); apply=False is never gated, since nothing runs. PRIVILEGE: the apt manager updates system packages and its command begins with `s…

PROVE an optimisation: same outputs, measurably AND SIGNIFICANTLY faster. Two gates, in order. Correctness: runs `candidate` against `original` on shared inputs — a faster-but-wrong candidate fails here and is never timed. Speed: times both at increasing sizes; accepts only when the median ratio clears `min_speedup` AND a one-sided Mann-Whitney U test rejects "not faster" at every counted size (2-3), or a Bonferroni-corrected majority above that — one size never accepts alone. See `inference` for the per-size U statistic, p-value, effect size. A rejection names which gate failed and by how m…

PROVE that a port is equivalent: run both programs, compare their output. You write the translation — you are the language model. This runs your source and your port on the same inputs and reports, per input, whether they matched, diverged, or could not be compared (a runtime that is missing or a program that failed on both sides is INCONCLUSIVE, never a pass). Use it after porting anything: python3 -> go, node -> rust, a rewritten function against the original. Pair with compare_edge_cases to find the inputs worth testing. Matching tolerates only line-ending/trailing-whitespace noise; stdo…

Use z3_check, not symbolic(op="solve"), for satisfiability over inequalities, boolean combinations, or several variables at once: sat/ unsat/unknown plus a model. Example: '(declare-const x Int)(assert (> x 5))(check-sat)'. `unsat` is graded `solver_proven` — see `grade_basis` for the engine version and timeout bound it was decided within. `sat` is graded `ungraded`: it's a real decided answer, just not a proof — reserving `solver_proven` for `unsat` means a counterexample can never wear a proof grade. `unknown` carries no proof either way and is also graded `ungraded`.