[KhaiTrang1995]

Summary

Add colab exec --json, which prints one JSON object per executed cell so
scripts and AI agents can tell whether code succeeded without scraping text.

Problem

colab exec exits 0 after a kernel error and prints an ANSI-coloured
traceback. A caller driving the CLI cannot detect a failed run from the exit
status, and has to parse coloured text to find the error.

Solution

With --json:

• stdout carries one JSON object per cell (NDJSON): cell_index, cell_id,
  status, stdout, stderr, data, images, error.
• error.traceback is plain text with ANSI escapes removed.
• Images are saved to disk (honouring --output-image) and reported by path,
  never inlined as base64.
• [colab] progress lines go to stderr.
• Exit status is 1 when any cell failed.

Example:

$ echo '1/0' | colab exec -s demo --json
{"cell_index": 0, "cell_id": null, "status": "error", "stdout": "",
 "stderr": "", "data": [], "images": [],
 "error": {"ename": "ZeroDivisionError", "evalue": "division by zero",
           "traceback": "..."}}
$ echo $?
1

Compatibility

Opt-in. Without --json, output and exit status are unchanged (covered by
test_exec_without_json_still_exits_zero_on_kernel_error). No new
dependencies.

Changes

• commands/execution.py: --json option, build_json_record.
• utils.py: split save_image out of handle_image (no behaviour change).
• tests/test_exec_json.py: 7 new tests, written first.
• Docs: README command index, CHANGELOG, docs/02_execution_and_interactive.md,
  skills/colab-operator/SKILL.md.

Testing

• pytest: new tests pass; no new failures in the existing suite
• ruff check and ruff format
• End-to-end on a live Colab session (stdin, .py, .ipynb, a failing
  cell, a plot)

Out of scope

--json for status / sessions, and live streaming of partial output.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[KhaiTrang1995]

@googlebot I signed it!

[KhaiTrang1995]

Hi maintainers, the CLA is signed and the check is green now.

I know CONTRIBUTING.md says external PRs aren't being accepted at the moment, so no pressure to review this. I opened it mainly to show a concrete proposal: colab exec exits 0 on a kernel error, which makes it hard for scripts and AI agents to tell whether a run failed. --json is opt-in and leaves the default behaviour unchanged.

If you'd rather discuss this in Discussions first, or want a different shape (e.g. only the non-zero exit code), I'm happy to move it there or rework it. Feel free to close this if it doesn't fit your plans.

One caveat: I have not run the end-to-end check on a live Colab session yet; only the unit tests.