fix(opencode): add short agent summaries for picker

[ChaoGlenXu]

Issue for this PR

Closes #4825

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

This fixes the /agent picker using the long agent description field directly.

opencode agent create currently writes a long description because that field is used for agent routing guidance. The TUI picker was also showing that same text, which makes custom agents hard to read.

This change adds an optional short summary field for agents, generates it during opencode agent create, and makes the TUI agent picker prefer summary over description. The long description is still preserved for routing behavior, while the picker gets a shorter display string.

I also regenerated the OpenAPI/SDK types because the agent schema changed.

How did you verify your code works?

I tested the agent config/runtime path locally with:

bun test test/agent/agent.test.ts

That passed with 38 tests passing.

I also verified the branch push passed the repo pre-push hook, including:

bun turbo typecheck

Screenshots / recordings

Not included. This is a small TUI text/display change and I verified it through tests and typecheck.

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

[github-actions]

Hey! Your PR title Codex/fix agent description cutoff doesn't follow conventional commit format.

Please update it to start with one of:

• feat: or feat(scope): new feature
• fix: or fix(scope): bug fix
• docs: or docs(scope): documentation changes
• chore: or chore(scope): maintenance tasks
• refactor: or refactor(scope): code refactoring
• test: or test(scope): adding or updating tests

Where scope is the package name (e.g., app, desktop, opencode).

See CONTRIBUTING.md for details.

[github-actions]

The following comment was made by an LLM, it may be inaccurate:

Based on my search results, I found two potentially related PRs that appear to address similar issues with agent display:

1. PR feat(agent): add optional title field for better display in agent lists #13839 - "feat(agent): add optional title field for better display in agent lists"

   • Related because it also addresses improving agent display in lists/pickers

2. PR feat(agent): add short description for better UI display #15809 - "feat(agent): add short description for better UI display"

   • Highly related as it adds a short description field specifically for UI display, which is very similar in concept to the summary field being added in the current PR

These PRs may have already implemented or attempted to solve the same problem (adding a shorter field for TUI display instead of using the long description). You should review these to determine if they were merged, closed, or superseded by the current PR.

[atharvau]

Code Review: Codex/fix agent description cutoff

✅ APPROVED - Good UI improvement

This PR adds an optional field to agents to fix the TUI agent picker showing overly long descriptions.

Problem Analysis ✅

• The agent picker was showing full text meant for routing guidance
• Made custom agents hard to read in the UI
• Clean separation of concerns needed between routing descriptions and UI display text

Solution Quality ✅

• Non-breaking: All changes are additive with optional fields
• Backwards compatible: Falls back to description when summary not available
• Consistent: Applied across all relevant schemas (Agent.Info, Config.AgentConfig, OpenAPI)
• Well-tested: Added comprehensive test coverage for the new field

Code Analysis

Schema Changes ✅

• Properly added to Zod schemas in agent.ts and config.ts
• Updated OpenAPI spec and regenerated SDK types
• Maintains type safety throughout

UI Logic ✅

Good fallback chain: native label → summary → description → undefined

Generation Process ✅

• Agent creation now generates both summary and description fields
• Summary gets appropriate length constraint (< 80 chars) in prompt

Security & Performance ✅

• Security: No security concerns - adds display metadata only
• Performance: Minimal impact - just additional optional string fields
• Breaking Changes: None - purely additive enhancement

Test Coverage ✅

• Added tests for summary field in agent.test.ts
• Tests verify both custom agents and summary override behavior
• All 37 agent tests passing
• Type checking passes

Minor Suggestions

1. Consider adding validation for summary length (80 char limit mentioned in generate.txt)
2. The generate.txt prompt could be clearer about summary vs description distinction

This is a well-implemented feature that improves UX without breaking existing functionality. The code follows project conventions and includes proper test coverage.

Ready to merge! 🎯

[atharvau]

Code Review: Codex/fix agent description cutoff

✅ APPROVED - Good UI improvement

This PR adds an optional summary field to agents to fix the TUI agent picker showing overly long descriptions.

Problem Analysis ✅

• The agent picker was showing full description text meant for routing guidance
• Made custom agents hard to read in the UI
• Clean separation of concerns needed between routing descriptions and UI display text

Solution Quality ✅

• Non-breaking: All changes are additive with optional fields
• Backwards compatible: Falls back to description when summary not available
• Consistent: Applied across all relevant schemas (Agent.Info, Config.AgentConfig, OpenAPI)
• Well-tested: Added comprehensive test coverage for the new field

Code Analysis

Schema Changes ✅

• Properly added to Zod schemas in agent.ts and config.ts
• Updated OpenAPI spec and regenerated SDK types
• Maintains type safety throughout

UI Logic ✅

description: item.native ? "native" : (item.summary ?? item.description)

Good fallback chain: native label → summary → description → undefined

Generation Process ✅

• Agent creation now generates both summary and description fields
• Summary gets appropriate length constraint (< 80 chars) in prompt

Security & Performance ✅

• Security: No security concerns - adds display metadata only
• Performance: Minimal impact - just additional optional string fields
• Breaking Changes: None - purely additive enhancement

Test Coverage ✅

• Added tests for summary field in agent.test.ts
• Tests verify both custom agents and summary override behavior
• All 37 agent tests passing
• Type checking passes

Minor Suggestions

1. Consider adding validation for summary length (80 char limit mentioned in generate.txt)
2. The generate.txt prompt could be clearer about summary vs description distinction

