feat(runtime): add FormatJson builtin tool

[luojiyin1987]

Summary

Closes#602

Adds FormatJson builtin tool — see issue #602 for full design.

Changes

• packages/runtime/src/builtin-tools.ts: +39 lines (FormatJson tool definition + sortKeysDeep helper)
• packages/runtime/src/__tests__/builtin-tools.test.ts: +69 lines (7 test cases)

Verification

• Runtime tests: 34/34 pass after rebase onto upstream/main
• No pre-existing tests broken
• Pure function tool — no permission required, no fs side effects

Notes

• Rebased onto upstream/main before opening this PR
• The __proto__ preservation behavior is documented in the test
• sortKeysDeep uses Object.fromEntries to avoid the __proto__ setter prototype pollution risk

[luojiyin1987]

CI Status Note

The failing typecheck job (https://github.com/maka-agent/maka-agent/actions/runs/28851164752/job/85566577387) is not caused by this PR. It is a pre-existing failure on upstream/main where the CapabilityAuditStrip component was simplified (designer-audit round 4) and dropped its focus prop, but the Storybook stories were not updated to match.

Verification

• I rebased this PR onto upstream/main (d229afe8) and re-ran tsc -p tsconfig.storybook.json --noEmit against the rebased branch — the storybook typecheck was the only blocker introduced by rebase.
• The e2e and test jobs both pass (2143/2143 tests pass, 378/378 suites).
• The typecheck failure on the original PR feat(runtime): add FormatJson builtin tool #603 is identical to what upstream/main produces on a clean checkout (verified locally).

Fix

I opened #608 which removes the stale focus prop from the four CapabilityAuditStrip usages in the Storybook stories. Once that is merged into main, this PR should rebase cleanly and turn green.

If the maintainers prefer a different fix (e.g. re-adding the focus prop to the component), I am happy to adjust the scope. Either way, the typecheck failure in #603 is not introduced by this PR — it is pre-existing.

[jackwener]

Thanks — the implementation itself is clean (the proto preservation test and recursive sort coverage are genuinely good). Closing on first-principles grounds rather than code quality:

The tool's economics don't work as a string→string function.content is a required string parameter, so the model must emit the entire JSON payload into the tool call before getting it back reformatted — that's ~2× the tokens of the model simply writing the formatted JSON directly, which any current model does reliably. There's no size threshold where this wins: bigger payloads make the round-trip cost worse, not better.

The capability already exists in-session. For on-disk JSON the agent uses Bash (jq ., python3 -m json.tool) without round-tripping content through the prompt; for in-context JSON it just… writes formatted JSON.

Every builtin has a standing cost — a slot in every session's tool list that all prompts pay for and the model must consider. That budget should go to tools that unlock something the model can't do: side effects, host access, privileged data.

A version of this that WOULD carry its weight: FormatJson({ path, sort_keys }) that validates/normalizes a JSON file in place and returns only a diagnostic (valid/error + byte delta) — no content round-trip, useful for config hygiene after Write. If you want to pursue that, happy to review it in a fresh PR against #602.

[luojiyin1987]

Summary

Closes#602

Adds FormatJson builtin tool — see issue #602 for full design.

Changes

• packages/runtime/src/builtin-tools.ts: +39 lines (FormatJson tool definition + sortKeysDeep helper)
• packages/runtime/src/__tests__/builtin-tools.test.ts: +69 lines (7 test cases)

Verification

• Runtime tests: 34/34 pass after rebase onto upstream/main
• No pre-existing tests broken
• Pure function tool — no permission required, no fs side effects

Notes

• Rebased onto upstream/main before opening this PR
• The __proto__ preservation behavior is documented in the test
• sortKeysDeep uses Object.fromEntries to avoid the __proto__ setter prototype pollution risk

[luojiyin1987]

CI Status Note

The failing typecheck job (https://github.com/maka-agent/maka-agent/actions/runs/28851164752/job/85566577387) is not caused by this PR. It is a pre-existing failure on upstream/main where the CapabilityAuditStrip component was simplified (designer-audit round 4) and dropped its focus prop, but the Storybook stories were not updated to match.

Verification

• I rebased this PR onto upstream/main (d229afe8) and re-ran tsc -p tsconfig.storybook.json --noEmit against the rebased branch — the storybook typecheck was the only blocker introduced by rebase.
• The e2e and test jobs both pass (2143/2143 tests pass, 378/378 suites).
• The typecheck failure on the original PR feat(runtime): add FormatJson builtin tool #603 is identical to what upstream/main produces on a clean checkout (verified locally).

Fix

I opened #608 which removes the stale focus prop from the four CapabilityAuditStrip usages in the Storybook stories. Once that is merged into main, this PR should rebase cleanly and turn green.

If the maintainers prefer a different fix (e.g. re-adding the focus prop to the component), I am happy to adjust the scope. Either way, the typecheck failure in #603 is not introduced by this PR — it is pre-existing.

[jackwener]

Thanks — the implementation itself is clean (the proto preservation test and recursive sort coverage are genuinely good). Closing on first-principles grounds rather than code quality:

The tool's economics don't work as a string→string function.content is a required string parameter, so the model must emit the entire JSON payload into the tool call before getting it back reformatted — that's ~2× the tokens of the model simply writing the formatted JSON directly, which any current model does reliably. There's no size threshold where this wins: bigger payloads make the round-trip cost worse, not better.

The capability already exists in-session. For on-disk JSON the agent uses Bash (jq ., python3 -m json.tool) without round-tripping content through the prompt; for in-context JSON it just… writes formatted JSON.

Every builtin has a standing cost — a slot in every session's tool list that all prompts pay for and the model must consider. That budget should go to tools that unlock something the model can't do: side effects, host access, privileged data.

A version of this that WOULD carry its weight: FormatJson({ path, sort_keys }) that validates/normalizes a JSON file in place and returns only a diagnostic (valid/error + byte delta) — no content round-trip, useful for config hygiene after Write. If you want to pursue that, happy to review it in a fresh PR against #602.

[luojiyin1987]

Summary

Closes#602

Adds FormatJson builtin tool — see issue #602 for full design.

Changes

• packages/runtime/src/builtin-tools.ts: +39 lines (FormatJson tool definition + sortKeysDeep helper)
• packages/runtime/src/__tests__/builtin-tools.test.ts: +69 lines (7 test cases)

Verification

• Runtime tests: 34/34 pass after rebase onto upstream/main
• No pre-existing tests broken
• Pure function tool — no permission required, no fs side effects

Notes

• Rebased onto upstream/main before opening this PR
• The __proto__ preservation behavior is documented in the test
• sortKeysDeep uses Object.fromEntries to avoid the __proto__ setter prototype pollution risk

[luojiyin1987]

CI Status Note

The failing typecheck job (https://github.com/maka-agent/maka-agent/actions/runs/28851164752/job/85566577387) is not caused by this PR. It is a pre-existing failure on upstream/main where the CapabilityAuditStrip component was simplified (designer-audit round 4) and dropped its focus prop, but the Storybook stories were not updated to match.

Verification

• I rebased this PR onto upstream/main (d229afe8) and re-ran tsc -p tsconfig.storybook.json --noEmit against the rebased branch — the storybook typecheck was the only blocker introduced by rebase.
• The e2e and test jobs both pass (2143/2143 tests pass, 378/378 suites).
• The typecheck failure on the original PR feat(runtime): add FormatJson builtin tool #603 is identical to what upstream/main produces on a clean checkout (verified locally).

Fix

I opened #608 which removes the stale focus prop from the four CapabilityAuditStrip usages in the Storybook stories. Once that is merged into main, this PR should rebase cleanly and turn green.

If the maintainers prefer a different fix (e.g. re-adding the focus prop to the component), I am happy to adjust the scope. Either way, the typecheck failure in #603 is not introduced by this PR — it is pre-existing.

[jackwener]

Thanks — the implementation itself is clean (the proto preservation test and recursive sort coverage are genuinely good). Closing on first-principles grounds rather than code quality:

The tool's economics don't work as a string→string function.content is a required string parameter, so the model must emit the entire JSON payload into the tool call before getting it back reformatted — that's ~2× the tokens of the model simply writing the formatted JSON directly, which any current model does reliably. There's no size threshold where this wins: bigger payloads make the round-trip cost worse, not better.

The capability already exists in-session. For on-disk JSON the agent uses Bash (jq ., python3 -m json.tool) without round-tripping content through the prompt; for in-context JSON it just… writes formatted JSON.

Every builtin has a standing cost — a slot in every session's tool list that all prompts pay for and the model must consider. That budget should go to tools that unlock something the model can't do: side effects, host access, privileged data.

A version of this that WOULD carry its weight: FormatJson({ path, sort_keys }) that validates/normalizes a JSON file in place and returns only a diagnostic (valid/error + byte delta) — no content round-trip, useful for config hygiene after Write. If you want to pursue that, happy to review it in a fresh PR against #602.

[luojiyin1987]

Summary

Closes#602

Adds FormatJson builtin tool — see issue #602 for full design.

Changes

• packages/runtime/src/builtin-tools.ts: +39 lines (FormatJson tool definition + sortKeysDeep helper)
• packages/runtime/src/__tests__/builtin-tools.test.ts: +69 lines (7 test cases)

Verification

• Runtime tests: 34/34 pass after rebase onto upstream/main
• No pre-existing tests broken
• Pure function tool — no permission required, no fs side effects

Notes

• Rebased onto upstream/main before opening this PR
• The __proto__ preservation behavior is documented in the test
• sortKeysDeep uses Object.fromEntries to avoid the __proto__ setter prototype pollution risk

[luojiyin1987]

CI Status Note

The failing typecheck job (https://github.com/maka-agent/maka-agent/actions/runs/28851164752/job/85566577387) is not caused by this PR. It is a pre-existing failure on upstream/main where the CapabilityAuditStrip component was simplified (designer-audit round 4) and dropped its focus prop, but the Storybook stories were not updated to match.

Verification

• I rebased this PR onto upstream/main (d229afe8) and re-ran tsc -p tsconfig.storybook.json --noEmit against the rebased branch — the storybook typecheck was the only blocker introduced by rebase.
• The e2e and test jobs both pass (2143/2143 tests pass, 378/378 suites).
• The typecheck failure on the original PR feat(runtime): add FormatJson builtin tool #603 is identical to what upstream/main produces on a clean checkout (verified locally).

Fix

I opened #608 which removes the stale focus prop from the four CapabilityAuditStrip usages in the Storybook stories. Once that is merged into main, this PR should rebase cleanly and turn green.

If the maintainers prefer a different fix (e.g. re-adding the focus prop to the component), I am happy to adjust the scope. Either way, the typecheck failure in #603 is not introduced by this PR — it is pre-existing.

[jackwener]

Thanks — the implementation itself is clean (the proto preservation test and recursive sort coverage are genuinely good). Closing on first-principles grounds rather than code quality:

The tool's economics don't work as a string→string function.content is a required string parameter, so the model must emit the entire JSON payload into the tool call before getting it back reformatted — that's ~2× the tokens of the model simply writing the formatted JSON directly, which any current model does reliably. There's no size threshold where this wins: bigger payloads make the round-trip cost worse, not better.

The capability already exists in-session. For on-disk JSON the agent uses Bash (jq ., python3 -m json.tool) without round-tripping content through the prompt; for in-context JSON it just… writes formatted JSON.

Every builtin has a standing cost — a slot in every session's tool list that all prompts pay for and the model must consider. That budget should go to tools that unlock something the model can't do: side effects, host access, privileged data.

A version of this that WOULD carry its weight: FormatJson({ path, sort_keys }) that validates/normalizes a JSON file in place and returns only a diagnostic (valid/error + byte delta) — no content round-trip, useful for config hygiene after Write. If you want to pursue that, happy to review it in a fresh PR against #602.

[luojiyin1987]

Summary

Closes#602

Adds FormatJson builtin tool — see issue #602 for full design.

Changes

• packages/runtime/src/builtin-tools.ts: +39 lines (FormatJson tool definition + sortKeysDeep helper)
• packages/runtime/src/__tests__/builtin-tools.test.ts: +69 lines (7 test cases)

Verification

• Runtime tests: 34/34 pass after rebase onto upstream/main
• No pre-existing tests broken
• Pure function tool — no permission required, no fs side effects

Notes

• Rebased onto upstream/main before opening this PR
• The __proto__ preservation behavior is documented in the test
• sortKeysDeep uses Object.fromEntries to avoid the __proto__ setter prototype pollution risk

[luojiyin1987]

CI Status Note

The failing typecheck job (https://github.com/maka-agent/maka-agent/actions/runs/28851164752/job/85566577387) is not caused by this PR. It is a pre-existing failure on upstream/main where the CapabilityAuditStrip component was simplified (designer-audit round 4) and dropped its focus prop, but the Storybook stories were not updated to match.

Verification

• I rebased this PR onto upstream/main (d229afe8) and re-ran tsc -p tsconfig.storybook.json --noEmit against the rebased branch — the storybook typecheck was the only blocker introduced by rebase.
• The e2e and test jobs both pass (2143/2143 tests pass, 378/378 suites).
• The typecheck failure on the original PR feat(runtime): add FormatJson builtin tool #603 is identical to what upstream/main produces on a clean checkout (verified locally).

Fix

I opened #608 which removes the stale focus prop from the four CapabilityAuditStrip usages in the Storybook stories. Once that is merged into main, this PR should rebase cleanly and turn green.

If the maintainers prefer a different fix (e.g. re-adding the focus prop to the component), I am happy to adjust the scope. Either way, the typecheck failure in #603 is not introduced by this PR — it is pre-existing.

[jackwener]

Thanks — the implementation itself is clean (the proto preservation test and recursive sort coverage are genuinely good). Closing on first-principles grounds rather than code quality:

The tool's economics don't work as a string→string function.content is a required string parameter, so the model must emit the entire JSON payload into the tool call before getting it back reformatted — that's ~2× the tokens of the model simply writing the formatted JSON directly, which any current model does reliably. There's no size threshold where this wins: bigger payloads make the round-trip cost worse, not better.

The capability already exists in-session. For on-disk JSON the agent uses Bash (jq ., python3 -m json.tool) without round-tripping content through the prompt; for in-context JSON it just… writes formatted JSON.

Every builtin has a standing cost — a slot in every session's tool list that all prompts pay for and the model must consider. That budget should go to tools that unlock something the model can't do: side effects, host access, privileged data.

A version of this that WOULD carry its weight: FormatJson({ path, sort_keys }) that validates/normalizes a JSON file in place and returns only a diagnostic (valid/error + byte delta) — no content round-trip, useful for config hygiene after Write. If you want to pursue that, happy to review it in a fresh PR against #602.

[luojiyin1987]

Summary

Closes#602

Adds FormatJson builtin tool — see issue #602 for full design.

Changes

• packages/runtime/src/builtin-tools.ts: +39 lines (FormatJson tool definition + sortKeysDeep helper)
• packages/runtime/src/__tests__/builtin-tools.test.ts: +69 lines (7 test cases)

Verification

• Runtime tests: 34/34 pass after rebase onto upstream/main
• No pre-existing tests broken
• Pure function tool — no permission required, no fs side effects

Notes

• Rebased onto upstream/main before opening this PR
• The __proto__ preservation behavior is documented in the test
• sortKeysDeep uses Object.fromEntries to avoid the __proto__ setter prototype pollution risk

[luojiyin1987]

CI Status Note

The failing typecheck job (https://github.com/maka-agent/maka-agent/actions/runs/28851164752/job/85566577387) is not caused by this PR. It is a pre-existing failure on upstream/main where the CapabilityAuditStrip component was simplified (designer-audit round 4) and dropped its focus prop, but the Storybook stories were not updated to match.

Verification

• I rebased this PR onto upstream/main (d229afe8) and re-ran tsc -p tsconfig.storybook.json --noEmit against the rebased branch — the storybook typecheck was the only blocker introduced by rebase.
• The e2e and test jobs both pass (2143/2143 tests pass, 378/378 suites).
• The typecheck failure on the original PR feat(runtime): add FormatJson builtin tool #603 is identical to what upstream/main produces on a clean checkout (verified locally).

Fix

I opened #608 which removes the stale focus prop from the four CapabilityAuditStrip usages in the Storybook stories. Once that is merged into main, this PR should rebase cleanly and turn green.

If the maintainers prefer a different fix (e.g. re-adding the focus prop to the component), I am happy to adjust the scope. Either way, the typecheck failure in #603 is not introduced by this PR — it is pre-existing.

[jackwener]

Thanks — the implementation itself is clean (the proto preservation test and recursive sort coverage are genuinely good). Closing on first-principles grounds rather than code quality:

The tool's economics don't work as a string→string function.content is a required string parameter, so the model must emit the entire JSON payload into the tool call before getting it back reformatted — that's ~2× the tokens of the model simply writing the formatted JSON directly, which any current model does reliably. There's no size threshold where this wins: bigger payloads make the round-trip cost worse, not better.

The capability already exists in-session. For on-disk JSON the agent uses Bash (jq ., python3 -m json.tool) without round-tripping content through the prompt; for in-context JSON it just… writes formatted JSON.

Every builtin has a standing cost — a slot in every session's tool list that all prompts pay for and the model must consider. That budget should go to tools that unlock something the model can't do: side effects, host access, privileged data.

A version of this that WOULD carry its weight: FormatJson({ path, sort_keys }) that validates/normalizes a JSON file in place and returns only a diagnostic (valid/error + byte delta) — no content round-trip, useful for config hygiene after Write. If you want to pursue that, happy to review it in a fresh PR against #602.

[luojiyin1987]

Summary

Closes#602

Adds FormatJson builtin tool — see issue #602 for full design.

Changes

• packages/runtime/src/builtin-tools.ts: +39 lines (FormatJson tool definition + sortKeysDeep helper)
• packages/runtime/src/__tests__/builtin-tools.test.ts: +69 lines (7 test cases)

Verification

• Runtime tests: 34/34 pass after rebase onto upstream/main
• No pre-existing tests broken
• Pure function tool — no permission required, no fs side effects

Notes

• Rebased onto upstream/main before opening this PR
• The __proto__ preservation behavior is documented in the test
• sortKeysDeep uses Object.fromEntries to avoid the __proto__ setter prototype pollution risk

[luojiyin1987]

CI Status Note

The failing typecheck job (https://github.com/maka-agent/maka-agent/actions/runs/28851164752/job/85566577387) is not caused by this PR. It is a pre-existing failure on upstream/main where the CapabilityAuditStrip component was simplified (designer-audit round 4) and dropped its focus prop, but the Storybook stories were not updated to match.

Verification

• I rebased this PR onto upstream/main (d229afe8) and re-ran tsc -p tsconfig.storybook.json --noEmit against the rebased branch — the storybook typecheck was the only blocker introduced by rebase.
• The e2e and test jobs both pass (2143/2143 tests pass, 378/378 suites).
• The typecheck failure on the original PR feat(runtime): add FormatJson builtin tool #603 is identical to what upstream/main produces on a clean checkout (verified locally).

Fix

I opened #608 which removes the stale focus prop from the four CapabilityAuditStrip usages in the Storybook stories. Once that is merged into main, this PR should rebase cleanly and turn green.

If the maintainers prefer a different fix (e.g. re-adding the focus prop to the component), I am happy to adjust the scope. Either way, the typecheck failure in #603 is not introduced by this PR — it is pre-existing.

[jackwener]

Thanks — the implementation itself is clean (the proto preservation test and recursive sort coverage are genuinely good). Closing on first-principles grounds rather than code quality:

The tool's economics don't work as a string→string function.content is a required string parameter, so the model must emit the entire JSON payload into the tool call before getting it back reformatted — that's ~2× the tokens of the model simply writing the formatted JSON directly, which any current model does reliably. There's no size threshold where this wins: bigger payloads make the round-trip cost worse, not better.

The capability already exists in-session. For on-disk JSON the agent uses Bash (jq ., python3 -m json.tool) without round-tripping content through the prompt; for in-context JSON it just… writes formatted JSON.

Every builtin has a standing cost — a slot in every session's tool list that all prompts pay for and the model must consider. That budget should go to tools that unlock something the model can't do: side effects, host access, privileged data.

A version of this that WOULD carry its weight: FormatJson({ path, sort_keys }) that validates/normalizes a JSON file in place and returns only a diagnostic (valid/error + byte delta) — no content round-trip, useful for config hygiene after Write. If you want to pursue that, happy to review it in a fresh PR against #602.

[luojiyin1987]

Summary

Closes#602

Adds FormatJson builtin tool — see issue #602 for full design.

Changes

• packages/runtime/src/builtin-tools.ts: +39 lines (FormatJson tool definition + sortKeysDeep helper)
• packages/runtime/src/__tests__/builtin-tools.test.ts: +69 lines (7 test cases)

Verification

• Runtime tests: 34/34 pass after rebase onto upstream/main
• No pre-existing tests broken
• Pure function tool — no permission required, no fs side effects

Notes

• Rebased onto upstream/main before opening this PR
• The __proto__ preservation behavior is documented in the test
• sortKeysDeep uses Object.fromEntries to avoid the __proto__ setter prototype pollution risk

[luojiyin1987]

CI Status Note

The failing typecheck job (https://github.com/maka-agent/maka-agent/actions/runs/28851164752/job/85566577387) is not caused by this PR. It is a pre-existing failure on upstream/main where the CapabilityAuditStrip component was simplified (designer-audit round 4) and dropped its focus prop, but the Storybook stories were not updated to match.

Verification

• I rebased this PR onto upstream/main (d229afe8) and re-ran tsc -p tsconfig.storybook.json --noEmit against the rebased branch — the storybook typecheck was the only blocker introduced by rebase.
• The e2e and test jobs both pass (2143/2143 tests pass, 378/378 suites).
• The typecheck failure on the original PR feat(runtime): add FormatJson builtin tool #603 is identical to what upstream/main produces on a clean checkout (verified locally).

Fix

I opened #608 which removes the stale focus prop from the four CapabilityAuditStrip usages in the Storybook stories. Once that is merged into main, this PR should rebase cleanly and turn green.

If the maintainers prefer a different fix (e.g. re-adding the focus prop to the component), I am happy to adjust the scope. Either way, the typecheck failure in #603 is not introduced by this PR — it is pre-existing.

[jackwener]

Thanks — the implementation itself is clean (the proto preservation test and recursive sort coverage are genuinely good). Closing on first-principles grounds rather than code quality:

The tool's economics don't work as a string→string function.content is a required string parameter, so the model must emit the entire JSON payload into the tool call before getting it back reformatted — that's ~2× the tokens of the model simply writing the formatted JSON directly, which any current model does reliably. There's no size threshold where this wins: bigger payloads make the round-trip cost worse, not better.

The capability already exists in-session. For on-disk JSON the agent uses Bash (jq ., python3 -m json.tool) without round-tripping content through the prompt; for in-context JSON it just… writes formatted JSON.

Every builtin has a standing cost — a slot in every session's tool list that all prompts pay for and the model must consider. That budget should go to tools that unlock something the model can't do: side effects, host access, privileged data.

A version of this that WOULD carry its weight: FormatJson({ path, sort_keys }) that validates/normalizes a JSON file in place and returns only a diagnostic (valid/error + byte delta) — no content round-trip, useful for config hygiene after Write. If you want to pursue that, happy to review it in a fresh PR against #602.