feat(runtime): rework FormatJson as file-in-place JSON validator

[luojiyin1987]

Summary

Reworked per the review on #603 (comment on the closed PR). The previous FormatJson({ content }) string→string form was rejected on first-principles grounds: it round-trips the entire JSON payload through the prompt (~2× tokens) for a capability the model already has directly, and burns a standing slot in every session's tool list.

This version follows the shape the maintainer said would carry its weight — FormatJson({ path, sort_keys }) that validates/normalizes a JSON file in place and returns only a diagnostic, no content round-trip.

Closes#602. Supersedes #603.

Behavior

Both success and failure return a single diagnostic object (matching "valid/error + byte delta"):

• Valid file → { ok: true, valid: true, path, bytesBefore, bytesAfter, byteDelta, changed }
• Invalid JSON → { ok: false, valid: false, error, byteDelta: 0, changed: false }, leaving the file untouched

Changes

• packages/runtime/src/builtin-tools.ts
  • New FormatJson tool: reads path, parses (returns { ok: false, valid: false, error, byteDelta: 0, changed: false } on invalid JSON, leaving the file untouched — no throw), optionally sorts object keys, rewrites with canonical 2-space indentation.
  • permissionRequired: true (in-place file mutation, same as Edit); uses the existing per-path write lock + path resolution.
  • Returns diagnostic only: { ok, path, valid, bytesBefore, bytesAfter, byteDelta, changed }.
  • Reuses sortKeysDeep, which preserves __proto__ as an own data property (no prototype-pollution).
• packages/runtime/src/__tests__/builtin-tools.test.ts
  • File-based tests (real temp dirs): happy path rewrites in place, sort_keys ordering (incl. __proto__ + nested recursion), invalid JSON returns the structured error diagnostic (no write, byteDelta: 0), already-canonical content reports changed: false / zero byteDelta, unicode handling, diagnostic fields.

Verification

• npm run -w @maka/runtime typecheck — clean
• npm run -w @maka/runtime test — all pass (FormatJson block green)

Notes

Strictly path + sort_keys only (no indent param) per the agreed scope. Useful for config hygiene after a Write.

[luojiyin1987]

Summary

Reworked per the review on #603 (comment on the closed PR). The previous FormatJson({ content }) string→string form was rejected on first-principles grounds: it round-trips the entire JSON payload through the prompt (~2× tokens) for a capability the model already has directly, and burns a standing slot in every session's tool list.

This version follows the shape the maintainer said would carry its weight — FormatJson({ path, sort_keys }) that validates/normalizes a JSON file in place and returns only a diagnostic, no content round-trip.

Closes#602. Supersedes #603.

Behavior

Both success and failure return a single diagnostic object (matching "valid/error + byte delta"):

• Valid file → { ok: true, valid: true, path, bytesBefore, bytesAfter, byteDelta, changed }
• Invalid JSON → { ok: false, valid: false, error, byteDelta: 0, changed: false }, leaving the file untouched

Changes

• packages/runtime/src/builtin-tools.ts
  • New FormatJson tool: reads path, parses (returns { ok: false, valid: false, error, byteDelta: 0, changed: false } on invalid JSON, leaving the file untouched — no throw), optionally sorts object keys, rewrites with canonical 2-space indentation.
  • permissionRequired: true (in-place file mutation, same as Edit); uses the existing per-path write lock + path resolution.
  • Returns diagnostic only: { ok, path, valid, bytesBefore, bytesAfter, byteDelta, changed }.
  • Reuses sortKeysDeep, which preserves __proto__ as an own data property (no prototype-pollution).
• packages/runtime/src/__tests__/builtin-tools.test.ts
  • File-based tests (real temp dirs): happy path rewrites in place, sort_keys ordering (incl. __proto__ + nested recursion), invalid JSON returns the structured error diagnostic (no write, byteDelta: 0), already-canonical content reports changed: false / zero byteDelta, unicode handling, diagnostic fields.

Verification

• npm run -w @maka/runtime typecheck — clean
• npm run -w @maka/runtime test — all pass (FormatJson block green)

Notes

Strictly path + sort_keys only (no indent param) per the agreed scope. Useful for config hygiene after a Write.

