---
name: mesh_terminal_control
emoji: "🖥️"
description: Execute stateful shell commands and manage terminal sessions across the
  agent mesh (Swarm Control).
skill_type: remote_grpc
is_enabled: true
features:
- swarm_control
- agent_harness
config:
  service: TerminalService
  method: Execute
  capabilities:
  - shell
  - pty
  - interactive
  parameters:
    type: object
    properties:
      command:
        type: string
        description: 'Command to run. Use !RAW: prefix for REPL inputs.'
      node_id:
        type: string
        description: "Target node ID. Use 'hub' or 'server' for local server commands, but CRITICAL WARNING: NEVER use shell commands (rm, mkdir) to manipulate synchronized workspace files here; you MUST use mesh_file_explorer instead to avoid breaking the sync engine!"
      node_ids:
        type: array
        items:
          type: string
        description: List of node IDs for parallel swarm execution.
      timeout:
        type: integer
        description: Max seconds to wait. Default 120.
      no_abort:
        type: boolean
        description: 'Internal use: If true, don''t kill on timeout.'
      session_id:
        type: string
        description: Optional persistent session ID.
    required:
    - command
is_system: true
---

# Mesh Terminal Control

This capability enables the orchestrator to manage stateful terminal sessions and execute shell commands across the agent mesh (Swarm Control). It supports persistent REPLs, parallel swarm execution, and asynchronous task management.

> [!CAUTION]
> **CRITICAL: HUB FILE OPERATIONS**
> When `node_id` is set to **'hub'** or **'server'**, commands execute directly on the Hub's host OS.
> - **NEVER** use native shell commands (`rm`, `mkdir`, `cp`, `mv`) to modify files within the synchronized Ghost Mirror workspace (`/tmp/cortex-sync/{session_id}/`).
> - **REQUIRED**: You **MUST** use the `mesh_file_explorer` skill for all synchronized file operations.
> - **RATIONALE**: Direct shell modifications bypass the mesh synchronization engine, causing file drift and reconciliation conflicts.

# AI Instructions & Operational Guidelines

You are the **High-Level Mesh Orchestrator**. Adhere to these principles for professional and efficient terminal management:

### 1. Swarm & Parallel Execution
- **Parallel Sweeps**: Utilize the `node_ids` (plural) array to execute commands across multiple nodes simultaneously.
- **Immediate Feedback**: Calls return immediately upon task completion. Optimize your planning by setting realistic timeouts.

### 2. Lifespan & Background Tasking
- **Asynchronous Polling**: For long-running or background tasks, set `no_abort=True`. 
- **Handling Timeouts**: If a command returns `TIMEOUT_PENDING`, use `mesh_wait_tasks` with `timeout=0` to peek at progress without blocking your execution turn.
- **Swarm Flow**: Start background services (e.g., a background worker or server daemon) with `no_abort=True` and a short timeout (e.g., `2s`) to move to the next task without blocking.

### 3. Interactive Sessions & REPLs
- **Stateful Persistence**: Use `session_id` to maintain context across multiple calls.
- **REPL Input**: Subsequent inputs to an active REPL MUST be prefixed with `!RAW:`.

### 4. Security & Privilege Management
Always check the **'Privilege Level'** in the mesh context before execution:
- **`root`**: Execute commands directly. No `sudo` prefix is available or necessary.
- **`standard user (passwordless sudo)`**: Prepend `sudo` to all privileged operations.
- **`standard user (no sudo)`**: Avoid privileged operations; if absolutely necessary, request user intervention.

### 5. Standard Interaction Patterns
- **Background Service Orchestration**:
  - **Host Setup**: Start background services/daemons with `no_abort=True` and a short timeout to return control quickly.
  - **Client Connectivity**: Use standard networking tools or custom binaries to connect to established background services on other nodes using mesh context IPs.
- **System Monitoring**: Use non-interactive flags (e.g., `top -n 1`, `df -h`) for status snapshots. For real-time monitoring, use background tasks with intermittent polling.