[SDK] Schema handling with universal file-write strategy for .harness()

[santoshkumarradha]

Overview

Implement the schema handling module that converts developer schemas (Pydantic/Zod) into prompt suffixes, manages temp file lifecycle, performs cosmetic JSON repair, and validates output against the schema. Uses universal file-write strategy (no native --json-schema flags).

Branch: feat/harness-v2
Design doc: docs/design/harness-v2-design.md (Section 5)

Scope

Python (sdk/python/agentfield/harness/)

• _schema.py:
  • build_prompt_suffix(schema, cwd) → appends OUTPUT REQUIREMENTS block
  • get_output_path(cwd) → returns {cwd}/.agentfield_output.json
  • get_schema_path(cwd) → returns {cwd}/.agentfield_schema.json
  • write_schema_file(schema, cwd) → for large schemas (>4K tokens), write to file
  • cosmetic_repair(raw_json: str) → strip markdown fences, trailing commas, fix truncated brackets
  • parse_and_validate(file_path, schema) → read file, parse JSON, validate against Pydantic model
  • cleanup_temp_files(cwd) → delete output + schema files
• Tests: prompt suffix generation, cosmetic repair (markdown fences, trailing commas, truncated JSON), validation success/failure, large schema file-write, cleanup

TypeScript (sdk/typescript/src/harness/)

• schema.ts:
  • Same functions adapted for Zod schemas
  • Uses zod-to-json-schema for schema conversion
• Tests: mirror Python test coverage

Key Design Decisions

• Output file: {cwd}/.agentfield_output.json (deterministic, dotfile, in cwd not /tmp)
• Prompt suffix at END of user prompt (recency bias)
• Large schemas (>4K tokens): write schema to .agentfield_schema.json, instruct agent to read it
• Cosmetic repair handles: markdown fences, trailing commas, truncated closing brackets

Acceptance Criteria

• Prompt suffix correctly formatted with schema JSON
• Cosmetic repair handles all documented failure modes
• Parse+validate returns typed instance on success, None on failure
• Temp files cleaned up after use
• All tests pass

Dependencies

• Depends on: [SDK] Core types & provider interface for .harness() #199 (types)
• Blocks: [SDK] HarnessRunner with retry & schema orchestration for .harness() #201

[github-actions]

Thanks for picking this up, @santoshkumarradha! 🎉

Here's what to expect:

• We'll check in after 7 days if we haven't heard an update
• After 14 days, we'll send a second reminder
• After 21 days without activity, we'll unassign to let others contribute

Tips for success:

• Drop a comment when you start working on it
• Share any blockers - we're here to help!
• Link your PR with Fixes #200 in the description

Happy coding! 🚀