[luojiyin1987]

Summary

Reworked per the review on #603 (comment on the closed PR). The previous FormatJson({ content }) string→string form was rejected on first-principles grounds: it round-trips the entire JSON payload through the prompt (~2× tokens) for a capability the model already has directly, and burns a standing slot in every session's tool list.

This version follows the shape the maintainer said would carry its weight — FormatJson({ path, sort_keys }) that validates/normalizes a JSON file in place and returns only a diagnostic, no content round-trip.

Closes#602. Supersedes #603.

Behavior

Both success and failure return a single diagnostic object (matching "valid/error + byte delta"):

• Valid file → { ok: true, valid: true, path, bytesBefore, bytesAfter, byteDelta, changed }
• Invalid JSON → { ok: false, valid: false, error, byteDelta: 0, changed: false }, leaving the file untouched

Changes

• packages/runtime/src/builtin-tools.ts
  • New FormatJson tool: reads path, parses (returns { ok: false, valid: false, error, byteDelta: 0, changed: false } on invalid JSON, leaving the file untouched — no throw), optionally sorts object keys, rewrites with canonical 2-space indentation.
  • permissionRequired: true (in-place file mutation, same as Edit); uses the existing per-path write lock + path resolution.
  • Returns diagnostic only: { ok, path, valid, bytesBefore, bytesAfter, byteDelta, changed }.
  • Reuses sortKeysDeep, which preserves __proto__ as an own data property (no prototype-pollution).
• packages/runtime/src/__tests__/builtin-tools.test.ts
  • File-based tests (real temp dirs): happy path rewrites in place, sort_keys ordering (incl. __proto__ + nested recursion), invalid JSON returns the structured error diagnostic (no write, byteDelta: 0), already-canonical content reports changed: false / zero byteDelta, unicode handling, diagnostic fields.

Verification

• npm run -w @maka/runtime typecheck — clean
• npm run -w @maka/runtime test — all pass (FormatJson block green)

Notes

Strictly path + sort_keys only (no indent param) per the agreed scope. Useful for config hygiene after a Write.

[luojiyin1987]

Summary

Reworked per the review on #603 (comment on the closed PR). The previous FormatJson({ content }) string→string form was rejected on first-principles grounds: it round-trips the entire JSON payload through the prompt (~2× tokens) for a capability the model already has directly, and burns a standing slot in every session's tool list.

This version follows the shape the maintainer said would carry its weight — FormatJson({ path, sort_keys }) that validates/normalizes a JSON file in place and returns only a diagnostic, no content round-trip.

Closes#602. Supersedes #603.

Behavior

Both success and failure return a single diagnostic object (matching "valid/error + byte delta"):

• Valid file → { ok: true, valid: true, path, bytesBefore, bytesAfter, byteDelta, changed }
• Invalid JSON → { ok: false, valid: false, error, byteDelta: 0, changed: false }, leaving the file untouched

Changes

• packages/runtime/src/builtin-tools.ts
  • New FormatJson tool: reads path, parses (returns { ok: false, valid: false, error, byteDelta: 0, changed: false } on invalid JSON, leaving the file untouched — no throw), optionally sorts object keys, rewrites with canonical 2-space indentation.
  • permissionRequired: true (in-place file mutation, same as Edit); uses the existing per-path write lock + path resolution.
  • Returns diagnostic only: { ok, path, valid, bytesBefore, bytesAfter, byteDelta, changed }.
  • Reuses sortKeysDeep, which preserves __proto__ as an own data property (no prototype-pollution).
• packages/runtime/src/__tests__/builtin-tools.test.ts
  • File-based tests (real temp dirs): happy path rewrites in place, sort_keys ordering (incl. __proto__ + nested recursion), invalid JSON returns the structured error diagnostic (no write, byteDelta: 0), already-canonical content reports changed: false / zero byteDelta, unicode handling, diagnostic fields.

Verification

• npm run -w @maka/runtime typecheck — clean
• npm run -w @maka/runtime test — all pass (FormatJson block green)

Notes

Strictly path + sort_keys only (no indent param) per the agreed scope. Useful for config hygiene after a Write.

