Skip to content

Fix MCP agent split-pane targeting, default direction, and guidance#287

Open
danshapiro wants to merge 63 commits intomainfrom
feature/mcp-agent-guidance
Open

Fix MCP agent split-pane targeting, default direction, and guidance#287
danshapiro wants to merge 63 commits intomainfrom
feature/mcp-agent-guidance

Conversation

@danshapiro
Copy link
Copy Markdown
Owner

Summary

Agents using the Freshell MCP tool were making three systematic mistakes:

  1. Opening new tabs instead of splitting panes
  2. Using terminal panes with shell commands (cat/vim/glow) instead of specialized pane types (editor/browser)
  3. Sending "ENTER" as literal text instead of using token mode

Code fix

  • Bug: split-pane with explicit target bypassed MCP-level resolution. When an agent passed a target (e.g. bare numeric index "0"), the MCP tool sent it raw to the REST API, where the server resolved it in the user's active viewport tab — not the caller's tab. Now routes through resolvePaneTarget() like all other pane-targeting actions (send-keys, capture-pane, screenshot).

Default direction change

  • Changed default split direction from horizontal to vertical in REST API, CLI, and MCP tool. Vertical is the more natural default for "open alongside" (top/bottom). CLI flag -v (vertical) replaced with -h (horizontal).

Agent instruction updates

  • Added "Choosing the right action" section to MCP INSTRUCTIONS with decision table
  • Added decision guide table to HELP_TEXT playbooks
  • Reordered playbooks to show split-pane (editor/browser) before new-tab
  • Fixed misleading "splits the active pane" → "splits your own pane"
  • Added literal mode + ENTER guidance
  • Updated SKILL.md to mirror all guidance

Test plan

  • Unit tests pass (2332 server + 28 CLI + 138 panesSlice)
  • MCP tool tests pass (99/99)
  • Manual: spawn an agent and verify it uses split-pane with editor: param for file opens
  • Manual: verify default direction is vertical in UI

Dan Shapiro added 30 commits April 2, 2026 22:11
Dan Shapiro added 29 commits April 3, 2026 17:08
# Conflicts:
#	src/components/TabsView.tsx
#	test/unit/client/components/TabsView.test.tsx
…ting

Code fixes:
- Fix split-pane with explicit target: route through resolvePaneTarget()
  (consistent with send-keys, capture-pane, etc.) so bare numeric
  indices resolve in the caller's tab, not the user's active viewport
- Change default split direction from horizontal to vertical (REST API,
  CLI flag -v -> -h)

Instruction updates:
- Add decision guide table to HELP_TEXT (split-pane vs new-tab, editor
  vs terminal+cat, browser vs terminal+curl)
- Add 'Choosing the right action' section to MCP INSTRUCTIONS covering
  tabs-vs-panes, specialized pane types, literal mode, and targeting
- Reorder playbooks to show split-pane before new-tab
- Fix split-pane description from 'active pane' to 'your own pane'
- Update SKILL.md with matching guidance and new -h flag
Copy link
Copy Markdown

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 525caf7b03

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

Comment on lines 182 to 186
if (msg.code === 'INVALID_SESSION_ID') {
// Session is gone on the server (e.g. server restarted). Mark it as lost
// so AgentChatView can detect this and trigger immediate recovery instead
// of waiting for the 5-second timeout.
// so AgentChatView can detect this and trigger immediate recovery.
dispatch(markSessionLost({ sessionId: msg.sessionId as string }))
} else {
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Treat RESTORE_NOT_FOUND as recoverable lost session

sdk.attach now emits sdk.error with code: "RESTORE_NOT_FOUND" when a persisted session cannot be restored (server/ws-handler.ts), but this branch only marks sessions lost for INVALID_SESSION_ID. In the reload/stale-session path, that leaves historyLoaded false and only records lastError, so AgentChatView remains stuck in “Restoring session...” with input disabled instead of recreating the session. Please classify restore-not-found restore errors as recoverable (or trigger equivalent recovery) so users are not trapped after restart/history cleanup.

Useful? React with 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant