CLI AI: Add --json flag for headless NDJSON output

[wesleyfantinel]

Related issues

• Related to sandboxed/Docker deployment of Studio AI agent
• Related to Studio Code Assistant #2870 (Studio Assistant UI)

How AI was used in this PR

Claude was used to brainstorm the design, write the implementation plan, and implement the changes. All code was reviewed and validated by the author.

Proposed Changes

• Add --json flag and positional message argument to studio ai command for headless mode
• Introduce AiOutputAdapter interface with AiChatUI implementing it directly (no wrapper class)
• Add JsonAdapter that streams typed NDJSON events to stdout
• Add --auto-approve as a separate CLI flag, independent of --json (defaults to true in JSON mode, overridable with --no-auto-approve)
• In JSON mode, agent questions are emitted as question.asked events and the process exits after cleanup
• Define NDJSON event schema: message, progress, info, error, question.asked, turn.started, turn.completed
• Fix: running studio code "hello" in interactive mode now stays in the input loop after the first reply

Usage

# Single turn, streams NDJSON events to stdout
studio code  "create a theme for my site" --json

# JSON mode without auto-approving tools
studio code "update my theme" --json --no-auto-approve

# Interactive mode with initial message (stays in input loop)
studio code "hello, what can you do?"

# Validation: --json requires a message
studio code --json  # Error: --json requires an initial message argument

Files changed

File	Change
apps/cli/ai/json-events.ts (new)	NDJSON event types and emitEvent() helper
apps/cli/ai/output-adapter.ts (new)	AiOutputAdapter interface and JsonAdapter
apps/cli/ai/agent.ts	Add autoApprove field to AiAgentConfig, short-circuit canUseTool
apps/cli/ai/ui.ts	AiChatUI implements AiOutputAdapter
apps/cli/commands/ai/index.ts	Positional message, --json and --auto-approve flags, adapter pattern, single-turn path, initial message fix
apps/cli/commands/ai/sessions/resume.ts	Use AiChatUI directly instead of removed InteractiveAdapter
apps/cli/commands/ai/tests/ai.test.ts	Tests for JSON mode, auto-approve flag

Testing Instructions

1. Build the CLI: npm run cli:build
2. Run in JSON mode:

   node apps/cli/dist/cli/main.mjs code "hello, what can you do?" --json

3. Verify NDJSON events are streamed to stdout (one JSON object per line)
4. Verify turn.started is the first event and turn.completed is the last
5. Run in interactive mode with initial message and verify it stays in the input loop after the first reply:

   node apps/cli/dist/cli/main.mjs code "hello"

6. Run in interactive mode (no flags) and verify the TUI works as before:

   node apps/cli/dist/cli/main.mjs code

7. Verify --json without a message shows an error:

   node apps/cli/dist/cli/main.mjs code --json

8. Verify --no-auto-approve works with --json:

   node apps/cli/dist/cli/main.mjs code "hello" --json --no-auto-approve

9. Run tests: npm test -- apps/cli/commands/ai/tests/ai.test.ts

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?

[wpmobilebot]

📊 Performance Test Results

Comparing 52e5a81 vs trunk

app-size

Metric	trunk	52e5a81	Diff	Change
App Size (Mac)	1286.16 MB	1286.30 MB	+0.14 MB	⚪ 0.0%

site-editor

Metric	trunk	52e5a81	Diff	Change
load	1921 ms	1869 ms	52 ms	🟢 -2.7%

site-startup

Metric	trunk	52e5a81	Diff	Change
siteCreation	9142 ms	8151 ms	991 ms	🟢 -10.8%
siteStartup	4158 ms	4303 ms	+145 ms	🔴 3.5%

---

Results are median values from multiple test runs.

Legend: 🟢 Improvement (faster) | 🔴 Regression (slower) | ⚪ No change (<50ms diff)

[sejas]

Code looks good and I confirmed it works as expected. Thanks for working in the PR.
I have created a PR against this branch suggesting a couple of changes. Could you take a look? #3081

Thank you!

[sejas]

Works as expected. Thank you! I pushed a couple of changes. Let me know if you want discuss or change anything. I'll be happy to create a follow-up if necessary.

studio-json-parameter.mov