feat(cli): add JSON schema contract (v1.0.0) for --json/--json-io modes

[PeterDaveHello]

Summary

• Add explicit schema versioning and unified event types for CLI JSON output
• Improve automation integration stability with --json/--json-io modes

Schema v1.0.0 Features

Output Messages

All JSON output messages now include:

• schemaVersion: Version identifier ("1.0.0") for automation compatibility
• messageId: Unique identifier for message tracking (format: cli-{ts}-{hash} or ext-{ts}-{hash})
• event: Unified event type for semantic categorization
  • system.* - System events (welcome, error, ready, empty)
  • user.* - User events (message, approval)
  • assistant.* - Assistant events (message, reasoning, completion)
  • tool.* - Tool events (request, output)
  • api.* - API events (request_started, request_completed, request_failed)
  • task.* - Task events (resumed, completed, checkpoint)
  • context.* - Context events (condensed, truncated)
• status: Message completion status (partial | complete)

Input Messages

Supports both versioned (v1.0.0) and legacy formats:

Versioned format:

{"schemaVersion": "1.0.0", "type": "user_input", "content": "hello"}
{"schemaVersion": "1.0.0", "type": "approval"}
{"schemaVersion": "1.0.0", "type": "rejection", "content": "reason"}
{"schemaVersion": "1.0.0", "type": "abort"}
{"schemaVersion": "1.0.0", "type": "response", "response": "retry_clicked"}

Legacy format (still supported):

{"type": "askResponse", "text": "hello"}
{"type": "respondToApproval", "approved": true}
{"type": "cancelTask"}

Implementation

New Files

• packages/core-schemas/src/messages/events.ts - Event types and mapping functions
• packages/core-schemas/src/messages/output.ts - Output message schemas
• packages/core-schemas/src/messages/input.ts - Input message schemas (discriminated union)
• cli/src/ui/utils/eventMapper.ts - CLI event mapping utilities
• cli/src/ui/utils/messageId.ts - Message ID generation (streaming-stable)

Key Design Decisions

1. Backward Compatibility

   • Output: .passthrough() preserves all original fields
   • Input: Dual handler for versioned + legacy formats
   • Legacy messages log deprecation warning but work normally

2. Event Mapping Correctness

   • user_feedback → user.message (not assistant)
   • command_output ask → tool.request (not output)
   • command_output say → tool.output

3. Streaming Stability

   • messageId uses stable properties (type, ask/say, timestamp)
   • Does NOT use text content (which changes during streaming)
   • Same messageId for partial/complete updates

4. Special Response Types

   • retry_clicked - Payment/model error retry
   • objectResponse - Multi-file diff selection
   • Handled via discriminated union with required response field

Test Coverage

• ✅ 2025+ tests pass
• ✅ Event mapper tests (170 lines) - All event mappings
• ✅ Message ID tests (129 lines) - Streaming stability
• ✅ JSON output tests (updated) - v1.0.0 fields validation
• ✅ Stdin handler tests (256 lines) - Versioned + legacy formats, images, response types

Test Plan

• Type check passes
• All CLI tests pass (2025 tests)
• Build succeeds
• Backward compatibility verified (legacy format works)
• Event mappings tested (user_feedback, command_output)
• Special responses tested (retry_clicked, objectResponse)

[changeset-bot]

🦋 Changeset detected

Latest commit: 2507cfa

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@kilocode/cli	Minor
@kilocode/core-schemas	Minor
kilo-code	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 41f5b1fb09

ℹ️ 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".

[PeterDaveHello]

cc #5107 #5173 for CI issue.

[PeterDaveHello]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 2507cfa73f

ℹ️ 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".

[chatgpt-codex-connector]

Map followup asks to user.message

The new mapping returns user.approval for followup asks, but followups are clarifying questions that expect free‑form user text, not a yes/no decision. For example, AskFollowupQuestionTool calls task.ask("followup") and consumes the returned text to produce the tool result, so an automation client that uses event to decide response type will likely send an approval instead of a message, yielding an empty follow‑up answer. This misclassification can break follow‑up flows; mapping followup to user.message aligns with how the response is used.

Useful? React with 👍 / 👎.

[marius-kilocode]

Thanks @PeterDaveHello, however I tend to the opinion that we don't want to introduce versioning for the --json API at this point. We planned to use it mostly internally.

[marius-kilocode]

Closing for now, maybe we reiterate later on this.

[PeterDaveHello]

Sure, no problem.