[luojiyin1987]

Summary

Reworked per the review on #603 (comment on the closed PR). The previous FormatJson({ content }) string→string form was rejected on first-principles grounds: it round-trips the entire JSON payload through the prompt (~2× tokens) for a capability the model already has directly, and burns a standing slot in every session's tool list.

This version follows the shape the maintainer said would carry its weight — FormatJson({ path, sort_keys }) that validates/normalizes a JSON file in place and returns only a diagnostic, no content round-trip.

Closes#602. Supersedes #603.

Behavior

Both success and failure return a single diagnostic object (matching "valid/error + byte delta"):

• Valid file → { ok: true, valid: true, path, bytesBefore, bytesAfter, byteDelta, changed }
• Invalid JSON → { ok: false, valid: false, error, byteDelta: 0, changed: false }, leaving the file untouched

Changes

• packages/runtime/src/builtin-tools.ts
  • New FormatJson tool: reads path, parses (returns { ok: false, valid: false, error, byteDelta: 0, changed: false } on invalid JSON, leaving the file untouched — no throw), optionally sorts object keys, rewrites with canonical 2-space indentation.
  • permissionRequired: true (in-place file mutation, same as Edit); uses the existing per-path write lock + path resolution.
  • Returns diagnostic only: { ok, path, valid, bytesBefore, bytesAfter, byteDelta, changed }.
  • Reuses sortKeysDeep, which preserves __proto__ as an own data property (no prototype-pollution).
• packages/runtime/src/__tests__/builtin-tools.test.ts
  • File-based tests (real temp dirs): happy path rewrites in place, sort_keys ordering (incl. __proto__ + nested recursion), invalid JSON returns the structured error diagnostic (no write, byteDelta: 0), already-canonical content reports changed: false / zero byteDelta, unicode handling, diagnostic fields.

Verification

• npm run -w @maka/runtime typecheck — clean
• npm run -w @maka/runtime test — all pass (FormatJson block green)

Notes

Strictly path + sort_keys only (no indent param) per the agreed scope. Useful for config hygiene after a Write.

[luojiyin1987]

Summary

Reworked per the review on #603 (comment on the closed PR). The previous FormatJson({ content }) string→string form was rejected on first-principles grounds: it round-trips the entire JSON payload through the prompt (~2× tokens) for a capability the model already has directly, and burns a standing slot in every session's tool list.

This version follows the shape the maintainer said would carry its weight — FormatJson({ path, sort_keys }) that validates/normalizes a JSON file in place and returns only a diagnostic, no content round-trip.

Closes#602. Supersedes #603.

Behavior

Both success and failure return a single diagnostic object (matching "valid/error + byte delta"):

• Valid file → { ok: true, valid: true, path, bytesBefore, bytesAfter, byteDelta, changed }
• Invalid JSON → { ok: false, valid: false, error, byteDelta: 0, changed: false }, leaving the file untouched

Changes

• packages/runtime/src/builtin-tools.ts
  • New FormatJson tool: reads path, parses (returns { ok: false, valid: false, error, byteDelta: 0, changed: false } on invalid JSON, leaving the file untouched — no throw), optionally sorts object keys, rewrites with canonical 2-space indentation.
  • permissionRequired: true (in-place file mutation, same as Edit); uses the existing per-path write lock + path resolution.
  • Returns diagnostic only: { ok, path, valid, bytesBefore, bytesAfter, byteDelta, changed }.
  • Reuses sortKeysDeep, which preserves __proto__ as an own data property (no prototype-pollution).
• packages/runtime/src/__tests__/builtin-tools.test.ts
  • File-based tests (real temp dirs): happy path rewrites in place, sort_keys ordering (incl. __proto__ + nested recursion), invalid JSON returns the structured error diagnostic (no write, byteDelta: 0), already-canonical content reports changed: false / zero byteDelta, unicode handling, diagnostic fields.

Verification

• npm run -w @maka/runtime typecheck — clean
• npm run -w @maka/runtime test — all pass (FormatJson block green)

Notes

Strictly path + sort_keys only (no indent param) per the agreed scope. Useful for config hygiene after a Write.

