🧾 fix: normalize PTC JSON-string inputs

[danny-avila]

Summary

I fixed programmatic tool execution so bridge/runtime input shapes are normalized according to the target tool schema before LangChain validates the call.

• Parse JSON-object strings only when the target tool advertises an object-only schema.
• Preserve literal JSON-looking strings for string-shaped and mixed object-or-string tools.
• Stringify object input back to JSON text only for string-only tools when a bridge has already parsed a JSON-looking string.
• Preserve object input unchanged for mixed object-or-string schemas.
• Widen PTCToolCall.input to reflect that bridge callers can provide either object input or serialized JSON text.
• Add regression coverage for object-schema JSON strings, string-schema JSON-looking strings, string-schema object input, and mixed object-or-string schemas in both directions.
• Root cause: LangChain validates tool input before _call; when executeTools() passed a JSON string directly into a tool with a z.object(...) schema, validation failed with Received tool input did not match expected schema before the MCP tool or _ptc layer ran.

Change Type

• Bug fix (non-breaking change which fixes an issue)

Testing

npm test -- --runTestsByPath /Users/danny/Projects/agents/src/tools/__tests__/ProgrammaticToolCalling.test.ts --runInBand --testPathIgnorePatterns='/.claude/'

# Local CodeAPI / OrbStack validation
curl -sS http://localhost:3112/v1/health
# OK

# Recreated sandbox-runner from the real codeapi checkout after finding a stale bind mount.
docker compose -p codeapi -f docker-compose.yaml -f docker-compose.mac.yml up -d

# Verified /exec works and both Bash/Python PTC wrapper paths complete through localhost:3112/v1
# with a Zod object-schema mock ClickHouse tool.
# Verified Bash PTC with a Zod string-schema mock tool preserves a JSON-looking string as string input.

Test Configuration:

• Repo: /Users/danny/Projects/agents
• CodeAPI checkout: /Users/danny/Projects/clickhouse-ai/services/codeapi
• CodeAPI endpoint: http://localhost:3112/v1
• Branch: danny-avila/fix-ptc-json-string-input
• Node test runner: project npm test script

Checklist

• My code adheres to this project's style guidelines
• I have performed a self-review of my own code
• My changes do not introduce new warnings
• I have written tests demonstrating that my changes are effective or that my feature works
• Local unit tests pass with my changes

[danny-avila]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8aea45027e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[danny-avila]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e508a248ff

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[danny-avila]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Keep them coming!

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".