Improve error messages for agent-friendly recovery and help guidance

[bigdra50]

概要

コーディングエージェントがエラーメッセージから適切に次のアクションを決定できるよう、エラーメッセージの改善を行う。

現状の分析で以下の課題を特定した。

課題

1. リカバリ手順の欠如

エラーメッセージに「次に何をすべきか」が含まれていない箇所がある。

レイヤー	エラー箇所	現状メッセージ	不足情報
Unity	Playmode.cs pause/unpause/step	Cannot pause: not in play mode	Play Mode に入るコマンドの示唆
Relay	INSTANCE_NOT_FOUND	Instance not found: {id}	接続中インスタンス一覧の確認方法
Relay	AMBIGUOUS_INSTANCE	Ambiguous instance 'X': matches A, B	--instance での絞り込み方法
Relay	インスタンス0台	Instance not found after waiting...	Unity 側の接続確認手順

※ 良い例（既存）: ConnectionError → Please ensure the relay server is running: $ python -m relay.server --port 6500
※ 良い例（既存）: Tests.cs → Cannot start tests while Editor is in Play Mode. Stop Play Mode first.
※ 良い例（#29）: Screenshot.cs → GameView screenshot requires Play Mode. Enter Play Mode first with 'manage_editor play' command.

2. Valid values 列挙の不統一

Playmode.cs の HandleCommand だけ Valid actions: が欠落している。

// 現状 (Playmode.cs)
$"Unknown action: {action}"

// 他の全ツール
$"Unknown action: {action}. Valid actions: enter, exit, pause, unpause, step, state"

3. CLI オプション不足時の help 誘導

CLI 側でオプション不足時のメッセージに --help への誘導がない。

# 現状
Error: --name or --id required

# 改善案
Error: --name or --id required. Run 'u gameobject find --help' for usage.

対象箇所（app.py 内の print_error + raise typer.Exit(1)）:

• gameobject find/modify/active/delete: --name or --id required
• component list/inspect/add/modify/remove: --target or --target-id required
• asset prefab: --source or --source-id required
• scene load: --path or --name required
• uitree inspect: ref argument or --panel + --name required

4. instance 指定ミスの防止

シナリオ	現状	改善案
--instance でパス間違い	Instance not found: {id}	接続中インスタンス一覧を表示
複数インスタンス一致	Ambiguous instance 'X': matches A, B	u instances または --instance <full-path> を示唆
インスタンス0台	Instance not found after waiting...	Ensure Unity Editor has UnityBridge connected. Check with 'u instances'.

5. 必須パラメータメッセージの不統一（低優先度）

Unity 側でフォーマットに揺れがある:

• 'path' is required
• 'type' parameter is required
• 'name' parameter is required for create action
• Either 'target' (name) or 'targetId' (instanceID) is required

統一フォーマットの検討: '{param}' is required または Either '{a}' or '{b}' is required

対象ファイル

• UnityBridge/Editor/Tools/Playmode.cs — Valid actions 追加、リカバリ手順追加
• relay/server.py — INSTANCE_NOT_FOUND / AMBIGUOUS_INSTANCE メッセージ改善
• relay/instance_registry.py — AmbiguousInstanceError メッセージ改善
• unity_cli/cli/app.py — help 誘導の追加、instance エラー時のガイダンス

優先度

1. リカバリ手順の追加（エージェントへの影響大）
2. instance 指定ミス防止
3. help 誘導
4. Valid values 統一
5. メッセージフォーマット統一

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

✅ Successfully generated implementation plan.

💡 Use @coderabbitai <feedback> to replan

Examples

• Example 1
• Example 2

---

⚠️ Possible Duplicate Issue

• GameView screenshot should return error when not in Play Mode #29

🔗 Related PRs

#30 - GameViewスクリーンショットにPlay Modeチェックを追加 [closed]

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

Coding Plan

Approach

