feat: Add debug mode to one-shot commands

[xalelax]

Relevant issue or PR

Debugging Tesseracts was limited to the serve command; this extends it to tesseract run ... commands. For those, the runtime waits for a debugger to attach, so that everything after it is in principle observable. That includes, for instance, tesseract_api.py import-time stuff.

Description of changes

• Refactored existing logic for the serve debugger into a common function.
• Added --debug arg to run; piped that in a few places
• Added a small paragraph to the docs

Some questions still open:

• I silenced the warnings that can be seen in the video with cea6bd3; should be a reasonable choice given that very seldom one needs to go down in the call stack until stdlib stuff is reached, but we could also force python to use non-freezed versions of stdlib (-Xfrozen_modules=off).
• The port debugpy listens to changes every time by default, unless host networking is used. I think it's not too bad, and the manual bit of inserting that port into the launch config can be ameliorated with multiple strategies (like having "port": "${input:debugPort}" in the launch config, and a corresponding input defined).

Testing done

(warnings were still there because this video is before cea6bd3)

Recording.2026-06-26.181450.mp4

Here's a more refined version, with the edits described in the previous section

Recording.2026-06-26.225216.mp4

[codecov]

Codecov Report

❌ Patch coverage is 30.43478% with 16 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.84%. Comparing base (2b7ac30) to head (5241671).

Files with missing lines	Patch %	Lines
tesseract_core/runtime/cli.py	7.14%	13 Missing ⚠️
tesseract_core/sdk/engine.py	66.66%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #631      +/-   ##
==========================================
- Coverage   77.95%   77.84%   -0.11%     
==========================================
  Files          39       39              
  Lines        4635     4654      +19     
  Branches      754      759       +5     
==========================================
+ Hits         3613     3623      +10     
- Misses        716      724       +8     
- Partials      306      307       +1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[PasteurBot]

Benchmark Results

Benchmarks use a no-op Tesseract to measure pure framework overhead.

🚀 0 faster, ⚠️ 0 slower, ✅ 36 unchanged

✅ No significant performance changes detected.

Full results

Benchmark	Baseline	Current	Change	Status
api/apply_1,000	0.387ms	0.392ms	+1.3%	✅
api/apply_100,000	0.389ms	0.402ms	+3.2%	✅
api/apply_10,000,000	0.388ms	0.402ms	+3.8%	✅
cli/apply_1,000	1549.433ms	1535.443ms	-0.9%	✅
cli/apply_100,000	1531.974ms	1547.593ms	+1.0%	✅
cli/apply_10,000,000	1618.735ms	1598.840ms	-1.2%	✅
decoding/base64_1,000	0.027ms	0.027ms	+0.5%	✅
decoding/base64_100,000	0.758ms	0.765ms	+0.9%	✅
decoding/base64_10,000,000	110.096ms	111.076ms	+0.9%	✅
decoding/binref_1,000	0.164ms	0.166ms	+1.3%	✅
decoding/binref_100,000	0.257ms	0.261ms	+1.8%	✅
decoding/binref_10,000,000	20.387ms	20.352ms	-0.2%	✅
decoding/json_1,000	0.089ms	0.090ms	+0.5%	✅
decoding/json_100,000	8.330ms	8.359ms	+0.3%	✅
decoding/json_10,000,000	1046.083ms	1045.155ms	-0.1%	✅
encoding/base64_1,000	0.034ms	0.034ms	+0.1%	✅
encoding/base64_100,000	0.210ms	0.194ms	-7.8%	✅
encoding/base64_10,000,000	47.231ms	47.858ms	+1.3%	✅
encoding/binref_1,000	0.244ms	0.235ms	-3.4%	✅
encoding/binref_100,000	0.417ms	0.401ms	-4.0%	✅
encoding/binref_10,000,000	22.902ms	22.589ms	-1.4%	✅
encoding/json_1,000	0.119ms	0.122ms	+2.4%	✅
encoding/json_100,000	10.786ms	11.113ms	+3.0%	✅
encoding/json_10,000,000	1234.002ms	1257.782ms	+1.9%	✅
http/apply_1,000	2.860ms	2.855ms	-0.2%	✅
http/apply_100,000	8.033ms	8.566ms	+6.6%	✅
http/apply_10,000,000	789.644ms	778.800ms	-1.4%	✅
roundtrip/base64_1,000	0.069ms	0.070ms	+0.8%	✅
roundtrip/base64_100,000	1.131ms	1.133ms	+0.2%	✅
roundtrip/base64_10,000,000	159.411ms	158.934ms	-0.3%	✅
roundtrip/binref_1,000	0.409ms	0.420ms	+2.8%	✅
roundtrip/binref_100,000	0.658ms	0.672ms	+2.1%	✅
roundtrip/binref_10,000,000	43.779ms	44.382ms	+1.4%	✅
roundtrip/json_1,000	0.217ms	0.221ms	+1.6%	✅
roundtrip/json_100,000	18.002ms	17.987ms	-0.1%	✅
roundtrip/json_10,000,000	2268.246ms	2296.109ms	+1.2%	✅

• Runner: Linux 6.17.0-1018-azure x86_64