This is a well-implemented feature that improves UX without breaking existing functionality. The code follows project conventions and includes proper test coverage.

Ready to merge! 🎯

[atharvau]

Code Review Summary

Overall Assessment: APPROVED ✅

What This PR Does

Adds a new field to agent configuration that provides a shorter description for UI displays (agent pickers, lists), while keeping the existing field for routing and detailed use cases.

✅ Positives

• Well-structured change: Cleanly separates UI display text from routing logic
• Comprehensive implementation: Updates schema, config, tests, SDK types, and OpenAPI spec
• Backward compatible: Makes optional, falls back to
• Good test coverage: Adds specific tests for the new functionality
• Consistent naming: Follows existing patterns in the codebase

🔍 Analysis

• No bugs detected: Clean implementation with proper null handling
• No security issues: Schema changes are safe
• Performance neutral: No performance implications
• Style compliance: Follows codebase conventions

💡 Minor Suggestions

1. UI fallback logic: The TUI component correctly uses item.summary ?? item.description - good defensive programming
2. Test quality: The new tests properly validate both native agent overrides and custom agent configurations

Schema Changes

The changes properly extend the Agent schema in multiple places:

• Core agent definition
• Configuration schema
• SDK type generation
• OpenAPI specification

This is a solid, well-tested feature addition that enhances the user experience without breaking existing functionality.

[atharvau]

Code Review Summary

Overall Assessment: APPROVED ✅

What This PR Does

Adds a new summary field to agent configuration that provides a shorter description for UI displays (agent pickers, lists), while keeping the existing description field for routing and detailed use cases.

✅ Positives

• Well-structured change: Cleanly separates UI display text from routing logic
• Comprehensive implementation: Updates schema, config, tests, SDK types, and OpenAPI spec
• Backward compatible: Makes summary optional, falls back to description
• Good test coverage: Adds specific tests for the new functionality
• Consistent naming: Follows existing patterns in the codebase

🔍 Analysis

• No bugs detected: Clean implementation with proper null handling
• No security issues: Schema changes are safe
• Performance neutral: No performance implications
• Style compliance: Follows codebase conventions

💡 Minor Suggestions

1. UI fallback logic: The TUI component correctly uses item.summary ?? item.description - good defensive programming
2. Test quality: The new tests properly validate both native agent overrides and custom agent configurations

Schema Changes

The changes properly extend the Agent schema in multiple places:

• Core agent definition
• Configuration schema
• SDK type generation
• OpenAPI specification

This is a solid, well-tested feature addition that enhances the user experience without breaking existing functionality.

[atharvau]

Code Review

✅ Overall Assessment

This is a well-implemented enhancement that addresses a real UX issue. The code follows established patterns and includes comprehensive test coverage.

🔍 Code Analysis

Strengths:

• Schema Evolution: Properly adds the new field across all necessary layers (agent schema, config, SDK types, OpenAPI spec)
• Backward Compatibility: The field is optional everywhere, ensuring existing agents continue working
• Consistent Fallback: TUI picker properly falls back to when is unavailable:
• Test Coverage: Includes new test cases for both the summary field and fallback behavior

Suggestions for Improvement:

1. Agent Generation Logic: In , consider adding validation that the summary stays under the 80-character limit:

   "summary": "A short one-line summary (max 80 chars) for agent pickers..."
   

2. Type Safety: The schema correctly makes optional, but consider if there are places where we should encourage/validate its presence for custom agents.

🔧 Technical Details

Schema Design ⭐

• The agent schema evolution is handled correctly
• All related files (config, SDK, OpenAPI) are updated consistently
• The fallback pattern is clean

Testing ⭐

• Good test coverage for both the new field and configuration override scenarios
• Tests verify both the new field storage and the fallback behavior

📋 Minor Observations

• The "noop change to force commit" comment in one file should be removed before merge
• Consider if the 80-character limit should be enforced programmatically somewhere

✨ Verdict

APPROVE - This is a solid, well-tested improvement that enhances UX without breaking existing functionality.

[atharvau]

Code Review for PR #18749

Overall Assessment ✅

This is a well-implemented enhancement that addresses a real UX issue. The code follows established patterns and includes comprehensive test coverage.

Code Analysis 🔍

Strengths:

• Schema Evolution: Properly adds the new summary field across all necessary layers (agent schema, config, SDK types, OpenAPI spec)
• Backward Compatibility: The summary field is optional everywhere, ensuring existing agents continue working
• Consistent Fallback: TUI picker properly falls back to description when summary is unavailable
• Test Coverage: Includes new test cases for both the summary field and fallback behavior

Suggestions for Improvement:

1. Agent Generation Logic: In generate.txt, consider adding validation that the summary stays under the 80-character limit
2. Type Safety: The schema correctly makes summary optional, but consider if there are places where we should encourage/validate its presence for custom agents

Technical Details 🔧

Schema Design - Excellent

• The agent schema evolution is handled correctly
• All related files (config, SDK, OpenAPI) are updated consistently
• The fallback pattern is clean and robust

Testing - Comprehensive

• Good test coverage for both the new field and configuration override scenarios
• Tests verify both the new field storage and the fallback behavior

Minor Observations 📋

• Consider if the 80-character limit should be enforced programmatically somewhere
• All type definitions are properly updated

Verdict ✨

APPROVE - This is a solid, well-tested improvement that enhances UX without breaking existing functionality.