Improve error messages across the Unity Bridge system to help coding agents determine appropriate recovery actions. Changes span Unity C# tools, relay server instance errors, and CLI parameter validation to add recovery guidance, disambiguation hints, and --help references.

Observations

The Unity Bridge system has three layers: Unity Editor tools (C# in UnityBridge/Editor/Tools/), a relay server (Python in relay/), and a CLI client (Python in unity_cli/). Error communication uses a standardized protocol with error codes like INSTANCE_NOT_FOUND and AMBIGUOUS_INSTANCE. The codebase already has good patterns for recovery-oriented error messages (ConnectionError, Tests.cs, Screenshot.cs) that should be extended to other components.

Assumptions

Assumption 1: Instance list inclusion in INSTANCE_NOT_FOUND errors

Options Considered:

1. Include full instance list in error message (project_name + instance_id for each)
2. Only suggest running u instances command without listing instances

Chosen Option: 2

Rationale: Suggest u instances command rather than embedding list in error. This keeps error messages concise, avoids protocol bloat for projects with many instances, and provides a consistent actionable command the agent can run.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Unity Playmode.cs Error Improvements

Enhance Playmode.cs to follow established patterns from other Unity tools by adding valid actions enumeration and recovery guidance for play mode state errors.

Task 1: Add Valid Actions List to Unknown Action Error

Add the list of valid actions to the unknown action error message to match the pattern used by all other Unity tools.

• Update UnityBridge/Editor/Tools/Playmode.cs HandleCommand switch default case (around line 27-30)
• Change error from $"Unknown action: {action}" to $"Unknown action: {action}. Valid actions: enter, exit, pause, unpause, step, state"
• Follow the exact format used in Asset.cs, Build.cs, Component.cs and other tools

Task 2: Add Recovery Guidance to Pause/Unpause/Step Errors

Add actionable recovery instructions to the play mode state validation errors, following the Screenshot.cs pattern of referencing specific commands.

• Update pause error (around line 82-88): Change message to "Cannot pause: not in play mode. Enter play mode first with action 'enter'."
• Update unpause error (around line 98-105): Change message to "Cannot unpause: not in play mode. Enter play mode first with action 'enter'."
• Update step error (around line 115-122): Change message to "Cannot step: not in play mode. Enter play mode first with action 'enter'."

🤖 Prompt for AI agents

Improve error messages in Playmode.cs to provide recovery guidance and valid
action lists following established patterns from other Unity tools.

**Unknown Action Error (HandleCommand switch default case around line 27-30):**
- Update the error message to include the list of all valid actions
- Change from `$"Unknown action: {action}"` to `$"Unknown action: {action}.
Valid actions: enter, exit, pause, unpause, step, state"`
- Match the format used in Asset.cs, Build.cs, Component.cs and other tools

**Play Mode State Validation Errors:**
- Update pause error (around line 82-88): Change message to `"Cannot pause: not
in play mode. Enter play mode first with action 'enter'."`
- Update unpause error (around line 98-105): Change message to `"Cannot unpause:
not in play mode. Enter play mode first with action 'enter'."`
- Update step error (around line 115-122): Change message to `"Cannot step: not
in play mode. Enter play mode first with action 'enter'."`
- Follow the Screenshot.cs pattern of referencing specific commands for recovery

Phase 2: Relay Server Instance Error Improvements

Enhance instance-related error messages in the relay layer to provide disambiguation guidance and connection troubleshooting steps.

Task 1: Improve AmbiguousInstanceError Message

Update the AmbiguousInstanceError exception to include guidance on how to disambiguate using full instance path.

• Modify relay/instance_registry.py AmbiguousInstanceError.init (lines 25-32)
• Append disambiguation guidance to the exception message
• New format: "Ambiguous instance '{query}': matches {names}. Use --instance with the full path to specify."
• Keep existing query and candidates attributes for programmatic access

Task 2: Improve INSTANCE_NOT_FOUND Error Messages

Update instance not found errors in relay server to include actionable recovery guidance based on the specific failure scenario.

• Update relay/server.py at all INSTANCE_NOT_FOUND locations (around lines 394-398, 461-466, 502-507)
• For specific instance not found (user specified an instance): Add "Check available instances with 'u instances'."
• For no instances after waiting (0 instances case): Add "Ensure Unity Editor has UnityBridge connected. Check with 'u instances'."
• Messages should follow the multi-line pattern from ConnectionError for complex guidance

🤖 Prompt for AI agents

Improve instance-related error messages in the relay server to provide
actionable recovery guidance.

**AmbiguousInstanceError in relay/instance_registry.py (lines 25-32):**
- Update the exception message in AmbiguousInstanceError.__init__
- Change format to: `"Ambiguous instance '{query}': matches {names}. Use
--instance with the full path to specify."`
- Keep existing `query` and `candidates` attributes unchanged for programmatic
access

**INSTANCE_NOT_FOUND Errors in relay/server.py (around lines 394-398, 461-466,
502-507):**
- For specific instance not found (when user specified an instance): Append
`"Check available instances with 'u instances'."`
- For no instances after waiting (0 instances case): Append `"Ensure Unity
Editor has UnityBridge connected. Check with 'u instances'."`
- Follow the multi-line pattern from ConnectionError for complex guidance
- Update all INSTANCE_NOT_FOUND error locations with context-appropriate
messages

Phase 3: CLI Help Guidance Improvements

Add --help command references to all required parameter validation errors in the CLI to guide users to proper usage documentation.

Task 1: Update Scene Command Errors

Add --help guidance to scene command parameter errors.

• Update unity_cli/cli/app.py scene load error (around line 495)
• Change from "--path or --name required" to "--path or --name required. Run 'u scene load --help' for usage."

Task 2: Update GameObject Command Errors

Add --help guidance to all gameobject command parameter errors.

• Update unity_cli/cli/app.py gameobject find error (around line 690): Add ". Run 'u gameobject find --help' for usage."
• Update gameobject modify error (around line 765): Add ". Run 'u gameobject modify --help' for usage."
• Update gameobject active error (around line 796): Add ". Run 'u gameobject active --help' for usage."
• Update gameobject delete error (around line 824): Add ". Run 'u gameobject delete --help' for usage."

Task 3: Update Component Command Errors

Add --help guidance to all component command parameter errors.

• Update unity_cli/cli/app.py component list error (around line 853): Add ". Run 'u component list --help' for usage."
• Update component inspect error (around line 880): Add ". Run 'u component inspect --help' for usage."
• Update component add error (around line 906): Add ". Run 'u component add --help' for usage."
• Update component modify error (around line 949): Add ". Run 'u component modify --help' for usage."
• Update component remove error (around line 982): Add ". Run 'u component remove --help' for usage."

Task 4: Update Asset Command Errors

Add --help guidance to asset command parameter errors.

• Update unity_cli/cli/app.py asset prefab error (around line 1094)
• Change from "--source or --source-id required" to "--source or --source-id required. Run 'u asset prefab --help' for usage."

Task 5: Update UITree Command Errors

Add --help guidance to all uitree command parameter errors.

• Update unity_cli/cli/app.py uitree inspect error (around line 1742): Add ". Run 'u uitree inspect --help' for usage."
• Update uitree click error (around line 1878): Add ". Run 'u uitree click --help' for usage."
• Update uitree scroll ref error (around line 1953): Add ". Run 'u uitree scroll --help' for usage."
• Update uitree scroll direction error (around line 1957): Add ". Run 'u uitree scroll --help' for usage."
• Update uitree text error (around line 2011): Add ". Run 'u uitree text --help' for usage."

🤖 Prompt for AI agents

Add --help command references to all required parameter validation errors in
unity_cli/cli/app.py to guide users to proper usage documentation.

**Scene Command Errors:**
- Update scene load error (around line 495)
- Change from `"--path or --name required"` to `"--path or --name required. Run
'u scene load --help' for usage."`

**GameObject Command Errors (around lines 690, 765, 796, 824):**
- gameobject find error: Append `". Run 'u gameobject find --help' for usage."`
- gameobject modify error: Append `". Run 'u gameobject modify --help' for
usage."`
- gameobject active error: Append `". Run 'u gameobject active --help' for
usage."`
- gameobject delete error: Append `". Run 'u gameobject delete --help' for
usage."`

**Component Command Errors (around lines 853, 880, 906, 949, 982):**
- component list error: Append `". Run 'u component list --help' for usage."`
- component inspect error: Append `". Run 'u component inspect --help' for
usage."`
- component add error: Append `". Run 'u component add --help' for usage."`
- component modify error: Append `". Run 'u component modify --help' for
usage."`
- component remove error: Append `". Run 'u component remove --help' for
usage."`

**Asset Command Errors:**
- Update asset prefab error (around line 1094)
- Change from `"--source or --source-id required"` to `"--source or --source-id
required. Run 'u asset prefab --help' for usage."`

**UITree Command Errors (around lines 1742, 1878, 1953, 1957, 2011):**
- uitree inspect error: Append `". Run 'u uitree inspect --help' for usage."`
- uitree click error: Append `". Run 'u uitree click --help' for usage."`
- uitree scroll ref error: Append `". Run 'u uitree scroll --help' for usage."`
- uitree scroll direction error: Append `". Run 'u uitree scroll --help' for
usage."`
- uitree text error: Append `". Run 'u uitree text --help' for usage."`

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Improve error messages in Playmode.cs to provide recovery guidance and valid
action lists following established patterns from other Unity tools.

**Unknown Action Error (HandleCommand switch default case around line 27-30):**
- Update the error message to include the list of all valid actions
- Change from `$"Unknown action: {action}"` to `$"Unknown action: {action}.
Valid actions: enter, exit, pause, unpause, step, state"`
- Match the format used in Asset.cs, Build.cs, Component.cs and other tools

**Play Mode State Validation Errors:**
- Update pause error (around line 82-88): Change message to `"Cannot pause: not
in play mode. Enter play mode first with action 'enter'."`
- Update unpause error (around line 98-105): Change message to `"Cannot unpause:
not in play mode. Enter play mode first with action 'enter'."`
- Update step error (around line 115-122): Change message to `"Cannot step: not
in play mode. Enter play mode first with action 'enter'."`
- Follow the Screenshot.cs pattern of referencing specific commands for recovery
===============================================================================

Task: 2

Improve instance-related error messages in the relay server to provide
actionable recovery guidance.

**AmbiguousInstanceError in relay/instance_registry.py (lines 25-32):**
- Update the exception message in AmbiguousInstanceError.__init__
- Change format to: `"Ambiguous instance '{query}': matches {names}. Use
--instance with the full path to specify."`
- Keep existing `query` and `candidates` attributes unchanged for programmatic
access

**INSTANCE_NOT_FOUND Errors in relay/server.py (around lines 394-398, 461-466,
502-507):**
- For specific instance not found (when user specified an instance): Append
`"Check available instances with 'u instances'."`
- For no instances after waiting (0 instances case): Append `"Ensure Unity
Editor has UnityBridge connected. Check with 'u instances'."`
- Follow the multi-line pattern from ConnectionError for complex guidance
- Update all INSTANCE_NOT_FOUND error locations with context-appropriate
messages
===============================================================================

Task: 3

Add --help command references to all required parameter validation errors in
unity_cli/cli/app.py to guide users to proper usage documentation.

**Scene Command Errors:**
- Update scene load error (around line 495)
- Change from `"--path or --name required"` to `"--path or --name required. Run
'u scene load --help' for usage."`

**GameObject Command Errors (around lines 690, 765, 796, 824):**
- gameobject find error: Append `". Run 'u gameobject find --help' for usage."`
- gameobject modify error: Append `". Run 'u gameobject modify --help' for
usage."`
- gameobject active error: Append `". Run 'u gameobject active --help' for
usage."`
- gameobject delete error: Append `". Run 'u gameobject delete --help' for
usage."`

**Component Command Errors (around lines 853, 880, 906, 949, 982):**
- component list error: Append `". Run 'u component list --help' for usage."`
- component inspect error: Append `". Run 'u component inspect --help' for
usage."`
- component add error: Append `". Run 'u component add --help' for usage."`
- component modify error: Append `". Run 'u component modify --help' for
usage."`
- component remove error: Append `". Run 'u component remove --help' for
usage."`

**Asset Command Errors:**
- Update asset prefab error (around line 1094)
- Change from `"--source or --source-id required"` to `"--source or --source-id
required. Run 'u asset prefab --help' for usage."`

**UITree Command Errors (around lines 1742, 1878, 1953, 1957, 2011):**
- uitree inspect error: Append `". Run 'u uitree inspect --help' for usage."`
- uitree click error: Append `". Run 'u uitree click --help' for usage."`
- uitree scroll ref error: Append `". Run 'u uitree scroll --help' for usage."`
- uitree scroll direction error: Append `". Run 'u uitree scroll --help' for
usage."`
- uitree text error: Append `". Run 'u uitree text --help' for usage."`

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[bigdra50]

追加調査: 事前調査からの漏れ

詳細調査の結果、Issue 本文に記載されていない追加の改善対象箇所を特定した。

A. Unity Tools 層の追加対象

ファイル	行	現状	問題
Tests.cs	58-60	Unknown action: {action}	Valid actions 列挙なし（Playmode.cs と同じ問題）
Screenshot.cs	68	manage_editor play command	CLI コマンド名が不正確。正しくは u play または action 'enter'
Console.cs	25-29	JObject でエラー返却	ProtocolException を使わないパターン不整合
MenuItem.cs	27-29, 39, 81, 104, 153, 189, 204, 234	同上	ProtocolException を使わない箇所が 8 箇所

B. Relay 層の追加対象 (INSTANCE_NOT_FOUND 以外)

server.py 行	エラーコード	現状メッセージ	不足
520	INSTANCE_RELOADING	Instance still reloading after {ms}ms	再試行すべきか u state で確認すべきかの誘導なし
568	INSTANCE_BUSY	Instance is busy: {id}	再試行 or --timeout 増加の誘導なし
554	TIMEOUT (queued)	Queued command timed out after {ms}ms	同上
608	TIMEOUT	Command timed out after {ms}ms	同上
561	QUEUE_FULL	Command queue is full (max: {size})	待機すべき旨の誘導なし

C. CLI 層の追加対象

app.py 行	コマンド	メッセージ	備考
689-691	gameobject find	--name or --id required	Issue 本文のリストから漏れ
1956-1958	uitree scroll	--x/--y or --to parameter required	同上
1882-1883	uitree click	--button must be 0 (left), 1 (right), or 2 (middle)	バリデーションエラーに --help 誘導なし
1886-1887	uitree click	--count must be a positive integer (>= 1)	同上

優先度についての所感

• Screenshot.cs の manage_editor play は GameViewスクリーンショットにPlay Modeチェックを追加 #30 で追加された直後のメッセージなので早めに修正したい
• Tests.cs の Valid actions 欠如は Playmode.cs と同じ対応で済む
• Console.cs / MenuItem.cs の JObject パターン不整合はスコープが大きいため、別 Issue で扱う方が適切かもしれない
• Relay 層の RELOADING/BUSY/TIMEOUT/QUEUE_FULL は CLI 側の自動リトライと組み合わせると、エージェントが手動リトライすべきか判断できる情報が不足している