[luojiyin1987]

Summary

Reworked per the review on #603 (comment on the closed PR). The previous FormatJson({ content }) string→string form was rejected on first-principles grounds: it round-trips the entire JSON payload through the prompt (~2× tokens) for a capability the model already has directly, and burns a standing slot in every session's tool list.

This version follows the shape the maintainer said would carry its weight — FormatJson({ path, sort_keys }) that validates/normalizes a JSON file in place and returns only a diagnostic, no content round-trip.

Closes#602. Supersedes #603.

Behavior

Both success and failure return a single diagnostic object (matching "valid/error + byte delta"):

• Valid file → { ok: true, valid: true, path, bytesBefore, bytesAfter, byteDelta, changed }
• Invalid JSON → { ok: false, valid: false, error, byteDelta: 0, changed: false }, leaving the file untouched

Changes

• packages/runtime/src/builtin-tools.ts
  • New FormatJson tool: reads path, parses (returns { ok: false, valid: false, error, byteDelta: 0, changed: false } on invalid JSON, leaving the file untouched — no throw), optionally sorts object keys, rewrites with canonical 2-space indentation.
  • permissionRequired: true (in-place file mutation, same as Edit); uses the existing per-path write lock + path resolution.
  • Returns diagnostic only: { ok, path, valid, bytesBefore, bytesAfter, byteDelta, changed }.
  • Reuses sortKeysDeep, which preserves __proto__ as an own data property (no prototype-pollution).
• packages/runtime/src/__tests__/builtin-tools.test.ts
  • File-based tests (real temp dirs): happy path rewrites in place, sort_keys ordering (incl. __proto__ + nested recursion), invalid JSON returns the structured error diagnostic (no write, byteDelta: 0), already-canonical content reports changed: false / zero byteDelta, unicode handling, diagnostic fields.

Verification

• npm run -w @maka/runtime typecheck — clean
• npm run -w @maka/runtime test — all pass (FormatJson block green)

Notes

Strictly path + sort_keys only (no indent param) per the agreed scope. Useful for config hygiene after a Write.

[luojiyin1987]

Summary

Reworked per the review on #603 (comment on the closed PR). The previous FormatJson({ content }) string→string form was rejected on first-principles grounds: it round-trips the entire JSON payload through the prompt (~2× tokens) for a capability the model already has directly, and burns a standing slot in every session's tool list.

This version follows the shape the maintainer said would carry its weight — FormatJson({ path, sort_keys }) that validates/normalizes a JSON file in place and returns only a diagnostic, no content round-trip.

Closes#602. Supersedes #603.

Behavior

Both success and failure return a single diagnostic object (matching "valid/error + byte delta"):

• Valid file → { ok: true, valid: true, path, bytesBefore, bytesAfter, byteDelta, changed }
• Invalid JSON → { ok: false, valid: false, error, byteDelta: 0, changed: false }, leaving the file untouched

Changes

• packages/runtime/src/builtin-tools.ts
  • New FormatJson tool: reads path, parses (returns { ok: false, valid: false, error, byteDelta: 0, changed: false } on invalid JSON, leaving the file untouched — no throw), optionally sorts object keys, rewrites with canonical 2-space indentation.
  • permissionRequired: true (in-place file mutation, same as Edit); uses the existing per-path write lock + path resolution.
  • Returns diagnostic only: { ok, path, valid, bytesBefore, bytesAfter, byteDelta, changed }.
  • Reuses sortKeysDeep, which preserves __proto__ as an own data property (no prototype-pollution).
• packages/runtime/src/__tests__/builtin-tools.test.ts
  • File-based tests (real temp dirs): happy path rewrites in place, sort_keys ordering (incl. __proto__ + nested recursion), invalid JSON returns the structured error diagnostic (no write, byteDelta: 0), already-canonical content reports changed: false / zero byteDelta, unicode handling, diagnostic fields.

Verification

• npm run -w @maka/runtime typecheck — clean
• npm run -w @maka/runtime test — all pass (FormatJson block green)

Notes

Strictly path + sort_keys only (no indent param) per the agreed scope. Useful for config hygiene after a Write.